@yunzai-ng/core 0.1.0

package/dist/message/segment.d.ts

@@ -0,0 +1,255 @@
+import type { AtAllSegment, AtSegment, ContactSegment, DiceSegment, FaceSegment, FileSegment, ForwardNode, ForwardSegment, ImageSegment, JsonSegment, KeyboardButton, KeyboardSegment, LocationSegment, MarkdownSegment, MediaInput, MediaRef, MessageContent, MusicSegment, PokeSegment, RawSegment, RecordSegment, ReplySegment, RpsSegment, Segment, SegmentType, ShareSegment, TextSegment, VideoSegment, XmlSegment } from "@yunzai-ng/types";
+/**
+ * 把宽松的媒体输入归一化成 `MediaRef`
+ *
+ * 识别顺序：已归一化对象 → 字节 → URL 对象 → 字符串前缀。字符串规则：
+ * - `http://` / `https://` → `url`
+ * - `file://` → `path`（经 `fileURLToPath`，正确处理 Windows 盘符与转义）
+ * - `base64://` / `data:*;base64,` → `base64`
+ * - 绝对路径 → `path`
+ *
+ * 相对路径**不予接受**：内核无法确定其解析基准（插件根目录、工作目录，或渲染产物目录），
+ * 判定错误的表现为"图片无法发出但未产生报错"。插件应使用 `ctx.resource()` 拼接绝对路径。
+ * @param input 媒体输入
+ * @returns 归一化后的媒体引用
+ * @throws 传入相对路径或空串时
+ */
+export declare function toMediaRef(input: MediaInput): MediaRef;
+/**
+ * 给媒体引用生成一句简短描述（日志用，绝不打印正文）
+ *
+ * base64 与 buffer 只打长度：把 2MB 的 base64 写进日志文件既没用又会把
+ * 日志轮转打满，而 CK/token 若混在其中还会泄露。
+ * @param ref 媒体引用
+ * @returns 描述文本
+ */
+export declare function describeMedia(ref: MediaRef): string;
+/**
+ * 消息段构造器
+ *
+ * 挂在导出对象上而非做成全局：全局构造器会让每个文件都成为潜在的消息构造点，
+ * 热重载时无从判断谁还在引用。
+ */
+export declare const seg: {
+    /**
+     * 纯文本
+     * @param text 文本内容（数字会被转成字符串）
+     * @returns 文本段
+     */
+    text(text: string | number): TextSegment;
+    /**
+     * 图片
+     * @param file 图片来源（链接 / 绝对路径 / Buffer / base64）
+     * @param opts 附加信息
+     * @returns 图片段
+     */
+    image(file: MediaInput, opts?: Omit<ImageSegment, "type" | "file">): ImageSegment;
+    /**
+     * @ 某人
+     * @param uid 用户 id
+     * @param name 展示名（仅回显用）
+     * @returns at 段
+     */
+    at(uid: string, name?: string): AtSegment;
+    /**
+     * @ 全体成员
+     * @returns atAll 段
+     */
+    atAll(): AtAllSegment;
+    /**
+     * QQ 原生表情
+     * @param id 表情 id
+     * @param big 是否超级表情
+     * @returns 表情段
+     */
+    face(id: number, big?: boolean): FaceSegment;
+    /**
+     * 引用回复
+     * @param messageId 被引用的消息 id
+     * @returns 回复段
+     */
+    reply(messageId: string): ReplySegment;
+    /**
+     * 语音
+     * @param file 音频来源
+     * @param opts 附加信息
+     * @returns 语音段
+     */
+    record(file: MediaInput, opts?: Omit<RecordSegment, "type" | "file">): RecordSegment;
+    /**
+     * 短视频
+     * @param file 视频来源
+     * @param thumb 封面
+     * @returns 视频段
+     */
+    video(file: MediaInput, thumb?: MediaInput): VideoSegment;
+    /**
+     * 文件
+     * @param file 文件来源
+     * @param opts 附加信息
+     * @returns 文件段
+     */
+    file(file: MediaInput, opts?: Omit<FileSegment, "type" | "file">): FileSegment;
+    /**
+     * 位置
+     * @param lat 纬度
+     * @param lon 经度
+     * @param opts 标题与描述
+     * @returns 位置段
+     */
+    location(lat: number, lon: number, opts?: Omit<LocationSegment, "type" | "lat" | "lon">): LocationSegment;
+    /**
+     * 链接分享
+     * @param url 目标地址
+     * @param title 标题
+     * @param opts 摘要与缩略图
+     * @returns 分享段
+     */
+    share(url: string, title: string, opts?: Omit<ShareSegment, "type" | "url" | "title">): ShareSegment;
+    /**
+     * 推荐好友/群
+     * @param scene 对象类别
+     * @param id 对象 id
+     * @returns 推荐段
+     */
+    contact(scene: "user" | "group", id: string): ContactSegment;
+    /**
+     * JSON 卡片
+     * @param data 卡片数据；传对象时自动序列化
+     * @returns JSON 段
+     */
+    json(data: string | object): JsonSegment;
+    /**
+     * XML 卡片
+     * @param data 卡片 XML
+     * @returns XML 段
+     */
+    xml(data: string): XmlSegment;
+    /**
+     * 戳一戳
+     * @param uid 目标用户（群聊内必填）
+     * @param pokeType 戳的类型
+     * @returns 戳一戳段
+     */
+    poke(uid?: string, pokeType?: number): PokeSegment;
+    /**
+     * 骰子
+     * @param result 点数，留空由平台随机
+     * @returns 骰子段
+     */
+    dice(result?: number): DiceSegment;
+    /**
+     * 猜拳
+     * @param result 结果，留空由平台随机
+     * @returns 猜拳段
+     */
+    rps(result?: number): RpsSegment;
+    /**
+     * 平台歌曲分享
+     * @param platform 音乐平台
+     * @param id 平台歌曲 id
+     * @returns 音乐段
+     */
+    music(platform: Exclude<MusicSegment["platform"], "custom">, id: string): MusicSegment;
+    /**
+     * 自定义音乐卡片
+     * @param opts 卡片字段
+     * @returns 音乐段
+     */
+    musicCustom(opts: Omit<MusicSegment, "type" | "platform" | "id">): MusicSegment;
+    /**
+     * 合并转发
+     * @param nodes 转发节点
+     * @param opts 外显字段
+     * @returns 合并转发段
+     */
+    forward(nodes: ForwardNode[], opts?: Omit<ForwardSegment, "type" | "nodes" | "id">): ForwardSegment;
+    /**
+     * 合并转发中的一条
+     * @param message 该条内容（支持宽松形式）
+     * @param opts 显示用的发送者信息
+     * @returns 转发节点
+     */
+    node(message: MessageContent, opts?: Omit<ForwardNode, "message" | "messageId">): ForwardNode;
+    /**
+     * Markdown
+     * @param content 正文
+     * @returns Markdown 段
+     */
+    markdown(content: string): MarkdownSegment;
+    /**
+     * 按钮键盘
+     * @param rows 按行组织的按钮
+     * @returns 键盘段
+     */
+    keyboard(rows: KeyboardButton[][]): KeyboardSegment;
+    /**
+     * 平台私有段（兼容出口）
+     * @param platform 来源平台
+     * @param platformType 平台侧段类型名
+     * @param data 原始数据
+     * @returns raw 段
+     */
+    raw(platform: string, platformType: string, data: unknown): RawSegment;
+};
+/**
+ * 判断一个值是否为消息段
+ * @param value 任意值
+ * @returns 是否为 Segment
+ */
+export declare function isSegment(value: unknown): value is Segment;
+/**
+ * 把宽松的消息内容归一化成消息段数组
+ *
+ * 展平任意层嵌套数组、把裸字符串/数字转成文本段、丢掉 `null`/`undefined`/`false`
+ * 与空文本，并合并相邻文本段（见文件头第 2、3 条）。
+ * @param content 消息内容
+ * @returns 消息段数组；内容为空时返回空数组
+ */
+export declare function toSegments(content: MessageContent): Segment[];
+/**
+ * 取消息的纯文本视图
+ * @param segments 消息段
+ * @returns 拼接后 trim 的文本；无文本段时为空串
+ */
+export declare function textOf(segments: readonly Segment[]): string;
+/**
+ * 取消息里的全部图片段
+ * @param segments 消息段
+ * @returns 图片段数组
+ */
+export declare function imagesOf(segments: readonly Segment[]): ImageSegment[];
+/**
+ * 取消息里被 @ 的用户 id
+ * @param segments 消息段
+ * @returns 用户 id 数组，已去重且保持出现顺序
+ */
+export declare function atUsersOf(segments: readonly Segment[]): string[];
+/**
+ * 判断消息里是否有 @全体成员
+ * @param segments 消息段
+ * @returns 是否含 atAll
+ */
+export declare function hasAtAll(segments: readonly Segment[]): boolean;
+/**
+ * 取消息里第一个 reply 段指向的消息 id
+ * @param segments 消息段
+ * @returns 消息 id；没有 reply 段时 undefined
+ */
+export declare function quotedIdOf(segments: readonly Segment[]): string | undefined;
+/**
+ * 统计各类型段的数量
+ * @param segments 消息段
+ * @returns 类型到数量的映射
+ */
+export declare function countByType(segments: readonly Segment[]): Partial<Record<SegmentType, number>>;
+/**
+ * 将消息渲染成一行日志文本
+ *
+ * 媒体只出摘要不出正文，见 `describeMedia`。这是日志中"收到消息"一行的来源，
+ * 也是排障时查阅频率最高的内容，因此格式刻意贴近使用者在聊天窗口中看到的形态。
+ * @param segments 消息段
+ * @returns 单行描述
+ */
+export declare function describeMessage(segments: readonly Segment[]): string;
+//# sourceMappingURL=segment.d.ts.map

package/dist/message/segment.d.ts.map

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