mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
docs: reserve seam for complete capabilities
This commit is contained in:
Turtle
@@ -2,5 +2,5 @@
|
||||
# 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 docs/user/develop/practice/index.md
|
||||
index.md: c3306725f47993aa9d3322423261a260754c1d5f
|
||||
index.zh.md: 3609cbce21e17ce9ca0a40b69999b293dee29012
|
||||
index.md: 6ae9fd152ca2e3b82bdb1ea9b3aa3d348ebfce66
|
||||
index.zh.md: 0056a81402761310fe5f0463b83762d98ed9745f
|
||||
|
||||
@@ -1,25 +1,25 @@
|
||||
# Three-layer capability design
|
||||
# Three-role capability design
|
||||
|
||||
English | [中文](index.zh.md)
|
||||
|
||||
This page has two parts: a concept reference for the three-layer capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
|
||||
This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first.
|
||||
|
||||
## Concept reference
|
||||
|
||||
When a capability is general enough to need replaceable implementations, such as Bash execution, Harness splits it into three packages: an **interface**, an **implementation**, and a **consumer**. Each layer can evolve or be replaced independently.
|
||||
When a capability is general enough to need replaceable providers, such as Bash execution, Harness separates three roles: a **Service Definition**, a **Service provider**, and a **Consumer**. Put the roles in separate packages when they need to evolve or be replaced independently; a package may otherwise own more than one role. The complete capability is its seam. No individual role is a seam.
|
||||
|
||||
## Bash example
|
||||
|
||||
The Bash execution capability consists of:
|
||||
|
||||
- **Interface** (`dsh-bash`) — defines Bash request and result shapes
|
||||
- **Implementation** (`dsh-bash-local`) — executes commands on the local machine
|
||||
- **Service Definition** (`dsh-bash`) — defines the Cordis service and Bash request/result vocabulary
|
||||
- **Service provider** (`dsh-bash-local`) — supplies local command execution
|
||||
- **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ dsh-bash │────▶│ dsh-bash-local │ │ dsh-tool-bash│
|
||||
│ (interface) │ │ (implementation) │ │(consumer/tool)│
|
||||
│(definition) │ │ (provider) │ │(consumer/tool)│
|
||||
└─────────────┘ └──────────────────┘ └──────────────┘
|
||||
▲ │
|
||||
└────────────────────────────────────────────┘
|
||||
@@ -28,36 +28,36 @@ The Bash execution capability consists of:
|
||||
|
||||
## Benefits of the split
|
||||
|
||||
### Replace implementations
|
||||
### Replace providers
|
||||
|
||||
One interface can have multiple implementations selected through `cordis.yml`:
|
||||
One Service Definition can have multiple providers selected through `cordis.yml`:
|
||||
|
||||
```yaml
|
||||
# Local execution
|
||||
- name: '@deepseek-ai/dsh-bash-local'
|
||||
|
||||
# Replace this row with another package that implements the same service.
|
||||
# Replace this row with another package that provides the same service.
|
||||
```
|
||||
|
||||
The interface and tool remain unchanged while the implementation changes.
|
||||
The Service Definition and tool remain unchanged while the provider changes.
|
||||
|
||||
### Evolve independently
|
||||
|
||||
- The interface changes rarely after its contract stabilizes.
|
||||
- Implementations can improve performance and security independently.
|
||||
- The Service Definition changes rarely after its contract stabilizes.
|
||||
- Service providers can improve performance and security independently.
|
||||
- Consumers can change how they present the capability to the model.
|
||||
|
||||
### Decouple dependencies
|
||||
|
||||
- The implementation depends on the interface.
|
||||
- The consumer depends on the interface.
|
||||
- The implementation and consumer **do not depend on each other**.
|
||||
- The Service provider depends on the Service Definition.
|
||||
- The Consumer depends on the Service Definition.
|
||||
- The Service provider and Consumer **do not depend on each other**.
|
||||
|
||||
The [capability-seam reference](../../../capability-seams.md) owns the current built-in families and package links.
|
||||
|
||||
## Tutorial: develop a three-layer capability
|
||||
## Tutorial: develop a three-role capability
|
||||
|
||||
### Step 1: define the interface
|
||||
### Step 1: write the Service Definition
|
||||
|
||||
```ts ignore-check
|
||||
// packages/my-cap/my-cap/src/index.ts
|
||||
@@ -87,7 +87,7 @@ export interface MyCapResult {
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: write an implementation
|
||||
### Step 2: write a Service provider
|
||||
|
||||
```ts ignore-check
|
||||
// packages/my-cap/my-cap-local/src/index.ts
|
||||
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
|
||||
|
||||
class MyCapLocal extends MyCapService {
|
||||
async execute(request: MyCapRequest): Promise<MyCapResult> {
|
||||
// Concrete implementation.
|
||||
// Local provider behavior.
|
||||
return { output: request.input.toUpperCase() }
|
||||
}
|
||||
}
|
||||
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
|
||||
|
||||
## Design points
|
||||
|
||||
- **Do not split preemptively** — use three packages only when the capability needs replaceable implementations. A simple tool plugin does not.
|
||||
- **The interface owns Request/Result types** — implementations and consumers depend only on the interface package.
|
||||
- **Do not split preemptively** — use separate packages only when the roles need to evolve independently. A simple tool plugin does not.
|
||||
- **The Service Definition owns Request/Result types** — Service providers and Consumers depend only on the Service Definition package.
|
||||
- **Explicit > implicit** — resolve defaults in an explicit `resolve(request): Spec` step rather than hiding `?? default` expressions inside `run()`.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [LLM adapter](./llm-adapter.md) — implement an LLM backend, a common capability interface extension
|
||||
- [LLM adapter](./llm-adapter.md) — implement an LLM provider
|
||||
|
||||
@@ -1,25 +1,25 @@
|
||||
# 能力的三层拆分
|
||||
# 能力的三种角色设计
|
||||
|
||||
[English](index.md) | 中文
|
||||
|
||||
本文分为两部分：先参考三层能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
|
||||
本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
|
||||
|
||||
## 概念参考
|
||||
|
||||
当一项能力足够通用，需要支持可替换的实现时（例如 Bash 执行），Harness 会将其拆成三个包：**接口**、**实现**和**消费方**。这样便可独立替换其中任何一层。
|
||||
当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），Harness 会区分三种角色：**Service Definition**、**Service provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
|
||||
|
||||
## 以 Bash 为例
|
||||
|
||||
以 Bash 执行能力为例：
|
||||
|
||||
- **接口** (`dsh-bash`)：定义 Bash 请求和结果的结构
|
||||
- **实现** (`dsh-bash-local`)：在本地计算机上执行命令
|
||||
- **消费方** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
|
||||
- **Service Definition** (`dsh-bash`)：定义 Cordis 服务以及 Bash 请求／结果词汇
|
||||
- **Service provider** (`dsh-bash-local`)：提供本地命令执行
|
||||
- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ dsh-bash │────▶│ dsh-bash-local │ │ dsh-tool-bash│
|
||||
│ (interface) │ │ (implementation) │ │(consumer/tool)│
|
||||
│(definition) │ │ (provider) │ │(consumer/tool)│
|
||||
└─────────────┘ └──────────────────┘ └──────────────┘
|
||||
▲ │
|
||||
└────────────────────────────────────────────┘
|
||||
@@ -28,36 +28,36 @@
|
||||
|
||||
## 拆分的好处
|
||||
|
||||
### 具体实现可替换
|
||||
### 提供方可替换
|
||||
|
||||
同一个接口可以有多种实现。用户通过 `cordis.yml` 选择：
|
||||
同一个 Service Definition 可以有多个提供方。用户通过 `cordis.yml` 选择：
|
||||
|
||||
```yaml
|
||||
# Local execution
|
||||
- name: '@deepseek-ai/dsh-bash-local'
|
||||
|
||||
# Replace this row with another package that implements the same service.
|
||||
# Replace this row with another package that provides the same service.
|
||||
```
|
||||
|
||||
更换实现时，接口和工具均保持不变。
|
||||
更换提供方时，Service Definition 和工具均保持不变。
|
||||
|
||||
### 独立演进
|
||||
|
||||
- 接口定义稳定后很少改动
|
||||
- 实现可以独立优化（性能、安全）
|
||||
- 消费方可以调整能力向模型呈现的方式。
|
||||
- Service Definition 的约定稳定后很少改动
|
||||
- Service provider 可以独立优化性能和安全性
|
||||
- Consumer 可以调整能力向模型呈现的方式。
|
||||
|
||||
### 依赖解耦
|
||||
|
||||
- 实现依赖接口。
|
||||
- 消费方依赖接口。
|
||||
- 实现和消费方**互不依赖**。
|
||||
- Service provider 依赖 Service Definition。
|
||||
- Consumer 依赖 Service Definition。
|
||||
- Service provider 和 Consumer **互不依赖**。
|
||||
|
||||
当前内置系列及其包链接由[能力 seam 参考](../../../capability-seams.md)负责。
|
||||
|
||||
## 教程：开发三层能力
|
||||
## 教程：开发三种角色的能力
|
||||
|
||||
### 第一步：定义接口
|
||||
### 第一步：编写 Service Definition
|
||||
|
||||
```ts ignore-check
|
||||
// packages/my-cap/my-cap/src/index.ts
|
||||
@@ -87,7 +87,7 @@ export interface MyCapResult {
|
||||
}
|
||||
```
|
||||
|
||||
### 第二步：编写实现
|
||||
### 第二步：编写 Service provider
|
||||
|
||||
```ts ignore-check
|
||||
// packages/my-cap/my-cap-local/src/index.ts
|
||||
@@ -96,7 +96,7 @@ import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/
|
||||
|
||||
class MyCapLocal extends MyCapService {
|
||||
async execute(request: MyCapRequest): Promise<MyCapResult> {
|
||||
// Concrete implementation.
|
||||
// Local provider behavior.
|
||||
return { output: request.input.toUpperCase() }
|
||||
}
|
||||
}
|
||||
@@ -146,10 +146,10 @@ export function apply(ctx: Context) {
|
||||
|
||||
## 设计要点
|
||||
|
||||
- **不要预防性拆分**：只有确实需要可替换实现时，才拆分为三个包。简单的工具插件无需拆分。
|
||||
- **接口拥有 Request/Result 类型**：实现和消费方只依赖接口包。
|
||||
- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
|
||||
- **Service Definition 拥有 Request/Result 类型**：Service provider 和 Consumer 只依赖 Service Definition 包。
|
||||
- **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 后端，这是一种常见的能力 seam 扩展
|
||||
- [LLM 适配器](./llm-adapter.md)：实现一个 LLM 提供方
|
||||
|
||||
Reference in New Issue
Block a user