@tier0/sdk-v2 0.2.1 → 0.3.0

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/deploy.md

@@ -3,31 +3,41 @@
 | 方法 | POST 路径 | 必要参数 |
 | --- | --- | --- |
 | programs.deploy | /openapi/v2/uns/streams/program/deploy | id、dryRun；建议 expectedRevision |
-| programs.disable | /openapi/v2/uns/streams/program/disable | id、dryRun；建议 expectedRevision |
 | programs.rollback | /openapi/v2/uns/streams/program/rollback | id、versionId、dryRun；建议 expectedRevision |
 | documents.disable | /openapi/v2/uns/streams/documents/disable | id、expectedRevision、expectedActiveRelease、dryRun |
 
 全部写操作使用各自的 idempotencyKey。expectedSourceRevision 只适用于恰好一个 Source 依赖，且同时保护草稿冻结修订与当前 Source head；多源不能塞入单个修订值。原生文档没有 documents.deploy，当前云端 program 模型发布走 programs.deploy。
 
+发布、停用和回滚需要 uns.stream.manage；相关 Source 访问还受各自授权约束。保存回执中的 revision、发布回执中的 activeVersion 与 activeRelease 分别用于不同目的：
+
+| 字段 | 含义与用途 |
+| --- | --- |
+| revision | 草稿修订；传给下次写入的 expectedRevision，冲突时显式处理 |
+| activeVersion | 不可变发布版本 ID；回滚的 versionId 使用这个 ID，不使用发布序号 |
+| activeRelease | 本次事务记录的正整数发布序号；与 runs.list 中的 release 对照；无活跃发布或旧回执未记录时省略 |
+
+programs 回执的 activeVersion:'0' 表示无活跃版本；新增 activeRelease 不用 0 表示未发布。原生 documents 回执的既有 activeRelease 约定不变。
+
 ```ts
-import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { createClient, type Tier0Client, type CloudStreamDocumentView } from '@tier0/sdk-v2';
 
-export async function deployStream(id: string, intentKey: string, client: Tier0Client = createClient()) {
-  const { data: current } = await client.stream.documents.get({ id, view: 'full' });
-  if (!('document' in current)) throw new Error('需要完整 Stream 文档');
+export async function deployStream(current: CloudStreamDocumentView, intentKey: string, client: Tier0Client = createClient()) {
   const sources = current.document.sources ?? [];
   const request = {
-    id, expectedRevision: current.revision,
+    id: current.id, expectedRevision: current.revision,
     ...(sources.length === 1 ? { expectedSourceRevision: sources[0]!.configRevision } : {}),
   };
   const receipt = await client.stream.programs.deploy({
     ...request, dryRun: false, idempotencyKey: intentKey,
   });
-  if (typeof receipt.data.activeVersion !== 'string' || receipt.data.activeVersion === '0') {
+  if (!('id' in receipt.data) || receipt.data.activeVersion === '0') {
     throw new Error('未确认发布版本');
   }
-  return { receipt, current: (await client.stream.documents.get({ id })).data,
-    observation: (await client.stream.observations.get({ id })).data };
+  const release = receipt.data.activeRelease;
+  if (release === undefined || BigInt(String(release)) <= 0n) {
+    throw new Error('历史回执缺少发布编号；保留原请求，不用当前发布编号替代');
+  }
+  return { receipt, release };
 }
 
 export async function disableStream(id: string, intentKey: string, client: Tier0Client = createClient()) {
@@ -43,7 +53,7 @@ export async function disableStream(id: string, intentKey: string, client: Tier0
 }
 ```
 
