dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/README.md

@@ -1,83 +1,88 @@
-# DeepSeek Harness 文档知识库
-
-本地镜像的 DeepSeek Harness 官方文档知识库，用于辅助 Harness **插件开发**。内容抓取自官方文档站点
-<https://deepseek-harness.github.io/deepseek-harness/>，并以**仓库内原始 Markdown**（`deepseek-ai/deepseek-harness` 的 `docs/` 目录）重建，比抓取渲染后的 HTML 保真度更高、链接与代码块完整。
-
-## 目录结构
-
-```
-knowledge/deepseek-harness/
-├── README.md         本文件：总览与使用指南
-├── INDEX.md          全部页面的 站点 URL ↔ 本地文件 对照索引（自动生成）
-├── site/             线上站点的完整镜像（中英双语，链接已按站点路由重写）
-│   ├── index.md            中文首页（/deepseek-harness/）
-│   ├── guide/              入门：quickstart / providers / python-sdk / github-review /
-│   │                       schedule / mcp-memory
-│   ├── develop/            开发：basic(第一个插件/tool/config/publish)、
-│   │                       framework(生命周期/service/事件)、practice、cordis-tutorial(7 章)
-│   ├── reference/          参考：架构、capability-seams、config-catalog、tool-catalog、
-│   │                       api-gateway、cordis-api、cookbook、subsystems(46 个子系统页)…
-│   └── en/                 英文站镜像（/deepseek-harness/en/...），结构同上
-├── extra/            仓库 docs/ 中未发布到站点的补充文档（开发参考）
-│   ├── glossary.md         术语表（capability seam 等核心概念）
-│   ├── defensive-patterns.md / testing.md / development.md / rescope.md …
-│   ├── module-graph.md     模块依赖全景图（125KB）
-│   ├── cookbook/           adding-a-vendored-package 等仓库内 cookbook
-│   ├── 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、抓取时间、统计
-    └── site-pages.txt      线上站点页面清单（由投影结果生成，188 页）
-```
-
-## 插件开发学习路径（从 `site/` 开始）
-
-1. **第一个插件** — `site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，`ctx.effect()` 自动清理）
-2. **开发一个 Tool** — `site/develop/basic/tool.md`（工具定义 DSL）
-3. **插件配置** — `site/develop/basic/config.md`；**打包安装** — `site/develop/basic/publish.md`
-4. **框架能力** — `site/develop/framework/index.md`（生命周期）、`service.md`（服务与依赖注入）、`events.md`（事件系统）
-5. **Cordis 框架教程** — `site/develop/cordis-tutorial/`（7 章：插件/生命周期/服务/事件/配置/组合与热重载/进入 Harness）
-6. **实战** — `site/develop/practice/index.md`（能力三层拆分）、`llm-adapter.md`、`dynamic-cordis.md`（运行时动态装配 Cordis）
-7. **按需查阅** — `site/reference/`：
-   - 架构总览 `reference/index.md`；能力服务 `reference/capability-seams.md`；Agent 生命周期 `reference/agent-lifecycle.md`
-   - 插件配置目录 `reference/config-catalog.md`；Tool Schema 目录 `reference/tool-catalog.md`；持久化事件 `reference/persistence-catalog.md`；API Gateway `reference/api-gateway.md`（Typert Remote 方法/RPC 约定）
-   - Cordis API `reference/cordis-api/`（Context / Events / Fiber / Registry / Service / 继承接口面）
-   - Cookbook `reference/cookbook/`（新增 package / tool / LLM adapter / 设置卡片 / 扩展模式）
-   - 子系统 `reference/subsystems/`（core / scope / session / tools / shell / filesystem / subagent / sandbox / approval / conversation / slots / web-client … 共 46 页）
-
-## 更新方法
-
-知识库与仓库 `master` 分支对齐（见 `meta/source.json` 的 commit）。需要刷新时：
-
-```sh
-# 1. 重新克隆仓库
-git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git <tmp>
-
-# 2. 安装投影依赖（mdast 三个包）。仓库本身是 pnpm workspace（package.json 含
-#    workspace: 协议），npm 无法直接在其内安装；装到克隆目录的上级，Node 的 ESM
-#    解析沿 node_modules 向上查找时即可命中。
-cd <tmp>/.. && npm install --no-save --no-package-lock mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm
-
-# 3. 运行站点投影器（Node ≥ 22.19；24 默认启用 type stripping）。
-#    上游已无 run-projector.ts，改为调用 scripts/project-doc-site.ts 的 projectDocs()：
-cd <tmp> && node --input-type=module -e "import('./scripts/project-doc-site.ts').then(m => { m.projectDocs(); console.log('projected') })"
-#    输出到 website/.generated/
-
-# 4. 用 website/.generated/ 覆盖本插件的 kb/site/；
-#    用 <tmp>/docs/ 中未发布的 Markdown 刷新 kb/extra/（对照 website/docs.ts 的
-#    docsPages source/sourceAliases 集合求差集）
-
-# 5. 在本插件根目录重新生成索引与 INDEX.md，并更新 meta/source.json 与统计
-node scripts/rebuild-index.mjs
-```
-
-站点投影逻辑为仓库内 `website/docs.ts`（发布清单）+ `scripts/project-doc-site.ts`（链接重写/图片复制，由 `website/.vitepress/config.ts` 在构建时调用）。
-
-## 统计
-
-- 站点页面：188 个 Markdown（中文 94 + 英文 94），4 张图片
-- 补充文档：182 个 Markdown（`extra/`）
-- 来源 commit：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（master，2026-10-10 同步）
+# DeepSeek Harness 文档知识库
+
+本地镜像的 DeepSeek Harness 官方文档知识库，用于辅助 Harness **插件开发**。内容抓取自官方文档站点
+<https://deepseek-harness.github.io/deepseek-harness/>，并以**仓库内原始 Markdown**（`deepseek-ai/deepseek-harness` 的 `docs/` 目录）重建，比抓取渲染后的 HTML 保真度更高、链接与代码块完整。
+
+## 目录结构
+
+```
+knowledge/deepseek-harness/
+├── README.md         本文件：总览与使用指南
+├── INDEX.md          全部页面的 站点 URL ↔ 本地文件 对照索引（自动生成）
+├── site/             线上站点的完整镜像（中英双语，链接已按站点路由重写）
+│   ├── index.md            中文首页（/deepseek-harness/）
+│   ├── guide/              入门：quickstart / providers / python-sdk / github-review /
+│   │                       schedule / mcp-memory
+│   ├── develop/            开发：basic(第一个插件/tool/config/publish)、
+│   │                       framework(生命周期/service/事件)、practice、cordis-tutorial(7 章)
+│   ├── reference/          参考：架构、capability-seams、config-catalog、tool-catalog、
+│   │                       api-gateway、cordis-api、cookbook、subsystems(46 个子系统页)…
+│   └── en/                 英文站镜像（/deepseek-harness/en/...），结构同上
+├── extra/            仓库 docs/ 中未发布到站点的补充文档（开发参考）
+│   ├── glossary.md         术语表（capability seam 等核心概念）
+│   ├── defensive-patterns.md / testing.md / development.md / rescope.md …
+│   ├── module-graph.md     模块依赖全景图（125KB）
+│   ├── cookbook/           adding-a-vendored-package 等仓库内 cookbook
+│   ├── 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、抓取时间、统计
+    └── site-pages.txt      线上站点页面清单（由投影结果生成，188 页）
+```
+
+## 插件开发学习路径（从 `site/` 开始）
+
+1. **第一个插件** — `site/develop/basic/index.md`（插件 = 导出 `apply(ctx)` 的模块，`ctx.effect()` 自动清理）
+2. **开发一个 Tool** — `site/develop/basic/tool.md`（工具定义 DSL）
+3. **插件配置** — `site/develop/basic/config.md`；**打包安装** — `site/develop/basic/publish.md`
+4. **框架能力** — `site/develop/framework/index.md`（生命周期）、`service.md`（服务与依赖注入）、`events.md`（事件系统）
+5. **Cordis 框架教程** — `site/develop/cordis-tutorial/`（7 章：插件/生命周期/服务/事件/配置/组合与热重载/进入 Harness）
+6. **实战** — `site/develop/practice/index.md`（能力三层拆分）、`llm-adapter.md`、`dynamic-cordis.md`（运行时动态装配 Cordis）
+7. **按需查阅** — `site/reference/`：
+   - 架构总览 `reference/index.md`；能力服务 `reference/capability-seams.md`；Agent 生命周期 `reference/agent-lifecycle.md`
+   - 插件配置目录 `reference/config-catalog.md`；Tool Schema 目录 `reference/tool-catalog.md`；持久化事件 `reference/persistence-catalog.md`；API Gateway `reference/api-gateway.md`（Typert Remote 方法/RPC 约定）
+   - Cordis API `reference/cordis-api/`（Context / Events / Fiber / Registry / Service / 继承接口面）
+   - Cookbook `reference/cookbook/`（新增 package / tool / LLM adapter / 设置卡片 / 扩展模式）
+   - 子系统 `reference/subsystems/`（core / scope / session / tools / shell / filesystem / subagent / sandbox / approval / conversation / slots / web-client … 共 46 页）
+
+## 更新方法
+
+**一键刷新（推荐）**：`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. 重新克隆仓库
+git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness.git <tmp>
+
+# 2. 安装投影依赖（mdast 三个包）。仓库本身是 pnpm workspace（package.json 含
+#    workspace: 协议），npm 无法直接在其内安装；装到克隆目录的上级，Node 的 ESM
+#    解析沿 node_modules 向上查找时即可命中。
+cd <tmp>/.. && npm install --no-save --no-package-lock mdast-util-from-markdown mdast-util-gfm micromark-extension-gfm
+
+# 3. 运行站点投影器（Node ≥ 22.19；24 默认启用 type stripping）。
+#    上游已无 run-projector.ts，改为调用 scripts/project-doc-site.ts 的 projectDocs()：
+cd <tmp> && node --input-type=module -e "import('./scripts/project-doc-site.ts').then(m => { m.projectDocs(); console.log('projected') })"
+#    输出到 website/.generated/
+
+# 4. 用 website/.generated/ 覆盖本插件的 kb/site/；
+#    用 <tmp>/docs/ 中未发布的 Markdown 刷新 kb/extra/（对照 website/docs.ts 的
+#    docsPages source/sourceAliases 集合求差集）
+
+# 5. 在本插件根目录重新生成索引与 INDEX.md，并更新 meta/source.json 与统计
+node scripts/rebuild-index.mjs
+```
+
+站点投影逻辑为仓库内 `website/docs.ts`（发布清单）+ `scripts/project-doc-site.ts`（链接重写/图片复制，由 `website/.vitepress/config.ts` 在构建时调用）。
+
+## 统计
+
+- 站点页面：192 个 Markdown，4 张图片
+- 补充文档：554 个 Markdown（`extra/`）
+- 来源 commit：`39163dd30f703a79079e2d2446545cff3c453738`（master，2026-11-14 同步）

package/kb/extra/AGENTS.md

@@ -1,77 +1,77 @@
-# 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 [archived doc-tiers Agent Note](../.agents/notes/archived/process/2026-07-04-doc-tiers-and-budgets.md) records the historical rationale.
-
-## Document structure
-
-These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
-
-Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
-
-Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
-
-Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
-
-## The tier taxonomy: one home per fact
-
-Each fact has one home: the tier whose job it is; elsewhere, link there.
-
-| Tier | Job | Does NOT belong there |
-|---|---|---|
-| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
-| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
-| [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), [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; review-enforced rules → `defensive-patterns/`.
-
-## Writing rules
-
-- **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](../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 ([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
-
-[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
-
-When the gate goes red:
-
-1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
-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` ≤ 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:
-
-- 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.
-- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
-- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
-- 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).
-
-## 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.
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc-writing](../.agents/skills/dsh-doc-writing/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
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [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), [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; review-enforced rules → `defensive-patterns/`.
+
+## Writing rules
+
+- **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](../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 ([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
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+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` ≤ 2,080; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 810 and this file ≤ 1,430; `packages/README.md` ≤ 1,100; 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-writing](../.agents/skills/dsh-doc-writing/SKILL.md) runs this list as an audit:
+
+- 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.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- 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).
+
+## 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 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 证据，从最终干净提交录制，并准确说明演示范围。