Agent Protocol：为AI编程助手打造工具无关的工程化工作流框架

Agent Protocol是一个工具无关的工程化方法论框架，旨在解决AI编程助手（如Claude Code、Cursor等）在代码生成中缺乏系统性变更管理的困境。通过四大表面分析、真相源管理、结构化变更清单等核心机制，帮助AI助手建立代码编写前、中、后全生命周期的变更管理能力，提升软件工程质量与效率。

随着Claude Code、Cursor、Gemini CLI等AI编程助手普及，开发者获得强大代码生成工具，但这些工具常忽视软件工程核心挑战——系统性变更管理。实际项目中，AI生成代码易出现API契约变更未考虑下游影响、数据库Schema改动未同步文档/迁移脚本、局部UI调整破坏国际化支持等问题。Agent Protocol作为开源项目，不绑定特定语言/框架/AI工具，提供通用工程化工作流插件，解决此困境。

Agent Protocol核心设计哲学是关注变更全生命周期管理，而非仅代码生成。核心原则包括：1.表面优先分析：变更前回答真相源、受影响表面/消费者、验证证据等问题；2.真相源纪律：明确唯一真相源，确保变更时先更新真相源；3.证据驱动交付：变更需附带可验证证据（测试、性能基准等）。此外，定义四大表面分析框架：用户表面（UI、路由等）、系统接口表面（API、Webhook等）、信息表面（数据库Schema、验证规则等）、运维表面（日志、文档等），全面理解变更影响范围。

Agent Protocol提供两种工作模式：Lean模式适用于简单低风险单表面变更（如孤立UI修复），跳过部分阶段但保留基础分析与证据收集；Full模式适用于复杂高风险跨表面变更（如核心数据模型重构），包含启动、发现、分析、规范、计划、实现、验证、观察八个阶段，每个阶段有明确准入标准与产出物。模式选择通过决策树/检查清单自动判断，平衡严谨性与效率。

Agent Protocol要求非平凡变更伴随YAML格式结构化变更清单，包含影响表面、真相源映射、证据计划、消费者通知、回滚策略等元数据，作为AI代理协作的标准化契约。此外，创新的运行时钩子机制植入AI执行循环：阶段门控钩子（提交前检查变更清单）、证据存在钩子（验证证据产出）、真相源漂移钩子（编辑后检查真相源变更）、完成审计钩子（会话结束把关），实现实时质量控制。

Agent Protocol支持多代理协作，定义规划（分析设计）、实现（代码编写）、审查（验证把关）三种角色，通过权限矩阵分离权限（如审查代理无写权限）确保制衡。跨平台方面，支持Claude Code（插件）、Cursor（规则文件）、Gemini CLI（GEMINI.md）等主流AI工具集成，并提供Flutter、Android Kotlin等技术栈的桥接文档，实现工具无关性与技术栈定制化。

Agent Protocol核心价值在于将AI辅助编程从代码生成升级为系统性变更管理，通过四大表面、真相源纪律等机制提升工程化水平。对开发团队而言，它减少返工与隐性缺陷，提高整体效率。作为开源项目，社区可贡献桥接文档、改进钩子或分享经验，推动方法论在更广泛场景落地。