dsh-plugin-guide 0.3.35 → 0.3.37

package/scripts/install-skill.ps1

@@ -1,63 +1,63 @@
-# dsh-plugin-guide skill installer.
-# Purpose: copy the KB (excluding generated/local-only parts) into an agent skill directory and verify byte parity.
-# Usage:   pwsh -File scripts/install-skill.ps1 -Target <skill-dir> [-Source <kb-root>]
-# Scope:   SKILL.md, guide/, references/ (incl. official-docs), scripts/, README*.md, LICENSE, NOTICE.md, CONTRIBUTING.md, SECURITY.md.
-# Excluded: downloads/ (generated by scripts), .github/ (CI), .gitignore.
-# Target must be the skill directory itself (e.g. ~/.deepseek/skills/dsh-plugin-guide or <project>/.agents/skills/dsh-plugin-guide).
-param(
-  [Parameter(Mandatory=$true)][string]$Target,
-  [string]$Source = ''
-)
-$ErrorActionPreference = 'Stop'
-if (-not $Source) { $Source = Split-Path $PSScriptRoot -Parent }
-$src = (Resolve-Path $Source).Path
-$top = @('SKILL.md','LICENSE','NOTICE.md','CONTRIBUTING.md','SECURITY.md') + @(Get-ChildItem $src -Filter 'README*.md' -File | ForEach-Object { $_.Name })
-$dirs = @('guide','references','scripts')
-
-New-Item -ItemType Directory -Force -Path $Target | Out-Null
-
-foreach ($f in $top) { Copy-Item (Join-Path $src $f) (Join-Path $Target $f) -Force }
-foreach ($d in $dirs) {
-  # Copy-Item -Recurse into an existing directory would nest the source inside it; replace the owned dir instead.
-  $td = Join-Path $Target $d
-  if (Test-Path $td) { Remove-Item $td -Recurse -Force }
-  Copy-Item (Join-Path $src $d) $td -Recurse -Force
-}
-
-# Prune target files under the owned scope that no longer exist in the source (keeps reinstalls clean).
-foreach ($d in $dirs) {
-  $td = Join-Path $Target $d
-  if (Test-Path $td) {
-    $sd = Join-Path $src $d
-    $sRoot = (Resolve-Path $sd).Path
-    $tRoot = (Resolve-Path $td).Path
-    Get-ChildItem -Recurse -File $td | ForEach-Object {
-      $rel = $_.FullName.Substring($tRoot.Length + 1)
-      if (-not (Test-Path (Join-Path $sRoot $rel))) { Remove-Item $_.FullName -Force }
-    }
-  }
-}
-Get-ChildItem $Target -File -ErrorAction SilentlyContinue | ForEach-Object {
-  if (($_.Name -like 'README*.md' -or $top -contains $_.Name) -and -not (Test-Path (Join-Path $src $_.Name))) { Remove-Item $_.FullName -Force }
-}
-
-# Parity report: every scoped source file must exist in the target byte-for-byte.
-$checked = 0; $mismatch = 0
-foreach ($f in $top) {
-  $s = Join-Path $src $f; $t = Join-Path $Target $f
-  if (Test-Path $t) { $checked++; if ((Get-FileHash $s -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $f" } }
-  else { $mismatch++; Write-Output "MISSING-TARGET: $f" }
-}
-foreach ($d in $dirs) {
-  $sd = Join-Path $src $d
-  $sRoot = (Resolve-Path $sd).Path
-  Get-ChildItem -Recurse -File $sd | ForEach-Object {
-    $rel = $_.FullName.Substring($sRoot.Length + 1)
-    $t = Join-Path (Join-Path $Target $d) $rel
-    if (Test-Path $t) { $checked++; if ((Get-FileHash $_.FullName -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $d\$rel" } }
-    else { $mismatch++; Write-Output "MISSING-TARGET: $d\$rel" }
-  }
-}
-Write-Output "DONE: $checked scoped files verified, $mismatch mismatches -> $Target"
-if ($mismatch -gt 0) { exit 1 }
-exit 0
+# dsh-plugin-guide skill installer.
+# Purpose: copy the KB (excluding generated/local-only parts) into an agent skill directory and verify byte parity.
+# Usage:   pwsh -File scripts/install-skill.ps1 -Target <skill-dir> [-Source <kb-root>]
+# Scope:   SKILL.md, guide/, references/ (incl. official-docs), scripts/, README*.md, LICENSE, NOTICE.md, CONTRIBUTING.md, SECURITY.md.
+# Excluded: downloads/ (generated by scripts), .github/ (CI), .gitignore.
+# Target must be the skill directory itself (e.g. ~/.deepseek/skills/dsh-plugin-guide or <project>/.agents/skills/dsh-plugin-guide).
+param(
+  [Parameter(Mandatory=$true)][string]$Target,
+  [string]$Source = ''
+)
+$ErrorActionPreference = 'Stop'
+if (-not $Source) { $Source = Split-Path $PSScriptRoot -Parent }
+$src = (Resolve-Path $Source).Path
+$top = @('SKILL.md','LICENSE','NOTICE.md','CONTRIBUTING.md','SECURITY.md') + @(Get-ChildItem $src -Filter 'README*.md' -File | ForEach-Object { $_.Name })
+$dirs = @('guide','references','scripts')
+
+New-Item -ItemType Directory -Force -Path $Target | Out-Null
+
+foreach ($f in $top) { Copy-Item (Join-Path $src $f) (Join-Path $Target $f) -Force }
+foreach ($d in $dirs) {
+  # Copy-Item -Recurse into an existing directory would nest the source inside it; replace the owned dir instead.
+  $td = Join-Path $Target $d
+  if (Test-Path $td) { Remove-Item $td -Recurse -Force }
+  Copy-Item (Join-Path $src $d) $td -Recurse -Force
+}
+
+# Prune target files under the owned scope that no longer exist in the source (keeps reinstalls clean).
+foreach ($d in $dirs) {
+  $td = Join-Path $Target $d
+  if (Test-Path $td) {
+    $sd = Join-Path $src $d
+    $sRoot = (Resolve-Path $sd).Path
+    $tRoot = (Resolve-Path $td).Path
+    Get-ChildItem -Recurse -File $td | ForEach-Object {
+      $rel = $_.FullName.Substring($tRoot.Length + 1)
+      if (-not (Test-Path (Join-Path $sRoot $rel))) { Remove-Item $_.FullName -Force }
+    }
+  }
+}
+Get-ChildItem $Target -File -ErrorAction SilentlyContinue | ForEach-Object {
+  if (($_.Name -like 'README*.md' -or $top -contains $_.Name) -and -not (Test-Path (Join-Path $src $_.Name))) { Remove-Item $_.FullName -Force }
+}
+
+# Parity report: every scoped source file must exist in the target byte-for-byte.
+$checked = 0; $mismatch = 0
+foreach ($f in $top) {
+  $s = Join-Path $src $f; $t = Join-Path $Target $f
+  if (Test-Path $t) { $checked++; if ((Get-FileHash $s -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $f" } }
+  else { $mismatch++; Write-Output "MISSING-TARGET: $f" }
+}
+foreach ($d in $dirs) {
+  $sd = Join-Path $src $d
+  $sRoot = (Resolve-Path $sd).Path
+  Get-ChildItem -Recurse -File $sd | ForEach-Object {
+    $rel = $_.FullName.Substring($sRoot.Length + 1)
+    $t = Join-Path (Join-Path $Target $d) $rel
+    if (Test-Path $t) { $checked++; if ((Get-FileHash $_.FullName -Algorithm MD5).Hash -ne (Get-FileHash $t -Algorithm MD5).Hash) { $mismatch++; Write-Output "MISMATCH: $d\$rel" } }
+    else { $mismatch++; Write-Output "MISSING-TARGET: $d\$rel" }
+  }
+}
+Write-Output "DONE: $checked scoped files verified, $mismatch mismatches -> $Target"
+if ($mismatch -gt 0) { exit 1 }
+exit 0

package/templates/js/icon.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="{{name}}">
-  <rect width="64" height="64" rx="14" fill="#1f6feb" />
-  <path d="M20 22h24v6H20zM20 32h24v6H20zM20 42h14v4H20z" fill="#ffffff" />
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="{{name}}">
+  <rect width="64" height="64" rx="14" fill="#1f6feb" />
+  <path d="M20 22h24v6H20zM20 32h24v6H20zM20 42h14v4H20z" fill="#ffffff" />
+</svg>

package/templates/js/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "{{name}}",
-    "description": "A DeepSeek Harness plugin scaffolded by dsh-plugin-dev."
-  }
-}
+{
+  "meta": {
+    "title": "{{name}}",
+    "description": "A DeepSeek Harness plugin scaffolded by dsh-plugin-dev."
+  }
+}

package/templates/js/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "{{name}}",
-    "description": "由 dsh-plugin-dev 脚手架生成的 DeepSeek Harness 插件。"
-  }
-}
+{
+  "meta": {
+    "title": "{{name}}",
+    "description": "由 dsh-plugin-dev 脚手架生成的 DeepSeek Harness 插件。"
+  }
+}

package/templates/js/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "{{pkgName}}",
-  "version": "{{version}}",
-  "description": "A DeepSeek Harness (DSH) plugin scaffolded by dsh-plugin-dev.",
-  "type": "module",
-  "main": "index.js",
-  "exports": {
-    ".": "./index.js",
-    "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
-  },
-  "files": [
-    "index.js",
-    "cordis.patch.yml",
-    "locale/*.json",
-    "icon.svg"
-  ],
-  "scripts": {
-    "test": "vitest run"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "vitest": "^3.2.7"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
-    "@deepseek-ai/schemastery": "^3.18.2"
-  },
-  "dsh": {
-    "manifestVersion": 1,
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "engines": {
-    "node": "^22.19.0 || >=24.0.0"
-  },
-  "packageManager": "pnpm@11.7.0",
-  "license": "Apache-2.0"
-}
+{
+  "name": "{{pkgName}}",
+  "version": "{{version}}",
+  "description": "A DeepSeek Harness (DSH) plugin scaffolded by dsh-plugin-dev.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "license": "Apache-2.0"
+}

package/templates/ts/icon.svg

@@ -1,4 +1,4 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="{{name}}">
-  <rect width="64" height="64" rx="14" fill="#1f6feb" />
-  <path d="M20 22h24v6H20zM20 32h24v6H20zM20 42h14v4H20z" fill="#ffffff" />
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="{{name}}">
+  <rect width="64" height="64" rx="14" fill="#1f6feb" />
+  <path d="M20 22h24v6H20zM20 32h24v6H20zM20 42h14v4H20z" fill="#ffffff" />
+</svg>

package/templates/ts/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "{{name}}",
-    "description": "A DeepSeek Harness plugin scaffolded by dsh-plugin-dev."
-  }
-}
+{
+  "meta": {
+    "title": "{{name}}",
+    "description": "A DeepSeek Harness plugin scaffolded by dsh-plugin-dev."
+  }
+}

package/templates/ts/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "{{name}}",
-    "description": "由 dsh-plugin-dev 脚手架生成的 DeepSeek Harness 插件。"
-  }
-}
+{
+  "meta": {
+    "title": "{{name}}",
+    "description": "由 dsh-plugin-dev 脚手架生成的 DeepSeek Harness 插件。"
+  }
+}

package/templates/ts/package.json

@@ -1,52 +1,52 @@
-{
-  "name": "{{pkgName}}",
-  "version": "{{version}}",
-  "description": "A DeepSeek Harness (DSH) plugin scaffolded by dsh-plugin-dev.",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": "./lib/index.js",
-    "./locale/*.json": "./locale/*.json",
-    "./icon": "./icon.svg"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "locale/*.json",
-    "icon.svg"
-  ],
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepare": "tsdown"
-  },
-  "dependencies": {
-    "tsdown": "^0.22.14",
-    "typescript": "^5.9.3"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@types/node": "^22.20.1",
-    "vitest": "^3.2.7"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
-    "@deepseek-ai/schemastery": "^3.18.2"
-  },
-  "dsh": {
-    "manifestVersion": 1,
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "engines": {
-    "node": "^22.19.0 || >=24.0.0"
-  },
-  "packageManager": "pnpm@11.7.0",
-  "license": "Apache-2.0"
-}
+{
+  "name": "{{pkgName}}",
+  "version": "{{version}}",
+  "description": "A DeepSeek Harness (DSH) plugin scaffolded by dsh-plugin-dev.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": "./lib/index.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepare": "tsdown"
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^22.20.1",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": "{{dshPeerRange}}",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "license": "Apache-2.0"
+}

