@tier0/sdk-v2 0.9.4 → 0.9.5

package/README.md

@@ -20,13 +20,13 @@ Collection 声明必须同时提供业务名称 `name`（例如「生产工单
 
 ## 安装与初始化
 
-维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。本分支的功能应使用检查通过的 `tier0-sdk-v2-0.9.4.tgz` 在业务项目中验证：
+维护者发布前在本仓库运行 `npm ci`、`npm run check`，并验证生成的 `.tgz`。本分支的功能应使用检查通过的 `tier0-sdk-v2-0.9.5.tgz` 在业务项目中验证：
 
 ```sh
-npm install /path/to/tier0-sdk-v2-0.9.4.tgz
+npm install /path/to/tier0-sdk-v2-0.9.5.tgz
 ```
 
-`0.9.4` 正式发布后再使用 `npm install @tier0/sdk-v2@0.9.4`。发布前，npm 的既有版本和 `next` 标签不代表本分支的完整功能。
+`0.9.5` 正式发布后再使用 `npm install @tier0/sdk-v2@0.9.5`。发布前，npm 的既有版本和 `next` 标签不代表本分支的完整功能。
 
 ```ts
 import { createClient } from '@tier0/sdk-v2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "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,6 +5,8 @@ description: 使用 @tier0/sdk-v2/data 在 App 服务端声明并读写本 App
 
 # App 数据层
 
+工业场景创建数据前，先按[工业命名空间指导](../tier0-sdk-v2-uns/references/namespace.md)查找并复用已有 ISA-95 目录，只创建业务需要且缺失的层级。`defineCollection` / ensure 不接收 `parentId`，新集合默认放入 App 专属目录；需要指定工业目录时，由 Agent 在构建期用现有元数据接口创建并通过 `data.parentId` 放置，运行时按已有集合 ID 访问。
+
 `@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 使用。
