Agent Wiki

agent-wiki

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

Prerequisites

pip install PyYAML

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),
# writing a task report to wiki/_archived/ingest-tasks.md
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  --vault /path/to/vault

# Record ingest result
python scripts/agent_wiki_cli.py cache-put  --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 + .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/.md) and tag kind: query
python scripts/agent_wiki_cli.py save-report  --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  --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
# Cards auto-detect Dataview (--cards auto|on|off); index.md prefers the Obsidian Local REST API when configured, else atomic write (--no-rest forces atomic)
python scripts/agent_wiki_cli.py gen-home --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

# Get maintenance worklists: wanted (broken links) and stale (low-quality/outdated) 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.

CLI Command Matrix

| Command | Purpose | Input | Output (JSON) | |---------|---------|-------|---------------| | init | Create wiki structure | vault path | {"status": "ok"\|"already_initialized", "created": [...]} | | scan | Classify sources as new/modified/deleted | vault path | {"version": 1, "vault": "...", "stats": {...}, "new": [...], "modified": [...], "deleted": [...]} | | plan | Split pending sources (new+modified) into batches; write task report to wiki/_archived/ingest-tasks.md | vault path, --batch-size (default 20) | {"ok": true, "total": N, "batch_size": N, "report": "...", "batches": [{"id": 1, "status": "pending", "count": N, "items": [...]}]} | | batch-done | Mark a round complete after verifying every doc in it was cache-put | vault path, --batch | {"ok": true, "batch": N, "remaining": [...], "complete": bool} or {"error": "batch_incomplete", "missing": [...]} | | cache-get | Query cache entry | source relative path | {"path": "...", "sha256": "...", ...} or {"path": "...", "status": "absent"} | | cache-put | Record ingest completion | source path, topic list | {"ok": true, "path": "...", "sha256": "..."} | | cleanup | Remove deleted sources from topics | vault path | {"removed": N, "archived": M, "details": [...]} | | status | Wiki health metrics (read-only) | vault path | {"vault": "...", "sources_tracked": N, "topics_total": N, "index_exists": bool, "index_topics": N, "index_stale": bool, "index_errors": [...], "batch": {...}\|null, "quality_distribution": {...}, "featured_count": N, "aliases_count": N, "backlinks_max": N, "gaps_count": N, "wanted_count": N, "stale_count": N, "site_exists": bool, "site_stale": bool, ...} | | index | Rebuild wiki/.wiki-index.json from topic frontmatter (no .base written) | vault path | {"ok": true, "topics": N, "errors": [...]} | | normalize-source-type | Rewrite each topic's source_type frontmatter to its sources[] file format (in place; no-source topics skipped) | vault path | {"ok": true, "changed": [{"path": "...", "source_type": "..."}], "skipped": N, "errors": [...]} | | gen-base | Rebuild the index, then write Obsidian Bases views (index + master table) | vault path, --name | {"ok": true, "prefix": "...", "written": [...]} | | save-report | Register an Agent-authored research report under wiki/queries/, ensure kind: query, log it | name, vault path | {"ok": true, "path": "queries/.md", "kind": "query"} | | gen-canvas | Generate per-topic JSON Canvas 1.0 graph(s) under wiki/graphs/ from the index (topic center + sources[] ring + 1-hop neighbor topics) | vault path, --topic or --all | {"ok": true, "path": "wiki/graphs/.canvas", "nodes": N, "edges": M} or {"ok": true, "written": [...], "count": K} | | gen-home | Build/refresh the wiki/index.md skeleton + one managed "工作区" block (Dataview card grid when detected, else static list); refreshes only the managed block on re-run (agent prose preserved), appends it to an unmarked content-bearing index; never touches index.base | vault path, --cards auto\|on\|off (default auto), --no-rest | {"ok": true, "path": "wiki/index.md", "cards": bool, "write_via": "rest\|atomic"} | | extract-authors | Raw 作者 row per topic source note (read-only) | vault path | {"ok": true, "topics": {".md": [{"src": "...", "file": "...", "authors": "..."}]}} | | aggregate-authors | Deduplicated first author per topic for frontmatter backfill (read-only) | vault path | {"ok": true, "authors": {".md": ["作者1", ...]}} | | quality | Compute quality tier distribution and metrics per topic (read-only) | vault path | {"ok": true, "tiers": {".md": {"tier": "...", "metrics": {...}}}, "distribution": {"stub": N, ...}, "errors": [...]} | | coverage | Identify covered sources vs gaps (read-only) | vault path | {"ok": true, "covered": N, "gaps": [{"path": "..."}], "coverage_ratio": 0.0-1.0} | | worklist | Get maintenance worklists: wanted (broken link targets ranked by demand) and stale (low-quality or index-stale topics) for bounded enrichment (read-only) | vault path | {"ok": true, "wanted": [{"target": "...", "inbound": N, "linked_from": [...]}], "stale": [{"path": "...", "tier": "...", "reason": "low_tier"\|"index_stale"}]} | | gen-site | Generate self-contained static HTML site under wiki/site/ (optional; requires markdown package; degrades gracefully to escaped plaintext if absent; inline CSS; deterministic injective filenames) | vault path | {"ok": true, "pages": N, "out": "wiki/site", "degraded": bool} |

