dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [1.8.0] - 2026-11-07
+
+- **新增 `dsh_kb_read` 工具**：知识库局部阅读——按知识库相对路径 + 行号窗口（`path`/`offset`/`limit`，
+  单窗口上限 400 行）读原文，输出带行号，自动防大文件整读、拒绝目录越界与非 .md 文件；
+  自动提示中英对照版本的对应路径（`site/` ↔ `site/en/`、`extra/*.zh.md` ↔ `extra/*.md`）与续读位置。
+  与 `dsh_kb_search` 形成检索→阅读闭环，替代用通用 read 工具手动定位。
+- **新增版本感知横幅**（`lib/kb-version.js`）：宿主加载插件时探测 `@deepseek-ai/dsh`（或 dsh-base）
+  实际版本，`dsh_kb_search` / `dsh_kb_read` 输出自带「知识库快照同步自上游 master，可能领先宿主」
+  提示 + 对应 `extra/upgrade-guide/<vX.Y.Z>` 指南路径（精确命中优先，否则取 ≤ 宿主版本的最大指南目录）。
+  探测失败安全（拿不到版本只少横幅，不影响工具可用性）。
+- **新增 `dsh-plugin-starter` 技能**：从零新建合规 dsh 插件的脚手架指南——骨架文件清单
+  （package.json 含 `dsh.bundle.patch` 与 peer 显式预发布范围、cordis.patch.yml、双语 README
+  含安装命令/双标题/相关插件段、selfcheck、CHANGELOG）、命名与 needsConfig 反向检测红线、
+  GitHub description/homepage/topics 补齐命令、沙箱冒烟验证闭环（与 dsh-dev-sandbox 联动）。
+- `scripts/selfcheck.mjs` 扩展 1.8.0 断言（kb_read 注册 / 版本探测接入 / starter 技能完整性）；
+  新增 `scripts/smoke.mjs` 离线冒烟（假 harness 真执行两个工具的 execute，26 项断言）。
+- 主技能正文使用流程更新为「search → kb_read → 文件工具兜底」三段式。
+
+## [1.7.0] - 2026-11-07
+
+- **新增 `dsh-upgrade-assistant` 技能**：升级 dsh 版本时的迁移助手。agent 按标准流程工作——
+  确定当前/目标版本 → 读取知识库 `extra/upgrade-guide/` 区间内逐版本官方升级指南与
+  `extra/persistence-changes/` 持久化变更 → 输出备份/变更摘要/插件兼容闸门预判/回滚方案四段式
+  检查清单 → 升级后按「skipping profile bundle」警告与旧会话加载情况逐条验证。
+  明确红线：未备份不动 profile、不擅自用 allow-version 绕过兼容闸门、知识库快照缺目标版本时如实告知而非编造。
+
+## [1.6.1] - 2026-11-07
+
+- **知识库内容同步至上游 master `fcc0ad4`**（2026-11-07）：`site/` 全量刷新（192 页不变，内容更新）；
+  `extra/` 以发布清单差集重建 **439 → 468 篇**（删除 191 篇过时文档，新增 0.2.1/0.2.2 系列升级指南、
+  2026-10/11 持久化变更记录、forge / computer-use / mcp 等子系统文档）；索引与 INDEX.md 已重建（663 文件）。
+- **新增 `npm run refresh-kb` 一键刷新脚本**（`scripts/refresh-kb.mjs`）：克隆上游 → 站点投影 →
+  覆盖 site/extra → 重建索引与 `meta/source.json`，全流程自动化。
+- **新增 GitHub Action 每周自动同步**（`.github/workflows/refresh-kb.yml`）：每周一从上游 master
+  刷新知识库，有变更即自动提交；README 顶部新增「kb sync」动态 badge（数据来自 `meta/source.json`）。
+- README（中英）统计更新，新增「30 秒验证装好了」段。
+
+## [1.6.0] - 2026-10-30
+
+- **新增 `dsh_kb_search` 工具**：知识库本地打分检索（零 token、毫秒级、零运行时依赖）。
+  一次调用返回命中文件路径 + 行号 + 上下文片段（每文件最多 3 处，前后各 2 行），替代
+  agent 多轮 grep/read 检索 634 文件知识库。
+  - 参数：`query`（空白分词多词；空或 `"topics"` 返回主题导航）、`scope`（`api` 只搜
+    API 签名/目录类文档：tool-catalog / config-catalog / capability-seams / cordis-api /
+    subsystems 等）、`lang`（zh 默认；en 首次调用现场建索引）、`maxResults`（默认 8）。
+  - 打分：标题 ×8、路径 ×4、正文行命中平方和（多词同现加权）、路径子词弱匹配
+    （`ctx.tools.register` → tool.md）、`site/develop|guide/` 教程优先 +2。
+  - 索引惰性构建（首次调用时，~60ms / 314 个中文文件）、内存缓存、只读不写；
+    `searchTool: false` 可关闭。
+  - 技能 `dsh-plugin-dev-kb` 检索指南同步改为「工具优先，文件工具兜底」。
+
 ## [1.5.2] - 2026-10-21
 
 - `dsh-dev-sandbox` 技能去掉固定 `dev` profile 约定：**沙箱 profile 名由 agent 按任务自定**

package/README.en.md

@@ -12,29 +12,50 @@
 
 [中文](./README.md) | **English**
 
-> **192-page official mirror · 439 supplementary docs · 634-file search index · 0 runtime dependencies**
+> **192-page official mirror · 468 exclusive supplementary docs · weekly auto-sync from upstream · 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 —
 once this plugin is installed, the agent automatically loads the knowledge base when writing plugins and locates docs by task scenario, so you never have to dig through web pages again.
