[转载] 认知重建：Speckit用了三个月，我放弃了——走出工具很强但用不好的困境

原文地址

2025 年 AI 编程工具遍地开花，但一个尴尬的现实是：工具越来越强，预期越来越高，落地却越来越难——speckit 的规范流程在企业需求的”千层套路”、海量代码面前显得理想化，上下文窗口频繁爆满让复杂任务半途而废，每次做类似需求还是要花同样的时间因为知识全在人脑里。本文记录了我从踩坑规范驱动工具，到借鉴 Anthropic 多 Agent 协作架构、融合上下文工程与复合工程理念，最终实现边际成本递减、知识持续复利的完整历程。如果你也在”AI 工具明明很强但就是用不好”的困境中挣扎，或许能找到一些共鸣。附带还有新的工作流下人的工作模式转变思考～

起点：规范驱动开发的美好承诺

1.0 团队的 AI Coding 起点

先交代一下背景：我所在的是一个后端研发团队，日常工作以存量项目迭代为主，涉及多个微服务的协作开发。

2024 年中，团队开始尝试 AI 辅助编程。最初的体验是：

短上下文场景效果不错：

• 写一个独立函数、实现一个工具方法——AI 表现良好
• 简单的代码补全、格式化、注释生成——确实提效

但规模化复用始终没起来：

• 当时只有三种触发类型的 rules（早期 rules 时代）
• 虽然提出过”在基础 agent 之上封装 agent”的想法
• 但几个月过去，仍然没有太多人真正动起来

原因分析：

• 规范没有形成共识——每个人对”怎么用好 AI”理解不同
• 对 AI 工程化没有标准认识——不知道该往哪个方向努力
• 提示词复用习惯没建立——好的 prompt 停留在个人经验，没有沉淀

这个困境促使我开始探索外部方案：有没有已经成熟的”AI 编程工程化”方法论？有没有可以直接借鉴的最佳实践？

带着这些问题，我遇到了 speckit 和 openspec。

遇见 speckit：AI 编程的”正确打开方式”？

2024 年开始，AI 编程助手如雨后春笋般涌现。Copilot、Cursor、Claude 让很多人第一次体验到了”AI 写代码”的魔力。但兴奋之后，问题也随之而来：

• AI 生成的代码质量参差不齐
• 需求理解经常偏离预期
• 缺乏持续性，上下文丢失严重
• 改一处坏十处，维护成本高

正当我被这些问题困扰时，遇到了 speckit——一个规范驱动开发（Spec-Driven Development, SDD）工具包。

speckit 的理念很吸引人：

1
2
3

规范即代码 → 规范直接生成实现，而非仅作为指导文档
权力倒置 → 代码服务于规范，而非规范服务于代码
测试优先 → 强制 TDD，不可协商地要求先写测试

它定义了一套清晰的 5 阶段流程：

1
2

Constitution → Specify → Plan → Tasks → Implement
   (宪章)      (规范)    (计划)  (任务)   (实施)

每个阶段对应一个命令，依次执行：创建项目宪章和开发原则 → 定义需求和用户故事 → 创建技术实现计划 → 生成可执行的任务列表 → 执行所有任务构建功能。

再加上 9 条不可变的架构原则（库优先、CLI 接口、测试优先、简洁性、反抽象…），7 层 LLM 输出约束机制，防止过早实现、强制标记不确定性、结构化自检…

这不就是 AI 编程的”工程化正确答案”吗？

带着这样的期待，我开始在项目中尝试落地。

openspec：另一种优雅的尝试

除了 speckit，我还研究了 openspec——一个更轻量的规范驱动框架：

1
2
3

Specs as Source of Truth → specs/ 目录始终反映系统当前真实状态
Changes as Proposals → 所有修改先以提案形式存在，经确认后实施
Lock Intent → AI 编码前通过明确规范锁定意图

openspec 的 Delta 机制设计得很巧妙：不同于直接存储完整的”未来状态”，它只存储变更操作本身（ADDED/MODIFIED/REMOVED/RENAMED）。归档时通过语义名称匹配来定位需求，避免了 Git Merge 常见的位置冲突问题。同时采用 Fail-Fast 机制，在写入前做完整冲突检测，保证不会产生半完成状态。

两个工具，两种风格，但都指向同一个目标：让 AI 编程更可控、更规范。

碰壁：理想流程遭遇企业现实

一个真实需求的”千层套路”

让我用一个真实的 12 月活动需求来说明问题：

协作复杂度：

• 跨 BG、跨前后端、跨 FT、跨项目、跨小组、跨服务
• 跨部门合作接口因合规要求变来变去，迟迟给不到位
• 雅典娜平台上接近 20 种商品类型，全得人工一个个配
• 活动流程必须按”玩法引擎”的方法论来拆解
• 技术方案得按习惯写在 iWiki 里

并行任务流：

1
2
3
4
5
6

同时处理：
├── 找产品确认商品细节
├── 找运营确认玩法逻辑
├── 找跨团队研发对齐接口
├── 找跨项目研发对齐交互
└── 内部技术方案评审

方案设计的”考古”需求：

• 某个商品创建、资产查看以前有什么坑？
• 现在的玩法能力有哪些？能不能直接用？
• 导航小结页到底是啥？怎么让它弹 Banner？

**写代码前的”九九八十一难”**：

1
2
3
4
5
6

前置任务链：
├── 玩法引擎：依赖数据、激励动作要在引擎仓库里实现
├── 外部依赖：关联的代码改动在其他服务里
├── 配置中心：要去阿波罗（Apollo）配配置
├── 雅典娜：商品场景得先配好（早期没数据还得 Mock）
└── 数据库：涉及表变更，得去测试环境操作

执行中的细节坑：

• 阿波罗配置有个坑，该怎么绕过去？
• 规则引擎的语法到底怎么写？
• 商品发放操作是重点，具体发到哪个钱包？

speckit 流程 vs 企业现实

把 speckit 的理想流程放到这个场景里：

1
2
3
4
5
6
7
8
9

speckit 假设的流程：
Constitution → Specify → Plan → Tasks → Implement
     ↓            ↓        ↓       ↓         ↓
  一次性定义   一次性写清   线性规划   任务分解   按序实施

企业现实：
多方博弈 → 动态调整 → 并行推进 → 持续扯皮 → 边做边改
    ↓          ↓          ↓          ↓          ↓
 需求会变   方案会改   依赖会卡   资源会抢   意外会来

核心矛盾：speckit 假设需求是清晰的、可一次性规划的，但企业真实需求是动态的、多方博弈的、持续变化的。

openspec 的 Delta 机制也救不了

openspec 的”提案→审查→归档”流程看起来更灵活，但：

• **假设需求可以”提案化”**：实际上外部接口因合规变来变去，5 个维度同时推进相互依赖，评审中发现问题需要立即改方案

• 人工介入成本高：Delta 与主 Spec 冲突时报错终止，复杂冲突需要人工解决，而人的认知窗口有限。具体来说，openspec archive 会在以下情况直接报错退出：

  • MODIFIED 引用的需求在主 Spec 中不存在（可能被别人删了或改名了）

  • ADDED 的需求在主 Spec 中已存在（别的分支先合入了同名需求）

  • RENAMED 的源名称不存在，或目标名称已被占用

  • 同一个需求同时出现在 MODIFIED 和 REMOVED 中（逻辑矛盾）

这些冲突没有自动解决策略，CLI 只会打印类似 MODIFIED failed for header "### Requirement: xxx" - not found 的错误信息，然后终止。你需要：手动打开两个文件对比、理解冲突原因、决定保留哪个版本、手工修改 Delta 文件、重新执行归档。整个过程要求你同时在脑中持有”主 Spec 当前状态”和”Delta 期望变更”两套信息——这对认知负担是很大的挑战

• 强依赖命名的脆弱性：产品叫”用户激励”，运营叫”活动奖励”，研发叫”商品发放”——同一个需求在不同阶段有不同表述

最致命的问题：无法应对”考古”需求

speckit 和 openspec 都有一个共同盲区：流程从零开始。

1
2
3
4
5
6
7
8
9

speckit 流程：
Constitution 定义原则 → Specify 定义需求 → Plan 设计方案 → ...

但真实需求必须"考古"：
├── 这个商品创建以前有什么坑？
├── 现有玩法能力有哪些？
├── 导航小结页的 Banner 怎么弹？
├── Apollo 配置有什么特殊处理？
└── 雅典娜 20 种商品类型的配置方式各不同

缺失能力：没有”上下文检索”机制，无法自动关联历史经验、已有能力、已知陷阱。

AI 生成 spec 时能看到的：

• ✅ 代码仓库
• ✅ project.md/Constitution
• ✅ 用户意图

AI 看不到（但需要知道）的：

• ❌ 业务边界（涉及哪些服务？）
• ❌ 历史经验（以前怎么做的？有什么坑？）
• ❌ 配置规范（Apollo 特殊要求？）
• ❌ 平台知识（雅典娜 20 种商品配置注意事项）
• ❌ 协作约束（依赖其他团队接口？合规要求？）

结果：依赖人 review 时逐步想起来告诉 AI，45 分钟 + 持续的认知负担。

AI 工程化如何破局？（预告）

面对上述问题，AI 工程化的解决思路是什么？这里先做个预告，详细方案见第五节。

核心差异：

1
2
3
4
5
6
7
8
9

speckit/openspec 的思路：
规范化流程 → 约束 AI 行为 → 期望产出质量
    ↓
问题：流程本身不适配企业现实，约束越多越僵化

AI 工程化的思路：
上下文完整性 → AI 决策质量 → 自动沉淀经验 → 下次更好
    ↓
解法：不是约束 AI，而是给 AI 完整信息 + 让知识复利

一个具体例子——同样是”商品发放”需求：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

speckit 模式（第 3 次做）：
1. Constitution → 写项目原则（已有，跳过）
2. Specify → 写需求规范（45 分钟，人逐步想起遗漏告诉 AI）
3. Plan → 写技术方案（人提醒：Apollo 有坑、钱包要区分）
4. Tasks → 生成任务（人补充：雅典娜配置注意事项）
5. Implement → 执行（遇到问题再排查）
耗时：45 分钟 + 排查时间，知识留在人脑

AI 工程化模式（第 3 次做）：
1. /req-dev "商品发放需求"
2. Agent 识别意图 → 自动加载 context/experience/商品发放历史问题.md
3. Agent 提醒："历史上有钱包选择、Apollo 配置、雅典娜商品类型三个坑点"
4. 人确认："对，继续"
5. Skill 执行 → 自动校验 → 生成代码 → 沉淀新发现
耗时：10 分钟，知识沉淀到 context/

后续章节将详细展开这套方案的设计原理和落地实践。

反思：从第一性原理重新审视

人的认知局限是刚性约束

实话实说，我的脑容量有限：

• 记性不好：只能记住关键的大方向，具体细节过脑就忘
• 专注窗口小：同时关注的信息有限，必须采用”专注单任务+全局索引”策略

我的日常工作模式（经过各种场景检验的最优路径）：

• 任务管理（外挂大脑）：Todo List 分优先级（红色紧急/黄色进行中/绿色完成/无色未开始）
• 备忘录：记录死记硬背的内容（打包命令、数据库 IP 密码、文档散落信息）
• 桌面即上下文：N 个桌面窗口，每个窗口对应一个垂直领域
• 复杂任务 SOP 化：脑内计划 + 执行机器模式 + 文档跟踪
• 简单任务 Fire and Forget：低频低思考成本事项秒回即忘

这套土办法是经过检验的最优路径。如果硬套 speckit/openspec 的范式，反而会丢掉这些 SOP，得不偿失。

执行过程的知识价值被忽视

speckit 和 openspec 都只关注”规范”（Spec）和”结果”（Code），忽视”过程”（Process）。

但真实价值恰恰在过程中：

1
2
3
4
5

执行 → 有问题 → 验证 → 排查 → 继续执行
                    ↓
            排查信息往往没被记录
                    ↓
        时间一久或换人，下次重新排查

这个循环中的排查信息，才是最宝贵的知识！

边际成本恒定是致命缺陷

1
2
3
4
5
6
7

Speckit 模式：
第 1 次商品发放需求：45 分钟（人逐步想起遗漏）
第 2 次商品发放需求：45 分钟（人 AGAIN 逐步想起遗漏）
第 n 次商品发放需求：45 分钟（还是要想，还是那么久）

边际成本恒定，无复利效应。
知识在哪里？在人脑里，每次都要重新想起来。

这与我期望的”越用越快”完全相反。

转折：遇见复合工程与上下文工程

复合式工程：让每一步都成为下一步的基石

在探索过程中，我接触到了”复合式工程”（Compounding Engineering）的理念。这个概念来自 Claude Code 团队与 Every 团队的实践交流，并在 Every 团队开源的 Compound Engineering Plugin 中得到了系统化实现——这是一个包含 27 个 Agent、19 个 Command、13 个 Skill 的完整 AI 辅助开发工具包。

定义”复合式工程”

“复合式工程”的核心目标非常明确：让每一单元的工程工作使后续工作变得更容易，而非更难。

1
2

传统开发：累积技术债务 → 每个功能增加复杂性 → 代码库越来越难维护
复合工程：每个功能产出文档模式 → 创建可复用组件 → 建立减少决策疲劳的约定 → 知识在团队中复合增长

与传统工程中每增加一个功能都会增加系统复杂度和维护成本不同，”复合式工程”追求的是一种”复利”效应，让系统的能力随着时间推移指数级增长。

核心工作流循环：Plan → Work → Review → Compound

Compound Engineering Plugin 设计了一个闭环的工作流循环：

1
2
3
4
5

