@tier0/sdk-v2 0.0.0-stage → 0.1.0

package/dist/esm/uns-v2/index.d.ts

@@ -0,0 +1,5 @@
+export * from './generated.js';
+export * from './client.js';
+export { UnsV2RawNumber } from './codec.js';
+export { createUnsDataClient } from './data-client.js';
+export type { UnsDataClient, UnsDataClientConfig, UnsDataOperationName } from './data-client.js';

package/dist/esm/uns-v2/index.js

@@ -0,0 +1,5 @@
+export * from './generated.js';
+export * from './client.js';
+export { UnsV2RawNumber } from './codec.js';
+export { createUnsDataClient } from './data-client.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/uns-v2/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/uns-v2/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["export * from './generated.js';\r\nexport * from './client.js';\r\nexport { UnsV2RawNumber } from './codec.js';\r\nexport { createUnsDataClient } from './data-client.js';\r\nexport type { UnsDataClient, UnsDataClientConfig, UnsDataOperationName } from './data-client.js';\r\n"]}

package/dist/esm/vue.d.ts

@@ -0,0 +1,9 @@
+import type { Tier0Client } from './client.js';
+/** Explicit execution, with latest-result wins and no automatic mutation replay. */
+export declare function useTier0Request<T, Variables>(client: Tier0Client, request: (client: Tier0Client, variables: Variables, signal: AbortSignal) => Promise<T>): {
+    data: import("vue").ShallowRef<T | undefined, T | undefined>;
+    error: import("vue").ShallowRef<unknown, unknown>;
+    loading: import("vue").ShallowRef<boolean, boolean>;
+    execute: (variables: Variables) => Promise<T>;
+    cancel: () => void;
+};

package/dist/esm/vue.js

@@ -0,0 +1,36 @@
+import { shallowRef, onScopeDispose, getCurrentScope } from 'vue';
+/** Explicit execution, with latest-result wins and no automatic mutation replay. */
+export function useTier0Request(client, request) {
+    const data = shallowRef();
+    const error = shallowRef();
+    const loading = shallowRef(false);
+    let controller;
+    let generation = 0;
+    const cancel = () => { generation++; controller?.abort(); loading.value = false; };
+    if (getCurrentScope())
+        onScopeDispose(cancel);
+    async function execute(variables) {
+        controller?.abort();
+        const own = ++generation;
+        const current = controller = new AbortController();
+        loading.value = true;
+        error.value = undefined;
+        try {
+            const result = await request(client, variables, current.signal);
+            if (own === generation)
+                data.value = result;
+            return result;
+        }
+        catch (failure) {
+            if (own === generation)
+                error.value = failure;
+            throw failure;
+        }
+        finally {
+            if (own === generation)
+                loading.value = false;
+        }
+    }
+    return { data, error, loading, execute, cancel };
+}
+//# sourceMappingURL=vue.js.map

package/dist/esm/vue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vue.js","sourceRoot":"","sources":["../../src/vue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,KAAK,CAAC;AAGlE,oFAAoF;AACpF,MAAM,UAAU,eAAe,CAAe,MAAmB,EAAE,OAAuF;IACxJ,MAAM,IAAI,GAAG,UAAU,EAAK,CAAC;IAC7B,MAAM,KAAK,GAAG,UAAU,EAAW,CAAC;IACpC,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,UAAuC,CAAC;IAC5C,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,MAAM,GAAG,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACnF,IAAI,eAAe,EAAE;QAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC9C,KAAK,UAAU,OAAO,CAAC,SAAoB;QACzC,UAAU,EAAE,KAAK,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,EAAE,UAAU,CAAC;QACzB,MAAM,OAAO,GAAG,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACnD,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;QACrB,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;QACxB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAChE,IAAI,GAAG,KAAK,UAAU;gBAAE,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;YAC5C,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,OAAO,EAAE,CAAC;YACjB,IAAI,GAAG,KAAK,UAAU;gBAAE,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;YAC9C,MAAM,OAAO,CAAC;QAChB,CAAC;gBAAS,CAAC;YAAC,IAAI,GAAG,KAAK,UAAU;gBAAE,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;QAAC,CAAC;IAC9D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACnD,CAAC","sourcesContent":["import { shallowRef, onScopeDispose, getCurrentScope } from 'vue';\nimport type { Tier0Client } from './client.js';\n\n/** Explicit execution, with latest-result wins and no automatic mutation replay. */\nexport function useTier0Request<T, Variables>(client: Tier0Client, request: (client: Tier0Client, variables: Variables, signal: AbortSignal) => Promise<T>) {\n  const data = shallowRef<T>();\n  const error = shallowRef<unknown>();\n  const loading = shallowRef(false);\n  let controller: AbortController | undefined;\n  let generation = 0;\n  const cancel = () => { generation++; controller?.abort(); loading.value = false; };\n  if (getCurrentScope()) onScopeDispose(cancel);\n  async function execute(variables: Variables): Promise<T> {\n    controller?.abort();\n    const own = ++generation;\n    const current = controller = new AbortController();\n    loading.value = true;\n    error.value = undefined;\n    try {\n      const result = await request(client, variables, current.signal);\n      if (own === generation) data.value = result;\n      return result;\n    } catch (failure) {\n      if (own === generation) error.value = failure;\n      throw failure;\n    } finally { if (own === generation) loading.value = false; }\n  }\n  return { data, error, loading, execute, cancel };\n}\n"]}

