Asqav SDK是面向 AI Agent 的可验证证据层：它为每一次 Agent 动作签发带签名的合规回执（Compliance Receipt，ML-DSA-65 后量子签名 + 哈希链 + 独立时间见证），并支持策略执行与审计追踪，可接入 LangChain、CrewAI、MCP 等生态。本文带你把它做成一道GitHub Actions 门禁：每个 PR 自动执行治理体检（asqav doctor）、导出合规包，并为 AI 参与的代码变更签发代码署名回执（code-authorship receipt），让"谁改了代码、改了什么"成为任何第三方可独立验证的签名事实。

为什么把 AI 治理检查放进 CI？

AI Agent 已经能直接改代码、调 API、跑流水线。传统代码审查只能看"改了什么"，却回答不了三个问题：

1. 这次变更是谁（人或哪个模型）做的？
2. Agent 的行为有没有留下可验证的审计记录？
3. 扫描器豁免、风险接受这类例外，有没有"到期作废"的机制？

Asqav SDK 的答案是：把治理检查变成 CI 的必过项。SDK 自带一个doctor子命令（python/src/asqav/cli.py），检查 API Key 是否配置、后端是否可达、SDK 版本是否正常，任何一项失败就返回非零退出码——正好适合让 CI 直接挂掉。官方甚至把"没有密钥时 doctor 报FAIL并让任务失败"当成期望行为。

官方完整说明见 docs/github-actions.md，仓库还提供两个开箱即用的 Action：

最快上手：4步搭好治理门禁

准备两样东西：一个 Asqav API Key（ASQAV_API_KEY），以及下面这个最小 workflow（放入.github/workflows/governance.yml）：

name: governance on: pull_request: push: branches: [main] jobs: governance: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install asqav run: pip install asqav - name: Validate setup env: ASQAV_API_KEY: ${{ secrets.ASQAV_API_KEY }} run: asqav doctor

就这么短，整个 CI 门禁就搭好了。asqav doctor会打印PASS / FAIL逐项体检结果（API key、API 可达性等），任一项失败即返回非零，PR 直接红叉。

💡 doctor 只读环境变量和公开 API，跑在 fork PR 上也安全；涉及签名的步骤建议用if: github.event.pull_request.head.repo.fork == false保护。

进阶：把签名回执打包成合规 Bundle

如果测试过程中会通过agent.sign(...)产生回执，可以在 CI 里把它们追加进一个 JSONL 文件，再用export_bundle打成带 Merkle 根的自包含合规包作为 workflow artifact 存档——这就是审计师最终下载的东西。Bundle 携带框架元数据、全部回执和 Merkle 根，离线即可校验，无需回调 Asqav。

目前内置的合规框架包括eu_ai_act_art12、eu_ai_act_art14、dora_ict、soc2，完整列表见 python/src/asqav/compliance.py。完整的"pytest fixture 捕获回执 + 导出 bundle + 上传 artifact"工作流，直接抄 docs/github-actions.md 里的模板即可。

代码署名回执：谁改的代码，服务器说了算

这是本仓库最有趣的部分。github-action/ 下的 Action 在每个 PR 上做两件事：

1. 在 runner 上计算一个建议性diff 摘要（sha256(git diff <base>..<head>)，实现见 github-action/sign_code_authorship.py）；
2. 调用 Asqav 服务器，服务器会自己重新拉取 commit、重新计算规范 diff，并用 ML-DSA-65（FIPS 204）签发一份 in-toto Statement v1。

关键点在于诚实的边界：绑定的摘要永远是服务器重算的那个，Action 本地算的只是参考值（digest-match只报告两者是否一致）。作者身份是"生产者声明"（producer-asserted，如human:alice@example.com或model:claude-opus-4-8），记录但不由 Asqav 验证。

3行接入 PR

jobs: record: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 # 必须拉全历史，否则算不出 base..head diff - name: Record Asqav code-authorship receipt uses: asqav-sdk/github-action@main with: asqav-api-key: ${{ secrets.ASQAV_API_KEY }} change-class: write author: model:claude-opus-4-8

常见输入参数一览（定义见 github-action/action.yml）：

输出则包括signature-id（回执签名 ID）、server-digest（绑定进 Statement 的服务器摘要）、intoto-statement-path（落盘的 in-toto Statement 文件路径）等，可直接upload-artifact归档或推入透明日志。

第三方如何独立验证？

回执不依赖信任 Action 或生产方，验证四步（见 github-action/README.md）：

1. 按commit_sha重新拉取 commit；
2. 用 JCS（RFC 8785）规范化变更文件列表并重算 SHA-256；
3. 比对结果与 Statement 中subject[0].digest.sha256；
4. 用jwks_url上按kid解析的公钥验证 ML-DSA-65 签名。

因为回执就是标准 in-toto Statement，它可以无缝接入既有 attestation 工作流，包括 Sigstore Rekor 透明日志条目和 GitHub Artifact Attestations。

风险接受回执：给豁免上"定时炸弹"

扫描器报了一个漏洞，团队决定先接受风险？github-action-risk-acceptance/ 让这次接受变成可审计的签名事实：

• mint 模式：PR 审批通过时触发，记录"某扫描发现（SARIF 文件只算摘要、不上云）+ 谁批准 + 谁发起 + 理由 + 过期时间"，服务器用 ML-DSA-65 签名。SARIF 文件绝不会被上传，只取 SHA-256。
• audit 模式：定时任务对豁免清单（suppression manifest）逐条核验回执——缺失、验签失败或已过期都会让 CI 变红。

这就形成了一个不会"悄悄变成永久"的闭环：

扫描器报警 → 例外PR加豁免（审批时mint回执，expires: 90d） → 定时audit通过 → 90天后回执过期 → audit失败 → 移除豁免 → 扫描器再次报警 → 重新决策（新回执 supersedes 旧回执）

过期时间支持90d、12h、30m等写法，也支持supersedes字段显式指向被替代的旧回执。完整参数表见 github-action-risk-acceptance/action.yml。

实战小贴士清单 📋

• 固定版本：治理流程稳定后把 SDK 钉住（pip install "asqav==<version>"），升级时批量更新，提前暴露破坏性变更。
• 先跑 doctor 再谈别的：它是最便宜的"配置烟雾测试"，密钥没配好时 PR 第一时间红，而不是签名步骤中途报错。
• 理解"建议性摘要"：digest-match: false只是提示值不一致，权威摘要始终以服务器重算为准，这是设计使然而非故障。
• 别混淆两个 hook 体系：asqav/hooks.py是进程内签名回调（fail-open），而asqav hookCLI 是给 Claude Code 用的 harness hook，Mode B（PreToolUse）是 fail-closed 硬门禁。详解见 hooks/README.md。
• 离线验证能力：回执可用asqav verify <signature_id>公开核验（无需 API Key），也可用verify_receipt_offline零信任离线复验签名，算法按回执signature.alg逐条选取。

相关文档与源码索引

把asqav doctor挂进每次 PR、给 AI 改过的代码签上署名回执、给每个豁免设定到期时间——三件事做完，你的 AI 治理就从"纸面制度"变成了 CI 里每 10 分钟跑一次、谁都能独立复核的硬约束。