@tier0/sdk-v2 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,40 @@
+# Source 影响分析
+
+方法：`source.impact`；POST `/openapi/v2/uns/sources/impact`。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| id / expectedRevision | string / integer | 是 | 当前 ID 和读取到的修订 |
+| action | update/enable/disable/delete | 是 | 精确变更类型 |
+| document | CloudSourceDocument | 更新时 | 完整拟提交文档 |
+| offset / size | integer | 否 | 首次 0；size 1–200 |
+| impactRevision | string | 翻页时 | 沿用首次返回的确认值 |
+
+```ts
+import { createClient, type Tier0Client, type UnsV2Request } from '@tier0/sdk-v2';
+
+export async function collectSourceImpact(
+  intent: Pick<UnsV2Request<'sourceImpact'>, 'id' | 'expectedRevision' | 'action' | 'document'>,
+  client: Tier0Client = createClient(),
+) {
+  const first = await client.source.impact({ ...intent, offset: 0, size: 200 });
+  const references = [...first.data.references];
+  let offset = first.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: first.data.impactRevision,
+    });
+    if (next.data.impactRevision !== first.data.impactRevision) throw new Error('影响确认值发生变化');
+    references.push(...next.data.references);
+    offset = next.data.nextOffset;
+  }
+  return { ...first.data, references, nextOffset: offset };
+}
+```
+
+data：impactRevision、sourceID/sourceRevision、action、counts（draft/activeRelease/historicalRelease）、restrictedCount、references、nextOffset、expiresAt。nextOffset=0 结束；complete=1 表示计算完成，不表示首页有全部引用。
+
+确认值绑定身份、修订、精确意图，不能合成或自动刷新。评估 counts 和 restrictedCount；有受限引用时不能说“无影响”。Source 更新不会自动替换 Stream 冻结修订。已有明确操作授权时不重复索要确认；影响分析本身不授予额外操作权限。

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

