iapplegenius Project Retrospective Skill
概述
本 skill 用于对刚完成的开发项目进行全面复盘，生成图文并茂的总结文档，供开发者存档、交接或分享。
输出物：
retrospective_<project_name>.md— 结构化 Markdown 复盘文档（含 Mermaid 图）retrospective_<project_name>.html— 可独立打开的美观 HTML 版本
Step 0：信息收集
在开始生成之前，先收集以下信息（优先从上下文/已有文件自动提取，缺失时才询问用户）：
自动提取（优先）
- 扫描项目目录结构（
find . -type f或ls -R） - 读取
README.md、package.json、requirements.txt、pyproject.toml、Cargo.toml等配置文件 - 分析主要源码文件，提取函数/类定义
- 从对话历史中提取遇到的错误、解决方案、关键决策
需要用户补充（如上下文缺失）
询问以下问题（一次性问完，不要分多轮）：
- 项目名称和一句话介绍是什么？
- 这次开发中遇到了哪些印象最深的难点？
- 有哪些你认为值得记录的设计决策？
- 后续打算在哪些方向继续优化？
Step 1：分析项目
1.1 文件结构分析
# 获取文件树（忽略 node_modules / .git / __pycache__ 等）
find . -type f \
-not -path '*/.git/*' \
-not -path '*/node_modules/*' \
-not -path '*/__pycache__/*' \
-not -path '*/.venv/*' \
| sort
1.2 函数/类提取
根据语言选择合适的分析方式：
- Python: 扫描
def和class定义，结合 docstring - JavaScript/TypeScript: 扫描
function、const xx = () =>、class - Rust/Go: 扫描
fn、func - 通用: 读取核心文件，手动识别关键函数
1.3 依赖/插件提取
- Python:
requirements.txt/pyproject.toml/setup.py - Node.js:
package.json→dependencies+devDependencies - Rust:
Cargo.toml - Go:
go.mod
Step 2：生成 Markdown 文档
按以下模板填充内容，存为 retrospective_<project_name>.md：
# 项目复盘：<项目名称>
> **完成时间**：<日期>
> **技术栈**：<主要语言 + 框架>
> **一句话描述**：<项目功能简介>
---
## 1. 项目概述
<2-4 段描述项目背景、目标、核心功能>
---
## 2. 技术架构
<整体架构说明文字>
```mermaid
graph TD
A[入口 / main] --> B[模块A]
A --> C[模块B]
B --> D[子功能1]
B --> E[子功能2]
C --> F[数据层]
D --> F
E --> F
F --> G[(存储/外部API)]
3. 文件目录结构
project/
├── src/
│ ├── main.py # 程序入口
│ ├── module_a.py # 模块A：功能描述
│ └── module_b.py # 模块B：功能描述
├── tests/
├── requirements.txt
└── README.md
4. 函数调用关系
sequenceDiagram
participant Main
participant ModuleA
participant ModuleB
participant Storage
Main->>ModuleA: init()
ModuleA->>ModuleB: process(data)
ModuleB->>Storage: save(result)
Storage-->>ModuleB: ok
ModuleB-->>Main: done
5. 核心函数详解
函数名(参数) — 所在文件
功能：<一句话描述>
参数：
参数名(类型): 含义
返回值：<描述>
关键逻辑：<说明核心实现思路，不要照抄代码，用文字解释>
<为每个核心函数重复以上结构>
6. 开发难点与解决方案
难点 1：<标题>
问题描述：<遇到了什么问题>
尝试过的方案：<失败的尝试，帮助后来者避坑>
最终解决方案：<如何解决的>
经验总结：<一句话提炼>
<为每个难点重复>
7. 使用的工具与插件
| 工具/库 | 版本 | 用途 | 文档链接 |
|---|---|---|---|
| <工具名> | <版本> | <用途> | <链接> |
8. 与 AI Agent 的交互亮点
<记录本次和 Claude Code / Codex 配合中值得记录的交互模式、有效的 prompt 技巧、AI 帮助解决了哪些具体问题>
9. 后续优化方向
| 优先级 | 方向 | 说明 | 预估工作量 |
|---|---|---|---|
| 🔴 高 | <方向> | <说明> | <小/中/大> |
| 🟡 中 | <方向> | <说明> | <小/中/大> |
| 🟢 低 | <方向> | <说明> | <小/中/大> |
10. 总结
<3-5 段总结性文字：这个项目最大的收获是什么、技术上学到了什么、下次会怎么做得更好>
---
## Step 3：生成 HTML 文档
参考 `assets/html_template.html` 的结构，将 Markdown 内容渲染为美观的 HTML。
**HTML 要求：**
- 自包含（所有 CSS/JS 内联，无外部依赖，可离线打开）
- 使用 [Mermaid.js CDN](https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js) 渲染图表
- 深色代码块（类似 GitHub 风格）
- 侧边栏目录导航（锚点跳转）
- 响应式布局，打印友好
- 顶部显示项目名称、日期、技术栈 Badge
具体 HTML 模板见 `assets/html_template.html`，基于此模板填充内容。
---
## Step 4：质量检查
生成完成后，自检以下项目：
- [ ] Mermaid 图表语法正确（至少包含架构图 + 函数调用图）
- [ ] 每个核心函数都有详解（不遗漏主要函数）
- [ ] 难点至少记录 1 条（如对话中有报错/重试，必须记录）
- [ ] 工具表格填写完整（版本号尽量准确）
- [ ] 后续优化方向至少 3 条
- [ ] HTML 可独立打开（无外部字体依赖以外）
- [ ] 文件命名：`retrospective_<snake_case_project_name>.md/html`
---
## Step 5：输出
1. 将 `.md` 和 `.html` 文件保存到 `/mnt/user-data/outputs/`
2. 使用 `present_files` 工具将两个文件呈现给用户
3. 简短说明："已生成项目复盘文档，MD 版本可直接提交到仓库，HTML 版本可在浏览器中查看完整图文报告。"
---
## 注意事项
- **不要照抄代码**：函数详解用文字描述逻辑，代码只做少量引用说明
- **Mermaid 语法**：使用 `graph TD`（流程图）和 `sequenceDiagram`（时序图），避免使用较新的语法以确保兼容性
- **如果项目很小**（<5个文件）：合并第4、5节，精简输出
- **如果项目很大**（>50个文件）：只对核心模块做函数详解，其他模块做摘要
- **语言**：默认用中文输出，除非用户指定英文