@dsh-ft/dsh-fft-settings 0.0.0-stage → 0.5.1

package/src/features/logs/collector.ts

@@ -0,0 +1,313 @@
+/**
+ * FT 运行日志采集器（Host 侧，不依赖 cordis，便于单测）。
+ *
+ * 职责：接收 cordis exporter 的记录 → 节流合并 → 脱敏 → 追加 `$DSH_HOME/logs/ft/current.log`，
+ * 超限轮转、保留 `keep` 份；写失败 / 轮转 / 丢弃一律自报 stderr，绝不抛回业务插件。
+ */
+
+import { appendFile, mkdir, readdir, rename, stat, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  LOGS_CURRENT_FILE,
+  LOGS_FILE_SUFFIX,
+  LOGS_LINE_MAX_BYTES,
+  LOGS_MAX_PENDING_KEYS,
+  LOGS_REPEAT_FIELD,
+  LOGS_ROTATED_PREFIX,
+  LOGS_SECRET_TTL_MS,
+  LOGS_THROTTLE_WINDOW_MS,
+  LOG_LEVEL_THRESHOLD,
+  type LogLevelName,
+} from './contract.js'
+import { byteLength, formatLogLine, formatLogMessage, formatRotationFileName, redactSecrets, truncateLine } from './format.js'
+
+/** 采集器接受的最小记录形状；cordis 的 `Message` 结构上满足它。 */
+export interface CollectorRecord {
+  readonly ts: number
+  readonly type: LogLevelName
+  readonly name: string
+  readonly args: readonly unknown[]
+}
+
+export interface CollectorOptions {
+  /** 落盘目录，通常是 `$DSH_HOME/logs/ft`。 */
+  readonly directory: string
+  readonly level: LogLevelName
+  readonly maxBytes: number
+  readonly keep: number
+  /** 已知密钥（如当前 FTShare Key）的延时提供者；取不到时按空处理。 */
+  readonly secrets?: () => Promise<readonly string[]>
+  readonly fileName?: string
+  /** 注入时钟，便于测试。 */
+  readonly now?: () => number
+  /** 注入定时器；返回取消函数。默认 `setTimeout().unref()`，不阻止进程退出。 */
+  readonly schedule?: (run: () => void, delayMs: number) => () => void
+  /** 自报通道；默认写 stderr。日志系统不能静默失败。 */
+  readonly selfReport?: (message: string) => void
+}
+
+export interface CollectorSnapshot {
+  readonly filePath: string
+  readonly fileBytes: number
+  readonly records: number
+  readonly dropped: number
+  readonly rotations: number
+  readonly writeFailures: number
+  readonly firstTs?: number
+  readonly lastTs?: number
+  readonly byName: Readonly<Record<string, number>>
+}
+
+interface PendingEntry {
+  /** 已格式化（未脱敏、未加重复次数）的单行。 */
+  readonly body: string
+  readonly name: string
+  readonly ts: number
+  count: number
+  firstTs: number
+}
+
+const defaultSchedule = (run: () => void, delayMs: number): (() => void) => {
+  const timer = setTimeout(run, delayMs)
+  timer.unref?.()
+  return () => clearTimeout(timer)
+}
+
+const defaultSelfReport = (message: string): void => {
+  try {
+    process.stderr.write(`[ft-logs] ${message}\n`)
+  } catch {
+    // 连 stderr 都写不进去时只能放弃自报，绝不能因此影响业务插件。
+  }
+}
+
+/** 常驻采集器；生命周期由调用方（cordis `ctx.effect`）负责关闭。 */
+export class FtLogCollector {
+  readonly filePath: string
+  readonly threshold: number
+  private readonly directory: string
+  private readonly options: CollectorOptions
+  private readonly now: () => number
+  private readonly schedule: (run: () => void, delayMs: number) => () => void
+  private readonly report: (message: string) => void
+  private readonly pending = new Map<string, PendingEntry>()
+  private readonly byName = new Map<string, number>()
+  private chain: Promise<void> = Promise.resolve()
+  private ready: Promise<void> | undefined
+  private cancelTimer: (() => void) | undefined
+  private timerDeadline = 0
+  private bytes = 0
+  private records = 0
+  private dropped = 0
+  private rotations = 0
+  private writeFailures = 0
+  private firstTs: number | undefined
+  private lastTs: number | undefined
+  private cachedSecrets: readonly string[] = []
+  private secretsAt = 0
+  private closed = false
+
+  constructor(options: CollectorOptions) {
+    this.options = options
+    this.directory = options.directory
+    this.filePath = join(options.directory, options.fileName ?? LOGS_CURRENT_FILE)
+    this.threshold = LOG_LEVEL_THRESHOLD[options.level]
+    this.now = options.now ?? Date.now
+    this.schedule = options.schedule ?? defaultSchedule
+    this.report = options.selfReport ?? defaultSelfReport
+  }
+
+  /** 接收一条 cordis 记录：同 key 在 10 秒窗口内合并为一行并累计重复次数。 */
+  append(record: CollectorRecord): void {
+    if (this.closed) return
+    // 级别门槛在 cordis 侧已经过滤过一次，这里再兜一层：即使 exporter 的 levels 配错也不会写进文件。
+    if (LOG_LEVEL_THRESHOLD[record.type] > this.threshold) return
+    // 采集器绝不能把异常抛回业务插件的 logger 调用。
+    try {
+      const at = this.now()
+      // key 不含时间戳：同一消息在不同毫秒打出也必须合并。
+      const text = formatLogMessage(record.args)
+      const key = `${record.type}\u0000${record.name}\u0000${text}`
+      const existing = this.pending.get(key)
+      if (existing !== undefined && at - existing.firstTs < LOGS_THROTTLE_WINDOW_MS) {
+        existing.count += 1
+        return
+      }
+      this.sweep(at)
+      if (this.pending.size >= LOGS_MAX_PENDING_KEYS) this.dropOldest()
+      this.pending.set(key, { body: formatLogLine(record), name: record.name, ts: record.ts, count: 1, firstTs: at })
+      this.armTimer(at)
+    } catch (error) {
+      this.writeFailures += 1
+      this.report(`格式化日志失败：${error instanceof Error ? error.message : String(error)}；累计失败 ${this.writeFailures} 次`)
+    }
+  }
+
+  /** 注册时回填 cordis 内置缓冲里剩余的 `error`/`info`（`warn`/`debug` 已丢，不可恢复）。 */
+  async backfill(records: readonly CollectorRecord[]): Promise<void> {
+    for (const record of records) this.append(record)
+    await this.flush()
+  }
+
+  /** 把队列全部落盘（导出前调用），等待写入链结束。 */
+  async flush(): Promise<void> {
+    this.cancel()
+    const entries = [...this.pending.values()]
+    this.pending.clear()
+    for (const entry of entries) this.enqueue(entry)
+    await this.ready
+    await this.chain
+  }
+
+  /** 关闭句柄与队列；之后 `append` 变为空操作。 */
+  async dispose(): Promise<void> {
+    await this.flush()
+    this.closed = true
+    this.cancel()
+  }
+
+  stats(): CollectorSnapshot {
+    return {
+      filePath: this.filePath,
+      fileBytes: this.bytes,
+      records: this.records,
+      dropped: this.dropped,
+      rotations: this.rotations,
+      writeFailures: this.writeFailures,
+      firstTs: this.firstTs,
+      lastTs: this.lastTs,
+      byName: Object.fromEntries(this.byName),
+    }
+  }
+
+  /** 当前已知密钥（带 TTL 缓存，避免每次写盘都解析凭据）。 */
+  private async currentSecrets(): Promise<readonly string[]> {
+    if (this.options.secrets === undefined) return []
+    const at = this.now()
+    if (this.secretsAt !== 0 && at - this.secretsAt < LOGS_SECRET_TTL_MS) return this.cachedSecrets
+    try {
+      this.cachedSecrets = (await this.options.secrets()).filter(secret => secret.length >= 6)
+    } catch {
+      // 取不到密钥时退化为纯模式脱敏，绝不能因此阻断写入。
+      this.cachedSecrets = []
+    }
+    this.secretsAt = at
+    return this.cachedSecrets
+  }
+
+  private armTimer(at: number): void {
+    const earliest = Math.min(...[...this.pending.values()].map(entry => entry.firstTs))
+    const deadline = earliest + LOGS_THROTTLE_WINDOW_MS
+    if (this.cancelTimer !== undefined && this.timerDeadline <= deadline) return
+    this.cancel()
+    this.timerDeadline = deadline
+    this.cancelTimer = this.schedule(() => {
+      this.cancelTimer = undefined
+      this.sweep(this.now())
+    }, Math.max(0, deadline - at))
+  }
+
+  private cancel(): void {
+    this.cancelTimer?.()
+    this.cancelTimer = undefined
+    this.timerDeadline = 0
+  }
+
+  /** 把窗口已过期的待写条目交给写入链（保持插入顺序）。 */
+  private sweep(at: number): void {
+    for (const [key, entry] of [...this.pending]) {
+      if (at - entry.firstTs < LOGS_THROTTLE_WINDOW_MS) continue
+      this.pending.delete(key)
+      this.enqueue(entry)
+    }
+  }
+
+  private dropOldest(): void {
+    const oldest = this.pending.keys().next()
+    if (oldest.done === true) return
+    const entry = this.pending.get(oldest.value)
+    this.pending.delete(oldest.value)
+    this.dropped += entry?.count ?? 1
+    this.report(`待写队列超过 ${LOGS_MAX_PENDING_KEYS} 条，丢弃最旧记录；累计丢弃 ${this.dropped} 条`)
+  }
+
+  private enqueue(entry: PendingEntry): void {
+    this.chain = this.chain.then(async () => {
+      if (this.closed) return
+      try {
+        const secrets = await this.currentSecrets()
+        const repeat = entry.count > 1 ? ` ${LOGS_REPEAT_FIELD}=${entry.count}` : ''
+        const line = truncateLine(redactSecrets(entry.body, secrets) + repeat, LOGS_LINE_MAX_BYTES)
+        await this.write(line, entry)
+      } catch (error) {
+        this.writeFailures += 1
+        this.report(`写入 ${this.filePath} 失败：${error instanceof Error ? error.message : String(error)}；累计失败 ${this.writeFailures} 次`)
+      }
+    })
+  }
+
+  private async write(line: string, entry: PendingEntry): Promise<void> {
+    this.ready ??= mkdir(this.directory, { recursive: true }).then(async () => {
+      try {
+        this.bytes = (await stat(this.filePath)).size
+      } catch {
+        this.bytes = 0
+      }
+    })
+    await this.ready
+    const payload = `${line}\n`
+    const size = byteLength(payload)
+    if (this.bytes > 0 && this.bytes + size > this.options.maxBytes) await this.rotate()
+    await appendFile(this.filePath, payload, 'utf8')
+    this.bytes += size
+    this.records += 1
+    this.firstTs = this.firstTs === undefined ? entry.ts : Math.min(this.firstTs, entry.ts)
+    this.lastTs = this.lastTs === undefined ? entry.ts : Math.max(this.lastTs, entry.ts)
+    this.byName.set(entry.name, (this.byName.get(entry.name) ?? 0) + 1)
+  }
+
+  private async rotate(): Promise<void> {
+    const target = await this.uniqueRotationPath()
+    try {
+      await rename(this.filePath, target)
+    } catch (error) {
+      const code = (error as { code?: string }).code
+      if (code !== 'ENOENT') throw error
+    }
+    this.bytes = 0
+    this.rotations += 1
+    this.report(`日志轮转：${target}（保留最近 ${this.options.keep} 份）`)
+    await this.prune()
+  }
+
+  /** 同一毫秒内可能连续轮转两次（小 maxBytes + 突发），文件名必须唯一，否则会互相覆盖。 */
+  private async uniqueRotationPath(): Promise<string> {
+    const base = formatRotationFileName(this.now())
+    for (let suffix = 1; suffix < 1_000; suffix += 1) {
+      const candidate = join(this.directory, suffix === 1 ? base : base.replace(/\.log$/, `-${suffix}.log`))
+      try {
+        await stat(candidate)
+      } catch {
+        return candidate
+      }
+    }
+    return join(this.directory, base)
+  }
+
+  /** 保留策略按修改时间（而不是文件名）排序：同一毫秒连转时的 `-N` 后缀不影响新旧判断。 */
+  private async prune(): Promise<void> {
+    const names = (await readdir(this.directory))
+      .filter(name => name.startsWith(LOGS_ROTATED_PREFIX) && name.endsWith(LOGS_FILE_SUFFIX))
+    const stamped = await Promise.all(names.map(async name => {
+      const path = join(this.directory, name)
+      try {
+        return { path, mtime: (await stat(path)).mtimeMs }
+      } catch {
+        return { path, mtime: 0 }
+      }
+    }))
+    stamped.sort((left, right) => left.mtime - right.mtime)
+    const excess = stamped.slice(0, Math.max(0, stamped.length - this.options.keep))
+    for (const item of excess) await unlink(item.path).catch(() => undefined)
+  }
+}

