dsh-plugin-guide 0.3.38 → 0.3.40

package/data/standards.json

@@ -0,0 +1,300 @@
+{
+  "schema": "dsh-plugin-guide-standards/1",
+  "version": "1.0.0",
+  "nonOfficial": true,
+  "updatedAt": "2026-11-01",
+  "localized": {
+    "en": "guide/standards.md",
+    "zh-CN": "guide/standards.zh-CN.md"
+  },
+  "canonical": {
+    "repo": "PerryLink/dsh-standards",
+    "version": "1.0.0-rc.1",
+    "status": "draft",
+    "clauses": [
+      "31-DSH-ENTRY入门规范.md",
+      "32-DSH-FLOW顺畅规范.md",
+      "33-DSH-BOOST加速实践.md",
+      "34-三层分级模型-GB-GBT-GBZ类比.md"
+    ],
+    "auditStatus": "available in the private standards repository; not bundled with this guide",
+    "entryChecker": "40-checker/bin/dsh-plugin-verify.mjs",
+    "private": true
+  },
+  "disclaimer": "Not an official DeepSeek standard, not a certification, not a security audit, and not a legal GB/GB-T/GB-Z instrument. The GB analogy is a communication aid only. Certification grades A-D are orthogonal to the three levels.",
+  "axes": {
+    "depth": [
+      "entry",
+      "flow",
+      "boost"
+    ],
+    "evidence": [
+      "not-run",
+      "recognized",
+      "static",
+      "runtime",
+      "manual",
+      "measured",
+      "blocked",
+      "failed",
+      "stale"
+    ],
+    "rules": [
+      "Depth and evidence are independent; never collapse them into one score.",
+      "static is not runtime; runtime is not UI-rendered; not-measured is not a pass.",
+      "blocked is not failed; failed needs evidence attributable to the plugin.",
+      "Certification grades A-D describe quality, not adoption depth."
+    ]
+  },
+  "levels": [
+    {
+      "id": "entry",
+      "label": "DSH-ENTRY",
+      "analogy": "GB",
+      "question": "Can an existing plugin be recognized, installed, and booted on a target DSH line with little or no code change?",
+      "claim": "compatibility baseline",
+      "evidence": [
+        "recognized",
+        "static",
+        "runtime",
+        "blocked",
+        "failed",
+        "not-run",
+        "stale"
+      ],
+      "gates": [
+        {
+          "id": "G0",
+          "check": "dsh.bundle.patch parses",
+          "owner": "plugin"
+        },
+        {
+          "id": "G1",
+          "check": "base + sample compose; inserted row names resolve",
+          "owner": "plugin"
+        },
+        {
+          "id": "G2",
+          "check": "evaluatePluginCompatibility admits, or an explicit exact-version exemption applies",
+          "owner": "host"
+        },
+        {
+          "id": "G3",
+          "check": "real boot() leaves every target row ACTIVE or disabled",
+          "owner": "plugin/host/fixture"
+        },
+        {
+          "id": "G4",
+          "check": "when dsh.client exists: exports['./client'] and a package-root row (static)",
+          "owner": "plugin"
+        },
+        {
+          "id": "G5",
+          "check": "report carries host version/commit and artifact mtime; expired evidence is stale",
+          "owner": "process"
+        }
+      ],
+      "notClaimed": [
+        "security",
+        "UI correctness",
+        "production readiness",
+        "full feature correctness",
+        "official endorsement",
+        "untested DSH lines"
+      ],
+      "selfCheck": [
+        "record dsh --version, host commit, and artifact mtime",
+        "run dsh-plugin-dev check --json (16 static checks, a subset of dsh-plugin-doctor's 33)",
+        "for bundles: dsh --profile <name> --dump-config, then boot and read row states",
+        "write the claim with level, evidence state, dsh version, commit, and date"
+      ]
+    },
+    {
+      "id": "flow",
+      "label": "DSH-FLOW",
+      "analogy": "GB/T",
+      "question": "Once installed, can a user install, configure, use, recover, upgrade, and uninstall the plugin without surprises?",
+      "claim": "recommended adoption experience",
+      "evidence": [
+        "manual",
+        "runtime",
+        "not-run",
+        "failed",
+        "stale"
+      ],
+      "journeys": [
+        {
+          "id": "J1",
+          "name": "install and remove"
+        },
+        {
+          "id": "J2",
+          "name": "enable and disable"
+        },
+        {
+          "id": "J3",
+          "name": "configuration and validation"
+        },
+        {
+          "id": "J4",
+          "name": "first success (quickstart and error triad)"
+        },
+        {
+          "id": "J5",
+          "name": "permissions and disclosure"
+        },
+        {
+          "id": "J6",
+          "name": "upgrade, rollback and uninstall"
+        },
+        {
+          "id": "J7",
+          "name": "observability and diagnostics"
+        },
+        {
+          "id": "J8",
+          "name": "client/server shapes (headless, web, client-off)"
+        }
+      ],
+      "notClaimed": [
+        "certification",
+        "ranking",
+        "security review",
+        "every UI layout",
+        "every platform",
+        "generalizing one host to another"
+      ],
+      "selfCheck": [
+        "throwaway DSH_HOME: add -> dump-config -> remove, no layer or dependency left",
+        "toggle enabled/disabled; dump diff is correct and the id is stable",
+        "boot with {} and an invalid value (loud failure with a field path)",
+        "follow the README as a new user with a five-minute timer and check the error triad",
+        "check capabilities/labels/commitments against README permissions",
+        "upgrade then rollback; uninstall leaves no layer/dependency/file",
+        "exercise normal, missing-service and port-in-use diagnostics",
+        "for client plugins test headless, web and client-off"
+      ]
+    },
+    {
+      "id": "boost",
+      "label": "DSH-BOOST",
+      "analogy": "GB/Z",
+      "question": "Does the plugin use Cordis primitives to make development and use measurably cheaper, and is the claimed saving reproducible?",
+      "claim": "guiding practice recorded as evidence cards, not a badge",
+      "evidence": [
+        "measured",
+        "not-measured",
+        "failed",
+        "stale"
+      ],
+      "practices": [
+        {
+          "id": "LEV-1",
+          "check": "effects, timers, connections, watchers, and subprocesses return to baseline"
+        },
+        {
+          "id": "LEV-2",
+          "check": "required services use inject; optional services use ctx.get; no polling"
+        },
+        {
+          "id": "LEV-3",
+          "check": "hot config uses volatile() and does not remount"
+        },
+        {
+          "id": "LEV-4",
+          "check": "event modes match; waterfall observers call next()"
+        },
+        {
+          "id": "LEV-5",
+          "check": "seams/isolate/group are used only when needed"
+        },
+        {
+          "id": "LEV-6",
+          "check": "tool and prompt prefixes are byte-stable; volatile data uses systemPrompt.context"
+        },
+        {
+          "id": "LEV-7",
+          "check": "long work uses jobs; parallel calls are bounded; cancellation propagates"
+        },
+        {
+          "id": "LEV-8",
+          "check": "bundle/preset differences are expressed in patches; every practice has an evidence card"
+        }
+      ],
+      "evidenceCardFields": [
+        "environment",
+        "input scale",
+        "command",
+        "negative control",
+        "result",
+        "version anchor",
+        "limitations"
+      ],
+      "notClaimed": [
+        "production benchmark",
+        "billing or cache-hit rate",
+        "total score",
+        "ranking",
+        "generalizing one fixture to another workload"
+      ],
+      "selfCheck": [
+        "pick one LEV and write the card before optimizing the next",
+        "run the negative control and record it",
+        "record dsh, cordis, Node, and the commit; a number without an anchor is not evidence"
+      ]
+    }
+  ],
+  "chapters": {
+    "entry": [
+      "guide/standards.md#dsh-entry-compatibility-baseline",
+      "guide/plugin-dev-guide.md#81-社区三层采用标准",
+      "guide/plugin-dev-guide.md#7-打包安装与分发踩坑重点",
+      "guide/quick-reference.md",
+      "guide/family-toolchain.md"
+    ],
+    "flow": [
+      "guide/standards.md#dsh-flow-adoption-experience",
+      "guide/plugin-dev-guide.md#81-社区三层采用标准",
+      "guide/plugin-dev-guide.md#7-打包安装与分发踩坑重点",
+      "guide/release-engineering.md#7-the-pre-tag-gate",
+      "guide/quick-reference.md"
+    ],
+    "boost": [
+      "guide/standards.md#dsh-boost-guiding-practice",
+      "guide/plugin-dev-guide.md#81-社区三层采用标准",
+      "guide/plugin-dev-guide.md#33-注册即-effect",
+      "guide/plugin-dev-guide.md#36-配置config",
+      "guide/plugin-dev-guide.md#43-后台任务长任务",
+      "guide/family-toolchain.md"
+    ]
+  },
+  "tools": {
+    "audit": {
+      "path": "40-checker/scripts/level-audit.mjs",
+      "url": "40-checker/scripts/level-audit.mjs",
+      "status": "planned",
+      "command": "node 40-checker/scripts/level-audit.mjs <plugin-dir>",
+      "note": "Not bundled with this guide; run only if the file exists in your checkout."
+    },
+    "entryChecker": {
+      "path": "40-checker/bin/dsh-plugin-verify.mjs",
+      "url": "40-checker/bin/dsh-plugin-verify.mjs",
+      "command": "node 40-checker/bin/dsh-plugin-verify.mjs <plugin-dir> --scope entry --entry-claim static"
+    },
+    "localStatic": {
+      "command": "dsh-plugin-dev check --json",
+      "note": "16 static checks (a subset of dsh-plugin-doctor's 33); not a level audit."
+    },
+    "private": true
+  },
+  "certification": {
+    "orthogonal": true,
+    "grades": [
+      "A",
+      "B",
+      "C",
+      "D"
+    ],
+    "note": "Grades describe quality and evidence depth; ENTRY/FLOW/BOOST describe adoption depth. Never compute a total from grade plus level."
+  }
+}

