@tier0/sdk-v2 0.0.0-stage → 0.2.1

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

@@ -0,0 +1,78 @@
+---
+name: tier0-sdk-v2-mq
+description: 使用 @tier0/sdk-v2/mq 连接 Tier0 MQTT WebSocket Broker，管理凭证、订阅和发布消息、清理连接及处理背压；不替代 Source 配置或 Stream 执行。
+---
+
+# MQTT 实时消息
+
+连接配置、完整订阅生命周期、通配符、发布及鉴权排查见 [Quickstart](references/quickstart.md)。v1 的旧 UNS 路径/字段规则不适用于新架构；实际 MQTT 映射需按目标环境确认。
+
+`Tier0MQClient` 从独立子入口导入。它面向消息客户端；配置平台采集连接用 Source，运行处理逻辑用 Stream。HTTP SDK 的“不自动重试”不等于 MQTT 禁用重连或 QoS 重投递。
+
+## 使用已有凭证订阅
+
+```ts
+import { Tier0MQClient, toWebSocketUrl, type TopicHandler } from '@tier0/sdk-v2/mq';
+
+export async function watchTopic(
+  broker: string,
+  credentials: { clientID: string; username: string; password: string },
+  topic: string,
+  handle: TopicHandler,
+) {
+  const mq = new Tier0MQClient({
+    host: toWebSocketUrl(broker),
+    clientId: credentials.clientID,
+    username: credentials.username,
+    password: credentials.password,
+    reconnectPeriod: 1000,
+  });
+  mq.on('error', error => console.error(error.name));
+  await mq.connect();
+  mq.subscribe(topic, handle);
+  return () => {
+    mq.unsubscribe(topic, handle);
+    mq.disconnect();
+  };
+}
+```
+
+broker 可来自 `client.system.info().mqttBroker`，先检查字段存在。保留已有 ws/wss URL 的端口和路径；HTTP 页面与 TLS/混合内容策略按实际部署配置，不能简单把 TCP 端口当 WebSocket 端口。
+
+subscribe 返回 void，错误通过 error 事件报告；回调参数是 topic 和字符串 payload。按业务格式解析 JSON，非法消息应隔离处理，避免一条坏消息打断消费。多个组件共享连接时，只清理自己的 handler，不直接 disconnect 其他订阅。
+
+## 凭证生命周期
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function provisionMqttCredential(name: string) {
+  return createClient().mqttAuth.create({ name });
+}
+export async function revokeMqttCredential(id: number | bigint) {
+  return createClient().mqttAuth.delete({ id });
+}
+```
+
+仅在任务需要创建凭证时使用 create，普通订阅重用已有受控凭证。完整 username/password/clientID 只在创建时返回一次，按秘密管理，别写日志。SDK 配置的 clientId 小写 d，接口回执的 clientID 大写 ID。
+
+也可从编码了 Workspace 的平台 Key 推导 MQTT 身份；无法解析的 Key 会拒绝连接，不回退到 Enterprise 身份。浏览器场景须使用针对当前用户/主题授权的凭证方案，不能为了省事下发长期 App Key。
+
+## 发布与确认边界
+
+```ts
+import { Tier0MQClient } from '@tier0/sdk-v2/mq';
+
+export async function publishMeasurement(mq: Tier0MQClient, topic: string, value: number) {
+  if (!Number.isFinite(value)) throw new Error('非法测量值');
+  await mq.publish(topic, { value, time: Date.now() }, { qos: 1, retain: false });
+}
+```
+
+publish 目前在建立连接并调用 MQTT 库发布后返回，不等待业务执行确认，也不保证已收到 broker PUBACK。需要闭环时使用业务 ACK 主题/关联 ID 或 Control 契约，不能把 Promise resolve 当成设备执行完成。
+
+订阅内部 QoS 为 1；发布默认 QoS 0、retain=false。业务消费者需考虑重复消息。对象 payload 经 JSON.stringify，不能直接包含 bigint；按协议约定编码精确值，不假设 MQTT 自动使用 UNS 的无损 codec。
+
+## 清理与背压
+
+组件卸载/任务结束时用原 handler 退订，连接归当前任务独占时再 disconnect。可配置 maxBackpressuredDeliveries；handler 连续同步返回严格 false 达到阈值后会移除订阅并触发 subscriptionDropped。异步 Promise 的 false 不等同同步背压信号。通过 isConnected/subscribedTopics 观察本地连接状态，不把它当作服务器完整订阅清单。

package/skills/tier0-sdk-v2/tier0-sdk-v2-mq/references/quickstart.md

@@ -0,0 +1,69 @@
+# MQTT 连接、订阅与清理
+
+入口：@tier0/sdk-v2/mq。使用 Tier0 平台 Broker 和已授权的真实主题；配置外部采集源转 Source，处理脚本转 Stream。
+
+| 配置 | 类型 | 说明 |
+| --- | --- | --- |
+| host | string | 完整 ws/wss URL，或通过 toWebSocketUrl 解析 |
+| clientId / username / password | string | 显式凭据；不要暴露到日志 |
+| reconnectPeriod | number | MQTT 重连间隔，与 HTTP 无重试不同 |
+| connectTimeout / keepAlive | number | 连接超时/保活配置 |
+| maxBackpressuredDeliveries | number | handler 连续同步返回 false 的退订阈值 |
+
+Broker 可从 system.info().mqttBroker 获取。用 parseMqttBroker/toWebSocketUrl，不手工解析 scheme 或把 TCP 1883 当 WebSocket 端口；显式环境地址优先。平台 Key 可派生身份，但浏览器不得接收长期 App Key。
+
+```ts
+import { Tier0MQClient, toWebSocketUrl, type TopicHandler } from '@tier0/sdk-v2/mq';
+
+export async function subscribeTelemetry(
+  broker: string, credentials: { clientID: string; username: string; password: string },
+  filter: string, onValue: (topic: string, value: unknown) => void,
+  onError: (error: Error) => void,
+) {
+  const mq = new Tier0MQClient({
+    host: toWebSocketUrl(broker), clientId: credentials.clientID,
+    username: credentials.username, password: credentials.password,
+    reconnectPeriod: 1000, maxBackpressuredDeliveries: 10,
+  });
+  const handler: TopicHandler = (topic, payload) => {
+    let value: unknown;
+    try { value = JSON.parse(payload); }
+    catch { onError(new Error('消息不是有效 JSON')); return; }
+    onValue(topic, value);
+  };
+  mq.on('error', onError);
+  try {
+    await mq.connect();
+    mq.subscribe(filter, handler);
+  } catch (error) {
+    mq.disconnect();
+    throw error;
+  }
+  return () => { mq.unsubscribe(filter, handler); mq.disconnect(); };
+}
+```
+
+回调是 (topic,payload)，payload 为字符串。subscribe 返回 void，订阅失败通过 error 事件，不把函数返回当 broker SUBACK。此例独占连接；共享连接只退订自己的 handler，不关闭其他消费者。
+
++ 匹配一层，# 匹配多层，订阅范围必须属于任务和主题授权。不能从旧 v1 的 Metric/Action/State 路径、enableHistory 或字段规则推断新 UNS MQTT 映射；先核实目标平台的实际主题和消息契约。App 服务端订阅新 UNS Record 变更用 `@tier0/sdk-v2/data` 的 `data.subscribe`（`records:subscribe` 服务端推送），不是 MQTT 主题。
+
+## 发布
+
+```ts
+import { Tier0MQClient } from '@tier0/sdk-v2/mq';
+
+export async function publishEvent(mq: Tier0MQClient, topic: string, eventId: string, value: number) {
+  if (!Number.isFinite(value)) throw new Error('测量值非法');
+  await mq.publish(topic, { eventId, value }, { qos: 1, retain: false });
+}
+```
+
+payload 必须符合实际主题契约；对象用 JSON.stringify，不可包含 bigint。publish resolve 不证明已收 PUBACK，更不证明设备执行；业务闭环用关联 ID/ACK 或 Control。订阅 QoS 1，发布默认 QoS 0/retain=false，消费端考虑重复消息。
+
+## 事件、背压和鉴权
+
+connect/disconnect/error/message/subscriptionDropped 反映客户端状态。isConnected/subscribedTopics 不是服务器全量状态。连续同步返回严格 false 才触发背压计数，Promise<false> 不等价；消费者不应无限缓存。
+
+创建凭据用 client.mqttAuth.create({name})，撤销用 delete({id})，检查 success。回执的 clientID 对应配置 clientId；完整密码只在创建时返回一次，受控保存。
+
+Not authorized/CONNACK 5/重连循环时核对注入的 Key 类型、过期/撤销、授权和 Broker ws/wss 地址。v2 不回退 Enterprise 身份，也不套用旧包升级到 @tier0/sdk@latest 的建议；不因连接失败自动新建凭据。

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

@@ -0,0 +1,42 @@
+---
+name: tier0-sdk-v2-notifications
+description: 使用 @tier0/sdk-v2 发送和查询 Tier0 站内通知、Web/Desktop 提醒及 Mobile 推送，解析收件人，处理发送者、渠道、业务幂等与投递状态。
+---
+
+# 通知
+
+服务端使用 `createClient()` 读取 TIER0_API_HOST / TIER0_API_KEY，或显式传 apiHost/apiKey。发送必须符合用户已授权的收件人和内容范围，查询状态不自动补发。
+
+| 任务 | 参考 | 方法 |
+| --- | --- | --- |
+| 收件人选择、完整发送、渠道、模式、错误 | [发送](references/send.md) | notifications.send |
+| 查询回执、有界等待投递完成 | [查询](references/get.md) | notifications.get |
+| 按姓名或邮箱查收件人 | [成员](../tier0-sdk-v2-members/SKILL.md) | members.listWorkspace |
+
+## 核心约束
+
+- type 固定 inbox；Swagger 的 string 不代表接受任意类型。
+- 用人读姓名/邮箱选择收件人，ID 由成员数据解析并保持字符串，不让用户填写 ID。Workspace 成员不等于 App 可访问用户。
+- title 最多50字符，content 最多800字符。mode 按真实发布环境选择 test/live；test 会创建测试消息，不能当预检。
+- App sender 使用 getCurrentAppId() 的真实 APP_ID，v2 不注入 project 上下文，不复制旧 getCurrentProjectId。导航和名称展示按目标前端支持核实。
+- sender/link/meta 是展示提示，不作为授权。新代码不使用废弃 source 字段。
+- 同一业务事件、收件人、内容使用稳定 idempotencyKey；新事件使用新键，不因超时随机换键。
+
+## 渠道
+
+| channels | 提醒范围 |
+| --- | --- |
+| 省略 | SDK 默认 web + mobile |
+| ['web'] | Web/Desktop |
+| ['mobile'] | 手机 |
+| [] | 只建站内信 |
+
+Desktop 属于 web，不存在 desktop 渠道。显式单渠道不补齐，重复项会去重。SDK 默认和裸后端省略参数的行为不同，不混用。
+
+## 返回与失败
+
+send 返回直接对象 {messageId,status,createdAt}，get 返回直接状态对象，没有 data 外层。accepted 表示受理，sent 表示已发送，不是用户已读；failed 检查 errorCode/message。
+
+v2 ApiError 提供 status/errorCode/msg；不要沿用 v1 JSON.parse(error.msg) 的旧解析方式。未知结果先对账；已有 messageId 按 ID 查，没有按 idempotencyKey 查询的 SDK 入口。HTTP SDK 不自动重试。
+
+完整示例与参数边界均在操作参考中。Skill 示例不会自动发送消息，也不授予真实发送权限。

package/skills/tier0-sdk-v2/tier0-sdk-v2-notifications/references/get.md

@@ -0,0 +1,34 @@
+# 查询通知投递状态
+
+方法：`notifications.get({messageId})`；POST /openapi/v1/notifications/get。需要 notifications:read，与 send 权限独立；仅查询当前发送 Key 可见的消息。
+
+| 参数/结果 | 类型 | 说明 |
+| --- | --- | --- |
+| messageId | string | 发送回执 ID，不转 Number |
+| status | string | accepted / sent / failed |
+| createdAt / completedAt | string | ISO 时间，completedAt 可省略 |
+| errorCode / message | string | 失败原因，可省略 |
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function waitForNotification(
+  messageId: string, client: Tier0Client = createClient(), maxAttempts = 10,
+) {
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1 || maxAttempts > 20) {
+    throw new Error('查询次数应为 1–20');
+  }
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const result = await client.notifications.get({ messageId });
+    if (result.status === 'sent' || result.status === 'failed') return result;
+    if (result.status !== 'accepted') throw new Error('未识别的通知状态');
+    if (attempt === maxAttempts - 1) return result;
+    await new Promise(resolve => setTimeout(resolve, 1500));
+  }
+  throw new Error('未取得通知状态');
+}
+```
+
+accepted 表示仍处理，达到次数上限就返回处理中；sent 表示站内信已创建、推送交给渠道，不代表用户收到或阅读。failed 显示 errorCode/message，不继续当成功。
+
+返回直接对象，不读取 result.data。404 MESSAGE_NOT_FOUND 也可能是发送 Key 不同，不能直接断言消息丢失；先核对原 messageId 与发送身份。查询任务不自动补发。

