作者：jacksondeng、yuxuanlai、gcchaoguo

1、背景与挑战

1.1 背景

当前从需求到交付的全链路中，大量人工仍耗费在方案设计、代码评审、测试验证等非编码环节，频繁的上下文切换与协作等待严重制约了研发效能。为此，我们在深耕AI编码能力的同时，正将自动化向上游的需求、方案设计与下游的测试、部署环节延伸，旨在通过AI将各环节无缝串联，最终实现需求至部署的全自动化交付与研发效能的全面跃升。

1.2现状

审核将AI全自动化演进规划为L1（纯人工）、L2（人机协同）、L3（全自动）三个阶段。

2025年，我们处于以“技术方案生成代码”为核心的L2阶段。基于“研发效能提升需突破单点、覆盖全链路”的共识，我们正从聚焦Coding，向需求、测试、部署等环节系统化辐射。最终目标是借由AI将各环节无缝串联，构建需求至部署的端到端自动化交付能力，驱动整体研发效能实现80%的效能提升，具体演进路线可以参考图1.1所示：

审核迈向L3需经历三段式能力阶梯：先夯实技术方案生成代码，再打通技术方案至交付链路，最终实现需求到交付的端到端跑通。在此基础之上，我们才会全面进入L3的全自动化交付阶段。详细信息如下：

1.3 挑战

审核要全面演进至L3阶段，需系统应对四大核心挑战：一是交付流程的标准化建设，二是需求描述的规范化与结构化，三是高质量、可检索的知识库搭建，四是核心技能（Skills）的标准化与复用。详细信息如下：

挑战	关键举措
交付流程的标准化	制定一套标准的研发流程，让大模型按照标准流程执行，同时具备流程回滚能力 ● 短期：通过流程编排skill，为大模型制定标准的交付流程，将需求、研发、测试、部署流程全自动串联起来，并且支持出现问题，流程自动回滚的能力 ● 长期：通过流程编排管理页面，配置交付流程及流程对应的相关skills
需求的标准化	让需求按照标准模板输出，大模型可以基于需求生成代码 ● 制定标准的需求模板，主要通过需求概述、需求正文、版本管理、外部依赖等4个部分对需求文档进行规范性约束，提升需求的质量 ● 制定需求的澄清规则，通过对需求概述、需求正文、版本管理、外部依赖等4个部分，建立一套需求澄清的规则，在需求编写不满足条件的情况下，给出修正建议 ● 制定需求评分规则，通过对需求背景、价值衡量、解决方案、影响范围、需求正文设定一套标准的打分规则，方便衡量需求的输出质量，如果不满足评分标准，需求将被打回 ● 构建需求PRD-Agent，配置需求模板、需求澄清规则、需求评分规则，支持产品在PRD-Agent上进行需求编写、澄清等
skills技能的沉淀/标准化	沉淀一套标准的skill能力，增强模型的执行和决策能力，目前需要沉淀技术方案生成、代码生成、代码CR、测试用例执行等skill能力
知识库的搭建	从需求生成代码，需要高质量的上下文 ● 构建审核的业务知识库，让大模型可以基于知识库生成技术方案 ● 构建审核的代码知识库，让大模型可以快速完成代码的熟悉，从而生成高质量的代码
代码质量保障	AI编码在提升速度的同时，也带来了质量失控的风险。若缺乏严格的质量门禁，代码库将在高速迭代中滑向高熵与腐化 ● 构建需求评审、方案评审、代码CR、安全检测等门禁，确保代码质量
线上问题的治理	AI编码基本都在静态代码的生成，对于系统架构、性能、可用性等问题会稍显不足，需要我们有一套对线上系统的实时监控及自我修复能力 ● 构建全自动化治理框架，打通运行时日志和监测指标，实现线上服务的自动巡检与修复、线上异常的实时感知与优化，从而完成从架构、性能到可用性的系统性治理

2、详细实践

我们致力于打造一个能够实现需求至发布全链路自动化、并具备自愈能力的AI交付平台。其成熟标志是形成由多个AI智能体自主协同的“N Agent交付模式”，达成L3级全自动化。为此，我们确立了分阶段演进的路线：现阶段（L2）的核心是“人机协同”，即全力打通并集成研发、测试、部署等关键工具链（MCP），为高阶自动化奠定工程基础。待此阶段稳固后，再系统性地迈向L3的AI全自动化交付阶段。

2.1.人机协同（L2）

2.1.1 技术方案到代码

在过去一年我们聚焦在coding阶段，主要通过“AI技术规范(索引/rules) + 模板化(技术方案/prompt) + MCP工具集成 + AI自我总结”，实现生产力提升的人机协同新范式。详情可以参考《AI研发新范式：基于技术方案全链路生成代码》，具体流程如下：

但是从需求到交付的全链路中，大量人工仍耗费在方案设计、代码评审、测试验证等非编码环节，所以我们将目光逐步向上游的需求、方案设计与下游的测试、部署环节延伸。

2.1.2 技术方案到交付

架构设计

我们在技术方案中，扩展出执行清单，然后通过codebuddy，基于模版化技术方案  +  模版化执行清单（测试执行清单、发布执行清单）+  模版化prompt，分阶段实现从研发到部署交付的目标。

● 研发阶段：基于代码层级结构、控制器层、业务层、持久层完成代码的生成及单元测试覆盖及验证

● 测试阶段：基于七彩石配置、DDL/DML工单、蓝盾流水线、lego环境创建等MCP工具实现测试环境的准备，基于自动化测试用例完成代码质量的验证

● 部署阶段：基于七彩石配置、DDL/DML工单等MCP工具完成发布前的准备，基于无人值守，完成智研发布单的申请、执行

图2.2 审核技术方案到交付的研发流程图

升级事项

我们联通测试、运维团队，通过建设LegoMcp/Skills、DDLMcp/Skills、接口自动化测试Mcp/Skills、接入无人值守，实现研发到部署发布的打通，为后续全自动化交付奠定基础。

Lego环境创建及更新

通过建设Lego环境的DDL、Mcp工具，支持用户在codebuddy内部一键拉起一套测试环境，整体耗时大概在5到10分钟，0平台切换

DDL申请

通过建设DDLSkill、DDLMcp工具，将DDL申请耗时降低到秒级以内

接口自动化测试

以审核的申诉复审场景为切入点，通过AI自动识别代码，生成存量接口/增量接口的自动化测试用例接口，最后通过codebuddy mcp一键发起接口自测，实现接口的自动化测试

添加MCP	添加Skills	开始测试
	在codebuddy内部安装测试用例执行skills	prompt输入：测试申诉复审接口

注明：在审核申诉复审场景中，我们当前通过“人工梳理结合AI辅助”的方式，完成了全链路自动化测试用例的构建。目前尚未具备由AI端到端自动生成完整测试用例的能力，该方向存在较大的迭代与优化空间。

接入无人值守

架构升级收益

○ 跨平台减少：架构优化前，完成测试和部署链路的工作需要跨6个平台，优化后可以在CodeBuddy内部闭环完成测试和部署的所有操作

○ 操作步骤减少：从测试到部署的步骤从12个步骤优化到5个步骤（理想可优化为2个步骤），提升了研发的交付效率

○ 耗时减少：架构优化前，测试阶段环境创建/更新平均节约时长1h，节约比例达到60%+（暂未统计自动化测试部分）；部署阶段平均节约时长达到0.5d，节约比例达到50%

2.1.3需求到交付

架构设计

在实现技术方案至部署交付的链路贯通后，我们将重心转向需求至代码生成链路的建设。最终，通过串联这两大阶段，我们将形成从需求到部署的端到端全链路闭环，从而为构建未来的AI全自动化交付体系奠定坚实基础。具体开发流程如下：

最佳实践

能力沉淀

在需求至代码生成的实践闭环中，我们已构建起一套完整的能力体系，沉淀出1个PRD-Agent、5套规范化标准、3个知识库与3项核心技能。该体系具备良好的通用性与可扩展性，已能覆盖并支持多数工程场景的快速落地。详情如下：

2.2AI全自动化交付（L3）

架构设计

我们以 CodeBuddy 为基座，完成了从需求到部署交付的实践，但是发现人工干预的环节还是比较多。在此基础上，我们引入了 Harness Engineering for AI Coding  理念，构建了一套标准的工程交付框架。该框架实现了从需求、方案、开发、测试到发布的全流程自动化串联；通过需求评审、方案评审、质量门禁与 MR 等工程卡点保障核心质量；并具备闭环反馈与卡点自动修复能力，支撑流程向自适应、无人值守方向演进。同时，我们持续沉淀标准 Rules、高质量知识库与可复用的 Skills，以此优化 AI 的上下文质量，系统性地增强大模型在复杂交付链路中的决策与执行可靠性。

最佳实践

我们通过在审核挑选6个试点需求，基于openclaw完成需求到代码生成的试验，最终沉淀出一套标准的交付框架与能力，方便后续在全中心推广。

能力沉淀

通过AI全自动化实践，我们已沉淀出一套标准交付流程、三套核心技能，并实现了与Tapd的深度集成，建立起规范化的需求管理链路。目前，该能力体系已具备较强的工程普适性，可支持多数业务场景的快速接入与应用。详情如下：

2.3、效果数据

基于OpenClaw/CodeBuddy模式，我们完成了6个试点需求的三轮迭代优化且成果显著，需求评分稳定在80分以上，技术方案评分达80分以上；平均生成对话轮次2轮；代码行采纳率达90%以上，AI生成率达到80%以上。

3、实践总结

在基于OpenClaw/CodeBuddy模式验证需求到部署的全链路过程中，我们遇到了诸多挑战。目前，大部分问题已得到有效解决，这为我们在中心内的顺利推广奠定了坚实基础。为系统沉淀经验，我们分别从需求侧与编码侧对典型问题进行了梳理与总结，具体如下：

4、未来展望

经过对L2~L3阶段的实践，然后结合业界的harness理念，我们认为L3阶段可归纳为：AI全自动化交付 = LLM + Harness Engineering（工作流程 + 知识库 + skills管理） + Business Engineering（skills + 知识库的沉淀），具体公式组成如下：

我们认为，一个完整的AI全自动化平台应由两套并行、协同的框架构成：AI全自动化交付框架与AI全自动化治理框架 。

AI全自动化交付框架旨在实现从需求、设计、开发、测试到发布的全流程自动化串联，并通过内置的需求评审、方案评审、质量门禁与MR等工程卡点，结合闭环反馈与自修复机制，保障交付流程的稳定、自适应与高质量。

AI全自动化治理框架则与其并行，通过构建覆盖运行时日志、监测指标、Spec知识与中间产物的全域数据洞察系统，实现线上服务的自动巡检与修复、异常的实时感知与优化，以及知识与Skills的自动化回溯与更新，从而系统性地保障架构、性能与可用性。

二者共同构成“交付驱动效率，治理保障质量”的双轮驱动体系，确保AI研发全流程在持续高效运转中，始终朝向有序、可持续的方向演进，如图4.1所示：

5、结语

目前，我们基于OpenClaw/CodeBuddy初步构建了AI全自动化交付框架，但其交付流程与Skills管理仍处于线下、非中心化的初级阶段。同时，AI全自动化治理框架尚在规划中。为实现体系的标准化与规模化，我们计划与研效团队协同，将这两大框架全面整合并迁移至AMS一站式研效平台，以达成线上化、中心化的统一管理。

作者：seanguo

引言

