故障排查
先对失败步骤做最小检查。不要把删除宿主缓存、插件目录、报告或用户配置作为第一 反应。诊断输出和公开 issue 中不要包含凭据、原始会话记录、私密提示词或完整报告。
如果独立 CLI 可用，请先运行只读生命周期检查：
better-harness plugin status --host all
better-harness doctor --platform all
这两个命令不访问远程注册表、不写配置、不执行安装命令，也不读取原始会话正文。
partial、unobserved、manual 或 unavailable 表示保留证据边界，不能据此推断
宿主已经加载插件。
看不到插件或 Skill
安装或更新 Better Harness 后，请开启新的宿主会话或任务。已有会话可能仍在使用 启动时加载的插件清单。然后执行该宿主支持的检查：
| 宿主 | 最小受支持检查 |
|---|---|
| Claude Code | 运行 claude plugin details better-harness@better-harness；详情中应包含 Skills (1) better-harness。 |
| Codex | Desktop 在 Settings > Plugins 中检查；CLI 运行 codex plugin list --marketplace better-harness。 |
| Qoder | Desktop 已内置；手动安装 CLI 插件后运行 qodercli plugin list；生命周期计划不会输出已经漂移的安装语法。 |
| Cursor | 运行 better-harness plugin status --host cursor --surface agent；在本机 Cursor help 合同完成核对前，安装保持不可用。 |
| Qwen Code | 运行 qwen extensions list 并确认其中包含 Better Harness，然后开启新会话并运行报告提示词。 |
| GitHub Copilot | 运行 copilot plugin list 和 copilot skill list；两处都应包含 better-harness。 |
如果 marketplace 命令失败，请返回对应宿主的安装标签页，逐字核对仓库源和命令。
特别是当前 Codex 先对仓库 URL 使用 marketplace add，再使用 plugin add。
如果本机原生 help 没有公开同样的合同，请不要复制旧版 Qoder 或 Cursor 安装示例；
生命周期计划会刻意返回手工或不可用状态。
Cursor 源码本地加载当前不可用
已核对的原生 cursor-agent help 没有公开受支持的源码本地插件参数。不要复用旧版
启动命令，也不要因为仓库包含 .cursor-plugin/plugin.json 就推断当前运行时可以
加载这个源码检出。
请用 better-harness plugin status --host cursor --surface agent 检查有边界的会话
证据。在 Cursor 发布匹配的原生合同之前，Better Harness 没有可供排查的受支持安装
命令；应保留生命周期结果 unavailable，而不是把检出目录复制到全局插件目录。
独立或源码 CLI 报告运行时版本不受支持
独立和源码 CLI 在 Windows、macOS 和 Linux 上支持 Node.js
>=22.20.0 <25.0.0 及 npm >=10.9.3 <12.0.0。请检查当前实际使用的可执行文件：
node --version
npm --version
切换到本仓库选定的运行时后再重试。不要绕过声明的 engine 范围，也不要为了隐藏 版本错误而修改 package lock。
源码 CLI 拒绝仓库目录
当 --cwd 为空、不存在、不可访问或不是目录时，better-harness report 会返回
INVALID_CWD。请从要检查的仓库中运行，或显式传入一个已存在的目录。从 Better
Harness 源码检出运行时，可用以下跨平台检查指向当前目录：
node scripts/better-harness.mjs report --cwd . --json
没有找到会话证据
会话证据缺失或不完整并不表示安装失败。Better Harness 会明确保留这一限制，而不 编造活动记录。从源码检出运行时，可以主动只检查静态项目证据：
node scripts/better-harness.mjs report --no-sessions
快速开始的会话探测默认使用 Qoder 数据根目录。如果该目录已被有意迁移，请通过
--qoder-home 传入已授权的位置：
node scripts/better-harness.mjs report --qoder-home /path/to/qoder-data
不要把搜索范围扩大到无关的用户目录，也不要在 issue 中附加原始会话文件。
报告已完成但找不到文件
行内输出或 no-files 输出本来就不会写入产物。对于持久化报告，请使用宿主最终
返回的准确报告链接。默认根目录和产物如下：
| 提供方 | 报告根目录 | 持久化产物 |
|---|---|---|
| Qoder | <target>/.qoder/better-harness/<run>/ | findings.json、canvas.json、report.canvas.tsx |
| Claude Code | <target>/.claude/better-harness/<run>/ | findings.json、report.md、report.html |
| Codex | <target>/.codex/better-harness/<run>/ | findings.json、report.md、report.html |
| Cursor | <target>/.cursor/better-harness/<run>/ | findings.json、report.md、report.html |
| Qwen Code | <target>/.qwen/better-harness/<run>/ | findings.json、report.md、report.html |
| GitHub Copilot | <target>/.copilot/better-harness/<run>/ | findings.json、report.md、report.html |
<target> 指正在接受评审的仓库；只有当 Better Harness 源码仓库本身就是选定目标
时，它才表示当前源码检出。
收集限定范围的诊断信息
报告问题前，只记录复现失败步骤所需的信息：
- 从已安装插件元数据获取 Better Harness 版本；源码检出则运行
node scripts/better-harness.mjs --version。 - 宿主及其版本、操作系统和安装方式。
- 失败的准确命令或功能，以及最小的有效错误信息。
- 最小复现、预期行为和实际行为。
- 仅当问题涉及源码 CLI 或运行时时，提供 Node.js 和 npm 版本。
- 问题涉及会话证据时，说明
--no-sessions是否可用。
请移除 token、凭据、私密路径、原始提示词、会话记录，以及与复现无关的报告内容。
报告可复现的问题
如果以上检查仍未解决问题，请打开 GitHub issue 选择页， 选择 Bug report 并提供上方限定范围的诊断信息。请先搜索已有 issue，只链接 可以安全共享的产物。