@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/read-write.md

@@ -0,0 +1,168 @@
+# 读写
+
+`data.collection(declaration)` 返回按声明推断类型的句柄（也可用 alias 字符串，类型由调用方指定）。读到的记录是扁平文档 `{ _id, ...字段, _meta }`；过滤、排序、投影都用同样的路径（`status`、`customer.id`、`_id`、`_meta.updatedAt`），不加 `data.` 前缀。
+
+```ts
+import { z } from 'zod';
+import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';
+
+const workOrders = defineCollection({
+  alias: 'work_orders',
+  schema: z.object({
+    code: z.string(),
+    status: z.enum(['DRAFT', 'RELEASED', 'DONE']),
+    line: z.object({ id: z.string(), name: z.string() }),
+    targetQty: z.number().int().min(1),
+    notes: z.string().optional(),
+  }),
+  indexes: [{ path: 'code', unique: true }, { path: 'status' }],
+});
+const data = createDataClient({ collections: [workOrders] });
+const orders = data.collection(workOrders);
+
+export async function dashboard(page: number) {
+  const recent = await orders.find({ status: { $in: ['RELEASED', 'DONE'] } }, { sort: { '_meta.createdAt': -1 }, limit: 50 }).toArray();
+  // 一页 + 总数是一次请求；total.capped 为 true 时显示成 "10000+"。
+  const listPage = await orders.findPage({ status: 'RELEASED' }, { sort: { code: 1 }, page, pageSize: 20 });
+  // 每个状态的数量：一次 $group，不要按状态逐个 countDocuments。
+  const byStatus = await orders.countBy('status');
+  const totals = await orders
+    .aggregate<{ _id: string; total: number }>([{ $match: { status: 'DONE' } }, { $group: { _id: '$line.id', total: { $sum: '$targetQty' } } }])
+    .toArray();
+  return { recent, listPage, byStatus, totals };
+}
+
+/** 角标只需要知道“有没有超过 99 条”。 */
+export async function releasedBadge() {
+  const { count, capped } = await orders.countDocuments({ status: 'RELEASED' }, { maxCount: 99 });
+  return capped ? '99+' : String(count);
+}
+
+export async function addNote(id: string, notes: string, revision: number) {
+  return orders.updateOne({ _id: id }, { $set: { notes } }, { expectedRevision: revision });
+}
+```
+
+## 一个页面一次请求：`data.queryBatch`
+
+页面要同时显示列表、总数、各状态数量、某条记录时，用 `data.queryBatch` 把这些读取合成一次请求（最多 20 个），结果来自同一个快照，不要分别发多个请求：
+
+```ts
+import { z } from 'zod';
+import { createDataClient, defineCollection } from '@tier0/sdk-v2/data';
+
+const workOrders = defineCollection({
+  alias: 'work_orders',
+  schema: z.object({ code: z.string(), status: z.enum(['DRAFT', 'RELEASED', 'DONE']) }),
+  indexes: [{ path: 'code', unique: true }, { path: 'status' }],
+});
+const data = createDataClient({ collections: [workOrders] });
+const orders = data.collection(workOrders);
+
+export async function ordersScreen(page: number, selectedId: string) {
+  const { list, byStatus, selected } = await data.queryBatch({
+    list: orders.query.findPage({ status: { $ne: 'DONE' } }, { sort: { code: 1 }, page, pageSize: 20 }),
+    byStatus: orders.query.countBy('status'),
+    selected: orders.query.get([selectedId]),
+  });
+  return { list, byStatus, selected: selected.items[0] ?? null };
+}
+```
+
+- 读取用 `collection.query.*` 构造：`find`（首页，可带 `maxCount` 附带总数）、`findPage`、`count`、`countBy`、`distinct`、`aggregate`、`get`；每项只返回一页（最多 200 行），`get` 最多 100 个 ID。
+- 结果按名字返回，类型与对应方法一致。名字只能用字母、数字、`_` `.` `-`。
+- 某一项被拒（过滤条件不合法、无授权）时整个调用抛出该项的 `DataError`；传 `{ settle: true }` 则每项返回 `{ ok: true, value }` 或 `{ ok: false, error }`。语句超时或整批超过 2000 行 / 8 MiB 时整批失败。
+
+## 方法
+
+| 读取 | 说明 |
+| --- | --- |
+| `find(filter, { sort, limit, projection })` | 游标，每页最多 200 条；列表读取始终给 `limit` |
+| `findOne(filter)` | 无匹配返回 `null` |
+| `get(ids, { projection })` | 按 `_id` 读取，返回 `{ items, missing }`，`items` 按请求顺序（重复的 ID 只取第一次出现）；不存在、已删除或员工无权查看的 ID 一律进 `missing`。超过 100 个自动分批 |
+| `findPage(filter, { sort, page, pageSize, maxCount })` | 页码分页，一次请求返回 `{ items, total: { count, capped }, page, pageSize }`；pageSize 最多 200，总数默认数到 10000（`maxCount` 最多 100000），超过时 `capped: true` |
+| `countDocuments(filter, { maxCount })` | 返回 `{ count, capped }`，默认数到 100000；只要阈值时给小的 `maxCount`（如角标 `99+`） |
+| `countBy(field, filter)` | 每个取值的数量 `[{ value, count }]`，从多到少；一次 `$group` |
+| `distinct(field, filter)` | 会取完所有页 |
+| `aggregate(pipeline)` | `$match` `$sort` `$group` `$project` `$set` `$unwind` `$skip` `$limit` `$count` `$lookup`；`$lookup.from` 写声明或 alias，数据层换成集合 ID。`$exists` / `$distinct` / `$frequencies` 阶段不执行，改用 `countBy`、`distinct` 或 `$group` |
+
+| 写入 | 说明 |
+| --- | --- |
+| `insertOne(doc)`、`insertMany(docs)` | 可带 `_id`；`insertMany` 最多 200 条、原子 |
+| `updateOne` / `updateMany` / `replaceOne` | 更新用操作符（`$set` `$inc` `$push` `$unset`…）；`replaceOne` 会丢掉其他代码版本写入的字段 |
+| `deleteOne` / `deleteMany` | 软删除，App Key 需要 `uns.delete` |
+| `findOneAndUpdate` / `findOneAndReplace` / `findOneAndDelete` | 原子读改写，默认返回更新后的文档 |
+| `bulkWrite(ops)` | `insertOne` / `updateOne` / `replaceOne` / `deleteOne` 混合，最多 200 项、原子 |
+| `data.transact(steps)` | 跨集合原子写，见 [一致性](consistency.md) |
+
+## 批量与原子性
+
+| 调用 | 上限 | 原子 |
+| --- | --- | --- |
+| `insertMany`、`bulkWrite`、`data.transact` | 每次 ≤200 项，超过在发送前抛 `BATCH_LIMIT_EXCEEDED` | 是，全部或全不 |
+| `updateMany`、`deleteMany` | 无上限，翻页处理所有匹配 | 否，逐条提交；已有提交后失败时错误保留原 `code`，`execution: 'committed'`、`retry.safe: false`，`details` 是累计结果（`matchedCount` 等、`status: 'partiallyCommitted'`、续做位置 `resumeAfter`） |
+
+超过 200 条按 200 分块写入（循环分块即可），每块是一次独立的原子调用：数据层自动给每次调用生成幂等键并在重试中复用，不需要手写；要让“某块写过就不再写”跨进程重启也成立，用固定 `_id`（或按业务意图显式传 `idempotencyKey`）。多条文档必须一起成功或失败时，用一次 `data.transact`（≤200 步），不要用 `updateMany`。不要在循环里逐条调用数据层：读用一次 `get` / `$in` 或 `queryBatch`，写用 `insertMany` / `updateMany` / `bulkWrite` 或 `data.transact`。
+
+### 非原子批量中途失败
+
+`updateMany` / `deleteMany` 已经提交了一部分后失败时（`execution === 'committed'`），不要整体重做：`$inc`、`$push` 这类更新会把已提交的记录再改一次。把 `details.resumeAfter` 传回去，从失败处继续：
+
+```ts
+import { DataError, type Collection } from '@tier0/sdk-v2/data';
+
+export async function bumpAll(items: Collection<{ status: string; views: number }>) {
+  let resumeAfter: string | undefined;
+  for (let round = 0; round < 3; round += 1) {
+    try {
+      return await items.updateMany({ status: 'OPEN' }, { $inc: { views: 1 } }, { resumeAfter });
+    } catch (error) {
+      // 只续做已证明部分提交、且给了续做位置的失败；结局未知的那一页要先核对。
+      const next = error instanceof DataError && error.execution === 'committed' ? error.details.resumeAfter : undefined;
+      if (typeof next !== 'string') throw error;
+      resumeAfter = next;
+    }
+  }
+  throw new Error('updateMany kept failing');
+}
+```
+
+`execution === 'unknown'` 时失败的那一页可能已经部分生效，续做前先核对。
+
+## 过滤
+
+支持 `$eq $ne $gt $gte $lt $lte $in $nin $exists $all $size $elemMatch $not $and $or $nor` 和 `$contains`。`$contains` 是子串匹配（1–256 字节，无通配符和正则），只对 ASCII 字母忽略大小写；缺失、null、非字符串值不匹配；只能用于声明为字符串的字段，用在数组或数字字段上返回 `INVALID_REQUEST`。它不能使用索引，大集合上可能触发 10 秒执行超时（`QUERY_TIMEOUT`），要和有索引的条件一起用。`$in` 最多 200 个值，排序最多 4 个字段（`toSortPairs` 也导出给自定义查询转换使用）。
+
+## 校验
+
+写入前按声明严格校验：未知字段、类型错误、未声明的更新路径抛 `ZodError`（HTTP 400 语义）。读取不严格解析：记录可能含其他代码版本写入的字段、新的枚举值，或缺少后来新增的字段。枚举渲染要有兜底标签，后加的字段按可能缺失处理。
+
+## 订阅变更
+
+`data.subscribe(...)` 返回已提交变更的异步迭代器（UNS `records:subscribe`，服务端推送）：断线、超时、服务端结束都自动续传（`Last-Event-ID`），刷新页面不需要轮询。事件只有标识，不带业务数据，收到后按需重新读取。
+
+```ts
+import { z } from 'zod';
+import { createDataClient, defineCollection, runAsApp, type SubscriptionEvent } from '@tier0/sdk-v2/data';
+
+const tickets = defineCollection({ alias: 'tickets', schema: z.object({ title: z.string(), status: z.enum(['OPEN', 'DONE']) }) });
+const data = createDataClient({ collections: [tickets] });
+
+/** 一个进程一条 App 级订阅，在进程内扇出给浏览器。 */
+export async function pumpChanges(send: (event: SubscriptionEvent) => void, signal: AbortSignal) {
+  await runAsApp(async () => {
+    for await (const event of data.subscribe({ collections: [tickets], signal })) {
+      // reset：续传位置失效或访问范围变化，浏览器应重新读取当前数据。
+      send(event);
+    }
+  });
+}
+```
+
+- 事件：`{ type: 'change', eventId, collection（alias）, collectionId, change: 'record' | 'delete', recordId, revision, occurredAt, restricted }`、集合级通知 `{ type: 'change', …, change: 'collection', restricted: true }`（没有 `recordId` / `revision`），或 `{ type: 'reset', reason, message? }`。心跳与重连在 SDK 内部处理；迭代抛出 `DataError` 表示不能再重试（如 403），正常结束只有 `signal` 中止或跳出循环。
+- 事件按写入事务的顺序到达，不是提交顺序，同一记录的 revision 可能乱序。SDK 已丢弃 revision 不大于该记录已投递 revision 的非 `delete` 变更；`delete` 一律投递（迟到的也投递），并清除该记录的 revision（同一 ID 再写入时可能从 1 开始）。收到事件后按 `recordId` 重新读取，不要用事件顺序推断记录的最终状态。
+- `reset`：`CURSOR_EXPIRED`（续传位置已被清理、游标无法解开或租户库已迁移）或 `SCOPE_CHANGED`（访问范围变化，例如集合不再可读）。重新读取当前数据；SDK 随后不带续传位置重新订阅。
+- `restricted: true`：该集合有员工数据规则。以 App 身份打开的订阅能看到所有记录的变更，所以默认把这类变更换成集合级通知，可以直接转发给任何员工的浏览器，浏览器再通过受规则约束的接口重新读取。只有不转发给浏览器的服务端逻辑才传 `restricted: 'record'` 拿完整事件（转发前仍须逐个经 `redactRestricted`）。
+- 默认订阅全部已声明的集合（最多 64 个）；`recordIds`（最多 100 个）只能配一个集合。
+- 订阅不占数据请求的并发名额，但每个租户的订阅数有上限（超出时 SDK 按 429 自动退避重连）：一个服务端进程只开一条订阅，在进程内扇出，不要每个浏览器连接开一条。App 刚导入还没就绪（`APP_NOT_READY`）时订阅会一直等待，不会结束。
+- 变更保留 24 小时；`lastEventId` 太旧时收到 `reset`。`lastEventId` 必须是收到过的事件 ID（可见 ASCII），否则调用时直接抛 `TypeError`。

