obsidian-notes-lite

在用户的本地 Obsidian 笔记库里找笔记、读笔记、写笔记、导出笔记。只读写磁盘上的 .md 文件，不碰 Obsidian 客户端界面。

运行方式

所有命令以本文件所在目录为基准（下称 <skill>）：

python <skill>/scripts/notes.py <command> [options]

首次使用

python <skill>/scripts/notes.py init --vault "<笔记库根目录>"

路径必须已存在，程序绝不替用户创建目录；已配置过会返回 CONFIG_EXISTS，确认要换库才加 --force。初始化会自动建一次索引，完成后即可搜索。需要临时切换库时用环境变量 OBSIDIAN_NOTES_LITE_VAULT=<目录>。

命令速查

多个关键词用空格分隔，含义是「必须同时出现」。正文较长或多行时用 --content-file <路径>，避免 shell 转义问题。

硬性规则

1. 写入默认是预演。 create / append 不加 --confirm 只计算并输出将要发生的变化，绝不落盘。必须先把预演结果（status:"preview"、diff、would_create）讲给用户，得到明确同意后才加 --confirm。
2. 追加必须带指纹。 先 read 取 sha1，再 append --confirm --expect-sha1 <sha1>。返回 FILE_CHANGED 表示笔记在此期间被手动改过：重新读取、重新展示差异，不要绕过或换参数硬写。
3. 不替用户挑重名笔记。 read --title 返回 AMBIGUOUS_TITLE 时，把 details.candidates 原样列给用户选，再用 --path 继续。
4. 只增不改。 不要用这个技能做润色、重写、摘要、批量修改；用户的原文一个字都不要动，追加内容写在末尾。唯一例外：用户明确要求「改写 / 重排格式 / 合并」。此时先 read 全文，把要改的点和改后的骨架讲给用户，得到同意后再直接覆盖文件（create 会返回 FILE_EXISTS，改用 Write 覆盖），写完跑一次 index 刷新索引。
5. 搜索默认只给片段。 用户明确要正文时才加 --with-content；--no-refresh 只在需要旧快照时使用，并在回答里说明结果可能不是最新。
6. 对外文件用 export-search。 它生成的报告只含相对路径、可直接分享；不要手工拼报告，也不要把本机绝对路径贴进给别人的文档。
7. 绝不凭空造链接。 「相关 / 延伸 / 参见」里的 [[...]] 只能指向库里真实存在的笔记：写之前先用 search 核对标题，标题对不上就用 [[真实标题|显示文字]]。搜不到可链的笔记，就省略这一节或留一句「暂无相关笔记」，不要为了版面好看编造标题、作者、页码或引文。同理，正文里提到的「另有一篇讲 X 的笔记」必须是 search 能查到的，不能凭印象虚构。

笔记格式规范

新建笔记、或用户说「按某篇的格式改」时，用下面这套骨架。若用户点了具体的参考笔记，先读那篇、把它的格式特征列给用户确认，再动笔——参考笔记的写法优先于本节默认值。

• 开头写 YAML frontmatter，tags: 用列表，2–3 个标签，尽量复用库里已有的标签词。
• 不写 H1 标题，标题即文件名。
• 开篇 1–2 段不带小标题的引子：先把观点立住、把问题问清，再进编号章节。
• 章节从 ### 1. xxx 起编号，细分用 #### 1.1 xxx；别把 ## 和 ### 混着当两套层级用。
• 正文以段落叙述为主，少用分点罗列；论证要连成话，而不是罗列条目。
• 公式用 $...$（行内、两侧不留空格）与 $$...$$；display 公式直接嵌在句子中间，不单独占行。
• 命题、例子、想法分别用 > [!note] 标题、> [!example] 例子1.1.1、> [!tip] 核心想法1.1 承载。callout 内每一行都要带 >，callout 内分段写一个孤立的 >。
• 例子编号跟着小节走：1.2 节里的例子叫「例子1.2.1」。
• 列表统一用 *，不用 -。
• 章节之间用 --- 分隔。
• 强调用整句加粗做转折（「这类错误最危险」），一节最多一处，不要满篇加粗。
• 写完后如需引用其他笔记，走硬性规则 7。
• 落盘前再过一遍「去 AI 味」那一节。

