speccheck

speccheck

规范只有在实际落实它的工作完成后才有价值。需求被写下，问题被提交，拉取请求被合并，代码被提交——而在这一堆工作中，“规范要求做什么”与“声称已完成什么”之间的对应关系，会悄然腐化。speccheck 会审计这种对应关系。你提供规范中的需求，以及针对这些需求提出的声明，它会报告哪些需求已覆盖、哪些未覆盖、哪些声明指向不存在的需求，以及每项需求收到了多少条声明。

不会获取任何内容。只要至少一条声明提到了某项需求的 id，该需求就算已覆盖；声明来源可以是问题、拉取请求或代码引用，重复声明都会计数——三个问题都声称解决了同一项需求，这个事实值得在计数中体现，而不是作为重复项去重。若声明提及的 id 不属于任何需求，则该声明为悬空声明：它会按原样完整回显，并保持声明到达时的顺序，且不计入任何地方——既不计入覆盖情况，也不计入任何需求的总数。这通常意味着需求已重命名或存在拼写错误；无论是哪种情况，都应该由规范所有者发现，而不是让工具猜测。

判定结果会用一个词概括报告。如果每项需求都有声明，则规范为 fully_covered。否则，覆盖率百分比——已覆盖需求数除以需求总数，四舍五入到最接近的整数——决定判定结果：80 及以上为 mostly_covered，50 及以上为 partial，低于 50 则为 sparse。判定结果始终附带计数，因此无需盲目相信这个词。

格式错误的输入会产生一条指出出错路径的验证错误，不会返回部分结果：requirements 必须是非空对象数组，每个对象都必须包含非空的 id 和 text；需求 id 必须唯一（重复时会指出该 id 并报错）；claims 必须是对象数组，可以为空，每个对象都必须包含非空的 requirement_id 和 source_ref，以及值为 issue、pr 或 code 的 source_kind。未知的额外字段会被忽略。整个计算是纯粹的本地操作：不会联网，不需要配置，也不会读取或触碰任何代码仓库。

CLI

npx @reneturcios/speccheck check --input args.json
npx @reneturcios/speccheck --version

args.json 包含完整的参数对象：

{
  "requirements": [
    { "id": "REQ-1", "text": "Users can sign in with a passkey" },
    { "id": "REQ-2", "text": "Sessions expire after 24 hours" },
    { "id": "REQ-3", "text": "Admins can revoke any session" }
  ],
  "claims": [
    { "requirement_id": "REQ-1", "source_kind": "pr", "source_ref": "PR #412" },
    { "requirement_id": "REQ-1", "source_kind": "issue", "source_ref": "issue #388" },
    { "requirement_id": "REQ-2", "source_kind": "code", "source_ref": "src/session.ts" },
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ]
}

结果会以 JSON 格式打印：

{
  "covered": ["REQ-1", "REQ-2"],
  "uncovered": ["REQ-3"],
  "dangling_claims": [
    { "requirement_id": "REQ-9", "source_kind": "issue", "source_ref": "issue #401" }
  ],
  "claim_counts": { "REQ-1": 2, "REQ-2": 1, "REQ-3": 0 },
  "coverage_percent": 67,
  "verdict": "partial",
  "requirement_count": 3,
  "claim_count": 4
}

claim_counts 会为每项需求提供一个条目，包括计数为零的需求；键的顺序与需求提供时的顺序一致。退出代码：成功时为 0，发生运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/speccheck mcp

MCP 客户端配置：

{
  "mcpServers": {
    "speccheck": {
      "command": "npx",
      "args": ["-y", "@reneturcios/speccheck", "mcp"]
    }
  }
}

工具

• check_spec_coverage — 根据调用方提供的需求和声明事实，验证问题、拉取请求或代码是否声明解决了规范中的需求。

  • requirements（数组，必填，至少 1 项）— 规范中的需求；每项都是包含非空 id 和 text 的对象，且 id 必须唯一
  • claims（数组，必填，可以为空）— 声明某个问题、拉取请求或代码引用解决了某项需求；每项都是包含非空 requirement_id、值为 issue、pr 或 code 的 source_kind，以及非空 source_ref 的对象

  返回 {covered, uncovered, dangling_claims, claim_counts, coverage_percent, verdict, requirement_count, claim_count}。

Docker

docker run -i ghcr.io/cloudcorprecords/speccheck
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/speccheck check --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios