CodeRifts

CodeRifts — 合约变更授权

只有获得授权的变更才能继续。 在合约变更合并、部署或注册之前，CodeRifts 会判定其是否已获授权；未获得授权时，检查结果为红色。

一项授权将三件事绑定在一起：授权本身、一次性使用，以及变更将转向的目标状态。判定经过签名，回执可离线验证——无需信任我们的数据库，也能检查授权内容。

每项判定还会说明它不能证明什么。

• 托管 MCP 服务：https://app.coderifts.com/mcp
• 清单：https://coderifts.com/mcp.json — 规范的已发布文档。此仓库根目录下的 mcp.json 是指向它的指针，而非第二份副本。
• 官方 MCP Registry：io.github.coderifts/api-governance
• 网站：https://coderifts.com
• 在线演示 PR：https://github.com/coderifts/demo/pull/4

---

安装

# Claude Code
/plugin marketplace add coderifts/api-governance
/plugin install api-governance@coderifts

# Any MCP client (Streamable HTTP) — add to its MCP config
{ "mcpServers": { "coderifts": { "url": "https://app.coderifts.com/mcp",
  "headers": { "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>" } } } }

# SDKs
npm install @coderifts/sdk
pip install coderifts-sdk

GitHub Copilot 会在三个不同的根键下读取同一服务——.vscode/mcp.json 中的 servers、云 Agent 的 MCP 设置中的 mcpServers，以及自定义 Agent 前置元数据中的 mcp-servers——而 npx coderifts copilot-setup 会写入这三项（详情见下文）。

只有授权时才需要密钥；请前往 https://app.coderifts.com/api/signup 获取。

---

Claude Code 插件

安装 CodeRifts marketplace，然后安装 api-governance 插件（MCP 服务 + 技能）。 调用工具需要 CODERIFTS_API_KEY。

/plugin marketplace add coderifts/api-governance
/plugin install api-governance@coderifts

本地检出（克隆后）：

/plugin marketplace add .
/plugin install api-governance@coderifts

该插件连接托管 MCP 服务 https://app.coderifts.com/mcp 和 api-governance 技能。仅提供以下工具：preflight_change_set、verify_receipt、 get_decision_details。

---

Cursor 插件

Cursor 插件包（经验证的 Cursor 布局：.cursor-plugin/plugin.json + skills/ + rules/ + mcp.json + hooks/hooks.json）。与 Claude 插件使用相同的托管 MCP 服务和 相同的三个工具——没有第四个工具。确定性 / 签名 / 默认拒绝——不是 AI 兼容性扫描。

路径	作用	事实来源
plugins/api-governance-cursor/.cursor-plugin/plugin.json	Cursor 插件清单	cursor/plugins plugin.schema.json
plugins/api-governance-cursor/skills/coderifts/SKILL.md	技能（name: coderifts）	生成 — coderifts-app scripts/generate-skill-carriers.js；网站上的 .well-known/agent-skills/coderifts/SKILL.md 从此处引入
plugins/api-governance-cursor/rules/coderifts.mdc	Cursor 规则	生成 — generate-agent-host-files.js
plugins/api-governance-cursor/mcp.json	Streamable HTTP MCP 接线	与 Claude .mcp.json 使用同一端点（不是网站的工具卡片）
plugins/api-governance-cursor/hooks/hooks.json	preToolUse 适配器，failClosed: true	CLI coderifts cursor-hook 在 Write|Delete 上运行——结构与应用生成的 .cursor/hooks.json 相同
.cursor-plugin/marketplace.json	Cursor marketplace 条目	Cursor marketplace.schema.json

验证：

npm run validate:cursor

当 CODERIFTS_APP_ROOT（默认为 ~/coderifts-app）中存在 generated/agent-host/.cursor/rules/coderifts.mdc 时，生成规则检查为 LIVE；不存在时，则针对 fixtures/recorded/app-generator 检查，并标记为 RECORDED（强度较低，且有明确标记）。缺少或 损坏的快照仍会以状态码 1 退出——不会静默跳过。

---

OpenAI / Codex 包

Codex 插件包（采用经过验证的 OpenAI Codex 布局：.codex-plugin/plugin.json + .mcp.json + skills/ + AGENTS.md）。使用相同的托管 MCP 和与 Claude 插件完全相同的三个工具 ——没有第四个工具。

路径	用途	信息来源
plugins/api-governance-openai/.codex-plugin/plugin.json	Codex 插件清单	Codex plugin-json-spec（脚手架技能）
plugins/api-governance-openai/.mcp.json	Streamable HTTP MCP 接线	与 Claude .mcp.json 使用相同端点
plugins/api-governance-openai/skills/api-governance/SKILL.md	技能 + 工具列表	触发措辞来自 Agent 设置规则；工具名称和描述来自生成的 mcp.json
plugins/api-governance-openai/AGENTS.md	Agent 规则文件	生成——coderifts agent-setup / generate-agent-host-files.js
plugins/api-governance-openai/openai-agent-instructions.md	OpenAI Agents SDK 指令	生成——使用同一生成器
plugins/api-governance-openai/docs/openai-production-pattern.md	生产模式（ID108）——包含 executeOpenAIToolCall 的宿主分发循环	手工编写的方案，基于已发布的 @coderifts/agent-guard ≥ 6.4.0（首个导出 executeOpenAIToolCall 的 npm 版本；当前 npm 版本为 17.3.3）
plugins/api-governance-openai/scripts/smoke-execute-openai-tool-call.mjs	离线冒烟测试（ALLOW + BLOCK；无需 OpenAI 密钥）	实际分发器 + 桩客户端
.agents/plugins/marketplace.json	Codex 市场条目	Codex 市场架构

生产模式（函数调用应用）

OpenAI 的模型只会输出 tool_call JSON；由你的应用执行它。应在该宿主循环中接入治理， 而不是使用 Claude 风格的 PreToolUse 钩子。完整步骤和一个规范循环见：

→ plugins/api-governance-openai/docs/openai-production-pattern.md

# Offline smoke (needs ~/coderifts-agent-guard built, or CODERIFTS_AGENT_GUARD_ROOT)
npm run smoke:openai-dispatch

⚠ 截至 2026-09-24 重新测量后，仍卡在同一项断言上：ALLOW factory ran — execute() did not run。其余八项断言均通过（4 项 ALLOW，5 项 BLOCK）；而对门控至关重要的 BLOCK 路径已全部通过：工厂不会运行，内容是门控拒绝，不会伪造成功，并且会显示决策身份。失败的断言出现在 ALLOW 路径：分发包装器返回了函数结果，却没有调用注入的工厂。

这条说明的 2026-09-14 版本以“正在调查”结尾。我们没有更新日期，而是删掉了这句话：十天过去了，这项进展无法通过本文中的任何内容验证；而在 README 中自报尽责，恰好是在报告读者无法核实的事情。读者能核实的是断言名称和今天的日期。

在 Codex 中本地检出（团队市场路径）：

# From a clone of this repo, point Codex at .agents/plugins/marketplace.json
# then install api-governance-openai (UI / plugin install — see Codex plugin docs).

验证包的一致性（清单、工具一致性、重新生成 AGENTS.md 后无差异）：

npm run validate:openai
# or: node scripts/validate-openai-package.js

如果 ~/coderifts-app（或 CODERIFTS_APP_ROOT）存在，重新生成 AGENTS.md 时将使用实时生成器；如果不存在，则会使用 fixtures/recorded/app-generator 中的记录快照（较弱，但已明确标注）。 快照缺失或损坏时仍会以状态码 1 退出。此处不会自动执行目录列表或账户提交步骤。

---

GitHub Copilot 工具包

已生成的 Copilot MCP 配置和指令的参考副本（唯一来源： coderifts-app 生成器）。使用相同的托管 MCP 和完全相同的三个工具——没有第四个工具。

主要安装方式（实时命令——优先使用此方式，而不是从工具包中复制）：

npx coderifts copilot-setup
# optional: --out <dir>   --check (drift-gate)   --force

Agent 宿主指令（包括 .github/copilot-instructions.md）来自：

npx coderifts agent-setup

三种 Copilot 接入方式（根键各不相同）

参见生成的指南（copilot/docs/copilot-mcp.md——请勿重新编写此表）：

接入方式	配置位置	根键	身份验证
VS Code / Copilot Chat	.vscode/mcp.json	servers	${input:coderifts_api_key} + inputs[]
Copilot 云端 Agent + 代码审查	仓库 Settings → Copilot → MCP servers（粘贴 JSON）	mcpServers	headers 中的 Agents secret COPILOT_MCP_CODERIFTS_API_KEY
自定义 Agent（组织/企业）	Agent 配置文件 .md YAML frontmatter	mcp-servers	${{ secrets.COPILOT_MCP_CODERIFTS_API_KEY }}

所有接入方式均允许使用以下工具：preflight_change_set、verify_receipt、get_decision_details。

随附的参考目录树（copilot/）

