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

@kanyun-ai-infra/agenthub 0.1.1 → 0.3.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,52 @@
 # @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 → agent → version → 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 让发布 Version 时不必每次手选模板。
 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。
+await agenthub.agents.create({
   projectId: project.id,
   slug: "support-bot",
   displayName: "Support Bot",
@@ -56,11 +57,10 @@ 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 的不可变发布版本。Runtime source 默认继承 Project default。
+const version = await agenthub.agents.publishVersion({
   projectId: project.id,
-  workloadSlug: "support-bot",
+  agentSlug: "support-bot",
   version: "v1",
   workerContract: { kind: "managed_agent" },
   setDefault: true,
@@ -70,144 +70,175 @@ const revision = await agenthub.workloads.publishRevision({
   },
 });
-// 4. Session — a runtime allocation against the default (or a specific) revision
+// 4. Session：基于默认 Version（或指定 Version）分配一次运行时。
 const session = await agenthub.sessions.create({
   projectId: project.id,
-  workloadId: revision.workloadId,
+  agentId: version.agentId, // 用默认 Version；指定版本传 versionId
 });
-const ready = await agenthub.sessions.wait(session.sessionId); // resolves when status === "ready"
+const ready = await agenthub.sessions.wait(session.sessionId); // status === "ready" 时返回
 ```
-## Client configuration
+## 核心模型
-`new PilotPlatformClient(config)`
+```text
+Project  →  Agent  →  Version  →  Session
+```
+- **Project**：租户 / 根分组，拥有 agents 和 runtime templates。
+- **Agent**：一个逻辑可运行应用。`kind` 是 `"managed_agent"`（平台基于
+  `model` + `systemPrompt` 运行 agent loop）或 `"self_managed"`（你自己提供 worker）。
+- **Version**：Agent 的不可变发布版本，绑定一个 runtime source。用 `setDefault`
+  标记 project/agent 默认版本。
+- **Session**：基于某个 Version 发起的一次 startup/runtime allocation。
-| Option | Required | Description |
+Agents 和 runtime templates 都是 **project-scoped**。Version 必须在同一个 Project
+内解析到 Agent 和 runtime source；唯一例外是下文的 platform-shared templates。
+> 本文一律用主词汇 **agent / version**；它们是底层 wire 名 `workload` / `revision`
+> 的别名，SDK 两套都接受，细节见 [术语别名](#术语别名agent--version)。
+### 术语别名（agent / version）
+| 主词汇（推荐） | 等价的底层名 | 说明 |
 | --- | --- | --- |
-| `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). |
+| `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` | 返回对象**同时带**两套字段（别名 = 规范值）。 |
-¹ `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.
+规则：
-### Getting a token
+- **互斥**：一对里只能传一个，规范名和别名同传会抛 `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 改名范围内）。
-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.
+## API 参考
-## Core model
+### `agenthub.projects`
-```text
-Project  →  Workload  →  Revision  →  Session
-```
+| 方法 | 说明 |
+| --- | --- |
+| `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | 创建 Project。slug 重复时返回 `409 PROJECT_SLUG_CONFLICT`。 |
+| `list()` | 列出 token 有效 scope 内的 Project。 |
+| `get(projectId)` | 查询单个 Project。 |
+### `agenthub.agents`（别名 `agenthub.workloads`）
-- **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.
+| 方法 | 说明 |
+| --- | --- |
+| `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 拼写都接受（互斥）。 |
-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).
+`create` / `publishVersion` 的 `req` 结构和 managed-agent 全部配置项（`model` /
+`systemPrompt` / `enabledSkills` / `enabledMcpServers` / `agentOptions` 安全约束 /
+`runtime` / `startup` 等），见
+[`specs/features/agenthub-sdk.md`](../../specs/features/agenthub-sdk.md)
+的 "Managed-Agent Configuration"、"Workload API Contract"、"Revision Publish Contract" 章节。
-## API reference
+> **`agentOptions` 安全约束（高频踩坑）**：`agentOptions` **只能收紧 / 限额**，不能放宽。
+> `allowedTools` 与平台基线**取交集**（只会更窄）、`disallowedTools` 叠加平台黑名单且
+> **不能移除**平台守卫工具；`permissionMode` / `env` / `mcpServers` / `hooks` /
+> `plugins` / 原始 `sdkOptions` 等可能越权或逃逸 sandbox 的字段**一律不开放**（见 issue #840）。
+> 字段全表见上述 spec。
-### `agenthub.projects`
+`apply*` 方法里的 `manifest` 可以是 manifest 对象、`{ yaml }` 或 `{ json }`。
+### `agenthub.sessions`
-| 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({ 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` 或超时会抛错。 |
-### `agenthub.workloads`
+Session `status` 取值为 `created`、`provisioning`、`starting`、`ready`、`failed`。
-| Method | Description |
+### `agenthub.files`
+| 方法 | 说明 |
 | --- | --- |
-| `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. |
+| `upload({ projectId, file, filename?, contentType? })` | 上传单个文件，返回 `{ ossUrl, url, filename, size, mediaType, mimeType }`。`file` 接受 `Blob` / `File` / `Uint8Array` / `ArrayBuffer`；非具名 `File` 时必须传 `filename`。 |
-`req` for `create`:
+文件落在 `pilot/attachments/<projectId>/`，与 Session 资源 scope 校验同一 keyspace —— 为某 Project
+上传的文件无法挂到另一个 Project 的 Session。`url` 是 ~1h 的 presigned GET（仅预览用）；
+要持久引用的是 `ossUrl`。
-```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 */ };
-}
-```
+#### Model A 只读输入文件（session resources）
-`req` for `publishRevision`:
+把文件作为 **Session 级只读输入**挂进 sandbox 的 `/workspace/.session/inputs/`（每次
+provision / revival 重新物化），用 `files.upload` + `sessions.create({ resources })`：
 ```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?: ... };
-}
+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 只读看到该文件
 ```
-`manifest` (for the `apply*` methods) accepts a manifest object, `{ yaml }`, or
-`{ json }`.
+约束：每 Session ≤ 20 个文件；`mountPath` 必须是 `.session/inputs/` 下的相对子路径
+（拒绝绝对路径与 `..`）；只读。
-### `agenthub.sessions`
+## Client 配置
-| Method | Description |
-| --- | --- |
-| `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. |
+`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
-Session `status` is one of `created`, `provisioning`, `starting`, `ready`,
-`failed`.
+登录 **管理门户** <https://agenthub.zhenguanyu.com> 并签发 **platform-api token**。
+该 token 的作用域是 Control Plane API（`agenthub-plane.zhenguanyu.com`）；可以存为
+`PILOT_TOKEN`，也可以显式传给 `token`。Token 是 Bearer 凭据，请不要提交到代码仓库；
+泄露后需要在门户里轮换。
-## 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 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`
-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 时设置默认模板，这样发布 Version 时不需要手选：
 ```ts
 await agenthub.projects.create({
@@ -217,21 +248,19 @@ await agenthub.projects.create({
 });
 ```
-Otherwise select one explicitly per revision with
-`runtime: { profileRef: { name: "..." } }`.
+否则需要在每个 Version 上显式指定：`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 的 Version 都可以按名称引用它们。`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 +268,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.
+`agents.create`、`publishVersion` 和 `apply*` 方法都接受 `{ dryRun: true }`。
+dry run 会校验并解析请求，但不持久化；返回 `mode: "dry_run"` 和
+`would_create` / `would_update` 状态；Version 已存在且内容一致时可能返回
+`existing`。正式发布前可以用它确认 runtime template 能正确解析。
-## Errors
+## 错误
-All API failures throw a typed error carrying `status`, `code`, and
-`requestId`:
+所有 API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`：
 | Class | HTTP |
 | --- | --- |
@@ -255,7 +283,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";