案例分析一：Coding Agent 从 CLI 迁移到 Web 页面，API 怎么设计才不会推翻原来的 Engine？

这个案例本质上在回答一个很实际的问题：原来 CLI 跑得好好的能力，怎么接进 Web，而又不把底层 Engine 搞乱。光靠文字说有时候不够直观，先看一张“错误做法 vs 正确方案”的对比图。

左边那两种写法，很多人第一次做 Web 接入时都容易下意识走过去：要么让前端直接碰本地脚本，要么把一堆主逻辑硬塞进 Route。短期看像是省事了，长期看会立刻遇到超时、强耦合、难扩展这些问题。右边这套更合理：前端提交任务，Route 只负责接入和转发，Service 管调度和状态，Engine 保留原来的执行能力。这样迁过去，既保住了原来的 Engine，也给 Web 场景留足了扩展空间。

场景背景

原来 CLI：

answer = agent.run(
    "检查这个 Python 项目"
)

用户只能在服务器终端里使用。

现在要做 Web 页面。

前端输入：

检查这个 Python 项目

点击：

运行

不合理做法

为了快，直接把原来 agent.run() 的所有内部逻辑复制进 Flask Route。

于是：

CLI 一份 Agent
Web 一份 Agent

过几个月，两份逻辑逐渐不一致。

正确方案

保持：

AgentEngine

只有一份。

新增：

AgentService

然后 Web 调：

POST /api/v1/chat

最终：

CLI --------→ AgentEngine
Web → Flask → AgentService → AgentEngine

结果

Web 和 CLI 看到的是同一套：

Tool Registry
Prompt
Memory
Error Recovery

不会因为入口不同而行为漂移。

迁移复盘

真正需要变化的是：

输入输出协议

不是：

Agent 核心逻辑

这也是为什么前一节反复强调 Service / Engine 分层。