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

package/src/features/logs/export.ts

@@ -0,0 +1,274 @@
+/**
+ * 导出物组装（Host 侧）：读主日志与配置的 sources，拼成单个 `.log` 文本。
+ *
+ * 体积上限按规格 §9：单来源 2 MiB、合计 8 MiB、目录最多 20 个 `*.log`；
+ * 超限按“保留最新”截断，并在 header 标注 `truncated=true`。
+ */
+
+import { open, readdir, readFile, stat } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import {
+  LOGS_EXPORT_MAX_BYTES,
+  LOGS_FILE_SUFFIX,
+  LOGS_MAX_SOURCE_FILES,
+  LOGS_SECTION_RULE,
+  LOGS_SOURCE_MAX_BYTES,
+  type LogsSourceSummary,
+  type LogsSourceState,
+} from './contract.js'
+import { byteLength, formatDownloadFileName, formatLogTimestamp } from './format.js'
+import { resolveSourcePath } from './home.js'
+
+const TIMESTAMP_PREFIX = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}[+-]\d{2}:\d{2})\s/
+
+/**
+ * 单文件导出选项：来源定义（与诊断包共用的 {@link LoadExportOptions}）加上 header 元信息。
+ */
+export interface ExportOptions extends LoadExportOptions {
+  readonly homeDisplay: string
+  readonly pluginVersion: string
+  readonly now?: () => number
+  readonly environment?: string
+}
+
+export interface ExportResult {
+  readonly text: string
+  readonly fileName: string
+  readonly bytes: number
+  readonly truncated: boolean
+  readonly summaries: readonly LogsSourceSummary[]
+}
+
+/** 读来源只用到这两项；诊断包复用同一加载过程。 */
+export interface LoadExportOptions {
+  /** 主日志文件（`current.log`）的绝对路径。 */
+  readonly filePath: string
+  /** 配置里的额外来源（原样，可能带 `~`）。 */
+  readonly sources: readonly string[]
+}
+
+/** 一次封装后的来源内容；`content` 已按上限截断。 */
+export interface LoadedSource {
+  readonly summary: LogsSourceSummary
+  readonly content: string
+}
+
+/** 加载结果：来源清单加正文，以及整体是否被截断。 */
+export interface LoadedExport {
+  readonly loaded: readonly LoadedSource[]
+  readonly truncated: boolean
+}
+
+/** 渲染导出文本所需的元信息（时间戳由调用方给定，保证同一份导出只有一个生成时间）。 */
+export interface RenderExportOptions {
+  readonly loaded: readonly LoadedSource[]
+  readonly truncated: boolean
+  readonly generatedAt: number
+  readonly homeDisplay: string
+  readonly pluginVersion: string
+  readonly environment?: string
+}
+
+/** 尾读一个文件，最多 `maxBytes` 字节；超出时丢掉首个不完整行。 */
+export async function readTail(path: string, maxBytes: number): Promise<{ text: string; truncated: boolean; size: number }> {
+  const size = (await stat(path)).size
+  if (size <= maxBytes) return { text: await readFile(path, 'utf8'), truncated: false, size }
+  const handle = await open(path, 'r')
+  try {
+    const buffer = new Uint8Array(maxBytes)
+    await handle.read(buffer, 0, maxBytes, size - maxBytes)
+    const text = new TextDecoder('utf-8', { fatal: false }).decode(buffer)
+    const firstBreak = text.indexOf('\n')
+    return { text: firstBreak === -1 ? text : text.slice(firstBreak + 1), truncated: true, size }
+  } finally {
+    await handle.close()
+  }
+}
+
+/** 读文件尾部最近的 N 行；同时受字节上限约束。 */
+export async function readTailLines(path: string, lines: number, maxBytes: number): Promise<{ lines: string[]; bytes: number; truncated: boolean; fileBytes: number }> {
+  const { text, truncated, size } = await readTail(path, maxBytes)
+  const all = text.split('\n').filter(line => line.length > 0)
+  const kept = all.slice(Math.max(0, all.length - lines))
+  return {
+    lines: kept,
+    bytes: kept.reduce((total, line) => total + byteLength(line) + 1, 0),
+    truncated: truncated || kept.length < all.length,
+    fileBytes: size,
+  }
+}
+
+/** 统计正文的行数与时间范围（时间戳取行首北京时间）。 */
+export function summarizeContent(text: string): { lines: number; firstAt?: string; lastAt?: string } {
+  let lines = 0
+  let firstAt: string | undefined
+  let lastAt: string | undefined
+  for (const line of text.split('\n')) {
+    if (line.length === 0) continue
+    lines += 1
+    const match = TIMESTAMP_PREFIX.exec(line)
+    if (match === null) continue
+    firstAt ??= match[1]
+    lastAt = match[1]
+  }
+  return { lines, firstAt, lastAt }
+}
+
+/** 目录展开成 `*.log` 文件（按修改时间倒序，最多 20 个）。 */
+async function expandDirectory(directory: string): Promise<string[]> {
+  const names = (await readdir(directory)).filter(name => name.endsWith(LOGS_FILE_SUFFIX))
+  const stamped = await Promise.all(names.map(async name => {
+    const path = join(directory, name)
+    try {
+      return { path, mtime: (await stat(path)).mtimeMs }
+    } catch {
+      return { path, mtime: 0 }
+    }
+  }))
+  stamped.sort((left, right) => right.mtime - left.mtime)
+  return stamped.slice(0, LOGS_MAX_SOURCE_FILES).map(item => item.path)
+}
+
+/** 判断配置的来源当前形态；目录会被展开成文件清单（最多 20 个）。 */
+export async function resolveSource(rawPath: string): Promise<{ state: LogsSourceState; files: readonly string[] }> {
+  const path = resolveSourcePath(rawPath)
+  try {
+    const info = await stat(path)
+    if (info.isDirectory()) {
+      const files = await expandDirectory(path)
+      return { state: { path, kind: 'directory', files: files.length }, files }
+    }
+    return { state: { path, kind: 'file', bytes: info.size }, files: [path] }
+  } catch {
+    return { state: { path, kind: 'missing' }, files: [] }
+  }
+}
+
+/** 各来源的存在性快照，供设置页展示。 */
+export async function describeSources(sources: readonly string[]): Promise<LogsSourceState[]> {
+  return await Promise.all(sources.map(async source => (await resolveSource(source)).state))
+}
+
+/** 导出物 header 与 manifest 共用的四条覆盖盲区（规格 §5）。 */
+export const LOG_BLIND_SPOTS = [
+  '采集器挂载前的极短窗口（毫秒级，只有模块加载期日志）：只回填了 cordis 缓冲里残留的 error/info，warn/debug 不可恢复。',
+  '没有桌面壳 log bridge 的环境（纯 dsh web）：MCP/Python 子进程的 stderr 只在启动它的终端里，不含在导出物中。',
+  '渲染进程（浏览器）日志：DSH 未提供回传通道，不含。',
+  '不走 logger 的失败：直接 console.*、只通过事件或只体现在返回值的失败，logger 通道看不到。',
+]
+
+/**
+ * 按规格 §9 的封顶语义读取主日志与额外来源：单来源 2 MiB、合计 8 MiB、目录最多 20 个 `*.log`。
+ *
+ * 单文件导出与诊断包共用这一步，两者的 `truncated` 语义因此完全一致。
+ * @param options - 主日志路径与配置的额外来源。
+ * @returns 每个来源的统计与正文，以及整体是否截断。
+ */
+export async function loadLogExport(options: LoadExportOptions): Promise<LoadedExport> {
+  const primaryLabel = 'FT 插件日志（本进程 cordis）'
+  const loaded: LoadedSource[] = []
+  let truncated = false
+  let remaining = LOGS_EXPORT_MAX_BYTES
+
+  const push = async (label: string, path: string, missing = false): Promise<void> => {
+    if (missing) {
+      loaded.push({
+        summary: { label, path, lines: 0, bytes: 0, truncated: false, missing: true },
+        content: '',
+      })
+      return
+    }
+    let tail: { text: string; truncated: boolean }
+    try {
+      tail = await readTail(path, Math.min(LOGS_SOURCE_MAX_BYTES, Math.max(0, remaining)))
+    } catch {
+      // 文件不存在（例如本次进程还没写过日志）不是错误：按空来源处理。
+      loaded.push({ summary: { label, path, lines: 0, bytes: 0, truncated: false, missing: true }, content: '' })
+      return
+    }
+    const { text, truncated: cut } = tail
+    const size = byteLength(text)
+    const { lines, firstAt, lastAt } = summarizeContent(text)
+    if (cut) truncated = true
+    remaining -= size
+    loaded.push({
+      summary: { label, path, lines, bytes: size, firstAt, lastAt, truncated: cut },
+      content: text,
+    })
+  }
+
+  await push(primaryLabel, options.filePath)
+  for (const source of options.sources) {
+    const { state, files } = await resolveSource(source)
+    if (remaining <= 0) {
+      truncated = true
+      loaded.push({
+        summary: { label: `额外来源（未纳入）`, path: state.path, lines: 0, bytes: 0, truncated: true },
+        content: '',
+      })
+      continue
+    }
+    if (state.kind === 'missing') {
+      await push('额外来源（文件不存在）', state.path, true)
+      continue
+    }
+    if (state.kind === 'directory' && files.length === 0) {
+      await push('额外来源（目录下没有 *.log）', state.path, true)
+      continue
+    }
+    for (const file of files) await push(`额外来源${files.length > 1 ? `（目录 ${basename(state.path)}）` : ''}`, file)
+  }
+  return { loaded, truncated }
+}
+
+/** 拼装导出文本：header（来源清单、条数、时间范围、truncated、盲区）+ 来源段落。 */
+export function renderLogExport(options: RenderExportOptions): { text: string; bytes: number } {
+  const header = [
+    '# ===== FT 运行日志 =====',
+    `# 生成时间：${formatLogTimestamp(options.generatedAt)}`,
+    `# 插件版本：@dsh-ft/dsh-fft-settings ${options.pluginVersion}`,
+    `# 运行时：${options.environment ?? process.version}`,
+    `# 日志目录：${options.homeDisplay}/logs/ft`,
+    `# 导出上限：单来源 ${LOGS_SOURCE_MAX_BYTES / 1024 / 1024} MiB、合计 ${LOGS_EXPORT_MAX_BYTES / 1024 / 1024} MiB、目录最多 ${LOGS_MAX_SOURCE_FILES} 个 *${LOGS_FILE_SUFFIX}`,
+    `# truncated=${options.truncated}`,
+    '# 来源：',
+    ...options.loaded.map((item, index) => {
+      const s = item.summary
+      if (s.missing === true) return `#   ${index + 1}. ${s.label} ${s.path}（缺失）`
+      const range = s.firstAt === undefined ? '时间范围=空' : `时间范围=${s.firstAt} ~ ${s.lastAt}`
+      return `#   ${index + 1}. ${s.label} ${s.path} 条数=${s.lines} 字节=${s.bytes} ${range}${s.truncated ? ' truncated=true' : ''}`
+    }),
+    '# 覆盖盲区：',
+    LOG_BLIND_SPOTS.map(line => `#   - ${line}`).join('\n'),
+    '',
+  ].join('\n')
+
+  const body = options.loaded
+    .filter(item => item.summary.missing !== true)
+    .map(item => `${LOGS_SECTION_RULE} ${item.summary.label}: ${item.summary.path} ${LOGS_SECTION_RULE}\n${item.content.replace(/\n?$/, '\n')}`)
+    .join('\n')
+
+  const text = `${header}${body}`
+  return { text, bytes: byteLength(text) }
+}
+
+/** 单文件导出：加载 + 渲染，附文件名与各来源统计。 */
+export async function buildLogExport(options: ExportOptions): Promise<ExportResult> {
+  const generatedAt = (options.now ?? Date.now)()
+  const { loaded, truncated } = await loadLogExport(options)
+  const { text, bytes } = renderLogExport({
+    loaded,
+    truncated,
+    generatedAt,
+    homeDisplay: options.homeDisplay,
+    pluginVersion: options.pluginVersion,
+    environment: options.environment,
+  })
+  return {
+    text,
+    fileName: formatDownloadFileName(generatedAt),
+    bytes,
+    truncated,
+    summaries: loaded.map(item => item.summary),
+  }
+}

