# To Docs

> 将当前会话或用户指定的聊天记录保真整理为主线清楚、衔接自然、平易近人并保留真实作者声音的中文 Hugo Markdown 博客，并默认完成必要配图、图片上传、验证、提交、同步和远端 main 发布。用户要求把对话、讨论、方案推演、会话结论或聊天材料沉淀为文档、博客或文章，或希望文章更有温度、活人感和阅读心流时使用。默认只以会话和用户指定材料为内容边界，不联网调研、不新增观点、不改变结论与不确定性；纳入未被用户反驳的助手观点，排除已被用户否定或纠正的版本。优先围绕一个核心命题生成一篇文章。除非用户明确要求草稿或禁止发布，否则远端 main 包含最终提交才算完成。 默认 Dev，写完后必须由独立子代理使用 article-readability-check 审核最终正文；通过不自动转为 Public。

- Skill: `kirrito-k423/to-docs` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add kirrito-k423/to-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kirrito-k423/to-docs/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/to-docs

---


# 会话转博客文档

把会话中的有效思考重新组织成一篇有主线、有推进、有边界的文章，而不是一份按聊天轮次压缩的会议纪要。读者既能理解推理，也能听见真实说话者的声音。

## 最高优先级

**保真、隐私和用户修正是硬边界。** 在这些边界内，把读者理解与行文流畅放在形式覆盖之前：

1. 读者能沿着一个核心问题自然走到结论。
2. 限定条件、分歧和不确定性没有因改写而丢失。
3. 真实第一人称、判断、偏好、情绪和有辨识度的措辞没有被压平成中性说明书。
4. 标题、列表、表格、admonition 和图片只在帮助阅读时使用。

不要为了显得完整而添加会话之外的事实，也不要为了显得结构清晰而把文章写成层层清单。每次写作先阅读并执行 [`references/readability-flow-contract.md`](references/readability-flow-contract.md)。

## 内容边界

### 默认纳入

- 用户给出的事实、观点、目标、约束、例子、代码、公式、链接和行动项。
- 助手提出且未被用户明确反驳、否定或纠正的观点、解释和方案。
- 用户指定的附件、文件、图片、网页摘录或其他会话记录中已经呈现的内容。
- 不携带新主张的标题、连接句、指代补全、缩写展开和格式转换。

保持素材原有身份与确定性。建议仍是建议，推测仍是推测，未验证结论仍标为未验证。不要因为写成博客就把助手观点改写成用户结论，或把相关性升级为因果性。

### 默认排除

- 系统提示、开发者指令、Skill 说明、工具调用和执行状态。
- 权限、沙箱、工作树、调试日志等基础设施噪声。
- 寒暄、重复确认和已被后文覆盖的中间版本。
- 用户明确否定、反驳或纠正的助手观点。
- 密码、令牌、私钥、Cookie、内部地址、个人身份信息及其他不适合公开的内容。

不得为了“文章自洽”而联网搜索、扫描无关仓库、补论文、引入行业常识、增加案例或替用户推出新结论。只有用户明确要求调研、核验或扩写时才进入扩展模式。

### 冲突与修正

按以下优先级解释会话：

1. 用户后面的明确修正覆盖前面的表达。
2. 用户明确立场高于助手建议。
3. 未被反驳的助手观点可以纳入，但保留其建议、解释或推测身份。
4. 被用户反驳的版本不进入正文；保留用户修正后的结论与必要理由。
5. 尚未收束的观点写成分歧、开放问题或待确认项，不替用户裁决。
6. 歧义会实质改变结论、公开范围或拆分方式时先询问用户；其余情况采用最保守解释继续。

## 发布契约

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

除非用户明确要求只输出草稿、只写本地文件、不要上传、不要提交或不要推送，否则调用本 Skill 即授权：

