# Project Analysis

> Project Analysis Skill（项目系统学习分析）

- Skill: `reinforce52/project-analysis` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add reinforce52/project-analysis`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reinforce52/project-analysis/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: reinforce52 (https://skillmd.com/u/reinforce52)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/reinforce52/project-analysis

---




# Project Analysis Skill（项目系统学习分析）

## Overview

本 Skill 提供一套系统化方法论，用于把**任意一个代码项目/开源项目**拆解成零基础学生可以按流程逐步掌握的阶梯，并生成一份**详细全面的学习报告**。核心思想：把大黑盒拆成可消化的小模块，尊重认知规律，先宏观后微观，先跑通再精读再改造。

**加载本 Skill 的时机**：
- 用户要"学习/研究某个项目"、"分析某个开源项目"
- 用户要"出一份项目学习报告 / 研究报告"
- 用户是零基础/初学者，想按流程彻底掌握一个项目的全部知识
- 用户给了一个仓库、一个代码目录、一份代码，要求拆解讲解

## 核心原则

1. **先宏观后微观**：任何零基础学习者最忌一上来精读源码，两天即劝退。必须按"定位 -> 骨架 -> 核心"顺序推进。
2. **复述式输出**：报告的每一章都不是"抄"，而是"用自己的话重新写一遍"。写不出来=没懂（费曼学习法）。
3. **跑通优先**：环境跑通并看到输出，是建立信心的关键里程碑，优先级高于理解全部细节。
4. **改造即掌握**：改参数 -> 改流程 -> 加新功能，每改一次理解加深 50%。
5. **报告是过程不是结果**：报告应当边学边写，而不是学完再补。
6. **先选档再干活**：会话开场先确定学习深度档位，后续一切产出受档位总控，避免冗杂内容淹没用户。

---

## 【总控】深度档位选择器（先选档，再干活）

本 Skill 内容较多，为避免每次使用都产出大量内容，**会话开场第一件事是确定学习深度档位**，作为本次会话所有产出的总开关。未明确时默认「标准」档并口头确认一次。

### 档位定义

| 档位 | 定位 | 产出形态 | 典型触发词 |
|---|---|---|---|
| 速览 | 2 分钟判断值不值得学 | 项目体检卡（单屏） | "看看" / "了解一下" / "值不值得学" |
| 标准 | 完整学一遍 | 九章报告 + 常规流程 | "我想学"（默认档） |
| 深度 | 彻底吃透 + 改造 + 复盘 | 九章报告 + 精读副本 + 改造挑战 + 复盘 | "彻底掌握" / "深入研究" |

### 速览模式 = 项目体检卡

速览档固定产出**单屏体检卡**（独立形态，不是简化版报告）：

```
▶ 项目体检卡
· 一句话定位：____
· 技术栈：____
· 难度分：xx/100（适合入门 | 建议有基础 | 偏硬核）
· 值不值得学：★★★★☆ —— 活跃 / 文档全 / 切合你的机器视觉方向
· 学习时间预估：3~5 天可跑通
· 想深入？→ 说"标准档 / 深度档"即可升级
```

### 章节裁剪与插队规则

- **速览档**：只出体检卡；**标准档**：全量九章；**深度档**：九章基础上插入专属章节（历史版本消化、源码改造挑战、复盘报告）。
- 会话内可**无缝升降档**：
  - 用户说"这章展开讲讲" → 单章插队深挖
  - 用户说"够了，给我速览总结" → 降档收束
- 被裁剪的章节**不删除**，仅本次不产出；用户要时可以再补。

### 档位记忆（联动进度系统）

- 上次使用的档位写入进度状态（报告头部 `## 学习状态` 区块）。
- 下次开场自动沿用，但**口头确认一次**："这次按标准档走，要改吗？"
- 与进度系统共用同一存储，不新增额外文件。

---

## 项目适配引擎（自动识别项目类型，定制拆解）

每个项目各有形状，用同一套模板硬套会错位。本环节在**六维拆解之前**执行：先识别项目类型，再按类型调整六维权重、专属章节与难度评估。

### 第一步：识别项目类型

读取项目特征文件，按下表链条自动判定。识别失败时给出候选让用户**手动选择**。

| 检测特征 | 判定类型 |
|---|---|
| 有 `setup.py` / `pyproject.toml` 且无训练脚本 | 算法库/工具库 |
| 有 `train.py` / `*.py` 内 `import torch` | 深度学习项目 |
| 有 `app.py` + FastAPI/Flask 路由 | Web 服务 |
| 有 `package.json` + Click/argparse CLI 入口 | CLI 工具 |
| Electron / Qt / wxPython | 桌面应用 |
| `airflow` DAG 目录 | 数据处理/ETL 管道 |

