---
name: technical-learning-notes
description: Use when a user wants structured learning notes for a technology using official documentation and provided third-party resources, especially with beginner-friendly explanations, runnable examples, and review materials
---

# 通用技术学习技能（Codex 专用 `SKILL.md`）

## Codex 专用执行说明

本文件是 `skill.md` 的 Codex 可触发版本，保留同等学习流程与质量标准，并增加以下 Codex 约束：

- 涉及“最新版本 / 当前文档 / 最近变更”时，优先使用联网检索能力确认，不凭旧记忆作答。
- 优先查官方文档与一手来源；关键结论必须附来源链接。
- 若能运行示例，先实际运行再声称“可运行/通过”；若不能运行，明确标注未验证。
- Mermaid 思维导图生成后必须执行语法检查与编译验证；失败则修复并重复验证，直到通过（或因环境限制明确降级）。
- 学习笔记正文必须做一次从头到尾通读检查，确保自包含且递进清晰；读者不应依赖先查官方文档才能理解主线。
- 必须专门进行一轮“逐大纲递归讲解深度检查”，确保每个大纲部分都被详细解释到非科班可理解。
- 必须专门进行一轮“官方文档章节映射与重要例子保留检查”，若有缺失需尽可能补充并在无法补充时说明原因。
- 若用户提供资源质量不足，可补充权威来源，但必须在来源说明中标注采信等级与裁决依据。
- 输出前执行一次自检：结构完整性、引用可追溯、术语一致性、示例可读性。

## 标题与目的

本技能用于指导 Agent 围绕“某项技术 + 用户提供的第三方资源”生成高质量学习笔记与复习材料。

目标：

- 官方文档优先，关键结论强引用，核心机制交叉验证
- 面向非科班友好，同时支持按基础水平自适应深度
- 给出最小可运行示例与运行时现象，帮助快速理解与复现
- 先摘要后展开，顶部提供记忆卡片（含 Mermaid 思维导图）
- 平台无关：描述所需能力，不绑定具体工具名称

---

## 适用场景 / 不适用场景

### 适用场景

- 用户希望系统学习某项技术（语言、框架、工具、数据库、协议、平台、基础设施等）
- 用户提供了部分第三方资源，希望 Agent 结合官方文档整理学习笔记
- 用户需要面向入门者/转行者/非科班读者的直白解释
- 用户需要可复习、可复现、可练习的学习材料
- 用户希望区分“必须掌握”与“暂时可略过”的内容

### 不适用场景

- 纯主观话题（无明确技术事实可验证）
- 仅需极简答案（如一句命令、单个配置项说明）
- 用户明确要求只做资源清单，不要学习笔记
- 无法访问任何可信来源且用户不接受基于已有知识的降级输出

---

## 能力要求（平台无关）

执行本技能的 Agent 应尽量具备以下能力（如缺失，必须走降级策略）：

- 检索公开网页/文档
- 读取并比较多个来源
- 识别来源权威性与发布时间/版本信息
- 生成代码或命令示例
- 在可用环境中运行示例并观察输出/现象（可选但强烈建议）
- 检查 Mermaid 代码块语法并执行编译验证（用于思维导图）
- 组织长文结构并执行多轮自检

---

## 输入规范（字段定义 + 缺省策略）

### 必填字段

- `technology_name`: 技术名称
- `third_party_resources`: 第三方资源列表（至少 1 项，允许质量参差）

### 可选字段（建议提供）

- `learning_goal`: 学习目标（如入门、实战、面试、源码理解、排障）
- `current_level`: 当前水平（零基础 / 初学 / 有经验）
- `time_budget`: 时间预算（如 `30min`、`3h`、`1周`）
- `output_language`: 输出语言（默认 `中文`）
- `preferred_code_language`: 偏好代码语言（如 `Python`、`TypeScript`）
- `runtime_environment`: 运行环境（本地/在线解释器/容器/不可运行）
- `focus_areas`: 希望重点覆盖的主题
- `avoid_areas`: 希望暂不覆盖的主题
- `version_scope`: 指定版本或“最新稳定版”
- `constraints`: 额外约束（不能联网、不能运行代码、篇幅限制等）

