DeepSeek Harness：从安装配置到真实代码任务

把一个 bug 描述交给大模型，得到一段看起来正确的代码，并不难。难的是让它找到真正的调用链、改对文件、跑通测试，并把失败反馈带进下一轮。上一篇Harness 工程讲的是模型周围需要哪些工程；这篇把镜头拉近到一个具体实现：DeepSeek Harness，命令名 dsh。重点不是“又一个聊天界面”，而是怎样把它接到你的仓库，配置成一个可以检查、约束和迭代的编码工作流。

DeepSeek Harness 到底是什么？

它是 DeepSeek 开源、采用 MIT 许可的 Agent Harness，底层使用 Cordis 插件系统。可以把它理解为一个可组装的运行环境：模型接入、工具、会话、存储、调度与界面都围绕插件组织。需要替换其中一块时，不必先把整个 Agent 应用重写。官方介绍 →

这与直接调用一次聊天 API 的区别，在于谁持有状态、谁执行动作、谁把执行结果送回模型。模型提出“读这个文件”或“执行测试”；Harness 负责执行，并把结果带回下一轮。你配置的不是一个更会写代码的提示词，而是模型工作的环境。

也要区分 agent harness 和 evaluation harness：前者运行 Agent，后者运行测试集、打分和比较结果。DeepSeek Harness 可以成为评测的被测系统或运行基础，但装好它并不会自动得到一套可信的 PR 评测标准。那是另一层工程，见LLM 应用的评测。

第一步：启动，而不是先研究所有插件

推荐从 Web UI 开始，因为模型、工作目录和会话状态都能直接检查。准备一个非敏感的练习仓库，以及可用的 DeepSeek API key。当前仓库声明的 Node.js 版本要求为 ^22.19.0 || >=24.0.0；源码开发使用的 pnpm 版本以 package.json 的 packageManager 为准。运行环境要求 →

cd /path/to/your/practice-repo
node --version
npx @deepseek-ai/dsh web

将示例路径换成自己的仓库。官方快速开始使用上面的命令，默认页面地址为 http://127.0.0.1:3080。不想自动打开浏览器时，加 --no-open。如果你要改 Harness 本身，再选择源码方式：安装说明 →

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

这两条路线解决不同问题：第一条是用 Agent 干活，第二条是开发 Agent 的运行框架。源码方式的启动目录是 Harness 仓库，后面仍要在 UI 中选择你真正想修改的项目。做团队试用时，记录具体安装版本或源码 commit；不要把“同一条 npx 命令”当成可复现的版本标识。

第二步：配置模型与 Workspace

1. 打开 Settings → Models，在 DeepSeek 卡片填写 API key 并保存。模型配置更新无需重启服务。
2. 点击 Choose workspace，添加并选中项目目录。即使从项目目录启动，新 Web UI 也不会自动选好 workspace；未选择时输入区不可用。
3. 确认模型选择器中的路由，然后新建会话，先要求它列出主要模块、入口和测试命令，暂时不要修改文件。

这些步骤对应官方的Web UI 指南。先做只读任务不是仪式：它能把“模型连不上”“目录选错了”和“代码任务太难”三类问题分开。让 Agent 引用实际文件路径，比让它泛泛介绍技术栈更容易发现上下文是否正确。

UI 保存的密钥位于 $DSH_HOME/.credentials.yaml，设置保留凭据引用；页面不会回显原始密钥。内置 Provider 可直接添加密钥；企业网关则走 Add a custom provider。已有请求记录的会话保留自己的模型选择，因此验证新默认模型时，最好新建会话。模型配置指南 →

进阶配置：Settings、Profile、Preset

遇到“配置了却没生效”，先判断改的是哪一层。这三个词不是同义词：

模型参数：先改最少的字段

在 Settings 中打开配置文件，找到实际运行实例的 settings.yaml，将下面字段合并到已有的 llm-deepseek 节点。不要覆盖整份文件，也不要重复创建同名 YAML 节点。保留 UI 已保存的凭据引用：

llm-deepseek:
  reasoningEffort: high
  maxTokens: 16384

reasoningEffort 是该适配器的推理强度设置，maxTokens 是单次请求的输出上限；这里的 16384 是示例取值，不是官方默认值，也不是整项任务的费用上限。多轮调用会继续产生消耗。原生 DeepSeek 适配器使用 deepseek-official 路由，默认凭据环境变量名为 DEEPSEEK_API_KEY。这些连接与模型设置会在下一次请求读取。原生适配器参考 →

企业网关：兼容协议要对得上

“OpenAI-compatible”不代表所有接口都一样。Chat Completions、Responses 和 Anthropic Messages 是不同协议。下面是一个结构示例：域名与模型 ID 必须替换为网关实际提供的值，启动 dsh 的进程必须能读到 GATEWAY_API_KEY。

llm-pi-ai:
  providers:
    team-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example.com/v1
      models:
        - id: your-served-model-id

这是 llm-pi-ai 路由，不能直接照搬 llm-deepseek 的所有参数。先确认最简单的文本请求和一次工具调用，再加推理参数或图片输入；否则协议错误、模型能力和工具执行问题会混在一起。自定义模型应填写服务端真实的能力与限制，不要为了消除错误虚报上下文窗口。通用 Provider 适配器 →

