Flaiwheel

flaiwheel MCP server Available on Glama

面向 AI 编码代理的自托管内存与治理层。将每一次 Bug 修复转化为永久知识。零云依赖。零厂商锁定。

🚀 为什么需要 Flaiwheel

AI 编码代理在会话之间会遗忘所有内容。这导致了重复的 Bug、架构决策的丢失以及知识的衰减。

Flaiwheel 确保：

代理在编码前进行搜索
代理在修复后进行记录
提交会自动捕获知识
内存随时间积累

每一次 Bug 的修复都会让下一次修复成本更低。

Related MCP server: MCP VectorStore Server

🧠 Flaiwheel 的独特之处

可积累的持久化 AI 内存 — 知识不会在会话之间重置。
Git 原生自动化 — 提交会自动转化为结构化知识。
治理，不仅仅是存储 — 质量门禁 + 强制文档化。
混合搜索 + 重排序 — 为真实代码库提供高精度上下文。
完全自托管 — 单个 Docker 容器，无需外部基础设施。
零厂商锁定 — 所有知识均以结构化纯文本文件存储在 Git 中。

✅ Flaiwheel 适用人群

在真实项目中使用 AI 编码助手的工程团队
重复 Bug 成本高昂的代码库
需要完全数据控制的团队
AI 原生开发环境

❌ 不适用人群

几千行代码以下的小型业余项目
只需要更好自动补全功能的开发者
对自托管不感兴趣的纯 SaaS 工作流

🆚 Flaiwheel 的定位

AI 编码工具生成代码。
RAG 工具检索文档。
Flaiwheel 在您自己的基础设施内治理并积累结构化工程知识。

它不会取代您的 AI 助手。它让 AI 助手在大规模场景下变得可靠。

📄 白皮书 (PDF) — 深入了解愿景、架构和设计。

⚙️ 关键技术特性

Flaiwheel 是一个自包含的 Docker 服务，在三个层面运行： 拉取 (Pull) — 代理在编码前进行搜索 (search_docs, get_file_context)
推送 (Push) — 代理在工作时进行记录 (write_bugfix_summary, write_architecture_doc, …)
捕获 (Capture) — Git 提交通过 post-commit 钩子自动捕获知识，即使没有 AI 代理参与

索引您的项目文档 (.md, .pdf, .html, .docx, .rst, .txt, .json, .yaml, .csv) 到向量数据库中
提供 MCP 服务器，供 AI 代理（Cursor, Claude Code, VS Code Copilot）连接
混合搜索 — 通过倒数排名融合 (RRF) 结合语义向量搜索与 BM25 关键词搜索，实现两者的最佳检索效果
交叉编码器重排序 (Cross-encoder reranker) — 可选的重排序步骤，使用交叉编码器模型对候选结果进行重新评分，在词汇不匹配的查询中显著提高精度
行为指令 — AI 代理在每次响应前静默搜索 Flaiwheel，在每次任务后自动记录，并在重新创建前优先复用 — 无需人工提示
get_file_context(filename) — 为代理即将编辑的任何文件预加载空间知识（与 get_recent_sessions 互补，提供完整的时间+空间上下文）
post-commit git 钩子 — 自动将每个 fix:, feat:, refactor:, perf:, docs: 提交捕获为结构化知识文档
动态架构 — 指导 AI 代理维护系统组件和流程的自更新 Mermaid.js 图表
可执行测试流程 — 测试场景以机器可读的 BDD/Gherkin 格式 (Given, When, Then) 记录，用于 QA 自动化
从 Bug 修复中学习 — 代理编写的 Bug 修复摘要会被即时索引
结构化写入工具 — 7 种特定类别的工具（Bug 修复、架构、API、最佳实践、设置、变更日志、测试用例），从源头强制执行质量
预提交验证 — validate_doc() 在自由格式 Markdown 进入知识库前进行检查
摄入质量门禁 — 存在严重问题的文件在索引期间会被自动跳过（不会删除 — 文件所有权归您）
通过 Git 自动同步 — 从专用知识库拉取并推送
工具遥测（持久化） — 跟踪每个项目的每次 MCP 调用（搜索、写入、缺失、模式），检测知识缺口，并提示代理进行记录 — 在重启后保持持久化，并在 Web UI 中可见
影响指标 API — /api/impact-metrics 计算预估节省的时间和避免的回归；CI 流水线可以将护栏结果发布到 /api/telemetry/ci-guardrail-report
主动质量检查 — 每次重新索引后自动验证知识库
知识引导 (Knowledge Bootstrap) — “这就是方式”：分析混乱的仓库，分类文件，检测重复项，提出清理计划，并在用户批准后执行（从不删除文件）
冷启动代码库分析器 — analyze_codebase(path) 在服务器端完全扫描源代码目录（零 Token，零云依赖）。使用 Python 内置的 ast 模块处理 Python，正则处理 TypeScript/JavaScript，使用现有的 MiniLM 嵌入模型进行分类和重复检测。返回一个包含语言分布、类别映射、按文档化得分排名的前 20 个文件、重复对和覆盖缺口的 bootstrap_report.md。在遗留代码库上将冷启动 Token 成本降低约 90%。
多项目支持 — 一个容器管理多个知识库，实现项目间隔离
包含 Web UI 用于配置、监控和测试

