Work With AI Doc Workflow

AI 技术文档工作流

把研究与工程材料写成一篇读者愿意顺着读完、读完能复述主线、需要时还能回到证据，也能感到背后有一个真实作者在思考的文章。

最高优先级

先守住事实准确、来源边界、用户意图、隐私安全和仓库规则。在这些硬边界内，按以下顺序做取舍：

1. 可读性、思路流畅性与活人感：读者不需要反复回看，能沿着问题自然走到结论，也能看见真实的判断、经历和边界。
2. 必要的技术完整性：足以理解、判断和复现当前主题，不追求百科全书式覆盖。
3. 形式与流程覆盖：标题、表格、公式、伪代码、配图和检查项只在确实帮助理解时出现。

不得为了完成清单而堆砌机制卡、五联图、对象表、论文图或层层标题。后台分析可以完整，正文必须克制。

每次写作都先阅读并执行 references/readability-flow-contract.md。

发布契约

文章默认发布到 Dev。 写作前必须阅读并执行 独立审核与 Dev 发布约定。设置 review_status: pending（保留已有 private / withdrawn）；写完后必须由独立子代理使用 $article-readability-check 审核最终版本。即使审核通过，也不自动转为 Public。

用户未明确要求草稿、只写本地文件或不要发布时，调用本 Skill 即授权提交和非强制推送本次有意创建或修改的文件到远端 main。

开始编辑前：

1. 记录 git status --short --branch、当前分支、远端和 upstream。
2. 遇到 detached HEAD 时先创建 codex/ 前缀任务分支；遇到未解决的 merge、rebase 或冲突时停止编辑并报告。
3. 记录所有预先存在的工作区改动，视为用户所有的无关内容。
4. 获取远端 main 并记录提交。
5. 检查 origin/main..HEAD 的提交和路径；不得把本任务未授权的本地提交带入远端 main。
6. 如果另一工作树已检出 main 且存在无关改动，不修改那棵工作树；在当前任务分支合入 origin/main，最后使用 HEAD:main 发布。

不得强制推送、改写历史、暂存无关文件、泄露凭据，或用功能分支和 Pull Request 冒充完成。认证、分支保护、缺少远端或无法安全解决的冲突阻止发布时，准确报告本地提交与远端状态。

既有文章保全

修改既有文章时，默认执行补充与重组，不执行压缩性重写。

编辑前记录不可变基线：

• 行数、标题树和 front matter；
• 代码块、公式、表格、admonition、脚注和引用；
• 每张图片的 URL、alt text、图注、顺序及附近解释。

保留有用正文、例子、代码、图片、引用、限制条件和历史背景。需要调整主线时，优先移动完整内容块或在最窄位置插入。只有用户明确要求、内容完全重复，或一手证据证明其错误且保留了更正记录时才删除。

暂存前逐项审阅所有删除的非空行，并比较修改前后的图片清单。未经授权的图片、URL、alt text 或图注变化视为失败。最终交付说明原始与最终图片数量、删除项及重组范围。

写作流程

1. 明确读者承诺

读取 AGENTS.md、archetypes/default.md 和 skills/hugo-tech-blog-writer/SKILL.md，然后先写五行内部工作笔记：

目标读者：谁会读，已经知道什么
核心问题：读者为什么现在需要这篇文章
一句话主线：文章最终要让读者理解或做出什么判断
文章原型：调查实验 / 产品体验 / 现象解读 / 工具分享 / 方法论分享 / 机制解释 / 方案比较 / 研究综述
作者声音：可使用的真实经历、判断、情绪节点和不确定性

文章原型只决定叙事重心，不是固定模板。无法用一句话说清主线时，不要开始写正文。

2. 建立证据账本

先调研，再下结论。当前事实、论文、API、项目行为或源码实现需要联网或读取一手材料验证时，优先使用官方文档、论文原文、项目仓库和固定版本源码。

为重要主张建立内部账本：

主张 -> 类型（事实 / 推导 / 建议） -> 来源 -> 证据强度 -> 适用边界 -> 目标段落

