Obsidian 笔记整理

把一次对话的成果变成可长期复用的知识资产。核心不是"记下来"，而是放进正确的位置、
补齐缺失的台阶、串上应有的链接，让笔记库从上往下读就是一条由浅入深的学习路径。

何时使用

• 用户要求把对话中的部分内容（手动挑选的片段）写进指定笔记
• 用户提问后希望结论沉淀进笔记库，并要求结合已有笔记上下文补全
• 用户要求梳理某个主题的知识体系、建 MOC、拆分过长笔记
• 用户要求在不同笔记之间建立/维护关联

不用于：纯阅读笔记回答问题（不落盘）、批量重命名/搬家等纯文件管理。

仓库识别（零配置，跨机器通用）

本 skill 不写死任何笔记库路径。每次操作按以下顺序定位仓库：

1. --root <绝对路径> —— 显式指定（最高优先）
2. --vault <别名> —— 查本 skill 目录下 vaults.json 的别名表（可选）
3. 自动识别：从当前工作区目录向上找 .obsidian/，找到即仓库根；
   找不到则在工作区直接子目录里找，唯一候选自动采用，多个候选则列出让你选
4. vaults.json 的 default 别名（兜底）

最省事的用法：把笔记库文件夹本身作为 WorkBuddy 工作区打开，之后所有命令都不用带定位参数。

多电脑 + git 同步的用法：每台机器把笔记库 clone 到任意位置、作为工作区打开即可，
skill 无需任何改动。vaults.json 里的 path 是机器相关的绝对路径，不要提交进笔记库的 git 仓库；
git 同步的注意事项见 references/git-sync.md。

下文命令示例中：

• PY = 本会话可用的 Python 3 解释器（优先 binary_context 里的托管运行时；
  独立使用时 python3 / python 均可，脚本只用标准库，Windows/macOS/Linux 通用）
• SK = 本 skill 目录下的 scripts/

环境自检

第一次使用时跑一次：

"$PY" "$SK/ob.py" probe

• available: true → CLI 就绪，可用链接感知的 move/rename 与官方索引。
• available: false（退出码 3）→ 正常现象，直接降级，用 vault.py 做文件扫描即可。
  不要报错、不要尝试安装或注册 CLI。启用方法见 references/obsidian-cli.md 第零节，
  只在用户主动问起时才说明。

六步工作流

第 1 步 · 确定要整理什么

从对话中截取与笔记主题相关的部分，而不是整段复制。
丢弃：来回试错的中间过程、与结论无关的家常、已经过时被推翻的说法。
保留：最终结论、踩过的坑、可复现的命令与配置。

拿不准时把候选片段列给用户确认，不要自行取舍后默默写入。

第 2 步 · 定位目标笔记

按 references/integration-playbook.md 第一节的决策树定位。快速检索：

"$PY" "$SK/vault.py" find   --query "GPIO"
"$PY" "$SK/vault.py" meta                          # 看 h1/tags/keywords 做语义匹配
"$PY" "$SK/vault.py" search --pattern "gpiod"
"$PY" "$SK/vault.py" tree                          # 先看一眼整体盘子

歧义（多篇同名/近名）时列出来让用户选，不要猜。

第 3 步 · 读取上下文并做差距分析

必读：目标笔记全文 + 所属主题 MOC + 阅读路径上相邻的笔记 + 反向链接。

"$PY" "$SK/vault.py" outline --file "Linux驱动.md"
"$PY" "$SK/vault.py" links                         # incoming/outgoing/unresolved

然后把新内容放进四象限（详见 playbook 第二节）：

• A 已有 → 不重写，补交叉引用
• B 补台阶 ← 新内容依赖笔记里没解释的概念 → 在依赖它的章节之前插入前置内容
• C 顺延 → 追加到对应章节或「五、进阶与变体」
• D 跨域 → 新建/追加到另一篇笔记，两处互挂链接

B 象限是本 skill 的核心价值，也最容易被跳过。 用户跳跃提问时，
先补台阶再放结论 —— 补到能落到公共基础（C 语法、shell、计算机组成）为止。

第 4 步 · 改写与落盘

按 references/note-style.md 的骨架与文风写。硬要求：

• 深度三支柱：心智模型先行（先立模型再挂命令）、概念先于操作（名词首次出现当场定义）、
  场景驱动收尾（真实场景 → 分析 → 多解法对比与风险）
