内容
# 构建你自己的 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 应用 — 网页 UI、JSON API 和 `runner.py` CLI。灵感来自 LangChain 的 *llm-wiki* 深度代理示例，但它构建了一个私有的、磁盘上的库，而不是同步到中心。<br />**本地优先**：每个存储都是 `data/` 下的纯 JSON/SQLite；云是可选的。
## 功能
- **智能知识图谱** — 一个 [`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["网页 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/>hit@k · MRR · 召回<br/>RAGAS · 5 家法官小组"]
REASON -.->|实时运行轨迹| OBS["可观察性<br/>LangSmith · OpenTelemetry"]
```
存储之上的一切都是无状态的；所有状态都存放在 `data/`（JSON 图、HNSW 向量、SQLite 检查点），因此应用程序是可复制的且本地优先。JSON API 也可以 **作为** MCP 服务器暴露（读取开放，写入默认拒绝）。
**评估和可观察性是不同的平面 — 不要混淆它们。** *评估* 在 **离线** 衡量质量：确定性检索指标（hit@k · MRR · 召回）、**RAGAS**（忠实度 · 答案相关性 · 上下文精度，作为 LangSmith 评估器封装在 `ragas_eval.py` 中）和 5 家法官小组校准对抗人类标签。<br />*可观察性* 跟踪 **实时** 运行 — 代理、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["入口 · 网页 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`），它添加了条件门控、持久的人工审查 `interrupt()` 和检查点（SQLite / Postgres / 内存）。每个阶段由进程内或 **Claude Code CLI 作为子进程**（`generate_cc`）编写。门控从不单独完成 — 它落在 `pending_review` 中，只有人类才能提升它。<br />暂停在门控处，检查点并在另一个进程中恢复，线程 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: 通过门控，pending_review
evaluate --> [*]: 拒绝
human_review --> finalize: 接受
human_review --> prepare_revision: 修订 + 笔记
human_review --> [*]: 拒绝
prepare_revision --> codeact: pipeline
prepare_revision --> generate_cc: claude_code
finalize --> [*]
note right of evaluate
确定性检查（11）
+ 5 家法官小组评分标准
end note
note right of human_review
interrupt() 暂停 + 检查点
（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。
## 工作原理（关键部分）
**图谱是分层的，不是扁平的实体袋。** 节点通过类型化边攀爬到 `source → section → chunk → entity → topic → synthesis → memory → agent_skill`（层 0–7），并加入类型化边（`mentions`、`relation`、`belongs_to`、`subtopic_of`，...）。KG 选项卡渲染三个粒度（文档 / 章节 / 分块）。
**检索仅基于向量 — 出于目的。** 每个章节都有一个 LLM 编写的上下文摘要；分块嵌入 `title · date · section` 前置到一个两层 HNSW 索引。检索排名章节，钻入分块，然后重排器 *或* MMR 选择 top-k。<br />**实体图谱遍历已构建、评估并移除** — MMR 在召回 *和* 评估合成方面击败它。图谱在 *构造*（规范化、主题、来源）和 *呈现*（概念图）中发挥作用，而不是检索。
**技能受到门控。** 技能草案必须通过确定性检查（可用描述，≥2 步，正面 *和* 负面触发器，声明的工具，无占位符）和跨家族评分标准小组 — 但门控从不单独完成：它落在 `pending_review` 中，只有 **人类** 才能提升它。每次构建/评估/精炼都记录了每个阶段的计时、令牌和触发精度/召回率；`refine` 从其测量的弱点重建技能。可选地作为 LangGraph `StateGraph` 运行，其中人类审查是一个持久的 `interrupt()` — 在门控处暂停，检查点，在另一个进程中恢复。
## 评估
所有数字来自一个版本控制的 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`。
| 设置 | 指标 | 结果 |
| --- | --- | --- |
| 单文档，重排 | hit@6 / MRR | 0.87 / 0.81 |
| 重排器关闭 → 打开 | RAGAS 上下文精度 | 0.51 → 0.67 |
| 跨文档，基准 → MMR | 检索召回 | 0.59 → **0.91** |
| 跨文档，MMR 与图谱-RAG | 检索召回 | **0.909** vs. 0.788 |
| 跨文档，合成提示修复 | RAGAS 答案相关性 | 0.65 → **0.90** |
MMR 在召回 *和* 合成方面获胜，因此图谱-RAG 被删除；相关性提升来自允许生成器跨段落合成而不是在没有单个分块声明连接时拒绝。
## 接口
**网页 UI** — 读取（搜索 / 获取 + 提取 / 总结 / 保存到 KG）的选项卡，知识图谱（摄入，浏览分层图谱，集成 / 提问 / 维护），库 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`.
## 截图
网页 UI 处于活动状态 — 每个选项卡一张图片。
**读取** — 搜索 / 获取 + 提取 / 总结 / 保存到 KG。
**缓存** — 在 KG、Q&A 和记忆中重用提取的内容，而无需重新获取。
**知识图谱** — 摄入，浏览分层图谱，集成 / 提问 / 维护。
**记忆** — 跨会话存储，在每次答案之前回忆，并在之后写入。
**代理技能** — 构建，观察评估/门控报告，接受/修订/拒绝。
## 连接工具（MCP）
代理可以调用外部 MCP 服务器，并且 BYO-WIKI 可以运行为一个 — 都是可选且本地优先的。使用 `MCP_ENABLED` 启用服务器；读取工具加入策划代理和技能构建器，并且 `mcp-ingest` 阶段将读取工具的输出摄入 KG。<br />**写入默认拒绝**：写入仅通过 `/api/mcp/write`（或 `mcp-call --confirm`）并使用 `MCP_ALLOW_WRITES=1` *和* 显式人类批准运行，并且客户端门控跟踪服务器自己的 `read_only` 范围，以免漂移。<br />托管的 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* 深度代理示例。<br />使用 Flask，`deepagents`/LangChain，`hnswlib`，OpenAI 嵌入，RAGAS 和 LangSmith 构建而成。