### 第三方资源项建议格式（允许字段缺省）

每项资源建议包含：

- `title`
- `url`
- `author_or_org`
- `resource_type`（博客/教程/视频/课程/仓库/文章）
- `notes`（用户为何提供）
- `priority`（高/中/低）

### 缺省策略与最少追问规则

- 当可选字段缺失时，先做合理假设并显式声明。
- 若缺失信息会显著影响学习笔记质量，最多追问 1-3 个关键问题。
- 优先追问高影响字段：
  - `current_level`
  - `learning_goal`
  - `time_budget`
  - `version_scope`
  - `runtime_environment`
- 若用户不回复，使用默认值继续，并在“假设与限制”中说明。

### 默认值（未提供时）

- `output_language = 中文`
- `current_level = 初学`
- `learning_goal = 实战`
- `time_budget = 3h`
- `preferred_code_language = Java`
- `runtime_environment = 本地`
- `version_scope = 最新稳定版（若可确认）`

---

## 输出规范（固定结构与顺序）

Agent 必须输出一个完整学习包，顺序固定如下：

1. 记忆卡片摘要（顶部）
2. 学习笔记正文（详细版）
3. 练习与复习闭环
4. 参考来源与版本说明

### 1) 记忆卡片摘要（必须包含）

- 学习笔记大纲（压缩版）
- Mermaid 思维导图
- 重要知识点清单
- 难点/易混点清单
- QA 快速复习卡片
- 快速复现步骤（最短路径）

### 2) 学习笔记正文（必须包含）

- 正文应尽量自包含：读者只看学习笔记正文即可完成主线理解；官方文档主要用于引用、校验与延伸阅读
- 背景与用途（从读者视角出发）
- 核心概念与术语（直白解释 + 术语原文）
- 工作原理 / 机制（先直观后严格）
- 核心 API / 语法 / 组件 / 命令（按技术类型适配）
- 常见用法与典型场景
- 最小可运行示例（含预期输出/现象）
- 常见错误与排查路径
- 最佳实践与边界条件
- 版本差异 / 兼容性说明（如适用）
- 延伸学习路径（官方优先）

### 3) 练习与复习闭环（必须包含）

- 分层练习（基础 / 应用 / 综合）
- 动手任务（带验收标准）
- 常见误区纠偏
- 复习节奏建议（1天 / 3天 / 7天 / 14天）
- 自测题与参考答案（简版）

### 4) 参考来源与版本说明（必须包含）

- 官方来源列表（优先列出）
- 第三方来源列表（按采信程度标注）
- 关键结论引用映射（正文中的引用标记对应来源）
- 技术版本与文档版本/访问日期
- 已知冲突点及裁决依据（如存在）

---

## 工作流程（主流程 + 自检循环）

以下流程用于生成学习笔记。步骤 4-9 允许循环迭代，直到质量门槛达标或受用户约束限制。

### 主流程

1. **输入解析与补全假设**
   - 读取用户输入字段
   - 标注缺失项并生成默认假设
   - 若关键缺失影响大，发起最少追问（1-3 个）

2. **来源收集与分级**
   - 查找官方文档/规范/权威维护者资源
   - 审查用户提供的第三方资源（质量、时效、版本）
   - 必要时主动补充权威第三方资源
   - 建立来源清单并分级（A=官方，B=权威第三方，C=参考性）

3. **深度学习与结构化笔记初稿**
   - 基于来源提炼主线：概念、机制、用法、示例、误区
   - 形成完整大纲与正文初稿
   - 记录关键结论的来源标记

