原文内容

我用 AI 辅助写代码的经历：从零开始构建开源agent框架Jarvis

这不是一篇“Agent 组件速通”，而是一篇我如何用 AI 把一个本地 Coding Agent 一步步搭出来的工程复盘。

这是我用 cc 花了十几天逐步搭出来的一个本地 agent 项目：Jarvis。

我写这篇 README，不是想重复网上那些“一个 harness agent 需要哪些部件”“context compression 有哪些套路”“本文速通 agent 核心组件”的文章。那些文章当然有价值，我自己也天天看。但我真正做 Jarvis 之后，最大的感受反而是：

Agent 工程不是摆零件，而是建楼。

你当然要知道一栋楼里哪里放承重墙、哪里放卫生间、管线怎么走；但对一个真正要开工的人来说，更关键的是：

• 第一步地基怎么打。
• 施工顺序怎么排。
• 哪一层先验收。
• 哪些部分必须先稳定。
• 发现问题以后，应该拆到哪里重来。

所以 Jarvis 对我最大的训练，不是让我多记住了几个 agent 名词，而是让我真正体会到：

AI 编程时代，代码生成变快了，但设计、取舍和验收的压力并没有消失，反而被放大了。

Jarvis 想解决什么问题

Jarvis 的目标不是做一个普通聊天机器人，而是做一个更接近真实工程工具的本地 agent：它应该能理解当前项目、判断用户意图、读取仓库、规划修改、申请审批、改代码、展示 diff、运行局部测试、根据失败结果重新规划，并最终给出可追溯的 evidence。

我真正想拆开的，其实是这些问题：

• 用户输入进入系统后，第一步应该先做什么。
• 哪些请求应该直接回答，哪些才应该进入任务流。
• 读仓库、写文件、执行命令、联网搜索，这些能力的边界怎么划。
• AI 什么时候可以自己动手，什么时候必须申请用户审批。
• 测试失败后，系统应该承认失败、重新规划，还是继续硬编一个“成功总结”。

计划书对我来说，不是附属文档，而是施工记录

我在做 Jarvis 的过程中，前后写了接近 10 份计划书。现在仓库里还保留了一部分：docs，当然也删掉了一部分。

这些文档对我来说不是最终架构说明书，而是版本化的施工记录。

有些计划后来被推翻了，有些路线被收编了，有些文档里的设计和现在的实现已经不一致了。计划一直在变，架构也一直在变。所以如果要准确描述这些计划书的价值，我更愿意说：

• 它们记录了我每个阶段在解决什么问题。
• 它们记录了我当时怎么划边界、怎么设计闭环。
• 它们记录了哪些假设后来被验证，哪些被否定。
• 它们是探索性经验，不是永远正确的答案。

也正因为这样，我反而更重视它们。因为 agent 项目最怕的不是计划变，而是没有计划就直接开工，最后只剩下一堆长得很快但说不清为什么这么长的代码。

我觉得最重要的几条搭建经验

1. 先分流输入，再谈 agent

不是每一句话都应该进入 coding task。

• “你是谁？”应该直接回答。
• “解释一下 sandbox 和 approval 的区别”应该是概念解释。
• “阅读一下这个仓库结构”应该是只读分析。
• “帮我修改这个模块”才应该进入受控 coding flow。

所以我早期很重视把输入拆层，而不是一上来全丢给模型：

InputEnvelope
  -> CommandRouter
  -> SkillCommandRouter
  -> NaturalLanguagePreparer
  -> IntentGateway
  -> SafetyGate

这让我学到的第一件事是：Agent 的入口必须先分流，否则所有东西都会坠入同一个任务黑洞。

2. 不像任务的东西，不要强行塞进任务流

很多 agent demo 的问题是，无论用户问什么，系统都喜欢包装成 Task / Plan / Result，看起来很“agent”，但体验很差，也容易误触发工具。

所以我后来越来越强调 response mode 分离。像这些模式，不应该进入 task flow：

• chat_answer
• help_answer
• clarify_question
• repo_inspection
• refusal_or_safety_message

真正允许进入任务流的，反而应该是少数，比如：

• coding_loop
• executor_action
• automation_action

3. coding loop 必须是受控流程

真正进入代码修改时，我更在意的是闭环是不是受控，而不是工具是不是够多。

Jarvis 当时规划过的一个核心闭环大致是：

inspect
  -> plan
  -> approval
  -> edit
  -> diff
  -> scoped test
  -> review
  -> evidence

这里我最看重的是几个硬约束：

• 修改前先检查相关文件。
• 修改前先给计划。
• 写文件前要有审批。
• 修改后要展示 diff。
• 优先跑 scoped tests，而不是默认全量回归。
• 测试失败不能声称成功。
• 最终结果要留下 evidence。

工具只是能力，闭环才是工程。

4. 安全必须是代码边界，不是 prompt 愿望

Jarvis 的计划书里我反复强调一件事：

LLM 输出不能升级成权限。

无论 JARVIS.md、AGENTS.md、CLAUDE.md 或 skill 文档怎么写，它们都只能提供指导，不能绕过代码层的安全策略。

