总结经验 (Summarize Experience)

当遇到需要多次尝试才解决的非平凡问题时，使用此工作流总结经验教训。

何时使用此工作流

✅ 应该总结的情况：

• 问题需要 2 次以上尝试才解决
• 涉及复杂的系统交互或隐蔽的机制
• 错误方案会导致严重后果（如内容消失、渲染错误）
• 经验对未来类似问题有参考价值

❌ 不需要总结的情况：

• 简单的 typo 或配置错误
• 一次就成功的常规修复
• 已有类似经验记录的问题

总结步骤

1. 阅读现有经验

# 查看 LEARNING.md 现有内容，避免重复
cat ai_must_read/LEARNING.md | less

2. 确定归类章节

现有章节：

• 一、Lua 与 LaTeX 交互：Lua/TeX 双向通信问题
• 二、expl3 语法陷阱：expl3/xparse 特殊行为
• 三、LuaTeX 特有机制：节点、属性、字体等
• 四、PDF 渲染问题：PDF 输出、颜色、绘制顺序
• 五、参数传递链路：跨层参数传递
• 六、特殊功能实现：复杂功能的实现模式

3. 编写简洁总结

格式模板：

### X.Y 问题标题

**问题**：一句话描述现象。

**根本原因**：
- 原因 1
- 原因 2

**错误方案**：
\`\`\`lua
-- ❌ 说明为什么错误
code_example()
\`\`\`

**正确方案**：
\`\`\`lua
-- ✅ 说明关键点
correct_code()
\`\`\`

**关键点**：
- 要点 1
- 要点 2

**适用场景**：何时需要此方案

4. 合并重复内容

如果新经验与现有条目相似：

• 扩展现有条目而非新增
• 合并示例代码
• 统一术语和表述

5. 更新 LEARNING.md

# 编辑文件
vim ai_must_read/LEARNING.md

# 或使用 Edit 工具直接修改

示例：跨页颜色保持

问题识别：

• 侧批和夹注跨页时颜色丢失
• 第一次尝试：直接在 render 中检测属性并包裹 → 内容消失
• 第二次尝试：通过 layout_map 传递颜色 → 成功

总结要点：

• 根本原因：group_nodes_by_page() 断开节点链接，颜色堆栈失效
• 正确方案：通过 layout_map 传递颜色，每页独立应用
• 关键：使用 q/Q PDF 命令包裹，不依赖跨页状态

归类：PDF 渲染问题（第四章）

记录位置：4.5 跨页颜色保持

注意事项

• 简洁优先：每个经验控制在 15-30 行
• 突出对比：用 ❌/✅ 标记错误/正确方案
• 可操作：提供具体代码示例，而非抽象描述
• 避免冗余：检查是否与现有条目重复

相关文件

• /ai_must_read/LEARNING.md - 经验文档
• .claude/skills/summarize-experience/SKILL.md - 本 skill