贡献指南

DispatchAtlas 接受保持包边界、确定性证据，以及受发布限制的公开主张的更改。贡献是从仓库契约编写而来——而非从外部源树、生成的报告，或未发布的实验产物复制。根 CONTRIBUTING.md 是权威检查清单；本页将其映射到代码库。

🧭 选择你的路径

每个文件夹的边界规则位于根 AGENTS.md；每个包文件夹也携带其自己的 README.md。

意图	路径	何处
修复求解器缺陷	求解器注册表、算子，或元启发式，外加行为测试。	`packages/dispatchatlas-solve/`（见其 README）与 `tests/solve/`。
添加一个基准族	生成器、分类法条目、引用矩阵行、目录接线。	`packages/dispatchatlas-bench/`（见其 README）与 `tests/bench/`。
扩展领域契约	内部边界中的调度模型、验证、来源，或序列化。	`packages/dispatchatlas-core/`（见其 README）与 `tests/core/`。
改进活动执行	配置、预算、检查点、重试、环境捕获。	`packages/dispatchatlas-lab/`（见其 README）与 `tests/lab/`。
扩展分析导出	统计、披露过滤、证据包、门户数据集、CLI。	`packages/dispatchatlas-analytica/`（见其 README）与 `tests/analytica/`。
改进文档	Next.js 文档栈上的站点页面。	`site/content/docs/`（见 `site/README.md`）。
添加一个可运行示例	烟雾规模、可配置、对公开安全的示例。	`examples/`（其 README 列出示例桶与规则）。
改进质量工具	build、prose-register、code-first，与 license-header 关卡。	`tools/`（见其 README）与 `tests/tools/`。
报告缺陷或提问	结构化 issue 表单与支持渠道。	Issue 表单与 `SUPPORT.md`。

⚙️ 本地设置

安装 Python 3.12 或更新版本。
安装 uv。
运行 uv sync --all-extras --group dev。
若你想要本地提交钩子，运行 uv run pre-commit install。

✅ 本地检查

在开启 pull request 之前运行这些——托管 CI 跨 OS 与 Python 矩阵运行同一关卡集：

uv run ruff format --check .
uv run ruff check .
uv run mypy packages tests tools examples
uv run coverage run -m pytest
uv run coverage report
uv run python tools/check_prose_register.py
uv run python tools/check_code_first.py
uv run python tools/check_root_outputs.py
uv run python tools/check_solver_metaphors.py
uv run python tools/license_header.py check
uv run reuse lint
gitleaks detect --source . --redact --config .gitleaks.toml
npm --prefix site run build
npm --prefix site run check
npm --prefix site audit --audit-level=moderate
uv run pip-audit --path .\.venv\Lib\site-packages --progress-spinner off

针对包-构建烟雾检查：

uv run python tools/build_packages.py
uv venv .package-smoke
uv pip install --python .\.package-smoke\Scripts\python.exe (Get-ChildItem .\packages\*\dist\*.whl)
.\.package-smoke\Scripts\python.exe -c "import dispatchatlas, dispatchatlas.core, dispatchatlas.bench, dispatchatlas.solve, dispatchatlas.lab, dispatchatlas.analytica"

📦 边界

将 import 保持在文档化的依赖方向之内——见架构概览了解图示与按-包 import 表。简短形式：

dispatchatlas.core 是内部领域边界，不 import 任何 DispatchAtlas 包。
dispatchatlas.bench 与 dispatchatlas.solve 仅依赖 core。
dispatchatlas.lab 组合 core、benchmark，与 solver 包。
dispatchatlas.analytica 消费 core 契约与稳定清单。
site/ 消费已批准的导出；tools/ 与 CI 检视每个包，但并非产品运行时依赖。

边界由 tests/architecture/test_import_boundaries.py 强制执行，因此一个跨越的 import 会在评审前使测试套件失败。

📋 Pull request 期望

领域	期望
代码	将 import 保持在文档化的依赖方向之内。
数据	将活动输出视为生成的证据，而非源文件。
文档	使用首-发布 DispatchAtlas 语言，使烟雾证据保持带标签，并在面向-用户行为更改时更新页面。
测试	为新公开契约添加行为断言；描述预期行为，而非复现外部结构。
安全	不要提交凭据、私有证据，或部署密钥。
生成产物	将缓存、构建输出、覆盖率报告、实验输出，与检查点保持在 Git 之外，除非某仓库策略将其命名为受跟踪源。

🤝 社区与支持

社区渠道、issue 表单，与讨论类别汇总于社区页面。贡献生命周期 ——提议、对齐、实现、评审、合并——记录于 GOVERNANCE.md。