@bolloon/bolloon-agent 0.3.52 → 0.4.2

package/dist/cron/cron-parser.js

@@ -0,0 +1,142 @@
+/**
+ * cron-parser.ts — cron 表达式 / 间隔解析 + 下次运行时间计算
+ *
+ * 借鉴 Hermes agent cron/scheduler.py 的调度心智:
+ *   - 支持标准 5 段 cron ("0 8 * * *") 与人类可读间隔 ("every 30m", "1h", "30s")
+ *   - 纯函数, 无 IO, 可单测: parseSchedule(schedule, from) → 下次触发 Date
+ *   - schedule 为空 / 解析失败 → 返回 null (调用方决定不调度或报错)
+ */
+/** "every 30m" / "every 1h" / "30s" / "1h" / "90s" → 毫秒; 其它返回 null */
+function _parseIntervalMs(raw) {
+    const m = raw.toLowerCase().trim().match(/^every\s+(\d+)\s*(s|m|h|d)?$|^(\d+)\s*(s|m|h|d)$/);
+    if (!m)
+        return null;
+    const num = Number(m[1] ?? m[3]);
+    const unit = (m[2] ?? m[4]) || 'm';
+    const mult = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+    return num * mult[unit];
+}
+/** 把 5 段 cron 拆成字段集合. 支持 *, 数字, 逗号, 范围, 步进 (仅分钟/小时/月/周日). */
+function _parseCronFields(expr) {
+    const parts = expr.trim().split(/\s+/);
+    if (parts.length !== 5)
+        return null;
+    const parse = (field, lo, hi) => {
+        const set = new Set();
+        for (const seg of field.split(',')) {
+            if (seg === '*') {
+                for (let v = lo; v <= hi; v++)
+                    set.add(v);
+                continue;
+            }
+            let step = 1;
+            let range = seg;
+            if (seg.includes('/')) {
+                const [r, s] = seg.split('/');
+                range = r;
+                step = Number(s) || 1;
+            }
+            let start = lo, end = hi;
+            if (range === '*') {
+                start = lo;
+                end = hi;
+            }
+            else if (range.includes('-')) {
+                const [a, b] = range.split('-');
+                start = Number(a);
+                end = Number(b);
+            }
+            else {
+                start = end = Number(range);
+            }
+            if (Number.isNaN(start) || Number.isNaN(end) || Number.isNaN(step))
+                return null;
+            for (let v = start; v <= end; v += step)
+                set.add(v);
+        }
+        return set;
+    };
+    const min = parse(parts[0], 0, 59);
+    const hour = parse(parts[1], 0, 23);
+    const dom = parse(parts[2], 1, 31);
+    const mon = parse(parts[3], 1, 12);
+    const dow = parse(parts[4], 0, 6);
+    if (!min || !hour || !dom || !mon || !dow)
+        return null;
+    return { min, hour, dom, mon, dow };
+}
+function _matchesCron(d, f) {
+    const domMatch = f.dom.has(d.getDate());
+    const dowMatch = f.dow.has(d.getDay());
+    // 经典 cron 语义: dom 与 dow 都受限时用 OR, 否则各自 AND
+    const domRestricted = !f.dom.has(31) && f.dom.size < 31;
+    const dowRestricted = f.dow.size < 7;
+    const dayOk = domRestricted && dowRestricted ? domMatch || dowMatch : domMatch && dowMatch;
+    return (dayOk &&
+        f.mon.has(d.getMonth() + 1) &&
+        f.hour.has(d.getHours()) &&
+        f.min.has(d.getMinutes()));
+}
+/**
+ * 解析 schedule 并计算下次触发时间.
+ * @param schedule "0 8 * * *" / "every 30m" / "1h" / "30s"
+ * @param from 基准时间 (默认 now)
+ * @returns ParsedSchedule 或 null (无法解析 / 未来 1 年内无匹配)
+ */
+export function parseSchedule(schedule, from = new Date()) {
+    const raw = (schedule || '').trim();
+    if (!raw)
+        return null;
+    // 间隔形式 (最快路径)
+    const intervalMs = _parseIntervalMs(raw);
+    if (intervalMs != null && intervalMs > 0) {
+        return { kind: 'interval', intervalMs, next: new Date(from.getTime() + intervalMs) };
+    }
+    // 5 段 cron: 从 from 起逐分钟扫描, 找下一个匹配 (上限 1 年避免死循环)
+    const fields = _parseCronFields(raw);
+    if (!fields)
+        return null;
+    const cursor = new Date(from);
+    cursor.setSeconds(0, 0);
+    cursor.setMinutes(cursor.getMinutes() + 1); // 严格 "下一次", 不含当前分
+    const capMs = from.getTime() + 366 * 86_400_000;
+    while (cursor.getTime() < capMs) {
+        if (_matchesCron(cursor, fields)) {
+            return { kind: 'cron', expr: raw, next: cursor, fields };
+        }
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return null;
+}
+/**
+ * 刷新一次调度: 给定 schedule 与上次触发, 返回本次应跑的触发点.
+ *   间隔型 → 以 lastRunAt 为基准叠加; 无 lastRunAt (首次) → 立即 due (返回 now).
+ *   cron 型 → 从 max(lastRunAt, now) 起找匹配; 上次触发已过期 → 立即 due.
+ */
+export function nextAfter(schedule, lastRunAt, now = new Date()) {
+    const raw = (schedule || '').trim();
+    if (!raw)
+        return null;
+    const intervalMs = _parseIntervalMs(raw);
+    if (intervalMs != null && intervalMs > 0) {
+        if (!lastRunAt)
+            return now; // 首次: 立即触发
+        return new Date(lastRunAt.getTime() + intervalMs);
+    }
+    // cron 型: 依托上次触发后的下一次, 与"当前墙钟"比较
+    const fields = _parseCronFields(raw);
+    if (!fields)
+        return null;
+    const base = lastRunAt && lastRunAt > now ? new Date(lastRunAt) : new Date(now);
+    base.setSeconds(0, 0);
+    let cursor = new Date(base);
+    if (lastRunAt)
+        cursor.setMinutes(cursor.getMinutes() + 1); // 严格晚于上次触发
+    const capMs = base.getTime() + 366 * 86_400_000;
+    while (cursor.getTime() < capMs) {
+        if (_matchesCron(cursor, fields))
+            return cursor;
+        cursor.setMinutes(cursor.getMinutes() + 1);
+    }
+    return null;
+}

package/dist/cron/jobs-store.js

@@ -0,0 +1,96 @@
+/**
+ * jobs-store.ts — 定时任务 (schedule jobs) 持久化
+ *
+ * 借鉴 Hermes agent cron/scheduler.py 心智:
+ *   - 每条 job 有: id / name / schedule (cron 或 every N) / prompt (执行体) / enabled
+ *   - 记录 lastRunAt / runCount, 调度器 tick 时找出 due 的 job 执行
+ *   - 落盘 ~/.bolloon/cron-jobs.json, 进程内互斥链序列化 + 临时文件原子写
+ *   - 不建数据库, 不引入外部调度系统 —— 单文件 + 内存互斥
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+function getJobsPath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'cron-jobs.json');
+}
+let jobsLock = Promise.resolve();
+function withLock(fn) {
+    const run = jobsLock.then(fn);
+    jobsLock = run.then(() => undefined, () => undefined);
+    return run;
+}
+async function readAll(home) {
+    try {
+        const raw = await fs.readFile(getJobsPath(home), 'utf-8');
+        const p = JSON.parse(raw);
+        if (p?.version === 1 && Array.isArray(p.jobs))
+            return p;
+        return { version: 1, jobs: [] };
+    }
+    catch {
+        return { version: 1, jobs: [] };
+    }
+}
+async function writeAll(file, home) {
+    const p = getJobsPath(home);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(file, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+}
+export async function addJob(input, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const job = {
+            id: crypto.randomUUID(),
+            name: input.name,
+            schedule: input.schedule,
+            prompt: input.prompt,
+            enabled: true,
+            createdAt: new Date().toISOString(),
+            runCount: 0,
+        };
+        file.jobs.push(job);
+        await writeAll(file, home);
+        return job;
+    });
+}
+export async function listJobs(home = os.homedir()) {
+    return withLock(async () => (await readAll(home)).jobs);
+}
+export async function removeJob(id, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const before = file.jobs.length;
+        file.jobs = file.jobs.filter((j) => j.id !== id);
+        if (file.jobs.length === before)
+            return false;
+        await writeAll(file, home);
+        return true;
+    });
+}
+export async function setEnabled(id, enabled, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const job = file.jobs.find((j) => j.id === id);
+        if (!job)
+            return null;
+        job.enabled = enabled;
+        await writeAll(file, home);
+        return job;
+    });
+}
+/** 标记已运行: 更新 lastRunAt + runCount (runId 用于并行保护, 由 scheduler 提供) */
+export async function markRun(id, at, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const job = file.jobs.find((j) => j.id === id);
+        if (!job)
+            return null;
+        job.lastRunAt = at;
+        job.runCount += 1;
+        await writeAll(file, home);
+        return job;
+    });
+}

