@kanyun-ai-infra/agenthub 1.7.1 → 1.8.0

package/README.md

@@ -182,6 +182,37 @@ App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清
 这些端点需要 `memories:write` / `memories:read` scope，且**只认 platform token**
 （门户登录态会被 403 `PLATFORM_TOKEN_REQUIRED` 挡掉）。
 
+## Turn 上的观测字段
+
+`agenthub.sessions.turns.get` / `.list`（以及 `waitForTurn` 返回的 `turn`）除了
+状态、消息、交付结果这些业务字段，还带三个**观测字段**，供用量对账、链路排查和记忆
+召回留痕：
+
+| 字段 | 含义 |
+| --- | --- |
+| `usage` | 模型用量（`inputTokens` / `outputTokens` / `totalTokens` 等）。其中 `costUsd` 是 Claude Code CLI **自报的列表价估算**（`costSource === "claude_code_cli"`），不是账单实付；`failed` / `aborted` 轮次没有 `usage`（T-INV-13）。`completed` 轮次也可能缺省——用量数据没通过校验时字段不落，并在该轮 `anomalies` 里记 `usage_parse_failed`。 |
+| `traceId` | 这一轮的分布式 trace id（`string \| null`），可拼 Octopus trace-explorer 深链定位整条链路（agenthub → control-worker → agent-worker）。 |
+| `memoryRecall.state` | **只在会话首轮出现**——设计如此，不是版本或故障问题：读服务只给首轮投影这个字段（`session-turns-read-service.ts` 的 `core.turnId === enrichment.firstTurnId` 判据），第 2 轮起 `memoryRecall` 恒为 `undefined`，即便服务端是最新版。值是这一轮的**记忆召回状态**枚举，不是召回内容：`selected`（召回并注入了条目）/ `empty`（功能开着、也查了，本轮无可注入记忆）/ `recall_failed`（召回过程失败）/ `unavailable`（回读时没能解出召回快照）/ `legacy`（会话早于记忆机制，无快照）。目前只对外暴露状态，召回内容展示挂在另一条线（#1837）。 |
+
+三个字段都是可选/可空的：`usage` 与 `memoryRecall` 是可选字段，`traceId` 可空、没有
+链路时为 `null`。写消费代码时一律按「缺失」处理，不要假定它们一定存在。
+
+**但「缺失」不等于「服务端旧」**——这三个字段各有自己的恒定缺失场景，轮询 `turns.list`
+看到空值先对照下面再判故障：`memoryRecall` 只有首轮有；`usage` 在 `failed` / `aborted`
+轮次没有，`completed` 轮次遇到用量解析失败也会缺（看 `anomalies` 里的
+`usage_parse_failed`）；`traceId` 在没采到链路时是 `null`。
+
+`traceId` 的 Octopus 深链（照 `apps/agent-hub` 里 `octopusTraceUrl` 的真实参数，
+query 名是 `traceExplorerQuery` 而非 `traceId`）：
+
+```text
+https://octopus.zhenguanyu.com/#/trace-explorer?env=<test|online>&time=<起-止,ms>&traceExplorerQuery=trace_id%20%3D%20<traceId>&traceExplorerQueryMode=label&traceExplorerQuerySpanType=entrySpan&traceExplorerSortField=endTime&traceExplorerSortOrder=desc
+```
+
+其中 `env` 只可能是 `test` 或 `online`（trace 数据不进 development 桶）；`time` 是
+一个绝对时间窗（ms，通常取该轮 `dispatchedAt` 前后各 1 小时）；`traceExplorerQuery`
+是 `trace_id = <traceId>` 整体 URL-encoded 后的结果。
+
 ## 完整参考
 
 下面这些内容日常写业务代码用不到，需要时查