mhtml-refine-to-md

🚦 触发机制 (Trigger)

当用户要求"总结"、"整理"、"提取"一个或多个极客时间专栏 .mhtml 文件并输出为笔记/Markdown 时，自动触发。非极客时间站点的 mhtml 不适用本 skill（关键提取规则如 data-slate-string、articleInfo class、resource/image 路径均为极客时间专属）。

📥 输入参数 (Inputs)

• Source_File: 待处理的源 .mhtml 文件绝对路径。
• Target_Directory: (可选) 笔记输出的目标目录。如果不指定，默认输出到 /Users/fengyuhao/SecondBrain/200_Learning/ 下的相关课程目录。

⚙️ 执行工作流 (Workflow)

请严格按照以下步骤执行任务：

1. 读取与解析 (Read & Parse)

• 读取 Source_File 的原始内容，正确处理 mhtml 的 Base64 或 quoted-printable 编码分段。

• 极客时间专栏 HTML 特性：极客时间专栏使用 Slate.js 富文本渲染，正文所有文本存储在 <span data-slate-string="true"> 元素中，不在 <p> 标签内。提取正文必须使用此选择器，而非常规 <p> 标签。

• 从 HTML 结构中优先提取关键元数据：

  • 文章标题（<title> 或 <h1>）
  • 课程名称（从 <title> 中提取，格式通常为"文章标题-课程名-极客时间"）
  • 讲次编号（标题前缀，如 "01｜"、"开篇词｜"；分隔符全角 ｜ 与半角 |（含两侧空格 |）均可能出现，按任一分隔符切分取前缀；无数字时保留文字前缀）
  • 作者名（即作者/讲师，极客时间专栏二者为同一人），按以下优先级提取（任一命中即可，不同讲师/编辑团队 DOM 结构不同）：
    1. class 含 articleInfo 的元素内的文本——注意该 class 可能挂在 <div> 上，作者名在其内层无 class 的 <span> 里（如茹炳晟《软件测试52讲》：<div class="...articleInfo..."> <span>茹炳晟</span></div>），不要机械只认"class 含 articleInfo 的 span"。
    2. class 含 authorName（如 ColumnInfo_authorName_*）的元素文本——最稳定的兜底来源，几乎所有极客时间专栏页都有。
    3. 正文首句"你好，我是 [名字]"——仅部分讲师适用（有的开篇词不用此句式，如茹炳晟以"作为专栏的第一篇文章…"开头），命中不到时回退到 1/2，切勿硬套。 提取后存为变量供后续章节标题（## [作者名]说）和署名使用。

