@tier0/sdk-v2 0.1.0 → 0.2.2

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

@@ -0,0 +1,38 @@
+# 目录、Topic 与元数据事务
+
+目录、Topic、Collection 使用同一套 metadata* 方法，通过 kind 指定类型。Source/Stream 的启停、连接和发布仍使用各自专用生命周期接口；不允许把系统任务、凭据或发布历史当作普通元数据修改。
+
+| 场景 | 方法 |
+| --- | --- |
+| 单条/批量新增 | metadataInsertOne / metadataInsertMany |
+| 单条/批量条件更新 | metadataUpdateOne / metadataUpdateMany |
+| 更新并读取原子结果 | metadataFindOneAndUpdate / metadataFindOneAndReplace |
+| 同 kind 混合写入 | metadataBulkWrite |
+| 跨 kind、有依赖的组合操作 | metadataTransact |
+| 软删除并返回原对象 | metadataFindOneAndDelete |
+| 按明确 ID 批量恢复 | metadataRestore |
+
+普通写操作只指定一个 kind。insertMany/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 中分别提供。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function createDirectoryAndTopic(
+  directoryId: 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 } },
+      { opId: 'topic', action: 'insertOne', kind: 'topic', id: topicId, dependsOn: ['directory'],
+        data: { name: '设备视图', parentId: { ref: 'directory' }, viewMode: 'records', collectionId } },
+    ],
+  });
+}
+```
+
+transact 始终原子，结果通过 opId 对应输入；dryRun=true 校验，不预留 ID 或名称。正式执行仍重新检查。创建结果引用仅用于契约支持的关系字段，不能把任意字符串或脚本当引用。
+
+名称、父目录、Schema、引用与权限由服务端校验。移动不改变对象 ID；删除目录不隐式清空后代；删除 Topic 不删除所引用的 Collection。引用查询仍使用 references 专用方法。

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

@@ -0,0 +1,34 @@
+# 查询集合与记录
+
+| 方法 | 必要输入 | 返回 data |
+| --- | --- | --- |
+| metadataFind | kinds；可选 filter、sort、projection、page、state | items、pageInfo |
+| metadataFindOne | kind、filter；可选 state | value，未找到为 null |
+| metadataCount / metadataDistinct | kind/kinds 与查询条件；distinct 还指定 field | count / values、pageInfo |
+| collectionDescribe | collectionId | 集合结构和数据能力 |
+| recordFind | collectionId；可选 filter、sort、limit、cursor | items、pageInfo |
+
+元数据查询配置字段写 name、parentId；系统字段写 _id、_meta.kind、_meta.revision。返回资源的配置在 value.data 或 items[].data 中。state 为 active/deleted/all，默认 active。对象身份始终是 kind + id。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function readDevices(collectionId: string, client: Tier0Client = createClient()) {
+  const collection = await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: collectionId } });
+  if (!collection.data.value) throw new Error('集合不存在或不可见');
+  const records = await client.uns.recordFind({
+    collectionId, filter: { enabled: true }, sort: [['name', 1]], limit: 20,
+  });
+  return { definition: collection.data.value.data, items: records.data.items, pageInfo: records.data.pageInfo };
+}
+
+export async function listCollections(page = 1, client: Tier0Client = createClient()) {
+  return client.uns.metadataFind({
+    kinds: ['collection'], state: 'active', sort: [['_id', 1]], page: { mode: 'offset', page, size: 20 },
+  });
+}
+```
+
+按 pageInfo.hasMore/nextPage 继续元数据分页；不要把第一页当全量。recordFind 的游标循环见[数据工作流](data-workflows.md)。sort 是数组元组。
+
+以上 metadataFind/FindOne 示例用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind/FindOne：用 dataAppContext 精确选择授权 alias，集合的 revision、indexStatus、ttl 也在其中。数据授权不等于元数据管理授权。网络/权限错误必须传播，不能用空数组掩盖错误。

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