做后台开发的同事应该都有这个体会：从接到需求到最终发布，我们要在 PM、GitPlatform、编辑器、DevOps 平台、Galileo 之间来回横跳。每次切换都在丢上下文——刚在 PM 看完需求描述，切到编辑器就忘了某个细节；部署完测试环境去查日志，又得回忆刚才改了哪几行代码。

你可能听过 Vibe Coding 这个说法——打开 AI 对话框，用自然语言描述需求，让模型直接生成代码，跑通就算完。原型验证很爽，但一旦要上生产，问题就来了：生成的代码质量不可控、没有审查流程、改完了 commit message 也是乱的。说到底，Vibe Coding 是"提示即祈祷"（prompt-and-pray），你把需求扔给 AI，然后祈祷它别出错。

今年行业里逐渐形成了一个更成熟的概念：Agentic Engineering（智能体工程）。核心思路是——人负责定义目标、约束条件和质量标准，AI 作为自主智能体在结构化流程中执行规划、编码、测试和迭代，每个关键节点都有人工审核。它不是让 AI 随意发挥，而是把 AI 的能力嵌入到一套有纪律的工程体系里。

最近一周，我用 Claude Code + 自定义 Skill/Command/MCP 体系 做了一次实践：把从需求到发布的所有环节串到一个终端会话里。AI 全程保持对当前任务的理解，在预设的流程框架内自主执行；我只需要在关键节点做决策——审批计划、确认部署、审查代码。回过头看，这套东西就是 Agentic Engineering 在后台开发场景的一个落地样本。

这篇文章把整个流程拆开给大家看，从需求到发布每一步怎么跑的，踩过哪些坑，最后沉淀出了什么（🔥token的十大技巧）。

不过，说实话，虽然过程很完美，但消耗的 token 数量也不容小觑。迫切需要更高的 token 额度了

全流程概览

先看效果。下面是整个流程的各阶段概览——从需求到发布，开发者的角色从"亲自执行"变成了"审核确认"：

阶段	核心工具	开发者做什么
① 需求创建 + 分支初始化	pm-dev	口述需求
② 需求澄清	brainstorming	回答 2-3 个问题
③ 制定实施计划	writing-plans	审核计划
④ 并行开发	executing-plans  + /commit	几乎无需干预
⑤ 代码自审	code-review	审核报告
⑥ 编译部署	dtools	确认部署参数
⑦ 日志排查	galileo-log-query	手动触发测试
⑧ 创建 MR	/create-mr	确认 MR 信息
⑨ AI 辅助评审	/review-mr	审核 AI 评审意见
⑩ 修复评审意见	/fix-mr	确认修复方案
⑪ 合入发布	CI/CD	点 Merge + 灰度发布

后面各阶段会逐个展开细节。

工具体系速览

这套工具链分三层，理解了层次关系，后面的内容就好跟了：

层次	说明	示例
Skill （技能）	核心业务逻辑，由系统根据上下文自动触发，或被 Command 调用。每个 Skill 有独立的工具权限白名单和执行流程	pm-dev 、git-workflow、code-review、dtools、galileo-log-query、git-context、wiki-doc、service-analyzer
Command （斜杠命令）	用户通过 /xxx 主动调用的入口，轻量级路由，委托给对应的 Skill 执行	/commit 、/create-mr、/review-mr、/fix-mr、/analyze-codebase
MCP Server （外部服务）	通过 Model Context Protocol 连接的外部平台 API，为 Skill 提供数据和操作能力	GitPlatform MCP、PM MCP、Galileo MCP、KnowledgeBase 知识库 MCP、InternalWiki MCP

此外还有一类来自 superpowers 插件的结构化工作流 Skill（brainstorming、writing-plans、executing-plans、subagent-driven-development、verification-before-completion 等），它们定义了从需求澄清到代码交付的标准流程，防止 AI 跳过关键步骤自由发挥。

下面以一个真实的小变更需求为例，走完从需求到发布的全流程——「RedeemReward 接口数据上报逻辑变更：无论领取是否成功，都要上报结果，新增 errcode/errmsg 字段」。选这个需求是因为它体量适中（涉及 go mod 依赖更新、结构体扩展、接口逻辑重构），刚好能展示每个阶段的自动化能力，又不会因为业务本身太复杂而分散注意力。

阶段 1：需求获取与分支初始化

[!info] 使用的工具pm-dev (Skill) — PM 开发初始化工具，两种入口：

1. 给 PM URL → 自动解析需求 ID，拉取需求标题和正文

2. 不给 URL → 通过 brainstorming 澄清需求后，自动调用 PM MCP 创建需求单

创建完成后自动：建分支（feature/{username}_{short_id}）→ 保存需求文档到 docs/pm/ → 衔接后续开发流程

场景：手头没有现成的 PM 需求单，直接在终端里口述需求就行。

操作：输入 /pm-dev 命令并附上需求描述：

❯ /pm-dev RedeemReward
接口里的数据上报逻辑变更，无论领取是否成功，都要上报结果
（上报数据新增 errcode, errmsg 字段）。新字段要更新
git.example.com/org/component/report_data/reportstruct go mod 获取。

Claude Code 检测到当前在 master 分支，又没有 PM URL，就弹出选择：

· 没有检测到 PM 需求单信息，请选择如何继续？ → 自动创建新需求单

接下来 AI 会进入 brainstorming 模式澄清需求（详见阶段 2），澄清完自动创建 PM 需求单：

⏺ pm - stories_create
  workspace_id: "12345678"
  name: "RedeemReward上报逻辑变更新增错误码"
  description: "RedeemReward 接口的数据上报逻辑变更：无论领取是否成功，都要上报结果..."
✅ 需求单创建成功
  - 标题: RedeemReward上报逻辑变更新增错误码
  - 链接: https://pm.example.com/pm_fe/12345678/story/detail/1012345678001958011

口述需求，AI 交互澄清后，自动创建的需求单示例：

随后自动创建开发分支并保存需求文档：

⏺ git checkout -b feature/alice_131900001
⏺ Write(docs/pm/131900001.md)  — 保存需求文档

效果：一段口述 → PM 需求单 → 规范命名的开发分支 → 需求文档落盘。全程没打开过 PM 页面。

[!tip] Skill 也可以当命令用pm-dev 是一个 Skill（系统根据上下文自动触发），但你也可以通过 /pm-dev 显式调用它。实际上，所有 Skill 都支持以 /skill-name 的方式手动触发——当你明确知道要用哪个 Skill 时，直接 /xxx 调用比等待自动触发更高效。

[!tip] 有现成的 PM 需求单？ 直接提供链接即可：/pm-dev https://pm.example.com/xxx/story/detail/10xxx，AI 会自动拉取需求详情并创建开发分支。

直接拉取需求单示例：

补充一个 AI aha moment 的例子：

我在开发 pm-dev skill 的时候，发现项目管理 MCP Server 并不支持将链接里面的长ID（1012345678001900001）转成 short_id（131900001）。但是想要自动创建特性管理值就需要用到 short_id，那该怎么做呢？

AI 直接推测出了 short_id 和 ID 的关系！（我开发这么久的需求，见过的需求 url & short ID 无数，从来都没有发现两者之间的关系。这个时候我就感觉 AI 是真的能够发现我们肉眼所发现不到的规律。）

阶段 2：交互式需求澄清

[!info] 使用的工具superpowers:brainstorming (Skill) — 结构化的需求澄清流程。AI 不会直接写代码，而是先探索代码库了解现状，然后通过提问-回答逐步明确需求边界、技术方案和实现路径，最终产出一份双方达成共识的设计方案。

wiki-doc (Skill) / knot MCP — 知识库检索。澄清过程中 AI 可以搜内部 Wiki 文档或通过 KnowledgeBase 知识库做语义检索，为设计决策补充技术背景和历史方案参考。

场景：需求描述就一句话，AI 得先搞清楚代码现状和变更细节才能动手。

[!info] 链式调用 这个阶段不需要手动触发——pm-dev 完成需求创建和分支初始化后，会自动链式调用 brainstorming 进入需求澄清。brainstorming 完成后又会接着调用 writing-plans（阶段 3），形成 需求 → 澄清 → 计划 的自动流水线。

操作：AI 先自动探索项目代码，了解 RedeemReward 接口和上报逻辑的现有实现：

⏺ Explore(探索 RedeemReward 和上报逻辑)
  Done (20 tool uses · 93.8k tokens · 56s)

然后基于代码理解，抛出关键问题：

🤔 新增的 errcode/errmsg 字段是加到现有的 Report_table_001（数据上报表）上，
   还是用一个新的上报表？
❯ 复用 Report_table_001 表, 更新 go mod 以后就有新增的 2 个字段了

AI 理解后，提出两种实现方案并给出推荐：

方案 A（推荐）：在 RedeemReward 末尾统一上报，不提前 return
  将上报逻辑移到函数末尾，把第三方调用的 error 信息传入上报参数。
  - 优点：改动集中，与现有 ReportConsumeCount 风格一致
  - 缺点：需要调整 error 处理流程
方案 B：在每个 return 前都加一次上报调用
  - 优点：不改变原有 return 逻辑
  - 缺点：多处重复调用，容易遗漏

· 你倾向哪种实现方式？ → 方案 A：统一上报 (Recommended)

确认方案后，AI 输出完整的设计方案：

设计方案:
1. 数据结构变更 — CardReportParam 新增 ErrCode/ErrMsg 字段
2. RedeemReward 流程变更 — 用 defer 确保上报一定执行
3. 变更文件清单:
   ┌──────────────────────────┬──────────────────────────────────────┐
   │           文件           │                 变更                 │
   ├──────────────────────────┼──────────────────────────────────────┤
   │ go.mod                   │ 升级 report_data 版本           │
   │ repo/report/card_report.go │ CardReportParam 新增字段，ReportCard │
   │                          │ 填充新字段                           │
   │ logic/redeem_reward.go      │ 重构 RedeemReward，无论成败都上报       │
   └──────────────────────────┴──────────────────────────────────────┘

效果：AI 不是闭门造车——先读代码、再提问、再出方案。设计文档自动保存到 docs/plans/ 并 commit。

[!tip] 不要重复造轮子pm-dev 早期版本曾经自己实现了头脑风暴/写计划/执行计划的功能，后来发现 superpowers 插件已经提供了成熟的 brainstorming、writing-plans、executing-plans 等 Skill，经过大量打磨，效果更好。最终把自制逻辑替换为链式调用现成 Skill。教训：自定义 Skill 的核心价值是编排和串联，而不是从零实现所有能力。

[!tip] 知识库补充上下文 在澄清过程中，AI 可以通过 wiki-doc 搜索内部 Wiki 文档，或通过 knot 知识库检索已有的技术方案，为设计决策提供依据。

阶段 3：制定实施计划

[!info] 使用的工具superpowers:writing-plans (Skill) — 结构化计划编写。AI 深入读代码细节（结构体字段、错误处理方式、依赖版本），确保计划里每个 Task 都有精确的文件路径、代码变更描述和验证标准。计划自动保存到 docs/plans/ 并 commit，人工审核通过后才进入执行。

场景：设计方案确认后，AI 自动深入阅读代码，生成可执行的实施计划。

操作：AI 先扎进代码细节——结构体字段、错误处理方式、go mod 版本——确保计划里的代码路径和修改点都是准确的：

⏺ Read: repo/report/card_report.go, logic/redeem_reward.go, errs 包
⏺ 查找 Report_table_001 结构体当前字段
⏺ 当前版本 v1.0.180 还没有 errcode/errmsg 字段，更新 go mod 后新版本才会有

然后生成实施计划（223 行），自动保存并 commit：