4. **大纲完备性检查与补漏（可循环）**
   - 检查是否覆盖“是什么/为什么/怎么用/怎么错/怎么排查/怎么进阶”
   - 检查是否缺失版本差异、边界条件、常见场景
   - 补充必要章节或合并不必要章节

5. **示例充分性检查（可循环）**
   - 核心概念是否有最小可运行示例
   - 是否包含运行前提、预期输出/现象、常见错误
   - 若无法运行，是否明确未验证并给替代验证方式

6. **冗余压缩与结构清理（可循环）**
   - 删除重复解释、同义重复、绕弯表达
   - 将长段拆为可扫描的小节/列表
   - 保留信息密度，不牺牲关键上下文

7. **语言直白化润色（可循环）**
   - 面向非科班读者重写生硬表述
   - 术语首次出现给中文解释 + 英文原文
   - 控制类比数量，类比后回到真实机制
   - 从头到尾通读学习笔记正文，检查是否为递进式讲解而非信息堆砌
   - 检查前置概念是否先于后续内容出现，避免读者来回跳跃查阅
   - 检查正文是否自包含：关键概念、前提、步骤、结论不应依赖读者先去看官方文档才能理解主线

8. **大纲逐项递归讲解深度检查（专门一轮，可循环）**
   - 按正文大纲从头到尾逐项检查（一级、二级、三级小节），不得只抽查部分章节
   - 检查每个大纲部分是否有递归解释：至少讲清“是什么 / 为什么 / 怎么做（或怎么用） / 如何判断是否正确”的适用项
   - 检查同层级、同等重要性的大纲部分是否保持相近详细度；若明显不均衡，补充说明或补写内容
   - 对仍然抽象的部分继续拆解解释（必要时补最小示例、反例、类比后的真实机制说明），直到非科班读者可顺读理解
   - 清理“只有标题或只有结论、缺少解释过程”的空壳小节

9. **官方文档章节映射与重要例子保留检查（专门一轮，可循环）**
   - 获取官方文档章节结构（至少到二级标题），建立“官方章节 -> 学习笔记章节”映射表
   - 逐项检查官方文档每个章节在学习笔记中是否有对应章节或明确合并说明
   - 检查官方文档中的重要例子是否在学习笔记中保留（原样、等价改写或补充解释版本均可）
   - 对缺失章节与缺失重要例子尽可能补充；若因范围/篇幅不纳入，必须显式标注原因
   - 补充后再次检查章节映射完整性，避免出现“官方有、笔记无”的关键断层

10. **生成记忆卡片摘要（可循环）**
   - 从正文提炼大纲、难点、关键点、QA、复现步骤
   - 生成 Mermaid 思维导图
   - 确保与正文结构一致

11. **Mermaid 语法检查与编译验证（可循环）**
   - 提取本次输出中的所有 Mermaid 代码块（至少包含记忆卡片思维导图）
   - 执行 Mermaid 语法检查与编译验证（如渲染为 SVG/PNG）
   - 若编译失败，定位报错行/节点/连接关系并修复 Mermaid 代码
   - 重复“检查 -> 修复 -> 编译验证”，直到编译通过
   - 若环境无法编译，必须明确标注未验证，并给出用户可执行的本地/在线验证步骤

12. **生成练习与复习闭环**
   - 按难度给练习
   - 给动手任务与验收标准
   - 制定复习节奏与自测题

13. **最终一致性与引用检查**
   - 检查术语一致、编号一致、链接有效性（若可检测）
   - 检查引用标记是否可追溯
   - 检查版本/日期/假设是否显式说明
   - 检查 Mermaid 图与正文结构一致，且编译结果基于最终版本 Mermaid 代码
   - 检查大纲逐项递归讲解深度检查结论已体现在最终正文（避免后续修改引入失衡）
   - 检查“官方章节映射与重要例子保留检查”结论已体现在最终正文（避免后续改动回退）

### 自检循环终止条件（满足其一）

- 质量检查清单全部通过
- 达到用户指定篇幅/时间预算
- 环境限制导致无法继续提升，且已清晰标注限制

