可观测性

wesgine 的观测体系：Token 用量、Run 追踪、证据链、崩溃日志与 Actor 边界。

Token 用量

细粒度查询

GET /cells/{id}/observe/token-usage

多维过滤：

参数	说明
`GroupBy`	model / agent / session / day / tag:actor
`Tags`	按标签过滤
`Model`	按模型过滤
`Session`	按会话过滤
`From` / `To`	时间范围

聚合摘要

GET /cells/{id}/observe/token-summary
GET /cells/{id}/observe/token-usage/aggregate?agent=&group_by=day&days=

Run 追踪

列表

GET /cells/{id}/observe/runs?agent=&session=&limit=&offset=

详情

GET /cells/{id}/observe/runs/{runID}

工具调用追踪

GET /cells/{id}/observe/runs/{runID}/tools

Cell 统计

GET /cells/{id}/observe/stats

运行时统计快照。

Run 追踪摘要

GET /cells/{id}/observe/traces

证据链

GET /cells/{id}/observe/evidence

JSONL 流格式。逐 Run hash chain，切片后缺环无法校验。

INV-OBS-09：抬作用域到 cell:admin，按 Cell 全量不过滤。

崩溃日志

GET /cells/{id}/observe/crash-log

Hypervisor 级观测

hyp.Observe().Snapshot()                  // HypervisorSnapshot
hyp.Observe().PerCellStats(ctx, cellIDs)  // []CellStats
hyp.Observe().CrashLog(ctx)              // []CrashEvent
hyp.Observe().ProviderLatencyStats(ctx)   // []ProviderLatency
hyp.Observe().ListRuns(ctx, filter)       // []RunTraceSummary

Actor 边界（INV-OBS-08~10）

三个判据层

层	执行点
SQL 谓词	`actorClause`（`internal/observe/actor.go`）
无归属表	`runOwnedByActor` EXISTS 子查询
公共 API	`CellObserveHandle` 每个方法首参 `actor string`

空 actor 语义

?actor= 只对 admin token 生效。非 admin 一律取 token 里的 actor。

漏传 = 合法的跨 actor 越权读取（不报错）。

页外过滤禁止

过滤必须在 LIMIT 之内：

WHERE actor_clause AND ... LIMIT ?
-- 不是
SELECT * LIMIT ? → Go 过滤

事件环（INV-OBS-10）

事件先进 per-Run 内存环再进 wes_run_traces。

只守 SQL 那一侧 = 把最新最全的一份留在门外。

RunEventBuffer 记 owner，Snapshot 判 observe.RunVisible。

无主 Run

owner == "" → 隐藏（不是"公共"）。

不属于你与不存在同返空流。

审计

方法	路径	说明
GET	`/audit/export`	`?format=jsonl\|csv&from=&to=`
GET	`/audit/summary`	审计摘要

INV-OBS-09：抬到 cell:admin，不做 actor 过滤。