Totoro-qaq/Cobsidian

Cobsidian

English · 简体中文

安全地把 AI 对话整理成带双链的 Obsidian 知识库。

Cobsidian 是一个不绑定 Agent 的 Obsidian / Markdown 知识库维护工作流 Skill。它先搜索再新建，预览准备执行的改动，只让你做一次自然语言确认，然后原子写入并校验结果。完整性哈希留在执行层，用户不需要复制确认码。

它不是托管服务，也不是 Obsidian 插件。你的编程 Agent 会在本机的 Markdown 文件夹上执行这套工作流。

快速开始 · 工作原理 · 安装 · DeepSeek Harness · MCP Server · 兼容性 · 最新版本

用你熟悉的 Agent 就行：Claude Code · Codex CLI · GitHub Copilot CLI · Kimi Code · OpenCode · Pi · Antigravity

演示使用合成知识库，不包含私人笔记、路径或凭据。

快速开始

先在自带的演示知识库上执行一次只读 dry run：

git clone https://github.com/Totoro-qaq/Cobsidian.git
cd Cobsidian
python skills/cobsidian/scripts/dry_run.py examples/demo-vault --topic "AI Conversations" --mode learning --text "agent workflow notes" --json

然后让 Agent 读取 skills/cobsidian/SKILL.md：

Use Cobsidian to organize this material into my Obsidian vault.
Vault: /absolute/path/to/obsidian-vault
Run a dry run first, check duplicates, suggest backlinks, and wait for confirmation before writing.

Cobsidian 做什么

| 阶段 | Cobsidian 会明确展示什么 |
| --- | --- |
| 读取 | 解析知识库，并从文件名、H1、title 与 aliases 建立笔记身份。 |
| 决策 | 把 create | append | blocked 与笔记形态分开报告。 |
| 审阅 | 返回重复风险、反链建议和精确的补丁计划。 |
| 确认 | 只询问“应用这项已审阅的变更吗？”，对应的 plan ID 留在后台。 |
| 写入 | 后台核验计划与文件哈希，原子写入、校验，并保留回滚能力。 |

最终产物是带有实用 [[双链]] 的长期 Markdown，而不是已有笔记的第二份副本。

前后对比

flowchart LR
A["AI 对话、日志、项目材料"] --> B["Cobsidian dry run"]
B --> C["搜索知识库中的已有笔记"]
C --> D{"Machine actioncreate | append | blocked"}
D --> E["Note plansingle-note | multi-note | report-onlysplit = multi-note"]
E --> F["补丁预览 + 自然确认"]
F --> G["原子写入 + 校验"]
G --> H["可回滚事务"]

| 整理前 | 整理后 |
| --- | --- |
| 有价值的回答沉在聊天记录里 | 可复用笔记留在知识库中 |
| 重复提问不断生成相似笔记 | 写入前先匹配已有身份 |
| 边写边猜应该加什么链接 | 从真实知识库笔记中建议反链 |
| Agent 改动难以审计 | 每次写入前都有已审阅且完整性绑定的计划 |

工作原理

搜索 → dry run → 审阅差异 → 确认写入 → 原子应用 → 校验

确认过程刻意保持自然：应用这项已审阅的变更吗？ 你确认后，Host 会把该预览对应的精确 plan ID 在后台传给确定性写入器。ID、目标指纹和写入前后的 SHA-256 只作为完整性检查。

- 你不需要阅读、复制或输入任何哈希。
- 一次确认只对应刚刚展示的那一项变更。
- 如果目标笔记或拟写内容发生变化，旧确认立即失效，Cobsidian 会重新预览并再次询问。
- 如果同时存在多个待审计划，Cobsidian 会用目标与摘要让你选择，不会猜测你指的是哪串哈希。

Dry-run 预览

Dry run 是默认的安全路径：报告决策，同时保持 writes 为空。

{
"dry_run": true,
"mode": "learning",
"decision": {
"action": "append",
"target_note": "AI Conversations.md"
},
"suggested_backlinks": [
{
"title": "Agent Workflows",
"path": "Agent Workflows.md"
}
],
"writes": []
}

不是普通 Markdown 生成器

| 普通 Markdown 生成 | Cobsidian |
| --- | --- |
| 产出一个孤立文件 | 维护相互连接的知识系统 |
| 忽略已有笔记 | 写入前扫描知识库 |
| 混在一起判断动作和文档形态 | 分开报告 machine action 与 note plan |
| 立即写入 | 规划、确认、写入、校验，并可回滚 |

Knowledge Read / 整理判读

写入前，Cobsidian 会计算 Knowledge Read：模式、深度、笔记粒度、证据与展示方式。auto | always | off 只控制对话中的展示；设为 off 时 display_style 会隐藏，但 dry-run 仍保留完整 JSON。

Capability-based degradation 会让结果忠实于真实能力：本地主机通过检查后可以进入 ready，MCP 保持只读，chat-only 主机只能返回草稿或请求可用路径，不会声称已经完成无法执行的工作。详细规则见 mode 和 host references与共享的 preflight contract。

Compact Knowledge Read

{
"mode": "learning",
"mode_explicit": true,
"recommended_modes": [],
"depth": "standard",
"granularity": "single-note",
"evidence": "conversation",
"display_policy": "auto",
"display_style": "compact"
}

Expanded Knowledge Read

