@tier0/sdk-v2 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,62 @@
+# 修改 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, view: 'full' });
+  if (!('document' in current)) throw new Error('需要完整 Source 文档');
+  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/tier0-sdk-v2-stream/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: tier0-sdk-v2-stream
+description: 使用 @tier0/sdk-v2 的 client.stream 创建、查询、修改和删除 Stream，绑定 Source，校验脚本，发布、停用、回滚及检查运行结果。
+---
+
+# Stream 处理与运行
+
+应用代码使用 client.stream；外部连接用 [Source](../tier0-sdk-v2-source/SKILL.md)，集合和记录用 [UNS](../tier0-sdk-v2-uns/SKILL.md)。服务端 `createClient()` 读取 TIER0_API_HOST / TIER0_API_KEY，也可显式传 apiHost/apiKey。
+
+## 按任务加载参考
+
+| 用户任务 | 参考 | 方法 |
+| --- | --- | --- |
+| 新建并绑定 HTTP Source | [创建](references/create.md) | programs.validate/create |
+| 列表、完整文档、运行记录 | [查询](references/read.md) | programs.list/get、documents.get、observations.get、runs.list |
+| 修改草稿、脚本和绑定 | [修改](references/update.md) | documents.validate/update |
+| 发布、停用、版本回滚 | [部署](references/deploy.md) | programs.deploy/rollback、documents.disable |
+| 删除并核验归档 | [删除](references/delete.md) | programs.delete |
+| 隔离样例测试、流程衔接 | [生命周期](references/lifecycle.md) | sampleTest |
+
+## 两种文档形态
+
+| 形态 | 完整输入 | 适用入口 |
+| --- | --- | --- |
+| Runtime program | name、sdkVersion、script 字符串、sourceBindings、timeoutMs | programs.create/update/validate |
+| 云端原生文档 | name、model、script 对象、sources、entries | documents.create/get/update/validate |
+
+程序必须是完整 `module.exports = api => { ... }`，执行器 API 是 api.sources/api.uns/api.stream，与 npm 包的 client.source 不同。Runtime sourceBindings 为 sourceId/configRevision/acquisition；原生 sources 还使用 alias/resources。连接凭据不进脚本或 acquisition。
+
+## 核心约束
+
+1. programs.get 返回脱敏摘要，不含可回写脚本；编辑必须 documents.get。保留未修改的 sources/entries/script 字段。
+2. create/update 保存草稿，不自动发布；documents 没有 deploy，云端 program 发布使用 programs.deploy。不能将已保存报告为已运行。
+3. 所有更新/部署/删除携带当前 expectedRevision。原生停用另需 expectedActiveRelease，避免停掉他人刚发布的版本。
+4. versionId 从 versions.list 取得，不把 release 序号当 ID。expectedSourceRevision 仅用于恰好一个依赖源，不代表多个源的修订。
+5. resources=[] 是空冻结资源集，不是通配符。先查询 runtime.capabilities，并让服务端 validate 检查能力；当前云端程序 timeoutMs 上限 30000。
+6. 仅执行用户要求的生命周期步骤；修改脚本不自动授予发布、停用或删除权限。
+
+## 成功与异常
+
+响应保留 code/msg/requestId/data。校验要检查 valid，样例要检查 completed/failed，删除要检查 deleted，发布要检查 activeVersion 和观测。样例 writePreview 不代表线上数据写入。
+
+UnsV2OutcomeUnknownError、发布超时或取消后先读取版本/观测对账，保留原请求意图键，不自动重复发布。版本冲突先比较当前草稿，不能忽略 expectedRevision。不同写入意图使用不同键；本地 SDK 测试不能代替目标环境联调。

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

