dsh-plugin-guide 0.3.29 → 0.3.30

package/README.md

@@ -60,7 +60,7 @@ content counts as stated in the README (What you get)
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2` (`d743267388641bc76f17c45ce8b4c231aed1d32c`, the newest master tag **and** master HEAD, 2026-10-09); npm `latest` = `next` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.2`. **There is no stable line** — all 31 npm versions and all 26 GitHub Releases are prereleases. The official-docs mirror and `guide/migration-0.2.md` are pinned one release back, at `dsh-v0.2.1-alpha.1` (`5badb15009`, 2026-10-03); the 20 breaking-change guides added since are captured in [guide/version-matrix.md](guide/version-matrix.md) §3. |
+| Harness | DeepSeek Harness `dsh-v0.2.1-alpha.2` (`d743267388641bc76f17c45ce8b4c231aed1d32c`, the newest master tag **and** master HEAD, 2026-10-09); npm `latest` = `next` = `0.2.0-rc.2`, `alpha` = `0.2.1-alpha.2`. **There is no stable line** — all 31 npm versions and all 26 GitHub Releases are prereleases. The official-docs mirror is pinned to that same commit (429 md pages, re-synced 2026-10-13; see [references/official-docs/SNAPSHOT.md](references/official-docs/SNAPSHOT.md)). `guide/migration-0.2.md` covers `0.1.6-alpha.2` → `0.2.1-alpha.1` in §0–§12 and `0.2.1-alpha.1` → `0.2.1-alpha.2` as 19 citable seams in §13; the 20 breaking-change guides added since the previous baseline (19 under `v0.2.1-alpha.1` plus one backfilled into `v0.2.0-rc.2`) are all in the mirror. |
 | Node | `^22.19.0 || >=24.0.0` (DeepSeek Harness runtime) |
 | Platforms | All (plain ESM bundle; no native code, no network) |
 | Model | Any (no model interaction) |

package/SKILL.md

@@ -19,7 +19,14 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## 开发前置（第一步必做）
 
-0. **先认版本**：`dsh --version`，然后读 `guide/version-matrix.md`（**版本适配矩阵**：五个"最新"的区分、子包 `latest` 冻结陷阱、破坏性变更断层、peer 区间选择、会话格式谱系）。要点：`0.1.7-alpha.1`（2026-09-22）起包含本世代全部破坏性变更（会话格式 V4、settings 重写、`readBytes`、Messages-only 适配器）；**npm `latest`=`0.2.0-rc.2`、`next`=`0.2.0-rc.2`、`alpha`=`0.2.1-alpha.2`，而 master 最新 tag 是 `dsh-v0.2.1-alpha.2`——这四个"最新"不是同一个东西**。**不存在稳定版**：全部 31 个 npm 版本都是 prerelease。目标宿主不是 matrix 基线时，按 `guide/migration-0.2.md` 逐条对照；目标宿主**更新**（如 `0.2.1-alpha.2`）时另见 `guide/version-matrix.md` §3 的 19 条新破坏性变更。
+0. **先认版本**：跑 `dsh --version`，然后按下表决定读什么。**不要跳过这一步**——本库 17 篇文档里对当前宿主不适用的部分不会自己标注。
+   | 你的 `dsh --version` | 含义 | 读什么 |
+   |---|---|---|
+   | `< 0.1.7-alpha.1` | 旧基线 | 本世代破坏性变更**全部适用** → `guide/migration-0.2.md` §0–§12 逐条改 |
+   | `0.1.7-alpha.1` – `0.2.1-alpha.1` | 中间线 | 会话格式 V4 已生效；§13 的 19 条**不适用** |
+   | `0.2.1-alpha.2` 或更新 | 最新线 | §13 的 19 条**适用** → `guide/version-matrix.md` §3 |
+   | **npm `latest`（= `0.2.0-rc.2`）** | **默认安装拿到的就是这一版** | ⚠️ 它**早于** master 一版：§13 不适用，但 `version-matrix.md` §1.1 的"不存在稳定版"警告适用 |
+   **四个"最新"不是同一个东西**：npm `latest`=`next`=`0.2.0-rc.2`、npm `alpha`=`0.2.1-alpha.2`、master 最新 tag = `dsh-v0.2.1-alpha.2`。**不存在稳定版**（全部 31 个 npm 版本都是 prerelease）。完整谱系、子包 `latest` 冻结陷阱与 peer 区间选择见 `guide/version-matrix.md`。
 1. 若未读过 Cordis 概念：读 `references/official-docs/docs/cordis-primer.md`（5 个概念，5 分钟）；需要动手跟练时跑 `references/official-docs/docs/cordis-tutorial/` 01-07（无 API key 可跑）。
 2. 打开 `guide/quick-reference.md`（契约速查）+ `guide/plugin-dev-guide.md`（完整路径）。官方/社区文档 URL 对照见 `guide/links.md`。排查官方运行时行为/未修复 bug 时查 `guide/unfixed-issues.md`（master 基线源码核实的问题清单 + 已修复提交号 + 设计行为对照 + 本世代新核实的 T1–T11）。决定一个插件**该不该继续维护**（官方已进内核 / 第三方采用度显著更高）时查 `guide/when-to-retire-a-plugin.md`（判据 + 实测倍数表）；判断某个能力面谁领先时查 `guide/choosing-a-plugin.md`。
 2b. **要判断"该改哪一行 / 该找哪个工具"时**，读 `guide/family-toolchain.md`（家族工具链路由：问题→所有者→可引用产物；`dsh-plugin-doctor` 33 项检查全表与裁定语义；本库 16 项检查与 doctor 的交叉对照）。发布流水线（多插件组合的持续可安装/可发布/可升级）见 `guide/release-engineering.md`。
