DeepSeek Harness从入门到插件化实践：增强版

Agent = Model + Harness

Harness = 插件树 + 服务依赖 + 事件 + 会话日志 + 权限策略

用户输入
  -> Agent inbox 领取消息
  -> 组装系统提示词、历史与工具 Schema
  -> LLM 请求
  -> 文本回复或工具调用
  -> 工具策略、参数校验与执行
  -> tool/result 写入会话日志
  -> 下一次模型请求或 turn/end

npx @deepseek-ai/dsh web

请概括这个仓库的目录结构，列出三个主要入口，并给出对应文件路径。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

pnpm dsh --profile headless "Summarize the repository"

dsh --profile web --dump-config

- patch:
    id: tool-web
    disabled: true

dsh --profile web --patch /absolute/path/disable-web.yml --dump-config

config:
  timeoutMs: 30000
  mode: accurate

config:
  mode: fast

config:
  timeoutMs: 30000
  mode: fast

mkdir -p scratch-plugin/src

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

[hello-plugin] plugin loaded

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

// 函数插件
export function apply(ctx: Context) {}

// 对象插件
export const objectPlugin = {
  name: 'object-plugin',
  apply(ctx: Context) {},
}

// Service 子类插件
export class MyService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'myService')
  }
}

export function apply() {
  throw new Error('apply exploded')
}

PENDING -> LOADING -> ACTIVE -> UNLOADING -> DISPOSED
                    -> FAILED

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

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

    return () => clearInterval(timer)
  })
}

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

export const name = 'config-demo'

export interface Config {
  greeting: string
  maxRetries: number
  verbose?: boolean
}

export const Config: Schema<Config> = Schema.object({
  greeting: Schema.string().default('Hello'),
  maxRetries: Schema.number().default(3),
  verbose: Schema.boolean().default(false),
})

export function apply(ctx: Context, config: Config) {
  console.log(`${config.greeting}, retries=${config.maxRetries}`)
}

- insert:
    - id: config-demo
      name: '/absolute/path/to/config-demo.ts'
      config:
        greeting: '你好'
        maxRetries: 5

export interface Config {
  timeout: number
  mode: 'fast' | 'accurate'
}

export const Config: Schema<Config> = Schema.object({
  timeout: Schema.number().default(30000),
  mode: Schema.union(['fast', 'accurate']).default('fast'),
})

config:
  timeout: 30000
  mode: turbo

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

export const name = 'project-brief-tool'
export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'project_brief',
    description: 'Create a short project brief from a goal and audience.',
    parameters: {
      goal: {
        type: 'string',
        required: true,
        description: 'The concrete project goal',
      },
      audience: {
        type: 'string',
        required: true,
        description: 'Who will use the result',
      },
      maxItems: {
        type: 'number',
        description: 'Maximum number of acceptance items',
      },
    },
    output: {
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          summary: { type: 'string' },
          acceptance: { type: 'array', items: { type: 'string' } },
        },
        required: ['title', 'summary', 'acceptance'],
        additionalProperties: false,
      },
      render: (_args, value) => [{
        type: 'text',
        text: [
          `# ${value.title}`,
          value.summary,
          ...value.acceptance.map((item, index) => `${index + 1}. ${item}`),
        ].join('\n'),
      }],
    },
    async execute(args, exec) {
      if (exec.signal.aborted) throw exec.signal.reason
      const limit = Math.max(1, Math.min(args.maxItems ?? 3, 6))
      const acceptance = [
        `结果适合${args.audience}直接阅读`,
        `内容覆盖目标：${args.goal}`,
        '关键结论可以从外部结果复核',
        '失败状态带有明确错误信息',
      ].slice(0, limit)

      return {
        title: `${args.audience}项目简报`,
        summary: `围绕“${args.goal}”整理可执行范围。`,
        acceptance,
      }
    },
  }))
}

请调用 project_brief，为“整理 DeepSeek Harness 插件导航”生成一份面向初级开发者的简报，验收项最多 4 条。

{
  "goal": "整理 DeepSeek Harness 插件导航",
  "audience": "初级开发者",
  "maxItems": 4
}

async execute(args, exec) {
  const response = await fetch(args.url, { signal: exec.signal })
  return response.text()
}

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

declare module '@deepseek-ai/cordis' {
  interface Context {
    greeter: GreeterService
  }
}

export class GreeterService extends Service {
  constructor(ctx: Context) {
    super(ctx, 'greeter')
  }

  greet(who: string) {
    return `Hello, ${who}`
  }
}

export function apply(ctx: Context) {
  ctx.plugin(GreeterService)
}

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

export const inject = ['greeter']

export function apply(ctx: Context) {
  console.log(ctx.greeter.greet('world'))
}

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

declare module '@deepseek-ai/cordis' {
  interface Events {
    'demo/report'(name: string, count: number): void
  }
}

export function apply(ctx: Context) {
  ctx.on('demo/report', (name, count) => {
    console.log(`[demo] ${name}=${count}`)
  })

  ctx.emit('demo/report', 'tool_call', 2)
}

ctx.on('demo/transform', async (input, next) => {
  if (input.includes('blocked')) return '** blocked **'
  return next()
})

ctx.on('demo/transform', async (_input, next) => {
  const result = await next()
  return result.toUpperCase()
})

hello-plugin/
├── package.json
├── cordis.patch.yml
└── 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"
    }
  }
}

export const name = 'hello-plugin'

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

- insert:
    - id: hello
      name: dsh-hello-plugin

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

dsh plugin --profile demo remove dsh-hello-plugin

dsh plugin --profile web add package-name
dsh plugin --profile web add github:you/plugin#<commit>
dsh plugin --profile web add git+https://github.com/you/plugin.git
dsh plugin --profile web add ./plugin-0.1.0.tgz

import { describe, expect, it } from 'vitest'

describe('project_brief', () => {
  it('limits acceptance items', async () => {
    const result = await executeBrief({
      goal: '整理插件导航',
      audience: '初级开发者',
      maxItems: 2,
    })

    expect(result.acceptance).toHaveLength(2)
  })
})

请调用 project_brief，为“做一个插件安全检查器”生成面向插件维护者的简报，验收项 3 条。

provider-en.ts
provider-zh.ts
consumer.ts
cordis-en.yml
cordis-zh.yml

# 启动 Web UI
npx @deepseek-ai/dsh web

# 从源码启动 Web UI
pnpm dsh web

# 通过本地覆盖层启动
pnpm dsh web --patch /absolute/path/to/cordis.yml

# 查看最终配置树
dsh --profile web --dump-config

# Headless 一次性任务
dsh --profile headless "Summarize the repository"

# 安装、移除 Bundle
dsh plugin --profile demo add ./hello-plugin
dsh plugin --profile demo remove dsh-hello-plugin

# 仓库常用验证
pnpm run test
pnpm run typecheck
pnpm run lint
pnpm run build