dsh-plugin-guide 0.2.0 → 0.3.2

package/references/official-docs/packages/README.md

@@ -1,69 +1,114 @@
+---
+description: "The DeepSeek Harness package workspace: how the npm packages under packages/ are grouped, what each group owns, and the conventions that bind them."
+kind: "package-group"
+---
+
 # Packages
 
 English | [中文](README.zh.md)
 
-npm scope: `@deepseek-ai/dsh-*`; Cordis `Service` subclasses and function plugins contribute through `ctx.effect()`, `ctx.on()`, or `ctx.waterfall()`. Rules: [package](AGENTS.md), [root](../AGENTS.md#conventions).
-
-## Hierarchy
-
-Groups hold `packages/<group>/<pkg>/`; names stay `@deepseek-ai/dsh-<pkg>`. **Group READMEs own package/ctx-key maps.**
-
-| Group | Role | Release expectation |
-|---|---|---|
-| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable API |
-| [`api/`](api/README.md) | Remote BFF assembly and Typert RPC gateway | Product — stable API |
-| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry | Product — stable API |
-| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle | Product — stable API |
-| [`schedule/`](schedule/README.md) | Session-local scheduled follow-ups | Product — stable API |
-| [`feedback/`](feedback/README.md) | Human feedback | Product — stable API |
-| [`identity/`](identity/README.md) | Shared anonymous identity | Product — stable API |
-| [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable API |
-| [`e2b/`](e2b/README.md) | E2B providers | POC |
-| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider | Product — stable API |
-| [`shell/`](shell/README.md) | Bash capability family: executor seam, local impl, model-facing tool | Product — stable API |
-| [`terminal/`](terminal/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, and model-facing tools | Product — stable API |
-| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + Code Mode Consumer | Product — stable API |
-| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends | Product — stable API |
-| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, bash-backed discovery tools | Product — stable API |
-| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool | Product — stable API |
-| [`skill/`](skill/README.md) | Skill capability family: the provider registry, local provider, and model-facing catalog/loader | Product — stable API |
-| [`compaction/`](compaction/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer | Product — stable API |
-| [`context/`](context/README.md) | Model-visible request context, including workspace instructions and time context | Product — stable API |
-| [`subagent/`](subagent/README.md) | Subagent capability family: the provider-registry contract and the model-facing delegation tool | Product — stable API |
-| [`jobs/`](jobs/README.md) | Generic background-job runtime and model-facing `job_*` control tools | Product — stable API |
-| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools | Product — stable API |
-| [`web/`](web/README.md) | Web capability family: seam, search/fetch provider impls, and the model-facing web tools | Product — stable API |
-| [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage | Product — stable API |
-| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable API |
-| [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable API |
-| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable API |
-| [`preset/`](preset/README.md) | Per-session agent composition from preset `cordis.yml` files | Product — stable API |
-| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer | Product — stable API |
-| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable API |
-| [`extensions/`](extensions/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written plugin mount/unmount ([design](../.agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable API |
-| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable API |
-| [`session/`](session/README.md) | Durable session data plane: persistence seam + JSONL/SQLite backends, projection seam, log-backed titles, session reporting | Product — stable API |
-| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, event relationships, semantic filtering, and SQLite full-text search | Product — stable API |
-| [`settings/`](settings/README.md) | User-settings seam + file-backed provider | Product — stable API |
-| [`credentials/`](credentials/README.md) | Credential-reference seam + env-over-`.env` provider | Product — stable API |
-| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form | Product — stable API |
-| [`workspace/`](workspace/README.md) | Workspace entity | Product — stable API |
-| [`sdk/`](sdk/README.md) | Out-of-process runtime SDK: JSON-RPC protocol, TypeScript client, and server plugin | Product — stable API |
-| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server | Product — stable API |
-| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool | Product — stable API |
-| [`boot/`](boot/README.md) | Shared app-bin boot glue | Product — stable API |
-| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server | Product — stable API |
-| [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins | Product — stable API |
-| [`examples/`](examples/README.md) | Demo bundles (agent-spine + CLI/ACP/JSON-RPC bins) leaves load | Support — example infra |
-| [`test-support/`](test-support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
-| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |
-
-New packages join existing groups; new groups update their README and this table.
+## Summary
+
+The harness is assembled from npm packages under `packages/`, grouped by capability family: sessions and the agent loop, model-facing tools, shell and filesystem execution, web access, subagents, and the rest. Use this page as the top-level map: find the owning group, then open its README for the package list. Every package is scoped `@deepseek-ai/dsh-*` and lives in exactly one group; each group README is the authoritative package map for its family.
+
+## Table of Contents
+
+- [Package groups](#package-groups)
+- [Release expectations](#release-expectations)
+- [Dependencies](#dependencies)
+- [Package README contracts](#package-readme-contracts)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="package-groups"></a>
+## Package groups
+
+Every package lives in exactly one group; new packages join existing groups, and a new group updates its own README and this table.
+
+| Group | Role |
+|---|---|
+| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop |
+| [`api/`](api/README.md) | Remote BFF assembly and Typert RPC gateway |
+| [`typert/`](typert/README.md) | Type graph generation, artifact loading, and runtime registry |
+| [`goal/`](goal/README.md) | Same-session goal persistence and lifecycle |
+| [`schedule/`](schedule/README.md) | Session-local scheduled follow-ups |
+| [`feedback/`](feedback/README.md) | Human feedback capture and command |
+| [`identity/`](identity/README.md) | Shared anonymous identity |
+| [`llm/`](llm/README.md) | LLM capability family: abstract service + provider adapters |
+| [`e2b/`](e2b/README.md) | E2B remote-runtime providers |
+| [`subprocess/`](subprocess/README.md) | Subprocess capability family: Service Definition + local process-tree provider |
+| [`shell/`](shell/README.md) | Bash capability family: executor seam, local impl, model-facing tools |
+| [`terminal/`](terminal/README.md) | Persistent PTY capability family: owner-scoped sessions, local implementation, model-facing tools |
+| [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: Service Definition + worker-thread provider + PTC mode Consumer |
+| [`sandbox/`](sandbox/README.md) | Process-confinement seam; bwrap/Landlock/Seatbelt backends |
+| [`fs/`](fs/README.md) | Filesystem capability family: seam, local impl, model-facing file tools, discovery tools |
+| [`lsp/`](lsp/README.md) | LSP capability family: seam, generic stdio provider, and the `lsp` tool |
+| [`skill/`](skill/README.md) | Skill capability family: provider registry, local provider, model-facing catalog/loader |
+| [`compaction/`](compaction/README.md) | Compaction capability family: Service Definition + basic provider + command Consumer |
+| [`context/`](context/README.md) | Model-visible request context: workspace instructions, time context, references |
+| [`subagent/`](subagent/README.md) | Subagent capability family: provider-registry contract and model-facing delegation tools |
+| [`jobs/`](jobs/README.md) | Generic background-job runtime and model-facing job control tools |
+| [`experimental/`](experimental/README.md) | Private prototypes and internal-only plugins |
+| [`workflow/`](workflow/README.md) | Workflow seam, worker-thread engine, and model-facing `workflow`/`ralph` tools |
+| [`webhook/`](webhook/README.md) | Verified external events, trusted rules, and fire-and-forget Workspace Sessions |
+| [`web/`](web/README.md) | Web capability family: seam, search/fetch providers, model-facing web tools |
+| [`attachment/`](attachment/README.md) | Durable attachment identity, validation, local content-addressed storage |
+| [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy |
+| [`todo/`](todo/README.md) | The model-facing `todo_write` tool |
+| [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit |
+| [`preset/`](preset/README.md) | Per-session agent composition from preset `cordis.yml` files |
+| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders + the `tools/execute` deadline enforcer |
+| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers |
+| [`extensions/`](extensions/README.md) | Agent runtime self-modification: live plugin/service inspection and model-written mount/unmount |
+| [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library |
+| [`session/`](session/README.md) | Durable session data plane: persistence seam + backends, projection seam, log-backed titles, session reporting |
+| [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, bounded reads, lineage, semantic filtering, SQLite full-text search |
+| [`settings/`](settings/README.md) | User-settings seam + file-backed provider |
+| [`credentials/`](credentials/README.md) | Credential-reference and credential-record seam + env-over-`.env` provider + authorization flows that ask a human |
+| [`storage/`](storage/README.md) | Non-session storage hub + backends + domain form |
+| [`workspace/`](workspace/README.md) | Workspace entity |
+| [`sdk/`](sdk/README.md) | Out-of-process SDK: JSON-RPC protocol and TypeScript client/server |
+| [`acp/`](acp/README.md) | Automation-only Agent Client Protocol server |
+| [`interaction/`](interaction/README.md) | Human-collaboration plane: approval/interaction seams, permission preset, commands, ask-user tool |
+| [`boot/`](boot/README.md) | Shared app-bin boot glue |
+| [`host/`](host/README.md) | Web-GUI host half: API gateway + HTTP route server |
+| [`client/`](client/README.md) | Web-GUI browser half: shell, wire, object services, slots, `ui-*` plugins |
+| [`test-support/`](test-support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) |
+| [`runtime-diagnostics/`](runtime-diagnostics/README.md) | Runtime diagnostics: package-owned invariant checks and reports |
+| [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, home/path helpers, timeout, retention) |
+
+-----
+
+<a id="release-expectations"></a>
+## Release expectations
 
+Most groups are product — stable API. The exceptions: `e2b/` is a POC, `experimental/` is unreleased, and `test-support/`, `runtime-diagnostics/`, and `util/` are support with lower compatibility expectations.
+
+-----
+
+<a id="dependencies"></a>
 ## Dependencies
 
 The dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).
 
-**Extension plugins depend on Service Definitions, never concrete providers.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles, including `dsh-agent-spine-demo`, may depend on spine plugins. Capabilities separate Service Definition / Service Provider / Consumer roles when they evolve independently; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
+**Extension plugins depend on Service Definitions, never concrete providers.** `dsh-agent-loop` is swappable; UI, hook, and tool plugins use `dsh-agent`. Composition bundles may depend on spine plugins. Capabilities separate Service Definition / Service Provider / Consumer roles when they evolve independently; see [capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md).
+
+-----
+
+<a id="package-readme-contracts"></a>
+## Package README contracts
+
+Every package README covers purpose, configuration, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts) exempts it. It also carries `## Known Limitations and Deferred Work` or uses its [allowlist](../scripts/verify-package-readme-limitations.ts). Package conventions — exports, service access, invariants, tests — live in [packages/AGENTS.md](AGENTS.md).
+
+-----
+
+<a id="dev-note"></a>
+## Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
 
-Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
+</details>

package/references/official-docs/vendor/README.md

@@ -48,6 +48,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 16. **`cordis/package.json` publishes `src`**: added `src` to the `files` list, joining the other eight vendored packages. Cordis declares `"./src/*": "./src/*"` in its exports, so a tarball without `src` publishes an export map pointing at absent files; the release change judgement also reads `files` to decide whether a diff reaches the payload, and a package whose only published paths are build output has no tracked path to match.
 17. **`@deepseek-ai` rescope**: every vendored manifest `name`, every internal dependency entry among the vendored set, and every module specifier that reaches them use the scoped names in the manifest table's `npm name` column. Directory names, version numbers, and dependency ranges are unchanged, and no upstream runtime identifier is renamed — `Symbol.for('schemastery')` and Schemastery's `vendor:` metadata field keep their upstream values. Re-apply with `pnpm run rescope-vendor --apply` after a sync; the table's two name columns are the mapping, restated for consumers in [docs/rescope.md](../docs/rescope.md).
 18. **Entry `disabled` interpolation in `loader/src/config/entry.ts`**: a `disabled: !!js` expression evaluates against the loader context at every mount decision; the raw node stays in the options, so write-back keeps the `!!js` form. `disabled` is the only interpolated metadata field. Covered by `packages/boot/app-boot/tests/user-patches.spec.ts` and `apps/cli/tests/windows-shell.spec.ts`.
+19. **`loader/src/internal.ts` runtime shape detection**: `ModuleLoader.fromInternal()` classifies the internal loader by which module-job API it owns — `getOrCreateModuleJob` for v2, `getModuleJobForImport` for v1 — instead of by Node major version. Upstream tags every major `>= 24` as v2, but the v2 interface arrived in Node 24.12.0, so 24.0–24.11.1 report major 24 while still carrying the v1 loader; consumers then called `resolveSync` with reversed parameters and every call threw. `dsh web` served an empty client graph (`__DSH_BOOT__.entries: []`) and HMR partial reload resolved no entry URL, both behind swallowed or warn-level errors. Arity cannot discriminate the two shapes, because each reports `resolveSync.length === 2`. A loader owning neither API is left unclassified rather than guessed, so consumers take their documented no-internals path. Covered on the `node-compat` Node version matrix, which pins 24.9 for the mistagged range.
 
 ## Sync procedure
 

package/references/official-docs/website-docs.ts

@@ -138,6 +138,30 @@ const homeAndGuide = pairedPages([
     section: { root: 'SDK', en: 'SDK' },
     order: 1,
   },
+  {
+    source: 'docs/user/guide/github-review.md',
+    route: 'guide/github-review.md',
+    label: { root: 'GitHub 评审会话', en: 'GitHub review sessions' },
+    sidebar: { root: 'zh-guide', en: 'en-guide' },
+    section: { root: '自动化', en: 'Automation' },
+    order: 1,
+  },
+  {
+    source: 'docs/user/guide/schedule.md',
+    route: 'guide/schedule.md',
+    label: { root: '会话内提醒', en: 'Session reminders' },
+    sidebar: { root: 'zh-guide', en: 'en-guide' },
+    section: { root: '自动化', en: 'Automation' },
+    order: 2,
+  },
+  {
+    source: 'docs/user/guide/mcp-memory.md',
+    route: 'guide/mcp-memory.md',
+    label: { root: '记忆 MCP', en: 'Memory MCP' },
+    sidebar: { root: 'zh-guide', en: 'en-guide' },
+    section: { root: '集成', en: 'Integrations' },
+    order: 1,
+  },
 ])
 
 const develop = pairedPages([
@@ -216,6 +240,14 @@ const develop = pairedPages([
     section: { root: '实战', en: 'Practice' },
     order: 2,
   },
+  {
+    source: 'docs/user/develop/practice/dynamic-cordis.md',
+    route: 'develop/practice/dynamic-cordis.md',
+    label: { root: '运行时 Cordis 工具', en: 'Runtime Cordis tools' },
+    sidebar: { root: 'zh-develop', en: 'en-develop' },
+    section: { root: '实战', en: 'Practice' },
+    order: 3,
+  },
 ])
 
 const cordisTutorial = pairedPages(([
@@ -304,8 +336,11 @@ const subsystemGroups = [
   ]],
   ['平台与接入', 'Platform and access', [
     ['web-server.md', 'HTTP 服务器', 'HTTP server'],
-    ['typert.md', 'Typert', 'Typert'],
+    ['web-client.md', 'Web Client 架构', 'Web Client architecture'],
     ['client-modules.md', '客户端模块', 'Client modules'],
+    ['slots.md', '客户端 Slots', 'Client slots'],
+    ['conversation.md', 'Conversation 组装', 'Conversation assembly'],
+    ['typert.md', 'Typert', 'Typert'],
     ['storage.md', '存储', 'Storage'],
     ['workspace.md', '工作区', 'Workspaces'],
     ['settings.md', '用户设置', 'User settings'],
@@ -328,6 +363,8 @@ const subsystemsReference = subsystemGroups.flatMap(([rootSection, enSection, fi
 ))
 
 const reference = [
+  // `docs/deepseek-llm-api-wire-extensions.md` is a repository-only provider protocol reference.
+  // Projected links intentionally resolve to its GitHub source instead of a public site route.
   ...pairedPages(([
     ['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
   ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
@@ -342,6 +379,7 @@ const reference = [
     ['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
     ['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
     ['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
+    ['docs/api-gateway.md', 'reference/api-gateway.md', 'API Gateway', 'API Gateway', 5],
   ] as const).map(([source, route, rootLabel, enLabel, order]): PairedPage => ({
     source,
     route,
@@ -392,6 +430,7 @@ const reference = [
     ['adding-a-package.md', '新增 Package', 'Adding a package'],
     ['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
     ['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
+    ['adding-a-settings-card.md', '新增设置卡片', 'Adding a settings card'],
     ['extension-cookbook.md', '扩展模式', 'Extension patterns'],
   ] as const).map(([file, rootLabel, enLabel], order): PairedPage => ({
     source: `docs/cookbook/${file}`,
@@ -401,16 +440,18 @@ const reference = [
     section: { root: '开发手册', en: 'Cookbook' },
     order,
   }))),
-  ...pairedPages([{
-    source: 'docs/cookbook/adding-a-conversation-node.md',
-    route: 'reference/cookbook/adding-a-conversation-node.md',
-    label: { root: '新增 Conversation Node', en: 'Adding a Conversation Node' },
-    sidebar: { root: 'zh-reference', en: 'en-reference' },
-    section: { root: '开发手册', en: 'Cookbook' },
-    order: 4,
-  }]),
 ]
 
+/**
+ * Sidebar collections of each locale, in the order the site's navigation
+ * presents them. The navigation bar and the llms.txt index both read this
+ * sequence, so a new collection lands in both surfaces together.
+ */
+export const localeCollections = {
+  root: ['zh-guide', 'zh-develop', 'zh-reference'],
+  en: ['en-guide', 'en-develop', 'en-reference'],
+} as const satisfies Record<DocsLocale, readonly DocsSidebar[]>
+
 /** A sidebar group, matched to pages by `label`. */
 export interface DocsSection {
   /** Group heading, equal to the `section` field of every page it holds. */
@@ -427,7 +468,7 @@ export interface DocsSection {
  */
 const sections: Record<DocsLocale, readonly DocsSection[]> = {
   root: [
-    { label: '入门' }, { label: 'SDK' },
+    { label: '入门' }, { label: 'SDK' }, { label: '自动化' }, { label: '集成' },
     { label: '基础' }, { label: '框架能力' }, { label: '实战' }, { label: 'Cordis 框架教程' },
     { label: '概念' }, { label: '生成参考' }, { label: 'Cordis API' }, { label: '开发手册' },
     { label: '总览' },
@@ -439,7 +480,7 @@ const sections: Record<DocsLocale, readonly DocsSection[]> = {
     { label: '平台与接入', collapsed: true },
   ],
   en: [
-    { label: 'Guide' }, { label: 'SDK' },
+    { label: 'Guide' }, { label: 'SDK' }, { label: 'Automation' }, { label: 'Integrations' },
     { label: 'Basics' }, { label: 'Framework' }, { label: 'Practice' }, { label: 'Cordis framework tutorial' },
     { label: 'Concepts' }, { label: 'Generated reference' }, { label: 'Cordis Core API' }, { label: 'Cookbook' },
     { label: 'Overview' },

package/references/sources.md

@@ -26,7 +26,7 @@
 - `/reference/`（架构）、`/reference/cordis-primer`、`/reference/capability-seams`、`/reference/agent-lifecycle`、`/reference/tool-execution-pipeline`
 - `/reference/config-catalog`、`/reference/tool-catalog`、`/reference/persistence-catalog`
 - `/reference/cordis-api/context|events|fiber|registry|service|inherited`
-- `/reference/cookbook/adding-a-package|adding-a-tool|adding-an-llm-adapter|extension-cookbook|adding-a-conversation-node`
+- `/reference/cookbook/adding-a-package|adding-a-tool|adding-an-llm-adapter|extension-cookbook`
 - `/reference/subsystems/` + 全部子系统页（core、llm-streaming、token-meter、scope、typert、goal、schedule、commands、session、persistence、settings、credentials、session-query、feedback、session-title、session-reference、system-prompt、tools、user-questions、approval、attachment、shell、subprocess、terminal、sandbox、code-runtime、extensions、filesystem、lsp、skills、compaction、subagent、web、spill、workflow、jobs、permission-presets、plan、invariants、web-server、storage、workspace、client-modules、session-projection、session-telemetry）
 - 站点投影清单源文件：`references/official-docs/website-docs.ts`（= 仓库 `website/docs.ts`）
 - **08-14 晚复核**：上游 master 仍为 47f9438（站点随仓库构建，无新增路由）；此前 404 的 `/reference/subsystems/{attachment,extensions,feedback}` 仍为 404（已确认），sitemap.xml 仍不存在。
@@ -35,7 +35,7 @@
 
 - `docs/**`（215 个 md，含全部 `.zh.md` 双语对）— 教程/架构/子系统/API/cookbook 全量
 - 仓库根文件（**2026-08-14 晚新增**）：`AGENTS.md`、`CLAUDE.md`（上游为 symlink→AGENTS.md，副本存其目标文本）、`BENCHMARK.md`、`CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`、`README.zh.md`/`.i18n.yaml`、`THIRD_PARTY_NOTICES.md`、`LICENSE`
-- `packages/AGENTS.md` · `examples/AGENTS.md` · `packages/README.md` · `vendor/README.md`
+- `packages/AGENTS.md` · `packages/README.md` · `vendor/README.md`
 - `website-docs.ts`（站点投影清单）
 - 上游英文 `README.md` 不进入本目录（与 KB 索引同名），线上快照在 `downloads/github/harness/README.md`
 - 同步脚本本次加固：pathspec 全部 `:(top)` 锚定（避免 basename 全局匹配误收仓库深处 symlink）；Windows 下无法解出的 symlink 按其 blob 目标文本落地；目的目录只保留范围内条目（曾因一次失败抽取残留污染，已由脚本自动修剪 107 项）。

package/references/website-pages.md

@@ -121,7 +121,7 @@
 | `/reference/cookbook/adding-a-tool` | 新增 Tool | `docs/cookbook/adding-a-tool.md` |
 | `/reference/cookbook/adding-an-llm-adapter` | 新增 LLM Adapter | `docs/cookbook/adding-an-llm-adapter.md` |
 | `/reference/cookbook/extension-cookbook` | 扩展模式 | `docs/cookbook/extension-cookbook.md` |
-| `/reference/cookbook/adding-a-conversation-node` | 新增 Conversation Node | `docs/cookbook/adding-a-conversation-node.md` |
+| ~~`/reference/cookbook/adding-a-conversation-node`~~ | （alpha.3 上游已移除该页） | 原 `docs/cookbook/adding-a-conversation-node.md` 已删除 |
 | `/reference/subsystems/` | 子系统 / Subsystems | `docs/subsystems/README.md` |
 
 **子系统页**（`/reference/subsystems/<name>`，共约 40 页，按侧栏分组）：
@@ -489,7 +489,7 @@
 #### `/reference/capability-seams` —— 能力服务（生成，`docs/capability-seams.md`）
 
 - 一份 **Mermaid 图 + 表格**，列出全部 `ctx.*` 服务：Role（`core` / `seam` / `bundle`）、Owner 包、实现包、直接消费者、companion 插件与说明。
-- 关键 seam 举例（表格行）：`ctx.llm`（seam；`llm-deepseek`/`llm-pi-ai`/`llm-replay` 实现）、`ctx.shell`（seam；`bash-local`/`bash-sandbox`/`pwsh-local`）、`ctx.fs`（seam；`fs-local`/`fs-sandbox`/`fs-e2b`）、`ctx.subprocess`、`ctx.sandbox`、`ctx.terminals`、`ctx.web`（`web-search-exa/perplexity/deepseek` + `web-fetch-http`）、`ctx.compaction`、`ctx.subagents`、`ctx.skills`、`ctx.sessionPersistence`（`jsonl`/`sqlite`）、`ctx.sessionQuery`、`ctx.storage`、`ctx.settings`、`ctx.credentials`、`ctx.workflowEngine`、`ctx.lsp`、`ctx.jobs` 等。core 服务如 `ctx.tools`、`ctx.sessions`、`ctx.systemPrompt`、`ctx.agents`、`ctx.agentLoop`（bundle）。
+- 关键 seam 举例（表格行）：`ctx.llm`（seam；`llm-deepseek`/`llm-pi-ai`/`llm-replay` 实现）、`ctx.shell`（seam；`bash-local`/`bash-sandbox`/`pwsh-local`）、`ctx.fs`（seam；`fs-local`/`fs-sandbox`/`fs-e2b`）、`ctx.subprocess`、`ctx.sandbox`、`ctx.terminals`、`ctx.web`（`web-search-exa/perplexity/deepseek` + `web-fetch-http`）、`ctx.compaction`、`ctx.subagents`、`ctx.skills`、`ctx.sessionPersistence`（`jsonl`）、`ctx.sessionQuery`、`ctx.storage`、`ctx.settings`、`ctx.credentials`、`ctx.workflowEngine`、`ctx.lsp`、`ctx.jobs` 等。core 服务如 `ctx.tools`、`ctx.sessions`、`ctx.systemPrompt`、`ctx.agents`、`ctx.agentLoop`（bundle）。
 - 完整消费者/实现关系图可作插件开发者的"服务地图"。
 
 #### `/reference/config-catalog` —— 插件配置目录（生成，`docs/config-catalog.md`，约 3151 行）
@@ -617,7 +617,7 @@
 - `/develop/cordis-tutorial/`、`/develop/cordis-tutorial/01-first-plugin`、`/develop/cordis-tutorial/02-lifecycle-and-effects`、`/develop/cordis-tutorial/03-services`、`/develop/cordis-tutorial/04-events`、`/develop/cordis-tutorial/05-config`、`/develop/cordis-tutorial/06-composition-and-hmr`、`/develop/cordis-tutorial/07-into-the-harness`
 - `/reference/`、`/reference/cordis-primer`、`/reference/capability-seams`、`/reference/agent-lifecycle`、`/reference/tool-execution-pipeline`、`/reference/config-catalog`、`/reference/tool-catalog`、`/reference/persistence-catalog`
 - `/reference/cordis-api/context`、`/reference/cordis-api/events`、`/reference/cordis-api/fiber`、`/reference/cordis-api/registry`、`/reference/cordis-api/service`、`/reference/cordis-api/inherited`
-- `/reference/cookbook/adding-a-package`、`/reference/cookbook/adding-a-tool`、`/reference/cookbook/adding-an-llm-adapter`、`/reference/cookbook/extension-cookbook`、`/reference/cookbook/adding-a-conversation-node`
+- `/reference/cookbook/adding-a-package`、`/reference/cookbook/adding-a-tool`、`/reference/cookbook/adding-an-llm-adapter`、`/reference/cookbook/extension-cookbook`
 - `/reference/subsystems/` + 子系统（core, scope, invariants, session, session-query, session-reference, session-title, session-projection, persistence, spill, session-telemetry, llm-streaming, token-meter, system-prompt, compaction, tools, shell, subprocess, terminal, jobs, filesystem, lsp, code-runtime, web, skills, workflow, subagent, approval, permission-presets, sandbox, plan, user-questions, commands, goal, schedule, web-server, typert, client-modules, storage, workspace, settings, credentials）
 
 ### 5.3 GitHub 仓库文档源文件（web_search 命中，均在 `github.com/deepseek-ai/deepseek-harness`）

package/scripts/check-docs-drift.ps1

@@ -0,0 +1,55 @@
+# 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
+#   recorded in references/official-docs/SNAPSHOT.md — the SHA-locked authority the
+#   mirror was synced from. It never edits the mirror; drift is only reported.
+# Usage:  pwsh -File scripts/check-docs-drift.ps1 [-Repo <url>] [-Branch <name>] [-Snapshot <path>] [-FailOnDrift]
+#   Exit codes: 0 = FRESH, 1 = DRIFT (with -FailOnDrift), 2 = probe could not run (snapshot/parse/fetch failure).
+#   In CI it also writes `drift=yes|no|error` to $env:GITHUB_OUTPUT when that variable is set.
+param(
+  [string]$Repo = 'https://github.com/deepseek-ai/deepseek-harness.git',
+  [string]$Branch = 'master',
+  [string]$Snapshot = 'references/official-docs/SNAPSHOT.md',
+  [switch]$FailOnDrift
+)
+$ErrorActionPreference = 'Stop'
+$kit = Split-Path $PSScriptRoot -Parent
+$snapshotPath = Join-Path $kit $Snapshot
+
+# ---- 1) Read the pinned source commit SHA from SNAPSHOT.md ----
+$pinned = $null
+if (-not (Test-Path $snapshotPath)) { Write-Error "snapshot not found: $snapshotPath"; exit 2 }
+foreach ($line in Get-Content $snapshotPath -Encoding UTF8) {
+  if ($line -match '^\|\s*Source commit\s*\|\s*`([0-9a-f]{40})`\s*\|') {
+    $pinned = $Matches[1]
+    break
+  }
+}
+if (-not $pinned) { Write-Error "cannot parse the pinned 'Source commit' SHA from $Snapshot"; exit 2 }
+
+# ---- 2) Fetch the upstream branch tip SHA (no clone required) ----
+$remoteLine = (& git ls-remote $Repo "refs/heads/$Branch" 2>$null | Select-Object -First 1)
+if (-not $remoteLine -or $remoteLine -notmatch '^([0-9a-f]{40})\s') {
+  $message = "cannot reach upstream $Repo (branch $Branch)"
+  Write-Output "ERROR: $message"
+  if ($env:GITHUB_OUTPUT) { Add-Content -Path $env:GITHUB_OUTPUT -Value 'drift=error' }
+  exit 2
+}
+$upstream = $Matches[1]
+
+# ---- 3) Compare and report ----
+$fresh = ($upstream -eq $pinned)
+Write-Output "pinned (SNAPSHOT.md): $pinned"
+Write-Output "upstream ($Branch): $upstream"
+if ($fresh) {
+  Write-Output 'FRESH: references/official-docs matches the upstream branch tip'
+} else {
+  Write-Output "DRIFT: references/official-docs is pinned to $pinned but upstream is at $upstream"
+  Write-Output 'Action: run  pwsh -File scripts/sync-official-docs.ps1  to refresh the mirror (do not hand-edit the mirror).'
+}
+if ($env:GITHUB_OUTPUT) {
+  Add-Content -Path $env:GITHUB_OUTPUT -Value ($(if ($fresh) { 'drift=no' } else { 'drift=yes' }))
+}
+if (-not $fresh -and $FailOnDrift) { exit 1 }
+exit 0

package/scripts/check-readme-sync.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Five-language README sync gate: the English file is the source of truth.
+// Every translation must carry the same `## ` section headings in the same
+// order and the same configuration-table keys, so a config change cannot
+// ship without its translations.
+import { readFileSync, existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+const LANGUAGES = [
+  ['README.md', 'en'],
+  ['README.zh.md', 'zh'],
+  ['README.es.md', 'es'],
+  ['README.pt.md', 'pt'],
+  ['README.hi.md', 'hi'],
+]
+
+const headingsOf = (text) => text.split(/\r?\n/u)
+  .map(line => /^##\s+(.+)$/u.exec(line)?.[1]?.trim())
+  .filter((heading) => heading !== undefined)
+
+// Configuration-table keys: the first cell of every row under the
+// "Configuration" section (until the next `## ` heading).
+const configKeysOf = (text) => {
+  const lines = text.split(/\r?\n/u)
+  const start = lines.findIndex(line => /^##\s+Configuration\s*$/u.test(line))
+  if (start === -1) return []
+  const end = lines.findIndex((line, index) => index > start && line.startsWith('## '))
+  const section = lines.slice(start, end === -1 ? undefined : end)
+  const keys = []
+  let headerSkipped = false
+  for (const line of section) {
+    if (!line.startsWith('|')) continue
+    if (!headerSkipped) { headerSkipped = true; continue }
+    const cells = line.split('|').map(cell => cell.trim())
+    if (cells.length < 2) continue
+    const key = cells[1]
+    if (key === '' || key === 'Key') continue
+    if (/^-+$/u.test(key)) continue
+    keys.push(key)
+  }
+  return keys
+}
+
+const failures = []
+const reference = LANGUAGES[0]
+if (reference === undefined) process.exit(1)
+const refPath = path.join(root, reference[0])
+if (!existsSync(refPath)) {
+  console.error(`${reference[0]} is missing`)
+  process.exit(1)
+}
+const refText = readFileSync(refPath, 'utf8')
+const refHeadings = headingsOf(refText)
+const refKeys = configKeysOf(refText)
+
+for (const [file, label] of LANGUAGES.slice(1)) {
+  const filePath = path.join(root, file)
+  if (!existsSync(filePath)) {
+    failures.push(`${file}: missing (${label})`)
+    continue
+  }
+  const text = readFileSync(filePath, 'utf8')
+  const headings = headingsOf(text)
+  for (let index = 0; index < refHeadings.length; index++) {
+    if (headings[index] !== refHeadings[index]) {
+      failures.push(`${file}: heading ${index + 1} is ${JSON.stringify(headings[index])}, expected ${JSON.stringify(refHeadings[index])}`)
+    }
+  }
+  if (headings.length !== refHeadings.length) {
+    failures.push(`${file}: ${headings.length} headings, expected ${refHeadings.length}`)
+  }
+  const keys = configKeysOf(text)
+  if (keys.length !== refKeys.length) {
+    failures.push(`${file}: ${keys.length} config keys, expected ${refKeys.length}`)
+    continue
+  }
+  for (let index = 0; index < refKeys.length; index++) {
+    if (keys[index] !== refKeys[index]) {
+      failures.push(`${file}: config key ${index + 1} is ${JSON.stringify(keys[index])}, expected ${JSON.stringify(refKeys[index])}`)
+    }
+  }
+}
+
+if (failures.length > 0) {
+  console.error('readme-sync failed:')
+  for (const failure of failures) console.error(`  - ${failure}`)
+  process.exit(1)
+}
+console.log(`readme-sync: all ${LANGUAGES.length} READMEs share section structure and config keys`)

package/scripts/download-sources.ps1

@@ -146,7 +146,7 @@ Get-ChildItem (Join-Path $docRoot 'subsystems') -Filter *.md | ForEach-Object {
 Get-ChildItem (Join-Path $docRoot 'cordis-api') -Filter *.md | ForEach-Object {
   [void]$routes.Add('reference/cordis-api/' + (SitePath $_.Name))
 }
-@('adding-a-package','adding-a-tool','adding-an-llm-adapter','extension-cookbook','adding-a-conversation-node') | ForEach-Object {
+@('adding-a-package','adding-a-tool','adding-an-llm-adapter','extension-cookbook') | ForEach-Object {
   [void]$routes.Add("reference/cookbook/$_")
 }
 

package/scripts/sync-official-docs.ps1

@@ -25,10 +25,10 @@ $pruned = 0
 $mdCount = 0
 $zhCount = 0
 
-# Sync scope: docs/, root AGENTS.md/BENCHMARK.md/CLAUDE.md/CONTRIBUTING.*/README.zh.md/README.i18n.yaml/THIRD_PARTY_NOTICES.md/LICENSE, packages/AGENTS.md, examples/AGENTS.md, packages/README.md, vendor/README.md, website/docs.ts
-# 上游 root README.md 不在此列：official-docs/README.md 是 KB 自有索引（上游英文 README 快照在 downloads/github/harness/README.md）。
-# pathspec 全部用 :(top) 锚定，避免 git 的 basename 全局匹配把仓库深处的同名 symlink（如各处 CLAUDE.md）误收进归档。
-$paths = @(':(top)docs', ':(top)AGENTS.md', ':(top)BENCHMARK.md', ':(top)CONTRIBUTING.md', ':(top)CONTRIBUTING.zh.md', ':(top)CONTRIBUTING.i18n.yaml', ':(top)README.zh.md', ':(top)README.i18n.yaml', ':(top)THIRD_PARTY_NOTICES.md', ':(top)LICENSE', ':(top)packages/AGENTS.md', ':(top)examples/AGENTS.md', ':(top)packages/README.md', ':(top)vendor/README.md', ':(top)website/docs.ts')
+# Sync scope: docs/, root AGENTS.md/BENCHMARK.md/CLAUDE.md/CONTRIBUTING.*/README.zh.md/README.i18n.yaml/THIRD_PARTY_NOTICES.md/LICENSE, packages/AGENTS.md, packages/README.md, vendor/README.md, website/docs.ts
+# Upstream root README.md is out of scope: official-docs/README.md is the KB-owned index (the upstream English README snapshot lives in downloads/github/harness/README.md).
+# Every pathspec uses the :(top) anchor so git's basename-wide matching cannot sweep in same-named symlinks (e.g. the various CLAUDE.md files).
+$paths = @(':(top)docs', ':(top)AGENTS.md', ':(top)BENCHMARK.md', ':(top)CONTRIBUTING.md', ':(top)CONTRIBUTING.zh.md', ':(top)CONTRIBUTING.i18n.yaml', ':(top)README.zh.md', ':(top)README.i18n.yaml', ':(top)THIRD_PARTY_NOTICES.md', ':(top)LICENSE', ':(top)packages/AGENTS.md', ':(top)packages/README.md', ':(top)vendor/README.md', ':(top)website/docs.ts')
 
 if ($gitOk) {
   # Prefer origin/master, fall back to HEAD - never the working tree (may contain untracked/unpushed content).
@@ -41,13 +41,20 @@ if ($gitOk) {
   if ($LASTEXITCODE -ne 0) { Write-Error "git archive failed (ref=$ref)"; exit 1 }
 
   New-Item -ItemType Directory -Force -Path $dest | Out-Null
+  # Verbatim copy: clear the destination before extracting (keep only the KB-owned index README.md,
+  # which is unrelated to upstream), so structural residue from older snapshots (e.g. a top-level
+  # .agents/ directory from a previous tree) cannot interfere with the extraction.
+  Get-ChildItem -Force $dest | Where-Object { $_.Name -ne 'README.md' } | ForEach-Object {
+    Remove-Item $_.FullName -Recurse -Force; $pruned++
+  }
   & tar -xf $tmp -C $dest
   if ($LASTEXITCODE -ne 0) { Write-Error 'tar extraction failed'; exit 1 }
   Remove-Item $tmp -Force
 
-  # CLAUDE.md 在上游是 symlink（指向 AGENTS.md，mode 120000）；Windows tar 无法解出 symlink，
-  # 且 pathspec 'CLAUDE.md' 会 basename 匹配到仓库深处同名 symlink，故不在 $paths 中——解包后按其
-  # symlink 目标文本落地同名普通文件（内容即上游 blob 原文）。
+  # CLAUDE.md is a symlink upstream (target AGENTS.md, mode 120000); Windows tar cannot extract
+  # symlinks, and the 'CLAUDE.md' pathspec would basename-match same-named symlinks deeper in the
+  # repo, so it stays out of $paths - after extraction its target text lands as a plain file
+  # (content = the upstream blob text).
   $claudeTarget = (& git -C $Checkout cat-file -p "${ref}:CLAUDE.md" 2>$null | Select-Object -First 1)
   if (-not $claudeTarget) { $claudeTarget = 'AGENTS.md' }
   Set-Content -Path (Join-Path $dest 'CLAUDE.md') -Value $claudeTarget -Encoding UTF8
@@ -59,7 +66,8 @@ if ($gitOk) {
     Remove-Item (Join-Path $dest 'website') -Force -Recurse -ErrorAction SilentlyContinue
   }
 
-  # 目的目录只保留范围内条目（清掉历史抽取残留/上游删除的根文件，保证逐字副本无污染）。
+  # Keep only in-scope entries at the destination root (drops stale extraction residue and
+  # upstream-deleted root files so the copy stays verbatim).
   $rootKeep = @('docs','examples','packages','vendor','AGENTS.md','BENCHMARK.md','CLAUDE.md','CONTRIBUTING.md','CONTRIBUTING.zh.md','CONTRIBUTING.i18n.yaml','LICENSE','README.zh.md','README.i18n.yaml','THIRD_PARTY_NOTICES.md','SNAPSHOT.md','README.md','website-docs.ts')
   Get-ChildItem -Force $dest | Where-Object { $rootKeep -notcontains $_.Name } | ForEach-Object {
     Remove-Item $_.FullName -Recurse -Force; $pruned++
@@ -94,7 +102,7 @@ if ($gitOk) {
 } else {
   Write-Output 'WARN: checkout is not a git repo (or -SkipGit) - copying the filesystem as-is; untracked files are not filtered and no pruning runs.'
   foreach ($p in $paths) {
-    $rel = $p -replace '^:\(top\)',''   # 去掉 pathspec 锚定前缀得到仓库内相对路径
+    $rel = $p -replace '^:\(top\)',''   # strip the pathspec anchor to get the in-repo relative path
     $srcFull = Join-Path $Checkout ($rel -replace '/','\')
     if (-not (Test-Path $srcFull)) { Write-Output "SKIP(source missing): $rel"; continue }
     $target = Join-Path $dest ($rel -replace '/','\')
@@ -119,9 +127,9 @@ $L = @(
   "| Source ref | ``$ref`` |",
   "| Source commit | ``$sha`` |",
   "| Synced at (UTC) | $utc |",
-  '| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md`(symlink 目标文本), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml`（上游英文 `README.md` 不在本目录，快照见 `downloads/github/harness/README.md`）, `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `examples/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |',
+  '| Scope | tracked files at the ref: `docs/`, root `AGENTS.md`, `BENCHMARK.md`, `CLAUDE.md` (symlink target text), `CONTRIBUTING.md`/`.zh.md`/`.i18n.yaml`, `README.zh.md`/`.i18n.yaml` (the upstream English `README.md` is not in this dir; its snapshot lives in `downloads/github/harness/README.md`), `THIRD_PARTY_NOTICES.md`, `LICENSE`, `packages/AGENTS.md`, `packages/README.md`, `vendor/README.md`, `website/docs.ts` |',
   "| File counts | docs/: $mdCount md files ($zhCount .zh.md pairs) |",
-  "| Pruned this run | $pruned 个不在范围内/上游已删除的条目 |",
+  "| Pruned this run | $pruned out-of-scope/upstream-deleted entries |",
   '',
   'Drift check: `pwsh -File scripts/verify-kit.ps1 -Checkout <checkout>` (tracked files only).'
 )