@@ -55,7 +62,7 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 - **新服务/能力**：`docs/user/develop/framework/service.md` + `docs/user/develop/practice/`（三层拆分完整代码）。
 - **拦截/策略/hook**：`docs/cookbook/extension-cookbook.md`（permission-gate 范例）+ `docs/event-producer-consumer.md`（全事件矩阵）。
 - **新 LLM 提供商**：`docs/user/develop/practice/llm-adapter.md`（StreamChunk 协议）。
-- **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、`ui-radius.md`；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
+- **UI 插件（Web）**：`references/official-plugin-dev-skill.md` §3.2 + `docs/subsystems/slots.md`、`sidebar-right.md`、`client-modules.md`、`web-client.md`、**`docs/ui-radius.md`**（注意 `ui-radius` 在 `docs/` 顶层，**不在** `docs/subsystems/` 下）；Chat 行业务节点用 `ctx.uiConversation.events.register()` + `conversation.chat.node` slot。
 - **插件配置表单**：`docs/subsystems/settings.md`（已改名 "Plugin Configuration Forms"）+ `docs/cookbook/adding-a-settings-card.md`（已重写）。
 - **打包/发布**：`docs/user/develop/basic/publish.md`（bundle/profile、层顺序、多 patch 数组、peer 解析、git 安装坑）。
 - **升级/迁移**：`guide/version-matrix.md`（**版本适配矩阵：先读这个**——五个"最新"、子包 `latest` 冻结、破坏性变更断层、peer 区间选择、会话格式 V0→V4）→ `guide/migration-0.2.md`（本库综述，0.1.6→0.2.1-alpha.1）→ `docs/upgrade-guide/**`（官方逐版本迁移指南）+ `docs/persistence-changes/**`（持久化类型变更记录）+ `docs/session-format-status.md`（会话格式版本权威）。⚠️ **目标宿主是 `0.2.1-alpha.2` 或更新时**：`version-matrix.md` §3 列了该版落的 **19 条破坏性变更**（`webRuntime`→`webStartup`、`mode: both` 被拒、`backgroundMode`/`run_in_background` 移除、`{{cwd}}` 移除、`BundleInfo` 新增必填字段、`dsh plugin --profile` 位置强制等），`migration-0.2.md` **尚未并入**。
@@ -82,11 +89,16 @@ description: Use when developing, reviewing, packaging, debugging, or answering
 
 ## CLI 工具链（dsh-plugin-dev）
 
-本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）：
+本仓库随 bundle 附带零依赖 CLI `dsh-plugin-dev`，把机械检查自动化（知识库仍是认知层，CLI 是机械层）。
 
