dsh-plugin-guide 0.3.29 → 0.3.31

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);
@@ -254,82 +277,82 @@ const SKILL_SECTIONS = {
 	"patch-valid": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.2",
-		heading: "两个概念、两种清单（bundle manifest）"
+		heading: "三个概念、三种清单（package.json 的 `dsh` 键）"
 	},
 	"patch-ids-unique": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.3",
-		heading: "配置分层顺序（按 id 整行覆盖）"
+		heading: "配置分层顺序（后层覆盖前层，逐行按 `id` 整段替换 config）"
 	},
 	"manifest-bundle-patch": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§2.2",
-		heading: "bundle 最小结构（dsh.bundle.patch）"
+		heading: "三个概念、三种清单（package.json 的 `dsh` 键）"
 	},
 	"manifest-main": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.3",
-		heading: "main/types 指向 lib 产物"
+		heading: "常见坑清单"
 	},
 	"manifest-peers": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.3",
-		heading: "cordis 双副本与 peer 对齐宿主"
+		heading: "常见坑清单"
 	},
 	"manifest-engines": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "规范与质量门禁（Node 版本）"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"manifest-files": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.1",
-		heading: "files 白名单与构建产物"
+		heading: "从 GitHub 安装的 build-script 坑"
 	},
 	"manifest-package-manager": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "packageManager 固定 pnpm"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"display-meta": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§7.0.1",
-		heading: "展示元数据与图标（locale meta + 导出 icon）"
+		heading: "展示元数据与图标（0.2 世代新增的硬性交付项）"
 	},
 	"readme-five-langs": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "文档双语/多语成对"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"readme-consistency": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§8",
-		heading: "五语 README 同步"
+		heading: "规范与质量门禁（对插件作者的实际影响）"
 	},
 	"redline-persona-role": {
-		file: "SKILL.md",
-		section: "§边界",
-		heading: "注入提示词段落以角色句开头、保持短小"
+		file: "guide/plugin-dev-guide.md",
+		section: "§3.7",
+		heading: "仓库级红线（写进 AGENTS.md，违反会挂门禁）"
 	},
 	"redline-waterfall-next": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.5",
-		heading: "waterfall 铁律：必须调用 next()"
+		heading: "事件（Events）"
 	},
 	"redline-no-hardcoded-tunables": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.6",
-		heading: "配置 Schema 化、不硬编码可调参数"
+		heading: "配置（Config）"
 	},
 	"redline-effect-registration": {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.3",
-		heading: "注册即 effect（disposer 可逆）"
+		heading: "注册即 effect"
 	},
 	"redline-async-apply-registration": {
 		file: "guide/plugin-dev-guide.md",
-		section: "§3.3",
-		heading: "async apply 首个 await 之后不得注册（卸载窗口竞态）"
+		section: "§3.3.1",
+		heading: "async `apply()` 的注册顺序（最容易写成静默缺陷的一条）"
 	}
 };
 /** Fallback citation for any check id not in the table. */
@@ -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/guide/plugin-dev-guide.md

@@ -148,6 +148,37 @@ ctx.effect(() => { const t = setInterval(...); return () => clearInterval(t) })
 
 框架代管：`ctx.on` / 服务 `register()` / `ctx.effect()`。`HMR`（`@deepseek-ai/cordis-plugin-hmr`）正因注册全部可逆而成立。
 
