核心用法
consensus-code-merge-guard 是一套面向 AI 辅助工程的代码合并治理框架，将传统的单人 Code Review 转化为多角色加权投票决策机制。开发者通过调用 invoke(input, opts) 入口，传入 PR/变更摘要，系统随即启动以下流程：
1. 风险信号采集：自动解析测试覆盖率、安全标记（如 SECURITY_CRITICAL）、可靠性指标（如 CI 状态、变更复杂度）
2. 角色投票仲裁：加载预定义的工程角色 persona（如 "安全审计员"、"性能守护者"、"测试专家"），各角色基于权重对变更进行独立评估
3. 硬约束强制执行：无视投票结果，直接拦截违反硬性策略的变更（如零测试覆盖的核心模块修改）
4. 决策状态映射：输出标准化决策——MERGE（通过）、BLOCK（拦截）、REVISE（需修改后重审）
5. 审计持久化：决策记录与更新后的 persona 配置写入 board 状态，支持历史追溯与合规审计
两种运行模式
| 模式 | 说明 |
|------|------|
| `persona`（默认） | 内部生成/加载 persona_set，执行完整投票流程 |
| `external_agent` | 接收外部真实 agent 的投票数组，仅做聚合与策略检查，适合集成已有 AI Agent 生态 |
---
显著优点
1. 结构化降低认知偏差
传统单点 Code Review 易受疲劳、时间压力、领域盲区影响。多角色强制视角切换，模拟跨职能团队的集体智慧。
2. 策略即代码
硬约束与软投票分离，关键安全策略可审计、版本化，避免 "人治" 带来的规则漂移。
3. 生产级可观测性
所有决策附带完整上下文（投票明细、触发约束、角色权重），满足金融、医疗等强合规场景的审计需求。
4. 生态一致性
基于 consensus-guard-core 构建，与生态内其他 guard 共享决策 substrate，便于构建跨域治理矩阵（如代码 guard + 部署 guard 联动）。
---
潜在缺点与局限性
1. Persona 质量依赖
投票质量高度取决于 persona 提示工程与角色定义。若 persona 设计偏向 "通过友好"，系统可能沦为形式化流程。
2. 冷启动配置成本
需为不同仓库/团队定制角色集、权重矩阵、硬约束规则，初期投入高于传统 linter/CI 配置。
3. 延迟敏感场景不适用
完整 persona 投票链涉及多轮 LLM 调用（或外部 agent 协调），不适合需秒级反馈的预提交钩子。
4. "Consensus" 不等于 "Correctness"
多角色一致通过仍可能漏过系统性漏洞——系统本质是多因素加权评分，非形式化验证。
---
适合人群
- 平台工程团队：需为组织内数百仓库建立统一的合并质量门禁
- 高合规行业开发者：金融、医疗、政务等需审计追踪的场景
- AI-Native 研发组织：已采用 AI Agent 辅助开发，需结构化治理人机协作边界
- 开源项目维护者：核心仓库面临海量 PR，需自动化初筛 + 风险分级
---
常规风险
| 风险类别 | 说明 | 缓解建议 |
|---------|------|---------|
| **策略误配置** | 硬约束过宽导致漏洞流入，或过严导致合法变更被阻 | 以影子模式运行数周，对比人工决策校准 |
| **Persona 投毒** | 恶意修改 persona 定义降低安全敏感度 | 将 persona 配置纳入代码审查，启用签名验证 |
| **外部 agent 串通** | `external_agent` 模式下，投票方可能协同绕过检查 | 要求 agent 身份认证 + 投票多样性阈值 |
| **审计日志篡改** | board 状态文件被恶意清理 | 启用追加-only 存储后端，或定期快照至不可变存储 |
---
技术依赖
- 运行时：
node+tsx（TypeScript 执行器） - 网络：决策核心零外部调用；若启用内部 persona 生成，依赖外部 LLM API（需配置
OPENAI_API_KEY等） - 存储：本地 filesystem 写入 board/state 目录