dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/cordis-tutorial/06-composition-and-hmr.zh.md

@@ -1,113 +0,0 @@
-# 6. 组合与 HMR（热模块替换）
-
-[English](06-composition-and-hmr.md) | 中文
-
-到目前为止构建的每项能力都是插件，`cordis.yml` 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。
-
-## Cordis 配置项不只有名称
-
-Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
-
-```yaml
-- id: greeter          # stable identity for this entry
-  name: './greeter.ts'
-- id: consumer
-  name: './consumer.ts'
-  disabled: true       # keep the entry, skip mounting it
-```
-
-`id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
-
-组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `shell` 提供方，互不影响。[Cordis 入门](../cordis-primer.zh.md)和[服务隔离示例](../user/develop/framework/service.zh.md#service-isolation)介绍了详细内容。
-
-## 热模块替换
-
-卸载会释放 effect（[第 2 章](02-lifecycle-and-effects.zh.md)），加载则遵循依赖关系（[第 3 章](03-services.zh.md)），因此 HMR 可以先卸载、再加载，以替换正在运行的插件。`@deepseek-ai/dsh-hmr` 插件会监视文件，并在保存时执行这一过程。
-
-在 `tmp/cordis-tutorial` 中编写 `cordis.yml`：
-
-```yaml
-- id: logger
-  name: '@deepseek-ai/cordis-plugin-logger-console'
-- id: timer
-  name: '@deepseek-ai/cordis-plugin-timer'
-- id: hmr
-  name: '@deepseek-ai/dsh-hmr'
-  config:
-    root: ['.']
-- id: hello
-  name: './hello.ts'
-```
-
-列表中增加了两个辅助插件：HMR 通过 Cordis logger 服务记录日志，因此没有控制台导出器时看不到其消息；它还会 `inject` `timer` 服务来实现去抖，如果没有 `@deepseek-ai/cordis-plugin-timer`，它就会永远停在 PENDING，而且不发出任何提示。下一节就讨论这种静默状态。
-
-HMR 通过 Loader 的原生辅助工具读取 Node 的 loader 内部结构。请在 tsx 下运行 Cordis：
-
-```sh
-node --import tsx ../../vendor/cordis/bin.js
-```
-
-现在编辑 `hello.ts`，修改日志消息并保存：
-
-```
-hello from my first plugin
-2026-07-22 15:44:36 [I] hmr watching [ '.' ]
-2026-07-22 15:44:39 [I] hmr reload plugin at hello.ts
-hello from my EDITED plugin
-```
-
-旧实例先卸载（其所有 effect 都会回卷），新代码随后加载，`apply` 再次运行。按 Ctrl-C 停止进程。编辑 `cordis.yml` 本身也会触发更新：loader 按 `id` 比较 Cordis 配置项，只挂载、卸载或重新配置发生变化的部分。这就是上述 Cordis 配置项显式携带 `id` 的原因：不带该字段的 Cordis 配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使自身文本未变，它也会被视为先删除再添加并重新挂载。
-
-## 诊断始终无法加载的插件
-
-依赖驱动加载也有另一面：如果插件的 `inject` 指定了无人提供的服务，它就会一直等待，不输出任何内容。这不是错误，因为 PENDING 是合法状态，提供方可能稍后才挂载。
-
-你可以直接查看这些状态。每个上下文都能枚举插件注册表；创建 `diagnose.ts`：
-
-```ts
-import { FiberState, type Context } from '@deepseek-ai/cordis'
-
-export const name = 'diagnose'
-
-export function apply(ctx: Context) {
-  setTimeout(() => {
-    for (const runtime of ctx.registry.values()) {
-      for (const fiber of runtime.fibers) {
-        if (fiber.state === FiberState.PENDING) {
-          console.log(`${fiber.name} is PENDING — a required service is missing`)
-        }
-      }
-    }
-  }, 500)
-}
-```
-
-再创建一个依赖无法满足的插件 `needs-timer.ts`：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-
-export const name = 'needs-timer'
-export const inject = ['timer']
-
-export function apply(ctx: Context) {
-  console.log('needs-timer loaded')
-}
-```
-
-```yaml
-- name: './needs-timer.ts'
-- name: './diagnose.ts'
-```
-
-运行它（直接执行 `node --import tsx ../../vendor/cordis/bin.js`，按 Ctrl-C 停止）：
-
-```
-needs-timer is PENDING — a required service is missing
-```
-
-`inject: ['timer']` 没有提供方。向列表添加 `- name: '@deepseek-ai/cordis-plugin-timer'` 后，插件就会加载。如果插件既不执行任何操作，也不报告任何内容，请检查其 fiber 状态。不加 PENDING 过滤条件进行迭代时，还会看到 loader 自身的插件（Loader、Include）处于 ACTIVE，因为配置文件本身也是通过插件挂载的。
-
-下一章：[进入 harness](07-into-the-harness.zh.md)：把相同模式用于真实的 harness 服务。
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for 07-into-the-harness.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/cordis-tutorial/07-into-the-harness.md
-/7-into-the-harness:
-  en: 470ff1f9eadc2663
-  zh: d92a95cc0058ed3b
-/7-into-the-harness/a-tool-plugin:
-  en: 00ae7d882a28622d
-  zh: 6386dcfac5df1a70
-/7-into-the-harness/an-observer-plugin:
-  en: 144e0445e183588a
-  zh: f02cfb7e91fdbd24
-/7-into-the-harness/compose-and-run:
-  en: 64a9d7a1430b3d0e
-  zh: 034e95c7f08bd70c
-/7-into-the-harness/from-here-to-a-full-agent:
-  en: a758f5739e30667b
-  zh: 3f9e0e2cc38af87b

