Skip to content

REVISION-PLAN.md

Latest commit

 

History

History
128 lines (85 loc) · 5.74 KB

REVISION-PLAN.md

File metadata and controls

128 lines (85 loc) · 5.74 KB

文档修正计划

目标：补充源码级洞察，让每篇文档从"概念科普"升级为"逆向工程白皮书"水准。

第一梯队：空壳页，需要大幅重写

1. safety/sandbox.mdx — 沙箱机制 ✅ DONE

现状：35 行，只列了"文件系统/网络/进程/时间"四个维度，没有任何实现细节。

修正方向：

  • 补充 macOS sandbox-exec 的实际调用方式，展示沙箱 profile 的关键片段
  • 说明 getSandboxConfig() 的判定逻辑：哪些命令走沙箱、哪些跳过
  • 补充 dangerouslyDisableSandbox 参数的设计权衡
  • 加入 Linux 平台的沙箱差异对比（seatbelt vs namespace）
  • 展示一次命令执行从权限检查→沙箱包裹→实际执行的完整链路

2. introduction/what-is-claude-code.mdx — 什么是 Claude Code ✅ DONE

现状：39 行，纯营销文案，和"普通聊天 AI"的对比表太低级。

修正方向：

  • 砍掉"能做什么"的泛泛列表，改为一个具体的端到端示例（从用户输入→系统处理→最终输出）
  • 用一张简化架构图替代文字描述，让读者 30 秒建立直觉
  • 补充 Claude Code 的技术定位：不是 IDE 插件、不是 Web Chat，而是 terminal-native agentic system
  • 加入与 Cursor / Copilot / Aider 等工具的定位差异（架构层面而非功能清单）

3. introduction/why-this-whitepaper.mdx — 为什么写这份白皮书 ✅ DONE

现状：40 行，全是空话，四张 Card 只是后续章节标题的预告。

修正方向：

  • 明确定位：这是对 Anthropic 官方 CLI 的逆向工程分析，不是官方文档
  • 列出逆向过程中发现的 3-5 个最意外/最精妙的设计决策（吊住读者胃口）
  • 说明白皮书的阅读路线图：推荐的阅读顺序和每个章节解决什么问题
  • 补充"这份白皮书不是什么"——不是使用教程，不是 API 文档

4. safety/why-safety-matters.mdx — 为什么安全至关重要 ✅ DONE

现状：40 行，只列了显而易见的风险，"安全 vs 效率的平衡"只有 3 个 bullet。

修正方向：

  • 从源码角度展示安全体系的全景图：权限规则 → 沙箱 → Plan Mode → 预算上限 → Hooks 的纵深防御链
  • 补充 Claude 自身 System Prompt 中的安全指令（"执行前确认"、"优先可逆操作"等），展示 AI 端的安全约束
  • 用真实场景说明"安全 vs 效率"的工程权衡：比如 Read 工具为什么免审批、Bash 工具为什么要逐条确认
  • 加入 Prompt Injection 防御的简要说明（tool result 中的恶意内容如何被系统标记）

第二梯队：有骨架但太浅，需要补肉

5. conversation/streaming.mdx — 流式响应 ✅ DONE

现状：43 行，只说了"流式好"和 3 行 provider 表。

修正方向：

  • 补充 BetaRawMessageStreamEvent 的核心事件类型及其含义
  • 展示文本 chunk 和 tool_use block 交织的状态机流转
  • 说明流式中的错误处理：网络断开、API 限流、token 超限时的重试/降级策略
  • 补充 processStreamEvents() 的核心逻辑：如何从事件流中分离出文本、工具调用、usage 统计

6. tools/search-and-navigation.mdx — 搜索与导航 ✅ DONE

现状：43 行，只说 Glob 和 Grep 存在。

修正方向：

  • 补充 ripgrep 二进制的内嵌方式（vendor 目录、平台适配）
  • 说明搜索结果的 head_limit 默认 250 的设计原因（token 预算）
  • 展示 ToolSearch 的实现：如何用语义匹配在 50+ 工具（含 MCP）中找到最相关的
  • 补充 Glob 按修改时间排序的意义：最近修改的文件最可能与当前任务相关

7. tools/task-management.mdx — 任务管理 ✅ DONE

现状：50 行，只有流程 Steps 和状态展示的 4 个 bullet。

修正方向：

  • 补充任务的数据模型：id / subject / description / status / blockedBy / blocks / owner
  • 说明依赖管理的实现：blockedBy 如何阻止任务被认领、完成一个任务后如何自动解锁下游
  • 展示任务与 Agent 工具的联动：子 Agent 如何认领任务、报告进度
  • 补充 activeForm 字段的 UX 设计：进行中任务的 spinner 动画文案

8. context/token-budget.mdx — Token 预算管理 ✅ DONE

现状：55 行，预算控制只有 3 张 Card 各一句话。

修正方向：

  • 补充 contextWindowTokens 和 maxOutputTokens 的动态计算逻辑
  • 说明缓存 breakpoint 的放置策略：System Prompt 中不变内容在前、变化内容在后的原因
  • 展示工具输出截断的具体机制：超长结果如何被 truncate、何时触发 micro-compact
  • 补充 token 计数的实现：countTokens 的调用时机和近似 vs 精确计数的权衡

9. agent/worktree-isolation.mdx — Worktree 隔离 ✅ DONE

现状：55 行，只描述了 git worktree 的概念。

修正方向：

  • 展示 .claude/worktrees/ 的目录结构和分支命名规则
  • 说明 worktree 的生命周期：创建时机（isolation: "worktree"）→ 子 Agent 执行 → 完成/放弃 → 自动清理
  • 补充 worktree 与子 Agent 的绑定关系：Agent 结束时如何判断 keep or remove
  • 加入 EnterWorktree / ExitWorktree 工具的交互设计

10. extensibility/custom-agents.mdx — 自定义 Agent ✅ DONE

现状：56 行，只有配置表和示例表。

修正方向：

  • 展示 agent markdown 文件的完整 frontmatter 格式（name / description / model / allowedTools 等）
  • 说明 agent 如何被加载和注入 System Prompt：loadAgentDefinitions() 的发现和合并逻辑
  • 展示工具限制的实现：allowedTools 如何过滤工具列表
  • 补充 agent 与 subagent_type 参数的关联：Agent 工具如何指定使用自定义 Agent