+It also ships the `dsh_kb_search` tool (since 1.6.0): local scored search over the knowledge base that returns matched files, line numbers, and context snippets in a single call,
+and the `dsh-upgrade-assistant` skill (since 1.7.0): when you upgrade dsh, the agent reads the official per-version upgrade guides and persistence-change records, produces a migration checklist, flags plugin compatibility-gate risks, and plans a rollback path.
+Since 1.8.0 it also ships a version-aware banner plus the `dsh_kb_read` tool (tool output flags "knowledge-base snapshot vs host dsh version" drift and points at the matching upgrade guide; line-numbered windowed reading prevents whole-file reads of huge docs) and the `dsh-plugin-starter` skill (a scaffold guide for creating compliant dsh plugins from scratch: file checklist, marketplace/awesome gates, verification loop).
 
 ## 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). 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.).
+- **Supplementary docs**: 468 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.) — this is **exclusive content from the official repo that you won't find on the live site**.
 - **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.
+- **Local search tool**: `dsh_kb_search` performs scored search over the knowledge base (title / path / body multi-term weighting) and returns
+  matched file paths, line numbers, and context snippets in a single call; supports `scope: api` (search only API-signature/catalog docs),
+  `lang: en`, and an empty query returning topic navigation. The index is built lazily in memory (~60ms / 314 files), read-only.
+- **Version awareness (since 1.8.0)**: tool output carries a banner — host dsh version vs the knowledge-base
+  master snapshot may drift on APIs, with the matching `extra/upgrade-guide/<vX.Y.Z>` guide path; detection
+  degrades gracefully (no banner, no error).
+- **Windowed reading tool (since 1.8.0)**: `dsh_kb_read` reads originals by `path`/`offset`/`limit` line windows,
+  with numbered output, whole-file-read protection, path-escape rejection, automatic zh↔en counterpart hints, and continuation pointers.
 
 ## 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,
   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.);
+- **Repo supplementary docs**: 468 development references not published to the site (glossary, defensive patterns, module graph, testing strategy, incident postmortems, i18n specs, upgrade guides, persistence changes, etc.);
+- **Weekly auto-sync**: a GitHub Action refreshes the knowledge base from upstream master on schedule (see the "kb sync" badge above for the sync date and commit);
 - **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;
