Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(i18n): proofread active Chinese documentation

Browse Source
This commit is contained in:
xjt
2026-08-04 17:36:14 +08:00
parent 11bad56fc3
commit 2db712eec7
976 changed files with 3180 additions and 3105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/cordis-tutorial/02-lifecycle-and-effects.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/02-lifecycle-and-effects.md
02-lifecycle-and-effects.md: f1b39e06e9d25c51ab2d76503025e2b6ffe90c73
02-lifecycle-and-effects.zh.md: a6021ed7475a0045d480810747244274eb5b4198
02-lifecycle-and-effects.zh.md: 2e98e3af6d2f2b1b9cbb8ea38559bc1ffbf7e43b

10
docs/cordis-tutorial/02-lifecycle-and-effects.zh.md
View File

@@ -2,11 +2,11 @@
[English](02-lifecycle-and-effects.md) | 中文
Cordis 插件可能因配置编辑、热重载、显式资源释放或所需服务消失而卸载。通过 Cordis API 建立的注册属于 effect，会在所属插件卸载时撤销；在这些 API 之外管理的资源必须包装在 `ctx.effect()` 中。
Cordis 插件可能因修改配置、热重载、显式资源释放或所需服务消失而卸载。通过 Cordis API 建立的注册属于 effect，会在所属插件卸载时撤销；在这些 API 之外管理的资源必须包装在 `ctx.effect()` 中。
## Effect
对于 Cordis 尚未管理的资源，例如定时器、连接或 watcher，应将其包装在 `ctx.effect()` 中并返回 disposer（dispose（资源释放）函数）：
对于 Cordis 尚未管理的资源，例如定时器、连接或 watcher，应将其包装在 `ctx.effect()` 中并返回 disposer（资源释放函数）：
创建 `lifecycle.ts`，将它放在 `tmp/cordis-tutorial` 中：
@@ -67,7 +67,7 @@ disposed
## Fiber 状态机
每个已加载插件实例都拥有一个 fiber，并依次经过以下状态：
每个已加载插件实例都拥有一个 fiber，并在以下状态之间转换：
```
PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
@@ -86,8 +86,8 @@ PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
你很少需要亲自编写 `ctx.effect()`，因为内置注册 API 本身已经是 effect：
- `ctx.on(event, listener)`：监听器会在卸载时移除（[第 4 章](04-events.md)）。
- `ctx.plugin(child)`：子插件会随父插件一同 dispose。
- 服务注册属于 effect。`ctx.tools.register(...)` 等 harness 注册表也会把返回的 disposer 附着到调用插件上，因此会自动回卷（[第 7 章](07-into-the-harness.md)）。
- `ctx.plugin(child)`：子插件会随父插件一同 dispose（资源释放）。
- 服务注册属于 effect。`ctx.tools.register(...)` 等 harness 注册表也会把返回的 disposer 附着到调用插件上，因此会自动撤销（[第 7 章](07-into-the-harness.md)）。
对于 Cordis 不管理的资源，应在 `ctx.effect()` 内获取它，并返回用于释放资源的 disposer。此后 Cordis 会在卸载期间调用该释放逻辑，热重载时也不例外。

4
docs/cordis-tutorial/03-services.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/03-services.md
03-services.md: 5848132c6ad18338fa893954d45fc20005db6199
03-services.zh.md: 3c77d0451df9062f1a344e7474e6be141b709197
03-services.zh.md: 0f599f082573364e6ad38278e1914d8faf67faa1

6
docs/cordis-tutorial/03-services.zh.md
View File

@@ -2,7 +2,7 @@
[English](03-services.md) | 中文
**服务**是一个插件提供、其他插件通过 `ctx` 消费的命名功能。在 harness 中，`ctx.tools`、`ctx.llm` 和 `ctx.agents` 都是服务。消费方只命名 `'tools'` 之类的功能，而不导入其提供方，因此配置可以选择提供方，无需修改消费方。
**服务**是一个插件提供、其他插件通过 `ctx` 消费的具名能力。在 harness 中，`ctx.tools`、`ctx.llm` 和 `ctx.agents` 都是服务。消费方只指定 `'tools'` 之类的能力，而不导入其提供方，因此配置可以选择提供方，无需修改消费方。
## 提供服务
@@ -73,9 +73,9 @@ Hello, world!
## 加载后仍会跟踪依赖关系
`inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](02-lifecycle-and-effects.md)），这能防止运行中的消费方保留对不可用服务的引用：依赖消失时，它自己的注册也会回卷。
`inject` 并非一次性的启动检查。如果应用运行期间所需服务消失，例如提供方被卸载或热替换，每个依赖插件也会随之卸载，并在服务恢复后再次加载。结合 effect（[第 2 章](02-lifecycle-and-effects.md)），这能防止运行中的消费方保留对不可用服务的引用：依赖消失时，它自己的注册也会撤销。
这也是配置中可以替换服务的原因：卸载 `dsh-bash-local` 配置项，挂载另一个 `bash` 提供方，所有注入 `'bash'` 的插件都会干净地重启并使用新实现。
这也是配置中可以替换服务的原因：卸载 Cordis 配置项 `dsh-bash-local`，挂载另一个 `bash` 提供方，所有注入 `'bash'` 的插件都会重新启动并使用新实现。
## 可选依赖

