stamp-cli：面向智能体工作流的本地化代码审查协议

stamp-cli是一个为AI智能体设计的本地、无头（headless）代码审查系统，旨在解决智能体集群间代码审查的效率与安全问题。它通过结构化审查流程、加密签名机制（Ed25519）实现智能体间的安全协作，无Web UI，依赖CLI与git钩子运行，核心目标是为智能体提供高效、可验证、可审计的代码审查协议。

随着AI智能体在软件开发中的角色日益重要，传统代码审查流程（依赖GitHub Web界面、人工判断）对智能体集群而言既不高效也不合适。stamp-cli应运而生：它是本地无头拉取请求系统，专为智能体到智能体的审查工作流设计。作者智能体打开diff，审查者智能体返回结构化反馈，迭代至满足合并规则后，签名合并并推送——远程会拒绝未经适当审查与签名的推送。

设计理念

stamp-cli并非GitHub替代品，而是为智能体集群快速迭代、保持主分支清洁设计，无Web UI或人类评论线程，仅依赖CLI与git钩子。设计原则包括：输出为散文（LLM易理解）、控制流通过退出码、状态存储在文件中、操作幂等。

关键概念

• 审查者：由.stamp/reviewers/.md提示文件定义，stamp init脚手架security、standards、product三个起始审查者。
• 裁决：审查者对diff的判断，按(base_sha, head_sha)记录在.git/stamp/state.db中，确保可追溯。
• 门禁：必需审查者的最新裁决需为approved，配置在.stamp/config.yml中。
• 证明：stamp merge用Ed25519签名载荷，附加到合并提交尾注，提供不可否认的审计追踪。
• 钩子：服务器端pre-receive阶段运行stamp-verify，重新执行客户端检查，防止绕过。

典型工作流

1. 初始化：stamp init脚手架.stamp/目录与密钥对
2. 审查：stamp review --diff main..feature并行运行所有配置审查者
3. 状态检查：stamp status --diff main..feature检查门禁状态
4. 合并：stamp merge feature --into main创建签名合并提交
5. 推送：stamp push main推送主分支，钩子验证通过后远程前进

退出码语义

命令	退出码0	非零退出
stamp review	审查者运行并记录	调用失败（审查者崩溃、DB错误），需跟随stamp status检查
stamp status	门禁开放（所有必需审查者已批准）	门禁关闭
stamp merge	合并已签名并在主分支	门禁关闭、预合并检查失败或git冲突
stamp push	远程接受	钩子拒绝或git错误
stamp verify	证明有效	验证步骤失败

安全模型

• 防护措施：作者智能体无法合并未经审查代码；无法伪造合并（签名密钥安全存储）；无法绕过远程验证（服务器端钩子强制执行）。
• 安全边界：持有签名密钥的人类可生成有效签名，但签名提供不可否认性（合并归属可追溯）。
• 预合并检查风险：required_checks在签名前运行，非零退出阻止合并；.stamp/config.yml更改需经审查。

部署模式

1. 自托管远程：用户服务器运行git+sshd，安装pre-receive钩子，拒绝未签名推送。
2. 自托管+GitHub镜像：stamp服务器为事实来源，post-receive钩子镜像到GitHub，GitHub分支保护限制推送。
3. 纯本地：无服务器，生成签名合并，可验证但无法阻止绕过，适合个人或小型团队。

审查者提示工程工具

• stamp reviewers test --diff ：调优提示，不记录到DB
• stamp reviewers show ：查看裁决历史与统计
• stamp reviewers verify []：检查提示/工具匹配

技术依赖与许可

• 需Node 22.5+（使用node:sqlite与Ed25519 API）
• MIT许可证，但依赖@anthropic-ai/claude-agent-sdk（Anthropic专有许可）

未来展望

stamp-cli代表AI原生开发工具方向：为智能体设计专用协议而非适配人类工具。未来将成为管理AI智能体协作的基础设施重要组成部分。