mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
163 lines
4.8 KiB
Markdown
163 lines
4.8 KiB
Markdown
# 能力的三层拆分
|
||
|
||
[English](index.md) | 中文
|
||
|
||
当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。
|
||
|
||
## 以 Bash 为例
|
||
|
||
以 Bash 执行能力为例：
|
||
|
||
- **接口** (`dsh-bash`)：定义 Bash 请求和结果的结构
|
||
- **实现** (`dsh-bash-local`)：在本地计算机上执行命令
|
||
- **消费方** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
|
||
|
||
```
|
||
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||
│ dsh-bash │────▶│ dsh-bash-local │ │ dsh-tool-bash│
|
||
│ (interface) │ │ (implementation) │ │(consumer/tool)│
|
||
└─────────────┘ └──────────────────┘ └──────────────┘
|
||
▲ │
|
||
└────────────────────────────────────────────┘
|
||
inject: ['bash']
|
||
```
|
||
|
||
## 拆分的好处
|
||
|
||
### 具体实现可替换
|
||
|
||
同一个接口可以有多种实现。用户通过 `cordis.yml` 选择：
|
||
|
||
```yaml
|
||
# Local execution
|
||
- name: '@deepseek-ai/dsh-bash-local'
|
||
|
||
# Or a future remote sandbox implementation
|
||
# - name: '@deepseek-ai/dsh-bash-remote'
|
||
# config:
|
||
# endpoint: 'https://sandbox.example.com'
|
||
```
|
||
|
||
更换实现时，接口和工具均保持不变。
|
||
|
||
### 独立演进
|
||
|
||
- 接口定义稳定后很少改动
|
||
- 实现可以独立优化（性能、安全）
|
||
- 消费方可以调整能力向模型呈现的方式。
|
||
|
||
### 依赖解耦
|
||
|
||
- 实现依赖接口。
|
||
- 消费方依赖接口。
|
||
- 实现和消费方**互不依赖**。
|
||
|
||
## Harness 中内置的三件套
|
||
|
||
| 能力 | 接口（seam） | 实现 | 消费方（工具） |
|
||
|------|-------------|------|---------------|
|
||
| Bash | `dsh-bash` | `dsh-bash-local` | `dsh-tool-bash` |
|
||
| 文件系统 | `dsh-fs` | `dsh-fs-local` + `dsh-fs-policy` | `dsh-tool-fs` |
|
||
| Web | `dsh-web` | `dsh-web-fetch-local` / `dsh-web-search-*` | `dsh-tool-web` |
|
||
| 子代理 | `dsh-subagent` | `dsh-subagent-spawn` / `dsh-subagent-fork` | `dsh-tool-subagent` |
|
||
| 压缩 | `dsh-compact` | `dsh-compact-basic` | 由实现插件消费 agent-loop 的扩展事件 |
|
||
|
||
## 开发你自己的三件套
|
||
|
||
### 第一步：定义接口
|
||
|
||
```ts ignore-check
|
||
// packages/my-cap/my-cap/src/index.ts
|
||
import { Service, type Context } from 'cordis'
|
||
|
||
declare module 'cordis' {
|
||
interface Context {
|
||
myCap: MyCapService
|
||
}
|
||
}
|
||
|
||
export abstract class MyCapService extends Service {
|
||
constructor(ctx: Context) {
|
||
super(ctx, 'myCap')
|
||
}
|
||
|
||
/** Execute the capability. */
|
||
abstract execute(request: MyCapRequest): Promise<MyCapResult>
|
||
}
|
||
|
||
export interface MyCapRequest {
|
||
input: string
|
||
}
|
||
|
||
export interface MyCapResult {
|
||
output: string
|
||
}
|
||
```
|
||
|
||
### 第二步：编写实现
|
||
|
||
```ts ignore-check
|
||
// packages/my-cap/my-cap-local/src/index.ts
|
||
import type { Context } from 'cordis'
|
||
import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
|
||
|
||
class MyCapLocal extends MyCapService {
|
||
async execute(request: MyCapRequest): Promise<MyCapResult> {
|
||
// Concrete implementation.
|
||
return { output: request.input.toUpperCase() }
|
||
}
|
||
}
|
||
|
||
export const name = 'my-cap-local'
|
||
|
||
export function apply(ctx: Context) {
|
||
ctx.plugin(MyCapLocal)
|
||
}
|
||
```
|
||
|
||
### 第三步：编写消费方
|
||
|
||
```ts ignore-check
|
||
// packages/my-cap/tool-my-cap/src/index.ts
|
||
import type { Context } from 'cordis'
|
||
import { defineTool } from '@deepseek-ai/dsh-tools'
|
||
|
||
export const name = 'tool-my-cap'
|
||
export const inject = ['tools', 'myCap']
|
||
|
||
export function apply(ctx: Context) {
|
||
ctx.tools.register(defineTool({
|
||
name: 'my_cap',
|
||
description: 'Execute my capability.',
|
||
parameters: {
|
||
input: { type: 'string', required: true },
|
||
},
|
||
output: {
|
||
schema: { type: 'string' },
|
||
render: (_args, value) => [{ type: 'text', text: value }],
|
||
},
|
||
async execute(args) {
|
||
const result = await ctx.myCap.execute({ input: args.input })
|
||
return result.output
|
||
},
|
||
}))
|
||
}
|
||
```
|
||
|
||
### 在 cordis.yml 中组合
|
||
|
||
```yaml
|
||
- name: '@deepseek-ai/dsh-my-cap-local'
|
||
- name: '@deepseek-ai/dsh-tool-my-cap'
|
||
```
|
||
|
||
## 设计要点
|
||
|
||
- **不要预防性拆分**：只有确实需要可替换实现时，才拆分为三个包。简单的工具插件无需拆分。
|
||
- **接口拥有 Request/Result 类型**：实现和消费方只依赖接口包。
|
||
- **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
|
||
|
||
## 下一步
|
||
|
||
- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 后端，这是一种常见的能力 seam 扩展
|