• 图片处理（必须逐张视觉核查，不得跳过）：

  1a — 提取图片并获取原文字符数：调用 skill 自带的提取脚本（已封装清空临时目录、封面识别、Slate 字符统计）：

  python3 __SKILL_DIR__/scripts/extract_images.py "<Source_File 的绝对路径>"
  

  脚本输出：

  • 图片清单：每行 <文件名> | <COVER|CONTENT> | <字节数> | <原始URL> [可选标注]，存放在 /tmp/geektime_imgs/。CONTENT 待视觉核查，COVER 直接跳过。
  • 若某张 CONTENT 图的任意边 > 2000px，脚本会自动原地缩放至 ≤ 2000px（保持比例），并在输出行末尾追加 [RESIZED WxH→W'xH'] 标注，确保后续 Read 工具视觉分析时不触发 Claude API many-image 尺寸限制。
  • [LIKELY_DECORATIVE] 装饰图标记：若 CONTENT 图同时满足"任意边 < 1500px"和"字节数 < 350KB"，脚本会追加此标注。这类图多为卡通插画、概念隐喻装饰，文字信息密度极低。视觉分析时应：
    • 先读同系列第 1 张（如多张卡通厨师插画通常风格一致）
    • 若确认是"标题 + 一行特性描述"形态的装饰图 → 其余同系列图可直接 base on 文件名跳过 Read，不再进入上下文
    • 在笔记中默认省略 [!INFO] 类比示意——这些图的文字内容已被正文覆盖，[!INFO] 块只是冗余复述
    • 例外：若用户明确要求"逐图还原"，则按 Step 1c 正常处理
  • 末尾一行 SLATE_CHARS: N：原文正文纯字符数。必须记录此 N 值，Step 6 字数比例核查依赖它（笔记字符数应 ≥ N × 60%）。

  脚本源码见 scripts/extract_images.py，可独立测试。

  1b — 逐张视觉分析（Read 工具查看每张图片）：对 1a 提取的每张图，使用 Read 工具查看实际内容，记录：

  • 图片类型（流程图 / 架构图 / 代码截图 / 配置截图 / 数据表格 / UI操作截图）
  • 图片中的关键信息：代码截图需记录实际代码内容；架构图需记录节点名称和关系；数据截图需记录关键数值
  • 在正文中的位置（对应哪段 Slate 文本之后）
  • 处理决策（见 1c）

  ⚠️ 批量读取与上下文控制（必须遵守，防止请求体超限）：图片超过 4 张时，每读完 4 张立即将分析结果归纳为一张紧凑摘要表，再继续读下一批。原始图片 base64 数据会快速撑大对话上下文；及时归纳摘要可将图片数据从"活跃上下文"中清出，避免后续 API 请求体超限崩溃。

  摘要表格式（每批读完后输出，后续步骤只依赖此表，不再重复引用原始图片内容）：

  文件名	图片类型	核心信息（一行内）	处理决策	所在正文位置
  img001.png	架构图	Client→Gateway→Service→DB 四层	Mermaid graph TD	第2节"架构概览"后
  img002.png	代码截图	Spring @Async + CompletableFuture 并发模式	代码块(java)	第4节示例后

  1c — 按类型决定处理方式（基于视觉分析，而非文字推测）：

  • 信息图 / 总览图 / 多分区架构图（特征：≥3 个并列彩色面板、多卡片网格、章节式分区，如"课程总览七大部分"、"五层架构总览"、"知识体系大图"、"方法论矩阵"）→ HTML/CSS 卡片（见 Step 3·A）。禁止用 Mermaid 重绘这类图——Mermaid 的 dagre 自动布局算法做不出"设计师手工排版"的卡片矩阵质感，强行画只会得到丑陋的树形噪音图。
  • 流程图 / 时序图 / 状态机 / 决策树 / 单一关系图 / 思维导图（特征：节点之间有明确的方向连接、强调"动态/拓扑"而非"分区/陈列"）→ Mermaid（见 Step 3·B）
  • 代码截图 → 将图中可读取的实际代码提炼为代码块（保留语言、关键注释），置于对应正文位置
  • 数据表格 / 参数截图 → 将截图中的数据以 Markdown 表格还原，保持原有行列结构
  • UI 操作截图 / 配置界面 → 写 [!INFO] 📷 图示：，内容不少于 3 句话，说明截图展示的具体界面、操作步骤和关键结论
  • 封面图（Step 1a 已标注 COVER）→ 直接跳过，无需 Read 查看
  • 禁止在笔记中插入任何外部图片 URL（![](https://...)）或基于外部 URL 的 <img> 标签；HTML 卡片中的 <div>/<span> 不受此限。

• 作者旁白块识别（条件性）：仅当文章中存在与正文视觉/结构显著区分的旁白块（独立 CSS class、特殊引用框、带头像发言框、明确以"提示："/"小贴士："等前缀引出的独立段落）时才识别。整篇都是第一人称叙述但无显著区分的文章（极客时间专栏多为此类），M=0，后续 ## [作者名]说 章节直接跳过。识别到的旁白块总数记为 M。

• 🔑 章节级标题判定（关键，不可跳过）：极客时间专栏中，章节级标题既可能是 H1，也可能是 H2（不同作者/编辑团队习惯不同），不能机械假设为 H2。判定规则：

  1. 第一个 H1（与 <title> 内容一致）= 文章主标题，不计入章节。
  2. 从剩余的 H1 与 H2 中，取层级最浅且数量 ≥ 3 的那一档作为"章节级标题"。例：若正文中有 4 个 H1（除主标题外）和 8 个 H2，则 H1 为章节级、H2 为子节；若没有正文 H1 而 H2 有 5 个，则 H2 为章节级。
  3. 在覆盖清单中明确标注实际章节级别（如"本文章节级 = H1"）。
  4. 🆕 特例 — 扁平叙述型文章（无分节标题）：若除主标题外，正文 H1/H2/H3 中没有任何一档数量 ≥ 3（典型如茹炳晟《软件测试52讲》：正文为连续叙述行文，分节标题仅有收束性的"总结""思考题"等 1-2 个 H2，逻辑分块完全靠话题转换而非标题），则判定为「扁平叙述型」，按下述方式处理（其余多标题文章不受影响，仍走规则 1-3）：
     • 覆盖清单改为按「正文逻辑主题块」建立，而非依赖标题。识别依据：① 话题转折句（"那什么是…呢？""接下来再说说…"）；② 加粗短语 / 概念定义句；③ 并列列表的分组前导句（如"安全性测试用例包括：""性能压力测试用例包括：""兼容性测试用例包括："）。把每个主题块作为一个清单项，标注为「逻辑块」而非「H2」。
     • 笔记的 ## 结构完全由 skill 模板（关键概念 / 原理解析 / 最佳实践…）主动赋予，把上述逻辑块归类填入对应模板章节。
     • 原文若有"总结""思考题"H2，仍按"章节级过滤规则"正常处理。
     • 在覆盖清单标题处注明"本文为扁平叙述型，章节级 = 逻辑主题块（无分节标题）"。

• 章节级过滤规则：

  • 过滤评论区：末尾含"全部留言"的章节级标题及其后所有内容属于评论区，不纳入笔记。
  • 原文"总结"章节：若存在，其 Slate 文本内容作为笔记 ## 总结 章节的基础素材（加以丰富，不照抄）。
  • 原文"思考题"章节：若存在，其 Slate 文本即为题目原文，完整保留。

• 剥离所有干扰内容：导航栏、侧边栏、广告、评论区、footer。

• 精准保留：正文段落、代码块、列表、表格、作者旁白块（若有）、以及文末的"思考题"部分。

• 建立章节级覆盖清单：解析完成后，列出正文中所有有效章节级标题（按上面"章节级判定"识别，已过滤"全部留言"），格式如下（后续 Step 2 写作前逐一打勾核对）：

  原文章节级覆盖清单（章节级 = H1 或 H2，写实际级别）：
  - [ ] 章节标题一
  - [ ] 章节标题二
  - [ ] 章节标题三
  ...
  

2. 内容提炼与重构 (Distill & Restructure)

⚠️ 写作前必须执行：内容完整性核查

1. 对照 Step 1 的章节级覆盖清单，逐项确认每个章节级标题（H1 或 H2，取决于本文判定结果）在笔记中均有对应的 ## 或 ### 节覆盖。
2. 不得以"与其他章节重复"为由跳过任何章节级标题——若内容有交叉，也须单独成节（或作为 ### 子节），保留该视角的核心论述。
3. 若 Step 1 识别到的 M > 0，确认 M 个作者旁白块已全部收入 ## [作者名]说，不得因"内容已在正文中体现"而删减；若 M = 0，跳过该章节。

将提炼后的内容重新组织为以下笔记结构（根据文章内容选用适合的章节，不强制全部包含）：

# [讲次编号]-[文章标题]

> [!ABSTRACT] 一句话摘要
> 本文解决什么问题？核心结论是什么？（1-2句话，用最精炼的语言）

---

## 关键概念
（定义类内容，术语解释，对比表格）

---

## 原理解析
（核心机制、架构、流程的深度拆解，长节必须拆 ### 子节）

---

## 代码示例
（保留文章中的关键代码，每段代码上方一句话说明演示目的）

---

## 最佳实践 & 避坑指南
（操作建议、常见误区）

---

## [作者名]说（仅当 M > 0 时包含）
（完整保留 Step 1 识别到的 M 个作者旁白块，每段独立一个 [!QUOTE] callout，末尾署名 `— [作者名]`；章节标题中的「作者名」替换为 Step 1 提取到的实际作者名，如「咖哥说」「张磊说」「Robert说」。若 M = 0（极客时间专栏常见情况），整节省略）

---

## 作者金句
（从正文中提炼 1-3 句最精炼、最具洞见的核心观点，用 [!QUOTE] callout 呈现，与上节"[作者名]说"的旁白不同，这里是对全文最重要论断的主动萃取）

---

## 思考题
（完整保留原文末尾的思考题，每题用 [!QUESTION] callout；每题下方紧跟一个 [!NOTE]- 折叠块，标题为「参考答案」，结合本文内容与相关技术背景给出完整、有深度的参考答案，不得仅用"见上文"敷衍）

---

## 总结
（必须包含：① 一个 mindmap 图表作为全文知识俯瞰 ② 3-5 条核心 bullet points）

重构原则：

• 禁止流水账式翻译，必须有归纳、提炼和重组。
• 每个 ## 章节之间使用 --- 分隔线，增强视觉层次感。
• 原文若存在"总结"/"小结"等收束章节，将其 Slate 文本作为本笔记 ## 总结 章节的基础素材，再补充 mindmap 与 3-5 条 bullet points。
• 长章节使用 ### 子节：## 原理解析 等内容丰富的章节，应拆分为多个 ### 子节（每个子节覆盖一个独立概念），避免整节变成无结构的长段落。
• 原文参考表格与目录结构必须完整保留：比较表、配置参数表、目录结构树等，直接以 Markdown 表格或 plain code block 原样呈现，不得压缩为描述性文字。
• plain code block 的使用场景：对于层级文本、目录树、结构化列表等"参考型"内容，使用普通 ``` 代码块（不带语言标注），而非强制转为 Mermaid；Mermaid 保留给需要展示"关系与动态"的内容。
• 图片内容还原（基于 Step 1b 的视觉分析结果，按 Step 1c 的决策执行，不再重复推测）：

  • Step 1c 中已确定处理方式的图，在笔记对应位置按决策输出（HTML 卡片 / Mermaid / 代码块 / 表格 / [!INFO]）。

  • 主动新增图/卡：即便原文某处没有图片，若该段文字描述了关系/流程/对比/层级/时序，主动生成 Mermaid；若描述的是多分区陈列/总览/方法论矩阵，主动生成 HTML 卡片。不受原文图片数量限制。

  • 可视化模式选型表（按内容形态选工具，而不是按"原文有没有图"）：

    内容形态	工具	典型场景
    多分区陈列（≥3 并列面板，无方向连接）	HTML 卡片	课程七大部分、五层架构总览、方法论矩阵、知识体系
    层级结构（有上下父子关系，节点 ≤6）	Mermaid graph TD + subgraph	系统三层模型、调用栈
    流程 / 链路 / 步骤	Mermaid graph TD/LR	请求处理流程、CI/CD 流水线
    时序 / 交互	Mermaid sequenceDiagram	OAuth 握手、RPC 调用
    状态 / 生命周期	Mermaid stateDiagram-v2	订单状态机、连接生命周期
    决策树 / 选型	Mermaid graph TD + 菱形	"什么时候用 X / Y"
    思维导图 / 全文俯瞰	Mermaid mindmap	总结章节
    属性对比 / 参数速查	Markdown 表格	方案对比表、配置参数
    目录 / 文件树	plain code block	工程目录结构

  • 关键判断："有方向的拓扑 → Mermaid"；"无方向的陈列 → HTML 卡片"；"精确查找 → 表格"。

  • 典型误判案例：

    • 原文是"七大模块"的彩色分区图 → ❌ 千万别画 ROOT --> M1 --> M1A 的 Mermaid 树（自动布局会乱、丑），✅ 用 HTML 卡片（见 Step 3·A）
    • 原文是"五层架构"流程：每层独立分区且互无连接 → HTML 卡片；若每层之间有数据流箭头 → Mermaid

  • 所有可视化块上方注明 > 📊 [内容描述]，下方 1-2 句话提炼核心结论。

• 作者旁白完整保留：识别到的所有作者旁白块（M > 0 时）必须全部保留，不得因"与正文重复"而删减，这是作者的教学设计核心；M = 0 时本规则不适用。

表格美化规范：

• 列对齐：文字列左对齐（默认），数字/百分比/版本号列右对齐（---:），状态/类型/是否等短值列居中（:---:）。
• 表头加粗：表头单元格内容无需额外加粗（Markdown 表头天然加粗），但可在语义重要的列名前加 emoji（如 | ⚙️ 配置项 | 📝 说明 | ✅ 是否必填 |）。
• 单元格简洁：每格内容不超过 20 字；超长描述拆为多行列表或移至正文；避免在单元格内嵌套复杂格式。
• 对比型表格：两方对比时，第一列为"维度"，后续列为各方案/对象，方便横向扫读。

代码块美化规范：

• 语言标注必须：```java、```python、```yaml、```sql 等；纯文本结构用 ```（无标注）。
• 代码标题：在代码块上方用 **📄 文件名 / 场景描述** 加粗行作为标题（如 **📄 .claude/skills/api/SKILL.md**），让读者一眼知道这段代码的来源或用途。
• 关键行注释：对代码中不易理解的关键行，在行尾添加 # ← 说明 或 // ← 说明，解释其作用（勿对每行都注释，只注释非显而易见的行）。
• 长代码分段：超过 25 行的代码块，用注释行（# --- 分段标题 ---）在块内分段，方便定位。
• ❌/✅ 对比示例：展示"错误做法 vs 正确做法"时，用两个独立代码块，分别在上方标注 **❌ 不推荐** 和 **✅ 推荐**，而非在同一代码块内混合。

3. 可视化生成 (Visualize)

核心原则：图是为了"看图就懂"，不是装饰。读者扫一眼图就应该明白这个概念/流程/关系，不必回到正文找解释。可视化块不设上限，鼓励多图。

双轨制：本 skill 用两种工具做可视化，必须按 Step 1c / Step 2 的选型表判断用哪种：

• A. HTML/CSS 卡片 —— 多分区陈列、总览信息图、方法论矩阵等"无方向拓扑"的内容
• B. Mermaid —— 流程、时序、状态、决策树、思维导图等"有方向拓扑"的内容

图配文规范（两者共用）：

• 块上方：一句话用 > 📊 [描述] 引用块说明这张图想表达什么
• 块下方：1-2 句话提炼核心结论，不要让图"裸奔"

可视化数量下限：每篇笔记至少 2 个可视化块（Mermaid + HTML 任意组合），且总结章节必须包含 1 个 mindmap。

---

3.A HTML/CSS 卡片（用于多分区信息图）

为什么用 HTML 而不是 Mermaid：Mermaid 是 dagre 自动布局，节点位置由算法决定，做不出"卡片矩阵+色面板+整齐对齐"的设计感。HTML+inline CSS 完全可控，且 Obsidian 原生渲染，无需任何插件。

🚨 铁律 1：HTML 块内禁止出现空行 Obsidian 的 markdown 处理器看到空行会把后面的 <div> 包进新的 <p>，直接破坏 CSS Grid / Flex 的父子关系，导致 grid 退化成单列、flex 间距错乱。所有 <div> 之间不能有任何空行，整个卡片块必须是连续的一整段 HTML。

铁律 2：只用 inline style= 属性 不要在笔记里引入 <style> 标签或外部 CSS——Obsidian 会过滤。所有样式必须写在 style= 内联属性中。

铁律 3：禁止外部资源 HTML 卡片不得引用任何外部 URL（图片、字体、JS）。

两种核心模板：

模板 A1 — 列表卡片（纵向堆叠，每张大卡片内含子标签） 适用于：课程章节总览、五层架构、分区式知识图 结构：外层 flex column 容器 → 每个分区一个色面板卡片 → 卡片内含 header 行（emoji + 加粗标题 + 副标题）和 chips 行（白底色边小标签）

<div style="display:flex; flex-direction:column; gap:10px; margin:1em 0;">
  <div style="background:#FCE4EC; border:2px solid #C2185B; border-radius:10px; padding:14px;">
    <div style="display:flex; align-items:baseline; gap:10px; margin-bottom:10px; flex-wrap:wrap;">
      <span style="font-weight:bold; color:#880E4F; font-size:1.05em;">🧠 第一部分 · 认知篇</span>
      <span style="color:#AD1457; font-size:0.85em;">你是架构师，AI 是团队</span>
    </div>
    <div style="display:flex; flex-wrap:wrap; gap:8px;">
      <span style="background:#fff; border:1.5px solid #C2185B; color:#880E4F; padding:6px 12px; border-radius:6px; font-size:0.9em;">三层分工模型</span>
      <span style="background:#fff; border:1.5px solid #C2185B; color:#880E4F; padding:6px 12px; border-radius:6px; font-size:0.9em;">规范驱动开发 SDD</span>
    </div>
  </div>
  <!-- 下一个分区卡片紧接着写，不能空行 -->
</div>

模板 A2 — 网格卡片（2 列 / 3 列网格，每张同等大小） 适用于：方法论矩阵、能力九宫格、特性对比卡 结构：外层 display:grid; grid-template-columns:repeat(N, 1fr) → 每张卡片同结构（标题 + 描述）

<div style="display:grid; grid-template-columns:repeat(2, 1fr); gap:10px; margin:1em 0;">
  <div style="background:#E8F5E9; border:1.5px solid #2E7D32; border-radius:8px; padding:12px;">
    <div style="font-weight:bold; color:#1B5E20; margin-bottom:6px; font-size:1em;">🧩 三层分工</div>
    <div style="color:#2E7D32; font-size:0.85em; line-height:1.5;">你负责思考<br/>AI / Agent 负责执行</div>
  </div>
  <!-- 下一张紧接着写，不能空行 -->
</div>

卡片配色板（7 色循环，对每个分区/卡片分配一种色组，保持视觉区分度）：

色系	面板底色	边框色	文字色（标题/正文）
粉	#FCE4EC	#C2185B	#880E4F / #AD1457
橙	#FFF3E0	#E65100	#BF360C / #E65100
黄绿	#F1F8E9	#558B2F	#33691E / #558B2F
绿	#E8F5E9	#2E7D32	#1B5E20 / #2E7D32
青	#E0F2F1	#00695C	#004D40 / #00695C
蓝	#E3F2FD	#1565C0	#0D47A1 / #1565C0
紫	#F3E5F5	#6A1B9A	#4A148C / #6A1B9A
琥珀（备用）	#FFF8E1	#F57F17	#E65100 / #F57F17

配色应用原则：

• 每个分区/卡片单独分配一种色组（不要重复，按"粉→橙→黄绿→绿→青→蓝→紫"顺序循环）
• 一个分区内：面板用浅底色 + 中等边框；内部 chips/子卡用白底/浅底 + 同色边框 + 深色文字
• 不同分区色组互不混用

写卡片的硬性要求：

• emoji 图标放在标题前（🧠 🏛 🏗 ⚙️ 🚀 🧪 🎓 🧩 🔍 📈 💬 🚚 🔄 等），帮助分区识别
• 标题用 font-weight:bold；副标题用 0.85em + 中等饱和度色
• 子标签 chip：padding:6px 12px; border-radius:6px; font-size:0.9em
• 卡片整体：border-radius:8-10px; padding:12-14px
• 卡片之间：gap:10px（不要用 margin，用 flex/grid 的 gap）

---

3.B Mermaid（用于流程/时序/状态/决策/思维导图）

Mermaid 适用范围（再次强调）：节点之间有明确方向连接的图——流程、时序、状态、决策、思维导图、类图、ER。 禁止用 Mermaid 画：多分区陈列总览图（用 HTML 卡片）、方法论矩阵（用 HTML 卡片）。

内容类型	推荐图表	Mermaid 语法
流程 / 链路 / 步骤	流程图	graph TD 或 graph LR
时序 / 交互 / 调用链	时序图	sequenceDiagram
思维导图 / 全文俯瞰	思维导图	mindmap
类 / 接口 / 继承	类图	classDiagram
数据模型 / 表关系	ER 图	erDiagram
状态机 / 生命周期	状态图	stateDiagram-v2

🚫 禁止的 Mermaid 反模式：

• ROOT + 树形扇出：用一个根节点连出 N 条边到各个 subgraph 标题节点（如 ROOT --> P1T、ROOT --> P2T…）——这种图视觉噪音极大，且本质上是"分区陈列"，应改用 HTML 卡片
• subgraph 之间用 ~~~ 强连：会让外层 TB 方向覆盖 subgraph 内的 direction LR，导致子项错乱。需要顺序时让 Mermaid 自然按声明顺序排
• subgraph 内子项之间用 ~~~：除非确实需要强制水平线性，否则不要用——会产生意外的不可见连线
• 节点显示标签用单字母：A[X] B[Y] 这种是大忌；节点 ID 可以用字母，但 [...] 内的显示文字必须是有意义的中文/术语

🚨 铁律：节点内换行必须用 <br/>，绝对禁止 \n Mermaid 渲染器不识别 \n 转义符——写 A["第一行\n第二行"] 在 Obsidian 里只会原样显示反斜杠 n，完全不换行。正确写法是 A["第一行<br/>第二行"]，且节点标签须用双引号包裹。

❌ 错误（常见踩坑）：

S1["第一步\n项目骨架\nVue3+Vite"] --> S2["第二步\naxios层"]

✅ 正确：

S1["第一步<br/>项目骨架<br/>Vue3+Vite"] --> S2["第二步<br/>axios层"]

图表详细度要求：

• 节点标签自带语义：❌ A[模型层] → ✅ A["模型层<br/>提供 LLM 能力"]
• 边必须带标签：❌ A --> B → ✅ A -->|调用| B，让人不用看正文也能读懂连线含义
• 决策点用菱形 + 分支标签：A{需要异步?} -->|是| B[消息队列] A -->|否| C[同步调用]
• 关键节点用色彩区分：起点绿、核心蓝、结果橙、风险红（见统一色板）

统一色板（Mermaid 节点高亮）：

节点语义	颜色	样式写法
起点 / 入口	绿色	fill:#4CAF50,stroke:#388E3C,color:#fff
核心概念 / 重点	蓝色	fill:#2196F3,stroke:#1565C0,color:#fff
结果 / 输出	橙色	fill:#FF9800,stroke:#E65100,color:#fff
风险 / 警告	红色	fill:#f44336,stroke:#B71C1C,color:#fff
普通节点（默认）	浅灰	不加 style，使用 Mermaid 默认

各图表类型细化规范：

• graph TD：流程首选，链路/对比选 graph LR
• sequenceDiagram：参与者名称使用中文；消息描述简短（≤ 15 字）；用 Note over 标注关键说明
• mindmap：根节点为文章核心主题；第二层为各 ## 章节；第三层为关键要点；层级不超过 4 层。总结章节的 mindmap 应覆盖全文所有 ## 章节
• stateDiagram-v2：明确 [*] 起止；转移条件写在箭头上
• 复杂图（>8 节点）用 subgraph 分组名 归组，但不要在 subgraph 之间加连线——让 dagre 自然排列即可

4. Obsidian 格式化 (Format for Obsidian)

Frontmatter（文件最顶部的 YAML 元数据）：

---
title: "[文章标题]"
course: "[课程名称]"
tags:
  - geektime
  - [技术领域标签，小写+连字符，如 golang / distributed-system / database]
date: [通过 Bash 执行 `date +%Y-%m-%d` 获取的当前日期，格式 YYYY-MM-DD]
source: "[原始mhtml文件名]"
---

可选字段 related / 正文 wikilink：仅当原文明确提到前置/相关讲次（如"详见第 08 讲 Hooks"）且能从文件名推断对应 wikilink 时才添加 frontmatter related 字段或在正文使用 [[讲次号-主题]]；不确定就整字段/链接省略，不要写空数组、占位符或硬编造，避免产生 Obsidian 断链。

Obsidian Callout 块完整规范：

Callout 类型	使用场景	语法示例
[!ABSTRACT]	文章开头一句话摘要	> [!ABSTRACT] 一句话摘要
[!NOTE]	重要知识点、概念定义	> [!NOTE] 核心概念
[!INFO]	关键数据、统计数字、版本信息	> [!INFO] 关键数字
[!TIP]	最佳实践、操作建议、技巧	> [!TIP] 最佳实践
[!WARNING]	常见误区、易错点、注意事项	> [!WARNING] 避坑指南
[!QUESTION]	文末思考题（每题单独一个）	> [!QUESTION] 思考题 1
[!QUOTE]	作者金句、核心洞见原话	> [!QUOTE] 作者原话
[!EXAMPLE]	具体案例、对比举例	> [!EXAMPLE] 示例

折叠 Callout（长参考内容使用，默认收起）：

> [!NOTE]- 完整配置参数速查（点击展开）
> 此处放详细的配置表格或长列表...

在 [!TYPE] 后加 - 表示默认折叠，+ 表示默认展开。适用于 frontmatter 字段速查、权限控制详情等参考型内容。

其他正文格式规范：

• 标题层级：规范使用 H1（#）到 H4（####），H1 仅用于文章主标题。
• 关键词加粗：使用 **文本** 强调核心术语（每段不超过 2 处）。
• 禁止外部资源：正文中不得插入 Base64 图片、外部图片 URL、<img src="http..."、外部 <style> 标签或外部脚本；HTML 卡片的 inline <div>/<span> + inline style= 属性不受此限。

5. 文件写入 (Write File)

• 文件命名规则：[讲次编号]-[简短主题].md

  • 讲次编号：从文章标题前缀提取（如 01、09、23）；无数字编号时保留文字前缀（如 开篇词、热点速递）。
  • 简短主题：4-8 个汉字，概括文章核心，不含特殊字符。
  • 示例：01-你是架构师.md、开篇词-以Claude-Code造简版Dify.md

• 目标目录推导（极客时间课程统一收纳在 260_Courses 下）：若未指定 Target_Directory，按以下步骤推导目录：

  1. 基础路径：/Users/fengyuhao/SecondBrain/200_Learning/260_Courses/
  2. 扫描已有课程目录：用 glob 遍历确认现有的 260X_GeekTime_* 编号序列（已存在：2601 / 2602 / 2603 / 2604 / 2605 / …）：

     for d in /Users/fengyuhao/SecondBrain/200_Learning/260_Courses/260*_GeekTime_*/; do basename "$d"; done
     

     ⚠️ 不要用 ls … | grep '^260…'：用户环境中 ls 被别名为带图标的工具（每个名字前注入一个图标字形），会破坏 ^260 行首锚点导致 grep 漏掉全部已有目录、错误地从 2601 重新开始。glob 直接由 shell 展开，不经过 ls 别名，最稳。取序列中最大编号 + 1 作为新课程编号。
  3. 判断是否新课程：根据课程名（如"AI 重塑测试开发系统实践"），尝试在已有目录中找到匹配（如 2604_GeekTime_AI_Reshaping_Test_Engineering）；找到则复用，否则取下一个未占用的编号（如 2604）并创建新目录。
  4. 命名约定：260<N>_GeekTime_<EnglishCamelOrSnake>。<EnglishCamelOrSnake> 是课程名的英文意译（不是音译，不是拼音），用下划线连接单词，首字母大写。例：
     • "Claude Code 企业级全链路开发实战" → 2603_GeekTime_Claude_Code_Enterprise_Level_End_to_End
     • "AI 重塑测试开发系统实践" → 2604_GeekTime_AI_Reshaping_Test_Engineering
     • "多 Agent 设计工程" → 2602_GeekTime_Multi_Agent_Design_Engineering
  5. 目录不存在时先用 mkdir -p 创建。

  ❌ 禁止：直接在 200_Learning/ 根目录创建中文目录（如 Claude-Code-企业级全链路开发实战）——这会破坏现有 260_Courses/ 收纳体系。

• 将最终 Markdown 内容写入目标目录。

• 写入完成后不要在对话框中打印笔记正文（避免冗余刷屏），但必须继续执行 Step 6 的回读核查并输出 checklist 与完成报告。

6. 后置质量核查 (Post-Write Verification)

通过 Bash 命令核查，禁止用 Read 工具整体回读大文件（文件全文重新进入上下文，叠加前面的 mhtml 原文 + 图片 base64 数据，会直接触发请求体超限错误）。将 <FILE> 替换为笔记绝对路径，逐条执行下方命令，根据输出填写 checklist：

# 核查 1 & 8：字符数（同时验证 > 1000 且 ≥ SLATE_CHARS × 60%）
wc -m <FILE>

# 核查 2：Frontmatter 字段（期望输出 5 行，覆盖 title/course/tags/date/source）
grep -E "^(title|course|tags|date|source):" <FILE>
# 核查 2b：tags 列表非空（期望输出 ≥ 2，至少 geektime + 1 个领域标签）
awk '/^tags:/{flag=1; next} flag && /^[^[:space:]-]/ {flag=0} flag && /^[[:space:]]*-/{count++} END{print count+0}' <FILE>

# 核查 3：章节级标题列表（对照 Step 1 覆盖清单逐一确认）
grep "^## " <FILE>

# 核查 4：可视化块计数
grep -c '```mermaid' <FILE>
grep -c 'mindmap' <FILE>
grep -cE 'display:(grid|flex)' <FILE>

# 核查 6：思考题（原文有思考题时期望 ≥ 1）
grep -c '\[!QUESTION\]' <FILE>

# 核查 7：外部资源污染（三项期望均为 0）
grep -c '!\[\](https://' <FILE>
grep -cF '<img src="http' <FILE>
grep -c '<style>' <FILE>

# 核查 9：Mermaid 节点内 \n 换行（期望为 0；Mermaid 不渲染 \n，必须用 <br/>）
python3 -c "
import re
content = open('<FILE>').read()
blocks = re.findall(r'\`\`\`mermaid\n(.*?)\`\`\`', content, re.DOTALL)
count = sum(1 for b in blocks for line in b.split('\n') if r'\n' in line)
print(count)
"

基于以上命令输出结果执行以下 7 项核查，以 checklist 形式输出结果：

#	核查项	通过标准
1	文件存在且有实质内容	文件可读，字符数 > 1000
2	Frontmatter 完整	包含 title / course / tags / date / source 五个字段；tags 列表至少含 2 项（geektime + 领域标签）
3	章节级覆盖无遗漏	对照 Step 1 的章节级覆盖清单，原文每个有效章节级标题在笔记中有对应章节；扁平叙述型文章则核对 Step 1 识别的每个「逻辑主题块」是否已归入笔记某个 ##/### 节（而非核对字面标题）
4	可视化块充分	① 至少 2 个可视化块（Mermaid + HTML 卡片任意组合），且总结章节必须含 1 个 mindmap；② Mermaid 不出现单字母显示标签（节点 ID 可字母但 [...] 内显示文字必须有意义）；③ 有方向的 graph 箭头中至少 80% 带 |文字| 关系说明；④ HTML 卡片必须用 Step 3·A 的两种模板之一，包含 emoji 图标 + 配色板
5	HTML 卡片块内无空行	用 grep -Pzo '<div[^>]*style="[^"]*display:(grid|flex)[^"]*"[^>]*>[\s\S]*?</div>' 抽取每个卡片容器后，容器内不得有 \n\s*\n（连续两个换行）。这是 HTML 卡片能否正确渲染的硬条件——失败则 Obsidian 会把子 <div> 包进 <p>，破坏 grid/flex
6	思考题处理正确	原文有思考题 → 笔记中有 [!QUESTION] 和折叠参考答案；原文无 → 该项自动通过
7	无外部资源污染	笔记中不含 ![](https://、<img src="http、外部 <style> 标签或外部脚本引用；HTML 卡片的 inline <div>/<span> 不违反此规则
8	内容未过度压缩	笔记字符数（wc -m 统计）≥ Step 1a 记录的 SLATE_CHARS 值 × 60%
9	Mermaid 节点无 \n 换行	所有 mermaid 代码块内的节点标签不含 \n 转义符（期望核查命令输出 0）；换行必须用 <br/>

HTML 卡片空行检查的简化命令（可直接复制执行）：

# 替换 <FILE> 为笔记绝对路径；若有任何输出，说明卡片内存在空行，需修复
python3 -c "
import re, sys
content = open('<FILE>').read()
# 匹配所有 display:grid 或 display:flex 的顶层 div 块
pattern = re.compile(r'<div[^>]*style=\"[^\"]*display:(grid|flex)[^\"]*\"[^>]*>(.*?)</div>\s*(?=<div|\n##|\n---|\Z)', re.DOTALL)
violations = []
for m in pattern.finditer(content):
    block = m.group(0)
    if re.search(r'\n\s*\n', block):
        violations.append(content[:m.start()].count(chr(10))+1)
print('VIOLATIONS at lines:', violations) if violations else print('OK')
"

输出格式（写在完成报告之前）：

## 质量核查结果
- [x] 文件存在且有实质内容（xxxx 字符）
- [x] Frontmatter 完整（tags 列表 N 项）
- [x] 章节级覆盖无遗漏（原文章节级 = H1/H2，共 N 个，笔记已覆盖 N 个）
- [x] 可视化块充分（Mermaid N 个 + HTML 卡片 M 个，含 mindmap）
- [x] HTML 卡片块内无空行
- [x] 思考题处理正确
- [x] 无外部资源污染
- [ ] 内容未过度压缩 ⚠️ 笔记 xxxx 字，原文 xxxx 字，未达 60%
- [x] Mermaid 节点无 \n 换行

核查失败处理：

• 1-2 项未通过：在报告中标出 ⚠️，说明具体原因，提示用户可手动补充
• 3 项及以上未通过：标出 ❌ 并提示"建议重新处理此文件"，列出所有失败项

完成报告：核查 checklist 输出后，紧跟一段简短报告，包含：文章标题 & 课程名、文件完整路径、Mermaid 图表数量及类型、思考题状态。

📜 输出规范与约束 (Rules & Constraints)

• 语言：笔记内容必须使用中文（代码、技术术语、专有名词除外）。
• 准确性：严禁捏造文章中不存在的概念，保持技术严谨性。对于路径、配置项名称、环境变量、数字参数等技术细节，必须与原文完全一致，不得凭印象补全或合并相似内容（如两个不同路径不能合并为同一个）。原文的强调性副词/限定语（如"最重要""最常用""极其关键""必须""绝不"）在提炼时应保留其语气强度，不要弱化（如把"最重要"改写成"较基础"会改变作者的判断），也不要凭空拔高。
• 内容深度：笔记字数不少于原文核心内容的 60%，不允许过度压缩导致关键细节丢失。
• 思考题处理：若文章含"思考题"H2（正式课程讲次通常有），必须完整保留并附参考答案；若文章无思考题（开篇词、热点速递等特殊讲次），跳过该章节，不强制。
• 示例代码语言偏好（重要）：当原文未指定语言、或在回答后续问题时需要自创代码示例（包括思考题参考答案、最佳实践演示、对比示例等），必须使用 Java 或 Python，不得使用 Go。理由：用户日常开发栈为 Java + Python，Go 示例无助于其落地理解。例外情况：① 原文本身就是 Go 代码 → 完整保留原文 Go 代码不翻译；② 原文明确讨论 Go 生态特性（如 goroutine、channel）→ 保留 Go 示例并补一段 Java/Python 的等价实现作对照。