@kanyun-ai-infra/agenthub 1.7.0 → 1.8.0

package/README.md

@@ -1,6 +1,7 @@
-# @kanyun-ai-infra/agenthub
+# @kanyun-ai-infra/agenthub — AgentHub Client SDK
 
-用于 **agenthub Control Plane API** 的类型化 TypeScript 客户端。
+AgentHub 的**客户端 SDK（Client SDK）**：业务系统通过 Control Plane API 程序化地创建/发布 Agent 并调用已部署的 Agent。
+定位区分：Agent 的**文件定义**与 Git 交付走 `agenthub` CLI；本包不承载文件定义。
 
 它直接调用 agenthub Control Plane，适合后端服务、CI 和工具以编程方式驱动
 `project → agent → version → session` 生命周期。
@@ -181,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 后的结果。
+
 ## 完整参考
 
 下面这些内容日常写业务代码用不到，需要时查
@@ -190,7 +222,7 @@ App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清
 | 你想找 | 链接 |
 | --- | --- |
 | 资源方法速查（projects / agents / stages / environments / sessions / files / profiles） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods> |
-| 记忆接口（写入 / 读回 / 确认 / 清空 / 策略）逐端点字段、outcome 与 REST 对照 | <https://agenthub.zhenguanyu.com/v1/docs/api-and-sdk/memories> |
+| 记忆接口（写入 / 读回 / 确认 / 清空 / 策略）逐端点字段、outcome 与 REST 对照 | <https://agenthub.zhenguanyu.com/v1/docs/agent-memory#api> |
 | "发布 → 部署 → 晋级 → 灰度 → 回滚"完整六幕示例 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#release-loop> |
 | Client 配置全部选项、获取 token | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-client-config> |
 | Runtime template 解析顺序 | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#runtime-template> |