dsh-plugin-guide 0.3.42 → 0.4.0

package/guide/family-toolchain.md

@@ -1,260 +0,0 @@
-# 家族工具链路由（family-toolchain.md）
-
-> **这份文件回答**：我的问题该找哪个工具？哪个文档是这项事实的**权威所有者**？
-> 以及 `dsh-plugin-dev check` 的 16 项检查和 `dsh-plugin-doctor` 的 33 项检查是什么关系。
->
-> **原则**：**一个事实只有一个所有者。** 本知识库只负责"认知 + 索引"，
-> 机械检查交给工具；发现重复时**链接**而不是**复述**。
->
-> **测量时间**：2026-10-13。
-
----
-
-## 1. 路由表：问题 → 所有者 → 可引用产物
-
-| 你的问题 | 权威所有者 | 可引用产物 | 命令 |
-|---|---|---|---|
-| 这个插件包结构对不对？ | `dsh-plugin-doctor` | `SPEC.md`（规范）R0–R8 | `npx @perrylink/dsh-plugin-doctor --only R` |
-| 我的 Cordis 用法有没有踩契约？ | `dsh-plugin-doctor` | `SPEC.md` §4.2b，K1–K14 | `… --only K` |
-| 装了能不能起来？ | `dsh-plugin-doctor` D 组 / `dsh-test-drive` | D0–D3/D9；test-drive 的四态记录 | `… --only D` |
-| 我在各个目录里被收录对了吗？ | `dsh-plugin-doctor` CC 组 | CC1–CC5 | `… --only CC` |
-| 我的插件质量几分？ | `dsh-score` | 五维评分 + 排行榜 JSON/MD | `dsh-score <repo\|pkg>` |
-| 怎么从旧世代升上来？ | `dsh-plugin-upgrade` | 走廊卡（`legAB` 20 seams / `legC` E1–E5） | `dsh-plugin-upgrade-scan` |
-| 共享代码怎么写？ | `@perrylink/dsh-plugin-kit` | `data/peer-range.json`、seam/gate 契约、新插件骨架 | — |
-| 社区认证是什么等级？ | `dsh-plugin-certification` + `dsh-cert-mcp` | 五维 A–E、等级 A–D、安全否决 | MCP：`get_certification` |
-| 目标宿主这一版有什么？ | **本知识库** | [`version-matrix.md`](version-matrix.md) | `dsh --version` |
-| 该改哪一行？ | **本知识库** | [`migration-0.2.md`](migration-0.2.md) | — |
-| 官方怎么规定的？ | **本知识库镜像** | `references/official-docs/` | — |
-
----
-
-## 2. `dsh-plugin-doctor`：33 项检查全表
-
-规范来源是 **`SPEC.md`**（spec `v1`，checkset 字符串
-`R0-R8+K1-K14+D0-D3,D9+CC1-CC5/3`），ID 空间**已冻结**（SPEC §3.3）。
-共 **33** 项 = 9 (R) + 14 (K) + 5 (D) + 5 (CC)。
-
-> ⚠️ **不要引用 doctor 的 README 核对检查 ID。** README 在 5 处写 `K1–K9` 和"16 checks"，
-> 而规范 `SPEC.md` 定义的是 **K1–K14** 和 **21 项规范门禁**——README 在 K10–K14 落地时没更新。
-> README 内部还自相矛盾（43 / 41 / 37 仓 vs `data/verified-repos.json` 的 40 条）。
-
-### 2.1 裁定词表（SPEC §2，规范，五种）
-
-| 裁定 | 含义 |
-|---|---|
-| `pass` | 已评估且成立 |
-| `warn` | 已评估、看似违规，**启发式**，需人工复核，**单独不足以定罪** |
-| `fail` | 已评估且违规 → 计入失败 |
-| `error` | **检查本身无法完成** → 计入失败 |
-| `skip` | **未评估** —— **绝不能渲染成 pass** |
-
-正交分类：`critical`（目前仅 `R1`）与 `category` ∈
-{`plugin-defect`, `policy`, `not-applicable`, `environment`, `infrastructure`, `unsupported-host`, `unstable`}。
-**后四类永远不是插件缺陷**；`policy` 表示这是"家族约定而规范并不共享"（R5、R8）。
-
-**降级规则**（SPEC §3.2，规范）：被请求的组里**每一项都 `skip`**，则该组"未被评估"，
-不得报告成功；零检查执行、或组名匹配不到任何东西，同样不得报告成功。
-规范里记了理由：**曾经一个写坏的组名让 35 个仓库的 CI 门禁全绿，而实际什么都没查。**
-
-**K 组覆盖模式**（SPEC §3.4，规范披露）：`src`（带 `src/` → 完整预期覆盖）·
-`lib-fallback`（无 `src/`，退到 `main` 所在目录 → 真实覆盖但**不等价**，K3–K7 可能少报）·
-`none`（都不存在 → 降级）。
-
-### 2.2 R 组 —— 静态 · 包结构（R0–R8）
-
-| ID | 要求 | 裁定 | critical |
-|---|---|---|---|
-| `R0` | 基础清单字段 `name`/`version`/`license`(SPDX)/`type`；仓内有 `README.md` + `LICENSE` | warn · pass | 否 |
-| `R1` | **激活门 `dsh.bundle.patch`** 声明为非空字符串 | fail · pass | **是——唯一 critical** |
-| `R2` | tarball 完整性：`npm pack --dry-run --json --ignore-scripts` 成功；文件表含声明的入口**与** patch 文件且都非空；tarball 名 = name+version | fail · pass · skip | 否 |
-| `R3` | `cordis.patch.yml` 结构（启发式）：存在、解析为顶层 YAML **数组**；空数组合法；非空必须含 `- insert:` 与 ≥1 个 `id:`；每个 `name:` 等于或命名空间在包名之下 | skip · fail · pass | 否 |
-| `R4` | 入口契约：`main`/`exports` 入口存在且同时导出 `apply` 与 `name`；`inject` 是字符串字面量数组 | fail · warn · pass · skip | 否 |
-| `R5` | 依赖策略：① 任何位置不许裸 `cordis`/`schemastery`；② 导入的 `@deepseek-ai/cordis` 必须被声明；③ 它必须在 `peerDependencies` **和** `devDependencies`，**绝不** `dependencies`；④ `@deepseek-ai/dsh` 不得是直接 `dependencies` | fail · pass · skip | 否（`policy`） |
-| `R6` | `engines.node` 兼容 `^22.19.0 \|\| >=24.0.0`（只声明 Node 23 会失败） | fail · warn · pass | 否 |
-| `R7` | `files` 白名单已声明且覆盖入口 + patch；需要构建时入口不得指向源码 | fail · pass | 否 |
-| `R8` | 不得有指向已被取代的预发布线的陈旧 peer 范围（`0.1.0-rc.*`、`0.1.1-rc.*`、`0.1.2-alpha.*`、`0.1.3-alpha.*`），也不得有开顶 `>=` 范围 | skip · fail · warn · pass | 否（`policy`；"报告**陈旧**，不是**损坏**"） |
-
-**规范门禁**（SPEC §1）：`R0, R1, R3, R5, R6, R7, R8, K1–K14` = **21 项**，
-故意排除 R2 和 R4（它们读的是**构建产物**）。
-
-### 2.3 K 组 —— 静态 · Cordis 契约扫描（K1–K14）
-
-K1–K9 回答"这个插件自身正确吗"；**K10–K14 回答"它会不会干扰别的插件，或被别的插件悄悄吃掉"**。
-全部为启发式；没有发现源码文件时一律 `skip`。
-
-| ID | 含义 | 裁定 |
-|---|---|---|
-| `K1` | 每个 `ctx.<service>` 访问要么是 Context 内建、要么在 `inject` 声明、要么经 `ctx.get(name)` | skip · warn · pass |
-| `K2` | **活数据序列化红线** —— 绝不 `JSON.stringify(ctx…)`、`structuredClone(ctx…)`、`{...ctx…}` | skip · **fail** · pass |
-| `K3` | 定时器/全局监听被 `ctx.effect`（或 `ctx.on`）包裹，或显式自清理 | skip · warn · pass |
-| `K4` | 定义 `Schema` 的文件里不得引入箭头函数 | skip · warn · pass |
-| `K5` | `apply` 返回形态（v4 Effect 契约）：disposer 函数、`null`、`undefined`、`Promise<disposer>`、或（异步）可迭代；async `apply` 合法但必须返回 `Promise<disposer>` | skip · warn · pass |
-| `K6` | 每个注入的服务名要么是已知宿主接缝、要么带命名空间（含 `.`）、要么是自己 `provide` 的 | skip · warn · pass |
-| `K7` | 无 v3 遗留 API：`ctx.using/scope/runtime/lifecycle/collect/accept/decline/alias/off/fork`、`ctx.config`、`ctx.start()/stop()`、v3 的 `inject: {required, optional}` | skip · **fail**（硬名单）· warn（软名单）· pass |
-| `K8` | `export const Config` 必须是 Standard Schema 校验器，不是普通对象字面量 | skip · **fail** · pass |
-| `K9` | 对象插件不得设 `name: 'apply'`（框架会把它重置为 `undefined`） | skip · warn · pass |
-| `K10` | 用 `ctx.on(<waterfall 事件>, …)` 注册的监听器必须引用 `next` | skip · warn · pass |
-| `K11` | 注册的工具名不得与宿主内建或保留字 `run_code` 冲突，也不得用 `tools.data.delete(def.name)` + 重新注册的遮蔽写法 | skip · warn · pass |
-| `K12` | 传给 `super(ctx, '<name>')` / `ctx.provide('<name>')` 的键不得等于宿主接缝名 | skip · warn · pass |
-| `K13` | `cordis.patch.yml` 不得带顶层（非 `insert`）且 `id` 属于宿主的行（按 id 定位的 patch **整行替换 config，不做深合并**） | skip · warn · pass |
-| `K14` | **跨仓注入点冲突** —— 任何自有名字（服务键、工具名、命令名、patch `insert` 行 id）都不得与同工作区的兄弟插件仓重复 | skip · warn · pass |
-
-**K14 有规范的"守卫感知豁免"**（SPEC §4.2b）：在 `package.json` 的
-`dsh-plugin-doctor.crossPlugin.exempt` 或旁挂 `dsh-plugin-doctor.yml` 里声明
-`{kind, name, peer?, guard?}` 列表，`kind` ∈ {`service`, `tool`, `command`, `patch insert id`}；
-被豁免的冲突算 `pass`。工作区里少于两个插件仓时降级为 `skip`——
-所以随包发布的 CI workflow（不传 `--workspace`）不会因此挂构建。
-
-K10/K11/K13 的参照数据取自上游 `docs/event-producer-consumer.md` 的 `@mode` 列、
-工具目录各节，以及基线 DSH `0.2.0-rc.2` 的 `packages/bundle/base/cordis.patch.yml` 顶层 id。
-
-### 2.4 D 组 —— 动态 · 沙箱冒烟（D0–D3, D9）
-
-| ID | 要求 | 裁定 |
-|---|---|---|
-| `D0` | `npm pack --ignore-scripts` 成功；tarball 写进**沙箱**，不是被测仓库 | fail · pass |
-| `D1` | 宿主从 tarball 安装：`dsh plugin --profile headless add <tarball>`（带 `--ignore-scripts`）把包名写进 `dsh.profile.bundles` | skip · fail · pass |
-| `D2` | `dsh --profile headless --dump-config` 输出层标记 `# == <package name>` | skip · fail · pass |
-| `D3` | **无密钥 headless 冒烟（`MISSING_CREDENTIAL` 判据）**：无凭据时以**退出码 1 + `dsh: MISSING_CREDENTIAL`** 结束（有凭据环境下退出 0 也算 pass）。明确致命：`NO_ADAPTER`、`ERR_MODULE_NOT_FOUND`、`SyntaxError`、`TypeError`、`ReferenceError`、`Cannot find module` | skip · fail · pass |
-| `D9` | **沙箱隔离** —— 沙箱被隔离而非删除；运行打印隔离路径；删除是单独显式步骤 | pass · fail |
-
-D1 里"不是插件缺陷"的情形：缺 `pnpm`/`npm`（`infrastructure`）、宿主版本装不上（`unsupported-host`）、
-pnpm `ignored-builds` 阻断（`environment`，报为 `skip`）。
-
-### 2.5 CC 组 —— 生态 · 目录收录（CC1–CC5）
-
-渠道数据缺失时一律 `skip`，**永不判失败**。
-
-| ID | 要求 | 裁定 |
-|---|---|---|
-| `CC1` | 认证注册表 spec v1：若已收录，条目需带 `grade`、`snapshot` 和五维（`manifest`、`buildHygiene`、`supplyChain`、`releaseIntegrity`、`installSmoke`）的 `evidence`，无 `veto`，且 `installSmoke ≠ install-fail` | skip · warn · pass |
-| `CC2` | `adp-list` 条目：`url`/`name`/`category` 齐备；`category` 在 **23 值枚举**内；`url` 与仓库一致；`description.en` 单行；`tarball` 若存在须是 GitHub Release 上的 `https` `.tgz` | skip · fail · pass |
-| `CC3` | `dsh-catalog` 条目：`npm`/`repo`/`displayName`/`categories`/`summary` 齐备；`repo` 一致；`categories` 非空数组；`summary` ≤1000 字符、不含安装命令文本、且未被截断（须以标点结尾） | skip · fail · pass |
-| `CC4` | `dshWorkshop` 清单：若声明，`lifecycle.activation` 必须是**五个枚举值**之一 | skip · fail · pass |
-| `CC5` | **家族三重门——规范明说"这不是生态标准"**：Apache-2.0 许可、五语 README、三种 seam 角色，由 `dsh-plugin-kit` 校验 CLI 检查。非 PerryLink 工作区报 `skip`（`not-applicable`） | skip · fail · pass |
-
-> **CC4 的五个值**（doctor SPEC 断言，但**只有 doctor 的 `SURVEY.md` §1.5 列出了它们**）：
-> `immediate`、`hot-reload`、`restart-plugin`、`restart-profile`、`restart-host`；
-> `restartRequired` 判据为 `/^restart-/`。
-
-### 2.6 退出码契约
-
-| 码 | 含义 |
-|---|---|
-| `0` | 无 fail/error，且每个被请求的组**真的跑过** |
-| `1` | 存在 fail/error（插件缺陷） |
-| `2` | 用法错误 / 未知组 / 未知选项 |
-| `3` | 基础设施错误 |
-| `4` | 宿主版本不支持，**不是插件裁定** |
-| `5` | 结果不稳定，步骤超时或被杀 |
-| `6` | **降级（degraded）**——被请求的组从未真正运行 |
-
-`--allow-degraded` 把 6 降为 0，但 JSON 里 `degraded` 字段仍非空。
-**两道防假绿**：`--only` 组名匹配不到 → 立即 `2`；被请求的组全部 `skip` → `6`。
-
-**组别名**：`R` = R0–R8，`K` = K1–K9 *(README)* / **K1–K14** *(SPEC，以此为准)*，
-`D` = D0–D3/D9，`CC` = CC1–CC5。**建议用 ASCII 别名**——
-一个被双重错误编码的 CJK 组名匹配不到任何东西（这正是 35 仓假绿的成因）。
-
----
-
-## 3. 六项检查族的交叉对照
-
-| 工具 | 检查项 | 层级 | 与本库的关系 |
-|---|---|---|---|
-| `dsh-plugin-dev check`（**本库**） | **16** 项 | 静态 | 每项经 `src/cli/skill-sections.ts` 链回本知识库章节 |
-| `dsh-plugin-doctor` | **33** 项（规范门禁 21） | 静态 + 动态 + 生态 | 超集；R8 与我们的 `manifest-peers` 重叠但**更严**（查开顶区间与陈旧线） |
-| `omdsh-dev/dsh-plugin-check` | **33** 项（README 只列 26） | 静态 | 独立实现，基线停在 0.1.5-rc.1 |
-| `dsh-session-health` | 11 项检测 ID | 静态 | 会话文件层面 |
-| `dsh-security-audit` | 6 个 action | 静态 | 四态诚实模型（skipped/error 永不记为 pass） |
-| `dsh-cert-mcp` / certification | 5 维（A–E） | 生态 | 认证等级 A–D + 安全否决 |
-
-### 3.1 本库 `dsh-plugin-dev check` 的 16 项 ID
-
-`patch-valid` · `patch-ids-unique` · `manifest-bundle-patch` · `manifest-main` ·
-`manifest-peers` · `manifest-engines` · `manifest-files` · `manifest-package-manager` ·
-`display-meta` · `readme-five-langs` · `readme-consistency` ·
-`redline-persona-role` · `redline-waterfall-next` · `redline-no-hardcoded-tunables` ·
-`redline-effect-registration` · `redline-async-apply-registration`
-
-### 3.2 与 doctor 的对应关系（谁更严就用谁）
-
-| 本库检查 | doctor 对应 | 说明 |
-|---|---|---|
-| `patch-valid` | `R3` | doctor 额外要求 `name:` 命名空间在包名之下 |
-| `patch-ids-unique` | `K13` | doctor 从"重复"扩展到"是否占用宿主 id" |
-| `manifest-bundle-patch` | `R1` | **R1 是唯一 critical**，我们的是普通 fail |
-| `manifest-main` | `R4` | doctor 还查导出是否含 `apply` + `name` |
-| `manifest-peers` | `R5` + `R8` | **doctor 更严**：查裸 `cordis`、查 `dependencies` 误置、查陈旧线与开顶区间 |
-| `manifest-engines` | `R6` | — |
-| `manifest-files` | `R7` | — |
-| `manifest-package-manager` | — | 本库独有 |
-| `display-meta` | — | 本库独有（doctor 无展示元数据检查） |
-| `readme-five-langs` | `CC5`（仅家族内） | doctor 只在 PerryLink 工作区查 |
-| `readme-consistency` | — | 本库独有 |
-| `redline-persona-role` | — | 本库独有 |
-| `redline-waterfall-next` | `K10` | 重叠 |
-| `redline-effect-registration` | `K3` + `K5` | doctor 拆成两项 |
-| `redline-async-apply-registration` | `K5` 部分 | ⚠️ **我们是家族内该缺陷的唯一检测器**——`dsh-plugin-upgrade` 的 `legC` W0 卡明确点名"guide async-apply lint"作为 E2 的预防门。doctor 只查返回形态 |
-| `redline-no-hardcoded-tunables` | `K8` 部分 | doctor 查 `Config` 是否 Standard Schema |
-
-> **结论**：**我们的 16 项是 doctor 33 项的子集，但有 5 项 doctor 没有**
-> （`manifest-package-manager`、`display-meta`、`readme-consistency`、
-> `redline-persona-role`、`redline-async-apply-registration`）。
-> 两者**不是替代关系**：本库的检查**每一项都链回可读章节**，doctor 的检查**有裁定语义与退出码契约**。
-> 严肃发布请**两个都跑**。
-
----
-
-## 4. 规范事实：只认一个所有者
-
-| 事实 | 所有者 | 值 |
-|---|---|---|
-| canonical peer 区间 | `dsh-plugin-kit` → `data/peer-range.json` | 六子句（见 [version-matrix.md](version-matrix.md) §4.1） |
-| 家族花名册 | `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/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) |
-
-> ⚠️ **花名册计数存在五个互相冲突的说法**，引用前先看日期：
-> `data/repos.json`（2026-10-12）95 条 · certification README 94/86 · doctor README 42/34 ·
-> doctor 自己的表 45 行 · `dsh-catalog` README 自相矛盾（开头 96 / 计数节 42）·
-> `dsh-kit` README "87 活跃 + 5 冻结 = 92"。
-> **以 `data/repos.json` 为准**；本库 `guide/when-to-retire-a-plugin.md` 的
-> "44 仓 / 7 冻结"是 **2026-10-05 那次审计的快照**，测的是不同时点，**不要直接换算**。
-
----
-
-## 5. 本知识库在家族里的位置
-
-```
-                        认知层（读）                    机械层（跑）
-                  ┌──────────────────────┐      ┌──────────────────────────┐
-   官方契约 ──────┤  dsh-plugin-guide    │      │  dsh-plugin-doctor       │ 33 项，有裁定语义
-   + 版本谱系     │  （本库）             │      │  dsh-test-drive          │ 隔离冒烟
-   + 迁移叙事     │  guide/ + references/ │      │  dsh-score               │ 五维评分
-   + 踩坑档案     │  + dsh-plugin-dev    │      │  dsh-cert-mcp            │ 认证查询
-                  │    check（16 项）     │      │  dsh-plugin-upgrade      │ 走廊扫描
-                  └──────────────────────┘      └──────────────────────────┘
-                            ↑                                  ↑
-                       回答"为什么/该改哪"                回答"过没过/几分"
-```
-
-**分工一句话**：本库负责**认知**（为什么、该改哪一行、这一版有什么），
-工具链负责**判定**（过没过、几分、能不能装）。**两者都链到本库章节**——
-`dsh-plugin-dev check` 经 `src/cli/skill-sections.ts`，
-`dsh-plugin-upgrade` 的 `legC` 卡直接点名本库的 async-apply lint。
-
----
-
-## 6. 未核事项
-
-- `dsh-plugin-doctor` 的 `--dsh` 默认值：README 兼容性单元格写 peer 下界 `0.1.2-rc.1`，
-  用法注释却写 npm latest——**两处冲突**。
-- SPEC checkset 字符串里的 `/3` 含义未确认。
-- CC2 的 23 值 `category` 枚举**家族内无人发布完整列表**（doctor 的 `adp-list` 可导出）。
-- `data/verified.json`（区别于 `verified-repos.json`）当前内容未读。
-- 本表**未执行任何家族工具**；所有行为描述均为**文档化行为**，非实测行为。

package/guide/links.md

@@ -1,112 +0,0 @@
-# 文档链接索引（links.md）
-
-> `dsh-plugin-guide` 的 URL 索引：官方开发/参考文档的**线上 URL ↔ 本地副本**对照，加上社区开发文档的常用入口。
-> **官方文档 URL 的唯一家**：官方链接在本文件维护，别处只引用本文件；社区链接的完整清单家是 [community-ecosystem.md](../references/community-ecosystem.md)，这里只列开发时最常用的入口，避免两份清单漂移。
-> 文档站根路由为中文，`en/` 前缀为英文投影；本地副本统一在 `references/official-docs/docs/`，`.zh.md` 为中文对。
-> 引用本文件的位置：[SKILL.md](../SKILL.md)、[plugin-dev-guide.md](plugin-dev-guide.md) §1/§9、[quick-reference.md](quick-reference.md)、README。
-
-## 1. 官方开发文档（develop）
-
-站点基址 `https://deepseek-harness.github.io/deepseek-harness`；下表链接为中文根路由，英文页在路径前加 `en/`。
-
-| 主题 | 站点路由 | 本地副本（references/official-docs/docs/） |
-|---|---|---|
-| 第一个 Harness 插件（入门） | [develop/basic/](https://deepseek-harness.github.io/deepseek-harness/develop/basic/) | user/develop/basic/index.md |
-| 开发一个 Tool | [develop/basic/tool](https://deepseek-harness.github.io/deepseek-harness/develop/basic/tool) | user/develop/basic/tool.md |
-| 插件配置 | [develop/basic/config](https://deepseek-harness.github.io/deepseek-harness/develop/basic/config) | user/develop/basic/config.md |
-| 打包与安装插件 | [develop/basic/publish](https://deepseek-harness.github.io/deepseek-harness/develop/basic/publish) | user/develop/basic/publish.md |
-| 插件与生命周期 | [develop/framework/](https://deepseek-harness.github.io/deepseek-harness/develop/framework/) | user/develop/framework/index.md |
-| 服务与依赖 | [develop/framework/service](https://deepseek-harness.github.io/deepseek-harness/develop/framework/service) | user/develop/framework/service.md |
-| 事件系统 | [develop/framework/events](https://deepseek-harness.github.io/deepseek-harness/develop/framework/events) | user/develop/framework/events.md |
-| 能力的三层拆分 | [develop/practice/](https://deepseek-harness.github.io/deepseek-harness/develop/practice/) | user/develop/practice/index.md |
-| LLM 适配器 | [develop/practice/llm-adapter](https://deepseek-harness.github.io/deepseek-harness/develop/practice/llm-adapter) | user/develop/practice/llm-adapter.md |
-| Cordis 框架教程 01–07 | [develop/cordis-tutorial/](https://deepseek-harness.github.io/deepseek-harness/develop/cordis-tutorial/) | cordis-tutorial/ |
-
-## 2. 官方参考文档（reference）
-
-| 主题 | 站点路由 | 本地副本（references/official-docs/docs/） |
-|---|---|---|
-| 架构总纲 | [reference/](https://deepseek-harness.github.io/deepseek-harness/reference/) | architecture.md |
-| Cordis 入门（5 分钟） | [reference/cordis-primer](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-primer) | cordis-primer.md |
-| 能力接缝 | [reference/capability-seams](https://deepseek-harness.github.io/deepseek-harness/reference/capability-seams) | capability-seams.md |
-| Agent 生命周期 | [reference/agent-lifecycle](https://deepseek-harness.github.io/deepseek-harness/reference/agent-lifecycle) | agent-lifecycle.md |
-| Tool 执行管线 | [reference/tool-execution-pipeline](https://deepseek-harness.github.io/deepseek-harness/reference/tool-execution-pipeline) | tool-execution-pipeline.md |
-| 生成式参考（配置/Tool/持久化） | [reference/config-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/config-catalog) · [tool-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/tool-catalog) · [persistence-catalog](https://deepseek-harness.github.io/deepseek-harness/reference/persistence-catalog) | config-catalog.md / tool-catalog.md / persistence-catalog.md |
-| Cordis 核心 API | [reference/cordis-api/context](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/context) · [events](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/events) · [fiber](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/fiber) · [registry](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/registry) · [service](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/service) · [inherited](https://deepseek-harness.github.io/deepseek-harness/reference/cordis-api/inherited) | cordis-api/ |
-| 开发手册（Cookbook） | [adding-a-package](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-package) · [adding-a-tool](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-a-tool) · [adding-an-llm-adapter](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/adding-an-llm-adapter) · [extension-cookbook](https://deepseek-harness.github.io/deepseek-harness/reference/cookbook/extension-cookbook)（`adding-a-conversation-node` 已在 alpha.3 上游移除） | cookbook/ |
-| 子系统生成式服务/事件 API | [reference/subsystems/](https://deepseek-harness.github.io/deepseek-harness/reference/subsystems/)（每个子系统一页：tools、shell、session、web、skills、subagent、settings、otel、product-telemetry、voice-input、claude-code-mods……） | subsystems/ |
-| API 网关 | [reference/api-gateway](https://deepseek-harness.github.io/deepseek-harness/reference/api-gateway) | api-gateway.md |
-| 公开部署（反向代理） | [guide/public-deployments](https://deepseek-harness.github.io/deepseek-harness/guide/public-deployments)（`--public-url` / `--trusted-host`） | user/guide/public-deployments.md |
-
-## 2.1 未上文档站的仓库内文档（只有 GitHub 直链 + 本地副本）
-
-这些文件在 `references/official-docs/docs/` 里**有全文副本**，但**不在站点路由表**（`website-docs.ts`）里，所以站上找不到——只能读本地副本或 GitHub：
-
-| 主题 | 本地副本 | GitHub 直链 |
-|---|---|---|
-| 会话格式版本状态（**版本权威**） | `docs/session-format-status.md`（**版本权威**；镜像基线已更新为 `latestReleasedVersion: 4` / `evidenceTag: dsh-v0.2.0-rc.2`） | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/session-format-status.md) |
-| 逐版本迁移指南（**无 index、无入链**，6 篇） | `docs/upgrade-guide/v0.1.7-rc.2/**`、`docs/upgrade-guide/v0.2.0-rc.2/**`（schedule-optional-bundle、transcript-view-legacy-normal、account-sign-in-errors、remove-runtime-invariants、schedule-bundle-retired、subpath-plugin-display-manifest） | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/upgrade-guide) |
-| 持久化类型变更记录（含 V4 声明） | `docs/persistence-changes/**`（`2026-09-16-session-format-v4.md`、`finalized/v4.json`、`historical-formats/v3.md`…） | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs/persistence-changes) |
-| 圆角规范 | `docs/ui-radius.md` | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/ui-radius.md) |
-| Web 样式 | `docs/web-styling.md` | [blob](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/web-styling.md) |
-| 模块图 / 依赖目录 / 持久化 schema | `docs/module-graph.md`、`docs/dependency-catalog.json`、`docs/persistence-schema.json` | [docs 目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/docs) |
-| **官方自带插件开发技能**（preset 内，最该读的一份） | 不在 `docs/` 下：`packages/preset/agent-preset/skills/cordis-plugin-development/**`；本库要点摘录见 [../references/official-plugin-dev-skill.md](../references/official-plugin-dev-skill.md) | [目录](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/preset/agent-preset/skills) |
-
-## 3. 官方仓库与直链（GitHub，master 分支）
-
-- 仓库根：https://github.com/deepseek-ai/deepseek-harness · 官网：https://www.deepseek.com/harness/
-- 开发红线 [AGENTS.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/AGENTS.md)（本地副本 references/official-docs/AGENTS.md）
-- **官方 Discussions（Issues 关闭，反馈主渠道）**：https://github.com/deepseek-ai/deepseek-harness/discussions —— **API 核实 `has_issues=false`（无 issue tracker、不收 PR），Discussions 是唯一渠道**；**2026-10-06 全量刷新归档**于 `downloads/github/harness/discussions/`（list.json 含正文；精选线程含评论；`scripts/archive-discussions.ps1` 可带 token 幂等刷新）——**list=5000、精选 1648**。⚠️ REST 列表最多翻到 5000 条（脚本会显式告警），而仓库实际 total_count≈8850（GraphQL 口径）。仓库元数据（star≈244k、fork≈29k、最后 push 2026-10-03）见 `downloads/github/harness/repo.json`。
-- **官方 Releases（唯一权威的"官方决定"记录）**：https://github.com/deepseek-ai/deepseek-harness/releases —— 仓库内**没有 CHANGELOG**，逐版本变更只在 Release 说明里；破坏性变更在正文里以"破坏性变更/Breaking change"标注。本库 `guide/migration-0.2.md` 已对照 `0.1.7-alpha.1` / `0.2.0-rc.2` / `0.2.1-alpha.1` 三份原文明列。
-- **重要社区帖（本世代）**：[#1629 RFC：官方插件脚手架](https://github.com/deepseek-ai/deepseek-harness/discussions/1629)、[#6520 未修复问题清单（本库汇总帖）](https://github.com/deepseek-ai/deepseek-harness/discussions/6520)、[#8199 升级后大批插件被判不兼容](https://github.com/deepseek-ai/deepseek-harness/discussions/8199)、[#8633 宿主插件失败在 web 下不可见](https://github.com/deepseek-ai/deepseek-harness/discussions/8633)、[#8968 改 patch 永久废掉 sessionController](https://github.com/deepseek-ai/deepseek-harness/discussions/8968)、[#8590 社区 0.1.5→0.2.0 移植实录](https://github.com/deepseek-ai/deepseek-harness/discussions/8590)、[#8537 插件验收 profile 隔离提案](https://github.com/deepseek-ai/deepseek-harness/discussions/8537)、[#8669 真实插件构建日志（12 评论）](https://github.com/deepseek-ai/deepseek-harness/discussions/8669)。
-- **npm 包**：`@deepseek-ai/dsh`（https://www.npmjs.com/package/@deepseek-ai/dsh）等全家桶 72 个包元数据归档于 `downloads/npm/`（README 含全表）；`create-dsh-plugin`（https://www.npmjs.com/package/create-dsh-plugin）
-- 未上站的仓库内文档（本地副本 references/official-docs/docs/ 同名文件）：
-  - [docs/event-producer-consumer.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/event-producer-consumer.md) — 全事件生产/消费矩阵
-  - [docs/defensive-patterns.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/defensive-patterns.md) — 防御性模式
-  - [docs/glossary.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/glossary.md) — 术语表
-  - [docs/testing.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/testing.md) — 测试政策
-- 仓库根文件（本地副本 references/official-docs/）：BENCHMARK.md、CLAUDE.md（symlink→AGENTS.md）、CONTRIBUTING.md/.zh.md/.i18n.yaml、README-zh.md/.i18n.yaml、THIRD_PARTY_NOTICES.md、LICENSE
-- 上游 Cordis 框架：https://github.com/cordiverse/cordis · Cordis 论文：https://github.com/cordiverse/paper · **Cordis 文档站源：https://github.com/cordiverse/docs（60+ md，本地 `downloads/github/cordis/docs/`）**
-
-## 4. 社区开发文档（常用入口）
-
-完整 114 仓库清单、awesome 列表与归档位置见 [community-ecosystem.md](../references/community-ecosystem.md)；逐仓库深读见 [community-repo-deep-dive.md](../references/community-repo-deep-dive.md)（首批 15 个）；08-14 晚生态扫描（26 高优文档型 + 19 中优 skill/契约 + 20 低优目录）见 `downloads/_research/github-ecosystem-scan.md`；08-15 第七批（14 个桌面端/桥接/安全/移植仓库）与第八批（3 个主题/市场仓库）见 community-ecosystem.md §4.6/§4.7。
-
-| 仓库 | 用途 |
-|---|---|
-| [omdsh-dev/plugin-template](https://github.com/omdsh-dev/plugin-template) | 生产级独立插件模板：src 四文件结构 + 7 个开发 skill + 自包含 prepare + 契约文档 |
-| [omdsh-dev/dsh-plugin-dev](https://github.com/omdsh-dev/dsh-plugin-dev) | 踩坑档案：20 个实测坑 + 环境基线 |
-| [Opr4Mp3r/deepseek-harness-plugin-from-scratch](https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch) | 代码审计式渐进教程：17 反模式 + 交付检查单 |
-| [vlln/dsh-skills](https://github.com/vlln/dsh-skills) | ✅ **现行**（`plugin-registry` 于 2026-10-03 归档后的继任者）：`make-dsh-plugin` 开发引导 skill + 0.1.6→0.2.0 改名症状表 + 实测踩坑（`gotchas.md`） |
-| ~~[vlln/plugin-registry](https://github.com/vlln/plugin-registry)~~ | ⚠️ **已归档（2026-10-03）**，冻结在 0.1.5 基线。仍可引其 repository-plugin 0809→0811 机制时间线，但**不要再当作活项目** |
-| [whyihaveyou/dsh-suite](https://github.com/whyihaveyou/dsh-suite) | 双语插件目录 + `npm create dsh-plugin` 脚手架 + 每日兼容性 CI |
-| [omdsh-dev/dsh-plugin-check](https://github.com/omdsh-dev/dsh-plugin-check) | 插件健康检查：清单协议 / patch 格式 / 构建陷阱 |
-| [omdsh-dev/dsh-plugin-skills](https://github.com/omdsh-dev/dsh-plugin-skills) | agent 会话内搭建/测试插件的 skill 集 |
-| [randerous/dsh-turn-meta](https://github.com/randerous/dsh-turn-meta) | 最小首插件模板（agent/pre-step + prepend:true） |
-| [flaqai/deepeseek-harness-guide](https://github.com/flaqai/deepeseek-harness-guide) | **15 语言**开发/插件构建指南（最接近官方文档多语翻译） |
-| [Electricitysheep/dsh-handbook](https://github.com/Electricitysheep/dsh-handbook) | 从 0 到 1 深度手册（14 章双语 + 2 PDF，174★） |
-| [flysheep-ai/learn_deepseek_harness](https://github.com/flysheep-ai/learn_deepseek_harness) | 可运行渐进课程 s01–s23（33 SKILL） |
-| [pingfanfan/hello-dsh](https://github.com/pingfanfan/hello-dsh) | 零基础插件开发教程（22 个中文技能实例） |
-| [LaplaceYoung/dsh-book-deepseek-harness](https://github.com/LaplaceYoung/dsh-book-deepseek-harness) | 《深入理解 DeepSeek Harness》源码拆解书（42 md + PDF） |
-| [curtiseng/cordis-course](https://github.com/curtiseng/cordis-course) | Cordis 论文交互式中文课程与译文 |
-| [NanmiCoder/dsh-agent-teams](https://github.com/NanmiCoder/dsh-agent-teams) | 英文插件开发教程 `docs/developing-dsh-plugins.md` + dsh-plugin-development SKILL |
-| [openma-ai/deepseek-harness-typescript-sdk](https://github.com/openma-ai/deepseek-harness-typescript-sdk) | TypeScript SDK（类型/DTS 参考）；Rust 版 [Loner1024/deepseek-harness-sdk-rs](https://github.com/Loner1024/deepseek-harness-sdk-rs) |
-| [anywhere-labs/deepseek-harness-desktop](https://github.com/anywhere-labs/deepseek-harness-desktop) | Electron 桌面端（macOS/Windows 深度适配，08-15 归档）；同类 [cc1252](https://github.com/cc1252/deepseek-harness-desktop)、[ChisaAlter](https://github.com/ChisaAlter/Deepseek-Harness-Desktop) 等 |
-| [zzszmyf/dsh-security-pocs](https://github.com/zzszmyf/dsh-security-pocs) | 三个漏洞 + 链式利用 PoC（!!js 配置执行/沙箱逃逸），配套官方讨论 #817/#454/#523/#250 |
-| [HenryZ838978/deepseek-harness](https://github.com/HenryZ838978/deepseek-harness) | Python 移植（`pip install deepseek-harness` + MCP server + 16 协议怪癖/270+ 试验） |
-| [banana770/dsh-qq-bridge](https://github.com/banana770/dsh-qq-bridge) | QQ ↔ Harness 桥接；npm 配套 [dsh-plugin-adapter-qq](https://www.npmjs.com/package/dsh-plugin-adapter-qq) |
-
-## 5. 官方与社区渠道
-
-- Discord：https://discord.gg/Ycq5dCaS4 · GitHub 讨论区：https://github.com/deepseek-ai/deepseek-harness/discussions（归档见 §3）
-- **未修复问题清单（社区核实版，2026-09-13）**：官方讨论 [#6520](https://github.com/deepseek-ai/deepseek-harness/discussions/6520)（PerryLink 发布：20+4 项 master 未修复 bug，逐条 path:line + 规避 + 原帖链接）；本地结构化对照见 [unfixed-issues.md](unfixed-issues.md)（含「已修复提交号」与「设计行为对照」两节）
-- 插件话题页：https://github.com/topics/dsh-plugin（08-15 快照在 `downloads/topic-snapshots/dsh-plugin-topic-2026-08-15/`，位置记录见 [sources.md](../references/sources.md) §D.2）
-- awesome 列表（插件发现）：见 [community-ecosystem.md](../references/community-ecosystem.md) §5
-- **中文社群与媒体**：微信公众号「DeepSeek Harness 团队」（黑鲸头像，08-12 注册）、企微小助手群（官方 README 链接）；[V2EX](https://global.v2ex.co/t/1234341) 系列线程（1234203/1234320/1234341/1234424/1234521…）；[Bilibili 教程视频](https://www.bilibili.com/video/BV1WmgF6qEMn/)（速通/安装/实战共 9 支，清单见归档 README）；知乎提问 [2040450519303288568](https://www.zhihu.com/question/2040450519303288568)（403 反爬，需浏览器）
-- **英文社群与媒体**：Hacker News（[主发布线程 49285244](https://hn.edgecompute.app/item/49285244) + 5 条子线程，镜像已归档）；X/Twitter（官方 @deepseek_ai [发布帖](https://twitter.com/deepseek_ai/status/2087887408440164663)，digg 聚合见 [Web UI 截图帖](https://digg.com/tech/7fx4ofvh)/[内测招募帖](https://digg.com/tech/silt5bft)）；[OpenRouter Ori Harness](https://openrouter.ai/docs/guides/ori/harness)（OpenRouter 的 DSH 集成）；[Ollama 官方集成](https://docs.ollama.com/integrations/deepseek-harness)
-- 社区文章归档（**149 篇**，`downloads/web/community-articles/`，`scripts/download-community-articles.ps1` 幂等刷新）：中文教程/实测（cnblogs、CSDN、51CTO、阿里云、V2EX、locdd、36氪、量子位、B站…）、英文教程（dev.to、AgentPedia、ExplainX、X-CMD、Ollama…）、HN 镜像线程 7 条
-- 中文速查 + 踩坑：[V2EX 1234341](https://global.v2ex.co/t/1234341)；X-CMD 一键安装：https://www.x-cmd.com/install/deepseek-harness/ ；Ollama 集成：https://docs.ollama.com/integrations/deepseek-harness
-
-## 6. 断链校验
-
-本文件与 README、SKILL.md、guide/*.md 的相对链接由 `scripts/verify-kit.ps1` 扫描；新增链接后运行 `pwsh -File scripts/verify-kit.ps1` 验证。