Plan ──────→ Work ──────→ Review ──────→ Compound
详细规划     执行工作     质量检查       知识沉淀
   ↑                                       │
   └───────────────────────────────────────┘
            知识复合：下次规划更精准

• Plan：多代理并行研究仓库模式、最佳实践、框架文档，输出结构化计划
• Work：系统性执行计划，边做边测，质量内建
• Review：多代理并行审查（安全、性能、架构等），输出分级 Todo
• Compound：这是复合工程的核心——将解决的问题结构化记录，形成团队知识资产

完整实现参见：Compound Engineering Plugin

为什么叫”Compound”？

1
2
3
4
5
6

第一次解决 "N+1 query in brief generation" → Research (30 min)
文档化 → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
下次类似问题 → Quick lookup (2 min)
知识复合 → Team gets smarter

Each unit of engineering work should make subsequent units of work easier—not harder.

实现机制：知识复合的典型场景

实现复合工程的关键，在于建立系统化的知识沉淀机制。以下是几个典型场景：

场景 1：Agent 重复犯同类错误

1
2
3

触发：发现 Agent 在某类问题上反复出错
沉淀：将教训写入 AGENTS.md / CLAUDE.md / 系统提示词
效果：该类错误不再发生，无需人工提醒

场景 2：某类问题需要频繁人工检查

1
2
3

触发：Code Review 时反复指出同类问题
沉淀：创建 Lint 规则 / Pre-commit Hook / CI 检查
效果：问题在提交前自动拦截，减少人工负担

场景 3：复杂流程被多次执行

1
2
3

触发：某个多步骤操作被团队重复执行
沉淀：封装为 Skill / Command / Agent
效果：一键触发标准化流程，新人也能执行专家级操作

场景 4：解决了一个有价值的问题

1
2
3

触发：花了较长时间解决某个棘手问题
沉淀：结构化记录到 context/experience/ 目录
效果：下次遇到类似问题，Agent 自动加载相关经验

这些场景的共同特点是：在问题解决的当下立即沉淀，而不是事后补文档。

Claude 团队的复合工程应用案例

以下是 Every 团队和 Anthropic 内部使用复合工程的真实案例：

案例 1：”@claude，把这个加到 claude.md 里”

当有人在 PR 里犯错，团队会说：”@claude，把这个加到 claude.md 里，下次就不会再犯了。”或者：”@claude，给这个写个测试，确保不会回归。”通过这种方式，错误转化为系统的免疫能力。

案例 2：100% AI 生成的测试和 Lint 规则

Claude Code 内部几乎 100% 的测试都是 Claude 写的。坏的测试不会被提交，好的测试留下来。Lint 规则也是 100% Claude 写的，每次有新规则需要，直接在 PR 里说一句：”@claude，写个 lint 规则。”

案例 3：十年未写代码的经理

经理 Fiona 十年没写代码了，加入团队第一天就开始提交 PR。不是因为她重新学会了编程，而是因为 Claude Code 里积累了所有团队的实践经验——系统”记得”怎么写代码。

案例 4：内置记忆系统

把每次实现功能的过程——计划怎么制定的、哪些部分需要修改、测试时发现了什么问题、哪些地方容易遗漏——全部记录下来，编码回所有的 prompts、sub-agents、slash commands。这样下次别人做类似功能时，系统会自动提醒：”注意，上次这里有个坑。”

成果：一个自我进化的开发伙伴

这一范式带来的最终效果是惊人的。它将 AI 从一个被动执行命令的工具，转变为一个能够从经验中持续学习、并让整个开发流程效率不断”复利”增长的开发伙伴。

为什么这解决了古老的知识管理问题

传统的知识管理困境：

1
2
3
4
5
6
7
8

方式 1：写文档
问题：没人看。写完就过时。维护成本高。

方式 2：靠人传授
问题：老人离职知识断层。新人上手慢。传授效率低。

方式 3：代码注释
问题：注释会过时。只能解释"是什么"，难以解释"为什么这么做"和"以前踩过什么坑"。

复合工程的答案：把知识编码进工具，让工具在正确的时刻主动提醒你。

1
2
3
4
5
6
7
8
9

不是：写一份"商品发放注意事项"文档，期望大家会看
而是：在 context/experience/商品发放历史问题.md 里记录，
      Agent 在执行商品发放需求时自动加载，主动提醒

不是：靠老人口头传授"Apollo 配置有个坑"
而是：把坑编码到 skill 里，执行时自动校验

不是：在代码里写注释"这里要注意 XX"
而是：让 AI 在生成代码前就已经知道要注意 XX

关键设计模式

从 Compound Engineering Plugin 中可以提炼出三个核心设计模式：

我的实践：基于工具架构的知识复合

基于复合工程理念，我设计了一套 AI 工程工具架构来实现知识的持续沉淀与复用：

工具架构：

1
2
3
4
5
6
7

用户输入 → Command（入口）→ Agent（决策层）→ Skill（执行层）
                              ↓
                         意图识别、流程路由
                              ↓
                         调用具体 Skill 执行
                              ↓
                         experience-index（经验检索）

• Command：用户交互入口，如 /req-dev、/optimize-flow
• Agent：自主决策，智能判断意图，可调用多个 Skill
• Skill：固化流程，执行具体操作步骤

知识复合的两条路径：

1
2
3
4
5
6
7
8
9
10

路径 1：经验沉淀（/optimize-flow）
用户发现规律 → experience-depositor Agent → 识别规则类型 → 写入规则文件
                                                              ↓
                                              context-rules.md（上下文映射）
                                              risk-rules.md（风险识别）
                                              service-rules.md（服务补全）
                                              pattern-rules.md（代码模式）

路径 2：经验检索（experience-index Skill）
需求分析/方案设计/代码编写前 → 自动检索匹配规则 → 加载相关 Context、提示风险、建议服务

复利效应示例：

1
2
3
4
5
6
7

第 1 次做支付需求：45 分钟（边做边踩坑）
    ↓ 沉淀规则：/optimize-flow "支付需求要加载 payment-service.md 并提示资金安全"

第 2 次做支付需求：15 分钟（experience-index 自动加载背景、提示风险）
    ↓ 沉淀更多规则：错误处理模式、服务依赖关系

第 N 次做支付需求：5 分钟（系统已积累完整的支付领域知识）

与传统文档的本质区别：

1
2

传统文档：写完没人看，看了也找不到对的时机
AI 工程化：experience-index 在正确的时刻自动检索，主动推送给 Agent

这就是为什么”知识应该沉淀到工具”不是一句口号，而是有实际 ROI 的工程决策。

对长期任务工程设计的启示

Compound Engineering Plugin 为 AI 工程化提供了极好的参考蓝图：

极简主义：设计理念如何影响我的实践

Claude Code 团队的实践给了我另一个启发：

“最好的工具，就是没有工具。”

他们的做法：

• 只给模型一样东西：bash
• 每周都在删工具，因为新模型不需要了
• 减少模型的选择，就是增加模型的能力
• “模型吞噬脚手架”——曾经的外部辅助，逐渐被模型吸收

产品极简主义：不是”越来越丰富”，而是”越来越纯粹”。每一代模型发布，工具都会变得更简单，因为复杂性转移到了模型内部。

这个理念深刻影响了我做 AI 工程化的设计思路：

1. 入口极简化：整个系统只有两个命令入口——/req-dev 和 /optimize-flow。不是因为功能少，而是把复杂性藏到了 Agent 的智能路由里。用户不需要记住十几个命令，只需要表达意图，Agent 会判断该调用哪个 Skill。
2. Skill 而非工具堆叠：speckit/openspec 倾向于提供更多工具、更多模板、更多约束。我选择相反的方向——把能力编码为 Skill，让 Agent 在需要时自动调用，而不是让用户手动选择”现在该用哪个工具”。
3. 上下文自动加载：Claude Code 团队说”人类和 AI 看同样的输出，说同样的语言，共享同一个现实”。我把这个原则应用到上下文管理——不是让用户手动指定”加载哪些背景资料”，而是让 Agent 根据当前阶段自动加载相关的 context/。用户感受不到”上下文加载”这个动作，但 AI 已经具备了完整的信息。
4. 删除优先于添加：每次迭代时，我会问自己”有哪些东西可以删掉？”而不是”还能加什么功能？”。AGENTS.md 从最初的长篇大论，精简到现在只放通用规范和目录指针，具体流程全部下沉到 Skill 里。
5. 双重用户设计：Claude Code 为工程师和模型同时设计界面。AI 工程化也是——/req-dev 命令人可以手动调用，Agent 也可以在流程中自动调用子 Skill。同一套能力，两种调用方式，没有冗余。

当前实践的目标：让工具尽可能”隐形”——用户只需要说”我要做一个商品发放需求”，系统自动加载上下文、自动识别阶段、自动调用对应 Skill、自动沉淀经验。用户感受不到在”使用工具”，只是在”完成工作”。

注：关于工具消失的行业发展趋势，详见第九节”未来展望”。

上下文工程：AI 能力的前提是信息完整性

参考：Anthropic - Effective Context Engineering for AI Agents

什么是上下文工程？

上下文（Context） 指的是在从大语言模型（LLM）采样时包含的一组 token——不仅仅是提示词，还包括系统提示、工具定义、对话历史、检索到的文档等所有进入模型的信息。

上下文工程 是指在 LLM 推理过程中，策划和维护最优 token 集合的策略集合。它代表了 LLM 应用构建方式的根本转变：

核心指导原则：

找到最小可能的高信号 token 集合，最大化期望结果的可能性

为什么不重视上下文工程会导致严重问题？

很多团队把 AI 辅助编程的失败归咎于”模型不够强”或”提示词没写好”，但真正的根因往往是上下文工程的缺失。Anthropic 的研究揭示了几个关键问题：

问题 1：上下文腐蚀（Context Rot）

研究发现：随着上下文窗口中 token 数量增加，模型准确回忆信息的能力会下降。

1
2
3
4

上下文腐蚀的恶性循环：
加载更多信息 → 窗口膨胀 → 信息检索精度下降 → 行为异常
                ↓
        人发现问题 → 加更多上下文纠正 → 窗口更膨胀 → 更差

这不是断崖式下降，而是梯度下降——模型在长上下文中仍然能力强大，但信息检索和长程推理的精度会持续降低。

问题 2：注意力预算耗尽（Attention Budget Exhaustion）

LLM 就像人类有限的工作记忆一样，拥有”注意力预算”：

1
2
3
4
5
6
7
8
9

Transformer 架构的约束：
├── 每个 token 都要关注所有其他 token，产生 n² 个成对关系
├── 训练数据中短序列比长序列更常见，模型对长上下文依赖的经验较少
└── 位置编码插值虽允许处理更长序列，但会降低 token 位置理解的精度

结果：
├── 每引入一个新 token 都会消耗注意力预算
├── 低质量的 token 会"稀释"高质量信息
└── 关键信息可能被噪声淹没

问题 3：speckit/openspec 的上下文盲区

回顾第二节的 speckit 困境，从上下文工程角度重新审视：

问题 4：工具设计不当导致上下文污染

Anthropic 指出一个常见失败模式：

“臃肿的工具集，覆盖过多功能或导致使用哪个工具的决策点模糊不清”

判断标准：如果人类工程师无法明确说出在给定情况下应该使用哪个工具，AI 智能体也不能做得更好。

1
2
3
4
5

工具设计不当的后果：
├── 工具描述冗长 → 消耗上下文预算
├── 工具边界模糊 → AI 决策困难，产生更多试错对话
├── 工具返回冗余信息 → 上下文快速膨胀
└── 最终：窗口爆满，任务失败

有效上下文工程的核心原则

基于 Anthropic 的实践和我们的落地经验，总结以下原则：

原则 1：分层式信息组织

1
2
3
4
5
6
7
8

context/
├── business/
│   └── 活动业务边界.md        ← 概要层（意图识别时加载）
├── tech/
│   └── Apollo配置规范.md      ← 技术层（方案设计时加载）
└── experience/
    ├── 商品发放历史问题.md    ← 经验层（实施前加载）
    └── 雅典娜配置注意事项.md  ← 详细层（配置时加载）

原则 2：”即时”上下文策略（Just-in-Time Context）

不是预先加载所有可能相关的信息，而是维护轻量级索引，在运行时动态加载：

1
2
3
4
5
6
7

传统方式（预加载）：
启动 → 加载所有相关文档（20000 tokens）→ 开始工作 → 窗口已满一半

即时策略：
启动 → 加载索引文件（500 tokens）→ 识别当前阶段 → 按需加载（3000 tokens）
                                                    ↓
                                          窗口保持精简，信息高度相关

Claude Code 的实践：使用 glob 和 grep 等原语允许即时导航和检索文件，而不是预先加载完整数据对象到上下文中。

原则 3：上下文压缩与笔记系统

对于长时间运行的任务：

1
2
3
4
5
6
7
8
9
10

压缩（Compaction）：
├── 将接近上下文窗口限制的对话内容总结
├── 保留：架构决策、未解决的 bug、实现细节
├── 丢弃：冗余的工具输出或消息
└── 用摘要重新初始化新的上下文窗口

结构化笔记（Structured Note-taking）：
├── 智能体定期将笔记写入上下文窗口外的持久化存储
├── 稍后根据需要拉回上下文窗口
└── 实现跨压缩步骤的连贯性

原则 4：工具设计的上下文效率

1
2
3
4
5
6
7
8
9
10
11

好的工具设计：
├── 自包含：不依赖"记住"之前的对话
├── 返回精简：只返回 token 高效的必要信息
├── 边界清晰：用途明确，减少决策成本
└── 发挥模型优势：利用模型擅长的能力

