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

> stamp-cli是一个为AI智能体设计的本地、无界面代码审查系统，通过结构化审查流程和加密签名机制，实现智能体之间的安全代码协作。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-19T22:43:40.000Z
- 最近活动: 2026-04-19T22:54:40.113Z
- 热度: 141.8
- 关键词: AI Agent, Code Review, Git, CLI, Ed25519, Security, Automation, DevTools
- 页面链接: https://www.zingnex.cn/forum/thread/stamp-cli
- Canonical: https://www.zingnex.cn/forum/thread/stamp-cli
- Markdown 来源: ingested_event

---

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

## 项目背景与核心问题

随着AI智能体在软件开发中的角色日益重要，一个新的问题浮出水面：如何让AI智能体之间进行有效的代码审查？传统的代码审查流程是为人类设计的，依赖于GitHub的Web界面、评论线程和人工判断。但对于智能体集群而言，这种模式既不高效也不合适。

stamp-cli正是为解决这一问题而生。它是一个本地、无头（headless）的拉取请求系统，专为智能体到智能体的代码审查工作流设计。作者智能体打开一个diff，审查者智能体消费它并返回结构化反馈，作者迭代直到满足合并规则，然后将签名合并推送到远程——远程通过加密方式拒绝任何未经适当审查和签名的推送。

## 核心理念与设计哲学

stamp-cli的设计哲学非常明确：它不是GitHub的替代品。GitHub是为人类协作而生的，而stamp-cli是为智能体集群在保持主分支清洁的前提下快速迭代而设计的。它没有Web UI，没有PR仪表板，没有核心的人类评论线程——只有CLI和git钩子。

这种极简设计背后是对智能体工作流的深刻理解：

- **输出是散文，不是JSON**：LLM天生理解散文，不需要专门的JSON接口
- **控制流通过退出码**：智能体循环可以根据退出码进行分支判断
- **状态存储在文件中**：.stamp/config.yml、.git/stamp/state.db、git提交尾注——易于检查，难以丢失
- **操作是幂等的**：stamp init可以安全地重复运行，stamp review会累积历史记录而不会损坏数据

## 核心概念解析

### 审查者（Reviewer）
审查者是由.stamp/reviewers/<name>.md中的提示文件定义的智能体角色。stamp init会脚手架三个起始审查者（security、standards、product），针对通用TS/JS项目进行校准——但用户应该编辑它们以适配自己的代码库。提示文件的唯一约定是必须以VERDICT: approved|changes_requested|denied行结尾。

### 裁决（Verdict）
裁决是审查者对特定diff的判断。它按审查者按(base_sha, head_sha)记录在.git/stamp/state.db中。这种设计保证了审查历史的可追溯性和可审计性。

### 门禁（Gate）
对于每个必需的审查者，最新的裁决必须是approved状态。配置位于.stamp/config.yml中。门禁机制确保了代码质量的标准化检查，防止未经审查的代码进入主分支。

### 证明（Attestation）
stamp merge会用Ed25519对载荷（base/head/target/approvals）进行签名，并将签名作为Stamp-Payload和Stamp-Verified提交消息尾注附加到合并提交上。这种加密证明提供了不可否认的审计追踪。

### 钩子（Hook）
stamp-verify在pre-receive阶段服务器端运行。它从目标分支的树中读取配置和受信任密钥，在推送时重新运行客户端执行的每个检查。这种服务器端验证防止了客户端的绕过尝试。

## 典型工作流

stamp-cli定义了一个典型的审查周期：

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

这个流程体现了stamp-cli的核心价值：为智能体提供一个结构化、可验证、可审计的代码审查协议。

## 安全模型与威胁防护

stamp-cli的安全模型设计非常周密：

### 防护措施
- **作者智能体无法合并未经审查的代码**：必须经过配置的审查者批准
- **无法伪造合并**：签名密钥不在智能体可以外泄的磁盘位置
- **无法绕过远程验证**：服务器端钩子强制执行所有检查

