dsh-plugin-dev-kb 1.0.0

package/kb/site/reference/cordis-api/registry.md

@@ -0,0 +1,156 @@
+---
+editSource: "docs/cordis-api/registry.zh.md"
+---
+
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/registry.md` 重新记录配对。 -->
+
+# 注册表
+
+插件加载与依赖注入。
+
+### ctx.inject(deps, callback)
+
+```ts cordis-catalog
+/**
+ * Run a callback once the requested services are available.
+ *
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+ * is unloaded and re-run whenever a required service changes.
+ *
+ * @param deps — required services, as an array or a name → config map.
+ * @param callback — plugin body called with `(ctx, config)`.
+ * @returns the fiber; awaiting it settles once loading finished.
+ */
+inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
+```
+
+请求的服务可用后，运行回调。
+
+这是 `ctx.plugin({ inject, apply: callback })` 的简写形式：每当某个必需服务发生变化时，系统都会卸载并重新运行该回调。
+
+- `deps`：必需服务，形式可以是数组，也可以是从名称到配置的映射。
+- `callback`：以 `(ctx, config)` 调用的插件主体。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/registry.ts#L176)
+
+### ctx.plugin(plugin, ...args)
+
+```ts cordis-catalog
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
+plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
+```
+
+在当前上下文中加载插件。
+
+- `plugin`：函数、类或 `{ apply }` 对象形式的插件。
+- `args`：插件配置，会根据其 `Config` schema 进行校验。
+
+**返回** fiber；对其执行 await 会在加载完成后结束等待（如果发生配置错误或启动错误，则会被拒绝）。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/registry.ts#L185)
+
+## Plugin
+
+支持的插件入口点形式。
+
+```ts cordis-catalog
+/** Supported plugin entrypoint shapes. */
+type Plugin<T = any> =
+  | Plugin.Function<T>
+  | Plugin.Constructor<T>
+  | Plugin.Object<T>
+
+/** Types associated with plugin entrypoints and runtime records. */
+namespace Plugin {
+  /** Shared metadata understood by the plugin registry and related tooling. */
+  export interface Base<T = any> {
+    /** Display name used for fiber diagnostics and logger names. */
+    name?: string
+    /** Standard-schema validator applied to config before the plugin starts. */
+    Config?: StandardSchemaV1<any, T>
+    /** Services the plugin requires; it only loads while all are available. */
+    inject?: Inject
+    /** Service name(s) the plugin provides (read by `Service` and by loaders). */
+    provide?: string | string[]
+    /** Service names whose intercept config the plugin declares it consumes. */
+    intercept?: Dict<boolean>
+  }
+
+  export interface Transform<S, T> {
+    /** Marks the transform object as a schema/config transform. */
+    schema?: true
+    /** Convert user-facing config to runtime config. */
+    Config: (config: S) => T
+  }
+
+  /** Function plugin called with `(ctx, config)`. */
+  export interface Function<T = any> extends Base<T> {
+    (ctx: Context, config: T): any
+  }
+
+  /** Class plugin constructed with `(ctx, config)`. */
+  export interface Constructor<T = any> extends Base<T> {
+    new (ctx: Context, config: T): any
+  }
+
+  /** Object plugin with an `apply(ctx, config)` method. */
+  export interface Object<T = any> extends Base<T> {
+    apply(ctx: Context, config: T): any
+  }
+
+  /** Mutable registry record shared by all fibers of one plugin callback. */
+  export interface Runtime {
+    /** Display name copied from the first registered plugin shape. */
+    name?: string
+    /** Every live fiber of this plugin (one per `ctx.plugin()` call). */
+    fibers: DisposableList<Fiber>
+    /** The executable entrypoint all fibers share (registry identity key). */
+    callback: globalThis.Function
+    /** Standard-schema validator applied to each fiber's config. */
+    Config?: StandardSchemaV1
+  }
+}
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/registry.ts#L92)
+
+## Inject
+
+插件和 `@Inject` 装饰器接受的服务依赖声明。
+
+数组形式请求不带拦截配置的服务。对象形式将每个服务名称映射到插件上下文中可选的拦截配置。
+
+```ts cordis-catalog
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
+type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
+
+/** Utilities for normalizing plugin dependency declarations. */
+namespace Inject {
+  /**
+   * Convert array/object/class-inherited inject metadata into a plain map.
+   *
+   * @param inject — the declaration to normalize; `null`/`undefined` add nothing.
+   * @param result — the map to fill (service name → intercept config or `null`).
+   * @returns `result`.
+   */
+  export function resolve(inject: Inject | null | undefined, result: Dict = Object.create(null))
+}
+```
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/registry.ts#L19)