---

## 来源检索与筛选规则（官方优先、权威判定、冲突处理）

### 来源优先级

按以下优先级采信（从高到低）：

1. 官方文档 / 官方规范 / 官方仓库 README 与正式指南
2. 官方维护者/核心贡献者发布内容（版本相符）
3. 权威第三方资料（知名技术媒体、高质量教程、成熟课程、高质量示例仓库）
4. 一般社区文章（仅作补充或对比）

### 第三方资源筛选规则

对用户提供的第三方资源执行筛选：

- **相关性**：是否直接覆盖该技术核心内容
- **时效性**：发布日期/最近更新是否匹配当前版本
- **准确性**：是否与官方文档冲突
- **完整性**：是否只有零散技巧而缺乏主线
- **可教学性**：是否有清晰示例与解释

处理原则：

- 可用但不完美：保留并标注局限
- 过时或冲突：不作为主依据，必须标注风险
- 明显错误：说明原因，不纳入结论依据
- 资源不足：主动补充更权威来源

### 强引用规则（关键结论必须引用）

以下内容必须标注来源：

- 核心机制或原理性结论
- 版本相关行为差异
- 官方推荐/弃用/限制
- 容易误解且会导致错误实践的结论

建议使用统一引用标记，例如：

- 正文内：`[来源1]`、`[来源2]`
- 文末来源表：列出标题、链接、版本/访问日期、采信说明

### 交叉验证规则

- 核心机制至少由 2 个来源交叉验证（其中至少 1 个为官方来源）
- 若仅有单一来源可得，必须标注“单源结论，待进一步验证”

### 冲突处理规则（必须显式）

当来源冲突时，必须输出：

- 冲突点是什么
- 各自来源与版本/发布时间
- 适用上下文差异（如版本、运行环境、配置前提）
- 裁决依据（通常以官方/更新版本/更具体上下文者为准）
- 最终采用结论 + 保留条件

可使用固定模板：

```text
冲突点：
来源A（版本/日期）：
来源B（版本/日期）：
差异原因判断：
本笔记采用结论：
适用条件/例外：
```

### 官方文档章节映射与重要例子保留规则

- 对官方文档执行章节级覆盖检查：官方每个章节在学习笔记中都应有对应章节、合并说明或明确不纳入理由
- 优先保持官方主线结构，必要时可为教学重排顺序，但应提供“官方章节 -> 学习笔记章节”映射
- 官方文档中的关键示例、典型示例和高频引用示例应尽可能保留
- 保留方式可为：原样引用、等价改写、补充注释后的教学版；但不得遗漏核心输入/输出与关键行为
- 若因环境限制无法复现实例，需标注未验证并说明该示例在官方文档中的章节位置

---

## 示例生成规则（最小可运行、预期输出、错误示例）

### 示例总原则

- 优先最小可运行示例（Minimal Runnable Example）
- 示例应服务于概念，不是炫技
- 一次只解释一个核心点
- 优先短小、可复制、可观察

### 每个示例必须包含的元素

- **示例目标**：这个示例要说明什么
- **前提条件**：版本、依赖、环境、文件结构（最小化）
- **示例代码/命令/配置**
- **运行步骤**
- **预期输出或可观察现象**
- **常见错误与修复提示**（如该示例容易踩坑）

### “代码实例 + 运行时实例”适配规则

按技术类型选择示例形式：

- 编程语言/框架：代码 + 运行输出/页面行为/log
- CLI 工具：命令 + 终端输出/错误提示
- 数据库：建表/查询语句 + 结果集示例
- 基础设施/容器：配置片段 + 应用后状态/日志/事件
- 协议/概念性技术：抓包/状态转换/消息流示意 + 可观察现象

### 无法实际运行时的降级要求

若环境无法运行示例，必须明确标注：

