@tier0/sdk-v2 0.2.2 → 0.4.0

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

@@ -1,6 +1,6 @@
 # 创建集合与记录
 
-元数据使用 metadataInsertOne（POST /openapi/v2/uns/metadata）或 metadataInsertMany；kind 指定 directory/topic/collection。单条提供 data、可选 id；批量提供同一 kind 的 documents[{id?,data}]。idempotencyKey 标识一个写入意图；dryRun=true 仅校验。schemaVersion 由服务端赋默认值。
+元数据使用 metadataInsertOne（POST /openapi/v2/uns/metadata）或 metadataBulkWrite 的 insertOne 项；kind 指定 directory/topic/collection。单条提供 data、可选 id；批量提供同一 kind 的 operations[{insertOne:{id?,data}}]。idempotencyKey 标识一个写入意图；dryRun=true 仅校验。schemaVersion 由服务端赋默认值。
 
 集合 data 必须包含 name、recordSchema，可选 description、parentId、sampleSchema、indexes、semantics。parentId=null 表示根目录。索引创建后仍需确认状态为 ready。
 
@@ -20,7 +20,7 @@ export async function createDeviceCollection(
       },
       sampleSchema: {
         type: 'object', additionalProperties: false, required: ['temperature'],
-        properties: { temperature: { type: 'number', unit: '°C' } },
+        properties: { temperature: { type: 'number', format: 'double', unit: '°C' } },
       },
     },
   };
@@ -28,13 +28,17 @@ export async function createDeviceCollection(
   if (preview.data.status !== 'validated') throw new Error('集合预检未通过');
   const receipt = await client.uns.metadataInsertOne({ ...request, dryRun: false, idempotencyKey: intentKey });
   if (receipt.data.status !== 'committed') return { state: 'unconfirmed' as const, receipt };
-  const current = await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: collectionId } });
-  if (!current.data.value) throw new Error('集合创建有回执，读回未确认');
-  return { state: 'committed' as const, receipt, current: current.data.value };
+  const current = await client.uns.metadataFind({ kind: 'collection', filter: { _id: collectionId }, limit: 1 });
+  if (!current.data.items[0]) throw new Error('集合创建有回执，读回未确认');
+  return { state: 'committed' as const, receipt, current: current.data.items[0] };
 }
 ```
 
-单条新增默认返回 insertedId/status/replayed。需要创建后的数据、revision 和时间戳时，传 returnDocument:'after'，同一次写入返回 value，无需再查询；可配合 projection，调用者必须同时具有读取权限。幂等重放返回原始创建快照，后续读取最新状态仍用 recordGet/recordFind。dryRun 的 value 是未提交预览。
+单条 Record 新增默认返回 insertedId/status/replayed。需要创建后的数据、revision 和时间戳时，传 returnDocument:'after'，同一次写入返回 value，无需再查询；可配合 projection，调用者必须同时具有读取权限。幂等重放返回原始创建快照，后续读取最新状态仍用 recordGet/recordFind。dryRun 的 value 是未提交预览。
+
+returnDocument 只允许 none（默认）或 after，不支持 before；projection 只能和 after 一起传。新增仍是 insert，已存在的 ID 不会变成更新。after 的 value 包括服务端补入的字段，但只返回当前授权可见的数据：普通数据权限需 uns.write 和 uns.read，App 还要满足集合的 record:write / record:read 及当前员工、行和字段策略。服务端在提交前校验读取权限，重放时也重新校验；旧回执不能绕过已撤销的授权。
+
+省略 returnDocument 与显式 none 保持相同幂等语义。不能用同一个意图键把原来的 none 改成 after 补取快照，否则返回 IDEMPOTENCY_CONFLICT；已创建的记录应改用读取接口。after 重放可对原始快照应用 projection，但不会变成最新记录。创建快照中的 revision 可用于下一次修改；若已有并发修改，版本冲突仍需显式处理。
 
 批量新增返回 insertedCount/insertedIds 及适用的逐项错误。insertedIds 的键是原始输入从 0 开始的索引。省略自定义 ID 时从成功回执取得实际 ID，不能把名称当成 ID。
 

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

@@ -23,7 +23,7 @@ export async function deleteDevice(
 }
 ```
 