@@ -0,0 +1,56 @@
+# 创建 Stream
+
+方法：`stream.programs.create`；POST `/openapi/v2/uns/streams/program/create`。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| dryRun | boolean | 是 | true 预检，false 保存草稿 |
+| document.name | string | 是 | 1–63 字符 |
+| document.sdkVersion | tier0-stream/v2 | 是 | 运行时脚本版本 |
+| document.script | string | 是 | 完整 module.exports 程序 |
+| document.timeoutMs | integer | 否 | 当前云端上限 30000 ms |
+| document.sourceBindings | array | 否 | sourceId、configRevision、acquisition |
+| idempotencyKey | string | 否 | 最多 128 字符，本次创建的固定意图键 |
+
+## HTTP Source 绑定示例
+
+先按[Source 查询](../../tier0-sdk-v2-source/references/read.md)选定真实 HTTP Source。脚本的 api.sources 属于平台执行器，与应用中的 client.source 不同。sourceId 保持字符串，configRevision 从完整源读取。
+
+```ts
+import { createClient, type Tier0Client, type RuntimeStreamDefinition } from '@tier0/sdk-v2';
+
+export async function createHttpStream(
+  sourceId: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  if (!/^[1-9][0-9]*$/.test(sourceId)) throw new Error('Source ID 必须是正十进制字符串');
+  const source = await client.source.documents.get({ id: sourceId, view: 'full' });
+  if (!('document' in source.data)) throw new Error('需要完整 Source 文档');
+  if (source.data.document.protocol !== 'http') throw new Error('此示例需要 HTTP Source');
+  const document: RuntimeStreamDefinition = {
+    name, sdkVersion: 'tier0-stream/v2', timeoutMs: 5000,
+    sourceBindings: [{ sourceId, configRevision: source.data.revision, acquisition: {} }],
+    script: [
+      'module.exports = api => {',
+      '  const upstream = api.sources.use({ id: ' + JSON.stringify(sourceId) + ', resources: [] });',
+      '  api.stream.onTimer({ id: "tick", intervalMs: 60000 }, async () => {',
+      '    const response = await upstream.request({ method: "GET", path: "orders" });',
+      '    return response.data;',
+      '  });',
+      '};',
+    ].join('\n'),
+  };
+  const validation = await client.stream.programs.validate({ document });
+  if (validation.data.valid !== true) throw new Error('Stream 校验未通过');
+  const saved = await client.stream.programs.create({
+    dryRun: false, document, idempotencyKey: intentKey,
+  });
+  if (typeof saved.data.id !== 'string') throw new Error('创建回执缺少 ID');
+  return { receipt: saved, current: (await client.stream.documents.get({ id: saved.data.id })).data };
+}
+```
+
+将 path="orders"、60 秒周期改为业务实际值。示例保存草稿，不部署，也不将返回值自动写入 UNS；需要写入集合时按执行器能力定义 api.uns 操作。resources=[] 是空冻结资源集，不是通配授权。源地址和凭据留在 Source，不能拷进 acquisition 或脚本。
+
+创建 data 是开放对象，成功返回 id、revision、activeVersion、executionState、脱敏 document；以实际字段判断，预检不生成 ID。当前后端创建/校验需要注册 Worker 可用。TEMPORARILY_UNAVAILABLE 不代表脚本一定错误；不要自动改用旧 Flow。
+
+原生编辑器形态 `documents.create({dryRun, document})` 的 document 为 name/model/script对象/sources/entries，script 为 `{sdkVersion,code,timeoutMs}`，sources 用 alias/sourceId/configRevision/resources/acquisition。不要把上面的 script 字符串直接塞入原生文档。

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

@@ -0,0 +1,35 @@
+# 删除 Stream
+
+方法：`stream.programs.delete`；POST `/openapi/v2/uns/streams/program/delete`。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | string | 是 | 十进制字符串 |
+| expectedRevision | integer | 建议提供 | 当前 get 返回修订 |
+| dryRun | boolean | 是 | true 预检；false 提交 |
+| idempotencyKey | string | 否 | 最多 128 字符 |
+
+先读取明确目标并评估活跃发布/调用依赖。停止运行与删除是两个操作，删除请求不自动授予对 Source/UNS 数据的清理权限。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function deleteStream(id: string, intentKey: string, client: Tier0Client = createClient()) {
+  const { data: current } = await client.stream.documents.get({ id });
+  const receipt = await client.stream.programs.delete({
+    id, expectedRevision: current.revision, dryRun: false, idempotencyKey: intentKey,
+  });
+  if (!('deleted' in receipt.data) || receipt.data.deleted !== true) throw new Error('未确认删除');
+  let page = 1;
+  while (true) {
+    const { data } = await client.stream.programs.list({ archived: true, page, size: 200 });
+    const archived = data.list.find(item => item.id === id);
+    if (archived) return { receipt, archived };
+    if (!data.hasMore) return { receipt, archived: undefined };
+    if (typeof data.nextPage !== 'number' || data.nextPage <= page) throw new Error('无有效下一页');
+    page = data.nextPage;
+  }
+}
+```
+
+成功 data 为 `{id,revision,deleted:true}`；预检为 `{validated:true,sideEffects:false}`。归档列表额外核验，未查到时报告“删除有回执，读回未确认”。不要捕获所有 get 异常并返回删除成功。并发冲突重新评估，不用无版本保护的请求覆盖。

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

@@ -0,0 +1,64 @@
+# 发布、停用与回滚 Stream
+
+| 方法 | 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。
+
+```ts
+import { createClient, type Tier0Client } 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 文档');
+  const sources = current.document.sources ?? [];
+  const request = {
+    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') {
+    throw new Error('未确认发布版本');
+  }
+  return { receipt, current: (await client.stream.documents.get({ id })).data,
+    observation: (await client.stream.observations.get({ id })).data };
+}
+
+export async function disableStream(id: string, intentKey: string, client: Tier0Client = createClient()) {
+  const { data: current } = await client.stream.documents.get({ id });
+  if (String(current.activeRelease) === '0') throw new Error('没有活跃发布可停用');
+  const receipt = await client.stream.documents.disable({
+    id, expectedRevision: current.revision, expectedActiveRelease: current.activeRelease,
+    dryRun: false, idempotencyKey: intentKey,
+  });
+  const after = await client.stream.documents.get({ id });
+  if (String(after.data.activeRelease) !== '0') throw new Error('停用读回未确认');
+  return { receipt, current: after.data };
+}
+```
+
+发布成功不表示外部连接健康或每次执行成功；检查 observation 与执行记录。停用保留草稿。仅修改草稿的任务不额外发布/停用。
+
+## 回滚到明确版本
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function rollbackStream(
+  id: string, versionId: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  // versionId 必须先从 programs.versions.list({id,page,size}) 查询并选定。
+  const { data: current } = await client.stream.documents.get({ id });
+  return client.stream.programs.rollback({
+    id, versionId, expectedRevision: current.revision, dryRun: false, idempotencyKey: intentKey,
+  });
+}
+```
+
+检查回执 activeVersion，并重新 get/observation。超时或 UnsV2OutcomeUnknownError 时先核对版本和观测，保留原请求意图键，不重复 deploy/rollback。预览用 dryRun=true，但不保证稍后的实际发布一定成功。

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

