@tier0/sdk-v2 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,64 @@
+---
+name: tier0-sdk-v2-system
+description: 使用 @tier0/sdk-v2 查询 Tier0 凭证身份、平台版本、MQTT Broker 与能力就绪状态，区分身份、授权、发布开关和实际可用性。
+---
+
+# 系统与能力发现
+
+| 任务 | 参考 |
+| --- | --- |
+| 诊断 Key 所属 Workspace 和权限 | [whoami](references/whoami.md) |
+| 查看平台版本、解析 Broker 地址 | [info](references/info.md) |
+
+v1 的内部 reload 接口不属于 v2 公共 SDK，不能在普通诊断时调用。
+
+使用服务端 `createClient()` 或显式传入 apiHost/apiKey。系统排查从只读信息开始，不因功能不可用自动创建 Key、修改权限或部署服务。
+
+## 最小诊断
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function diagnose() {
+  const client = createClient();
+  const identity = await client.system.whoami();
+  const info = await client.system.info();
+  const discovery = await client.capabilities.discover();
+  return {
+    workspaceId: String(identity.workspaceID),
+    keyType: identity.keyType,
+    platformVersion: info.version,
+    capabilities: discovery.capabilities.map(item => ({
+      code: item.code, state: item.state, allowed: item.allowed,
+      availability: item.availability,
+    })),
+  };
+}
+```
+
+whoami 返回 Key 关联的主体与 Workspace，包括 userID、workspaceID、permissions、roles、keyType；它不是当前浏览器员工的身份证明。不要将关联 userID 当作 App 请求的当前访问者。
+
+info 返回 name/version/mqttBroker/capabilities，字段可能省略。MQTT broker 地址先用 `toWebSocketUrl` 转换，详见 [MQTT](../tier0-sdk-v2-mq/SKILL.md)。info 中的 capabilities 字符串列表不替代完整能力发现。
+
+## 读懂能力结果
+
+| 字段/状态 | 判断 |
+| --- | --- |
+| releaseEnabled | 平台/Workspace 发布开关，不代表运行时已准备好 |
+| allowed | 当前身份的授权摘要，不是所有具体 Control 的执行许可 |
+| enabled、state=ready | 服务端评估就绪 |
+| availability=available | 能力可用性，不是设备在线、业务执行或 ACK |
+| disabled / not_supported / unavailable | 展示具体不可用原因，不强制调用 |
+| readiness_unknown | 保留未知状态，不能按成功处理 |
+
+能力目录当前识别 namespace.v2、source.v1、stream.v2、control.v1、control.invoke.v1。contractVersions、apiContractVersions、sdkContractVersions 是契约标签，不是 npm 包版本；productVersion 未配置时可缺省。
+
+## 定位问题
+
+- 401/403：核对目标 Host、Key 对应 Workspace 和所需权限；不输出完整 Key。
+- 方法存在但能力关闭：记录 code/state/availability，检查该环境的部署与配置，不能凭本地生成文件推断线上已支持。
+- `CapabilityError`：保留 status/errorCode；不支持的契约版本与错误响应格式需要排查服务端/SDK 配套版本。
+- 系统普通 API 使用 `ApiError`，HTTP 200 的业务失败仍会抛错。
+- 仅上报排查需要的字段；whoami 中的邮箱、角色和 Key 前缀不应无差别返回给浏览器。
+
+需要 Source/Stream 运行健康信息时，进一步使用对应领域的 observations/runs；系统能力就绪只说明可以进入该领域流程。

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

@@ -0,0 +1,23 @@
+# 服务信息与 MQTT 地址
+
+方法：`system.info()`；POST /openapi/v1/info，无业务参数。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+import { parseMqttBroker, toWebSocketUrl } from '@tier0/sdk-v2/mq';
+
+export async function inspectService(client: Tier0Client = createClient()) {
+  const info = await client.system.info();
+  const endpoint = parseMqttBroker(info.mqttBroker);
+  return {
+    name: info.name, version: info.version, capabilities: info.capabilities,
+    mqtt: endpoint && info.mqttBroker ? toWebSocketUrl(info.mqttBroker) : undefined,
+  };
+}
+```
+
+返回已解包对象，name/version/capabilities/mqttBroker 均可能省略。mqttBroker 是连接串，可能裸 host、host:port、tcp://host:1883 或完整 ws/wss，不能直接拼 wss:// 前缀。toWebSocketUrl 保留已有 WebSocket URL；TCP 端口不直接复用为 WebSocket 端口。实际端口/路径由环境决定。
+
+info.capabilities 的简略字符串列表不是就绪证明。进一步读取 client.capabilities.discover 的 releaseEnabled、allowed、state、availability，区分开关、授权与运行能力；详见[系统 Skill](../SKILL.md)。
+
+v1 的 /gw/reload 是内部管理操作，未纳入 v2 公共 SDK，不复制旧 reload 示例，也不在连通性诊断中尝试重载服务。

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

