真值网关 · API 文档

体系统一真值接入协议 · 版本 V3.0 · 锚定 DID-BR-000002 / Ω₀⊂⊙∞⊂Ω

POST/api/report/truth

真值写入 · 认证：仅 X-DID 单头（零明文令牌）

项	说明
端点	`https://www.huodouai.com/api/report/truth`（无尾部斜杠，带斜杠 404）
认证头	`X-DID: DID-BR-000002`
内容类型	`application/json`
载荷	`{"key":"<唯一key>","value":{事件字段}}`
成功判据	响应含 `"message":"真值写入成功"` + `truth_count`
容错	失败不阻塞主流程；备用端点 `https://drama.huodouai.com/api/report/truth`

curl -X POST https://www.huodouai.com/api/report/truth \
  -H "X-DID: DID-BR-000002" -H "Content-Type: application/json" \
  -d '{"key":"demo.20261003","value":{"event":"示例真值","at":"2026-10-03"}}'

GET/api/status

网关状态 · 返回 status / truth_count / merkle_root / version

curl https://www.huodouai.com/api/status
# {"status":"ok","service":"zhongshu-meta-core","did":"DID-BR-000002",
#  "truth_count":209,"merkle_root":"...","version":"V3.0"}

GET/api/verify（Merkle 完整性校验）

重算账本 Merkle 根 vs 存储根 → 一致性判定（数据防篡改证明）

curl https://www.huodouai.com/api/verify
# {"ok":true,"computed":"db000e95...","stored":"db000e95...","consistent":true,"ledger_lines":272,"checked_at":"..."}

GET/api/truth?key=&limit=（真值查询）

按 key 前缀审计检索（只读，最多 200 条）· 同族：/api/ledger?limit=N 账本快照

curl "https://www.huodouai.com/api/truth?key=cloud&limit=2"
# {"ok":true,"count":2,"results":[{"seq":230,"key":"cloud.arbiter.20261003","value":{...},...}]}

GET/_zongyuan-assets/*（状态数据）

资源	内容
`zhongshu-metrics.json`	实时监控指标（网关/真值/延迟/磁盘/内存）
`zhongshu-nodes.json`	同源节点注册表
`zhongshu-sync.json`	本地⇄云端双向同步状态
`local-asset-index.json`	本地核心资产索引

外部系统接入指南（真值 API 生态）

三步接入，任何系统可成为体系同源节点：

步骤	动作	说明
`1 注册`	向仲裁中枢登记节点身份	分配 `node_id`（如 EXT-SYS-001）+ 自治层级 + 能力通道，写入节点注册表
`2 上报`	POST 真值	`X-DID: DID-BR-000002` 单头 + `key` 命名空间（建议 `<系统>.<事件>.<时间戳>`）+ `value` 事件字段
`3 查询`	GET 状态 / 拉取指令	`/api/status`（全局活性）+ `/zhongshu/data/arbiter/instructions/`（节点指令队列）

# Python 外部系统接入示例
import json, urllib.request
def report_truth(key, value):
    req = urllib.request.Request("https://www.huodouai.com/api/report/truth",
        data=json.dumps({"key": key, "value": value}).encode(),
        headers={"X-DID": "DID-BR-000002", "Content-Type": "application/json"})
    r = json.loads(urllib.request.urlopen(req, timeout=10).read().decode())
    assert r.get("message") == "真值写入成功"
    return r["truth_count"]

# 上报事件
tc = report_truth("ext-sys-001.order.20261003",
    {"event": "order_sync", "system": "外部系统示例", "orders": 128, "at": "2026-10-03"})
print("真值条目:", tc)

生态规则（META-CLOUD-AUTONOMY-001 AU-1~6）：只追加不修改 · 失败不阻塞 · 高风险写操作挂起人工审批 · 全留痕可追溯。

真值网关 V3.0 · 云端中枢 v2.3.0-arbiter · 全链路 append-only 只追加不修改