lumina-wiki

v0.8.1

Published

10 hours ago

Domain-agnostic, multi-IDE wiki scaffolder — Karpathy's LLM-Wiki vision, cross-platform and pack-based.

0High
0Medium
0Low

luutronghieu

llm-wiki knowledge-base wiki ai claude-code codex obsidian scaffolder karpathy

Lumina-Wiki

Where Knowledge Starts to Glow.
专为技术研究设计的 LLM 维护型知识库。

1. 核心工作流

Lumina-Wiki 遵循一个简单的原则：将您的原始资料与 AI 的结构化知识分开。

+-------------------------+      /lumi-ingest      +---------------------------+
|      您的输入            | ---------------------> |      AGENT 的大脑         |
|      (raw/ 文件夹)       |                        |      (wiki/ 文件夹)       |
|                         | <--------------------- |                           |
|  - my-paper.pdf         |       /lumi-ask        |  - my-paper.md (摘要)     |
|  - my-notes.txt         |                        |  - concept-a.md           |
+-------------------------+                        +---------------------------+

您提供： 将您的文档（PDF、笔记）放入 raw/ 目录。
Agent 构建： 在 AI 聊天中使用指令（如 /lumi-ingest）让 Agent 读取 raw/ 内容，并在 wiki/ 目录中构建一个结构化、互相关联的维基。
您查询： 针对 wiki/ 中 Agent 的“大脑”进行提问（使用 /lumi-ask），获得更快、更具上下文感知能力的回答。

2. 快速开始

第一步：安装

在当前项目中使用一条指令安装维基工作区：

npx lumina-wiki install

Windows 用户注意： 为了获得最佳体验，建议开启开发者模式，以便安装程序正确使用符号链接。如果开发者模式关闭，安装程序将退而使用文件复制，虽然功能正常，但不利于后续更新。

安装程序将引导您进行快速设置，包括选择可选的 Packs（如 research 和 reading）。

第二步（可选）：配置 Research Pack

如果您安装了 research 包，某些技能需要 API 密钥才能进行在线搜索。请在 AI 聊天窗口中运行设置技能进行配置：

您： /lumi-research-setup

Agent 将引导您通过交互式设置将密钥保存到本地 .env 文件中。

第三步（升级时）：迁移旧版 Wiki 条目

如果您在已经有 wiki/ 的旧项目上重新安装 Lumina-Wiki，照常运行安装器：

npx lumina-wiki install

安装器检测到版本升级后会原子性地更新 scripts、schemas 和 skills。您的 wiki 内容（wiki/、raw/、log.md）不会被安装器修改。 当安装器发现新版本添加的 frontmatter 字段在旧条目中缺失时，会打印 [warn] 横幅，显示数量和下一步操作。

您有两种方式进行回填：

方案 A — LLM 驱动（推荐）： 打开 AI 聊天并运行：

您： /lumi-migrate-legacy

方案 B — 快速确定性回填： 从终端运行：

node _lumina/scripts/wiki.mjs migrate --add-defaults

此命令为所有缺失字段的条目设置保守的默认值（provenance: missing，confidence: unverified）。lint 立即变绿，但值只是占位符 — 您可以稍后通过方案 A 或手动编辑来优化。

您可以组合使用：先运行方案 B 让 lint 变绿，需要更准确的值时再运行方案 A。两种方式都是原子写入并在 wiki/log.md 留下记录。

完整的版本 schema 变更列表请见 CHANGELOG.md 或安装后的本地副本 _lumina/CHANGELOG.md。

3. 常用指令（核心技能 Core Skills）

在您的 AI 聊天界面（Gemini CLI, Claude 等）中使用这些指令与维基进行交互。

第一阶段：导入与构建

/lumi-init: 扫描 raw/ 目录并执行维基的首次构建。
/lumi-ingest [path/to/file]: 处理单个新文档并将其集成到知识库中。

第二阶段：查询与维护

/lumi-ask [您的提问]: 针对 wiki/ 中的整个知识库进行提问。
/lumi-edit [path/to/wiki/page]: 要求对特定的维基页面进行修改或更正。
/lumi-check: 检查维基是否存在错误（死链等）。

如果您安装了可选包如 research 或 reading，还会有更多可用技能。

4. 工作区目录指南

Lumina 创建的工作区为每个目录都设定了明确的用途。

主要文件夹（您的日常工作区）

系统文件夹（由 Lumina 管理）

| 路径 | 用途 | 管理方 | | :--- | :--- | :--- | | _lumina/ | 维基的核心引擎、脚本和配置。 | 系统 | | .agents/ | 包含 Agent 可以使用的所有 skills（技能）。 | 系统 | | ... | (其他点文件如 .claude/, .gitignore) | 系统 |

注意： 您通常不需要修改系统文件夹。

使用 Obsidian 浏览您的 Wiki（可选）

Obsidian 是与 Lumina-Wiki 配合使用的推荐可视化工具。由于 Wiki 使用原生 Obsidian [[wikilinks]] 语法，您无需额外配置即可获得完整的图谱视图、反向链接面板和属性查询功能。

