DeepSeek Harness 使用

本文讲解 Web UI 的基础操作、模型配置、工作区、运行模式切换、会话与轨迹调试、权限确认、命令行使用，不涉及底层插件源码开发。

一、Web UI 基础界面概览

启动服务后访问 http://127.0.0.1:3080 进入工作台。界面主要分为四大区域：

1. 设置面板（Settings）：模型服务商、API密钥、全局参数、插件查看；
2. 工作区选择（Workspace）：指定Agent可读写的本地项目目录；
3. 会话与任务输入区：新建会话、输入任务指令；
4. 轨迹视图（Trajectory）：查看完整Agent执行事件流，是调试的核心面板。

重要前提：必须先选择工作区 + 配置模型API密钥，否则无法发起任务。

二、模型服务商与API密钥配置

进入 Settings → Models 模型配置页面。

1. 选择模型服务商，默认 DeepSeek 官方；也可添加其他兼容 OpenAI 协议的模型端点（本地Ollama、第三方大模型服务）。
2. 在API Key输入框填入密钥，保存。保存后页面不会完整回显密钥，仅做掩码展示，密钥会保存在本地配置文件，不会上传第三方服务器。
3. 选择目标模型，例如 deepseek-v4-flash。
4. 可调整基础参数：最大上下文长度、温度、超时时间，新手保持默认即可。
5. 保存配置，无需重启服务，立即生效。

密钥也可通过环境变量、项目内 .env 文件注入，适合脚本/CI场景。

三、选择工作区（Workspace）

Harness 会限制Agent的文件操作范围，所有读写、Shell命令都被限定在选定的工作目录内，保障本地文件安全。

1. 点击界面上「Choose workspace」，选择本地项目文件夹；
2. 选中目录后，会话输入框才会被激活；
3. 建议选择一个专门的空项目目录做测试，不要直接选择系统根目录、包含重要隐私文件的目录。

工作区一旦选定，Agent可以读取目录内文件、新建文件、执行shell命令；超出该目录的文件访问会被沙箱拦截。

四、切换Agent预设（四种运行模式）

在设置或会话顶部选择Agent预设Profile，对应四种运行模式，每种模式自动加载不同插件组合：

1. 标准模式（Standard）
   全套工具集：文件编辑、Shell执行、文件检索、网页抓取、任务规划、子代理、工作流。适合绝大多数编码、项目自动化任务，新手默认推荐。
2. PTC模式（Code Mode）
   保留标准模式全部能力，采用Code Mode SDK。模型输出TypeScript代码编排多步工具调用，减少多轮往返，适合复杂长链路任务。
3. 极简模式（Minimal）
   仅保留持久Bash、文本替换编辑器两个工具，移除所有额外插件。用于干净环境下做Agent基准评测，消除多余组件干扰。
4. 创造模式（Creative）
   拥有标准模式全部能力，额外开放运行时插件检查、内存插件调试、自定义预设创作。面向插件开发者，可试验自定义插件组合。

切换预设后，新建会话才会使用新的插件组合；已有会话沿用创建时的Profile。

五、新建会话，执行第一个任务

1. 点击新建会话，确认当前选中的运行模式、工作区；
2. 在输入框输入任务指令，例如：

列出当前工作目录下所有js文件，统计每个文件行数

3. 发送任务，Agent开始执行；
4. 当执行高危操作（删除文件、修改重要配置）时，系统会弹出人工确认弹窗，需要手动批准后才会执行，防止误操作。

执行过程中可以随时暂停、继续任务。

六、Trajectory 轨迹视图（核心调试功能）

Trajectory是Harness最核心的调试面板，记录仅追加式会话事件流，不会覆盖历史记录。
可查看的内容：

• 系统提示词、模型思考推理内容；
• 每一次工具调用的入参、返回结果；
• 子代理调度、上下文注入事件；
• 全部工具执行日志。

支持能力：

• 回放：从头到尾复现整个任务流程；
• 分叉（Fork）：基于会话中任意一个历史节点新建分支会话，修改指令重试，方便对比不同策略结果；
• 检索：在事件流中搜索关键词，快速定位报错、工具返回信息；
• 会话恢复：关闭页面后，重新打开可继续上次未完成任务。

调试Agent时，优先看Trajectory，判断是提示词问题、工具调用错误还是模型输出异常。

七、命令行（CLI）与 Headless 无头模式使用

除Web UI外，dsh 支持终端直接执行任务，适合脚本自动化、批量评测。

1. 交互式CLI

dsh --profile standard

直接在终端对话，Agent执行工作区内任务。

2. Headless 一次性任务（执行完自动退出）

dsh --profile standard "读取README.md并总结文档要点"

适合嵌入shell脚本、CI流水线，不需要人工交互。

3. 查看当前加载的完整配置树（开发调试）

dsh --profile web --dump-config

打印当前Profile完整插件与配置结构，用于排查插件加载、自定义补丁调试。

八、会话管理

• 新建会话：每个任务独立会话，上下文隔离；
• 会话保存：会话日志默认本地持久化存储，重启服务不会丢失；
• 会话归档/删除：清理不需要的历史任务，释放存储空间；
• 会话分叉 Fork：基于历史节点生成新会话，做A/B测试。

九、权限与安全说明

1. Agent的文件读写、Shell命令严格限制在选定工作区；
2. 高危操作默认启用人工审批机制；
3. 所有会话日志、密钥默认本地存储，不会自动上传云端；
4. 沙箱隔离执行代码，降低恶意代码风险，但依然不建议在工作区存放核心机密。

十、常见使用问题

1. 输入框灰色无法输入：没有选择工作区，选择目录后即可解锁。
2. 模型调用报错：检查API Key、模型名称、接口地址；确认余额、接口权限。
3. 工具调用被拦截：操作超出工作区目录，或者触发高危操作审批，需要手动确认。
4. 轨迹视图空白：任务尚未开始执行，或者会话未触发工具调用。
5. 切换运行模式不生效：已有会话不会自动更新Profile，需要新建会话。