# GovernFlow

**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 安装（推荐）

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

### 方式二：源码构建

```bash
# 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` | 注入审批工作流 |

### MCP 工具 (20 tools)

| 分类 | 工具 | 用途 |
|------|------|------|
| **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 包：

```bash
npm install governflow-core
```

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

---

## 文档

完整架构设计与开发文档见 [GitHub Wiki](https://github.com/sole03/governflow/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`

设置环境变量或使用默认值：
```bash
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 并发文件锁的已知限制。重跑即可：
```bash
npm test
```
如果频繁出现，尝试 `npx vitest run --no-cache --pool=forks`。

### Node.js 版本过低

MCP SDK 和 tree-sitter wasm 绑定需要 Node.js ≥ 22。检查版本：
```bash
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 熊高锐