-- `dsh-plugin-dev new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。
-- `dsh-plugin-dev check [--json] [--strict]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。
-- `dsh-plugin-dev verify`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
+> ⚠️ **调用方式**：`dsh-plugin-dev` **通常不在 PATH 上**（bundle 安装只登记技能，不安装二进制）。
+> 用本 SKILL.md 所在目录下的入口调用：`node "<resourceBase>/bin/dsh-plugin-dev.js" <子命令>`。
+> bundle 安装的包已带 `dist/`；从源码副本用则先跑一次 `pnpm run build`。
+> 只有全局 `npm i -g dsh-plugin-guide` 之后才可以直接敲 `dsh-plugin-dev`。
+
+- `new <name>`：参数化脚手架，生成 TS 或 JS 插件仓库骨架（`src/index.ts` 契约模板、Schemastery Config、tests、tsdown/vitest、注释齐全的 `cordis.patch.yml`、五语 README），模板与 `references/official-docs` 同步更新。标志：`--lang <ts|js>`、`--dir <path>`、`--force`、`--git`。
+- `check [--json] [--strict] [--cwd <dir>]`：静态检查（`cordis.patch.yml` 合法性、`package.json` 元数据（`dsh.bundle.patch` 指向/peer 依赖/engines/files 白名单）、五语 README 一致性、工程红线模式），输出 CI 可消费的结构化 JSON；每个检查项在输出里引用本知识库对应章节（skill 联动），agent 可继续人工审计。**这 16 项是同族 `dsh-plugin-doctor` 33 项的子集**（逐项对照见 `guide/family-toolchain.md` §3）；发布前建议两个都跑。
+- `verify [--cwd <dir>] [--base <spec>] [--headless <spec>] [--profile <name>]`：`pnpm pack` 后装入干净临时 `DSH_HOME` profile 做安装+启动+卸载冒烟（对齐官方 verify:self-contained）；失败给出日志尾部与建议。
 
 三个子命令均可逆/幂等；网络/子进程尊重超时与 AbortSignal；只清理自己 mkdtemp 的目录。CLI 零运行时依赖，构建产物经 tsdown 打包为单文件 `dist/dsh-plugin-dev.js`。
 

package/dist/dsh-plugin-dev.js

@@ -9,14 +9,31 @@ const LONG_ALIASES = {
 	help: "help",
 	version: "version"
 };
+/** Raised for a malformed or unrecognised argument. */
+var UsageError = class extends Error {};
 /**
 * Parse an argv slice (without the node/script prefix) into positionals and flags.
+*
+* `allowed` is the set of long flag names the caller accepts (aliases included).
+* Passing it turns an unrecognised flag into a `UsageError` instead of a silently
+* ignored one: `dsh-plugin-dev check --stirct` used to parse the typo, check
+* nothing extra, and exit 0 — a gate that can be disabled by a spelling mistake
+* is worse than no gate, because CI stays green and everyone believes it ran.
+*
 * @param argv - process.argv.slice(2) style input.
+* @param allowed - optional allowlist of accepted long flag names.
 * @returns the parsed structure.
 */
