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

package/lib/features/logs/collector.js

@@ -0,0 +1,258 @@
+/**
+ * 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, } from './contract.js';
+import { byteLength, formatLogLine, formatLogMessage, formatRotationFileName, redactSecrets, truncateLine } from './format.js';
+const defaultSchedule = (run, delayMs) => {
+    const timer = setTimeout(run, delayMs);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+};
+const defaultSelfReport = (message) => {
+    try {
+        process.stderr.write(`[ft-logs] ${message}\n`);
+    }
+    catch {
+        // 连 stderr 都写不进去时只能放弃自报，绝不能因此影响业务插件。
+    }
+};
+/** 常驻采集器；生命周期由调用方（cordis `ctx.effect`）负责关闭。 */
+export class FtLogCollector {
+    filePath;
+    threshold;
+    directory;
+    options;
+    now;
+    schedule;
+    report;
+    pending = new Map();
+    byName = new Map();
+    chain = Promise.resolve();
+    ready;
+    cancelTimer;
+    timerDeadline = 0;
+    bytes = 0;
+    records = 0;
+    dropped = 0;
+    rotations = 0;
+    writeFailures = 0;
+    firstTs;
+    lastTs;
+    cachedSecrets = [];
+    secretsAt = 0;
+    closed = false;
+    constructor(options) {
+        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) {
+        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) {
+        for (const record of records)
+            this.append(record);
+        await this.flush();
+    }
+    /** 把队列全部落盘（导出前调用），等待写入链结束。 */
+    async flush() {
+        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() {
+        await this.flush();
+        this.closed = true;
+        this.cancel();
+    }
+    stats() {
+        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 缓存，避免每次写盘都解析凭据）。 */
+    async currentSecrets() {
+        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;
+    }
+    armTimer(at) {
+        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));
+    }
+    cancel() {
+        this.cancelTimer?.();
+        this.cancelTimer = undefined;
+        this.timerDeadline = 0;
+    }
+    /** 把窗口已过期的待写条目交给写入链（保持插入顺序）。 */
+    sweep(at) {
+        for (const [key, entry] of [...this.pending]) {
+            if (at - entry.firstTs < LOGS_THROTTLE_WINDOW_MS)
+                continue;
+            this.pending.delete(key);
+            this.enqueue(entry);
+        }
+    }
+    dropOldest() {
+        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} 条`);
+    }
+    enqueue(entry) {
+        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} 次`);
+            }
+        });
+    }
+    async write(line, entry) {
+        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);
+    }
+    async rotate() {
+        const target = await this.uniqueRotationPath();
+        try {
+            await rename(this.filePath, target);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT')
+                throw error;
+        }
+        this.bytes = 0;
+        this.rotations += 1;
+        this.report(`日志轮转：${target}（保留最近 ${this.options.keep} 份）`);
+        await this.prune();
+    }
+    /** 同一毫秒内可能连续轮转两次（小 maxBytes + 突发），文件名必须唯一，否则会互相覆盖。 */
+    async uniqueRotationPath() {
+        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` 后缀不影响新旧判断。 */
+    async prune() {
+        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/lib/features/logs/config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `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 { 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 declare const DEFAULT_LOGS_CONFIG: LogsConfig;
+/**
+ * `logs` 这一片的原生 Schemastery schema（`src/index.ts` 的顶层 `Config` 组合它）。
+ *
+ * 两点不可省：
+ * 1. `.default()` 必须带默认值对象 —— 无参写法在 Schemastery 里不生效；
+ * 2. 无配置行时 cordis 传的是 `{}` 而不是 `undefined`，靠 `validate` 补齐全部默认值
+ *    （`validate(undefined)` 与 `validate({})` 结果一致）。因此不要在 `apply` 的参数默认值上
+ *    兜底，见 `index.ts`。
+ */
+export declare const logsConfigSchema: z<Schemastery.ObjectS<NoInfer<{
+    level: z<"warn" | "debug", "warn" | "debug", "defined">;
+    maxBytes: z<number, number, "defined">;
+    keep: z<number, number, "defined">;
+    sources: z<string[], string[], "defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    level: z<"warn" | "debug", "warn" | "debug", "defined">;
+    maxBytes: z<number, number, "defined">;
+    keep: z<number, number, "defined">;
+    sources: z<string[], string[], "defined">;
+}>>, "defined">;
+/**
+ * 内部兜底解析：非法组合不抛错，回落到默认值/夹紧；`level` 写错才报 issue
+ * （写错级别等于静默丢日志）。入参是整个插件配置，只取 `input.logs` 这一片；
+ * 只在绕过 cordis 校验时使用。
+ */
+export declare function parseLogsConfig(input: unknown): {
+    value: LogsConfig;
+} | {
+    issues: {
+        message: string;
+    }[];
+};
+/** 取值：解析结果永远是完整配置，调用方不再做空值判断。 */
+export declare function resolveLogsConfig(input: unknown): LogsConfig;

package/lib/features/logs/config.js

@@ -0,0 +1,97 @@
+/**
+ * `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 } from './contract.js';
+export const DEFAULT_LOGS_CONFIG = {
+    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() {
+    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) => typeof value === 'object' && value !== null && !Array.isArray(value);
+function clampNumber(value, fallback, min, max) {
+    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) {
+    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.includes(level)) {
+        return { issues: [{ message: `logs.level 必须是 ${LOGS_CONFIG_LEVELS.join(' / ')} 之一` }] };
+    }
+    const sources = Array.isArray(raw.sources)
+        ? raw.sources.filter((item) => typeof item === 'string' && item.trim() !== '')
+        : [];
+    return {
+        value: {
+            level: level,
+            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) {
+    const parsed = parseLogsConfig(input);
+    if ('issues' in parsed) {
+        // 兜底路径不阻断挂载：回到默认级别，避免“插件起不来 = 一行日志都没有”。
+        // （真正生效的配置由原生 Schema 校验，写错会在这里之前就让插件不挂载。）
+        return createDefaultLogsConfig();
+    }
+    return parsed.value;
+}

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

@@ -0,0 +1,130 @@
+/**
+ * `logs` 命名空间的共享契约：只有常量与类型，浏览器半边可以安全导入。
+ *
+ * 采集器（Host 常驻）与导出器（设置页）通过文件解耦；本文件是两者唯一的共同语言。
+ */
+/**
+ * 卡片在 `ftshare.settings.card` 槽位里的 id 与 order。
+ *
+ * 归 feature 所有（与业务契约同一份来源）：卡片组件与浏览器侧的守卫测试都读它，
+ * order 20 排在 API Key 卡（10）之后。
+ */
+export declare const LOGS_CARD_ID = "logs";
+export declare const LOGS_CARD_ORDER = 20;
+/** 显式登记的 RPC 方法；未登记的方法一律 `not_found`。 */
+export declare const LOGS_METHODS: readonly ["stats", "preview", "export"];
+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 declare const LOG_LEVEL_THRESHOLD: Record<LogLevelName, number>;
+export declare const LOG_LEVEL_NAMES: readonly ["warn", "info", "debug", "error"];
+/**
+ * 可配置的级别（规格 §10）。
+ *
+ * 不提供 `info` 档：`levels` 是接收上限，`info`(1) 会把 `warn`(2) 一起丢掉，与规格 §6
+ * 「失败日志不低于 warn」冲突；`error`(0) 同样不成立（等于只剩 error）。允许值收敛为
+ * `warn | debug`，档位越界由 Schemastery 直接拒绝（插件不挂载），不做静默夹紧。
+ */
+export declare const LOGS_CONFIG_LEVELS: readonly ["warn", "debug"];
+export type LogsConfigLevel = typeof LOGS_CONFIG_LEVELS[number];
+/** 落盘位置：`$DSH_HOME/logs/ft/`。 */
+export declare const LOGS_DIR_SEGMENTS: readonly ["logs", "ft"];
+export declare const LOGS_CURRENT_FILE = "current.log";
+export declare const LOGS_ROTATED_PREFIX = "ft-";
+export declare const LOGS_FILE_SUFFIX = ".log";
+export declare const LOGS_LINE_MAX_BYTES: number;
+export declare const LOGS_TRUNCATED_MARK = "...[\u5DF2\u622A\u65AD]";
+export declare const LOGS_REPEAT_FIELD = "\u91CD\u590D\u6B21\u6570";
+export declare const LOGS_THROTTLE_WINDOW_MS = 10000;
+export declare const LOGS_MAX_PENDING_KEYS = 2000;
+export declare const LOGS_MAX_FIELD_LENGTH = 2000;
+export declare const LOGS_MAX_FIELD_DEPTH = 3;
+export declare const LOGS_DEFAULT_PREVIEW_LINES = 80;
+export declare const LOGS_MAX_PREVIEW_LINES = 200;
+export declare const LOGS_PREVIEW_MAX_BYTES: number;
+/** 导出体积上限（规格 §9）：单来源 2 MiB、合计 8 MiB、目录最多 20 个 `*.log`。 */
+export declare const LOGS_SOURCE_MAX_BYTES: number;
+export declare const LOGS_EXPORT_MAX_BYTES: number;
+export declare const LOGS_MAX_SOURCE_FILES = 20;
+export declare const LOGS_EXPORT_FILE_PREFIX = "ft-runtime-";
+export declare const LOGS_SECRET_TTL_MS = 5000;
+/**
+ * 诊断包路由（规格 §9 / §12 决策 3）：`/api` 载体上的第二条精确路由，归 `logs` feature 所有。
+ *
+ * 卡片用 `<a download>` 直接指向它：浏览器同源 GET 自带凭据，不需要 fetch/Blob，
+ * `/api` 前缀的鉴权由载体负责，本 feature 不重复鉴权、也不读任何请求参数。
+ * 它随 owner fiber 释放（`ctx.effect` + `register` 返回的 disposer）。
+ */
+export declare const LOGS_ARCHIVE_ROUTE: "/api/ftshare-settings/logs.zip";
+/** 归档内固定条目名（`manifest.json` 永远排第一）。 */
+export declare const LOGS_ARCHIVE_MANIFEST = "manifest.json";
+export declare const LOGS_ARCHIVE_LOG = "ft-runtime.log";
+/** 额外来源原文的目录前缀：`sources/<n>-<basename>`。 */
+export declare const LOGS_ARCHIVE_SOURCE_DIR = "sources/";
+/** 导出 header 里的来源段落分隔标记。 */
+export declare 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>;
+}

package/lib/features/logs/contract.js

@@ -0,0 +1,67 @@
+/**
+ * `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'];
+/**
+ * 配置级别 → cordis `levels.default` 数值。
+ *
+ * cordis 的 `levels` 是**接收上限**而不是下限：`targetLevel < level` 才丢弃。
+ * 因此 `warn`(2) 收 error/info/warn，`debug`(3) 收全部，`info`(1) 会把 `warn` 丢掉。
+ */
+export const LOG_LEVEL_THRESHOLD = { error: 0, info: 1, warn: 2, debug: 3 };
+export const LOG_LEVEL_NAMES = ['warn', 'info', 'debug', 'error'];
+/**
+ * 可配置的级别（规格 §10）。
+ *
+ * 不提供 `info` 档：`levels` 是接收上限，`info`(1) 会把 `warn`(2) 一起丢掉，与规格 §6
+ * 「失败日志不低于 warn」冲突；`error`(0) 同样不成立（等于只剩 error）。允许值收敛为
+ * `warn | debug`，档位越界由 Schemastery 直接拒绝（插件不挂载），不做静默夹紧。
+ */
+export const LOGS_CONFIG_LEVELS = ['warn', 'debug'];
+/** 落盘位置：`$DSH_HOME/logs/ft/`。 */
+export const LOGS_DIR_SEGMENTS = ['logs', 'ft'];
+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';
+/** 归档内固定条目名（`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 = '=====';