所以我一直很在意几类必须代码强制的边界：

• 写文件审批。
• shell 执行审批。
• 网络访问审批。
• secret / token / .env 拒绝读取。
• 高风险操作拒绝或要求人工确认。

安全不是 prompt 写得诚恳一点就能解决的，安全必须是执行路径上的硬门。

5. 测试不是装饰，测试策略更不是 AI 自动会的

agent 工程里最危险的一句话是：“看起来可以了。”

后来我越来越明确：AI 可以帮忙写测试，但不能完全替你判断什么值得测。它很容易补出很多看起来热闹的测试文件，却没有覆盖真正的风险。

所以我更看重的是：

• chat-like 输入是否真的走了直接回答。
• safety 请求是否仍然被阻断。
• work 请求是否仍然保留审批边界。
• 修改是否只跑相关 scoped tests。

也就是说，AI 可以帮你执行测试，但测试策略本身，至少现在还得人来定。

6. 计划书可以变，但变化要留痕

Jarvis 当前架构和部分早期计划已经有差距，这很正常。

真正重要的不是计划永远正确，而是：

• 每一阶段都有一个明确假设。
• 实现之后能验证这个假设。
• 假设错了能及时收束。
• 新计划能解释为什么替代旧计划。

所以我现在更愿意把计划书看成“工程航海日志”，而不是“永远不许变的圣旨”。

我对 AI 编程的一个越来越强烈的判断

现在很多 coding 工作确实已经可以被 AI 接管：

• 搭脚手架。
• 补样板代码。
• 实现局部功能。
• 重构重复逻辑。
• 给出多个候选实现。

但属于人的压力并没有消失，而是转移到了别处：

• 你要负责项目设计。
• 你要负责边界判断。
• 你要负责功能取舍。
• 你要负责结果验收。
• 你要负责判断“它是真的对了，还是只是看起来像对了”。

所以我后来才会半开玩笑地说：我任命 ChatGPT 做 CTO，我自己做 CEO。

AI 可以是执行力极强的 CTO，但方向、取舍、停损、复盘，这些事还是要 CEO 来做。

agent 现在还没有强到可以替你兜住 testcase

至少在我现在的实践里，agent 在 testcase 和样例这件事上还没有强到让人放心。

它能写测试，也能补样例，但它经常不知道：

• 哪些测试是真正关键的。
• 哪些边界条件必须卡住。
• 哪些样例只是看起来让人安心。
• 哪些测试文件虽然变多了，但并没有覆盖真正的风险。

这也让我想起之前那个笑话：搞大模型的害死了前端兄弟，现在又准备去害测试兄弟。当然，测试兄弟现在还死不了。因为真正高质量的测试意识、边界意识和验收意识，到今天为止依然很稀缺。

一个很让我高兴的现实：学校真的在快速响应这件事

我曾经在教学座谈会上向老师提过两个建议：

• 给学生发 API。
• 开展 agent 与 vibe coding 相关课程。

当然，现在更流行的说法可能是 harness agents，但我关心的核心一直没变：我希望学生不要只停留在“会用聊天框”，而是真正进入“会设计工作流、会构建系统、会带着 AI 做工程”的阶段。

让我很高兴的是，学校在考虑学生意见这件事上确实很有效率。前者已经落地，后者我觉得也不会太远。

README.md 所在文件夹里有一张图，是 dpskv4pro 的本月调用量。我觉得很适合放在这里，因为它说明了一件很朴素但很重要的事：学生真的在用，需求真的存在，基础设施一旦给出来，就会迅速转化成真实生产力。

我希望 Jarvis 以后能成为科大 AI 新课里的一个课程内容

我希望 Jarvis 以后可以成为科大 AI 教学新课里的一个课程内容。

不是把它当成一个简单 demo，而是把它当成一个可以训练学生工程能力的入口。我希望它训练的不是“怎么更快调 prompt”，而是这些能力：

• 大局观。
• 设计观。
• 规划能力。
• 工程取舍能力。
• 对结果负责的能力。

如果以后 AI 会接管越来越多具体 coding 工作，那么学生最该被培养的，也许不是“更快手写更多代码”，而是成为那种能定义问题、组织系统、管理边界、验收结果的人。

说得夸张一点，我希望这样的课程最后培养出来的，不是一批只会调 prompt 的人，而是一批能带着 AI 把事情做成的 CEO。

最后

如果你也想做 agent，我的建议其实很简单：

不要一上来就沉迷“本文带你速通 agent 核心组件”。

先问自己几件事：

1. 我到底要建一个什么系统？
2. 哪些请求根本不应该进入 task flow？
3. 哪些动作必须审批，哪些不需要？
4. 一次 coding task 的标准链路是什么？
5. 如果失败了，系统怎么承认失败并重来？

这些问题想明白了，技术细节自然会慢慢落位。

技术文章会告诉你楼里有什么，但真正把楼建起来，靠的是计划、施工顺序、边界控制、验收标准，以及必要时愿意返工的勇气。

而这恰恰是我在 Jarvis 上体会最深的一件事。