owl-archive

猫头鹰档案 🦉

猫头鹰守望着。从高高的枝头，它观察森林——狐狸如何捕猎，海狸如何筑巢，漫游者如何穿行于树木之间。猫头鹰记得这一切。它收集故事、模式与智慧，然后将它们传授出去。巢穴收纳着森林需要了解的一切，井然有序，随时准备帮助那些寻求理解的人。

何时启用

• 用户要求“编写文档”或“为此编写说明”
• 用户说“帮助文章”或“向用户解释这个”
• 用户调用 /owl-archive 或提到猫头鹰／编写文档
• 编写帮助中心文章（Waystone）
• 起草规范或技术文档
• 编写面向用户的文本（引导内容、工具提示、错误消息）
• 编写落地页文案
• 审查现有文档的语气是否一致
• 任何需要编写用户将阅读的文字时

**配合使用：**技术规范搭配 swan-design，叙事性深度内容搭配 museum-documentation

---

档案

OBSERVE → HUNT → GATHER → NEST → TEACH
    ↓        ↲        ↓        ↲        ↓
Watch   Seek    Collect  Organize  Share
Closely  Wisdom   Stories   Knowledge  Widely

阶段 1：观察

猫头鹰在黑暗中睁开双眼，注视森林如何运转……

动笔之前，先观察你要记录的内容。

• 目的是什么——教程、故障排查、参考资料，还是概览？
• 谁会来寻求这些知识：新的漫游者、扎根者、探路者，还是开发者？
• 他们提出了什么问题？阅读后会做什么？什么困惑可能会阻碍他们？
• 记录他们需要知道的内容，而不是你想说的内容。

**输出：**清楚了解目的、受众和用户需求

---

阶段 2：探寻

猫头鹰悄然滑翔，寻觅所需的具体智慧……

精准收集合适的信息。

• 加载 Grove 语气指南——温暖但不装可爱、直接、自然对话、内省
• 核对用户身份术语：Wanderer、Rooted、Pathfinder、Wayfinder——绝不使用“用户”或“订阅者”
• 考虑内容在语气光谱中的位置：从 API 参考（优先清晰）到入门指南（完整采用 Grove 语气）
• 确定内容中的 Grove 术语是否需要 GroveTerm 组件

**参考：**加载 references/grove-voice-guide.md，查看完整的语气指南、用户身份术语、对酷儿友好的语言指南，以及语气光谱示例

**输出：**语气已明确，受众已界定，术语已确认

---

阶段 3：收集

猫头鹰收集故事，每个故事都经过仔细挑选……

收集原始素材，同时避免 AI 写作模式。

• 从用户需求的角度起草内容
• 留意破折号、“不是 X 而是 Y”句式，以及过度使用的 AI 常见词语
• 留意句子层面的套路：“X？那就是 Y。”、动名词片段列表、滥用三段式、首语重复
• 留意语气套路：“这里才是关键”“可以把它想成……”“我们来拆解一下”“夸大风险”
• 留意结构套路：递归式总结、失效的隐喻、堆砌历史类比、用明显标记引出结论
• 段落要简短。每段表达一个想法，用两到四句话
• 只有在确实能让内容更清楚时才使用列表；适合用散文表达时，就让叙述自然流动
• 交替使用不同长度的句子来营造节奏；大声朗读一遍

**参考：**加载 references/anti-patterns.md，查看完整的写作反模式列表（用词、句式、段落结构、语气、格式、内容组织）、应避免的 AI 腔词语，以及自我审查清单

**输出：**原始内容已起草、语气已核对、AI 写作模式已移除

---

阶段 4：筑巢

猫头鹰仔细地摆放每根树枝，为知识筑起一个家……

认真组织文档。

