2026年DeepSeekHarness白皮书-从 0 到 1 玩转 DeepSeek Harness 的新手百科全书

闭环"第4页**验收**：能给dsh生态贡献一个小5.**谁该用**：要深度定制/玩生态/跑CI**①dsh是什么？——它是"Agent的），界面、改行为）。对比之下，ClaudeCode更像"一辆整车"——很好开，但你想**②为什么需要"harness"这个词？——它是"套在模型外跑命令、改代码、多轮循环），外面需要一层工程：会话管理、工具调用、上下文**③为什么2026年才开源？——因为Agent进入"）；事变成开放生态**——像当年Android开源改变手flowchartflowchartTBsubgraphT["tools：写文件/终端/搜索/技能"]S["session：会话持久化"]e×闭源×闭源×闭源×闭源)+时时时时包无无××××✅✅✅✅✅✅✅✅态化通俗文字版：每家是什么、适合谁、和ds**ClaudeCode（Anthropic）**：目前最成熟的终端编码助手。开箱即态成熟——**适合想马上干活的人**。缺点：闭源、绑定Claude模型、定制），**OpenCode**：开源、终端、可配任意模型——和dsh），IDE里**。dsh是独立运行时，可以在任**Devin**：云端工程师——你给它任务，它在云上干活。优势是托管**Aider**：老牌开源、Git优先、轻量。适合"只想让AI帮改代码"**QwenCode/GLMCLI/GrokCLI**：各家模型的终端agent），**任务**：让Agent在仓库里"找到所有调用某个函数的败成以下是我们**真实开发dsh生态**时的对优**⏸暂时观望**：•重度依赖某模型独有能力（如Clau不是。dsh是运行时/框架，模型通过`llm`插方插件生态"（有官方后端bundle与**Q3：没写过TypeScript），**下一章**：[第2章：五分钟快速1.**一句话测试**：向不懂技术的人解释"d4.**架构测试**：画出"profile•[Node版本红线(≥22.19）](#node-版本红线2219)Node版本红线(≥22.19）v24.15）也可能触发`install-lefthookfailed`——若遇此错，pi(/deepseek-ai/deepseek-harness（[#380](/deepseek-ai/d坑上>![dsh模型选择与推理档位](./assets/d**推理等级**（思考模式三档，202好划只接受`off`（关闭思考，最快）/`high`/`max`三档，`l你好！我是DeepSeek驱动的AI编程助手，可以帮你写代型）：dsh的侧边栏默认是空的——安装社区插件`dsh-better-sideba##1.找到你的webprofile#Windows:%USERPROFILE%\.dsh\pr"dsh-better-sidebar":"link:C:\\path\\to\\DSH-bett%USERPROFILE%\.dsh\profiles\![dshGit面板（better-sidebar插件）](./asagent-default-model:agent-default-model:model:deepseek-v4-flashTUI模式（需先安装tui插件，官**下一章**：[第3章：profile>4.**推理档位实验**：把settings.yaml的`reasoningEffo），5.**排障演练**：模拟"端口被占"（先起一个占用），`conversationEvents`、`ctx5.**rc阶段三大坑**：依赖版本用`^0.1.0-rc.6`线、`nexdsh用**profile**表示"一种可启动的形态"。官）：的`cordis.patch.yml`→用户级`~/.dsh/cordis.patch了四种Agent预设（源码在官方仓库`apps/cli/config/agent-presets/``agent.cordis.yml`每种预设默码组合多轮工具调用（[#1052](/deepseek-ai/d）：工具调用"），官方英文页面对应**Code扩写出自社区详解（[cnblogs指南](/sing1ee/p/224与源码实现完全吻合。机制与收益详见第8章{{"dependencies":{"dsh-be}**②`cordis.patch.y），只能做界面和交互）。两者通过cordis服务桥明`dsh.client`、不写`exports["./cli），程/服务behaviorgoesondocum**怎么用（以`agent/request`为例）**——在插件的`appl坑—突,—\path\to\plugin—坑jsdom无法直接跑client2.**理解题**：解释"host半"和"client半"分别4.**动手题**：假设你要挂载一个名为`dsh-my-widget`的插件，写出`package.和`cordis.patch.yml`各需要加5.**动手题**：在`cordis.patch），），`insert`是"在插件链中插入一个新插件"。patch文件基于cor），），个？**`agent/request`是"改模型请求配置"每次请求前触发，返回新配置。`conversation子（tool/call、turn/start等用于监听或注入事件流。想改请求参数用前者，想监听对话**Q6：为什么我的插件装上去没反应？怎三步排查：①确认`pnpminstall`无报错且`node_modules`里`cordis.patch.yml`的id/name拼写正确；**下一章**：[第4章：插件开发实战2.**验证三层**：纯函数单测（决策正确）→waterfall3.**`agent/request`waterfall**：每次模型请5.**开发纪律**：先找扩展点（90%省•[4.4插件主体：接入`agen把简单轮次的`reasoning_effort`从`high`降到SIMPLE_TOOL_RE=/^(fs|bash|terminal|read|write|grep|glob|edipwd)/iconstHEAVY_ARGS=800exportrecentCalls.filter(c=>SIMPLE_TOOL_RE.test(c.n**为什么拆成纯函数**：决策逻辑与dsh运行时解耦——单元测试4.4插件主体：接入`agent/request`wareturnout.reverse()}exprecentToolCalls(payload.agent)selected:config.baseline,allowDowngrade:config.aconfig.allowUpgrade,})console.log(`[speed-plugin2.**waterfall语义**：监听者的**返回值**传给下一个监听者/最配套模板的[`tests/plugin.spec.ts`](../examples/plugin-plugin]agent/request:calls=[{"name":"writ路完整工作。**waterfall和`tools/result`。讨论中的命令基于特脚本和事件清单为准，不要把固定的事件数量当成跨>2.**逻辑抽纯函数**：决策/计算逻辑与dsh解3.**边界和实机都要验证**：契约测试证明`1.**理解题**：不看原文，说出这个提2.**理解题**：解释为什么`decideEffort`要设计成纯函数而不是直接在3.**动手题**：给`decideEffort`写一个新的测试用例：当`rec行），5.**动手题**：假设你要写一个类似的插），seed是当前waterfall链上游累积的请求配置，通常包含`p**Q3：我的插件需要在每个工具调用后都触发决策，`agent/request够。`agent/request`在每次模型请求前触发（包括工具调用后的下一轮请求）。监听者里读取最近的工具调用历史（从`payload.agent.session.events`里倒序找`t），几种可能：①用户的`settings.yam）；**Q5：我想给插件加一个用户可配置的开关（设置），用`settings`服务注册一个命名空间（如`speed-plugin`），baseline等）。dsh的设置页会自动渲染表单，用户修改后通过），reverse后恢复时间正序（最旧的在前和实），**这是dsh生态最被低估的优势**。DeepS重复/相似的输入token按缓存价计费中**实际意义**：一个长会话Agent任务，绝大部分输入token走缓存工具链任务、2.4M输入token"的成本远低于按未命中价计算的预期**。对高）：dsh--profileheadless"审查bugg），）：是否该删取决于业务"——这是agent工程层"会思考"dsh--profileheadless"为user值、异常、示例、边界情况"#实测：423行），）：dsh--profileheadless"把legacy_orders.p**亮点**（实测）：dsh的工程意识——识别重复代码合并沙箱下tempfile权限问题主动换方2.**给上下文**：一句话说清背景（文件在哪3.**一次一个任务**：复杂目标拆），靠4.对比输出，感受dsh的"完成度"——它是不是只给了个大概？验收标准写清2.**提示词对比**：对同一任务写两个版本提示词—4.**多步任务**：设计一个跨场景任务（如"读代码→生成文档），？（•**Q：dsh只是编码助手吗？**不是—）；第40页——工具执行有沙箱，但**内容责任在使用者*第41页段第42页benchmark所走网关）。工具链降档叙事在网关环境#坑1线23第43页45jsdom报678验证点：off）：2.**什么harness**？框架不同分数差dsh的`agent/request`waterfall让模型跑分可复现——这是第44页），简单轮次用low档（思考token减1.**理解题**：不看原文，说出d2.**理解题**：解释`low`/`high`/`max`三个推理），4.**动手题**：把`~/.dsh/settings.yaml`的`reasoni跑同一个简单任务，对比耗时差异。再改回`high`，跑一个复杂推理任），第45页）；**Q2：示例提速插件真的能提速多少？有没有实提速收益取决于任务类型。简单任务（1-3步）dsh本来就快，插件效果不明显。**长工具链**Q3：我把推理档位设为`low`，模型质量会下取决于任务。简单文件操作、批量处理、确定性任务用`low`质量几乎无差别。**Q4：坑#6说的"contextcache命中"是什么？怎么判DeepSeekAPI会对重复/相似的上下文做缓存，命中时首token时间大幅缩短。判断方法：**Q6：我想做性能基准测试（benchmark有什么）；次运行取中位数（单次波动大）。记录：墙**下一章**：[第7章：生态与资源](.第46页写教程/博客——社区已自发形成"报告-复现-根因-修复分支"的贡献模板章完整拆解）、本白皮书——发现插件搜`topic:dsh第47页板——[#341](/deepseek-ai/deepseek-harness/discussions/3[#371](/deepseek-ai/deepseek-harness/discussions/371)、[#(/deepseek-ai/deepseek-harness/discussions/775)反复呼吁4.**修复分支**：fork后提第48页ai/deepseek-harness/#529/deepseek-ai/deepseek/deepseek-ai/deepseek-harness/discussions/446见/deepseek-ai/deepseek第49页/deepseek-ai/deepseek/deepseek-ai/deepseek-harness/discussions/525《记忆体》提案），m/deepseek-ai/deepseek-harness/discussions/1052经），m/deepseek-ai/deepseek-harness/discussions/1889）），/三平台沙箱/持久调度——40分钟任务第39分钟崩溃不丢状态4.**写内容**：教程/测评/避坑文（官方鼓励与本白皮书互相例**①`package.json`加依赖**（`~/.dsh/profiles/web/p{{"dependencies":{"dsh-be}**②`cordis.patch.y**②`cordis.patch.y**④验证效果**：发一个"创建3个文件"的任务，观察日志是否出现`或/search?q=dsh-plugin把7.4节的"四步走"展开为**可操作的盖等级3.5节"常见坑"接）；可引用内容（单条回复会沉底，写成章节/FAQ才能持续）；dsh是2026-08-13才开源的项目——**生态的每一天都是"早期"1.**理解题**：不看原文，说出dsh生4.**动手题**：按本章7.6节的步骤，完整挂载`DSH-better-sidebar`或按第4），放在你自己的GitHub仓库，作为独立的dsh-plugin生态项目。官方鼓励这种方没有官方格式要求。建议包含安装步骤、代码示例、实机截图/日志。可参考**Q4：生态零日是什么意思？为什么说是"**Q6：我想做dsh生态项目，但不一样。Windows用双反斜杠转义（`link:C:\\path\\to），参考7.10节3个原则：带环境信息、带复现步骤、先搜索避免重复。功能建议说5.**长对话自动压缩（compaction）**：检测）；）；）：>模型实际可调用的工具名是**简短动词**（实测记录，来自dshweb会话与agent/**工具结果与产物追踪**（重要概念工具的返回里带有`locations上下文注入@deepseek-ai/dsh-system-prompt）：（[#1052](/deepseek-ai/d）；下模型**生成一段TypeScript程序**，在单次程序内编排多轮工具调`Promise.all`并行整段程序灌行**执行机制**：程序交给`@deepseek-ai/dsh-code-runtime-worker-th）；长对话会撑爆上下文。dsh的`compaction`插件（如`compaction-b•检测上下文溢出（`agent/request-error`的`CONT1.**工具名是简短动词**（read/write/grep/3.**长对话自动压缩**——不必手尤其waterfall事件监听器（`tools/execute`、`approval/request`、`fs/write-int），DEEPSEEK_BASE_URL=:8000/v1\DEEPSEEK_API_KEY=生命周期`session/created→…→tools/pre-execute(wf)→tools/etools/post-execute(wf)→t**从源码跑的三点提醒**（#462作者实测踩坑）：sparseclo）；+web-frontenddist三层构建缺一不可；`mock:llm`参数前不要多传`--`（会被(/deepseek-ai/deepseek-harne[#581](/de(/deepseek-ai/deepseek-harnes型常把内层`bash.descriptio`ToolArgsError`不带工具名，模型无法定位错在哪个工具→死循环重试（附）；**坑2：流式下工具调用被抹空名**（[#725](/deeps修复；[#161](/deepseek-ai/deep[#615](/de(/deepseek-ai/deepseek-harne**坑3：`run_code`内调用交互式工具被"吞"*ai/deepseek-harness/discus`run_code`程序内调用交互式工具（如`ask_user_question`）4ms就返回空；异步结果约12s后回执行模型的问题（应支持异步工具回调或返回p），4.**动手题**：在`dshweb`里进行一个长对话（20+），5.**思考题**：为什么"重要信息要写进提示词"6.**思考题**：本章8.5节说"dsh的工具执行是。`str_replace_editor`是内部包名，模型调用时可能显示为`edit`。功能一样：文件中的某段文本。工具结果里的`locations`schema）。`compaction/*`负责"长对话压缩"（检测溢出**Q5：安全模型里"沙箱"和"交互审沙箱（`sandbox/*`）隔离命令执行环境（如p互审批（`interaction/*`）是"危险操作前要求用户确认"（如删除文件、执行**Q6：我想给dsh加一个新工具（比如"查数据库"），两种方式：①写一个host插件，用`c）；/条件执行——适合数据拉取→清洗→报表→校验）：）：**MCP（ModelContextPr）：**对新手**：子代理是"高阶武器"——先用好单Agent，理解配置，社区已在讨论区反馈（[#118](/deepseekharness/discussions/118)评论区，对比Claude不同模型能力时，目前只能整体切换父Agent的模型配置，或拆成独立会话分）：）：生态正在快速生长——**现在是进场搭积木的好表，每服务器独立进程）、`command`/`args`（启动命令与参数）、`env`（环境并行子代理通过`packages/subagent/*`提供。以下准件以下是一个**确定性工作流**的`cordis.patch.yml`片段，模拟"数据销#坑12345入具），行阶段二没跑通→阶段三并行放大问题；阶段三没跑通→阶段四YAML写出来段一到阶段二之间，先读第8章8.1节能力包地图——确认需求是否已内置，避免为"已有能2.**理解题**：解释"工作流"和"多轮？（？（4.**动手题**：设计"子代理并行调研"：调研3个模块（src/lib/src/？（MCP是"给Agent插外部工具"的开放协）；己的上下文，不会互相干扰。但多个子代理改同一个文件可能冲突——建议工作流把步骤定义成流程（如cordis.yml），按顺序/条件执对话是"模型自由发挥"。确定性流程适合"必须按固定步骤走"的场景，自由），（以官方changelog为准）①安装`cordis.patch.yml`挂载（参考9.6节）；③配置服务器），3.**dsh的画像**：多步工具链自动编排、有4.**关键启示**：提示词把验收标准写清楚（如"运），），给dsh一份含脏数据的合成JSON（52行：缺失值、类型错误、重复行、异常值3.编写可视化脚本`visualizeread(sales_data.json)→write(clean.py)→bash(pytho![dsh生成的销售额可视化（案例A产物）](**dsh不仅执行了任务，还主动说明了数据处理的权衡与假设**——这是•**测试设计**：覆盖边界（除零/负数/精度），不是"能跑就行"开Agent运行时的主要价值场景。复杂任务建议：提示词把**验收标准写清楚**），1.**理解题**：不看原文，说出案例A），3.**动手题**：设计一个类似的"数据质量分析），峰副作用）。这个行为对"agent工程层"的设计有什么启示？模型只取决于任务复杂度和模型档位。同模型同网关下**Q2：案例里的"合成数据"是什么意思？为什么不隐私保护。本白皮书不涉及任何真实业务数据或敏感信息**Q3：如果dsh在复杂任务中"卡住了"（比如某步），几种处理：①看dsh进程日志，定位哪步失败；②检查工具调用的输入是否正确径、命令语法）；③配guard超时（`guard/*`包），避免无限等待；④工审批（`interaction/*`），质量不错。覆盖了边界（除零/负数/精度）、异常（必须抛特定异常）、常规**Q5：我想让dsh跑一个"多文件、多步骤"的任务，提示词怎么）；）；dsh有compaction（上下文溢出恢复）、guard（超时）、inter避免误操作；③长任务分步验证，不要"一口气跑完再检查"。具体配置参考第8章8.5节安•**精准识别重复**：合并两份相同逻辑为•**沙箱感知**：发现`tempfile.mkdtemp`在沙test_refactor.py](./assets/case-d-test•**契约差异识别**：主动发现"文档声明"与"代码实），全）**——这是agent从"能答"到"第11章：未来展望——dsh与Agent生态的演进预测1.**短期（1-3月）**：正式版0.熟4.**最大风险**：破坏性变更、生态碎片化、官方），快求），•**内容生态**：教程/博客/awesome），•**垂直Agent产品**：会涌现"行业Ag具4.**模型竞争**：其他模型迭代可能削弱D），>4.**性能边界未充分验证**：高并发、大型代码库场景缺少公开5.**官方策略风险**：开源承诺致）-->坑），**判断**：生态玩法现在入场是早期红利（竞争少、官方），），**根因**：`crypto.randomUUID`只**临时workaround**：官方无修），**临时workaround**：手动`taskkill/T`）；）；用优雅终止（孙进程输出截断/spill失效），本*1.**三层防线**：沙箱（在哪执行4.**审批fail-closed**：），5.**社区审计找到真实边界**：#159fs-sandbox竞态、#56.**企业基线一句话**：默认`workspace-write`+ask、lodsh的安全骨架是三层各管一件事（依`sandbox.md`/`permission-presets.md`/`a层升（切`danger-full-access`、改审批策略）都显式发生并）；），/dev/null））：`ctx.sandbox`）在沙箱内起子进程；Wi**同族案例**：#159的竞态属于TOCTOU（检查与使用）；宽手法——`/tmp`作workspace时，受限子进程可通过客户端展示为一个"Permissions"选择器。默认表低r中高）：）；）；minimalpreset允许工作区**结果集fail-closed**（`App×中止×中止×中止（默认fail-**流程**：工具调用→`approva**请求内容**（`ApprovalRequest`）：1.**审批回环**：#250真实复现"模型自批准danger-2.**并发误定向**：#453并发沙箱审批时点Allow）；#1pluginadd无签名/来源校验2345678以下4帖全部经`ghapigraphql`核验存在（deepseek-a常Windows上的写围栏把字面量致认死busybox-w32的`ash`在同一个受限令牌下能完成send/re来源[#2184](/deepseek-ai/deepsee给"要上生产/团队推广"的决策建议（对齐第）；用闸制）；full-access`再切回，看会话日志里的`permission/p不能当安全边界用。沙箱只管文件效果；网络（如SSRF）与进程（如#466taskkill汇表外。防恶意代码靠插件信任（13.5）与网络/进程级隔离（容器/VM/远程沙派发应答者——无人值守时不会出现"挂着等人点边界内相对安全，但#149显示"递归删除整个工作区"在workspace-write4个核心帖号（#159#584#381#817）均经`gh表格）；同族补充帖来自仓库内`docs/research/discu接减半**——与命中率**乘法叠加**、不需要改配置）；（[#560](/deepseek-a4.**命中率三原则**：会话延续（别频繁新建）、前缀稳定（别老改配置）6.**成本要看得见**：会话统计行看缓存命中%；每轮tok(/deepseek-ai/deepseek-harnes），DeepSeekAPI的**contextcache*）：），**折扣率变化（旧→新）**——14.3的三原则方向仍然成立，但「•**对国内用户**：日常写代码的时间基本全部落在），——命中时首token时间量级性缩中ai/deepseek-harness/discussi），缓存命中%），会话重讲上下文"来**落地检查**：命中率低于预期时，第一反应查"前缀是否变了"—**峰谷是第四条、也是最大的杠杆**：长跑任务（批量重构、跑测试、a），），）：）：）：期"的数字来源（注：旧表下此倍数约20×,新表因命中两者相乘。思考token减少→），档）：）；•注：`low/high/max`为本手册实测网关（pi-ai/open），）：1成本仍为美分级（推断，待实测）。这就是"ds（[#735](/deepseek-ai*，多对话整体命中率会被其他低命中对话拉低（[#1234](https://gith[#735](/deepseek-ai/deepseek-harn08-14提出，标题「【友好显示】希望在每轮对话中加入本轮对**社区建议（已同步到#735评论区）**：每轮显示应拆成**两个数*）；插件/MCP形态）——实现层面走第4）；kestiany，[#1169](https://gi），•`assistant/chunk`里`chunk.type`为`inputTokens`/`cacheReadTokens`/`outputTokens`/`reasoningT），•`request/header`事件带着实际发出去的完整工**记忆/压缩生态工具**（#1052长会话降本专题评论区，2026-），/weijiafu14用闭环压缩）。与缓#坑1型变快"234567），），>自查：参考14.4对比表（7.0×)与6.6/首token/tok/s），判断这次任务3.**动手题**：把同一批任务分别用"每4.**思考题**：为什么"只看本轮总token"会误判成本？#735评论区建议5.**动手题**：按#735的建议口径，把一个）；（[#560](/deepseek-ai/dee简单确定性任务（文件操作、批量处理）几乎无差别；复杂推理、长链规划、debug[#735](/deepseek-ai/deepseek-harnes），）；）：），修正。*设计/UI生成（348个/94K★)和视觉（132个/90K★)需求最旺/发布）+**免费托管实例**出现（#2826）——生态从"有序分发"走2.**"官方没做，社区全做"是主旋律**：桌面壳（1403.**缺口明确**：金融（8个）、数据库（14）、/合规场景9主题热度（插件数/总star/判断）94K89K90K90K88K中7.7K中8数据面：Windows兼容是最高频话题；讨论面：**中文路径截断（#107/#151/#396等15+帖同根因）**、koffi原生崩**交叉验证**：数据面"Windows兼容差"与讨论面60+