尧图网页设计 
DeepSeek Harness 实战用 dsh 从零搭一个能干活的编码 Agent系列导航本篇是 DeepSeek Harness 实战系列第 1 篇。前序已发布的《概念综述》《使用教程》《系统架构及运行原理》《插件机制全解》可在我的主页回看。本文不堆概念直接把一个会读代码、会改文件、会跑测试、会提交的编码 Agent 从零跑通并讲清每一步背后的取舍。引言你缺的不是模型是手很多开发者第一次接触大模型写代码时的体验是这样的把需求贴给网页版对话它返给你一段看起来很对的代码你复制进项目跑一下报错再贴回去让它改来回几个回合上下文被稀释最后你干脆自己手搓了。问题不在模型不会写而在于模型和真实世界之间缺了一层执行身体——它看不到你的文件树改不了你的代码跑不了你的测试连这个文件现在长什么样都不知道。 DeepSeek 在 2026-08-13 开源的DeepSeek Harness命令行名dsh干的就是这件事它把模型和在真实工程里持续干活的能力缝到一起提出了那句贯穿整个项目的最核心公式——Agent Model HarnessModel 是灵魂负责思考和推理Harness 是身体让它理解环境、使用工具、在真实世界里把一件事干完。网页版对话 AI 交付的是一段话而 Harness 交付的是一件做完的事。这背后有个常被忽略的判断大部分人的AI 编码停在 Model 层所以永远在聊天真正产生生产力的是补上 Harness 这一层让模型够得着你的工程。本文我就用 dsh把一个编码 Agent 从装好到每天帮我审代码、跑测试、出修复建议完整跑通。所有命令都来自官方文档和社区实测你可以照抄也可以直接拿去写你团队的自动化脚本。一、先理解 dsh 是怎么干活的在敲命令之前先建立三个关键认知这能帮你避开 90% 的新手卡点。我见过太多人卡在网页打不开输入框是灰的这种问题上一小时其实都是没搞懂这三件事1. 终端窗口不能关。dsh web启动的那个进程才是真正干活的Host宿主浏览器只是操作界面。终端一关网页立刻失联——这不是 bug是设计。换句话说你不是在用网页聊天而是在启动一个常驻的本地 Agent 服务然后用浏览器当遥控器。生产环境里有人把它跑成 systemd 用户服务道理就在这。2. 默认只监听本机。它监听127.0.0.1:3080局域网其他设备默认访问不到。这同样是安全设计一个能跑 shell、能读你文件的 Agent不该默认对全网开放。要远程访问得显式声明trustedHosts否则 API 层会拒绝一切非环回请求。3. 端口可换。3080 被占用时用dsh web --port 8080。注意一个 CLI 细节启动器自己的 flag 必须写在最前面它不认识的第一个 token 开始算应用参数。所以dsh --profile web --port 8080是对的而把--port塞到奇怪的位置可能失效。理解了它是常驻服务、不是聊天窗口这个定位后面所有设计会话持久化、轨迹回溯、Headless 批处理就都顺理成章了。二、环境准备与最小启动2.1 环境要求项目要求操作系统Windows / macOS / LinuxNode.js≥ 22.19推荐 Node 24 LTS兼容性最优包管理器npmNode 自带源码构建需 pnpm ≥ 10内存≥ 4 GB磁盘预留 2 GB 以上网络可访问 npm 与模型开放平台注意不支持 Node 23.x。DSH 要求^22.19.0 \|\| 24.0.0这是底层 Cordis 内核的硬性约束它用到了某些只在 22.19 / 24 才稳定的运行时特性。选错版本会直接启动失败报错还不明显所以第一步先node -v确认。macOS 用户可用brew install node24 brew link --overwrite --force node24。2.2 一行命令启动推荐首次体验npx deepseek-ai/dsh webnpx 会自动拉取并运行无需预先安装。首次启动会下载全部依赖根据网速耗时 1–3 分钟属正常。启动成功后终端打印dsh web: http://127.0.0.1:3080浏览器打开这个地址你就进入了 dsh 的 Web 界面。2.3 全局安装日常推荐npminstall-gdeepseek-ai/dsh dsh--versiondsh web2.4 源码构建开发者 / 二次定制如果你要改内核、写原生插件、或跟进最新迭代、参与开源贡献gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harness corepackenable# 启用 pnpmpnpminstallpnpmrun buildpnpmdsh web仓库在package.json里锁定了 pnpm 版本约 11.x需要corepack enable启用对应版本否则可能装出一份不兼容的依赖树。2.5 配置 API KeyDSH 是BYO Model自带模型模式——框架本身不带模型需要你配置一个可用的模型端点。最省事的是 DeepSeek 官方 API打开 DeepSeek 开放平台注册登录并充值少量余额日常试用消耗极低实测 5 个任务在 V4-Flash 上约 3 美分、V4-Pro 约 7 美分。左侧进入 API Keys创建 key。密钥只在创建那一刻显示一次立即复制保存关掉页面就再也看不到了。在 Web 界面设置弹窗中粘贴密钥并保存无需重启即时生效。密钥字段是只写的保存后只能看到脱敏描述符不回显明文。它存储在$DSH_HOME/.credentials.yaml权限 0600。安全规范务必遵守禁止截图泄露密钥、禁止明文写入代码文件、禁止上传到 Git 仓库。$DSH_HOME默认是~/.dshWindows 为C:\Users\你\.dsh里面的sessions、settings.yaml、.credentials.yaml都别提交。2.6 选择工作区新手最常见的卡点DSH 有严格的安全隔离未选中工作区时所有对话输入框是锁定的。这是它默认不信任理念的体现——一个能跑命令的 Agent绝不能在没明确授权目录的情况下乱动文件。界面左侧点击选择工作区 → “ 新增本地文件夹”。安全禁忌禁止选系统盘根目录、系统文件夹、桌面全目录、隐私文件目录。推荐新建一个空白专属文件夹仅用于 Harness 任务处理。选中后输入框自动解锁。2.7 验证部署跑一个只读任务验证一切就绪请读取当前工作区的全部文件与目录结构仅做汇总展示不修改、不新增、不删除任何文件。AI 正常输出目录清单、无报错、无超时即部署完成。这一步同时验证了模型连通 文件读取 工作区授权三件事。三、选对预设四种岗位模式Preset预设是能力组合包——同一种模型挂上不同的工具集和规则就能承担不同的岗位。DSH 内置四种预设这是它组合即一切理念最直接的体现模式工具集适合场景标准模式 Standard全功能文件编辑、Shell、检索、Skills、计划、子代理、工作流功能最完整拿不准就选它代码模式 Code Mode模型编写 TypeScript把多步工具操作组合成一段程序一次执行批量任务效率提升 3–8 倍极简模式 Minimal仅保留核心文件编辑、Shell 工具禁用冗余插件性能评测、轻量化精准调试创造模式 Creator插件热加载、自定义 Agent 模板、内核调试插件开发、私有化工作流定制重要模式决定工具集中途切换会破坏会话可复现性所以新建会话后无法切换模式需提前选择。对编码任务日常用 Standard批量重构/数据处理用 Code Mode做基准测试或想要最干净的上下文时用 Minimal。为什么切换会破坏可复现因为 DSH 的会话是只追加日志日志里记的是当时挂载了哪些能力。换模式等于换了一套能力旧日志就对应不上了。这是它诚实的地方——很多框架假装能无缝切换实则把状态悄悄弄乱。四、第一个真实任务让 Agent 修一个 bug现在用一个具体例子。假设工作区里有个会崩溃的小函数# calc.pydefdivide(a,b):returna/bprint(divide(1,0))我在对话框里输入当前工作区的calc.py运行时会在除以零时崩溃。请阅读代码修复这个问题让函数在除数为零时返回一个有意义的错误信息而不是抛异常。修改后简要说明你做了什么。DSH 的执行轨迹通常是Think模型分析判断要先读文件、再改、再验证。Read调用文件读取工具看到calc.py源码。Write/Edit修改divide函数加入零值保护。Bash可能运行python calc.py验证不再崩溃。Reply用中文总结改动。整个过程你只需要描述要什么不需要告诉它先读文件再改。它自己拆解步骤、调用工具、验证结果——这就是 Agent 和一问一答聊天的本质区别。聊天是你掌舵、模型划桨Agent 是你定目标、模型既掌舵又划桨还自己检查航迹。五、Headless 模式把跑测试变成一行命令Web UI 适合交互式探索但很多编码任务是一次性的。比如你刚改完代码想让 Agent 把测试跑一遍并总结。这时候用Headless无头模式# 先设置环境变量exportDEEPSEEK_API_KEYsk-xxx# 无界面运行跑完打印最终答案并退出dsh--profileheadless把本仓库的测试跑一遍用中文总结失败原因并给出修复建议它的行为是打印最终答案到 stdout然后退出返回退出码exit 0 表示正常。这让它天然适合脚本化和 CI。在 CI 里一条命令搞定自动修测试 输出报告配合非零退出码触发流水线失败非常顺手。社区实测的一个优雅例子cd~/Projects/dsh-playground dsh--profileheadlessCreate fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only.# 输出# 1 2 Fizz 4 Buzz ... FizzBuzzecho$?# 0六秒文件创建、程序运行、答案打印、退出码 0。它只写你启动所在文件夹内的内容默认workspace-write权限stdout 只打印最终消息并且把每一次运行都持久化你之后能在 Web UI 里打开它逐条读到它做了什么——每一个工具调用、每一个 token 数。⚠️ CLI 易错点再强调启动器 flag 在最前。dsh--profileweb--port8080# --port 属于 web 应用OKdsh--profileheadlessrun tests# 引号里算任务dsh--help# 启动器帮助dsh--profileweb--help# web 应用帮助六、Code Mode把多步操作编译成一段 TS这是 DSH 在编码场景里最被低估的能力。在标准模式下模型每调用一次工具都要走一轮思考→调用→等待结果而Code Mode让模型把多个工具操作写成一段 TypeScript 程序一次执行完。为什么这很关键因为很多编码任务是读 A、改 B、跑 C、看 D的序列标准模式里每一步之间模型都要重新加载上下文、重新决策慢且容易在中途跑偏。Code Mode 把它变成先规划好整段程序再执行社区反馈效率提升3–8 倍尤其适合跨多个文件的批量重构比如统一改 import 路径需要循环/条件判断的数据处理比如批量重命名、生成样板代码一连串读-改-验证的确定性操作使用方式在新建会话时选 Code Mode 预设即可。模型会在内部生成 TS 片段借助code-runtime能力族Service Definition worker-thread provider执行后把结果交回。你作为使用者感知到的是它一下子就把活干完了。代价是Code Mode 下轨迹更整块单步可观测性比标准模式弱一点——所以探索未知代码库时我更倾向标准模式做已知结构的批量活时用 Code Mode。七、轨迹面板Trajectory每一步都可回溯DSH 的核心特色之一是Trajectory轨迹面板。它完整记录系统提示词模型推理过程Think工具调用记录参数 返回结果文件修改日志终端命令执行详情逐条可回溯、可排查报错支持按来源筛选、搜索、导出“Every run is traceable”——模型看到的一切、做的一切都记录在只追加append-only的会话日志中。这对编码工作流是刚需当 Agent 改出了你不想要的结果你能精确看到它哪一步读错了文件、哪一步的命令参数写偏了而不是对着最终答案干瞪眼。底部状态栏还会实时显示当前模型、上下文 Token 占用、推理速度 TPS、缓存命中率、工作区权限等级。这些信息帮你判断是不是该压缩上下文了“是不是该换更轻量的模型了”。把轨迹当黑盒录像用是我用 DSH 排查问题的第一习惯——比猜模型在想什么靠谱得多。Web 界面布局也值得记一下左侧是工作区文件树与会话列表自动永久保存支持搜索/重命名/删除/回溯中间是对话区输入框支持引用本地文件、粘贴图片附件右侧是产物预览HTML、文档、图表等底部状态栏是模型与权限信息。右侧的产物预览对让 Agent 生成一份带图表的报告这类任务特别爽——它直接渲染不用你复制 markdown 再转。八、沙箱与权限默认只写工作区编码 Agent 最让人担心的是它会不会把我整个电脑搞乱。DSH 用三档权限模型 操作系统级沙箱来兜底权限档内部名允许操作典型场景只读Read Only只读不能修改任何文件调查、总结、出方案工作区写Workspace Write只能在工作区内写文件日常默认全访问danger-full-access全盘读写无边界高风险操作切换前二次确认注意danger-full-access的内部名已经说明了风险等级——它是危险模式不是高级模式。而且一个关键的认知是权限限制的是写不是看。Workspace Write 只限制写入范围读取文件、联网、查看系统进程不受同等限制。它的手被绑住了但眼睛是自由的。三档权限有真实的操作系统级沙箱支撑Linuxbwrapbubblewrap/ LandlockmacOSSeatbeltWindowsACL 受限令牌这意味着即便 Agent 被诱导去执行rm -rf之类沙箱也会把它框在工作区边界内。另有两个常驻纠偏插件重复无效动作检测防止 Agent 对着同一个失败方案反复重试这是自主 Agent 最常见的 token 黑洞。超时强制中断防止任务无限期运行。这两道机制保证了一个编码 Agent 即使想搞事或被诱导也越不出沙箱边界。安全不是靠相信模型乖是靠它根本出不去。这才是把 Agent 接进真实工程的前提。九、进阶让编码 Agent 提交 PR 的完整工作流真正把 dsh 用进日常是把读代码→改→测→提交串成一条流水线。结合它内置的能力族plan计划让它先输出一份改动计划你 review 后再动手——plan包提供 Plan 协作状态有直接的进入命令和受审查的退出机制。这步能避免它直接大改一通你才发现方向错了。todo待办todo_write工具让它在多文件重构时维护任务清单避免遗漏。git / shell通过shell能力族bash executor seam local impl执行git diff、git add、git commit。subagent子代理把一个大重构拆给多个子代理并行处理不同模块详见本系列后续文章。一个典型的帮我给这个仓库加单元测试的 prompt这个仓库目前没有测试。请1) 用 plan 输出测试方案2) 为src/下的核心函数编写 pytest 单元测试3) 运行pytest确保全绿4) 用 git 提交commit message 遵循 Conventional Commits。不要推送远程。它会自己规划、自己写、自己跑、自己提交全程在轨迹面板里留痕。你最后 review 一下 diff 就行。人类负责定方向 验收Agent 负责执行 验证——这是目前最稳的人机协作分工。十、成本与性能来自社区的实测几个值得记下的真实数据来自多位开发者的独立实测版本约 0.1.0-rc.6/rc.7速度15 个编码子任务在 V4-Flash / V4-Pro / 本地 Gemma-4-26B 上全部通过单任务 2–18 秒。成本整个 5 任务 benchmarkV4-Flash 约 3 美分、V4-Pro 约 7 美分本地模型零成本。相比请人做同样的事几乎可以忽略。遥测默认关闭DSH_TELEMETRY_MODE未设 disabled隐私友好。省成本技巧探索性任务用 V4-Flash需要强推理的复杂重构用 V4-Pro长会话记得让 Agent 用 compaction上下文压缩避免 token 爆炸Headless 批处理任务用 Minimal 预设减少冗余插件开销。没有交互式 TUI启动器是 CLI但交互界面是浏览器。在纯 SSH 远程盒子上这是最大的吐槽点——官方目前没有 TUI 来回应这个需求所以远程机建议用 Headless 本地看轨迹。接口不稳定README 用大写警告会有破坏性变更rc 之间确实会变。所以本文所有 YAML key 我都建议你在自己版本用dsh --profile web --dump-config核实后再依赖。十一、常见问题排查FAQQ1网页打不开127.0.0.1:3080先看终端有没有打印这个地址再看终端进程是否还在关了就失联最后确认没被别的程序占用 3080用--port换一个。Q2输入框是灰的、不能打字没选工作区。左侧选择工作区选一个本地文件夹即可。Q3模型不回复 / 报 MISSING_CREDENTIAL密钥没配好。去设置里重新粘贴并保存或检查$DSH_HOME/.credentials.yaml。Q4Agent 一直在重复同样的失败动作这是重复无效动作检测要兜底的场景。可以手动在 prompt 里让它换一种思路或检查工具返回是否让它误判成功。Q5想换模型设置 → 模型 → 添加提供方。DSH 支持 40 家DeepSeek、Anthropic、OpenAI、Bedrock、Azure、Gemini 等也可以自定义端点公司网关/自建服务器。十二、端到端实战让 Agent 重构一个真实模块前面都是小修小补这一节给一个更接近生产的场景让你看看 DSH 在中等复杂度任务上的真实表现。假设工作区里有个utils.py里面散落着二十多个互不相关的函数日期格式化、文件哈希、重试装饰器、CSV 解析……既没有类型注解也没有测试新人根本不敢动。我给的任务是把utils.py按职责拆成io_utils.py、date_utils.py、decorators.py三个模块给每个公开函数加类型注解保持原有调用方不变为三个新模块各写一份 pytest 单元测试确保pytest全绿最后用 git 提交commit message 遵循 Conventional Commits。先输出 plan 让我确认再动手。它在轨迹面板里的执行大致是这样一段Think规划识别出拆文件是高风险操作先调用plan输出方案——哪些函数归哪个模块、调用方要不要改 import、测试怎么覆盖。我 review plan确认无误回复开始。todo_write它建了一张清单建三个文件 → 迁移函数 → 更新 import → 写测试 → 跑 pytest → 提交。Read / Write逐个读取原函数写入新模块并在原调用处更新 import 路径。Bash跑pytest发现两个测试因边界条件失败它回到 Write 修正类型注解再跑全绿。Bashgitgit add -A git commit -m refactor: split utils.py into focused modules with types and tests。全程我只在两个节点出手确认 plan、最后 review diff。最值钱的能力是你能从轨迹看出它为什么这么拆——它没把retry装饰器误放进io_utils因为它在 Think 阶段就把重试判定为控制流而非IO。这种可解释性是闭源黑盒产品给不了的。十三、settings.yaml 调优把默认模型与推理强度钉死交互式设置适合尝鲜但团队要的是可复现。DSH 的配置落在$DSH_HOME/settings.yaml纯文本、可版本化注意别把.credentials.yaml一起提交。一个典型片段agent-default-model:provider:deepseek-officialmodel:deepseek-v4-proreasoningEffort:max几个关键点reasoningEffort推理强度。复杂重构、需要多步推理的任务开max探索性、轻量任务开low省成本和延迟。这不是 DSH 发明的而是 DeepSeek V4 系列模型原生支持的能力DSH 只是把它暴露成配置。走代理如果走 OpenAI 兼容代理设DEEPSEEK_BASE_URL或自定义 provider 的baseURL框架会自动把请求转过去。视觉模型自定义模型在声明能力之前一律按纯文本对待。要让它接收图片得显式声明input: [text, image]llm-pi-ai:providers:my-gateway:apiKeyEnv:GATEWAY_API_KEYapi:openai-completionsbaseURL:https://gateway.example/v1models:-id:vision-previewinput:[text,image]改完即生效settings.yaml支持热重载不用重启服务。这也是配置即组合理念的体现——大部分行为调整不需要动代码。十四、从一次性到常驻把它跑成系统服务个人尝鲜用dsh web起一个终端进程就够了但要想团队共享一个 Agent 后端或把自己的应用接到它得让它常驻。社区已有成熟做法方案 Asystemd 用户服务Linux。写一个 unit把dsh web跑成后台服务开机自启、崩溃自拉。这样 Web UI 就是个稳定的本地 Agent 网关你的其他脚本/应用都能调用。方案 B嵌进你自己的应用。DSH 的 Web UI 本质上是个 HTTP 服务host 包是 API 网关 HTTP 路由服务器client 包是浏览器端 shell/wire/object 服务。很多开发者直接把它iframe进自己的内部工具旁边放个运行按钮背后用固定的dsh --profile headless ...argv 触发任务。方案 C队列化 headless 任务。把用户提交一个需求变成往队列里塞一条 headless 任务DSH 跑完把结果写回。这种方式特别适合AI 工单自动 PR 审查这类场景。laserlloyd 的实测就是个好范本他把 dsh 跑成 systemd 用户服务再iframe进自己的聊天应用 DisPatch旁边配一个 systemd 单元控制条和默认模型切换器最终得到一个聊天应用里的 DeepSeek Harness bot。这一步的意义是DSH 不再是你一个人的玩具而是一个可以被产品化的 Agent 运行时。十五、DSH 与直接用 API / 其他编码工具的本质区别有人会问“我直接调 DeepSeek API再自己写个循环调工具不也能做编码 Agent 吗“能但你得自己造一遍 DSH 已经造好的轮子会话持久化、轨迹记录、沙箱隔离、权限分层、工具注册表、上下文压缩、子代理调度、审批流……这些每一个单独都不难合起来是个系统工程。DSH 的价值不是它做了你做不了的事”而是它把这套系统工程做成了可组合的零件你不用从零造”。和其他编码工具的区别也清晰vs 纯补全插件Copilot 类那些是你写、它提示主动权在你DSH 是你定目标、它执行并验证主动权在 Agent。互补不替代。vs 闭源编码 AgentClaude Code/Codex能力重叠但 DSH 开放、可插件化、可自建网关闭源产品打磨更细但锁死。vs 自己手搓的 Agent 脚本你手搓的往往是写死的单场景DSH 是可演化的运行时。当你的需求从跑一次测试变成团队共享的 Agent 平台时手搓脚本会迅速变成技术债DSH 反而越用越香。一句话小需求手搓够用真要把 Agent 当基础设施DSH 这类运行时才是正解。十六、写给不同角色的上手建议最后按身份给一句实在的起步建议学生 / 编程初学者把它当不会嫌你笨的结对伙伴。从 Standard 预设开始让它带你读开源项目、解释报错、写小练习。重点不是让它替你写是借它的轨迹学一个成熟工程师怎么拆解问题。在职工程师把它接进你的日常——Headless 跑测试、Code Mode 做批量重构、Trajectory 学别人的代码库。先用 Minimal 预设做基准测试再逐步加能力。技术管理者 / 架构师把它当成团队 Agent 能力底座来评估。重点看它的插件化、会话留痕、沙箱隔离——这三点决定了它能不能进生产。先在小范围试点比如自动 PR 审查验证 ROI 再推广。开源贡献者直接从源码构建pnpm dsh web读packages/和官方AGENTS.md约定从一个小插件或文档 PR 开始。DSH 的一切皆插件让贡献门槛比想象中低。无论哪个角色记住一句话Agent 不会取代你定方向的能力但它会放大你执行的速度。越早学会把目标说清楚、把验收标准定清楚你从 DSH 身上拿到的杠杆就越大。十七、性能与上下文调优清单长会话是编码 Agent 最大的隐性成本来源。上下文越长token 越贵、推理越慢、越容易忘掉早期约定。DSH 提供几条调优路径上下文压缩compactioncompaction包提供 Service Definition basic provider能在上下文临近上限时把历史压成摘要保留关键决策。复杂长任务务必让它开着否则到后期模型会开始忘记你最初的要求。按任务选模型探索性、轻量任务用 V4-Flash快且便宜需要强推理的复杂重构用 V4-Pro开reasoningEffort: max。别所有任务都上最贵的模型——那是 token 黑洞。社区实测 5 任务在 Flash 上约 3 美分、Pro 上约 7 美分差距主要来自这里。用 Minimal 预设做基准性能评测或想要最干净上下文时Minimal 禁用冗余插件减少系统提示和工具描述占用的 token也方便你隔离是不是某个插件在干扰模型。善用引用而非全量粘贴输入框支持引用本地文件模型按需读取比把整个文件贴进对话省上下文也更不容易触发长度限制。缓存命中率看状态栏底部状态栏的缓存命中率能告诉你模型是不是在重复处理相同前缀。命中率低说明你的任务切分太碎可以合并成更大的批次。这些不是玄学是把 Agent 当服务来运营的基本功。把它当成你团队的AI 资源成本仪表盘每月复盘一次能砍掉不少不必要的开销。我见过团队因为没开 compaction一个长会话烧掉普通人一周的额度——这种坑看一眼状态栏就能提前发现。十八、把 DSH 嵌进你的开发生命周期一个 Agent 最大的价值不是你手动叫它干一次而是它成为你开发流程的一环。几个落地姿势按投入从低到高AI 代码审查 bot在 PR 创建时触发一条 headless 任务让 DSH 读 diff、跑相关测试、生成审查意见贴回 PR。比人工 review 快且 24 小时在线特别适合半夜合入的小 PR 没人看的团队。Pre-commit 守卫在 pre-commit hook 里跑一条轻量 headless 任务检查这次改动是否引入了明显回归拦在本地而不是等 CI 红。注意只做快且确定的检查重活留给 CI。需求转任务把产品需求文档丢给 DSH用 Minimal 或 Standard 预设让它拆成带验收标准的开发任务清单导入你们的项目管理工具。这一步能把需求→任务的转化时间从半天压到十分钟。Onboarding 助手新人问这个模块干嘛的“这个函数为什么这么写”DSH 读代码库用中文讲清楚比翻过时文档快得多也不会因为怕问 dumb question而不敢开口。这些场景的共同点是把 DSH 当可调用的 Agent 服务用而不是我坐在前面聊天的对象。一旦你切换到这个视角前面讲的 Headless、systemd 常驻、iframe 嵌入全部串起来了——它们存在的目的就是让 Agent 能被别的程序调用。这层认知是从玩具到基础设施的分水岭。十九、成本账单与红线讲完能力落地点永远是值不值和别出事。给两份清单。一份成本账单社区实测口径一个中等重构任务人工约 3 小时、容易引入回归DSH Headless V4-Pro 跑完约 7 美分、6–18 秒轨迹全留痕。差距不在贵不贵在于可复现、可审计、可批量。当这类任务一天发生十几次Agent 的边际成本趋近于零而人力的边际成本不降。这就是为什么Agent 化在高频、结构化任务上 ROI 最高。几条红线务必守住绝不把$DSH_HOME/.credentials.yaml提交到 Git——它存明文密钥0600 权限。默认用Workspace Write非必要不开danger-full-access开之前问自己这一步真的需要碰工作区外的东西吗。让 Agent 碰生产数据/资金操作前必须过交互审批 seam绝不静默放行。长会话务必开compaction否则上下文膨胀会悄悄推高成本、拉低质量。对外交付的改动永远 human review diff 再合入——Agent 是执行者不是责任人。这五条不是保守是把强力工具用久的底线。守住它们DSH 才是杠杆破了任何一条它就是隐患。二十、从个人玩具到团队基础设施一份落地路线图前面讲的都是能力最后给一份可执行的落地路线图照着走能少踩半年坑。分四个阶段每个阶段都有明确的毕业标准阶段一个人提效第 1–2 周。目标你个人用 DSH 替代 30% 的机械编码劳动。动作装好dsh web用 Standard 预设跑通读代码、改 bug、跑测试用 Headless 把跑测试总结变成一行命令。毕业标准你连续三天没手动pytest而是让 Agent 跑的。阶段二流程嵌入第 3–6 周。目标把 DSH 接进你的开发流程。动作用 Code Mode 做批量重构用 Trajectory 做代码库 onboarving试一条 headless 的 PR 审查。毕业标准团队有人开始顺手用你的 headless 脚本。阶段三团队共享第 2–3 月。目标团队共享一个 Agent 后端。动作用 systemd/容器把它跑成常驻服务写自己的工具插件比如公司内部的 lint、部署、监控命令用--dump-config确保组合可复现。毕业标准新人有AI 审查 bot兜底且配置能版本化。阶段四平台化半年。目标DSH 成为团队 Agent 基础设施。动作基于 Cordis 写自定义能力包capability seam把审批、审计、成本控制做成公司标准插件评估是否贡献回上游。毕业标准换模型/换工具不需要改业务代码只改一层 patch。这套路线图的精髓是每阶段都先验证 ROI 再往下走——别一上来就搞平台化那会死在前期复杂度上。DSH 的插件化让你能小步快跑这是它相比闭源成品最大的战略优势。写在最后回头看DSH 最打动我的不是它能改代码而是它把一个能自我重配而不 corruption 自身状态的运行时做成了开放底座。你今天用它跑测试明天挂个自己的工具插件后天把它跑成团队服务——全都不用改它的核心。这种越用越自由的体验是闭源成品给不了的。本篇是实战系列的第 1 篇重在跑通。后面我会带你钻进它的架构、插件、会话、Headless、安全、多 Agent直到你能基于它搭自己的东西。如果这篇让你第一次真的让 Agent 把活干完了那它的使命就达到了。结语从会聊天到能干活的只差一层 Harness回到开头的公式——Agent Model Harness。大部分人卡在只有 Model的阶段模型很聪明但够不着你的工程。DSH 的价值就是把够不着变成随手就能让它干活。本文我们跑通了最小启动 → 选预设 → 修 bug → Headless 跑测试 → Code Mode 提效 → 轨迹回溯 → 沙箱兜底 → 串成 PR 流水线 → 成本与排错。这已经覆盖了一个编码 Agent 80% 的日常。剩下 20%——多 Agent 协作、自定义工具、二次开发——本系列后续会逐一展开。下一篇我会把 DSH 和 AutoGPT、LangGraph、MetaGPT、CrewAI 摆到一起讲清楚Agent 框架到底怎么选——什么时候该用 DSH什么时候它反而是错的选择。如果这篇对你有用点个关注我会持续更新 DeepSeek Harness 的实战系列概念 / 教程 / 架构 / 插件 / 本文 / 框架对比 / 会话管理 / Headless 接入 CI / 自定义工具 / 模型适配 / Web 协同 / 安全沙箱 / 多 Agent / 二次开发。有问题欢迎在评论区交流我会挑典型的回。本文基于 deepseek-ai/deepseek-harness 官方仓库、官方docs/architecture.md、deepseek-ai/cordis及多位社区开发者laserlloyd、jb51、掘金/SSD Nodes 教程2026-08 的实测整理。dsh 处于开发者预览阶段命令与配置请以你安装版本的实际输出为准。 DeepSeek Harness 实战：用 dsh 从零搭一个“能干活“的编码 Agent
DeepSeek Harness 实战用 dsh 从零搭一个能干活的编码 Agent系列导航本篇是 DeepSeek Harness 实战系列第 1 篇。前序已发布的《概念综述》《使用教程》《系统架构及运行原理》《插件机制全解》可在我的主页回看。本文不堆概念直接把一个会读代码、会改文件、会跑测试、会提交的编码 Agent 从零跑通并讲清每一步背后的取舍。引言你缺的不是模型是手很多开发者第一次接触大模型写代码时的体验是这样的把需求贴给网页版对话它返给你一段看起来很对的代码你复制进项目跑一下报错再贴回去让它改来回几个回合上下文被稀释最后你干脆自己手搓了。问题不在模型不会写而在于模型和真实世界之间缺了一层执行身体——它看不到你的文件树改不了你的代码跑不了你的测试连这个文件现在长什么样都不知道。 DeepSeek 在 2026-08-13 开源的DeepSeek Harness命令行名dsh干的就是这件事它把模型和在真实工程里持续干活的能力缝到一起提出了那句贯穿整个项目的最核心公式——Agent Model HarnessModel 是灵魂负责思考和推理Harness 是身体让它理解环境、使用工具、在真实世界里把一件事干完。网页版对话 AI 交付的是一段话而 Harness 交付的是一件做完的事。这背后有个常被忽略的判断大部分人的AI 编码停在 Model 层所以永远在聊天真正产生生产力的是补上 Harness 这一层让模型够得着你的工程。本文我就用 dsh把一个编码 Agent 从装好到每天帮我审代码、跑测试、出修复建议完整跑通。所有命令都来自官方文档和社区实测你可以照抄也可以直接拿去写你团队的自动化脚本。一、先理解 dsh 是怎么干活的在敲命令之前先建立三个关键认知这能帮你避开 90% 的新手卡点。我见过太多人卡在网页打不开输入框是灰的这种问题上一小时其实都是没搞懂这三件事1. 终端窗口不能关。dsh web启动的那个进程才是真正干活的Host宿主浏览器只是操作界面。终端一关网页立刻失联——这不是 bug是设计。换句话说你不是在用网页聊天而是在启动一个常驻的本地 Agent 服务然后用浏览器当遥控器。生产环境里有人把它跑成 systemd 用户服务道理就在这。2. 默认只监听本机。它监听127.0.0.1:3080局域网其他设备默认访问不到。这同样是安全设计一个能跑 shell、能读你文件的 Agent不该默认对全网开放。要远程访问得显式声明trustedHosts否则 API 层会拒绝一切非环回请求。3. 端口可换。3080 被占用时用dsh web --port 8080。注意一个 CLI 细节启动器自己的 flag 必须写在最前面它不认识的第一个 token 开始算应用参数。所以dsh --profile web --port 8080是对的而把--port塞到奇怪的位置可能失效。理解了它是常驻服务、不是聊天窗口这个定位后面所有设计会话持久化、轨迹回溯、Headless 批处理就都顺理成章了。二、环境准备与最小启动2.1 环境要求项目要求操作系统Windows / macOS / LinuxNode.js≥ 22.19推荐 Node 24 LTS兼容性最优包管理器npmNode 自带源码构建需 pnpm ≥ 10内存≥ 4 GB磁盘预留 2 GB 以上网络可访问 npm 与模型开放平台注意不支持 Node 23.x。DSH 要求^22.19.0 \|\| 24.0.0这是底层 Cordis 内核的硬性约束它用到了某些只在 22.19 / 24 才稳定的运行时特性。选错版本会直接启动失败报错还不明显所以第一步先node -v确认。macOS 用户可用brew install node24 brew link --overwrite --force node24。2.2 一行命令启动推荐首次体验npx deepseek-ai/dsh webnpx 会自动拉取并运行无需预先安装。首次启动会下载全部依赖根据网速耗时 1–3 分钟属正常。启动成功后终端打印dsh web: http://127.0.0.1:3080浏览器打开这个地址你就进入了 dsh 的 Web 界面。2.3 全局安装日常推荐npminstall-gdeepseek-ai/dsh dsh--versiondsh web2.4 源码构建开发者 / 二次定制如果你要改内核、写原生插件、或跟进最新迭代、参与开源贡献gitclone https://github.com/deepseek-ai/deepseek-harness.gitcddeepseek-harness corepackenable# 启用 pnpmpnpminstallpnpmrun buildpnpmdsh web仓库在package.json里锁定了 pnpm 版本约 11.x需要corepack enable启用对应版本否则可能装出一份不兼容的依赖树。2.5 配置 API KeyDSH 是BYO Model自带模型模式——框架本身不带模型需要你配置一个可用的模型端点。最省事的是 DeepSeek 官方 API打开 DeepSeek 开放平台注册登录并充值少量余额日常试用消耗极低实测 5 个任务在 V4-Flash 上约 3 美分、V4-Pro 约 7 美分。左侧进入 API Keys创建 key。密钥只在创建那一刻显示一次立即复制保存关掉页面就再也看不到了。在 Web 界面设置弹窗中粘贴密钥并保存无需重启即时生效。密钥字段是只写的保存后只能看到脱敏描述符不回显明文。它存储在$DSH_HOME/.credentials.yaml权限 0600。安全规范务必遵守禁止截图泄露密钥、禁止明文写入代码文件、禁止上传到 Git 仓库。$DSH_HOME默认是~/.dshWindows 为C:\Users\你\.dsh里面的sessions、settings.yaml、.credentials.yaml都别提交。2.6 选择工作区新手最常见的卡点DSH 有严格的安全隔离未选中工作区时所有对话输入框是锁定的。这是它默认不信任理念的体现——一个能跑命令的 Agent绝不能在没明确授权目录的情况下乱动文件。界面左侧点击选择工作区 → “ 新增本地文件夹”。安全禁忌禁止选系统盘根目录、系统文件夹、桌面全目录、隐私文件目录。推荐新建一个空白专属文件夹仅用于 Harness 任务处理。选中后输入框自动解锁。2.7 验证部署跑一个只读任务验证一切就绪请读取当前工作区的全部文件与目录结构仅做汇总展示不修改、不新增、不删除任何文件。AI 正常输出目录清单、无报错、无超时即部署完成。这一步同时验证了模型连通 文件读取 工作区授权三件事。三、选对预设四种岗位模式Preset预设是能力组合包——同一种模型挂上不同的工具集和规则就能承担不同的岗位。DSH 内置四种预设这是它组合即一切理念最直接的体现模式工具集适合场景标准模式 Standard全功能文件编辑、Shell、检索、Skills、计划、子代理、工作流功能最完整拿不准就选它代码模式 Code Mode模型编写 TypeScript把多步工具操作组合成一段程序一次执行批量任务效率提升 3–8 倍极简模式 Minimal仅保留核心文件编辑、Shell 工具禁用冗余插件性能评测、轻量化精准调试创造模式 Creator插件热加载、自定义 Agent 模板、内核调试插件开发、私有化工作流定制重要模式决定工具集中途切换会破坏会话可复现性所以新建会话后无法切换模式需提前选择。对编码任务日常用 Standard批量重构/数据处理用 Code Mode做基准测试或想要最干净的上下文时用 Minimal。为什么切换会破坏可复现因为 DSH 的会话是只追加日志日志里记的是当时挂载了哪些能力。换模式等于换了一套能力旧日志就对应不上了。这是它诚实的地方——很多框架假装能无缝切换实则把状态悄悄弄乱。四、第一个真实任务让 Agent 修一个 bug现在用一个具体例子。假设工作区里有个会崩溃的小函数# calc.pydefdivide(a,b):returna/bprint(divide(1,0))我在对话框里输入当前工作区的calc.py运行时会在除以零时崩溃。请阅读代码修复这个问题让函数在除数为零时返回一个有意义的错误信息而不是抛异常。修改后简要说明你做了什么。DSH 的执行轨迹通常是Think模型分析判断要先读文件、再改、再验证。Read调用文件读取工具看到calc.py源码。Write/Edit修改divide函数加入零值保护。Bash可能运行python calc.py验证不再崩溃。Reply用中文总结改动。整个过程你只需要描述要什么不需要告诉它先读文件再改。它自己拆解步骤、调用工具、验证结果——这就是 Agent 和一问一答聊天的本质区别。聊天是你掌舵、模型划桨Agent 是你定目标、模型既掌舵又划桨还自己检查航迹。五、Headless 模式把跑测试变成一行命令Web UI 适合交互式探索但很多编码任务是一次性的。比如你刚改完代码想让 Agent 把测试跑一遍并总结。这时候用Headless无头模式# 先设置环境变量exportDEEPSEEK_API_KEYsk-xxx# 无界面运行跑完打印最终答案并退出dsh--profileheadless把本仓库的测试跑一遍用中文总结失败原因并给出修复建议它的行为是打印最终答案到 stdout然后退出返回退出码exit 0 表示正常。这让它天然适合脚本化和 CI。在 CI 里一条命令搞定自动修测试 输出报告配合非零退出码触发流水线失败非常顺手。社区实测的一个优雅例子cd~/Projects/dsh-playground dsh--profileheadlessCreate fizz.py that prints FizzBuzz for 1..15 and run it; reply with the program output only.# 输出# 1 2 Fizz 4 Buzz ... FizzBuzzecho$?# 0六秒文件创建、程序运行、答案打印、退出码 0。它只写你启动所在文件夹内的内容默认workspace-write权限stdout 只打印最终消息并且把每一次运行都持久化你之后能在 Web UI 里打开它逐条读到它做了什么——每一个工具调用、每一个 token 数。⚠️ CLI 易错点再强调启动器 flag 在最前。dsh--profileweb--port8080# --port 属于 web 应用OKdsh--profileheadlessrun tests# 引号里算任务dsh--help# 启动器帮助dsh--profileweb--help# web 应用帮助六、Code Mode把多步操作编译成一段 TS这是 DSH 在编码场景里最被低估的能力。在标准模式下模型每调用一次工具都要走一轮思考→调用→等待结果而Code Mode让模型把多个工具操作写成一段 TypeScript 程序一次执行完。为什么这很关键因为很多编码任务是读 A、改 B、跑 C、看 D的序列标准模式里每一步之间模型都要重新加载上下文、重新决策慢且容易在中途跑偏。Code Mode 把它变成先规划好整段程序再执行社区反馈效率提升3–8 倍尤其适合跨多个文件的批量重构比如统一改 import 路径需要循环/条件判断的数据处理比如批量重命名、生成样板代码一连串读-改-验证的确定性操作使用方式在新建会话时选 Code Mode 预设即可。模型会在内部生成 TS 片段借助code-runtime能力族Service Definition worker-thread provider执行后把结果交回。你作为使用者感知到的是它一下子就把活干完了。代价是Code Mode 下轨迹更整块单步可观测性比标准模式弱一点——所以探索未知代码库时我更倾向标准模式做已知结构的批量活时用 Code Mode。七、轨迹面板Trajectory每一步都可回溯DSH 的核心特色之一是Trajectory轨迹面板。它完整记录系统提示词模型推理过程Think工具调用记录参数 返回结果文件修改日志终端命令执行详情逐条可回溯、可排查报错支持按来源筛选、搜索、导出“Every run is traceable”——模型看到的一切、做的一切都记录在只追加append-only的会话日志中。这对编码工作流是刚需当 Agent 改出了你不想要的结果你能精确看到它哪一步读错了文件、哪一步的命令参数写偏了而不是对着最终答案干瞪眼。底部状态栏还会实时显示当前模型、上下文 Token 占用、推理速度 TPS、缓存命中率、工作区权限等级。这些信息帮你判断是不是该压缩上下文了“是不是该换更轻量的模型了”。把轨迹当黑盒录像用是我用 DSH 排查问题的第一习惯——比猜模型在想什么靠谱得多。Web 界面布局也值得记一下左侧是工作区文件树与会话列表自动永久保存支持搜索/重命名/删除/回溯中间是对话区输入框支持引用本地文件、粘贴图片附件右侧是产物预览HTML、文档、图表等底部状态栏是模型与权限信息。右侧的产物预览对让 Agent 生成一份带图表的报告这类任务特别爽——它直接渲染不用你复制 markdown 再转。八、沙箱与权限默认只写工作区编码 Agent 最让人担心的是它会不会把我整个电脑搞乱。DSH 用三档权限模型 操作系统级沙箱来兜底权限档内部名允许操作典型场景只读Read Only只读不能修改任何文件调查、总结、出方案工作区写Workspace Write只能在工作区内写文件日常默认全访问danger-full-access全盘读写无边界高风险操作切换前二次确认注意danger-full-access的内部名已经说明了风险等级——它是危险模式不是高级模式。而且一个关键的认知是权限限制的是写不是看。Workspace Write 只限制写入范围读取文件、联网、查看系统进程不受同等限制。它的手被绑住了但眼睛是自由的。三档权限有真实的操作系统级沙箱支撑Linuxbwrapbubblewrap/ LandlockmacOSSeatbeltWindowsACL 受限令牌这意味着即便 Agent 被诱导去执行rm -rf之类沙箱也会把它框在工作区边界内。另有两个常驻纠偏插件重复无效动作检测防止 Agent 对着同一个失败方案反复重试这是自主 Agent 最常见的 token 黑洞。超时强制中断防止任务无限期运行。这两道机制保证了一个编码 Agent 即使想搞事或被诱导也越不出沙箱边界。安全不是靠相信模型乖是靠它根本出不去。这才是把 Agent 接进真实工程的前提。九、进阶让编码 Agent 提交 PR 的完整工作流真正把 dsh 用进日常是把读代码→改→测→提交串成一条流水线。结合它内置的能力族plan计划让它先输出一份改动计划你 review 后再动手——plan包提供 Plan 协作状态有直接的进入命令和受审查的退出机制。这步能避免它直接大改一通你才发现方向错了。todo待办todo_write工具让它在多文件重构时维护任务清单避免遗漏。git / shell通过shell能力族bash executor seam local impl执行git diff、git add、git commit。subagent子代理把一个大重构拆给多个子代理并行处理不同模块详见本系列后续文章。一个典型的帮我给这个仓库加单元测试的 prompt这个仓库目前没有测试。请1) 用 plan 输出测试方案2) 为src/下的核心函数编写 pytest 单元测试3) 运行pytest确保全绿4) 用 git 提交commit message 遵循 Conventional Commits。不要推送远程。它会自己规划、自己写、自己跑、自己提交全程在轨迹面板里留痕。你最后 review 一下 diff 就行。人类负责定方向 验收Agent 负责执行 验证——这是目前最稳的人机协作分工。十、成本与性能来自社区的实测几个值得记下的真实数据来自多位开发者的独立实测版本约 0.1.0-rc.6/rc.7速度15 个编码子任务在 V4-Flash / V4-Pro / 本地 Gemma-4-26B 上全部通过单任务 2–18 秒。成本整个 5 任务 benchmarkV4-Flash 约 3 美分、V4-Pro 约 7 美分本地模型零成本。相比请人做同样的事几乎可以忽略。遥测默认关闭DSH_TELEMETRY_MODE未设 disabled隐私友好。省成本技巧探索性任务用 V4-Flash需要强推理的复杂重构用 V4-Pro长会话记得让 Agent 用 compaction上下文压缩避免 token 爆炸Headless 批处理任务用 Minimal 预设减少冗余插件开销。没有交互式 TUI启动器是 CLI但交互界面是浏览器。在纯 SSH 远程盒子上这是最大的吐槽点——官方目前没有 TUI 来回应这个需求所以远程机建议用 Headless 本地看轨迹。接口不稳定README 用大写警告会有破坏性变更rc 之间确实会变。所以本文所有 YAML key 我都建议你在自己版本用dsh --profile web --dump-config核实后再依赖。十一、常见问题排查FAQQ1网页打不开127.0.0.1:3080先看终端有没有打印这个地址再看终端进程是否还在关了就失联最后确认没被别的程序占用 3080用--port换一个。Q2输入框是灰的、不能打字没选工作区。左侧选择工作区选一个本地文件夹即可。Q3模型不回复 / 报 MISSING_CREDENTIAL密钥没配好。去设置里重新粘贴并保存或检查$DSH_HOME/.credentials.yaml。Q4Agent 一直在重复同样的失败动作这是重复无效动作检测要兜底的场景。可以手动在 prompt 里让它换一种思路或检查工具返回是否让它误判成功。Q5想换模型设置 → 模型 → 添加提供方。DSH 支持 40 家DeepSeek、Anthropic、OpenAI、Bedrock、Azure、Gemini 等也可以自定义端点公司网关/自建服务器。十二、端到端实战让 Agent 重构一个真实模块前面都是小修小补这一节给一个更接近生产的场景让你看看 DSH 在中等复杂度任务上的真实表现。假设工作区里有个utils.py里面散落着二十多个互不相关的函数日期格式化、文件哈希、重试装饰器、CSV 解析……既没有类型注解也没有测试新人根本不敢动。我给的任务是把utils.py按职责拆成io_utils.py、date_utils.py、decorators.py三个模块给每个公开函数加类型注解保持原有调用方不变为三个新模块各写一份 pytest 单元测试确保pytest全绿最后用 git 提交commit message 遵循 Conventional Commits。先输出 plan 让我确认再动手。它在轨迹面板里的执行大致是这样一段Think规划识别出拆文件是高风险操作先调用plan输出方案——哪些函数归哪个模块、调用方要不要改 import、测试怎么覆盖。我 review plan确认无误回复开始。todo_write它建了一张清单建三个文件 → 迁移函数 → 更新 import → 写测试 → 跑 pytest → 提交。Read / Write逐个读取原函数写入新模块并在原调用处更新 import 路径。Bash跑pytest发现两个测试因边界条件失败它回到 Write 修正类型注解再跑全绿。Bashgitgit add -A git commit -m refactor: split utils.py into focused modules with types and tests。全程我只在两个节点出手确认 plan、最后 review diff。最值钱的能力是你能从轨迹看出它为什么这么拆——它没把retry装饰器误放进io_utils因为它在 Think 阶段就把重试判定为控制流而非IO。这种可解释性是闭源黑盒产品给不了的。十三、settings.yaml 调优把默认模型与推理强度钉死交互式设置适合尝鲜但团队要的是可复现。DSH 的配置落在$DSH_HOME/settings.yaml纯文本、可版本化注意别把.credentials.yaml一起提交。一个典型片段agent-default-model:provider:deepseek-officialmodel:deepseek-v4-proreasoningEffort:max几个关键点reasoningEffort推理强度。复杂重构、需要多步推理的任务开max探索性、轻量任务开low省成本和延迟。这不是 DSH 发明的而是 DeepSeek V4 系列模型原生支持的能力DSH 只是把它暴露成配置。走代理如果走 OpenAI 兼容代理设DEEPSEEK_BASE_URL或自定义 provider 的baseURL框架会自动把请求转过去。视觉模型自定义模型在声明能力之前一律按纯文本对待。要让它接收图片得显式声明input: [text, image]llm-pi-ai:providers:my-gateway:apiKeyEnv:GATEWAY_API_KEYapi:openai-completionsbaseURL:https://gateway.example/v1models:-id:vision-previewinput:[text,image]改完即生效settings.yaml支持热重载不用重启服务。这也是配置即组合理念的体现——大部分行为调整不需要动代码。十四、从一次性到常驻把它跑成系统服务个人尝鲜用dsh web起一个终端进程就够了但要想团队共享一个 Agent 后端或把自己的应用接到它得让它常驻。社区已有成熟做法方案 Asystemd 用户服务Linux。写一个 unit把dsh web跑成后台服务开机自启、崩溃自拉。这样 Web UI 就是个稳定的本地 Agent 网关你的其他脚本/应用都能调用。方案 B嵌进你自己的应用。DSH 的 Web UI 本质上是个 HTTP 服务host 包是 API 网关 HTTP 路由服务器client 包是浏览器端 shell/wire/object 服务。很多开发者直接把它iframe进自己的内部工具旁边放个运行按钮背后用固定的dsh --profile headless ...argv 触发任务。方案 C队列化 headless 任务。把用户提交一个需求变成往队列里塞一条 headless 任务DSH 跑完把结果写回。这种方式特别适合AI 工单自动 PR 审查这类场景。laserlloyd 的实测就是个好范本他把 dsh 跑成 systemd 用户服务再iframe进自己的聊天应用 DisPatch旁边配一个 systemd 单元控制条和默认模型切换器最终得到一个聊天应用里的 DeepSeek Harness bot。这一步的意义是DSH 不再是你一个人的玩具而是一个可以被产品化的 Agent 运行时。十五、DSH 与直接用 API / 其他编码工具的本质区别有人会问“我直接调 DeepSeek API再自己写个循环调工具不也能做编码 Agent 吗“能但你得自己造一遍 DSH 已经造好的轮子会话持久化、轨迹记录、沙箱隔离、权限分层、工具注册表、上下文压缩、子代理调度、审批流……这些每一个单独都不难合起来是个系统工程。DSH 的价值不是它做了你做不了的事”而是它把这套系统工程做成了可组合的零件你不用从零造”。和其他编码工具的区别也清晰vs 纯补全插件Copilot 类那些是你写、它提示主动权在你DSH 是你定目标、它执行并验证主动权在 Agent。互补不替代。vs 闭源编码 AgentClaude Code/Codex能力重叠但 DSH 开放、可插件化、可自建网关闭源产品打磨更细但锁死。vs 自己手搓的 Agent 脚本你手搓的往往是写死的单场景DSH 是可演化的运行时。当你的需求从跑一次测试变成团队共享的 Agent 平台时手搓脚本会迅速变成技术债DSH 反而越用越香。一句话小需求手搓够用真要把 Agent 当基础设施DSH 这类运行时才是正解。十六、写给不同角色的上手建议最后按身份给一句实在的起步建议学生 / 编程初学者把它当不会嫌你笨的结对伙伴。从 Standard 预设开始让它带你读开源项目、解释报错、写小练习。重点不是让它替你写是借它的轨迹学一个成熟工程师怎么拆解问题。在职工程师把它接进你的日常——Headless 跑测试、Code Mode 做批量重构、Trajectory 学别人的代码库。先用 Minimal 预设做基准测试再逐步加能力。技术管理者 / 架构师把它当成团队 Agent 能力底座来评估。重点看它的插件化、会话留痕、沙箱隔离——这三点决定了它能不能进生产。先在小范围试点比如自动 PR 审查验证 ROI 再推广。开源贡献者直接从源码构建pnpm dsh web读packages/和官方AGENTS.md约定从一个小插件或文档 PR 开始。DSH 的一切皆插件让贡献门槛比想象中低。无论哪个角色记住一句话Agent 不会取代你定方向的能力但它会放大你执行的速度。越早学会把目标说清楚、把验收标准定清楚你从 DSH 身上拿到的杠杆就越大。十七、性能与上下文调优清单长会话是编码 Agent 最大的隐性成本来源。上下文越长token 越贵、推理越慢、越容易忘掉早期约定。DSH 提供几条调优路径上下文压缩compactioncompaction包提供 Service Definition basic provider能在上下文临近上限时把历史压成摘要保留关键决策。复杂长任务务必让它开着否则到后期模型会开始忘记你最初的要求。按任务选模型探索性、轻量任务用 V4-Flash快且便宜需要强推理的复杂重构用 V4-Pro开reasoningEffort: max。别所有任务都上最贵的模型——那是 token 黑洞。社区实测 5 任务在 Flash 上约 3 美分、Pro 上约 7 美分差距主要来自这里。用 Minimal 预设做基准性能评测或想要最干净上下文时Minimal 禁用冗余插件减少系统提示和工具描述占用的 token也方便你隔离是不是某个插件在干扰模型。善用引用而非全量粘贴输入框支持引用本地文件模型按需读取比把整个文件贴进对话省上下文也更不容易触发长度限制。缓存命中率看状态栏底部状态栏的缓存命中率能告诉你模型是不是在重复处理相同前缀。命中率低说明你的任务切分太碎可以合并成更大的批次。这些不是玄学是把 Agent 当服务来运营的基本功。把它当成你团队的AI 资源成本仪表盘每月复盘一次能砍掉不少不必要的开销。我见过团队因为没开 compaction一个长会话烧掉普通人一周的额度——这种坑看一眼状态栏就能提前发现。十八、把 DSH 嵌进你的开发生命周期一个 Agent 最大的价值不是你手动叫它干一次而是它成为你开发流程的一环。几个落地姿势按投入从低到高AI 代码审查 bot在 PR 创建时触发一条 headless 任务让 DSH 读 diff、跑相关测试、生成审查意见贴回 PR。比人工 review 快且 24 小时在线特别适合半夜合入的小 PR 没人看的团队。Pre-commit 守卫在 pre-commit hook 里跑一条轻量 headless 任务检查这次改动是否引入了明显回归拦在本地而不是等 CI 红。注意只做快且确定的检查重活留给 CI。需求转任务把产品需求文档丢给 DSH用 Minimal 或 Standard 预设让它拆成带验收标准的开发任务清单导入你们的项目管理工具。这一步能把需求→任务的转化时间从半天压到十分钟。Onboarding 助手新人问这个模块干嘛的“这个函数为什么这么写”DSH 读代码库用中文讲清楚比翻过时文档快得多也不会因为怕问 dumb question而不敢开口。这些场景的共同点是把 DSH 当可调用的 Agent 服务用而不是我坐在前面聊天的对象。一旦你切换到这个视角前面讲的 Headless、systemd 常驻、iframe 嵌入全部串起来了——它们存在的目的就是让 Agent 能被别的程序调用。这层认知是从玩具到基础设施的分水岭。十九、成本账单与红线讲完能力落地点永远是值不值和别出事。给两份清单。一份成本账单社区实测口径一个中等重构任务人工约 3 小时、容易引入回归DSH Headless V4-Pro 跑完约 7 美分、6–18 秒轨迹全留痕。差距不在贵不贵在于可复现、可审计、可批量。当这类任务一天发生十几次Agent 的边际成本趋近于零而人力的边际成本不降。这就是为什么Agent 化在高频、结构化任务上 ROI 最高。几条红线务必守住绝不把$DSH_HOME/.credentials.yaml提交到 Git——它存明文密钥0600 权限。默认用Workspace Write非必要不开danger-full-access开之前问自己这一步真的需要碰工作区外的东西吗。让 Agent 碰生产数据/资金操作前必须过交互审批 seam绝不静默放行。长会话务必开compaction否则上下文膨胀会悄悄推高成本、拉低质量。对外交付的改动永远 human review diff 再合入——Agent 是执行者不是责任人。这五条不是保守是把强力工具用久的底线。守住它们DSH 才是杠杆破了任何一条它就是隐患。二十、从个人玩具到团队基础设施一份落地路线图前面讲的都是能力最后给一份可执行的落地路线图照着走能少踩半年坑。分四个阶段每个阶段都有明确的毕业标准阶段一个人提效第 1–2 周。目标你个人用 DSH 替代 30% 的机械编码劳动。动作装好dsh web用 Standard 预设跑通读代码、改 bug、跑测试用 Headless 把跑测试总结变成一行命令。毕业标准你连续三天没手动pytest而是让 Agent 跑的。阶段二流程嵌入第 3–6 周。目标把 DSH 接进你的开发流程。动作用 Code Mode 做批量重构用 Trajectory 做代码库 onboarving试一条 headless 的 PR 审查。毕业标准团队有人开始顺手用你的 headless 脚本。阶段三团队共享第 2–3 月。目标团队共享一个 Agent 后端。动作用 systemd/容器把它跑成常驻服务写自己的工具插件比如公司内部的 lint、部署、监控命令用--dump-config确保组合可复现。毕业标准新人有AI 审查 bot兜底且配置能版本化。阶段四平台化半年。目标DSH 成为团队 Agent 基础设施。动作基于 Cordis 写自定义能力包capability seam把审批、审计、成本控制做成公司标准插件评估是否贡献回上游。毕业标准换模型/换工具不需要改业务代码只改一层 patch。这套路线图的精髓是每阶段都先验证 ROI 再往下走——别一上来就搞平台化那会死在前期复杂度上。DSH 的插件化让你能小步快跑这是它相比闭源成品最大的战略优势。写在最后回头看DSH 最打动我的不是它能改代码而是它把一个能自我重配而不 corruption 自身状态的运行时做成了开放底座。你今天用它跑测试明天挂个自己的工具插件后天把它跑成团队服务——全都不用改它的核心。这种越用越自由的体验是闭源成品给不了的。本篇是实战系列的第 1 篇重在跑通。后面我会带你钻进它的架构、插件、会话、Headless、安全、多 Agent直到你能基于它搭自己的东西。如果这篇让你第一次真的让 Agent 把活干完了那它的使命就达到了。结语从会聊天到能干活的只差一层 Harness回到开头的公式——Agent Model Harness。大部分人卡在只有 Model的阶段模型很聪明但够不着你的工程。DSH 的价值就是把够不着变成随手就能让它干活。本文我们跑通了最小启动 → 选预设 → 修 bug → Headless 跑测试 → Code Mode 提效 → 轨迹回溯 → 沙箱兜底 → 串成 PR 流水线 → 成本与排错。这已经覆盖了一个编码 Agent 80% 的日常。剩下 20%——多 Agent 协作、自定义工具、二次开发——本系列后续会逐一展开。下一篇我会把 DSH 和 AutoGPT、LangGraph、MetaGPT、CrewAI 摆到一起讲清楚Agent 框架到底怎么选——什么时候该用 DSH什么时候它反而是错的选择。如果这篇对你有用点个关注我会持续更新 DeepSeek Harness 的实战系列概念 / 教程 / 架构 / 插件 / 本文 / 框架对比 / 会话管理 / Headless 接入 CI / 自定义工具 / 模型适配 / Web 协同 / 安全沙箱 / 多 Agent / 二次开发。有问题欢迎在评论区交流我会挑典型的回。本文基于 deepseek-ai/deepseek-harness 官方仓库、官方docs/architecture.md、deepseek-ai/cordis及多位社区开发者laserlloyd、jb51、掘金/SSD Nodes 教程2026-08 的实测整理。dsh 处于开发者预览阶段命令与配置请以你安装版本的实际输出为准。