llm-wiki

name	llm-wiki
version	0.6.0
description	Build, query, and maintain a personal LLM-powered wiki from a local knowledge base. Features three distinct modes: Ingest (add knowledge), Query (ask questions with auto-enhancement), and Lint+Heal (health check + auto-repair). Query mode includes full knowledge compounding loop (Tier 1-3): automatic logging, smart enhancement (A/B/C/D types), and periodic review with query pattern analysis and archiving. Supports multiple knowledge source directories, automatic Quartz initialization, and GitHub Pages sync.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","AskUserQuestion","WebSearch","WebFetch","Skill","Agent"]

/llm-wiki — LLM Wiki Manager

Build and maintain a personal knowledge wiki following the LLM Wiki pattern by Andrej Karpathy.

---

Phase 0: Startup Check (ALWAYS RUN FIRST)

Before doing anything else, check if the skill has been configured:

Read the file: ~/.claude/skills/llm-wiki/config.md

• If the file exists AND configured: true is in the frontmatter: Parse the config and proceed to Phase 1 (Intent Routing). Extract:

  • SOURCE_DIRS: list of paths under "## Source Directories"
  • WIKI_DIR: path under "## Wiki Directory"
  • GITHUB_PAGES: URL under "## GitHub Pages" (may be empty)

• If the file does not exist OR configured: true is missing: Run the First-Time Setup Wizard below before proceeding.

---

First-Time Setup Wizard

Greet the user and explain this is a one-time setup. Run these three steps in order:

Setup Step 1: Dependency Check

Run the following checks silently:

node --version 2>/dev/null
git --version 2>/dev/null

• If Node.js is not found or version is below v18:

  ❌ 未检测到 Node.js（v18 或以上）。
  请先安装：https://nodejs.org
  安装完成后，重新运行 /llm-wiki 继续配置。
  

  Stop here. Do not proceed until the user resolves this.

• If Git is not found:

  ❌ 未检测到 Git。
  请先安装：https://git-scm.com
  安装完成后，重新运行 /llm-wiki 继续配置。
  

  Stop here.

• If both are found, tell the user: ✅ 环境检查通过（Node.js vX.X.X，Git vX.X.X）

Setup Step 2: Knowledge Base Directories

Ask the user:

请输入你的知识库目录路径。
支持多个目录，每行输入一个。输入完成后告诉我。

例如：
/Users/yourname/Obsidian/Raw
/Users/yourname/Obsidian/Learning

For each path the user provides:

• Verify it exists: ls "{path}" 2>/dev/null
• If it does not exist, warn: ⚠️ 路径不存在：{path}，请确认后重新输入
• Ask user to confirm the final list before saving

Setup Step 3: Wiki Directory

Ask the user:

Wiki 要保存在哪个目录？
如果目录不存在，我会自动帮你初始化一个新的 Quartz 项目。

例如：/Users/yourname/MyWiki

After the user provides the path:

Case A — Directory already exists and contains a Quartz project (check for quartz.config.ts):

✅ 检测到已有的 Quartz Wiki 项目，直接使用。

Case B — Directory does not exist or is empty:

📦 正在初始化 Quartz Wiki 项目，请稍候...

Run the following to initialize:

git clone https://github.com/jackyzha0/quartz.git "{WIKI_DIR}"
cd "{WIKI_DIR}"
npm install

Then apply the standard wiki configuration:

• Set pageTitle to "LLM Wiki" in quartz.config.ts
• Create content/index.md with a basic welcome page
• Create content/log.md with initial entry
• Create SCHEMA.md (copy the standard schema — see Schema section below)

Tell the user when done: ✅ Quartz Wiki 初始化完成：{WIKI_DIR}

Setup Step 4: GitHub Pages (Optional)

Ask the user:

（选填）你的 GitHub Pages 地址是什么？
格式如：https://username.github.io/LLMWiki
直接回车跳过。

Save Config

Write the collected values to ~/.claude/skills/llm-wiki/config.md:

---
configured: true
---

# LLM Wiki 配置文件

此文件由 /llm-wiki 首次运行向导自动生成。如需修改，直接编辑对应字段即可。

## Source Directories
# 知识库目录（支持多个路径，每行一个）
- {path1}
- {path2}

## Wiki Directory
{wiki_dir}

## GitHub Pages
{github_pages_url}