package/dist/cron/scheduler.js

@@ -0,0 +1,72 @@
+/**
+ * scheduler.ts — 定时任务调度器
+ *
+ * 借鉴 Hermes agent cron/scheduler.py 心智:
+ *   - 一个 tick() 扫描全部 enabled jobs, 用 parseSchedule 判断是否 due (下次时间 <= now)
+ *   - due → 执行 exec(job), 完成后 markRun 更新 lastRunAt
+ *   - 并发保护: 正在运行的 jobId 集合, 避免同一 job 并行重复触发
+ *   - exec 可注入: bolloon CLI 里把 job.prompt 投给 agent 调度闭环, 测试里可注入 fake
+ *   - 不建数据库, 不引入外部调度 —— 由调用方 (CLI 主循环) 定期调 tick()
+ */
+import * as os from 'os';
+import { listJobs, markRun } from './jobs-store.js';
+import { parseSchedule, nextAfter } from './cron-parser.js';
+export class Scheduler {
+    exec;
+    now;
+    home;
+    /** 正在运行的 job id, 防止并行重复触发 */
+    running = new Set();
+    /** 已触发但执行失败, 待下次重试 (避免死循环 + 可观测) */
+    failed = new Map();
+    constructor(opts) {
+        this.exec = opts.exec;
+        this.now = opts.now ?? (() => new Date());
+        this.home = opts.home ?? os.homedir();
+    }
+    /** 是否正在运行某 job (供外部查询并发状态) */
+    isRunning(jobId) {
+        return this.running.has(jobId);
+    }
+    /**
+     * 一次调度心跳. 找出所有 due 的 enabled job 并执行 (串行), 成功者 markRun.
+     * @returns 本次执行数量
+     */
+    async tick() {
+        const now = this.now();
+        const jobs = await listJobs(this.home);
+        let ran = 0;
+        for (const job of jobs) {
+            if (!job.enabled)
+                continue;
+            if (this.running.has(job.id))
+                continue; // 正在跑, 跳过防重入
+            const parsed = parseSchedule(job.schedule, now);
+            if (!parsed)
+                continue; // 解析不了的调度, 跳过 (可另做告警)
+            const lastRunAt = job.lastRunAt ? new Date(job.lastRunAt) : undefined;
+            const due = nextAfter(job.schedule, lastRunAt, now);
+            if (due && due.getTime() > now.getTime())
+                continue; // 还不到时间 (含首次: 立即触发)
+            this.running.add(job.id);
+            try {
+                await this.exec(job);
+                await markRun(job.id, now.toISOString(), this.home);
+                this.failed.delete(job.id);
+                ran += 1;
+            }
+            catch (e) {
+                this.failed.set(job.id, (this.failed.get(job.id) ?? 0) + 1);
+                console.error(`[scheduler] job 执行失败 (${job.name}):`, e?.message ?? e);
+            }
+            finally {
+                this.running.delete(job.id);
+            }
+        }
+        return ran;
+    }
+    /** 最近失败统计 (供诊断) */
+    failureCounts() {
+        return this.failed;
+    }
+}

