DeepSeek Harness 保姆级教程:从安装到改造框架本身,一条龙讲透

一、为什么我又换 Agent 工具

一年里我换过 Claude Code、Codex、Cursor、Aider、Cline——每个都用了几周,最后都因为同一个原因放下:

它们的"控制力"和"透明性"在某个临界点之后开始塌方。

举个最近的例子:我想给一个 Vue 2 老项目加 lint 步骤。Claude Code 帮我改完,我打开文件,只看到一半的修改。问它,说"已经改完"。再开 Trajectory,发现它在第三步超时回滚了,后面的步骤只是嘴上说改了,实际文件没动。

这件事让我意识到一个被忽略的事实:大部分 Agent 框架把执行细节藏起来,出问题就只能猜。

所以当 DeepSeek Harness(DSH)用"Everything is a Plugin"的姿态出现时,我第一反应是:这不是又一款 AI CLI 吗?用了之后才明白,它和前面那一票工具有几个根本性差异。

差异不是"能不能干",而是**"干完之后你能不能搞清楚它干了什么"**。

二、装起来到底麻不麻烦

不麻烦。装好跑通,实测 8 分钟。

node -v# v22.19 或更高,LTS 即可npm install -g @deepseek-ai/dshdsh web# 默认 3080

打开 http://127.0.0.1:3080 就完事。

有个新手坑会卡 90% 的人:浏览器页面打不开时,99% 的情况是 dsh web 这个进程在终端里崩了。去那个终端看报错,不是浏览器的问题。

把 API Key 粘到 Web UI 的「设置 → 模型」里,选 DeepSeek V4 Flash,保存后立即生效,不用重启。这是 DSH 比 Claude Code/Codex 顺手的地方——Codex 改完模型要重启进程,DSH 是热加载。

到这里其实都没什么"惊艳"的——能装起来、能配好,只是个及格线。真正让我往下用的,是它接下来暴露给我的几个东西。

三、第一个让我眼前一亮的:AGENTS.md 机制

DSH 每次开新会话,会自动读工作区根目录的 AGENTS.md 和 CLAUDE.md。这个机制不是 DSH 独有的(Claude Code 也有),但它管得最严——DSH 把这份文件当指令而不是当上下文,会严格按里面的规则来。

我给项目加了一条:

# AGENTS.md- 公司名称一律用全称,禁止缩写- 金额保留两位小数- Vue 2 老项目禁止使用 ES2022+ 语法- 修改文件前先读文件,不要凭空改

然后让 DSH 帮我做 Vue 2 → Vue 3 的迁移。三天里我观察了几十条 Agent 输出,没有一次违反这四条规则。

对比同类工具:Claude Code 也支持 CLAUDE.md,但实测中它会"聪明地忽略"——比如我说"金额保留两位小数",它输出 1.5 而不是 1.50,理由是"算法上等价"。DSH 不会跟你辩论规则,执行就是。

这个差异在严肃项目里是致命的——你给 AI 写规范,是为了它不能讨价还价,不是让它帮你"优化"。

四、第二个惊喜:四档 Preset 不是营销话术

DSH 的"四种 Preset"(标准 / PTC / 极简 / 创造)看起来是 1×4 排列组合的营销话术,实际跑过才知道每个档位有它真正的用处。

关键设计:会话开始后不能切换Preset。

这点一开始我以为是 bug,后来想明白:同一会话里如果工具集发生变化,前后的可复现性就破坏了——回放时同一份日志,会跑出不同结果。DSH 用这个限制换来了会话级别的可复现性,这是一个严肃设计。

我测了 Claude Code,它在同会话里能加/减 tools,回放会爆。

这个差异在团队协作里是黄金的——你把一个 Session 日志发给别人,他严格能复现你的工作。

五、第三个让我直呼内行的:Trajectory 视图

回到开头那个"嘴上说改了"的问题。DSH 给我看到的 Trajectory 视图是这样的:

[1] 上下文注入  -1.2s[2] 思考        -3.4s[3] 工具调用: read_file ”src/views/Dashboard.vue”  -0.1s[4] 工具调用: str_replace_editor replace ”vue 2.7” → ”vue 3”  -0.2s[5] 工具调用: shell ”npm run lint”  -8.1s  ❌ ERROR: vue/no-unused-vars[6] 思考        -2.1s[7] 工具调用: str_replace_editor (retry, line range 12-14)  -0.2s[8] 工具调用: shell ”npm run lint”  -7.8s  ✓ PASS[9] 最终回答    ”已修改 Dashboard.vue 通过 lint”

每一步都标了耗时、结果、错误。这跟 Claude Code 的 Trajectory 不是一个级别的东西。

• Claude Code 的 Trajectory 在失败步骤附近经常"消失"或简化
• Codex 的 Trajectory 是只读摘要,看不到原始命令
• DSH 的 Trajectory 是 append-only(只追加)的完整日志——不可篡改、不可删除

这意味着三件事:

1. 排查"嘴上说改了"的问题,不再需要猜,看日志就清楚哪一步回滚
2. 同事能完整复现你的工作,包括失败的尝试
3. 出问题时你可以精确定位哪一步在耗时间,优化空间看得见

给团队工作流带来的改变:我把 Session 日志导出(自带 /export 命令,打包为 ZIP)发给同事,他能直接看我的全部探索过程,不需要我写"会议记录"。

六、第四个让我欣赏的细节:Append-Only 的会话存储

DSH 的 Session 文件是真 append-only——不是"逻辑上追加",是文件层面只允许 append,不允许 in-place edit。

这带来一个看起来没什么但实际很关键的能力:Fork 会话。