package/guide/family-toolchain.md

@@ -214,7 +214,7 @@ pnpm `ignored-builds` 阻断（`environment`，报为 `skip`）。
 | 家族花名册 | `dsh-plugin-kit` → `data/repos.json` | **95 条**（94 插件 + 1 基建）；活跃 87 / 冻结 5 / 退役 3 |
 | 家族检查 ID 空间 | `dsh-plugin-doctor` → `SPEC.md` | 33 项，已冻结 |
 | 认证等级定义 | `dsh-plugin-certification` → README（即规范） | 五维 A–E，等级 A–D |
-| 认证注册表内容 | 同上 → `data/certified.json` | 截至 2026-10-13：**仅 1 条**（`dsh-auto-review`，A 级，快照 2026-09-07） |
+| 认证注册表内容 | 同上 → `data/attestations.json` | 截至 2026-10-13：**仅 1 条**（`dsh-auto-review`，A 级，快照 2026-09-07） |
 | 已核验仓名单 | `dsh-plugin-doctor` → `data/verified-repos.json` | **40 条** |
 | 升级走廊与 seam | `dsh-plugin-upgrade` | `legAB` 20 seams；`legC` E1–E5 |
 | DSH 版本谱系与 peer 区间选择 | **本知识库** | [`version-matrix.md`](version-matrix.md) |