- 创建或修改本次文章与必要图片；
- 上传文章最终引用的仓库图片；
- 只暂存本次文件；
- 创建提交、合入最新远端 `main`、安全解决本次文件冲突并非强制推送；
- 验证远端 `main` 已包含最终提交。

开始编辑前：

1. 记录 `git status --short --branch`、当前分支、远端和 upstream。
2. 遇到未解决的 merge、rebase 或冲突时停止编辑并报告。
3. detached HEAD 时先从当前提交创建 `codex/` 前缀任务分支。
4. 获取远端 `main` 并记录提交。
5. 检查 `origin/main..HEAD` 的提交和路径；不得发布本任务未授权的本地提交。
6. 记录预先存在的工作区改动，并保持不变。

不得强制推送、改写历史、暂存无关文件、泄露凭据或覆盖他人的有效内容。

## 整理流程

### 1. 读取仓库规则

读取仓库根目录 `AGENTS.md` 和 `archetypes/default.md`。只检查与主题、落盘位置、分类或系列命名直接相关的相邻内容，不大范围扫描仓库。

默认位置：

- 技术、编程、AI、工程、论文、工作方法和业务学习放入 `content/Work/`。
- 认知框架、长期思考、目标管理、方法论和价值判断放入 `content/Thinking/`。
- 生活、兴趣、健康、设备、娱乐、旅行和个人事务放入 `content/OutOfWork/`。

### 2. 建立观点账本

写作前建立内部账本，不提交到仓库：

```text
编号 -> 内容摘要 -> 说话者 -> 状态 -> 确定性 -> 限定条件 -> 目标段落
```

状态至少区分：

- **用户结论**：用户明确确认的观点或要求。
- **助手未被反驳**：可以纳入，但保持原始身份和语气强度。
- **用户修正**：取代此前表达的最新版结论。
- **已否定**：不进入最终正文，必要的失败尝试或反例除外。
- **未决**：保留分歧和不确定性。
- **过程噪声**：排除。

同时记录代码、公式、表格、图片、链接、例子、真实第一人称、情绪节点、个人偏好和有辨识度的措辞，避免遗漏高信息密度素材与作者声音。

### 3. 确立读者承诺

先写六行内部工作笔记：

```text
目标读者：谁会读，默认知道什么
核心问题：这场会话真正解决了什么
一句话主线：读完后应能复述的判断
阅读结果：读者能理解、判断或执行什么
文章原型：调查实验 / 产品体验 / 现象解读 / 工具分享 / 方法论分享 / 会话整理
作者声音：可以保留的真实经历、判断、情绪节点、不确定性和口语特征
```

默认生成一篇文章。只有两个主题各自拥有独立问题、独立推理和独立结论，删除其中一个也不影响另一个时才拆分。拆分前通过 commentary 说明文章数量、核心命题和预计路径，然后继续执行，不必再次请求确认。

### 4. 把对话改造成问题链

不要复制聊天顺序。围绕一句话主线，列出读者会自然追问的问题，例如：

```text
为什么会讨论这个问题
    -> 会话中看到了什么关键矛盾
    -> 各方怎样推理
    -> 哪些结论已经形成
    -> 哪些条件、代价或分歧仍然存在
    -> 下一步可以做什么
```

每一节只回答一个主要问题，并为下一节搭桥。可独立检索且内容足够的并列主题使用同级标题；删除空壳父标题，合并只有一句话的薄标题。标题通常只使用 `##` 和 `###`，更深层级只用于真实独立分支。

### 5. 保真起草