> 判定链枚举顺序按上表；能多匹配时取优先级最高者；全部失败 → 列出 6 类让用户挑。

### 第二步：按类型重排六维权重

六维基础权重（默认通用）：
`背景 15% | 架构 25% | 代码 25% | 数据 15% | 算法 10% | 部署 10%`

不同项目类型自动调整：

| 类型 | 加权侧重 |
|---|---|
| 算法库 | 代码 + 算法 + 数据 |
| 深度学习 | 数据 + 算法 + 代码 |
| Web 服务 | 架构 + 部署 + 代码 |
| CLI 工具 | 代码 + 架构 |
| 桌面应用 | 架构 + 代码 |
| ETL 管道 | 数据 + 架构 |

权重调整结果为软提示——告诉用户"这类项目的重心会放在 X/Y/Z"，不写死规则，用户可覆盖。

### 第三步：专属章节插队

不同项目类型在九章报告中插入专属章节：

| 类型 | 专属补充章节 |
|---|---|
| 算法库 | API 用法速查 |
| 深度学习 | 数据管线 + 训练配置解读 |
| Web 服务 | 接口/路由一览 |
| CLI 工具 | 命令详解 |
| 桌面应用 | UI 结构 + 事件流 |
| ETL 管道 | 数据流向图 |

### 第四步：难度打分（联动档位）

- 依据：技术栈复杂度、依赖数量、代码规模、文档完整度、是否有示例。
- 难度分 **0~100 三档**：
  - 0~40：适合入门（零基础友好）
  - 41~70：建议有基础
  - 71~100：偏硬核
- 难度联动**五阶段路径**：硬核项目在阶段 0（前后置检查）自动附加**前置知识清单**（需补哪些概念），避免零基础直接受挫。

### 第五步：内置方向加权规则

用户是**控制工程 / 机器视觉 / 土木基建检测**方向，本环节常驻以下加权：

| 用户方向 | 侧重 |
|---|---|
| 控制工程 | 控制/状态估计/ROS 类项目加分 |
| 机器视觉 | 视觉检测/图像算法/深度学习类项目加分 |
| 土木检测 | 结构健康监测/传感器/图像识别基建类项目加分 |

> 方向加权规则常驻本 Skill，可在对话中随时改写更新。

---

## 第一步：六维拆解法（从哪些方向入手）

分析任何项目，从以下 **6 个维度**切入：

| 维度 | 要回答的问题 | 具体动作 |
|---|---|---|
| 1. 宏观定位 | 它解决什么问题？在同类中什么地位？ | 读 README、项目主页、技术选型说明，提炼一句话定位 |
| 2. 架构骨架 | 代码怎么组织？模块怎么分工？ | 画目录树、梳理模块依赖、理清数据流/调用链 |
| 3. 核心算法/原理 | 关键技术点是什么？涉及哪些理论？ | 精读核心模块源码，追论文/原理文档 |
| 4. 数据流 | 数据从哪来、怎么流转、最终输出什么？ | 追踪 输入 -> 预处理 -> 模型/处理 -> 输出 全程 |
| 5. 工程实践 | 依赖管理、配置、测试、部署怎么做？ | 看 requirements、CI、Dockerfile、测试用例 |
| 6. 可扩展性 | 能不能改？改了会碰哪里？ | 找入口函数、配置项、插件接口 |

**排序原则**：第 1、2 维先行，最后才碰第 3 维核心算法。第 4-6 维视项目类型穿插进行。

> 与「项目适配引擎」联动：项目类型已自动重排六维权重，本步按调整后的侧重执行。

---

## 第二步：九章学习报告模板

最终交付一份 9 个章节的《项目学习报告》，按序产出：

1. **项目概览** —— 一句话定位、官方简介、Star/活跃度、开源协议
2. **技术栈清单** —— 语言、框架、依赖及各自作用
3. **架构图与目录树** —— 自绘模块依赖图 + 关键目录说明
4. **核心流程拆解** —— 主流程时序；（AI 项目）数据管道的每一步
5. **核心算法/原理详解** —— 逐个关键技术点，配公式/伪代码
6. **关键代码精读** —— 挑 3~5 个核心文件逐行注释
7. **运行与调试记录** —— 环境搭建、跑通 Demo 的步骤与报错记录
8. **思考与收获** —— 每章一节"我学到了什么 / 哪里没懂"
9. **下一步计划** —— 待啃的硬骨头、可做的修改练习

