better-notes git:20261027.b7972f3A

Immutable. This exact content never changes and is served at /api/v1/blob/f9c35b255981ee7c.

---
name: better-notes
description: 编写、整理或重写有事实依据的技术与知识笔记。用户要求“写笔记”“整理知识点”“做学习笔记”“写教程/概念说明”，尤其涉及 API、库、框架、论文、算法或可能随版本变化的内容时使用。笔记对象是论文时，按固定四部分模板写：研究现状和作者动机、方法简要介绍（带论文主图）、方法细节、实验。写作前必须先查阅网络上的官方文档、发布说明、论文、技术博客或文章，核对版本、弃用状态与替代方案；不能只凭模型记忆成文。输出简洁、直接，不用比喻，并把前置条件、输入、处理过程、输出、限制和来源说清楚。笔记保存在 Obsidian 库时，用 Datacore 的 JSX 交互组件取代 Mermaid 图，并在有助于理解处补充小组件。不用于仅做文字校对，或逐字整理用户提供的私人会议记录。
---

# Better Notes

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

## 核心规则

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

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

开始调研前读取 [references/research-and-verification.md](references/research-and-verification.md)。确定结构与措辞前读取 [references/note-style.md](references/note-style.md) 和 [references/humanizer.md](references/humanizer.md)。去 AI 味规则已内置，无需另行安装 `humanizer`。写正文和做内部编辑时另读 [references/language-precision.md](references/language-precision.md)，其中的 STE 准确性规则（一句一事、一词一义、具体动词、固定情态词与证据标签）与 humanizer 配合使用，默认 80% 模式。

笔记对象是一篇论文时，另读 [references/paper-note-template.md](references/paper-note-template.md)，按其中固定的四部分模板写，不使用下文的通用结构。

目标笔记在 Obsidian 库里（上级目录含 `.obsidian/`，或用户说明写给 Obsidian）时，另读 [references/obsidian-datacore.md](references/obsidian-datacore.md)，其中给出环境检查、组件写法、示例和验证脚本；设计组件界面前读 [references/widget-design.md](references/widget-design.md)。

## 工作流

### 1. 明确笔记任务

从用户输入中提取：

- 主题与目标读者；
- 想解决的问题；
- 期望深度和输出语言；
- 指定技术栈、版本、时间范围或来源；
- 笔记类型：论文笔记，还是 API、框架、概念等其他笔记；
- 目标格式与保存位置，包括保存位置是否在 Obsidian 库内。

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

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

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

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

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

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

按以下顺序选择来源：

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

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

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

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

写论文笔记时，一手资料是论文全文（PDF 或 arXiv HTML）和官方代码；必须读完全文，核对所读版本（如 arXiv v1/v2）和发表信息，不能只读摘要。

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

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

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

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

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

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

**论文笔记**：固定使用四部分模板，章节名称和顺序不改，写法见 [references/paper-note-template.md](references/paper-note-template.md)：

1. 一、研究现状和作者动机；
2. 二、方法简要介绍（含论文主图；这一部分自足，重读时只看它就能抓住论文主要内容）；
3. 三、方法细节（含流程图，Obsidian 里用 Datacore 组件）；
4. 四、实验（做了什么实验，得到什么结论）。

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

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

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

#### Obsidian 目标：交互组件

目标在 Obsidian 库内时，按 [references/obsidian-datacore.md](references/obsidian-datacore.md) 处理：

1. 检查 Datacore 已安装、已启用且开启了 JavaScript 视图；缺失时先询问用户，不要擅自改库配置。
2. 流程图、对比图用 `datacorejsx` 组件实现，不写 Mermaid（论文笔记的第三部分至少放一个流程组件）；再按"读者能多理解什么"补充必要的小组件（参数滑块、逐步播放、可点击轨迹、页面内运行最小示例等），一篇通常 2–6 个。
3. 组件里的数据和文案遵守同一套事实规则：来自已核对的来源；自拟参数或随机数据标注"示意"；计算类组件先与独立脚本的结果对照。
4. 组件界面按 [references/widget-design.md](references/widget-design.md) 设计：沿用主题变量、一个强调点、先按读者要做的事选形式、数值不靠悬停也能读到、动效克制。
5. 组件只是补充：删掉全部组件后，正文和表格仍完整。
6. 用 [references/datacore/smoke-test.cjs](references/datacore/smoke-test.cjs) 测试，并在对话回复里如实报告验证状态；没有在 Obsidian 里渲染过就不能说效果已确认。
7. 笔记正文不写组件说明：不写“由 Datacore 生成”“需要启用 JavaScript 视图”“已通过测试”“插件版本”等，这些只放在回复里。

### 6. 语言准确性与去 AI 味

先按 [references/language-precision.md](references/language-precision.md) 的 A 部分检查准确性：步骤句一个动作，术语全文同名，动词具体，指代明确，数字带单位，情态词和证据标签含义固定。再按 [references/humanizer.md](references/humanizer.md) 对事实草稿做一次内部编辑：

- 通读全文，先检查信息顺序和段落，再清理空泛铺垫、无意义对比、重复结尾、机械排比、夸大和装饰性格式。
- 围绕具体事实重写，保留每项独立信息；不为显得自然编造经历、观点或细节。
- 对照编辑前后的事实、数字、条件、版本、推断强度和引用归属。风格编辑不修改代码、命令、路径、URL、元数据、数据、公式或引用原文；技术错误回到事实核对步骤处理。
- 保留有信息的对比、真实三项列表、必要定义、限制和验证状态，不按禁词表机械删改。
- 再读一次，修正仍显刻意或重复的段落。只交付最终笔记，不附草稿、模式清单或编写过程。

