2026-09-08

文档同步 2026-09-08

上游范围: b0a7d2ce3b4c..c389f96bf3a9（27 commits）

更新的文档章节

part4-web/ch17-web-client.md

新增 17.7 节交叉引用：

• 在 keyed slot 典型用例段落末尾添加右侧 Sidebar 的 sidebar.right.pane.tab keyed slot 用例说明，指向 17.20 节

新增 17.18 客户端资源模型（Client resources）：

• 描述 packages/client/resources 的统一资源抽象：地址（dsh-resource://<protocol>/<path>）+ 当前值
• 说明 useResource<T>(address) 标准 hook 与保留订阅机制
• 详述文件资源地址的两种作用域：session（相对会话工作区根）与 absolute（绝对路径）
• 解释 fileAddressFor / parseFileAddress 助手与 file 资源元数据（absolutePath, version, bytes, changed）
• 对应上游提交：
  • 3a85ac6d8 feat(resources): add Client resource registry and retained subscriptions
  • 4a4b86d9b feat(workspace-path): define Session and absolute file resource addresses

新增 17.19 工作区文件服务（Workspace Files）：

• 描述 packages/api/workspace-files 的两个 Remote 面：元数据面（stat/list/changes）与内容面（read）
• 说明按页读取机制：maxLines（默认 5000 行）与 maxBytes（默认 2 MB）上限
• 详述有界字节窗口（bounded byte windows）：本地（fs-local）与沙箱（fs-e2b）实现共享同一合约
• 列出失败码到用户句的映射：not-found/outside-workspace/too-large/not-text/not-regular-file/not-directory
• 对应上游提交：
  • f7b6a1332 feat(fs): define bounded byte-range reads
  • bc2174e3a feat(fs-local): implement bounded local byte windows
  • 442976344 feat(fs-e2b): implement cancellable sandbox byte windows
  • 4ce4f0bac feat(workspace-files): add dual-face file API and Host-resolved resources
  • 9f2b07cea feat(remotes): expose workspace file operations to the Client

新增 17.20 右侧 Sidebar 与停靠系统：

• 描述右侧 Sidebar 作为第三列（左：会话列表，中：对话，右：Sidebar）的定位
• 详述停靠基础设施（packages/client/ui-dockkit）：pane 的 drag/split/fullscreen、pointer 交互、布局持久化
• 说明三种显示模式：normal（并排展开）、fullscreen（小视口覆盖）、capacity-close（左列偏好挤零右列）
• 描述 tab 类型注册表（ctx.sidebarRightTabs）与档位认领：extension/builtin/fallback
• 详述三个随包交付的 tab 类型：
  • 引导页（ui-sidebar-right，kind=guide）：pane 的门，入口框栅格，chain fallback
  • 文本预览（ui-sidebar-textpreview，kind=text，patterns=['dsh-resource://file/**']，priority=fallback）：按页读取、按 tab 分桶的 Slot store、changed 提示不刷新
  • 文件树（ui-sidebar-files，kind=files）：页类型，不认领地址，懒加载目录列表
• 说明产品行为变化：Details 列移除，文件打开改道 Sidebar（7e017046c/108a7478c/a7c7e9965）
• 描述会话 Header corner slot（490955078）与 Sidebar 切换按钮
• 对应上游提交：
  • 9e7c57009 feat(dockkit): add reversible docking engine and pointer interactions
  • 9241e10a4 feat(layout): add responsive right column and width concessions
  • b67e0a838 feat(sidebar): add tab navigation, injected information, and fullscreen shell
  • b24ebc8cc feat(sidebar-files): add lazy workspace file tree tabs
  • d10af0654 feat(textpreview): add paged file tabs and retained reader state
  • 490955078 feat(conversation): provide the session header corner slot
  • 7e017046c refactor(chat): open file resources in the Sidebar and remove Details
  • 108a7478c refactor(tool-ui): route file navigation and remove ToolDetails
  • a7c7e9965 feat(deliverables): open produced files through Sidebar resources
  • 77690644b fix(sidebar): show full file paths and refine split and fullscreen controls
  • 4a60189a6 fix(layout): prepare destination widths before fullscreen retreat

更新 17.21 设计亮点小结（原 17.18，重新编号）：

• 新增第 11 点：客户端资源模型（useResource）与保留订阅
• 新增第 12 点：工作区文件服务的有界字节范围读取
• 新增第 13 点：右侧 Sidebar 的停靠与 tab 类型注册
• 新增第 14 点：会话 Header corner slot 与响应式右列几何

未影响文档的变更

以下上游变更未触发文档更新：

• 测试覆盖（fe5aee7e7/bd4199f48/755e3ceca/e73906d06）：Sidebar 交互、文件系统资源、文件订阅与 tab 生命周期的测试新增，不影响公开 API 或架构描述
• 包装配与目录清理（508831624 chore(web): assemble Sidebar domains and register workspace packages、08cfbd897 chore(api): remove stale session controller file dependencies）：内部包组织变化，ch2 仓库布局未在本书详细描述
• 目录与翻译哈希（4fef2786a chore: regenerate catalogs, dependency lock, and translation hashes）：自动生成文件，无架构影响
• 合并提交（c389f96bf、de01754f1）：PR 合并，无独立内容

变更总结

本次上游更新引入了 Web 客户端的右侧 Sidebar 系统，这是自词法 Composer 以来最大的 UI 架构变化。核心交付包括：

1. 客户端资源模型（useResource）：统一的"有名东西"读取抽象，地址是身份，订阅是状态，多个观察者共享同一份订阅
2. 工作区文件服务：把 Host 侧的文件操作拆成元数据面与内容面，底层提供有界字节范围读取（本地与沙箱共享合约）
3. 右侧 Sidebar：第三列可停靠 tab pane，tab 类型注册表按地址/档位认领，三个随包类型（引导页、文本预览、文件树）演示 keyed slot + chain fallback + 档位认领的完整模式
4. 产品行为变化：Details 列移除，文件打开改道 Sidebar；会话 Header 新增 corner slot 承载 Sidebar 切换按钮

