@tier0/sdk-v2 0.6.1 → 0.6.3

package/README.md

@@ -2,13 +2,9 @@
 
 Tier0 云端新架构的独立 TypeScript / JavaScript SDK。新仓库、新 npm 包，不覆盖 `@tier0/sdk`。
 
-`0.6.0` 的 HTTP Source 只保留 `protocol: http-api`，通过 `config.role: client | server` 区分主动请求与入站服务。旧 `http` / `http_push` 配置需要迁移；响应时机属于 Stream，不再建立独立异步 Source。同步 singlemodel 合同后，Source 配置不再带 configVersion，Stream 输入不再带 sdkVersion；保留完整 module.exports 程序与原生 script 对象/Runtime program 字符串两种既有形态，不能将旧 transform 函数体直接改名迁入。
+要求 Node.js 20.19+。HTTP API 统一使用 `/openapi/v2`，Source、Stream、UNS 按领域提供入口；浏览器 HTTP、MQTT、React、Vue 和服务端身份验签分别提供独立入口。
 
-`0.4.0` 版本变更：相对 0.3.x 移除已退役的 Stream 就绪探针且不保留别名，改用服务端现有统一权限，不再配置逐 Key Control scopes/codes。0.3.0 起统一使用 OpenAPI v2 并退役重复及旧接口；与 0.2.x 存在不兼容变更，迁移方式见下方“本次接口退役”。对应 UNS v2 契约 5.0.0，与 0.1.0 不兼容（新错误模型 `execution` / `retry`、封顶计数、删除 `recordChangesPoll` 等）。Collection 支持 int、float、double 和 datetime 声明；格式注解不新增数值范围或日期格式校验，Sample 外层 time 保持不变。使用时需确认目标环境已部署对应后端。要求 Node.js 20.19+。浏览器 HTTP、MQTT、React、Vue 和服务端身份验签分别提供独立入口。
-
-本版本合同快照固定到已提交 Backend `86bef2325253c2f4eaab8168f983ac4ec09c0d2f`；使用前需确认目标环境已部署相应合同。请求统一权限、旧探针退役门禁、Source discovery 的副作用分类及不自动重试语义保持不变。
-
-既有接口收敛：平台接口统一迁移到 `/openapi/v2`，Controls 使用 `/openapi/v2/uns/controls/*`；移除 21 个重复 UNS 入口和旧 Agent nodes/relations 方法。完善 Source 操作、Stream 发布回执及 UNS 创建快照的使用说明，保留精确发布编号和完整文档访问规则。
+当前契约版本与后端提交见 [契约来源](contracts/upstream.json)。安装 SDK 后仍需确认目标环境已部署相应后端。
 
 ## 安装与初始化
 
@@ -23,9 +19,8 @@ import { createClient } from '@tier0/sdk-v2';
 
 // 服务端环境注入 TIER0_API_HOST 和 TIER0_API_KEY。
 const tier0 = createClient();
+// 首次接入时确认身份与 Workspace；不需要在每次业务操作前重复调用。
 const user = await tier0.system.whoami();
-const platform = await tier0.system.info();
-const capabilities = await tier0.capabilities.discover();
 ```
 
 也可显式配置 `{ apiHost, apiKey, transportTimeoutMs, fetch }`，或提供 `getApiHost` / `getApiKey` 回调。裸域名默认使用 HTTPS；本地 HTTP 测试请显式写 `http://127.0.0.1:端口`。不自动向浏览器注入或读取 `VITE_` API Key。
@@ -57,18 +52,7 @@ const capabilities = await tier0.capabilities.discover();
 | `@tier0/sdk-v2/data` | App 数据层：`defineCollection()` 声明集合（含 TTL）、`createDataClient()` 首次访问时 ensure，Mongo 风格读写、带总数分页与封顶计数、原子批量与 `transact`、`subscribe` 变更订阅、员工数据主体透传；自动幂等键、并发上限与按 `retry.safe` 重试；仅服务端，需要 `zod` 4 |
 | `@tier0/sdk-v2/data/define` | 集合声明与类型：`defineCollection()`、`Doc` / `NewDoc` 等、`compileCollection()`、`validateDocument()`；可进浏览器包，组件和 route 的客户端代码只从这里取声明和类型 |
 