@@ -0,0 +1,63 @@
+# 创建 Source
+
+方法：`source.documents.create`；POST `/openapi/v2/uns/sources/documents/create`。需要 Source manage 权限。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| dryRun | boolean | 是 | true 校验；false 保存 |
+| document.name | string | 是 | 1–128 字符 |
+| document.protocol | string | 是 | 原生协议，如 http、mqtt、modbus |
+| document.config | object | 是 | configVersion=2、endpoint、options；见[协议配置](protocols.md) |
+| document.description | string | 否 | 最多 512 字符 |
+| credentials | object | 否 | 仅创建时提供新 HTTP 凭据，与已有 auth/TLS 引用互斥 |
+| idempotencyKey | string | 否 | 建议提供，最多 128 字符，同一业务意图保持不变 |
+
+## 完整示例：HTTP 数据源
+
+传入实际端点、名称和意图键。此函数创建配置，不启用源。client 从服务端环境读取 API Host/Key，也可显式注入。
+
+```ts
+import { createClient, type Tier0Client, type CloudSourceDocument } from '@tier0/sdk-v2';
+
+export async function createHttpSource(
+  endpoint: string, name: string, intentKey: string, client: Tier0Client = createClient(),
+) {
+  const document: CloudSourceDocument = {
+    name, protocol: 'http', description: '订单系统 HTTP 接入',
+    config: { configVersion: 2, endpoint, options: {} },
+  };
+  const preview = await client.source.documents.create({ dryRun: true, document });
+  if (!('validated' in preview.data) || !preview.data.validated) throw new Error('Source 预检未通过');
+  const saved = await client.source.documents.create({
+    dryRun: false, document, idempotencyKey: intentKey,
+  });
+  if (!('id' in saved.data)) throw new Error('未返回已保存的 Source');
+  const current = await client.source.documents.get({ id: saved.data.id });
+  return { receipt: saved, current: current.data };
+}
+```
+
+提交返回 data：id、revision、document、desiredState、runtimeState、health、createdAt、updatedAt；预检返回 `{ validated: true, sideEffects: false }`，没有 ID。ID 原样保留十进制字符串。
+
+## HTTP Bearer 凭据
+
+token 从服务端密钥提供者取得，不写入脚本、文档、日志或仓库。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function createAuthenticatedHttpSource(
+  endpoint: string, name: string, token: string, intentKey: string,
+  client: Tier0Client = createClient(),
+) {
+  const saved = await client.source.documents.create({
+    dryRun: false, idempotencyKey: intentKey,
+    document: { name, protocol: 'http', config: { configVersion: 2, endpoint, options: {} } },
+    credentials: { method: 'GET', kind: 'bearer', material: { token } },
+  });
+  if (!('id' in saved.data)) throw new Error('未返回 Source ID');
+  return client.source.documents.get({ id: saved.data.id });
+}
+```
+
+配置保存不代表连接健康；见[查询](read.md)。仅在任务包含启用时执行[启停](state.md)。结果未知时保留原请求、requestId、意图键，先核对列表/历史，不自动重复创建。

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

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

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

@@ -0,0 +1,36 @@
+# 协议与连接配置
+
+先调用 `source.protocols.list({})`。协议枚举存在不等于目标环境驱动或凭据解析器已就绪。原生 `protocol: 'http'` 与通用投影 `adapter: 'http-api'` 不可混用。
+
+| 配置字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| configVersion | 2 | 是 | 新架构配置快照 |
+| endpoint | string | 是 | 地址，不内嵌凭据 |
+| options | object | 是 | 协议专用选项 |
+| auth.kind | string | 有认证时 | basic/bearer/apiKey/usernamePassword/oauth2ClientCredentials |
+| auth.credentialRef | string | 有认证时 | 已存在且可用的凭据引用 |
+| tls.caRef / clientIdentityRef | string | 否 | 已存在的 CA/客户端身份引用 |
+
+以下只构造文档，不执行创建；实际地址、主题、设备 unitId 由任务上下文提供。提交前用 documents.create 的 dryRun 校验。
+
+```ts
+import { createClient, type CloudSourceDocument } from '@tier0/sdk-v2';
+
+export async function inspectProtocolExamples() {
+  const capabilities = await createClient().source.protocols.list({});
+  const examples: CloudSourceDocument[] = [
+    { name: 'orders-http', protocol: 'http',
+      config: { configVersion: 2, endpoint: 'https://orders.example.com', options: {} } },
+    { name: 'line-plc', protocol: 'modbus',
+      config: { configVersion: 2, endpoint: 'tcp://plc.example.com:502', options: { unitId: 1 } } },
+    { name: 'line-mqtt', protocol: 'mqtt',
+      config: { configVersion: 2, endpoint: 'mqtt://broker.example.com:1883',
+        options: { clientId: 'tier0-line-reader', subscriptions: { 'factory/line1/status': 1 } } } },
+  ];
+  return { capabilities: capabilities.data, examples };
+}
+```
+
+HTTP 公开 headers 只允许 Accept/Content-Type，不能塞 Authorization/Cookie。Modbus 寄存器范围和轮询频率在 Stream acquisition 中定义；MQTT QoS 为 0/1/2。认证创建见[创建](create.md)，修改时保留原 auth/tls 引用。
+
+SQL options 包含 tlsMode（verify-full/disable）和 queries（资源名→固定 SQL）；脚本不能替换任意 SQL。OPC UA、SAP、Teamcenter 等按能力和服务端校验配置，不从 HTTP 模板生造字段。不要为通过校验自动移除认证或关闭 TLS。

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

@@ -0,0 +1,34 @@
+# 查询 Source
+
+| 方法 | POST 路径 | 输入 | data |
+| --- | --- | --- | --- |
+| source.documents.list | /openapi/v2/uns/sources/documents/list | page、size、search、protocol、desiredState、health、archived、includeDocument | list、total、page、hasMore、nextPage |
+| source.documents.get | /openapi/v2/uns/sources/documents/get | id（必填） | id、revision、完整 document、状态 |
+| source.runtime.get | /openapi/v2/uns/sources/runtime/get | id（必填） | 运行状态 |
+| source.observations.get | /openapi/v2/uns/sources/observations/get | items：id、expectedRevision | 指定源和修订的观测 |
+
+page 从 1 开始，size 1–200。列表默认安全摘要；完整文档需要管理权限，编辑时显式 get。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function* listSources(client: Tier0Client = createClient()) {
+  let page = 1;
+  while (true) {
+    const { data } = await client.source.documents.list({ page, size: 100, includeDocument: false });
+    yield data.list;
+    if (!data.hasMore) return;
+    if (typeof data.nextPage !== 'number' || data.nextPage <= page) throw new Error('无有效下一页');
+    page = data.nextPage;
+  }
+}
+export async function readSource(id: string, client: Tier0Client = createClient()) {
+  const current = await client.source.documents.get({ id });
+  const observation = await client.source.observations.get({
+    items: [{ id, expectedRevision: current.data.revision }],
+  });
+  return { current: current.data, observation: observation.data };
+}
+```
+
+ID 不得转 Number；跨页不是稳定快照。权限错误、网络故障与不存在应分别处理，不能把任何 get 失败当成删除成功。probe 可能触达外部系统，不属于单纯读取。

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

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

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

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

package/skills/tier0-sdk-v2-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-stream/references/create.md

@@ -0,0 +1,55 @@
+# 创建 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 });
+  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-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-stream/references/deploy.md

@@ -0,0 +1,63 @@
+# 发布、停用与回滚 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 });
+  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-stream/references/lifecycle.md

@@ -0,0 +1,25 @@
+# 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 });
+  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-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-stream/references/update.md

@@ -0,0 +1,35 @@
+# 修改 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 });
+  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)。