玄圭 · 软件可信裁决套件 API

云端中枢只读侧车 axg-sidecar127.0.0.1:8420/api/axiomgate/
应用层工单裁决 · 配额只读校验 · 账本完整性校验 · 全部 POST 端点要求 X-DID 身份头

口径先行：本套件为软件实现，不提供 TPM/TEE 硬件信任根，对外不得表述为「硬边界裁决」。客户如需硬件级信任根，可自备 TPM 模块接入外接插件。所有端点只读运行：不写业务库、不扣减配额、不改账本。

安装：curl -fsSL https://www.huodouai.com/axiomgate-deploy/install.sh | bash —— 验签、选端口、装服务、自检一条命令完成；离线包与回滚见部署说明。

GET

健康检查

zr-axg-sidecar.health正式服务名: axg-sidecar

公开只读，不需要 X-DID，不计入限流。用于探活、版本核对与策略版本比对。

GET https://www.huodouai.com/api/axiomgate/health

响应体

{
  "ok": true,
  "service": "axg-sidecar",
  "version": "AXG-SIDECAR V1.0",
  "mode": "read_only",
  "policy_version": "AXG-POLICY-V1",
  "endpoints": ["/api/axiomgate/health", "/api/axiomgate/verdict",
                "/api/axiomgate/quota", "/api/axiomgate/audit"],
  "anchor": "Ω₀⊂⊙∞⊂Ω",
  "did": "DID-BR-000002"
}

GET

授权状态

zr-axg-sidecar.license

公开只读，不需要 X-DID。返回试用剩余天数、授权到期时间、签名校验结果与时钟回拨检测状态。

GET https://www.huodouai.com/api/axiomgate/license

响应体（试用中）

{
  "ok": true,
  "mode": "trial",
  "valid": true,
  "trial_days": 30.0,
  "trial_started_at": 1794034393,
  "trial_ends_at": 1796626393,
  "days_left": 30,
  "hours_left": 720
}

响应体（已授权）

{
  "ok": true,
  "mode": "licensed",
  "valid": true,
  "license_id": "AXG-LIC-DC44806E",
  "edition": "enterprise",
  "expires_at": 2109394412,
  "days_left": 3650
}

mode	含义
`trial`	试用中，全功能可用
`licensed`	授权有效，按授权到期时间
`trial_expired`	试用到期或被判定时钟回拨，执行端点返回 403
`invalid`	签名无效 / 已过期 / DID 不匹配，执行端点返回 403

POST

工单裁决复核

zr-axg-sidecar.verdict

对工单执行确定性规则判定：DID 格式、DID 黑名单、事件类型白名单、设备标识、载荷体积、时间偏移、金额符号。同一输入多次调用裁决与哈希恒定，供第三方复算。

POST https://www.huodouai.com/api/axiomgate/verdict Headers: Content-Type: application/json · X-DID: DID-BR-000002

请求体

{
  "did": "DID-BR-000002",
  "event_type": "api.aholo.generate",
  "device_id": "node-01",
  "payload": {"prompt": "昆仑殿"},
  "amount": 1,
  "ts": 1794033000
}

响应体（放行）

{
  "ok": true,
  "verdict": "ALLOW",
  "reasons": [],
  "risk_score": 0,
  "request_digest": "92fafc9ae84259b52c78d49c5d4d14b3fe34bd032b3ec38878c96eb5758d8546",
  "policy_version": "AXG-POLICY-V1",
  "verdict_id": "AXG-V-d1d7af84a79939ca",
  "verdict_hash": "D1D7AF84A79939CAADE43CA696A5507944FBA897E1B1D122FEB6D3C070DD8CAA",
  "hash_scope": "verdict+reasons+risk_score+request_digest+policy_version",
  "anchor": "Ω₀⊂⊙∞⊂Ω"
}

裁决与原因码

裁决	触发条件	说明
`ALLOW`	无任何原因码	放行，可进入下游业务链路
`REVIEW`	仅含提示级原因码	未知事件类型、时间偏移、缺设备标识
`REJECT`	含阻断级原因码	身份非法、类型非法、载荷超限、金额为负