坏的工具设计：
├── 返回完整数据库查询结果（可能数千行）
├── 工具描述长达数百 token
├── 多个工具功能重叠，边界模糊
└── 强迫模型做它不擅长的事情

上下文工程与 AI 工程化的关系

理解了上下文工程，就能理解 AI 工程化架构设计的”为什么”：

本质规律：

1
2
3

AI 的决策质量 ∝ 可用信息的完整性 × 信息的信噪比
                        ↑                    ↑
                   不是越多越好          高信号、低噪声才有效

这意味着：

• 与其让人在 review 时逐步想起遗漏告诉 AI
• 不如建立系统化的上下文管理，让 AI 自动获取精简且高信号的信息

实践：AI 工程化的设计与落地

AI 工程化是什么

经过反复思考和实践，我提炼出了 AI 工程化的定义：

智能化管理工作信息，以上下文工程的理解管理整个工作场景，借助AI的能力，降低人对已识别问题的处理成本

组成部分：

1. 脚手架（Git 仓库形式）

• 把规范转为基础的目录结构
• 附带基础的初始化命令
• 存放业务线的上下文信息（业务背景、技术背景等）
• 随项目独立迭代的资源文件

2. 工具包（插件形式）

• 提供 AI 工程需要的 cmd、skill、mcp、agent、hook 等
• 在插件市场迭代，分版本管理
• update 即可升级最新的规范、能力集成

为什么分脚手架和工具包？

• 插件市场内容会迭代、分版本，需要灵活升级
• 脚手架项目初始化后，随项目迭代，是独立的 git 仓库
• 脚手架适合存放基础资源文件和业务上下文信息
• 工具包适合封装通用能力和规范

核心架构：Agent + Skill 分层设计

1
2
3
4
5

用户输入 → Command → Agent（决策层）→ Skill（执行层）
                         ↓
                    意图识别、流程路由
                         ↓
                    调用具体 Skill 执行

• Agent：自主决策层，负责意图识别、流程路由、上下文管理
• Skill：过程执行层，负责固定流程任务的具体执行
• Command：用户交互入口，通过 Agent 路由到具体执行

当前系统设计：

• 5 个 Agents：phase-router、requirement-manager、design-manager、implementation-executor、experience-depositor
• 12 个 Skills：req-create、req-change、experience-index、design-create、design-change、workspace-setup、design-implementation、code-commit、requirement-completer、requirement-archiver、meta-maintainer、index-manager
• 2 个 Commands：/req-dev（需求研发统一入口）、/optimize-flow（流程优化沉淀）

目录结构：位置即语义

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

your-project/
├── AGENTS.md              # 项目记忆入口（每次会话自动加载）
├── .codebuddy/            # AI 自动化配置
│   ├── agents/            # Agent 定义（决策层）
│   ├── commands/          # 命令入口
│   └── skills/            # Skill 定义（执行层）
├── context/               # 项目知识库（长期记忆）
│   ├── business/          # 业务领域知识
│   ├── tech/              # 技术背景
│   │   └── services/      # 服务分析文档
│   └── experience/        # 历史经验
├── requirements/          # 需求管理
│   ├── INDEX.md           # 需求索引
│   ├── in-progress/       # 进行中需求
│   └── completed/         # 已完成需求
└── workspace/             # 代码工作区（Git 忽略）

三个核心约束：

1. 入口短小：AGENTS.md 只放通用规范 + 目录指针，不写具体流程步骤
2. 位置即语义：requirements/ 放需求产物，context/ 放可复用上下文，workspace/ 放代码
3. 复利沉淀：每次执行命令，除了产出当前结果，还要让”下一次更快、更稳”

经验沉淀的技术实现

前面 4.1 节讲了复合工程的理念和三层沉淀机制，这里聚焦具体怎么实现。

触发时机：什么时候沉淀？

1
2
3
4
5
6
7
8

不是：做完需求后专门花时间"写总结"
而是：在流程关键节点自动触发沉淀

具体触发点：
├── 需求完成时 → requirement-completer skill 自动提取可复用经验
├── 遇到问题解决后 → 用户说"记住这个坑" → experience-depositor agent 记录
├── 代码提交时 → code-commit skill 检查是否有值得记录的模式
└── 流程优化时 → /optimize-flow 命令专门用于沉淀和优化

沉淀格式：记录什么？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# context/experience/商品发放-钱包选择问题.md

## 问题描述
商品发放时选错钱包类型，导致用户领取失败

## 触发条件
- 需求涉及商品发放
- 商品类型为虚拟商品

## 解决方案
虚拟商品必须发到虚拟钱包，实物商品发到实物钱包
具体判断逻辑见 Apollo 配置：xxx.wallet.type

## 校验方式
检查 goods_type 与 wallet_type 的匹配关系

## 关联文档
- context/tech/Apollo配置规范.md
- context/tech/services/商品服务技术总结.md

检索机制：怎么在对的时候加载？

检索由 experience-index Skill 统一负责，在需求分析、方案设计、代码编写前自动调用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Agent 的上下文加载逻辑：

1. 意图识别阶段
   phase-router 识别意图，路由到对应 Agent
        ↓
2. 经验检索阶段
   Agent 调用 experience-index Skill，传入场景描述
   Skill 检索四类规则文件：
   ├── context-rules.md  → 匹配需加载的背景文档
   ├── risk-rules.md     → 匹配风险提示
   ├── service-rules.md  → 匹配服务依赖建议
   └── pattern-rules.md  → 匹配代码规范
        ↓
3. 返回结构化结果
   {
     "context": { "files": ["商品发放历史问题.md"] },
     "risk": { "alerts": [{"level": "high", "message": "注意钱包类型"}] },
     "service": { "suggestions": ["商品服务", "钱包服务"] },
     "pattern": { "files": ["error-handling.md"] }
   }
        ↓
4. Agent 主动提醒
   "注意：历史上商品发放有钱包选择问题，请确认..."

规则沉淀入口：通过 /optimize-flow 命令，调用 experience-depositor Agent 将新规则写入对应规则文件。

演进路径：从文档到 Skill 到 Command

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

阶段 1：纯文档（被动）
context/experience/xxx.md
→ AI 读取后提醒，但需要人确认

阶段 2：校验 Skill（半自动）
skill/product-distribution-validator
→ 自动校验配置，发现问题直接报错

阶段 3：完整 Command（全自动）
cmd/implement-product-distribution
→ 一个命令：加载背景 + 校验 + 生成 + 提醒 + 沉淀新经验

演进判断标准：
- 同类需求做了 5 次以上 → 考虑封装 Skill
- Skill 被调用 10 次以上 → 考虑封装 Command
- 不要过早抽象，让实践驱动演进

与 speckit 的本质区别

1
2
3
4
5
6
7
8
9

speckit 的知识流向：
人脑 → Spec 文档 → 代码
      ↑__________|
      下次还要从人脑开始

AI 工程化的知识流向：
人脑 → context/ → Skill → Command
         ↑_________|________|
         知识留在工具链里，下次直接复用

时间成本的量化对比

前面 2.5 节从”问题-方案”角度做了概念对比，这里从时间成本角度量化差异：

关键差异：

• 知识位置：speckit 在人脑（每次想），AI 工程化在 context/+skill/
• 新人上手：speckit 依赖老人传授，AI 工程化第一天就能用
• 边际成本：speckit 恒定，AI 工程化递减

深度对比：为什么传统 SDD 工具不够用

前面 2.5 节从”问题-方案”角度概述了 AI 工程化的优势，本节深入分析 speckit 和 openspec 的技术设计缺陷，帮助理解为什么需要新的解决方案。

speckit 的核心缺陷

问题 1：流程过于理想化

speckit 的 Constitution → Specify → Plan → Tasks → Implement 流程假设：

• 需求是清晰的
• 可以一次性规划
• 按阶段线性推进

但企业真实场景是：

• 需求动态变化
• 多方并行博弈
• 持续扯皮调整

问题 2：无法处理”考古”需求

speckit 从零开始定义，但真实开发必须”考古”：

• 历史坑点在哪？
• 现有能力有哪些？
• 配置规范是什么？

问题 3：知识不会沉淀

1
2
3

每次执行：Constitution → Specify → Plan → Tasks → Implement
                                                    ↓
                                              每次从头开始

缺失机制：

• ❌ 实施过程中发现的坑不会被记录
• ❌ 排查信息丢失
• ❌ 下次遇到类似问题还得重新排查

问题 4：宪章系统的僵化

9 条不可变原则固然保证质量，但：

• ✅ 适合标准化项目（Demo、开源库）
• ❌ 不适合企业定制场景（历史债务、框架限制、合规要求）

openspec 的核心缺陷

问题 1：Delta 机制的理论美好与现实骨感

假设需求可以”提案化”，但企业真实场景是多线并行、动态调整、持续扯皮。

问题 2：Fail-Fast 的代价

理论上保证一致性，实际上成为阻塞点。人的认知窗口有限，很难手动解决复杂冲突。

问题 3：强依赖命名的脆弱性

产品、运营、研发对同一个需求有不同表述，命名不一致导致归档失败。

问题 4：Archive 只是”合并”，不是”学习”

1
2
3
4
5
6

F(CurrentSpec, DeltaSpec) → NewSpec

缺失的维度：
F(CurrentSpec, DeltaSpec, Context, Lessons) → NewSpec + Knowledge
                           ↑          ↑
                     实施上下文    经验教训

共性问题：忽视人的现实工作模式

问题 1：忽视认知负担管理

两个工具都假设人能理解并遵循复杂流程、维护大量结构化文档、记住所有规范和约束。

但现实是：土办法最管用。工具应该适配人的工作模式，而不是强行改变它。

问题 2：忽视”执行过程”的价值

只关注”规范”和”结果”，忽视”过程”中的知识价值。

问题 3：忽视复利效应的关键性

1
2
3
4
5

传统工具：帮你"做事"
复合工程：帮你"越做越快"

传统工具：每次都是新的开始
AI 工程化：每次都站在上次的肩膀上

问题 4：Spec 详细程度的悖论

规范驱动开发有一个根本性的矛盾：

1
2

Spec 越详细 → 越接近代码本身 → 维护两份"代码"
Spec 越简略 → 越难指导 AI → 失去规范的意义

详细 Spec 的问题：

• 当 Spec 详细到可以精确指导 AI 生成代码时，它本身就变成了另一种形式的”代码”
• 你需要同时维护 Spec 和 Code 两套产物，且要保持同步
• 代码改了 Spec 要改，Spec 改了代码要改——双倍维护成本

AI 工程化的解法：不追求详细 Spec，而是分层概要 + 代码指针

1
2
3
4
5
6
7
8
9
10
11
12

AI 工程化的上下文组织：
├── 服务概要：这个服务做什么、边界在哪
├── 业务概要：核心业务流程、关键概念
├── 模块概要：模块职责、依赖关系
├── 接口概要：对外接口、调用方式
└── 代码指针：具体细节在 xxx/xxx.go 的 xxx 函数

不维护：
├── ❌ 详细的数据结构定义（代码里有）
├── ❌ 完整的接口参数说明（代码里有）
├── ❌ 具体的实现逻辑描述（代码里有）
└── ❌ 任何可以从代码直接获取的信息

核心原则：概要层帮助 AI 快速定位，细节层直接读代码。避免维护一份”像代码一样详细的 Spec 文档”——那只是换了个格式的代码，没有降低复杂度，反而增加了同步成本。

进阶能力：插件、Skill、MCP 的融合

对于大多数研发同学来说，可能还停留在 speckit、openspec 这类规范驱动工具的认知上。但 AI 工程化把更多能力融合在了一起：

Skill：可复用的能力单元

Skill 是过程执行层的基本单元，每个 Skill 负责一个具体的固定流程任务：

1
2
3
4
5
6
7

.codebuddy/skills/
├── req-create/            # 需求创建
│   ├── SKILL.md          # 技能定义
│   └── templates/        # 模板资源
├── design-create/         # 方案创建
├── workspace-setup/       # 环境搭建
└── code-commit/           # 代码提交

Skill 的特点：

• 单一职责：每个 Skill 只做一件事
• 可复用：多个流程可以调用同一个 Skill
• 可组合：复杂流程由多个 Skill 组合完成
• 可演进：Skill 可以独立升级，不影响其他部分

Agent：自主决策层

Agent 负责意图识别、流程路由、上下文管理：

1
2
3
4
5
6

.codebuddy/agents/
├── phase-router.md        # 阶段路由，意图识别
├── requirement-manager.md # 需求全生命周期管理
├── design-manager.md      # 方案全生命周期管理
├── implementation-executor.md # 开发实施执行
└── experience-depositor.md    # 经验沉淀（独立上下文）

Agent 与 Skill 的分工：

• Agent：决定”做什么”
• Skill：执行”怎么做”

多 Agent 协作：从上下文窗口爆满到高效分工

在实践 AI 工程化的过程中，我们遇到了一个关键瓶颈：上下文窗口爆满。

问题的根源

早期使用 speckit 等工具时，最痛苦的体验是：

1
2
3
4
5
6
7
8

执行复杂需求时：
├── 加载业务背景（5000 tokens）
├── 加载技术上下文（8000 tokens）
├── 加载历史经验（3000 tokens）
├── 当前对话记录（持续增长）
└── ...
        ↓
窗口频繁爆满 → 强制截断 → 丢失关键上下文 → AI 行为异常

Anthropic 工程团队精准描述了这个问题：

“想象一个软件项目由轮班工程师负责，每个新工程师到来时对上一班发生的事情毫无记忆。”

解决方案：Subagent 架构

借鉴 Anthropic 的双 Agent 架构思想，我们设计了 主 Agent + Subagent 的协作模式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

