DSH 核心机制与插件开发

{"type":"session","version":3,"id":"{{session:1}}","cwd":"{{cwd}}","delegationDepth":0,"agentPreset":"standard"}
{"type":"sandbox/mode","data":{"mode":"danger-full-access"}}
{"type":"turn/start","data":{"turn":1}}
{"type":"step/start","data":{"turn":1,"step":1}}
{"type":"user/message","data":{"content":[{"type":"text","text":"Inspect the protected operation, but do not run it unless authorized."}],"role":"user"}}
{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"auto-review-denied-call","name":"mystery","arguments":"{\"secret\":\"hidden-input\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"}}}}
{"type":"tool/call","data":{"turn":1,"step":1,"callId":"auto-review-denied-call","name":"mystery"}}
{"type":"tool/result","data":{"turn":1,"step":1,"message":{"content":[{"type":"tool-result","toolCallId":"auto-review-denied-call","isError":true}]},"error":{"code":"AUTO_REVIEW_DENIED"}}}
{"type":"step/end","data":{"turn":1,"step":1}}

- id: sandbox
  name: '@deepseek-ai/dsh-sandbox-local'     # 按平台选择的后端提供方（ctx.sandbox）
- id: sandbox-policy
  name: '@deepseek-ai/dsh-sandbox-policy'    # 部署默认的模式，以及 workspace-write 的根目录
  config:
    mode: workspace-write
    workspaceRoot: !!js process.cwd()
- id: bash
  name: '@deepseek-ai/dsh-bash-sandbox'      # ctx.shell 背后的受限执行器

// 片段（no-check）：仓库源码的 API。npm 上的 rc 包类型可能略有不同，见第 8 节
import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

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

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',          // 模型看到的说明
    parameters: {
      path: { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },                     // 默认是可选参数
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      // args 的类型由 schema 推导出来：{ path: string; limit?: number }
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

// greet-tool.ts（已按 npm 0.0.1-rc 包的 API 调整，并实际运行过）
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
import type { CallId } from '@deepseek-ai/dsh-llm'

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

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

  // 代替模型发起一次调用，走真实的执行流水线
  void (async () => {
    const result = await ctx.tools.execute({
      callId: 'demo-1' as CallId, // branded 类型只存在于编译期
      name: 'greet',
      arguments: { name: 'Cordis' },
      signal: new AbortController().signal,
    })
    console.log('tool replied:', JSON.stringify(result.content))
  })()
}

// tool-logger.ts：一个独立的观察插件，通过 tools/result 事件观察所有工具调用
import type { Context } from '@deepseek-ai/cordis'
import type {} from '@deepseek-ai/dsh-tools'

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

export function apply(ctx: Context) {
  ctx.on('tools/result', (exec, result) => {
    const text = result.content
      .map(block => (block.type === 'text' ? block.text : ''))
      .join('')
    console.log(`[tool-logger] ${exec.name} -> ${text}`)
  })
}

# cordis.yml：dsh-tools 会 inject systemPrompt，所以要同时列出它的提供方
- name: '@deepseek-ai/dsh-system-prompt'
- name: '@deepseek-ai/dsh-tools'
- name: './tool-logger.ts'
- name: './greet-tool.ts'

$ node --import tsx node_modules/@deepseek-ai/cordis/bin.js
[tool-logger] greet -> Hello, Cordis!
tool replied: [{"type":"text","text":"Hello, Cordis!"}]