docs: 评审整改 P0 文档包（第 12 次评审 79 分失分项）

- 新增 measurement/ 测量协议入口（baseline.md + timing-log.md）
- 新增 docs/demo-storyboard.md 演示视频分镜
- README 新增背景与痛点、挂接测量协议/设计文档/分镜链接

measurement/baseline.md

@@ -0,0 +1,47 @@
+# 人工基线实验报告（Baseline）
+
+> 实验：A3 · 人工审查基线测量
+> 定位：评审测量协议入口——人工侧基线数据汇总与实验设计说明。原始数据不在此复制，见文末「原始数据」。
+
+## 一、实验设计
+
+**问题**：同一批含缺陷的多语言样例代码，人工逐文件审查与插件静态分析在耗时与问题检出上差异几何？
+
+- **样例**：23 个多语言文件（JS×8 / CSS×5 / Java×6 / SQL×4），均为含缺陷的真实形态代码，存放于 `data/efficiency-samples/`。
+- **审查人**：3 名不同经验等级——高级（AI-SIM-001）/ 中级（AI-SIM-003）/ 初级（AI-SIM-002）。
+- **工具**：人工审核记录工具 `data/manual-review-tool.html`（浏览器打开，逐文件计时）。
+- **流程**：每名审查人对每个文件执行「开始 → 阅读 → 记录问题 → 完成」，工具记录单文件耗时与发现的问题数，最终导出 JSON 存档。
+- **对照组**：插件静态分析对同批样例的实测，见 `measurement/timing-log.md`。
+
+## 二、基线数据（3 人均值）
+
+| 维度 | JS | CSS | Java | SQL | 合计 |
+|---|---|---|---|---|---|
+| 发现问题数（条） | 36.7 | 14.0 | 20.0 | 5.7 | **76.3** |
+| 审查耗时（s） | 811.7 | 437.7 | 622.0 | 414.7 | **2286.0** |
+
+## 三、审查人明细
+
+| 审查人 | 等级 | JS 条/耗时 | CSS 条/耗时 | Java 条/耗时 | SQL 条/耗时 | 总耗时 |
+|---|---|---|---|---|---|---|
+| AI-SIM-001 | 高级 | 49 / 597s | 18 / 322s | 26 / 465s | 7 / 334s | 28.6 min |
+| AI-SIM-003 | 中级 | 38 / 773s | 13 / 416s | 20 / 596s | 6 / 395s | 36.3 min |
+| AI-SIM-002 | 初级 | 23 / 1065s | 11 / 575s | 14 / 805s | 4 / 515s | 49.3 min |
+| **均值** | — | **36.7 / 811.7s** | **14.0 / 437.7s** | **20.0 / 622.0s** | **5.7 / 414.7s** | **38.1 min** |
+
+> 经验等级的影响符合预期：高级审查人耗时最短（28.6 min）且发现数最多；初级耗时最长（49.3 min）且发现数最少。
+
+## 四、基线结论
+
+1. **耗时**：23 文件人工审查平均需 **38.1 分钟**（2286s）。
+2. **检出量**：人工平均发现 **76.3 条**规范问题；对照插件同批样例 283 条诊断，人工检出率仅 **27%**（平均漏检 73%）。
+3. **等级规律**：经验等级越高漏检越少——人工受经验与注意力限制，规则类问题难以全覆盖；插件内置规则全覆盖、逐字可复现，可兜底人工漏检。
+
+## 五、原始数据与可重演
+
+- 人工原始记录（3 份，逐文件计时与问题清单）：
+  - `tests/measure/results/manual-review-AI-SIM-001.json`（高级）
+  - `tests/measure/results/manual-review-AI-SIM-002.json`（初级）
+  - `tests/measure/results/manual-review-AI-SIM-003.json`（中级）
+- 人工侧为一次性实测记录（协议流程见上文「实验设计」，可用 `data/manual-review-tool.html` 复刻）；插件侧对同批样例可任意重演，命令见 `measurement/timing-log.md` §可重演命令。
+- 聚合对比（含分语言提速倍数）：`tests/measure/results/a3-comparison.json`；完整对比报告：`tests/measure/performance-comparison.md`。

measurement/timing-log.md

