Flaiwheel 是一个自托管的记忆与治理层，专为 AI 编程智能体设计，目标是把每一次 bug 修复变成永久知识，实现零云依赖、零锁定。
【用途】 AI 编程智能体在会话之间会遗忘一切，导致重复 bug、架构决策丢失和知识衰减。Flaiwheel 让智能体在编码前先检索、修复后写文档，提交自动捕获知识，使记忆随时间复利增长——每修复一个 bug，下一个 bug 的成本就更低。它不替代 AI 助手，而是让助手在规模化时保持可靠。
【主要能力】
- 持久化 AI 记忆：知识不会在会话间重置。
- Git 原生自动化：提交自动转化为结构化知识。
- 治理而非仅存储：质量门禁 + 强制文档化。
- 混合检索 + 重排序：为真实代码库提供高精度上下文。
- 完全自托管：单个 Docker 容器，无外部基础设施。
- 零锁定：所有知识以结构化扁平文件存储在 Git 中。
【技术特性】 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）连接。混合检索结合语义向量搜索与 BM25 关键词搜索，通过 Reciprocal Rank Fusion（RRF）实现两者兼得的检索效果；可选的交叉编码器重排序步骤会用交叉编码器模型对候选结果重新打分，在词汇不匹配的查询上显著提高精度。
行为指令（Behavioral Directives）让 AI 智能体在每次响应前静默检索 Flaiwheel、每次任务后自动记录、在重建前先复用，无需人工要求。get_file_context(filename) 为智能体即将编辑的文件预加载空间知识（与 get_recent_sessions 互补，提供完整的时间 + 空间上下文）。post-commit git 钩子自动把 fix:、feat:、refactor:、perf:、docs: 提交捕获为结构化知识文档。Living Architecture 要求 AI 智能体维护自更新的 Mermaid.js 系统组件与流程图表。可执行测试流程以机器可读的 BDD/Gherkin 格式（Given、When、Then）记录测试场景，用于 QA 自动化。智能体编写 bugfix 摘要后会被立即索引。
结构化写入工具包含 7 个类别专用工具（bugfix、architecture、API、best-practice、setup、changelog、test case），在源头强制质量。结构化关系（v1）通过 relations() 和 timeline() 从现有文档的可选 YAML frontmatter（id、replaces、depends_on、fixes、implements、status）推导出每个项目的知识图谱，不设第二存储——markdown 保持权威，Git 历史即有效期窗口。pre-commit 校验通过 validate_doc() 在自由格式 markdown 进入知识库前进行检查，包括未知关系键警告。摄取质量门禁会在索引时自动跳过存在严重问题的文件（绝不删除——文件归你所有）。通过 Git 自动同步，向专用知识仓库拉取和推送。
工具遥测（持久化）按项目跟踪每次 MCP 调用（检索、写入、未命中、模式），检测知识缺口并推动智能体记录，跨重启持久化并在 Web UI 中可见。影响指标 API /api/impact-metrics 计算预估节省时间与避免的回归；CI 流水线可将护栏结果提交到 /api/telemetry/ci-guardrail-report。主动质量检查在每次重建索引后自动校验知识库。Knowledge Bootstrap（“This is the Way”）分析杂乱仓库、分类文件、检测重复、提出清理计划并在用户批准后执行（绝不删除文件）。
冷启动代码库分析器 analyze_codebase(path) 完全在服务端扫描源代码目录（零 token、零云）。对 Python 使用内置 ast 模块，对 TypeScript/JavaScript 使用正则，用现有 MiniLM 嵌入模型进行分类和重复检测。返回单个 bootstrap_report.md，包含语言分布、类别映射、按可文档化评分排序的前 20 个优先文档化文件、重复对和覆盖缺口。在遗留代码库上可减少约 90% 的冷启动 token 成本。
多项目支持：一个容器管理多个知识仓库，按项目隔离。包含用于配置、监控和测试的 Web UI。
【使用方式】 以单个 Docker 容器自托管部署，通过 MCP 服务器连接 AI 编程智能体。默认使用纯 HTTP 端点 http://host:8081/sse，这是推荐配置，直到 Web UI 提供 TLS 激活、CA 下载和操作系统安装说明。更新会保留现有模式，除非显式设置 FLAIWHEEL_TLS_AUTO=0 或 1。自动 TLS 为可选功能：设置 MCP_SSE_TLS_AUTO=true 后，Flaiwheel 在首次启动时生成私有 CA 和服务器证书，覆盖配置的主机与回环地址；材料持久化在 /data/tls 并在有效且仍覆盖请求名称时复用。但容器无法让另一台机器信任该 CA，启动日志会打印指纹和客户端环境块所需的 NODE_EXTRA_CA_CERTS=... 行。远程 MCP 无需反向代理：设置 MCP_SSE_ALLOWED_HOSTS=flaiwheel.example.com 即可直接连接；原生 TLS 可设置 MCP_SSE_TLS_CERTFILE + MCP_SSE_TLS_KEYFILE 直接以 HTTPS 提供服务。TLS 失败即关闭：半配置或不可读的证书会中止启动，而非静默提供明文。
【适用场景】 适合在真实项目中使用 AI 编程助手的工程团队、重复 bug 代价高昂的代码库、需要完全数据控制的团队、AI 原生开发环境。
【限制】 不适合几千行以下的小型业余项目，也不适合只想要更好自动补全的开发者，以及无意自托管的纯 SaaS 工作流。
【版本要点】 v3.15.3：纯 HTTP 仍为默认。v3.15.0：Flaiwheel 签发自己的 TLS 证书，测试从 370 增至 439。v3.14.0：无需反向代理的远程 MCP，测试从 335 增至 370。v3.13.0：可观测性，check_divergence() 比较 HEAD 与 @{u} 并分类为 synced / ahead / behind / diverged / no-upstream，/health 增加 divergence_status、commits_ahead、commits_behind 和 last_divergence_at，测试从 316 增至 335。v3.12.3：每个依赖都限制在下一个主版本以下。
