dsh-plugin-dev-kb 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.4.0] - 2026-10-10
+
+- 知识库同步至上游 master `5badb150`（2026-10-10，对应 dsh `0.2.0-rc.2` / `0.2.1-alpha` 时期）：
+  站点镜像维持 188 页（中英 94/94），全部页面内容刷新；页面集合变化：
+  `subsystems/code-runtime` → `subsystems/ptc-runtime`（dsh 0.2.0 更名）、`subsystems/invariants`
+  移除、新增 `guide/public-deployments`（公共部署，中英一对）、新增 `subsystems/sidebar-right`
+  与 `subsystems/client-resources`（中英一对）。
+- 补充文档 62 → 182 篇：新增 `upgrade-guide/`（0.1.7-rc.2 / 0.2.0-rc.2 升级指南，
+  schedule-bundle-retired / remove-runtime-invariants / subpath-plugin-display-manifest 等）、
+  `persistence-changes/`（持久化格式变更记录与历史格式）、`cookbook/reviewing-persistence-type-changes`、
+  `subsystems/`（boot / browser-use / claude-code-mods / computer-use / deliverables / mcp /
+  office-to-pdf / otel / product-telemetry / ssh / voice-input 等）。
+- 更新 `kb/meta/source.json` 与 `site-pages.txt`；重建检索索引（253 → 373 文件）与 INDEX.md；
+  `topics.md` 新增「版本升级与持久化变更」主题，子系统速查同步 ptc-runtime 更名与新页面。
+
 ## [1.3.0] - 2026-09-10
 
 - 修复：移除每次加载覆写 `state.json` 的调试残留（纯数据插件本不需要持久化状态）；

package/README.en.md

@@ -12,7 +12,7 @@
 
 [中文](./README.md) | **English**
 
-> **188-page official mirror · 62 supplementary docs · 253-file search index · 0 runtime dependencies**
+> **188-page official mirror · 182 supplementary docs · 373-file search index · 0 runtime dependencies**
 
 **The official docs at your side whenever you write dsh plugins**: the entire content of the DeepSeek Harness official documentation site
 <https://deepseek-harness.github.io/deepseek-harness/> is organized into a form natively usable by dsh —
@@ -22,7 +22,7 @@ once this plugin is installed, the agent automatically loads the knowledge base
 
 - **Complete site mirror**: the official docs (VitePress) are generated as a projection of the raw Markdown in
   `docs/` of the `deepseek-ai/deepseek-harness` repository (links rewritten to site routes, verbatim identical to the live site). 188 pages in both Chinese and English.
-- **Supplementary docs**: 62 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.).
+- **Supplementary docs**: 182 development references from the repo's `docs/` that were not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, upgrade guides, persistence changes, etc.).
 - **Agent-friendly**: the `skills/dsh-plugin-dev-kb.md` skill lets dsh auto-load it during plugin development tasks, providing the knowledge base location,
   topic navigation, and search strategy; `kb/meta/topics.md` maps task scenarios to the files to read; `kb/meta/search-index.json` provides full search coverage.
 
@@ -30,7 +30,7 @@ once this plugin is installed, the agent automatically loads the knowledge base
 
 - **Complete mirror of the official docs**: the entire content of the deepseek-ai/deepseek-harness official documentation site, organized into a form natively usable by dsh,
   188 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
-- **Repo supplementary docs**: 62 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, etc.);
+- **Repo supplementary docs**: 182 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, upgrade guides, persistence changes, etc.);
 - **Agent-friendly**: the `dsh-plugin-dev-kb` skill lets dsh auto-load the knowledge base during plugin development tasks;
   `kb/meta/topics.md` maps task scenarios to the files to read, and `kb/meta/search-index.json` provides full search coverage;
 - **Human-usable**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping;
@@ -96,7 +96,7 @@ dsh-plugin-dev-kb/
 │   ├── extra/         repo supplementary docs: glossary, defensive-patterns, module-graph, postmortem/, i18n/ …
 │   ├── meta/
 │   │   ├── topics.md         ★ topic navigation: task scenario → files
-│   │   ├── search-index.json full index (253 files)
+│   │   ├── search-index.json full index (373 files)
 │   │   ├── source.json       source commit / time / stats
 │   │   └── site-pages.txt    list of live site pages
 │   ├── INDEX.md        site URL ↔ local file mapping

package/README.md

@@ -12,7 +12,7 @@
 
 [**中文**](./README.md) | [English](./README.en.md)
 
-> **188 页官方镜像 · 62 篇补充文档 · 253 文件搜索索引 · 0 运行时依赖**
+> **188 页官方镜像 · 182 篇补充文档 · 373 文件搜索索引 · 0 运行时依赖**
 
 **写 dsh 插件时的随身官方文档**：把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
@@ -22,7 +22,7 @@
 
 - **站点完整镜像**：官方文档（VitePress）由仓库 `deepseek-ai/deepseek-harness` 的 `docs/` 原始 Markdown
   投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 188 页。
-- **补充文档**：仓库 `docs/` 中未发布到站点的 62 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）。
+- **补充文档**：仓库 `docs/` 中未发布到站点的 182 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）。
 - **agent 友好**：`skills/dsh-plugin-dev-kb.md` 技能让 dsh 在插件开发任务中自动加载，获知知识库位置、
   主题导航与检索策略；`kb/meta/topics.md` 按任务场景映射要读的文件；`kb/meta/search-index.json` 提供全量检索。
 
