1 问题根源

你是否曾在AI智能体执行中途不得不打断它、纠正它？长期观察你就会发现一个规律：会话运行时间越长，输出质量越差。因为会话拉长后，模型对中间信息的注意力急剧衰减（Lost-in-the-Middle），且早期产生的错误假设或过时代码引用会持续污染后续所有决策。更本质的缺陷在于：多数工作流是开环的——规划一旦生成，实施便机械执行，遇到偏差只能被动暂停，缺乏自动修正能力。

单纯的“减少上下文”只能治标。一个高可靠性的智能体工作流必须建立在四个支柱之上：证据可溯源性（杜绝摘要堆叠）、锚定稳定性（对抗代码漂移）、硬约束首位化（确保红线不被逾越）以及闭环可恢复性（失败后自主修正）。

2 核心原则

• 证据驱动，而非摘要驱动：
   子智能体不得只返回自然语言总结。必须向主智能体提供带置信度评分的原始代码切片（Quoted Snippet），主智能体必须亲眼看到证据原文，而非二手转述。
• 语义锚定，而非行号锚定：
   代码位置引用必须绑定唯一函数签名、类名或路由路径，并附带当前的 Git Commit SHA。物理行号仅作为辅助参考，防止代码提交后所有规划一夜失效。
• 硬约束前缀注入：
   放弃模糊的“上下文占用百分比”目标。阶段清空后，新会话的前 2000 个 Token 必须固定写入系统级“不可变红线”（如：严禁修改的底层模块、禁止删除数据表、禁止引入非标准库），确保模型在任何时候都优先看到这些底线规则。
• 闭环重规划，而非死板暂停：
   实施阶段出错后，不直接等待人类介入。智能体应解析错误堆栈，针对失败点生成增量补丁并重新执行，仅在连续多次失败后才向人类求助。

3 三阶段执行流程

整体流程依然分三大阶段，阶段间清空上下文。

3.1 第一阶段：研究（Research）—— 生成“证据包”

研究阶段回答“当前系统究竟如何运作”。此阶段的目标不是写一篇阅读笔记，而是产出结构化的 evidence_pack.json。

主智能体会并行启动多类子智能体，但所有子智能体的返回结果必须遵循统一的证据格式：

{
  "target_entity": "PaymentRouter",
  "entity_type": "ExpressRoute",
  "symbol_signature": "router.post('/pay', rateLimit({...}))",
  "base_commit": "a1b2c3d4e5",
  "quoted_snippet": "const rateLimit = require('express-rate-limit'); ...",
  "confidence_score": 0.92,
  "fallback_lines": "34-58"
}

关键机制： 主智能体在进入规划阶段前，会舍弃子智能体生成的大部分解释性文字，但必须完整保留quoted_snippet 中置信度高于 0.85 的原始代码。这些一手证据将直接作为规划的事实地基，从根本上阻断“摘要导致幻觉”的传导链。

3.2 第二阶段：规划（Planning）—— 生成“语义规划本体”与“范围哨兵”

规划阶段负责构建精确的改动蓝图。文档格式为混合体：人类可读的 Markdown 说明 + 机器可执行的 JSON 语义元数据。

3.2.1 语义锚定替代物理行号

规划文档禁止单独使用行号定位。所有改动目标必须附带可检索的符号签名，例如：

<!-- TARGET: src/middleware/auth.ts -->
<!-- SYMBOL: authenticateUser -->
<!-- COMMIT: a1b2c3d4e5 -->
<!-- ACTION: 在第45行之后插入限流校验逻辑 -->

实施智能体在执行时，会通过 git grep 或语言服务协议（LSP）动态解析 authenticateUser 在当前分支的最新行号，而不是盲目信任旧文档中可能已失效的数字。

3.2.2 独立的“范围哨兵”智能体

