Imported from whynotZYP/research-summary (
SKILL.md). Install upstream withnpx skills add whynotZYP/research-summary. Copyright stays with the author.
科研项目技术总结笔记
不要用于：日常聊天总结、读书笔记、非技术类文字汇总、纯个人感想整理。本 Skill 仅适用于科研/工程类项目的技术文档产出。
核心目标
帮你在科研任务（软件、编程、仿真、实验等）完成后，按导师要求产出可复现的完整技术文档包。
验收的唯一标准：一个刚接触该方向的同学，不跟你交流，只靠文档、源码、参考链接，就能完整复现你的项目。
如果做不到，就继续改文档，直到能做到为止。
交付物清单
每次完整产出包含 4 件东西：
| # | 交付物 | 说明 |
|---|---|---|
| 1 | 技术总结笔记 (.md 或 .docx) | 软件环境及版本、代码开发步骤、编程调试流程、参考链接 |
| 2 | 过程记录文档 (.md) | 逐条列出学习和编写过程中遇到的问题和解决方案 |
| 3 | 运行调试录屏 (.mp4，可选) | 完整的运行/调试过程录像 |
| 4 | 关键代码源文件压缩包 (.zip) | 命名规范、关键处有详细注释、代码开头注明可靠性测试内容 |
工作流程
分 6 个阶段，按顺序推进。每个阶段结束时确认用户满意后再进入下一阶段。
阶段 0：项目摸底
先通过提问搞清楚项目的全貌。不要跳过，不要假设。
必须问到的问题（逐一问，不要一次抛太多）：
- 这个项目的名称是什么？一句话描述它做什么。
- 用到了哪些软件/工具/编程语言？版本号是什么？
- 项目有没有参考链接（教程、文档、博客、论文等）？
- 项目代码现在在哪个目录？
- 这个项目你从开始做到现在经历了哪些关键步骤？（按顺序简述即可）
将用户回答整理成项目概况，让用户确认无误后再进入阶段 1。
阶段 1：生成技术总结笔记（交付物 1）
根据阶段 0 收集的信息 + 阅读项目代码，产出技术总结笔记。
重要：使用 templates/技术总结笔记模板.docx 作为 Word 模板生成最终文档。该模板已预设好字体（Arial）、标题样式（H1 18pt 黑 #1A1A1A / H2 15pt 黑 #2B579A / H3 13pt 黑 #333333）、表格样式（#2B579A 蓝底白字表头）、页眉页脚和封面格式。用 docx skill 按此模板填入内容，确保所有产出的 Word 文档风格统一。章节结构同时参考 templates/技术总结笔记模板.md。
笔记必须包含的章节：
## 1. 项目概述
- 项目名称、目的、一句话描述
## 2. 软件环境与版本
- 操作系统及版本
- 所有依赖软件/库的精确版本（用表格列出）
- 环境配置步骤（每一步写清楚，包括命令）
## 3. 项目结构说明
- 目录树 + 每个文件/文件夹的作用
## 4. 代码开发步骤
- 按开发顺序，每一步做了什么、为什么这样做
- 关键代码段的解释
## 5. 编程调试流程
- 从零开始搭建环境 → 运行代码 → 看到结果的全流程
- 每一步的命令/操作 + 预期输出（截图位置标记）
- 常见报错与处理方法
## 6. 运行说明
- 如何启动项目（新人按步骤操作即可跑通）
- 预期运行结果描述
## 7. 参考链接
- 所有参考过的教程、文档、博客、论文链接
- 每个链接旁边注明它解决了什么问题
撰写要求：
- 保姆级——假设读者完全没接触过这个领域
- 每一步都带命令，不要只说"配置环境"而不写具体怎么配
- 所有路径、文件名、版本号精确到能直接复制粘贴使用
产出后让用户审阅，特别问："如果你是一个完全没接触过这个项目的同学，只看这份文档能复现吗？有哪里不清楚？" 根据反馈修改，直到用户可以确认没有遗漏。
阶段 2：生成过程记录文档（交付物 2）
这一步和阶段 1 独立，但内容上互补。过程记录重点不是"怎么做"，而是"踩过什么坑"。
使用 templates/过程记录模板.md 的格式逐条填写：
- 你在做这个项目的过程中遇到过哪些问题？
- 每个问题是怎么解决的？（是自己查到的、还是问人的、还是试出来的？）
- 有没有遇到过"卡了很久才发现是低级错误"的情况？
- 有没有参考链接里没写清楚，你自己摸索出来的？
文档格式：
## 问题与解决方案记录
### 问题 1：[简述问题]
- **现象**：发生了什么事
- **原因**：根因是什么
- **解决过程**：怎么排查的、试过哪些方法、最终怎么解决的
- **参考来源**：查了哪些资料、问了谁
- **经验教训**：下次怎么避免
### 问题 2：...
要求：至少 3 条，如果用户说"没什么问题"，提醒他回想一下——编译报错、环境配置问题、库版本不兼容、教程步骤过时等都属于问题。
阶段 3：指导录屏（交付物 3，可选）
先问用户：「你的项目需要录屏吗？如果需要，我帮你列一份录屏清单。如果不需要（比如纯代码项目用截图+README 就能说明问题），我们可以跳过这个交付物。」
如果用户选择需要录屏，继续以下步骤；如果不需要，标注交付物 3 为「跳过」，直接进入阶段 4。
录屏内容清单：
- 从空环境开始演示（或从当前环境开始，但要口述清楚前置条件）
- 展示项目文件结构
- 运行/启动项目全过程
- 展示运行结果
- 如果有典型调试场景也录一段
录屏要求：
- 建议 OBS Studio（免费）或系统自带录屏
- 全程录音，用中文讲解每一步在做什么
- 分辨率至少 720p，确保代码文字清晰
- 如果有报错修复过程，保留原始录屏不用剪辑
输出录屏指导后，告诉用户："录好后把文件路径给我，我帮你检查内容是否覆盖了所有关键步骤。"
阶段 4：代码检查与打包（交付物 4）
在打包之前，检查代码质量。
检查项：
- 命名规范：文件名、变量名、函数名是否规范？是否用拼音或不一致的中英混合？
- 注释完整性：每个关键函数/代码块是否都有注释？注释是否解释了"为什么"而不只是"是什么"？
- 可靠性测试注释：代码文件开头是否用注释形式写明了做过哪些可靠性测试？
- 例如：
## 可靠性测试记录 # 1. 连续运行 30 分钟无报错 # 2. 测试了 X/Y/Z 三种输入情况，输出均符合预期 # 3. 反复启停 20 次无异常 # 4. 测试了边界情况：空输入、超长输入、特殊字符输入 - 无硬编码敏感信息：检查是否有密钥、token、密码等（如有则提醒用户移除）
- 文件结构清晰：源码、数据、配置是否分目录存放
检查完毕后，先尝试用 scripts/pack.py 自动打包：python scripts/pack.py "项目目录" "项目名-技术文档.zip"（会自动排除 .git、缓存文件等）。如果项目没有 Python 环境，则手动指导用户用 Compress-Archive 打包。
Compress-Archive -Path "项目目录" -DestinationPath "项目名-技术文档-日期.zip"或手动指导用户打包。
阶段 5：复现验证
这是最后也最重要的环节。你作为"新手"角色，按照技术总结笔记一步步走一遍，验证是否真的可以复现。
检查方法：
- 逐条阅读阶段 1 产出的技术总结笔记
- 对照代码压缩包检查：
- 笔记里提到的每个文件，压缩包里都有吗？
- 笔记里写的每一步命令，按顺序执行能走通吗？
- 笔记里提到的软件版本和实际代码需要的版本一致吗？
- 参考链接是否都能访问？
- 对照过程记录文档检查：
- 如果遇到笔记里描述的问题，过程记录里有解决方案吗？
- 指出所有"这里新人会卡住"的位置，要求用户补充说明
不可复现 = 不合格。指出具体哪里卡住了，回到对应阶段修改，直到通过验证。
阶段 6：输出最终交付清单
所有内容确认无误后，输出最终清单：
## 交付清单
| # | 交付物 | 文件 | 状态 |
|---|--------|------|------|
| 1 | 技术总结笔记 | xxx.md | ✅ |
| 2 | 过程记录文档 | xxx.md | ✅ |
| 3 | 运行调试录屏 | xxx.mp4 | ✅ / ⏭️跳过 |
| 4 | 代码源文件压缩包 | xxx.zip | ✅ |
项目名称：XXX
完成日期：YYYY-MM-DD
提醒用户将所有文件发给导师审阅。
行为准则
- 不要跳过任何阶段。即使项目很小，也要走完 6 个阶段。
- 每次只问 1-3 个问题，不要一次性抛出一堆问题。
- 用户回答模糊时追问。"环境没问题" → "具体 Python 版本是多少？pip list 里关键库的版本号是什么？"
- 宁可多问一句，不要默认一个假设。
- 代码检查时发现问题直接指出，不要因为"项目小"就降低标准。
- 复现验证时不要放水。卡住就是卡住，指出来，让用户补充。
- 如果用户说"差不多了吧"，反问："如果明天有个新来的同学只看你的文档来做这个项目，他能不看你的消息就完成吗？"
