@aalis/schema-message 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ace Nyan <ace@acenyan.com>
+
+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.

package/README.md

@@ -0,0 +1,25 @@
+# @aalis/schema-message
+
+类型/接口/能力声明包（只导出 `type` 与 `*Capabilities`，不含运行时逻辑）
+
+## 角色
+
+类型/接口/能力声明包（只导出 `type` 与 `*Capabilities`，不含运行时逻辑）
+
+## 安装
+
+```bash
+pnpm add @aalis/schema-message
+```
+
+## 使用
+
+```ts
+import type { /* ... */ } from '@aalis/schema-message';
+```
+
+本包为 *-api 类型包；实现见对应的运行时插件。
+
+## 许可
+
+见仓库根目录 LICENSE。

package/dist/attachment-ref.d.ts

@@ -0,0 +1,35 @@
+/** 附件 kind 显示名（中文，用作占位符前缀）。新增 kind 在此处加常量即可。 */
+export declare const AttachmentRefKind: {
+    readonly Image: "图片";
+    readonly Audio: "音频";
+    readonly Video: "视频";
+    readonly File: "文件";
+};
+export type AttachmentRefKind = (typeof AttachmentRefKind)[keyof typeof AttachmentRefKind];
+export interface AttachmentRef {
+    kind: AttachmentRefKind;
+    /** 可选语义描述（视觉概要 / 文件备注 / 音频转写片段等） */
+    desc?: string;
+    /** 引用：本地路径 / file:// / http(s) URL；调用方决定如何解析 */
+    ref: string;
+}
+/**
+ * 把 ref 描述对象格式化为统一占位符字符串。
+ *
+ *   { kind: '图片', desc: 'x', ref: 'p' }  →  '[图片: x | ref:p]'
+ *   { kind: '图片',          ref: 'p' }    →  '[图片 | ref:p]'
+ *
+ * desc 为空字符串视同未提供（与历史行为一致）。
+ */
+export declare function formatAttachmentRef(r: AttachmentRef): string;
+/**
+ * 在文本中扫描所有形如 `[<kind>(: <desc>)? | ref:<ref>]` 的占位符。
+ * `<ref>` 内不允许出现 `]`（这是契约：写入时由 formatAttachmentRef 保证）。
+ */
+export declare function parseAttachmentRefs(text: string): AttachmentRef[];
+/**
+ * 构造一个用于在文本中匹配「指定 kind + 指定 ref」的全部已存在占位符的正则。
+ * 主要给 plugin-media 的 update_image_description 工具用，让它不必重新硬编码格式。
+ */
+export declare function buildAttachmentRefMatcher(kind: AttachmentRefKind, ref: string): RegExp;
+//# sourceMappingURL=attachment-ref.d.ts.map

package/dist/attachment-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-ref.d.ts","sourceRoot":"","sources":["../src/attachment-ref.ts"],"names":[],"mappings":"AAyBA,gDAAgD;AAChD,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAK3F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAI5D;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAUjE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAItF"}

package/dist/attachment-ref.js