⏺ Write(docs/plans/2026-03-03-claimgift-report-errcode.md)
计划拆成 4 个 Task：
  1. 更新 report_data 依赖 — go get 升级版本，验证新字段存在
  2. CardReportParam 新增 ErrCode/ErrMsg — 修改结构体和 ReportCard 函数
  3. RedeemReward 无论成败都上报 — 重构流程，asyncReportRedeemReward 接收 error
  4. 最终验证 — go build/vet

[!warning] 人工审核是关键 这是你审查 AI 方案的第一道关卡。计划里每个 Task 都有精确的文件路径、代码变更描述、甚至具体的代码片段，方便逐条审核。AI 可能会遗漏边界情况或误判依赖关系，这一步不能省。

阶段 4：并行执行开发任务

[!info] 使用的工具superpowers:executing-plans / superpowers:subagent-driven-development (Skill) — 计划执行引擎，两种模式：

• Sequential：主 Agent 按顺序逐 Task 执行

• Subagent-Driven（推荐）：为每个 Task 派独立子 Agent 并行执行，完成后自动跑 spec review（功能是否符合计划）和 code quality review（代码质量检查）

/commit (Command → git-workflow commit 模块) — 智能分析 git diff --cached，生成 Conventional Commits 格式的 commit message（feat/fix/refactor 等），交互确认后提交。还会检查是否需要拆分原子提交。

场景：计划审批通过，选择执行方式。

· 选择哪种执行方式？ → Subagent-Driven (Recommended)

操作：AI 按计划逐个派子 Agent 执行，每个 Task 完成后自动跑 spec review 和 code quality review：

⏺ Task 1: 更新 report_data
  ├─ Agent 执行 (5 tool uses · 49s)
  ├─ 新字段: Errcode(string), Errmsg(string), 版本 v1.0.182
  └─ ✅ Spec review 通过
⏺ Task 2: CardReportParam 新增字段
  ├─ Agent 执行 (6 tool uses · 1m 6s)
  └─ ✅ Spec review 通过
⏺ Task 3: RedeemReward 上报重构（核心变更）
  ├─ Agent 执行 (4 tool uses · 6m 25s)
  ├─ ✅ Spec review 通过
  └─ ✅ Code quality review 通过，无 critical/important issues
⏺ Task 4: go build + go vet
  └─ ✅ 全部通过

每个 Task 完成后自动生成规范的 Git commit：

d81eaee chore: upgrade report_data for new errcode/errmsg fields
18a0975 feat: add ErrCode/ErrMsg to CardReportParam and ReportCard
e978e6b feat: report RedeemReward result regardless of success or failure

效果：4 个 Task 全部完成，3 个实现 commit。你只在关键节点确认就行。

变更文件汇总：
- go.mod / go.sum — 升级 report_data v1.0.180 → v1.0.182
- repo/report/card_report.go — CardReportParam 新增 ErrCode/ErrMsg，ReportCard 填充
- logic/redeem_reward.go — RedeemReward 无论成败都上报，传入 errcode/errmsg

git commit 交互式澄清，自动生成规范的 commit 消息：

规范 git commit 示例，更容易看出变更内容。

subagents 并发任务示例，superpowers:execute-plan 会自动根据需要执行的计划，决定开几个 subagent，全程不用操作。你唯一需要的就是担心 token 额度。

阶段 5：代码审查（自审）

[!info] 使用的工具code-review (Skill) — Golang 代码审查工具。对 git diff 变更做系统化审查，按严重程度（Critical / Major / Minor / Suggestion）和分类标签（业务逻辑 / 安全性 / 性能影响 / 编程规范等 8 类）输出 CR 报告。

内置完整的检查清单，覆盖：

• Critical：空指针、SQL 注入、数据竞争、资源泄漏、循环中 defer

• Major：错误处理不规范（未用 errs.Newf/Wrapf）、嵌套超 4 层、switch 缺 default、并发安全

• Minor：命名规范、import 顺序、魔法数字、函数超 80 行

• Suggestion：可用 lo 简化集合操作、可用 copier 简化结构体复制、Table-Driven Tests

场景：代码写完了，提交 MR 之前先自己过一遍，在 reviewer 看到之前就消灭明显问题。这一步是"自查"——用 AI 帮你快速扫一遍格式、命名、规范类的低级问题；后面阶段 9 的 AI 辅助评审则是站在 reviewer 的角度做正式审查，两者定位不同。

操作：直接在终端里说就行：

❯ 审查一下当前分支相对 master 的代码变更

AI 自动加载 code-review skill，获取 diff 并执行审查：

⏺ git diff master...HEAD — 3 个文件，+21 -11 行
审查报告：
┌──────────┬──────┐
│ 级别     │ 数量 │
├──────────┼──────┤
│ Critical │ 0    │
│ Major    │ 0    │
│ Minor    │ 1    │
│ Suggestion│ 1   │
└──────────┴──────┘
m1. [CR-可读性] ChannelID 魔法数字缺少注释
  文件: logic/redeem_reward.go:43
  ChannelID: 3 缺少注释说明含义（会员页发放场景）
  建议: 添加行内注释或提取为命名常量
S1. [CR-编程规范] Errcode/Errmsg 字段缩进不一致
  文件: repo/report/card_report.go:57-58
  与上方字段的对齐方式不一致
  建议: 统一使用 gofmt 标准对齐
⏺ Write(docs/code-review-report-20260303-153022.md) — 保存报告

· 如何处理审查结果？
  ○ 自动修复所有问题
  ○ 仅保存报告
  ○ 指定要修复的问题（输入编号如 m1, S1）

[!warning] 本文示例中跳过了自审修复 为了在后面阶段 9（AI 辅助代码评审）完整展示 /review-mr 的工作流——包括 AI 如何发现问题并精确提交行级评论到GitPlatform——这里选了"仅保存报告"，把两个问题留给 MR 评审阶段处理。

实际开发中建议自审阶段就修掉所有问题，让 reviewer 聚焦更高层面的设计和逻辑。

效果：code-review 相当于一个随时待命的 Golang 审查专家，内置了团队的编码规范和检查清单。提 MR 前先跑一遍，格式、命名、规范类问题基本能清干净，reviewer 就不用在这些细节上浪费时间了。

阶段 6：编译部署到测试环境

[!info] 使用的工具dtools (Skill) — DevOps 平台 CLI 工具集成。自动从 Makefile 探测 APP/SERVER/ENV/INSTANCE 等参数（找不到时依次查 go.mod、trpcprotocol 协议路径），支持 dpatch（包发布）、bpatch（二进制发布）、ipatch（镜像发布）三种模式。还会自动处理 Mac → Linux 交叉编译（CGO_ENABLED=0 GOOS=linux GOARCH=amd64），仓库没有 Makefile 时会自动生成标准化构建/部署模板。

场景：代码开发完毕，部署到 pre 环境跑一下看看。

操作：输入 /dtools，AI 自动从 Makefile 中提取部署参数：

确认部署参数：
  APP=my_app, SERVER=reward_service, ENV=pre, USER=alice
· 选择哪种发布方式？ → 指定实例发布 (make deploy)

AI 执行交叉编译和部署：

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -v -o .build/reward_service
dtools bpatch -env pre -app my_app -server reward_service \
  -bin .build/reward_service -user alice \
  -instances "pre.my_app.reward_service.instance001"

[!tip] 自动发现配置过期 部署过程中发现 Makefile 里的实例名 instance002 已经过期了，AI 自动跑了 dtools node ls 查到当前可用实例是 instance001，确认后发布成功，还顺手把 Makefile 里的实例名更新了。这种"顺手修"的能力在日常开发中很实用。

效果：编译 + 部署 + 修正过期配置，一条命令搞定。

dtools发布示例：

阶段 7：日志排查与调试

[!info] 使用的工具galileo-log-query (Skill) — Galileo日志查询。通过内置 Python 脚本调用 Galileo Log Query API，支持按 target（BG-PLATFORM.{appid}.{server}）、namespace、时间范围、查询语句、traceID 等条件查日志。自动探测 appid/server（优先从 Makefile、go.mod、trpcprotocol 路径提取），内置防上下文爆炸机制（默认 limit 50，建议先用 level:error 缩小范围）。脚本查不到结果时会自动降级到Galileo MCP 的 ask_question 接口。

场景：部署后需要验证上报数据是否正确，或者排查异常。这一步目前还是"半自动"的——AI 能帮你查日志、定位问题，但测试请求还得人工手动发，因为 AI 不了解整条调用链的上下游，没法自己构造有效的测试用例。后续计划在代码里加测试入口，让 AI 能直接发 tRPC 请求触发模拟调用。

操作：直接在终端中描述查询需求：

❯ 帮我查一下 pre 环境 reward_service 最近 10 分钟的 error 日志

AI 通过Galileo API 查询，拿到结果后自动关联代码上下文分析：

🔍 问题定位：
  - redeem_reward.go:48 上报时 cfg 为 nil
  - 原因：获取配置失败的路径没有正确传入默认值
  - 建议修复：在 cfg == nil 时使用空 config 而非跳过上报

[!tip] 支持多种查询方式

• 按 trace_id 查询完整调用链

• 按关键词搜索特定日志

• 按时间范围 + 日志级别过滤

• 按 target/namespace 精确定位服务

Galileo日志自助排查示例：

再给一个例子，辅助排查Galileo profile 内容，帮忙快速定位了一个 OOM 问题。

阶段 8：创建 Merge Request

[!info] 使用的工具/create-mr (Command → git-workflow push-mr 模块) — MR 创建全自动化：

1. 调用 git-context 获取 project_id、校验分支命名

2. 从分支名提取 PM short_id，通过 PM MCP 拉取需求标题，组装源码关键字（--story={id} {title}）

3. 分析 git log origin/master..HEAD 全部 commit 和 diff，生成 MR 标题和描述（含变更说明 + 影响范围）

4. 预览确认后，git push -u origin + 调用GitPlatform MCP 创建 MR

git-context (Skill) — GitPlatform项目上下文提取，两个复用模块：project-context（解析 project_id、校验分支、检查工作区）和 mr-locate（从 URL 或当前分支定位 MR 并获取元数据）。

场景：测试通过，该提代码了。

操作：输入 /create-mr，AI 自动执行完整流程：

⏺ git-context:
  - 解析分支名 feature/alice_131900001 → 提取 story ID: 131900001
  - 校验分支命名规范 ✅
  - 通过 PM MCP 获取需求标题
⏺ 分析 git log origin/master..HEAD 的全部 commit
⏺ 预览生成的 MR 信息：
  项目: org/team/project/backend/reward_service
  分支: feature/alice_131900001 → master
  PM: --story=131900001 RedeemReward上报逻辑变更新增错误码
  标题: RedeemReward 上报逻辑变更，无论成败都上报并新增错误码

确认后自动推送分支并创建 MR：

⏺ git push -u origin feature/alice_131900001
⏺ git-platform - create_merge_request
✅ MR 创建成功！
  - 链接: https://git.example.com/.../reward_service/-/merge_requests/64
  - 状态: can_be_merged
  - 必要评审人: bob, charlie（GitPlatform项目已配置默认评审规则，自动分配）

自动生成的 MR 描述：

--story=131900001 RedeemReward上报逻辑变更新增错误码
## 变更说明
- 升级 report_data v1.0.180 → v1.0.182，获取 Report_table_001 新增的 errcode/errmsg 字段
- CardReportParam 新增 ErrCode/ErrMsg 字段，ReportCard 填充到上报结构体
- RedeemReward 接口无论领取成功或失败都执行数据上报，传入错误码和错误信息
- 获取配置失败时也上报（cfg 为 nil 安全处理）
## 影响范围
仅影响 RedeemReward 接口的数据上报逻辑，其他接口的 ReportCard 调用不受影响
（ErrCode/ErrMsg 零值默认 0/""）