@@ -0,0 +1,21 @@
+# API Key 身份诊断
+
+方法：`system.whoami()`；POST /openapi/v1/auth/whoami，无业务参数。不是调用其他 API 的强制前置步骤。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function inspectCredential(client: Tier0Client = createClient()) {
+  const identity = await client.system.whoami();
+  return {
+    workspaceId: String(identity.workspaceID), workspaceName: identity.workspaceName,
+    keyType: identity.keyType, permissions: identity.permissions, roles: identity.roles,
+  };
+}
+```
+
+返回已解包的 userID/userName/email/workspaceID/workspaceName/apiKeyName/keyPrefix/permissions/roles/keyType。v2 对大整数保留 number|bigint，不能套用 v1 “一定已经丢精度”的描述；需要字符串时用 String，不先转 Number。
+
+App Key 是共享业务凭证，不代表访问 App 的自然人。whoami 不能用于登录、当前用户、操作人审计或选择通知收件人；当前人来自应用认证会话，收件人从成员数据解析。
+
+401 核对 Host/Key，403 核对权限；不要输出完整 Key、无差别展示邮箱或所有角色，也不自动换更高权限身份。

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

@@ -0,0 +1,53 @@
+---
+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

@@ -0,0 +1,85 @@
+# 创建集合与记录
+
+| 方法 | 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/data-workflows.md

@@ -0,0 +1,73 @@
+# UNS 分页、采样与写入恢复
+
+## 完整游标遍历
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function* scanRecords(collectionId: string, signal?: AbortSignal) {
+  const client = createClient();
+  let cursor: string | undefined;
+  const seen = new Set<string>();
+  while (true) {
+    const { data } = await client.uns.recordFind({ collectionId, limit: 200, cursor }, { signal });
+    yield data.items;
+    if (!data.pageInfo.hasMore) return;
+    const next = data.pageInfo.nextCursor;
+    if (!next || seen.has(next)) throw new Error('服务端未返回可继续的游标');
+    seen.add(next);
+    cursor = next;
+  }
+}
+```
+
+消费方逐批处理以避免无限堆积内存；需要截止时用 AbortSignal。分页保证按返回游标继续，不保证跨请求保留相同行版本；导出审计要求一致快照时必须另行确认后端能力。
+
+## 历史采样
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function readHistory(collectionId: string, recordId: string, from: number, to: number) {
+  if (!Number.isSafeInteger(from) || !Number.isSafeInteger(to) || from < 0 || to <= from) {
+    throw new Error('时间应为有效的 Unix 毫秒范围');
+  }
+  return createClient().uns.sampleFind({
+    collectionId, recordIds: [recordId], from, to, limit: 200,
+  });
+}
+```
+
+返回可能分页；page 模式与 limit/cursor 互斥。Record 是业务实体，Sample 是该实体的时间序列，不用覆盖 Record 伪装保存历史。sampleDeleteRange 删除明确的时间范围，与删除 Record 的操作不可混淆。
+
+## 写入、事务与恢复
+
+```ts
+import { createClient, UnsV2Error, UnsV2OutcomeUnknownError, type UnsV2JSONValue } from '@tier0/sdk-v2';
+
+export async function insertRecord(collectionId: string, id: string, data: Record<string, UnsV2JSONValue>, intentKey: string) {
+  try {
+    return await createClient().uns.recordInsertOne({
+      collectionId, id, data, dryRun: false, idempotencyKey: intentKey,
+    });
+  } catch (error) {
+    if (error instanceof UnsV2OutcomeUnknownError) {
+      return { state: 'unknown' as const, requestId: error.requestId };
+    }
+    if (error instanceof UnsV2Error) {
+      return { state: 'rejected' as const, code: error.code, retryAdvice: error.retryAdvice };
+    }
+    throw error;
+  }
+}
+```
+
+该函数执行真实写入，仅用于已授权的新增意图。unknown 时按指定 id 读取并核对业务内容；不能只凭记录存在就判定本次成功。
+
+recordTransactionExecute 用 opId/dependsOn 表达依赖；不要拆成若干普通请求后声称具备事务性。allowPartial 适用于支持它的普通数组写入，事务不接受。部分成功检查每项结果，修正后的失败项是新的业务请求，不能原样重放整个批次。
+
+recordLock 返回的 token 是租约凭据，更新/续租/解锁按原记录匹配；超时或租约失效不能继续假定持锁。只读响应中的 lock 状态不包含可用于写入的令牌。
+
+## 变更轮询
+
+recordChangesPoll 使用 collectionId、可选 recordIds/cursor/limit/waitMs；limit 最大 100，waitMs 最大 5000。保存返回游标并在取消或目标完成后停止。收到变更后按事件语义重新读取需要的记录；这不是任意 SQL CDC，也不代表有 Source/Stream 管理权限。

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

@@ -0,0 +1,69 @@
+# 删除记录与归档集合
+
+集合没有 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)。

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

@@ -0,0 +1,75 @@
+# 目录和 Topic
+
+目录组织资源，Topic 是集合的 records/fields 视图，不是旧架构 Metric。增删改查使用 client.uns 的 directory*/topic*。
+
+| 操作 | 目录 | Topic | 关键参数 |
+| --- | --- | --- | --- |
+| 创建 | directoryCreate | topicCreate | dryRun、items；名称必填，Topic 另需 viewMode |
+| 查询 | directoryList/Get | topicList/Get | list 的 page/size/search/archived；get 的 id |
+| 改元数据 | directoryUpdate | topicUpdate | items[].id、expectedRevision、name/description/parentId |
+| 归档 | directoryArchive | topicArchive | items[].id、expectedRevision |
+| 恢复 | directoryRestore | topicRestore | 归档对象的 id 和当前 revision |
+| 改字段映射 | — | topicBindingsUpdate | 按 Topic 字段绑定契约 |
+
+创建/更新/归档/恢复均返回 Outcome；检查 committed、results[].error。目录/Topic 的删除语义是归档，不存在 directoryDelete/topicDelete。parentId=null 表示根；更新时省略则保持原位置。归档不能自行扩展成递归清空所有后代或关联集合。
+
+## 创建目录和集合视图
+
+以下函数独立调用；不要把创建目录后创建 Topic 说成一个原子事务。collectionId 先从集合查询取得。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function createDirectory(
+  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.directoryCreate({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, name, parentId: null }],
+  });
+  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.directoryGet({ id })).data };
+}
+export async function createRecordTopic(
+  id: string, name: string, collectionId: string, parentId: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.topicCreate({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, name, viewMode: 'records', collectionId, parentId }],
+  });
+  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.topicGet({ id })).data };
+}
+```
+
+## 修改与归档 Topic
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameTopic(
+  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = await client.uns.topicGet({ id });
+  return client.uns.topicUpdate({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, name, expectedRevision: current.data.revision }],
+  });
+}
+export async function archiveTopic(
+  id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const current = await client.uns.topicGet({ id });
+  return client.uns.topicArchive({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, expectedRevision: current.data.revision }],
+  });
+}
+```
+
+调用后检查 Outcome；修改后 get 核对名称，归档后 topicList({archived:true}) 遍历核对 ID。目录使用对应 directoryGet/Update/Archive；恢复从归档列表取得当前修订再 Restore，最后 get 核对。不要把 Topic 归档解释成底层 Record 已删除。

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

@@ -0,0 +1,32 @@
+# 查询集合与记录
+
+| 方法 | 必要输入 | 返回 data |
+| --- | --- | --- |
+| collectionList | 可选 page、size、search、archived | list、total、hasMore、nextPage |
+| collectionGet | id | kind、id、revision、data（Schema/元数据） |
+| collectionDescribe | collectionId | 集合结构和数据能力 |
+| recordFind | collectionId；可选 filter、sort、limit、cursor | items、pageInfo |
+| recordCount | collectionId；可选 filter | 计数结果 |
+
+集合详情有两层 data：响应.data 是资源，响应.data.data 才是集合定义。记录行是 `{id,data,revision,…}`，过滤业务路径用 name，系统字段用 _id、_meta.revision；不要写 data.name。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function readDevices(collectionId: string, client: Tier0Client = createClient()) {
+  const collection = await client.uns.collectionGet({ id: collectionId });
+  const records = await client.uns.recordFind({
+    collectionId, filter: { enabled: true }, sort: [['name', 1]], limit: 20,
+  });
+  return { schema: collection.data.data.recordSchema, items: records.data.items,
+    pageInfo: records.data.pageInfo };
+}
+export async function readDevice(collectionId: string, id: string, client: Tier0Client = createClient()) {
+  const result = await client.uns.recordFind({ collectionId, filter: { _id: id }, limit: 1 });
+  return result.data.items[0] ?? null;
+}
+```
+
+recordFind 的 limit 为 1–200；按 pageInfo.hasMore/nextCursor 继续，完整循环见[数据工作流](data-workflows.md)。不要把第一页当全量，sort 是数组，不是 MongoDB 对象。
+
+App 使用 dataAppContext 精确选择授权 alias；Workspace 集成使用 dataDiscover/collectionList。数据访问授权不等于集合管理授权。网络/权限错误必须传播，不能返回空数组掩盖错误。

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

