AI-native code governance pipeline. Assemble, don't build.
GovernFlow 将 AI Agent 的代码治理从"自研轮子"重构为"组装业界工具链"的四层流水线。不建新平台，嵌入现有工作流。
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | ≥ 22 | 运行时 |
| npm | ≥ 10 | 包管理 |
| SQLite | 3 (内置) | 本地数据库 (零配置) |
Node.js 22 是硬性要求（使用了
--experimental特性的 tree-sitter wasm 绑定）。SQLite 通过better-sqlite3内嵌，无需单独安装。
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 模式| 环境变量 | 默认值 | 说明 |
|---|---|---|
DATABASE_URL |
file:./mcp-cognition.db |
SQLite 数据库路径 |
LOG_LEVEL |
info |
日志级别 (trace/debug/info/warn/error) |
无需 .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)
| 层 | 核心模块 | 功能 |
|---|---|---|
| 感知层 | perception/ |
Z-score 动态基线异常检测 + EMA 自适应 + 季节性分解 + Shapley 多维根因归因 |
| 提案层 | proposal/ |
JSON DSL → OPA Rego 编译 + Zod 约束 LLM 结构化输出 + Few-shot 自动编译 |
| 验证层 | verification/ |
属性测试自动证伪 + 影子日志回放 + CI 自动验证 PR |
| 决策层 | delivery/ |
DashboardSnapshot → PR Markdown (GitOps) + 5%→100% 金丝雀渐进交付 |
| 模型 | 用途 |
|---|---|
Rule |
规则定义 (含 hitCount/falsePositiveCount/adoptedCount 效能追踪) |
PolicyVariant |
A/B 策略变体对比 |
ShadowLog |
影子模式运行日志 (新规则 7 天前置观察) |
CognitionNode / CognitionEdge |
认知图拓扑 |
AstTemplate |
AST 级约束模板 |
Proposal / ApprovalRequest |
注入审批工作流 |
| 分类 | 工具 | 用途 |
|---|---|---|
| Diff | analyze_workspace |
Git diff 分析 + 意图识别 + 语言检测 (19 种语言) |
| Diff | capture_diff |
单文件差异捕获 → AST/Regex 差异归一化 |
| Rule | list_rules |
分页查询全量规则 + 按语言/置信度过滤 |
| Rule | query_rules |
按文件路径 + 语言匹配适用规则 |
| Rule | confirm_rule |
审批(adopt)/拒绝(reject)/跳过(skip) 规则 |
| Rule | resolve_conflict |
解决规则冲突 (keep/skip/merge 三种策略) |
| Cognition | cognition_query |
认知图上下文查询 (最大深度 3 层 BFS) |
| Cognition | cognition_validate |
代码 vs 约束节点一致性校验 |
| Cognition | cognition_feedback |
提交 ACCEPTED/REJECTED 反馈回流 |
| Cognition | cognition_update_config |
认知引擎配置热更新 (需 expertMode) |
| Cognition | cognition_approve_injection |
审批/拒绝注入提案 |
| Governance | governance_pause_arbitrator |
暂停自动仲裁 (1-1440 分钟) |
| Governance | governance_rollback_arbitration |
回滚指定时间后的仲裁结果 |
| Workflow | workflow_submit |
提交多评审人审批工作流 |
| Workflow | workflow_vote |
审批投票 (APPROVE/REJECT) |
| Workflow | workflow_status |
查询审批状态 |
| Workflow | workflow_escalate |
审批超时升级 |
| Immune | immune_cycle |
规则免疫周期执行 |
| Immune | immune_stats |
免疫统计 (抑制/恢复/反馈) |
传输协议: stdio 和 HTTP 均覆盖，HTTP 额外包含 Workflow + Immune 工具。
| 类别 | 技术 |
|---|---|
| 语言 | TypeScript 5.6 |
| 运行时 | Node.js 22 |
| 数据库 | SQLite (better-sqlite3) |
| ORM | Prisma 5.22 |
| 测试 | Vitest 2.1 |
| AST | tree-sitter (JS/Python/TS) |
| Embedding | @xenova/transformers (ONNX 本地推理) |
| Schema 校验 | Zod 4 |
| 日志 | Pino |
| 协议 | MCP (Model Context Protocol) |
governflow-core 零 MCP 依赖，可独立发布为 npm 包：
npm install governflow-coreimport { MerlionBridge, RegoCompiler, CanaryController } from "governflow-core";完整架构设计与开发文档见 GitHub Wiki.
需要系统安装 C++ 编译工具链：
- Windows:
npm install --global windows-build-tools或安装 Visual Studio Build Tools - Mac:
xcode-select --install - Linux:
sudo apt install build-essential python3
设置环境变量或使用默认值：
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" # PowerShellSQLite 并发文件锁的已知限制。重跑即可：
npm test如果频繁出现，尝试 npx vitest run --no-cache --pool=forks。
MCP SDK 和 tree-sitter wasm 绑定需要 Node.js ≥ 22。检查版本：
node -v如果低于 22，使用 nvm/fnm 升级。
不要构建系统，要构建流水线。
让异常检测成为监控平台的插件，而非独立服务。 让规则生成成为 CI 的一个 Step，而非后台黑盒。 让人机协同成为 Code Review 的自然延伸，而非额外负担。
- 🔴 认知图写入修复: 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）
- 🧠 Prisma Client 重新生成: 同步 ApprovalRequest.version 字段
- 🧠 build 修复: approval-workflow.ts version 类型错误修复
- 🛡 冲突全景图修复①: 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 个历史脏数据库文件
- 🧠 认知图谱闭环: 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）
- 🐛 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）
- 🛠 工程: 新增
.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引导，替换硬编码路径示例
- 🔴 修复: 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_configTOOLS schema 补齐expertMode字段 - 📦 首次发布 npm 包:
npm install governflow@1.0.0-alpha.7
- 20 MCP 工具完整实现 (Diff/Rule/Cognition/Governance/Workflow/Immune 六分类)
- 认知图引擎 (CognitionNode + CognitionEdge + BFS 遍历)
- AST 约束求解器 + 意图识别器
- 策略引擎 + 规则免疫 + 审批工作流 + 影子服务
- Streamable HTTP + stdio 双传输协议
- Prisma + SQLite 数据持久层
Apache-2.0 © 2026 熊高锐