架构概览

DispatchAtlas 是一个由五个聚焦的发行包组成的工作区，它们共享 dispatchatlas Python 命名空间，外加一个根聚合包。该架构将领域契约保持在中心，并将基准生成、求解、活动执行、分析、文档与发布自动化向外移。每条依赖都指向内部，朝向 dispatchatlas.core——绝不在对等包之间横向，也绝不向外朝向工具。

🧭 依赖方向

                 dispatchatlas.lab
                /        |        \
               v         |         v
  dispatchatlas.bench    |    dispatchatlas.solve
               \         |         /
                v        v        v
                dispatchatlas.core
                         ^
                         |
               dispatchatlas.analytica
       (也将稳定的活动清单作为数据读取)

每个箭头表示“导入”。所有箭头都指向 dispatchatlas.core；没有箭头指向外部或横向。 dispatchatlas.analytica 刻意没有指向 dispatchatlas.lab 的箭头：它消费一个已完成活动留在磁盘上的 JSON 清单，而非活动运行时本身。

派生自各包清单（packages/*/pyproject.toml）与每个包 src/ 树中的导入语句；已于 2026-06-10 验证。

层	包	职责	可导入	不得导入
领域	`dispatchatlas.core`	调度契约、验证、出处、种子、序列化、协议。	仅标准库与经批准的轻量依赖。	任何其他 DispatchAtlas 包。
基准	`dispatchatlas.bench`	基准分类法、生成器、目录、物化、引用证据。	`dispatchatlas.core`。	求解器、活动、分析或站点运行时代码。
求解器	`dispatchatlas.solve`	求解器元数据、注册表、基线、元启发式、算子、可选适配器。	`dispatchatlas.core`。	基准生成器、活动执行器、分析导出或站点运行时代码。
活动	`dispatchatlas.lab`	可复现的活动配置、预算、检查点、重试、执行。	`dispatchatlas.core`、`dispatchatlas.bench`、`dispatchatlas.solve`。	分析包或站点运行时内部。
分析	`dispatchatlas.analytica`	统计、披露过滤、证据包、门户数据集、CLI。	`dispatchatlas.core`，外加作为 JSON 数据读取的稳定活动清单。	实时活动执行或站点运行时内部。
聚合	`dispatchatlas`	根发行；公开版本面，并通过其 `all` extra 固定这五个包。	运行时无；组合通过 extra 发生。	—

📦 包角色

dispatchatlas.core 是内部边界。它定义共享的调度词汇（ProblemSpec、 Schedule、目标、约束）、验证、出处与种子谱系、规范序列化，以及每个外层包都实现的协议（BenchmarkProvider、Solver、ExperimentRunner、ResultRepository、 DisclosurePolicy、AnalysisExporter）。其清单声明零依赖，因此领域处处可导入。
dispatchatlas.bench 将领域词汇转化为基准证据：生成器族、领域配置、冒烟与完整目录、特征化指标，以及一个记录每个族假设来源的引用矩阵。
dispatchatlas.solve 拥有一切产生调度的内容：求解器元数据与能力描述符、求解器注册表、构造式基线、置换元启发式、NDSO 族、调度算子，以及保留在 extra 之后的可选精确求解器适配器。
dispatchatlas.lab 将基准与求解器组合为带检查点、有预算、带环境戳记的活动，具有确定性运行标识符，并拥有将每个族与每个求解器相互核对的适用性矩阵。正因为这个矩阵，它才是唯一被允许同时看到 core、bench 与 solve 的包：将三者配对正是它存在的意义。
dispatchatlas.analytica 读取一个已完成的活动目录——checkpoint.json、 plan.json、environment.json 与结果行——并产出统计摘要、证据包、报告脚手架与门户数据集。基于清单的输入使分析仅凭记录的产物即可复现。
dispatchatlas（根）聚合这五个包以供一条命令安装，并承载公开版本面。

🔒 为何强制该方向

仅向内的方向是一个经测试的契约，而非一种约定：

可测试性。 core 在未安装任何求解器、活动或分析机制的情况下验证问题与调度，因此领域测试以仅标准库导入运行。bench 与 solve 针对 core 契约测试，互不牵连。
可复现性。 由于 dispatchatlas.analytica 消费记录的清单而非实时活动运行时，任何已完成活动都可从其产物逐字节地重新分析。
独立发布。 每个包分别构建并固定版本；一次求解器更改无法静默改变基准或分析行为。

导入边界测试位于 tests/architecture/：test_import_boundaries.py 用 ast 模块遍历每个包源文件，并在任何跨越上述禁止导入表的导入上失败，而 test_workspace_privacy.py 守护私有研究产物。该方向由根 AGENTS.md （§ Package Boundary Summary）规范地陈述，CONTRIBUTING.md 面向贡献者承载它；本页是构建于二者之上的深入说明，每个 pull request 都据此评审。

🌐 公开面

site/ 下的文档站点消费经批准的导出数据——经披露过滤的门户包与证据摘要。它不执行实时活动，也不绕过披露策略。

🛠️ 治理面

tools/ 与 CI 可检视所有包代码、构建产物与报告。它们从外部把关质量，且从不是产品包的运行时依赖。