• 区分来源事实、基于来源的推导、本地工作流约定和个人建议。
• 弱证据、跨论文比较和未测量效果必须明确降级表达。
• 不编造实验结果、框架行为、用户经历、引语或个人感受。
• 只有主题需要长期维护时才使用 LLM Wiki：原始资料放入 obsidian-vault/.raw/，结构化理解放入 obsidian-vault/wiki/，并更新相关索引；不要把 Wiki 维护变成每篇文章的形式任务。

3. 设计问题链

不要按资料出现顺序或旧稿标题顺序机械组织文章。围绕一句话主线，列出读者会自然追问的问题，并让后一节由前一节推出。

常见推进关系是：

具体问题或反常现象
    -> 为什么旧方法不够
    -> 新方法的直觉是什么
    -> 关键对象如何变化
    -> 证据支持到哪里
    -> 应该怎样选择或实践
    -> 代价、限制与未决问题是什么

只保留真正改变读者问题的标题。删除空壳父标题，合并只有一句话的薄标题，给可独立检索的并列方法同级标题。标题深度表达语义关系，不用于制造视觉层次。

为每个拟定章节写一张内部小卡：

本节回答的问题 -> 一句话答案 -> 使用的例子或证据 -> 如何接回主线 -> 下一问

4. 沿认知路径起草

• 从材料中最具体的矛盾、失败、现象、场景或问题切入；没有真实场景时直接提出问题，不编造故事。
• 先让读者看见问题和物理直觉，再引入术语、公式、shape、collective 或实现细节。
• 根据素材选择调查实验、产品体验、现象解读、工具分享、方法论分享或技术解释的主叙事弧，不把不同姿态混成统一报告。
• 保留来源支持的真实第一人称、好恶、犹豫、失败和情绪节点；允许自然口语、自我修正和短句停顿，不把作者磨平成中性旁白。
• 一个段落只完成一个认知动作。长短句与长短段自然交替，关键判断可以单独成段；疑问句用于替读者问出下一问并完成转向。
• 偏离主线补充背景后，用一句简短的回扣句说明它与核心问题的关系。
• 让知识在当前问题需要它时自然出现，不用“下面开始科普”切断主线。
• 使用具体模型、框架、算子、对象和版本名，避免“某种方案”“相关技术”一类空泛代称。
• 给出判断前先具体呈现反方或普通读者的合理处境；有实验、体验或排障材料时展示实际过程，不只汇报最终结论。
• 多个产品、模型或案例按基础、进阶、意外发现逐一展示，每一项增加新的观察；比较表放在发现过程之后。
• 方法论和教程给出读者当天能执行的动作，同时坦诚学习曲线、时间成本与失败点。
• 列表只承载真正并列的对象或步骤；表格只承载需要横向对齐的比较；admonition 只承载值得打断阅读节奏的提醒。
• 不用总览表替代解释。先逐个讲清独立方法，再进行横向综合。
• 文化、历史或哲学参照只有在能自然解释当前问题时才引入，不为了升华而升华。
• 结尾优先回到开头的场景、问题或意象，说明已经回答什么、尚未证明什么，以及读者下一步能做什么；不要在结尾突然引入新论点。

5. 解释技术方法

文章包含命名概念、算法、优化、架构路径或框架后端时，阅读并执行 references/beginner-technical-method-contract.md。

必须做到：

• 区分抽象概念、可复用机制和特定框架补丁。
• 从瓶颈与直觉开始，再解释关键对象、过程和效果边界。
• 给出足以消除关键歧义的小例子；涉及多 Rank、切分、cache 或 state 时，说明什么留在本地、什么移动、什么复制、什么聚合。
• 说明实现归属、适用条件、新成本、迁移代价，以及证据证明和没有证明的部分。

机制解释的深度与文章问题成比例。伪代码、shape 表和内存账本是可选表达工具，不是每个方法的固定配额。

6. 解释公式与源码