路径	用途	权威来源
copilot/.vscode/mcp.json	VS Code / Copilot Chat	生成 — generate-copilot-mcp.js
copilot/copilot-cloud-agent-mcp.json	云端 Agent 粘贴用 JSON（mcpServers）	生成 — 同上
copilot/copilot-custom-agent-mcp.frontmatter.md	自定义 Agent YAML frontmatter	生成 — 同上
copilot/docs/copilot-mcp.md	安装指南 + 接入方式表	生成 — 同上
copilot/.github/copilot-instructions.md	Copilot 编码 Agent 指令	生成 — generate-agent-host-files.js
copilot/SOURCE.md	来源信息 + 重新同步命令	打包说明（此仓库）

验证重新生成后无差异，并遵守 3 个工具的规范：

node scripts/validate-copilot-kit.js

当 CODERIFTS_APP_ROOT 中存在生成器时，重新生成后无差异验证为 LIVE；若不存在，则对照 fixtures/recorded/app-generator 验证，状态为 RECORDED（强度较弱，已明确标注）。 快照缺失或损坏时，仍会以状态码 1 退出。该工具包是一个沟通 / 分发镜像——安装仍须使用 npx coderifts copilot-setup。

---

Agent Skill（skills.sh）

npx skills add coderifts/api-governance

skills CLI 会发现此仓库根目录下的 skills/api-governance/SKILL.md，并以 api-governance 为名称进行安装。安装位置取决于 Agent（参见 CLI 自带的表格）：大多数 Agent（Codex、Cursor、Gemini CLI、GitHub Copilot、OpenCode，……）会安装到 .agents/skills/api-governance/，Claude Code 则会安装到 .claude/skills/api-governance/。

一个 Skill，一个名称（2026-09-29）。 三个 SKILL.md 载体——Claude（plugins/api-governance/skills/api-governance/）、Cursor（plugins/api-governance-cursor/skills/coderifts/）和 Codex/OpenAI（plugins/api-governance-openai/skills/api-governance/）——包含逐字节相同的正文，以及相同的 name: coderifts，这也是 skills.sh 列出的名称（npx skills add coderifts/api-governance 会安装到 ./.agents/skills/coderifts/，于 2026-09-29 测得）。只有 frontmatter 中的 description 因宿主而异。三个载体均由 coderifts-app 的 scripts/generate-skill-carriers.js 根据 agent/skills/coderifts/SKILL.md 生成；test/one-skill.test.js 确保三者保持一致。网站上的 .well-known/agent-skills/coderifts/SKILL.md 是随附的 Cursor 载体。

MCP 服务

CodeRifts 以托管式 Streamable HTTP MCP 服务的形式运行。任何兼容 MCP 的 Agent（Claude Desktop、Cursor、LangGraph、AutoGen、自定义 Agent）都可以连接，并在调用工具或合并代码前运行治理检查。

• 端点： https://app.coderifts.com/mcp
• 传输方式： Streamable HTTP（协议版本 2025-06-18）
• 服务端： CodeRifts API Governance v1.0.3 — 于 2026-09-24 从 initialize → result.serverInfo.version 读取。在 README 中填写的版本号只是带日期的声明；npm run validate:tools-wire 会在每次推送、拉取请求和每日 cron 中将 TOOLS 与在线服务进行比较，但没有任何检查会比较这一行，因此请重新读取，而不要轻信。
• 身份验证： initialize、tools/list 和 analyze 类 tools/call 无需密钥（于 2026-09-26 在线测得）。authorize 调用会签发签名回执，需要 API 密钥——请发送 Authorization: Bearer <key> 或 X-API-Key: <key>。

连接

{
  "mcpServers": {
    "coderifts": {
      "url": "https://app.coderifts.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>"
      }
    }
  }
}

验证连接

curl -sS https://app.coderifts.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

预期结果：包含 serverInfo 和 capabilities.tools 的 JSON-RPC result。

无需密钥即可试用

通过 MCP 发起 analyze 调用无需密钥：

curl -sS https://app.coderifts.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preflight_change_set","arguments":{"preflight_mode":"analyze","artifacts":[{"id":"api","type":"openapi","before":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n                  name: {type: string}\n","after":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n"}]}}}'

实测响应（实时数据，2026-09-26 — 从 GET /pets 中移除 name），位于工具结果中：

{ "preflight_mode": "analyze", "analysis_outcome": "BREAKS_DETECTED",
  "authorization_effect": "NONE", "may_execute": false, "receipt_kind": "NONE",
  "breaking_changes": 1, "risk_score": 14 }

这是信息，不是许可：每个 analyze 答案中的 may_execute 都是 false。要执行操作，请使用密钥再次调用，并设置 preflight_mode: "authorize" 和 context.operation。

有两个公共 REST 端点完全无需身份验证：

curl -s "https://app.coderifts.com/api/v1/public/preflight?url=https://petstore3.swagger.io/api/v3/openapi.json"

