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

DeepSeek Harness 新手常见 10 问一次讲清所有入门坑FAQ 速查这个系列写了十几篇评论区和私信里翻来覆去就是那十几个问题怎么装配什么 Key为什么界面这么简陋Windows 能不能用会不会乱删我的文件这篇把所有高频问题汇总成一份 FAQ 速查表新手先看这一篇能少走 90% 的弯路。Q1DeepSeek 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 / 极简 / 创造我该用哪个你的场景选哪个日常开发搭子功能要全标准模式步骤明确的批量任务想省 TokenPTC 模式跑基准测试 / 验证模型裸能力极简模式只有 2 个工具想让 Agent 检查并改造自身插件创造模式高级玩法不确定就用标准模式。Q6Windows 能跑吗能跑但沙箱不稳。Harness 的文件沙箱在 Linux 用内核级 Landlock最可靠macOS 有专门实现Windows 原生支持不稳——官方建议 Windows 走 WSL2。直接跑在 PowerShell 里能用但隔离保护会打折扣。Q7它会乱删我的文件吗怎么保证安全三道防线缺一不可文件沙箱默认「工作区可写、敏感操作询问」但注意——沙箱只管文件不管网络和进程操作审批危险命令默认要你确认Python SDK 默认是danger-full-access名字就叫「危险全访问」官方明确要求只能在可丢弃的 checkout 或容器里跑。生产部署铁律给副本目录不给真实数据、容器隔离、网络出口加白名单。Q8DeepSWE 62.7% 是什么我自己能复现吗DeepSWE 是「AI 修真实 GitHub 仓库 bug」的编程基准。V4-Pro 预览版 12.8%正式版 62.7%就是靠后训练把分数拉上去的。官方跑分就是在Harness 极简模式下测的复现链路已开源拉源码 → 配 V4-Flash → 每个 issue 独立 workspace 跑 → 用仓库自带测试判分。注意你自己复现分数会略低于官方官方用隐藏测试用例重点不是追平官方而是建立自己的基线量化每次配置改动的影响。Q9API 涨价了怎么用 Harness 最省钱峰谷定价 8 月 17 日生效三板斧复用 session_id缓存命中率能到 90%频繁开新会话等于每次清零缓存重活挪到低谷时段每天 20 小时半价批量评测、CI、夜间任务全挪过去用 PTC 模式把多轮工具调用打包成一段代码执行模型往返次数大降。三个叠加同一个任务的成本能差 8-10 倍。便宜从来不是标价低是跑法对。Q10现在值得投入时间学吗生态成熟了吗看你要什么要稳定生产工具再等等。预览版有破坏性变更插件 API 还会动要占生态位现在就是窗口期。#dsh-plugintopic 几天破千仓库但远未饱和通讯类、评测类、可视化类插件都缺人要研究 Agent 架构马上学。这是目前唯一把「Agent Loop 本身」都做成可替换插件的开源框架架构参考价值极高。参考 Koishi 的先例同一套 Cordis 内核在聊天机器人领域已经验证过一次「插件生态能成」。这次底层多了条 Agent Loop天花板只会更高。附这个系列的全部文章索引篇主题01快速上手 四大模式02Cordis 架构拆解一切皆插件03vs Claude Code / Codex 横评04Python SDK 程序化驱动05手写插件入门06缓存机制与峰谷定价省钱07PTC 模式深挖08沙箱与安全专题09复现 DeepSWE 基准10dsh-plugin 生态盘点1115 天 3 连发的发布节奏解读12Agent 标准战争开源 vs 闭源13新手常见 10 问 FAQ 速查本文有新问题评论区见后续会持续更新这份 FAQ。附二进阶阅读清单按水平分层FAQ 只解决「入门」想深入还需要系统化阅读。按你的水平选入门 → 进阶看完能自己搭 Agent官方 README BENCHMARK.md搞清楚跑分怎么来的顺便学会复现本系列 04 篇Python SDK 最小示例跑通一个真实任务本系列 05 篇写一个自己的工具插件——这是从「用户」变「建设者」的分水岭。进阶 → 深度看完能理解架构官方 Cordis primer 文档插件组合语法、服务/事件模型本系列 02 篇ctx键、可逆副作用、遮蔽算法的完整讲解读packages/core/agent-loop源码理解一轮 Agent 循环到底发生了什么。深度 → 专家能写论文级的对比分析Cordis 设计论文《A Programming Paradigm for Spatiotemporal Composability》自己复现 DeepSWE 基准并和官方分数对比本系列 09 篇尝试写一个「组合配方」插件多个能力打包成一个 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 值得认真投入我需要审计Agent 的每一步操作吗安全/合规团队是我需要换着用多家模型吗不想被单家绑定是我需要自己拼装Agent 能力工具、技能、子智能体吗平台方/产品方是我需要复现官方跑分、建立自己的基准基线吗做评测/调优是我能接受预览版破坏性变更、愿意跟着迭代吗有技术余量是三个以上「否」Claude Code / Codex 这类成品对你更友好——这不丢人工具适配场景不是场景迁就工具。附五术语速查表一页看懂 Harness 黑话术语一句话解释Harness / dshDeepSeek 开源的 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-accessPython SDK 默认沙箱级别危险全访问ACPAgent Client Protocol跨客户端驱动 Agent 的协议MCPModel 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 是买毛坯房加一套管线改造自由度完全不同。追问 2MIT 协议我能拿去商用吗能。MIT 允许商用、闭源、修改再分发只需保留版权声明。但注意三点一是框架本身免费不等于你调用的模型 API 免费二是预览版 API 会变商业项目要锁定版本并做回归测试三是如果产品重度依赖 Harness要提前评估自托管与升级成本别把「开源免费」误当成「零维护成本」。追问 3生产环境到底敢不敢上分场景。内部工具、批量评测、可回滚的研发流程现在就可以小步上直接面向 C 端、涉及真实资金或敏感数据的业务建议再等正式版。预览版最大的风险不是「会出错」而是「API 会变」。上生产的底线是容器隔离、副本目录、网络白名单、锁定依赖版本并且把 Harness 当「可替换组件」而不是不可动摇的地基。追问 4社区现在活跃吗会不会很快凉活跃且处于红利期。#dsh-plugintopic 几天破千仓库官方 15 天连发 3 个版本迭代节奏很快。但它仍处生态早期文档在补齐、插件品类不全、破坏性变更会劝退一部分人。判断健康度别只看 star 数去看 issue 响应速度和插件仓库更新频率——这两项目前都算健康。追问 5后续学习路线怎么走按四周推进第一周跑通官方示例建立自己的任务基线第二周写第一个工具插件从「用户」变「建设者」第三周读agent-loop核心源码搞懂一轮循环到底发生了什么第四周复现 DeepSWE 基准把「会跑」变成「会评」。之后按兴趣分流做产品就钻插件分发与 profile 组合做研究就钻基准与可逆副作用做工程就钻沙箱、ACP/MCP 接入与 CI 集成。标签#DeepSeek #Harness #AI Agent #FAQ #新手入门