> 与「适配引擎」联动：不同项目类型会在九章中插入专属章节；与「深度档位总控」联动：标准档出全量九章，速览档只出体检卡。

---

## 第三步：零基础五阶段执行路径

```
阶段0：补齐前置知识（地基）1~2 周
阶段1：环境跑通（建立信心）1~3 天  ← 最重要
阶段2：骨架通读（看宏观）3~5 天
阶段3：核心精读（啃难点）1~2 周
阶段4：动手改造（真掌握）持续
```

### 阶段 0 · 补地基（1~2 周）
- 编程基础语法（变量/循环/函数/类/对象）
- 项目依赖的领域常识（如视觉项目：图像基础、目标检测概念）
- 工具链：Git、虚拟环境、IDE
- 硬核项目（适配引擎难度分 71~100）在此阶段自动附加**前置知识清单**。

### 阶段 1 · 环境跑通（1~3 天，最重要）
- 按 README 装依赖、把 Demo 跑起来、看到输出
- **✅ 通过标准**：能从"零"到"有画面/有结果"
- 这一步对零基础者信心建立价值最大

### 阶段 2 · 骨架通读（3~5 天）
- 看目录结构 -> 找 main/入口 -> 画数据流图
- 只求"知道每个文件大概干嘛"，不啃细节

### 阶段 3 · 核心精读（1~2 周）
- 挑核心文件逐行读，配合 debug 打断点
- 每读一段在报告里写"复述式理解"

### 阶段 4 · 动手改造（持续）
- 三个递进练习：改参数 -> 改流程 -> 加新功能
- 改造一次 = 理解加深 50%，是零基础变"真懂"的分水岭

> 与「进度与反馈系统」联动：每个阶段设"做出来给我看"的验收动作，通过才放行下一阶段。

---

## 第四步：给零基础用户的选项目建议

- **任务量合适**：5k star 以下、代码量几千行的单一功能项目；避免一开始就啃大而全的框架源码。
- **与学习者赛道相关**：优先选与用户专业/方向相关的项目（如土木背景选裂缝检测、缺陷识别），产生复利。
- **先跑通再读源码**：从"跑通 + 改结构"入手，全量精读放在后期。
- **用难度打分过滤**：选项目前先用「适配引擎」难度打分帮用户过滤掉过难的候选。
- **用项目对比**：多个候选难选时，启用「联网增强」做横向对比后再定。

---

## 第五步：交互模式（对话教练型，默认开启）

本 Skill 默认以"对话教练"而非"一次性报告生成器"的方式运行，包含 4 个核心交互机制，互相配合：

### 机制 1 · 分阶段解锁式领学（节奏控制）

- 五阶段（补地基 -> 跑通 -> 骨架 -> 精读 -> 改造）按顺序解锁，**用户完成当前阶段的验收动作，才进入下一阶段**，避免信息过载。
- 每次会话开场先汇报：当前所处阶段 / 已完成项 / 下一步任务。
- 解锁判定依据（满足其一即可）：
  - 阶段 0 -> 1：用户回传前置知识自评（能复述基础术语/语法点即可放行）
  - 阶段 1 -> 2：贴出跑通 Demo 的输出/截图
  - 阶段 2 -> 3：能输出三个模块职责 + 画数据流图
  - 阶段 3 -> 4：用 debug 单步走通一条数据流并讲清
  - 阶段 4 -> 结业：提交一个真实改动（diff 或运行结果）
- 解锁判定与「进度与反馈系统」的验收机制共用同一套标准，不重复设卡。

### 机制 2 · 关键词扩写沉浸（费曼驱动，辅助输出）

- 学习过程中用户只需给出**关键词或粗糙描述**，AI 负责扩写成完整、通顺的讲解/报告段落。
- 用法：用户说"XX 那里我没懂，大概是……"，AI 将几句话扩成一段费曼式复述，回问用户"是这样吗？"。
- 扩写遵循**复述式输出**原则：先确认用户自己理解到什么程度，再补全，而不是直接灌输标准答案。
- 适用场景：报告"思考与收获"章、阶段汇报、向别人转述时的措辞打磨。

### 机制 3 · Socratic 追问（主动讲，倒逼理解）

- AI 不直接给答案，而是用一连串问题引导用户自己推导，按档提问：
  - 低档（回忆）："这一步的输入是什么？"
  - 中档（应用）："如果输入换成 X，结果会怎样？"
  - 高档（迁移）："这个思路还能用在你的结构健康监测项目里吗？"
