dsh-ebbing-context 0.0.0-stage → 0.2.7

package/lib/config.js

@@ -0,0 +1,195 @@
+// 配置：长度一律按 token，只有标题按字符。可被 profile 的 bundle patch 行 config 覆盖。
+// 纪律：配置项名字只在这里定义一次，别处一律引用，不许硬编码数字。
+
+export const DEFAULTS = {
+  // 各区总长上限（占可用输入预算的比例：窗口减输出预留，且不低于窗口的 10%）。
+  // 超了只在提醒里报数字，不做任何机械处置。
+  budget: { l1: 0.10, l2: 0.06, l3: 0.03 },
+
+  // 单块正文上限，单位是 token（不是字数）。用插件自带估算器算（中文 1 字≈0.6 token、
+  // 英文 1 字≈0.3 token，按真实用量校准过），不用宿主那套 4 字 1 token 的口径，
+  // 否则中英文会被同一个数字卡出两种结果。超了直接拒绝写入，把实测值与上限回给模型。
+  segment: { l1: 5000, l2: 2000, l3: 5000 },
+
+  // 压缩比不设门槛、也不在提示里提。原来那套"至少 25 倍/8 倍"等于在鼓励模型
+  // 往死里压；而压缩比只有下限没有上限，真压成一句话它也照样通过。
+  // 现在只保留一条硬约束：压完必须比原来小（那是宿主的硬要求，不达标整批不落盘）。
+
+  // 标题上限：用"等效 token"算（中文 1 字 = 0.6，英文 1 字 = 0.3）。
+  // 不用宿主的估算器——它按 CHARS_PER_TOKEN=4 直接除 text.length，
+  // 中文会被低估约 4 倍（4 个汉字才算 1 token），拿来当长度尺子会松得离谱。
+  title: { maxTokens: 50 },
+
+  // 剪掉超大的工具返回（原位改写，原文仍在日志，可逆性比我们好）。
+  // 宿主的 toolResultPruner 是全局服务：任何工具返回超过 thresholdChars（默认 8192 字符）
+  // 就把中间挖掉、留 head 4096 + tail 1024；它只碰 tool/result，碰不到 assistant/message
+  // 与 user/message——所以压缩块和摘要剪不掉。
+  // 宿主只在它自己的自动压缩两条路上调它（compaction-basic 的 context-overflow / pressure）——
+  // 宿主把它当"压缩的前置步骤"。我们与它同构：只在 compress 里叫一次（见 compress.js），
+  // 不压缩就不动表层。开关关掉就完全不剪（宿主的 auto 关着时也就没人剪了）。
+  pruneFirst: true,
+
+  // 压缩成功后，把「这次 compress 调用 + 它的返回」从表层折成一句短注。
+  // 摘要里那份参数副本在被折成块之后就是纯重复：原文已经是顶部的块，它却还整份发一遍。
+  // 必须在工具返回后的下一次 pre-step 做——那一刻工具结果才存在；只删调用会留下孤儿返回。
+  // 代价：模型看不到自己那次调用的完整返回，只剩一句"成功了、压了什么"；摘要正文仍在块里。
+  foldCallRecord: true,
+
+  // 到线提醒：占用量达到 triggerPct 时每一轮追加一条；掉到线下就不再发到线提醒（没有滞回）。
+  notice: {
+    enabled: true,
+      // 另一个独立触发条件：自上次提醒后上下文又长了多少 token，就再提醒一次
+    // （总量还没到线、但一直在稳步变长时，这条会先叫）。
+    // 长到这个数却一层都压不动时，额度自动砍到它的一半、基线前移，再长半个额度才重新判
+    // （用户要求 第 2 条：不是静默丢一次，而是把门槛降下来继续等）。
+    growthTokens: 65000,
+    // 增长提醒发出、模型这一轮选择不压之后，门槛按原额的百分之多少重设。
+    // 40 = 原额 65000 的话，下一轮再长 26000 就重新触发（设计约束）。
+    // 100 = 全额重攒；0 = 下一轮立刻再触发。只影响增长这条触发。
+    growthResetPct: 40,
+    // 子代理（宿主用 `agents.enter(agent, owner)` 建出来的非根 agent）要不要也参与：
+    // 默认 true（用户要求 定）——子代理也会碰到已压缩的表层，没有轮次标记它就看不出
+    // 「这一块盖住了哪几轮」，等于压过的信息在它眼里丢了。所以标记、提醒、判据全都照做。
+    // 想安静时可以在面板关掉：关掉后子代理不叫醒、不写标记、不报红字。
+    notifySubagents: true,
+  },
+  reservedTokens: 0,            // 输出预留读不到时的兜底值（0 = 不扣）
+  triggerPct: 0.75,
+
+  // 原文区（l0）必须留住的最后 N 轮：`to` 最多只写到 currentTurn − keepTurns。
+  // 当前轮天然压不了；这条给"最近几轮还在用、压了就要立刻取回原文"留缓冲。
+  keepTurns: 2,
+
+  // 取回：依赖宿主「会话搜索」实验性插件。缺失时每次调用这两个工具都直接报错，
+  // 不静默降级——否则压缩不可逆，而模型不知道自己已经取不回原文了。
+  requireSessionQuery: true,
+}
+
+export const NAME = 'dsh-ebbing-context'
+export const LOG_FILE = 'ebbing-context.log'
+export const STATUS_COMMAND = 'context-status'
+
+// 块正文第一行的标题行格式：〔L1｜T16–T19｜ev 4121–4390〕标题
+export const TITLE_OPEN = '〔'
+export const TITLE_CLOSE = '〕'
+
+// 与原生成检查点逐字节对齐的前导（宿主未导出该常量，只能自建）
+export const CHECKPOINT_PREAMBLE =
+  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. ' +
+  'Treat the captured context as established background and build on it without restating it. ' +
+  'Continue the task directly from the messages that follow, without acknowledging this checkpoint.'
+
+export const SUMMARY_OPEN_TAG = '<compacted-summary>'
+export const SUMMARY_CLOSE_TAG = '</compacted-summary>'
+
+// 配置自检：不依赖宿主的 schema 机制，自己也能把写错的配置挡下来。
+// 原来只靠 schemastery，加载不到就静默跳过校验——用户以为设上了，其实走的是默认值。
+// 老配置项的迁移：`notice.forgivePct`（旧语义「不压时退回多少额度」，默认 100）
+// 在 0.1.9 之后改名成 `notice.growthResetPct`（新语义「门槛重设到原额的百分之多少」，默认 40）。
+// 不做迁移的话，老 profile 里那一行要么被宿主 schema 丢掉、静默按 40 跑（语义反了），
+// 要么留在对象里被下面的 knownSub 判成"不认识的配置项"，直接拒绝启动（回归修复）。
+// 这里就地改名，并保留"用户原来写的那个数"，不替他猜语义。
+export function migrateConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return raw
+  // 默认就地改（宿主保存配置时只看这个对象，改就地最不容易漏）。
+  // 万一宿主将来把配置对象深冻结，就地写会抛 TypeError、整插件加载失败：
+  // 那时退回"浅拷贝再改"，返回拷贝给调用方即可。
+  try {
+    return migrateInPlace(raw)
+  } catch {
+    const copy = { ...raw }
+    const notice = copy.notice
+    if (notice && typeof notice === 'object' && !Array.isArray(notice)) copy.notice = { ...notice }
+    return migrateInPlace(copy)
+  }
+}
+
+function migrateInPlace(raw) {
+  // 0.1.11 的 patch 模板把 notifySubagents 写错了一层（落到了根上），装过那版的人
+  // 配置里就有个根级键；这里把它挪进 notice，别让它变成"启动即拒绝"。
+  // 判据只看「旧键在不在」，**不要**看新键是不是 undefined：宿主解析 schema 时会把
+  // volatile 叶子按默认值预置好（schemastery 先处理 volatile、再填 default），
+  // 于是新键永远有值，`=== undefined` 恒假 —— 那正是"旧值被静默丢弃"的坑（第四轮审查 D1）。
+  if (raw.notifySubagents !== undefined) {
+    if (!raw.notice || typeof raw.notice !== 'object' || Array.isArray(raw.notice)) raw.notice = {}
+    // 根级键是 0.1.11 模板写错层的产物，只有它还等于旧默认值时才认为"用户没在新位置设过"。
+    const current = raw.notice.notifySubagents
+    const sameAsDefault = current === DEFAULTS.notice.notifySubagents
+    if (current === undefined || sameAsDefault) raw.notice.notifySubagents = raw.notifySubagents
+    delete raw.notifySubagents
+  }
+  const notice = raw.notice
+  if (notice && typeof notice === 'object' && !Array.isArray(notice)) {
+    if (notice.forgivePct !== undefined) {
+      notice.growthResetPct = notice.forgivePct
+      delete notice.forgivePct
+    }
+  }
+  return raw
+}
+
+export function validateConfig(input) {
+  // 迁移可能返回拷贝（配置被冻结时），校验必须看同一份。
+  const raw = migrateConfig(input)
+  const bad = []
+  const num = (value, path, min, max) => {
+    if (value === undefined) return
+    if (typeof value !== 'number' || !Number.isFinite(value)) return bad.push(`${path} 应该是数字，现在是 ${JSON.stringify(value)}`)
+    if (min !== undefined && value < min) bad.push(`${path} 不能小于 ${min}，现在是 ${value}`)
+    if (max !== undefined && value > max) bad.push(`${path} 不能大于 ${max}，现在是 ${value}`)
+  }
+  const bool = (value, path) => {
+    if (value === undefined) return
+    if (typeof value !== 'boolean') bad.push(`${path} 应该是 true 或 false，现在是 ${JSON.stringify(value)}`)
+  }
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`${NAME}: 配置必须是一个对象，现在是 ${JSON.stringify(raw)}`)
+  }
+  for (const group of ['budget', 'segment', 'title', 'notice']) {
+    const value = raw[group]
+    if (value === undefined) continue
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      bad.push(`${group} 应该是对象（形如 ${group}: { ... }），现在是 ${JSON.stringify(value)}`)
+    }
+  }
+  const budget = raw.budget || {}
+  for (const k of ['l1', 'l2', 'l3']) num(budget[k], `budget.${k}`, 0, 1)
+  const segment = raw.segment || {}
+  for (const k of ['l1', 'l2', 'l3']) num(segment[k], `segment.${k}`, 64)
+  const title = raw.title || {}
+  num(title.maxTokens, 'title.maxTokens', 4)
+  const notice = raw.notice || {}
+  bool(notice.enabled, 'notice.enabled')
+  num(notice.growthTokens, 'notice.growthTokens', 0)
+  num(notice.growthResetPct, 'notice.growthResetPct', 0, 100)
+  bool(notice.notifySubagents, 'notice.notifySubagents')
+  bool(raw.pruneFirst, 'pruneFirst')
+  bool(raw.foldCallRecord, 'foldCallRecord')
+  bool(raw.requireSessionQuery, 'requireSessionQuery')
+  num(raw.reservedTokens, 'reservedTokens', 0)
+  num(raw.triggerPct, 'triggerPct', 0.1, 0.99)
+  // keepTurns：面板 min=1 拦正常输入；校验副本上也兜底夹到 1..50（SPEC §4.2：必须是 ≥1 的整数）。
+  // 不再报红、不再停轮——以前放 0 进来靠 pre-step 每轮抛错，会把整段对话打死（用户 2026-11-05）。
+  if (raw.keepTurns !== undefined) {
+    if (typeof raw.keepTurns !== 'number' || !Number.isFinite(raw.keepTurns)) {
+      bad.push(`keepTurns 应该是数字，现在是 ${JSON.stringify(raw.keepTurns)}`)
+    } else {
+      raw.keepTurns = Math.min(50, Math.max(1, Math.trunc(raw.keepTurns)))
+    }
+  }
+  const known = ['budget','segment','title','notice','pruneFirst','foldCallRecord','requireSessionQuery','reservedTokens','triggerPct','keepTurns']
+  for (const key of Object.keys(raw)) {
+    if (!known.includes(key)) bad.push(`不认识的配置项 ${key}（拼错了？可用的是 ${known.join(' / ')}）`)
+  }
+  const knownSub = { budget: ['l1','l2','l3'], segment: ['l1','l2','l3'], title: ['maxTokens'], notice: ['enabled','growthTokens','growthResetPct','notifySubagents'] }
+  for (const [group, keys] of Object.entries(knownSub)) {
+    const value = raw[group]
+    if (value === undefined || value === null || typeof value !== 'object') continue
+    for (const key of Object.keys(value)) {
+      if (!keys.includes(key)) bad.push(`${group}.${key} 不认识（可用的是 ${keys.join(' / ')}）`)
+    }
+  }
+  if (bad.length) {
+    throw new Error(`${NAME}: 配置有 ${bad.length} 处不对，插件拒绝启动（以免你以为设上了、实际用的是默认值）：\n  - ${bad.join('\n  - ')}`)
+  }
+}