package/src/features/logs/config.ts

@@ -0,0 +1,115 @@
+/**
+ * `logs` feature 配置（规格 §10）：`level` / `maxBytes` / `keep` / `sources`，全部有安全默认值，
+ * 不配置也能正常挂载。
+ *
+ * 子 schema 归 feature 所有：本文件导出 `logs` 这一片的原生 Schemastery schema 与默认值，
+ * 插件入口 `src/index.ts` 只负责把它组合进插件的顶层 `Config`。新增 feature 的配置同理，
+ * 不要往这里塞别人的字段。
+ *
+ * `logsConfigSchema` 必须是**原生 Schemastery schema**，不能用任何手写的 Standard Schema 冒充：
+ * DSH 配置收集器的判定是
+ * `Reflect.get(value, Symbol.for('schemastery')) === true && typeof Reflect.get(value, 'type') === 'string'`
+ * （`packages/boot/app-boot/src/config-schema/native.ts`）。不满足会得到
+ * `entry.status='unsupported'` 与一条 `Config is not a native Schemastery schema` 的
+ * **error** 诊断、`x-cordis.complete: false`，`logs.*` 进不了 profile 的配置 schema 与配置编辑器。
+ * 运行时 cordis 只要求 Standard Schema（`vendor/cordis/src/fiber.ts` 的 `resolveConfig`
+ * 读 `Config['~standard'].validate`），所以能跑不等于能加载。
+ *
+ * 校验失败时 cordis 抛 `ValidationError`、**插件整体不挂载**：写错 `level` 或给出越界数值
+ * 都会让插件消失，这是刻意的（配置错误要响，而不是静默回退到别的级别）。
+ * 下面的 `parseLogsConfig` / `resolveLogsConfig` 只是给绕过 cordis 校验的调用方（测试、
+ * 直接调用 `apply`）准备的**内部兜底**：容错、夹紧数值，不是配置的真相来源，
+ * 也不参与 DSH 的 schema 收集。
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { LOGS_CONFIG_LEVELS, type LogsConfigLevel } from './contract.js'
+
+export interface LogsConfig {
+  /** `warn`（默认，error+info+warn）｜`debug`（含 debug）。不提供 `info` 档，见 `./contract.ts`。 */
+  level: LogsConfigLevel
+  /** 单文件上限，超过即轮转。 */
+  maxBytes: number
+  /** 轮转文件保留份数。 */
+  keep: number
+  /** 导出时一并打包的额外来源：文件路径或目录（目录取最近的 `*.log`）。 */
+  sources: string[]
+}
+
+export const DEFAULT_LOGS_CONFIG: LogsConfig = {
+  level: 'warn',
+  maxBytes: 8 * 1024 * 1024,
+  keep: 3,
+  sources: [],
+}
+
+const MIN_MAX_BYTES = 64 * 1024
+const MAX_MAX_BYTES = 1024 * 1024 * 1024
+const MAX_KEEP = 20
+
+/** 每次返回新对象，避免默认值里的 `sources` 数组被调用方改写。 */
+function createDefaultLogsConfig(): LogsConfig {
+  return { ...DEFAULT_LOGS_CONFIG, sources: [] }
+}
+
+/**
+ * `logs` 这一片的原生 Schemastery schema（`src/index.ts` 的顶层 `Config` 组合它）。
+ *
+ * 两点不可省：
+ * 1. `.default()` 必须带默认值对象 —— 无参写法在 Schemastery 里不生效；
+ * 2. 无配置行时 cordis 传的是 `{}` 而不是 `undefined`，靠 `validate` 补齐全部默认值
+ *    （`validate(undefined)` 与 `validate({})` 结果一致）。因此不要在 `apply` 的参数默认值上
+ *    兜底，见 `index.ts`。
+ */
+export const logsConfigSchema = z.object({
+  level: z.union(LOGS_CONFIG_LEVELS).default(DEFAULT_LOGS_CONFIG.level),
+  maxBytes: z.number().min(MIN_MAX_BYTES).max(MAX_MAX_BYTES).default(DEFAULT_LOGS_CONFIG.maxBytes),
+  keep: z.number().min(0).max(MAX_KEEP).default(DEFAULT_LOGS_CONFIG.keep),
+  sources: z.array(z.string()).default([]),
+}).default(createDefaultLogsConfig())
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback
+  return Math.min(max, Math.max(min, Math.trunc(parsed)))
+}
+
+/**
+ * 内部兜底解析：非法组合不抛错，回落到默认值/夹紧；`level` 写错才报 issue
+ * （写错级别等于静默丢日志）。入参是整个插件配置，只取 `input.logs` 这一片；
+ * 只在绕过 cordis 校验时使用。
+ */
+export function parseLogsConfig(input: unknown): { value: LogsConfig } | { issues: { message: string }[] } {
+  if (input === undefined || input === null || input === false) return { value: createDefaultLogsConfig() }
+  if (!isRecord(input)) return { issues: [{ message: '插件配置必须是对象' }] }
+  const raw = isRecord(input.logs) ? input.logs : {}
+  const level = raw.level ?? DEFAULT_LOGS_CONFIG.level
+  if (typeof level !== 'string' || !(LOGS_CONFIG_LEVELS as readonly string[]).includes(level)) {
+    return { issues: [{ message: `logs.level 必须是 ${LOGS_CONFIG_LEVELS.join(' / ')} 之一` }] }
+  }
+  const sources = Array.isArray(raw.sources)
+    ? raw.sources.filter((item): item is string => typeof item === 'string' && item.trim() !== '')
+    : []
+  return {
+    value: {
+      level: level as LogsConfigLevel,
+      maxBytes: clampNumber(raw.maxBytes, DEFAULT_LOGS_CONFIG.maxBytes, MIN_MAX_BYTES, MAX_MAX_BYTES),
+      keep: clampNumber(raw.keep, DEFAULT_LOGS_CONFIG.keep, 0, MAX_KEEP),
+      sources,
+    },
+  }
+}
+
+/** 取值：解析结果永远是完整配置，调用方不再做空值判断。 */
+export function resolveLogsConfig(input: unknown): LogsConfig {
+  const parsed = parseLogsConfig(input)
+  if ('issues' in parsed) {
+    // 兜底路径不阻断挂载：回到默认级别，避免“插件起不来 = 一行日志都没有”。
+    // （真正生效的配置由原生 Schema 校验，写错会在这里之前就让插件不挂载。）
+    return createDefaultLogsConfig()
+  }
+  return parsed.value
+}