{
"mode": "dissection",
"mode_explicit": false,
"recommended_modes": [],
"depth": "deep",
"granularity": "multi-note",
"evidence": "source-grounded",
"display_policy": "auto",
"display_style": "expanded"
}

Obsidian Vault 工作流

flowchart TD
U["用户材料"] --> R["解析知识库路径或配置"]
R --> S["建立身份并扫描知识库"]
S --> A{"Machine actioncreate | append | blocked"}
A --> P["Note plansingle-note | multi-note | report-onlysplit = multi-note"]
P --> L["建议反链"]
L --> X["预览补丁 + 确认已审阅变更"]
X --> V["原子写入、校验、出现新告警时回滚"]
V --> O["报告事务、链接与校验结果"]

安装

需要 Git、Python 3.10+、一个 Markdown 知识库，以及能够读取本地说明和运行命令的编程 Agent。

先预览安装位置，再为支持的 CLI 安装 Skill：

python install_cobsidian.py --host all --scope user --dry-run --json
python install_cobsidian.py --host all --scope user

也可以手动复制到共享 Skill 目录：

mkdir -p ~/.agents/skills
cp -r skills/cobsidian ~/.agents/skills/cobsidian

Windows、项目级安装、软链接、更新与卸载见 INSTALL.md；不同主机的发现路径见 Integrations。

DeepSeek Harness Cordis Bundle

Cobsidian 仍然是 Agent Skill。可选的 DSH Cordis Bundle 把同一份 canonical Skill 与 Python backend 封装成 DeepSeek Harness 原生扩展，增加 typed tools 和一次性批准，不改变现有 Skill、CLI 或 MCP 路径。

cd integrations/dsh
npm install
npm run build
dsh plugin --profile web add .

export COBSIDIAN_VAULT="/absolute/path/to/obsidian-vault"
dsh web

原生工作流把 scan、dry-run、prepare、apply 和 rollback 分成独立工具。DSH 展示一次性批准界面，并在后台携带精确的 plan / transaction ID；用户不需要粘贴哈希。私人笔记内容通过权限受限的临时文件传给 Python，不进入命令行参数；plan 默认保存在 ~/.dsh/cobsidian，不保存 API key 或 token。

Bundle 当前针对 DSH 0.1.0-rc.6 API 系列，因为 DeepSeek Harness 仍处于 developer preview。配置、使用与验证步骤见 Bundle 指南。

MCP Server

支持 Model Context Protocol 的主机可以把 Cobsidian 作为本地只读 stdio server 运行：

python -m pip install -r requirements-mcp.txt
python skills/cobsidian/mcp_server.py

配置 COBSIDIAN_CONFIG 或 COBSIDIAN_VAULT；详见 MCP Server。

Agent 用法

告诉 Agent 使用什么工作流、操作哪个知识库，以及安全边界：

Use Cobsidian to turn this conversation into an Obsidian learning note.
Check whether it should create a new note or append to an existing one.
Add useful wiki links, report possible duplicates, and wait before writing.

更多可直接复制的写法见 Prompt Examples。

模式

Cobsidian 接受显式模式，也能按自然语言路由。意图清晰时只推断一个模式；有歧义时最多推荐两个相关模式。参见模式说明和详细的 mode references。

CLI 工具

确定性工具覆盖知识库扫描、重复检测、反链建议、校验、dry run、事务准备、精确计划应用与质量评估：

python skills/cobsidian/scripts/scan_vault.py /path/to/vault --json
python skills/cobsidian/scripts/find_duplicates.py /path/to/vault
python skills/cobsidian/scripts/suggest_backlinks.py /path/to/vault --file draft.md
python skills/cobsidian/scripts/validate_notes.py /path/to/vault
python skills/cobsidian/scripts/write_executor.py prepare /path/to/vault --action append --target-note "RAG.md" --content-file draft.md --plan-out /tmp/cobsidian-plan.json
python skills/cobsidian/scripts/write_executor.py apply /path/to/vault --plan /tmp/cobsidian-plan.json --confirm PLAN_ID --json

可选配置

cobsidian.config.example.yml 是当前支持的配置面，包含知识库路径、模式目录、Knowledge Read 展示、反链数量、重复阈值、追加偏好与校验行为。

interaction:
knowledge_read: auto

复制为 cobsidian.config.yml 后，辅助脚本可以通过 --config cobsidian.config.yml 读取。

功能

- 基于文件名、H1、title 与 aliases 的确定性身份匹配，支持去前缀核心标题。
- 用 CJK bigram / trigram 匹配中文相关短语。
- 校验缺失双链目标和相似标题。
- 通过分页的本地 MCP 工具执行检查与 dry-run 规划。
- 完整性哈希补丁、自然确认、后台精确计划绑定、原子写入与回滚。
- 公开评估重复检测、反链、追加目标与模式准确率。

路线图

- 超越标题身份的语义重复检测。
- 用更大的标注知识库基准调优反链排序。
- 可选笔记模板与可配置命名规则。
- 工作流稳定后再考虑 Obsidian 插件集成。

贡献

欢迎贡献。请先阅读 CONTRIBUTING.md，并且不要提交私人知识库内容、本机用户路径、API key、未公开笔记或个人截图。

商标和独立性声明

Cobsidian 是独立开源项目。OpenAI、Codex、Obsidian、Claude、Cursor、Hermes 以及其他名称均属于各自权利人。本项目不隶属于这些权利人，也未获得其背书或赞助。

License

MIT © 2026 Totoro。