flaiwheel (Dl4rce)

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的内置 ast Python的模块，TypeScript/JavaScript的正则表达式，用于分类和重复检测的现有MiniLM嵌入模型。返回单个 bootstrap_report.md 通过语言分布、类别图、前20个文件，按可文档性得分、重复对和覆盖差距排名第一。将旧代码库上的冷启动令牌成本降低约90%。
• 多项目支持 --一个容器以每个项目隔离的方式管理多个知识仓库
• 包括Web UI 用于配置、监控和测试

______________________________________________________________________

v3.9.40的新增功能

• 安装程序： claude-md 重复运行时不再失败 — claude mcp add 非零出口（例如MCP已注册）在以下情况下不再中止并行阶段 set -e；注册输出被安全捕获。
• 安装程序：GitHub上的正确发布版本 — _FW_VERSION 从刷新 main pyproject.toml 当可访问时，即使是原始的，Docker的重建/版本检查也会与包保持一致 install.sh 上 main CDN滞后。

上一个：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 WSL2/Linux注释：** 使用 `bash

Click to expand manual steps

1.创建知识库

# 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

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:

{
  "mcpServers": {
    "flaiwheel": {
      "type": "sse",
      "url": "http://localhost:8081/sse"
    }
  }
}

VS代码/GitHub副本 （1.99+）--添加到 .vscode/mcp.json:

{
  "servers": {
    "flaiwheel": {
      "type": "sse",
      "url": "http://localhost:8081/sse"
    }
  }
}

然后：命令面板→ MCP：列出服务器 → start flaiwheel.

克劳德桌面版 （macOS应用程序）-添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flaiwheel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8081/sse"]
    }
  }
}

需要Node.js。编辑后重新启动Claude for Mac。

Claude 代码命令行工具 --在项目目录中运行一次：

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 文件夹。其他格式按原样索引。

______________________________________________________________________

配置

所有配置均通过环境变量进行(MCP_ 前缀），Web UI(http://localhost:8080)，或 .env 文件。

多回购支持

一个Flaiwheel容器可以管理多个知识库——每个项目一个。每个项目都有自己的ChromaDB集合、git监视器、索引锁、健康跟踪器和质量检查器，同时在RAM中共享一个嵌入模型和一个MCP/Web端点。

它是如何工作的：

• 第一 install.sh run使用项目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显示了一个实时进度条，其中包含文件计数和百分比。您可以随时取消。

嵌入模型（本地，免费）

通过Web UI选择或 MCP_EMBEDDING_MODEL env var.Web UI中的完整列表。

交叉编码器重排器（可选）

重新排序器是一个第二阶段模型，用于重新排序混合搜索中的顶级候选对象。全文如下 (query, document) 配对，这比独立嵌入产生更准确的相关性得分，尤其是对于用户和文档对同一概念使用不同单词的词汇不匹配查询。

它是如何工作的：

1. 混合搜索（向量+BM25）检索更广泛的候选池(top_k × 5)
2. RRF对候选人进行合并和排名
3. 交叉编码器重新排序排名靠前的候选者，只返回最好的候选者 top_k

通过Web UI启用 （搜索和检索卡）或环境变量：

docker run -d \
  -e MCP_RERANKER_ENABLED=true \
  -e MCP_RERANKER_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2 \
  ...

重新登录的是 默认情况下关闭 （零开销）。启用后，每次搜索会增加约50毫秒的延迟，但通常会将词汇不匹配查询的精度提高10-25%。

GitHub Webhook（即时重新索引）

与其等待300秒的轮询间隔，不如配置一个GitHub webhook，以便在推送时立即重新索引：

1. 在GitHub上的知识仓库中： 设置→ 网络钩子→ 添加webhook
2. 有效载荷URL： http://your-server:8080/webhook/github
3. 内容类型： application/json
4. 秘密： 设置与相同的值 MCP_WEBHOOK_SECRET
5. 活动： 选择“仅推送事件”

如果满足以下条件，webhook端点将验证HMAC签名 MCP_WEBHOOK_SECRET 已设置。如果没有秘密，任何POST都会触发pull+reindex。

CI护栏遥测（ROI跟踪）

在Flaiwheel中直接跟踪非虚荣工程影响：

• 发布 /api/telemetry/ci-guardrail-report --CI根据PR报告护栏发现/修复情况
• 获取 /api/impact-metrics?project=&days=30 --回报估计节省了时间+避免了回归

有效载荷示例：

{
  "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）
• 密码管理

______________________________________________________________________

发展

# 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

看 许可证 完整条款。