Knowledge compounds like code. FlowWiki is the compiler.
- Karpathy 的愿景
- 原始愿景的 6 个缺口
- FlowWiki 的 6 个增强
- 架构总览
- 三大创新招牌
- 快速开始
- 核心操作
- Skill vs Prompt 决策指南
- 与具体项目对比
- Tech Stack
- 设计哲学
- 适用场景
- 里程碑路线图
- FAQ
- 参考与致谢
- License
2025 年，Andrej Karpathy 提出了一个简洁而强大的类比：
Obsidian 是 IDE，LLM 是程序员，Wiki 是代码库。
传统 RAG 是解释器——每次查询都重新推导。LLM Wiki 是编译器——知识只编译一次，保持最新，查询时直接读取。好的查询结果归档回 Wiki，探索本身也复利积累。
三层架构：raw/（不可变源文件）→ wiki/（LLM 编译维护）→ schema/（协同演进配置）。
四个操作：ingest → query → lint → research。
这个概念启发了整个社区——GitHub 上已涌现 30+ 个 LLM Wiki 项目，累计 30,000+ Stars。
但原始愿景有缺口。
| # | 缺口 | 症状 | 后果 |
|---|---|---|---|
| 1 | 无防幻觉机制 | AI 生成的摘要可能包含事实错误 | 错误知识永久化，越积越深 |
| 2 | 无跨会话记忆 | 每次 ingest 独立执行，不记得上次做了什么 | 重复劳动，无法累积上下文 |
| 3 | 无人类入口 | wiki/ 是扁平文件列表，人类找不到东西 | 技术好但不好用 |
| 4 | 知识不复利到能力 | 高频任务每次都从零开始 | 效率不随知识增长而提升 |
| 5 | 变更不可追溯 | 改了什么、为什么改，无记录 | 知识库变成黑箱 |
| 6 | 单平台绑定 | 绑死 Claude Code 或单一 agent | 换工具就丢知识库 |
| 缺口 | FlowWiki 解法 | 层级 |
|---|---|---|
| 无防幻觉 | ACE 反思循环 — Generator→Reflector→Curator 三 agent 制约，错误知识不进 wiki | L4 |
| 无跨会话记忆 | A-MEM 卡片 — 每个 raw 生成 Zettelkasten 卡片，跨会话可读 | L4 |
| 无人类入口 | 双索引 — 机器走 wiki/index.md，人类走 00_首页/ 6 板块 MOC |
L1 |
| 知识不复利 | 任务→知识→Skill 三元组 — 高频任务自动抽象为 O(1) 调用的 skill | L5 |
| 变更不可追溯 | SpecCoding 七阶段 — 每个变更走 openspec/changes/ |
L3 |
| 单平台绑定 | 多 agent bootstrap — CLAUDE.md + AGENTS.md + CODEX.md + WORKBUDDY.md + GEMINI.md + HERMES.md + KIRO.md + PI.md + TRAE.md + OPENDROID.md（10 家 agent） | L6 |
┌──────────────────────────────────────────────────────────────┐
│ L7 场景层（业务外壳，可插拔） │
│ 7 行业适配器（enforcement-review / enterprise-compliance / ...） │
├──────────────────────────────────────────────────────────────┤
│ L6 多 agent 接手层 │
│ CLAUDE.md + AGENTS.md + CODEX.md + WORKBUDDY.md │
│ + GEMINI.md + HERMES.md + KIRO.md + PI.md + TRAE.md + OPENDROID.md │
│ （10 家 agent 兼容） │
├──────────────────────────────────────────────────────────────┤
│ L5 Skill 化层 │
│ 36 skill（双部署：.agents/skills/ + .claude/skills/）+ 高频任务自动抽象 │
├──────────────────────────────────────────────────────────────┤
│ L4 Agent 记忆层 ★ FlowWiki 独有 │
│ A-MEM 卡片（Zettelkasten）+ ACE 反思循环 + 少数派分支 + 缺口检测 │
├──────────────────────────────────────────────────────────────┤
│ L3 Spec-Driven 层 │
│ spec/ 全局设计 + openspec/changes/<name>/ 单任务变更 │
├──────────────────────────────────────────────────────────────┤
│ L2 检索增强层（自适应插件） │
│ ≤100 页 BM25+CJK → 100-500 nano-graphrag → 500+ LightRAG │
├──────────────────────────────────────────────────────────────┤
│ L1 知识编译层（双索引，核心骨架） │
│ raw/ (只读) + wiki/ (AI 编译) + 00_首页/ (TRAE 6 板块人类 UX) │
└──────────────────────────────────────────────────────────────┘
详细设计见 spec/design.md。
FlowWiki v0.5.0 起支持 OKF（Open Knowledge Format） — 由 llm-wiki-compiler v1.1.0 定义的可移植知识交换格式，对齐 Google Cloud 新兴标准。OKF 是 LLM Wiki 领域的「POSIX」：
# 导出 wiki/ 为 OKF bundle（可供其他 LLM Wiki 工具消费）
python _scripts/okf_export.py
# 导入外部 OKF bundle（默认进入隔离区审核）
python _scripts/okf_import.py --input ./external-bundle
# 受信任的 bundle 直接导入
python _scripts/okf_import.py --input ./bundle --trusted- 导出产物：
okf.json清单 +pages/Markdown 页面 +SHA256SUMS完整性校验 - 导入安全：非 trusted 模式自动隔离到
wiki/_quarantine/，审核后放行 - 跨工具兼容：与 llm-wiki-compiler、swarmvault 等支持 OKF 的系统互操作
任务层（openspec/changes/） → 知识层（wiki/） → Skill 层（.claude/skills/）
↑ │
└────────── O(1) 调用 ──────────────────────────┘
- Karpathy 只有 raw→wiki 两层（O(n) 查询）
- FlowWiki 引入第三层 Skill，让"复利"从知识扩展到能力，下次同类任务 O(1) 调用
┌──────────────┐
│ Generator │ ← 根据 raw 生成摘要
└──────┬───────┘
▼
┌──────────────┐
│ Reflector │ ← 批判：找矛盾/幻觉/过时
└──────┬───────┘
▼
┌──────────────┐
│ Curator │ ← 决策：入 wiki / 标"待核" / 触发 conflict/
└──────────────┘
- Karpathy 的 lint 只扫结构不扫内容
- FlowWiki 在 ingest 时三 agent 制约，错误知识不进 wiki
| 索引 | 受众 | 形态 |
|---|---|---|
wiki/index.md |
AI agent | 紧凑扁平（1000 页只占 50KB） |
00_首页/ 6 板块 |
人类 | TRAE 风格 MOC + Dataview 看板 |
- 两者内容可重复但呈现不同
- 机器走 index，人类走 6 板块，互不干扰
- 解决 Karpathy "500 页爆 context" 痛点
知识库最大的敌人不是 AI 不够聪明，而是时间。新法规出台、旧标准废止、跨页引用断裂——FlowWiki v0.7.x 引入了五道防线：
┌──────────────────────┐
│ L1: pre-commit hook │ ← 本地写入前 lint + frontmatter 校验
├──────────────────────┤
│ L2: CI quality-gate │ ← push/PR 自动跑 14 维度审计 + 红线阻断
├──────────────────────┤
│ L3: daily auto-audit │ ← 每日全量巡检 + 自动修复 + 报告同步
└──────────────────────┘
14 个维度量化知识库健康度：文件覆盖率、frontmatter 完整性、溯源率、内容信号密度、内部链接有效性、悬空链接率……从第一次审计的 74% 到 v0.7.5 的 87.3%，两阶段优化（代码修复 + LLM 管道）。
用图论的 Tarjan 关节点算法扫描整个知识图谱——删掉任何一个 wiki 页面，图谱都不会断裂。 这是知识库架构的结构性保障，不是事后修补。
sync_bidirectional.sh 让 wiki 内容反向更新 raw 索引、检测孤立节点、自动补全缺失引用。v0.7.4 一次运行反哺 806 条关联——知识库从"被动存储"进入"自我修复"模式。
仓库预置 enforcement-review（执法督察评查） 作为测试知识库：
# 一键引导（入仓 → 设计 → 入库 → 三验 → 自修复）
python _scripts/bootstrap.py --source raw/enforcement-review --slug enforcement-review --skip-to 2
# 验收
python _scripts/hermes_review.py --industry enforcement-review
python _scripts/graph.py --format stats --industry enforcement-review| 指标 | 值 |
|---|---|
| raw/ | 155 篇原始资料 |
| wiki/ | 806 页知识图谱 |
| 可路由率 | 87.3%（Hermes 红线 ≥ 85% 达标） |
| 反断裂度 | Tarjan 零关节点 |
| 质量门控 | 三层自动化 |
详见 TESTING.md
pip install flowwiki
flowwiki init my-wiki
cd my-wiki
flowwiki doctor # 健康检查 ✅对标 Ar9av obsidian-wiki setup 和 GBrain gbrain init。2 秒创建完整知识库结构（23 目录 + 6 文件），幂等安全。
放入原始资料即开始编译：
mkdir -p raw/articles
cp ~/some-article.md raw/articles/
flowwiki-ingest # 开始编译知识git clone https://github.com/xiejianjun000/FlowWiki.git my-wiki
cd my-wiki
# 自动检测区域 + 生成本地化目录（中文/英文）
bash _scripts/setup.sh
# 选择你的 agent bootstrap（10 家兼容）
# Claude Code → 读 CLAUDE.md
# Codex / Amp → 读 AGENTS.md
# Gemini CLI → 读 GEMINI.md
# Hermes → 读 HERMES.md
# WorkBuddy → 读 WORKBUDDY.md
# Kiro IDE → 读 KIRO.md
# Pi Agent → 读 PI.md
# Trae / Trae CN → 读 TRAE.md
# Droid / Aider → 读 OPENDROID.md
# 投入第一篇 raw
mkdir -p raw/articles
cp ~/some-article.md raw/articles/
# 在 agent 中触发 ingest
> 请按 ingest skill 把 raw/articles/some-article.md 入库💡 区域自适应：
setup.sh会自动检测你的 IP 归属地。国内用户看到中文目录（原始资料/知识库/首页/），海外用户保持英文目录。AI Agent 始终走英文路径，互不干扰。
# 把 FlowWiki 骨架文件复制到你的 vault 根目录
cp -r raw/ wiki/ 00_首页/ config.toml SCHEMA.md your-vault/
# 把 CLAUDE.md / AGENTS.md 放到 vault 根目录
# Obsidian 会自动识别 00_首页/ 为 MOC 入口参考 SCHEMA.md 手动创建目录结构，或使用 _scripts/ 下的脚本初始化。
git clone https://github.com/xiejianjun000/FlowWiki.git my-wiki
cd my-wiki
# 构建并启动
docker compose up -d
# 接入 MCP（让 AI Agent 直接调用 FlowWiki）
# 参考 docs/mcp-integration.mdpip install -r requirements.txt
python _scripts/mcp_server.py然后在你的 AI Agent 的 MCP 配置中添加 FlowWiki server，详见 docs/mcp-integration.md。
FlowWiki 继承 Karpathy 的 4 操作，并在每个操作中嵌入创新：
| 操作 | Karpathy 原教 | FlowWiki 增强 |
|---|---|---|
| ingest | 单 agent 生成摘要 | ★ ACE 三 agent 反思循环 + A-MEM 卡片生成 |
| query | 读 index + 加载相关页 | ★ 答案回存 episodic + 检查是否值得抽象 skill |
| lint | 扫结构（悬空/孤儿/缺口） | ★ 加扫矛盾未解决 + confidence 不匹配 + 4 项新检查（index同步/frontmatter/wikilink/命名） |
| research | （Karpathy 未定义） | ★ 跨页综合研究 + 自动生成 comparison 页 |
| fulltext | （FlowWiki 原创） | ★ 按需加载 raw/ 全文，配套原文指针铁律，避免双写 |
每个操作有对应的 .claude/skills/<op>/SKILL.md 和 .agents/skills/<op>/SKILL.md，10 家 agent 都能直接调用。
| 用 Skill | 用 Prompt |
|---|---|
| 高频操作（≥3 次同类任务） | 一次性或低频（≤2 次） |
| 多步骤工作流（如 ingest 7 步） | 单步骤操作或风格切换 |
| 跨场景通用（如 lint 体检） | 场景专属引导（如"用执法者视角回答"） |
| 有明确输入输出契约 | 探索性实验（还没形成标准流程） |
| 长期维护、版本管理 | 用完即弃，不持久化 |
升级路径：Prompt（探索期）→ 高频使用 ≥3 次 + 流程可标准化 → 升级为 Skill（O(1) 调用）
| 维度 | Karpathy LLM Wiki | TRAE Work | 传统 RAG | FlowWiki |
|---|---|---|---|---|
| 知识复利 | ✅ | ❌ | ❌ | ✅ |
| 人类 UX | ❌ | ✅ | ❌ | ✅ 双索引 |
| AI 接手友好 | 🟡 仅 Claude | ❌ | ❌ | ✅ 10 家 agent |
| 防幻觉 | ❌ lint 只扫结构 | N/A | ❌ | ✅ ACE 三 agent |
| 跨会话记忆 | ❌ | ❌ | 🟡（向量库） | ✅ A-MEM 卡片 |
| 变更追溯 | ❌ | ❌ | ❌ | ✅ SpecCoding |
| 业务可插拔 | ❌ | ❌ | ❌ | ✅ L7 场景外壳 |
| 规模上限 | 200 页 | 无限（但人工） | 万页 | 自适应 |
| 能力 | FlowWiki | llm-wiki-agent | claude-obsidian | llm-wiki-compiler | synthadoc |
|---|---|---|---|---|---|
| 防幻觉机制 | ACE 三 agent + VBFW | 矛盾标记 | review policy | VERIFY-BEFORE-WRITE | Pre-LLM 净化 |
| 跨会话记忆 | A-MEM 卡片 | 无 | Hot Cache | 无 | 无 |
| 多 agent 兼容 | 10 家 agent | 3 家 | 仅 Claude | 仅 Claude | 3 家 |
| 人类 UX | 双索引 6 板块 | 无 | Obsidian 原生 | 桌面 GUI | Web UI |
| 业务可插拔 | L7 场景外壳 | 无 | 无 | 无 | 无 |
| 变更追溯 | SpecCoding | 无 | 无 | 无 | 无 |
| 知识复利到能力 | 任务→知识→Skill | 无 | 无 | 无 | 无 |
| 自适应检索 | BM25→graphrag→LightRAG | 无 | 混合检索 | BM25 | 知识图谱 |
| 矛盾追踪 | conflict/ 目录 | 标记不追踪 | 无 | 无 | 无 |
| OKF 知识交换 | ✅ v0.5.0 | 无 | 无 | ✅ v1.1.0 | 无 |
FlowWiki 是唯一同时覆盖以上 10 个维度的项目。
| 项目 | Stars | 定位 | 核心亮点 | FlowWiki 对比 |
|---|---|---|---|---|
| garrytan/gbrain | 25K+ | 企业级 AI 大脑 | PGLite 零基础设施引擎（v0.7.0），company brain scope-by-login，DreamCycle 9 阶段自维护，Skillify 技能进化，146K+ 页生产部署 | 企业级能力远超 FlowWiki；FlowWiki 面向方法论和个人用户 |
| nashsu/llm_wiki | 15.2K | 桌面 GUI 应用 | Tauri+React GUI，Louvain 图谱聚类，Chrome 剪藏，MCP，Two-Step CoT 摄入 | FlowWiki 无 GUI 但方法论更深、防幻觉更强 |
| SamurAIGPT/llm-wiki-agent | 3.2K | 多 Agent Skill 包 | Agent-agnostic，Git 版本控制，知识图谱可视化 | FlowWiki 的 ACE 是其没有的防幻觉层 |
| Ar9av/obsidian-wiki | 3.0K | 完整框架 | PyPI 包分发(pip install)，36 skill，trust-ledger strict_trust，12+ Agent 兼容，7 月已发布 9 个 release |
FlowWiki 有 ACE+OKF+VBFW，已对标 PyPI 分发和 Agent 数量 |
| atomicstrata/llm-wiki-compiler | 1.5K | npm 知识编译器 | OKF 格式，eval harness，MCP Server，Ed25519 签名模板分发（v1.1.0 Jul 15） | 最接近 FlowWiki 品控理念；FlowWiki v0.5.0 已支持 OKF 互操作 |
| LangChain OpenWiki | 新发布 | Agent 主动记忆 | 6 信源自动连接（Gmail/Notion/Git/X/HN/Web），定时刷新，Personal Brain 模式 | FlowWiki 缺少主动信源连接；OpenWiki 没有 ACE 反思 |
| swarmclawai/swarmvault | ~600 | 知识图谱编译器 | candidate review queue，桌面应用，本地图谱查看器，30+ 输入格式 | 活跃度下降（6/30 最后推送）；FlowWiki 方法论覆盖更全 |
| lucasastorian/llmwiki | 1.4K | Web 托管 | llmwiki.app 在线服务，Chrome 扩展 | FlowWiki 本地优先，数据主权更好 |
| Ekgardt/llm-wiki | 新品 | 会话记忆系统 | VERIFY-BEFORE-WRITE，会话生命周期钩子，三级分类（FLUSH_MAJOR/MINOR/OK） | FlowWiki v0.6.0 已集成 VBFW 门控到 ingest 流程 |
FlowWiki 的差异化定位：最严格的知识质量保证 + 能力复利飞轮。
- 桌面应用选 nashsu，Web 托管选 lucasastorian，工程化编译选 atomicstrata
- 要对知识质量有洁癖 → FlowWiki（ACE 三 agent 制约 + SpecCoding 追溯）
| 层 | 技术 | 说明 |
|---|---|---|
| 知识格式 | Markdown + YAML frontmatter | 人类可读、Obsidian 兼容 |
| 检索 L2 | BM25 + CJK 分词 → nano-graphrag → LightRAG | 自适应三档，按规模自动切换 |
| 记忆 L4 | A-MEM Zettelkasten 卡片 | 跨会话持久化，零数据库依赖 |
| 防幻觉 L4 | ACE Generator→Reflector→Curator + Strict 模式 + 原文指针铁律 | 三 agent 制约 + 强制校验，ingest 时拦截错误 |
| 变更管理 L3 | OpenSpec + SpecCoding 七阶段 | 可追溯，每个变更有提案/执行/归档 |
| Agent 兼容 L6 | CLAUDE.md + AGENTS.md + CODEX.md + WORKBUDDY.md + GEMINI.md + HERMES.md + KIRO.md + PI.md + TRAE.md + OPENDROID.md | 10 家 agent 通吃 |
| Skill 分发 L5 | .agents/skills/ + .claude/skills/ 双部署 | 同一 skill 两套格式，36 个 skill |
| 质量工程 L3-L4 | quality_audit.py（14 维）+ CI quality-gate + Tarjan 反断裂度 + 双向同步 | 三层门控，知识库自我修复 |
| 竞品监控 | 35+ 项目全景扫描 + 11 轮手动巡查 | 自动化基础设施常态化 |
| 可视化 | Obsidian Graph View + Dataview | 零额外依赖 |
| 部署 | Docker + docker compose | 一键启动 |
| MCP 接口 | _scripts/mcp_server.py |
5 工具暴露给 AI Agent |
| 依赖 | PyYAML + MCP SDK | 极简优先 |
思考、规格、执行在物理上分开。raw 只读 / wiki AI 写 / spec 人写。三者不交叉。
默认零依赖：纯 Markdown + frontmatter + git。L2 检索、L4 记忆都不强制引入数据库。
AI 走 index.md，人类走 6 板块。两者并行不冲突。
每个任务都走"接任务 → spec → 执行 → archive → 复利"五步，不留孤立操作。
ACE 三 agent 制约 + 矛盾显式标注 + 旧说法被推翻时不静默覆盖。
raw → wiki → skill → 自动调用 → 新任务 → 新 raw → wiki 增厚 → skill 增多 → ...
- 个人/团队知识库（100-10000 页规模）
- AI agent 长期维护的专业领域知识库
- 需要多 agent 接手的协作型知识库
- 业务领域可插拔的多场景知识库
- 单次查询的临时知识需求（用 RAG 即可）
- 必须用云服务的多租户 SaaS（FlowWiki 是本地优先）
- 必须图形界面（FlowWiki 依赖 Obsidian 等第三方可视化）
- 万页以上且需秒级查询（用专业向量数据库）
| 里程碑 | 名称 | 状态 |
|---|---|---|
| M0 | 全局 spec 设计 | ✅ |
| M1 | 骨架脚手架 | ✅ |
| M2 | 4 操作 skill 实现 | ✅ |
| M3 | ACE 反思循环 + A-MEM | ✅ |
| M4 | 双索引同步 | ✅ |
| M5 | L7 场景参考实现 | ✅ |
| M6 | 多 agent 兼容矩阵 | ✅ |
| M7 | 方法论白皮书 + GitHub 发布 | ✅ |
| M8 | 质量工程——三层门控 + D1-D14 健康度 + 反断裂度 + 双向同步（v0.7.5） | ✅ |
详细任务见 spec/tasks.md。
Karpathy 提出了 raw→wiki→schema 三层架构和 4 操作的核心理念。FlowWiki 在此基础上新增了 6 个增强：ACE 防幻觉循环、A-MEM 跨会话记忆、双索引人类 UX、任务→知识→Skill 复利、SpecCoding 变更追溯、多 agent 兼容。简单说，Karpathy 是编译器，FlowWiki 是带类型检查、缓存和插件的编译器。
RAG 是解释器——每次查询都重新推导，结果不持久化。FlowWiki 是编译器——知识只编译一次并保持最新，查询时直接读取编译产物。更关键的是，FlowWiki 的探索结果会归档回 wiki，让探索本身也复利积累。传统 RAG 没有防幻觉机制，FlowWiki 有 ACE 三 agent 制约。
100-10000 页是最佳区间。100 页以下用纯 Obsidian 即可，不需要 FlowWiki 的 L2 自适应检索。10000 页以上且需秒级查询，建议用专业向量数据库。FlowWiki 的 BM25→nano-graphrag→LightRAG 三档自适应正好覆盖中间地带。
不需要。FlowWiki 默认零数据库依赖，100 页以下用 BM25+CJK 分词就够了。超过 100 页可以按需启用 nano-graphrag（轻量图谱检索），超过 500 页可以启用 LightRAG。全部是纯 Python + 文件系统，不引入任何外部服务。
10 家：Claude Code（读 CLAUDE.md）、Codex（读 AGENTS.md）、Gemini CLI（读 GEMINI.md）、Amp（读 AGENTS.md）、WorkBuddy（读 WORKBUDDY.md）、Hermes（读 HERMES.md）、Kiro IDE（读 KIRO.md）、Pi Agent（读 PI.md）、Trae（读 TRAE.md）、OpenCode/Aider/Droid（读 OPENDROID.md）。所有 agent 共享同一套 skill（.agents/skills/ 和 .claude/skills/ 双部署），换 agent 不丢知识库。
不是。FlowWiki 是一套方法论 + 目录规范 + 脚本工具，输出的是标准 Markdown 文件。你可以用 Obsidian 打开（推荐，因为有 Graph View 和 Dataview），也可以用 VS Code、Typora 或任何 Markdown 编辑器打开。
FlowWiki 站在以下巨人的肩膀上：
| 来源 | 贡献 |
|---|---|
| Karpathy LLM Wiki gist | 三层架构 + 4 操作原教 |
| TRAE Work 官方知识库 | 6 板块 + 7 场景人类 UX |
| OpenSpec | Spec-Driven 变更管理 |
| SuperSpec / Superpowers | 6 阶段执行节奏 |
| A-MEM 论文（NeurIPS 2025） | Zettelkasten 卡片记忆 |
| ACE 论文（LangChain） | Generator→Reflector→Curator 三 agent |
| llm-wiki-agent (SamurAIGPT) | 5 平台 agent 兼容矩阵 |
| llm-wiki CLI | BM25+CJK 检索 + Rust 扩展方案 |
| nano-graphrag | 轻量图谱检索 |
| LightRAG | 实体抽取 + 图谱增强 |
| SpecCoding 模板 | 七阶段工作流 |
| claude-obsidian | /wiki /save 命令交互 |