开发者文档

可复制粘贴的完整快速开始（徽章 / 验证片段 / SDK / Validator）见 接入中心

1. 安装 Validator（国内用清华镜像，不用翻墙）： python -m pip install jiaozi-validator -i https://pypi.tuna.tsinghua.edu.cn/simple 清华镜像站说明 →
2. 生成主人密钥（私钥自持、永不上传；生成命令见接入中心 Validator 一节，仅演示可用 --demo-owner-key）
3. 本地体检并生成摘要：jiaozi-validator --agent-name MyAgent --path ./my-agent --owner-pubkey-file owner.pub
4. 门户提交摘要，获得凭证标识与 did:web
5. 公开查询：GET /api/resolve?q=JIAOZI-… 或 DID；凭证页 /certs/:certId

SDK 已发布：npm 装 @jiaozi-protocol/sdk，PyPI 装 jiaozi-gdid，用法见接入中心。

接口约定

• POST /api/verify — 受理发证（需 X-Jiaozi-Key）；正常返回 201 + issuedBy: sg-core；签发节点链路断时返回 202 pending，可轮询 /api/verify/pending/:requestId
• attestationDegraded — 发证响应中的布尔提示字段。true 表示签发时服务端认证链尝试了更高信任级的证据插件（TPM / TEE / 云端远程认证）但均不可用，凭证按证据实际支持的等级签发（即响应中的 trustLevel）；申请更高信任级不会被拒发，只会降级签发。验证方处置：信任判定一律以 trustLevel 实际值为准，attestationDegraded 仅是提示，不影响凭证有效性。
• GET /api/resolve?q= — 凭证标识或 DID 公开解析
• GET /agents/:certId/did.json — did:web 标准路径（签发主机 jiaozi.io）

独立核验（不依赖饺子的工具）

凭证与状态全部走开放标准，任何人用通用开源库即可独立验证——不需要我们的 SDK、不需要许可，官网下线也能验。信任根只有一个： https://www.jiaozi.io/.well-known/did.json（did:web 签发方文档，含签发钥与状态钥）。

• GET /api/certs/:certId/vc — W3C VC 2.0 + DataIntegrityProof（eddsa-rdfc-2022）。用 @digitalbazaar/vc 等任意 DI 验证器验签。
• GET /api/status-list/revocation · /api/status-list/suspension — W3C Bitstring Status List：吊销（不可逆）与锁定（可逆）两份签名位图，分钟级新鲜度；VC 里的 credentialStatus 指到对应位置。
• GET /api/status/:certId?format=jwt — 60 秒实时状态的标准表示：VC 2.0 vc+jwt 紧凑 JWS（EdDSA），任何 JOSE 库两行验签，kid 直指 did.json 里的状态钥。缺省（不带 format）仍返回 jiaozi.status.v1 信封，两者同状态同密钥。
• GET /api/status-key — 状态钥便捷公示（标准 Multikey 编码 z6Mk…），权威口径以 did.json 为准。

从源码开发

仅面向想改 Validator 本身的贡献者：克隆仓库后 cd packages/validator && pip install -e .；普通使用请直接用上面的 PyPI 包。

DID Method：did:web（主机 jiaozi.io）；体检在本机完成，只提交摘要哈希，源码不上传。