npm - @kanyun-ai-infra/agenthub - Versions diffs - 0.1.1 → 0.2.0 - Mend

@kanyun-ai-infra/agenthub 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -1,51 +1,54 @@
 # @kanyun-ai-infra/agenthub
-Typed TypeScript client for the **agenthub Control Plane API**.
+用于 **agenthub Control Plane API** 的类型化 TypeScript 客户端。
-It talks directly to the agenthub Control Plane and is meant for backend
-services, CI, and tooling that drive the
-`project → workload → revision → session` lifecycle programmatically.
+它直接调用 agenthub Control Plane，适合后端服务、CI 和工具以编程方式驱动
+`project -> workload -> revision -> session` 生命周期。
-Two surfaces are involved:
+接入时会遇到两个入口：
-| Surface | URL | Audience |
+| 入口 | URL | 用途 |
 | --- | --- | --- |
-| **Control Plane API** | `https://agenthub-plane.zhenguanyu.com` | This SDK / your services — pass it as `controlPlaneUrl`. |
-| **Admin portal** | `https://agenthub.zhenguanyu.com` | Humans who publish and manage agents — and where you **issue an API token**. |
+| **Control Plane API** | `https://agenthub-plane.zhenguanyu.com` | SDK / 你的服务调用。作为 `controlPlaneUrl` 传入。 |
+| **管理门户** | `https://agenthub.zhenguanyu.com` | 人工发布和管理 agent，并在这里**签发 API token**。 |
-The two use different token audiences: a portal session token will **not** work
-against the Control Plane, and vice versa. Always pair the platform-api token
-issued from the portal with the `agenthub-plane` Control Plane URL.
+两者使用不同的 token audience：Portal 登录态 token 不能调用 Control Plane，反过来也一样。
+请始终把管理门户签发的 platform-api token 和 `agenthub-plane` Control Plane URL 配套使用。
-## Install
+## 安装
 ```bash
 pnpm add @kanyun-ai-infra/agenthub
-# or: npm i @kanyun-ai-infra/agenthub
+# 或：npm i @kanyun-ai-infra/agenthub
 ```
-Requires Node 18+ (uses the global `fetch`).
+需要 Node 18+，因为 SDK 使用全局 `fetch`。
-## Quickstart
+如果调用方是 Java、Python、Go 或 Shell，请优先看 raw HTTP 指南和 REST 参考：
+[`docs/user-guide/agenthub-http-quickstart.md`](../../docs/user-guide/agenthub-http-quickstart.md)，
+[`docs/user-guide/agenthub-rest-api.md`](../../docs/user-guide/agenthub-rest-api.md)。
+## 快速开始
 ```ts
 import { PilotPlatformClient } from "@kanyun-ai-infra/agenthub";
 const agenthub = new PilotPlatformClient({
   controlPlaneUrl: "https://agenthub-plane.zhenguanyu.com",
-  token: process.env.PILOT_TOKEN, // platform-api token from the admin portal
+  token: process.env.PILOT_TOKEN, // 管理门户签发的 platform-api token
 });
-// 1. Project — the tenant/root grouping. The default runtime template lets
-//    callers publish revisions without picking one each time (see below).
+// 1. Project：租户 / 根分组。默认 runtime template 让调用方发布
+//    Revision 时不必每次手选模板。
 const project = await agenthub.projects.create({
   slug: "acme",
   displayName: "Acme",
   defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
 });
-// 2. Workload — a runnable agent/app in the project
-await agenthub.workloads.create({
+// 2. Agent：Project 下一个可运行的 agent/app
+//    （`agents` 是 `workloads` 的别名，下文「术语别名」有说明）
+await agenthub.agents.create({
   projectId: project.id,
   slug: "support-bot",
   displayName: "Support Bot",
@@ -56,11 +59,12 @@ await agenthub.workloads.create({
   },
 });
-// 3. Revision — an immutable published version. Runtime source is inherited
-//    from the project default; override per revision with `runtime.profileRef`.
-const revision = await agenthub.workloads.publishRevision({
+// 3. Version：Agent 的不可变发布版本（`publishVersion` 是 `publishRevision`
+//    的别名）。Runtime source 默认继承 Project default；要按版本覆盖传
+//    `runtime.profileRef`。
+const version = await agenthub.agents.publishVersion({
   projectId: project.id,
-  workloadSlug: "support-bot",
+  agentSlug: "support-bot",
   version: "v1",
   workerContract: { kind: "managed_agent" },
   setDefault: true,
@@ -70,79 +74,103 @@ const revision = await agenthub.workloads.publishRevision({
   },
 });
-// 4. Session — a runtime allocation against the default (or a specific) revision
+// 4. Session：基于默认 Version 或指定 Version 分配一次运行时
+//    （Session 接口仍用 `workloadId` 字段 —— 核心模型保持 workload 命名）
 const session = await agenthub.sessions.create({
   projectId: project.id,
-  workloadId: revision.workloadId,
+  workloadId: version.workloadId,
 });
-const ready = await agenthub.sessions.wait(session.sessionId); // resolves when status === "ready"
+const ready = await agenthub.sessions.wait(session.sessionId); // status === "ready" 时返回
 ```
