dsh-plugin-guide 0.3.42 → 0.4.0

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

@@ -1,148 +0,0 @@
-# Services and dependencies
-
-English | [中文](service.zh.md)
-
-A service is a capability one plugin exposes to other plugins. `inject` declares the services a plugin requires.
-
-## What is a service?
-
-In Harness, `tools`, `llm`, and `agents` are services. Each is a named capability mounted on `ctx`:
-
-```ts ignore-check
-ctx.tools    // ToolRuntime service
-ctx.llm      // LLM service
-ctx.agents   // Agent service
-```
-
-Any plugin can provide a service for other plugins to consume.
-
-## Consume a service
-
-Declare `inject` to use an existing service:
-
-```ts ignore-check
-export const inject = ['tools']
-
-export function apply(ctx: Context) {
-  // ctx.tools exists and is ready here.
-  ctx.tools.register(/* ... */)
-}
-```
-
-When `apply` runs, every service declared by `inject` is ready. If a service is not ready, the plugin waits instead of running.
-
-## Provide a service
-
-### Extend 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) {
-    // ...
-  }
-}
-```
-
-After loading this plugin, consumers access the service as `ctx.metrics`:
-
-```ts ignore-check
-export const inject = ['metrics']
-
-export function apply(ctx: Context) {
-  ctx.metrics.record('tool_call', 1)
-}
-```
-
-### Declare its type
-
-Use TypeScript declaration merging to type `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) { /* ... */ }
-}
-```
-
-## Dependency behavior
-
-### Required and optional dependencies
-
-```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)
-}
-```
-
-### When a service disappears
-
-If a required service disappears while the application is running, for example because its provider unloads:
-
-1. Dependent plugins dispose automatically.
-2. They load again when the service returns.
-
-This prevents a plugin from calling a service that no longer exists.
-
-## Service isolation
-
-`cordis.yml` can isolate services so separate plugin groups see separate instances of the same service:
-
-```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` and `plugin-b` each see the Bash instance in their own group, with no cross-group effect.
-
-## Built-in Harness services
-
-The repository generates the service names, public methods, and source locations into each service's [subsystem page](../../../subsystems/core.md). Use those generated regions and the service's TypeScript interface while developing a plugin; do not maintain a second static list.
-
-## Next steps
-
-- [Event system](./events.md) — communicate between plugins without tight coupling
-- [Capability layering](../practice/index.md) — use services as capability interfaces

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

@@ -1,150 +0,0 @@
-# 服务与依赖
-
-[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.zh.md)。开发插件时应以这些生成区块和服务的 TypeScript 接口为准，不要维护另一份静态清单。
-
-## 下一步
-
-- [事件系统](./events.zh.md) — 插件间松耦合通信
-- [能力分层](../practice/index.zh.md) — 将服务用作能力接口

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.i18n.yaml

@@ -1,10 +0,0 @@
-# Bilingual-pair consistency record for dynamic-cordis.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/develop/practice/dynamic-cordis.md
-/configure-persistent-plugins-from-a-prompt:
-  en: 9503745724cbe962
-  zh: 985513234a4eda31
-/configure-persistent-plugins-from-a-prompt/connect-an-mcp-server:
-  en: f9fefda94ba8a005
-  zh: f1a9a977a0732fc0

package/references/official-docs/docs/user/develop/practice/dynamic-cordis.md

@@ -1,15 +0,0 @@
-# Configure persistent plugins from a prompt
-
-English | [中文](dynamic-cordis.zh.md)
-
-Creator mode provides [Plugin Manager](../../../../packages/boot/plugin-manager/README.md) and read-only [runtime inspection](../../../../packages/extensions/tool-cordis/README.md). Plugin configuration belongs to the current profile, affects its sessions, and survives process restarts.
-
-## Connect an MCP server
-
-Start the Web profile and select Creator mode. With a reachable Streamable HTTP MCP server that exposes `ping`, send this prompt using its actual endpoint:
-
-> Configure the MCP server at `<endpoint>` in this profile as `demo`. Make its tools available now, then call its ping tool and tell me the result.
-
-The agent writes a configuration-only bundle whose patch inserts `@deepseek-ai/dsh-mcp-client`, then installs it with `plugin_manager install_bundle`. With HMR enabled, the tools appear in the same running session. Verify both the management result (`application: applied`) and a successful `mcp__demo__ping` call. A saved entry with `restart-required` has not activated yet; a failed entry needs configuration repair.
-
-Read the bundle patch before editing its configuration. Use Plugin Manager to disable entries or remove the bundle. See the [MCP client reference](../../../../packages/mcp/mcp-client/README.md) for accepted configuration and connection failure behavior.

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

@@ -1,15 +0,0 @@
-# 通过提示词配置持久化插件
-
-[English](dynamic-cordis.md) | 中文
-
-创造模式提供 [Plugin Manager](../../../../packages/boot/plugin-manager/README.zh.md) 和只读[运行时检查](../../../../packages/extensions/tool-cordis/README.zh.md)。插件配置属于当前 profile，影响其会话，并在进程重启后保留。
-
-## 连接 MCP 服务器
-
-启动 Web profile 并选择创造模式。准备一个可访问且提供 `ping` 的 Streamable HTTP MCP 服务器，将其实际端点填入以下提示词：
-
-> 将 `<endpoint>` 处的 MCP 服务器配置到当前 profile，命名为 `demo`。立即启用它的工具，然后调用它的 ping 工具并告诉我结果。
-
-agent 编写纯配置组合包，在 patch 中插入 `@deepseek-ai/dsh-mcp-client`，再通过 `plugin_manager install_bundle` 安装。启用 HMR 时，工具会出现在同一个运行中的会话里。同时检查管理结果（`application: applied`）和成功的 `mcp__demo__ping` 调用。返回 `restart-required` 的已保存条目尚未激活；失败条目需要修复配置。
-
-修改配置前先读取组合包 patch。使用 Plugin Manager 停用条目或移除组合包。可接受的配置及连接失败行为见 [MCP client 参考](../../../../packages/mcp/mcp-client/README.zh.md)。

package/references/official-docs/docs/user/develop/practice/index.i18n.yaml

@@ -1,46 +0,0 @@
-# Bilingual-pair consistency record for index.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/develop/practice/index.md
-/three-role-capability-design:
-  en: 16d18db6160c9f61
-  zh: 823ea7e889390fab
-/three-role-capability-design/concept-reference:
-  en: 4e60abf663a9748f
-  zh: 3c80c65e519a51dd
-/three-role-capability-design/bash-example:
-  en: 548526d726675a23
-  zh: 51f065f8b23ea6f9
-/three-role-capability-design/benefits-of-the-split:
-  en: 026507583f272d46
-  zh: db37713da87a0e0e
-/three-role-capability-design/benefits-of-the-split/replace-providers:
-  en: 8f74a0bba164ce14
-  zh: e1869cf9b4dd284c
-/three-role-capability-design/benefits-of-the-split/evolve-independently:
-  en: bdf8329fe9d51537
-  zh: 416b7d81d8d30881
-/three-role-capability-design/benefits-of-the-split/decouple-dependencies:
-  en: 068feeea47c2ab74
-  zh: b53112b27f3bf82f
-/three-role-capability-design/tutorial-develop-a-three-role-capability:
-  en: 7bd3c99c2cdb06ad
-  zh: 264d321e9fa35dd8
-/three-role-capability-design/tutorial-develop-a-three-role-capability/step-1-write-the-service-definition:
-  en: 3940ce7faa9e33d6
-  zh: 71e5450d4f57e43a
-/three-role-capability-design/tutorial-develop-a-three-role-capability/step-2-write-a-service-provider:
-  en: 187b9fd73900f8ea
-  zh: 19d29d3fd9cea71a
-/three-role-capability-design/tutorial-develop-a-three-role-capability/step-3-write-a-consumer:
-  en: 604c3c3483a0db87
-  zh: 3069257db64d921c
-/three-role-capability-design/tutorial-develop-a-three-role-capability/compose-them-in-cordis-yml:
-  en: 7b5eae32911c61d3
-  zh: 8a7a03df8294a8c9
-/three-role-capability-design/design-points:
-  en: 5822e06c2cfce8e1
-  zh: aed13f901bb8891e
-/three-role-capability-design/next-steps:
-  en: 27b5fd93b6ab9e75
-  zh: 598c47f40a4ac25b

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

@@ -1,155 +0,0 @@
-# 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/index.md) 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

@@ -1,155 +0,0 @@
-# 能力的三种角色设计
-
-[English](index.md) | 中文
-
-本文分为两部分：先参考三种角色能力模式的概念，再通过高级教程构建一项能力。请先完成[基础插件路径](../basic/index.zh.md)和[服务教程](../framework/service.zh.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.zh.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.zh.md)：实现一个 LLM 提供方