package/dist/cron/suggestion-catalog.js

@@ -0,0 +1,41 @@
+/**
+ * suggestion-catalog.ts — 内置"下一动作"建议目录
+ *
+ * 借鉴 Hermes agent suggestion_catalog.py 心智:
+ *   - 不是让用户每次从零想"该做什么", 而是提供一组成熟、可一配置就用的自动化/策略建议
+ *   - 每个条目是 { dedupKey, title, summary, schedule?, prompt? }
+ *   - CLI `/suggestions catalog` 可列出, 用户任选自动装机 (装成 suggestion 或 cron job)
+ */
+export const SUGGESTION_CATALOG = [
+    {
+        dedupKey: 'daily-review',
+        title: '每日工作复盘',
+        summary: '每天工作结束后 5 分钟, 让 agent 总结当天做的事、遗留事项、并写进 wiki 日志。',
+        schedule: '0 18 * * *',
+        prompt: '对今天的会话做一次工作复盘: 列出完成的任务、遗留的阻塞项、并追加一行到 wiki 日志。',
+    },
+    {
+        dedupKey: 'weekly-planner',
+        title: '每周计划',
+        summary: '每周一早上生成本周重点任务清单, 纳入当前计划。',
+        schedule: '0 9 * * 1',
+        prompt: '生成本周计划: 结合最近 wiki 状态与未完成任务, 列出 3-5 条本周重点。',
+    },
+    {
+        dedupKey: 'wiki-sync',
+        title: 'Wiki 一致性检查',
+        summary: '定期跑 wiki lint / stale 检查, 发现过期页面就建议修正。',
+        schedule: '0 12 * * 5',
+        prompt: '运行一次 wiki 一致性检查 (stale_report/wiki_lint), 把发现的过期页面整理成待办建议。',
+    },
+    {
+        dedupKey: 'version-check',
+        title: '版本更新检查',
+        summary: '定期检查 bolloon 是否有新版本并提示升级。',
+        schedule: 'every 1d',
+        prompt: '检查 bolloon 是否有新版本, 若有则提示用户升级。',
+    },
+];
+export function findCatalogEntry(dedupKey) {
+    return SUGGESTION_CATALOG.find((c) => c.dedupKey === dedupKey);
+}