@@ -0,0 +1,76 @@
+// ============================================================
+// attachment-ref.ts — 跨插件统一的「附件引用」字符串契约
+//
+// Aalis 在多个地方需要把附件（图片 / 音频 / 视频 / 文件）以可读、可解析的
+// 形式塞回 LLM 上下文里。历史上有四个调用点各自硬编码 `[图片: desc | ref:xxx]`
+// 这种格式：
+//   - plugin-adapter-onebot 入站构造图片占位
+//   - plugin-image-sender 出站归档自己刚发的图
+//   - plugin-media tools.ts regex 重写历史描述
+//   - plugin-image-recognition 解析历史图片引用
+// 任何一处格式漂移都会让其它三处的解析悄悄断链。
+//
+// 本模块提供单一格式来源 + 类型安全的 kind 枚举：
+//   formatAttachmentRef({ kind: AttachmentRefKind.Image, desc: '一只猫', ref: 'data/x.png' })
+//     === '[图片: 一只猫 | ref:data/x.png]'
+//   formatAttachmentRef({ kind: AttachmentRefKind.Image, ref: 'data/x.png' })
+//     === '[图片 | ref:data/x.png]'
+//   parseAttachmentRefs(text)
+//     === [{ kind: '图片', desc?: string, ref: string }, ...]
+//
+// 设计约束：
+//   - 输出必须 byte-for-byte 兼容历史格式（数据库里已有的字符串不重写）。
+//   - parser 不消耗 desc 中的转义；上游写入时确保 desc 不含 `]` / `|`。
+// ============================================================
+/** 附件 kind 显示名（中文，用作占位符前缀）。新增 kind 在此处加常量即可。 */
+export const AttachmentRefKind = {
+    Image: '图片',
+    Audio: '音频',
+    Video: '视频',
+    File: '文件',
+};
+/** 所有 kind 显示名的联合，供正则构造时迭代。 */
+const ALL_KINDS = Object.values(AttachmentRefKind);
+/**
+ * 把 ref 描述对象格式化为统一占位符字符串。
+ *
+ *   { kind: '图片', desc: 'x', ref: 'p' }  →  '[图片: x | ref:p]'
+ *   { kind: '图片',          ref: 'p' }    →  '[图片 | ref:p]'
+ *
+ * desc 为空字符串视同未提供（与历史行为一致）。
+ */
+export function formatAttachmentRef(r) {
+    const desc = r.desc?.trim();
+    if (desc)
+        return `[${r.kind}: ${desc} | ref:${r.ref}]`;
+    return `[${r.kind} | ref:${r.ref}]`;
+}
+// 内部：把所有 kind 拼成 alternation `图片|音频|视频|文件`
+function kindAlternation() {
+    return ALL_KINDS.map(k => k.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+}
+/**
+ * 在文本中扫描所有形如 `[<kind>(: <desc>)? | ref:<ref>]` 的占位符。
+ * `<ref>` 内不允许出现 `]`（这是契约：写入时由 formatAttachmentRef 保证）。
+ */
+export function parseAttachmentRefs(text) {
+    const re = new RegExp(`\\[(${kindAlternation()})(?:: ([^\\]\\n|]+?))? \\| ref:([^\\]\\n]+?)\\]`, 'g');
+    const out = [];
+    for (const m of text.matchAll(re)) {
+        const kind = m[1];
+        const desc = m[2]?.trim();
+        const ref = m[3].trim();
+        out.push(desc ? { kind, desc, ref } : { kind, ref });
+    }
+    return out;
+}
+/**
+ * 构造一个用于在文本中匹配「指定 kind + 指定 ref」的全部已存在占位符的正则。
+ * 主要给 plugin-media 的 update_image_description 工具用，让它不必重新硬编码格式。
+ */
+export function buildAttachmentRefMatcher(kind, ref) {
+    const escapedKind = kind.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escapedRef = ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`\\[${escapedKind}(?:: [^\\]\\n]*?)? \\| ref:${escapedRef}\\]`, 'g');
+}
+//# sourceMappingURL=attachment-ref.js.map

package/dist/attachment-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-ref.js","sourceRoot":"","sources":["../src/attachment-ref.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,wCAAwC;AACxC,EAAE;AACF,8CAA8C;AAC9C,sDAAsD;AACtD,QAAQ;AACR,qCAAqC;AACrC,qCAAqC;AACrC,yCAAyC;AACzC,wCAAwC;AACxC,0BAA0B;AAC1B,EAAE;AACF,+BAA+B;AAC/B,2FAA2F;AAC3F,uCAAuC;AACvC,8EAA8E;AAC9E,kCAAkC;AAClC,8BAA8B;AAC9B,4DAA4D;AAC5D,EAAE;AACF,QAAQ;AACR,gDAAgD;AAChD,sDAAsD;AACtD,+DAA+D;AAE/D,gDAAgD;AAChD,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;IACX,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,IAAI;CACF,CAAC;AAIX,+BAA+B;AAC/B,MAAM,SAAS,GAAiC,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAUjF;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAgB;IAClD,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;IAC5B,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,UAAU,CAAC,CAAC,GAAG,GAAG,CAAC;IACvD,OAAO,IAAI,CAAC,CAAC,IAAI,UAAU,CAAC,CAAC,GAAG,GAAG,CAAC;AACtC,CAAC;AAED,2CAA2C;AAC3C,SAAS,eAAe;IACtB,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAChF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,OAAO,eAAe,EAAE,iDAAiD,EAAE,GAAG,CAAC,CAAC;IACtG,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAsB,CAAC;QACvC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACxB,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAuB,EAAE,GAAW;IAC5E,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IAC9D,OAAO,IAAI,MAAM,CAAC,MAAM,WAAW,8BAA8B,UAAU,KAAK,EAAE,GAAG,CAAC,CAAC;AACzF,CAAC"}

