本文把上游 copy-editing skill 中适合技术写作的检查方法整理为 Fluxon 文档审校流程。它用于技术事实和结构已经确认后的文字审校，不替代仓库文档规约，也不能改变公共接口、运行行为或性能结论。
1. 来源与适用边界
| 项目 | 内容 |
|---|---|
| 上游项目 | coreyhaines31/marketingskills |
| 上游 skill | copy-editing |
| skill 版本 | 2.0.0 |
| 固定提交 | 0ba2a7fafc7b0827a261bd518e87cbda18e6675f |
| 上游定位 | 审校已有的营销与转化文案，保留核心信息和作者语气。 |
| 本文用途 | 提取清晰度、语气、理由、证据和具体性检查，适配 Fluxon 技术文档。 |
| 许可 | MIT，完整声明见文末。 |
使用时按以下优先级处理冲突：
- 当前任务要求、仓库
AGENTS.md和文档写作规约。 - 代码、公共接口、测试和已验证的运行行为。
- 本文的审校流程。
文字更顺不能成为修改技术含义的理由。遇到事实不确定、接口与文档不一致或证据不足时，先核对实现，再决定修改文档还是代码。
2. 上游七轮检查如何用于技术文档
上游 skill 把审校拆成七轮。Fluxon 只直接采用其中四轮，改写两轮，跳过一轮：
| 上游检查 | Fluxon 用法 | 处理方式 |
|---|---|---|
| Clarity | 检查长句、指代、未定义术语、上下文缺口和被限定条件埋住的主结论。 | 直接采用。 |
| Voice and Tone | 统一正式程度、角色名、组件名和中英文术语，保持自然的工程表达。 | 直接采用。 |
| So What | 对架构选择补充原因、影响和代价，回答“为什么这样设计”。 | 改写为工程动机检查，不写营销收益。 |
| Prove It | 用代码路径、类型签名、测试、指标或受限实验支撑行为与性能判断。 | 直接采用。 |
| Specificity | 写清范围、抽象层、前提、失败条件和不包含的路径。 | 直接采用。 |
| Heightened Emotion | 渲染痛点、焦虑、愿景或情绪。 | 跳过。技术文档优先准确和可验证。 |
| Zero Risk | 营销 CTA、保证和风险逆转。 | 只保留用户操作中的前置条件、失败结果和下一步，不引入营销 CTA。 |
上游的英文词数、主动语态和短段落建议都是启发式规则。中文句长、代码标识和复杂所有权关系应按可读性判断，不机械套用固定阈值。
3. 审校流程
3.1 先固定技术事实
审校前先确认：
- 文档类型和目标读者。
- 公共契约、当前实现和专用 fast path 的边界。
- 关键类型、配置键、返回值和失败语义是否与代码一致。
- 行为、所有权和性能判断覆盖的完整路径。
- 是否存在需要同步修改的中英文页面。
如果这些问题还没有答案，先做技术 review。copy editing 不能替代实现核对。
3.2 第一轮：结构与清晰度
先检查读者能否在开头快速回答三个问题：
- 这篇文档解决什么问题。
- 最重要的稳定信息是什么。
- 正文将按什么顺序展开。
随后逐节检查：
- 标题是否直接表达本节判断或任务。
- 每节是否先给当前抽象层的稳定信息，再进入字段、分支和数字。
- 开头列出的轴是否在正文中逐项回应。
- 同一事实是否被角色表、链路表、图例和总结重复解释。
- 局部实现细节是否过早出现在导读或架构概览中。
3.3 第二轮：语气与术语
- 一个概念只保留一个规范名称、拼写和大小写。
- 角色职责用明确主语表达，例如“master 维护
route”“owner 管理本地 SSD”。 - 删除“稳定结论”“当前结论”等与实际内容不匹配的标签，直接写“核心要点”“当前状态”或具体判断。
- 避免模板腔、宣传语和没有对象的“提升”“增强”“优化”。
- 保留必要的英文代码术语，不为了中文化而改写公共类型或字段名。
3.4 第三轮：理由、证据与边界
每个重要判断都检查四件事：
| 检查项 | 要回答的问题 |
|---|---|
| 理由 | 为什么选择这条职责边界、数据方向或生命周期。 |
| 机制 | 哪个对象、字段或调用链实现了该行为。 |
| 范围 | 判断覆盖到哪一步、哪个抽象层和哪些分支。 |
| 排除项 | 哪些成本、路径、恢复能力或部署条件没有包含在内。 |
架构判断应把原因放在判断附近。例如，内存 allocation 归 master 调度时，应立即说明它同时覆盖最终 value 副本和跨 owner 传输临时内存；不能只列职责归属。
性能判断还必须绑定硬件、数据集、并发、输出边界、统计窗口和运行次数。端到端逻辑 payload 带宽不能写成裸 SSD 带宽。
3.5 第四轮：收缩与去重
按以下顺序处理重复内容：
- 保留首次出现的稳定判断。
- 保留能显著降低理解成本的一张表或一张图。
- 后续章节只展开新增机制、条件或失败路径。
- 总结回收公共契约、核心数据流和当前边界，不复述实验表格。
不要为了让每节“看起来完整”而重复角色定义。已经在总览中定义的角色，后续图前只补充该图中特有的含义。
3.6 第五轮：发布前回查
完成一轮修改后，从后向前回查，确认后续编辑没有破坏前面的判断：
- 术语、章节号和交叉引用仍然一致。
- 表格列数、代码围栏、折叠块和 Mermaid 图可以解析。
- 中英文页面表达相同的契约和边界。
- 所有精确标识仍使用正确名称。
- 修改没有引入新的兼容路径、配置入口或未验证事实。
- 文档站构建通过。
4. 协作审校与 one-shot 示例
4.1 从表面问题回溯根因
审校意见应同时给出位置、问题、原因和建议改法。只说“读起来不顺”不足以支持修改。
| 项目 | 示例 |
|---|---|
| 位置 | 开头的实验说明。 |
| 问题 | 在读者理解文章结构前提前展开统计口径。 |
| 原因 | 局部证据抢占导读层级。 |
| 改法 | 开头只保留全文结构，把统计条件留在实验节。 |
对于明确、局部且不会改变技术语义的问题，可以直接修改并回查。会改变契约、结论范围或章节主线的修改，应先说明判断依据和影响。
一轮完整审校还应归纳多个表面问题背后的共同原因。这样才能修正全文，并把经验复用于下一篇文档。下面以 KV SSD 文章的一组实际修改为例：
| 表面问题 | 根因 | 审校决策 |
|---|---|---|
| 用“先记住四个稳定结论”引出内容摘要。 | 标签强度超过内容；摘要尚未构成经过论证的结论。 | 改为“四个核心要点”。 |
| 先写 owner 的物理资源，再写 master，最后又回到 owner 的 SSD 调度。 | 同一主体的职责被拆散，读者需要来回重组角色边界。 | 按主体归并，先集中说明 master，再集中说明 owner。 |
| 只写“内存 allocation 调度归 master”。 | 职责判断缺少就地理由，读者无法判断该边界是否覆盖完整。 | 紧跟说明内存 allocation 同时包含最终 value 副本和临时传输分配，两者都与 route 和 in-flight 状态联动。 |
| 开头提前解释第 9 节的实验分组、命中条件和统计口径。 | 局部证据与导读不在同一抽象层，细节遮住了全文结构。 | 开头只保留问题、核心要点和阅读路径，把实验条件留在第 9 节。 |
| 把“覆盖更大的运行期工作集”直接写成既成结果。 | 设计预期被写成已验证结果，主张强度超过现有证据，也没有直接落到读者关心的运行收益。 | 保留公共 API 不变这一范围，改为“有望提高缓存命中率，并更充分地利用存储带宽”。 |
这些修改共同服务于两个目标：让读者按正确层级建立系统模型，并确保每个判断都不越过其证据边界。
4.2 可复用的 one-shot 示例
下面的提示词适用于技术事实已经核对、需要完成一轮结构与语言审校的文档：
目标文档：<文档路径>
请对目标技术文档完成一轮审校并直接修改。保持公共 API、实现事实、实验数字和已有结论边界不变。
重点检查：
1. 开头只说明问题、核心要点和全文结构，不提前展开局部实现或实验方法。
2. 标题、导语和表头的标签必须匹配内容，不把摘要或能力状态统称为“结论”。
3. 按主体归并职责；介绍多个角色时，集中写完一个角色再写下一个角色。
4. 每个重要架构判断附近都要说明原因或机制，尤其是职责归属、生命周期和数据方向。
5. 主张强度必须匹配证据：已验证结果可以直接陈述；设计目标或预期收益使用“有望”“预计”等限定；证据不足的结果不写成事实。
6. 删除重复的角色说明、错层细节和不增加新信息的总结，同时保留必要的范围、前提和排除项。
7. 保持术语、类型名、接口名、章节号、交叉引用、表格和代码围栏一致。
完成后：
- 用“表面问题 → 根因 → 修改决策”概括主要改动，不逐句复述。
- 如存在对应的中英文页面，同步更新。
- 回查公共契约、技术事实和性能口径，并运行仓库规定的文档站构建。5. 不采用的上游做法
- 不用情绪渲染、FOMO、痛点放大或销售话术增强技术文章。
- 不为每项实现强行补“用户收益”。只在理由影响理解或取舍时说明结果。
- 不添加没有来源的数字、时间承诺、案例或比较级。
- 不把英文“每句不超过 25 个词”等经验机械转换为中文字符限制。
- 不要求所有句子改成主动语态；所有权和数据流清晰度优先。
- 不使用虚构专家 persona 打分代替代码、测试和同层级链路核对。
6. 更新上游快照
本文固定到上游提交 0ba2a7f。更新时：
- 对比上游
skills/copy-editing/SKILL.md和references/的变化。 - 只吸收适合技术文档、且不与 Fluxon 规约冲突的部分。
- 同步更新中英文文档、skill 版本和固定提交。
- 重新执行文档站构建。
不要自动用上游内容覆盖本文；上游目标是营销文案，本文目标是准确、可验证的技术文档。
7. 第三方许可
本文基于 Corey Haines 的 copy-editing skill 整理，并针对 Fluxon 技术文档进行了修改。上游采用 MIT License。
MIT License
MIT License
Copyright (c) 2025 Corey Haines
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.