@kanyun-ai-infra/agenthub 1.0.0 → 1.1.0

package/README.md

@@ -15,6 +15,17 @@
 两者使用不同的 token audience：Portal 登录态 token 不能调用 Control Plane，反过来也一样。
 请始终把管理门户签发的 platform-api token 和 `agenthub-plane` Control Plane URL 配套使用。
 
+## 如果你是 agent
+
+不需要读完这份 README——已经发布了对应的 skill，装完直接照着写代码即可：
+
+```bash
+npx rush-ai skill install @kanyun/agenthub-sdk
+```
+
+skill 内容和这份 README 保持同步；改了 public API 时必须同步改 skill。公开方法与示例见
+[AgentHub API 与 SDK 文档](https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods)。剩下的正文是给人类读者的完整参考。
+
 ## 安装
 
 ```bash
@@ -24,9 +35,9 @@ pnpm add @kanyun-ai-infra/agenthub
 
 需要 Node 18+，因为 SDK 使用全局 `fetch`。
 
-如果调用方是 Java、Python、Go 或 Shell，请优先看 REST 参考及其多语言快速开始：
-[`docs/user-guide/agenthub-rest-api.md`](../../docs/user-guide/agenthub-rest-api.md)
-（curl / Python / Java 示例见 [§9 多语言快速开始](../../docs/user-guide/agenthub-rest-api.md#9-多语言快速开始)）。
+如果调用方是 Java、Python 或 Shell（curl），请优先看
+<https://agenthub.zhenguanyu.com/docs/api-and-sdk/multi-language-examples>（Python / Java）
+或 <https://agenthub.zhenguanyu.com/docs/api-and-sdk#rest-flow>（curl）。
 
 ## 快速开始
 
@@ -80,15 +91,22 @@ const version = await agenthub.agents.publishVersion({
   },
 });
 
-// 4. Session：基于默认 Version（或指定 Version）分配一次运行时。
+// 4. Session：通过 stage 槽位分配一次运行时。setDefault:true 首次发布已自动
+//    创建 test 槽位，直接用即可（stage 与 versionId 互斥，见下方「完整参考」）。
 const session = await agenthub.sessions.create({
   projectId: project.id,
-  agentId: version.agentId, // 用默认 Version；指定版本传 versionId
+  agentId: version.agentId,
+  stage: "test",
 });
 
 const ready = await agenthub.sessions.wait(session.sessionId); // status === "ready" 时返回
 ```
 