效果：MR 标题、描述、PM 关联全部自动生成，格式规范、内容完整。

全自动提交 MR 示例，极大缓解了写 MR 描述的痛苦。

GitPlatform MR 页面示例：

阶段 9：AI 辅助代码评审

[!info] 使用的工具/review-mr (Command → git-workflow review 模块) — AI 代码审查，精确提交行级评论到GitPlatform MR：

1. 通过 git-context 的 mr-locate 定位 MR（支持从 URL 解析或从当前分支自动查找）

2. 加载 code-review 的审查标准（含 Golang 规范、trpc-go 模式、完整检查清单），仅审查新增/修改的行

3. 每个问题标注严重程度和分类标签

4. 用 git show {source_branch}:{file_path} 验证行号准确性，确保评论定位精确

5. 人工审核后批量调用GitPlatform MCP 提交评论（单条失败不阻塞其余）

场景：MR 创建后，reviewer（同事 charlie）用 AI 辅助审查这个 MR。

操作：reviewer 在自己的终端中输入 MR 链接：

❯ /review-mr
https://git.example.com/org/team/project/backend/reward_service/-/merge_requests/64

AI 自动获取 MR 元数据、拉取 diff、读源文件验证行号，然后输出审查结论：

变更文件：
  - repo/report/card_report.go (+4 行)
  - logic/redeem_reward.go (+17 -11 行)
  - go.mod (+1 -1), go.sum (+2 -2)
主要逻辑评估：
  - 整体逻辑正确：无论成败都上报，cfg 为 nil 时安全处理 ✓
  - errs.Code(nil) / errs.Msg(nil) 在 trpc-go 框架中 nil 错误返回 0/"" ✓
  - 依赖升级合理 ✓
发现问题：
  Minor 1 个：
  - repo/report/card_report.go:57-58 — Errcode/Errmsg 字段赋值缩进与上方字段不一致
  Suggestion 1 个：
  - logic/redeem_reward.go:43 — ChannelID: 3 魔法数字，原有注释 // 发放场景，3-会员页
    在重构时被误删，建议补回

审查概要示例：

[!tip] AI 能区分"本次引入"和"历史遗留" 审查过程中 AI 发现 asyncReportRedeemReward 函数名带 async 前缀但实际是同步调用，但它主动拉了 master 分支原始代码对比，确认这是历史遗留而非本次引入，所以没有纳入审查范围。这个能力很重要——没人喜欢 reviewer 在你的 MR 里提一堆历史债务。

确认后，AI 将 2 条评论精确提交到GitPlatform MR 页面：

· 代码审查已完成，请选择评论提交范围：→ Minor + Suggestion（共 2 条）
⏺ git-platform - create_merge_request_note
  ✅ M1 → repo/report/card_report.go:57（含修复代码建议）
  ✅ S1 → logic/redeem_reward.go:43（含补回注释或提取常量两种方案）

提交评论示例：极大提高了 CR 效率，不用再一个个去评论了。

AI 提交评论的关键，是找准要评论的位置。经过实测，发现 Claude 模型效果最好，DeepSeek 模型经常找错行数，评论到错误的位置。

GitPlatform MR 上面的评论效果：

效果：代码评审从人工逐行看 diff 变成了 AI 初筛 + 人工把关。AI 精确定位到文件和行号，附带代码建议，reviewer 只需审核和决定提交哪些评论。更多真实案例见附录中的「AI 代码评审案例」。

[!warning] AI 评审有对有错，人工审核不能省 AI 给出的评审意见不一定都是对的。它可能误判代码意图、遗漏业务上下文、或者给出看起来合理但实际不适用的建议。上面这个例子里 AI 提的 2 个问题碰巧都是准确的，但在更复杂的 MR 中，我们见过 AI 把正确的错误处理标记为"缺少 error check"、把刻意的空实现标记为"未完成代码"等误判。所以 reviewer 拿到 AI 的审查结果后，每一条都要过脑子判断，该采纳的采纳，不靠谱的直接丢掉。

[!tip] 跨模型审查：避免同一个模型的盲区 一个实用技巧：谁写的代码，就让别的模型来审查。同一个模型写的代码再让它自己审，容易陷入相同的思维盲区——它写代码时没考虑到的问题，审查时大概率也发现不了。比如用 Claude 写的代码，可以用 Codex 或 Gemini 来做 AI 评审；反过来也一样。不同模型的知识结构和关注点不同，交叉审查能显著提高问题发现率。

阶段 10：修复 MR 评审意见

[!info] 使用的工具/fix-mr (Command → git-workflow fix 模块) — MR 评审意见自动修复：

1. 通过 git-context 定位 MR，自动切到源分支并拉最新代码

2. 调用GitPlatform MCP 拉所有未解决评论（resolve_states=[1]），提取文件路径、行号、评论内容

3. 读对应文件（前后各 10 行上下文），分析问题是否仍存在并生成修复方案

4. 交互展示分析结果（含风险评估），确认后逐条修改

5. 修改后自动跑 go build ./... 验证编译，并调用GitPlatform MCP 回复每条评论

场景：MR 收到了 reviewer 的评审意见，需要逐条修。

操作：终端里输入 /fix-mr，AI 自动定位当前分支的 MR 并拉取未解决评论：

⏺ MR: #64 - RedeemReward 上报逻辑变更，无论成败都上报并新增错误码
  未解决评论: 2 条
────────────────────────────────
[1] logic/redeem_reward.go:43
评论者: charlie
评论内容: [Suggestion] ChannelID 魔法数字 3 缺少注释说明
修复方案: 为 ChannelID: 3 添加注释 "// 发放场景，3-会员页"
────────────────────────────────
[2] repo/report/card_report.go:59-60
评论者: charlie
评论内容: [Minor] Errcode/Errmsg 字段赋值缩进与上方字段对齐不一致
修复方案: 调整 Errcode/Errmsg 缩进，使用 gofmt 标准对齐
────────────────────────────────
· 如何处理这 2 条未解决评论？ → 全部修复

AI 自动执行修复：

[1] 修复 logic/redeem_reward.go:43
  -    ChannelID: 3,
  +    ChannelID: 3, // 发放场景，3-会员页
[2] 修复 repo/report/card_report.go:59-60
  -    Errcode:    cast.ToString(param.ErrCode),
  -    Errmsg:     param.ErrMsg,
  +    Errcode:     cast.ToString(param.ErrCode),
  +    Errmsg:      param.ErrMsg,
⏺ go build ./...  ✅ 编译通过
⏺ gofmt -d ...    ✅ 格式检查通过

修复完成后，通过 /commit 提交：

fix: address CR comments for RedeemReward report changes
- 为 ChannelID 魔法数字 3 补充注释说明（会员页发放场景）
- 修正 Errcode/Errmsg 字段缩进，与上方字段对齐一致

然后自动推送并回复评论。如果后续还有新的评审意见，再跑一次 /fix-mr 就行。

效果：评审 → 修复 → 提交 → 回复的完整闭环，全程在终端里完成。

阶段 11：合入发布

[!info] 使用的工具 CI/CD 流水线 — DevOps 平台自动构建与发布

场景：评审意见全部修完，MR 拿到 Approve。

操作：

1. GitPlatform上点 Merge 合入主干

2. 03 流水线自动触发：编译 → 构建镜像 → 推送镜像仓库

3. 按发布流程灰度发布到现网

这一步目前还是纯人工操作——合入和发布涉及灰度策略和线上风险，暂时不打算交给 AI。

效果：从一句口述需求开始，到代码合入主干触发自动发布，整个流程的核心工作都在一个终端会话里完成了。

开发这个需求，消耗的 token 情况如下：

总结

全流程回顾

回到开头那张概览表，这里补充一下各阶段的实际耗时：

阶段	耗时	人工操作
① 需求创建 + 分支初始化	自动	口述需求
② 需求澄清（brainstorming）	~5 min	回答 2-3 个问题
③ 制定实施计划	~3 min	审核确认
④ 并行开发（4 个 Task）	~10 min	几乎无需干预
⑤ 代码自审	~2 min	审核报告
⑥ 编译部署	~3 min	确认部署参数
⑦ 日志排查	按需	手动触发测试
⑧ 创建 MR	~2 min	确认 MR 信息
⑨ AI 辅助评审	~3 min	审核 AI 评审意见，决定提交哪些
⑩ 修复评审意见（2 条）	~3 min	确认修复方案

整个流程走下来，开发者的工作方式发生了比较大的变化：

传统方式	Claude Code 方式
打开 PM 页面创建需求，手动建分支	口述需求，自动创建需求单和分支
自己拆解任务、逐个实现	AI 制定计划、子 Agent 并行执行、自动 commit
手动 dtools 部署，排查实例名过期	AI 自动检测过期配置并修正
手动写 MR 描述，对照 commit 逐条整理	AI 分析全部 commit 自动生成规范描述
在GitPlatform页面逐条看评审、手动改代码	AI 拉取评论、定位代码、生成修复、自动提交

说到底，这就是 Agentic Engineering 的核心理念——人是编排者（Orchestrator），AI 是自主执行者：

• 人负责：定义目标、拆解任务、审核方案、把关质量、最终决策——方案选择、计划审核、部署确认、评审把关、合入发布

• AI 负责：在结构化流程中自主执行——代码生成、commit 格式化、MR 描述整理、评审意见定位、日志分析……这些重复性高、规则明确的工作

Skill/Command 体系就是那个"结构化流程"——brainstorming 确保先理解再动手，writing-plans 确保先计划再执行，code-review 确保有检查清单而非凭感觉审查。它们把 AI 的能力约束在可控的工程框架里，而不是让 AI 自由发挥然后祈祷结果正确。

这和 Vibe Coding 的本质区别在于：Vibe Coding 依赖运气，Agentic Engineering 依赖流程。每个关键节点都有人工审核，AI 是高效的执行者，不是不受控的自动机。

Skill & Command 的协作架构

理解了全流程之后，来看看这套工具链内部是怎么协作的。整个体系可以用一张依赖图表达：

几个设计上的关键决策：

• Command 是薄壳：每个 /xxx 命令只有一行——委托给 git-workflow 对应模块执行。所以你在对话中说"帮我提交代码"也能触发 commit 流程，不一定非得打 /commit。

• Skill 之间可组合：pm-dev 创建完需求单后自动调用 brainstorming，brainstorming 完了接着调 writing-plans。git-workflow 的每个模块都复用 git-context 做前置准备。组合优于重复实现。

• Superpowers 管纪律：brainstorming 确保 AI 先理解再动手；writing-plans 确保先计划再执行；executing-plans 确保按步骤推进而不跳跃。这些不是"可选的好习惯"，而是写进 Skill 定义的强制流程。

• MCP 对用户透明：你不需要知道"调用GitPlatform API 创建 MR"这件事——Skill 通过 MCP 自动完成，你只看到"MR 已创建，链接是 xxx"。

附录

本文涉及的工具速查