-元数据使用 metadataDeleteOne/Many，或 metadataFindOneAndDelete 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。引用约束与版本冲突必须处理，不能自行扩展删除范围。
+元数据使用 metadataDeleteOne/Many，或 metadataDeleteOne + returnDocument:before 返回删除前对象。它们执行软删除，增加 revision，不隐式级联目录后代、引用对象或集合数据。引用约束与版本冲突必须处理，不能自行扩展删除范围。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
@@ -31,7 +31,7 @@ import { createClient, type Tier0Client } from '@tier0/sdk-v2';
 export async function deleteCollection(
   id: string, intentKey: string, client: Tier0Client = createClient(),
 ) {
-  const current = (await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id } })).data.value;
+  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
   if (!current) throw new Error('集合不存在或不可见，未执行删除');
   const receipt = await client.uns.metadataDeleteOne({
     kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
@@ -40,9 +40,9 @@ export async function deleteCollection(
   if (receipt.data.status !== 'committed' || String(receipt.data.deletedCount) !== '1') {
     return { state: 'unconfirmed' as const, receipt };
   }
-  const deleted = await client.uns.metadataFindOne({ kind: 'collection', filter: { _id: id }, state: 'deleted' });
-  if (!deleted.data.value) throw new Error('删除有回执，但删除状态读回未确认');
-  return { state: 'deleted' as const, receipt, deleted: deleted.data.value };
+  const deleted = await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, state: 'deleted', limit: 1 });
+  if (!deleted.data.items[0]) throw new Error('删除有回执，但删除状态读回未确认');
+  return { state: 'deleted' as const, receipt, deleted: deleted.data.items[0] };
 }
 ```
 

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

@@ -4,15 +4,15 @@
 
 | 场景 | 方法 |
 | --- | --- |
-| 单条/批量新增 | metadataInsertOne / metadataInsertMany |
+| 单条/批量新增 | metadataInsertOne / metadataBulkWrite 的 insertOne 项 |
 | 单条/批量条件更新 | metadataUpdateOne / metadataUpdateMany |
-| 更新并读取原子结果 | metadataFindOneAndUpdate / metadataFindOneAndReplace |
+| 更新并读取原子结果 | metadataUpdateOne / metadataReplaceOne + returnDocument:before/after |
 | 同 kind 混合写入 | metadataBulkWrite |
 | 跨 kind、有依赖的组合操作 | metadataTransact |
-| 软删除并返回原对象 | metadataFindOneAndDelete |
+| 软删除并返回原对象 | metadataDeleteOne + returnDocument:before |
 | 按明确 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 中分别提供。
+普通写操作只指定一个 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 中分别提供。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';

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

@@ -3,23 +3,24 @@
 | 方法 | 必要输入 | 返回 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 |
+| metadataFind + limit:1 | kind、filter；可选 state | 取 items[0]，空结果视为未匹配 |
+| metadataCount / metadataAggregate | kind/kinds 与查询条件；去重 pipeline 为 [{ $distinct: field }] | count / items、pageInfo；去重每项为 {value} |
 | 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。
+元数据查询配置字段写 name、parentId；系统字段写 _id、_meta.kind、_meta.revision。返回资源的配置在 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 collection = await client.uns.metadataFind({ kind: 'collection', filter: { _id: collectionId }, limit: 1 });
+  const definition = collection.data.items[0];
+  if (!definition) 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 };
+  return { definition: definition.data, items: records.data.items, pageInfo: records.data.pageInfo };
 }
 
 export async function listCollections(page = 1, client: Tier0Client = createClient()) {
@@ -31,4 +32,4 @@ export async function listCollections(page = 1, client: Tier0Client = createClie
 
 按 pageInfo.hasMore/nextPage 继续元数据分页；不要把第一页当全量。recordFind 的游标循环见[数据工作流](data-workflows.md)。sort 是数组元组。
 
-以上 metadataFind/FindOne 示例用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind/FindOne：用 dataAppContext 精确选择授权 alias，集合的 revision、indexStatus、ttl 也在其中。数据授权不等于元数据管理授权。网络/权限错误必须传播，不能用空数组掩盖错误。
+以上 metadataFind 示例用于 Workspace 集成（会话、personal / agent Key）。App 凭证不能调用 metadataFind：用 dataAppContext 精确选择授权 alias，集合的 revision、indexStatus、ttl 也在其中。数据授权不等于元数据管理授权。网络/权限错误必须传播，不能用空数组掩盖错误。

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

@@ -8,7 +8,7 @@ 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;
+  const deleted = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, state: 'deleted', limit: 1 })).data.items[0];
   if (!deleted) throw new Error('未找到待恢复集合');
   const receipt = await client.uns.metadataRestore({
     kind: 'collection', items: [{ id, expectedRevision: deleted.revision }], idempotencyKey: intentKey,
@@ -16,7 +16,7 @@ export async function restoreCollection(
   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;
+  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
   if (!current) throw new Error('恢复有回执，读回未确认');
   return { state: 'committed' as const, receipt, current };
 }

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

@@ -1,6 +1,6 @@
 # 修改记录、元数据和 Schema
 
-元数据单条使用 metadataUpdateOne 或 metadataFindOneAndUpdate；后者原子返回 value，returnDocument 可选 before/after。批量相同更新使用 metadataUpdateMany；不同更新使用 metadataBulkWrite。完整替换使用 metadataReplaceOne/metadataFindOneAndReplace，replacement 是完整可写配置。
+元数据单条使用 metadataUpdateOne；returnDocument 默认 none，需要原子返回 value 时显式传 before/after。批量相同更新使用 metadataUpdateMany；不同更新使用 metadataBulkWrite。完整替换使用 metadataReplaceOne，replacement 是完整可写配置。
 
 update 首版支持 $set/$unset/$setOnInsert。字段使用裸配置路径；_id/_meta 为只读。写前读取 revision，编辑页面携带 expectedRevision，冲突后重新比较。单条 upsert 需明确 _id 等值条件，新增内容满足完整创建约束；同 ID 的软删除对象必须显式恢复。
 
@@ -10,9 +10,9 @@ 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;
+  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
   if (!current) throw new Error('集合不存在或不可见');
-  return client.uns.metadataFindOneAndUpdate({
+  return client.uns.metadataUpdateOne({
     kind: 'collection', filter: { _id: id }, expectedRevision: current.revision,
     update: { $set: { name } }, returnDocument: 'after', upsert: false, idempotencyKey: intentKey,
   });
@@ -27,7 +27,7 @@ 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;
+  const current = (await client.uns.metadataFind({ kind: 'collection', filter: { _id: id }, limit: 1 })).data.items[0];
   if (!current) throw new Error('集合不存在或不可见');
   const request = { kind: 'collection' as const, filter: { _id: id },
     expectedRevision: current.revision, update: { $set: { recordSchema } } };