规划草稿生成后，不会被直接执行。系统会唤醒一个只读的“守门员”智能体，它的唯一职责是依据规划开篇的“本次不做事项”清单，检查改动点是否越界。一旦发现规划试图新增管理后台界面或调整非目标数据库，守门员会强制删除相关段落并记录拦截日志，确保智能体“乐于助人”的倾向不会演变成范围蔓延（Scope Creep）。

3.3 第三阶段：实施（Implementation）—— 带闭环重规划的自主执行

实施阶段分为“执行-验证-修正”三个子步骤，形成一个内循环：

1. 执行：
    智能体根据语义定位，精准修改代码。
2. 自动验证：
    立即运行项目的编译检查与单元测试套件（如 npm run build && npm test）。
3. 分支处理：
   
   - 验证通过： 清空上下文，阶段结束。
   - 验证失败：上下文保留，智能体将完整的错误堆栈（stderr）与当前修改的 diff 打包。针对报错信息，仅对涉及失败的模块生成一份 patch_plan.md（增量补丁），应用补丁后再次跳回“执行”步骤。
   - 该内循环最多重试 3 次。若 3 次后验证依然失败，系统才会暂停并汇总所有尝试记录，向开发者发起精准求助。

4 研究文档的“保质期”管理

跨任务复用研究文档能大幅提效，但代码库时刻在变动，陈旧的研究结论等同于有毒知识。为此，每份研究文档的头部强制包含 base_commit_sha 与 generated_at 时间戳。

当后续任务打算引用某份历史文档时，工作流的第一步是执行：

git diff --stat <base_commit_sha> HEAD -- <相关文件路径>

若相关文件的改动比例超过 15%，则认定该文档过期。系统会自动触发一次“增量研究”，仅针对变动的部分更新证据包，并刷新 base_commit_sha，确保规划永远基于最近的有效基线。

5 上下文管理策略：固定前缀 + 按需检索

抛弃无效的百分比控制，采用更激进的主动管理：

• 固定硬约束前缀：
   每次清空上下文启动新阶段时，系统提示词的最前方（前 2000 Token）强制植入不可变更的项目红线。这些红线不依赖模型“记住”，而是作为系统级消息硬编码注入。
• 按需检索加载（RAG）：
   主智能体不一次性加载完整的数百行研究文档和规划文档。它仅在执行具体任务步骤时，通过关键词或向量检索，提取规划文档中对应的章节片段载入上下文。这使得每次决策所依赖的上下文既精炼又高度相关，极大缓解了窗口中间区域的注意力衰减问题。

6 何时精简流程

并非所有场景都需要跑满全套流程，可根据任务边界灵活裁剪：

• 微小改动（≤ 30 行或单文件）：
   跳过研究和完整规划阶段，直接进入实施，但范围哨兵智能体必须保留，以防范越界修改。
• 探索性编码或引入新技术栈：
   全力投入研究阶段，且将生成的证据包有效期设为较短时间（如 3 天），强制高频刷新。
• 大型架构重构：
   按业务模块分别生成多份独立的 evidence_pack，规划也拆分为若干个可独立验证的阶段，每个阶段完成后执行一次“证据包刷新”，确保下游阶段不依赖上游的过时上下文。

7 文档存储与团队协作

目录结构依然推荐：

thoughts/
├── shared/
│   ├── manifests/
│   │   └── index.json        # 记录所有文档的base_commit与有效期状态
│   ├── research/
│   │   └── payment_flow.json # 结构化证据包
│   └── plans/
│       └── rate_limit.md      # 语义规划本体

对于大型团队，由于多人并行提交可能导致文档冲突，建议将 manifests/index.json 提交至代码仓库，而详细的研究与规划文档仅在本地维护。开发者可通过 index.json 获知当前项目整体的规划基线与哈希版本，在需要共享时再将特定文档导出交换。

这套工作流的核心交付物不是“完美的首次规划”，而是可证伪的证据、可寻址的锚点、可自愈的执行闭环。它将智能体从一次性的“猜测机器”转变为可迭代、可审计的系统工程组件，欢迎在实战中检验其韧性。

有任何不同的看法，评论区我们可以继续聊~ 😊