工具	类型	对应阶段	一句话说明
pm-dev	Skill	① 需求获取	解析 PM URL 或自动创建需求单，初始化开发分支
brainstorming	Superpowers	② 需求澄清	交互式需求探索，先理解再动手
writing-plans	Superpowers	③ 制定计划	深入代码生成精确的多 Task 实施计划
executing-plans	Superpowers	④ 并行开发	按步骤执行计划，支持子 Agent 并行
/commit	Command	④ 并行开发	智能生成 Conventional Commits 格式的 commit
code-review	Skill	⑤ 代码自审	Golang 审查，4 级严重度 × 8 类标签
dtools	Skill	⑥ 编译部署	DevOps 平台 CLI，自动探测参数并交叉编译
galileo-log-query	Skill	⑦ 日志排查	Galileo日志查询，支持多条件过滤
/create-mr	Command	⑧ 创建 MR	分析 commit 自动生成 MR 标题/描述
/review-mr	Command	⑨ AI 评审	行级代码评审，精确提交评论到GitPlatform
/fix-mr	Command	⑩ 修复意见	拉取未解决评论，逐条修复并回复
git-context	Skill	⑧⑨⑩	GitPlatform项目上下文提取，被多个工具复用

完整的 Skill/Command/Plugin 列表和配置说明，见配置仓库。

AI 代码评审案例

拿一个比本文示例更复杂的 MR（4 个文件，+252 行）来看，AI 审查出了 9 个问题：

级别	数量	典型问题
Critical	1	HTTP 下载无超时控制，goroutine 可能永久阻塞
Major	4	竞态窗口、重复读配置、缺少 HTTP 状态码
Minor	2	错误封装不规范、不必要的导出字段
Suggestion	2	切片预分配、handler 文件拆分

reviewer 审阅后调整了 AI 的部分建议（如将 C1 改为"建议使用 trpc-go http client 代替 net/http"），然后提交了 7 条评论到GitPlatform。

MCP 服务配置

以下 MCP 服务为 Skill 提供外部平台的数据和操作能力，配置一次全局生效：

MCP 服务	用途	依赖的 Skill
GitPlatform MCP	Git 仓库操作、MR 管理	git-workflow 、git-context
PM MCP	需求/缺陷/任务管理	pm-dev 、git-workflow
InternalWiki MCP	Wiki 文档搜索与管理	wiki-doc
Galileo MCP	日志查询与分析	galileo-log-query
KnowledgeBase MCP	知识库语义+关键词检索	brainstorming 阶段补充技术背景

具体的 MCP 配置命令和 Token 获取方式，见配置仓库。

配置目录结构

~/.claude-internal/              # Claude Code 全局配置目录
├── CLAUDE.md                    # 全局指令（操作原则、代码规范、偏好设置）
├── settings.json                # 权限白名单、模型选择、启用插件
├── commands/                    # 自定义斜杠命令（/commit, /create-mr, /review-mr, /fix-mr 等）
└── skills/                      # 技能库（pm-dev, git-workflow, code-review, dtools 等）

完整的 Skill/Command/Plugin 列表、官方插件配置、目录详情，均见配置仓库。

作者：yabohe

年初火爆现在热度依旧的OpenClaw为AI Agent带来了新的想象。如果说2025是AI Agent智能体元年，想必2026将会是AI Agent真正商用化的开端，而AI Agent商用化的前提是各行各业开始落地实际商业领域的AI Agent。

作为一名程序员/工程师，思考的更多的可能是如何将AI Agent落地实现的层面。工程框架往往是工程应用实现的基石，框架选型也是架构师们设计与实现一个AI Agent智能体的首要工作。

一、AI Agent 框架理论篇

Agent = Reasoning + Acting

1.1 AI Agent 框架基础理论

AI 智能体是使用 AI 来实现目标并代表用户完成任务的软件系统。其表现出了推理、规划和记忆能力，并且具有一定的自主性，能够自主学习、适应和做出决定。

Google Cloud

关于AI Agent这里引用了Google Cloud的定义，言简意赅。

1）ReAct 模式

在当前AI Agent理论中，最具有基础性与代表性的要数ReAct模式，它是Yao等人于2022年在《ReAct: Synergizing Reasoning and Acting in Language Models》论文中提出，核心思想将推理（Reasoning）和行动（Acting）相结合。CoT提升的是LLM的推理能力，但它的缺点在于缺少与外部世界的交互从而缺少外部反馈来拓展自身的知识空间，ReAct弥补了这一缺陷。

ReAct智能体的运作基于一个循环过程（不断迭代更新），包括以下三个步骤：

• 推理（Reasoning）：依赖LLM，分析当前任务状态，生产内部推理，决定下一步行动，核心思想是CoT（Chain of Thought）

• 执行（Acting）：根据上一步的推理结果，执行具体的操作，例如查询信息或调用外部工具（Function Tool，MCP， Shell命令，代码执行等），具体依赖宿主机的执行环境与应用场景

• 观察（Observation）：观察行动的结果，将反馈用于下一轮的思考；或者观察到已经判断是最终的答案，则整理输出结果

2）Plan-and-Execute 模式

2023年5月，Langchain团队基于Lei Wang等发表的《Plan-and-Solve Prompting》论文和开源的BabyAGI Agent项目的工作，提出了Plan-and-Execute 模式。

• 《Plan-and-Solve Prompting》核心思想：让LLM先制定完整的分步计划，再按步骤执行，而非边做边想（ReAct）

• BabyAGI项目：首个流行的任务驱动型自主Agent，实现了"生成任务列表→执行→再规划"的Agent Loop

Plan-and_Execute模式强调先制定多步计划，再逐步执行，属于结构化工作流程（Planing -> Task1 -> Task2 -> Task3 -> Summary），比较适合复杂且任务关系以来明确的长期任务。缺点则是倾向于workflow，缺乏动态调整能力。

3）Reflection 模式

最早系统性的提出在Agent中引入反思概念的是Noah Shinn、Shunyu Yao（对，还是ReAct作者）等的《Reflexion: Language Agents with Verbal Reinforcement Learning》论文，论文里提出了Reflexion框架，通过语言反馈而非权重更新来强化语言Agent。Agent通过对任务反馈信号进行 口头反思，然后在情节记忆缓冲区中维护自己的反思文本，以在后续试验中做出更好的决策。

另外，Aman Madaan等受人类改进文本方式的启发，在《Self-Refine: Iterative Refinement with Self-Feedback》论文提出了一种名Self-Refine的方法，通过迭代反馈和改进来提升 LLM 的初始输出：先让LLM输出，然后再根据输出提供反馈，不断迭代。在所有评估的任务中Self-Refine方法可以使得任务性能平均提升约 20%。

清华大学与微软联合发布的《CRITIC: Large Language Models Can Self-Correct with Tool-Interactive Critiquing》论文则结合外部工具（如搜索引擎、代码执行器）验证输出，再基于验证结果自我修。

这些里程碑论文都是Reflection模式的理论基础，当前主流的Agent框架虽然有各种演绎与变形，也都是在ReAct提出之后发展出来的扩展和补充，Agent核心实践依旧离不开ReAct：将推理与执行结合起来。

1.2 主流 AI Agent 框架对比

当前主流Agent框架主要包含以下几种：

• LangChain - 最成熟和流行的框架之一，提供丰富的工具链和集成，适合快速构建复杂的AI应用。支持多种LLM、向量数据库和工具调用，有完善的文档和社区支持。

• LlamaIndex - 专注于数据索引和检索，特别擅长RAG（检索增强生成）场景。提供高效的文档处理和查询能力，适合知识密集型应用。

• AutoGPT/AutoGen - 微软推出的多Agent协作框架，支持多个Agent之间的对话和协作，可以处理更复杂的任务分解和执行。

• CrewAI - 专注于角色扮演型Agent的协作框架，每个Agent有明确的角色和目标，适合模拟团队协作场景。

• LangGraph - LangChain团队开发的状态图框架，提供更精细的流程控制，适合构建复杂的、需要明确状态管理的Agent应用。

• Semantic Kernel - 微软的轻量级框架，与Azure服务集成良好，支持多种编程语言，强调插件化设计。

选择建议

• 如果是想快速出Agent原型，可以试试LangChain；

• 如果是构建RAG应用，则强烈建议LlamaIndex；

• 如果业务场景为多Agent协作，推荐AutoGen或CrewAI，它们是专为多智能体协作而生的；

• 如果业务中涉及复杂的流程控制，建议使用LangGraph，通用性好，基于状态管理的workflow灵活性高；

• 如果工作环境围绕.NET生态展开的，那搭配Semantic Kernel是最佳选项。

另外，随着Anthropic公司的Claude Cowork AI通用Agent兴起，一些基于通用Code Agent SDK的套壳Agent也开始流行（如公司CodeBuddy团队基于CodeBuddy Agent SDK等生成的WorkBuddy应用），这些Agent的创新之处在于可以针对各类用户场景提供更好的交互设计与工作流场景解决方案。

1.3 AI Agent 框架核心

在Agent应用发展与实践过程中，有一家公司的一款Agent应用不得不提，那就是AI初创公司Monica发布的Agent C端产品：Manus，它的爆火让让Agent产品进入大众视野。

• 在Agent产品人机交互方面：它模糊地勾勒出了Agent应用的人机交互的雏型。想象一下，键盘和鼠标的出现，第一代iPhone的出现，回过头来看都是变革性的历史事件。

• 在Agent工程实践方面：当MCP风靡一时时，Manus首席科学家Peak在社交媒体直接回复"Actually, Manus doesn't use MCP"；4个月后（2025年7月），Manus工程博客发表《AI Agent的上下文工程：构建Manus的经验教训》，分享Manus为何放弃微调（Fine-tuning）路线，转而选择基于已有通用大模型深耕上下文工程（Context Engineering），其中的一条经验教训为：使用文件系统作为上下文。3个月后，Anthropic 在2025年10月推出Claude Skills，从此"使用文件系统作为上下文"的理念开始深入人心。

"Actually, Manus doesn't use MCP"还有后半句："inspired by CodeAct"。CodeAct是一个Agent设计架构，来自于UIUC的王星尧博士在2024年初发表的一篇论文《Executable Code Actions Elicit Better LLM Agents》，它提出通过生成可执行的Python代码来统一LLM Agent的行动空间，也就是Acting不仅可以有Fucntion Call和MCP，还可以执行代码完成任务，而且效果更好。2025年11月，Anthropic官方博客更新技术文章《Code execution with MCP: Building more efficient agents》，提出将 MCP 服务器作为代码 API（而非直接的工具调用）来提供，然后，Agent就可以编写代码来与 MCP 服务器交互，这样Agent可以按需加载，更高效地利用上下文。CodeAct这个观点与本文开头的Shunyu Yao的"人类最重要的 affordance 是手，而 AI 最重要的 affordance 可能是代码"也不谋而合。

从Manus的故事，我们可以得出当前关于Agent工程的两大业内共识：

• 使用文件系统作为上下文（如使用文件保存Agent长期记忆，如OpenClaw的SOUL.md/TOOLS.md/MEMORY.md等）

• 编程是解决通用问题的一种普适方法（AI更擅长使用代码解决问题：问题->生成代码->执行代码->Again->直到问题解决）

虽然当前Agent框架发展从ReAct模式逐渐融合CodeAct模式，但是Agent框架本质的推理与执行功能并没有变化。

在工程层面来说，推理本质就是LLM Call，执行本质则是Tools Call（代码可认为是Tools的一种），而连接这二者的上下文工程（Context Engineering）则是Agent框架的核心。

1.3.1 Agent 框架三大部分

下面我们来拆解一下Agent框架在工程上的解法，主要包括三大部分

• LLM Call：这部分为API管理的范畴，通常情况下，主要工作是兼容各大LLM厂商的API实现细节以及流式输出等基础能力，为Agent框架提供一个标准化的API调用。

