dsh-plugin-guide 0.1.0

package/references/official-docs/docs/user/develop/framework/service.zh.md

@@ -0,0 +1,150 @@
+# 服务与依赖
+
+[English](service.md) | 中文
+
+服务是一个插件向其他插件公开的能力。inject 声明插件需要哪些服务。
+
+## 什么是服务
+
+在 Harness 中，`tools`、`llm`、`agents` 都是服务。服务是挂载在 `ctx` 上的命名能力：
+
+```ts ignore-check
+ctx.tools    // ToolRuntime service
+ctx.llm      // LLM service
+ctx.agents   // Agent service
+```
+
+任何插件都可以提供服务，供其他插件使用。
+
+## 使用服务
+
+声明 `inject` 来使用已有服务：
+
+```ts ignore-check
+export const inject = ['tools']
+
+export function apply(ctx: Context) {
+  // ctx.tools exists and is ready here.
+  ctx.tools.register(/* ... */)
+}
+```
+
+框架保证：在 `apply` 执行时，`inject` 声明的服务已经全部就绪。如果服务还没准备好，你的插件会等着，不会执行。
+
+## 提供服务
+
+### 使用 Service 基类
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+export default class MetricsService extends Service {
+  static inject = ['llm']  // A service may depend on other services.
+
+  constructor(ctx: Context) {
+    super(ctx, 'metrics')  // 'metrics' is the service name.
+  }
+
+  // Public service method.
+  record(event: string, value: number) {
+    // ...
+  }
+}
+```
+
+加载这个插件后，消费方就可以通过 `ctx.metrics` 访问它：
+
+```ts ignore-check
+export const inject = ['metrics']
+
+export function apply(ctx: Context) {
+  ctx.metrics.record('tool_call', 1)
+}
+```
+
+### 类型声明
+
+使用 TypeScript 声明合并让 `ctx.metrics` 有正确类型：
+
+```ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    metrics: MetricsService
+  }
+}
+
+export default class MetricsService extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'metrics')
+  }
+
+  record(event: string, value: number) { /* ... */ }
+}
+```
+
+## 依赖的行为
+
+### 必需依赖与可选依赖
+
+```ts ignore-check
+// Required: the plugin does not load while the service is absent.
+export const inject = ['tools']
+
+// Optional: omit inject and query with ctx.get() at the use site.
+export function apply(ctx: Context) {
+  const metrics = ctx.get('metrics')
+  metrics?.record('plugin_loaded', 1)
+}
+```
+
+### 服务消失时的行为
+
+如果应用运行期间某项必需服务消失（例如其提供方卸载）：
+
+1. 依赖它的插件会自动 dispose（资源释放）
+2. 当服务重新出现时，插件自动重新加载
+
+这可以防止插件调用已不存在的服务。
+
+<a id="service-isolation"></a>
+
+## 服务隔离
+
+`cordis.yml` 支持服务隔离——同一个服务可以有多个实例，不同插件组看到不同实例：
+
+```yaml
+- id: group-a
+  name: '@deepseek-ai/cordis-plugin-group'
+  group: true
+  isolate:
+    shell: true
+  config:
+    - name: '@deepseek-ai/dsh-bash-local'
+      config:
+        timeoutMs: 5000
+    - name: './src/plugin-a.ts'
+
+- id: group-b
+  name: '@deepseek-ai/cordis-plugin-group'
+  group: true
+  isolate:
+    shell: true
+  config:
+    - name: '@deepseek-ai/dsh-bash-local'
+      config:
+        timeoutMs: 60000
+    - name: './src/plugin-b.ts'
+```
+
+`plugin-a` 和 `plugin-b` 各自看到自己组内的 Bash 实例，互不影响。
+
+## Harness 内置服务
+
+服务名、公开方法和源码位置由仓库自动生成到各服务的[子系统页面](../../../subsystems/core.md)。开发插件时应以这些生成区块和服务的 TypeScript 接口为准，不要维护另一份静态清单。
+
+## 下一步
+
+- [事件系统](./events.md) — 插件间松耦合通信
+- [能力分层](../practice/) — 将服务用作能力接口

package/references/official-docs/docs/user/develop/practice/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 docs/user/develop/practice/index.md
+index.md: cc6bd7a234305f6fa193341f15354b40855f72e9
+index.zh.md: aed13b00f9bc74946aace614953bed30705c8281

package/references/official-docs/docs/user/develop/practice/index.md

@@ -0,0 +1,155 @@
+# Three-role capability design
+
+English | [中文](index.zh.md)
+
+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 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:
+
+- **Service Definition** (`dsh-shell`) — defines the Cordis service and Bash request and result types
+- **Service Provider** (`dsh-bash-local`) — executes commands on the local machine
+- **Consumer** (`dsh-tool-bash`) — exposes the capability as a model-callable tool
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
+│  dsh-shell   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
+└─────────────┘     └──────────────────┘     └──────────────┘
+       ▲                                            │
+       └────────────────────────────────────────────┘
+                    inject: ['shell']
+```
+
+## Benefits of the split
+
+### Replace providers
+
+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 provides the same service.
+```
+
+The Service Definition and tool remain unchanged while the provider changes.
+
+### Evolve independently
+
+- The Service Definition changes rarely after callers depend on its contract.
+- Service Providers can improve performance and security independently.
+- Consumers can change how they present the capability to the model.
+
+### Decouple dependencies
+
+- 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-role capability
+
+### Step 1: write the Service Definition
+
+```ts ignore-check
+// packages/my-cap/my-cap/src/index.ts
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/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
+}
+```
+
+### Step 2: write a Service Provider
+
+```ts ignore-check
+// packages/my-cap/my-cap-local/src/index.ts
+import type { Context } from '@deepseek-ai/cordis'
+import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
+
+class MyCapLocal extends MyCapService {
+  async execute(request: MyCapRequest): Promise<MyCapResult> {
+    // Local provider behavior.
+    return { output: request.input.toUpperCase() }
+  }
+}
+
+export const name = 'my-cap-local'
+
+export function apply(ctx: Context) {
+  ctx.plugin(MyCapLocal)
+}
+```
+
+### Step 3: write a consumer
+
+```ts ignore-check
+// packages/my-cap/tool-my-cap/src/index.ts
+import type { Context } from '@deepseek-ai/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
+    },
+  }))
+}
+```
+
+### Compose them in cordis.yml
+
+```yaml
+- name: '@deepseek-ai/dsh-my-cap-local'
+- name: '@deepseek-ai/dsh-tool-my-cap'
+```
+
+## Design points
+
+- **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 provider

package/references/official-docs/docs/user/develop/practice/index.zh.md

@@ -0,0 +1,155 @@
+# 能力的三种角色设计
+
+[English](index.md) | 中文
+
+本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/)和[服务教程](../framework/service.md)。
+
+## 概念参考
+
+当一项能力足够通用，需要支持可替换的提供方时（例如 Bash 执行），harness 会区分三种角色：**Service Definition**、**Service Provider** 和 **Consumer**。角色需要独立演进或替换时，将它们放入不同包；否则一个包可以承担多个角色。完整能力构成其 seam。任何单一角色都不是 seam。
+
+## 以 Bash 为例
+
+以 Bash 执行能力为例：
+
+- **Service Definition** (`dsh-shell`)：定义 Cordis 服务以及 Bash 请求和结果类型
+- **Service Provider** (`dsh-bash-local`)：在本地计算机上执行命令
+- **Consumer** (`dsh-tool-bash`)：将该能力公开为模型可调用的工具
+
+```
+┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
+│  dsh-shell   │────▶│  dsh-bash-local  │     │ dsh-tool-bash│
+│(definition) │     │    (provider)     │     │(consumer/tool)│
+└─────────────┘     └──────────────────┘     └──────────────┘
+       ▲                                            │
+       └────────────────────────────────────────────┘
+                    inject: ['shell']
+```
+
+## 拆分的好处
+
+### 提供方可替换
+
+同一个 Service Definition 可以有多个提供方，可通过 `cordis.yml` 选择：
+
+```yaml
+# Local execution
+- name: '@deepseek-ai/dsh-bash-local'
+
+# Replace this row with another package that provides the same service.
+```
+
+更换提供方时，Service Definition 和工具均保持不变。
+
+### 独立演进
+
+- 调用方开始依赖 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
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+declare module '@deepseek-ai/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
+}
+```
+
+### 第二步：编写 Service Provider
+
+```ts ignore-check
+// packages/my-cap/my-cap-local/src/index.ts
+import type { Context } from '@deepseek-ai/cordis'
+import { MyCapService, type MyCapRequest, type MyCapResult } from '@deepseek-ai/dsh-my-cap'
+
+class MyCapLocal extends MyCapService {
+  async execute(request: MyCapRequest): Promise<MyCapResult> {
+    // Local provider behavior.
+    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 '@deepseek-ai/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'
+```
+
+## 设计要点
+
+- **不要预防性拆分**：只有角色需要独立演进时，才使用不同包。简单的工具插件无需拆分。
+- **Service Definition 拥有 Request/Result 类型**：Service Provider 和 Consumer 只依赖 Service Definition 包。
+- **显式优于隐式**：实现应通过显式的 `resolve(request): Spec` 步骤处理默认值，而不是在 `run()` 中隐藏 `?? default`。
+
+## 下一步
+
+- [LLM（大语言模型）适配器](./llm-adapter.md)：实现一个 LLM 提供方