+#### 3.3.1 ⚠️ async `apply()` 的注册顺序（最容易写成静默缺陷的一条）
+
+`apply` **可以是 async**，但**第一个 `await` 之后再做注册是错的**：从 `await` 返回到注册完成之间存在一个
+卸载窗口——插件已开始 `UNLOADING`、effect 却还没建立，于是那次注册**既不会被记入 fiber 的 disposer 集合，
+也不会报错**。表现为"插件装了、日志全绿、能力却时有时无"（高负载下才复现）。
+
+**规则：注册必须在第一个 `await` 之前完成。** 需要异步数据才能决定注册内容时，先取数据再注册：
+
+```ts
+// ✅ 正确：await 只用于取数据，注册全部落在 await 之前的同步段之后、但不再 await
+export async function apply(ctx) {
+  const cfg = await loadRemoteConfig()        // 允许 await
+  if (!cfg.enabled) return                    // 允许提前返回
+  ctx.effect(() => ctx.tools.register(buildTool(cfg)))   // 注册紧随其后，不再 await
+}
+```
+
+```ts
+// ❌ 错误：await 之后才注册，卸载窗口内注册会丢
+export async function apply(ctx) {
+  ctx.on('a', handlerA)
+  await something()
+  ctx.tools.register(toolB)                  // ← 这次注册可能永远不会被撤销
+}
+```
+
+**自查**：`dsh-plugin-dev check` 的 `redline-async-apply-registration` 就是本条的机械检测
+（家族内唯一检测器，见 [`family-toolchain.md`](family-toolchain.md) §3.2）。
+**官方契约**：`apply` 返回 disposer 函数 / `null` / `undefined` / `Promise<disposer>` / （异步）可迭代——
+async `apply` 合法，但**必须返回 `Promise<disposer>`**，不能靠"await 之后再注册"来隐式注册。
+
 ### 3.4 服务（Service）
 
 - **消费**：`export const inject = ['tools']` → `apply` 里 `ctx.tools` 已就绪。可选依赖：不写 inject，用 `ctx.get('metrics')?.method()`。