码	含义	处置
`R001`	missing_did	工单未携带 did，直接拒绝
`R002`	did_format_invalid	不匹配 `DID-BR-######`，直接拒绝
`R003`	did_blocked	命中黑名单，直接拒绝
`R004`	missing_event_type	事件类型缺失或不在白名单，直接拒绝
`R005`	payload_too_large	载荷超过 4096 字节，直接拒绝
`R006`	event_type_unknown	落在待审清单，转人工复核
`R007`	timestamp_skew	时间戳偏差超 300 秒，提示复核
`R008`	amount_negative	金额为负，直接拒绝
`R009`	device_id_missing	IoT 类事件缺设备标识，提示复核

如何复算：取响应中的 verdict、reasons、risk_score、request_digest、policy_version 五个字段，按 JSON 键排序、紧凑分隔符序列化后做 SHA256，应等于 verdict_hash。哈希不覆盖自身，因此不存在自引用循环。

POST

配额余量只读校验

zr-axg-sidecar.quota

读取授权台账中的额度上限与已用量，判断本次请求是否在余量内。只读不扣减，实际扣减由上层调度引擎负责，避免双写冲突。未登记的服务默认放行并标记 registered=false。

POST https://www.huodouai.com/api/axiomgate/quota Headers: Content-Type: application/json · X-DID: DID-BR-000002

请求体

{"service": "api.aholo.generate", "amount": 20}

响应体

{
  "ok": true,
  "allowed": true,
  "registered": true,
  "did": "DID-BR-000002",
  "service": "api.aholo.generate",
  "requested": 20.0,
  "limit": 1000.0,
  "used": 0.0,
  "remaining": 1000.0,
  "headroom_after": 980.0,
  "deducted": false
}

字段	说明
`allowed`	本次请求量是否在剩余额度内
`deducted`	恒为 false，套件不写台账
`registered`	false 表示未登记，按默认放行并提示补录

POST

账本完整性校验

zr-axg-sidecar.audit

对 M9 统一账本的 7 个源文件逐项计算 SHA256 并与记录比对，同时按公开规则复算链式根哈希。资产漂移与根哈希不复算被严格区分：前者是篡改风险，后者是记账口径待校准。

POST https://www.huodouai.com/api/axiomgate/audit Headers: Content-Type: application/json · X-DID: DID-BR-000002 · Body: {}

响应体

{
  "ok": true,
  "status": "ASSETS_INTACT",
  "sources_checked": 7,
  "sources_matched": 7,
  "drift": [],
  "root_match": false,
  "root_recorded": "EE15006F63201E50E3FDBC4EFE938BC9AE9120AB4EFEE09225ABC7F54C9B12D3",
  "root_recomputed": "4845E25187B966F7AAC644EB2DE68AC3F214060EB5011E8808FC9A6EF3374314",
  "root_note": "root 不复算仅表示记录口径待校准，不等于篡改；以 sources_matched 为准"
}

status	含义
`ASSETS_INTACT`	全部源文件哈希匹配，HTTP 200
`ASSET_DRIFT`	存在源文件漂移，HTTP 409，drift 中列出明细
`LEDGER_UNREADABLE`	账本不可读，HTTP 409

通用

鉴权、限流与错误码

POST 端点统一要求 X-DID 身份头，格式 DID-BR-######。默认限流 60 次 / 10 分钟 / IP，阈值可用环境变量 AXG_RATE_LIMIT 调整。

状态码	含义	排查方向
`200`	正常返回	—
`403`	license_required	试用到期或授权无效；访问 `/license` 确认状态
`400`	invalid_json / 参数非法	检查请求体 JSON 与 amount 取值
`401`	X-DID 缺失或格式非法	补 X-DID，格式须为 DID-BR-######
`409`	审计发现资产漂移	查看 drift 明细，确认是否人为改动
`429`	触发限流	按 retry_after 秒后重试

快速验证

curl -s https://www.huodouai.com/api/axiomgate/health

curl -s -H 'X-DID: DID-BR-000002' -H 'Content-Type: application/json' \
  -X POST https://www.huodouai.com/api/axiomgate/verdict \
  -d '{"did":"DID-BR-000002","event_type":"iot.lock","device_id":"lock-01"}'

玄圭 · 软件可信裁决套件 API 文档 · 对外版｜产品页 · API 总览 · 裁决内核白皮书
锚定 Ω₀⊂⊙∞⊂Ω · DID-BR-000002