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

package/src/features/api-key/service.ts

@@ -0,0 +1,157 @@
+import { type ApiKeySettings, type CredentialStatus, type ConfigureResult, type ValidationResult, normalizeApiKey, untested, FTSHARE_API_KEY_REF } from './contract.js'
+import type { FeatureLogger } from './logging.js'
+import { probeApiKey } from './probe.js'
+
+export interface CredentialStore {
+  resolve(): Promise<string | undefined>
+  describe(): Promise<CredentialStatus>
+  set(value: string): Promise<void>
+  clear(): Promise<void>
+}
+export type Validator = (key: string | undefined, signal: AbortSignal) => Promise<ValidationResult>
+
+/**
+ * One Host instance owns validation state; the DSH provider owns all secrets.
+ *
+ * `logger` is optional so a directly constructed instance (tests, embeddings)
+ * stays silent: the plugin entry passes `ctx.logger()` in through
+ * `createApiKeyModule`. Fields never carry the Key or any token value.
+ */
+export function createApiKeySettings(store: CredentialStore, validator?: Validator, logger?: FeatureLogger) {
+  // 默认校验器 = 真实探测：只有这条路径才需要把 logger 传进 probe 记请求级失败。
+  const validate: Validator = validator ?? ((key, signal) => probeApiKey(key, signal, fetch, Date.now(), logger))
+  let revision = 0
+  let fingerprint: string | undefined
+  let validation = untested()
+  let active: { revision: number; controller: AbortController; promise: Promise<ValidationResult> } | undefined
+  let writes: Promise<unknown> = Promise.resolve()
+  let reads: Promise<unknown> = Promise.resolve()
+  let disposed = false
+  const listeners = new Set<() => void>()
+  function invalidate() {
+    revision++
+    fingerprint = undefined
+    validation = untested()
+    active?.controller.abort()
+    active = undefined
+    for (const listener of listeners) {
+      try { listener() } catch { /* Observers cannot turn a committed write into a failure. */ }
+    }
+  }
+  function current(): Promise<string | undefined> {
+    const read = reads.then(async () => {
+      while (true) {
+        if (disposed) throw new Error('FTShare settings service is disposed')
+        const started = revision
+        const key = await store.resolve()
+        const hash = key === undefined ? 'absent' : Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key))), b => b.toString(16).padStart(2, '0')).join('')
+        if (started !== revision) continue
+        if (fingerprint !== undefined && fingerprint !== hash) invalidate()
+        fingerprint = hash
+        return key
+      }
+    })
+    reads = read.catch(() => {})
+    return read
+  }
+  function enqueue<T>(operation: () => Promise<T>): Promise<T> {
+    const promise = writes.then(() => {
+      if (disposed) throw new Error('FTShare settings service is disposed')
+      return operation()
+    })
+    writes = promise.catch(() => {})
+    return promise
+  }
+  async function write(value?: string) {
+    if (!(await store.describe()).writable) throw new Error('当前配置来源为只读')
+    const started = revision
+    if (value === undefined) await store.clear()
+    else await store.set(value)
+    // Also covers providers without update events.
+    if (started === revision) invalidate()
+  }
+  function testSnapshot(key: string | undefined, expectedRevision: number): Promise<ValidationResult> {
+    if (disposed || revision !== expectedRevision) return Promise.resolve(untested('superseded', '凭据已变化，请重新测试'))
+    if (active?.revision === revision) return active.promise.then(value => structuredClone(value))
+    const controller = new AbortController()
+    const run = { revision, controller, promise: Promise.resolve(untested()) }
+    run.promise = (async () => {
+      let result: ValidationResult
+      try { result = await validate(key, controller.signal) } catch {
+        logger?.warn('FTShare 验证服务异常', { stage: 'validate', code: 'validator_failed' })
+        result = { ...untested('not_run', '验证服务异常，请重试'), status: 'failed' }
+      }
+      try { if (!disposed) await current() } catch {
+        logger?.warn('FTShare 凭据不可确认', { stage: 'resolve', code: 'credential_unavailable' })
+        return { ...untested('not_run', '无法确认当前凭据，请重新测试'), status: 'failed' as const }
+      }
+      if (disposed || controller.signal.aborted || revision !== run.revision) return untested('superseded', '凭据已变化，旧测试结果已丢弃')
+      validation = structuredClone(result)
+      return structuredClone(result)
+    })().finally(() => { if (active === run) active = undefined })
+    active = run
+    return run.promise.then(value => structuredClone(value))
+  }
+  const api: ApiKeySettings = {
+    credentialRef: FTSHARE_API_KEY_REF,
+    async describe() {
+      while (true) {
+        const key = await current()
+        const started = revision
+        const { configured, writable, source } = await store.describe()
+        if (started !== revision) continue
+        const characters = Array.from(key ?? '')
+        // Short/invalid keys must not be exposed in full by the suffix preview.
+        const maskedValue = configured ? '••••••••' + (characters.length > 4 ? characters.slice(-4).join('') : '') : undefined
+        return { configured, writable, ...(source === undefined ? {} : { source }), ...(maskedValue === undefined ? {} : { maskedValue }), revision, validation: structuredClone(validation) }
+      }
+    },
+    resolve: current,
+    async set(input) { const value = normalizeApiKey(input); await enqueue(() => write(value)) },
+    async clear() { await enqueue(() => write()) },
+    async createEnvironment(base = {}) {
+      const env = { ...base }
+      delete env[FTSHARE_API_KEY_REF]
+      const key = await current()
+      if (key !== undefined) env[FTSHARE_API_KEY_REF] = key
+      return env
+    },
+    subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener) } },
+    async getValidationStatus() { await current(); return structuredClone(validation) },
+    async testConnection() {
+      await writes
+      const key = await current()
+      return testSnapshot(key, revision)
+    },
+    async configureAndTest(input): Promise<ConfigureResult> {
+      let value: string
+      try { value = normalizeApiKey(input) } catch {
+        return { save: { status: 'failed', code: 'invalid_input', message: 'API Key 格式不正确' }, validation: untested('not_run', '保存失败，未执行测试') }
+      }
+      const saved = await enqueue(async () => {
+        try {
+          if (!(await store.describe()).writable) return { code: 'read_only' as const }
+          await write(value)
+        } catch {
+          logger?.warn('FTShare API Key 保存失败', { code: 'save_failed' })
+          return { code: 'save_failed' as const }
+        }
+        // Reading/testing can fail after a committed save. Preserve that fact.
+        try {
+          const key = await current()
+          return { revision: key === value ? revision : -1, key }
+        } catch { return { unavailable: true } }
+      })
+      if ('code' in saved) return {
+        save: { status: 'failed', code: saved.code, message: saved.code === 'read_only' ? '当前配置来源为只读' : '保存失败，请重试' },
+        validation: untested('not_run', '保存失败，未执行测试'),
+      }
+      if ('unavailable' in saved) return { save: { status: 'saved', message: '已保存到 DSH 凭据存储' }, validation: untested('not_run', '已保存，但无法读取生效凭据，请重试') }
+      return { save: { status: 'saved', message: '已保存到 DSH 凭据存储' }, validation: await testSnapshot(saved.key, saved.revision) }
+    },
+  }
+  return {
+    api, invalidate,
+    dispose() { disposed = true; active?.controller.abort(); active = undefined; listeners.clear() },
+  }
+}

