flow-guard

面向 AI 编码智能体（Coding Agents）的端到端因果水路（Source ➔ Branch ➔ Sink）架构视野、跨语言桥接与增量通水验收引擎

简体中文 · English · 快速开始 · MCP 工具矩阵 · 17 仓实战基准

💡 为什么需要 FlowGuard？

在大规模、多语言生产仓库中，仅依赖 grep 和局部文件阅读的 AI 智能体极易陷入三大工程顽疾：

Related MCP server: PrecisionContextEngine

🏗️ 引擎五层因果架构

flowchart LR
  subgraph L1["1. 多语言容错词法层 (lexer.mjs)"]
    A1["25 种源码后缀扫描"]
    A2["全语言字符串插值保留 (Template / f-string / Raw)"]
    A3["JSX / 泛型 / 嵌套括号平衡定界"]
  end

  subgraph L2["2. 符号与边界信号提取 (file-parser.mjs)"]
    B1["函数 / 类 / 接口 / 状态字段提取"]
    B2["行级精确 (offsetToLine) 跨界探针"]
    B3["局部死变量 / 裸调忽略返回值检测"]
  end

  subgraph L3["3. 六通道跨语言桥接器 (bridge-linker.mjs)"]
    C1["TAURI_IPC (Rust command ⇄ Frontend invoke)"]
    C2["RPC_SERVICE (ConnectRPC / gRPC)"]
    C3["EVENT_BUS (emit ⇄ listen 自定义协议)"]
    C4["ELECTRON_IPC / HTTP_REST / CONFIG"]
  end

  subgraph L4["4. 全局因果图与架构视野 (graph-builder + arch-vision)"]
    D1["三层子系统拓扑 (Entry ➔ Orchestration ➔ Sink)"]
    D2["正向/反向 BFS 可达性传递闭包"]
    D3["Top 8 主干动脉 + 高中心度枢纽"]
  end

  subgraph L5["5. 九维增量通水验收 (flow-verifier.mjs)"]
    E1["断流 / 死代码废管 / 死水状态拦截"]
    E2["预留契约 (reservedContracts) 保护"]
    E3["成对生命周期 (Save/Load) 对称性校验"]
  end

  L1 --> L2 --> L3 --> L4 --> L5

🧰 四大核心 MCP 工具

FlowGuard 通过标准 Model Context Protocol (stdio JSON-RPC 2.0，零外部依赖) 向 AI 智能体暴露 4 个高信噪比工具：

1. flow_overview — 全局架构视野与主干水路测绘

扫描整个工作区并输出宏观架构蓝图：

• architectureDomains：自动将仓库符号划分为 ENTRY_SURFACE（水源入口层）、ORCHESTRATION_ROUTING（核心编排分流层）与 INFRA_SINK（基础设施落点层）。

• backbonePipelines：提取高达 Top 8 条核心端到端主干因果动脉（Source ➔ Hub ➔ Sink）。

• architecturalHubs：按入度/出度中心度排序的核心路由枢纽符号。

• extensionAndReserveCatalog：汇总仓库内的多态基类/接口实现矩阵与受保护的预留扩展钩子。

• stateOwnership (SSOT)：全局状态字段的唯一写入者与读取者映射。

2. flow_trace — 改代码前必调：单符号全链路与爆炸半径透视

输入任意函数名、类名、文件名或状态字段，一次性返回：

• architectureContext.blastRadius：直接调用者、传递性受影响上游节点数、受影响跨文件列表与风险评级（LOW / MEDIUM / HIGH / CRITICAL）。

• architectureContext.parameterFlowMatrix：逐个入参分析其在函数体内的消费情况（分支控制/传参转发/属性读取），自动识别多态对齐预留参数。

• upstreamSources & downstreamSinks：完整上下游因果链路。

• siblingBranches & polymorphicPeers：同一父分流阀下的并列支流与同接口兄弟实现，彻底杜绝“改 A 漏 B”。

