DeepSeek Harness按证据排查Debug预设

“这个 Bug 修一下”通常不是一条足够好的调试任务。Agent 可能根据经验直接改代码，恰好让现象消失，也可能掩盖真正的根因。对可稳定复现、但原因尚不明确的问题，更可靠的流程是先提出可检验的假设，再收集证据，最后实施最小修复。

DeepSeek Harness 的创造模式可以基于已有预设创建一个新的 Agent 预设。目标是创建一个 Debug 预设，让 Agent 固定遵循“假设、插桩、复现、分析、修复、清理”六个步骤，并给出创建后应如何验证其工作方式。

以下以 DeepSeek Harness dsh@0.1.1-rc.2 为依据，配置内容在 2026 年 8 月 22 日核对。由于创造模式能操作运行时和预设组合，操作前应使用测试项目和可恢复的工作区。

适用场景和前置条件

这个预设适合以下问题：Bug 有明确的复现步骤；当前行为与预期不同；需要查看日志、堆栈、测试输出或运行时状态；修复后可以运行测试或重复操作验证。

开始前请准备：

• 一个可恢复的测试仓库，最好已有 Git 历史；
• 可重复执行的复现步骤、预期结果和实际结果；
• 与问题相关的测试命令或最小复现脚本；
• 已脱敏的日志、堆栈或示例数据；
• 一个明确的写入范围，例如只允许修改 src/ 与 tests/。

不要把生产目录、真实凭据或客户数据作为第一次试验的输入。调试时日志和终端输出很容易携带敏感信息，先使用脱敏样例更容易控制范围。

为什么从标准预设复制

一个预设至少包含 agent.cordis.yml，也可以带 preset.yml 保存显示名称和描述。官方的预设创作指导要求从已有预设复制，而不是修改系统内置的 standard、minimal、code 或 cordis 目录。内置预设可能被升级覆盖，错误修改还可能损坏预设创作环境。

官方给出的流程是：使用 agentPresets.copy(from, id, name) 生成用户目录中的副本，再编辑副本并用 standingKeyFor(id) 做挂载验证。相关创作指导随创造模式预设一同提供，可在官方创造模式目录中核对。

因此，Debug 预设应从标准模式复制。标准模式已有文件、Shell、检索、计划、待办和工作流能力，调试时通常仍然需要这些能力；我们只需要增加更严格的工作顺序和停止条件。

在创造模式中提交创建任务

切换到创造模式后，给 Agent 一份范围明确的任务。下面的提示词可以直接作为起点：

请基于标准预设创建一个用户级 Agent 预设。

预设 ID：debug
显示名称：Debug 模式

目标：用于排查可复现但根因未知的软件问题。

工作规则：
1. 先复述现象、预期行为、复现步骤和已知证据；信息不足时先提问。
2. 列出至少两个可验证的根因假设，并说明每个假设需要什么证据。
3. 只添加最小范围的日志、断言、测试或观测点；不要先做猜测性修复。
4. 按复现步骤收集输出，区分观察结果和推断。
5. 依据证据定位根因，只做能解释现象的最小修复。
6. 运行相关测试或重复复现；删除临时调试代码，并报告根因、修改、验证结果和剩余风险。

限制：
- 不修改系统自带预设，只创建用户副本。
- 默认不访问生产资源，不读取密钥或客户数据。
- 无法复现或证据不足时，明确停止并列出缺失信息，不伪造结论。

完成后：
- 报告新预设的目录和修改过的文件；
- 说明新增或修改的系统提示词；
- 对新预设执行挂载验证，并报告结果。

这里不要要求 Agent 机械复刻其他产品的私有实现。把想要的行为、限制和验证标准写清楚，比指定一个品牌模式更容易审查，也更不依赖外部页面变动。

预设中应出现什么

创建完成后，先检查两个文件。

preset.yml 应包含用户能识别的名称和简洁描述。例如：

name: Debug 模式
description: 基于证据排查可复现问题，按假设、插桩、复现、分析、修复和清理推进。

agent.cordis.yml 应保留标准模式所需的能力，并通过 persona 或指令段写入调试流程和限制。不要为了“调试更专注”随意删除 Shell、文件搜索或测试相关工具，否则 Agent 可能无法收集足够证据。

若新增了会发布服务的插件行，必须与其消费者一起放进带 isolate 的组中；否则多个会话挂载时可能发生服务冲突。官方说明将 standingKeyFor(id) 定义为实际挂载验证，它能发现缺包、配置无效、服务未激活和服务域冲突等问题；相关规则位于上文引用的官方创造模式目录中。