-function parseArgs(argv) {
+function parseArgs(argv, allowed) {
 	const positionals = [];
 	const flags = {};
+	const permitted = allowed ? new Set(allowed) : void 0;
+	const assertAllowed = (key) => {
+		if (permitted && !permitted.has(key)) {
+			const known = [...permitted].sort().join(", ");
+			throw new UsageError(`unknown option "--${key}" (accepted: ${known})`);
+		}
+	};
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (arg === "--") {
@@ -27,10 +44,13 @@ function parseArgs(argv) {
 			const body = arg.slice(2);
 			const eq = body.indexOf("=");
 			if (eq >= 0) {
-				setFlag(flags, body.slice(0, eq), body.slice(eq + 1));
+				const key = body.slice(0, eq);
+				assertAllowed(LONG_ALIASES[key] ?? key);
+				setFlag(flags, key, body.slice(eq + 1));
 				continue;
 			}
 			const key = body;
+			assertAllowed(LONG_ALIASES[key] ?? key);
 			const next = argv[i + 1];
 			if (next !== void 0 && !next.startsWith("-")) {
 				setFlag(flags, key, next);
@@ -39,7 +59,10 @@ function parseArgs(argv) {
 			continue;
 		}
 		if (arg.startsWith("-") && arg.length > 1) {
-			for (const ch of arg.slice(1)) flags[ch] = true;
+			for (const ch of arg.slice(1)) {
+				assertAllowed(ch);
+				flags[ch] = true;
+			}
 			continue;
 		}
 		positionals.push(arg);
@@ -909,7 +932,8 @@ function checkManifestFiles(_root, pkg) {
 	const problems = [];
 	for (const patchFile of patchFiles) if (!files.includes(patchFile)) problems.push(`files whitelist is missing the patch file "${patchFile}"`);
 	if (main && !files.includes(main) && !files.some((f) => main.startsWith(`${f.replace(/\/$/, "")}/`))) problems.push(`files whitelist is missing the main entry "${main}"`);
-	if (!files.some((f) => f === "lib" || f === "dist")) problems.push("files whitelist has no built-artifact directory (`lib` or `dist`)");
+	const entryDir = main?.includes("/") ? main.slice(0, main.indexOf("/")) : void 0;
+	if (entryDir && (entryDir === "lib" || entryDir === "dist") && !files.includes(entryDir)) problems.push(`files whitelist has no built-artifact directory ("${entryDir}"), but main points into it`);
 	if (problems.length > 0) return {
 		id: "manifest-files",
 		severity: "error",
@@ -1104,14 +1128,26 @@ function checkReadmeConsistency(root) {
 		skillRef: ref
 	};
 }
-/** Body of SKILL.md after its YAML frontmatter, or undefined. */
+/**
+* Body of SKILL.md after its YAML frontmatter, or undefined when the file is
+* absent. Falls back to the whole text when there is no well-formed block.
+*
+* CRLF tolerance is load-bearing: without `.gitattributes`, a Windows checkout
+* (`core.autocrlf=true`) delivers CRLF while CI and the published tarball
+* deliver LF. An exact `startsWith('---\n')` guard therefore failed locally,
+* leaving the frontmatter in the "body" — so `redline-persona-role` judged the
+* `name:` line as the opening paragraph and emitted a false warning on every
+* local run while CI stayed green. Keep this in step with `index.js`.
+*/
 function skillBody(root) {
 	const text = readText(join(root, "SKILL.md"));
 	if (!text) return void 0;
-	if (!text.startsWith("---\n")) return text;
-	const end = text.indexOf("\n---", 4);
-	if (end < 0) return text;
-	return text.slice(end + 4).replace(/^\n+/, "");
+	const open = /^---\r?\n/.exec(text);
+	if (!open) return text;
+	const rest = text.slice(open[0].length);
+	const close = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(rest);
+	if (!close) return text;
+	return rest.slice(close.index + close[0].length).replace(/^(?:[ \t]*\r?\n)+/, "");
 }
 function checkRedlinePersonaRole(root) {
 	const ref = skillRefFor("redline-persona-role");
@@ -1921,7 +1957,37 @@ function timeoutMs(flags, key, envKey, fallback) {
 * @param cwd - working directory (injectable for tests).
 */
 async function main(argv, cwd = process.cwd()) {
-	const { positionals, flags } = parseArgs(argv);
+	const KNOWN_FLAGS = [
+		"help",
+		"h",
+		"version",
+		"V",
+		"lang",
+		"dir",
+		"force",
+		"git",
+		"cwd",
+		"json",
+		"strict",
+		"dsh",
+		"pnpm",
+		"profile",
+		"base",
+		"headless",
+		"timeout",
+		"smoke-timeout"
+	];
+	let parsed;
+	try {
+		parsed = parseArgs(argv, KNOWN_FLAGS);
+	} catch (err) {
+		if (err instanceof UsageError) {
+			process.stderr.write(`dsh-plugin-dev: ${err.message}\n`);
+			return 2;
+		}
+		throw err;
+	}
+	const { positionals, flags } = parsed;
 	if (flagBool(flags, "version") || flags.V === true) {
 		process.stdout.write(`${readCliVersion()}\n`);
 		return 0;

package/index.d.ts

@@ -0,0 +1,32 @@
+// Type declarations for the bundle entry point (`index.js`).
+//
+// `index.js` is plain ESM JavaScript and is intentionally not part of the
+// TypeScript program (`tsconfig.json` includes only `src`, `tests` and the build
+// configs, with `allowJs` off). `tests/entry.test.ts` imports it, so without this
+// file `noImplicitAny` rejects the import as an untyped module.
+//
+// The declaration is deliberately loose: this module exists to be loaded by the
+// host's Cordis loader, not consumed as a typed library, and the shapes it
+// touches (`ctx.effect`, `ctx.skills.register`) belong to the harness rather
+// than to this package. Pinning them here would create a second, drifting copy
+// of the host contract — the exact failure mode `guide/family-toolchain.md`
+// warns about. The test asserts the runtime shape instead.
+
+/** Cordis plugin name contributed by this bundle. */
+export declare const name: string
+
+/** Services this plugin requires before `apply` runs. */
+export declare const inject: string[]
+
+/**
+ * Split a SKILL.md document into its frontmatter description and instruction
+ * body. Falls back to `{ description: undefined, body: text }` when there is no
+ * well-formed frontmatter block. Tolerates both LF and CRLF line endings.
+ */
+export declare function splitFrontmatter(text: string): {
+  description: string | undefined
+  body: string
+}
+
+/** Register the knowledge-base skill. Registration is an effect. */
+export declare function apply(ctx: any): void

package/index.js

@@ -21,18 +21,33 @@ const packageRoot = dirname(fileURLToPath(import.meta.url))
 
 /**
  * Strip the YAML frontmatter block from SKILL.md and return the description
- * plus the instruction body. A malformed or missing block fails loud through
- * the read itself or falls back to the full text as the body.
+ * plus the instruction body. A malformed or missing block falls back to the
+ * full text as the body.
+ *
+ * CRLF tolerance is deliberate and load-bearing, not cosmetic. Without
+ * `.gitattributes`, git's `core.autocrlf=true` checks this repository out with
+ * CRLF while the published tarball and every CI checkout use LF. An exact
+ * `startsWith('---\n')` guard therefore took a different branch on a Windows
+ * working tree and the skill silently registered its generic fallback
+ * description instead of the trigger-phrase description from the frontmatter —
+ * the text that decides when the host loads the skill at all. `.gitattributes`
+ * now pins LF; this function no longer depends on that being true.
+ *
  * @param text - raw SKILL.md content.
  * @returns parsed description (when the frontmatter carries one) and body.
  */
-function splitFrontmatter(text) {
-  if (!text.startsWith('---\n')) return { description: undefined, body: text }
-  const end = text.indexOf('\n---', 4)
-  if (end < 0) return { description: undefined, body: text }
-  const meta = text.slice(4, end)
-  const body = text.slice(end + 4).replace(/^\n+/, '')
-  const match = /^description:\s*(.+)$/m.exec(meta)
+export function splitFrontmatter(text) {
+  // Match the opening fence with either ending, then find the closing fence.
+  const open = /^---\r?\n/.exec(text)
+  if (!open) return { description: undefined, body: text }
+  const rest = text.slice(open[0].length)
+  const close = /\r?\n---[ \t]*(?:\r?\n|$)/.exec(rest)
+  if (!close) return { description: undefined, body: text }
+  const meta = rest.slice(0, close.index)
+  // Trim the separating blank lines so the body starts at the first heading,
+  // matching the host provider's own body trimming.
+  const body = rest.slice(close.index + close[0].length).replace(/^(?:[ \t]*\r?\n)+/, '')
+  const match = /^description:[ \t]*(.+?)[ \t]*$/m.exec(meta)
   return { description: match?.[1]?.trim(), body }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.29",
-  "description": "The dsh-plugin-guide knowledge base plus the dsh-plugin-dev CLI toolchain: official docs, Cordis primer, community deep-dives, and battle-tested pitfalls registered as an on-demand agent skill, with a scaffolder, static checker, and pack verifier for building DSH plugins.",
+  "version": "0.3.30",
+  "description": "DSH plugin development as an on-demand agent skill: official docs mirror, version-compatibility matrix, migration seams, measured pitfalls, plus a scaffolder, checker and pack verifier CLI.",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -15,6 +15,7 @@
   },
   "files": [
     "index.js",
+    "index.d.ts",
     "bin",
     "dist",
     "templates",
@@ -35,15 +36,21 @@
   ],
   "keywords": [
     "dsh",
-    "deepseek-harness",
     "dsh-plugin",
+    "dsh-plugin-development",
+    "dsh-skill",
+    "deepseek",
+    "deepseek-harness",
     "cordis",
-    "agent-skill",
     "plugin-development",
+    "agent-skill",
+    "agent-skills",
     "knowledge-base",
+    "documentation",
     "cli",
     "scaffold",
-    "checker"
+    "checker",
+    "typescript"
   ],
   "license": "Apache-2.0",
   "repository": {
@@ -57,6 +64,7 @@
     "typecheck:checkout": "tsc -p tsconfig.checkout.json --noEmit",
     "test": "vitest run",
     "check:readmes": "node scripts/check-readme-sync.mjs",
+    "check:ps1-bom": "node scripts/check-ps1-bom.mjs",
     "build:llms": "node scripts/build-llms-full.mjs",
     "check:kit": "pwsh -File scripts/verify-kit.ps1",
     "verify:artifacts": "node scripts/verify-artifacts.mjs",
@@ -64,15 +72,14 @@
     "prepare": "tsdown",
     "prepack": "tsdown"
   },
-  "dependencies": {
-    "tsdown": "^0.22.14",
-    "typescript": "^5.9.3"
-  },
+  "dependencies": {},
   "devDependencies": {
     "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
     "@types/node": "^22.20.1",
     "@types/semver": "^7.8.0",
     "semver": "^7.8.5",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.7"
   },
   "peerDependencies": {

package/references/sources.md

@@ -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 插件）并归档，如用户所指另有其仓，请告知后补充。