2026-09-10 文档同步

上游变更概览

本次同步覆盖上游提交范围 b2e3b2a01258..c291e7961a51，主要包含以下重要变更：

1. Session 事件读取器弃用（PR #3828）：弃用 eventAt()、snapshotEvents() 和 ownEvents() 三个同步历史读取方法
2. Web 客户端反馈与文件改进（PR #3973）：对称消息反馈提交、引导页细化、命令标识与文件动作所有权、Agent preset 选择器门控
3. 公共 package manifest 类型：引入 DshPackageManifest 等公共 TypeScript 类型
4. Desktop 相关变更：profile 就地修改、并行 macOS 公证、立即显示窗口等（本书不涉及 Desktop 章节，未更新文档）
5. 其他内部改进：dshCachePath 助手、attachment-local 缓存路径、测试基础设施等

文档更新详情

part4-web/ch17-web-client.md

• 17.20 节：更新右侧 Sidebar 引导页说明，增加 0.1.5-rc.2 的细化内容：

  • 入口胶囊上方的 56px 罗盘图标（CompassGlyph）
  • SidebarRightGuideEntry 新增可选 thunk 化 description 字段
  • 描述显示的 4 入口阈值（MAX_DESCRIBED_ENTRIES）
  • 图标尺寸随胶囊高度变化（单行 22px，两行 26px）
  • 未注册图标入口回退到立方体占位符（CubeGlyph）
  • 文件树入口注册描述文本与共享文件夹图标（FolderSheetGlyph）

• 新增 17.23 节"对称消息反馈提交"：说明 0.1.5-rc.2 统一正面与负面评分的提交流程，两者都使用共享反馈弹窗，仅在提交后记录评分，支持分类和备注

• 新增 17.24 节"命令标识与输入框拥有的文件动作"：

  • 命令注册表保留可选品牌类型 CommandDefinitionId 字段 definitionId
  • 客户端命令目录通过内部 resolution.ts 解析输入（精确注册名优先、中英文别名仅选择内置定义）
  • File 动作由 Conversation 通过注入的命令服务注册，统一处理锁定、卸载、subagent 和提交状态

• 新增 17.25 节"Agent preset 选择器可见性门控"：

  • agent-presets 用户设置命名空间新增 modeSelectionEnabled 字段（默认 true）
  • Web Settings 开关可隐藏/显示 preset 选择器，这是对"用户值覆盖组装值"优先级的有意例外
  • 隐藏选择器时停用用户的模式选择策略但不删除保存值
  • 设置页 preset 管理分区包含可见性开关（默认开启）

• 新增 17.26 节"统计 pill 与输入框细节细化"：

  • Token 用量弹窗仅在 cacheWriteTokens !== 0 时渲染 Cache write 行
  • 已完成轮次动作页脚从前序内容下方 20px 处开始

• 17.27 节（原 17.23 节）设计亮点小结：新增第 17-20 项，涵盖对称反馈提交、命令标识、preset 选择器门控、引导页罗盘与图标回退

part5-plugins/ch18-plugin-basics.md

• 新增 18.8 节"公共 package manifest 类型"：
  • 说明 @deepseek-ai/dsh-package-manifest 包提供的公共 TypeScript 类型
  • 详述 DshPackageManifest 核心类型（必填 name/version，可选 dsh/engines）
  • 说明 DshManifest 和 DshClientManifest 类型
  • 提供代码示例展示类型使用方式
  • 说明内部字段（configTrees、Session 迁移声明、模块后备元数据）与公共类型的隔离
• 原 18.8 节重编号为 18.9 节

未影响文档的变更

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

• Session 事件读取器弃用相关测试与 CI 调整：属于内部测试基础设施，不影响用户文档
• Desktop 相关架构决策：包括 profile 就地修改（2026-09-09-desktop-in-place-profile）、并行 macOS 公证（2026-09-09-parallel-macos-notarization）、立即显示窗口（2026-09-09-desktop-immediate-window-and-direct-start）等，本书不涉及 Desktop 应用章节
• dshCachePath 助手与 attachment-local 缓存路径：属于内部实现细节，未在用户文档中描述
• 测试基础设施改进：包括 native-mock 客户端装配、remote-mock 类型化原生 mock 等，属于开发工具链
• 内部 Agent Notes 更新：属于仓库内部设计文档，不直接映射到用户可见的书籍章节