package/dist/cron/suggestions-command.js

@@ -0,0 +1,96 @@
+/**
+ * suggestions-command.ts — `/suggestions` CLI 子命令处理 (纯函数返回文本)
+ *
+ * 借鉴 Hermes agent suggestions_cmd.py 心智: 一个入口, 多个子动作, 全部返回可回显的文本.
+ * 用法:
+ *   /suggestions            → 列出当前待处理建议
+ *   /suggestions accept <n> → 接受第 n 条 (转成任务 / 消费)
+ *   /suggestions dismiss <n>
+ *   /suggestions clear      → 全部清空
+ *   /suggestions catalog    → 列出内置建议目录
+ *   /suggestions install <dedupKey> → 从目录装机 (生成 suggestion 或 cron job)
+ *
+ * 返回 [text, consumedSuggestionId?]; 无副作用逻辑放在 store, 本模块只做编排与文本渲染.
+ */
+import { listSuggestions, acceptSuggestion, dismissSuggestion, clearSuggestions, addSuggestion, } from './suggestions.js';
+import { addJob } from './jobs-store.js';
+import { findCatalogEntry, SUGGESTION_CATALOG } from './suggestion-catalog.js';
+function noArgs() {
+    return '用法: /suggestions \u3000| accept <n> \u3000| dismiss <n> \u3000| clear \u3000| catalog \u3000| install <dedupKey>';
+}
+function renderList(items) {
+    if (items.length === 0)
+        return '当前没有待处理建议。\n\n可用: /suggestions catalog 查看内置建议目录。';
+    const lines = items.map((s, i) => `${i + 1}. [${s.source}] ${s.summary}${s.dueAt ? ` (到期 ${s.dueAt})` : ''}`);
+    return lines.join('\n') + `\n\n用 /suggestions accept <n> 接受, dismiss <n> 忽略, clear 全清。`;
+}
+export function renderCatalog() {
+    return '内置建议目录:\n' +
+        SUGGESTION_CATALOG.map((c) => `- ${c.dedupKey}: ${c.title} — ${c.summary}`).join('\n') +
+        '\n\n用 /suggestions install <dedupKey> 装机。';
+}
+export async function handleSuggestionsCommand(args, home) {
+    const parts = args.trim().split(/\s+/).filter(Boolean);
+    const action = parts[0]?.toLowerCase() ?? '';
+    switch (action) {
+        case '':
+        case 'list': {
+            const items = await listSuggestions(home);
+            return { text: renderList(items) };
+        }
+        case 'accept': {
+            const n = Number(parts[1]);
+            if (!Number.isInteger(n) || n < 1)
+                return { text: '用法: /suggestions accept <n>' };
+            const items = await listSuggestions(home);
+            const target = items[n - 1];
+            if (!target)
+                return { text: `没有第 ${n} 条建议。` };
+            const accepted = await acceptSuggestion(target.id, home);
+            if (!accepted)
+                return { text: '该建议已被移除, 请重试。' };
+            return {
+                text: `已接受: ${accepted.summary}`,
+                accepted,
+            };
+        }
+        case 'dismiss': {
+            const n = Number(parts[1]);
+            if (!Number.isInteger(n) || n < 1)
+                return { text: '用法: /suggestions dismiss <n>' };
+            const items = await listSuggestions(home);
+            const target = items[n - 1];
+            if (!target)
+                return { text: `没有第 ${n} 条建议。` };
+            const ok = await dismissSuggestion(target.id, home);
+            return { text: ok ? `已忽略: ${target.summary}` : '忽略失败。' };
+        }
+        case 'clear': {
+            const n = await clearSuggestions(home);
+            return { text: `已清空 ${n} 条建议。` };
+        }
+        case 'catalog': {
+            return {
+                text: renderCatalog(),
+            };
+        }
+        case 'install': {
+            const key = parts[1];
+            if (!key)
+                return { text: '用法: /suggestions install <dedupKey>' };
+            const entry = findCatalogEntry(key);
+            if (!entry)
+                return { text: `目录里没有 ${key}。用 /suggestions catalog 看。` };
+            // 有 schedule + prompt → 直接生成 cron job; 否则先塞一条建议
+            const s = await addSuggestion({ dedupKey: entry.dedupKey, summary: entry.summary, source: 'system' }, home);
+            let extra = '';
+            if (entry.schedule && entry.prompt) {
+                await addJob({ name: entry.title, schedule: entry.schedule, prompt: entry.prompt }, home);
+                extra = ` 并生成了定时任务 (${entry.schedule})。`;
+            }
+            return { text: `已装机: ${entry.title}${extra}\n(可用 /suggestions dismiss 1 撤销这条建议)` };
+        }
+        default:
+            return { text: noArgs() };
+    }
+}

