消息与操作结果 API

@ambleloft/extension-sdk/messages-preview：本地业务消息、并发更新与可追踪的消息操作。

API 参考

按章节查看契约、签名、字段与示例；未注明的默认值不作推断。

本页内容

01LocalMessageInput

预览能力 · SDK 0.1.0-alpha.9

publish 的输入。expiresAt 使用 Unix 毫秒，非负安全整数或 null。actions 最多两个，绑定同扩展 page 操作。

Input signature

type LocalizedText = string | { key: string; args?: Record<string, string | number | boolean> };
interface LocalMessageInput {
  eventKey: string; title: LocalizedText; body: LocalizedText;
  category: 'notice' | 'actionRequired';
  severity?: 'info' | 'warning' | 'error';
  businessType?: string | null;
  expiresAt?: number | null;
  actions?: { id: string; label: LocalizedText; commandId: string;
    arguments?: Record<string, unknown> }[];
}

02LocalMessages 方法

预览能力 · SDK 0.1.0-alpha.9

所有方法作用于当前扩展的本地消息。不存在读取所有用户消息或获取账号 token 的接口。getMessages(context) 本身同步返回 API。 getMessages 检查完整七方法，任一缺失即抛出 UNSUPPORTED；探测不代表授权，也不绕过用户偏好。

字段 / API	说明
publish(input): Promise<PublishResult>	发布或返回 duplicate / dismissed / rejected。
getByEventKey(eventKey): Promise<LocalMessage\|null>	按稳定业务键查找。
update(id,patch,expectedRevision): Promise<LocalMessage\|null>	按修订更新；不存在时可返回 null。
withdraw(id,expectedRevision): Promise<LocalMessage\|null>	按修订撤回。
getPreferences(): Promise<MessagePreferences>	返回 {receive:boolean, muted:boolean}。
listActionInvocations(): Promise<MessageActionInvocation[]>	仅含 dispatching、accepted、unknown 的动作，不是完整历史。
reportActionResult(input): Promise<{invocation,message}>	报告结果；message 为 LocalMessage 或 null。

03发布结果与消息状态

预览能力 · SDK 0.1.0-alpha.9

LocalMessage 包含 id、eventKey、title、body、category、severity、businessType、actions、expiresAt、revision、receivedAt、updatedAt。没有 readAt、dismissedAt、用户身份或凭据字段。

Result and state signatures

type PublishResult =
  | { status: 'published'; id: string; revision: number; remind: boolean }
  | { status: 'duplicate' | 'dismissed'; id: string }
  | { status: 'rejected' };
// Additional LocalMessage state fields:
// validity: 'active' | 'expired' | 'withdrawn'
// businessState: 'pending' | 'resolved' | null

LocalMessagePatch 可选更新 title、body、severity、actions、expiresAt、businessState、validity。不能通过 patch 改 eventKey 或 category。MessageActionInvocation 包含 id、messageId、actionId、operationId、revision、state、可选 remoteTaskId、createdAt、updatedAt。记录还包含 effect: 'read' | 'write'。记录 id 在报告参数中为 invocationId；handler 普通成功不自动代表 completed。

Invocation state values

type InvocationState = 'prepared' | 'dispatching' | 'accepted'
  | 'completed' | 'failed' | 'unknown' | 'notExecuted';

05ActionResultReport

预览能力 · SDK 0.1.0-alpha.9

两种 revision 分别属于执行记录和消息。reportId 需要稳定且描述同一报告；相同 ID 不可提交不同内容。

Report signature

interface ActionResultReport {
  invocationId: string;
  reportId: string;
  expectedRevision: number;
  outcome: 'accepted' | 'completed' | 'failed' | 'unknown';
  remoteTaskId?: string;
  messageUpdate?: { patch: LocalMessagePatch; expectedRevision: number };
}

按教程完成消息操作

SDK / CLI 0.1.0-alpha.9 · 接口基线兼容性与预览说明 · 案例源码

消息与操作结果 API

01LocalMessageInput

02LocalMessages 方法

03发布结果与消息状态

04Patch 与执行记录

05ActionResultReport