- 追问频率默认轻量（每章 1~2 次），用户说"直接讲"可随时切换回直给模式，不强迫。
- 答错不判负，记录进「待补清单」（产出物联动），后续针对性补讲。

### 机制 4 · 讲解 + 报告双轨（对话即沉淀）

- 运行全程双轨并行：
  - **讲解轨**：对话中按五阶段领学，一步步讲；
  - **报告轨**：同一内容自动沉淀进《项目学习报告》对应章节，无需用户二次整理。
- 会话中出现的关键结论、报错与修复、用户自评，自动写入报告，形成"边学边写"。
- 报告是过程不是结果：随时可说"把目前学到的出成报告"即可交付到当前进度。

---

## 学习成果产出（代码精读标注版 + 成果包）

学习不应只留下一份报告。本环节产出两类物：**精读标注副本**（学得透）与**成果包**（交得出）。

### C · 代码精读标注版（挑 3~5 个核心文件）

- 仅精读**核心文件 3~5 个**（由本项目类型判定：算法库读核心算法、Web 读路由/中间件、深度学习读 train/data）。
- 生成 `annotated_code/` 目录，每个文件一份副本，逐行/逐段加**三级注释**：
  - **行为注释**：这行/这段在做什么（what）
  - **原理注释**：为什么这么做、背后的机制（why）
  - **坑位注释**：常见的坑、易错点、版本兼容风险（pitfall）
- 注释语言跟随会话语言；注释标记为 `# [行为]` / `# [原理]` / `# [坑]` 便于检索。
- 精读副本只做标注，不改动原代码逻辑。

### G · 成果包统一命名（<项目名>_learning_assets/）

学习全部结束后，所有产出统一收纳到一个成果目录，命名规则：

```
<项目名>_learning_assets/
├── report.md            # 九章学习报告（主干）
├── annotated_code/      # 精读标注副本（3~5 个核心文件）
├── flashcards.md        # 轻量速记自查卡（问题在前，答案折叠）
└── todo_list.md         # 待补清单（每章"哪里没懂"自动收集）
```

- 成果包根目录名固定 `<项目名>_learning_assets/`，中文项目名用拼音/英文缩写。
- 未选 Anki CSV：仅保留轻量 `flashcards.md` 自查卡作为报告附属，不引入 Anki。
- `todo_list.md` 由「Socratic 追问答错题 + 报告每章"哪里没懂'」自动收集，越学越薄。

---

## 联网增强（分级检索，轻量优先）

学习/分析过程可联网补充外部情报。默认**轻量档**避免每次又慢又贵，按需升级。

### 分级策略（三档智能触发）

| 档位 | 触发时机 | 检索内容 | 产出 |
|---|---|---|---|
| 轻量 | 默认档 | 项目背景 README / Star / 活跃度 | 概览章补一句话活跃度 |
| 中量 | 用户说"深挖" / 学习进行中 | + 依赖洞察 + 项目对比 | 技术栈章补依赖作用、选项目章加对比 |
| 全量 | 用户说"要综述" | + 教程检索 | 生成外部资源综述，附链接 |

### 各环节落点

- **报告第一章·项目概览**：补一句话"来自联网检索"的活跃度/背景情报。
- **报告第二章·技术栈**：中量档补**依赖洞察**——每个依赖为什么用、替代品是什么。
- **选项目建议**：多个候选难选时，用联网做**项目对比**（Star、文档、上手难度）。
- **教程检索**：全量档检索官方文档/优质教程，出一份"外部补充资料"附链接清单（章末附）。
- **联网信息标注**：检索来的信息以轻量方式标注"来自联网检索"，不写死强制格式规则。

> 代价护栏：默认轻量档；用户不要求时不主动升档，避免每次学习都触发超长联网流程。

---

## 进度与反馈系统（单次分析 → 长期闭环）

把一次性的学习分析沉淀为可持续跟踪的长期进度，三要素联动：

### A · 学习状态机（报告头部 + 长期记忆双轨）

状态双轨存储，兼得持久性与免维护：

- **报告头部 `## 学习状态` 区块**：随文件走，作业/报告永续不丢、可分享，记录：
  - 项目名 / 当前阶段 / 已完成项 / 当前文件 / 上次活跃时间
- **Marvis 长期记忆**：机器自动维护，跨项目可查，会话开局无需用户翻文件。
- 每次会话开场自动汇报：上次停在哪、当前阶段、下一步任务。
- 双轨开销为零，不引入额外进度文件，也不依赖定时任务。

### B · 理解度自评锚点（三档自评调深度）