package/dist/cron/suggestions.js

@@ -0,0 +1,110 @@
+/**
+ * suggestions.ts — 轻量建议队列 (sticky-note suggestions)
+ *
+ * 借鉴 Hermes agent cron/suggestions.py + suggestion_catalog.py 心智:
+ *   - 建议是一个个"待办/提醒/下一动作", 由调度器/策略/系统在合适的时机塞入
+ *   - 同一 dedup_key 只保留最新的一个 (避免同一提醒重复刷屏)
+ *   - MAX_PENDING 上限, 超出自动丢最旧的 (队列有界, 不无限膨胀)
+ *   - 用户可接受 (accept) / 忽略 (dismiss) / 全部清空 (clear)
+ *   - 每个 suggestion 记住来源 (source) / 摘要 (summary) / 到期 (dueAt?, 可选)
+ *   - 落盘 ~/.bolloon/suggestions.json, 进程内互斥链序列化 (对齐 server-storage)
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+export const MAX_PENDING = 5; // 借鉴 hermes: 建议队列有界, 最长该数
+function getSuggestionsPath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'suggestions.json');
+}
+// 进程内互斥链: 所有写操作串行, 失败不毒化链 (对齐 server-storage 的 updateChannels 设计)
+let suggestionsLock = Promise.resolve();
+function withLock(fn) {
+    const run = suggestionsLock.then(fn);
+    suggestionsLock = run.then(() => undefined, () => undefined);
+    return run;
+}
+async function readAll(home) {
+    try {
+        const raw = await fs.readFile(getSuggestionsPath(home), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed?.version === 1 && Array.isArray(parsed.items))
+            return parsed;
+        return { version: 1, items: [] };
+    }
+    catch {
+        return { version: 1, items: [] };
+    }
+}
+async function writeAll(file, home) {
+    const p = getSuggestionsPath(home);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    // 原子写: 先写临时文件再 rename, 避免半截 JSON (对齐 plan-store 直接重写该校验线)
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, JSON.stringify(file, null, 2), 'utf-8');
+    await fs.rename(tmp, p);
+}
+/**
+ * 添加一条建议. 同一 dedupKey 已存在 → 更新其 summary/来源, 并重置插入到队尾; 不超过 MAX_PENDING.
+ * @returns 新构建 (或更新后) 的 suggestion
+ */
+export async function addSuggestion(input, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const existing = file.items.find((s) => s.dedupKey === input.dedupKey);
+        const now = new Date().toISOString();
+        const entry = {
+            id: existing?.id ?? crypto.randomUUID(),
+            dedupKey: input.dedupKey,
+            summary: input.summary,
+            source: input.source,
+            relatedTaskId: input.relatedTaskId,
+            createdAt: existing?.createdAt ?? now,
+            ...(input.dueAt ? { dueAt: input.dueAt } : {}),
+        };
+        file.items = file.items.filter((s) => s.dedupKey !== input.dedupKey);
+        file.items.push(entry);
+        while (file.items.length > MAX_PENDING)
+            file.items.shift(); // 丢最旧的
+        await writeAll(file, home);
+        return entry;
+    });
+}
+/** 全部未完成建议 */
+export async function listSuggestions(home = os.homedir()) {
+    return withLock(async () => (await readAll(home)).items);
+}
+/** 接受: 从队列移除并返回它 (调用方可据此做后续动作, 如转成 task) */
+export async function acceptSuggestion(id, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const idx = file.items.findIndex((s) => s.id === id);
+        if (idx < 0)
+            return null;
+        const [removed] = file.items.splice(idx, 1);
+        await writeAll(file, home);
+        return removed;
+    });
+}
+/** 忽略: 从队列移除 */
+export async function dismissSuggestion(id, home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const before = file.items.length;
+        file.items = file.items.filter((s) => s.id !== id);
+        if (file.items.length === before)
+            return false;
+        await writeAll(file, home);
+        return true;
+    });
+}
+/** 全部清空 */
+export async function clearSuggestions(home = os.homedir()) {
+    return withLock(async () => {
+        const file = await readAll(home);
+        const n = file.items.length;
+        file.items = [];
+        await writeAll(file, home);
+        return n;
+    });
+}

