用途
Flue 文档编辑器技能用于把粗糙、臃肿或 AI 生成的 Flue 文档，转化为清晰且经过人工编辑塑造和批准的文档。它适用于重组、重写、审阅或批准文档页面与导航的场景。
该技能明确划分职责：人类编辑拥有产品故事，包括信息架构、页面目的、范围、重点、术语和最终判断；智能体负责实现，包括定位相关源材料、对照代码库验证事实性声明、把已批准的章节要点转化为精炼文字、更新明确限定范围的导航和链接，以及忠实根据编辑反馈迭代。
编辑原则
- 让文档显得有意图。页面应有明确职责和刻意设计的形态，而不是详尽重复所有相关事实。
- 优先采用单一权威叙事。在普通示例中教授推荐路径；仅在用户需要区分时，才在少数页面解释受支持的替代方案。
- 保持范围克制。不要让每个页面都承载项目布局注意事项、部署限定条件或属于别处的概念背景，而应链接到拥有该内容的页面。
- 陈述行为前先验证。阅读相关源码、测试、示例、配置和既有术语；不要因为过时文字已存在于文档中就保留它。
- 让文档暴露产品问题。如果某页面因实现不必要地复杂而难以解释，应指出简化机会；当用户要求时，先改进实现再定稿文档。
- 尊重正在进行的编辑工作。保留用户撰写的草稿和附近未被请求的改动；除非用户将其纳入范围，不要机械地清扫相邻文档。
- 按页面类型组织。指南通常把产品界面组织为清晰的主题和决策，而不是叙述从开始到结束的旅程；只有教程或真正顺序性任务才使用顺序递进。
- 引入而不罗列。页面可以简要介绍属于读者心智模型的相邻能力，即使细节在别处；不要把这种介绍变成产品支持内容的详尽清单。
- 示例中一次只教一个概念。首个或主要示例应聚焦该章节的核心接口；仅在解释身份、授权、持久化或高级能力时才加入它们。
- 以人类判断写作。直接、简洁、自信、具体；删除填充内容、过度防御性细节、重复的注意事项和 AI 风格的过度解释。
务实使用 Diátaxis
Flue 使用 Diátaxis 模型决定页面的主要职责，而不是把它当作僵化问卷或编辑障碍。
- 教程：用户需求是通过一次成功的初次体验来学习；写作姿态是引导式、顺序式、鼓励式，推迟详尽选项。
- 操作指南：用户需求是理解或应用某项产品能力；把相关任务、配置和决策组织为可导航的主题，避免暗示线性教程，除非任务确实需要。
- 参考：用户需求是准确查阅机制；精确、结构化、对其声明范围完整，避免说服性叙述。
- 解释：用户需求是理解概念和设计选择；编辑性和概念性，建立有用的心智模型，而不成为 API 清单。
一个页面可以包含来自其他模式的支撑材料，但应有一个主导目的。如果页面属于另一章节或 URL，应在范围内建议或执行该移动。
协作工作流
- 确定当前页面和范围
阅读正在编辑的页面、其导航位置、拥有重叠主题的邻近页面，以及验证技术声明所需的实现源。编辑生态系统渠道指南时，还要阅读 references/ecosystem-channel-guides.md 并将其共享模式适配到对应提供方。
确定：页面应执行什么职责；其可能的 Diátaxis 类型；其受众及支持的决策或任务；哪些内容属于本页；哪些内容应删除、移动或替换为链接；当前复杂性是否暴露了实现清理机会。
当信息已从用户提示、草稿或现有讨论中明确时，不要强迫用户填写接收问卷。只询问阻碍正确重写的决策。
- 起草前先商定信息架构
对于大幅页面重写，在撰写完整文字前，与编辑一起确定标题及每个章节的目的。
首选交流方式：审阅当前页面并找出为何感觉不对或臃肿；提出或完善精简的标题结构；记录编辑对每个标题的指导，即应传达什么、省略什么、应有多少细节；把已批准的标题结构和章节指导作为重写规范。
有用的提纲格式为：章节、目的、包含、排除或链接到别处。
如果用户已提供提纲和章节级指导，不要再要求他们批准；简要确认歧义后继续。
- 调查事实和相关实现
起草事实材料前：检查相关实现和测试；检查相邻已批准文档中的既有约定和术语；如果 URL 或分类变化，定位导航条目和入站链接；识别应表达权威用户路径、同时一次隔离一个新概念的示例；检查现有文档是否描述了意外或过时行为；区分值得简要介绍的重要相关能力与属于专门指南或参考页的细节。
文档工作可能有意导致代码改进。当编辑要求先简化实现时，先实现并验证产品行为，再针对简化后的契约编写文档。
- 撰写已批准的页面
当结构已批准或明确提供时，让计划落地：在商定标题下写简洁、精炼的内容；每段聚焦该章节目的；章节组织和标题风格匹配页面模式，指南应主题化且便于查阅，只有教程或必需流程才顺序化；仅当代码或树示例能立即澄清接口或约定时使用，避免让基础示例承载无关关注点；使用权威文档路径和术语，除非页面专门解释替代方案；当读者需要知道相邻能力属于此界面时简要介绍，然后链接到更深入的指南或参考页，而不是重述其机制；适用时保持生成输出、运行时上下文、源码布局和产品概念彼此区分；不要暗示产品未实现的约定或特殊行为。
对于包含 TODO 注释的现有经人工编辑提纲，用最终内容替换注释，同时保留预期组织和范围。
- 与编辑迭代
把后续编辑和评论视为编辑方向，而不仅是补丁请求。如果编辑缩小范围，删除材料而不是为其辩护；如果他们改变框架，更新附近段落使页面读起来连贯。
当编辑要求交接而非编辑时，提供紧凑的编辑简报，包含：已实现或已验证的行为；应使用的权威术语和示例；需要简短说明的替代行为；不得暗示的事实；需要更新的页面或链接。
- 仅验证限定范围的结果
编辑后：移动或重命名页面时搜索过时的入站链接；运行仓库提供的文档类型检查/构建命令；运行与变更文件相关的格式或空白检查；避免仅因其他页面包含旧措辞就清扫无关页面，除非编辑要求该迁移。
应避免的模式
不要：在商定重大结构变化前先重写文字；把每个页面变成详尽规范；默认把指南变成教程，围绕隐含的构建顺序组织，而读者应能独立导航其主题；仅因另一页面深入记录了某项重要能力就省略它，或把简要介绍扩展为分散注意力的功能清单；让入门示例承载多个可分别介绍的概念；在所有指南中重复可选布局或边缘情况解释；仅因示例使用就把普通同目录文件呈现为框架约定；当简化产品能产生更清晰契约时保留实现细节；除非用户请求或提供，或验证明确链接的声明有必要，否则查阅外部内容来支持声明；在未先理解哪些文字是有意为之的情况下覆盖编辑正在进行的草稿。
预期输出模式
根据请求选择模式：编辑诊断，即对页面目的、错位材料和推荐形态的简洁评估；提纲/简报，即供编辑批准的标题及章节级范围；实现计划，即文字准确前所需的代码/文档/导航工作；草稿/编辑，即对已批准文档范围的直接修改；交接上下文，即可供另一位写作者在实现决策确定后复制的简报。
目标不是生成更多文档，而是产出结构、声明和语气都反映清晰人类编辑意图的文档。