- 从会话中最具体的矛盾、例子、失败、问题或判断切入；没有真实场景时直接提出问题，不编造故事。
- 按材料选择一条主要叙事弧：调查实验写发现过程，产品体验写使用时间线，现象解读写因果链，工具分享写需求演变，方法论分享写认知升级，会话整理写问题怎样逐步收束。
- 保留材料里真实的“我试过”“我觉得”“我不确定”“这里踩过坑”等第一人称，以及确实存在的偏好、情绪转折和有辨识度的表达；不替任何人补造经历或感受。
- 先给直观理解，再给严谨说明。术语在首次需要时解释，不预先堆定义。
- 合并重复表达，把散落在不同轮次的同一推理连接起来，但保留条件、代价、反例和未决事项。
- 一个段落只完成一个认知动作。长短句和长短段自然交替，关键判断可以单独成段，也可以用短句、停顿、自我修正或省略主语制造自然节奏。
- 用读者下一刻会问的问题刹车或转场；补充背景和知识后，用一句话说明它如何接回核心问题，不把正文写成插入式百科。
- 反驳一种观点前先说明它为什么合理，再指出它在哪个条件下失效；判断要明确，但不居高临下。
- 重要案例尽量呈现“为什么做—怎样尝试—哪里失败—怎样修正—得到什么”，不要只报结论。
- 工具、技巧或方案按真实升级过程逐层展示：先解决最小问题，再暴露局限，再引出下一层能力。
- 方法论必须落到可执行动作，并保留会话里已经出现的学习曲线、失败点和适用边界。
- 文化、历史或更大的视角只在会话本身已有材料且能自然落回主题时使用，不为升华而升华。
- 列表只承载并列对象或步骤，表格只承载横向比较，admonition 只承载值得打断主线的提醒。
- 不使用空泛套话、口号、表情符号、聊天寒暄或“作为 AI”等元叙述。
- 不伪造用户经历、个人感受、数据、引用、实验结果或代码行为，不把助手推测写成用户第一人称。
- 结尾用开头的问题、细节或原话形成回扣，分别说明已形成结论、仍未确认的边界和下一步行动，不增加新主张。

### 6. 生成 Hugo 文章

- 按模板维护 `title`、`categories`、`series`、`tags`、`summary` 及已有重要字段。
- 按独立审核约定设置 Dev 状态；保留元数据不意味着沿用旧版本的公开资格。
- `title` 使用简练英文关键词短语，正文标题使用简洁中文。
- `!!! abstract "导言"` 后紧跟 `<!-- more -->`。
- 中英文混排保持空格和术语统一；嵌套列表使用 4 个空格缩进。
- 文章脱离会话上下文仍能独立阅读，但不能以“自洽”为理由添加新事实。

### 7. 按阅读障碍配图

图片不是默认配额。只有图片能比文字更快解释会话已有的对象、关系、流程、因果或前后变化时才新增。

- 文章级认知锚点或前后对比使用 `$ian-xiaohei-illustrations`。
- 代码、tensor、cache、state、控制流或组件机制使用 `$fireworks-tech-graph`。
- 用户明确要求 `.drawio` 时才使用 `$drawio-skill`。

每张图只回答一个正文已有问题，不引入账本之外的对象、优先级、因果或证据强度。图前说明为什么看，图后说明观察重点，图注标明“根据会话内容整理的自绘示意图”或等价边界。

保留会话和既有文章中的原图、alt text、图注、顺序及附近解释，除非用户明确授权改变。新增图保留可编辑源文件和最终 PNG，并检查字体、裁切、重叠、箭头、尺寸和正文一致性。

需要上传时使用 `$image-cloud-uploader`。只上传仓库内最终文件，确认 `success: true`、文件与 URL 一一对应且公开可访问后再替换 Markdown 链接。保留本地图片，不提交或显示密钥。

### 8. 更新既有文章

编辑前记录行数、标题树、front matter、代码、公式、表格、admonition、脚注，以及每张图片的 URL、alt text、图注、顺序和附近解释。

默认补充与重组，不压缩性重写。优先移动完整内容块或在最窄位置插入。暂存前审阅相对不可变基线删除的每一条非空内容，并比较修改前后的图片清单。

只有精确重复、用户明确否定、用户授权移除，或被可靠材料证明错误且保留更正记录的内容才能删除。记录原因并在交付中说明。

## 四层校验