-不保留 UNS v1、旧 Flow、`getCurrentProjectId()`、project 成员查询或 `/gw/reload`。Workspace 成员不等于能使用某个 App 的成员，不可用前者在客户端猜测 App 权限。
-
-## 本次接口退役
-
-HTTP 调用统一使用 `/openapi/v2`。21 个重复 UNS 公共入口及生成方法直接移除，没有旧路由回退；升级 SDK 时需同时部署对应后端。
-
-- Source 的 list/get/create/update、connection.update 改用 documents.*；Stream 的 programs.get/create/update/validate/disable 改用 documents.*，停用同时携带 expectedRevision 与 expectedActiveRelease。
-- 低层 findOneAnd* 改用 updateOne/replaceOne/deleteOne 的 returnDocument；批量新增用 bulkWrite 的 insertOne 项；元数据单条读取用 metadataFind + limit:1，去重用 aggregate。
-- App 数据层的 insertMany、findOneAnd*、distinct 等便捷方法保留，由 SDK 映射到当前入口；insertMany 仍是单次原子请求，最多 200 项。
-- Agent 的旧 nodes.searchSemantic/indexSync 和 relations.list/teach 没有 v2 契约，不再导出。Controls 使用 `/openapi/v2/uns/controls/*`，错误保留 execution/retry/requestId，且不会自动重试。
-
-升级前应核对旧写请求的最终结果，包括集合初始化 seed。退役入口不再可调用，不能将未知结果的旧请求或幂等键直接改投新入口重做。当前入口的重试仍保留原路径、原键和原载荷。
+Workspace 成员不等于能使用某个 App 的成员；App 成员选择使用 `members.listApp`。
 
 ## Source、Stream 与 UNS 分域
 
