内容
# Librarian
一套用于 AI 工程的知识库 — 遵循 [Karpathy LLM Wiki 模式](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。
原始资料（文档、会议记录、论文、书籍）存放在 `raw/` 目录（只追加）。Claude 将它们编译到 `wiki/` 目录 — 结构化、相互关联、冲突标记。本地 MCP 服务器在运行时将 wiki 暴露给任何代理。
**思维模型：** `raw/` = 源代码。Claude = 编译器。`wiki/` = 可执行输出。
---
## 为什么
代理工程积累了许多经验知识：使用哪个框架、何时使用、实际有效的阈值、文档中看起来不错但运行时失败的模式。没有系统支持，每次项目都会重新推导这些决策。
Librarian 捕获这些知识，结构化后便于检索，并在开始前通过 Claude Code 中的斜杠命令、运行代理中的 MCP 工具或用于探索的图 UI 显示出来。
---
## 架构
```
会议 ──────────────────────────────► raw/sessions/ ─┐
文档（.claude/skills/，CLAUDE.md） ─────► raw/claude-docs/ │
仓库爬虫（etl/scrape_repos.py） ─────► raw/repos/ │
谷歌硬盘 ──MCP──────────────────────► raw/gdrive/ ├──► /ingest ──► wiki/
Notion ────────MCP──────────────────────► raw/notion/ │
会议、PDF、网页、书籍、文章 ──► raw/*/ ─┘
wiki/
│
┌───────────────────┼──────────────────┐
▼ ▼ ▼
MCP 服务器 /adk-context 图形 UI
（search_wiki、 （代理生成器 （React + Cytoscape
read_page、 简报） + 聊天代理）
get_domain_briefing）
│
▼
Claude Code · 自定义代理 · 任意 MCP 客户端
```
**关键不变性：**
- `raw/` 只追加 — 追加后永不编辑
- `wiki/` 由 Claude 维护 — 人类仅纠正事实错误
- 冲突被标记，而非静默覆盖
- `wiki/private/` 被 gitignore — 公司特定页面在此本地存储
---
## 用例
| 用例 | 操作方法 |
|---|---|
| **构建前简报** | `/adk-context` 或 `get_domain_briefing("langgraph")` — 在开始新代理前加载积累的模式 |
| **基于事实的问答** | `/query "我们的代理内存方法是什么？"` — 从您自己的编译经验中回答，而非通用文档 |
| **决策记录** | 导入 ADR 或会议记录 → wiki 自动创建 `type: decision` 页面，包含权衡和交叉链接 |
| **运行时代理知识** | 在任意代理中将 `search_wiki` + `read_page` 作为 MCP 工具 — 在查询时自我简报 |
| **研究综合** | 将论文、书籍引用、文章捕获到 `raw/` → 导入编译冲突、交叉链接和概念页面 |
| **团队知识库** | 共享 wiki，具有多用户导入；MCP 服务器作为团队范围的检索 API |
| **代码库入职** | 爬取新仓库的 CLAUDE.md + 文档 → 导入 → 关于架构决策的即时事实答案 |
---
## 快速入门
```bash
# 1. 安装
uv sync # 核心依赖
make install-api # FastAPI + sentence-transformers + Gemini 客户端
make install-ui # npm 安装，用于 React UI
# 2. 配置
cp .env.example .env
# 填写：
# ANTHROPIC_API_KEY — /ingest、/query、/lint 斜杠命令所需
# GOOGLE_API_KEY — 图形 UI 聊天代理所需（免费 at aistudio.google.com）
# NOTION_API_KEY — 可选，用于 Notion 连接器
# LINEAR_API_KEY — 可选，用于 Linear 连接器
# 3. 在 Claude Code 中打开
code . # CLAUDE.md 自动加载；MCP 服务器自动启动
```
**首次运行 — 从现有文档开始：**
```
/ingest raw/claude-docs/ # 编译任意现有的 .claude/ 文档
/ingest raw/sessions/ # 编译 Claude Code 会话历史（每批 20 个）
```
**然后查询：**
```
/query "LangGraph 的代理内存方法是什么？"
/adk-context # 您的领域简报
```
---
## 推荐工作流
### 每天（30 秒）
丢弃任何新的原始资料并立即导入：
```bash
# 示例：粘贴会议记录
# raw/meetings/2026-07-05-architecture-review.md
/ingest raw/meetings/2026-07-05-architecture-review.md
```
### 每周（5–10 分钟）
完整同步 — 拉取新的 Notion/Drive 内容，爬取会话，编译所有新内容：
/ingest # 完整管道：Notion + GDrive + 会话 + 仓库 → wiki
/lint # 健康检查：孤立页面、死链接、过期页面、未解决冲突
可选地爬取您正在积极工作的仓库：
```bash
# 将仓库添加到 raw/repos/repos.txt，然后：
uv run python etl/scrape_repos.py
/ingest raw/repos/
```
### 代理构建会话前
```
/adk-context # 简报：您领域的决策 + 模式 + 概念
# 或
get_domain_briefing("langgraph") # 通过 MCP 在代理本身
```
### 遇到冲突时
```
/ingest resolve # 有指导的冲突解决：阅读双方主张，选择正确，标记解决
/lint # 确认所有冲突已关闭
```
### 架构治理（PR）
```
/sanyi review # 检查 diff 是否违反 SANYI 变更合同
/code-review # 正确性 + 简化检查
```
---
## 组件
| 组件 | 功能 |
|---|---|
| `raw/` | 只追加的输入缓冲区 — 会话、文档、会议记录、PDF、书籍、文章、仓库爬取 |
| `wiki/` | LLM 编译的知识 — 每个概念、模式或决策一个 `.md` 文件；结构化 frontmatter，维基链接 |
| `wiki/private/` | 公司特定页面，gitignore — 相同格式，仅限本地 |
| `CLAUDE.md` | 编译器合约 — 模式规则、导入检查清单、冲突策略、领域分类法 |
| `etl/` | 爬虫：`scrape_sessions.py`（Claude/Codex）、`scrape_claude_docs.py`（工作区文档）、`scrape_repos.py`（仓库） |
| `app/mcp_server/` | FastMCP 服务器：`search_wiki`（混合 FTS + 语义 + 反向链接排名）、`read_page`、`list_domain`、`get_domain_briefing` |
| `app/backend/` | FastAPI — wiki 图形 API、DuckDB 缓存嵌入 + UMAP 布局、流式 Gemini 聊天代理 |
| `app/ui/` | React + Vite 图形 UI — Cytoscape.js 力导向图、聊天面板、实时 wiki 监视 |
| `.claude/skills/` | `/ingest`、`/query`、`/lint`、`/adk-context`、`/seed-kb`、`/sanyi` — Claude Code 斜杠命令 |
---
## MCP 服务器
在 `.claude/settings.json` 中预配置 — 自动适用于 Claude Code 和任意 MCP 客户端。
```bash
uv run python app/mcp_server/server.py
```
**工具：**
| 工具 | 描述 |
|---|---|
| `search_wiki(query, domain, limit)` | 混合搜索：FTS + 余弦相似度 + 反向链接排名 |
| `read_page(path_or_title)` | 按路径或模糊标题匹配读取页面 |
| `list_domain(domain)` | 域中的所有页面，按反向链接计数排序 |
| `list_pages(tag, directory)` | 按标签或目录过滤页面 |
| `get_domain_briefing(domain)` | 域中的所有页面连接起来 — 决策优先，然后是模式、概念 |
**混合搜索** 结合三个信号：文本匹配相关性（FTS）、语义相似性（sentence-transformers，如果安装）和反向链接计数。如果 sentence-transformers 缺失，则仅回落到 FTS。
---
## 图形 UI
```bash
make api # FastAPI 后端 on :8000（wiki 图形 + 语义边缘 + UMAP + 聊天）
make ui # Vite 开发服务器 on :5173
```
后端在 DuckDB 中缓存嵌入和 UMAP 布局 — 仅在 wiki 页面更改时重新计算。
---
## Wiki 不变性
1. **每个概念一个页面** — 找到现有页面或创建一个；永远不要分散知识
2. **冲突被标记，不被覆盖** — 矛盾进入 `wiki/_conflicts.md` 进行人工审查
3. **每个页面至少有一个反向链接** — 孤立页面是 lint 错误
4. **`updated:` 在每次写入时设置** — 过期页面（>60 天）通过 `/lint` 显示
5. **来源被引用** — 每个 wiki 页面列出它编译的 `raw/` 文件
6. **私有内容保持私有** — 公司特定页面进入 `wiki/private/`（gitignore），而非 `wiki/projects/`
---
## 领域标签
| 标签 | 涵盖 |
|---|---|
| `adk` | Google Agent Development Kit — 模式、API、部署 |
| `langgraph` | LangGraph 状态机、CRAG、检查点、边缘 |
| `rag` | 检索增强生成、嵌入器、重新排序器、分块 |
| `memory` | 代理内存模式 — 短期、长期、情景、语义 |
| `mcp` | 模型上下文协议、MCP 服务器设计、工具模式 |
| `voice` | 语音代理模式、BIDI 流媒体、会话管理 |
| `eval` | 评估框架、LLM 评判器、黄金集、指标 |
| `infra` | 部署、CI/CD、可观察性、缓存 |
| `llm` | LLM API 模式、提示工程、上下文管理 |
| `deep-agents` | Deep Agents 框架 — 中间件、StateBackend、StoreBackend |
| `context-management` | 前缀缓存、会话压缩、历史修剪 |
---
## 原始资料类型
| 目录 | 来源 | 爬虫 |
|---|---|---|
| `raw/sessions/` | Claude Code + Codex 会话 JSONL | `etl/scrape_sessions.py` |
| `raw/claude-docs/` | `.claude/` 文档来自工作区项目 | `etl/scrape_claude_docs.py` |
| `raw/repos/` | CLAUDE.md、技能、文档来自配置的仓库 | `etl/scrape_repos.py` + `repos.txt` |
| `raw/notion/` | Notion 页面 | MCP 连接器 |
| `raw/gdrive/` | Google Drive 文档 | MCP 连接器 |
| `raw/linear/` | Linear 问题 + 项目 | `etl/ingest_linear.py` |
| `raw/pdfs/` | PDF 文本提取 | `etl/ingest_pdf.py` |
| `raw/meetings/` | 会议记录 | 手动丢弃 |
| `raw/web/` | 网页文章捕获 | 手动丢弃或 URL 模式 |
| `raw/books/` | 书籍引用 + 笔记 | 手动丢弃（参见 `CLAUDE.md` 了解格式） |
| `raw/articles/` | 文章高亮 + 笔记 | 手动丢弃或 URL 模式 |
---
## 斜杠命令
| 命令 | 功能 |
|---|---|
| `/ingest [path \| url \| resolve]` | 编译原始资料 → wiki；`resolve` 模式用于冲突解决 |
| `/query <question>` | 从编译的 wiki 中获取事实答案；可选地将答案作为新页面文件 |
| `/lint` | 健康检查 — 孤立页面、死链接、过期页面、未解决冲突 |
| `/adk-context [domain]` | 针对构建会话的精选简报 |
| `/seed-kb` | 爬取会话 + 文档，然后提示导入 |
| `/sanyi [init \| review \| audit]` | 变更合约治理 — 检测跨层违规 |
---
## 架构治理（SANYI）
仓库包括 [SANYI 变更合约系统](wiki/meta/sanyi-change-contract-system.md)，用于检测跨 PR 的架构衰退。
此仓库的层级：
- **Bianyi** （不断变化）：wiki 页面内容、导入提示、领域分类法配置
- **Jianyi** （有界）：MCP 工具模式、wiki frontmatter 规范、清单格式
- **Buyi** （不变）：来源归因（永不服务无根据的来源）、清单去重、冲突标记、MCP 只读约束
```
/sanyi init # 创建 SANYI.md 合同
/sanyi review # 检查 diff 是否违反合同
/sanyi audit # 完整的仓库健康检查
```
---
## 相关
- [Karpathy llm-wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — 原始编译 wiki 模式
