SKILL.md 23 KB

name: deepseek-harness description: DeepSeek Harness (dsh) 开源 Agent runtime 实操——安装/启动/四种模式/插件架构/仅追加日志。触发词:dsh、DeepSeek Harness、@deepseek-ai/dsh、Agent runtime、PTC。Use when 火星人问 DeepSeek 开源 Agent 框架、要本地拉起 dsh、或审计 harness 设计需开源对照物。 version: 1.9.0

category: autonomous-ai-agents

DeepSeek Harness (dsh)

DeepSeek 2026-08-13 发布的 MIT 开源 Agent 基础设施。模型之外的一切(工具/技能/会话/沙箱/存储/循环/调度/界面)皆插件,基于 Cordis(副作用追踪、依赖解析、配置协调、热更新)。

Quick Start(2026-09-20 本机实测)

npx -y @deepseek-ai/dsh --version   # 查版本
npx -y @deepseek-ai/dsh web         # 启动 Web 界面,默认 http://127.0.0.1:3080
  • Node.js 22.19+/24+(本机 v26.4.0 实测通过;首次 npx 需下载包,耐心等)
  • 版本快速迭代期(2026-09-21 实测 latest 已到 0.1.5-rc.2),升级可能有破坏性变更,别在生产管线硬依赖

四种运行模式

模式 用途
标准 日常任务
极简 仅 Shell+文件编辑,跑基准测试用
PTC 模型先写代码再组织多轮工具调用,减少往返——程序化工具调用参考实现
创造 检查运行时、试验插件、组合新模式

