dsh-plugin-guide 0.3.27 → 0.3.30

package/references/official-docs/docs/user/guide/github-review.zh.md

@@ -22,20 +22,17 @@ export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
 printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
 ```
 
-在开发 checkout 中运行：
+先把两个实验包安装到 Web profile。Profile 不会自动安装 peer；GitHub 适配器需要显式安装 webhook 运行时：
 
 ```sh
+dsh plugin --profile web add @deepseek-ai/dsh-webhook @deepseek-ai/dsh-webhook-github
 export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
-pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml
+dsh web --patch "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@deepseek-ai/dsh-webhook-github/examples/github-review/cordis.yml"
 ```
 
-安装版 DSH 通过绝对路径使用同一 overlay：
+示例随 GitHub 适配器发布，并从 profile 的安装目录加载，因此规则模块能解析该 profile 安装的 peer。不要把规则单独放到 profile 之外的任意目录运行。需要定制时，将示例的两个文件复制到 `$DSH_HOME/profiles/web/github-review/`，修改其配置并把 `--patch` 指向复制后的 `cordis.yml`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
 
-```sh
-dsh web --patch /absolute/path/to/github-review/cordis.yml
-```
-
-对于永久 profile，把 `github-ready-review-rule.mjs` 放在 `$DSH_HOME/profiles/web/cordis.patch.yml` 旁边，把 `cordis.yml` 中的行追加到该 patch，然后运行 `dsh web`。随附 CLI 已经包含两个 webhook 包；只需 overlay 即可激活它们。
+仓库中的示例位于 `packages/experimental/webhook-github/examples/github-review/`。Webhook 包不随 CLI 安装，也不出现在官方插件列表中；安装包与提供 overlay 是两个独立步骤。
 
 ## 暴露专用端点
 
@@ -65,7 +62,7 @@ Active:       yes
 
 ## 规则行为
 
-规则只接受来源 `primary-github`、仓库 `deepseek-harness/deepseek-harness`、事件 `pull_request` 与动作 `ready_for_review`。它会把精确 head SHA 和选定 PR 字段传给评审提示词，把 JSON 标为不受信任的元数据，并禁止修改文件、分支、PR 或 GitHub 状态。
+规则只接受来源 `primary-github`、仓库 `deepseek-ai/deepseek-harness`、事件 `pull_request` 与动作 `ready_for_review`。它会把精确 head SHA 和选定 PR 字段传给评审提示词，把 JSON 标为不受信任的元数据，并禁止修改文件、分支、PR 或 GitHub 状态。
 
 Session 请求选择 `standard` agent preset 与 `read-only` permission preset。`workspacePath` 通过 `WorkspaceRegistry.create()` 规范化，因此第一次匹配交付会在 Workspace 不存在时创建它，后续交付会复用它。
 
@@ -89,7 +86,7 @@ if (!response.ok || (await response.json()).automaticReview !== true) return nul
 
 ```js
 const workspacePath = {
-  'deepseek-harness/deepseek-harness': '/path/to/deepseek-harness',
+  'deepseek-ai/deepseek-harness': '/path/to/deepseek-harness',
   'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
 }[payload.repository.full_name]
 if (workspacePath === undefined) return null

package/references/official-docs/docs/user/guide/public-deployments.i18n.yaml

@@ -3,17 +3,17 @@
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/public-deployments.md
 /publish-the-web-ui-behind-a-reverse-proxy:
-  en: 15b92e92d2526f37
-  zh: b58079cf6eee78cc
+  en: 867565aa675f3fb3
+  zh: c60606b5e5bdb778
 /publish-the-web-ui-behind-a-reverse-proxy/what-public-url-advertises:
   en: 576292b93ccf299a
   zh: ded5adc55396869c
 /publish-the-web-ui-behind-a-reverse-proxy/what-the-proxy-must-do:
-  en: 8dd9d910a93fe54d
-  zh: 1e9e21d9949c8ab2
+  en: 2f93051763125365
+  zh: 1dd699cb84ecf034
 /publish-the-web-ui-behind-a-reverse-proxy/trust-the-authority-browsers-use:
-  en: 907b5f90c9860733
-  zh: dcbffd3f00d6c64f
+  en: 08e5a6cc45918876
+  zh: d59178e10e915748
 /publish-the-web-ui-behind-a-reverse-proxy/secure-the-external-leg:
-  en: a833880da5c8bbf4
-  zh: 6f9bd565b7266241
+  en: 2afac1f10e2d2e88
+  zh: f9b4b03a5aad27e1

package/references/official-docs/docs/user/guide/public-deployments.md

@@ -2,7 +2,7 @@
 
 English | [中文](public-deployments.zh.md)
 