package/src/features/logs/format.ts

@@ -0,0 +1,188 @@
+/**
+ * 日志行格式化与脱敏（纯函数，无 Node 依赖，浏览器半边也可导入）。
+ *
+ * 行格式（规格 §8）：
+ * `<ISO8601+08:00> <LEVEL> <plugin-name> <message> <k=v …>`，单行上限 8 KiB。
+ */
+
+import {
+  LOGS_EXPORT_FILE_PREFIX,
+  LOGS_LINE_MAX_BYTES,
+  LOGS_MAX_FIELD_DEPTH,
+  LOGS_MAX_FIELD_LENGTH,
+  LOGS_ROTATED_PREFIX,
+  LOGS_TRUNCATED_MARK,
+  type LogLevelName,
+} from './contract.js'
+
+const SHANGHAI = new Intl.DateTimeFormat('en-CA', {
+  timeZone: 'Asia/Shanghai',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hourCycle: 'h23',
+})
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: false })
+
+/** 规格固定写 +08:00，不跟随宿主机时区。 */
+function shanghaiParts(ts: number): Record<string, string> {
+  const parts: Record<string, string> = {}
+  for (const { type, value } of SHANGHAI.formatToParts(new Date(ts))) parts[type] = value
+  return parts
+}
+
+function millis(ts: number): string {
+  return String(new Date(ts).getMilliseconds()).padStart(3, '0')
+}
+
+/** 行首时间戳：`2026-10-12T15:04:05.123+08:00`。 */
+export function formatLogTimestamp(ts: number): string {
+  const p = shanghaiParts(ts)
+  return `${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}.${millis(ts)}+08:00`
+}
+
+/** 下载文件名时间戳：`yyyyMMdd-HHmmss`。 */
+export function formatCompactStamp(ts: number): string {
+  const p = shanghaiParts(ts)
+  return `${p.year}${p.month}${p.day}-${p.hour}${p.minute}${p.second}`
+}
+
+/** 轮转文件名时间戳：`2026-10-12T15-04-05-123+0800`（去掉文件系统不友好的 `:`/`.`）。 */
+export function formatRotationStamp(ts: number): string {
+  const p = shanghaiParts(ts)
+  return `${p.year}-${p.month}-${p.day}T${p.hour}-${p.minute}-${p.second}-${millis(ts)}+0800`
+}
+
+/** 导出物文件名：`ft-runtime-<yyyyMMdd-HHmmss>.log`。 */
+export function formatDownloadFileName(ts: number): string {
+  return `${LOGS_EXPORT_FILE_PREFIX}${formatCompactStamp(ts)}.log`
+}
+
+/** 诊断包文件名：`ft-runtime-<yyyyMMdd-HHmmss>.zip`（与单文件导出同一时间戳口径）。 */
+export function formatArchiveFileName(ts: number): string {
+  return `${LOGS_EXPORT_FILE_PREFIX}${formatCompactStamp(ts)}.zip`
+}
+
+/** 轮转文件名：`ft-<ISO时间戳>.log`（与当前文件名 `current.log` 不冲突）。 */
+export function formatRotationFileName(ts: number): string {
+  return `${LOGS_ROTATED_PREFIX}${formatRotationStamp(ts)}.log`
+}
+
+/** 文本 UTF-8 字节数（不依赖 Buffer，浏览器可用）。 */
+export function byteLength(text: string): number {
+  return encoder.encode(text).length
+}
+
+/** 按 UTF-8 字节截断单行，并在上限内补 `...[已截断]`。 */
+export function truncateLine(line: string, maxBytes = LOGS_LINE_MAX_BYTES): string {
+  if (byteLength(line) <= maxBytes) return line
+  const budget = Math.max(0, maxBytes - byteLength(LOGS_TRUNCATED_MARK))
+  let text = decoder.decode(encoder.encode(line).subarray(0, budget))
+  // 截断点可能落在多字节字符中间，去掉 UTF-8 替换字符。
+  while (text.endsWith('\uFFFD')) text = text.slice(0, -1)
+  return text + LOGS_TRUNCATED_MARK
+}
+
+/** 把可能的多行文本压成单行（换行转义），保持「一条记录一行」。 */
+export function singleLine(text: string): string {
+  return text.replace(/\r\n|\r|\n/g, '\\n')
+}
+
+function clip(value: string): string {
+  return value.length > LOGS_MAX_FIELD_LENGTH ? `${value.slice(0, LOGS_MAX_FIELD_LENGTH)}…` : value
+}
+
+/** 把任意值渲染成短、稳定、可读的文本；键按字典序排列以便节流合并可比。 */
+export function renderValue(value: unknown, depth = 0): string {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  switch (typeof value) {
+    case 'string': return clip(value)
+    case 'number':
+    case 'boolean':
+    case 'bigint': return String(value)
+    case 'symbol': return clip(value.toString())
+    case 'function': return `[Function ${value.name || 'anonymous'}]`
+    default: break
+  }
+  // 到这里只剩对象；Error 取 message，避免整段堆栈（堆栈由 Logger 侧的字符串参数提供）。
+  if (value instanceof Error) return clip(value.message || value.name)
+  if (depth >= LOGS_MAX_FIELD_DEPTH) return '[…]'
+  if (Array.isArray(value)) return clip(value.map(item => renderValue(item, depth + 1)).join(','))
+  const entries: string[] = []
+  for (const key of Object.keys(value as object).sort()) {
+    entries.push(`${key}=${renderValue((value as Record<string, unknown>)[key], depth + 1)}`)
+  }
+  return clip(entries.join(' '))
+}
+
+const PLACEHOLDER = /%([a-zA-Z%])/g
+
+/**
+ * 渲染一条记录的正文，语义对齐 cordis `Logger.format`：
+ * 首参是 Error 时取 message，首参非字符串时当作字段对象；`%s/%d/%i/%f/%o/%O/%c/%%` 生效，
+ * 对象参数统一渲染为 `k=v`（而不是 JSON），且结果恒为单行。
+ */
+export function formatLogMessage(args: readonly unknown[]): string {
+  const rest = [...args]
+  if (rest[0] instanceof Error) {
+    rest[0] = rest[0].message || rest[0].name
+    rest.unshift('%s')
+  } else if (typeof rest[0] !== 'string') {
+    rest.unshift('%o')
+  }
+  let format = String(rest.shift())
+  format = format.replace(PLACEHOLDER, (match, char: string) => {
+    if (match === '%%') return '%'
+    if (!'sdifoOcC'.includes(char)) return match
+    const value = rest.shift()
+    switch (char) {
+      case 's': case 'c': return String(value ?? '')
+      case 'C': return String(value ?? '')
+      case 'd': case 'i': return String(Math.trunc(Number(value)))
+      case 'f': return String(Number(value))
+      default: return renderValue(value)
+    }
+  })
+  for (const arg of rest) {
+    format += typeof arg === 'object' && arg !== null ? ` ${renderValue(arg)}` : ` ${String(arg)}`
+  }
+  return singleLine(format)
+}
+
+interface RedactionRule { readonly pattern: RegExp; readonly replacement: string }
+
+/**
+ * 脱敏规则：`Bearer`、`Authorization:`、`Cookie:`、`sk-` 形态、长 hex、`*_KEY=*` 形态。
+ * 命中即整段打码，宁可多打不可漏。
+ */
+const REDACTION_RULES: readonly RedactionRule[] = [
+  { pattern: /(bearer\s+)[A-Za-z0-9._~+/=-]{6,}/gi, replacement: '$1***' },
+  // 只吃掉「可选 scheme + 凭据」这一段，后面的结构化字段仍保留可读性。
+  { pattern: /((?:proxy-)?authorization\s*[:=]\s*)(?:\S+\s+)?\S+/gi, replacement: '$1***' },
+  { pattern: /((?:set-)?cookie\s*[:=]\s*)[^\n]*/gi, replacement: '$1***' },
+  { pattern: /sk-[A-Za-z0-9_-]{6,}/g, replacement: 'sk-***' },
+  { pattern: /\b[0-9a-fA-F]{32,}\b/g, replacement: '***' },
+  { pattern: /([A-Za-z0-9_-]*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)[A-Za-z0-9_-]*\s*[:=]\s*)[^\s,;'"]+/gi, replacement: '$1***' },
+]
+
+/** 当前 FTShare Key 等已知密钥的精确值替换（长度过短的值不参与，避免误伤普通文本）。 */
+export function redactSecrets(text: string, secrets: readonly string[] = []): string {
+  let output = text
+  for (const secret of secrets) {
+    if (secret.length < 6) continue
+    output = output.split(secret).join('***')
+  }
+  for (const rule of REDACTION_RULES) output = output.replace(rule.pattern, rule.replacement)
+  return output
+}
+
+/** 组装一行：`<时间> <LEVEL> <name> <正文>`（`WARN` 之类按 5 字符对齐）。 */
+export function formatLogLine(record: { ts: number; type: LogLevelName; name: string; args: readonly unknown[] }): string {
+  return `${formatLogTimestamp(record.ts)} ${record.type.toUpperCase().padEnd(5)} ${record.name} ${formatLogMessage(record.args)}`
+}

package/src/features/logs/home.ts

@@ -0,0 +1,43 @@
+/**
+ * `$DSH_HOME` 解析（Host 侧）。
+ *
+ * 与 `@deepseek-ai/dsh-home-paths` 的 `resolveDshHome` 语义一致：显式配置 → `$DSH_HOME` →
+ * `~/.dsh`。此处自己实现，避免为一个纯路径函数新增运行时依赖与锁文件改动。
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, join, normalize, resolve } from 'node:path'
+import { LOGS_DIR_SEGMENTS } from './contract.js'
+
+export const DSH_HOME_ENV = 'DSH_HOME'
+export const DSH_HOME_DIR_NAME = '.dsh'
+
+/** 解析 DSH 根目录；空白 `$DSH_HOME` 视为未设置，`~` 前缀按官方语义展开。 */
+export function resolveDshHome(env: Readonly<Record<string, string | undefined>> = process.env): string {
+  const configured = env[DSH_HOME_ENV]?.trim()
+  if (configured) return resolve(expandHomePath(configured))
+  return join(homedir(), DSH_HOME_DIR_NAME)
+}
+
+/** 面向用户的展示形式：默认目录写 `~/.dsh`，自定义目录写 `$DSH_HOME`。 */
+export function displayDshHome(home: string): string {
+  return normalize(home) === normalize(join(homedir(), DSH_HOME_DIR_NAME)) ? '~/.dsh' : '$DSH_HOME'
+}
+
+/** 展开 `~`、`~/`、`~\` 前缀；不做其他 shell 展开。 */
+export function expandHomePath(value: string, home = homedir()): string {
+  if (value === '~') return home
+  if (value.startsWith('~/') || value.startsWith('~\\')) return join(home, value.slice(2))
+  return value
+}
+
+/** 解析配置里的来源路径为绝对路径（相对路径按当前工作目录）。 */
+export function resolveSourcePath(value: string, home = homedir()): string {
+  const expanded = expandHomePath(value, home)
+  return isAbsolute(expanded) ? normalize(expanded) : resolve(expanded)
+}
+
+/** 日志目录：`$DSH_HOME/logs/ft`。 */
+export function logsDirectory(home = resolveDshHome()): string {
+  return join(home, ...LOGS_DIR_SEGMENTS)
+}

package/src/features/logs/host.ts

@@ -0,0 +1,153 @@
+/**
+ * `logs` 命名空间 Host 半边：常驻采集器 + 导出器。
+ *
+ * 采集器在 `create()` 里**无条件启动**（`apply()` 期注册即执行，与设置页是否渲染无关）；
+ * exporter 由 cordis 绑定当前 fiber，另用 `ctx.effect` 明确关闭文件句柄与队列。
+ *
+ * 工厂化：dev 的接缝里 `create(ctx)` 不再收配置，模块由 `apply()` 用一个闭包把
+ * 已解析的 `logs` 配置带进来（`createLogsModule(logsConfig)`）。这样采集器仍然在
+ * 注册期、而不是等到设置页打开才启动。
+ */
+
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { FTSHARE_API_KEY_REF } from '../api-key/contract.js'
+import { defineSettingsModule, type SettingsModule } from '../../core/module-registry.js'
+import { createLogsArchiveRoute, type LogsArchiveRouteRegistry } from './archive.js'
+import { FtLogCollector } from './collector.js'
+import {
+  LOGS_DEFAULT_PREVIEW_LINES,
+  LOGS_MAX_PREVIEW_LINES,
+  LOGS_PREVIEW_MAX_BYTES,
+  type LogsPreview,
+  type LogsSettings,
+} from './contract.js'
+import type { LogsConfig } from './config.js'
+import { buildLogExport, describeSources, readTailLines } from './export.js'
+import { formatLogTimestamp } from './format.js'
+import { displayDshHome, logsDirectory, resolveDshHome } from './home.js'
+import { createLogsRpcMethods } from './rpc.js'
+
+/** 从本包 `package.json` 读版本；读不到时退回 `unknown`，不影响导出。 */
+async function readPluginVersion(): Promise<string> {
+  try {
+    const url = new URL('../../../package.json', import.meta.url)
+    const { readFile } = await import('node:fs/promises')
+    const parsed = JSON.parse(await readFile(url, 'utf8')) as { version?: unknown }
+    return typeof parsed.version === 'string' ? parsed.version : 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+/**
+ * 运行时描述串：header 与 manifest 共用一个口径。
+ * @returns 形如 `node v22.19.0 darwin arm64`。
+ */
+function runtimeDescription(): string {
+  return `node ${process.version} ${process.platform} ${process.arch}`
+}
+
+/**
+ * 构建 `logs` 模块：把已解析的配置闭包进 `create`。
+ * @param config - 本 feature 的 `logs` 配置（`resolveLogsConfig` 的输出，永远完整）。
+ * @returns 可交给 `ctx.ftshareSettings.modules.register` 的模块。
+ */
+export function createLogsModule(config: LogsConfig): SettingsModule<'logs', LogsSettings> {
+  return defineSettingsModule<'logs', LogsSettings>({
+    namespace: 'logs',
+    inject: ['credentials'],
+    create(ctx) {
+      const home = resolveDshHome()
+      const directory = logsDirectory(home)
+      const collector = new FtLogCollector({
+        directory,
+        level: config.level,
+        maxBytes: config.maxBytes,
+        keep: config.keep,
+        // 当前 FTShare Key 的精确值替换：取不到就退化为纯模式脱敏。
+        secrets: async () => {
+          const ref = credentialRef(FTSHARE_API_KEY_REF)
+          const resolved = await ctx.credentials.resolve(ref)
+          return resolved?.value === undefined ? [] : [resolved.value]
+        },
+      })
+
+      const version = readPluginVersion()
+      const service: LogsSettings = {
+        filePath: collector.filePath,
+        flush: () => collector.flush(),
+        dispose: () => collector.dispose(),
+        stats: async () => {
+          const snapshot = collector.stats()
+          return {
+            file: snapshot.filePath,
+            fileBytes: snapshot.fileBytes,
+            level: config.level,
+            maxBytes: config.maxBytes,
+            keep: config.keep,
+            records: snapshot.records,
+            dropped: snapshot.dropped,
+            rotations: snapshot.rotations,
+            writeFailures: snapshot.writeFailures,
+            firstAt: snapshot.firstTs === undefined ? undefined : formatLogTimestamp(snapshot.firstTs),
+            lastAt: snapshot.lastTs === undefined ? undefined : formatLogTimestamp(snapshot.lastTs),
+            byName: snapshot.byName,
+            sources: await describeSources(config.sources),
+          }
+        },
+        preview: async (lines = LOGS_DEFAULT_PREVIEW_LINES): Promise<LogsPreview> => {
+          await collector.flush()
+          const wanted = Math.min(LOGS_MAX_PREVIEW_LINES, Math.max(1, Math.trunc(lines)))
+          try {
+            const tail = await readTailLines(collector.filePath, wanted, LOGS_PREVIEW_MAX_BYTES)
+            return { lines: tail.lines, bytes: tail.bytes, truncated: tail.truncated, fileBytes: tail.fileBytes }
+          } catch {
+            // 还没有任何日志时不是错误：返回空预览。
+            return { lines: [], bytes: 0, truncated: false, fileBytes: 0 }
+          }
+        },
+        export: async () => {
+          await collector.flush()
+          const result = await buildLogExport({
+            filePath: collector.filePath,
+            sources: config.sources,
+            homeDisplay: displayDshHome(home),
+            pluginVersion: await version,
+            environment: runtimeDescription(),
+          })
+          return { fileName: result.fileName, text: result.text, bytes: result.bytes, truncated: result.truncated, sources: result.summaries }
+        },
+      }
+
+      // 诊断包由本 feature 自己挂路由（core 不认识 /logs.zip）：与插件入口同一条惯用法，
+      // register 返回的 disposer 交给 scoped.effect，owner fiber 释放时路由随之撤销。
+      ctx.inject(['connection'], scoped => {
+        const connection = scoped.get('connection') as { fetch: LogsArchiveRouteRegistry }
+        scoped.effect(() => connection.fetch.register(createLogsArchiveRoute({
+          filePath: collector.filePath,
+          sources: config.sources,
+          homeDisplay: displayDshHome(home),
+          pluginVersion: version,
+          environment: runtimeDescription(),
+          flush: () => collector.flush(),
+        })), 'ftshare-settings: /logs.zip route')
+      })
+
+      const disposeExporter = ctx.logger.exporter({
+        // levels 是接收上限：warn=2 收 error/info/warn，debug=3 全收。
+        levels: { default: collector.threshold },
+        export: message => collector.append(message),
+      })
+      ctx.effect(() => () => {
+        disposeExporter()
+        void collector.dispose()
+      }, 'ftshare-settings: FT 日志采集器')
+
+      // 回填内置缓冲里残留的 error/info（warn/debug 已被默认门槛丢弃，不可恢复）。
+      const buffered = ctx.logger.buffer.filter(message => message.type === 'error' || message.type === 'info')
+      void collector.backfill(buffered)
+
+      return { service, rpcMethods: createLogsRpcMethods(service) }
+    },
+  })
+}

package/src/features/logs/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Host half of the `logs` feature: the entry a host assembly imports.
+ *
+ * Like every feature directory, this file is the host entry, `./contract.js`
+ * its shared contract, and `./card.js` the browser entry browser code imports
+ * directly instead of going through here (a browser half must never pull the
+ * collector, the file system or the config schema).
+ */
+export * from './contract.js'
+export { buildLogArchive, createLogsArchiveRoute, type LogsArchive, type LogsArchiveManifest, type LogsArchiveOptions, type LogsArchiveRoute } from './archive.js'
+export { createLogsModule } from './host.js'
+export { createLogsRpcMethods } from './rpc.js'