# 决赛材料制作 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 基于当前优化分支、初赛结项书、复现脚本和已有测试证据，生成放置于 `docs/finals/` 的决赛结项书 Markdown、Word 版本及 12 分钟答辩 PPT。

**Architecture:** 先建立单一事实清单，再由该清单驱动 Markdown、DOCX 和 PPT，避免三个交付物出现数字漂移。Word 采用正式技术报告样式并进行逐页渲染检查；PPT 继承赛事模板母版和布局，使用 Artifact Tool 编辑并进行逐页渲染、内容溢出和模板一致性检查。

**Tech Stack:** Markdown、Git、Python `python-docx`/OOXML、LibreOffice、`@oai/artifact-tool`、PowerPoint OOXML、Node.js、赛事 PPT 模板。

## Global Constraints

- 主标题必须为 `[功能] 适配 offload_group_size 和 offload_num_in_group 到 Ascend NPU`。
- 副标题必须为 `vLLM Ascend 权重分组预取卸载参数适配与优化`。
- 团队名称必须为 `乘风破浪的大学生`。
- 三份最终交付物必须位于 `docs/finals/`。
- PPT 必须基于 `D:\PDSL\Ascend\CCF大赛-vLLM Ascend赛道PPT模板.pptx`，保持 12 页并适配 12 分钟答辩。
- 所有测试数字必须来自仓库现有证据；GPQA 0/198 必须如实说明，不得包装为高精度结果。
- 不修改核心实现代码和已有测试结果。

---

## File Map

- Create: `docs/finals/决赛项目结项书.md` - 决赛结项书的内容权威版本。
- Create: `docs/finals/决赛项目结项书.docx` - 正式排版版本。
- Create: `docs/finals/决赛答辩PPT.pptx` - 12 页决赛答辩材料。
- Create: `.codex_tmp/finals-materials/evidence-summary.md` - 制作过程使用的事实清单。
- Create: `.codex_tmp/finals-materials/build_final_report.py` - DOCX 生成脚本。
- Create: `.codex_tmp/finals-materials/build_final_deck.mjs` - PPT 生成脚本。
- Create: `.codex_tmp/finals-materials/template-audit.txt` - 模板逐页审计记录。
- Create: `.codex_tmp/finals-materials/template-frame-map.json` - 输出页与模板页映射。
- Create: `.codex_tmp/finals-materials/deviation-log.txt` - 模板偏差记录。
- Create: `.codex_tmp/finals-materials/docx-render/` - Word 逐页渲染结果。
- Create: `.codex_tmp/finals-materials/ppt-render/` - PPT 逐页渲染结果。

### Task 1: 建立统一事实清单

**Files:**
- Create: `.codex_tmp/finals-materials/evidence-summary.md`
- Read: `docs/final-report.md`
- Read: `docs/v018-deployment-and-reproduction.md`
- Read: `docs/v018-test-evidence.md`
- Read: `docs/benchmark/offload-benchmark-report.md`
- Read: `scripts/run_reproduce_all.sh`
- Read: `scripts/run_accuracy_gsm8k_gpqa.sh`
- Read: `scripts/verify_accuracy_matrix.py`

**Interfaces:**
- Consumes: 当前分支代码、提交历史及仓库内测试证据。
- Produces: 三份交付物共同使用的版本、实现、精度、性能和复现事实。

- [ ] **Step 1: 提取版本、实现、性能、精度和复现命令**

  逐文件核对并记录数值、路径和限定条件；对重复数字进行交叉检查。

- [ ] **Step 2: 检查代码实现与文档描述一致性**

  使用 `rg` 定位 `offload_group_size`、`offload_num_in_group`、`NPUPrefetchOffloader`、`offload_backend`、pinned storage 和设备映射实现。

- [ ] **Step 3: 写入事实清单并扫描矛盾**

  人工核对事实清单中是否存在未完成段落、模糊数值或互相冲突的环境描述。

  Expected: 不出现占位符；近似数值均明确单位和来源。

### Task 2: 编写决赛结项书 Markdown