这些变化为插件作者提供了完整的 tab 类型注册样板：查看器（textpreview）、页类型（files）、替换接缝（guide）各有可照抄的模式。

---

文档同步 2026-09-08（第二批）

上游范围: c389f96bf3a9..5dda764ed3aa（40 commits）

更新的文档章节

part3-core/ch10-session-log.md

更新 10.2 SessionEventMap 词汇表：

• 新增 system/message 事件类型（V3 格式）：系统提示词作为 surface 节点，渲染后的提示词住在 surface 上而非 request/header
• 更新 request/header 描述：V3 起不再包含系统提示词（system 字段）

更新 10.3 SessionEvent 类型定义：

• seq 字段类型从 number 改为 SessionSeq（品牌类型）
• sourceEventSeqs 类型从 number[] 改为 SessionSeq[]（品牌类型）
• surfaceOp 从可选（?）改为必填
• SurfaceEventType 从三种扩展为四种：新增 system/message

更新 10.4 Surface 派生历史：

• Surface 事件从三种扩展为四种（system/message、user/message、assistant/message、tool/result）
• SurfaceOp 替换端点从 start/end 改为 startSeq/endSeq
• deriveMessages() 以遍历 surface 作为唯一派生路径（V3 起不再对没有 surface 标记的会话回退到线性扫描）
• 新增 system/message 派生规则：空 content 投影为 null

更新 10.11 持久化格式迁移：

• 标题从 v0→v1→v2 改为 v0→v1→v2→v3
• 新增 V3 格式（0.1.5-alpha.1）说明：系统提示词迁入 surface、surfaceOp 必填、品牌类型、替换端点重命名、PTC 子派发事件重命名（tool/code-dispatch → tool/ptc-dispatch）
• 迁移链新增 dsh-session-format-v2-to-v3 边

更新 10.13 小结：

• 新增 V3 格式要点
• 更新格式迁移链条（v0→v1→v2→v3）

对应上游提交：

• 5212603a4 fix(session): audit every historical content carrier before V3 migration
• 5924d4c15 test(session): audit V3 migration composition and centralize upgrade spec
• 以及多个 V3 规范信封、系统提示词 surface 节点、规范信封决策相关的 Agent Note 更新

part3-core/ch13-system-prompt-scope.md

更新 13.3 组装流程：

• 步骤 6 从"结果进入 EpochHeader.system，随 request/header 事件写入会话日志"改为"V3 起渲染后的提示词作为 system/message surface 事件写入会话日志（位于 surface 节点 0），而非 request/header 的 system 字段"
• 说明提示词变更通过 surface 替换表达，与工具变更在日志中可区分

更新 13.5 小结：

• 更新组装结果写入方式的描述

对应上游提交：

• 5212603a4 fix(session): audit every historical content carrier before V3 migration
• Agent Note 2026-09-02-system-prompt-as-surface-node.md 的实现

part3-core/ch16-preset-goal-subagent.md

更新 16.4 spill 节：

• tools/code-dispatch-log waterfall 改名为 tools/ptc-dispatch-log（V3 起）

对应上游提交：

• Agent Note 2026-06-15-ptc.md 中 PTC 子派发事件重命名

未影响文档的变更

以下上游变更未触发文档更新：

• Agent Note 更新（.agents/notes/ 目录下多个架构决策文档）：这些是内部架构决策记录，不是本书章节。虽然它们描述了底层实现细节（如显式 Agent 身份、SubagentContinuationManager 父级传递、Profile --from-default-profile 标志等），但本书章节未涉及这些细节
• native/system 包重命名（从 native/landlock-run 到 native/system，node-addon-system 包族）：本书 ch2 仓库布局和 ch8 引导链未详细描述该包路径
• 测试与 CI 改进：Session V3 迁移测试、Web SSH 重放对齐、fixture worker 清理等，不影响公开 API 描述
• Web UI 细节（StatsLine → StatsPills 重命名）：本书 ch17 Web 客户端未提及该组件名称
• Goal 暂停/恢复行为变化（用户独占暂停、update_goal resume 拒绝持久 paused goal）：本书 ch16 的 GoalOperation 枚举未变，工具行为细节未在章节中展开
• 合并提交（5dda764ed、96a66ba47、7b1c98933 等）：PR 合并，无独立内容
• 发布提交（2faa751be release(dsh): 0.1.5-alpha.1、9ddc35c26 release(node-addon-system): 0.1.2）：版本号更新，本书按特性而非版本号组织

变更总结

本次上游更新的核心是 Session 格式 V3（0.1.5-alpha.1），这是自 V2 嵌入式 stream 重构后的又一次结构性升级。主要变化：

1. 系统提示词迁入 surface：system/message 成为 surface 事件（节点 0），request/header 不再包含 system 字段。提示词变更通过 surface 替换表达，与工具/配置变更在日志中可区分
2. Surface 元数据规范化：surfaceOp 从可选改为必填，sourceEventSeqs 使用品牌类型 SessionSeq[]，替换端点从 start/end 改为 startSeq/endSeq
3. 派生路径唯一化：deriveMessages() 以遍历 surface 作为唯一派生路径，不再回退到线性扫描
4. PTC 事件重命名：tool/code-dispatch → tool/ptc-dispatch

这些变化在保持"模型可见即已记录"不变式的同时，统一了系统提示词与其他消息的表示方式，使提示词变更成为可观察、可重放的 surface 操作。V2-to-V3 迁移链保证已有会话可以无损升级。