package/dist/identity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 用户身份标识工具函数
+ *
+ * 统一 userId / nickname 的使用模式，避免各插件实现不一致。
+ *
+ * 由 schema-message 提供（cleanup-9 从 core 迁出——core 不应知晓
+ * IM 平台层的「发送者」「昵称」「OpenAI Message.name 字段」等概念）。
+ */
+/**
+ * 获取消息发送者的显示标签。
+ * 同时展示 nickname 和 userId 帮助 LLM 关联身份。
+ * - 两者都有时返回 `昵称(ID)`
+ * - 只有 nickname 返回 nickname
+ * - 只有 userId 返回 userId
+ * - 都无返回 undefined
+ */
+export declare function getSenderLabel(nickname?: string, userId?: string): string | undefined;
+/**
+ * 将发送者标签格式化为消息前缀。
+ * 有标签时返回 `[label]: content`，无标签时原样返回 content。
+ */
+export declare function prefixSender(content: string, nickname?: string, userId?: string): string;
+/**
+ * 获取适用于 Message.name / OpenAI API name 字段的安全标识符。
+ * 使用 userId（稳定不变）而非 nickname（可变）。
+ * 返回 undefined 表示不设置 name 字段。
+ */
+export declare function getMessageName(userId?: string): string | undefined;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIrF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE"}

package/dist/identity.js