传统模式（单一 Agent）：
用户输入 → 一个大 Agent 处理所有事情 → 上下文持续膨胀 → 窗口爆满 → 任务失败

Subagent 模式：
用户输入 → 主 Agent（决策层）
              ↓
    意图识别 + 任务拆分
              ↓
    ┌─────────┼─────────┐
    ↓         ↓         ↓
Subagent1  Subagent2  Subagent3
(独立窗口)  (独立窗口)  (独立窗口)
    └─────────┼─────────┘
              ↓
    结果汇总 → 主 Agent 继续

核心优势：

效果对比

状态传递机制

Subagent 之间不共享上下文窗口，通过结构化状态文件保证信息传递：

1
2
3
4
5
6
7
8
9

核心文件：
├── requirements/INDEX.md      # 需求状态索引
├── requirements/in-progress/  # 进行中的需求详情
└── context/session/           # 会话级临时上下文

工作流程：
1. Subagent 启动时：读取状态文件，快速理解当前状态
2. Subagent 执行中：专注自己的任务
3. Subagent 结束时：更新状态文件，提交"干净的交接"

核心原则：每个 Subagent 只完成一个”原子任务”，不是一个工程师连续工作 48 小时，而是轮班工程师每人 4 小时但交接清晰。

与 speckit 的本质差异

1
2
3
4
5
6
7

speckit：依赖"一个 Agent 记住所有事情"
         Constitution → Specify → Plan → Tasks → Implement
         上下文持续累积，到 Implement 阶段时窗口已经很满

Subagent：依赖"结构化的状态传递"
         每个阶段独立的 Subagent，独立的上下文窗口
         状态通过文件传递，而非上下文累积

前者是人脑模型（记忆有限），后者是团队协作模型（交接清晰）。

MCP：外部系统集成

MCP（Model Context Protocol）让 AI 能够直接对接外部系统：

1
2
3
4
5
6
7
8
9
10
11
12
13

基础集成：
├── TAPD MCP（需求管理）
│   ├── 自动获取需求详情
│   ├── 关联相关需求
│   └── 更新需求状态
├── 工蜂 MCP（代码管理）
│   ├── 自动创建分支
│   ├── 提交代码变更
│   └── 创建合并请求
└── iWiki MCP（知识管理）
    ├── 检索历史技术方案
    ├── 获取业务背景文档
    └── 关联团队知识库

MCP 的价值：

• 自动化操作：不需要人手动操作 TAPD、工蜂、iWiki
• 信息同步：AI 自动获取最新信息
• 减少错误：避免手动操作的遗漏和错误

插件市场：能力的分发与升级

工具包以插件形式发布到插件市场：

• 版本管理：每个版本独立，可回滚
• 灵活升级：update 即可获得最新能力
• 团队共享：团队成员共享同一套能力集

与脚手架的配合：

• 脚手架存放业务上下文（随项目迭代）
• 工具包提供通用能力（独立版本管理）

落地策略：从零到一的实践路径

前面各节从理论角度阐述了 AI 工程化的设计，本节聚焦具体怎么落地。以 2.5 节提到的”商品发放”场景为例，展示完整的实践路径。

冷启动：新项目接入

冷启动是 AI 工程化的核心优势之一。传统工具的知识在人脑，需要传授；AI 工程化的知识在工具链里，开箱即用。

步骤 1：安装 AgentProjectKit 插件（5 分钟）

首先需要添加插件市场并安装 AgentProjectKit：

1
2
3
4
5

# 安装 AgentProjectKit 插件
/plugin install agent-project-kit@tmap-codebuddy-plugin

# 验证安装
/plugin list

步骤 2：脚手架初始化（15 分钟）

1
2

# 初始化 AI 工程项目
/agent-project-kit:init-project

命令会自动完成：

1. 克隆 AI 工程项目模板
2. 引导配置项目基本信息（业务线名称、定位等）
3. 初始化 AGENTS.md 项目记忆文件

步骤 3：加载服务上下文（30 分钟）

这是冷启动的关键步骤。/agent-project-kit:load-service 命令实现项目级别长期记忆初始化：

1
2
3
4

# 加载相关服务，生成技术总结
/agent-project-kit:load-service 
/agent-project-kit:load-service 
/agent-project-kit:load-service

/agent-project-kit:load-service 的工作流程：

1
2
3
4
5
6
7
8
9
10
11
12
13

用户执行 /agent-project-kit:load-service 
                ↓
1. 克隆服务代码到 workspace/loadservice/ 目录
                ↓
2. 分析服务架构、业务逻辑、API 接口：
   - 业务定位、核心职责、技术栈
   - 依赖关系、对外接口、数据模型
   - 关键模块、配置要点、常见坑点
                ↓
3. 生成技术文档到 context/tech/services/ 目录
                ↓
结果：AI 获得该服务的完整上下文，后续任何涉及该服务的需求
      都会自动加载这份上下文

为什么这很重要？

• speckit/openspec：每次需要描述服务背景时，依赖人记住并手动描述
• AI 工程化：一次 /agent-project-kit:load-service，永久复用，新成员也能立即获得”老兵视角”

步骤 4：开始需求研发

使用 /req-dev 命令开始你的第一个需求：

1
2
3
4
5

# 创建新需求
/req-dev 实现用户认证功能

# 或者指定已有需求继续工作
/req-dev REQ-001

工具包自带常用研发工具集成（MCP），开箱即用：

MCP 集成的价值：

• 不是”又多了几个工具要学”，而是”AI 自动帮你操作这些系统”
• 需求来了 → AI 自动从 TAPD 拉取详情 → 自动检索 iWiki 历史方案 → 自动生成方案
• 人只需要 review 和确认

冷启动效果对比：

关键差异：

• speckit/openspec：工具是”空壳”，知识在人脑，需要传授
• AI 工程化：工具包含”知识”（context/+MCP），新人第一天就能高质量工作

持续迭代：知识的复利沉淀

第 1 个需求：建立 context/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

需求：实现 12 月活动的商品发放

执行过程中发现问题：
- Apollo 配置有特殊格式要求
- 雅典娜 20 种商品类型，配置方式各不同
- 钱包选择要区分虚拟/实物
- 敏感 接口有合规要求

知识沉淀：
人："@agent，记住这些坑"
    ↓
自动生成/更新 context/:
├── context/tech/Apollo配置规范.md
├── context/experience/雅典娜配置注意事项.md
├── context/experience/商品发放历史问题.md
└── context/business/跨团队协作.md

耗时：45 分钟（首次建立）

第 2 个需求：复用 context/

1
2
3
4
5
6
7
8
9
10
11
12

需求：实现春节活动的商品发放（类似场景）

AI 自动加载 context/，自动提醒历史坑点
人 review："嗯，都考虑到了" ✓

新发现：春节活动需要限制地域
    ↓
"@agent，记住地域限制"
    ↓
context/ 自动更新

耗时：15 分钟（大量复用，少量新增）

第 6-10 个需求：封装为 skill

1
2
3
4
5
6
7
8
9
10
11
12

当 context/ 足够完善，封装为能力层：

skill/product-distribution-helper:
- 自动加载所有商品发放相关 context/
- 自动校验 Apollo 配置格式
- 自动检查雅典娜商品类型
- 自动提醒钱包选择、地域限制
- 自动生成监控配置

使用：/implement-product-distribution → 一键完成

耗时：3 分钟（高度自动化）

团队协作：知识的共享与传承

新成员第一天：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

speckit/openspec：
1. 学习工具用法（1-2 小时）
2. 了解服务架构（需老人讲解，2-4 小时）
3. 熟悉流程规范（1 小时）
4. 开始工作：依赖记忆和老人传授，首次质量不稳定
总计：4-7 小时准备 + 不稳定的首次质量

AI 工程化：
1. 脚手架初始化（15 分钟）
2. 工具包安装（5 分钟）
3. 立即开始工作：
   - context/ 提供服务上下文
   - MCP 自动集成 TAPD/工蜂/Apollo
   - cmd/skill 引导完成任务
   - 首次就能高质量完成
总计：20 分钟准备 + 稳定的首次质量

团队效应：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

5 人团队，各做 2 次商品发放：

speckit：5 人 × 2 次 × 45 分钟 = 450 分钟

AI 工程化：
第 1 人第 1 次：45 分钟 → context/ 建立
第 1 人第 2 次：15 分钟
第 2 人第 1 次：15 分钟（复用第 1 人 context/）
第 2 人第 2 次：10 分钟
...
第 5 人第 2 次：5 分钟

总计：126 分钟
节省：450 - 126 = 324 分钟（72%）

未来展望：工具终将消失

第 4.2 节讨论了极简主义如何影响当前设计，本节从行业发展趋势角度展望工具的演进方向。

模型吞噬脚手架

随着模型能力的提升，很多外部辅助会被模型内化：

1
2
3
4
5

Opus 4.1 需要的东西，Sonnet 4.5 已经内化了
    ↓
系统提示可以删 2000 个 tokens
    ↓
工具每周都在变简单

这意味着什么？ 今天我们在 context/、Skill、Agent 中编码的知识和流程，未来可能直接被模型”学会”。AI 工程化的架构设计需要为这种迁移做好准备——当某个 Skill 不再需要时，能够平滑删除而不影响整体。

多 Agent 架构的演进方向

从”工具调用”到”团队协作”

当前的 AI 辅助编程主要是”人调用 AI”模式：

1

人 → 发指令 → AI 执行 → 人检查 → 人发下一个指令

Subagent 架构开启了新的可能：

1

人 → 设定目标 → 主 Agent 拆解 → 多个 Subagent 协作 → 主 Agent 汇总 → 人验收

未来可能演进为：

1

人 → 设定目标 → Agent 团队自主协作数小时/数天 → 人验收最终结果

长时间运行 Agent 的关键挑战

Anthropic 的实践揭示了几个核心挑战：

Agent 专门化 vs 通用化的权衡

一个开放问题：应该用一个强大的通用 Agent，还是多个专门化的 Agent？

1
2
3
4
5
6
7
8
9

通用 Agent 路线：
├── 优势：简单，不需要协调
├── 劣势：上下文负担重，需要"知道所有事情"
└── 适合：简单任务、短时间任务

专门化 Agent 路线：
├── 优势：每个 Agent 更专精，上下文更精简
├── 劣势：需要协调机制，状态传递成本
└── 适合：复杂任务、长时间任务、团队协作场景

我们的选择：对于企业级复杂场景，专门化 Agent 更适合。原因是：

1. 企业场景本身就是”团队协作”，Agent 架构应该反映这一现实
2. 上下文窗口是硬约束，专门化可以更高效利用
3. 专门化 Agent 更容易独立迭代和优化

与人类团队的类比

最好的 Agent 架构设计，灵感来自人类高效团队的工作方式：

1
2
3
4
5
6
7
8
9
10
11
12
13

人类团队：
├── 产品经理：理解需求、拆解任务
├── 技术 Leader：设计方案、分配工作
├── 开发工程师：实现功能
├── 测试工程师：验证质量
└── 每个人有自己的专业领域，通过"会议"和"文档"协调

Agent 团队：
├── phase-router：理解意图、路由任务
├── design-manager：设计方案
├── implementation-executor：实现功能
├── test-agent（计划中）：验证质量
└── 每个 Agent 有自己的专业 Prompt，通过"状态文件"协调

Anthropic 工程团队的洞察：”这些实践的灵感来自于了解高效软件工程师每天做什么。”

当前范式：Claude 做一步，你检查，批准，它继续。

未来范式：

1
2
3
4
5

当模型可以自主工作几天甚至几周：
早上："我想完成 X"
晚上：看结果

中间的过程？它自己处理。

人的角色从”操作者”变成”监督者”，从”指令发出者”变成”目标设定者”。

AI 工程化的定位：在这个转型过程中，AI 工程化是”过渡期基础设施”——帮助团队在当前阶段高效工作，同时为未来的全自动化积累知识和经验。

研发工作的本质变化

AI 工程化不只是引入新工具，而是重新定义了研发的工作方式。这种变化已经在 AI 技术最前沿的团队中发生。

首先要避免的认知误区

工程师在使用 AI 时最常见的两种误解：

正确的定位是：AI 是强大的执行工具，但决策权和判断力必须留在人手中。

来自 OpenAI 与 Anthropic 的实践经验

理解 AI 的真实能力边界

参考 OpenAI 团队使用 Codex 构建 Sora 安卓应用的经验，将 AI 定位为**”一位新入职的资深工程师”**：

三步协作工作流（借鉴 OpenAI 与 Anthropic 经验）：

Anthropic 内部调查数据（2025年8月，132名工程师，20万条使用记录）：

• 工程师在 60% 的工作中使用 AI，实现 50% 的生产力提升，年同比增长 2-3 倍
• 27% 的 AI 辅助工作是原本不会完成的任务（如交互式仪表板、探索性工作）
• 工程师倾向于委托易于验证、定义明确、代码质量不关键、重复无聊的任务

“我可以非常胜任前端、事务性数据库的工作…而以前我会害怕触碰这些东西。” —— 后端工程师

“我以为我真的很享受编写代码，但实际上我只是享受编写代码带来的结果。” —— 高级工程师

核心理念：寻找 AI 的”舒适区”

工程师的核心工作之一，已经从纯粹的编码转变为识别 AI 的能力边界，并将复杂任务转化为落入 AI “舒适区”内的子任务：

• 低标准、高容错场景：任务对精确度要求不高，容忍多次失败。AI 尝试 N 次只要一次成功，就是显著提效
• 迭代式开发场景：形成”AI 初步实现 → 人验证修正 → 快速反馈”的闭环，不追求一次完美

工作模式的具体变化

工作内容的迁移：

时间分配的重构：

1
2
3
4
5