Profile：运行入口不是工具预设

web 用于浏览器交互；headless 执行一次任务并退出；sdk 通过 stdio 为 SDK 客户端服务。Profile 将插件 bundle、用户 patch 组合成运行树，使用 --dump-config 可以检查组合后的配置。CLI 入口说明 →

npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh --profile headless "Read the repository and report its test commands. Do not edit files or run commands."

用当前实例的配置输出定位问题，别从网上抄一整份不匹配的插件树。导出文件也应视为可能含敏感配置的材料，分享前检查。上面的“不要执行命令”只是任务约束，不是权限隔离；要限制真实执行能力，还需要权限策略与运行环境。

Preset：先用 Standard 建立基线

官方将 Agent 预设分为 Standard、Code、Minimal 和 Creator。Standard 提供常用能力；Code 让模型通过 TypeScript SDK 组合操作；Minimal 收缩到 bash 与文本编辑；Creator 面向运行时检查和插件试验。推荐先用 Standard，跑通一个有明确验收标准的任务，再改变工具组织方式。预设说明 →

不要把 Web 里的 Minimal 预设等同于 CLI 的 sdk-minimal。后者当前没有挂载审批与权限设置服务，使用 danger-full-access；“工具少”并不等于“权限小”。同样，普通 patch 编辑与添加新 bundle 的重载语义不同，新增 bundle 后需要重启对应 Profile。CLI 行为与权限边界 →

真正的使用方式：把任务写成可验收的修改

第一次实战别从“重构整个后端”开始。选择一个可以写出失败用例的小问题，例如分页边界。下面是示例任务，不假设你的仓库已经使用某个框架或测试工具：

目标：修复列表接口在 page=0 时行为不一致的问题。

先检查：
1. 定位路由、参数校验和现有分页测试，引用文件路径。
2. 根据 API 约定确认应该拒绝还是归一化；不明确就问我。
3. 列出最小修改计划，不顺手重构相邻模块。

实现与验收：
- 先补一个能复现问题的测试，再修改实现。
- 使用仓库已有测试、lint 和构建命令。
- 覆盖 page=0、正常页码和原有边界行为。
- 保留已有未提交改动，不删除或跳过失败测试。
- 需要新依赖、联网安装或扩大范围时，先请求确认。
- 最后报告 diff 摘要、实际执行的命令、结果和未验证项。
- 不提交、不推送、不部署。

这里最重要的不是提示词长度，而是把业务决策和技术执行分开。page=0 应返回 400，还是当成第一页，是契约问题，不应该让模型凭常识猜。让它先找项目证据，再写测试，你才有办法区分“修复了需求”与“实现了一个合理但错误的行为”。

团队还可以把稳定约定写进项目指令文件，例如目录职责、生成代码不可手改、测试入口与禁止动作。指令应该短、具体、可验证；不要把整个架构手册每轮塞进去。更重要的是，文档中的“禁止”不能替代实际权限控制。

当 Agent 汇报完成，按三个层次验收：结果是否符合接口契约，回归是否由测试覆盖，范围是否只有必要改动。先读 diff，再看测试输出。若它没有执行某项检查，明确记为“未验证”，而不是默认通过。

看执行轨迹，而不只看最后一句话

DeepSeek Harness 将会话活动保存在追加式日志中，Trajectory 视图用于查看执行过程；这是排查 Agent 行为的关键入口。会话与轨迹设计 → 但保存轨迹不意味着重跑必然产生同样结果：模型响应、依赖与外部环境都可能变化。

例如，一个修改失败可以拆成四种完全不同的情况：没读到正确文件；读到了但理解错契约；修改合理但测试环境缺依赖；测试已经失败却仍宣称完成。对应的修复分别是上下文、需求澄清、环境和验收机制。直接把模型换成“更强的”会掩盖这个区别。

评估它是否适合团队，可以固定几个真实小任务，记录成功率、总耗时、人工介入次数和实际 token 消耗。比较时保持同一仓库 commit、任务描述、模型与权限条件；每次只改一个 Harness 变量。不要用“最终回答很长”或“调用工具很多”当成生产力指标。关于停止条件和重试边界，可以继续看循环工程。

安全与排障：先检查边界，再放大能力

官方安全说明明确表示项目尚未经过安全审计，不能视为生产就绪。沙箱和审批只能降低风险，不能保证隔离。推荐在可丢弃的 VM、容器或专用环境中试用，只挂载必要代码，不提供生产云凭据或 SSH 私钥，并保留备份。安全说明 →

“本地运行”也不等于“数据不会离开电脑”：使用远程模型时，相关上下文需要发送给模型服务；额外工具、插件和遥测各有自己的数据路径。接入公司代码前，应检查当前版本的数据处理设置与组织要求，而不是仅凭 localhost 地址判断安全。数据处理说明 →

什么时候值得用？

如果你想研究 Agent 如何运行、接入自定义模型网关，或围绕真实开发流程调整工具与插件，DeepSeek Harness 值得在小范围试用。如果你只是想立刻获得一个几乎不需要维护的编码工具，那么开发者预览版的配置和升级成本也要算进去。可定制性是一种能力，也是一份维护责任。