curl -s -X POST https://app.coderifts.com/api/v1/public/actionguard-check \
  -H "Content-Type: application/json" \
  -d '{"filename":".github/workflows/ci.yml","base_content":null,"head_content":"jobs:\n  b:\n    steps:\n      - uses: some-owner/some-action@main"}'

两者在没有密钥的情况下都会返回 HTTP 200。但它们的响应结构并不相同：

• GET /api/v1/public/preflight 仅用于 analyze。没有 decision 字段。响应正文包含 analysis_outcome（Petstore URL：NO_BREAK_DETECTED）、authorization_effect: NONE 和 may_execute: false。
• POST /api/v1/public/actionguard-check 会返回 decision 字段（未固定版本的 uses: @main 负载：WARN）以及 execution_action: CONTINUE_WITH_MONITORING。

---

工具

托管 MCP 服务恰好提供三个工具（来自实时 tools/list；在本仓库中固定于 tools.wire.v1.json，npm run validate:tools-wire 会在每次推送、拉取请求及每日 cron 运行时检查其与实时服务的一致性）：

工具	功能
preflight_change_set	对完整的基础版本→头版本契约制品变更集进行预检。返回风险评分和破坏性变更分析。设置 preflight_mode: "authorize"（以及 context.operation）时，会返回治理决策（ALLOW / WARN / REQUIRE_APPROVAL / BLOCK），并可能生成签名链收据。设置 preflight_mode: "analyze" 时，仅返回风险信息（may_execute: false，不含决策，也不含收据）。需要 artifacts 和 preflight_mode。
verify_receipt	验证你已持有的签名链收据：签名真实性、正文绑定，以及（生命周期索引可用时）当前是否已获准执行指定操作／目标。需要 token。不会重新比较规范差异。
get_decision_details	通过 decision_id（首选）或 fingerprint 检索过往决策：存储的报告、破坏性变更、评分，以及关联的收据元数据（如有）。不用于分析当前变更集。

在 preflight_change_set 的 authorize 路径上，决策封套包含 decision、execution_action、risk_score、safe_for_agent 等字段，以及相关分析字段，以便 Agent 运行时依据稳定的契约进行分支处理。若存在 execution_action，优先根据该字段进行分支处理。

---

Agent 如何使用

1. 在合并 API 变更之前（或 Agent 根据契约变更采取行动之前），使用完整的变更前后制品调用 preflight_change_set，并设置 preflight_mode: "authorize"（以及 context.operation）。
2. 仅根据 execution_action 进行分支处理：CONTINUE 表示继续，CONTINUE_WITH_MONITORING 表示接入监控接收端后继续，REQUEST_APPROVAL 表示暂停并等待人工审批，STOP 表示停止合并／中止 Agent 步骤。任何其他值都不代表许可——默认拒绝。
3. 在依据持有的收据采取行动之前，使用预检时相同的上下文调用 verify_receipt，并且仅在 currently_authorized 为 true 时采取行动。除非变更集或操作发生变化，否则不要重新预检。
4. 要按 ID 查看过往决策，请调用 get_decision_details。

决策逻辑是确定性的：单个破坏性变更绝不会被默许。测试通过了，契约仍可能存在缺陷并被发布——CodeRifts 会在 PR 阶段检查契约本身。

---

另请参阅

• GitHub App 位于 GitHub Marketplace — 无需配置即可安装，并会在每个拉取请求中发布签名的合约变更决策（ALLOW / WARN / REQUIRE_APPROVAL / BLOCK），涵盖四个检查关卡：API 合约、架构与代码一致性、身份验证接口和工作流操作。⚠ 默认情况下，它仅报告：检查的第一阶段结论会限制为 neutral，且 MERGEGATE_ENFORCE 默认值为 false，因此只有在分支上将该检查设为必需且启用该变量后，它才会阻止合并。平台真值表是区分这两种情况的权威来源：https://coderifts.com/docs/platform-truth-table/
• SDK： npm install @coderifts/sdk（TypeScript）、pip install coderifts-sdk（Python）。
• CLI： coderifts（npm），带有一个推送前钩子。
• 集成： Backstage 插件、VS Code 扩展、LangGraph / AutoGen / CrewAI。

链接

• 网站：https://coderifts.com
• 决策规范：https://coderifts.com/decision-spec/
• API 参考：https://app.coderifts.com/api/docs
• 清单：https://coderifts.com/mcp.json
• 回执验证器（无需信任我们即可验证我们的回执）：https://github.com/coderifts/receipt-verifier
• 联系方式：[email protected]

许可证

请参阅 LICENSE。