DeepSeek Harness

一条 Bash 命令背后的三个包

Provider 与 Consumer 互不依赖，两者都只依赖 Definition。 于是「把命令从本地挪到容器」只需要在 cordis.yml 里换一行。

npx @deepseek-ai/dsh web

# 默认 http://127.0.0.1:3080，并自动开浏览器
# 只想起服务不弹浏览器：
npx @deepseek-ai/dsh web --no-open

# 换端口（URL 由 SSH 客户端/编辑器持有本地转发时只打印宿主机地址）
npx @deepseek-ai/dsh web --port 8080

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

python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

# 跑一次、打印最终答案后退出
dsh --profile headless "run the tests"

# 通过 ACP stdio 为自动化客户端服务
dsh --profile acp

六个内置 profile

dsh 是唯一受支持的 Node 应用启动器。 所有子命令都由 profile 决定——profile 不是「模式开关」， 而是一棵由多个插件组合包按顺序叠加出来的配置树。

入口模式速查

$DSH_HOME 里有什么

用 Python SDK 跑一个任务

from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path("/absolute/path/to/disposable-workspace").resolve()
dsh_home  = Path("/absolute/path/to/example-dsh-home").resolve()

with DeepSeekHarness(
    provider="deepseek-official",
    model="deepseek-flash",
    max_tokens=49_152,
    cwd=str(workspace),
    dsh_home=str(dsh_home),      # 绝不静默读取 ~/.dsh
    profile="sdk-minimal",
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

SDK 会延迟启动内置的 dsh --profile sdk-minimal 进程， 并在上下文管理器退出时关闭；进程在整个 with 块内被复用，不是每次调用都重启。

一条好任务的四要素

目标：给订单模块补上「幂等下单」，重复请求返回同一订单号
范围：仅改 src/main/java/**/order 与对应测试目录
验收：新增单测通过，且 OrderControllerTest 全绿
禁区：不动数据库表结构，不动公共 Result 封装
完成后：输出改动的文件清单 + 为什么这么改

高频操作速记

第一步：最小插件长什么样

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

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // 必需依赖在此刻已经就绪
  console.log('[hello-plugin] plugin loaded!')
}

就这么多。没有注册表要填，没有插件清单文件——把文件挂进 cordis.yml 就能跑。

第二步：用 overlay 挂载它

# scratch-plugin/cordis.yml —— 一个 patch 数组
- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

