dsh-plugin-guide 0.3.21 → 0.3.23

package/scripts/build-llms-full.mjs

@@ -0,0 +1,64 @@
+// build-llms-full.mjs — concatenate the knowledge base into llms-full.txt
+//
+// The KB ships a handful of long-form documents. LLM crawlers fetch a single
+// plain-text URL far more reliably than they walk a repository tree, so
+// `llms-full.txt` carries the whole corpus in reading order, and `llms.txt`
+// carries the index that points at it.
+//
+// Idempotent: re-running rewrites the file with identical bytes when the
+// sources are unchanged. Run it after editing any file in SOURCES.
+//
+//   node scripts/build-llms-full.mjs
+import { readFileSync, writeFileSync, existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+
+// Reading order: what a plugin author needs first, then the evidence base.
+const SOURCES = [
+  ['README.md', 'Overview'],
+  ['guide/plugin-dev-guide.md', 'Plugin development guide (10 chapters)'],
+  ['guide/quick-reference.md', 'Quick reference'],
+  ['guide/when-to-retire-a-plugin.md', 'When to retire or freeze a plugin'],
+  ['guide/choosing-a-plugin.md', 'Choosing a plugin: who leads each capability surface'],
+  ['guide/release-engineering.md', 'Release engineering'],
+  ['guide/unfixed-issues.md', 'Unfixed upstream issues (source-verified)'],
+  ['guide/links.md', 'Curated links'],
+  ['references/harness-repo.md', 'Harness repository reference'],
+  ['references/upstream-cordis.md', 'Upstream Cordis reference'],
+  ['references/cordis-paper-and-community.md', 'Cordis paper and community'],
+  ['references/community-ecosystem.md', 'Community ecosystem'],
+  ['references/community-repo-deep-dive.md', 'Community repository deep dive'],
+  ['references/website-pages.md', 'Official website pages'],
+  ['references/sources.md', 'Sources'],
+]
+
+const missing = SOURCES.filter(([rel]) => !existsSync(path.join(root, rel)))
+if (missing.length > 0) {
+  console.error('build-llms-full: missing sources:')
+  for (const [rel] of missing) console.error('  - ' + rel)
+  process.exit(1)
+}
+
+const header = [
+  '# dsh-plugin-guide — full knowledge base',
+  '',
+  '> DeepSeek Harness (dsh) plugin development knowledge base, in reading order.',
+  '> One document per section, each preceded by its source path so a citation can',
+  '> name the file it came from. Index: llms.txt. Repository:',
+  '> https://github.com/PerryLink/dsh-plugin-guide',
+  '',
+  `> Generated by scripts/build-llms-full.mjs from ${SOURCES.length} sources. Do not hand-edit.`,
+  '',
+].join('\n')
+
+const parts = [header]
+for (const [rel, title] of SOURCES) {
+  const body = readFileSync(path.join(root, rel), 'utf8').replace(/\r\n/gu, '\n').trimEnd()
+  parts.push(`\n\n<!-- source: ${rel} -->\n\n# [${title}] ${rel}\n\n${body}\n`)
+}
+
+const out = parts.join('')
+writeFileSync(path.join(root, 'llms-full.txt'), out, 'utf8')
+console.log(`llms-full.txt written: ${Buffer.byteLength(out)} bytes from ${SOURCES.length} sources`)

package/scripts/check-docs-drift.ps1

@@ -1,4 +1,4 @@
-# dsh-plugin-guide official-docs freshness probe.
+# dsh-plugin-guide official-docs freshness probe.
 # Purpose: detect drift between the KB mirror (references/official-docs) and the
 #   upstream deepseek-harness repository WITHOUT a local checkout. It compares the
 #   upstream branch tip SHA (git ls-remote) against the pinned "Source commit" SHA

package/scripts/sync-official-docs.ps1

@@ -1,4 +1,4 @@
-# dsh-plugin-guide official-docs sync script.
+# dsh-plugin-guide official-docs sync script.
 # Purpose: sync the deepseek-harness checkout's official docs into references/official-docs/ (verbatim copy).
 # Source is pinned to origin/master (HEAD fallback): untracked drafts and unpushed commits in the checkout never enter the KB.
 # Output: references/official-docs/SNAPSHOT.md (source ref/SHA, sync time, file counts - the freshness authority for READMEs).

package/templates/js/icon.svg

@@ -0,0 +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>

package/templates/js/locale/en.json

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

package/templates/js/locale/zh.json

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

package/templates/js/package.json

@@ -4,9 +4,16 @@
   "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"
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
   ],
   "scripts": {
     "test": "vitest run"
@@ -23,6 +30,7 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
     }

package/templates/ts/icon.svg

@@ -0,0 +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>

package/templates/ts/locale/en.json

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

package/templates/ts/locale/zh.json

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

package/templates/ts/package.json