+> Environment（k8s 配置底座：资源规格 / envVars / TTL）上面还没有登场——test 槽位
+> 目前落在裸 revision 快照上，本地联调、smoke test 够用。真实上线到 production，
+> 要额外给槽位绑一个 Environment，才有资源规格定制、canary 灰度、drift 检测、
+> 一键回滚这些能力：完整走一遍见下方「完整参考」里的发布闭环六幕示例。
+
 ## 核心模型
 
 ```text
@@ -102,428 +120,37 @@ Project  →  Agent  →  Version  →  Session
   标记 project/agent 默认版本。
 - **Session**：基于某个 Version 发起的一次 startup/runtime allocation。
 
-上面这条链路是"定义"层面的（发布了什么）；真正"跑在哪"是另一个独立维度——
-**Environment**（k8s 配置底座）+ **Stage 槽位**（`test`/`production`，把某个
-Version 部署到某个 Environment）。这两个概念、以及一次完整的"发布 → 部署 →
-诊断 → 回滚"闭环，见 [发布闭环](#发布闭环)。
+上面这条链路是"定义"层面的（发布了什么）；Session 已经通过 **Stage** 槽位
+（`test`/`production`，指向当前生效的 Version，可选绑定 **Environment**）
+跑起来了——但这个槽位目前没绑 Environment（k8s 配置底座：资源规格 / envVars /
+TTL），落的是裸 revision 快照。给槽位绑定 Environment、晋级到 production、
+canary 灰度、drift 检测、一键回滚——完整闭环见下方「完整参考」的发布闭环六幕示例。
 
 Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一个 Project
-内解析到 Agent 和 runtime source；唯一例外是下文的 platform-shared templates。
+内解析到 Agent 和 runtime source；唯一例外是下方「完整参考」提到的 platform-shared templates。
 
 > 本文一律用主词汇 **agent / version**；它们是底层 wire 名 `workload` / `revision`
-> 的别名，SDK 两套都接受，细节见 [术语别名](#术语别名agent--version)。
-
-### 术语别名（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` | 返回对象**同时带**两套字段（别名 = 规范值）。 |
-
-规则：
-
-- **互斥**：一对里只能传一个，规范名和别名同传会抛 `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 参考
-
-### `agenthub.projects`
-
-| 方法 | 说明 |
-| --- | --- |
-| `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 }`。 |
-| `getWorkbench(projectId)` | 工作台聚合（AgentHub lifecycle console 同款读模型）：`workloadCount` / `sessionStats` / `stageDrift` / `recentChanges`。 |
-| `getReleaseBoard(projectId)` | 发布板聚合：每个 Agent 一行,含 test/production 槽位摘要与 `drift`。 |
-
-### `agenthub.agents`（别名 `agenthub.workloads`）
-
-| 方法 | 说明 |
-| --- | --- |
-| `create(req, { dryRun? })` | 创建 Agent。返回 `{ mode, status, agentId?/workloadId?, workload }`。 |
-| `get({ projectId, agentSlug \| workloadSlug })` | 读回单个 Agent（含 `defaultRevisionId` 与内嵌 `defaultRevision`；发布过 `setDefault` Version 前为 `null`）。不存在返回 `404 WORKLOAD_NOT_FOUND`；`projectId` 超出 token scope 返回 `403 PROJECT_NOT_IN_TOKEN_SCOPE`。 |
-| `getVersion({ projectId, agentSlug \| workloadSlug, version })` | 读回单个 Version（别名 `getRevision`）。返回 `{ id, projectId, workloadId, workloadSlug, version, runtimeSnapshotHash, createdAt }`（SDK 额外附 `agentId` 镜像）。不存在返回 `404 WORKLOAD_NOT_FOUND / REVISION_NOT_FOUND`。 |
-| `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 }`。
-
-#### `agenthub.agents.stages` + `previewStage`
-
-Stage 槽位（`test` / `production`）——把一个 Version 部署到某个槽位，槽位把
-「version 指针」和「environment 绑定」当成两个独立维度组合在一起。概念全貌与
-完整走一遍的例子见 [发布闭环](#发布闭环)。
-
-| 方法 | 说明 |
-| --- | --- |
-| `stages.list(workloadId)` | 列出该 Agent 已部署的槽位；从未部署的 stage 直接不出现（无隐式创建）。 |
-| `stages.set(workloadId, stage, { revisionId, environmentId?, runtimeOverrides?, configValues?, expectedUpdatedAt? })` | 创建/更新槽位（upsert，部署动作）。 |
-| `stages.promote(workloadId, { environmentId?, expectedUpdatedAt?, sourceRevisionId?, expectedTestUpdatedAt? }?)` | 把 production 指针挪到 test 槽位当前指向的 revision（原子操作；只挪指针，production 自己的 overrides/config 不变）。 |
-| `previewStage({ agentId \| workloadId, versionId \| revisionId, runtimeOverrides?, configValues?, environmentId? })` | UI-5 解析预览：只读计算部署后会解析成什么，不写任何行。晋级 / 部署前的确认步骤。 |
-
-`set` / `promote` 的 `environmentId` 都是**三态**语义：
-
-- **省略**（`undefined`）—— 保留槽位当前绑定；槽位第一次创建时没有"现值"可保留，
-  于是落成 `environmentId: null`（未绑定）。
-- **`null`** —— 清除绑定（槽位回退到 revision 快照，不叠加任何 environment 字段组）。
-- **UUID** —— 绑定该 Environment（服务端校验：存在 / 同项目或 platform-shared /
-  未 archived），并钉住它当前的 tip 版本。
-
-⚠️ **`environmentId` "必须显式传，没有继承 revision 环境这回事"这条规则，只适用于
-`stages.set` / `stages.promote` 这两个显式调用——`publishVersion` / `publishRevision`
-本身没有 `environmentId` 这个入参，传不了。** `publishVersion({ setDefault: true })`
-首次发布时自动创建的那条 **test** 槽位（2026-07-13 起的新行为，`production` 不会
-被自动创建）同样落地成未绑定状态，但那是 upsert 时"省略"分支的结果，不是你对
-publishVersion 传了什么参数。给这条自动创建的 test 槽位补环境绑定，要另外显式调用
-`agenthub.agents.stages.set(workloadId, "test", { revisionId, environmentId })`。
-见下方 [发布闭环](#发布闭环) 的 ⚠️ 说明。
-
-### `agenthub.environments`
-
-Environment = agent 运行的 **k8s 配置底座**（provider / 资源规格 / envVars /
-TTL）——它本身不是"部署目标"；`test`/`production` 才是部署目标（stage 槽位，
-`agents.stages`），槽位钉住一对 `(environmentId, environmentVersion)`。
-
-| 方法 | 说明 |
-| --- | --- |
-| `list(projectId, { includeArchived? })` | 列出项目可见的 Environment（含 platform-shared）。 |
-| `get(id, projectId)` | 查询单个 Environment（含 config 全貌 + `referencedBy`——当前所有引用它的槽位）。 |
-| `create(projectId, { name, base, description?, config? })` | 创建（从 platform-shared 底座拷贝 provider 字段）。定义域操作，日常建议在管理门户完成；这里是给 CI/IaC 场景开的口子。 |
-| `update(id, projectId, { name?, description?, config?, repointReferences? })` | 编辑。`config` 面变更（`resources`/`envVars`/`defaultTtlSeconds`）冻结一个新版本，默认（`repointReferences` 省略或 `true`）批量把所有引用槽位拨到新版本；传 `false` 只建版本、槽位不动（配合 `repoint` 手动灰度）。返回 `{ environment, createdVersion, repointedSlotCount }`；改名/描述这类 metadata-only 写不产生新版本（`createdVersion: null`）。 |
-| `archive(id, projectId)` | 归档（终态，无法撤销）。存量引用继续解析；任何新引用一律拒绝。 |
-| `versions(id, projectId)` | 版本历史（每条自带完整 config 快照，不需要单独的详情调用）+ repoint 审计账（哪个槽位、何时、被谁从哪个版本拨到哪个版本）。 |
-| `repoint(id, projectId, { toVersion, slots?, expectedSlots? })` | 拨动槽位的版本指针——回滚=拨回旧版本，灰度=只拨 `slots` 里点的槽位。省略 `slots` = 项目内所有引用该 Environment 的槽位。槽位选择器接受 `agentId`（同 `workloadId`）。 |
+> 的别名，SDK 两套都接受，规范名与别名同传会抛 `ALIAS_CONFLICT`，细节见下方「完整参考」。
 
-`repoint` 同步执行——单事务内的有界原子操作（行锁 + CAS + 批量 UPDATE），不是
-长任务，调用直接拿到结果，不需要轮询。
+## 完整参考
 
-### `agenthub.sessions`
+下面这些内容日常写业务代码用不到，需要时查
+[AgentHub 文档站](https://agenthub.zhenguanyu.com/docs/api-and-sdk) 对应小节
+（这份 README 会随 npm 包分发到别的项目里，下面全部是可以直接点开的网址，不是仓库内相对路径）：
 
-| 方法 | 说明 |
+| 你想找 | 链接 |
 | --- | --- |
-| `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 会兜底销毁）。 |
-| `getDiagnosis(sessionId)` | 会话诊断聚合（AgentHub lifecycle console 同款读模型）：`session` / `failure` / `events` / `sandbox`，任一区块读取失败时该块为 `null` 且 `blockErrors` 带错误说明,不影响其它区块。 |
-
-Session `status` 取值为 `created`、`provisioning`、`starting`、`ready`、`failed`。
-
-### `agenthub.files`
-
-| 方法 | 说明 |
-| --- | --- |
-| `upload({ projectId, file, filename?, contentType? })` | 上传单个文件，返回 `{ ossUrl, url, filename, size, mediaType, mimeType }`。`file` 接受 `Blob` / `File` / `Uint8Array` / `ArrayBuffer`；非具名 `File` 时必须传 `filename`。 |
-
-文件落在 `pilot/attachments/<projectId>/`，与 Session 资源 scope 校验同一 keyspace —— 为某 Project
-上传的文件无法挂到另一个 Project 的 Session。`url` 是 ~1h 的 presigned GET（仅预览用）；
-要持久引用的是 `ossUrl`。
-
-#### Model A 只读输入文件（session resources）
-
-把文件作为 **Session 级只读输入**挂进 sandbox 的 `/workspace/.session/inputs/`（每次
-provision / revival 重新物化），用 `files.upload` + `sessions.create({ resources })`：
-
-```ts
-const up = await agenthub.files.upload({
-  projectId,
-  file: new Blob([await fs.promises.readFile("spec.md")]),
-  filename: "spec.md",
-});
-
-// `up` 是 SessionFileResource 的超集，只多一个预览用的 `url`；解构掉它，
-// 剩下的 `meta`（ossUrl/filename/size/mediaType/mimeType）正是一个资源条目。
-const { url, ...meta } = up;
-
-const { sessionId } = await agenthub.sessions.create({
-  projectId,
-  agentId,
-  resources: {
-    version: "v1",
-    files: [{ ...meta, mountPath: "docs/spec.md" }], // mountPath 可省略 → 用文件名
-  },
-});
-// agent 在 /workspace/.session/inputs/docs/spec.md 只读看到该文件
-```
-
-约束：每 Session ≤ 20 个文件；`mountPath` 必须是 `.session/inputs/` 下的相对子路径
-（拒绝绝对路径与 `..`）；只读。
-
-## 发布闭环
-
-**正名**：Environment 对应 k8s 的「配置」——agent 跑在什么样的容器里（provider /
-资源规格 / envVars / TTL），是**底座**，不是部署目标本身。`test` 和
-`production` 才是部署目标，叫 **stage**（部署槽位）。槽位
-= `{ version 指针, environment 绑定 }` 两个互相独立的维度：一个槽位可以只钉了
-version、没绑 environment（回退到 revision 快照），也可以两者都钉。**"分别创建
-测试环境和线上环境"**这个诉求，落到 API 上不是造两个 Environment，而是给
-`test` 和 `production` 两个槽位各自 `stages.set` 一次——两个槽位可以指向
-**同一个** Environment（同配置跑两份），也可以指向**不同**的 Environment
-（比如 production 用更大的资源规格）。
-
-下面完整走一遍"发布 → 部署 → 预览 → 晋级 → canary 灰度出真实 drift → repoint
-回滚"，全程用 agent 词汇；每段代码都是照实测过的 j8 SDK 旅程
-（`tests/e2e/j8-agenthub-sdk-journey.spec.ts`）抄的真实调用序列，不是省略号带过
-的伪代码——复制到 strict TS 项目里应该能直接编译。
-
-### 第一幕：创建 Agent，发布 v1（setDefault:true 自动落地 test）
-
-```ts
-const project = await agenthub.projects.create({ slug: "acme", displayName: "Acme" });
-await agenthub.agents.create({
-  projectId: project.id,
-  slug: "support-bot",
-  displayName: "Support Bot",
-  kind: "managed_agent",
-});
-
-// setDefault:true —— 首发用它是安全的：2026-07-13 起的新行为只会自动创建
-// **test** 槽位（environmentId 仍是 null，未绑定）+ 翻转 defaultRevisionId，
-// 不会误建一个"看起来已经上线其实没配置"的 production（见文末 ⚠️）。存量
-// 在此之前已经发布过、已经有 production 槽位的老 workload 走的是另一条
-// 分支，不受这次改动影响（同样见文末 ⚠️ 的存量说明）。
-const v1 = await agenthub.agents.publishVersion({
-  projectId: project.id,
-  agentSlug: "support-bot",
-  version: "v1",
-  workerContract: { kind: "managed_agent" },
-  setDefault: true,
-});
-// `revisionId` 在 RevisionApplyResult 里是 optional（dry-run / manifest 面共用
-// 同一个类型）；status:"created" 时必然有值，但 strict TS 下仍需要先断言/守卫
-// 才能当必填参数传下去——不要在类型上偷懒直接 `v1.revisionId!` 到处传。
-if (!v1.revisionId) throw new Error("publishVersion did not return a revisionId");
-const revisionId = v1.revisionId;
-```
-
-### 第二幕：给已存在的 test 槽位补上环境绑定
-
-```ts
-const env = await agenthub.environments.create(project.id, {
-  name: "acme-standard",
-  base: { platformTemplateName: "pilot-v2-pod-agent" },
-});
-
-// test 槽位在第一幕已经由 setDefault:true 自动创建（environmentId 是 null，
-// 未绑定）——这里不是"首次部署"，是确认/补上环境绑定。set 是 upsert，同一个
-// revisionId 再传一次不会产生新状态，只补 environmentId 这一个字段。
-// production 槽位此刻还不存在，留到第四幕用 promote 显式创建它。
-await agenthub.agents.stages.set(v1.workloadId, "test", {
-  revisionId,
-  environmentId: env.id,
-});
-```
-
-### 第三幕：晋级前先 preview
-
-```ts
-const preview = await agenthub.agents.previewStage({
-  agentId: v1.workloadId,
-  versionId: revisionId,
-  environmentId: env.id,
-});
-// 把 preview.runtimeSnapshot / preview.environment 展示给操作者确认，
-// 无误后再提交第四幕的晋级请求。
-```
-
-### 第四幕：晋级 production（第一次创建它）
-
-```ts
-await agenthub.agents.stages.promote(v1.workloadId, {
-  // TOCTOU 防护：确保确认弹窗打开期间 test 槽位没有被别人改过。
-  sourceRevisionId: revisionId,
-  // production 此刻并不存在（新行为下首发只写 test）——promote 把它的指针
-  // 挪到 test 当前指向的 revision，但 environmentId 是独立三态、不会从
-  // test 继承绑定：首次创建 production 必须显式传 environmentId，否则会
-  // 带着 environmentId:null 落地（同一个坑，见文末 ⚠️）。
-  environmentId: env.id,
-});
-```
-
-此刻 production 才第一次出现，且与 test 完全同步（同 revision、同
-environment、同 environment 版本）——`getReleaseBoard` 这一行的 `drift` 是
-`false`，这是正常稳态,不是 bug。
-
-### 第五幕：环境升级到 v2，canary 灰度到 test（这才是真实 drift 的由来）
-
-```ts
-// defaultTtlSeconds 是"永不物化"字段（不需要 Kanyun template gateway）——
-// config 面变更冻结出 v2；repointReferences:false 让两个槽位暂时都留在 v1，
-// 不要一步就把所有槽位都拨过去。
-const updated = await agenthub.environments.update(env.id, project.id, {
-  config: { defaultTtlSeconds: 7200 },
-  repointReferences: false,
-});
-// `createdVersion` is `number | null` — metadata-only writes create no
-// version. A config-face write always does, but the type doesn't know that;
-// guard before treating it as a required `toVersion`.
-if (updated.createdVersion === null) throw new Error("update() did not create a new version");
-const canaryVersion = updated.createdVersion;
-
-// canary：只把 test 槽位拨到 v2，production 留在 v1。
-const canary = await agenthub.environments.repoint(env.id, project.id, {
-  toVersion: canaryVersion,
-  slots: [{ agentId: v1.workloadId, stage: "test" }],
-});
-
-// 这才是 drift 真正出现的时刻——不是假设，是两次 get 读回来的真实状态。
-const afterCanary = await agenthub.environments.get(env.id, project.id);
-const testRef = afterCanary.referencedBy.find((ref) => ref.stage === "test");
-const productionRef = afterCanary.referencedBy.find((ref) => ref.stage === "production");
-// testRef.environmentVersion === 2, productionRef.environmentVersion === 1
-```
-
-### 第六幕：canary 效果不理想，回滚（真实 409 重试，不是省略号带过）
-
-```ts
-import { PilotPlatformApiError } from "@kanyun-ai-infra/agenthub";
-
-async function rollbackTestSlot(): Promise<void> {
-  // 重新拉一次，把 test 槽位的当前状态当成"我现在看到的影响面"传给
-  // expectedSlots——不要复用第五幕观察时的旧快照。
-  const environment = await agenthub.environments.get(env.id, project.id);
-  const testRef = environment.referencedBy.find((ref) => ref.stage === "test");
-  if (!testRef) return; // 槽位已经不再引用这个 environment，没什么可回滚的。
-
-  try {
-    await agenthub.environments.repoint(env.id, project.id, {
-      toVersion: 1, // 回到 canary 之前的版本
-      slots: [{ workloadId: testRef.workloadId, stage: "test" }],
-      expectedSlots: [{ workloadId: testRef.workloadId, stage: "test" }],
-    });
-  } catch (err) {
-    if (err instanceof PilotPlatformApiError && err.code === "ENVIRONMENT_REPOINT_IMPACT_SET_CHANGED") {
-      // 有人在你上面这次 get 之后又动过这个槽位——重新拉最新状态再试，
-      // 不能对着同一份 expectedSlots 硬重试。
-      return rollbackTestSlot();
-    }
-    throw err;
-  }
-}
-
-await rollbackTestSlot();
-// production 全程没有被 canary 影响过——回滚只是撤销 test 侧的灰度尝试。
-```
-
----
-
-⚠️ **`publishVersion({ setDefault: true })` 首次发布只会自动写 `test` 槽位
-（`environmentId` 仍是 `null`，未绑定）+ 翻转 `defaultRevisionId`；`production`
-永远不会被自动创建，必须显式 `stages.set` / `stages.promote`。** 这是
-2026-07-13 拍板落地的行为（spec `pilot-v2-agent-stage-environment.md` §5.1
-STG-M5~M8；读代码 + 实测确认，不是猜的）：`applySetDefault`
-（`packages/control-plane/src/workload/workload-manifest-apply.ts`）判定
-"该 workload 此刻一个 stage 槽位都没有"（首发）时，只 upsert `test` 槽位
-（`environmentId: undefined` 落在还不存在的槽位上，等价于插入 `null`——没有
-"现值"可继承）+ 调用新写端点 `setWorkloadDefaultRevisionPointer` 挪
-`default_revision_id`；`production` 完全不碰。**非首发**（该 workload 已经
-有 ≥1 个槽位，不管是 `test` 还是 `production`）的 `setDefault` 写只挪
-`default_revision_id` 指针，同样不碰任何槽位——上面六幕如果给第二次发布也传
-`setDefault: true`，也只是指针翻转，不会自动同步任何槽位。
-
-> **存量兼容**：2026-07-13 之前已经首发过、因而已经有 `production` 槽位的老
-> workload 判定为"非首发"，行为不受这次改动影响、不做迁移——`production`
-> 槽位继续存在，只是后续 `setDefault` 写不会再挪动它的 revision 指针（这本身
-> 是一处行为变化：改动前"非首发"的 `setDefault` 也会挪 `production` 指针）。
-
-## 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 Version 运行在一个 **runtime template**（已注册的 runtime source）上。
-Control Plane 按以下顺序解析：
-
-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 时设置默认模板，这样发布 Version 时不需要手选：
-
-```ts
-await agenthub.projects.create({
-  slug: "acme",
-  displayName: "Acme",
-  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
-});
-```
-
-否则需要在每个 Version 上显式指定：`runtime: { profileRef: { name: "..." } }`。
-
-**Platform-shared templates。** Platform Default project 拥有的模板（例如
-`pilot-v2-pod-agent`）是共享基础设施：当调用方 Project 内找不到同名模板时，解析会回退到
-Platform Default，因此任意 Project 的 Version 都可以按名称引用它们。`echo-bot`
-是内置 echo-only 模板，适合 smoke test；它**不会**运行 LLM。
-
-## 模型
-
-`model` 接受完整 id（`claude-opus-4-7`、`claude-sonnet-4-6`、`claude-haiku-4-5`），
-也接受会映射到完整 id 的历史别名：
-
-| Alias | 解析为 |
-| --- | --- |
-| `opus` | `claude-opus-4-7` |
-| `sonnet` | `claude-sonnet-4-6` |
-| `haiku` | `claude-haiku-4-5` |
-
-## Dry runs
-
-`agents.create`、`publishVersion` 和 `apply*` 方法都接受 `{ dryRun: true }`。
-dry run 会校验并解析请求，但不持久化；返回 `mode: "dry_run"` 和
-`would_create` / `would_update` 状态；Version 已存在且内容一致时可能返回
-`existing`。正式发布前可以用它确认 runtime template 能正确解析。
+| 资源方法速查（projects / agents / stages / environments / sessions / files / profiles） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#sdk-methods> |
+| "发布 → 部署 → 晋级 → 灰度 → 回滚"完整六幕示例 | <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> |
+| Model 别名、Dry runs | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#model-dry-run> |
+| 调用方是 Java / Python（最后手段，官方只推荐这份 TS SDK） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk/multi-language-examples> |
+| 调用方是 Shell（curl） | <https://agenthub.zhenguanyu.com/docs/api-and-sdk#rest-flow> |
 
 ## 错误
 
-所有 API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`：
+API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`——但请求被 `AbortSignal` 取消是例外，那条路径抛的是原生 `AbortError`，没有这些字段，需要单独判断：
 
 | Class | HTTP |
 | --- | --- |