将 Vault 指向项目根目录 — 而非仅指向 wiki/ 子文件夹。项目根目录包含 index.md、log.md，以及 wiki/ 页面与 raw/ 原始文件之间的交叉链接——只有当 Obsidian 能同时访问两个目录时，这些链接才能正确解析。

运行 npx lumina-wiki install 后的推荐配置：

Obsidian → Open folder as vault → 选择项目根目录。
Settings → Files & links → Excluded files — 添加：
- _lumina/, .claude/, .cursor/, .agents/, .git/, wiki/graph/
- 重定向到 README.md 的 Agent 入口 stub 文件：CLAUDE.md、AGENTS.md、GEMINI.md、QWEN.md — 它们仅指向 README.md，若保留会在图谱视图中产生空节点。保留 README.md 本身：它是规范的 Schema 参考文档。
Settings → Files & links：
- Use [[Wikilinks]]：开启
- New link format：Shortest path when possible
- Default attachment location：In the folder specified below → raw/assets/
建议开启的核心插件： Graph view、Backlinks、Outgoing links、Tags、Properties、Outline。
（可选） 社区插件 Dataview — 允许按 frontmatter 字段（如 type、importance、confidence、date_added）查询页面。

wiki/graph/ 文件夹包含 edges.jsonl 和 citations.jsonl（机器可读数据文件，非 Markdown）。排除该文件夹可保持图谱视图整洁。

使用 qmd 进行本地搜索（可选）

随着您的 Wiki 不断增长，您可能希望获得比 index.md + grep 更快的全文搜索体验。我们推荐 qmd —— 一个完全本地、设备上的 Markdown 搜索引擎，结合 BM25、向量搜索和 LLM 重排序。qmd 与 Lumina-Wiki 和您的 AI Agent 配合得非常顺畅。

如何与 AI Agent 集成：

按照 qmd 仓库中的说明安装，然后对项目根目录建立索引，使 qmd 能同时看到 wiki/ 和 raw/。
CLI 方式 — Agent 可以通过 Bash 调用 qmd <query>。只需在提示中提及该命令已可用。
MCP 方式（在 Claude Code、Codex、Cursor 中很方便） — 在 IDE 的 MCP 配置中注册 qmd 的 MCP 服务器。Agent 会将其识别为原生工具，可以从 /lumi-ask 或后续提问中调用。
在每次 /lumi-ingest 后重新索引（手动或通过 hook），让新页面可被搜索到。

qmd 与 index.md 和 wiki 图谱并行工作 —— 作为一个快速检索层，在 Agent 完整阅读页面之前为它提供更好的候选结果。

额外推荐 —— tobi 的官方 qmd skill。 tobi 还发布了一个专用 skill，教您的 Agent 如何高效使用 qmd（何时选择 lex vs vec vs hyde、如何编写 intent 进行消歧、lex 短语与排除项语法）。如果您的 IDE 支持 skill 格式，可以通过以下命令安装：

npx skills add https://github.com/tobi/qmd --skill qmd

建议先阅读 skills.sh 上的 skill 页面，了解它具体添加了什么。

5. 可用技能与工具 (v0.1)

技能 (用户指令)

这些是您在与 AI 聊天时可以使用的指令。

工具 (底层引擎)

这些是 Agent 技能用于执行操作的脚本。

6. 未来规划

当前版本为 v0.2 (预览版)。完整计划位于 ROADMAP.md。核心项：

v1.0.0 — 首个稳定版

每日搜索与获取 — 观察列表查询 (_lumina/config/watchlist.yml) 定期运行；新的 arXiv / Semantic Scholar 结果自动进入 raw/discovered/<date>/。
新的 /lumi-daily 技能，用于分类自上次运行以来新增的内容。
v0.1 版本的稳定性锁定（CLI 标志、退出代码、Schema 字段名）。
跨平台 CI 矩阵（macOS + Linux + Windows, Node 20 + 22）。

v2.0.0 — Research Pack 来源扩展

新论文来源： OpenAlex, Unpaywall, CORE (优先级 1) → OpenReview, Hugging Face Papers, Papers With Code (优先级 2) → Crossref, DOAJ, 研究博客 RSS (优先级 3)。
论文排名： 新的 /lumi-rank 技能，在论文的 frontmatter 中显示影响力引用数、领域标准引用排名、Scite 支持/对比统计以及 Altmetric 关注度。

想要帮忙吗？ 选择 ROADMAP.md 中任何未勾选的项目，开一个 Issue 申领，然后发送 PR。所有来源获取程序在 src/tools/ 中都遵循相同的模式（CLI + JSON, 无 async, 退出代码 0/2/3），非常适合作为首次贡献。请参阅下方的本地开发步骤。

7. 贡献与许可

🛠️ 本地开发 (针对贡献者)

如果您想为 lumina-wiki 安装程序本身做出贡献：

# 1. 克隆并安装依赖
git clone https://github.com/tronghieu/lumina-wiki.git
cd lumina-wiki
npm ci

# 2. 运行测试
npm run test:all