@@ -5,9 +5,16 @@
   "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"
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg"
   ],
   "scripts": {
     "build": "tsdown",
@@ -32,6 +39,7 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "dsh": {
+    "manifestVersion": 1,
     "bundle": {
       "patch": "./cordis.patch.yml"
     }

package/references/official-docs/docs/subsystems/invariants.i18n.yaml

@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/invariants.md
-invariants.md: 2d1856dfd049a32076356bf6fa8736d4179881f2
-invariants.zh.md: 15760a9b116d03475970de762657e841e094c72a

package/references/official-docs/docs/subsystems/invariants.md

@@ -1,88 +0,0 @@
-# Runtime Invariants
-
-English | [中文](invariants.zh.md)
-
-[dsh-invariants](../../packages/runtime-diagnostics/invariants) is the configurable registry service (`ctx.invariants`) for package-owned runtime invariant checks. It is one support-group package, not a three-package capability seam, and not part of the agent-loop spine: the registry owns selection, name reservation, child-fiber lifecycle, and package-attributed failure, while every workspace package publishes a `./invariant` companion plugin that registers checks under its exact npm package name. What a check may assert — authoritative event streams or mutable data, never service or method presence — is the runtime-invariants convention in [AGENTS.md](../../AGENTS.md#conventions).
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-
-## Selection
-
-```ts type-equiv
-/** Runtime invariant selection configured on the service plugin. */
-interface Config {
-  /** Global switch; defaults to `true`. */
-  readonly enabled?: boolean
-  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
-  readonly package_allowlist?: string[]
-  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
-  readonly package_blocklist?: string[]
-}
-```
-
-A package is selected when the service is enabled, the allowlist is empty or at least one pattern matches its full npm name, and no blocklist pattern matches — a blocklist match overrides an allowlist match. Entries compile with `new RegExp(source)`: matching is unanchored unless the source supplies `^` and `$`, and `/pattern/flags` syntax is not parsed. Validation fails loud at service startup: a blank, whitespace-padded, duplicate, or invalid entry throws instead of being skipped. A valid pattern may match no currently loaded package, so later loading and HMR stay deterministic; filters are fixed for the service lifetime ([README](../../packages/runtime-diagnostics/invariants/README.md)).
-
-## The installer
-
-```ts type-equiv
-/**
- * Throw a package-attributed invariant failure.
- * @param message - violated package contract without the standard prefix.
- * @returns never because reporting a violation throws.
- */
-type InvariantFailure = (message: string) => never
-```
-
-```ts type-equiv
-/** Install one package's checks into the registration's child context. */
-interface InvariantInstaller {
-  /**
-   * Install the package contribution.
-   * @param ctx - child context owned by this invariant registration.
-   * @param fail - reporter bound to the registering package name.
-   * @returns nothing, or a promise settling after asynchronous checks finish.
-   */
-  (ctx: Context, fail: InvariantFailure): void | Promise<void>
-  /** Services the child installer fiber may access. */
-  readonly inject?: Inject
-}
-```
-
-An enabled installer runs in a dedicated child Cordis fiber; `installer.inject` declares the services that fiber may access, and synchronous or asynchronous installer completion is joined before the registration succeeds. `fail(message)` throws `InvariantError` — `extends Error` with stable `code: 'INVARIANT'`, the owning `packageName`, and a message prefixed `invariant violated by "<package>": …` — so a violation is attributable without the registry importing any product package.
-
-## The service
-
-`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name and returns its effect-scoped disposer. The reservation holds even when filters keep the installer inactive, so two plugins can never silently claim the same package name; a duplicate, blank, or whitespace-containing name throws. An installer failure disposes the child fiber and releases the reservation atomically. The service owns every registration fiber while the returned disposer also belongs to the companion fiber: unloading either side removes listeners, trace state, and the reservation, so a companion can reload and register the same name again without retained state.
-
-## The companion contract
-
-Every workspace package owns a `./invariant` companion ([package contract](../../packages/AGENTS.md)); publication and registration are exhaustive, but assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event or mutable-data relationship; otherwise it exports an empty installer whose leading comment starts `No runtime invariant:` and explains, package-specifically, why nothing is checkable. `pnpm run verify-package-invariants` mechanically rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, or bundle wiring ([mechanical-rule Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md)). The catalog of executable companions and the standard composition live in the [package README](../../packages/runtime-diagnostics/invariants/README.md).
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxinvariants--invariantregistry"></a>
-
-### `ctx.invariants` — `InvariantRegistry`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/invariants.zh.md

@@ -1,88 +0,0 @@
-# 运行时不变式
-
-[English](invariants.md) | 中文
-
-[dsh-invariants](../../packages/runtime-diagnostics/invariants) 是面向包自有运行时不变式检查的可配置注册表服务（`ctx.invariants`）。它是一个 support 组的包，不是三包能力 seam，也不属于 agent loop（智能体循环）主干：注册表拥有选择逻辑、名称保留、子 fiber 生命周期和归因到包的失败，而每个工作区包发布一个 `./invariant` 配套插件，以自己确切的 npm 包名注册检查。检查可以断言什么（权威事件流或可变数据，绝不是服务或方法是否存在）是 [AGENTS.md](../../AGENTS.md#conventions) 中的运行时不变式约定。
-
-源码：[`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-
-## 选择
-
-```ts type-equiv
-/** Runtime invariant selection configured on the service plugin. */
-interface Config {
-  /** Global switch; defaults to `true`. */
-  readonly enabled?: boolean
-  /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
-  readonly package_allowlist?: string[]
-  /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
-  readonly package_blocklist?: string[]
-}
-```
-
-一个包被选中的条件是：服务已启用，允许列表为空或至少一个模式匹配其完整 npm 名称，且没有任何阻止列表模式匹配；阻止列表匹配优先于允许列表匹配。条目用 `new RegExp(source)` 编译：除非模式自带 `^` 和 `$`，匹配不锚定；`/pattern/flags` 语法不被解析。校验在服务启动时明确报错：空白、首尾带空白、重复或无效的条目会抛出异常，而不是被跳过。有效模式可以不匹配任何当前已加载的包，因此后续加载与 HMR（热模块替换）保持确定性；过滤器在服务生命周期内固定不变（[README](../../packages/runtime-diagnostics/invariants/README.zh.md)）。
-
-## 安装器
-
-```ts type-equiv
-/**
- * Throw a package-attributed invariant failure.
- * @param message - violated package contract without the standard prefix.
- * @returns never because reporting a violation throws.
- */
-type InvariantFailure = (message: string) => never
-```
-
-```ts type-equiv
-/** Install one package's checks into the registration's child context. */
-interface InvariantInstaller {
-  /**
-   * Install the package contribution.
-   * @param ctx - child context owned by this invariant registration.
-   * @param fail - reporter bound to the registering package name.
-   * @returns nothing, or a promise settling after asynchronous checks finish.
-   */
-  (ctx: Context, fail: InvariantFailure): void | Promise<void>
-  /** Services the child installer fiber may access. */
-  readonly inject?: Inject
-}
-```
-
-被启用的安装器在专属的子 Cordis fiber 中运行；`installer.inject` 声明该 fiber 可以访问的服务，注册成功之前会先等待安装器同步或异步地执行完毕。`fail(message)` 抛出 `InvariantError`（`extends Error`，带稳定的 `code: 'INVARIANT'`、所属 `packageName`，以及前缀为 `invariant violated by "<package>": …` 的消息），因此违规可归因，而注册表无需导入任何产品包。
-
-## 服务
-
-`ctx.invariants.register(packageName, installer)` 为完整 npm 包名保留唯一一个活跃注册，并返回其绑定到 effect 的 disposer。即使过滤器使安装器保持不活跃，保留依然成立，因此两个插件绝不可能静默地认领同一个包名；重复、空白或含空白字符的名称会抛出异常。安装器失败会原子地 dispose（资源释放）子 fiber 并释放保留。服务拥有每个注册 fiber，而返回的 disposer 同时属于配套插件的 fiber：卸载任一侧都会移除监听器、trace 状态和保留项，因此配套插件可以重载并再次注册同一名称，不留残余状态。
-
-## 配套插件约定
-
-每个工作区包都拥有一个 `./invariant` 配套插件（[包约定](../../packages/AGENTS.md)）；发布与注册是穷尽式的，但刻意不合成断言。只有当包拥有某个可观察事件或某种可变数据关系时，配套插件才安装检查；否则它导出一个空安装器，其起始注释以 `No runtime invariant:` 开头，针对该包具体解释为什么没有可检查项。`pnpm run verify-package-invariants` 机械地拒绝「生成文件」标记、无解释的空安装器、遗漏或忽略报告器的非空安装器、错误的注册名称，以及不完整的导出、发布、依赖或打包接线（[机械规则 Agent Note](../../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md)）。可执行配套插件的目录与标准组合方式见[包 README](../../packages/runtime-diagnostics/invariants/README.zh.md)。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxinvariants--invariantregistry"></a>
-
-### `ctx.invariants` — `InvariantRegistry`
-
-Package-owned invariant registry with global and regex-based selection.
-
-```ts cordis-catalog
-/**
- * Register one package's invariant installer. The package name is reserved
- * even when filtering disables its checks. Enabled installers run in a child
- * fiber; failure disposes that fiber and releases the reservation.
- * @param packageName - full npm package name that owns the contribution.
- * @param installer - listener or startup-check installer for the child context.
- * @returns an effect-scoped disposer for the registration.
- */
-register(packageName: string, installer: InvariantInstaller): () => void
-```
-
-Source: [`packages/runtime-diagnostics/invariants/src/index.ts`](../../packages/runtime-diagnostics/invariants/src/index.ts)
-<!-- END GENERATED cordis-surface -->