**Files:**
- Create: `docs/finals/决赛项目结项书.md`
- Read: `.codex_tmp/finals-materials/evidence-summary.md`
- Read: `docs/final-report.md`

**Interfaces:**
- Consumes: Task 1 的事实清单和初赛七章结构。
- Produces: Word 与 PPT 文案的内容权威版本。

- [ ] **Step 1: 按七章结构撰写正文**

  覆盖项目概述、参数难点、技术方案、实际交付、测试结论、AI 使用和限制及后续工作。

- [ ] **Step 2: 补充复现步骤和判定标准**

  包含环境准备、功能测试、性能测试、GSM8K、GPQA、结果校验和产物路径。

- [ ] **Step 3: 完成数字和路径一致性检查**

  Run: `rg -n "742\\.77|678\\.85|383\\.49|51/1319|0/198|35/35|69 passed" docs/finals/决赛项目结项书.md`

  Expected: 所有关键数据均出现，且上下文描述与事实清单一致。

- [ ] **Step 4: 检查 Markdown 质量**

  Run: `git diff --check -- docs/finals/决赛项目结项书.md`

  Expected: 无空白错误或冲突标记。

### Task 3: 生成并验证 Word 结项书

**Files:**
- Create: `.codex_tmp/finals-materials/build_final_report.py`
- Create: `docs/finals/决赛项目结项书.docx`
- Create: `.codex_tmp/finals-materials/docx-render/`

**Interfaces:**
- Consumes: `docs/finals/决赛项目结项书.md`。
- Produces: 内容一致、可打印、经过逐页检查的 DOCX。

- [ ] **Step 1: 读取文档设计规范并确定样式令牌**

  采用 formal technical report / standard business brief：A4 纵向、中文无衬线正文、蓝色标题体系、封面、自动目录字段、页眉、页脚和页码。

- [ ] **Step 2: 编写 DOCX 生成脚本**

  将标题、段落、真实项目符号、代码块和数据表转换为 Word 样式；表格固定列宽并避免跨页断裂。

- [ ] **Step 3: 生成 Word 文档**

  Run: `python .codex_tmp/finals-materials/build_final_report.py`

  Expected: `docs/finals/决赛项目结项书.docx` 可被 OOXML 工具正常读取。

- [ ] **Step 4: 运行结构和可访问性检查**

  Run: `python <documents-skill>/scripts/a11y_audit.py docs/finals/决赛项目结项书.docx`

  Expected: 无阻断级错误。

- [ ] **Step 5: 渲染全部页面**

  Run: `python <documents-skill>/render_docx.py docs/finals/决赛项目结项书.docx --output_dir .codex_tmp/finals-materials/docx-render --emit_pdf`

  Expected: 每页生成 PNG，无转换错误。

- [ ] **Step 6: 逐页视觉检查并迭代**

  检查封面、目录、标题孤行、表格截断、代码换行、页眉页脚和中文字体；发现问题后修改脚本、重建并重新渲染。

### Task 4: 审计赛事 PPT 模板并建立页面映射

**Files:**
- Create: `.codex_tmp/finals-materials/template-audit.txt`
- Create: `.codex_tmp/finals-materials/template-frame-map.json`
- Create: `.codex_tmp/finals-materials/deviation-log.txt`
- Read: `D:\PDSL\Ascend\CCF大赛-vLLM Ascend赛道PPT模板.pptx`

**Interfaces:**
- Consumes: 赛事模板的 12 个源页面、母版和布局。
- Produces: PPT 构建脚本的页面继承与可编辑区域约束。

- [ ] **Step 1: 检查 12 个模板页及全部布局元素**

  记录各页用途、固定品牌元素、可替换元素、提示文字和可用内容区域。

- [ ] **Step 2: 建立一一页面映射**

  将 12 个输出页面分别映射至模板 1-12 页，不新增或删除页。

- [ ] **Step 3: 记录必要偏差**

  仅记录清除示意提示、替换占位内容和在模板正文区域中加入图表等必要变化。