package/skills/tier0-sdk-v2/tier0-sdk-v2-data/references/schema-evolution.md

@@ -0,0 +1,36 @@
+# Schema 演进
+
+Preview 与部署后的 App 共用集合，较旧的部署版本随时可能用它的旧声明冷启动。因此 ensure 只会**放宽**：存储是所有运行过的声明的并集，每个版本的写入都保持有效。按变更类型选择做法：
+
+| 变更 | 做法 |
+| --- | --- |
+| 新增可选字段（任意层级，含数组元素内）、新增枚举值、字段改为可选、`int` → `number`、放宽或去掉 `min`/`max`、新增索引 | 修改声明；下次访问时 ensure 生效 |
+| 修改 `.describe()` 文本或集合 `description` | 修改声明，然后通过 tier0 MCP 执行 `schema:replace`，请求体用 `compileCollection(declaration)` 的结果（先 `dryRun`：期望 `widened`；`narrowed` 说明存储里还有该声明之外的内容，例如其他版本的字段——合并进请求体或停止）。ensure 保留已存储的描述并报告 `ANNOTATION_NOT_APPLIED`；新字段和新集合在创建时带上描述 |
+| 新增每条记录都必须有的字段 | 先以 `.optional()` 加入，所有写入路径都写它，回填旧记录，等部署版本也写入后再用 `schema:replace` 改为必填 |
+| 删除或重命名字段 | 代码不再使用旧字段（它可以留在存储里）；新名字就是新的可选字段。通过 tier0 MCP 一次性回填（`records:updateMany` 配 `$rename` / `$set`） |
+| 修改字段类型 | 换一个新字段名，回填，读取时以旧字段兜底。ensure 从不转换类型（`SCHEMA_CONFLICT`） |
+| 删除枚举值、可选改必填、从存储删除字段、删除索引、收紧 `min`/`max` | 只能在部署版本不再写旧形态之后：通过 tier0 MCP `schema:replace`，先 `dryRun` |
+
+不要为了“重置” Schema 而 `deleteMany` 或重建集合：部署版本的数据会一起丢失。修改 `seed` 不会重新写种子。
+
+## 运行时代码与 worker 操作的边界
+
+`schema:replace`、`archive`、`restore` 由 worker 通过 tier0 MCP 显式执行（`/uns/app/collections/schema:replace`、`archive`、`restore`），App 运行时代码不调用。数据层导出的 `compileCollection(declaration)` 给出与运行时 ensure 完全一致的条目 `{ alias, recordSchema, indexes, description? }`，可作为 ensure `dryRun` 或 `schema:replace` 请求体的基础。
+
+```ts
+import { z } from 'zod';
+import { compileCollection, defineCollection } from '@tier0/sdk-v2/data';
+
+const tickets = defineCollection({
+  alias: 'tickets',
+  schema: z.object({ title: z.string().describe('Short summary'), severity: z.enum(['LOW', 'HIGH']).optional() }),
+});
+
+/** schema:replace 请求体的基础；expectedRevision 取自 ensure 结果的集合 revision。 */
+export function replaceBody(expectedRevision: number) {
+  const { alias, recordSchema, indexes } = compileCollection(tickets);
+  return { alias, recordSchema, indexes, expectedRevision, dryRun: true };
+}
+```
+
+Schema 中 `ignored`、`warnings`、`conflicts`、`violations` 的路径用 `.` 连接属性，用 `[]` 表示数组元素（`lines.[].qty`）。

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

