better-notes git:20260908.8c5e1ecA

Immutable. This exact content is served forever at /api/v1/blob/64940719aa98b3b3.

---
name: better-notes
description: 编写、整理或重写有事实依据的技术与知识笔记。用户要求“写笔记”“整理知识点”“做学习笔记”“写教程/概念说明”，尤其涉及 API、库、框架、论文、算法或可能随版本变化的内容时使用。写作前必须先查阅网络上的官方文档、发布说明、论文、技术博客或文章，核对版本、弃用状态与替代方案；不能只凭模型记忆成文。输出简洁、直接，不用比喻，并把前置条件、输入、处理过程、输出、限制和来源说清楚。不用于仅做文字校对，或逐字整理用户提供的私人会议记录。
---

# Better Notes

编写能追溯来源、版本不过时、结构简洁的知识笔记。

## 核心规则

**先查资料，再写笔记。** 不要先凭记忆生成正文，再搜索资料为既有结论补引用。

- 至少查到一份直接支持核心内容的一手资料，才开始写作。
- 涉及 API、命令、依赖或框架时，必须核对当前官方文档和版本/发布说明。
- 把资料没有支持的内容删除、改为明确推断，或标记为“尚未确认”。
- 没有网络或无法取得必要资料时，停止撰写事实性正文；说明缺少什么，并请求用户提供来源或允许稍后重试。
- 引用来源不等于复制来源。笔记应重新组织信息，只保留理解和使用所需的内容。

开始调研前读取 [references/research-and-verification.md](references/research-and-verification.md)。确定结构与措辞前读取 [references/note-style.md](references/note-style.md)。

## 工作流

### 1. 明确笔记任务

从用户输入中提取：

- 主题与目标读者；
- 想解决的问题；
- 期望深度和输出语言；
- 指定技术栈、版本、时间范围或来源；
- 目标格式与保存位置。

已有信息不要重复询问。只有缺失项会改变资料范围或正文结构时才提问；否则采用最窄、最实用的范围。

### 2. 先建立问题清单

写出本篇笔记必须回答的 3～7 个问题，例如：

1. 它是什么，解决什么问题？
2. 使用它需要哪些前置条件？
3. 输入是什么，经过什么处理，输出是什么？
4. 最小可运行用法是什么？
5. 当前版本有哪些限制、弃用项或迁移要求？

问题清单用于约束搜索范围，不需要默认展示给用户。

### 3. 检索并核对资料

按以下顺序选择来源：

1. 官方文档、规范、API reference、发布说明、迁移指南；
2. 原始论文、作者项目页、官方仓库与源码；
3. 维护者或研究机构的技术文章；
4. 能补充实践细节的高质量博客或文章。

搜索时同时包含主题、版本和 `deprecated`、`migration`、`release notes` 等关键词。对每个会影响使用方式的结论记录来源和适用版本。

对于 API 或命令，逐项确认：

- 当前推荐名称与导入路径；
- 参数、默认值、返回值或输出格式；
- 首次引入、弃用或移除的版本；
- 官方推荐替代项与迁移方法；
- 示例所需的运行时和依赖版本。

如果官方资料与博客冲突，以适用于目标版本的一手资料为准，并在笔记中简短说明差异。搜索摘要只能用于发现页面，不能单独作为事实依据；必须打开并阅读原文。

### 4. 先做事实检查，再组织正文

在草稿前把核心结论分成三类：

- **已证实**：来源直接支持，可写入正文；
- **推断**：由多项事实推导，必须用“因此”“可以推断”等措辞标明；
- **未确认**：资料不足或相互冲突，不写成事实。

代码和命令必须与已核对版本一致。能够在当前环境运行的示例应实际运行；不能运行时明确写“未运行验证”及原因，不能写成“可运行”。

### 5. 用最短结构写清楚

根据主题选择必要章节，不机械套模板。通常按以下顺序：

1. 标题；
2. 本篇实际使用的论文、官方文档、官方仓库或博客链接；
3. 一句话定义；
4. 适用范围或要解决的问题；
5. 前置条件；
6. 输入 → 处理 → 输出；
7. 核心原理或执行步骤；
8. 最小示例与预期输出；
9. 版本、限制和常见错误；
10. 带访问日期的完整来源。

简单概念可以只保留“定义—关键点—示例—来源”。比较类内容优先用表格；流程只在存在明确顺序时使用编号列表。

### 6. 交付前复核

逐项检查：

- 每个时效性事实是否有当前来源；
- 是否仍出现已弃用 API，却没有显式说明其状态和替代方案；
- 输入、输出、前置条件和失败情况是否具体；
- 示例与正文中的名称、参数和版本是否一致；
- 是否把推断、经验或未验证内容写成事实；
- 是否存在比喻、宣传词、重复总结或不影响理解的背景；
- 来源是否包含标题、链接、访问日期，版本敏感时是否包含版本。

任一核心项不满足时先修正，不要宣布完成。

## 输出要求

默认使用 Markdown，并遵守：

- 开头直接定义主题，不写泛泛背景和铺垫。
- 使用短段落、明确标题和具体动词。
- 不使用比喻或拟人化表达；直接说明数据、状态和操作。
- 第一次出现术语时给出定义，后文保持同一名称。
- 涉及函数、命令、协议或训练过程时，明确写出输入、关键处理和输出。
- 示例只展示当前结论所需的最小内容，并给出预期输出或可观察结果。
- 数字、性能结论和论文实验结果同时写清条件、指标和对照对象。
- 公式使用 LaTeX，并紧接着定义符号、单位和适用条件；图片不能替代正文中的公式或核心解释。
- API、协议和数据格式优先展示真实的最小输入/输出，不只做抽象描述。
- 在相关段落就近放引用；文末再列去重后的“来源”。
- 文末注明“资料核对日期：YYYY-MM-DD”。

推荐的来源格式：

```markdown
## 来源

- [文档或论文标题](URL) — 发布者，适用版本（如有），访问于 YYYY-MM-DD
```

## 禁止事项

- 不得只凭模型记忆编写事实性技术笔记。
- 不得用搜索结果摘要、转载聚合页或无来源的 AI 生成文章支撑核心结论。
- 不得为了显得完整而补写资料中不存在的参数、默认值、因果解释或历史。
- 不得把旧教程中的 API 当成当前推荐用法。
- 不得隐藏版本冲突、弃用警告、运行失败或资料缺口。
- 不得堆砌链接；每个来源都应实际支撑正文中的具体内容。
- 不得使用“像……一样”“可以把它想象成……”等比喻替代定义。
- 不得重复同一结论，或在结尾机械复述全文。

## 完成标准

只有同时满足以下条件才算完成：

- 写作前已阅读支持核心结论的一手资料；
- 时效性内容已核对目标版本、弃用状态和替代方案；
- 核心事实可追溯到正文引用或文末来源；
- 输入、处理、输出、前置条件和限制按主题需要被明确说明；
- 示例的验证状态真实可辨；
- 正文简洁直接、没有比喻和无依据补全。