DeepSeek Harness 二次开发实战：从「一切皆插件」到写出你自己的 Tool

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

export const name = 'my-plugin'

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

export const inject = ['tools']

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

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

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

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

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

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))
}

import Schema from '@deepseek-ai/schemastery'

export interface Config {
  greeting: string
  emoji: boolean
}

// 导出同名 Schema（Cordis 用它校验 + 填充默认值）
export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  emoji: Schema.boolean().default(true),
})

// apply 的第二个参数就是 config
export function apply(ctx: Context, config: Config) {
  // ... 用 config.greeting / config.emoji
}

- insert:
    - id: hello
      name: '/absolute/path/.../my-plugin.ts'
      config:
        greeting: 'Hey'
        emoji: false

export function apply(ctx: Context) {
  let pool: ConnectionPool | undefined

  ctx.effect(() => {
    pool = createConnectionPool({ host: 'localhost', port: 5432 })
    return () => {   // 清理函数，自动执行
      pool?.close()
      pool = undefined
    }
  })

  ctx.tools.register(defineTool({
    name: 'db_query',
    description: 'Run a read-only SQL query.',
    parameters: { sql: { type: 'string', required: true } },
    output: {
      schema: { type: 'array', items: { type: 'object' } },
      render: (_args, rows) => [{ type: 'text', text: JSON.stringify(rows, null, 2) }],
    },
    async execute(args) {
      if (!pool) throw new Error('Database pool not available')
      return await pool.query(args.sql)
    },
  }))
}

hello-plugin/
├── package.json       # 声明 dsh.bundle
├── cordis.patch.yml   # 该 bundle 贡献的配置层
└── index.js           # 插件入口

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

dsh plugin --profile demo add ./hello-plugin
dsh --profile demo --dump-config
dsh --profile demo

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

declare module '@deepseek-ai/cordis' {
  interface Context {
    myService: MyService
  }
}

export default class MyService extends Service {
  static inject = ['tools']
  constructor(ctx: Context) {
    super(ctx, 'myService')
  }
  doSomething() { /* ... */ }
}

import { readdir, readFile, stat } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'repo-explorer'
export const inject = ['tools']

// 可配置项：文件大小上限 + 忽略目录
export interface Config {
  maxFileBytes: number
  ignore: string[]
}

export const Config: Schema<Config> = Schema.object({
  maxFileBytes: Schema.number().default(128 * 1024),
  ignore: Schema.array(Schema.string()).default(['node_modules', '.git', 'dist', '.next']),
})

export function apply(ctx: Context, config: Config) {
  // 工具一：列出目录内容
  ctx.tools.register(defineTool({
    name: 'list_dir',
    description: 'List files and subdirectories in a directory.',
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path to the directory' },
    },
    output: {
      schema: { type: 'array', items: { type: 'string' } },
      render: (_args, value) => [{ type: 'text', text: value.join('\n') }],
    },
    async execute(args, exec) {
      const entries = await readdir(args.path, { signal: exec.signal })
      return entries
        .filter((entry) => !config.ignore.includes(entry))
        .sort()
    },
  }))

  // 工具二：读取文件内容（带大小上限与取消信号）
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a text file from disk. Returns its content as text.',
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path to the file' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      const info = await stat(args.path)
      if (info.size > config.maxFileBytes) {
        throw new Error(`File too large (${info.size} bytes, limit ${config.maxFileBytes})`)
      }
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

- insert:
    - id: repo-explorer
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/repo-explorer.ts'
      config:
        maxFileBytes: 65536
        ignore: [node_modules, .git, dist, .next, build]

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

浏览 /home/user/my-project 目录，找到入口文件，
总结这个项目的技术栈和目录结构。

export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.waterfall('tools/pre-execute', async (toolName, args, next) => {
    if (toolName === 'bash' && isDangerous(args)) {
      throw new Error('Blocked by safety policy')
    }
    return next()
  })
}