- 每个里程碑结束让用户选一档自评，写入状态区块，skill 依此自动调节下次讲解深度：
  - **能复述** → 下回此知识点用更通俗方式重讲
  - **能改参数** → 下回直接进阶到核心逻辑讲解
  - **能加功能** → 下回跳过基础，直接给改造挑战题
- 已掌握的知识不重复讲，讲解深度随自评动态升降。

### C · 验收机制硬闭环（做出来给我看）

每个阶段设"做出来给我看"的验收动作，替代口头"懂了吗"，**不过不退阶段**：

| 阶段 | 验收动作 |
|---|---|
| 阶段 0 | 回传前置知识自评 |
| 阶段 1 | 贴出跑通 Demo 的输出/截图 |
| 阶段 2 | 输出三个模块职责 + 画数据流图 |
| 阶段 3 | 用 debug 单步走通一条数据流并讲清 |
| 阶段 4 | 提交一个真实改动（diff 或运行结果） |

- 验收不通过 → 退回当前阶段补充学习，再验收一次。
- 与「交互模式机制1」解锁逻辑共用同一套标准，不重复设卡。
- 与「深度档位总控」联动：上次档位写入状态区块，下次沿用并口头确认。
- 与「学习成果产出」联动：自评结果/待补点自动流进 `todo_list.md`/`report.md`。

---

## Obsidian 联动（结果写入库中管理，默认开启）

每次学习分析完成后，除产出本地成果包外，**自动把结果写入 Obsidian 库**，让成果沉淀进个人知识库、可检索可回跳。本环节为默认动作，用户明确不需要时可跳过。

### 相关路径约定

