dianel555/dskills/agent-wiki

agent-wiki

增量式 Obsidian 笔记仓库 Wiki 生成器，为 LLM 优化的知识库管理工具。

Prerequisites

pip install PyYAML

References (load on demand)

Detailed specs live under references/ in this skill directory — read them only when the task needs them:

Execution

The skill provides a Python CLI with the following subcommands:

# Initialize wiki structure
python scripts/agent_wiki_cli.py init --vault /path/to/vault
 
# Scan for changed sources
python scripts/agent_wiki_cli.py scan --vault /path/to/vault
 
# Plan a batched ingest: split pending sources into rounds (default 20/round)
python scripts/agent_wiki_cli.py plan --batch-size 20 --vault /path/to/vault
 
# Mark a round complete (verifies every doc in the batch was cache-put)
python scripts/agent_wiki_cli.py batch-done --batch 1 --vault /path/to/vault
 
# Get cache entry for a source
python scripts/agent_wiki_cli.py cache-get <relative-path> --vault /path/to/vault
 
# Record ingest result
python scripts/agent_wiki_cli.py cache-put <relative-path> --topics topic1.md,topic2.md --vault /path/to/vault
 
# Clean up deleted sources
python scripts/agent_wiki_cli.py cleanup --vault /path/to/vault
 
# Get wiki health status
python scripts/agent_wiki_cli.py status --vault /path/to/vault
 
# Rebuild the retrieval index (wiki/.wiki-index.json) without writing .base files
python scripts/agent_wiki_cli.py index --vault /path/to/vault
 
# Backfill source_type frontmatter to match each topic's sources[] file formats
python scripts/agent_wiki_cli.py normalize-source-type --vault /path/to/vault
 
# Generate Obsidian Bases (.base) views: wiki/index.base + <name>.base master table
python scripts/agent_wiki_cli.py gen-base --name sources --vault /path/to/vault
 
# Register an Agent-authored research report (wiki/queries/<name>.md) and tag kind: query
python scripts/agent_wiki_cli.py save-report <name> --vault /path/to/vault
 
# Generate per-topic JSON Canvas knowledge graphs under wiki/graphs/ (one topic or all)
python scripts/agent_wiki_cli.py gen-canvas --topic <name> --vault /path/to/vault
python scripts/agent_wiki_cli.py gen-canvas --all --vault /path/to/vault
 
# Build/refresh the wiki/index.md skeleton + its managed "工作区" card block
python scripts/agent_wiki_cli.py gen-home --vault /path/to/vault
 
# Render index.md without writing it, so an MCP-side conditional write can apply it
python scripts/agent_wiki_cli.py gen-home --emit-only --vault /path/to/vault
 
# Extract raw 作者 rows from each topic's source notes (read-only)
python scripts/agent_wiki_cli.py extract-authors --vault /path/to/vault
 
# Deduplicated first-author list per topic, for frontmatter backfill (read-only)
python scripts/agent_wiki_cli.py aggregate-authors --vault /path/to/vault
 
# Compute quality tier distribution and per-topic metrics (read-only)
python scripts/agent_wiki_cli.py quality --vault /path/to/vault
 
# Identify covered sources vs gaps (read-only)
python scripts/agent_wiki_cli.py coverage --vault /path/to/vault
 
# Inventory keywords across topics to derive subject categories (read-only)
python scripts/agent_wiki_cli.py keywords --vault /path/to/vault
 
# Get maintenance worklists: wanted (broken links) and stale topics (read-only)
python scripts/agent_wiki_cli.py worklist --vault /path/to/vault
 
# Generate static HTML site (optional, requires markdown package)
python scripts/agent_wiki_cli.py gen-site --vault /path/to/vault

Vault Path Resolution: Use --vault PATH or set environment variable AGENT_WIKI_VAULT. This is the agent-wiki source scope, which may be the registered Obsidian root or a child directory. Each scope owns its own wiki/; multiple scopes can coexist in one registered Obsidian vault. Paths in topic frontmatter/cache are relative to the selected scope.

CLI Command Matrix

All commands emit JSON on stdout and JSON errors on stderr with a non-zero exit code. Per-command inputs and output shapes: see references/cli-matrix.md.

Agent Workflow

Intent Routing

Before any action, classify the user request into one of two modes. Default to Answer mode.

Rules:

• Reports are the default output. A regular question never triggers topic generation — unless the user explicitly requests wiki building/maintenance, or explicitly says "make it a topic page".
• Topics are only produced in Ingest/Maintain mode: when ingesting source notes, batch ingesting, or maintaining/enriching existing topics.
• When uncertain which mode applies, treat as Answer and produce a report directly; confirm if wiki building is actually needed.
• Answer mode can read topics/index for retrieval (read-only), but does NOT write topics.

Standard Ingest Loop

1. Scan: Run scan to get new/modified/deleted sources
2. Process each source:

• For new/modified: Read source → generate/update enriched topic pages → cache-put
• For deleted: Run cleanup (handles topic frontmatter update and archival)

1. Refresh retrieval index: Run index to rebuild wiki/.wiki-index.json from topic frontmatter
2. Refresh views: Run gen-base to (re)write the Bases views (this also rebuilds the index), then update wiki/index.md with topic summaries and embed ![[index.base#主题总览]]
3. Log: Append to wiki/log.md

Batched Ingest (large vaults)

To avoid loading the whole vault at once, process sources in bounded rounds:

1. Plan: Run plan --batch-size 20 once. It scans, splits the pending sources into rounds of at most N, and writes a checklist report to wiki/_archived/ingest-tasks.md.
2. Process one round: Read only the docs in the current batch, author/update their topic pages, and cache-put each one. Do not read ahead into later batches.
3. Confirm the round: Run batch-done --batch <id>. It refuses (batch_incomplete, listing missing docs) until every doc in the batch is cached, then marks the batch [x] and returns remaining batch ids.
4. Repeat for each remaining batch until complete is true.
5. Finish: Run cleanup (if any deletions), then gen-base, and log as usual.

status reports batch progress under batch. Re-running plan re-derives batches from the current scan — already-ingested docs drop out automatically.

Bounded Enrichment Loop

After initial ingest, maintain topics incrementally without scanning the entire vault:

1. Check worklist: Run worklist for two bounded queues: wanted (broken wikilink targets ranked by inbound demand) and stale (low-quality stub/basic or index-stale topics)

Understanding `wanted` (Broken Wikilinks): These are wikilink targets referenced by wiki/topics/ pages but not yet created as dedicated topic pages. Not an error — most point to source notes in the vault root or other directories outside wiki/. They work as jump links in Obsidian; the "broken" label only means no dedicated topic page exists. Use as demand signal: inbound count shows reference frequency → prioritize high-demand sources (≥3) for enrichment.

1. Pick one page: Select a single target from wanted (create new topic) or stale (enrich existing)
2. Enrich the page: Read relevant sources, author/update the topic body and frontmatter
3. Re-index: Run index (recomputes quality tiers, backlinks, alias resolution)
4. Repeat: Run worklist again for the updated queue

One page per iteration keeps context bounded; as topics improve, they drop out of stale automatically. status reports wanted_count and stale_count for progress tracking.

Quality Tiering

Topics get a five-tier rating (stub / basic / standard / rich / premium) from structural metrics of the markdown body (sections, evidence lines, script-fair prose weight, images, lead sentence — see references/topic-authoring.md for metric definitions).

Effective prose with source grounding: effective_prose = prose_weight + 500 × unique_source_count — each deduplicated source reference adds a grounding bonus.

Tier gates (top-down first-match):

• premium: sections ≥ 6 AND effective_prose ≥ 3000 AND evidence_lines ≥ 3
• rich: sections ≥ 4 AND effective_prose ≥ 1500 AND (evidence_lines ≥ 1 OR has_image)
• standard: sections ≥ 2 AND effective_prose ≥ 600
• basic: (effective_prose ≥ 200 AND prose_weight > 0) OR sections ≥ 1
• stub: otherwise

Usage: quality reports structural completeness, not scientific truth. worklist flags stub/basic topics as stale and reports source-backed pages in review; index recomputes tiers on every rebuild. The formula is deterministic and monotonic — quality and index apply the same source-grounding bonus.

Authors Backfill

When source notes carry a 作者: metadata row: aggregate-authors resolves each topic's sources to root notes and returns the deduplicated first author per topic (read-only). Write the returned lists into each topic's authors frontmatter, then rebuild via index/gen-base. Use extract-authors to inspect raw rows when a result looks off.

Report Capture (research reports)

Persist valuable Agent research reports as first-class, cross-linkable wiki nodes. Capture is passive: the Agent authors the page, then registers it — the CLI writes no prose. This is the default landing spot for Answer mode output.

1. Author the page directly under wiki/queries/<name>.md, with topic-compatible frontmatter (title, sources [may be empty], last_updated, optional summary/keywords, citekey/doi/library_id, and review_status/reviewed_at). Preserve any [[wikilinks]]/![[embeds]] verbatim. For a repeatable literature review, start from templates/query/research.md.
2. Register it: run save-report <name>. The CLI ensures the kind: query discriminator (directory-derived), appends a log entry, and emits the page path. <name> is sanitized to its final path component with .md ensured.
3. Re-ingest / cross-link: run index (or gen-base) to pick the page up into the retrieval index under queries. To relate a report to a topic, add a [[wikilink]] in either page body — relations are surfaced by gen-canvas.

The CLI touches only wiki/queries/ and wiki/log.md; an uninitialized wiki → wiki_not_initialized, a missing page → capture_not_found, and unparseable frontmatter fails with no write and no log entry.

Web Augmentation & Citations (Supplement when information is insufficient)