@aalis/schema-message 0.9.1 → 0.11.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type { TextRef } from '@aalis/schema-i18n';
 /**
  * OpenAI/DeepSeek chat completions 中 assistant 消息携带的工具调用载荷。
  * 与 Message 同源同生命周期，故所属本包。
@@ -14,7 +15,8 @@ export interface ToolCall {
  * 内容时间线分段（按到达顺序记录助手输出的真实结构）。
  * - text：正常对话文本
  * - reasoning_text：思考/推理文本（部分模型如 DeepSeek-R1、Ollama thinking 会产出）
- * - tool_call：工具调用片段（startTime/endTime 用于时长展示）
+ * - tool_call：工具调用片段（startTime/endTime 用于时长展示；callId 同这次调用的 ToolCallContext.callId，
+ *   历史里的工具卡据它与实时推送对上，参数没解析成、没有执行的调用没有）
  *
  * 该数组若存在则为渲染顺序的真相；同时 message.content / reasoningContent
  * 仍保留为派生镜像，供 LLM API 与历史压缩等纯文本消费者使用。
@@ -32,6 +34,7 @@ export type ContentSegment = {
     result?: string;
     startTime?: number;
     endTime?: number;
+    callId?: string;
 };
 /**
  * 标准 LLM role（OpenAI / DeepSeek / Ollama 等 chat 协议直接接受的四种）。
@@ -59,11 +62,13 @@ export interface Message {
      * - 让所有 role 共用同一个子类入口，避免 system.name / notice.metadata.noticeType / assistant.metadata.kind 三套互不相通的"伪子分类"。
      * - 统一过滤/渲染判断：`m.kind === 'event-marker'` 这种写法跨 role 通用。
      *
-     * 约定的语义类（详见 `WellKnownKinds` / `CONTROL_KINDS`）：
+     * 约定的语义类（详见 `WellKnownKinds` / `CONTROL_KINDS` / `DIRECTIVE_KINDS`）：
      * - `'event-marker'`              ：system 控制类标记（如压缩分隔条），不应进入 LLM 上下文。
-     * - `'cross-session-delegation'`  ：notice 子类——来自另一会话的 agent 委派任务。
+     * - `'cross-session-delegation'`  ：notice 子类——系统代发的任务指令（triggerType 为 proactive，如 workflow 的 agent 节点）。
+     * - `'host-notice'`               ：notice 子类——宿主撰写的事件通知（入站消息带 hostNotice）。
      * - `'outbound-image'`            ：assistant 子类——agent 已发出的图片。
-     * - notice 的平台事件类型         ：`'poke' | 'group_recall' | 'group_increase' | ...`（取自 OneBot 等适配器）。
+     * - 平台事件类型                 ：`'poke' | 'group_recall' | 'group_increase' | ...`（取自 OneBot 等适配器）。平台通知
+     *   落成 notice；转成入站的（如戳一戳、群文件上传）仍是 user，kind 取 {@link IncomingMessage}.noticeType。
      *
      * 第三方插件可定义自己的 kind 字符串，但请避开 `WellKnownKinds` 中已有的语义。
      */