-## Client configuration
+## Client 配置
 `new PilotPlatformClient(config)`
-| Option | Required | Description |
+| 选项 | 必填 | 说明 |
 | --- | --- | --- |
-| `controlPlaneUrl` | yes¹ | Control Plane origin. Relative request paths are composed under it; cross-origin paths are rejected before the token is sent. |
-| `token` | yes¹ | Platform-api token. Sent as `Authorization: Bearer <token>` on every request. |
-| `fetch` | no | Custom `fetch` implementation (defaults to the global). |
-| `signal` | no | Default `AbortSignal` applied to every request. |
-| `defaultHeaders` | no | Extra headers merged into every request. |
-| `userAgent` | no | Overrides the default `@kanyun-ai-infra/agenthub/<version>` UA. |
-| `pilotApiVersion` | no | Pins the `x-pilot-api-version` header (defaults to the v2 wire version). |
+| `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` falls back to `PILOT_CONTROL_PLANE_URL` then
-`KANYUN_PILOT_CONTROL_PLANE_URL`; `token` falls back to `PILOT_TOKEN`. Missing
-either produces a typed SDK error before any request is sent.
+¹ `controlPlaneUrl` 会依次回退到 `PILOT_CONTROL_PLANE_URL`、
+`KANYUN_PILOT_CONTROL_PLANE_URL`；`token` 会回退到 `PILOT_TOKEN`。任意一项缺失时，
+SDK 会在发送请求前抛出类型化错误。
-### Getting a token
+### 获取 token
-Sign in to the **admin portal** at <https://agenthub.zhenguanyu.com> and issue a
-**platform-api token**. That token is scoped to the Control Plane API
-(`agenthub-plane.zhenguanyu.com`); store it as `PILOT_TOKEN` (or pass it as
-`token`). Tokens are bearer credentials — keep them out of source control and
-rotate from the portal if leaked.
+登录 **管理门户** <https://agenthub.zhenguanyu.com> 并签发 **platform-api token**。
+该 token 的作用域是 Control Plane API（`agenthub-plane.zhenguanyu.com`）；可以存为
+`PILOT_TOKEN`，也可以显式传给 `token`。Token 是 Bearer 凭据，请不要提交到代码仓库；
+泄露后需要在门户里轮换。
-## Core model
+## 核心模型
 ```text
-Project  →  Workload  →  Revision  →  Session
+Project  ->  Workload  ->  Revision  ->  Session
 ```
-- **Project** — tenant/root grouping; owns workloads and runtime templates.
-- **Workload** — a logical runnable app. `kind` is `"managed_agent"` (platform
-  runs the agent loop from `model` + `systemPrompt`) or `"self_managed"` (you
-  ship the worker).
-- **Revision** — an immutable published version of a workload, bound to one
-  runtime source. Mark one as the project/workload default with `setDefault`.
-- **Session** — a startup/runtime allocation against a revision.
+- **Project**：租户 / 根分组，拥有 workloads 和 runtime templates。
+- **Workload**：一个逻辑可运行应用。`kind` 是 `"managed_agent"`（平台基于
+  `model` + `systemPrompt` 运行 agent loop）或 `"self_managed"`（你自己提供 worker）。
+- **Revision**：Workload 的不可变发布版本，绑定一个 runtime source。用 `setDefault`
+  标记 project/workload 默认版本。
+- **Session**：基于某个 Revision 发起的一次 startup/runtime allocation。
+Workloads 和 runtime templates 都是 **project-scoped**。Revision 必须在同一个 Project
+内解析到 Workload 和 runtime source；唯一例外是下文的 platform-shared templates。
+### 术语别名（agent / version）
+为降低理解成本，SDK 为核心概念提供了一组**别名**——语义完全一致，只是更口语化：
+| 规范名（核心模型） | 友好别名 | 说明 |
+| --- | --- | --- |
+| `agenthub.workloads` | `agenthub.agents` | **同一个资源实例**，方法完全一致。 |
+| `workloads.publishRevision({ workloadSlug })` | `agents.publishVersion({ agentSlug })` | 同一个调用；友好版用 `agentSlug`，内部映射回 `workloadSlug` 后发出，wire body 完全一致。 |
+| 概念 “Workload” / “Revision” | “Agent” / “Version” | 仅命名差异。 |
+`agentSlug` 仅在 `publishVersion` 上；`publishRevision` 仍用 `workloadSlug`。
+`applyRevisionManifest` 两个拼写都接受（同时给出时 `workloadSlug` 优先）。
+别名是**附加糖**：`workloads` / `publishRevision` / `workloadSlug` 一直保留，行为不变；
+返回结果的字段名（`workloadId` / `revisionId`）以及 `sessions.create({ workloadId })`
+仍沿用核心模型命名。挑读起来顺的那套写即可。
-Workloads and runtime templates are **project-scoped**. A revision must resolve
-its workload and runtime source inside the same project (the one exception is
-platform-shared templates, below).
+```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" } });
+```
-## API reference
+## API 参考
 ### `agenthub.projects`