+  the `dsh_kb_search` tool locates docs in a single call; `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;
-- Pure data plugin, zero runtime dependencies, registers no tools.
+- Zero runtime dependencies; two tools (`dsh_kb_search` / `dsh_kb_read`), pure local Node implementations (no network, no file writes).
+
+## Verify in 30 seconds
+
+After installation, ask the agent in any session:
+
+> What changed in the dsh 0.2.0 settings subsystem (SettingsForms) compared to before?
+
+- If the agent uses `dsh_kb_search` and answers with details like `SettingsForms` / `.volatile()` / revision conflict detection, it is **installed correctly**;
+- If it cannot answer or the search tool is missing, the mount did not take effect — recheck the "Install" step.
 
 ## Configuration
 
@@ -80,8 +101,8 @@ After restarting, open a new session and simply ask:
 
 > Help me write a minimal dsh plugin
 
-The agent will automatically load the `dsh-plugin-dev-kb` skill (visible in the skill catalog), locate the docs via `kb/meta/topics.md`,
-and only then start working — if you see it referencing `kb/site/...` paths, the verification has passed.
+The agent will automatically load the `dsh-plugin-dev-kb` skill (visible in the skill catalog), locate the docs via the `dsh_kb_search` tool
+(or `kb/meta/topics.md`), and only then start working — if you see it referencing `kb/site/...` paths, the verification has passed.
 
 ## Directory structure
 
@@ -96,7 +117,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 (634 files)
+│   │   ├── search-index.json full index (663 files)
 │   │   ├── source.json       source commit / time / stats
 │   │   └── site-pages.txt    list of live site pages
 │   ├── INDEX.md        site URL ↔ local file mapping
@@ -107,7 +128,8 @@ dsh-plugin-dev-kb/
 ## Usage
 
 - **Agent side**: when writing plugins / Tools / config / services / events / packaging / LLM adapters, load
-  the `dsh-plugin-dev-kb` skill → read `kb/meta/topics.md` to locate → read/grep as needed.
+  the `dsh-plugin-dev-kb` skill → prefer the `dsh_kb_search` tool (one call returns matched files + line numbers + snippets;
+  `scope: api` for `ctx.*` API signatures) → read the source locally by line number; fall back to grepping `kb/` if the tool is unavailable.
 - **Human side**: browse the `kb/` directory directly, or open `kb/INDEX.md` to look things up by URL mapping.
 
 ## Self-check

package/README.md

@@ -9,45 +9,71 @@
 ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-dev-kb)
 ![Stars](https://img.shields.io/github/stars/Pasumao/dsh-plugin-dev-kb?style=social)
 ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
+![kb sync](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FPasumao%2Fdsh-plugin-dev-kb%2Fmaster%2Fkb%2Fmeta%2Fsource.json)
 
 [**中文**](./README.md) | [English](./README.en.md)
 
-> **192 页官方镜像 · 439 篇补充文档 · 634 文件搜索索引 · 0 运行时依赖**
+> **192 页官方镜像 · 468 篇独占补充文档 · 每周自动同步上游 · 0 运行时依赖**
 
 **写 dsh 插件时的随身辅助**：① 把 DeepSeek Harness 官方文档站点
 <https://deepseek-harness.github.io/deepseek-harness/> 的全部内容整理为 dsh 原生可用的形态——
 装了这个插件，agent 写插件时自动加载知识库，按任务场景定位文档，不用再翻网页；
 ② 附带 `dsh-dev-sandbox` 技能：自建独立沙箱 profile 开发沙箱工作流（沙箱名由 agent 按任务自定），
-开发中的插件隔离运行，agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh。
+开发中的插件隔离运行，agent 自主启动 / 重启 / 冒烟验证，插件崩了不影响主力 dsh；
+③ `dsh_kb_search` 工具（1.6.0 起）：知识库本地打分检索，一次调用返回命中文件 + 行号 + 上下文片段；
+④ `dsh-upgrade-assistant` 技能（1.7.0 起）：升级 dsh 版本时，agent 自动读官方升级指南与持久化变更记录，
+生成迁移检查清单、预判插件兼容闸门与回滚方案；
+⑤ 版本感知横幅 + `dsh_kb_read` 工具（1.8.0 起）：工具输出自动标注「知识库快照 vs 宿主 dsh 版本」差异
+并给出对应升级指南；按路径 + 行号窗口局部阅读原文，防大文件整读、自动提示中英对照；
+⑥ `dsh-plugin-starter` 技能（1.8.0 起）：从零新建合规 dsh 插件的脚手架指南（骨架清单 / 收录门槛 / 验证闭环）。
 
 ## 这是什么
 
 - **站点完整镜像**：官方文档（VitePress）由仓库 `deepseek-ai/deepseek-harness` 的 `docs/` 原始 Markdown
   投影生成（链接已按站点路由重写，与线上逐字一致）。中英双语共 192 页。
-- **补充文档**：仓库 `docs/` 中未发布到站点的 439 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）。
+- **补充文档**：仓库 `docs/` 中未发布到站点的 468 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）——这部分是**官方仓库独占内容，线上站点看不到**。
 - **agent 友好**：`skills/dsh-plugin-dev-kb.md` 技能让 dsh 在插件开发任务中自动加载，获知知识库位置、
   主题导航与检索策略；`kb/meta/topics.md` 按任务场景映射要读的文件；`kb/meta/search-index.json` 提供全量检索。
 - **开发沙箱**：`skills/dsh-dev-sandbox.md` 技能提供自建独立沙箱 profile 工作流（沙箱名 agent 按任务
   自定，不与主力 profile 重名）——初始化（兼容闸门 / link: 挂载）、后台启动（自选空闲端口）、自主重启、headless 冒烟验证，
   全程 agent 闭环，不要求用户重启。
+- **本地检索工具**：`dsh_kb_search` 工具在知识库上做打分检索（标题 / 路径 / 正文多词加权），
+  一次调用返回命中文件路径、行号与上下文片段；支持 `scope: api`（只搜 API 签名/目录类文档）、
+  `lang: en`、空 query 返回主题导航。索引惰性构建于内存（约 60ms / 314 文件），只读不写。
+- **版本感知（1.8.0 起）**：工具输出自带横幅——宿主 dsh 版本 vs 知识库 master 快照可能存在的
+  API 差异，并给出对应的 `extra/upgrade-guide/<vX.Y.Z>` 指南路径；探测失败自动降级（无横幅不报错）。
+- **局部阅读工具（1.8.0 起）**：`dsh_kb_read` 按 `path`/`offset`/`limit` 行号窗口读原文，
+  带行号输出、防大文件整读、拒绝越界路径，自动提示中英对照路径与续读位置。
 
 ## 功能
 
 - **官方文档完整镜像**：deepseek-ai/deepseek-harness 官方文档站全部内容整理为 dsh 原生可用的形态，
-  中英双语共 188 页，链接按站点路由重写，与线上逐字一致；
-- **仓库补充文档**：未发布到站点的 182 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）；
+  中英双语共 192 页，链接按站点路由重写，与线上逐字一致；
+- **仓库补充文档**：未发布到站点的 468 篇开发参考（术语表、防御模式、模块图、测试策略、事故复盘、i18n 规范、升级指南、持久化变更等）；
+- **每周自动同步**：GitHub Action 定时从上游 master 刷新（见顶部「kb sync」badge 可查同步日期与 commit）；
 - **agent 友好**：`dsh-plugin-dev-kb` 技能让 dsh 在插件开发任务中自动加载知识库；
-  `kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
+  `dsh_kb_search` 工具一次调用完成检索定位；`kb/meta/topics.md` 按任务场景映射要读的文件，`kb/meta/search-index.json` 提供全量检索；
 - **人侧可用**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅；
-- 纯数据插件，零运行时依赖，不注册任何工具。
+- 零运行时依赖；两个工具（`dsh_kb_search` / `dsh_kb_read`）为纯 Node 本地实现（不联网、不写文件）。
+
+## 30 秒验证装好了
+
+安装挂载后，随便开个会话问 agent：
+
+> dsh 0.2.0 的设置子系统（SettingsForms）和以前有什么不一样？
+
+- agent 用 `dsh_kb_search` 检索并答出 `SettingsForms` / `.volatile()` / 修订号冲突检测等细节 = **装好了**；
+- 答不上来或检索工具不存在 = 挂载没生效，回看「安装 / 挂载」一步。
 
 ## 配置
 
-无需任何配置，安装即用：
+默认零配置，安装即用：
 
 - 不读取环境变量，不需要 API Key / token，不写配置文件；
 - 挂载后 `skills/dsh-plugin-dev-kb.md` 技能在会话启动时进入可用技能列表，自动生效；
