N4darae/shrt

项目介绍

shrt 用有顺序的 API 调用链来测试后端：登录、建条目、加库存、再读回来。调用链是 YAML 文件；跑通一次后由人批准为基线，之后每个版本都对着基线重放。当响应字段发生变化时，shrt 会指出出错步骤、字段以及它怀疑造成漂移的写操作。

契约文件描述每个 RPC 应有的行为：哪些字段必填、值从哪来、怎么返回错误、写操作对数字有什么影响。有了契约，shrt 能自动规划调用链，包括边界值、缺失或错误 token、不存在的 ID、重复 key 等探测。项目面向由编程代理驱动设计（shrt init 会安装 Claude Code 技能），但所有命令也能手工执行 README。

安装与协议要求

需要 Go 1.26 或更新版本，并把 buf 放在 PATH 上，因为 shrt 用 buf build 编译后端的 .proto 文件 安装说明。它使用 Connect 协议（JSON over HTTP POST），适用于 connect-go 构建的服务，因为 connect-go 同时提供 Connect 与 gRPC。只讲二进制 gRPC over HTTP/2 的服务不支持。支持一元和服务器流式 RPC；流式步骤只读第一条消息。

go install github.com/N4darae/shrt/cmd/shrt@latest
shrt version

也可以在代码检出目录里用 go build -o shrt ./cmd/shrt 构建后把二进制放到 PATH 构建说明。

快速开始：inventory 演示

仓库自带 examples/inventory 这个 connect-go 小服务，含四个 RPC；以 -release 2 启动时 GetItem 会读到过期缓存，演示正是要抓这个回归。先把示例复制出来，因为 shrt init 会把 .shrt/、.claude/ 和 .gitignore 写进当前目录 演示准备。

git clone https://github.com/N4darae/shrt
cp -r shrt/examples/inventory /tmp/inventory-demo
cd /tmp/inventory-demo
go build -o inventory . && ./inventory &
export API_USER=demo API_PASSWORD=demo-password
shrt init
shrt doctor

init 会从 proto 构建描述符、猜测哪个 RPC 是登录，并读一次登录响应确认成功包结构；凭据留在环境变量里，运行记录中的密码和 token 会被脱敏 init 输出。然后加载示例契约并自动生成调用链：

shrt contract init -all
cp contracts/inventory.yaml .shrt/contracts/
shrt contract lint
shrt contract plan -all -write
shrt gate
shrt confirm -all -note "release 1 of the inventory demo"
shrt confirm -all -approve -by you@example.com

plan 为每个 RPC 写一条链（示例中共四条链、53 步），gate 把每条链跑一遍。提出的通过运行必须由人批准后，各响应字段才进入基线 审批步骤。把服务换成 release 2 重启并再跑一次 shrt gate 就能看到回归：

kill %1
./inventory -release 2 &
shrt gate

此时 inventory-addstock 链应失败，输出会指明 item.qty_on_hand want=5 got=0 及怀疑的写操作，并让 gate 以退出码 1 结束，从而在 CI 中判失败 预期失败。

使用约束

调用链会创建记录并故意发送错误请求，因此工具限制目标：除非主机列入 target.allow_hosts，否则只向 localhost、127.0.0.1 或 ::1 发送；不在列表中的主机会让 run、verify、gate 以及 init 的登录在首次调用前直接拒绝。run -dry-run 仍然可用，因为它不发送请求。shrt 无法自行区分预发和生产，因此只应列出你愿意让其数据被修改的后端 目标限制。

契约和调用链通过环境变量引用凭据，运行记录会脱敏密码和 token。项目采用 MIT 许可证 许可证。

HotRepo 点评

站内记录显示，该项目在 2026-11-03 的 Go 月榜上以 2,110 星、当期新增 1,711 星排第 10。只有这一条快照，没有全语言日榜名次或 Star 曲线采样，因此只能支撑「当月表现强」这一事实，不能据此判断趋势。设计上值得留意的是审批关口：代理可以提出基线，但必须由人确认，这与项目「由代理驱动但不把回归决策完全交给模型」的定位一致。

与代理配合使用

shrt init 会安装 .claude/skills/shrt/SKILL.md、一个负责写契约的子代理，以及 .shrt/docs/ 下的代理文档；文档来源在 docs/agent/，包括命令参考、配置与调用链字段、操作流程和症状到修复的对照表。设计与限制见 docs/OVERVIEW.md。所有命令用 -h 都能打印参数和退出码。