• Tools Call：这部分主要是LLM如何使用外部工具，从最早的Function Call到后来的MCP以及当前的Skill部分内容（涉及工具调用的那部分）都属于这一范畴。当前Tools的主流形式包括文件操作、网络搜索、Shell命令/代码执行以及API/MCP调用等，根据Agent具体使用场景而定，也可以后续增删改。

• Context Engineering：狭义的上下文工程特指提示词Prompt的工程实现（如Rules、Claude.md以及AGENTS.md等），而广义上的上下文工程其实也包含LLM使用外部工具这部分（比如Skills，它是工具与提示词结合的典范）。

以上Agent三大部分中，第1部分的LLM Call基本上没有啥工程变量，这块的工程实践中LiteLLM库（它是一个Python 库，旨在简化多种大型语言模型（LLM）API 的集成）已经是佼佼者了；第2部分的Tools使用，包含的工具列表范围也有业内最佳实践，具体取决于Agent使用的业务场景。

剩下的最大的一个变量是第3部分的上下文工程，这也是Agent框架智能的核心所在。OpenClaw的爆火出圈除了将手机即时应用与Agent结合这点之外，它的上下文工程的管理也非常有创新。

近日，Shunyu Yao团队在腾讯混元官网发表了一篇名为《从 Context 学习，远比我们想象的要难》的文章，提出“模型想要迈向高价值应用，核心瓶颈就在于能否用好 Context。”的观点。正如文中所言"在不提供任何 Context 的情况下，最先进的模型 GPT-5.1 (High) 仅能解决不到 1% 的任务"。如果说Agent应用中，现在哪里还是低垂的果实可以摘取，那可能是上下文工程（Context Engineering）。

简单总结为一句话：Agent应用中上下文工程大有可为（仍有很大优化空间）。

1.3.2 Agent Loop

在1.3.1小节中我们讨论了Agent框架的核心是上下文工程，而上下文工程的核心引擎或者称之为运行框架则是Agent Loop。

Agent Loop也不神秘，本质是一个While循环，每一次迭代是一次LLM推理外加工具调用和上下文处理，也就是说所有Agent行为的发生都是在这个While循环里面，直到任务完成退出。

典型的工作流程如下：

初始上下文（系统提示词+用户请求）
    ↓
[agent loop开始]
    ↓
agent读取上下文 → 思考 → 决定行动
    ↓
执行工具/行动 → 获得结果
    ↓
结果追加到上下文
    ↓
[循环继续或结束]

细分到While循环到每一次迭代（Turn）可简单表示为：

初始化上下文（用户请求）
  ↓
┌─────────────────────────────────┐
│  Agent Loop                     │
│                                 │
│  ┌─────────────────────┐        │
│  │ Turn 1              │        │
│  │  LLM Call 推理 #1            │
│  │  → 解析LLM响应        │        │
│  │  → 执行工具1          │        │
│  │  → 返回结果，更新上下文 │        │
│  └─────────────────────┘        │
│           ↓                     │
│  ┌─────────────────────┐        │
│  │ Turn 2              │        │
│  │  LLM Call 推理 #2    │        │
│  │  → 执行工具2          │        │
│  │  → 返回结果，更新上下文 │        │
│  └─────────────────────┘        │
│           ....                  │
└─────────────────────────────────┘
  ↓
完成(当某一次Turn不再执行工具即表示完成，返回所有结果信息）

Agent Loop通过在每次迭代中读取、利用和更新上下文来完成任务；上下文工程则是设计如何组织、管理和优化这些上下文信息以提升Agent的决策质量和效率。

回到本节的主题，可总结为一句话：Agent框架设计的核心就是在Agent Loop这个While循环中设计如何管理上下文。

二、AI Agent 框架实践篇

承接上篇：Agent框架设计的核心是在Agent Loop这个While循环中设计如何管理上下文，本篇即围绕这个核心论点展开。

2.1 Agent 框架架构图一览

┌─────────────────────────────────────────────────────────────────────┐
│                User Interface（CLI REPL Layer ）                     │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────────────────┐ │
│  │  User Input  │   │    Exit/     │   │   Message History        │ │
│  │   Handler    │   │   Clear Cmd  │   │   Management             │ │
│  └──────┬───────┘   └──────────────┘   └──────────────────────────┘ │
│         │                                                           │
│         ▼                                                           │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                      Agent Loop Core                         │   │
│  │  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │   │
│  │  │   LLM Call   │───▶│ Tool Call    │───▶│   Tool Exec  │   │   │
│  │  │   (DeepSeek) │    │   Parser     │    │   Engine     │   │   │
│  │  └──────────────┘    └──────────────┘    └──────────────┘   │   │
│  │         │                                              │     │   │
│  │         │◀─────────────────────────────────────────────┘     │   │
│  │         │ (Tool Results Feedback)                            │   │
│  │         ▼                                                    │   │
│  │  ┌──────────────┐    ┌──────────────┐                       │   │
│  │  │   Response   │───▶│   Context    │                       │   │
│  │  │   Formatter  │    │   Manager    │                       │   │
│  │  └──────────────┘    └──────────────┘                       │   │
│  └──────────────────────────────────────────────────────────────┘   │
│                              │                                      │
│                              ▼                                      │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    Tools Registry (TOOLS)                    │   │
│  │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐            │   │
│  │  │ shell_  │ │ file_   │ │ file_   │ │ python_ │            │   │
│  │  │ exec    │ │ read    │ │ write   │ │ exec    │            │   │
│  │  └─────────┘ └─────────┘ └─────────┘ └─────────┘            │   │
│  │      │            │            │            │                │   │
│  │      ▼            ▼            ▼            ▼                │   │
│  │  [Function]   [Function]   [Function]   [Function]          │   │
│  │  [Schema]     [Schema]     [Schema]     [Schema]            │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

再review一下工作流：

初始上下文（系统提示词+用户请求）
    ↓
[agent loop开始]
    ↓
agent读取上下文 → 思考 → 决定行动
    ↓
执行工具/行动 → 获得结果
    ↓
结果追加到上下文
    ↓
[循环继续或结束]

2.2 Agent 框架三大要素设计

2.2.1 LLM Call

采用极简设计，以DeepSeek模型示例说明

• LLM Provider：使用DeepSeek deepseek-chat 模型

• LLM Call API：使用标准化OpenAI SDK

为保证代码的最大可读性，这里使用同步非流式调用。

2.2.2 Tools Call

采用极简的工具集，操作对象包含文件、Shell和Python代码执行

1）Tools 实现：总共支持4个工具函数

• shell_exec：执行shell命令并返回输出

• file_read：读取文件内容

• file_write：写入文件内容（自动创建目录）

• python_exec：在子进程中执行Python代码并返回输出

2）Tools 注册：这里选择的是手动维护字典映射的方式 name → (function, OpenAI function schema) ，这一步是为了解析llm call 的response时可以根据name匹配需要具体执行哪个tool

Tools 的定义遵循的是 OpenAI Function Calling 的标准格式（也称 OpenAI Tools API schema）

2.2.3 Context Engineering

• System Prompt：极简系统提示词，告知LLM可用工具和ReAct思考方式

• 用户Session管理：使用messages 列表方式（OpenAI chat 格式），它是核心状态，累积系统提示词、用户消息、助手响应和工具结果

2.3 Agent 框架代码实现

2.3.1 第一部分：Agent Loop 与 上下文

• 基础流程： LLM call → parse tool_calls → execute → append results to messages → loop or exit

• 安全设置：为while循环设置了一个迭代的安全上限：20 轮（MAX_TURNS=200）

• 使用全局变量message作为上下文的载体，累积系统提示词、用户消息、助手响应和工具结果

其中，变量message按如下规则更新

• 使用System Prompt初始化：{"role": "system", "content": system_prompt}

• 追增User Message：{"role": "user", "content": user_message}

• 追加Tool Results：{"role": "tool", "content": result}

# ============================================================
# Agent Loop — 核心
# ============================================================
MAX_TURNS = 20
defagent_loop(user_message: str, messages: list, client: OpenAI) -> str:
"""
    Agent Loop：while 循环驱动 LLM 推理与工具调用。
    流程：
      1. 将用户消息追加到 messages
      2. 调用 LLM
      3. 若 LLM 返回 tool_calls → 逐个执行 → 结果追加到 messages → 继续循环
      4. 若 LLM 直接返回文本（无 tool_calls）→ 退出循环，返回文本
      5. 安全上限 MAX_TURNS 轮
    """    messages.append({"role": "user", "content": user_message})
    tool_schemas = [t["schema"] for t in TOOLS.values()]
for turn in range(1, MAX_TURNS + 1):
# --- LLM Call ---
        response = client.chat.completions.create(
            model="deepseek-chat",
            messages=messages,
            tools=tool_schemas,
        )
        choice = response.choices[0]
        assistant_msg = choice.message
# 将 assistant 消息追加到上下文
        messages.append(assistant_msg.model_dump())
# --- 终止条件：无 tool_calls ---
ifnot assistant_msg.tool_calls:
return assistant_msg.content or""
# --- 执行每个 tool_call ---
for tool_call in assistant_msg.tool_calls:
            name = tool_call.function.name
            raw_args = tool_call.function.arguments
            print(f"  [tool] {name}({raw_args})")
# 解析参数并调用工具
try:
                args = json.loads(raw_args)
except json.JSONDecodeError:
                args = {}
            tool_entry = TOOLS.get(name)
if tool_entry isNone:
                result = f"[error] unknown tool: {name}"
else:
                result = tool_entry["function"](**args)
# 将工具结果追加到上下文
            messages.append(
                {
"role": "tool",
"tool_call_id": tool_call.id,
"content": result,
                }
            )
return"[agent] reached maximum turns, stopping."

注：这里使用的模型为deepseek-chat，主要考量因素是模型支持Tool Calls，并且完全兼容OpenAI的SDK。

2.3.2 第二部分：Tools 实现与注册

这里主要实现四个工具函数: shell_exec, file_read, file_write, python_exec

# ============================================================
# Tools 实现 — 4 个工具函数
# ============================================================
defshell_exec(command: str) -> str:
"""执行 shell 命令并返回 stdout + stderr。"""
try:
        result = subprocess.run(
            command,
            shell=True,
            capture_output=True,
            text=True,
            timeout=30,
        )
        output = result.stdout
if result.stderr:
            output += "\n[stderr]\n" + result.stderr
if result.returncode != 0:
            output += f"\n[exit code: {result.returncode}]"
return output.strip() or"(no output)"
except subprocess.TimeoutExpired:
return"[error] command timed out after 30s"
except Exception as e:
returnf"[error] {e}"
deffile_read(path: str) -> str:
"""读取文件内容。"""
try:
with open(path, "r", encoding="utf-8") as f:
return f.read()
except Exception as e:
returnf"[error] {e}"
deffile_write(path: str, content: str) -> str:
"""将内容写入文件（自动创建父目录）。"""
try:
        os.makedirs(os.path.dirname(path) or".", exist_ok=True)
with open(path, "w", encoding="utf-8") as f:
            f.write(content)
returnf"OK — wrote {len(content)} chars to {path}"
except Exception as e:
returnf"[error] {e}"
defpython_exec(code: str) -> str:
"""在子进程中执行 Python 代码并返回输出。"""
try:
with tempfile.NamedTemporaryFile(
            mode="w", suffix=".py", delete=False, encoding="utf-8"
        ) as tmp:
            tmp.write(code)
            tmp_path = tmp.name
        result = subprocess.run(
            [sys.executable, tmp_path],
            capture_output=True,
            text=True,
            timeout=30,
        )
        output = result.stdout
if result.stderr:
            output += "\n[stderr]\n" + result.stderr
return output.strip() or"(no output)"
except subprocess.TimeoutExpired:
return"[error] execution timed out after 30s"
except Exception as e:
returnf"[error] {e}"
finally:
try:
            os.unlink(tmp_path)
except OSError:
pass

工具实现好了下一步就是注册，方便Agent Loop可以根据LLM的返回结果执行具体的工具方法（实际上就是一个字典映射name → {function, OpenAI schema}）

# ============================================================
# Tools 注册 — name → (function, OpenAI function schema)
# ============================================================
TOOLS = {
"shell_exec": {
"function": shell_exec,
"schema": {
"type": "function",
"function": {
"name": "shell_exec",
"description": "Execute a shell command and return its output.",
"parameters": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "The shell command to execute.",
                        }
                    },
"required": ["command"],
                },
            },
        },
    },