-| Method | Description |
+| 方法 | 说明 |
 | --- | --- |
-| `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | Create a project. Duplicate slug → `409 PROJECT_SLUG_CONFLICT`. |
-| `list()` | List projects in the token's effective scope. |
-| `get(projectId)` | Fetch one project. |
+| `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | 创建 Project。slug 重复时返回 `409 PROJECT_SLUG_CONFLICT`。 |
+| `list()` | 列出 token 有效 scope 内的 Project。 |
+| `get(projectId)` | 查询单个 Project。 |
+### `agenthub.workloads`（别名 `agenthub.agents`）
-### `agenthub.workloads`
+> `agenthub.agents` 与 `agenthub.workloads` 是同一个对象，下表方法两边都能调。
-| Method | Description |
+| 方法 | 说明 |
 | --- | --- |
-| `create(req, { dryRun? })` | Create a workload from structured input. Returns `{ mode, status, workloadId?, workload }`. |
-| `publishRevision(req, { dryRun? })` | Publish a revision. Returns `{ mode, status, workloadId, revisionId?, runtimeTemplateId, resolved }`. |
-| `applyManifest({ projectId, manifest, dryRun? })` | Advanced/GitOps: apply a raw workload manifest. |
-| `applyRevisionManifest({ projectId, workloadSlug, manifest, dryRun? })` | Advanced/GitOps: apply a raw revision manifest. |
+| `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` 优先。 |
-`req` for `create`:
+`create` 的 `req`：
 ```ts
 {
@@ -162,7 +190,7 @@ platform-shared templates, below).
 }
 ```
-`req` for `publishRevision`:
+`publishRevision` 的 `req`：
 ```ts
 {
@@ -178,36 +206,129 @@ platform-shared templates, below).
 }
 ```
-`manifest` (for the `apply*` methods) accepts a manifest object, `{ yaml }`, or
-`{ json }`.
+`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`
-| Method | Description |
+| 方法 | 说明 |
+| --- | --- |
+| `create({ projectId, workloadId, revisionId?, configValues?, metadata?, idempotencyKey?, resources?, ... })` | 启动 Session。省略 `revisionId` 时使用 Workload 默认 Revision。`resources` 注入 Model A 只读输入文件（见下）。返回 `{ sessionId, status }`。 |
+| `get(sessionId)` | 读取 Session 快照（`{ session: { id, status, ... } }`）。 |
+| `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | 轮询到 `status === "ready"`；遇到 `failed` 或超时会抛错。 |
+Session `status` 取值为 `created`、`provisioning`、`starting`、`ready`、`failed`。
+### `agenthub.files`
+| 方法 | 说明 |
 | --- | --- |
-| `create({ projectId, workloadId, revisionId?, configValues?, metadata?, idempotencyKey?, ... })` | Start a session. Omitting `revisionId` uses the workload's default revision. Returns `{ sessionId, status }`. |
-| `get(sessionId)` | Snapshot the session (`{ session: { id, status, ... } }`). |
-| `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | Poll until `status === "ready"`; throws on `failed` or timeout. |
+| `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,
+  workloadId,
+  resources: {
+    version: "v1",
+    files: [{ ...meta, mountPath: "docs/spec.md" }], // mountPath 可省略 → 用文件名
+  },
+});
+// agent 在 /workspace/.session/inputs/docs/spec.md 只读看到该文件
+```
-Session `status` is one of `created`, `provisioning`, `starting`, `ready`,
-`failed`.
+约束：每 Session ≤ 20 个文件；`mountPath` 必须是 `.session/inputs/` 下的相对子路径
+（拒绝绝对路径与 `..`）；只读。
-## Runtime templates
+## Runtime template
-A managed-agent revision runs on a **runtime template** (a registered runtime
-source). The Control Plane resolves it in this order:
+managed-agent Revision 运行在一个 **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. revision `runtime.profileRef`（structured）/ `spec.runtime.profileRef`
+2. revision `spec.runtimeTemplateRef`（manifest）
+3. workload defaults `spec.defaults.runtimeTemplateRef`（manifest）
 4. project `defaultRuntimeTemplateRefName`
