docs(c14): 勘误保留 + 补 AgentSummary / /agents 入口

[luyao618]

概要

C14（Agent 系统）按 spec §5 分类为「勘误保留 / S / 15% 新增」。本次改动只做最小增量：

• §1.5 新增 commands/agents/ 这一交互式管理入口的描述，把它定位成 loadAgentsDir.ts 的写入端。
• §7.5 新增 services/AgentSummary/agentSummary.ts 一节，覆盖 30 秒定时 fork、canUseTool 拒绝代替 tools:[]、不动 maxOutputTokens 这三件相互呼应的 cache-key 保护手段，以及 closure 丢弃过期 forkContextMessages 的写法。

两处合计 +54 行，未删原文段落、未改任何 v1 标题，仅插入 1 个新小标题 §1.5 与 1 个新二级标题 §七.5。

风格双亲

本次新增段落以下两个 v1 章节为模板：

• docs/13-内置Agent设计模式.md：紧贴 C14 同主题，叙事节奏一致（先抛问题、引一段源码、解释设计动机）。
• docs/20-API调用与错误恢复.md：写「不可靠系统的工程优化」这一类章节的标杆，AgentSummary 的 cache 保护逻辑与 §20 中 withRetry 的退避策略叙事同构。

风格双亲实证段（v1 摘抄 × 2 + 新增 × 2）

v1-13 摘抄 ≥200 字

在第 12 篇中，我们了解了 Agent 系统的整体架构 —— AgentDefinition 数据结构、runAgent() 生命周期、createSubagentContext() 的隔离机制。但架构只是骨架，真正赋予 Agent "灵魂"的是它们的 System Prompt 设计。

一个核心问题：Claude Code 拥有 40+ 个工具，为什么不让一个通用 Agent 做所有事？答案藏在工程实践中：成本控制 —— Explore Agent 用 Haiku 模型就够了，不需要用 Opus 来做文件搜索；安全隔离 —— Verification Agent 禁止修改项目目录，否则"检验者"自己改代码就失去了意义；prompt 精度 —— 越专注的角色定义，模型的行为越可预测；token 节约 —— 只读 Agent 不需要 CLAUDE.md 中的 commit/PR/lint 规则，省下 5-15 Gtok/周。

v1-20 摘抄 ≥200 字

当你在本地调用一个 REST API 时，最简单的做法是失败就报错。但 Claude Code 面对的是一个远比这复杂的现实：网络不可靠 —— 用户可能在咖啡馆 WiFi、企业代理、VPN 隧道后面使用；API 容量波动 —— 529 过载和 429 限流是 LLM API 的常态，不是异常；认证令牌过期 —— OAuth token、AWS credential、GCP credential 都有 TTL；流式连接脆弱 —— SSE 流可能在中途断开、超时、或被代理截断；多 Provider 差异 —— 同一份代码要兼容 Anthropic 直连、AWS Bedrock、GCP Vertex、Azure Foundry 四种后端。如果每种错误都让用户手动重试，用户体验将是灾难性的 —— 想象你在一个需要 10 分钟的 agentic 编程任务中途遇到一次 529，不得不从头开始。

新增段落 ≥200 字（§7.5 开头）

异步 Agent 跑起来之后，UI 上 "in progress" 的一行字会让用户失去耐心。Claude Code 给出的解法不是改 UI，而是再开一个 Agent —— services/AgentSummary/agentSummary.ts 实现了一个 30 秒一拍的后台摘要器，定时 fork 当前对话，让模型自己用 3-5 个英文单词描述"我此刻正在做什么"，再把这句话写回 AgentProgress 供前端显示。整段实现里最值得抄的不是 fork 本身，而是它保护 prompt cache 的方式。每一拍生成摘要，子请求必须和父请求共用同一个 cache key，否则每 30 秒就要为整段历史付一次全价。

新增段落 ≥200 字（§7.5 收尾）

这段代码中唯一被注释着重提醒的"反直觉"细节：禁用工具必须走 canUseTool 回调，绝不能改 tools: []。后者会改变请求的 cache key（工具列表是 key 的一部分），整段历史的缓存瞬间作废；前者只在调用阶段拒绝，请求本身仍然把完整工具集发出去，cache 才能继续命中。第三步是它没做的事 —— 源码注释花了 8 行篇幅说为什么不能设 maxOutputTokens：它会被向下传到 thinking config 的 budget_tokens，而 thinking config 本身也参与 cache key，一个看似无害的"省点输出"会让所有缓存全部失效。

段落统计

• 留存原段：N ≈ 全部（C-1 留存率 99.6%）
• 修改段：M = 0
• 新增段：K ≈ 12（§1.5 三段 + §7.5 九段，含 2 段代码注释引用）
• 满足 N ≫ M+K。

manifest diff 摘要

新覆盖目录（首次进入 C14）：

• services/AgentSummary/agentSummary.ts（30s 后台摘要器）
• commands/agents/agents.tsx + components/agents/AgentsMenu.tsx 等（/agents 交互式管理入口）

未新增或删除 v1 既有锚点。tools/AgentTool/、utils/forkedAgent.ts、constants/tools.ts、tools/AgentTool/agentMemory.ts、tools/AgentTool/forkSubagent.ts、tools/AgentTool/built-in/* 全部沿用。

CI 闸验证（本地）

• C-1 prose-diff-ratio：OK（留存率 99.6%）
• C-2 heading-preservation：OK（11 个 v1 标题全部保留）
• C-3 code-ratio：skip（C14 非新章）
• C-4 section-titles：OK（35 个标题全部合规）
• check-source-commits：OK（6 个文件指向 290fdc9）
• lint-no-fuzzy-quantifiers：OK
• lint-no-revision-codenames：OK
• check-no-frontmatter-in-chapters：OK
• lint-no-spec-jargon-in-prose：OK

合并说明

请尧哥 review 后手动合并，本 PR 不自动合。