183 lines
6.3 KiB
Markdown
183 lines
6.3 KiB
Markdown
# 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 仅用于永久删除 |
|