0 Fork 0

Files

T

lintianle 6ce9f16030 website: wire the site into the repo gates; make every tutorial example compile

- website joins the pnpm workspace; root scripts website:dev/website:build;
  run-gates gains a website-build gate (ci-primary + ci-static) — the
  VitePress build doubles as the site's dead-link check; AGENTS.md documents
  the commands.
- doc-typecheck + verify-type-equiv now scan website/zh-CN/**/*.md; every
  ```typescript fence converted to ```ts and made standalone-compilable
  (55 compiled, 1 ignore-check). Phantom APIs the compiler caught are fixed:
  invented event names (agent/turn-end, tool/call, llm/pre-request, ready,
  dispose) replaced with real catalog events or per-plugin declare-module
  merges; presentCall/inject/Config claims corrected to the real shapes.
- guide/config.md entry-fields table completed against loader EntryOptions;
  its coding-agent example brought in line with examples/coding-agent.

2026-07-16 18:12:22 +08:00

3.6 KiB

Raw Blame History

第一个插件

本文带你编写一个最小的 Harness 插件并加载到 Agent 中。

插件是什么

在 Harness 中，插件是一个导出 apply 函数的 TypeScript 模块。框架在加载时调用 apply，传入一个 ctx（上下文对象），你通过 ctx 注册能力：

import type { Context } from 'cordis'

export const name = 'my-plugin'

export function apply(ctx: Context) {
  // 在这里注册能力
}

就这么简单。

创建插件文件

在你的项目目录下创建 src/my-plugin.ts：

import type { Context } from 'cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // apply 函数体在插件加载时执行
  console.log('[hello-plugin] 插件已加载!')
}

注册到 cordis.yml

在你的 cordis.yml 中添加一条：

- id: hello
  name: './src/my-plugin.ts'

启动后你会在控制台看到 [hello-plugin] 插件已加载!。

自动清理

通过 ctx 注册的任何东西——事件监听、tool、定时器——在插件卸载时都会被自动清理。你不需要手动 removeListener 或 clearInterval。

如果你有需要手动清理的资源（比如一个网络连接），用 ctx.effect() 告诉框架怎么清理：

import type { Context } from 'cordis'

export function apply(ctx: Context) {
  ctx.effect(() => {
    const timer = setInterval(() => {
      console.log('heartbeat')
    }, 5000)

    // 返回的函数会在插件卸载时被调用
    return () => clearInterval(timer)
  })
}

声明依赖

如果你的插件需要使用其他服务（如 tools、llm），需要声明 inject：

import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool-plugin'
export const inject = ['tools']

export function apply(ctx: Context) {
  // ctx.tools 现在可用
  ctx.tools.register(defineTool({
    name: 'demo',
    description: 'Demo tool.',
    parameters: {},
    async execute() {
      return []
    },
  }))
}

框架会确保依赖的服务就绪后才加载你的插件。

插件的三种形态

除了函数形式，插件还支持对象形式和类形式：

对象形式

import type { Context } from 'cordis'
import type {} from '@deepseek-ai/dsh-tools'

export default {
  name: 'my-plugin',
  inject: ['tools'],
  apply(ctx: Context) {
    // ...
  },
}

类形式

import { Service, type Context } from 'cordis'
import type {} from '@deepseek-ai/dsh-tools'

export default class MyService extends Service {
  static inject = ['tools']

  constructor(ctx: Context) {
    super(ctx, 'myService')
  }

  // 服务的公开方法
  greet(name: string) {
    return `Hello, ${name}!`
  }
}

大多数情况下，函数形式足够了。类形式用于需要对外提供服务的插件（见服务与依赖）。

完整示例

参考仓库中的 examples/echo-agent/src/echo-tool.ts，这是一个注册 tool 的插件：

import type { Context } from 'cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'echo-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'echo',
    description: 'Echo the given text back, uppercased.',
    parameters: {
      text: { type: 'string', required: true },
    },
    async execute(args) {
      return [{ type: 'text', text: `ECHO: ${args.text.toUpperCase()}` }]
    },
  }))
}

下一步

开发一个 Tool — 详细了解 tool 定义 DSL
插件配置 — 让插件接受用户配置

3.6 KiB Raw Blame History Unescape Escape