DeepSeek Harness 是面向 Agent 开发与实验的开发者预览版工具。其设计重点不是固定一套 Agent 流程，而是通过 preset 组合运行时能力，并以插件形式扩展工具、界面与行为。使用本地 Web UI 时，Trajectory 视图可把一次 Agent 会话呈现为可检查的执行轨迹，帮助开发者回看模型决策、工具调用及其前后上下文。
对编码 Agent 而言，最终文本往往不足以说明问题：失败可能来自工具参数、工作目录、命令输出、模型在中途丢失约束，或某个插件的运行时行为。Trajectory 的价值在于将排查对象从“最后回答”扩展为“完整执行过程”。当需要从某一步开始尝试另一种处理方式时，可基于该会话节点创建分叉，避免重新从头运行并混淆两条不同的排查路径。
注意：Harness 处于开发者预览阶段。preset、插件接口和运行行为可能发生不兼容变更，因此应将可复现命令、使用的 preset、插件配置及关键轨迹一并记录；升级后不要直接把旧会话的行为等同于新环境中的结果。
一、先理解 Harness、preset 与插件
- Harness：承载 Agent 运行、工具使用和交互界面的运行框架。
- preset：一组预先组合好的运行配置。它决定 Agent 可获得哪些工具与工作方式，适合按任务目标切换，而非为每个任务从零配置。
- 插件：向运行时加入能力的扩展单元。插件化架构使开发者能够实验工具、运行时行为和自定义 Agent 组合。
- Trajectory：会话执行轨迹的检查入口。它应被视为调试与复现材料，而非只用于浏览最终答案。
二、四种官方运行模式的能力边界
- 标准模式：面向完整的编码 Agent 工作流。适合让 Agent 在较完整的开发环境中理解任务、修改代码、使用工具并持续推进工作。需要排查多轮编码任务时，优先在此模式查看完整轨迹。
- PTC 模式：通过 Code Mode SDK，让模型使用 TypeScript 编排多步工具调用。它适用于工具调用顺序、条件分支和多步骤流程本身就是问题重点的场景。排查时应特别关注生成或执行的 TypeScript 编排逻辑，以及每一步工具调用的输入和输出。
- 极简模式：只保留持久 Bash 与
str_replace_editor。它适合最小工具集下的模型评测、工具使用基准测试，以及排除复杂插件干扰的诊断。它不等于功能更弱的标准编码环境，而是有意缩小变量范围。 - 创造模式：用于检查运行时、实验 Cordis 插件，并制作自定义 preset。适合需要改变 Agent 组成或研究插件行为的开发者。此模式中的轨迹应同时用于验证 Agent 任务结果和验证自定义运行时是否按预期工作。
三、按需求选择模式
- 编码开发：选择标准模式。目标是完成较完整的软件开发任务，并追踪代码修改、命令执行和多轮决策之间的关系。
- 工具编排：选择 PTC 模式。目标是让模型以 TypeScript 明确组织多步工具调用，便于检查顺序、分支与中间结果。
- 模型评测：选择极简模式。目标是降低工具与插件变量，以持久 Bash 和
str_replace_editor为固定条件比较任务表现。 - 自定义 Agent：选择创造模式。目标是检查运行时、试验 Cordis 插件，或制作和维护自己的 preset。
四、启动本地 Web UI
开始前需要安装 Node.js，使系统能够运行 npx。在终端中执行以下命令启动 Harness 的本地 Web UI：
npx @deepseek-ai/dsh web命令启动后，按终端输出提示在浏览器中打开本地地址。由于本文不假定固定端口、操作系统或预览版具体版本，应以本机终端实际输出为准。进入界面后，选择与任务匹配的 preset 或运行模式，创建或打开一个 Agent 会话，并在会话完成、停滞或出现异常时进入 Trajectory 视图。
五、用 Trajectory 回放会话
- 先明确要回答的排查问题，例如“Agent 为什么没有修改目标文件”“某个命令为何失败”或“工具调用为何没有进入下一步”。没有明确问题时，轨迹容易变成难以筛选的日志。
- 在 Trajectory 中从会话起点向后检查每个关键节点，重点核对模型输入、工具选择、工具参数、工具返回结果和后续模型响应是否连贯。
- 定位第一个与预期不符的节点。不要只看最后一次报错，因为后续失败常常是更早的错误假设、路径错误或工具结果未被正确利用所导致。
- 对涉及文件修改的会话，检查
str_replace_editor的目标内容与替换范围；对涉及命令的会话，检查 Bash 的当前上下文、命令文本和输出。极简模式下，这两类记录尤其是主要诊断依据。 - 对 PTC 模式，按工具调用链检查 TypeScript 编排是否遗漏前置结果、错误处理或必要的后续调用，而不是只判断最终工具是否成功。
六、何时分叉，以及如何让分叉有诊断价值
分叉适用于“保留已确认正确的历史，只替换某一步之后的假设或指令”的情况。例如，前半段已正确定位项目目录，但 Agent 在选择编辑策略时走错方向，就应从该决策附近分叉，而不是重新执行整段会话。
- 先在原轨迹中选定分叉点：该点之前的上下文、工具结果和约束应当仍然可信。
- 在分叉会话中只改变一个主要变量，例如补充文件路径、改写任务约束、替换工具调用策略，或换用另一种 preset。一次改变多个变量会削弱对比结论。
- 将原分支与新分支并行比较，检查它们从分叉点开始的工具选择、参数和输出差异。
- 记录有效分叉所依赖的环境条件。若结果依赖工作区状态、外部服务或插件版本，后续重放不一定得到相同结果。
示例：用分叉定位编辑失败原因
假设 Agent 已通过 Bash 找到项目目录，却在后续编辑步骤中失败。先在 Trajectory 中确认目录定位命令及其输出是否正确；再查看 str_replace_editor 所引用的文件和匹配文本。若文件路径正确但匹配内容不再存在，可从编辑前的节点分叉，在新分支中要求 Agent 先读取当前文件内容，再执行更精确的替换。这样比较的重点不是两次最终回答的措辞，而是新分支是否基于实际文件状态重新形成编辑操作。
七、常见错误
- 把 Trajectory 当成结果展示页：只看最终回答会漏掉首个异常节点。应从最早的不一致处向后追踪。
- 在错误节点之后才分叉：若错误假设已经污染后续上下文，过晚分叉会保留无效前提。应尽量回到最后一个已确认正确的节点。
- 为评测选择了工具过多的模式：当目标是比较模型在固定工具集中的表现时，标准模式或自定义插件可能引入额外变量；极简模式更便于控制条件。
- 把 PTC 当成普通对话模式：PTC 的核心是以 TypeScript 编排工具调用，诊断重点应放在调用链和中间状态，而非仅检查自然语言回复。
- 升级后直接复用旧结论：开发者预览版可能有破坏性兼容变更。升级 Harness、preset 或插件后，应重新验证关键流程，并保留旧环境的配置记录。
八、限制与复现边界
Trajectory 能帮助解释一次已记录会话的执行过程，但不能自动证明该过程在不同机器、不同工作区状态、不同模型配置或不同插件版本下必然复现。尤其是涉及持久 Bash、文件系统和插件运行时的任务，环境状态会直接影响后续步骤。对于需要稳定评测的场景，应固定任务输入、工作区、运行模式和工具条件；对于自定义 Agent，则应同时保存 preset 与相关插件配置。
排查 Agent 会话时，先找第一个偏离预期的轨迹节点，再围绕该点建立单变量分叉。这样得到的是可比较的诊断过程，而不只是一次偶然成功或失败的最终输出。