package/docs/acceptance-2026-10-22.md

@@ -0,0 +1,88 @@
+# SDK v2 安装包与开发环境验收
+
+日期：2026-10-22。包：`@tier0/sdk-v2@0.1.0`。
+
+验收对应 SDK 提交 `5d30d5154354bac94bbbe88402a8303d6c43526d` 的安装包。报告提交时远端已合入其他功能（至 `78f5168`）；下列测试数量和业务结论不覆盖那些新增功能。
+
+结论：安装包和本地自动化通过；多组真实业务操作通过，但不能宣称“所有功能已可用”。追加验收已完成真实站内通知发送、Stream 发布、当前 release 的真实执行、停用及归档。Source 创建预检、Control 权限、Stream 能力查询、Agent 真实用户身份及文件大分片传输仍有阻断或限制。
+
+## 测试对象与方法
+
+- 测试 Workspace：`374897752781296`。网页 `https://dev.tier0.cn`，SDK API Host **`https://api-dev.tier0.cn`**。
+- 使用用户提供的 service Key，先以 `system.whoami()` 验证 Workspace。凭据仅进入测试进程环境，没有写入文件、安装包或 Git。
+- 后端契约固定版本：`1e93620522caa47869d67e9aea1491a8cda71fa5`。未修改后端或部署配置。
+- `npm pack` 后在独立 consumer 中安装 `.tgz`。真实环境脚本从这个 consumer 加载 SDK；Skill 工作流提取的是安装包中的 Markdown 代码。
+- 写入仅针对本次生成的 SDK 验收资源。Source 只做创建预检；追加测试发布了无 Source 绑定、无外部写入的独立 timer Stream，随后停用并归档。经用户指定，向成员 `tier0` 发送了一条“SDK 验收”站内通知。
+
+## 安装包检查
+
+| 检查 | 结果 |
+| --- | --- |
+| 源码行为测试 | 580 / 580，15 个文件 |
+| 安装后行为测试 | 580 / 580，同套断言，导入目标为包内 dist |
+| 全部生成操作路由 | 50 个 v1 + 98 个 v2，每个实际请求本地 HTTP fixture |
+| Skills | 11 个；62 个 TypeScript 示例对源码及包内声明类型检查通过 |
+| 使用形式 | ESM、CommonJS、声明导出、独立包安装、浏览器 bundle 通过 |
+| 调试映射 | JS map 内嵌源码；不再提供指向包外源码的声明 map |
+
+路由 smoke 检查证明方法、路径和基本传输可用，不证明每个业务字段或每种服务端状态已验收。已有测试另外覆盖无损整数、超时/取消、写入结果未知、不自动重试、凭据隔离、对象存储无平台凭据以及 Skill 的主要生命周期。
+
+## 真实环境结果
+
+| 功能 | 结果与范围 |
+| --- | --- |
+| 系统、成员、能力发现 | whoami、info、Workspace 成员列表、capabilities.discover 通过 |
+| Source 查询 | 协议列表、配置列表、原生文档列表通过；读到 7 个现有 Source |
+| Source 创建 | 原生文档 dryRun 返回 HTTP 503 / TEMPORARILY_UNAVAILABLE，消息 `cloud lifecycle service unavailable`；未继续提交创建，因此修改/删除/连接采集未验收 |
+| Stream | 读取原有 9 个 Stream；独立 timer 草稿 CRUD 通过。追加的发布、当前 release 执行完成、停用、归档通过，证据见下文 |
+| Stream runtime capabilities | HTTP 403 / FORBIDDEN，`API key operation not allowed`；不代表所有 Stream 接口都不可用 |
+| UNS 集合与记录 | 创建、读取、修改、删除/归档、恢复和最终清理通过；执行包内 Skill 示例 |
+| UNS 目录与 Topic | 创建、读回、修改、归档、恢复、再次归档通过 |
+| UNS 采样与查询 | 采样追加、历史、最新值、聚合、范围删除及空结果核对；记录 count/distinct 通过 |
+| UNS 并发和事务 | 记录加锁、续租、解锁；事务 dryRun、提交和读回；changes poll 通过 |
+| 文件普通上传 | 上传测试文本、签名 URL、下载内容逐字比对、删除通过 |
+| 文件分片 | 6 MiB、两片测试未完成。初始化和签名 API 返回 200，第一片向 OSS S3 endpoint 的 PUT 在 30 秒和诊断用 60 秒期限内均未完成；错误为 AbortError，尚不能区分网络与服务配置根因。两次未完成会话均已 abort 成功 |
+| MQTT | 使用同一 service Key 连接 `wss://mqtt-dev.tier0.cn:8084/mqtt` 成功，已断开 |
+| Control | discover 返回 HTTP 403 / CONTROL_FORBIDDEN；未调用实际控制设备 |
+| Agent | library/results/canvases 列表通过；当前画布列表为空，未构造虚假 canvasId 测卡片。jobs.list 返回业务码 100012：任务管理需要真实用户身份，内部服务虚拟负责人不能代替 |
+| 通知 | 向用户指定的 `tier0` 成员发送一条 live inbox 通知，channels=[]，无邮件/短信；发送返回 accepted，随后状态查询为 sent。未验证收件人已读 |
+
+Source 的 503 是后端返回的统一生命周期错误。对固定版本代码的检查表明它可包装多种内部失败，因此本报告不把它进一步断言为某个具体服务宕机或数据库故障。SDK 正确抛出了服务端错误。
+
+## 追加验收与修复判断
+
+追加测试仍从已安装的 `.tgz` 加载 SDK，Workspace 不变。只读检查 ACK `tier0-dev-ack`；当时 unssvr、syssvr、gwsvr 镜像 tag 为 `feature-cloud-new-architecture-migration-ab88c067-20261022-204`，对应提交 `ab88c0674f8362780bd685743fe064aa22143e64`。这是部署版本，不能与 SDK 固定契约版本混同。
+
+- 通知：messageId `375221818446704`，收件人 `tier0`，标题“SDK 验收”，查询状态 `sent`，errorCode 为空。只发送一次；sent 是服务端状态，不等同于用户已读。
+- Stream：测试 ID `375222335204848`，activeVersion `375222336562672`，activeRelease `1`。本次 release 的执行 `delivery:375222339446256` 和 `delivery:375222337334768` 均为 `completed`。随后确认 activeRelease=0，再删除归档。首次补测脚本误读 `runs.list`，已修正为契约规定的 `runs.items`，并重新创建隔离流验证；两次测试流均已清理。
+- 保存后的通用脚本再次实跑通过：Stream `375222824547824`，activeVersion `375222826821104`，release `1` 的 `delivery:375222827312624` 为 `completed`，最后停用并归档。脚本语法检查和 `git diff --check` 通过；本次未修改 SDK 运行时代码。
+- 此前通知因未指定收件人而未发送；Stream 发布运行属于上一轮测试覆盖遗漏。能力查询 403 不构成停止测试发布运行接口的理由。
+
+| 阻断 | 已确认事实 | 修复方向与边界 |
+| --- | --- | --- |
+| Source 创建 503 | 当前镜像仍复现；requestId `8b0197c1-3479-4277-ba70-89e131512437`。错误映射将多种内部错误合并为 `cloud lifecycle service unavailable`，现有日志未能将根因关联到此请求 | 服务端在 Source 管理身份刷新、租户解析、凭据绑定预检、事务写入边界增加不含凭据的阶段码和 requestId 关联，再针对确切失败修复。暂不能声称重启、加权限或迁库能解决。未修改部署或数据库 |
+| 大文件分片 PUT 超时 | 追加对照中 1 KiB 的 PUT=200、complete=200；5 MiB 首片仍超过 20 秒。原测试 30/60 秒同样超时；额外把 Blob 转为 Uint8Array 发送，60 秒仍超时。小文件完成后的下载 URL 查询另遇连接错误，文件已删除，大分片会话已 abort | 签名对小分片有效，替换 Blob 发送体未解决。仍需上传路径/OSS 服务端证据定位；仅增大 timeout 不能算修复，须以两片上传、合并及下载 hash 比对为验收 |
+| Control 与 runtime capabilities 403 | 当前 Key 只有 UNS/Source/Stream scope；部署代码 `apiKeyUnsV2ControlScopes` 将能力查询也放在 Control 权限分支，且要求非空控制码 grants | 为测试对象配置最小 `control.read`/`control.execute` scope 和具体控制码授权；Stream manage 或 owner 身份不能替代。若产品要求普通 Stream 用户查询能力，需要后端单独调整该查询的授权规则；不得绕过真实 Control 调用授权 |
+| Agent jobs 身份限制 | 当前是 service Key；任务管理明确要求真实用户 | 使用有任务权限的真实成员 personal Key 或该功能支持的会话身份。扩大 service Key scope 不能把它变成真实用户 |
+
+ACK 日志另有 `UNS control metadata requires explicit migration before startup`，但尚未证实属于本 Workspace 或此次 Source 请求，不能把该日志当成本次 503 的根因。部署、重启、授权变更和数据库迁移均未执行。
+
+## 未验收范围
+
+不能从上述通过项推断 Source 探测/启用/真实采集、Source 绑定 Stream 的端到端数据链、Stream 回滚、MQTT 发布订阅消息闭环及凭证创建撤销、通知已读、邮件/短信通道、Control 执行、Agent 任务/卡片/即时分析写入已经可用。React/Vue 完成类型和打包检查，未在实际应用页面中进行组件交互验收。
+
+全量业务验收需要先解决 Source 和分片阻断，并提供相应功能允许的身份、权限和测试对象。权限失败不能通过 SDK 绕过；当前 service Key 不应被当作真实用户身份。
+
+## 清理与复现
+
+最终以 SDK 按测试前缀检索，活跃 Source、Stream、集合、目录、Topic 均为 0。创建过的业务资源使用平台归档语义清理，归档历史保留；测试文本对象已删除，未完成分片会话已终止。
+
+复现入口：
+
+- `npm run check`：自动打包、安装并执行包内行为测试，不触及线上。
+- `scripts/check-live-readonly.mjs`：仅查询，检查 Workspace 绑定，报告不保存原始业务响应。
+- `scripts/check-live-workflows.mjs`：需显式 `--write-test-fixtures`，可用 `TIER0_TEST_DOMAINS=uns,extended` 选择扩展 UNS 验收。
+- `scripts/check-live-transports.mjs`：普通 API 鉴权、分片传输和 MQTT 连接诊断；只记录状态、耗时与存储 origin，不记录签名查询字符串。
+- `scripts/check-live-stream-runtime.mjs <consumer> <workspace> <report> --write-test-fixtures`：从安装包创建独立 timer 流，发布后按当前 release 检查 completed 记录，最后停用并归档；需进程环境中的 API Host 和 Key。
+
+本次安装包用于本地分发与验收，未发布到 npm。

