llmwiki-suite 0.1.0__tar.gz

llmwiki_suite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

llmwiki_suite-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+recursive-include docs *.md

llmwiki_suite-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: llmwiki-suite
+Version: 0.1.0
+Summary: LLM-compiled personal wiki toolkit: BM25 + wikilink-graph recall, lint, and chat channels over plain Markdown notes.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: wechat
+Requires-Dist: fastapi>=0.110; extra == "wechat"
+Requires-Dist: uvicorn>=0.29; extra == "wechat"
+Dynamic: license-file
+
+# llmwiki-suite
+
+把一堆 Markdown 笔记编成「会生长、能问答」的个人知识库。
+
+源自 Karpathy 的 LLM-wiki 思路：不做每次查询临时切片的 RAG，而是用工具链
+**持续编译**笔记——补 frontmatter、建 BM25 + wikilink 图索引、巡检断链，
+最后通过 CLI 或微信通道问答。
+
+> **包名 vs 命令名**：PyPI 发布名为 **`llmwiki-suite`**（`llmwiki` 这个包名已被其他项目占用），
+> 安装后执行命令仍然是 **`llmwiki`** —— 即「装的是 `llmwiki-suite`，用的是 `llmwiki`」。
+
+## 安装
+
+> 发布状态：尚未上 PyPI，以下 `pip install` 均从 GitHub 直装（`main` 分支最新）。
+> 从 GitHub 直装时，`[wechat]` extra **不会自动带上** fastapi/uvicorn，跑渠道必须显式写 `[wechat]`。
+
+```bash
+# 二选一，不必两条都装：
+#   只用 ingest / index / query / lint / eval（核心，零依赖）→ 装第 1 条即可
+#   要跑微信/企业微信渠道（核心 + fastapi/uvicorn）→ 装第 2 条，它已包含核心
+
+# ① 核心（零依赖，纯标准库）
+pip install "llmwiki-suite @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# ② 微信/企业微信通道（在核心之上额外装 fastapi + uvicorn；已含核心，无需再装①）
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+```
+
+要求 Python >= 3.11。
+
+### 本地开发安装（源码）
+
+```bash
+git clone https://github.com/voidvec/llmwiki-suite.git
+cd llmwiki-suite
+pip install -e .                 # 或带微信通道：pip install -e ".[wechat]"
+```
+
+## 五步接入你已有的笔记库
+
+```bash
+cd ~/my-notes          # 1. 进入你的笔记目录
+llmwiki init           # 2. 生成 llmwiki.toml 配置模板
+llmwiki ingest         # 3. 补 frontmatter + 规范化 wikilink
+llmwiki index          # 4. 建检索索引
+llmwiki query "..."    # 5. 检索 / 问答
+```
+
+可选：`llmwiki lint`（巡检断链/词表）、`llmwiki eval`（评估召回质量）、
+`llmwiki serve`（启动 HTTP 问答服务，需 `wechat` extras）。
+
+## 命令一览
+
+| 命令 | 作用 |
+|------|------|
+| `llmwiki init` | 在目标库生成 `llmwiki.toml` 模板 + 脚手架（.gitignore / pre-commit / CI） |
+| `llmwiki ingest` | 扫描笔记，补齐 frontmatter，规范化 wikilink 命名 |
+| `llmwiki index` | 生成 BM25 + wikilink 图检索索引（`kb-index.json`） |
+| `llmwiki query "..."` | 召回最相关章节；配置 `LLM_WIKI_API_KEY` 后生成完整回答 |
+| `llmwiki lint` | 巡检：断链、词表越界、命名规范 |
+| `llmwiki eval` | 用内置评估集跑 recall@k / MRR |
+| `llmwiki serve` | 启动 FastAPI 桥接服务（`/chat` `/recall` `/healthz`） |
+
+所有命令支持 `--repo <path>` 显式指定库路径（默认取当前目录）。
+
+## 微信渠道接入（个人微信 / 企业微信）
+
+用 `llmwiki serve` 把知识库接到微信，直接发消息问答：
+
+```bash
+# ① 前提：必须装带 wechat extra 的包（核心安装不含 fastapi/uvicorn）
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# ② 配置 LLM（OpenAI 兼容端点；只设 KEY 时默认走 OpenAI）
+export LLM_WIKI_API_KEY="sk-xxx"
+export LLM_WIKI_BASE_URL="https://api.openai.com/v1"        # 不设则默认 OpenAI
+export LLM_WIKI_MODEL="gpt-4o-mini"                          # 不设则默认 gpt-4o-mini
+
+export LLM_WIKI_BRIDGE_TOKEN="my-secret"       # 建议：保护 /chat、/recall
+llmwiki serve --host 127.0.0.1 --port 8000
+```
+
+- **个人微信（推荐，免费官方 iLink 通道）**：浏览器打开
+  `http://127.0.0.1:8000/ilink/webui` → 手机微信扫码 → 绑定成功后
+  直接在微信里给 bot 发消息即查即答。
+- **企业微信**：配置 `LLM_WIKI_WECOM_*` 环境变量后自动启用回调 / 主动推送通道。
+
+### 换 LLM 厂商 / 模型（OpenAI 兼容协议即可）
+
+套件只调 OpenAI 兼容的 `/chat/completions`，**不看厂商名**——任何提供该协议的服务都能用：
+
+| 厂商 | `LLM_WIKI_BASE_URL` | `LLM_WIKI_MODEL` |
+|------|---------------------|------------------|
+| OpenAI（默认） | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
+| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
+| Kimi / Moonshot | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
+| 本地 Ollama | `http://127.0.0.1:11434/v1` | `qwen2.5:7b`（API_KEY 随便填） |
+
+> 换厂商只需把上面三个变量一起设；只有 OpenAI 时只用 `LLM_WIKI_API_KEY` 即可。
+> 支持任意 **OpenAI `/chat/completions` 兼容**的第三方服务（DeepSeek / 通义 / Kimi / 本地 Ollama / vLLM 等），
+> 完整对接步骤、会话持久化与排错，详见 [[llmwiki-tutorial-02-channel]]。
+
+## 配置与密钥
+
+- **库配置**：库根 `llmwiki.toml`（categories 词表、排除目录、模型名等非密钥项）
+- **密钥**：只走环境变量（`LLM_WIKI_API_KEY`、`LLM_WIKI_BRIDGE_TOKEN`、
+  `LLM_WIKI_WECOM_*`、`LLM_WIKI_ILINK_*`），本套件不读取任何 `.env` 文件
+
+## 文档
+
+全部文档在 `docs/`，按「入口 → 进阶 → 参考」组织：
+
+| 文档 | 说明 |
+|------|------|
+| `docs/getting-started.md` | **入口**：五步接入已有笔记库（10 分钟上手） |
+| `docs/llmwiki-tutorial-01-system.md` | 体系搭建完整教程：目录规范、Ingest / Query / Lint、自动化 |
+| `docs/llmwiki-tutorial-02-channel.md` | 渠道接入：微信 / 企业微信桥接、serve 部署 |
+| `docs/llmwiki-tutorial-03-quality-tuning.md` | 检索质量调优：评估集、诊断、调参 |
+| `docs/llmwiki-architecture.md` | 系统架构：分层设计、通道抽象 |
+| `docs/obsidian-guide.md` | 可选：用 Obsidian 作为前端编辑器 |
+| `docs/pypi-release-guide.md` | 维护者：发布到 PyPI 的操作指南（注册/2FA/Token/twine） |
+
+建议顺序：getting-started → tutorial-01 → 02/03（按需）→ architecture。
+
+## License
+
+MIT