package/src/features/api-key/styles.ts

@@ -0,0 +1,24 @@
+/**
+ * The API Key card's own styles, rendered by the card component's `<style>`.
+ *
+ * A card owns everything past the section shell: the core declares the
+ * `--ftshare-*` tokens and the section container, never card internals.
+ * Every selector stays scoped under `.ftshare-settings`, so a card never
+ * styles another card's markup.
+ */
+export const API_KEY_CARD_CSS = `
+.ftshare-settings .ftshare-eyebrow { color:var(--ftshare-accent-on-surface); font-size:11px; letter-spacing:.12em; }
+.ftshare-settings .ftshare-card { padding:22px; background:var(--ftshare-panel); border:0.5px solid var(--ftshare-border); border-radius:var(--dsw-radius-xl); margin-top:16px; }
+.ftshare-settings label { display:block; font-weight:500; }
+.ftshare-settings input { width:100%; height:32px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 12px; background:var(--ftshare-input); color:inherit; font:inherit; }
+.ftshare-settings input::placeholder { color:var(--ftshare-muted); opacity:1; }
+.ftshare-settings .ftshare-actions { display:flex; flex-wrap:wrap; gap:10px; align-items:center; margin-top:16px; }
+.ftshare-settings button { min-height:36px; border:0.5px solid var(--ftshare-control); border-radius:var(--dsw-radius-md); padding:0 14px; font:inherit; background:transparent; color:inherit; cursor:pointer; }
+.ftshare-settings button.primary { background:var(--ftshare-accent); color:var(--ftshare-accent-ink); border-color:var(--ftshare-accent); font-weight:500; }
+.ftshare-settings button:disabled { opacity:.5; cursor:not-allowed; }
+.ftshare-settings dl { margin:0; }
+.ftshare-settings .ftshare-result { display:grid; grid-template-columns:130px 1fr; gap:12px; padding:10px 0; border-top:0.5px solid var(--ftshare-border); }
+.ftshare-settings dd { margin:0; overflow-wrap:anywhere; }
+.ftshare-settings .ftshare-error { color:var(--ftshare-error); }
+@media(max-width:540px) { .ftshare-settings .ftshare-card { padding:16px; } .ftshare-settings .ftshare-result { grid-template-columns:1fr; gap:4px; } }
+`