- `未在当前环境实际验证`
- 预期输出/现象（基于来源与经验）
- 替代验证方式（在线 playground、官方示例、最小实验步骤）

### 错误示例（建议）

对高频误区可增加“错误示例”：

- 错误写法/错误命令
- 典型报错或异常现象
- 错误原因（直白解释）
- 修复后的正确写法

---

## 教学表达规则（非科班友好、术语处理、谨慎类比）

### 读者友好原则

- 默认读者不熟悉术语和上下文
- 先回答“这东西有什么用”，再讲原理
- 先给直观版本，再给严格版本
- 让读者能先跑起来，再逐步理解细节

### 术语处理规则

- 术语首次出现格式：`中文解释（英文原文）`
- 避免在未定义术语前继续引用它
- 对易混术语给对比表（如“进程 vs 线程”）

### 类比使用规则

- 类比仅用于降低入门门槛，不作为最终定义
- 每个类比后必须回到真实机制
- 避免连续使用多个类比导致概念漂移

### 正文自包含与递进性规则

- 正文应能独立支撑主线学习，官方文档作为引用与延伸阅读，不应成为理解前提
- 章节顺序应按“前置概念 -> 核心机制 -> 用法 -> 示例 -> 排错 -> 最佳实践”递进展开
- 若某节依赖尚未介绍的概念，应前移定义或在当前位置补最小解释
- 避免“信息堆砌式”罗列；每一节都应回答明确问题并与上一节衔接
- 完成后必须以首次读者视角从头到尾通读一遍正文，修复跳跃与断层

### 大纲逐项递归解释与深度均衡规则

- 对正文大纲的每个部分执行同等强度的检查与解释补全，不能只打磨少数章节
- 同层级、同等重要性的部分应保持相近详细度；若刻意简化某部分，必须有明确原因（如超出当前目标/时间预算）
- “递归解释”指：对抽象概念继续拆到读者能理解的层级，而不是用另一组同样抽象的术语替代
- 优先补足每一部分的“定义、作用、前提、步骤/机制、例子/反例、边界或误区”中适用项
- 目标是让非科班读者按正文顺序读完即可理解，不需要来回查阅外部材料补关键定义

### “必须记住 / 可后看”标记

建议在正文中显式标记：

- `必须记住`：初学阶段就会影响正确使用的点
- `容易踩坑`：高频错误点
- `先知道即可`：进阶再深入的点

---

## 压缩与润色规则（去重、简化、信息保真）

在保持完整性的前提下优化清晰度：

### 去重规则

- 删除同一结论在多个段落的重复表述
- 将零散重复点合并为一张表或一组清单
- 若某结论已在示例解释过，正文只保留简洁引用

### 简化规则

- 优先短句，避免多层从句
- 一段只讲一个中心意思
- 长段拆成小节、列表、表格
- 将背景知识压缩到“够用”而非“百科全书”

### 信息保真规则

- 不因压缩删除边界条件或前提假设
- 不将“可能/通常”写成“总是/必须”
- 不省略版本差异导致误导

### 篇幅策略（分层）

- **速览版**（时间预算很短）：记忆卡片 + 主线概念 + 最少示例集合
- **标准版**（默认）：完整结构 + 适量示例 + 基础练习
- **深入版**（复杂技术/实战目标）：补充机制细节、更多排障案例、进阶练习

---

## 自适应难度策略（根据用户水平与目标调整）

### 按 `current_level` 调整

- **零基础**
  - 术语解释密度更高
  - 示例更小、更直观
  - 加更多“为什么要这样做”
- **初学**
  - 保留主线解释，减少过度铺垫
  - 强化常见坑与最佳实践
- **有经验**
  - 压缩基础定义
  - 增加原理、权衡、性能/可维护性/兼容性讨论

### 按 `learning_goal` 调整

- **入门**：重概念、基本用法、最小示例
- **实战**：重场景、错误处理、最佳实践、排障
- **面试**：重原理、常见追问、对比与边界
- **源码理解**：重内部机制、关键模块、调用流程

