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

docs: address cookbook translation review

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-14 22:50:20 +08:00
parent 3d0ad3db3e
commit 1fbb1cb229
15 changed files with 50 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/cookbook/adding-a-package.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
adding-a-package.md: ff05f130e4ae5499c3f7b3ef8a73b1beeb00938d adding-a-package.md: 2930cee9ab64b382f6211335ae639bce45629d1d
adding-a-package.zh.md: 7b612ee1e7caf06075cb25851b61706ce7ac31db adding-a-package.zh.md: 10e906c320203c3658c103fc8936540f72697d65

2
docs/cookbook/adding-a-package.md
View File

@@ -2,7 +2,7 @@
English | [中文](adding-a-package.zh.md) English | [中文](adding-a-package.zh.md)
The file-by-file checklist for a new `@deepseek-ai/dsh-<name>` package. (Verified by the bash and adapter packages; if it drifts, fix it here.) The file-by-file checklist for a new `@deepseek-ai/dsh-<name>` package. This checklist is validated against the bash and adapter packages as templates; if it drifts from them, fix it here.
## 1. Create the package ## 1. Create the package

30
docs/cookbook/adding-a-package.zh.md
View File

@@ -1,10 +1,10 @@
# 实操手册：添加 workspace package # 实操手册：添加 workspace 包（package）
[English](adding-a-package.md) | 中文 [English](adding-a-package.md) | 中文
为新建 `@deepseek-ai/dsh-<name>` package 提供的逐文件清单。（已通过 bash 和 adapter package 验证；如有漂移，请在此修正。） 为新建 `@deepseek-ai/dsh-<name>` 包提供的逐文件清单。本清单以 bash 和 adapter 这两个包为模板进行验证；如果清单与模板有出入，请在此修正。
## 1. 创建 package ## 1. 创建包
``` ```
packages/<group>/<pkg>/ packages/<group>/<pkg>/
@@ -21,11 +21,11 @@ packages/<group>/<pkg>/
# (or a whitelist entry in scripts/verify-package-readme-limitations.ts) # (or a whitelist entry in scripts/verify-package-readme-limitations.ts)
``` ```
当已有分组与 package 的角色匹配时，选择该分组（`core`、`llm`、`bash`、`compact`、`subagent`、`todo`、`session-persistence`、`ui`、`util` 或 `support`）。允许新建分组，但分组只是纯容器：没有 `package.json`，没有源文件，package 仍然恰好位于其下一层。 当已有分组与包的角色匹配时，选择该分组（`core`、`llm`、`bash`、`compact`、`subagent`、`todo`、`session-persistence`、`ui`、`util` 或 `support`）。允许新建分组，但分组只是纯容器：没有 `package.json`，没有源文件，包仍然恰好位于其下一层。
package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表要精确：`lib/index.js`、`lib/types/**/*.d.ts`、`lib/types/**/*.d.ts.map` 和 `src`；不要发布 `lib/types` 下的 JS 或 JS-map 中间产物，也不要发布陈旧的根声明文件。带有 package `bin` 的 CLI 应用 package 在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。 package.json 不变式（由 `pnpm run constraints` / `scripts/check-workspace-constraints.ts` 强制执行）：`private: true`，`version` 与根 `package.json` 一致，`type: module`，`main: "lib/index.js"`，`types: "lib/types/index.d.ts"`，`exports["."].types: "./lib/types/index.d.ts"`，`exports["."].default: "./lib/index.js"`，`cordis` 同时出现在 peerDependencies 和 devDependencies 中（相同范围）。每个 dsh 对等依赖（peer dependency）都要在 devDependencies 中镜像。`schemastery` 放在 `dependencies` 中（它是运行时校验器），与 agent-loop 保持一致。`files` 列表要精确：`lib/index.js`、`lib/types/**/*.d.ts`、`lib/types/**/*.d.ts.map` 和 `src`；不要发布 `lib/types` 下的 JS 或 JS-map 中间产物，也不要发布陈旧的根声明文件。带有 `bin` 的 CLI 应用包在 `files` 中将 `lib/bin.js` 紧跟在 `lib/index.js` 之后。
package 内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export * from './types.ts'`）。编译器在输出的 JS 中将其重写为 `.js`，在声明文件中保留显式 `.ts` 后缀；标准的 NodeNext/Node16 TypeScript 消费方会将其解析到同目录的 `.d.ts` 文件。 包内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export * from './types.ts'`）。编译器在输出的 JS 中将其重写为 `.js`，在声明文件中保留显式 `.ts` 后缀；标准的 NodeNext/Node16 TypeScript 消费方会将其解析到同目录的 `.d.ts` 文件。
## 2. 在根配置中注册 ## 2. 在根配置中注册
@@ -34,17 +34,17 @@ package 内的相对导入在源码中使用显式 `.ts` 后缀（例如 `export
| `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 | | `tsconfig.base.json` | 已有分组无需编辑；新分组需为 `@deepseek-ai/dsh-*` 通配符添加 `./packages/<group>/*/src` 候选路径 |
| `tsconfig.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` | | `tsconfig.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` |
| `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` | | `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./packages/<group>/<pkg>" }` |
| `knip.json` | 仅当 package 有非 `*.spec.ts` 入口时需要（如 `*.e2e.ts` → 添加 per-workspace override，参照 `packages/llm/llm-deepseek`） | | `knip.json` | 仅当包有非 `*.spec.ts` 入口时需要（如 `*.e2e.ts` → 添加 per-workspace override，参照 `packages/llm/llm-deepseek`） |
以下内容由 glob 或 package-manifest 发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`、`scripts/check-workspace-constraints.ts`。 以下内容由 glob 或包 manifest 发现机制自动覆盖，无需手动编辑：根 `package.json` workspaces、`scripts/publint-all.ts`、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`、`scripts/check-workspace-constraints.ts`。
## 3. 确定 package 拓扑 ## 3. 确定包拓扑
对于可替换的能力，将接口、实现、消费方拆分为独立的 package（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个 package。 对于可替换的能力，将接口、实现、消费方拆分为独立的包（见 docs/architecture.md § "Capability seams"——bash 三组件是模板）。单一用途的插件保持为一个包。
## 4. 编写 package README ## 4. 编写包 README
将 package 特有的服务 API、配置、事件、扩展点和设计说明放在前面。limitations 部分记录持久的消费方缺口和本 package 拥有的非显而易见的维护者约束；日常清理事项留在源码 TODO 或 RFC 中。间接的 Model Experience 语句可以点名暴露本 package 贡献的消费方，但不重述该消费方的实现。package README 以如下规范序列结尾： 将包特有的服务 API、配置、事件、扩展点和设计说明放在前面。limitations 部分记录持久的消费方缺口和本包拥有的非显而易见的维护者约束；日常清理事项留在源码 TODO 或 RFC 中。间接的 Model Experience 语句可以点名暴露本包贡献的消费方，但不重述该消费方的实现。包 README 以如下规范序列结尾：
````markdown ````markdown
## Model Experience ## Model Experience
@@ -66,9 +66,9 @@ Stable system-prompt prose of any length, or another long non-generated literal,
- **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint. - **Consumer-visible gap** — exact boundary, consequence, or maintainer constraint.
```` ````
根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述两个字段。引用 package 拥有的稳定文本：系统提示词放在带标题的 H4 加 `markdown` 围栏中，其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。 根据实现填写 Model Experience。每个直接、条件、上限、生命周期或辅助模型的 surface 使用一个 H3，包含上述两个字段。引用包拥有的稳定文本：系统提示词放在带标题的 H4 加 `markdown` 围栏中，其他短文本以命名占位符内联，其他长文本使用相同的嵌套形式。仅概述数据依赖或提供方拥有的文本。tool-schema surface 链接到生成的[工具目录](../tool-catalog.md)中对应的锚定章节，仅说明该处缺失的差异。当作用域可以隐藏 prompt 或 schema 其中之一而不影响另一个时，将二者分开。[行文标准](../../.agents/skills/dsh-prose-standard/SKILL.md)约束完整性与归属；验证器强制执行机械形状。
没有上下文效果或仅有消费方拥有路径的 package 使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句；与模型无关的通用 package 可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个 package 工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience RFC](../rfc/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。 没有上下文效果或仅有消费方拥有路径的包使用 [`SENTENCE_MODEL_EXPERIENCE`](../../scripts/verify-package-readme-model-experience.ts) 中经过审计的 `None, as ` 或 `Indirectly, through ` 语句；与模型无关的通用包可以改为加入 `NO_MODEL_EXPERIENCE_SECTION`。两种情况都不要展开为对另一个包工作的描述。limitations [allowlist](../../scripts/verify-package-readme-limitations.ts) 独立管理。[Model Experience RFC](../rfc/implemented/process/2026-07-12-package-model-experience-contract.md) 记录了设计动机。
## 5. 验证 ## 5. 验证
@@ -80,4 +80,4 @@ pnpm run test:coverage # 100% per-file over src (types.ts exempt)
pnpm run build && pnpm run hygiene pnpm run build && pnpm run hygiene
``` ```
测试要求：每个注册表/注册操作都需要一个 HMR（热模块替换）安全测试（从子 fiber（插件运行时）注册，dispose（资源释放）它，断言清理完成）。鼓励编写充分的测试——见 [docs/testing.md](../testing.md)。 测试要求：每个注册表/注册操作都需要一个 HMR（热模块替换）安全测试（从子 fiber 注册，dispose（资源释放）它，断言清理完成）。鼓励编写充分的测试——见 [docs/testing.md](../testing.md)。

4
docs/cookbook/adding-a-tool.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
adding-a-tool.md: 3c6b3a143fd25c6fe7aefc59f0256d5bbef39b0c adding-a-tool.md: 4920c98894326fb8eab3b3d5df298baf1da33c1d
adding-a-tool.zh.md: ce8a59031bccb4b5710b95f1ee2c7ee89f44a823 adding-a-tool.zh.md: 3caf1e62f15f2f15103836b4d3f22be20ba02385

2
docs/cookbook/adding-a-tool.md
View File

@@ -51,7 +51,7 @@ Follow tool-bash's background pattern: a `run_in_background` flag returns a task
## Execution policy and observation ## Execution policy and observation
Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](./extension-cookbook.md#a-hook-plugin-permission-gate)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap core dispatch with a deadline/retry/metrics scope, `tools/post-execute` to transform or attach model-facing context, and `tools/result` to observe the immutable normalized outcome without changing it. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points). Prefer not to build deployment policy into the tool. Use `tools/pre-execute` for extensible allow/deny/ask policy (the [permission-gate example](./extension-cookbook.md#a-hook-plugin-permission-gate-example)), `ctx.tools.guard()` for a final monotonic deny that later listeners cannot undo, `tools/execute` to wrap core dispatch with a deadline/retry/metrics scope, `tools/post-execute` to transform or attach model-facing context, and `tools/result` to observe the immutable normalized outcome without changing it. A sandboxing implementation can also sit behind the tool's executor capability seam; the exact contracts are in the [`dsh-tools` README](../../packages/core/tools/README.md#extension-points).
## Code Mode reaches your tool for free ## Code Mode reaches your tool for free

6
docs/cookbook/adding-a-tool.zh.md
View File

@@ -2,7 +2,7 @@
[English](adding-a-tool.md) | 中文 [English](adding-a-tool.md) | 中文
如何为模型赋予一项新能力。参考实现：`examples/echo-agent/src/echo-tool.ts`（最小化）和 `packages/bash/tool-bash`（生产级，由三个 package 构成的 seam）。 如何为模型赋予一项新能力。参考实现：`examples/echo-agent/src/echo-tool.ts`（最小化）和 `packages/bash/tool-bash`（生产级，由三个包（package）构成的 seam）。
## 最小形态 ## 最小形态
@@ -31,7 +31,7 @@ export function apply(ctx: Context) {
} }
``` ```
注册基于副作用：dispose（资源释放）插件 fiber（插件运行时）即注销该工具（请编写 HMR（热模块替换）测试）。schema 会自动流入系统提示词的组装过程。 注册基于副作用：dispose（资源释放）插件 fiber 即注销该工具（请编写 HMR（热模块替换）测试）。schema 会自动流入系统提示词的组装过程。
## execute() 契约的规则 ## execute() 契约的规则
@@ -51,7 +51,7 @@ export function apply(ctx: Context) {
## 执行策略与观测 ## 执行策略与观测
尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许/拒绝/询问策略（见[权限门禁示例](./extension-cookbook.md#a-hook-plugin-permission-gate)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝（后续监听器无法撤销）；使用 `tools/execute` 为核心分发包装截止时间/重试/指标作用域；使用 `tools/post-execute` 转换或附加模型可见的上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。 尽量不要把部署策略内建到工具中。使用 `tools/pre-execute` 实现可扩展的允许/拒绝/询问策略（见[权限门禁示例](./extension-cookbook.md#a-hook-plugin-permission-gate-example)）；使用 `ctx.tools.guard()` 设置最终的单调拒绝（后续监听器无法撤销）；使用 `tools/execute` 为核心分发包装截止时间/重试/指标作用域；使用 `tools/post-execute` 转换或附加模型可见的上下文；使用 `tools/result` 观测不可变的归一化结果而不改变它。沙箱实现也可以位于工具执行器的能力 seam 之后；确切契约见 [`dsh-tools` README](../../packages/core/tools/README.md#extension-points)。
## Code Mode 自动触达你的工具 ## Code Mode 自动触达你的工具

2
docs/cookbook/adding-a-vendored-package.i18n.yaml
View File

@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
adding-a-vendored-package.md: d7b5b93b59fb39d8369be6eb42fb0a8b977c68b4 adding-a-vendored-package.md: d7b5b93b59fb39d8369be6eb42fb0a8b977c68b4
adding-a-vendored-package.zh.md: e1274b0855539e5f69b278b256c45fdcb57c048a adding-a-vendored-package.zh.md: 86b1e6c959180ba15b6fcb56b6dfe5a3be791b47

10
docs/cookbook/adding-a-vendored-package.zh.md
View File

@@ -1,8 +1,8 @@
# 实操手册：添加一个 vendored package # 实操手册：添加一个 vendored 包（package）
[English](adding-a-vendored-package.md) | 中文 [English](adding-a-vendored-package.md) | 中文
当 harness 需要引入另一个上游 Cordis package（如 `@cordisjs/plugin-http`）时，应将其作为固定版本的源码 **vendor** 到 `vendor/` 下，而非作为 npm 依赖添加——原因见[vendoring 决策](../rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md)。[vendor/README.md](../../vendor/README.md) 介绍如何*更新*已有的 vendored package；本指南是添加**新** vendored package 的逐文件清单。（已对照现有 vendored 集合验证；如有偏差，请在此修正。） 当 harness 需要引入另一个上游 Cordis 包（如 `@cordisjs/plugin-http`）时，应将其作为固定版本的源码 **vendor** 到 `vendor/` 下，而非作为 npm 依赖添加——原因见[vendoring 决策](../rfc/implemented/process/2026-06-11-vendor-cordis-as-source.md)。[vendor/README.md](../../vendor/README.md) 介绍如何*更新*已有的 vendored 包；本指南是添加**新** vendored 包的逐文件清单。（已对照现有 vendored 集合验证；如有偏差，请在此修正。）
## 1. 复制源码 ## 1. 复制源码
@@ -14,7 +14,7 @@ vendor/<dir>/
README.md LICENSE # if upstream ships them README.md LICENSE # if upstream ships them
``` ```
`tsconfig.json` 与其他 vendored package 保持一致：`rootDir: src`、`outDir: lib/types`、上游代码所需的严格性放宽项，以及对所导入的每个其他 vendored package 的 `references` 条目： `tsconfig.json` 与其他 vendored 包保持一致：`rootDir: src`、`outDir: lib/types`、上游代码所需的严格性放宽项，以及对所导入的每个其他 vendored 包的 `references` 条目：
```jsonc ```jsonc
{ {
@@ -29,7 +29,7 @@ vendor/<dir>/
} }
``` ```
`package.json` 的不变式：`"private": true`（vendored package 永不发布）；保留上游的 `name`/`version`/`exports`/`type`；声明元数据指向 `lib/types`；发布 `.d.ts` 与 `.d.ts.map` 声明输出；在 `peerDependencies` 中列出其 Cordis 依赖（与上游 manifest（元数据清单）一致）。传递性上游依赖本身也必须被 vendor 或已存在于仓库中——vendor 一个 package 往往意味着 vendor 其整条依赖树（如 `@cordisjs/plugin-http` 会拉入 `@cordisjs/fetch-file`）。 `package.json` 的不变式：`"private": true`（vendored 包永不发布）；保留上游的 `name`/`version`/`exports`/`type`；声明元数据指向 `lib/types`；发布 `.d.ts` 与 `.d.ts.map` 声明输出；在 `peerDependencies` 中列出其 Cordis 依赖（与上游 manifest（元数据清单）一致）。传递性上游依赖本身也必须被 vendor 或已存在于仓库中——vendor 一个包往往意味着 vendor 其整条依赖树（如 `@cordisjs/plugin-http` 会拉入 `@cordisjs/fetch-file`）。
vendored TypeScript 源码中的本地相对导入/导出在复制后使用显式 `.ts` 后缀。这是仓库本地的构建形态与上游的差异：`rewriteRelativeImportExtensions` 输出 `.js` 运行时导入，而声明文件保留显式 `.ts` 后缀，使 NodeNext/Node16 的 TypeScript 消费方能够解析。 vendored TypeScript 源码中的本地相对导入/导出在复制后使用显式 `.ts` 后缀。这是仓库本地的构建形态与上游的差异：`rewriteRelativeImportExtensions` 输出 `.js` 运行时导入，而声明文件保留显式 `.ts` 后缀，使 NodeNext/Node16 的 TypeScript 消费方能够解析。
@@ -41,7 +41,7 @@ vendored TypeScript 源码中的本地相对导入/导出在复制后使用显
| `tsconfig.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }` | | `tsconfig.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }` |
| `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }`（置于 `packages/*` 条目之前） | | `tsconfig.build.json` | 在 `references` 中添加 `{ "path": "./vendor/<dir>" }`（置于 `packages/*` 条目之前） |
| `vendor/README.md` | 添加一行 manifest 表格行（dir、npm name、version、upstream repo、commit SHA）并记录所有本地修改 | | `vendor/README.md` | 添加一行 manifest 表格行（dir、npm name、version、upstream repo、commit SHA）并记录所有本地修改 |
| `scripts/publint-all.ts` | 仅当该 vendored package 本身从此仓库发布时才需要（vendored 依赖通常不发布——跳过） | | `scripts/publint-all.ts` | 仅当该 vendored 包本身从此仓库发布时才需要（vendored 依赖通常不发布——跳过） |
以下由 glob 自动覆盖，无需手动编辑：根 `package.json` 的 workspaces（`vendor/*`）、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`。只有当构建形态偏离根默认值时（双 ESM/CJS 或多入口——参见 `vendor/schemastery` 和 `vendor/logger-console`），才需要单独的 `vendor/<dir>/tsdown.config.ts`；其入口应读取 `lib/types` 下输出的 JS。 以下由 glob 自动覆盖，无需手动编辑：根 `package.json` 的 workspaces（`vendor/*`）、`tsdown.config.ts`、`vitest.config.ts`、`eslint.config.mjs`。只有当构建形态偏离根默认值时（双 ESM/CJS 或多入口——参见 `vendor/schemastery` 和 `vendor/logger-console`），才需要单独的 `vendor/<dir>/tsdown.config.ts`；其入口应读取 `lib/types` 下输出的 JS。

4
docs/cookbook/extension-cookbook.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
extension-cookbook.md: 620d8957c360a755ab2d868a636044b3b755442e extension-cookbook.md: 40ee22b352c884d7f295c87726c54ab8e166c844
extension-cookbook.zh.md: c2ce077d37155cdbadc707994fea1c9a53b71fb3 extension-cookbook.zh.md: 4e5bc68c973649574bcb2404bea00096eb9ca41f

6
docs/cookbook/extension-cookbook.md
View File

@@ -2,15 +2,17 @@
English | [中文](extension-cookbook.zh.md) English | [中文](extension-cookbook.zh.md)
> FIXME: This important guide has not received sufficient human design review; complete that review before the first release.
The three plugin shapes you write against the harness extension surface, as illustrative snippets (elided imports and helper stubs — not copy-paste-complete). For the full step-by-step guides see [adding a package](./adding-a-package.md), [adding a tool](./adding-a-tool.md), and [adding an LLM adapter](./adding-an-llm-adapter.md); for the seams these hook into see [docs/architecture.md](../architecture.md). The three plugin shapes you write against the harness extension surface, as illustrative snippets (elided imports and helper stubs — not copy-paste-complete). For the full step-by-step guides see [adding a package](./adding-a-package.md), [adding a tool](./adding-a-tool.md), and [adding an LLM adapter](./adding-an-llm-adapter.md); for the seams these hook into see [docs/architecture.md](../architecture.md).
## A tool plugin ## A tool plugin
A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `execute` args, result shaping, the `run_in_background` pattern) lives in [adding-a-tool.md](./adding-a-tool.md) — that guide is the source of truth for the tool shape. Raw JSON-Schema `ToolDefinition`s are also accepted by `ctx.tools.register()` directly (that is how MCP-sourced tools arrive); `defineTool` is the typed sugar for first-party tools. A tool registers on `ctx.tools`. The annotated `defineTool` example (typed `execute` args, result shaping, the `run_in_background` pattern) lives in [adding-a-tool.md](./adding-a-tool.md) — that guide is the source of truth for the tool shape. Raw JSON-Schema `ToolDefinition`s are also accepted by `ctx.tools.register()` directly (that is how MCP-sourced tools arrive); `defineTool` is the typed sugar for first-party tools.
## A hook plugin (permission gate) ## A hook plugin (permission-gate example)
A hook returns a typed decision from the `tools/pre-execute` gate to allow or deny a call — the seam where sandbox, permission, and plan-mode plugins live. (A "native hook" is just this: an ordinary cordis plugin on the interception seams, returning typed decisions — no external protocol needed.) This permission gate is one example of a hook plugin. It returns a typed decision from the `tools/pre-execute` gate to allow or deny a call; sandbox, permission, and plan-mode plugins can use this seam. Hook plugins can intercept other seams and are not inherently permission gates. A "native hook" is an ordinary Cordis plugin on an interception seam; it needs no external protocol.
```ts ```ts
import type { Context } from 'cordis' import type { Context } from 'cordis'

10
docs/cookbook/extension-cookbook.zh.md
View File

@@ -2,15 +2,17 @@
[English](extension-cookbook.md) | 中文 [English](extension-cookbook.md) | 中文
针对 harness 扩展表面编写的三种插件形态，以示意性代码片段呈现（省略了 import 和辅助桩——不可直接复制运行）。完整的分步指南见[添加 package](./adding-a-package.md)、[添加工具](./adding-a-tool.md)和[添加 LLM（大语言模型）适配器](./adding-an-llm-adapter.md)；这些插件所挂接的 seam 见 [docs/architecture.md](../architecture.md)。 > FIXME：这篇重要指南尚未经过充分的人工设计审查；请在首次发布前完成审查。
针对 harness 扩展表面编写的三种插件形态，以示意性代码片段呈现（省略了 import 和辅助桩——不可直接复制运行）。完整的分步指南见[添加包（package）](./adding-a-package.md)、[添加工具](./adding-a-tool.md)和[添加 LLM（大语言模型）适配器](./adding-an-llm-adapter.md)；这些插件所挂接的 seam 见 [docs/architecture.md](../architecture.md)。
## 工具插件 ## 工具插件
工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](./adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON-Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。 工具在 `ctx.tools` 上注册。带注解的 `defineTool` 示例（类型化的 `execute` 参数、结果塑形、`run_in_background` 模式）见 [adding-a-tool.md](./adding-a-tool.md)——该指南是工具形态的真源。`ctx.tools.register()` 也直接接受原始 JSON-Schema `ToolDefinition`（MCP 来源的工具就是这样到达的）；`defineTool` 是为第一方工具提供的类型化语法糖。
## 钩子插件（权限门禁） ## 钩子插件（以权限门禁为例）
钩子从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用——这是沙箱、权限和 plan-mode 插件所在的 seam。（所谓"原生钩子"就是这样：一个挂在拦截 seam 上、返回类型化决策的普通 Cordis 插件，无需外部协议。） 这个权限门禁是钩子插件的一个示例。它从 `tools/pre-execute` 门禁返回一个类型化的决策，用于允许或拒绝一次调用；沙箱、权限和 plan-mode 插件都可以使用该 seam。钩子插件也可以拦截其他 seam，本身并不等同于权限门禁。「原生钩子」是在拦截 seam 上运行的普通 Cordis 插件，不需要外部协议。
```ts ```ts
import type { Context } from 'cordis' import type { Context } from 'cordis'
@@ -85,7 +87,7 @@ export function apply(ctx: Context) {
## 可运行的组装示例 ## 可运行的组装示例
三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app-package 入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent)，ACP 演示加载 [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent)，两个 app package 通过 [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle 共享主干。 三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app 包入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent)，ACP 演示加载 [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent)，两个 app 包通过 [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle 共享主干。
## 功能→机制映射 ## 功能→机制映射

4
docs/cookbook/responding-to-pr-review-on-a-stack.i18n.yaml
View File

@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority; # 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: # after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write # pnpm run verify-translation-pairing --write
responding-to-pr-review-on-a-stack.md: 96dfc594d26ffa8a2d44a1aff8d4a6918c88cc82 responding-to-pr-review-on-a-stack.md: 3fb7eb943eeb8d703303be3f6a844870cc26fd47
responding-to-pr-review-on-a-stack.zh.md: 7a5c764bef0a5844128f8df0fa190a046d7b7ce2 responding-to-pr-review-on-a-stack.zh.md: d96323b853c093265931904c20996df335f82926

4
docs/cookbook/responding-to-pr-review-on-a-stack.md
View File

@@ -2,7 +2,7 @@
English | [中文](responding-to-pr-review-on-a-stack.zh.md) English | [中文](responding-to-pr-review-on-a-stack.zh.md)
A wave of review comments lands across several PRs in a dependent stack (`A ← B ← C …`). This is the discipline for resolving it without corrupting the stack. The two invariants it rests on are standing orders in the root [AGENTS.md](../../AGENTS.md) § Conventions: merge commits only, and never rewrite a pushed branch. Review comments may target several PRs in a dependent stack (`A ← B ← C …`). This guide explains how to resolve them without corrupting the stack. The two invariants it rests on are standing orders in the root [AGENTS.md](../../AGENTS.md) § Conventions: merge commits only, and never rewrite a pushed branch.
## Ground rules ## Ground rules
@@ -11,7 +11,7 @@ A wave of review comments lands across several PRs in a dependent stack (`A ←
3. **A fix lands on the PR that INTRODUCED the issue, then flows down.** When a comment on PR `B` points at code `B` introduced, fix it on `B` and merge `B` into `C` — even if `C` also carries the file. Originating the fix downstream leaves `B` shipping the unfixed code and hides the fix from `B`'s reviewer. 3. **A fix lands on the PR that INTRODUCED the issue, then flows down.** When a comment on PR `B` points at code `B` introduced, fix it on `B` and merge `B` into `C` — even if `C` also carries the file. Originating the fix downstream leaves `B` shipping the unfixed code and hides the fix from `B`'s reviewer.
4. **Each review fix is a separate commit, never an amend.** The "fix review findings" commit documents what the review caught. Amending is fine only for your own not-yet-pushed, not-yet-reviewed work. 4. **Each review fix is a separate commit, never an amend.** The "fix review findings" commit documents what the review caught. Amending is fine only for your own not-yet-pushed, not-yet-reviewed work.
## Working the wave ## Resolve comments through the stack
1. Triage every comment on the merits before acting: verify the claim against the code — a reviewer flagging the right symptom can still mis-diagnose the cause. 1. Triage every comment on the merits before acting: verify the claim against the code — a reviewer flagging the right symptom can still mis-diagnose the cause.
2. Map each accepted finding to its originating PR, fix it there, then merge down the chain in order. 2. Map each accepted finding to its originating PR, fix it there, then merge down the chain in order.

4
docs/cookbook/responding-to-pr-review-on-a-stack.zh.md
View File

@@ -2,7 +2,7 @@
[English](responding-to-pr-review-on-a-stack.md) | 中文 [English](responding-to-pr-review-on-a-stack.md) | 中文
一波评审意见同时落在一条依赖堆叠（`A ← B ← C …`）中的多个 PR（Pull Request）上。本文规定在不破坏堆叠的前提下解决这些意见的纪律。它依赖的两个不变式是根 [AGENTS.md](../../AGENTS.md) § Conventions 中的常设指令：只用 merge commit，以及永远不改写已推送的分支。 评审意见可能同时针对一条依赖堆叠（`A ← B ← C …`）中的多个 PR（Pull Request）。本指南说明如何在不破坏堆叠的前提下解决这些意见。它依赖的两个不变式是根 [AGENTS.md](../../AGENTS.md) § Conventions 中的常设指令：只用 merge commit，以及永远不改写已推送的分支。
## 基本规则 ## 基本规则
@@ -11,7 +11,7 @@
3. **修复落在引入问题的那个 PR 上，然后向下流动。** 当 PR `B` 上的评论指向 `B` 引入的代码时，在 `B` 上修复，再将 `B` 合并到 `C`——即使 `C` 也包含该文件。把修复发起在下游会导致 `B` 带着未修复的代码交付，并对 `B` 的评审者隐藏修复。 3. **修复落在引入问题的那个 PR 上，然后向下流动。** 当 PR `B` 上的评论指向 `B` 引入的代码时，在 `B` 上修复，再将 `B` 合并到 `C`——即使 `C` 也包含该文件。把修复发起在下游会导致 `B` 带着未修复的代码交付，并对 `B` 的评审者隐藏修复。
4. **每个评审修复是一个独立 commit，绝不 amend。** "修复评审发现"的 commit 记录了评审捕获的内容。只有你自己尚未推送、尚未评审的工作才可以 amend。 4. **每个评审修复是一个独立 commit，绝不 amend。** "修复评审发现"的 commit 记录了评审捕获的内容。只有你自己尚未推送、尚未评审的工作才可以 amend。
## 处理评审浪潮 ## 沿堆叠解决评审意见
1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。 1. 在行动之前先就事论事地审视每条评论：对照代码验证其论断——评审者指出了正确的症状，但仍可能误诊原因。
2. 将每个被接受的发现映射到其发起 PR，在那里修复，然后按顺序沿链向下合并。 2. 将每个被接受的发现映射到其发起 PR，在那里修复，然后按顺序沿链向下合并。

4
docs/i18n/terminology.md
View File

@@ -40,7 +40,7 @@
| Cordis | Cordis | | | | | Cordis | Cordis | | | |
| dispose | dispose | dispose（资源释放） | | | | dispose | dispose | dispose（资源释放） | | |
| doc-sync | doc-sync | doc-sync（文档同步门禁） | | | | doc-sync | doc-sync | doc-sync（文档同步门禁） | | |
| fiber | fiber | fiber（插件运行时） | | | | fiber | fiber | | | |
| fixture | fixture | fixture（测试前置数据） | | | | fixture | fixture | fixture（测试前置数据） | | |
| fork | fork | | | | | fork | fork | | | |
| Function Calling | Function Calling | Function Calling（函数调用） | | | | Function Calling | Function Calling | Function Calling（函数调用） | | |
@@ -51,7 +51,6 @@
| loader | loader | | | | | loader | loader | | | |
| manifest | manifest | manifest（元数据清单） | | | | manifest | manifest | manifest（元数据清单） | | |
| monorepo | monorepo | | | | | monorepo | monorepo | | | |
| package | package | | | 保留英文；指 npm 包（`@deepseek-ai/dsh-*`） |
| schema | schema | | | | | schema | schema | | | |
| schema DSL | schema DSL | | | | | schema DSL | schema DSL | | | |
| seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` | | seam | seam | | | 与 `extension point` 是不同概念；根据具体语境，可译为`服务边界`或`可替换点` |
@@ -125,6 +124,7 @@
| module | 模块 | | | | | module | 模块 | | | |
| orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 | | orphan | 遗留 | | 孤儿、孤立 | 指英文源已不存在的 `.zh.md`（如「遗留译文」）；进程语境按 OS 惯用语译「孤儿进程」 |
| orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 | | orphan branch | 孤立分支 | | 孤儿分支 | 沿用 git 官方中文翻译 |
| package | 包 | 包（package） | | 指 npm 包（`@deepseek-ai/dsh-*`）；`package.json` 等代码标识保持原样 |
| pairing | 配对 | | | | | pairing | 配对 | | | |
| peer dependency | 对等依赖 | 对等依赖（peer dependency） | | | | peer dependency | 对等依赖 | 对等依赖（peer dependency） | | |
| permission | 权限 | | | | | permission | 权限 | | | |