@@ -0,0 +1,85 @@
+---
+name: tier0-sdk-v2-files
+description: 使用 @tier0/sdk-v2 实现 Tier0 应用附件、头像、导入导出、生成报告、上传下载和持久化文件引用，包括分片上传及中断处理。
+---
+
+# 文件与附件
+
+## 按任务读取操作文档
+
+| 任务 | 参考 |
+| --- | --- |
+| 上传并保存 filePath | [上传](references/upload.md) |
+| 大文件、进度、中断会话 | [分片上传](references/multipart.md) |
+| 图片预览、临时访问地址 | [访问 URL](references/url.md) |
+| 服务端转发、浏览器保存附件 | [下载](references/download.md) |
+| 删除对象及核验回执 | [删除](references/delete.md) |
+
+沿用 v1 的业务流程，调用已适配 v2；不提供旧版自动续传/并发助手。
+
+业务文件使用平台对象存储，数据库保存返回的 filePath。App 本地目录可用于临时处理和构建，但不能替代持久化上传。使用服务端 client.files，API Key 不下发给浏览器或对象存储。
+
+## 上传并保存引用
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function uploadReport(text: string) {
+  const client = createClient();
+  const file = new File([text], 'report.txt', { type: 'text/plain;charset=utf-8' });
+  const saved = await client.files.upload(file);
+  // 将 filePath 保存到业务记录；临时 URL 到期后重新获取。
+  return { filePath: saved.filePath };
+}
+export async function downloadFile(filePath: string) {
+  const response = await createClient().files.download({ filePath });
+  return response.arrayBuffer();
+}
+export async function getTemporaryLink(filePath: string) {
+  return createClient().files.url({ filePath, expiredSec: 300 });
+}
+```
+
+upload 接收 Web File；Node 20.19+ 可直接构造。若文件来自磁盘，先读取内容构造 File，别把本地路径字符串当文件参数。大文件避免全部读入内存后重复复制；按业务运行环境决定流转方式。
+
+## 上传协议与参数
+
+- `upload(file, options)` 自动填写 fileName/contentType/size；options 支持平台定义的 business/useBy/visibility/sessionId/appInstanceId 与 signal，不猜测这些字段的合法业务枚举。
+- 普通上传先向平台申请 postUrl/postFields，再向对象存储提交表单，file 必须排在签名字段之后。SDK 已处理，不能手工附带平台 Authorization。
+- filePath 为持久化引用；私有文件的 fileUrl 为临时地址，公开文件可能返回公开 URL。发通知或生成页面时，按当前权限请求访问 URL。
+- 下载通过平台申请签名地址后匿名读取，使用 `client.files.download`，不要手动跟随携带 API Key 的下载重定向。
+
+## 分片上传
+
+超过 100 MiB 自动分片，也可显式调用：
+
+```ts
+import { createClient, MultipartUploadError } from '@tier0/sdk-v2';
+
+export async function uploadLargeFile(file: File, signal?: AbortSignal) {
+  try {
+    return await createClient().files.uploadMultipart(file, {
+      partSize: 8 * 1024 * 1024, signal,
+      onProgress: ({ uploadedBytes, totalBytes }) => {
+        console.info({ uploadedBytes, totalBytes });
+      },
+    });
+  } catch (error) {
+    if (error instanceof MultipartUploadError) {
+      // 交给受控的作业存储保留 session；不要自动 complete/abort。
+      return { interrupted: true as const, session: error.session };
+    }
+    throw error;
+  }
+}
+```
+
+partSize 至少 5 MiB；SDK 使用服务端返回的实际分片大小，首版顺序上传，不自动重试/续传。中断 session 含 fileKey、uploadId、已成功 parts/ETag、completionAttempted；它是恢复依据，不是上传成功回执。
+
+`files.multipart` 提供 init/partUrls/complete/abort 原子接口。继续已有分片时保留服务端 ETag；跨域直传还需要存储暴露 ETag 响应头。completionAttempted=true 时先核对最终文件是否存在，不能盲目重新完成或终止。当前 SDK 未提供自动列举远端分片的恢复助手。
+
+## 删除与失败
+
+`files.delete({ filePath })` 返回 `{ deleted }`，deleted=false 不能显示“已删除”。删除前按业务引用关系处理，读取/下载请求不附带删除。
+
+平台阶段抛 ApiError/TransportError，存储阶段还可能抛 fetch/Abort 错误；不要吞掉上传失败后仍保存“成功”记录。上传/下载超时覆盖取得响应头阶段，返回 Response 的后续流由调用方消费和管理。

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

@@ -0,0 +1,22 @@
+# 删除文件
+
+方法：`files.delete({filePath}, {signal}?)`；POST /openapi/v1/assets/files/delete。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| filePath | string | 是 | 业务记录中已确认目标的上传引用 |
+| signal | AbortSignal | 否 | 第二参数；取消客户端等待 |
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function deleteAttachment(filePath: string, client: Tier0Client = createClient()) {
+  const result = await client.files.delete({ filePath });
+  if (!result.deleted) throw new Error('平台未确认文件已删除');
+  return { deleted: true };
+}
+```
+
+删除前明确目标及业务引用，读取/下载不附带删除。返回已解包的 {deleted}；不要复制 v1 把 204/空体也无条件视为成功的逻辑。v2 要按实际回执判断。
+
+对象删除不提供 SDK 恢复功能。401/403 处理身份与授权；网络中断/结果未知时先对账，不把错误当“已经不存在”，不自动换身份重试。