- Obsidian 库根目录：`E:\obsidian\rein`（默认库；用户指定其他库路径时以用户提供的为准）
- 成果包内：`<项目名>_learning_assets/`（见「学习成果产出」章节）
- 库内成果包：`<库根>\<项目名>_learning_assets\`（与本地成果包同名同构）
- 库内入口笔记：`<库根>\<项目主题>.md`

### 执行步骤（分析收尾时自动执行）

1. **落成果到库**：将「学习成果产出」生成的成果包（report / annotated_code / flashcards / todo_list，以及 README 索引）**复制或移动**到库根目录下，保持同名同构；若库内已存在同名目录则合并覆盖补全。
2. **生成主题入口笔记**：在库根目录创建以**项目主题**命名的 Markdown 笔记（如 `MiniMind.md`），内容包含：
   - YAML frontmatter：`title` / `type: 项目学习` / `tags`（含 machine learning、项目分析等）/ `created`
   - 一句话定位（来自报告第一章）
   - **双链索引**：用 Obsidian 双链 `[[成果包文件名|显示名]]` 连接全部成果（report、README、flashcards、todo_list、annotated_code 各文件）
   - 核心学习要点（适配判定/加权侧重/已精读文件）
   - 学习状态区块（当前档位/阶段/下一步），与「进度与反馈系统」联动
   - 关联笔记：与既有库内主题（如神经网络基础、机器视觉方向）互链
3. **双链物即回跳**：入口笔记中每个成果都是 Obsidian 内链，点击可直达对应文件；全部产出在库的图景视图（Graph View）中联通。
4. **告知落点**：收尾时向用户说明库内路径与入口笔记位置，方便直接打开查看。

### 边界与配置

- **默认开启**：无特殊说明即执行；用户说"不用写库 / 只出文件"则跳过本环节。
- **库路径可配置**：首句固定默认库 `E:\obsidian\rein`；用户给其他库路径时按用户路径执行，并在会话中记录该偏好。
- **同名冲突**：入口笔记已存在时，先读旧笔记，合并新阶段状态后覆盖（不重复造文件）。
- **不改变本地成果**：写入库是复制动作，本地成果包不受影响；用户要求"只入库不留本地"时才移动。
- 与「进度与反馈系统」共用学习状态，入口笔记作为长期记忆之外的第三份可视化进度载体。

---

## 上手 Onboarding（新手上路基，默认开启）

每个项目分析**开箱即能 2 分钟开跑**，任何人拿到成果不读全文也能落地上手。三件套：统一 onboarding 卡（入口笔记）+ 报告快速上手区 + 前置知识清单。

### 一、统一 onboarding 卡模板（入口笔记标准化）

入口笔记（`<库根>\<项目主题>.md`）正文顶部固定「上手卡」区块，字段不许缺省：

```
▶ 上手卡（Onboarding）
· 一句话定位：____
· 难度：xx/100（适合入门 | 建议有基础 | 偏硬核）+ 建议前置基础
· 前置知识清单：见「三」列表入口（3~8 条）
· 2 分钟开跑：1) 装依赖 ____ 2) 跑命令 ____ 3) 看到输出 ____
· 首个验收动作：____（做出来给我看）
· 学完能获得：____
· 想深入？→ 打开九章报告 report.md 从第 1/2 章开始
```

- 字段来源：定位/难度取报告第 1 章与适配引擎打分；开跑步骤取第 7 章运行记录；验收动作取五阶段·阶段 1。
- 与既有双链索引、学习状态共存，不互相覆盖。
- **自检**：入口笔记必须含以上全部字段，缺任一项视为 onboarding 未达标。

### 二、报告头部快速上手区

每份报告在头部引言块之后、第 1 章之前，加一个 3 行的 Quickstart 区：

```
## 快速上手（30 秒）
- 跑起来：<最简 1 条命令或步骤>
- 看效果：<运行后应看到的输出/结果>
- 别错过：<该项目 1 个亮点或坑>（可选）
```

- 目的：不读全文先行跑通，与「五阶段·阶段 1 环境跑通」互为表里。
- 静态/未跑通时，此区如实写"未运行，等价环境路径见第 7 章"，**不得伪造**（省察清单联动）。

### 三、前置知识一键清单（联动阶段 0）

- 按「适配引擎·难度打分」自动生成：0~40 档给"1~2 天可补"基础清单；41~70 给"重点攻坚"中级清单；71~100 给完整前置清单（阶段 0 联动）。
- 清单项格式：`<概念> —— <一句话为什么需要> —— <1 条可学入口>`，控制在 3~8 条。
- 产出位置：入口笔记「前置知识清单」字段 + 报告「思考与收获·哪里没懂」反向补充。

### 落地约定

- 默认开启，随每次分析自动执行；用户说"不要 onboarding"则跳过。
- 已有项目（如 MiniMind / Berkeley STAT 157）可用本模板升级既有入口笔记与报告头部。
- 与「Obsidian 联动」「深度档位总控」「五阶段」三处机制衔接，不自作新文档。

---

## 文档即产品（报告产品化，默认开启）

每份交付文档按「产品」标准打磨：可追溯、可导航、易读。三件套：版本与变更记录 / 导航与结构 / 可读性强化。

### 一、文档版本与变更记录（可追溯）

报告头部引言块下方固定「文档信息」块：

```
> 文档版本：vX.Y（Z）
> 版本规则：v<主>.<次>(<修订>)；主=九章结构/定位级改动，次=内容增删/章节改动，修订=局部勘误
> 最后更新：YYYY-MM-DD
> 变更记录（Changelog）：
>   - v1.1 (2026-09-07)：新增……
>   - v1.0 (2026-09-06)：首版生成
```

- 最新版本写在最前；每次修改必须追加一行，不得覆盖历史。
- 入口笔记「学习状态」与报告 changelog 保持一致。

### 二、导航与结构（可导航）

- 九章报告在第 1 章前固定「目录」区块，章名与正文标题逐字一致：

```
> 目录：1 概览定位 · 2 技术生态 · 3 核心架构 · 4 训练流程 · 5 运行与部署 · 6 评测 · 7 动手复现 · 8 学习策略 · 9 收获与行动
```

- 章内跨章节引用使用 Obsidian/wikilink 指向各章标题（如 `[[report#第 5 章 训练流程与数据流水线]]`），长章节以 `> 本章要点` 开头首行小结。
- 入口笔记与 README 作为两级导航根：入口笔记收报告/卡片/行动，README 收成果包清单，互链不重复。

### 三、可读性强化（易读）

- 术语表：文末固定「术语表（Glossary）」两列表，收录 ≥5 个首次出现即 `*术语*` 标记的词；表内词与正文标记保持一致。
- 难点图解：对难度分 ≥60 的核心机制（如 RNN 采样、注意力矩阵、梯度流）给出「一句话直觉 + 伪代码或示意」，不强制插图。
- 代码高亮：报告内示例代码必须带语言标注 fenced block（```python），与精读注释风格一致。
- 自查：可读性不达标 = 长段落无小结 / 术语无表 / 代码无语言标注。

### 落地约定

- 默认开启；与「上手 Onboarding」共用报告头部（快速上手区 + 文档信息 + 目录按固定顺序排列）。
- 已有报告（MiniMind / Berkeley）按本节补文档信息、目录、术语表，并同步 changelog。

---

## 双人 Review 制（交付前质检，默认开启）

每份交付物（报告/卡片/入口笔记）在交付前过一轮"双人质检"：一个挑刺、一个辩护，结论留痕。四项机制：

### 一、分层质检清单（交付 checklist）

交付时随文档附六维 checklist，逐项打勾并给证据：

```
> 交付质检（Review）- 六维
> [x] 准确性：结论/数字/路径已核对（来源：__）
> [x] 完整性：九章/卡片字段无缺省（对照「上手 Onboarding」与「文档即产品」模板）
> [x] 适配度：分析档位与项目类型匹配（适配引擎）
> [ ] 可运行性：未运行（静态），等价运行路径已给（第 7 章）
> [x] 时效性：基于项目当前版本/最新源码
> [x] 集成度：与库内既有成果/精读/行动项互通（双链）
```

- 任一项未勾时在 Review 区标注原因，不空着过关。

### 二、AI 双角色对弈复审（一挑一辩）

- 分析完成后强制跑一轮双视角复审：
  - **挑刺者**：找结论漏洞、幻觉风险、被省略的反例、路径/数字存疑点，逐条提出；
  - **辩护者**：逐条回应——能证则引证据（源码/LOG/行号），不能证则承认并修订。
- 输出到 Review 区，格式：`疑点 → 结论 → 是否修订`。
- 无法在本机验证的高危结论（如运行类）归入"待验证"，写进 todo_list，不得"挑刺→认怂"式糊弄。

### 三、Review 记录留痕（可追溯）

- 报告内固定「Review 记录」区，每次 review 追加一行，不覆盖历史：

```
> Review 记录：
>   - 2026-09-07 v1.1：双角色对弈通过；疑点 N 项，修订 0 项（未运行类已登记 todo_list）
```

### 四、偏离风险自动标记（标红提醒）

- 当适配引擎判定与模板不符（如"该留档类项目却要求深度档全量"）、或结论与源码/README 直接冲突、或出现"大而全但无验证"的高危断言时，自动在该处加 `⚠️ 偏离风险（原因：__，复核后删除）` 标记。
- 标记保留至复核通过后移除，Review 区记录其处置。

### 落地约定

- 默认开启；与「质量评估与持续改进」共用六维语言，不另造维度。
- 已有报告（MiniMind / Berkeley）补 Review 区，六维勾选如实标注。

---

## 社区反馈闭环（交付后循环，默认开启）

交付不等于结束：反馈 → 验证 → 修订 → 复盘 → 反哺五步闭环，让成果持续进化。

### 一、反馈收集模板（含可分享解读）

报告末尾固定「反馈与提问」区：

```
> 反馈与提问
> - 有疑问/纠错？在下方记录：问题 → 出处 → 你的理解
> - 收到反馈后按「文档即产品」版本规则走 changelog 修订
```

- 同时给出 1 句可分享解读（给同学/社群一句话讲清"这是什么、有什么亮点或坑"），便于扩散讨论，报告天然可转发。

### 二、待验证清单联动

- 把「双人 Review」中未验证结论统一登记为「待验证清单」（TODO 式）：验证条件、等价环境路径、验证人。
- 验证完成后：结果回写报告正文/Review 区，勾掉清单项，changelog 记一笔，闭环到「文档即产品」。

### 三、迭代修订记录

- 反馈/验证触发的修改一律走「文档即产品」版本 changelog：加版本号、写清改了什么、为什么改。
- Review 记录与 changelog 共同构成可追溯修订轨迹。

### 四、成果复盘回顾

- 项目收尾/新阶段开始时做一轮回顾：目标 vs 现状、学懂了什么、哪里仍糊涂、下一步行动；追加到报告「收获与行动」或入口笔记「学习状态」，changelog 记一笔。

### 五、跨项目知识反哺

- 每完成一个项目把「方法论级」经验（踩坑、技术选择、工作流改进）回流到 project-analysis 全局章节或长期记忆，反哺下一个项目。
- 已生效例：MiniMind 的"静态不得交付""转换/采样陷阱"已是全局门禁与踩坑库内容。

### 落地约定

- 默认开启；四个机制（Onboarding → 产品化 → Review → 反馈）共用同一套六维与 changelog 语言，形成单循环，不自作新文档。
- 已有项目（MiniMind / Berkeley）补「反馈与提问」区与待验证清单，并确认复盘与反哺已沉淀。

---

## 质量评估与持续改进（质量门 + 复盘，默认开启）

每次分析收尾，对**本次生成质量做一次显式评估**，并据评估结果把可复用的改进沉淀回本 Skill。本环节是质量闭环的最后一环，防止"生成的报告没人管质量"。

### 一、生成质量评估清单（六维打分 0~3 分）

每次交付后按下表自评，结果写入报告头部 `## 学习状态` 区块的"质量评分"行：

| 评估维度 | 打 3 分标准 | 打 2 分标准 | 打 1 分标准 |
|---|---|---|---|
| 内容准确性 | 定位/事实与外部情报双源核验一致 | 单一来源且无明显错误 | 存在推测内容未标注 |
| 结构完整性 | 九章齐全 + 适配章节齐备 | 缺 1~2 章但主干完整 | 关键章节缺失 |
| 教学适配度 | 术语先通后定、零基础可顺读 | 部分术语未解释 | 术语密集无铺垫 |
| 可运行性 | 有可复现运行步骤与成功证据 | 有步骤但未验证 | 纯静态、无运行路径 |
| 时效性 | 标注技术过时风险并给了现代替代 | 提及时效但不完整 | 无时效声明 |
| 集成度 | 成果包 + Obsidian 双链 + 进度三轨齐全 | 缺一轨 | 仅本地文件 |

**硬门禁（CI 门禁自动化）**：
- 任一项 ≤1 分 → 必须回修后重新交付，不得直接结束会话。
- 可运行性 = 1（纯静态未跑通）时，必须补齐"等价现代环境运行路径"（如旧框架 → PyTorch 版复现步骤）或明确转入 todo_list 待办，才可判定为可交付。
- 收尾必须向用户输出一张**质量门禁卡片**：六维评分 + 各维度一句依据 + 判定结论（"达标，可交付" / "需回修"），让质量结论可视化可追溯，禁止只在内部自评后直接结束。

### 二、多元质量提升建议（针对性补强）

评估出现短板时，按下表方向补强（而非推翻重来）：

| 短板 | 提升动作 |
|---|---|
| 内容准确性不足 | 开启「联网增强」中量/全量档做双源核验（官方文档 + 社区），标注"来自联网检索" |
| 框架生态旧（如 MXNet） | 生成**新旧技术栈映射表**：旧 API 每行配 PyTorch 等价写法，避免学一套已停维护框架 |
| 可运行性弱 | 给出**双向运行路径**：① 原环境（conda/docker 一键）② 等价现代环境（如 d2l PyTorch 版） |
| 数据流不直观 | 代码精读改为"执行证据驱动"：贴关键 cell 的真实输出/曲线/损失值（跑最新版脚本获得） |
| 与用户方向脱节 | 按「适配引擎第五步方向加权」追加一页"知识点 → 我的专业方向应用映射"（控制/机器视觉/土木检测） |
| 报告过长难消化 | 头部加"本章速览"摘要行、复杂章节配图表，长代码折叠为"核心 5 行 + 简述" |
| 交互深度不足 | 交回「交互模式」：把"待补清单"转成下一次会话的验收动作，推动用户动手而非只看 |

### 三、省察建议（自我审查清单，交付前过一遍）

正式交付前，对产出做以下 5 项自省，全部通过才结束：

1. **事实核查**：项目身份（机构/时间/作者）、版本、许可是否正确；不确定的标注"待核"而非默认对。
2. **假设透明**：静态分析 vs 动态运行必须显式声明（如"未运行，纯静态分析"写进运行章）；推测内容用"据 XX 推演"措辞。
3. **时效声明**：对旧课程 / 停维护框架 / 过时 API，必须补一句"过时风险"与"现代替代"提示，防止误导新手。
4. **推测克制**：目录/单元仅列出**实际读到的**文件，"..."省略项不得假装已读；未核对的内容进「待补清单」。
5. **免责与边界**：报告结尾保留"内容由 AI 生成，仅供参考"提示，明确 AI 产物的边界。

> 与「进度与反馈系统」联动：质量评分与省察结论写入状态区块与长期记忆，成为下次分析的方法底座。

---


## 交付约定

- 学习报告落盘为 Markdown 文件（`report/<项目名>_learning_report.md`）或按用户要求格式。
- **Obsidian 联动**：学习报告与成果包自动同步写入 Obsidian 库（默认 `E:\obsidian\rein`），并生成以项目主题命名的入口笔记（详见「Obsidian 联动」章节）。
- 若用户已提供项目路径/仓库，直接按六维法进行分析；未提供则先帮用户选项目。
- 输出要结构化：拆解结果用表格，流程画图或时序式描述。
- 面向零基础：解释任何术语时先给一句话通俗定义，再给技术定义。
- 成果包统一收纳进 `<项目名>_learning_assets/` 目录（见「学习成果产出」）。
*（内容由AI生成，仅供参考）*