dsh-plugin-guide 0.3.21 → 0.3.23

package/guide/when-to-retire-a-plugin.zh-CN.md

@@ -0,0 +1,127 @@
+# DSH 插件生态实测：我怎么判断一个插件该不该继续做
+
+> English: [when-to-retire-a-plugin.md](when-to-retire-a-plugin.md)
+
+## 0. 我做了什么，为什么公开
+
+2026-10-05，我把 npm 上的 DSH 生态全量拉了一遍（324 个真插件），把自己每个插件与同赛道对手比了周下载量：**3 个退役、7 个冻结、1 个改判**。公开判据，是因为「该不该继续维护」人人都会遇到，却大多无数据可依。
+
+## 1. 判据
+
+先讲清楚一件事：**这不是一次清理门户，是一次自我审计。** 官方没有要淘汰第三方插件——宿主 `CONTRIBUTING.md:19` 说，官方仓里的包并不天然比社区包更重要；官方展示的作用是「一个想法、一次官方展示、一种灵感来源，但不是来自我们的命令」。压力来自第三方作者。这一点在第 3 节用数据说。
+
+**两条硬标准。**
+
+**硬标准 A：同一能力已被官方做进内核。** 措辞很重要。不是「官方有一个同名包」，而是「官方**默认挂载**」或「官方已把它做成**一等子系统**」。这两者的差别，是这次审查里最容易搞错的地方。
+
+**硬标准 B：同能力面上，第三方存在采用度显著更高的实现。** 「显著」量级定为「高出一个数量级」。判据只用同生态内的**相对**量级，不用绝对值。
+
+**一条软标准。**
+
+**软标准 C：维护成本 vs 真实使用者数。** 这条最容易被误用。我现在自己的 Web profile 跑的是 stock 组合，一个家族插件都不装。所以「我还用不用」不能当判据——这批仓对我来说是**发布物**，不是**自用工具**。能当判据的是两句话：**对外是否还有人需要**，和**这份维护成本是否还值**。
+
+**一条元规则。**
+
+**只承认文件级证据。** 任何结论必须能指到具体文件、具体行，或具体的 npm / GitHub API 读数；指不到的一律标「未证实」，不进决策。这条规则在本轮纠正了 4 处我原本的前提，其中两处直接关于「官方到底有没有这个能力」——一处是官方做了、只是没挂载，另一处是官方挂了、而我原以为没有。
+
+**三档处置。**
+
+| 档位 | 数量 | 包 | 含义 |
+|---|---|---|---|
+| 🪦 **退役** | 3 | `dsh-background-agents`、`dsh-session-pin`、`dsh-team-rooms` | **停止兼容性更新**：README 顶部 RETIRED 横幅、npm 已 `deprecate`、GitHub 仓已归档（只读） |
+| 🧊 **冻结** | 7 | `dsh-budget`、`dsh-memento`、`dsh-draw`、`dsh-claude-move`、`dsh-reach`、`dsh-wechat`、`dsh-defend` | **不发新功能；但仍然可用、没有废弃**，只有真实故障才修 |
+| ✅ **改判** | 1 | `dsh-catalog` | 原本判退役，复核后改判：它是家族内部工具，不与第三方目录竞争，**继续维护** |
+
+另有两支早期走廊线 `dsh-plugin-upgrade-015`（停在 npm `0.1.1`）与 `dsh-plugin-upgrade-016`（从未发布）已退役；插件升级由 `dsh-plugin-upgrade` 一条线独家继续。
+
+## 2. 数据（一）：3 个退役
+
+这一档基本只用了硬标准 A。
+
+| 包 | 官方对应物 | 判定依据 |
+|---|---|---|
+| `dsh-background-agents` | `tool-subagent`（`backgroundMode: continuable`）+ `tool-subagent-control` + `tool-jobs` | 官方**默认挂载**。而且这个包**自己的 README 已经写了**：后台代理那一半 *superseded by DSH's native continuable subagents* |
+| `dsh-session-pin` | `client-ui-workspace` 的 pin action | 官方**默认挂载**：会话右键菜单有 `Pin session`、行悬停有 pin 按钮、支持在置顶块内拖拽排序、宿主侧持久化 `pinnedSessionIds` 并广播 `pinned` 增量帧。插件这边剩下的只有行颜色 / 置顶面板 / 头部总开关这类外观增强 |
+| `dsh-team-rooms` | `dsh-experimental-agent-team` | 官方把「团队」做成**一等子系统**：隐式根 roster、持久邮箱（离线成员恢复后收信、去重）、共享任务 DAG（CAS 防覆盖、依赖解锁、文件写冲突告警）、`wait_agent`。**同时**满足硬标准 B：自身周下载 **589（家族最低）**，第三方 `@nanmicoder/dsh-agent-teams` **13,273（22×）** |
+
+关于 `dsh-team-rooms` 有一处必须说清楚：官方那个 `dsh-experimental-agent-team` 是**可选项**，base 里默认 `disabled`，而且启用时**要求禁用** `send_message` / `interrupt_agent` / `list_agents`。所以它不是「默认挂载式」的覆盖。它进内核、加上第三方 22× 的采用度，两条合起来才是这条判据成立的原因。
+
+一处不好看的数据我照实写：`dsh-session-pin` 在官方内置 pin 之后**仍有 1,015 周下载**。报告给了两种解释——外观增强确实有真实需求，或者下载量口径本身有噪声。我无法从现有数据里区分这两者，所以按判据退役，但把这个数字留在这里。
+
+## 3. 数据（二）：7 个冻结 —— 倍数表
+
+采集时间 2026-10-05，来源 npm registry API。**先说口径**：npm 周下载量**不等于用户数**（含 CI、镜像、重复安装），所以下表只用**包与包之间的相对量级**，不用绝对值。
+
+| 能力面 | 我的包（周下载） | 同赛道第三方（周下载） | 倍数 | 对手强在哪 |
+|---|---|---|---|---|
+| 成本 / 用量计费 | `dsh-budget` 1,079 | **`dsh-cost-meter` 33,526** | **31×** | 170+ 模型价目、11 家 Coding Plan 额度查询 |
+| 跨会话记忆 | `dsh-memento` 1,202 | **`@openviking/dsh-memory-plugin` 10,160** | **8×** | 字节跳动 volcengine 官方组织仓，有公司级资源投入 |
+| IM 桥接 | `dsh-reach` ~0.6k ／ `dsh-wechat` 752 | **`@xmanrui/dsh-im` 17,384** | **23×** | 一个包覆盖 10 个通道（微信 / 飞书 / 企微 / 钉钉 / QQ / TG / WA / Slack / Discord / Matrix） |
+| 注入与破坏性命令防护 | `dsh-defend` 937 | **`cc-safety-net` 13,087** | **14×** | 作为 coding-agent CLI hook 直接拦破坏性命令与密钥文件访问，接入路径短、覆盖人群广 |
+| 图像生成 | `dsh-draw` 973 | **`dsh-image-gen` 7,216** | **7×** | 多供应商 |
+| 会话 / 配置迁移 | `dsh-claude-move` 843 | **`dsh-chat-import` 5,111** | **6×** | 覆盖 25+ 个 AI coding agent |
+
+**补四条背景读数。**
+
+- **生态盘子。** 两个关键词交叉取并集：8,620 条命中、772 个候选，逐个核对 `dsh` 字段确认真插件 **324 个**。（口径说明：这个数**只算 npm 上声明了 `dsh` 清单、真的能被 `dsh plugin add` 装上的包**。社区目录站公布的条目数会高得多——它们把 GitHub 仓、子目录、未发布的候选都计进去，所以两个数字不该互相引用，也不该相加。）
+- **不是个别现象。** **16 个能力面里，我的包在 14 个面上不是第一**，多数落后 **3–31 倍**；差距最大的一处在上下文洞察面：`dsh-fast` 917 对 `dsh-context` 38,999（**43×**）。
+- **家族内第一不等于赛道第一。** `dsh-mcp-panel` 2,472 是家族内第一，但同赛道 `dsh-mcp-connector` 是 7,556（3×）。
+- **没有一个是放任不管的仓。** 在这份报告之前，全部相关仓在 2026-10-05 当天都还有推送。退役和冻结是一次**主动判断**，不是清理死项目。
+
+**为什么是这 7 个？** 它们同时满足两件事：对手不只是下载量更高，而是**在能力面上做得更宽**（多供应商 / 多通道 / 多 agent / 官方组织资源）；而我在这些面上继续投入，已经不太可能产出「只有我能给」的东西。
+
+也有两个反例必须一起说，否则判据会变成「落后就退」：
+
+- **`dsh-fast`（917 对 `dsh-context` 38,999，43×）留在现状。** 它是轻量包，维护成本本就低，冻结省不下多少力气。**落后不是判据。**
+- **硬标准 A 不成立、只成立硬标准 B，也足以冻结。** `dsh-draw` 这类包，官方对应物是**零**（`text-to-image` / `image_gen` / `txt2img` 在宿主全仓 0 命中），`dsh-memento` 也一样（官方 `capability-seams.md` 里没有 memory seam，`docs/user/guide/mcp-memory.md:5,31` 明写 shipped composition 里**没有** memory server）。**「官方没做」不等于「我该继续重投」**——记忆赛道至少有 10 个对手，`dsh-memento` 大概排在第 8 位。
+
+## 4. 我在哪些面仍然第一
+
+只列输的那一半，是误导。这一节是同时期的「仍然只有我」清单（2026-10-05）：
+
+| 能力面 | 我的包（周下载） | 状态 |
+|---|---|---|
+| LSP 动作面 | `dsh-lsp-actions` **1,170** | **全生态无强力对手**。官方 LSP **刻意排除** rename / formatting / diagnostics / symbol 列表 |
+| 插件认证 / 体检 / 评分 | `dsh-plugin-doctor` 218、`dsh-score`、`dsh-test-drive`、`dsh-plugin-certification` | **无对手**。生态里只有 `dsh-why`（137）、`dsh-fix`（1,503）这类「修坏插件」，不是评分体系 |
+| 研究 / 报告引擎 | `dsh-research-report` 1,019、`dsh-industry-research` 926、`dsh-fund-research` 802 | **基本无对手**（垂直领域） |
+| 数据质量 | `dsh-data-quality` 769 | 接近的只有 `dsh-data-cleaning-agent` |
+| 声明式权限 + 网络策略 | `dsh-permission-rules` **1,459** | 下载量上 `dsh-perm-gate` 1,851 **略高**（报告原文标注为「对手略高」）；但**进程级 HTTP / CONNECT 代理网络策略**无人复制 |
+| GitHub CI 自动化 | `dsh-github` 359 | 无对手（也是最低的一个，但确实没人在做） |
+
+两条交叉验证：
+
+- **star 冠军不是旗舰安全插件，是研究线。** `dsh-research-report` 215★ 与 `dsh-industry-research` 212★ 都高于 `dsh-memento` 139★、`dsh-permission-rules` 118★、`dsh-mcp-panel` 75★。
+- **「官方没有」和「第三方没做」是两件独立的事。** 报告确认官方至今为零的面至少有 8 个（`dsh-defend`、`dsh-mask`、`dsh-budget`、`dsh-draw`、`dsh-translate`、`dsh-library`、`dsh-autotier`、`dsh-plugin-*` 工具链）——其中一部分被第三方占了，一部分还空着。**空缺本身不是护城河；没人在做、且我做得动，才是。**
+
+## 5. 「冻结」不等于「废弃」
+
+这一节是写给使用者的。
+
+| 状态 | 会删包 / 撤版吗 | 还会修 bug 吗 | npm 状态 | 仓库状态 |
+|---|---|---|---|---|
+| 🪦 **退役**（3 个） | 不会 | **不会**（含兼容性更新） | 已 `deprecate` | 已归档，只读 |
+| 🧊 **冻结**（7 个） | 不会 | **会**——但只有当宿主破坏性变更让它完全不可用时，才做最小兼容修复 | 正常，**没有** deprecated | 正常，**未归档** |
+| 其余 | 不会 | 会 | 正常 | 正常 |
+
+**已安装的用户该怎么做：什么都不用做。** 冻结的 7 个照常安装、照常运行，接口不变、版本不撤。只有当某次宿主升级真的把它弄坏了才需要动作——那种情况请开 issue，我会修。**如果你要的是新功能，请去用第 3 节表里那些对手**——它们在各自赛道上的采用度都明显更高，这也是我冻结自己这几个包的原因。
+
+**为什么不用「删包」表达态度？** 因为删了之后，下一个人搜不到这个包，也看不到退役原因。所以家族表**行不删、只加状态备注**：退役与冻结的仓全部保留在每一张家族表里，用状态列标注 `🚫 已退役` / `🧊 已冻结`，描述原文照旧。
+
+## 6. 给其他插件作者的 8 个自查问题
+
+1. **官方是「有这个包」，还是「默认挂载」？** 官方 `experimental/*`、`computer-use`、`browser-use`、`lsp`、`speech-to-text` **都不在 stock 组合里**。「官方有包」不等于「用户装完就有」。
+2. **`base` 里有这一行，等于用户有这个能力吗？** 不一定。Web 补丁会把 base 进程级挂载的模型面向工具行**逐条 disable**，再交给每个 agent preset 重新挂载。只查 `base/cordis.patch.yml` 会得出偏乐观的结论。
+3. **你搜对手时用的是能力关键词，还是包名？** 只比包名会漏掉全部对手：`dsh-cost-meter` 与 `dsh-budget` 名字完全不同，`cc-safety-net` 与 `dsh-defend` 也是。
+4. **同名等于同一件事吗？** 官方 `dsh-experimental-auto-review` 与 `dsh-auto-review` 同名，但安全模型相反：官方用当前 agent 自己的 provider / model，并自述 *can allow unsafe actions, deny useful work, and spend additional tokens*，没有确定性豁免、没有持久授权；我的是独立只读的第二模型 reviewer，失败即 **fail-closed**。这不算被替代。
+5. **你的下载量能被第二个信号验证吗？** `dsh-budget` 周下载 1,079，star 只有 **10**——高下载更像 CI / 镜像噪声，低 star 才是真实吸引力。反过来 `dsh-auto-review` 有 **10 个 open issue**，那是真有人在用、在报障。单看下载量会骗人。
+6. **「我还在用吗」是不是你的判据？** 如果不用了，它不该当判据（我的 Web profile 现在就跑 stock 组合）。换成这两句：**对外是否还有人需要？维护成本是否还值？**
+7. **落后多少倍才该退？** 没有阈值。`dsh-fast` 落后 43× 留在现状，`dsh-defend` 落后 14× 被冻结。冻结要付的代价是「承认自己不再是这条赛道最好的选择」，所以只值得对「继续投入也不会产出独特东西」的包付这个代价。
+8. **你的决定写进 README 了吗？** 只写在脑子里、或只写在一份内部报告里，等于没写。冻结的 7 个各自有 `## Maintenance status: 🧊 FROZEN` 一节，含实测对比表与「对手强在哪」的说明；退役的 3 个 README 顶部有 RETIRED 横幅。**使用者至少应该能从 README 里知道你为什么不做了。**
+
+## 7. 事实陈述
+
+- **家族现状**：家族表现在列 **44 个插件仓**（含 `dsh-plugin-upgrade-015` 的表为 45 行），其中 🚫 **已退役 3 个**、🧊 **已冻结 7 个**，其余按活跃仓维护。许可以 Apache-2.0 为主。
+- **仓库位置**：https://github.com/PerryLink
+- **数据采集时间**：2026-10-05。来源为那份自查报告——npm registry API 全量拉取、GitHub REST API 实测、宿主源码逐文件取证。**结论是可复核的**：每一条都能指到具体文件或具体 API 读数，指不到的一律标「未证实」。
+
+最后一句，说给可能想接手的人：**`dsh-reach` 与 `dsh-wechat` 这两条 IM 桥接线，欢迎接手维护。** 它们被冻结的理由很具体——`@xmanrui/dsh-im` 在一个包里覆盖了 10 个通道，那是一件比我做得好的事。如果这两条线对你有用，而你想让它们继续长下去，两个仓都是宽松许可（`dsh-reach` 为 Apache-2.0、`dsh-wechat` 为 MIT），欢迎开 issue 谈接手。