4
docs/cordis-tutorial/04-events.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/04-events.md
04-events.md: 18f39dc1b693e5fb7e1793ec4b7dcac9cf24db95
04-events.zh.md: f55a61ff2f43ea42968893d07eb92ea0613b921a
04-events.zh.md: 3fdafb50303f49dca179bcaea32db211a66241f6

2
docs/cordis-tutorial/04-events.zh.md
View File

@@ -91,7 +91,7 @@ export function apply(ctx: Context) {
每个 harness 事件都会在生成的[事件目录](../cordis-catalog/events.md)中记录其模式。
## Waterfall：转换或短路
## waterfall：转换或短路
waterfall 是实现拦截的模式。每个监听器都会收到参数和一个 `next()` continuation；它可以转换 `next()` 的返回值，也可以不调用 `next()` 就直接返回，从而短路链条的其余部分。Cordis 文档把后一种行为称为否决。创建 `waterfall-demo.ts`：

4
docs/cordis-tutorial/05-config.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/05-config.md
05-config.md: fc19add239636fa9e7071d9c77e48595caec1f08
05-config.zh.md: 52a75e40672c9a08d285677dd14dcd404b925e5a
05-config.zh.md: 0c8170f518f0c87ab5c754606436496a4ff9d51e

8
docs/cordis-tutorial/05-config.zh.md
View File

@@ -2,7 +2,7 @@
[English](05-config.md) | 中文
每个 `cordis.yml` 配置项都可以携带 `config` 块，插件则声明一个 schema，在运行 `apply` 前验证该块。错误配置会导致加载失败，并给出准确的错误：插件绝不会在配置不完整时启动。
`cordis.yml` 中的每个 Cordis 配置项都可以携带 `config` 块，插件则声明一个 schema，在运行 `apply` 前验证该块。错误配置会导致加载失败，并给出准确的错误：插件绝不会在配置不完整时启动。
## 可配置插件
@@ -65,7 +65,7 @@ ValidationError: invalid config:
- $.targets expected array but got not-an-array (at targets)
```
插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的 schema 有效配置命名了不可用的资源或提供方，该插件也应当在能解析该引用时立即拒绝。
插件的 fiber 进入 FAILED 状态，本教程的启动器打印错误后以状态码 1 退出。如果某个插件的配置通过了 schema 验证，但其中指定的资源或提供方不可用，该插件也应当在能解析该引用时立即拒绝。
## 计算得到的配置值
@@ -77,8 +77,8 @@ ValidationError: invalid config:
apiKey: !!js process.env.DEEPSEEK_API_KEY
```
`!!js` **仅在 `config` 内有效**。配置项元数据（`name`、`id`、`disabled`、`inject` 等）是静态的；`disabled: !!js ...` 会生成一个真值表达式对象，始终禁用该配置项。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
`!!js` **仅在 `config` 内有效**。Cordis 配置项的元数据（`name`、`id`、`disabled`、`inject` 等）是静态的；`disabled: !!js ...` 会生成一个真值表达式对象，始终禁用该 Cordis 配置项。详见 [loader 配置](../cordis-primer.md#loader-configuration)。
下一章：[组合与 HMR](06-composition-and-hmr.md)：将 `cordis.yml` 视为应用。
下一章：[组合与 HMR（热模块替换）](06-composition-and-hmr.md)：将 `cordis.yml` 视为应用。
[![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-harness/deepseek-harness)

4
docs/cordis-tutorial/06-composition-and-hmr.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/06-composition-and-hmr.md
06-composition-and-hmr.md: 66d6a9d93fe39baa881940ba32388979e2678505
06-composition-and-hmr.zh.md: ebe63fc26607ae6d9344c4795a7975496ed901b5
06-composition-and-hmr.zh.md: 7c0a94b0abcc0f153f59391fd009f1e0b40500e5

14
docs/cordis-tutorial/06-composition-and-hmr.zh.md
View File

@@ -2,11 +2,11 @@
[English](06-composition-and-hmr.md) | 中文
到目前为止构建的每项功能都是插件，`cordis.yml` 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。
到目前为止构建的每项能力都是插件，`cordis.yml` 则选择应用的插件树。本章会改变这种组合、热重载一个插件，并诊断始终无法加载的插件。
## 配置项不只有名称
## Cordis 配置项不只有名称
配置项除了 `name` 和 `config`，还接受其他元数据：
Cordis 配置项除了 `name` 和 `config`，还接受其他元数据：
```yaml
- id: greeter # stable identity for this entry
@@ -16,9 +16,9 @@
disabled: true # keep the entry, skip mounting it
```
`id` 为配置项提供稳定标识，使 loader 能区分修改现有配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
`id` 为 Cordis 配置项提供稳定标识，使 loader 能区分修改现有 Cordis 配置项与先删除再添加。`disabled: true` 会卸载插件而不删除其 Cordis 配置项；改回原值后，插件以及所有因依赖其服务而处于 PENDING 的插件都会再次加载。
组可以嵌套一份配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。这些概念值得在用到之前先了解；[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
组可以嵌套一份 Cordis 配置项子列表，并将其作为一个单元加载和卸载；`isolate` 则为一个组提供某项服务名称的独立实例，因此两个组可以各自看到配置不同的 `bash`，互不影响。这些概念值得在用到之前先了解；[Cordis 入门](../cordis-primer.md)和[服务隔离示例](../user/develop/framework/service.md#service-isolation)介绍了详细内容。
## 热模块替换
@@ -39,7 +39,7 @@
name: './hello.ts'
```
列表中增加了两个支持插件：HMR 通过 Cordis logger 服务记录日志，因此没有 console exporter 时看不到其消息；它还会 `inject` `timer` 服务来实现去抖，如果没有 `@cordisjs/plugin-timer`，它就会永远停在 PENDING，而且不发出任何提示。下一节就讨论这种静默状态。
列表中增加了两个辅助插件：HMR 通过 Cordis logger 服务记录日志，因此没有控制台导出器时看不到其消息；它还会 `inject` `timer` 服务来实现去抖，如果没有 `@cordisjs/plugin-timer`，它就会永远停在 PENDING，而且不发出任何提示。下一节就讨论这种静默状态。
HMR 通过 Loader 的原生辅助工具读取 Node 的 loader 内部结构。请在 tsx 下运行 Cordis：
@@ -56,7 +56,7 @@ hello from my first plugin
hello from my EDITED plugin
```
旧实例先卸载（其所有 effect 都会回卷），新代码随后加载，`apply` 再次运行。按 Ctrl-C 停止进程。编辑 `cordis.yml` 本身也会触发更新：loader 按 `id` 比较配置项，只挂载、卸载或重新配置发生变化的部分。这就是上述配置项显式携带 `id` 的原因：不带该字段的配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使自身文本未变，它也会被视为先删除再添加并重新挂载。
旧实例先卸载（其所有 effect 都会回卷），新代码随后加载，`apply` 再次运行。按 Ctrl-C 停止进程。编辑 `cordis.yml` 本身也会触发更新：loader 按 `id` 比较 Cordis 配置项，只挂载、卸载或重新配置发生变化的部分。这就是上述 Cordis 配置项显式携带 `id` 的原因：不带该字段的 Cordis 配置项在每次读取时都会获得一个新生成的 id，所以只要配置文件发生任何编辑，即使自身文本未变，它也会被视为先删除再添加并重新挂载。
## 诊断始终无法加载的插件

4
docs/cordis-tutorial/07-into-the-harness.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/07-into-the-harness.md
07-into-the-harness.md: 6ec42c50fe5059955734fe7bc46117538dafaffc
07-into-the-harness.zh.md: 32b21b008837e2972a53db9d893788dc6a7de9a9
07-into-the-harness.zh.md: 903adb903aa4c4355b92eb34e89f218a0295767c

6
docs/cordis-tutorial/07-into-the-harness.zh.md
View File

@@ -46,7 +46,7 @@ export function apply(ctx: Context) {
}
```
这里的每个模式都来自前几章：`inject: ['tools']`（[第 3 章](03-services.md)）会让插件等待工具注册表就绪；`ctx.tools.register(...)` 会把注册 disposer 附着到插件（[第 2 章](02-lifecycle-and-effects.md)），因此卸载时会注销工具。`defineTool` 将 `parameters` 规约转换为向模型展示的 JSON Schema，推导 `args` 的类型，并在 `execute` 运行前校验模型提供的参数。工具返回由 `output.schema` 声明的规范值；`output.render` 则另行生成原生且持久的结果内容。
这里的每个模式都来自前几章：`inject: ['tools']`（[第 3 章](03-services.md)）会让插件等待工具注册表就绪；`ctx.tools.register(...)` 会把注册 disposer 附着到插件（[第 2 章](02-lifecycle-and-effects.md)），因此卸载时会注销工具。`defineTool` 将 `parameters` 规约转换为向模型展示的 JSON Schema，推导 `args` 的类型，并在 `execute` 运行前校验模型提供的参数。工具返回由 `output.schema` 声明的规范值；`output.render` 则作为 Native renderer（原生渲染器），另行生成可持久化的结果内容。
## 观察插件
@@ -91,7 +91,7 @@ node --import tsx ../../vendor/cordis/bin.js
tool replied: [{"type":"text","text":"Hello, Cordis!"}]
```
logger 会先触发：`tools/result` 在结果物化过程中发出，早于 `execute` 的 promise 向调用方返回结果。两个插件都不知道另一个插件存在，它们由注册表服务和事件连接。
logger 会先触发：`tools/result` 在结果物化过程中发出，发生在 `execute` 向调用方返回的 promise 兑现之前。两个插件都不知道另一个插件存在，它们由注册表服务和事件连接。
## 从这里走向完整 agent（智能体）
@@ -100,7 +100,7 @@ logger 会先触发：`tools/result` 在结果物化过程中发出，早于 `ex
后续可以阅读：
- [构建工具](../user/develop/basic/tool.md)：深入了解 `defineTool`，包括呈现和更丰富的 schema。
- [三层功能设计](../user/develop/practice/index.md)：harness 如何组织可替换功能。
- [三层能力设计](../user/develop/practice/index.md)：harness 如何组织可替换能力。
- 生成的[服务](../cordis-catalog/services.md)与[事件](../cordis-catalog/events.md)目录：可以注入和监听的所有内容。
- [架构](../architecture.md)：这些插件所处的系统地图。

4
docs/cordis-tutorial/index.i18n.yaml
View File

@@ -1,6 +1,6 @@
# 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
# pnpm run verify-translation-pairing --write docs/cordis-tutorial/index.md
index.md: af622ad4e35829c6283c40f1b0019d7959dac973
index.zh.md: 35bad552ecce9c0496b0ed88b041a8109c81945b
index.zh.md: 0b7684a9532a1efdcc3ea2d067da23852d146e2f

4
docs/cordis-tutorial/index.zh.md
View File

@@ -6,7 +6,7 @@ Cordis 是 DeepSeek Harness SDK 底层的插件框架：它是一个小型运行
本教程面向 agent 开发者。你不需要深入掌握 TypeScript；下文的 [TypeScript 说明](#typescript-notes)会解释可能陌生的语法，并且每一章都会给出确切命令和预期输出。
如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见生成的[事件](../cordis-catalog/events.md)与[服务](../cordis-catalog/services.md)目录，以及 [Cordis 核心 API](../cordis-catalog/core/context.md)页面。
如果你想阅读精简的概念参考，而不是逐步实践，请参阅 [Cordis 入门](../cordis-primer.md)。详尽的 API 参考见生成的[事件](../cordis-catalog/events.md)与[服务](../cordis-catalog/services.md)目录，以及 [Cordis 核心 API](../cordis-catalog/core/context.md) 页面。
## 准备工作
@@ -39,7 +39,7 @@ node --import tsx ../../vendor/cordis/bin.js
2. [生命周期与 effect](02-lifecycle-and-effects.md)：由 Cordis 管理的注册会在所属插件卸载时撤销。
3. [服务](03-services.md)：在 `ctx` 上公开一项能力，并通过 `inject` 依赖它。
4. [事件](04-events.md)：类型化事件、广播分发和 waterfall（瀑布式事件）的短路行为。
5. [配置](05-config.md)：读取 `cordis.yml` 中经过校验的配置，并在输入错误时快速失败。
5. [配置](05-config.md)：读取 `cordis.yml` 中经过校验的配置，并在输入错误时明确报错。
6. [组合与 HMR（热模块替换）](06-composition-and-hmr.md)：把配置文件作为插件树，使用热重载，并诊断始终无法加载的插件。
7. [进入 harness](07-into-the-harness.md)：基于真实的 harness 服务注册一个可由模型调用的工具。