package/src/features/logs/archive.ts

@@ -0,0 +1,230 @@
+/**
+ * 诊断包（P2，规格 §9 / §12 决策 3）：把单文件导出与额外来源原文打成一个 zip。
+ *
+ * 归档结构与封顶语义：
+ *
+ * - `manifest.json`：生成时间、插件版本、运行时、`$DSH_HOME` 展示名、上限、`truncated`、
+ *   各来源统计（label/path/lines/bytes/firstAt/lastAt/missing/truncated）、四条覆盖盲区；
+ * - `ft-runtime.log`：与单文件导出**完全相同**的文本（复用 `loadLogExport` + `renderLogExport`）；
+ * - `sources/<n>-<basename>`：配置的额外来源文件原文，编号稳定、按路径去重；缺失来源只进 manifest。
+ *
+ * 封顶沿用规格 §9：单来源 2 MiB、合计 8 MiB、目录最多 20 个 `*.log`；归档以**未压缩字节**
+ * 计入同一个 8 MiB 预算（`ft-runtime.log` 先算，剩余额度再分给 `sources/*`），超限截断并在
+ * manifest 标 `truncated: true`。
+ *
+ * 本文件是 Host 半边（Node 文件系统 + `fflate`），不得被浏览器半边引用：卡片只用
+ * `./contract.js` 里的 `LOGS_ARCHIVE_ROUTE` 与 `<a download>`。
+ */
+
+import { zipSync } from 'fflate'
+import type { SettingsRoute } from '../../core/rpc-core.js'
+import {
+  LOGS_ARCHIVE_LOG,
+  LOGS_ARCHIVE_MANIFEST,
+  LOGS_ARCHIVE_ROUTE,
+  LOGS_ARCHIVE_SOURCE_DIR,
+  LOGS_EXPORT_MAX_BYTES,
+  LOGS_MAX_SOURCE_FILES,
+  LOGS_SOURCE_MAX_BYTES,
+  type LogsSourceSummary,
+} from './contract.js'
+import { LOG_BLIND_SPOTS, loadLogExport, renderLogExport, type ExportOptions } from './export.js'
+import { byteLength, formatArchiveFileName, formatLogTimestamp } from './format.js'
+import { basename } from 'node:path'
+
+/**
+ * 与 core 的 `SettingsRoute` 同形，只把 `path` 从「那一条 POST 路由」放宽到本 feature 的精确路径。
+ * core 因此不需要认识 `/logs.zip`（架构守护测试要求 core 无 feature 词汇）。
+ */
+export interface LogsArchiveRoute extends Omit<SettingsRoute, 'path'> {
+  readonly path: typeof LOGS_ARCHIVE_ROUTE
+}
+
+/** 载体侧的注册面：与 core 的 `HostFetch` 同形，收本 feature 自己的路由。 */
+export interface LogsArchiveRouteRegistry {
+  register(route: LogsArchiveRoute): () => Promise<void>
+}
+
+/** 归档选项：来源定义与 header 元信息（`filePath`/`sources`/`homeDisplay`/`environment`）。 */
+export interface LogsArchiveOptions extends Omit<ExportOptions, 'pluginVersion' | 'now'> {
+  /** 插件版本；允许传 promise，`readPluginVersion()` 的结果可以直接塞进来。 */
+  readonly pluginVersion: string | Promise<string>
+  /** 读文件前刷盘（采集器的 10 秒合并窗口）；省略时直接读当前文件。 */
+  readonly flush?: () => Promise<void>
+  readonly now?: () => number
+}
+
+/** manifest 里的一个来源：规格 §9 的统计字段，外加它落在归档里的条目名。 */
+export interface LogsArchiveManifestSource extends LogsSourceSummary {
+  /** 归档内的条目路径；缺失或未纳入时不存在。 */
+  readonly entry?: string
+}
+
+export interface LogsArchiveEntry {
+  readonly name: string
+  readonly bytes: number
+}
+
+export interface LogsArchiveManifest {
+  readonly generatedAt: string
+  readonly pluginVersion: string
+  readonly runtime: string
+  /** `$DSH_HOME` 的展示名（`~/.dsh` 或 `$DSH_HOME`），不写绝对路径。 */
+  readonly home: string
+  readonly limits: {
+    readonly sourceBytes: number
+    readonly archiveBytes: number
+    readonly maxSourceFiles: number
+  }
+  /** 未压缩字节是否触到任一上限。 */
+  readonly truncated: boolean
+  /** 归档内除 `manifest.json` 自身之外的条目（它无法记录自己的字节数）。 */
+  readonly entries: readonly LogsArchiveEntry[]
+  readonly sources: readonly LogsArchiveManifestSource[]
+  readonly blindSpots: readonly string[]
+}
+
+export interface LogsArchive {
+  readonly fileName: string
+  readonly bytes: Uint8Array
+  readonly truncated: boolean
+  readonly manifest: LogsArchiveManifest
+}
+
+const encoder = new TextEncoder()
+const decoder = new TextDecoder('utf-8', { fatal: false })
+
+/** 按 UTF-8 字节上限截断原文副本，并丢掉最后一个不完整行。 */
+function truncateToBytes(text: string, maxBytes: number): string {
+  let slice = decoder.decode(encoder.encode(text).subarray(0, Math.max(0, maxBytes)))
+  // 截断点可能落在多字节字符中间，去掉 UTF-8 替换字符。
+  while (slice.endsWith('\uFFFD')) slice = slice.slice(0, -1)
+  const lastBreak = slice.lastIndexOf('\n')
+  return lastBreak === -1 ? slice : slice.slice(0, lastBreak + 1)
+}
+
+/**
+ * 生成诊断包：单文件导出文本 + manifest + 额外来源原文。
+ * @param options - 来源定义与 header 元信息。
+ * @returns 归档字节、文件名、manifest 与整体 `truncated`。
+ */
+export async function buildLogArchive(options: LogsArchiveOptions): Promise<LogsArchive> {
+  await options.flush?.()
+  const pluginVersion = await options.pluginVersion
+  const generatedAt = (options.now ?? Date.now)()
+  const { loaded, truncated: logTruncated } = await loadLogExport(options)
+  const rendered = renderLogExport({
+    loaded,
+    truncated: logTruncated,
+    generatedAt,
+    homeDisplay: options.homeDisplay,
+    pluginVersion,
+    environment: options.environment,
+  })
+
+  let truncated = logTruncated
+  // 未压缩字节共用同一个 8 MiB 预算：ft-runtime.log 先占，剩下的才分给原文副本。
+  let remaining = LOGS_EXPORT_MAX_BYTES - rendered.bytes
+  const content: [string, Uint8Array][] = [[LOGS_ARCHIVE_LOG, encoder.encode(rendered.text)]]
+  const entries: LogsArchiveEntry[] = [{ name: LOGS_ARCHIVE_LOG, bytes: content[0][1].byteLength }]
+  const sources: LogsArchiveManifestSource[] = []
+  const seen = new Set<string>()
+  let index = 0
+
+  for (const [position, item] of loaded.entries()) {
+    const summary = item.summary
+    // 第一条固定是主日志：它的内容已经完整进了 ft-runtime.log。
+    if (position === 0) {
+      sources.push({ ...summary, entry: LOGS_ARCHIVE_LOG })
+      continue
+    }
+    if (summary.missing === true) {
+      sources.push({ ...summary })
+      continue
+    }
+    let entry: string | undefined
+    let sourceTruncated = summary.truncated
+    if (seen.has(summary.path)) {
+      // 同一路径被配置两次：归档内只留一份原文，编号仍然稳定。
+    } else if (remaining <= 0) {
+      truncated = true
+      sourceTruncated = true
+    } else {
+      const budget = Math.min(LOGS_SOURCE_MAX_BYTES, remaining)
+      let text = item.content
+      if (byteLength(text) > budget) {
+        text = truncateToBytes(text, budget)
+        truncated = true
+        sourceTruncated = true
+        // 一份来源被切短即表示预算耗尽：剩下的零头不再喂给后续来源，条目数保持确定。
+        remaining = 0
+      } else {
+        remaining -= byteLength(text)
+      }
+      if (text !== '' || item.content === '') {
+        index += 1
+        entry = `${LOGS_ARCHIVE_SOURCE_DIR}${index}-${basename(summary.path)}`
+        seen.add(summary.path)
+        const bytes = encoder.encode(text)
+        content.push([entry, bytes])
+        entries.push({ name: entry, bytes: bytes.byteLength })
+      }
+    }
+    sources.push({ ...summary, truncated: sourceTruncated, ...(entry === undefined ? {} : { entry }) })
+  }
+
+  const manifest: LogsArchiveManifest = {
+    generatedAt: formatLogTimestamp(generatedAt),
+    pluginVersion: `@dsh-ft/dsh-fft-settings ${pluginVersion}`,
+    runtime: options.environment ?? process.version,
+    home: options.homeDisplay,
+    limits: {
+      sourceBytes: LOGS_SOURCE_MAX_BYTES,
+      archiveBytes: LOGS_EXPORT_MAX_BYTES,
+      maxSourceFiles: LOGS_MAX_SOURCE_FILES,
+    },
+    truncated,
+    entries,
+    sources,
+    blindSpots: [...LOG_BLIND_SPOTS],
+  }
+
+  // manifest 排第一，其余条目按 ft-runtime.log → sources/<n>-… 的顺序写入（对象键保持插入序）。
+  const files: Record<string, Uint8Array> = {
+    [LOGS_ARCHIVE_MANIFEST]: encoder.encode(JSON.stringify(manifest, null, 2)),
+  }
+  for (const [name, bytes] of content) files[name] = bytes
+
+  return { fileName: formatArchiveFileName(generatedAt), bytes: zipSync(files), truncated, manifest }
+}
+
+/**
+ * 挂到 `/api` 载体上的精确 GET 路由。
+ *
+ * 不读任何请求参数、不重复鉴权（`/api` 前缀的信任与认证由载体负责）；每次请求现算归档，
+ * 因此刷盘与版本解析都在这里发生。
+ * @param options - 归档选项。
+ * @returns 交给 `connection.fetch.register` 的路由定义。
+ */
+export function createLogsArchiveRoute(options: LogsArchiveOptions): LogsArchiveRoute {
+  return {
+    path: LOGS_ARCHIVE_ROUTE,
+    methods: ['GET'],
+    // GET 不读体；buffered 只是与载体约定「本路由不消费请求体」。
+    requestBody: 'buffered',
+    fetch: async () => {
+      const archive = await buildLogArchive(options)
+      // 复制成独立 ArrayBuffer 承载的视图：`Response` 的 BodyInit 不接受 ArrayBufferLike 视图。
+      const body = new Uint8Array(archive.bytes)
+      return new Response(body, {
+        status: 200,
+        headers: {
+          'content-type': 'application/zip',
+          'content-disposition': `attachment; filename="${archive.fileName}"`,
+          'cache-control': 'no-store',
+          'content-length': String(body.byteLength),
+        },
+      })
+    },
+  }
+}