-`dsh --profile web` serves the GUI over plain HTTP on a loopback port, so a browser on another machine cannot reach it, and the process knows nothing about the address you do use. A reverse proxy in front of it owns that external leg — the public host name, TLS, and the path prefix it strips before forwarding to the listener — and `--public-url` tells DSH which address browsers use:
+`dsh --profile web` serves the GUI on a loopback port, so a browser on another machine cannot reach it, and the process knows nothing about the address you do use. A reverse proxy in front of it owns that external leg — the public host name, TLS, and the path prefix it strips before forwarding to the listener — and `--public-url` tells DSH which address browsers use:
 
 ```sh
 dsh --profile web --public-url https://app.example/ui/ --trusted-host app.example
@@ -17,17 +17,21 @@ dsh --profile web --public-url https://app.example/ui/ --trusted-host app.exampl
 - **Preserve the browser-facing `Host`.** The fence compares the received `Host` against the accepted authorities, so the proxy forwards it unchanged instead of rewriting it to the listener's address.
 - **Strip the mount prefix.** The listener answers origin-root routes, so a request for `/ui/api/...` must arrive as `/api/...`.
 - **Forward upgrades.** Every request and WebSocket upgrade the page opens must reach the listener with its `Upgrade` and `Connection` headers intact; TLS terminates on the proxy's external leg when it serves HTTPS.
-- **Rewrite cookie scope.** The backend always issues host-only `Path=/` cookies without `Secure`; the proxy rewrites `Path` to the mount (`/ui/`) and adds `Secure` on its HTTPS leg.
+- **Rewrite cookie scope.** A backend serving plain HTTP issues host-only `Path=/` cookies without `Secure`; the proxy then rewrites `Path` to the mount (`/ui/`) and adds `Secure` on its HTTPS leg. A backend listener serving its own TLS already marks the cookie `Secure`, so the proxy only rewrites `Path`.
 - **Redirect the bare mount.** `/ui/` is the only entry: it alone exchanges the launch token for the session cookie, and it or `/ui/index.html` serves the document to a browser that already holds that cookie, because the served document resolves URLs against its own directory. A request to `/ui` must arrive as `/ui/`, and the stripped backend cannot reconstruct that external path.
 
 ## Trust the authority browsers use
 
-The fence accepts loopback plus every authority `--trusted-host` names. A browser that reaches the deployment under any other authority gets 403 for every API call, however correct the proxy is, so name the browser-visible authority with `--trusted-host`; advertising it with `--public-url` is display only and does not admit it. An entry without a port matches any port, which suits a tunnel that binds a different one each time. The fence only admits the request; the launch token in the printed URL and the signed session cookie authenticate it.
+The fence accepts loopback, the listener's own bind address, and every authority `--trusted-host` names. A browser that reaches the deployment under any other authority gets 403 for every API call, however correct the proxy is, so name the browser-visible authority with `--trusted-host`; advertising it with `--public-url` is display only and does not admit it. An entry without a port matches any port, which suits a tunnel that binds a different one each time. The fence only admits the request; the launch token in the printed URL and the signed session cookie authenticate it. TLS, wherever it terminates, changes none of this: the certificate identifies the server to the browser, not the browser to the server.
 
 Neither the advertised URL nor the fence protects the listening port itself, so restrict the port to the trusted proxy or network.
 
 ## Secure the external leg
 
-Terminate TLS at the proxy. An `http://` advertised root sends the launch token and the session cookie unencrypted, and an `https://` root encrypts only the browser-to-proxy leg. The printed URL carries a process credential, so share it only with intended users.
+Terminate TLS at the proxy, on the listener itself, or on both; `--public-url` remains an advertisement. An `http://` browser-facing root exposes the launch token in plaintext. An `https://` proxy root protects the browser-to-proxy leg; encryption between proxy and listener depends on the listener's TLS configuration.
 