• reusableSimilarSymbols：基于归一化 AST Token 指纹检索仓内高相似度现成实现，防止重复造轮子。

3. flow_blueprint — 接新功能前必调：同类模块四站式接线施工单

指定仓内任意现有模块作为参考标杆，自动生成结构化施工清单：

1. Station 1 — 构造与注册表挂载：容器初始化与依赖注入挂载点。

2. Station 2 — 上游分流入口：需要在哪些 Dispatcher / Router 中注册新分支。

3. Station 3 — 成对对称生命周期契约：自动识别必须双向闭合的接口对（如 Save ⇄ Load、Serialize ⇄ Deserialize、Send ⇄ Receive、Connect ⇄ Disconnect）。

4. Station 4 — 下游真实终端与状态落点：需要连通的持久化、网络发包或 UI 状态 Sink。

4. flow_verify — 交卷前必调：九维端到端通水试验与死代码审计

对工作区（自动聚焦 Git 增量变更文件）执行严格验收：

🌐 多语言与跨边界桥接矩阵

支持的 25 种源码扩展名（10+ 主流语言家族）

• TypeScript / JavaScript / 前端框架：.ts, .tsx, .mts, .cts, .js, .jsx, .mjs, .cjs, .vue, .svelte

• Rust：.rs（支持 #[tauri::command]、#[command]、#[specta::specta]、原始字符串 r#"..."#、宏内插值 {ident}）

• Go：.go（支持 Receiver 方法、interface 契约提取、自动过滤 *.pb.go / *.connect.go 生成代码）

• Python：.py（支持装饰器路由、缩进块定界、f"""...""" 多行插值字符串）

• C#：.cs（支持属性/方法/委托、$@"..." 混合插值字符串、Unity/Godot/Harmony 生命周期识别）

• Java / Kotlin / Dart：.java, .kt, .dart（支持 Spring/Retrofit 注解、record、伴生对象与扩展函数）

• Swift：.swift（支持 extension 挂载、init、内外部命名标签与 \(ident) 字符串插值）

• PHP：.php（支持 PHP 8 构造器属性提升、#[Route] / Route::get、$this->field 状态追踪与 {$this->field} 插值）

• Ruby：.rb（支持 def ... rescue ... end 块定界、@ivar 实例状态追踪与 #{ident} 插值）

• C / C++：.c, .cpp, .cc, .h, .hpp

自动缝合的 6 类跨语言/跨进程桥接通道

1. TAURI_IPC：前端 invoke("cmd") ⇄ Rust #[tauri::command] fn cmd

2. RPC_SERVICE：TypeScript ConnectRPC / gRPC client.method() ⇄ Go / Rust / Java RPC Service Handler

3. EVENT_BUS_BRIDGE：跨进程事件总线 emit("topic://...") ⇄ listen("topic://...")（精确保留 URI 风格事件名）

4. ELECTRON_IPC：ipcRenderer.invoke/send ⇄ ipcMain.handle/on

5. HTTP_REST_API：前端 fetch/axios("/api/v1/...")（含模板动态路由参数 /api/memos/${id}）⇄ 后端参数化路由控制器（{id} / :id / <id>）

6. SHARED_CONFIG_BRIDGE / ENV_VAR_BRIDGE：跨语言共享配置文件与环境变量读写闭环

📊 实战基准测试（17 仓 · 19,125 生产符号）

FlowGuard 已在 17 个涵盖各大语言的真实开源仓库与生产全栈项目（共计 19,125 个生产符号）以及 10 语言对抗性语法酷刑、变异模糊与契约测试套件（test/torture-suite.mjs） 上完成实战验证：

🚀 快速安装与接入

方式一：作为 Antigravity / Gemini 插件安装（推荐）

将本仓库克隆至插件目录即可自动加载 MCP Server、Lifecycle Hooks（SessionStart & Stop）、Rules 与 Skills：

