first commit
This commit is contained in:
233
文档润色流和知识库构建流/claude-scholar/OBSIDIAN_SETUP.md
Normal file
233
文档润色流和知识库构建流/claude-scholar/OBSIDIAN_SETUP.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Obsidian Project Knowledge Base Setup
|
||||
|
||||
Claude Scholar ships with a built-in Obsidian research knowledge-base workflow. It does **not** require MCP or an API key.
|
||||
|
||||
## What this provides
|
||||
|
||||
Obsidian is treated as the default knowledge base for a research project, not just a paper library. A project knowledge base can store:
|
||||
|
||||
- stable project background and research questions
|
||||
- paper notes and literature syntheses
|
||||
- experiment runbooks and result summaries
|
||||
- daily research logs, scratch notes, and sync queues
|
||||
- writing assets such as drafts, slides, proposals, and rebuttal material
|
||||
- archived project knowledge that should not stay on the main working surface
|
||||
|
||||
## Requirements
|
||||
|
||||
### Required
|
||||
- A local Obsidian vault path
|
||||
- `OBSIDIAN_VAULT_PATH` set in your environment, or passed explicitly when bootstrapping a project
|
||||
|
||||
### Optional
|
||||
- Obsidian Desktop installed and open for navigation
|
||||
- `obsidian` CLI available for open/search/daily actions
|
||||
- `OBSIDIAN_VAULT_NAME` for cleaner `obsidian://` links and CLI targeting
|
||||
|
||||
## Built-in skills
|
||||
|
||||
Claude Scholar includes a project-scoped Obsidian KB workflow.
|
||||
|
||||
Most relevant for the default workflow:
|
||||
|
||||
- `obsidian-project-kb-core`
|
||||
- `obsidian-source-ingestion`
|
||||
- `obsidian-literature-workflow`
|
||||
- `obsidian-kb-artifacts`
|
||||
- `defuddle`
|
||||
|
||||
Some optional graph-oriented helpers may still exist in the repo, but the default workflow does **not** depend on `.base`, MCP, or API services. The main default graph artifact is `Maps/literature.canvas`; additional `.base` views or project/experiment canvases are explicit-only.
|
||||
|
||||
## Default behavior
|
||||
|
||||
When Claude Scholar is running inside a repository that contains `.claude/project-memory/registry.yaml`, it should treat the repository as bound to an Obsidian project knowledge base and update it by default.
|
||||
|
||||
If the repository is not yet bound, but it looks like a research project (for example it contains `.git`, `README.md`, `docs/`, `notes/`, `plan/`, `results/`, `outputs/`, `src/`, or `scripts/`), Claude Scholar should bootstrap a project knowledge base automatically.
|
||||
|
||||
## Project structure in the 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
|
||||
```
|
||||
|
||||
Key generated files commonly include:
|
||||
|
||||
- `02-Index.md`
|
||||
- `_system/registry.md`
|
||||
- `_system/schema.md`
|
||||
- `_system/lint-report.md`
|
||||
- `.claude/project-memory/{project_id}.md`
|
||||
- `Maps/literature.canvas` when literature workflow needs it
|
||||
|
||||
## Repository-local memory binding
|
||||
|
||||
Each research repo gets a local binding under:
|
||||
|
||||
```text
|
||||
.claude/project-memory/
|
||||
registry.yaml
|
||||
{project_id}.md
|
||||
```
|
||||
|
||||
- `registry.yaml` stores the repo ↔ vault binding
|
||||
- `{project_id}.md` stores the assistant-facing project memory for incremental syncs
|
||||
|
||||
## Note language
|
||||
|
||||
Generated and synced notes resolve their language with this priority:
|
||||
1. project config in `.claude/project-memory/registry.yaml`
|
||||
2. environment variable `OBSIDIAN_NOTE_LANGUAGE`
|
||||
3. default `en`
|
||||
|
||||
Note: `registry.yaml` remains a repo-local runtime binding file. The visible project source of truth stays in `_system/registry.md`.
|
||||
|
||||
Supported values:
|
||||
- `en`
|
||||
- `zh-CN`
|
||||
|
||||
Per-project example:
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": {
|
||||
"my-project": {
|
||||
"project_id": "my-project",
|
||||
"vault_root": "/path/to/vault/Research/my-project",
|
||||
"note_language": "zh-CN"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Existing English and Chinese headings remain compatible during sync, so changing the configured language does not break older notes.
|
||||
|
||||
## Main commands
|
||||
|
||||
- `/kb-init` — initialize the vault-first project KB
|
||||
- `/kb-status` — summarize the bound KB state
|
||||
- `/kb-ingest` — route new source material into canonical notes
|
||||
- `/kb-log` — update the current Daily note and related project surfaces
|
||||
- `/kb-sync` — run deterministic KB maintenance and resync project surfaces
|
||||
- `/kb-links` — repair or strengthen wikilinks among canonical notes
|
||||
- `/kb-promote` — promote durable content into canonical notes
|
||||
- `/kb-index` — rebuild `02-Index.md`
|
||||
- `/kb-lint` — run deterministic KB health checks and rewrite `_system/lint-report.md`
|
||||
- `/kb-archive` — archive, detach, purge, or rename KB objects
|
||||
- `/kb-map` — generate explicit-only artifact outputs beyond the default literature canvas
|
||||
- `/kb-literature-review` — synthesize literature from `Sources/Papers` into `Knowledge`, `Writing`, and `Maps/literature.canvas`
|
||||
|
||||
## Minimum bound-repo maintenance
|
||||
|
||||
When a repo is already bound through `.claude/project-memory/registry.yaml`, Claude Scholar should keep automatic maintenance conservative:
|
||||
|
||||
- always verify `Daily/YYYY-MM-DD.md` when the turn changes research state,
|
||||
- update `00-Hub.md` only when top-level project status actually changes,
|
||||
- update `.claude/project-memory/{project_id}.md` whenever project state changes,
|
||||
- keep `Knowledge/`, `Experiments/`, `Results/`, and `Writing/` agent-first rather than automatically rewriting them every turn.
|
||||
|
||||
## Optional Obsidian CLI installation
|
||||
|
||||
The official Obsidian CLI is built into newer desktop installers. To use `obsidian ...` commands:
|
||||
|
||||
1. Use an Obsidian desktop build that supports CLI registration.
|
||||
2. In Obsidian Desktop, open `Settings -> General -> Advanced`.
|
||||
3. Turn on **Command line interface**.
|
||||
4. Ensure `/Applications/Obsidian.app/Contents/MacOS` is on your `PATH` on macOS (for example via `~/.zprofile`).
|
||||
5. Restart your terminal, then verify:
|
||||
|
||||
```bash
|
||||
obsidian help
|
||||
obsidian search query="diffusion" limit=5
|
||||
```
|
||||
|
||||
If you see `Command line interface is not enabled`, the shell path is fine but the Obsidian in-app toggle is still off.
|
||||
|
||||
## Lifecycle actions
|
||||
|
||||
### Detach
|
||||
- stop automatic syncing
|
||||
- keep vault content
|
||||
- keep project memory file
|
||||
|
||||
### Archive
|
||||
- **note archive** moves a canonical note into `Research/{project-slug}/Archive/`
|
||||
- **project archive** moves the whole project into `Research/_archived/{project-slug}-{date}/`
|
||||
- archive keeps history and disables syncing for project-level archive
|
||||
|
||||
### Purge
|
||||
- permanently delete the binding, project memory, and vault project folder
|
||||
- only use when the user explicitly asks for permanent deletion
|
||||
|
||||
## Optional CLI and URI usage
|
||||
|
||||
Claude Scholar can optionally use the official Obsidian CLI and URI scheme:
|
||||
|
||||
- CLI docs: <https://help.obsidian.md/cli>
|
||||
- URI docs: <https://help.obsidian.md/uri>
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
obsidian help
|
||||
obsidian search query="diffusion" limit=10
|
||||
obsidian daily:append content="- [ ] Follow up on experiment"
|
||||
```
|
||||
|
||||
```text
|
||||
obsidian://open?vault=My%20Vault&file=Research%2Fproject-slug%2F00-Hub
|
||||
obsidian://search?vault=My%20Vault&query=%23experiment
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Bootstrap fails with missing vault path | Set `OBSIDIAN_VAULT_PATH` or pass a vault path explicitly |
|
||||
| Project keeps re-importing | Check `.claude/project-memory/registry.yaml` exists and points to the correct repo root |
|
||||
| The vault still shows older topologies | Those are from older docs or older project generations; the current default workflow uses the structure above and only keeps `Maps/literature.canvas` by default |
|
||||
| CLI commands fail | Check that `Settings -> General -> Advanced -> Command line interface` is enabled; otherwise continue with filesystem-only sync |
|
||||
| “Remove project knowledge” is too destructive | Use archive or detach; purge is only for permanent deletion |
|
||||
|
||||
## WSL -> Windows mirror workflow
|
||||
|
||||
If you run Claude Scholar inside WSL but prefer opening Obsidian through native Windows for more stable window behavior, use a two-copy setup:
|
||||
|
||||
- keep the WSL vault as the source of truth (for example `<repo-root>/obsidian-vault`)
|
||||
- keep a Windows-local mirror directory mounted in WSL (for example `<wsl-mounted-windows-vault-path>`)
|
||||
- open the mirrored Windows-local directory in Windows Obsidian
|
||||
|
||||
Sync with:
|
||||
|
||||
```bash
|
||||
bash scripts/sync_obsidian_to_windows.sh --windows-path <wsl-mounted-windows-vault-path>
|
||||
```
|
||||
|
||||
Preview first if needed:
|
||||
|
||||
```bash
|
||||
bash scripts/sync_obsidian_to_windows.sh --windows-path <wsl-mounted-windows-vault-path> --dry-run
|
||||
```
|
||||
|
||||
By default the sync deletes mirror-only files that no longer exist in the WSL source. Add `--no-delete` if you want to keep extra files in the Windows mirror.
|
||||
Reference in New Issue
Block a user