package/kb/site/reference/cordis-api/service.md

@@ -0,0 +1,106 @@
+---
+editSource: "docs/cordis-api/service.zh.md"
+---
+
+<!-- 英文源文件由 scripts/gen-cordis-catalog.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-cordis-catalog` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/cordis-api/service.md` 重新记录配对。 -->
+
+# Service
+
+上下文服务的基类。以插件形式加载的子类会将自身注册为 `ctx.<name>`。
+
+用于在 `ctx` 上公开具名 API 的服务基类。
+
+子类在构造函数中调用 `super(ctx, name)`。服务会立即注册，并随所属 fiber 自动移除。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L11)
+
+### service.name
+
+```ts cordis-catalog
+/** The service name this instance is registered under. */
+public name!: string
+```
+
+此实例注册时使用的服务名称。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L30)
+
+## 静态成员
+
+### Service.init
+
+```ts cordis-catalog
+/** Symbol key of an instance method run after construction (class plugins). */
+static readonly init: unique symbol
+```
+
+构造完成后运行的实例方法所使用的符号键（类插件）。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L13)
+
+### Service.check
+
+```ts cordis-catalog
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
+static readonly check: unique symbol
+```
+
+传给 `ctx.provide()` 的可用性谓词所使用的符号键。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L15)
+
+### Service.config
+
+```ts cordis-catalog
+/** Symbol key of the phantom intercept-config type parameter. */
+static readonly config: unique symbol
+```
+
+虚设拦截配置类型参数所使用的符号键。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L17)
+
+### Service.invoke
+
+```ts cordis-catalog
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
+static readonly invoke: unique symbol
+```
+
+使服务可被调用的调用体所使用的符号键（例如 `ctx.logger()`）。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L19)
+
+### Service.extend
+
+```ts cordis-catalog
+/** Symbol key of the helper deriving an extended service instance. */
+static readonly extend: unique symbol
+```
+
+用于派生扩展服务实例的辅助方法所使用的符号键。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L21)
+
+### Service.tracker
+
+```ts cordis-catalog
+/** Symbol key of the tracker metadata used for context tracing. */
+static readonly tracker: unique symbol
+```
+
+上下文追踪所用跟踪器元数据的符号键。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L23)
+
+### Service.resolveConfig
+
+```ts cordis-catalog
+/** Symbol key of the intercept-config resolution helper below. */
+static readonly resolveConfig: unique symbol
+```
+
+下述拦截配置解析辅助方法所使用的符号键。
+
+[源码](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/cordis/src/service.ts#L25)

package/kb/site/reference/cordis-primer.md

@@ -0,0 +1,52 @@
+---
+editSource: "docs/cordis-primer.zh.md"
+---
+
+# Cordis 入门
+
+Cordis 是 DeepSeek Harness 底层以 vendor 方式引入的插件框架。本文介绍 harness 插件作者在阅读[子系统页面](./subsystems/core.md)上生成的服务/事件参考之前需要了解的 Cordis 核心概念；[Cordis 教程](../develop/cordis-tutorial/index.md)则通过实践逐一讲解这些概念。vendor 源码与同步流程见 [vendor/README.md](https://github.com/deepseek-ai/deepseek-harness/blob/master/vendor/README.md)。
+
+## 五个核心概念
+
+- **插件是实现 Service 的对象。** 它可以是一个带有可选 `inject` 和 `apply(ctx)` 字段的函数，也可以是一个 `Service` 子类，其生命周期由 Cordis 挂载到当前上下文中。
+- **上下文是服务的容器。** 一个服务占据一个稳定的 `ctx.<key>`（如 `ctx.tools`、`ctx.llm`、`ctx.sessions`）；其他插件通过 key 查找服务，而非导入具体实现。
+- **通过 `inject` 声明服务依赖。** 插件声明所需的服务后，会等待这些服务就绪才启动；加载顺序通过服务依赖表达，而非手动编排启动序列。
+- **类型化事件用于通信。** 服务通过 TypeScript 声明合并注册事件名，然后以 `emit`、`waterfall`（瀑布式事件）、`parallel` 或 `serial` 方式分发，分别对应监听者观察、包装、并行扇出或按序执行。
+- **注册是可逆的副作用。** 提示词片段、工具 schema、适配器、提供方和监听器通过 `ctx.effect()` 或 `ctx.on()` 安装，reload 和 teardown 时会按预期撤销。
+
+<a id="dispatch-modes"></a>
+
+## 分发模式
+
+每个事件具有以下分发模式之一，且只能通过对应方法分发。
+
+| 模式 | 是否 await？ | 分发顺序 | 是否有返回值？ |
+|---|---|---|---|
+| `emit` | 否 | 监听器按注册顺序观察 | 否 |
+| `waterfall` | 否 | 监听器按注册顺序观察 | 是 |
+| `parallel` | 是 | 所有监听器并行观察事件 | 否 |
+| `serial` | 是 | 监听器按注册顺序观察 | 是 |
+
+分发模式是事件公开约定的一部分。新的 harness 事件通过 `@mode` 标签记录模式，以便生成的目录可以将声明与分发调用点做交叉校验。
+
+<a id="cordis-waterfall-semantics"></a>
+
+## Cordis Waterfall 语义
+
+`ctx.waterfall` 是环绕中间件。监听器接收 `(...args, next)`。调用 `next()` 会执行下游监听器；下游返回值通过 `next()` 返回当前包装层，可由该层包装后继续向外返回。不调用 `next()` 直接返回则短路。
+
+协作式监听器通常修改一个共享的请求或决策对象，然后委托。监听器也可以选择完全替换结果，下游监听器将只看到替换后的结果。仅当监听器必须在普通注册之前运行时才使用 `prepend: true`。
+
+对于单决策事件，短路是设计意图。策略监听器在拥有决策权时可以不调用 `next()` 直接返回，而仅做标注或观察的监听器则必须委托。
+
+<a id="loader-configuration"></a>
+
+## Loader 配置
+
+`@deepseek-ai/cordis-plugin-include` 将 `!!js` 解析为表达式节点。Loader 在声明的注入激活后，基于该插件上下文（`ctx.serviceName`）插值条目的 `config`，并在每次挂载决策时基于 loader 上下文插值其 `disabled` 字段；Include 会保留嵌套行表达式，直到目标行激活。其余条目元数据保持字面值。由环境选择插件时，请使用 overlay。
+
+## 实践规则
+
+将行为封装为插件：工具流水线事件属于 `ctx.tools`，模型流式输出属于 `ctx.llm`，实时 agent（智能体）协调属于 `ctx.agents`。拦截和策略优先使用事件；直接能力调用优先使用服务方法。
+
+每个注册都应有对应的 disposer（资源释放函数）：要么从 `ctx.effect()` 返回一个，要么使用 Cordis 提供的辅助方法自动处理。如果 teardown 顺序有要求，请将相关工作放在同一个 effect 中，以确保资源按预期顺序释放。

package/kb/site/reference/index.md

@@ -0,0 +1,135 @@
+---
+editSource: "docs/architecture.zh.md"
+---
+
+# DeepSeek Harness 架构
+
+改动 `packages/` 下的任何内容之前，请先阅读本文。本文假定你已了解 Cordis；如果尚未了解，请先阅读[入门](./cordis-primer.md)或[教程](../develop/cordis-tutorial/index.md)。
+
+建议使用 agent（智能体）探索代码库并理解其架构。
+
+## Cordis
+
+[Cordis](./cordis-primer.md) 是 dsh 底层的框架：插件向共享上下文贡献服务、类型化事件和可逆的副作用。产品的每一部分都是插件，包括模型适配器、工具注册表、会话日志，以及 agent loop（智能体循环）本身，因此每一部分都可以从配置替换。
+
+不存在需要打补丁的特权内核：扩展 dsh 的方式是把插件挂载到其他插件旁边，而各项注册都是副作用，会在其插件卸载时撤销。
+
+## Profile 与组合包
+
+运行中的 `dsh` 是一棵插件树，由启动时按序叠加的各层组合而成。
+
+**profile** 是存放在 Harness home 中的具名组装。它列出自己叠放的组合包，存放自己安装的树外插件，并保存用户自己的 `cordis.patch.yml`。`web` 和 `headless` 作为模板随发行版交付。
+
+**组合包**是 Cordis 配置项及其挂载代码的分发格式，因此它插入的内容始终可被其上各层 patch。
+
+两者都在各自的 `package.json` 中通过 `dsh` 字段声明自己：`dsh.profile` 列出一个 profile 的组合包，`dsh.bundle` 指向一个组合包的 patch 文件。
+
+[`dsh-base`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/base/README.md) 是每个 profile 的第一层：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测。[`dsh-web-app`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/web-app/README.md) 增加浏览器应用；[`dsh-headless`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/bundle/headless/README.md) 增加一次性运行器，且完全不带服务器。
+
+各层按此顺序应用在空条目列表之上：先按 profile 列出的顺序应用每个组合包，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的那份，最后是任意 `--patch` overlay。一条 patch 按 id 定位某个条目并替换其整个 config，或插入新条目。
+
+要查看你的机器实际启动的配置树：
+
+```sh
+dsh --profile web --dump-config
+```
+
+它打印出的任何条目，都可以由你自己的 patch 替换。
+
+组装机制见 [app-boot](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/app-boot/README.md#profiles)；配置字段见生成的[配置目录](./config-catalog.md)。
+
+## 核心包
+
+以下是向 Cordis 树贡献内容的部分核心包。
+
+| 包 | 职责 | `ctx` 键 |
+|---|---|---|
+| [`core/session`](./subsystems/session.md) | 仅追加的 `SessionEvent` 日志和内存存储 | `ctx.sessions` |
+| [`core/system-prompt`](./subsystems/system-prompt.md) | 提示词片段与工具 schema 的组装 | `ctx.systemPrompt` |
+| [`core/tools`](./subsystems/tools.md) | 作用域化的工具注册表和带把关的执行流水线 | `ctx.tools` |
+| [`core/agent`](./subsystems/core.md) | `Agent` 接口、活跃 agent 注册表和 `agent/*` 事件 | `ctx.agents` |
+| [`core/agent-loop`](./subsystems/core.md) | 实现该接口的默认驱动器 | `ctx.agentLoop` |
+| [`core/scope`](./subsystems/scope.md) | 按 agent 划分作用域的注册原语 | 库，无 ctx 键 |
+| [`llm/llm`](./subsystems/llm-streaming.md) | 消息与流式词汇表，以及适配器 seam | `ctx.llm` |
+
+<a id="events"></a>
+
+## 事件
+
+事件就是扩展点，而选对事件域是大多数改动的第一个决定。
+
+- **会话事件**是追加到日志并通过 `session/event` 广播的持久事实。当某个事实必须在重新加载后仍然存在时，使用它。
+- **Agent 事件**（`agent/*`）携带活跃 `Agent`：inbox、步骤、状态、请求、验证、续跑。要观察或拦截进行中的工作时，使用它。
+- **能力事件**无需导入循环即可向某个 seam（`fs/*`、`tools/*`、`telemetry/*`）附加策略和适配器。
+
+[事件映射](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/event-producer-consumer.md)列出每个事件的生产方与消费方。
+
+<a id="turn-flow"></a>
+
+## 轮次流程
+
+一个**步骤**是一次模型请求加上它调用的工具。一个**轮次**包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。
+
+```text
+turn/start
+  claim next-step input plus one queued message
+  assemble prompt sections + tool schemas
+  -> agent/pre-step                   reject | enter(messages)
+     reject, or a first enter rewritten empty -> close the turn with no step
+     step/start
+     append entered messages as user/message
+     derive model history from the log
+     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
+     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
+     step/end
+     tools owe another request, or next-step input arrived -> claim -> next step
+  -> agent/turn-stopping
+turn/end
+```
+
+`turn/*`、`step/*`、`user/message`、`assistant/*` 和 `tool/*` 是持久会话事件；其余是分属三个事件域的实时扩展点。`agent/pre-step`、`agent/request`、`llm/stream` 和三个 `tools/*` 事件是 waterfall（瀑布式事件），其监听器必须调用 `next()` 才能委托下去；`agent/turn-stopping` 是 serial 事件，没有 `next()`。
+
+输入通过同一个 inbox 到达驱动器。有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。
+
+`agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试。每个步骤读取插件注册的提示词片段和工具 schema。
+
+详情见[时序图](./agent-lifecycle.md)、[工具流水线](./tool-execution-pipeline.md)和[取消与错误恢复](./subsystems/core.md#the-agent-handle)。
+
+## 会话日志
+
+会话日志是模型所见上下文的来源。`deriveMessages()` 从中投影出模型历史，原始 `assistant/chunk` 事件则保证回放和 UI 保真。fork、恢复、transcript（文本记录）、遥测和持久化都派生自该事件流。
+
+**模型可见即已记录。** 抵达模型请求的一切都必须能从日志重建，并由一项运行时不变量断言这一点。因此，新增一项模型可见输入就需要新增一个会话事件：扩展 `SessionEventMap` 并从日志渲染。
+
+## 能力 seam
+
+一个 **seam** 是一项可替换能力，包含三种角色：声明接口的 **Service Definition**、实现它的 **Service Provider**，以及使用它的 **Consumer**（通常是面向模型的工具）。一个包可以合并承担多个角色，但单一角色本身不是 seam；添加一项能力意味着把三者一并设计（[能力图](./capability-seams.md)）。
+
+seam 正是替换一个提供方就能改变整个产品的原因。文件系统与进程提供方共享同一个执行世界，因此把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需提供方专用 fork。[subagent 提供方](./subsystems/subagent.md)在同一个接口之后同样千差万别，从新建一个子 agent，到把一个轮次委派给另一个产品。
+
+## 新行为的归属位置
+
+新行为附加到已有文档记录的扩展点。改动循环本身时，本映射随之更新。
+
+| 目标 | 机制 |
+|---|---|
+| 添加模型提供方 | 在 `ctx.llm` 上注册其适配器 |
+| 添加面向模型的能力 | 在 `ctx.tools` 上注册；其 schema 加入提示词组装 |
+| 让某个会话拥有不同的能力集合 | 组装一个 agent preset；其中的服务行需要 `isolate` realm |
+| 添加 shell 执行 | 注册 `ctx.shell` 后端；本地后端通过 `ctx.subprocess` spawn 进程 |
+| 添加持久化终端执行 | 注册 `ctx.terminals` 后端和 `dsh-tool-terminal` |
+| 添加用户命令 | 在 `ctx.commands` 上注册；它无需模型轮次即可分派 |
+| 添加后台工作 | 在 `ctx.jobs` 上注册；`job_*` 工具负责收集或停止 |
+| 添加文件系统访问或策略 | 注册 `ctx.fs` 提供方，或监听 `fs/*` 事件 |
+| 限制所启动的进程 | 使用 `ctx.sandbox` 后端；消费方在启动进程前包装 argv |
+| 拦截请求、工具或轮次 | 使用相应的 `agent/*` 或 `tools/*` 事件；`agent/turn-stopping` 会停止轮次 |
+| 添加模型可见上下文 | 调用 `agent.inject()`；它会落到下一次获准的请求中 |
+| 添加 UI 或编辑器集成 | 驱动 `ctx.agents` 并从 `session/event` 渲染 |
+| 添加 Web Client Chat 节点 | 注册 `ConversationNodeDefinition` + keyed renderer |
+| 添加持久会话状态 | 扩展 `SessionEventMap`；从日志渲染和回放 |
+| 生成会话标题 | 注册唯一的 `ctx.sessionTitle` 提供方 |
+| 管理同会话目标 | 使用 `ctx.goals`；通过 `agent/*` 续跑 |
+| fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` |
+| 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` |
+
+[扩展实操手册](./cookbook/extension-cookbook.md)将功能映射到能力，并索引[包](./cookbook/adding-a-package.md)、[工具](./cookbook/adding-a-tool.md)、[LLM（大语言模型）适配器](./cookbook/adding-an-llm-adapter.md)、[Chat 节点](./cookbook/adding-a-conversation-node.md)和[设置卡片](./cookbook/adding-a-settings-card.md)的分步指南。