创造模式为什么需要比普通调试更严格的边界

创造模式不是单纯多了几个“编辑配置”按钮。官方预设说明中写明，cordis_mount 会在当前运行时执行模型写出的 JavaScript，而新写出的 composition 还可能被其他会话挂载。因此它应被视为接近 Shell 访问的信任边界，而不是一个可随时开启的普通工作模式。创造模式配置

这不意味着不能用创造模式做 Debug 预设，而是要将“写预设文件”“在内存中试挂载”“让新会话使用该预设”分开。第一次只修改用户副本和相关提示词；第二次只在受控运行时检查挂载是否成功；第三次才在测试项目中执行真实故障用例。每一步都有独立的可观察结果，出现问题时也不会把“预设语法错误”“运行时服务冲突”“调试流程质量差”混成同一个故障。

创建前还应明确哪些内容绝不能交给预设触碰：全局宿主配置、生产密钥、已安装的内置预设目录、其他用户会话的运行状态。创造模式所使用的能力不应替代代码评审，尤其是 Agent 建议引入新 plugin、修改共享服务或执行动态代码时，应让人先阅读变更范围与目的。

理解 host 与单会话预设的职责

DeepSeek Harness 的配置把共享能力与单会话能力分在不同层。宿主组合负责注册表、持久化、沙箱与审批、模型路由和跨会话共享的服务；Agent 预设负责一个会话暴露哪些工具、使用什么 persona 和提示词片段。若一个服务只属于当前 Agent，还需要放入隔离的 isolate realm，避免第二个会话挂载时与第一个会话发生名称或生命周期冲突。

对 Debug 预设而言，这条区分带来一个实用原则：优先只改工作流程和现有工具的可见性，不要为了实现“先假设、再插桩”的方法就新增宿主服务。大多数调试约束可以写进 persona、任务指令和工具使用顺序，风险和维护成本最低。只有确实需要一个会话私有的辅助服务时，才依据官方 composition authoring 指引处理隔离与挂载验证。

不要因为把一个 plugin 放进预设文件，就假定它只影响当前聊天。是否共享取决于服务注册位置和运行时组合。创建完成后用一个空的第二会话加载预设，再确认两个会话都能独立启动，是发现此类问题的低成本方法。

预设版本与回滚策略

调试流程会随着项目和团队习惯变化，不要只在同一个目录中不断覆盖。建议在 preset.yml 的描述或同目录说明文件里写出版本、修改日期和主要变化，例如“v1 仅增加六步证据流程”“v2 增加无复现时的停止规则”。这不要求引入复杂的发布系统，但能让一次异常行为有明确的对照点。

改动前可先复制用户预设目录，或用版本控制保存该目录的内容。出现挂载失败、提示词导致越界或调试流程不适合某项目时，先恢复上一个已验证版本，再单独分析新改动。不要通过改内置 standard 预设来“快速回退”，官方配置已明确提示安装目录会被升级覆盖，且错误编辑可能使创作预设本身无法使用。

一个最小回滚记录可以包括：

预设 ID 与显示名称：
本次改变的文件和原因：
挂载验证结果：
验收 Bug 与测试命令：
已知限制：
可恢复的上一版本位置或提交：

它会让 Debug 预设从“一段一次性提示词”变成可演进、可审查的工程配置。

用一个故障用例验收

预设能显示在选择器中，不等于它能按流程工作。使用一个已知可复现的低风险 Bug 做验收，记录下面四个阶段。

一个合格的验收提示可以写成：

在 tests/fixtures 中有一个已知失败用例。请使用 Debug 模式定位根因。
只允许修改 fixture 和对应测试；不要改生产配置。
完成条件：失败用例转为通过，已有相关测试不新增失败，临时日志已删除。

最后检查 Git Diff、测试输出和临时文件清单。即使结果正确，也要确认没有越过预先约定的目录边界。

把调试输入写成可验证的事实

Debug 预设能否发挥作用，很大程度取决于任务输入是否区分了事实和猜测。下面两种写法看似接近，能得到的排查质量却不同：

登录模块有问题，帮我修一下。

现象：使用有效测试账号提交登录表单后，页面停留在登录页。
预期：跳转到 /dashboard，并显示当前用户名。
复现：启动测试服务后执行 tests/e2e/login.spec.ts 中的第一条用例。
已知证据：浏览器控制台没有错误；服务端日志出现 401。
范围：只允许读取 src/auth、tests/e2e 和相关配置；修改前先报告假设。
完成条件：该失败用例通过，相关认证测试不新增失败，临时观测代码已清理。