### 7. 交付前复核

逐项检查：

- 每个时效性事实是否有当前来源；
- 是否仍出现已弃用 API，却没有显式说明其状态和替代方案；
- 输入、输出、前置条件和失败情况是否具体；
- 示例与正文中的名称、参数和版本是否一致；
- 是否把推断、经验或未验证内容写成事实；
- 术语是否全文同名、步骤句是否一个动作、数字是否带单位和对象、“必须 / 应当 / 可以 / 可能”是否用在固定含义上；
- 是否存在比喻、宣传词、无意义对比、重复结尾、机械排比或不影响理解的背景；
- 风格编辑是否改变了技术内容、事实范围、真实不确定性或引用归属；
- 来源是否包含标题、链接、访问日期，版本敏感时是否包含版本；
- 论文笔记：四部分名称与顺序是否与模板一致；第二部分是否有论文主图（取不到时是否已说明）且自足；第四部分的结论是否带指标、条件、对照对象和表号或图号；推断和“论文未说明”是否已标明；
- Obsidian 目标：是否残留 Mermaid、组件是否都通过冒烟测试、是否沿用主题变量且无装饰性效果、自拟数据是否标了"示意"、删去组件后正文是否仍完整、笔记正文里是否没有任何关于组件、Datacore 或测试状态的说明（这些只在回复里报告）。

任一核心项不满足时先修正，不要宣布完成。维护或评估本 skill 时，可按 [evals/humanizer-cases.md](evals/humanizer-cases.md) 检查风格编辑边界；Obsidian 组件规则可按 [evals/obsidian-widget-cases.md](evals/obsidian-widget-cases.md) 检查；论文笔记模板可按 [evals/paper-note-cases.md](evals/paper-note-cases.md) 检查。场景清单和结构校验不代表生成行为已经通过验证。

## 输出要求

默认使用 Markdown，并遵守：

- 开头直接定义主题，不写泛泛背景和铺垫。
- 使用短段落、明确标题和具体动词；段落长短按内容变化，不机械拆成相同句数，不给每条列表添加加粗标签。
- 每句话应增加定义、事实、解释、条件或例子；删除聊天套话、空泛铺垫和正文中的编写过程说明。
- 不使用比喻或拟人化表达；直接说明数据、状态和操作。
- 第一次出现术语时给出定义，后文保持同一名称。
- 涉及函数、命令、协议或训练过程时，明确写出输入、关键处理和输出。
- 示例只展示当前结论所需的最小内容，并给出预期输出或可观察结果。
- 数字、性能结论和论文实验结果同时写清条件、指标和对照对象。
- 公式使用 LaTeX，并紧接着定义符号、单位和适用条件；图片和交互组件不能替代正文中的公式或核心解释。
- 目标是 Obsidian 时，图用 Datacore 组件而不是 Mermaid；组件之外仍保留完整的静态正文和表格。
- API、协议和数据格式优先展示真实的最小输入/输出，不只做抽象描述。
- 论文笔记的数字和结论写明实验条件、指标和对照对象，并标出论文的表号或图号。
- 在相关段落就近放引用；文末再列去重后的“来源”。
- 文末注明“资料核对日期：YYYY-MM-DD”。

推荐的来源格式：

```markdown
## 来源

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

## 禁止事项

- 不得只凭模型记忆编写事实性技术笔记。
- 不得用搜索结果摘要、转载聚合页或无来源的 AI 生成文章支撑核心结论。
- 不得为了显得完整而补写资料中不存在的参数、默认值、因果解释或历史。
- 不得在没读完论文全文时写论文笔记；不得用自绘图冒充论文原图。
- 不得把旧教程中的 API 当成当前推荐用法。
- 不得隐藏版本冲突、弃用警告、运行失败或资料缺口。
- 不得堆砌链接；每个来源都应实际支撑正文中的具体内容。
- 不得使用“像……一样”“可以把它想象成……”等比喻替代定义。
- 不得重复同一结论，或在结尾机械复述全文。
- 不得在 Obsidian 笔记里写 Mermaid 图（Datacore 不可用且用户不愿安装时除外）。
- 不得在组件里放资料不支持的数据、步骤或因果；自拟参数和随机数据必须在组件内标注"示意"。
- 不得让核心结论只存在于组件里；不得为装饰添加没有解释价值的组件。
- 不得在笔记正文里写组件的来源、依赖、插件版本或验证状态说明。
- 不得在没有于 Obsidian 里渲染确认时，声称组件效果已确认。

## 完成标准

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

- 写作前已阅读支持核心结论的一手资料；
- 时效性内容已核对目标版本、弃用状态和替代方案；
- 核心事实可追溯到正文引用或文末来源；
- 输入、处理、输出、前置条件和限制按主题需要被明确说明；
- 论文笔记：已读论文全文，四部分结构与模板一致，第二部分自足并含主图或说明，第四部分结论可追溯到论文的表和图；
- 示例的验证状态真实可辨；
- 已完成语言准确性检查、去 AI 味编辑与编辑前后核对，正文简洁直接、没有比喻、无依据补全、空泛铺垫或重复结尾；
- 技术内容、事实条件、真实不确定性和引用归属未被风格编辑改变；
- Obsidian 目标：环境已检查，图已改为通过冒烟测试的 Datacore 组件，笔记正文不含组件说明，验证状态已在回复里如实报告。