@@ -0,0 +1,26 @@
+# Stream 样例测试与流程衔接
+
+完整流程按任务选取：[创建](create.md) → [查询](read.md) → [修改](update.md) → [发布/停用/回滚](deploy.md) → [删除](delete.md)。不要为了完成一次查询自动执行整套流程。
+
+## 原生文档样例测试
+
+方法：stream.sampleTest；输入 document、entryId、input。document 来自 documents.get 的完整草稿，entryId 必须在该文档注册的 entries 内。
+
+```ts
+import { createClient, type Tier0Client, type UnsV2JSONValue } from '@tier0/sdk-v2';
+
+export async function testStreamSample(
+  id: string, entryId: string, input: UnsV2JSONValue, client: Tier0Client = createClient(),
+) {
+  const { data: current } = await client.stream.documents.get({ id, view: 'full' });
+  if (!('document' in current)) throw new Error('需要完整 Stream 文档');
+  if (!current.document.entries?.some(entry => entry.id === entryId)) throw new Error('入口不在草稿中');
+  const response = await client.stream.sampleTest({ document: current.document, entryId, input });
+  return { status: response.data.status, errorCode: response.data.errorCode,
+    writes: response.data.writePreview, logs: response.data.logs, mode: response.data.mode };
+}
+```
+
+HTTP 成功也要检查 completed/failed 和 errorCode。模式为 isolated-sample，writePreview 不是线上写入；样例成功不能证明线上依赖健康。日志可能有业务数据，不直接公开。
+
+所有 Source/Stream 接口返回完整 code/msg/requestId/data。预检、草稿保存、发布回执和真实运行应分别记录；不要以 SDK 本地测试通过宣称完成真实环境联调。

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

@@ -0,0 +1,35 @@
+# 查询 Stream
+
+| 方法 | 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 |
+| 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 不是脚本内容，不能据此重建草稿。
+
+```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 };
+}
+export async function* listStreams(client: Tier0Client = createClient()) {
+  let page = 1;
+  while (true) {
+    const { data } = await client.stream.programs.list({ page, size: 100, archived: false });
+    yield data.list;
+    if (!data.hasMore) return;
+    if (typeof data.nextPage !== 'number' || data.nextPage <= page) throw new Error('无有效下一页');
+    page = data.nextPage;
+  }
+}
+```
+
+保存、发布、某次执行成功是三个事实。显示实际 revision/activeVersion/release，不用旧 runs 证明新版本生效。版本列表不保证与普通列表相同分页结构；按其 list/total/page/size 读取，versionId 不是 release 序号。

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

@@ -0,0 +1,36 @@
+# 修改 Stream 草稿
+
+方法：`stream.documents.update`；POST `/openapi/v2/uns/streams/documents/update`。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id | string | 是 | 十进制字符串 |
+| document | CloudStreamDocument | 是 | name、model、script、sources、entries 完整文档 |
+| expectedRevision | integer | 建议始终提供 | get 返回修订，防止覆盖他人修改 |
+| dryRun | boolean | 是 | true 预检；false 保存 |
+| idempotencyKey | string | 否 | 本次更新独立意图键 |
+
+## 示例：更新描述，保持脚本和绑定
+
+```ts
+import { createClient, type Tier0Client, type CloudStreamDocument } from '@tier0/sdk-v2';
+
+export async function updateStreamDescription(
+  id: string, description: 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 文档');
+  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 };
+}
+```
+
+需要改脚本时构造 `{ ...current.document, script: { ...current.document.script, code: newCode } }`，保留 sdkVersion/timeoutMs；变更入口或绑定时同步修改 entries/sources 并重新 validate。不要对脱敏 programs.get.document 做展开更新。
+
+响应是完整 CloudStreamDocumentView 或预检结果；保存草稿不会自动部署，activeDocument 可能仍是旧发布版本。VERSION_CONFLICT 后重新读取、比较并决策；不无条件覆盖。下一步发布见[部署](deploy.md)。