package/lib/imageprice.js

@@ -0,0 +1,96 @@
+// 图片计价（设计约束）：宿主按路由声明的图片价是唯一与账单同源的口径，
+// 拿不到就退回固定 800——宁可粗，也不能让计价问题冒到压缩流程里。
+//
+// 宿主口径（`ref/pkg-0.2.2-alpha.2/tok/lib/types/route-pricing.js:28-30`）：
+//   const pricing = llm.imageRequestPricing(provider, model)
+//   const prices = pricing.priceImages(images)   // 每张图（按出现顺序）一个 token 数
+// 张数对不上会抛错。我们全部包在 try/catch 里，任何异常都返回 null（调用方退回 800）。
+//
+// 缓存：按 (provider, model) 缓存 pricing 对象。频繁切模型时最坏情况只是多个键、
+// 每次都退回固定价，不会报错、不会中断压缩。
+import { IMAGE_TOKENS, estimateTokens } from './tokens.js'
+
+// 宿主 `priceImages()` 返回的元素**不是数字**，而是 `{ visualTokens, text }`：
+// 宿主自己的账是 `tokens += price.visualTokens + estimateContent([{type:'text',text:price.text}])`
+// （`ref/pkg-0.2.2-alpha.2/tok/lib/index.js:754-757`）。只认数字的话每张图都会落回 800，
+// 于是"用真实价"这层壳在真机上等于没装（回归修复）。
+// 两种形状都认：数字（旧版/第三方路由）与对象（当前宿主）。
+function normalizePrice(price) {
+  if (typeof price === 'number' && Number.isFinite(price) && price > 0) return price
+  if (price && typeof price === 'object') {
+    const visual = typeof price.visualTokens === 'number' && Number.isFinite(price.visualTokens) ? price.visualTokens : null
+    const text = typeof price.text === 'string' && price.text.length ? estimateTokens(price.text) : 0
+    if (visual !== null && visual >= 0) return Math.max(1, Math.round(visual) + text)
+  }
+  return IMAGE_TOKENS
+}
+
+const seen = new WeakMap() // ctx -> Map<key, pricing|null>
+
+function cacheFor(ctx) {
+  // WeakMap 的键必须是对象：宿主恒传对象，但假宿主/探针可能传 null、数字、字符串，
+  // 那会在 set 处抛「Invalid value used as weak map key」。拿不到可用的键就不缓存。
+  if (!ctx || (typeof ctx !== 'object' && typeof ctx !== 'function')) return null
+  let byKey = seen.get(ctx)
+  if (!byKey) {
+    byKey = new Map()
+    seen.set(ctx, byKey)
+  }
+  return byKey
+}
+
+function pricingOf(ctx, route) {
+  const provider = (route && route.provider) || ''
+  const model = (route && route.model) || ''
+  const key = provider + '\u0000' + model
+  const byKey = cacheFor(ctx)
+  if (!byKey) return null
+  if (byKey.has(key)) return byKey.get(key)
+  let value = null
+  // 只缓存"确定没有图片价"这个结论。llm 服务还没装配、imageRequestPricing 抛错这类
+  // 都是暂时状态（宿主晚装配、适配器刚注册），把它们钉死在缓存里会整个进程都退回 800，
+  // 用户切模型时还会再踩一次（回归修复）。暂时性失败不写缓存，下次调用重试。
+  let cacheable = false
+  try {
+    const llm = ctx && typeof ctx.get === 'function' ? ctx.get('llm') : null
+    if (llm && typeof llm.imageRequestPricing === 'function') {
+      const got = llm.imageRequestPricing(provider, model)
+      if (got && typeof got.priceImages === 'function') value = got
+      // 方法存在、明确没给价（undefined / 缺 priceImages）：这条路由就是不供应图片价，
+      // 属于确定性结论，可以缓存。
+      cacheable = true
+    }
+  } catch {
+    value = null
+    cacheable = false
+  }
+  // 只缓存"拿到了价格对象"这一种结果：适配器未装配、路由暂不可用时 `imageRequestPricing`
+  // 也会返回 undefined，把它永久缓存会让这个进程后续都退回 800（回归修复）。
+  if (cacheable && value) byKey.set(key, value)
+  return value
+}
+
+/**
+ * 给一批图片出现位置定价。返回 null 表示"拿不到按路由的真实价，请退回固定价"。
+ * @param {any} ctx 插件上下文（只用于 ctx.get('llm')）
+ * @param {any} route 当前路由（agent.options 里的 provider/model）
+ * @param {any[]} images 按出现顺序排列的图片块
+ * @param {(event: string, data?: any) => void} [log]
+ * @returns {number[]|null}
+ */
+export function imagePrices(ctx, route, images, log) {
+  if (!Array.isArray(images) || images.length === 0) return []
+  const pricing = pricingOf(ctx, route)
+  if (!pricing) return null
+  try {
+    const prices = pricing.priceImages(images)
+    if (!Array.isArray(prices) || prices.length !== images.length) {
+      if (log) log('image-pricing-mismatch', { want: images.length, got: Array.isArray(prices) ? prices.length : -1 })
+      return null
+    }
+    return prices.map(normalizePrice)
+  } catch (error) {
+    if (log) log('image-pricing-failed', { error: String((error && error.message) || error) })
+    return null
+  }
+}