-The [Web app reference](../../../packages/bundle/web-app/README.md#public-deployments) owns the `--public-url` and `--trusted-host` command-line contract and the `publicUrl` and `trustedHosts` fields.
+To terminate on the listener, pass `--tls-cert` and `--tls-key`, each a path resolved against the process working directory: the certificate file holds the full chain and the key file an unencrypted PEM private key. DSH never obtains, renews, or watches certificates, and the carrier reads the files once, so replace them and reload the listener or restart the process to change them; startup fails on a missing or invalid pair and never falls back to HTTP. The browser applies its own trust store and name checks, so the certificate must cover the hostname or IP you open. The default port stays 3080. Native TLS needs no proxy, but proxy deployments and `--public-url` remain supported independently. A TLS listener marks session cookies `Secure`; keep the public browser-facing leg HTTPS so browsers can return those cookies.
+
+The printed URL carries a process credential, so share it only with intended users.
+
+The [Web app reference](../../../packages/bundle/web-app/README.md#public-deployments) documents the `--public-url`, `--trusted-host`, and `--tls-cert`/`--tls-key` command-line options. In the Web profile, `publicUrl` configures the `web-runtime` row, `trustedHosts` configures the [Connection row](../../../packages/client/connection/README.md), and `tls` configures the [webserver row](../../../docs/subsystems/web-server.md#config).

package/references/official-docs/docs/user/guide/public-deployments.zh.md

@@ -2,7 +2,7 @@
 
 [English](public-deployments.md) | 中文
 
-`dsh --profile web` 在 loopback 端口上以明文 HTTP 提供 GUI，因此其他机器上的浏览器无法访问它，进程也无从得知你实际使用的地址。它前面的反向代理拥有这条外部链路——公开主机名、TLS，以及转发到监听器之前剥离的路径前缀——`--public-url` 则告诉 DSH 浏览器使用的是哪个地址：
+`dsh --profile web` 在 loopback 端口上提供 GUI，因此其他机器上的浏览器无法访问它，进程也无从得知你实际使用的地址。它前面的反向代理拥有这条外部链路——公开主机名、TLS，以及转发到监听器之前剥离的路径前缀——`--public-url` 则告诉 DSH 浏览器使用的是哪个地址：
 
 ```sh
 dsh --profile web --public-url https://app.example/ui/ --trusted-host app.example
@@ -17,17 +17,21 @@ dsh --profile web --public-url https://app.example/ui/ --trusted-host app.exampl
 - **保留浏览器可见的 `Host`。** 栅栏把收到的 `Host` 与被接受的 authority 比对，因此代理应原样转发，而不要改写成监听器的地址。
 - **剥离挂载前缀。** 监听器应答的是 origin-root 路由，因此对 `/ui/api/...` 的请求必须以 `/api/...` 抵达。
 - **转发升级请求。** 页面发出的每个请求与 WebSocket 升级都必须连同其 `Upgrade` 与 `Connection` 头抵达监听器；代理对外提供 HTTPS 时，TLS 在其外部链路上终止。
-- **改写 cookie 作用域。** 后端始终签发不带 `Secure` 的 host-only `Path=/` cookie；代理把 `Path` 改写为挂载（`/ui/`），并仅在其 HTTPS 链路上添加 `Secure`。
+- **改写 cookie 作用域。** 以明文 HTTP 提供服务的后端签发不带 `Secure` 的 host-only `Path=/` cookie；代理再把 `Path` 改写为挂载（`/ui/`），并仅在其 HTTPS 链路上添加 `Secure`。监听器自身提供 TLS 时 cookie 已带 `Secure`，代理只需改写 `Path`。
 - **重定向裸挂载。** `/ui/` 是唯一入口：只有它把启动 token 换成会话 cookie；已持有该 cookie 的浏览器可由它或 `/ui/index.html` 取得文档，因为所提供的文档以自身目录解析 URL。对 `/ui` 的请求必须以 `/ui/` 抵达，而被剥离路径的后端无法重建该外部路径。
 
 ## 信任浏览器使用的 authority
 
-栅栏接受 loopback，以及每个由 `--trusted-host` 点名的 authority。浏览器若以其他任何 authority 访问部署，无论代理多么正确，每个 API 调用都会得到 403，因此请用 `--trusted-host` 点名浏览器可见的 authority；用 `--public-url` 公告它只是展示，并不等于接纳。不带端口的条目匹配任意端口，适合每次绑定不同端口的隧道。栅栏只放行请求；打印 URL 中的启动 token 与签名会话 cookie 才完成认证。
+栅栏接受 loopback、监听器自身的绑定地址，以及每个由 `--trusted-host` 点名的 authority。浏览器若以其他任何 authority 访问部署，无论代理多么正确，每个 API 调用都会得到 403，因此请用 `--trusted-host` 点名浏览器可见的 authority；用 `--public-url` 公告它只是展示，并不等于接纳。不带端口的条目匹配任意端口，适合每次绑定不同端口的隧道。栅栏只放行请求；打印 URL 中的启动 token 与签名会话 cookie 才完成认证。无论 TLS 在哪里终止都不改变这一切：证书只是向浏览器标识服务器，而不是向服务器标识浏览器。
 
 无论是公告 URL 还是栅栏都不保护监听端口本身，因此请把端口限制在可信代理或网络内。
 
 ## 保护外部链路
 
-在代理处终止 TLS。`http://` 公告根会以明文发送启动 token 与会话 cookie，而 `https://` 根只加密浏览器到代理这一段。打印的 URL 携带进程凭据，只应与预期用户分享。
+可以在代理处、监听器本身或两者上终止 TLS；`--public-url` 仍只是公告。面向浏览器的 `http://` 根会明文暴露启动 token。`https://` 代理根保护浏览器到代理这一段；代理与监听器之间是否加密取决于监听器的 TLS 配置。
 
-[Web 应用参考](../../../packages/bundle/web-app/README.zh.md#public-deployments)负责 `--public-url` 与 `--trusted-host` 的命令行约定，以及 `publicUrl` 与 `trustedHosts` 字段。
+要在监听器上终止 TLS，请传入 `--tls-cert` 与 `--tls-key`，两者各是相对进程工作目录解析的路径：证书文件包含完整证书链，密钥文件为不带口令的 PEM 私钥。DSH 从不获取、续期或监视证书，且载体只读取一次文件，因此更换文件后需重新加载监听器或重启进程；文件缺失或无效时启动失败，绝不回退到 HTTP。浏览器使用自己的信任库与名称校验，因此证书必须覆盖你所访问的 hostname 或 IP。默认端口仍为 3080。原生 TLS 不需要代理，但代理部署与 `--public-url` 仍分别受支持。TLS 监听器会给会话 cookie 加上 `Secure`；公开部署的浏览器侧链路应保持 HTTPS，才能让浏览器回传这些 cookie。
+
+打印的 URL 携带进程凭据，只应与预期用户分享。
+
+[Web 应用参考](../../../packages/bundle/web-app/README.zh.md#public-deployments)说明 `--public-url`、`--trusted-host` 与 `--tls-cert`/`--tls-key` 命令行选项。在 Web profile 中，`publicUrl` 配置在 `web-runtime` 行，`trustedHosts` 配置在 [Connection 行](../../../packages/client/connection/README.zh.md)，`tls` 配置在 [webserver 行](../../../docs/subsystems/web-server.zh.md#config)。

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

@@ -40,7 +40,7 @@ Every package lives in exactly one group; new packages join existing groups, and
 | [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider |
 | [`ssh/`](ssh/README.md) | POSIX remote connection with paired filesystem, subprocess and sandbox providers |
 | [`shell/`](shell/README.md) | Bash capability family: executor seam, local impl, model-facing tools |
-| [`terminal/`](terminal/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, model-facing tools |
+| [`terminal/`](terminal/README.md) | Persistent PTY service with owner-scoped sessions and a local shell backend |
 | [`ptc-runtime/`](ptc-runtime/README.md) | PTC execution capability family: Service Definition + sandboxed Node provider + PTC mode Consumer |
 | [`computer-use/`](computer-use/README.md) | Exclusive named desktop-provider registration |
 | [`browser-use/`](browser-use/README.md) | Exclusive named browser-provider registration |
@@ -53,9 +53,8 @@ Every package lives in exactly one group; new packages join existing groups, and
 | [`context/`](context/README.md) | Model-visible request context: workspace instructions, time context, references |
 | [`subagent/`](subagent/README.md) | Subagent capability family: provider-registry contract and model-facing delegation tools |
 | [`jobs/`](jobs/README.md) | Generic background-job runtime and model-facing job control tools |
-| [`experimental/`](experimental/README.md) | Pre-stable prototypes with explicit private exceptions |
-| [`workflow/`](workflow/README.md) | Workflow seam, PTC process engine, and model-facing `workflow`/`ralph` tools |
-| [`webhook/`](webhook/README.md) | Verified external events, trusted rules, and fire-and-forget Workspace Sessions |
+| [`experimental/`](experimental/README.md) | Capabilities under evaluation; [status and support policy](experimental/README.md#status) |
+| [`workflow/`](workflow/README.md) | Workflow seam, PTC process engine, and the model-facing `workflow` tool |
 | [`web/`](web/README.md) | Web capability family: seam, search/fetch providers, model-facing web tools |
 | [`document/`](document/README.md) | Shared Host Office-to-PDF conversion |
 | [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage |
@@ -67,7 +66,6 @@ Every package lives in exactly one group; new packages join existing groups, and
 | [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers |
 | [`extensions/`](extensions/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written mount/unmount |
 | [`mcp/`](mcp/README.md) | External Model Context Protocol servers exposed as native tools |
-| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library |
 | [`session/`](session/README.md) | Durable session data plane: persistence seam + backends, projection seam, log-backed titles, session reporting |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, semantic filtering, SQLite full-text search |
 | [`settings/`](settings/README.md) | User-settings seam + file-backed provider |
@@ -88,7 +86,7 @@ Every package lives in exactly one group; new packages join existing groups, and
 <a id="release-expectations"></a>
 ## Release expectations
 
-Most groups are product — stable API. The exceptions: `experimental/` publishes without stability or support promises, and `test-support/` and `util/` are support with lower compatibility expectations.
+Product groups have maintained product roles, while their public APIs remain pre-stable. [Experimental status](experimental/README.md#status) is independent of publication, installation, and optional delivery. Nonexperimental runtime packages must have product use or an explicit [package classification](../scripts/product-package-policy.ts); SDK, build, test, and declaration infrastructure have separate classifications.
 
 -----
 

package/references/official-docs/website-docs.ts

@@ -409,6 +409,7 @@ const reference = [
     ['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
     ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
+    ['docs/experimental-persistence-catalog.md', 'reference/experimental-persistence-catalog.md', '实验性持久化记录', 'Experimental persistence'],
   ] as const).map(([source, route, rootLabel, enLabel, outline], order): PairedPage => ({
     source,
     route,

package/references/official-plugin-dev-skill.md

@@ -2,7 +2,7 @@
 
 > **这是什么**：DeepSeek Harness 自带的 preset（`packages/preset/agent-preset/`）里有一整套**官方插件开发技能**，是 0.2 世代最重要的新增资料——它描述的正是"在当前 Harness 里、由 agent 自己写并安装插件"的官方流程。
 > **本文件性质**：**要点摘录 + 原文定位**（不是逐字全文；逐字全文随官方文档副本一起在 `references/official-docs/` 之外的仓库路径，需 checkout 才能读）。凡写"官方明确"的地方都能在上游文件里逐字查到。
-> **基线**：`5badb15009ae1756c3afe0ae0cef1faafc290ccc`（`dsh-v0.2.1-alpha.1`，2026-10-03）。升级宿主后若与上游冲突，以上游为准。
+> **基线**：`d743267388641bc76f17c45ce8b4c231aed1d32c`（`dsh-v0.2.1-alpha.2`，2026-10-09）。升级宿主后若与上游冲突，以上游为准。
 > **上游路径**（在 checkout 里，如 `D:\deepseek-harness`）：`packages/preset/agent-preset/skills/`
 
 ## 1. 四个技能与各自职责
@@ -121,4 +121,4 @@
 
 - 本文件是**索引与摘录**；机制细节（精确签名、事件 `@mode`、Config schema）永远以 **inspection** 与 `references/official-docs/docs/**` 为准。
 - 官方这份技能覆盖"在会话里让 agent 写并安装插件"；本知识库另外覆盖**对外发布**（npm/tarball/git 通道、`prepare` + `allowBuilds`、五语 README、质量门禁）与**版本迁移**（[migration-0.2.md](../guide/migration-0.2.md)）。
-- 上游路径随宿主版本变化（本文件基线 `5badb15009`）；`preset/agent-presets` → `preset/agent-preset` 的改名发生在 `d1e22a7e24`。
+- 上游路径随宿主版本变化（本文件基线 `d743267`）；`preset/agent-presets` → `preset/agent-preset` 的改名发生在 `d1e22a7e24`。

package/references/sources.md

@@ -33,7 +33,7 @@
 
 ## C. 本地 checkout 文档副本（references/official-docs/）
 
-- `docs/**`（**369 个 md**，含 182 个 `.zh.md` 双语对）— 教程/架构/子系统/API/cookbook/upgrade-guide/persistence-changes 全量（计数以 `references/official-docs/SNAPSHOT.md` 为准）
+- `docs/**`（**429 个 md**，含 212 个 `.zh.md` 双语对；2026-10-13 重同步到 `dsh-v0.2.1-alpha.2`）— 教程/架构/子系统/API/cookbook/upgrade-guide/persistence-changes 全量（计数以 `references/official-docs/SNAPSHOT.md` 为准）
 - 仓库根文件（**2026-08-14 晚新增**）：`AGENTS.md`、`CLAUDE.md`（上游为 symlink→AGENTS.md，副本存其目标文本）、`BENCHMARK.md`、`CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`、`README.zh.md`/`.i18n.yaml`、`THIRD_PARTY_NOTICES.md`、`LICENSE`
 - `packages/AGENTS.md` · `packages/README.md` · `vendor/README.md`
 - `website-docs.ts`（站点投影清单）
@@ -122,6 +122,7 @@
 - 重跑：脚本均幂等，可随时刷新；`sync-official-docs.ps1` 同步官方文档副本（本次扩展了根文件范围与 `:(top)` pathspec/修剪）。
 - **08-14 晚环境限制记录**：`gh` CLI token 失效（401）后，GitHub 全部查询改走 git 协议（ls-remote/clone）与 codeload；api.github.com 匿名配额 60/h 仅用于 Discussions 评论精选抓取；本机网络直连 github.com 网页与 raw.githubusercontent.com 失败（curl 000），git https 与 codeload 正常。
 - **编码约定（重要）**：Windows PowerShell 5.1 无 BOM 的 UTF-8 脚本会按 ANSI 解析，中文注释尾字节可能吞换行导致代码行并入注释（本次真实踩坑）；`scripts/*.ps1` 必须保持 **UTF-8 with BOM**，编辑后务必复核 BOM。
+  - **2026-10-13 复核（约定被违反的实例）**：实测 `scripts/` 下 9 个 `.ps1`，**8 个带 BOM 且 5.1 解析 0 错**；唯一无 BOM 的 `verify-kit.ps1` 有 **1644 个非 ASCII 字节**、在 5.1 下报 **5–6 个解析错误**（`Missing ')' in method call`）——**而它正是发布门禁**（`release.yml` 用 `shell: pwsh` 调它，所以 CI 从没发现；本机没有 pwsh 时才暴露）。已补回 BOM 并实测 `VERIFY-OK` / exit 0（82 项关键路径全在）。**根因不是约定错，而是这一个文件丢了 BOM**——另加 `.gitattributes` 固定行尾，避免同类问题复现。
 - 时间戳：下载会话 2026-08-14 22:45–23:59（+08:00）；dsh-plugin topic 快照共三期（2026-08-13T15:15Z/08-13T18:36Z/08-14T08:16Z）+ 08-14 晚扫描（total_count 2034，见 §D.2）。
 - 官网 deepseek.com 页面受 Cloudflare 保护时可能失败——以 manifest 记录为准，正文内容以 GitHub Pages 同源文档为准。
 - **备注**：用户清单中 `ess-plugin-mcp` 经 GitHub 搜索无精确匹配（最接近者为 Skyrim .ess 插件工具的 MCP，与 DSH 无关）；按 DSH 生态语义定位到 `bobleer/deepseek-harness-plugin-mcp`（让任意 agent 经 MCP 发现/安装/运行 DSH 插件）并归档，如用户所指另有其仓，请告知后补充。

package/scripts/archive-discussions.ps1

@@ -1,162 +1,162 @@
-# dsh-plugin-guide 官方 GitHub Discussions 归档脚本（可复跑，幂等）
-# 输出: downloads/github/harness/discussions/
-#   list.json          全部讨论（title/body/category/answers/labels 等，正文即文档）
-#   comments-<n>.json  精选线程的全部评论（选择规则见下）
-#   _selection.tsv     精选线程清单
-#   README.md          分类统计 + 精选清单
-# 说明: GitHub REST API;未提供 Token 时走匿名配额(60/h,可能不够),建议
-#   $env:GH_TOKEN 或 -Token <token>(经典 PAT,只需 public_repo 读权限)。
-#   选择规则(与 08-14 首版覆盖度一致): Announcements 全部; Q&A/Ideas 评论>=1;
-#   General/Show and tell 评论>=3 且标题不含拉群/招聘/广告词。
-#   传输用 Invoke-WebRequest(而非 curl.exe 数组参数): PS 5.1 下 curl 数组参数
-#   的引号拆分会把 -H 头打碎,导致静默拿到错误对象——本脚本已规避该坑。
-# 参数: -OutDir <dir> 覆盖输出目录; -SkipComments 只刷新 list.json 不拉评论。
-param(
-  [string]$OutDir = '',
-  [string]$Repo = 'deepseek-ai/deepseek-harness',
-  [string]$Token = $env:GH_TOKEN,
-  [switch]$SkipComments
-)
-$ErrorActionPreference = 'Stop'
-$ProgressPreference = 'SilentlyContinue'
-if (-not $OutDir) { $OutDir = Join-Path (Split-Path $PSScriptRoot -Parent) 'downloads\github\harness\discussions' }
-New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
-
-$headers = @{ 'User-Agent' = 'dsh-plugin-guide-research'; 'Accept' = 'application/vnd.github+json' }
-if ($Token) { $headers['Authorization'] = "Bearer $Token" }
-
-function Get-Api([string]$url) {
-  # 返回对象数组;失败/限流时抛错(带状态码),由调用方决定重试或中止。
-  try {
-    $resp = Invoke-WebRequest -Uri $url -Headers $headers -TimeoutSec 60 -UseBasicParsing
-  } catch {
-    $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
-    throw "HTTP $code : $url"
-  }
-  $obj = $null
-  try { $obj = $resp.Content | ConvertFrom-Json } catch { throw "JSON parse failed: $url" }
-  if ($obj -is [System.Management.Automation.PSCustomObject] -and $obj.PSObject.Properties.Name -contains 'message') {
-    throw "API message '$($obj.message)' : $url"
-  }
-  return @($obj)
-}
-
-# ---- 1) 全量 list(按创建序分页;REST 的 direction 参数对 discussions 无效,只能从头翻到尾) ----
-$prevCount = 0
-if (Test-Path (Join-Path $OutDir 'list.json')) {
-  try { $prev = @((Get-Content (Join-Path $OutDir 'list.json') -Raw -Encoding UTF8 | ConvertFrom-Json)); $prevCount = $prev.Count } catch { $prevCount = 0 }
-}
-$all = @()
-$page = 1
-# REST /discussions caps at 5000 rows (50 pages x 100). The cap is explicit so a
-# silent truncation cannot be mistaken for a complete archive: the run reports
-# when it stops at the ceiling, and the README records the ceiling alongside the
-# GraphQL total_count (which is larger).
-$pageCap = 50
-while ($page -le $pageCap) {
-  $items = Get-Api "https://api.github.com/repos/$Repo/discussions?per_page=100&page=$page&sort=created"
-  if ($items.Count -eq 0) { Write-Output "page ${page}: 空页,列表结束"; break }
-  $all += $items
-  Write-Output ("page {0}: +{1} (累计 {2})" -f $page, $items.Count, $all.Count)
-  if ($items.Count -lt 100) { break }
-  $page++
-  Start-Sleep -Milliseconds 500
-}
-if ($all.Count -ge ($pageCap * 100)) {
-  Write-Output "WARN: 列表在第 $pageCap 页触顶(REST 5000 条上限)——归档为前 5000 条,非全量;更全的历史需按 GraphQL UPDATED_AT 分页补抓"
-}
-if ($all.Count -eq 0) { throw 'discussions 列表抓取失败(0 条)' }
-if ($prevCount -gt 0 -and $all.Count -lt [Math]::Floor($prevCount * 0.9)) {
-  throw "列表疑似缩水: 上次 $prevCount 条, 本次仅 $all.Count 条 —— 拒绝覆盖归档,请检查网络/配额后重跑"
-}
-
-# 按 number 去重(分页边界可能重复)
-$uniq = @{}
-foreach ($d in $all) { $uniq[[int]$d.number] = $d }
-$discs = @($uniq.Values | Sort-Object { [int]$_.number })
-$listPath = Join-Path $OutDir 'list.json'
-$discs | ConvertTo-Json -Depth 6 | Set-Content -Path $listPath -Encoding UTF8
-Write-Output "list.json: $($discs.Count) 条 -> $listPath"
-
-# ---- 2) 精选线程 + 评论 ----
-$sel = @()
-foreach ($d in $discs) {
-  $cat = $d.category.name
-  $c = [int]$d.comments
-  $t = [string]$d.title
-  $pick = $false
-  if ($cat -eq 'Announcements') { $pick = $true }
-  elseif ($cat -eq 'Q&A' -and $c -ge 1) { $pick = $true }
-  elseif ($cat -eq 'Ideas' -and $c -ge 1) { $pick = $true }
-  elseif (($cat -eq 'General' -or $cat -eq 'Show and tell') -and $c -ge 3) {
-    # 非社群拉群帖: 标题含拉群/扫码/加群/招聘/广告类词的不收
-    if ($t -notmatch '群|扫码|加群|招聘|内推|广告|投简历|纳新') { $pick = $true }
-  }
-  if ($pick) { $sel += $d }
-}
-$sel = @($sel | Sort-Object { [int]$_.number })
-Write-Output "精选线程: $($sel.Count) 条"
-
-if (-not $SkipComments) {
-  $n = 0
-  foreach ($d in $sel) {
-    $num = [int]$d.number
-    $comments = @()
-    $cp = 1
-    while ($cp -le 20) {
-      $ci = Get-Api "https://api.github.com/repos/$Repo/discussions/$num/comments?per_page=100&page=$cp"
-      if ($ci.Count -eq 0) { break }
-      $comments += $ci
-      if ($ci.Count -lt 100) { break }
-      $cp++
-      Start-Sleep -Milliseconds 300
-    }
-    $comments | ConvertTo-Json -Depth 6 | Set-Content -Path (Join-Path $OutDir "comments-$num.json") -Encoding UTF8
-    $n++
-    if ($n % 20 -eq 0) { Write-Output "comments: $n / $($sel.Count)" }
-    Start-Sleep -Milliseconds 200
-  }
-  Write-Output "comments: 完成 $n 个线程"
-  # 清掉列表里已不存在的旧 comments 文件
-  $keep = New-Object System.Collections.Generic.HashSet[string]
-  foreach ($d in $sel) { [void]$keep.Add("comments-$([int]$d.number).json") }
-  Get-ChildItem $OutDir -Filter 'comments-*.json' | Where-Object { -not $keep.Contains($_.Name) } | Remove-Item -Force
-} else {
-  Write-Output 'comments: 跳过(-SkipComments)'
-}
-
-# ---- 3) _selection.tsv 与 README.md ----
-$selLines = @('number' + "`t" + 'category' + "`t" + 'comments' + "`t" + 'title')
-foreach ($d in $sel) { $selLines += ("{0}`t{1}`t{2}`t{3}" -f $d.number, $d.category.name, $d.comments, ($d.title -replace "`t",' ')) }
-Set-Content -Path (Join-Path $OutDir '_selection.tsv') -Value $selLines -Encoding UTF8
-
-$cats = @{}
-foreach ($d in $discs) { $k = [string]$d.category.name; if (-not $cats.ContainsKey($k)) { $cats[$k] = 0 }; $cats[$k]++ }
-$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
-$L = @()
-$L += '# 官方 GitHub Discussions 归档（自动生成，见抓取时间）'
-$L += ''
-$L += '> 来源：https://github.com/deepseek-ai/deepseek-harness/discussions （官方仓库 Issues 关闭，Discussions 为反馈主渠道）。'
-$L += '> 抓取：GitHub REST API（list 含每条正文；comments-<n>.json 为精选线程的全部评论）。'
-$L += "> 更新：提供 ``GH_TOKEN`` 后可由 ``scripts/archive-discussions.ps1`` 幂等刷新；抓取时间 $utc (UTC)。"
-$L += ''
-$L += '## 文件'
-$L += ''
-$L += "- list.json — 全部 $($discs.Count) 条讨论（含 title/body/category/answers/labels 等字段，正文即模型可读文档）。"
-$L += "- comments-<n>.json — 精选 $($sel.Count) 条线程的评论（选择规则：Announcements/Q&A/Ideas 评论>=1；General/Show and tell 评论>=3 且非社群拉群帖）。"
-$L += '- _selection.tsv — 精选线程清单（编号/分类/评论数/标题）。'
-$L += ''
-$L += '## 分类统计'
-$L += ''
-foreach ($k in @($cats.Keys | Sort-Object)) { $L += "- $k：$($cats[$k]) 条" }
-$L += ''
-$L += '## 有归档评论的精选线程'
-$L += ''
-$L += '| # | 分类 | 评论 | 标题 |'
-$L += '|---|---|---|---|'
-foreach ($d in $sel) {
-  $title = ($d.title -replace '\|','\|' -replace "[\r\n]",' ')
-  $L += "| [#$($d.number)](https://github.com/deepseek-ai/deepseek-harness/discussions/$($d.number)) | $($d.category.name) | $($d.comments) | $title |"
-}
-Set-Content -Path (Join-Path $OutDir 'README.md') -Value ($L -join "`r`n") -Encoding UTF8
-Write-Output "DONE: list=$($discs.Count) selected=$($sel.Count) -> $OutDir"
+# dsh-plugin-guide 官方 GitHub Discussions 归档脚本（可复跑，幂等）
+# 输出: downloads/github/harness/discussions/
+#   list.json          全部讨论（title/body/category/answers/labels 等，正文即文档）
+#   comments-<n>.json  精选线程的全部评论（选择规则见下）
+#   _selection.tsv     精选线程清单
+#   README.md          分类统计 + 精选清单
+# 说明: GitHub REST API;未提供 Token 时走匿名配额(60/h,可能不够),建议
+#   $env:GH_TOKEN 或 -Token <token>(经典 PAT,只需 public_repo 读权限)。
+#   选择规则(与 08-14 首版覆盖度一致): Announcements 全部; Q&A/Ideas 评论>=1;
+#   General/Show and tell 评论>=3 且标题不含拉群/招聘/广告词。
+#   传输用 Invoke-WebRequest(而非 curl.exe 数组参数): PS 5.1 下 curl 数组参数
+#   的引号拆分会把 -H 头打碎,导致静默拿到错误对象——本脚本已规避该坑。
+# 参数: -OutDir <dir> 覆盖输出目录; -SkipComments 只刷新 list.json 不拉评论。
+param(
+  [string]$OutDir = '',
+  [string]$Repo = 'deepseek-ai/deepseek-harness',
+  [string]$Token = $env:GH_TOKEN,
+  [switch]$SkipComments
+)
+$ErrorActionPreference = 'Stop'
+$ProgressPreference = 'SilentlyContinue'
+if (-not $OutDir) { $OutDir = Join-Path (Split-Path $PSScriptRoot -Parent) 'downloads\github\harness\discussions' }
+New-Item -ItemType Directory -Force -Path $OutDir | Out-Null
+
+$headers = @{ 'User-Agent' = 'dsh-plugin-guide-research'; 'Accept' = 'application/vnd.github+json' }
+if ($Token) { $headers['Authorization'] = "Bearer $Token" }
+
+function Get-Api([string]$url) {
+  # 返回对象数组;失败/限流时抛错(带状态码),由调用方决定重试或中止。
+  try {
+    $resp = Invoke-WebRequest -Uri $url -Headers $headers -TimeoutSec 60 -UseBasicParsing
+  } catch {
+    $code = if ($_.Exception.Response) { [int]$_.Exception.Response.StatusCode } else { 0 }
+    throw "HTTP $code : $url"
+  }
+  $obj = $null
+  try { $obj = $resp.Content | ConvertFrom-Json } catch { throw "JSON parse failed: $url" }
+  if ($obj -is [System.Management.Automation.PSCustomObject] -and $obj.PSObject.Properties.Name -contains 'message') {
+    throw "API message '$($obj.message)' : $url"
+  }
+  return @($obj)
+}
+
+# ---- 1) 全量 list(按创建序分页;REST 的 direction 参数对 discussions 无效,只能从头翻到尾) ----
+$prevCount = 0
+if (Test-Path (Join-Path $OutDir 'list.json')) {
+  try { $prev = @((Get-Content (Join-Path $OutDir 'list.json') -Raw -Encoding UTF8 | ConvertFrom-Json)); $prevCount = $prev.Count } catch { $prevCount = 0 }
+}
+$all = @()
+$page = 1
+# REST /discussions caps at 5000 rows (50 pages x 100). The cap is explicit so a
+# silent truncation cannot be mistaken for a complete archive: the run reports
+# when it stops at the ceiling, and the README records the ceiling alongside the
+# GraphQL total_count (which is larger).
+$pageCap = 50
+while ($page -le $pageCap) {
+  $items = Get-Api "https://api.github.com/repos/$Repo/discussions?per_page=100&page=$page&sort=created"
+  if ($items.Count -eq 0) { Write-Output "page ${page}: 空页,列表结束"; break }
+  $all += $items
+  Write-Output ("page {0}: +{1} (累计 {2})" -f $page, $items.Count, $all.Count)
+  if ($items.Count -lt 100) { break }
+  $page++
+  Start-Sleep -Milliseconds 500
+}
+if ($all.Count -ge ($pageCap * 100)) {
+  Write-Output "WARN: 列表在第 $pageCap 页触顶(REST 5000 条上限)——归档为前 5000 条,非全量;更全的历史需按 GraphQL UPDATED_AT 分页补抓"
+}
+if ($all.Count -eq 0) { throw 'discussions 列表抓取失败(0 条)' }
+if ($prevCount -gt 0 -and $all.Count -lt [Math]::Floor($prevCount * 0.9)) {
+  throw "列表疑似缩水: 上次 $prevCount 条, 本次仅 $all.Count 条 —— 拒绝覆盖归档,请检查网络/配额后重跑"
+}
+
+# 按 number 去重(分页边界可能重复)
+$uniq = @{}
+foreach ($d in $all) { $uniq[[int]$d.number] = $d }
+$discs = @($uniq.Values | Sort-Object { [int]$_.number })
+$listPath = Join-Path $OutDir 'list.json'
+$discs | ConvertTo-Json -Depth 6 | Set-Content -Path $listPath -Encoding UTF8
+Write-Output "list.json: $($discs.Count) 条 -> $listPath"
+
+# ---- 2) 精选线程 + 评论 ----
+$sel = @()
+foreach ($d in $discs) {
+  $cat = $d.category.name
+  $c = [int]$d.comments
+  $t = [string]$d.title
+  $pick = $false
+  if ($cat -eq 'Announcements') { $pick = $true }
+  elseif ($cat -eq 'Q&A' -and $c -ge 1) { $pick = $true }
+  elseif ($cat -eq 'Ideas' -and $c -ge 1) { $pick = $true }
+  elseif (($cat -eq 'General' -or $cat -eq 'Show and tell') -and $c -ge 3) {
+    # 非社群拉群帖: 标题含拉群/扫码/加群/招聘/广告类词的不收
+    if ($t -notmatch '群|扫码|加群|招聘|内推|广告|投简历|纳新') { $pick = $true }
+  }
+  if ($pick) { $sel += $d }
+}
+$sel = @($sel | Sort-Object { [int]$_.number })
+Write-Output "精选线程: $($sel.Count) 条"
+
+if (-not $SkipComments) {
+  $n = 0
+  foreach ($d in $sel) {
+    $num = [int]$d.number
+    $comments = @()
+    $cp = 1
+    while ($cp -le 20) {
+      $ci = Get-Api "https://api.github.com/repos/$Repo/discussions/$num/comments?per_page=100&page=$cp"
+      if ($ci.Count -eq 0) { break }
+      $comments += $ci
+      if ($ci.Count -lt 100) { break }
+      $cp++
+      Start-Sleep -Milliseconds 300
+    }
+    $comments | ConvertTo-Json -Depth 6 | Set-Content -Path (Join-Path $OutDir "comments-$num.json") -Encoding UTF8
+    $n++
+    if ($n % 20 -eq 0) { Write-Output "comments: $n / $($sel.Count)" }
+    Start-Sleep -Milliseconds 200
+  }
+  Write-Output "comments: 完成 $n 个线程"
+  # 清掉列表里已不存在的旧 comments 文件
+  $keep = New-Object System.Collections.Generic.HashSet[string]
+  foreach ($d in $sel) { [void]$keep.Add("comments-$([int]$d.number).json") }
+  Get-ChildItem $OutDir -Filter 'comments-*.json' | Where-Object { -not $keep.Contains($_.Name) } | Remove-Item -Force
+} else {
+  Write-Output 'comments: 跳过(-SkipComments)'
+}
+
+# ---- 3) _selection.tsv 与 README.md ----
+$selLines = @('number' + "`t" + 'category' + "`t" + 'comments' + "`t" + 'title')
+foreach ($d in $sel) { $selLines += ("{0}`t{1}`t{2}`t{3}" -f $d.number, $d.category.name, $d.comments, ($d.title -replace "`t",' ')) }
+Set-Content -Path (Join-Path $OutDir '_selection.tsv') -Value $selLines -Encoding UTF8
+
+$cats = @{}
+foreach ($d in $discs) { $k = [string]$d.category.name; if (-not $cats.ContainsKey($k)) { $cats[$k] = 0 }; $cats[$k]++ }
+$utc = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+$L = @()
+$L += '# 官方 GitHub Discussions 归档（自动生成，见抓取时间）'
+$L += ''
+$L += '> 来源：https://github.com/deepseek-ai/deepseek-harness/discussions （官方仓库 Issues 关闭，Discussions 为反馈主渠道）。'
+$L += '> 抓取：GitHub REST API（list 含每条正文；comments-<n>.json 为精选线程的全部评论）。'
+$L += "> 更新：提供 ``GH_TOKEN`` 后可由 ``scripts/archive-discussions.ps1`` 幂等刷新；抓取时间 $utc (UTC)。"
+$L += ''
+$L += '## 文件'
+$L += ''
+$L += "- list.json — 全部 $($discs.Count) 条讨论（含 title/body/category/answers/labels 等字段，正文即模型可读文档）。"
+$L += "- comments-<n>.json — 精选 $($sel.Count) 条线程的评论（选择规则：Announcements/Q&A/Ideas 评论>=1；General/Show and tell 评论>=3 且非社群拉群帖）。"
+$L += '- _selection.tsv — 精选线程清单（编号/分类/评论数/标题）。'
+$L += ''
+$L += '## 分类统计'
+$L += ''
+foreach ($k in @($cats.Keys | Sort-Object)) { $L += "- $k：$($cats[$k]) 条" }
+$L += ''
+$L += '## 有归档评论的精选线程'
+$L += ''
+$L += '| # | 分类 | 评论 | 标题 |'
+$L += '|---|---|---|---|'
+foreach ($d in $sel) {
+  $title = ($d.title -replace '\|','\|' -replace "[\r\n]",' ')
+  $L += "| [#$($d.number)](https://github.com/deepseek-ai/deepseek-harness/discussions/$($d.number)) | $($d.category.name) | $($d.comments) | $title |"
+}
+Set-Content -Path (Join-Path $OutDir 'README.md') -Value ($L -join "`r`n") -Encoding UTF8
+Write-Output "DONE: list=$($discs.Count) selected=$($sel.Count) -> $OutDir"

package/scripts/build-llms-full.mjs

@@ -18,13 +18,21 @@ const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
 // Reading order: what a plugin author needs first, then the evidence base.
 const SOURCES = [
   ['README.md', 'Overview'],
+  // SKILL.md first among the authored docs: it carries the contract red lines,
+  // and llms-full previously omitted it entirely.
+  ['SKILL.md', 'Agent skill: contract red lines and task-based development paths'],
+  ['guide/version-matrix.md', 'Version adaptivity matrix (latest values, seams, peer ranges, session format)'],
   ['guide/plugin-dev-guide.md', 'Plugin development guide (10 chapters)'],
   ['guide/quick-reference.md', 'Quick reference'],
+  ['guide/migration-0.2.md', 'Migration to the 0.2 generation (breaking changes)'],
+  ['guide/family-toolchain.md', 'Family toolchain router (check catalogs and crosswalk)'],
   ['guide/when-to-retire-a-plugin.md', 'When to retire or freeze a plugin'],
   ['guide/choosing-a-plugin.md', 'Choosing a plugin: who leads each capability surface'],
   ['guide/release-engineering.md', 'Release engineering'],
   ['guide/unfixed-issues.md', 'Unfixed upstream issues (source-verified)'],
   ['guide/links.md', 'Curated links'],
+  ['references/official-plugin-dev-skill.md', 'Distilled official in-repo plugin-development skill'],
+  ['references/dev-resource-landscape.md', 'Competing and adjacent plugin-development resources'],
   ['references/harness-repo.md', 'Harness repository reference'],
   ['references/upstream-cordis.md', 'Upstream Cordis reference'],
   ['references/cordis-paper-and-community.md', 'Cordis paper and community'],