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

package/lib/features/logs/archive.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 诊断包（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 type { SettingsRoute } from '../../core/rpc-core.js';
+import { LOGS_ARCHIVE_ROUTE, type LogsSourceSummary } from './contract.js';
+import { type ExportOptions } from './export.js';
+/**
+ * 与 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;
+}
+/**
+ * 生成诊断包：单文件导出文本 + manifest + 额外来源原文。
+ * @param options - 来源定义与 header 元信息。
+ * @returns 归档字节、文件名、manifest 与整体 `truncated`。
+ */
+export declare function buildLogArchive(options: LogsArchiveOptions): Promise<LogsArchive>;
+/**
+ * 挂到 `/api` 载体上的精确 GET 路由。
+ *
+ * 不读任何请求参数、不重复鉴权（`/api` 前缀的信任与认证由载体负责）；每次请求现算归档，
+ * 因此刷盘与版本解析都在这里发生。
+ * @param options - 归档选项。
+ * @returns 交给 `connection.fetch.register` 的路由定义。
+ */
+export declare function createLogsArchiveRoute(options: LogsArchiveOptions): LogsArchiveRoute;

package/lib/features/logs/archive.js

@@ -0,0 +1,156 @@
+/**
+ * 诊断包（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 { 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, } from './contract.js';
+import { LOG_BLIND_SPOTS, loadLogExport, renderLogExport } from './export.js';
+import { byteLength, formatArchiveFileName, formatLogTimestamp } from './format.js';
+import { basename } from 'node:path';
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: false });
+/** 按 UTF-8 字节上限截断原文副本，并丢掉最后一个不完整行。 */
+function truncateToBytes(text, maxBytes) {
+    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) {
+    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 = [[LOGS_ARCHIVE_LOG, encoder.encode(rendered.text)]];
+    const entries = [{ name: LOGS_ARCHIVE_LOG, bytes: content[0][1].byteLength }];
+    const sources = [];
+    const seen = new Set();
+    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;
+        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 = {
+        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 = {
+        [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) {
+    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/lib/features/logs/card.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from 'react';
+import { type LogsPublicApi } from './contract.js';
+import type { FtshareSettingsShellContext } from '../../core/shell.js';
+/**
+ * 快照缺失时的占位文案。
+ *
+ * 失败后不能继续写「读取中…」：那会把一次已经结束的失败说成正在进行的读取，掩盖真正的
+ * 原因（例如宿主插件没有这个接口，重试永远不会成功）。
+ * @param failed - 本次读取是否已经失败。
+ * @returns 失败提示，或仍在读取的提示。
+ */
+export declare function statsPlaceholder(failed: boolean): string;
+/**
+ * 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 declare function registerLogsCard(ctx: FtshareSettingsShellContext): () => void;
+export declare function LogsSection({ api }: {
+    readonly api: LogsPublicApi;
+}): ReactNode;

package/lib/features/logs/card.js

@@ -0,0 +1,107 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+import { LOGS_ARCHIVE_ROUTE, LOGS_CARD_ID, LOGS_CARD_ORDER, LOGS_DEFAULT_PREVIEW_LINES, LOGS_MAX_PREVIEW_LINES, } 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 { 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) {
+    return failed ? '读取失败' : '读取中…';
+}
+function displayBytes(bytes) {
+    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, text) {
+    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) {
+    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() {
+    const api = createLogsClient(createSettingsTransport());
+    return () => _jsx(LogsSection, { api: api });
+}
+export function LogsSection({ api }) {
+    const [stats, setStats] = useState();
+    const [preview, setPreview] = useState();
+    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 _jsxs(_Fragment, { children: [_jsx("style", { children: LOGS_CARD_CSS }), _jsxs("section", { className: "ftshare-settings", "aria-label": "FT \u8FD0\u884C\u65E5\u5FD7", "aria-busy": busy, children: [_jsx("header", { children: _jsxs("div", { children: [_jsx("span", { className: "ftshare-eyebrow", children: "FTSHARE / LOGS" }), _jsx("h2", { children: "\u8FD0\u884C\u65E5\u5FD7" })] }) }), _jsxs("div", { className: "ftshare-card", children: [_jsx("h3", { children: "\u91C7\u96C6\u72B6\u6001" }), _jsxs("dl", { children: [_jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u65E5\u5FD7\u6587\u4EF6" }), _jsx("dd", { children: stats?.file ?? placeholder })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u8BB0\u5F55 / \u65F6\u95F4\u8303\u56F4" }), _jsxs("dd", { children: [stats === undefined ? placeholder : `${stats.records} 条`, stats?.firstAt !== undefined && `（${stats.firstAt} ~ ${stats.lastAt}）`] })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u6587\u4EF6\u5927\u5C0F / \u4E0A\u9650" }), _jsx("dd", { children: stats === undefined ? placeholder : `${displayBytes(stats.fileBytes)} / ${displayBytes(stats.maxBytes)}` })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u4E22\u5F03 / \u8F6E\u8F6C / \u5199\u5931\u8D25" }), _jsx("dd", { children: stats === undefined ? placeholder : `${stats.dropped} / ${stats.rotations} / ${stats.writeFailures}` })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u65E5\u5FD7\u7EA7\u522B" }), _jsxs("dd", { children: [stats?.level ?? placeholder, " "] })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u7EDF\u8BA1" }), _jsx("dd", { children: stats === undefined
+                                                    ? placeholder
+                                                    : Object.keys(stats.byName).length === 0
+                                                        ? '暂无'
+                                                        : Object.entries(stats.byName).map(([name, count]) => `${name}=${count}`).join('、') })] }), _jsxs("div", { className: "ftshare-result", children: [_jsx("dt", { children: "\u989D\u5916\u6765\u6E90" }), _jsx("dd", { children: stats === undefined
+                                                    ? placeholder
+                                                    : stats.sources.length === 0
+                                                        ? '暂无'
+                                                        : stats.sources.map(source => `${source.path}（${source.kind}${source.bytes === undefined ? '' : ` ${displayBytes(source.bytes)}`}）`).join('；') })] })] }), _jsxs("div", { className: "ftshare-actions", children: [_jsx("button", { className: "primary", type: "button", onClick: () => void doExport(), disabled: busy, children: "\u5BFC\u51FA\u65E5\u5FD7" }), _jsx("a", { className: "ftshare-download", href: LOGS_ARCHIVE_ROUTE, download: "", children: "\u5BFC\u51FA\u8BCA\u65AD\u5305" }), _jsx("button", { type: "button", onClick: () => void refresh(), disabled: busy, children: "\u5237\u65B0" }), _jsx("label", { htmlFor: "ftshare-log-lines", children: "\u9884\u89C8\u884C\u6570" }), _jsx("select", { id: "ftshare-log-lines", value: lines, onChange: e => setLines(Number(e.target.value)), disabled: busy, children: PREVIEW_CHOICES.map(choice => _jsx("option", { value: choice, children: choice }, choice)) })] }), busy && _jsx("p", { role: "status", children: "\u6B63\u5728\u5904\u7406\uFF0C\u8BF7\u7A0D\u5019\u2026" }), message && _jsx("p", { role: "status", children: message }), error && _jsx("p", { className: "ftshare-error", role: "alert", children: error })] }), _jsxs("div", { className: "ftshare-card", children: [_jsxs("h3", { children: ["\u6700\u8FD1\u65E5\u5FD7", preview?.truncated === true ? '（已截断）' : ''] }), preview === undefined
+                                ? _jsx("p", { children: error === '' ? '正在读取…' : '日志预览读取失败，见上方提示。' })
+                                : preview.lines.length === 0
+                                    ? _jsx("p", { children: "\u65E0" })
+                                    : _jsx("pre", { className: "ftshare-log-preview", children: preview.lines.join('\n') })] })] })] });
+}

package/lib/features/logs/client-api.d.ts

@@ -0,0 +1,4 @@
+import { type LogsPublicApi } from './contract.js';
+import { type ClientTransport } from '../../core/rpc-core.js';
+/** 浏览器适配器：只读，且不暴露本地路径以外的任何 Host 能力（刷盘与释放句柄）。 */
+export declare function createLogsClient(transport: ClientTransport): LogsPublicApi;

package/lib/features/logs/client-api.js

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

package/lib/features/logs/collector.d.ts

@@ -0,0 +1,91 @@
+/**
+ * FT 运行日志采集器（Host 侧，不依赖 cordis，便于单测）。
+ *
+ * 职责：接收 cordis exporter 的记录 → 节流合并 → 脱敏 → 追加 `$DSH_HOME/logs/ft/current.log`，
+ * 超限轮转、保留 `keep` 份；写失败 / 轮转 / 丢弃一律自报 stderr，绝不抛回业务插件。
+ */
+import { type LogLevelName } from './contract.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>>;
+}
+/** 常驻采集器；生命周期由调用方（cordis `ctx.effect`）负责关闭。 */
+export declare class FtLogCollector {
+    readonly filePath: string;
+    readonly threshold: number;
+    private readonly directory;
+    private readonly options;
+    private readonly now;
+    private readonly schedule;
+    private readonly report;
+    private readonly pending;
+    private readonly byName;
+    private chain;
+    private ready;
+    private cancelTimer;
+    private timerDeadline;
+    private bytes;
+    private records;
+    private dropped;
+    private rotations;
+    private writeFailures;
+    private firstTs;
+    private lastTs;
+    private cachedSecrets;
+    private secretsAt;
+    private closed;
+    constructor(options: CollectorOptions);
+    /** 接收一条 cordis 记录：同 key 在 10 秒窗口内合并为一行并累计重复次数。 */
+    append(record: CollectorRecord): void;
+    /** 注册时回填 cordis 内置缓冲里剩余的 `error`/`info`（`warn`/`debug` 已丢，不可恢复）。 */
+    backfill(records: readonly CollectorRecord[]): Promise<void>;
+    /** 把队列全部落盘（导出前调用），等待写入链结束。 */
+    flush(): Promise<void>;
+    /** 关闭句柄与队列；之后 `append` 变为空操作。 */
+    dispose(): Promise<void>;
+    stats(): CollectorSnapshot;
+    /** 当前已知密钥（带 TTL 缓存，避免每次写盘都解析凭据）。 */
+    private currentSecrets;
+    private armTimer;
+    private cancel;
+    /** 把窗口已过期的待写条目交给写入链（保持插入顺序）。 */
+    private sweep;
+    private dropOldest;
+    private enqueue;
+    private write;
+    private rotate;
+    /** 同一毫秒内可能连续轮转两次（小 maxBytes + 突发），文件名必须唯一，否则会互相覆盖。 */
+    private uniqueRotationPath;
+    /** 保留策略按修改时间（而不是文件名）排序：同一毫秒连转时的 `-N` 后缀不影响新旧判断。 */
+    private prune;
+}