feat: add agent-first minitool studio MVP
CI / verify (push) Has been cancelled

This commit is contained in:
2026-09-17 21:54:33 +08:00
commit 74a8f7cdf3
51 changed files with 3855 additions and 0 deletions
+192
View File
@@ -0,0 +1,192 @@
# 小工具 JSBridge API 规范
容器会注入 **`window.xhs.miniTool.*`**,业务代码通过它调用 Native 能力。字段以本文档为准,表中未声明的字段不要传。
## 调用约定
| 项 | 规则 |
| --- | --- |
| 入口 | `window.xhs.miniTool.<apiName>(options)` |
| 两种用法 | 不传回调 → 返回 `Promise`;传 `success` / `fail` / `complete` 任一 → 返回 `undefined`,经回调拿结果 |
| 成功 | Promise resolve / `success(result)`;关注业务字段(见各 API「结果」),无业务字段则结果为空 |
| 失败 | Promise reject / `fail(error)`;失败原因看 `error.errMsg`(形如 `<apiName>:fail …`),可能带 `errCode` |
| `complete` | 成功或失败都会回调,参数为对应的 result / error |
| 禁止 | 不要调用本文未列出的 API,不要传字段表未声明的字段 |
## API 索引
| API | 说明 |
| --- | --- |
| [`postNote`](#postnote) | 发布笔记 |
| [`saveImageToPhotosAlbum`](#saveimagetophotosalbum) | 保存图片到系统相册 |
| [`openRedPage`](#openredpage) | 通用原生页面跳转 |
| [`writeTempFile`](#writetempfile) | base64 转临时文件 |
## postNote
发布笔记。
- **调用**:`window.xhs.miniTool.postNote(options)`
### 使用规则
- `mediaInfo` 必填;`image_resources`(图文)、`video_resources`(视频)、`live_photo_resources`(实况)至少传一种,可同时传。
- 所有地址(`url` / `video_url` / `cover_url`)承载 base64 data:uri 或网络地址,格式由 Native 侧校验。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| `title` | string | 否 | 标题,最长 20 |
| `content` | string | 否 | 正文,最长 1000 |
| `pageType` | `"video_publish" \| "photo_publish" \| "slides_edit"` | 否 | 页面类型 |
| `mediaInfo` | object | 是 | 见「mediaInfo」 |
| `tags` | string | 否 | 标签 |
**`mediaInfo`**
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| `image_resources` | `{ url }[]` | 否 | 图文,1–18 张;`url` 图片地址 |
| `video_resources` | `{ video_url, cover_url? }` | 否 | 视频;`video_url` 视频地址,`cover_url` 可选封面 |
| `live_photo_resources` | `{ url, video_url }[]` | 否 | 实况,1–18 张;`url` 动图封面,`video_url` 动图视频 |
### 结果
成功结果仅含通用 `errMsg`,无额外业务字段。
### 示例
图文笔记:
```js
await window.xhs.miniTool.postNote({
title: "标题",
content: "正文",
pageType: "photo_publish",
mediaInfo: {
image_resources: [{ url: "data:image/png;base64,..." }],
},
});
```
视频笔记:
```js
await window.xhs.miniTool.postNote({
pageType: "video_publish",
mediaInfo: {
video_resources: { video_url: "...", cover_url: "..." },
},
});
```
## saveImageToPhotosAlbum
保存图片到系统相册。
- **调用**:`window.xhs.miniTool.saveImageToPhotosAlbum(options)`
### 使用规则
- `filePath` 只接受 base64 data:uri 或本地路径,传网络地址(`http(s)://`)会失败。
- 已有 base64 时可先调 `writeTempFile` 换取本地 `filePath`,再传入本 API。
- 需由用户主动操作触发;首次调用可能弹系统相册权限。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| `filePath` | string | 是 | 本地图片路径(base64 data:uri 或本地引用),不支持网络地址 |
### 结果
成功结果仅含通用 `errMsg`,无额外业务字段。
### 示例
```js
await window.xhs.miniTool.saveImageToPhotosAlbum({
filePath: "data:image/png;base64,...",
});
```
## openRedPage
通用原生页面跳转。
- **调用**:`window.xhs.miniTool.openRedPage(options)`
### 使用规则
- `type` 命中 Native 规则表白名单才放行,未命中直接失败;规则表由客户端维护。
- `params` 为语义参数,由规则表映射到目标页面;信任字段由客户端强制注入。
- 跳转会离开当前小工具页面,调用前应完成本地状态持久化。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| `type` | string | 是 | 规则表 key(如 search / note / user…) |
| `params` | object | 否 | 语义参数(如 `{ keyword }`) |
### 结果
成功结果仅含通用 `errMsg`,无额外业务字段。
### 示例
```js
await window.xhs.miniTool.openRedPage({
type: "search",
params: { keyword: "连衣裙" },
});
```
## writeTempFile
base64 转临时文件,返回可传给其他 API 的 `filePath`。
- **调用**:`window.xhs.miniTool.writeTempFile(options)`
### 使用规则
- 用于把内存中的 base64(Canvas 导出、选图预览等)落成本地文件,换取 `filePath`。
- **`data` 必须是完整 data:uri**,即 `data:<mime>;base64,<payload>` 开头(如 `data:image/png;base64,iVBORw0KGgo...`);只传裸 base64 字符串会失败。
- `canvas.toDataURL()` / `FileReader.readAsDataURL()` 的返回值已是 data:uri,**不要**再截取 `,` 之后的部分。
- 返回的 `filePath` 为临时文件,即用即弃。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | :---: | --- |
| `data` | string | 是 | 完整 data:uri(`data:<mime>;base64,<payload>`),不接受裸 base64 |
### 结果
成功结果在通用 `errMsg` 之外附带:
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `filePath` | string | 转换得到的临时文件路径 |
### 示例
```js
// canvas.toDataURL() 直接就是 data:uri,原样传入
const { filePath } = await window.xhs.miniTool.writeTempFile({
data: canvas.toDataURL("image/png"), // "data:image/png;base64,iVBORw0KGgo..."
});
await window.xhs.miniTool.saveImageToPhotosAlbum({ filePath });
```
错误用法:
```js
// ✗ 裸 base64,会失败
await window.xhs.miniTool.writeTempFile({ data: "iVBORw0KGgo..." });
// ✗ 手动去掉了 data:uri 前缀
await window.xhs.miniTool.writeTempFile({
data: canvas.toDataURL("image/png").split(",")[1],
});
```