-If none resolves → `PROJECT_DEFAULT_RUNTIME_MISSING`. If the named template does
-not exist in the project (or as a platform-shared template) →
-`RUNTIME_TEMPLATE_NOT_FOUND`.
+如果都解析不到，返回 `PROJECT_DEFAULT_RUNTIME_MISSING`。如果指定模板在当前 Project
+或 platform-shared templates 中不存在，返回 `RUNTIME_TEMPLATE_NOT_FOUND`。
-For the happy path, give the project a default at creation so callers never pick
-a template:
+主路径建议在创建 Project 时设置默认模板，这样调用方发布 Revision 时不需要手选：
 ```ts
 await agenthub.projects.create({
@@ -217,21 +338,20 @@ await agenthub.projects.create({
 });
 ```
-Otherwise select one explicitly per revision with
-`runtime: { profileRef: { name: "..." } }`.
+否则需要在每个 Revision 上显式指定：
+`runtime: { profileRef: { name: "..." } }`。
-**Platform-shared templates.** Templates owned by the Platform Default project
-(e.g. `pilot-v2-pod-agent`) are shared infrastructure: the lookup falls back to
-Platform Default when the name is not found in the caller's project, so any
-project's revision may reference them by name. `echo-bot` is a built-in
-echo-only template useful for smoke tests — it does **not** run an LLM.
+**Platform-shared templates。** Platform Default project 拥有的模板（例如
+`pilot-v2-pod-agent`）是共享基础设施：当调用方 Project 内找不到同名模板时，解析会回退到
+Platform Default，因此任意 Project 的 Revision 都可以按名称引用它们。`echo-bot`
+是内置 echo-only 模板，适合 smoke test；它**不会**运行 LLM。
-## Models
+## 模型
-`model` accepts a full id (`claude-opus-4-7`, `claude-sonnet-4-6`,
-`claude-haiku-4-5`) or a legacy alias that maps to one:
+`model` 接受完整 id（`claude-opus-4-7`、`claude-sonnet-4-6`、`claude-haiku-4-5`），
+也接受会映射到完整 id 的历史别名：
-| Alias | Resolves to |
+| Alias | 解析为 |
 | --- | --- |
 | `opus` | `claude-opus-4-7` |
 | `sonnet` | `claude-sonnet-4-6` |
@@ -239,15 +359,14 @@ echo-only template useful for smoke tests — it does **not** run an LLM.
 ## Dry runs
-`workloads.create`, `publishRevision`, and the `apply*` methods accept
-`{ dryRun: true }`. A dry run validates and resolves the request without
-persisting, returning `mode: "dry_run"` and a `would_create` / `would_update`
-status. Use it to verify a runtime template resolves before publishing for real.
+`workloads.create`、`publishRevision` 和 `apply*` 方法都接受 `{ dryRun: true }`。
+dry run 会校验并解析请求，但不持久化；返回 `mode: "dry_run"` 和
+`would_create` / `would_update` 状态；Revision 已存在且内容一致时可能返回
+`existing`。正式发布前可以用它确认 runtime template 能正确解析。
-## Errors
+## 错误
-All API failures throw a typed error carrying `status`, `code`, and
-`requestId`:
+所有 API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`：
 | Class | HTTP |
 | --- | --- |
@@ -255,7 +374,7 @@ All API failures throw a typed error carrying `status`, `code`, and
 | `PilotPlatformForbiddenError` | 403 |
 | `PilotPlatformNotFoundError` | 404 |
 | `PilotPlatformServerError` | 5xx |
-| `PilotPlatformApiError` | base class for the above |
+| `PilotPlatformApiError` | 上述错误的基类 |
 ```ts
 import { PilotPlatformNotFoundError } from "@kanyun-ai-infra/agenthub";