传统研发：                         AI 工程化后：
├── 40% 信息收集                   ├── 10% 信息确认
├── 30% 重复劳动                   ├── 10% 结果审核  
├── 20% 核心决策        →          ├── 50% 核心决策
└── 10% 知识沉淀                   └── 30% 知识沉淀

一个具体的对比——以”商品发放需求”为例：

1
2
3
4
5
6
7
8

传统模式的一天：                              AI 工程化模式的一天：
09:00-10:30 阅读需求文档，追问产品            09:00-09:30 /req-dev，确认需求边界
10:30-12:00 翻阅历史代码，理解逻辑            09:30-10:30 review AI 方案，调整决策点
14:00-15:30 询问老人"以前怎么做"              10:30-12:00 review AI 代码，优化核心逻辑
15:30-18:00 写代码，边写边查文档              14:00-15:00 AI 辅助测试，修复问题
18:00-19:00 遇到配置问题，排查                15:00-15:30 /optimize-flow 沉淀经验
19:00-20:00 继续写代码                       15:30-17:00 处理下一个需求
产出：完成 60%，知识留在脑子里                产出：完成 100%，经验沉淀到 context/

能力要求的升级

新的核心竞争力体现为三种能力：

1. 系统理解能力：AI 能实现功能，但只有人能判断它是否以正确方式融入系统
2. AI 协作能力：设计上下文、拆解计划、通过反馈循环持续优化
3. 设计质量标准：当”写出能工作的代码”门槛降低，架构设计和交付质量成为区分标准

监督悖论：有效使用 AI 需要监督能力，而监督能力可能因过度依赖 AI 而退化。Anthropic 的一些工程师故意在没有 AI 的情况下练习以”保持敏锐”。

本质洞察

黄仁勋有一个精准的判断：**AI 改变的是”任务”，而非”职业”**。

• 被 AI 接管的任务：信息检索、样板代码、格式化、重复配置
• 人依然主导的核心：系统设计、架构决策、质量判断、创新突破

AI 工程化的价值，就是让这种”任务迁移”在团队中系统化落地——通过 context/ 让信息检索自动化，通过 Skill 让重复流程标准化，通过经验沉淀让知识持续复利。

最终目标：让研发把时间花在”只有人能做的事”上，而不是”AI 也能做的事”上。

工具隐形化：从”使用工具”到”完成工作”

工具消失的含义：不是工具不存在了，而是工具变得如此无缝，你感受不到它的存在。

1
2

就像现在你用搜索引擎，不会想"我在使用一个信息检索系统"。
你只是在找答案。工具隐形了。

隐形化的三个层次

层次一：操作隐形——从”记住命令”到”表达意图”

1
2
3
4
5
6
7
8
9
10

过去：记住 20 个命令，选择正确的那个
├── /speckit.constitution
├── /speckit.specify  
├── /speckit.plan
├── /speckit.tasks
└── ...

现在：只说你要什么
├── "/req-dev 实现商品发放" → Agent 自动判断是创建还是继续
└── 不需要知道底层调用了哪些 Skill

层次二：知识隐形——从”想起经验”到”系统提醒”

1
2
3
4
5
6
7
8
9

过去：做需求时，人要想起历史上有什么坑
├── "上次商品发放好像有个钱包问题..."
├── "Apollo 配置格式是什么来着..."
└── 认知负担在人身上

现在：experience-index 自动检索，主动提醒
├── "检测到商品发放场景，已加载相关经验..."
├── "风险提示：注意钱包类型匹配"
└── 知识在系统里，人只需确认

层次三：流程隐形——从”遵循步骤”到”自然完成”

1
2
3
4
5
6
7
8
9

过去：严格按 Constitution → Specify → Plan → Tasks → Implement 执行
├── 人要知道"现在该执行哪个阶段"
├── 人要判断"前置条件是否满足"
└── 流程感知在人身上

现在：Agent 自主决策流程路由
├── 人说"继续做 REQ-001"
├── phase-router 自动判断当前阶段和下一步
└── 人感受到的是"工作在推进"，而非"在执行流程"

AI 工程化的隐形化进度

隐形化的终极形态

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

今天：
人："我要做一个商品发放需求"
AI：执行一步，等待确认
人：确认，继续
AI：执行下一步，等待确认
...

明天：
人："我要做一个商品发放需求"
AI：分析、设计、实现、测试、提交 PR
人：Review 最终结果

后天：
人：（在 TAPD 创建需求单）
AI：（自动感知、自动完成、自动提交 Review）
人：（只在关键决策点介入）

最后一步：你不再”使用”工具，你只是在思考业务问题，而工具已经把代码写好了。

写在最后：从第一性原理出发

回顾这段历程，我最大的收获是：不要为了用工具而用工具。

speckit 和 openspec 都是优秀的工具，它们定义的流程、模板、检查清单都很有价值。但正如 2.5 节(AI 工程化如何破局)的对比所示，它们解决的是”规范化”问题，而企业真实场景的核心问题是：

1. 上下文缺失：AI 看不到历史经验、业务边界、配置规范
2. 知识不沉淀：每次都从头开始，边际成本恒定
3. 范围太窄：只管单个仓库，无法覆盖跨服务、跨系统的复杂场景

AI 工程化试图解决这些问题：

1
2
3

上下文工程 → 让 AI 自动获取完整信息
复合工程 → 让每次实践都降低下次成本
项目级方案 → 管理所有仓库和外部系统

核心思路：

1
2
3
4
5
6
7
8
9

能够落地的最高效流程 → 已存在于高效的人的行为过程中
              ↓
      把高效流程 AI 化 → 推广到全团队应用
              ↓
  细节流程在具体业务线中迭代 → 自定义探索
              ↓
  实践中发现问题 → 提取可复用信息 → AI 工程化融入工具
                                  ↓
                      下次通用场景使用时可复用

最后想说的是：

AI 工程化不是要替代 speckit 或 openspec，而是在它们的基础上，融合上下文工程、复合工程、插件市场、MCP 集成等能力，形成一套更适合企业复杂场景的解决方案。

如果你也在探索 AI 辅助研发，希望这篇文章能给你一些启发：

1. 从真实工作场景出发，而不是从工具出发
2. 把知识编码进工具，而不是只写文档
3. 追求边际成本递减，而不是固定成本
4. 让工具适配人，而不是让人适配工具

工具的终极形态是消失。在那一天到来之前，我们要做的是让工具越来越”懂”我们的工作，越来越”记得”我们的经验，越来越”自然”地融入我们的日常。

这就是 AI 工程化的意义所在。

参考资料

• 上下文工程

• 复合工程

• claude code团队复合工程

• openspec

• speckit

• 多Agent协作的长时间任务

• 我们如何使用 Codex 在 28 天内构建 Android 版 Sora

• SKILL

Title: 彻底爆了！一文吃透AIGC、Agent、MCP的概念和关系-腾讯云开发者社区-腾讯云

原文地址

导语: 近年来，人工智能 领域涌现出许多新概念和新技术，其中AIGC、MCP和 Agent 成为了业界和学术界的热门话题。本文将深入浅出地介绍这三个概念，帮助读者全面理解它们的内涵、区别与联系，以及在实际应用中的价值。

AIGC

AIGC，全称为 AI Generated Content，意为“人工智能生成内容”。它指的是利用人工智能技术（尤其是大模型，如GPT、Stable Diffusion 等）自动生成文本、图片、音频、视频等多种内容的过程。2022 年 11 月 30 日，OpenAI 的 ChatGPT 正式上线（基于 GPT-3.5），引爆了 AIGC 热潮。

多模态技术

• 单模态： 只处理一种类型的数据，比如只处理文本（如GPT-3.5）、只处理图像（如图像识别模型）。
• 多模态： 能够同时处理两种及以上类型的数据。例如，既能理解图片内容，又能理解文本描述，甚至还能结合音频、视频等信息进行综合分析和生成。对应的场景有。

RAG 技术

RAG（Retrieval-Augmented Generation，检索增强生成） 技术，是一种将信息检索（IR） 与大型语言模型（LLM） 的文本生成能力相结合的人工智能框架。其核心思想是：当 LLM 需要回答一个问题或生成文本时，不是仅依赖其内部训练时学到的知识，而是先从一个外部知识库中检索出相关的信息片段，然后将这些检索到的信息与原始问题/指令一起提供给LLM，让LLM基于这些最新、最相关的上下文信息来生成更准确、更可靠、更少幻觉的答案。

大型语言模型虽然拥有海量的知识和强大的语言理解与生成能力，但也存在一些关键限制：

1. 知识局限性/过时性： LLM 的知识主要来源于其训练数据截止日期之前的信息。对于训练数据之后发生的事件、新研究、最新数据或特定领域的细节，LLM 可能不知道或给出过时的信息。
2. 幻觉： 当 LLM 遇到其知识库中不明确或不存在的信息时，它可能会“捏造”出看似合理但事实上错误或不存在的答案。
3. 缺乏来源/可验证性： LLM 通常无法提供其生成答案的具体来源依据，使得验证答案的准确性变得困难。
4. 特定领域知识不足： 通用 LLM 可能缺乏对某个特定公司、组织或个人私有知识库的深入了解。

RAG 正是为了解决这些问题而诞生的。

智能体 Agent

“智能体”（Agent）在计算机科学和人工智能领域指的是一个能够感知环境、自主决策并采取行动以实现特定目标的实体或系统。 它可以是软件程序、机器人硬件，甚至是生物实体（如人类或动物），但在 AI 领域通常指软件智能体。

Agent 和 AIGC 最大的区别：

1. AIGC 主要以生成式任务为主，而 Agent 是可以通过自主决策能力完成更多通用任务的智能系统。
2. 常见的 AIGC 系统（文生文，文生图）的核心就是一个生成模型，而 Agent 是一个集Function Call 模型（下文会详细介绍）、软件工程 于一体的复杂的系统，需要处理模型和外界的信息交互。
3. Agent 可以集成 AIGC 能力完成某些特定的任务，也就是 AIGC 可以是 Agent 系统里面的一个子模块。

Agent 最大的特点是，借助Function Call 模型，可以自主决策使用外接的一些工具来完成特定的任务。

Function Call 模型

什么是 Fucntion Call 模型

Function Calling（函数调用） 是大型语言模型的关键技术。前面有提到过RAG技术是为了解决模型无法和外接数据交互的问题，但是RAG的局限在于只赋予了模型检索数据的能力，而Function Calling允许模型理解用户请求中的潜在意图，并自动生成结构化参数来调用外部任何函数/工具，从而突破纯文本生成的限制，实现与真实世界的交互，比如可以调用查天气、发邮件、数学计算等工具。

Function Call 模型最早由 OpenAI 在 2023 年 6 月 13 正式提出并发布，首次在 GPT-4 模型上实现了 Function Calling 能力。OpenAI 作为大语言模型的领路人，其发布的模型的 API 协议都会行业标准，后面国内外新发布模型都会按照 OpenAI 的协议作为标准实现。截止目前，支持 Fucntion Calling 能力的主流模型如下表：

除了上面的知名度高的模型，还有一些其他开源或闭源模型也支持了 Fucntion Calling 能力，但是截止目前为止，GPT-4 仍然是公认的 Fucntion Calling 能力最强的模型。

工作原理：三步闭环流程

Function Call 模型的工作流程如下图：

步骤详解：

1、定义函数（开发者预设）

向 LLM 描述函数的用途、输入参数格式（JSON Schema），例如：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "name": "get_current_weather",
  "description": "获取指定城市的天气",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "城市名称"},
      "unit": {"enum": ["celsius", "fahrenheit"]}
    },
    "required": ["city"]
  }
}

• name 是工具名称
• description 是这个工具的用途
• parameters 是这个工具需要的输入参数

2、模型决策与生成参数

用户提问：“北京今天需要带伞吗？”

→ LLM 识别意图需调用 get_current_weather

→ 生成结构化参数：

1

{"city": "北京", "unit": "celsius"}

3、执行函数 & 返回结果

• 程序调用天气API，获真实数据：{"temp": 25, "rain_prob": 30%}
• 将结果交回LLM，生成最终回复：“北京今天25°C，降水概率30%，建议带伞。”

核心优势：LLM 的“手和眼睛”

Agent

OpenAI 发布 Function Call 模型后，Agent 才开始发展。而 Agent 真正进入到公众视野，被大家广泛关注的事件是 2025年4月 Manus 发布了通用智能体产品，引入了Computer Use 和 Browser Use，首次展现出智能体的强大能力。

Agent 的工作流程

实际上上文提到的 Function Call 模型的工作流程图，已经算是一个 Agent 的雏形了，不同点是，Agent 完成一次任务，实际上会循环调用模型，可能会调用多次 Function Calling，每次需要调用什么工具，完全由模型决策。一个最简单的 Agent 调用流程图如下：

比如有一个出行规划的智能体，这个智能体配置有天气查询、驾车规划、公共交通规划、骑行规划、步行规划等工具。用户询问“我在深圳，5月1日想去自驾去北京旅行，帮我规划一下出行方案。”，一个可能的具体的执行流程如下：

怎么开发一个自己的 Agent

最简单的方法就是把 Agent 的提示词（prompt）、工具、llm 调用，工具执行都硬编码到代码中，这样确实可以快速开发一个特定功能的 Agent。这样的实现会带来一些问题：

1. 提示词（prompt），工具需要调整的时候，需要改配置或者代码，灵活度不够高；
2. 如果要开发一个新功能的 Agent，整体代码可能需要重新实现一遍。

为了解决这一系列的问题，coze 、dify 、 腾讯云智能体开发平台等智能体开发平台相继出现。借助这些平台，开发者甚至不需要会编程，不需要 服务器 资源，就可以开发一个自己的Agent，Agent 的整个执行流程完全由平台在云上执行。智能体开发平台的架构一般包含 插件配置、Agent 配置、Agent 执行模块、插件执行模块，发布模块。