@@ -56,7 +58,7 @@ export async function releasedOrders(): Promise<WorkOrder[]> {
 
 ## 核心约束
 
-1. 声明文件只从 `@tier0/sdk-v2/data/define` 导入，客户端代码可以安全引用它；全部集合在一个 `collections` 列表里声明（每个 App 最多 64 个），只建一个进程级 client；不要手动 ensure、不要在 import 时访问数据、不要自建“已初始化”标记。
+1. 声明文件只从 `@tier0/sdk-v2/data/define` 导入，客户端代码可以安全引用它；由 ensure 管理的自有集合放在一个 `collections` 列表里（每个 App 最多 64 个），只建一个进程级 client；不要手动 ensure、不要在 import 时访问数据、不要自建“已初始化”标记。
 2. 集合 Schema 是存储 Schema：只能用可存储的 Zod 子集，输入规则（格式、长度、默认值、transform）放在 API 入参 Schema。
    新建数值字段明确选择 int（integer + int32）、float 或 double（number + 对应 format）；普通小数选 double，嵌套对象和数组元素同样处理。SDK 会为未标注的 integer/number 补齐 int32/double；直接 MCP 请求必须自行提供 format。
 3. 写入前按声明严格校验，未知字段、类型错误、未声明的更新路径直接抛 `ZodError`；读取不做严格解析，旧版本写入的字段、新枚举值或缺字段都可能出现。

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

@@ -7,6 +7,8 @@ description: 使用 @tier0/sdk-v2 的 client.uns 完成新架构集合、Schema
 
 UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本分别用 [Source](../tier0-sdk-v2-source/SKILL.md)、[Stream](../tier0-sdk-v2-stream/SKILL.md)。服务端 `createClient()` 读取 TIER0_API_HOST / TIER0_API_KEY，或显式传 apiHost/apiKey。数据权限不自动授予管理权限：管理操作中 App 凭证只能调用本 App 集合的 appCollectionsEnsure / SchemaReplace / Archive / Restore；appDataPolicyGet/Update 的调用方必须是持有 uns.write 的登录会话、持有 uns.write 且 full_access、不绑定 App 的 personal / agent Key，或治理会话；运行时 App 凭证不能管理数据授权。
 
+工业场景创建目录或集合前，先按[命名空间指导](references/namespace.md)查询并复用已有 ISA-95 目录，只创建业务需要且缺失的层级，用现有 `parentId` 挂接；不要按 App 重建一套工厂目录。
+
 ## 按任务加载参考
 
 | 用户任务 | 参考 | 方法 |

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/create.md

@@ -6,16 +6,19 @@
 
 目录、集合和主题使用现有 name 填写易读的真实业务名称，语言遵循用户偏好和已有术语；不要用程序 alias、随机串或 ID 代替名称，不提供 displayName 或名称回退。name 为 1–63 个 Unicode 字符，无首尾空白，不含 `/` 或空字符；同目录重名时选择明确的业务名称，不自动拼接随机后缀。工业目录按[命名空间](namespace.md)指导复用已有 ISA-95 设备层级，只创建业务已知的层级，非工业业务不强套工厂结构；修改既有名称须有用户授权，不借整理名称改写 ID、alias、权限或移动数据。
 
+下例传入已查询确认的父目录 ID；只有业务位置确实在根目录时才传 `null`。
+
 ```ts
 import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
 
 export async function createDeviceCollection(
-  collectionId: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+  collectionId: string, name: string, parentId: string | null,
+  intentKey: string, client: Tier0Client = createClient(),
 ) {
   const request: UnsV2Request<'metadataInsertOne'> = {
     kind: 'collection', id: collectionId,
     data: {
-      name, parentId: null,
+      name, parentId,
       recordSchema: {
         type: 'object', additionalProperties: false, required: ['name', 'enabled'],
         properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },

package/skills/tier0-sdk-v2/tier0-sdk-v2-uns/references/namespace.md

@@ -4,7 +4,9 @@
 
 目录、Collection 和 Topic 直接以 name 展示业务名称，不提供 displayName。系统引用用 ID，App 程序标识用独立 alias；名称改动不影响它们。不要用随机串、时间戳或 ID 拼接名称，也不自动用无意义后缀解决重名。
 
-工业目录优先按实际 ISA-95 设备层级组织：企业 → 工厂/站点 → 区域/车间 → 工作中心（产线等）→ 工作单元。先查询并复用已有目录，只建立业务已知且有意义的层级；通过 parentId 挂接，跨区域共享数据放到共同祖先。不要编造工厂设备，也不用 Level 0–4 控制功能层级替代设备层级；非工业业务按真实业务结构组织。整理时不擅自移动已有数据或更改权限。
+工业目录优先按实际 ISA-95 设备层级组织：企业 → 工厂/站点 → 区域/车间 → 工作中心（产线等）→ 工作单元。创建前用 `metadataFind` 查询相关已有目录和集合，结合名称与 `parentId` 确认位置，有分页时继续读取。优先复用，只创建业务需要且缺失的层级，通过 `data.parentId` 挂接；不为凑齐层级编造工厂设备，也不按每个 App 重建一套目录。跨区域共享数据放到适合其业务范围的共同祖先；非工业业务按真实业务结构组织，不用 Level 0–4 控制功能层级替代设备层级。整理时不擅自移动已有数据或更改权限。
+
+例如已有“上海工厂 / 装配车间”，新增一条产线的数据只补缺少的产线节点；车间共享集合可直接放在车间下。App 的 `defineCollection` / ensure 不接收 `parentId`，新集合默认放在 App 专属目录。需要工业目录位置时，由 Agent 在构建期通过 `metadataInsertOne` 的 `data.parentId` 放置集合；为本 App 新建时可同时提供顶层 `appId/alias`，记录唯一 `ownerAppId` 和授权。随后 App 按已有集合 ID 访问，目录位置不决定归属或权限。
 
 | 场景 | 方法 |
 | --- | --- |
@@ -18,18 +20,21 @@
 
 普通写操作只指定一个 kind。updateMany/deleteMany/restore 固定原子执行；bulkWrite 默认 atomic=true，原子批次不接受 ordered=false。bulkWrite 显式 atomic=false 时 ordered=true 遇错停止，false 继续，并检查 results/errors。非原子执行有任一项已提交后失败时，`execution` 为 committed、`retry.safe` 为 false，错误的 data 是累计结果：序号小于 `nextIndex` 且不在 errors 里的操作已提交；有 `unknownUntil` 时 `[nextIndex, unknownUntil)` 结局未知，用同一个幂等键重试（不带键时只有按 id 的操作能先读回再续做，所以非原子批次始终带幂等键）；没有 `unknownUntil` 时从 `nextIndex` 续做。第一块就结局未知时 `execution` 为 unknown。批次最多 200 项。不要给所有对象套一个相同 expectedRevision：需要逐项版本检查时在 bulkWrite 中分别提供。
 
+下面示例只用于确认已有父目录下缺少一个业务节点的情况；若节点已存在，直接复用其 ID 创建 Topic。
+
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
 
 export async function createDirectoryAndTopic(
-  directoryId: string, topicId: string, collectionId: string, intentKey: string,
+  parentId: string, directoryId: string, directoryName: string,
+  topicId: string, collectionId: string, intentKey: string,
   client: Tier0Client = createClient(),
 ) {
   return client.uns.metadataTransact({
     idempotencyKey: intentKey,
     operations: [
       { opId: 'directory', action: 'insertOne', kind: 'directory', id: directoryId,
-        data: { name: '设备目录', parentId: null } },
+        data: { name: directoryName, parentId } },
       { opId: 'topic', action: 'insertOne', kind: 'topic', id: topicId, dependsOn: ['directory'],
         data: { name: '设备视图', parentId: { ref: 'directory' }, viewMode: 'records', collectionId } },
     ],