H5 SDK 参考

soduwork-app.js（1.6 版）把即用页面和 SoduWork 连接起来。从 client/sdk/soduwork-app.js 复制到你的即用里，在你自己的脚本之前加载。它可以在原生即用页面里使用，也可以在即用明确授权的 iframe 里使用。

<script src="soduwork-app.js"></script>

每个方法都返回一个回执（Promise）。检查 ok，为 false 时把 reason 显示给用户。

能力

页面用到的每项能力，都要在 source.bridge.capabilities 里声明。没有声明对应能力的调用会被拒绝。

能力	方法
`context.read`	`context.get()`、`user.getCurrent()`
`conversation.send`	`chat.send()`
`composer.control`	`chat.insertText()`、`chat.expand()`、`chat.collapse()`、`attachments.*`
`settings.read` / `settings.write`	`settings.get()` / `settings.update()`
`automation.create`	`automation.create()`
`data.read` / `data.write`	`data.apps()`、`data.get()`、`data.list()`、`data.assetGet()` / `data.batch()`、`data.assetPut()`
`messages.read`	`conversations.list()`、`conversations.messages()`、`notifications.list()`
`library.read`	`library.list()`、`library.read()`
`directory.read`	`directory.list()`
`notifications.send`	`chat.mention()`
`mcp.connect`	`mcp.connect()`
`ai.generate`	`ai.generate()`

上下文

context.get() 返回即用和标签页的上下文；有当前对话时返回对话 ID；还返回主窗口的界面语言 locale（例如 zh-CN）。可以据此选择页面语言，取不到时回退到英文。它不会翻译你的业务数据，也不会覆盖用户在你的页面里自己选的语言。

发送到右侧对话

const receipt = await soduWorkApp.chat.send({
  text: '总结当前选中的记录',
  requestId: soduWorkApp.createRequestId(),
  attachmentIds: []            // 可选
});

ok 表示对话已经接收了消息，不代表模型已经完成。
文字最多 8,000 个字符。
重试同一个操作时使用同一个 requestId，已经发送过的消息不会重复执行；新操作使用新的 requestId。
调用超时时，先查看右侧对话，再决定是否重新发送。

events.onRefresh(callback) 在右侧对话的一轮结束时触发，可以在这里重新读取数据。失败或取消也会结束一轮，所以刷新不代表工作成功。

附件

attachments.pick() 打开系统的文件选择器，返回文件引用（ID、名称、MIME 类型和大小），不返回文件内容或路径。attachments.importFile(file) 暂存粘贴或拖入的文件。把 ID 传给 chat.send；不再需要时调用 attachments.release(ids)。

每个页面最多 20 个附件，合计 256 MiB。
源文件被修改或删除、暂存未完成、ID 无效时，发送会被阻止。
附件 ID 是临时的。要在即用里长期保存文件，请读取文件内容，用 data.assetPut 保存。

设置

const state = await soduWorkApp.settings.get();
const saved = await soduWorkApp.settings.update({
  values: { theme: 'dark', pageSize: 20 },
  expectedRevision: state.revision
});

设置按 SoduWork 账号、即用和页面来源隔离，使用系统安全存储加密保存。值可以是任意 JSON，最多 100 个键、64 KiB、8 层。update 按顶层键合并；删除某个键用 remove: ['key']。敏感的键要列在 secretKeys 里，普通读取时会隐藏它们。

设置不是单点登录，也不会自动生成设置表单。

定时任务

await soduWorkApp.automation.create({
  text: '每个工作日早上 9 点，收集昨天的订单并做汇总',
  requestId: soduWorkApp.createRequestId()
});

支持的时间：每天、每周某一天、每小时、指定日期执行一次。没写时间时默认北京时间每天 18:00，请在页面上告诉用户。
文字最多 8,000 个字符。
回执成功表示计划已保存，不表示已经执行。
SDK 不能查询、暂停或删除计划。
界面上请使用业务用语（如"每日汇报""订阅简报"），不要出现"自动化"。

即用数据

data.get、data.list、data.batch 读写即用集合里的记录；data.assetPut、data.assetGet 存取文件。写入时会检查 expectedRevision，冲突时重新读取并合并。data.apps() 列出同一账号下你能读取的即用。页面和即用的 Skill 共用同一份数据。

同事与 @ 提醒

directory.list() 返回你能看到的同事及其所在部门，每次最多 500 人。结果不包含你自己的账号，也不包含凭据、手机号或邮箱。chat.mention({ recipientUserId, text }) 会在右侧对话里打开一张卡片，由用户核对后发送通知。文字最多 500 个字符。

快速 AI

ai.generate({ input, instructions }) 把 { ok, text, model, usage, finishReason } 直接返回给页面，不经过对话、工具或历史记录，适合生成标题、打标签这类小任务。模型授权、额度和用量统计照常适用。结果不确定时不要自动重试。

iframe

要让另一个来源的 iframe 使用 SDK，在即用的顶层页面授权它的精确来源，并在 iframe 里设置父页面的来源：

// 即用顶层页面
soduWorkApp.configure({ allowedFrameOrigins: ['https://business.example'] });
// iframe 内
soduWorkApp.configure({ parentOrigin: 'https://shell.example' });

不接受通配符或 opaque origin。iframe 不能转发 mcp.connect、本机路径或 IPC。

在 SoduWork 之外

在没有 SoduWork 即用窗口的普通浏览器里，调用会以"未连接"失败。SDK 不注册自定义 URL 协议。

编辑此页

能力​

上下文​

发送到右侧对话​

附件​

设置​

定时任务​

即用数据​

同事与 @ 提醒​

快速 AI​

iframe​

在 SoduWork 之外​

能力

上下文