GovernFlow

AI-native code governance pipeline. Assemble, don't build.

GovernFlow 将 AI Agent 的代码治理从"自研轮子"重构为"组装业界工具链"的四层流水线。不建新平台，嵌入现有工作流。

环境依赖

Node.js 22 是硬性要求（使用了 --experimental 特性的 tree-sitter wasm 绑定）。SQLite 通过 better-sqlite3 内嵌，无需单独安装。

快速部署运行

方式一：npm 安装（推荐）

npm install governflow
# 或指定版本
npm install governflow@1.0.0-alpha.9

方式二：源码构建

# 1. 拉取仓库
git clone https://github.com/sole03/governflow.git
cd governflow

# 2. 安装依赖 (自动编译 TypeScript → dist/ + 生成 Prisma Client)
npm install

# 3. 配置环境变量 (可选，默认使用 SQLite)
#    set DATABASE_URL=file:./custom.db   (Windows)

# 4. 运行测试 (验证环境正确)
npm test                    # 291 tests, 37 files

# 5. 启动
governflow                  # MCP stdio 模式 (供 Cursor/Claude Desktop 等客户端使用)
# 或
npm run start:http          # HTTP REST API 模式

配置说明

无需 .env 文件即可运行。所有配置均有合理默认值。

项目目录结构

governflow/
├── packages/
│   ├── core/                    # governflow-core — 协议无关内核
│   │   └── src/
│   │       ├── perception/      # 感知层: MerlionBridge + ShapleyAttributor
│   │       ├── proposal/        # 提案层: RegoCompiler + StructuredGenerator + PromptPipeline
│   │       ├── verification/    # 验证层: PropertyTests + ShadowVerifier
│   │       ├── delivery/        # 决策层: GitOpsEngine + CanaryController
│   │       ├── constraints/     # 约束 DSL 编译器 + 模板库 + 运行时
│   │       ├── sandbox/         # COW 沙箱 + 自愈循环 + 安全阀 + 健康门控
│   │       ├── dashboard/       # 指标收集器 + DashboardSnapshot 类型
│   │       ├── cognition/       # 认知图引擎核心
│   │       ├── events/          # 事件总线 + 领域事件
│   │       ├── audit/           # 满意度追踪 (开发者体验兜底)
│   │       ├── cli/             # CLI 入口
│   │       └── di/              # 依赖注入容器
│   └── dashboard/               # governflow-dashboard — 可视化仪表盘
├── src/                         # MCP Server 传输层 (stdio + HTTP)
│   ├── transport/               # MCP 工具处理器 + HTTP 服务
│   ├── governance/              # 策略引擎 + 规则免疫 + 审批工作流 + 影子服务
│   ├── core/                    # AST 约束求解器 + 认知图遍历器 + 意图识别
│   ├── data/                    # Prisma Repository + 向量存储 + LRU 缓存
│   └── adapters/                # Zod Schema 校验 + Embedding 适配器
├── tests/                       # 测试 (37 files, 291 tests)
├── prisma/                      # 数据库 Schema + 迁移
├── scripts/                     # License 检查 + 影子回放 CLI + Pack 脚本
├── benchmarks/                  # 性能基准
└── .github/workflows/           # CI 配置 (Rule Verification + License Check)

功能说明

四层流水线

数据模型

MCP 工具 (20 tools)

传输协议: stdio 和 HTTP 均覆盖，HTTP 额外包含 Workflow + Immune 工具。

技术栈

内核包

governflow-core 零 MCP 依赖，可独立发布为 npm 包：

npm install governflow-core

import { MerlionBridge, RegoCompiler, CanaryController } from "governflow-core";

文档

完整架构设计与开发文档见 GitHub Wiki.

常见问题

npm install 报错 better-sqlite3 编译失败

需要系统安装 C++ 编译工具链：

• Windows: npm install --global windows-build-tools 或安装 Visual Studio Build Tools

• Mac: xcode-select --install

• Linux: sudo apt install build-essential python3

prisma db push 报错 Environment variable not found: DATABASE_URL

设置环境变量或使用默认值：

export DATABASE_URL="file:./mcp-cognition.db"   # Linux/Mac
set DATABASE_URL=file:./mcp-cognition.db        # Windows cmd
$env:DATABASE_URL="file:./mcp-cognition.db"     # PowerShell

测试报错 database is locked

SQLite 并发文件锁的已知限制。重跑即可：

npm test

如果频繁出现，尝试 npx vitest run --no-cache --pool=forks。

Node.js 版本过低

MCP SDK 和 tree-sitter wasm 绑定需要 Node.js ≥ 22。检查版本：

node -v

如果低于 22，使用 nvm/fnm 升级。

心法

不要构建系统，要构建流水线。

让异常检测成为监控平台的插件，而非独立服务。 让规则生成成为 CI 的一个 Step，而非后台黑盒。 让人机协同成为 Code Review 的自然延伸，而非额外负担。

Changelog

v1.0.0-alpha.9 (2026-06-21)

• 🔴 认知图写入修复: capture_diff / analyze_workspace 所有 upsertCognitionClosure / createNodeWithEdges 加 await，解决 fire-and-forget 导致节点丢失

• 🔴 认知图错误可见: 写入错误不再静默吞掉，改为写入 warnings 字段