@@ -0,0 +1,39 @@
+/**
+ * 用户身份标识工具函数
+ *
+ * 统一 userId / nickname 的使用模式，避免各插件实现不一致。
+ *
+ * 由 schema-message 提供（cleanup-9 从 core 迁出——core 不应知晓
+ * IM 平台层的「发送者」「昵称」「OpenAI Message.name 字段」等概念）。
+ */
+/**
+ * 获取消息发送者的显示标签。
+ * 同时展示 nickname 和 userId 帮助 LLM 关联身份。
+ * - 两者都有时返回 `昵称(ID)`
+ * - 只有 nickname 返回 nickname
+ * - 只有 userId 返回 userId
+ * - 都无返回 undefined
+ */
+export function getSenderLabel(nickname, userId) {
+    const nick = nickname?.trim();
+    if (nick && userId)
+        return `${nick}(${userId})`;
+    return nick || userId || undefined;
+}
+/**
+ * 将发送者标签格式化为消息前缀。
+ * 有标签时返回 `[label]: content`，无标签时原样返回 content。
+ */
+export function prefixSender(content, nickname, userId) {
+    const label = getSenderLabel(nickname, userId);
+    return label ? `[${label}]: ${content}` : content;
+}
+/**
+ * 获取适用于 Message.name / OpenAI API name 字段的安全标识符。
+ * 使用 userId（稳定不变）而非 nickname（可变）。
+ * 返回 undefined 表示不设置 name 字段。
+ */
+export function getMessageName(userId) {
+    return userId || undefined;
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAiB,EAAE,MAAe;IAC/D,MAAM,IAAI,GAAG,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC9B,IAAI,IAAI,IAAI,MAAM;QAAE,OAAO,GAAG,IAAI,IAAI,MAAM,GAAG,CAAC;IAChD,OAAO,IAAI,IAAI,MAAM,IAAI,SAAS,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAiB,EAAE,MAAe;IAC9E,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,OAAO,MAAM,IAAI,SAAS,CAAC;AAC7B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * OpenAI/DeepSeek chat completions 中 assistant 消息携带的工具调用载荷。
+ * 与 Message 同源同生命周期，故所属本包。
+ */
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * 内容时间线分段（按到达顺序记录助手输出的真实结构）。
+ * - text：正常对话文本
+ * - reasoning_text：思考/推理文本（部分模型如 DeepSeek-R1、Ollama thinking 会产出）
+ * - tool_call：工具调用片段（startTime/endTime 用于时长展示）
+ *
+ * 该数组若存在则为渲染顺序的真相；同时 message.content / reasoningContent
+ * 仍保留为派生镜像，供 LLM API 与历史压缩等纯文本消费者使用。
+ */
+export type ContentSegment = {
+    type: 'text';
+    content: string;
+} | {
+    type: 'reasoning_text';
+    content: string;
+} | {
+    type: 'tool_call';
+    name: string;
+    args: Record<string, unknown>;
+    result?: string;
+    startTime?: number;
+    endTime?: number;
+};
+/**
+ * 标准 LLM role（OpenAI / DeepSeek / Ollama 等 chat 协议直接接受的四种）。
+ * 出口适配器只看到这四种；任何 WellKnownRole 以外的扩展 role 需在出口转译为其中之一。
+ */
+export type WellKnownRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * 消息 role：标准四种 + 任意扩展字符串。
+ *
+ * 设计：使用 `WellKnownRole | (string & {})` 模式既保留四种标准 role 的字面量自动补全/收窄，
+ * 又允许任意自定义 role（如 `'notice'`、未来可能的 `'event'` / `'observation'` 等）。
+ *
+ * 约束：自定义 role 仅用于 Aalis 内部存储/检索/渲染；调用 LLM 前必须由 provider 适配器
+ * 转译为 WellKnownRole 之一（典型做法：notice → system，并在 content 前加 `[系统通知]` 前缀）。
+ */
+export type MessageRole = WellKnownRole | (string & {});
+export interface Message {
+    role: MessageRole;
+    content: string | null;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    name?: string;
+    /**
+     * 子分类（与 role 正交的语义维度）。设计目标：
+     * - 让所有 role 共用同一个子类入口，避免 system.name / notice.metadata.noticeType / assistant.metadata.kind 三套互不相通的"伪子分类"。
+     * - 统一过滤/渲染判断：`m.kind === 'event-marker'` 这种写法跨 role 通用。
+     *
+     * 约定的语义类（详见 `WELL_KNOWN_KINDS` / `CONTROL_KINDS`）：
+     * - `'event-marker'`              ：system 控制类标记（如压缩分隔条），不应进入 LLM 上下文。
+     * - `'cross-session-delegation'`  ：notice 子类——来自另一会话的 agent 委派任务。
+     * - `'outbound-image'`            ：assistant 子类——agent 已发出的图片。
+     * - notice 的平台事件类型         ：`'poke' | 'group_recall' | 'group_increase' | ...`（取自 OneBot 等适配器）。
+     *
+     * 第三方插件可定义自己的 kind 字符串，但请避开 `WELL_KNOWN_KINDS` 中已有的语义。
+     */
+    kind?: string;
+    timestamp?: number;
+    reasoningContent?: string | null;
+    /**
+     * 助手输出的有序时间线（含 text / reasoning_text / tool_call）。
+     * 仅 assistant 消息可能携带；存在时为 UI 渲染的权威来源，
+     * content 与 reasoningContent 应与之保持一致（由生产方在累积时同步写）。
+     */
+    segments?: ContentSegment[];
+    /** 图片列表（base64 data URL 或 HTTP URL），用于多模态 LLM */
+    images?: string[];
+    /**
+     * 音频列表（base64 data URL / 本地路径 / file:// / http(s) URL），
+     * 用于支持原生音频输入的 LLM（如 Gemma 3n E 系列、Gemini、GPT-4o-audio）。
+     * Provider 实现需自行解析为各 API 期望的格式（base64 / file ref 等）。
+     */
+    audios?: string[];
+    /** 元数据：用于标记消息来源等信息（不会发送给 LLM） */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 多模态附件统一载体（v2 新主字段）。
+ * 取代 images[] / files[]：所有适配器（OneBot / WebUI / CLI 等）应优先填 attachments，
+ * 旧的 images / files 字段保留以兼容老的预处理器与历史代码，框架内的归一化函数会双向同步。
+ */
+export interface MessageAttachment {
+    /** 媒介类型 */
+    kind: 'image' | 'audio' | 'video' | 'file';
+    /** 内容：base64 data URL / http(s) URL / file:// URI；下游决定如何解析 */
+    data: string;
+    /** MIME 类型，尽量提供以便分发 */
+    mimeType?: string;
+    /** 文件名（如有） */
+    name?: string;
+    /** 来源标识（platform 内部 ID 等，用于幂等与去重） */
+    sourceId?: string;
+    /** 字节大小（如已知，便于上限/计费判断） */
+    byteSize?: number;
+    /** 时长秒（仅音视频，如已知） */
+    durationSec?: number;
+    /**
+     * 出站附件：文本描述（vision/asr 结果）。由生产者（如 send_attachment）填充，
+     * 供全局出站归档写入 `[类型: desc | ref:xxx]` 标记，让 memory_recall 能命中。
+     */
+    description?: string;
+    /**
+     * 出站附件：稳定引用标识（http(s) url / storage uri）。用于出站归档与历史回放；
+     * 缺省时全局归档回退用 data。与平台落盘后改写的 data 解耦，避免归档到临时/不可访问路径。
+     */
+    ref?: string;
+    /**
+     * 出站附件：跳过全局归档。用于 history_ref 重发等场景（同一媒体已在档，
+     * 避免向量库膨胀与重复入档）。缺省 false。
+     */
+    skipArchive?: boolean;
+}
+export interface IncomingMessage {
+    content: string;
+    sessionId: string;
+    platform: string;
+    userId?: string;
+    /** 用户昵称 */
+    nickname?: string;
+    /**
+     * 平台侧消息 ID（如 OneBot 的 message_id）。
+     * 由适配器填充；归档插件会写入 metadata.messageId，供"引用回复"反查归档原文以保留图片描述等富信息。
+     */
+    messageId?: string;
+    /**
+     * 多模态附件统一载体（唯一入口）。
+     * 所有平台适配器（OneBot / WebUI / CLI 等）都应只填此字段；
+     * plugin-media 在 preprocess 阶段会为每条 attachment 生成文本描述写入 _attachmentDescriptions。
+     */
+    attachments?: MessageAttachment[];
+    /**
+     * 预处理器为各 attachments 生成的文本描述（按 attachments 下标对齐；未识别项为 undefined）。
+     * 由 plugin-media 写入。
+     */
+    _attachmentDescriptions?: Array<string | undefined>;
+    /** 会话类型：群聊、私聊、频道等 */
+    sessionType?: 'group' | 'private' | 'channel';
+    /** 消息来源标识（用于并发隔离：同一 session 不同来源互不打断） */
+    source?: string;
+    /** 群名称（仅群聊时可用） */
+    groupName?: string;
+    /** 群组 ID（直接字段，无需从 sessionId 解析） */
+    groupId?: string;
+    /**
+     * 群聊中发送者在群内的角色：owner=群主, admin=管理员, member=普通成员。
+     * 仅群聊有效，由适配器从平台消息 sender 字段或主动查询填充。
+     */
+    senderRole?: 'owner' | 'admin' | 'member';
+    /** 群聊中发送者的专属头衔（如 "群主"、"打卡王" 等），仅群聊有效。 */
+    senderTitle?: string;
+    /**
+     * 群聊中 self 账号（机器人自身）在该群内的角色。
+     * 适配器应在群消息处理时主动查询（带缓存）并填充，用于让 agent 正确认知自身权限。
+     */
+    selfRole?: 'owner' | 'admin' | 'member';
+    /** 群聊中 self 账号的专属头衔（如有）。 */
+    selfTitle?: string;
+    /** 引用回复的原消息 */
+    replyTo?: {
+        messageId: string;
+        content?: string;
+        userId?: string;
+        nickname?: string;
+    };
+    /** 通知子类型（如 poke、group_upload 等非消息事件） */
+    noticeType?: string;
+    /**
+     * 触发类型（适配器侧设置，下游插件可据此区分主发言者语义）：
+     * - 'direct'    私聊或单一用户直连（默认语义：userId 是主发言者）
+     * - 'immediate' 群聊中被 @/名字主动触发（userId 是主发言者）
+     * - 'interval'  群聊中因消息频率/活跃度被动触发（无明确主发言者，userId 仅为最后一条消息发送者）
+     * - 'idle'      空闲自动触发（无 userId / 无主发言者）
+     * - 'proactive' 由另一会话的 agent 通过工具发起跨会话委派（content 是任务描述而非用户消息）
+     * 未设置时下游插件按 'direct' 兼容处理。
+     */
+    triggerType?: 'direct' | 'immediate' | 'interval' | 'idle' | 'proactive';
+    /**
+     * 代理身份（与 platform/userId 解耦）：当本条消息并非由人类直接发送，而是由 scheduler、
+     * idle-trigger、proactive 委派等系统侧触发器投递时，记录"AI 应代谁执行"。
+     *
+     * 与 platform/userId 的区别：
+     * - platform/userId 表示消息的物理来源（路由+发言者标识），写归档、做用户档案/关系；
+     * - actor 表示授权身份，agent 构造 ToolCallContext 时优先使用 actor，
+     *   从而让 authority 守卫按 actor 的 (platform, userId) 查权限等级。
+     *
+     * 触发器（如 scheduler）应在创建任务时 snapshot 调用者身份，触发时回填此字段；
+     * 不能由 LLM/AI 在工具入参中自由指定，避免提权。
+     */
+    actor?: {
+        platform: string;
+        userId: string;
+    };
+}
+export interface OutgoingMessage {
+    content: string;
+    sessionId: string;
+    platform?: string;
+    reasoningContent?: string;
+    /** 助手输出的有序时间线（与 Message.segments 含义一致），存在时为 webui 等消费者顺序渲染的依据 */
+    segments?: ContentSegment[];
+    /**
+     * 助手要附带发送的多模态附件（图片/音频/视频/文件）。
+     * 适配器（OneBot / WebUI 等）应优先发结构化 attachments，把远程 URL 主动下载为本地文件后用 file:// 形式发送。
+     * 若 attachments 为空但 content 内含 `<image url="...">` 标记，则由适配器解析嵌入式发图（旧路径，仍兼容）。
+     */
+    attachments?: MessageAttachment[];
+    /** 消息来源：agent = AI 回复（可分条延迟发送），其他来源默认立即整条发送 */
+    source?: 'agent' | 'system' | 'command';
+    /** 本条回复的 LLM 元数据（供 webui 实时展示，不需持久化）。 */
+    modelInfo?: {
+        provider?: string;
+        model?: string;
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        elapsedMs?: number;
+    };
+}
+/** 流式消息片段 */
+export interface StreamChunkMessage {
+    sessionId: string;
+    platform?: string;
+    contentDelta?: string;
+    reasoningDelta?: string;
+    /**
+     * 工具调用生成进度提示。当 LLM 正在生成 tool_call（不发文本/reasoning）时，
+     * provider 每收到一段 tool_calls delta 会通过此字段上报，让 UI 显示「正在生成工具调用」。
+     * 仅用于 UI 提示，不影响最终 tool_call segment 的下发。
+     */
+    toolCallProgress?: {
+        index: number;
+        name: string;
+        charsAccumulated: number;
+    };
+    done?: boolean;
+    /** 当工具调用次数达到上限时为 true，前端可据此提示用户继续 */
+    toolLimitReached?: boolean;
+}
+declare module '@aalis/core' {
+    interface AalisEvents {
+        'inbound:message': [message: IncomingMessage];
+        /**
+         * 入站消息已落库（来自 message-archive.archiveIncoming）。无论是否触发 agent 回复都会发出。
+         *
+         * payload 字段：
+         * - `incoming`：原始入参（含 platform/userId/nickname/groupName/triggerType 等会话上下文，未必持久化）
+         * - `archivedMessage`：实际写入 memory 的 `Message`（经过预处理器变换后的最终内容，可能与 `incoming.content` 不同）
+         */
+        'inbound:message:archived': [data: {
+            sessionId: string;
+            incoming: IncomingMessage;
+            archivedMessage: Message;
+        }];
+        'outbound:message': [message: OutgoingMessage];
+        'outbound:stream': [chunk: StreamChunkMessage];
+    }
+}
+export type _MessageRef = Message;
+/**
+ * 已知的 Message.kind 语义常量。第三方插件可使用新值；本表仅作为框架内的契约。
+ *
+ * - `EventMarker`：纯 UI/控制标记（如对话压缩分隔条）。LLM 出口与抽取均应排除。
+ * - `CrossSessionDelegation`：跨会话委派——另一 agent 通过工具向本会话派发任务。
+ * - `OutboundImage`：assistant 已发出的图片占位（content 为 attachment ref 标签）。
+ * - `OutboundAudio`：assistant 已发出的语音占位。
+ * - `OutboundVideo`：assistant 已发出的视频占位。
+ */
+export declare const WellKnownKinds: {
+    readonly EventMarker: "event-marker";
+    readonly CrossSessionDelegation: "cross-session-delegation";
+    readonly OutboundImage: "outbound-image";
+    readonly OutboundAudio: "outbound-audio";
+    readonly OutboundVideo: "outbound-video";
+};
+export type WellKnownKind = (typeof WellKnownKinds)[keyof typeof WellKnownKinds];
+/**
+ * 控制类 kind 集合：这些消息不携带可供模型理解或抽取的语义内容，
+ * 仅用于 UI / 内部状态。LLM 出口、信息抽取等流程默认应排除。
+ */
+export declare const CONTROL_KINDS: ReadonlyArray<string>;
+/**
+ * 把 Aalis 内部 role 转译为 LLM 协议接受的 WellKnownRole。
+ * 未知 role 一律回落为 'system'，避免任何漏网造成 provider 报错。
+ */
+export declare function toLLMRole(role: MessageRole): WellKnownRole;
+/**
+ * 准备发往 LLM provider 的消息：把所有自定义 role 转译为 WellKnownRole，
+ * 同时给 content 加上可读前缀（kind 优先，其次 role）。
+ * provider 适配器应在序列化前调用该函数，确保协议合法。
+ *
+ * 不修改原对象；返回浅拷贝数组与必要时的消息浅拷贝。
+ */
+export declare function prepareLLMMessages<T extends Pick<Message, 'role' | 'content' | 'kind'>>(messages: T[]): T[];
+export { type AttachmentRef, AttachmentRefKind, buildAttachmentRefMatcher, formatAttachmentRef, parseAttachmentRefs, } from './attachment-ref.js';
+export { getMessageName, getSenderLabel, prefixSender } from './identity.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,102 @@
+// ============================================================
+// @aalis/schema-message — 消息层契约
+//
+// 本包持有 Aalis 全部"消息载体"类型，分两层：
+//
+// 1. LLM 协议层（OpenAI/DeepSeek format）：
+//   - Message：LLM 对话上下文消息（role / content / toolCalls / segments ...）
+//   - ContentSegment：助手输出的有序时间线分段（text / reasoning_text / tool_call）
+//   - ToolCall：助手消息的 tool_calls 载荷（同为 OpenAI chat 协议字段）
+//
+// 2. 平台适配层（Aalis 边界消息形态）：
+//   - IncomingMessage：从平台适配器（OneBot / WebUI / CLI 等）流入的原始消息
+//   - OutgoingMessage：发往平台的回复消息
+//   - StreamChunkMessage：流式回复片段（用于 WebUI 等支持流式的前端）
+//
+// 同时通过 declaration merging 将下列事件注入 `AalisEvents`：
+//   - 'inbound:message'
+//   - 'inbound:message:archived'
+//   - 'outbound:message'
+//   - 'outbound:stream'
+//
+// 依赖：@aalis/core（类型锚点）+ @aalis/util-text-normalize（prepareLLMMessages 的 UTF-16 规整）。
+// ============================================================
+import { toWellFormedText } from '@aalis/util-text-normalize';
+// ============================================================
+// LLM 出口工具：自定义 role → WellKnownRole 转译
+// ============================================================
+/**
+ * 已知的 Message.kind 语义常量。第三方插件可使用新值；本表仅作为框架内的契约。
+ *
+ * - `EventMarker`：纯 UI/控制标记（如对话压缩分隔条）。LLM 出口与抽取均应排除。
+ * - `CrossSessionDelegation`：跨会话委派——另一 agent 通过工具向本会话派发任务。
+ * - `OutboundImage`：assistant 已发出的图片占位（content 为 attachment ref 标签）。
+ * - `OutboundAudio`：assistant 已发出的语音占位。
+ * - `OutboundVideo`：assistant 已发出的视频占位。
+ */
+export const WellKnownKinds = {
+    EventMarker: 'event-marker',
+    CrossSessionDelegation: 'cross-session-delegation',
+    OutboundImage: 'outbound-image',
+    OutboundAudio: 'outbound-audio',
+    OutboundVideo: 'outbound-video',
+};
+/**
+ * 控制类 kind 集合：这些消息不携带可供模型理解或抽取的语义内容，
+ * 仅用于 UI / 内部状态。LLM 出口、信息抽取等流程默认应排除。
+ */
+export const CONTROL_KINDS = [WellKnownKinds.EventMarker];
+/** 自定义 role 转译为 LLM 接受的 WellKnownRole 的默认映射。 */
+const CUSTOM_ROLE_MAP = {
+    notice: 'system',
+};
+/** 自定义 role 在 LLM 视角下的内容前缀（仅当转译为 system 时使用）。 */
+const CUSTOM_ROLE_PREFIX = {
+    notice: '[系统通知]',
+};
+/**
+ * Kind 级别的内容前缀（优先级高于 role 前缀）。当 message.kind 命中时，
+ * 用此前缀替换 role 前缀，从而精确表达子语义（例如「跨会话委派」与普通通知区分）。
+ */
+const KIND_PREFIX = {
+    [WellKnownKinds.CrossSessionDelegation]: '[跨会话委派]',
+};
+/**
+ * 把 Aalis 内部 role 转译为 LLM 协议接受的 WellKnownRole。
+ * 未知 role 一律回落为 'system'，避免任何漏网造成 provider 报错。
+ */
+export function toLLMRole(role) {
+    if (role === 'system' || role === 'user' || role === 'assistant' || role === 'tool') {
+        return role;
+    }
+    return CUSTOM_ROLE_MAP[role] ?? 'system';
+}
+/**
+ * 准备发往 LLM provider 的消息：把所有自定义 role 转译为 WellKnownRole，
+ * 同时给 content 加上可读前缀（kind 优先，其次 role）。
+ * provider 适配器应在序列化前调用该函数，确保协议合法。
+ *
+ * 不修改原对象；返回浅拷贝数组与必要时的消息浅拷贝。
+ */
+export function prepareLLMMessages(messages) {
+    return messages.map(m => {
+        const llmRole = toLLMRole(m.role);
+        const prefix = (m.kind && KIND_PREFIX[m.kind]) ?? CUSTOM_ROLE_PREFIX[m.role];
+        const needsRoleRewrite = llmRole !== m.role;
+        // 边界硬保证：所有发往 LLM 的 string content 先规整成良构 UTF-16（孤代理→�）。杜绝孤代理经
+        // JSON.stringify 编成 `\ud83d`（半个代理对）被严格 JSON 解析器（如 DeepSeek 服务端）拒收、
+        // 致整条请求 400。对良构内容为 no-op（原样返回、不新建字符串），故不改变现有行为；对任何插件
+        // 产生的内容在此唯一出口自动生效，第三方插件无需感知"孤代理"、无需调用任何东西。
+        const content = typeof m.content === 'string' ? toWellFormedText(m.content) : m.content;
+        const contentChanged = content !== m.content;
+        const needsPrefix = !!prefix && typeof content === 'string' && content.length > 0;
+        if (!needsRoleRewrite && !needsPrefix && !contentChanged)
+            return m;
+        const newContent = needsPrefix ? `${prefix} ${content}` : (content ?? null);
+        return { ...m, role: llmRole, content: newContent };
+    });
+}
+export { AttachmentRefKind, buildAttachmentRefMatcher, formatAttachmentRef, parseAttachmentRefs, } from './attachment-ref.js';
+// ----- 身份标识工具（cleanup-9 从 core 迁入） -----
+export { getMessageName, getSenderLabel, prefixSender } from './identity.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@aalis/schema-message",
+  "version": "0.5.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AalisLabs/Aalis.git",
+    "directory": "packages/schema-message"
+  },
+  "author": "Ace Nyan <ace@acenyan.com>",
+  "bugs": {
+    "url": "https://github.com/AalisLabs/Aalis/issues"
+  },
+  "homepage": "https://github.com/AalisLabs/Aalis#readme",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aalis/util-text-normalize": ">=0.5.1 <1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "@aalis/core": "0.10.0"
+  },
+  "aalis": {
+    "types": true
+  },
+  "peerDependencies": {
+    "@aalis/core": ">=0.2.0 <1.0.0"
+  },
+  "keywords": [
+    "aalis",
+    "aalis-schema"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}