package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.md

@@ -1,108 +0,0 @@
-# 7. Into the harness
-
-English | [中文](07-into-the-harness.zh.md)
-
-This chapter registers a model-callable tool with the harness's `tools` service, executes it through the harness tool pipeline, and observes the result event. It remains keyless and does not call a model.
-
-## A tool plugin
-
-Create `greet-tool.ts` in `tmp/cordis-tutorial`:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import { brandString } from '@deepseek-ai/dsh-brand'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolCallId } from '@deepseek-ai/dsh-llm'
-
-export const name = 'greet-tool'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'greet',
-    description: 'Greet the named person.',
-    parameters: {
-      name: { type: 'string', required: true, description: 'Who to greet' },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      return `Hello, ${args.name}!`
-    },
-  }))
-
-  // Drive one call through the real execution pipeline, standing in for
-  // the model. ToolCallId brands the correlation id a provider would issue.
-  void (async () => {
-    const result = await ctx.tools.execute({
-      callId: brandString<ToolCallId>('demo-1'),
-      name: 'greet',
-      arguments: { name: 'Cordis' },
-      signal: new AbortController().signal,
-    })
-    console.log('tool replied:', JSON.stringify(result.content))
-  })()
-}
-```
-
-Every pattern here is from the earlier chapters: `inject: ['tools']` ([chapter 3](03-services.md)) holds the plugin until the tool registry exists; `ctx.tools.register(...)` attaches the registration disposer to the plugin ([chapter 2](02-lifecycle-and-effects.md)), so unloading unregisters the tool. `defineTool` converts the `parameters` spec to the JSON Schema shown to the model, infers the type of `args`, and validates model-supplied arguments before `execute` runs. The tool returns the canonical value declared by `output.schema`; `output.render` separately produces the Native and durable result content.
-
-## An observer plugin
-
-Create `tool-logger.ts` — a separate plugin that watches every tool call in the app through the harness's `tools/result` event:
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-logger'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.on('tools/result', (exec, result) => {
-    const text = result.content
-      .map(block => (block.type === 'text' ? block.text : ''))
-      .join('')
-    console.log(`[tool-logger] ${exec.name} -> ${text}`)
-  })
-}
-```
-
-The `import type {} from '@deepseek-ai/dsh-tools'` line pulls in the package's declaration merges so `'tools/result'` and its payload are typed — the same move as chapter 4's `stats.ts` import, at package scale.
-
-## Compose and run
-
-```yaml
-- name: '@deepseek-ai/dsh-system-prompt'
-- name: '@deepseek-ai/dsh-tools'
-- name: './tool-logger.ts'
-- name: './greet-tool.ts'
-```
-
-`@deepseek-ai/dsh-tools` injects the `systemPrompt` service because tools contribute schemas to the system prompt, so the composition lists its provider too. Without it, the tools plugin remains PENDING as described in [chapter 6](06-composition-and-hmr.md).
-
-```sh
-node --import tsx ../../vendor/cordis/bin.js
-```
-
-```
-[tool-logger] greet -> Hello, Cordis!
-tool replied: [{"type":"text","text":"Hello, Cordis!"}]
-```
-
-The logger fired first: `tools/result` is emitted as part of result materialization, before `execute`'s promise resolves to the caller. Neither of your plugins knows the other exists — the registry service and the event connect them.
-
-## From here to a full agent
-
-A real agent is this composition plus more plugins: an LLM adapter, the agent loop, persistence, and an application entry. Compare the [base profile layer](../../packages/bundle/base/cordis.patch.yml) and [headless layer](../../packages/bundle/headless/cordis.patch.yml) — you can read their entries now. Add your `greet-tool.ts` through a small `--patch` overlay.
-
-Where to go next:
-
-- [Build a tool](../user/develop/basic/tool.md) — more of `defineTool`, including presentation and richer schemas.
-- [Three-layer capability design](../user/develop/practice/index.md) — how the harness structures replaceable capabilities.
-- The generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) — everything you can inject and listen to, each on its owning page.
-- [Architecture](../architecture.md) — the system map these plugins live in.
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/07-into-the-harness.zh.md