### Task 5: 制作 12 分钟决赛答辩 PPT

**Files:**
- Create: `.codex_tmp/finals-materials/build_final_deck.mjs`
- Create: `docs/finals/决赛答辩PPT.pptx`
- Read: `docs/finals/决赛项目结项书.md`
- Read: `.codex_tmp/finals-materials/template-frame-map.json`

**Interfaces:**
- Consumes: Task 2 文案、Task 4 模板映射和原始 PPTX。
- Produces: 12 页、含讲述备注和来源备注的答辩 PPT。

- [ ] **Step 1: 创建模板继承的工作副本**

  使用 presentations skill 的模板辅助脚本准备 starter deck，保持母版和布局层级。

- [ ] **Step 2: 编写 Artifact Tool 构建脚本**

  逐页编辑继承元素，加入参数关系图、实现数据流、验证矩阵、精度对比和性能/显存权衡图；所有新增元素必须位于映射内容区内。

- [ ] **Step 3: 写入 12 分钟讲述备注**

  每页记录建议时长、核心讲述句和证据来源；总讲述目标为 11 分 20 秒。

- [ ] **Step 4: 导出 PPTX**

  Run: `node .codex_tmp/finals-materials/build_final_deck.mjs`

  Expected: `docs/finals/决赛答辩PPT.pptx` 包含 12 页并继承模板主题。

### Task 6: PPT 渲染与模板一致性检查

**Files:**
- Create: `.codex_tmp/finals-materials/ppt-render/`
- Modify: `.codex_tmp/finals-materials/build_final_deck.mjs`
- Modify: `docs/finals/决赛答辩PPT.pptx`

**Interfaces:**
- Consumes: Task 5 输出的 PPTX。
- Produces: 无溢出、无遮挡、模板一致性合格的最终 PPTX。

- [ ] **Step 1: 渲染全部幻灯片**

  Run: `python <presentations-skill>/render_slides.py docs/finals/决赛答辩PPT.pptx --output_dir .codex_tmp/finals-materials/ppt-render`

  Expected: 12 张 PNG 全部生成。

- [ ] **Step 2: 逐页视觉检查**

  检查品牌元素、标题层级、图表标签、中文换行、页码、备注和示意提示是否清除。

- [ ] **Step 3: 运行幻灯片结构检查**

  Run: `python <presentations-skill>/slides_test.py docs/finals/决赛答辩PPT.pptx`

  Expected: 无文本溢出、边界越界或损坏对象错误。

- [ ] **Step 4: 运行模板一致性检查**

  比较页面数、母版、布局关系和关键固定元素；将可接受偏差写入 `deviation-log.txt`。

- [ ] **Step 5: 修复问题并重新执行全部检查**

  对任何截断、重叠、密度过高或模板偏移进行迭代，直到所有 12 页检查通过。

### Task 7: 最终一致性与仓库验收

**Files:**
- Verify: `docs/finals/决赛项目结项书.md`
- Verify: `docs/finals/决赛项目结项书.docx`
- Verify: `docs/finals/决赛答辩PPT.pptx`

**Interfaces:**
- Consumes: Task 2、3、6 的最终输出。
- Produces: 可提交的决赛材料目录。

- [ ] **Step 1: 核对三个文件存在且非空**

  Run: `Get-Item docs/finals/* | Select-Object Name,Length`

  Expected: 三个目标文件均存在且大小大于 0。

- [ ] **Step 2: 跨文件核对标题、团队、版本和数字**

  从 Markdown、DOCX 和 PPTX 中提取文本，比对主标题、团队名称、版本号、精度和性能关键数字。

- [ ] **Step 3: 检查 Git 工作区范围**

  Run: `git status --short`

  Expected: 仅包含计划内文档、交付物和必要制作记录，不包含核心代码变化。

- [ ] **Step 4: 提交最终材料**

  Run: `git add docs/finals docs/superpowers/plans/2026-07-29-finals-materials.md`

  Run: `git commit -m "docs: add finals report and defense deck"`

  Expected: 提交成功，工作区干净。