"file_read": {
"function": file_read,
"schema": {
"type": "function",
"function": {
"name": "file_read",
"description": "Read the contents of a file at the given path.",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute or relative file path.",
                        }
                    },
"required": ["path"],
                },
            },
        },
    },
"file_write": {
"function": file_write,
"schema": {
"type": "function",
"function": {
"name": "file_write",
"description": "Write content to a file (creates parent directories if needed).",
"parameters": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "Absolute or relative file path.",
                        },
"content": {
"type": "string",
"description": "Content to write.",
                        },
                    },
"required": ["path", "content"],
                },
            },
        },
    },
"python_exec": {
"function": python_exec,
"schema": {
"type": "function",
"function": {
"name": "python_exec",
"description": "Execute Python code in a subprocess and return its output.",
"parameters": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Python source code to execute.",
                        }
                    },
"required": ["code"],
                },
            },
        },
    },
}

Tools 的定义遵循的是 OpenAI Function Calling 的标准格式（也称 OpenAI Tools API schema）。

具体来说，Agent 中每个工具的 schema 字段的结构如下：

{
"type": "function",
"function": {
"name": "...",
"description": "...",
"parameters": {
"type": "object",
"properties": { ... },
"required": [ ... ],
          },
      },
  }

2.3.3 第三部分：System Prompt

这里定义System Prompt，每一次与LLM交互都需要带上它。

# ============================================================
# System Prompt
# ============================================================
SYSTEM_PROMPT = """You are a helpful AI assistant with access to the following tools:
1. shell_exec — run shell commands
2. file_read — read file contents
3. file_write — write content to a file
4. python_exec — execute Python code
Think step by step. Use tools when you need to interact with the file system, \
run commands, or execute code. When the task is complete, respond directly \
without calling any tool."""

明确告知：你是一个AI助手，当需要的时候可以使用哪些工具。

至此一个极简的Agent框架就此实现完成，单文件搞定，全部代码279行。

2.4 基于极简 Agent 框架的极简 Agent 应用

2.4.1 用户交互界面设计 - Python CLI REPL

框架实现完成之后，距离Agent应用就剩下最后一个用户交互界面了。

避免增加读者认知负担，从极简思想出发，这里使用Python CLI REPL 即Python的交互式命令行作为Agent的入口：

defmain():
    api_key = os.environ.get("DEEPSEEK_API_KEY")
ifnot api_key:
        print("Error: please set DEEPSEEK_API_KEY environment variable.")
        sys.exit(1)
    client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
    messages: list = [{"role": "system", "content": SYSTEM_PROMPT}]
    print("Agent ready. Type your message (or 'exit' to quit, 'clear' to reset).\n")
whileTrue:
try:
            user_input = input("You> ").strip()
except (EOFError, KeyboardInterrupt):
            print("\nBye.")
break
ifnot user_input:
continue
if user_input.lower() == "exit":
            print("Bye.")
break
if user_input.lower() == "clear":
            messages.clear()
            messages.append({"role": "system", "content": SYSTEM_PROMPT})
            print("(context cleared)\n")
continue
        reply = agent_loop(user_input, messages, client)
        print(f"\nAgent> {reply}\n")

2.4.2 DeepSeek 注册，获取 API Key

由于本文Agent框架的LLM Provider是基于DeepSeek实现的，所以需要获取DeepSeek模型（deepseek-chat模型）的API key才能使用。

• 注册： https://platform.deepseek.com

• 获取API Keys： https://platform.deepseek.com/api_keys

2.4.3 极简 Agent 应用体验

使用之前设置API key

export DEEPSEEK_API_KEY="sk-xxxxx"

先来问候一下：

输出的基本上是System Prompt中的内容，符合预期。

1）第1个问题

帮我查一下当前目录都有哪些文件

2）第2个问题

让它执行一个统计任务：帮我统计下当前目录下的代码行数以及token数

可以看到Agent Loop里在持续地调用Tools、写代码以及执行代码

最终的统计结果：

做完任务，使用exit命令退出当前session

可以看到实现的Agent应用，虽然实现极简，但是功能可以一点不简单（当Agent拥有文件读写权限，外加Shell工具以及代码生成与执行权限，它在本机上真的可以"为所欲为")。

要知道OpenClaw的底层Agent Core（Pi Agent）的Tools层也是有且仅包含四个工具方法：读文件（Read）、写文件（Write）、编辑文件（Edit）、命令行（Shell），其他的丰富且强大能力均靠事件机制及Skills扩展而来。

三、写在后面的话

• 毫无疑问，当前极简版的AI Agent框架在程序健壮性、安全性、功能性（如流式输出）以及优雅性（如Tools注册）都有很大改进空间，但是不容否认的是它五脏俱全，简单清晰，可以帮助我们摒除那些复杂冗长的组件库，看清Agent的本质。

• 为什么需要极简？一方面是为了方便论述清楚Agent的关键点；另一方面是现实考量，代码库（本质也是文件）也将逐渐成为上下文工程的一部分，代码库越简单上下文越清晰（信息噪声越少），Agent则越智能。

• Agent框架之外，Agent应用之内，上下文工程是智能的核心（短期/长期记忆、主动/被动记忆、用户Session管理、动态RAG等等），也是Agent商业上应用的关键。框架提供基础工具，上下文工程提供环境，搭配商业领域的Skills，Agent就能发挥出巨大的潜力。

typedef struct {
    unsigned long val;
} swp_entry_t;

作者：charrli

前言

近期，某顶级 AI Agent 研究团队的一个工业级 Harness 项目源码在开发者社区中引起广泛关注。这个项目是一个基于 TypeScript 的 CLI 形态 AI Coding Agent，其工程规模和架构成熟度令社区印象深刻：

"REPL.tsx 单文件 875KB，我以为我看错了小数点。这不是代码，这是一部长篇小说。" — HN 评论

社区普遍认为，这份源码不仅仅展示了一个产品的实现细节，更像是一本关于如何构建工业级 AI Agent 的技术教科书。

这份源码的规模令人印象深刻——约 1,900 个文件、512,000+ 行代码，完整涵盖了一个工业级 AI Coding Agent 的全部实现细节。对于 AI Agent 的开发者来说，这不啻于拿到了一份由顶级团队验证过的"生产级架构蓝图"。

我们可以从中看到：

• 🧠 顶级团队如何设计一个 Agent Harness 的核心 Loop

• 🛡️ 工具系统的 fail-closed 安全模型如何实现

• ⚡ 50 万行代码级别的 CLI 应用如何做到亚秒级启动

• 🐝 多 Agent 编排（Agent Swarms）的工程实现方式

• 🎮 用 React 写终端 UI 到底是什么体验（答案是：875KB 的 REPL.tsx）

• 🥚 隐藏在代码深处的 Easter Eggs：宠物精灵、梦境系统、年度回顾...

本文将对这份源码进行全面架构拆解，从启动流程到查询引擎，从工具系统到权限模型，再到那些藏在角落里的惊喜彩蛋——最终提炼出构建顶级 Harness 工程的方法论。文章面向有经验的开发者，假设读者了解 TypeScript、React 和 LLM API 基础概念。

阅读指南：全文分为 8 个 Part，每个 Part 可独立阅读。如果时间有限，建议优先阅读 Part 4（查询引擎）和 Part 8（隐藏彩蛋）。如果你是架构师，Part 7 的方法论总结不容错过。

目录

• Part 1: 项目全景与技术选型

• Part 2: 启动流程 — 极致的性能工程

• Part 3: 工具系统 — 可扩展的能力基座

• Part 4: 查询引擎 — Agent Loop 的核心

• Part 5: 多 Agent 编排与任务系统

• Part 6: TUI 与用户体验工程

• Part 7: Harness Engineering — 从该项目看 2026 年最热工程范式

• Part 8: 隐藏彩蛋 — 藏在 50 万行代码里的浪漫

Part 1: 项目全景与技术选型

"50 万行 TypeScript，43 个工具，80 个斜杠命令——这不是一个 CLI 工具，这是一个操作系统。" — 某 HN 评论者

1.1 规模一览

先看几个震撼的数字——当社区第一次跑 cloc 看到结果时，很多人以为统计工具出了 bug：

指标	数据
TypeScript 源文件	~1,332 个 .ts + ~552 个 .tsx = 1,884 个文件
代码总行数	512,000+  行
最大单文件	screens/REPL.tsx  — 875 KB（约 25,000 行）
第二大文件	main.tsx  — 785 KB（约 4,684 行，编译后膨胀）
系统提示模板	constants/prompts.ts  — 53 KB
工具定义目录	src/tools/  — 43 个子目录，184 个文件
斜杠命令	src/commands/  — 101 个子目录/文件，80+ 个命令
React Hooks	src/hooks/  — 85 个文件
UI 组件	src/components/  — 144 个文件
Utility 函数	src/utils/  — 329 个文件

这是一个超大型 CLI 应用——它的代码量超过了大多数 Web 应用的前后端总和。

1.2 技术栈选型分析

在源码中翻看 package.json 和构建配置，你会发现一个有趣的现象——这不是一个"什么流行用什么"的技术栈，而是一个每个选型都能追溯到具体性能瓶颈的技术栈：

类别	选型	选型理由分析
运行时	Bun	相比 Node.js，Bun 的启动速度快 4-6 倍，且原生支持 TypeScript、内置 bundler。对 CLI 工具来说，启动速度是生死线
语言	TypeScript (strict)	50 万行代码没有类型系统是不可维护的。strict 模式确保类型安全
终端 UI	React + Ink	用 React 组件模型构建 TUI，复用 Web 生态的状态管理和组件化思想。但该项目内置了自己的 Ink 渲染引擎（src/ink/），而非使用 npm 上的 Ink 包
CLI 解析	Commander.js (extra-typings)	成熟、轻量、TypeScript 友好。extra-typings 插件提供完整的类型推导
Schema 校验	Zod v4	工具输入校验、配置校验、Hook schema 校验。Zod 的 TypeScript-first 设计与项目的类型优先理念一致
代码搜索	ripgrep	通过 GrepTool 提供极速代码搜索能力。ripgrep 是目前最快的正则搜索工具
协议	MCP SDK + LSP	MCP（Model Context Protocol）实现外部工具集成；LSP（Language Server Protocol）提供代码智能
API 客户端	官方模型 SDK	官方 SDK，直接调用模型 API，支持流式响应
遥测	OpenTelemetry + gRPC	行业标准的可观测性框架，但 延迟加载（~400KB OTel + ~700KB gRPC 按需导入）
特性标记	GrowthBook	支持 A/B 测试和渐进式发布。大量功能通过 feature() 门控
认证	OAuth 2.0 + JWT + macOS Keychain	企业级认证方案，Keychain 集成确保凭据安全存储

1.3 目录结构与模块划分

