编程 claude-obsidian：本地优先的 Agent 知识库技能集

2026-09-03 07:31:12

claude-obsidian：本地优先的 Agent 知识库技能集

claude-obsidian 是面向 Claude Code 及兼容 Agent Skills 主机的一个本地优先知识系统。它把源材料转换为带引用的 Obsidian 链接页面，基于库内证据回答问题，并提供研究、检索、维护、可视化映射的显式工作流。它针对 AI 笔记工具的两个常见缺口：用户是否真正拥有数据、答案能否回溯到原材料。

架构上产品代码与用户知识库分离。写入采用可恢复事务模型：读取目标 SHA-256，由并行 Worker 生成草稿，合并为操作包，检查后原子应用；配合进程级 Vault 锁、日志备份和原子替换，避免并发写入造成静默覆盖。检索侧使用内容寻址存储与 BM25。内置 15 个技能模块（Build、Extend、Reference），支持 Generic、LYT、PARA、Zettelkasten 四种笔记方法论。

核心特性

本地数据主权

知识库由普通 Markdown 与 JSON 目录构成，不依赖云数据库或插件缓存；所有网络出口访问均需显式授权。

可恢复事务写入

并行 Agent 只生成草稿，由单一编排器执行原子应用，失败时完整回滚。这可以避免多 Agent 环境下的竞态条件和数据损坏。

证据溯源与接地

笔记内容关联不可变的源副本，保留支持度、矛盾点、置信度元数据。没有源材料支撑的引用会被拒绝，知识可回溯到原始材料。

技能集

包含 15 个技能模块，覆盖摄取、查询、Lint 检查、Canvas 创建、Web 研究等操作。所有模块共享同一套证据模型和变更规则，保证行为一致。

笔记方法论

内置 Generic、LYT、PARA、Zettelkasten 四种归档模式。切换模式只影响新笔记的路由策略，不会重排既有知识结构。

使用场景

AI 辅助深度研究：将论文、网页等源材料放入 inbox/，系统生成带引用的链接笔记，构建可复用、可验证的知识图谱。
知识库健康维护：wiki-lint 检测死链、孤儿笔记、元数据缺失及过期索引，持续保持 Vault 结构整洁。
基于证据的问答：wiki-query 只检索库内已有证据，针对 unsupported claims 保留可见标记，不强行补全答案。
结构化知识整理：结合 wiki-fold 与 canvas 技能生成操作日志摘要或可视化知识地图，适配不同复盘与思维框架。
多 Agent 协作编辑：在 Codex、OpenCode 等环境中运行多个 Agent 实例，事务机制确保并发写入不冲突、结果不丢失。

安装步骤

克隆仓库：

git clone https://github.com/AgriciDaniel/claude-obsidian.git
cd claude-obsidian

准备初始化参数：

export GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
export OPERATION_ID="init-reviewed"

预览初始化计划：

python3 scripts/claude-obsidian.py init "$HOME/Documents/MyKnowledgeVault" --generated-at "$GENERATED_AT" --operation-id "$OPERATION_ID"

确认计划并应用：复制输出中的 approved_plan_sha256，再次运行 init 命令，附加 --approved-plan-sha256 "" --apply。

启动 Claude Code 并加载插件：

cd "$HOME/Documents/MyKnowledgeVault"
claude --plugin-dir /absolute/path/to/claude-obsidian

使用示例

加载插件后，先调用技能入口：

/claude-obsidian:wiki

将源材料放入 inbox/，然后摄取：

/claude-obsidian:wiki-ingest

保存回答，或基于库内知识提问：

/claude-obsidian:save
/claude-obsidian:wiki-query

使用环境

Python 3.11+
Bash
Obsidian 可选，纯 Markdown 也可用
Git 仅在开发、发布、检查点时需要
原生 Windows 仅支持只读检查，写入操作需在 WSL 中进行