• 🔴 认知图查询扩展: cognition_query 支持 5 种检索模式（nodeType / filePath / language / contextHash / semanticHash），不再死锁在单一 hash

• 🟡 CognitionRepository: 新增 findOrCreateNode（P2002 时返回已有节点）+ findNodesByPayloadField / findNodesByType 多维检索

• 🟡 Schema 放宽: CognitionQuerySchema 放宽 required 约束，支持多种可选检索条件

• 🟡 空 pattern 防御: rule-matcher / rule-generator / capture-diff / rule-repo 四层拦截空 pattern 规则

• 📄 文档: 新增 Agent 工作流指南（knowledge injection → rule coding → code audit）

• 📄 文档: 新增架构设计文档（enhancement-plan / gaps）

v1.0.0-alpha.8 (2026-06-21)

• 🧠 Prisma Client 重新生成: 同步 ApprovalRequest.version 字段

• 🧠 build 修复: approval-workflow.ts version 类型错误修复

v1.0.0-alpha.7 (2026-06-18)

• 🛡 冲突全景图修复①: Rule 模型新增 @@unique([type, language, pattern, suggestion]) — 数据库级拦截完全重复规则

• 🛡 冲突全景图修复②: rule-repo.ts create() 前置 findFirst 存在检查（belt-and-suspenders）

• 🛡 冲突全景图修复③: ApprovalRequest 新增 version 字段 + castVote 乐观锁 P2025 重试（最多 3 次），防止并发投票丢失

• 🛡 冲突全景图修复④: capture-diff PATTERN 节点 TOCTOU 硬化（re-fetch on duplicate key）

• 🛠 CognitionRepository: 新增 createEdge() 单边创建方法

• 🛠 Schema 错误消息: Zod enum 校验失败时显式列出合法值

• 🛠 Schema 别名: cognition_query 新增 semanticHash 参数

• 🛠 validateInput: Zod Required 错误翻译为 field-aware 消息

• 🧹 清理: prisma/ 下 59 个历史脏数据库文件

v1.0.0-alpha.6 (2026-06-18)

• 🧠 认知图谱闭环: capture_diff 自动创建 INTENT 节点（intent-recognizer 分类 REFACTOR/BUGFIX/BOILERPLATE）+ CAUSES 边连接 PATTERN

• 🧠 认知图谱完善: analyze_workspace 为每个文件 diff 持久化 PATTERN 节点

• 🧠 认知图谱完善: confirm_rule accept 自动创建 CONSTRAINT 节点（架构约束）

• 🛠 CognitionRepository: 新增 createEdge() 单边创建方法

• 🛠 Schema 错误消息: Zod enum 校验失败时显式列出合法值（accept/reject/edit/skip）

• 🛠 Schema 别名: cognition_query 新增 semanticHash 参数（contextHash 别名）

• 🛠 validateInput: Zod Required 错误翻译为 field-aware 消息（如 filePath is required）

• 🧹 清理: prisma/ 下 59 个历史脏数据库文件（dev-1.db ~ dev-37.db）

v1.0.0-alpha.5 (2026-06-18)

• 🐛 CI 修复: bench workflow DATABASE_URL 路径偏差（prisma/prisma/ -> prisma/）+ Node 22

• 🐛 pack 修复: VM EOF bug — 新增 pack-from-subdir.mjs 绕过 npm tar 路径问题

• 🐛 License: 修复 sentinel 注释导致 CI license:check 失败

• 📄 文档: README 精简安装步骤（auto prepare + Prisma generate）

v1.0.0-alpha.4 (2026-06-18)

• 🛠 工程: 新增 .env.example 配置模板，覆盖 DATABASE_URL / LOG_LEVEL

• 🛠 工程: 清理 prisma/ 下 37 个 CI/测试残留 .db 文件，加入 .gitignore 全局匹配

• 🛠 测试: 修复 cognition-repository 性能测试偶发超时（timeout 5s → 15s + semanticHash 去重）

• 🛠 文档: 修正 README 全文 DATABASE_URL 默认值与代码实际值不一致（dev.db → mcp-cognition.db）

• 🛠 文档: 快速开始新增 .env.example 引导，替换硬编码路径示例

v1.0.0-alpha.3 (2026-06-18)

• 🔴 修复: HTTP transport 每次请求重新创建 transport 导致崩溃 — 改为启动时连接一次

• 🔴 修复: detectLang 缺失 Java/Vue/XML/YML/YAML 等 5 种语言覆盖率

• 🔴 修复: CaptureDiffSchema.originalContent 从 .min(1) 放宽为 .optional().default("")，新文件不再被拒绝

• 🟡 修复: HTTP transport 补齐 governance_pause_arbitrator / governance_rollback_arbitration 工具注册

• 🟡 修复: cognition_update_config TOOLS schema 补齐 expertMode 字段

• 📦 首次发布 npm 包: npm install governflow@1.0.0-alpha.7

v1.0.0-alpha.2 (2026-06-17)

• 20 MCP 工具完整实现 (Diff/Rule/Cognition/Governance/Workflow/Immune 六分类)

• 认知图引擎 (CognitionNode + CognitionEdge + BFS 遍历)

• AST 约束求解器 + 意图识别器

• 策略引擎 + 规则免疫 + 审批工作流 + 影子服务

• Streamable HTTP + stdio 双传输协议

• Prisma + SQLite 数据持久层

License

Apache-2.0 © 2026 熊高锐