-发布成功不表示外部连接健康或每次执行成功；检查 observation 与执行记录。停用保留草稿。仅修改草稿的任务不额外发布/停用。
+将创建或更新回执的 current 传给 deployStream，只发一次发布请求。只有手上没有草稿快照时才先 documents.get。使用 [按发布号查询运行记录](read.md#观察本次发布) 才能观察这次发布，观察窗口汇总不能证明该版本运行。发布成功不表示外部连接健康或执行成功。停用保留草稿。仅修改草稿的任务不额外发布/停用。
 
 ## 回滚到明确版本
 
@@ -61,4 +71,4 @@ export async function rollbackStream(
 }
 ```
 
-检查回执 activeVersion，并重新 get/observation。超时或 UnsV2OutcomeUnknownError 时先核对版本和观测，保留原请求意图键，不重复 deploy/rollback。预览用 dryRun=true，但不保证稍后的实际发布一定成功。
+检查回执 activeVersion 与 activeRelease。超时或 UnsV2OutcomeUnknownError 时保留原路由、载荷和幂等键；允许恢复时原样重发以取得原回执，不用新键再次发布。旧回执可能没有 activeRelease，不能读取当前 head 后冒充旧请求的发布编号。相同草稿使用不同键仍会创建新发布，expectedRevision 仅保护草稿修订。预览用 dryRun=true，返回 validated/sideEffects，不保证稍后的实际发布一定成功。

package/skills/tier0-sdk-v2/tier0-sdk-v2-stream/references/lifecycle.md

@@ -1,6 +1,6 @@
 # Stream 样例测试与流程衔接
 
-完整流程按任务选取：[创建](create.md) → [查询](read.md) → [修改](update.md) → [发布/停用/回滚](deploy.md) → [删除](delete.md)。不要为了完成一次查询自动执行整套流程。
+创建并发布时，将 [创建](create.md) 或 [修改](update.md) 回执中的草稿直接交给 [发布](deploy.md)，再用发布回执的 activeRelease [观察运行](read.md#观察本次发布)，无需在发布前后各 get 一次。只有缺少当前草稿、处理版本冲突或需要最新状态时才 [查询](read.md)。停用、回滚和 [删除](delete.md) 按任务选择，不自动执行整套生命周期。
 
 ## 原生文档样例测试
 

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

@@ -3,22 +3,20 @@
 | 方法 | POST 路径 | 输入 | 结果 |
 | --- | --- | --- | --- |
 | programs.list | /openapi/v2/uns/streams/program/list | page、size、search、sourceId、model、status、archived | list、total、hasMore、nextPage |
-| programs.get | /openapi/v2/uns/streams/program/get | id | 运行摘要，document 已脱敏 |
-| documents.get | /openapi/v2/uns/streams/documents/get | id | 完整草稿、revision、status、activeRelease、可选 activeDocument |
+| documents.get | /openapi/v2/uns/streams/documents/get | id；可选 view:summary/full | summary 返回摘要；full 返回完整草稿、revision、status、activeRelease、可选 activeDocument |
 | observations.get | /openapi/v2/uns/streams/observation/get | id | 运行观测 |
 | runs.list | /openapi/v2/uns/streams/runs/list | id、size、cursor | 执行记录 |
 | programs.versions.list | /openapi/v2/uns/streams/program/versions/list | id、page、size | list、total，含 versionId |
 
-page 从 1 开始，size 最大 200。完整文档需要 Stream manage 权限；programs.get 的 scriptConfigured 不是脚本内容，不能据此重建草稿。
+page 从 1 开始，size 最大 200。summary 只需 uns.stream.view 或 uns.stream.manage；full 或省略 view 需要 uns.stream.manage，API Key 还必须是 full_access。摘要不含脚本，不能据此重建草稿。已有创建或更新回执时可复用其文档与 revision，不必再读取。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
 
 export async function readStream(id: string, client: Tier0Client = createClient()) {
   const draft = await client.stream.documents.get({ id });
-  const summary = await client.stream.programs.get({ id });
   const observation = await client.stream.observations.get({ id });
-  return { draft: draft.data, summary: summary.data, observation: observation.data };
+  return { draft: draft.data, observation: observation.data };
 }
 export async function* listStreams(client: Tier0Client = createClient()) {
   let page = 1;
@@ -33,3 +31,25 @@ export async function* listStreams(client: Tier0Client = createClient()) {
 ```
 
 保存、发布、某次执行成功是三个事实。显示实际 revision/activeVersion/release，不用旧 runs 证明新版本生效。版本列表不保证与普通列表相同分页结构；按其 list/total/page/size 读取，versionId 不是 release 序号。
+
+## 观察本次发布
+
+把 deploy 回执的 activeRelease 原样传入，不需要先读取当前 head。runs.list 需要 uns.stream.view 或 uns.stream.manage；它没有服务端 release 过滤参数，按返回的 nextCursor 继续翻页并在客户端匹配发布号：
+
+```ts
+import { createClient, type Tier0Client, type UnsV2Integer } from '@tier0/sdk-v2';
+
+export async function readPublishedRuns(
+  id: string, release: UnsV2Integer, cursor?: string,
+  client: Tier0Client = createClient(),
+) {
+  if (typeof release === 'number' && !Number.isSafeInteger(release)) {
+    throw new Error('发布号必须保留回执中的精确整数，不能传已失真的 number');
+  }
+  if (BigInt(String(release)) <= 0n) throw new Error('需要发布回执中的正整数发布号');
+  const { data } = await client.stream.runs.list({ id, size: 100, ...(cursor ? { cursor } : {}) });
+  return { ...data, items: data.items.filter(run => run.release === String(release)) };
+}
+```
+
+此函数只读一页。items 为空但 nextCursor 非空时，下一页仍可能有匹配记录；达到调用方的观察时限就报告“尚未观察到”。匹配记录也要检查 status、entryId 和时间，不能把存在记录当成执行成功。历史幂等回执若缺少 activeRelease，应保留为未确认，不能用当前 head 的发布号代替。

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

@@ -21,16 +21,14 @@ export async function updateStreamDescription(
   const { data: current } = await client.stream.documents.get({ id, view: 'full' });
   if (!('document' in current)) throw new Error('需要完整 Stream 文档');
   const document: CloudStreamDocument = { ...current.document, description };
-  const checked = await client.stream.documents.validate({ document });
-  if (!checked.data.valid) throw new Error('Stream 文档校验失败，请检查 issues');
   const saved = await client.stream.documents.update({
     id, expectedRevision: current.revision, document, dryRun: false, idempotencyKey: intentKey,
   });
   if (!('id' in saved.data)) throw new Error('未返回已保存文档');
-  return { receipt: saved, current: (await client.stream.documents.get({ id })).data };
+  return { receipt: saved, current: saved.data };
 }
 ```
 
-需要改脚本时构造 `{ ...current.document, script: { ...current.document.script, code: newCode } }`，保留 sdkVersion/timeoutMs；变更入口或绑定时同步修改 entries/sources 并重新 validate。不要对脱敏 programs.get.document 做展开更新。
+代码应用可直接用 documents.update({id, expectedRevision, program, dryRun:false, idempotencyKey})，由服务端编译入口和绑定。编辑完整文档时保留 sdkVersion/timeoutMs，并同步 entries/sources；写入本身执行校验，只有需要提前展示问题时才单独 validate。不要对documents.get 的 summary 做展开更新。
 
-响应是完整 CloudStreamDocumentView 或预检结果；保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。下一步发布见[部署](deploy.md)。
+响应是完整 CloudStreamDocumentView 或预检结果；把 saved.data 直接传给下一步[发布示例](deploy.md)，无需为了 revision 再读取。已有当前完整文档时可省去示例最初的 get。保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。

package/skills/tier0-sdk-v2/tier0-sdk-v2-system/references/info.md

@@ -1,6 +1,6 @@
 # 服务信息与 MQTT 地址
 
-方法：`system.info()`；POST /openapi/v1/info，无业务参数。
+方法：`system.info()`；POST /openapi/v2/info，无业务参数。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';

package/skills/tier0-sdk-v2/tier0-sdk-v2-system/references/whoami.md

@@ -1,6 +1,6 @@
 # API Key 身份诊断
 
-方法：`system.whoami()`；POST /openapi/v1/auth/whoami，无业务参数。不是调用其他 API 的强制前置步骤。
+方法：`system.whoami()`；POST /openapi/v2/auth/whoami，无业务参数。不是调用其他 API 的强制前置步骤。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';

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

@@ -13,7 +13,7 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 | --- | --- | --- |
 | 创建集合、定义 Schema、新增记录 | [创建](references/create.md) | metadataInsertOne/Many、recordInsertOne |
 | 查询集合、筛选/排序记录 | [查询](references/read.md) | dataAppContext、metadataFind/FindOne（非 App 凭证）、collectionDescribe、recordFind |
-| 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many、metadataFindOneAndUpdate |
+| 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many |
 | 删记录、软删除集合 | [删除](references/delete.md) | recordDeleteOne、metadataDeleteOne/Many |
 | 恢复集合或记录 | [恢复](references/restore.md) | metadataRestore、recordRestore |
 | 分页、历史采样、事务、写入结果 | [数据工作流](references/data-workflows.md) | sampleFind、recordTransactionExecute |
@@ -42,7 +42,7 @@ export async function findAppCollection(alias: string) {
 ## 核心约束
 
 1. 记录行是 id/data/revision；filter 与 update 的业务路径用 name、customer.name，不加 data.；系统路径用 _id、_meta.revision。
-2. 改/删前读取 expectedRevision；不同操作使用独立意图键，长度上限以当前操作契约为准。
+2. 改/删使用最近写回执或读取取得的 revision 作为 expectedRevision；创建时可用 returnDocument:'after' 取得快照。历史重放不是当前最新版本，冲突时显式处理；不同操作使用独立意图键，长度上限以当前操作契约为准。
 3. metadataUpdateOne 的 $set.recordSchema 替换完整 Schema，不迁移已有记录；未更新的 sampleSchema/indexes 保留。先预检兼容性。
 4. 集合无硬删除入口，用 metadataDeleteOne/Many 软删除；Record 删除会物理删除关联 Sample，恢复 Record 不会恢复这些 Sample。
 5. recordFind 使用 pageInfo.hasMore/nextCursor，limit 1–200；sort 为 [['field',1]]。单页不是全量，跨页不是稳定快照。
@@ -50,6 +50,6 @@ export async function findAppCollection(alias: string) {
 
 ## 结果与异常
 
-响应为 code/msg/requestId/data。元数据 find 返回 items/pageInfo；findOne 与 findOneAnd* 返回 value；普通写入返回对应计数和 ID。metadataTransact 的 results 按 opId 对应。检查 committed、每项错误和实际计数；dryRun 只校验。metadataBulkWrite 默认原子，显式非原子时必须逐项检查 results/errors；跨 kind 的依赖写入使用 metadataTransact。recordBulkWrite 不保证跨集合事务。
+响应为 code/msg/requestId/data。元数据 find 返回 items/pageInfo；单条 updateOne/replaceOne/deleteOne 请求 returnDocument 时附带 value；普通写入默认返回对应计数和 ID。metadataTransact 的 results 按 opId 对应。检查 committed、每项错误和实际计数；dryRun 只校验。metadataBulkWrite 默认原子，显式非原子时必须逐项检查 results/errors；跨 kind 的依赖写入使用 metadataTransact。recordBulkWrite 不保证跨集合事务。
 
 大整数与 JSON 精确数字可能为 bigint/UnsV2RawNumber；保留读取到的 revision 类型，不用 Number 或普通 JSON.stringify 做无损往返。错误带 execution（notStarted / rolledBack / committed / unknown）与 retry（safe、afterMs）。UnsV2OutcomeUnknownError（execution 为 unknown）先读回核对内容；retry.safe 时可以用同一请求、同一幂等键原样重发。取消请求不撤销写入；client.uns 不自动重试。

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。
 
@@ -28,13 +28,19 @@ 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；批量新增返回 insertedCount/insertedIds 及适用的逐项错误。insertedIds 的键是原始输入从 0 开始的索引。省略自定义 ID 时从成功回执取得实际 ID，不能把名称当成 ID。
+单条 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。
 
 ```ts
 import { createClient, type Tier0Client } from '@tier0/sdk-v2';
@@ -44,12 +50,11 @@ export async function insertDevice(
   client: Tier0Client = createClient(),
 ) {
   const receipt = await client.uns.recordInsertOne({
-    collectionId, id, data: { name, enabled: true }, dryRun: false, idempotencyKey: intentKey,
+    collectionId, id, data: { name, enabled: true }, dryRun: false, idempotencyKey: intentKey, returnDocument: 'after',
   });
   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] };
+  if (!receipt.data.value) throw new Error('创建回执缺少请求的快照');
+  return { state: 'committed' as const, receipt, created: receipt.data.value };
 }
 ```
 

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 } } };