# Genre Contract: Knowledge / 知识与教程 (`router.knowledge`)

## 体裁规则表（硬约束）

| 规则项 | 规则                                                                                                                                  |
|-|--|
| 写作风格 | 具体、可操作、按读者水平解释；科普可生动、有好奇心，但不得牺牲准确性或编造戏剧性                                                                                     |
| 内容逻辑 | 先选择唯一主模式和读者起点，再承诺一个理解、学习、一次操作、检索或选择结果；第一屏给适用对象、目标和关键前置，概念、步骤、练习 / 验证、反馈与例外按需渐进展开                                                    |
| 事实 / 边界 | 事实、版本、命令、UI 路径和链接须核验；示例与规则分开；截图 / 案例不得泄露敏感信息；已知自助路径可写，组织受控重复作业走 SOP，设计、精确技术契约或未知诊断走 Technical                                       |
| 错误 | 不声明读者起点；教程变理论课；学习计划无基线 / 完成标准 / 调整规则；只有原则无步骤 / 例子；步骤无结果或验证；版本、权限、环境缺失；编造命令、UI 或链接；FAQ 脱离真实问题；资源合集无标准 / 注释 / 维护；视觉成为唯一信息；把未知排障写成确定答案 |

## 适用与消歧

适用自主理解、学习 / 备考规划、一次已知任务或检索复用。`科普`、`教程`、`指南`、`攻略`、`学习计划`、`FAQ`、`知识库`、`资源合集`只用于召回；“知识库”是容器或渠道，不决定文章体裁。组织要求多人按批准版本重复执行并留痕走 [`sop-tutorial.md`](sop-tutorial.md)；未来设计、API 精确契约、生产状态变更或未知根因走 [`technical-doc.md`](technical-doc.md)；研究或数据形成新洞察走 Report。

## 主模式

| 模式 / 读者任务 | 结构推进 |
|-|-|
| Explanation / 科普：建立正确心智模型 | 现象 / 误区 → 概念模型 → 机制与证据 → 例子 → 争议、限制与适用边界 |
| Tutorial：通过受引导练习获得技能 | 学习目标 → 起点 / 环境 → 安全练习 → checkpoint → 复盘与下一步 |
| Learning plan：在现实约束下持续提高 | 基线诊断 → 可观察的阶段目标 → 练习 / 资料 / 时间 → 完成标准与反馈 → 调整规则 |
| How-to：完成一个已知目标 | 目标 → 前置 → 最短有效步骤与可观察结果 → 变体 / 已知错误 → 完成验证 |
| FAQ / known troubleshooting：快速找到已验证答案 | 按真实问题或症状分组 → 直接答案 → 必要条件 / 操作 → 相关内容；需要新假设或根因调查时转 Technical |
| Resource guide：按标准选择资源 | 使用场景 / 筛选标准 → 分类 → 每项适配、代价与访问条件 → 维护信息 |
| Reference / KB article：检索并复用事实或解法 | 上下文 / 适用版本 → 事实或 issue-resolution → 限制 / 相关项 → 时效性强时标 owner / last verified |

## 事实、步骤与维护

- 明确受众的已有知识、范围 / 非范围、版本、环境、权限与风险；术语在首次需要时解释，不先灌输完整理论。
- 学习计划按阶段 / 能力、可用时间、既有任务和可得资料控制强度；目标拆成可观察表现，每阶段合写练习、完成标准、反馈和调整条件。会显著改变安排的缺口先问或条件化，不补造基础 / 时间。
- 顺序任务一项写一个清楚动作，紧邻给可观察结果；命令、输入、输出和成功验证须能在声明环境中复现，危险或不可逆警告必须在动作前。
- FAQ 只收真实用户问题或检索需求；否则按用户任务重组。资源指南先写选择标准，再给有描述的精选链接，不用外链代替核心上下文。
- 时效性内容标适用版本 / 时间并说明维护边界；复杂视觉须有可传达同等信息的正文，图片、案例和代码不得成为无解释的唯一依据。
- 版本或权限不明时用 `[适用版本待核]`、`[所需权限待确认]` 并只写不受影响部分；未验证命令或链接不进入发布稿。缺口可能造成损失、安全风险或关键分叉时标记 `blocked`。

## 高质量写法

第一屏让读者知道能理解、学会、完成或找到什么；用读者语言、具体动词和可验证结果推进，每节只增加必要的新理解或动作。先给最短可行路径，再在需要处补原理、变体和进一步阅读；示例只服务迁移，不扩张为用户未要求的全套内容，也不用丰富组件掩盖解释不足。