@@ -91,7 +96,10 @@ export interface Message {
 export interface MessageAttachment {
     /** 媒介类型 */
     kind: 'image' | 'audio' | 'video' | 'file';
-    /** 内容：base64 data URL / http(s) URL / file:// URI；下游决定如何解析 */
+    /**
+     * 内容：base64 data URL / http(s) URL / file:// URI / storage URI（`<根>:/路径`，如 `data:/images/…`，经 storage 服务读取；
+     * 与 data URL 以有无 `;base64,` 区分）；下游决定如何解析
+     */
     data: string;
     /** MIME 类型，尽量提供以便分发 */
     mimeType?: string;
@@ -104,20 +112,31 @@ export interface MessageAttachment {
     /** 时长秒（仅音视频，如已知） */
     durationSec?: number;
     /**
-     * 出站附件：文本描述（vision/asr 结果）。由生产者（如 send_attachment）填充，
-     * 供全局出站归档写入 `[类型: desc | ref:xxx]` 标记，让 memory_recall 能命中。
+     * 出站附件：文本描述（识图、转写的结果），生产者已有时填上。出站记进会话历史时写进占位符的描述位
+     * （`[类型: desc | ref:xxx]`，见 api-message-archive 的 recordOutbound），memory_recall 据此命中
      */
     description?: string;
     /**
-     * 出站附件：稳定引用标识（http(s) url / storage uri）。用于出站归档与历史回放；
-     * 缺省时全局归档回退用 data。与平台落盘后改写的 data 解耦，避免归档到临时/不可访问路径。
+     * 稳定的地址（网址或存储地址）。出站：记进会话历史时用它，没有时取 data 里的地址（见 api-message-archive 的
+     * outboundAddress），与平台落盘后改写的 data 无关。入站：预处理器把附件落了盘或换掉 data 时写的地址（媒体识别落盘上传的
+     * 图片、文件读取换成文件引用前的地址），存档的附件清单在 data 不是地址时按它记；适配器不填
      */
     ref?: string;
-    /**
-     * 出站附件：跳过全局归档。用于 history_ref 重发等场景（同一媒体已在档，
-     * 避免向量库膨胀与重复入档）。缺省 false。
-     */
-    skipArchive?: boolean;
+}
+/** 一轮的事实（见 {@link IncomingMessage.fromTurn}） */
+export interface FromTurn {
+    platform: string;
+    /** 物理发言者（同 {@link IncomingMessage.userId}，没有时不设，如定时任务那一轮） */
+    userId?: string;
+    /** 参与者：那次调用的参与者（按 api-authority 的 originTurnOf 算，批过的是批的人） */
+    participants: readonly {
+        platform: string;
+        userId: string;
+    }[];
+    /** 那一轮的来源（同 {@link IncomingMessage.source}，人亲手发来的没有） */
+    source?: string;
+    /** 那一轮自己的起它的那一轮 */
+    fromTurn?: FromTurn;
 }
 export interface IncomingMessage {
     content: string;
@@ -128,7 +147,7 @@ export interface IncomingMessage {
     nickname?: string;
     /**
      * 平台侧消息 ID（如 OneBot 的 message_id）。
-     * 由适配器填充；归档插件会写入 metadata.messageId，供"引用回复"反查归档原文以保留图片描述等富信息。
+     * 由适配器填充；归档插件写进元数据的 {@link WellKnownMetadataKeys}.MessageId，供"引用回复"反查归档原文以保留图片描述等富信息。
      */
     messageId?: string;
     /**
@@ -142,17 +161,36 @@ export interface IncomingMessage {
      * 由 plugin-media 写入。
      */
     _attachmentDescriptions?: Array<string | undefined>;
-    /** 会话类型：群聊、私聊、频道等 */
-    sessionType?: 'group' | 'private' | 'channel';
     /**
-     * 系统侧注入者的来源标识（如 'idle-trigger'、'scheduler'、'workflow:<id>'、'proactive:from:<sid>'）。
+     * 平台类型名：适配器在 PlatformAdapter.sessionTypes 里声明的类型之一（如 OneBot 的 group、private、channel）。会话管理在
+     * IM 房间建档时按它记下聊天窗口；判是不是多方读会话记录的 originChat.multiParty（子会话取根会话的），不看消息上的它。
+     * 不带时，平台声明了多方类型的按其中第一个、多方，只声明了一对一类型的按第一个，没声明的按 private、一对一
+     * （api-platform 的 resolveSessionType）
+     */
+    sessionType?: string;
+    /** 收到这条消息的机器人账号（平台给出时由适配器填，如 OneBot 的 self_id） */
+    selfId?: string;
+    /**
+     * 系统侧注入者的来源标识（如 'idle-trigger'、'scheduler'、'workflow:<id>'）。
      * 平台适配器投递真人消息**不设置**此字段：带 source 的消息被视为内部注入——不经触发策略、
-     * 不过回复后冷却（禁言与限速照常生效）。同时用于并发隔离：同一 session 不同来源互不打断。
+     * 不过回复后冷却（禁言与限速照常生效），也不过指令解析（声明了 {@link IncomingMessage.ownerApproved} 的除外），
+     * 不进长期记忆（向量记忆，档案的旁观计数与事实提取）。
+     * 带来源的输入各自成一轮，不与别的输入叠加；注入方的来源应当标识发送方。
      */
     source?: string;
+    /**
+     * 到达序号：网关在入站相位之前给每条入站消息打的，这次运行内递增（网关重载后从头计）。只用于日志关联（见
+     * {@link arrivalTag}），不落库、不进模型；没经网关进来的没有
+     */
+    arrival?: number;
+    /**
+     * 注入方的声明：这段文字在建立时经 owner 过目过原文（owner 自己写下，或每次由 owner 审批），算作 owner 亲手写的。
+     * 注入方必须同时设 source；只给经 owner 过目原文的文字设，第一方的设置方在仓内守卫里登记
+     */
+    ownerApproved?: boolean;
     /** 群名称（仅群聊时可用） */
     groupName?: string;
-    /** 群组 ID（直接字段，无需从 sessionId 解析） */
+    /** 多方聊天窗口的 id，由适配器填（如 OneBot 的群号，频道为 `<guild>:<channel>`） */
     groupId?: string;
     /**
      * 群聊中发送者在群内的角色：owner=群主, admin=管理员, member=普通成员。
@@ -175,104 +213,257 @@ export interface IncomingMessage {
         userId?: string;
         nickname?: string;
     };
-    /** 通知子类型（如 poke、group_upload 等非消息事件） */
+    /**
+     * 随这条消息转发来的聊天记录（如 OneBot 的合并转发），按在正文里出现的先后，不是发言人自己写的话。适配器在 content 里它所在的
+     * 位置写 {@link forwardPlaceholder}(id)（转发 id 不含双引号；用户手打的同样写法先转义，同 {@link AT_SELF_PATTERN}），给模型的
+     * 展开写在 content、给界面的事实写在 facts；适配器必须在 content 里写占位，漏写的展开不进归档文本。归档文本
+     * （{@link buildIncomingContent}）把占位换回展开，模型看到的与展开写在正文里一样；发言人的话（content、存档的 SpokenContent）、
+     * 点名、禁言关键词与 @ 的账号只看 content；存档另记成 {@link WellKnownMetadataKeys}.Forwards。别的平台有转发照这条接：渲染成
+     * 占位、展开放这里、转义手打的写法；存档、会话服务、WebUI、点名与画像都不认平台
+     */
+    forwards?: ForwardedChat[];
+    /** 通知子类型（如 poke、group_upload 等非消息事件）；存档记成消息的 kind */
     noticeType?: string;
+    /** 通知动作是否指向机器人；poke 为 false 时按未点名互动判断，省略沿用戳机器人的语义。 */
+    noticeTargetIsSelf?: boolean;
+    /**
+     * 平台事件合成或转成的入站（如好友申请、入群邀请、戳一戳、群文件上传）给人看的那句（文字对象）：content 是写给模型的
+     * （有的带处理办法与工具用法），界面显示这一句，按读者的语言渲染。适配器写，真人发言不设；不进模型的上下文，也不参与触发与
+     * 回复的判定，存档按 {@link WellKnownMetadataKeys}.Text 记下
+     */
+    text?: TextRef;
     /**
      * 触发类型（下游插件可据此区分主发言者语义）。真人消息由 inbound:trigger 相位生效的触发插件写入
      * （immediate / interval），平台适配器不设置；内部注入由注入方自带（idle、proactive）。flow 相位对
-     * immediate 不查回复后冷却与限速，所以不经触发插件改写时（作用域外、没装触发插件），入站消息上预设的
+     * immediate 不查回复后冷却与限速，所以不经触发插件改写时（生效范围外、没装触发插件），入站消息上预设的
      * immediate 会原样生效。
      * - 'direct'    私聊或单一用户直连（默认语义：userId 是主发言者）
      * - 'immediate' 群聊中被 @/名字主动触发（userId 是主发言者）
-     * - 'interval'  群聊中因消息频率/活跃度被动触发（无明确主发言者，userId 仅为最后一条消息发送者）
-     * - 'idle'      空闲自动触发（无 userId / 无主发言者）
-     * - 'proactive' 由另一会话的 agent 通过工具发起跨会话委派（content 是任务描述而非用户消息）
+     * - 'interval'  群聊中没点名、因消息频率/活跃度被挑中（提示词按无明确主发言者写；授权身份照旧是发言者）
+     * - 'idle'      空闲自动触发（无 userId / 无主发言者）；存档不落档，agent 以 system 指令块交给模型
+     * - 'proactive' 系统代发给 agent 的任务指令，如 workflow 的 agent 节点（content 是任务描述而非用户消息）
      * 未设置时下游插件按 'direct' 兼容处理。
      */
     triggerType?: 'direct' | 'immediate' | 'interval' | 'idle' | 'proactive';
     /**
      * 代理身份（与 platform/userId 解耦）：当本条消息并非由人类直接发送，而是由 scheduler、
-     * idle-trigger、proactive 委派等系统侧触发器投递时，记录"AI 应代谁执行"。
+     * idle-trigger、workflow 等系统侧触发器投递时，记录"AI 应代谁执行"。
      *
      * 与 platform/userId 的区别：
      * - platform/userId 表示消息的物理来源（路由+发言者标识），写归档、做用户档案/关系；
-     * - actor 表示授权身份，agent 构造 ToolCallContext 时优先使用 actor，
+     * - actor 表示授权身份，agent 算这一轮的参与者时优先使用 actor（api-authority 的 originTurnOf），
      *   从而让 authority 守卫按 actor 的 (platform, userId) 查权限等级。
      *
      * 触发器（如 scheduler）应在创建任务时 snapshot 调用者身份，触发时回填此字段；
      * 不能由 LLM/AI 在工具入参中自由指定，避免提权。
      *
-     * AI 自发回合（无主发言者，如群聊 'interval' 触发）没有可代之人：触发器应回填
-     * {@link selfInitiatedActor}（userId 为空串 = 无主体），authority 按默认等级裁决、
-     * 永不视为 owner。'idle' 合成消息本就不带 userId，天然无主体，无需回填。
+     * 没有人的注入（不延续调用的宿主通知等）没有可代之人：注入方回填 {@link selfInitiatedActor}（userId 为空串 = 无主体），
+     * authority 按默认等级裁决、永不视为 owner。'idle' 合成消息本就不带 userId，天然无主体，无需回填。
+     * 带 {@link IncomingMessage.fromTurn} 的消息不设此字段，授权身份取它的参与者。
      */
     actor?: {
         platform: string;
         userId: string;
     };
     /**
-     * 委派链深度：跨会话委派（delegate_to_session）注入目标会话时填的「这是第几跳」，
-     * 从 1 起。防雪崩的深度随消息走，不按会话计时——由委派消息驱动的那一个回合内禁止
-     * 再委派，回合结束即解除；真人消息不带此字段，其回合不受影响。缺省视为 0。
+     * 起它的那一轮：续做（如后台任务的结束通知）与子任务（任务消息与追问）的消息带着起它的那次调用所在那一轮的事实，权限服务
+     * 按那一轮判续做与子任务这一轮的类别与主体，这一轮的参与者取它的参与者（agent 经 api-authority 的 originTurnOf
+     * 拼工具调用上下文）。只由登记的注入方填（`test/architecture/host-notice-identity.test.ts`），只在那次调用在入站回合里时填，
+     * 不由模型给；不进归档与提示词钩子
+     */
+    fromTurn?: FromTurn;
+    /**
+     * 宿主撰写的事件通知（不是任何人的发言）。带这个字段的消息：
+     * - 注入方必须同时设 `source`；不设 userId、nickname、sessionType、triggerType；
+     * - 身份：不延续某次调用的通知的 actor 用 {@link selfInitiatedActor}；延续某次工具调用的（如后台任务结束通知）不设
+     *   actor，改带 {@link IncomingMessage.fromTurn}（那次调用所在那一轮），platform 同那一轮；
+     * - agent 渲染为 system 通知，归档为 role 'notice'、kind {@link WellKnownKinds}.HostNotice；
+     * - 不进向量记忆、抽取与记忆扩窗。
+     *
+     * `kind` 是通知的子类（如 'paper-task'），`id` 是注入方生成的通知标识（日志与账本对位用，存档记下；含义随 kind，
+     * 如后台任务结束通知的是任务 id）。
+     * `untrusted` 是注入方已用 wrapUntrustedContent 包好的不可信段：只在当轮渲染时接在正文之后，
+     * 不归档、不进任何存储。宿主撰写的行一律放在 content 里。
      */
-    proactiveDepth?: number;
+    hostNotice?: {
+        kind: string;
+        id?: string;
+        untrusted?: string;
+        /**
+         * 仅转述状态：保留人设、提供本轮结果，不续跑历史工具链，不提供或执行工具。
+         * 误调用工具、空回复或遗漏正文链接与格式纠正共用重试预算（至少一次）；用尽才由注入方兜底。
+         * 客户端只收到校验后的正文，不流出生成中或失败轮的原文。
+         * 模型错误只记日志并报告 agent:turn:after(error)，
+         * 不向会话发通用错误提示；注入方负责根据回合结果派发固定正文或保留待发。
+         * 需要 Agent 后续行动的通知不设置此项。
+         */
+        reportOnly?: boolean;
+        /**
+         * 回复这条通知时引用哪条消息：平台消息 id，取自起那次调用的入站消息（ToolCallContext.inbound.messageId）。
+         * plugin-agent 回复时把它带进出站消息的 {@link OutgoingMessage.replyTo}；入站消息没有平台消息 id 的不设
+         */
+        replyTo?: string;
+        /**
+         * 给界面的事实：扁平的键值，键由定义这个 kind 的契约约定（如 api-tools 的后台任务结束通知）。界面据此把通知画成状态，
+         * 写给模型的 content 不给人看；不进模型的上下文，存档按 {@link WellKnownMetadataKeys}.HostNoticeFacts 记下
+         */
+        facts?: Record<string, string | number>;
+        /**
+         * 给人看的那句话（文字对象）：content 是写给模型的，界面显示这一句，按读者的语言渲染。不进模型的上下文，
+         * 存档按 {@link WellKnownMetadataKeys}.Text 记下
+         */
+        text?: TextRef;
+    };
 }
 /**
- * AI 自发回合的授权身份：无主体。
- *
- * 'interval' 触发复用的是恰好撞上频率阈值的那条真人消息，若不回填 actor，授权轴会经
- * `actor ?? {platform, userId}` 回退到「最后发言者」——绝大多数回合按陌生人 0 级判权
- * （自发回合工具全挂），而 owner 恰好最后发言时整轮（含群内任何提示注入）以 owner 等级
- * 执行。契约（triggerType 注释）与 prompt 侧特判都把 interval 当无主发言者，授权轴应一致。
+ * 没有人的注入的授权身份：无主体。只给没有人的注入（不延续调用的宿主通知等）用；人发来的话（含群里没点名、被频率触发挑中的）
+ * 按说话的人算，不用它。
  *
  * userId 取空串而非缺省：`actor?.userId ?? userId` 回退链遇空串不回退（?? 只认 null/undefined），
- * 由此派生的定时任务/委派/子任务保持匿名，不会漂回物理发言者；authority 的等级查表以空
+ * 由此派生的定时任务/子任务保持匿名，不会漂回物理发言者；authority 的等级查表以空
  * userId 为无键 → 默认等级，owner 判定永不命中空串。
  */
 export declare function selfInitiatedActor(platform: string): {
     platform: string;
     userId: string;
 };
+/**
+ * 一轮的各条输入是不是同一位物理发言者说的（平台与账号都相同）：会话语义的发言者（工具调用上下文的 userId、人设的说话人
+ * 事实）只在这时有
+ */
+export declare function oneSpeaker(inputs: readonly Pick<IncomingMessage, 'platform' | 'userId'>[]): boolean;
+/**
+ * 这条输入点名了她：真人输入（不带 source）的触发类型为 direct 或 immediate，没有触发类型的（没经触发判定）按 direct 算。带来源的
+ * 注入（定时任务、编排、各种通知）不是谁在跟她说话，不算点名。焦点指引、排着开的一轮的说明、档案与关系子图都按它判
+ */
+export declare function wasAddressed({ source, triggerType, }: Pick<IncomingMessage, 'source' | 'triggerType'>): boolean;
+/**
+ * 对她的 @：适配器按机器人账号写下的 `<at self …>…</at>` 标记，读的一方只认这个结构化标记，不按文字猜。文法与读它的几处见
+ * docs/concepts/message-llm-pipeline.md
+ */
+export declare const AT_SELF_PATTERN: RegExp;
+/**
+ * 一段文字 @ 了哪些账号：适配器写下的 `<at id="…">` 与 `<at self id="…">` 标记里的账号，按出现先后去重；@全体不是账号，
+ * 不算：入站写作 `<at>all</at>`（不带 id），她的回复里写作 `<at id="all">`（出站按这个发成 @全体）。文法见
+ * {@link AT_SELF_PATTERN}。存档按它从发言人自己写的话里抽，记成元数据的 {@link WellKnownMetadataKeys}.Mentions
+ */
+export declare function extractMentions(text: string): string[];
+/**
+ * 传输端确认已接受消息，不代表收件人已阅读；失败也 resolve，避免无人等待时产生拒绝。
+ * 成功分支的 messageIds 是正文送达时平台给出的消息 id（分条发出的各一个，按发送顺序；与入站 replyTo.messageId 同一写法，
+ * 引用回复据此认出被引用的是哪一条），平台不给时没有。
+ * 失败分支的 error 是给人看的原因，可以是文字对象（@aalis/schema-i18n 的 TextRef，按读者语言显示）；交给模型与写日志的
+ * 一方取 toSource。unconfirmed 表示有请求已经发出、只是没等到平台确认（如 OneBot 发消息或上传文件超时、等回执时断线），那部分
+ * 可能已经送达：发起方不得自动重发，也不得劝模型重发。没有这个标记的失败才是确定没送达。
+ * sentPieces 是逐条发出（分条的正文与各自成一条的附件）停在中途时已经发出的条数：前 sentPieces 条平台已经收下，之后的没收下
+ * 或结果未知，补发只补后面的；一条都没发出时没有。
+ */
+export type OutboundDeliveryResult = {
+    ok: true;
+    messageIds?: string[];
+} | {
+    ok: false;
+    error: string | TextRef;
+    unconfirmed?: true;
+    sentPieces?: number;
+};
+/**
+ * 发起方等待传输确认的上限。适配器自身的发送可能更久（如 OneBot 先下载附件落盘、再逐条发出，下载与每条的回执各等 30 秒），
+ * 超过上限时发起方应报「未确认、请勿重发」而不是失败；上限只为不带回合中止信号的调用方
+ * （mcp-server、workflow）不至于一等两三分钟。
+ */
+export declare const DELIVERY_WAIT_MS = 90000;
+/**
+ * 日志行里一条输入的到达序号，接在动作之后：` #<序号>`（带前导空格），没经网关进来的为空串。日志行据此串起同一条输入，
+ * 不记正文与昵称
+ */
+export declare function arrivalTag({ arrival }: Pick<IncomingMessage, 'arrival'>): string;
+/**
+ * 等 {@link OutgoingMessage.delivery} 结算；signal 中止（回合被停下、插件停机）或到 timeoutMs
+ * （缺省 {@link DELIVERY_WAIT_MS}）时不再等，返回 undefined。适配器的发送不随之取消，所以 undefined 只能当
+ * 「未确认」，不能当「未发送」。
+ */
+export declare function awaitDelivery<T>(delivery: Promise<T>, signal?: AbortSignal, timeoutMs?: number): Promise<T | undefined>;
+/** 发往平台的回复：只带要发出去的正文与附件。思考与工具时间线在存档的 Message 上，客户端经会话协议拿 */
 export interface OutgoingMessage {
     content: string;
+    /**
+     * 正文是要翻译的文字时，它的文字对象：发起方同时写 content（`toSource(text)`，按原文渲染的整句）。经网关派发时，网关按
+     * 这条消息所在会话的语言把它渲染进 content（i18n 缺席或渲染抛错时按原文）；按连接显示的出口（会话协议的时间线、WebUI
+     * 会话的历史）另按各自的读者渲染它，其余照旧读 content
+     */
+    text?: TextRef;
     sessionId: string;
     platform?: string;
-    reasoningContent?: string;
-    /** 助手输出的有序时间线（与 Message.segments 含义一致），存在时为 webui 等消费者顺序渲染的依据 */
-    segments?: ContentSegment[];
+    /**
+     * 仅进程内：目标适配器在出站监听器中同步认领并填写，发起方 await emit 后可等待它。
+     * 不存在表示没有适配器提供确认，不能当作发送成功。旁观/镜像客户端不得认领其他平台的消息。
+     * 所有发送分支都须结算；不序列化、不持久化，也不把事件广播完成当成投递完成。
+     */
+    delivery?: Promise<OutboundDeliveryResult>;
+    /** 宿主通知的最终转述或宿主正文兜底；用于关联通知派发，不给回合中的工具消息附带此标记。 */
+    hostNotice?: {
+        kind: string;
+        id?: string;
+    };
+    /**
+     * 引用回复：被引用消息的平台消息 id。支持引用的适配器把引用加在这条消息的第一条分条前，不支持的忽略。
+     * 现在只有回复宿主通知时带（IncomingMessage.hostNotice.replyTo）
+     */
+    replyTo?: string;
     /**
      * 助手要附带发送的多模态附件（图片/音频/视频/文件）。
      * 适配器（OneBot / WebUI 等）应优先发结构化 attachments，把远程 URL 主动下载为本地文件后用 file:// 形式发送。
-     * 若 attachments 为空但 content 内含 `<image url="...">` 标记，则由适配器解析嵌入式发图（旧路径，仍兼容）。
      */
     attachments?: MessageAttachment[];
-    /** 消息来源：agent = AI 回复（可分条延迟发送），其他来源默认立即整条发送 */
+    /**
+     * 正文含平台标记、要解析：有标记语法的适配器（如 OneBot 的 `<at>`、`<image|record|video url>`、`<reply>`）把它们解析成
+     * @、媒体与引用，并可分条延迟发送；不设的正文按纯文字原样整条发出，不解析、不分条。要发平台标记的出站自己设它；
+     * attachments 不受它影响。媒体标记的地址不是网址的（本机路径、存储地址、data URI 等），适配器不得自己读取，也不交给实现端，
+     * 一律去掉并报投递失败：存储里的媒体由 plugin-image-sender 在派发前过媒体判据转成附件，留在正文里的存储地址是没转成的（过
+     * 不了判据、读不出、不是对应媒体，或没装它）。正文里的媒体标记怎么发，见 docs/services/media.md
+     */
+    markup?: boolean;
+    /** 消息来源：agent = AI 发出的（回复与经工具发的附件），system = 宿主提示，command = 指令回复 */
     source?: 'agent' | 'system' | 'command';
-    /** 本条回复的 LLM 元数据（供 webui 实时展示，不需持久化）。 */
+    /** 由工具调用发出的消息：那次调用的 id（ToolCallContext.callId），会话的客户端据此把消息挂到对应的工具卡上 */
+    callId?: string;
+    /**
+     * 这一轮发出的消息（她的回复、[错误] 等提示与经工具发出的）：这一轮的 id。适配器记回复的投递失败时带上它，回看历史时据此标出
+     * 这一轮的回复没发出；出站记进会话历史的各条同样记下（api-message-archive 的 recordOutbound）
+     */
+    turnId?: string;
+    /**
+     * 本条回复的 LLM 元数据（agent 存档时同一份写进这条 assistant 消息元数据的 {@link WellKnownMetadataKeys}.ModelInfo），
+     * 只在进程内；会话服务取其中的模型与这一轮的 token 标在实时推送的回复上，与历史里还原的一致
+     */
     modelInfo?: {
         provider?: string;
         model?: string;
         promptTokens?: number;
         completionTokens?: number;
-        totalTokens?: number;
-        elapsedMs?: number;
     };
 }
 /** 流式消息片段 */
 export interface StreamChunkMessage {
     sessionId: string;
+    /** 所在回合的 id（agent 在回合开始时生成，同一轮的工具调用、用量与回合结束带同一个） */
+    turnId: string;
     platform?: string;
     contentDelta?: string;
     reasoningDelta?: string;
     /**
-     * 工具调用生成进度提示。当 LLM 正在生成 tool_call（不发文本/reasoning）时，
-     * provider 每收到一段 tool_calls delta 会通过此字段上报，让 UI 显示「正在生成工具调用」。
-     * 仅用于 UI 提示，不影响最终 tool_call segment 的下发。
+     * 工具调用的生成进度：模型生成工具调用的参数时，provider 每收到一段增量上报一次（api-llm 的 ToolCallProgress），
+     * agent 转发时带上这次调用的 callId，与之后执行它时 tool:execute 的 callId 相同，界面据此在参数生成期间就画出它的
+     * 工具卡。同一个调用的多次进度 callId 相同；只是提示，不影响最终的工具调用
      */
     toolCallProgress?: {
+        /** 这一次模型回复里的第几个工具调用 */
         index: number;
         name: string;
+        /** 已生成的参数字数 */
         charsAccumulated: number;
+        callId: string;
     };
     done?: boolean;
     /** 当工具调用次数达到上限时为 true，前端可据此提示用户继续 */
@@ -302,17 +493,33 @@ declare module '@aalis/core' {
             archivedMessage: Message;
         }];
         'outbound:message': [message: OutgoingMessage];
+        /**
+         * 送达之后的消息快照，给存档与旁观者用：content 只在文字送达时有，attachments 只包含成功的附件。认领回执的适配器在送达后对
+         * 每条消息都发，只有文字的也发，存档据此记进会话历史；送达本身就是写进会话历史的适配器（如 WebUI）不发，改为调 api-message-archive
+         * 的 recordOutbound 并等它兑现。
+         */
+        'outbound:delivered': [message: OutgoingMessage];
         'outbound:stream': [chunk: StreamChunkMessage];
     }
 }
 /**
  * 已知的 Message.kind 语义常量。第三方插件可使用新值；本表仅作为框架内的契约。
  *
- * - `EventMarker`：纯 UI/控制标记（如对话压缩分隔条）。LLM 出口与抽取均应排除。
- * - `CrossSessionDelegation`：跨会话委派——另一 agent 通过工具向本会话派发任务。
- * - `OutboundImage`：assistant 已发出的图片占位（content 为 attachment ref 标签）。
- * - `OutboundAudio`：assistant 已发出的语音占位。
- * - `OutboundVideo`：assistant 已发出的视频占位。
+ * - `EventMarker`：纯 UI/控制标记（如对话压缩分隔条、不是她回复的出站文字）。LLM 出口与抽取均应排除。
+ * - `CrossSessionDelegation`：代发任务——triggerType 为 proactive 的入站消息（如 workflow 的 agent 节点）归档时标的 kind。
+ * - `OutboundImage`：发出的图片占位（content 为 attachment ref 标签，记法见 {@link outboundMediaMessage}）。
+ * - `OutboundAudio`：发出的音频占位。
+ * - `OutboundVideo`：发出的视频占位。
+ * - `OutboundFile`：发出的文件占位（描述位是文件名）。
+ * - `HostNotice`：宿主撰写的事件通知——带 `hostNotice` 的入站消息归档时标的 kind（role 为 notice）。
+ * - `IdlePrompt`：空闲开话题的提示——triggerType 为 idle 的入站交给模型时那条指令块的 injector。它不落档，没有这个 kind 的
+ *   归档消息。
+ * - `OutboundDeliveryFailed`：平台适配器记下的投递失败（role 为 system）：她发出的消息平台没收下或结果未知，进下一轮的上下文，
+ *   让她知道刚才那条没送达。metadata 带 {@link WellKnownMetadataKeys} 的 `DeliveryError`（与投递结果同一句原因），以及那条
+ *   消息的 `TurnId`（一轮的回复）或 `CallId`（经工具发出的）；逐条发出停在中途时另带 `SentPieces`。
+ * - `TurnStopped`：agent 记下的停下标记（role 为 system）：一轮在回复之前被停下、会话历史里已有这一轮的输入或工具调用时写，
+ *   进下一轮的上下文，让她知道那一轮停下了、没说完的话没有留下；有停下的人时写是谁。metadata 带这一轮的 `TurnId`；回合记录
+ *   照旧另落事件标记，这一条不带 `TurnRecord`。
  */
 export declare const WellKnownKinds: {
     readonly EventMarker: "event-marker";
@@ -320,19 +527,159 @@ export declare const WellKnownKinds: {
     readonly OutboundImage: "outbound-image";
     readonly OutboundAudio: "outbound-audio";
     readonly OutboundVideo: "outbound-video";
+    readonly OutboundFile: "outbound-file";
+    readonly HostNotice: "host-notice";
+    readonly IdlePrompt: "idle-prompt";
+    readonly OutboundDeliveryFailed: "outbound-delivery-failed";
+    readonly TurnStopped: "turn-stopped";
 };
 export type WellKnownKind = (typeof WellKnownKinds)[keyof typeof WellKnownKinds];
 /**
- * 跨插件约定的 `Message.metadata` 键。metadata 是开放字典，本表只登记由一方写入、另一方读取的键。
+ * 发出的图片、音频、视频与文件在会话历史里的记法：kind 为 OutboundImage / OutboundAudio / OutboundVideo / OutboundFile，
+ * 正文是附件引用占位符（{@link formatAttachmentRef}）。出站的 source 是 agent 的是她发的，role 为 assistant；其余是插件发的，
+ * role 为 notice（进模型时是一条系统通知，不算她的发言）。归档方一律用它，memory_recall 与会话服务回看历史才能按同一格式命中、
+ * 还原。文件的 desc 记文件名。时间戳与 metadata 由调用方补上。
+ */
+export declare function outboundMediaMessage(kind: MessageAttachment['kind'], ref: string, { desc, source }?: {
+    desc?: string;
+    source?: OutgoingMessage['source'];
+}): Message & {
+    content: string;
+};
+/**
+ * 不是她回复的出站文字（`source` 不是 agent，如指令的回复、宿主提示）在会话历史里的记法：一条事件标记，不进模型的上下文，
+ * 正文是 `content`，元数据记文字对象（{@link WellKnownMetadataKeys} 的 `Text`，有才记），会话服务据此还原成通知。她的回复
+ * （agent 存档）与空文字不记，回 undefined。归档方一律用它；时间戳与出站的 `Source`、`TurnId`、`CallId` 由调用方补上（与
+ * {@link outboundMediaMessage} 记的附件同一条规则，见 api-message-archive 的 recordOutbound）
+ */
+export declare function outboundMarkerMessage(msg: OutgoingMessage): Message | undefined;
+/** 存档里提问带的一个附件（{@link WellKnownMetadataKeys}.Attachments 的一项） */
+export interface ArchivedAttachment {
+    kind: MessageAttachment['kind'];
+    /** 入站附件带的文件名 */
+    name?: string;
+    /** 地址：存储地址（`<根>:/路径`）或网址；入站附件的 data 不是地址（内联数据、本机路径、预处理器的私有引用）、预处理器也没在它的 ref 上写地址的没有 */
+    ref?: string;
+}
+/** 一段转发给界面的事实（{@link ForwardedChat.facts}）：适配器展开成功时有 */
+export interface ForwardFacts {
+    /** 顶层的条数 */
+    count: number;
+    /** 参与的人，最多前 8 个（写法由适配器定，如 OneBot 的「昵称(账号)」） */
+    participants: string[];
+    /** 没列出的人数；都列出了时没有 */
+    unlisted?: number;
+    /** 转发的文字：有摘要时是摘要，没有时是原文（可能截断） */
+    text: string;
+    /** 原文被截断时为 true */
+    cutOff?: true;
+}
+/** 随入站消息转发来的一段聊天记录（{@link IncomingMessage.forwards} 的一项） */
+export interface ForwardedChat {
+    /** 平台给的转发 id：正文里它的占位（{@link forwardPlaceholder}）按它对位 */
+    id: string;
+    /** 给模型看的展开，归档文本把它换进占位的位置（OneBot 的信封；拉不到时写原因；适配器关掉展开时就是占位本身） */
+    content: string;
+    /** 给界面的事实；拉不到内容、展开出错与关掉展开时没有 */
+    facts?: ForwardFacts;
+}
+/** 存档记下的一段转发（{@link WellKnownMetadataKeys}.Forwards 的一项）：展开已按原位置拼进归档正文，不另存 */
+export type ArchivedForward = Omit<ForwardedChat, 'content'>;
+/**
+ * 跨插件约定的 `Message.metadata` 键。metadata 是开放字典，本表登记由一方写入、另一方读取的键：写方与读方都引用这里的
+ * 常量，第三方的 agent、存档与适配器照着写，读历史与记忆的一方（会话服务回看历史、向量记忆、用户档案与关系等）才还原得出
+ * 说话人、群、文件、回复的模型与 token、工具卡的归组。
  *
  * - `VisibleContent`：assistant 消息的可见正文（字符串）。回复经结构化输出（persona 的 outputFormat）
- *   时，`content` 存整串 JSON 信封（保持历史 few-shot 的格式），用户实际看到的是其中的回复字段。
+ *   时，`content` 存整串 JSON 信封（存档原文），用户实际看到的是其中的回复字段；agent 交给模型的历史取这个键。
  *   agent 落库时把解码后的正文写进这个键，只在它与 `content` 不同时写入；缺省即 `content` 本身就是
  *   可见正文。检索、摘要等按语义消费历史的一方应优先读它，读不到再退回 `content`。
+ * - `SpokenContent`：提问里发言人自己写的话（字符串，可以是空串），即入站消息的 `content`。存档的 `content` 是给模型看的
+ *   归档文本（{@link buildIncomingContent}：发送者前缀、转发的展开、引用与附件描述），存档只在两者不同时写这个键；缺省即
+ *   `content`。合并转发的展开不在里面，只有它的占位。会话服务据此给出提问条目的正文，用户档案据此核对原话。
+ * - `Attachments`：提问带的附件清单（{@link ArchivedAttachment} 的数组，按入站顺序），存档写；会话服务据此把文件还原成卡片、
+ *   图片等按地址显示。没有附件时不写。
+ * - `Forwards`：提问随附的转发（{@link ArchivedForward} 的数组：入站消息 forwards 的 id 与事实，不存展开），存档在有时写；
+ *   会话服务据此把转发画成单独的块。
+ * - `SenderLabel`：归档文本发送者前缀里的标签（字符串，{@link getSenderLabel} 的写法），存档只在加了前缀时写。把归档文本重排给
+ *   模型或界面看的一方（向量记忆的召回片段、撤回通知的摘录、引用反查）按它用 {@link stripSenderPrefix} 去掉这一层，没有这个键
+ *   的不去。
+ * - `Mentions`：提问里发言人自己写的话 @ 了哪些账号（字符串数组，{@link extractMentions} 从入站消息的 `content` 抽，引用、
+ *   附件描述与转发里的不算），存档在有时写；向量记忆据此给被 @ 的人加权，关系图的提取据此认被 @ 的人。
+ * - `Platform`、`UserId`、`Nickname`：说话人的平台、用户 id 与昵称（字符串）。存档写入站消息的；agent 给她自己的回复写
+ *   这一轮的平台与她在那里的账号、昵称。会话服务据此标出说话人与是不是 owner，向量记忆、用户档案与关系等也读。
+ * - `GroupId`、`GroupName`、`SessionType`：说话所在的群号、群名与会话类型（字符串，即入站消息的 `groupId`、`groupName`、
+ *   `sessionType`）。存档写入站消息的，agent 给她自己的回复写这一轮的；向量记忆与最近消息据此写出说话的位置，只用于显示：
+ *   判是不是多方读会话记录的 originChat.multiParty（子会话取根会话的）。
+ * - `MessageId`：平台侧的消息 id（字符串，即入站消息的 `messageId`），存档写；存档按它反查被引用的原文，关系插件据此把
+ *   引用与回复对回消息。
+ * - `Source`：这条记录的来源（字符串）：入站消息是它的 `source`（内部注入的来源，真人发言没有）；出站消息记进历史的各条
+ *   （文字的事件标记与发出的附件）是出站的 `source`（如指令回复的 command）；插件自己写的其余记录（投递失败）写插件的名字。
+ *   会话服务据此标出提问是不是内部注入的、认出指令的回复。
+ * - `HostNoticeKind`、`HostNoticeId`、`HostNoticeFacts`：宿主通知的子类（`hostNotice.kind`）、id（`hostNotice.id`）与给界面的
+ *   事实（`hostNotice.facts`），存档写；会话服务据此给出通知条目的种类、id 与事实。
+ * - `TurnId`：所在回合的 id（字符串）。进了一轮的输入由存档按 agent 归档时交来的回合记下，agent 写在这一轮落库的回复、工具
+ *   结果与停下标记上，平台适配器写在一轮回复的投递失败记录上，出站记进历史的各条由写方按出站消息的 turnId 记下（有才记）；
+ *   会话服务据此把存档归回回合、标出哪一轮的回复没发出，连对话回滚据此只删这一轮的消息。
+ * - `TurnEntry`：输入怎么进的这一轮（字符串）：`opened` 是开轮的，`joined` 是插进在跑的一轮的。与 `TurnId` 一起由存档记下。
+ * - `TriggerType`：入站消息的触发类型（字符串，即 {@link IncomingMessage}.triggerType），存档写；会话服务据此标出被点名与插话。
+ * - `TurnRecord`：一轮的结局与来源（{@link TurnRecord}）。agent 记在这一轮最后落库的那条回复上，没有落库回复的一轮另落一条只带
+ *   `TurnId` 与它的事件标记（role system、kind EventMarker、正文为空，属于 {@link CONTROL_KINDS}）；会话服务据此在历史里还原
+ *   这一轮的结局。
+ * - `CallId`：工具调用的 id（字符串，即 `ToolCallContext.callId`）。agent 写在工具结果上，平台适配器写在经工具发出的
+ *   消息的投递失败记录上，出站记进历史的各条由写方按出站消息的 callId 记下（有才记）；会话服务据此把历史里的工具卡对回实时推送。
+ * - `ModelInfo`：一轮回复的模型与这一轮的 token，与 {@link OutgoingMessage}.modelInfo 同形；agent 写在这一轮最后的回复上，
+ *   会话服务标在回复条目上。
+ * - `SentRef`、`SentName`：发出的附件（`outboundMediaMessage` 记的那条）原样的地址与文件名（字符串）：占位符里的地址遇到
+ *   「]」会截断、描述位的「]」「|」换成了全角。记出站的一方写（api-message-archive 的 recordOutbound），会话服务优先取它们
+ *   还原附件。
+ * - `DeliveryError`：投递失败记录（{@link WellKnownKinds}.OutboundDeliveryFailed）里与投递结果同一句的原因（字符串或文字对象），
+ *   平台适配器写；会话服务据此按读者语言写出回复为什么没发出。
+ * - `SentPieces`：投递失败记录里与投递结果同一个已发出条数（数字，{@link OutboundDeliveryResult} 的 sentPieces），平台适配器在
+ *   逐条发出停在中途时写；会话服务据此写出回复只发出了前几条。
+ * - `Unconfirmed`：投递失败记录里已经发出、没等到平台确认的各项（字符串数组，如「消息（第 2 条）」「文件 a.html」），平台适配器写；
+ *   会话服务据此写出回复可能已经发出。
+ * - `Text`：通知与事件标记给人看的文字（@aalis/schema-i18n 的文字对象），`content` 是写给模型的话或它按原文渲染的整句。
+ *   宿主通知的 `hostNotice.text`、平台通知的文字、平台事件合成的入站的 {@link IncomingMessage}.text、不是她回复的出站按
+ *   {@link outboundMarkerMessage} 记成事件标记时的 {@link OutgoingMessage}.text 由写方记下，没有地址的出站附件记成的事件标记、
+ *   压缩分隔线同样；会话服务据此按读者语言显示（合成的入站画成通知），没有时显示 `content`。
  */
 export declare const WellKnownMetadataKeys: {
     readonly VisibleContent: "visibleContent";
+    readonly SpokenContent: "spokenContent";
+    readonly Attachments: "attachments";
+    readonly Forwards: "forwards";
+    readonly SenderLabel: "senderLabel";
+    readonly Mentions: "mentions";
+    readonly Platform: "platform";
+    readonly UserId: "userId";
+    readonly Nickname: "nickname";
+    readonly GroupId: "groupId";
+    readonly GroupName: "groupName";
+    readonly SessionType: "sessionType";
+    readonly MessageId: "messageId";
+    readonly Source: "source";
+    readonly HostNoticeKind: "hostNoticeKind";
+    readonly HostNoticeId: "hostNoticeId";
+    readonly HostNoticeFacts: "hostNoticeFacts";
+    readonly TurnId: "turnId";
+    readonly TurnEntry: "turnEntry";
+    readonly TriggerType: "triggerType";
+    readonly TurnRecord: "turnRecord";
+    readonly CallId: "callId";
+    readonly ModelInfo: "modelInfo";
+    readonly SentRef: "ref";
+    readonly SentName: "name";
+    readonly DeliveryError: "error";
+    readonly SentPieces: "sentPieces";
+    readonly Unconfirmed: "unconfirmed";
+    readonly Text: "text";
 };
+/** 一轮的回合记录（{@link WellKnownMetadataKeys} 的 `TurnRecord`）：结局，与这一轮的来源（输入的 source，真人消息开的没有） */
+export interface TurnRecord {
+    outcome: 'replied' | 'silent' | 'aborted' | 'error';
+    source?: string;
+}
 /**
  * 平台无关的 well-known `noticeType` 值。
  *
@@ -342,9 +689,8 @@ export declare const WellKnownMetadataKeys: {
  */
 export declare const WellKnownNoticeTypes: {
     /**
-     * 用户对 bot 的"戳/逗弄"类注意力动作（QQ 戳一戳等）。
-     * adapter 映射约定：群聊场景仅当动作指向 bot 时才转为 inbound（旁观他人互戳不转）；
-     * 私聊场景全部转入（不校验目标）。
+     * "戳/逗弄"类互动动作（QQ 戳一戳等）。
+     * adapter 把群友互戳与戳机器人都转为 inbound，并用 noticeTargetIsSelf 区分是否点名机器人。
      */
     readonly Poke: "poke";
 };
@@ -354,6 +700,13 @@ export type WellKnownNoticeType = (typeof WellKnownNoticeTypes)[keyof typeof Wel
  * 仅用于 UI / 内部状态。LLM 出口、信息抽取等流程默认应排除。
  */
 export declare const CONTROL_KINDS: ReadonlyArray<string>;
+/**
+ * 宿主或系统撰写、不是任何人发言的指令类 kind。
+ * - 归档消息的 kind 属于它：抽取（用户事实、指令、关系）与记忆扩窗一律跳过；
+ * - 请求期消息的 metadata.injector 属于它：是本轮的指令块（turn-context、turn-hint 落在它之前；agent 裁剪时不缩不删；DeepSeek
+ *   不把它改成 user）。
+ */
+export declare const DIRECTIVE_KINDS: ReadonlyArray<string>;
 /**
  * 把 Aalis 内部 role 转译为 LLM 协议接受的 WellKnownRole。
  * 未知 role 一律回落为 'system'，避免任何漏网造成 provider 报错。
@@ -373,7 +726,8 @@ export declare function toLLMRole(role: MessageRole): WellKnownRole;
  * 不修改原对象；返回新数组与必要时的消息浅拷贝。
  */
 export declare function prepareLLMMessages<T extends Pick<Message, 'role' | 'content' | 'kind'> & Pick<Message, 'images' | 'toolCallId'>>(messages: T[]): T[];
-export { type AttachmentRef, AttachmentRefKind, buildAttachmentRefMatcher, formatAttachmentRef, parseAttachmentRefs, } from './attachment-ref.js';
-export { getMessageName, getSenderLabel, prefixSender } from './identity.js';
-export { buildIncomingContent } from './incoming-content.js';
+export { ATTACHMENT_REF_KINDS, type AttachmentRef, AttachmentRefKind, buildAttachmentRefMatcher, formatAttachmentRef, parseAttachmentRefs, } from './attachment-ref.js';
+export { getMessageName, getSenderLabel, prefixSender, stripSenderPrefix } from './identity.js';
+export { buildIncomingContent, forwardPlaceholder, withForwards } from './incoming-content.js';
+export { groupToolCalls, type MessageUnit } from './tool-call-groups.js';
 //# sourceMappingURL=index.d.ts.map