llmwiki_suite-0.1.0/README.md

@@ -0,0 +1,128 @@
+# llmwiki-suite
+
+把一堆 Markdown 笔记编成「会生长、能问答」的个人知识库。
+
+源自 Karpathy 的 LLM-wiki 思路：不做每次查询临时切片的 RAG，而是用工具链
+**持续编译**笔记——补 frontmatter、建 BM25 + wikilink 图索引、巡检断链，
+最后通过 CLI 或微信通道问答。
+
+> **包名 vs 命令名**：PyPI 发布名为 **`llmwiki-suite`**（`llmwiki` 这个包名已被其他项目占用），
+> 安装后执行命令仍然是 **`llmwiki`** —— 即「装的是 `llmwiki-suite`，用的是 `llmwiki`」。
+
+## 安装
+
+> 发布状态：尚未上 PyPI，以下 `pip install` 均从 GitHub 直装（`main` 分支最新）。
+> 从 GitHub 直装时，`[wechat]` extra **不会自动带上** fastapi/uvicorn，跑渠道必须显式写 `[wechat]`。
+
+```bash
+# 二选一，不必两条都装：
+#   只用 ingest / index / query / lint / eval（核心，零依赖）→ 装第 1 条即可
+#   要跑微信/企业微信渠道（核心 + fastapi/uvicorn）→ 装第 2 条，它已包含核心
+
+# ① 核心（零依赖，纯标准库）
+pip install "llmwiki-suite @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# ② 微信/企业微信通道（在核心之上额外装 fastapi + uvicorn；已含核心，无需再装①）
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+```
+
+要求 Python >= 3.11。
+
+### 本地开发安装（源码）
+
+```bash
+git clone https://github.com/voidvec/llmwiki-suite.git
+cd llmwiki-suite
+pip install -e .                 # 或带微信通道：pip install -e ".[wechat]"
+```
+
+## 五步接入你已有的笔记库
+
+```bash
+cd ~/my-notes          # 1. 进入你的笔记目录
+llmwiki init           # 2. 生成 llmwiki.toml 配置模板
+llmwiki ingest         # 3. 补 frontmatter + 规范化 wikilink
+llmwiki index          # 4. 建检索索引
+llmwiki query "..."    # 5. 检索 / 问答
+```
+
+可选：`llmwiki lint`（巡检断链/词表）、`llmwiki eval`（评估召回质量）、
+`llmwiki serve`（启动 HTTP 问答服务，需 `wechat` extras）。
+
+## 命令一览
+
+| 命令 | 作用 |
+|------|------|
+| `llmwiki init` | 在目标库生成 `llmwiki.toml` 模板 + 脚手架（.gitignore / pre-commit / CI） |
+| `llmwiki ingest` | 扫描笔记，补齐 frontmatter，规范化 wikilink 命名 |
+| `llmwiki index` | 生成 BM25 + wikilink 图检索索引（`kb-index.json`） |
+| `llmwiki query "..."` | 召回最相关章节；配置 `LLM_WIKI_API_KEY` 后生成完整回答 |
+| `llmwiki lint` | 巡检：断链、词表越界、命名规范 |
+| `llmwiki eval` | 用内置评估集跑 recall@k / MRR |
+| `llmwiki serve` | 启动 FastAPI 桥接服务（`/chat` `/recall` `/healthz`） |
+
+所有命令支持 `--repo <path>` 显式指定库路径（默认取当前目录）。
+
+## 微信渠道接入（个人微信 / 企业微信）
+
+用 `llmwiki serve` 把知识库接到微信，直接发消息问答：
+
+```bash
+# ① 前提：必须装带 wechat extra 的包（核心安装不含 fastapi/uvicorn）
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# ② 配置 LLM（OpenAI 兼容端点；只设 KEY 时默认走 OpenAI）
+export LLM_WIKI_API_KEY="sk-xxx"
+export LLM_WIKI_BASE_URL="https://api.openai.com/v1"        # 不设则默认 OpenAI
+export LLM_WIKI_MODEL="gpt-4o-mini"                          # 不设则默认 gpt-4o-mini
+
+export LLM_WIKI_BRIDGE_TOKEN="my-secret"       # 建议：保护 /chat、/recall
+llmwiki serve --host 127.0.0.1 --port 8000
+```
+
+- **个人微信（推荐，免费官方 iLink 通道）**：浏览器打开
+  `http://127.0.0.1:8000/ilink/webui` → 手机微信扫码 → 绑定成功后
+  直接在微信里给 bot 发消息即查即答。
+- **企业微信**：配置 `LLM_WIKI_WECOM_*` 环境变量后自动启用回调 / 主动推送通道。
+
+### 换 LLM 厂商 / 模型（OpenAI 兼容协议即可）
+
+套件只调 OpenAI 兼容的 `/chat/completions`，**不看厂商名**——任何提供该协议的服务都能用：
+
+| 厂商 | `LLM_WIKI_BASE_URL` | `LLM_WIKI_MODEL` |
+|------|---------------------|------------------|
+| OpenAI（默认） | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| DeepSeek | `https://api.deepseek.com/v1` | `deepseek-chat` |
+| 通义千问 | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen-plus` |
+| Kimi / Moonshot | `https://api.moonshot.cn/v1` | `moonshot-v1-8k` |
+| 本地 Ollama | `http://127.0.0.1:11434/v1` | `qwen2.5:7b`（API_KEY 随便填） |
+
+> 换厂商只需把上面三个变量一起设；只有 OpenAI 时只用 `LLM_WIKI_API_KEY` 即可。
+> 支持任意 **OpenAI `/chat/completions` 兼容**的第三方服务（DeepSeek / 通义 / Kimi / 本地 Ollama / vLLM 等），
+> 完整对接步骤、会话持久化与排错，详见 [[llmwiki-tutorial-02-channel]]。
+
+## 配置与密钥
+
+- **库配置**：库根 `llmwiki.toml`（categories 词表、排除目录、模型名等非密钥项）
+- **密钥**：只走环境变量（`LLM_WIKI_API_KEY`、`LLM_WIKI_BRIDGE_TOKEN`、
+  `LLM_WIKI_WECOM_*`、`LLM_WIKI_ILINK_*`），本套件不读取任何 `.env` 文件
+
+## 文档
+
+全部文档在 `docs/`，按「入口 → 进阶 → 参考」组织：
+
+| 文档 | 说明 |
+|------|------|
+| `docs/getting-started.md` | **入口**：五步接入已有笔记库（10 分钟上手） |
+| `docs/llmwiki-tutorial-01-system.md` | 体系搭建完整教程：目录规范、Ingest / Query / Lint、自动化 |
+| `docs/llmwiki-tutorial-02-channel.md` | 渠道接入：微信 / 企业微信桥接、serve 部署 |
+| `docs/llmwiki-tutorial-03-quality-tuning.md` | 检索质量调优：评估集、诊断、调参 |
+| `docs/llmwiki-architecture.md` | 系统架构：分层设计、通道抽象 |
+| `docs/obsidian-guide.md` | 可选：用 Obsidian 作为前端编辑器 |
+| `docs/pypi-release-guide.md` | 维护者：发布到 PyPI 的操作指南（注册/2FA/Token/twine） |
+
+建议顺序：getting-started → tutorial-01 → 02/03（按需）→ architecture。
+
+## License
+
+MIT

