第 2 章 安装与第一个合同

定位：本章带你在五分钟内完成安装、初始化第一个合同并跑通第一次验证。 前置依赖：第 1 章的心智模型。基于 agent-spec 1.0.0。

安装

安装需要 Rust 工具链（rustup.rs）；使用则不需要任何 Rust 知识——装完就是一个普通 CLI。

cargo install agent-spec
agent-spec --version

agent-spec 1.0.0

也可以克隆仓库一键安装 CLI + 全部技能文件（供 Claude Code / Codex / Cursor 等 Agent 使用）：

git clone https://github.com/ZhangHanDong/agent-spec && cd agent-spec && ./install-skills.sh

初始化第一个合同

init 在当前目录生成合同文件（保留你给的大小写），所以先进入 specs/：

mkdir -p specs && cd specs
agent-spec init --level task --lang zh --name "用户注册API"
cd ..

生成的 specs/用户注册API.spec.md 是一个骨架。合同的完整语法在第 4、5 章展开， 这里先感受最小可用形态：

spec: task
name: "用户注册API"
---

## 意图

为认证模块添加注册端点：邮箱+密码注册，成功后发送验证邮件。

## 边界

### 允许修改
- src/auth/**
- tests/auth/**

## 完成条件

场景: 注册成功
  测试: test_register_returns_201
  假设 不存在该邮箱的用户
  当 客户端提交注册请求
  那么 响应状态码为 201

场景: 重复邮箱被拒绝
  测试: test_register_rejects_duplicate
  假设 已存在该邮箱的用户
  当 客户端提交相同邮箱的注册请求
  那么 响应状态码为 409

注意两点纪律：每个场景都绑定一个测试（测试: 行），异常场景不少于正常场景 ——这两条会被质量门强制（详见第 6 章）。

第一次质量门与验证

agent-spec lint specs/用户注册API.spec.md --min-score 0.7
agent-spec lifecycle specs/用户注册API.spec.md --code . --format json

lifecycle 是主质量门：先重跑 lint（防合同被篡改），再依次跑结构、边界、测试三层 验证。此刻测试还没写，你会看到 skip verdict——skip 不等于 pass，五种 verdict 各司其职（详见第 7 章）。当 Agent（或你）补上实现与测试后，摘要会收敛为（示例，字段与真实输出一致—— 真实摘要固定六键，按字母序）：

"summary": { "failed": 0, "passed": 2, "pending_review": 0, "skipped": 0, "total": 2, "uncertain": 0 }

你刚刚经历了什么

sequenceDiagram
    participant H as 人类
    participant CLI as agent-spec
    participant A as Agent
    H->>CLI: init（骨架）
    H->>H: 填四要素（高价值时间在这里）
    H->>CLI: lint（合同质量门）
    A->>CLI: contract（读执行计划）
    A->>A: 实现 + 测试
    A->>CLI: lifecycle（自检重试循环）
    CLI-->>H: explain（合同级摘要，验收）

这条链路的完整版就是下一章的七步工作流。