DeepSeek Harness 新手常见 10 问：一次讲清所有入门坑（FAQ 速查）

这个系列写了十几篇，评论区和私信里翻来覆去就是那十几个问题：怎么装？配什么 Key？为什么界面这么简陋？Windows 能不能用？会不会乱删我的文件？这篇把所有高频问题汇总成一份 FAQ 速查表，新手先看这一篇，能少走 90% 的弯路。

---

Q1：DeepSeek Harness 到底是什么？和 Claude Code 是同类吗？

一句话：模型 + Harness = Agent。 模型负责思考，Harness 负责动手（调工具、跑命令、读写文件、管理上下文）。

它和 Claude Code / Codex 不在同一层：后两者是开箱即用的成品智能体（闭源），Harness 是开源的 Agent 运行框架——模型、工具、沙箱、循环全部插件化（MIT 协议），你可以自由组装甚至重写。想「直接用」选成品，想「自己造」选 Harness。

Q2：安装需要几步？要配什么环境？

最少一步：

npx @deepseek-ai/dsh web

自动拉包、起 Web UI、默认监听 127.0.0.1:3080。唯一前置依赖是 Node.js（建议 LTS）。想深入研究就克隆源码 pnpm install && pnpm run build。

Q3：界面怎么这么简陋？是不是没做完？

是故意的。 开发者预览版的界面只有一个对话框，没有功能面板。Harness 的定位是给「构建 Agent 的人」用的框架，不是给普通用户的成品。那些智能体工具全藏在内置插件里。官方明说预览版会有破坏性变更——把它当毛坯房，别当精装房。

Q4：必须用 DeepSeek 的模型吗？能接 Claude / GPT 吗？

不必须，模型无关。 Harness 的模型层是插件（ctx.llm 接口），官方自带两个适配器：dsh-llm-deepseek（自家模型）和 dsh-llm-pi-ai（协议转换，支持近 40 家厂商，含 Anthropic、OpenAI、Google）。你甚至可以让它调用本机装好的 Claude Code 当「外包工人」（该开关默认关闭）。

Q5：四大模式（标准 / PTC / 极简 / 创造）我该用哪个？

你的场景	选哪个
日常开发搭子，功能要全	标准模式
步骤明确的批量任务，想省 Token	PTC 模式
跑基准测试 / 验证模型裸能力	极简模式（只有 2 个工具）
想让 Agent 检查并改造自身插件	创造模式（高级玩法）

不确定就用标准模式。

Q6：Windows 能跑吗？

能跑，但沙箱不稳。Harness 的文件沙箱在 Linux 用内核级 Landlock（最可靠），macOS 有专门实现，Windows 原生支持不稳——官方建议 Windows 走 WSL2。直接跑在 PowerShell 里能用，但隔离保护会打折扣。

Q7：它会乱删我的文件吗？怎么保证安全？

三道防线，缺一不可：

1. 文件沙箱：默认「工作区可写、敏感操作询问」，但注意——沙箱只管文件，不管网络和进程；
2. 操作审批：危险命令默认要你确认；
3. Python SDK 默认是 danger-full-access：名字就叫「危险全访问」，官方明确要求只能在可丢弃的 checkout 或容器里跑。

生产部署铁律：给副本目录不给真实数据、容器隔离、网络出口加白名单。

Q8：DeepSWE 62.7% 是什么？我自己能复现吗？

DeepSWE 是「AI 修真实 GitHub 仓库 bug」的编程基准。V4-Pro 预览版 12.8%，正式版 62.7%，就是靠后训练把分数拉上去的。

官方跑分就是在 Harness 极简模式下测的，复现链路已开源：拉源码 → 配 V4-Flash → 每个 issue 独立 workspace 跑 → 用仓库自带测试判分。注意你自己复现分数会略低于官方（官方用隐藏测试用例），重点不是追平官方，而是建立自己的基线，量化每次配置改动的影响。

Q9：API 涨价了，怎么用 Harness 最省钱？

峰谷定价 8 月 17 日生效，三板斧：

1. 复用 session_id：缓存命中率能到 90%+，频繁开新会话等于每次清零缓存；
2. 重活挪到低谷时段：每天 20 小时半价，批量评测、CI、夜间任务全挪过去；
3. 用 PTC 模式：把多轮工具调用打包成一段代码执行，模型往返次数大降。

三个叠加，同一个任务的成本能差 8-10 倍。便宜从来不是标价低，是跑法对。

Q10：现在值得投入时间学吗？生态成熟了吗？

看你要什么：

• 要稳定生产工具：再等等。预览版有破坏性变更，插件 API 还会动；
• 要占生态位：现在就是窗口期。#dsh-plugin topic 几天破千仓库但远未饱和，通讯类、评测类、可视化类插件都缺人；
• 要研究 Agent 架构：马上学。这是目前唯一把「Agent Loop 本身」都做成可替换插件的开源框架，架构参考价值极高。

参考 Koishi 的先例：同一套 Cordis 内核，在聊天机器人领域已经验证过一次「插件生态能成」。这次底层多了条 Agent Loop，天花板只会更高。

---

附：这个系列的全部文章索引

篇	主题
01	快速上手 + 四大模式
02	Cordis 架构拆解（一切皆插件）
03	vs Claude Code / Codex 横评
04	Python SDK 程序化驱动
05	手写插件入门
06	缓存机制与峰谷定价省钱
07	PTC 模式深挖
08	沙箱与安全专题
09	复现 DeepSWE 基准
10	dsh-plugin 生态盘点
11	15 天 3 连发的发布节奏解读
12	Agent 标准战争：开源 vs 闭源
13	新手常见 10 问 FAQ 速查（本文）

有新问题评论区见，后续会持续更新这份 FAQ。

---

附二：进阶阅读清单（按水平分层）

FAQ 只解决「入门」，想深入还需要系统化阅读。按你的水平选：

入门 → 进阶（看完能自己搭 Agent）

1. 官方 README + BENCHMARK.md：搞清楚跑分怎么来的，顺便学会复现；
2. 本系列 04 篇：Python SDK 最小示例跑通一个真实任务；
3. 本系列 05 篇：写一个自己的工具插件——这是从「用户」变「建设者」的分水岭。

进阶 → 深度（看完能理解架构）

1. 官方 Cordis primer 文档：插件组合语法、服务/事件模型；
2. 本系列 02 篇：ctx 键、可逆副作用、遮蔽算法的完整讲解；
3. 读 packages/core/agent-loop 源码：理解一轮 Agent 循环到底发生了什么。

深度 → 专家（能写论文级的对比分析）

1. Cordis 设计论文《A Programming Paradigm for Spatiotemporal Composability》；
2. 自己复现 DeepSWE 基准并和官方分数对比（本系列 09 篇）；
3. 尝试写一个「组合配方」插件（多个能力打包成一个 profile）。

学习路径图

第 1 周：跑起来 + 跑通官方示例        （01/04 篇 + README）
第 2 周：写第一个插件 + 过审查清单     （05/10 篇）
第 3 周：理解架构 + 读核心包源码       （02 篇 + packages/）
第 4 周：复现基准 + 建立团队基线       （09 篇 + BENCHMARK.md）

四周围下来，你已经不是「用 Agent」的人，而是「造 Agent」的人——这中间差的，不是模型，是这套开源框架给你的操作权限。

---

附三：三个常见误区的澄清

误区一：「Harness 太简陋，说明 DeepSeek 不用心」

恰恰相反，这是故意的取舍。Harness 的定位是「给造 Agent 的人用的框架」，不是「给普通人用的成品」。就像 Android 开源给厂商、苹果精装给用户——DeepSeek 选择做前者。你在界面上的「简陋感」，本质是「组装权」的具象化：没人替你决定该挂什么插件，因为这本来就是你的决定。

误区二：「模型无关 = 不推荐 DeepSeek 自己的模型」

官方跑分（DeepSWE 62.7%）是用自家 V4-Pro 在 Harness 极简模式下测的，等于用行动告诉你：「我们对自己的模型最了解，默认推荐组合就是这个」。模型无关的意思是「你不必被绑定」，而不是「我们的模型不行」。你可以自由换模型，但默认组合的性价比，是官方用跑分背书过的。

误区三：「开源 = 免费 = 没有商业模式，会死掉」

开源项目的商业模式早就不靠卖软件了：Red Hat 卖支持、MongoDB 卖托管、K8s 背后是云厂商的生意。DeepSeek 的算盘更直接——框架免费吸引生态，API 峰谷定价收重度使用者的钱。框架越流行，用 API 的人越多；用 API 的人越多，生态越大。这是「开源抢定义权、算力收生态税」的经典打法，不赚钱才怪。

---

附四：快速自查表（你该不该用 Harness）

回答下面五个问题，四个以上「是」，Harness 值得认真投入：

1. 我需要审计 Agent 的每一步操作吗？（安全/合规团队：是）
2. 我需要换着用多家模型吗？（不想被单家绑定：是）
3. 我需要自己拼装 Agent 能力（工具、技能、子智能体）吗？（平台方/产品方：是）
4. 我需要复现官方跑分、建立自己的基准基线吗？（做评测/调优：是）
5. 我能接受预览版破坏性变更、愿意跟着迭代吗？（有技术余量：是）

三个以上「否」，Claude Code / Codex 这类成品对你更友好——这不丢人，工具适配场景，不是场景迁就工具。

---

附五：术语速查表（一页看懂 Harness 黑话）

术语	一句话解释
Harness / dsh	DeepSeek 开源的 Agent 运行框架，「模型 + Harness = Agent」
Cordis	底层插件元框架，负责依赖注入、作用域服务、可逆副作用
ctx	共享上下文，插件向它贡献服务、监听事件
Profile	具名组装，决定一个 Agent 装哪些插件（标准/PTC/极简/创造）
Bundle	分层：dsh-base 地基、dsh-web-app 界面、dsh-headless 无服务器
cordis.patch.yml	用户补丁，不改源码地选择/替换/扩展能力
ctx.tools	工具注册表，作用域化、可遮蔽
ctx.llm	模型调用接口，适配器可换（DeepSeek / Pi-AI / 40 家厂商）
SessionEvent	仅追加的会话日志，权威、可审计
Session ID	会话标识，复用即保留 Bash 进程与环境
PTC	程序化工具调用，模型生成代码批量编排工具
极简模式	只留 shell + 文件编辑两个工具，官方跑分配置
创造模式	Agent 能检查/挂载/卸载插件，改造自身运行时
danger-full-access	Python SDK 默认沙箱级别，危险全访问
ACP	Agent Client Protocol，跨客户端驱动 Agent 的协议
MCP	Model Context Protocol，工具接入的事实标准
dsh-plugin	官方插件仓库 topic，生态索引入口
DeepSWE	编程智能体基准，V4-Pro 正式版 62.7%
峰谷定价	DeepSeek API 分时段计价，低谷半价
缓存命中	前缀缓存复用，命中价极低，Agent 长任务省钱关键

这份表配合正文使用：遇到看不懂的术语，先回这张表查一眼，再回到对应章节细读，效率最高。

最后说一句

DeepSeek Harness 目前还是开发者预览版，界面简陋、API 会变、文档在快速补齐——但它的底层架构（一切皆插件、可逆副作用、Agent Loop 可替换）是经过认真设计的。你现在花在它身上的每一小时，都是在为一个可能定义未来十年 Agent 运行时的标准投资。

如果这份 FAQ 帮到了你，欢迎收藏转发；如果还有没覆盖到的问题，评论区留言，我会持续更新。也欢迎关注我的专栏，Harness 系列的每一篇更新都会第一时间同步在那里——从入门、架构、横评、SDK 实战到插件开发与生态观察，十三篇连起来读，就是一套完整的 DeepSeek Harness 学习地图。

附六：高频追问 5 条

追问 1：它和 Coze / Dify 这类 Agent 平台有什么区别？

平台给你的是「成品工作台」：拖拽编排、预置工具、托管运行，上手快但边界由平台定。Harness 给你的是「运行框架」：模型、工具、沙箱、循环全部插件化，自己拼装、自己部署、自己审计。一句话——平台是租精装房，Harness 是买毛坯房加一套管线，改造自由度完全不同。

追问 2：MIT 协议，我能拿去商用吗？

能。MIT 允许商用、闭源、修改再分发，只需保留版权声明。但注意三点：一是框架本身免费，不等于你调用的模型 API 免费；二是预览版 API 会变，商业项目要锁定版本并做回归测试；三是如果产品重度依赖 Harness，要提前评估自托管与升级成本，别把「开源免费」误当成「零维护成本」。

追问 3：生产环境到底敢不敢上？

分场景。内部工具、批量评测、可回滚的研发流程，现在就可以小步上；直接面向 C 端、涉及真实资金或敏感数据的业务，建议再等正式版。预览版最大的风险不是「会出错」，而是「API 会变」。上生产的底线是：容器隔离、副本目录、网络白名单、锁定依赖版本，并且把 Harness 当「可替换组件」而不是不可动摇的地基。

追问 4：社区现在活跃吗？会不会很快凉？

活跃且处于红利期。#dsh-plugin topic 几天破千仓库，官方 15 天连发 3 个版本，迭代节奏很快。但它仍处生态早期：文档在补齐、插件品类不全、破坏性变更会劝退一部分人。判断健康度别只看 star 数，去看 issue 响应速度和插件仓库更新频率——这两项目前都算健康。

追问 5：后续学习路线怎么走？

按四周推进：第一周跑通官方示例，建立自己的任务基线；第二周写第一个工具插件，从「用户」变「建设者」；第三周读 agent-loop 核心源码，搞懂一轮循环到底发生了什么；第四周复现 DeepSWE 基准，把「会跑」变成「会评」。之后按兴趣分流：做产品就钻插件分发与 profile 组合，做研究就钻基准与可逆副作用，做工程就钻沙箱、ACP/MCP 接入与 CI 集成。

---

标签：#DeepSeek #Harness #AI Agent #FAQ #新手入门