用 LLM 维护 Obsidian…

当你需要搭建或维护一个由 LLM 持续编译、可累积的 Obsidian 知识库（原始资料 → wiki → schema 三层架构）时，用这套模式来组织分类、项目、模板、溯源标记、置信度与检索策略。

适用场景

解决思路

1. 按三层架构组织：Layer 1 原始资料（不可变，放在 OBSIDIAN_SOURCES_DIR，图片也算一等来源，需视觉模型读取，无视觉模型则跳过并报告）；Layer 2 wiki（LLM 维护的 Obsidian markdown，位于 OBSIDIAN_VAULT_PATH，含 YAML frontmatter、[[wikilinks]]、可溯源）；Layer 3 schema（本技能 + 配置，规定分类、约定、模板与工作流）。注意区分 vault 内的 _raw/ 暂存收件箱与 Layer 1 原始资料。
2. 用两级结构组织 vault：categories（知识类型）与 projects（知识来源）。默认分类为 concepts/、entities/、skills/、references/、synthesis/、journal/。项目专属知识放 projects/<project-name>/<category>/，通用知识放全局分类目录，两者互相 [[wikilink]] 交叉引用。
3. 项目概览文件必须命名为 <project-name>.md（不要用 _project.md），否则 Obsidian 图谱视图会把所有项目都显示为 _project。概览页含 frontmatter（title/category/tags/source_path/created/updated）以及 Key Concepts、Related 等小节。
4. 维护三个根级特殊文件：index.md（按分类的内容目录，每条一行摘要 + 标签，每次 ingest 后重建；标签格式必须在左括号后加空格，如 ( #tag)，否则标签解析失败）；log.md（按时间追加的操作记录，条目可解析，如 INGEST/QUERY/LINT/ARCHIVE/REBUILD）；.manifest.json（记录每个已 ingest 源文件的路径、时间戳、产出的 wiki 页面，支撑 delta 计算、append 模式、审计与陈旧检测）。
5. 遵守 source key 契约 v2：源键必须机器可移植，绝不存裸绝对路径。vault 内用 vault 相对路径（POSIX 分隔符、无前导 ./、无 ..）；$HOME 下用 ~ 开头的 home 相对路径；非文件用伪键（scheme: 或 ://，如 repo:、url:、agent:）。比较前先归一化（展开 ~ 与环境变量、相对 vault 根解析、伪键视为不透明）。项目身份用 source_repo（host/owner/name）而非机器路径，机器相关检出位置放可选的 source_cwd_hint（~ 相对）。旧 manifest 可用 scripts/manifest.py migrate <vault> --dry-run 迁移；vault 跨机器移动时用 --from-root <old-vault-root> 指定旧根。写 manifest 条目时填充 pages_created 与 pages_updated 为 vault 相对页面路径。
6. 创建新页面时使用标准 Page Template：frontmatter 含 title、category、tags、aliases、relationships、sources、summary（≤200 字符）、provenance、base_confidence、lifecycle、lifecycle_changed、tier、created、updated；正文含一段摘要、Key Ideas、Open Questions、Sources。自由文本 frontmatter 值（至少 title 与 summary）用折叠标量语法 >-，避免 : 、# 或引号破坏 YAML 解析。
7. 学术论文（ML/AI/LLM/VLM 等）落入 references/ 时改用 Paper Deep-Dive Template：含 tldr callout、Problem & Motivation、Method/Architecture（嵌入论文真实架构图，无法提取时才用 Mermaid 回退）、Key Equations（用 $$…$$ 显示数学）、Results（表格 + 关键结果图）、Limitations、Related、Sources（可点击规范链接）。Mermaid 重建图若含非平凡解读应标 ^[inferred]。
8. 用三种溯源标记标注每条声明：Extracted（默认，无标记，源中确有此说）、Inferred（^[inferred] 后缀，LLM 合成）、Ambiguous（^[ambiguous] 后缀，源冲突或不清）。可选在 frontmatter 的 provenance 块给出粗略比例（extracted/inferred/ambiguous），由 ingest 写入、wiki-lint 重算并标记漂移。
9. 用可选的 relationships: frontmatter 块添加有类型的、有方向的边：每条含 target（wikilink）与 type（extends/implements/contradicts/derived_from/uses/replaces/related_to）。规则：可省略；不重复已有内联 wikilink；方向以声明页为源；不臆造，不确定时用 related_to 或省略。
10. 为每页维护两个正交信任信号：base_confidence（[0,1]，时间无关的质量估计）与 lifecycle（draft/reviewed/verified/disputed/archived），以及可选的 lifecycle_reason 与 superseded_by（仅 lifecycle=archived 时）。
11. 按公式计算 base_confidence = lineage_count_score * 0.5 + source_quality_score * 0.5，其中 lineage_count_score = min(独立证据谱系 / 3, 1.0)，source_quality_score = 各独立谱系质量分的平均。源质量分桶：paper 1.0、official 0.9、documentation 0.85、book 0.8、repository 0.75、blog 0.55、session_transcript 0.5、forum 0.4、unknown 0.4、llm_generated 0.3。计数前先合并依赖证据（同仓库的 files/releases/commits 算一个谱系；同一工作流的重试/评审/修复算一个任务谱系；父子 Kanban 记录算一个；跨 profile 字节相同的记忆算一个；快照与其可变源算一个；别名或元数据指向同一来源算一个）。计算后评估证据是否覆盖页面实质声明，覆盖不全可保持或降低分数，无支撑的实质声明须先修复来源/声明再改置信度，避免无实质认知变化的小幅抖动。
12. 遵守 lifecycle 状态机：draft 由任何 ingest 技能首次写入时设置；reviewed/verified/disputed 仅由人工编辑设置；archived 由人工编辑或 ingest 设置 superseded_by 进入，为终态。stale 不是状态而是计算叠加：is_stale = (today − updated) > 90 天。状态变化时更新 lifecycle_changed。非法转换（回退到 draft、从 archived 退出）由 obsidian-wiki lint 报告为 illegal_lifecycle_transitions。
13. 用 tier 字段做重要性分层：core（承重页，入链多或桥接位置，源只要略相关就更新，查询优先）、supporting（默认）、peripheral（低连接，除非源主要讲该主题否则跳过，查询最后考虑）。新页默认 supporting；入链 ≥5 或被 wiki-status insights 标为桥接则升 core；入链 ≤1 且 90+ 天未更新则降 peripheral；人工手动编辑 tier 永远优先。无 tier 的旧页视为 supporting。
14. 按检索原语表用最便宜的读取方式并仅在不足时升级：判断页面是否存在/标题/分类/标签 → 读 index.md 或 Grep frontmatter 块（最便宜）；1–2 句预览 → 读 frontmatter 的 summary:（便宜）；页内特定声明或小节 → Grep -A <n> -B <n> "<term>" <file>（中等）；整页内容 → Read <file>（昂贵，最后手段）；跨页关系 → Grep "\[\[.*?\]\]" 或从已知页走 wikilink。shell/文件搜索优先用 ripgrep（rg、rg --files），不可用再退回 grep/find。
15. QMD 索引新鲜度：QMD 是可选搜索索引，markdown vault 是唯一真相源。写 wiki markdown 的技能应在写入完成后刷新 QMD，但仅当配置了 QMD_WIKI_COLLECTION 且本地 QMD 传输可用；刷新失败则保留 vault 变更并单独报告 QMD 状态。用最便宜的验证路径证明新内容可见：qmd update，仅当向量陈旧或缺失时 qmd embed，然后对某个写入页或集合根做定向 qmd get 或 qmd ls 检查。只读技能不应刷新 QMD。
16. 遵循六条核心原则：1) Compile, don't retrieve——ingest 时更新所有相关页而非只写摘要；2) Compound over time——每次 ingest 让 wiki 更聪明而非更大，合并新信息、解决矛盾、强化交叉引用；3) Provenance matters——每条声明可溯源，更新时注明触发源；4) Mark inferences——默认 extracted，合成标 ^[inferred]，争议标 ^[ambiguous]；5) Human curates, LLM maintains——人决定加什么源、问什么问题，LLM 负责记账；6) Obsidian is the IDE——一切必须是合法 Obsidian markdown 且 wikilink 可用。
17. 按 OBSIDIAN_LINK_FORMAT 生成内部链接：wikilink（默认）用 [[path/to/page]] 或 [[path/to/page|display text]]；markdown 用 [display text](relative/path.md)，从当前文件目录计算到目标 .md 的相对路径（用 .. 上溯），始终带 .md 扩展名。该设置只影响新写或更新的链接，不自动迁移旧内容。
18. 按 Config Resolution Protocol 解析配置，不要硬编码 .env 或全局配置路径：全局配置目录用 XDG 风格 $XDG_CONFIG_HOME/obsidian-wiki（默认 ~/.config/obsidian-wiki），已有 ~/.obsidian-wiki 的旧安装继续沿用。解析顺序：0) 请求中的 @<name> 内联覆盖（解析 <global config dir>/config.<name>，仅本次调用生效，绝不改活动符号链接；不存在则报告并列出可用 vault，不静默回退；@name 是路由指令，处理前先剥离）；1) 从 CWD 向上查找含 OBSIDIAN_VAULT_PATH 的 .env 直到 $HOME；2) 全局配置；3) 都没有则提示运行 wiki-setup。@name 是单次覆盖，/wiki-switch <name> 是持久默认。
19. 写入运行时状态的技能须把状态按解析出的 vault 作用域化：VAULT_ID=$(echo "$OBSIDIAN_VAULT_PATH" | md5sum 2>/dev/null || md5 -q - <<< "$OBSIDIAN_VAULT_PATH" | cut -c1-8)，STATE_DIR="$(obsidian_wiki_config_dir)/state/$VAULT_ID"。
20. 起草或重写自然语言 Markdown 前，先按 XDG/legacy 算法解析全局配置目录，再读取 <global config dir>/WRITING.md（存在时）。缺失或为空表示无自定义写作偏好；读取失败则警告并继续用框架默认。优先级：框架不变量 > 当前任务/技能要求 > 当前项目 AGENTS.md > vault AGENTS.md > 全局 WRITING.md。写作偏好只作用于新起草或重写的自然语言字段与正文（含 frontmatter 中自然语言的 title 与 summary），不得改变 YAML 语法、必需键、结构、类型或机器生成字段；JSON、结构化日志与透传内容保持不变。
21. 通过环境变量配置：唯一必需的是 OBSIDIAN_VAULT_PATH，其余有合理默认。其他包括 OBSIDIAN_SOURCES_DIR、OBSIDIAN_CATEGORIES、WIKI_SKIP_PROJECTS、CLAUDE_HISTORY_PATH、CODEX_HISTORY_PATH、HERMES_HOME、OPENCLAW_HOME、COPILOT_HISTORY_PATH、OBSIDIAN_LINK_FORMAT、WIKI_TOKEN_WARN_THRESHOLD（默认 100000，0 禁用）、WIKI_STAGED_WRITES（true 时 LLM 写的页面进 _staging/<category>/ 待人工审核）、CODE_UNDERSTANDING_BACKEND（auto/builtin/codegraph）、CODE_UNDERSTANDING_CODEGRAPH_BIN、OBSIDIAN_MAX_PAGES_PER_INGEST（默认 15）、LINT_SCHEDULE（daily/weekly/manual）。无需 API key。
22. 按三种 ingest 模式操作：Append（小 delta、增量更新，经 manifest 算 delta 只处理新增/修改源）、Rebuild（重大漂移或重来，把当前 wiki 归档到 _archives/、清空、重处理所有源）、Restore（恢复先前归档）。用 wiki-status 查看 delta 与建议，用 wiki-rebuild 做归档/重建/恢复。

适用边界 · 注意事项

• 不适用于非 Obsidian 或非 markdown 的知识管理场景（本模式依赖 Obsidian 的 wikilink、frontmatter、图谱视图等特性）。
• 不适用于一次性、无需累积的问答或摘要任务（本模式的核心是持久、可累积、可溯源的编译产物）。
• 图片来源的 ingest 需要具备视觉能力的模型；无视觉模型时应跳过图片源并报告，而非强行处理。