• 插件配置：所有 Agent 的工具都统一管理起来，而不是散落在各个 Agent 内部，这样可以做到工具的复用。一般平台会自带一些插件，比如网络搜索、文件上传、AIGC 工具等，同时也支持开发者添加自己的自定义插件。
• Agent 配置：配置 Agent 的 提示词 (prompt)，使用的模型，以及选择插件配置中的一批工具提供给模型做选择。
• 发布配置：开发者把自己的 Agent 开发调试稳定以后，发布成稳定版本就可以提供给用户使用了。
• 插件执行：执行某个特定的插件，返回结果。
• Agent 执行：实现通用的 Agent 执行流程，调用插件执行模块实现工具调用。

下图是用腾讯云智能体开发平台，开发一个简单的 Agent 配置和实际执行效果图。

Multi-Agent

除了使用智能体开发平台快速开发自己的 Agent 以外，还可以使用 sdk 的方式进行开发。2025 年 3 月 11 日，OpenAI 重磅发布 OpenAI Agent SDK！AI 开发范式彻底颠覆！使用 sdk 可以快速配置一个自定义的 Agent 后执行，相比智能体开发平台，sdk 具有更高的灵活性和自主可控性。

同时，在 OpenAI Agent SDK 中，首次引入了 Mulit Agent 的概念。在此之前，通过智能体开发平台，我们开发出来的 Agent 都只是单 Agent。一个单 Agent 的能力有限，只能解决特定领域的一个任务，而一个复杂任务往往需要执行多个领域的任务才能完成。而 OpenAI Agent SDK 可以让开发者定义多个领域的 Agent，并且给这些 Agent 配置一些转交关系，允许某个 Agent 把特定的任务交给另外一个合适领域的 Agent 来执行，多个 Agent 之间协同和互动来完成一个复杂任务。

在 OpenAI Agent SDK 发布以后，以腾讯云智能体开发平台为代表的相关产品都相继支持了 Multi-Agent 模式。

Agent 的发展

Agent 目前的发展还处于一个较初期的阶段，但是发展速度很快。在一些垂直领域比如代码生成 Cursor / 腾讯云 AI 代码助手 CodeBuddy、广告营销等方向已经有了比较好的落地。而更通用的 Agent 目前除了看到 Manus 落地以外，还没看到其他比较好的应用模式落地。相信随着时间发展，会有越来越好用，越来越通用的 Agent 应用诞生。

MCP

什么是 MCP

MCP（Model Context Protocol，模型上下文协议）是由人工智能公司Anthropic于2024 年 11 月 24 日正式发布并开源的协议标准。Anthropic 公司是由前 OpenAI 核心人员成立的人工智能公司，其发布的 Claude 系列模型是为数较少的可以和 GPT 系列抗衡的模型。

为什么需要 MCP

MCP 协议旨在解决大型语言模型（LLM）与外部数据源、工具间的集成难题，被比喻为“AI应用的USB-C接口“。通过标准化通信协议，将传统的“M×N集成问题”（即多个模型与多个数据源的点对点连接）转化为“M+N模式”，大幅降低开发成本。

在 MCP 协议没有推出之前：

1. 智能体开发平台需要单独的插件配置和插件执行模型，以屏蔽不通工具之间的协议差异，提供统一的接口给 Agent 使用；
2. 开发者如果要增加自定义的工具，需要按照平台规定的 http 协议实现工具。并且不同的平台之间的协议可能不同；
3. “M×N 问题”：每新增一个工具或模型，需重新开发全套接口，导致开发成本激增、系统脆弱；
4. 功能割裂：AI 模型无法跨工具协作（如同时操作 Excel 和 数据库），用户需手动切换平台。

没有标准，整个行业生态很难有大的发展，所以 MCP 作为一种标准的出现，是 AI 发展的必然需求。

总结：MCP 如何重塑 AI 范式：

MCP 的发展情况

MCP 自2024 年 11 月 24 日 发布以来，OpenAI、Google、微软、腾讯、阿里、百度等头部企业纷纷接入 MCP，推动其成为事实性行业标准。并且相继出现了 mcp.so 、mcpmarket 等超大体量的 MCP 服务提供商。国内的头部企业也相继加入 MCP 服务商的竞争中。在如此庞大的 MCP 市场下，开发者基本不需要开发自己的插件，直接使用 MCP 服务商的插件就可以直接开发大量 Agent。

同时很多头部企业，开始把自身原有的 API 业务开发成封装成 MCP 服务对外提供。比如：

1. GitHub Copilot 提供 MCP 的方式生成代码；
2. AWS 2025 年 6月推出开源工具 Amazon Serverless MCP Server，支持 Agent 直接操作云上资源，进行服务编排。
3. 腾讯地图、高德地图、百度地图均发布 MCP Server，支持在 Agent 中使用丰富的地图资源。
4. 腾讯云COS、百度网盘均已支持 MCP 协议的接入。

未来趋势：

• 与 AIOS 融合： MCP 正成为 AI 操作系统（如华为鸿蒙 HMAF）的核心组件，实现跨设备智能调度；
• 生态挑战： 大厂通过 MCP 构建“闭环生态”（如 阿里 集成高德地图），可能引发协议割裂，需推动跨平台协作标准。

MCP 不仅是技术协议，更是AI 生产力革命的基石——它让模型真正融入现实世界，成为人类工作的无缝延伸。

总结

整体上看，Agent 是在 AIGC、MCP 、大语言模型 LLM 等原子能力的基础上进行编排，以提供更复杂的 AI 应用。

原文地址

AI coding 智能体设计

理解 AI coding 智能体的设计，可以帮助开发者更好地使用 AI coding 工具，实现开发提效。

了解用户提示词预处理，帮助我们写出高效的用户提示词。例如：为什么在提示词中使用 @字符引入文件、目录作为上下文，可以减少会话轮次？如何自定义命令？

• 了解智能体如何处理 MCP 扩展，如何解析 MCP 的 prompt 和 tool 能力，从而更好的进行 MCP 设计，为 AI coding 智能体提供子命令扩展和工具集扩展。
• 了解 SubAgent 的实现，理解上下文隔离的意义，基于高内聚、低耦合原则进行智能体的模块化设计，降低系统复杂度。
• 了解 MCP 工具调用的局限性，从而理解 Claude Code 推出 Skills、Code Execution with MCP 的动机和原理。
• 为什么规约驱动开发（spec-driven development）成为 AI coding 的最佳实践？通过对开源项目 OpenSpec 的解读，了解规约驱动开发背后的奥秘和改进点。
  本文从分析 Gemini-CLI 源代码开始，解读 AI coding 工具的智能体设计。Claude Code 本身不开源，但是实现原理大同小异。

在分析 Gemini-CLI 过程中，特别感谢 Qwen Code 团队，他们的开源项目中的 openaiContentGenerator包提供了OpenAI API的兼容层，使用这个模块可以很容易将 Gemini-CLI 内置的谷歌认证和外部模型切换为公司内部模型。

Gemini-CLI 的用户提示词预处理

在 Gemini-CLI 中输入提示词，首先对输入的内容进行预处理。

• 如果提示词的第一个字符是斜线（/），将提示词视为命令，执行特定操作，或者替换为预置提示词和大模型交互。
• 如果提示词中包含 @字符+路径，检查 @字符后的路径是否存在，读取文件作为上下文，再发送给大模型。可减少不必要的模型会话。

内置命令

Gemini-CLI 的内置命令在 packages/cli/src/ui/commands/目录下定义。

• 例如 clear 命令在文件 packages/cli/src/ui/commands/clearCommand.ts 中定义。

• 内置命令可以执行特定操作。例如：/clear 命令用于重置对话、清空上下文。

内置命令可以使用预置用户提示词调用大模型完成相关任务。例如：/init 命令使用大模型分析工程代码创建 GEMINI.md 文件。

内置命令列表参见：docs/cli/commands.md。

MCP Server 提供的提示词命令

MCP server 提供两种能力：工具和提示词。工具被拼装为模型上下文，而提示词则作为 Gemini-CLI 的扩展命令。

例如安装 mcp-server-commands命令行工具后，该工具通过
STDIO 协议提供 MCP 服务，在 ~/.gemini/settings.json 配置示例如下：

1
2
3
4
5
6
7
8
9
10

{
  "mcpServers": {
    "mcp-server-commands": {
      "command": "npx",
      "args": [
        "mcp-server-commands"
      ]
    }
  }
}

在 Gemini-CLI 中输入斜线触发命令补全，可以看到新增的 run_command 命令，该命令有[MCP]标识和内置命令相区分：

1
2
3
4
5
6

╭─────────────────────────────────────────────────────────────────────────╮
│ > /                                                                     │
╰─────────────────────────────────────────────────────────────────────────╯
 run_command [MCP]   Include command output in the prompt. This is effectively a user tool call.
 clear               Clear the screen and conversation history
 compress            Compresses the context by replacing it with a summary

扩展包提供的提示词命令

从 Gemini-CLI 的官方扩展市场下载扩展。扩展包安装在 ~/.gemini/extensions目录下，每个扩展下面的 commands/子目录提供扩展命令。

以gemini-cli-security扩展为示例，安装命令如下：

1
2

$ gemini extensions install \
  https://github.com/gemini-cli-extensions/security

安装后重启 Gemini-CLI，执行命令 /extensions list查看安装的扩展：

1
2
3
4
5

> /extensions list

Installed extensions:
  gemini-cli-security (v0.3.0) - active

在 Gemini-CLI 中输入斜线触发命令补全，可以看到由扩展引入的新命令命令，这些命令有[]标识，以便和内置命令相区分：

1
2
3
4
5
6

╭─────────────────────────────────────────────────────────────────────────╮
│  > /security:                                                           │
╰─────────────────────────────────────────────────────────────────────────╯
 security:analyze             [gemini-cli-security] Analyzes code changes on your current branch for common security vulnerabilities
 security:analyze-github-pr   [gemini-cli-security] Only to be used with the run-gemini-cli GitHub Action. Analyzes code changes on a GitHub…

本地文件自定义命令

用户可以通过在特定目录下创建 *.toml文件，创建扩展命令。