package/references/official-docs/docs/user/develop/practice/llm-adapter.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 docs/user/develop/practice/llm-adapter.md
+llm-adapter.md: 882e82d880ac622cf886c6c24e75a1987e1c6702
+llm-adapter.zh.md: 27c480af2a19a68ac35900a2ce1b5e9dbdc85bf8

package/references/official-docs/docs/user/develop/practice/llm-adapter.md

@@ -0,0 +1,188 @@
+# LLM adapters
+
+English | [中文](llm-adapter.zh.md)
+
+This guide connects a new LLM provider to Harness.
+
+## Overview
+
+An LLM adapter extends `LlmAdapter` and implements `stream()`, translating Harness's provider-neutral request into a provider API call and translating the response back into Harness chunks.
+
+## Minimal implementation
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import Schema from '@deepseek-ai/schemastery'
+import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+class MyAdapter extends LlmAdapter {
+  private apiKey: string
+
+  constructor(apiKey: string) {
+    super()
+    this.apiKey = apiKey
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    // 1. Convert options.messages to the provider format.
+    // 2. Call the streaming API.
+    // 3. Convert the response into StreamChunk values.
+  }
+}
+
+export interface Config {
+  apiKey: string
+  providers: string[]
+}
+
+export const Config: Schema<Config> = Schema.object({
+  apiKey: Schema.string().required(),
+  providers: Schema.array(Schema.string()).required(),
+})
+
+export const name = 'my-llm-adapter'
+export const inject = ['llm']
+
+export function apply(ctx: Context, config: Config) {
+  const adapter = new MyAdapter(config.apiKey)
+  ctx.llm.registerAdapter(config.providers, adapter)
+}
+```
+
+## StreamChunk protocol
+
+`stream()` yields chunks using this protocol:
+
+```ts
+import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+async function* exampleChunks(): AsyncIterable<StreamChunk> {
+  // 1. Start each content block with block-start.
+  yield { type: 'block-start', index: 0, blockType: 'text' }
+
+  // 2. Stream text through text-delta.
+  yield { type: 'text-delta', index: 0, text: 'Hello' }
+  yield { type: 'text-delta', index: 0, text: ' world' }
+
+  // 3. End each content block with block-end and the complete block.
+  yield {
+    type: 'block-end',
+    index: 0,
+    block: { type: 'text', text: 'Hello world' },
+  }
+
+  // 4. Tool-call block.
+  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
+  yield {
+    type: 'tool-call-delta',
+    index: 1,
+    id: CallId('call-123'),
+    name: 'bash',
+    argumentsDelta: '{"command":"ls"}',
+  }
+  yield {
+    type: 'block-end',
+    index: 1,
+    block: {
+      type: 'tool-call',
+      id: CallId('call-123'),
+      name: 'bash',
+      arguments: '{"command":"ls"}',
+    },
+  }
+
+  // 5. Token usage.
+  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
+
+  // 6. Finish reason.
+  yield { type: 'finish', reason: { kind: 'stop' } }
+  // Alternatively, { kind: 'tool-calls' } requests tool execution.
+}
+```
+
+### Key rules
+
+- Every `block-start` has a matching `block-end`.
+- `index` increases from 0 and identifies content-block order.
+- A `tool-call-delta` carries raw JSON text in `argumentsDelta`, either all at once or over multiple chunks.
+- `finish` is the final chunk.
+- Emit `usage` before `finish`.
+
+## GenerateOptions
+
+`stream()` receives the exported `GenerateOptions` type. It includes the model, adapter-owned reasoning-effort id, conversation history, system prompt, tool schemas, generation parameters, stop sequences, and abort signal; treat the TypeScript type exported by `@deepseek-ai/dsh-llm` as authoritative. Map supported fields to the provider API. If the provider cannot honor a field, throw `LlmError` with a stable code instead of silently dropping it.
+
+Override `resolveModel(provider, model, signal?)` to return exact provider/model identity plus optional `context` and `reasoning` metadata in one lookup. Reasoning metadata contains ordered opaque ids and display names plus an optional configured default; preserve the adapter's authoritative selectable list, including `off` when its upstream capability API returns it, instead of promoting those values into a core enum. Honor the optional signal for asynchronous lookup so cancellation and disposal reach quiescence. The service validates the aggregate and rejects unsupported explicit efforts before `stream()`; omitting `reasoning` means that model has no selectable reasoning-effort capability.
+
+## Register an adapter
+
+```ts ignore-check
+ctx.llm.registerAdapter(['my-provider'], adapter)
+```
+
+The first argument lists provider routes handled by the adapter. `GenerateOptions.provider` selects the registered adapter, while `GenerateOptions.model` passes an adapter-owned model id without lifecycle registration. Override `listModels()` when the adapter can advertise model choices to selectors.
+
+## Use it from cordis.yml
+
+```yaml
+- id: my-llm
+  name: './src/my-llm-adapter.ts'
+  config:
+    apiKey: !!js process.env.MY_API_KEY
+    providers:
+      - my-provider
+
+- id: agent-loop
+  name: '@deepseek-ai/dsh-agent-loop'
+  config:
+    agents:
+      - id: main
+        provider: my-provider
+        model: my-model-v1
+```
+
+## Reference implementations
+
+The repository contains complete implementations:
+
+- `packages/llm/llm-deepseek/` — DeepSeek API adapter using the OpenAI-compatible format
+- `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format
+
+Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs.
+
+## Error handling
+
+Adapters throw transport and protocol failures as `LlmError` values with stable codes. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
+
+```ts
+import {
+  attributionHeaders,
+  LlmAdapter,
+  LlmError,
+  type GenerateOptions,
+  type StreamChunk,
+} from '@deepseek-ai/dsh-llm'
+
+class HttpAdapter extends LlmAdapter {
+  constructor(private readonly endpoint: string) {
+    super()
+  }
+
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const response = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        ...attributionHeaders(),
+      },
+      body: JSON.stringify({ model: options.model, messages: options.messages }),
+      ...options.signal ? { signal: options.signal } : {},
+    })
+    if (!response.ok) {
+      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
+    }
+    // A real adapter parses the response and emits the complete chunk sequence.
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+```