@@ -0,0 +1,39 @@
+# 恢复元数据与记录
+
+metadataRestore 接收 kind、items[{id,expectedRevision?}]，支持一个或多个明确 ID。revision 应从 state=deleted 的当前对象读取。恢复重新校验名称、父目录、Schema 与引用；不会恢复其他对象，冲突时原子批次回滚。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function restoreCollection(
+  id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const deleted = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id }, state: 'deleted' })).data.value;
+  if (!deleted) throw new Error('未找到待恢复集合');
+  const receipt = await client.uns.metadataRestore({
+    kind: 'collection', items: [{ id, expectedRevision: deleted.revision }], idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.restoredCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('恢复有回执，读回未确认');
+  return { state: 'committed' as const, receipt, current };
+}
+
+export async function restoreDevice(
+  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.recordRestore({
+    collectionId, ids: [id], dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || !receipt.data.restoredIds.includes(id)) {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  if (!found.data.items[0]) throw new Error('恢复有回执，读回未确认');
+  return { state: 'committed' as const, receipt, current: found.data.items[0] };
+}
+```
+
+Record 恢复使用 recordRestore 的 ids（最多 100 条），重新校验当前 Schema 和有效唯一索引，冲突整批回滚。新增同 ID 或 upsert 不会隐式恢复对象。幂等键每个新意图独立。

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

@@ -0,0 +1,62 @@
+# 修改记录、元数据和 Schema
+
+元数据单条使用 metadataUpdateOne 或 metadataFindOneAndUpdate；后者原子返回 value，returnDocument 可选 before/after。批量相同更新使用 metadataUpdateMany；不同更新使用 metadataBulkWrite。完整替换使用 metadataReplaceOne/metadataFindOneAndReplace，replacement 是完整可写配置。
+
+update 首版支持 $set/$unset/$setOnInsert。字段使用裸配置路径；_id/_meta 为只读。写前读取 revision，编辑页面携带 expectedRevision，冲突后重新比较。单条 upsert 需明确 _id 等值条件，新增内容满足完整创建约束；同 ID 的软删除对象必须显式恢复。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameCollection(
+  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('集合不存在或不可见');
+  return client.uns.metadataFindOneAndUpdate({
+    kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
+    update: { $set: { name } }, returnDocument: 'after', upsert: false, idempotencyKey: intentKey,
+  });
+}
+```
+
+修改 Schema 时先构造完整 recordSchema，再用 $set 更新该字段。它不迁移已有记录，必须兼容保留数据与引用。没有修改的 sampleSchema/indexes 保持原值。先 dryRun，再用独立正式意图键提交。
+
+```ts
+import { createClient, type Tier0Client, type Schema } from '@tier0/sdk-v2';
+
+export async function replaceRecordSchema(
+  id: string, recordSchema: Schema, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  if (!current) throw new Error('集合不存在或不可见');
+  const request = { kind: 'collection' as const, filter: { _id: id },
+    expectedRevision: current.revision, update: { $set: { recordSchema } } };
+  const preview = await client.uns.metadataUpdateOne({ ...request, dryRun: true });
+  if (preview.data.status !== 'validated') throw new Error('Schema 预检未通过');
+  return client.uns.metadataUpdateOne({ ...request, dryRun: false, idempotencyKey: intentKey });
+}
+```
+
+业务记录仍使用 recordUpdateOne：传 collectionId/filter/update，按需携带 expectedRevision。metadataUpdateOne 不能更新 Record 的业务内容。matchedCount 和 modifiedCount 不等价；值未变化时 modifiedCount 可为 0。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameDevice(
+  collectionId: string, id: string, name: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  const current = (await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 })).data.items[0];
+  if (!current) throw new Error('记录不存在或不可见');
+  const receipt = await client.uns.recordUpdateOne({
+    collectionId, filter: { _id: id }, expectedRevision: current.revision,
+    update: { $set: { name } }, upsert: false, dryRun: false, idempotencyKey: intentKey,
+  });
+  if (receipt.data.status !== 'committed' || String(receipt.data.matchedCount) !== '1') {
+    return { state: 'unconfirmed' as const, receipt };
+  }
+  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  if (after.data.items[0]?.data.name !== name) throw new Error('读回名称与目标不一致');
+  return { state: 'committed' as const, receipt, current: after.data.items[0] };
+}
+```

package/skills/tier0-sdk-v2-data/references/read-write.md

@@ -1,72 +0,0 @@
-# 读写
-
-`data.collection(declaration)` 返回按声明推断类型的句柄（也可用 alias 字符串，类型由调用方指定）。读到的记录是扁平文档 `{ _id, ...字段, _meta }`；过滤、排序、投影都用同样的路径（`status`、`customer.id`、`_id`、`_meta.updatedAt`），不加 `data.` 前缀。
-
-```ts
-import { z } from 'zod';
-import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';
-
-const workOrders = defineCollection({
-  alias: 'work_orders',
-  schema: z.object({
-    code: z.string(),
-    status: z.enum(['DRAFT', 'RELEASED', 'DONE']),
-    line: z.object({ id: z.string(), name: z.string() }),
-    targetQty: z.number().int().min(1),
-    notes: z.string().optional(),
-  }),
-  indexes: [{ path: 'code', unique: true }, { path: 'status' }],
-});
-const data = createDataClient({ collections: [workOrders] });
-const orders = data.collection(workOrders);
-
-export async function dashboard(page: number) {
-  const recent = await orders.find({ status: { $in: ['RELEASED', 'DONE'] } }, { sort: { '_meta.createdAt': -1 }, limit: 50 }).toArray();
-  const listPage = await orders.findPage({ status: 'RELEASED' }, { sort: { code: 1 }, page, pageSize: 20 });
-  const released = await orders.countDocuments({ status: 'RELEASED' });
-  const totals = await orders
-    .aggregate<{ _id: string; total: number }>([{ $match: { status: 'DONE' } }, { $group: { _id: '$line.id', total: { $sum: '$targetQty' } } }])
-    .toArray();
-  return { recent, listPage, released, totals };
-}
-
-export async function addNote(id: string, notes: string, revision: number) {
-  return orders.updateOne({ _id: id }, { $set: { notes } }, { expectedRevision: revision });
-}
-```
-
-## 方法
-
-| 读取 | 说明 |
-| --- | --- |
-| `find(filter, { sort, limit, projection })` | 游标，每页最多 200 条；列表读取始终给 `limit` |
-| `findOne(filter)` | 无匹配返回 `null` |
-| `findPage(filter, { sort, page, pageSize })` | 带总数的页码分页 `{ items, total, page, pageSize }`，pageSize 最多 200 |
-| `countDocuments(filter)`、`distinct(field, filter)` | `distinct` 会取完所有页 |
-| `aggregate(pipeline)` | `$match` `$sort` `$group` `$project` `$set` `$unwind` `$skip` `$limit` `$count` `$lookup`；`$lookup.from` 写声明或 alias，数据层换成集合 ID。`$exists` / `$distinct` / `$frequencies` 阶段不执行，改用 `countDocuments`、`distinct` 或 `$group` |
-
-| 写入 | 说明 |
-| --- | --- |
-| `insertOne(doc)`、`insertMany(docs)` | 可带 `_id`；`insertMany` 最多 200 条、原子 |
-| `updateOne` / `updateMany` / `replaceOne` | 更新用操作符（`$set` `$inc` `$push` `$unset`…）；`replaceOne` 会丢掉其他代码版本写入的字段 |
-| `deleteOne` / `deleteMany` | 软删除，App Key 需要 `uns.delete` |
-| `findOneAndUpdate` / `findOneAndReplace` / `findOneAndDelete` | 原子读改写，默认返回更新后的文档 |
-| `bulkWrite(ops)` | `insertOne` / `updateOne` / `replaceOne` / `deleteOne` 混合，最多 200 项、原子 |
-| `data.transact(steps)` | 跨集合原子写，见 [一致性](consistency.md) |
-
-## 批量与原子性
-
-| 调用 | 上限 | 原子 |
-| --- | --- | --- |
-| `insertMany`、`bulkWrite`、`data.transact` | 每次 ≤200 项，超过在发送前抛 `BATCH_LIMIT_EXCEEDED` | 是，全部或全不 |
-| `updateMany`、`deleteMany` | 无上限，翻页处理所有匹配 | 否，逐条提交；失败抛 `WRITE_ERRORS` 并报告已提交的数量 |
-
-超过 200 条按 200 分块写入（循环分块即可），每块用固定 `_id` 或独立 `idempotencyKey`，重试不会重复。多条文档必须一起成功或失败时，用一次 `data.transact`（≤200 步），不要用 `updateMany`。不要在循环里逐条调用数据层：读用一次 `$in`，写用 `insertMany` / `updateMany` / `bulkWrite` 或 `data.transact`。
-
-## 过滤
-
-支持 `$eq $ne $gt $gte $lt $lte $in $nin $exists $all $size $elemMatch $not $and $or $nor` 和 `$contains`。`$contains` 是子串匹配（1–256 字节，无通配符和正则），只对 ASCII 字母忽略大小写；缺失、null、非字符串值不匹配；只能用于声明为字符串的字段，用在数组或数字字段上返回 `INVALID_REQUEST`。它不能使用索引，大集合上可能触发 15 秒语句超时（`QUERY_TIMEOUT`），要和有索引的条件一起用。`$in` 最多 200 个值，排序最多 4 个字段（`toSortPairs` 也导出给自定义查询转换使用）。
-
-## 校验
-
-写入前按声明严格校验：未知字段、类型错误、未声明的更新路径抛 `ZodError`（HTTP 400 语义）。读取不严格解析：记录可能含其他代码版本写入的字段、新的枚举值，或缺少后来新增的字段。枚举渲染要有兜底标签，后加的字段按可能缺失处理。

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

@@ -1,47 +0,0 @@
-# 删除 Source
-
-方法：`source.delete`；POST `/openapi/v2/uns/sources/delete`。
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| dryRun | boolean | 是 | true 预检；false 提交 |
-| items | array | 是 | 1–200 项 |
-| items[].id | string | 是 | 正十进制 int64 字符串 |
-| items[].expectedRevision | integer | 是 | get 返回的修订 |
-| items[].confirmedImpactRevision | string | 是 | action=delete 的影响回执 |
-| mode | auto/sync | 否 | 不支持 async |
-| allowPartial | false | 否 | 不支持部分提交 |
-| idempotencyKey | string | 否 | 最多 128 字符 |
-
-先 get → impact(action=delete) → [遍历并评估影响](changes.md)。存在 Stream 依赖时遵守服务端保护，不自动删除依赖流。
-
-```ts
-import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
-
-export async function deleteSource(
-  id: string, expectedRevision: UnsV2Request<'sourceImpact'>['expectedRevision'],
-  confirmedImpactRevision: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const receipt = await client.source.delete({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, expectedRevision, confirmedImpactRevision }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  let page = 1;
-  while (true) {
-    const { data } = await client.source.documents.list({
-      archived: true, page, size: 200, includeDocument: false,
-    });
-    const archived = data.list.find(item => item.id === id);
-    if (archived) return { state: 'archived' as const, receipt, archived };
-    if (!data.hasMore) break;
-    if (typeof data.nextPage !== 'number' || data.nextPage <= page) throw new Error('无有效下一页');
-    page = data.nextPage;
-  }
-  return { state: 'committed-readback-unconfirmed' as const, receipt };
-}
-```
-
-返回 Outcome，HTTP 200/validated/accepted 不等于完成。归档列表找到 ID 是额外核验；读回不可见时保留提交回执，报告核验未完成。不能把任意 get 异常当成成功。

package/skills/tier0-sdk-v2-source/references/state.md

@@ -1,37 +0,0 @@
-# 启用、停用 Source
-
-方法：`source.state.update`；POST `/openapi/v2/uns/sources/state/update`。
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| dryRun | boolean | 是 | 提交 false |
-| items[].id / expectedRevision | string / integer | 是 | 当前对象和修订 |
-| items[].desiredState | enabled/disabled | 是 | 目标状态 |
-| items[].confirmedImpactRevision | string | 是 | enable/disable 对应的影响回执 |
-| mode / allowPartial | string / boolean | 否 | 单项示例 sync / false |
-| idempotencyKey | string | 否 | 本次状态变更的独立意图键 |
-
-先 get，以相同修订执行 impact(action=enable 或 disable)，按[影响分析](changes.md)遍历并评估。将原修订和回执传给下例。
-
-```ts
-import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
-
-export async function setSourceState(
-  id: string, expectedRevision: UnsV2Request<'sourceImpact'>['expectedRevision'],
-  desiredState: 'enabled' | 'disabled', confirmedImpactRevision: string,
-  intentKey: string, client: Tier0Client = createClient(),
-) {
-  const receipt = await client.source.state.update({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, expectedRevision, desiredState, confirmedImpactRevision }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  const current = await client.source.documents.get({ id });
-  if (current.data.desiredState !== desiredState) throw new Error('读回状态与目标不一致');
-  return { state: 'committed' as const, receipt, current: current.data };
-}
-```
-
-响应为 Outcome；accepted/jobId 仅表示受理，继续查询作业。enabled 是期望状态；健康与连通性另用 observations/runtime 检查。

package/skills/tier0-sdk-v2-source/references/update.md

@@ -1,61 +0,0 @@
-# 修改 Source
-
-方法：`source.documents.update`；POST `/openapi/v2/uns/sources/documents/update`。
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| id | string | 是 | get 返回的 ID |
-| document | CloudSourceDocument | 是 | 完整新文档，保留未改字段和认证引用 |
-| expectedRevision | integer | 是 | 读取时的 revision，原样传回 |
-| confirmedImpactRevision | string | 是 | 相同文档和修订的 impact 回执 |
-| dryRun | boolean | 是 | true 预检；false 提交 |
-| idempotencyKey | string | 否 | 最多 128 字符 |
-
-## 示例：修改名称并保留连接
-
-prepare 读取文档、形成新文档并收集全部影响分页。在已有授权范围内评估 counts、restrictedCount 和引用后调用 commit，不自动串联未经授权的操作。影响字段说明见[影响分析](changes.md)。
-
-```ts
-import { createClient, type Tier0Client, type CloudSourceDocument, type UnsV2Request } from '@tier0/sdk-v2';
-
-export async function prepareSourceRename(id: string, name: string, client: Tier0Client = createClient()) {
-  const { data: current } = await client.source.documents.get({ id });
-  const document: CloudSourceDocument = { ...current.document, name };
-  const intent: UnsV2Request<'sourceImpact'> = {
-    id, expectedRevision: current.revision, action: 'update', document,
-  };
-  const impact = await client.source.impact({ ...intent, offset: 0, size: 200 });
-  const references = [...impact.data.references];
-  let offset = impact.data.nextOffset;
-  const seen = new Set<string>();
-  while (String(offset) !== '0') {
-    if (seen.has(String(offset))) throw new Error('影响分页未前进');
-    seen.add(String(offset));
-    const next = await client.source.impact({
-      ...intent, offset, size: 200, impactRevision: impact.data.impactRevision,
-    });
-    if (next.data.impactRevision !== impact.data.impactRevision) throw new Error('影响确认值发生变化');
-    references.push(...next.data.references);
-    offset = next.data.nextOffset;
-  }
-  return { intent, impact: { ...impact.data, references, nextOffset: offset } };
-}
-export async function commitSourceRename(
-  plan: { intent: UnsV2Request<'sourceImpact'>; impact: { impactRevision: string } },
-  intentKey: string, client: Tier0Client = createClient(),
-) {
-  const { id, expectedRevision, document, action } = plan.intent;
-  if (action !== 'update' || !document) throw new Error('需要完整更新意图');
-  const request = { id, expectedRevision, document,
-    confirmedImpactRevision: plan.impact.impactRevision };
-  const preview = await client.source.documents.update({ ...request, dryRun: true });
-  if (!('validated' in preview.data) || !preview.data.validated) throw new Error('预检未通过');
-  const saved = await client.source.documents.update({
-    ...request, dryRun: false, idempotencyKey: intentKey,
-  });
-  if (!('id' in saved.data)) throw new Error('未收到更新提交结果');
-  return { receipt: saved, current: (await client.source.documents.get({ id })).data };
-}
-```
-
-提交返回完整 Source view。核对读回名称、配置和提交修订；若读回又被别人修改，报告并发变化。影响评估后的 plan 保持不变。遇到 VERSION_CONFLICT、确认过期/不匹配，重新读取并评估，不静默刷新 token 重放。

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

@@ -1,53 +0,0 @@
----
-name: tier0-sdk-v2-uns
-description: 使用 @tier0/sdk-v2 的 client.uns 完成新架构集合、Schema、目录、Topic、Record 增删改查、归档恢复、采样历史与事务，区分 App 和 Workspace 数据权限。
----
-
-# UNS 数据操作
-
-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 凭证不能管理数据授权。
-
-## 按任务加载参考
-
-| 用户任务 | 参考 | 方法 |
-| --- | --- | --- |
-| 创建集合、定义 Schema、新增记录 | [创建](references/create.md) | collectionCreate、recordInsertOne |
-| 查询集合、筛选/排序记录 | [查询](references/read.md) | collectionGet/List/Describe、recordFind |
-| 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、collectionUpdate/SchemaUpdate |
-| 删记录、归档集合 | [删除](references/delete.md) | recordDeleteOne、collectionArchive |
-| 恢复集合或记录 | [恢复](references/restore.md) | collectionRestore、recordRestore |
-| 分页、历史采样、事务、变更轮询 | [数据工作流](references/data-workflows.md) | sampleFind、recordTransactionExecute、recordChangesPoll |
-| 目录与 Topic 元数据 | [命名空间](references/namespace.md) | directory*、topic* |
-
-## 找到正确数据上下文
-
-托管 App 使用 dataAppContext，按业务 alias 精确选择授权集合；Workspace 集成用 dataDiscover/collectionList，不强制 App 上下文。
-
-```ts
-import { createClient } from '@tier0/sdk-v2';
-
-export async function findAppCollection(alias: 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 });
-}
-```
-
-不要把 alias/名称当 collectionId，不猜第一个集合是业务目标。
-
-## 核心约束
-
-1. 记录行是 id/data/revision；filter 与 update 的业务路径用 name、customer.name，不加 data.；系统路径用 _id、_meta.revision。
-2. 改/删前读取 expectedRevision；普通 Record 意图键上限 96 字符，集合管理为 128。不同操作使用独立键。
-3. collectionSchemaUpdate 替换完整 Schema，不迁移已有记录；sampleSchema/indexes 省略保留。先预检兼容性。
-4. 集合无硬删除入口，用 archive；Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
-5. recordFind 使用 pageInfo.hasMore/nextCursor，limit 1–200；sort 为 [['field',1]]。单页不是全量，跨页不是稳定快照。
-6. Sample 的时间是 Unix 毫秒，查询范围 [from,to)。Record 代表业务实体，不用覆盖它来保存历史。
-
-## 结果与异常
-
-响应为 code/msg/requestId/data；集合写入 Outcome 与记录写入计数回执不同。检查 committed、每项错误和实际计数；accepted/jobId 先对账，不当成完成。allowPartial 不等于事务，recordBulkWrite 不保证跨集合事务。
-
-大整数与 JSON 精确数字可能为 bigint/UnsV2RawNumber；保留读取到的 revision 类型，不用 Number 或普通 JSON.stringify 做无损往返。UnsV2OutcomeUnknownError 先读回核对内容或查询 jobs；取消请求不撤销写入，SDK 不自动重试。

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

@@ -1,85 +0,0 @@
-# 创建集合与记录
-
-| 方法 | POST 路径 | 用途 |
-| --- | --- | --- |
-| uns.collectionCreate | /openapi/v2/uns/collections/create | 创建集合及 Schema |
-| uns.recordInsertOne | /openapi/v2/uns/collections/{collectionId}/records | 新增业务记录 |
-
-## 集合参数
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| dryRun | boolean | 是 | true 预检；false 提交 |
-| items[].id | string | 否 | 可指定稳定业务 ID，不能与已有集合冲突 |
-| items[].name | string | 是 | 1–63 字符 |
-| items[].recordSchema | Schema | 是 | 至少 type；对象可含 properties/required |
-| items[].sampleSchema | Schema | 否 | 需要采样时配置 |
-| items[].parentId | string/null | 否 | 目录 ID；null 或创建时省略表示根 |
-| items[].indexes | IndexSpec[] | 否 | 索引定义，不能把索引创建当成已 ready |
-| mode / allowPartial | string / boolean | 否 | 示例 sync / false |
-| idempotencyKey | string | 否 | 集合管理最多 128 字符 |
-
-## 完整示例：设备集合
-
-```ts
-import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
-
-export async function createDeviceCollection(
-  collectionId: string, name: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const item: UnsV2Request<'collectionCreate'>['items'][number] = {
-    id: collectionId, name, parentId: null,
-    recordSchema: {
-      type: 'object', additionalProperties: false, required: ['name', 'enabled'],
-      properties: { name: { type: 'string' }, enabled: { type: 'boolean' } },
-    },
-    sampleSchema: {
-      type: 'object', additionalProperties: false, required: ['temperature'],
-      properties: { temperature: { type: 'number', unit: '°C' } },
-    },
-  };
-  const preview = await client.uns.collectionCreate({ dryRun: true, mode: 'sync', items: [item] });
-  if (preview.data.status !== 'validated') throw new Error('集合预检未通过');
-  const receipt = await client.uns.collectionCreate({
-    dryRun: false, mode: 'sync', allowPartial: false, items: [item], idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  return { state: 'committed' as const, receipt,
-    current: (await client.uns.collectionGet({ id: collectionId })).data };
-}
-```
-
-返回 Outcome：status、results、replayed，可含 jobId/summary。accepted 需要作业对账；validated 不表示已创建。省略自定义 ID 时从成功 results[].id 取得实际 ID，不能用集合名称代替。
-
-## 新增设备记录
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| collectionId | string | 是 | 已存在且有权限的集合 |
-| id | string | 否 | 可指定稳定记录 ID |
-| data | object | 是 | 符合 recordSchema 的业务字段 |
-| dryRun | boolean | 否 | 默认 false，示例显式给出 |
-| idempotencyKey | string | 否 | 记录写入最多 96 字符 |
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function insertDevice(
-  collectionId: string, id: string, name: string, intentKey: string,
-  client: Tier0Client = createClient(),
-) {
-  const receipt = await client.uns.recordInsertOne({
-    collectionId, id, data: { name, enabled: true }, dryRun: false, idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed') return { state: 'unconfirmed' as const, receipt };
-  const found = await client.uns.recordFind({
-    collectionId, filter: { _id: receipt.data.insertedId }, limit: 1,
-  });
-  if (!found.data.items[0]) throw new Error('新增有回执，但读回未找到记录');
-  return { state: 'committed' as const, receipt, current: found.data.items[0] };
-}
-```
-
-成功 data：insertedId、status、replayed；不能把 replayed 误解为本次重复插入。记录创建与集合创建用不同意图键。未知结果先按 ID 核对业务内容，不仅检查“存在”。

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

@@ -1,69 +0,0 @@
-# 删除记录与归档集合
-
-集合没有 collectionDelete；使用 collectionArchive。记录使用 recordDeleteOne/Many。两种操作的影响不可互换。
-
-## 删除一个明确 ID 的记录
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| collectionId | string | 是 | 所属集合 |
-| filter | object | 是 | 示例用 _id 精确等值 |
-| expectedRevision | integer | 建议提供 | 刚读取的记录修订 |
-| dryRun | boolean | 否 | 默认 false，示例显式指定 |
-| idempotencyKey | string | 否 | 最多 96 字符 |
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function deleteDevice(
-  collectionId: string, id: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const found = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  const current = found.data.items[0];
-  if (!current) throw new Error('记录不存在或不可见，未执行删除');
-  const receipt = await client.uns.recordDeleteOne({
-    collectionId, filter: { _id: id }, expectedRevision: current.revision,
-    dryRun: false, idempotencyKey: intentKey,
-  });
-  if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  const after = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
-  if (after.data.items.length) throw new Error('删除有回执，但记录仍可见或已被恢复');
-  return { state: 'committed' as const, receipt };
-}
-```
-
-删除 Record 时关联 Sample 被物理删除；恢复记录不会重建这些 Sample。批量删除先明确筛选范围，不能用空 filter 代替未知 ID。删除回执含 deletedCount/status/replayed。
-
-## 归档集合
-
-输入 dryRun、items[{id,expectedRevision}]，可选 mode/allowPartial/idempotencyKey（最多128字符）。归档不等于逐条删除 Record，也不承诺物理擦除。
-
-```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
-
-export async function archiveCollection(
-  id: string, intentKey: string, client: Tier0Client = createClient(),
-) {
-  const { data: current } = await client.uns.collectionGet({ id });
-  const receipt = await client.uns.collectionArchive({
-    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
-    items: [{ id, expectedRevision: current.revision }],
-  });
-  if (receipt.data.status !== 'committed' || receipt.data.results?.some(item => item.error)) {
-    return { state: 'unconfirmed' as const, receipt };
-  }
-  let page = 1;
-  while (true) {
-    const { data } = await client.uns.collectionList({ archived: true, page, size: 200 });
-    const archived = data.list.find(item => item.id === id);
-    if (archived) return { state: 'archived' as const, receipt, archived };
-    if (!data.hasMore) return { state: 'committed-readback-unconfirmed' as const, receipt };
-    if (typeof data.nextPage !== 'number' || data.nextPage <= page) throw new Error('无有效下一页');
-    page = data.nextPage;
-  }
-}
-```
-
-返回 Outcome，accepted 需要 jobs 对账；不能提前宣称完成。引用约束或版本冲突应停止并评估，不自动连带删除 Topic/Source/Stream。恢复见[恢复](restore.md)。