• 用户级：~/.gemini/commands/*.toml
• 项目级：<project>/.gemini/commands/*.toml
• 扩展级：<extension>/commands/*.toml（扩展包提供的命令扩展）

扩展文件名（包含相对路径名）作为扩展命令，文件内容定义提示词。

• prompt = “提示词”
• description = “命令描述（可选）”

@路径扩展

在提示词中出现的"@路径"，在将提示词发送给大模型之前会提前读取相关文件（如果路径是目录名，会读取目录下所有文件）作为上下文，可以减少一轮或多轮和大模型的对话，提升效率。

Gemini-CLI 的工具注册和工具调用

在 Gemini-CLI 和大模型会话中，将工具列表作为上下文提供给大模型，由大模型决定是否调用，Gemini-CLI 接收到大模型的调用指令请求，由 Gemini-CLI 执行相应的调用指令，将命令输出作为上下文提供大模型，最终完成相应的任务。

注册核心工具

Gemini-CLI 内置的核心工具在 packages/core/src/tools/目录下定义，通过调用 packages/core/src/config/config.ts的createToolRegistry方法对工具注册。

可以通过配置文件中的 coreTools（如："coreTools": ["ReadFileTool", "GlobTool", "ShellTool(ls)"]）限制工具的访问，默认所有内置工具均可用。

这些核心工具，每个工具使用 TypeScript 实现相关功能，或者调用外部命令实现。

核心工具如下表所示：

子智能体注册为工具

目前只有一个子智能体（SubAgent）：CodebaseInvestigatorAgent，用于针对复杂请求的代码分析工作。Gemini-CLI 将子智能体 CodebaseInvestigatorAgent封装为工具，和其他工具以同样的流程调用。该子智能体被设置为只能使用只读工具。

子智能体在执行时有隔离的上下文空间，不会污染主智能体的上下文，通过高内聚松耦合的子智能体，有效降低智能体设计的复杂度。目前 Claude Code 已经提供用户自定义子智能体功能。

用户自定义工具

还支持通过用户指定命令提供自定义工具的发现。用配置tools.discoveryCommand设置自定义工具的发现命令（如 bin/get_tools），该命令的输出是一个 JSON 数组，提供自定义工具的定义。

参见 docs/get-started/configuration.md中的示例：

1
2
3
4
5
6

"tools": {                                                                     
  "sandbox": "docker",                                                         
  "discoveryCommand": "bin/get_tools",                                         
  "callCommand": "bin/call_tool",                                              
  "exclude": ["write_file"]                                                    
},  

MCP 注册为工具

通过 settings.json配置的 MCP Servers，以及扩展（extensions）包含的 MCP
Servers，用于发现自定义工具。

在 settings.json中每一个 mcpServers.<SERVER_NAME>小节支持三种 MCP
配置：stdio/SSE/streamable HTTP。

• command、args、env、cwd：用于设置 stdio 协议 MCP 连接。
• url：用于 SSE 协议。
• httpUrl：用于 streamable HTTP 协议。
• headers：设置 HTTP 头。
• includeTools、excludeTools：从 MCP 服务中包含和排除工具。

示例：

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  ...,
  "mcpServers": {
    "mainServer": {
      "command": "bin/mcp_server.py"
    },
    "anotherServer": {
      "command": "node",
      "args": ["mcp_server.js", "--verbose"]
    }
  },
  ...
}

MCP client 连接 MCP server 将返回注册到工具列表。参见代码文件 packages/core/src/tools/mcp-client-manager.ts、 packages/core/src/tools/mcp-client.ts。

流程图如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

1. maybeDiscoverMcpServer (入口)
   ├─ 权限检查
   ├─ 创建/重用 McpClient
   └─ 调用 connect() + discover()

2. connect() (连接)
   └─ connectToMcpServer()
      ├─ 创建 MCP Client 实例
      ├─ 注册能力 (roots)
      ├─ createTransport() (创建传输层)
      │  ├─ StdioClientTransport (stdio)
      │  ├─ SSEClientTransport (SSE)
      │  ├─ StreamableHTTPClientTransport (HTTP)
      │  └─ OAuth 认证处理
      └─ client.connect(transport)

3. discover() (发现)
   ├─ discoverPrompts() (发现提示)
   └─ discoverTools() (发现工具)
      ├─ 检查服务器能力
      ├─ mcpToTool().tool() (获取工具列表)
      ├─ 遍历 functionDeclarations
      ├─ isEnabled() (过滤工具)
      └─ new DiscoveredMCPTool() (封装工具)

4. 工具注册
   └─ toolRegistry.registerTool(tool)

5. 工具执行 (运行时)
   └─ DiscoveredMCPToolInvocation.execute()
      ├─ mcpTool.callTool() (调用 MCP 服务器)
      ├─ 处理响应
      └─ transformMcpContentToParts() (转换内容)

工具列表作为上下文提供给大模型

会话时，工具列表作为上下文传递给大模型。这个过程中，MCP server 提供的工具和内置工具一样写入上下文。一个 MCP server 可能会广播上百个工具，如果一个 AI coding 智能体添加了过多的 MCP server，太多的 MCP 工具会导致大模型上下文爆炸。即使少量配置的 MCP server，对于大部分场景用不到的 tools，会大量消耗大模型 token，非常不经济。

Claude Code 引入和 Skills 扩展，以及提出了大模型通过编码调用 MCP，都是为了解决传统 MCP 工具广播造成的 token 爆炸问题。

Gemini-CLI 中相关执行链路：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

1. 工具注册
   └─ ToolRegistry.registerTool()
      └─ 工具被添加到 allKnownTools Map

2. 获取工具列表
   └─ GeminiClient.startChat() 或 setTools()
      └─ toolRegistry.getFunctionDeclarations()
         └─ ToolRegistry.getFunctionDeclarations()
            ├─ getActiveTools() - 过滤被排除的工具
            └─ tool.schema - 获取每个工具的 FunctionDeclaration

3. 封装工具格式
   └─ const tools: Tool[] = [{ functionDeclarations: toolDeclarations }]
      └─ Tool 格式: { functionDeclarations: FunctionDeclaration[] }

4. 存储到 GeminiChat
   └─ new GeminiChat(config, { tools, ... }, history)
      └─ this.generationConfig.tools = tools

5. 发送消息时传递
   └─ GeminiChat.sendMessageStream()
      └─ makeApiCallAndProcessStream()
         └─ generateContentStream({
              model,
              contents,
              config: { ...this.generationConfig, ...params.config }
            })
            └─ config.tools 包含工具列表

6. ContentGenerator 处理
   ├─ Gemini API (GoogleGenAI)
   │  └─ 直接传递 tools 到 SDK
   │
   └─ OpenAI 兼容 API
      └─ convertGeminiToolsToOpenAI()
         └─ 转换为 OpenAI 格式
            └─ { type: 'function', function: { name, description, parameters } }

7. API 调用
   └─ 工具列表作为请求参数的一部分发送给大模型

Gemini API 的提示词中封装工具列表，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "model": "gemini-2.0-flash",
  "request": {
    "contents": [
      { "role": "user", "parts": [{ "text": "用户消息1" }] },
      { "role": "model", "parts": [{ "text": "模型回复1" }] },
      { "role": "user", "parts": [{ "text": "用户消息2" }] }
    ],
    "systemInstruction": {
      "role": "user",
      "parts": [{ "text": "系统提示词内容..." }]
    },
    "tools": [
      {
        "functionDeclarations": [
          { "name": "read_file", "description": "...", "parameters": {"..."} },
          { "name": "write_file", "description": "...", "parameters": {"..."} }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 8192
    }
  }
}

OpenAI 兼容 API 的提示词中封装工具列表，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "system",
      "content": "系统提示词内容..."
    },
    {
      "role": "user",
      "content": "用户消息1"
    },
    {
      "role": "assistant",
      "content": "模型回复1"
    },
    {
      "role": "user",
      "content": "用户消息2"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "...",
        "parameters": { /* JSON Schema */ }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "write_file",
        "description": "...",
        "parameters": { /* JSON Schema */ }
      }
    }
  ],
  "temperature": 0.7,
  "max_tokens": 8192
}

大模型工具调用请求和结果返回

大模型如果判断需要执行相应工具，会在输出中包含工具调用。

Gemini API 的工具调用请求：

1
2
3
4
5
6
7
8

// 从响应中提取的格式
{
  "functionCall": {
    "id": "...",        // 工具调用ID
    "name": "string",      // 工具名称
    "args": Record<string, unknown>  // 工具参数（JSON对象）
  }
}

OpenAI 兼容API的工具调用请求：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "tool_calls": [
    {
      "id": "...",
      "type": "function",
      "function": {
        "name": "...",
        "arguments": "..."  // JSON 字符串
      }
    }
  ]
}

Gemini-CLI 执行相关命令后，执行结果以 JSON格式封装。

GEMINI API 将执行结果作为用户消息的一部分返回，格式示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// 作为用户消息的一部分发送
{
  "role": "user",
  "parts": [
    {
      "functionResponse": {
        "id": "call_123",
        "name": "read_file",
        "response": {
          "output": "文件内容..."
        }
      }
    },
    {
      "functionResponse": {
        "id": "call_124",
        "name": "write_file",
        "response": {
          "error": "..."       // 错误信息
        }
      }
    }
  ]
}

OpenAI 兼容 API 将工具返回以新的 role（tool）返回：

1
2
3
4
5
6
7

// OpenAI API 格式
{
  "role": "tool",
  "tool_call_id": "call_123",
  "content": "工具执行结果字符串"
}

Gemini-CLI 的架构设计

Gemini-CLI、Claude Code 不但是强大的 AI coding 工具，用户也可以将其扩展为更加通用的智能体。例如在Claude Agent SDK文档中写到 Claude Code 可以扩展为：

• 编程类智能体：
  • 诊断并修复生产环境问题的 SRE（站点可靠性工程）智能体
  • 审查代码漏洞的安全审计机器人
  • 对突发事件进行分类处理的值班工程师助手
  • 强制执行代码风格与最佳实践的代码审查智能体
• 业务类智能体：
  • 审核合同与合规性的法律助手
  • 分析财务报告与预测的金融顾问
  • 解决技术问题的客户支持智能体
  • 为营销团队提供内容创作支持的助手

分析 Gemini-CLI 架构，理解智能体设计，通过扩展放大智能体能力为我所用。

流程图

Gemini-CLI 智能体流程图如下：

意图识别和智能路由

意图识别步骤是代码生成流程的第一阶段。当用户向 Gemini-CLI 提交请求时，系统必须首先理解用户想要完成什么任务，分析确定请求是需要代码生成还是可以通过直接响应来处理。

意图识别主要通过提示词工程和智能体ReAct架构实现。

文件packages/core/src/core/prompts.ts中的主系统提示词包含指导模型分析用户请求的特定指令：

• 对于软件工程任务，模型被指示思考用户请求和相关代码库上下文。
• 模型被指示使用 CodebaseInvestigatorAgent处理复杂任务或使用直接工具处理简单搜索。
• 提示提供了一个结构化的工作流程，用于在采取行动之前理解和制定代码库上下文策略。
• 详见后面的”主系统提示词”。

路由决策主要通过提示工程实现，配合少量支持代码。

• 没有显式的路由代码：路由决策由模型根据系统提示自主做出，而非硬编码的条件判断。
• 配置驱动可用性：智能体是否可用由配置决定，影响工具列表。
• 提示工程实现路由：系统提示明确指导何时使用智能体、何时使用直接工具。
• 工具化智能体：通过SubagentToolWrapper将智能体包装为工具，使其可被模型调用。

相关调用链路如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

1. 系统提示构建
   └─ getCoreSystemPrompt()
      ├─ 检查配置（enableCodebaseInvestigator）
      ├─ 选择提示模板（primaryWorkflows_prefix_ci 等）
      └─ 组合提示片段
         └─ 包含任务分类指导

2. 模型接收系统提示
   └─ 系统提示包含：
      ├─ 角色定位："specializing in software engineering tasks"
      ├─ 软件工程任务示例："fixing bugs, adding features, refactoring, or explaining code"
      ├─ 处理流程：Understand → Plan → Implement → Verify → Finalize
      └─ 路由指导：复杂任务 → CodebaseInvestigatorAgent，简单任务 → 直接工具

3. 模型自主分类（运行时）
   └─ 模型根据系统提示的指导
      ├─ 分析用户请求
      ├─ 判断是否为软件工程任务
      │  └─ 基于关键词和上下文：
      │     - "fixing bugs" → 软件工程任务
      │     - "adding features" → 软件工程任务
      │     - "refactoring" → 软件工程任务
      │     - "explaining code" → 软件工程任务
      │     - "what is..." → 可能是一般信息任务
      │     - "how does..." → 可能是一般信息任务
      └─ 决定处理方式：
         - 软件工程任务 → 遵循工作流程（使用工具）
         - 一般信息任务 → 直接回答（不使用代码生成工具）

4. 路由决策（如果是软件工程任务）
   └─ 模型评估复杂度
      ├─ 复杂任务（重构、系统分析）
      │  └─ 检查 CodebaseInvestigatorAgent 是否可用
      │     └─ 如果可用 → 调用 CodebaseInvestigatorAgent
      │     └─ 如果不可用 → 使用直接工具
      └─ 简单任务（查找文件、函数）
         └─ 直接使用 search_file_content 或 glob

主流程的 ReAct 框架

简单的编码任务，不使用CodebaseInvestigatorAgent子智能体，在主流程的
ReAct 架构中实现。

• 文件packages/cli/src/nonInteractiveCli.ts中的 while 循环。
• Reasoning：用geminiClient.sendMessageStream() 调用模型。
• Acting：用executeToolCall() 执行工具。
• Observing：收集 toolResponseParts。
• Updating：将结果设为 currentMessages，继续循环。

以一个简单的编码任务为例，流程如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

用户输入: "在 helper.ts 中添加 formatDate 函数"
    ↓
runNonInteractive()
    ↓
[初始化] 处理命令、设置取消监听
    ↓
┌────────────────────────────────────────┐
│      ReAct Loop Start(whiletrue)     │
└────────────────────────────────────────┘
    ↓
[Turn 1 - REASONING]
geminiClient.sendMessageStream()
    ├─> 系统提示词: "使用 GREP/GLOB 搜索"
    ├─> 模型分析: "需要先查看文件内容"
    └─> 返回工具调用: [read_file, search_file_content]
    ↓
[Turn 1 - ACTING]
executeToolCall(read_file) → 读取 helper.ts
executeToolCall(search_file_content) → 搜索 formatDate
    ↓
[Turn 1 - OBSERVING]
收集工具结果 → toolResponseParts
    ↓
[Turn 1 - UPDATING]
currentMessages = [{ role: 'user', parts: toolResponseParts }]
    ↓
[Turn 2 - REASONING]
模型收到文件内容，分析如何添加函数
    └─> 返回工具调用: [replace]
    ↓
[Turn 2 - ACTING]
executeToolCall(replace) → 修改文件
    ↓
[Turn 2 - OBSERVING]
收集修改结果
    ↓
[Turn 2 - UPDATING]
currentMessages = [{ role: 'user', parts: toolResponseParts }]
    ↓
[Turn 3 - REASONING]
模型确认任务完成
    └─> 返回文本响应（无工具调用）
    ↓
[终止]
toolCallRequests.length === 0
    └─> return (退出循环)

子智能体的 ReAct 框架

子智能体CodebaseInvestigatorAgent封装为一个工具，针对复杂的软件工程场景，大模型第一轮返回对子智能体 CodebaseInvestigatorAgent的调用请求。于是 Gemini-CLI 调用子智能体对本地代码工程做分析，查找代码文件和内容。

子智能体有自己的系统提示词，参见后面的”代码库调查 SubAgent 的系统提示词”。

子智能体的运行的 ReAct 框架代码见文件：packages/core/src/agents/executor.ts。

流程图如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

┌─────────────────────────────────────────────────────────────┐
│            CodebaseInvestigatorAgent ReAct Loop             │
└─────────────────────────────────────────────────────────────┘

初始化阶段
  ├─ 创建 GeminiChat 实例
  ├─ 准备工具列表（ls, read_file, glob, grep）
  └─ 构建初始查询（基于 objective 参数）

主循环 (whiletrue)
  │
  ├─ 【终止检查】
  │   ├─ 检查 max_turns (15)
  │   ├─ 检查 max_time_minutes (5)
  │   └─ 检查 AbortSignal
  │
  ├─ 【Reasoning 阶段】
  │   ├─ executeTurn()
  │   ├─ callModel() → 调用 Gemini API
  │   ├─ 提取 functionCalls
  │   └─ 提取思考内容（THOUGHT_CHUNK）
  │
  ├─ 【Acting 阶段】
  │   ├─ processFunctionCalls()
  │   ├─ 验证工具权限（只读工具白名单）
  │   ├─ 执行工具调用（ls, read_file, glob, grep）
  │   └─ 收集工具执行结果
  │
  ├─ 【Observing 阶段】
  │   ├─ 检查是否调用了 complete_task
  │   ├─ 验证输出模式（CodebaseInvestigationReportSchema）
  │   └─ 判断任务是否完成
  │
  └─ 【Updating 阶段】
      ├─ 如果完成：返回结构化报告
      ├─ 如果未完成：将工具结果作为 nextMessage
      └─ 继续下一轮循环