package/src/features/logs/card.tsx

@@ -0,0 +1,169 @@
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import {
+  LOGS_ARCHIVE_ROUTE,
+  LOGS_CARD_ID,
+  LOGS_CARD_ORDER,
+  LOGS_DEFAULT_PREVIEW_LINES,
+  LOGS_MAX_PREVIEW_LINES,
+  type LogsPreview,
+  type LogsPublicApi,
+  type LogsStats,
+} from './contract.js'
+import { createLogsClient } from './client-api.js'
+import { createSettingsTransport } from '../../core/client-transport.js'
+import { FTSHARE_SETTINGS_CARD_SLOT } from '../../core/contract.js'
+import type { FtshareSettingsShellContext } from '../../core/shell.js'
+import { LOGS_CARD_CSS } from './styles.js'
+
+/** 预览行数候选：上限由 Host 侧校验兜底。 */
+const PREVIEW_CHOICES = [50, LOGS_DEFAULT_PREVIEW_LINES, LOGS_MAX_PREVIEW_LINES]
+
+/**
+ * 快照缺失时的占位文案。
+ *
+ * 失败后不能继续写「读取中…」：那会把一次已经结束的失败说成正在进行的读取，掩盖真正的
+ * 原因（例如宿主插件没有这个接口，重试永远不会成功）。
+ * @param failed - 本次读取是否已经失败。
+ * @returns 失败提示，或仍在读取的提示。
+ */
+export function statsPlaceholder(failed: boolean): string {
+  return failed ? '读取失败' : '读取中…'
+}
+
+function displayBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`
+  return `${(bytes / 1024 / 1024).toFixed(2)} MiB`
+}
+
+/** 把文本包成 Blob，用 a[download] 触发下载（Web 与桌面同一套）。 */
+function downloadText(fileName: string, text: string): void {
+  const url = URL.createObjectURL(new Blob([text], { type: 'text/plain;charset=utf-8' }))
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = fileName
+  anchor.rel = 'noopener'
+  document.body.appendChild(anchor)
+  anchor.click()
+  anchor.remove()
+  setTimeout(() => URL.revokeObjectURL(url), 0)
+}
+
+/**
+ * Contribute the built-in runtime-log card through the same slot a third-party
+ * card uses. Nothing about it is privileged: same declaration, same options.
+ * @param ctx - client context carrying the renderer's slots service.
+ * @returns idempotent disposer for the card registration.
+ */
+export function registerLogsCard(ctx: FtshareSettingsShellContext): () => void {
+  return ctx.slots.inject(FTSHARE_SETTINGS_CARD_SLOT, () => ctx.slots.register(
+    { name: FTSHARE_SETTINGS_CARD_SLOT, id: LOGS_CARD_ID, order: LOGS_CARD_ORDER },
+    createLogsCard(),
+  ))
+}
+
+/** Bind the card's adapter; the component only reads through it. */
+function createLogsCard(): () => ReactNode {
+  const api = createLogsClient(createSettingsTransport())
+  return () => <LogsSection api={api} />
+}
+
+export function LogsSection({ api }: { readonly api: LogsPublicApi }): ReactNode {
+  const [stats, setStats] = useState<LogsStats>()
+  const [preview, setPreview] = useState<LogsPreview>()
+  const [lines, setLines] = useState(LOGS_DEFAULT_PREVIEW_LINES)
+  const [busy, setBusy] = useState(false)
+  const [message, setMessage] = useState('')
+  const [error, setError] = useState('')
+  /** 读取已失败且还没有任何快照时，每个字段都必须说出来，而不是假装还在读。 */
+  const placeholder = statsPlaceholder(error !== '')
+
+  const refresh = useCallback(async () => {
+    setBusy(true)
+    setError('')
+    try {
+      setStats(await api.stats())
+      setPreview(await api.preview(lines))
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : '读取日志状态失败')
+    } finally {
+      setBusy(false)
+    }
+  }, [api, lines])
+
+  useEffect(() => { void refresh() }, [refresh])
+
+  const doExport = async () => {
+    setBusy(true)
+    setError('')
+    setMessage('')
+    try {
+      const result = await api.export()
+      downloadText(result.fileName, result.text)
+      setMessage(`已导出 ${result.fileName}（${displayBytes(result.bytes)}${result.truncated ? '，已达体积上限并截断' : ''}）`)
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : '导出日志失败')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return <>
+    <style>{LOGS_CARD_CSS}</style>
+    <section className="ftshare-settings" aria-label="FT 运行日志" aria-busy={busy}>
+    <header><div><span className="ftshare-eyebrow">FTSHARE / LOGS</span><h2>运行日志</h2></div></header>
+    <div className="ftshare-card">
+      <h3>采集状态</h3>
+      <dl>
+        <div className="ftshare-result"><dt>日志文件</dt><dd>{stats?.file ?? placeholder}</dd></div>
+        <div className="ftshare-result"><dt>记录 / 时间范围</dt><dd>
+          {stats === undefined ? placeholder : `${stats.records} 条`}
+          {stats?.firstAt !== undefined && `（${stats.firstAt} ~ ${stats.lastAt}）`}
+        </dd></div>
+        <div className="ftshare-result"><dt>文件大小 / 上限</dt><dd>
+          {stats === undefined ? placeholder : `${displayBytes(stats.fileBytes)} / ${displayBytes(stats.maxBytes)}`}
+        </dd></div>
+        <div className="ftshare-result"><dt>丢弃 / 轮转 / 写失败</dt><dd>
+          {stats === undefined ? placeholder : `${stats.dropped} / ${stats.rotations} / ${stats.writeFailures}`}
+        </dd></div>
+        <div className="ftshare-result"><dt>日志级别</dt><dd>{stats?.level ?? placeholder} </dd></div>
+        <div className="ftshare-result"><dt>统计</dt><dd>
+          {stats === undefined
+            ? placeholder
+            : Object.keys(stats.byName).length === 0
+              ? '暂无'
+              : Object.entries(stats.byName).map(([name, count]) => `${name}=${count}`).join('、')}
+        </dd></div>
+        <div className="ftshare-result"><dt>额外来源</dt><dd>
+          {stats === undefined
+            ? placeholder
+            : stats.sources.length === 0
+              ? '暂无'
+              : stats.sources.map(source => `${source.path}（${source.kind}${source.bytes === undefined ? '' : ` ${displayBytes(source.bytes)}`}）`).join('；')}
+        </dd></div>
+      </dl>
+      <div className="ftshare-actions">
+        <button className="primary" type="button" onClick={() => void doExport()} disabled={busy}>导出日志</button>
+        {/* 同源 GET，浏览器自带凭据：直接指向路由，不需要 fetch/Blob。 */}
+        <a className="ftshare-download" href={LOGS_ARCHIVE_ROUTE} download="">导出诊断包</a>
+        <button type="button" onClick={() => void refresh()} disabled={busy}>刷新</button>
+        <label htmlFor="ftshare-log-lines">预览行数</label>
+        <select id="ftshare-log-lines" value={lines} onChange={e => setLines(Number(e.target.value))} disabled={busy}>
+          {PREVIEW_CHOICES.map(choice => <option key={choice} value={choice}>{choice}</option>)}
+        </select>
+      </div>
+      {busy && <p role="status">正在处理，请稍候…</p>}
+      {message && <p role="status">{message}</p>}
+      {error && <p className="ftshare-error" role="alert">{error}</p>}
+    </div>
+    <div className="ftshare-card">
+      <h3>最近日志{preview?.truncated === true ? '（已截断）' : ''}</h3>
+      {preview === undefined
+        ? <p>{error === '' ? '正在读取…' : '日志预览读取失败，见上方提示。'}</p>
+        : preview.lines.length === 0
+          ? <p>无</p>
+          : <pre className="ftshare-log-preview">{preview.lines.join('\n')}</pre>}
+    </div>
+    </section>
+  </>
+}

package/src/features/logs/client-api.ts

@@ -0,0 +1,20 @@
+import {
+  LOGS_DEFAULT_PREVIEW_LINES,
+  type LogsExport,
+  type LogsMethod,
+  type LogsPreview,
+  type LogsPublicApi,
+  type LogsStats,
+} from './contract.js'
+import { callSettingsRpc, type ClientTransport } from '../../core/rpc-core.js'
+
+/** 浏览器适配器：只读，且不暴露本地路径以外的任何 Host 能力（刷盘与释放句柄）。 */
+export function createLogsClient(transport: ClientTransport): LogsPublicApi {
+  const call = <T>(method: LogsMethod, payload: unknown = {}): Promise<T> =>
+    callSettingsRpc<T>(transport, 'logs', method, payload)
+  return {
+    stats: () => call<LogsStats>('stats'),
+    preview: (lines = LOGS_DEFAULT_PREVIEW_LINES) => call<LogsPreview>('preview', { lines }),
+    export: () => call<LogsExport>('export'),
+  }
+}