gitea-admin/obsidian-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
obsidian-wiki/SETUP.md
T
Codex d3f3151218 feat(business): add schema-driven query templates 
Expose a business schema catalog and explicit template runner for Kingdee sales-order facts. Update wiki-query guidance so the LLM routes operational questions through templates first and guarded SQL only when needed. Refresh user docs and ops aliases, and add coverage for schema metadata, template execution, and CLI JSON output.

Validation: python3 -m unittest discover -v; python3 -m compileall obsidian_wiki tests scripts; git diff --check
2026-07-06 22:27:49 +00:00

207 lines
11 KiB
Markdown
Raw Permalink Blame History

# Setup
A skill-based framework for AI coding agents — Claude Code, Cursor, Windsurf, Pi, Gemini CLI, Google Antigravity, Codex, Hermes, OpenClaw, OpenCode, Aider, Factory Droid, Trae / Trae CN, Kiro, GitHub Copilot (CLI + VS Code Chat) — to build and maintain an Obsidian wiki using Karpathy's LLM Wiki pattern. No scripts, no API keys — the agent **is** the LLM.
> Running `bash setup.sh` wires up every supported agent: project-local skill symlinks (`.claude/skills/`, `.cursor/skills/`, `.windsurf/skills/`, `.agents/skills/`, `.kiro/skills/`), global symlinks (`~/.claude/skills/`, `~/.gemini/skills/`, `~/.codex/skills/`, `~/.hermes/skills/`, `~/.openclaw/skills/`, `~/.copilot/skills/`, `~/.trae/skills/`, `~/.trae-cn/skills/`, `~/.kiro/skills/`, `~/.agents/skills/`), and always-on rule files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, `.hermes.md`, `.cursor/rules/…`, `.windsurf/rules/…`, `.kiro/steering/…`, `.agent/rules/…`, `.agent/workflows/…`, `.github/copilot-instructions.md`). See the [Agent Compatibility table in README.md](README.md#agent-compatibility) for the full matrix.
## Install via pip (no clone needed)
```bash
pip install obsidian-wiki
obsidian-wiki setup --vault /path/to/your/vault
```
This does everything `setup.sh` does without a clone: writes `~/.obsidian-wiki/config` and installs every skill into all supported agents' skills directories (symlinked to the installed package, so `pip install -U obsidian-wiki` upgrades them everywhere). Add `--project .` to also drop project-local skills and the `AGENTS.md` / rule files into the current repo, or `--copy` to copy skill files instead of symlinking. Run `obsidian-wiki info` to see resolved paths.
The rest of this doc covers the `git clone` + `setup.sh` path.
## Quick Start (git clone)
### 1. Set your vault path
```bash
cp .env.example .env
```
Open `.env` and set `OBSIDIAN_VAULT_PATH` to your Obsidian vault:
```
OBSIDIAN_VAULT_PATH=/path/to/your/vault
```
That's the only required config.
### 2. Point an agent at the skills
Open this project in your coding agent and tell it what you want:
| What you say | Skill triggered |
|---|---|
| "Set up my wiki" | `wiki-setup` |
| "Ingest my documents from ~/research" | `wiki-ingest` |
| "/wiki-history-ingest claude" or "/wiki-history-ingest codex" | `wiki-history-ingest` |
| "Import my Claude history" | `claude-history-ingest` |
| "Import my Codex history" | `codex-history-ingest` |
| "Import my Pi history" | `pi-history-ingest` |
| "Process this ChatGPT export" | `data-ingest` |
| "What's the status of my wiki?" | `wiki-status` |
| "What do I know about X?" | `wiki-query` |
| "Audit my wiki" | `wiki-lint` |
| "Rebuild from scratch" | `wiki-rebuild` |
The agent reads the skills from `.skills/`, reads `.env` for your vault path, and does the work.
### 3. Open in Obsidian
Open your vault directory in Obsidian (File → Open Vault). The wiki pages, wikilinks, and graph view all work natively.
## What Can It Ingest?
Anything text-based:
| Source | Skill | What it reads |
|---|---|---|
| Markdown, PDFs, text files | `wiki-ingest` | Any document directory |
| Claude Code history | `claude-history-ingest` | `~/.claude/` — conversations, memories, sessions |
| Codex CLI history | `codex-history-ingest` | `~/.codex/` — sessions, rollouts, history index |
| Pi agent sessions | `pi-history-ingest` | `~/.pi/agent/sessions/` — tree-structured JSONL |
| ChatGPT exports | `data-ingest` | `conversations.json` from ChatGPT export |
| Slack / Discord logs | `data-ingest` | Channel export JSON files |
| Meeting transcripts | `data-ingest` | Any text transcript |
| Raw text dumps | `data-ingest` | Anything — CSV, logs, journals, notes |
## Tracking & Delta
The framework tracks everything it ingests via `.manifest.json` in the vault root. This enables:
- **Status view** — "What's been ingested? What's new? What's changed?"
- **Delta ingestion** — Only process new/modified sources, skip what's already in the wiki
- **Provenance** — Which source produced which wiki page
- **Staleness detection** — Source changed but wiki page hasn't been updated
### Typical workflow
```
"What's the status?" → wiki-status computes the delta
"Ingest the new stuff" → wiki-ingest processes only the delta (append mode)
"What's the status now?" → wiki-status confirms everything is up to date
```
### When things drift too far
```
"Archive and rebuild" → wiki-rebuild archives current wiki to _archives/, clears, ready for fresh ingest
"Restore the old one" → wiki-rebuild restores from a previous archive
```
Archives live at `$VAULT/_archives/` with full snapshots. Nothing is ever lost.
## Vault Structure
```
$OBSIDIAN_VAULT_PATH/
├── concepts/ # Global knowledge — ideas, theories, mental models
├── entities/ # People, orgs, tools
├── skills/ # How-to knowledge, procedures
├── references/ # Source summaries
├── synthesis/ # Cross-cutting analysis
├── journal/ # Timestamped logs
├── projects/ # Per-project knowledge
│ ├── my-project/
│ │ ├── _project.md
│ │ ├── concepts/
│ │ └── skills/
│ └── another-project/
│ └── ...
├── _archives/ # Wiki snapshots for rebuild/restore
├── index.md # Auto-maintained catalog
├── log.md # Chronological operation log
└── .manifest.json # Ingest tracking ledger
```
Knowledge that's project-specific goes under `projects/<name>/`. Knowledge that's general goes in the global category directories. Both are cross-referenced with `[[wikilinks]]`.
## Optional Config
| Variable | What it does | Default |
|---|---|---|
| `OBSIDIAN_SOURCES_DIR` | Directories with docs to ingest (comma-separated) | *(empty — point agent at specific files)* |
| `OBSIDIAN_BUSINESS_FACTS_DB` | Optional path for structured business facts such as Kingdee orders | `<vault>/_meta/business-facts.sqlite` |
| `.runtime/kingdee.env` | Private local Kingdee sales-order API config created by `scripts/obsidian-wiki-ops.py kingdee config` | official sales-order URL, blank credentials |
| `OBSIDIAN_CATEGORIES` | Wiki page categories | `concepts,entities,skills,references,synthesis,journal` |
| `OBSIDIAN_MAX_PAGES_PER_INGEST` | Max pages updated per ingest | `15` |
| `CLAUDE_HISTORY_PATH` | Where to find Claude data | *auto-discovers from `~/.claude`* |
| `CODEX_HISTORY_PATH` | Where to find Codex data | *defaults to `~/.codex`* |
| `PI_HISTORY_PATH` | Where to find Pi sessions | *defaults to `~/.pi/agent/sessions`* |
| `LINT_SCHEDULE` | Wiki health check frequency | `weekly` |
## Skills Reference
| Skill | Purpose |
|---|---|
| `llm-wiki` | Core pattern — 3-layer architecture, page templates, project org |
| `wiki-setup` | Initialize vault structure, create index/log, configure Obsidian |
| `wiki-ingest` | Distill source documents into wiki pages (append or full mode) |
| `wiki-history-ingest` | Unified history ingest router (`claude`, `codex`, `pi`) |
| `data-ingest` | Ingest any raw text — chat exports, logs, transcripts, anything |
| `claude-history-ingest` | Mine `~/.claude` conversations and memories into wiki pages |
| `codex-history-ingest` | Mine `~/.codex` sessions and rollout logs into wiki pages |
| `pi-history-ingest` | Mine `~/.pi/agent/sessions` JSONL history into wiki pages |
| `wiki-status` | Audit: what's ingested, what's pending, delta, recommend action |
| `wiki-rebuild` | Archive current wiki, rebuild from scratch, or restore from archive |
| `wiki-query` | Answer questions from the compiled wiki with citations |
| `wiki-lint` | Find orphans, broken links, stale content, contradictions |
| `wiki-update` | Sync current project's knowledge into the vault (works from any project) |
| `skill-creator` | Create new skills to extend the framework |
## Business Facts
Use the business fact database for exact operational questions, for example monthly order counts or sales amounts. Do not ingest every order line into the wiki. Ask normal questions through `wiki-query`; it will decide when to use structured business facts.
```bash
scripts/obsidian-wiki-ops.py kingdee sync --input ./kingdee-orders.json
scripts/obsidian-wiki-ops.py kingdee config
# Fill .runtime/kingdee.env, then test login/refresh without syncing orders:
scripts/obsidian-wiki-ops.py kingdee auth-test
scripts/obsidian-wiki-ops.py kingdee sync \
--start-bizdate 2026-06-01 \
--end-bizdate 2026-06-30 \
--billstatus C
scripts/obsidian-wiki-ops.py kingdee sync --incremental
scripts/obsidian-wiki-ops.py kingdee schema --json
scripts/obsidian-wiki-ops.py kingdee template order_count --vault /path/to/vault --year 2026 --month 6 --json
scripts/obsidian-wiki-ops.py kingdee template sales_amount --vault /path/to/vault --year 2026 --month 6 --json
scripts/obsidian-wiki-ops.py kingdee template staff_order_list --vault /path/to/vault --start-date 2026-06-30 --end-date 2026-07-07 --staff 徐丽 --json
scripts/obsidian-wiki-ops.py kingdee sql "SELECT COUNT(*) AS order_count FROM orders"
scripts/obsidian-wiki-ops.py timer install --vault /path/to/vault
```
Without `--input`, the Kingdee sync command creates/reads `.runtime/kingdee.env`, obtains or refreshes an access token, calls the official sales order query API, then stores the fetched JSON response in `<vault>/_meta/business-facts.sqlite`. The private config supports configurable login/token URL, request body, response field paths, refresh URL/body, and required `x-acgw-identity`; fetched tokens are cached in `.runtime/kingdee-token.json`. `.runtime/` is ignored by git.
The answer reports the statistic, counting basis, data source, and last successful sync time. If the latest successful sync is before today, the answer warns that newer data may be missing. `wiki-query` loads the business schema, chooses a template when one fits, and uses guarded read-only SQL only for gaps. Salesperson templates default to the main salesperson and use `--staff-role-scope all` to include sales 2/3/4 and follow-up roles. The Linux timer uses `systemd --user`, runs daily by default, and syncs incrementally with a 48-hour lookback.
## How It Works
No scripts, no dependencies. The skills are markdown files that tell an AI agent *how* to operate on your Obsidian vault:
1. Agent reads `.env` for vault path
2. Agent reads `.manifest.json` to know what's already been done
3. Agent reads the relevant skill for instructions
4. Agent uses its built-in tools (read, write, search) to do the work
5. Agent updates `.manifest.json` to track what it did
6. Output is standard Obsidian-compatible markdown with frontmatter and `[[wikilinks]]`
**The wiki is the artifact. The agent is the maintainer. Obsidian is the viewer.**
## Extending
Want a new workflow? Use the `skill-creator` skill:
> "Create a skill that generates weekly summaries from my journal entries"
It walks you through drafting, testing, and refining a new skill in `.skills/`.
Reference in New Issue View Git Blame Copy Permalink