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

- 新增 measurement/ 测量协议入口（baseline.md + timing-log.md） - 新增 docs/demo-storyboard.md 演示视频分镜 - README 新增背景与痛点、挂接测量协议/设计文档/分镜链接
2026-08-29 11:39:49 +08:00
parent 71de0e7dc0
commit 458647d82e
5 changed files with 333 additions and 2 deletions
@@ -0,0 +1,34 @@
+# 演示视频分镜脚本（docs/demo.mp4）
+
+> 用途：录制 ≤5 分钟演示视频的分镜参考，覆盖大赛规范要求的三个要素——**完整工作流 + IDE 集成效果 + 异常处理**。
+> 成品存放：`docs/demo.mp4`；录完后更新 README「演示视频」节为正式描述。
+
+## 录制准备
+
+| 项 | 建议 |
+|---|---|
+| 录屏工具 | OBS Studio（免费）或 VS Code 内置屏幕录制 |
+| 分辨率 | 1920×1080，窗口聚焦 VS Code |
+| 示例工程 | `data/efficiency-samples/`（含缺陷的多语言样例，JS/CSS/Java/SQL 混合） |
+| 时长 | ≤5 分钟，按分镜控制 |
+| 语速 | 关键操作配一句口播或字幕说明，不堆话 |
+
+## 分镜表
+
+| 段 | 时间 | 内容 | 镜头要点 |
+|---|---|---|---|
+| 开场 | 0:00–0:20 | 项目一句话定位：「净码特工——AI 驱动的多语言代码审查一体化 VS Code 插件」；打开含缺陷示例工程 | 标题卡片 3 秒 → VS Code 窗口切入，左侧资源管理器展示四种语言文件 |
+| 工作流①：静态审查 | 0:20–1:50 | 一键审查（`Ctrl+Shift+R`）→ 编辑器波浪线标记 → 「问题」面板结果 → 树形审查面板按严重级分组 | 编辑器 → 问题面板 → Webview 审查面板三个视角切换；圈出英文机器诊断原文 |
+| 工作流②：AI 审查 | 1:50–3:00 | 触发 AI 深度审查：英文诊断翻译为中文 + 修复建议；挖掘语义级问题（安全/逻辑/性能/设计） | 高亮 AI 翻译条目与静态通道的合并展示；点开一条 AI 审查详情 |
+| 工作流③：自动修复 | 3:00–3:40 | 单条 AI 修复 → diff 预览两步确认 → 写入自动保存；演示全部修复与按来源撤销 | diff 预览界面特写（两步确认按钮）；修复后问题数下降 |
+| IDE 集成 | 3:40–4:20 | 方法级 CodeLens 审查按钮；保存自动分析；设置面板配置 AI Provider；导出 Markdown 审查报告 | 四个功能各 8–10 秒快切；CodeLens 按钮悬停特写 |
+| 异常处理 | 4:20–4:50 | 断网或无效 API Key 场景：AI 通道优雅降级（面板 degraded 状态），静态通道独立可用不阻塞 | 面板降级状态标识特写 + 静态诊断仍正常产出 |
+| 收尾 | 4:50–5:00 | 效果数据卡：23 文件 8.6 秒 / 人工 38.1 分钟 / 提速约 266 倍 / 检出率 27%→100%；仓库地址 | 数据卡片定格 5 秒（数据源：`measurement/timing-log.md`） |
+
+## 录制后自查
+
+- [ ] 三个规范要素均出现：完整工作流（段 2–4）、IDE 集成效果（段 5）、异常处理（段 6）
+- [ ] 总时长 ≤5 分钟
+- [ ] 文件命名 `demo.mp4`（ASCII 小写，无中文无空格），置于 `docs/`
+- [ ] 单文件 ≤50MB（超限时压缩分辨率/帧率）
+- [ ] README「演示视频」节更新为正式描述，删除「进行中」
@@ -0,0 +1,139 @@
+# 评审整改 P0 方案：测量协议对齐 + README 痛点补全 + 演示分镜
+
+> 日期：2026-08-29
+> 阶段链：① 用户提出 → ② 需求澄清 → ③ 方案设计
+> 背景：第 12 次评审 79/100。提效幅度 2/10（-8）主因评审探针未识别测量协议文件（`measurement` 目录 / `baseline.md` / `timing-log` / 可重演命令）；提效设计合理性 8/10 缺痛点分析；演示与文档 2/5 演示视频未提供。
+> 约束：大赛规范 §8-04 要求提效对比数据放 `tests/`（已满足、不动）；`measurement/` 为新增协议入口目录，不与规范冲突。截止 2026-08-31 push。
+
+## 1. 架构概览（数据流）
+
+```
+原始数据层（不动）                    协议入口层（新增）              展示层（修改）
+data/efficiency-samples/  ─┐
+data/manual-review-tool.html ─┤→ measurement/baseline.md  ←─┐
+tests/measure/results/        │  measurement/timing-log.md  ├─→ README.md（效果总结段链接）
+  manual-review-AI-SIM-*.json ─┘         │                   │→ README.md（新增"背景与痛点"节）
+  a3-plugin-results.json ─────→ 全部为真实数据提炼，零占位      └→ docs/demo-storyboard.md（分镜）
+  a3-comparison.json ─────────┘
+```
+
+* 原则：`measurement/` 两文件是**汇总视图**，不复制原始 JSON，一律以相对路径引用原始数据，保证"协议入口 → 原始数据"单向引用链、单一数据源。
+
+* 命名对齐评审探针字面词：目录 `measurement/`、文件 `baseline.md`、文件 `timing-log.md`（ASCII 小写+连字符，符合规范 §6 红线 1）。
+
+## 2. 文件变更清单
+
+| # | 文件                          | 操作 | 内容                                               |
+| - | --------------------------- | -- | ------------------------------------------------ |
+| 1 | `measurement/baseline.md`   | 新建 | 人工基线实验报告（协议+数据+结论）                               |
+| 2 | `measurement/timing-log.md` | 新建 | 计时日志（插件侧+人工侧+环境+可重演命令）                           |
+| 3 | `docs/demo-storyboard.md`   | 新建 | 演示视频分镜脚本（≤5 分钟三段式）                               |
+| 4 | `README.md`                 | 修改 | 3 处：新增"背景与痛点"节、效果总结段补 measurement/ 链接、演示视频节挂分镜链接 |
+| 5 | `_AI_USAGE_LOG.md`          | 追加 | 实现后按日志规则补一条记录（Stage ⑤ 执行时）                       |
+
+不动：`tests/measure/` 全部、`data/` 全部、`DESIGN.md`、时间线文档。
+
+## 3. 各文件内容设计
+
+### 3.1 `measurement/baseline.md`（人工基线）
+
+* **标题与定位**：A3 实验人工基线报告——评审测量协议入口之一。
+
+* **实验设计**：问题（人工审查 vs 插件静态分析的耗时与检出差异）；样例 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`；流程「开始 → 阅读 → 记录问题 → 完成」逐文件计时。
+
+* **基线数据表**（源自 `a3-comparison.json`，数据核对一致）：
+
+| 维度       | 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 |
+
+* **审查人明细表**（复用 performance-comparison.md §四：三人×四语言条/耗时+总耗时 28.6/36.3/49.3 min）。
+
+* **基线结论**：均值 38.1 分钟 / 76 条；对照插件 283 条，人工检出率 27%（漏检 73%）；等级越高漏检越少。
+
+* **原始数据与可重演**：列 `tests/measure/results/manual-review-AI-SIM-00*.json` 三份路径；说明人工侧为一次性实测记录（协议上文可复刻流程），插件侧对同批样例可重演。
+
+### 3.2 `measurement/timing-log.md`（计时日志）
+
+* **测量环境**：测量日期 2026-08-27；工具链（ESLint/Stylelint 引擎直跑 + PMD `pmd-java-ruleset.xml` + SQLFluff oracle 方言，与插件内置配置逐字一致）；Windows 11 / Node 22（以实测环境为准，实现时核对 `a3-plugin-results.json` 的 `tool`/`measureDate` 字段如实填写）。
+
+* **插件侧计时表**（源自 `a3-plugin-results.json`）：分语言 4 行 + 合计（95.1 / 129.3 / 6610.7 / 1741.7 / 8576.8 ms，283 条），含"Java 含 JVM 启动、SQL 含子进程启动"注记。
+
+* **逐文件计时表**：23 行（文件名 / 耗时 ms / 诊断数），从 `a3-plugin-results.json` 的 `perFile` 逐一转录。
+
+* **人工侧计时表**：三人×分语言耗时 + 总计（同 baseline.md 数据源，交叉引用不重复展开条数）。
+
+* **汇总提速表**：JS 约 8500× / CSS 约 3400× / Java 约 94× / SQL 约 238× / 合计约 266×。
+
+* **可重演命令**（独立小节，逐条列出）：
+
+  * `node tests/measure/measure-plugin-samples.mjs`（插件侧全量计时，产出 `tests/measure/results/a3-plugin-results.json`）
+
+  * `node tests/measure/compare-a3.mjs`（聚合对比，产出 `tests/measure/results/a3-comparison.json`）
+
+  * 人工侧：浏览器打开 `data/manual-review-tool.html` 按协议流程复刻
+
+* 头部引用链：样例目录、对比报告 `tests/measure/performance-comparison.md`、原始 JSON 路径。
+
+### 3.3 `docs/demo-storyboard.md`（演示分镜，交付给用户录制用）
+
+按规范 §8-06 要求三要素（完整工作流 + IDE 集成效果 + 异常处理），总长 ≤5 分钟：
+
+| 段      | 时长        | 内容                                                          | 镜头要点                             |
+| ------ | --------- | ----------------------------------------------------------- | -------------------------------- |
+| 开场     | 0:00–0:20 | 项目一句话定位 + 打开含缺陷的多语言示例工程（用 `data/efficiency-samples/`）       | 标题卡片→VS Code 窗口                  |
+| 工作流①   | 0:20–1:50 | 一键审查（Ctrl+Shift+R）→ 问题面板波浪线 → 树形审查面板按严重级分组 → AI 审查（中文翻译+建议） | 编辑器→问题面板→Webview 面板切换；高亮 AI 翻译条目 |
+| 工作流②   | 1:50–3:00 | AI 自动修复：单条修复→diff 预览两步确认→写入自动保存；全部修复                        | diff 预览界面特写                      |
+| IDE 集成 | 3:00–3:50 | 方法级 CodeLens 审查按钮、保存自动分析、设置面板 Provider 配置、报告导出 Markdown     | 四个功能各 10–15 秒快切                  |
+| 异常处理   | 3:50–4:40 | 断网/无效 API Key 下 AI 通道优雅降级（degraded 状态展示）、静态通道独立可用           | 面板降级状态标识特写                       |
+| 收尾     | 4:40–5:00 | 效果数据卡（266× 提速、27%→100% 检出率）+ 仓库地址                           | 数据卡片定格                           |
+
+* 附录制提示：录屏工具建议、分辨率、存放路径 `docs/demo.mp4`、录完后更新 README 演示视频节。
+
+* 本文件为团队内部工作文档，放 `docs/`（非 spec、非根目录 README 嵌套问题）。
+
+### 3.4 `README.md` 修改（3 处）
+
+**① 新增"背景与痛点"节**——位置：`项目概述`之后、`效果总结`之前（评审原话"缺乏明确的痛点分析和业务背景"）。内容 = 场景一句（企业多语言混合工程：运营商城域后台、金融核心等遗留系统）+ 从 DESIGN.md 1.2 提炼的 4 行精简痛点表：
+
+| 痛点                    | 插件方案                                 |
+| --------------------- | ------------------------------------ |
+| 英文机器诊断阅读成本高           | AI 翻译为输出语言（中/英/日）+ 修复建议              |
+| 静态规则覆盖不了语义级安全/逻辑/设计缺陷 | LLM 深度审查通道四类增量发现，不重复静态结果             |
+| 团队私有规范无法进通用 linter    | YAML 自定义规则 + AI 语义判定 + 热加载           |
+| 发现问题后修复靠人工逐条处理        | 分级修复闭环（原生 fix → AI 修复 → diff 预览两步确认） |
+
+末行链接：`详细场景与价值映射见 DESIGN.md §1`。
+
+**② 效果总结数据来源段**——在现有 blockquote 末尾追加一句：`测量协议详见 measurement/baseline.md（人工基线）与 measurement/timing-log.md（计时日志与可重演命令）。`
+
+**③ 演示视频节**——`进行中`文字后追加：`分镜脚本见 docs/demo-storyboard.md（三段式：完整工作流 / IDE 集成 / 异常处理）`；保留"后续提交补齐"表述，用户录完视频后自行替换为正式链接。
+
+另：`项目概述`段末追加一行引用：`完整设计见 DESIGN.md，实现时间线见 docs/2026-08-27-implementation-timeline.md`（补评审"无时间线"缺口）。
+
+## 4. 关键决策记录
+
+| 决策                          | 选项与理由                                                             |
+| --------------------------- | ----------------------------------------------------------------- |
+| 不整体迁移 `tests/measure/`      | 大赛规范 §8-04 硬性要求实验报告在 `tests/` 内；迁移违反规范（Stage ② 已共识推翻备选方案）         |
+| `measurement/` 不放 README.md | 规范红线 4 要求主 README 在根目录；嵌套 README 虽未明令禁止但检测逻辑未知，用户要求避开（Stage ② 共识） |
+| 只新建 2 文件                    | 协议说明与可重演命令并入 baseline.md / timing-log.md 正文，避免第三文件                |
+| 分镜脚本放 `docs/`               | 非交付 spec、非成果物清单文件，属过程文档                                           |
+
+## 5. 非目标（本方案不做）
+
+* AI 调用重试机制与统一异常兜底（P1，代码变更，另立 spec）
+
+* CI 流水线 / MCP Server（P1，另立 spec）
+
+* `demo.mp4` 实际录制（用户亲自完成，本方案仅交付分镜）
+
+## 6. 验证方式（Stage ⑥ 预告）
+
+1. 四个探针词逐一 grep 验证存在：`measurement` 目录、`baseline.md`、`timing-log`、可重演命令字串 `node tests/measure/measure-plugin-samples.mjs`。
+2. 数据一致性抽查：baseline.md / timing-log.md 中数值与 `a3-comparison.json`、`a3-plugin-results.json` 逐项一致（2286s / 8576.8ms / 283 条 / 266×）。
+3. README 渲染检查：新增节锚点正常、相对链接可达（`measurement/baseline.md`、`docs/demo-storyboard.md`、`docs/2026-08-27-implementation-timeline.md`）。
+4. 红线自查：新文件名全 ASCII 小写+连字符；无绝对路径；无密钥。
+5. `_AI_USAGE_LOG.md` 已按规则追加记录。
+