package/templates/ts/tsdown.config.mjs

@@ -1,21 +1,21 @@
-import { defineConfig } from 'tsdown'
-
-// tsdown bundles src/index.ts into lib/index.js (ESM) and emits lib/index.d.ts.
-// It is also the self-contained `prepare` script for git installs: no project
-// references, no type checking (see guide §7.1 "build-script catch").
-export default defineConfig({
-  entry: { index: 'src/index.ts' },
-  format: ['esm'],
-  platform: 'node',
-  target: 'node22',
-  dts: true,
-  clean: true,
-  sourcemap: false,
-  outDir: 'lib',
-  // With `platform: node` tsdown forces `.mjs`/`.cjs`; disable that so ESM output
-  // follows the package `"type": "module"` and emits `lib/index.js` +
-  // `lib/index.d.ts` — the paths this template's package.json declares. Without
-  // this flag the build emits `lib/index.mjs`/`lib/index.d.mts`, `main` resolves
-  // to nothing, and the plugin silently never loads.
-  fixedExtension: false,
-})
+import { defineConfig } from 'tsdown'
+
+// tsdown bundles src/index.ts into lib/index.js (ESM) and emits lib/index.d.ts.
+// It is also the self-contained `prepare` script for git installs: no project
+// references, no type checking (see guide §7.1 "build-script catch").
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm'],
+  platform: 'node',
+  target: 'node22',
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  outDir: 'lib',
+  // With `platform: node` tsdown forces `.mjs`/`.cjs`; disable that so ESM output
+  // follows the package `"type": "module"` and emits `lib/index.js` +
+  // `lib/index.d.ts` — the paths this template's package.json declares. Without
+  // this flag the build emits `lib/index.mjs`/`lib/index.d.mts`, `main` resolves
+  // to nothing, and the plugin silently never loads.
+  fixedExtension: false,
+})

