deepseek+harness白皮书：从0到1玩转deepseek+harness的新手百科全书

从0到1玩转DeepSeekHarness的新手百科全书学习路径：从0到1的3天计划Day1:理解+跑起来(第1-2章)时间30分钟能力矩阵)能向别人解释"dsh和ClaudeCode的区别"30分钟对话+headless能启动UI完成一次对话；能跑一条headless30分钟障速查能改settings.yaml;能解决端口占用Day2:理解骨架+第一个插件(第3-4章)**目标**:理解profile/插件机制，写出第一个能跑的插件。时间1小时第3章(profile、挂载、host/client、扩展点、能挂载社区插件(Git面1.5小时第4章抄写示例提速插agent/request注入决策输出Day3:实战+调优(第5-6章)时间1小时方法)能说出"写一个PR的完整闭环"1小时第6章性能模型(思考占30分钟下文、MCP/子代理/工作流)+术语表知道dsh的能力全貌与扩展方向想做什么第9章MCP+官方mcp包文档并行任务第9章工作流+官方examples生产部署官方架构文档+安全模型(sandbox/权限)第7章+dsh-plugintopic内容开源时间MIT(可商用、可改)语言版本线方明示”将有破坏性变更")内置形态web(WebUI)+headless次性CLI)官方定位官方README原话："everythingflowcharflowchartTBsubgraphProfile["你的profile(可启动形态)"]P1["dshweb(WebUI)"]P3["自定义profile(TUI/桌面/机器人..)"]endsubgraphPlugins["能力层(每个能力=一个插件)"]L["11m:模型接入+推理档位"]T["tools:写文件/终端/搜索/技能"]S["session:会话持久化"]C["client:界面(web/终端)"]ST["settings:用户配置"]subgraphCordis["Cordis插件容器"]D["依赖注入·事件·生命周期"]Cordis-->-->ST=bundle栈+你的补丁层·dshheadless(CLI形态)·11m:模型接入(DeepSeekV4系+推理档位)你的profile(可启动形态)I·dshweb(WebUI形态)·你的自定义profile(TUI/桌面/机器人|能力层(每个能力=一个插件)·toois:工具(写文件/终端/搜索/技能.…)·client:界面(web浏览器半/终端半)生命周期Cordis插件容器：加载、依赖注入、事件、干什么client半浏览器(webprofile)package.json的dsh.client声明模型绑定DeepSeek)Claude系GPT系任意Gemini系Kimi系官方运行时+时时官方后端)时时插件体系官方级：一切皆插件，包为主无无自定义界面半=自由××部分(TUI固定)××自动化/CI☑☑☑☑☑☑(官方未内☑☑成熟成熟成熟成熟早期想深度定制+玩生态的开箱即用开箱即用熟悉用户态IDE内嵌的AI编码助手 (Composer/Agent模编码agent轻量终端形态；dsh多了官方后端+插件生态云端"AI软件工程师"(独立任务/浏览器/工作区)IDE内嵌编码agent(Flow/Agent模式)同Cursor,绑定IDE是通用运行时阿里通义codingagent主打Qwen模型；dsh官化智谱codingagentCLI型无关+插件生态xAI终端codingagent主打Grok模型<!--[style]子标题编号统一：去掉残留旧编号-->**OpenCode没有官方后端运行时**(它是客户端+配置),dsh有官方bundle+60+包似)。第10页定制深度(可改的东西)高|dsh(运行时+插件生态)Code/Codex/Gemini/Kimi(产品即运行时)低开箱即用程度高自建框架dshweb→输入指令→模型用Grep/Read/Edit栏(可加Git面板)"任务"→打印结果退出败打开TUI→输入指令→终端TUI,开箱即用IDE内嵌体验网页里建任务→云上完成托管、有浏览器、数据出dsh实测下文注入)→热缓存~1s50步工具链任务(含测试+实机验证)与ClaudeCode同任务dsh配V4-Flash成本约为Claude的1/10~1/30价格维度dsh生态显著占优接其他OpenAI兼容模型)。**Q3:没写过TypeScript能玩吗?**能。使用(第2章)不需要编程；写插件(第4章)需要基础TS,但教程给完整代码。**Q4:dsh稳定吗?**第12页5.**FAQ测试**:回答"dsh是模型吗?""没写过TS能玩吗?"第13页low)/high(默认)/max(最强)——**工具链任务90%时间在思考，降档是最快5.**配置**:~/.dsh/settings.yaml`(模型+推理档位)2.1准备工作(30秒检查)需要见下)npm(随Node附带)第14页能访问npmregistry能装包(/deepseek-ai/deepseek-harnes2.2安装(三种方式)第15页帖号首次npx极慢需下载500+包耐心等待；改用h后秒启未发布不到插件h后启动报Cannotpnpm全局安装的依赖解析策略与npm不同；建议用上测可行)>第16页内容中栏(DeepSeekV4Flash)、推理等级(High)右侧/底部件后出现)(工具调用轨迹)deepseek-v4-flash(默认)性价比：快、便宜，日常够用第17页**推理等级**(思考模式三档，2026-08-13起支持):够用简单/确定性任务、high(默认)好日常Agent任务复杂推理、长链规划编程助手，可以帮你写代码、调试问题、处理文件、搜索资料，以及完成各种开发和办公任务。dsh--profileheadless“读取工作区今天的gitlog,生成一份中文日报摘要”>daily-report.mdecho两节(web/headless)是白皮书实测详讲的(标准)☑2.3节实测第18页(极简)strreplaceeditor两Codemode(代码)模型写次程序内编排多轮工具调用长链路自动化、确定性执行造)内测试Cordis插件+组合新模式插件开发、快速原型原理见第3章，这里先跑通):-id:better-sidebar#name:dsh-better-sidebar#4.%USERPROFILE%\.dsh\profiles\web)dshweb#全局设置(模型、推理档位)#全局设置(模型、推理档位)cordis.patch.yml#补丁层(挂载插件)#会话数据—storages/#持久化存储agent-default-agent-default-model:model:deepseek-v4-flashre第19页dsh--profileheadless"任务"一次性任务，打印结果退出给profile安装插件TUI模式(需先安装tui插件，官方未内置)tuiprofile需插件创建(dsh端口被占：netstat-ano\插件装不上(404)rc.1依赖断裂：确认依赖用^0.1.0-rc.6线(第3章常见坑升级后行为变了第20页>'动手练习(10分钟内完成)5.**排障演练**:模拟"端口被占"(先起一个占用3080的服务),用`netstat`排查第21页package.json(插件清单)+cordis.patch.yml`(补丁层)组成后`pnpminstall'重启要dsh运行时dsh用**profile**表示"一种可启动的形态"。官方内置两个，其余+工具)一次性CLI任务"任务"第22页tui(需插件)终端UIdsh--profiletui(未内置，需安装插件)profiles/web/—package.jsoncordis.patch.yml#你的补丁层：挂载/覆盖插件的声明十cordis.yml#(生成的)合成**加载顺序**(官方文档原文):内置bundle('dsh-base→`dsh-web-app')→profile日常Agent工作一模型生成一段代码组合多轮工具调用复杂多步骤工具工极简最小环境下的模型插件开发用检查当前运行时、第23页{"dependencies"{"dependencies":{"dsh-better-sidebar":"link:C:\\path\\to\\DSH-better-sidebar"}明`dsh.client、不写`exports程client半浏览器(webpackage.json的"./lib/index.js"},"./client":{"types":"./lib/第24页compaction插件用这个做上下文溢出恢复)订阅/注入对话事件在界面槽位注入UI(如turnTail显示产物文件settings服务间(设置页自动渲染)ctx.on('agent/request',async(request,next)=>{/1每次模型请求前触发：可以改provider/model/reasoningEffort/toolsr'low':request.reasoningEffort/1必须awaitnext()并return其结果(它是Promise,把修改后的请求交给下一环)returnawaitnext(request)}>关键：agent/request`'是**waterfall**(链式)—每个插件都要awaitnext(`并return3.5常见坑(真实踩过)帖号官方rc.1时代多个到^0.1.0-rc.6线一全局core.hooksPath冲突(如临时取消全局第25页pnpm全局安装的模块解析策略与建议用npmi-9或默挂 直接挂掉误(社区有补丁)帖号npm包名需已发布到npm;一github:作者/仓库只加依赖，不自动append到需手动补挂载行一dshplugin<..>传路径在内部转发时修复方向：shell:组)或转发前自行第26页rc/plugin.ts的runPlugin用DEP0190警告),调用方引号到不了转发层要暴露.入口("main":"src/index.ts"可被tsx直接加载)事件handler忘了awaitagent/request的next类型报'agent/request'npm类型未re-export官方类型增强用宽松签名(ctx.onasclient包产物依赖jsdom无法直接跑client组件级测试需dshweb运行时(官方Cl跑)第27页>自查：参考本章3.3节表格第28页第29页2.**验证三层**:纯函数单测(决策正确)→waterfall契约测试(接线正确)→实机省dsh-speed-plugin/十package.json#host插件声明十effort-decision.ts#纯函数：决策逻辑(零依赖，可单测)apply(ctx):接入扩展点一tests/—effort-decision.spec.ts第30页{".":{"types":"./src/iEffortId//用户基线档allowDowngrade:booleanallowUpgrade:boolean}constEffortId{const{recentCalls,selected,allowDowngrecentCalls.filter(c=>SIMPLE_TOOL_RMath.max(m,c.argsSize),0)if(ratio>=0.75&&allowDowngrade)allowUpgrade?'high':selstring/exportinterfaceEffortDecisionInput{recimporttype{ConToolCallSample}from'./effort-decision.ts'export{enabled:booleanallowDowngallowDowngrade:true,allowUpgrade:frecentToolCalls(agent:unknown):ToolCallSa{events?:readonlyunknown[]}}).session?.events??[]for(leti=events.length-1;i>=0&&out.length<Wevents[i]asif(e?.type!=='tool/call')continueout.push(argsSize:typeofe.data?.argumentsreturnout.reverse()}exportfunction==='string'?e.data.argumargsSize:typeofe.data?.argumentsreturnout.reverse()}exportfunction事件类型增强，这里放宽签名(第3章常见坑)conston=ctx.onasunknownas(event:string,handler:(payload:Record<string,unknown>,next:()=>uorecentToolCalls(payload.agent)consteffort=decideEffort({selected:config.baseline,allowDowngrade:config.allowDowngrade,allowUpgradconfig.allowUpgrade,=>reasoningEffort=${effort}`)return{..seed,re第31页4.5测试importimport{describe,expect,it}from'vitest'import{decideEtoolchains',()=>{expect(decidallowUpgrade:true,})).toBe('low')})//….更多分支：全新提示保持基线/禁用降档/超大载recentCalls:[{name:'writeit('awaitsnext,preservesthexpect(result).toEqual({provider:'deepseek-official',awaitrunRegisteredHandleexpect(result).toEqual({provider:'deepseek-official',[speed-plugi[speed-plugin]agent/request:calls=[]plugin]agent/request:c第32页>>constfinal=SUPPORTED.includes(effort)?effort:(effort===Iow'?high':effort)//>第33页行>自查:参考本章4.5节单元测试示例。**注意**:3简单+1超大=4个调用,ratio=>自查:参考本章4.4节"三个关键点"第1条6.**思考题**:`agent/request`waterfall一`ctx.on('agent/request第34页因为从events数组末尾往前遍历(取最近的N个),结果是倒序的(最新第35页日常编码写函数、修bug、5-bug修复+49测试：94s化、报告数据清洗+可视化：文档知识结、翻译API文档生成：自动化运维第36页原因说明录/历史重复→命中中**成本影响(98%缓存折扣)**:折扣输入(Flash)dsh--profile过”#实测：5个bug全修复+49个测试通过(94s)第37页dsh--profileheadless"分析sales_data.json的数据质量(缺失/类型错/重复/异常),写清洗脚本+可视化脚本，运行验证，总结处理方案"#实测：52→35行归零+图表+权衡说明(186s)dsh--profileheadless"为user_module.py(8个函数)生成完整MarkdownAPI文档：参数表、返回值、异常、示例、边界情况"#实测：423行ReadTheDocs风格文档(1m04s),主动识别“文档契约vs代码实现"差异##cron每天8点生成日报dsh--profileheadless“读取工作区gitlog,生成中文日报”>daily-.md(保留结构)"第38页dsh--dsh--profileheadless"把legacy_orders.py重构构前后输出相同”#实测：17/17测试通过，含脚本级产物对比(4m37s)靠5.8我的第一个真实任务(15分钟上手)4.**多步任务**:设计一个跨场景任务(如"读代码→生成文档→输出报告第39页章)链/界面/插件(第1章矩阵)第40页第41页1.**时间花在哪**:模型思考占~90%,工具执行<1%,网络/渲染~10%——优化思段占比说明模型思考(Think)~90%(单仓库/定位明确场景)思考，是绝对大头工具调用/搜索(Tool)多仓库场景可反超至87% 4m8s/工具29m17s)仓库时，harness在仓库工具执行文件写入等毫秒级网络/渲染第42页6.2reasoning_effort策略(官方三档)provider请用off-->日常Agent任务(默认)1(dsh-type-meta等从未发布)线2暴露.入口；"main":"src/index.ts"可被tsx加载3next忘awaitagent/request的next返回第43页4事件类型不识别npm未re-export宽签名5client测试跑不了jsdom报引导机制，组件测6简单任务"突然变快"的误判误归因cache命中也会提用全新prompt7端口占用dshweb起不来8d)档正常(仅high/max触发);high/max下工具调用轮次没有思考内容时，>0条件把空的reasoning字段省略→下一轮请求报replaystate)留reasoning占序列化时始终保留3.**验证器多严**?宽松验证器(SWE-benchVerified第44页6.6缓存策略：让每次调用都更便宜第5章讲了高缓存命中率的价值(实测会话缓存命中率97%;缓存折扣Flash档98%/Pro档99%+),这里给出**可操作策略**:目标提高命中建会话)提高命中(不要频繁改配置)提高命中一批文件分析)降低成本简单轮次用low档(思考token减少→总token下降)稳定性>自查：参考本章6.1节耗时分布表格5.**动手题**:模拟"端口占用"坑(先起一个服务占3080端口),用netstat-ano|>自查：参考本章6.4节坑#7第45页第46页官方仓库官方文档站官方VitePress文档站 2026-08上线)第47页产品站点官方产品介绍(四种运行模式、轨迹视图等)官方README内链接官方仓库Discussions的贡献入口)[#371](/deepseek-ai/deepseek-harness/d2.**复现**:最小复现步骤+报错日志前20行帖号问题断含"需求"等汉字的路径附修复补丁复现+修复代码片段第48页附可cherry-pick修复7.3插件生态(2026-08-13快照)项目(reasoningeffort自动调节)教学示例(第4章)dsh-handbook(本白皮生态文档安装器)discussions/872,同族见移植)第49页/deepseek-ai/deepseek计，可挂接记忆插件族)期记忆分层，提炼前自动剪枝(省65-96%会话内sgme(npm包dsh-m/deepseek-ai/deepse工具输出压缩：进上下文览+本地artifact(>12,000字符或240行触发)经m/weijiafu14/pi2dsh挂失的win32简模式的持久shell能起来；另有沙箱内可用的m/deepseek-ai/deepse免装Node安装包：mac自带Node运行时、零前discussions/380作者第50页codeAnqiang-ma提供),安装见第2章2.2实测验证)clone即用(DSHskill)令与详情页(headless默认只打印最把Claude/ChatGPT历史记忆迁入DSH(含逐字目标第51页常用例深度定制官方AGENTS.md(架构)→cd～/.dsh/profiles/web&&pnpm**②cordis.patch.yml`加挂载行**:**③安装并验证**:cd~/.cd~/.dsh/profiles/webcalls=[...]=>reasoningEffort=low`(参考第4章4.5>②两个插件均要求@deepseek-ai/dsh-agent^0.1.0-rc.6',若pnpminstall'报404,请检查版本线(见第3章3.5节)。第52页topics/dsh-plugin或搜所有打了topic的仓库dsh-plugin+语言过滤或已发布的包(rc阶段以GitHub为主)官方讨论区Showand社区自荐项目把7.4节的"四步走"展开为**可操作的决策树**:时间dsh开源(零日)编程时代起点60+官方包同步放出文/会话/子代理/MCP/I第53页盖官方讨论区单日30+等2026-08-13当周14章中文教程+板，补零日文档缺口进行中官方讨论区持续活跃插件/路径/TUI/vision等方向(见7.10节)规划中ROADMAP.mdP1优先级结论整理进第3章3.5节”常见坑”接台短板界→帮官方分流更新能力矩阵中新能力→调研→更新表格→确认第54页(docs/faq.md六类问答)社区五项目章7.3节成生态地图token成本节成本模型沉淀展望帖给链接，如"详见第7章7.6节")。第55页>自查：参考本章7.4节第2步+第5章案例的PR范式>自查：参考本章7.9节时间线表格+7.10节联动模式(TL;DR+分步讲解+练习)。第56页第57页1.**60+官方能力包**:工具(fs/shell/web/skill/todo)、上下文4.**上下文=系统提示+技能目录+对话历史+工具结果**:分层注入，每步请求携环(#558/#581/#689);流式下工具名被抹空(#725同族，见FAQ);run_code内8.1官方能力包地图(60+包一览)第58页作用工具(tools)办等可调用工具上下文(context)会话(session)持久化、标题、遥测服务器)工作流(workflow)多步工作流编排安全(safety)策略分散在多个包组)技能(skill)界面(client)>agent-loop/scope/Ilm-streaming/subagent)日志):第59页工具名作用fs能力写文件fs能力内容搜索工具结果含locations(用于产物追踪)沙箱隔离长任务规划技能调用skill-catalog注入一次模型请求的上下文=系统提示+技能目录+对话历史+工具结果。实测在会话日志中上下文注入上下文注入@deepseek-ai/dsh-system-prompt←官方系统提示上下文注入skill-catalog←技能目录第60页每步一次工具调用一段程序编排多轮调用中间结果仅return/console.log回灌典型场景日常对话、单步任务行第61页[#462](/deepseek-ai/deepseek-harne尤其waterfall事件监听器('to复(--sequencetool_call_success,success),以此注入工具调用tool-arguments'{"command":"Is"}'#2.跑headless**从源码跑的三点提醒**(#462作者实测踩坑):sparseclone一次加全(缺报`Cannotfind数)。第62页rc.6时代的工具链已知坑(坑1/2已入[FAQ](./faq.md)):(/deepseek-ai/deepseek-harne[#581](/deepseek-ai/deepseek-harness/(/deepseek-ai/deepseek-harnes修复);#689显示同族问题让run_[#615](/deepseek-ai/deepseek-harness/d(/deepseek-ai/deepseek-harneai/deepseek-harness/discuss第63页1.**理解题**:不看原文，列出dsh内置的8个工具名(简短动词)及各自作用>自查：参考本章8.2节工具表格4.**动手题**:在`dshweb`里进行一个长对话(20+轮),观察是否触发第64页第65页独立验证)—先用好单Agent再上子代理4.**组合起来=Agent系统**:父Agent规划→子代理并行调研→工具链+MCP→工作流汇总→产物5.**新手路径四阶段**:单Agent+内置工具→+MCP→+子代理→+工作流(逐`mcp`客户端包(@deepseek-ai/dsh-mcp-client')。第66页你的提示词(目标)你的提示词(目标)↓父Agent(规划)十子代理A:调研模块A(并行)子代理B:调研模块B(并行)工具链：read/grep/bash+MCP(数据库)↓工作流(如：校验→汇总→输出报告)↓产物(可打开/追踪)1.**阶段一**:单Agent+内置工具(第2-5章)3.**阶段三**:+子代理(并行)4.**阶段四**:+工作流(确定性流程)第67页9.5社区生态示例(2026-08-13快照)'dsh-plugin-cost-tracker']env:DSH_API_KEY:'${DSH_--insert:maxConcurrency:33-5个总结论2-3个1-2个准交叉检查多文件并行编辑2-4个免冲突各子代理写不同文件第68页校验"四步(参考第10章案例校验"四步(参考第10章案例A的任务结构):-insert:-/data'command:'pythonclean.pyraw.jsoncleanchart.png'dependson:[clean]-id:validatecommand:'pythonverify.py(调研/验证/多模取→清洗→报表→校验)复杂度中(需配置服务器+理解协议)高(需任务分解设计+结果汇总)繁琐)或报错(推断，待实测)单个子代理失败→父代理决定重试/忽略/终止断，待实测)性能开销额外进程通信开销并发节省墙钟时间，但增加协调开销串行执行，无额外行收益第69页实测)2重复提问描述(推断，待实3配置onError:pause或每步后加校验脚本(推断，待实测)4子代理文件冲突多个子代理同时写同一个文件待实测)5入确认宿主shell已export;或写死(仅本地测试)(推断，待实测)能力阶段)阶段一单Agent+内置工具能独立完成：创建文件→搜索→编第2-5章阶段二服务器，任务中调明调用发生阶段三子代理任务(如同时调研2个模总结果阶段四成功配置并执行一个3步以上工作第70页dependsOn顺序执行(自查:9.1-9.3节首段+9.9节对比表)节+9.8节)3.**动手题**:在`dshweb`节+9.9节)出父Agent规划+3个子代理任务描述(自查:9.2节+9.7节)5.**思考题**:任务"读100个文件后汇总",单Agent分5批串行,各有什么优劣?(自查:9.9节对比表)6.**思考题**:想让dsh"条路各需什么条件?哪条最快?(自查:第8章8.1节+本章9.1节+第3章3.4第71页**Q4:我想接一个MCP服务器(比如数据库),具体怎么操作?**第72页1.**案例A(数据质量分析，186秒)**:52行脏数据→分析→清洗脚本→可视化2.**案例B(5-bug修复+49测试，94秒)**:故意埋5个bug的计算器模块→全<!--[fix]链接健康检查：案例A/B锚点中`+`在GitHubslug里产生双连字符(--),原案例A:数据质量分析+清洗+可视化(186秒)第73页dsh怎么做的(工具链)read(sales_data.json)→write(clean.py)→bash(pythonclean.py)→write(visualize.py)→bash(pythonvisualize.py)→read(输出)→总结问题归零☑生成有效PNG(1950×825)缺失金额中位数填充、异常值删除、去重、类型统一案例B:5-bug代码修复+49个测试(94秒)第74页dsh的修复+测试(验证：49passed)正/负/零/浮点/精度/交换律负结果/零边界/浮点符号组合/乘零/浮点0!/1!边界/已知值/负数必须抛·**完整闭环**:读→修→写测试→跑测试多步工具链☑自动编排(读→写→跑→验证→总结)复杂任务耗时94s-186s(同模型同网关，比benchmark简单任务慢但可控)☑有判断力(数据权衡说明、测试边界设计)开失败恢复第75页证"),dsh会照着闭环。3种问题：缺失值、类型错误、异常值),写提示词让dsh分析+清洗+可视化，记块(如字符串处理、日期计算),让dsh找bug→修复→写测试→运行验证，记录**Q1:案例A耗时186秒，案例B耗时94秒，这个速度算快还是慢?**第76页径、命令语法);③配guard超时(guard/*`包),避免无限等待；④生产环境建议配人**Q4:案例B的49个测试是dsh自动生成的，质量怎么样?**第77页校验),如实写入边界章节跨领域能力闭环工程意识☑零依赖权衡、沙箱感知、向后兼容、契约差异识别级产物对比)第78页第79页熟时间短期当前rc.6,官方明示"将有破坏性变更”,迭代极快短期官方补上TUI与交互式CLI(社区呼声最高，#17215+评论)官方Discussion最热需求中期 (reasoningeffort精细化、缓存命中率工具化)高缓存命中率已是成本优势(第5章),会被工具中期场/一键安装/质量分级)官方已有dsh-plugintopic,插件数量增长必然第80页长期已被验证为可组合架构定制+开源+成本"差异化都开源；dsh的官方后端+插件生态是差异点(OpenCode无官方后比自建省事，比闭源可控模型侧dsh生态价值(模型+运行时协第81页教程/内容作者中文教程真空(白皮书是第一份)现在(红利最大)程访问、移动端、缓存工具工具型项目提速、耗时可视化、MCP现在(我们已做提速插件实验验证)插件市场、模板生成器、中期行业解决方案金融/教育等行业插件包中期书+第4章示例是示范之一)·**想试试**:现在装起来玩(第2章),成本几乎为零第82页第83页>第84页link开发依赖断裂@deepseek-ai/本地link时报D,npm安装却正常含中文/特殊字符路径fs-sandbox竞态post-check路径检查与序竞态社区反馈中(#159)入)建议中(#392)第85页人反馈(根因#107,家族17+帖)端口：默认3080撞上Hyper-V保留区间(#589)**临时workaround**:换用保留区间外的端口(社区实测13080可用)。局域网HTTP访问RPC全挂(#755)子进程：Windows无优雅终止(#7第86页12.4跨平台已知问题速查表harness),截至2026-08-14。问题帖号中文路径截断(readUtf16单字=U+5F00被截)(根因；家族等17+帖)工作区路径避开中文/特殊字符；社区附修复补丁可目录选择器worker崩溃(koffi相关)(家族安装层锁(#293);选择器Hyper-V保留区间Windows(启用口(如13080)局域网HTTP访问规避(推论);官第87页后永久崩溃(不自愈，PO)项目放/root下使用/shellPath错)追上):零日，第三方资产稀少开箱即用需理解profile/插件体系第88页文档官方偏架构，上手靠社区官方文档完善+教程丰富IDE/工具链集成本*第89页1.**三层防线**:沙箱(在哪执行)→权限预设(能做什么)→审批(危险动作要不要workspace-write`(工作区写+ask)与`danger-full-access(无沙箱+never)伤、#381iframe点击劫持、#817审计报告(vm逃逸+本地RPC无认证)sandbox.md/`permission-presets.md/'approval.md;与第8章8.5实测交叉印证):管什么第90页能做什么审批最小权限的最后一道闸说明只读+必需sink(POSIX下如式可写根，报partial工作区根+后端承诺的临时区可写默认预设；根来自会话不不设限走ctx.sandbox第91页13.3权限模型：工具权限分级表工作区内可写、操作前询问(默认)无沙箱、不询问custom(派生态)任意级别只读探查read-only兼容低只读不落盘；读不限于工作区工作区写r中写边界=工作区根+临时区高沙箱不挡网络与第92页全访问任意(切关闭所有闸门(#149);`danger-full-access`误删整个家目录(#461,真实事故);Windows上 一次性放行(只放行被问的这一个动作)☑继续明确拒绝×中止请求被撤回×中止无应答者/应答者异常**流程**:工具调用→`approval/request`waterfall(插件可拦截/改写)→应答者(WebUI人肉应答，或ACP桥的一次性机器决策)→每次请求成+signal(AbortSignal撤回)。3.**重连丢审批**:#646重连静默丢pendingapproval(resyn第93页审计(#817及同族)沉淀的检查清单：1pluginadd无签名只装官方/知名源；2插件boot期有全配3界?workflow/动态vm只当隔离引擎，不当安全层4scrubbed正确?KEY等含KEY子串的变量是否被误scrub(误伤机制按标题推断)5敏缺口6失效?timeout:0hook超时设正数；7审计留痕?回溯8不泄漏会话明文?话残留帖号第94页换，可越界写pick修复)scrubbed,行为异常默认localhost诱导授权Full限操作恶意网页诱导用户安全审计报告：沙箱/审批边界绕过与(PoC可私下提系统性审计覆盖vm逃逸(同族#243#778)、 (同族#451,的写围栏把字面量/tmp解析成C:\tmp,静默授予一编辑器面可写入，shell面写同一路同一路径判定不一致告称全量780帖程序化核验):帖号归删除整个工作区，零确认审批不是安全边界个家目录(真实事故)高权限预设风险实锤第95页沙箱内agent可taskkill杀宿主留不清理隐私风险签名说明受限令牌破坏Windows凭据栈，走Schannel的OpenSSL的(node、死Cygwin的cygheap初shell到不了提示符。报错长得像PTY问题，其实是ACL问题同上，另一台机器的变体同一堵墙的另一个症状，由第三方在自己机器上独第96页保持loopback(--host的);远程认证完善前勿只在隔离机/一次性任务用官方preset表+#461审批策略人肉应答链路必备；性拒绝)并前置review闸白名单源+装前过13.5addgithub:敏感目录(家目录/密钥目制审计审计对可回溯);防.tmp明文残留13.5清单(沙箱后端/预设表可能变)第12章rc版诚信理由团队共享主机Cl/无人值守置review闸隔离机/一次性任务器本身隔离)第97页>自查:参考本章13.3节预设表>自查:参考本章13.5节清单表>自查:参考本章13.6节+13.7节基线表第98页4个核心帖号(#159#584#381#817)均经`ghapigraphql`逐号核验存在(链接见13.6第99页 3.**手册实测命中率97%**:会话延续+稳定工具schema+Agent多步工作负载特性(第5章5.1.1);社区长跑实测可达99.7%([#560](/deepseek-ai/deepseek-harneslow`档+高命中=最便宜组合计行+社区cost-tracker插件，或零安装直接读sess第100页*计费，而不是全价。dsh每次模型请求的输入=系统提示+技能目录+对话历史+工具缓存命中未命中输出旧表(统一价)新表(谷时)120倍**峰谷计价(2026-08-1616:00UTC起)**:可以叠加(见14.3末尾)**每次请求的输入结构**(第8章8.3),决定了哪些tok14.2命中率实测：97%怎么来的原因说明录/历史重复→命中中第102页 (第12章12.5)。社区长跑实测可达**99.7%**([#560](/deepseek-**实测方法**:WebUI底部会话统计行看"缓存命中%"(第6章6.6);对比基准是5.1.1 作者实测踩过：两组数据重算时才发现时间分布不同，按金额对比会得出错误结从10s+量级性降到1s以下(第6章FAQQ4)(14.1结构)历史消息重复→命中稳定提示词前缀一致→命中一次把验收标准写清楚(第5章5.7/第10章会话重讲上下文”来过技能目录，都会让缓存失效(第6章6.6监控行)。第103页**成本模型速记**(第6章6.6):总成本≈输出token×输出价+输入未命中×未命中价用14.1谷时Flash输入价算一笔账(**10k输入token**,命中率对比)。算术示例(90%(Flash谷时)放大到1M输入token:90%命中≈**$0.0283**,10%命中≈**$0.199**,全价$0.22两者相乘。思考token减少→总token下降(第6章6.6),且随上下文重复的部分同样第104页章6.2)最少最低简单/确定性轮次：文件操作、批量、工具链中的廉价步档中等日常Agent任务(默认)最多复杂推理、长链用，别开进批量 official适配器为`off/high/max`(第6章6.2注释)5.1.1量级折算(50步≈2.4M输入token),案例A输入量级约**50万token(推断，待实测)**:估算)荐做法)中途新开会话/前缀变动内容第105页断，待实测)1~5万冷启动(未命中)总结~45万极小1/10~1/30"(第1章实测)在单任务维度的来源。**现状(有的)**:[#735](/deepseek-ai/deepseek-harness/ 同样10ktoken,命中率90%和10%成本差7.0×(见14.4)。**过渡期工具**:社区`dsh-plugi第106页inputTokens/`cacheReadTokens`/`outputTokens`/`reasoningTok 实测)。npm包dsh-记忆引擎(治本)「对话历史」与「长期记忆」分物，实测省65%~入相关记忆块(纯结构化查询，不烧token)→需要细需检索/weijiafu14/pi2dsh挂载)工具输出压缩(治前压缩大工具结12,000字符或240行时只把确定性的型，完整结果存本用闭环压缩)。与缓而缩小"必然首次安装示例(pi-quiet-tools,摘自#1052作者实测):--profilewebaddfile:$PWD/dsh-pi-quiet1型变快”110s误导(第6章坑#6)2每个任务都冷启长任务/批量保持会第108页3改配置悄悄杀掉命中率命中%突然下降，监控统计行命中4只看总token误判10%差7.0×(#735建议)5预算漏了输出侧只按输入价算，账按官方定价页/14.1(输出=未命中36批量任务开max,批量用low,复杂7测踩过)只比token,不比单价不同，见14.2口径注意2)长工具链任务(20-50步)high+会话延续+前缀稳定；中，谷时)low+同会话批量(命中红利最接受冷启动low+headless+单会话串行长跑任务(批量重构/测试/agent长任务)挪到谷时(北京晚8点后/早8点前),账单直接减半(与命中率乘法叠加，14.1)中位数；跨峰谷边界的组只比token不比金额(第6章6.4/6.6,14.2口径注意2)/模型档位)第109页释90%与10%命中差多少倍>自查：参考14.4对比表(7.0×)与6.6成本模型速记>自查：参考14.1冷启动110svs热缓存1s的实测手册实测97%(第5章5.1.1);社区长跑实测可达99.7%08-14提出的需求帖(每轮token+provider/model标识，见14.7第110页渡期用：会话统计行命中%+社区`dsh-plugin-cost-tracker(第9章)或`dsh-usage第1章实测)。判断方法：首token突然从10s+降到1s以下，大概率命中(第6章FAQQ4)。做性能对比时用全新promp2026-08-16起峰谷计价(14.1):峰时UTC01:00-04:00+06:00-10:00(北京时间第111页第15章：DSH生态全景报告——4000+插件与2400店[dsh-hub.cc](https://dsh-hub.cc08(帖号2400+)。1.**生态在爆发**:4000+插件(插件商店dsh-hub.cc收录),两周内从零长出来；设计/UI生成(348个/94K★)和视觉(132个/90K★)需求最旺1b.**分发质变**:插件商店上线且收录从4000+涨到**6000+**(#2423,一键安装/评分3.**缺口明确**:金融(8个)、数据库(14)、音频(19)、评测(37)几乎空白一4.**Windows与远程是硬伤**:中文路径家族(#107等15+帖)、子进程(#717)、局域网RPC(#755)15.1生态数据快照(4000+插件)心价值承载)第112页9稀缺(见15.4)主题热度(插件数/总star/判断)设计/UI生成需求最旺(agent产出视觉的刚需)IDE集成高需求视觉/看图纯文本模型看图是刚需(与讨论区78视觉桥家族互桌面/客户端官方无桌面壳，社区补位内容创作中忆体/#1448/#1478等，路线多)中金融/交易8缺口数据库缺口多模态/音频缺口100%覆盖门禁形第113页成反差)15.2定性洞察(780帖讨论区观察，交叉验证数据)洞察1:Windows是第一大痛点(60+帖)等15+帖同根因)**、koffi原生崩溃(#197/#293)、端口保留区间(#589)、子进程无优雅终止(#717)、沙箱临时目录清理崩溃(#758)。CLI/TUI/桌面/memory/视觉(#391/#405/#386等)。**交叉验证**:安全需求高(审计活跃)但安全工具少(9个sandbox插件)——**供给缺讨论面：unknowntool""(#725/#1405)、reasoning序列化省略(#739/#1850)、截断tool-call污染(#1519)、run_code异步回调丢弃(#1476)、损坏会话拖垮boot(#1519/#725都带测试修复)。(#735/#1052/#1234/#1374/#1520),成本工具雨后春笋(dsh-usage/usage-panel/第114页程"(第14章)是确定性方向。**交叉验证**:插件总量从1804(总表)到6000+(商店)——口径不同(商店含部分非真数据面：音频类插件仍稀缺(19个);讨论面：#2008实时语音+#2431ASR/TTS/avatar15.3官方可优先建的能力缝(数据+讨论双验证)多模态/视觉通道(OCR+视觉服务抽象)高(core实现已出中高(标准层已有人提)(官方可替换)高(session已有全量记录)(定标准收编)多套客户端并存高(session→报告)官方100%覆盖门中高第115页/远程)中高(工程量大)容契约#1825提案；社区已先行：dsh-高(官方可收编/标准化)3.**成本优势**:缓存命中97%×折扣，成本透明化工具链已齐(第14章)·数据面(1804仓库总表+4000+商店收录)口径已标注(README提及dsh,含部分·定性面(2400+帖+225帖响应)来自本手册持续观察——帖号均可溯源第116页>>> (dsh-base→`dsh-headless包名dshCLI:profile启动、核心bundle:每个profile的核心直接core核心第117页 (插件开发常直接依赖)核心dsh浏览器面bundle:服务、web面提示词、核心(dsh的插件底座)核心web_search`/'todo_write...),底层由本组包提供实现。包名工具(ctx.fs):词汇类型、IO+可选版本守卫原子写)、fs/策略事件词汇工具基于ctx.fs工具(glob、grep),内置打包的ripgrep二进制工具locations→产物追踪)工具工具工具第118页果词汇、WebEror分类工具工具todowrite,基于事件溯源会话日志工具(skill调用入口)工具"装什么"(系统提示+技能目录+历史+工具schema)与"装不下时怎么压缩"。包名系统提示组装注册表(官注册提示片段)上下文上下文token计量驱动的压缩策略+LLM摘要后端(检测溢出→修剪→摘要)上下文模型按需调用)上下文包名第119页与提供者注册表遥测seam:会话事件捕上报后端包名包名包名工作流能力seam:包名(ctx.sandbox):同世界隔离词汇+SandboxProvider契约安全循环卫生与工具超时(白具体包名待补全)安全权限/审批(危险操作确补全)安全第120页包名