Agent Workflow

Intent Routing

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

| Trigger Signal | Mode | Action | Output | |---|---|---|---| | User is asking / seeking explanation / requesting lookup on a topic ("what is…", "compare…", "help me find…") — and NOT requesting wiki building | Answer (default) | Follow Hybrid Retrieval Protocol to answer → optionally save-report as a report | wiki/queries/.md (kind: query), does NOT create/modify topics | | User explicitly requests "build / import / ingest / update / maintain wiki", or "create topics from these notes", or points to a vault/directory to be ingested | Ingest/Maintain | Follow Standard / Batched Ingest or Bounded Enrichment | wiki/topics/.md (kind: topic) |

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 (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 instead of the single-pass loop above:

1. Plan: Run plan --batch-size 20 once. It scans, splits the pending sources

(new + modified) into rounds of at most N (default 20), and writes a checklist report to wiki/_archived/ingest-tasks.md. The JSON lists each batch's items.

1. 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.

1. Confirm the round: Run batch-done --batch . It refuses (batch_incomplete,

listing missing docs) until every doc in the batch is cached, then marks the batch [x] in the report and returns remaining batch ids.

1. Repeat for each remaining batch until complete is true.
2. Finish: Run cleanup (if any deletions), then gen-base, and log as usual.

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

Bounded Enrichment Loop

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

1. Check worklist: Run worklist to get two bounded work queues:

• wanted: broken wikilink targets ranked by demand (inbound link count)
• stale: low-quality topics (stub/basic tier) or index-stale topics (modified after last index rebuild)

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

Key properties:

• No full-vault scan: worklist reads only the index, not every source file
• One page per iteration: Bounded context, no state explosion
• Automatic priority: wanted ranks by link demand, stale identifies quality gaps
• Self-correcting: as topics improve (tier rises), they drop out of stale automatically

Status metrics: status reports wanted_count and stale_count for progress tracking.

Quality Metrics & Tiering

Topics are automatically assigned a five-tier quality rating (stub / basic / standard / rich / premium) based on structural metrics computed from the markdown body:

Metrics:

• sections: count of level-2 to level-6 ATX headings (## to ######), excluding level-1 title
• evidence_lines: count of blockquote lines (starting with > )
• prose_weight: script-aware prose measure combining CJK ideographs and Latin words
• CJK characters (East Asian Width W/F, Unicode category L/N): weighted ×10
• Latin/other word runs: weighted ×16
• Ratio calibrated so equivalent-information content in CJK and Latin tier equally
• cjk_chars, latin_words: component counts (transparency)
• prose_chars: raw NFC character count (retained for transparency)
• has_image: boolean, true if body contains Obsidian (![[image.ext]]) or Markdown (``) image embeds
• has_lead: boolean, true if first non-blank line after optional level-1 heading is a paragraph (not heading/list/quote/table/image-only)

Effective prose with source grounding: effective_prose = prose_weight + 500 × unique_source_count

Each deduplicated source reference adds a 500-point grounding bonus, rewarding well-referenced topics.

Tier gates (top-down first-match):

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

Tiers are monotonic in all dimensions (adding prose, sections, evidence, images, or sources never lowers tier). The formula is deterministic and script-fair: CJK and Latin content of equivalent information density receive the same tier.

Usage: quality command reports per-topic metrics and tier distribution. worklist identifies stub/basic topics as stale candidates for enrichment. index recomputes tiers on every rebuild.

Authors Backfill

When source notes carry a 作者: metadata row and topics accumulate too many / duplicate authors, normalize them deterministically:

1. aggregate-authors resolves each topic's sources to the root notes, extracts the

作者: row, and returns the deduplicated first author per topic (read-only).

1. Write the returned lists into each topic's authors frontmatter, then rebuild via

index/gen-base. Use extract-authors to inspect the 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 (mirroring cache-put). This is the default landing spot for Answer mode output (see Intent Routing).

1. Author the page directly under wiki/queries/.md (a research report), with

topic-compatible frontmatter (title, sources [may be empty], last_updated, optional summary/keywords). Preserve any [[wikilinks]]/![[embeds]] verbatim.

1. Register it: run save-report . The CLI ensures the kind: query discriminator

(directory-derived), force-setting and atomically rewriting only when it is absent or wrong (a correctly-tagged page is left byte-unchanged), appends a capture | save_report | log entry, and emits the page path. ` is sanitized to its final path component with .md` ensured.

1. Re-ingest / cross-link: run index (or gen-base) to pick the page up into the

retrieval index under the queries object (with its kind and body links[]). To relate a report to

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Dianel555
• Source: Dianel555/DSkills
• License: MIT
• Homepage: https://github.com/Dianel555/DSkills

Install and usage instructions live in the source repository linked above.