用途
pr-to-spec 用于把观察到的代码变更转换为带版本的 JSON 规格，并与声明的意图进行比对，从而检测意图漂移。它强调以结果和支撑信号、风险、契约与策略证据为先，并且明确要求：绝不能把非零的 gate 退出码当作普通的 CLI 失败来处理。
主要能力
- 声明意图：通过
intent set设置目标、作用范围、禁止范围、最大风险等级等，并可用intent show查看。 - 本地比较：支持三种比较模式——分支比较（
--branch）、暂存区比较（--staged）、最近提交比较（--diff）。其中--staged优先于--diff；否则 CLI 会将当前分支与--branch或 main 比较。 - 远程 PR 分析：通过根命令
pr-to-spec --repo OWNER/REPO --pr 42 --json分析 GitHub 拉取请求。 - 检查已完成工作：
check使用与 scan 相同的比较边界，评估漂移、验证契约和策略门禁。 - 结构化输出：JSON 输出使用带版本的 agent-protocol 信封，包含 version、command、status、exit_code、signals、spec、intent 等字段。
使用方式
前置条件：在被分析的 Git 仓库内运行，需要 Node.js 20+ 且 pr-to-spec 在 PATH 中。若本地 ref 可能过期，在分支比较前先获取目标 base ref。远程 PR 分析需通过环境变量提供 GITHUB_TOKEN，建议使用具有拉取请求读取权限的细粒度令牌，不要在命令行传递或打印令牌。.pr-to-spec/intent.yaml、contracts.yaml、policy.yaml 视为项目治理状态，提交前应审查变更。
典型流程：
- 编辑前声明意图，例如：
pr-to-spec intent set \
--goal "Add rate limiting to the API" \
--scope "src/middleware/**" \
--forbid "src/db/**" \
--max-risk medium \
--json
pr-to-spec intent show --json
当 --type 或 --size-budget 表达真实验收边界时可添加。不要在出现漂移结果后仅为让门禁通过而扩大意图。
- 选择一种本地比较方式并请求 JSON：
pr-to-spec scan --branch main --json
pr-to-spec scan --staged --json
pr-to-spec scan --diff 3 --json
当发现高风险变更时，scan 可能退出码为 2，即使它已生成有效规格。
- 检查已完成工作：
pr-to-spec check --branch main --json
若不存在意图，check 会回退到 scan 行为并返回 0 或 2；存在意图时，会评估漂移、验证契约和策略门禁。在决定工作是否可继续前，应读取 JSON 的 status、signals、gate_result 和 contracts 字段。
- 响应门禁退出码：
- 0：在评估边界内干净。
- 2：有效结果但存在高风险变更，需审查风险标记。
- 3：漂移或阻塞性契约违规，需修复变更或有意修订意图并给出明确说明。
- 4：策略门禁失败，需满足其阻塞性检查。
- 1：调用、Git、配置或运行时错误，需修复后重跑。
绝不能把 2–4 折叠为通用失败，因为每种都需要不同的响应。
输出
JSON 输出使用带版本的 agent-protocol 信封，例如：
{
"version": 1,
"command": "check",
"status": "drift_detected",
"exit_code": 3,
"signals": [],
"spec": {},
"intent": {}
}
报告应包含比较边界、退出码及含义、变更文件摘要、最高风险、每个漂移信号、契约与门禁结果，以及下一步安全操作。当 JSON 用于门禁发布时，应连同审查证据一并保留。
适用场景
- 在编辑代码前声明意图，编辑后检查是否发生意图漂移。
- 对分支、暂存区、最近提交或 GitHub 拉取请求进行变更分析。
- 在发布流程中作为门禁，依据退出码和 JSON 结果决定是否继续。
限制与错误处理
- 缺少 base ref：获取或选择已存在的 ref，用
git branch -a验证。 - 无变更：确认所选分支、暂存集或提交数量。
- 无意图：声明一个用于漂移检查，或说明 check 使用了仅 scan 行为。
- 退出码 2、3 或 4：在补救前先解析发出的信封。
- 远程认证失败：验证仓库访问和令牌范围，不要记录令牌。
- 治理 YAML 格式错误：修复指定的
.pr-to-spec文件并重跑。
其他具体功能、收费、价格、平台或效果信息暂未提供。