正文包含公式、源码、伪代码、tensor、cache、state 或计算图时，阅读并执行 references/formula-code-diagram-contract.md。

先在后台建立完整对象账本，再选择读者理解当前结论所必需的对象进入正文。定义首次出现的符号和轴，区分语义等价式与实际运行路径，并说明哪些 tensor 真正物化、哪些只是 view 或代数解释。

允许在源码摘录中省略与当前机制无关的日志、校验或样板代码，但必须标明省略范围；不得用 ... 隐藏会改变所讲机制的输入、分支、shape 变换、状态更新或输出。

7. 按认知障碍配图

先写出每张图要解决的唯一阅读问题。无法写清时，不画。

• 文章级认知锚点或前后对比使用 skills/ian-xiaohei-illustrations/SKILL.md。
• tensor、cache、state、控制流或源码机制图使用 $fireworks-tech-graph；明确需要 .drawio 时才使用 $drawio-skill。
• 论文原图只有在承担方法来源或效果证据时才使用 skills/paper-figure-supplement/SKILL.md，并说明它证明与没有证明什么。

根据障碍选择最少视图：看不懂变化就画前后对比，看不懂因果就画逻辑链，看不懂顺序与并发就画流程或时序，看不懂 shape 与状态就画数据流。不要强制每个方法都配齐所有视图，也不要把多个小图拼成难以阅读的检查表。

技术图保留可编辑 SVG 和 1920px PNG，检查中文字体、裁切、重叠、箭头、shape、对象生命周期和正文一致性。上传时使用 skills/image-cloud-uploader/SKILL.md，只在上传成功且 URL 一一对应后替换 Markdown 链接，并保留本地源文件。

8. 写入 Hugo

• 按 archetypes/default.md 维护 front matter，重点检查 title、categories、series、tags 和 summary。
• 按独立审核约定设置 Dev 状态；保留元数据不意味着沿用旧版本的公开资格。
• title 使用简练英文关键词短语，正文标题使用简洁中文。
• !!! abstract "导言" 后紧跟 <!-- more -->。
• 保持标题尽量浅，通常使用 ## 和 ###；更深层级只用于真实的独立分支。
• 中英文混排保持空格和术语一致，不使用表情符号或口号式表达。

分类按文章的主要可复用主题与瓶颈选择一个语义主类：

• 1-AI Model Architecture
• 1-Distributed Parallelism
• 1-Operator Development
• 1-AI Systems
• 1-Agent Workflow

0-TOP 只是精选导航叠加层，必须位于语义主类之后。由于首个分类参与文章 URL，批量修改主分类前记录旧、新路由并验证重定向需求。

9. 沉淀可复用工作流

用户要求把重复 prompt、研究方法或写作流程安装为 Skill 时，使用 $skill-creator 在本 Git 仓库中创建或更新规范源，并通过安全符号链接安装到全局 Skill 目录。保留现有资源和无关改动，不原地修改系统内置 Skill。

只沉淀已经在本次实践中证明必要的规则。把稳定判断写进 Skill，把主题知识写进 Wiki 或参考文档，不把一次性操作、冗长质检报告和当前文章细节固化为永久流程。

10. 四层校验与返工

按 references/readability-flow-contract.md 完成四层校验：

1. L1 硬边界：事实、来源、隐私、Hugo 结构和既有内容保全。
2. L2 结构与节奏：开头承诺、问题链、长短句段、疑问转向、标题、转场和图文位置。
3. L3 内容质量：观点支撑、知识融入、原型专项、反方处境、机制深度、证据边界、行动与代价。
4. L4 活人感与心流：检查温度、独特性、作者姿态，以及注意力中断、假装亲历、导师训话、品牌营销和结尾没有闭合的位置。

质检报告只记录失败项、证据位置和修复动作，不要用大量“已通过”制造完成感。每轮优先修复最影响阅读的 1 至 3 个问题，然后从头通读。四层自检后必须安排独立子代理终审；未通过或审核未完成时只可保留为 Dev 草稿，不得报告通过或转为 Public。

验证与发布