package/skills/tier0-sdk-v2/tier0-sdk-v2-files/references/download.md

@@ -0,0 +1,49 @@
+# 下载与应用附件保存
+
+v2 方法：`files.download({filePath,…}, {signal}?) → Promise<Response>`。与 v1 不同，返回值本身就是 Response，不再取 result.response。
+
+v2 先请求文件 URL，再匿名读取对象存储；不沿用带 Key 的重定向下载链。平台认证信息不能转发给存储。
+
+## 同源服务端下载
+
+应用路由先校验登录和业务权限，再按业务记录 ID 从数据库取可信 filePath。下例只负责已经授权后的转发，不可直接暴露为接受任意 filePath 的公共接口。
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function streamAuthorizedAttachment(
+  filePath: string, client: Tier0Client = createClient(), signal?: AbortSignal,
+) {
+  const upstream = await client.files.download({ filePath }, { signal });
+  return new Response(upstream.body, {
+    headers: {
+      'Content-Type': upstream.headers.get('content-type') ?? 'application/octet-stream',
+      'Content-Disposition': 'attachment',
+      'Cache-Control': 'private, no-store',
+    },
+  });
+}
+```
+
+大文件直接转发 response.body，避免服务端先完整 buffer。返回响应头后的流消费/取消由应用管理；SDK 请求超时不覆盖后续所有流读取。
+
+## 浏览器保存
+
+浏览器访问自己的业务下载路由，不持有平台 Key。下面的路由是应用需要实现的接口。
+
+```ts
+export async function saveAttachment(recordId: string, fileName: string) {
+  const response = await fetch('/api/attachments/' + encodeURIComponent(recordId) + '/download');
+  if (!response.ok) throw new Error('附件下载失败');
+  const url = URL.createObjectURL(await response.blob());
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = fileName;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+```
+
+Blob 方案会占用浏览器内存；超大文件按应用支持的流式保存能力设计。不能将权限失败当空文件下载，也不能将文件不存在当成网络异常重试。

package/skills/tier0-sdk-v2/tier0-sdk-v2-files/references/multipart.md

@@ -0,0 +1,42 @@
+# 分片上传、进度和中断
+
+| 调用 | 行为 |
+| --- | --- |
+| files.upload(file) | 大于 100 MiB 自动分片 |
+| files.uploadMultipart(file, options) | 非空文件显式分片，可报告进度 |
+| files.multipart.init/partUrls/complete/abort | 原子接口，普通业务上传使用上面两个助手 |
+
+| options 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| partSize | number | 默认 8 MiB，至少 5 MiB；实际采用服务器返回值 |
+| onProgress | function | 收到 uploadedBytes、totalBytes |
+| signal | AbortSignal | 取消等待/传输 |
+| 其余上传元数据 | string | 与 upload 相同 |
+
+```ts
+import { createClient, MultipartUploadError, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function uploadWithProgress(
+  file: File, report: (uploadedBytes: number, totalBytes: number) => void,
+  client: Tier0Client = createClient(), signal?: AbortSignal,
+) {
+  try {
+    const saved = await client.files.uploadMultipart(file, {
+      partSize: 8 * 1024 * 1024, signal,
+      onProgress: progress => report(progress.uploadedBytes, progress.totalBytes),
+    });
+    return { state: 'completed' as const, filePath: saved.filePath };
+  } catch (error) {
+    if (error instanceof MultipartUploadError) {
+      return { state: 'interrupted' as const, session: error.session };
+    }
+    throw error;
+  }
+}
+```
+
+成功后才持久化 filePath。中断 session 包含 fileKey、uploadId、parts（partNumber/etag）、completionAttempted；session 不是完成回执，不公开到日志或无关用户。
+
+v2 首版顺序上传，无自动重试、并发参数或一键续传。不要复制 v1 的 resumeMultipartUpload、multipartSession 等不存在的助手。部分 PUT 可能成功但回执丢失，不能仅凭本地 parts 判断远端完整状态。跨域存储需要暴露 ETag 响应头。
+
+completionAttempted=true 表示 complete 可能已提交，先对账最终文件，不能直接 abort 或重复 complete。明确放弃未完成会话时才调用 abort；初始化请求本身结果未知且无 session 时，保存错误信息交由平台对账，不猜 uploadId。

package/skills/tier0-sdk-v2/tier0-sdk-v2-files/references/upload.md

@@ -0,0 +1,27 @@
+# 上传并保存文件引用
+
+从 v1 的 uploadFile 流程迁移，v2 使用 `client.files.upload(file, options)`；独立入口为 `createFilesClient`（@tier0/sdk-v2/files）。Node.js 20.19+。浏览器只调用应用自己的上传接口，平台 Key 留在服务端。
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| file | File | 是 | 名称、MIME、大小从 File 读取；不是磁盘路径字符串 |
+| options.business / useBy | string | 否 | 平台定义的业务归属，不猜枚举 |
+| options.visibility | string | 否 | 根据业务授权选择公开或私有，不自动公开 |
+| options.sessionId / appInstanceId | string | 否 | 真实运行上下文，不用 projectId 替代 |
+| options.signal | AbortSignal | 否 | 取消等待/上传，不保证服务端回滚 |
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function uploadAttachment(file: File, client: Tier0Client = createClient()) {
+  const saved = await client.files.upload(file);
+  if (!saved.filePath) throw new Error('上传回执缺少 filePath');
+  return { filePath: saved.filePath };
+}
+```
+
+上传流程：平台 prepareUpload 返回 postUrl/postFields/filePath → SDK 按签名字段在前、file 在后构建表单 → 匿名上传存储。不要给对象存储附带平台 Authorization。上传失败时不能将准备阶段返回的 filePath 当成功附件保存。
+
+业务表持久化 filePath；临时签名 URL 不作为长期引用。文件写入和业务记录写入不是原子事务，业务保存失败时记录待清理对象，只在任务授权范围内清理。
+
+文件大于 100 MiB 时自动分片；阈值不是单文件产品上限，套餐配额/文件类型限制由后端决定。需要进度时显式用 [uploadMultipart](multipart.md)。v2 没有 v1 的 options.multipart/concurrency/retry/resume 控件，不照抄旧参数。

package/skills/tier0-sdk-v2/tier0-sdk-v2-files/references/url.md

@@ -0,0 +1,22 @@
+# 获取文件访问地址
+
+方法：`files.url({filePath,expiredSec?,responseContentDisposition?}, {signal}?)`；GET /openapi/v1/assets/files/url。
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| filePath | string | 是 | 上传返回的持久化引用 |
+| expiredSec | number / bigint | 否 | 请求有效期（秒），由后端决定实际期限 |
+| responseContentDisposition | string | 否 | 底层响应头提示，不代替浏览器保存动作 |
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function getPreview(filePath: string, client: Tier0Client = createClient()) {
+  const result = await client.files.url({ filePath, expiredSec: 300 });
+  return { url: result.fileUrl, expiresAt: result.expiresAt };
+}
+```
+
+返回已解包的 fileUrl、可选 expiresAt。私有文件是短期签名 URL；公开文件可能是公开地址且无过期字段。不能对缺失 expiresAt 猜时间，也不能用普通 Number 强转大整数。
+
+URL 适合图片预览、媒体引用或明确要求的临时分享。业务表仍保存 filePath。附件“下载”用[下载流程](download.md)，避免直接导航签名 URL 进入 PDF 预览器。分享链接不改变文件权限，也不允许把 API Key 拼进 URL。

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

@@ -0,0 +1,56 @@
+---
+name: tier0-sdk-v2-members
+description: 使用 @tier0/sdk-v2 查询 Tier0 Workspace 成员、搜索用户和解析通知收件人，并按 appId 查询能使用某个 App 的成员；区分 Workspace 身份与 App 访问授权。
+---
+
+# Workspace 成员查询
+
+参数表、成员选择和有界增量分页见 [Workspace 成员](references/platform-members.md)。v1 的项目成员接口未迁入 v2，不能用 Workspace 列表代替 App 授权名单。
+
+公开入口有两个：`client.members.listWorkspace` 只用于 Workspace 级的成员选择；需要能使用某个 App 的成员时用 `client.members.listApp`。没有 project 成员迁移别名，也不在客户端推断 App 成员。使用服务端 API Key；平台授权决定可查询范围。
+
+## 搜索与展示候选人
+
+```ts
+import { createClient } from '@tier0/sdk-v2';
+
+export async function searchMembers(keyword: string, page = 1) {
+  const result = await createClient().members.listWorkspace({
+    keyword, statuses: ['active'], page, size: 20,
+  });
+  return {
+    list: result.list.map(member => ({
+      userId: member.userId,
+      label: member.nickName || member.userName || member.email || '未命名成员',
+      email: member.email,
+      status: member.status,
+      roles: member.roles,
+    })),
+    total: result.total, page: result.page, size: result.size,
+  };
+}
+```
+
+返回值已解包，不读 result.data。userId 始终作为字符串传给通知或业务表；不要转换成 Number。名称不唯一，用户意图不能唯一定位时返回候选人，不能静默选第一个。
+
+## 筛选与分页
+
+请求可带 keyword、page、size、roleKey、roles、statuses、updatedAtStart、updatedAtEnd。角色与状态取自实际平台定义，不造枚举或假定固定管理员角色。时间字段为字符串，按服务端认可格式使用；不要将 number 毫秒直接填进去。
+
+返回 list/total/page/size；total/page/size 可能为 number 或 bigint。批量同步按服务端返回分页继续，并限定本次任务的范围，不把一页或受限视图宣称为完整目录。按更新时间增量同步时保存已确认的水位并处理边界重复。
+
+## 用于通知
+
+1. 确定查询的是当前 Workspace，按姓名/邮箱等输入取得候选人。
+2. 使用选定的 userId 调用通知，展示名只用于 UI。
+3. 需要“这个 App 的所有用户”时用 `listApp` 取访问名单，不能直接遍历 Workspace 成员群发。
+
+[通知 Skill](../tier0-sdk-v2-notifications/SKILL.md)说明渠道与幂等。成员查询不会替你建立 App 访问权限，也不能证明收件人可以打开通知里的业务页面。
+
+## App 可用成员
+
+能使用某个 App 的成员用 `members.listApp`，参数、示例与错误处理见 [App 可用成员](references/app-members.md)。`appId` 必须显式传入，SDK 不隐式读取 `APP_ID`；查询当前 App 时传 `getCurrentAppId()`。接口只接受 API Key，登录会话不能调用；绑定 App 的凭证只能查自己的 appId，查其他 App 返回 403。3003016 / 3003017 都是 HTTP 503，表示访问名单暂时无法给出，不是空名单：按 `ApiError.code` 分支，不匹配 message 文本；3003016 需要重新部署 App，3003017 可稍后重试。
+
+## 当前边界
+
+whoami 是 Key 身份查询，不是成员列表；它也不是浏览器当前员工身份。401/403 应核对 Workspace 和权限，不自动切换到更高权限凭证。只回传界面实际需要的成员字段，避免把整个目录和角色数据泄露给无关调用方。

package/skills/tier0-sdk-v2/tier0-sdk-v2-members/references/app-members.md

@@ -0,0 +1,41 @@
+# App 可用成员
+
+方法：`members.listApp(body)`；POST /openapi/v1/apps/access-members/list。返回能使用该 App 线上版本的有效成员。`appId` 必填且由调用方显式传入，SDK 不隐式读取 `APP_ID`；查询当前 App 时传 `getCurrentAppId()`。接口只接受 API Key，登录会话不能调用；绑定 App 的凭证只能查自己的 appId，查其他 App 返回 403。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| appId | string | 必填，agent-platform App UUID |
+| roleKeys | string[] | 任一命中即可，大小写不敏感 |
+| grantedAtStart / grantedAtEnd | number / bigint | 授权时间，Unix 毫秒，闭区间，精度为秒 |
+| page / size | number / bigint | 分页 |
+
+```ts
+import { ApiError, createClient, getCurrentAppId, type Tier0Client } from '@tier0/sdk-v2';
+
+/** 线上版本的角色事实未落库：重试无效，需要重新部署 App。 */
+const APP_ACCESS_LIST_UNDETERMINED = 3003016;
+/** 成员有效状态暂时取不到：稍后重试。 */
+const APP_ACCESS_LIST_UNAVAILABLE = 3003017;
+
+export async function appMembers(page = 1, client: Tier0Client = createClient(), appId = getCurrentAppId()) {
+  try {
+    const result = await client.members.listApp({ appId, page, size: 20 });
+    return {
+      list: result.list.map(member => ({
+        userId: member.userId,
+        label: member.userName || member.email || '未命名成员',
+        roles: member.roles.map(role => role.roleName),
+      })),
+      total: result.total, page: result.page, size: result.size,
+    };
+  } catch (error) {
+    if (error instanceof ApiError && error.code === APP_ACCESS_LIST_UNDETERMINED) throw new Error('App 访问名单无法确定，请重新部署 App');
+    if (error instanceof ApiError && error.code === APP_ACCESS_LIST_UNAVAILABLE) throw new Error('App 访问名单暂不可用，请稍后重试');
+    throw error;
+  }
+}
+```
+
+返回已解包的 appId、published（1 已发布 / 2 未发布）、allActiveMembers（1 所有有效成员都可使用 / 2 按角色授权）、roles、list、total、page、size。成员的 roles[].sources 区分直接授予（direct）和经成员组授予（group）。userId 保持字符串。
+
+3003016 / 3003017 都是 HTTP 503：访问名单暂时无法给出，不是空名单，也不代表所有人可用。按 `ApiError.code` 分支，不匹配 message 文本。3003016 是线上版本角色事实未落库，重试无效，需要重新部署 App；3003017 是成员有效状态暂时取不到，可稍后重试。无权限（403）时报告配置问题，不改用 Workspace 成员列表代替。

package/skills/tier0-sdk-v2/tier0-sdk-v2-members/references/platform-members.md

@@ -0,0 +1,56 @@
+# Workspace 成员查询与选择
+
+方法：`members.listWorkspace(body)`；POST /openapi/v1/platform/getMembers。查询当前 Key 所属 Workspace；云端需要 uns:read。通知读写权限不自动包含成员查询。
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| keyword | string | 姓名、昵称、邮箱关键词 |
+| roleKey / roles | string / string[] | 单个或多个角色筛选，组合为 OR |
+| statuses | string[] | active / disabled；选择通知收件人通常 active |
+| updatedAtStart / updatedAtEnd | string | RFC3339，包含边界 |
+| page | number / bigint | 从 1 开始，默认 1 |
+| size | number / bigint | 默认 20，最大 100 |
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function memberOptions(keyword: string, page = 1, client: Tier0Client = createClient()) {
+  const result = await client.members.listWorkspace({ keyword, statuses: ['active'], page, size: 20 });
+  return {
+    options: result.list.map(member => ({
+      value: member.userId,
+      label: member.nickName || member.userName || member.email || '未命名成员',
+      email: member.email, roles: member.roles.map(role => role.roleName || role.roleKey),
+    })),
+    total: result.total, page: result.page, size: result.size,
+  };
+}
+```
+
+v2 返回已解包的 list/total/page/size，不读 result.data。userId、roleId 保持字符串；value 留作内部选项值，用户看到姓名/邮箱/角色，不让用户填写 ID。不确定匹配时展示候选人，不默认选第一项。
+
+内置公开角色 owner/builder/operator；筛选兼容性以服务端为准，匹配后仍返回成员全部角色。不要根据某个角色名自行推断 App 访问授权。
+
+## 有界分页同步
+
+```ts
+import { createClient, type Tier0Client } from '@tier0/sdk-v2';
+
+export async function* scanMembers(
+  updatedAtStart: string, updatedAtEnd: string, maxPages = 20,
+  client: Tier0Client = createClient(),
+) {
+  if (!Number.isSafeInteger(maxPages) || maxPages < 1) throw new Error('无效页数上限');
+  for (let page = 1; page <= maxPages; page++) {
+    const result = await client.members.listWorkspace({ page, size: 100, updatedAtStart, updatedAtEnd });
+    yield result.list;
+    if (BigInt(result.page) * BigInt(result.size) >= BigInt(result.total)) return;
+    if (!result.list.length) throw new Error('分页结果与总数不一致');
+  }
+  throw new Error('达到同步页数上限，结果未完整');
+}
+```
+
+增量时间包含边界，按 userId/updatedAt 去重，成功完成后再保存水位；跨页没有固定快照保证。只向界面返回实际需要字段。
+
+v1 project-members 不迁移：v2 没有 getCurrentProjectId 或项目成员接口。Workspace 列表只用于 Workspace 级选择，不能冒充某 App 的可访问用户；需要 App 可用成员时用 `members.listApp`（见 [App 可用成员](app-members.md)）。无权限时报告配置问题，不以用户手填 ID 绕过。