v3.9.29 更新内容

Glama 工具检测修复 — AuthManager 在 MCP 服务器启动前在只读 /data 上崩溃（这是 Glama 看到 0 个工具的真正原因）。在 stdio 冷启动模式下已跳过。
stdout 零 print() — 监视器、索引器、读取器、引导程序中剩余的 36 个 print() 已替换为 diag() (stderr)。已验证：完整的 MCP 握手通过 stdio 返回所有 28 个工具。
config.save() 弹性 — 只读文件系统记录警告而不是崩溃。

之前版本: v3.9.28

Glama / MCP stdio 修复 — 所有诊断输出移至 stderr；stdout 现在仅用于 JSON-RPC。Glama Inspector 现在能正确检测所有 28 个工具。
改进的冷启动检测 — stdio 冷启动逻辑能正确处理空的 Docker 卷（在 Glama 检查期间不进行引导/模型下载）。

之前版本: v3.9.27

许可证清理 — 一个 LICENSE 文件 (BSL 1.1) 以实现正确的 GitHub/Glama 检测；所有文档和头文件均指向 LICENSE (而非 LICENSE.md)。
Glama / stdio 检查 — 可选的 [inspect] 依赖项和冷启动 stdio 路径，用于轻量级 MCP 目录构建。

之前版本: v3.9.26

Claude Cowork 技能 — Flaiwheel 工作流现在作为原生 Claude 技能分发。安装程序会将 .skills/skills/flaiwheel/SKILL.md 写入您的项目。当您在 Claude (Cowork) 中打开项目时，该技能会自动可用 — 无需额外设置。该技能驱动会话开始时的上下文恢复、编码前知识搜索、强制性的 Bug 修复后文档记录以及会话结束总结。
技能源码也提交到了本仓库的 skills/flaiwheel/SKILL.md 中，供参考和手动安装。

之前版本: v3.9.25

WSL2 自动预检设置 — 现在会自动检测 WSL2，并在主安装流程前运行专用的预检块。无需手动步骤：
1. 将 iptables 切换到旧版后端（修复 Docker 网络 / DNAT 错误）
2. 将当前用户添加到 docker 组（不再有 permission denied）
3. 通过 service 启动 Docker 守护进程（WSL2 上没有 systemd）
4. 将 Docker 自动启动片段添加到 ~/.bashrc（幂等，每次 WSL2 登录时运行）
脚本中分散的 WSL2 检查已合并到单个预检块中。

之前版本: v3.9.24

修复：如果缺失则自动安装 python3 — 安装程序大量使用 python3 进行 JSON 操作。在没有 python3 的最小化 Linux/WSL2 系统上，配置文件写入会静默失败 (/dev/fd/63: line N: python3: command not found)。现在将 python3 作为第 0 号先决条件进行检查，如果缺失则通过 apt/dnf/yum/pacman/brew 自动安装。

之前版本: v3.9.23

修复：WSL2 上使用 iptables-legacy 启动 Docker 守护进程 — WSL2 上的 Docker 通常会因为不支持默认的 iptables-nft 后端而静默启动失败。安装程序现在在启动 Docker 前通过 update-alternatives 切换到 iptables-legacy。同时自动将当前用户添加到 docker 组。
所有安装命令更新为 bash <(curl ...) — 脚本中显示的所有安装/重新运行命令（错误消息、AGENTS.md、Cursor 规则等）现在都使用进程替换，以避免 WSL2 管道问题。

之前版本: v3.9.22

修复：WSL2 上 curl | bash 管道写入失败 — 由于管道/tmp 权限问题，curl | bash 在 WSL2 上可能会失败并显示 curl: (23) Failure writing output。README 中的主要安装命令现在是 bash <(curl ...)（进程替换），完全避免了管道。重新执行块在 /tmp 写入失败时也会尝试使用 $HOME 作为后备临时目录。错误消息明确建议使用 bash <(curl ...) 形式。