@@ -1,108 +0,0 @@
-# 7. 进入 harness
-
-[English](07-into-the-harness.md) | 中文
-
-本章会向 harness 的 `tools` 服务注册一个可由模型调用的工具，通过 harness 工具流水线执行它，并观察结果事件。整个示例无需密钥，也不会调用模型。
-
-## 工具插件
-
-创建 `greet-tool.ts`，将它放在 `tmp/cordis-tutorial` 中：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import { brandString } from '@deepseek-ai/dsh-brand'
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import type { ToolCallId } from '@deepseek-ai/dsh-llm'
-
-export const name = 'greet-tool'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.tools.register(defineTool({
-    name: 'greet',
-    description: 'Greet the named person.',
-    parameters: {
-      name: { type: 'string', required: true, description: 'Who to greet' },
-    },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value }],
-    },
-    async execute(args) {
-      return `Hello, ${args.name}!`
-    },
-  }))
-
-  // Drive one call through the real execution pipeline, standing in for
-  // the model. ToolCallId brands the correlation id a provider would issue.
-  void (async () => {
-    const result = await ctx.tools.execute({
-      callId: brandString<ToolCallId>('demo-1'),
-      name: 'greet',
-      arguments: { name: 'Cordis' },
-      signal: new AbortController().signal,
-    })
-    console.log('tool replied:', JSON.stringify(result.content))
-  })()
-}
-```
-
-这里的每个模式都来自前几章：`inject: ['tools']`（[第 3 章](03-services.zh.md)）会让插件等待工具注册表就绪；`ctx.tools.register(...)` 会把注册 disposer 附着到插件（[第 2 章](02-lifecycle-and-effects.zh.md)），因此卸载时会注销工具。`defineTool` 将 `parameters` 规约转换为向模型展示的 JSON Schema，推导 `args` 的类型，并在 `execute` 运行前校验模型提供的参数。工具返回由 `output.schema` 声明的规范值；`output.render` 则作为 Native renderer（原生渲染器），另行生成可持久化的结果内容。
-
-## 观察插件
-
-创建 `tool-logger.ts`。这是一个独立插件，通过 harness 的 `tools/result` 事件观察应用中的每次工具调用：
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '@deepseek-ai/dsh-tools'
-
-export const name = 'tool-logger'
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  ctx.on('tools/result', (exec, result) => {
-    const text = result.content
-      .map(block => (block.type === 'text' ? block.text : ''))
-      .join('')
-    console.log(`[tool-logger] ${exec.name} -> ${text}`)
-  })
-}
-```
-
-`import type {} from '@deepseek-ai/dsh-tools'` 行会引入该包的声明合并，使 `'tools/result'` 及其 payload 具有类型。这与第 4 章导入 `stats.ts` 的做法相同，只是扩展到了包级别。
-
-## 组合并运行
-
-```yaml
-- name: '@deepseek-ai/dsh-system-prompt'
-- name: '@deepseek-ai/dsh-tools'
-- name: './tool-logger.ts'
-- name: './greet-tool.ts'
-```
-
-`@deepseek-ai/dsh-tools` 会注入 `systemPrompt` 服务，因为工具需要向系统提示词贡献 schema，所以组合中也要列出该服务的提供方。缺少提供方时，工具插件会像[第 6 章](06-composition-and-hmr.zh.md)所述那样保持 PENDING。
-
-```sh
-node --import tsx ../../vendor/cordis/bin.js
-```
-
-```
-[tool-logger] greet -> Hello, Cordis!
-tool replied: [{"type":"text","text":"Hello, Cordis!"}]
-```
-
-logger 会先触发：`tools/result` 在结果物化过程中发出，发生在 `execute` 向调用方返回的 promise 兑现之前。两个插件都不知道另一个插件存在，它们由注册表服务和事件连接。
-
-## 从这里走向完整 agent（智能体）
-
-真实 agent 就是这套组合再加上更多插件：LLM（大语言模型）适配器、agent loop（智能体循环）、持久化和应用入口。对照 [base profile 层](../../packages/bundle/base/cordis.patch.yml)与 [headless 层](../../packages/bundle/headless/cordis.patch.yml)，你现在已经可以读懂其中各项。通过一个小型 `--patch` overlay 加入 `greet-tool.ts` 即可。
-
-后续可以阅读：
-
-- [构建工具](../user/develop/basic/tool.zh.md)：深入了解 `defineTool`，包括呈现和更丰富的 schema。
-- [三层能力设计](../user/develop/practice/index.zh.md)：harness 如何组织可替换能力。
-- [子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块：可以注入和监听的所有内容，各在其所属页面上。
-- [架构](../architecture.zh.md)：这些插件所处的系统地图。
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/index.i18n.yaml

@@ -1,16 +0,0 @@
-# Bilingual-pair consistency record for index.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/cordis-tutorial/index.md
-/cordis-tutorial:
-  en: 07671d53f483c796
-  zh: 495179dd609bf5a9
-/cordis-tutorial/setup:
-  en: beffc06ab58daf2d
-  zh: a0a2dd15e4a3989e
-/cordis-tutorial/chapters:
-  en: 1b72d8e48e2688f3
-  zh: a4beaacdca936766
-/cordis-tutorial/typescript-notes:
-  en: 60a3f108ca98e532
-  zh: 1cd4aabf471a576a

package/references/official-docs/docs/cordis-tutorial/index.md

@@ -1,60 +0,0 @@
-# Cordis tutorial
-
-English | [中文](index.zh.md)
-
-Cordis is the plugin framework underneath DeepSeek Harness: a small runtime where every capability — tools, LLM adapters, file access, the agent loop itself — is a plugin mounted into a shared context. This tutorial teaches Cordis hands-on: each chapter is a runnable example you build in a scratch directory inside this repository, ending with a plugin wired into real harness services.
-
-The audience is agent developers. You do not need deep TypeScript experience; the [TypeScript notes](#typescript-notes) below explain the syntax that may be unfamiliar, and every chapter shows the exact commands and expected output.
-
-If you want the condensed concept reference instead of a walkthrough, read the [Cordis primer](../cordis-primer.md). The exhaustive API reference lives in the generated `cordis-surface` regions on the [subsystem pages](../subsystems/core.md) and the [Cordis core API](../cordis-api/context.md) pages.
-
-To write plugins for the harness itself — loaded from a `cordis.yml` and driven from the Web UI rather than the launcher below — start from [your first Harness plugin](../user/develop/basic/index.md).
-
-## Setup
-
-You need a clone of this repository with dependencies installed; the [development guide](../development.md#setup-tutorial) lists the prerequisites. No API key is needed for this tutorial; every example runs keylessly.
-
-```sh
-git clone https://github.com/deepseek-ai/deepseek-harness.git
-cd deepseek-harness
-pnpm install
-```
-
-Create the scratch directory the chapters work in. `tmp/` is gitignored, so nothing you write there touches version control:
-
-```sh
-mkdir -p tmp/cordis-tutorial
-cd tmp/cordis-tutorial
-```
-
-Every chapter runs the same command from this directory:
-
-```sh
-node --import tsx ../../vendor/cordis/bin.js
-```
-
-That one-file launcher (see [vendor/cordis/bin.js](../../vendor/cordis/bin.js)) creates a root `Context`, mounts the Loader plugin, and tells it to load `./cordis.yml` from the current directory. Everything else — which plugins exist, how they are configured — comes from that YAML file, which you will write in a moment. The `--import tsx` flag lets Node run the TypeScript files the config points at without a build step.
-
-## Chapters
-
-1. [Your first plugin](01-first-plugin.md) — a plugin is a function; the loader mounts it.
-2. [Lifecycle and effects](02-lifecycle-and-effects.md) — Cordis-managed registrations are undone when their plugin unloads.
-3. [Services](03-services.md) — expose a capability on `ctx` and depend on it with `inject`.
-4. [Events](04-events.md) — typed events, broadcast dispatch, and the waterfall short-circuit.
-5. [Configuration](05-config.md) — validated config from `cordis.yml`, failing loud on bad input.
-6. [Composition and HMR](06-composition-and-hmr.md) — the config file as a plugin tree, hot reload, and diagnosing a plugin that never loads.
-7. [Into the harness](07-into-the-harness.md) — register a model-callable tool against real harness services.
-
-<a id="typescript-notes"></a>
-
-## TypeScript notes
-
-The examples use three TypeScript features beyond ordinary modern JavaScript:
-
-- **Type annotations** describe values without changing runtime behavior: `ctx: Context` says that `ctx` has the Cordis context API, `who: string` accepts text, and `string[]` means an array of strings.
-- **`import type { Context } from '@deepseek-ai/cordis'`** imports only type information. It vanishes at runtime, so a plugin file that needs `Context` solely for annotations adds no runtime dependency.
-- **Declaration merging** (`declare module '@deepseek-ai/cordis' { ... }`) adds your entries to interfaces that Cordis already declares — for example the type of a new `ctx.greeter` property or event name. It generates no runtime wiring; the plugin separately provides the service or emits the event. Chapter 3 shows the pattern in full.
-
-Chapter 5 also uses an `interface` to describe a configuration object's fields and a generic type such as `Schema<Config>` to say which object fields a schema validates. You can copy those declarations as shown; the surrounding text explains what each one connects.
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/cordis-tutorial/index.zh.md

@@ -1,62 +0,0 @@
-# Cordis 教程
-
-[English](index.md) | 中文
-
-Cordis 是 DeepSeek Harness 底层的插件框架：它是一个小型运行时，其中的每项能力，包括工具、LLM（大语言模型）适配器、文件访问乃至 agent loop（智能体循环）本身，都是挂载到共享上下文中的插件。本教程通过动手实践讲解 Cordis：每一章都是一个可以运行的示例，你将在本仓库内的临时目录中逐步构建它，最后把一个插件接入真实的 harness 服务。
-
-本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 [TypeScript 说明](#typescript-notes)会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
-
-如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.zh.md)。详尽的 API 参考见[子系统页面](../subsystems/core.zh.md)上生成的 `cordis-surface` 区块，以及 [Cordis 核心 API](../cordis-api/context.zh.md) 页面。
-
-如果你要为 harness 本身编写插件——由 `cordis.yml` 加载、在 Web UI 中驱动，而不是下面这个启动器——请从[第一个 Harness 插件](../user/develop/basic/index.zh.md)开始。
-
-<a id="setup"></a>
-
-## 准备工作
-
-你需要克隆本仓库并安装依赖；[开发指南](../development.zh.md#setup-tutorial)列出了前置条件。本教程不需要 API 密钥；所有示例均可在无密钥环境中运行。
-
-```sh
-git clone https://github.com/deepseek-ai/deepseek-harness.git
-cd deepseek-harness
-pnpm install
-```
-
-创建各章使用的临时目录。`tmp/` 已被 git 忽略，因此你在其中写入的任何内容都不会进入版本控制：
-
-```sh
-mkdir -p tmp/cordis-tutorial
-cd tmp/cordis-tutorial
-```
-
-每一章都从该目录运行同一条命令：
-
-```sh
-node --import tsx ../../vendor/cordis/bin.js
-```
-
-这个单文件启动器（见 [vendor/cordis/bin.js](../../vendor/cordis/bin.js)）会创建根 `Context`、挂载 Loader 插件，并让它从当前目录加载 `./cordis.yml`。其余所有内容，包括有哪些插件以及如何配置它们，都来自你稍后将编写的 YAML 文件。`--import tsx` 标志让 Node 无需构建步骤即可运行配置所指向的 TypeScript 文件。
-
-## 章节
-
-1. [你的第一个插件](01-first-plugin.zh.md)：插件是函数，由 loader 挂载。
-2. [生命周期与 effect](02-lifecycle-and-effects.zh.md)：由 Cordis 管理的注册会在所属插件卸载时撤销。
-3. [服务](03-services.zh.md)：在 `ctx` 上公开一项能力，并通过 `inject` 依赖它。
-4. [事件](04-events.zh.md)：类型化事件、广播分发和 waterfall（瀑布式事件）的短路行为。
-5. [配置](05-config.zh.md)：读取 `cordis.yml` 中经过校验的配置，并在输入错误时明确报错。
-6. [组合与 HMR（热模块替换）](06-composition-and-hmr.zh.md)：把配置文件作为插件树，使用热重载，并诊断始终无法加载的插件。
-7. [进入 harness](07-into-the-harness.zh.md)：基于真实的 harness 服务注册一个可由模型调用的工具。
-
-<a id="typescript-notes"></a>
-
-## TypeScript 说明
-
-这些示例使用了普通现代 JavaScript 之外的三项 TypeScript 功能：
-
-- **类型注解**描述值，但不会改变运行时行为：`ctx: Context` 表示 `ctx` 具备 Cordis 上下文 API，`who: string` 接受文本，而 `string[]` 表示字符串数组。
-- **`import type { Context } from '@deepseek-ai/cordis'`** 只导入类型信息。它在运行时会消失，因此仅为类型注解使用 `Context` 的插件文件不会增加运行时依赖。
-- **声明合并**（`declare module '@deepseek-ai/cordis' { ... }`）会为 Cordis 已经声明的接口添加你的条目，例如新 `ctx.greeter` 属性的类型或事件名称。它不会生成任何运行时接线；插件必须另行提供服务或发出事件。第 3 章会完整展示该模式。
-
-第 5 章还会使用 `interface` 描述配置对象的字段，并使用 `Schema<Config>` 这类泛型表示 schema 校验哪些对象字段。你可以直接照写这些声明；周围的正文会解释每项声明连接了什么。
-
-[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)

package/references/official-docs/docs/deepseek-llm-api-wire-extensions.i18n.yaml

@@ -1,34 +0,0 @@
-# Bilingual-pair consistency record for deepseek-llm-api-wire-extensions.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/deepseek-llm-api-wire-extensions.md
-/official-deepseek-llm-api-wire-extensions:
-  en: 39729b071744e94b
-  zh: f3a1913295e78b5f
-/official-deepseek-llm-api-wire-extensions/wire-namespaces-and-versioning:
-  en: 1da81051addc4b47
-  zh: 3e8d7cd3f8c1cdba
-/official-deepseek-llm-api-wire-extensions/request-headers:
-  en: 740e92e903ecb594
-  zh: f934d3c9e5c56bfe
-/official-deepseek-llm-api-wire-extensions/body-extension-transaction:
-  en: 48001cfd1281a23b
-  zh: d410530ae8aa2823
-/official-deepseek-llm-api-wire-extensions/dsh-plugin-packages:
-  en: f89059050613f3e8
-  zh: da5cf2a4eeb81b75
-/official-deepseek-llm-api-wire-extensions/dsh-session-log:
-  en: de1a3f2c377d74e3
-  zh: 7c803345f71117c5
-/official-deepseek-llm-api-wire-extensions/dsh-session-log/wire-session-header:
-  en: ccd8fcd773df21c4
-  zh: 7ea020068ad093ae
-/official-deepseek-llm-api-wire-extensions/dsh-session-log/canonical-event-envelopes:
-  en: 008a21df5e314154
-  zh: 8855710a37542ec5
-/official-deepseek-llm-api-wire-extensions/dsh-session-log/acceptance-watermark-and-at-least-once-delivery:
-  en: 4d84cb1e61f9cf58
-  zh: 8a63ce3069e2f0b3
-/official-deepseek-llm-api-wire-extensions/exposure-and-receiver-requirements:
-  en: ae93d9a44245b12f
-  zh: 8b95fc66c6e653c2