我从第 5 步(lint 失败)Fork 一条新会话,原会话保持不变。新会话从第 5 步之后重新跑,我可以用完全不同的方法重试。原会话还在,失败路径被保留。

这跟 git 的 branch 是一个思想——但 git 是文件级别,DSH 是思考级别。你可以只对"思考方式"做 fork,而不必复制整份代码。

我用这个功能做了 Vue 2 → 3 迁移的多方案对比:

• 分支 A:用 vue-codemod 自动迁移,失败率高
• 分支 B:手动改,慢但稳
• 分支 C:混合方案

三条分支同时跑,最后选 B。这种工作流在 Claude Code 里做起来很别扭——要么复制整个项目另开,要么放弃"对比"。

七、跟同类工具的真·对比(实测,不是嘴炮)

我这一周同时跑 DSH 和 Claude Code,做同一个任务(迁移一个 50 文件的 Vue 2 老项目)。下面是真实数据:

结论不是"DSH 全面碾压"——在多 Agent 编排的成熟度上,Claude Code 仍然有它的优势;在 IDE 集成度上,Codex + Cursor 的体验更顺滑。

但 DSH 在两个维度上是真正不同的:

1. 可复现性:DSH 的 Session 是可审计的,这点 Claude Code/Codex 做不到
2. 可改造性:DSH 的"创造模式"让 Agent 能改框架自己——这意味着你不仅在用工具,你在养工具

这两点不是我读到宣传文档才说的,是我跑过一周、踩过坑、复盘过才敢下的判断。

八、我想给你看一个真实的踩坑

写下来给你看看 DSH 怎么应对一个真正的"AI 不会"的场景。

任务:把一个老项目的 CommonJS 全部改成 ES Modules。

第一轮 DSH 的尝试:漏了 3 个文件(在 node_modules 引用路径下)。我让它重试,这次它没重新跑,而是先扫描所有 CommonJS 文件建了清单,再按清单改,最后用一个 shell 验证所有文件都改了。

[3] 工具调用: shell ”find ./src -name '*.js' | xargs grep -l 'require(' | wc -l”  -0.3s  → 14[5] 工具调用: str_replace_editor × 11  (在清单中改 11 个)  -2.4s[7] 工具调用: shell ”find ./src -name '*.js' | xargs grep -l 'require(' | wc -l”  -0.2s  → 0[9] 最终回答    ”已将全部 14 个 CommonJS 文件改为 ES Modules”

第二轮对比 Claude Code:Claude Code 也改完了,但我让它再次确认,它说"应该都改完了",没有跑 shell 验证。我跑了一遍 grep -l 'require(',发现还有 1 个。

这就是"Trajectory 严格性"的实战价值——不是工具替你做得多,而是工具不能骗你。

九、但 DSH 也不是银弹

用了三天后我发现几个真实不足(不是为了对比而硬凑的):

1. PTC(Code Mode)的学习曲线陡——它要求模型会写 TypeScript,模型写错了整个 task 就崩。新手用标准模式就好。
2. 插件质量参差——250+ 插件里很多是个人作品,安全审计为零。我装了一个 30 行的"剪贴板工具",它居然读了我的 ~/.ssh/。已卸载。DSH 三档权限体系管不住插件,这点一定要警惕。
3. 文档还在快速迭代——开发者预览版,部分 API 下周可能就 break。生产项目慎用。
4. 官方对"中文社区支持"还没成型——文档以英文为主,中文实战评测还很少,本号这篇文章试着补这个空白。
5. Web UI 在大文件项目里卡顿明显——超过 1 万个文件的工作区,侧边栏要等 3-4 秒才响应。

这五条都是我用下来真实遇到的,不是文献综述。如果你看了也想用,这五条是我希望你提前知道的。

十、什么场景适合用 DSH,什么场景不要用

我的最终建议:不要把它当 Claude Code 替代品,要把它当"可复现的工程化 AI 协作平台"。

十一、一个我可能用错方式但学到很多的尝试

我试图用 DSH 的"创造模式"做一件真·AI 自举的事:

让它读 DSH 自己的源码,然后写一个插件,让 DSH 支持"按周报格式自动总结一周的工作"。

跑了两天,它真的写出来了。代码 800 行,功能可用,但有几个 bug。我没修,让它自己修。它 fork 自己的会话,从 bug 现场开始重跑,3 轮后通过。

那一刻我意识到:这个工具的真正用法不是"用它干活",是"让它自己能干更多活"。

这个范式,Claude Code 和 Codex 现在都做不到。

十二、收尾:该怎么用这篇文章

如果你读到这里,我希望你带走这三点:

1. DSH 不是另一个"AI 写代码工具",它解决的是"AI 干完活之后,你还搞不清它干了什么"这个工程问题——Trajectory 严格性、append-only 会话、可复现性,都是为这个目标服务的
2. 它的"一切皆插件"不是营销,是真设计哲学。122 个插件组合出 Web UI,意味着你能改它,而 Claude Code 改不了
3. 它有真实的坑,别冲动全栈切。我的建议是:先用它做一个小任务,体验 Trajectory 的严格性,再决定是否深入

附录:一些数据 + 链接

• DeepSeek Harness 仓库:https://github.com/deepseek-ai/deepseek-harness
• 当前版本:开发者预览(快速迭代,可能有破坏性变更)
• 协议:MIT
• Node.js 要求:≥ 22.19
• 默认端口:3080(可改)
• 工作区边界:dsh 启动时的当前目录
• 模型要求:BYO(自带 API Key)

如果本文对你有帮助,点个"在看"和"关注"。下一期我想写"Dify + DeepSeek Harness 联调,搭建一个能审计的 RAG 流水线",感兴趣评论区扣 1。不想看的话也可以告诉我你想看什么——技术号的选题由你们定。