DispatchAtlas故障排查
症状按其在从安装到导出路径上出现的位置分组，最常见的新人故障排在最前。每个条目都 说明原因与修复命令。
🚧 安装与环境
uv sync 失败
原因： PATH 上没有 Python 3.12 或更新版本，或缺少 uv。
修复： 确认 Python 版本，然后重新运行：
uv sync --all-extras --group dev若缺少 uv，请按 Astral 官方包说明安装它，打开一个新 shell，然后重新运行命令。
安装程序报告缺少前置条件
原因： 安装脚本要求 PATH 上有 git 和 uv。
修复： 安装所指明的前置条件，然后重新运行同一条安装命令。当检出应位于默认用户
数据目录之外时，请在重新运行前设置 DISPATCHATLAS_HOME。
更新报告了变更但不应用它们
原因： 更新检查默认为只读。
修复： 将 DISPATCHATLAS_REF 设为发布标签或 40 字符的完整提交 SHA，然后显式应用
分离检出更新：
$env:DISPATCHATLAS_REF = "<release-tag>"
.\scripts\installer\update.ps1 -Applyexport DISPATCHATLAS_REF="<release-tag>"
scripts/installer/update.sh --apply卸载拒绝某个目标
原因： 卸载脚本会拒绝空路径、文件系统根目录、主目录，以及不带 DispatchAtlas
工作区哨兵的目录。
修复： 将 DISPATCHATLAS_HOME 设为已安装检出的路径，然后重新运行卸载命令。
📦 导入
ModuleNotFoundError: No module named 'dispatchatlas'
原因： 工作区未同步，或脚本在项目环境之外的 Python 解释器下运行。
修复： 从仓库根目录出发，通过 uv 同步并运行脚本，使项目环境处于激活状态：
uv sync --all-extras --group dev
uv run python your-script.py创建求解器时出现 MissingOptionalDependencyError
原因： 可选的重量级后端（精确求解器、学习估计器）保留在 extras 之后，于运行时
探测，绝不在包导入期间被导入。该错误会说明缺失的 extra、其用途以及任何许可说明。
修复： 安装所指明的 extra（例如 exact、exact-commercial 或 learning），或
选择后端已存在的求解器。求解器的依赖声明列在求解器系统中。
🧪 活动配置与执行
验证活动时出现 CampaignConfigError
原因： 某个配置字段未通过验证——空 id、非正的种子或预算、重复的停止协议名称，或
空的基准、求解器或目标列表。该错误携带失败字段的路径。
修复： 更正所指明的字段。活动引擎页面记录了每一个配置
块，而 experiments/configs/smoke-pilot.json 是一个完整的可用示例：
uv run dispatchatlas-lab validate --config experiments/configs/smoke-pilot.json获取基准问题时出现 KeyError
原因： 该问题 id 不在提供方的目录中，或在期望 ProblemId 的位置传入了普通字符串。
修复： 包裹该 id（provider.get_problem(ProblemId("smoke-job-shop-0"))），并先用
provider.list_problem_ids() 列出可用的 id——参见教程。
完整活动拒绝执行
原因： 处于 full 阶段的活动会以 full-campaign execution requires statistical design approval 失败关闭，直到该批准被记录在配置上。
修复： 对本地检查请在 smoke 或 pilot 阶段运行，或在启用完整执行前按
发布就绪记录统计设计批准。
恢复重新规划而非跳过已完成的运行
原因： 位于 .checkpoints/{campaign_id}.json 的检查点由配置哈希守护；任何配置
更改都会使其失效，而非静默重用。
修复： 保持配置不变以恢复，或在更改后的配置下接受一份新计划。工作区契约在
可复现活动中描述。
📤 导出、报告与站点
分析导出报告缺少检查点
原因： dispatchatlas export 命令期望一个已完成的活动目录，其中包含
checkpoint.json、plan.json、environment.json 以及结果记录。
修复： 将 --campaign-dir 指向活动结果目录而非其父目录，或重新运行活动：
uv run dispatchatlas export `
--campaign-dir .\experiments\results\smoke-pilot `
--target-dir .\exports\smoke-pilot `
--authorized-output-root .\exports `
--tier core若 --target-dir 在当前工作目录之外，请传入一个包含目标位置的显式
--authorized-output-root。
门户数据验证失败
原因： 静态站点资产与门户结果导出不同步。
修复： 重新生成静态资产。该命令默认读取位于 exports/portal-results.json 的、
已提交且经披露过滤的结果导出，因此无参数即可运行：
uv run python tools/build_site_assets.py传入 --result-source 以发布另一个经披露过滤的 portal-results.json 导出：
uv run python tools/build_site_assets.py --result-source .\path\to\portal-results.json若命令报告 dispatchatlas site-assets: error，请检查 --result-source（或默认的
exports/portal-results.json）是否指向由分析导出路径生成的、现存的
portal-results.json 文件。
门户编修关卡失败
原因： 一个不属于公开表面的令牌到达了门户数据，因此构建失败关闭，以使已发布的
门面读起来像一个通用的调度优化工具包。
修复： 该错误会列出每个违规产物、字段路径与令牌。在发出该产物的构建器中
（位于 tools/portal_contract.py 或其源证据之下）编修违规字段，使只有公开安全的
派生证据到达门户数据，然后重新生成：
uv run python tools/build_site_assets.py此故障不同于缺少门户导出：传入不同的 --result-source 并不能清除它——违规令牌必须
在其源头被移除。
站点构建找不到某个页面
修复： 运行站点契约测试与文档构建：
uv run pytest tests/site
npm --prefix site run build
npm --prefix site run check某个求解器在推荐中缺失
原因： 选择基于元数据进行过滤。 修复： 检查该求解器的元数据中的目标支持、所需能力标签、可选依赖状态，以及在 求解器系统中的证据层可见性。