# Retrospects · AI 协作复盘

每次任务收尾的 AI-用户协作复盘。**两份文件配对：**

| 后缀 | 用途 | 受众 |
|---|---|---|
| `*.md` | 长读版（完整 8 段格式） | UX team 内部精读 / handoff reference |
| `*.slides.md` | Marp 幻灯片源文件 | 转 PPTX / PDF / HTML 给同事 + 领导内部分享 |

复盘的 **8 段格式 spec**：见同目录 [`RETROSPECT_FORMAT.md`](./RETROSPECT_FORMAT.md) — 段落结构 + 写法要点 + 标杆参考。

## 默认 = 不导出

**复盘写完默认只有 `.md` + `.slides.md` 源文件**，不自动生成 dist/ 产物。

理由：
- `.md` 长读版 + gitea 自带 Markdown 渲染已能覆盖"日常看复盘"场景
- PPTX / HTML 是给"对外分享"场景用的，没分享需求就不浪费 ~7MB 本地空间 + Chromium 启动时间
- AI 不要自作主张帮你导出（详见 [[feedback_export_on_demand_only]]）

## 触发导出（用户说这些关键词才跑）

| 关键词 | 触发 |
|---|---|
| 导出幻灯片 / export slides | 跑 marp → PPTX + HTML 到 dist/ |
| 分享 / share | 同上 |
| 出 PPT / 出 HTML | 仅出指定格式 |

## 起步：装 marp-cli（一次）

```bash
npm i -g @marp-team/marp-cli
```

## 手动导出命令

仓库根目录跑（`.marprc.yml` 自动加载 TVU 真源主题）：

```bash
# 推荐组合 — HTML + PPTX
marp docs/retrospects/<name>.slides.md --pptx -o docs/retrospects/dist/<name>.pptx
marp docs/retrospects/<name>.slides.md --html -o docs/retrospects/dist/<name>.html

# 批量 — 所有 .slides.md
marp docs/retrospects/*.slides.md --pptx -o docs/retrospects/dist/
marp docs/retrospects/*.slides.md --html -o docs/retrospects/dist/
```

产物目录 `docs/retrospects/dist/` 已 `.gitignore`，不入库。

## 分享场景对应格式

| 格式 | 场景 |
|---|---|
| **`.md` 源**（默认有） | UX team 精读 / git diff / 代码同事直接看 / **gitea 浏览器渲染**（无需导出） |
| **PPTX**（按需出） | 投屏会议、嵌进周报、领导要改 |
| **HTML**（按需出） | 内网链接分享 / 本地预览深色科技风 |

**不出 PDF**：Marp PDF 走打印 CSS 管线，渐变 / box-shadow 会失真，跟 HTML/PPTX 排版有差异。需要静态附件用 PPTX → 另存为 PDF（Keynote / PowerPoint 自带导出更稳）。

## 写新复盘

1. **长读版**：按 [`RETROSPECT_FORMAT.md`](./RETROSPECT_FORMAT.md) 8 段格式写，命名 `YYYY-MM-DD-{feature}-{type}.md`
2. **幻灯版**：复制 `_template.slides.md` → 同名加 `.slides.md` 后缀。按 **15-20 张幻灯片重组核心内容**（不是 1:1 复制长读版）
3. 默认不导出 → 用户触发关键词才跑 marp → 分享

## 维护

骨架文件 `_template.slides.md` 由 `tvu-design-system/templates/consumer-product/docs/retrospects/_template.slides.md` scaffold。改主题 / 改结构请改真源，单点改本目录不入回流。