@kanyun-ai-infra/agenthub 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 本文件从 1.12.0 开始记录；更早的版本见 git 历史中的 `chore(agenthub-sdk): release X.Y.Z` 提交。
 
+## 1.26.0
+
+本版带上 1.25.0（87ef69055，#5878，11-06）之后合入 main 的公开面变化：`vaults.credentials` 的 create / update 建模 `net_secret` 凭据（#5879，#5805 SDK 臂）。新增凭据类型属 minor，无破坏性变化，不建 `net_secret` 凭据时行为逐字不变。会话侧的冻结与下发（#5874）、gateway 转发（#5876）不进 SDK 导出面（d.ts diff 为准），只在 JS 运行时以内联常量出现。
+
+### 新增（主入口）
+
+- `vaults.credentials.create(vaultId, { auth: { type: "net_secret", envName, domains, inject?, accessToken } })`（#5879）：让 agent 直接调用非 MCP 的多模态 HTTP 服务（图像 / 语音 / 视频 API），key 由平台按域名注入，不进沙箱。四件事：
+  - **三个身份字段不可变**：`envName`（大写蛇形，2–48 字符，不得以 `_BASE_URL` / `_BASE_URL_TEMPLATE` 结尾）、`domains`（1–32 个互异的小写域名，可 `*.` 前缀；无 IP 字面量、端口、单标签通配）、`inject`（缺省 `{ header: "Authorization", prefix: "Bearer " }`；framing / cookie / proxy / `x-pilot-*` 头名被拒）创建后不可改，只许 `update` 改 `displayName` 与原地换 `accessToken`（`rotationSeq` +1，在途会话下一次请求即用新 key）。在 `update` 请求里写这些身份字段（或任何多余键），在发请求前就被本地 zod 拒绝；`customHeaders` / `auth.refresh` / `auth.expiresAt` 对该类型不适用，本地 schema 放行、请求照发，由服务端以 400 `validation_error` 拒绝。同一 vault 里第二个同 `envName` 的活跃凭据是 409 `vault_credential_env_name_conflict`。
+  - **返回体不带值与尾号**：create / update 返回的 `net_secret` 行只有元数据（`envName`、`domains`、`inject`、`secretRotatedAt`、`rotationSeq` 等），key 与任何 key 派生值都不出现。
+  - **会话里只拿到占位符**（需服务端部署 #5874 / #5876 且平台开关打开）：绑定该 vault 的会话每轮拿到 `<NAME>` = 占位 token（24h，不落库）与 `<NAME>_BASE_URL`（登记了唯一精确域名时）或 `<NAME>_BASE_URL_TEMPLATE`（通配 / 多域名，含字面 `{host}`），真实 key 永不进沙箱；agent 把请求发给 `<gateway>/net/v1/<NAME>/<host>/…`，gateway 校验 host 是否落在 `domains` 内、换成真实 key 后转发到 `https://<host>/…`。3xx 原样返回不跟随，agent 自行决定是否按 `Location` 再发；未登记 host 是 403，私网 / 回环地址拒绝。两个绑定 vault 有同名 `envName` 的活跃 `net_secret` 时 `sessions.create` 返回 409 `SESSION_NET_CREDENTIAL_CONFLICT`。
+  - **需要平台开 flag 才生效**：下发与转发由平台侧 `v2_net_secret_enabled`（`PILOT_V2_NET_SECRET_ENABLED`）控制，默认关；关态下 create / update 仍可写库（SDK 无开关），会话不下发变量。
+  - 服务端没有单条凭据的 list / get 路由，SDK 也不提供；`vcrd_*` id 只在 `create` 的返回里出现一次，调用方自行保存。
+- `CreateCredentialRequest` 的 `auth` 判别联合新增 `net_secret` 臂；`VaultCredentialRecord` 联合新增 `net_secret` 记录（`isKnownVaultCredential` 对它返回 true，可直接按 `authType` 收窄）。
+
+### 随包文档
+
+- `SKILL.md`：`net_secret` 用法一节（创建、不可变边界、占位符与 gateway 路径、409 冲突、平台开关）已在 #5879 随源码进 main。随包 skill 版本由 0.34.0 升至 0.35.0（npm 1.25.0 包里实测 `version: 0.34.0`）。
+
+### 导出面核对
+
+`npm pack @kanyun-ai-infra/agenthub@1.25.0` 解包后的 `dist/index.d.ts` 与本分支构建产物逐块对比，全部非注释差异：`CreateCredentialRequestSchema` 的 `auth` 判别联合新增 `net_secret` 臂（`envName` / `domains` / `inject?` / `accessToken` 四行）、凭据响应联合新增 `net_secret` 记录臂（17 行），以及三处 JSDoc 注释把 `net_secret` 加进「已建模类型」列表。没有删除行。`dist/realtime.d.ts` 逐字节相同。JS 运行时 diff（ESM 与 CJS 同内容，zod 别名重编号归一后）为 #5879 的建模臂与 #5874 经 contracts 进入 bundle 的内联常量（`NET_CREDENTIAL_TOKEN_TYPE` / `NET_CREDENTIAL_TOKEN_TTL_SECONDS` / `NetCredentialTokenClaimsSchema` / `FrozenNetCredentialSchema` / `FrozenNetCredentialListSchema`）——它们不被 SDK 导出、无 SDK 方法引用，不构成类型面变化；#5876（gateway）不触及 SDK bundle。
+
+### 迁移说明
+
+无破坏性变化，不需要迁移。旧版本风险：已发布的 1.25.0 收到 `net_secret` 行时走宽松兜底——`update` 响应作为 `UnknownVaultCredentialRecord` 原样返回不报错；`create` 响应因联合里无该臂会解析失败，要建模 `net_secret` 先升级到 1.26.0。
+
+## 1.25.0
+
+本版带上 1.24.0（85b344c33，#5864，11-05）之后合入 main 的公开面变化：`sessions.create` 钉 `revisionId` 起会话时显式指定 environment 的两个可选入参（#5871，F6）。无破坏性变化，不传新字段逐字不变。期间合入的 #5872（pending 凭据建壳）不进 SDK 类型面，只新增一个透传错误码。
+
+### 新增（主入口）
+
+- `sessions.create` 的可选 `environmentId` / `environmentVersion`（#5871，F6；Band 从 blocks 板 #1569 真依赖的读回路径）：钉 `revisionId`（别名 `versionId`）起会话时，让会话跑在显式指定的 environment（`runtime_templates` 行 id）上，而不是 revision 快照的基础模板。三件事：
+  - **不传 `environmentId` 时与 1.24.0 完全一样**：pin 路径的 environment 保持 `null`，用 revision 快照的模板；`stage` 路径不受影响，环境仍来自槽位绑定。
+  - **传了按显式环境走**：`environmentVersion` 缺省取该环境当时的可服务版本（current servable version），实际解析到的版本冻进会话；显式传的版本不存在或不可服务 → 400 `ENVIRONMENT_VERSION_NOT_FOUND`，不退到最新版。环境必须可被会话所属项目引用（同项目或平台共享、未归档），否则拒绝且不写会话行。
+  - **他项目的环境与不存在的 id 同形**：都是 404 `ENVIRONMENT_NOT_FOUND`（#3410 反枚举口径）；已归档是 422 `ENVIRONMENT_ARCHIVED`。
+  - 边界：`environmentId` 没有 `revisionId` 相伴 → 400 `ENVIRONMENT_REQUIRES_REVISION_PIN`（与 `stage` 同传也拒，stage 路径的环境来自槽位绑定）；`environmentVersion` 单独出现（无 `environmentId`）也被拒；公开项目的非成员访客带它 → 403 `public_viewer_cannot_declare_environment`；`(environmentId, environmentVersion)` 进 `idempotencyKey` 的请求身份（同 key 换环境 = 幂等冲突），带 `environmentId` 的 pin 请求不走预热池（`revisionId` 本身已退出预热）。请求 schema 是 `.strict()`：1.24.0 及更早版本传 `environmentId` 会在发请求前被本地 zod 拒绝，要用先升级到 1.25.0。需要服务端部署 #5871。
+- 错误码透传（#5872，不改调用方式）：SDK 按服务端原样透传的 zod 内联闭集（`dist/index.js` 里的 `MANAGED_MCP_ERROR_CODES` 数组）新增成员 `managed_mcp_pending_credential`（409：值待填的壳不能退场 / 重建）。该闭集不在 d.ts 类型面（1.24.0 起即如此），不构成类型变化。闭集在构建时内联进 SDK bundle：1.24.0 的 bundle 构建于 85b344c33，里面没有这个成员——服务端部署 #5872 后，1.24.0 收到它会投影成 `UNKNOWN_ERROR`（`PilotPlatformApiError`，status 409，非原样 code）；要原样透出，先升级到 1.25.0。
+
+### 随包文档
+
+- `SKILL.md`：「Pinning a revision with an explicit environment: `environmentId`」一节（用法、错误码、幂等与预热池边界）已在 #5871 随源码进 main。随包 skill 版本由 0.33.0 升至 0.34.0（npm 1.24.0 包里实测 `version: 0.33.0`）。
+
+### 导出面核对
+
+`npm pack @kanyun-ai-infra/agenthub@1.24.0` 解包后的 `dist/index.d.ts` 与本分支构建产物逐块对比，全部非注释差异：`CreatePlatformSessionRequestSchema`（即 `CreateSessionRequestSchema`）对象内新增 `environmentId: z.ZodOptional<z.ZodString>` 与 `environmentVersion: z.ZodOptional<z.ZodNumber>` 两行（#5871）。没有删除行。`dist/realtime.d.ts` 逐字节相同。JS 运行时 diff（ESM 与 CJS 同内容）的其余部分均为 #5872 带入、SDK 不导出的内联 schema 与常量：`CreatePendingManagedMcpRemoteSchema` / `CreatePendingManagedMcpStdioSchema` / `CreatePendingManagedMcpRequestSchema` / `CreatePendingSecretRequestSchema`（pending 建壳，仅经 contracts 源码树进入 bundle，不在 SDK 出参 / 入参 / 导出类型上）、`MANAGED_MCP_ERROR_CODES` 数组新增成员 `managed_mcp_pending_credential`、以及 #5871 的两个 refine 消息文本；不构成类型面变化。#5869（迁移）不触及 SDK。
+
+### 迁移说明
+
+无破坏性变化，不需要迁移。两个字段均可选，不传逐字不变。1.24.0 的 `sessions.create` 请求 schema 是 strict，传 `environmentId` 会在发请求前被拒，要用先升级到 1.25.0。
+
 ## 1.24.0
 
 本版带上 1.23.0（9a5aad9fe，#5829，11-04）之后合入 main 的两组公开面变化：`workloads.getRevisionById`（#5856，Band 从槽位 `revisionId` 得到版本名的依赖），以及凭据直写收紧到项目管理员带来的新 403 错误码（#5858）。均不破坏编译。