@tier0/sdk-v2 0.9.8 → 0.9.9

package/package.json

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

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

@@ -7,7 +7,9 @@ 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 重建一套工厂目录。
+先按[命名空间指导](references/namespace.md)区分凭证：`namespace()` 走 OpenAPI，但当前不对 App Key 开放；App 查询可用集合走 `dataAppContext`，不能改用同样受限的 `appCollectionsList`。Agent / Personal Key 也须满足当前工作空间权限；不要从“使用 SDK / MCP”推定权限。
+
+工业场景中，有管理权限的调用方创建目录或集合前，先查询并复用已有 ISA-95 目录，只创建业务需要且缺失的层级，用现有 `parentId` 挂接；App Key 根据上下文和已知业务范围声明集合的 `directoryPath`。不要要求 App Key 先调用管理查询，也不要按 App 重建一套工厂目录。
 
 ## 按任务加载参考
 
@@ -17,6 +19,7 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 | 查询集合、筛选/排序记录 | [查询](references/read.md) | dataAppContext、metadataFind/FindOne（非 App 凭证）、collectionDescribe、recordFind |
 | 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many |
 | 删记录、软删除集合 | [删除](references/delete.md) | recordDeleteOne、metadataDeleteOne/Many |
+| 永久删除回收站集合 | [删除](references/delete.md) | metadataPurge、jobs |
 | 恢复集合或记录 | [恢复](references/restore.md) | metadataRestore、recordRestore |
 | 分页、历史采样、事务、写入结果 | [数据工作流](references/data-workflows.md) | sampleFind、recordTransactionExecute |
 | 目录、Topic 元数据及组合事务 | [命名空间](references/namespace.md) | metadata*、metadataBulkWrite、metadataTransact |