补充(learn_queue #851):PTC 模式把多步工具调用写成一段代码一次执行——步骤越多越快、上下文消耗越少。会话产生内容后不能中途切换模式,开新会话才能换。

模式选型判据(learn_queue #891,v1.7.1)

PTC 不是默认档,按任务形状选:长流程(步骤多)/重复性操作多/数据量大 → PTC;短平快任务 → 标准模式。标准模式 = 调一次工具看一次结果,短任务下更简单可控;PTC = 先把多步组织成可执行程序再一次性跑完,省往返、稳收敛。实证:测速案例中 PTC 自动写脚本、全球 8 地区反复采样并落盘原始数据,全程无逐轮往返〔原文 L7〕。

选型铁律(同模型切模式即换产出):同一模型只切换运行模式,产出质量就上一个量级——模型决定上限,Harness 决定能力发挥程度,乘法关系。反直觉锚点:v4 Flash + dsh 画纽约天际线效果胜过 v4 Pro——日常小任务用便宜模型(快/便宜/够稳)+ 好 Harness 即可,复杂长流程才切强模型。与 HLR 定量实证(memory: hlr-harness-leverage-ratio-2026,Harness 增益随任务程长 0.78x→3.57x 递增)互证。

社区演化锚点:dsh 上线 1 小时 2 万星、次日 6 万星;社区演化三级 = 换 UI 皮肤 → 换工具层 → 直接手搓主循环。证明生态引爆点是可改造程度(一切皆插件的红利),不是模型本身〔原文 L13〕。

核心设计(审计/对照时引用)

  • 仅追加会话日志:Session 事件流是交互历史唯一事实来源,支持回放、错误回溯与恢复
  • 与 MCP 分层:MCP 管「怎么连」,Harness 管「怎么运行」
  • 开放生态:MIT + 可接第三方模型(vs Codex/Claude Code 封闭自家模型)
  • 产品分层定位:Claude Code、Codex、WorkBuddy 都是建立在 Harness 之上的完整 Agent 产品——Harness 是基座层,Agent 产品是其上应用;Hermes 同构(runtime + skills + UI)

架构方法论与 RSI 运行时基础(learn_queue #852)

同一主题第二篇(方法论+理论篇)。#851 讲安装/安全/生态实操,本篇讲架构方法论与 RSI 理论基础。

核心公式:Agent = Model + Harness。一切皆插件(模型适配器/工具/日志/Agent Loop 均可重组),无特权核心组件,重心是长期可扩展性/可替换性/可恢复性〔原文 L3〕。

  • 换配置即变身:同一套 Harness 只换配置,即可从类 Claude Code 编程助手变成后台自动化执行器——Harness 与产品形态解耦的直接证据,审计 harness 设计时的「形态无关性」检查项
  • 重建性判据(append-only 的强化表述):凡进入模型上下文的信息都必须能从日志重建;任务可恢复、可分叉、可重放,UI/遥测/持久化共享同一事实来源。判据升级:不只问「日志能不能回放」,问「上下文里的每一条是否都可从日志重建」——任何靠 session 内存而非日志承载的状态都是重建性缺口

RSI 优化对象五层外移(Lilian Weng《Harness Engineering for Self-Improvement》)

自改进系统的优化对象沿以下序列逐层外移:

Prompt → Structured Context → Workflow → Harness Code → Optimizer Code
  • Hermes 定位:learn-and-build 6 步 Loop 改 skill/memory = 在 Harness Code 层优化;「用 AI 审计 AI 的学习流程本身」= 向 Optimizer Code 层外移(当前未达)
  • 用法:评估任何自进化提案时先定位它在哪一层——只调 prompt 是最浅层,改流程编排是中间层,改「改流程的代码」是最外层。外移一层 = 自我改进的作用域扩大一圈
  • 与 RSI Level 1(Weco AIDE²,外层 agent 改写内层 harness)的关系:AIDE² 实证的就是「外移到 Harness Code/Optimizer Code 层」的可行性

可组合性三判据(《A Programming Paradigm for Spatiotemporal Composability》)

形式化论证,管线/多 Agent 系统审计时的三项检查:

判据 含义 审计问题
时间可组合性 副作用可回滚 失败重跑时,上一次的副作用能否撤销?(如 auto-reply 已发的 ack 消息)
空间可组合性 依赖局部重连 替换一个组件(如换 sender/换模型)时,是否只需局部改连线而非全局重写?
Confluence(合流) 多路径殊途同归 两条修复/执行路径是否收敛到一致状态,而非分叉冲突?

与 Graph Engineering「四类边」互补:四类边审计静态拓扑(数据/权限/验证/恢复边),三判据审计动态行为(回滚/重连/合流)。两套一起用才完整。

Cordis 动态组合机制(learn_queue #996,三判据的工程来源)

上表三判据不是抽象指标,DSH 用 Cordis meta-framework 在工程层实现。DSH 三层架构:Coding Agent(Web UI)→ Harness 构造框架(everything-is-a-plugin:Model Adapter/Tool Registry/Sandbox Policy/Agent Loop 全可自定义)→ Cordis meta-framework(底层插件机制:热重载/自由组合/彻底删除)。

  • Component Mutation(组件变异):Cordis 把一次危险的全局修改缩小成有边界的组件级变更,类似数据库事务——要么完整生效、要么整体回滚
  • 时间可组合性的实现:卸载插件时撤销其所有副作用,杜绝「幽灵组件」(插件没了但残留还在)
  • 空间可组合性的实现:依赖出现/消失时组件自动在 Waiting/Active 状态间重组,无需手工重连线
  • 两种 Harness 哲学对照:Anthropic 优化当下(从 SOTA 模型失败模式出发设计 harness;Opus 5 后删掉超 80% System Prompt);DSH 押注范式(设计可低成本修改、可撤销、可重组的 Meta Harness)。审计/选型时先问立场:解决眼前模型的短板,还是赌模型持续变强后基础设施形态
  • To Developer → To Agent:Harness 短期用户是开发者,长期用户是 Agent 自己。Hermes 已在此轨迹上——learn-and-build 的 skill 消费者已是 Agent 本身
  • Hermes 应用:patch skill / 改 cron / 换管线组件时,自检是否「有边界的 Component Mutation」(可撤销、局部重连、不留幽灵残留)而非全局修改

多智能体与循环(learn_queue #851)

  • subagent:可续跑的后台子代理(长任务放后台,之后接着跑)
  • subagent_fork:继承当前上下文的一次性子代理(跑完即弃,适合并行分叉)
  • 工作流引擎:脚本确定性编排多个子代理(Graph 式编排,对应 Hermes「Graph/Loop 分工」)
  • Ralph 循环:每轮启动全新子代理重复执行同一目标直到达成——上下文污染隔离的循环范式
  • 治理锚点:长期目标操作需人类根权限

编排控制权与子代理化(learn_queue #1034,v1.5.0)

来源:《从 Codex Harness 到 DSH Subagent:Agent 编排新范式》,article_url 可从 learn_queue #1034 查询。补充上文 subagent 三原语所缺的控制权归属框架——多 Agent 系统审计时逐项对照,防四权混用。

背景:DSH 0.1.0-rc.8 把 Codex 和 Claude Code「降级」成可调用子代理(按需安装的配置包);Codex 侧则通过 app-server 把执行入口开放成平台(thread/turn/事件/中断/审批接口)。父 Agent 只负责委派,DSH 运行时负责调度,子代理保留完整执行系统而非被拆成普通函数〔原文 L5/L7〕。

四种控制权不能混在一起:

控制权 归属 Hermes 对应
委派权(是否委派、委派给谁) 父 Agent hermes chat / hermes 子进程的调用方(cron 管线、本吸收器)
调度权(启动进程、管理 Job、等待或后台) DSH 运行时 Hermes runtime / cron 调度器
执行权(各 Harness 内部工具与循环) 子代理自身 子进程的 Agent Loop
验收权(权威事实与验收) 业务系统与人 外部产物对账、人类拍板节点

三个不等式:选中子代理 ≠ 拿到全部权限;子代理说「完成」≠ 业务验收通过;取消 Job ≠ 副作用已回滚。

一次性委派五缺陷(Hermes 的 hermes chat 子进程、cron one-shot 全是此形态,设计/审计时逐条对照):① 不继承父对话/角色设定/工具筛选/输出格式 ② 中间过程(工具调用/文件改动/Token 消耗)不回传父会话 ③ 无统一超时验收 ④ 无副作用回滚 ⑤ 并发改同一批文件会冲突〔原文 L9〕。

Agent 调用粒度判据:Agent 调用是模型调用、工具调用之后的第三种组合粒度——更像 Runtime 而非更大的函数(要维护上下文、多轮往返、请求审批、产生状态和副作用)。何时值得 spawn 子 Agent 而非普通工具调用:需要多轮往返/审批/状态副作用时才用 Agent 级;子 Agent 收到的是自然语言任务,「已完成」是自述而非可入账的业务事实,验收必须落在执行权之外〔原文 L11〕。

Harness 基础设施层实证(ARC-AGI-3):OpenAI 实验中同一模型保留推理状态+启用上下文压缩后得分显著提升——模型没换,执行状态和上下文整理方式变了〔原文 L15〕。与上文「Agent = Model + Harness」公式互证。

安全与治理(learn_queue #851)

  • 进程沙箱三档:read-only / workspace-write / danger-full-access,Linux/macOS/Windows 原生隔离机制
  • 敏感操作需审批(对应 Hermes per-action 审批梯度 gap 的开源参照)
  • 守卫插件:自动纠偏循环失控和超时(防 Agent 无限消耗)
  • API Key 独立通道传递,不进日志;遥测默认档 = FEEDBACK_ONLY(纠正旧表述「遥测显式开启才上传」,learn_queue #1395,2026-10-13 修正):默认不主动上报,但点反馈即释放截至该反馈的会话前缀(提问/模型回复/命令输出,含上下文),出厂零脱敏规则(seam 在、规则空 ⇒ 原样离开进程)——跑过 .env / 带密钥命令的会话千万别点反馈;进程级开关 DSH_TELEMETRY_DISABLED(profile 启动时给 session-telemetry 行打补丁,实测 dsh/lib/profile-boot-*.js:249),OTEL 侧 mode=DISABLED 不构造任何传输对象。/feedback 确认文本只确认「已记录」,不是投递回执;sharing(full/feedback-only/disabled)同样不是投递回执。本机源码级复证见 skill agent-client-telemetry-audit(@deepseek-ai/dsh 0.1.5-rc.2)

生态兼容(learn_queue #851)

  • MCP 服务器 + Hooks 桥(Claude Code/Codex 钩子脚本可直接复用)+ 内置 ACP 服务端 + Skills 技能库
  • 三种定时任务;任意 OpenAI 兼容模型端点
  • 质量标准:源码逐文件 100% 单元测试覆盖率,文档过期阻断 CI(开源工程基准参照)

实操要点(v0.1,2026-09-21 补充自 learn_queue #847)

  • 133 个内置插件:默认全装、界面自由开关,替换/扩展任何能力无需改源码
  • 分工铁律:「模型思考,Harness 干活」——模型、工具、文件、会话、权限、任务调度、执行过程全部由 Harness 管理
  • 模型无关切换:配置厂商 API Key 后即可在界面切换几乎所有主流模型
  • Trajectory 视图:系统提示词、思维链、工具调用、执行结果、子 Agent 调度全部记录,可查看/恢复/分叉/检索/回放(Hermes AgentLoop trace gap 的能力参照)
  • 量化锚点:用 Harness 写扫雷游戏约 5-6 分钟完成,全程每步工具调用可查

架构精读:双线架构与机制边界(learn_queue #855)

来源:《DSH(DeepSeek Harness)架构解析》,article_url 可从 learn_queue #855 查询。同主题第六篇(架构精读篇),前三篇讲「能做什么」,本篇补「怎么组织」与「统一机制做不到什么」。

双线架构:「一切皆插件」只是表象,真正有辨识度的是两条数据结构并行运转——Cordis 维护的运行时插件图(系统现在由什么组成)与 Session 维护的追加式事件流(系统刚才做过什么),Agent loop 位于两者之间〔原文 L4〕。对照:Skill Relation Graph 回答「能力拓扑」,append-only 日志回答「行为历史」——任何 runtime 审计都应先找这两条线在哪。

Cordis 五合一:一个插件系统同时解决五个通常分离的问题〔原文 L5〕——①插件能看见哪些能力 ②必需能力缺失时是否启动 ③同名 service 按作用域解析到不同实现(scope resolution,普通 DI 容器做不到)④插件退出时谁清理资源 ⑤静态配置如何变成可更新的运行时插件树。

时空可组合性的实现机制〔原文 L6,为 #996 三判据表的工程落点〕:

  • 空间组合性 = Context 的继承与隔离(inject、service realm)决定插件在哪个位置看到哪个 service
  • 时间组合性 = Fiber 的装载/卸载与 effect 资源回收决定插件在什么时间生效和退出

Runtime Profile 与 Agent Preset 是两条独立的轴〔原文 L7〕——修正「四种模式互斥」的表面理解:

  • Runtime Profile(web/headless)= 进程形态轴;Agent Preset(standard/code/minimal/cordis)= 会话能力轴
  • 一个 Web 进程可同时承载不同 preset 的会话
  • PTC 只替换工具展示协议层(不改变工具能力本身);Minimal 只收窄模型可见工具面(仅 Bash 与 str_replace_editor)
  • Hermes 对照:cron/CLI/web 即 Hermes 的 Runtime Profile 轴,-s 技能组合即 Preset 轴——两轴独立组合,不是四种互斥形态

统一机制的边界(评估「一切皆插件」类架构时的现实性检查,含对 Hermes skill 生态的映射)〔原文 L8〕:

  • effect 可逆 ≠ 事务:网络消息、文件写入、支付这类外部世界写入无法自动补偿——审计管线回滚设计时别把「effect 可逆」当成「已发微信能撤回」
  • 插件化 ≠ 安全:inject 挡不住同进程直接 import Node API——插件边界不是安全边界,Hermes 同理:skill 隔离挡不住 terminal 工具的全盘访问
  • 「一切皆插件」并非递归到底:Cordis 根 Context 等核心必须先存在——「无特权核心」是有前提的
  • 性能开销至今缺乏量化基准——插件化灵活性的代价尚未被测量

插件内核机制(learn_queue #908,系列 1/4)

来源:《DeepSeek Harness 插件内核机制(1/4)》,article_url 可从 learn_queue #908 查询。前序章节讲「能做什么/怎么组织」,本篇补 Cordis 内核的效应系统与切缝原则。

effect/coeffect 从编译期搬到运行期〔原文 L5〕:

  • effect(可逆效应,管时间):每次环境修改自带逆操作,卸载 = 安装的严格逆运算——比 #996「组件变异=有边界事务」更底层的机制表述:可逆性不是打包实现,是每个 effect 携带自己的 undo
  • coeffect(反应式协效应,管空间):依赖成为被持续监控的关系,能力消失则依赖方自动停摆——「依赖」从一次性解析变成持续观察的活关系

抽象好坏判据:新功能是「推论」而非「新机制」则抽象正确〔原文 L6〕——热更新在 Cordis 里不是专门实现的功能,而是「可逆效应+依赖跟踪」自然掉出来的推论。审计/设计抽象时反向应用:如果每加一个功能都要引入专门机制,说明底层抽象错了(对照:Hermes 加 cron 暂停/断点恢复若是专门补丁而非从任务状态模型自然推出,就是抽象债信号)。

插件化难点不在「支持插件」而在「在哪里下刀」〔原文 L7〕——dsh 把「执行 shell 命令」拆成定义/实现/消费者三个互不相识的包,换两行配置即可让工具层物理执行位置(本地→远程沙箱)搬家。Hermes 映射:skill(SKILL.md 定义)+ scripts/(实现)+ 管线调用方(消费者)已是三包雏形;「换模型/换工具层只改配置」的解耦程度是切缝质量的标尺。

插件开发接口与事件钩子(learn_queue #1325,桌面端机制篇)

PURPOSE 锚:为解决「Hermes 长期只有 cron 时间触发,缺 agent 生命周期事件钩子(执行前可拦截/执行后可改写)——补 hook 层时没有可抄的最小契约」这个 pattern 而加(learn_queue #1325,2026-10-12)。修改前先回溯此意图。 来源:《DeepSeek Harness (DSH) 桌面端核心机制拆解》,article_url 从 learn_queue #1325 查询。

业务插件最小开发面 = 两件套〔原文 L5〕:实现 apply 函数注册能力(如 lookup_order 工具)+ 用 inject 声明依赖服务。插件只注册能力,不接管主流程——模型何时调用、结果如何回传、是否继续下一步,全由已有主流程决定。这是「业务插件开发成本低」的机制来源,也是 Hermes 同构点:skill 定义能力边界(SKILL.md),循环控制权留在 runtime(hermes / cron 管线),skill 不自己跑循环。

时间可组合性的 API 级落点〔原文 L4〕:#996 三判据表讲「副作用可回滚」,落点是——自建定时器/连接必须交给 ctx.effect() 托管,否则插件卸载时不会被自动撤销注册与资源清理(自己裸建的 timer/连接 = 幽灵残留,是时间可组合性的头号破口)。空间可组合性的落点 = 声明依赖的服务就绪后激活、消失时停用、恢复后重载,无需手工重连线。Hermes 自检:管线里是否有人绕过托管机制裸建资源(后台 shell、独立轮询脚本、常驻进程)——那些就是「卸载后仍在跑」的候选。

事件介入点三档〔原文 L6〕——工具执行的三个切面,补 Hermes hook gap 的最小契约:

钩子 用途 语义
tools/pre-execute 执行前检查/拦截(如非营业时间禁止删单) 可阻断
tools/execute 超时重试等执行策略 包裹执行
tools/post-execute 改结果 可改写输出

瀑布式铁律:钩子按注册顺序串行传递,每档必须调 next() 交出控制权——漏调 = 断链,其后的钩子静默失效(不报错,最难查的那种)。审计任何 hook 链先查「有没有漏 next()」。

Hermes 映射(hook gap 的参照实现):Hermes 当前无 agent 生命周期钩子——cron 是时间驱动(异步、不阻塞、事后),hook 是事件驱动(同步、可阻断、事前/事中)。分工判据:写文件后扫描、发消息前校验、commit 前拦密钥 → hook;定时批处理、周期性巡检 → cron。三档切点 + next() 瀑布语义构成补 hook 层时的最小契约(L2 待实现,此前只有「该不该做 hook」的定性讨论,无具体形状)。

Hermes 侧插件层对照物:hermes-desktop-plugins skill(desktop-plugin-sdk)是同一「注册能力不接管主流程」形状的既有实现——其 ctx.register/ctx.i18n.register 对应 apply 注册能力,SDK 托管生命周期(热重载时自动 teardown)对应 ctx.effect()。差异即 hook gap:desktop 插件只有「注册」面无「执行前拦截/执行后改写」面。审计插件层时两 skill 配对读。

创造模式(Agent 自写插件)实测——负面锚点〔原文 L7〕:Agent 可按需自动编写并安装插件(自我进化实验性落地),但实测因 parameters 声明格式不符反复报错、并影响正常对话,最终靠人工定位修正才恢复。→ 机制世界的自进化也会被「声明格式」这种琐碎约束卡死,且失败会污染主流程(不只是插件没装上)。与 HarnessDev(剥离人工脚手架后泛化差、严重寄生于 Runtime 模型)同向,构成「自进化案例必须正反面配对引用」的反面一侧。Hermes 对照:learn-and-build 的 skill/memory 自动改写之所以没翻车,靠的是 Step 5 确定性验证 + 回放验证才入库——不重蹈「无人值守自写」的机制。

环境与部署分档(learn_queue #1325)

  • 源码版本 0.1.7-rc.1(原文 L8 时点);依赖 Node.js 24 + pnpm 11.7.0。本机实测路径:Node v26.4.0 + npx(Quick Start)通过,源码构建未在本机验证
  • DSH_HOME 隔离运行数据——多实例/试验不污染主环境(Hermes 对照:HOME / profile 隔离)
  • --patch 加载插件仅本次启动生效;要持久化必须写入 $DSH_HOME/profiles〔原文 L8〕。这是「临时试验 vs 长期配置」两档显式分离——排查「插件装了重启就没了」先查它是不是 --patch 加载的
  • 不可逆写入的部署陷阱:--patch 让人误以为已安装(会话内一切正常),重启才暴露 → 凡涉及「配置生效范围」的机制,都要问「这次生效的边界在哪、重启后还在不在」

与 Hermes 的关系

  • 同为 Agent runtime 层;插件化 + 仅追加日志两个设计可直接对照借鉴
  • PTC 模式是给学习执行器/长管线减 token 往返的参考实现(L2 待集成)

Troubleshooting

  • npx 首次运行慢 = 正在下载包,不是卡死
  • Node node --version
  • npx @deepseek-ai/dsh --version 报 dsh: not found(exit 127)(2026-09-21 实测):新版 bin 解析问题,绕过 = 直接跑 npx 缓存里的 bin:node ~/.npm/_npx/*/node_modules/@deepseek-ai/dsh/lib/bin.js --version
  • 插件装了、重启就没了:多半是 --patch 加载的(仅本次启动生效)——持久化须写入 $DSH_HOME/profiles,详见「环境与部署分档」