把 src/ 展开后的第一感觉是——这比很多中型 SaaS 公司的整个后端都大。但令人意外的是，它的组织方式却出奇地清晰：

src/
├── main.tsx                     # 主入口（Commander.js CLI 解析器）
├── QueryEngine.ts               # 查询引擎（LLM 交互核心）
├── query.ts                     # 查询循环（AsyncGenerator 实现）
├── Tool.ts                      # 工具类型定义与 buildTool 工厂
├── tools.ts                     # 工具注册表
├── commands.ts                  # 命令注册表
├── context.ts                   # 系统/用户上下文收集
├── cost-tracker.ts              # 费用追踪
│
├── entrypoints/                 # 入口点（cli.tsx, init.ts, mcp.ts, sdk/）
├── bootstrap/                   # 启动状态（state.ts 54KB — 全局原子状态）
├── tools/                       # 43 个工具实现（BashTool, FileEditTool...）
├── commands/                    # 80+ 斜杠命令（/commit, /review, /compact...）
├── services/                    # 外部服务集成（API, MCP, OAuth, 压缩...）
├── components/                  # 144 个 Ink UI 组件
├── hooks/                       # 85 个 React Hooks
├── screens/                     # 全屏 UI（REPL, Doctor, Resume）
├── state/                       # 状态管理（极简 Store 模式）
├── types/                       # TypeScript 类型定义
├── utils/                       # 329 个工具函数（最大的目录）
│
├── bridge/                      # IDE 桥接（VS Code, JetBrains 集成）
├── coordinator/                 # 多 Agent 协调器
├── tasks/                       # 任务系统（6 种 TaskType）
├── plugins/                     # 插件系统
├── skills/                      # 技能系统（Markdown 驱动的能力扩展）
├── memdir/                      # 持久化记忆管理
├── keybindings/                 # 键绑定系统
├── vim/                         # Vim 模式仿真
├── ink/                         # 内置 Ink 渲染引擎
├── query/                       # 查询管道（config, deps, stopHooks）
├── remote/                      # 远程会话管理
├── cli/                         # 非交互模式（print.ts 208KB）
├── migrations/                  # 配置迁移（11 个脚本）
├── buddy/                       # 伴侣精灵（Easter egg）
└── voice/                       # 语音输入支持

关键架构洞察：

1. 入口分层：entrypoints/cli.tsx → main.tsx → setup.ts，三层入口分别处理 fast-path、CLI 解析、会话初始化

2. 核心与外围分离：query.ts + QueryEngine.ts + Tool.ts 构成核心引擎，其他模块都是外围

3. utils 膨胀问题：src/utils/ 有 329 个文件、远超其他目录，说明工具函数缺乏进一步的模块化。utils/hooks.ts 单文件 156KB，是典型的"瑞士军刀"反模式

1.4 与同类工具的技术对比

将该项目与其他主流 AI Coding 工具进行对比：

维度	该项目	Cursor Agent	Aider	OpenHands
语言	TypeScript	TypeScript	Python	Python
运行时	Bun	Electron + Node	CPython	Docker
UI 方案	React/Ink (TUI)	Web (Electron)	纯终端	Web
Agent Loop	AsyncGenerator	未公开	同步循环	事件驱动
工具数量	43+ 内建 + MCP	~20	~10	~20
多 Agent	Agent Swarms + Coordinator	无	无	有限
插件系统	完整（插件 + 技能 + MCP）	无	无	有限
代码行数	512K+	未公开	~30K	~100K

该项目在工程复杂度上远超同类——它不只是一个 CLI 工具，而是一个完整的 Agent 平台。

1.5 设计洞察

从 Part 1 可以提炼出几个核心设计决策：

1. Bun 而非 Node.js：对 CLI 工具来说，冷启动性能是决定用户体验的第一要素。Bun 的启动速度优势和内置 bundler 的 dead code elimination（feature() 门控）使其成为最优选择

2. React 写终端 UI：虽然 875KB 的 REPL.tsx 令人窒息，但 React 的组件化和声明式 UI 确实适合构建复杂的交互界面。内置 Ink 引擎（而非依赖 npm 包）说明 团队需要对渲染层有完全的控制权

3. TypeScript strict 模式：50 万行代码的可维护性完全依赖类型系统。从 DeepImmutable<AppState> 到 z.infer<Input> 再到泛型 Tool<Input, Output, Progress>，类型贯穿了每一层

4. 极简自研 Store：没有使用 Redux/Zustand，而是用 34 行代码 实现了一个符合 useSyncExternalStore 契约的 Store（src/state/store.ts）。这对性能敏感的 CLI 应用来说是正确的选择——第三方状态库的 overhead 在这里是不可接受的

Part 2: 启动流程 — 极致的性能工程

CLI 工具的启动速度是用户体验的生死线。该项目为此设计了一套精密的分层启动架构，核心思想是：能不加载的就不加载，能并行的就并行，能延迟的就延迟。

"我做了个实验，agent --version 只要 12ms。作为对比，node --version 要 50ms。他们到底怎么做到的？" — @nicolo_ribaudo

2.1 四层启动链

graph TD
    A["cli.tsx<br/>入口分发"] -->|"--version"| B["直接输出<br/>零导入"]
    A -->|"--dump-system-prompt"| C["最小导入路径"]
    A -->|"--daemon-worker"| D["Worker 精简路径"]
    A -->|"其他"| E["main.tsx<br/>完整 CLI 初始化"]
    E --> F["init.ts<br/>全局单例初始化"]
    F --> G["setup.ts<br/>会话级设置"]
    G --> H["launchRepl()<br/>渲染 REPL"]

Layer 1: entrypoints/cli.tsx — 入口分发

这是进程的真正起点。它的核心设计是 Fast Path 优先——在加载任何重量级模块之前，先检查是否可以快速退出：

# Python 伪代码重构 -- 展示核心设计思路
# Fast Path: 零模块加载，直接输出版本号退出
if args[0] in ('--version', '-v'):
    print(f"{BUILD_VERSION} (Agent CLI)")  # 版本号在构建时内联
    sys.exit(0)

所有后续路径都使用延迟导入（lazy import），确保只加载当前路径需要的模块：

# Python 伪代码重构 -- 展示核心设计思路
# 每个路径只按需导入对应模块
if is_feature_enabled('DAEMON') and args[0] == '--daemon-worker':
from daemon.worker_registry import run_daemon_worker  # 延迟导入
await run_daemon_worker(args[1])
return

feature() 是 Bun bundler 的编译时特性门控——不激活的代码在构建时被完全剥离（Dead Code Elimination），不会出现在最终产物中。

Layer 2: main.tsx — 主入口（4,684 行）

这是 CLI 解析和 UI 渲染器初始化的核心。它在模块加载阶段并行启动三个耗时操作：

# Python 伪代码重构 -- 展示核心设计思路
# 这三个任务在所有后续 import 之前并行启动！
mark_checkpoint('main_entry')                          # 标记入口时间
mdm_task = asyncio.create_task(read_mdm_settings())    # 并行启动 MDM 子进程
keychain_task = asyncio.create_task(prefetch_keychain())# 并行启动 Keychain 双路读取

这是并行预取（Parallel Prefetch）模式：MDM 设置读取需要 spawn 一个子进程（plutil on macOS），Keychain 读取需要两次同步 spawn（OAuth token + legacy API key）。如果串行等待，这些操作会增加 ~65ms 启动延迟。通过在模块评估阶段就启动它们，这些 I/O 操作与后续 ~135ms 的 import 链并行执行。

Layer 3: entrypoints/init.ts — 全局初始化

使用 memoize 确保只执行一次（即使被多处 import）：

# Python 伪代码重构 -- 展示核心设计思路
@run_once  # 等价于 memoize，确保只执行一次
asyncdefinitialize():
    validate_configs()                        # 验证配置
    apply_safe_env_variables()                # 安全环境变量
    apply_extra_ca_certs()                    # TLS 证书（必须在首次握手前）
    setup_graceful_shutdown()                 # 优雅退出
# OpenTelemetry (~400KB) 此处延迟加载...
    configure_global_agents()                 # 代理配置
    start_loading_policy_limits()             # 组织策略限制
    preconnect_model_api()                    # API 预连接（仅建立 TCP，不发请求）

注意 preconnectModelApi() — 它在初始化阶段就建立 TCP 连接（不发送请求），这样当真正需要调用 API 时，TLS 握手已经完成。

Layer 4: setup.ts — 会话设置

处理会话级别的初始化，包括 Node.js 版本检查、Git worktree 创建、UDS 消息服务器启动、Hooks 配置快照等。

2.2 延迟加载策略

该项目对重量级模块采用极致的延迟加载：

模块	大小	策略
OpenTelemetry	~400 KB	延迟导入，到遥测初始化时才加载
gRPC (grpc-js)	~700 KB	OpenTelemetry exporter 进一步延迟
React/Ink 渲染	大量	非交互模式（-p）完全不加载
内部命令模块	insights.ts  113KB	懒加载 shim，用户执行 /insights 时才加载
Sentry	较大	is_feature_enabled()  特性开关，外部构建剥离

# Python 伪代码重构 -- 展示核心设计思路
# 懒加载 shim：命令定义是同步的，实际逻辑延迟到首次调用时导入
usage_report = {
"type": "prompt",
"name": "insights",
"get_prompt": lambda args, ctx: _lazy_load_insights(args, ctx),
}
asyncdef_lazy_load_insights(args, context):
from commands.insights import handler  # 首次调用时才导入 113KB 模块
returnawait handler.get_prompt(args, context)

2.3 设计洞察

1. Fast Path 模式：将最常用的快速操作（--version）放在最前面，零依赖直接返回。这在所有 CLI 工具中都应该是标配

2. 并行预取 vs 串行阻塞：Keychain、MDM、GrowthBook 的并行启动节省了关键路径上的 60-100ms

3. is_feature_enabled() 特性开关的 DCE：构建工具在构建时根据特性标记剥离整个代码块。这意味着外部用户拿到的构建产物中不包含内部工具（如 REPLTool、TungstenTool）

4. memoize 单例模式：init()、getCommands()、getUserContext() 等函数都用 memoize 包裹，确保重量级初始化只执行一次，后续调用直接返回缓存值

Part 3: 工具系统 — 可扩展的能力基座

工具系统是该项目的能力基座——模型通过工具与外部世界交互。这个系统的设计融合了类型安全、fail-closed 安全默认、条件编译三大理念。

"看完他们的 buildTool() 默认值设计，我回去把自己项目的权限系统全部重写了。Fail-closed 不是一个理念，是一种信仰。" — @LangChainDev

3.1 Tool 接口设计

每个工具都是一个实现了 Tool<Input, Output, Progress> 泛型接口的对象，定义在 src/Tool.ts（793 行）中：

# Python 伪代码重构 -- 展示核心设计思路
type Tool<
    Input extends AnyObject = AnyObject,
    Output = unknown,
    P extends ToolProgressData = ToolProgressData,
> =
    name: string
    inputSchema: Input                              # Zod v4 schema
    call(args, context, canUseTool, parentMessage, onProgress): Promise>
    description(input, options): Promise    # 动态描述
    checkPermissions(input, context): Promise
    validateInput?(input, context): Promise
    isEnabled(): boolean
    isReadOnly(input): boolean
    isConcurrencySafe(input): boolean
    isDestructive?(input): boolean
    maxResultSizeChars: number
# 渲染方法
    renderToolUseMessage(input, options): React.ReactNode
    renderToolResultMessage?(content, progress, options): React.ReactNode
# 安全分类器输入
    toAutoClassifierInput(input): unknown
# ** 更多方法