libero3 0.3.0

package/dist/mcp/src/timeline/index.js

@@ -0,0 +1,705 @@
+import { effectiveUserId } from "../profile-helpers.js";
+const SLOT_MS = 10 * 60 * 1000;
+const KIND_PRIORITY = {
+    timer: 5,
+    completed: 4,
+    unverified: 3,
+    planned: 2,
+    empty: 1,
+};
+const FIXED_EMOJI = {
+    empty: "⬜",
+    planned: "🟦",
+    unverified: "❓",
+    timer_running: "⏰",
+    timer_paused: "⏸️",
+};
+const FIXED_ASCII = {
+    empty: "[ ]",
+    planned: "[#]",
+    unverified: "[?]",
+    timer_running: "[T]",
+    timer_paused: "[P]",
+};
+const LEGEND_ZH = {
+    "⬜": "无安排",
+    "🟦": "计划",
+    "❓": "未回应",
+    "⏰": "计时中",
+    "⏸️": "暂停计时",
+    "[ ]": "无安排",
+    "[#]": "计划",
+    "[?]": "未回应",
+    "[T]": "计时中",
+    "[P]": "暂停计时",
+};
+/** category name → ascii token like [W] / [·]（空分类不用 [?]，以免和未回应撞车） */
+export function categoryAsciiToken(name) {
+    if (!name || !name.trim())
+        return "[·]";
+    const latin = name.trim().match(/[A-Za-z]/);
+    if (latin)
+        return `[${latin[0].toUpperCase()}]`;
+    return `[${name.trim()[0]}]`;
+}
+/**
+ * S9 v0.2: hex 颜色 → 方块 emoji（粗色相映射，6-7 色）
+ *
+ * 设计意图（见 docs/specs/S9-v0.2-design-plan-colored-tiles.md）：
+ * - 15 个分类压缩到 7 种方块色——保留视觉区分度，避免 15 色用户认不过来
+ * - 用 HSL hue 粗分（不用精确匹配 hex，避免脆弱）
+ * - 灰阶 / 深色 → ⬛（视觉暗色，区分显著）
+ * - 无效输入 → 🟦（默认蓝，跟原 spec v0.1 兼容）
+ */
+export function colorToTile(hex) {
+    if (!hex || typeof hex !== "string" || !hex.startsWith("#"))
+        return "🟦";
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    // 解析失败 → fallback
+    if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b))
+        return "🟦";
+    const { h, s, l } = rgbToHsl(r, g, b);
+    // 灰阶（饱和度 < 12%）或过暗（亮度 < 0.35）→ ⬛
+    // 设计：睡眠(#34495E l=0.29 s=0.29)、内务(#95A5A6 s=0.09)、闲散(#BDC3C7) 等
+    // 深色 / 中性色都归黑，区分显著
+    if (s < 0.12 || l < 0.35)
+        return "⬛";
+    // 色相分段（0-360）
+    if (h < 15 || h >= 345)
+        return "🟥"; // 红
+    if (h < 45)
+        return "🟧"; // 橙
+    if (h < 70)
+        return "🟨"; // 黄
+    if (h < 165)
+        return "🟩"; // 绿
+    if (h < 240)
+        return "🟦"; // 蓝（含青）
+    if (h < 315)
+        return "🟪"; // 紫（240-315）
+    return "🟥"; // 粉红归红
+}
+/** RGB → HSL（h: 0-360, s/l: 0-1） */
+function rgbToHsl(r, g, b) {
+    const rN = r / 255;
+    const gN = g / 255;
+    const bN = b / 255;
+    const max = Math.max(rN, gN, bN);
+    const min = Math.min(rN, gN, bN);
+    const l = (max + min) / 2;
+    let h = 0;
+    let s = 0;
+    if (max !== min) {
+        const d = max - min;
+        s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+        switch (max) {
+            case rN:
+                h = ((gN - bN) / d + (gN < bN ? 6 : 0)) * 60;
+                break;
+            case gN:
+                h = ((bN - rN) / d + 2) * 60;
+                break;
+            default:
+                h = ((rN - gN) / d + 4) * 60;
+        }
+    }
+    return { h, s, l };
+}
+function timerKey(status) {
+    return status === "paused" ? "timer_paused" : "timer_running";
+}
+/** Resolve display symbol for a cell given format. */
+export function resolveCellSymbol(cell, format) {
+    if (cell.kind === "completed") {
+        if (format === "emoji") {
+            if (cell.emoji && cell.emoji.trim())
+                return cell.emoji;
+            return cell.ascii && cell.ascii !== "[?]" ? cell.ascii : "•";
+        }
+        if (cell.ascii && cell.ascii !== "[?]")
+            return cell.ascii;
+        return "[·]";
+    }
+    if (cell.kind === "timer") {
+        const key = timerKey(cell.status);
+        return format === "emoji" ? FIXED_EMOJI[key] : FIXED_ASCII[key];
+    }
+    // S9 v0.2: planned 块带 tile 时优先用分类色方块，否则 fallback 到默认 🟦
+    if (cell.kind === "planned") {
+        if (format === "emoji") {
+            if (cell.tile && cell.tile.trim())
+                return cell.tile;
+            return FIXED_EMOJI.planned;
+        }
+        // ascii 用 category 首字母（如 [W]），否则默认 [#]
+        return cell.ascii ?? FIXED_ASCII.planned;
+    }
+    // unverified / empty
+    const key = cell.kind;
+    return format === "emoji" ? FIXED_EMOJI[key] : FIXED_ASCII[key];
+}
+/**
+ * Merge candidates by priority:
+ * timer_running > timer_paused > completed > unverified > planned > empty
+ * Between two timers, running beats paused.
+ */
+export function mergeTimelineCells(candidates) {
+    if (candidates.length === 0)
+        return { kind: "empty" };
+    let best = candidates[0];
+    for (let i = 1; i < candidates.length; i++) {
+        const c = candidates[i];
+        const bp = KIND_PRIORITY[best.kind];
+        const cp = KIND_PRIORITY[c.kind];
+        if (cp > bp) {
+            best = c;
+            continue;
+        }
+        if (cp < bp)
+            continue;
+        // same kind: for timer, running > paused
+        if (c.kind === "timer" && best.kind === "timer") {
+            if (c.status === "running" && best.status !== "running")
+                best = c;
+        }
+    }
+    return best;
+}
+function legendMeaning(symbol) {
+    if (LEGEND_ZH[symbol])
+        return LEGEND_ZH[symbol];
+    // S9 v0.2: 方块色 = 计划块（按分类上色）
+    if (symbol === "🟦" ||
+        symbol === "🟪" ||
+        symbol === "🟩" ||
+        symbol === "🟥" ||
+        symbol === "🟧" ||
+        symbol === "🟨" ||
+        symbol === "⬛") {
+        return "计划";
+    }
+    // completed category emoji / ascii letter
+    if (symbol.startsWith("[") && symbol.endsWith("]"))
+        return "实绩";
+    return "实绩";
+}
+function formatHourLabel(d) {
+    const hh = String(d.getHours()).padStart(2, "0");
+    return `${hh}:00`;
+}
+function isEmptyRow(cells) {
+    return cells.every((c) => c.kind === "empty");
+}
+/**
+ * Pure render: table header + matrix (with collapse) + details table.
+ * No DB access.
+ */
+export function renderTimelineCells(input) {
+    const format = input.format;
+    const boundary = input.boundaryEllipsis !== false;
+    const now = new Date(input.nowIso);
+    const nowHourStart = new Date(now);
+    nowHourStart.setMinutes(0, 0, 0);
+    const nowHourIso = nowHourStart.toISOString();
+    const rows = input.hours.map((h) => ({
+        hour: h.hour,
+        current: h.hourStartIso === nowHourIso,
+        cells: h.cells,
+    }));
+    const legend = {};
+    const mark = (sym) => {
+        legend[sym] = legendMeaning(sym);
+    };
+    // Always include empty in legend for orientation
+    mark(resolveCellSymbol({ kind: "empty" }, format));
+    const matrixLines = [];
+    // pressure E-6: 全空窗口不折叠（否则只剩 ··· 废文本，用户看不到时间范围）
+    const hasAnyNonEmpty = rows.some((r) => !isEmptyRow(r.cells));
+    // Collapse: ≥3 consecutive empty rows → keep 1 empty + ···
+    let i = 0;
+    while (i < rows.length) {
+        if (!isEmptyRow(rows[i].cells)) {
+            const row = rows[i];
+            const syms = row.cells.map((c) => {
+                const s = resolveCellSymbol(c, format);
+                mark(s);
+                return s;
+            });
+            // 2026-07-27 UX 反馈：current 行用 → 替代 ▶（更窄、不挤压 emoji 行）
+            const hourPart = format === "emoji"
+                ? row.current
+                    ? `→${row.hour}`
+                    : ` ${row.hour}`
+                : row.current
+                    ? `>${row.hour}`
+                    : ` ${row.hour}`;
+            matrixLines.push({
+                type: "row",
+                row,
+                text: `${hourPart}  ${syms.join(" ")}`,
+            });
+            i++;
+            continue;
+        }
+        // count consecutive empty
+        let j = i;
+        while (j < rows.length && isEmptyRow(rows[j].cells))
+            j++;
+        const emptyCount = j - i;
+        // pressure E-6: 全空窗口不折叠，逐行展示让用户看到完整时间范围
+        if (emptyCount >= 3 && hasAnyNonEmpty) {
+            const row = rows[i];
+            const syms = row.cells.map((c) => resolveCellSymbol(c, format));
+            mark(syms[0]);
+            const hourPart = format === "emoji"
+                ? row.current
+                    ? `→${row.hour}`
+                    : ` ${row.hour}`
+                : row.current
+                    ? `>${row.hour}`
+                    : ` ${row.hour}`;
+            matrixLines.push({
+                type: "row",
+                row,
+                text: `${hourPart}  ${syms.join(" ")}`,
+            });
+            matrixLines.push({ type: "ellipsis" });
+            i = j;
+        }
+        else {
+            for (let k = i; k < j; k++) {
+                const row = rows[k];
+                const syms = row.cells.map((c) => resolveCellSymbol(c, format));
+                mark(syms[0]);
+                const hourPart = format === "emoji"
+                    ? row.current
+                        ? `→${row.hour}`
+                        : ` ${row.hour}`
+                    : row.current
+                        ? `>${row.hour}`
+                        : ` ${row.hour}`;
+                matrixLines.push({
+                    type: "row",
+                    row,
+                    text: `${hourPart}  ${syms.join(" ")}`,
+                });
+            }
+            i = j;
+        }
+    }
+    // Build text lines: 明细在前（用户先看具体内容），矩阵在后（时间分布概览）
+    // S9 v0.5（2026-08-07）：表头移到矩阵上方，不再夹在明细前面
+    const textLines = [];
+    // ── 明细段（在前）──
+    // S9 v0.3: 按 symbol 分组紧凑展示
+    // S9 v0.4: completed → ✓ + ~~划线~~；unverified → ❓ 后缀；插入「📍 现在」分隔线
+    // S9 v0.5（2026-08-07）: 每条独占一行
+    // S45（2026-08-07）: 同 category + 时间连续 → 合并成组；中间 ≤15min 短休息 → 吸收
+    //   组（>1 member 或吸收了休息）：组头 + 子任务列表
+    //   组（仅 1 member 无休息）：退化为 v0.5 单行（避免冗余）
+    const details = input.details ?? [];
+    if (details.length > 0) {
+        textLines.push("📋 明细");
+        const inWin = details.filter((d) => d.in_window);
+        const outWin = details.filter((d) => !d.in_window);
+        // S45: inWin 已按 time 排序，可直接分组
+        const inWinGroups = groupDetails(inWin);
+        // S9 v0.5: 单条 entry 格式
+        const buildEntry = (d) => {
+            let statusMark = "  "; // 默认 2 空格占位（对齐 ✓ 和 ?）
+            let titlePart = d.title;
+            if (d.status === "completed") {
+                statusMark = "✓ ";
+                titlePart = `~~${d.title}~~`;
+            }
+            else if (d.status === "unverified") {
+                statusMark = "? ";
+            }
+            return `${statusMark}${d.symbol} ${d.time} ${titlePart}`;
+        };
+        // S45: 组内子任务 entry（不带组 symbol，状态前缀照旧）
+        const buildSubEntry = (d) => {
+            let statusMark = "  ";
+            let titlePart = d.title;
+            if (d.status === "completed") {
+                statusMark = "✓ ";
+                titlePart = `~~${d.title}~~`;
+            }
+            else if (d.status === "unverified") {
+                statusMark = "? ";
+            }
+            // 子任务缩进 2 空格，时间取自 d.time 的 "HH:MM-HH:MM"
+            return `  ${statusMark}${d.time} ${titlePart}`;
+        };
+        // S45: 组头格式
+        const buildGroupHeader = (g) => {
+            const emoji = g.category_emoji && g.category_emoji.trim() ? g.category_emoji : "•";
+            const name = g.category_name ?? "活动";
+            const breakNote = g.break_total_min > 0 ? `（含休息 ${g.break_total_min}min）` : "";
+            return `${emoji} ${name} ${g.start_time}-${g.end_time}${breakNote}`;
+        };
+        // S9 v0.4: 「📍 现在」分隔线判断
+        const parseDetailStart = (time) => {
+            const startStr = time.split("-")[0].trim();
+            const [h, m] = startStr.split(":").map(Number);
+            return h * 60 + m;
+        };
+        const nowDate = new Date(input.nowIso);
+        const nowHM = nowDate.getHours() * 60 + nowDate.getMinutes();
+        const nowLabel = `${String(nowDate.getHours()).padStart(2, "0")}:${String(nowDate.getMinutes()).padStart(2, "0")}`;
+        const inWinAllPast = inWin.every((d) => parseDetailStart(d.time) <= nowHM);
+        const inWinAllFuture = inWin.every((d) => parseDetailStart(d.time) > nowHM);
+        const needNowMarker = inWin.length > 0 && !inWinAllPast && !inWinAllFuture;
+        // S45: 渲染组——支持"现在"标识插在第一个未来组之前
+        const renderGroup = (g) => {
+            const isMulti = g.members.length > 1 || g.absorbed_breaks.length > 0;
+            if (!isMulti) {
+                // 退化为 v0.5 单行
+                return [buildEntry(g.members[0])];
+            }
+            const lines = [buildGroupHeader(g)];
+            for (const m of g.members) {
+                lines.push(buildSubEntry(m));
+            }
+            return lines;
+        };
+        for (let i = 0; i < inWinGroups.length; i++) {
+            const g = inWinGroups[i];
+            // 「📍 现在」标识插在第一个未来组之前
+            if (needNowMarker && parseDetailStart(`${g.start_time}-${g.end_time}`) > nowHM && i > 0 && !textLines.includes(`─── 📍 现在 ${nowLabel} ──`)) {
+                textLines.push(`─── 📍 现在 ${nowLabel} ──`);
+            }
+            textLines.push(...renderGroup(g));
+        }
+        // 兜底：如果所有组都过去/未来，但 needNowMarker 仍 true（混合）且没插入过 → 不补
+        // (理论上不会发生，因为上面循环会处理)
+        if (outWin.length > 0) {
+            textLines.push("（窗口外）");
+            const outWinGroups = groupDetails(outWin);
+            for (const g of outWinGroups) {
+                textLines.push(...renderGroup(g));
+            }
+        }
+    }
+    else {
+        // pressure E-6: details 空 → 给"该时段无安排"提示，不留空段
+        textLines.push("📋 明细：该时段无安排");
+    }
+    // ── 矩阵段（在后，作为时间分布概览）──
+    const pushEllipsis = () => {
+        if (textLines[textLines.length - 1] !== "···")
+            textLines.push("···");
+    };
+    if (boundary)
+        pushEllipsis();
+    // S9 v0.5: 时间表头紧贴矩阵上方（之前在明细前，造成"表头夹中间"错觉）
+    textLines.push("       00  10  20  30  40  50");
+    // 2026-07-27 UX 反馈：矩阵上下行距太挤，每行后加一个空行透气
+    for (let k = 0; k < matrixLines.length; k++) {
+        const line = matrixLines[k];
+        if (line.type === "ellipsis") {
+            pushEllipsis();
+        }
+        else {
+            textLines.push(line.text);
+            // 行间留白：仅当下一行也是 row（避免 row→ellipsis/末尾 出现多余空行）
+            const next = matrixLines[k + 1];
+            if (next && next.type === "row")
+                textLines.push("");
+        }
+    }
+    if (boundary)
+        pushEllipsis();
+    // S9 v0.2: 末尾拼图例（按本次实际出现的色）
+    // 设计：图例短一行，只列实际出现过的符号；颜色块统一标"计划·X 类"
+    if (Object.keys(legend).length > 1) {
+        const legendParts = [];
+        for (const [sym, meaning] of Object.entries(legend)) {
+            legendParts.push(`${sym} ${meaning}`);
+        }
+        textLines.push(`图例：${legendParts.join(" · ")}`);
+    }
+    return { rows, rendered_text: textLines.join("\n"), legend };
+}
+const S45_GAP_THRESHOLD_MIN = 15;
+const S45_BREAK_THRESHOLD_MIN = 15;
+function isShortBreak(d) {
+    return !!d.is_break && (d.duration_min ?? 999) <= S45_BREAK_THRESHOLD_MIN;
+}
+/**
+ * S45: 把已排序的 detail 列表分组成 DetailGroup[]。
+ * 输入必须按 start_ms 升序排好。
+ */
+export function groupDetails(details) {
+    if (details.length === 0)
+        return [];
+    const groups = [];
+    let current = null;
+    for (let i = 0; i < details.length; i++) {
+        const d = details[i];
+        if (current === null) {
+            // 首个块 → 开新组（休息块也开自己的"独立组"，members 是它自己）
+            current = newGroup(d);
+            continue;
+        }
+        const gapMin = ((d.start_ms ?? 0) - (current.members[current.members.length - 1]?.end_ms ?? 0)) /
+            (60 * 1000);
+        const sameCategory = !!d.category_id &&
+            d.category_id === current.category_id &&
+            !!current.category_id;
+        // 情况 1：当前块是短休息，且后面（i+1）还有同 category 块 → 吸收到当前组
+        if (isShortBreak(d) && sameCategoryContinuesAfter(details, i, current.category_id)) {
+            current.absorbed_breaks.push(d);
+            current.break_total_min += d.duration_min ?? 0;
+            // 注意：休息块的 end_ms 不更新 current 的 last_end——组的 last_end 取最后一个非休息块
+            continue;
+        }
+        // 情况 2：同 category + gap ≤15min → 加入组
+        if (sameCategory && gapMin >= 0 && gapMin <= S45_GAP_THRESHOLD_MIN) {
+            current.members.push(d);
+            // 更新组的 end_time
+            current.end_time = d.time.split("-")[1]?.trim() ?? current.end_time;
+            continue;
+        }
+        // 情况 3：边界 → 结束当前组，开新组
+        groups.push(current);
+        current = newGroup(d);
+    }
+    if (current)
+        groups.push(current);
+    return groups;
+}
+function newGroup(d) {
+    return {
+        members: [d],
+        absorbed_breaks: [],
+        break_total_min: 0,
+        start_time: d.time.split("-")[0]?.trim() ?? "",
+        end_time: d.time.split("-")[1]?.trim() ?? "",
+        category_id: d.category_id ?? null,
+        category_name: d.category_name ?? null,
+        category_emoji: d.category_emoji ?? null,
+    };
+}
+/** 判断 details[i] 之后是否还有同 category_id 的非休息块（前视，用于休息吸收判定） */
+function sameCategoryContinuesAfter(details, i, categoryId) {
+    if (!categoryId)
+        return false;
+    for (let j = i + 1; j < details.length; j++) {
+        const next = details[j];
+        if (next.is_break)
+            continue; // 跳过中间的休息块
+        if (next.category_id === categoryId)
+            return true;
+        return false; // 遇到非同 category 的非休息块 → 不算后续同 category
+    }
+    return false;
+}
+export function computeDefaultWindow(now) {
+    const hour = new Date(now);
+    hour.setMinutes(0, 0, 0);
+    const from = new Date(hour.getTime() - 5 * 60 * 60 * 1000);
+    const to = new Date(hour.getTime() + 5 * 60 * 60 * 1000);
+    return { from, to };
+}
+function cellFromBlock(b) {
+    if (b.status === "completed") {
+        const ascii = categoryAsciiToken(b.category_name);
+        const emoji = b.category_emoji && b.category_emoji.trim()
+            ? b.category_emoji
+            : "•";
+        return {
+            kind: "completed",
+            emoji,
+            ascii,
+            label: b.title,
+        };
+    }
+    // S9 v0.2: planned 块按分类上色（不再统一 🟦）
+    // unverified 保持 ❓ 不上色（状态优先于分类）
+    if (b.status === "planned") {
+        const ascii = categoryAsciiToken(b.category_name);
+        const tile = colorToTile(b.category_color);
+        return {
+            kind: "planned",
+            tile,
+            ascii,
+            label: b.title,
+        };
+    }
+    return { kind: b.status, label: b.title };
+}
+function cellFromTimer(t) {
+    return {
+        kind: "timer",
+        status: t.status,
+        label: t.event,
+    };
+}
+function occupySlots(map, startMs, endMs, cell, mode) {
+    let startSlot = Math.floor(startMs / SLOT_MS) * SLOT_MS;
+    let endSlot;
+    if (mode === "timer-inclusive") {
+        endSlot = Math.floor(endMs / SLOT_MS) * SLOT_MS; // inclusive
+    }
+    else {
+        // half-open [start, end): last slot whose start < end
+        endSlot = Math.floor((endMs - 1) / SLOT_MS) * SLOT_MS;
+        if (endMs <= startMs)
+            return;
+    }
+    if (endSlot < startSlot)
+        return;
+    // Align startSlot to be >= startMs floor already done
+    for (let s = startSlot; s <= endSlot; s += SLOT_MS) {
+        if (mode === "half-open") {
+            if (s < startMs || s >= endMs)
+                continue;
+        }
+        const arr = map.get(s) ?? [];
+        arr.push(cell);
+        map.set(s, arr);
+    }
+}
+function fmtHm(d) {
+    const hh = String(d.getHours()).padStart(2, "0");
+    const mm = String(d.getMinutes()).padStart(2, "0");
+    return `${hh}:${mm}`;
+}
+function detailTimeRange(startIso, endIso) {
+    return `${fmtHm(new Date(startIso))}-${fmtHm(new Date(endIso))}`;
+}
+function overlaps(aStart, aEnd, bStart, bEnd) {
+    return aStart < bEnd && aEnd > bStart;
+}
+/** Build full TimelineResult from in-memory events (shared by sqlite/in-memory repos). */
+export function buildTimelineFromEvents(opts) {
+    const { from, to, now, format } = opts;
+    const slotMap = new Map();
+    for (const b of opts.blocks) {
+        const cell = cellFromBlock(b);
+        occupySlots(slotMap, new Date(b.start).getTime(), new Date(b.end).getTime(), cell, "half-open");
+    }
+    for (const t of opts.timers) {
+        const startMs = new Date(t.started_at).getTime();
+        const endMs = t.status === "running"
+            ? now.getTime()
+            : startMs + t.accumulated_ms;
+        occupySlots(slotMap, startMs, endMs, cellFromTimer(t), "timer-inclusive");
+    }
+    // Build dense hour rows from `from` (inclusive hour) to `to` (exclusive hour end?)
+    // Window: from=04:00, to=14:00 → hours 04..13 (10 rows) when to is exclusive end?
+    // Design: now=9:32 → 04:00–14:00, 共 10 行. That's hours 04,05,...,13 = 10 hours.
+    // So from inclusive, to exclusive (to is the end boundary, not a row).
+    const hours = [];
+    const cursor = new Date(from);
+    cursor.setMinutes(0, 0, 0);
+    const endBound = new Date(to);
+    endBound.setMinutes(0, 0, 0);
+    while (cursor.getTime() < endBound.getTime()) {
+        const hourStartMs = cursor.getTime();
+        const cells = [];
+        for (let m = 0; m < 6; m++) {
+            const slotMs = hourStartMs + m * SLOT_MS;
+            const cands = slotMap.get(slotMs) ?? [];
+            cells.push(mergeTimelineCells(cands));
+        }
+        hours.push({
+            hour: formatHourLabel(cursor),
+            hourStartIso: cursor.toISOString(),
+            cells,
+        });
+        cursor.setHours(cursor.getHours() + 1);
+    }
+    // Details
+    const wStart = from.getTime();
+    const wEnd = to.getTime();
+    const details = [];
+    for (const b of opts.blocks) {
+        const cell = cellFromBlock(b);
+        const sym = resolveCellSymbol(cell, format);
+        const bStart = new Date(b.start).getTime();
+        const bEnd = new Date(b.end).getTime();
+        // S45: is_break 判定——标题含「休息」/「break」/「放松」/「空闲」或 category 是闲散
+        const titleLower = b.title.toLowerCase();
+        const isBreak = /休息|break|放松|空闲|歇|摸鱼|发呆/.test(b.title) ||
+            (b.category_name ?? "").includes("闲散");
+        details.push({
+            time: detailTimeRange(b.start, b.end),
+            symbol: sym,
+            title: b.title,
+            status: b.status,
+            in_window: overlaps(bStart, bEnd, wStart, wEnd),
+            category_id: b.category_id ?? null,
+            category_name: b.category_name ?? null,
+            category_emoji: b.category_emoji ?? null,
+            is_break: isBreak,
+            start_ms: bStart,
+            end_ms: bEnd,
+            duration_min: Math.round((bEnd - bStart) / 60000),
+        });
+    }
+    for (const t of opts.timers) {
+        const cell = cellFromTimer(t);
+        const sym = resolveCellSymbol(cell, format);
+        const startMs = new Date(t.started_at).getTime();
+        const endMs = t.status === "running" ? now.getTime() : startMs + t.accumulated_ms;
+        details.push({
+            time: detailTimeRange(t.started_at, new Date(endMs).toISOString()),
+            symbol: sym,
+            title: t.event,
+            status: t.status === "running" ? "timer_running" : "timer_paused",
+            in_window: overlaps(startMs, endMs, wStart, wEnd),
+            // timer 通常不参与分组（用户主动计时，独立性强）
+            category_id: null,
+            category_name: null,
+            category_emoji: null,
+            is_break: false,
+            start_ms: startMs,
+            end_ms: endMs,
+            duration_min: Math.round((endMs - startMs) / 60000),
+        });
+    }
+    // sort: in_window first, then by time string
+    details.sort((a, b) => {
+        if (a.in_window !== b.in_window)
+            return a.in_window ? -1 : 1;
+        return a.time.localeCompare(b.time);
+    });
+    const rendered = renderTimelineCells({
+        hours,
+        nowIso: now.toISOString(),
+        format,
+        details,
+        boundaryEllipsis: true,
+    });
+    return {
+        window: {
+            from: from.toISOString(),
+            to: to.toISOString(),
+            now: now.toISOString(),
+        },
+        rows: rendered.rows,
+        details,
+        rendered_text: rendered.rendered_text,
+        legend: rendered.legend,
+    };
+}
+export function createTimelineTools(repo) {
+    return {
+        async renderTimeline(filters) {
+            if (!filters.user_id) {
+                throw new Error("user_id 为必填参数");
+            }
+            if (filters.from !== undefined &&
+                filters.to !== undefined &&
+                filters.from > filters.to) {
+                throw new Error("开始时间不能晚于结束时间");
+            }
+            const userId = effectiveUserId(filters);
+            return repo.renderTimeline({ ...filters, user_id: userId });
+        },
+    };
+}