dsh-plugin-dev-kb 1.3.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.5.1] - 2026-10-21
+
+- **知识库同步上游 master `687f282e`（2026-10-17）**：
+  - 站点镜像 188 → **192 页**（中英各 96），全量刷新；`kb/extra/` 补充文档 182 → **439 篇**
+    （上游 `docs/` 大幅扩充，按 docs.ts 发布清单差集重建）；索引 373 → **634 文件**。
+  - 修复 `kb/meta/source.json` 历史 bug：自始以 GBK 编码提交（含 BOM + 控制字符），
+    JSON.parse 恒失败、中文字段永久乱码；现重写为 UTF-8 无 BOM。
+
+## [1.5.0] - 2026-10-21
+
+- **定位升级为「dsh 插件辅助」**（插件 id / 包名 `dsh-plugin-dev-kb` 不变，避免破坏挂载与市场收录）。
+- 新增 `dsh-dev-sandbox` 技能：独立 dev profile 开发沙箱工作流——开发中的插件隔离装进
+  `~/.dsh/profiles/dev`（默认名，用户可指定），agent 自主后台启动（`dsh web --profile dev
+  --port 3081`，npx 拉与主力同版本的 dsh CLI）、自主重启（查端口 PID → Stop-Process → 起回）、
+  读 `skipping profile bundle` 警告与崩溃栈、headless 冒烟验证；插件崩了只崩沙箱，
+  绝不影响主力 dsh，全程不要求用户重启。含初始化（`plugin --profile dev add file:` /
+  `link:` 挂载 / 兼容闸门 / 双挂载禁令）与进主力 profile 的收尾流程。
+- `lib/index.js` 无需改动：skills/ 目录自动扫描，新技能文件即插即用。
+
+## [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**
+> **192-page official mirror · 439 supplementary docs · 634-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 —
@@ -21,16 +21,16 @@ once this plugin is installed, the agent automatically loads the knowledge base
 ## What is this
 
 - **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.).
+  `docs/` of the `deepseek-ai/deepseek-harness` repository (links rewritten to site routes, verbatim identical to the live site). 192 pages in both Chinese and English.
+- **Supplementary docs**: 439 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.
 
 ## Features
 
 - **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.);
+  192 pages in both Chinese and English, links rewritten to site routes, verbatim identical to the live site;
+- **Repo supplementary docs**: 439 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 (634 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,25 +12,30 @@
 
 [**中文**](./README.md) | [English](./README.en.md)
 
-> **188 页官方镜像 · 62 篇补充文档 · 253 文件搜索索引 · 0 运行时依赖**
+> **192 页官方镜像 · 439 篇补充文档 · 634 文件搜索索引 · 0 运行时依赖**
 
-**写 dsh 插件时的随身官方文档**：把 DeepSeek Harness 官方文档站点
+**写 dsh 插件时的随身辅助**：① 把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
-装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页。
+装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页；
+② 附带 `dsh-dev-sandbox` 技能：独立 dev profile 开发沙箱工作流，开发中的插件隔离运行，
+agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh。
 
 ## 这是什么
 
 - **站点完整镜像**：官方文档（VitePress）由仓库 `deepseek-ai/deepseek-harness` 的 `docs/` 原始 Markdown
-  投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 188 页。
-- **补充文档**：仓库 `docs/` 中未发布到站点的 62 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范等）。
+  投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 192 页。
+- **补充文档**：仓库 `docs/` 中未发布到站点的 439 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）。
 - **agent 友好**：`skills/dsh-plugin-dev-kb.md` 技能让 dsh 在插件开发任务中自动加载，获知知识库位置、
   主题导航与检索策略；`kb/meta/topics.md` 按任务场景映射要读的文件；`kb/meta/search-index.json` 提供全量检索。
+- **开发沙箱**：`skills/dsh-dev-sandbox.md` 技能提供独立 dev profile（`~/.dsh/profiles/dev`，可自定义）
+  沙箱工作流——初始化（兼容闸门 / link: 挂载）、后台启动（独立端口）、自主重启、headless 冒烟验证，
+  全程 agent 闭环，不要求用户重启。
 
 ## 功能
 
 - **官方文档完整镜像**：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 +98,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` 自动生成。共 192 个站点页面（中英双语），另有 439 个补充文档在 `extra/`。
 
 ## 中文站点（根路径）
 
@@ -17,10 +17,12 @@
 | 通过 GitHub Webhook 创建评审会话 | [https://deepseek-harness.github.io/deepseek-harness/guide/github-review](https://deepseek-harness.github.io/deepseek-harness/guide/github-review) | `site/guide/github-review.md` |
 | 连接第三方记忆 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/plugin-market](https://deepseek-harness.github.io/deepseek-harness/guide/plugin-market) | `site/guide/plugin-market.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 +43,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 +56,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` |
@@ -65,12 +67,12 @@
 | 注册表 | [https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/registry](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/registry) | `site/reference/cordis-api/registry.md` |
 | Service | [https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/service](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/service) | `site/reference/cordis-api/service.md` |
 | Cordis 入门 | [https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) | `site/reference/cordis-primer.md` |
+| 实验性插件记录目录 | [https://deepseek-harness.github.io/deepseek-harness/reference/experimental-persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/experimental-persistence-catalog) | `site/reference/experimental-persistence-catalog.md` |
 | DeepSeek Harness 架构 | [https://deepseek-harness.github.io/deepseek-harness/reference](https://deepseek-harness.github.io/deepseek-harness/reference) | `site/reference/index.md` |
 | 会话持久化事件目录 | [https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog) | `site/reference/persistence-catalog.md` |
 | 用户审批 | [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 +81,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,14 +97,14 @@
 | 遥测（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` |
 | spill 存储 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/spill](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/spill) | `site/reference/subsystems/spill.md` |
 | 存储 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/storage](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/storage) | `site/reference/subsystems/storage.md` |