package/references/official-docs/docs/defensive-patterns.i18n.yaml

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for defensive-patterns.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/defensive-patterns.md
-/defensive-patterns:
-  en: 6316b1da0ae4561b
-  zh: f059647429c707d5
-/defensive-patterns/report-orthogonal-outcomes-independently:
-  en: 09cdbaa7cf763dc9
-  zh: 11e5c13d77b2a563
-/defensive-patterns/honor-public-contracts-on-both-sides:
-  en: 157f966db7329171
-  zh: 80da311819125f36
-/defensive-patterns/async-state-is-not-synchronous-state:
-  en: 33085f2b58bab16c
-  zh: be38e69a9c7d3f0e
-/defensive-patterns/dispose-must-reach-quiescence-not-just-request-it:
-  en: 5c906be504b88a65
-  zh: 8f428f59a87bb1a8
-/defensive-patterns/contain-callback-exceptions-in-the-dispatcher:
-  en: 3275390293995f44
-  zh: 4d143e99a2a7c8cb
-/defensive-patterns/never-hand-untrusted-output-the-ambient-environment-or-predictable-paths:
-  en: 09ad9d6433026468
-  zh: cc0ba1a52859bb08
-/defensive-patterns/unlink-link-shaped-paths:
-  en: 644e6b1a9bd7b7d7
-  zh: 823600c76c81ead1

