@tier0/sdk-v2 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",

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

@@ -5,7 +5,9 @@ description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App
 
 # App 数据层
 
-`@tier0/sdk-v2/data` 是 App 自有业务数据的服务端入口：用 `defineCollection` 声明集合，`createDataClient` 在首次访问时一次性 ensure 全部声明，然后用 Mongo 驱动风格的集合句柄读写 UNS 记录。没有 SQL、ORM、连接串或迁移步骤；Preview 与部署后的 App 共用同一批集合和记录。
+`@tier0/sdk-v2/data` 是 App 业务数据的服务端入口：用 `defineCollection` 声明集合，`createDataClient` 在首次访问时一次性 ensure 全部声明，然后用 Mongo 驱动风格的集合句柄读写 UNS 记录。没有 SQL、ORM、连接串或迁移步骤；Preview 与部署后的 App 共用同一批集合和记录。
+
+这里创建的集合以 `ownerAppId` 标识唯一所属 App。使用已有或其他 App 共享的集合时，用 `data.collection({ collectionId })` 获取句柄；可选 `schema` 仅做本地写入校验，不创建或修改集合。已有 ID 引用同样用于 `queryBatch`、`transact` 和 `subscribe`，不放入 `createDataClient` 的 `collections` 声明数组，不执行 ensure 或写种子。无需服务端 alias，仍须当前 App 已有相应集合授权；SDK 不授予权限，复用不改变所属关系。底层 [UNS](../tier0-sdk-v2-uns/SKILL.md) 的记录接口仍可直接按 ID 使用。
 
 数据读写只在服务端代码（业务 service）里用 `@tier0/sdk-v2/data`：该入口依赖 Node 内置模块，浏览器打包会直接失败。组件和 route 的客户端代码只能从 `@tier0/sdk-v2/data/define` 取集合声明和类型（`defineCollection`、`Doc`、`NewDoc` 等），它不加载数据运行时，可以进浏览器包。需要 `zod` 4。底层调用 SDK 生成的 UNS 操作（`appCollectionsEnsure`、`recordFind`、`recordTransactionExecute` 等），凭证读取平台注入的 TIER0_API_HOST / TIER0_API_KEY。
 

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/modeling.md

@@ -4,6 +4,22 @@
 
 `name` 是必填的业务名称，界面直接展示，例如“生产工单”；1–63 个 Unicode 字符，无首尾空白，不含 `/` 或空字符。`alias` 是独立、稳定的程序标识，例如 `production_orders`，改业务名称不改 alias 或集合 ID。名称应表达实际用途，语言遵循用户偏好和已有业务术语，不附加无业务含义的随机串、时间戳或 ID。没有 displayName，也不从 alias 回退生成名称。ensure 只在首次创建时写入 name；命中已有 alias 时保留用户当前名称，显式改名走 MCP 元数据更新。
 
+已有集合直接引用实际 ID，不需要 alias、name 或注册到声明数组；只使用已有集合时可调用 `createDataClient({})`。可选 `schema` 沿用数据层的本地写入校验规则；省略时由服务端验证存储 schema。ID 引用不会 ensure、写种子、改变 owner 或自动补授权，被删或撤权时直接报告错误。
+
+```ts
+import { createDataClient } from '@tier0/sdk-v2/data';
+
+const data = createDataClient({});
+const devices = { collectionId: 'existing-device-collection-id' };
+const handle = data.collection<{ code: string }>(devices);
+const rows = await handle.find({}).toArray();
+const counts = await data.queryBatch({ devices: handle.query.count() });
+await data.transact([{ opId: 'read-device', action: 'record.read', collection: devices, id: 'device-1' }]);
+// 订阅同样使用 ID 引用；事件的 collection 字段为该 ID。
+const changes = data.subscribe({ collections: [devices] });
+void [rows, counts, changes];
+```
+
 ```ts
 import { z } from 'zod';
 import { defineCollection, type Doc } from '@tier0/sdk-v2/data/define';

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

@@ -21,17 +21,14 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 
 ## 找到正确数据上下文
 
-托管 App 使用 dataAppContext，按业务 alias 精确选择授权集合；它同时给出每个集合的 revision、索引就绪状态（indexStatus）、TTL 和平台限额（limits）。App 凭证不能调用 metadataFind/FindOne、async 模式与 jobs 查询；Workspace 集成（会话、personal / agent Key）用 dataDiscover/metadataFind，不强制 App 上下文。通用元数据管理写入不向 App 凭证开放。App 自有业务数据优先用 [App 数据层](../tier0-sdk-v2-data/SKILL.md)（`@tier0/sdk-v2/data`），变更订阅只在那里提供（`data.subscribe`）。
+托管 App 从配置或 dataAppContext 取得实际 collectionId；alias 是可选的查找便利。dataAppContext 同时给出授权、revision、索引就绪状态（indexStatus）、TTL 和平台限额（limits）。已有或共享集合直接用 collectionId 调用记录接口，无需先 ensure 或配置服务端 alias；App Key 必须已有该集合及操作的授权，不以 Workspace 权限替代 App 授权。App 凭证不能调用 metadataFind/FindOne、async 模式与 jobs 查询；Workspace 集成（会话、personal / agent Key）用 dataDiscover/metadataFind，不强制 App 上下文。通用元数据管理写入不向 App 凭证开放。App 业务数据可用 [App 数据层](../tier0-sdk-v2-data/SKILL.md)（`@tier0/sdk-v2/data`，已有集合用 `data.collection({ collectionId })`），变更订阅只在那里提供（`data.subscribe`）。
 
 ```ts
 import { createClient } from '@tier0/sdk-v2';
 
-export async function findAppCollection(alias: string) {
+export async function readAppRecords(collectionId: string) {
   const client = createClient();
-  const context = await client.uns.dataAppContext({});
-  const collection = context.data.collections.find(item => item.alias === alias);
-  if (!collection) throw new Error('当前 App 未获得目标集合授权');
-  return client.uns.collectionDescribe({ collectionId: collection.collectionId });
+  return client.uns.recordFind({ collectionId, limit: 20 });
 }
 ```