@@ -79,18 +63,14 @@ const sources = await tier0.source.documents.list({ page: 1, size: 20 });
 const programs = await tier0.stream.programs.list({ page: 1, size: 20 });
 ```
 
-HTTP Source 统一使用 `protocol: 'http-api'`，显式设置 `config.role: 'client'`（主动请求）或 `config.role: 'server'`（接收入站请求），与 Enterprise 一协议两角色保持一致；Cloud 管理文档的角色位于 config 内。旧 `http` 正向示例迁移为 `http-api` + `client`；Server 不能作为 Client 发起主动请求。HTTPServer 使用固定前缀 `/ingest/v1/{workspaceId}/{sourceId}`，业务路由注册在 Stream；普通返回在处理和提交完成后回复；HTTP `onRequest` 可通过一次 `await ctx.reply(...)` 先回复再继续，仍受超时、并发和权限限制，回复后不随客户端断线取消但可由 shutdown 取消，不保证崩溃重放。202 状态本身不证明处理完成。示例见 [HTTPServer Stream Skill](skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/http-server.md)。使用 `source.protocols.list({})` 核对目标环境支持，再通过现有 `source.documents.*` 管理配置。HTTP Client 单条 inline 创建支持 Basic、Bearer、APIKey、OAuth 四类认证，凭据默认绑定 Source 基址 REQUEST，显式方法继续保留限制；独立 credentialCreate 仍为 coreOnly。SDK 不新增猜测的 HTTP In API；npm 管理 SDK 与执行器中的 Goja Stream 脚本 API 分开使用。
+HTTP Source 统一使用 `protocol: 'http-api'`，显式设置 `config.role: 'client'`（主动请求）或 `config.role: 'server'`（接收入站请求），与 Enterprise 一协议两角色保持一致；Cloud 管理文档的角色位于 config 内。Server 不能作为 Client 发起主动请求。HTTPServer 使用固定前缀 `/ingest/v1/{workspaceId}/{sourceId}`，业务路由注册在 Stream；普通返回在处理和提交完成后回复；HTTP `onRequest` 可通过一次 `await ctx.reply(...)` 先回复再继续，仍受超时、并发和权限限制，回复后不随客户端断线取消但可由 shutdown 取消，不保证崩溃重放。202 状态本身不证明处理完成。示例见 [HTTPServer Stream Skill](skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/http-server.md)。使用 `source.protocols.list({})` 核对目标环境支持，再通过现有 `source.documents.*` 管理配置。HTTP Client 单条 inline 创建支持 Basic、Bearer、APIKey、OAuth 四类认证，凭据默认绑定 Source 基址 REQUEST，显式方法继续保留限制；独立 credentialCreate 仍为 coreOnly。SDK 不新增猜测的 HTTP In API；npm 管理 SDK 与执行器中的 Goja Stream 脚本 API 分开使用。
 
 Source/Stream 仍保留 `{ code, msg, requestId, data }` 响应以及 `UnsV2Error` 错误类型。Source 配置统一使用 `source.documents`；Stream 草稿统一通过 `stream.documents` 创建、读取、校验和修改，输入 `program` 与 `document` 二选一。发布和回滚仍走 `stream.programs`。保存、部署、运行成功分别判断。
 
-旧 `stream.runtime.capabilities()` 及底层 `streamRuntimeCapabilitiesGet` 已退役，没有兼容别名；不要把该查询当作 Stream 前置检查，也不要为消除它的 403 增加 Control scope 或逐 Key 的控制码授权。Stream 管理、实际执行、发布、回滚及运行记录继续通过各自接口和统一权限校验；通用能力发现不代替实际操作结果。
-
 - 已知 Source ID/revision 且没有 Stream 引用时，可 [直接 patch 或变更状态](skills/tier0-sdk-v2/tier0-sdk-v2-source/references/update.md)；有引用时仍按精确意图确认影响。
 - Stream 创建/更新回执的 revision 可直接用于发布；[发布回执](skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md) 的 activeRelease 用于观察这次发布，无需前后各查询一次。
 - 单条 Record 新增可用 [returnDocument:'after'](skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/create.md) 同次取得创建快照；[App 数据层](skills/tier0-sdk-v2/tier0-sdk-v2-data/references/read-write.md) 支持相同选择及投影类型。
 
-从最初提交迁移：`uns.sourceList` → `source.documents.list`；`uns.sourceDocumentGet` → `source.documents.get`；`uns.streamProgramDeploy` → `stream.programs.deploy`；`uns.streamDocumentValidate` → `stream.documents.validate`。这些管理方法已移出主入口的 `uns`。底层 `createUnsV2Client()` 仍提供完整生成契约供契约工具使用；数据专用客户端可用 `createUnsDataClient()`。
-
 随包提供 Skill：总入口 [tier0-sdk-v2](skills/tier0-sdk-v2/SKILL.md) 下嵌套 11 个领域子 Skill（`skills/tier0-sdk-v2/tier0-sdk-v2-<领域>/`），每个仍可独立发现，包含完整流程、参数边界、错误处理与可类型检查的示例：[Source](skills/tier0-sdk-v2/tier0-sdk-v2-source/SKILL.md)、[Stream](skills/tier0-sdk-v2/tier0-sdk-v2-stream/SKILL.md)、[UNS](skills/tier0-sdk-v2/tier0-sdk-v2-uns/SKILL.md)、[通知](skills/tier0-sdk-v2/tier0-sdk-v2-notifications/SKILL.md)、[系统](skills/tier0-sdk-v2/tier0-sdk-v2-system/SKILL.md)、[文件](skills/tier0-sdk-v2/tier0-sdk-v2-files/SKILL.md)、[MQTT](skills/tier0-sdk-v2/tier0-sdk-v2-mq/SKILL.md)、[成员](skills/tier0-sdk-v2/tier0-sdk-v2-members/SKILL.md)、[Controls](skills/tier0-sdk-v2/tier0-sdk-v2-controls/SKILL.md)、[Agent](skills/tier0-sdk-v2/tier0-sdk-v2-agent/SKILL.md)、[App 数据](skills/tier0-sdk-v2/tier0-sdk-v2-data/SKILL.md)。复杂流程的参考文档随 Skill 一起打包。在 Tier0 Console 上传时，把整个 `skills/tier0-sdk-v2/` 目录打成一个 zip。
 
 ## UNS 数据访问
@@ -139,14 +119,15 @@ await tier0.notifications.send({
 ```ts
 const saved = await tier0.files.upload(new File(['report'], 'report.txt'));
 const stableReference = saved.filePath;
