dsh-plugin-guide 0.3.15 → 0.3.17

package/README.md

@@ -3,6 +3,8 @@
 # 🐳 dsh-plugin-guide
 - **1024 store channel**: `npm i -g dsh1024` once, then `dsh1024 plugin --profile web add dsh-plugin-guide` (counts toward the [deepseek1024.com](https://deepseek1024.com) install ranking).
 [![Gitee](https://img.shields.io/badge/Gitee-mirror-c71d23?logo=gitee)](https://gitee.com/perrylink/dsh-plugin-guide)
+[![dshfind](https://dshfind.com/api/badge/PerryLink/dsh-plugin-guide?metric=downloads)](https://dshfind.com/plugins/PerryLink/dsh-plugin-guide?ref=badge)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-plugin-guide/badge)](https://api.securityscorecards.dev/projects/github.com/PerryLink/dsh-plugin-guide)
 
 **Everything you need to build [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugins.**
 
@@ -13,6 +15,7 @@
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![DSH plugin](https://img.shields.io/badge/dsh--plugin-✅-green)](https://github.com/topics/dsh-plugin)
 [![dsh-doctor](https://raw.githubusercontent.com/PerryLink/dsh-plugin-doctor/main/badges/PerryLink__dsh-plugin-guide.svg)](https://github.com/PerryLink/dsh-plugin-doctor#verified-徽章)
+[![DSH Market](https://raw.githubusercontent.com/2BingLing/dsh-market/master/assets/readme/badge-top-rated.svg)](https://dsh.market/)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
 [![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-plugin-guide/verify.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-plugin-guide/actions)
 [![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-plugin-guide?label=version)](https://github.com/PerryLink/dsh-plugin-guide/releases)
@@ -29,7 +32,7 @@
 
 | Surface | Status |
 |---|---|
-| Harness | DeepSeek Harness `dsh-v0.1.5-rc.2` (adapted 2026-09-09): the session envelope keeps its ignorable field for stored-log read compatibility only - Session.append still cannot stamp it, so audit-gate behavior is unchanged. Verified 2026-09-11 against the dsh-v0.1.5-rc.2 master checkout (full gate chain + profile install smoke). |
+| Harness | DeepSeek Harness `dsh-v0.1.7-alpha.2` (re-synced 2026-09-18, `ddefc45`): the official-docs snapshot is refreshed to alpha.2, the checker now expects the four-clause peer range (`… || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0`) single-sourced from the scaffold templates, and a new red line fails `async apply` functions that register after their first `await`. Local gate chain green (40 tests, typecheck, `verify` dogfood); the compat job's real alpha.2 run lands with the next CI push. |
 | 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) |
@@ -206,13 +209,16 @@ pwsh -File scripts/verify-kit.ps1   # critical paths + link scan (+ docs drift w
 
 ## PerryLink DSH Plugin Family
 
-This project is one of the [40 DeepSeek Harness plugins](https://github.com/PerryLink) maintained by [PerryLink](https://github.com/PerryLink). If this one helps you, the others likely will too:
+This project is one of the **45 DeepSeek Harness plugins** maintained by [PerryLink](https://github.com/PerryLink). If this one helps you, the others likely will too:
 
 | Plugin | One-liner |
 |---|---|
 | **[dsh-auto-review](https://github.com/PerryLink/dsh-auto-review)** | Second-model auto-review on the approval chain, fail-closed by default | |
+| **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | Automatic strong/cheap model-tier routing with deterministic risk guards and a `/tier` command | |
 | **[dsh-background-agents](https://github.com/PerryLink/dsh-background-agents)** | Durable background child agents with a Web UI sidebar, messaging and interrupt | |
 | **[dsh-budget](https://github.com/PerryLink/dsh-budget)** | Cost governance for DeepSeek Harness: budgets, carbon, and latency in one panel. | |
+| **[dsh-catalog](https://github.com/PerryLink/dsh-catalog)** | DSH Desktop Market standard catalog source for the PerryLink family | |
+| **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence | |
 | **[dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind)** | Claude Code /rewind-equivalent: snapshots, session forks, one-shot restore | |
 | **[dsh-claude-move](https://github.com/PerryLink/dsh-claude-move)** | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH | |
 | **[dsh-click](https://github.com/PerryLink/dsh-click)** | Cross-platform native desktop control for DeepSeek Harness — Windows first. | |
@@ -225,6 +231,7 @@ This project is one of the [40 DeepSeek Harness plugins](https://github.com/Perr
 | **[dsh-fund-research](https://github.com/PerryLink/dsh-fund-research)** | Deterministic research reports for Chinese public mutual funds | |
 | **[dsh-github](https://github.com/PerryLink/dsh-github)** | GitHub PR/issues integration for DSH, every write gated by approval | |
 | **[dsh-industry-research](https://github.com/PerryLink/dsh-industry-research)** | Industry research orchestration that seals its deliverables through this plugin's `ctx.researchReport.assemble` | |
+| **[dsh-laya](https://github.com/PerryLink/dsh-laya)** | Laya typed decisions (`noul`/`choice`/`score`) as a first-class Cordis service and model-visible tools | |
 | **[dsh-library](https://github.com/PerryLink/dsh-library)** | Local document knowledge base for DeepSeek Harness. | |
 | **[dsh-local-ai](https://github.com/PerryLink/dsh-local-ai)** | Local-model (Ollama) integration for DeepSeek Harness. | |
 | **[dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions)** | LSP diagnostics, formatting, completion, code actions and rename over language servers | |
@@ -234,27 +241,24 @@ This project is one of the [40 DeepSeek Harness plugins](https://github.com/Perr
 | **[dsh-observe](https://github.com/PerryLink/dsh-observe)** | OpenTelemetry and Langfuse observability exporter for DeepSeek Harness. | |
 | **[dsh-output-styles](https://github.com/PerryLink/dsh-output-styles)** | Claude Code outputStyles-equivalent runtime style switching | |
 | **[dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules)** | Claude Code-style declarative allow/deny/ask permission rules with audit | |
-| **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console |
+| **[dsh-plugin-certification](https://github.com/PerryLink/dsh-plugin-certification)** | Community certification registry with repro-checkable grades and badges | |
+| **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | Zero-dependency static + sandbox smoke detector for DSH plugins | |
+| **[dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide)** | Plugin-development knowledge base as an on-demand agent skill | |
+| **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins | |
+| **[dsh-plugin-upgrade](https://github.com/PerryLink/dsh-plugin-upgrade)** | One-package, one-corridor-index plugin upgrade skill: routes a repository to the matching closed corridor card | |
+| **[dsh-plugin-upgrade-015](https://github.com/PerryLink/dsh-plugin-upgrade-015)** | Merged `0.1.3-alpha.1` → `0.1.5-rc.1` upgrade corridor card plus a zero-dependency seam scanner | |
+| **[dsh-reach](https://github.com/PerryLink/dsh-reach)** | Multi-channel approval/question bridge: WeChat/Telegram/Feishu, session console | |
 | **[dsh-research-report](https://github.com/PerryLink/dsh-research-report)** | Verifiable research-report engine: content-addressed evidence ledger and sealed versions | |
 | **[dsh-score](https://github.com/PerryLink/dsh-score)** | Multi-dimensional quality scoring for DeepSeek Harness plugins. | |
 | **[dsh-session-pin](https://github.com/PerryLink/dsh-session-pin)** | Pin sessions in the Web sidebar with durable ordering | |
 | **[dsh-session-sync](https://github.com/PerryLink/dsh-session-sync)** | Cross-device session sync for DeepSeek Harness — a dedicated git mirror of your session store. | |
 | **[dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security)** | Security-audit skill pack: secret scan, dependency and supply-chain review | |
 | **[dsh-talk](https://github.com/PerryLink/dsh-talk)** | Voice-first session loop for DeepSeek Harness: talk to it, hear it answer. | |
+| **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | Cross-session team rooms: shared message bus, task board and timeline | |
 | **[dsh-test-drive](https://github.com/PerryLink/dsh-test-drive)** | Isolated install-and-smoke test drives for DeepSeek Harness plugins. | |
-| **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | TickTick/Dida365 task bridge: session-header panel + 11 tools |
+| **[dsh-ticktick](https://github.com/PerryLink/dsh-ticktick)** | TickTick/Dida365 task bridge: session-header panel + 11 tools | |
 | **[dsh-translate](https://github.com/PerryLink/dsh-translate)** | Vendor parameter translation and deterministic JSON repair for DeepSeek Harness. | |
-| **[dsh-wechat](https://github.com/pan17/dsh-wechat)** | WeChat ↔ DSH bridge (Tencent iLink bot): text/image/file/voice, approvals in chat |
-| **[dsh-autotier](https://github.com/PerryLink/dsh-autotier)** | Automatic strong/cheap model-tier routing with deterministic risk guards and a `/tier` command | |
-| **[dsh-catalog](https://github.com/PerryLink/dsh-catalog)** | DSH Desktop Market standard catalog source for the PerryLink family | |
-| **[dsh-cert-mcp](https://github.com/PerryLink/dsh-cert-mcp)** | Read-only MCP server exposing the certification registry: grades, snapshots and five-dimension evidence | |
-| **[dsh-kit](https://github.com/PerryLink/dsh-kit)** | One-command starter pack that installs the core family | |
-| **[dsh-plugin-certification](https://github.com/PerryLink/dsh-plugin-certification)** | Community certification registry with repro-checkable grades and badges | |
-| **[dsh-plugin-kit](https://github.com/PerryLink/dsh-plugin-kit)** | Shared zero-runtime-dependency toolkit for the PerryLink DSH plugins | |
-| **[dsh-plugin-portal](https://github.com/PerryLink/dsh-plugin-portal)** | Zero-dependency static portal rendering the whole plugin family as one page | |
-| **[dsh-plugin-upgrade-015](https://github.com/PerryLink/dsh-plugin-upgrade-015)** | Merged `0.1.3-alpha.1` → `0.1.5-rc.1` upgrade corridor card plus a zero-dependency seam scanner | |
-| **[dsh-team-rooms](https://github.com/PerryLink/dsh-team-rooms)** | Cross-session team rooms: shared message bus, task board and timeline | |
-| **[dsh-plugin-doctor](https://github.com/PerryLink/dsh-plugin-doctor)** | Zero-dependency static + sandbox smoke detector for DSH plugins | |
+
 
 ## Disclaimer
 

package/dist/dsh-plugin-dev.js

@@ -134,6 +134,15 @@ function isDir(path) {
 
 //#endregion
 //#region src/cli/templates.ts
+/**
+* The canonical `@deepseek-ai/dsh-*` peer range, single-sourced here and
+* substituted into every scaffolded package.json through the
+* `{{dshPeerRange}}` placeholder. Keep it identical to the canonical range in
+* `dsh-plugin-kit/data/peer-range.json`: one clause per prerelease tuple is
+* required by semver's prerelease rule, and the `-0` floor covers the whole
+* 0.1.6 tuple (never the bare `>=0.1.6` form).
+*/
+const DSH_PEER_RANGE = ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0";
 /** Resolve the templates root: env override first, then candidate walks. */
 function resolveTemplatesRoot() {
 	const env = process.env.DSH_PLUGIN_DEV_TEMPLATES;
@@ -159,7 +168,7 @@ function walkFiles(dir, base = "") {
 }
 /** Substitute placeholders in template text. */
 function renderTemplate(text, context) {
-	return text.replaceAll("{{pkgName}}", context.pkgName).replaceAll("{{name}}", context.name).replaceAll("{{version}}", context.version).replaceAll("{{year}}", context.year);
+	return text.replaceAll("{{pkgName}}", context.pkgName).replaceAll("{{name}}", context.name).replaceAll("{{version}}", context.version).replaceAll("{{year}}", context.year).replaceAll("{{dshPeerRange}}", DSH_PEER_RANGE);
 }
 /** Render every file of a language template. */
 function renderScaffold(lang, context) {
@@ -295,6 +304,11 @@ const SKILL_SECTIONS = {
 		file: "guide/plugin-dev-guide.md",
 		section: "§3.3",
 		heading: "注册即 effect（disposer 可逆）"
+	},
+	"redline-async-apply-registration": {
+		file: "guide/plugin-dev-guide.md",
+		section: "§3.3",
+		heading: "async apply 首个 await 之后不得注册（卸载窗口竞态）"
 	}
 };
 /** Fallback citation for any check id not in the table. */
@@ -499,7 +513,8 @@ function runCheck(options) {
 		checkRedlinePersonaRole(root),
 		checkRedlineWaterfallNext(root),
 		checkRedlineNoHardcodedTunables(root),
-		checkRedlineEffectRegistration(root)
+		checkRedlineEffectRegistration(root),
+		checkRedlineAsyncApplyRegistration(root)
 	];
 	const report = buildReport(root, readCliVersion(), checks);
 	return {
@@ -775,7 +790,7 @@ function checkManifestPeers(root, pkg) {
 	const expected = {};
 	for (const imp of harnessImports) if (imp === "@deepseek-ai/cordis") expected[imp] = "^4.0.2";
 	else if (imp === "@deepseek-ai/schemastery") expected[imp] = "^3.18.2";
-	else if (imp.startsWith("@deepseek-ai/dsh-")) expected[imp] = ">=0.1.0-rc.8 <0.2.0";
+	else if (imp.startsWith("@deepseek-ai/dsh-")) expected[imp] = DSH_PEER_RANGE;
 	const problems = [];
 	for (const [pkgName, range] of Object.entries(expected)) {
 		const declared = peers[pkgName];
@@ -1117,6 +1132,215 @@ function checkRedlineEffectRegistration(root) {
 		skillRef: ref
 	};
 }
+/** Registration idioms that must never run after the first `await` of an async apply. */
+const ASYNC_APPLY_REGISTRATION = [
+	["ctx.effect", /\bctx\.effect\s*\(/],
+	["ctx.on", /\bctx\.on\s*\(/],
+	["ctx.provide", /\bctx\.provide\s*\(/],
+	["ctx.plugin", /\bctx\.plugin\s*\(/],
+	["register()", /\.register\s*\(/]
+];
+/** Braces of the block whose `{` is at `openIdx`, skipping strings and comments. Returns the inner body or undefined. */
+function blockBody(text, openIdx) {
+	let depth = 0;
+	let quote = null;
+	let lineComment = false;
+	let blockComment = false;
+	for (let i = openIdx; i < text.length; i++) {
+		const ch = text[i];
+		const next = text[i + 1];
+		if (lineComment) {
+			if (ch === "\n") lineComment = false;
+			continue;
+		}
+		if (blockComment) {
+			if (ch === "*" && next === "/") {
+				blockComment = false;
+				i++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (ch === "\\") {
+				i++;
+				continue;
+			}
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			lineComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			blockComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return text.slice(openIdx + 1, i);
+		}
+	}
+}
+/** Index just past the first top-level (brace-depth 0) `await` keyword, or -1. */
+function firstTopLevelAwait(body) {
+	let depth = 0;
+	let quote = null;
+	let lineComment = false;
+	let blockComment = false;
+	for (let i = 0; i < body.length - 5; i++) {
+		const ch = body[i];
+		const next = body[i + 1];
+		if (lineComment) {
+			if (ch === "\n") lineComment = false;
+			continue;
+		}
+		if (blockComment) {
+			if (ch === "*" && next === "/") {
+				blockComment = false;
+				i++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (ch === "\\") {
+				i++;
+				continue;
+			}
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			lineComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			blockComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === "{") depth++;
+		else if (ch === "}") depth--;
+		else if (depth === 0 && ch === "a" && body.startsWith("await", i)) {
+			const before = i === 0 ? "" : body[i - 1];
+			const after = body[i + 5] ?? "";
+			if (!/[A-Za-z0-9_$]/.test(before) && !/[A-Za-z0-9_$]/.test(after)) return i + 5;
+		}
+	}
+	return -1;
+}
+/** First top-level registration idiom after `fromIdx` (nested function bodies excluded), or undefined. */
+function registrationAfter(body, fromIdx) {
+	let depth = 0;
+	let quote = null;
+	let lineComment = false;
+	let blockComment = false;
+	for (let i = fromIdx; i < body.length; i++) {
+		const ch = body[i];
+		const next = body[i + 1];
+		if (lineComment) {
+			if (ch === "\n") lineComment = false;
+			continue;
+		}
+		if (blockComment) {
+			if (ch === "*" && next === "/") {
+				blockComment = false;
+				i++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (ch === "\\") {
+				i++;
+				continue;
+			}
+			if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			lineComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			blockComment = true;
+			i++;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			quote = ch;
+			continue;
+		}
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			if (depth === 0) break;
+			depth--;
+			continue;
+		}
+		if (depth !== 0) continue;
+		for (const [kind, re] of ASYNC_APPLY_REGISTRATION) {
+			const m = re.exec(body.slice(i));
+			if (m) return [kind, body.slice(i, i + Math.min(m[0].length, 40))];
+		}
+	}
+}
+function checkRedlineAsyncApplyRegistration(root) {
+	const ref = skillRefFor("redline-async-apply-registration");
+	const files = listSourceFiles(root);
+	const flagged = [];
+	for (const file of files) {
+		const text = readText(file) ?? "";
+		const re = /export\s+async\s+function\s+apply\s*\(/g;
+		let match;
+		while ((match = re.exec(text)) !== null) {
+			const bodyStart = text.indexOf("{", match.index);
+			if (bodyStart < 0) continue;
+			const body = blockBody(text, bodyStart);
+			if (body === void 0) continue;
+			const awaitIdx = firstTopLevelAwait(body);
+			if (awaitIdx < 0) continue;
+			const hit = registrationAfter(body, awaitIdx);
+			if (hit) flagged.push(`${relativePath(root, file)}: async apply calls ${hit[0]} (${hit[1]}) after its first await — registration belongs in ctx.effect()/ctx.on() or before any await`);
+		}
+	}
+	if (flagged.length > 0) return {
+		id: "redline-async-apply-registration",
+		severity: "error",
+		kind: "heuristic",
+		status: "fail",
+		message: "async apply registers after its first await (unload-window race)",
+		skillRef: ref,
+		detail: flagged
+	};
+	if (!files.some((f) => /export\s+async\s+function\s+apply\s*\(/.test(readText(f) ?? ""))) return {
+		id: "redline-async-apply-registration",
+		severity: "error",
+		kind: "heuristic",
+		status: "skip",
+		message: "no async apply function found to inspect",
+		skillRef: ref
+	};
+	return {
+		id: "redline-async-apply-registration",
+		severity: "error",
+		kind: "heuristic",
+		status: "pass",
+		message: "no registration after the first await of any async apply",
+		skillRef: ref
+	};
+}
 function relativePath(root, file) {
 	return file.replace(root.replace(/[\\/]$/, ""), "").replace(/^[\\/]/, "");
 }
@@ -1466,7 +1690,7 @@ function suggestionsFor(step, result) {
 	const base = [`tail of "${step}":\n${tailOf(result)}`];
 	if (result.timedOut) base.push(`command timed out; raise --timeout or --smoke-timeout`);
 	if (step === "install") {
-		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.1.5-rc.1 (older builds such as the rc.6 line do not satisfy the compat pin)");
+		base.push("ensure the dsh CLI is @deepseek-ai/dsh@0.1.7-alpha.2 (older builds such as the rc.6 line do not satisfy the compat pin)");
 		base.push("confirm the profile allowlist matches the repo compat workflow (native builds allowlisted)");
 	}
 	if (step === "headless") base.push("a hang usually means an injected service stayed pending; the smoke timeout surfaces exactly that");
@@ -1587,8 +1811,8 @@ async function main(argv, cwd = process.cwd()) {
 					dshBin: resolveDsh(flagString(flags, "dsh")),
 					pnpmBin: resolvePnpm(flagString(flags, "pnpm")),
 					profile: flagString(flags, "profile", "compat") ?? "compat",
-					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.1.5-rc.1") ?? "@deepseek-ai/dsh-base@0.1.5-rc.1",
-					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.1.5-rc.1") ?? "@deepseek-ai/dsh-headless@0.1.5-rc.1",
+					base: flagString(flags, "base", "@deepseek-ai/dsh-base@0.1.7-alpha.2") ?? "@deepseek-ai/dsh-base@0.1.7-alpha.2",
+					headless: flagString(flags, "headless", "@deepseek-ai/dsh-headless@0.1.7-alpha.2") ?? "@deepseek-ai/dsh-headless@0.1.7-alpha.2",
 					timeoutMs: timeoutMs(flags, "timeout", "DSH_PLUGIN_DEV_TIMEOUT", DEFAULT_TIMEOUT_MS),
 					smokeTimeoutMs: timeoutMs(flags, "smoke-timeout", "DSH_PLUGIN_DEV_SMOKE_TIMEOUT", DEFAULT_SMOKE_TIMEOUT_MS)
 				});

package/guide/plugin-dev-guide.md

@@ -300,7 +300,7 @@ LLM 适配器同理：继承 `LlmAdapter` 实现 `stream(options)`，`ctx.llm.re
 | 同会话目标 | `ctx.goals`；经 `agent/*` 继续 |
 | fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
 | 只对一个 agent 注册 | 用该 agent 的 `agent.ctx`（作用域注册） |
-| Hook 系统（用户/项目级） | `agent/session-start`、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping` 监听器 |
+| Hook 系统（用户/项目级） | `agent/created`（serial）、`agent/pre-step`、`agent/request`、`tools/pre-execute`、`tools/post-execute`、`agent/turn-stopping` 监听器 |
 | 上下文压缩 | `ctx.compaction` 缝 + `dsh-compaction-basic`；自动压力走 serial `agent/pre-step`，溢出恢复走 `agent/request-error` |
 | 系统提示词配置 | `ctx.systemPrompt.section()`（带排序与作用域内遮蔽） |
 | 计划模式 | `@deepseek-ai/dsh-plan-mode`（`plan/mode` 日志态、`/plan`、`exit_plan_mode` 工具） |

package/guide/release-engineering.md

@@ -34,22 +34,24 @@ Keep a per-repo `AGENTS.md` stating that repository's own rules. As a portfolio
 
 ## 2. The version-line matrix
 
-During developer preview the harness publishes several lines at once, for example `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`. A portfolio pinned to one line breaks the moment a user installs from another.
+During developer preview the harness publishes several lines at once, for example `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, `0.1.6-alpha.2`, `0.1.7-alpha.2`. A portfolio pinned to one line breaks the moment a user installs from another.
 
-The pattern that admits both windows:
+The pattern that admits all windows (one clause per prerelease tuple; each `-0` floor covers every prerelease of its tuple, never the bare `>=0.1.7` form):
 
 ```jsonc
 {
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.1"
+    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2"
   }
 }
 ```
 
+A range is only as wide as its newest clause, and semver makes this easy to get wrong in a way that looks right: **a range admits a prerelease only if some comparator carries that same `[major, minor, patch]` tuple AND a prerelease.** So a band ending at `>=0.1.6-0 <0.2.0` admits `0.1.6-alpha.2` but *not* `0.1.7-alpha.2` — it reads as "everything up to 0.2" and behaves as "nothing after the 0.1.6 tuple". Adding the line's own clause is the whole fix; check it with `semver.satisfies('0.1.7-alpha.2', range)`, never by eye.
+
 Rules that follow:
 
 - **`devDependencies` pin the newest published line.** Your typecheck must fail before your users do.

package/guide/release-engineering.zh-CN.md

@@ -34,22 +34,24 @@
 
 ## 2. 版本线矩阵
 
-开发者预览期，宿主会同时存在多条线，例如 `0.1.2-rc.1`、`0.1.5-alpha.1`、`0.1.5-rc.1`。只钉一条线的组合，在用户从另一条线安装的那一刻就坏。
+开发者预览期，宿主会同时存在多条线，例如 `0.1.2-rc.1`、`0.1.5-alpha.1`、`0.1.5-rc.1`、`0.1.6-alpha.2`、`0.1.7-alpha.2`。只钉一条线的组合，在用户从另一条线安装的那一刻就坏。
 
-同时接受两个窗口的写法：
+同时接受全部窗口的写法（每个预发布 tuple 一条子句；每个 `-0` 下界覆盖该 tuple 的全部预发布，绝不写成裸 `>=0.1.7` 形态）：
 
 ```jsonc
 {
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.1"
+    "@deepseek-ai/dsh-tools": "0.1.7-alpha.2"
   }
 }
 ```
 
+范围的宽度只等于它最新那条子句，而 semver 在这里很容易让人写错、且**看起来是对的**：**一个范围只有在某条比较符带着同一个 `[major, minor, patch]` tuple 且带预发布时，才接纳该预发布版本。** 所以一条止于 `>=0.1.6-0 <0.2.0` 的带子接纳 `0.1.6-alpha.2`，却**不**接纳 `0.1.7-alpha.2`——读起来像"0.2 之前全都要"，行为上却是"0.1.6 tuple 之后一概不要"。补上该线自己的子句就是全部修法；用 `semver.satisfies('0.1.7-alpha.2', range)` 去验，**不要用眼睛看**。
+
 由此得到的规则：
 
 - **`devDependencies` 钉最新已发布的线。** 类型检查要赶在你的用户之前报错。

package/guide/unfixed-issues.md

@@ -11,7 +11,7 @@
 > - 用法：开发插件/排障时按「症状 → 位置 → 规避」查；条目后附原讨论，官方有新回复时以原帖为准。
 > - 诚实标注：无法在源码复核的环节（依赖未安装的半边）已注明。
 
-## 1. 仍未修复（29 项 + 2 项部分修复（#1、#2）+ 1 项已修复（#27，保留为修复记录），按严重度排序）
+## 1. 仍未修复（30 项 + 2 项部分修复（#1、#2）+ 1 项已修复（#27，保留为修复记录），按严重度排序）
 
 | # | 问题 | 位置（@ddefc45，2026-09-19 复核） | 临时规避 | 讨论 |
 |---|---|---|---|---|
@@ -47,8 +47,9 @@
 | 30 | http-proxy 把 `[::1]` 写进子进程 `no_proxy`/`NO_PROXY` → httpx 系 MCP server 崩溃（undici 专用括号项泄漏到子进程 env） | `packages/util/http-proxy/src/policy.ts:33`（LOOPBACK_NO_PROXY 含 `[::1]`，注释 `:25-32` 自认是为 undici）、`:206-210`；`install.ts:79-92,113-129`；harness 自身匹配器无需括号项（`:279-295` 去括号） | env 写入侧只写裸 `::1`，undici 消费处保留括号项（两处消费者分离） | #6655 |
 | 31 | 粘贴图片惰性持有 File 快照：剪贴板同步（如微信输入法跨设备复制）后提交时 FileReader NotFoundError | `ui-conversation/src/client/service.ts:73-80`（browserDraftAttachment 只存 File+objectURL）、`:124-135`（base64ImageOf）、`:286-291`；对比文件类立即上传 `:316-324` | 粘贴后立即发送，或拖拽/文件选择 | #6673 |
 | 32 | web-fetch NAT64 探测无守卫：无 DNS64 网络（ipv4only.arpa 不解析）下所有双栈主机 fetch 全灭 | `packages/web/web-fetch-http/src/network.ts:90-92`（无 try/catch）、`:113-134`（discoverNat64Prefixes）、`:38`；SSRF 检查独立（`:96-106`） | 无产品内规避；补丁方向=ENOTFOUND/ENODATA 视为无前缀 | #6664 |
+| 33 | 官方 cookbook 仍在教已删除的 `settings.plugin.item` 槽（alpha.2 已改为 `plugins.item` 列表槽：`id`/`order`/`label` + props `{view:'summary'|'page'}`） | `docs/cookbook/adding-a-settings-card.md:50,62-63`（+.zh；@ddefc45，0.1.6-alpha.2 世代）；正确槽树见 `docs/subsystems/slots.md:132-134`（`plugins.item`/`plugins.bundle.config`/`plugins.row.config`） | 照本 KB 订正版写（已本地改写并登记本条；重同步会复原，需按本条重新打补丁） | 无（上游 doc bug，未开帖） |
 
-## 2. 次级清单（已核实、优先级较低，6 项）
+## 2. 次级清单（已核实、优先级较低，7 项）
 
 | # | 问题 | 位置 | 规避 | 讨论 |
 |---|---|---|---|---|
@@ -58,6 +59,7 @@
 | S5 | cordis preset 的 SKILL.md 仍在教已废弃工具名（6 处旧名 vs 实现注册 7 个新名） | `packages/preset/agent-presets/presets/cordis/skills/editing-cordis-compositions/SKILL.md:32,34,64,80,118,122`；新名 `packages/extensions/tool-cordis/src/index.ts:45,64,100,152,244,333,355`；另有生成文件/文档残留 `tool-cordis/src/api-catalog.ts:6`、`cordis-client-runner/.../slot-catalog.ts:7,74`、`docs/subsystems/slots.md:176`（+.zh）与三个快照（`ui.expected.md:36`、`session.v2.jsonl:17`、`session.v3.jsonl:18`） | 文档修复型 PR；快照测试需重生成 | #6679 |
 | S6 | SIGTERM 无在途 turn 排空路径；5s 宽限硬编码；无 `dsh restart` | `apps/cli/src/process-shutdown.ts:4,69-75`；dispose=cancel+whenIdle `agent-loop/src/index.ts:594-595`；launcher 无 restart（`apps/cli/src/args.ts:145-201`） | 第二信号即强退是固定语义；drain 属 feature request | #6665 |
 | S7 | LLM 出站超时修复未合入；undici 全局 dispatcher 由 http-proxy 独占（>5min prefill 在 ~302s 被 body timeout 终止） | 无 `egress.ts`/`httpBodyTimeoutMs`；`llm-pi-ai/src/config.ts:46`（300s 空闲看门狗）、`adapter.ts:355`；`util/http-proxy/src/install.ts:208-220` | 每请求新建 fetch 绕过共享 socket 记账 | #5673 |
+| S8 | 创造模式 `cordis_define`/`cordis_run` 动态工具已退役 | 0.1.6-alpha.2 的 `docs/tool-catalog.md` 只剩两个只读检查工具（`cordis_inspect_list`/`cordis_inspect_query`）；运行期创作的替代面 = `plugin_manager` 工具 + `ctx.pluginManager` + `OPTIONAL_BUNDLES`（@ddefc45，0.1.6-alpha.2 世代） | 0.1.5-rc.2 世代 `docs/tool-catalog.md` 的 cordis_* 工具段（旧快照 :269-501）；`docs/capability-seams.md` 的 `ctx.dynamicCordisRunner` | 无（上游工具退役，非缺陷） |
 
 ## 3. 已在 master 修复（旧帖一律更新即可，无需改代码）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-guide",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "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.",
   "type": "module",
   "main": "index.js",
@@ -50,6 +50,7 @@
     "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "typecheck:ci": "tsc --noEmit --pretty false",
+    "typecheck:checkout": "tsc -p tsconfig.checkout.json --noEmit",
     "test": "vitest run",
     "check:readmes": "node scripts/check-readme-sync.mjs",
     "check:kit": "pwsh -File scripts/verify-kit.ps1",
@@ -63,12 +64,12 @@
     "typescript": "^5.9.3"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "0.1.5-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.1.7-alpha.2",
     "@types/node": "^22.20.1",
     "vitest": "^3.2.7"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0"
+    "@deepseek-ai/dsh": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0 || >=0.1.6-0 <0.2.0 || >=0.1.7-0 <0.2.0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh": {
@@ -105,7 +106,7 @@
       "filesystem:read"
     ],
     "compatibility": {
-      "dshVersions": ["0.1.2-rc.1","0.1.5-rc.2"]
+      "dshVersions": ["0.1.2-rc.1","0.1.5-rc.2","0.1.7-alpha.2"]
     },
     "capability": {
       "id": "dsh-plugin-guide",