---

## 质量检查清单（完成前必须通过）

在输出最终结果前，逐项检查：

### A. 完整性

- 是否覆盖“是什么/为什么/怎么用/怎么错/怎么排查/怎么进阶”
- 是否包含版本说明与适用范围
- 是否包含练习与复习闭环
- 是否包含记忆卡片摘要（含 Mermaid）

### B. 来源质量

- 是否以官方文档为主轴
- 关键结论是否都有引用
- 核心机制是否已交叉验证
- 冲突点是否显式说明并裁决

### B1. 官方章节与例子覆盖（必须）

- 是否专门进行一轮“官方文档章节映射检查”（覆盖官方各章节，而非抽查）
- 学习笔记是否对官方文档每个章节都有对应内容、合并说明或排除理由
- 官方文档重要例子是否在学习笔记中得到保留（原样/等价改写/教学增强版）
- 缺失章节与缺失重要例子是否已尽可能补充，并记录无法补充的原因

### C. 示例质量

- 核心概念是否有最小可运行示例（或合理降级）
- 每个示例是否有前提、步骤、预期输出/现象
- 是否给出高频错误示例或错误提示（至少若干关键点）

### C1. Mermaid 图质量（必须）

- 是否包含 Mermaid 思维导图（记忆卡片要求）
- Mermaid 语法是否已检查
- Mermaid 是否已完成编译验证并通过（或明确降级说明）
- 若修复过 Mermaid 报错，是否基于最终版本重新编译验证

### D. 可读性

- 语言是否足够直白，不堆术语
- 是否存在明显重复/啰嗦段落
- 非科班读者是否能顺着示例理解主线

### D1. 正文自包含与递进性（必须）

- 读者只看学习笔记正文，是否能完成主线理解而不必先回看官方文档
- 正文是否从头到尾可顺读，理解路径递进清晰，不需要频繁来回跳转
- 正文是否避免纯信息堆砌（存在明确的讲解顺序、衔接和层次）
- 关键概念/前提是否在首次使用前已定义或给出最小解释

### D2. 大纲逐项递归解释深度检查（必须）

- 是否专门进行一轮“逐大纲检查”（覆盖所有正文大纲部分，而非抽查）
- 每个大纲部分是否有足够详细的解释，而非仅给定义或结论
- 是否对难点进行了递归拆解解释，直到非科班读者可理解
- 同层级、同等重要性部分的详细度是否基本均衡；若不均衡是否说明原因
- 是否消除了“标题完整但正文某些部分明显过薄”的章节

### E. 一致性

- 术语命名是否前后一致
- 章节顺序是否符合输出规范
- 引用编号/来源表是否一一对应
- 版本/访问日期是否明确

---

## 失败与降级策略（无法联网 / 无法运行 / 资源不可靠）

### 场景 1：无法联网检索官方文档

处理方式：

- 明确声明无法联网
- 优先使用用户提供资源 + 已知可靠资料
- 将结论标注为“需联网复核”
- 输出“后续复核清单”（建议补查哪些官方页面）

### 场景 2：无法运行示例

处理方式：

- 明确声明未实际验证
- 给出预期输出/现象
- 给出替代验证步骤（在线环境/官方示例/本地最低配置）
- 降低对运行细节的确定性措辞

### 场景 2.5：无法编译验证 Mermaid 图

处理方式：

- 明确声明 Mermaid 图 `未在当前环境完成编译验证`
- 先做 Mermaid 语法自检（括号、缩进、节点文本、连接符）
- 提供可执行的验证方式（本地 Mermaid CLI / 在线 Mermaid Live Editor）
- 给出“建议验证步骤”与预期应看到的图结构
- 不得声称“Mermaid 图已通过编译”

### 场景 3：用户资源质量差或明显过时

处理方式：