package/guide/plugin-dev-guide.md

@@ -578,6 +578,10 @@ bundle 挂一个普通 provider 插件：`inject = ['cmdlineArgs']`，用 `@deep
 - **switch 按 discriminant tags**：closed union 以 `assertNever` 收尾；merge-extensible union 落入文档化 default（`SessionEvent` 是后者，见 §3.5）。
 - **独立插件包测试路径**：包级 vitest（fixtures 跨平台回放）+ keyless snapshot（模型/产品可见行为必须有组装后转录快照）+ `pnpm pack` 后装进干净 profile 冒烟（含 `lib/` 构建产物）；社区现成的健康检查见 omdsh-dev/dsh-plugin-check，测试结构范例见 plugin-template 的 `tests/`。
 
+### 8.1 社区三层采用标准
+
+社区标准仓 [`PerryLink/dsh-standards`](https://github.com/PerryLink/dsh-standards) 把 DSH 插件的"合格"拆成三个不同问题：**DSH-ENTRY**（兼容底线，G0–G5）、**DSH-FLOW**（采用体验，J1–J8）与 **DSH-BOOST**（Cordis 增效实践，LEV-1–LEV-8）。三者用"采用深度 × 证据状态"两轴记录，不折算成总分；`static` 不是 `runtime`，`runtime` 不是 UI 已渲染，`not-measured` 不是通过；认证 A–D 与三层正交。完整定义、GB / GB-T / GB-Z 类比（仅类比，非官方）、逐层自检与升级路径见 [standards.md](standards.md)（中文稿 [standards.zh-CN.md](standards.zh-CN.md)），本节不重复。
+
 ---
 
 ## 9. 生态与社区（找参考实现、发插件）

package/guide/standards.md

@@ -0,0 +1,141 @@
+# 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

@@ -0,0 +1,141 @@
+# 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` 项目。本章非官方，不授予任何认证。修正应先提到标准仓，再同步回本库。*