feat(docs): build maintainable documentation site
This commit is contained in:
Yichen Jiang
@@ -0,0 +1,57 @@
|
||||
# 配置文件
|
||||
|
||||
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)中最接近的例子。
|
||||
@@ -0,0 +1,47 @@
|
||||
# 介绍
|
||||
|
||||
DeepSeek Harness 是一个**插件化的 Agent 开发框架**，基于 [Cordis](https://github.com/cordiverse/cordis) 微内核构建。它的核心理念是：**一切皆插件**。
|
||||
|
||||
## 它是什么
|
||||
|
||||
Harness 将一个 AI Agent（智能体） 所需要的所有能力——LLM 调用、工具执行、会话管理、子任务分配——全部构建为可组合的插件。你通过一个 `cordis.yml` 配置文件来声明加载哪些插件、使用什么参数，就能组装出一个完整的 Agent。
|
||||
|
||||
```yaml
|
||||
# 选择 LLM 后端
|
||||
- name: '@deepseek-ai/dsh-llm-deepseek'
|
||||
config:
|
||||
apiKey: !!js process.env.DEEPSEEK_API_KEY
|
||||
|
||||
# 选择应用模板
|
||||
- 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）
|
||||
@@ -0,0 +1,97 @@
|
||||
# 快速开始
|
||||
|
||||
本指南带你在 5 分钟内跑起一个 Agent。
|
||||
|
||||
## 环境准备
|
||||
|
||||
- [Node.js](https://nodejs.org/) ^22.19 或 >= 24
|
||||
- [pnpm](https://pnpm.io/) 11（建议通过 Corepack 使用仓库固定的版本）
|
||||
|
||||
```sh
|
||||
# 确认版本
|
||||
node -v # v22.19.x，或 v24.x 及更高版本
|
||||
corepack enable
|
||||
pnpm -v # 11.x
|
||||
```
|
||||
|
||||
## 第一步：运行 echo-agent
|
||||
|
||||
echo-agent 不需要 API key，装好依赖就能跑。
|
||||
|
||||
```sh
|
||||
# 克隆仓库
|
||||
git clone https://github.com/deepseek-harness/deepseek-harness.git
|
||||
cd deepseek-harness
|
||||
|
||||
# 安装依赖
|
||||
pnpm install
|
||||
|
||||
# 启动 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.
|
||||
>
|
||||
```
|
||||
|
||||
这就是一个完整的编程助手，它能读写文件、跑命令、拆分子任务。
|
||||
|
||||
试着给它一个任务：
|
||||
|
||||
```
|
||||
> 在当前目录创建一个 hello.js，内容是打印 "Hello from Harness!"，然后运行它
|
||||
```
|
||||
|
||||
## 回头看
|
||||
|
||||
echo-agent 和 coding-agent 用的是同一个应用框架(`@deepseek-ai/dsh-stdio-agent`)，区别只在 `cordis.yml`——换了哪些插件、填了什么配置。你以后定制自己的 Agent 也是同样的方式。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [配置文件](./config.md) — 了解 `cordis.yml` 的完整语法
|
||||
- [开发插件](../develop/basic/) — 编写你自己的 tool 或后端
|
||||
Reference in New Issue
Block a user