终止条件
  ├─ GOAL: 成功调用 complete_task 并验证输出
  ├─ MAX_TURNS: 达到 15 轮
  ├─ TIMEOUT: 超过 5 分钟
  ├─ ABORTED: 用户取消
  └─ ERROR: 协议违反（未调用 complete_task）

完成编码

完成编码任务是通过大模型返回的工具调用实现的。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

用户请求 (fixing bugs, adding features)
    ↓
模型分析任务类型
    ↓
模型返回工具调用 (functionCall)
    ↓
Gemini-CLI 解析工具调用
    ↓
工具验证和确认
    ↓
工具执行 (EditTool / WriteFileTool)
    ↓
文件系统写入 (FileSystemService.writeTextFile)
    ↓
执行结果返回给模型
    ↓
模型继续处理或完成

针对要修改的文件，模型通过 functionCall 返回修改请求，示例如下：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "functionCall": {
    "id": "call_123",
    "name": "replace",  // 或 "edit"
    "args": {
      "file_path": "src/utils/helper.ts",
      "old_string": "function oldFunction() {\n  return 'old';\n}",
      "new_string": "function newFunction() {\n  return 'new';\n}",
      "expected_replacements": 1  // 可选
    }
  }
}

针对要替换或新增的文件，模型返回 WriteFileTool
(创建新文件或覆盖)，示例如下：

1
2
3
4
5
6
7
8
9
10

{
  "functionCall": {
    "id": "call_456",
    "name": "write_file",
    "args": {
      "file_path": "src/new-feature.ts",
      "content": "export function newFeature() {\n  // implementation\n}"
    }
  }
}

工具执行完成后，结果被封装为 functionResponse
并添加到对话历史，在下次请求时发送给模型：

1
2
3
4
5
6
7
8
9

{
  "functionResponse": {
    "id": "call_123",
    "name": "replace",
    "response": {
      "output": "Successfully modified file: src/utils/helper.ts (1 replacements)."
    }
  }
}

记忆压缩

记忆压缩的触发条件：

• 用户提示词超过最大值的 20%（DEFAULT_COMPRESSION_TOKEN_THRESHOLD），启动压缩。
• 记忆压缩方法：
• 使用 findCompressSplitPoint 函数找到压缩分割点。
• 保留最近 30% 的对话历史 (COMPRESSION_PRESERVE_THRESHOLD = 0.3)。
• 使用大模型和提示词，将较早的历史通过模型进行总结压缩。提示词参见后面的”记忆压缩系统提示词”。
• 如果压缩后 token 数量反而增加，则标记为压缩失败。

记忆压缩的完整流程图如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

触发点：sendMessageStream() 发送消息前
  │
  ├─ tryCompressChat(prompt_id, force=false)
  │   │
  │   └─ ChatCompressionService.compress()
  │       │
  │       ├─ 【步骤 1】获取对话历史
  │       │   └─ chat.getHistory(true)  // curated history
  │       │
  │       ├─ 【步骤 2】早期退出检查
  │       │   ├─ 历史为空？→ NOOP
  │       │   └─ 之前压缩失败且未强制？→ NOOP
  │       │
  │       ├─ 【步骤 3】Token 阈值检查
  │       │   ├─ 获取当前 token 数：chat.getLastPromptTokenCount()
  │       │   ├─ 计算阈值：threshold * tokenLimit(model)
  │       │   └─ 未超过阈值？→ NOOP
  │       │
  │       ├─ 【步骤 4】找到分割点
  │       │   ├─ findCompressSplitPoint(history, 0.7)
  │       │   ├─ 计算字符数，找到 70% 位置
  │       │   ├─ 只在用户消息（非 functionResponse）处分割
  │       │   ├─ historyToCompress = history[0:splitPoint]
  │       │   └─ historyToKeep = history[splitPoint:]
  │       │
  │       ├─ 【步骤 5】调用模型生成摘要
  │       │   ├─ 准备输入：
  │       │   │   ├─ contents: [...historyToCompress, 压缩指令]
  │       │   │   └─ systemInstruction: getCompressionPrompt()
  │       │   ├─ 调用：config.getContentGenerator().generateContent()
  │       │   └─ 提取摘要：getResponseText(summaryResponse)
  │       │
  │       ├─ 【步骤 6】构建新历史
  │       │   ├─ extraHistory = [
  │       │   │     { role: 'user', parts: [{ text: summary }] },
  │       │   │     { role: 'model', parts: [{ text: 'Got it...' }] },
  │       │   │     ...historyToKeep
  │       │   │   ]
  │       │   └─ 计算新 token 数：JSON.stringify().length / 4
  │       │
  │       ├─ 【步骤 7】验证压缩效果
  │       │   ├─ newTokenCount > originalTokenCount？
  │       │   │   └─ 是 → COMPRESSION_FAILED_INFLATED_TOKEN_COUNT
  │       │   └─ 否 → COMPRESSED
  │       │
  │       └─ 【步骤 8】返回结果
  │           ├─ newHistory: 压缩后的历史（或 null）
  │           └─ info: 压缩状态和统计信息
  │
  └─ 处理压缩结果
      ├─ 压缩失败？
      │   └─ 设置 hasFailedCompressionAttempt = true
      │
      └─ 压缩成功？
          ├─ 更新对话历史：this.chat = await this.startChat(newHistory)
          ├─ 更新 token 计数：this.updateTelemetryTokenCount()
          └─ 强制完整 IDE 上下文：this.forceFullIdeContext = true

Gemini-CLI 的预置提示词

Gemini-CLI 的意图理解、智能路由能力，大部分是通过提示词实现的。

主系统提示词

参见文件 packages/core/src/core/prompts.ts的 getCoreSystemPrompt()方法。

关于主系统提示词的说明：

• 主系统提示词由以下所示的 preamble、coreMandates、primaryWorkflows*
• 等几个部分组成。
• 可以通过环境变量 GEMINI_PROMPT_*（如 GEMINI_PROMPT_PREAMBLE=false）关闭相关的提示词。
• 提示词中的类似 ${CodebaseInvestigatorAgent.name}的语法是变量替换。
• 提示词中的类似${(function () { ... }()的语法是 IIFE（立即执行函数表达式），以便利用更加灵活的条件判断等指令生成字符串。
• 可以使用文件绕过系统提示词，使用文件内容作为系统提示词（不建议）：
• 如果有环境变量 GEMINI_SYSTEM_MD，使用该环境变量指向的文件作为系统提示词。
• 默认检查是否存在文件 ~/.gemini/system.md，如果存在则使用该文件作为系统提示词。

系统提示词的中文译文如下：

1.Preamble

1
2
3

你是一个专门从事软件工程任务的交互式 CLI 代理。  
你的主要目标是帮助用户安全高效地完成任务，  
严格遵守以下指令并使用你可用的工具。

2.CoreMandates

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 核心职责

- **约定：** 在读取或修改代码时严格遵守现有项目约定。  
  先分析周围代码、测试和配置。

- **库/框架：** 绝不假设某个库/框架可用或合适。  
  在使用前验证其在项目中的既定用法（检查导入语句、  
  配置文件如 'package.json'、'Cargo.toml'、  
  'requirements.txt'、'build.gradle' 等，或观察相邻文件）。

- **风格与结构：** 模仿项目中现有代码的风格（格式、命名）、  
  结构、框架选择、类型和架构模式。

- **惯用更改：** 编辑时理解本地上下文（导入、函数/类），  
  确保您的更改能够自然且惯用地集成。

- **注释：** 谨慎添加代码注释。重点关注 *为什么* 要做某事，  
  特别是对于复杂逻辑，而不是 *做什么*。仅在必要时添加  
  高价值注释以提高清晰度或按用户要求添加。  
  不要编辑与您更改的代码分开的注释。  
  *绝不* 通过注释与用户交谈或描述您的更改。

- **主动性：** 彻底完成用户的请求。添加功能或修复错误时，  
  这包括添加测试以确保质量。除非用户另有说明，  
  否则将所有创建的文件（尤其是测试）视为永久工件。

- **确认模糊/扩展：** 不要在请求的明确范围之外采取重大行动，  
  除非与用户确认。如果被问及 *如何* 做某事，先解释，不要直接操作。

- **解释更改：** 完成代码修改或文件操作后，  
  *不要* 提供摘要，除非被要求。

- **不要回滚更改：** 除非用户要求，否则不要回滚对代码库的更改。  
  只有在您所做的更改导致错误或用户明确要求您回滚更改时，  
  才回滚您所做的更改。

3.PrimaryWorkflows_ (根据不同条件选择不同提示词)*

1. primaryWorkflows_prefix_ci_todo（if enableCodebaseInvestigator &&
   enableWriteTodosTool）

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24

   # 主要工作流程 ## 软件工程任务 当被要求执行诸如修复错误、添加功能、重构或解释代码等任务时， 请遵循以下步骤： 1. **理解与策略：** 思考用户请求以及相关的代码库上下文。 当任务涉及**复杂的重构、代码库探索或系统级分析**时， 你的**第一且主要的工具**必须是「${CodebaseInvestigatorAgent.name}」。 使用它来全面了解代码、其结构和依赖关系。 对于**简单的、有针对性的搜索**（如查找特定函数名、文件路径或变量声明）， 你应该直接使用「${GREP_TOOL_NAME}」或「${GLOB_TOOL_NAME}」。 2. **计划：** 基于第一步的理解，制定一个连贯且有根据的计划， 说明你打算如何解决用户的任务。 如果使用了「${CodebaseInvestigatorAgent.name}」， 请不要忽视其输出，你必须将其作为计划的基础。 对于复杂任务，将其分解为更小、可管理的子任务， 并使用「`${WRITE_TODOS_TOOL_NAME}`」工具跟踪进度。 如果有助于用户理解你的思路， 请提供一个极为简洁但清晰的计划。 在计划中，应包含编写单元测试来验证更改的迭代开发过程， 并在过程中使用输出日志或调试语句辅助实现解决方案。

2. PrimaryWorkflows_prefix_ci（if enableCodebaseInvestigator）

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23

   # 主要工作流程 ## 软件工程任务 当被要求执行诸如修复错误、添加功能、重构或解释代码等任务时， 请遵循以下顺序： 1. **理解与制定策略：** 思考用户的要求和相关代码库的上下文。 当任务涉及**复杂重构、代码库探索或系统范围分析**时， 您的**第一个且主要的工具**必须是 '${CodebaseInvestigatorAgent.name}'。 使用它来全面了解代码、其结构和依赖关系。 对于**简单的、有针对性的搜索**（如查找特定函数名、文件路径或变量声明）， 您应直接使用 '${GREP_TOOL_NAME}' 或 '${GLOB_TOOL_NAME}'。 2. **规划：** 基于第一步的理解，构建一个连贯且有根据的计划 来解决用户的任务。 如果使用了 '${CodebaseInvestigatorAgent.name}'， 请不要忽视其输出，您必须将其作为计划的基础。 如果这有助于用户理解您的思考过程， 请与用户分享一个极其简洁但清晰的计划。 作为计划的一部分，您应该使用迭代开发过程， 包括编写单元测试来验证您的更改。 在这个过程中使用输出日志或调试语句来得出解决方案。

3. PrimaryWorkflows_todo（if enableWriteTodosTool）

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

   # 主要工作流程 ## 软件工程任务 当被要求执行诸如修复错误、添加功能、重构或解释代码等任务时， 请遵循以下步骤： 1. **理解：** 思考用户请求及相关代码库上下文。 广泛使用 '${GREP_TOOL_NAME}' 和 '${GLOB_TOOL_NAME}' 搜索工具 （若独立则并行使用），以了解文件结构、现有代码模式和规范。 使用 '${READ_FILE_TOOL_NAME}' 和 '${READ_MANY_FILES_TOOL_NAME}' 来理解上下文并验证你可能有的任何假设。 2. **计划：** 制定一个连贯且有根据（基于第1步的理解）的计划， 说明你打算如何解决用户的任务。 对于复杂的任务，将其分解为更小、易于管理的子任务， 并使用 \`${WRITE_TODOS_TOOL_NAME}\` 工具来跟踪你的进度。 如果有助于用户理解你的思路， 可向用户提供一个极其简洁但清晰的计划。 作为计划的一部分，你应该采用包含编写单元测试 以验证更改的迭代开发过程。 在此过程中使用输出日志或调试语句来得出解决方案。

4. PrimaryWorkflows_prefix

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

   # 主要工作流程 ## 软件工程任务 当被要求执行诸如修复错误、添加功能、重构或解释代码等任务时， 请遵循以下步骤： 1. **理解：** 思考用户的需求以及相关的代码库上下文。 广泛使用 '${GREP_TOOL_NAME}' 和 '${GLOB_TOOL_NAME}' 搜索工具 （如果独立则并行使用），以了解文件结构、现有代码模式和规范。 使用 '${READ_FILE_TOOL_NAME}' 和 '${READ_MANY_FILES_TOOL_NAME}' 来理解上下文并验证你可能有的任何假设。 2. **计划：** 制定一个连贯且基于第一步理解的计划， 说明你打算如何解决用户的任务。 如果对用户理解你的思路有帮助， 可以向用户提供一个极其简洁但清晰的计划。 作为计划的一部分，你应该采用包含编写单元测试 来验证更改的迭代开发过程。 在这一过程中使用输出日志或调试语句来得出解决方案。