之前版本: v3.9.21

修复：sudo 保护移至重新执行块之前 — 当使用 sudo curl | bash 时，curl: (23) 管道错误在到达之前的 sudo 保护（位于颜色/函数之后）之前就截断了脚本。保护现在是第一行可执行代码（set -euo pipefail 除外），因此即使在下载截断时也会触发。移除了颜色之后的重复保护。

之前版本: v3.9.20

修复：WSL2 上的 Docker 守护进程启动轮询 — 安装程序现在不再使用固定的 5 秒睡眠，而是在 service docker start 后每 2 秒轮询一次 docker info，最多 30 秒。同时显示 service docker start 的实际输出，以便启动错误可见，而不是被静默吞掉。

之前版本: v3.9.19

修复：WSL2 上的 Docker 守护进程启动 — WSL2 通常没有 systemd，因此 systemctl start docker 会静默失败。安装程序现在通过 /proc/version 检测 WSL2，并改用 sudo service docker start。如果安装后 Docker 仍未运行，则会显示清晰的 WSL2 特定错误，并附带确切的修复命令以及将其添加到 ~/.bashrc 以实现登录时自动启动的提示。

之前版本: v3.9.18

修复：阻止 sudo curl | bash 和 sudo bash install.sh — 通过 sudo 以 root 身份运行安装程序会破坏 GitHub CLI 身份验证：gh auth 将凭据存储在 /root/.config/gh/ 而不是真实用户的主目录中，导致后续所有 gh 调用失败。也会在 WSL 上导致 curl: (23) Failure writing output 管道错误。安装程序现在在启动时检测 SUDO_USER，并立即退出，并显示清晰的消息，告知用户在没有 sudo 的情况下重新运行。包安装的权限提升在内部处理。

之前版本: v3.9.17

修复：gh auth login 不得使用 sudo 运行 — 在 Linux/WSL 上自动安装 gh 后，安装程序现在明确告知用户不要使用 sudo 运行 gh auth login。如果之前使用 sudo 进行了身份验证，凭据会进入 /root/.config/gh/ 且对当前用户不可见，导致身份验证检查失败。安装后和身份验证检查步骤的错误消息现在都明确警告：不要对 gh auth 使用 sudo。

之前版本: v3.9.16

修复：安装程序可在 WSL 和非 root Linux 上工作 — 所有 Linux 包管理器命令 (apt-get, dnf, yum, zypper, pacman)、Docker 便捷脚本和 systemctl 调用现在在安装程序未以 root 身份运行时自动使用 sudo。Root 安装不受影响。修复了 WSL 和标准 Linux 桌面用户上的 Permission denied / 锁文件错误。

之前版本: v3.9.15

冷启动报告缓存在 /data/ 中 — analyze_codebase() 在首次运行后将报告保存到 /data/coldstart-<project>.md。后续调用会立即返回缓存的报告（<1s）。安装程序还在安装期间写入缓存，因此任何代理的第一次 MCP 调用都是即时的。使用 force=True 调用以在重大代码库更改后重新生成。
所有代理会话设置模板中的 analyze_codebase() — AGENTS.md, .cursor/rules/flaiwheel.mdc, CLAUDE.md 和 .github/copilot-instructions.md 现在都将其作为会话设置的第 3 步包含在内。代理在开始工作前会自动获得代码库概览。
Docker 重建前询问冷启动提示 — 所有交互式问题（嵌入模型 + 冷启动）现在都在前期批量处理，然后重建过程在无人值守的情况下运行。
修复：使用 docker exec 进行冷启动 — 将损坏的 MCP SSE 端点 HTTP 调用替换为直接的 docker exec python3。分析现在可以在约 20 秒内可靠地工作。

之前版本: v3.9.14

修复：快速路径总是提示冷启动 — 当存在缓存报告时不再静默跳过。

之前版本: v3.9.13

改进的冷启动分类 — 两阶段分类器：先进行路径启发式分析，再以代码特定的嵌入模板作为后备。

之前版本: v3.9.12

修复：在缓存检查前尊重 y/n 回答 — 显式的 y 现在即使在存在缓存报告时也会重新运行分析。

之前版本: v3.9.11

修复：全局作用域中的冷启动函数 — 将 _run_coldstart/_do_coldstart_analysis 移至脚本顶部，以便快速路径可以调用它们。

之前版本: v3.9.10

修复：版本检查 — `

flaiwheel