package/icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="dsh-plugin-guide">
+  <rect width="64" height="64" rx="14" fill="#0b6bcb" />
+  <path d="M14 20h36v5H14zM14 30h24v5H14zM14 40h30v5H14z" fill="#ffffff" />
+  <circle cx="48" cy="32" r="5" fill="#ffd166" />
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-plugin-guide",
+    "description": "DeepSeek Harness plugin-development knowledge base: official docs mirror, contract rules, migration guide, verified issue index, and the dsh-plugin-dev CLI."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "dsh-plugin-guide",
+    "description": "DeepSeek Harness 插件开发知识库：官方文档副本、契约红线、迁移指南、源码核实的问题索引，以及 dsh-plugin-dev 命令行工具。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "The dsh-plugin-guide knowledge base plus the dsh-plugin-dev CLI toolchain: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill, with a scaffolder, static checker, and pack verifier for building DSH plugins.",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,9 @@
   },
   "exports": {
     ".": "./index.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
   },
   "files": [
     "index.js",
@@ -17,10 +19,11 @@
     "dist",
     "templates",
     "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
     "SKILL.md",
     "guide",
-    "references",
-    "scripts",
+    "references",    "scripts",
     "LICENSE",
     "NOTICE.md",
     "README.md",
@@ -53,6 +56,7 @@
     "typecheck:checkout": "tsc -p tsconfig.checkout.json --noEmit",
     "test": "vitest run",
     "check:readmes": "node scripts/check-readme-sync.mjs",
+    "build:llms": "node scripts/build-llms-full.mjs",
     "check:kit": "pwsh -File scripts/verify-kit.ps1",
     "verify:artifacts": "node scripts/verify-artifacts.mjs",
     "verify:self-contained": "pnpm run build && node dist/dsh-plugin-dev.js verify",

package/references/official-docs/AGENTS.md

@@ -8,6 +8,8 @@ Public APIs are pre-stable; update every consumer. Follow [version/status](docs/
 
 Acknowledge [declared persistence-type changes](docs/cookbook/reviewing-persistence-type-changes.md).
 
+Record each externally perceptible breaking change immediately in an [upgrade guide](.agents/skills/dsh-create-upgrade-guide/SKILL.md).
+
 **Application launch.** Only `dsh` profiles launch supported Node apps; package bins, demos, and public SDK argv escapes are forbidden ([rule](docs/architecture.md#application-launch)).
 
 ## Repository layout
@@ -66,7 +68,6 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   mcp/                  external tools
   experimental/         pre-stable prototypes; public by default with explicit private exceptions
   test-support/         test infrastructure
-  runtime-diagnostics/  runtime invariants
   util/                 zero-dependency utilities
 python/      Python SDK/runtime (python/README.md)
 native/      @deepseek-ai/node-addon-system source (native/README.md)
@@ -101,6 +102,8 @@ pnpm run test:docs      # quick documentation checks (no build; doc-quick aggreg
 pnpm run website:build  # VitePress build (doubles as dead-link check)
 pnpm dsh --profile headless "task"  # run one task from source (needs DEEPSEEK_API_KEY)
 pnpm run demo:ptc -- "task"  # headless PTC mode run (needs key)
+pnpm run dev:web | dev:desktop  # build, then launch; Web also rebuilds client bundles on edits. start:web | start:desktop skip the build
+make web|dev-web|desktop|dev-desktop|build  # the same commands; ARGS='--no-open' forwards options
 ```
 
 ### Host sandbox failures
@@ -124,11 +127,10 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 
 ## Conventions
 
-- Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.
+- Packages use `@deepseek-ai/dsh-<name>`; vendor is [rescoped](docs/rescope.md) and `private: true`. Harness packages declare `@deepseek-ai/cordis` in `peerDependencies`/`devDependencies`. Workspace dependency sections use DSH `workspace:*`, vendor/native `workspace:~` ([rules](.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
 - ESM everywhere (`"type": "module"`). Use package names across packages and `.ts` in local relative imports. Config subprocesses run built `lib/` under plain Node; source regressions use their declared launcher ([testing policy](docs/testing.md#test-subprocess-launch-modes)). The `dsh` CLI source launch runs through tsx's ESM-only hook (`node --import tsx/esm`); modules it reaches must stay ESM (no CJS-only exports) — Node's native TypeScript modes are unavailable across the engines range ([source-launch contract](.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md)). Raw/Web `cordis.yml` bare plugins must appear in their resolver manifest's `dependencies`; `verify-cordis-config` enforces it.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
-- **Runtime invariants assert owned relationships.** Publish `./invariant` only when independent observations can diverge. Otherwise omit its source and wiring and record why in its README; empty installers and checks of service presence, plugin metadata, effects, or fixed examples are invalid ([package invariant rules](packages/AGENTS.md)).
-- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. `SessionEventMap` members are required-on-read by default — builds that do not know a type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
+- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`. Public service methods document parameters and non-void returns. `SessionEventMap` members are required-on-read by default — builds that do not know a type refuse the log unless the event carries the envelope's `ignorable: true`; only structural format changes bump `SESSION_FORMAT_VERSION` ([mechanism](.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
@@ -140,10 +142,11 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 - **Misconfiguration fails loud** at load when self-contained, otherwise at the earliest resolvable point; never silently skip a missing referent.
 - **Opaque cross-boundary ids are branded** (`Branded<B>` from `dsh-brand`), never bare `string`.
 - **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries.
+- **No new assertions to `unknown`** (`as unknown` or `<unknown>`). Preserve or reduce the exact legacy baseline; use typed values or validation for replacements ([rule](.agents/notes/implemented/process/2026-09-19-no-unknown-casts.md)).
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
 - **Keep compiler faces explicit.** A package with both Host and Client programs exposes face-specific leaf configs and a solution-only root; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
 - **An empty `catch` names the error** and why; keep its `try` to one statement.
-- **Keep comments local.** Do not restate code, expand unrelated comments, or explain distant behavior without local need ([rationale](.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)).
+- **Keep comments local.** Do not restate code, expand unrelated comments, or explain distant behavior without local need ([rationale](.agents/skills/dsh-prose-standard/SKILL.md)).
 - **Ban `prove` + `nance`** ([rule](.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md)).
 - **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
 - **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.

package/references/official-docs/CONTRIBUTING.i18n.yaml

@@ -1,6 +1,7 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for CONTRIBUTING.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write CONTRIBUTING.md
-CONTRIBUTING.md: 9f30e23a6d9567db7d6097cb82e481b16dda299e
-CONTRIBUTING.zh.md: 35eb0b87fc4d9af11bef616039570dc5e6a1b309
+/contributing:
+  en: 08d2f421ff3617f4
+  zh: 9d060d70ad186dc5

package/references/official-docs/README.i18n.yaml

@@ -1,6 +1,34 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write README.md
-README.md: 36adfe913902e75ce0673adc2cb5cb692151a291
-README.zh.md: f6861b4c9490741b5e5f2d825a370766178dd9f6
+/deepseek-harness:
+  en: f68c4f080ce55ff2
+  zh: 88a76d7f7f0b260e
+/deepseek-harness/developer-preview:
+  en: 4ef4d8a71ac143f0
+  zh: 1bfc3149ba8e5543
+/deepseek-harness/run:
+  en: 4e0248e4c6474fc6
+  zh: eb2fb8d78c7d6bc0
+/deepseek-harness/run/run-from-npm:
+  en: e22005cd42e6cbad
+  zh: 0f536f4208df1d60
+/deepseek-harness/run/run-from-source:
+  en: 819e3f7c144d0d64
+  zh: de815f040975dba7
+/deepseek-harness/community-and-support:
+  en: 20acf6451fdc869b
+  zh: d06246dd019ecef7
+/deepseek-harness/contributing:
+  en: cabc2d3e9f8898bd
+  zh: 83b6d238bae29ce3
+/deepseek-harness/development:
+  en: 803ca2b11b497bed
+  zh: 8b4071eb0e7783ef
+/deepseek-harness/citation:
+  en: 6704e9e5a8d49a91
+  zh: 85c9cdd8d56f8e9d
+/deepseek-harness/license:
+  en: 926995344fc1c72b
+  zh: c92fab5abf85932f

package/references/official-docs/README.zh.md

@@ -48,19 +48,17 @@ pnpm dsh web
 
 - 通过 [GitHub Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions) 提交反馈或 bug 报告。
 - 为你的插件仓库添加 [`dsh-plugin`](https://github.com/topics/dsh-plugin) 话题，便于被发现。
-- 欢迎加入 DeepSeek Harness 企微群：扫码添加企微小助手并填写入群问卷，完成后小助手会邀请你入群。
+- 欢迎加入 DeepSeek Harness 企微群！扫描下方二维码填写入群问卷，小助手会定期发送入群邀请。
 
 <table>
   <thead>
     <tr>
-      <th align="center">企微小助手</th>
       <th align="center">入群问卷</th>
       <th align="center">微信公众号</th>
     </tr>
   </thead>
   <tbody>
     <tr>
-      <td align="center"><img src="https://cdn.deepseek.com/harness/readme/community-wecom-assistant.png" alt="DeepSeek Harness 企微小助手二维码" width="180" height="180"></td>
       <td align="center"><a href="https://trtgsjkv6r.feishu.cn/share/base/form/shrcnIt5twSVdLGD52KJBckGCgg"><img src="https://cdn.deepseek.com/harness/readme/community-wecom-survey.png" alt="DeepSeek Harness 入群问卷二维码" width="180" height="180"></a></td>
       <td align="center"><img src="https://cdn.deepseek.com/harness/readme/community-wechat-official-account.png" alt="DeepSeek Harness 团队微信公众号二维码" width="180" height="180"></td>
     </tr>
@@ -75,6 +73,8 @@ pnpm dsh web
 
 请先阅读[开发指南](docs/development.zh.md)与[架构文档](docs/architecture.zh.md)。
 
+`pnpm run dev:web` 会在一个终端里完成构建、启动，并在源码修改时重建 client bundle；`make help` 列出 Web 与 Desktop 对应的 Make target。完整表格见开发指南的「应用命令」一节。
+
 面向 agent：请遵循 [AGENTS.md](AGENTS.md)。
 
 ## 引用

package/references/official-docs/SNAPSHOT.md

@@ -7,10 +7,10 @@
 |---|---|
 | Source checkout | `D:\deepseek-harness` |
 | Source ref | `origin/master` |
-| Source commit | `ddefc45fbc7f8e46dd73185e68295696d1297887` |
-| Synced at (UTC) | 2026-09-19T10:42:53Z |
+| Source commit | `5badb15009ae1756c3afe0ae0cef1faafc290ccc` |
+| Synced at (UTC) | 2026-10-06T11:33:47Z |
 | Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md` (symlink target text), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml` (the upstream English `README.md` is not in this dir; its snapshot lives in `downloads/github/harness/README.md`), `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |
-| File counts | docs/: 337 md files (166 .zh.md pairs) |
+| File counts | docs/: 369 md files (182 .zh.md pairs) |
 | Pruned this run | 15 out-of-scope/upstream-deleted entries |
 
 Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).

package/references/official-docs/THIRD_PARTY_NOTICES.md

@@ -5,7 +5,7 @@
 
 DeepSeek Harness is licensed under [MIT](LICENSE). It depends on the third-party software listed below. Each project remains under its own license; nothing in this file changes those terms.
 
-This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Desktop bundled Python distributions. It is generated by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
+This file lists **direct** dependencies declared by the workspace, the explicitly disclosed official Claude Code platform payload closure, and the Bundled Python distributions. It is generated by `scripts/gen-third-party-notices.ts`: a pre-commit hook regenerates it whenever a staged file changes one of its inputs, and `scripts/gen-third-party-notices.spec.ts` asserts in the test lane that the committed bytes match. Deleting a manifest runs no hook, so that case is caught by the assertion instead. Run `pnpm run verify-third-party-notices` for the standalone check.
 
 The complete npm transitive closure, including the Landlock launcher workspace, is recorded with exact pinned versions in [`pnpm-lock.yaml`](pnpm-lock.yaml) — inspect it with `pnpm licenses list`. The Python SDK closure is recorded separately in [`python/sdk/uv.lock`](python/sdk/uv.lock).
 
@@ -36,10 +36,14 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`@anthropic-ai/sdk`](https://github.com/anthropics/anthropic-sdk-typescript) | MIT |
 | [`@babel/code-frame`](https://github.com/babel/babel) | MIT |
 | [`@browserbasehq/stagehand`](https://github.com/browserbase/stagehand) | MIT |
-| [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-harness/libreoffice-kit) | MPL-2.0 |
+| [`@deepseek-ai/libreoffice-kit`](https://github.com/deepseek-ai/dsh-libreoffice-kit) | MPL-2.0 |
 | [`@earendil-works/pi-ai`](https://github.com/earendil-works/pi) | MIT |
+| [`@eslint-community/regexpp`](https://github.com/eslint-community/regexpp) | MIT |
+| [`@fortune-sheet/core`](https://github.com/ruilisi/fortune-sheet) | MIT |
+| [`@fortune-sheet/react`](https://github.com/ruilisi/fortune-sheet) | MIT |
 | [`@joplin/turndown-plugin-gfm`](https://github.com/laurent22/joplin-turndown-plugin-gfm) | MIT |
 | [`@jridgewell/gen-mapping`](https://github.com/jridgewell/sourcemaps) | MIT |
+| [`@js-temporal/polyfill`](https://github.com/js-temporal/temporal-polyfill) | ISC |
 | [`@lexical/history`](https://github.com/facebook/lexical) | MIT |
 | [`@lexical/plain-text`](https://github.com/facebook/lexical) | MIT |
 | [`@lexical/text`](https://github.com/facebook/lexical) | MIT |
@@ -51,8 +55,9 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`@openai/codex`](https://github.com/openai/codex) | Apache-2.0 |
 | [`@opentelemetry/api`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@opentelemetry/api-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
-| [`@opentelemetry/exporter-logs-otlp-http`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/core`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@opentelemetry/otlp-exporter-base`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
+| [`@opentelemetry/otlp-transformer`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@opentelemetry/resources`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@opentelemetry/sdk-logs`](https://github.com/open-telemetry/opentelemetry-js) | Apache-2.0 |
 | [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | Apache-2.0 |
@@ -68,18 +73,25 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`@xterm/xterm`](https://github.com/xtermjs/xterm.js) | MIT |
 | [`@yarnpkg/parsers`](https://github.com/yarnpkg/berry) | BSD-2-Clause |
 | [`acorn`](https://github.com/acornjs/acorn) | MIT |
+| [`ajv`](https://github.com/ajv-validator/ajv) | MIT |
 | [`anser`](https://github.com/IonicaBizau/anser) | MIT |
+| [`big.js`](https://github.com/MikeMcl/big.js) | MIT |
 | [`buffer`](https://github.com/feross/buffer) | MIT |
 | [`chokidar`](https://github.com/paulmillr/chokidar) | MIT |
+| [`chrome-devtools-frontend`](https://github.com/ChromeDevTools/devtools-frontend) | BSD-3-Clause |
 | [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Apache-2.0 |
 | [`clsx`](https://github.com/lukeed/clsx) | MIT |
 | [`commander`](https://github.com/tj/commander.js) | MIT |
 | [`compression`](https://github.com/expressjs/compression) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`dompurify`](https://github.com/cure53/DOMPurify) | (MPL-2.0 OR Apache-2.0) |
 | [`electron-updater`](https://github.com/electron-userland/electron-builder) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
+| [`exceljs`](https://github.com/exceljs/exceljs) | MIT |
 | [`execa`](https://github.com/sindresorhus/execa) | MIT |
+| [`fast-xml-parser`](https://github.com/NaturalIntelligence/fast-xml-parser) | MIT |
 | [`fflate`](https://github.com/101arrowz/fflate) | MIT |
+| [`got`](https://github.com/sindresorhus/got) | MIT |
 | [`immer`](https://github.com/immerjs/immer) | MIT |
 | [`ipaddr.js`](https://github.com/whitequark/ipaddr.js) | MIT |
 | [`js-yaml`](https://github.com/nodeca/js-yaml) | MIT |
@@ -102,6 +114,7 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`node-addon-require-builtin`](https://www.npmjs.com/package/node-addon-require-builtin) | MIT |
 | [`node-pty`](https://github.com/microsoft/node-pty) | MIT |
 | [`open`](https://github.com/sindresorhus/open) | MIT |
+| [`papaparse`](https://github.com/mholt/PapaParse) | MIT |
 | [`pdfjs-dist`](https://github.com/mozilla/pdf.js) | Apache-2.0 |
 | [`picomatch`](https://github.com/micromatch/picomatch) | MIT |
 | [`react`](https://github.com/facebook/react) | MIT |
@@ -109,7 +122,9 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`readable-stream`](https://github.com/nodejs/readable-stream) | MIT |
 | [`resolve.exports`](https://github.com/lukeed/resolve.exports) | MIT |
 | [`semver`](https://github.com/npm/node-semver) | ISC |
+| [`serve-static`](https://github.com/expressjs/serve-static) | MIT |
 | [`sharp`](https://github.com/lovell/sharp) | Apache-2.0 |
+| [`sherpa-onnx-node`](https://github.com/csukuangfj/sherpa-onnx) | Apache-2.0 |
 | [`shiki`](https://github.com/shikijs/shiki) | MIT |
 | [`simple-icons`](https://github.com/simple-icons/simple-icons) | CC0-1.0 |
 | [`supports-color`](https://github.com/chalk/supports-color) | MIT |
@@ -119,16 +134,26 @@ External packages installed for runtime use or distributed inside the prebuilt b
 | [`undici`](https://github.com/nodejs/undici) | MIT |
 | [`use-sync-external-store`](https://github.com/facebook/react) | MIT |
 | [`ws`](https://github.com/websockets/ws) | MIT |
+| [`xlsx`](https://git.sheetjs.com/SheetJS/sheetjs) | Apache-2.0 |
 | [`yaml`](https://github.com/eemeli/yaml) | ISC |
 | [`zod`](https://github.com/colinhacks/zod) | MIT |
 | [`zustand`](https://github.com/pmndrs/zustand) | MIT |
 
 pnpm applies local patches to the following packages at install time, so shipped artifacts carry modified copies; each patch file is the complete record of the modification:
 
+- `@earendil-works/pi-ai@0.87.1` — [`patches/@earendil-works__pi-ai@0.87.1.patch`](patches/@earendil-works__pi-ai@0.87.1.patch)
 - `@electron/osx-sign@1.3.3` — [`patches/@electron__osx-sign@1.3.3.patch`](patches/@electron__osx-sign@1.3.3.patch)
+- `@fortune-sheet/core@1.0.4` — [`patches/@fortune-sheet__core@1.0.4.patch`](patches/@fortune-sheet__core@1.0.4.patch)
+- `@fortune-sheet/react@1.0.4` — [`patches/@fortune-sheet__react@1.0.4.patch`](patches/@fortune-sheet__react@1.0.4.patch)
 - `@yao-pkg/pkg@6.21.0` — [`patches/@yao-pkg__pkg@6.21.0.patch`](patches/@yao-pkg__pkg@6.21.0.patch)
+- `exceljs@4.4.0` — [`patches/exceljs@4.4.0.patch`](patches/exceljs@4.4.0.patch)
 - `node-pty@1.2.0-beta.15` — [`patches/node-pty@1.2.0-beta.15.patch`](patches/node-pty@1.2.0-beta.15.patch)
 
+## Chrome DevTools frontend
+
+The optional experimental Inspector distributes a locally compiled copy of [chrome-devtools-frontend 1.0.1638082](https://www.npmjs.com/package/chrome-devtools-frontend/v/1.0.1638082), from upstream revision [0e1186138ed519d9659c1874bf6375eca4483c72](https://chromium.googlesource.com/devtools/devtools-frontend/+/0e1186138ed519d9659c1874bf6375eca4483c72). The build includes the Chromium [BSD-3-Clause license](packages/experimental/inspector/assets/devtools/LICENSE) and the third-party license and notice files supplied by the npm source. The Chromium root license does not replace those dependencies' licenses.
+
+
 ## Official Claude Code platform payloads
 
 The project owner authorizes distribution of every version of the official `@anthropic-ai/claude-agent-sdk` package and the official Claude Code CLI/platform payloads that each version declares through `optionalDependencies`. This identity-scoped authorization does not classify their declared terms as permissive and does not cover any unrelated runtime package; version, declared-license, and payload-set changes still require the ordinary dependency, lockfile, compatibility, terms, and notices review.
@@ -151,7 +176,7 @@ The installed SDK 0.3.263 declares the following optional platform packages. Eac
 
 `@deepseek-ai/libreoffice-kit`, `@deepseek-ai/libreoffice-kit-wasm`, `@deepseek-ai/libreoffice-kit-darwin-arm64`, `@deepseek-ai/libreoffice-kit-darwin-x64`, `@deepseek-ai/libreoffice-kit-win32-arm64`, `@deepseek-ai/libreoffice-kit-win32-x64` declare MPL-2.0, which remains outside the permissive-license allowlist; the notices check accepts only these package identities at those terms. The [distribution decision](.agents/notes/implemented/architecture/2026-09-14-independent-libreoffice-kit.md) records the source obligations.
 
-The [kit repository](https://github.com/deepseek-harness/libreoffice-kit) supplies the corresponding LibreOffice source pin, modifications, build instructions, Node API, and artifact validation. Its engine packages retain their license and third-party notices; the Node API retains its MPL-2.0 declaration and NOTICE. Recipients must have access to those corresponding sources and notices.
+The [kit repository](https://github.com/deepseek-ai/dsh-libreoffice-kit) supplies the corresponding LibreOffice source pin, modifications, build instructions, Node API, and artifact validation. Its engine packages retain their license and third-party notices; the Node API retains its MPL-2.0 declaration and NOTICE. Recipients must have access to those corresponding sources and notices.
 
 
 ## Development-only npm dependencies
@@ -173,6 +198,7 @@ External packages **directly declared** for development, tests, types, or toolin
 | [`@testing-library/dom`](https://github.com/testing-library/dom-testing-library) | MIT |
 | [`@testing-library/react`](https://github.com/testing-library/react-testing-library) | MIT |
 | [`@types/babel__code-frame`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/big.js`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/compression`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/js-yaml`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/jsdom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
@@ -180,11 +206,13 @@ External packages **directly declared** for development, tests, types, or toolin
 | [`@types/mime-types`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/negotiator`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/node`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/papaparse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/picomatch`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/readable-stream`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/semver`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/serve-static`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/spdx-expression-parse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/use-sync-external-store`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
@@ -244,9 +272,9 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
 | [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only |
 | [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |
 
-## Desktop bundled Python distributions
+## Bundled Python distributions
 
-The [Desktop runtime lock](apps/desktop/scripts/primary-runtime-lock.json) records each distribution version and the wheel download hashes. The table includes every entry in `pythonPackages`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
+The [shared runtime lock](scripts/primary-runtime/lock.json) records each distribution version and the wheel download hashes. The table includes every entry in `pythonPackages`, including transitive dependencies. Wheel extraction preserves distribution metadata and the license and notice files supplied by each archive. Project licenses below do not enumerate the separate licenses of native libraries bundled inside wheels.
 
 | Distribution | Locked version | Project license |
 | --- | --- | --- |

package/references/official-docs/docs/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
 
@@ -40,10 +40,10 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb
 - **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
 
@@ -55,7 +55,7 @@ When the gate goes red:
 2. **Condense** content that belongs here but can be shorter.
 3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
 
-Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,960; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
 
 ## The slop checklist
 

package/references/official-docs/docs/agent-lifecycle.i18n.yaml

@@ -1,6 +1,10 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for agent-lifecycle.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/agent-lifecycle.md
-agent-lifecycle.md: 6ffe3c2b47e766ac985b3192a1c08787821fc46e
-agent-lifecycle.zh.md: c4b2fa70dbdb0487c3871b6e65227eac8b062e24
+/:
+  en: 41d772192075e133
+  zh: 305a6826a598b96d
+/agent-turn-and-step-lifecycle:
+  en: a1389c8ed7e37324
+  zh: c2944b9192af4ec9

package/references/official-docs/docs/api-gateway.i18n.yaml

@@ -1,6 +1,28 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
+# Bilingual-pair consistency record for api-gateway.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/api-gateway.md
-api-gateway.md: 2cf7b2f345991fd20639e1294662cc64fc02093d
-api-gateway.zh.md: 5b80db08de49591b27751e187aa6278384a7444e
+/api-gateway:
+  en: 735eb4f22d5f6f71
+  zh: 1ca2759961efdc06
+/api-gateway/programming-model:
+  en: ea12b64211f0d377
+  zh: 032e5c0d799c7529
+/api-gateway/component-responsibilities:
+  en: e29f1d7026291075
+  zh: 15e361e797d44fce
+/api-gateway/strict-generation-pipeline:
+  en: cb8da81a92acfa52
+  zh: be5f3c268f8571df
+/api-gateway/runtime-invocation:
+  en: 2a2fed340aaa926c
+  zh: 46bb1f500c870a76
+/api-gateway/src-development-fallback:
+  en: 9570ffe7a348e5ac
+  zh: 2b70b61b1ff1fbb0
+/api-gateway/development-mode:
+  en: ba090d76471dd663
+  zh: fcddcb232de98248
+/api-gateway/boundaries:
+  en: e6befc5f8c90f97b
+  zh: 3ade08102542a894