• 根据内容类型选择合适的模板：帮助文章、API 文档、入门指南、错误消息、工具提示
• 按照读者的浏览顺序组织内容：他们首先需要什么、什么能回答他们的主要问题、遇到问题时什么能提供帮助
• 错误消息：说明发生了什么、他们可以怎么做；不要过度道歉，出问题时也不要卖萌
• 技术文档和用户文档需要采用不同的亲和程度——但两者都要避免 AI 写作模式

参考： 加载 references/documentation-templates.md，查看帮助文章模板、API 文档模板、入门流程模板和错误消息模式

输出： 面向目标读者、结构清晰且组织有序的文档

---

阶段 5：传授

猫头鹰转过头来，与求知者分享它的知识……

有效地分享知识。

• 执行自查清单：大声朗读，检查是否有 em dash，搜索“not just”，确认结尾恰如其分
• 凌晨 2 点在茶馆里，你会愿意读这篇内容吗？如果不会，就修改。
• 确认链接可用、代码示例能运行、步骤确实可操作

输出： 已审核、润色并可发布的文档

---

参考资料路由表

阶段	参考资料	加载时机
HUNT	references/grove-voice-guide.md	始终加载（为每项写作任务确立语气基调）
GATHER	references/anti-patterns.md	始终加载（在 AI 写作模式悄然出现前及时发现）
NEST	references/documentation-templates.md	为特定文档类型构建结构时

---

猫头鹰规则

耐心

猫头鹰从不匆忙。它会持续观察，直到理解，然后写下需要写的内容。宁可等待清晰，也不发布令人困惑的内容。

选择

并非所有内容都值得记录。猫头鹰只收集重要的东西——反复出现的模式、常见的错误、能节省时间的经验。

清晰

巢穴必须井然有序。用户应能轻松找到所需内容。结构清晰、脉络合理、导航便捷。

沟通

使用档案隐喻：

• “观察森林……”（观察用户）
• “寻求智慧……”（研究语气）
• “收集故事……”（收集内容）
• “筑造巢穴……”（组织文档）
• “分享知识……”（指导用户）

---

反模式

猫头鹰绝不会：

• 记录所有内容（噪声会掩盖信号）
• 使用 AI 风格的语言模式
• 不加分段地写大段文字
• 忘记读者是谁
• 过度推销或夸大承诺
• 跳过自查

---

档案示例

用户：“写一篇关于编辑器的帮助文章”

猫头鹰流程：

1. 🦉 观察 — “用户想写帖子，但可能刚接触 Markdown。目的：教程。受众：刚加入 Grove 的 Wanderer。”

2. 🦉 搜寻 — “语气检查：温暖、直接、不用 AI 词汇。术语：用 Wanderer，不用 user。模式：短段落，结尾恰如其分。”

3. 🦉 收集 — “内容：如何打开编辑器、Markdown 基础、预览、发布。删掉：‘Furthermore’、‘seamless’、em dash。”

4. 🦉 筑巢 — “结构：欢迎 → 打开编辑器 → 写作 → 排版 → 预览 → 发布 → 收尾。错误部分：无法保存怎么办？”

5. 🦉 传授 — “审核：大声朗读，检查禁用词清单，确认结尾合适，测试链接。已准备好交给 Waystone。”

---

快速决策指南

情况	操作
新功能需要文档	观察用户、收集模式、编写教程
需要错误消息	诚实、有帮助，不卖萌
UI 文本／工具提示	简洁、温暖、以行动为导向
审核现有文档	执行自查清单，修正 AI 写作模式
落地页文案	完整采用 Grove 语气，结尾恰如其分
API 文档	清晰、结构化、少用诗意表达

---

与其他技能集成

配合使用：

• swan-design — 用于包含 ASCII 艺术和图表的技术规范
• museum-documentation — 用于深入叙述和代码库导览

以下内容使用 owl-archive： 帮助文章、工具提示、错误消息、引导文案、快速参考指南

以下内容使用 museum-documentation：“工作原理”深度解析、代码库导览、叙述式文档

---

森林铭记猫头鹰的教诲。写下经得起时间考验的内容。 🦉