AI 编程助手架构拆解：以 WCode 为例

2026-09-27T00:00:00.000Z · #AI #Agent #编程助手 #WCode #架构

AI 编程助手架构拆解：以 WCode 为例

前面几篇讲的是“通用原理”。这一篇落地——以我自己做的桌面 AI 编程助手 WCode 为例，看一个真实 Agent 产品是怎么搭起来的。

一、为什么需要编程助手 Agent

IDE 里的代码补全只是“写下一行”。而真正的开发是多步任务：读代码→定位 bug→改文件→跑测试→看报错→再改。这需要 Agent：能读能写能执行，还要有规划。

二、分层架构

WCode 刻意做了端口隔离，避免“逻辑”和“副作用”缠在一起：

   ┌─────────────┐  ┌─────────────┐  ┌──────────┐
   │   CLI(TUI)  │  │  Desktop    │  │  Shared  │
   │             │  │ (Electron)  │  │ (reducer)│
   └──────┬──────┘  └──────┬──────┘  └────┬─────┘
          │                │              │
          └───────┬────────┴──────────────┘
                  ▼
            ┌──────────┐    依赖倒置    ┌──────────────┐
            │   Core   │ ◀──────────── │   Adapters   │
            │ 纯逻辑   │  定义端口接口  │ fs/exec/model│
            └──────────┘               └──────────────┘
  • core：纯逻辑、零 DOM、零 IO，定义“端口（Port）“接口（如 FileSystem、Exec、Model）。
  • adapters：端口的真实实现（读文件、跑 shell、调大模型）。
  • cli / desktop / shared：交互层，可替换。

好处：核心逻辑可单测、可在 CLI 和桌面版共用，换模型/换平台只改 adapter。

三、Agent Loop + 计划模式

WCode 的主循环就是前面讲的 Agent Loop。但加了一道关键闸——计划模式：

   用户需求 → 设计阶段(只出方案,不动代码)
        │
        ▼
   是否需要确认？ ──是──▶ 暂停,等用户 approve
        │否
        ▼
   开发 → 自测(编译/测试) → 完成

“先给方案、用户 review 后再改文件”——既尊重人的掌控感，也避免 Agent 自作主张乱改代码。这正是我把“不可逆动作需人类确认”原则产品化的例子。

四、工具集

WCode 暴露给模型的工具：

工具 作用 安全约束
read_file 读文件 限定工作目录
write_file 写文件 备份 + 确认
run_command 执行命令 白名单、超时
model 调大模型 必须支持 function calling

硬约束：模型必须支持 tools/function calling，否则 Agent 退化成纯聊天。WCode 默认接腾讯混元 hy3（实测 tools ✅）。

五、Token 压缩

长会话里历史对话会无限增长。WCode 做了历史摘要压缩：把早期轮次提炼成几条摘要，既保留上下文又控制成本与延迟。这也是长上下文那篇讲过的“压缩历史”的工程落地。

六、一个真实踩坑

接混元时曾排查半天 401，最后发现端点必须与 Key 同源：tokenhub 的 key 在老 api.hunyuan.cloud.tencent.com 端点永远 401，两者 key 不通用。排障第一步永远是 curl 用同源端点直接验证。这条已写进项目记忆，下次不再踩。

WCode 的设计哲学就一句：最小必要改动 + 人类在环 + 端口隔离。原理不新，难在把每一条工程纪律都落到产品里。

下一篇聊安全——LLM 的软肋与防御。

← 返回首页