# Obsidian 项目知识库配置指南

Claude Scholar 内置了 Obsidian 研究知识库工作流，不需要 MCP，也不需要 API key。

## 这套工作流提供什么

Obsidian 在这里不是单纯的论文库，而是研究项目的默认知识层，可以统一沉淀：

- 稳定的项目背景与研究问题
- 论文笔记与文献综合
- 实验 runbook 与结果总结
- 每日研究日志、scratch notes 与同步队列
- 草稿、slides、proposal、rebuttal 等写作资产
- 不应继续留在主工作面的历史知识

## Requirements

### Required
- 一个本地 Obsidian vault 路径
- 通过环境变量设置 `OBSIDIAN_VAULT_PATH`，或在 bootstrap 时显式传入

### Optional
- 安装并打开 Obsidian Desktop，便于跳转与查看
- 可用的 `obsidian` CLI，用于 open/search/daily 等辅助操作
- `OBSIDIAN_VAULT_NAME`，便于生成更干净的 `obsidian://` 链接和 CLI targeting

## 内置 skills

Claude Scholar 内置了面向项目作用域的 Obsidian KB 工作流。

默认主线最相关的是：

- `obsidian-project-kb-core`
- `obsidian-source-ingestion`
- `obsidian-literature-workflow`
- `obsidian-kb-artifacts`
- `defuddle`

默认工作流不依赖 `.base`、MCP 或 API 服务。默认自动维护的图谱产物只有 `Maps/literature.canvas`；其他 `.base` 视图或项目/实验 canvas 都是 explicit-only。

## 默认行为

当 Claude Scholar 运行在一个包含 `.claude/project-memory/registry.yaml` 的仓库里时，应默认把这个仓库视为已经绑定到 Obsidian 项目知识库，并在任务过程中自动维护它。

如果仓库还没有绑定，但看起来像研究项目（例如包含 `.git`、`README.md`、`docs/`、`notes/`、`plan/`、`results/`、`outputs/`、`src/` 或 `scripts/`），Claude Scholar 应自动 bootstrap 一个项目知识库。

## Vault 中的默认目录结构

```text
Research/{project-slug}/
  00-Hub.md
  01-Plan.md
  02-Index.md
  Sources/
    Papers/
    Web/
    Docs/
    Data/
    Interviews/
    Notes/
  Knowledge/
  Experiments/
  Results/
    Reports/
  Writing/
  Daily/
  Maps/
  Archive/
  _system/
    registry.md
    schema.md
    lint-report.md
```

常见生成文件包括：

- `02-Index.md`
- `_system/registry.md`
- `_system/schema.md`
- `_system/lint-report.md`
- `.claude/project-memory/{project_id}.md`
- 文献工作流需要时生成 `Maps/literature.canvas`

## Repo-local binding metadata

每个研究仓库都会在本地维护：

```text
.claude/project-memory/
  registry.yaml
  {project_id}.md
```

- `registry.yaml` 存 repo ↔ vault 的绑定关系
- `{project_id}.md` 存 assistant-facing 的运行时项目记忆

## 笔记语言

生成和同步笔记时，语言按以下优先级解析：
1. `.claude/project-memory/registry.yaml` 中的项目配置
2. 环境变量 `OBSIDIAN_NOTE_LANGUAGE`
3. 默认 `en`

注意：`registry.yaml` 仍然只是 repo-local runtime binding 文件。项目内真正可见的 source of truth 仍然是 `_system/registry.md`。

支持的值：
- `en`
- `zh-CN`

## 主命令

- `/kb-init` — 初始化 vault-first 项目知识库
- `/kb-status` — 汇总当前已绑定 KB 的状态
- `/kb-ingest` — 将新的 source material 路由到 canonical notes
- `/kb-log` — 更新当天 `Daily/` 和相关项目表面
- `/kb-sync` — 运行确定性的 KB 维护并重同步项目表面
- `/kb-links` — 修复或增强 canonical notes 之间的 wikilink
- `/kb-promote` — 将稳定内容提升为 canonical note
- `/kb-index` — 重建 `02-Index.md`
- `/kb-lint` — 运行确定性的 KB 健康检查并重写 `_system/lint-report.md`
- `/kb-archive` — 归档、detach、purge 或重命名 KB 对象
- `/kb-map` — 在默认 literature canvas 之外按需生成 artifact
- `/kb-literature-review` — 从 `Sources/Papers` 合成文献并写入 `Knowledge`、`Writing`、`Maps/literature.canvas`

## 已绑定仓库的最小维护面

当仓库已经通过 `.claude/project-memory/registry.yaml` 绑定时，Claude Scholar 应保持保守维护：

- 只要研究状态发生变化，就检查 `Daily/YYYY-MM-DD.md`
- 只有项目顶层状态真正变化时才更新 `00-Hub.md`
- 只要项目状态变化，就更新 `.claude/project-memory/{project_id}.md`
- `Knowledge/`、`Experiments/`、`Results/`、`Writing/` 默认保持 agent-first，而不是每轮都自动重写

## 可选的 Obsidian CLI 安装

官方 Obsidian CLI 是内置在较新的桌面版安装器里的。要使用 `obsidian ...` 命令：

1. 使用支持 CLI 注册的 Obsidian Desktop 版本。
2. 在 Obsidian Desktop 中打开 `Settings -> General -> Advanced`。
3. 打开 **Command line interface**。
4. 在 macOS 上确保 `/Applications/Obsidian.app/Contents/MacOS` 已加入 `PATH`（例如写入 `~/.zprofile`）。
5. 重启终端后验证：

```bash
obsidian help
obsidian search query="diffusion" limit=5
```

如果提示 `Command line interface is not enabled`，通常说明 shell 路径已经配置好，但 Obsidian 应用内的开关还没打开。

## Lifecycle actions

### Detach
- 停止自动同步
- 保留 vault 内容
- 保留 project memory 文件

### Archive
- **note archive**：把 canonical note 移到 `Research/{project-slug}/Archive/`
- **project archive**：把整个项目移到 `Research/_archived/{project-slug}-{date}/`
- archive 会保留历史记录；project archive 会同时禁用同步

### Purge
- 永久删除 binding、project memory 和 vault 中的项目目录
- 只有在用户明确要求永久删除时才使用

## 可选的 CLI 与 URI 用法

Claude Scholar 可选使用官方 Obsidian CLI 与 URI：

- CLI 文档：<https://help.obsidian.md/cli>
- URI 文档：<https://help.obsidian.md/uri>

## Troubleshooting

| 问题 | 解决方式 |
|------|----------|
| Bootstrap 缺少 vault path | 设置 `OBSIDIAN_VAULT_PATH` 或显式传入 vault path |
| 项目反复重新导入 | 检查 `.claude/project-memory/registry.yaml` 是否存在且 repo root 正确 |
| vault 里仍出现旧目录拓扑 | 那通常来自旧文档或旧项目生成；当前默认结构以上述目录为准，默认只自动维护 `Maps/literature.canvas` |
| CLI 命令失败 | 检查 `Settings -> General -> Advanced -> Command line interface` 是否已打开；否则继续使用 filesystem-only sync |
| “删除项目知识” 看起来过于危险 | 优先使用 archive 或 detach；purge 仅用于永久删除 |