{"skill":{"slug":"kg-note-method-obsidian","displayName":"Kg Note Method Obsidian","summary":"Obsidian笔记库按KG笔记法整理——四种笔记类型、链接权限、关系中转、命名规范、新旧分离。自动纠错+建关系+去重+补缺+无关内容分离+分层加载","description":"---\r\nname: kg-note-method-obsidian\r\ndescription: Obsidian笔记库按KG笔记法整理——四种笔记类型、链接权限、关系中转、命名规范、新旧分离。自动纠错+建关系+去重+补缺+无关内容分离+分层加载\r\nversion: 3.23.0\r\nauthor: Hermes Agent\r\nlicense: MIT\r\nmetadata:\r\n  hermes:\r\n    tags: [obsidian, kg-notes, knowledge-graph, token-saving]\r\n---\r\n\r\n# KG笔记法 — Obsidian 笔记整理\r\n\r\n<!-- 速查: 内容检查+拆分→分类匹配→名称匹配→图片保护→直链检查→查相关笔记→查重→更改清单→补完计划→收尾 -->\r\n\r\n> ⚠️ **不主动改写笔记**：所有命令（除 `kg 完善`），尽量保留原文原貌。\r\n\r\n## ⚡ 手动调用命令\r\n\r\n> 所有命令第一步：`skill_view(name='kg-note-method-obsidian')` 加载本 skill。不可跳过。\r\n\r\n### `kg start`\r\n加载本 skill。\r\n\r\n### `kg \"笔记名.md\"/\"关键词\"`\r\n`kg start` → 建执行清单+检查清单到 `_working/`（清单强制）→ 查找笔记逐条跑 ①-⑥ → ⑦ → 按清单执行 → ⑧，无笔记则新建再跑\r\n\r\n### `kg 完善 \"笔记名.md\"`\r\n`kg start` → 建执行清单+检查清单到 `_working/`（清单强制）→ 逐条跑 ①-⑥ → ⑦ → ⑨ → 按清单执行 → ⑧\r\n\r\n### `kg 检查 \"笔记名.md\"` / `kg 检查 \"关键词\"`\r\n与其他命令相同的清单（清单名=笔记名），区别仅在于：分析完成后**询问是否执行**，等用户确认后才动手。\r\n\r\n### `kg 查看 \"笔记名.md\"`\r\n加载 L0（frontmatter）。相关则加载 L1（对应段落）。仍不足加载 L2（全文）。\r\n\r\n> 用户消息以 `kg` 开头 → 必须先加载本 skill。路径含 vault → 自动触发，用上述命令更可靠。\r\n\r\n| `_working/` | 当前任务清单目录 |\r\n\r\n**📦 内置脚本和参考（skill_view + file_path 加载）：**\r\n1. `checklist-generator.py` — 自动生成执行清单+检查清单。用法：`python <script> <任务名> <步1> [步2...]`\r\n2. `yaml-validator.py` — 编辑后验证 YAML 结构。用法：`python <script> <文件.md>`\r\n3. `enrichment.py` — 补完计划：将搜索结果格式化为 KG 标准段落追加到笔记。用法：`echo \"内容\" | python <script> <文件.md> --stdout` 或 `--text \"...\"`\r\n\r\n**清单目录：** vault 根目录下的 `_working/`\r\n\r\n### 两个清单文件\r\n\r\n| 文件 | 用途 | 更新时机 |\r\n|:----|:-----|:--------|\r\n| `{任务名}_执行清单.md` | 预判所有步骤的详细操作 | 任务开始前一次性生成 |\r\n| `{任务名}_检查清单.md` | 追踪每步完成/失败状态 | 每步完成后立即更新 |\r\n\r\n### 执行清单格式\r\n\r\n**执行时照做，不重复分析。**\r\n\r\n```markdown\r\n# {任务名} — 执行清单\r\n## 步骤\r\n### 1. 重命名「美食-青岛.md」→「青岛美食.md」（②名称检查：主体名禁` - `）\r\n- 操作类型：mv\r\n### 2. 修改「笔记A.md」tag\r\n- 操作类型：patch\r\n- tags: [旧tag] → tags: [某物]\r\n### 3. 新建「笔记A - 关系 - 笔记B.md」\r\n- 操作类型：新建文件\r\n- 内容：[[笔记A]]关系描述[[笔记B]]。\r\n### 4. 检查两端残留链接 + 查重\r\n- 操作类型：检查验证\r\n### N. 删除本任务的2个清单文件\r\n- 操作类型：删除文件\r\n```\r\n\r\n### 检查清单格式\r\n\r\n**极度精简一行状态码。执行清单已含完整描述，这里只记进度。每步一个位：`0`=未做，`1`=完成。** 文件内容仅一行：\r\n\r\n```\r\n0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0:0\r\n```\r\n\r\n步数 = 冒号分隔的位数。更新时 `patch` 单字符 `0`→`1`（只改对应位，不改全文）。失败步记步号到末尾：` | 失败:3,7`。**完整标识**：检查清单全 `1` + 执行清单最后一步≥\"删除本任务2个清单文件\"。\r\n\r\n格式示例（17步，第1、3步已完成，第7步失败）：\r\n```\r\n1:0:1:0:0:0:0:0:0:0:0:0:0:0:0:0:0 | 失败:7\r\n```\r\n\r\n### 执行流程\r\n\r\n**步0 和步5 不可跳过。跳过步0 → 同名任务已有清单却被覆盖。跳过步5 → 用户不知道还有其他任务。**\r\n\r\n```\r\n0. 任务开始前（不可跳过）：\r\n   search_files target=content, pattern='检查清单', path=_working/\r\n   ├─ 有同名任务的清单 → read_file 检查清单+执行清单 → 检查是否可续接\r\n   │  （有未完成位 且 最后一步不是\"删除本任务\"）→ 从未完成步开始\r\n   │  否则（全1或最后一步是删除）→ 删除清单文件，重新建\r\n   ├─ 有其他任务的清单（不同名）→ 当前任务执行完后步5再提示\r\n   └─ 无清单 → **清理同名残留：先 `search_files` 搜 `_working/` 下所有包含该笔记名的清单文件并删除**（防止之前建错的 `笔记名+命令名` 形式残留）。\r\n      然后生成执行清单+检查清单。**清单名=笔记名(用户给的参数)，不加任何命令前缀/后缀。**\r\n      **参数映射：** `kg 检查 苏州` → checklist-generator.py 第一个参数传 `苏州`，不传 `苏州检查`\r\n      `kg \"青岛美食.md\"` → 传 `青岛美食`\r\n      `kg 完善 资本收益.md` → 传 `资本收益`\r\n      优先用脚本（需设环境变量）：\r\n      `OBSIDIAN_VAULT=\"<vault绝对路径>\" python scripts/checklist-generator.py <任务名> <步1> [步2...]`\r\n      或用完整路径：`python <script_full_path> <任务名> <步1> [步2...]`（此时仅打印到终端，需手动保存）\r\n      ⚠️ 脚本在终端输出清单不等于文件已保存到 _working/。\r\n      **必须验证：** 脚本执行后立即 `search_files path=_working/ pattern=<任务名>` 确认清单文件存在：\r\n      ├─ 不存在 → 重跑（检查环境变量或手动 copy 内容建文件）\r\n      └─ 存在 → 继续\r\n      无脚本环境 → 手动建（格式见上）\r\n\r\n1. **命令流程分支：**\r\n   ├─ **`kg 检查` → 分析阶段（只读不写）：**\r\n   │   ├─ 逐条跑 ①-⑥ → ⑦ → ⑨，**此阶段禁止任何 patch/write_file/mv**\r\n   │   ├─ **⑧（生成变更清单）两个动作：**\r\n   │   │   ① 在回复中向用户列出所有变更\r\n   │   │   ② **同时用 `write_file` 覆盖执行清单，把具体的操作步骤写进去**（每条操作含：文件、操作类型、具体内容）\r\n   │   │      ⚠️ 清单源自初始脚本，但分析后才产生具体内容。不能只列在回复里，必须写回清单文件。\r\n   │   ├─ **同步更新检查清单 bitmask 步数** — 执行清单步骤数变化后，检查清单的位也要对应\r\n   │   ├─ → **询问用户「是否执行？」**\r\n   │   │     「📋 分析完成，发现以下问题：\\n        · 傻瓜.md: tags为空→[概念], 删除无关行\\n     是否执行这些修改？」\r\n   │   │     等用户回复\"执行/动手/是\" → 进入执行阶段\r\n   │   │     用户说\"不/算了\" → 删除清单，结束\r\n   │   └─ **⚠️ 分析阶段动手修改是最高频错误** — read_file 后会产生\"这里要改\"的冲动，必须克制。只更新执行清单，不动笔记文件。分析阶段的假设是\"没有写操作\"。\r\n   │\r\n   └─ **`kg \"笔记名\"` / `kg 完善` → 直接执行（不询问）：**\r\n        逐条跑 ①-⑥ → ⑦ → ⑨(仅完善)，分析和执行合一。发现一个问题就把操作记入执行清单（write_file 追加或覆盖）→ 立即执行 → 更新 bitmask。不等待用户确认。\r\n        完成后 → ⑧（列出所有变更）\r\n\r\n2. 每步完成后 → 立即 `patch` 检查清单，将该步对应的 `0` 改为 `1`（单字符替换，不得用 `write_file` 重写全文）。失败则追加 `| 失败:N`。\r\n   **patch 操作安全规则（适用所有文件编辑）：**\r\n   - `patch` 的 old_text 必须足够短且唯一，**禁止跨 frontmatter 边界**（`---` 之间 vs `---` 之外分开编辑）\r\n   - 编辑笔记文件后，立即调用 `python scripts/yaml-validator.py <文件>` 验证 frontmatter 闭合\r\n   - 涉及 YAML 字段（tags/abstract/aliases）用单行 patch，不要大段替换\r\n3. 全部完成 → read_file 检查清单+执行清单，确认检查清单所有位均为 `1` 且执行清单最后一步为\"删除本任务2个清单文件\"。是则删除两个清单文件；否则说明执行不完整，删除清单并通知用户。\r\n4. 中途中止 → 清单文件保留，下次会话恢复\r\n\r\n**5. 任务完成后（不可跳过）：**\r\n   search_files target=files, pattern=*检查清单*, path=_working/\r\n   ├─ 有 OTHER 清单文件 → 逐条 read_file 读取 → 列给用户：\r\n   │     「📋 还有未完成任务：\r\n   │       · 小村庄 — 完成度 0/14（14步未完成）\r\n   │       · 美食-青岛 — 完成度 0/17」\r\n   │     → clarify 询问：「是否继续完成某个？」\r\n   │     → 用户选是 / 指定某个 → 开始执行\r\n   │     → 用户选否 → 结束\r\n   └─ 无 → 结束\r\n```\r\n\r\n> 清单文件不在 KG 图谱内，禁止用 `[[链接]]`。纯文本跟踪用。\r\n\r\n## 四种类型\r\n\r\n所有主体笔记（概念/某物/skill）**统一 L0 为 `abstract`**，一句让人看明白的核心简介。\r\n\r\n| 类型 | tag | `[[链接]]`? | 文件名含`-`? | 内容 |\r\n|:---|:---|:---:|:---:|:-----|\r\n| **概念笔记** | `概念` | ❌ | ❌ | 抽象概念 |\r\n| **某物笔记** | `某物` | ❌ | ❌ | 具体人/物/地点 |\r\n| **Skill笔记** | `skill` | ❌ | ❌ | 技能块/技巧/经验/攻略/操作步骤/执行清单 |\r\n| **关系笔记** | `关系` | ✅唯一 | ✅ 格式：`A - 关系 - B` | 一句话+两个`[[链接]]`，禁表格/段落/标题 |\r\n\r\n> 主体笔记=概念+某物+skill。关系笔记=线。攻略类文件→归入 **skill 笔记**。\r\n\r\n## L0/L1/L2 分层加载\r\n\r\nL0 搜索时自动加载（匹配到即读 frontmatter）。L1/L2 需要时手动加载。\r\n\r\n| 层级 | 概念笔记 | 某物笔记 | Skill笔记 | 何时加载 |\r\n|:---:|:--------|:--------|:----------|:--------|\r\n| **L0** | `abstract:` YAML | `abstract:` YAML | `abstract:` YAML | 搜到即加载 |\r\n| **L1** | `## 核心规则` 段落 | `## 基本信息` 段落 | `## 步骤` / 技能块 | L0相关后加载 |\r\n| **L2** | 全文+来源 | 全文+来源 | 全文+来源 | 需要细节时 |\r\n\r\n## 操作流程\r\n\r\n> **两阶段模型：** `kg 检查` 的分析阶段只读不写（read_file/search_files 可以，patch/write_file/mv 禁止），分析完写回执行清单→问用户→等确认再执行。\r\n> `kg 完善` / `kg \"笔记名\"` 无分析阶段——分析和执行合一，发现即动手。不询问。\r\n\r\n逐条跑 ①-⑥ → ⑦ → 按清单执行 → ⑧\r\n\r\n---\r\n\r\n### ① 内容检查 + 拆分\r\n```\r\nread_file 先读。内容 > tag > 名称。\r\n└─ 内容有混入/分属多主题（表格/段落/无关信息混在主体或关系里）\r\n   └─ 搜库判断：\r\n      ├─ 已有主体且缺此信息 → 生成时写入清单：patch 移入该主体\r\n      ├─ 已有更完整 → 生成时写入清单：patch 删除混入内容\r\n      └─ 无主体 → 生成时写入清单：新建文件（保留原笔记，只拆分不改写）\r\n```\r\n\r\n### ② 分类匹配\r\n```\r\n└─ 内容与当前 tag 不匹配：\r\n   └─ 抽象定义+规则 → 生成时写入清单：patch tags 为 [概念]\r\n   └─ 描述具体人/物/地点属性 → 生成时写入清单：patch tags 为 [某物]\r\n   └─ 步骤清单/技巧/能执行/经验 → 生成时写入清单：patch tags 为 [skill]\r\n   └─ 一句话+俩 [[链接]] → 生成时写入清单：patch tags 为 [关系]\r\n```\r\n\r\n### ③ 名称匹配\r\n```\r\n└─ 主体笔记名含 ` - `（误认为关系笔记）→ 生成时写入清单：重命名 mv\r\n└─ 文件名 与 核心内容 不匹配 → 生成时写入清单：重命名 mv（以核心内容为准）\r\n```\r\n\r\n### ④ 图片保护\r\n```\r\n└─ 已有 ![]() 图片：\r\n   ├─ 有效（HTTP 200）→ 不动\r\n   └─ 失效（404/403）→ 生成时写入清单：搜有效替代链接\r\n└─ 没有图片 → 跳过\r\n```\r\n\r\n### ⑤ 直链检查\r\n```\r\nread_file 检查正文 [[链接]]：\r\n└─ tag 是 概念/某物/skill（主体笔记）且有 [[链接]]：\r\n   └─ 检查 [[链接]] 目标是否存在：\r\n      ├─ 存在 → 生成时写入清单：新建关系笔记（A - 关系 - B）+ 删原直链（先补关系再删链）\r\n      └─ 不存在 → 生成时写入清单：[[链接]] 转为纯文本（删除 [[ ]] 保留字词）\r\n└─ tag 是 关系 → [[链接]] 合法，不动\r\n```\r\n\r\n### ⑥ 查相关笔记 + 关联处理\r\n\r\n按以下顺序检查 tag 类型，在清单生成时写入：\r\n\r\n```──────────────────────────────────────\r\n└─ tag 是 概念/某物/skill（主体笔记）：\r\n   └─ search_files 搜库中有关联的其他主体笔记\r\n   └─ 每找到一条有效关联 → 生成时写入清单：新建关系笔记（A - 关系 - B）\r\n──────────────────────────────────────\r\n└─ tag 是 概念（特殊处理——概念之间常需连线成网）：\r\n   └─ 列出本概念相关的其他概念\r\n   └─ 搜库查找：\r\n      ├─ 已有 → 生成时写入清单：新建关系笔记（A - 关系 - B）\r\n      └─ 没有 → 生成时写入清单：新建概念笔记 + 建关系\r\n──────────────────────────────────────\r\n└─ tag 是 关系（检查两端主体是否存在）：\r\n   └─ search_files 查 A 端和 B 端是否已有主体笔记\r\n      ├─ 一端有、一端没有：\r\n      │  └─ 判断缺失端：\r\n      │     ├─ 缺失端是概念 → 生成时写入清单：新建概念笔记 + 两端建关系\r\n      │     └─ 缺失端不是概念 → 生成时写入清单：把关系笔记内容移入已有主体（转纯文本）+ 删除关系笔记\r\n      ├─ 两端都没有：\r\n      │  └─ 判断两端：\r\n      │     ├─ 两端都是概念 → 生成时写入清单：新建两端概念笔记 + 两端建关系\r\n      │     ├─ 一端是概念 → 生成时写入清单：新建概念笔记 + 把关系笔记内容移入已有主体（转纯文本）+ 删除关系笔记\r\n      │     └─ 两端都不是概念 → 不改动\r\n      └─ 两端都有 → 生成时写入清单：跳过（已有主体，关系笔记正常即可）\r\n```\r\n\r\n### ⑦ 查重（R7）\r\n\r\n```\r\n└─ search_files 通过关系笔记连接的目标主体笔记（反向追踪）：\r\n   └─ 检查两个主体之间是否有多条关系笔记：\r\n      ├─ 多条同向（A→B 多条）→ 生成时写入清单：选最佳名称保留，其余删除\r\n      ├─ 双向（A→B + B→A）→ 生成时写入清单：保留不冲突\r\n      └─ 同语义覆盖（一条含归属+类型+位置等，另一条只是子集）→ 生成时写入清单：保留语义更全的一条，删子集\r\n   └─ 每条被保留的关系笔记 → 生成时写入清单：校验文件名最佳匹配\r\n```\r\n\r\n### ⑧ 更改清单\r\n操作完成后在回复中列出所有更改：新建/修改/删除的文件清单。\r\n**分析阶段的⑧不同：** 分析完成后的⑧不仅要列出变更，还必须用 `write_file` 覆盖 `_working/` 下的执行清单，\r\n把具体的操作步骤写入（替换初始模板），同时更新检查清单 bitmask 步数。然后等用户确认后才进入执行。\r\n\r\n### ⑨ 补完计划\r\n优先用脚本：`python scripts/enrichment.py <笔记.md> --stdout` 预览格式化的补充内容，确认后再追加。\r\n无脚本环境 → 手动写：\r\n\r\n```\r\n└─ tag 是 概念/skill 笔记：\r\n   └─ 网络搜索 What、Why、Who、When、Where、How、How much、Effectiveness\r\n   └─ 搜到有用信息 → 写入笔记对应段落并标明出处\r\n   └─ 需改写原文 → clarify 询问用户确认后再改\r\n└─ tag 是 某物笔记：\r\n   └─ 查询具体属性信息（位置/参数/数据等）并填写\r\n```\r\n\r\n## 规则\r\n\r\n### R4：Skill 结构\r\nSkill笔记=步骤清单/技巧/能执行/经验/攻略的集合，必须有完整的可执行技能块（步骤+陷阱+验证），信息密度够大才能让 agent 直接用。任何可执行的流程、经验、技巧、攻略都归入 skill。\r\n\r\n标准结构（L1）：\r\n```\r\n---\r\nname: 技能名\r\ndescription: 一句话描述\r\nversion: x.x.x\r\n---\r\n\r\n# 标题\r\n\r\n## 步骤\r\n1. ...\r\n2. ...\r\n\r\n## 陷阱\r\n- ...\r\n```\r\n\r\n### R5：图片保护\r\n笔记中已有图片禁止删除。图片嵌入见①步（同步图片嵌入）。\r\n\r\n## 模板\r\n\r\nabstract 只放 YAML frontmatter。正文在闭合 `---` 之后，闭合不可省略。\r\n\r\n**概念：**\r\n```yaml\r\n---\r\ntags: [概念]\r\nabstract: 一句话核心定义\r\n---\r\n```\r\n正文结构（L1）：\r\n```\r\n## 核心规则\r\n...\r\n## 来源\r\n...\r\n```\r\n\r\n**某物：**\r\n```yaml\r\n---\r\ntags: [某物]\r\nabstract: 一句话简介\r\n---\r\n```\r\n正文结构（L1）：\r\n```\r\n## 基本信息\r\n...\r\n```\r\n\r\n**Skill：**\r\n```yaml\r\n---\r\ntags: [skill]\r\nname: 技能名\r\nabstract: 一句话描述\r\nversion: x.x.x\r\n---\r\n```\r\n正文结构（L1）：\r\n```\r\n## 步骤（技能块/技巧/经验/攻略/执行清单）\r\n...\r\n## 陷阱\r\n...\r\n```\r\n\r\n**关系：**\r\n```yaml\r\n---\r\ntags: [关系]\r\n---\r\n```\r\n正文：`[[A]]关系描述[[B]]。` 一句完整句子（含动词+句号），禁止 `created`/`source`/标题行。\r\n\r\n## 速查\r\n\r\n```\r\n内容检查+拆分→分类匹配→名称匹配→图片保护→直链检查→查相关笔记→查重→更改清单→补完计划→收尾\r\n```\r\n\r\n## 陷阱（按频率排序）\r\n\r\n- **不看内容就动手** → 涉文件操作必须先 `read_file`\r\n- **见链接就动手/多链/复合句** → 先看tag→关系链接合法；正文只允许2链；复合因果拆多条(⑥关联处理自动校验)\r\n- **建完主体停手/忘查另一端/直链先删后补** → 同轮次搜关联建关系(⑥)；直链先补关系再删\r\n- **多主体不扫/缺端直接删/关系重复** → ⑥已覆盖缺端处理；⑦查重覆盖关系冗余和语义覆盖\r\n- **清单相关** → 任务开始必须建清单；步0必搜同名清单检查完整标识；步5必查其他清单\r\n- **全图空白/skill写一半** → ①-⑤检查阶段图片保护；skill缺abstract或缺技能块\r\n- **关系笔记前部冗余** → frontmatter 只能 `tags: [关系]`，禁止 `created`/`source`/标题行(⑥关联处理校验)\r\n- **⚠️ 未加载skill直接操作** → 用户消息以 `kg` 开头必须先加载本 skill，再走清单强制建单。跳过会丢失格式校验和流程控制\r\n- **⚠️ 跳过清单直接动手** → 每条命令第一动作就是建清单。不建清单不允许任何文件操作\r\n- **⚠️ 分析阶段动手修改** → `kg 检查` 的分析阶段只读不写。read_file 后产生\"这里要改\"的冲动是正常的，但必须先列变更清单→问用户→等确认→再动手。分析阶段的假设是\"没有写操作\"\r\n- **⚠️ 执行中修改清单** → 清单生成后禁止追加/删除步骤。发现新问题记下来→执行完当前→删清单→建新清单处理\r\n- **⚠️ patch 跨 YAML 边界** → old_text 禁止跨 `---` 编辑。frontmatter 和正文分开 patch。每次 patch 后 read_file 验证 frontmatter 闭合和结构完整\r\n- **⚠️ 字段名写错 `tag:` 而非 `tags:`** → 库里有多个笔记误写 `tag:`（缺 s）。yaml-validator 会报 TAG_VS_TAGS 错误。修 frontmatter 时注意该字段是 `tags:` 不是 `tag:`\r\n- **⚠️ 脚本输出≠文件保存** → 在终端跑 checklist-generator.py 只打印到 stdout，文件未必写入 _working/。必须设 OBSIDIAN_VAULT 环境变量或手动保存。执行后立即 `search_files` 验证文件存在\r\n","topics":["笔记"],"tags":{"latest":"3.23.0","kg-notes":"1.5.0","knowledge-graph":"1.5.0","note-organization":"1.5.0","obsidian":"1.5.0"},"stats":{"comments":0,"downloads":1085,"installsAllTime":40,"installsCurrent":1,"stars":1,"versions":62},"createdAt":1777893969253,"updatedAt":1778492846193},"latestVersion":{"version":"3.23.0","createdAt":1778326970060,"changelog":"回退v3.22.0: 撤销'分支模式'和'直接跳到执行阶段'改动, 回到v3.21.0状态","license":"MIT-0"},"metadata":{"setup":[],"os":null,"systems":null},"owner":{"handle":"realpda","userId":"s17aspeya65fa14fe9v237r5qd863x8n","displayName":"RealGhost","image":"https://avatars.githubusercontent.com/u/60616432?v=4"},"moderation":null}