### 安全边界
持有签名密钥的人类仍然可以为任意内容生成有效的签名合并——这是任何本地优先系统的固有特性。签名提供的是不可否认性——主分支上的每个合并都永久归属于特定密钥的所有者，仅凭git历史即可证明。

### 预合并检查的风险
required_checks在签名前在合并后的树上运行。任何非零退出都会阻止合并并回滚。.stamp/config.yml的更改与其他代码更改一样经过相同的审查者审查，安全审查者提示应该将required_checks编辑视为高审查优先级。

## 部署模式

stamp-cli提供了三种部署模式，在设置成本和执行强度之间权衡：

### 1. 自托管远程（推荐）
用户控制的服务器运行git + sshd，安装了stamp-cli的pre-receive钩子。每次推送都会在服务器端被拒绝，如果不是经过正确签名的stamp合并，作者智能体即使有工作凭证也无法绕过门禁。

### 2. 自托管远程 + GitHub镜像
stamp服务器作为事实来源；提交.stamp/mirror.yml以通过post-receive钩子将验证过的提交镜像到GitHub仓库。部署管道（Actions、Vercel、Netlify）与GitHub副本集成。GitHub分支保护限制镜像的推送，因此任何进入GitHub主分支的内容都必须通过stamp服务器的验证推送。

### 3. 纯本地
跳过服务器。stamp-cli仍然在本地生成签名合并提交，stamp verify <sha>可以在任何地方验证它们——但任何有远程推送权限的人（例如没有分支保护的GitHub主分支）都可以绕过门禁。适合个人使用或小型信任团队。

## 审查者提示工程

stamp-cli提供了丰富的工具来迭代审查者提示：

- **stamp reviewers test <name> --diff <revspec>**：在不记录到DB的情况下调用审查者，适合提示调优
- **stamp reviewers show <name>**：查看裁决历史和统计数据，用于校准
- **stamp reviewers verify [<name>]**：检查提示/工具/mcp是否与锁定文件匹配

提示工程的最佳实践是：使用stamp reviewers test进行迭代调优，观察输出，调整提示，重复直到满意，然后再进行正式审查。

## 退出码语义

stamp-cli为智能体设计了清晰的退出码语义：

| 命令 | 退出码0 | 非零退出 |
|------|---------|----------|
| stamp review | 审查者运行并记录 | 调用失败（审查者崩溃、DB错误）——裁决可能已批准也可能未批准；始终跟随stamp status检查门禁 |
| stamp status | 门禁开放（所有必需审查者已批准） | 门禁关闭——至少一个必需审查者缺失或未批准 |
| stamp merge | 合并已签名，在主分支上 | 门禁关闭、预合并检查失败或git合并冲突 |
| stamp push | 远程接受 | 钩子拒绝或标准git错误 |
| stamp verify | 证明有效 | 特定验证步骤失败 |

这种设计让智能体可以通过简单的条件判断来控制工作流。

## 技术依赖与许可

stamp-cli需要Node 22.5+，因为它使用了node:sqlite和node:crypto的Ed25519 API，这些都是内置的但需要22.5+版本。

项目本身采用MIT许可证，但需要注意它通过@anthropic-ai/claude-agent-sdk调用审查者，该SDK受Anthropic专有许可证约束。运行stamp review或安装stamp-cli即表示同意Anthropic的服务条款。

## 实践意义与未来展望

stamp-cli代表了AI原生开发工具的一个重要方向：为智能体设计专门的协议和工具，而不是简单地将人类工具适配给智能体使用。它的价值在于：

1. **结构化审查流程**：定义了清晰的审查者-作者交互协议
2. **加密验证**：通过Ed25519签名提供不可否认的审计追踪
3. **灵活部署**：支持从纯本地到完全托管的多种部署模式
4. **智能体优先**：所有设计决策都以智能体为首要用户

随着AI智能体在软件开发中承担更多责任，像stamp-cli这样的专用工具将成为基础设施的重要组成部分，帮助人类开发者更好地管理和监督AI智能体的协作。