Tell the user: ✅ 配置已保存！下次运行 /llm-wiki 将直接使用这些设置。

Then proceed to Phase 1 (Intent Routing).

---

Phase 1: Intent Routing

Read {WIKI_DIR}/content/index.md to understand the current wiki structure, then determine the user's intent from their input:

1. Asking a question about existing knowledge → Go to Query Flow
2. Requesting cleanup, health check, or gap finding → Go to Lint Flow
3. Providing a topic to research or new sources → Go to Ingest Flow

If the intent is ambiguous, ask the user which of the three operations they want to perform.

---

Ingest Flow (Knowledge Building)

Step 1: Topic Resolution

Based on the user's input and index.md, determine if this is a new topic or relates to an existing one:

• Clearly a new topic: Tell the user and prepare to create a new topic directory.
• Clearly related to an existing topic: Tell the user "这与已有话题 [Topic Name] 相关，准备补充资料。"
• Ambiguous: Present the closest 1-2 existing topics and ask: 新建新话题，还是补充到现有话题中？

Step 2: Scope Clarification

Ask the user (concisely, max 2 rounds):

1. Mode: 批量模式（一次处理完，结束后再看结果）or 精读模式（每个资料处理完暂停确认）?
2. Focus: 有没有特别想深入的方向，或偏好的资料类型？

Step 3: Source Discovery

Scan all SOURCE_DIRS for relevant files:

