@kanyun-ai-infra/agenthub 1.8.0 → 1.10.0

package/README.md

@@ -50,12 +50,10 @@ const agenthub = new PilotPlatformClient({
   // controlPlaneUrl 可省略——默认打线上地址；打 test 等环境再显式传（或设 PILOT_CONTROL_PLANE_URL）。
 });
 
-// 1. Project：租户 / 根分组。默认 runtime template 让发布 Version 时不必每次手选模板。
-const project = await agenthub.projects.create({
-  slug: "acme",
-  displayName: "Acme",
-  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
-});
+// 1. Project：租户 / 根分组。模型服务按 Project 归属、目前只能在门户「凭证与集成」→「模型服务」
+//    里配，所以这里用一个已经配好模型服务的 Project。新建用 agenthub.projects.create({ slug,
+//    displayName, defaultRuntimeTemplateRefName })，建完先去门户给它配一套模型服务。
+const project = await agenthub.projects.get("<已配好模型服务的 Project id>");
 
 // 2. Agent：Project 下一个可运行的 agent。
 await agenthub.agents.create({
@@ -64,7 +62,6 @@ await agenthub.agents.create({
   displayName: "Support Bot",
   kind: "managed_agent",
   defaults: {
-    model: "claude-opus-4-7",
     systemPrompt: "You are the Acme support agent.",
     agentPackage: {
       format: "claude_code",
@@ -87,7 +84,10 @@ const version = await agenthub.agents.publishVersion({
   workerContract: { kind: "managed_agent" },
   setDefault: true,
   managedAgentProfileSnapshot: {
-    model: "claude-opus-4-7",
+    // 模型服务必填：没声明模型服务的 Agent 建不出会话（SESSION_LLM_PROVIDER_REQUIRED）。
+    // 填这个 Project 那套模型服务的 publicId（llmp_ 开头，门户列表里复制）。
+    // model 省略 = 用该模型服务声明的默认档位。
+    llmProviderRef: "llmp_xxxxxxxxxxxxxxxx",
     systemPrompt: "You are the Acme support agent.",
   },
 });
@@ -108,6 +108,23 @@ const ready = await agenthub.sessions.wait(session.sessionId); // status === "re
 > 要额外给槽位绑一个 Environment，才有资源规格定制、canary 灰度、drift 检测、
 > 一键回滚这些能力：完整走一遍见下方「完整参考」里的发布闭环六幕示例。
 
+### 代表用户调用（仅第一方服务）
+
+服务到服务的场景（门户、后台任务等）可以用**第一方服务 token** 声明「代表某个用户」：
+给客户端传 `actAs`（用户 LDAP），此后该客户端发出的**每个**请求——JSON、multipart
+上传、SSE（首连与带 `Last-Event-ID` 的重连）——都带代表声明头。
+
+```ts
+const agenthub = new PilotPlatformClient({
+  token: process.env.PILOT_SERVICE_TOKEN, // 第一方服务 token（actor:delegate）
+  actAs: "zhangsan", // 代表 zhangsan 行事
+});
+```
+
+仅第一方服务 token 可用：其他 token 带它会得到 403 `ACT_AS_NOT_ALLOWED`（服务端开关
+未开：403 `ACT_AS_DISABLED`；值不是用户标识：400 `ACT_AS_INVALID`）。空串 / 纯空白在
+构造时即抛。`defaultHeaders` 或单次请求的 `headers` 里写同名头不能覆盖 `actAs`。
+
 ## 核心模型
 
 ```text
@@ -192,7 +209,7 @@ App 里点的"对"；`purge(projectId, { subjectKind, subjectId })` 按主体清
 | --- | --- |
 | `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）。 |
+| `memoryRecall.state` | **只在会话首轮出现**——设计如此，不是版本或故障问题：读服务只给首轮投影这个字段（`session-turns-read-service.ts` 的 `core.turnId === enrichment.firstTurnId` 判据），第 2 轮起 `memoryRecall` 恒为 `undefined`，即便服务端是最新版。值是这一轮的**记忆召回状态**枚举，不是召回内容：`selected`（召回并注入了条目）/ `empty`（功能开着、也查了，本轮无可注入记忆）/ `recall_failed`（召回过程失败）/ `unavailable`（回读时没能解出召回快照）/ `legacy`（会话早于记忆机制，无快照）。目前只对外暴露状态，不含召回内容。 |
 
 三个字段都是可选/可空的：`usage` 与 `memoryRecall` 是可选字段，`traceId` 可空、没有
 链路时为 `null`。写消费代码时一律按「缺失」处理，不要假定它们一定存在。