package/dist/electron/first-run.js

@@ -9,60 +9,60 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { firstRunFlagPath, dataDir, logsDir } from './paths';
 import { log } from './logger';
-const OVERLAY_HTML = `
-<!DOCTYPE html>
-<html>
-<head>
-<meta charset="utf-8" />
-<style>
-  :root { color-scheme: light dark; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-    margin: 0; padding: 32px 28px;
-    background: rgba(245,245,247,0.97);
-    color: #1d1d1f;
-    height: 100vh; box-sizing: border-box;
-  }
-  @media (prefers-color-scheme: dark) {
-    body { background: rgba(28,28,30,0.97); color: #f5f5f7; }
-  }
-  h1 { font-size: 18px; margin: 0 0 14px; font-weight: 600; }
-  p  { font-size: 13px; line-height: 1.55; margin: 8px 0; }
-  code {
-    font-family: ui-monospace, "SF Mono", Menlo, monospace;
-    font-size: 12px; padding: 1px 5px;
-    background: rgba(0,0,0,0.06); border-radius: 3px;
-  }
-  @media (prefers-color-scheme: dark) {
-    code { background: rgba(255,255,255,0.08); }
-  }
-  .btn {
-    display: inline-block; margin-top: 18px; padding: 8px 18px;
-    background: #007aff; color: #fff; border: none; border-radius: 6px;
-    font-size: 13px; font-weight: 500; cursor: pointer;
-  }
-  .btn:hover { background: #0066d6; }
-  ul { padding-left: 20px; }
-  li { font-size: 13px; line-height: 1.7; }
-</style>
-</head>
-<body>
-<h1>欢迎使用 Bolloon Agent</h1>
-<p>你的数据存放在本地, 不上传:</p>
-<ul>
-  <li>配置 / 频道 / P2P 密钥: <code id="data"></code></li>
-  <li>运行日志: <code id="logs"></code></li>
-</ul>
-<p>所有数据在卸载后仍保留 — 想清理就手动删除 ~/.bolloon/。</p>
-<button class="btn" id="ok">知道了</button>
-<script>
-  const ok = document.getElementById('ok');
-  ok.addEventListener('click', () => window.electronAPI.markFirstRunSeen());
-  document.getElementById('data').textContent = window.electronAPI.getDataPathSync?.() || '';
-  document.getElementById('logs').textContent = window.electronAPI.getLogsPathSync?.() || '';
-</script>
-</body>
-</html>
+const OVERLAY_HTML = `
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    margin: 0; padding: 32px 28px;
+    background: rgba(245,245,247,0.97);
+    color: #1d1d1f;
+    height: 100vh; box-sizing: border-box;
+  }
+  @media (prefers-color-scheme: dark) {
+    body { background: rgba(28,28,30,0.97); color: #f5f5f7; }
+  }
+  h1 { font-size: 18px; margin: 0 0 14px; font-weight: 600; }
+  p  { font-size: 13px; line-height: 1.55; margin: 8px 0; }
+  code {
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    font-size: 12px; padding: 1px 5px;
+    background: rgba(0,0,0,0.06); border-radius: 3px;
+  }
+  @media (prefers-color-scheme: dark) {
+    code { background: rgba(255,255,255,0.08); }
+  }
+  .btn {
+    display: inline-block; margin-top: 18px; padding: 8px 18px;
+    background: #007aff; color: #fff; border: none; border-radius: 6px;
+    font-size: 13px; font-weight: 500; cursor: pointer;
+  }
+  .btn:hover { background: #0066d6; }
+  ul { padding-left: 20px; }
+  li { font-size: 13px; line-height: 1.7; }
+</style>
+</head>
+<body>
+<h1>欢迎使用 Bolloon Agent</h1>
+<p>你的数据存放在本地, 不上传:</p>
+<ul>
+  <li>配置 / 频道 / P2P 密钥: <code id="data"></code></li>
+  <li>运行日志: <code id="logs"></code></li>
+</ul>
+<p>所有数据在卸载后仍保留 — 想清理就手动删除 ~/.bolloon/。</p>
+<button class="btn" id="ok">知道了</button>
+<script>
+  const ok = document.getElementById('ok');
+  ok.addEventListener('click', () => window.electronAPI.markFirstRunSeen());
+  document.getElementById('data').textContent = window.electronAPI.getDataPathSync?.() || '';
+  document.getElementById('logs').textContent = window.electronAPI.getLogsPathSync?.() || '';
+</script>
+</body>
+</html>
 `;
 export function hasSeenFirstRun() {
     try {