故障排查

先看运行状态，再看最近事件，最后看日志。大多数问题都能在这三处确定是合同、模型、插件还是存储层出错。

最短诊断流程

CLI：

scientific-agent status RUN_ID
scientific-agent status RUN_ID --events

Control API：

curl -sS http://127.0.0.1:8000/api/v1/health | jq
curl -sS http://127.0.0.1:8000/api/v1/diagnostics | jq
curl -sS http://127.0.0.1:8000/api/v1/runs/RUN_ID/state | jq

桌面端：打开 Control Room，先看 State 的 current_terminal_failure 和 Recent failures，再看 Timeline 的 Failures 过滤器、Jobs 和 Model calls。Settings → About 可以打开日志位置。

理解运行状态

不要只根据“进度条不动”判断卡死。长求解器可能没有中间指标；检查 Jobs 的状态和 Timeline 是否仍有心跳更新。

无法创建研究合同

acceptance metric has no producer

所选能力的 metric_outputs 中没有验收指标。

• 打开能力详情核对实际指标名。
• 检查大小写、点号和下划线；指标会规范化，但不能凭近似名称匹配。
• 插件开发者需同时更新 plugin.yaml 与 Python manifest。
• 如果指标必须独立评估，加入对应 trusted evaluator 能力。

重复或冲突的验收条件

acceptance_criteria 中每个 metric 只能出现一次，且第一项必须与 acceptance 完全相同。合并同名条件或选择更严格的一项。

能力约束无效

每条约束只能包含映射类型的 when 和 require。先用能力示例跑通，再增加冻结参数；嵌套字段必须与插件实际输入一致。

输入上传失败

桌面端一次研究最多 20 个输入文件。检查文件是否仍可读、Base64 是否完整，以及 artifact type 是否合适。大数据集更适合由受控插件从明确位置生成或导入，不要塞进 API 请求。

Provider 或模型失败

找不到密钥

CLI 配置中的 auth_env 是环境变量名，不是密钥值：

export OPENAI_API_KEY="..."
python -c 'import os; print(bool(os.environ.get("OPENAI_API_KEY")))'

从不同终端、systemd 或 IDE 启动时，环境变量可能没有传入。桌面端应在 Settings → Providers 重新保存凭据并运行 Test connection。

Codex CLI 未登录

codex login

完成浏览器登录后，回到 Settings 重新检测。确保 Desktop 与终端使用同一操作系统用户和同一个 Codex 配置目录。

连接成功但结构化输出失败

• 核对 API format 与端点：Responses、Chat Completions、Anthropic Messages 不可混用。
• 为兼容端点尝试其确实支持的 json_schema、json_object 或 tool_call。
• Anthropic Messages 不支持这里的 json_object 模式。
• 增加 schema repair 只能处理有限格式偏差，不能修复不兼容 API。

超时或频繁重试

查看 Model calls 的延迟、错误码、重试数和 fallback。先减小 max_output_tokens 或任务规模，再谨慎增加 timeout_seconds。持续的 401/403、model not found 和配额错误不会因为重试而改善。

插件问题

Installed 但能力不可选

插件还没有 Enable，或启用后发现依赖缺失。打开详情检查 status、missing_dependencies 和 load_error。

entrypoint 无法导入

entrypoint 使用 package.module:ClassName，不是文件路径。确认：

• ZIP 或目录中包含该 Python package；
• package 目录有 __init__.py；
• 类继承 ScientificPlugin；
• 依赖装在 Scientific Agent 实际使用的 Python 环境中；
• import 阶段没有执行依赖外部文件或网络的副作用。

ZIP 被拒绝

常见原因是多个 plugin.yaml、压缩包内含虚拟环境/符号链接、路径穿越、加密条目，或超过 10 MiB/50 MiB/512 文件限制。只打包清单、源代码和少量必要资源。

能力调用输入错误

从能力详情复制 example，再逐项替换。普通输入不能有清单未声明的键；需要的产物必须放在 artifact_inputs，不能把 artifact ID 当普通路径字段传入。

Local Executor 问题

• 命令找不到：依赖工具没有安装在应用进程的 PATH 中。用同一用户和环境在终端确认。
• 输出缺失：生成代码没有写入 JobSpec 声明的相对文件名。
• 退出码非零：查看 Jobs 中保存的 stdout、stderr 和结构化 failure type。
• 取消很慢：外部进程没有及时处理终止信号；等待状态完成，必要时在隔离环境中清理。
• 路径被拒绝：输入/输出必须留在工作区，不能使用绝对路径或 ..。

不要通过放宽路径检查来修复任务；应修正 JobSpec 或代码的文件约定。

产物或谱系问题

hash mismatch / 产物损坏

底层文件与记录的 SHA-256 不一致。不要覆盖记录或重新计算 hash 来掩盖问题。

1. 停止该运行。
2. 保存日志和损坏文件的副本。
3. 从已验证备份恢复整个相关运行，或创建新运行重算。
4. 检查同步盘、手工编辑和磁盘故障。

Lineage 中没有预期关系

插件应通过 artifact inputs、已有 artifact ID 或同一次返回中的 parent_names 声明关系。仅在 metadata 的自由文本中写文件名不会形成谱系边。

无法预览文件

控制室内置文本和 CSV 预览；大型或二进制产物可能只能下载。下载后使用领域工具打开，并核对 UI 中的类型、大小和 hash。

存储与恢复问题

找不到旧运行

最常见原因是 --data-dir 不同。运行：

scientific-agent --data-dir EXPECTED_DIR status RUN_ID

桌面端在 Settings → Storage 查看当前目录。不要把 cache 目录误当 data 目录。

数据目录不可写或空间不足

检查目录权限、挂载状态和可用空间。先暂停运行并创建备份，再通过 Settings 或 /storage/location 迁移。不要在应用运行时手工移动一半目录。

resume 被拒绝

只有可继续状态才能 resume。SUCCESS、FAILED 和 CANCELLED 是终态。对 INTERRUPTED 使用 Recover；对 BUDGET_EXHAUSTED 先审查并通过受控介入增加有限预算。

Control API 问题

先访问 /api/v1/health 确认端口与 mode。开发服务的交互式 schema 在 /api/v1/docs。SSE 断线后使用上次 cursor 重连，不要同时启动大量从 after=0 开始的流。

Benchmark 问题

• --prepare-only 失败：先确认 Xsuite/ML 依赖和 spec 中相对 base_config 路径。
• spec hash 不一致：冻结规格、基础配置或协议相关文件发生改变；不要强行复用旧结果目录。
• 没有有效成功结果：查看各 trial 的 Runtime 状态和可信验收指标，而不仅是聚合报告。
• integrity 失败：该报告无效；检查私有数据泄漏、事件冻结、predictor hash 和跨运行隔离。
• 重跑没有从头开始：difficulty runner 设计为按 slot 恢复；若要独立实验，使用新的 --data-dir。

更新检查不可用

About 页面会显示当前 Desktop 和 Runtime 版本。若发行版没有配置更新源，Check for updates 会明确显示不可用；这不是网络故障。按项目的正式发布渠道安装新版本，并在升级前创建备份。

提交问题时附带什么

提供最小且已脱敏的信息：

• Desktop、Runtime、操作系统和 Python 版本；
• run ID 与最终状态；
• diagnostics 输出；
• Timeline 中相关事件类型和错误码；
• 插件 ID/版本、能力 ID和 load_error；
• 可复现的最小配置（删除密钥、私有数据和绝对个人路径）。

不要发送 API key、操作系统凭据、evaluator-private 内容或整份敏感数据目录。