--- 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 本机实测) ```bash 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 < 22.19 会拒绝启动,先 `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`,详见「环境与部署分档」