[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-94760":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":36,"readmeContent":37,"aiSummary":38,"trendingCount":16,"starSnapshotCount":16,"syncStatus":39,"lastSyncTime":40,"discoverSource":41},94760,"dsh-handbook","Electricitysheep\u002Fdsh-handbook","Electricitysheep","DeepSeek Harness (dsh) 从 0 到 1 深度手册：安装\u002F插件开发\u002F性能调优\u002F实测案例\u002F同模型多 Agent 实测对比（中文 + 英文 PDF）","https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook",null,"Python",521,24,138,1,0,164,337,75.19,false,"main",true,[24,25,26,27,28,29,30,31,32,33,34,35],"agent","agent-framework","ai-agents","beginners","deepseek","deepseek-ai","dsh-plugin","getting-started","guide","harness","llm","tutorial","2026-08-24 04:01:22","# DeepSeek Harness 白皮书 · dsh-handbook\n\n> **DeepSeek Harness 中文手册 × 生态观察中心**——从 0 到 1 玩转 dsh，跟着 780 帖讨论区看懂生态 · 中文 · [English](.\u002FREADME.en.md)\n\n**📖 [在线阅读](https:\u002F\u002Felectricitysheep.github.io\u002Fdsh-handbook\u002F) · 📄 [下载 PDF](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Freleases) · ⭐ [点 Star 支持](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Fstargazers)**\n\n*· 15 章手册 · 195 帖社区响应 · 280+ Stars**\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fbanner.svg\" alt=\"dsh-handbook banner\" width=\"720\"\u002F>\n\u003C\u002Fp>\n\n\u003Cdiv align=\"center\">\n\n![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FElectricitysheep\u002Fdsh-handbook?style=flat&color=yellow)\n![GitHub release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Ftag\u002FElectricitysheep\u002Fdsh-handbook?label=release&color=success)\n![dsh-handbook](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdsh--handbook-白皮书-blue)\n![chapters](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F章节-15-green)\n![pdf](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPDF-5.5MB-orange)\n![license](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-CC--BY--NC--SA--4.0-lightgrey)\n![dsh](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdsh-0.1.0--rc.6-8A2BE2)\n\n\u003C\u002Fdiv>\n\n> [!WARNING]\n> dsh 当前为 `0.1.0-rc.6`（预发布阶段），生产环境请谨慎评估，详见 [ℹ️ 版本说明](#ℹ️-版本说明)。\n\n## 🚀 快速体验（30 秒）\n\n```bash\n# 1. 安装（需要 Node.js ≥ 22）\nnpx -y @deepseek-ai\u002Fdsh web\n\n# 2. 浏览器打开 http:\u002F\u002F127.0.0.1:3080，开始对话\n# 3. 或跑一次性任务（适合脚本\u002FCI）\ndsh --profile headless \"你好，请用一句话介绍自己\"\n```\n\n> 想系统学？看 [🗺 学习路径（3 天计划）](.\u002Fdocs\u002Froadmap.md)；想先跑？[第 2 章：五分钟快速上手](.\u002Fdocs\u002F02-quickstart.md)；想速查？[📇 一页速查卡](.\u002Fdocs\u002Fcheatsheet.md)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fdemo-webui.gif\" alt=\"dsh Web UI 实测演示\" width=\"720\"\u002F>\n  \u003Cbr\u002F>\n  \u003Csub>\u003Cb>30 秒看懂 dsh Web UI\u003C\u002Fb>：新建会话 → 输入任务 → 模型选择 → 发送 → AI 回复\u003C\u002Fsub>\n\u003C\u002Fp>\n\n## 🎯 这是什么\n\n**DeepSeek Harness（`dsh`）**是 DeepSeek 官方 2026-08-13 开源的 Agent 运行时——一个\"一切皆插件\"（everything is a plugin）的框架。\n\n\u003Cimg width=\"614\" height=\"230\" alt=\"image\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F19482c24-2208-468e-ad38-9096d9270f8d\" \u002F>\n\n但官方文档以架构说明为主，**缺少一条从零上手的路径**。\n\n**这本白皮书补上这条路**：从\"什么是 Agent 运行时\"讲起，到安装、使用、开发插件、性能调优——每一章都有可复制、可运行的命令，全部在本机实测验证。**目标是：任何一个开发者，跟着这本书都能从 0 到 1 用起来、写起来。**\n\n### 为什么值得读（而不是只看官方文档）\n\n| 官方文档 | 本白皮书|\n|---|---|\n| 架构视角（AGENTS.md \u002F architecture.md） | **新手视角**：一条从 0 到 1 的路径|\n| 零散示例 | **每章可运行**，命令全部实测|\n| 无中文教程 | **中文优先**，英文同步|\n| 无生态实操 | **真实插件\u002FPR 拆解**（含踩坑与安全约束）|\n\n## 🎁 这本能给你什么\n\n\n| 如果你是… | 你会得到 |\n|---|---|\n| 🆕 **第一次接触 dsh** | 3 天从 0 到 1 学习路径（每天有目标+验收） |\n| 🛠 **开发者** | 可克隆的插件模板 + 配置参考大全（照抄能跑） |\n| ⚖️ **正在选型** | 6 个主流 Agent 对比（表格+文字）+ 同模型实测 benchmark |\n| ⚡ **要调优** | 推理档位策略 + 缓存命中率专题（实测 97%） |\n| 📚 **要案例** | 5 个真实复杂案例（含耗时\u002F产物\u002F验证） |\n\n## 🌟 感谢与社区\n\n首先要感谢每一位 Star、回复和投稿——这本手册不是一个人的作品，是 dsh 社区一起\"长\"出来的。\n\n发布两天，很幸运得到了这些反馈：\n\n- ⭐ **280+ Stars**——对一份刚发布的教程来说远超预期，感谢大家认可\n- 💬 **官方库 195 帖回应**——我们持续在[讨论区](https:\u002F\u002Fgithub.com\u002Fdeepseek-ai\u002Fdeepseek-harness\u002Fdiscussions)和大家一起踩坑、排障、交流\n- 🧠 **FAQ 里的 39 条问题大多来自真实提问**——社区问什么，我们沉淀什么（#380\u002F#817\u002F#1052…）\n- 📦 已向 [awesome-dsh-plugin](https:\u002F\u002Fgithub.com\u002Fawesome-dsh-plugin\u002Fawesome-dsh-plugin) 提交收录 PR（[#33](https:\u002F\u002Fgithub.com\u002Fawesome-dsh-plugin\u002Fawesome-dsh-plugin\u002Fpull\u002F33)，待合并）；阮一峰周刊自荐已提交\n- 🤝 与 30+ 社区项目互链（dsh-usage \u002F dsh-sgme \u002F AgentSoul \u002F dsh-vault \u002F egress-guard \u002F agentmemory…）\n\n> 内容随讨论区持续更新（[沉淀流水线](.\u002Fdocs\u002Fresearch\u002Ffeedback-pipeline.md)，19 项可追踪）。如果你觉得有用，Star 是对我们最大的支持。\n\n## 🔭 生态观察（第 15 章·全景报告）\n\n> 把 **1804 个插件仓库**的数据盘点 × **780 帖讨论区**定性观察交叉验证，5 个关键结论：\n\n| 结论 | 一句话 |\n|---|---|\n| 🪟 **Windows 是第一痛点** | 中文路径（15+ 帖同根因）\u002F koffi \u002F 端口 \u002F 子进程——数据讨论双证实 |\n| 🧩 **\"官方没做，社区全做\"** | 桌面壳 140+ \u002F TUI \u002F 记忆 77 \u002F 视觉 132——健康互补 |\n| 🛡️ **安全审计活跃，工具稀缺** | sandbox 分类仅 9 个插件——**供给缺口** |\n| 🐛 **序列化 bug 家族** | unknown tool \u002F reasoning 省略 \u002F run_code 丢弃——rc 期主战场 |\n| 💰 **成本透明化是刚需** | 缓存命中 97% 实测 + 成本工具雨后春笋 |\n\n**6 个能力缝**（官方可优先建）：视觉通道 · 记忆 seam · 桌面 TUI 协议 · 评测闭环 · Windows 一等支持 · 插件 registry\n> 完整报告（含对开发者\u002F选型者\u002F观望者的建议）：[第 15 章](.\u002Fdocs\u002F15-ecosystem-report.md)\n\n## 📚 目录（从 0 到 1）\n\n\u003Cdiv align=\"center\">\n\n| 🗺️ **[学习路径（3 天计划）](.\u002Fdocs\u002Froadmap.md)** | 从 0 到 1：每天目标 + 验收标准 + 学习原则 |\n|---|---|\n\n\u003C\u002Fdiv>\n\n### 🟢 阶段 1 · 入门：认知与上手\n\n\u003Cdiv align=\"center\">\n\n| 📖 **[第 1 章 · 认识 Harness](.\u002Fdocs\u002F01-intro.md)** | ⚡ **[第 2 章 · 五分钟上手](.\u002Fdocs\u002F02-quickstart.md)** |\n|---|---|\n| 与主流 Agent 全面对比 · FAQ · [EN](.\u002Fdocs\u002F01-intro.en.md) | 安装 · web\u002Fheadless 双模式 · 推理档位 · [EN](.\u002Fdocs\u002F02-quickstart.en.md) |\n\n\u003C\u002Fdiv>\n\n### 🔵 阶段 2 · 开发：骨架与插件\n\n\u003Cdiv align=\"center\">\n\n| 🧩 **[第 3 章 · profile 与插件系统](.\u002Fdocs\u002F03-profiles.md)** | 🛠️ **[第 4 章 · 插件开发实战](.\u002Fdocs\u002F04-plugin-dev.md)** |\n|---|---|\n| 可定制骨架 · 插件挂载 · 扩展点 · 真实坑 | 从零写第一个插件（完整代码 + 测试 + 实机验证） |\n\n\u003C\u002Fdiv>\n\n### 🟠 阶段 3 · 实战：场景与调优\n\n\u003Cdiv align=\"center\">\n\n| 📦 **[第 5 章 · dsh 应用场景](.\u002Fdocs\u002F05-cases.md)** | 🚀 **[第 6 章 · 进阶与性能调优](.\u002Fdocs\u002F06-advanced.md)** |\n|---|---|\n| 5 大场景 · 高缓存命中率专题 · 5 行业视角 | 推理档位策略 · 耗时分析 · 踩坑清单 |\n\n\u003C\u002Fdiv>\n\n### 🟣 阶段 4 · 生态：能力与编排\n\n\u003Cdiv align=\"center\">\n\n| 🌐 **[第 7 章 · 生态与资源](.\u002Fdocs\u002F07-ecosystem.md)** | 🧰 **[第 8 章 · 工具与上下文系统](.\u002Fdocs\u002F08-tools-context.md)** | 🔗 **[第 9 章 · MCP 子代理与工作流](.\u002Fdocs\u002F09-mcp-subagent-workflow.md)** |\n|---|---|---|\n| 官方入口 · 参与路径 · 阅读建议 | 60+ 能力包地图 · 内置工具 · compaction | 外部工具接入 · 并行子代理 · 多步编排 |\n\n\u003C\u002Fdiv>\n\n### 🔴 阶段 5 · 进阶：复杂案例与展望\n\n\u003Cdiv align=\"center\">\n\n| 🧪 **[第 10 章 · 复杂实战案例](.\u002Fdocs\u002F10-complex-cases.md)** | 🔮 **[第 11 章 · 未来展望](.\u002Fdocs\u002F11-future.md)** | ⚠️ **[第 12 章 · 已知不足与边界](.\u002Fdocs\u002F12-limitations.md)** |\n|---|---|---|\n| dsh 真实跑出：数据清洗管线 186s · 5-bug 修复 94s | 技术\u002F生态\u002F竞争\u002F机会\u002F风险 预测 + 时间线 | rc 版诚实版：不稳定性 · 生态早期 · 跨平台短板 |\n\n\u003C\u002Fdiv>\n\n\u003Cdiv align=\"center\">\n\n| 🛡️ **[第 13 章 · 安全与沙箱](.\u002Fdocs\u002F13-security.md)** | 💰 **[第 14 章 · 缓存与成本](.\u002Fdocs\u002F14-cost.md)** |\n|---|---|\n| 沙箱机制 · 权限模型 · 审批流 · 插件安全审计清单 | 缓存命中率实测 97% · 成本模型 · 推理档位联动 · 预算实战 |\n\n\u003C\u002Fdiv>\n\n| 📊 **[第 15 章 · 生态全景报告](.\u002Fdocs\u002F15-ecosystem-report.md)** | |\n|---|---|\n| 1804 插件 × 780 帖交叉验证：5 大洞察 + 6 个能力缝 + 生态参与者建议 |\n\n### 📎 附录\n\n\u003Cdiv align=\"center\">\n\n| 📚 **[附录 A·术语表](.\u002Fdocs\u002Fappendix-glossary.md)** · 📦 **[附录 B·官方包速查](.\u002Fdocs\u002Fappendix-packages.md)** · 📊 **[附录 C·Benchmark](.\u002Fdocs\u002Fbenchmark.md)** |\n|---|\n| 30+ 术语 · 命令速查 · 官方 @deepseek-ai\u002F* 包清单 · 同模型 3 Agent 实测 |\n\n\u003C\u002Fdiv>\n\n## 💎 内容精华速览（点开即看，不止链接）\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📖 第 1 章：认识 DeepSeek Harness —— 三个直觉 + 能力矩阵\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **三个直觉**：dsh = Agent 的乐高底座；harness = 套在模型外的工程层；2026 = Agent 可编程时代\n- **核心事实**：MIT 开源 · TypeScript · \"一切皆插件\" · 2026-08-13 发布\n- **dsh vs 5 个主流 Agent 能力矩阵**（Claude Code \u002F Codex \u002F OpenCode \u002F Gemini \u002F Kimi）：开源✅、模型无关✅、**官方级插件体系**（独有）、自定义界面✅、headless CI✅\n- **选型决策**：深度定制+生态 → dsh；开箱即用 → Claude Code\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>⚡ 第 2 章：五分钟快速上手 —— 30 秒跑起来\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **一条命令启动**：`npx -y @deepseek-ai\u002Fdsh web` → http:\u002F\u002F127.0.0.1:3080\n- **双模式**：web（对话 UI）\u002F headless（`dsh --profile headless \"任务\"`，CI 友好）\n\n- **推理档位三档**：`low`（最快\u002F简单任务）· `high`（默认）· `max`（最强\u002F复杂推理）——**性能关键：思考占工具链 90% 时间**。>注：`low` 为本白皮书实测网关（pi-ai\u002Fopencode-go）档位；**DeepSeek 官方适配器为 `off`（关闭思考\u002F最快）\u002F `high` \u002F `max`**（见 02-quickstart 2.3 注）\n- **第一个插件**：Git 面板 4 步挂载\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧩 第 3 章：profile 与插件系统 —— 可定制骨架\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **profile** = bundle 栈 + 你的 patch 层（`package.json` + `cordis.patch.yml`）\n- **挂载插件只需 2 处改动**（加依赖 + 加 insert 行）\n- **host\u002Fclient 双半**：一个 npm 包 = Node 侧工具\u002F服务 + 浏览器侧 UI\n- **5 大扩展点**：`agent\u002Frequest` waterfall、`conversationEvents`、`ctx.slots`、`settings`、`ctx.provide`\n- **6 个真实踩坑**：rc.1 依赖断裂、插件缺 main、`next()` 忘 await、类型不识别、ModuleLoader、端口占用\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛠 第 4 章：插件开发实战 —— 完整可运行代码\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **从零写提速插件**（完整拆解）：纯函数决策 + `agent\u002Frequest` waterfall 注入\n- **核心技巧**：决策逻辑抽纯函数（单测毫秒级）→ 实机只验证\"注入是否发生\"\n- **3 条开发纪律**：先找扩展点 \u002F 逻辑抽纯函数 \u002F 实机验证不能省\n- **实机日志证据**：`calls=[{name:\"write\"}] => reasoningEffort=low`\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📦 第 5 章：实战案例 —— 三个真实开源 PR 的完整闭环\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **Git 面板 push\u002Fpull\u002Ffetch**（PR #10）：`--force-with-lease` 安全红线 + 本地 bare-repo 集成测试 + Playwright 实机验证\n- **HTML 草稿预览**（PR #11）：沙箱安全约束下的 srcdoc 决策纯函数\n- **提速插件示例**：长工具链每步思考降档\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🚀 第 6 章：进阶与性能调优 —— 时间花在哪\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **性能模型**：工具链任务 90% 时间在模型思考（每次工具调用前）\n- **档位策略**：简单轮次 low \u002F 日常 high \u002F 复杂 max——降档是最高杠杆提速\n- **7 个真实坑**：含\"简单任务突然变快 = 缓存命中\"的评测陷阱\n- **看成绩单三问**：谁测的 \u002F 什么 harness \u002F 验证器多严\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🌐 第 7 章：生态与资源 —— 加入 dsh 生态的地图\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **官方入口**：仓库 \u002F API 文档 \u002F Discord \u002F Discussions\n- **当前状态**：官方暂不收外部 PR → **做 dsh-plugin 生态项目是官方点名的贡献方式**\n- **新手路径**：用起来 → 小 PR → 发插件 → 写内容\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧰 第 8 章：工具与上下文系统 —— 能力引擎\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **60+ 官方能力包地图**：工具\u002F上下文\u002F会话\u002F子代理\u002FMCP\u002F工作流\u002F安全\n- **内置工具（实测）**：read\u002Fwrite\u002Fgrep\u002Fglob\u002Fedit\u002Fbash\u002Ftodo\u002Fskill\n- **产物追踪**：工具返回 locations → 对话末尾可打开产物\n- **上下文注入**：系统提示分层 + 技能目录\n- **长对话自动压缩**（compaction）+ 沙箱\u002F权限\u002F审批安全层\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔗 第 9 章：MCP、子代理与工作流 —— Agent 系统化\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **MCP**：接入外部工具服务器（社区已有 token 追踪插件）\n- **子代理**：并行委派任务（大仓库调研\u002F长任务分解）\n- **工作流**：确定性多步编排（拉取→清洗→报表→校验）\n- **四阶段新手路径**：单 Agent → +MCP → +子代理 → +工作流\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🧪 第 10 章：复杂实战案例 —— dsh 真实跑出来的\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **案例 A**：数据质量分析→清洗→可视化（186s，52→35 行归零，chart.png，含权衡说明）\n- **案例 B**：5-bug 修复 + 49 测试（94s，pytest 49 passed，覆盖除零\u002F负数\u002F精度边界）\n- **画像**：多步工具链自动编排 + 有判断力 + 产物可追踪\n- 隐私声明：全部合成数据\u002F自造代码\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📚 附录：术语表 + 命令速查\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **30+ 术语**：harness\u002Fprofile\u002Fbundle\u002Fcordis\u002F扩展点\u002Fwaterfall\u002Fcompaction…\n- **命令速查**：dsh 核心 \u002F 环境 \u002F 排障 \u002F 插件开发\n- **Benchmark**：同模型 3 Agent 实测（3 轮中位数）\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔮 第 11 章：未来展望 —— 五个维度的预测\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **技术\u002F生态\u002F竞争\u002F机会\u002F风险** 五维度预测 + 时间线\n- **机会点**：官方生态早期，做 dsh-plugin 项目是入场红利\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>⚠️ 第 12 章：已知不足与边界 —— rc 版诚实说\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **不稳定性**：rc 迭代快、破坏性变更频繁\n- **生态早期**：官方包 60+ 但插件生态刚起步\n- **跨平台短板**：Windows 家族踩坑记录（含 Node 版本红线）\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🛡️ 第 13 章：安全与沙箱模型 —— 敢上生产的关键\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **沙箱机制**：进程隔离（bwrap\u002FLandlock\u002FSeatbelt）+ 权限分级 + 审批流\n- **社区审计边界**：node:vm 非安全边界、approval 回环、workspace-write 递归删除等真实逃逸面\n- **插件安全审计清单**：第三方审计方法论（[#454](https:\u002F\u002Fgithub.com\u002Fdeepseek-ai\u002Fdeepseek-harness\u002Fdiscussions\u002F454)）\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>💰 第 14 章：缓存与成本工程 —— 把\"便宜\"变工程\u003C\u002Fb>\u003C\u002Fsummary>\n\n- **缓存机制**：上下文缓存 + 命中率实测 97%（Flash 折扣 98% \u002F Pro 99%+）\n- **成本模型**：token 花在哪 + 推理档位联动 + 真实任务预算\n- **可视化**：session log \u002F 余额插件看每笔成本\n\u003C\u002Fdetails>\n\n## 🖥 演示（Demo）—— 直接看效果\n\n### ① Web UI 对话（`dsh web`）\n\n```bash\ndsh web    # → http:\u002F\u002F127.0.0.1:3080\n```\n\n![dsh Web UI 对话](.\u002Fdocs\u002Fassets\u002Fdemo-web-chat.png)\n\n### ② Headless CLI（一次性任务，适合脚本\u002FCI）\n\n运行 `dsh --profile headless \"你好，请用一句话介绍你自己\"`（命令见 [🚀 快速体验](#-快速体验30-秒)）：\n\n```bash\n# → 你好！我是 DeepSeek 驱动的 AI 编程助手，可以帮你写代码、调试问题、\n#    处理文件、搜索资料，以及完成各种开发和办公任务。\n```\n\n### ③ 插件生态（Git 面板，`dsh-better-sidebar`）\n\n![dsh Git 面板（better-sidebar 插件）](.\u002Fdocs\u002Fassets\u002Fdemo-git-panel.png)\n\n> 完整图文演示见 [📺 30 秒看懂 dsh](.\u002Fdocs\u002Fdemo.md)。\n\n## 🧰 快速上手资产（精华直接看）\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>📇 一页速查卡\u003C\u002Fb> —— 安装 · 命令 · 推理档位 · 排障\u003C\u002Fsummary>\n\n```bash\nnpx -y @deepseek-ai\u002Fdsh web          # 安装即启动 Web UI\ndsh --profile headless \"任务\"        # 一次性任务（脚本\u002FCI）\n```\n\n推理档位：`low`（最快\u002F简单轮次）· `high`（默认）· `max`（最强\u002F复杂推理）——`low` 为实测网关（pi-ai）档位，**官方适配器用 `off`\u002F`high`\u002F`max`**\n> 工具链任务 90% 时间在思考——降档是最高杠杆提速\n> 完整卡：[docs\u002Fcheatsheet.md](.\u002Fdocs\u002Fcheatsheet.md)\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>🔧 插件模板\u003C\u002Fb> —— 挂载只需 2 步\u003C\u002Fsummary>\n\n```yaml\n# ① package.json 加依赖\n\"my-plugin\": \"link:C:\\\\path\\\\to\\\\my-plugin\"\n# ② cordis.patch.yml 加挂载\n- insert:\n    - id: my-plugin\n      name: my-plugin\n```\n```bash\ncd ~\u002F.dsh\u002Fprofiles\u002Fweb && pnpm install && dsh web\n```\n> 可克隆模板（含纯函数+waterfall+测试）：[examples\u002Fplugin-template\u002F](.\u002Fexamples\u002Fplugin-template\u002FREADME.md)\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>⚙️ 配置参考\u003C\u002Fb> —— settings.yaml 核心\u003C\u002Fsummary>\n\n```yaml\nagent-default-model:\n  model: deepseek-v4-flash    # 或 deepseek-v4-pro\n  reasoningEffort: high       # off（关闭思考\u002F最快）\u002F high（默认）\u002F max（最强）\n```\n> 全字段（profile\u002Fcordis.patch.yml\u002F常用场景）：[docs\u002Fconfig-reference.md](.\u002Fdocs\u002Fconfig-reference.md)\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>❓ FAQ Top 5\u003C\u002Fb>\u003C\u002Fsummary>\n\n1. **dsh 是模型吗？** 不是——是运行时，模型通过 llm 插件接入\n2. **和 Claude Code 区别？** Claude Code 是\"整车\"，dsh 是\"乐高底座\"（开源可定制）\n3. **要花钱吗？** dsh 免费开源；对话按量付费（缓存折扣：Flash 档 98% \u002F Pro 档 99%+，实测会话缓存命中率 97%）\n4. **插件装不上 404？** rc.1 依赖断裂——用 `^0.1.0-rc.6` 线\n5. **能进生产吗？** rc 阶段有破坏性变更；生态玩法现在可入\n> 完整 FAQ（六类）：[docs\u002Ffaq.md](.\u002Fdocs\u002Ffaq.md)\n\u003C\u002Fdetails>\n\n## ⚖️ DSH vs 主流 Agent（能力矩阵）\n\n| 维度 | **dsh** | Claude Code | OpenAI Codex | OpenCode | Gemini CLI | Kimi CLI |\n|---|---|---|---|---|---|---|\n| 开源 | ✅ MIT | ❌ | ❌ | ✅ MIT | ❌ | ❌ |\n| 模型绑定 | 模型无关 | Claude 系 | GPT 系 | 任意 | Gemini 系 | Kimi 系 |\n| **插件体系** | **官方级：一切皆插件，60+ 官方包** | 配置\u002F钩子 | 配置 | 配置 | 无 | 无 |\n| 自定义界面 | ✅（client 半） | ❌ | ❌ | 部分 | ❌ | ❌ |\n| 自动化\u002FCI | ✅ headless | ✅ | ✅ | ✅ | ✅ | ✅ |\n| TUI | 插件可做 | ✅ 内置 | ✅ 内置 | ✅ 内置 | ✅ | ✅ |\n| 生态阶段 | 零日（2026-08-13） | 成熟 | 成熟 | 成熟 | 成熟 | 早期 |\n| 适合谁 | 深度定制+生态 | 开箱即用 | 开箱即用 | OpenCode 用户 | Google | Kimi |\n\n> 实测案例、同模型多 Agent 对比数据见 [第 1 章](.\u002Fdocs\u002F01-intro.md) 与 benchmark 章节。\n\n## 📊 同模型 × 不同 Agent 实测（2026-08-13）\n\n> 模型统一 `deepseek-v4-flash`（同一网关、同一 key），只对比 Agent 工程层。5 任务全部正确完成，差异在效率：\n\n| Agent | 总耗时 | 正确率|\n|---|---|---|\n| **omp** | **70s** | 45\u002F45 ✅|\n| **dsh** | **130s** | 45\u002F45 ✅|\n| **opencode** | 172s | 45\u002F45 ✅|\n\n> 5 任务 × 3 轮采样中位数（T1 创建文件 → T5 多文件重构），45\u002F45 全对。完整方法\u002F解读见 [📊 Benchmark 附录](.\u002Fdocs\u002Fbenchmark.md)。\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fdocs\u002Fassets\u002Fbenchmark-bar.svg\" alt=\"benchmark 柱状图：omp 70s \u002F dsh 130s \u002F opencode 172s\" width=\"720\"\u002F>\n\u003C\u002Fp>\n\n\n## 📄 白皮书 PDF\n\n- **中文完整版**：[DeepSeek-Harness-白皮书.pdf](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Freleases\u002Fdownload\u002Fv1.8.0\u002FDeepSeek-Harness-.pdf)（15 章 + 附录 ABC，~130k+ 字符，5.5MB）\n- **英文完整版**：[DeepSeek-Harness-Handbook.pdf](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Freleases\u002Fdownload\u002Fv1.8.0\u002FDeepSeek-Harness-Handbook.pdf)（15 章 + 附录，83 页，约 160k 字符，1.7MB）\n\n## 🌐 与生态联动\n\n本白皮书的方法论来自真实开源实践：\n- [DSH-better-sidebar](https:\u002F\u002Fgithub.com\u002Fomdsh-dev\u002FDSH-better-sidebar) —— 社区侧边栏插件（第 5 章案例）\n\n### 🧩 社区插件推荐（来自官方讨论区 \u002F [awesome-dsh-plugin](https:\u002F\u002Fgithub.com\u002Fawesome-dsh-plugin\u002Fawesome-dsh-plugin) 精选）\n\n| 插件 | 用途 |\n|---|---|\n| [dsh-specflow](https:\u002F\u002Fgithub.com\u002Flonelymoon87\u002Fdsh-specflow) | 规格驱动开发：技能+命令+目标实现+进度上下文 |\n| [dsh-gitflow](https:\u002F\u002Fgithub.com\u002Flonelymoon87\u002Fdsh-gitflow) | 审批门控的 Git 工作流（status\u002Fdiff\u002Fcommit\u002Fbranch） |\n| [dsh-guardian](https:\u002F\u002Fgithub.com\u002Flonelymoon87\u002Fdsh-guardian) | 危险操作策略检查 + 输出脱敏 + 安全审查 |\n| [dsh-code-intel](https:\u002F\u002Fgithub.com\u002Flonelymoon87\u002Fdsh-code-intel) | Tree-sitter 符号索引 + 混合搜索 |\n| [dsh-tianshu-tui](https:\u002F\u002Fgithub.com\u002Fhuiliyi37\u002Fdsh-tianshu-tui) | 终端 UI（TUI） |\n| [dsh-computer-use](https:\u002F\u002Fgithub.com\u002FAnionex\u002Fdsh-computer-use) | 无障碍优先的 macOS 电脑控制 |\n| [dsh-data-agent](https:\u002F\u002Fgithub.com\u002Fomdsh-dev\u002Fdsh-data-agent) | 连数据库写 SQL 的数据 Agent |\n| [dsh-balance-meter](https:\u002F\u002Fgithub.com\u002FGhost011118\u002Fdsh-balance-meter) | 余额 + 会话成本实时显示 |\n| [dsh-usage](https:\u002F\u002Fgithub.com\u002Fkestiany\u002Fdsh-usage) | Token 用量 + 费用估算 + 52 周热力图（#1169） |\n| [dsh-sgme](https:\u002F\u002Fgithub.com\u002Ffreehul\u002Fsgme) | 记忆引擎：按场景注入 + 自动剪枝（省 65-96% 会话，#1052） |\n| [AgentSoul](https:\u002F\u002Fgithub.com\u002Fyuhui-sama\u002Fdsh-agentsoul) | 本地人格 + 长期记忆 + 记忆蒸馏（#1478） |\n| [dsh-vault](https:\u002F\u002Fgithub.com\u002Fakslcw\u002Fdsh-vault) | 加密凭据保险库：TOTP\u002FAPI Key\u002FSSH 加密存储（#1457） |\n\n> 完整列表见 [awesome-dsh-plugin](https:\u002F\u002Fgithub.com\u002Fawesome-dsh-plugin\u002Fawesome-dsh-plugin)（122+ 插件）。想被收录？[社区案例征集](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Fdiscussions\u002F12)\n\n### 📣 官方讨论区活跃响应\n\n已在 [deepseek-ai\u002Fdeepseek-harness](https:\u002F\u002Fgithub.com\u002Fdeepseek-ai\u002Fdeepseek-harness) Discussions 持续活跃响应（100+ 帖）：插件踩坑 #380 \u002F 安全审计 #817 \u002F 缓存成本 #1052\u002F#1234 \u002F 生态洞察帖 #839 等（[沉淀流水线](.\u002Fdocs\u002Fresearch\u002Ffeedback-pipeline.md) 持续收录反馈）\n\n## 🙏 贡献与反馈\n\n- ⭐ 觉得有帮助？点个 Star 支持持续更新\n- 📝 **跑过真实案例？** 投稿收录进白皮书（署名 + 季度精选 PDF）：[社区案例征集](https:\u002F\u002Fgithub.com\u002FElectricitysheep\u002Fdsh-handbook\u002Fdiscussions\u002F12) ← 直接回帖，模板已备好\n- 章节\u002F命令失效？rc 版本迭代所致，欢迎 issue 指正\n- 想参与？见 [🤝 贡献指南（CONTRIBUTING）](.\u002FCONTRIBUTING.md) · 想看计划？[🗺️ 路线图（ROADMAP）](.\u002FROADMAP.md) · 生态参与见 [第 7 章](.\u002Fdocs\u002F07-ecosystem.md)\n\n## ℹ️ 版本说明\n\n- 基于 dsh `0.1.0-rc.6` \u002F DeepSeek-V4-Flash-0731（2026-08-13 开源）\n- 示例环境：Windows 11 + Node 24\n\n### 🔄 最近更新\n\n- **15 章完整版**（第 13 安全沙箱 \u002F 第 14 缓存成本 \u002F 第 15 生态全景报告）+ 附录 A\u002FB\u002FC\n- 讨论区反馈持续沉淀：FAQ 39 条 \u002F KVCache 规则 \u002F 内置 Agent 预设 \u002F run_code 异步坑（[沉淀流水线](.\u002Fdocs\u002Fresearch\u002Ffeedback-pipeline.md)）\n\n## 📜 许可\n\n内容 [CC BY-NC-SA 4.0](https:\u002F\u002Fcreativecommons.org\u002Flicenses\u002Fby-nc-sa\u002F4.0\u002F) · 示例代码 MIT\n","这是一个面向 DeepSeek Harness（dsh）框架的中文深度实践手册，系统覆盖从环境安装、Web\u002FCLI 快速上手、插件开发、性能调优到多 Agent 实测对比的全流程。手册基于 dsh 0.1.0-rc.6 预发布版本，所有命令均经本地实测验证，配套中英文 PDF 与在线文档，并整合社区真实问题与插件案例。内容以开发者视角组织，强调可复现性与工程落地性，适用于 AI Agent 初学者快速入门、框架选型评估者横向对比、以及需定制插件或优化推理效率的 LLM 应用开发者。",2,"2026-08-15 02:30:10","CREATED_QUERY"]