去 AI 味

用户说"AI 味太重""不像人写的"时，或每篇长笔记写完之前，走一遍这一节。完整清单（24 条模式，含英文例句）在 ~/.workbuddy/skills/humanizer/SKILL.md，源自 Wikipedia 的 Signs of AI writing；但那份清单以英文政经文本为主，中文数学笔记实际会踩的坑集中在下面几条，按出现频率排。

一、删

• 负面平行："不是 X，而是 Y""不仅……而且……"。中文笔里最高频的指纹，一篇超过两处就露馅。改成直接陈述 Y。
• 破折号：一段最多一个，能换句号就换。这是英文模式的直接迁移，中文里本来就用得少。
• 加粗：只留真正需要回头查的结论，一节最多一处。满篇加粗是机械强调，不是重点。
• 路标语："下面我们来看""这解释了两件事""换句话说""值得注意的是"。全删；删完段落接不上，说明逻辑本来没连上，补一句实打实的过渡，而不是补一个路标。
• 泛化收尾："这体现了……之美""由此可见一斑""这正是数学的迷人之处"。删。
• 模糊归因："众所周知""易知""显然"。要么给依据，要么删——数学笔记里"易知"十有八九是在掩盖一步没想清楚的地方。
• 三段式：三个要点、三个例子、三段并列。砍掉一个，或加一个凑成不对称的四个。

二、破均匀

• 句长：挑一处 30 字以上的长句，砍成 4 字短句 + 26 字长句。全程同一节奏最像机器。
• 段落：最长段与最短段相差五倍以上；同类例子别用同一个模子（"错解→真解→错在哪"）套三遍。
• 颗粒度：有的一步带过，有的展开到两倍。不要每步都解释到尾。

三、补毛刺（真加，不是装饰）

• 具体细节：哪本书、哪次考试、谁的原话。
• 私人判断："我不喜欢这个说法""这一步我自己也漏过"。
• 故意的省略："这里先不证，等用到再说"。

验收

1. 读出声。像讲课、像公众号推文 → 不合格；像写给自己的备忘 → 合格。
2. 随机抽一句问自己：我会不会在微信里这么跟同学讲？不会，就改。

别做的：加"说白了""其实吧"不叫去味，那是给机器套了件口语外套，骨架照旧均匀。改的是信息怎么分配、谁在说话，不是语气词。

典型流程

• 「我笔记里关于判别式的内容在哪？」→ search -q "判别式" → 用 results[].path + snippet 回答，必要时再 read。
• 「把《一元二次方程》读给我听」→ read --title "一元二次方程" → 用 content 回答（truncated 为真时说明原文总字数）。
• 「把今天这个结论记一下」→ 先 search 确认没有重复 → create 预演 → 用户同意 → create --confirm。
• 「把刚才搜到的整理成一个文件发我」→ export-search -q "..." --out <目标路径> → 把 target 告诉用户。
• 「按《某篇》的格式改一下这篇」→ read 参考笔记 + read 待改笔记 → 先把参考笔记的格式特征列给用户 → 说明新骨架 → 用户同意 → Write 覆盖 → index 刷新。
• 「写得 AI 味太重了」→ 先诊断具体是哪几条（负面平行 / 破折号 / 加粗 / 路标语 / 三段式），挑两三句给用户看改前改后，再整篇重写；不要只说"会更自然"。

出错时

失败返回 ok:false，error 里有 code / message / why / next。把 message 转述给用户，按 next 执行；不要用同样参数重试或自行拼路径。
常见码：NOT_CONFIGURED（先 init）、VAULT_NOT_FOUND、FILE_NOT_FOUND、AMBIGUOUS_TITLE、FILE_EXISTS、FILE_CHANGED、PATH_OUTSIDE_VAULT、TARGET_INSIDE_VAULT、TARGET_EXISTS、PARENT_MISSING。

文件位置

配置与索引都在笔记库之外：Windows %LOCALAPPDATA%\obsidian-notes-lite，macOS ~/Library/Application Support/obsidian-notes-lite，Linux ~/.local/share/obsidian-notes-lite。--home 可临时指定。索引可随时用 index --full 重建，删掉也不影响笔记。