网页内容→结构化学习笔记 模式库#
模式使用指南#
何时参考本模式库#
需要从网页/技术文档/最佳实践指南中提取知识并生成学习笔记时：逐一检查BP-1到BP-2的核心步骤是否已覆盖，AP-1到AP-3是否已规避
评审AI生成的学习笔记质量时：用知识增强四要素检查清单快速判断文档质量等级
规划大型文档生成任务时：按文档体量决策树选择合适的工程范式
优化现有知识库文档质量时：对照KE-4四要素补充缺失的知识增强元素
使用原则#
BP是必要条件而非充分条件：遵循BP不能保证产出优秀笔记，但违反BP几乎必然导致质量问题
AP是红线：出现任一反模式信号必须立即修正，不要交付半成品
体量决策优先：不确定用哪种流程时，先过文档体量决策树
格式锚定先行：生成文档前必须先读取1-2个同类现有文档作为风格参考
前置：内容质量预检（必做）#
在选择工程模式之前，先判断源内容是否值得深度加工：
内容质量 |
判断标准 |
处理方式 |
|---|---|---|
高质量 |
官方文档、权威指南、结构化教程、有明确代码示例 |
使用完整/标准/轻量模式 |
中等质量 |
技术博客、经验分享、观点文章（有实质内容但结构松散） |
使用标准模式，增加批判性标注 |
低质量 |
新闻转载、营销文案、内容碎片、明显事实错误 |
❌ 不做结构化笔记，仅做摘要或跳过 |
内容类型适配：
✅ 技术类（最佳实践、API文档、教程、框架指南）：KE-4全要素适用
🔘 观点类（技术博客、行业分析、方案对比）：术语解释+风险标注必须，场景标注可选
❌ 创意类（散文、故事、营销文案）：不适用本模式库
文档体量决策树#
内容预检通过？
├─ 否 → 跳过或仅做摘要
└─ 是 → 需要生成的文档体量？
├─ <200行（小型信息卡片）
│ └─ 轻量模式：frontmatter+来源块 → 内容整理 → 术语解释≥3个+关键警告标记
├─ 200-1000行（中型专题笔记）
│ └─ 标准模式：spec.md框架（章节大纲+验收标准）→ 生成 → checklist验证 → KE-4（交叉引用≥1）
└─ >1000行（大型体系化学习笔记/多章节指南）
└─ 完整工程模式：格式锚定 → Spec三层规划 → 逐章原子任务 → KE-4全要素（交叉引用≥3）→ 验证闭环
第一部分：最佳实践模式（Best Practices）#
BP-1：Spec前置规划+逐章原子委托模式（Spec-First Atomic Delegation）#
属性 |
值 |
|---|---|
模式ID |
BP-1 |
模式名称 |
Spec前置规划+逐章原子委托（Spec-First Atomic Delegation） |
领域 |
文档工程 & 质量保证 |
优先级 |
P0（>1000行文档）/ P1（200-1000行） |
实现说明："逐章委托"的核心是任务原子化边界——每个任务只处理一个逻辑完整的章节，完成验证后再进入下一个。sub-agent是推荐的执行方式（隔离上下文、质量更稳定），但单Agent逐章完成、甚至人工逐章编写同样遵循此模式。
问题场景#
从网页中提取知识生成大型结构化学习笔记时，如何保证：(1) 内容完整无遗漏；(2) 结构清晰逻辑一致；(3) 代码示例、表格等复杂元素正确保留；(4) 质量可验证可追溯？直接让AI一次性生成4000行文档时，常见问题包括：前半部分质量高后半部分敷衍、章节间格式不一致、代码块遗漏、重复内容未去重、没有验收标准。
典型场景：
官方文档/最佳实践指南的系统性学习笔记（如本次AtomGit案例，4390行）
技术方案深度分析报告（如Karpathy LLM Wiki分析，788行）
多章节教程/手册类文档整理
需要保留大量代码示例和配置模板的技术文档
核心解决方案#
四步闭环工程流程：
步骤1：格式锚定（Format Anchoring）
读取目标目录下1-2个现有文档作为"格式锚点"
观察并对齐：frontmatter字段、来源信息块样式、标题层级、引用格式、代码块语言标注习惯
对于全新目录，读取相邻分类目录的文档作为参考
步骤2：Spec三层规划
spec.md：定义Goals/Non-Goals/Functional Requirements/Non-Functional Requirements/Acceptance Criteria（Given/When/Then格式）tasks.md：将大文档拆分为N个原子任务，每个任务：单一章节、独立测试要求（TR）、明确的验收标准映射（AC-x）checklist.md：生成分类检查清单（内容完整性/代码示例/内容质量/结构格式/文件规范）
步骤3：逐章委托sub-agent执行
按任务依赖顺序逐章委托（每次只处理1个章节）
任务状态用
[ ]→[/]→[x]三态标记追踪每个任务委托时传入：明确的上下文、术语解释要求、代码保留要求、风格一致性要求
前置任务完成验证后再启动下一个任务
步骤4：checklist验证闭环
所有章节完成后，按checklist逐项验证
运行自动化检查（文件名规范、路径位置、格式语法）
人工审阅内容质量和连贯性
工作流示意图#
┌─────────────────────────────────────────────────────────┐
│ 阶段1：格式锚定 │
│ 读取1-2个同类文档 → 确认frontmatter/标题/引用/代码块格式 │
└──────────────────────┬──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 阶段2：Spec三层规划 │
│ spec.md（需求+AC）→ tasks.md（原子任务拆分）→ checklist.md │
└──────────────────────┬──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 阶段3：逐章原子委托 │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Task 1 │───▶│ Task 2 │───▶│ Task N │ │
│ │框架初始化│ │章节1编写 │ │最终检查 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ [ ]→[/]→[x] [ ]→[/]→[x] [ ]→[/]→[x] │
└──────────────────────┬──────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────┐
│ 阶段4：验证闭环 │
│ 自动化检查（文件名/路径/语法）→ checklist逐项验证 → 交付 │
└─────────────────────────────────────────────────────────┘
关键代码/配置示例#
tasks.md 任务格式模板：
## [ ] Task N: [章节名称]
- **Priority**: high | medium | low
- **Depends On**: Task IDs
- **Description**: 具体要做什么、关键术语解释要求、代码保留要求
- **Acceptance Criteria Addressed**: [AC-x, ...]
- **Test Requirements**:
- `programmatic` TR-N.1: 可自动化验证的检查点
- `human-judgement` TR-N.2: 需要人工评审的检查点
- **Notes**: 边缘情况、风险、实现提示
任务状态标记规范：
[ ] = pending（待开始）
[/] = in progress（进行中——委托给sub-agent时）
[x] = completed（已完成且验证通过）
适用边界#
✅ 必须使用完整模式：>1000行、含大量代码示例、多章节、需要团队协作或多轮迭代的文档
✅ 推荐使用标准模式：200-1000行、中等复杂度的专题笔记
❌ 过度工程不适用：<200行的简单信息卡片、单段内容摘要、临时笔记
迁移验证场景#
场景1：AI平台最佳实践指南（首次验证）
任务：AtomGit AI平台8大领域最佳实践学习笔记
体案：4390行，68个代码块，9个章节
Spec拆分：10个原子任务（框架→8个内容章节→总结验证）
效果：内容完整无遗漏，格式统一，代码示例全部保留，重复内容去重处理
场景2：技术方案深度分析（Karpathy案例验证）
任务：Karpathy LLM Wiki方案深度洞察分析
体量：788行，12个分析维度
Spec拆分：9个主任务+多个子任务，33个检查点
效果：维度完备无重叠，批判性思考充分，与内部体系对照分析深入
场景3：技术博客学习Wiki教程（Declarative PU案例验证）
任务：微信公众号文章《HTML 最值得关注的一次升级：声明式局部更新》学习Wiki教程
体量：约850行，11个章节，8个FAQ，6个个人见解
Spec拆分：13个原子任务（框架→10个内容章节→索引更新），35个检查点
特殊实践：首次采用"创建sub-agent + 独立验证sub-agent"分离模式（详见BP-3）
效果：35个检查点全部通过，内容评估三维完整，个人见解有深度
适用边界（v1.1更新）#
✅ 必须使用完整模式：>1000行、含大量代码示例、多章节、需要团队协作或多轮迭代的文档
✅ 推荐使用完整模式（v1.1新增）：≥5章节且>200行的中型文档——案例3证明11章节850行同样受益于完整Spec流程
✅ 推荐使用标准模式：200-1000行、中等复杂度的专题笔记
❌ 过度工程不适用：<200行的简单信息卡片、单段内容摘要、临时笔记
Open Questions 闭环要求（v1.1新增）#
Spec三层规划中的 spec.md 如果包含 Open Questions，必须满足：
每个Open Question在checklist验证前被明确处理（解答或标记为Out of Scope并说明原因）
禁止在任务执行过程中忽略Open Questions
建议在checklist中增加"Open Questions已全部闭环"检查点
BP-2：知识增强四要素模式（Knowledge Enhancement 4-Elements, KE-4）#
属性 |
值 |
|---|---|
模式ID |
BP-2 |
模式名称 |
知识增强四要素（KE-4: Terminology + Scenario + Warnings + Cross-refs） |
领域 |
知识呈现 & 学习体验 |
优先级 |
P0（学习笔记类文档） |
问题场景#
为什么有些技术文档读起来"信息都在但学不会"？纯内容提取和整理只是"信息搬运"，读者需要自己完成术语理解、场景判断、风险识别、知识关联这些认知工作。如何将文档从"信息集合"升级为"认知成品"？
典型场景：
官方文档/最佳实践的学习笔记
技术方案/框架的教程文档
API/工具的使用指南
知识入库类文档（供未来查阅）
核心解决方案#
在内容整理基础上，必须添加四个知识增强元素：
要素1：术语解释（Terminology）
规则：关键专业术语在首次出现时给出1-2句话的简明解释
实现：在术语后用括号或独立句子说明，文末附术语表（>10个术语时）
验收标准：不查阅外部资料即可理解文档核心概念
示例：语义化版本号（Semantic Versioning）——采用"主版本.次版本.修订版本"三段式结构的版本规范…
要素2：适用场景标注（Scenario Labeling）
规则：每个主要方法/实践/配置项标注"什么时候用"
实现：每个三级标题下第一行标注 适用场景：…
验收标准：读者能快速判断某条实践是否适用于自己的项目
示例：适用场景：所有新模型创建、模型重命名、衍生模型命名
要素3：风险/注意事项突出标记（Warnings Highlighting）
规则：警告、限制、陷阱、不推荐做法用统一视觉标记突出
实现：使用
> **注意**：或 ⚠️ 标记，确保不被淹没在正文中验收标准：扫一眼文档就能看到所有关键风险点
示例：⚠️ 重要提示：一旦版本标签推送到远程仓库，禁止修改或删除…
要素4：交叉引用（Cross-references）
规则：相关章节间建立显式关联引用，形成知识网络
实现：在相关处添加"参见X.X节"或"与Y章节配合使用"
验收标准：≥1处（<500行）/≥3处（>1000行）交叉引用，连接不同领域的相关知识
示例：Space应用的环境变量配置参见6.1.1节敏感信息保护
KE-4验收检查清单#
要素 |
检查项 |
<500行轻量/标准 |
>1000行完整 |
|---|---|---|---|
术语解释 |
关键术语首次出现有解释 |
≥3个术语有解释 |
≥10个术语+文末术语表 |
适用场景 |
主要实践有场景标注 |
≥3个核心实践有标注 |
100%主要实践有标注 |
风险标记 |
警告/限制有突出标记 |
关键警告有标记 |
所有警告/限制/最佳实践均有标记 |
交叉引用 |
相关章节有引用链接 |
≥1处交叉引用 |
≥3处且引用准确有用 |
体量适配原则：交叉引用数量与文档章节数正相关，不少于"章节数/3"处（向上取整）。
文档质量等级判定#
KE-4覆盖度 → 文档等级
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4/4要素齐全且达标 → A级（可直接用作学习材料）
3/4要素达标 → B级（基本可用，建议补充缺失要素）
2/4要素达标 → C级（信息整理，非学习笔记）
1/4或0/4达标 → D级（内容复制，需重新加工）
适用边界#
✅ 必须包含KE-4：学习笔记、教程、入门指南、知识入库文档
🔘 选择性包含：API参考文档（术语解释+注意事项必须，场景和交叉引用可选）
❌ 不需要：纯数据文件、配置文件模板、临时会议记录
迁移验证场景#
场景1：AI平台最佳实践笔记（首次验证）
KE-4实现：16个术语解释、所有主要节有适用场景、⚠️标记突出、3处交叉引用+术语表
质量等级：A级
效果：可直接作为AtomGit平台的学习材料使用
场景2：技术方案深度分析（Karpathy案例验证）
KE-4实现：关键概念解释、场景分析隐含在对照分析中、局限性/风险明确标注（8项）、与SpecWeave内部体系关联
质量等级：A级（分析维度更丰富，术语和风险标注充分）
场景3：技术博客学习Wiki教程（Declarative PU案例验证）
KE-4实现：技术术语解释（Declarative Partial Updates/Shadow DOM/SSE等）、7类适用场景表格、实验阶段警告多处标注、资源链接章节交叉引用官方文档
质量等级：A级（8个FAQ+6个个人见解增强了知识深度）
效果：35个检查点全部通过，内容评估三维完整
BP-3：实施与验证分离模式（Implementation-Verification Separation, IVS）#
属性 |
值 |
|---|---|
模式ID |
BP-3 |
模式名称 |
实施与验证分离（IVS: Implementation-Verification Separation） |
领域 |
质量保证 & 流程工程 |
优先级 |
P1（所有Spec驱动文档）/ P0（>1000行大型文档） |
首次验证 |
案例3（Declarative PU Wiki，2026-08-01） |
问题场景#
Spec驱动文档创建流程中，创建者自我验证容易产生盲区：
格式盲区：创建者习惯了自己的格式选择，看不出与项目规范的不一致
遗漏盲区：创建者记得"应该有这个章节"但实际可能漏写，自我检查时大脑会"补全"记忆
逻辑盲区：创建者理解自己的逻辑链条，但读者可能无法跟随——自我验证无法发现
标准盲区：创建者可能潜意识降低标准（"差不多就行了"），独立验证者按检查清单严格判断
核心解决方案#
三步分离验证流程：
步骤1：创建者完成实施
sub-agent A（或主agent）按tasks.md逐章完成文档创建
创建者可以边创建边自检，但不作为最终验收依据
步骤2：独立验证者执行验证
由独立的sub-agent B（或另一个agent会话）执行验证
验证者只看checklist.md和最终文档，不看创建过程中的上下文
逐项检查每个检查点，返回"通过/未通过+原因"
步骤3：反馈修复闭环
验证结果反馈给主agent
未通过的检查点创建修复任务
修复后重新验证（可只验证未通过项）
工作流示意图#
┌─────────────────────────────────────────────────┐
│ 阶段1：实施（sub-agent A） │
│ 按 tasks.md 逐章创建 → 自检 → 标记完成 │
└──────────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────────┐
│ 阶段2：独立验证（sub-agent B） │
│ 只看 checklist.md + 最终文档 → 逐项验证 → 报告 │
└──────────────────────┬──────────────────────────┘
▼
┌─────────────────────────────────────────────────┐
│ 阶段3：反馈修复（主 agent） │
│ 收集未通过项 → 创建修复任务 → 重新验证 │
└─────────────────────────────────────────────────┘
适用边界#
✅ 必须使用：>1000行大型文档、多人协作项目、对外交付文档
✅ 推荐使用：所有Spec驱动文档（200行以上）、有35+检查点的任务
🔘 可选使用：<200行简单文档（创建者自检+主agent抽查即可）
❌ 不适用：纯个人笔记、临时草稿、实验性代码
反模式（不要这么做）#
❌ 自我验证跳过独立验证：创建者标记"已验证"但实际只自检——盲区无法发现
❌ 验证者参与创建：验证者同时参与文档编写，失去独立性
❌ 验证者看创建上下文：验证者看了创建过程会受"确认偏误"影响
❌ 验证后不修复：发现未通过项但不创建修复任务——验证失去意义
检验标准#
[ ] 验证者与创建者是不同的agent/会话
[ ] 验证者未参与文档创建过程
[ ] 每个检查点有明确的"通过/未通过"判定
[ ] 未通过的检查点有修复任务并已闭环
[ ] 最终所有检查点全部通过
迁移验证场景#
场景1：技术博客学习Wiki教程（首次验证）
任务：Declarative Partial Updates Wiki教程创建
实施：sub-agent A创建11章节文档
验证：独立sub-agent B验证35个检查点
效果：35个检查点全部通过，验证报告详细列出每项判定和依据
待验证场景：
场景2：>1000行大型文档的验证分离（需未来案例验证）
场景3：多人协作项目的验证分离（需未来案例验证）
第二部分：反模式（Anti-Patterns）#
AP-1：无规划直接生成模式（No-Spec Direct Generation）#
属性 |
值 |
|---|---|
反模式ID |
AP-1 |
反模式名称 |
无规划直接生成（No-Spec Direct Generation） |
严重等级 |
P0（大型文档） |
识别信号#
任务描述就是"帮我分析这个网页生成笔记"，没有spec/tasks/checklist
一次性让AI"生成完整文档"而不拆分
没有定义验收标准，"生成完看看"就是验收
生成结果<200行但原网页内容远多于此
文档后半部分明显比前半部分简略（注意力衰减）
后果#
内容遗漏：关键章节/代码示例/注意事项被遗忘
结构混乱：章节间逻辑不清，格式前后不一致
质量波动：前半部分精心写，后半部分草草收尾
返工成本高：发现问题后需要大段重写，无法局部修复
无法验证：没有检查清单，不知道什么算"做完了"
修复方案#
立即停止，回退到BP-1：先用10%时间做Spec三层规划，再按原子任务逐章生成。<200行文档可使用简化版（只写spec.md列出章节大纲，然后直接生成）。
AP-2：无格式锚定自由发挥模式（No-Anchor Free Style）#
属性 |
值 |
|---|---|
反模式ID |
AP-2 |
反模式名称 |
无格式锚定自由发挥（No-Anchor Free Style） |
严重等级 |
P1 |
识别信号#
新文档的frontmatter字段与同目录文档不一致
标题层级使用混乱（有的用###有的用####开始正文）
代码块没有语言标注
来源信息格式与同目录其他文档不同
读者反馈"这个文档和其他文档风格不一样"
后果#
知识库文档风格参差不齐，读者需要反复适应不同格式
自动化索引生成/文档处理工具可能因格式不一致而出错
维护成本增加：后续统一格式需要批量修改
专业感降低：格式不统一暗示内容质量也可能不一致
修复方案#
在生成第一行内容之前，先读取1-2个目标目录下的现有文档，记录其frontmatter格式、标题层级起点、引用样式、代码块习惯，作为生成的"格式锚点"。
AP-3：纯内容搬运无增强模式（Content Dump Without Enhancement）#
属性 |
值 |
|---|---|
反模式ID |
AP-3 |
反模式名称 |
纯内容搬运无增强（Content Dump Without Enhancement） |
严重等级 |
P1（学习笔记类） |
识别信号#
文档只是对原网页内容的重新排版/分段
没有任何术语解释，读者需要频繁Google
没有标注"什么时候用"，只有"怎么做"
没有警告/注意事项，踩坑点完全不提示
章节之间各自独立，没有任何关联引用
读完感觉"信息都看到了但还是不会用"
后果#
学习效率低：读者需要自己完成大量认知加工
信息价值低：和直接看原网页没有本质区别
知识库沦为"网页镜像"：没有增量价值
可查性差：术语不懂、场景不明、风险不知，遇到问题还是要翻原文档
修复方案#
按BP-2的KE-4四要素逐项补充：先加术语解释（最容易），再加适用场景和风险标记，最后添加交叉引用。补充后用KE-4检查清单重新评级。
AP-4：Open Questions 不闭环模式（Unclosed Open Questions）#
属性 |
值 |
|---|---|
反模式ID |
AP-4 |
反模式名称 |
Open Questions 不闭环（Unclosed Open Questions） |
严重等级 |
P2 |
首次识别 |
案例3（Declarative PU Wiki，2026-08-01） |
识别信号#
spec.md 包含 Open Questions，但 tasks.md 中没有处理这些问题的任务
checklist.md 没有"Open Questions 已闭环"检查点
任务全部完成后，Open Questions 仍为未勾选状态
复盘时才发现 Open Questions 被忽略
后果#
未决问题遗留：spec 生命周期结束后，Open Questions 仍未被处理
完整性受损：文档可能遗漏本应包含的内容（如果 Open Questions 答案为"是"）
可追溯性降低：未来读者不知道为什么这些问题没有被处理
潜在返工：如果后续发现这些问题需要处理，可能需要重新启动 spec
修复方案#
在 BP-1 的 Spec 三层规划中增加 Open Questions 闭环要求：
spec.md 中的每个 Open Question 必须在 checklist 验证前被明确处理
处理方式：解答（转为需求）或标记为 Out of Scope（说明原因）
在 checklist.md 中增加"Open Questions 已全部闭环"检查点
复盘时检查 Open Questions 是否被正确处理
附录：快速参考卡#
网页→学习笔记标准流程（7步速查，v1.1更新）#
内容预检：判断源内容质量/类型，低质量跳过或仅做摘要
锚定格式：读取同目录1-2个文档，对齐风格
选择模式：按体量决策树选择轻量/标准/完整模式
规划Spec：写spec.md（需求+AC+Open Questions）、tasks.md（原子任务）、checklist.md（检查点+Open Questions闭环检查）
逐章生成：按依赖顺序逐章完成，三态标记追踪
增强KE-4：根据体量添加对应数量的知识增强要素
独立验证（v1.1新增，BP-3）：由独立agent验证checklist，非创建者自检
闭环交付：处理Open Questions（解答或Out of Scope）→ 修复未通过项 → 最终验证通过
投入产出参考#
文档体量 |
预检投入 |
规划投入 |
生成投入 |
验证投入 |
KE-4要求 |
预期等级 |
|---|---|---|---|---|---|---|
<200行 |
5% |
0%（无Spec） |
80% |
15% |
术语≥3，警告标记 |
B-C级 |
200-1000行 |
5% |
10% |
70% |
15% |
四要素基础版（交叉引用≥1） |
A-B级 |
>1000行 |
3% |
17% |
65% |
15% |
四要素完整版（交叉引用≥3） |
A级 |
KE-4快速自检（30秒）#
[ ] 看到陌生术语有解释吗？
[ ] 知道这条实践什么时候用吗？
[ ] 关键风险点一眼能看到吗？
[ ] 相关内容有提示去哪儿看吗？
四个问题全"是" → 文档合格。