开发你的第一个 Cordis 插件

00 · 开始之前

开始之前

官方教程假设你已经可以从源码运行 DeepSeek Harness。请在仓库根目录操作，确保命令和 Patch 路径与示例一致。

• 已检出 deepseek-ai/deepseek-harness 源码
• 已使用仓库指定的包管理器安装依赖
• 终端当前位于仓库根目录
• Node.js 与 pnpm 版本符合当前检出版本要求

步骤 1

创建本地插件项目

在 Harness 仓库内创建临时项目。第一个实验保持本地化，加载路径更明确，也更容易完整移除。

mkdir -p scratch-plugin/src

步骤 2

编写插件模块

Harness 插件是导出 apply 函数的 TypeScript 模块。框架使用 Cordis Context 调用 apply，你可以通过这个上下文注册能力。

创建 scratch-plugin/src/my-plugin.ts。示例中的日志将作为插件成功加载的可观察信号。

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // Required dependencies are ready before apply runs.
  console.log('[hello-plugin] plugin loaded!')
}

步骤 3

注册到 cordis.yml

先在仓库根目录执行 pwd，再创建 scratch-plugin/cordis.yml 作为 Web 配置覆盖层。请把示例路径替换为 pwd 输出的绝对路径。

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

步骤 4

使用覆盖层启动 Web UI

在仓库根目录使用 Patch 文件启动 Web UI，然后访问 http://127.0.0.1:3080。

pnpm dsh web --patch ./scratch-plugin/cordis.yml

05 · Cordis

生命周期与服务依赖

Cordis 会把注册内容限定在插件上下文内。在插件持有定时器、连接、工具或共享能力前，应先理解下面两个机制。

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

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

    // Runs automatically when the plugin unloads.
    return () => clearInterval(timer)
  })
}

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

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

export function apply(ctx: Context) {
  // ctx.tools is ready here.
  ctx.tools.register(/* ... */)
}

06 · API

选择最简单的插件形态

Cordis 支持函数、对象和类三种形态。优先使用函数；只有插件需要向其他插件提供服务时，再考虑 Service 类。

对象形式

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

Service 类

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

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

  constructor(ctx: Context) {
    super(ctx, 'myService')
    // Perform synchronous initialization here.
  }
}

07 · Verify

验证清单

进程启动并不等于开发完成，还要检查加载路径、生命周期和移除行为。

• Web UI 可以在 127.0.0.1:3080 打开。
• 终端只输出一次 hello-plugin 加载日志。
• 将绝对路径改为无效文件时，会得到可理解的加载错误。
• 停止或卸载插件后，定时器等副作用被正确清理。
• 移除 Patch 后，Web Profile 恢复原始行为。

常见问题