Governance — 端侧代码治理工具

在提交阶段拦截问题代码的轻量级 Git 工具：一个 CLI 二进制 + 一个 pre-commit hook，配合 CI 在每次 push 上逐提交复查。防止 AI 生成的大量代码、密钥、调试残留混入仓库。

工作原理

开发者机器                          CI（每次 push，建木 webhook 自动触发）
git commit                          governance validate-range
  ├─ pre-commit hook                  （逐提交复查区间，拦截被
  │    └─ governance validate            --no-verify 绕过的提交）
  └─ commit-msg hook
       └─ governance validate
git push
  └─ pre-push hook（v0.3.2+）
       └─ governance validate-range   （校验整个待推区间，补上
                                        CI 只查头提交的缝隙）

命令

命令	作用
`governance init`	在仓库生成 `.governance/config.yaml` 并安装 pre-commit hook
`governance validate`	检查暂存区（hook 调用的就是它）
`governance validate-range <base>..<head>`	逐提交检查一个区间（CI 调用）
`governance onboard`	把 GitLink 仓库接入建木 CI：自动创建/更新 CI 项目并下发 DSL，引擎随后写回 `.devops/governance-ci.yml`（需本机 `gitlink-cli` 已登录 GitLink）；`--baseline-config <url>` 可让 CI 使用受保护的基线配置，防仓库内配置被篡改
`governance ci-clean`	停止建木上占住并发槽的挂起/排队运行（红运行不清理会让后续 push 全部停摆）

内置规则

规则	拦截内容
`diff-size`	单文件/单次提交新增行数超限（默认 600 / 1500，只统计新增行）
`secrets-scan`	AWS 密钥、私钥、JWT 等敏感信息
`debug-residue`	打印语句、断点等调试残留（默认排除测试目录）
`binary-size`	超过阈值的二进制文件（默认 20MB）
`text-encoding`	被 git 判为二进制的代码/配置文件（典型是 UTF-16 编码）——内容规则扫不到它们，拦截并要求转存 UTF-8
`protected-path`	受保护路径的改动
`commit-msg`	提交标题以 `feat` / `fix` / `docs` / `test` / `chore` / `refactor` 开头，≤72 字符（本地 commit-msg hook 即拦，Merge 提交豁免）

阈值和排除项都可在 .governance/config.yaml 中调整。

自定义规则

内置规则之外可在 .governance/config.yaml 的 custom-rules 节定义团队专属检查（v0.3.0+）：regex 单正则、pattern-file 多模式（按文件类型过滤）、command 外部插件（stdin/stdout JSON 协议，超时 fail-closed）。详见 USER_GUIDE.md。

服务端防篡改与运维（v0.3.2+）

基线配置：onboard --baseline-config <url> 让 CI 使用受保护的基线配置校验，仓库内 .governance/config.yaml 仅作本地开发——改配置绕过检查的路被堵死；未配基线时，触及配置文件的提交会在 CI 日志中输出篡改告警
pre-push 区间校验：本地 push 前校验整个待推区间，中间提交的违规（含被 --no-verify 绕过的）在离机前即被拦
**governance ci-clean**：一键停止建木上占住并发槽的挂起/排队运行
**scripts/release.sh <tag>**：维护者发版一条命令（构建/上传/建 Release/sha256 自校验/附件自愈）
validate --quiet 与 --report json 便于 CI 集成

豁免方式

行内豁免：调试行加 // governance:skip-debug，测试夹具里的示例密钥加 // governance:skip-secret
紧急绕过：git commit --no-verify（CI 会逐提交复查抓回来）
配置排除：在 .governance/config.yaml 的对应规则下加 exclude 路径模式

快速开始

从 Releases 下载对应平台的二进制：

平台	资产
Windows（开发者本机）	`governance-windows-amd64.exe` → 改名为 `governance.exe` 放入 PATH
Linux（由 CI 运行时自动下载，无需手工安装）	`governance-linux-amd64`

# 1. 在目标项目里初始化（生成 .governance/config.yaml + 本地 pre-commit hook）
cd your-project
governance init

# 2. 提交并推送配置（先推，避免与引擎回写提交冲突）
git add .governance/
git commit -m "chore: add governance config"
git push

# 3. 接入 GitLink 建木 CI（一条命令；需本机 gitlink-cli 已登录 GitLink）
governance onboard

# 之后正常开发即可：每次 push 由建木 webhook 自动触发逐提交复查

governance onboard 幂等——重复执行即更新；--dry-run 只打印将要下发的 DSL，不发任何请求。

文档

开发

go build ./...            # 构建
go test ./...             # 单元测试
bash testdata/e2e_test.sh # 端到端测试

核心实现位于 internal/：rules/ 各条规则、cli/ 各命令（init / validate / validate-range / onboard）、gitlink/ 建木接入、gitctx/ 与 git 的交互。