我们的 Coding Agent 实战技术栈与系统架构
最后更新：2026-09-01
上一篇：Coding Agent 通用原理 讲的是"任意一个 Agent 内部怎么转"；本篇只回答一个工程问题：我们团队实际落地的这套系统，每一层到底用的是什么、为什么这么选、数据怎么流。 配置细节见 接入指南，日常怎么用见 标准工作流 SOP。
如果说原理篇是"发动机原理"，这一篇就是"我们这辆车的整车配置单"。
一、一张图看懂我们的系统
整张图分四层，记住这四个词就抓住了全部：
| 层 | 是什么 | 我们的选择 |
|---|---|---|
| 模型层（云端） | 负责推理的大脑 | 火山方舟 Coding-Plan 套餐，模型别名 ark-code-latest |
| 客户端层（本地） | 负责动手的手 | Cline / Roo-Code / OpenCode / Claude Code 四选一或组合 |
| 编排记忆层（本地） | 让 Agent 懂项目、会用工具 | CLAUDE.md 规则 + MCP 总线 + CodeGraph 图谱 + 子 Agent/Skill |
| 权限安全层（本地） | 防止 Agent 闯祸 | 人工审批 + git 快照兜底 |
关键边界：只有"推理"在云端，读文件、改代码、跑命令全在本地。云端的 Coding-Plan 看不见你的磁盘，本地客户端才是真正动手的那只手。
二、模型层：为什么用火山方舟 Coding-Plan
模型层是整套系统里唯一在云端的部分。我们统一用火山方舟的 Coding-Plan 代码大模型订阅套餐。
| 决策点 | 我们的选择 | 理由 |
|---|---|---|
| 推理服务 | 火山方舟 Coding-Plan | 套餐内固定额度，不按 token 单独计费，适合 Agent 一个任务发几十轮请求的高频循环 |
| 模型名 | 别名 ark-code-latest | 网关自动路由到当前最优代码模型（底层 doubao-seed-code 等），升级模型不用改配置 |
| 接入协议 | OpenAI 兼容 /api/coding/v3 + Anthropic 兼容 /api/coding | 一套套餐同时喂饱 VSCode 系客户端和 Claude Code |
| 计费 | 走 /api/coding 前缀才扣套餐 | 普通 /api/v3 是按量计费，是最高频的踩坑点 |
两个端点、一个模型名，配置时务必记牢（完整配置见 接入指南）：
- OpenAI 兼容：
https://ark.cn-beijing.volces.com/api/coding/v3- Anthropic 兼容：
https://ark.cn-beijing.volces.com/api/coding- 模型：
ark-code-latest
为什么不直接用各家官方云？因为 Agent 的请求模式和聊天完全不同：一个重构任务会触发 Plan-Act 循环，每读一批文件、每改一处、每跑一次命令都要回模型一轮，请求量是普通对话的十几倍。套餐制把这部分成本锁死，避免按量计费账单失控。
三、客户端层：四只"手"怎么分工
客户端是真正跑在你机器上、能读文件改代码执行命令的程序。我们用四个，按场景分工：
| 客户端 | 形态 | 接入协议 | 最适合 | 一句话特点 |
|---|---|---|---|---|
| Cline | VSCode 扩展 | OpenAI 兼容 | 芯片 EDA、C++ 大型工程 | 默认逐步弹窗审批，风险最可控 |
| Roo-Code | VSCode 扩展（Cline 分支） | OpenAI 兼容 | 超大项目、复杂任务 | 多模式（Code/Architect/Ask）+ 子 Agent 并行 |
| OpenCode | 终端 + 编辑器 | OpenAI 兼容 | 喜欢终端、要 CI 脚本化 | 开源，终端与 VSCode 同一套配置 |
| Claude Code | 终端 CLI | Anthropic 兼容 | 深度 Claude 工作流 | Agent/Skill/钩子体系最完整，-p 非交互模式适合 CI/CD |
这四个客户端的安装、字段级配置、验证、排错见 接入指南；日常怎么操作、模式怎么切、任务怎么派见 VSCode 三剑客实战手册 与 Claude Code 完整教程。
它们不是四选一的互斥关系——很多人是 IDE 里装 Cline/Roo-Code 做交互式开发，终端里挂 Claude Code 跑批量/CI 任务，共用同一个 Coding-Plan 套餐。
四、编排与记忆层：让 Agent"懂你的项目"
光有模型和客户端，Agent 每次都像第一次见到你的代码库。编排记忆层解决"它怎么知道项目规矩、怎么高效查代码、复杂任务怎么分工"三件事，由四个部件组成：
| 部件 | 作用 | 类比 | 深入文档 |
|---|---|---|---|
| CLAUDE.md / .rules | 写死项目结构、技术栈版本、命令、禁忌 | 给新人的项目交接文档 | 编写指南 |
| MCP 协议 | Agent 接外部工具的标准总线（一次编写，所有客户端通用） | AI 世界的 "TCP/IP" | 协议深度解析 |
| CodeGraph | Tree-sitter 预建符号/调用链索引到本地 SQLite，经 MCP 给 Agent 查 | 给 Agent 一张代码地图 | 完整教程 |
| 子 Agent / Skill | 子 Agent=专职执行角色；Skill=可复用操作手册 | 专职员工 vs 标准作业卡 | 分工模型 |
这一层是拉开使用水平的关键：新手只用"模型 + 客户端"，高手会把 CLAUDE.md 写清楚、MCP 接对工具、大项目挂 CodeGraph、复杂任务拆给子 Agent。
五、权限与安全层：给 Agent 装上刹车
Agent 能执行任意 shell、改任意文件，必须有刹车。我们的做法是两道防线：
- 人工审批：文件修改看 diff 预览、高危命令逐条确认。生产环境禁止开启终端自动批准；
- git 快照兜底：让 Agent 动手前先
git commit或git stash当前工作区，改坏了一键回滚。
安全红线（详见 原理篇第八章）：不开自动审批、密钥走环境变量不入库、只启用可信 MCP、敏感项目评估数据合规、改完必须编译跑测试。
六、一次任务的数据流（把四层串起来）
注意云端只在循环里的"推理"一步出现；读文件、改代码、跑命令、审批全部发生在本地。
七、这个技术栈对应的文档地图
| 你想做什么 | 看哪篇 |
|---|---|
| 理解 Agent 内部为什么能自己改代码 | Coding Agent 工作原理 |
| 把 Coding-Plan 接到客户端（填什么 URL/模型/Key） | 接入指南 |
| 日常从头到尾怎么用一个 Agent 完成任务 | 标准工作流 SOP |
| Cline/Roo-Code/OpenCode 具体怎么操作 | VSCode 三剑客实战手册 |
| Claude Code 完整命令/快捷键/配置 | Claude Code 教程 |
| 写好项目规则、降低 Agent 幻觉 | CLAUDE.md 编写指南 |
| 给 Agent 接外部工具 | MCP 协议深度解析 |
| 大项目让 Agent 快速定位代码 | CodeGraph 代码地图 |
| 复杂任务怎么拆给子 Agent / Skill | Agent vs Skill 分工 |
| 怎么提问效果最好 | Prompt Engineering 方法论 |
一句话总结
我们这套 Coding Agent 系统就四层：云端用 Coding-Plan（
ark-code-latest）当大脑，本地用 Cline/Roo-Code/OpenCode/Claude Code 当手，靠 CLAUDE.md + MCP + CodeGraph + 子 Agent/Skill 让它懂项目、会用工具，再用人工审批 + git 快照兜底安全。 大脑可以换、手可以换，但"编排记忆层"和"权限层"才是决定你用得好不好、闯不闯祸的真正分水岭。