-const { fileUrl } = await tier0.files.url({ filePath: stableReference });
 const response = await tier0.files.download({ filePath: stableReference });
 const bytes = await response.arrayBuffer();
 ```
 
+只需要临时链接时调用 `files.url({ filePath })`；`download()` 已包含获取链接，无需先调用 url。
+
 保存 `filePath`，不把临时签名地址当作持久化引用。上传由平台签发地址后直传对象存储，平台 API Key 不传到存储域名；下载先获取签名地址，再匿名获取文件，避免认证重定向泄漏凭证。
 
-超过 100 MiB 自动使用分片上传，也可调用 `uploadMultipart(file, { partSize, signal, onProgress })`。首版顺序上传分片，不自动重试。中断后 `MultipartUploadError.session` 保留 uploadId、fileKey、已完成 parts 和 `completionAttempted`，可以通过 `files.multipart` 完成或终止；尝试过 complete 后必须先核对结果。未实现自动断点续传。
+超过 100 MiB 自动使用分片上传，也可调用 `uploadMultipart(file, { partSize, signal, onProgress })`。顺序上传分片，不自动重试。中断后 `MultipartUploadError.session` 保留 uploadId、fileKey、已完成 parts 和 `completionAttempted`，可以通过 `files.multipart` 完成或终止；尝试过 complete 后必须先核对结果。未实现自动断点续传。
 
 返回的下载 `Response` 由调用方消费；文件传输配置超时约束取得响应头的阶段，后续流式读取由调用方管理。所有业务附件、头像、导入/导出文件使用平台文件存储，不以 App 本地目录作为持久化存储。
 
@@ -223,6 +204,12 @@ node scripts/check-live-workflows.mjs <consumer> <workspaceId> .tmp/live-workflo
 node scripts/check-live-transports.mjs <consumer> <workspaceId> .tmp/live-transports.json --write-test-fixtures
 ```
 
-写入验收不发布 Stream、不启用 Source、不发送通知。归档资源保留正常产品恢复能力；报告区分通过、服务端拒绝和未验证范围。分片上传失败会保留错误原因，确认尚未尝试 complete 时清理本次会话；完成结果未知时先对账。完整结果见 [2026-10-22 验收报告](docs/acceptance-2026-10-22.md)。
+写入验收不发布 Stream、不启用 Source、不发送通知。归档资源保留正常产品恢复能力；报告区分通过、服务端拒绝和未验证范围。分片上传失败会保留错误原因，确认尚未尝试 complete 时清理本次会话；完成结果未知时先对账。
+
+Stream 发布和实际运行使用单独的验收脚本，同样只在明确授权的测试 Workspace 执行；按脚本报告区分已测和未测的生命周期阶段：
+
+```sh
+node scripts/check-live-stream-runtime.mjs <consumer> <workspaceId> .tmp/live-stream-runtime.json --write-test-fixtures
+```
 
-业务接入时仍需核对验收报告中的环境限制并补齐未验收范围、将 App 脚手架精确依赖更新为 `"@tier0/sdk-v2": "0.3.0"`，并按需更新已安装的 Skill。
+业务项目锁定实际安装的版本并同步更新随包 Skills；本地检查不代表线上业务验收通过。

package/dist/cjs/uns-v2/generated.d.ts