1. 对本次路径运行 git diff --check -- <intended-paths>，并执行仓库可用的 Markdown 或 MkDocs/Hugo 构建验证。
2. 检查最终文章、图片和远程 URL；审阅 git diff -- <intended-paths>。 提交前按独立审核约定派发子代理、等待结论并记录受审版本；通过仍默认 Dev。检查部署的 Public/Dev 隔离，不把推送成功当成公开授权。
3. 只暂存本次文件，运行 git diff --cached --check 并审阅暂存差异后提交。
4. 再次获取 origin/main，确认 origin/main..HEAD 只有本次授权提交与路径。
5. 使用普通 merge 合入最新 origin/main。逐文件保留双方有效内容，不对整棵目录使用笼统的 ours 或 theirs。
6. 冲突后重新执行内容保全、四层校验、图片审计、git diff --check 和构建验证；内容发生变化时由独立子代理复审最终版本。
7. 发布前再次获取 origin/main；若有推进，重复合并与复验。
8. 使用 git push origin HEAD:main 发布。
9. 比较 git rev-parse HEAD 与 git ls-remote --heads origin refs/heads/main，并确认最终提交是远端 main 的祖先。对象 ID 一致才算完成。

最终交付

最终说明：

• 文章的一句话主线、目标读者和采用的文章原型；
• 使用的一手来源、重要推导与仍未验证的边界；
• 为改善可读性进行的主要重组，以及四层校验修复的心流断点；
• 保留了哪些真实第一人称、判断、情绪或不确定性，以及如何避免导师式和 AI 汇总式语气；
• 新增图片各自解决的阅读问题；没有新增时说明原因；
• 既有文章的原始与最终图片数量、删除项及重组范围；
• 本地验证、构建与图片 URL 验证结果；
• 工作分支、最终提交、远端 main 哈希、冲突与推送验证结果。
• 独立子代理的可读性结论、受审版本及未解决问题；明确发布状态为 Dev（默认）或已获授权并验证的 Public。

调用模板

使用 $work-with-ai-doc-workflow 完成下面的文档任务。

主题：[要研究和解释的问题]
目标读者：[读者已知与未知]
读完后希望读者能够：[复述、判断或执行的结果]
必须使用的材料：[论文、官方文档、源码、实验或现有文章]
特别关注：[机制、比较、实践、限制、配图或发布要求]

在事实与仓库规则的硬边界内，把可读性、思路流畅性和活人感放在形式覆盖之前。先选择文章原型，建立一句话主线、读者问题链和真实作者声音清单，再调研、起草、按认知障碍配图，最后执行四层自检和独立子代理的文章可读性审核。解决集成冲突后复审最终版本，默认以 Dev 内容发布到远端 main；通过不自动转为 Public。

完成门槛

• 读者在导言中能知道文章要解决什么问题，以及读完能获得什么。
• 各节由自然问题推动，没有空壳标题、模板章节或突然跳转。
• 文章像一个有实践、有判断、愿意承认边界的同行在讲解，而不是导师授课、品牌宣传或 AI 汇总。
• 素材中的真实第一人称、具体细节、好恶、情绪和不确定性没有被无故磨平，也没有伪造亲历。
• 技术解释先有直觉和具体对象，再进入术语、公式与实现。
• 每个重要主张有来源或明确标为推导、建议、未验证结论。
• 图、表、公式、伪代码和 admonition 都解决明确的阅读问题。
• 结尾回扣开头，说明结论、行动、代价和证据边界。
• L1 至 L4 校验通过，全文不存在阻断性的注意力断点或需要反复回读的逻辑跳跃。
• 既有有效内容与图片已保全，所有删除均有允许理由。
• 只暂存本次文件；用户未禁用发布时，本地 HEAD 与远端 main 对象 ID 一致。
• 最终版本经过独立子代理的 $article-readability-check 审核；缺失或未通过时如实标注 Dev 草稿与未完成项。
• 默认 Dev 状态已写入元数据，未因审核通过或推送 main 自动公开。