# Work With AI Doc Workflow

> 将研究问题、技术主题或工作流需求转化为来源可追溯、思路连贯、平易近人并保留真实作者声音的中文 Hugo Markdown 文章，并完成必要的 Wiki 维护、公式与源码解释、技术图或论文图、图片上传、验证、提交、冲突处理和远端 main 发布。用户要求调研后写技术文章、解释概念或机制、比较多种方案、结合论文或源码给出证据、以更有温度和活人感的方式写作、沉淀可复用工作流，或完整发布 Hugo 内容时使用。除非用户明确要求草稿或禁止发布，否则远端 main 包含最终验证提交才算完成。 默认 Dev，写完后必须由独立子代理使用 article-readability-check 审核最终正文；通过不自动转为 Public。

- Skill: `kirrito-k423/work-with-ai-doc-workflow` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add kirrito-k423/work-with-ai-doc-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/work-with-ai-doc-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Kirrito-k423 (https://skillmd.com/u/kirrito-k423)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/kirrito-k423/work-with-ai-doc-workflow

---


# AI 技术文档工作流

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

## 最高优先级

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

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

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

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

## 发布契约

**文章默认发布到 Dev。** 写作前必须阅读并执行 [独立审核与 Dev 发布约定](../hugo-tech-blog-writer/references/dev-review-contract.md)。设置 `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`，然后先写五行内部工作笔记：

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

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

### 2. 建立证据账本

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

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

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

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

### 3. 设计问题链

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

常见推进关系是：

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

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

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

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

### 4. 沿认知路径起草

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

### 5. 解释技术方法

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

必须做到：

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

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

### 6. 解释公式与源码

正文包含公式、源码、伪代码、tensor、cache、state 或计算图时，阅读并执行 [`references/formula-code-diagram-contract.md`](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`](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。

## 调用模板

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

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

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

## 完成门槛

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