本项目重建了一个面向 DeepSeek-V3 Decode 的算子级、stage/event 级 analytical simulator，用于比较 H800/H20、EP 配置、local fabric domain 拓扑和三个封闭 Execution Plans 下的吞吐、显存与瓶颈。
当前版本作为 Python library 使用，提供三个行为入口：
simulate(config, batch_size_per_rank) -> SimulationResult：对一个不可变配置和一个 Local Batch 执行完整确定性 Simulation Run，返回实际execution_plan/batch_partition、吞吐（Cluster / Per-GPU / User-experienced）、显存分解与 memory-safe 上限、通信 Bytes 汇总、瓶颈类别与方向、Timeline、Critical Path 与contains_extrapolation；find_best_batch(config, minimum_ux_tokens_per_s=None) -> BatchSearchResult：按配置的 Batch Partition 枚举[1, memory-safe 上限]（SINGLE）或[2, memory-safe 上限]（DUAL）的全部整数 Local Batch，对每个候选复用同一个 Reference Catalog 执行完整 Simulation，按更高 Per-GPU throughput、更高 UX TPS、更小 Local Batch 的精确顺序选出获胜者；不可达 QoS 抛出携带诊断的NoFeasibleBatch。find_best_resource_order(config, batch_size_per_rank, *, max_schedule_evaluations) -> ResourceOrderSearchResult：固定 ASAP 源 Plan、Composition、Batch Partition、Local Batch 和全部 Event durations，以确定性的 Critical-Path Tabu Search 在明确的 Schedule evaluation 预算内优化 Compute/Communication 完整队列，并返回 best found、规范 Schedule、下界和终止诊断。
支持范围与固定参数：DeepSeek-V3 Decode（61 层：3 Dense + 58 MoE）、H800/H20、单一 EP Group（EP 8–256 且为 8 的倍数）、q_seq_len ∈ {1, 2} 的 Simplified MTP Verification，以及 BASELINE_ASAP、SPLIT_ATTENTION_ASAP、仅 DUAL 的 DEEPSEEK_V3_INTERLEAVED。详见 REQUIREMENTS.md。
基本使用示例：
./.venv/bin/python examples/basic_decode.pytools/e2e/ 中每个 Python 文件独立定义一个性能场景。默认直接计算该配置的最大
memory-safe Local Batch，运行一次完整 Simulation Run，并覆盖对应的
reports/e2e/<plan>/<scenario>.md，例如：
./.venv/bin/python tools/e2e/baseline_asap/h800_ep72_9x8_q2_dual.pytools/e2e/ 与 reports/e2e/ 分为 baseline_asap/（8）、split_attention_asap/（8）和 deepseek_v3_interleaved/（7）三组受控场景。报告显式记录 Execution Plan 与 Batch Partition，并展示 token/throughput、显存、端到端时延、计算与通信 overlap、Stage/Operator/
fabric tier 的单次与累计时延，以及独立的 Critical Path 瓶颈摘要。性能脚本和报告与
Regression Golden 完全独立；新增场景时复制一个脚本并在文件内直接修改完整配置即可。
如需复现脚本内固定 Batch，将 USE_MAX_MEMORY_SAFE_BATCH 设为 False；固定值由
DEFAULT_BATCH_SIZE_PER_RANK 定义。
三个 h800_ep72_9x8_q1_dual 脚本额外生成可离线打开的自包含 Timeline HTML：
reports/timeline/baseline_asap/、reports/timeline/split_attention_asap/ 与
reports/timeline/deepseek_v3_interleaved/。页面以真实 Timeline 时间比例展示 Compute 与
Communication 两条 Resource track：MB0 Event 完整填充黄色、MB1 Event 完整填充绿色，Stage
使用文字与 1px 黑色边界区分。浅色页面支持最高 80× 缩放、平移、隐藏式筛选与极简 Event
details；其余 20 个脚本显式不生成 HTML，全部 Markdown 内容保持不变。
Resource Order Search 的受控代表场景使用 Split-Attention ASAP 的同一个 H800 EP72 9x8、q=1、 DUAL 配置和 memory-safe 最大 Local Batch，显式执行 4,000 次 Schedule evaluation：
./.venv/bin/python tools/search/resource_order/h800_ep72_9x8_q1_dual.py它固定生成 reports/search/resource_order/h800_ep72_9x8_q1_dual.md 与同目录 Timeline HTML；
两者是人工审阅分析产物，不是 Regression Golden。
M1 可以把固定 H800 训练场景转换为受限的策略问题，并把 dynamic ASAP seed 通过正式 Scheduler 评分一次：
./.venv/bin/python -m tools.agent_search.resource_order.m1_kernel命令在 Git 忽略的 .agent_runs/resource_order/m1-kernel/ 中写出 manifest.json、
problem.json 和 result.json。这三个文件分别回答“运行了什么”“Agent 可以看见什么”和“正式
Scheduler 判了多少分”。M1 不调用 LLM，也不执行自动搜索；它只是后续 Agent loop 的可信实验
内核。
M2 提供结构化 DSL 与手动 episode；M3 提供确定性 Packet、append-only ledger、lineage、人工接受的 Working Knowledge 和中断恢复。最小 campaign 从已完成的 M1 根证据开始：
./.venv/bin/python -m tools.agent_search.resource_order.campaign_memory \
--campaign-dir .agent_runs/resource_order/tutorial-campaign init \
--campaign-id tutorial-campaign \
--root-artifact-dir .agent_runs/resource_order/m1-kernel
./.venv/bin/python -m tools.agent_search.resource_order.campaign_memory \
--campaign-dir .agent_runs/resource_order/tutorial-campaign prepare-episode \
--experiment-id episode-001 --parent-experiment-id m1-kernel这只建立可供当前 Codex App 手动研究的文件闭环，不会自动调用模型或联网。完整命令与学习路径见 Resource Order LLM-Agent 寻优项目教程， 整体设计见已接受的 Resource Order Agent Harness Design。
M4 已接通独立角色、指定单轮和连续 campaign 控制，以及 clean tracked workspace 上的基线准备。
已接通显式单角色 runner：Packet/Skill/模板编译、输出校验、两次尝试上限、超时回收、修改检查和
attempt receipt 接续。每个 attempt 从本地权威角色 Schema 生成 Codex 兼容传输 Schema，模型返回后
仍以权威 Schema 二次校验。角色只读取 AgentCall 中精确的 inputs 与自有 outputs；静态 shell 事件在输出验收、重试和
评分前审计，报告直接进入 receipt。调用入口自动处理代理，角色显式使用项目 .venv/bin/python，不改变父进程或其他终端。
单角色与连续运行均需要人工审阅的 CLI policy evidence，不能用替身测试或任意填写 approval 文件替代。
single_episode 接收已准备的当前 Schema 自动 episode，串接 Researcher、正式评分、Reflector、完成和 ledger，
打印最小回执后停止；可只读查看或在两次失败后显式确认结束。小图工程闭环由真实 Scheduler 与
角色替身验证。真实入口仍拒绝缺失基线、未通过的程序检查或 policy 证据。
campaign_control 提供 status/run/pause/resume，按 ledger 派生的停止条件串行执行；使用方式见
07：连续 campaign 控制。旧教学实验不自动迁移。
操作与学习路径见 06：独立角色与单轮实验。
代理行为和限制见 项目级代理启动准备。
已实现能力与实验合同见 SEARCH.md。
在仓库根目录建立工作树本地环境并安装（见 CONTRIBUTING.md 第 9 节）：
python3 -m venv .venv
./.venv/bin/pip install -e ".[dev]"验证入口（均在仓库根目录执行）：
| 用途 | 入口 |
|---|---|
| format | ./.venv/bin/ruff format . |
| lint | ./.venv/bin/ruff check . |
| type check | ./.venv/bin/mypy |
| Core Validation | ./.venv/bin/pytest tests/core tests/regression |
| Calibration Validation | ./.venv/bin/pytest tests/calibration |
| 完整验证 | ./.venv/bin/pytest |
data/ 保存由 tools/build_canonical_data.py 从只读参考快照（references/，固定上游 commit）最小清理得到的八份 canonical CSV，是唯一在盘 Operator performance reference；来源、逐文件过滤与已知限制见 data/SOURCES.md。ReferenceCatalog 一次加载并索引全部 canonical CSV，提供 Dense、Masked Grouped、Batched GEMM 与 FlashMLA 四类 latency 查询（Exact Hit、区间内插值、边界外推与 is_extrapolated 标记，禁止跨 hardware / Operator Family / dtype fallback）。
- 需求文档：系统必须支持的行为、输入输出和验收口径。
- 领域语言：需求、设计、代码和测试统一使用的规范术语。
- 建模规范：数学模型、单位、假设、计算顺序和边界。
- 数据合同：canonical CSV 的 schema、清理、查询分组和失败边界。
- 架构文档：目标模块、关键 Interface、依赖方向、数据所有权和执行流。
- 搜索文档：当前搜索能力，以及搜索变量、objective、预算和结果语义的权威入口。
- 验证规范：最小验证集合、校准方法、端到端场景和门禁规则。
- 开发与文档治理：纵向增量、Design/ADR、实现、验证、文档生命周期与版本发布规则。
- 版本说明：正式版本的能力摘要、兼容性和验证状态。
- 参考资料索引：两个只读参考快照的来源和使用边界。
- Agent 约定：后续修改的工程规则。
上述权威文档始终对应当前代码。历史版本通过正式 Git tag 查看；当前分支不复制旧版本文档或保留已完成 Roadmap。