• 反碎片：正文只管模型、因果、场景；选项细节收进 #### 【命令名】相关用法 速查表
• 沿用库内既有文风（见 note-style.md）：中文叙述、- 列表且句末无句号、
  术语保留英文原文、命令路径用反引号、整句警示用反引号包裹
• 编号沿用双轨制：顶层 一、二、三，子层 2.1 / 2.1.1
• 每节闭环：是什么 → 为什么 → 怎么做 → 怎么验证
• 核心机制配 Mermaid 图（选图与画法见 references/diagrams.md）：图辅助文字、
  紧跟相关段落、一屏放得下、写完在 Obsidian 里目测渲染
• 源码摘录三件套（细则见 note-style.md「六、代码引用与展开」）：
  ① 代码块标注来源文件 —— 项目根目录相对路径，优先以当前工作区为项目根，
  工作区不是代码项目时按对话上下文判断并注明；
  ② 函数摘录保留完整签名 —— 返回类型 + 函数名 + 形参列表 + {}，
  函数体省略处用注释标明省掉的内容，禁止"半截函数"；
  ③ 流程讲解图先行 —— 按函数调用关系或线程/核间时序组织叙述，先立时序图/流程图
  （贯穿全文的流程放笔记开头，局部流程放该独立部分开头），再按图编号逐步展开代码
• 为上下文连贯而新增的背景知识用 > [!note] 补充 标注，与用户原始内容区分开
• 推不出来、必须查源码才能确认的内容，标 > [!warning] 待核实，不要编

章节级编辑一律用 note.py，它支持 dry-run 与自动重编号：

# 先 dry-run 看 diff
"$PY" "$SK/note.py" insert --file "Linux驱动.md" \
    --heading "2.1.1 环境配置" --position under --content-file /tmp/sec.md --renumber --dry-run
# 确认无误再落盘（去掉 --dry-run）

• --position under 插入到该章节末尾；before/after 贴着标题插
• 标题不存在时加 --create-heading 在文末新建
• 插入导致后续编号错位时加 --renumber（中文编号章不受影响）
• --content 支持内联；--content-file - 读 stdin
• 整节替换用 replace（谨慎：只替换该标题下的正文，保留标题行）

更新 frontmatter：

"$PY" "$SK/note.py" frontmatter --file "Linux驱动.md" \
    --set 'tags=["Linux/驱动","SemiDrive/X9"]' --set updated=2026-09-04

diff 里删除行多于新增行就要停下来检查 —— 大概率误用了 replace。

第 5 步 · 挂链接与维护 MOC

四项收尾（详见 playbook 第四节）：

1. 主题 MOC 的阅读路径里有本篇，且位置反映深浅顺序
2. 正文提到的、已有独立笔记的概念都挂 [[wikilink]]
3. 笔记底部「延伸」写上一步 / 下一步 / 所属主题
4. unresolved 为空

跨笔记联动按联系类型处理：上下游依赖 → 互挂且 MOC 里排序；同层并列 → 同一分支下互挂；
引用关系 → [[B#章节]]；重复内容不自动合并，留互相指向并列入待办。

新建笔记时用 assets/templates/ 下的 topic-moc.md 与 sub-note.md 作骨架。

第 6 步 · 验证与汇报

"$PY" "$SK/vault.py" links                                     # 断链 / 孤儿 / 无出链
"$PY" "$SK/ob.py" exec --vault "<库名>" unresolved format=json # CLI 可用时
"$PY" "$SK/vault.py" outline --file "..."                      # 复核章节顺序与编号

CLI 可用时优先用它的 move / rename 做搬迁 —— 会自动改写全库 wikilink；
手工 mv 会留下一堆断链。

最后按 playbook 第五节的模板输出改动摘要：新增 / 补充完善 / 重排 / 跨笔记联动 / 待办。

硬约束

• 绝不删除或压缩用户已有的叙述，整理只做增补与重排。要重写必须用户明确要求。
• 不编造源码、寄存器地址、命令输出。推不出来就标 > [!warning] 待核实。
• 落盘前必须 dry-run 并实际看过 diff。
• 一次整理不超过 3 篇笔记。跨度更大时先改主笔记，其余列入待办交用户确认。
• 不改写用户的行话（mbox、R5、ko模块 之类原样保留）。
• CLI 不可用时静默降级，不打扰用户。
• 禁止 obsidian reload / restart，禁止未授权的删除、Publish、Sync 恢复、插件装卸。
• 笔记统一 UTF-8 + LF，git 跨平台同步不炸（细节见 references/git-sync.md）。

资源索引