-- 知识库更新走 `npm run rebuild-index`（见「更新知识库」），无手动配置项。
+- `dsh_kb_search` 工具随宿主启动注册，首次调用时构建索引（毫秒级）；如需关闭，
+  在 profile 的插件配置里设 `searchTool: false`（只保留技能，不注册工具）；
+- 知识库更新走 `npm run rebuild-index`（见「更新知识库」）。
 
 ## 安装 / 挂载
 
@@ -85,8 +111,8 @@ npm install
 
 > 帮我写一个最小的 dsh 插件
 
-agent 会自动加载 `dsh-plugin-dev-kb` 技能（技能清单里可见），按 `kb/meta/topics.md`
-定位文档后再动手——看到它引用 `kb/site/...` 路径即验证通过。
+agent 会自动加载 `dsh-plugin-dev-kb` 技能（技能清单里可见），调用 `dsh_kb_search`
+（或读 `kb/meta/topics.md`）定位文档后再动手——看到它引用 `kb/site/...` 路径即验证通过。
 
 ## 目录结构
 
@@ -112,7 +138,9 @@ dsh-plugin-dev-kb/
 ## 使用
 
 - **agent 侧**：写插件 / Tool / 配置 / 服务 / 事件 / 打包 / LLM 适配器时，加载
-  `dsh-plugin-dev-kb` 技能 → 读 `kb/meta/topics.md` 定位 → 按需 read/grep。
+  `dsh-plugin-dev-kb` 技能 → 首选调 `dsh_kb_search` 工具检索（一次拿命中文件 + 行号 + 片段，
+  `scope: api` 查 `ctx.*` API 签名）→ 用 read 按行号局部读原文；工具不可用时退回
+  grep `kb/` 兜底。
 - **人侧**：直接浏览 `kb/` 目录，或打开 `kb/INDEX.md` 按 URL 对照查阅。
 
 ## 自检
@@ -136,13 +164,13 @@ npm run selfcheck   # 结构完整 + 入口 / bundle patch 存在性
 
 | 插件（npm） | GitHub | 说明 |
 |---|---|---|
