DeepSeek Harness 使用指南
从概念到实战的开源 Agent 运行时深度指南：私有化部署、插件生态、30+ 内置工具、20+ 模型接入与权限安全。
Agent Harness 完全指南：从概念到 DeepSeek Harness 实战
AIGC / Agent 领域开发者的概念科普 + 实战使用文档
整理日期：2026-08-14（54520520@qq.com，王博）
目录
- 应用方向与能力评估（开篇速览）
- 什么是 Harness
- 开源 Harness 生态
- DeepSeek Harness 实战
- 选型建议
- 常见问题 FAQ
- 附录：官方文档与参考资料
〇、应用方向与能力评估（开篇速览）
一句话定位：DeepSeek Harness 是「可私有化的通用 Agent 运行时」——它不是某个垂直应用，而是一台能装不同「马具」的机器。应用方向主要落在下面五个场景。
五大应用方向
| 方向 | 适合谁 | 一句话说明 |
|---|---|---|
| ① 私有化 Agent 平台（最主流） | 个人开发者 / 小团队 | 内网部署统一编码助手或业务 Agent 底座，数据不出内网、完全可控 |
| ② 插件化扩展生态（最具想象空间） | 有定制需求的开发者 | 改能力不用 fork 源码：接数据库、包内部 API、写校验规则、换 UI，全在配置层解决 |
| ③ Agent 调试与研究（差异化王牌） | AI 研究者 / 框架开发者 | 会话回放 + 分叉：失败任务精确重放、任意节点分叉对比，传统黑盒重跑做不到 |
| ④ 多模型统一网关 | 注重成本控制的团队 | 一个 UI 切 20+ 提供方：便宜模型跑机械任务、强模型跑关键任务、本地 Ollama 免费跑隐私数据 |
| ⑤ 教学与二次开发 | 想理解 Agent 原理的人 | MIT 协议 + 微内核架构，代码量可控、分层清晰，是学习现代 Agent 运行时的极佳标本 |
能力总评
架构思想是顶级的，成熟度是预览级的——这是理解它一切优劣的总钥匙。
核心优势（按含金量排序）
- 插件架构是真·可组合，不是宣传话术：Cordis 内核的时间/空间可组合性，模型、工具、循环、UI 全部可单独替换——升级 Harness 时自定义插件不用重写，这是 fork 改内核的 LangGraph 路线做不到的。
- 会话回放 / 分叉，调试体验断层领先：任务失败可精确重放执行轨迹、任意节点分叉出新路径对比结果。对研究性和高成本任务（一次长任务可能烧几十万 token）价值极高。
- 模型中立，成本可塑性极强：20+ 提供方 + 任意 OpenAI 兼容端点，配合 PTC 模式（TypeScript 编排工具调用、减少模型往返），同一套 Harness 可做到「贵模型想、便宜模型干」。官方 V4 系列 benchmark 就是自家 Harness 跑的。
- 开箱即用的安全底座：三档权限模式 + 按系统实现的沙箱（Linux Landlock / macOS Seatbelt / Windows ACL）+ ask/never 审批，把「模型乱执行」这个最大风险在架构层兜住。
主要劣势与风险
- 预览版的不确定性（最大风险）：v0.1-rc 阶段，接口、配置格式、插件 API 都可能破坏性变更。生产环境接入前必须锁定版本（本指南部署即固定 0.1.0-rc.6，不走最新）。
- 生态尚在萌芽：社区插件约 12 个（DeepBolt 目录收录），对比 Claude Code 生态差一到两个数量级。好消息是 3.7 万 Star 的增速意味着生态会快速填充，但短期内「想要的能力可能要自己写插件」。
- 企业级配套缺失：无 SSO、多租户、集中审计、灰度发布等企业标配——面向个人/小团队够用，做公司级平台要自己补一层；长任务稳定性（几十步以上）尚无大规模生产验证。
- 部署门槛实测偏高：Node 22.19+ 是硬门槛，Windows 下存在 pnpm 沙箱、npx 兼容、bat 编码等坑（本指南附录已给出规避方案），对非技术用户不友好。
一句话结论
- 适合：个人/小团队私有化部署、Agent 研究与调试、想深度定制 Agent 能力的开发者
- 暂不适合：需要 SLA 保障的大规模生产系统、需要企业管控能力的中大型组织、非技术用户（等生态成熟）
一、什么是 Harness
1.1 核心定义
读音：/ˈhɑːrnɪs/，原意：马具、缰绳
Agent = Model + Harness
- Model（大模型）：是马，负责思考、推理、生成内容，有原始智力，但容易幻觉、跑偏、长任务失控。
- Harness：就是马具 / 运行壳，是大模型之外的整套外围工程系统，不修改模型权重，用来约束、管控、引导、校验大模型，让它稳定、安全、按规则干活。
一句话：模型负责"会做"，Harness 负责"做对"。
1.2 Harness 里面包含什么（AIGC/Agent）
- 上下文 & 记忆管理：长任务状态维护、历史裁剪、长期记忆，防止 AI 干着活忘记前面目标
- 工具注册表：管理能调用的插件、函数、文件读写、联网能力，控制哪些工具可用
- 权限与安全层：哪些操作允许、哪些禁止，沙箱隔离，防止越权操作
- 任务循环 / 工作流：任务拆解、计划、执行、校验、失败重试、回滚逻辑
- 校验与反馈闭环：自动检查输出对错，发现幻觉自动修正，日志、可观测性监控
- 系统规则、约束协议：不只是简单 prompt，是一套强制执行的行为规范
⚠️ Harness ≠ LangChain/AutoGen 这类开发框架
框架是给开发者用的工具库；Harness 是给模型运行用的一整套运行环境，可以基于框架搭建，但不等于框架本身。
1.3 和 Prompt 工程的区别
| 对比项 | Prompt 工程 | Harness Engineering（驾驭工程） |
|---|---|---|
| 手段 | 靠写提示词，靠模型自己"听话" | 靠外部工程机制强制约束 |
| 本质 | 模型内部说服 | 模型外部管控 |
| 效果 | 复杂任务容易失效 | 就算模型"想犯错"，外部系统也会拦截、校验、回滚 |
| 定位 | 基础技巧 | 生产级 Agent 的核心方案 |
1.4 通俗比喻
大模型 = 很聪明但是不守规矩的实习生；
Prompt = 口头叮嘱；
Harness = 完整员工手册 + 检查清单 + 报警系统 + 权限管控 + 出错自动回滚机制。
1.5 AIGC 实际例子：AI 绘图 Agent
- Model：文生图大模型，负责画图。
-
Harness：
-
约束：禁止生成违规内容；
- 校验：检查提示词、图片结果；
- 任务流：多轮迭代、修改重绘；
- 记忆：记住用户前面的风格、尺寸要求；
- 权限：文件保存、输出格式管控。
没有 Harness，模型可能乱生成、忘记需求；加上 Harness，才能稳定交付业务可用结果。
补充：同一个大模型，仅仅更换 / 优化 Harness，任务成功率就可以大幅提升，不需要换更强模型——这也是 2026 年 AIGC/Agent 圈非常火的工程方向。
二、开源 Harness 生态
2.1 概念澄清
⚠️ Harness 是一类架构概念（驾驭层），不是某一个固定软件。
市面上有多个开源 Harness 实现；大厂闭源产品内部也有私有 Harness，不对外放出。
2.2 主流开源项目速览
① DeepSeek-Harness（2026-08-13 发布）
- 协议：MIT 开源，开发者预览版 v0.1
- 特点：一切皆插件，Agent 循环、模型适配器、工具注册表、沙箱、UI 全部是插件，不用 fork 修改内核，直接写插件扩展；可以切换任意 OpenAI 兼容模型，不限于 DeepSeek 模型。
- 可做：新增自定义工具、改写安全校验策略、替换 Agent 主循环、二次封装 WebUI。
- 注意：开源的是 Harness 运行壳，调用大模型仍需要 API Key 产生费用。
② OpenHarness（港大 HKUDS）
- 协议：MIT，Python 实现，代码量很小，轻量化 Harness 底座
- 特点：工具调用、记忆、权限沙箱、多子 Agent；兼容 Kimi、Ollama、DeepSeek 等几乎所有模型。
- 适合：深度二次改造、学术研究、本地 Agent 开发。
③ 其他社区开源 Harness
- agent-harness：Python 极简运行时，协议宽松，适合嵌入自有业务系统
- Go-Harness：Golang 版本，面向生产高并发场景
闭源阵营：Claude Code、OpenAI Agent SDK 内部、企业自研 Agent 系统——Harness 为闭源私有实现，拿不到源码，只能调用 API，不能二次开发。
2.3 主流实现对比表
关键区分：DeepSeek-Harness、OpenHarness = 完整现成 Harness 运行时（沙箱、记忆、Agent 循环、安全校验全部内置，开箱即用）；LangGraph = 图编排库（零件库）（只提供状态、循环、分支原语，Harness 整套能力需要自己开发实现）。
| 对比项 | DeepSeek-Harness (dsh) | OpenHarness (港大 HKUDS) | LangGraph |
|---|---|---|---|
| 本质定位 | 完整 Agent Harness 运行时，微内核 + 全插件架构，"一切皆插件" | 轻量化 Harness 完整运行时，复刻 Claude Code 核心逻辑 | 状态图编排开发库，不是现成 Harness，只提供基础骨架 |
| 开源协议 | MIT，可商用、私有化部署 | MIT，可商用、私有化部署 | MIT |
| 主要技术栈 | Node.js，Cordis 微内核插件系统 | Python，CLI 终端优先，轻量代码库 | Python / JS，基于 Pregel 图模型 |
| 内置 Harness 能力 | ✅ Agent 循环、沙箱、工具注册表、记忆、会话回放/分叉、日志审计、多运行模式，全部内置 | ✅ Agent 循环、沙箱权限管控、持久记忆 MEMORY.md、43+ 内置工具、会话断点恢复，开箱即用 | ❌ 没有内置沙箱、安全拦截、记忆管理、失败校验；需要开发者自己写代码实现整套 Harness 层 |
| 模型绑定 | 完全不绑定 DeepSeek，兼容 OpenAI 兼容接口：Kimi、Qwen、Ollama 全部支持 | 完全解耦模型，兼容绝大多数大模型 API / 本地 Ollama | 任意大模型都可接入 |
| 二次开发方式 | 优先写插件，不用修改内核源码；重度场景可 fork 改内核 | 代码量小，阅读修改成本低；可 fork 深度改写全部逻辑 | 基于 API 组装业务逻辑；全部约束、安全、记忆都需要手写 |
| UI 交互 | 自带 WebUI，也支持 CLI 模式 | 只有 CLI 终端界面，无 Web 图形界面 | 无自带 UI，需要自己开发前端 |
| 生态现状 | 2026-08 刚发布开发者预览版，接口会变动，不建议直接上生产，生态快速扩张 | 偏学术研究、原型验证；社区规模中等，生产需要补边缘场景处理 | 生态庞大，文档成熟，企业生产大量使用 |
| 优点 | 插件化极强，模块自由插拔；会话回放、分叉调试能力强；配置驱动，不用大量写代码 | 代码极少，逻辑清晰，适合学习 Harness 底层原理；资源消耗低，部署简单 | 灵活可控，分支、回滚、人工介入能力强；生态组件极多 |
| 缺点 | 预览版，版本迭代快，存在破坏性更新风险；刚出来，生产案例少 | 缺少 WebUI；部分边缘场景不完善；企业级配套少 | 上手门槛高；想要 Harness 完整能力，大量代码需要自己实现，容易写漏安全、校验逻辑 |
| 最适合场景 | ① 快速搭建完整 Agent 运行时 ② 插件化扩展 Agent 能力 ③ 做 Agent 调试回放实验 ④ 私有化部署完整 Agent 系统 | ① 学习研究 Harness 底层原理 ② Python 栈快速原型验证 ③ 本地 CLI Agent 工具开发 | ① 企业业务定制 Agent ② 复杂多分支、多人介入工作流 ③ 团队有充足开发人力，愿意自建 Harness 层 |
2.4 概念区分：Harness / Loop / Graph
- Harness：整套运行环境，沙箱、权限、记忆、工具管理，管环境。
- Loop：Agent 循环：调用模型 → 调用工具 → 校验结果，循环直到任务结束，管重复执行逻辑。
- Graph：状态图，定义分支、跳转、多子 Agent 调度，管流程走向。
DeepSeek-Harness、OpenHarness 内部已经包含 Loop 和 Graph；LangGraph 只提供 Graph，Loop、Harness 环境需要开发者自己实现。
三、DeepSeek Harness 实战
3.1 背景与定位
- 发布：2026-08-13 深夜发布 v0.1 开发者预览版，MIT 协议开源，GitHub 首日破 3.4 万 Star（现 3.7 万+）
- 伏笔：早在 7 月 31 日 V4 Flash 发布时，公开 Code Agent benchmark 的测试框架就是"即将发布"的 Harness 极简模式——DSH 正式公开前已参与自家模型的 Agent 能力评估
- 同日前置：8 月 13 日白天 V4 Pro 正式版上线 App/Web/API（模型号
DeepSeek-V4-Pro-0813），支持 1M Token 上下文、最高 384K Token 输出；晚上 Harness 开源，形成"模型 + 运行层"组合拳 - 定位：Agent 执行框架（Harness 系统 / 基建），不是模型，也不是普通编码工具。媒体评价："DeepSeek 终于有了自己的 Vibe Coding 入口"
- 团队：负责人崔添翼（90 后，6 枚 ACM 金牌，前 Jane Street 量化），2026 年 3 月加入 DeepSeek
关键链接
- 官网：https://www.deepseek.com/harness/
- GitHub：https://github.com/deepseek-ai/deepseek-harness
- API 开放平台：https://platform.deepseek.com/
3.2 核心架构："一切皆插件"
底层框架：Cordis
- 基于 Cordis 内核（核心作者已加入 DeepSeek，配套发布 88 页论文《A Programming Paradigm for Spatiotemporal Composability》）
- 内核只做一件事：插件的加载、卸载、依赖管理，不承载具体能力。运行中的
dsh就是一棵插件树 - 不存在需要打补丁的特权内核：扩展 dsh 的方式是把插件挂载到其他插件旁边，各项注册都是副作用，会在插件卸载时撤销
两大关键特性
- 时间可组合性（Temporal composability）：插件卸载后，它之前产生的副作用能完整撤销，不留孤儿状态
- 空间可组合性（Spatial composability）：插件依赖其他插件时，当其他插件出现/消失/改变，它能动态重新处理依赖
Profile 与组合包（bundle）
- Profile 是存放在 Harness home 中的具名组装：列出叠放的组合包、存放树外插件、保存用户自己的
cordis.patch.yml。web和headless是随发行版交付的两个模板 - 组合包是 Cordis 配置项 + 挂载代码的分发格式。每层可被上一层 patch：先按 profile 列出的顺序应用组合包 → profile 的
cordis.patch.yml→ home 级 → 任意--patchoverlay - 查看本机实际启动的配置树：
dsh --profile web --dump-config——打印出的任何条目都可以被自己的 patch 替换 - 三层组合：
dsh-base（模型、工具、持久化、沙箱、审批、设置、凭据、遥测）→dsh-web-app（浏览器应用）/dsh-headless（一次性运行器，无服务器）
能力 seam（接缝）
一个 seam = Service Definition（接口声明）+ Service Provider（实现）+ Consumer（消费方，通常是面向模型的工具）三位一体。替换一个提供方就能改变整个产品：比如把文件系统与进程提供方指向远程沙箱，Bash、PTY、LSP 会一并搬过去，无需提供方专用 fork。
事件即扩展点
- 会话事件：追加到日志的持久事实（
session/event），重新加载后仍存在 - Agent 事件（
agent/*）：携带活跃 Agent，观察/拦截进行中的工作 - 能力事件：无需导入循环即可向 seam 附加策略（
fs/*、tools/*、telemetry/*）
轮次流程（turn/step）
一个步骤 = 一次模型请求 + 它调用的工具；一个轮次包含零个或多个步骤。关键设计：模型可见即已记录——抵达模型请求的一切都必须能从会话日志重建，并由运行时不变量断言。这让轨迹回放、审计、调试成为可能。
3.3 四种运行模式
| 模式 | 能力 | 适用场景 |
|---|---|---|
| 标准模式 | 完整编码 Agent：文件编辑、Shell、文件/网页搜索、Skills、计划、目标、子 Agent、工作流 | 日常使用（首推） |
| PTC 模式 | 标准模式全部能力 + Code Mode SDK：模型写一段 TypeScript 程序，在一次 run_code 里组合多步工具操作 |
大量重复工具往返、结构化多步操作、省 Token |
| 极简模式 | 仅持久 Bash + str_replace_editor 两个工具，固定极简系统提示词 | 模型基准测试（不要日常用） |
| 创造模式 | 标准模式全部能力 + 运行时检查 + 内存中试验插件 + 创建新模式 | Agent 自进化、开发新插件 |
创造模式示例："帮我做一个只允许读代码、不允许改文件、专门负责安全审计的模式"——Agent 发现自己没有扳手，现场造了一把扳手，插到自己手上接着干活。
3.4 官方内置工具全景（30+ 工具）
dsh 以插件包形式内置了全部面向模型的能力（packages/*/tool-*），工具本身也是插件。按能力分 7 大类：
① 文件与代码
| 工具 | 作用 | 备注 |
|---|---|---|
read / write |
读写 UTF-8 文本文件 | 读带行号，写可整体替换 |
edit |
按字面量替换编辑文件 | 需精确匹配，默认必须唯一 |
read_image |
读取 PNG/JPEG/WebP/GIF 图片 | 要求当前模型支持图像输入 |
glob / grep |
文件名模式搜索 / ripgrep 内容搜索 | 内置 ripgrep 二进制，无需本机安装 |
str_replace_editor |
查看/创建/替换/插入编辑器 | 极简模式专用，状态跨调用保留 |
lsp |
语言服务器查询：goToDefinition、findReferences、goToImplementation、hover | 代码精确导航，需注册 LSP 提供方 |
② Shell 与终端
| 工具 | 作用 | 备注 |
|---|---|---|
bash |
执行 bash 命令（bash -c） | 每次调用新 shell，无状态保留 |
pwsh |
执行 PowerShell 命令 | Windows 原生支持，路径 C:\ 形式 |
bash（持久） |
持久 bash shell，状态跨调用保留 | 按 Agent 所有者隔离 |
terminal_open/list/read/send/close/signal |
6 个持久终端工具 | 需显式选择启用，支持 PTY 会话 |
③ 搜索与网页
| 工具 | 作用 | 备注 |
|---|---|---|
web_search |
网页搜索最新信息 | 返回摘要答案 + 源 URL 列表 |
web_fetch |
抓取指定 URL 并解码为文本 | 提供方可替换（seam） |
④ 任务与协作（多 Agent / 工作流）
| 工具 | 作用 | 备注 |
|---|---|---|
subagent / subagent_fork |
委派独立子 Agent 执行自包含任务 | 前台等待 / 后台返回 job id |
send_message / interrupt_agent / list_agents |
给后台子 Agent 发消息、打断、查看状态 | 全局命名工具 |
report |
子 Agent 向父 Agent 汇报结果 | 子级作用域内注册 |
workflow |
运行 JavaScript 工作流脚本批量编排子 Agent | 提供 agent() / pipeline() / parallel() / phase() 钩子 |
ralph |
每轮用全新 Agent 迭代的 Ralph 循环 | 共享工作区充当长期记忆 |
job_list / job_output / job_kill |
后台任务统一管理 | 与任务种类无关，bash/终端/subagent 通用 |
todo_write |
结构化任务清单 | UI 渲染为检查清单，每次全量替换 |
⑤ 规划与目标
| 工具 | 作用 | 备注 |
|---|---|---|
exit_plan_mode |
计划模式：提交完整 Markdown 计划供审阅 | 批准后退出计划模式执行 |
create_goal / get_goal / update_goal |
持久化同会话目标，自动延续多轮 | 长任务跨轮推进，edit/pause/resume/complete/blocked |
schedule_create / schedule_list / schedule_delete |
会话内定时提醒 | after_seconds / at / every_seconds 三种模式 |
ask_user_question |
暂停执行向用户提问 | 带稳定 id，答案原样返回 |
⑥ 会话与记忆
| 工具 | 作用 | 备注 |
|---|---|---|
session_search |
搜索工作区历史会话 | 跨会话全文本检索 |
session_trace |
读取会话谱系（祖先/后代） | 只读工具 |
session_event_read/search/trace |
读取/搜索单个会话事件流 | 审计与调试 |
skill |
加载可用技能的完整说明 | 执行点名技能前调用 |
⑦ 自进化（创造模式核心）
| 工具 | 作用 | 备注 |
|---|---|---|
cordis_define |
定义不可变 Cordis Package（新建/追加插件） | 只校验参数与语法 |
cordis_inspect_list/query/self |
查询运行时 Service/Event/Tool schema | 写插件前先侦察 |
cordis_run / cordis_stop / cordis_undefine |
激活动态插件 / 停止 / 永久移除 | 运行中热插拔，状态不崩 |
这 7 个
cordis_*工具就是"Agent 给自己写插件并装上"的底层实现——需要显式选择启用，不在默认组合中。
3.5 安装部署
前置条件：Node.js ^22.19.0 或 >=24.0.0（推荐 22 LTS）
方式 A：快速体验（推荐，一行命令）
npx @deepseek-ai/dsh web
启动后浏览器打开：http://127.0.0.1:3080
方式 B：全局安装（适合经常用）
npm install -g @deepseek-ai/dsh
dsh web
方式 C：源码安装（适合改插件/参与开发）
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
实用小技巧
- 换端口：
npx @deepseek-ai/dsh web --port 8080 - npm 下载慢换国内镜像：
npm config set registry https://registry.npmmirror.com - headless 模式（一句话跑任务，适合脚本/CI）：
export DEEPSEEK_API_KEY="你的密钥"
dsh --profile headless "总结当前目录下这个项目的结构"
Windows 实测踩坑记录
- pnpm 11.8.0 在受限环境下，内置
safe-delete（回收站清理）可能被系统拦截，导致所有 pnpm 命令失败（连pnpm config list都不行）→ 规避：改用 npm 安装发布包，或关闭沙箱后运行 - Windows 下
npx @deepseek-ai/dsh web若报'dsh' 不是内部或外部命令（bin 是 shell 脚本无法直接执行）→ 用 node 直接执行：
node node_modules/@deepseek-ai/dsh/lib/bin.js web
3.6 配置模型（20+ 提供方）
打开 设置 → 模型，有两条入口：
方式一：内置提供方列表（最省事）
内置支持 20+ 家：DeepSeek、OpenAI、OpenRouter、xAI、通义千问（qwen）、MiniMax、Moonshot（月之暗面）、Mistral、智谱（zai）、小米、NVIDIA、Together 等。选择后只需填 API 密钥，端点、协议、模型列表自动就位。
注意：Bedrock、Vertex、Azure、Codex 等需要各自原生认证（AWS 凭据、ADC 项目、
api-version、OAuth），只填 API Key 不够。
方式二：自定义提供方（适合本地模型/中转/内部网关）
| 字段 | 说明 | 示例 |
|---|---|---|
| Provider ID | 小写字母开头的唯一标识（永久，改名需重建） | my-gateway |
| 显示名称 | 界面显示名 | 我的网关 |
| API 地址 | 服务完整地址 | https://gateway.example/v1 |
| API 协议 | 三选一 | openai-completions |
| API 密钥 | 该服务密钥 | sk-... |
| 模型目录 | 自动获取（调 GET /models）或手动添加 |
qwen2.5-7b |
API 协议三选一：openai-completions（标准 OpenAI 对话补全，绝大多数服务，默认）、openai-responses（OpenAI 新版 Responses）、anthropic-messages（Anthropic/Claude 消息协议）。
实战示例：接入本地 Ollama
- 添加自定义提供方
- Provider ID：
ollama-local；显示名称：本地 Ollama - API 地址：
http://localhost:11434/v1；API 协议：openai-completions - API 密钥：随便填占位符
- 获取可用模型或手动添加（如
qwen2.5:7b）→ 保存
配置文件方式：批量管理多提供方（推荐进阶）
适合一次配置多个模型、写模板复用。配置分散在两个文件，各司其职：
| 文件 | 路径 | 职责 |
|---|---|---|
| 提供方定义 | $DSH_HOME/settings.yaml |
声明提供方（显示名、协议、地址、模型列表），密钥只写引用名，不写明文 |
| 密钥存储 | $DSH_HOME/.credentials.yaml |
只存放密钥明文（XXX_API_KEY: sk-...），权限收紧，不提交 git |
$DSH_HOME默认是~/.dsh（Windows 为C:\Users\<你>\.dsh）。配置修改即时生效，下一次请求即可用，无需重启服务。DeepSeek 是默认提供方，无需在此声明。
实测可用示例：接入本机 Ollama（无需任何云 Key）
Ollama 本地服务无鉴权，但协议强制要求密钥字段，填占位凭证即可：
# settings.yaml —— 提供方定义
llm-pi-ai:
providers:
ollama:
displayName: Ollama (Local)
api: openai-completions
baseURL: http://127.0.0.1:11434/v1
apiKeyEnv: OLLAMA_API_KEY # 占位凭证，实际写在下表
models:
- id: gemma4:12b
- id: qwen2.5:14b
- id: gemma3:12b-it-qat
# .credentials.yaml —— 密钥（占位即可）
OLLAMA_API_KEY: ollama
配置后，新会话的模型选择器里会出现 "Ollama (Local)" 及其模型，直接选用。此配置已在本机端到端验证通过（模型发现 + 真实推理正常）。
国内主流 API 模板（拿到 Key 取消注释即用）
llm-pi-ai:
providers:
# --- Kimi（月之暗面） ---
# moonshot:
# displayName: Kimi (Moonshot)
# api: openai-completions
# baseURL: https://api.moonshot.cn/v1
# apiKeyEnv: MOONSHOT_API_KEY
# models:
# - id: kimi-k2.5
# --- 通义千问（阿里云 DashScope） ---
# qwen:
# displayName: 通义千问
# api: openai-completions
# baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
# apiKeyEnv: DASHSCOPE_API_KEY
# models:
# - id: qwen-max
# - id: qwen-plus
# --- 智谱 GLM ---
# zhipu:
# displayName: 智谱 GLM
# api: openai-completions
# baseURL: https://open.bigmodel.cn/api/paas/v4
# apiKeyEnv: ZHIPU_API_KEY
# models:
# - id: glm-4.5
# - id: glm-4.5-air
# --- OpenRouter（聚合 300+ 模型） ---
# openrouter:
# displayName: OpenRouter
# api: openai-completions
# baseURL: https://openrouter.ai/api/v1
# apiKeyEnv: OPENROUTER_API_KEY
# models:
# - id: deepseek/deepseek-chat
# - id: anthropic/claude-sonnet-4
.credentials.yaml 里对应加一行（键名必须与 apiKeyEnv 完全一致）：
MOONSHOT_API_KEY: sk-xxx
DASHSCOPE_API_KEY: sk-xxx
ZHIPU_API_KEY: xxx
OPENROUTER_API_KEY: sk-or-xxx
模型 id 以各家最新列表为准；想用视觉模型，在对应模型条目下加
input: [text, image]。
多模型日常切换：新会话在模型选择器下拉切换即可；同会话内可用指令 /model 快速切换，无需重启。
视觉模型配置（进阶）
自定义提供方下，视觉模型需在 $DSH_HOME/settings.yaml 里声明模态（表单没有该字段）：
llm-pi-ai:
providers:
vision-gateway:
apiKeyEnv: GATEWAY_API_KEY
api: openai-completions
baseURL: https://vision.example/v1
defaultInput: [text, image] # 路由级回退，或逐模型 input
models:
- id: first-model
- id: vision-preview
input: [text, image]
排错速查
| 报错 | 原因 | 解决 |
|---|---|---|
MISSING_CREDENTIAL |
密钥未配置 | 模型页存密钥，或提供引用的环境变量 |
UNKNOWN_MODEL |
模型不在配置中 | 选择已配置模型，或向自定义提供方添加 |
| 获取可用模型 401 | 密钥错误 | 检查密钥；不提供 /models 端点的服务改手动输入 |
| 图片发送前被拒绝 | 模型未声明图片模态 | 自定义模型加 input: [text, image] |
安全提示：密钥保存在 $DSH_HOME/.credentials.yaml（只写），设置页只显示脱敏描述符。别截图发群、别提交 git，怀疑泄露立即在平台吊销重建。
3.7 权限与安全
权限模式三档（UI 可切）
| 模式 | 文件沙箱 | 审批策略 | 适用场景 |
|---|---|---|---|
| Read Only | read-only | ask | 只问问题、看代码、查资料 |
| Workspace Write | workspace-write | ask | 日常干活（推荐） |
| Full access | danger-full-access | never | 全局操作（慎用） |
沙箱只管文件读写（工作区 + 临时区可写 / 只读 / 无限制），网络访问与进程可见性不归沙箱管。
审批策略两档：ask（默认，每次超权限操作弹出审批卡片，允许只放行这一次）vs never（不问直接拒绝，适合无人值守/CI）。
沙箱在各系统的实现：Linux = bwrap 或 Landlock（仓库自带 landlock-run 原生包）；macOS = Seatbelt；Windows = ACL 受限令牌。
实践建议
- 日常用 Workspace Write；只查不改切 Read Only；Full access 临时用、用完切回
- 审批弹窗认真看再点——这是最后一道闸
- 运行不可信任务前主动配置权限策略，Web UI 会按策略请求批准
- 自动化场景才考虑
never审批
3.8 核心亮点：可观测的会话日志
- 会话设计为只追加（append-only）的事件日志：系统提示词、用户消息、推理内容、工具调用与结果、权限变化、上下文注入、压缩、子 Agent 调度，全部成为日志中的事件
- 下一轮模型看到的历史，从这份日志重新推导
- Trajectory 轨迹视图：可按来源查看每一次运行——可观测、可审计、可复现，非常适合调试与研究
- 恢复、分叉、检索、回放共享同一份事件流
3.9 插件生态（社区插件详解）
安装命令：设置 → 插件 tab 管理已装插件；CLI 下用 profile 命令安装：
dsh plugin --profile web add <目标>
# 目标可以是：npm 包名 / GitHub 仓库 / 本地路径 / link / checkout
每个 profile 有独立插件组合，互不干扰。打上 dsh-plugin 话题标签的 GitHub 仓库可被社区发现；官方也维护企微群与 Discord。
插件 vs 技能：技能是给 Agent 的"说明书"（会话中
/调用）；插件是能力的"零件"（工具、界面组件、服务都靠插件装配，设置里管理）。@可引用技能、子 Agent、工作区文件。
社区推荐插件（原 36氪/社区文章推荐 5 款）
| 插件 | 地址 | 用途 | 评价 |
|---|---|---|---|
| dsh-at-file | github.com/omdsh-dev/dsh-at-file | 输入框 @ 直接调用文件 |
便捷，社区装机量高 |
| dsh-genui | github.com/omdsh-dev/dsh-genui | 回复中渲染图表、表格、表单、Diff、Mermaid、交互面板 | 可视化输出利器 |
| dsh-automation | github.com/titanwings/dsh-automation | 补上自动化能力（定时/触发执行） | 刚需，交互稍粗糙 |
| DSH-better-sidebar | github.com/omdsh-dev/DSH-better-sidebar | VS Code 式工作台：文件管理、代码编辑、真实终端、Git、Diff、内嵌浏览器、后台任务与子 Agent 状态 | 体验升级最大的一款 |
| ModLens | github.com/liustack/modlens | 给纯文本 DeepSeek 模型补视觉能力，配置视觉通道后可直接粘贴图片读图 | 刚需 |
插件目录 DSH Plugins 收录的 12 款（dshplugins.com，2026-08 更新）
| 插件 | 类别 | 用途 |
|---|---|---|
| DSH Better Sidebar | UI | VS Code 式侧边栏工作台（同 omdsh 版） |
| DSH Vision Toolkit | 视觉 | 视觉能力工具集 |
| dsh-agent-teams | 多 Agent | 多 Agent 团队协作工作流 |
| dsh-at-file | 文件 | 输入框 @ 引用文件 |
| dsh-computer-use | 电脑控制 | Agent 控制电脑操作 |
| dsh-custom-tool | 自定义工具 | 免代码定义自定义工具 |
| dsh-message-edit | 消息 | 编辑已发送消息 |
| dsh-notification | 通知 | 任务完成通知推送 |
| dsh-open-in-vscode | 编辑器 | 在 VS Code 中打开文件 |
| dsh-share | 分享 | 会话/工作区分享 |
| dsh-turn-rewind | 会话控制 | 回退到指定轮次重来 |
| dsh-visualize | 可视化 | 数据可视化渲染 |
安装安全提醒：插件目录会人工审核（确认仓库公开活跃、阅读 README），但第三方代码可能变化——装前自己读源码、查权限与依赖、尽量锁定版本。源码才是最终权威。
官方能力包速查（packages/ 目录，均为可插拔模块）
core（内核/会话/提示词/工具流水线）、llm（模型适配）、sandbox（沙箱）、fs（文件系统）、shell（bash/pwsh）、terminal（持久终端）、web（网页搜索/抓取）、subagent（子 Agent）、workflow（工作流引擎）、plan（计划模式）、goal（目标）、schedule（调度）、jobs（后台任务）、todo（待办）、skill（技能）、session-query（会话检索）、lsp（语言服务器）、mcp（MCP 支持）、acp（Agent Client Protocol）、storage（存储）、compaction（上下文压缩）、hooks（钩子）、guard（守卫）、credentials（凭据）、settings（设置）、feedback（反馈）、e2b（云端沙箱）、python（Python SDK）……
想自己写插件？官方提供完整扩展手册（docs/cookbook）：添加工具、添加 LLM 适配器、添加 Chat 节点、添加 Package 各有分步指南；创造模式下可先在内存中试验插件再打包。
3.10 使用技巧
- 指令越具体越好：明确"做什么、范围在哪、产出什么格式"，含糊的指令必然得到含糊的结果
- 按任务切换模型：简单任务（查资料、整理）用轻量模型快又省；复杂任务（重构、架构）用强模型。会话中途也能换模型，下一条消息起生效。推理等级：High/Medium/Low
- 分叉是神器：从某节点复制出新会话（原会话保留），适合实验不同方案；不用的会话归档，保持侧边栏干净。分叉/归档/删除工作区均为非破坏性操作
- 目标写得越收敛越好："把 README 补全"优于"把项目完善一下"；Agent 每轮决策对照目标，跑偏就拉回。目标状态：进行中/暂停/受阻/已完成
- 计划模式适合大改动：输入
/plan进入（/plan off退出），也可/plan 帮我重构登录模块权限校验同时进入并提交任务。Agent 先只读研究 → 出计划 → 等你审阅 → 批准后执行。计划模式是"软约束"，不额外限制工具权限 - 子代理适合"拆得开、各干各"：多方向调研、前后端并行改；紧密耦合的任务不适合拆。可给子代理发消息、打断、查状态
- 长任务默认丢后台：
job_output读输出、job_kill停止；后台任务多了互相抢资源，没用的及时终止。任务完成 ≠ 结果正确，收到汇报后抽验 - 附件占用上下文 token：能靠工作区读的文件就别用附件传（图片、CSV、压缩包支持，但越大越贵）
- 轨迹视图是调试利器：对话视图看"人话版"，轨迹视图按轮次看完整原始记录（USER/CONTEXT/ASSISTANT/TOOL），排查"Agent 为什么这么干"时用
- 工作区选项目根目录，别选 C 盘、用户主目录等大而全的目录——范围太大查找慢、误操作风险高
3.11 注意事项
- 开发者预览版：版本迭代极快，官方明确警告会有破坏性更新，不建议直接上生产（README 用大写字母标注）
- 开源的是 Harness 运行壳，调用大模型仍需 API Key 按量付费；可接本地模型（Ollama 等）实现完全本地化
- 生态愿景：官方正在铺"自进化"大棋——从成百上千万 Agent 实例里筛选魔改得好的插件，融回主线，形成正循环。目前对普通用户帮助有限，是吃生态的功能，极客可以先去种树
- 对普通用户不算友好：开发者术语多、使用门槛高，需要一点耐心上手
四、选型建议
- 想直接拿到一套完整 Harness，不想从零写沙箱、记忆、循环：优先 DeepSeek-Harness（注意是预览版，生产谨慎）；Python 栈选 OpenHarness。
- 团队人力充足，业务逻辑高度定制，需要精细控制每一步流转：选 LangGraph，自己实现 Harness 层。
- 学习 Harness 原理：OpenHarness 代码量最小，最适合读源码理解 Harness 的工作机制。
五、常见问题 FAQ
Q1：Harness 开源吗？能二次开发吗？
A：能。DeepSeek-Harness（MIT）、OpenHarness（MIT）等均有成熟开源实现，可私有化部署、定制、二次开发，优先 MIT 协议。闭源阵营（Claude Code 等）拿不到源码，只能调用 API。
Q2：两种开发模式怎么选？
- 轻量：写插件，不碰内核源码（推荐，升级方便）
- 重度：Fork 仓库，直接修改内核源码深度改造
Q3：能换别的模型吗？
A：可以。内置 20+ 提供方（OpenAI、qwen、智谱、Moonshot、MiniMax 等），或自定义 OpenAI 兼容端点接任意模型（含本地 Ollama、vLLM、LM Studio、第三方中转、公司内部网关）。
Q4：本地部署要钱吗？
A：Harness 本身 MIT 免费；但调用大模型 API 按量付费。也可接本地模型（Ollama）实现完全本地化运行。
Q5：DeepSeek Harness 现在能替代 Claude Code 吗？
A：为时尚早。v0.1 是开发者预览版，定位是可自由改造的 Harness 基建，不是成熟的开箱即用产品。建议体验、研究、为插件生态贡献，生产环境等版本稳定。
Q6：插件装多了会互相冲突吗？
A：Cordis 的时间/空间可组合性保证插件卸载时副作用完整撤销，依赖变化时动态重排；但插件生态刚起步，建议装前看源码、锁定版本，别一次装太多。
Q7：极简模式有什么用？
A：官方用它做模型基准测试（V4 Flash 的 Code Agent benchmark 就是它）。它把变量压到最少——只有 bash + 文件编辑器，纯粹考验模型本身能力。
Q8：会话日志会不会很大、很占空间？
A：会话是 append-only 事件日志，但设计上配套了上下文压缩（compaction）机制；普通使用无需担心，工作区会持久化会话但可归档清理。
六、附录
官方文档索引（仓库 docs/ 目录）
- 架构总览：docs/architecture.md
- 用户指南：docs/user/guide/（Web UI、模型配置、Python SDK）
- 工具 Schema 目录：docs/tool-catalog.md（全部内置工具的 JSON Schema）
- 配置目录：docs/config-catalog.md（所有配置字段与默认值）
- 插件开发手册：docs/cookbook/extension-cookbook.md + adding-a-tool / adding-an-llm-adapter / adding-a-package
- 防御模式：docs/defensive-patterns.md；术语表：docs/glossary.md；Agent 生命周期：docs/agent-lifecycle.md
参考资料
- DeepSeek 官方发布页：https://www.deepseek.com/harness/
- GitHub 仓库：https://github.com/deepseek-ai/deepseek-harness
- Cordis 论文：《A Programming Paradigm for Spatiotemporal Composability》
- 插件目录：https://dshplugins.com/（DSH Plugins）
- 社区教程：掘金《DeepSeek 昨晚刚开源了 Harness：附万少的 2 万字保姆级教程》
本文档综合公开资料（36氪、DeepSeek 官方仓库文档、社区教程）与 DeepSeek Harness 实际部署体验整理，供学习交流。