版本更新记录

§新新增卷三：AI 协同（2026-09-15）

新增一章 35 AI 协同：仓库如何与 agent 一起写代码。前 34 章读的是「dsh 是什么」，这一章读的是这个仓库本身怎么被写出来——它的 agent 协同基建。

覆盖内容（六个小节）

§1站点当前状态

§00000000最新：0.1.6-alpha.2 → 0.1.7-rc.1 同步（2026-09-23）

本轮 pull 的变更量：1617 个提交、5142 个文件。这是站点历次同步里跨度最大的一次——四处破坏性 API 变更，15 个页面、159 处锚点漂移。

① 会话格式升到 V4：developer/message 与 forked—— 06 页新增 §1d

② Shell 契约合并：run + start → execute—— 15/16/17 页

③ 分辨率子系统收敛为单一路径—— 02/04 页

④ CLI 新增 --dump-config-schema—— 00/01 页

⑤ 其他机制变更（站点已同步）

• abortedCancelCause()（05 页新增 §6，agent.ts:79-94）：取代裸的 signal.reason as AgentCancelCause 断言。重建一个干净的 { kind } 对象，丢掉 Node 附加的 stack——否则 Session.append 要么把它写进日志、要么因非 JSON 序列化而拒绝。这是 agent.ts 620→647 行的全部来源。
• 新增 packages/boot/plugin-manager/（2227 行，12 文件）：插件安装/卸载的完整生命周期，含 build-approval、install-spec、run-tree、registry。apps/cli/src/plugin.ts 因此大幅瘦身。
• 新增 packages/boot/config-editor/；packages/boot/ 现为 5 个子包（app-boot / cmdline / config-editor / hmr / plugin-manager）。
• 新增顶层分组：packages/code-runtime/、packages/e2b/、packages/examples/、packages/deliverables/、packages/document/。
• 配置系统迁到 schemastery .volatile()：bash-local 的 graceMs 等改为 this.config.graceMs.get() 访问器；agent-loop 的 maxParallelToolCalls 同理（tool-calls.ts:132）。
• app-boot 新增模块：compatibility-preflight.ts、config-schema/（7 文件）、package-meta.ts、plugin-compatibility.ts、profile-compatibility.ts——profile.ts 的旧职责拆出。
• tool 新增 projectContent 钩子（tools/src/index.ts:245）：在 tools/post-execute 策略之前安装执行预备内容。
• runtime-context 成为一等消息来源：新增 MessageSourceMap 增强声明，SOURCE 从 '@deepseek-ai/dsh-system-prompt' 改为 'runtime-context'。
• session-persistence-jsonl（1647→1725 行）：历史会话的 subagent 子会话目录迁移、corpus revision、listGenerations() 与 listArtifacts() 拆分。

⑥ 本轮同步的锚点工作

15 个页面、159 处锚点漂移。位移与语义变更交织：agent.ts +27、surface.ts +56、types.ts +23、app-boot/index.ts +53、profile.ts −227、args.ts +15、bin.ts −7、tool-bash +187、bash-local +34、shell/index.ts −8。_verify.py 全程用于定位与复验，最终 0 差异；结构检查同样 0 问题。

§00000000.1.6-alpha.1 → 0.1.6-alpha.2 同步（2026-09-16）

本轮 pull 的变更量：882 个提交、2548 个文件。核心是一次启动链的多重重构——热重载独立成包、CLI 参数模型更换、启动失败有了诊断落盘。站点 11 个页面受影响，66 处锚点漂移。

① 热重载独立成包：packages/boot/hmr/—— 04 页 §3 重写

② CLI 参数模型：web 子命令 → 通用前缀展开—— 00/01 页更新

③ 启动失败诊断—— 00 页新增 §5，03 页 §4 更新

④ 其他机制变更（站点已同步）

