内容
# 打造属于自己的 WIKI
<img width="1672" height="941" alt="ChatGPT Image Jun 22, 2026, 01_55_25 AM" src="https://github.com/user-attachments/assets/5e5243b5-9614-4f5d-9cc2-b54b492a8fe8" />
将网络、文件和零散的笔记转化为一个**个人 WIKI**，由 LLM 代理保持一致性：搜索和总结页面，将它们吸收到上下文向量索引中，进行基础的、引用的问答，并建立一个分层的知识图谱，消除重复的实体，构建主题，并编写综合页面。一个 Flask 应用 — Web UI、JSON API 和 `runner.py` CLI。灵感来自 LangChain 的 *llm-wiki* 深度代理示例，但它构建的是私有的、磁盘上的库，而不是同步到中心。<br>**本地优先**：每个存储都是 `data/` 下的纯 JSON/SQLite；云存储是可选的。<br>**在线演示**：https://byo-wiki-demo.onrender.com
## 功能特点
- **智能知识图谱** — 一个 [`deepagents`](https://pypi.org/project/deepagents/) 代理（本地文件系统后端，无云沙盒）保存段落，提取实体和类型化关系，规范化重复项，嵌套主题，并编写综合页面。
- **上下文 RAG** — 类似 Anthropic 的*上下文检索*，通过两层 HNSW 索引（章节摘要 + 块），使用 LLM 重新排序器（精度）或文档感知 MMR（多文档召回）。答案有据可查。
- **记忆** — 跨会话存储，在每次回答**之前**回忆，**之后**写入（观察， 👍/👎，纠正取代过时的笔记）；它通过使用而非仅通过摄入而改进。
- **代理技能** — 将选定的上下文转化为可重复使用的、**评估过的**技能，通过子代理管道（理解 → 分析 → 作者 → 评估 → 门控 → 改进）。由最新的 Claude 进程或通过 **Claude Code CLI 作为子进程**编写，由确定性 + 评分标准面板评估，并**在人工审查后**加入库 — 可选地作为持久的**LangGraph**构建，在门控处暂停，稍后继续。
- **MCP，双向** — 连接代理到外部 MCP 服务器（Supabase、GitHub、…）并运行 BYO-WIKI **作为** MCP 服务器。读取加入代理；**写入默认拒绝**。
## 架构
```mermaid
flowchart TB
subgraph IF["接口"]
direction LR
UI["Web UI · Flask"]
API["JSON API · /api"]
CLI["CLI · runner.py"]
end
ING["摄入管道<br/>获取 · 清洁 · 上下文摘要<br/>分块 · 嵌入 · 实体 / 关系 / 主题提取"]
subgraph STORE["存储 · 本地优先 data/"]
direction LR
KG[("知识图谱 · 层 0–5<br/>来源 · 章节 · 块<br/>实体 · 主题 · 综合")]
VEC[("HNSW 索引<br/>章节摘要 + 块")]
MEM[("记忆 · 层 6")]
SKL[("技能库 · 层 7")]
end
subgraph REASON["推理"]
direction LR
RAG["上下文 RAG<br/>检索 → 重新排序 / MMR → 引用"]
AGENT["策划代理 · deepagents<br/>摄入 · 查询 · 清理"]
SKILL["代理技能循环 · LangGraph<br/>作者 → 评估 → 门控 → 人工审查"]
end
IF --> ING
IF --> REASON
ING --> KG
ING --> VEC
VEC --> RAG
RAG --> EMB["嵌入 · OpenAI"]
RAG <--> MEM
KG <--> AGENT
AGENT <--> MEM
AGENT <--> MCP["外部 MCP 服务器<br/>Supabase · GitHub · 获取<br/>读取加入代理 · 写入门控"]
SKILL --> SKL
SKILL --> KG
SKILL --> MCP
REASON --> LLM["LLM 提供商<br/>Claude · OpenAI · Qwen<br/>DeepSeek · Gemini · Mistral"]
REASON -.->|离线指标| EVAL["评估<br/>命中率@k · MRR · 召回率<br/>RAGAS · 5 家裁判小组"]
REASON -.->|实时运行轨迹| OBS["可观察性<br/>LangSmith · OpenTelemetry"]
```
存储层以上的所有内容都是无状态的；所有状态都存放在 `data/`（JSON 图、HNSW 向量、SQLite 检查点），因此应用程序是可复制的且本地优先。JSON API 也可以**作为** MCP 服务器暴露（读取开放，写入默认拒绝）。
**评估和可观察性是不同的平面 — 不要混淆它们。** *评估*衡量**离线**的质量：确定性检索指标（命中率@k · MRR · 召回率），**RAGAS**（忠实度 · 答案相关性 · 上下文精度，作为 LangSmith 评估器封装在 `ragas_eval.py` 中），以及 5 家 LLM 裁判小组校准为人类标签。*可观察性*跟踪**实时**运行 — 代理、RAG 和技能构建 — 到 **LangSmith** 和可选的 **OpenTelemetry**。RAGAS 是一个评估器，而不是跟踪器。
### 策略代理的工作原理
一个 [`deepagents`](https://pypi.org/project/deepagents/) 代理驱动四个模式（`init · ingest · query · lint`）作为递归限制的推理↔行动循环，适用于本地文件系统后端。其工具读取和写入知识图谱，在答案**之前**回忆记忆，在答案**之后**写入，看起来技能，并调用外部 MCP **读取**工具。<br>`query` 通过上下文 RAG 确立引用的答案；`ingest`/`lint` 规范化重复项，嵌套主题，并编写综合页面。
```mermaid
flowchart TB
subgraph DRIVE["入口 · Web UI · /api · runner.py"]
direction LR
INIT["init<br/>搭建"]
INGEST["ingest<br/>组织新材料"]
QUERY["query<br/>引用答案"]
LINT["lint<br/>维护库"]
end
DRIVE --> REASON
subgraph LOOP["deepagents · 本地文件系统后端"]
REASON["推理 ↔ 行动循环<br/>(递归限制)]
KGRW["知识图谱工具<br/>搜索 · 插入 · 合并<br/>关联 · 嵌套主题 · 综合"]
MEMT["记忆工具<br/>回忆前 · 写入后"]
SKT["技能查找"]
MCPR["MCP 读取工具"]
REASON <--> KGRW
REASON <--> MEMT
REASON <--> SKT
REASON <--> MCPR
end
KGRW <--> KG[("知识图谱<br/>层 0–5")]
MEMT <--> MEM[("记忆 · 层 6")]
QUERY -.->|确立答案| RAG["上下文 RAG<br/>检索 → 重新排序 / MMR"]
RAG --> VEC[("HNSW 索引")]
RAG --> KG
```
### 技能构建作为持久的 LangGraph 运行
技能循环有两个可互换的运行时，适用于相同的阶段函数：线性进程管道（`SKILL_BACKEND=pipeline`），或 LangGraph `StateGraph`（`skill_graph.py`），它添加了条件门控，一个持久的人工审查**中断（）**，以及检查点（SQLite / Postgres / 内存）。每个阶段都由进程内或 **Claude Code CLI 作为子进程**编写（`generate_cc`）。门控永远不会单独完成 — 它将草稿放入`pending_review`；只有人类才能促进它。在门控处暂停，检查点，并通过`thread_id`在另一个进程中恢复。每个构建/评估/改进都跟踪到 LangSmith（父运行 + 每个阶段的子运行）和可选的 OpenTelemetry。
```mermaid
stateDiagram-v2
direction TB
[*] --> gather
gather --> understand: backend = pipeline
gather --> generate_cc: backend = claude_code
understand --> analyze
analyze --> codeact
codeact --> evaluate
generate_cc --> evaluate
evaluate --> human_review: 通过门控，待人工审查
evaluate --> [*]: 拒绝
human_review --> finalize: 接受
human_review --> prepare_revision: 修订 + 注释
human_review --> [*]: 拒绝
prepare_revision --> codeact: 管道
prepare_revision --> generate_cc: claude_code
finalize --> [*]
note right of evaluate
确定性检查（11）
+ 5 家评分小组
end note
note right of human_review
中断（）暂停 + 检查点
（SQLite / Postgres / 内存）
通过 thread_id 恢复，生存重启
end note
```
## 快速开始
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt # 添加 `ragas` 以获取 RAGAS 指标
cp .env.example .env # 设置至少一个提供者密钥
python app.py # → http://localhost:5000
```
`app.py` 和 `runner.py` 都自动加载 `.env`。<br>**RAG 需要 `OPENAI_API_KEY`** 用于嵌入（`text-embedding-3-small`），无论聊天提供者如何 — Anthropic 没有嵌入 API。
## 工作原理（关键部分）
**图谱是分层的，不是扁平的实体袋。** 节点通过类型化边（`mentions`、`relation`、`belongs_to`、`subtopic_of`，...）爬升 `source → section → chunk → entity → topic → synthesis → memory → agent_skill`（层 0–7）。KG 选项卡渲染三个粒度（文档 / 章节 / 块）。
**检索仅基于向量 — 故意如此。** 每个章节都有一个由 LLM 编写的上下文摘要；块嵌入 `title · date · section` 前置到两层 HNSW 索引中。检索排名章节，钻入块，然后重新排序器 **或** MMR 选择 top-k。<br>**实体图遍历已构建、评估并移除** — MMR 在**召回率**和**综合质量**上击败了它。图谱在**构建**（规范化、主题、来源）和**呈现**（概念图）中发挥作用，而不是在检索中。
**技能受到门控。** 起草的技能必须通过确定性检查（可用描述，≥2 步，正面 **和** 负面触发器，声明的工具，无占位符）和跨家族评判小组 — 但门控永远不会单独完成：它将草稿放入 `pending_review`，只有**人类**才能促进它。每个构建/评估/改进都记录了每个阶段的计时、令牌和触发精度/召回率；`refine` 从其测量的弱点重建技能。可选地作为 LangGraph `StateGraph` 运行，其中人工审查是持久的**中断（）** — 在门控处暂停，检查点，在另一个进程中恢复。
## 评估
所有数字都来自一个版本控制的 28 文档语料库（`eval/corpus_urls.txt`，LangChain + Anthropic 文章）。确定性检索指标在运行间最具可比性；绝对 LLM 裁判分数依赖于裁判，因此使用 **5 家裁判小组**（`gpt-5.2 · qwen3.7-plus · deepseek-v4-flash · gemini-3.5-flash · mistral-large-2512`）并报告相对于人类标签的`judge_alignment`。
| 设置 | 指标 | 结果 |
| --- | --- | --- |
| 单文档，重新排序 | 命中率@6 / MRR | 0.87 / 0.81 |
| 关闭重新排序 → 打开 | RAGAS 上下文精度 | 0.51 → 0.67 |
| 跨文档，基线 → MMR | 检索召回率 | 0.59 → **0.91** |
| 跨文档，MMR vs. 图谱-RAG | 检索召回率 | **0.909** vs. 0.788 |
| 跨文档，综合提示修复 | RAGAS 答案相关性 | 0.65 → **0.90** |
MMR 在召回率 **和** 综合质量上获胜，因此图谱-RAG 被淘汰；相关性提升来自让生成器跨段落综合，而不是拒绝当没有单个块声明连接时。
## 接口
**Web UI** — 选项卡用于读取（搜索 / 获取 + 提取 / 总结 / 保存到知识图谱）、知识图谱（摄入，浏览分层图谱，集成 / 提问 / 维护）、库 Q&A（引用答案，重新排序/MMR 切换）、记忆和代理技能（构建，观察评估/门控报告，接受/修订/拒绝；切换 **持久 ⛓** 以获取检查点 LangGraph 构建）。
**HTTP API** — 在 `/api` 下：`read` · `kg` · `agent` · `memory` · `rag` · `skill` · `mcp`.
**CLI** (`runner.py --mode …`)：
```bash
init · ingest · query · lint # 知识图谱工作区
memory-add · memory-recall · memory-list # 跨会话记忆
skill-build · skill-pending · skill-review · skill-refine · skill-observability
skill-graph-build · skill-graph-resume # 持久，暂停审查构建
rag-ingest · rag-ask · rag-eval · rag-experiment · rag-ragas · rag-crossdoc
mcp-list · mcp-ingest · mcp-call · mcp-serve # MCP 客户端 + 服务端
```
常见标志： `--provider`、`--model`、`--rerank/--no-rerank`、`--mmr`、`--no-agent`.
## 快速预览
Web UI 正在运行 — 每个选项卡一张图片。
**读取** — 搜索 / 获取 + 提取 / 总结 / 保存到知识图谱。
**缓存** — 在知识图谱、问答和记忆之间重用提取的内容，无需重新获取。
**知识图谱** — 摄入，浏览分层图谱，集成 / 提问 / 维护。
**记忆** — 跨会话存储，在每次答案之前回忆，并在之后写入。
**代理技能** — 构建，观察评估/门控报告，接受/修订/拒绝。
## 连接工具（MCP）
代理可以调用外部 MCP 服务器，并且 BYO-WIKI 可以运行为一个 — 都是可选且本地优先的。使用 `MCP_ENABLED` 启用服务器；读取工具加入策划代理和技能构建器，并且 `mcp-ingest` 阶段将读取工具的输出阶段到知识图谱中。<br>**写入默认拒绝**：写入仅通过 `/api/mcp/write`（或 `mcp-call --confirm`）并使用 `MCP_ALLOW_WRITES=1` **和** 显式人类批准运行，并且客户端门控跟踪服务器自己的 `read_only` 范围，以便两者永远不会漂移。托管的 Supabase MCP 是 HTTPS，因此即使直接 Postgres 被阻止，它也有效。
```bash
pip install langchain-mcp-adapters mcp
export MCP_ENABLED=supabase SUPABASE_ACCESS_TOKEN=… SUPABASE_PROJECT_REF=…
python runner.py --mode mcp-list
```
查看 `docs/mcp-proposal.md` 以获取完整设计。
## 配置
提供者密钥位于 `.env`（gitignored — 永远不要提交真实密钥）；请参阅 `.env.example` 以获取完整列表。常见额外功能：
| 变量 | 用途 |
| --- | --- |
| `LANGSMITH_TRACING` / `LANGSMITH_API_KEY` | 启用 + 验证 LangSmith 跟踪/评估。 |
| `KG_DATA_DIR` | 存储目录（默认 `data/`）。 |
| `SKILL_GATE_ACCEPT` / `SKILL_GATE_REJECT` / `SKILL_DET_PASS` | 技能门控阈值。 |
| `SKILL_BACKEND` | 技能生成器：`pipeline`（进程内）或 `claude_code`（CLI 子进程）。 |
| `SKILL_GRAPH_CHECKPOINT` | LangGraph 检查点：`sqlite`（默认）/ `postgres` / `memory`。 |
| `MCP_ENABLED` / `MCP_ALLOW_WRITES` | 启用外部 MCP 服务器；允许（门控）写入。 |
| `PORT` | 绑定端口（默认 5000）。 |
## 项目布局```
app.py / runner.py Flask 应用（UI + API）/ CLI
agent.py kg_tools.py deepagents 套件 + 图谱工具
knowledge_graph.py 多层图谱存储 + 查询
ingestion.py extraction.py enrich.py 分块 · 实体/关系/主题提取
pipeline.py embeddings.py vectorstore.py 上下文摄入 + HNSW + MMR
rag.py rag_experiment.py ragas_eval.py crossdoc.py 检索、答案、评估套件
memory.py memory_tools.py 会话记忆（层 6）
skill_*.py 代理技能构建循环，评估/门控，可观察性，LangGraph（层 7）
mcp_config.py mcp_tools.py mcp_server.py MCP 客户端（门控）+ BYO-WIKI 作为 MCP 服务器
providers.py config.py 提供者表 + 判选择；.env / LangSmith
eval/ static/ templates/ data/ 语料库 + 数据集；UI；本地存储
```
## 致谢
灵感来自 LangChain 的 *llm-wiki* 深度代理示例。构建使用 Flask，`deepagents`/LangChain，`hnswlib`，OpenAI 嵌入，RAGAS 和 LangSmith。 </content>