-| Subagent | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subagent](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subagent) | `site/reference/subsystems/subagent.md` |
+| 子代理 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subagent](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subagent) | `site/reference/subsystems/subagent.md` |
 | 子进程 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subprocess](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/subprocess) | `site/reference/subsystems/subprocess.md` |
 | 系统提示词组装 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/system-prompt](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/system-prompt) | `site/reference/subsystems/system-prompt.md` |
 | 持久 PTY 会话 | [https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/terminal](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/terminal) | `site/reference/subsystems/terminal.md` |
@@ -145,22 +147,24 @@
 | 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` |
+| Plugin markets | [https://deepseek-harness.github.io/deepseek-harness/en/guide/plugin-market](https://deepseek-harness.github.io/deepseek-harness/en/guide/plugin-market) | `site/en/guide/plugin-market.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` |
@@ -171,12 +175,12 @@
 | Registry | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-api/registry](https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-api/registry) | `site/en/reference/cordis-api/registry.md` |
 | Service | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-api/service](https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-api/service) | `site/en/reference/cordis-api/service.md` |
 | Cordis Primer | [https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-primer](https://deepseek-harness.github.io/deepseek-harness/en/reference/cordis-primer) | `site/en/reference/cordis-primer.md` |
+| Experimental Plugin Record Catalog | [https://deepseek-harness.github.io/deepseek-harness/en/reference/experimental-persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/en/reference/experimental-persistence-catalog) | `site/en/reference/experimental-persistence-catalog.md` |
 | DeepSeek Harness Architecture | [https://deepseek-harness.github.io/deepseek-harness/en/reference](https://deepseek-harness.github.io/deepseek-harness/en/reference) | `site/en/reference/index.md` |
 | Session Persistence Event Catalog | [https://deepseek-harness.github.io/deepseek-harness/en/reference/persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/en/reference/persistence-catalog) | `site/en/reference/persistence-catalog.md` |
 | 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 +189,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,14 +205,14 @@
 | 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` |
 | Spill Storage | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/spill](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/spill) | `site/en/reference/subsystems/spill.md` |
 | Storage | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/storage](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/storage) | `site/en/reference/subsystems/storage.md` |
-| Subagent | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subagent](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subagent) | `site/en/reference/subsystems/subagent.md` |
+| Subagents | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subagent](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subagent) | `site/en/reference/subsystems/subagent.md` |
 | Subprocess | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subprocess](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/subprocess) | `site/en/reference/subsystems/subprocess.md` |
 | System Prompt Assembly | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/system-prompt](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/system-prompt) | `site/en/reference/subsystems/system-prompt.md` |
 | Persistent PTY Sessions | [https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/terminal](https://deepseek-harness.github.io/deepseek-harness/en/reference/subsystems/terminal) | `site/en/reference/subsystems/terminal.md` |
@@ -226,5 +230,5 @@
 
 ---
 
-*站点页面：188（中文 94，英文 94）*
+*站点页面：192（中文 96，英文 96）*
 

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
 
@@ -23,26 +23,28 @@ Each fact has one home: the tier whose job it is; elsewhere, link there.
 | [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
 | [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 |
+| [defensive-patterns/](defensive-patterns/README.md) | Rules this repository enforces in review, split by artifact: one general bug-class page plus per-domain pages | Type definitions and semantics (→ subsystems), decision rationale (→ Agent Notes) |
 | [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 |
 | [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
-| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md), [cli-help](cli-help.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
 | Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
 
-Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link; review-enforced rules → `defensive-patterns/`.
 
 ## 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 +56,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` ≤ 2,080; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 810 and this file ≤ 1,430; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `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 +72,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/agent-lifecycle.md

@@ -0,0 +1,91 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected, first batch empty, or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Hooks: <code>agent/request</code> waterfall
+  Driver->>LLM: prepareCall(config, signal)
+  Note over Driver,LLM: cancellation during either async phase commits neither system nor users
+  Note over Driver,Session: synchronous admission using the prepared call capability
+  Driver->>Session: <code>system/message</code> ordered per-node reconciliation
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Session: <code>request/header</code> and <code>request/context</code> as needed
+  Driver->>Driver: derive and freeze request from the log
+  Driver->>LLM: bound prepared call through <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>assistant/attempt</code>
+    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
+
+`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery runs within the open step and retries only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative. Each retry prepares its call and reconciles the retained rendered assembly before request derivation, without repeating assembly, pre-step, or user admission.
+
+The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
+
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.