@@ -30,7 +30,7 @@
 
 - **官方文档完整镜像**：deepseek-ai/deepseek-harness 官方文档站全部内容整理为 dsh 原生可用的形态，
   中英双语共 188 页，链接按站点路由重写，与线上逐字一致；
-- **仓库补充文档**：未发布到站点的 62 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）；
+- **仓库补充文档**：未发布到站点的 182 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）；
 - **agent 友好**：`dsh-plugin-dev-kb` 技能让 dsh 在插件开发任务中自动加载知识库；
   `kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
 - **人侧可用**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅；
@@ -93,10 +93,10 @@ dsh-plugin-dev-kb/
 │   └── dsh-plugin-dev-kb.md   ★ 知识库使用指南（agent 加载此技能）
 ├── kb/
 │   ├── site/          站点镜像：guide/ develop/ reference/（+ en/ 英文站）
-│   ├── extra/         仓库补充文档：glossary、defensive-patterns、module-graph、postmortem/、i18n/ …
+│   ├── extra/         仓库补充文档：glossary、defensive-patterns、module-graph、upgrade-guide/、persistence-changes/、postmortem/、i18n/ …
 │   ├── meta/
 │   │   ├── topics.md         ★ 主题导航：任务场景 → 文件
-│   │   ├── search-index.json 全量索引（253 文件）
+│   │   ├── search-index.json 全量索引（373 文件）
 │   │   ├── source.json       来源 commit / 时间 / 统计
 │   │   └── site-pages.txt    线上页面清单
 │   ├── INDEX.md        站点 URL ↔ 本地文件 对照

package/kb/INDEX.md

@@ -1,6 +1,6 @@
 # DeepSeek Harness 文档索引
 
-> 由 `scripts/rebuild-index.mjs` 自动生成。共 188 个站点页面（中英双语），另有 62 个补充文档在 `extra/`。
+> 由 `scripts/rebuild-index.mjs` 自动生成。共 188 个站点页面（中英双语），另有 182 个补充文档在 `extra/`。
 
 ## 中文站点（根路径）
 
@@ -18,9 +18,10 @@
 | 连接第三方记忆 MCP 服务 | [https://deepseek-harness.github.io/deepseek-harness/guide/mcp-memory](https://deepseek-harness.github.io/deepseek-harness/guide/mcp-memory) | `site/guide/mcp-memory.md` |
 | 在网络代理后面运行 DSH | [https://deepseek-harness.github.io/deepseek-harness/guide/network-proxy](https://deepseek-harness.github.io/deepseek-harness/guide/network-proxy) | `site/guide/network-proxy.md` |
 | 配置模型 | [https://deepseek-harness.github.io/deepseek-harness/guide/providers](https://deepseek-harness.github.io/deepseek-harness/guide/providers) | `site/guide/providers.md` |
+| 在反向代理之后发布 Web UI | [https://deepseek-harness.github.io/deepseek-harness/guide/public-deployments](https://deepseek-harness.github.io/deepseek-harness/guide/public-deployments) | `site/guide/public-deployments.md` |
 | Python SDK 入门 | [https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk](https://deepseek-harness.github.io/deepseek-harness/guide/python-sdk) | `site/guide/python-sdk.md` |
 | 使用 Web UI | [https://deepseek-harness.github.io/deepseek-harness/guide/quickstart](https://deepseek-harness.github.io/deepseek-harness/guide/quickstart) | `site/guide/quickstart.md` |
-| 安排会话内提醒 | [https://deepseek-harness.github.io/deepseek-harness/guide/schedule](https://deepseek-harness.github.io/deepseek-harness/guide/schedule) | `site/guide/schedule.md` |
+| Schedule 提醒 | [https://deepseek-harness.github.io/deepseek-harness/guide/schedule](https://deepseek-harness.github.io/deepseek-harness/guide/schedule) | `site/guide/schedule.md` |
 
 ### 开发（/develop/）
 
@@ -41,7 +42,7 @@
 | 事件系统 | [https://deepseek-harness.github.io/deepseek-harness/develop/framework/events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events) | `site/develop/framework/events.md` |
 | 插件与生命周期 | [https://deepseek-harness.github.io/deepseek-harness/develop/framework](https://deepseek-harness.github.io/deepseek-harness/develop/framework) | `site/develop/framework/index.md` |
 | 服务与依赖 | [https://deepseek-harness.github.io/deepseek-harness/develop/framework/service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service) | `site/develop/framework/service.md` |
-| 用 Cordis 工具扩展运行中的智能体 | [https://deepseek-harness.github.io/deepseek-harness/develop/practice/dynamic-cordis](https://deepseek-harness.github.io/deepseek-harness/develop/practice/dynamic-cordis) | `site/develop/practice/dynamic-cordis.md` |
+| 通过提示词配置持久化插件 | [https://deepseek-harness.github.io/deepseek-harness/develop/practice/dynamic-cordis](https://deepseek-harness.github.io/deepseek-harness/develop/practice/dynamic-cordis) | `site/develop/practice/dynamic-cordis.md` |
 | 能力的三种角色设计 | [https://deepseek-harness.github.io/deepseek-harness/develop/practice](https://deepseek-harness.github.io/deepseek-harness/develop/practice) | `site/develop/practice/index.md` |
 | LLM 适配器 | [https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter) | `site/develop/practice/llm-adapter.md` |
 
@@ -54,7 +55,7 @@
 | 能力 Seams 与核心服务 | [https://deepseek-harness.github.io/deepseek-harness/reference/capability-seams](https://deepseek-harness.github.io/deepseek-harness/reference/capability-seams) | `site/reference/capability-seams.md` |
 | 插件配置目录 | [https://deepseek-harness.github.io/deepseek-harness/reference/config-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/config-catalog) | `site/reference/config-catalog.md` |
 | 实操手册：添加 workspace 包 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-package](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-package) | `site/reference/cookbook/adding-a-package.md` |
-| Cookbook: 新增设置卡片 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-settings-card](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-settings-card) | `site/reference/cookbook/adding-a-settings-card.md` |
+| 实践指南：即时配置表单 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-settings-card](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-settings-card) | `site/reference/cookbook/adding-a-settings-card.md` |
 | 工具编写参考 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) | `site/reference/cookbook/adding-a-tool.md` |
 | 实操手册：添加 LLM（大语言模型）适配器 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-an-llm-adapter](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-an-llm-adapter) | `site/reference/cookbook/adding-an-llm-adapter.md` |
 | 实操手册：扩展插件形态 | [https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook) | `site/reference/cookbook/extension-cookbook.md` |
@@ -70,7 +71,6 @@
 | 用户审批 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/approval](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/approval) | `site/reference/subsystems/approval.md` |
 | Client 模块 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-modules](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-modules) | `site/reference/subsystems/client-modules.md` |
 | 客户端资源 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-resources](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/client-resources) | `site/reference/subsystems/client-resources.md` |
-| 代码运行时 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/code-runtime](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/code-runtime) | `site/reference/subsystems/code-runtime.md` |
 | 用户命令 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/commands](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/commands) | `site/reference/subsystems/commands.md` |
 | 压缩（compaction） | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/compaction](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/compaction) | `site/reference/subsystems/compaction.md` |
 | Conversation 组装 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/conversation](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/conversation) | `site/reference/subsystems/conversation.md` |
@@ -79,15 +79,15 @@
 | 文件系统 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/filesystem](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/filesystem) | `site/reference/subsystems/filesystem.md` |
 | 同会话目标 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/goal](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/goal) | `site/reference/subsystems/goal.md` |
 | 子系统 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems) | `site/reference/subsystems/index.md` |
-| 运行时不变式 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/invariants](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/invariants) | `site/reference/subsystems/invariants.md` |
 | 后台任务运行时 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/jobs](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/jobs) | `site/reference/subsystems/jobs.md` |
 | LLM（大语言模型）流式输出 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/llm-streaming](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/llm-streaming) | `site/reference/subsystems/llm-streaming.md` |
 | LSP 导航 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/lsp](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/lsp) | `site/reference/subsystems/lsp.md` |
 | 权限预设 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/permission-presets](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/permission-presets) | `site/reference/subsystems/permission-presets.md` |
 | 会话持久化 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/persistence](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/persistence) | `site/reference/subsystems/persistence.md` |
 | 计划模式 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/plan](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/plan) | `site/reference/subsystems/plan.md` |
+| PTC 运行时 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/ptc-runtime](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/ptc-runtime) | `site/reference/subsystems/ptc-runtime.md` |
 | 进程沙箱 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sandbox](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sandbox) | `site/reference/subsystems/sandbox.md` |
-| 仅限 Session 内的 Schedule | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/schedule](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/schedule) | `site/reference/subsystems/schedule.md` |
+| 宿主级 Schedule | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/schedule](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/schedule) | `site/reference/subsystems/schedule.md` |
 | 作用域注册 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/scope](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/scope) | `site/reference/subsystems/scope.md` |
 | 会话投影 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-projection](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-projection) | `site/reference/subsystems/session-projection.md` |
 | 会话查询 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-query](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-query) | `site/reference/subsystems/session-query.md` |
@@ -95,8 +95,8 @@
 | 遥测（telemetry） | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-telemetry](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-telemetry) | `site/reference/subsystems/session-telemetry.md` |
 | 会话标题 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-title](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session-title) | `site/reference/subsystems/session-title.md` |
 | 会话 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/session) | `site/reference/subsystems/session.md` |
-| 用户设置 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings) | `site/reference/subsystems/settings.md` |
-| Bash 执行器 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell) | `site/reference/subsystems/shell.md` |
+| 插件配置表单 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/settings) | `site/reference/subsystems/settings.md` |
+| Shell 执行器 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/shell) | `site/reference/subsystems/shell.md` |
 | 右侧 Sidebar | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sidebar-right](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/sidebar-right) | `site/reference/subsystems/sidebar-right.md` |
 | Skills | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/skills](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/skills) | `site/reference/subsystems/skills.md` |
 | Web Client Slots | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/slots](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/slots) | `site/reference/subsystems/slots.md` |
@@ -145,22 +145,23 @@
 | Event system | [https://deepseek-harness.github.io/deepseek-harness/en/develop/framework/events](https://deepseek-harness.github.io/deepseek-harness/en/develop/framework/events) | `site/en/develop/framework/events.md` |
 | Plugins and lifecycle | [https://deepseek-harness.github.io/deepseek-harness/en/develop/framework](https://deepseek-harness.github.io/deepseek-harness/en/develop/framework) | `site/en/develop/framework/index.md` |
 | Services and dependencies | [https://deepseek-harness.github.io/deepseek-harness/en/develop/framework/service](https://deepseek-harness.github.io/deepseek-harness/en/develop/framework/service) | `site/en/develop/framework/service.md` |
-| Extend a running agent with Cordis tools | [https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/dynamic-cordis](https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/dynamic-cordis) | `site/en/develop/practice/dynamic-cordis.md` |
+| Configure persistent plugins from a prompt | [https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/dynamic-cordis](https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/dynamic-cordis) | `site/en/develop/practice/dynamic-cordis.md` |
 | Three-role capability design | [https://deepseek-harness.github.io/deepseek-harness/en/develop/practice](https://deepseek-harness.github.io/deepseek-harness/en/develop/practice) | `site/en/develop/practice/index.md` |
 | LLM adapters | [https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/llm-adapter](https://deepseek-harness.github.io/deepseek-harness/en/develop/practice/llm-adapter) | `site/en/develop/practice/llm-adapter.md` |
 | Create review Sessions from GitHub webhooks | [https://deepseek-harness.github.io/deepseek-harness/en/guide/github-review](https://deepseek-harness.github.io/deepseek-harness/en/guide/github-review) | `site/en/guide/github-review.md` |
 | Connect a third-party memory MCP server | [https://deepseek-harness.github.io/deepseek-harness/en/guide/mcp-memory](https://deepseek-harness.github.io/deepseek-harness/en/guide/mcp-memory) | `site/en/guide/mcp-memory.md` |
 | Run DSH behind a network proxy | [https://deepseek-harness.github.io/deepseek-harness/en/guide/network-proxy](https://deepseek-harness.github.io/deepseek-harness/en/guide/network-proxy) | `site/en/guide/network-proxy.md` |
 | Configure models | [https://deepseek-harness.github.io/deepseek-harness/en/guide/providers](https://deepseek-harness.github.io/deepseek-harness/en/guide/providers) | `site/en/guide/providers.md` |
+| Publish the Web UI behind a reverse proxy | [https://deepseek-harness.github.io/deepseek-harness/en/guide/public-deployments](https://deepseek-harness.github.io/deepseek-harness/en/guide/public-deployments) | `site/en/guide/public-deployments.md` |
 | Get started with the Python SDK | [https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk](https://deepseek-harness.github.io/deepseek-harness/en/guide/python-sdk) | `site/en/guide/python-sdk.md` |
 | Use the Web UI | [https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart](https://deepseek-harness.github.io/deepseek-harness/en/guide/quickstart) | `site/en/guide/quickstart.md` |
-| Schedule session-local reminders | [https://deepseek-harness.github.io/deepseek-harness/en/guide/schedule](https://deepseek-harness.github.io/deepseek-harness/en/guide/schedule) | `site/en/guide/schedule.md` |
+| Schedule reminders | [https://deepseek-harness.github.io/deepseek-harness/en/guide/schedule](https://deepseek-harness.github.io/deepseek-harness/en/guide/schedule) | `site/en/guide/schedule.md` |
 | Agent Turn And Step Lifecycle | [https://deepseek-harness.github.io/deepseek-harness/en/reference/agent-lifecycle](https://deepseek-harness.github.io/deepseek-harness/en/reference/agent-lifecycle) | `site/en/reference/agent-lifecycle.md` |
 | API Gateway | [https://deepseek-harness.github.io/deepseek-harness/en/reference/api-gateway](https://deepseek-harness.github.io/deepseek-harness/en/reference/api-gateway) | `site/en/reference/api-gateway.md` |
 | Capability Seams And Core Services | [https://deepseek-harness.github.io/deepseek-harness/en/reference/capability-seams](https://deepseek-harness.github.io/deepseek-harness/en/reference/capability-seams) | `site/en/reference/capability-seams.md` |
 | Plugin Config Catalog | [https://deepseek-harness.github.io/deepseek-harness/en/reference/config-catalog](https://deepseek-harness.github.io/deepseek-harness/en/reference/config-catalog) | `site/en/reference/config-catalog.md` |
 | Cookbook: adding a workspace package | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-package](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-package) | `site/en/reference/cookbook/adding-a-package.md` |
-| Cookbook: adding a settings card | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-settings-card](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-settings-card) | `site/en/reference/cookbook/adding-a-settings-card.md` |
+| Cookbook: live configuration forms | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-settings-card](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-settings-card) | `site/en/reference/cookbook/adding-a-settings-card.md` |
 | Tool authoring reference | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-tool) | `site/en/reference/cookbook/adding-a-tool.md` |
 | Cookbook: adding an LLM adapter | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-an-llm-adapter](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-an-llm-adapter) | `site/en/reference/cookbook/adding-an-llm-adapter.md` |
 | Cookbook: extension plugin shapes | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/extension-cookbook) | `site/en/reference/cookbook/extension-cookbook.md` |
@@ -176,7 +177,6 @@
 | User Approval | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/approval](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/approval) | `site/en/reference/subsystems/approval.md` |
 | Client Modules | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-modules](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-modules) | `site/en/reference/subsystems/client-modules.md` |
 | Client Resources | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-resources](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/client-resources) | `site/en/reference/subsystems/client-resources.md` |
-| Code Runtime | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/code-runtime](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/code-runtime) | `site/en/reference/subsystems/code-runtime.md` |
 | Human Commands | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/commands](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/commands) | `site/en/reference/subsystems/commands.md` |
 | Compaction | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/compaction) | `site/en/reference/subsystems/compaction.md` |
 | Conversation assembly | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/conversation](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/conversation) | `site/en/reference/subsystems/conversation.md` |
@@ -185,15 +185,15 @@
 | Filesystem | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/filesystem](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/filesystem) | `site/en/reference/subsystems/filesystem.md` |
 | Same-session goals | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/goal](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/goal) | `site/en/reference/subsystems/goal.md` |
 | Subsystems | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems) | `site/en/reference/subsystems/index.md` |
-| Runtime Invariants | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/invariants](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/invariants) | `site/en/reference/subsystems/invariants.md` |
-| Background Task Runtime | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/jobs](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/jobs) | `site/en/reference/subsystems/jobs.md` |
+| Background Job Runtime | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/jobs](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/jobs) | `site/en/reference/subsystems/jobs.md` |
 | LLM Streaming | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/llm-streaming](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/llm-streaming) | `site/en/reference/subsystems/llm-streaming.md` |
 | LSP navigation | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/lsp](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/lsp) | `site/en/reference/subsystems/lsp.md` |
 | Permission Presets | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/permission-presets](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/permission-presets) | `site/en/reference/subsystems/permission-presets.md` |
 | Session Persistence | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/persistence](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/persistence) | `site/en/reference/subsystems/persistence.md` |
 | Plan Mode | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/plan](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/plan) | `site/en/reference/subsystems/plan.md` |
+| PTC runtime | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/ptc-runtime](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/ptc-runtime) | `site/en/reference/subsystems/ptc-runtime.md` |
 | Process Sandbox | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sandbox](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sandbox) | `site/en/reference/subsystems/sandbox.md` |
-| Session-local Schedule | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/schedule](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/schedule) | `site/en/reference/subsystems/schedule.md` |
+| Host-wide Schedule | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/schedule](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/schedule) | `site/en/reference/subsystems/schedule.md` |
 | Scoped Registration | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/scope](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/scope) | `site/en/reference/subsystems/scope.md` |
 | Session Projections | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-projection](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-projection) | `site/en/reference/subsystems/session-projection.md` |
 | Session Query | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-query](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-query) | `site/en/reference/subsystems/session-query.md` |
@@ -201,8 +201,8 @@
 | SessionTelemetryBackend | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-telemetry](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-telemetry) | `site/en/reference/subsystems/session-telemetry.md` |
 | Session Titles | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-title](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session-title) | `site/en/reference/subsystems/session-title.md` |
 | Sessions | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/session) | `site/en/reference/subsystems/session.md` |
-| User Settings | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings) | `site/en/reference/subsystems/settings.md` |
-| Bash Executor | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell) | `site/en/reference/subsystems/shell.md` |
+| Plugin Configuration Forms | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/settings) | `site/en/reference/subsystems/settings.md` |
+| Shell Executor | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/shell) | `site/en/reference/subsystems/shell.md` |
 | Right Sidebar | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sidebar-right](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/sidebar-right) | `site/en/reference/subsystems/sidebar-right.md` |
 | Skills | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/skills](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/skills) | `site/en/reference/subsystems/skills.md` |
 | Web Client Slots | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/slots](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/slots) | `site/en/reference/subsystems/slots.md` |

package/kb/README.md

@@ -23,8 +23,10 @@ knowledge/deepseek-harness/
 │   ├── defensive-patterns.md / testing.md / development.md / rescope.md …
 │   ├── module-graph.md     模块依赖全景图（125KB）
 │   ├── cookbook/           adding-a-vendored-package 等仓库内 cookbook
-│   ├── subsystems/         attachment / extensions / feedback
-│   ├── postmortem/         事故复盘（4 篇）
+│   ├── upgrade-guide/      各版本升级指南（0.1.7-rc.2 / 0.2.0-rc.2 …）
+│   ├── persistence-changes/ 持久化格式变更记录（releases/、historical-formats/）
+│   ├── subsystems/         未发布进站点的子系统文档（boot / browser-use / ssh / otel …）
+│   ├── postmortem/         事故复盘
 │   └── i18n/               文档双语规范与术语
 └── meta/
     ├── source.json         来源信息：仓库 commit、抓取时间、统计
@@ -77,5 +79,5 @@ node scripts/rebuild-index.mjs
 ## 统计
 
 - 站点页面：188 个 Markdown（中文 94 + 英文 94），4 张图片
-- 补充文档：62 个 Markdown（`extra/`）
-- 来源 commit：`aa8262ec091698bae9a6b04773a6b5b06ad4aef2`（master，2026-09-10 同步）
+- 补充文档：182 个 Markdown（`extra/`）
+- 来源 commit：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（master，2026-10-10 同步）

package/kb/extra/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — The documentation standard
 
-This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
 
 ## Document structure
 
@@ -24,6 +24,7 @@ Each fact has one home: the tier whose job it is; elsewhere, link there.
 | [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
 | [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
 | [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [Persistence history](persistence-changes/README.md) and [format references](persistence-changes/historical-formats/README.md) | Type-change acknowledgements, release comparisons, and complete historical format schemas | Behavior-only changes; current runtime contracts |
 | [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
 | [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
 | Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
@@ -35,14 +36,14 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 
 ## Writing rules
 
-- **Document current state, not change history.** Name live mechanisms, not PRs, commits, stack positions, or "previously/now/no longer". Keep history in commits, PRs, Agent Notes, or postmortems. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
-- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **Document current state.** Keep history in commits, PRs, Agent Notes, postmortems, or scoped persistence records. Other prose names live mechanisms, not changes or stack positions. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
+- **Apply the Agent Note creation criteria.** Mechanical/local edits are exempt, including local UI changes; keep existing owning notes accurate ([scope](../.agents/notes/README.md#when-to-write-one)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
 - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
-- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../scripts/verify-subsystem-pages.ts)).
 - **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
-- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+- Write directly: name actors and facts ([reference](../.agents/skills/dsh-prose-standard/SKILL.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
 
 ## Wordcount Budgets
 
@@ -54,14 +55,14 @@ When the gate goes red:
 2. **Condense** content that belongs here but can be shorter.
 3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
 
-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,960; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
 
 ## The slop checklist
 
 Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
 
-- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
-- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
+- Duplicated rules: search a distinctive phrase; keep one home and link the rest.
+- History outside its permitted tier: state current facts and link the historical owner.
 - Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
 - Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
 - Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
@@ -70,6 +71,6 @@ Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this l
 - Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
 - Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
 
-## Cross-reference with machine-checkable links, never free prose
+## Repository references
 
-Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors.
+Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects actual commit identifiers and disallowed organization URLs in maintained files.

package/kb/extra/cookbook/adding-a-remote-api.md

@@ -97,8 +97,8 @@ export async function rename(noteId: string, title: string): Promise<void> {
     "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
     "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
   },
-  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
-  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" },
+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" }
 }
 ```
 

