Better Notes

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

核心规则

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

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

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

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

目标笔记在 Obsidian 库里（上级目录含 .obsidian/，或用户说明写给 Obsidian）时，另读 references/obsidian-datacore.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：

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

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

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

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

Obsidian 目标：交互组件

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

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

6. 语言准确性与去 AI 味

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

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

7. 交付前复核

逐项检查：

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

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

输出要求

默认使用 Markdown，并遵守：

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

推荐的来源格式：

## 来源

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

禁止事项

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

完成标准

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

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