find "{source_dir}" -type f \( -name "*.md" -o -name "*.pdf" -o -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.webp" \) 2>/dev/null

Run this for each directory in SOURCE_DIRS. Merge results, filter by relevance, present to user grouped by type (MD / PDF / Image), and ask for confirmation.

Threshold rules:

• < 3 files: Proactively suggest web search for supplementary materials
• 3–9 files: Offer web search as an option
• ≥ 10 files: Proceed directly, optionally offer enrichment

Step 4: Wiki Construction

Read {WIKI_DIR}/SCHEMA.md FIRST to strictly follow page format and wikilink rules.

CRITICAL: Bilingual Content Generation (Default Behavior)

All wiki pages MUST be generated in bilingual format (English + Chinese) by default. For each paragraph:

1. Write the English content first
2. Immediately translate to Chinese using the configured translation engine
3. Append the translation as: <div class="zh-trans">中文翻译</div>

Translation Engine Selection: Read ~/.claude/skills/llm-wiki/config.md to get translation settings:

• primary_engine: First choice (zhipu/deepl/minimax)
• fallback_engine: Backup if primary fails
• If both fail, log error and continue with English-only

Translation Rules:

• Preserve technical terms in English: Agent, Harness, CLI, LLM, SDK, API, RAG, MCP, etc.
• Keep proper nouns, product names, and code identifiers untranslated
• Translate naturally for Chinese technical documentation style
• Do NOT translate: frontmatter, code blocks, URLs, wikilinks

GLM-5 Translation Function (Zhipu AI):

def translate_paragraph(text: str, api_key: str, endpoint: str) -> str:
    """Translate using GLM-5 via Anthropic-compatible API."""
    prompt = f"""请将以下英文技术文本翻译成中文。要求：
1. 技术术语保持英文（如 Agent、Harness、CLI、LLM、SDK、API 等）
2. 翻译自然流畅，符合中文技术文档习惯
3. 只输出翻译结果，不要任何解释

{text}"""
    
    payload = {
        "model": "GLM-5",
        "max_tokens": 2000,
        "messages": [{"role": "user", "content": prompt}]
    }
    
    req = urllib.request.Request(
        endpoint,
        data=json.dumps(payload).encode(),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    )
    
    try:
        with urllib.request.urlopen(req, timeout=30) as response:
            result = json.loads(response.read())
            return result["content"][0]["text"].strip()
    except Exception as e:
        # Log error and return empty (fallback to English-only)
        print(f"Translation failed: {e}")
        return ""

Batch mode: Process all sources at once, generate all pages in bilingual format, then show the user a summary.

Deep-read mode: Process one source at a time, generate bilingual content, show the result, wait for feedback, then proceed to the next.

For each source:

1. Generate a bilingual source summary page in {WIKI_DIR}/content/{topic}/sources/
2. Create or update bilingual concept pages in {WIKI_DIR}/content/{topic}/concepts/
3. Create or update bilingual entity pages in {WIKI_DIR}/content/{topic}/entities/
4. Create bilingual synthesis pages for cross-cutting insights in {WIKI_DIR}/content/{topic}/synthesis/
5. Write or update bilingual {WIKI_DIR}/content/{topic}/overview.md
6. Update {WIKI_DIR}/content/index.md
7. Append to {WIKI_DIR}/content/log.md using format: ## [YYYY-MM-DD] ingest | {topic} | {source_title}

Wikilink rule (CRITICAL): Always use full paths from the content root:

• ✅ [[topic-name/concepts/concept-name|Display Text]]
• ❌ [[concepts/concept-name|Display Text]]

Step 5: Build & Preview

cd "{WIKI_DIR}" && npx quartz build

Then start the local server:

cd "{WIKI_DIR}" && python3 serve.py

Tell the user: Wiki 已构建完成，本地预览地址：http://localhost:8888

If serve.py does not exist in the wiki directory, create it first using the standard clean-URL server template.

Offer to sync to GitHub Pages if GITHUB_PAGES is configured.

---

Query Flow (Asking Questions)

1. Search: Read {WIKI_DIR}/content/index.md, identify relevant pages, read them.

2. Answer: Synthesize a comprehensive answer with citations.

3. Auto-log: Automatically record this query to {WIKI_DIR}/query-stats.json:

   {
     "timestamp": "2026-04-06T14:23:45Z",
     "query": "{user_question}",
     "pages_consulted": ["{page1}", "{page2}"],
     "tokens_generated": {estimated_tokens},
     "enhancement_type": null,
     "action_taken": "answered only"
   }
   

   If the file doesn't exist, create it as an empty array [] first.

4. Evaluate enhancement: Check if this query meets quality thresholds:

   • ≥3 pages consulted, OR

   • 500 tokens generated, OR

   • Reveals contradiction/gap between pages

   If threshold met, determine enhancement type:

   • A: New synthesis page (comprehensive cross-page analysis)
   • B: Enhance existing page (found missing content in a concept page)
   • C: Add cross-reference (found related pages without wikilinks)
   • D: Log knowledge gap (cannot answer sufficiently)

5. Execute enhancement:

   C-type (auto):

   • Add wikilink to the Connections section of the relevant page
   • Update the query-stats.json entry with "enhancement_type": "C" and "action_taken": "added cross-reference between {page1} and {page2}"
   • Briefly note at end of answer: [已自动添加 {page1} ↔ {page2} 的交叉引用]

   D-type (auto):

   • Append to {WIKI_DIR}/knowledge-gaps.md (create if doesn't exist):

     ## [YYYY-MM-DD] {topic}
     - 问题：{user_question}
     - 原因：Wiki 中缺少相关内容
     - 建议：联网搜索补充相关概念
     

   • Update query-stats.json entry with "enhancement_type": "D" and "action_taken": "logged knowledge gap"
   • Briefly note: [已将此问题记录到知识空白清单，供下次 Lint 时补充]

   A-type (confirm):

   • Ask user:

     💡 这个分析综合了 {N} 个页面，生成了 {X} tokens 的深度对比。
     建议创建新的 synthesis 页面：{topic}/synthesis/{slug}.md
     是否保存？(y/n)
     

   • If yes: create page following SCHEMA.md format, update index.md, append to log.md, update query-stats.json with "enhancement_type": "A" and "action_taken": "created synthesis/{filename}"
   • If no: update query-stats.json with "enhancement_type": "A" and "action_taken": "user declined"

   B-type (confirm):

   • Ask user:

     💡 发现 {page} 缺少关于 {topic} 的内容。
     建议追加新小节：## {section_title}
     是否保存？(y/n)
     

   • If yes: append section to page, append to log.md, update query-stats.json with "enhancement_type": "B" and "action_taken": "enhanced {page} with new section"
   • If no: update query-stats.json with "enhancement_type": "B" and "action_taken": "user declined"

---

Lint + Heal Flow (Wiki Health Check & Auto-Repair)

Phase 1: Scan (fully automatic)

Read ALL markdown files under {WIKI_DIR}/content/. Check five issue types:

1. Broken links (all pages) Collect every [[wikilink]] in every page. For each, check whether the target file exists under content/. Flag any that don't.

2. Orphan pages (all pages) Find pages that have zero inbound wikilinks from any other page. Sources being orphaned is lower severity than concepts or synthesis.

3. Missing concept pages (all pages) Scan all page bodies for noun phrases that appear ≥ 2 times across the wiki but have no corresponding page in any concepts/ directory. Limit to top 5 most-mentioned missing concepts.

4. Contradictions (concepts + synthesis pages) Compare factual claims across concepts/ and synthesis/ pages. Flag direct conflicts (e.g., page A says X is true, page B says X is false).

5. Knowledge gaps (whole wiki) Identify 2–3 specific questions the wiki currently cannot answer based on its coverage. Frame as questions, not vague topics.

Stale content check (run alongside scan): Find any paragraph or page that contains ⚠️ 待验证 AND was last modified more than 180 days ago. Add to report as "建议复核".

6. Query pattern analysis (Tier 3 of knowledge compounding loop): Read {WIKI_DIR}/query-stats.json if it exists:

• Count queries by topic/theme
• Identify high-frequency topics (≥3 queries on same topic)
• Find repeated questions that Wiki cannot answer well
• Example: if "cost optimization" was queried 3+ times but no related pages exist, flag it

7. Query archive check: Check the oldest timestamp in query-stats.json:

• If oldest record is >180 days old, flag for archiving
• Archive target: query-stats-archive-YYYY-QN.json (by quarter)
• Keep only recent 180 days in query-stats.json

---

Phase 2: Report

Present findings grouped by severity. Use this format:

📋 Wiki 健康报告 — YYYY-MM-DD
扫描了 N 个页面

🔴 断链（N处）
  - {page} 第{n}行 → [[{target}]] 不存在

🟡 孤立页（N处）
  - {page} — 没有任何页面链接到它

🟡 缺少概念页（N个）
  - "{concept}" — 在 N 个页面中被提到，但没有概念页

🟠 矛盾（N处）
  - {page A} 与 {page B} 关于"{topic}"的说法冲突

🔵 知识空白（Wiki 目前无法回答）
  1. {question}
  2. {question}

⏰ 建议复核（⚠️标记超过180天）
  - {page} — 标记于 {date}

📊 Query 模式分析（基于 N 次查询记录）
  高频主题（≥3次）：
  - "{topic}" — 被问了 N 次，Wiki 中缺少相关页面
  建议补充的问题：
  - "{question}"（来自 knowledge-gaps.md）

⏰ Query 记录归档建议
  - 最早记录：YYYY-MM-DD（距今 X 天）
  - 建议归档 180 天前的记录到：query-stats-archive-YYYY-QN.json

---

Phase 3: Confirm what to fix

After the report, present three fix categories and ask the user which to execute:

是否需要修复？请告诉我要做哪些，或直接说「全做」/「只做A」：

【A 类 — 自动修复，不需联网】
  A1. 删除/注释 N 处断链 wikilink
  A2. 为 N 个孤立页在最相关页面补入链

【B 类 — 联网补充】
  B1. 为"{concept}"生成新概念页（需联网搜索）
  B2. 填补知识空白："{question}"（需联网搜索）
  B3. 补充高频 Query 主题："{topic}"（需联网搜索）

【C 类 — Query 数据维护】
  C1. 归档 180 天前的 query 记录 → query-stats-archive-YYYY-QN.json

Wait for user confirmation before proceeding.

---

Phase 4: Heal Execution

A-type fixes (no web search)

A1 — Broken links:

• If the target page clearly doesn't exist and can't be inferred: remove the wikilink brackets, keep plain text.
• If a similar page exists (typo or path issue): correct the wikilink path.

A2 — Orphan pages:

• Read the orphan page's content to understand its topic.
• Find the 1–2 most related pages in the wiki.
• Add a brief mention + wikilink to the orphan from those pages (append to a "Related" or "See also" section).

B-type fixes (web search required)

For each B-type item, follow this pipeline strictly:

Step 1 — Search

WebSearch("{concept or question} site:arxiv.org OR site:anthropic.com OR site:github.com OR site:huggingface.co OR site:paperswithcode.com")

If results are thin, retry without domain filter.

Step 2 — Filter by trusted domains Prioritize results from (in order):

1. arxiv.org / aclanthology.org — academic papers
2. anthropic.com / openai.com / deepmind.com — primary sources
3. github.com — official repos
4. huggingface.co / paperswithcode.com

Deprioritize: blogs, social media, aggregators.

Step 3 — Fetch full content Use baoyu-url-to-markdown skill on the top 2–3 URLs to get full page content.

Step 4 — Cross-validate

• If a key fact appears in ≥ 2 independent sources → write it as a direct statement.
• If a key fact appears in only 1 source → write it with ⚠️ 待验证 marker.

Step 5 — Write to wiki (BILINGUAL)

CRITICAL: All new content MUST be bilingual.

For missing concept pages (B1): Create {WIKI_DIR}/content/{topic}/concepts/{concept-slug}.md following SCHEMA.md format.

• Write each paragraph in English first
• Immediately translate using GLM-5 and append <div class="zh-trans">中文翻译</div>
• Append at the bottom:

---
*Sources added by Heal on YYYY-MM-DD:*
- [Title](url) · YYYY-MM
- [Title](url) · YYYY-MM

For knowledge gaps (B2): If the answer fits an existing page, append a new bilingual section to that page. If the answer is broad enough, create a new bilingual synthesis page. Always append source citations in the same format above.

Never overwrite existing content. Only append new sections or create new pages.

C-type fixes (query data maintenance)

C1 — Archive old query records:

1. Read {WIKI_DIR}/query-stats.json
2. Split records into two groups:
   • recent: timestamp within last 180 days
   • old: timestamp older than 180 days
3. If old is empty: tell user "没有需要归档的记录（最早记录距今不足180天）"
4. If old has records:
   • Determine archive filename by quarter of oldest record:
     • Q1: Jan-Mar → query-stats-archive-YYYY-Q1.json
     • Q2: Apr-Jun → query-stats-archive-YYYY-Q2.json
     • Q3: Jul-Sep → query-stats-archive-YYYY-Q3.json
     • Q4: Oct-Dec → query-stats-archive-YYYY-Q4.json
   • Write old records to archive file (append if file exists, create if not)
   • Write recent records back to query-stats.json
   • Tell user: "已归档 {N} 条记录到 {archive_filename}，query-stats.json 保留最近 {M} 条"

B3 — Supplement high-frequency query topics:

• Same pipeline as B1/B2 (web search → validate → write to wiki)
• Target: create a new concept or synthesis page for the high-frequency topic
• Use the original queries as context to understand what the user wants to know

---

Phase 5: Wrap up

After all fixes are applied:

1. Run npx quartz build to rebuild the wiki.
2. Append to log.md:

## [YYYY-MM-DD] lint+heal | 断链:{n}处, 孤立页:{n}个, 新建概念页:{list}, 填补空白:{list}, 归档query:{n}条

3. Show the user a summary of everything changed.

---

Standard serve.py Template

If {WIKI_DIR}/serve.py does not exist during Step 5, create it with this content:

import http.server
import os
import sys

DIRECTORY = os.path.join(os.path.dirname(os.path.abspath(__file__)), "public")
PORT = 8888

class CleanURLHandler(http.server.SimpleHTTPRequestHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory=DIRECTORY, **kwargs)

    def do_GET(self):
        path = self.path.split("?")[0].split("#")[0]
        full = os.path.join(DIRECTORY, path.lstrip("/"))
        if not os.path.exists(full):
            if os.path.exists(full + ".html"):
                self.path = path + ".html"
            elif os.path.exists(os.path.join(full, "index.html")):
                self.path = path + "/index.html"
            else:
                if os.path.exists(os.path.join(DIRECTORY, "404.html")):
                    self.path = "/404.html"
        super().do_GET()

    def log_message(self, format, *args):
        pass

with http.server.HTTPServer(("", PORT), CleanURLHandler) as httpd:
    print(f"Serving at http://localhost:{PORT}")
    httpd.serve_forever()

---

Important Rules

• Use Chinese for all user-facing communication.
• All wiki content MUST be bilingual (English + Chinese) by default. Each English paragraph followed by <div class="zh-trans">中文翻译</div>.
• Translation engine priority: read from config.md (primary_engine → fallback_engine).
• NEVER modify files in the user's source/knowledge-base directories — they are read-only.
• All writes go to {WIKI_DIR}.
• Always update index.md and log.md after every operation.
• Read SCHEMA.md before generating any wiki pages.