-| [dsh-notify](https://www.npmjs.com/package/dsh-notify) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-notify) | Windows 原生通知 + 系统托盘 |
+| [dsh-notify](https://www.npmjs.com/package/dsh-notify) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-notify) | Windows 原生通知  |
 | [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-choice-refresh) | 选择增强：重新生成选项 / 更多选项 |
 | [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-image-tools) | 图片选择卡 + 回复内嵌图片 + 盲模型收图 |
 | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-table-zoom) | 聊天长表格浮窗查看 + 一键复制 Markdown |
 | [dsh-plugin-windows-guard](https://www.npmjs.com/package/dsh-plugin-windows-guard) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-windows-guard) | Windows 环境防坑：守则技能 + 乱码检测 / 危险写拦截 / 编码诊断修复 |
-| [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code 风格文件浏览器 + 可编辑预览 |
 | [dsh-plugin-context-trim](https://www.npmjs.com/package/dsh-plugin-context-trim) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-context-trim) | 会话注入门控：skill / tool / 提示词段落按会话裁剪 |
+| [dsh-plugin-future-session](https://www.npmjs.com/package/dsh-plugin-future-session) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-future-session) | 现实/未来会话：工具调用由继承全部上下文的未来会话代执行，主上下文只保留「一次调用+一份结论」 |
 > 本系列其余插件见 [Pasumao · dsh 插件](https://github.com/Pasumao)；觉得好用欢迎到 GitHub 点 ⭐。
 
 ## AI 生成声明

package/kb/INDEX.md

@@ -1,6 +1,6 @@
 # DeepSeek Harness 文档索引
 
-> 由 `scripts/rebuild-index.mjs` 自动生成。共 192 个站点页面（中英双语），另有 439 个补充文档在 `extra/`。
+> 由 `scripts/rebuild-index.mjs` 自动生成。共 192 个站点页面（中英双语），另有 468 个补充文档在 `extra/`。
 
 ## 中文站点（根路径）
 
@@ -17,7 +17,7 @@
 | 通过 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/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` |
@@ -153,7 +153,7 @@
 | 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` |
+| Plugin indexes | [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` |

package/kb/README.md

@@ -50,7 +50,12 @@ knowledge/deepseek-harness/
 
 ## 更新方法
 
-知识库与仓库 `master` 分支对齐（见 `meta/source.json` 的 commit）。需要刷新时：
+**一键刷新（推荐）**：`npm run refresh-kb`（克隆上游 → 投影 → 覆盖 site/extra → 重建索引与元数据），
+完成后 `npm run selfcheck` 自检。GitHub Action（`.github/workflows/refresh-kb.yml`）每周一自动执行同一
+脚本，有变更即自动提交；README 顶部「kb sync」badge 数据来自 `meta/source.json`。
+
+以下为手动步骤（理解流程 / 非 Windows 环境参考）。知识库与仓库 `master` 分支对齐
+（见 `meta/source.json` 的 commit）。需要刷新时：
 
 ```sh
 # 1. 重新克隆仓库
@@ -78,6 +83,6 @@ node scripts/rebuild-index.mjs
 
 ## 统计
 
-- 站点页面：188 个 Markdown（中文 94 + 英文 94），4 张图片
-- 补充文档：182 个 Markdown（`extra/`）
-- 来源 commit：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（master，2026-10-10 同步）
+- 站点页面：192 个 Markdown，4 张图片
+- 补充文档：468 个 Markdown（`extra/`）
+- 来源 commit：`fcc0ad462172522aaf5c93a7b2e01f6b9f0b0159`（master，2026-11-07 同步）

package/kb/extra/AGENTS.md

@@ -74,4 +74,4 @@ Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this l
 
 ## Repository references
 
-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.
+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 commit identifiers containing a hexadecimal letter and disallowed organization URLs in maintained files. Decimal-only tokens are ignored to avoid collisions with numeric data, even when they identify commits.

package/kb/extra/cli-help.md

@@ -108,21 +108,29 @@ Usage: dsh --profile headless [options] [task...]
 Answer one task and exit; the answer goes to stdout and diagnostics to stderr.
 
 Arguments:
-  task               the task text; multiple words are joined by spaces, and `-`
-                     reads stdin
+  task                        the task text; multiple words are joined by
+                              spaces, and `-` reads stdin
 
 Options:
-  --json             write newline-delimited run events to stdout instead of the
-                     final message
-  --session-id <id>  adopt the persisted Session with this id; an unknown id is
-                     an error
-  -h, --help         show this help
+  --json                      write newline-delimited run events to stdout
+                              instead of the final message
+  --session-id <id>           adopt the persisted Session with this id; an
+                              unknown id is an error
+  --permission-mode <preset>  select a configured permission preset for this
+                              task, including on resume
+  --approval-policy <policy>  set approval behavior after selecting the
+                              permission preset (choices: "ask", "never")
+  --add-dir <path>            allow an additional physical absolute directory
+                              under workspace-write (repeatable)
+  -h, --help                  show this help
 
 Examples:
   dsh --profile headless "run the tests"          answer one task and exit
   echo "run the tests" | dsh --profile headless   read the task from stdin
   dsh --profile headless --json "run the tests"   emit machine-readable run events
   dsh --profile headless --session-id session-… "continue"   resume an existing Session
+  dsh --profile headless --permission-mode workspace-write --add-dir /repo/.git "commit the fix"
+                                                        grant shared Git metadata for this task
 
 ```
 

package/kb/extra/cli-help.zh.md

@@ -110,21 +110,29 @@ Usage: dsh --profile headless [options] [task...]
 Answer one task and exit; the answer goes to stdout and diagnostics to stderr.
 
 Arguments:
-  task               the task text; multiple words are joined by spaces, and `-`
-                     reads stdin
+  task                        the task text; multiple words are joined by
+                              spaces, and `-` reads stdin
 
 Options:
-  --json             write newline-delimited run events to stdout instead of the
-                     final message
-  --session-id <id>  adopt the persisted Session with this id; an unknown id is
-                     an error
-  -h, --help         show this help
+  --json                      write newline-delimited run events to stdout
+                              instead of the final message
+  --session-id <id>           adopt the persisted Session with this id; an
+                              unknown id is an error
+  --permission-mode <preset>  select a configured permission preset for this
+                              task, including on resume
+  --approval-policy <policy>  set approval behavior after selecting the
+                              permission preset (choices: "ask", "never")
+  --add-dir <path>            allow an additional physical absolute directory
+                              under workspace-write (repeatable)
+  -h, --help                  show this help
 
 Examples:
   dsh --profile headless "run the tests"          answer one task and exit
   echo "run the tests" | dsh --profile headless   read the task from stdin
   dsh --profile headless --json "run the tests"   emit machine-readable run events
   dsh --profile headless --session-id session-… "continue"   resume an existing Session
+  dsh --profile headless --permission-mode workspace-write --add-dir /repo/.git "commit the fix"
+                                                        grant shared Git metadata for this task
 
 ```
 

package/kb/extra/cookbook/adding-a-plugin-preview.md

@@ -1,52 +1,45 @@
-# Cookbook: Add a built-in plugin feature preview
+# Cookbook: Add a plugin feature preview
 
 English | [中文](adding-a-plugin-preview.zh.md)
 
-Plugin Manager owns optional feature illustrations for built-in bundles. Follow this guide when editing its internal `BUNDLE_PREVIEWS` map. Packages cannot declare illustrations through their manifest or exports; third-party plugins have no preview interface.
+A feature preview is an optional illustration in a bundle's detail document, the document that its page in **Plugins** shows below the description. Follow this guide when drawing one for an official bundle. The detail document itself is declared through [`meta.detail`](adding-a-package.md#plugin-display-metadata).
 
 ## 1. Decide whether an image helps
 
-Show one concrete result or recognizable capability. Omit the map entry when the description is enough: no image is required, and omission reserves no space. Essential instructions stay in localized text or configuration outside the illustration.
+Show one concrete result or recognizable capability. Omit the image when the description is enough: no image is required. Essential instructions stay in the bundle's description or in configuration outside the illustration.
 
 ## 2. Draw one fixed-size SVG
 
 | Item | Requirement |
 |---|---|
-| Count | Zero or one logical feature image per bundle. English and Chinese files are alternatives for that image, not a gallery or carousel. |
-| Format | SVG only: `width="640" height="300" viewBox="0 0 640 300"` (32:15). Raster preview files and other dimensions are unsupported. |
-| Languages | Supply both `en` and `zh`. Translate headings, annotations, and example content; preserve official brand assets and names. No single strings, arrays, or extra languages. |
+| Count | Zero or one feature image per bundle. English and Chinese files are alternatives for that image, not a gallery or carousel. |
+| Format | SVG: `width="640" height="300" viewBox="0 0 640 300"` (32:15). |
+| Languages | Supply both an English and a Chinese file. Translate headings, annotations, and example content; preserve official brand assets and names. |
 | Composition | One main example, optionally with one close-up. Keep important content about 32 canvas units from the edges. Review text at the page's actual size. |
 | Typography | Outline lettering into paths using a suitable font. Match the feature and neighboring UI; do not rely on browser font substitution. |
 | Theme | Compare light and dark themes. One illustration serves both; avoid transparent dark text that disappears on dark backgrounds. |
 
-The SVG is self-contained: no fonts, remote resources, scripts, handlers, animation, stylesheets, `text`, or `foreignObject`. An `image` element may embed an unchanged official PNG/JPEG/WebP brand asset as a base64 data URL. Small plugin icons remain geometry-only. This exception preserves brand artwork and does not permit raster preview files. Validation checks the data-URL envelope, not decoded pixels; the page renders the SVG through `<img>`. Both raw language files together must stay within 1 MiB. They are embedded as base64 data URLs in the Plugin Manager client bundle, so keep them small.
+The SVG is self-contained: no fonts, remote resources, scripts, handlers, animation, stylesheets, `text`, or `foreignObject`. An `image` element may embed an unchanged official PNG/JPEG/WebP brand asset as a base64 data URL. Small plugin icons remain geometry-only. The page renders the SVG through `<img>`. Keep each file small; the Host refuses images above plugin-manager's `detailImageMaxBytes`, 5 MiB by default.
 
-## 3. Register the internal pair
+## 3. Make it the detail document
 
-Put `<feature>-preview.svg` and `<feature>-preview.zh.svg` under [Plugin Manager assets](../../packages/client/ui-plugin-manager/src/client/assets/). Import both into [PluginManagerPage.tsx](../../packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx), then add one exact built-in package name to `BUNDLE_PREVIEWS`:
+Save the pair as `docs/preview.svg` and `docs/preview.zh.svg` in the bundle package, beside `docs/DETAIL.md` and `docs/DETAIL.zh.md`, and make the image the only line of each document:
 
-```ts ignore-check
-import examplePreview from './assets/example-preview.svg'
-import examplePreviewZh from './assets/example-preview.zh.svg'
-
-// One entry in the existing Map<string, Readonly<Record<'en' | 'zh', string>>>.
-['@deepseek-ai/dsh-example-bundle', { en: examplePreview, zh: examplePreviewZh }]
+```markdown
+![Example feature preview](preview.svg)
 ```
 
-Keep the map's required `en` and `zh` type. Do not add package metadata, a Host read method, exported preview resources, or a third-party declaration path. Use the [badge skill](../../packages/client/ui-plugin-manager/src/client/assets/badge-skill-preview.svg) and [voice input](../../packages/client/ui-plugin-manager/src/client/assets/voice-input-preview.svg) illustrations as examples. The voice transcript is explanatory sample content, not a recording result.
+The Chinese document references `preview.zh.svg` with Chinese alternative text. Use the [badge skill](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md) and [voice input](../../packages/experimental/voice-input-bundle/docs/DETAIL.md) documents as examples. The voice transcript is explanatory sample content, not a recording result. Describe what the bundle does and how to use it, at the level of behavior, in `meta.description`, which the page shows above the image.
 
-## 4. Keep the page contract
+## 4. Page behavior
 
 | Item | Current behavior |
 |---|---|
-| Position | Below the description and status notices, above components and source information; aligned with the description. |
-| Spacing | 24 px above the image; 32 px before the following details section. |
-| Display | One `<img>`, natural 640×300 canvas, at most the available width and 320 px high; proportional scaling. The page supplies border and 16 px corners. |
-| Language | The current UI language selects one of the required files. Alternative text uses the localized plugin name. |
-| Availability | Visible before activation. Decode failure shows a localized notice without blocking controls. Lists and component rows retain their small icons. |
+| Position | First in the detail document, which is the first section of the bundle page, below the description and status notices. |
+| Display | The detail document renders the image at most its own width, inside its height-bounded scroll area. |
+| Language | The document for the UI language references its own file. |
+| Availability | Visible before activation. Lists and component rows keep their small icons. |
 
 ## 5. Validate and review
 
-Run `pnpm exec vitest run scripts/builtin-plugin-preview.spec.ts packages/client/ui-plugin-manager/tests/components.client.spec.tsx scripts/client-bundle-css.spec.ts`, then `pnpm run build`. The asset test checks every registered pair, fixed SVG dimensions, self-contained content, and combined size. Type checking requires both languages. These checks enforce format; visual quality and equivalent meaning in both languages still require review.
-
-Open the real plugin details in English and Chinese before activation. Decode the image and confirm 640×300 natural dimensions, placement, light/dark readability, and no horizontal overflow at 390 px. Also check a built-in without artwork and a third-party plugin. Follow [record-browser-gif](../../.agents/skills/record-browser-gif/SKILL.md) for PR evidence; record from the final clean commit and label the demonstrated flow accurately.
+`scripts/plugin-preview-assets.spec.ts` checks every preview pair in a bundle's `docs` directory: the fixed canvas, absent scripts, stylesheets, text elements, and external references, the 1 MiB pair limit, and English and Chinese files that differ. Then open the real plugin details in English and Chinese before activation and confirm the image loads, its placement, light/dark readability, and no horizontal overflow at 390 px; review owns visual quality and equivalent meaning in both languages. Follow [record-browser-gif](../../.agents/skills/record-browser-gif/SKILL.md) for PR evidence; record from the final clean commit and label the demonstrated flow accurately.

package/kb/extra/cookbook/adding-a-plugin-preview.zh.md

@@ -1,52 +1,45 @@
-# Cookbook: 添加内置插件功能配图
+# Cookbook: 添加插件功能配图
 
 [English](adding-a-plugin-preview.md) | 中文
 
-插件管理拥有内置组合包的可选功能配图。编辑其内部 `BUNDLE_PREVIEWS` 映射时遵循本指引。包不能通过 manifest 或 exports 声明配图；第三方插件没有配图接口。
+功能配图是组合包详细介绍文档中的可选插图；详细介绍文档是该组合包在**插件**中的页面显示在描述下方的文档。为官方组合包绘制配图时遵循本指引。详细介绍文档本身通过 [`meta.detail`](adding-a-package.zh.md#plugin-display-metadata) 声明。
 
 ## 1. 判断是否需要配图
 
-展示一个具体结果或容易辨认的能力。文字说明足够时不添加映射项：配图不是必需的，省略时不占空间。必要操作说明仍放在图外的本地化文字或配置中。
+展示一个具体结果或容易辨认的能力。文字说明足够时省略配图：配图不是必需的。必要操作说明仍放在组合包描述或图外的配置中。
 
 ## 2. 绘制一张固定尺寸 SVG
 
 | 项目 | 要求 |
 |---|---|
-| 数量 | 每个组合包零张或一张逻辑配图。英文和中文文件是同一张图的替代版本，不是图库或轮播。 |
-| 格式 | 仅 SVG：`width="640" height="300" viewBox="0 0 640 300"`（32:15）。不支持位图配图文件或其他尺寸。 |
-| 语言 | 同时提供 `en` 和 `zh`。翻译标题、标注和示例内容，保留官方品牌素材和名称。不使用单个字符串、数组或额外语言。 |
+| 数量 | 每个组合包零张或一张配图。英文和中文文件是同一张图的替代版本，不是图库或轮播。 |
+| 格式 | SVG：`width="640" height="300" viewBox="0 0 640 300"`（32:15）。 |
+| 语言 | 同时提供英文和中文文件。翻译标题、标注和示例内容，保留官方品牌素材和名称。 |
 | 构图 | 一个主体示例，可选一个局部特写。重要内容距边缘约 32 个画布单位；按页面实际显示尺寸检查文字。 |
 | 字体 | 选择合适字体并把文字转成路径，匹配功能及相邻界面，不依赖浏览器字体替换。 |
 | 主题 | 对比浅色和深色主题。同一张图服务两种主题，避免透明底深色文字在深色背景中消失。 |
 
-SVG 必须自包含：不使用字体、远程资源、脚本、事件处理器、动画、样式表、`text` 或 `foreignObject`。`image` 元素可以通过 base64 data URL 嵌入未改动的官方 PNG/JPEG/WebP 品牌素材。小插件图标仍仅使用几何图形。此例外用于保留品牌素材，不允许直接使用位图配图文件。校验检查 data URL 结构，不解码像素；页面通过 `<img>` 渲染 SVG。两种语言的原始文件合计不超过 1 MiB。图片会以 base64 data URL 嵌入插件管理 client bundle，因此应控制大小。
+SVG 必须自包含：不使用字体、远程资源、脚本、事件处理器、动画、样式表、`text` 或 `foreignObject`。`image` 元素可以通过 base64 data URL 嵌入未改动的官方 PNG/JPEG/WebP 品牌素材。小插件图标仍仅使用几何图形。页面通过 `<img>` 渲染 SVG。每个文件都应控制大小；Host 会拒绝超过 plugin-manager 的 `detailImageMaxBytes`（默认 5 MiB）的图片。
 
-## 3. 注册内部双语配图
+## 3. 用它作为详细介绍文档
 
-将 `<feature>-preview.svg` 和 `<feature>-preview.zh.svg` 放在[插件管理素材目录](../../packages/client/ui-plugin-manager/src/client/assets/)下。在 [PluginManagerPage.tsx](../../packages/client/ui-plugin-manager/src/client/PluginManagerPage.tsx) 中导入两者，再向 `BUNDLE_PREVIEWS` 添加一个精确的内置包名：
+将这对文件保存为组合包中的 `docs/preview.svg` 和 `docs/preview.zh.svg`，与 `docs/DETAIL.md` 和 `docs/DETAIL.zh.md` 放在一起，并把图片作为每份文档唯一的一行：
 
-```ts ignore-check
-import examplePreview from './assets/example-preview.svg'
-import examplePreviewZh from './assets/example-preview.zh.svg'
-
-// One entry in the existing Map<string, Readonly<Record<'en' | 'zh', string>>>.
-['@deepseek-ai/dsh-example-bundle', { en: examplePreview, zh: examplePreviewZh }]
+```markdown
+![Example feature preview](preview.svg)
 ```
 
-保留映射中必需的 `en` 和 `zh` 类型。不添加包元数据、Host 读取方法、导出的配图资源或第三方声明入口。可参考[徽章技能](../../packages/client/ui-plugin-manager/src/client/assets/badge-skill-preview.svg)和[语音输入](../../packages/client/ui-plugin-manager/src/client/assets/voice-input-preview.svg)配图。语音图中的转写文字是说明性示例，不是录音结果。
+中文文档引用 `preview.zh.svg`，并使用中文替代文字。可参考[徽章技能](../../packages/experimental/badge-skill-bundle/docs/DETAIL.md)和[语音输入](../../packages/experimental/voice-input-bundle/docs/DETAIL.md)文档。语音图中的转写文字是说明性示例，不是录音结果。组合包做什么、怎么用，按行为层面写在 `meta.description` 中，页面将其显示在配图上方。
 
-## 4. 保持页面契约
+## 4. 页面行为
 
 | 项目 | 当前行为 |
 |---|---|
-| 位置 | 在描述和状态提示下方、组件与来源信息上方，与说明左边缘对齐。 |
-| 间距 | 图片上方 24 px，后续详情区前 32 px。 |
-| 显示 | 一个 `<img>`，原始画布 640×300，最大宽度为可用宽度，最大高度 320 px，等比缩放；页面提供边框及 16 px 圆角。 |
-| 语言 | 当前 UI 语言选择必需的两份文件之一；替代文字使用本地化插件名。 |
-| 可用性 | 启用前可见；解码失败显示本地化提示，不阻塞操作；列表和组件行保留小图标。 |
+| 位置 | 位于详细介绍文档开头；该文档是组合包页面的第一个区域，在描述和状态提示下方。 |
+| 显示 | 详细介绍文档以不超过文档自身宽度的尺寸渲染图片，图片位于有高度上限的滚动区域内。 |
+| 语言 | 当前 UI 语言对应的文档引用其自己的文件。 |
+| 可用性 | 启用前可见；列表和组件行保留小图标。 |
 
 ## 5. 校验与验收
 
-运行 `pnpm exec vitest run scripts/builtin-plugin-preview.spec.ts packages/client/ui-plugin-manager/tests/components.client.spec.tsx scripts/client-bundle-css.spec.ts`，再运行 `pnpm run build`。素材测试检查每个注册条目的双语文件、固定 SVG 尺寸、自包含内容和合计大小；类型检查要求同时提供两种语言。这些检查约束格式；视觉质量及双语含义一致仍需人工审阅。
-
-在真实插件详情页分别使用英文和中文，启用前解码图片，确认原始尺寸 640×300、插入位置、浅色及深色主题的可读性，以及 390 px 宽度下没有横向溢出。同时检查一个无配图的内置插件和一个第三方插件。按 [record-browser-gif](../../.agents/skills/record-browser-gif/SKILL.md) 制作 PR 证据，从最终干净提交录制，并准确说明演示范围。
+`scripts/plugin-preview-assets.spec.ts` 检查组合包 `docs` 目录中的每一对配图：固定画布；不使用脚本、样式表、`text` 元素或外部引用；每对文件合计不超过 1 MiB；英文和中文文件不相同。然后在真实插件详情页分别使用英文和中文，启用前确认图片能加载，并检查插入位置、浅色及深色主题的可读性，以及 390 px 宽度下没有横向溢出；审阅负责检查视觉质量及双语含义是否一致。按 [record-browser-gif](../../.agents/skills/record-browser-gif/SKILL.md) 制作 PR 证据，从最终干净提交录制，并准确说明演示范围。

package/kb/extra/cookbook/reviewing-persistence-type-changes.md

@@ -43,7 +43,7 @@ A recorded decision does not hide the transition from this comparison. `--check`
 
 Record the commits supplying those files with the report. Add `--json` for structured output. This read-only comparison groups shared changes with their affected roots and uses actual literal `kind`/`form` values instead of union positions. Ambiguous alternatives remain separate additions and removals. Its compatibility section copies every root's authoritative classifier result; the structural explanation does not replace acknowledgement checks. Current catalog labels and declaration names are descriptive metadata; structural anchors and fingerprints identify types.
 
-The current machine inventory stores complete graphs in `roots`. A `types` entry contains `digest`, `names`, and `sources`, plus an explicit `schema` when roots cannot reconstruct that graph exactly. Readers resolve omitted graphs from root subgraphs by digest and validate explicit graphs directly, preserving every type and its metadata. Historical full entries remain readable. `formatVersion` identifies normalization rules; storage compaction does not change root fingerprints or require an acknowledgement.
+Every inventory uses the [node-table layout](../persistence-changes/README.md#files-and-ownership); both comparison inputs must be generated by the current tooling. `formatVersion` identifies normalization rules; the storage layout does not change root fingerprints or require an acknowledgement.
 
 <a id="acknowledge"></a>
 ## 1. Record the change

package/kb/extra/cookbook/reviewing-persistence-type-changes.zh.md

@@ -43,7 +43,7 @@ pnpm --silent run persistence-review --before .artifacts/base.schema.json --afte
 
 在报告旁记录这些文件对应的 commit。添加 `--json` 可获取结构化输出。此只读比较将共享变更与受影响的根类型归组，使用实际字面量 `kind`/`form` 值代替联合类型位置。无法唯一匹配的候选项保留为独立的新增与删除。兼容性部分复制每个根类型的权威分类结果；结构说明不替代确认检查。当前目录标签和声明名称是描述元数据；结构锚点和指纹标识类型。
 
-当前机器清单在 `roots` 中保存完整图。每个 `types` 条目包含 `digest`、`names` 和 `sources`；若根无法精确重建该图，条目还会保存显式 `schema`。读取器按摘要从根的子图恢复省略的图，并直接验证显式图，保留每个类型及其元数据。历史完整条目仍然可读。`formatVersion` 标识规范化规则；存储压缩不改变根指纹，也不需要确认记录。
+所有清单都使用[节点表布局](../persistence-changes/README.zh.md#files-and-ownership)；两个比较输入都必须由当前工具生成。`formatVersion` 标识规范化规则；存储布局不改变根指纹，也不需要确认记录。
 
 <a id="acknowledge"></a>
 ## 1. 记录变更