@kanyun-ai-infra/agenthub 0.1.0 → 0.2.0

package/README.md

@@ -1,24 +1,57 @@
 # @kanyun-ai-infra/agenthub
 
-Typed SDK for the Pilot v2 Control Plane API.
+用于 **agenthub Control Plane API** 的类型化 TypeScript 客户端。
+
+它直接调用 agenthub Control Plane，适合后端服务、CI 和工具以编程方式驱动
+`project -> workload -> revision -> session` 生命周期。
+
+接入时会遇到两个入口：
+
+| 入口 | URL | 用途 |
+| --- | --- | --- |
+| **Control Plane API** | `https://agenthub-plane.zhenguanyu.com` | SDK / 你的服务调用。作为 `controlPlaneUrl` 传入。 |
+| **管理门户** | `https://agenthub.zhenguanyu.com` | 人工发布和管理 agent，并在这里**签发 API token**。 |
+
+两者使用不同的 token audience：Portal 登录态 token 不能调用 Control Plane，反过来也一样。
+请始终把管理门户签发的 platform-api token 和 `agenthub-plane` Control Plane URL 配套使用。
+
+## 安装
+
+```bash
+pnpm add @kanyun-ai-infra/agenthub
+# 或：npm i @kanyun-ai-infra/agenthub
+```
+
+需要 Node 18+，因为 SDK 使用全局 `fetch`。
+
+如果调用方是 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 pilot = new PilotPlatformClient({
-  controlPlaneUrl: "https://pilot-control-plane.example.com",
-  token: process.env.PILOT_TOKEN,
+const agenthub = new PilotPlatformClient({
+  controlPlaneUrl: "https://agenthub-plane.zhenguanyu.com",
+  token: process.env.PILOT_TOKEN, // 管理门户签发的 platform-api token
 });
 
-const project = await pilot.projects.create({
-  slug: "acme-project",
-  displayName: "Acme Project",
+// 1. Project：租户 / 根分组。默认 runtime template 让调用方发布
+//    Revision 时不必每次手选模板。
+const project = await agenthub.projects.create({
+  slug: "acme",
+  displayName: "Acme",
+  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
 });
 
-await pilot.workloads.create({
+// 2. Agent：Project 下一个可运行的 agent/app
+//    （`agents` 是 `workloads` 的别名，下文「术语别名」有说明）
+await agenthub.agents.create({
   projectId: project.id,
-  slug: "acme-agent",
-  displayName: "Acme Agent",
+  slug: "support-bot",
+  displayName: "Support Bot",
   kind: "managed_agent",
   defaults: {
     model: "claude-opus-4-7",
@@ -26,21 +59,332 @@ await pilot.workloads.create({
   },
 });
 
-const revision = await pilot.workloads.publishRevision({
+// 3. Version：Agent 的不可变发布版本（`publishVersion` 是 `publishRevision`
+//    的别名）。Runtime source 默认继承 Project default；要按版本覆盖传
+//    `runtime.profileRef`。
+const version = await agenthub.agents.publishVersion({
   projectId: project.id,
-  workloadSlug: "acme-agent",
+  agentSlug: "support-bot",
   version: "v1",
   workerContract: { kind: "managed_agent" },
+  setDefault: true,
+  managedAgentProfileSnapshot: {
+    model: "claude-opus-4-7",
+    systemPrompt: "You are the Acme support agent.",
+  },
 });
 
-const session = await pilot.sessions.create({
+// 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); // 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**：租户 / 根分组，拥有 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 })`
+仍沿用核心模型命名。挑读起来顺的那套写即可。
+
+```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 参考
+
+### `agenthub.projects`
+
+| 方法 | 说明 |
+| --- | --- |
+| `create({ slug, displayName, description?, defaultRuntimeTemplateRefName? })` | 创建 Project。slug 重复时返回 `409 PROJECT_SLUG_CONFLICT`。 |
+| `list()` | 列出 token 有效 scope 内的 Project。 |
+| `get(projectId)` | 查询单个 Project。 |
+
+### `agenthub.workloads`（别名 `agenthub.agents`）
+
+> `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?: ... };
+}
+```
+
+`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, ... } }`）。 |
+| `wait(sessionId, { intervalMs?, timeoutMs?, signal? })` | 轮询到 `status === "ready"`；遇到 `failed` 或超时会抛错。 |
+
+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,
+  workloadId,
+  resources: {
+    version: "v1",
+    files: [{ ...meta, mountPath: "docs/spec.md" }], // mountPath 可省略 → 用文件名
+  },
 });
+// agent 在 /workspace/.session/inputs/docs/spec.md 只读看到该文件
+```
+
+约束：每 Session ≤ 20 个文件；`mountPath` 必须是 `.session/inputs/` 下的相对子路径
+（拒绝绝对路径与 `..`）；只读。
+
+## Runtime template
+
+managed-agent Revision 运行在一个 **runtime template**（已注册的 runtime source）上。
+Control Plane 按以下顺序解析：
 
-await pilot.sessions.wait(session.sessionId);
+1. revision `runtime.profileRef`（structured）/ `spec.runtime.profileRef`
+2. revision `spec.runtimeTemplateRef`（manifest）
+3. workload defaults `spec.defaults.runtimeTemplateRef`（manifest）
+4. project `defaultRuntimeTemplateRefName`
+
+如果都解析不到，返回 `PROJECT_DEFAULT_RUNTIME_MISSING`。如果指定模板在当前 Project
+或 platform-shared templates 中不存在，返回 `RUNTIME_TEMPLATE_NOT_FOUND`。
+
+主路径建议在创建 Project 时设置默认模板，这样调用方发布 Revision 时不需要手选：
+
+```ts
+await agenthub.projects.create({
+  slug: "acme",
+  displayName: "Acme",
+  defaultRuntimeTemplateRefName: "pilot-v2-pod-agent",
+});
 ```
 
-This package talks directly to `apps/control-plane`. The legacy
-`@kanyun-ai-infra/pilot` package remains available for the portal/BFF
-`agents` and `runs` workflows.
+否则需要在每个 Revision 上显式指定：
+`runtime: { profileRef: { name: "..." } }`。
+
+**Platform-shared templates。** Platform Default project 拥有的模板（例如
+`pilot-v2-pod-agent`）是共享基础设施：当调用方 Project 内找不到同名模板时，解析会回退到
+Platform Default，因此任意 Project 的 Revision 都可以按名称引用它们。`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
+
+`workloads.create`、`publishRevision` 和 `apply*` 方法都接受 `{ dryRun: true }`。
+dry run 会校验并解析请求，但不持久化；返回 `mode: "dry_run"` 和
+`would_create` / `would_update` 状态；Revision 已存在且内容一致时可能返回
+`existing`。正式发布前可以用它确认 runtime template 能正确解析。
+
+## 错误
+
+所有 API 请求失败都会抛出类型化错误，错误对象带 `status`、`code` 和 `requestId`：
+
+| Class | HTTP |
+| --- | --- |
+| `PilotPlatformUnauthenticatedError` | 401 |
+| `PilotPlatformForbiddenError` | 403 |
+| `PilotPlatformNotFoundError` | 404 |
+| `PilotPlatformServerError` | 5xx |
+| `PilotPlatformApiError` | 上述错误的基类 |
+
+```ts
+import { PilotPlatformNotFoundError } from "@kanyun-ai-infra/agenthub";
+
+try {
+  await agenthub.sessions.get(sessionId);
+} catch (err) {
+  if (err instanceof PilotPlatformNotFoundError) {
+    // err.status === 404, err.code === "SESSION_NOT_FOUND"
+  }
+  throw err;
+}
+```