flaiwheel (Dl4rce)

MCP开发工具

提供方 dl4rce

开发工具 stdio · 本地进程 会话登录 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

Flaiwheel是一个自托管的AI编程代理知识治理层,通过Git原生自动化、混合搜索和强制执行文档规范,实现工程知识的持久化积累和复用。

一句话选型结论

按资料字段整理

flaiwheel (Dl4rce) 属于开发工具类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 29 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量29暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

AI编程辅助Python本地部署知识管理Git集成自托管代码质量治理向量搜索

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
docker run -d \

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Docker,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 29 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 29 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
flaiwheel (Dl4rce)当前 29 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方dl4rce上游标注的维护方 dl4rce
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Docker本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

39.8 KB
来自项目仓库与上游目录的原文,未做删改

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 <(curl ...) --整个脚本中显示的每个install/rerun命令(错误消息、AGENTS.md、Cursor规则等)现在都使用进程替换来避免WSL2管道问题。

上一个:v3.9.22

  • 修复: curl · bash WSL2上的管道写入失败 — 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 output WSL上的管道错误。安装程序现在检测到 SUDO_USER 启动后立即退出,并显示一条明确的消息,告诉用户在没有 sudo。软件包安装的权限升级由内部处理。

上一个:v3.9.17

  • 修复: gh auth login 不得使用sudo运行 --自动安装后 gh 在Linux/WSL上,安装程序现在明确地“告诉”用户运行 gh auth login 没有 sudo如果之前已使用完成身份验证 sudo,凭据最终在 /root/.config/gh/ 并且对当前用户不可见,导致身份验证检查失败。安装后和身份验证检查步骤中的错误消息现在都明确警告:不要使用sudo gh 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中完全在服务器端运行。使用Python ast、正则表达式、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)


&gt; **WSL2/Linux注释:** 使用 `bash &lt;(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=&quot;$HOME/projects/my-repo&quot; ./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 &quot;# Project Knowledge Base&quot; &gt; README.md
git add -A &amp;&amp; git commit -m &quot;init&quot; &amp;&amp; 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
{
&quot;mcpServers&quot;: {
&quot;flaiwheel&quot;: {
&quot;type&quot;: &quot;sse&quot;,
&quot;url&quot;: &quot;http://localhost:8081/sse&quot;
}
}
}

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
{
&quot;mcpServers&quot;: {
&quot;flaiwheel&quot;: {
&quot;command&quot;: &quot;npx&quot;,
&quot;args&quot;: [&quot;-y&quot;, &quot;mcp-remote&quot;, &quot;http://localhost:8081/sse&quot;]
}
}
}

需要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 .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.sh run使用项目A创建Flaiwheel容器
  • 随后的 install.sh 从其他项目目录运行检测正在运行的容器,并通过API注册新项目-没有其他容器
  • 所有MCP工具都接受可选 project 参数(例如。, search_docs(&quot;query&quot;, project=&quot;my-app&quot;))
  • 呼叫 set_project(&quot;my-app&quot;) 在每次对话开始时,将所有后续调用绑定到该项目(粘性会话)
  • 没有明确的 project 参数,活动项目(通过设置 set_project)使用;如果没有设置,则使用第一个项目
  • Web UI有一个项目选择器下拉列表,用于在项目之间切换
  • 使用 list_projects() 通过MCP查看所有已注册的项目(显示活动标记)

添加/删除项目:

  • 通过AI代理: 呼叫 setup_project(name=&quot;my-app&quot;, git_repo_url=&quot;...&quot;) --寄存器、克隆、索引和自动绑定
  • 通过安装脚本: 跑 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) 配对,这比独立嵌入产生更准确的相关性得分,尤其是对于用户和文档对同一概念使用不同单词的词汇不匹配查询。

它是如何工作的:

  1. 混合搜索(向量+BM25)检索更广泛的候选池(top_k × 5)
  2. RRF对候选人进行合并和排名
  3. 交叉编码器重新排序排名靠前的候选者,只返回最好的候选者 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=&amp;days=30` --回报估计节省了时间+避免了回归

有效载荷示例:```json
{
&quot;project&quot;: &quot;my-app&quot;,
&quot;violations_found&quot;: 4,
&quot;violations_blocking&quot;: 1,
&quot;violations_fixed_before_merge&quot;: 2,
&quot;cycle_time_baseline_minutes&quot;: 58,
&quot;cycle_time_actual_minutes&quot;: 43,
&quot;pr_number&quot;: 127,
&quot;branch&quot;: &quot;feature/payment-fix&quot;,
&quot;commit_sha&quot;: &quot;abc1234&quot;,
&quot;source&quot;: &quot;github-actions&quot;
}

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

看 许可证 完整条款。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
flaiwheel (Dl4rce) 怎么安装?

在客户端按下面的安装命令接入:docker run -d \。装完在客户端配置里引用同一个包或端点。

flaiwheel (Dl4rce) 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

flaiwheel (Dl4rce) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

flaiwheel (Dl4rce) 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

flaiwheel (Dl4rce) 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

flaiwheel (Dl4rce) 能提供哪些能力?

资料显示约 29 个工具;能力标签包括 AI编程辅助、Python、Claude、向量搜索。具体工具清单以官方文档为准。

flaiwheel (Dl4rce) 需要什么运行环境?

运行时为 Docker;属于本地进程,需要在本机装好运行环境。

flaiwheel (Dl4rce) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。