第三步：让插件成为模型能用的工具

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}!`
    },
  }))
}

defineTool 根据 parameters 推导并校验 args；execute 返回 output.schema 声明的规范值，output.render 再把它转成面向模型的内容。重载后直接对 Agent 说「用 greet 工具向 Ada 问好」即可验证。

插件配置：用 schema 而不是野对象

import Schema from '@deepseek-ai/schemastery'

export interface Config {
  greeting: string
  maxRetries: number
}

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

export function apply(ctx: Context, config: Config) {
  console.log(config.greeting)   // 用户值，或 schema 默认值
}

在 cordis.yml 的插件行里加 config: 即可传参。 加载时 Cordis 会用 schema 校验配置并补齐默认值； 不要导出普通对象当 Config，它不满足 Cordis 要求的 Standard Schema 接口。

插件生命周期：Fiber 状态机

五种事件分发模式

waterfall 监听器拿到 (...args, next)：调用 next() 才委托下游；不调用直接返回就是短路—— 这正是策略插件声明「这个决策归我」的方式。

自动清理：不用手写 removeListener

export function apply(ctx: Context) {
  // 通过 ctx 注册的任何东西（事件监听、工具、定时器）在插件卸载时自动撤销
  ctx.effect(() => {
    const timer = setInterval(() => console.log('heartbeat'), 5000)
    return () => clearInterval(timer)   // 插件卸载时执行
  })
}

打包成组合包，让 profile 装它

# 组合包的 package.json：声明一个 patch 文件
{ "name": "dsh-hello-plugin", "version": "0.1.0", "type": "module",
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } }

# cordis.patch.yml：按包名引用，Node 才能解析到已安装代码
- insert:
    - id: hello
      name: dsh-hello-plugin

# 安装到某个 profile（管理命令才需要 pnpm，启动不需要）
dsh plugin --profile sdk-minimal add file:/absolute/path/to/hello-plugin

没有 dsh.bundle 声明的包也能装，但只作为普通依赖： dsh plugin 会打印警告且不激活任何层—— 如果这个包只是供别的插件 import，那正是你想要的效果。

没有技能时，Agent 每次都靠「通用常识」硬扛，结果就是风格漂移、流程随机。 装上技能后，你的架构规范、SQL 审查口径、安全审计清单都会被固定下来—— 同一个任务，不同人跑，产出接近，这才是能进团队工作流的前提。

加载流程：目录先看，正文按需

这个机制是「能装很多技能却不撑爆窗口」的原因： 会话里注入的只是已排序的 name 与 description， 不含正文、不含绝对路径；模型真的要用时才通过 skill 工具把正文读进来。 因此只改技能正文会影响后续调用，但不会改写历史对话。

技能根目录优先级

rank 越小越优先：项目根目录是「包含 .git 的最近祖先目录」， 找不到才用当前 cwd。重名时最近层直接赢；同一层内才按 rank、提供方顺序、本地顺序裁决。 技能名必须是 kebab-case（^[a-z0-9]+(?:-[a-z0-9]+)*$）， 支持目录包 <name>/SKILL.md 与扁平文件 <name>.md 两种形态。

两个开关：谁能调用这个技能

两个字段都设为 false 时，该技能只能由受信的代码 通过 ctx.skills.get() 获取——连模型和用户目录里都不会出现。 本地提供方读取省略的字段时默认都是 true。

技能本体长什么样

# .dsh/skills/idempotent-api/SKILL.md
---
name: idempotent-api
description: 为写接口补幂等键，覆盖去重存储、并发与重放测试
whenToUse: 新增/修改任何会产生副作用的写接口时
---

# 幂等写接口

## 何时使用
新增 POST/PUT 接口，或改造已有接口使其可安全重试时。

## 步骤
1. 确认幂等键来源：客户端 Header 还是业务唯一键
2. 落库去重表，唯一索引兜底并发
3. 补三个测试：重复请求、并发请求、超时重试
4. 在 PR 描述里写明幂等键与过期策略

## 检查清单
- [ ] 重复请求返回同一业务结果，而非报错
- [ ] 并发场景有唯一索引或分布式锁兜底
- [ ] 幂等记录有 TTL，不会无限增长

description 会被注入目录（默认上限 500 字符）， 写得能「路由」比写得长更重要；whenToUse 是额外的路由提示，不会替模型做决策。

沙箱管文件效果，审批管是否放行

注意网络与进程可见性不在这套词汇里——沙箱只管文件效果。 同类产品里已有实现把容器、microVM 当作同级 seam，而不是 ctx.sandbox 的一个提供方。

权限预设：把两个开关捆成一个选择器

预设切换只记录意图并通过每个 knob 各自的规范 setter 写入； 真正执行、提示词叙述与回放读的仍是各自的折叠结果，所以预设层不拥有任何强制执行权。

值得单独学的五个能力

工程集成：让它自己开评审会话

dsh 带了一个可选的 GitHub webhook overlay： 当已配置仓库的 PR 从 draft 变为 ready for review 时， 规则会在该仓库的 Web Workspace 下自动创建带标题的根会话，并启动只读评审提示词。

# 1) 生成一个高熵共享密钥，重启后继续用同一个值
export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"

# 2) 指定要评审的本地 checkout，并挂上 overlay
export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/your/repo
pnpm dsh web --patch apps/cli/config/examples/github-review/cordis.yml

# overlay 默认监听 127.0.0.1:3081，只注册 POST /github，其他路径 404
# 用 TLS 反代或 tunnel 把单个公网 URL 转发到这个 loopback 监听器

⚠️ 开发者预览状态

五条不该让它干的事