YunYouJun · Sep 24, 2026 · Sep 24, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -21,7 +21,7 @@ jobs:
       - name: Set node
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 22.x
           cache: pnpm
 
       - name: Install
@@ -41,7 +41,7 @@ jobs:
       - name: Set node
         uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 22.x
           cache: pnpm
 
       - name: Install
@@ -55,7 +55,7 @@ jobs:
 
     strategy:
       matrix:
-        node: [16.x]
+        node: [22.x]
         os: [ubuntu-latest]
       fail-fast: false
 

diff --git a/README.md b/README.md
@@ -1,19 +1,26 @@
-# @YunLeFun/toolkit
+# YunLeFun Toolkit
 
-> Toolkit for YunLeFun H5 developing.
+云乐坊的公共工具箱，集中维护可公开复用的协议、类型定义和 npm 包。每个包独立版本化；随包演进的契约说明放在本仓库 `docs/`。
 
 ## Packages
 
-- [@yunlefun/utils](./packages/utils/): Common Utils.
-- [@yunlefun/vueuse](./packages/vueuse/): Helpers with Vue Composition API.
+| 包 | 用途 |
+| --- | --- |
+| [`@yunlefun/assets`](./packages/assets/) | 第一方应用的素材 schema、HTTP 客户端与 Picker 消息协议；尚未发布到 npm |
+| [`@yunlefun/utils`](./packages/utils/) | 通用工具函数 |
+| [`@yunlefun/vueuse`](./packages/vueuse/) | Vue Composition API 工具 |
 
-## Usage
+[`@yunlefun/assets` 契约说明](./docs/assets/README.md)与包源码在同一个仓库，便于按版本核对。公开包只包含客户端契约；使用云乐坊服务仍需相应应用的注册和授权。
+
+## Development
 
 ```bash
-pnpm add -D @yunlefun/vueuse
+pnpm install
+pnpm build
+pnpm test
+pnpm typecheck
 ```
 
-## TODO
+## License
 
-- [ ] Release CLI
-- [ ] Publish `@yunlefun/toolkit`
+[MIT](./LICENSE)
diff --git a/docs/assets/README.md b/docs/assets/README.md
@@ -0,0 +1,34 @@
+# 素材库公开契约
+
+本目录随 `@yunlefun/assets` 版本维护云乐坊第一方应用可依赖的素材契约。包提供 Zod schema、TypeScript 类型、HTTP 客户端和 Picker 消息协议；Drive 服务端负责认证、授权、存储和素材生命周期。公开契约不代表第三方应用可直接接入；使用服务需要事先登记应用与所需权限。
+
+## HTTP API
+
+`createAssetClient` 的 `baseUrl` 为 `/api/v1/library`，资源路径从 `/assets` 开始。旧 `/api/v1/assets` 是独立的兼容接口，不使用此包的响应 schema。
+
+| 方法 | 相对路径 | 客户端方法 |
+| --- | --- | --- |
+| GET | `/assets` | `listAssets` |
+| GET | `/assets/:assetId` | `getAsset` |
+| POST | `/assets/uploads` | `createUpload` |
+| POST | `/assets/uploads/:uploadId/complete` | `completeUpload` |
+| PATCH | `/assets/:assetId` | `updateAsset` |
+| POST | `/assets/:assetId/trash` | `trashAsset` |
+| POST | `/assets/:assetId/restore` | `restoreAsset` |
+| POST | `/assets/:assetId/access` | `createAccess` |
+| DELETE | `/assets/:assetId` | `purgeAsset` |
+| PUT | `/asset-usages/:consumerAppId/:resourceType/:resourceId` | `replaceUsages` |
+
+输入与输出的权威定义在 [`schemas.ts`](../../packages/assets/src/schemas.ts)。客户端解析成功响应及 `{ error }` 失败响应，不自动重试。写入请求生成 `Idempotency-Key`；需要重试同一次操作时，调用方应通过 `headers` 提供原键。会话写入还需要应用提供 CSRF token。列表以 `nextCursor === null` 判断结束，空页仍可能有下一游标。
+
+上传接口只返回短期精确对象 PUT 能力或去重结果；图片字节不经过客户端包或素材 API。签名预览和下载 URL 仅在鉴权后短期签发，不应持久保存。`assetId + sha256` 是消费者保存的稳定引用，名称与标签不参与内容身份。
+
+## Picker v1
+
+`openAssetPicker` 打开 Drive 的 `/picker`，在查询参数中传递已登记 `appId`、调用方精确 `origin`、随机 `requestId` 和 MIME 限制。Drive 只向核准的来源发送版本为 `1` 的 `postMessage`。成功响应包含 `assetId`、`sha256`、`requestId`；失败响应包含错误码与消息。协议的权威 schema 在 [`schemas.ts`](../../packages/assets/src/schemas.ts)。
+
+客户端同时验证弹窗窗口引用、Drive 来源、`requestId` 和消息 schema。消费者收到选择结果后，仍需由自己的服务端核对素材权限；消息中不包含签名 URL 或长期凭据。
+
+## 版本与发布
+
+当前源码版本为 `0.1.0`，尚未发布 npm。协议变更与包版本一起提交；Drive 应在 npm 首发且契约测试通过后改为依赖发布版。在切换前，Drive 的工作区副本是运行时来源，两个副本的协议变更须同步核对。
diff --git a/package.json b/package.json
@@ -4,7 +4,7 @@
   "version": "0.1.2",
   "private": true,
   "packageManager": "pnpm@9.15.9",