package/src/features/logs/contract.ts

@@ -0,0 +1,149 @@
+/**
+ * `logs` 命名空间的共享契约：只有常量与类型，浏览器半边可以安全导入。
+ *
+ * 采集器（Host 常驻）与导出器（设置页）通过文件解耦；本文件是两者唯一的共同语言。
+ */
+
+/**
+ * 卡片在 `ftshare.settings.card` 槽位里的 id 与 order。
+ *
+ * 归 feature 所有（与业务契约同一份来源）：卡片组件与浏览器侧的守卫测试都读它，
+ * order 20 排在 API Key 卡（10）之后。
+ */
+export const LOGS_CARD_ID = 'logs'
+export const LOGS_CARD_ORDER = 20
+
+/** 显式登记的 RPC 方法；未登记的方法一律 `not_found`。 */
+export const LOGS_METHODS = ['stats', 'preview', 'export'] as const
+export type LogsMethod = typeof LOGS_METHODS[number]
+
+export type LogLevelName = 'error' | 'info' | 'warn' | 'debug'
+
+/**
+ * 配置级别 → cordis `levels.default` 数值。
+ *
+ * cordis 的 `levels` 是**接收上限**而不是下限：`targetLevel < level` 才丢弃。
+ * 因此 `warn`(2) 收 error/info/warn，`debug`(3) 收全部，`info`(1) 会把 `warn` 丢掉。
+ */
+export const LOG_LEVEL_THRESHOLD: Record<LogLevelName, number> = { error: 0, info: 1, warn: 2, debug: 3 }
+export const LOG_LEVEL_NAMES = ['warn', 'info', 'debug', 'error'] as const
+
+/**
+ * 可配置的级别（规格 §10）。
+ *
+ * 不提供 `info` 档：`levels` 是接收上限，`info`(1) 会把 `warn`(2) 一起丢掉，与规格 §6
+ * 「失败日志不低于 warn」冲突；`error`(0) 同样不成立（等于只剩 error）。允许值收敛为
+ * `warn | debug`，档位越界由 Schemastery 直接拒绝（插件不挂载），不做静默夹紧。
+ */
+export const LOGS_CONFIG_LEVELS = ['warn', 'debug'] as const
+export type LogsConfigLevel = typeof LOGS_CONFIG_LEVELS[number]
+
+/** 落盘位置：`$DSH_HOME/logs/ft/`。 */
+export const LOGS_DIR_SEGMENTS = ['logs', 'ft'] as const
+export const LOGS_CURRENT_FILE = 'current.log'
+export const LOGS_ROTATED_PREFIX = 'ft-'
+export const LOGS_FILE_SUFFIX = '.log'
+
+export const LOGS_LINE_MAX_BYTES = 8 * 1024
+export const LOGS_TRUNCATED_MARK = '...[已截断]'
+export const LOGS_REPEAT_FIELD = '重复次数'
+export const LOGS_THROTTLE_WINDOW_MS = 10_000
+export const LOGS_MAX_PENDING_KEYS = 2_000
+export const LOGS_MAX_FIELD_LENGTH = 2_000
+export const LOGS_MAX_FIELD_DEPTH = 3
+
+export const LOGS_DEFAULT_PREVIEW_LINES = 80
+export const LOGS_MAX_PREVIEW_LINES = 200
+export const LOGS_PREVIEW_MAX_BYTES = 256 * 1024
+
+/** 导出体积上限（规格 §9）：单来源 2 MiB、合计 8 MiB、目录最多 20 个 `*.log`。 */
+export const LOGS_SOURCE_MAX_BYTES = 2 * 1024 * 1024
+export const LOGS_EXPORT_MAX_BYTES = 8 * 1024 * 1024
+export const LOGS_MAX_SOURCE_FILES = 20
+
+export const LOGS_EXPORT_FILE_PREFIX = 'ft-runtime-'
+export const LOGS_SECRET_TTL_MS = 5_000
+
+/**
+ * 诊断包路由（规格 §9 / §12 决策 3）：`/api` 载体上的第二条精确路由，归 `logs` feature 所有。
+ *
+ * 卡片用 `<a download>` 直接指向它：浏览器同源 GET 自带凭据，不需要 fetch/Blob，
+ * `/api` 前缀的鉴权由载体负责，本 feature 不重复鉴权、也不读任何请求参数。
+ * 它随 owner fiber 释放（`ctx.effect` + `register` 返回的 disposer）。
+ */
+export const LOGS_ARCHIVE_ROUTE = '/api/ftshare-settings/logs.zip' as const
+/** 归档内固定条目名（`manifest.json` 永远排第一）。 */
+export const LOGS_ARCHIVE_MANIFEST = 'manifest.json'
+export const LOGS_ARCHIVE_LOG = 'ft-runtime.log'
+/** 额外来源原文的目录前缀：`sources/<n>-<basename>`。 */
+export const LOGS_ARCHIVE_SOURCE_DIR = 'sources/'
+
+/** 导出 header 里的来源段落分隔标记。 */
+export const LOGS_SECTION_RULE = '====='
+
+/** 一条来源（文件或目录）在 Host 侧的存在性快照。 */
+export interface LogsSourceState {
+  readonly path: string
+  readonly kind: 'file' | 'directory' | 'missing'
+  readonly bytes?: number
+  readonly files?: number
+}
+
+/** 导出物 header 里每个来源的统计。 */
+export interface LogsSourceSummary {
+  readonly label: string
+  readonly path: string
+  readonly lines: number
+  readonly bytes: number
+  readonly firstAt?: string
+  readonly lastAt?: string
+  readonly truncated: boolean
+  readonly missing?: boolean
+}
+
+/** 采集器运行时统计；时间一律是北京时间 ISO 字符串。 */
+export interface LogsStats {
+  readonly file: string
+  readonly fileBytes: number
+  readonly level: LogLevelName
+  readonly maxBytes: number
+  readonly keep: number
+  readonly records: number
+  readonly dropped: number
+  readonly rotations: number
+  readonly writeFailures: number
+  readonly firstAt?: string
+  readonly lastAt?: string
+  readonly byName: Readonly<Record<string, number>>
+  readonly sources: readonly LogsSourceState[]
+}
+
+export interface LogsPreview {
+  readonly lines: readonly string[]
+  readonly bytes: number
+  readonly truncated: boolean
+  readonly fileBytes: number
+}
+
+export interface LogsExport {
+  readonly fileName: string
+  readonly text: string
+  readonly bytes: number
+  readonly truncated: boolean
+  readonly sources: readonly LogsSourceSummary[]
+}
+
+/** 浏览器可用的只读日志接口。 */
+export interface LogsPublicApi {
+  stats(): Promise<LogsStats>
+  preview(lines?: number): Promise<LogsPreview>
+  /** 先刷盘，再把主日志与配置的 sources 拼成单文件文本。 */
+  export(): Promise<LogsExport>
+}
+
+/** Host 服务：比浏览器多出本地路径与刷盘/释放句柄的能力。 */
+export interface LogsSettings extends LogsPublicApi {
+  readonly filePath: string
+  flush(): Promise<void>
+  dispose(): Promise<void>
+}