@@ -43,7 +46,7 @@ export async function readAppRecords(collectionId: string) {
 1. 记录行是 id/data/revision；filter 与 update 的业务路径用 name、customer.name，不加 data.；系统路径用 _id、_meta.revision。
 2. 改/删使用最近写回执或读取取得的 revision 作为 expectedRevision；创建时可用 returnDocument:'after' 取得快照。历史重放不是当前最新版本，冲突时显式处理；不同操作使用独立意图键，长度上限以当前操作契约为准。
 3. metadataUpdateOne 的 $set.recordSchema 替换完整 Schema，不迁移已有记录；未更新的 sampleSchema/indexes 保留。先预检兼容性。
-4. 集合无硬删除入口，用 metadataDeleteOne/Many 软删除；Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
+4. metadataDeleteOne/Many 软删除集合并保留 Record/Sample；metadataPurge 永久清理明确 ID 的回收站集合。accepted 只表示任务已受理，须用 jobs 查询逐项结果。Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
 5. recordFind 使用 pageInfo.hasMore/nextCursor，limit 1–200；sort 为 [['field',1]]。单页不是全量，跨页不是稳定快照。
 6. Sample 的时间是 Unix 毫秒，查询范围 [from,to)。Record 代表业务实体，不用覆盖它来保存历史。
 

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

@@ -23,7 +23,7 @@ export async function deleteDevice(
 }
 ```
 
-元数据使用 metadataDeleteOne/Many，或 metadataDeleteOne + returnDocument:before 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。引用约束与版本冲突必须处理，不能自行扩展删除范围。
+元数据使用 metadataDeleteOne/Many，或 metadataDeleteOne + returnDocument:before 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。集合有 Record/Sample 或配置引用不阻止明确删除；引用方保留并得到目标已删除的结果。目录和 Topic 保留原有约束，不能自行扩展删除范围。已知 revision 可直接提交，不要求每次重新读取或先 dryRun。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
@@ -51,3 +51,29 @@ metadataDeleteMany 使用明确 filter 和 maxDocs。默认原子；超过上限
 业务记录使用 recordDeleteOne/Many，传 collectionId 和明确 filter，编辑型流程同时传 expectedRevision。不要把元数据软删除解释成逐条删除该集合的 Record。Sample 的删除是独立的显式时间范围操作，具体影响遵循当前数据 API 契约。
 
 恢复见[恢复](restore.md)。未知写入结果保留原意图键，先按对象身份核对，不自动换键重试。
+
+## 永久删除回收站集合
+
+Workspace 管理调用方使用 `metadataPurge`，传 `kind:'collection'` 和 1–200 个明确 `ids`。
+只允许回收站集合；清空时先查全分页并固定这次选中的 ID，再按批调用同一个接口。
+不另传 `force`、`cascade`、确认 token，也不要求先清空记录或执行 dryRun。
+运行时 App 凭证不开放此操作；权限由后端统一校验。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function purgeCollections(
+  ids: string[], intentKey: string, client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.metadataPurge({
+    kind: 'collection', ids, idempotencyKey: intentKey,
+  });
+  return { state: 'submitted' as const, receipt };
+}
+```
+
+`status:accepted` 和 `jobId` 表示已受理，不表示已永久删除。通过 `client.uns.jobs`
+查询任务并检查终态和逐项结果；部分失败不能报告整批成功，中断后继续查询原任务或复用原意图键。
+永久删除包括全部 Record、Sample、集合元数据、索引以及指向集合的 App 授权；不连带删除 Topic、Source、Stream。
+清理开始后不能恢复。索引由后台回收，不能仅凭已受理或数据清理回执声称物理空间已全部释放。
+可选 `dryRun:true` 只返回校验结果，不创建清理任务。

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

@@ -1,5 +1,21 @@
 # 目录、Topic 与元数据事务
 
+## 先确定凭证与查询目的
+
+`client.uns.namespace()` 对应 `POST /openapi/v2/uns/namespace/query`，不是内部接口。SDK 保留该方法供有权限的工作空间调用方使用；SDK 方法目录不是当前凭证的授权清单。
+
+| 凭证 | Namespace / metadata 查询 | 发现并读取集合 |
+| --- | --- | --- |
+| 未绑定 App 的 Agent / Personal Key | 有当前工作空间权限及 Key scope 时可用；Agent Key 还会复核真实负责人的状态和权限 | 按当前工作空间授权查询，再调用 `recordFind` |
+| App Key | 当前不开放；`appCollectionsList` 也不能调用 | `dataAppContext({})` 返回自有及已授权集合、目录路径、结构和有效权限，再按集合 ID 调 `recordFind` |
+| 平台系统 Service Key | 按实际系统凭证授权，不按“Agent 正在调用”推定权限 | 带 Builder 目标时，指定 App 操作可使用目标 App 视角；不代表所有查询都变成 App 视角 |
+
+目录位置不产生数据授权。App 自有集合的正常创建流程提供相应授权，但读取仍受凭证权限、App 状态及数据策略约束；不能仅凭 `ownerAppId` 推定任何接口都可调用。SDK 和 MCP 使用相同凭证时仍受服务端授权约束。
+
+收到 `403 FORBIDDEN` 且原因为 `operation is not available to App credentials` 时，先核对调用接口与服务端确认的凭证身份。这是操作准入拒绝，不能据此认定 Collection 不可读或没有数据。App 的正确流程见[读取示例](read.md)；不要重试同一不允许的操作、改走内部接口或自动换成权限更大的 Key。记录 `requestId`；错误文案仅供诊断，不在程序中匹配文案作权限判断。
+
+## 工作空间目录管理
+
 目录、Topic、Collection 使用同一套 metadata* 方法，通过 kind 指定类型。Source/Stream 的启停、连接和发布仍使用各自专用生命周期接口；不允许把系统任务、凭据或发布历史当作普通元数据修改。
 
 目录、Collection 和 Topic 直接以 name 展示业务名称，不提供 displayName。系统引用用 ID，App 程序标识用独立 alias；名称改动不影响它们。不要用随机串、时间戳或 ID 拼接名称，也不自动用无意义后缀解决重名。

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

@@ -1,5 +1,27 @@
 # 查询集合与记录
 
+## App Key：从授权上下文读取
+
+App Key 使用 `dataAppContext`，不调用 `namespace`、`metadataFind` 或 `appCollectionsList`。上下文包含可访问集合的名称、目录路径、Schema 和有效权限；按已配置 alias 精确定位，不能随意选择列表第一项。已知集合 ID 时可直接调用 `recordFind`，不要求每次预先加载上下文。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+// 在服务端使用 App Key；alias 是应用配置中的稳定集合别名。
+export async function readAppRecords(alias: string, client: Tier0Client = createClient()) {
+  const context = await client.uns.dataAppContext({});
+  const collection = context.data.collections.find(item => item.alias === alias);
+  if (!collection || !collection.permissions.includes('record:read')) {
+    throw new Error('当前 App 上下文没有该别名的可读集合，请核对别名、授权和凭证');
+  }
+  return client.uns.recordFind({ collectionId: collection.collectionId, limit: 20 });
+}
+```
+
+未找到别名不等于集合不存在；共享授权可能没有 alias，应使用明确配置的集合 ID。上下文只是发现结果，后续请求仍由服务端重新检查权限。网络或权限错误应传播，不转换成“零条记录”。此例只读取第一页，后续按返回的 `pageInfo` 继续查询。
+
+## 工作空间凭证：查询元数据与记录
+
 | 方法 | 必要输入 | 返回 data |
 | --- | --- | --- |
 | metadataFind | kinds；可选 filter、sort、projection、page、state | items、pageInfo |