- 保留资源但标注风险与局限
- 主动补充权威来源
- 在“来源说明”中标注哪些资源仅作参考、不作为结论依据

### 场景 4：时间预算极短

处理方式：

- 优先输出“速览版”
- 保留记忆卡片、主线概念、最少示例、常见坑
- 将进阶内容移至“后续学习路径”

### 场景 5：输入信息严重不足

处理方式：

- 先做合理假设并继续
- 对关键未知点标注“假设”
- 若影响过大，最多追问 1-3 个关键问题

---

## 输出模板（可直接复用，中文默认）

以下模板用于生成最终学习包。可按技术类型微调，但总体顺序不得改变。

````markdown
# 记忆卡片摘要（快速复习版）

## 1. 大纲（压缩版）
- 这项技术是什么
- 核心概念
- 工作机制
- 常见用法
- 最小可运行示例
- 常见错误与排查
- 最佳实践
- 练习与复习路径

## 2. 思维导图（Mermaid）
```mermaid
mindmap
  root(({{technology_name}}))
    是什么
    为什么用
    核心概念
    工作机制
    常见用法
    示例与运行现象
    常见错误
    最佳实践
    练习与复习
```

## 3. 重要知识点（必须记住）
- ...

## 4. 难点 / 易混点
- ...

## 5. QA 快速复习卡片
- Q: ...?
  A: ...
- Q: ...?
  A: ...

## 6. 快速复现步骤（最短路径）
1. ...
2. ...
3. ...

---

# 学习笔记正文（详细版）

## 0. 学习目标、读者画像与假设
- 技术：`{{technology_name}}`
- 学习目标：...
- 读者水平：...
- 时间预算：...
- 版本范围：...
- 运行环境：...
- 假设与限制：...

## 1. 背景与用途（从读者视角）
- 这项技术解决什么问题
- 不用它会怎样
- 典型应用场景

## 2. 核心概念与术语（直白解释）
- 术语A（English Term）：...
- 术语B（English Term）：...

## 3. 工作原理 / 机制（先直观后严格）
### 3.1 直观版
- ...
### 3.2 严格版
- ...

## 4. 核心 API / 语法 / 组件 / 命令（按技术类型适配）
- ...

## 5. 常见用法与典型场景
- 场景1：...
- 场景2：...

## 6. 最小可运行示例（含预期输出/现象）
### 示例1：说明某核心概念
- 目标：...
- 前提条件：...
- 代码/命令：
```txt
...
```
- 运行步骤：...
- 预期输出/现象：...
- 常见错误与修复：...

## 7. 常见错误与排查路径
- 错误现象：...
- 常见原因：...
- 排查顺序：...

## 8. 最佳实践与边界条件
- 最佳实践：...
- 边界条件/限制：...

## 9. 版本差异 / 兼容性说明（如适用）
- ...

## 10. 延伸学习路径（官方优先）
- 先读：...
- 再做：...
- 进阶：...

---

# 练习与复习闭环

## 1. 分层练习
### 基础练习
- ...
### 应用练习
- ...
### 综合练习
- ...

## 2. 动手任务（带验收标准）
- 任务：...
- 验收标准：...

## 3. 常见误区纠偏
- 误区：...
  正解：...

## 4. 复习节奏建议
- Day 1：...
- Day 3：...
- Day 7：...
- Day 14：...

## 5. 自测题与参考答案（简版）
- 题目1：...
  参考答案：...

---

# 参考来源与版本说明

## 官方来源（优先）
1. [标题](链接) - 版本/访问日期 - 用途

## 第三方来源（按采信程度标注）
1. [标题](链接) - 采信程度：高/中/低 - 备注

## 关键结论引用映射
- [来源1] -> ...
- [来源2] -> ...

## 冲突点与裁决（如有）
- 冲突点：...
- 裁决依据：...
- 采用结论：...
````

---

## 执行示例（输入示例 + 输出骨架示例）

### 输入示例（JSON）