package/kb/extra/cookbook/adding-a-remote-api.zh.md

@@ -97,8 +97,8 @@ export async function rename(noteId: string, title: string): Promise<void> {
     "./typert": { "types": "./lib/typert.host.d.ts", "default": "./lib/typert.host.js" },
     "./remote": { "types": "./lib/typert.remote-client.d.ts", "default": "./lib/typert.remote-client.js" }
   },
-  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" },
-  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:^" }
+  "peerDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" },
+  "devDependencies": { "@deepseek-ai/dsh-typert-protocol": "workspace:*" }
 }
 ```
 

package/kb/extra/cookbook/adding-a-session-format-version.md

@@ -14,18 +14,23 @@ Use this tutorial to introduce the next structural Session log version without r
 - [4. Update current-version consumers](#current-version-consumers)
 - [5. Create snapshot successors](#snapshot-successors)
 - [6. Validate the integrated result](#validate)
+- [Developer V4 corpus trial](#v4-corpus-trial)
 - [Dev Note](#dev-note)
 
 <a id="choose-the-version"></a>
 ## 1. Choose the version and release base
 
-Bump the format for a structural change to headers, event envelopes, core event semantics, or surface reconstruction. Ordinary event additions do not require a bump; follow the [versioning rule](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md). Distinguish the Session format integer from package release versions, SQLite schema versions, projection-unit versions, and protocol-wrapper versions.
+Bump the format for a structural change to headers, event envelopes, core event semantics, or surface reconstruction. Backward-compatible changes can remain at the current version through new acknowledgements; follow the [versioning rule](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md) and [type-change rules](../persistence-changes/README.md#compatibility-rules). Distinguish the Session format integer from package release versions, SQLite schema versions, projection-unit versions, and protocol-wrapper versions.
+
+Let N be the accepted or published version in [version/status](../session-format-status.md) when planning the next breaking change. A breaking change after accepted V4 therefore needs V5 even before V4 publication is recorded; compatible additions do not require that step.
 
 Use a shared `release/*` integration base for N+1. The base change adds the writer, codec, catalog wiring, identity migration, and verification. Create each independent child branch from that base and target its PR at the release branch, not another independent child’s branch. Each child adds its structural transformation, validators, consumers, and tests to the same adjacent migration package. Do not allocate extra versions just to represent review order. Merge reviewed children into the release branch through PRs, then validate the combined result before release. Honor release-branch force-push and deletion protections; do not force-sync it.
 
-Released codecs and migration semantics remain frozen. Do not amend a released edge to implement a new structural feature. Only the N→N+1 edge may incorporate coordinated changes before N+1 ships; after release, further structural changes need the next adjacent edge.
+Released codecs and accepted target-format meanings remain stable. The N→N+1 converter may receive fixes or support additional historical cases after N+1 ships, without a version bump, if its output remains compatible with N+1. A converter fix affects subsequent conversions, not existing N+1 successors. Document changes to previously accepted mappings and how existing outputs remain supported. Changing the established target representation or interpretation incompatibly requires the next version.
+
+Use disposable, isolated Harness homes while N+1 remains open for integration. An interim N+1 file already has the target writer version, so a later edit to N→N+1 will not migrate that file again. Re-run from unchanged historical input in a fresh test home; never repair this by rewriting a committed generation or reusing a real user's home.
 
-Use disposable, isolated Harness homes for unreleased N+1 integration testing. An interim N+1 file already has the target writer version, so a later edit to N→N+1 will not migrate that file again. Re-run from unchanged historical input in a fresh test home; never repair this by rewriting a committed generation or reusing a real user's home.
+Before changing the writer, use the [archive command](../persistence-changes/historical-formats/README.md#maintenance) to preserve its complete persistence schema, then add the bilingual format reference under `docs/persistence-changes/historical-formats/vN.*`. Preserve all earlier records. The format coverage check requires every integer below the new writer to have its own document; the current generated catalog covers only the new writer.
 
 <a id="add-an-identity-edge"></a>
 ## 2. Add an identity edge
@@ -53,12 +58,20 @@ Treat the inherited cut as a logical event count, not a physical row count. Expo
 
 Define the new edge's event admission and transformation rules explicitly. The [V2-to-V3 source audit](../../packages/session/session-format-v2-to-v3/README.md#source-audit) and [alpha V0→V1 rule](../../.agents/notes/implemented/architecture/2026-08-31-alpha-historical-unknown-event-refusal.md) own the policies of those released edges, not the new edge. Do not generalize either to every edge. A change to structure or event positions requires classifying source events, payload members, and references, and explicitly deciding whether opaque data can remain valid. [Equal-version retention](../../.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md) alone does not prove a structural transformation safe. Validate target semantics and give each newly accepted case a rejecting counterexample; never widen older edges to hide an unsupported transformation.
 
+Use native writer output as the conversion oracle: replay the same recorded LLM messages, tool outputs, and other inputs through the old and target writers. Compare migrated old output with raw target output before any format-normalizing helper; mask only documented volatile fields. For V4, ordinary tool results become flat tool-role messages with ordinary content blocks. A theoretically permitted old structure alone does not justify a new core content type.
+
+Alpha converters may explicitly refuse historical cases without an implemented, evidenced mapping, including otherwise valid logs. Keep the source unchanged and publish no partial successor. Prefer real corpora and reproducible writers when extending support; inspect user corpora read-only and create sanitized regression fixtures.
+
+Document only the identifier and field mappings needed by the target format in the edge README, with a reason for each. Do not add namespaces to direct source kinds or ordinary metadata solely because they are extensible. Preserve opaque nested data. Alpha converters may refuse unexpected source fields that would acquire new target meanings rather than invent an interpretation.
+
+Maintain the new edge's README as its single complete transformation and admission catalog, following the [V2-to-V3 specification](../../packages/session/session-format-v2-to-v3/README.md#v2-to-v3-specification). Enumerate every converted header, event, message slot, and payload field; exact rename or collision rules; preserved ids, coordinates, references, and inherited cuts; external prerequisites; refusal and opaque-data policies; and unsupported or deferred behavior. Separate historical source conversion from native target admission, and state which codec, restorer, installed validator, and recovery policy performs each check. Record any validation that is deliberately narrower than the declared schema. Update this catalog in the same change as its code; a generated schema inventory or PR description does not replace it.
+
 Prove strict restoration through `sessionFormatCatalog.createRestore(header, { recovery: 'strict', validation: 'current' })`, feeding rows in order and calling `finish()`. This exercises physical decoding, the complete chain, and installed current Session validation. Production's recoverable/transformed policy is not a replacement for strict fixture and publication verification. Preserve documented historical validation exceptions rather than claiming stricter source validation than the edge actually performs.
 
 <a id="current-version-consumers"></a>
 ## 4. Update current-version consumers
 
-Trace each current-version consumer, including Session creation/restoration, JSONL filename selection and publication, the catalog's current encoder/restorer, projection-cache generation identity, replay and snapshot normalization, and TypeScript/Python SDK recordings. Use the writer constant where a value means current; keep literal historical versions in released codecs and historical fixtures. Update current documentation and generated references through their owners.
+Trace each current-version consumer, including Session creation/restoration, JSONL filename selection and publication, the catalog's current encoder/restorer, projection-cache generation identity, replay and snapshot normalization, [physical fixture-layout validation](../../scripts/session-fixture-layout.ts), and TypeScript/Python SDK recordings. Use the writer constant where a value means current; keep literal historical versions in released codecs and historical fixtures. Update current documentation and generated references through their owners.
 
 Do not bump unrelated versions automatically. A request wrapper's `sessionFormatVersion` identifies its embedded Session generation; its outer schema version has its own meaning. Projection-unit state versions likewise do not replace the cache's Session-generation identity.
 
@@ -67,7 +80,7 @@ Verify both read and write paths. Header-only listing must not read bodies or pu
 <a id="snapshot-successors"></a>
 ## 5. Create snapshot successors
 
-Read [snapshot ownership](../../snapshots/AGENTS.md) and the [snapshot library](../../packages/test-support/session-snapshot/README.md). Select the owning scenario, not an adapter that only references it. After implementing N+1, keep each historical file and generate its successor using the target version’s canonical parent and child filenames. Never rename a predecessor to the target filename or change only its header.
+Read [snapshot ownership](../../snapshots/AGENTS.md) and the [snapshot library](../../packages/test-support/session-snapshot/README.md). The [corpus policy](../../scripts/session-snapshot-corpus-policy.ts) keeps its declared baseline as replay input so upgrades exercise the adjacent chain; a writer bump does not require refreshing that corpus. Select the owning scenario when a current-generation successor is needed, keep each historical file, and use the target version’s canonical parent and child filenames. Never rename a predecessor to the target filename or change only its header.
 
 For unchanged replay input, use keyless refresh on the owner, then replay without write-back. These SDK commands use `text-turn` and the checkout's writer version. Implement and wire N+1 before using them to generate that version, and select the actual affected owner for a feature:
 
@@ -78,7 +91,7 @@ pnpm run test:snapshot snapshots/sdk/sdk.snapshot.ts -t text-turn
 
 Review the new generation, request sidecars, and protocol output together. Verify every predecessor remains byte-identical and that parent/child roles remain contiguous. Selection uses the numerically highest generation, so update shared references to the owner's selected parent. Do not use the packed-layout migrator as a version upgrader. If the model transcript must change, the scenario owner uses live recording under the [testing policy](../testing.md), with its required provider key.
 
-Keep deliberate historical cases explicit through `snapshot.yml`'s `sessionFormat.version` and supported `coverage` names; record and refresh leave their Session fixtures untouched. Update the [corpus policy](../../scripts/session-snapshot-corpus-policy.ts) for the current generation while retaining focused direct-edge, multi-hop, packed-row, retry/failure, and shipped-profile coverage. Check the corpus and both SDK projections; do not mass-refresh unrelated scenarios merely to silence a validation failure.
+Keep cases older than the retained baseline explicit through `snapshot.yml`'s `sessionFormat.version` and supported `coverage` names; record and refresh leave pinned Session fixtures untouched. Update the [corpus policy](../../scripts/session-snapshot-corpus-policy.ts) for the current generation while retaining focused direct-edge, multi-hop, packed-row, retry/failure, and shipped-profile coverage. Check the corpus and both SDK projections; do not mass-refresh unrelated scenarios merely to silence a validation failure.
 
 <a id="validate"></a>
 ## 6. Validate the integrated result
@@ -103,6 +116,35 @@ pnpm run lint
 git diff --check
 ```
 
+<a id="v4-corpus-trial"></a>
+### Developer V4 corpus trial
+
+Use the one-time [migration script](../../scripts/migrate-sessions-to-v4.ts) from an installed contributor checkout whose writer is V4. Stop DSH processes using the target root before starting so writer locks and changing child logs do not prevent migration. Run from the repository root:
+
+```sh
+pnpm run migrate:sessions-to-v4
+```
+
+The default root is `~/.dsh/sessions`. Use `--sessions-dir /path/to/sessions-copy` for another corpus, or `--help` for usage. Concurrent jobs default to the available CPU count capped at 16; `--jobs N` accepts any positive safe integer, including larger expert overrides, and `--jobs 1` runs serially. A bounded queue opens only that many Sessions at once, regardless of corpus size. Each historical Session goes through the normal locked, validated publication path to create a V4 successor beside its unchanged source files. Existing V4 Sessions are opened read-only; rerunning does not reconvert them. The script makes no model requests and does not change conversion or refusal rules.
+
+The terminal reports each Session's selected file, version, progress, outcome, and elapsed time. Individual errors do not stop later Sessions. The final summary lists every failure and the full diagnostic log under the system temporary directory; any failure returns a nonzero exit status. It also prints JSON and saves the same report as `summary.json` beside `migration.log`: counts by source version and outcome, grouped failure reasons, per-input diagnostics, runtime details, and both report paths. Known diagnostics expose event types, unexpected members, child-log involvement, and sequence numbers; unrecognized errors retain their messages without inferred causes. Include these reports when reporting a migration problem. Sessions converted during this run remain distinct from those already at V4.
+
+Concurrent conversion can invalidate a parent’s child evidence when the child publishes V4. Only that source-change error receives one sequential retry after all initial jobs finish; corruption, unsupported formats, and held locks are reported immediately. Completion lines keep the original input index and a separate completed count, so out-of-order results remain readable.
+
+<a id="final-v3-vocabulary"></a>
+### Final V3 event vocabulary before V4 publication
+
+While the published format remains V3 and the integration writer is V4, master can still add valid V3 event types. After each master integration and before the first V4 publication, compare the migration-owned `RELEASED_V3_EVENT_TYPES` with the latest V3-writer commit used by that refresh. Capture its full immutable id while the locally verified `origin/master` still writes V3:
+
+```sh
+V3_SOURCE_REF="$(git rev-parse --verify 'origin/master^{commit}')"
+pnpm run verify-v3-event-vocabulary --source-ref "$V3_SOURCE_REF"
+```
+
+The verifier reads only that local commit and requires exact event-name equality. It rejects missing V3 names, extra copied names, and a source writer other than V3. In particular, V4-only `developer/message` must not enter the frozen V3 set. Review each difference against the V3 payload, required conversions, target admission, and consumers; adding the name alone does not establish a complete migration. Add the corresponding migration regression before accepting a new source event.
+
+This command does not fetch or establish remote freshness. The release operator must verify that the selected commit is the latest V3 writer included in the integration; an old remote-tracking ref or passing result for an older pin is insufficient. Record the checked id with release validation. If master already writes V4, reuse the recorded final V3 commit rather than resolving current master. After V4 ships, keep the V3 vocabulary tied to that historical source; later V4 event additions do not update it. Regular static CI has no dependency on a mutable master ref.
+
 <a id="dev-note"></a>
 ## Dev Note