package/lib/license.js

@@ -0,0 +1,63 @@
+// 压缩许可证：地图是一次"看地形"的凭证，看一次只能用一次。
+// 为什么需要它：模型只能按"区内序号"点名，序号是它看地图那一刻的。
+// 如果中间表层被替换过（上一次压缩、或者别的插件），同一个序号可能指到隔壁的块。
+// 所以：取地图发证，压缩成功收证；想再压必须重新看一遍地图。
+//
+// 判据不用宿主的 `replaceGeneration`（契约收紧）：那个计数会被**任何**替换 +1，
+// 包括宿主自己把提示词重写一遍、图片离线化、我们自己的折叠短注——
+// 它们一个都没动块的位置，却会把刚发出去的地图打废，于是每次压完想再压一层都被假报过期。
+// 现在改成对"地图里真正出现的东西"取指纹：三层的块 seq 表 + 表头节点。
+// 只要这些没变，地图里写的序号就仍然指同一个块；变了就一定是真的过期。
+const seen = new Map()
+
+function fingerprint(zones) {
+  if (!zones || !zones.zones) return null
+  const seqs = (list) => (Array.isArray(list) ? list : []).map((b) => (b && b.seq !== undefined && b.seq !== null ? String(b.seq) : '')).join(',')
+  // 只算三层块的 seq 表，**不含表头节点 0**（回归修复）：节点 0 不在任何地图里展示，
+  // 而宿主重写提示词（渲染文本变化）会把它换成新 seq——带上它就会出现"块一个没动、
+  // 却报这张地图过期"的假报警。地图给模型看的正是这三层，指纹就只盯这三层。
+  return [
+    seqs(zones.zones.l3),
+    seqs(zones.zones.l2),
+    seqs(zones.zones.l1),
+  ].join('|')
+}
+
+
+// 条目上限（许可证本轮要求）：清理只挂在 agent/disposed 上，而插件被禁用时监听器
+// 先卸掉了，之后销毁的代理没人 forget，长跑进程里会缓慢累积。按插入顺序淘汰最老的，
+// 数量封顶即可——条目本身只有指纹，误淘汰最多让模型重看一次地图。
+const SEEN_LIMIT = 256
+
+export function issue(agentId, session, zones) {
+  seen.set(agentId, { fp: fingerprint(zones) })
+  while (seen.size > SEEN_LIMIT) {
+    const oldest = seen.keys().next().value
+    if (oldest === agentId) break
+    seen.delete(oldest)
+  }
+}
+
+export function check(agentId, session, zones) {
+  const rec = seen.get(agentId)
+  if (!rec) {
+    return '还没看过地图：这条提醒或上一次工具结果里附的地图就能用；手边没有时再调一次 context_map。'
+  }
+  // 拿不到指纹（调用方没给 zones）时不拦：宁可按"没过期"放行，也不要凭空造一次拒绝。
+  // 真正的保护仍在 compress 里——它按实时表层重新算区间，区间对不上就整批拒绝。
+  if (rec.fp === null || !zones) return null
+  if (fingerprint(zones) !== rec.fp) {
+    return '这张地图已经过期了（这几层区里的块在这之后变过）——用最近一次结果里附的新地图，照它再压。'
+  }
+  return null
+}
+
+export function consume(agentId) {
+  seen.delete(agentId)
+}
+
+
+
+export function forget(agentId) {
+  seen.delete(agentId)
+}

