故障排查与错误码说明

本文汇总 Desktop、Control API 和 Runtime 中常见、可操作的错误。先看错误码和完整消息， 再看运行状态、最近事件，最后看日志。大多数问题都能据此确定是附件、合同、模型、插件、 执行器还是存储层出错。

最短诊断流程

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 可以打开日志位置。

怎样阅读一条错误

Control API 的应用错误通常使用统一结构：

{
  "error": {
    "code": "AUTONOMOUS_PLANNER_UNAVAILABLE",
    "message": "The language-model task planner could not produce a validated decomposition: ..."
  }
}

桌面端会把它显示为“控制 API 错误 · 错误码”，下一行是完整消息。诊断时注意：

• code 是稳定的错误类别，适合检索文档和日志；
• message 才包含本次失败的具体原因，例如文件类型冲突、模型路由不存在或插件依赖缺失；
• HTTP 409 表示当前状态或已冻结数据发生冲突，不等于服务器宕机；
• HTTP 422 表示请求或科学合同不合法；
• HTTP 502 多见于上游模型服务调用失败或其返回值始终无法通过校验；
• Timeline 中的 failure type 和事件名不一定是 Control API 错误码，应结合所属 Job、Model call 和 current_terminal_failure 一起判断。

例如：

AUTONOMOUS_PLANNER_UNAVAILABLE
data_roles[0] role research_dataset conflicts with trusted attachment kind unknown

真正根因是第二行：规划模型把附件当作数据集，但 Runtime 的可信静态分析没有识别出该格式。 这不是网络错误，也不表示文件内容损坏。

理解运行状态

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

运行生命周期与预算错误码

附件上传与格式识别

“上传成功”和“已识别为数据集”是两件事。上传阶段会保存并校验文件的名称、大小和 SHA-256， 同时进行不执行文件内容的静态分析；无法识别格式并不会让上传失败，而是把静态类型记为 unknown。自主规划随后必须服从这个可信类型。

自主任务附件格式

文件夹上传与 solver_bundle

使用 选择文件夹 时，客户端发送 source_kind=directory，后端验证单根目录后识别为 directory_bundle；固定 ZIP 只作内部传输编码，不再把目录降格为普通压缩包。目录仍占用一个 附件名额。Web 与 Desktop 都限制为最多 512 个普通文件、编码前合计 50 MiB、编码后最多 10 MiB、路径最多 32 层且 UTF-8 路径不超过 1,024 字节。危险路径、多个根、规范化后重复路径、 读取失败或过程中变化的文件和超限内容会被拒绝；Desktop 原生选择还会拒绝 symlink 与特殊 文件。支持目录项的 WebUI 浏览器可以直接拖入文件夹；否则请使用 选择文件夹。

Web File API 无法保留 Unix mode，浏览器归档因此把普通文件写成非执行条目；这本身不会阻止 求解器识别，Runtime 会在隔离工作区中确保选中的求解器二进制可执行。后端仅在安全 ZIP 同时 包含非空 README/usage 和 ELF、PE 或 Mach-O 文件头时升格为 solver_bundle。README 最多读取 64 KiB，作为不可信文档上下文；二进制不会启动，归档也不会整体解压。危险或重复路径、symlink、 加密成员、膨胀风险、成员过多会阻止目录画像；手工上传的 ZIP 未声明目录来源时仍显示 zip_archive。

正常的 XLSX 现在可以直接用于自主回归研究。为保证上传内容不会变成执行入口，解析器有意采用以下边界：

• 选择扫描范围内首个具有非空、唯一表头且至少一行数据的二维工作表；
• 不运行公式，只使用文件中已有的缓存标量值；没有缓存值的公式单元格按空值处理；
• profile 阶段会忽略并报告宏部件；需要密封 holdout 的回归任务会拒绝含宏的工作簿；
• 不跟随外部关系，不接受加密、重复、符号链接或危险路径成员；
• XML、工作表数量、行列、单元格、文本和 ZIP 解压体积都有固定上限。

复杂或不安全的 XLSX 仍可能被标成 unknown，或在回归 holdout 阶段返回 HOLDOUT_DATASET_INVALID。此时按下面方式整理：

1. 使用唯一、非空的首行列名，取消合并单元格，避免标题、说明文字和数据混在同一区域。
2. 如果表格包含公式，在 Excel 中重新计算并保存，确保缓存值已写入文件。
3. 移除 VBA/宏、外部链接和加密；或把需要分析的工作表另存为 CSV UTF-8。
4. 如果另存为 CSV，一个文件只保留一张二维表，然后重新上传并发起任务。
5. 如果文件只是背景材料而不是数据表，在任务描述中明确写“该附件仅作为 research_input， 不作为 dataset”。

仅修改扩展名不能把 XLSX 变成 CSV；必须实际导出或转换文件内容。

常见上传错误码

大数据集更适合由受控能力从明确位置导入，不要把超大二进制内容塞进普通 JSON/Base64 请求。

自主规划错误

Desktop 的“一句话开干”流程必须先由已连接的 Scientific Reasoner 生成严格结构化的意图草案， 再由 Runtime 对附件角色、能力、验收条件和权限进行确定性校验。