package/references/official-docs/docs/defensive-patterns.md

@@ -1,33 +0,0 @@
-# Defensive patterns
-
-English | [中文](defensive-patterns.zh.md)
-
-Hard-won bug-class rules: each pattern below is a class of defect that actually shipped or nearly shipped here, stated as the rule that prevents its recurrence. Read this before writing lifecycle, concurrency, subprocess, or teardown code. Test-tier counterparts (real entry path, world-verification, resource ownership) are in [testing.md](testing.md).
-
-## Report orthogonal outcomes independently
-
-A result can be several things at once — a process can time out AND exit 0 because it trapped the signal. Surface each independent fact (`timedOut`, `signal`, `exitCode`) on its own; never nest one flag's report inside another's branch, or a caller reads a cut-short run as a clean success.
-
-## Honor public contracts on BOTH sides
-
-When an implementation receives several representations of one outcome, normalize them before returning through the public API. `LlmAdapter.stream()` implementations may throw or emit `finish {kind:'error'|'aborted'}`, but `LlmRuntime.stream()` exposes model-request failures only as terminal finish chunks; middleware and consumer defects remain thrown. This keeps consumers from guessing whether a caught exception came from the provider, a wrapper, chunk logging, or their own assembly. Document the normalized contract where the type is defined; exercise every source form through the real consumer.
-
-## Async state is not synchronous state
-
-`agent.followup()` has no per-message completion or result; a background job's completion races turn boundaries; `reader.close()` fires for both EOF and disposal. Never treat `agent/status` or `whenIdle()` as the result of one follow-up: several queued follow-ups, steering, and injected work may share one `running` interval, while cancellation or disposal can discard unstarted items. An automation caller that truly owns a run must define its interval explicitly—for example, from its message's durable inbox receipt through the next whole-agent `idle`—and describe any selected output as interval-wide rather than causally attributed to that message. The guard cuts both ways: if the awaited transition can never occur, the wait hangs, so handle the "nothing to wait for" branch explicitly.
-
-## Dispose must reach quiescence, not just request it
-
-A teardown that issues kills/aborts but returns before the work stops leaves orphans. Make cleanup async and await the children's exit (kill → await `done`), and close listener/notification registries BEFORE killing so late completions stay silent.
-
-## Contain callback exceptions in the dispatcher
-
-Catch and report each listener's exception without rejecting the dispatch promise or starving later listeners. The listener's owner must handle state it mutates under the [error-handling rules](../.agents/skills/dsh-error-handling/SKILL.md#catch-recover-or-stop); catching alone does not restore state.
-
-## Never hand untrusted output the ambient environment or predictable paths
-
-Spawned commands get a scrubbed env (drop `*KEY*`/`*SECRET*`/`*TOKEN*`/`*PASSWORD*`) so harness credentials cannot leak into output, `env`, or spill files. Temp/spill files use a private (0700) dir, random names, and exclusive owner-only opens (`'wx'`, `0o600`) — predictable world-readable paths invite symlink races and disclosure.
-
-## Unlink link-shaped paths
-
-A path that may be a symlink or Windows junction is removed with `lstatSync().isSymbolicLink()` then `unlinkSync`: unlink deletes only the link and refuses a real directory, so it never follows the link into its target. Windows `rmSync(link)` throws `ERR_FS_EISDIR` on a junction; recursive deletion may descend through one into its target. Reserve recursive `rmSync` for known real directories.

package/references/official-docs/docs/defensive-patterns.zh.md

@@ -1,35 +0,0 @@
-# 防御性模式
-
-[English](defensive-patterns.md) | 中文
-
-来之不易的缺陷类别规则：下面每条模式都是本项目实际发布或差点发布的一类缺陷，以防止其复发的规则形式陈述。在编写生命周期、并发、子进程或清理代码之前请先阅读本文。测试层面的对应规则（真实入口路径、验证实际结果、资源归属）见 [testing.md](testing.zh.md)。
-
-## 正交结果独立上报
-
-一个结果可以同时具有多种性质：进程可能已经超时，却仍以退出码 0 结束，因为它捕获了终止信号。每个独立事实（`timedOut`、`signal`、`exitCode`）都应单独上报；切勿把一个标志的上报嵌套在另一个标志的分支中，否则调用方可能把提前终止的运行误判为正常成功。
-
-## 公共约定两侧都要遵守
-
-当一个实现收到同一结果的多种表示时，应在通过公共 API 返回前将其规范化。`LlmAdapter.stream()` 的实现可以抛出异常或发出 `finish {kind:'error'|'aborted'}`，但 `LlmRuntime.stream()` 只会通过终止型 finish 分片暴露模型请求失败；middleware 缺陷与消费方缺陷仍会以异常形式抛出。这使消费方不必猜测捕获的异常究竟来自提供方、包装层、分片日志记录还是自身组装逻辑。请在类型定义处记录规范化后的约定；通过真实消费方覆盖每种来源形式。
-
-## 异步状态不是同步状态
-
-`agent.followup()` 没有逐消息的完成状态或结果；后台任务的完成与轮次边界存在竞争；`reader.close()` 在 EOF 和 dispose（资源释放）两种情况下都会触发。切勿把 `agent/status` 或 `whenIdle()` 当作某次 `followup()` 的结果：多条已排队的后续消息、steering（中途引导）和注入工作可能共用同一个 `running` 区间，而取消或资源释放可能丢弃尚未启动的项。真正拥有一次运行的自动化调用方必须显式定义其区间——例如从消息的持久 inbox 回执到整个 agent（智能体）下一次进入 `idle`——并将选取的任何输出描述为整个区间的输出，而不是把因果关系归于该消息。这条守则是双向的：如果等待的转换永远不会发生，等待就会挂起，因此应显式处理「无需等待」的分支。
-
-<a id="dispose-must-reach-quiescence-not-just-request-it"></a>
-
-## dispose 必须达到完全停稳，而不仅仅是请求停止
-
-如果清理流程只发出终止或中止信号便返回，而不等待工作真正停止，就会留下孤儿进程。清理逻辑应采用异步流程，并等待子进程退出（发出终止信号后等待 `done`）；还应在终止进程前关闭监听器注册表和通知注册表，使迟到的完成事件保持静默。
-
-## 在分发器中隔离回调异常
-
-逐个捕获并报告监听器的异常，不让分发 promise 被 reject，也不让后续监听器失去执行机会。监听器的所有者必须按[错误处理规范](../.agents/skills/dsh-error-handling/SKILL.md#catch-recover-or-stop)处置其修改的状态；仅捕获异常不会恢复状态。
-
-## 绝不将环境变量或可预测路径暴露给不可信输出
-
-启动的命令应使用经过清理的环境变量，移除名称匹配 `*KEY*`、`*SECRET*`、`*TOKEN*` 或 `*PASSWORD*` 的项，防止 harness 凭证通过命令输出、`env` 或 spill 文件泄漏。临时文件和 spill 文件应放在权限为 0700 的私有目录中，使用随机文件名，并以独占且仅所有者可访问的方式打开（`'wx'`、`0o600`）；可预测且全局可读的路径会引发符号链接竞态和信息泄露。
-
-## 用 unlink 删除链接形态的路径
-
-可能是符号链接或 Windows junction 的路径，应先用 `lstatSync().isSymbolicLink()` 判断，再用 `unlinkSync` 删除：unlink 只删除链接本身并拒绝真实目录，因此绝不会跟随链接进入其目标。Windows 上对 junction 调用 `rmSync(link)` 会抛 `ERR_FS_EISDIR`；递归删除可能穿过 junction 进入其目标。真实目录才使用带 `recursive` 的 `rmSync`。