package/lib/log.js

@@ -0,0 +1,135 @@
+// 运行日志：只记"发生了什么判定"，不记任何消息正文。
+// 纪律：按大小滚动（默认 2 MiB × 2 份），单条超过 4 KiB 截断，写失败静默——
+// 诊断面以 /context-status 为主，这个文件只是给"为什么会这样"留痕。
+//
+// 两条底线（2026-11-05 改）：
+// 1. **建目录失败不等于永久关闭**：以前一次失败就把 logger 换成空函数，整个进程再无痕迹；
+//    现在每次写之前允许重试（失败后 30 秒冷却，避免每步都去撞同一个权限错误）。
+// 2. **`DSH_HOME/logs` 建不了就退到系统临时目录**，宁可位置难看，也别让诊断线自己先断。
+
+import { appendFileSync, mkdirSync, renameSync, statSync, rmSync } from 'node:fs'
+import { isAbsolute, join, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
+
+const MAX_BYTES = 2 * 1024 * 1024
+const KEEP_FILES = 2
+const MAX_LINE = 4 * 1024
+const RETRY_MS = 30 * 1000
+
+function homeDir() {
+  return process.env.DSH_HOME || process.env.HOME || process.env.USERPROFILE || '.'
+}
+
+// 解析成功后的文件路径；空串表示"此刻建不出来"（30 秒后会再试）。
+let target = null
+let targetOrigin = ''
+let lastTry = 0
+
+function logDirs(dir) {
+  const list = [dir]
+  if (process.platform === 'win32' && !dir.startsWith('\\\\?\\')) {
+    const abs = isAbsolute(dir) ? dir : resolve(dir)
+    list.push(`\\\\?\\${abs.replace(/\//g, '\\')}`)
+  }
+  return list
+}
+
+function candidates() {
+  const list = []
+  for (const [dir, origin] of [
+    [join(homeDir(), 'logs'), 'home'],
+    [join(tmpdir(), 'ebbing-context'), 'temp'],
+  ]) {
+    for (const candidate of logDirs(dir)) list.push({ dir: candidate, origin })
+  }
+  return list
+}
+
+// Windows 上超过 MAX_PATH(260) 的路径会让 mkdir 直接失败（ENAMETOOLONG），
+// 那时退回长路径前缀（`\\?\` + 绝对路径）再试一次；还不行就换临时目录。
+function tryResolve() {
+  for (const { dir, origin } of candidates()) {
+    try {
+      mkdirSync(dir, { recursive: true })
+      return { path: join(dir, 'ebbing-context.log'), origin }
+    } catch {}
+  }
+  return null
+}
+
+function ensureTarget() {
+  if (target) return target
+  const now = Date.now()
+  if (now - lastTry < RETRY_MS) return ''
+  lastTry = now
+  const got = tryResolve()
+  if (!got) {
+    target = ''
+    targetOrigin = ''
+    return ''
+  }
+  target = got.path
+  targetOrigin = got.origin
+  return target
+}
+
+// 给 /context-status 用：日志到底写在哪、是不是退到了临时目录。
+export function logStatus() {
+  const path = ensureTarget()
+  return { path, origin: targetOrigin, writable: Boolean(path) }
+}
+
+function rotate(path) {
+  try {
+    if (statSync(path).size < MAX_BYTES) return
+  } catch {
+    return
+  }
+  // 每一步单独兜住：第一次滚动时 .1 还不存在，整体 try 会在第一步就抛出，
+  // 结果主日志永远轮不掉、无限增长。这里必须逐次容错。
+  for (let i = KEEP_FILES - 1; i >= 1; i--) {
+    try {
+      renameSync(`${path}.${i}`, `${path}.${i + 1}`)
+    } catch {}
+  }
+  try {
+    rmSync(`${path}.${KEEP_FILES}`, { force: true })
+  } catch {}
+  try {
+    renameSync(path, `${path}.1`)
+  } catch {
+    // 滚动失败就不滚，宁可日志大一点也不能让插件写崩
+  }
+}
+
+// 同一个 scope 只发一个写入口：多个模块各建一个也能写，但每个实例各记一份"已经滚到哪个大小"，
+// 轮到自己判断时容易在别人刚滚完之后再滚一次；共享一个入口就不会有这个歧义。
+const byScope = new Map()
+
+export function makeLogger(scope) {
+  const cached = byScope.get(scope)
+  if (cached) return cached
+  const write = (event, detail) => {
+    const path = ensureTarget()
+    if (!path) return
+    try {
+      let line = `${new Date().toISOString()} [${scope}] ${event}`
+      if (detail !== undefined) {
+        let text
+        try {
+          text = typeof detail === 'string' ? detail : JSON.stringify(detail)
+        } catch {
+          text = String(detail)
+        }
+        if (text && text.length > MAX_LINE) text = `${text.slice(0, MAX_LINE)}…`
+        if (text) line += ` ${text}`
+      }
+      rotate(path)
+      appendFileSync(path, `${line}\n`)
+    } catch {
+      // 写日志永远不能影响主流程；下次调用会照常重试（不再永久关闭）
+    }
+  }
+  byScope.set(scope, write)
+  return write
+}