# Research Summary

> 科研项目技术总结笔记生成器（所有专业通用）。当用户说"写总结笔记"、"技术总结"、"科研总结"、"项目复现笔记"、"整理项目文档"、"写个总结"、"项目做完了写笔记"、"毕设总结"、"课程设计总结"、"实验总结"、"课题总结"时使用。适用于机械/土木/电气/化学/生物/材料/计算机/经管/社科等任何需要按导师要求产出可复现技术文档的专业。Skill 会通过主动提问引导用户完成 4 项交付物：技术总结笔记、过程记录文档、录屏、项目文件压缩包，并以"他人可按文档复现"为唯一验收标准反复迭代。

- Skill: `whynotzyp/research-summary` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add whynotzyp/research-summary`
- Raw SKILL.md: https://api.skillmd.com/api/skills/whynotzyp/research-summary/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: whynotzyp (https://skillmd.com/u/whynotzyp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/whynotzyp/research-summary

---


# 科研项目技术总结笔记

> **不要用于**：日常聊天总结、读书笔记、非技术类文字汇总、纯个人感想整理。本 Skill 仅适用于科研/工程类项目的技术文档产出。

## 核心目标

帮你在科研任务（软件、编程、仿真、实验等）完成后，按导师要求产出**可复现**的完整技术文档包。

**验收的唯一标准**：一个刚接触该方向的同学，不跟你交流，只靠文档、源码、参考链接，就能完整复现你的项目。

如果做不到，就继续改文档，直到能做到为止。

## 交付物清单

每次完整产出包含 4 件东西：

| # | 交付物 | 说明 |
|---|--------|------|
| 1 | **技术总结笔记** (.md 或 .docx) | 软件环境及版本、代码开发步骤、编程调试流程、参考链接 |
| 2 | **过程记录文档** (.md) | 逐条列出学习和编写过程中遇到的问题和解决方案 |
| 3 | **运行调试录屏** (.mp4，可选) | 完整的运行/调试过程录像 |
| 4 | **关键代码源文件压缩包** (.zip) | 命名规范、关键处有详细注释、代码开头注明可靠性测试内容 |

## 工作流程

分 6 个阶段，按顺序推进。每个阶段结束时确认用户满意后再进入下一阶段。

---

### 阶段 0：项目摸底

先通过提问搞清楚项目的全貌。不要跳过，不要假设。

**必须问到的问题**（逐一问，不要一次抛太多）：

1. 这个项目的名称是什么？一句话描述它做什么。
2. 用到了哪些软件/工具/编程语言？版本号是什么？
3. 项目有没有参考链接（教程、文档、博客、论文等）？
4. 项目代码现在在哪个目录？
5. 这个项目你从开始做到现在经历了哪些关键步骤？（按顺序简述即可）

将用户回答整理成项目概况，让用户确认无误后再进入阶段 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。

**录屏内容清单**：

1. 从空环境开始演示（或从当前环境开始，但要口述清楚前置条件）
2. 展示项目文件结构
3. 运行/启动项目全过程
4. 展示运行结果
5. 如果有典型调试场景也录一段

**录屏要求**：
- 建议 OBS Studio（免费）或系统自带录屏
- 全程录音，用中文讲解每一步在做什么
- 分辨率至少 720p，确保代码文字清晰
- 如果有报错修复过程，保留原始录屏不用剪辑

输出录屏指导后，告诉用户："录好后把文件路径给我，我帮你检查内容是否覆盖了所有关键步骤。"

---

### 阶段 4：代码检查与打包（交付物 4）

在打包之前，检查代码质量。

**检查项**：

1. **命名规范**：文件名、变量名、函数名是否规范？是否用拼音或不一致的中英混合？
2. **注释完整性**：每个关键函数/代码块是否都有注释？注释是否解释了"为什么"而不只是"是什么"？
3. **可靠性测试注释**：代码文件开头是否用注释形式写明了做过哪些可靠性测试？
   - 例如：
   ```
   ## 可靠性测试记录
   # 1. 连续运行 30 分钟无报错
   # 2. 测试了 X/Y/Z 三种输入情况，输出均符合预期
   # 3. 反复启停 20 次无异常
   # 4. 测试了边界情况：空输入、超长输入、特殊字符输入
   ```
4. **无硬编码敏感信息**：检查是否有密钥、token、密码等（如有则提醒用户移除）
5. **文件结构清晰**：源码、数据、配置是否分目录存放

检查完毕后，先尝试用 `scripts/pack.py` 自动打包：`python scripts/pack.py "项目目录" "项目名-技术文档.zip"`（会自动排除 `.git`、缓存文件等）。如果项目没有 Python 环境，则手动指导用户用 `Compress-Archive` 打包。

```powershell
Compress-Archive -Path "项目目录" -DestinationPath "项目名-技术文档-日期.zip"
```

或手动指导用户打包。

---

### 阶段 5：复现验证

这是最后也最重要的环节。你作为"新手"角色，按照技术总结笔记一步步走一遍，验证是否真的可以复现。

**检查方法**：

1. 逐条阅读阶段 1 产出的技术总结笔记
2. 对照代码压缩包检查：
   - 笔记里提到的每个文件，压缩包里都有吗？
   - 笔记里写的每一步命令，按顺序执行能走通吗？
   - 笔记里提到的软件版本和实际代码需要的版本一致吗？
   - 参考链接是否都能访问？
3. 对照过程记录文档检查：
   - 如果遇到笔记里描述的问题，过程记录里有解决方案吗？
4. 指出所有"这里新人会卡住"的位置，要求用户补充说明

**不可复现 = 不合格**。指出具体哪里卡住了，回到对应阶段修改，直到通过验证。

---

### 阶段 6：输出最终交付清单

所有内容确认无误后，输出最终清单：

```
## 交付清单

| # | 交付物 | 文件 | 状态 |
|---|--------|------|------|
| 1 | 技术总结笔记 | xxx.md | ✅ |
| 2 | 过程记录文档 | xxx.md | ✅ |
| 3 | 运行调试录屏 | xxx.mp4 | ✅ / ⏭️跳过 |
| 4 | 代码源文件压缩包 | xxx.zip | ✅ |

项目名称：XXX
完成日期：YYYY-MM-DD
```

提醒用户将所有文件发给导师审阅。

---

## 行为准则

- **不要跳过任何阶段**。即使项目很小，也要走完 6 个阶段。
- **每次只问 1-3 个问题**，不要一次性抛出一堆问题。
- **用户回答模糊时追问**。"环境没问题" → "具体 Python 版本是多少？pip list 里关键库的版本号是什么？"
- **宁可多问一句，不要默认一个假设**。
- **代码检查时发现问题直接指出**，不要因为"项目小"就降低标准。
- **复现验证时不要放水**。卡住就是卡住，指出来，让用户补充。
- 如果用户说"差不多了吧"，反问："如果明天有个新来的同学只看你的文档来做这个项目，他能不看你的消息就完成吗？"