llmwiki_suite-0.1.0/docs/RELEASE.md

@@ -0,0 +1,62 @@
+---
+title: "发布检查清单（Pre-Release Checklist）"
+description: "llmwiki-suite 发布 PyPI 前的核名、构建、安装链路验证记录（M6 后半）"
+created: "2026-08-24"
+status: "checklist"
+---
+
+# 发布检查清单（Pre-Release Checklist）
+
+> 对应 S2 里程碑 M6 后半：`pip install git+file://` 直装验证 + PyPI 发布名最终核名。
+
+## 1. PyPI 发布名核名（2026-08-24 最终确认）
+
+| 候选名 | 状态 | 证据 |
+|--------|------|------|
+| `llmwiki` | ❌ 已被占用 | PyPI 已存在 v0.9.0（Hosuke 的 LLMBase） |
+| `llmwiki-cli` | ❌ 已被占用 | 已被 ktrysmt 占用 |
+| **`llmwiki-suite`** | ✅ **可发布** | `https://pypi.org/project/llmwiki-suite/` → 404；JSON API `https://pypi.org/pypi/llmwiki-suite/json` → `{"message": "Not Found"}` |
+
+- 发布名：**`llmwiki-suite`**，CLI 命令仍为 `llmwiki`（见 README「包名 vs 命令名」）。
+- PyPI 项目注册采用**先发布后核名**流程：实际占用发生在上传 wheel 时，因此发布名以本次核名为准，`twine upload` 前若冲突需再核。
+
+## 2. 构建产物验证（sdist + wheel）
+
+```bash
+python -m build
+```
+
+产物：
+- `dist/llmwiki_suite-0.1.0.tar.gz`（48 文件，含 6 篇 docs + scaffold 2 文件 + README）
+- `dist/llmwiki_suite-0.1.0-py3-none-any.whl`（26 文件）
+
+关键内容断言（wheel）：
+- `llmwiki/channels/*`：channel_base / ilink_adapter / wechat_bridge / wecom_adapter / wecom_crypto ✅
+- `llmwiki/data/scaffold/.pre-commit-config.yaml` ✅（M6 打包修复：隐藏文件显式入包）
+- `llmwiki/data/templates/` + `eval_queries.json` ✅
+
+## 3. 分发链路验证（clean venv）
+
+| 验证项 | 命令 | 结果 |
+|--------|------|------|
+| wheel 安装 | `pip install dist/llmwiki_suite-0.1.0-py3-none-any.whl` | ✅ CLI 可用 `llmwiki --version` → 0.1.0 |
+| 五步工作流 | `init → ingest --apply → index → query --recall-only → eval` | ✅ 全通（脚手架正确落到测试库，`.pre-commit-config.yaml` 来自 wheel 内 data） |
+| wechat extras | `pip install "llmwiki-suite[wechat]"` | ✅ fastapi 0.141.1 / uvicorn 0.52.4 |
+| serve 端点 | `/healthz`、`/recall`(POST)、`/chat`(POST) | ✅ 均 200；`/recall` 返回候选含 `index_stale:null`；无 LLM 密钥时 `/chat` 降级为片段预览 |
+| git 检出源码树安装 | `git clone <repo> && pip install .` | ✅ 构建 wheel + 安装成功（等价 GitHub 直装链路） |
+
+### 已知平台限制（非缺陷）
+
+**Windows 下 `pip install git+file:///D:/...` 不可用**：pip 会把 `file://` URL 的盘符转小写（`d:/`），Git for Windows 无法解析小写盘符路径，报
+`fatal: '/d:/...' does not appear to be a git repository`。此为 pip + Git-for-Windows 的已知组合问题，与套件本身无关。真实 GitHub 直装走 `git+https://`，Windows 下无此问题。
+
+## 4. 回归基线
+
+- 套件 testkb：`recall@4 = 100%`，`MRR@4 = 1.0`（与 P5 基线一致，M6 零行为变化）
+- 个人知识库 57 条评估集：`recall@4 = 100%`，`MRR@4 = 0.9605`（P5 后基线）
+
+## 5. 发布前待办（后续）
+
+1. 配置套件仓库 GitHub remote（当前无 remote，所有提交都在本地 main）；
+2. `twine check dist/*` + `twine upload`（需 PyPI 账号令牌，走 CI 优先）；
+3. GitHub 直装 `pip install git+https://github.com/<org>/llmwiki-suite.git` 实测（跨平台最接近真实用户路径）。