package/package.json

@@ -1,6 +1,244 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FREEZONEX/Tier0-sdk-v2.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "docs/acceptance-2026-10-22.md",
+    "LICENSE",
+    "NOTICE.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./openapi": {
+      "import": {
+        "types": "./dist/esm/openapi/index.d.ts",
+        "default": "./dist/esm/openapi/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/openapi/index.d.ts",
+        "default": "./dist/cjs/openapi/index.js"
+      }
+    },
+    "./uns": {
+      "import": {
+        "types": "./dist/esm/uns-v2/index.d.ts",
+        "default": "./dist/esm/uns-v2/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/uns-v2/index.d.ts",
+        "default": "./dist/cjs/uns-v2/index.js"
+      }
+    },
+    "./source": {
+      "import": { "types": "./dist/esm/source.d.ts", "default": "./dist/esm/source.js" },
+      "require": { "types": "./dist/cjs/source.d.ts", "default": "./dist/cjs/source.js" }
+    },
+    "./stream": {
+      "import": { "types": "./dist/esm/stream.d.ts", "default": "./dist/esm/stream.js" },
+      "require": { "types": "./dist/cjs/stream.d.ts", "default": "./dist/cjs/stream.js" }
+    },
+    "./files": {
+      "import": {
+        "types": "./dist/esm/files.d.ts",
+        "default": "./dist/esm/files.js"
+      },
+      "require": {
+        "types": "./dist/cjs/files.d.ts",
+        "default": "./dist/cjs/files.js"
+      }
+    },
+    "./mq": {
+      "import": {
+        "types": "./dist/esm/mq/index.d.ts",
+        "default": "./dist/esm/mq/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/mq/index.d.ts",
+        "default": "./dist/cjs/mq/index.js"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/esm/cloud-server.d.ts",
+        "default": "./dist/esm/cloud-server.js"
+      },
+      "require": {
+        "types": "./dist/cjs/cloud-server.d.ts",
+        "default": "./dist/cjs/cloud-server.js"
+      }
+    },
+    "./data": {
+      "import": {
+        "types": "./dist/esm/data/index.d.ts",
+        "default": "./dist/esm/data/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/data/index.d.ts",
+        "default": "./dist/cjs/data/index.js"
+      }
+    },
+    "./data/define": {
+      "browser": {
+        "types": "./dist/esm/data/declarations.d.ts",
+        "default": "./dist/esm/data/declarations.js"
+      },
+      "import": {
+        "types": "./dist/esm/data/declarations.d.ts",
+        "default": "./dist/esm/data/declarations.js"
+      },
+      "require": {
+        "types": "./dist/cjs/data/declarations.d.ts",
+        "default": "./dist/cjs/data/declarations.js"
+      }
+    },
+    "./react": {
+      "import": {
+        "types": "./dist/esm/react.d.ts",
+        "default": "./dist/esm/react.js"
+      },
+      "require": {
+        "types": "./dist/cjs/react.d.ts",
+        "default": "./dist/cjs/react.js"
+      }
+    },
+    "./vue": {
+      "import": {
+        "types": "./dist/esm/vue.d.ts",
+        "default": "./dist/esm/vue.js"
+      },
+      "require": {
+        "types": "./dist/cjs/vue.d.ts",
+        "default": "./dist/cjs/vue.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "sync:contracts": "node scripts/sync-contracts.mjs",
+    "generate": "node scripts/generate-openapi.mjs && node scripts/generate-uns-v2.mjs",
+    "check:contracts": "node scripts/check-contracts.mjs && node scripts/generate-openapi.mjs --check && node scripts/generate-uns-v2.mjs --check",
+    "check:skills": "node scripts/check-skills.mjs && node scripts/check-skill-examples.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.tests.json",
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "check": "npm run check:contracts && npm run check:skills && npm run typecheck && npm test && npm run build && node scripts/check-package.mjs",
+    "prepack": "npm run check:contracts && npm run check:skills && npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "dependencies": {
+    "mqtt": "^5.3.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": ">=18.0.0",
+    "vue": "^3.4.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^19.0.0",
+    "vue": "^3.4.0",
+    "typescript": "~5.9.3",
+    "openapi-typescript": "^7.0.0",
+    "vitest": "^4.1.7",
+    "esbuild": "^0.25.0",
+    "yaml": "^2.8.0",
+    "zod": "^4.0.0"
+  },
+  "agents": {
+    "skills": [
+      {
+        "name": "tier0-sdk-v2-source",
+        "path": "./skills/tier0-sdk-v2-source"
+      },
+      {
+        "name": "tier0-sdk-v2-stream",
+        "path": "./skills/tier0-sdk-v2-stream"
+      },
+      {
+        "name": "tier0-sdk-v2",
+        "path": "./skills/tier0-sdk-v2"
+      },
+      {
+        "name": "tier0-sdk-v2-uns",
+        "path": "./skills/tier0-sdk-v2-uns"
+      },
+      {
+        "name": "tier0-sdk-v2-files",
+        "path": "./skills/tier0-sdk-v2-files"
+      },
+      {
+        "name": "tier0-sdk-v2-notifications",
+        "path": "./skills/tier0-sdk-v2-notifications"
+      },
+      {
+        "name": "tier0-sdk-v2-mq",
+        "path": "./skills/tier0-sdk-v2-mq"
+      },
+      {
+        "name": "tier0-sdk-v2-members",
+        "path": "./skills/tier0-sdk-v2-members"
+      },
+      {
+        "name": "tier0-sdk-v2-system",
+        "path": "./skills/tier0-sdk-v2-system"
+      },
+      {
+        "name": "tier0-sdk-v2-controls",
+        "path": "./skills/tier0-sdk-v2-controls"
+      },
+      {
+        "name": "tier0-sdk-v2-agent",
+        "path": "./skills/tier0-sdk-v2-agent"
+      },
+      {
+        "name": "tier0-sdk-v2-data",
+        "path": "./skills/tier0-sdk-v2-data"
+      }
+    ]
+  }
+}

