21. 二十个知识维度的源码索引
21. 二十个知识维度的源码索引
| 维度 | Claude Code 主入口 | Codex 主入口 | DeepSeek Harness 主入口 | 工程验证抓手 |
|---|---|---|---|---|
| Harness | query.ts、toolOrchestration.ts | session/turn.rs、tools/router.rs | bundle/base/cordis.patch.yml、boot/app-boot | 六个平面与可替换组装 |
| Runtime | StreamingToolExecutor.ts | tasks/regular.rs、session/turn.rs | core/agent-loop/src/agent.ts | 状态机、取消、并发 |
| Multi-Agent | AgentTool/*、teammateMailbox.ts | agent/control/*、agent_communication.rs | subagent/*、tool-subagent* | 路由、血缘、任务所有权 |
| Agent Loop | query.ts | session/turn.rs | core/agent-loop/src/agent.ts | Turn/Step 与 sample-act-observe-stop |
| Skill | SkillTool.ts、skills/* | ext/skills、skills.rs | skill/skill、skill-filesystem、tool-skill | 发现、加载、调用权限、Scope |
| MCP | services/mcp/client.ts | mcp_tool_call.rs、session/mcp.rs | mcp/mcp-client/src/{connection,tools}.ts | 连接代际、命名、超时、原子换代 |
| 长期记忆 | extractMemories.ts | memories/* | session-query/*（只是可检索基础） | 抽取、验证、索引、缺口边界 |
| 短期记忆 | Session Memory、Compact | ContextManager、TurnState | core/agent/src/inbox.ts、session-projection | Working Memory 与事实日志 |
| 上下文压缩 | services/compact/* | compact.rs | compaction-basic、compaction-tool-result-pruner | 压力触发、Surface replacement、有界重试 |
| 上下文窗口 | token 预算与 Compact | session/context_window.rs | llm/token-meter、llm.resolveModelInfo | 请求包络、容量、模型特定策略 |
| Prompt Engineering | Prompt 常量与 Tool prompt | prompt templates/spec | core/system-prompt、core/tools | 带顺序、Scope 与生命周期的编译 |
| Context Engineering | attachments、fork context | context_manager/*、WorldState | context/*、agent.inject() | 来源、排序、注入、可重建 |
| 交互体验 | Streaming executor、审批 UI | Protocol Event、TUI/App Server | host/apiproxy、client/ui-* | 事件投影、断线恢复、可操作终态 |
| Tool Use | toolExecution.ts | tools/* | core/tools、agent-loop/tool-calls.ts | 校验、策略、有界并发、有序提交 |
| Memory | Memory + Skill + Transcript | Memories + Rollout | Session Log/Surface/Projection/Query | 类型、写入权、失效与 provenance |
| Planning | PlanMode、Task tools | Plan mode、update_plan | plan-mode、goal、tool-todo、workflow | 协作模式、目标、清单、执行分离 |
| Session | sessionStorage.ts | session/*、rollout/* | core/session、session-persistence、session-projection | Turn/Step、barrier、恢复、投影 |
| 可观测 | utils/telemetry/* | otel/*、turn_timing.rs | session-telemetry、session-telemetry-otel | Ledger/Ops、脱敏、共享策略 |
| 权限 | utils/permissions/* | PermissionProfile、Approval | user-approval、permission-presets | 失败关闭、审计对、委派递减 |
| 沙箱 | sandbox-adapter.ts | sandboxing/*、linux-sandbox/* | sandbox-policy、sandbox-local、fs/bash-sandbox | Policy 编译、共享根目录、OS enforcement |
21.1 如何用索引追踪端到端原理
索引不是“建议阅读的文件列表”，而是调用链起点。选择一个真实问题，例如“用户批准 Bash 后命令怎样执行并恢复”，先从 Loop 找到 ToolCall 创建点，再追 Router、参数规范化、Permission Decision、Sandbox backend、ToolResult、Rollout 和 UI Event；每跳记录输入类型、输出类型、稳定 ID、失败分支和所有者。若只读 permissions 目录，就无法验证批准的参数是否与沙箱执行参数相同。
推荐为每个维度画一张五列证据表：领域对象 | 创建/迁移点 | 持久化事实 | 强制边界 | 用户可见事件。例如 MCP Tool 的领域对象由连接快照创建，迁移点在 Tool Handler，持久化事实是调用及结果，强制边界是权限与远端认证，用户事件是进度/审批/终态。两套源码若对象名称不同，就比较不变量而不是强行一一对应。
源码演进后先用 rg 搜索类型和事件名，再重新确认相邻调用。文档中的行号只用于当前快照定位；工程实践真正应记住的是“哪一层拥有状态、哪一层实施约束、失败后从哪条持久化记录恢复”。
21.2 Claude Code：从产品入口到持久化与安全边界
图表加载中…
阅读这张图时不要把箭头理解成唯一函数调用；它表示稳定职责链。最值得追踪的三个闭环是：ToolUse → ToolResult → 下一次 query、Session JSONL → Recovery → query、Permission Decision → Sandbox Execution → Audit Event。若某个实现改名，只要这三个闭环仍存在，整体原理就没有改变。
21.3 Codex：从 RegularTask 到 Tool Handler 与 Rollout
图表加载中…
Codex 需要重点区分 History 与 Rollout：History 服务当前模型采样，可以裁剪和压缩；Rollout 服务恢复与回放，不能因为 Context 窗口不足而删除关键事件。源码追踪时可从 run_turn 分别沿“模型输入链、工具执行链、持久化链”向下阅读，再用相同的 turn_id/step_id/call_id 把三条链重新连接。
21.4 DeepSeek Harness：从 Profile 组装到可恢复 Session
图表加载中…
这张图的核心是两类可替换边界：Cordis 插件树决定“当前组装了什么”，Capability seam 决定“同一能力由哪个 Provider 实施”。Agent Loop 只依赖 Session、System Prompt、LLM 和 Tool Runtime 主干；文件系统、Shell、MCP、Subagent、安全、界面和遥测都在事件或 Service 扩展点上组合，避免为每项产品功能修改循环。
详细阅读应从第 27 章开始：先用 Bundle 确认产品实际组装，再沿 Agent Loop 追一次 Turn，沿 Tool Runtime 追一次受控副作用，最后沿 Session Event 分别追到 Persistence、Projection、UI 和 Telemetry。若只阅读某个包 README，尚不能证明它已进入当前 Profile 的实际运行链。