第 14 章
附录 B：语料与检索记录
使用说明
正文 12 章的横向对比都检索过对比语料。读者判断这本书可信度时，三样东西需要能对账：所有引用锚定的语料版本、每章检索过什么词、哪些机制确认没有找到实现。这个附录就是这张对账表。
三块内容对应三个小节。第一节是语料锚点：两个仓库的 commit 与 tag 记录，以及「对比语料公开仓库已无主产品源码」这个事实的实测证据。第二节是各章检索关键词索引：12 章横向对比段的检索关键词与结论，逐章一行。第三节是「未找到实现」清单：正文明确声明找不到实现的对象、检索关键词与补足方式。
口径说明：commit、tag、日期来自 git 记录，2026-08-23 实读核实；正文位置是 chapters/ 目录下的相对路径加行号，指向检索交代所在行；行数一律用 splitlines() 口径；引用块与正文一样逐字节核对，行号实读。
一、语料锚点
1. 主教材：deepseek-harness
| 项 | 值 |
|---|---|
| 仓库 | deepseek-ai/deepseek-harness |
| commit | b150a551b8（b150a551b8d465e31e418e1b2eaf5e79bbb7d28e） |
| 提交日期 | 2026-08-21 |
| tag | course-anchor-20260823 |
| 提交主题 | Merge pull request #2908 from deepseek-harness/release/dsh-0.1.1-rc.2 |
本书 12 章正文与附录 A 的全部引用块都以这个 commit 为锚，tag course-anchor-20260823 指向同一 commit。
2. 对比语料：claude-code
| 项 | 值 |
|---|---|
| 仓库 | anthropics/claude-code |
| commit | 45bdfa96（45bdfa96ca415da92e62b6ca85a1d6e29adf3c44） |
| 提交日期 | 2026-08-23 |
| tag | v2.1.241 |
| 提交主题 | chore: Update CHANGELOG.md and feed.xml |
CHANGELOG 顶部版本号与 tag 一致：
claude-code/CHANGELOG.md3:3
3## 2.1.241README 里的一句话产品定位：
claude-code/README.md7:7
7Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows -- all through natural language commands. Use it in your terminal, IDE, or tag @claude on Github.3. 公开仓库已无主产品源码（实测结构）
产品是终端 CLI，二进制发行，公开仓库不含主产品源码。2026-08-23 对锚点 commit 的实测结构：
- 顶层没有
packages/目录，也没有任何主产品源码目录。 - 顶层 9 个目录：
.claude、.claude-plugin、.devcontainer、.github、.vscode、Script、examples、plugins、scripts。 - 顶层 8 个文件：
CHANGELOG.md（5763 行）、README.md、SECURITY.md、LICENSE.md、feed.xml、demo.gif、.gitattributes、.gitignore。 - 全仓 .ts/.js 文件共 5 个，全部在
scripts/下：auto-close-duplicates、backfill-duplicate-comments、issue-lifecycle、lifecycle-comment、sweep，都是 GitHub issue 维护脚本。scripts/另 3 个 .sh（comment-on-duplicates.sh、edit-issue-labels.sh、gh.sh），Script/1 个 .ps1（run_devcontainer_claude_code.ps1）。 - 全仓文件总数 229（不含 .git）。
plugins/README.md 第 3 行说明 plugins 目录的性质，是官方插件示例，不是主产品：
claude-code/plugins/README.md3:3
3This directory contains some official Claude Code plugins that extend functionality through custom commands, agents, and workflows. These are examples of what's possible with the Claude Code plugin system—many more plugins are available through community marketplaces.4. 这个事实对对比深度的含义
主产品实现不在公开仓库，直接限制横向对比的深度：两侧实现细节无法逐行比对，对比语料侧只能依赖三类公开材料，正文 12 章全部按这个边界写作。
- CHANGELOG 行为记录。5763 行的变更日志是主产品变更的投影，正文第 3、6、7、8、9、10、11、12 章用它补足。两个数字可复现：按大小写不敏感且限定 64 至 1248 行的口径检索 bash，得 40 条，对应第 7 章正文「检索含 Bash 的条目共 40 条」；按含 transcript 的口径检索，得 115 处，对应第 3 章正文「CHANGELOG 里 115 处相关修复记录」。
- examples/ 与 plugins/ 公开材料。示例配置、插件 agent 定义、插件开发文档，正文第 1、2、3、5、8、12 章直接引用。
- dsh 内部双实现或双视角对照。同一问题在 dsh 仓库内就有两种答案时，改为内部对照补足，两侧都是真实代码。第 4 章两套驱动（agent-loop 对 workflow worker-thread）、第 7 章两个 provider（bash-local 对 bash-sandbox）、第 10 章两个 adapter（llm-deepseek 对 llm-pi-ai）、第 11 章 subagent 对 workflow。
两条边界纪律贯穿正文与这个附录：
- 检索无果必须写明关键词与范围。正文按「未找到对应实现，检索关键词为 X、Y、Z」的格式声明，12 章共 12 处，第三节汇总。
- 拿不准的差异标推断。两侧差异可能是 dsh 主动改的，也可能是上游后来改的，正文在拿不准处明确写「按推断处理」，第 11、12 章有实例。
二、各章检索关键词索引
下表 12 行，逐章汇总横向对比段的检索记录。正文位置列指向该章检索交代所在行。
| 章 | 对比对象 | 检索关键词 | 结论要点 | 正文位置 |
|---|---|---|---|---|
| 第 1 章 一切皆插件：Cordis 的五个思想 | claude-code hooks 拦截机制 | cordis、packages/（均无命中） | 进程内监听可持状态、可卸载、可热重载，对进程外协议跨进程开销；dsh 把 hooks 协议做成桥接插件 | ch-01.md:500 |
| 第 2 章 从 cordis.yml 到运行中的树 | claude-code settings 层级 | cordis、SettingsMap、userSettings、loadSettings（0 个文件）、settings.local.json（2 个 examples 文件）、managed-settings（6 个 examples 模板） | 行 id 整份替换对固定层级逐键合并；加载合并实现不在公开仓库，层级行为按文档转述 | ch-02.md:827 |
| 第 3 章 会话日志：Model-visible ⟺ logged | claude-code transcript | transcript、jsonl、replay、resume（非 CHANGELOG 文件零命中实现代码） | 日志当数据源（版本整数、surface 投影）对副产品（JSONL 内部约定，损坏截断在 CHANGELOG 反复修） | ch-03.md:622 |
| 第 4 章 turn/step：ReactLoopAgent 的驱动循环 | claude-code 主循环 | main loop、agent loop、ReactLoop、turn、step、loop、transcript、session log、query | 未找到实现；改 dsh 内部对照：隐式数据驱动对显式脚本驱动 | ch-04.md:689 |
| 第 5 章 系统提示与工具 schema 组装 | claude-code 子 agent 工具集 | systemPrompt、assemble、allowedTools、subagent、tools:（只在 CHANGELOG 与 plugins、scripts 命中） | 运行时组合加过滤（活名单）对 frontmatter 静态声明（白名单加 disallowedTools 黑名单） | ch-05.md:738 |
| 第 6 章 工具执行管线与审批 | claude-code permission 机制 | permission、canUseTool、PermissionCallback | 未找到实现；行为记录推断权限检查在工具执行路径内、与命令解析器耦合；dsh 把决策抬到管线层 | ch-06.md:666 |
| 第 7 章 capability seam 解剖：shell 三件套 | claude-code BashTool | BashTool、tool-bash、toolBash、BashSandbox、spawn bash -c、bash -c | 未找到实现；行为记录补足；seam provider 独立版本化对单体发布周期 | ch-07.md:559 |
| 第 8 章 沙箱与进程树 | claude-code 沙箱 | sandbox、landlock、seccomp、seatbelt、bwrap、deny、permission、jail、restricted | 未找到实现；sandbox 只作用于 Bash 工具（README 27 行）；dsh 隔离是 capability seam，每次能力调用带 policy | ch-08.md:572 |
| 第 9 章 文件系统 capability 与策略 | claude-code 路径规则 | permission、allowlist、denylist、Edit(、Read(、permission rules、FileWrite、allowedDirectories | 规则长在工具层、与工具枚举耦合；dsh 事件闸门按事件接线，新工具自动过闸 | ch-09.md:452 |
| 第 10 章 LLM 适配层：twin adapters 与流式词汇 | claude-code 流式消费 | anthropic SDK、messages.stream、@anthropic-ai/sdk、content_block_delta、client.messages | 未找到实现；行为记录补足；上游对 SDK 与网关怪癖逐个打补丁对可见契约条款 | ch-10.md:637 |
| 第 11 章 委托与并行：subagent、workflow、goal | claude-code Task tool / AgentTool | Task tool、AgentTool、subagent_type、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | 未找到实现；行为记录补足；深度写进 durable header 从源头避免 | ch-11.md:418 |
| 第 12 章 协议边界：Typert、MCP、ACP、双 SDK | claude-code MCP 命名与 Agent SDK | json-rpc、agent-sdk、client、sdk、stdio、stream-json | MCP 命名有公开插件文档可实查（两种拼写同一骨架）；SDK 未找到实现，行为记录补足 | ch-12.md:519 |
三、已知「未找到实现」清单
12 章对比语料侧全部命中同一种情况：主产品实现不在公开仓库。按措辞分两类。严格句式「未找到对应实现，检索关键词为…」4 处，在第 4、6、7、11 章；等价句式 8 处，在第 1、2、3、5、8、9、10、12 章（写法分别是「均无命中」「没找到对应实现」「零命中实现代码」「解析逻辑在本仓库不可见」「未找到主产品沙箱实现源码」「没有主产品源码」「检索不到它的流式消费实现」「没有主产品 SDK 实现源码」）。
| 章 | 声明对象 | 检索关键词 | 正文位置 | 补足方式 |
|---|---|---|---|---|
| 第 1 章 | claude-code hooks 产品实现 | cordis、packages/ | ch-01.md:500 | examples/hooks 官方示例、plugins 目录、dsh hooks 桥接包对协议的理解 |
| 第 2 章 | claude-code settings 加载与合并 | cordis、SettingsMap、userSettings、loadSettings、settings.local.json、managed-settings | ch-02.md:827 | examples/settings/README.md、examples/mdm/README.md、settings-strict.json、CHANGELOG 304 与 357 行 |
| 第 3 章 | claude-code transcript 实现 | transcript、jsonl、replay、resume | ch-03.md:622 | plugins/ralph-wiggum 消费方脚本、CHANGELOG 修复记录（transcript 口径 115 处） |
| 第 4 章 | claude-code 主循环 | main loop、agent loop、ReactLoop、turn、step、loop、transcript、session log、query | ch-04.md:689 | dsh 内部双驱动对照、plugins/README.md:3 |
| 第 5 章 | claude-code agent 工具集解析 | systemPrompt、assemble、allowedTools、subagent、tools: | ch-05.md:738 | plugins/feature-dev 与 hookify 的 agent 定义文件、plugin-dev SKILL.md、CHANGELOG 4895 与 4733 行 |
| 第 6 章 | claude-code permission 机制 | permission、canUseTool、PermissionCallback | ch-06.md:666 | examples/hooks 示例、plugins/hookify rule_engine.py、CHANGELOG 106 与 299 与 435 行 |
| 第 7 章 | claude-code BashTool | BashTool、tool-bash、toolBash、BashSandbox、spawn bash -c、bash -c | ch-07.md:559 | CHANGELOG 行为记录（bash 口径 64 至 1248 行内 40 条）、dsh 双 provider 对照 |
| 第 8 章 | claude-code 沙箱实现 | sandbox、landlock、seccomp、seatbelt、bwrap、deny、permission、jail、restricted | ch-08.md:572 | examples/settings/settings-bash-sandbox.json、examples/settings/README.md:27、CHANGELOG 48 与 124 行 |
| 第 9 章 | claude-code 路径规则实现 | permission、allowlist、denylist、Edit(、Read(、permission rules、FileWrite、allowedDirectories | ch-09.md:452 | CHANGELOG 660 与 1574 与 1557 与 364 行行为记录 |
| 第 10 章 | claude-code 流式消费实现 | anthropic SDK、messages.stream、@anthropic-ai/sdk、content_block_delta、client.messages | ch-10.md:637 | CHANGELOG 19 与 216 与 282 与 315 与 530 行、dsh 双 adapter 对照 |
| 第 11 章 | claude-code Task tool / AgentTool | Task tool、AgentTool、subagent_type、CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS | ch-11.md:418 | CHANGELOG 751 与 1231 与 547 与 608 行、plugins/pr-review-toolkit 的 agent 定义 |
| 第 12 章 | claude-code Agent SDK 实现 | json-rpc、agent-sdk、client、sdk、stdio、stream-json | ch-12.md:519 | CHANGELOG 5057 与 4932 与 3191 行、plugins/plugin-dev 的 mcp-integration 文档 |
四、复查方式
读者可以沿三条路径复查本附录与正文。
- 升级语料重跑检索。claude-code 换新 commit 后，用第二节的关键词表重扫公开仓库，任何新命中都值得对照正文结论。
- 读官方文档。claude-code 官方文档站，以及公开仓库内 plugins/plugin-dev 下的插件开发文档，都能独立验证正文对公开材料的转述。
- 沿正文位置追踪。正文位置列的每一条都指向检索交代所在行，该行后面通常紧跟着补足证据的原文引用，可以逐段核对。
最后提醒一句：公开仓库不含主产品源码是时序事实，在 2026-08-23 的锚点上成立。上游若未来公开主产品源码，本附录第二节的检索记录依然可复现，第三节的结论边界需要重估。