dsh-plugin-guide 0.3.42 → 0.4.0

package/guide/release-engineering.zh-CN.md

@@ -1,198 +0,0 @@
-# DSH 插件组合的发布工程
-
-> English: [release-engineering.md](release-engineering.md)
-
-官方文档教的是**一个**插件怎么写。它没有讲**几十个**插件怎么在一个"设计上就会破坏兼容"的宿主上持续可安装、可发布、可升级。本章补的就是这一段，素材来自一个真实在跑的插件组合：38 个 bundle 插件、39 个 npm 包、500+ 已发布版本。
-
----
-
-## 0. 你实际在维护的是四份契约
-
-插件不是"一个 TypeScript 包"，而是四份契约；组合出问题，一定是其中一份先漂移了：
-
-| 契约 | 位置 | 断裂方式 |
-|---|---|---|
-| Bundle 清单 | `package.json` -> `dsh.bundle.patch` | patch 文件改名，或该键被删掉 |
-| 安装面 | npm 包名 + `dist-tags` | 发布落到错误的 tag，或根本没发出去 |
-| 兼容窗口 | `@deepseek-ai/*` 的 `peerDependencies` | 宿主换了 alpha/rc 线，范围不再接受它 |
-| 可发现性 | GitHub topic `dsh-plugin` + 包 `keywords` | 仓库改名，或 fork 出来时没带 topic |
-
-下面全部围绕"如何低成本地让这四份契约在组合规模上保持一致"。
-
----
-
-## 1. 能扩展的布局与命名
-
-从 5 个插件走到 50 个，只差两个习惯：
-
-1. **一个插件一个仓库**，各自独立发布。monorepo 会让一个失败的门禁卡住所有插件的发布。
-2. **可预测的命名**：包名 `dsh-<能力>`，仓库同名。scoped 名（`@you/dsh-x`）也可以，但仓库名要保持稳定——发现机制靠 GitHub topic，改名会让你无声地掉出搜索结果。
-
-每个仓库保留一份 `AGENTS.md` 写清该仓自己的规则。组合变大后，仓库内文件是该仓的权威，跨仓约定则集中在一份共享文档里（就是本文）。
-
----
-
-## 2. 版本线矩阵
-
-开发者预览期，宿主会同时存在多条线，例如 `0.1.2-rc.1`、`0.1.5-alpha.1`、`0.1.5-rc.1`、`0.1.6-alpha.2`、`0.1.7-alpha.2`。只钉一条线的组合，在用户从另一条线安装的那一刻就坏。
-
-同时接受全部窗口的写法（每个预发布 tuple 一条子句；每个 `-0` 下界覆盖该 tuple 的全部预发布，绝不写成裸 `>=0.1.7` 形态）：
-
-```jsonc
-{
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0 || >=0.2.0-0 <0.3.0 || >=0.2.1-0 <0.3.0"
-  },
-  "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2"
-  }
-}
-```
-
-⚠️ **不要写开区间 `>=0.1.2-rc.1 <0.3.0`。** 它看起来是最宽的"安全"范围，实际正相反：它横跨整整一代破坏性变更，门禁会放行 `0.2.x` 宿主，而你的插件还在调 `0.1.x` 的 API——**安装期放行、运行期炸**。**上界必须按世代切**（`<0.2.0` / `<0.3.0`）；上面这个六子句形态就是 `dsh-plugin-kit` 的 `data/peer-range.json`（`canonicalRange`，2026-09-26 更新）记录的规范区间，`dsh-plugin-doctor` 的 R8 会标记开区间写法。
-
-范围的宽度只等于它最新那条子句，而 semver 在这里很容易让人写错、且**看起来是对的**：**一个范围只有在某条比较符带着同一个 `[major, minor, patch]` tuple 且带预发布时，才接纳该预发布版本。** 所以一条止于 `>=0.1.6-0 <0.2.0` 的带子接纳 `0.1.6-alpha.2`，却**不**接纳 `0.1.7-alpha.2`——读起来像"0.2 之前全都要"，行为上却是"0.1.6 tuple 之后一概不要"。补上该线自己的子句就是全部修法；用 `semver.satisfies('0.1.7-alpha.2', range)` 去验，**不要用眼睛看**。
-
-由此得到的规则：
-
-- **`devDependencies` 钉最新已发布的线。** 类型检查要赶在你的用户之前报错。
-- **`dependencies` 钉 stable/rc 线，`peerDependencies` 接受两个窗口。** 永远不要为了让自己的 CI 变绿而收窄 peer 范围——那等于把另一条线上的用户静默卸载掉。
-- **绝不用手改 30 个仓库的钉号。** 脚本化的一波（patch bump、更新钉号、过门禁、发布）是唯一可持续的路径；把它当成一个原子批次执行，并为每个仓留回滚注记。
-
----
-
-## 3. 发布流水线
-
-每个仓的发布 = 推一个 tag，触发 workflow：
-
-```yaml
-on:
-  push:
-    tags: ['v*']
-jobs:
-  publish:
-    steps:
-      - run: pnpm install --frozen-lockfile
-      - run: pnpm run build
-      - run: npm publish --provenance --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-五个用时间换来的经验：
-
-1. **`--frozen-lockfile` 是一道门禁，而且它是对的。** 发布提交漏了 `pnpm-lock.yaml`，就会死在这里。绝不要在锁文件不干净的状态下发布。
-2. **用 `--provenance` 发布。** 一个参数换来签名的供应链凭证，这是你能给审查者的最便宜的信任信号。
-3. **secret 是按仓存的。** 每个会发布的仓都必须有 `NPM_TOKEN`。令牌轮换时要全量重播种，否则故障会晚很多、一个一个仓地冒出来。
-4. **已推送的 tag 不能重发。** 产物错了就：修提交、强制移动 tag、重跑，并接受第一次尝试已成为公开历史。
-5. **要知道 registry 的复制延迟。** 发布后立刻跑的校验任务，可能仍解析到上一个版本（"The latest release is X"）。等 `latest` 稳定后重跑，而不是去"修"一个本来没坏的包。
-
----
-
-## 4. 一个版本，三个面
-
-发布一次，镜像到位，并让镜像幂等：
-
-| 面 | 机制 | 要盯的失败模式 |
-|---|---|---|
-| npm | tag 触发 workflow | dist-tag 落错线 |
-| GitHub Release | 同一个 tag 触发的 workflow（幂等） | release notes 与 CHANGELOG 漂移 |
-| Gitee（镜像） | 定时同步 workflow | 强制移动 tag 后镜像 HEAD 落后于上游 |
-
-三面都验过，才算发布完成。只上了 npm 而镜像没有，是半个发布——镜像上的用户会来报一个你早已修好的 bug。
-
-GitHub Release 由**发布 npm 的同一个 tag workflow** 创建，**绝不手工建**。手工建正是 release notes 与 `CHANGELOG.md` 漂移的来源，而且这个缺口在 registry 侧看不见：一个上了 npm 却没有 Release 页的版本，对 `npm view` 看起来是完整的，对任何读仓库的人却是不完整的。这一步必须幂等，这样重跑、补 tag、或 Release 页已存在都不会让 job 失败：
-
-```sh
-if gh release view "$TAG" >/dev/null 2>&1; then
-  echo "release $TAG already exists; skipping"
-  exit 0
-fi
-node scripts/changelog-section.mjs "$VERSION" > release-notes.md || true
-if [ -s release-notes.md ]; then
-  gh release create "$TAG" --title "$TAG" --notes-file release-notes.md
-else
-  gh release create "$TAG" --generate-notes
-fi
-```
-
-三个细节是关键。该 job 需要 `permissions: contents: write`（publish job 的 `contents: read` 不够，且 job 级权限会覆盖 workflow 级）。它应当是**一个 `needs:` 发布 job 的独立 job**，这样一个 `CHANGELOG.md` 缺少该小节的 tag 就不会把已经成功的 npm 发布变成红灯。而 `|| true` 加 `-s` 判断，正是让「缺小节」这一情形退化为生成式 notes 而不是失败的原因——有生成式 notes 的 Release 页，胜过没有 Release 页。
-
----
-
-## 5. README 一致性属于构建的一部分
-
-如果组合提供多语言 README，就把它们当构建产物：
-
-- 语言集合是固定的、且被检查。只给一种语言加章节而其他语言不加，必须让 CI 失败。
-- tag 之前先跑编码门禁：UTF-8 无 BOM、无乱码、无替换字符。已发布的 README 修不回来——npm 元数据不可变，registry 甚至可能不展示你修正后的文件。
-- 写锚点正则时注意：CJK 字符之后的词边界行为与英文不同。
-
----
-
-## 6. 宿主破坏兼容时的迁移波
-
-宿主明确写了会破坏兼容。所以要按"波"来做计划，而不是指望稳定：
-
-1. **探测。** 在用户撞上之前，先对最新已发布的线跑类型检查矩阵。某个事件类型被移除、或签名变了，会在某一个仓里先炸成编译错误——这个错误就告诉你全部仓的影响面。
-2. **分诊。** 把"钉号更新""机械改写""语义重设计"分开。只有前两类属于一波；第三类单独发布、单独写 changelog。
-3. **原子执行。** 一批 patch bump、一次门禁、一波发布，并为每个仓留回滚注记（上一个 tag + 要还原的确切钉号）。
-4. **记录事故。** 两个值得写下来的例子，都是自伤，都各吃掉一个发布周期：
-   - 发布提交漏了锁文件导致 CI 红；修法是补提交 + 强制移动 tag。
-   - 用另一个包管理器生成的锁文件里含 workspace link 条目，干净环境无法复现；修法是删掉锁文件、隔离重装、重新生成。
-
-**经验值**：一波超过约四个仓，CI 队列就会饱和、各 run 结算乱序。按此分批。
-
----
-
-## 7. 打 tag 前的门禁清单
-
-每次推 tag 之前：
-
-- [ ] `pnpm install --frozen-lockfile` 干净
-- [ ] 对**最新已发布的线**做类型检查，而不是你开发时用的那条
-- [ ] 单元测试全绿
-- [ ] 包不变量：`files` 白名单确实包含构建产物，且该产物存在
-- [ ] 多语 README 一致 + 编码审计（无 BOM、无乱码、无替换字符）
-- [ ] `CHANGELOG.md` 有即将打的这个版本的小节
-- [ ] tag workflow 自己创建 GitHub Release，且幂等，正文取自该版本小节（见第 4 节）
-- [ ] 版本号与意图一致（patch = 波，minor = 功能，major = 破坏性）
-- [ ] 远端还没有这个 tag
-
-推 tag 之后：
-
-- [ ] npm `dist-tags.latest` 等于新版本
-- [ ] GitHub Release 已建且带 notes
-- [ ] 镜像已同步
-- [ ] 所有 vendor 钉住该包的消费仓已在同一批里升级
-
----
-
-## 8. 那些看起来像你的 bug、其实不是的 registry 行为
-
-写下来一次，省得有人调两遍：
-
-- **`versions[].readme` 可能为空**——即使 tarball 里的 README 与你的仓库逐字节一致，包页也会展示旧 README。这是 registry 侧的呈现行为，CLI 与 CI 两条通道都能复现，不要靠"重发一次"去修。
-- **`description` 在包元数据里约 255 字符处被截断。** 校验发布时按截断形式比对，而不是全文。
-- **scoped 包**在某些下载量端点上会返回占位值。用 range 端点，别用 point 端点。
-- **发布成功不等于可见。** 见第 3 节第 5 条。
-
----
-
-## 9. 会伪造结论的本地工具
-
-下面每一条都返回一个自信的错误答案，而不是报错；每一条都真实吃掉过一个排查周期。写下来，好让下一个人认得出这个形状：
-
-- **`npm view <pkg>@<ver> A B --json` 会凭空造出「缺失」。** 一次问两个字段时，它可能把一个实际存在的字段报成空值，读起来就像「已发布的包丢了 `peerDependencies`」。每次只查一个字段；当真要下结论时，解开已发布的 tarball 读它的 `package.json`——那才是地面真相。曾有一次审计据此标出八个仓，八个全错。
-- **遵守 `.gitignore` 的内容检索会返回假阴性。** 当工作区根目录忽略一切（`*` 加一条例外）时，在它上面做检索会一无所获，而「一无所获」会被读成「不存在」的证据。在断言某个模式不存在之前，先用一个不查忽略规则的扫描确认一遍。
-- **Windows PowerShell 5.1 的 `Set-Content -Encoding utf8` 会写 BOM。** 以 `EF BB BF` 开头的 JSON 请求体会解析失败，而报错指向的是载荷内容而不是编码。机器要读的文件一律走显式编码器：`[System.IO.File]::WriteAllText($path, $text, (New-Object System.Text.UTF8Encoding($false)))`。
-- **在 Windows 上，`rd /s /q` 删不掉含保留设备名的目录树**（`NUL`、`CON`、`AUX`、`PRN`、`COM1`-`COM9`、`LPT1`-`LPT9`）。它会报成功，却把整条祖先链原样留下。用 `\\?\` 前缀的长路径删除该条目，然后断言目录确实消失——退出码为 0 不能作为「树已消失」的证据。
-
----
-
-## 10. 这样做换来什么
-
-按这套方式维护的组合，表现得像一个产品：任何宿主线上的用户都能装到任何插件，每个版本都有凭证，镜像一致，上游的破坏性变更只花掉一波而不是一次事故。这同时也是最强的生态贡献形式——官方要的正是这个，并且明确否认"官方仓的包比社区的包更重要"。
-
-欢迎指出错误或补充；常用入口见 [links.md](links.md)。

package/guide/standards.md

@@ -1,141 +0,0 @@
-# DSH plugin adoption levels: ENTRY, FLOW, BOOST
-
-> **Status: community draft, non-official.** This chapter explains the three-level model maintained in the `dsh-standards` project (public since 2026-11-01). It is teaching material, not a certificate, ranking, security audit, or official DeepSeek position. If your copy of the canonical clause text or `spec/levels.json` disagrees with this summary, the canonical files win. Chinese version: [standards.zh-CN.md](standards.zh-CN.md).
-
-## Three levels, three different questions
-
-In the DSH plugin ecosystem, "qualified" is at least three questions, and they are not three marks on one ruler. **DSH-ENTRY** asks whether an existing plugin can be recognized, installed, and booted on a target DSH line with little or no code change — the compatibility baseline ("装完能跑"). **DSH-FLOW** asks whether a user can then install, configure, use, recover, upgrade, and uninstall it without surprises — the recommended adoption experience ("用起来顺"). **DSH-BOOST** asks whether the plugin uses Cordis primitives (effects, inject, volatile, events, seams, jobs, bounded parallelism) to make development and use measurably cheaper — guiding practice recorded as evidence cards, not a badge ("用 Cordis 做得更省").
-
-A plugin can be `ENTRY=runtime` and `FLOW=not-run`; a `BOOST`-measured plugin can still fail `ENTRY`. That is why the three levels are judged, cited, and expired **separately**. Never collapse them into one score, never use `BOOST` to infer `ENTRY`, and never call the result a "level" without naming its evidence state.
-
-## The GB analogy (analogy only, not a standard)
-
-> **Analogy only — non-official.** The GB / GB∕T / GB∕Z columns borrow the *intuition* of a baseline / recommended / guidance layering. This project has no standards-issuing body, no standard number, no accreditation, no legal effect, and no DeepSeek endorsement. `DSH` is an abbreviation; DeepSeek Harness is a DeepSeek trademark. Do not describe a plugin as "GB compliant", "nationally certified", "officially certified", or "ranked" on the basis of this model.
-
-| Dimension | GB (analogy) | GB∕T (analogy) | GB∕Z (analogy) |
-|---|---|---|---|
-| What it stands for | mandatory national standard | recommended national standard | guiding technical document |
-| This project | **DSH-ENTRY** | **DSH-FLOW** | **DSH-BOOST** |
-| Question | can it be installed and run? | is it smooth after install? | is Cordis used efficiently? |
-| Adoption | self-adopted; must pass if you claim it | recommended; not adopting is not "nonconforming" | guidance; register practices and evidence |
-| If it fails | cannot claim compatibility | not recommended for broad adoption | cannot claim a speed-up |
-| Evidence | G0–G5 + static/runtime state | J1–J8 + journey records | LEV-1–8 + evidence cards |
-| Force in this project | none; only self-consistency when cited | none | none |
-
-## Two axes: adoption depth and evidence state
-
-Depth and evidence are independent coordinates. `ENTRY` is not "bronze", `FLOW` is not "silver", and `BOOST` is not "gold": the depth says **what was judged**, the evidence state says **how strongly**. Always write both, for example `ENTRY=runtime, FLOW=manual(J1–J8), BOOST=not-measured`.
-
-| Depth ↓ / evidence → | `not-run` | `recognized` / `static` | `runtime` | `manual` | `measured` | `blocked` / `failed` |
-|---|---|---|---|---|---|---|
-| **DSH-ENTRY** | untested; no claim | manifest, entry, patch recognized; no boot | real boot; target rows ACTIVE or disabled | — (not a substitute for boot) | — | host/fixture blocked, or plugin-attributable failure |
-| **DSH-FLOW** | journey not run; no claim | static prep only (manifest, README); not a journey | automated journey passed on a recorded host | a person ran the journey and recorded steps/logs | — (use runtime/manual per journey) | environment blocked, or journey failure |
-| **DSH-BOOST** | not measured; no claim | pattern present in code; not evidence of benefit | — (execution alone is not a measurement) | — | evidence card reproduces on the recorded anchor | benchmark blocked, or claimed gain contradicted |
-
-Cells marked "—" are category errors, not passes. The evidence words mean:
-
-| State | What it supports | What it never means |
-|---|---|---|
-| `not-run` / `not-measured` | "this was not tested" | a pass, or "should work" |
-| `recognized` / `static` | structural recognition: manifest, entry, patch, client export | a running process or a rendered UI |
-| `runtime` | a real boot or real execution on a recorded host version/commit | UI correctness, production readiness, security |
-| `manual` | a human walked the journey with steps and logs recorded | automation, or a claim that covers other platforms |
-| `measured` | a reproducible evidence card with environment, input, command, control, result | a production benchmark or a billing claim |
-| `blocked` | the host or fixture prevented judgment | a plugin failure, or a pass |
-| `failed` | a reproducible failure attributable to the plugin | "environment issue" without evidence |
-| `stale` | past its expiry window | current evidence; quote it only as stale |
-
-Three misreadings this table exists to stop:
-
-- **`runtime` is not UI-rendered.** A booted server-side row, or a client module that loaded, does not prove the slot renders correctly. `client-module-loaded` ≠ `UI-rendered`; render correctness needs its own observation (slot output, console errors, a screenshot).
-- **`static` is not `runtime`.** Parsing and recognition say the artifact is structurally plausible. They do not say a process booted it, or that a dependency resolved at boot.
-- **`not-measured` is not a pass.** Absence of evidence is a third state with its own label. Write "not tested", not "passes" or "should work".
-
-## DSH-ENTRY: compatibility baseline
-
-**What it answers.** Can an existing plugin be recognized, installed, and booted on the target DSH line without changing its code?
-
-**Required evidence.** Four static gates plus one runtime gate and one process gate:
-
-| Gate | Check | Owner |
-|---|---|---|
-| G0 | `dsh.bundle.patch` parses | plugin |
-| G1 | base + sample compose; inserted row names resolve | plugin |
-| G2 | `evaluatePluginCompatibility` admits, or an explicit exact-version exemption applies | host |
-| G3 | real `boot()` leaves every target row `ACTIVE` or `disabled` | plugin/host/fixture |
-| G4 | when `dsh.client` exists: `exports["./client"]` and a package-root row (static) | plugin |
-| G5 | report carries host version/commit and artifact mtime; expired evidence is `stale` | process |
-
-G0–G2 and G4 pass in static inspection, which supports `recognized`; `runtime` requires G3 on a recorded host. `blocked` and `failed` are different outcomes and must be reported with their cause.
-
-**What it does not claim.** Security, UI correctness, production readiness, full feature correctness, official endorsement, or that the plugin will work on an untested DSH line.
-
-**How to self-check.** Record `dsh --version`, the host commit, and the artifact mtime. Run `dsh-plugin-dev check --json` for the 16 local static checks (a subset of `dsh-plugin-doctor`'s 33 — see [family-toolchain.md](family-toolchain.md)), then the standards repo's entry checker (commands below). For bundles, also run `dsh --profile <name> --dump-config` and look for `patch: entry <id> not found`, then boot and read the row states. Write the claim as `DSH-ENTRY: runtime (dsh 0.2.1-rc.2, commit <sha>, 2026-11-01)`.
-
-## DSH-FLOW: adoption experience
-
-**What it answers.** Once installed, can a user install it, configure it, use it, recover from errors, upgrade, and uninstall it without surprises?
-
-**Required evidence.** The eight user journeys J1–J8: install/remove; enable/disable; configuration and validation; first success (quickstart and error triad); permissions and disclosure; upgrade/rollback/uninstall; observability and diagnostics; and client/server shapes (headless, web, client-off). Each journey records the command, environment, result, log path, and time. A manual journey is valid evidence when it says `manual`; a journey that was not run is `not-run`, not a pass.
-
-**What it does not claim.** Certification, ranking, security review, every UI layout, every platform, or that a journey tested on one host generalizes to another.
-
-**How to self-check.** Use a throwaway `DSH_HOME`: `add` → `--dump-config` shows the layer → `remove` → the layer and dependencies are gone. Boot with `{}` and with an invalid value (it must fail loudly with a field path). Follow the README as a new user with a five-minute timer; check the error triad (cause, next command, doc anchor). Test upgrade then rollback, and for client plugins test headless, web, and client-off. Start from [plugin-dev-guide.md](plugin-dev-guide.md) §7 and the release checklist in [release-engineering.md](release-engineering.md).
-
-## DSH-BOOST: guiding practice
-
-**What it answers.** Does the plugin use Cordis primitives to make development and use measurably cheaper, and is the claimed saving reproducible?
-
-**Required evidence.** LEV-1–8: effects are reversible and return to baseline; required services are injected and polling is absent; hot config uses `volatile()` without remounting; event modes match and waterfall observers call `next()`; seams/isolate/group are used only when needed; tool and prompt prefixes stay byte-stable with volatile data in `systemPrompt.context`; long work uses jobs and bounded parallelism with cancellation; and bundle/preset composition is expressed in patches, with an evidence card per practice. Each card records environment, input scale, command, a **negative control**, result, version anchor, and limitations.
-
-**What it does not claim.** A production benchmark, a billing or cache-hit rate, a total score, a ranking, or that one fixture generalizes to another workload. LEV-6 prefix stability is the one practice directly priced in tokens; the others still need a card.
-
-**How to self-check.** Pick one LEV and write the card before optimizing the next. Run the negative control (for example, a normal config field that *does* remount, or a volatile nonce that *does* break the prefix). Record `dsh`, `cordis`, Node, and the commit; a number without an anchor is not evidence. Link the code path to [plugin-dev-guide.md](plugin-dev-guide.md) §3.3 (effects), §3.6 (config), §4.3 (jobs), and §5 (seams).
-
-## How to move up
-
-**ENTRY → FLOW.** First get a real `runtime` claim: boot the bundle and record the host version/commit. Then make the first five minutes work: a quickstart, a working `add`/`remove` in a temporary `DSH_HOME`, empty-config boot, loud invalid-config errors with a field path, and an error triad in every failure message. Test one upgrade and one rollback, and check that uninstall leaves no layer or dependency behind. For client plugins, test headless, web, and client-off before claiming a UI. Relevant chapters: [plugin-dev-guide.md](plugin-dev-guide.md) §7 (packaging, install, and pitfalls), [release-engineering.md](release-engineering.md) §7 (pre-tag gate), and [quick-reference.md](quick-reference.md).
-
-**FLOW → BOOST.** Move timers, listeners, connections, watchers, and subprocesses into `ctx.effect()` with labels, then measure that reloads return to baseline. Declare required services in `inject`, use `ctx.get()` only for optional ones, and remove polling. Make adjustable fields `volatile()` and measure zero remounts on change. Keep tool and prompt prefixes stable; put volatile data in `systemPrompt.context`. Move long work to `ctx.jobs` and bound parallel calls, then verify cancellation. Start with LEV-6 and LEV-3 — the draft already carries measured examples for both, and each has a clean negative control. Relevant chapters: [plugin-dev-guide.md](plugin-dev-guide.md) §3.3, §3.6, §4.3, §4.8; [references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md); and the official extension cookbook in [references/official-docs/docs/cookbook/extension-cookbook.md](../references/official-docs/docs/cookbook/extension-cookbook.md).
-
-**Do not move up for its own sake.** A frozen or retiring plugin should not buy a `BOOST` card; check [when-to-retire-a-plugin.md](when-to-retire-a-plugin.md) first. A plugin whose capability is better served by another implementation should be retired, not polished.
-
-## Certification grades are orthogonal
-
-Certification grades A–D describe quality and evidence depth; ENTRY/FLOW/BOOST describe adoption depth. They are orthogonal: `A` is not "ENTRY level", `D` is not "BOOST failed". A certified plugin can still be `ENTRY=blocked`, and a `BOOST=measured` plugin can still have a supply-chain problem. State each scope separately; never compute a total from grade plus level.
-
-## Canonical source and checker commands
-
-- Canonical repository (public): https://github.com/PerryLink/dsh-standards — clauses `31` (ENTRY), `32` (FLOW), `33` (BOOST), `34` (the GB analogy), and `spec/levels.json`.
-- Audit tool in that repository: `40-checker/scripts/level-audit.mjs`. It is not bundled with this guide; if your checkout does not have it, use `spec/levels.json` for definitions and the entry checker below.
-- Existing entry checker: `40-checker/bin/dsh-plugin-verify.mjs`.
-
-```sh
-git clone https://github.com/PerryLink/dsh-standards
-cd dsh-standards
-# entry, static only (does not claim runtime)
-node 40-checker/bin/dsh-plugin-verify.mjs <plugin-dir> --scope entry --entry-claim static
-# audit (run only if the file exists in your checkout)
-node 40-checker/scripts/level-audit.mjs <plugin-dir>
-```
-
-Scaffolded plugins (`dsh-plugin-dev new`) ship `dsh.standards` as a placeholder — `entry`/`flow` = `not-run`, `boost` = `not-measured`, every `evidence` = `null`. Replace it only with the audit's recorded output; without evidence it stays `not-run`, and no level is read as a pass.
-
-`dsh-plugin-dev check` is a static assistance tool, not a level audit; `dsh-plugin-doctor` maps its R/K/D/X results to an ENTRY status and does not cover FLOW or BOOST. Neither tool can issue a level by itself.
-
-## For reviewers: a short checklist
-
-- [ ] The claim names **both** a level and an evidence state, not just "compatible".
-- [ ] Evidence carries the DSH version, host commit, Cordis version, date, and scope.
-- [ ] `runtime` was observed, not inferred from `static`; static is labelled `recognized`.
-- [ ] No `not-run`, `not-measured`, or `blocked` was rewritten as a pass.
-- [ ] UI claims have a render observation; `client-module-loaded` is not called rendered.
-- [ ] FLOW claims list which journeys ran, who ran them, the command, result, and log path.
-- [ ] BOOST claims have a card with a negative control and a limitation, and no production percentage is inferred from one fixture.
-- [ ] Grades A–D are stated separately and are not used as a level.
-- [ ] No "official", "certified", "national standard", "GB compliant", or "ranked" wording.
-- [ ] Evidence is inside its expiry window; expired evidence is labelled `stale`.
-
----
-
-*Canonical model: the public `dsh-standards` project. This chapter is non-official and grants no certification. Corrections should go to the canonical repo first, then be mirrored here.*

package/guide/standards.zh-CN.md

@@ -1,141 +0,0 @@
-# DSH 插件三层采用标准：ENTRY、FLOW、BOOST
-
-> **状态：社区草案，非官方。** 本章解释 `dsh-standards` 项目（2026-11-01 起公开）维护的三层模型。它是教学材料，不是认证、排名、安全审计，也不代表 DeepSeek 官方立场。如果你手上的条款原文或 `spec/levels.json` 与本摘要冲突，以原文和该文件为准。英文版：[standards.md](standards.md)。
-
-## 三层，三个不同的问题
-
-在 DSH 插件生态里，"合格"至少是三个问题，而不是同一把尺子上的三个刻度。**DSH-ENTRY** 问：现有插件几乎不改，能不能在目标 DSH 线上被识别、安装并跑起来——这是兼容底线（"装完能跑"）。**DSH-FLOW** 问：装好之后，用户能不能装得上、配得动、用得顺、出错能恢复、能升级、能卸干净——这是推荐采用体验（"用起来顺"）。**DSH-BOOST** 问：插件有没有用 Cordis 原生能力（effect、inject、volatile、事件、seam、jobs、有界并行）把开发和使用做得可测量地更省——这是指导性实践，以证据卡登记，不是徽章（"用 Cordis 做得更省"）。
-
-一个插件可以 `ENTRY=runtime`、`FLOW=not-run`；一个 `BOOST` 已 measured 的插件仍可能 `ENTRY` 失败。所以三层必须**分开判定、分开引用、分开过期**。不要把三层折成一个分数，不要用 `BOOST` 反推 `ENTRY`，也不要在不写证据状态的情况下只说"它是某一级"。
-
-## GB 类比（仅为类比，不是标准）
-
-> **仅为类比——非官方。** GB / GB∕T / GB∕Z 三列只借用"基线 / 推荐 / 指导"的**分层直觉**。本项目没有标准化主管机构、没有标准号、没有认可资质、没有法律效力，也没有 DeepSeek 背书。`DSH` 是缩写；DeepSeek Harness 是 DeepSeek 的商标。不要据此把插件写成"符合 GB""国家认证""官方认证"或"排名第几"。
-
-| 维度 | GB（类比） | GB∕T（类比） | GB∕Z（类比） |
-|---|---|---|---|
-| 在类比中代表 | 强制性国家标准 | 推荐性国家标准 | 国家标准化指导性技术文件 |
-| 本项目 | **DSH-ENTRY** | **DSH-FLOW** | **DSH-BOOST** |
-| 回答 | 能不能装、能不能跑 | 装完之后顺不顺 | Cordis 有没有被用出效率 |
-| 采用方式 | 自选采用；声称通过就必须过 | 推荐采用；不采用不构成"不合格" | 指导性；只登记做法与证据 |
-| 失败的说法 | 不能声称兼容 | 不推荐大规模采用 | 不能声称增效 |
-| 证据 | G0–G5 + 静态/运行时状态 | J1–J8 + 旅程记录 | LEV-1–8 + 证据卡 |
-| 本项目强制力 | 无；只有引用时的自洽要求 | 无 | 无 |
-
-## 两轴：采用深度 × 证据状态
-
-深度与证据是两个独立坐标。`ENTRY` 不是"铜牌"，`FLOW` 不是"银牌"，`BOOST` 不是"金牌"：深度说明**判了什么**，证据状态说明**判得有多硬**。两者必须一起写，例如 `ENTRY=runtime, FLOW=manual(J1–J8), BOOST=not-measured`。
-
-| 深度 ↓ / 证据 → | `not-run` | `recognized` / `static` | `runtime` | `manual` | `measured` | `blocked` / `failed` |
-|---|---|---|---|---|---|---|
-| **DSH-ENTRY** | 未测；无声明 | 识别到清单/入口/patch；未 boot | 真实 boot；目标行 ACTIVE 或 disabled | —（不能替代 boot） | — | 宿主/夹具 blocked，或可归因于插件的失败 |
-| **DSH-FLOW** | 旅程未跑；无声明 | 仅静态准备（清单、README）；不算旅程 | 在记录的宿主上自动旅程通过 | 真人走完旅程并记录步骤/日志 | —（按旅程用 runtime/manual） | 环境 blocked，或旅程失败 |
-| **DSH-BOOST** | 未测量；无声明 | 代码里有该模式；不能证明收益 | —（只执行不等于测量） | — | 证据卡在记录的锚点上可复跑 | 基准 blocked，或声称的收益被反证 |
-
-标"—"的格子是类别错误，不是通过。各证据词的含义：
-
-| 状态 | 它能支持什么 | 它永远不意味着什么 |
-|---|---|---|
-| `not-run` / `not-measured` | "这项没有测" | 通过，或"应该能跑" |
-| `recognized` / `static` | 结构识别：清单、入口、patch、client 导出 | 进程已运行，或 UI 已渲染 |
-| `runtime` | 在记录的宿主版本/commit 上真实 boot 或真实执行 | UI 正确、生产可用、安全 |
-| `manual` | 真人走完旅程并记录了步骤和日志 | 自动化，或覆盖其他平台 |
-| `measured` | 带环境、输入、命令、对照、结果的可复跑证据卡 | 生产基准，或计费口径 |
-| `blocked` | 宿主或夹具导致判不了 | 插件失败，或通过 |
-| `failed` | 可复现、可归因于插件的失败 | 没有证据的"环境问题" |
-| `stale` | 已过有效期 | 当前证据；只能当 stale 引用 |
-
-这张表专门拦三种误读：
-
-- **`runtime` 不是 UI 已渲染。** 服务端行 boot 起来、或 client 模块加载成功，都不能证明 slot 渲染正确。`client-module-loaded` ≠ `UI-rendered`；渲染正确要单独观察（slot 输出、console 错误、截图）。
-- **`static` 不是 `runtime`。** 解析和识别只说明产物结构上像那么回事，不说明进程真的 boot 了，也不说明依赖在 boot 时解析成功。
-- **`not-measured` 不是通过。** 没有证据是第三种状态，要写"未测"，不能写"通过"或"应该能跑"。
-
-## DSH-ENTRY：兼容底线
-
-**回答什么。** 现有插件几乎不改，能不能在目标 DSH 线上被识别、安装并跑起来？
-
-**需要什么证据。** 四个静态门 + 一个运行时门 + 一个流程门：
-
-| 门 | 检查 | 归因 |
-|---|---|---|
-| G0 | `dsh.bundle.patch` 可解析 | 插件 |
-| G1 | base + 样本可组合；插入行 name 可解析 | 插件 |
-| G2 | `evaluatePluginCompatibility` 放行，或存在显式的精确版本豁免 | 宿主 |
-| G3 | 真实 `boot()` 后每个目标行是 `ACTIVE` 或 `disabled` | 插件/宿主/夹具 |
-| G4 | 有 `dsh.client` 时：`exports["./client"]` + 包根行（静态） | 插件 |
-| G5 | 报告带宿主版本/commit 与产物 mtime；过期证据标 `stale` | 流程 |
-
-G0–G2 与 G4 在静态检查里通过，支持 `recognized`；`runtime` 需要在记录的宿主上过 G3。`blocked` 与 `failed` 是不同结论，必须带原因分别报告。
-
-**不声称什么。** 不声称安全、UI 正确、生产可用、功能完整、官方背书，也不声称在未测过的 DSH 线上可用。
-
-**怎么自检。** 记录 `dsh --version`、宿主 commit、产物 mtime。先跑 `dsh-plugin-dev check --json` 的 16 项本地静态检查（它是 `dsh-plugin-doctor` 33 项的子集，见 [family-toolchain.md](family-toolchain.md)）；再跑标准仓的 entry 检查器（命令见下）。bundle 还要跑 `dsh --profile <name> --dump-config`，确认没有 `patch: entry <id> not found`，然后真实 boot 并读行状态。声明写成 `DSH-ENTRY: runtime (dsh 0.2.1-rc.2, commit <sha>, 2026-11-01)`。
-
-## DSH-FLOW：采用体验
-
-**回答什么。** 装好之后，用户能不能装得上、配得动、用得顺、出错能恢复、能升级、能卸干净，而不会踩到意外？
-
-**需要什么证据。** 八条用户旅程 J1–J8：安装/移除；启用/停用；配置与校验；首次成功（quickstart 与错误三要素）；权限与披露；升级/回滚/卸载；可观测与诊断；client/server 形态（headless、web、client-off）。每条旅程记录命令、环境、结果、日志路径和时间。人工旅程只要标 `manual` 就是有效证据；没跑的旅程是 `not-run`，不是通过。
-
-**不声称什么。** 不声称认证、排名、安全审计、覆盖所有 UI 布局与平台，也不声称在一台宿主上跑通的旅程能自动推广到另一台。
-
-**怎么自检。** 用临时 `DSH_HOME`：`add` → `--dump-config` 能看到层 → `remove` → 层和依赖都消失。分别用 `{}` 和非法值 boot（非法值必须带字段路径响亮失败）。以新用户身份按 README 走五分钟计时；检查错误三要素（原因、下一条命令、文档锚点）。测一次升级再回滚；client 插件测 headless、web、client-off 三态。起点见 [plugin-dev-guide.md](plugin-dev-guide.md) §7 与 [release-engineering.md](release-engineering.md) 的发布检查单。
-
-## DSH-BOOST：指导性实践
-
-**回答什么。** 插件有没有用 Cordis 原生能力把开发和使用做得可测量地更省，且声称的收益可复跑？
-
-**需要什么证据。** LEV-1–8：effect 可逆且回到基线；必需服务走 `inject` 且不轮询；热配置用 `volatile()` 且不 remount；事件 mode 一致、waterfall 观察者调 `next()`；seam/isolate/group 只在需要时用；工具与提示前缀逐字节稳定，易变数据走 `systemPrompt.context`；长任务走 jobs、并行有界、取消贯穿；bundle/preset 组合差异用 patch 表达，且每条实践一张证据卡。每张卡记录环境、输入规模、命令、**负向对照**、结果、版本锚和限制。
-
-**不声称什么。** 不声称生产基准、计费或缓存命中率、总分、排名，也不声称一个夹具能推广到另一种负载。LEV-6 的前缀稳定性是唯一能直接用 token 计价的实践；其余实践仍然需要证据卡。
-
-**怎么自检。** 一次只挑一条 LEV，先写卡再优化下一条。跑负向对照（例如一个普通配置字段**确实** remount，或一个易变 nonce **确实**打断前缀）。记录 `dsh`、`cordis`、Node 和 commit；没有锚点的数字不是证据。代码路径对照 [plugin-dev-guide.md](plugin-dev-guide.md) §3.3（effect）、§3.6（配置）、§4.3（jobs）、§5（seam）。
-
-## 怎么往上升
-
-**ENTRY → FLOW。** 先拿到真实的 `runtime` 声明：boot bundle，记录宿主版本/commit。再把"前五分钟"做顺：quickstart、在临时 `DSH_HOME` 里可用的 `add`/`remove`、空配置能 boot、非法配置带字段路径响亮失败、每条失败信息都有错误三要素。测一次升级和一次回滚，确认卸载不残留层或依赖。client 插件在声称 UI 之前，先测 headless、web、client-off。相关章节：[plugin-dev-guide.md](plugin-dev-guide.md) §7（打包、安装与踩坑）、[release-engineering.md](release-engineering.md) §7（发布前门禁）、[quick-reference.md](quick-reference.md)。
-
-**FLOW → BOOST。** 把定时器、监听器、连接、watcher、子进程收进带 label 的 `ctx.effect()`，再测量 reload 是否回到基线。必需服务写进 `inject`，可选服务才用 `ctx.get()`，去掉轮询。可调字段改 `volatile()`，测量配置变更 0 remount。工具与提示前缀保持稳定；易变数据放 `systemPrompt.context`。长任务移到 `ctx.jobs`，并行调用加上界，再验证取消。先做 LEV-6 和 LEV-3——草案对两者都已有 measured 示例，且各自都有干净的负向对照。相关章节：[plugin-dev-guide.md](plugin-dev-guide.md) §3.3、§3.6、§4.3、§4.8；[references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md)；官方扩展点手册 [references/official-docs/docs/cookbook/extension-cookbook.md](../references/official-docs/docs/cookbook/extension-cookbook.md)。
-
-**不要为了升级而升级。** 已冻结或准备退役的插件不该再买 `BOOST` 卡；先看 [when-to-retire-a-plugin.md](when-to-retire-a-plugin.md)。如果某个能力已经由更强的实现接管，应该退役，而不是抛光。
-
-## 认证 A–D 与三层正交
-
-认证等级 A–D 描述质量与证据深度；ENTRY/FLOW/BOOST 描述采用深度。两者正交：`A` 不是"ENTRY 级"，`D` 不是"BOOST 不合格"。认证过的插件仍可能 `ENTRY=blocked`；`BOOST=measured` 的插件仍可能有供应链问题。两个 scope 分开写，永远不要把认证等级和层数算成一个总分。
-
-## 标准来源与检查器命令
-
-- 标准仓（公开）：https://github.com/PerryLink/dsh-standards —— 条款 `31`（ENTRY）、`32`（FLOW）、`33`（BOOST）、`34`（GB 类比），以及 `spec/levels.json`。
-- 该仓的审计工具：`40-checker/scripts/level-audit.mjs`。它不随本指南分发；如果你的 checkout 没有，先用 `spec/levels.json` 读定义，再用下面已有的检查器。
-- 已有的 entry 检查器：`40-checker/bin/dsh-plugin-verify.mjs`。
-
-```sh
-git clone https://github.com/PerryLink/dsh-standards
-cd dsh-standards
-# entry，仅静态（不声明 runtime）
-node 40-checker/bin/dsh-plugin-verify.mjs <plugin-dir> --scope entry --entry-claim static
-# 计划中的审计（只有你 checkout 里存在该文件时才运行）
-node 40-checker/scripts/level-audit.mjs <plugin-dir>
-```
-
-`dsh-plugin-dev new` 生成的插件自带 `dsh.standards` 占位——`entry`/`flow` = `not-run`，`boost` = `not-measured`，`evidence` 全为 `null`。只有拿到审计记录的输出才替换它；没有证据就保持 `not-run`，任何层级都不能据此读成通过。
-
-`dsh-plugin-dev check` 是静态辅助工具，不是分级审计；`dsh-plugin-doctor` 把 R/K/D/X 结果映射成 ENTRY 状态，不覆盖 FLOW 或 BOOST。两者都不能单独给出级别。
-
-## 评审者清单
-
-- [ ] 声明同时写了**层**和**证据状态**，不是只写"兼容"。
-- [ ] 证据带 DSH 版本、宿主 commit、Cordis 版本、日期和 scope。
-- [ ] `runtime` 是观察到的，不是从 `static` 推出来的；静态结果标 `recognized`。
-- [ ] 没有把 `not-run`、`not-measured`、`blocked` 改写成通过。
-- [ ] UI 声明有渲染观察；没有把 `client-module-loaded` 说成已渲染。
-- [ ] FLOW 声明列清跑了哪些旅程、谁跑的、命令、结果和日志路径。
-- [ ] BOOST 声明有带负向对照和限制的证据卡；没有从一个夹具推出生产百分比。
-- [ ] A–D 认证等级单独写，没有被当成级别使用。
-- [ ] 没有"官方""认证""国家标准""符合 GB""排名"这类措辞。
-- [ ] 证据在有效期内；过期证据标 `stale`。
-
----
-
-*标准模型：公开的 `dsh-standards` 项目。本章非官方，不授予任何认证。修正应先提到标准仓，再同步回本库。*