First Shot — 技术全景学习文档：深度研究后成文

用户点名「讲透 / 完整了解 / 系统学习某项技术」时：先深度研究，摸清知识地形，再据地形决定结构与行文，产出单篇全景深入的学习文档交付思源。完成标准：读者读完这一份，能向同事讲清楚这项技术是什么、怎么运作、为什么这样设计、何时该用何时不该用。

设计原则：目标导向，形态自主

**不变的是四条目标底线，可变的是结构与行文。**不同技术的知识构成不同，可讲的东西不同，文档形态应随之变化。本技能不提供填空模板：骨架只是完整性参考（references/checklists.md），风格原型只是校准参考（见文末）。

目标底线（任何一条不满足即返工）

1. 真：关键事实（数字、版本、年代、规格、性能）必须有来源——≥2 个独立来源，或 1 个一手来源（官方文档、RFC/PEP/ISO 规范、论文、官方博客）。必须真的去搜，不得只凭模型记忆。检索不到就写「约 / 未核实」，禁止编造；二手统计注明口径。
2. 全：宁全勿略、不限字数。这项技术「可说的」都要说到，一个主题没讲透不许开下一个；禁止为控篇幅点到为止。
3. 懂：以读者起点行文（默认：会编程的工程师、非本领域专家）。术语零突然：首次出现当场一句话解释或给章节指针；缩写首现写全拼——中文「全拼（缩写）」如远程直接内存访问（RDMA），外文「缩写（Full Name，中文含义）」如 PFC（Priority-based Flow Control，按优先级流控），此后统一只用缩写。禁止前向引用：不得使用尚未讲过的概念。讲机制靠拆解不靠降智类比：默认直接拆参与者、数据流、状态转换、约束条件；确需类比必须过例子四条标准（红黑榜见 references/checklists.md），「就像寄快递」式表面类比出现即删。
4. 深：每个机制至少讲到「为什么这样设计」一层——痛点、备选方案、代价。讲性能 / 规模 / 时间线必须给数字和单位，不许只用「很快」「广泛使用」。

另外两件必做：写完全篇必须核查（阶段四）；终稿必须过 humanizer-zh。

方法主线：五个阶段

阶段一 研究定形

1. 定位消歧：是哪个技术（语言 vs 工具 vs 协议 vs 商业产品）、哪个版本（默认当前稳定版）。
2. 摸知识地形：这项技术的知识由哪几类构成、每类有多少可说、证据在哪。五类知识「可说的」不一样：

3. 权威调研（必做，没有证据清单不动笔）：WebSearch 定位一手来源 → WebFetch 通读。产出三样：编号证据清单（直接进参考资料章）、不确定项清单（决定正文所有「约 / 未核实」的落点）、知识地形图（哪类知识材料厚可深写、哪类薄需补搜或明说不讲）。
4. 研究预算与技术复杂度、目标篇幅成正比；大技术、多争议、快速演进的领域，重度文献研究升级走 deep-research。
5. 操作坑：WebSearch 整批失败重试单条即可；WebFetch 超时就 curl 拉原文到本地再 Read。

阶段二 结构设计（形态由地形决定）

• 据知识地形图定章节、排序与篇幅重心；按依赖排序（读者永远用旧概念学新概念），机制类知识从端到端主链路切入。
• 参考骨架与文档信息头模板见 references/checklists.md（知识类 / 工具类两套）。它们是完整性参考，不是填空模板：可合并、可拆分、可增删章节。
• 完整性自查（写大纲时对一遍，交付前再对一遍）：动机与历史 / 核心概念 / 端到端机制 / 设计取舍 / 上手实操 / 生态与工具 / 横向对比 / 生产陷阱 / 端到端案例 / 方法论清单 / 练习自测 / 总结 / 术语表 / 编号参考 / 文档说明。缺哪块，要么补，要么在地形图上有「不讲 / 略讲」的明确理由。
• 一次性 Write 本地骨架文件（含各章占位标记）。本地 md 全程是基准版。

阶段三 逐章成文

• 长文分批落盘：写完一章 Edit 落盘一章；禁止试图一口气输出全文导致截断。
• 每章动笔前问一句：这一章的知识属于哪类，起手式对位吗？材料够吗（不够回阶段一补搜）？
• 行文工具箱（按需取用，唯一标准是四条目标底线）：
  • 短句直给，一段一个意思；枚举、清单、因果链可用 text 代码块逐行呈现。
  • 数字算给读者看：给推导过程（如尾延迟 1−0.99¹⁰⁰≈63%），不只给结论。
  • 知识点六问：是什么 / 为什么需要它 / 怎么工作 / 何时用 / 何时不用 / 常见误区。
  • 工具与实践类先给最小可用路径（装 → 跑通 → 看到结果），再回头讲原理；动手实验优先找无硬件等价物，并声明软件实现的性能不代表硬件。
  • 旁支解释（术语深挖、类比、大段注）写成独立注释块（思源 callout，markdown 形态即 > [!NOTE] 引用块），主叙事保持线性自包含。
  • 配图可选；配了就图文互锁（每图被正文引用，图内口径与正文一致），绘制归 visual-diagrams。
  • 系列文档时：章节编号跨份对齐；多主题对比表只维护一份；每份自包含（公共前置知识写精要版内置）。

阶段四 核查（必做，全量）

• 事实门：关键数字 / 版本 / 年代 / 规格逐条对照证据清单（全量，非抽查）；确定程度的用词与证据强度一致。
• 术语门：以读者起点通读全文，逐个首现术语查当场解释与全拼；全文同物同名。
• 格式门：标题锚点、表格、代码块完好；配图全被正文引用。
• 改正 → 定稿；《文档说明》写 AI 辅助声明 + 核验范围 + 版本基准日期。逐项清单见 references/checklists.md。

阶段五 润色与交付

• 终稿整体过 humanizer-zh；代码块、路径、表格数据按其保护规则保持原样。
• 交付思源：整篇 markdown 一次 createDocWithMd（整篇一次优于逐块追加），exportMdContent 断言章节数与块数，最后 reloadUI（reload 后内核短暂无响应，重试即可）；标题不带 /；配图上传走 file[]。API 参数与坑位手册归 siyuan-kernel-ops。落点笔记本就近推断，推不出问一次。
• 本地 md 与思源版并存时，以思源版为真相源（用户手改优先，双标记核查归 siyuan-kernel-ops）。

校准参考（不是模板）

「细、完善、好懂」做到位长什么样，看思源原型：/分布式计算/分布式系统与计算/可观测性与调试（doc id 20261020150346-loafyn7，约两万字）。拿不准细到什么程度、机制怎么讲才好懂时，用 siyuan-kernel-ops 的 sy.py 导出通读找感觉。它是一个做到位的实例，不是必须模仿的结构或风格——换一类知识（如工具类、算法类），形态就该不同。已知缺陷：其 9.6 节有一处生成残留（空 NOTE「antigravity 就是」），不要学。

指针（规则只在属主技能维护）

• 完整性参考骨架、信息头模板、例子红黑榜、核查清单 → references/checklists.md（本技能属主）
• 思源 API 与坑位 → siyuan-kernel-ops；重度文献调研 → deep-research；配图 → visual-diagrams；语言润色 → humanizer-zh