fix(docs): align site with bilingual source pairs

2026-08-15 21:04:50 +00:00 · 2026-07-15 18:08:28 +08:00
parent e0a0b8b06d
commit 6af61c6f4e
43 changed files with 2112 additions and 353 deletions
--- a/docs/user/guide/config.i18n.yaml
+++ b/docs/user/guide/config.i18n.yaml
@@ -0,0 +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
+config.md: 0cad49d9bd82813da230a44d526190d4e0b6a730
+config.zh.md: ee1ea9a0c1d9010be8c1a3984acdcbe870e30584
--- a/docs/user/guide/config.md
+++ b/docs/user/guide/config.md
@@ -0,0 +1,59 @@
+# Configuration
+
+English | [中文](config.zh.md)
+
+Harness uses `cordis.yml` to describe which plugins an agent loads and the configuration passed to each one. The file composes capabilities; the generated configuration catalog records the fields and defaults each package actually supports, avoiding a second hand-maintained reference.
+
+## Start from a real configuration
+
+The repository examples are runnable configurations and the most reliable starting points for a new project:
+
+- [echo-agent](../../../examples/echo-agent/cordis.yml) uses a local mock model and needs no API key.
+- [coding-agent](../../../examples/coding-agent/cordis.yml) combines the DeepSeek model, Bash, filesystem, compaction, subagents, and workflows.
+- [acp-agent](../../../examples/acp-agent/cordis.yml) connects to editor clients over ACP.
+
+A minimal configuration is a list of plugin entries:
+
+```yaml
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models:
+      - deepseek-v4-flash
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+```
+
+## Plugin entries
+
+`name` identifies an npm package or a local module relative to `cordis.yml`; `id` gives the plugin instance a stable identity; and `config` supplies plugin-specific configuration. Set `disabled: true` to skip an entry temporarily.
+
+```yaml
+- id: local-tool
+  name: './src/my-tool.ts'
+  disabled: false
+  config:
+    toolName: my_tool
+```
+
+Plugins load in file order. Place plugins that depend on services after the applications or capability plugins that provide them. Missing models, tools, and plugins fail as early as possible instead of being silently ignored.
+
+## JavaScript values and environment variables
+
+The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
+
+```yaml
+config:
+  apiKey: !!js process.env.DEEPSEEK_API_KEY
+  cwd: !!js process.cwd()
+```
+
+The tag is `!!js`, not `!js`.
+
+## Exact configuration reference
+
+The generated [plugin configuration catalog](../../config-catalog.md) lists every current field, type, and default. For composition concepts, continue to the [architecture](../../architecture.md) and [capability interfaces](../../capability-seams.md). To create a configuration, copy the closest entry from the [examples overview](../../../examples/README.md) and adapt it.
--- a/docs/user/guide/config.zh.md
+++ b/docs/user/guide/config.zh.md
@@ -0,0 +1,59 @@
+# 配置文件
+
+[English](config.md) | 中文
+
+Harness 使用 `cordis.yml` 描述 Agent 加载哪些插件以及每个插件的参数。配置文件负责组合能力；每个包真正支持的字段和默认值由源码生成的配置目录负责记录，避免两份手写表格逐渐不一致。
+
+## 从真实配置开始
+
+仓库中的示例就是可以运行的配置，也是新项目最可靠的起点：
+
+- [echo-agent](../../../examples/echo-agent/cordis.yml) 使用本地 mock 模型，不需要 API key。
+- [coding-agent](../../../examples/coding-agent/cordis.yml) 组合 DeepSeek 模型、Bash、文件系统、压缩、子代理和工作流。
+- [acp-agent](../../../examples/acp-agent/cordis.yml) 通过 ACP 接入编辑器客户端。
+
+最小配置由一组插件条目组成：
+
+```yaml
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models:
+      - deepseek-v4-flash
+
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+```
+
+## 插件条目
+
+`name` 指定 npm 包或相对于 `cordis.yml` 的本地模块，`id` 为插件实例提供稳定标识，`config` 传入插件自己的配置。需要临时跳过某个条目时可设置 `disabled: true`。
+
+```yaml
+- id: local-tool
+  name: './src/my-tool.ts'
+  disabled: false
+  config:
+    toolName: my_tool
+```
+
+插件按文件中的顺序加载。依赖其他服务的插件应该排在提供这些服务的应用或能力插件之后；引用不存在的模型、工具或插件会尽早报错，而不是被静默忽略。
+
+## JavaScript 值和环境变量
+
+Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。
+
+```yaml
+config:
+  apiKey: !!js process.env.DEEPSEEK_API_KEY
+  cwd: !!js process.cwd()
+```
+
+标签是 `!!js`，不是 `!js`。
+
+## 精确配置参考
+
+每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
--- a/docs/user/guide/index.i18n.yaml
+++ b/docs/user/guide/index.i18n.yaml
@@ -0,0 +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
+index.md: 4daf7fdc76b38b5d10cc8b4726d9b6239a72933f
+index.zh.md: 1f41078822009234cbaf513aaa8dbc01c4b5d879
--- a/docs/user/guide/index.md
+++ b/docs/user/guide/index.md
@@ -0,0 +1,49 @@
+# Introduction
+
+English | [中文](index.zh.md)
+
+DeepSeek Harness is a **plugin-based agent development framework** built on the [Cordis](https://github.com/cordiverse/cordis) microkernel. Its central idea is simple: **everything is a plugin**.
+
+## What it is
+
+Harness implements every capability an AI agent needs—including LLM calls, tool execution, session management, and subtask delegation—as a composable plugin. A `cordis.yml` file declares which plugins to load and how to configure them, assembling a complete agent.
+
+```yaml
+# Select the LLM backend
+- name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+
+# Select the application template
+- name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+```
+
+## Who it is for
+
+### Application users
+
+To run an existing agent application, such as a coding assistant or conversational agent:
+
+1. Copy an example template.
+2. Add an API key.
+3. Run it.
+
+No code is required. See the [quick start](./quickstart.md).
+
+### Plugin developers
+
+To add a custom tool, a new LLM adapter, or another execution backend, write a plugin. Harness provides explicit extension interfaces and a type-safe development experience. See [development](../develop/basic/).
+
+## Core features
+
+- **Configuration only** — `cordis.yml` selects the capability set; changing a model or adding a tool is a configuration edit.
+- **Hot replacement (HMR)** — edit plugin code during development without restarting the process.
+
+## Technology
+
+- **Runtime**: Node.js ^22.19 or >= 24
+- **Language**: TypeScript (ESM)
+- **Framework**: Cordis
+- **Package manager**: pnpm workspaces (the repository pins pnpm 11)
--- a/docs/user/guide/index.zh.md
+++ b/docs/user/guide/index.zh.md
@@ -0,0 +1,49 @@
+# 介绍
+
+[English](index.md) | 中文
+
+DeepSeek Harness 是一个**插件化的 Agent 开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
+
+## 它是什么
+
+Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 Agent。
+
+```yaml
+# Select the LLM backend
+- name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+
+# Select the application template
+- name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+```
+
+## 适合谁
+
+### 应用使用者
+
+如果你只是想用一个现成的 Agent 应用（如编程助手、对话代理），你需要的全部操作就是：
+
+1. 复制一个 example 模板
+2. 填写 API key
+3. 运行
+
+不需要写任何代码。详见 [快速开始](./quickstart.md)。
+
+### 插件开发者
+
+如果你想为 Agent 添加新能力——一个自定义 tool、一个新的 LLM 适配器、一个新的执行后端——你需要编写一个插件。Harness 提供了清晰的扩展接口和类型安全的开发体验。详见 [开发](../develop/basic/)。
+
+## 核心特性
+
+- **只需要配置** — `cordis.yml` 决定能力集合，换模型、加工具只需改一行
+- **随时替换 (HMR)** — 开发时修改插件代码，无需重启进程
+
+## 技术栈
+
+- **运行时**: Node.js ^22.19 或 >= 24
+- **语言**: TypeScript (ESM)
+- **框架**: Cordis
+- **包管理**: pnpm workspaces（仓库固定使用 pnpm 11）
--- a/docs/user/guide/quickstart.i18n.yaml
+++ b/docs/user/guide/quickstart.i18n.yaml
@@ -0,0 +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
+quickstart.md: c2932cf5a5f49c3e3ddb887866b421c6e6cad7a1
+quickstart.zh.md: 54ddb50be31203e98d4cd75d0b8851f8f0e14cc5
--- a/docs/user/guide/quickstart.md
+++ b/docs/user/guide/quickstart.md
@@ -0,0 +1,99 @@
+# Quick start
+
+English | [中文](quickstart.zh.md)
+
+This guide gets an agent running in five minutes.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) ^22.19 or >= 24
+- [pnpm](https://pnpm.io/) 11 (use Corepack to select the repository-pinned version)
+
+```sh
+# Check versions
+node -v   # v22.19.x, or v24.x and newer
+corepack enable
+pnpm -v   # 11.x
+```
+
+## Step 1: run echo-agent
+
+echo-agent needs no API key and runs after dependencies are installed.
+
+```sh
+# Clone the repository
+git clone https://github.com/deepseek-harness/deepseek-harness.git
+cd deepseek-harness
+
+# Install dependencies
+pnpm install
+
+# Start echo-agent
+pnpm run demo:echo
+```
+
+The process prints:
+
+```
+echo-agent ready. Type a message ("echo <text>" triggers the tool).
+>
+```
+
+Enter:
+
+```
+> echo hello world
+```
+
+The model issues a tool call, and the echo tool returns the text in uppercase:
+
+```
+[tool call] echo({"text":"hello world"})
+[tool result] ECHO: HELLO WORLD
+```
+
+Your local environment is ready.
+
+## Step 2: use a real model
+
+Next, connect a real DeepSeek model and run the complete command-line agent.
+
+### Get an API key
+
+Get an API key from [DeepSeek Platform](https://platform.deepseek.com/).
+
+### Configure the environment
+
+Create a gitignored `.env` file in the repository root:
+
+```sh
+DEEPSEEK_API_KEY=sk-your-key-here
+```
+
+### Start coding-agent
+
+```sh
+pnpm run demo:repl
+```
+
+```
+agent REPL ready. Give it a coding task.
+>
+```
+
+This is a complete coding assistant that can read and write files, run commands, and delegate subtasks.
+
+Try a task:
+
+```
+> Create hello.js in the current directory, print "Hello from Harness!", and run it
+```
+
+## What happened
+
+echo-agent and coding-agent use the same application framework (`@deepseek-ai/dsh-stdio-agent`). Their `cordis.yml` files select different plugins and configuration. Custom agents use the same composition model.
+
+## Next steps
+
+- [Configuration](./config.md) — understand the `cordis.yml` format
+- [Develop a plugin](../develop/basic/) — build your own tool or backend
--- a/docs/user/guide/quickstart.zh.md
+++ b/docs/user/guide/quickstart.zh.md
@@ -0,0 +1,99 @@
+# 快速开始
+
+[English](quickstart.md) | 中文
+
+本指南带你在 5 分钟内跑起一个 Agent。
+
+## 环境准备
+
+- [Node.js](https://nodejs.org/) ^22.19 或 >= 24
+- [pnpm](https://pnpm.io/) 11（建议通过 Corepack 使用仓库固定的版本）
+
+```sh
+# Check versions
+node -v   # v22.19.x, or v24.x and newer
+corepack enable
+pnpm -v   # 11.x
+```
+
+## 第一步：运行 echo-agent
+
+echo-agent 不需要 API key，装好依赖就能跑。
+
+```sh
+# Clone the repository
+git clone https://github.com/deepseek-harness/deepseek-harness.git
+cd deepseek-harness
+
+# Install dependencies
+pnpm install
+
+# Start echo-agent
+pnpm run demo:echo
+```
+
+启动后你会看到：
+
+```
+echo-agent ready. Type a message ("echo <text>" triggers the tool).
+>
+```
+
+试着输入：
+
+```
+> echo hello world
+```
+
+你会看到模型发起了一次 tool call（工具调用），echo 工具将文本转为大写并返回：
+
+```
+[tool call] echo({"text":"hello world"})
+[tool result] ECHO: HELLO WORLD
+```
+
+恭喜！环境没问题。
+
+## 第二步：使用真实模型调用
+
+接下来接入真实的 DeepSeek 模型，跑一个完整的命令行 Agent。
+
+### 获取 API Key
+
+前往 [DeepSeek Platform](https://platform.deepseek.com/) 获取你的 API key。
+
+### 配置环境变量
+
+在仓库根目录创建 `.env` 文件（已被 gitignore）：
+
+```sh
+DEEPSEEK_API_KEY=sk-your-key-here
+```
+
+### 启动 coding-agent
+
+```sh
+pnpm run demo:repl
+```
+
+```
+agent REPL ready. Give it a coding task.
+>
+```
+
+这就是一个完整的编程助手，它能读写文件、跑命令、拆分子任务。
+
+试着给它一个任务：
+
+```
+> Create hello.js in the current directory, print "Hello from Harness!", and run it
+```
+
+## 回头看
+
+echo-agent 和 coding-agent 用的是同一个应用框架(`@deepseek-ai/dsh-stdio-agent`)，区别只在 `cordis.yml`——换了哪些插件、填了什么配置。你以后定制自己的 Agent 也是同样的方式。
+
+## 下一步
+
+- [配置文件](./config.md) — 了解 `cordis.yml` 的完整语法
+- [开发插件](../develop/basic/) — 编写你自己的 tool 或后端