一致性守卫

先说清楚要解决的问题

一个字段在 API 响应里加了，前端类型没更新；数据库迁移脚本改了 nullable，校验器还按旧规则放行；缓存 TTL 和业务文档写的不一致——这类问题很少在改动当天暴露，往往在部署后、甚至在生产环境流量切上来之后才被发现。根因不是某一个文件写错了，而是契约的来源没有对齐：SDK、初始化 SQL、生成的 schema、缓存、文档都可能是派生产物，如果默认把它们当作事实来源，越改越乱。

consistency-guard 做的不是代码生成，而是一致性评审与架构守护：在动手改之前，先把变更定位到具体契约上，再判断这次改动会波及哪些节点。

它怎么工作

核心能力是按一套 AI 一致性协议推进，大致分几个阶段：

• 能力协商：先声明当前 agent 能读、改、解析、执行、测试、校验什么，不支持的步骤降级为人工或标记为不支持，而不是假装跑过了。
• 项目画像：加载项目 adapter、产物地图、来源优先级、校验命令、保护域、生成文件与忽略规则。
• 产物发现与分类：扫描迁移、schema、实体、DTO、校验器、API 规范、SDK、前端类型、表单、缓存契约、测试和文档，并记录路径、角色与证据。
• 事实来源裁决：显式识别权威契约，默认不把生成物、快照、初始化 SQL、SDK、文档、缓存或派生 schema 当作权威；冲突时按项目声明的优先级解决，解决不了就停下来等人。
• 一致性图：以图作为主模型，按契约、映射、生成、消费、校验、缓存、文档关系连接产物；影响面从图中推导，而不是靠猜。重命名要和"删了重建"区分开，有兼容矩阵时不要把 v1/v2 的有意差异算作漂移。
• 迁移分类与风险打分：区分只读、简单写、批量写、事务、资金、分布式、DDL、维护、后台任务、权限/安全等类型；按优先级、类别、置信度、爆炸半径、可逆性量化。
• 修复计划与决策门：每个计划都要包含执行、校验、回滚、证据、置信度和阻塞原因；遇到认证、授权、支付、钱包、提现、审计、上传、WebSocket 权限、限流、验证码等保护域，或者资金流、破坏性迁移、事务、队列、Webhook、安全边界，必须走审批门。
• 校验与退出条件：产出并完成该变更类型的 checklist，退出前逐条用证据证明，否则标记未达成。

完成状态只有三种：consistent、partial_with_risk、blocked，中断状态包括 NEED_HUMAN_DECISION、NEED_HUMAN_REVIEW、NEED_APPROVAL、CAPABILITY_UNSUPPORTED、SOURCE_OF_TRUTH_AMBIGUOUS、CONTRACT_CONFLICT、VERIFICATION_FAILED。

适用边界

它不会编造业务需求、默认值、可空性、枚举值、权限、缓存 TTL、保留策略或生命周期语义。业务语义缺失时会停下来等人决策，而不是自己补一套看起来合理的解释。它也不会自动把写操作、事务、锁、资金流、权限变更、Webhook、任务或消息队列判定为安全迁移。

换句话说，这个技能的价值在于降低把不一致带上线的概率，而不是替你做架构决定。它依赖项目侧提供 adapter 与优先级声明，配置越完整，裁决越靠谱；在没有任何项目约定的情况下，它会更频繁地停下来要求人工输入。