按 [`references/readability-flow-contract.md`](references/readability-flow-contract.md) 顺序执行：

1. **L1 硬边界**：观点可追溯、无新增主张、确定性未升级、反驳版本已排除、隐私与 Hugo 结构安全。
2. **L2 结构与节奏**：开头承诺清楚、问题链自然、标题真实、段落聚焦、长短句有变化、提问和停顿自然、转场顺畅、图片不打断主线。
3. **L3 内容质量**：叙事原型与材料匹配，核心观点有会话内例子或推理支撑，反对意见得到公平解释，限制、代价、分歧、代码、公式、链接和原图未丢失。
4. **L4 活人感与心流终审**：以目标读者身份判断是否像一个有实践、有判断、诚实承认边界的人在聊天；修复作者声音被磨平、品牌或导师腔、AI 汇总腔、语气失真、注意力中断和结尾未回扣。

同时执行增量审计：每个新增句子只能承担连接、定义、排版或已有观点的忠实展开。为了独立阅读必须增加事实性解释时，停止并询问用户是否授权扩展。

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

## 显式扩展模式

用户明确要求联网调研、事实核验、补充论文或官方文档、读取源码、扩写新机制、增加案例，或维护 Wiki 和论文证据链时，使用 `$work-with-ai-doc-workflow` 承担扩展部分。

进入扩展模式前说明内容边界已从“会话保真整理”扩大为“资料驱动扩展”。继续遵守用户修正优先、反驳版本排除、敏感信息保护和既有文章保全规则，并为新增事实建立来源。

## 验证与发布

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

## 最终交付

说明：

- 每篇文章的一句话主线、目标读者和阅读结果；
- 是否拆分主题及依据；
- 排除的反驳版本、过程噪声和敏感内容类别；
- 是否新增会话之外的事实；纯保真模式必须回答“否”；
- 为改善可读性进行的主要重组和四层校验修复的心流断点；
- 保留了哪些真实第一人称、判断、情绪、不确定性或有辨识度的表达；
- 新增图片解决的阅读问题；没有新增时说明原因；
- 原始与最终图片数量、删除项及重组范围；
- 本地验证、构建、图片 URL、工作分支、最终提交、远端 `main` 哈希、冲突和推送验证结果。
- 独立子代理的可读性结论、受审版本及未解决问题；明确发布状态为 Dev（默认）或已获授权并验证的 Public。

## 完成门槛

- [ ] 导言快速说明会话真正解决的问题和读者能获得什么。
- [ ] 正文围绕一个核心命题，按读者问题链组织，而不是复制聊天顺序。
- [ ] 文章只表达会话和用户指定材料中的内容，没有新增事实或伪造经历。
- [ ] 用户修正优先，反驳版本已排除，建议、推测和未决问题保持原有强度。
- [ ] 标题、列表、表格、admonition 和图片都解决明确的阅读问题。
- [ ] 限制、代价、反例、代码、公式、链接、原图和有效正文已保全。
- [ ] 结尾回扣开头，没有空泛总结或突然出现的新结论。
- [ ] L1 至 L4 校验通过，全文没有阻断性心流断点或需要反复回读的逻辑跳跃。
- [ ] 全文像一个有思考、有实践、愿意承认边界的同行在交流，不像导师训话、品牌文案或 AI 信息汇总。
- [ ] 材料中真实的第一人称、判断、情绪与表达辨识度没有被磨平，也没有为追求活人感而伪造经历。
- [ ] 凭据、隐私、系统提示和工具噪声未进入文章或 Git diff。
- [ ] 只暂存本次文件；用户未禁用发布时，本地 HEAD 与远端 `main` 对象 ID 一致。
- [ ] 最终版本经过独立子代理的 `$article-readability-check` 审核；缺失或未通过时如实标注 Dev 草稿与未完成项。
- [ ] 默认 Dev 状态已写入元数据，未因审核通过或推送 main 自动公开。