package/skills/tier0-sdk-v2/tier0-sdk-v2-notifications/references/send.md

@@ -0,0 +1,72 @@
+# 发送通知
+
+方法：`notifications.send(body)`；POST /openapi/v1/notifications/send。需要 notifications:send；收件人为当前 Workspace 内可用的成员，按[成员查询](../../tier0-sdk-v2-members/references/platform-members.md)解析。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| recipientUserId | string | 是 | 已解析的用户 ID，保持字符串 |
+| type | inbox | 是 | 后端只接受 inbox；不是 business |
+| title | string | 是 | 1–50 字符 |
+| content | string | 是 | 1–800 字符 |
+| idempotencyKey | string | 是 | 最多 128 字符；同一次业务事件固定 |
+| mode | test/live | 否 | 根据实际发布环境显式选择；省略服务端默认 live |
+| channels | array | 否 | SDK 省略补 web+mobile；[] 仅站内信 |
+| sender | object | 否 | app/other；system 仅平台内部服务 Key |
+| link | string | 否 | https:// 或单斜杠开头，最多 500 字符 |
+
+## 完整 App 示例
+
+下面函数供应用在已授权的业务事件中调用；写示例不意味着发送真实消息。intentKey 应包含收件人、业务对象和事件版本，不因网络重试换键。
+
+```ts
+import { createClient, getCurrentAppId, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function sendCompletedOrder(
+  recipientUserId: string, orderId: string, intentKey: string, mode: 'test' | 'live',
+  client: Tier0Client = createClient(),
+) {
+  return client.notifications.send({
+    recipientUserId, type: 'inbox', title: '工单已完成',
+    content: '工单 ' + orderId + ' 已完成，请查看处理结果。',
+    idempotencyKey: intentKey, mode, channels: ['web', 'mobile'],
+    sender: { type: 'app', id: getCurrentAppId() },
+  });
+}
+```
+
+sender.id 来自真实 APP_ID UUID。v2 不注入 project 上下文，也没有 getCurrentProjectId；不要把 Folder/Workspace ID 填进 meta.projectId。旧 UI 的 App 名称解析/打开 App 按钮依赖 appId+projectId，不能将旧导航规则原样承诺到新架构。需带链接时传已验证可访问的业务 https 地址，或确认目标前端支持的相对路由；缺少旧上下文时不猜拼地址。
+
+other 发送者应给人读名称，如 `{type:'other',name:'库存同步服务'}`。app 不重复硬编码名称。sender/meta/link 都是展示导航提示，不是授权证明。meta 值为字符串，序列化最多 500 字节；sender.name 最多100字符。source 是废弃别名，不用于新代码。
+
+## 渠道、模式与幂等
+
+| channels | 提醒范围 |
+| --- | --- |
+| 省略 | SDK 显式发送 web+mobile |
+| ['web'] | Web/Desktop |
+| ['mobile'] | 手机 |
+| [] | 只建站内信 |
+| 重复项 | SDK 去重 |
+
+没有 desktop 渠道。不要将 SDK 默认值与裸后端省略渠道的静默语义混淆。test 也会创建测试消息，不是 dryRun；仅因 NODE_ENV=production 不能证明 App 已发布。
+
+同键同内容用于重放原意图；同键改内容产生冲突。新事件/不同收件人使用不同键。SDK 不自动重试，结果未知先对账；已有 messageId 用 get，没有按意图键查询的 SDK 方法。
+
+## 回执与错误
+
+成功为直接 {messageId,status,createdAt}，没有 data。accepted 是异步受理，sent 不是已读，详见[查询](get.md)。
+
+v2 的 ApiError 已提供 status/errorCode/msg，不再 JSON.parse(error.msg) 提取旧版原始错误。
+
+| HTTP / errorCode | 处理 |
+| --- | --- |
+| 400 INVALID_NOTIFICATION_TYPE | type 必须 inbox |
+| 400 INVALID_REQUEST | 检查字段、枚举和长度 |
+| 401 INVALID_CREDENTIAL | 核对注入身份 |
+| 403 NOTIFICATION_NOT_ALLOWED | 核对 send 权限 |
+| 404 RECIPIENT_NOT_AVAILABLE | 刷新成员并重新选择 |
+| 409 IDEMPOTENCY_KEY_CONFLICT | 区分原事件与新事件，不静默换键重发 |
+| 422 CONTENT_LIMIT_EXCEEDED | 缩短内容 |
+| 429 NOTIFICATION_RATE_LIMITED | 有界退避；保留原键，不自动广播重发 |
+
+link 拒绝 //host、反斜杠、Unicode 空白/控制/不可见格式字符。省略 link 不保证无按钮，实际导航还取决于发送者与目标前端。

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

