Dev

.gitignore

@@ -23,6 +23,9 @@ src-tauri/gen/
 
 # Internal docs (not shipped)
 docs/
+# But: the skill subproject's docs ARE part of the public skill surface.
+!skill/docs/
+!skill/docs/**
 
 # Benchmark and test data (local only)
 tests/

HERMES.md

@@ -0,0 +1,78 @@
+# llm-wiki — Hermes Skill Entry
+
+> **Status: ✅ Complete** — all CLI commands and MCP tools are
+> implemented and validated end-to-end (see
+> [`skill/docs/test-report.md`](skill/docs/test-report.md)).
+
+## What this skill does
+
+Build and maintain a structured knowledge base ("wiki") from raw
+documents. Every command operates on a single project root that
+contains a `wiki/` subdirectory. See [`SKILL.md`](SKILL.md) for the
+full command reference.
+
+## Trigger conditions
+
+Load this skill when the user mentions:
+
+- "知识库" / "wiki"
+- "知识图谱" / "graph analysis" / "knowledge graph"
+- "深度研究" / "deep research"
+- "知识缺口" / "knowledge gap"
+- "惊人连接" / "surprising connection"
+- ingest / search / lint operations against an existing wiki
+
+## Two integration modes
+
+### Mode A — CLI shell-out (the original Hermes path)
+
+```bash
+node skill/dist/cli.js <command> <wiki_root> [args]
+```
+
+All eight commands (`status`, `search`, `graph`, `insights`, `lint`,
+`init`, `ingest`, `deep-research`) follow this pattern. JSON output is
+produced where appropriate so downstream agents can parse it.
+
+### Mode B — Hermes MCP client
+
+Recent Hermes versions support MCP. Register the server in your
+Hermes MCP config:
+
+```yaml
+servers:
+  llm-wiki:
+    command: node
+    args: ["/abs/path/to/llm_wiki/skill/dist/mcp-server.js"]
+    env:
+      WIKI_PATH: /Users/me/wiki
+      OPENAI_API_KEY: sk-...
+      LLM_MODEL: gpt-4o-mini
+      TAVILY_API_KEY: tvly-...
+```
+
+The same seven `wiki_*` tools appear as native Hermes tool calls.
+
+Detailed walk-through: [`skill/docs/usage-hermes.md`](skill/docs/usage-hermes.md).
+
+## Install
+
+```bash
+cd skill
+npm install
+npm run build
+```
+
+Or use the existing repo installer:
+
+```bash
+bash install.sh --platform hermes
+```
+
+## Requirements
+
+- Node.js ≥ 20
+- `OPENAI_API_KEY` (or `LLM_API_KEY` + `LLM_BASE_URL`) for `ingest`
+  and `deep-research`
+- `TAVILY_API_KEY` for `deep-research`
+- All other commands work without any LLM credentials

SKILL.md

@@ -0,0 +1,136 @@
+---
+name: llm-wiki
+version: 0.4.6-skill.1
+license: MIT
+description: |
+  Backend port of nashsu/llm_wiki (knowledge-base builder + maintainer)
+  delivered as a single Node.js library exposed through three entry
+  points: a CLI, an MCP stdio server, and this skill manifest.
+
+  Trigger conditions: the user mentions a "knowledge base", "wiki",
+  "knowledge graph", "graph analysis", "deep research", "ingest a
+  source into the wiki", "知识库", "知识图谱", "深度研究", or asks
+  to operate on an already-initialized wiki directory (search,
+  health check, insights, etc.).
+metadata:
+  origin: nashsu/llm_wiki (GUI stripped, backend extracted)
+  runtime: node >= 20
+  entry_points:
+    cli: skill/dist/cli.js
+    mcp: skill/dist/mcp-server.js
+  hermes:
+    tags: [knowledge-base, wiki, graph-analysis, deep-research, semantic-search]
+---
+
+# llm-wiki — Skill Manifest
+
+Three equivalent ways to use this skill, picked by the host:
+
+1. **MCP (recommended)** — point your AI host (Claude Desktop, Cursor,
+   VS Code Copilot Chat, OpenAI Codex CLI, Hermes) at
+   `skill/dist/mcp-server.js`. It exposes seven `wiki_*` tools.
+2. **CLI** — shell out to `node skill/dist/cli.js <command>`.
+3. **Direct library** — `require('./skill/dist/lib/...')` from your
+   own Node.js code.
+
+All three routes hit the same backend (`skill/src/lib/`).
+
+## Install
+
+```bash
+cd skill
+npm install
+npm run build
+```
+
+Verify:
+
+```bash
+node dist/cli.js --help
+node dist/cli.js status /path/to/wiki-project
+```
+
+Run the full end-to-end test suite (real HTTP server, no mocks):
+
+```bash
+npm run test:e2e
+# → writes skill/docs/test-report.md
+```
+
+## CLI commands
+
+| Command | Purpose |
+|---|---|
+| `init <wiki>` | Create the wiki directory layout |
+| `status <wiki>` | Page count + community count |
+| `search <wiki> <query>` | BM25 (+ optional vector) search with snippets |
+| `graph <wiki>` | Build knowledge graph (4-signal relevance + Louvain) |
+| `insights <wiki>` | Surprising connections + knowledge gaps |
+| `lint <wiki>` | Find orphans / isolated pages |
+| `ingest <wiki> <file>` | Two-stage LLM ingest of a markdown/text source |
+| `deep-research <wiki> <topic>` | Web search → LLM synthesis → auto-ingest |
+
+Examples:
+
+```bash
+node skill/dist/cli.js status        ~/notes/my-wiki
+node skill/dist/cli.js search        ~/notes/my-wiki "attention mechanism"
+node skill/dist/cli.js insights      ~/notes/my-wiki
+node skill/dist/cli.js ingest        ~/notes/my-wiki ~/raw/paper.md
+node skill/dist/cli.js deep-research ~/notes/my-wiki "Mixture of Experts"
+```
+
+## MCP tools
+
+Exact JSON schemas are in `skill/src/mcp-server.ts`.
+
+| Tool | Required args | Optional args |
+|---|---|---|
+| `wiki_status` | — | `project_path` |
+| `wiki_search` | `query` | `project_path`, `limit` |
+| `wiki_graph` | — | `project_path`, `format` (`summary`\|`json`) |
+| `wiki_insights` | — | `project_path`, `max_connections`, `max_gaps` |
+| `wiki_lint` | — | `project_path` |
+| `wiki_ingest` | `source_file` | `project_path`, `folder_context` |
+| `wiki_deep_research` | `topic` | `project_path`, `search_queries`, `auto_ingest` |
+
+## Configuration (env vars)
+
+| Variable | Purpose |
+|---|---|
+| `OPENAI_API_KEY` / `LLM_API_KEY` | LLM credentials |
+| `LLM_BASE_URL` | OpenAI-compatible endpoint (Ollama, OpenRouter, ...) |
+| `LLM_MODEL` | Model name (default `gpt-4o-mini`) |
+| `LLM_PROVIDER` | `openai` / `anthropic` / `ollama` / `deepseek` |
+| `TAVILY_API_KEY` | Required for `deep-research` / `wiki_deep_research` |
+| `WIKI_OUTPUT_LANGUAGE` | `auto` / `English` / `Chinese` / ... |
+| `WIKI_PATH` | Default project path for the MCP server |
+| `EMBEDDING_*` | Optional vector search (graceful no-op if unset) |
+| `SKILL_VERBOSE` | Mirror activity logs to stderr |
+
+## Host integration guides
+
+- Claude (Desktop MCP + Claude Code Skill): [`skill/docs/usage-claude.md`](skill/docs/usage-claude.md)
+- Cursor (MCP): [`skill/docs/usage-cursor.md`](skill/docs/usage-cursor.md)
+- VS Code Copilot Chat (MCP): [`skill/docs/usage-copilot.md`](skill/docs/usage-copilot.md)
+- OpenAI Codex CLI (MCP): [`skill/docs/usage-codex.md`](skill/docs/usage-codex.md)
+- Hermes (Skill or MCP): [`skill/docs/usage-hermes.md`](skill/docs/usage-hermes.md)
+
+## Architecture & test report
+
+- Architecture: [`skill/docs/architecture.md`](skill/docs/architecture.md)
+- E2E test report: [`skill/docs/test-report.md`](skill/docs/test-report.md)
+- Status / progress: [`skill/docs/skill-mcp-progress.md`](skill/docs/skill-mcp-progress.md)
+
+## Out of scope
+
+This is a backend-only skill. Image extraction (PDF/PPTX/DOCX),
+vision-LLM captioning, the async sweep-reviews queue, and the
+embedded vector index are intentionally not ported — they require
+the GUI desktop app or specialized binary dependencies. Use the
+upstream [nashsu/llm_wiki](https://github.com/nashsu/llm_wiki) Tauri
+app for those.
+
+REVIEW blocks emitted by the LLM during `ingest` are still parsed and
+returned to the caller (the CLI prints them as JSON; the MCP tool
+includes them in the reply) so a host can act on them.

install.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# llm-wiki-nashsu install script
+# Installs the nashsu backend skill (CLI-based, no GUI)
+
+set -euo pipefail
+
+SKILL_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLATFORM="${1:-}"
+
+install_skill_files() {
+  local target_dir="$1"
+  mkdir -p "$target_dir"
+  cp -r "$SKILL_DIR"/* "$target_dir/"
+  echo "✅ Skill files installed to $target_dir"
+}
+
+install_npm_deps() {
+  local skill_dir="${1:-$SKILL_DIR}"
+  if [ -d "$skill_dir/skill" ]; then
+    echo "📦 Installing Node.js dependencies..."
+    cd "$skill_dir/skill"
+    npm install --quiet
+    echo "✅ Dependencies installed"
+  fi
+}
+
+echo "🔧 llm-wiki-nashsu Skill Installer"
+echo "   Source: $SKILL_DIR"
+echo ""
+
+case "$PLATFORM" in
+  --platform=hermes|--platform\ hermes)
+    HERMES_SKILLS="${HOME}/.hermes/skills"
+    TARGET="${HERMES_SKILLS}/llm-wiki-nashsu"
+    echo "🎯 Platform: Hermes"
+    install_skill_files "$TARGET"
+    install_npm_deps "$TARGET"
+    echo ""
+    echo "✅ Installed to: $TARGET"
+    echo "   Usage: hermes run llm-wiki-nashsu graph <wiki_root>"
+    ;;
+
+  --platform=claude|--platform\ claude)
+    echo "🎯 Platform: Claude Code"
+    echo "   Add to CLAUDE.md:"
+    echo "   @${SKILL_DIR}/SKILL.md"
+    install_npm_deps
+    ;;
+
+  "")
+    echo "📦 Local installation (no platform)"
+    install_npm_deps
+    echo ""
+    echo "✅ Ready. Usage:"
+    echo "   node ${SKILL_DIR}/skill/src/cli.ts graph <wiki_root>"
+    ;;
+
+  *)
+    echo "⚠️  Unknown platform: $PLATFORM"
+    echo "   Supported: --platform hermes, --platform claude"
+    exit 1
+    ;;
+esac