@@ -200,9 +231,10 @@ export function apply(ctx: Context, config: Config) { /* config 已校验+补默
 
 1. **注册即 effect**：所有贡献走 `ctx.effect()` / `ctx.on()`；registry 的 `register()` 返回 disposer。
 2. **waterfall 监听器必须调 `next()`**。
-3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。运行时不变式会断言这一点。
+3. **模型可见 ⟺ 已记录**（Model-visible ⟺ logged）：任何进入模型请求的内容必须能从会话日志重建；新增模型可见输入必须新增会话事件。~~运行时不变式会断言这一点~~ —— ⚠️ **该强制手段已于 `0.2.1-alpha.1` 随运行时 invariants 整体移除**（`upgrade-guide/v0.2.0-rc.2/remove-runtime-invariants`），所以这条**现在完全靠评审与自觉**，没有任何机械兜底。见 §3.6 与 [`migration-0.2.md`](migration-0.2.md) §4。
 4. **跨边界 opaque id 用 branded**：`Branded<B>`（`dsh-brand`，纯类型、零运行时依赖），从不裸 `string`；构造走 per-type factory（`SessionId` / `CallId` / `JobId` / `GoalId` 等），防止不同 id 在类型层互换。
 5. **会话事件版本规则**：`SessionEventMap` 成员默认 required-on-read——不认识该事件类型的 build 一律拒绝整份日志，除非该事件带信封的 `ignorable: true`。**插件不得新增事件类型**（见 §3.5 红线）：`Session.append()` 写不了信封标记。只有结构格式变更才 bump `SESSION_FORMAT_VERSION`（当前 **4**；V3→V4 把 results 提升为 tool-role 消息、把消息 source 改为生产者自有的 `source.kind`，V3 读方拒绝 V4 日志）。新增**模型可见输入**由宿主侧事件承担（红线 3），插件只消费。
+6. **注入的提示词段落要短、且以角色句开头**：插件写进系统提示词的段落（`systemPrompt.section()` 的正文）**第一句应当是说明"你是谁/做什么"的短句**，整段保持精简。原因有二：它是每轮请求都付费的固定前缀；而且段落开头若不是完整句子，模型会把后续内容当作它的延续来读。**自查**：`dsh-plugin-dev check` 的 `redline-persona-role`（段落首句需以 `。.?!` 收尾、首句 ≤200 字符、整段 ≤600 字符）。**这条是"工程卫生"而非官方硬门禁**——官方文档没有对应条款，别在 README 里把它说成官方要求。
 
 ---
 
@@ -306,6 +338,70 @@ declare module '@deepseek-ai/dsh-llm' {
 
 **工具的 `parameters` 是 DSH 自己的方言，不是 JSON Schema**；Remote 服务调用是**位置参数**而不是对象参数（`get()` 能用，最有欺骗性）；往 `ctx` 上写**未声明**的属性会抛错并可能静默杀掉整个插件的激活——可选服务一律 `ctx.get(name)`，**`ctx.<service>` 只对自己 `inject` 里声明过的服务合法**。
 
+### 4.9 插件内如何发布一个 skill（本仓库就是参考实现）
+
+一个插件可以**自己携带一份 agent 技能**——这是把"知识/流程"交付给宿主的标准做法，也是本仓库
+（`dsh-plugin-guide`）唯一在做的事。机制曾经在社区资料里被写错成"systemPrompt section + 工具注册"，
+**那不是这条路**。
+
+**契约**（官方 `docs/subsystems/skills.md`）：
+
+- `ctx.skills` 是 **provider 注册表**，注册是**同步**的，必须在 `apply()` 内完成。
+- 插件走的是**运行时贡献**入口 `ctx.skills.register(definition)`，其类型为
+  `SkillRegistration = Omit<SkillDefinition, 'invocation' | 'provider'> & { invocation?; provider? }`
+  ——`invocation` 省略即模型与用户两侧都可见，`provider` 省略即落到注册表自有的 runtime provider。
+- **返回的是 Cordis effect disposer**：撤销该贡献并使发现缓存失效。所以照例写成
+  `ctx.effect(() => ctx.skills.register({...}))`。
+- 要携带随包资料，给 **`resourceBase: { kind: 'directory', path: <包目录> }`**；技能正文里的
+  `./guide/...`、`./references/...` 相对路径就按该目录解析。**这是"渐进披露"得以成立的关键**：
+  技能正文只放路由，重资料留在包里按需读，不必一次塞进模型上下文。
+
+**最小可用实现**（取自本仓库 `index.js`，可直接抄）：
+
+```js
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const name = 'my-skill-plugin'
+export const inject = ['skills']
+
+const packageRoot = dirname(fileURLToPath(import.meta.url))
+
+export function apply(ctx) {
+  const { description, body } = splitFrontmatter(readFileSync(join(packageRoot, 'SKILL.md'), 'utf8'))
+  ctx.effect(() =>
+    ctx.skills.register({
+      name: 'my-skill-plugin',
+      source: 'bundled',
+      description,                                     // 决定"何时被加载"
+      content: body,                                   // 技能正文
+      resourceBase: { kind: 'directory', path: packageRoot },
+    }),
+  )
+}
+```
+
+**四个实测要点**（每一条都踩过）：
+
+1. **`description` 就是触发器，要写"何时使用"而不是"这是什么"。** 宿主只把 name + description 放进目录给模型挑，
+   所以写 `Use when developing, reviewing, packaging, debugging, or answering questions about …`
+   这类带场景动词的句子，而不是名词短语。
+2. **解析 frontmatter 要容忍 CRLF。** 用精确的 `startsWith('---\n')` 会在 Windows 检出（`core.autocrlf=true`）
+   上失配，后果是**静默退化**：描述掉回兜底字符串（技能变得不易被选中），且**整份文件连同 frontmatter 被当成技能正文**注入。
+   本仓库为此加了 `.gitattributes`（`* text=auto eol=lf`），并把解析改成行尾无关。
+3. **截断 frontmatter 与裁掉正文前导空行是两件事。** 只做前者，正文会以换行开头；宿主的 filesystem provider
+   自己会裁，但**不是所有 provider 都裁**，自己裁更稳。
+4. **单测要真的加载入口模块。** `index.js` 长期零测试，缺陷因此活到发布之后；测试只需一个
+   `{ effect, skills: { register } }` 桩，就能断言"注册的 name、用的是 frontmatter 描述还是兜底、
+   `resourceBase` 是否指向包目录"。本仓库 `tests/entry.test.ts` 就是这 8 条断言。
+
+**与"工具"的区别**：注册工具（`ctx.tools.register`）会让**每一次请求**都付该工具定义的 token；
+注册技能只在模型**按描述选中**它时才加载正文。给 agent 交付"资料/流程"用技能，交付"可执行动作"才用工具。
+
+**相关**：`references/official-plugin-dev-skill.md`（官方自带开发技能的要点）、
+`references/official-docs/docs/subsystems/skills.md`（完整契约与 ranked local discovery 表）。
+
 ---
 
 ## 5. 能力分层：Service Definition / Provider / Consumer
@@ -356,7 +452,7 @@ LLM 适配器同理：继承 `LlmAdapter` 实现 `stream(options)`，`ctx.llm.re
 | 子代理委派 | `ctx.subagents` provider 注册表 + `dsh-tool-subagent`（现有多家 provider：in-process spawn / fork / `dsh-subagent-acp` / `-codex` / `-claude-code` / `-dsh-sdk`） |
 | 多代理编排 | `ctx.workflowEngine` 缝（Definition/Provider/Consumer）+ PTC workflow engine + `workflow`/`ralph` 工具 Consumer |
 | MCP | 每服务器一个插件：发现工具 → `ctx.tools.register()` |
-| Skills | section + 工具注册；调用时 `inject()` 技能内容 |
+| Skills | ⚠️ **不是** section + 工具注册：插件用 **`ctx.skills.register()`** 注册一个运行时技能（`SkillRegistration` = `SkillDefinition` 去掉 `invocation`/`provider`，两者可省略走默认），**在同一 `apply()` 内同步注册**，返回的 disposer 撤销贡献并使发现缓存失效。随包携带资料时给 **`resourceBase: { kind: 'directory', path: <包目录> }`**，技能正文里的 `./...` 相对路径即按该目录解析。官方参考实现是 `dsh-skill-badge`（注册一个不可变的 `bundled` 候选 + 暴露打包资源目录）。**本仓库 `index.js` 是第二个可跑的例子**——见下方 §"插件内如何发布 skill" |
 | 定时任务 | 注册模型可调的调度工具；定时器 → 空闲 `followup(source:{kind:'cron'})` / 忙碌 `inject()` |
 | 遥测/回放 | `session/event` → JSONL；回放 = `sessions.create(id, {seed})` |
 | 上报通道（0.2 新增） | `ctx.otel`：`createEventReporter(options)` / `createSessionLogReporter(options)`——自带传输与批处理，未用时**不分配** provider/transport；**消费者必须在自己 fiber 释放时 drain 通道** |

package/guide/quick-reference.es.md

@@ -181,3 +181,5 @@ Documentación comunitaria de desarrollo — plantillas/tutoriales/errores, list
 - Investigación del repo: `references/harness-repo.md`
 - Comunidad/ecosistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas las URLs de fuentes: `references/sources.md`
+- [Matriz de versiones](version-matrix.md) — los cuatro valores «latest», etiquetas `latest` congeladas, fallas de compatibilidad y selección de rango de peers.
+- [Lista de migración](migration-0.2.md) — §0–§12 cubren los cambios que rompen compatibilidad, **§13 los 19 seams de `0.2.1-alpha.2`**.

package/guide/quick-reference.hi.md

@@ -181,3 +181,5 @@ Consumer (`dsh-tool-my-cap`): `inject = ['tools','myCap']`, `ctx.tools.register(
 - रिपो शोध: `references/harness-repo.md`
 - समुदाय/पारिस्थितिकी: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - सभी स्रोत URL: `references/sources.md`
+- [संस्करण मैट्रिक्स](version-matrix.md) — चार "latest" मान, जमे हुए `latest` टैग, संगतता-भंग बिंदु और peer रेंज का चयन।
+- [माइग्रेशन सूची](migration-0.2.md) — §0–§12 संगतता-भंग बदलाव, **§13 में `0.2.1-alpha.2` के 19 seams**।

package/guide/quick-reference.pt.md

@@ -181,3 +181,5 @@ Documentação comunitária de desenvolvimento — modelos/tutoriais/armadilhas,
 - Pesquisa do repo: `references/harness-repo.md`
 - Comunidade/ecossistema: `references/community-ecosystem.md` + `references/community-repo-deep-dive.md`
 - Todas as URLs de fontes: `references/sources.md`
+- [Matriz de versões](version-matrix.md) — os quatro valores "latest", tags `latest` congeladas, falhas de compatibilidade e seleção de intervalo de peers.
+- [Lista de migração](migration-0.2.md) — §0–§12 cobrem as mudanças que quebram compatibilidade, **§13 os 19 seams de `0.2.1-alpha.2`**.

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.31",
+  "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,8 @@
     "typecheck:checkout": "tsc -p tsconfig.checkout.json --noEmit",
     "test": "vitest run",
     "check:readmes": "node scripts/check-readme-sync.mjs",
+    "check:parity": "node scripts/check-readme-parity.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 +73,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": {