package/skills/tier0-sdk-v2/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: tier0-sdk-v2
+description: 使用 @tier0/sdk-v2 开发或迁移 Tier0 云端 TypeScript/JavaScript 应用，按 Source、Stream、UNS、通知与系统能力选择入口，处理配置、身份和框架集成。
+---
+
+# Tier0 SDK v2 应用集成
+
+面向应用代码编写；运行时为 Node.js 20.19+。独立包 `@tier0/sdk-v2` 的当前源码版本为 0.1.0，是否可从 npm 安装须检查实际发布状态；未发布时安装仓库构建的 tarball。不要改回旧包或旧 Flow API。
+
+## 选择业务入口
+
+| 用户要做什么 | SDK 入口 | 深入说明 |
+| --- | --- | --- |
+| 连接外部系统、维护采集源、检查连接和影响范围 | `client.source` | [Source](../tier0-sdk-v2-source/SKILL.md) |
+| 编写处理程序、配置源绑定、校验和发布、查运行记录 | `client.stream` | [Stream](../tier0-sdk-v2-stream/SKILL.md) |
+| 集合、目录、Topic、业务记录、历史采样与事务 | `client.uns` | [UNS](../tier0-sdk-v2-uns/SKILL.md) |
+| App 自有业务数据：声明集合、Mongo 风格读写与事务 | `@tier0/sdk-v2/data` | [App 数据](../tier0-sdk-v2-data/SKILL.md) |
+| 站内信、Web/Desktop 提醒、手机推送 | `client.notifications` | [通知](../tier0-sdk-v2-notifications/SKILL.md) |
+| 当前凭证、平台信息、功能是否就绪 | `client.system`、`client.capabilities` | [系统](../tier0-sdk-v2-system/SKILL.md) |
+| 附件、头像、导入导出、生成报告 | `client.files` | [文件](../tier0-sdk-v2-files/SKILL.md) |
+| 实时主题订阅/发布 | `@tier0/sdk-v2/mq`、`client.mqttAuth` | [MQTT](../tier0-sdk-v2-mq/SKILL.md) |
+| Workspace 收件人/成员检索、App 可用成员 | `client.members` | [成员](../tier0-sdk-v2-members/SKILL.md) |
+| 调用已发布的 Control | `client.controls` | [Controls](../tier0-sdk-v2-controls/SKILL.md) |
+| Agent 作业、运行、分析结果和卡片 | `client.agent` | [Agent](../tier0-sdk-v2-agent/SKILL.md) |
+
+每个领域 Skill 可单独使用，无需先加载本文件。Source → Stream → UNS 是接入、处理与数据存储三个领域；不是要求每个数据读取场景都创建一套流水线。通知和系统能力独立于这条链路。
+
+## 初始化与身份
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+// 服务端注入 TIER0_API_HOST / TIER0_API_KEY。
+export const client = createClient({ transportTimeoutMs: 30_000 });
+export async function inspectConnection() {
+  return client.system.info();
+}
+```
+
+也可传 `apiHost`、`apiKey` 或 `getApiHost` / `getApiKey` 回调。API Key 留在服务端；不要生成 `VITE_*KEY` 或让页面携带 App Key。浏览器通过自己的服务端接口访问平台。
+
+不同身份使用独立实例。含员工数据委托时，每个入站请求新建实例，使用受信 App Gateway 提供的 `unsV2AppDataSubject`；它不是用户 ID，也不是 App 请求验签断言。不要从请求 JSON 拼造委托。身份验签流程见 [身份与框架集成](references/integration.md)。
+
+## 返回值与错误
+
+| 入口 | 成功值 | 失败类型 |
+| --- | --- | --- |
+| Source、Stream、UNS | 完整 `{ code, msg, requestId, data }` | `UnsV2Error` / `UnsV2OutcomeUnknownError` |
+| 普通 v1，如 system、members、agent、mqttAuth | 解包后的 `data` | `ApiError` / `TransportError` |
+| notifications | 直接对象，如 `messageId`、`status` | `ApiError` |
+| controls、capabilities | 专属响应对象 | `ControlError` / `CapabilityError` |
+
+方法存在不等于目标环境已部署或当前 Key 有权限。整数可能为 `bigint`；UNS 任意 JSON 中还可能含 `UnsV2RawNumber`。不要将标识符强制转为 Number；给浏览器返回数据时显式定义精确数字的序列化格式。
+
+HTTP 不自动重试。带 `outcomeUnknown` 的失败应先对账，保留原意图键；取消请求不代表服务端撤销。Source/Stream 仍使用底层 UNS v2 契约，所以错误类名保留 UNS，不代表它们仍属于数据入口。
+
+## 从首版入口迁移
+
+- `client.uns.sourceList(body)` → `client.source.list(body)`。
+- `client.uns.sourceDocumentGet(body)` → `client.source.documents.get(body)`。
+- `client.uns.streamProgramDeploy(body)` → `client.stream.programs.deploy(body)`。
+- `client.uns.streamDocumentValidate(body)` → `client.stream.documents.validate(body)`。
+- `client.uns.recordFind(body)` 保持不变；Control 使用 `client.controls.use({ code })`。
+- 低层 `createUnsV2Client` 保留完整生成契约，供契约工具使用；业务主入口不再把 Source/Stream/Control 混入 `client.uns`。
+
+React/Vue 示例与验签见 [集成参考](references/integration.md)。完成接入时验证目标入口、真实身份、响应解包和错误分支；SDK 本地测试通过不代表环境联调完成。

package/skills/tier0-sdk-v2/references/integration.md

@@ -0,0 +1,72 @@
+# 身份与框架集成
+
+仅在接入服务端身份或 React/Vue 时阅读本文件。基本分域调用见入口 Skill。
+
+## 网关身份验签
+
+使用服务端入口，公钥与期望 appID/workspaceID 来自固定服务端配置，不能从请求的 JWK/URL 取钥。保留原始请求字节与路径+query；JSON 解析、重编码或路径归一化后再验签会破坏绑定。
+
+```ts
+import {
+  createCloudAppRequestVerifier,
+  type CloudAppIdentityAuthority,
+  type CloudAppIdentityRequest,
+} from '@tier0/sdk-v2/server';
+
+export function authenticateRequest(authority: CloudAppIdentityAuthority, request: CloudAppIdentityRequest) {
+  const verify = createCloudAppRequestVerifier(authority);
+  return verify(request);
+}
+```
+
+输入 assertion 对应平台约定的 APP_REQUEST_IDENTITY_HEADER；method、requestURI、body 必须是网关签名对应的值。成功只证明该请求来源与员工身份，业务授权仍单独检查。失败拒绝当前请求，不从未验证 claims 兜底建立身份。
+
+App 请求断言与 UNS 员工数据委托是不同的 audience。只有受信接入层获得真实 App-Data-Subject 后，才能为本次请求创建客户端：
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export function clientForTrustedGatewayRequest(apiHost: string, apiKey: string, trustedDataSubject: string) {
+  return createClient({ apiHost, apiKey, unsV2AppDataSubject: trustedDataSubject });
+}
+```
+
+SDK 仅检查委托的紧凑格式，不自行信任/验证其 claims。不要直接转发公开入口任意同名 header，部署边界必须保证它来自可信网关。不要跨员工复用这个实例或令牌。
+
+## React
+
+需要 React 与 TanStack Query、外层 QueryClientProvider。稳定持有 client；内部缓存按 client 实例隔离。含服务端 App Key 的代码不能为了使用 hook 被搬到浏览器。
+
+```ts
+import type { Tier0Client } from '@tier0/sdk-v2';
+import { useTier0Query, useTier0Mutation } from '@tier0/sdk-v2/react';
+
+export function useRecords(client: Tier0Client, collectionId: string) {
+  return useTier0Query(client, ['records', collectionId], (sdk, signal) =>
+    sdk.uns.recordFind({ collectionId, limit: 20 }, { signal }));
+}
+export function useNotification(client: Tier0Client) {
+  type Message = Parameters<Tier0Client['notifications']['send']>[0];
+  return useTier0Mutation(client, (sdk, body: Message) => sdk.notifications.send(body));
+}
+```
+
+查询 key 包含影响结果的参数。读操作用 query，写操作用 mutation；默认不重试。实际浏览器应用若没有可安全直连平台的用户鉴权，使用自己的服务端 API 与普通框架请求库，不强行把平台 client 放入页面。
+
+## Vue
+
+```ts
+import type { Tier0Client } from '@tier0/sdk-v2';
+import { useTier0Request } from '@tier0/sdk-v2/vue';
+
+export function useRecords(client: Tier0Client) {
+  return useTier0Request(client, (sdk, collectionId: string, signal) =>
+    sdk.uns.recordFind({ collectionId, limit: 20 }, { signal }));
+}
+```
+
+在组件 setup 中调用，随后 execute(collectionId) 显式发起；data/error/loading 为 ref，cancel 可取消当前等待。后发请求的结果优先，scope 销毁时会取消。写操作的取消不意味着撤回服务端副作用。
+
+## 联调证据
+
+本 SDK 验签契约沿用已记录的上游 App 网关契约，须与目标环境实际注入的 header/公钥/受众对照。契约生成、类型与本地测试证明包内部一致，不替代环境联调。确认身份、权限与字段返回后再切换真实业务流量。