AUTONOMOUS_PLANNER_UNAVAILABLE 是一个外层类别。以下消息尾部最常见：

附件角色必须服从画像中的确定性 allowed_data_roles：数据集角色只接受 dataset；配置只接受普通 json；source_code 接受单个 .py 或含已识别源码成员的 directory_bundle；参考求解器必须是 静态判断为 solver-like 的 Python/目录/ZIP 或已确认的 solver_bundle；插件包必须含项目插件 manifest；无法更具体分类的文件只能安全地作为 research_input。

模型给出的 suggested_capability 只用于审计对照，不是授权。确定性编译器会根据已确认的研究意图 和可信附件重新推导必需步骤；即使建议在 Catalog 中精确且唯一命中，也不能新增 lease、选择生成能力 或触发安装。冲突、目录外、多余 executor 以及其他未被独立选择的建议会写入 warning，不会让任务 创建失败。只有确定性推导出的必需能力确实不存在时，才返回 AUTONOMOUS_CAPABILITY_MISSING。语义意图来自结构化 LLM 草案，不由另一套关键词规则重新解释；复用 Runtime 生成代码、发布新的持久插件、降级到有界符号基线分别需要显式的 UI/API 权限，默认全部 关闭，绝不从原文子串推断。

规划失败和需要澄清都发生在创建 Research Run 及准备项目插件之前：不会创建输入产物，项目插件状态不变， 暂存附件会保留。Desktop 会把需要澄清投影到 Planning Control Room Timeline，而不是错误横幅；这个页面是 会话级的预运行规划界面，不是一个半配置的 Research Run。Desktop 不会把失败的 LLM 规划悄悄替换成关键词规则。

无法创建研究合同

acceptance metric has no producer / CRITERION_METRIC_UNAVAILABLE

所选能力的 metric_outputs 中没有验收指标，或要求 trusted 指标却没有 authorized trusted evaluator 能够产生它。

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

重复或冲突的验收条件

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

CAPABILITY_CONSTRAINT_UNKNOWN 或能力约束无效

约束引用了未授权能力，或 when / require 不是合法映射。先把能力加入合同，从能力示例跑通， 再增加冻结参数；嵌套字段必须与项目插件的实际输入一致。

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 当普通路径字段传入。

求解器适配插件没有发布

识别为 solver_bundle 不等于获得发布权限。请先在新建页勾选 允许发布可复用插件。随后合同 要求产出 file-solver-adapter-v1 源码和 Local Executor 的通过验证记录；固定 publisher 只接受 solver_bundle、adapter_source、validation 三个不可变来源，并在 Control 进入受管理安装和 启用前，核对记录声明的通过状态、接口、精确来源 hash 与 Artifact 谱系。

默认 reviewer 状态 permissive_deferred 只表示允许继续发布，并明确记录没有独立恶意软件扫描、 签名验证、来源认证或二进制安全审查；它不是安全批准。validation 记录和摘要 attestation 只证明 所声明的状态、身份与谱系，也不是冒烟测试确实执行或二进制安全的独立证明。

Local Executor 问题

JOB_FAILED、EXPERIMENT_FAILED 等通常是 Timeline 事件或运行 failure type，不是 Control API 错误码。它们只说明执行失败，根因应从对应 Job 的 failure_type、退出码、stdout 和 stderr 读取。

• 命令找不到：依赖工具没有安装在应用进程的 PATH 中。用同一用户和环境在终端确认。
• 输出缺失：生成代码没有写入 JobSpec 声明的相对文件名。
• 退出码非零：查看 Jobs 中保存的 stdout、stderr 和结构化 failure type。
• MEMORY_ERROR / OOM / SIGKILL：Runtime 生成的普通本地作业当前申请 8,192 MiB；POSIX Local Executor 会施加地址空间上限。先缩小样本 mini-batch、对坐标或推理分块，并确认算法没有把完整场重复复制到内存；不要只把科学模型换掉来掩盖实现问题。
• 取消很慢：外部进程没有及时处理终止信号；等待状态完成，必要时在隔离环境中清理。
• 路径被拒绝：输入/输出必须留在工作区，不能使用绝对路径或 ..。

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

产物或谱系问题

hash mismatch / 产物损坏

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

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

Lineage 中没有预期关系

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

无法预览文件

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

结果交付与自动导出问题

科学运行达到 SUCCESS 后，生成插件发布和结果包导出是独立的交付阶段。交付失败不会把已经满足 验收条件的科学结果改成失败，但也不能把未准备完成的包报告为“已交付”。

存储与恢复问题

找不到旧运行

最常见原因是 --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 内容或整份敏感数据目录。

系统 VPN、代理与证书设置

桌面应用遵循操作系统的路由表、DNS 配置和 VPN 路由。Desktop Runtime 还会继承标准代理环境变量、 Windows/macOS 原生代理设置、GNOME 代理设置、Linux 桌面 Portal/PAC 解析、代理绕过规则以及系统证书库； 支持 HTTP、HTTPS 和 SOCKS 代理。显式设置的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、 NO_PROXY、SSL_CERT_FILE 和 SSL_CERT_DIR 具有最高优先级。

系统路由变化会立即生效；应用会在模型服务请求前刷新代理设置，因此切换系统网络后无需重新配置模型服务商。