• Inbox 投影注册移交（07 页）：ReactLoopInbox 的构造器现在是空的 ) {}——注册职责移到 AgentLoop（agent-loop/src/index.ts:416-417，与 turnBoundary 一起注册）。inbox.ts 247→244 行。
• Profile.patchReload 字段删除（02 页）：profile 不再声明热重载策略——HMR 服务读 profileContext 就知道该观察什么。相关校验代码整段消失，PROFILE_TEMPLATES 条目从两行压成一行。
• resolvedProfile / packageManager（04 页）：RunProfileOptions 新增两个字段，让打包应用（Electron desktop）交来自己已加载的 profile，绕过 $DSH_HOME 命名查找。
• 分辨率模式默认值翻转：resolutionMode 的默认从 'link' 改为 'runtime'——内存路由表成为常规路径，symlink 物化退化为可选。
• app-boot 三个新模块：profile-context.ts（75 行，readProfilePatches 接手五层组装 + 遥测 patch）、profile-plugins.ts（127 行，插件清单读写）、profile-sanitize.ts（34 行，文件系统恢复）——内容分别从 profile-boot.ts 与 apps/cli/src/plugin.ts 搬出。
• initProfile 签名简化：(dir, bundles, patchReload) → (dir, bundles)。
• 新增 skill-office 包：内置 Word/PPT/Excel 工作流（3 个 SKILL.md + Python 结构检查脚本）。注意这是产品包（packages/skill/），与仓库自己的 .agents/skills/ 不同层。
• llm 微调：discoverModels 透出 inputModalities（llm/src/index.ts:617）——模型发现时一并报告模态能力。

⑤ 卷三的数据刷新

