@tier0/sdk-v2 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tier0/sdk-v2",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Tier0 Cloud new-architecture SDK for TypeScript and JavaScript",
   "license": "MIT",
   "type": "module",

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

@@ -45,7 +45,7 @@ export async function inspectConnection() {
 
 **Tier0 预览和部署里，App 的 Key 在运行进程的环境里**：平台注入 `TIER0_API_KEY`（这个 App 的 Key，秘密；预览是 preview Key，部署是 deployed Key）和 `TIER0_API_HOST`，`createClient()` 直接用它们，只发一个 `X-API-Key`。App 代码不要自己读、复制、打印或下发这个 Key，也不要生成或硬编码 Key；直接调平台时也通过 SDK。身份读平台设置的 `TIER0_WORKSPACE_ID`、`TIER0_APP_ID`。
 
-App 的 Key 只能调 `/openapi/v2/uns/**`、`assets/files/**`（`client.files`；`assets/upload` 不在内）、`notifications/send`、`platform/getMembers`（`members.listWorkspace()`）、`apps/access-members/list`（`members.listApp()`）、`stream-requests/discover` 和 `stream-requests/<code>/describe|invoke`、`stream-messages/connect`（`client.streams`）、`capabilities/discover`、`info`；其他接口（`system.whoami()`、`notifications.get`、`mqttAuth`、`agent`）回 403 `hosted_app_key_route_forbidden`；Source / Stream 管理接口 App 的 Key 无权调用，Backend 回 403。App 的平台能力固定 11 项（`openapi.base`、`platform.users.read`、`notifications.send`、文件上传 / 下载 / 删除、`stream.requests.read` / `invoke` / `write`、`stream.messages.publish` / `subscribe`），每个 App 都有、不在 App 设置里配置，生效的是它们和 Key 权限、Key 模式、工作区套餐的交集。外部集合只由工作区 Owner/Admin 在 App 设置里授权，删掉后下一个请求起生效。MQTT 主题只能用 App 自己的命名空间 `apps/<TIER0_APP_ID>/<TIER0_RUNTIME>/…`，用 `appTopic()` 拼，见 [MQTT](tier0-sdk-v2-mq/SKILL.md)。没有 `TIER0_API_KEY` 而 `TIER0_RUNTIME` 为 `deployed` / `preview` 时 SDK 进入平台代理模式（不发凭据、带 `X-Tier0-SDK: 1`），当前平台不会出现这种运行时，见 [错误码](tier0-sdk-v2-data/references/errors.md#平台代理模式的错误)。
+App 的 Key 只能调 `/openapi/v2/uns/**`、`assets/files/**`（`client.files`；`assets/upload` 不在内）、`notifications/send`、`platform/getMembers`（`members.listWorkspace()`）、`apps/access-members/list`（`members.listApp()`）、`stream-requests/discover` 和 `stream-requests/<code>/describe|invoke`、`stream-messages/connect`（`client.streams`）、`capabilities/discover`、`info`；其他接口（`system.whoami()`、`notifications.get`、`mqttAuth`、`agent`）回 403 `hosted_app_key_route_forbidden`；Source / Stream 管理接口 App 的 Key 无权调用，Backend 回 403。App 的平台能力固定 11 项（`openapi.base`、`platform.users.read`、`notifications.send`、文件上传 / 下载 / 删除、`stream.requests.read` / `invoke` / `write`、`stream.messages.publish` / `subscribe`），每个 App 都有、不在 App 设置里配置，生效的是它们和 Key 权限、Key 模式、工作区套餐的交集。已有集合可由内置 Builder 以自身系统身份主动关联同一工作区的目标 App，不查询对话用户的角色或要求其确认；当前绑定 App 只表示构建上下文。服务端复验系统 Key 自身权限、工作区及目标 App 状态。App 运行时只能访问已授予的集合及操作，不能管理授权；授权删掉后下一个请求起生效。MQTT 主题只能用 App 自己的命名空间 `apps/<TIER0_APP_ID>/<TIER0_RUNTIME>/…`，用 `appTopic()` 拼，见 [MQTT](tier0-sdk-v2-mq/SKILL.md)。没有 `TIER0_API_KEY` 而 `TIER0_RUNTIME` 为 `deployed` / `preview` 时 SDK 进入平台代理模式（不发凭据、带 `X-Tier0-SDK: 1`），当前平台不会出现这种运行时，见 [错误码](tier0-sdk-v2-data/references/errors.md#平台代理模式的错误)。
 
 不同身份使用独立实例。App 调平台只有一种身份：App 自身。当前用户和角色从前门注入的 `X-Tier0-Visitor` 读（`parseVisitorHeader`），按角色决定谁能看、能改什么由 App 在服务端自己做，见 [身份与框架集成](references/integration.md)。
 

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

@@ -33,7 +33,7 @@ Data 客户端创建时固定 Host 和 Key（含环境值），不支持 `getApi
 
 ## 最小用法
 
-新 App 没有集合时是正常空态：`uns.dataAppContext({})` 返回 `dataState: "uninitialized"` 和空集合，不创建任何数据。无需先调用 context 或手工激活数据策略；声明真实业务集合后，第一次数据访问会自动初始化。`dataState: "ready"` 也不代表可访问整个工作空间，仍以返回的集合授权为准。引用已有 WMS 等外部集合要由工作区 Owner/Admin 在 App 设置里授权（Builder agent 加不了），不能创建同名空集合代替；授权删掉后下一个请求起被拒绝。管理员停用返回 `FORBIDDEN`、reason `APP_DATA_POLICY_DISABLED`，不得自动恢复。
+新 App 没有集合时是正常空态：`uns.dataAppContext({})` 返回 `dataState: "uninitialized"` 和空集合，不创建任何数据。无需先调用 context 或手工激活数据策略；声明真实业务集合后，第一次数据访问会自动初始化。`dataState: "ready"` 也不代表可访问整个工作空间，仍以返回的集合授权为准。引用已有 WMS 等集合时，由 Builder 以自身系统身份按 [已有集合授权流程](../tier0-sdk-v2-uns/references/update.md#已有集合授权给-app) 关联当前 App；不依赖对话用户的角色或确认。App 运行时凭证不能自行扩大授权，也不能创建同名空集合代替；授权删掉后下一个请求起被拒绝。管理员停用返回 `FORBIDDEN`、reason `APP_DATA_POLICY_DISABLED`，不得自动恢复。
 
 ```ts
 import { z } from 'zod';

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

@@ -9,6 +9,8 @@ Read the [root Skill](../SKILL.md) first.
 
 **In a Tier0 App's server code** the App's key (`TIER0_API_KEY`) can use both. Stream requests and messages are fixed capabilities of every App (`stream.requests.read` / `invoke` / `write`, `stream.messages.publish` / `subscribe`), not configured per App and not approved by an admin. They are still bounded by the workspace plan (a plan without Stream refuses them) and, for requests, by the Stream request grants: the request code must be granted to this App. Message topics come from published Stream manifests: the App may subscribe to a topic a published Stream declares with `api.stream.messages.use({ topic, access: 'publish' })`, and publish to a topic an active Stream subscribes to. There is no per-App topic list. These APIs require an artifact built from the unified SDK implementation: pin its commit and SHA-256 until the corresponding version is published.
 
+Builder configures request grants using the management operations exposed by the current MCP contract: `/openapi/v2/uns/stream-requests/grants/get` and `/openapi/v2/uns/stream-requests/grants/set`, and `/openapi/v2/uns/app-stream-access/list`. Use the injected system key's current `stream.requests.manage` permission; its bound App is build context, so it may manage target Apps in the same workspace. Granted actions cannot exceed the manager's current permissions. Read the grant snapshot before updating or revoking, and reconcile state after conflicts or unknown outcomes. App runtime keys cannot manage grants. These management operations are separate from `client.streams` execution; do not invent a `client.uns` grant method.
+
 ## Select the interaction
 
 - A public request code with an input/output contract: `client.streams.requests.use({ code })`. Use `describe()` to inspect it; use `client.streams.requests.discover()` to find visible contracts.

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

@@ -5,7 +5,7 @@ description: 使用 @tier0/sdk-v2 的 client.uns 完成新架构集合、Schema
 
 # 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（平台里由平台注入 App 的 Key），或显式传 apiHost/apiKey。数据权限不自动授予管理权限：管理操作中 App 凭证只能调用本 App 集合的 appCollectionsEnsure / SchemaReplace / Archive / Restore；appDataPolicyGet/Update 的调用方必须是持有 uns.write 的登录会话、持有 uns.write 且 full_access、不绑定 App 的 personal / agent Key，或治理会话；新增授权（新集合、放宽权限、从 disabled 重新启用）只接受工作区 Owner/Admin 的人工会话或平台导入，其他调用方回 403（reason `app_grant_admin_required` / `app_grant_agent_forbidden`），收窄和移除不受此限；运行时 App 凭证不能管理数据授权。
+UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本分别用 [Source](../tier0-sdk-v2-source/SKILL.md)、[Stream](../tier0-sdk-v2-stream/SKILL.md)。服务端 `createClient()` 读 TIER0_API_HOST / TIER0_API_KEY（平台里由平台注入 App 的 Key），或显式传 apiHost/apiKey。管理操作中 App 运行时凭证只能调用本 App 集合的 appCollectionsEnsure / SchemaReplace / Archive / Restore，不能管理数据授权。appDataPolicyGet/Update 使用当前管理主体的有效权限：持有 uns.write 的登录会话，持有 uns.write 且 full_access、不属于 App 运行时的 personal / agent / service-system Key，或治理会话。内置 Builder 以自身系统身份主动为同一工作区的 App 关联已有集合，当前绑定 App 不限制授权目标，不查询对话用户的角色、不要求其确认；外部 Key 按自身权限执行。新增、扩大、收窄和移除授权走同一管理校验，受工作区、目标 App、当前资源权限和提交前凭据复验约束，没有 Agent 身份禁令或平台导入特例。
 
 先按[命名空间指导](references/namespace.md)区分凭证：`namespace()` 走 OpenAPI，但当前不对 App Key 开放；App 查询可用集合走 `dataAppContext`，不能改用同样受限的 `appCollectionsList`。Agent / Personal Key 也须满足当前工作空间权限；不要从“使用 SDK / MCP”推定权限。
 
@@ -17,6 +17,7 @@ UNS 管数据命名空间、集合、Record 和 Sample；外部连接与脚本
 | --- | --- | --- |
 | 创建集合、定义 Schema、新增记录 | [创建](references/create.md) | metadataInsertOne/Many、recordInsertOne |
 | 查询集合、筛选/排序记录 | [查询](references/read.md) | dataAppContext、metadataFind/FindOne（非 App 凭证）、collectionDescribe、recordFind |
+| 把已有集合授权给 App | [修改](references/update.md#已有集合授权给-app) | appDataPolicyGet、appDataPolicyUpdate |
 | 改记录、集合名称、扩展 Schema | [修改](references/update.md) | recordUpdateOne、metadataUpdateOne/Many |
 | 删记录、软删除集合 | [删除](references/delete.md) | recordDeleteOne、metadataDeleteOne/Many |
 | 精确删除选中的历史样本 | [删除](references/delete.md#精确删除历史样本) | sampleFind、sampleDeleteExact（非 App 凭证） |

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

@@ -60,3 +60,14 @@ export async function renameDevice(
   return { state: 'committed' as const, receipt, current: after.data.items[0] };
 }
 ```
+
+## 已有集合授权给 App
+
+这是 Builder 的管理操作，使用内置 MCP 注入的系统身份；不从 App 运行时取得管理 Key，也不需要对话用户具有 Owner/Admin 角色或再次确认。外部 personal / agent Key 按自身当前权限调用同一接口。Builder 可为同一工作区内的 App 管理授权，当前绑定 App 仅是构建上下文。服务端校验工作区、目标 App 状态和所授资源权限，App 运行时凭证不能管理授权。
+
+- 先发现并确认真实的 `collectionId`、结构和当前目标 `appId`；保留已有集合所属 App、目录和数据，不创建同名空集合代替。
+- 调用 `appDataPolicyGet({ appId })` 读取当前策略及 `revision`。使用 `appDataPolicyUpdate` 的 `changes` 增量提交，以 `action: 'upsert'`、实际 `collectionId` 和业务所需 `permissions` 关联集合；`alias` 可省略，不能同时传 `collections`。`upsert` 指定该集合的完整目标权限，其他集合授权保留。
+- 传入读到的 `expectedRevision`、现有 `status` 和本次操作的独立 `idempotencyKey`，执行时 `dryRun: false`。策略已 `disabled` 时，关联不应顺便重新启用；恢复策略是另一个明确管理动作。
+- 检查写入回执 `data.status === 'committed'`，再读取策略核对集合与权限已生效。随后使用 App 运行时的 `dataAppContext` 确认有效授权，并用真实 App 凭证读取已有记录；需要写入时按实际业务验证写入结果。管理身份能查到数据不代表 App 已获授权。
+
+`expectedRevision` 冲突时重读策略并重新计算改动；403 保留原错误，不换凭证或复制集合绕过。结果为 `unknown` 时先读回核对，未确认结果前不自动重试。对话确认不是后端权限凭据，也不需要新增确认字段。