package/skills/tier0-sdk-v2/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/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/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/tier0-sdk-v2-uns/SKILL.md

@@ -0,0 +1,55 @@
+---
+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) | metadataInsertOne/Many、recordInsertOne |
+| 查询集合、筛选/排序记录 | [查询](references/read.md) | dataAppContext、metadataFind/FindOne（非 App 凭证）、collectionDescribe、recordFind |
+| 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many、metadataFindOneAndUpdate |
+| 删记录、软删除集合 | [删除](references/delete.md) | recordDeleteOne、metadataDeleteOne/Many |
+| 恢复集合或记录 | [恢复](references/restore.md) | metadataRestore、recordRestore |
+| 分页、历史采样、事务、写入结果 | [数据工作流](references/data-workflows.md) | sampleFind、recordTransactionExecute |
+| 目录、Topic 元数据及组合事务 | [命名空间](references/namespace.md) | metadata*、metadataBulkWrite、metadataTransact |
+
+## 找到正确数据上下文
+
+托管 App 使用 dataAppContext，按业务 alias 精确选择授权集合；它同时给出每个集合的 revision、索引就绪状态（indexStatus）、TTL 和平台限额（limits）。App 凭证不能调用 metadataFind/FindOne、async 模式与 jobs 查询；Workspace 集成（会话、personal / agent Key）用 dataDiscover/metadataFind，不强制 App 上下文。通用元数据管理写入不向 App 凭证开放。App 自有业务数据优先用 [App 数据层](../tier0-sdk-v2-data/SKILL.md)（`@tier0/sdk-v2/data`），变更订阅只在那里提供（`data.subscribe`）。
+
+```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，不猜第一个集合是业务目标。
+
+平台签发的 App Key 声明本 App 自有集合使用 appCollectionsEnsure，修改结构、停用及恢复分别使用 appCollectionsSchemaReplace/Archive/Restore；这些保留专用 App 归属和授权语义，不能改成 metadataInsertOne 或普通元数据写入。会话或个人 Key 查询自有集合使用 appCollectionsList。Builder 创建普通授权集合可在 metadataInsertOne 中提供 appId/alias，具体凭证与权限由服务端复验。
+
+## 核心约束
+
+1. 记录行是 id/data/revision；filter 与 update 的业务路径用 name、customer.name，不加 data.；系统路径用 _id、_meta.revision。
+2. 改/删前读取 expectedRevision；不同操作使用独立意图键，长度上限以当前操作契约为准。
+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]]。单页不是全量，跨页不是稳定快照。
+6. Sample 的时间是 Unix 毫秒，查询范围 [from,to)。Record 代表业务实体，不用覆盖它来保存历史。
+
+## 结果与异常
+
+响应为 code/msg/requestId/data。元数据 find 返回 items/pageInfo；findOne 与 findOneAnd* 返回 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

@@ -0,0 +1,56 @@
+# 创建集合与记录
+
+元数据使用 metadataInsertOne（POST /openapi/v2/uns/metadata）或 metadataInsertMany；kind 指定 directory/topic/collection。单条提供 data、可选 id；批量提供同一 kind 的 documents[{id?,data}]。idempotencyKey 标识一个写入意图；dryRun=true 仅校验。schemaVersion 由服务端赋默认值。
+
+集合 data 必须包含 name、recordSchema，可选 description、parentId、sampleSchema、indexes、semantics。parentId=null 表示根目录。索引创建后仍需确认状态为 ready。
+
+```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 request: UnsV2Request<'metadataInsertOne'> = {
+    kind: 'collection', id: collectionId,
+    data: {
+      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.metadataInsertOne({ ...request, dryRun: true });
+  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 };
+}
+```
+
+单条新增返回 insertedId/status/replayed；批量新增返回 insertedCount/insertedIds 及适用的逐项错误。insertedIds 的键是原始输入从 0 开始的索引。省略自定义 ID 时从成功回执取得实际 ID，不能把名称当成 ID。
+
+```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] };
+}
+```
+
+记录创建与集合创建使用不同意图键。未知结果先按 ID 核对内容，不仅检查存在；SDK 不自动重试。