package/skills/tier0-sdk-v2-agent/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: tier0-sdk-v2-agent
+description: 使用 @tier0/sdk-v2 的 client.agent 查询和管理 Agent 作业、运行记录、分析、结果、卡片、资料库与关系，处理调度副作用和并发编辑。
+---
+
+# Agent 作业与结果
+
+Agent 是平台应用能力，区别于 Stream 数据处理程序。使用服务端 client.agent；本领域普通 v1 响应已解包，直接读取 list/job/run/result 等字段。
+
+## 入口选择
+
+| 入口 | 方法与用途 |
+| --- | --- |
+| jobs | list/get/create/update/pause/resume/trigger/delete，管理任务与调度 |
+| jobRuns | list/get，查看具体执行 |
+| analyses | dispatch/get，分发分析和读取结果 |
+| results | create/get/list/pin，保存分析产物并固定到画布 |
+| cards | list/get/update/delete，操作画布卡片 |
+| canvases | list，查找画布 |
+| library | list/get/create/update/delete，复用卡片定义 |
+| nodes | searchSemantic/indexSync，语义搜索与索引同步 |
+| relations | list/teach，读取和写入数据关系 |
+
+dispatch、trigger、indexSync、teach 都有副作用，不能在普通查询流程中悄悄执行。
+
+## 查询作业与运行
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function listJobs(page = 1) {
+  return createClient().agent.jobs.list({ page, size: 20 });
+}
+export async function inspectJob(jobId: string) {
+  const client = createClient();
+  const job = await client.agent.jobs.get({ jobId });
+  const runs = await client.agent.jobRuns.list({ jobId, page: 1, size: 20 });
+  return { job: job.job, runs: runs.list, total: runs.total };
+}
+export async function inspectJobRun(jobId: string, jobRunId: string) {
+  const response = await createClient().agent.jobRuns.get({ jobId, jobRunId });
+  return response.run;
+}
+```
+
+作业 ID 与运行 ID 不同；不能拿 resultId 去查 jobRuns。分页接口一般要求 page/size，按返回 total/list 继续。status/dispatchState 按服务端值处理，收到派发回执不等于作业完成。
+
+## 创建与调度
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+type CreateJob = Parameters<Tier0Client['agent']['jobs']['create']>[0];
+export async function createConfiguredJob(input: CreateJob) {
+  // input 的调度和 task 内容来自当前平台认可的业务配置。
+  return createClient().agent.jobs.create(input);
+}
+export async function triggerExistingJob(jobId: string) {
+  return createClient().agent.jobs.trigger({ jobId });
+}
+```
+
+创建必填 name/scheduleKind/task/sourceType/sessionId。scheduleKind 的可用值、task 对象和时间单位须来自实际业务契约，Swagger 中的 string/unknown 不意味着可以任意填写。pause/resume/trigger 是不同意图；不要用“暂停后再恢复”来替代查询。
+
+jobs.update 的 notifyEnabled：省略保留原通知，1 要求提供 notify，2 关闭通知且不带 notify。没有通用作业幂等键字段时，不得额外塞 idempotencyKey；不确定的 trigger 先查运行列表对账。
+
+## 保存结果与并发编辑
+
+result.create 的 operationId 由调用方持有；保存超时后可用 `results.get({ operationId })` 查回，不能再创建新 operationId 重复保存。get 按 resultId 或 operationId 二选一。
+
+cards.update 要带读取时的完整 expectedCardSpec；library.update 要带完整 expectedItem 快照。409 表示内容已变化，应重新读取并合并用户意图，不能自动覆盖。具体示例见 [结果与卡片编辑](references/results.md)。
+
+结果附件/图片使用 [文件 Skill](../tier0-sdk-v2-files/SKILL.md) 的持久化 filePath，不保存签名 URL 作为长期资源。失败保留 ApiError.status/code/errorCode；写入 outcomeUnknown 时先查询对应资源，不自动重发。