git clone https://github.com/senran-N/flow-guard.git ~/.gemini/config/plugins/flow-guard

方式二：接入 Claude Code / Cursor / Windsurf / 任意 MCP 客户端

在客户端的 MCP 配置文件（如 .mcp.json 或 claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "flow-guard": {
      "command": "node",
      "args": ["/path/to/flow-guard/src/server.mjs"]
    }
  }
}

方式三：命令行独立运行（CLI 模式）

无需启动 MCP 会话，直接对任意本地代码仓库执行扫描与验收：

# 1. 全局架构视野与主干水路测绘
node src/server.mjs --cli overview /path/to/your-repo

# 2. 单符号上下游水路与爆炸半径透视
node src/server.mjs --cli trace /path/to/your-repo YourFunctionOrClassName

# 3. 提取同类模块四站式接线施工单
node src/server.mjs --cli blueprint /path/to/your-repo ReferenceModuleName

# 4. 执行九维端到端通水验收与死代码排查
node src/server.mjs --cli verify /path/to/your-repo

🧪 运行测试与自举校验

FlowGuard 采用零外部依赖纯 Node.js ESM 编写，内置 10 语言对抗性语法酷刑、变异模糊与 Hook/MCP 契约测试套件，并通过自身 flow_verify 实现自举零缺陷验收：

# 运行 10 语言极端语法酷刑测试 + 8 类故障变异测试 + Hook/MCP 契约测试 (36 项断言)
npm test

# 使用 FlowGuard 对自身代码库执行九维端到端通水自举验收
npm run verify:self

📂 仓库目录结构

flow-guard/
├── assets/
│   ├── banner.svg                 # 仓库顶栏架构视觉横幅
│   └── logo.svg                   # 插件矢量图标
├── rules/
│   └── AGENTS.md                  # 面向 AI 智能体的端到端水路开发准则
├── skills/
│   └── flow-engineering/SKILL.md  # 端到端透视、沙盒迁移与废管清理标准作业流程 (SOP)
├── src/
│   ├── server.mjs                 # MCP Server (stdio JSON-RPC 2.0) & CLI 入口
│   ├── lexer.mjs                  # 多语言容错词法扫描器（保留全语言字符串插值与平衡括号）
│   ├── lang-presets.mjs           # 25 种源码后缀的语言家族规则与水源/终端启发式配置
│   ├── file-parser.mjs            # 符号提取、行级跨界探针与局部数据流断裂分析
│   ├── fingerprint.mjs            # AST 结构指纹提取、预留契约分类与克隆检测
│   ├── bridge-linker.mjs          # 6 通道跨语言/跨进程桥接缝合器
│   ├── graph-builder.mjs          # 全局因果图构建与正反向可达性闭包计算
│   ├── arch-vision.mjs            # 子系统分层、主干动脉提取、爆炸半径与入参流向矩阵
│   ├── flow-tools.mjs             # flow_overview / flow_trace / flow_blueprint 实现
│   ├── flow-verifier.mjs          # flow_verify 九维增量通水试验与死代码审计引擎
│   └── hook-runner.mjs            # SessionStart / Stop 生命周期自动化钩子执行器
├── test/
│   └── torture-suite.mjs          # 10 语言对抗性语法酷刑、故障注入变异与 Hook/MCP 契约测试套件
├── .github/workflows/ci.yml       # GitHub Actions 自动化持续集成流水线
├── hooks.json                     # 插件生命周期钩子配置
├── mcp_config.json                # MCP Server 启动配置
├── plugin.json                    # 插件清单定义 (v0.1.0)
├── package.json                   # Node.js 包定义与脚本
├── CHANGELOG.md                   # 版本演进记录
├── CONTRIBUTING.md                # 贡献指南与自举验收规范
└── LICENSE                        # MIT 开源许可证

📄 开源协议

本项目基于 MIT License 开源。Copyright © 2026 senran-N.