@@ -0,0 +1,38 @@
+---
+name: tier0-sdk-v2-source
+description: 使用 @tier0/sdk-v2 的 client.source 查询、创建、修改、启停和删除新架构 Source，配置协议连接、处理影响分析、版本冲突与运行观测。
+---
+
+# Source 数据接入
+
+Source 维护连接配置、认证引用与源状态。脚本处理用 [Stream](../tier0-sdk-v2-stream/SKILL.md)，数据存储用 [UNS](../tier0-sdk-v2-uns/SKILL.md)。服务端使用 `createClient({apiHost,apiKey})`，或注入 TIER0_API_HOST / TIER0_API_KEY 后 `createClient()`；密钥不进入浏览器。
+
+## 按任务加载参考
+
+| 用户任务 | 参考 | SDK 方法 |
+| --- | --- | --- |
+| 选协议、准备连接配置 | [协议配置](references/protocols.md) | protocols.list |
+| 创建 HTTP/带凭据源 | [创建](references/create.md) | documents.create |
+| 列表、详情、运行状态 | [查询](references/read.md) | documents.list/get、observations.get、runtime.get |
+| 修改名称、端点或配置 | [修改](references/update.md) | documents.update |
+| 查看修改/启停/删除影响 | [影响分析](references/changes.md) | impact |
+| 启用、停用 | [状态变更](references/state.md) | state.update |
+| 删除并核验 | [删除](references/delete.md) | delete |
+
+先加载对应操作文档，使用其中的参数表、完整请求及返回判断。只执行用户任务所需步骤；示例函数调用才会执行写入，导入不执行。新建→查询→修改→删除可组成生命周期，但查询任务不触发其他操作。
+
+## 核心约束
+
+1. 原生文档 `{name,protocol,config}` 使用 documents.*；通用投影使用 source.list/get/create/update。http 原生协议与 http-api adapter 不可互换。
+2. 编辑前读取完整 documents.get；安全列表摘要不能无损回写。原生 ID 是十进制字符串，revision 原样传递，不转 Number。
+3. 现有 Source 修改、启停、删除都要 expectedRevision + confirmedImpactRevision。先形成精确意图，再读取全部影响分页；回执不可合成、跨意图复用或静默刷新。
+4. 配置中保留认证/TLS 引用，不写明文秘密；HTTP 新凭据走创建专用 credentials。
+5. desiredState 不代表实际健康，保存配置不代表 Stream 已切换至新 configRevision。运行状态另行读取。
+
+## 返回值与异常
+
+所有调用返回完整 code/msg/requestId/data。documents.create/update 的预检返回 validated/sideEffects，提交返回完整 Source view；批量状态/删除返回 Outcome。只有 committed 且无项错误才可报告提交成功；accepted/jobId 继续查询作业。
+
+需要查看历史用 source.history({id,beforeRevision,size})，按 nextBeforeRevision 继续；探测用 source.probe，其外部系统访问应属于当前任务。source.connection.update 属于现有源变更，同样遵守影响确认契约，不能作为绕过文档校验的入口。
+
+UnsV2Error 表示已知拒绝；UnsV2OutcomeUnknownError 表示可能已写入。保存 requestId、原请求和意图键，先查详情/历史/作业对账。取消等待不撤销服务端操作；SDK 不自动重试。权限不足不能解释为资源不存在。

package/skills/tier0-sdk-v2/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/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/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/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/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/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 检查。