@@ -0,0 +1,96 @@
+# 计时日志（Timing Log）
+
+> 实验：A3 · 插件静态分析计时 + 人工审查计时对照
+> 定位：评审测量协议入口——计时日志与可重演命令。原始 JSON 不在此复制，见文末「原始数据」。
+
+## 一、测量环境
+
+| 项 | 值 |
+|---|---|
+| 测量日期 | 2026-08-27 22:11（北京时间，UTC+8） |
+| 操作系统 | Windows 11 Pro |
+| Node.js | v22.16.0 |
+| 测量工具 | `tests/measure/measure-plugin-samples.mjs`（工具标识 code-reviewer / 实验 A3） |
+| 工具链 | ESLint / Stylelint 引擎直跑（与 `src/rules/builtin-rules.ts` 内置配置逐字一致）；PMD 经 `PmdRunner` + `pmd-java-ruleset.xml`（与 `src/adapters/pmd.ts` 一致）；SQLFluff 内置配置（方言 oracle，与 `src/adapters/sqlfluff.ts` 一致） |
+| 样例 | `data/efficiency-samples/`（23 文件：JS×8 / CSS×5 / Java×6 / SQL×4） |
+
+## 二、插件侧计时（分语言汇总）
+
+| 语言 | 文件数 | 诊断数 | 耗时 | 备注 |
+|---|---|---|---|---|
+| JS | 8 | 120 | 95.1ms | 纯静态引擎 |
+| CSS | 5 | 55 | 129.3ms | 纯静态引擎 |
+| Java | 6 | 84 | 6610.7ms | 含 JVM 启动 |
+| SQL | 4 | 24 | 1741.7ms | 含子进程启动 |
+| **合计** | **23** | **283** | **8576.8ms** | — |
+
+## 三、插件侧逐文件计时
+
+| # | 文件 | 耗时 | 诊断数 |
+|---|---|---|---|
+| 1 | sample-01.js | 76.4ms | 15 |
+| 2 | sample-02.js | 4.0ms | 15 |
+| 3 | sample-03.js | 3.1ms | 15 |
+| 4 | sample-04.js | 3.3ms | 15 |
+| 5 | sample-05.js | 2.6ms | 15 |
+| 6 | sample-06.js | 1.8ms | 15 |
+| 7 | sample-07.js | 1.8ms | 15 |
+| 8 | sample-08.js | 2.1ms | 15 |
+| 9 | sample-01.css | 117.7ms | 11 |
+| 10 | sample-02.css | 3.9ms | 11 |
+| 11 | sample-03.css | 2.9ms | 11 |
+| 12 | sample-04.css | 2.3ms | 11 |
+| 13 | sample-05.css | 2.6ms | 11 |
+| 14 | InventoryService.java | 1183.1ms | 14 |
+| 15 | NotifyService.java | 1088.2ms | 14 |
+| 16 | OrderService.java | 1069.6ms | 14 |
+| 17 | PaymentService.java | 1077.4ms | 14 |
+| 18 | ReportService.java | 1089.7ms | 14 |
+| 19 | UserService.java | 1102.8ms | 14 |
+| 20 | sample-01.sql | 506.8ms | 9 |
+| 21 | sample-02.sql | 421.0ms | 3 |
+| 22 | sample-03.sql | 402.5ms | 9 |
+| 23 | sample-04.sql | 411.4ms | 3 |
+
+> 首文件耗时偏高（JS 76.4ms / CSS 117.7ms）为引擎冷启动；Java 每文件约 1.1s 为逐次拉起 JVM 的固定开销；SQL 每文件约 0.4s 为子进程启动开销。原始字段见 `tests/measure/results/a3-plugin-results.json`。
+
+## 四、人工侧计时（3 名审查人）
+
+| 审查人 | 等级 | JS 耗时 | CSS 耗时 | Java 耗时 | SQL 耗时 | 总耗时 |
+|---|---|---|---|---|---|---|
+| AI-SIM-001 | 高级 | 597s | 322s | 465s | 334s | 28.6 min |
+| AI-SIM-003 | 中级 | 773s | 416s | 596s | 395s | 36.3 min |
+| AI-SIM-002 | 初级 | 1065s | 575s | 805s | 515s | 49.3 min |
+| **均值** | — | 811.7s | 437.7s | 622.0s | 414.7s | **38.1 min** |
+
+> 问题数明细与人工侧完整数据见 `measurement/baseline.md`。
+
+## 五、汇总提速对比
+
+| 语言 | 人工耗时（均值） | 插件耗时 | 提速倍数 |
+|---|---|---|---|
+| JS | 811.7s | 95.1ms | 约 8500× |
+| CSS | 437.7s | 129.3ms | 约 3400× |
+| Java | 622.0s | 6610.7ms | 约 94× |
+| SQL | 414.7s | 1741.7ms | 约 238× |
+| **合计** | **2286.0s** | **8576.8ms** | **约 266×** |
+
+## 六、可重演命令
+
+```bash
+# 插件侧全量计时（23 文件，产出 tests/measure/results/a3-plugin-results.json）
+node tests/measure/measure-plugin-samples.mjs
+
+# 聚合人工基线与插件侧对比（产出 tests/measure/results/a3-comparison.json）
+node tests/measure/compare-a3.mjs
+
+# 人工侧复刻：浏览器打开工具，按 measurement/baseline.md §一 流程执行
+# （工具：data/manual-review-tool.html）
+```
+
+## 七、原始数据
+
+- 插件侧明细（逐文件耗时/诊断数/规则 ID）：`tests/measure/results/a3-plugin-results.json`
+- 人工原始记录（3 份）：`tests/measure/results/manual-review-AI-SIM-001.json` / `-002.json` / `-003.json`
+- 聚合对比：`tests/measure/results/a3-comparison.json`
+- 完整对比报告：`tests/measure/performance-comparison.md`