Add BMM_Theory: docs/03_测评报告/ 软件测评报告 v1.0

BMM/BMM_Theory/docs/03_测评报告/BMM_Theory软件测评报告_v1.0.md

@@ -0,0 +1,266 @@
+# BMM/BMM_Theory 理论最优实现分析软件 测评报告
+
+- 测评对象：`git.magicnetworld.com/admin/matmul-analysis` 仓库中的 **BMM/BMM_Theory**（Python 包 `bmm_theory`，batch_mat_mul_v3 在 Ascend950PR 上的理论最优实现分析软件）
+- 测评日期：2026-09-06（本地环境）
+- 测评基准：仓库 HEAD `5ab04bab11c80e544c6969fbfdbd9869871f7aa3`（2026-09-03 09:25:58 UTC, main 分支）
+- 测评方式：静态代码审查 + 文档对照审计 + 全量运行复现 + 随机压力/自洽性测试 + 公式手工核验（无法在真实 950PR 硬件上运行验证，见 §7 局限说明）
+
+---
+
+## 0. 测评结论摘要（TL;DR）
+
+BMM_Theory 是一个**立意清晰、理论文档资产扎实、代码与理论公式可追溯性好**的"BMM 分支决策 + 时延评估"分析工具雏形（`__version__ = 0.1.0`，纯标准库、零第三方依赖，Python 包共 17 个源文件 / 2125 行 + 148 行单测）：
+
+| 维度 | 结论 | 评分 |
+|---|---|---|
+| 设计架构 | 分层清晰：CLI → 路由/评估 → 分支插件 → 时延引擎 → 硬件参数表 → CSV IO；ImplPlan 作为推荐/评估的"通用货币" | 9/10 |
+| 理论-代码映射 | 6 个分支的进入条件/方案生成/时延模型与自建理论文档（v0.98、v1.1、v1.5 等）逐条对应，公式常数（θ_c≈12、R16≈607.5、93.5/304 分界）抽查一致 | 8/10 |
+| 功能完成度 | recommend / evaluate 双模式可运行，10 个 demo case 全部跑通，输出与仓库固化示例**逐字段一致**（确定性良好）；17 个单测全过 | 8/10 |
+| 内部一致性（正确性） | **发现 P0 级崩溃 bug 与 ~6%~18% 的"推荐方案自检不可行"矛盾**（约束在生成与校验两侧不共享） | 5/10 |
+| 鲁棒性/错误处理 | 崩溃路径、输入面缺口（out_nd 不可达、dtype 不一致无警告）、裸 traceback | 4/10 |
+| 测试充分性 | 17 条测试只覆盖 router + 2 个分支文件，未覆盖 CLI/io_csv/约束器/StreamK/ASW/特殊分支故障面 | 5/10 |
+| 工程化/交付 | 无打包、无 CI、无版本门禁、无 .gitignore/LICENSE；大量历史重复提交与文档-代码漂移 | 5/10 |
+
+**总体评价：约 6.2/10。作为"概念验证（POC）"质量良好、理论分析价值高；作为"可交付的可信工具"仍属早期——推荐先修复 P0 崩溃与约束自洽问题，再补测试与标定验证后使用其结果做决策。**
+
+关键发现速览（详见 §5）：
+1. **【P0 崩溃】** 任意 `K=1 且 batch < 128` 的 case（如 `B=64, M=8192, N=32, K=1`）走 `recommend` 直接抛 `AttributeError: 'NoneType' object has no attribute 'used_core_num'` 崩溃——router 无条件把 `k≤1` 路由到特殊分支，但该分支 K=1 需 `B≥128` 才 capable，返回空方案后未做兜底。
+2. **【P1 自相矛盾】** 推荐模式**从不做可行性校验**，而其自带 evaluate 约束器与分支生成逻辑存在冲突：8 000 个随机 case 中 480 个（6.0%）"推荐方案"被软件自己判为不可行（违规集中在 dValue<128B 下限 344 条、L0A/L0B 超容量 210 条）；换用典型 LLM 形状 6 000 例，比例高达 **18.0%**。
+3. **【P2 覆盖缺口】** case 输入列 `out_nd`（决定 StreamK 可用性的关键工程约束）在 `io_csv.load_cases` 中未解析，CLI 层无法表达非 ND 输出场景；`trans_a/trans_b/has_bias` 被解析但全部未参与建模；`models.py` 注释承诺的 "A/B dtype 不一致告警" 实际没有实现。
+4. **【P2 口径疑点】** StreamK 的归约时延既进稳态 `max()` 又作 `drain` 追加（归约主导时会重复计账）；fixpipe 写出口径（C dtype 2B vs 部分和 4B）与文档/plan 字段不一致。
+5. **【P2 文档漂移】** README 目录树与 `docs/01_软件架构.md` 仍把分支层描述为 "MergeBatch+IterBatch 本期、asw_basic/stream_k 待迭代"，与实际 6 分支现状不符。
+
+---
+
+## 1. 仓库概况
+
+`git clone` 后实测（main 分支 HEAD 5ab04ba）：
+
+| 指标 | 数值 |
+|---|---|
+| 提交数 | 397（2026-08-20 ～ 2026-09-03，全部作者 "admin"） |
+| 跟踪文件 | 127 个 / 4.48 MB |
+| 顶层目录 | `BMM/`、`Matmul/`、`昇腾950PR/` |
+| 软件本体 | `BMM/BMM_Theory/`：32 个跟踪文件（18 `.py` + 10 `.md` + 4 `.csv`，162.6 KB） |
+| 理论文档 | `BMM/BMM算子优化分析_Release/`（v0.4→v0.98 各 .md+.html 双版本、ASW_Basic 分支分析 v1.0→v1.91 系列、MergeBatch_vs_IterBatch v1.0/1.1、尾轮处理策略 v1.0→v1.5、L0C 流水机制等，约 60+ 个文件） |
+| 源码对照 | `Matmul/3_源码对比/3.1_mat_mul_v3源码解析.md(.html)`、`BMM/` 下 BatchMatMulV3 分析等 |
+| 其他 | 无根 README、无 LICENSE、无 .gitignore、无 CI 配置、无打包文件（pyproject/setup） |
+
+仓库演进脉络：8/20–8/31 全部用于**理论分析文档**的多轮自审迭代（提交信息可见 v0.4→v0.98、分支文档 v1.0→v1.91 的逐版修正），9/3 一次性新增 **BMM_Theory 软件包**（把理论固化为可执行代码），同日把 03–07 分支理论文档、示例与测试入库。即：软件是"理论文档体系 + 一次性代码化"的产物，天然带有"单日成仓、文档与代码由不同轮次生成"的痕迹（§5.6）。
+
+---
+
+## 2. 软件定位与设计（阅读源码后的理解）
+
+按 README 与 `docs/01_软件架构.md`，软件回答两个问题：
+1. 任意 BMM case 的**理论最优实现方案**是什么（走哪个分支、核间怎么切、核内 tile/流水怎么配）；
+2. 该方案在 950PR 上的**端到端各级时延**与瓶颈（MTE2 搬入/Cube 计算/Fixpipe 搬出/StreamK 归约）。
+
+设计要点（与源码一致）：
+
+- **两种模式**：`python -m bmm_theory recommend cases.csv`（方案推荐，输出 result + plans）、`python -m bmm_theory evaluate cases.csv plans.csv`（用户方案评估：约束校验 + 时延 + 瓶颈 + 建议）；`-v` 人类可读。
+- **ImplPlan 标准结构体**（models.py，34 字段分四组：分支与核间切分 / 核内 tiling / 存储 Cache 策略 / 尾轮与流水策略）作为推荐输出与评估输入的统一格式，字段名与理论文档符号一一对应。
+- **分支插件化**（branches/base.py）：统一 `check_conditions / make_plan / evaluate / analyze` 接口；6 个分支文件：MergeBatch、IterBatch、转Matmul、特殊分支(K=0/1)、StreamK、ASW_Basic(含降核模式)。
+- **决策树路由**（router.py）：① 单边 batch=1 → 转Matmul；② K≤1 → 特殊分支；③ B≥C 且 BatchA==BatchB → MergeBatch/IterBatch（分界公式预判 + 端到端时延双保险仲裁）；④ P≤C/2 且切 K 条件满足 → StreamK；⑤ 兜底 ASW_Basic（P<C 时降核）。
+- **时延引擎**（timing.py）：`T = max(MMAD, MTE2_GM, MTE2_L2, FIXPIPE[, REDUCE]) + T_drain`；搬入分 GM→L1 直读（1.6TB/s）与 L2→L1 命中（5.2TB/s）两段；带宽按"每核独立 DMA、单核份额=聚合/C"建模。
+- **硬件参数隔离**（hardware/ascend950pr.py）：核数 32 AIC/64 AIV、BF16 486 TFLOPS、L1 512KB、L0A/L0B 64KB、L0C 256KB、L2 128MB、T_cmd=50ns（标注为估计值）。
+
+亮点评价：
+- "决策树成本排序：切B=0 < 切M/N(低) ≪ 切K(高)"的**第一性问题划分**非常清晰，代码实现忠实；
+- MergeBatch vs IterBatch 采用"K截断 + b_core 阈值"解析分界 **与** 端到端模型双保险，且裁决说明（arbitration）字符串把两边数值与公式都打印出来，**可解释性做得好**；
+- 时延结果附 `bound_type`（计算/访存/写出/归约 Bound）与针对性建议，作为"理论对照工具"比裸数值更有用。
+
+---
+
+## 3. 测评环境与方法
+
+- 环境：Windows 11 本机；Python 3.14.7（该仓库声明 "Python ≥ 3.8, 仅标准库"）；git 2.55；无任何第三方 pip 包安装。
+- 方法：
+  1. 逐文件阅读 18 个 `.py`（2125 行）+ 10 篇架构/分支文档 + 测试与示例；
+  2. 全量运行：单测、recommend/evaluate 双模式 demo、与仓库固化的 `examples/result_*.csv` 逐字段比对（可复现性）；
+  3. 手工公式核验（附录 B）；
+  4. 随机压力测试：宽范围 8 000 例 + 典型 LLM 形状 6 000 例，检测崩溃/NaN/负值/推荐-自检矛盾；
+  5. 针对性构造最小复现（P0 崩溃、三类约束矛盾样例）；
+  6. 文档-代码一致性审计。
+
+---
+
+## 4. 运行结果与功能核验
+
+### 4.1 单元测试：17/17 通过
+`python -m unittest discover -s tests -v`：Ran 17 tests in 0.011s, OK（exit 0）。覆盖 router 决策、Merge/Iter 仲裁、时延模型自洽、dtype 换算等——但**覆盖面窄**（仅 import 了 MergeBatch/IterBatch 两个分支类，其余分支只经 router 间接覆盖；CLI、io_csv、约束校验器、StreamK/ASW/转Matmul/特殊分支的 evaluate 细节均无直接单测，见 §6）。
+
+### 4.2 recommend / evaluate：10 个 demo 全部跑通
+`recommend` 10 例 → 各分支各命中一例，`evaluate` 用输出 plans 回灌 10/10 feasible。分支归属：转Matmul、特殊分支(K=0/1)、MergeBatch、IterBatch(形态 b/d)、StreamK(grid_K=32)、ASW_Basic、ASW_Basic_降核。
+
+### 4.3 可复现性：与仓库固化示例逐字段一致
+将新生成的 `out_recommend.csv` 与仓库 `examples/result_recommend.csv`（10 行 × 全部列，含 advice/arbitration 文本）比对：**0 处差异**。纯函数式、确定性输出，这对"可审计工具"很重要。
+
+### 4.4 demo 输出快照（时延单位 us）
+| case | B | M×N×K | 分支 | T_total | 瓶颈 |
+|---|---|---|---|---|---|
+| to_matmul_demo | 1 | 2048³ | 转Matmul | 35.35 | MMAD |
+| special_k0_demo | 128 | 256²×0 | 特殊分支 | 10.49 | FIXPIPE |
+| special_k1_demo | 128 | 256²×1 | 特殊分支 | 10.49 | FIXPIPE |
+| merge_demo_k_trunc | 2048 | 32²×256 | MergeBatch(b0=4) | 43.04 | MTE2_GM |
+| merge_iter_arbitrate | 128 | 64²×512 | IterBatch | 11.13 | MTE2_GM |
+| iter_demo_form_b | 128 | 64²×256 | IterBatch(b) | 5.74 | MTE2_GM |
+| iter_demo_form_d | 64 | 64²×8192 | IterBatch(d) | 85.40 | MTE2_GM |
+| streamk_demo | 4 | 128²×10240 | StreamK(×32) | 9.96 | MTE2_GM+归约3.41 |
+| asw_demo_full | 2 | 8192²×1024 | ASW_Basic | 565.59 | MMAD |
+| asw_demo_reduce_core | 16 | 256²×128 | ASW_Basic_降核(16核) | 2.62 | MTE2_GM |
+
+抽检数值（手工核算见附录 B）：IterBatch 例 GM=5.24us、MMAD=0.55us、FIX=0.66us、cmd=0.20us、drain=0.30us 全部与公式一致；MergeBatch 例 41.94+0.80+0.30 亦一致。**时延引擎内部自洽、易于审计**。
+
+---
+
+## 5. 发现的问题（按严重度分级，附证据定位）
+
+### 5.1 【P0-崩溃】K=1 且 batch<128 → recommend 必崩
+
+**复现**（最小 case）：
+```
+case_id,batch_a,batch_b,m,n,k,dtype_a,dtype_b,dtype_c
+bug1,64,64,8192,32,1,int8,int8,int8
+```
+```
+$ python -m bmm_theory recommend bug.csv -o out.csv -v
+  AttributeError: 'NoneType' object has no attribute 'used_core_num'
+    （-v 在 __main__.py:85 _print_case；不带 -v 在 models.py:271 EvalResult.to_row；带 --plans 在 save_plans 同样崩溃）
+```
+
+**根因链**：
+1. `router.py:49-52` 把 `k ≤ 1` **无条件**路由到特殊分支（决策树文档 00 总纲/04 特殊分支也是这么写的）；
+2. 但 `special.py:26-32` 对 K=1 附加 `batch_c ≥ 2×AIV核数(128)` 才 capable（文档 §3 触发条件）；
+3. `base.py:56-63` capable=False 时 `plan=None`；
+4. 下游 `__main__` / `EvalResult.to_row` 无空值防护 → AttributeError。
+
+即 **K=1 且 B<128 是"决策树文档声称覆盖、代码实际无解、路由不设兜底"的空洞**。K=1/B<128 在真实场景并非不可能（如小 batch 头数 × K 退化为 1 的元素级 case），且触发无需任何特殊 dtype。建议：capable=False 时回退其它通路（如 AIV 单缓冲 / Cube 兜底）或显式报"该区域暂无理论方案"而**不崩溃**。
+
+### 5.2 【P1-自相矛盾】推荐方案与自带约束校验冲突（随机 6%–18%）
+
+**现象**：把 recommend 输出的 plans 回灌 evaluate，本应全部 feasible，实测大量被判违反约束——**生成阶段完全没跑约束校验**（`router.route` → `branch.analyze` 只做条件判定与时延评估；`PlanEvaluator._check_constraints` 只在 evaluate 模式生效，两套约束规则还互相矛盾）。
+
+**实测统计**（均为合法输入、已剔除 P0 场景）：
+
+| 实验 | 样本 | 自检不可行 | 主要分布 |
+|---|---|---|---|
+| A：宽范围随机（B/M/N/K/dtype 全谱） | 8 000 | 480（6.0%） | IterBatch 206、ASW_降核 237、MergeBatch 37；违规条目：dValue 344、L0A 111、L0B 99、L1 20、L0C 9 |
+| B：典型 LLM 形状（B∈1..512、M/N∈16..8192、K∈8..16384） | 6 000 | 1 079（**18.0%**） | IterBatch 656、ASW_降核 422、MergeBatch 1（IterBatch 的 dValue 违规占绝对多数） |
+
+另一次 5 000 例实验为 6.4%。**违规分支的典型最小样例**：
+
+| 分支 | 样例 | 违规 |
+|---|---|---|
+| IterBatch | B=256, M=128, N=1024, K=8, bf16 | dValue = K×2B = 16B < 128B 下限 |
+| IterBatch | B=64, M=64, N=512, K=2, fp8 | dValue = 2B |
+| MergeBatch | B=1024, M=2, N=512, K=32, fp8 | dValue = 32B |
+| ASW_Basic_降核 | B=2, M=64, N=16, K=32, fp16 | dValue = 64B |
+| ASW_Basic_降核 | B=51, M=255, N=42, K=682, fp32 | L0A tile 超容量 |
+| MergeBatch | B=128, M=512, N=16, K=2048, fp32 | L0A tile 超容量 |
+
+**三条具体矛盾**：
+1. **IterBatch 形态 a/b 豁免 vs 约束器一刀切**：`iter_batch.py:95-104` 对形态 a/b 的搬移效率条件标注"恒满足"（k_L1=K 整体驻留不切分），但 `evaluator.py:83-84` 对所有 `k_l1>0` 的方案无条件要求 `k_L1×dtype ≥ 128B`。K 小的整驻留 case（K=8/16/32）必然冲突——小矩阵单次 DMA 是否必须满足 dValue 下限属于**理论口径问题**，但"生成说可行、校验说不可行"的产品级矛盾不容回避（也说明小 K 大 batch case 的时延估算（按满带宽）偏乐观，未计 T_cmd/min_TileSize 崩坏效应）。
+2. **ASW 降核 base_k 与 dtype 容量脱钩**：`asw_basic.py:148` 硬编码 `base_k = min(K, 64)` 且 `base_m=single_m=min(M,256)`，fp32(dt=4B) 时 `base_m×64×4B×2 > 64KB` 必然 L0A/L0B 溢出（代码却照常生成 16 核方案并给出乐观时延）。正常 ASW 模式有 `base_k` 由 L0A/L0B 容量反推（:67-70），降核模式漏了这一步。
+3. **MergeBatch fp8/int8 dValue**：`merge_batch.py:104` 用 `dvalue_recommend(512B)//dt` 截断后 `align_down(…,16)` 再 `max(16)`，fp8 下 k_L1 可低至 16~32 元素 → 16~32B < 128B，与条件 4/评估口径冲突。
+
+**共性根因**：约束知识分散在三处（各分支 `check_conditions`、`make_plan` 内部硬编码、evaluate 的 `_check_constraints`），三套规则由不同轮次独立写出、互相不一致，且生成路径从不调用校验器。修复方向：抽单一 `constraints.py` 供生成与校验共用，生成后强制校验并在不可行时降级/报错。
+
+### 5.3 【P2-输入面缺口】
+- `out_nd`（StreamK 工程约束之一：输出需 ND 格式）在 `io_csv.load_cases`（:44-68）**没有解析**，CSV 输入恒为默认 True——CLI 无法构造 `out_nd=False` 的评估；`deterministic_level` 解析正常且 `≥2 禁用 StreamK` 实测有效（B=4,M=N=128,K=10240,det=2 → 正确落入 ASW_降核）。
+- `trans_a/trans_b`（影响 ND/NZ 数据排布与 dValue 语义）与 `has_bias`（bias 读取/写出增量）被 CSV 解析但**全链路未参与任何建模**——对"理论最优"完备性有影响（模型里 bias 免费、转置免费）。
+- `models.py:93-94` 注释承诺"A/B dtype 不一致时取较大者**并在校验中报 warning**"，全仓 grep 无任何 warning 实现（仅 evaluate 缺 case 的 stderr 提示）。dtype_a≠dtype_b 时静默按大者建模。
+- 无任何输入合法性校验：负维度/零 M/N/非法 dtype 等会产出无意义结果或裸 traceback；文件不存在直接抛完整堆栈。
+
+### 5.4 【P2-StreamK 计账口径疑点】（需作者澄清，非定论）
+- `stream_k.py:161` `drain = t_reduce`，而 `timing.py:104-112` 又把 REDUCE 放进稳态 `max(stages)`——归约同时被"取最大"与"串行追加"，**REDUCE 为主导时会近似双倍计账**（文档语义是"归约串行追加不可掩盖"，若如此则 REDUCE 不应进 max()）。
+- `stream_k.py:152-153` fixpipe 按 **C 矩阵 dtype（2B/1B）** 计 `t_fix`，而其 plan(`out_dtype_bytes=4`，:116) 与归约子模型 `timing.py:77-93`（部分和写读按 4B + 最终写回）口径不一致，`t_fix` 存在低估/与 `t_reduce` 内含写回重复计账的可能。
+- StreamK 评估基于"单 tile=65536 元素"近似（:140-142），把整 case 的并行/多 tile 处理折算为 `tile/grid_K`，与 plan 中实际 m_cnt/n_cnt/b 切分未严格联动（plan 里算了 M/N 切分与 workspace，evaluate 却只用单 tile 缩放）——大 B 场景（每核多 tile）的流水评估粗糙。
+
+### 5.5 【P2-文档-代码漂移】
+- `README.md:71` 分支目录注释仍写"(本期: MergeBatch + IterBatch)"；目录树（:76-84）只列了 00/01/02 三篇分支文档——实际已 6 分支 + 03~07 文档。
+- `docs/01_软件架构.md` 分层图与 §4"扩展指南"仍写"asw_basic.py/stream_k.py **待迭代**、新建 branches/asw_basic.py 接入…"，与现状（已实现且为兜底主干）直接矛盾；该文档更新时间早于 9/3 代码落地后未同步。
+- README 声称 "Python ≥ 3.8"，代码大量使用 `X | None`（PEP 604，3.10+）与内置泛型 `list[...]`（3.9+）语法——虽有 `from __future__ import annotations` 兜底（标注字符串化）大概率可在 3.8 运行，但**未经任何 3.8/3.9/3.10/3.11/3.12/3.13 实测**（本机仅 3.14 验证通过），声明与验证脱节。
+- 特殊分支文档 `04_特殊分支.md:27` 自称"router.py 前置归约中 k≤1 直接路由到特殊分支"——恰好是该空洞区域（无 B≥128 时方案的说明），文档把 bug 区域描述成了正常行为。
+
+### 5.6 【P3-工程/过程痕迹】
+- 无打包（无 pyproject/setup）、无 CI、无 .gitignore（运行即产生 `__pycache__` 噪音）、无根 README/LICENSE；`__version__=0.1.0` 与 397 个提交的演进不成比例——9/3 一天之内整包落地。
+- 提交信息大量重复（同一条目重复 2 次以上、"目录整理"条目 ×20+），历史信息熵低；`.md/.html` 双版本靠人工同步（提交里可见多次 "同步HTML"），易产生漂移。
+- 少量无用导入（如 `models.Optional`、`merge_batch.MoveInPlan/BranchResult`、`iter_batch.BranchResult` 等）与注释式常量，无 lint 门禁。
+- 时延模型的 `t_cmd=50ns` 等经验参数在文档中诚实标注为"估计值、需实测标定"（架构文档 §4.4），是加分项，但也意味着**当前所有输出数值都未经真实硬件校准**。
+
+---
+
+## 6. 测试充分性评估
+
+`tests/test_branches.py`（148 行，17 例）质量尚可（边界 case 都来自理论文档、断言具体），但：
+- 只直接导入 MergeBatch/IterBatch 两个分支；StreamK/ASW/转Matmul/特殊分支全部只经 router 冒烟；
+- 无 io_csv、CLI（__main__）、evaluator 约束器、models 往返、HardwareTiming 明细、错误路径的任何测试；
+- 无 K=1×B<128（P0 漏洞区）、无 dtype_a≠dtype_b、无 trans/bias/out_nd 变体、无小 K 大 B（dValue 矛盾区）、无 fp32 降核 L0A 溢出（P1 矛盾区）测试；
+- 覆盖率视角：把 bug 场景固化进测试正是 README 宣称的"可验证——文档典型边界 case 全部固化，改动不破结论"，但实际只固化了一半。
+
+---
+
+## 7. 局限说明（本次测评的边界）
+
+1. 无法在真实 Ascend950PR（CANN/硬件）上实测：时延数值的**绝对精度无法验证**，只能验证"模型内部自洽 + 与文档公式一致 + 相对排序合理"；
+2. 芯片规格（486 TFLOPS、1.6/5.2TB/s、搬移效率经验值等）为仓库自述，未与外部公开资料交叉验证（昇腾950PR 属于新芯片，公开资料有限）；
+3. 随机压力测试覆盖了形状谱系但不可能穷举；数值结论（6%/18%）随采样分布变化，属量级参考而非精确声称；
+4. 未对理论文档的数学推导本身做正确性复审（超出软件测评范围），仅抽查了代码中使用的关键常数。
+
+---
+
+## 8. 总评与建议
+
+### 8.1 定位判断
+这是**"理论分析文档的代码化 POC"**，不是经过生产打磨的工具。它最有价值的资产不在代码量而在**决策树 + 分界公式 + 逐分支时延模型的可执行化**与**可解释输出**。方向上与 ops-nn 源码"当前实现 vs 理论上限"对照的初衷一致，但当前版本还缺少把结论与真实算子实现/实测对标的能力（无对照数据输入、无标定通道）。
+
+### 8.2 改进路线（按优先级）
+1. **P0**：修复特殊分支空洞（K=1×B<128 兜底或显式报错不崩溃）；`BranchResult` 无 plan 时路由层必须 fallback；为 plan 为 None 的路径补全链路防护 + 回归测试。
+2. **P1**：抽出单一约束源（L0C/L0A/L0B/L1/dValue/min_TileSize/核数）供 `make_plan` 与 `_check_constraints` 共用；recommend 生成后强制自检，不可行则修复/降级；对齐 IterBatch a/b 豁免与 dValue 检查的口径（并补充小 K 时 T_cmd 主导的时延修正）；降核模式 base_k 按 dtype 容量反推。
+3. **P2**：io_csv 支持 `out_nd`；实现 dtype 不一致告警；明确 trans/bias 的建模边界或在文档声明不支持；StreamK 归约计账口径（max vs drain、fixpipe 4B vs C dtype）请作者复核并写清约定；输入校验与友好报错。
+4. **测试**：补 CLI/io/evaluator/约束器单测，把本文 §5 全部复现样例固化为回归用例；跑多 Python 版本矩阵并修正版本声明。
+5. **工程化**：补 README 目录树与架构文档同步机制（或引入文档 lint）；打包（pyproject）+ CI；参数表增加"来源/置信度/待标定"列，标定流程文档化。
+6. **远期**：接入真实 kernel 时延/电源剖面数据做模型标定（T_cmd、带宽利用率曲线、dValue 实际影响），使"理论最优"能回答"离实测最优差多远"；输出"与源码方案对比"通道，兑现 README 定位。
+
+### 8.3 是否推荐使用
+- 用于**理论学习、分支归属直觉、方案生成的结构化探索**：推荐（0.1 版本已具备核心价值）；
+- 用于**对真实 NPU 性能做定量决策**：当前**不建议**——先完成 P0/P1 修复与硬件标定。
+
+---
+
+## 附录 A：复现命令
+
+```bash
+# 克隆
+git clone https://oauth2:<TOKEN>@git.magicnetworld.com/admin/matmul-analysis.git
+# 单测
+cd BMM/BMM_Theory && python -m unittest discover -s tests -v
+# 双模式
+python -m bmm_theory recommend examples/cases_demo.csv -o r.csv --plans p.csv -v
+python -m bmm_theory evaluate examples/cases_demo.csv p.csv -o e.csv -v
+# P0 崩溃复现
+python -m bmm_theory recommend <(printf 'case_id,batch_a,batch_b,m,n,k,dtype_a,dtype_b,dtype_c\nx,64,64,8192,32,1,int8,int8,int8\n')
+```
+
+## 附录 B：手工核验样例（与程序输出一致）
+
+以 `iter_demo_form_b`（B=128, M=N=64, K=256, bf16）为例，单核带宽份额 GM=1.6TB/s÷32=50GB/s、L2=5.2÷32=162.5GB/s、单核 Cube=486÷32=15.1875 TFLOPS：
+- 每核搬入 = b_core(4)×(M·K+K·N)×2B = 4×65536B = 256KB → 256KB/50GB/s = **5.24us**（GM=5.24 ✓）
+- MMAD = 4×2×64×64×256 / 15.1875e12 = **0.55us** ✓
+- Fixpipe = 4×64×64×2B / 50GB/s = **0.66us** ✓（C 为 bf16 按 2B 写出）
+- DMA 命令 = b_core×n_K = 4×50ns = **0.20us** ✓
+- drain = T_comp_chunk + T_write = 0.138+0.164 = **0.30us** ✓
+- T_total = max(5.24+0.20, 0.55, 0.66)+0.30 = **5.74us** ✓
+
+常数抽检：R16=486e12/(1.6e12/2)=**607.5** ✓；θ_c=Q16/2·(8/W_L2+1/Q_AIV)=**12.24≈12** ✓；ASW 面积/周长分界的 93.5（=dt·Q16/(2·BW_L2pc)）与 304（=outB·Q16/(2·BW_pc)）与文档一致 ✓；L0C=65536 元素 ✓。
+
+## 附录 C：随机压力测试分支分布（供参考）
+
+实验 A（宽范围 8000，剔除 P0 区）：IterBatch 501、ASW_Basic 1581、StreamK 154、转Matmul 1459、ASW_降核 685、MergeBatch 580、特殊分支 40。
+实验 B（典型形状 6000）：ASW_Basic 2222、IterBatch 1609、StreamK 476、ASW_降核 1029、转Matmul 570、MergeBatch 94。
+两实验未见 NaN/负时延/崩溃（P0 区除外；另一次 5 000 例实验对 NaN 与负时延做了显式断言，全部通过），说明数值层面稳定，问题集中在**约束一致性**。
+
+---
+
+*报告生成：本地静态审查与动态测试相结合；所有"问题"均有文件:行号或可复现命令支撑。*