@@ -119,6 +119,7 @@ export type AppContext = {
     "name": string;
     "platformPermissions": Array<"openapi.base" | "platform.users.read" | "notifications.send" | "notifications.read" | "asset.file.upload" | "asset.file.download" | "asset.file.delete" | "stream.requests.read" | "stream.requests.invoke" | "stream.requests.write">;
     "revision": UnsV2Integer;
+    "dataState": "uninitialized" | "ready";
     "limits": CloudAppDataLimits;
 };
 export type AppKeyCreated = {
@@ -1885,7 +1886,7 @@ export type CloudStreamRunsListResponse = {
     "data": ({
         "items": (Array<({
             "id": string;
-            "kind": "delivery" | "control";
+            "kind": "delivery" | "control" | "http";
             "release": string;
             "entryId": string;
             "trigger": string;
@@ -1893,6 +1894,7 @@ export type CloudStreamRunsListResponse = {
             "createdAt": UnsV2Int64;
             "finishedAt": UnsV2Int64 | null;
             "durationMs": UnsV2Number | null;
+            "responseSentAt"?: UnsV2Int64 | null;
         })>);
         "nextCursor": string;
         "checkedAt": UnsV2Int64;
@@ -7754,6 +7756,9 @@ export declare const UNS_V2_CODEC_SCHEMAS: {
                                 readonly durationMs: {
                                     readonly k: "n";
                                 };
+                                readonly responseSentAt: {
+                                    readonly k: "i";
+                                };
                             };
                         };
                     };
@@ -9839,11 +9844,11 @@ export declare const UNS_V2_CODEC_SCHEMAS: {
 };
 export declare const UNS_V2_CONTRACT_PROVENANCE: {
     readonly repository: "FREEZONEX/Tier0-Backend";
-    readonly revision: "120902c12b25ac2ef5f54fa3340a94fb3a5206b3";
+    readonly revision: "12c7310b71538ed81add95d7d2935c8cf12792bd";
     readonly version: "5.0.0";
     readonly source: "service/unssvr/internal/domain/unsv2/contract_generated.go#ContractJSON";
-    readonly cloudRevision: "120902c12b25ac2ef5f54fa3340a94fb3a5206b3";
-    readonly cloudContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+collection-namespace/1+http-acquisition/2+http-source-role/1+http-source-request/1+app-collection/2+collection-ownership/1+metadata/1+app-context/2+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+api-surface/2+source-stream-single-model+app-data/2+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
+    readonly cloudRevision: "12c7310b71538ed81add95d7d2935c8cf12792bd";
+    readonly cloudContractRevision: "cloud-source-impact/2+source-vendor/2+app-create-capability/1+data/3+record-reads/1+stream-receipt/1+collection-namespace/1+http-acquisition/2+http-source-role/1+http-source-request/1+app-collection/2+collection-ownership/1+metadata/1+app-context/3+collection-ttl/1+error-model/1+crud-consolidation/1+record-insert-return/1+lifecycle-consolidation/1+api-surface/2+source-stream-single-model+app-data/2+hosted-control/1+source-bindings/1+record-notifications/1+record-delete-samples/1+stream-history/1+app-collections/1+http-in/1+app-resource-access/2+stream-control-probe-retirement/1+http-push-retirement/1";
     readonly resolvedCloudContract: true;
     readonly enterpriseBase: {
         readonly repository: "FREEZONEX/Tier0-Enterprise-New";
@@ -9851,16 +9856,23 @@ export declare const UNS_V2_CONTRACT_PROVENANCE: {
         readonly version: "4.0.0";
         readonly source: "backend/internal/domain/unsv2/contract_generated.go";
         readonly note: "Reviewed Enterprise wire contract imported as editable Cloud contract source; regenerate all adapters with scripts/generate-uns-v2.mjs.";
+        readonly cloudSourceCatalog: {
+            readonly generator: "go run ./service/unssvr/tools/sourcecatalog -output share/unscontract/source-protocols.json";
+            readonly modelSource: "service/unssvr/internal/domain/sourcestream/SourceEnvelopeSchema + SourceAcquisitionSchema";
+            readonly modelRevision: "aec9a778bf8bc7a153c26c40715ad85d670bdb06";
+            readonly managedServerRegistryRevision: "4fb470c03";
+            readonly capability: "x-tier0-opcua-server: static available=false; online availability is workspace/registry authoritative";
+        };
     };
-    readonly sourceDerivedContractSHA256: "27a23f7db02f2f0681d1a66565be3b6e478f07b3cd1a9c9e1e880bd304106614";
+    readonly sourceDerivedContractSHA256: "6758eff26d4d5bb93039014385ed927525364348934bddb4060d1bf88c0d6d2d";
     readonly hashes: {
-        readonly contract: "27a23f7db02f2f0681d1a66565be3b6e478f07b3cd1a9c9e1e880bd304106614";
-        readonly cloudSupport: "23e5680ec2c4f645067789e366d783961817bbb7438a3aa98099fd5314e6a35f";
-        readonly manifest: "ad9c0e97585be774e72c4335e801437c3dfd9187f0ce0c49e566aa98d4f79547";
-        readonly provenance: "5b8626103092682bb393c2d94142b410e293b1fcfdf057d65d91e6e4c5d66ac0";
-        readonly registry: "62dd03cf1240dddf40dfb663c1f4e742d25d8b1d78f349927a2120656c7ed24d";
+        readonly contract: "6758eff26d4d5bb93039014385ed927525364348934bddb4060d1bf88c0d6d2d";
+        readonly cloudSupport: "2e42aec85964f78165bfe2dbc9145d03796308560179824a6c2546a5509a05c8";
+        readonly manifest: "39eacfb569b7131c6a98e37f37672b6f519a40e90bbc42e1edcc0b0b06f1ee7e";
+        readonly provenance: "f20e85627662225f1b210faa34f3bf11bdbdf6b3bfac4527d5cae75ac91e320b";
+        readonly registry: "16da392126338bc0dc92eb28ed0f0472794ec733a964c6e31a0aed400a10c9ac";
     };
     readonly publicOperationCount: 85;
     readonly streamOperationCount: 1;
-    readonly manifestOperationCount: 97;
+    readonly manifestOperationCount: 98;
 };