DeepSeek Harness（dsh）源码分析¶
状态：官方 developer preview；研究快照：2026-09-26。
它是什么¶
DeepSeek Harness（dsh）是 DeepSeek AI 开源的 Agent harness，核心主张是 Everything is a Plugin。官方介绍把模型、工具、skills、sessions、sandboxes、storage、loops、scheduling 和 UI 都视作插件能力，并通过 Cordis kernel 组合运行时。
官方入口：DeepSeek Harness developer preview、dshai.org、GitHub 仓库。
源码地图¶
以仓库当前架构文档为准，重点阅读：
| 位置/概念 | 作用 | FDE 阅读问题 |
|---|---|---|
packages/core |
能力抽象、Cordis 服务和事件 | 哪些接口是稳定 seam，哪些仍是 preview |
packages/bundle |
base、headless、web-app、sdk-app、sdk-minimal、acp-app 组合 |
Profile 如何决定运行时能力 |
packages/llm* |
模型适配与重试等能力 | 模型切换是否不影响 agent loop |
packages/tool* |
文件、shell、搜索、浏览等工具 | 工具权限与 approval 在哪里生效 |
| session / trajectory | 追加式日志、resume、fork、replay | 能否重现一次模型看到的上下文 |
docs/architecture.md |
官方架构约束和入口分类 | 哪些 Node entrypoint 被禁止绕过 dsh |
源码树会随 preview 演进，以 docs/architecture.md 和对应 commit 为准，不把旧目录名当稳定 API。
运行时心智模型¶
dsh launcher
-> profile
-> ordered plugin bundles
-> model adapter + tool registry + session log
-> sandbox + approval + storage + telemetry
-> agent loop + UI / headless / SDK / ACP
官方架构文档强调没有一个必须修改的“特权核心”；扩展通过挂载 plugin 和 effect unwind 组合。对 FDE 来说，这意味着可以把企业策略作为旁路插件，而不是 fork 整个 Agent。
Profile 对应什么场景¶
| Profile | 形态 | 适用条件 | 代价 | 验证方式 |
|---|---|---|---|---|
web |
浏览器 UI | 需要可视化 session、审批和 trajectory | Web 层依赖较多 | dsh web --dump-config、固定任务回放 |
headless |
一次性运行器 | CI、批处理、无 UI 自动化 | 需要自己处理 stdout、退出码和日志 | 相同输入跑三次，比较退出原因和副作用 |
sdk |
JSON-RPC/SDK 服务 | 宿主应用要控制 live agent | API 版本与生命周期需要锁定 | SDK contract test、断线恢复、取消测试 |
sdk-minimal |
最小显式 SDK 树 | benchmark、最小实验、减少变量 | 失去标准 bundle 能力 | 与 standard mode 对照评测 |
acp |
自动化协议服务 | 接入外部 Agent/IDE 编排 | 依赖 ACP 兼容性 | ACP session、tool call、错误语义测试 |
模式差异¶
- Standard：全工具 coding agent，适合开发任务。
- Code：把能力暴露给 Code Mode SDK，让模型用 TypeScript 组织多步调用；适合减少多轮 tool-call 往返，但增加代码执行边界。
- Minimal：只保留 shell 与文件编辑，适合测模型本身，不适合直接当生产默认。
- Creator：检查当前 runtime、试验 Cordis 插件和组合 preset；适合开发 harness，不应直接开放给不可信用户。
关键设计判断¶
优点¶
- 能力可替换：模型、工具、日志、loop 都不被单一实现锁死。
- 运行可追踪：官方强调 append-only session log，能记录 system prompt、工具、结果、subagent scheduling 与 context injection。
- Profile 明确：同一套插件能力可以面向 Web、headless、SDK、ACP 组合。
- 适合做平台原型：Cordis 服务/事件适合承载企业扩展。
代价和风险¶
- Developer preview 意味着 API、包结构和文档可能快速变化。
- 插件化扩大了供应链和权限面；第三方插件必须 pin commit、审查权限和 SBOM。
- Code Mode 把执行权交给模型生成的程序，必须把 sandbox、网络、文件范围和预算作为独立策略。
- append-only trace 解决可见性，不自动解决敏感数据保留和租户隔离。
FDE 集成建议¶
业务入口 -> dsh sdk/acp -> 企业 policy plugin
-> private model / hosted model adapter
-> tool allowlist + approval
-> append-only trace -> eval replay
先用 headless 建立固定任务回放，再用 sdk 接入产品；不要一开始就 fork Web UI。企业插件最小集合：身份与租户、工具 allowlist、审批、成本限额、trace 脱敏、回放导出。
验证清单¶
[ ] 同一任务在 standard/headless/sdk 上输出和工具轨迹可解释
[ ] 关闭 shell、写文件、网络后权限真的生效
[ ] 工具超时、取消、未知状态不会重复写入
[ ] session 可 resume、fork、replay，且不泄露其他租户
[ ] 插件卸载后 effect 和后台任务能回收
[ ] 第三方插件的 commit、依赖和权限已记录