后者没有直接给出根因，但限定了现象、预期、复现、证据、范围和完成条件。Agent 因此可以提出“凭据未传递”“测试数据失效”“会话创建失败”等不同假设，再分别设计最小观测，而不是一开始就改认证逻辑。对无法公开的日志或数据，应提供脱敏片段与字段说明，不要为了让 Agent 复现而复制真实凭据。

如果复现步骤本身不稳定，也要如实写出触发概率和已观察到的条件。例如“连续运行 10 次中出现 2 次”与“每次必现”需要不同策略。前者应优先收集时间、并发、输入差异和环境信息；后者可以先用最短路径做断点、日志或单测。预设只能约束工作顺序，不能替代高质量的问题描述。

每个假设都要配一个可否定的观测

“列两个假设”并不是为了让报告显得全面，而是为了避免单一路径的确认偏误。一个有用的假设必须能被某个观察结果支持或否定。例如：

表中字段只是通用示例，实际观测点需要跟项目技术栈匹配。关键是日志、断言或测试应当尽可能局部，能够回答一个具体问题。一次性打印整个请求对象、整个数据库记录或大量环境变量，通常既增加噪声，也有泄露敏感信息的风险。

对于已经有单元测试的模块，优先扩展失败用例或添加最小断言；对于跨服务问题，可以先在边界处记录一个关联 ID，再沿着同一个 ID 查看各层日志。没有证据之前，不要把“可能是缓存”“可能是网络”写成根因，也不要为了让测试转绿而吞掉异常、放宽断言或增加无限重试。

修复、清理与回归验证要形成闭环

收集到证据后，Debug 预设应把修复限制在能解释该证据的最小范围。比如日志证明测试 fixture 使用了过期字段，优先修改 fixture 或其构造逻辑；不要顺带重构整个认证模块。修复前后都要能清楚回答：哪个观察导致了这个改动、改动如何改变失败条件、哪个测试证明它没有破坏相邻行为。

一个完整的收尾应包括：

1. 重复原始复现步骤，确认最初现象消失。
2. 运行直接相关的测试集合，记录通过、失败与跳过情况。
3. 检查 Diff，确认只修改了约定目录和必要文件。
4. 删除临时日志、断言、fixture 和调试开关，或将确有长期价值的观测改为正式可维护的监控。
5. 写出尚未覆盖的边界，例如并发、旧数据、特定浏览器或外部服务故障。

“清理”不等于删除所有新增内容。若新的测试准确覆盖了根因，它应当保留，防止回归；应删除的是临时打印、只为本次定位而加的开关和含敏感信息的样例。区分两者能让 Debug 预设既不留下噪声，也不丢掉可复现的保护。

建议固定一份调试报告格式

预设的最终输出可以要求包含下面的字段：

现象与影响范围：
复现步骤与结果：
已检查的假设及证据：
确认的根因：
修改的文件和修改理由：
验证命令与结果：
清理的临时内容：
未验证条件和剩余风险：

这样做的好处是，即使这次未能修复，下一位接手的人也能知道已经排除了什么、证据在哪里、为什么停止。比起“我试过几种方法都不行”，它更接近工程上可继续推进的故障记录。

对于无法复现的事件，Debug 预设的正确产物不应是假装找到了根因，而是一份最小化的观测计划：还缺哪些输入、该在哪个边界增加什么日志、触发时如何保存关联 ID、什么条件满足后才能进行下一轮修复。把“未知”保留在报告里，是这类预设比直接改代码更有价值的地方。

常见问题

预设创建后无法显示或无法启动。 先检查用户副本的 preset.yml 是否存在、YAML 是否有效，再做挂载验证。不要尝试修补系统内置预设。

Agent 仍然跳过证据收集。 调试流程必须写成明确的硬约束，例如“未记录复现输出前不得修改业务逻辑”和“至少列出两个可验证假设”。只写“请仔细调试”通常不够。

为了调试打开了过多权限。 将外部系统、生产数据和凭据读取设为默认禁止项。需要时拆成一个经人工确认的独立步骤，而不是让 Debug 预设默认拥有这些能力。

修复后测试仍然不稳定。 不要将偶然通过视为修复成功。保留失败输出，缩小复现步骤，并报告尚未确认的条件。

结论

Debug 预设的价值不在于多一段角色提示词，而在于把调试的证据链固化下来。复制标准预设、只修改用户副本、挂载验证后再用真实故障验收，可以降低“看起来创建成功、实际无法工作”的风险。

对于根因未知的问题，先假设、再观测、后修复，比让 Agent 直接凭经验改代码更容易解释，也更容易在失败时继续排查。