mengzhx/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness.git synced 2026-08-29 04:26:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: complete Chinese proofreading and generated reference pairing

Browse Source
This commit is contained in:
xjt
2026-08-09 11:02:16 +08:00
parent 0543a6f79d
commit 7ff0cbcb7e
565 changed files with 10606 additions and 2171 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user/develop/basic/publish.i18n.yaml
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md
publish.md: 1d1179a78c4d3a7e9e7055e3f5ee41381e28147e
publish.zh.md: 26d1c2b737a3498bce0757d5b2d14e254fc13527
publish.zh.md: d683762b78920dc754b6871ed7bd0caf3ee9afd4
docs/user/develop/basic/publish.zh.md
+7 -7
View File
@@ -2,14 +2,14 @@
[English](publish.md) | 中文
前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**，用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
## 两个概念，两种 manifest
## 两个概念，两种 manifest（元数据清单）
安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest 种类不同，回答的问题也不同：
- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是「这个包贡献什么？」：一个插入或覆盖插件行的 patch 文件。
- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是「这套配置由哪些组合包按什么顺序组成？」。
组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
@@ -41,7 +41,7 @@ patch 文件的形状与你一直在写的 `--patch` overlay 相同——一个
name: dsh-hello-plugin
```
没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是"供插件包 import 的库"应有的形状，区别于"供用户启用的插件"。
没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。这正是「供插件包 import 的库」应有的形状，区别于「供用户启用的插件」。
### profile manifest
@@ -127,7 +127,7 @@ dsh plugin --profile demo add github:you/hello-plugin
然后重新执行 `add`。
请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent（智能体）运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
docs/user/guide/config.i18n.yaml
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/config.md
config.md: 34ab38c60cc7a9b6026f5be2be47f440eb6cb08d
config.zh.md: ce965dfc67c759ffcbad7b044b74abb2025851c2
config.zh.md: 621b5a75a98ab4b8d8517f4ec8894db0472e994c
docs/user/guide/config.zh.md
+2 -2
View File
@@ -47,7 +47,7 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
## CLI 补丁层
`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级 `$DSH_HOME/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
@@ -64,4 +64,4 @@ config:
## 精确配置参考
每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力 seam](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
docs/user/guide/index.i18n.yaml
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/index.md
index.md: a04698e29755d4a08b012f8b61accb79c470dcb0
index.zh.md: 85990f49c7b3cdf7518237c6b558375b7a636243
index.zh.md: 3808d9506fa9cb3a3e455ed478e4f02c18fc09ab
docs/user/guide/index.zh.md
+13 -13
View File
@@ -2,11 +2,11 @@
[English](index.md) | 中文
DeepSeek Harness 是一个**插件化的 Agent 开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
DeepSeek Harness 是一个**插件化的 agent（智能体）开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
## 它是什么
Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 Agent。
Harness 将 AI（人工智能） agent 所需的所有能力——LLM（大语言模型）调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 agent。
```yaml
# Select the LLM backend
@@ -27,26 +27,26 @@ Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调
### 应用使用者
如果你只是想用一个现成的 Agent 应用（如编程助手、对话代理），你需要的全部操作就是：
如果你只是想用一个现成的 agent 应用（如编程助手、对话代理），你需要的全部操作就是：
1. 复制一个 example 模板
2. 填写 API key
3. 运行
1. 复制一个示例模板。
2. 填写 API 密钥。
3. 运行。
不需要写任何代码。详见 [快速开始](./quickstart.md)。
### 插件开发者
如果你想为 Agent 添加新能力——一个自定义 tool、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
如果你想为 agent 添加新能力——一个自定义工具、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
## 核心特性
## 核心功能
- **只需要配置** — `cordis.yml` 决定能力集合，换模型、加工具只需改一行
- **随时替换 (HMR)** — 开发时修改插件代码，无需重启进程
- **HMR（热模块替换）** — 开发时修改插件代码，无需重启进程
## 技术栈
- **运行时**: Node.js ^22.19 或 >= 24
- **语言**: TypeScript (ESM)
- **框架**: Cordis
- **包管理**: pnpm workspaces（仓库固定使用 pnpm 11）
- **运行时**：Node.js ^22.19 或 >= 24
- **语言**：TypeScript（ESM）
- **框架**：Cordis
- **包管理**：pnpm workspaces（仓库固定使用 pnpm 11）
docs/user/guide/providers.i18n.yaml
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/providers.md
providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
providers.zh.md: f4a42a4093d253b4b230e4a838ba275a0ce58ac9
providers.zh.md: 0e48c31c7006a5c9c0b014e46bc7915d625389db
docs/user/guide/providers.zh.md
+4 -4
View File
@@ -2,14 +2,14 @@
[English](providers.md) | 中文
Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 Anthropic、OpenAI 这类内置目录里的提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
Harness 出厂自带 DeepSeek，同时预装了一个通用的多提供方适配器，用来接入 pi-ai 已安装目录中的 Anthropic、OpenAI 等提供方，或任何 OpenAI 兼容的网关与自建服务。你有两个入口：Web 界面的**模型**页，以及 `$DSH_HOME/settings.yaml`。两者写的是同一份文档，改完下一次请求即生效，不用重启。
## 提供方从哪里来
`cordis.yml` 决定装了哪些**适配器**，settings 文档决定跑哪些**提供方**。出厂组合里有两个 LLM 适配器：
- `llm-deepseek` 提供 `deepseek-official` 路由，是默认可用的那个。
- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出 provider profile，路由才注册上来；段落清空则一并撤下。
- `llm-pi-ai` 以**休眠**状态挂载：零路由，模型选择器里也不会多出条目，直到 settings 里的 `llm-pi-ai:` 段落给出提供方 profile，路由才注册上来；段落清空则一并撤下。
因此新增一个提供方通常不需要改 `cordis.yml`，写 settings 就够了——而模型页做的正是这件事。
@@ -120,7 +120,7 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
在 `dsh` 下，引用依次从继承环境、模型页的 `$DSH_HOME/.credentials.yaml` 存储、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析。未挂载凭据服务时，引用只读取同名环境变量。一份凭据供该路由上的所有模型使用。
## 让 agent 用上新提供方
## 让 agent（智能体）用上新提供方
配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
@@ -133,7 +133,7 @@ api-gateway:
reasoningEffort: high # optional
```
已经跑过一轮的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
已经跑过一个轮次的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
docs/user/guide/quickstart.i18n.yaml
+1 -1
View File
@@ -3,4 +3,4 @@
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write docs/user/guide/quickstart.md
quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
quickstart.zh.md: 7182f63586f4f08524c643a7c6c1ad599b2de098
quickstart.zh.md: 4c62b0a9deda3559f29ad214903ca55aea8b970e
docs/user/guide/quickstart.zh.md
+7 -7
View File
@@ -2,13 +2,13 @@
[English](quickstart.md) | 中文
本指南带你在 5 分钟内跑起一个 Agent。
本指南带你在 5 分钟内跑起一个 agent（智能体）。
## 环境准备
- [Node.js](https://nodejs.org/) ^22.19 或 >= 24
- 通过 Corepack 使用 [pnpm](https://pnpm.io/) 11
- [DeepSeek Platform](https://platform.deepseek.com/) API key
- [DeepSeek Platform](https://platform.deepseek.com/) API 密钥
```sh
node -v
@@ -16,7 +16,7 @@ corepack enable
pnpm -v
```
## 第一步：安装并配置 API key
## 第一步：安装并配置 API 密钥
```sh
git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git
@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
pnpm run dsh run "summarize the architecture of this workspace"
```
`dsh run` 创建并持久化一个新会话，打印最终 assistant 回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
## 第三步：使用 Web UI
@@ -51,12 +51,12 @@ pnpm run dsh web
打开 `http://127.0.0.1:3080`。agent 可以读写文件、运行命令、分配子任务和跟踪计划。可以尝试：`Create hello.js in the current directory, print "Hello from Harness!", and run it`。
## 回头看
## 运行原理
`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性 runner。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性运行器。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
## 下一步
- [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
- [配置文件](./config.md) — 了解 `cordis.yml` 的格式
- [开发插件](../develop/basic/) — 编写自己的 tool 或后端
- [开发插件](../develop/basic/) — 编写自己的工具或后端