证据链

wesgine 内置接地声明（Grounded Claims）架构，通过 per-Run hash chain 和结构化证据记录，为 AI Agent 的每一步行为提供可验证的审计追踪。

概览

Run 执行
    │
    ├── 每次工具调用 → EvidenceRef 记录
    ├── 每个模型响应 → EvidenceRef 记录
    └── 每个决策点   → EvidenceRef 记录
    │
    ▼
per-Run Hash Chain
    │
    ├── 链式哈希（前一条的 hash → 下一条的 prev_hash）
    └── 不可篡改（插入/删除/修改会破坏链）
    │
    ▼
持久化到 state.db
    │
    ├── GET /observe/evidence  → JSONL 流式导出
    └── GET /audit/export      → 完整审计导出

接地声明架构

设计原则

"接地声明"意味着 AI Agent 的每个行为和决策都有据可查：

1. 每一步可追溯：从最终结果反向追踪到原始输入
2. 机械可验证：hash chain 可由程序自动校验，不依赖人工
3. 防篡改：任何中间环节的修改都会破坏后续哈希链
4. 完整导出：可完整导出为 JSONL 用于外部审计

三层分离

EvidenceRef 结构

每条证据记录包含：

{
    "id": "ev-a1b2c3d4",
    "run_id": "run-x1y2z3",
    "seq": 42,
    "timestamp": "2026-09-14T13:00:00.123Z",
    "type": "tool_call",
    "data": {
        "tool": "exec",
        "input": {"command": "go build ./..."},
        "output": {"exit_code": 0, "stdout": "..."},
        "duration_ms": 1200
    },
    "hash": "sha256:a1b2c3...",
    "prev_hash": "sha256:x1y2z3..."
}

字段说明

事件类型

per-Run Hash Chain

链式结构

Evidence[0]  →  Evidence[1]  →  Evidence[2]  → ...
    │               │               │
    hash=H(data)    hash=H(data)    hash=H(data)
    prev_hash=∅     prev_hash=H0    prev_hash=H1

哈希计算

H(evidence) = SHA-256(
    run_id || seq || timestamp || type || JSON(data) || prev_hash
)

验证算法

def verify_chain(evidences):
    """验证 per-Run 证据链完整性"""
    for i, ev in enumerate(evidences):
        # 1. 序号连续
        assert ev.seq == i

        # 2. 前向链接
        if i == 0:
            assert ev.prev_hash == ""
        else:
            assert ev.prev_hash == evidences[i-1].hash

        # 3. 哈希正确
        expected = sha256(
            ev.run_id + str(ev.seq) + ev.timestamp +
            ev.type + json(ev.data) + ev.prev_hash
        )
        assert ev.hash == expected

    return True  # 链完整

切片不可验证

证据链是逐 Run hash chain，切片后缺环无法校验。这是 /observe/evidence 抬到 cell:admin 且不做 per-actor 过滤的原因（INV-OBS-09）——"只给我看我自己的审计记录"不是审计。

JSONL 导出

API

GET /cells/{id}/observe/evidence
→ Content-Type: application/x-ndjson
→ 流式返回每行一个 JSON 对象

格式

每行一个 JSON 对象，按 run_id + seq 排序：

{"id":"ev-001","run_id":"run-abc","seq":0,"type":"run_start","data":{...},"hash":"sha256:...","prev_hash":""}
{"id":"ev-002","run_id":"run-abc","seq":1,"type":"llm_request","data":{...},"hash":"sha256:...","prev_hash":"sha256:..."}
{"id":"ev-003","run_id":"run-abc","seq":2,"type":"tool_call","data":{...},"hash":"sha256:...","prev_hash":"sha256:..."}

审计导出

完整的审计数据导出支持多种格式：

GET /cells/{id}/audit/export?format=jsonl&from=2026-09-01&to=2026-09-14
GET /cells/{id}/audit/export?format=csv&from=2026-09-01&to=2026-09-14

审计摘要：

GET /cells/{id}/audit/summary
→ {
    "total_runs": 1250,
    "total_evidence": 48000,
    "chain_integrity": "verified",
    "period": {"from": "...", "to": "..."}
  }

审计用途

合规审计

金融/法律/医疗等受监管行业需要完整的 AI 决策审计追踪：

审计员请求：
"请提供 2026年9月 法务部门 AI 助手的所有决策记录"

→ GET /cells/dept-legal/audit/export?format=csv&from=2026-09-01&to=2026-09-30
→ 包含每次对话、工具调用、治理决策的完整链
→ hash chain 验证确认无篡改

事故回溯

当 AI 产生不当行为时，通过证据链精确回溯：

// 查看特定 Run 的所有工具调用
tools, _ := cell.Observe().RunTools(ctx, runID)
for _, t := range tools {
    fmt.Printf("[%s] %s(%v) → %v\n",
        t.Timestamp, t.Tool, t.Input, t.Output)
}

行为归因

结合 actor 标签，可以按人归因行为：

// 查看 alice 的所有 Run
runs, _ := cell.Observe().ListRuns(ctx, wesgine.ObserveFilter{
    Actor: "alice",
    From:  startDate,
    To:    endDate,
})

与 Observe 体系的关系

证据链是 Observe（可观测性）体系的子集：

Actor 边界（INV-OBS-08/09/10）

最佳实践

1. 定期验证链完整性：使用审计摘要 API 确认 chain_integrity: verified
2. 保留导出备份：定期 JSONL 导出存储到外部审计系统
3. 金融合规启用 Regulated 预设：Compliance: "financial" 自动启用严格审计
4. 不要尝试切片证据链：查询单 actor 的行为使用 Run 列表而非证据链
5. 活用 Run Tools 接口：事故回溯时先 ListRuns 定位，再 RunTools 看细节

相关 API