Flaiwheel
> AI编码代理的自托管内存和治理层。
> 把每一个bug修复变成永久知识。零云。零锁定。
🚀 为什么Flaiwheel存在
AI编码代理在会话之间会忘记一切。
这会导致重复的错误、丢失的架构决策和知识衰退。
Flaiwheel确保:
- 编码前进行代理搜索
- 修复后的代理文件
- 提交自动获取知识
- 记忆化合物随时间的变化
修复的每个错误都会使下一个错误更便宜。
🧠 Flaiwheel有何不同
- 复合的持久AI记忆 --知识不会在会话之间重置。
- Git原生自动化 --提交自动成为结构化知识。
- 治理,而不仅仅是存储 --质量门+强制文件。
- 混合搜索+重新排名 --真实代码库的高精度上下文。
- 完全自托管 --单个Docker容器,没有外部基础设施。
- 零锁定 --所有知识都以结构化平面文件的形式存储在Git中。
✅ Flaiwheel为谁服务
- 在实际项目中使用AI编码助手的工程团队
- 重复错误代价高昂的代码库
- 需要完全数据控制的团队
- AI原生开发环境
❌ 不是为了
- 几千行以下的小爱好项目
- 只想要更好的自动补全功能的开发人员
- 纯粹的SaaS工作流程,对自托管不感兴趣
🆚 哪里适合穿Flaiwheel
- AI编码工具生成代码。
- RAG工具检索文档。
- Flaiwheel在您自己的基础设施中管理和组合结构化的工程知识。
它不会取代你的AI助手。 这使得它在规模上可靠。
📄 白皮书(PDF) --深入的愿景、架构和设计。
⚙️ 关键技术特性
Flaiwheel是一个自包含的Docker服务,在三个级别上运行:
拉 --代理在编码之前进行搜索(search_docs, get_file_context)\
推 --代理人在工作时记录(write_bugfix_summary, write_architecture_doc, …)\
捕捉 --git通过提交后钩子提交自动捕获知识,即使没有AI代理
- 索引 您的项目文档(
.md,.pdf,.html,.docx,.rst,.txt,.json,.yaml,.csv)进入矢量数据库 - 提供MCP服务器 AI代理(Cursor、Claude Code、VS Code Copilot)连接到的
- 混合搜索 --通过互易秩融合(RRF)将语义向量搜索与BM25关键字搜索相结合,实现两全其美的检索
- 交叉编码器重定器 --可选的重新排序步骤,使用交叉编码器模型重新排序候选者,以显著提高词汇不匹配查询的精度
- 行为指示 --AI代理在每次响应前都会默默地搜索Flaiwheel,在每次任务后自动记录,并在重新创建前重用——所有这些都是在没有被要求的情况下进行的
get_file_context(filename)--预加载代理即将编辑的任何文件的空间知识(补充get_recent_sessions用于完整的时间+空间上下文)- 提交后git钩子 --捕捉每一个
fix:,feat:,refactor:,perf:,docs:自动提交为结构化知识文档 - 生活建筑 --指示AI代理维护系统组件和流程的自更新Mermaid.js图
- 可执行测试流程 --测试场景以机器可读的BDD/Gherkin格式记录(
Given,When,Then)用于QA自动化 - 从错误修复中学习 --代理编写可立即编入索引的错误修复摘要
- 结构化写入工具 -7种特定于类别的工具(错误修复、体系结构、API、最佳实践、设置、变更日志、测试用例),在源代码处强制执行质量
- 提交前验证 —
validate_doc()在自由标记进入知识库之前检查它 - 摄入质量门 --索引过程中会自动跳过有关键问题的文件(永远不会删除——您拥有自己的文件)
- 通过Git自动同步 --拉取并推送到专用知识库
- 工具遥测(持久) --跟踪每个项目的每个MCP调用(搜索、写入、未命中、模式),检测知识差距,并推动代理记录——在重启过程中持续存在,并在Web UI中可见
- 影响指标API —
/api/impact-metrics计算节省的估计时间+避免的回归;CI管道可以将护栏结果张贴到/api/telemetry/ci-guardrail-report - 主动质量检查 --每次重新索引后自动验证知识库
- 知识引导 --“就是这样”:分析杂乱的存储库,对文件进行分类,检测重复项,提出清理计划,在用户批准的情况下执行(从不删除文件)
- 冷启动代码库分析器 —
analyze_codebase(path)完全在服务器端扫描源代码目录(零令牌,零云)。使用Python的内置astPython的模块,TypeScript/JavaScript的正则表达式,用于分类和重复检测的现有MiniLM嵌入模型。返回单个bootstrap_report.md通过语言分布、类别图、前20个文件,按可文档性得分、重复对和覆盖差距排名第一。将旧代码库上的冷启动令牌成本降低约90%。 - 多项目支持 --一个容器以每个项目隔离的方式管理多个知识仓库
- 包括Web UI 用于配置、监控和测试
v3.9.40的新增功能
- 安装程序:
claude-md重复运行时不再失败 —claude mcp add非零出口(例如MCP已注册)在以下情况下不再中止并行阶段set -e;注册输出被安全捕获。 - 安装程序:GitHub上的正确发布版本 —
_FW_VERSION从刷新mainpyproject.toml当可访问时,即使是原始的,Docker的重建/版本检查也会与包保持一致install.sh上mainCDN滞后。
上一个:v3.9.29
- Glama工具检测修复 —
AuthManager以只读模式崩溃/data在MCP服务器启动之前(Glama看到0个工具的真正原因)。在stdio冷启动模式下跳过。 - stdout上的零print() --剩余36
print()在watcher、indexer、readers、bootstrap中替换为diag()(标准错误)。已验证:完整的MCP握手通过stdio返回所有28个工具。 config.save()坚韧的 --只读文件系统记录警告而不是崩溃。
上一个:v3.9.28
- Glama/MCP标准修复 --所有诊断输出都移动到stderr;stdout现在仅支持JSON-RPC。Glama Inspector现在可以正确检测所有28个工具。
- 改进的冷启动检测 --stdio冷启动逻辑正确处理空Docker卷(Glama检查期间没有引导/模型下载)。
上一个:v3.9.27
- 许可证清理 --一个
LICENSE用于正确检测GitHub/Glama的文件(BSL 1.1);所有文档和标题都指向LICENSE(不是LICENSE.md). - Glama/stdio检查 --可选
[inspect]deps和冷启动stdio路径,用于轻量级MCP目录构建。
上一个:v3.9.26
- 克劳德协作技能 --Flaiwheel工作流现在作为本地Claude技能分发。安装程序写入
.skills/skills/flaiwheel/SKILL.md到你的项目。当你在Claude(Cowork)中打开项目时,技能是自动可用的,不需要额外的设置。该技能驱动会话开始上下文恢复、预编码知识搜索、强制性错误修复后文档和会话结束总结。 - 技能来源也承诺
skills/flaiwheel/SKILL.md在这个仓库中,供参考和手动安装。
上一个:v3.9.25
- WSL2自动飞行前设置 --WSL2现在被自动检测到,并且在主安装程序流之前运行一个专用的飞行前块。无需手动操作:
1. 开关iptables到旧后端(修复Docker网络/DNAT错误)
1. 将当前用户添加到docker组(不再permission denied)
1. 通过以下方式启动Docker守护进程service(WSL2上没有系统)
1. 将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
- 修复:Docker守护进程在WSL2上启动时使用iptables遗留问题 --WSL2上的Docker经常无法静默启动,因为默认
iptables-nft后端不受支持。安装程序现在切换到iptables-legacy通过update-alternatives在启动Docker之前。还将当前用户添加到docker组自动。 - 所有安装命令更新为
bash <(curl ...)--整个脚本中显示的每个install/rerun命令(错误消息、AGENTS.md、Cursor规则等)现在都使用进程替换来避免WSL2管道问题。
上一个:v3.9.22
- 修复:
curl · bashWSL2上的管道写入失败 —curl · bash可能会失败curl: (23) Failure writing output由于管道/tmp权限问题,在WSL2上。README中的主要安装命令现在是bash <(curl ...)(工艺替代),完全避免了管道。re-exec块也会尝试$HOME作为回退临时目录/tmp写入失败。错误消息明确建议bash <(curl ...)形式。
上一个:v3.9.21
- 修复:sudo守卫在re-exec块之前移动 --何时
sudo curl | bash被使用curl: (23)管道错误在达到之前的sudo guard(位于颜色/函数之后)之前截断了脚本。警卫现在是第一个可执行行(set -euo pipefail旁白),因此即使在截断的下载上也会触发。去除颜色后重复防护。
上一个:v3.9.20
- 修复:WSL2上Docker守护进程启动轮询 --安装程序现在轮询,而不是固定的5秒睡眠
docker info每2秒一次,持续30秒service docker start。还显示了实际输出service docker start因此,启动错误是可见的,而不是默默地吞下。
上一个:v3.9.19
- 修复:Docker守护进程在WSL2上启动 --WSL2通常没有
systemd,所以systemctl start docker默默地失败了。安装程序现在通过以下方式检测WSL2/proc/version并使用sudo service docker start相反。如果Docker在安装后仍未运行,则会显示一个明确的WSL2特定错误,并显示精确的fix命令和添加它的提示~/.bashrc用于登录时自动启动。
上一个:v3.9.18
- 修复:阻塞
sudo curl | bash和sudo bash install.sh--通过以下方式以root身份运行安装程序sudo中断GitHub CLI身份验证:gh auth将凭据存储在/root/.config/gh/而不是真正的用户家,使每个后续gh呼叫失败。也造成curl: (23) Failure writing outputWSL上的管道错误。安装程序现在检测到SUDO_USER启动后立即退出,并显示一条明确的消息,告诉用户在没有sudo。软件包安装的权限升级由内部处理。
上一个:v3.9.17
- 修复:
gh auth login不得使用sudo运行 --自动安装后gh在Linux/WSL上,安装程序现在明确地“告诉”用户运行gh auth login没有sudo如果之前已使用完成身份验证sudo,凭据最终在/root/.config/gh/并且对当前用户不可见,导致身份验证检查失败。安装后和身份验证检查步骤中的错误消息现在都明确警告:不要使用sudogh auth.
上一个:v3.9.16
- 修复:安装程序在WSL和非root Linux上工作 --所有Linux包管理器命令(
apt-get,dnf,yum,zypper,pacman)Docker便利脚本,以及systemctl呼叫现在自动使用sudo当安装程序不是以root身份运行时。根安装不受影响。修复Permission denied/WSL和标准Linux桌面用户上的锁定文件错误。
上一个:v3.9.15
- 冷启动报告缓存在
/data/—analyze_codebase()将报告保存到/data/coldstart-.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
- 修复:全局范围内的coldstart函数 --移动
_run_coldstart/_do_coldstart_analysis到脚本顶部,快速路径可以调用它们。
上一个:v3.9.10
- 修复:版本检查 —
LATEST_VERSION现在使用_FW_VERSION直接不进行CDN获取。
上一个:v3.9.9
- 修复:所有路径上的冷启动 —
_run_coldstart()从快速路径、更新和新安装调用。智能缓存检测。
上一个:v3.9.8
- 冷启动报告缓存 —
analyze_codebase()缓存到/data/coldstart-.md即时阅读。新force=True参数。
上一个:v3.9.7
- 代理会话设置 --所有指令模板现在都包括
analyze_codebase()作为第一会话步骤。
上一个:v3.9.6
- 修复:使用docker exec --将对MCP SSE端点的中断HTTP调用替换为直接
docker exec python3调用。冷启动报告现在确实有效(~20s)。
上一个:v3.9.5
- 修复:预热嵌入模型 --在冷启动分析之前增加了模型预热(由v3.9.6取代)。
上一个:v3.9.4
- 修复:模型加载时冷启动重试问题 --安装程序现在重试
analyze_codebase()集装箱启动后长达90秒。
上一个:v3.9.3
- 修复:更新检测始终检查
main—LATEST_VERSION现在从main分支,使过时的缓存安装程序不再默默地跳过更新。
上一个:v3.9.2
- Docker重建前移动了冷启动提示 --所有的互动问题现在都是预先处理好的。
上一个:v3.9.1
- 冷启动提示已提前移动 --the
install.sh冷启动问题现在是在嵌入模型选择之后(在Docker重建之前)提出的,因此所有交互式问题都是首先收集的,用户在长时间重建后永远不会错过提示。
上一个:v3.9.0
analyze_codebase(path)--新的第28代MCP工具,用于对遗留代码库进行零令牌冷启动分析。在Docker中完全在服务器端运行。使用Pythonast、正则表达式、MiniLM嵌入和最近质心分类。返回排名bootstrap_report.md包括语言分布、类别图、按可文档性得分排名前20的文件、近乎重复的文件对,以及建议的下一步行动。将冷启动令牌成本降低约90%。
上一个:v3.8.3
- 项目添加时没有自动索引 --通过web UI添加项目不再立即提取和嵌入知识库。索引现在被推迟,直到明确触发(“Git Pull+Reindex”或
reindex()MCP工具),保持矢量数据库干净,直到审查了仓库。
上一个:v3.6.x
- VS代码/GitHubCopilot支持——安装程序编写
.vscode/mcp.json和.github/copilot-instructions.md. - Claude Desktop支持——安装程序通过以下方式自动配置Claude Desktop
mcp-remote. - Web UI客户端配置面板——添加了VS代码和Claude代码CLI选项卡。
上一个:v3.5.x
- 添加了克劳德桌面+克劳德代码CLI支持。
- README策略性地重写了定位、目标受众和竞争框架。
上一个:v3.4.x
- 搜索失败率修复--
search_bugfixes电话不再将错过率夸大到100%以上。 - 分类一致性--
_path_category_hint跨所有类别的统一基于令牌的方法。 CHANGELOG.md添加到repo根目录。
快速入门--一个命令(推荐)
先决条件: GitHub命令行界面 已认证(gh auth login), 码头工人 跑步。
平台支持: macOS和Linux开箱即用。开 视窗,从运行安装程序 Windows 子系统 for Linux 或 Git Bash (Docker Desktop必须在启用WSL 2后端的情况下运行)。
从项目目录中运行以下命令:```bash
bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)
> **WSL2/Linux注释:** 使用 `bash <(curl ...)` 上面的形式——它避免了 `curl: (23)` 以下情况发生的管道写入错误 `curl | bash` 在某些WSL2设置中。从不加前缀 `sudo`.
**就这样** 安装程序会自动执行以下操作:
1. 从git远程检测您的项目名称和GitHub组织
1. 创建私人 `-knowledge` 具有标准文件夹结构的repo
1. 启动指向该仓库的Flaiwheel Docker容器
1. 配置 **光标** --写 `.cursor/mcp.json` 和 `.cursor/rules/flaiwheel.mdc`
1. 配置 **VS代码/GitHub副本** --写 `.vscode/mcp.json` (本地SSE,VS代码1.99+)和 `.github/copilot-instructions.md`
1. 配置 **克劳德桌面版** (macOS应用程序)-写入 `claude_desktop_config.json` 通过 `mcp-remote` 桥(需要Node.js)
1. 配置 **Claude 代码命令行工具** --写 `.mcp.json` + `CLAUDE.md` 并奔跑 `claude mcp add` 如果CLI位于PATH上,则自动执行
1. 安装 **克劳德协作技能** --写 `.skills/skills/flaiwheel/SKILL.md` 因此,完整的Flaiwheel工作流程可作为Claude的本地技能使用
1. 写 `AGENTS.md` 对于所有其他代理
1. 如果存在 `.md` 找到文档,创建迁移指南——人工智能将提供将它们组织到知识库中的功能
**安装后:**
|代理|该怎么办|
|-------|------------|
| **光标** |重新启动游标→ 设置→ MCP → 启用 `flaiwheel` 切换|
| **克劳德桌面版** (macOS应用程序)|退出并重新打开Claude for Mac-连接时出现锤子图标|
| **Claude 代码命令行工具** |已自动注册--运行 `/mcp` 在Claude Code内部进行验证|
| **VS Code** |开放项目→ 命令面板→ **MCP:列出服务器** → start `flaiwheel` |
| **克劳德(合作)** |技能自动加载自 `.skills/skills/flaiwheel/SKILL.md` --无需采取进一步行动|
安装程序还设置了 **提交后git钩子** 自动捕捉每一个 `fix:`, `feat:`, `refactor:`, `perf:`,以及 `docs:` 以结构化知识文档的形式提交——无需代理或手动操作。
一旦连接,AI就可以访问所有Flaiwheel工具。如果你有现有的文档,告诉AI: *“迁移文档”*.
______________________________________________________________________
## 可选:打开终端本地守护程序(打开WebUI)
如果您还使用Open WebUI的Open Terminal集成,则此仓库包括用于本地 `open-terminal` 守护进程。
第三方报告(例如 AI·Collab——开放式终端)可能仅镜像Linux脚本; **macOS** 用途 `scripts/macos/install-open-terminal-launchagent.sh` 在......下面在任何镜像更新后,请使用以下命令重新检查文件 `shasum -a 256` GitHub上的同一版本。
### 通过以下方式安装一个衬里 `curl` (无git克隆)
使用 **`main`** 或固定a **提交SHA** / **标签** 在可再现字节的URL中。
**Linux/WSL2** (`systemd --user`):```bash
curl -fsSL -o install-open-terminal-systemd-user.sh \
https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install-open-terminal-systemd-user.sh
/bin/chmod +x install-open-terminal-systemd-user.sh
/bin/bash ./install-open-terminal-systemd-user.sh
macOS (LaunchAgent;执行 不 使用 sudo):```bash
curl -fsSL -o install-open-terminal-launchagent.sh \
https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/macos/install-open-terminal-launchagent.sh
/bin/chmod +x install-open-terminal-launchagent.sh
/bin/bash ./install-open-terminal-launchagent.sh
如果 `chmod` 或 `bash` “未找到”,你的 `PATH` 坏了(通常是康达 `base`) `/bin/…` 上面的路径仍然有效。
### Linux/WSL2(`systemd --user`)```bash
./scripts/install-open-terminal-systemd-user.sh
- 服务名称:
com.flaiwheel.open-terminal-local.service - 默认端点:
http://localhost:8000 - 脚本自动生成API密钥,并在安装/重置后打印该密钥。
- 在WSL2上,确保
systemd=true在中启用/etc/wsl.conf.
有用的命令:```bash
systemctl --user status com.flaiwheel.open-terminal-local.service
journalctl --user -u com.flaiwheel.open-terminal-local.service -f
### macOS(`launchctl` LaunchAgent)```bash
./scripts/macos/install-open-terminal-launchagent.sh
- LaunchAgent标签:
com.flaiwheel.open-terminal-local - 默认端点:
http://localhost:8000 - 脚本自动生成API密钥,并在安装/重置后打印该密钥。
- LaunchAgent设置 工作目录 到
$HOME默认情况下,Open Terminal不会在中启动/private/tmp. - 路径:
launchd不加载~/.zshrc,因此守护进程过去只能看到/usr/bin:/bin:…想念Homebrew/Supabase CLI。生成的包装器将作为前缀/opt/homebrew/bin,/usr/local/bin,~/.local/bin,以及~/.npm-global/bin.重新运行安装程序(菜单 →1 更新)拉动此更改后,包装将重新生成。 - 持久自定义文件夹: 安装程序可以在中保存路径
~/.config/flaiwheel/open-terminal-working-directory(新安装提示或菜单 →5 重新运行脚本时)。 更新(菜单→1) 继续使用保存的路径。一次性覆盖:设置OPEN_TERMINAL_WORKING_DIRECTORY只为这次跑步。
环境覆盖(两个脚本):```bash
HOST=127.0.0.1 PORT=8000 OPEN_TERMINAL_CORS_ALLOWED_ORIGINS='https://your-openwebui.example' ./scripts/install-open-terminal-systemd-user.sh
``````bash
HOST=127.0.0.1 PORT=8000 OPEN_TERMINAL_CORS_ALLOWED_ORIGINS='https://your-openwebui.example' ./scripts/macos/install-open-terminal-launchagent.sh
仅限macOS——Open Terminal的自定义初始文件夹(保存前必须存在):```bash
OPEN_TERMINAL_WORKING_DIRECTORY="$HOME/projects/my-repo" ./scripts/macos/install-open-terminal-launchagent.sh
重新运行相同的脚本并选择 5 更改或清除已保存的文件夹(或编辑 ~/.config/flaiwheel/open-terminal-working-directory).非交互式安装:在上面设置env-var或用单行(路径)创建该文件;使用 AUTO_INSTALL_DEPS=1 跳过第一个运行路径提示。
更新
从项目目录再次运行相同的安装命令:```bash
bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)
安装程序检测到现有容器,要求确认,然后:
- 使用最新代码重建Docker镜像
- 重新创建容器(保留您的数据量+配置)
- 刷新所有代理配置和指南
您的知识库、索引和凭据将被保留,只有代码会被更新。
______________________________________________________________________
## 手动设置
Click to expand manual steps
### 1.创建知识库```bash
# On GitHub, create: -knowledge (private repo)
mkdir -p architecture api bugfix-log best-practices setup changelog
echo "# Project Knowledge Base" > README.md
git add -A && git commit -m "init" && git push
2.构建并启动Flaiwheel```bash
git clone https://github.com/dl4rce/flaiwheel.git /tmp/flaiwheel-build
docker build -t flaiwheel:latest /tmp/flaiwheel-build
docker run -d \
--name flaiwheel \
-p 8080:8080 \
-p 8081:8081 \
-e MCP_GIT_REPO_URL=https://github.com/you/yourproject-knowledge.git \
-e MCP_GIT_TOKEN=ghp_your_token \
-v flaiwheel-data:/data \
flaiwheel:latest
### 3.连接您的AI代理
**光标** --添加到 `.cursor/mcp.json`:```json
{
"mcpServers": {
"flaiwheel": {
"type": "sse",
"url": "http://localhost:8081/sse"
}
}
}
VS代码/GitHub副本 (1.99+)--添加到 .vscode/mcp.json:```json
{
"servers": {
"flaiwheel": {
"type": "sse",
"url": "http://localhost:8081/sse"
}
}
}
然后:命令面板→ **MCP:列出服务器** → start `flaiwheel`.
**克劳德桌面版** (macOS应用程序)-添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"flaiwheel": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:8081/sse"]
}
}
}
需要Node.js。编辑后重新启动Claude for Mac。
Claude 代码命令行工具 --在项目目录中运行一次:```bash
claude mcp add --transport sse --scope project flaiwheel http://localhost:8081/sse
### 4.完成。开始编码。
______________________________________________________________________
## 知识回购结构```
yourproject-knowledge/
├── README.md ← overview / index
├── architecture/ ← system design, decisions, diagrams
├── api/ ← endpoint docs, contracts, schemas
├── bugfix-log/ ← auto-generated bugfix summaries
│ └── 2026-02-25-fix-payment-retry.md
├── best-practices/ ← coding standards, patterns
├── setup/ ← deployment, environment setup
├── changelog/ ← release notes
└── tests/ ← test cases, scenarios, regression patterns
支持的输入格式
Flaiwheel索引9种文件格式。所有非markdown文件在索引时都会在内存中转换为类似markdown的文本——磁盘上没有生成的文件,也没有仓库混乱。
| 格式 | 扩展名 | 工作原理 |
|---|---|---|
| 标记语言 | .md |
本地(传递) |
| 纯文本 | .txt |
包裹在 # filename 标题 |
.pdf |
通过以下方式提取每页文本 pypdf |
|
| 超文本标记语言 | .html, .htm |
标题/列表/代码转换为markdown,脚本被删除 |
| 重新结构化文本 | .rst |
标题下划线已转换为 # 级别、代码块保留 |
| 字 | .docx |
段落+标题样式映射到markdown |
| JSON | .json |
漂亮的印在围栏里 json 代码块 |
| YAML | .yaml, .yml |
用栅栏包着 yaml 代码块 |
| 逗号分隔值 | .csv |
转换为markdown表 |
质量检查(结构、完整性、错误修复格式)仅适用于 .md 文件夹。其他格式按原样索引。
配置
所有配置均通过环境变量进行(MCP_ 前缀),Web UI(http://localhost:8080),或 .env 文件。
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_DOCS_PATH |
/docs |
容器内.md文件的路径 |
MCP_EMBEDDING_PROVIDER |
local |
local (免费、私人)或 openai |
MCP_EMBEDDING_MODEL |
all-MiniLM-L6-v2 |
嵌入模型名称 |
MCP_CHUNK_STRATEGY |
heading |
heading, fixed,或 hybrid |
MCP_RERANKER_ENABLED |
false |
启用交叉编码器重新分级器以获得更高的精度 |
MCP_RERANKER_MODEL |
cross-encoder/ms-marco-MiniLM-L-6-v2 |
重新排序模型名称 |
MCP_RRF_K |
60 |
RRF k参数(越低=排名靠前的权重越大) |
MCP_RRF_VECTOR_WEIGHT |
1.0 |
RRF融合中的向量搜索权重 |
MCP_RRF_BM25_WEIGHT |
1.0 |
RRF融合中BM25关键字搜索权重 |
MCP_MIN_RELEVANCE |
0 |
返回的最小相关性百分比(0=无过滤器) |
MCP_GIT_REPO_URL |
知识库URL(启用git同步) | |
MCP_GIT_BRANCH |
main |
要同步的分支 |
MCP_GIT_TOKEN |
私有仓库的GitHub代币 | |
MCP_GIT_SYNC_INTERVAL |
300 |
拉取间隔(秒)(0=禁用) |
MCP_GIT_AUTO_PUSH |
true |
自动提交+推送错误修复摘要 |
MCP_WEBHOOK_SECRET |
GitHub webhook密钥(启用 /webhook/github HMAC验证) |
|
MCP_TRANSPORT |
sse |
MCP传输: sse 或 stdio |
MCP_SSE_PORT |
8081 |
MCP SSE端点端口 |
MCP_WEB_PORT |
8080 |
Web UI端口 |
多回购支持
一个Flaiwheel容器可以管理多个知识库——每个项目一个。每个项目都有自己的ChromaDB集合、git监视器、索引锁、健康跟踪器和质量检查器,同时在RAM中共享一个嵌入模型和一个MCP/Web端点。
它是如何工作的:
- 第一
install.shrun使用项目A创建Flaiwheel容器 - 随后的
install.sh从其他项目目录运行检测正在运行的容器,并通过API注册新项目-没有其他容器 - 所有MCP工具都接受可选
project参数(例如。,search_docs("query", project="my-app")) - 呼叫
set_project("my-app")在每次对话开始时,将所有后续调用绑定到该项目(粘性会话) - 没有明确的
project参数,活动项目(通过设置set_project)使用;如果没有设置,则使用第一个项目 - Web UI有一个项目选择器下拉列表,用于在项目之间切换
- 使用
list_projects()通过MCP查看所有已注册的项目(显示活动标记)
添加/删除项目:
- 通过AI代理: 呼叫
setup_project(name="my-app", git_repo_url="...")--寄存器、克隆、索引和自动绑定 - 通过安装脚本: 跑
install.sh从新项目目录(自动注册) - 通过Web UI: 单击项目选择栏中的“添加项目”
- 通过API:
POST /api/projects随着{name, git_repo_url, git_branch, git_token} - 删除:
DELETE /api/projects/{name}或Web UI中的“删除”按钮
向后兼容性: 现有的单个项目设置将继续工作而不进行更改。如果不 projects.json 存在,但 MCP_GIT_REPO_URL 如果设置好,Flaiwheel会自动从env变量创建一个项目。
嵌入模型热交换
当您通过Web UI更改嵌入模型时,Flaiwheel会使用阴影集合在后台重新嵌入所有文档。在迁移运行期间,旧型号上的搜索仍然完全可用。一旦完成,新索引将自动替换旧索引——零停机时间。
Web UI显示了一个实时进度条,其中包含文件计数和百分比。您可以随时取消。
嵌入模型(本地,免费)
| 型号 | RAM | 质量 | 最适合 |
|---|---|---|---|
all-MiniLM-L6-v2 |
90MB | 78% | 存储库大,RAM低 |
nomic-ai/nomic-embed-text-v1.5 |
520MB | 87% | 最佳英语质量 |
通过Web UI选择或 MCP_EMBEDDING_MODEL env var.Web UI中的完整列表。
交叉编码器重排器(可选)
重新排序器是一个第二阶段模型,用于重新排序混合搜索中的顶级候选对象。全文如下 (query, document) 配对,这比独立嵌入产生更准确的相关性得分,尤其是对于用户和文档对同一概念使用不同单词的词汇不匹配查询。
它是如何工作的:
- 混合搜索(向量+BM25)检索更广泛的候选池(
top_k × 5) - RRF对候选人进行合并和排名
- 交叉编码器重新排序排名靠前的候选者,只返回最好的候选者
top_k
通过Web UI启用 (搜索和检索卡)或环境变量:```bash
docker run -d \
-e MCP_RERANKER_ENABLED=true \
-e MCP_RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2 \
...
|Reranker型号|RAM|速度|质量|
|----------------|-----|-------|---------|
| `cross-encoder/ms-marco-MiniLM-L-6-v2` |90MB |快速|良好--最佳速度/质量平衡|
| `cross-encoder/ms-marco-MiniLM-L-12-v2` |130MB |中等|更好——精度更高|
| `BAAI/bge-reranker-base` |420MB |较慢|最好——最先进的精度|
重新登录的是 **默认情况下关闭** (零开销)。启用后,每次搜索会增加约50毫秒的延迟,但通常会将词汇不匹配查询的精度提高10-25%。
### GitHub Webhook(即时重新索引)
与其等待300秒的轮询间隔,不如配置一个GitHub webhook,以便在推送时立即重新索引:
1. 在GitHub上的知识仓库中: **设置→ 网络钩子→ 添加webhook**
1. **有效载荷URL:** `http://your-server:8080/webhook/github`
1. **内容类型:** `application/json`
1. **秘密:** 设置与相同的值 `MCP_WEBHOOK_SECRET`
1. **活动:** 选择“仅推送事件”
如果满足以下条件,webhook端点将验证HMAC签名 `MCP_WEBHOOK_SECRET` 已设置。如果没有秘密,任何POST都会触发pull+reindex。
### CI护栏遥测(ROI跟踪)
在Flaiwheel中直接跟踪非虚荣工程影响:
- **发布** `/api/telemetry/ci-guardrail-report` --CI根据PR报告护栏发现/修复情况
- **获取** `/api/impact-metrics?project=&days=30` --回报估计节省了时间+避免了回归
有效载荷示例:```json
{
"project": "my-app",
"violations_found": 4,
"violations_blocking": 1,
"violations_fixed_before_merge": 2,
"cycle_time_baseline_minutes": 58,
"cycle_time_actual_minutes": 43,
"pr_number": 127,
"branch": "feature/payment-fix",
"commit_sha": "abc1234",
"source": "github-actions"
}
Flaiwheel将遥测数据保存在磁盘上(/telemetry)因此,度量在容器重启和更新后仍然有效。
差异感知重新索引
默认情况下,重新索引是增量的——只有自上次运行以来内容发生更改的文件才会被重新嵌入。在500个文件的仓库中,这意味着在单个文件推送花费\<1s后,通常会重新索引,而不是重新嵌入所有内容。
使用 reindex(force=True) 通过MCP或Web UI的“重新索引”按钮强制完全重建(例如在更改嵌入模型后)。
建筑```
┌─────────────────────────────────────────────────────────────┐
│ Docker Container (single process, N projects) │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ Web-UI (FastAPI) Port 8080 │ │
│ │ Project CRUD, config, monitoring, search, health │ │
│ └─────────────────────┬─────────────────────────────────┘ │
│ │ shared state (ProjectRegistry) │
│ ┌─────────────────────┴─────────────────────────────────┐ │
│ │ MCP Server (FastMCP) Port 8081 │ │
│ │ 28 tools (search, write, classify, manage, projects) │ │
│ └─────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────┴─────────────────────────────────┐ │
│ │ Shared Embedding Model (1× in RAM) │ │
│ └─────────────────────┬─────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────┴────────────────────────────────┐ │
│ │ Per-Project Contexts (isolated) │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Project A │ │ Project B │ │ Project C │ │ │
│ │ │ collection │ │ collection │ │ collection │ │ │
│ │ │ watcher │ │ watcher │ │ watcher │ │ │
│ │ │ lock │ │ lock │ │ lock │ │ │
│ │ │ health │ │ health │ │ health │ │ │
│ │ │ quality │ │ quality │ │ quality │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
│ /docs/{project}/ ← per-project knowledge repos │
│ /data/ ← shared vectorstore + config + projects │
└─────────────────────────────────────────────────────────────┘
### 搜索管道```
query
│
├──► Vector Search (ChromaDB/HNSW, cosine similarity)
│ fetch top_k (or top_k×5 if reranker enabled)
│
├──► BM25 Keyword Search (bm25s, English stopwords)
│ fetch top_k (or top_k×5 if reranker enabled)
│
├──► RRF Fusion (configurable k, vector/BM25 weights)
│ merge + rank candidates
│
├──► [optional] Cross-Encoder Reranker
│ rescore (query, doc) pairs for higher precision
│
├──► Min Relevance Filter (configurable threshold)
│
└──► Return top_k results with relevance scores
Web 用户界面
访问地址: http://localhost:8080 (HTTP基本身份验证——首次启动时显示的凭据)。
特征:
- 系统健康面板:最后一个索引、最后一个git pull、git commit、版本、搜索指标、质量分数、跳过文件计数
- 索引状态和统计数据(包括重新登录状态)
- 嵌入模型选择(视觉选择器)
- 搜索和检索调优:交叉编码器重新排序器切换+模型选择器、RRF权重、最小相关性阈值
- 分块策略配置
- Git同步设置(URL、分支、自动推送切换)
- 测试搜索界面
- 知识质量检查器(每次重新索引后也会自动运行)
- 搜索指标(点击率/总数、错过率、每个工具的细分)
- 跳过文件指示器(由于严重质量问题,文件被排除在索引之外)
- “就是这样”——知识引导:代理驱动的项目分类+仓库内清理(Web UI显示指导+高级扫描)
- 多项目切换器(从一个实例管理多个仓库)
- 客户端配置片段(Cursor、Claude Desktop、Docker)
- 密码管理
发展```bash
Clone
git clone https://github.com/dl4rce/flaiwheel.git
cd flaiwheel
Install
pip install -e ".[dev]"
Run tests (259 tests covering readers, quality checker, indexer, reranker, health tracker, MCP tools, model migration, multi-project, bootstrap, classification, file-context, cold-start analyzer)
pytest
Run locally (needs /docs and /data directories)
mkdir -p /tmp/flaiwheel-docs /tmp/flaiwheel-data
MCP_DOCS_PATH=/tmp/flaiwheel-docs MCP_VECTORSTORE_PATH=/tmp/flaiwheel-data python -m flaiwheel
```
许可证
商业来源许可证1.1(BSL 1.1)
Flaiwheel来源于 商业来源许可证1.1.
您可以免费使用Flaiwheel 如果:
- 你的用途是 非商业性的 (个人、教育、无收入),或
- 您的组织有 不超过10人 使用它
超出这些限制的商业用途 (例如11+团队或商业部署)需要付费许可证。
- 有效的 2030-02-25,此版本转换为 Apache许可证2.0 (完全开源)
- 商业许可证: info@4rce.com | https://4rce.com
看 许可证 完整条款。
