@kanyun-ai-infra/agenthub 0.2.0 → 0.4.0

package/README.md

@@ -3,7 +3,7 @@
 用于 **agenthub Control Plane API** 的类型化 TypeScript 客户端。
 
 它直接调用 agenthub Control Plane，适合后端服务、CI 和工具以编程方式驱动
-`project -> workload -> revision -> session` 生命周期。
+`project → agent → version → session` 生命周期。
 
 接入时会遇到两个入口：
 
@@ -38,16 +38,14 @@ const agenthub = new PilotPlatformClient({
   token: process.env.PILOT_TOKEN, // 管理门户签发的 platform-api token
 });
 
-// 1. Project：租户 / 根分组。默认 runtime template 让调用方发布
-//    Revision 时不必每次手选模板。
+// 1. Project：租户 / 根分组。默认 runtime template 让发布 Version 时不必每次手选模板。
 const project = await agenthub.projects.create({
   slug: "acme",
   displayName: "Acme",
   defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
 });
 
-// 2. Agent：Project 下一个可运行的 agent/app
-//    （`agents` 是 `workloads` 的别名，下文「术语别名」有说明）
+// 2. Agent：Project 下一个可运行的 agent。
 await agenthub.agents.create({
   projectId: project.id,
   slug: "support-bot",
@@ -56,12 +54,20 @@ await agenthub.agents.create({
   defaults: {
     model: "claude-opus-4-7",
     systemPrompt: "You are the Acme support agent.",
+    agentPackage: {
+      format: "claude_code",
+      source: {
+        kind: "oss",
+        url: "https://bucket.oss-cn-beijing.aliyuncs.com/pilot/agent-packages/support-bot.tar.gz",
+        sha256: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        sizeBytes: 4096,
+      },
+      entryCommand: "报告",
+    },
   },
 });
 
-// 3. Version：Agent 的不可变发布版本（`publishVersion` 是 `publishRevision`
-//    的别名）。Runtime source 默认继承 Project default；要按版本覆盖传
-//    `runtime.profileRef`。
+// 3. Version：Agent 的不可变发布版本。Runtime source 默认继承 Project default。
 const version = await agenthub.agents.publishVersion({
   projectId: project.id,
   agentSlug: "support-bot",
@@ -74,79 +80,52 @@ const version = await agenthub.agents.publishVersion({
   },
 });
 
-// 4. Session：基于默认 Version 或指定 Version 分配一次运行时
-//    （Session 接口仍用 `workloadId` 字段 —— 核心模型保持 workload 命名）
+// 4. Session：基于默认 Version（或指定 Version）分配一次运行时。
 const session = await agenthub.sessions.create({
   projectId: project.id,
-  workloadId: version.workloadId,
+  agentId: version.agentId, // 用默认 Version；指定版本传 versionId
 });
 
 const ready = await agenthub.sessions.wait(session.sessionId); // status === "ready" 时返回
 ```
 
-## Client 配置
-
-`new PilotPlatformClient(config)`
-
-| 选项 | 必填 | 说明 |
-| --- | --- | --- |
-| `controlPlaneUrl` | 是¹ | Control Plane 源地址。相对路径会拼到它下面；跨 origin 路径会在发 token 前被拒绝。 |
-| `token` | 是¹ | Platform-api token。每个请求都会作为 `Authorization: Bearer <token>` 发送。 |
-| `fetch` | 否 | 自定义 `fetch` 实现，默认使用全局 `fetch`。 |
-| `signal` | 否 | 应用于每个请求的默认 `AbortSignal`。 |
-| `defaultHeaders` | 否 | 合并到每个请求的额外 header。 |
-| `userAgent` | 否 | 覆盖默认 `@kanyun-ai-infra/agenthub/<version>` UA。 |
-| `pilotApiVersion` | 否 | 固定 `x-pilot-api-version` header，默认使用 v2 wire version。 |
-
-¹ `controlPlaneUrl` 会依次回退到 `PILOT_CONTROL_PLANE_URL`、
-`KANYUN_PILOT_CONTROL_PLANE_URL`；`token` 会回退到 `PILOT_TOKEN`。任意一项缺失时，
-SDK 会在发送请求前抛出类型化错误。
-
-### 获取 token
-
-登录 **管理门户** <https://agenthub.zhenguanyu.com> 并签发 **platform-api token**。
-该 token 的作用域是 Control Plane API（`agenthub-plane.zhenguanyu.com`）；可以存为
-`PILOT_TOKEN`，也可以显式传给 `token`。Token 是 Bearer 凭据，请不要提交到代码仓库；
-泄露后需要在门户里轮换。
-
 ## 核心模型
 
 ```text
-Project  ->  Workload  ->  Revision  ->  Session
+Project  →  Agent  →  Version  →  Session
 ```
 
-- **Project**：租户 / 根分组，拥有 workloads 和 runtime templates。
-- **Workload**：一个逻辑可运行应用。`kind` 是 `"managed_agent"`（平台基于
+- **Project**：租户 / 根分组，拥有 agents 和 runtime templates。
+- **Agent**：一个逻辑可运行应用。`kind` 是 `"managed_agent"`（平台基于
   `model` + `systemPrompt` 运行 agent loop）或 `"self_managed"`（你自己提供 worker）。
-- **Revision**：Workload 的不可变发布版本，绑定一个 runtime source。用 `setDefault`
-  标记 project/workload 默认版本。
-- **Session**：基于某个 Revision 发起的一次 startup/runtime allocation。
+- **Version**：Agent 的不可变发布版本，绑定一个 runtime source。用 `setDefault`
+  标记 project/agent 默认版本。
+- **Session**：基于某个 Version 发起的一次 startup/runtime allocation。
 
-Workloads 和 runtime templates 都是 **project-scoped**。Revision 必须在同一个 Project
-内解析到 Workload 和 runtime source；唯一例外是下文的 platform-shared templates。
+Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一个 Project
+内解析到 Agent 和 runtime source；唯一例外是下文的 platform-shared templates。
 
-### 术语别名（agent / version）
+> 本文一律用主词汇 **agent / version**；它们是底层 wire 名 `workload` / `revision`
+> 的别名，SDK 两套都接受，细节见 [术语别名](#术语别名agent--version)。
 
-为降低理解成本，SDK 为核心概念提供了一组**别名**——语义完全一致，只是更口语化：
+### 术语别名（agent / version）
 
-| 规范名（核心模型） | 友好别名 | 说明 |
+| 主词汇（推荐） | 等价的底层名 | 说明 |
 | --- | --- | --- |
-| `agenthub.workloads` | `agenthub.agents` | **同一个资源实例**，方法完全一致。 |
-| `workloads.publishRevision({ workloadSlug })` | `agents.publishVersion({ agentSlug })` | 同一个调用；友好版用 `agentSlug`，内部映射回 `workloadSlug` 后发出，wire body 完全一致。 |
-| 概念 “Workload” / “Revision” | “Agent” / “Version” | 仅命名差异。 |
+| `agenthub.agents` | `agenthub.workloads` | **同一个资源实例**（`agents === workloads`），方法两边都能调。 |
+| `agents.publishVersion({ agentSlug })` | `workloads.publishRevision({ workloadSlug })` | 同一个调用；wire body 完全一致。 |
+| `sessions.create({ agentId, versionId })` | `sessions.create({ workloadId, revisionId })` | 入参别名，内部映射回规范名后再发出。 |
+| 返回字段 `result.agentId` / `result.versionId` | `result.workloadId` / `result.revisionId` | 返回对象**同时带**两套字段（别名 = 规范值）。 |
 
-`agentSlug` 仅在 `publishVersion` 上；`publishRevision` 仍用 `workloadSlug`。
-`applyRevisionManifest` 两个拼写都接受（同时给出时 `workloadSlug` 优先）。
+规则：
 
-别名是**附加糖**：`workloads` / `publishRevision` / `workloadSlug` 一直保留，行为不变；
-返回结果的字段名（`workloadId` / `revisionId`）以及 `sessions.create({ workloadId })`
-仍沿用核心模型命名。挑读起来顺的那套写即可。
-
-```ts
-// 下面两段完全等价
-await agenthub.agents.publishVersion({ projectId, agentSlug: "support-bot", version: "v1", workerContract: { kind: "managed_agent" } });
-await agenthub.workloads.publishRevision({ projectId, workloadSlug: "support-bot", version: "v1", workerContract: { kind: "managed_agent" } });
-```
+- **互斥**：一对里只能传一个，规范名和别名同传会抛 `ALIAS_CONFLICT`，避免笔误被静默忽略
+  （`sessions.create` 的 `agentId`/`workloadId`、`versionId`/`revisionId`，
+  `applyRevisionManifest` 的 `agentSlug`/`workloadSlug`）。
+- 入参别名**不进 wire**：发请求前映射回 `workloadId`/`revisionId`，body 永远是规范名。
+- 返回别名是 SDK 派生的可枚举字段（`JSON.stringify` / 日志都带得上），不回传服务端。
+- 底层名（`workloads` / `publishRevision` / `workloadId`）一直保留、行为不变，挑读着顺的那套写即可。
+- 异步事件 payload、日志 / Trace 里的关联 ID 仍是 `workloadId`/`revisionId`（属 control-plane 范畴，不在 SDK 改名范围内）。
 
 ## API 参考
 
@@ -157,121 +136,39 @@ await agenthub.workloads.publishRevision({ projectId, workloadSlug: "support-bot
 | `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | 创建 Project。slug 重复时返回 `409 PROJECT_SLUG_CONFLICT`。 |
 | `list()` | 列出 token 有效 scope 内的 Project。 |
 | `get(projectId)` | 查询单个 Project。 |
+| `delete(projectId)` | 软删（停用）Project：清空 owner / members、关闭集成。**owner-only**（需 `project:settings`）。系统项目不可删。返回 `{ action: "deactivated", projectId }`。 |
 
-### `agenthub.workloads`（别名 `agenthub.agents`）
-
-> `agenthub.agents` 与 `agenthub.workloads` 是同一个对象，下表方法两边都能调。
+### `agenthub.agents`（别名 `agenthub.workloads`）
 
 | 方法 | 说明 |
 | --- | --- |
-| `create(req, { dryRun? })` | 用结构化输入创建 Workload。返回 `{ mode, status, workloadId?, workload }`。 |
-| `publishRevision(req, { dryRun? })` | 发布 Revision。返回 `{ mode, status, workloadId, revisionId?, runtimeTemplateId, resolved }`。 |
-| `publishVersion(req, { dryRun? })` | `publishRevision` 的友好别名；`req` 用 `agentSlug` 代替 `workloadSlug`。返回结构与 `publishRevision` **完全相同**（字段仍是 `workloadId` / `revisionId`，不会改名为 `agentId` / `versionId`）。 |
-| `applyManifest({ projectId, manifest, dryRun? })` | 高级 / GitOps：apply raw workload manifest。 |
-| `applyRevisionManifest({ projectId, workloadSlug \| agentSlug, manifest, dryRun? })` | 高级 / GitOps：apply raw revision manifest。两个 slug 拼写都接受，同时给出时 `workloadSlug` 优先。 |
-
-`create` 的 `req`：
-
-```ts
-{
-  projectId: string;
-  slug: string;
-  displayName: string;
-  kind: "managed_agent" | "self_managed";
-  defaults?: {
-    model?: string;
-    systemPrompt?: string;
-    workerContract?: { name?: string; version?: string };
-    configValues?: Record<string, string>;
-    enabledSkills?: EnabledSkill[];
-    enabledMcpServers?: EnabledMcpServer[];
-  };
-  ui?: { /* Default-UI hints */ };
-}
-```
-
-`publishRevision` 的 `req`：
-
-```ts
-{
-  projectId: string;
-  workloadSlug: string;
-  version: string;
-  workerContract: { kind: "managed_agent" | "self_managed"; name?: string; version?: string };
-  runtime?: { profileRef?: { name: string }; environment?: ...; overrides?: ... };
-  setDefault?: boolean;
-  startup?: { requiredGates?: string[]; optionalGates?: string[] };
-  configValues?: Record<string, string>;
-  managedAgentProfileSnapshot?: { model?: string; systemPrompt?: string; enabledSkills?: ...; enabledMcpServers?: ... };
-}
-```
+| `create(req, { dryRun? })` | 创建 Agent。返回 `{ mode, status, agentId?/workloadId?, workload }`。 |
+| `publishVersion(req, { dryRun? })` | 发布 Version（别名 `publishRevision`，用 `workloadSlug`）。返回 `{ mode, status, agentId/workloadId, versionId?/revisionId?, runtimeTemplateId, resolved }`。 |
+| `applyManifest({ projectId, manifest, dryRun? })` | 高级 / GitOps：apply raw agent manifest。 |
+| `applyRevisionManifest({ projectId, agentSlug \| workloadSlug, manifest, dryRun? })` | 高级 / GitOps：apply raw version manifest。两个 slug 拼写都接受（互斥）。 |
+
+`create` / `publishVersion` 的 `req` 结构和 managed-agent 全部配置项（`model` /
+`systemPrompt` / `enabledSkills` / `enabledMcpServers` / `agentPackage` /
+`agentOptions` 安全约束 / `runtime` / `startup` 等），见
+[`specs/features/agenthub-sdk.md`](../../specs/features/agenthub-sdk.md)
+的 "Managed-Agent Configuration"、"Workload API Contract"、"Revision Publish Contract" 章节。
+
+> **`agentOptions` 安全约束（高频踩坑）**：`agentOptions` **只能收紧 / 限额**，不能放宽。
+> `allowedTools` 与平台基线**取交集**（只会更窄）、`disallowedTools` 叠加平台黑名单且
+> **不能移除**平台守卫工具；`permissionMode` / `env` / `mcpServers` / `hooks` /
+> `plugins` / 原始 `sdkOptions` 等可能越权或逃逸 sandbox 的字段**一律不开放**（见 issue #840）。
+> 字段全表见上述 spec。
 
 `apply*` 方法里的 `manifest` 可以是 manifest 对象、`{ yaml }` 或 `{ json }`。
 
-### Agent 配置项总览
-
-managed_agent 的配置可写在两处，语义不同（**Version 快照优先级高于 Workload 默认**）：
-
-| 写在哪 | 字段入口 | 性质 |
-| --- | --- | --- |
-| `agents.create({ defaults })` | Workload 级默认 | 可变；作为新版本的起始模板，也是没快照时的兜底。 |
-| `agents.publishVersion({ managedAgentProfileSnapshot })` | Version 级不可变快照 | **session 运行时实际解析的值**；按版本钉死，隔离后续对 defaults 的修改。 |
-
-> 想要「版本钉死 + 隔离」的真实 agent 配置就写在 `managedAgentProfileSnapshot`；
-> `defaults` 当作 workload 级默认模板。两层字段基本一致（下表）。
-
-#### 画像字段（`defaults` 与 `managedAgentProfileSnapshot` 通用）
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `model` | `string` | 模型 id 或别名（见 [模型](#模型)）。 |
-| `systemPrompt` | `string` | 系统提示词，≤ 32768 字符。 |
-| `enabledSkills` | `EnabledSkillEntry[]` | 启用的 Rush skills。 |
-| `enabledMcpServers` | `EnabledMcpEntry[]` | 启用的 MCP server，每个可带 `toolFilter` / `extraConfigValues` / `disabled`。 |
-| `configValues` | `Record<string, string>` | 配置 / env 键值（有保留 key 与长度限制）。 |
-| `agentOptions` | `AgentOptions` | 高级运行选项，见下表。 |
-
-`defaults` 额外接受 `workerContract`（workload 级默认 worker 契约）；
-`managedAgentProfileSnapshot` 仅当 `workerContract.kind === "managed_agent"` 时允许。
-
-#### `agentOptions`（仅 managed_agent；**只能收紧 / 限额**）
-
-| 字段 | 约束 | 说明 |
-| --- | --- | --- |
-| `maxTurns` | 整数 1–200 | 最大 agentic 轮次。 |
-| `maxThinkingTokens` | 整数 1–60000 | 扩展思考 token 预算。 |
-| `maxBudgetUsd` | 0–50 | 单次运行花费上限（USD）。 |
-| `effort` | `"low"｜"medium"｜"high"｜"max"` | 推理强度。 |
-| `allowedTools` | `string[]`，≤ 64 | 工具白名单；与平台基线**取交集**（只会更窄）。 |
-| `disallowedTools` | `string[]`，≤ 64 | 工具黑名单；叠加平台黑名单，**不能移除**平台守卫工具。支持有界 arg matcher（如 `Bash(rm:*)`），禁止全通配 `(*)` / `(*:*)`。 |
-
-出于跨租户安全，`agentOptions` 故意**不开放** `permissionMode` / `env` / `mcpServers` / `systemPrompt`
-替换 / `hooks` / `plugins` / 原始 `sdkOptions` 等可能越权或逃逸 sandbox 的字段（见 issue #840）。
-
-#### Version 级其他字段（`publishVersion` / `publishRevision`，非画像）
-
-| 字段 | 说明 |
-| --- | --- |
-| `workerContract` | `{ kind: "managed_agent" ｜ "self_managed"; name?; version? }`，必填。 |
-| `setDefault` | 是否设为默认版本，默认 `true`。 |
-| `startup` | 启动门禁 `{ requiredGates?: string[]; optionalGates?: string[] }`。 |
-| `runtime` | 运行时环境 `{ profileRef?; environment?; overrides? }`，省略则继承 project 默认。 |
-| `configValues` | version 级配置 / env 键值。 |
-
-#### Workload 级其他字段（`create`）
-
-| 字段 | 说明 |
-| --- | --- |
-| `ui` | Default-UI 展示提示（`WorkloadManifestUiHint`）。 |
-| `defaults.workerContract` | workload 级默认 worker 契约。 |
-
 ### `agenthub.sessions`
 
 | 方法 | 说明 |
 | --- | --- |
-| `create({ projectId, workloadId, revisionId?, configValues?, metadata?, idempotencyKey?, resources?, ... })` | 启动 Session。省略 `revisionId` 时使用 Workload 默认 Revision。`resources` 注入 Model A 只读输入文件（见下）。返回 `{ sessionId, status }`。 |
-| `get(sessionId)` | 读取 Session 快照（`{ session: { id, status, ... } }`）。 |
+| `create({ projectId, agentId, versionId?, configValues?, metadata?, idempotencyKey?, resources?, ... })` | 启动 Session。省略 `versionId` 时使用 Agent 默认 Version。`agentId`/`versionId` 也可写成 `workloadId`/`revisionId`（互斥）。`resources` 注入 Model A 只读输入文件（见下）。返回 `{ sessionId, status }`。 |
+| `get(sessionId)` | 读取 Session 快照（`{ session: { id, status, ... } }`，字段为服务端原样返回）。 |
 | `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | 轮询到 `status === "ready"`；遇到 `failed` 或超时会抛错。 |
+| `releaseSandbox(sessionId)` | 释放 Session 当前 sandbox（保留 session，下一轮 turn 自动 revive 到新 sandbox）。需 `runs:create`。返回 `{ released, sandboxId, sandboxDestroyed, destroyError? }`；`sandboxDestroyed:false` 不代表失败（watcher 会兜底销毁）。 |
 
 Session `status` 取值为 `created`、`provisioning`、`starting`、`ready`、`failed`。
 
@@ -303,7 +200,7 @@ const { url, ...meta } = up;
 
 const { sessionId } = await agenthub.sessions.create({
   projectId,
-  workloadId,
+  agentId,
   resources: {
     version: "v1",
     files: [{ ...meta, mountPath: "docs/spec.md" }], // mountPath 可省略 → 用文件名
@@ -315,20 +212,45 @@ const { sessionId } = await agenthub.sessions.create({
 约束：每 Session ≤ 20 个文件；`mountPath` 必须是 `.session/inputs/` 下的相对子路径
 （拒绝绝对路径与 `..`）；只读。
 
+## Client 配置
+
+`new PilotPlatformClient(config)`
+
+| 选项 | 必填 | 说明 |
+| --- | --- | --- |
+| `controlPlaneUrl` | 是¹ | Control Plane 源地址。相对路径会拼到它下面；跨 origin 路径会在发 token 前被拒绝。 |
+| `token` | 是¹ | Platform-api token。每个请求都会作为 `Authorization: Bearer <token>` 发送。 |
+| `fetch` | 否 | 自定义 `fetch` 实现，默认使用全局 `fetch`。 |
+| `signal` | 否 | 应用于每个请求的默认 `AbortSignal`。 |
+| `defaultHeaders` | 否 | 合并到每个请求的额外 header。 |
+| `userAgent` | 否 | 覆盖默认 `@kanyun-ai-infra/agenthub/<version>` UA。 |
+| `pilotApiVersion` | 否 | 固定 `x-pilot-api-version` header，默认使用 v2 wire version。 |
+
+¹ `controlPlaneUrl` 会依次回退到 `PILOT_CONTROL_PLANE_URL`、
+`KANYUN_PILOT_CONTROL_PLANE_URL`；`token` 会回退到 `PILOT_TOKEN`。任意一项缺失时，
+SDK 会在发送请求前抛出类型化错误。
+
+### 获取 token
+
+登录 **管理门户** <https://agenthub.zhenguanyu.com> 并签发 **platform-api token**。
+该 token 的作用域是 Control Plane API（`agenthub-plane.zhenguanyu.com`）；可以存为
+`PILOT_TOKEN`，也可以显式传给 `token`。Token 是 Bearer 凭据，请不要提交到代码仓库；
+泄露后需要在门户里轮换。
+
 ## Runtime template
 
-managed-agent Revision 运行在一个 **runtime template**（已注册的 runtime source）上。
+managed-agent Version 运行在一个 **runtime template**（已注册的 runtime source）上。
 Control Plane 按以下顺序解析：
 
-1. revision `runtime.profileRef`（structured）/ `spec.runtime.profileRef`
-2. revision `spec.runtimeTemplateRef`（manifest）
-3. workload defaults `spec.defaults.runtimeTemplateRef`（manifest）
+1. version `runtime.profileRef`（structured）/ `spec.runtime.profileRef`
+2. version `spec.runtimeTemplateRef`（manifest）
+3. agent defaults `spec.defaults.runtimeTemplateRef`（manifest）
 4. project `defaultRuntimeTemplateRefName`
 
 如果都解析不到，返回 `PROJECT_DEFAULT_RUNTIME_MISSING`。如果指定模板在当前 Project
 或 platform-shared templates 中不存在，返回 `RUNTIME_TEMPLATE_NOT_FOUND`。
 
-主路径建议在创建 Project 时设置默认模板，这样调用方发布 Revision 时不需要手选：
+主路径建议在创建 Project 时设置默认模板，这样发布 Version 时不需要手选：
 
 ```ts
 await agenthub.projects.create({
@@ -338,12 +260,11 @@ await agenthub.projects.create({
 });
 ```
 
-否则需要在每个 Revision 上显式指定：
-`runtime: { profileRef: { name: "..." } }`。
+否则需要在每个 Version 上显式指定：`runtime: { profileRef: { name: "..." } }`。
 
 **Platform-shared templates。** Platform Default project 拥有的模板（例如
 `pilot-v2-pod-agent`）是共享基础设施：当调用方 Project 内找不到同名模板时，解析会回退到
-Platform Default，因此任意 Project 的 Revision 都可以按名称引用它们。`echo-bot`
+Platform Default，因此任意 Project 的 Version 都可以按名称引用它们。`echo-bot`
 是内置 echo-only 模板，适合 smoke test；它**不会**运行 LLM。
 
 ## 模型
@@ -359,9 +280,9 @@ Platform Default，因此任意 Project 的 Revision 都可以按名称引用它
 
 ## Dry runs
 
-`workloads.create`、`publishRevision` 和 `apply*` 方法都接受 `{ dryRun: true }`。
+`agents.create`、`publishVersion` 和 `apply*` 方法都接受 `{ dryRun: true }`。
 dry run 会校验并解析请求，但不持久化；返回 `mode: "dry_run"` 和
-`would_create` / `would_update` 状态；Revision 已存在且内容一致时可能返回
+`would_create` / `would_update` 状态；Version 已存在且内容一致时可能返回
 `existing`。正式发布前可以用它确认 runtime template 能正确解析。
 
 ## 错误