```json
{
  "technology_name": "React",
  "third_party_resources": [
    {
      "title": "React 入门教程（第三方）",
      "url": "https://example.com/react-guide",
      "author_or_org": "Example Blog",
      "resource_type": "教程",
      "notes": "我之前看过，但不确定是否过时",
      "priority": "high"
    }
  ],
  "learning_goal": "入门并能写出基础交互页面",
  "current_level": "初学",
  "time_budget": "2h",
  "output_language": "中文",
  "preferred_code_language": "JavaScript",
  "runtime_environment": "本地可运行",
  "version_scope": "最新稳定版"
}
```

### 输出骨架示例（仅结构示意）

```markdown
# 记忆卡片摘要（快速复习版）
## 1. 大纲（压缩版）
## 2. 思维导图（Mermaid）
## 3. 重要知识点（必须记住）
## 4. 难点 / 易混点
## 5. QA 快速复习卡片
## 6. 快速复现步骤（最短路径）

# 学习笔记正文（详细版）
## 0. 学习目标、读者画像与假设
## 1. 背景与用途
## 2. 核心概念与术语
## 3. 工作原理 / 机制
## 4. 核心 API / 语法 / 组件 / 命令
## 5. 常见用法与典型场景
## 6. 最小可运行示例（含预期输出/现象）
## 7. 常见错误与排查路径
## 8. 最佳实践与边界条件
## 9. 版本差异 / 兼容性说明
## 10. 延伸学习路径

# 练习与复习闭环
## 1. 分层练习
## 2. 动手任务（带验收标准）
## 3. 常见误区纠偏
## 4. 复习节奏建议
## 5. 自测题与参考答案（简版）

# 参考来源与版本说明
## 官方来源（优先）
## 第三方来源（按采信程度标注）
## 关键结论引用映射
## 冲突点与裁决（如有）
```

---

## 验证场景（用于自测该技能是否达标）

使用以下场景检查本技能输出质量：

1. **零基础场景（Git）**
   - 输入：博客 + 官方文档
   - 期望：非科班可读、命令示例清晰、含错误示例、记忆卡片完整

2. **工程实践场景（Docker）**
   - 输入：视频教程 + 官方 docs
   - 期望：概念与运行时行为清晰，示例附预期现象

3. **过时资源场景（React）**
   - 输入：含过时写法的第三方教程
   - 期望：识别过时内容，补充官方现代写法，说明版本差异

4. **复杂基础设施场景（Kubernetes）**
   - 输入：用户资源较少
   - 期望：主动补权威来源，分层篇幅控制，不丢主线

5. **资源冲突场景**
   - 输入：第三方资源与官方文档冲突
   - 期望：显式列出冲突点、版本与裁决依据

6. **无法运行示例场景**
   - 输入：环境限制不可运行
   - 期望：启用降级策略，明确未验证，并给替代验证方法

7. **时间预算受限场景（30 分钟）**
   - 输入：`time_budget=30min`
   - 期望：输出速览版，但保留记忆卡片、主线与最少示例集合

---

## 执行要求（简明版）

生成学习笔记时，Agent 必须做到：

- 先确认输入与假设，再开始整理
- 官方优先，第三方资源筛选后使用
- 关键结论强引用，核心机制交叉验证
- 示例最小可运行，附预期输出/现象
- Mermaid 思维导图必须做语法检查与编译验证，失败则修复重试直到通过（或明确降级）
- 学习笔记正文必须自包含且可顺读：需从头到尾通读检查，确保递进讲解而非信息堆砌
- 必须专门进行一轮“逐大纲递归讲解深度检查”，确保每个部分都讲清楚到非科班可理解
- 必须专门进行一轮“官方文档章节映射与重要例子保留检查”，若有缺失需尽可能补充
- 语言直白，减少重复，保留边界条件
- 顶部输出记忆卡片（含 Mermaid）
- 补齐练习与复习闭环
- 最终做一致性与引用检查