llm-wiki-stack 1.0.0

package/README.md

@@ -0,0 +1,64 @@
+# llm-wiki-stack
+
+Obsidian-based knowledge base compiler. Turns fragmented source notes into an interconnected concept network, powered by LLM compilation.
+
+## Philosophy
+
+Most note systems are **warehouses** — you put things in. This is a **compiler** — it transforms raw material into structured, queryable knowledge.
+
+```
+01 raw/  ──compile──>  02 wiki/  ──dialogue──>  03 outputs/
+(source of truth)      (concept network)          (your opinions)
+```
+
+## Install
+
+```bash
+npx llm-wiki-stack
+```
+
+This copies the skills into `~/.claude/skills/`. Works in Claude Code.
+
+Or clone manually:
+
+```bash
+git clone https://github.com/<your-username>/llm-wiki-stack.git
+cp -R llm-wiki-stack/skills/* ~/.claude/skills/
+```
+
+## Commands
+
+| Command | Action | When |
+|---------|--------|------|
+| `/kb-init` | Bootstrap a knowledge base from scratch | Once per vault |
+| `/wiki-compile` | Compile new raw notes into wiki | After collecting source material |
+| `/wiki-topic` | Question-driven opinion formation | When you have a research question |
+| `/wiki-lint` | Health check + structured report | Monthly |
+
+## How It Works
+
+1. **Collect** — Save articles, thoughts, clippings into `01 raw/` with `status: inbox`
+2. **Compile** — Run `/wiki-compile`; LLM extracts concepts, creates wiki pages, builds cross-references
+3. **Think** — Run `/wiki-topic` with a question; LLM reveals structural relationships between concepts
+4. **Maintain** — Run `/wiki-lint` monthly; LLM surfaces orphan nodes, fragile dependencies, concept evolution
+
+## Key Mechanisms
+
+**Concept Independence Test** — Before creating a new wiki page, every candidate concept must pass:
+- Definability: can you clearly state what this concept *is* in 1-2 sentences?
+- Single core: is it one concept, or "A and B" glued together?
+- Multi-source verification: does it appear in at least two different source notes?
+
+**Concept Evolution** — No overwrites. Understanding changes are tracked in a versioned timeline. Default behavior is *append*, not replace.
+
+**Cross-Reference Integrity** — Every claim links to its raw source. Every wiki link is bidirectional. Linked counts are verified on each compile.
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or compatible AI coding agent
+- [Obsidian](https://obsidian.md/) (recommended, for graph visualization)
+- Git (for version control)
+
+## License
+
+MIT

package/bin/setup.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -e
+
+SKILLS_SRC="$(cd "$(dirname "$0")/../skills" && pwd)"
+SKILLS_DST="${HOME}/.claude/skills"
+
+echo "llm-wiki-stack installer"
+echo "========================"
+echo ""
+
+# Install each skill into ~/.claude/skills/
+for skill_dir in "$SKILLS_SRC"/*/; do
+  skill_name=$(basename "$skill_dir")
+  target="$SKILLS_DST/$skill_name"
+
+  if [ -d "$target" ]; then
+    echo "  updating: $skill_name (existing install, backing up)"
+    rm -rf "${target}.bak" 2>/dev/null
+    mv "$target" "${target}.bak"
+  else
+    echo "  installing: $skill_name"
+  fi
+
+  mkdir -p "$SKILLS_DST"
+  cp -R "$skill_dir" "$target"
+done
+
+echo ""
+echo "Done. Available commands:"
+echo "  /kb-init         — bootstrap a new knowledge base"
+echo "  /wiki-compile    — compile raw sources into wiki"
+echo "  /wiki-topic      — question-driven topic synthesis"
+echo "  /wiki-lint       — health check and structured report"
+echo ""
+echo "Each command delegates to llm-wiki-stack, which reads"
+echo "your repo-local AGENTS.md as the schema of truth."

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "llm-wiki-stack",
+  "version": "1.0.0",
+  "description": "Obsidian knowledge base compiler — three-layer architecture (raw → wiki → outputs) with concept evolution, cross-reference integrity, and health checks. Command-driven, AI-maintained, plain Markdown.",
+  "license": "MIT",
+  "bin": {
+    "llm-wiki-stack": "bin/setup.sh"
+  },
+  "files": [
+    "bin/",
+    "skills/"
+  ],
+  "keywords": [
+    "obsidian",
+    "knowledge-base",
+    "wiki",
+    "markdown",
+    "llm",
+    "claude-code",
+    "compiler",
+    "concept-network",
+    "note-taking",
+    "personal-knowledge-management"
+  ]
+}

package/skills/kb-init/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: kb-init
+description: Subcommand of the `llm-wiki-stack` knowledge-base management framework. Initialize an Obsidian knowledge base from a raw-only or partially initialized directory. Use when the user wants to bootstrap the wiki structure, generate repo-local AGENTS.md, initialize git, or run `/kb-init` directly.
+---
+
+# KB Init
+
+## Framework Binding
+
+- This skill is one command adapter in the `llm-wiki-stack` framework.
+- It does not define its own schema or workflow; it delegates to `../llm-wiki-stack/SKILL.md`.
+- Repo-local `AGENTS.md` overrides both the core framework and this wrapper.
+
+- This skill is a thin wrapper around `llm-wiki-stack`.
+- First read `../llm-wiki-stack/SKILL.md` and follow the `/kb-init` command path only.
+- Treat the user request as an explicit `/kb-init` invocation even if they do not mention `llm-wiki-stack`.
+- Stay within bootstrap orchestration: create missing structure (including `03 outputs/`), generate local `AGENTS.md`, initialize git if needed, and keep the action idempotent.
+- If `01 raw/` contains raw files, generate `03 outputs/初始化提案.md` listing suggested wiki concept pages and link relationships.
+- Wait for user approval before batch compiling raw into wiki.
+- After approval, reuse the core `/wiki-compile` pipeline with an explicit list of all eligible raw files. Do not invent a second compilation path inside this wrapper.
+- Treat `/wiki-lint` mechanical checks as the completion gate for a full initialized knowledge base: uncompiled raw, broken links, frontmatter, raw_sources backfill, backlinks, and linked_count must be checked before writing `03 outputs/初始化完成报告.md`.
+- Do not call `/wiki-topic` during initialization; initialization reports are system outputs, not question-driven topic pages.

package/skills/kb-init/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "KB Init"
+  short_description: "Bootstrap an LLM wiki knowledge base."
+  brand_color: "#0F766E"
+  default_prompt: "Use $kb-init to initialize the current repo as an LLM wiki knowledge base."
+
+policy:
+  allow_implicit_invocation: true
+

package/skills/llm-wiki-stack/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: llm-wiki-stack
+description: Core skill of the `llm-wiki-stack` knowledge-base management framework. 管理基于 Obsidian 的知识库，可用于从仅含 raw 的目录启动一个新的知识库，或维护已初始化的知识库。
+---
+
+# LLM Wiki Stack — 知识库编译器
+
+## Role
+
+你是三层知识库编译器的维护者。将 `01 raw/` 素材编译为 `02 wiki/` 概念网络，辅助用户在 `03 outputs/` 形成观点。
+
+设计起点源自 Karpathy 的 [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 思路，以及《知识库编译器系统规格书》的三层编译器架构。
+
+## Architecture
+
+```
+01 raw/  ──编译──>  02 wiki/  ──对话──>  03 outputs/
+(不可变源)           (概念网络)            (个人观点)
+```
+
+### 权限模型
+
+| 层 | LLM 权限 |
+|----|---------|
+| raw 正文 | **只读**，绝不修改 |
+| raw YAML | **可写，分级**（自动字段/推断字段/手动字段） |
+| raw 文件名 | **可建议**，不直接修改 |
+| wiki | **可创建、更新、链接** |
+| outputs 初始分析 | **可写** |
+| outputs 对话区用户内容/综合判断 | **只读** |
+
+### 页面类型
+
+| type | 层 | 说明 |
+|------|----|------|
+| `source` | raw | 源笔记 |
+| `entity` | wiki | 实体页——具体的人、组织、产品、岗位 |
+| `concept` | wiki | 概念页——跨实体提炼的框架与原理 |
+| `map` | wiki | 分区导航页 |
+| `log` | wiki | 操作日志 |
+| `output` | outputs | 观点主题页 |
+| `health-report` | outputs | 体检报告 |
+
+## Source Of Truth
+
+1. repo-local `AGENTS.md`（最高优先级）
+2. `references/default-schema.md`
+3. `assets/*.template.md`
+
+如果本地 `AGENTS.md` 存在，则视为当前知识库的唯一 schema 来源。如果不存在，只允许 `/kb-init` 继续执行。
+
+## Operating Modes
+
+### Bootstrap Mode
+- 条件：repo 中不存在本地 `AGENTS.md`
+- 允许：`/kb-init`
+- 其他命令一律拒绝
+
+### Managed Mode
+- 条件：本地 `AGENTS.md` 已存在且可读
+- 行为：所有命令优先遵循本地 `AGENTS.md`，仅在其缺失时回落 default-schema
+
+## Command Router
+
+4 个命令，对应规格书的日常操作：
+
+| 命令 | 规格书动作 | 说明 |
+|------|-----------|------|
+| `/kb-init` | `🏗️ 初始化知识库` | 从零或 raw-only 目录启动知识库 |
+| `/wiki-compile` | `🔄 编译新素材` | 编译指定或未编译 raw 进 wiki |
+| `/wiki-topic` | `🧠 新建主题` | question-driven 观点形成 |
+| `/wiki-lint` | `🏥 月度体检` | 健康检查 + 结构化报告 |
+
+（`📄 新建源笔记` 由 Obsidian QuickAdd + 模板完成，非 LLM 命令）
+
+### `/kb-init`
+
+目标：将当前目录初始化为可管理的知识库。
+
+执行要求：
+- 读取 `references/default-schema.md`
+- 执行 dependency doctor：检查 `git`、`rg`、基础 shell 工具、写权限；`git` 与写权限为必需项；`rg` 缺失时回退 `grep/find`
+- 创建 `01 raw/`、`02 wiki/`、`03 outputs/`、`98 template/`
+- 用 `assets/AGENTS.template.md` 生成本地 `AGENTS.md`
+- 用模板生成 `02 wiki/log.md`
+- 创建本地状态文件 `.wiki-kb/state.json`
+- 若 `01 raw/` 下存在 raw 文件，扫描并生成 `03 outputs/初始化提案.md`（建议的 wiki 概念页、重要度、链接关系）
+- **等待用户审阅确认**后，调用本文件的 `/wiki-compile` 核心流水线，并传入全部合格 raw 文件的显式列表；`/kb-init` 不另写轻量编译逻辑
+- 编译后建立或补齐必要的全局索引页和分区 map 页，确保所有已生成概念页可从索引导航到达
+- 将 `/wiki-lint` 的机械检查作为完成门禁：未编译 raw、断链、frontmatter、raw_sources 回填、双向回链、linked_count 一致性和孤立节点必须检查
+- 输出 `03 outputs/初始化完成报告.md`，列出 raw 总数、已编译数、跳过项及原因、概念页数、map 页数和 lint 门禁结果
+- 保持幂等；如果结构已基本存在，只补齐缺失项
+
+### `/wiki-compile`
+
+定义：将 raw 编译进 wiki 的唯一入口。`🔄 编译新素材`。
+
+**文件选择**：
+- 若用户在命令中指定了 raw 文件路径（可多个），直接编译这些文件
+- 若由 `/kb-init` 调用，必须传入已扫描确认的全部合格 raw 文件列表；此时跳过交互式候选确认，但不能跳过文件名阻断、元数据补全、概念独立性测试和交叉引用完整性检查
+- 若用户未指定文件，执行**未编译 raw 检测**：
+  1. 收集 `02 wiki/` 全部概念页 `raw_sources` 中已引用的 raw 路径，构建已编译集合
+  2. 扫描 `01 raw/` 全部 `.md` 文件，找出不在已编译集合中的文件
+  3. 排除 `README.md`、`.gitkeep` 等非笔记文件
+  4. 将候选列表呈现给用户，列出每个文件所属分区和标题，供用户勾选确认
+  5. 若候选列表为空，提示"当前无未编译 raw 文件"并退出
+
+流程（对每个待编译文件）：
+1. **文件名阻断检查**：文件名含随机字符串或与内容明显不符时，停止处理该文件，写入 `title: 建议标题` 到 YAML，追加记录到 `03 outputs/待确认文件名.md`，提示用户处理后重新编译
+2. **元数据补全**：补全缺失的 YAML 字段（type/created/source_url/title/tags）。若 `status` 缺失则设为 `processed`。正文永不修改
+3. **实体与概念提取**：从 raw 提取关键实体和候选概念
+4. **概念独立性测试**（创建新概念页前强制执行）：
+   - **测试一（可定义性 + 单一核心）**：能否用一两句不含同义词循环的话清晰定义？拆解为"A 与 B"/"A 的 B"等形式后，各部分是否各自可独立定义？若可独立定义则为组合概念，不满足单一核心要求
+   - **测试二（多重验证）**：至少来自两个不同 raw 笔记的支撑，且有独立论述角度
+   - 不通过测试一的可定义性 → 不创建页，信息归入上位概念
+   - 不通过测试一的单一核心 → 拆分成独立概念分别创建
+   - 不通过测试二 → 不创建页，标记 `<!-- 潜在独立概念：XXX -->`
+5. **wiki 页创建/更新**：
+   - 无对应 wiki 页则基于 concept 模板创建
+   - 已存在则默认**补充**至 `## 阐述`，不覆盖 `## 当前理解`
+   - **只有新信息明确纠正旧事实**时，触发版本归档：旧定义追加到 `## 概念演化`，更新 `## 当前理解`
+   - **观点冲突**：列入 `## 不同理解`，并列双方时间与出处，不判定对错
+6. 每条关键陈述附 `[[01 raw/...]]` 出处
+7. 建立 wiki 间 `[[02 wiki/...]]` 双向链接
+8. **交叉引用完整性检查**（编译收尾强制执行）：
+   - 出链回填：正文引用的 raw 路径全部回填到 `raw_sources`
+   - 入链保障：`## 相关概念` 列出的每个目标页必须包含回链，缺失时自动补入
+   - linked_count 准确性：等于全库指向该页的链接总数
+   - 孤立检测：linked_count 为 0 的页面显式提醒，向用户确认是否保留
+9. 更新受影响 wiki 页的 `linked_count` 和 `updated`
+
+### `/wiki-topic`
+
+定义：围绕目标主题的 question-driven 观点形成流程，写入 `03 outputs/`。
+
+流程：
+1. 用户提出一个**问题**（非概念列表）
+2. LLM 读取相关 map 页和概念页定位知识，生成 `🤖 初始分析`（含 `[[02 wiki/...]]` 来源标注），写入 `03 outputs/` 新页面
+3. 用户主导后续对话，LLM 回应追问，提供多视角，不替用户做综合判断
+4. 相关 wiki 链接自动建立，`linked_count` 增加
+
+创建或更新 outputs 页面后，必须将正文中引用的所有 wiki 路径回填到 `raw_sources` 字段。
+
+### `/wiki-lint`
+
+定义：全库健康检查 + 结构化报告。`🏥 月度体检`。
+
+执行要求：
+- 机械检查：断链、孤儿页、空目录、frontmatter 完整性、linked_count 一致性、raw_sources 回填、未编译 raw、组合概念命名检测（A与B/A、B与C 模式）
+- 当作为 `/kb-init` 完成门禁调用时，只执行机械检查和低风险自动修复；语义合并、主题创建和破坏性结构清理不得自动执行
+- 语义检查：重复/可合并概念、raw 目录错放、合成缺口、交叉引用缺失（出链无回链）
+- 生成 `03 outputs/月度体检-YYYY-MM.md`，使用 `- [ ]` 任务列表，包含：
+  - 概念演化一览
+  - 脆弱依赖（outputs 依赖低 linked_count 概念）
+  - 孤岛节点（linked_count 为 0 的概念页）
+  - 时间提示（引用已演化概念的 outputs）
+- 输出分级清单：fix（可自动修复）/ consider（需确认）/ notice（仅提示）
+- 只输出建议，绝不自动创建主题页
+
+## Compilation Pipeline
+
+编译是 `/wiki-compile` 的核心流水线：
+
+```
+raw → 文件名阻断 → 元数据补全 → 实体提取 → 概念独立性测试 → wiki 创建/更新 → 交叉引用完整性检查
+```
+
+**概念独立性测试**（创建新概念页前）：可定义性 + 单一核心 + 多重验证。组合概念必须拆分，单一来源概念不创建独立页。
+
+**默认追加原则**：新信息默认补充进 `## 阐述`，不覆盖 `## 当前理解`。只有明确纠正旧错误时才更新核心定义。
+
+**交叉引用完整性检查**（编译收尾）：出链回填 raw_sources + 入链保障（被链页面必须回链）+ linked_count 准确性 + 孤立节点显式提醒。
+
+**信息时间偏见防范**：不因新信息时间更新就认为更好；除非明确纠正错误，否则不降低旧信息权重。
+
+## Concept Independence Test
+
+创建新概念页前的强制门禁，防止过泛化、过特异化和组合概念。
+
+### 测试一：可定义性 + 单一核心
+
+1. 能否用一两句不含同义词循环的话，清晰陈述"这个概念是什么"？
+2. 该定义是否指向**单一核心**？检验：尝试拆解为"A 与 B"、"A 的 B"、"A 中的 B"。若 A 或 B 各自能独立通过可定义性测试，则为组合概念。
+
+正面示例："幸存者偏差"——拆解后各部分无法独立构成概念。
+反面示例："财富积累与人生算法"——可拆为"财富积累"和"人生算法"，两者均可独立定义。
+
+**不通过处理**：
+- 不满足可定义性 → 不创建页，信息归入上位概念
+- 不满足单一核心 → 拆分成独立概念分别创建或归入已有页
+
+### 测试二：多重验证
+
+该概念是否来自**至少两个不同 raw 笔记**的支撑，且有独立的论述角度（非同一篇文章重复剪藏）。
+
+**不通过处理**：不创建页，在相关概念页中标记 `<!-- 潜在独立概念：XXX -->`。
+
+## Concept Evolution
+
+wiki 概念页的核心机制，追踪观念生长全程。
+
+概念页标准结构：
+```markdown
+# {{概念名}}
+## 当前理解
+> 一句话核心定义
+## 阐述
+<!-- 整合自 raw 的理解，附 [[01 raw/...]] 出处 -->
+## 不同理解
+<!-- 冲突观点并列，附时间与出处 -->
+## 概念演化
+<!-- - (YYYY-MM) 旧理解摘要 [[01 raw/出处]] -->
+## 相关概念
+<!-- [[02 wiki/...]] 双向链接 -->
+```
+
+触发版本归档：新素材明确纠正旧事实错误 → 旧定义移入 `## 概念演化`，更新 `## 当前理解`。
+触发冲突记录：不同来源有不同理解且无法判定对错 → 列入 `## 不同理解`，并列呈现。
+
+## Metadata Completion
+
+编译前自动补全 raw 的 YAML frontmatter：
+
+| 字段 | 级别 | 规则 |
+|------|------|------|
+| `status` | 自动 | 缺失时设为 `processed`；已存在则不修改 |
+| `type` | 自动 | 缺失补 `source` |
+| `created` | 自动 | 缺失取文件系统创建时间 |
+| `source_url` | 推断 | 从正文查找链接补入 |
+| `title` | 推断 | 缺失则根据正文生成人类可读标题 |
+| `tags` | 推断 | 提取 2-4 个主题标签 |
+| 其他 | 手动 | 缺失不补 |
+
+外部渠道（剪藏、抓取）的无 YAML 笔记，编译前自动生成最小 YAML 块。
+
+## Filename Blocking
+
+编译时检测不可读文件名，防止污染知识库。
+
+触发条件：
+- 文件名含随机字符串（如 `clip_20260506_1423.md`）
+- 文件名与正文内容明显不符
+- 与已有文件名冲突
+
+阻断流程：停止处理 → YAML 写 `title: 建议标题` → 追加 `03 outputs/待确认文件名.md` → 提示用户 → 用户重命名后重新编译。
+
+## Health Check
+
+月度体检输出格式（`03 outputs/月度体检-YYYY-MM.md`）：
+
+```markdown
+# 月度体检报告 — YYYY-MM
+## 概念演化一览
+## 脆弱依赖
+## 孤岛节点
+## 时间提示
+## 建议行动
+- [ ] ...
+```
+
+定性使用影响力信息（核心概念/边缘概念），不列具体 linked_count 数值。
+
+## Context Discipline
+
+- 只加载当前命令所需的最小文件集合
+- 优先搜索再读取，不做全库全文装载
+- 若本地 `AGENTS.md` 已覆盖规则，不在 skill 中创造第二套规则
+- 输出简短、操作型，说明读取/更新了哪些文件
+
+## Refusal Rules
+
+- Bootstrap mode 下除 `/kb-init` 外拒绝所有命令
+- 拒绝未指定 raw 的旧式 ingest 请求，引导使用 `/wiki-compile`
+- 拒绝任何改写 raw 正文含义的请求
+- 拒绝把 `00 daily memo/` 当作编译或主题输入
+- `/wiki-topic` 若缺少合适主题且用户未明确要求新建，说明缺口并停止
+- `/wiki-lint` 只输出建议，绝不自动创建主题页
+
+## Context Loading Strategy
+
+- 永远先读本地 `AGENTS.md`
+- `/kb-init`：加载 default-schema + 模板文件
+- `/wiki-compile`：加载指定或候选 raw + 相关 wiki 概念页 + map 页 + log.md
+- `/wiki-topic`：加载对应 map 页 + 候选概念页 + 相关 raw（按需）
+- `/wiki-lint`：先搜索定位问题，按需打开少量文件，不做全库全文读取

package/skills/llm-wiki-stack/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "LLM Wiki Stack"
+  short_description: "Bootstrap and maintain an LLM-owned markdown wiki."
+  brand_color: "#0F766E"
+  default_prompt: "Use $llm-wiki-stack to initialize or maintain a raw-sources -> wiki -> schema knowledge base."
+
+policy:
+  allow_implicit_invocation: true

package/skills/llm-wiki-stack/assets/AGENTS.template.md

@@ -0,0 +1,93 @@
+# LLM Wiki Schema
+
+本仓库采用知识库编译器三层结构：
+
+- `raw sources`：`01 raw`
+- `wiki`：`02 wiki`
+- `outputs`：`03 outputs`
+- `schema`：本文件 `AGENTS.md`
+
+完整规则集参见 skill 内置的 `references/default-schema.md`。
+本文件仅定义项目特定配置和增量规则；通用 compile / topic / lint 工作流以 default-schema.md 为准。
+
+## 项目路径
+
+- `raw_root = 01 raw`
+- `wiki_root = 02 wiki`
+- `output_root = 03 outputs`
+- `template_root = 98 template`
+- `assets_root = _assets`
+
+## 项目特定规则
+
+以下规则是对 default-schema.md 的补充或覆盖，优先级高于 default-schema.md。
+
+### Raw Asset Rules
+
+带图片、截图、音频、附件等本地资源的 raw，统一使用库根 `_assets/` 作为资源根目录。
+
+- 本地资源统一保存到 `_assets/<raw 文件名去扩展名>/`
+- 禁止为 raw 新建同级 `*.assets/`、`assets/` 或 `_assets/` 子目录
+- raw 内本地图片链接必须使用从当前 raw 文件到库根 `_assets` 的相对路径
+- 编译收尾必须确认本次新增 raw 的本地图片链接全部解析到实际文件
+
+### Daily Memo Boundary
+
+`00 daily memo/**` 是独立模块，不属于 `raw sources`，也不属于 `wiki`。
+
+- 不要将 `00 daily memo` 视为编译输入
+- 不要在 `02 wiki` 中链接、引用或沉淀 `00 daily memo` 的内容
+- 不要把 `00 daily memo` 的页面登记到 wiki 的任何导航或索引中
+
+### Git Scope
+
+- 纳入 git：`01 raw/**`、`02 wiki/**`、`03 outputs/**`、`98 template/**`、`AGENTS.md`、必要的共享资源文件
+- 不纳入 git：`00 daily memo/**`、`.obsidian/**`、`.DS_Store`、`*.icloud`、`.wiki-kb/**`
+
+### Git Sync 约定
+
+实质变更后提交。commit message 格式：
+
+- `compile: <分区或主题>`
+- `topic: <主题名>`
+- `refactor: <页面或结构>`
+- `lint: <修复范围>`
+- `fix: <具体问题>`
+- `init: <初始化步骤>`
+
+提交粒度：一次知识库动作对应一次 commit。不要求把 commit hash 回写进页面。
+
+### 编译工作流（项目增量）
+
+在 default-schema.md 的编译流程之上：
+
+- 编译不在此阶段创建 outputs 页（那是 `/wiki-topic` 的职责）
+- 仅当 raw 满足"枢纽来源"条件且用户明确要求时，才创建单篇来源页
+- 若本次编译涉及本地图片或附件，先确认资源已保存到 `_assets/<raw 文件名去扩展名>/`
+
+### 主题页写作规则
+
+`02 wiki/` 下概念页默认按"可复用结论页"来写：
+
+- 语言风格：简练、客观、清晰，避免口语化废话和 AI 式套话
+- 优先输出压缩后的判断、优先级和取舍
+- 如果 raw 已提供具体数字、动作、例子，正文中至少吸收一个具体细节
+- 能明确判断时直接写结论，不默认做两边都讲的中性综述
+- 结构服务于内容，不为结构而结构
+
+### 单篇来源页例外条件
+
+以下情况可创建单篇来源页（需用户明确要求）：
+
+- raw 本身非常长，内部已有多个可复用子结构
+- 该 raw 预计会被高频反复引用
+- 该 raw 属于会持续编译的系列内容
+- 该 raw 能同时支撑多个概念页，具有"枢纽来源"角色
+
+### Query Workflow
+
+回答问题时优先使用 `02 wiki/` 概念页定位知识，再按需回读 raw。
+
+- 若 wiki 层已经覆盖问题，优先基于 wiki 回答
+- 若没有合适概念页，默认先停在 wiki 层；只有用户明确要求新建主题时，才通过 `/wiki-topic` 创建 outputs 页
+- 只有在 wiki 缺失或需要核对原文时，才回读 raw

package/skills/llm-wiki-stack/assets/concept.template.md

@@ -0,0 +1,31 @@
+---
+type: concept
+status: active
+created: {{DATE}}
+updated: {{DATE}}
+linked_count: 0
+raw_sources: []
+tags: []
+---
+
+# {{概念名}}
+
+## 当前理解
+
+> 一句话核心定义，随认知演化更新
+
+## 阐述
+
+<!-- 整合来自不同 raw 的理解，每条关键陈述附 [[01 raw/...]] 出处 -->
+
+## 不同理解
+
+<!-- 若存在观点冲突，并列不同来源的视角与时间 -->
+
+## 概念演化
+
+<!-- 格式：- (YYYY-MM) 旧理解摘要 [[01 raw/出处]] -->
+
+## 相关概念
+
+<!-- [[02 wiki/...]] 双向链接 -->

package/skills/llm-wiki-stack/assets/entity.template.md

@@ -0,0 +1,22 @@
+---
+type: entity
+status: active
+created: {{DATE}}
+updated: {{DATE}}
+raw_sources: []
+tags: []
+---
+
+# {{实体名}}
+
+## 基本信息
+
+<!-- 谁/什么、时间、关键属性 —— 事实性描述 -->
+
+## 相关素材
+
+<!-- [[01 raw/...]] 出处列表 -->
+
+## 相关概念
+
+<!-- [[02 wiki/...]] 链接到解释该实体的概念页 -->

package/skills/llm-wiki-stack/assets/health-report.template.md

@@ -0,0 +1,32 @@
+---
+type: health-report
+created: {{DATE}}
+tags:
+  - 月度体检
+  - 系统报告
+---
+
+# 月度体检报告 — {{YYYY-MM}}
+
+## 概念演化一览
+
+<!-- 本月发生理解更新的概念 -->
+
+## 脆弱依赖
+
+<!-- 03 outputs 中观点依赖低 linked_count 概念的情况 -->
+
+## 孤岛节点
+
+<!-- linked_count 为 0 或长期未被引用的 02 wiki 页面 -->
+
+## 时间提示
+
+<!-- 引用了已演化概念的 03 outputs 笔记 -->
+
+---
+
+## 建议行动
+
+- [ ] ...
+- [ ] ...

package/skills/llm-wiki-stack/assets/log.template.md

@@ -0,0 +1,18 @@
+---
+type: log
+status: active
+created: {{DATE}}
+updated: {{DATE}}
+raw_sources: []
+tags:
+  - llm-wiki-stack
+  - 日志
+---
+
+# LLM Wiki Log
+
+## [{{DATE}}] bootstrap | 初始化 wiki 骨架
+
+- 建立 `02 wiki` 的分区目录、map 页与日志结构。
+- 创建 `log.md` 与根目录 `AGENTS.md`。
+- 初始化本地知识库管理规则，并准备后续 compile / topic / lint 工作流。

package/skills/llm-wiki-stack/assets/output.template.md

@@ -0,0 +1,28 @@
+---
+type: output
+status: in-progress
+created: {{DATE}}
+tags: []
+---
+
+# {{主题名}}
+
+## 我的问题
+
+{{用户输入的研究问题}}
+
+---
+
+> 🤖 **初始分析**（LLM 基于 02 wiki 生成）
+
+---
+
+## 对话
+
+<!-- 用户与 LLM 持续交互，LLM 部分用 🤖 标记 -->
+
+---
+
+## ✍️ 我的综合判断
+
+<!-- 思考成熟后写下最终观点 -->

package/skills/llm-wiki-stack/commands.md

@@ -0,0 +1,35 @@
+# llm-wiki-stack Command Manifest
+
+Framework: `llm-wiki-stack`
+
+## Spec Mapping
+
+| 命令 | 规格书动作 |
+|------|-----------|
+| `/kb-init` | `🏗️ 初始化知识库` |
+| `/wiki-compile` | `🔄 编译新素材` |
+| `/wiki-topic` | `🧠 新建主题` |
+| `/wiki-lint` | `🏥 月度体检` |
+
+（`📄 新建源笔记` 由 Obsidian QuickAdd + 模板完成，非 LLM 命令）
+
+## Command Adapters
+
+- `kb-init` -> bootstrap workflow
+- `wiki-compile` -> compilation pipeline
+- `wiki-topic` -> topic workflow (outputs layer)
+- `wiki-lint` -> lint + health check workflow
+
+## Rule Hierarchy
+
+1. repo-local `AGENTS.md`
+2. `llm-wiki-stack/SKILL.md`
+3. `llm-wiki-stack/references/default-schema.md`
+
+## Interpretation Rules
+
+- 这些 wrapper 属于同一个知识库管理框架，不是彼此独立的 skill。
+- wrapper 不定义自己的 schema；它们只把用户请求映射到 core skill 的某一个命令入口。
+- 若 wrapper 文案与 core skill 或 repo-local `AGENTS.md` 冲突，以更高层规则为准。
+- `/wiki-compile` 是唯一将 raw 编译进 wiki 的入口，不再有独立的 lightweight ingest。
+- `/kb-init` 是编排入口：初始化骨架后复用 core `/wiki-compile` 流水线编译全部合格 raw，并用 `/wiki-lint` 机械检查作为完成门禁；不得调用 `/wiki-topic` 生成初始化报告。

package/skills/llm-wiki-stack/references/default-schema.md

@@ -0,0 +1,273 @@
+# Default Schema
+
+本文件定义 `llm-wiki-stack` 在 bootstrap mode 下使用的默认知识库规则。
+
+当 repo-local `AGENTS.md` 不存在时：
+- `/kb-init` 以本文件作为默认 profile
+- 其他日常动作不得继续执行，应提示先初始化
+
+## Architecture
+
+三层编译器架构：
+
+```
+01 raw/  ──编译──>  02 wiki/  ──对话──>  03 outputs/
+(不可变源)           (概念网络)            (个人观点)
+```
+
+- **L1 raw**：源笔记，LLM 只读正文，可按权限规则修改 YAML frontmatter
+- **L2 wiki**：概念页，LLM 维护，追踪概念演化
+- **L3 outputs**：观点主题页 + 系统报告，用户主导，LLM 辅助
+
+## Default Paths
+
+- `raw_root = 01 raw`
+- `wiki_root = 02 wiki`
+- `output_root = 03 outputs`
+- `template_root = 98 template`
+- `assets_root = _assets`
+
+## Bootstrap
+
+`/kb-init` 假定用户只有大模型和一个目录，必须先做 dependency doctor：
+
+- 检查 `git`、`rg`、基础 shell 工具和当前目录写权限
+- `git` 与写权限为必需项；缺失时请求授权安装或提示用户处理
+- `rg` 为推荐项；缺失时可回退到 `grep/find`
+
+初始化流程：
+
+1. 创建 `01 raw/`、`02 wiki/`、`03 outputs/`、`98 template/`
+2. 用模板生成 `AGENTS.md`、`02 wiki/log.md`
+3. 若 `01 raw/` 下存在 raw 文件，扫描并生成 `03 outputs/初始化提案.md`（列出建议创建的 wiki 概念页、重要度、链接关系）
+4. **等待用户审阅确认**初始化提案
+5. 用户确认后，调用 `/wiki-compile` 核心流水线，并传入全部合格 raw 文件的显式列表；`/kb-init` 不另写编译逻辑
+6. 建立或补齐全局索引页和分区 map 页，确保概念页可从索引导航到达
+7. 调用 `/wiki-lint` 机械检查作为完成门禁：未编译 raw、断链、frontmatter、raw_sources、双向回链、linked_count 和孤立节点必须检查
+8. 输出 `03 outputs/初始化完成报告.md`，记录 raw 总数、已编译数、跳过项及原因、概念页数、map 页数和 lint 门禁结果
+9. 初始化 git 和 `.gitignore`
+
+## Page Types
+
+wiki 和 outputs 页面统一使用最小 frontmatter：
+
+| type | 所在层 | 说明 |
+|------|--------|------|
+| `source` | raw | 源笔记 |
+| `entity` | wiki | 实体页——具体的人、组织、产品、岗位等可指名事物 |
+| `concept` | wiki | 概念页——跨实体提炼的框架、原理、模式 |
+| `map` | wiki | 分区导航页，簇识别与入口路由 |
+| `log` | wiki | 追加式操作日志 |
+| `output` | outputs | 观点主题页，question-driven 对话 |
+| `health-report` | outputs | 月度体检报告 |
+
+### concept 页 frontmatter
+
+```yaml
+type: concept
+status: active
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+linked_count: 0
+raw_sources: []
+tags: []
+```
+
+linked_count 记录被其他 wiki 页和 outputs 页引用的次数，LLM 编译和创建主题时更新。
+
+### entity 页 frontmatter
+
+```yaml
+type: entity
+status: active
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+raw_sources: []
+tags: []
+```
+
+实体页记录具体事物的事实信息（谁/什么、时间、关键属性），通过 `## 相关素材` 链接 raw 出处，`## 相关概念` 链接到解释该实体的概念页。实体页不包含 `## 当前理解` 和 `## 概念演化`——那是概念页的职责。
+
+### output 页 frontmatter
+
+```yaml
+type: output
+status: in-progress
+created: YYYY-MM-DD
+tags: []
+```
+
+## Raw Boundary
+
+- 允许：移动目录、重命名文件、按主题重组层级
+- 禁止：修改正文、增删原文段落、改写原始摘录含义
+- 如需补充结构化信息，只写到 `02 wiki`
+
+## Permission Model
+
+raw 笔记采用三级权限：
+
+| 区域 | 权限 | 说明 |
+|------|------|------|
+| 正文（标题、`## 即时思考`、`## 原文`） | **只读** | LLM 绝不修改 |
+| YAML frontmatter | **可写，分级** | 见下方字段表 |
+| 文件名 | **可建议** | LLM 仅可建议，不直接修改 |
+
+### YAML 字段处理规则
+
+| 字段 | 类型 | 处理 |
+|------|------|------|
+| `status` | 自动 | 缺失时设为 `processed`；已存在则不修改 |
+| `type` | 自动 | 缺失时填入 `source` |
+| `created` | 自动 | 缺失时取文件系统创建时间 |
+| `source_url` | 推断 | 从正文查找链接补入 |
+| `title` | 推断 | 缺则根据正文生成人类可读标题 |
+| `tags` | 推断 | 提取 2-4 个主题标签 |
+| 其他 | 手动 | 缺失不补，不猜测 |
+
+来自外部渠道（剪藏、抓取）的无 YAML 笔记，LLM 在编译开始前自动生成最小 YAML 块并补全上述字段。
+
+## Compilation Workflow (`/wiki-compile`)
+
+`🔄 编译新素材` 是唯一将 raw 编译进 wiki 的入口，替代旧的 lightweight ingest 模式。
+
+流程：
+
+**文件选择**：
+- 若用户指定了 raw 文件路径，直接编译
+- 若由 `/kb-init` 调用，使用初始化阶段扫描并经用户确认的全部合格 raw 文件显式列表；只跳过交互式候选选择，不跳过后续编译门禁
+- 若未指定，检测未编译 raw：收集 wiki 概念页 raw_sources 中已引用的路径，扫描 `01 raw/` 全量，找出不在已编译集合中的文件，呈现候选列表供用户确认
+- 若候选列表为空，提示"当前无未编译 raw 文件"并退出
+
+流程（对每个待编译文件）：
+1. **文件名阻断检查**：文件名含随机字符串、与正文内容明显不符、或与已有文件冲突时，停止处理该文件，写入 `title: 建议标题` 到其 YAML，追加记录到 `03 outputs/待确认文件名.md`，提示用户处理后重新编译
+2. **元数据补全**：按 Permission Model 规则补全缺失的 YAML 字段，正文永不修改
+3. **实体提取**：从 raw 中提取关键实体和概念
+4. **概念独立性测试**：创建新概念页前必须通过可定义性、单一核心和多重验证；单来源候选不创建独立页，只进入相关概念页或报告说明
+5. **wiki 页创建/更新**，对每个实体/概念：
+   - 无对应 wiki 页则基于 `concept.template.md` 创建
+   - 已存在则默认**补充**新信息至 `## 阐述`，不覆盖 `## 当前理解`
+   - **只有新信息明确纠正旧事实错误**时，将旧定义追加到 `## 概念演化`：`- (YYYY-MM) 旧理解摘要 [[01 raw/出处]]`，再更新 `## 当前理解`
+   - **观点冲突**：列入 `## 不同理解`，并列双方时间与出处，不判定对错
+6. 每条关键陈述附 `[[01 raw/...]]` 出处链接
+7. 建立 wiki 间 `[[02 wiki/...]]` 双向链接
+8. 交叉引用完整性检查：正文 raw 链接回填到 `raw_sources`，相关概念获得回链，`linked_count` 等于实际入链数
+9. 更新受影响 wiki 页的 `linked_count`（=入链数）和 `updated`
+
+编译完成后提交 git。
+
+## Concept Evolution
+
+wiki 概念页追踪观念生长全程，不覆盖历史。
+
+**页面结构**：
+
+```markdown
+# {{概念名}}
+
+## 当前理解
+> 一句话核心定义，随认知演化更新
+
+## 阐述
+<!-- 整合来自不同 raw 的理解，每条关键陈述附 [[01 raw/...]] 出处 -->
+
+## 不同理解
+<!-- 若存在观点冲突，并列不同来源的视角与时间 -->
+
+## 概念演化
+<!-- - (YYYY-MM) 旧理解摘要 [[01 raw/出处]] -->
+
+## 相关概念
+<!-- [[02 wiki/...]] 双向链接 -->
+```
+
+**版本归档触发条件**：新素材明确纠正了旧事实错误。
+**冲突记录触发条件**：不同来源对同一概念有不同理解，且无法判定对错。
+
+默认假设新信息为补充，不因时间新就认为更好。
+
+## Filename Blocking
+
+防止随机 ID 文件名污染知识库。
+
+触发条件（任一）：
+- 文件名含随机字符串（如 `clip_20260506_1423.md`）
+- 文件名与正文内容明显不符
+- 与已有文件名冲突
+
+阻断流程：
+1. `/wiki-compile` 发现此类文件，停止处理
+2. 在该 raw 的 YAML 写入 `title: 建议标题`
+3. 追加记录到 `03 outputs/待确认文件名.md`
+4. 提示用户："有 N 个文件待确认文件名，请处理后重新运行编译"
+5. 用户处理完毕后再次触发编译，LLM 检查通过后继续
+
+## Influence Weight
+
+通过 `linked_count` 追踪概念被引用次数，定性区分核心与边缘。
+
+- LLM 编译时更新受影响 wiki 页的 `linked_count`
+- 在 outputs 对话和体检报告中定性使用：`被 outputs/ 引用` → 核心概念；`linked_count 低` → 边缘概念
+- 默认不进行 PageRank 式递归计算，保持简单
+
+## Health Check (`/wiki-lint`)
+
+`🏥 月度体检` 目标：全库健康检查 + 结构化报告。
+
+检查项：
+- **断链**：所有 `[[...]]` 目标文件是否存在
+- **孤儿页**：wiki 概念页是否被其他页面引用
+- **空目录**：wiki、raw、outputs 下的空目录
+- **frontmatter 完整性**：wiki/outputs 页面是否有 type/status/created/updated
+- **linked_count 一致性**：声明的 linked_count vs 实际引用数
+- **raw_sources 回填状态**：概念页正文引用了 raw 但 frontmatter raw_sources 为空
+- **未编译 raw**：raw 文件未被任何 wiki 概念页的 raw_sources 引用
+
+当 `/wiki-lint` 作为 `/kb-init` 完成门禁调用时，只执行机械检查和低风险自动修复；语义合并、主题创建和破坏性结构清理不得自动执行。
+
+输出格式 `03 outputs/月度体检-YYYY-MM.md`，使用 `- [ ]` 任务列表：
+
+- **概念演化一览**：本月发生理解更新的概念
+- **脆弱依赖**：outputs 中观点依赖低 linked_count 概念的情况
+- **孤岛节点**：linked_count 为 0 的 wiki 概念页
+- **时间提示**：引用了已演化概念的 outputs 笔记
+
+报告中定性使用影响力信息，不列具体数值。只输出建议，绝不自动创建主题页。
+
+## Topic Workflow (`/wiki-topic`)
+
+`🧠 新建主题` 是 question-driven 的观点形成流程，写入 `03 outputs/`。
+
+流程：
+1. 用户提出一个**问题**（非概念列表）
+2. LLM 读取相关 wiki 概念，生成 `🤖 初始分析`（含来源标注）
+3. 用户在 `对话` 区持续追问、质疑、引导，LLM 回应（均用 `🤖` 标记）
+4. 用户自行在 `✍️ 我的综合判断` 写下结论
+5. 相关 wiki 链接自动建立，`linked_count` 增加
+
+LLM 权限：
+- 可写入 `🤖 初始分析` 和对话区自己的回复
+- 对话区用户内容、`✍️ 我的综合判断` 只读
+- 不替用户做综合判断
+
+## Git Sync
+
+实质变更后提交，不再有 off/major/on 模式切换。
+
+实质变更定义：
+- 发生了文件或目录的创建、删除、移动、重命名
+- 修改命中了 `01 raw/**` 或 `02 wiki/**` 或 `03 outputs/**` 下的内容
+- 结构初始化或 schema 级改动
+
+不算实质变更：
+- 纯错字修复
+- 单页轻微措辞调整
+
+commit message 格式：`ingest: <分区>`, `compile: <主题>`, `refactor: <范围>`, `lint: <范围>`, `fix: <问题>`
+
+## Linking Rules
+
+- raw 与 wiki 的关联统一用 Obsidian 链接维护
+- 概念页必须列出 `raw_sources`，并在正文中链接关键来源
+- 命名使用中文优先；概念页不带时间戳
+- wiki 概念页之间通过 `## 相关概念` 双向链接

package/skills/wiki-compile/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: wiki-compile
+description: Subcommand of the `llm-wiki-stack` knowledge-base management framework. Compile user-specified or uncompiled raw files into the wiki layer with concept evolution, metadata completion, and linked_count tracking. Use when the user wants to run `/wiki-compile` or `🔄 编译新素材`.
+---
+
+# Wiki Compile
+
+## Framework Binding
+
+- This skill is one command adapter in the `llm-wiki-stack` framework.
+- It does not define its own schema or workflow; it delegates to `../llm-wiki-stack/SKILL.md`.
+- Repo-local `AGENTS.md` overrides both the core framework and this wrapper.
+
+- This skill is a thin wrapper around `llm-wiki-stack`.
+- First read `../llm-wiki-stack/SKILL.md` and follow the `/wiki-compile` command path only.
+- Treat the user request as an explicit `/wiki-compile` invocation.
+- Run the full compilation pipeline: determine target files (user-specified or auto-detect uncompiled) → filename check → metadata completion → entity extraction → concept independence test → wiki page creation/update with concept evolution → cross-reference integrity check → linked_count maintenance.

package/skills/wiki-lint/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: wiki-lint
+description: Subcommand of the `llm-wiki-stack` knowledge-base management framework. Lint an Obsidian knowledge base for orphan pages, duplicate topics, missing backlinks, misplaced raw files, empty source-index entries, and similar structural issues. Use when the user wants to run `/wiki-lint` directly.
+---
+
+# Wiki Lint
+
+## Framework Binding
+
+- This skill is one command adapter in the `llm-wiki-stack` framework.
+- It does not define its own schema or workflow; it delegates to `../llm-wiki-stack/SKILL.md`.
+- Repo-local `AGENTS.md` overrides both the core framework and this wrapper.
+
+- This skill is a thin wrapper around `llm-wiki-stack`.
+- First read `../llm-wiki-stack/SKILL.md` and follow the `/wiki-lint` command path only.
+- Treat the user request as an explicit `/wiki-lint` invocation.
+- Auto-fix low-risk mechanical issues (broken links, missing frontmatter); for semantic merges or destructive structural cleanup, follow the guardrails defined in the core skill.
+- When user requests "月度体检" or "health check", generate a structured health report at `03 outputs/月度体检-YYYY-MM.md` with sections: concept evolution, fragile dependencies, orphan nodes, time hints, and suggested actions.
+- Only output suggestions; never auto-create topic pages.

package/skills/wiki-lint/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "Wiki Lint"
+  short_description: "Lint wiki structure and fix low-risk issues."
+  brand_color: "#0F766E"
+  default_prompt: "Use $wiki-lint to lint the current LLM wiki and fix low-risk structural issues."
+
+policy:
+  allow_implicit_invocation: true
+

package/skills/wiki-topic/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: wiki-topic
+description: Subcommand of the `llm-wiki-stack` knowledge-base management framework. Query, synthesize, create, or update a topic page inside an Obsidian knowledge base. Use when the user wants to run `/wiki-topic` directly to update a topic page, infer a topic target, or create a new reusable topic page when explicitly needed.
+---
+
+# Wiki Topic
+
+## Framework Binding
+
+- This skill is one command adapter in the `llm-wiki-stack` framework.
+- It does not define its own schema or workflow; it delegates to `../llm-wiki-stack/SKILL.md`.
+- Repo-local `AGENTS.md` overrides both the core framework and this wrapper.
+
+- This skill is a thin wrapper around `llm-wiki-stack`.
+- First read `../llm-wiki-stack/SKILL.md` and follow the `/wiki-topic` command path only.
+- Treat the user request as an explicit `/wiki-topic` invocation.
+- New topic pages go into `03 outputs/` with `type: output`. Use question-driven flow: user asks a question → LLM provides initial analysis → dialogue → user writes judgment.
+- Resolve the target topic according to the core skill rules: prefer an explicit page, then an inferred reusable page, and only create a new page when an existing one cannot naturally absorb the content.

package/skills/wiki-topic/agents/openai.yaml

@@ -0,0 +1,9 @@
+interface:
+  display_name: "Wiki Topic"
+  short_description: "Update or create a reusable topic page."
+  brand_color: "#0F766E"
+  default_prompt: "Use $wiki-topic to update or create a topic page in the current LLM wiki."
+
+policy:
+  allow_implicit_invocation: true
+