本轮同步顺带更新了 35 页的统计：Agent Notes 1028 → 1105 篇（implemented 355→424、archived 629→635），scripts/*.ts 226 → 230 个。这本身就说明这套协同基建在持续运转——每轮同步看到的数字都在长。

⑥ 本轮同步的锚点工作

11 个页面、66 处锚点漂移。位移主要来自 app-boot/index.ts +66（新增日志收集与 StartupError）、profile-boot.ts −76（热重载迁出）、args.ts −15、inbox.ts −3、llm/index.ts +1。_verify.py 全程用于定位与复验，最终 0 差异；结构检查（内部链接、锚点、标签平衡、页脚版本）同样 0 问题。

§0000000.1.5-rc.2 → 0.1.6-alpha.1 同步（2026-09-15）

本轮 pull 的变更量：666 个提交、3123 个文件。核心语义变更三个主题，另有一次破坏性重命名。

① 插件消息投影：surface 的第三种变换—— 06 页更新

② profile 分辨率子系统：内存路由表—— 04 页新增 §1c

③ 启动审计分级 + shell 后台执行支持—— 03/15/16 页更新

④ 其他机制变更（站点已同步）

• runMaintenance 的 disposed 守卫（agent.ts:173-174）：收敛时先查 abort 原因，disposed 不再重放唤醒。
• AgentLoop.publish 变 async（agent-loop/src/index.ts:216）：创建监听器现在会在 disposal 前被 await（publication promise），避免它们在 teardown 中途还持有 session。
• system-prompt 的 interpolate: false：section 可声明不做变量插值（保留字面文本）。新增 TOOL_COMPUTER_USE: 3000 / MCP_SERVERS: 3100 两个 order 常量。
• code-runtime 全线改名 ptc-runtime：packages/code-runtime/ → packages/ptc-runtime/，CodeRuntime → PtcRuntime，CodeSdkLanguage → PtcSdkLanguage。
• workflow 引擎迁进 PTC 运行时：packages/workflow/workflow-worker-thread/（1987 行）整体删除，由 packages/workflow/workflow-ptc/（1321 行）取代——PtcWorkflowEngine 的 inject 变成 ['subagents', 'ptcRuntime', 'sandboxPolicy']，编排脚本从 worker 线程搬进沙箱（25 页已更新）。
• mcp-client 精简：src/index.ts 188→203 行，重活拆到 connection.ts/tools.ts/transport.ts，新增 server-context.ts 与 maxInstructionBytes 选项。
• 会话格式迁移器出现：新增 packages/session/session-format-v0-to-v1/、-v1-to-v2/、-v2-to-v3/ 三个迁移包——0.1.5 引入的 v3 断点现在有了显式升级路径。

⑤ 本轮同步的锚点工作

15 个页面、98 处锚点漂移。主要位移来源：agent.ts +1、session/index.ts +33、surface.ts +96、system-prompt/index.ts +8、tools/index.ts +19、app-boot/index.ts +83、profile.ts +92、profile-boot.ts +21、bash-local/index.ts +28。_verify.py 全程用于定位与复验，最终 0 差异；结构检查（内部链接、锚点、标签平衡、页脚版本）同样 0 问题。

§000000.1.3-alpha.2 → 0.1.5-rc.2 同步（2026-09-11）

跨两个 minor 版本（0.1.3 → 0.1.4 → 0.1.5）的一次同步。核心语义变更一个主题：system prompt 从请求头字段迁移为 surface 事件——它连带改了会话格式版本、step 的结构、以及适配器的一个能力位。

① system prompt 迁为 system/message surface 事件—— 05/06/08/09/11/12 页更新

② --from-default-profile：用模板初始化自定义 profile—— 00/01/04 页更新

③ 其他机制变更（站点已同步）

• turn 的提前收敛：agent.ts:294 新增 if (turnEnds && decision.messages.length === 0) break——终局已定且无新输入就不再空跑一次 step。
• step 的 firstAttempt 标志（agent.ts:360）：重试循环里 user/message 与 system/message 只在首次尝试落盘一次，避免重试时重复注入。
• inbox 的 unban / splice 语义：determineStartOfRevertedRange 逐槽取 Math.max，负 startIndex 的钳制更精确。
• session/end-seed 拆分：Session.fromRestore（530-544 行）成为静态工厂，私有构造器带 5 个参数（546-552 行）。

④ 站点级修正（本轮新发现的历史错误）

• packages/host/apiproxy/ 不存在——32 页曾引用它。该包在 0.1.2-alpha 之前就被删除（4f00a8b82a refactor(api): remove ApiProxy package），任何发布标签里都查不到。已改指 packages/api/gateway/（11 文件 / 4391 行，TypertGatewayService @ src/index.ts:169）。
• system-prompt/assemble 是连字符不是斜杠——12 页曾写作 systemPrompt/assemble，全仓库 0 命中。真实事件名声明在 system-prompt/src/index.ts:31，派发在 617-620 行。
• 20 页的 static inject = ['sessions'] 在 jsonl 后端里并不存在——它靠基类 super(ctx, 'sessionPersistence') 注册（session-persistence-jsonl/src/index.ts:261）。已补上格式版本守卫（263-268 行）。
• 03 页 boot 代码块缺 </code></pre> 闭合标签——预先存在的 HTML 结构错误，导致后续块边界错位。已修复。

⑤ 校验方式升级

本轮起站点带一个可执行的锚点校验器 _verify.py：扫描所有 HTML 里 <figcaption> 标明的文件路径与每个 <span class="ln"> 行号，去上游源码取对应行、按标识符集合做模糊比对（容忍折叠签名与中文尾注）。当前全站 0 差异。以后的同步只需重跑它即可定位所有漂移。

§00000.1.3-alpha.1 → 0.1.3-alpha.2 同步（2026-09-08）

本轮 pull 的变更量：4345 个文件、+90046/-19843（含 alpha.2 与大量 web/CI 合入）。站点锚定文件里的核心语义变更两处：

① Inbox 迁移为 session projection—— 07 页重写

② bin.ts 抽出 runCli—— 00 页更新

③ 其余行号位移（站点已同步）

• session/index.ts 1254→1248：Session 类 451→422、构造器 541→522、append 699→678、eventAt 618→597、ownEvents 645→624、deriveMessages 820→799；session/end-seed 新增 { inherited: true } 变体（583 行）。
• session/types.ts 483→489：SessionEvent 447→453、assistant/attempt 313→319、RequestHeaderReason 252→258。
• system-prompt/index.ts 614→630：assemble 536→552。
• app-boot/profile.ts 861→853：PROFILE_TEMPLATES 137→110、新增 loadProfileDirectory（774 行）、manifest 类型迁到 @deepseek-ai/dsh-package-manifest。
• app-boot/index.ts 862：boot 790→787、assertEntriesActivated 725→722。
• tool-bash 393：apply 190→189、defineTool 242→241、execute 330→329。

§0000.1.2-rc.1 → 0.1.3-alpha.1 同步（2026-09-05）

本轮 pull 的变更量：1672 个文件、+43229/-14119。站点锚定文件里的核心语义变更：assistant-stream 机制重构（一处大主题）+ 文件引用投影：

① assistant-stream 机制（assistant/chunk 退役）—— 05/06/10/11 页更新

② 文件引用投影—— 10 页更新

③ 其余影响面

• agent.ts 行号位移（preStep 234→237、turn 255→258、kick 219→222、wakeDriver 181→184、send 122→125、setPhase 113→116、buildRequest 444→488）——05/08/09 页已全面重映射。
• session/index.ts 行号位移（append 668→699、构造器 514→541、deriveMessages 790→820、firstLiveSeq 555→581）——06 页已重映射。
• llm/index.ts 行号位移（prepareCall 890→904、adapterStream 964→998、streamWithRegistration 1055→1097、forAdapter 944→958）——09/10 页已重映射。
• 06 页真实 fixture 行更新为 assistant/attempt 格式（v2）。

§000.1.2-alpha.3 → 0.1.2-rc.1 同步（2026-09-04）

本轮 pull 的变更量：2682 个文件、+46669/-33253。站点锚定文件里的实质语义变更集中在一处大主题（session 序列品牌化）与两处引导层变化：

① Session 序列品牌化（SessionSeq / SessionLogOffset）—— 06/07/13 页更新

② HTTP 代理引导—— 03/04 页更新

③ 其余影响面（站点未覆盖或行号位移）

• packages/core/agent-loop/src/index.ts（713→915 行）：AgentLoop 生命周期重构——StoredSession 写句柄与 storedCount、SessionPersistenceNotFoundError 判断「真缺失」、配置启动失败 trackStartup 追踪。
• packages/core/agent-loop/src/{agent,tool-calls,runtime-context}.ts：仅 SessionSeq 类型化（chunkSeqs/callSeqs 等），行号未变；13 页 trace 里 167→168 已修。
• packages/core/agent/src/index.ts（±21）：AgentRegistry 细节调整。
• 各包 invariant.ts 有删减（bash-local/shell/tool-bash/subprocess-local 的 invariant 移除）——站点未深入。

§00.1.1-rc.2 → 0.1.2-alpha.3 同步（2026-09-01）

本轮 pull 的变更量：7036 个文件、+355256/-144539（rc.2 之后两个 alpha 版本的全部合入）。站点锚定的核心文件有大批语义变更，逐页处理如下：

① request/header 的 series 维度—— 05/08/09/11 页更新

② LLM：TypertRemoteService 与 @Remote—— 09/10 页更新

③ 提示词 SECTION_ORDERS 中央分配表—— 12 页更新

④ profile 层重构—— 02/03/04 页更新

⑤ 其余（站点未覆盖或无需改动）

• apps/cli/src/bin.ts（53→50 行）：头部 JSDoc 精简，代码未变——00 页行号重映射。
• packages/core/tools/src/：code-mode.ts 改名 ptc.ts（PTC 传输）；ts-types/py-types 同步调整——14 页提到 code-mode 的句子已随主链行号更新，未深挖改名细节。
• packages/core/session/src/：json.ts 移除（无损 JSON 工具迁入 @deepseek-ai/dsh-util-values）；新增 seq-ranges.ts（seq 区间编解码）；chunk-rows.ts +56 行。
• packages/subprocess/subprocess-local/：process-inspector.ts +275（重写）、windows-inspector.ts ±29、terminal.ts ±36——16 页「下层职责」描述仍成立。
• packages/llm/llm/：never.ts / call-config.ts 部分删除（assertNever 等迁入工具包），brand.ts +28（ToolCallId 等新品牌类型）。

§2示例贯穿：全书配套真实轨迹（2026-08-23）

用户反馈：纯讲解难吃透，要带入示例看。新增「示例轨迹」组件（米色 .trace 块），全书 33 页每页一个「示例」节：

• 卷零（00-04）：用真实命令 pnpm dsh web 贯穿——真实 argv 分解、本机真实 profile 目录（~/.dsh）、真实 dump-config 输出（135 个条目）、真实 help 文本、五层补丁的真实内容。
• 卷一（05-17）：用一条消息「帮我列一下当前目录」贯穿——完整的 turn/step 事件序列（seq 0-16 逐条标注）、真实 fixture 的 JSONL 行格式（plain-turn）、inbox 三个 splice、preStep 四动作实况、请求折叠、流 chunk、压缩/取消/interrupted 分支。
• 卷二（20-34）：每章配该能力域的实况轨迹（持久化的崩溃恢复、压缩的 replace 事件、子代理的血缘头、审批的升级流程等），并与卷一的 seq 序列交叉引用。
• 所有示例标注「来源」行（真实文件/真实行号/真实输出），与解读严格分离——轨迹是可复现的数据，不是叙事。

§3结构性重构：从叙事到全书（2026-08-23）

用户反馈：旧结构只讲了「叙事逻辑」（核心机制的故事），没有把整个项目线性地讲清。重构为三卷全书结构：

• 卷零 · 入口与组装（00-04）：从 bin.ts 到活插件树的完整启动链。
• 卷一 · 核心循环深读（05-17）：一条消息的一生 + shell 旁支。
• 卷二 · 能力全景（20-34，新增 15 章）：按 cordis.patch.yml 挂载顺序遍历每一个能力域——20 持久化、21 压缩、22 子代理、23 技能命令、24 目标计划、25 工作流任务、26 文件系统、27 终端 LSP、28 Web、29 审批沙箱、30 存储查询、31 设置凭据、32 SDK/API、33 客户端/Python/Native、34 工程基础设施。每章统一结构：挂载条目 → 包文件地图 → 机制 → 与卷一连接点 → 关键代码 → 易错点。
• 导航改为三卷分组；新增 assets/nav.js 共享导航。

§4rc.7 → 0.1.1-rc.2：同步（2026-08-21）

本轮 pull 的变更量：3319 个文件、+83084/-21535（含两个 rc 版本的全部合入）。站点锚定的 18 个文件里有实质语义变更的集中在四处，均已更新：

① 取消时固化文本前缀（interrupted 锚点）—— 11 页更新

② LLM 调用代际绑定（adapter prepareCall）—— 09/10 页更新

③ DeepSeek 文件管理策略（站点未覆盖，仅记录）

④ 其余影响面（无需站点改动的记录）

• packages/boot/app-boot/src/index.ts：环境剥离名单（BOOTSTRAP_NAMES）新增 BROWSER（100 行附近）——boot 链语义未变。
• packages/core/session/src/known-event-types.ts：登记 team/member、team/message/delivered、team/message/queued、team/task 四个新事件类型（团队功能扩展了事件词汇表）。
• packages/subprocess/subprocess-local/：新增 windows-inspector.ts（325 行）——Windows 进程表探测；terminal.ts +74 行（PTY 前台进程组）。旁支 16 页的「下层职责」描述仍成立。
• packages/llm/llm/src/retry-policy.ts：±10 行调整，重试策略结构未变。

§5rc.5 → rc.7：首轮同步（2026-08-19）

首次同步时上游从 rc.5 升到 rc.7。当时站点精读的核心文件几乎没动，只有一处实质语义变更：

• assembler.ts 的 max-tokens keep/drop 收敛（PR #2596 deepseek-maxToken-consistency）：新增 assembled() 统一决策——blocks() 与 replayState 同源派生，max-tokens 截断丢弃无法安全执行的 tool-call 块；replay envelope 块数不对齐时 replayState 归 undefined。已写入 11 页。
• 8 处文件行数修正（session/index.ts、surface.ts、tool-calls.ts、bash-local、subprocess-local、spawn.ts、tool-bash）。
• code-mode 提示词文案微调（图片子工具结果 attach 到 run 之后）——站点未覆盖，未更新。

§6同步方法（供后续复用）

每轮 pull 后的标准流程：

1. git pull --ff-only，记录新 HEAD 与 release 版本。
2. 圈定影响面：git diff --stat <旧版本tag/commit> HEAD -- <站点锚定的目录>——只有站点引用的文件变更才需要动站点。
3. 逐文件 diff：对每个有变更的锚定文件 git diff，判断是「行号位移」（只改行号）还是「语义变更」（重写内容）。
4. 重验证锚点：对站点引用的每个 file:line，用 grep -n/sed -n 核对新位置的符号是否还是原来那个。
5. 批量更新版本号：sed -i 's/0\.x\.y-rc\.N/新版本/g' *.html。
6. 语义变更写进对应页 + 本页：凡上游改了行为，对应页的解读必须跟上，并在本页留档。
7. 校验：残留旧版本号扫描、坏 SVG 属性扫描、内部链接检查。
8. 提交：站点是独立 git 仓库（coldingcode.github.io），commit + push。