llmwiki_suite-0.1.0/docs/getting-started.md

@@ -0,0 +1,173 @@
+---
+title: "Getting Started：五步接入你已有的笔记库"
+description: "llmwiki-suite 的快速上手入口：装包 → init → ingest → index → query。把任意 Markdown 笔记目录变成可检索、可问答、可自维护的个人知识库。"
+categories: ['知识库规范']
+tags:
+  - llmwiki
+  - getting-started
+  - tutorial
+difficulty: "beginner"
+estimated_time: "10分钟"
+created: "2026-08-24"
+updated: "2026-08-24"
+version: "1.0"
+---
+
+# 五步接入你已有的笔记库
+
+> 目标：**`pip install` 后指向你的笔记目录，五步内完成接入**：装包 → init → ingest → query →（可选）接通道。
+
+---
+
+## 第 0 步：安装
+
+> 当前发布状态：**套件尚未推送到 PyPI**（核名已确认 `llmwiki-suite` 可发布，待正式发布）。
+> 因此其他电脑/用户的接入，从 GitHub 直装即可：可装最新 main，且升级即 `pip install --upgrade`（或带 `@<commit/tag>` 锁版本）。
+
+```bash
+# 二选一（不必两条都装）：
+#   - 只用 query/lint/eval 等核心 → 装下面第 1 条；
+#   - 要跑微信/企业微信渠道 → 装第 3 条（[wechat]，已含核心 + fastapi/uvicorn）。
+
+# 1) 核心（零依赖，纯标准库）—— 从 GitHub 直装（main 分支最新）
+pip install "llmwiki-suite @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# 2) 锁定某个已验证版本（推荐给远端用户）：直接安装某个 commit 的源码
+pip install "git+https://github.com/voidvec/llmwiki-suite.git@7be91c9"
+
+# 3) 需要微信/企业微信通道时（额外装 fastapi + uvicorn）【必须显式写 [wechat]】
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+```
+
+要求 Python ≥ 3.11（内置 `tomllib` 的下限）。安装后命令是 **`llmwiki`**（注意：包名是 `llmwiki-suite`，PyPI 上 `llmwiki` 已被其他项目占用）。
+
+> **Windows 注意事项**：不要用 `git+file:///D:/...` 本地盘符直装——pip 会把盘符转小写导致 Git 无法解析（已知平台缺陷）。必须走 `git+https://` 或先 `git clone` 再 `pip install .`。
+
+若仓库公开，别的电脑无需账号直接可装；若日后改为私有，远端需先配置 GitHub 认证（`gh auth login` 或 SSH key，并用 `git+ssh://git@github.com/voidvec/llmwiki-suite.git`）。
+
+验证：
+
+```bash
+llmwiki --help
+```
+
+---
+
+## 第 1 步：进入你的笔记目录并初始化
+
+```bash
+cd ~/my-notes            # 你的 Markdown 笔记目录（新建或已有都行）
+llmwiki init             # 生成 llmwiki.toml + 拷入脚手架（.gitignore/pre-commit/CI）
+```
+
+`llmwiki init` 会：
+
+- 生成 `llmwiki.toml`（三层配置：套件默认 < 本文件 < 环境变量，密钥只走环境变量）；
+- 拷入 `.gitignore` 片段（忽略 `kb-index.json` 等产物）、`.pre-commit-config.yaml`、GitHub Actions lint 工作流；
+- 在库根 `templates/` 放入**会议纪要 / 读书笔记两份通用模板**。
+
+> `llmwiki.toml` 不配也能跑（纯默认）；想定制受控词表 / 排除目录 / LLM 模型时再编辑它。
+
+---
+
+## 第 2 步：归一并建索引（把 Markdown 变成可检索结构）
+
+```bash
+llmwiki ingest            # 先 dry-run 预览（补 frontmatter / 归一文件名 / 查重）
+llmwiki ingest --apply    # 确认后真正写入
+llmwiki index             # 建 BM25 + wikilink 图索引 → kb-index.json
+```
+
+- `ingest` 是**行级编辑**：补缺失的 frontmatter、把 `Weekly_会议纪要.md` 归一为 `weekly-meeting.md`，绝不整篇重写。
+- `index` 后产物：`kb-index.json`（检索索引）+ `category-index.md`（自动分类导航页）。
+
+---
+
+## 第 3 步：查询你的知识库
+
+```bash
+llmwiki query "本周例会行动项"                 # 召回 + LLM 生成完整回答
+llmwiki query "本周例会行动项" --recall-only  # 仅看召回候选（不调 LLM，离线调试）
+llmwiki query "哪个文档讲 BM25" --top-k 4     # 显式控制候选数
+```
+
+- 配了 `LLM_WIKI_API_KEY`（OpenAI 兼容端点）→ 返回带来源引用的回答。
+- 没配 → 返回「检索片段预览」，**离线也能联调**。
+
+```bash
+# 一键巡检知识库健康度（断链 / frontmatter / 词表）
+llmwiki lint
+```
+
+---
+
+## 第 4 步（可选）：接入微信 / 企业微信
+
+```bash
+pip install "llmwiki-suite[wechat] @ git+https://github.com/voidvec/llmwiki-suite.git"
+cd ~/mykb
+# 指定 LLM（OpenAI 兼容端点）。只设 key 时默认走 OpenAI gpt-4o-mini；
+# 换 DeepSeek/通义/Kimi/Ollama 等只需把 base_url + model 一起设（详见 tutorial-02 §2.1）
+export LLM_WIKI_API_KEY="sk-xxx"        # 建议；不设则降级预览
+export LLM_WIKI_BASE_URL="https://api.openai.com/v1"   # 可选；默认 OpenAI
+export LLM_WIKI_MODEL="gpt-4o-mini"     # 可选；默认 gpt-4o-mini
+export LLM_WIKI_BRIDGE_TOKEN="my-secret"# 建议：保护 /chat /recall
+llmwiki serve --host 127.0.0.1 --port 8000
+```
+
+- 浏览器打开 `http://127.0.0.1:8000/ilink/webui` → 手机微信扫码 → 绑定个人微信 bot；
+- 之后在微信里直接给 bot 发文本，即查即答。
+- 企业微信、LLM 厂商切换、排错等详见 [[llmwiki-tutorial-02-channel]]。
+
+---
+
+## 在另一台电脑 / 别人的机器上接入（远端消费方）
+
+> 适用：新机器、同事/朋友的知识库，与第 0～4 步完全一致的 CLI，唯一差异在**安装来源**。
+
+```bash
+# 1. 环境
+python -m venv .venv && source .venv/bin/activate    # Linux/macOS
+# 或 Windows: python -m venv .venv; .venv\Scripts\activate
+pip install "llmwiki-suite @ git+https://github.com/voidvec/llmwiki-suite.git"
+
+# 2. 进入他们已有的笔记目录（git 仓库或裸目录均可）
+cd ~/their-notes
+llmwiki init          # 生成 llmwiki.toml + 拷脚手架（已有不覆盖）
+llmwiki ingest        # 先 dry-run 预览，再 --apply 真正写入
+llmwiki index         # 建 kb-index.json
+llmwiki query "随便问"   # 检索/问答
+llmwiki lint          # 健康巡检
+llmwiki serve         # 要跑 HTTP 服务时（需 [wechat] extras）
+```
+
+要点：
+
+| 事项 | 说明 |
+|------|------|
+| **任意数量/任意位置** | 套件是「指向库」的 CLI，不是绑死库路径；`--repo <path>` 可切换到任何库，或 `cd` 进库直接用 |
+| **Python ≥ 3.11** | 唯一硬依赖（内置 `tomllib`） |
+| **配置不落地** | `llmwiki.toml` 随库走；密钥只读环境变量，绝不写进笔记仓库 |
+| **私有仓库反向依赖** | 套件公开可直装；若套件仓库设为私有，远端需配认证（SSH key / `gh auth login`）后改用 `git+ssh://`，或为机器单独签发只读 token |
+| **CI/pre-commit** | `llmwiki init` 拷入的 `.github/workflows/kb-lint.yml` 与 `.pre-commit-config.yaml` 已内置上游安装命令，双端（新建/既有仓库）共用 |
+| **其它库迁移历史** | 别的库没有 `_deprecated/` 那些旧引擎，无需迁移；**不存在「必须带旧文件才能跑」** |
+| **升级** | 改完套件跑 `pip install --upgrade "llmwiki-suite @ git+https://..."` 即升级到最新 main |
+
+---
+
+## 3 条铁律（避免踩坑）
+
+1. **改文档后必重建索引**：新增 / 修改任一篇 `.md` 后跑 `llmwiki index`，否则新内容不进入召回。
+2. **密钥只走环境变量**：`LLM_WIKI_API_KEY` / `LLM_WIKI_BRIDGE_TOKEN` / `LLM_WIKI_WECOM_*` / `LLM_WIKI_ILINK_*`，套件不读任何 `.env`。
+3. **别乱建游离分类**：`categories` 必须落在 `llmwiki.toml` 词表内，否则 `lint` 报 error。
+
+---
+
+## 相关文档
+
+- [[remote-onboarding]]（另一台电脑 / 别人的知识库接入：安装、五步、多库/多用户、升级与私有化）
+- [[llmwiki-tutorial-01-system]]（体系搭建完整教程：目录规范、Ingest/Query/Lint、自动化）
+- [[llmwiki-tutorial-02-channel]]（渠道接入：微信 / 企业微信）
+- [[llmwiki-tutorial-03-quality-tuning]]（检索质量调优：评估、诊断、调参）
+- [[llmwiki-architecture]]（系统架构：分层 + 通道抽象）
+- [[obsidian-guide]]（可选：用 Obsidian 作为前端编辑器）