@@ -0,0 +1,41 @@
+# 恢复集合与记录
+
+| 方法 | 输入 | 返回 |
+| --- | --- | --- |
+| collectionRestore | dryRun、items[{id,expectedRevision}]、可选 mode/idempotencyKey | Outcome |
+| recordRestore | collectionId、ids（1–100）、可选 dryRun/idempotencyKey | restoredCount、restoredIds、status、replayed |
+
+集合 ID 和修订从 collectionList({archived:true,…}) 的实际归档项取得；不要使用归档前的旧修订。
+
+```ts
+import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
+
+export async function restoreCollection(
+  id: string, expectedRevision: NonNullable<UnsV2Request<'collectionRestore'>['items'][number]['expectedRevision']>,
+  intentKey: string, client: Tier0Client = createClient(),
+) {
+  const receipt = await client.uns.collectionRestore({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, expectedRevision }],
+  });
+  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 })).data };
+}
+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 恢复重新校验当前 Schema 和有效唯一索引，冲突整批回滚；revision 递增。删除记录时关联 Sample 已物理删除，恢复不会重建历史。幂等键每个新意图独立，未知结果不要换键重试。

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

@@ -0,0 +1,86 @@
+# 修改记录、集合元数据和 Schema
+
+| 方法 | 关键输入 | 语义 |
+| --- | --- | --- |
+| recordUpdateOne | collectionId、filter、update、expectedRevision | 修改一个精确目标 |
+| collectionUpdate | dryRun、items[].id/name/description/parentId/expectedRevision | 修改元数据 |
+| collectionSchemaUpdate | dryRun、items[].id/recordSchema/expectedRevision | 替换 recordSchema |
+
+写前读取 revision；冲突后重新比较并决策。省略 expectedRevision 可能覆盖最新状态，示例始终携带。
+
+## 修改一条设备记录
+
+```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 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.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] };
+}
+```
+
+data 返回 matchedCount、modifiedCount、status、replayed。modifiedCount=0 可能是值未变化；不能据此断言请求失败。upsert=false 避免不存在时意外创建。批量修改只在明确筛选范围和授权内使用。
+
+## 修改集合名称
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function renameCollection(
+  id: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const { data: current } = await client.uns.collectionGet({ id });
+  const receipt = await client.uns.collectionUpdate({
+    dryRun: false, mode: 'sync', allowPartial: false, idempotencyKey: intentKey,
+    items: [{ id, name, expectedRevision: current.revision }],
+  });
+  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 })).data };
+}
+```
+
+## 扩展 Schema：添加可选位置字段
+
+```ts
+import { createClient, type Tier0Client, type Schema } from '@tier0/sdk-v2';
+
+export async function addDeviceLocation(
+  id: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const { data: current } = await client.uns.collectionGet({ id });
+  if (current.data.recordSchema.type !== 'object') throw new Error('此示例仅支持对象 Schema');
+  if (current.data.recordSchema.properties?.location) throw new Error('location 已定义，应先比较原 Schema');
+  const recordSchema: Schema = {
+    ...current.data.recordSchema,
+    properties: { ...current.data.recordSchema.properties, location: { type: 'string' } },
+  };
+  const item = { id, expectedRevision: current.revision, recordSchema };
+  const preview = await client.uns.collectionSchemaUpdate({ dryRun: true, mode: 'sync', items: [item] });
+  if (preview.data.status !== 'validated') throw new Error('Schema 预检未通过');
+  const receipt = await client.uns.collectionSchemaUpdate({
+    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 })).data };
+}
+```
+
+recordSchema 是完整替换，不是 merge patch，也不自动迁移记录。新 Schema 必须接受已有数据并满足相关引用约束。sampleSchema/indexes 省略时保留；不要为了添加一个字段顺手清空它们。收紧类型、增加必填或删除采样 Schema 需额外评估已有数据。