-  "description": "Toolkit for YunLeFun developing.",
+  "description": "Public YunLeFun protocols, types, and reusable npm packages.",
   "author": {
     "name": "YunLeFun",
     "email": "i@yunle.fun",
@@ -31,7 +31,7 @@
     "@yunyoujun/utils": "^0.3.5",
     "bumpp": "^9.4.0",
     "eslint": "^9.0.0",
-    "typescript": "^5.4.5",
+    "typescript": "^5.9.3",
     "unbuild": "^2.0.0",
     "vite": "^5.2.8",
     "vitest": "^1.5.0",

diff --git a/packages/assets/LICENSE b/packages/assets/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 YunLeFun Studio | 云乐坊工作室
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/assets/README.md b/packages/assets/README.md
@@ -0,0 +1,36 @@
+# `@yunlefun/assets`
+
+云乐坊第一方应用的素材契约包，提供 Zod schema、TypeScript 类型、HTTP 客户端与 Picker 消息校验。源码与[版本化契约说明](../../docs/assets/README.md)一同维护。
+
+> 当前包尚未发布到 npm。Drive 仍使用其工作区内的同版本实现；切换到本包需等首次发布并验证兼容性。
+
+包不包含 CloudBase、COS、管理员能力或凭据。应用必须由 Drive 注册并授权；公开包本身不授予素材服务访问权。
+
+## Usage
+
+发布后可从 npm 安装：
+
+```bash
+pnpm add @yunlefun/assets
+```
+
+```ts
+import { createAssetClient, openAssetPicker } from '@yunlefun/assets'
+
+const assets = createAssetClient({
+  baseUrl: 'https://drive.yunle.fun/api/v1/library',
+  headers: () => ({ 'x-csrf-token': csrfToken }),
+})
+
+const page = await assets.listAssets({ limit: 30 })
+const selected = await openAssetPicker({
+  appId: 'your-registered-app-id',
+  driveOrigin: 'https://drive.yunle.fun',
+})
+```
+
+`selected` 只包含 `assetId` 和 `sha256` 等选择结果。消费者应在自己的服务端重新鉴权，再获取短期预览或下载能力。上例中的 CSRF 值应由应用自身会话流程提供。
+
+## License
+
+[MIT](./LICENSE)
diff --git a/packages/assets/build.config.ts b/packages/assets/build.config.ts
@@ -0,0 +1,7 @@
+import { defineBuildConfig } from 'unbuild'
+
+export default defineBuildConfig({
+  entries: ['src/index'],
+  declaration: 'node16',
+  clean: true,
+})
diff --git a/packages/assets/package.json b/packages/assets/package.json
@@ -0,0 +1,35 @@
+{
+  "name": "@yunlefun/assets",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "YunLeFun asset schemas, client, and picker protocol for first-party apps",
+  "license": "MIT",
+  "homepage": "https://github.com/YunLeFun/toolkit/tree/main/packages/assets",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YunLeFun/toolkit.git",
+    "directory": "packages/assets"
+  },
+  "bugs": "https://github.com/YunLeFun/toolkit/issues",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": ["LICENSE", "README.md", "dist"],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "unbuild --stub",
+    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "unbuild": "^3.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}