@yunzai-ng/core 0.1.0

package/src/logger/rotate.ts

@@ -0,0 +1,265 @@
+/**
+ * 模块职责：日志文件的滚动写入与保留策略
+ * 依赖方向：仅依赖 node:fs / node:path
+ * 生命周期：由 LoggerHub 创建与关闭；`close()` 前必须 `flushSync()`
+ * 注意事项：刻意**不用** `pino-roll` / `pino/file` 这类 worker 线程 transport。
+ *          worker transport 在两个场景下存在缺陷：
+ *          1) 单文件打包（Windows 安装包）里 worker 入口路径解析不到；
+ *          2) 进程被强杀时 worker 尚未落盘的日志直接丢失 —— 而崩溃前最后
+ *             几行日志恰恰是排障最需要的。
+ *
+ *          因此此处自行维护一个 fd 与内存缓冲：常态下批量异步刷盘，退出与致命
+ *          错误时 `flushSync()` 同步落盘。写入用 `writeSync` 循环，处理
+ *          部分写入（管道/网络盘上会发生）。
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, statSync, unlinkSync, writeSync } from "node:fs"
+import { join } from "node:path"
+
+/** 滚动写入参数 */
+export interface RotateOptions {
+  /** 日志目录 */
+  dir: string
+  /** 文件名前缀，缺省 `"app"` */
+  basename?: string
+  /** 单文件字节上限，缺省 8MB */
+  maxSize?: number
+  /** 保留天数，缺省 14 */
+  keepDays?: number
+  /** 文件数上限，缺省 100（防止同一天大量写入日志将磁盘写满） */
+  maxFiles?: number
+  /** 批量刷盘间隔毫秒，缺省 200 */
+  flushInterval?: number
+  /** 缓冲字节数上限，超过立即刷盘，缺省 32KB */
+  bufferLimit?: number
+}
+
+/** 默认单文件上限：8MB */
+const DEFAULT_MAX_SIZE = 8 * 1024 * 1024
+
+/**
+ * 取本地日期字符串
+ * @param date 时间
+ * @returns 形如 `"2026-08-21"`
+ */
+function localDay(date: Date): string {
+  const y = date.getFullYear()
+  const m = String(date.getMonth() + 1).padStart(2, "0")
+  const d = String(date.getDate()).padStart(2, "0")
+  return `${y}-${m}-${d}`
+}
+
+/**
+ * 滚动日志写入器
+ *
+ * 触发滚动的两个条件：跨自然日、当前文件超过 `maxSize`。
+ * 同一天内超限则追加序号：`app-2026-08-21.1.log`。
+ */
+export class RotatingFileWriter {
+  /** 日志目录 */
+  readonly #dir: string
+  /** 文件名前缀 */
+  readonly #basename: string
+  /** 单文件上限 */
+  readonly #maxSize: number
+  /** 保留天数 */
+  readonly #keepDays: number
+  /** 文件数上限 */
+  readonly #maxFiles: number
+  /** 刷盘间隔 */
+  readonly #flushInterval: number
+  /** 缓冲上限 */
+  readonly #bufferLimit: number
+
+  /** 当前文件描述符 */
+  #fd = -1
+  /** 当前文件路径 */
+  #file = ""
+  /** 当前文件已写字节数 */
+  #size = 0
+  /** 当前文件对应的日期 */
+  #day = ""
+  /** 待刷盘缓冲 */
+  #buffer: string[] = []
+  /** 缓冲字节数（按 UTF-8 估算） */
+  #bufferBytes = 0
+  /** 刷盘定时器 */
+  #timer: NodeJS.Timeout | undefined
+  /** 是否已关闭 */
+  #closed = false
+
+  /**
+   * @param opts 滚动参数
+   */
+  constructor(opts: RotateOptions) {
+    this.#dir = opts.dir
+    this.#basename = opts.basename ?? "app"
+    this.#maxSize = Math.max(64 * 1024, opts.maxSize ?? DEFAULT_MAX_SIZE)
+    this.#keepDays = Math.max(1, opts.keepDays ?? 14)
+    this.#maxFiles = Math.max(2, opts.maxFiles ?? 100)
+    this.#flushInterval = Math.max(50, opts.flushInterval ?? 200)
+    this.#bufferLimit = Math.max(4096, opts.bufferLimit ?? 32 * 1024)
+  }
+
+  /** 当前正在写入的文件路径 */
+  get file(): string {
+    return this.#file
+  }
+
+  /**
+   * 写入一行（调用方需自带换行符，pino 已带）
+   * @param line 日志行
+   */
+  write(line: string): void {
+    if (this.#closed) return
+    this.#buffer.push(line)
+    this.#bufferBytes += Buffer.byteLength(line)
+
+    if (this.#bufferBytes >= this.#bufferLimit) {
+      this.flushSync()
+      return
+    }
+    if (!this.#timer) {
+      this.#timer = setTimeout(() => {
+        this.#timer = undefined
+        this.flushSync()
+      }, this.#flushInterval)
+      // unref：日志缓冲不该拖着进程不让退出
+      if (typeof this.#timer.unref === "function") this.#timer.unref()
+    }
+  }
+
+  /**
+   * 同步刷盘
+   *
+   * 进程退出、`uncaughtException`、`fatal` 级日志之后都应调用，
+   * 否则最关键的几行日志会随进程一起消失。
+   */
+  flushSync(): void {
+    if (this.#buffer.length === 0) return
+    const payload = this.#buffer.join("")
+    this.#buffer = []
+    this.#bufferBytes = 0
+
+    try {
+      this.#ensureTarget(Buffer.byteLength(payload))
+      if (this.#fd < 0) return
+      const data = Buffer.from(payload, "utf8")
+      let offset = 0
+      // writeSync 可能只写了一部分，必须循环
+      while (offset < data.length) {
+        offset += writeSync(this.#fd, data, offset, data.length - offset)
+      }
+      this.#size += data.length
+    } catch {
+      // 日志系统本身不能抛错，否则会把"记录错误"变成"制造错误"。
+      // 磁盘满或权限问题只能静默丢弃，控制台流仍然可用。
+    }
+  }
+
+  /** 刷盘并关闭文件 */
+  close(): void {
+    if (this.#closed) return
+    this.flushSync()
+    this.#closed = true
+    if (this.#timer) {
+      clearTimeout(this.#timer)
+      this.#timer = undefined
+    }
+    if (this.#fd >= 0) {
+      try {
+        closeSync(this.#fd)
+      } catch {
+        // 关闭失败无从处理
+      }
+      this.#fd = -1
+    }
+  }
+
+  /**
+   * 确保当前文件可写且容量足够
+   * @param incoming 即将写入的字节数
+   */
+  #ensureTarget(incoming: number): void {
+    const day = localDay(new Date())
+    const needRotate = this.#fd < 0 || day !== this.#day || this.#size + incoming > this.#maxSize
+    if (!needRotate) return
+
+    if (this.#fd >= 0) {
+      try {
+        closeSync(this.#fd)
+      } catch {
+        // 忽略
+      }
+      this.#fd = -1
+    }
+
+    mkdirSync(this.#dir, { recursive: true })
+    this.#day = day
+
+    // 找当天第一个未超限的序号
+    let index = 0
+    let file = join(this.#dir, `${this.#basename}-${day}.log`)
+    let size = this.#sizeOf(file)
+    while (size + incoming > this.#maxSize && index < 1000) {
+      index++
+      file = join(this.#dir, `${this.#basename}-${day}.${index}.log`)
+      size = this.#sizeOf(file)
+    }
+
+    this.#file = file
+    this.#size = size
+    this.#fd = openSync(file, "a")
+    this.#cleanup()
+  }
+
+  /**
+   * 取文件大小
+   * @param file 文件路径
+   * @returns 字节数；不存在时 0
+   */
+  #sizeOf(file: string): number {
+    try {
+      return existsSync(file) ? statSync(file).size : 0
+    } catch {
+      return 0
+    }
+  }
+
+  /**
+   * 按保留策略删除旧日志
+   *
+   * 只在滚动时调用（低频），因此用同步 API 无妨。
+   */
+  #cleanup(): void {
+    try {
+      const pattern = new RegExp(`^${this.#basename}-(\\d{4}-\\d{2}-\\d{2})(?:\\.(\\d+))?\\.log$`)
+      const files: { name: string; day: string; index: number }[] = []
+      for (const name of readdirSync(this.#dir)) {
+        const m = pattern.exec(name)
+        if (m) files.push({ name, day: m[1]!, index: Number(m[2] ?? 0) })
+      }
+
+      // 按日期倒序、同日按序号倒序 → 数组头部是最新的
+      files.sort((a, b) => (a.day === b.day ? b.index - a.index : a.day < b.day ? 1 : -1))
+
+      const cutoff = new Date()
+      cutoff.setDate(cutoff.getDate() - this.#keepDays)
+      const cutoffDay = localDay(cutoff)
+
+      for (let i = 0; i < files.length; i++) {
+        const entry = files[i]!
+        const tooOld = entry.day < cutoffDay
+        const tooMany = i >= this.#maxFiles
+        if (!tooOld && !tooMany) continue
+        if (join(this.#dir, entry.name) === this.#file) continue
+        try {
+          unlinkSync(join(this.#dir, entry.name))
+        } catch {
+          // 文件被占用（Windows 常见）时留到下次滚动再试
+        }
+      }
+    } catch {
+      // 清理失败不影响写入
+    }
+  }
+}

package/src/message/segment.test.ts

@@ -0,0 +1,335 @@
+/**
+ * 模块职责：消息段编解码的单元测试 —— 归一化、媒体引用、纯文本视图、日志摘要
+ * 依赖方向：测试文件，只依赖 message/segment
+ * 生命周期：纯函数，无夹具
+ * 注意事项：这里盯的是文件头那三条取舍能不能一直守住：
+ *          媒体**不**擅自转 base64、相邻文本段合并、假值被丢弃。
+ *          三条都是"写错了也能跑"的那种缺陷 —— 图片照样发得出去，只是多占几倍
+ *          内存；回复照样收得到，只是被平台当成三条内容计费。
+ *
+ *          路径断言一律以 `resolve()` + `pathToFileURL()` 实时计算，不硬编码
+ *          `C:\` 或 `/tmp`：这套代码 Windows 与 Termux 双端都要跑，
+ *          把盘符写进测试等于把测试绑死在一个平台上。
+ */
+import { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
+import { describe, expect, it } from "vitest"
+import type { MediaRef, MessageContent, Segment } from "@yunzai-ng/types"
+import {
+  atUsersOf,
+  countByType,
+  describeMedia,
+  describeMessage,
+  hasAtAll,
+  imagesOf,
+  isSegment,
+  quotedIdOf,
+  seg,
+  textOf,
+  toMediaRef,
+  toSegments
+} from "./segment.js"
+
+/** 本机上一个真实存在写法的绝对路径 */
+const ABS = resolve("temp", "示例 图.png")
+
+describe("toSegments 归一化", () => {
+  it("裸字符串与数字都变成文本段", () => {
+    expect(toSegments("你好")).toEqual([{ type: "text", text: "你好" }])
+    expect(toSegments(160)).toEqual([{ type: "text", text: "160" }])
+  })
+
+  it("相邻文本段合并成一段", () => {
+    // 原样产出三段的话，部分平台会当成三条内容拼接甚至分别计费
+    expect(toSegments(["你的体力：", 160, "/160"])).toEqual([{ type: "text", text: "你的体力：160/160" }])
+  })
+
+  it("非相邻的文本段各自保留", () => {
+    expect(toSegments(["前", seg.at("20000"), "后"])).toEqual([
+      { type: "text", text: "前" },
+      { type: "at", uid: "20000" },
+      { type: "text", text: "后" }
+    ])
+  })
+
+  it("任意层嵌套数组都被展平", () => {
+    expect(toSegments(["a", ["b", ["c", [["d"]]]]])).toEqual([{ type: "text", text: "abcd" }])
+  })
+
+  it("null / undefined / false / 空串被丢弃", () => {
+    // 于是条件拼装可以直接写 `[e.isGroup && seg.at(uid), "内容"]`
+    expect(toSegments([null, undefined, false, "", "正文"])).toEqual([{ type: "text", text: "正文" }])
+    expect(toSegments(null)).toEqual([])
+    expect(toSegments([])).toEqual([])
+  })
+
+  it("数字 0 是有意义的文本，不能跟着假值一起丢", () => {
+    expect(toSegments(["剩余 ", 0, " 次"])).toEqual([{ type: "text", text: "剩余 0 次" }])
+  })
+
+  it("已经是段的对象原样透传", () => {
+    const image = seg.image("https://example.com/a.png")
+    const out = toSegments(["看图", image])
+    expect(out[1]).toBe(image)
+  })
+
+  it("文本段对象也参与合并", () => {
+    expect(toSegments([seg.text("甲"), { type: "text", text: "乙" }])).toEqual([{ type: "text", text: "甲乙" }])
+  })
+
+  it("空文本段不会额外产生一个段", () => {
+    expect(toSegments([seg.text(""), seg.at("1")])).toEqual([{ type: "at", uid: "1" }])
+  })
+
+  it("认不出来的对象被丢掉而不是抛错", () => {
+    // 平台或插件传入非法数据时，宁可少一个段，亦不应使整条回复无法发出
+    expect(toSegments([{ foo: 1 }, "正文"] as unknown as MessageContent)).toEqual([{ type: "text", text: "正文" }])
+  })
+})
+
+describe("toMediaRef 媒体归一化", () => {
+  it("http(s) 链接归到 url", () => {
+    expect(toMediaRef("https://example.com/a.png")).toEqual({ kind: "url", url: "https://example.com/a.png" })
+    expect(toMediaRef("http://example.com/a.png")).toEqual({ kind: "url", url: "http://example.com/a.png" })
+  })
+
+  it("file:// 与绝对路径都归到 path", () => {
+    // 经 fileURLToPath 而不是字符串切片：Windows 盘符与 %20 转义都要正确还原
+    expect(toMediaRef(pathToFileURL(ABS).href)).toEqual({ kind: "path", path: ABS })
+    expect(toMediaRef(pathToFileURL(ABS))).toEqual({ kind: "path", path: ABS })
+    expect(toMediaRef(ABS)).toEqual({ kind: "path", path: ABS })
+  })
+
+  it("URL 对象按协议分流", () => {
+    expect(toMediaRef(new URL("https://example.com/a.png"))).toEqual({
+      kind: "url",
+      url: "https://example.com/a.png"
+    })
+  })
+
+  it("base64:// 前缀归到 base64", () => {
+    expect(toMediaRef("base64://QUJD")).toEqual({ kind: "base64", base64: "QUJD" })
+  })
+
+  it("data URI 归到 base64 并带上 mime", () => {
+    expect(toMediaRef("data:image/png;base64,QUJD")).toEqual({ kind: "base64", base64: "QUJD", mime: "image/png" })
+    expect(toMediaRef("data:text/plain;charset=utf-8;base64,QUJD")).toEqual({
+      kind: "base64",
+      base64: "QUJD",
+      mime: "text/plain"
+    })
+    // 未标注 mime 的 data URI 不应写入一个空串 mime
+    expect(toMediaRef("data:;base64,QUJD")).toEqual({ kind: "base64", base64: "QUJD" })
+  })
+
+  it("字节直接归到 buffer，不做 base64 编码", () => {
+    const bytes = new Uint8Array([1, 2, 3])
+    const ref = toMediaRef(bytes)
+    expect(ref).toEqual({ kind: "buffer", data: bytes })
+    // 同一块内存，不做拷贝：base64 会让 2MB 的图多占 2.7MB
+    if (ref.kind === "buffer") expect(ref.data).toBe(bytes)
+  })
+
+  it("ArrayBuffer 包成 Uint8Array 视图", () => {
+    const buf = new ArrayBuffer(2)
+    new Uint8Array(buf).set([7, 8])
+    expect(toMediaRef(buf)).toEqual({ kind: "buffer", data: new Uint8Array([7, 8]) })
+  })
+
+  it("已归一化的引用原样返回，不重复包装", () => {
+    const ref: MediaRef = { kind: "id", id: "file-123" }
+    expect(toMediaRef(ref)).toBe(ref)
+  })
+
+  it("相对路径被拒绝，并指出该用 ctx.resource", () => {
+    // 内核无从判定其解析基准，判定错误的表现为"图片无法发出但未产生报错"
+    expect(() => toMediaRef("./resources/a.png")).toThrow(/ctx\.resource/)
+    expect(() => toMediaRef("a.png")).toThrow(/无法识别的媒体引用/)
+  })
+
+  it("空串被拒绝", () => {
+    expect(() => toMediaRef("")).toThrow("媒体引用不能为空串")
+  })
+})
+
+describe("seg 构造器", () => {
+  it("可选参数没传时不留 undefined 键", () => {
+    // 留着的话适配器 `if ("name" in s)` 之类的判断会误判，序列化出去也多一个 null
+    expect(seg.at("20000")).toEqual({ type: "at", uid: "20000" })
+    expect(Object.keys(seg.at("20000"))).toEqual(["type", "uid"])
+    expect(Object.keys(seg.face(1))).toEqual(["type", "id"])
+    expect(Object.keys(seg.poke())).toEqual(["type"])
+    expect(Object.keys(seg.dice())).toEqual(["type"])
+    expect(Object.keys(seg.video("https://e.com/v.mp4"))).toEqual(["type", "file"])
+  })
+
+  it("可选参数传了就带上", () => {
+    expect(seg.at("20000", "阿测")).toEqual({ type: "at", uid: "20000", name: "阿测" })
+    expect(seg.face(4, true)).toEqual({ type: "face", id: 4, big: true })
+    expect(seg.poke("20000", 2)).toEqual({ type: "poke", uid: "20000", pokeType: 2 })
+    expect(seg.dice(6)).toEqual({ type: "dice", result: 6 })
+  })
+
+  it("媒体类构造器把来源归一化，附加字段照原样带上", () => {
+    expect(seg.image(ABS, { summary: "面板图", width: 800 })).toEqual({
+      type: "image",
+      file: { kind: "path", path: ABS },
+      summary: "面板图",
+      width: 800
+    })
+    expect(seg.file("base64://QUJD", { name: "a.txt" })).toEqual({
+      type: "file",
+      file: { kind: "base64", base64: "QUJD" },
+      name: "a.txt"
+    })
+    expect(seg.video("https://e.com/v.mp4", ABS)).toEqual({
+      type: "video",
+      file: { kind: "url", url: "https://e.com/v.mp4" },
+      thumb: { kind: "path", path: ABS }
+    })
+  })
+
+  it("json 接对象时自动序列化", () => {
+    expect(seg.json({ app: "com.tencent.miniapp" })).toEqual({
+      type: "json",
+      data: '{"app":"com.tencent.miniapp"}'
+    })
+    expect(seg.json('{"raw":1}')).toEqual({ type: "json", data: '{"raw":1}' })
+  })
+
+  it("转发节点的内容也走归一化", () => {
+    const node = seg.node(["第", 1, "条"], { name: "阿测", uid: "20000" })
+    expect(node).toEqual({ message: [{ type: "text", text: "第1条" }], name: "阿测", uid: "20000" })
+
+    expect(seg.forward([node], { summary: "查看 1 条转发" })).toEqual({
+      type: "forward",
+      nodes: [node],
+      summary: "查看 1 条转发"
+    })
+  })
+
+  it("音乐分两种：平台歌曲与自定义卡片", () => {
+    expect(seg.music("163", "123")).toEqual({ type: "music", platform: "163", id: "123" })
+    expect(seg.musicCustom({ title: "曲名", url: "https://e.com/s", audio: "https://e.com/a.mp3" })).toEqual({
+      type: "music",
+      platform: "custom",
+      title: "曲名",
+      url: "https://e.com/s",
+      audio: "https://e.com/a.mp3"
+    })
+  })
+
+  it("raw 段为平台私有内容的兼容出口", () => {
+    expect(seg.raw("napcat", "mface", { emoji_id: "x" })).toEqual({
+      type: "raw",
+      platform: "napcat",
+      platformType: "mface",
+      data: { emoji_id: "x" }
+    })
+  })
+})
+
+describe("派生视图", () => {
+  /** 一条什么都有的消息 */
+  const rich: Segment[] = [
+    seg.reply("m-1"),
+    seg.at("10000", "机器人"),
+    seg.at("20000"),
+    seg.at("20000"),
+    seg.at(""),
+    seg.text("  查一下 "),
+    seg.atAll(),
+    seg.image("https://e.com/1.png"),
+    seg.image(ABS),
+    seg.text("角色  ")
+  ]
+
+  it("textOf 只拼文本段并 trim", () => {
+    expect(textOf(rich)).toBe("查一下 角色")
+    expect(textOf([])).toBe("")
+    expect(textOf([seg.image(ABS)])).toBe("")
+  })
+
+  it("imagesOf 按出现顺序取全部图片", () => {
+    expect(imagesOf(rich).map(i => i.file.kind)).toEqual(["url", "path"])
+  })
+
+  it("atUsersOf 去重保序并忽略空 uid", () => {
+    expect(atUsersOf(rich)).toEqual(["10000", "20000"])
+  })
+
+  it("hasAtAll 认 atAll 段", () => {
+    expect(hasAtAll(rich)).toBe(true)
+    expect(hasAtAll([seg.at("20000")])).toBe(false)
+  })
+
+  it("quotedIdOf 取第一个 reply 段", () => {
+    expect(quotedIdOf(rich)).toBe("m-1")
+    expect(quotedIdOf([seg.reply("a"), seg.reply("b")])).toBe("a")
+    expect(quotedIdOf([seg.text("无引用")])).toBeUndefined()
+  })
+
+  it("countByType 统计各类型条数", () => {
+    expect(countByType(rich)).toEqual({ reply: 1, at: 4, text: 2, atAll: 1, image: 2 })
+    expect(countByType([])).toEqual({})
+  })
+
+  it("isSegment 只认有 type 字符串的对象", () => {
+    expect(isSegment(seg.text("x"))).toBe(true)
+    expect(isSegment({ type: "谁知道是什么" })).toBe(true)
+    expect(isSegment({ type: 1 })).toBe(false)
+    expect(isSegment(null)).toBe(false)
+    expect(isSegment("text")).toBe(false)
+  })
+})
+
+describe("日志摘要", () => {
+  it("describeMedia 对 base64 与字节只报长度", () => {
+    // 把 2MB 的 base64 写进日志既没用又会把轮转打满，混在里面的 CK 还会泄露
+    expect(describeMedia({ kind: "base64", base64: "QUJD" })).toBe("base64 4 字符")
+    expect(describeMedia({ kind: "buffer", data: new Uint8Array(2048) })).toBe("2048 字节")
+    expect(describeMedia({ kind: "id", id: "f-1" })).toBe("id:f-1")
+    expect(describeMedia({ kind: "path", path: ABS })).toBe(ABS)
+  })
+
+  it("describeMedia 把超长 url 截断", () => {
+    const long = `https://example.com/${"a".repeat(80)}.png`
+    const out = describeMedia({ kind: "url", url: long })
+    expect([...out]).toHaveLength(61)
+    expect(out.endsWith("…")).toBe(true)
+  })
+
+  it("describeMessage 贴着聊天窗口的样子拼一行", () => {
+    expect(
+      describeMessage([
+        seg.reply("m-1"),
+        seg.at("20000", "阿测"),
+        seg.at("30000"),
+        seg.atAll(),
+        seg.text("查\n角色"),
+        seg.face(4),
+        seg.image("https://e.com/1.png"),
+        seg.record(ABS),
+        seg.video(ABS),
+        seg.file(ABS, { name: "a.txt" }),
+        seg.forward([seg.node("一条")]),
+        seg.json("{}"),
+        seg.markdown("# 标题"),
+        seg.keyboard([[{ label: "按我", action: "input", data: "#帮助" }]]),
+        seg.raw("napcat", "mface", {})
+      ])
+    ).toBe("[回复m-1][@阿测][@30000][@全体]查 角色[表情4][图片 https://e.com/1.png][语音][视频][文件 a.txt][合并转发 1][卡片][Markdown][按钮][napcat:mface]")
+  })
+
+  it("describeMessage 里的媒体只出摘要，不出正文", () => {
+    const out = describeMessage([seg.image(`base64://${"Q".repeat(200)}`)])
+    expect(out).toBe("[图片 base64 200 字符]")
+    expect(out).not.toContain("QQQ")
+  })
+
+  it("describeMessage 把超长文本截断", () => {
+    const out = describeMessage([seg.text("字".repeat(50))])
+    expect([...out]).toHaveLength(41)
+    expect(out.endsWith("…")).toBe(true)
+  })
+})