chatccc 0.2.251 → 0.2.253

package/dist/deepccc-agent/src/progress/terminal-renderer.js

@@ -0,0 +1,264 @@
+/**
+ * progress/terminal-renderer.ts — 终端"过程区块"渲染器
+ *
+ * 把 ProgressView 渲染为终端里的一块固定区域（对应飞书过程卡片）：
+ *   - 状态行：生成中 / 完成 / 已停止 / 异常结束
+ *   - 工具行：每个工具调用一行（emoji + 名称 + ✓/✗ + 摘要），不再滚屏刷 JSON
+ *   - 正文行：模型流式输出，原地更新不滚动
+ *
+ * 实现要点：
+ *   - 隐藏光标（\x1b[?25l）→ 每帧整块重绘（\x1b[{n}A 上移 + \x1b[2K 清行 + \x1b[J 清下方）
+ *   - 帧节流合并重绘，避免高频文本增量导致闪烁
+ *   - 每行按显示宽度截断（CJK/emoji 算 2 列），保证永不折行：一旦折行，
+ *     实际占用的屏幕行数会超过 blockLines 计数，下次重绘上移行数不足，
+ *     会清掉区块上方的历史内容（用户输入的问题被"吃掉"）。
+ *   - end() 时把终态区块定型留在屏幕上（与飞书完成卡片留在消息流语义一致），恢复光标
+ */
+import { getToolEmoji, truncateContent } from "./cards-helpers.js";
+import { progressView } from "./view.js";
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+/** 生成中标题后的心跳点号动画帧（1 → 2 → 3 → 2 循环，避免跳变感） */
+const ANIM_FRAMES = ["·", "··", "···", "··"];
+const ANSI_TOKEN = /\x1b\[[0-9;]*m/;
+/** 单个字符在终端里的显示列宽：CJK/emoji 占 2 列，控制符/ZWJ/变体选择符占 0 列 */
+export function charWidth(ch) {
+    const code = ch.codePointAt(0);
+    if (code < 32 || (code >= 0x7f && code <= 0xa0))
+        return 0; // 控制字符
+    if (code === 0x200d || code === 0xfe0e || code === 0xfe0f)
+        return 0; // ZWJ / VS15 / VS16
+    if ((code >= 0x1100 && code <= 0x115f) || // 谚文 Jamo
+        (code >= 0x2e80 && code <= 0x303f) || // CJK 部首 / 标点
+        (code >= 0x3040 && code <= 0xa4cf) || // 假名 / 汉字 / 谚文 / 彝文
+        (code >= 0xac00 && code <= 0xd7a3) || // 谚文音节
+        (code >= 0xf900 && code <= 0xfaff) || // CJK 兼容汉字
+        (code >= 0xfe30 && code <= 0xfe6f) || // CJK 兼容形式
+        (code >= 0xff00 && code <= 0xff60) || // 全角形式
+        (code >= 0xffe0 && code <= 0xffe6) || // 全角符号
+        (code >= 0x2600 && code <= 0x27bf) || // 杂项符号 + Dingbats（emoji 呈现 2 列）
+        (code >= 0x1f000 && code <= 0x1faff) // emoji 补充区
+    ) {
+        return 2;
+    }
+    return 1;
+}
+/**
+ * 按终端显示宽度截断一行（CJK/emoji 计 2 列），ANSI 序列零宽且永不截断。
+ * 截断位置若处于未闭合的颜色状态，自动补 \x1b[0m，避免颜色泄漏到后续输出。
+ */
+export function clipToWidth(s, maxCols) {
+    if (maxCols <= 0)
+        return "";
+    let out = "";
+    let visible = 0;
+    let colorOpen = false;
+    let i = 0;
+    while (i < s.length) {
+        if (s.charCodeAt(i) === 0x1b) {
+            const m = ANSI_TOKEN.exec(s.slice(i));
+            if (m && m.index === 0) {
+                out += m[0];
+                colorOpen = m[0] !== "\x1b[0m";
+                i += m[0].length;
+                continue;
+            }
+        }
+        const cp = s.codePointAt(i);
+        const ch = String.fromCodePoint(cp);
+        const w = charWidth(ch);
+        if (visible + w > maxCols)
+            break;
+        out += ch;
+        visible += w;
+        i += ch.length;
+    }
+    if (colorOpen)
+        out += "\x1b[0m";
+    return out;
+}
+function buildStatusLine(view) {
+    switch (view.status) {
+        case "done":
+            return `${BOLD}${GREEN}✅ 完成${RESET}`;
+        case "stopped":
+            return `${YELLOW}⏹ 已停止${RESET}`;
+        case "error":
+            return `${RED}❌ 异常结束${RESET}`;
+        case "generating": {
+            const hint = view.showStop ? `${DIM}  ·  Ctrl+C 停止${RESET}` : "";
+            return `⏳ ${view.headerTitle}${hint}`;
+        }
+    }
+}
+function buildToolLine(tool) {
+    const emoji = getToolEmoji(tool.name);
+    const mark = tool.status === "running"
+        ? "…"
+        : tool.status === "ok"
+            ? `${GREEN}✓${RESET}`
+            : `${RED}✗${RESET}`;
+    const info = tool.status === "running" ? (tool.detail ?? "") : (tool.summary ?? "");
+    // 摘要/详情用正常色：最终区块里不出现浅色文字（可读性优先）
+    return `  ${emoji} ${tool.name} ${mark} ${info}`;
+}
+/**
+ * 把 ProgressView 展开为区块的完整行列表（不含 ANSI 定位序列，只含内容与颜色）。
+ * 单独导出便于单元测试；每行按终端宽度截断，避免长行折行导致行数计数失准。
+ */
+export function buildBlockLines(view, width, maxBodyLines = 30, maxBodyChars = 12000) {
+    const clip = (s) => clipToWidth(s, width);
+    const lines = [];
+    lines.push(clip(buildStatusLine(view)));
+    for (const tool of view.tools) {
+        lines.push(clip(buildToolLine(tool)));
+    }
+    const body = truncateContent(view.text, maxBodyLines, maxBodyChars);
+    if (body.trim()) {
+        for (const line of body.split("\n")) {
+            lines.push(clip(line));
+        }
+    }
+    else {
+        lines.push(`${DIM}等待 Agent 输出...${RESET}`);
+    }
+    return lines;
+}
+export class TerminalProgressRenderer {
+    out;
+    frameMs;
+    animMs;
+    maxBodyLines;
+    maxBodyChars;
+    view;
+    blockLines = 0;
+    dirty = false;
+    timer = null;
+    ended = false;
+    animFrame = 0;
+    animTimer = null;
+    constructor(opts = {}) {
+        this.out = opts.out ?? process.stdout;
+        this.frameMs = opts.frameMs ?? 66;
+        this.animMs = opts.animMs ?? 300;
+        this.maxBodyLines = opts.maxBodyLines ?? 30;
+        this.maxBodyChars = opts.maxBodyChars ?? 12000;
+        this.view = progressView();
+    }
+    /** 开始一轮区块：隐藏光标并渲染首帧，随后启动生成中心跳动画 */
+    begin(view) {
+        this.view = view;
+        this.out.write(HIDE_CURSOR);
+        this.renderNow(view);
+        this.startAnimation();
+    }
+    /** 标记视图已更新，按帧节流合并重绘（高频增量不闪烁） */
+    render(view) {
+        this.view = view;
+        if (this.ended)
+            return;
+        this.dirty = true;
+        if (this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            if (this.dirty && !this.ended) {
+                this.dirty = false;
+                this.renderNow(this.view);
+            }
+        }, this.frameMs);
+    }
+    /** 强制立即重绘（工具结果、终态等低频率但需及时反馈的事件） */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.ended)
+            return;
+        this.dirty = false;
+        this.renderNow(this.view);
+    }
+    /** 结束一轮：定型终态区块（留在屏幕上），恢复光标，停止动画 */
+    end(view) {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.stopAnimation();
+        this.ended = true;
+        this.renderNow(view);
+        this.out.write(SHOW_CURSOR);
+    }
+    /** 兜底清理：清除未决定时器并恢复光标 */
+    dispose() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.stopAnimation();
+        if (!this.ended) {
+            this.out.write(SHOW_CURSOR);
+        }
+    }
+    startAnimation() {
+        if (this.animMs <= 0 || this.animTimer)
+            return;
+        this.animTimer = setInterval(() => {
+            this.animFrame++;
+            // 终态（done/stopped/error）由 end() 停止；此处兜底跳过，避免结束后还在重绘
+            if (this.ended || this.view.status !== "generating")
+                return;
+            // 无新事件也持续重绘，点号动画让静止期（思考/工具运行中）也有动态感
+            this.renderNow(this.view);
+        }, this.animMs);
+        this.animTimer.unref?.();
+    }
+    stopAnimation() {
+        if (this.animTimer) {
+            clearInterval(this.animTimer);
+            this.animTimer = null;
+        }
+    }
+    renderNow(view) {
+        const width = this.out.columns && this.out.columns > 0 ? this.out.columns : 80;
+        const lines = buildBlockLines(this.applyAnimation(view), width, this.maxBodyLines, this.maxBodyChars);
+        const newLines = lines.length;
+        if (this.blockLines > 0) {
+            // 关键：光标此刻停在区块【最后一行】行尾，回到区块第一行只需上移
+            // blockLines - 1 行。上移 blockLines 行会每帧多上移 1 行，把区块上方
+            // 的历史内容逐行"吃掉"（用户看到的"一行一行往上吃"）。
+            this.out.write(`\x1b[${this.blockLines - 1}A`);
+            this.out.write("\r");
+        }
+        for (let i = 0; i < lines.length; i++) {
+            this.out.write(`\r\x1b[2K${lines[i]}`);
+            if (i < lines.length - 1) {
+                this.out.write("\n");
+            }
+        }
+        if (newLines < this.blockLines) {
+            // 新区块比旧区块短：清掉下方多出的行
+            this.out.write("\n");
+            for (let i = 0; i < this.blockLines - newLines; i++) {
+                this.out.write("\x1b[2K\n");
+            }
+        }
+        this.out.write("\x1b[J");
+        this.blockLines = newLines;
+    }
+    /** 生成中阶段在标题后叠加心跳点号动画；终态原样返回（buildBlockLines 保持纯函数可测） */
+    applyAnimation(view) {
+        if (view.status !== "generating")
+            return view;
+        const base = view.headerTitle.replace(/\.\.\.\s*$/, "").trim();
+        const dots = ANIM_FRAMES[this.animFrame % ANIM_FRAMES.length];
+        return { ...view, headerTitle: `${base} ${dots}` };
+    }
+}

package/dist/deepccc-agent/src/progress/view.js

@@ -0,0 +1,30 @@
+/**
+ * progress/view.ts — 平台无关的"过程进度"视图模型
+ *
+ * 这是飞书过程卡片与终端过程区块共享的唯一数据模型：
+ *  - 飞书：buildProgressCard(view) 把 ProgressView 渲染为卡片 JSON
+ *  - 终端：TerminalProgressRenderer 把 ProgressView 渲染为 ANSI 区块
+ *  - 事件流：reduceProgress(prev, event) 把 ChatEvent 增量合并进 ProgressView
+ *
+ * 语义与飞书卡片对齐：
+ *  - headerTitle 是"生成中"阶段展示的标题（如"正在启动 Agent · 0秒"）
+ *  - status 决定终态外观（完成 / 已停止 / 异常结束）
+ *  - text 是正文累积（对应卡片 main_content / 终端区块正文）
+ *  - tools 是本轮工具调用列表（飞书卡片暂不展示，终端折叠为单行）
+ */
+/** 创建 ProgressView，未提供的字段使用与飞书 buildProgressCard 一致的默认值 */
+export function progressView(init = {}) {
+    return {
+        status: init.status ?? "generating",
+        headerTitle: init.headerTitle ?? "生成中...",
+        headerTemplate: init.headerTemplate ?? "blue",
+        text: init.text ?? "",
+        tools: init.tools ?? [],
+        showStop: init.showStop ?? true,
+        updatedAt: Date.now(),
+    };
+}
+/** 只读浅拷贝并覆盖部分字段，返回新视图（reducer 的不可变更新用） */
+export function withProgressView(prev, patch) {
+    return { ...prev, ...patch, updatedAt: Date.now() };
+}

package/dist/deepccc-agent/src/raw-stream-log.js

@@ -0,0 +1,106 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, readdir, rm, stat, unlink } from "node:fs/promises";
+import { once } from "node:events";
+import { join } from "node:path";
+import { createGzip } from "node:zlib";
+export function sanitizeLogPathSegment(value) {
+    const safe = value.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^[._]+|_+$/g, "");
+    return safe || "unknown";
+}
+async function cleanupOldRawStreamLogs(rootDir, retentionDays) {
+    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
+        return;
+    const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+    const visit = async (dir) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        await Promise.all(entries.map(async (entry) => {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await visit(path);
+                try {
+                    await rm(path, { recursive: false });
+                }
+                catch {
+                    // Directory is not empty or already gone.
+                }
+                return;
+            }
+            if (!entry.isFile())
+                return;
+            try {
+                const info = await stat(path);
+                if (info.mtimeMs < cutoff)
+                    await rm(path, { force: true });
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
+        }));
+    };
+    await visit(rootDir);
+}
+export async function createRawStreamLog(options) {
+    if (!options.enabled)
+        return null;
+    const maxBytes = Math.max(0, Math.floor(options.maxBytesPerTurn));
+    const tool = sanitizeLogPathSegment(options.tool);
+    const session = sanitizeLogPathSegment(options.sessionId);
+    const label = sanitizeLogPathSegment(options.label);
+    const dir = join(options.rootDir, tool, session);
+    await mkdir(dir, { recursive: true });
+    void cleanupOldRawStreamLogs(join(options.rootDir, tool), options.retentionDays);
+    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const filePath = join(dir, `${timestamp}-${label}.jsonl.gz`);
+    const output = createWriteStream(filePath);
+    const gzip = createGzip();
+    gzip.pipe(output);
+    let bytes = 0;
+    let truncated = false;
+    let ended = false;
+    const writeLine = (line) => {
+        if (ended || truncated)
+            return;
+        const payload = `${line}\n`;
+        const payloadBytes = Buffer.byteLength(payload, "utf-8");
+        if (maxBytes > 0 && bytes + payloadBytes > maxBytes) {
+            const marker = JSON.stringify({
+                type: "deepccc_raw_stream_log_truncated",
+                reason: "max_bytes_per_turn_exceeded",
+                maxBytesPerTurn: maxBytes,
+                writtenBytes: bytes,
+            });
+            gzip.write(`${marker}\n`);
+            truncated = true;
+            return;
+        }
+        bytes += payloadBytes;
+        gzip.write(payload);
+    };
+    const close = async ({ keep }) => {
+        if (ended)
+            return;
+        ended = true;
+        gzip.end();
+        try {
+            await once(output, "finish");
+        }
+        catch {
+            // Ignore close errors; caller cannot recover from debug log failures.
+        }
+        if (!keep) {
+            try {
+                await unlink(filePath);
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
+        }
+    };
+    return { filePath, writeLine, close };
+}

package/dist/deepccc-agent/src/session-search.js

@@ -0,0 +1,276 @@
+/**
+ * session-search.ts — DeepCCC 历史会话关键词检索
+ *
+ * 供 agent 通过 session_search 工具按需查找很久以前的原始消息/工具调用：
+ * - 主数据源：~/.deepccc/sessions/<sessionId>/context.json（明文 JSON，含 summary、
+ *   messages.content 与结构化 toolCalls）
+ * - 可选数据源：~/.deepccc/raw-stream-logs/deepccc/<sessionId>/*.jsonl.gz（gzip 原始流，
+ *   逐行解压检索，默认关闭）
+ *
+ * 纯关键词匹配（多词 AND、大小写不敏感），不依赖向量索引。
+ */
+import { createReadStream, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { createGunzip } from "node:zlib";
+import { RAW_STREAM_LOGS_DIR } from "./config.js";
+import { DEFAULT_BUILTIN_CONTEXT_DIR } from "./context.js";
+const DEFAULT_MAX_RESULTS = 20;
+const MAX_RESULTS_CAP = 50;
+const DEFAULT_MAX_SNIPPET_CHARS = 400;
+const MAX_SNIPPET_CHARS_CAP = 2_000;
+const DEFAULT_MAX_RAW_LOG_BYTES_PER_FILE = 4 * 1024 * 1024;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length > 0);
+}
+/** 多词 AND、大小写不敏感：候选文本必须包含全部关键词 */
+function matchesTerms(text, terms) {
+    const lower = text.toLowerCase();
+    return terms.every((term) => lower.includes(term));
+}
+function makeSnippet(text, terms, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const lower = text.toLowerCase();
+    let hitIndex = -1;
+    for (const term of terms) {
+        const index = lower.indexOf(term);
+        if (index !== -1) {
+            hitIndex = index;
+            break;
+        }
+    }
+    const half = Math.floor(maxChars / 2);
+    if (hitIndex === -1) {
+        return `${text.slice(0, half)}…${text.slice(-half)}`;
+    }
+    const start = Math.max(0, hitIndex - half);
+    const end = Math.min(text.length, hitIndex + half);
+    const prefix = start > 0 ? "…" : "";
+    const suffix = end < text.length ? "…" : "";
+    return `${prefix}${text.slice(start, end)}${suffix}`;
+}
+function searchContextDir(query, options, maxResults, maxSnippetChars) {
+    const dir = options.contextDir ?? DEFAULT_BUILTIN_CONTEXT_DIR;
+    const terms = tokenize(query);
+    const matches = [];
+    if (terms.length === 0 || !existsSync(dir)) {
+        return { matches, scannedSessions: 0, totalHits: 0 };
+    }
+    const restrictTo = options.sessionId?.trim();
+    let scannedSessions = 0;
+    let totalHits = 0;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        if (restrictTo && entry.name !== restrictTo)
+            continue;
+        const filePath = join(dir, entry.name, "context.json");
+        if (!existsSync(filePath))
+            continue;
+        let state;
+        try {
+            state = JSON.parse(readFileSync(filePath, "utf8"));
+        }
+        catch {
+            continue; // 损坏或非 JSON 的会话文件跳过
+        }
+        if (!state || typeof state !== "object")
+            continue;
+        if (restrictTo && state.sessionId !== restrictTo && entry.name !== restrictTo)
+            continue;
+        scannedSessions += 1;
+        const sessionId = typeof state.sessionId === "string" ? state.sessionId : entry.name;
+        if (typeof state.summary === "string" && matchesTerms(state.summary, terms)) {
+            totalHits += 1;
+            matches.push({
+                sessionId,
+                source: "summary",
+                snippet: makeSnippet(state.summary, terms, maxSnippetChars),
+                filePath,
+            });
+        }
+        if (Array.isArray(state.messages)) {
+            state.messages.forEach((message, messageIndex) => {
+                if (!message || typeof message !== "object")
+                    return;
+                const raw = message;
+                const role = raw.role === "user" || raw.role === "assistant" ? raw.role : undefined;
+                if (typeof raw.content === "string" && matchesTerms(raw.content, terms)) {
+                    totalHits += 1;
+                    matches.push({
+                        sessionId,
+                        source: "context",
+                        role,
+                        messageIndex,
+                        snippet: makeSnippet(raw.content, terms, maxSnippetChars),
+                        filePath,
+                    });
+                }
+                if (Array.isArray(raw.toolCalls)) {
+                    raw.toolCalls.forEach((call, toolCallIndex) => {
+                        if (!call || typeof call !== "object")
+                            return;
+                        const callRaw = call;
+                        const name = typeof callRaw.name === "string" ? callRaw.name : "";
+                        const input = typeof callRaw.input === "string" ? callRaw.input : "";
+                        const output = typeof callRaw.output === "string" ? callRaw.output : "";
+                        if (name.length === 0 && input.length === 0 && output.length === 0)
+                            return;
+                        const haystack = [name, input, output].join("\n");
+                        if (!matchesTerms(haystack, terms))
+                            return;
+                        totalHits += 1;
+                        const source = output || input || name;
+                        matches.push({
+                            sessionId,
+                            source: "context",
+                            role,
+                            messageIndex,
+                            toolCallIndex,
+                            toolCallName: name,
+                            snippet: makeSnippet(source, terms, maxSnippetChars),
+                            filePath,
+                        });
+                    });
+                }
+            });
+        }
+    }
+    return { matches: matches.slice(0, maxResults), scannedSessions, totalHits };
+}
+async function searchRawLogs(query, options, maxResults, maxSnippetChars) {
+    const terms = tokenize(query);
+    const rootDir = options.rawLogsDir ?? RAW_STREAM_LOGS_DIR;
+    const matches = [];
+    if (terms.length === 0 || !existsSync(rootDir)) {
+        return { matches, scannedFiles: 0, truncated: false };
+    }
+    const toolRoot = join(rootDir, "deepccc");
+    if (!existsSync(toolRoot))
+        return { matches, scannedFiles: 0, truncated: false };
+    const restrictTo = options.sessionId?.trim();
+    const maxBytesPerFile = Math.max(0, options.maxRawLogBytesPerFile ?? DEFAULT_MAX_RAW_LOG_BYTES_PER_FILE);
+    // 收集所有 .jsonl.gz 文件，按 mtime 新→旧排序（最新轮次优先）
+    const files = [];
+    for (const sessionEntry of readdirSync(toolRoot, { withFileTypes: true })) {
+        if (!sessionEntry.isDirectory())
+            continue;
+        if (restrictTo && sessionEntry.name !== restrictTo)
+            continue;
+        const sessionDir = join(toolRoot, sessionEntry.name);
+        let entries;
+        try {
+            entries = readdirSync(sessionDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const fileEntry of entries) {
+            if (!fileEntry.isFile() || !fileEntry.name.endsWith(".jsonl.gz"))
+                continue;
+            const filePath = join(sessionDir, fileEntry.name);
+            try {
+                const info = statSync(filePath);
+                files.push({ path: filePath, sessionId: sessionEntry.name, mtimeMs: info.mtimeMs });
+            }
+            catch {
+                // 无法 stat 的文件跳过
+            }
+        }
+    }
+    files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    let scannedFiles = 0;
+    let truncated = false;
+    for (const file of files) {
+        if (matches.length >= maxResults) {
+            truncated = true;
+            break;
+        }
+        scannedFiles += 1;
+        const snippets = await searchGzipFileLines(file.path, terms, maxBytesPerFile, maxSnippetChars);
+        for (const snippet of snippets) {
+            matches.push({
+                sessionId: file.sessionId,
+                source: "raw-log",
+                snippet,
+                filePath: file.path,
+            });
+            if (matches.length >= maxResults)
+                break;
+        }
+    }
+    return { matches: matches.slice(0, maxResults), scannedFiles, truncated };
+}
+async function searchGzipFileLines(filePath, terms, maxBytes, maxSnippetChars) {
+    const hits = [];
+    let bytes = 0;
+    try {
+        const source = createReadStream(filePath);
+        const gunzip = createGunzip();
+        // 防崩溃（线上事故）：截断/损坏的 gzip 会在 zlib 层 emit 'error'（如
+        // "unexpected end of file"）。若无人监听，错误事件会升级为 uncaughtException
+        // 直接杀死整个服务（崩溃黑匣子 exit(1)）。显式挂监听把错误降级为
+        // “跳过该文件”：destroy 流让 for await 正常结束，不再冒泡。
+        source.on("error", () => gunzip.destroy());
+        gunzip.on("error", () => gunzip.destroy());
+        const reader = createInterface({ input: source.pipe(gunzip), crlfDelay: Infinity });
+        // readline 会把 input 流的 error 转发到自己身上，同样需要监听避免冒泡
+        reader.on("error", () => { });
+        for await (const line of reader) {
+            bytes += Buffer.byteLength(line, "utf-8");
+            if (bytes > maxBytes)
+                break;
+            if (!matchesTerms(line, terms))
+                continue;
+            hits.push(makeSnippet(line, terms, maxSnippetChars));
+            if (hits.length >= 50)
+                break;
+        }
+    }
+    catch {
+        // 损坏的 gzip 文件按 best-effort 跳过
+    }
+    return hits;
+}
+/**
+ * 关键词检索历史会话存档。context.json 为同步扫描；raw-stream-logs 为
+ * gzip 逐行解压（异步，仅 options.includeRawLogs 时启用）。
+ */
+export async function searchBuiltinSessions(query, options = {}) {
+    const terms = tokenize(query);
+    const maxResults = clamp(options.maxResults ?? DEFAULT_MAX_RESULTS, 1, MAX_RESULTS_CAP);
+    const maxSnippetChars = clamp(options.maxSnippetChars ?? DEFAULT_MAX_SNIPPET_CHARS, 80, MAX_SNIPPET_CHARS_CAP);
+    if (terms.length === 0) {
+        return {
+            query,
+            terms,
+            matches: [],
+            truncated: false,
+            scannedSessions: 0,
+            scannedRawLogFiles: 0,
+        };
+    }
+    const contextResult = searchContextDir(query, options, maxResults, maxSnippetChars);
+    let rawResult = { matches: [], scannedFiles: 0, truncated: false };
+    if (options.includeRawLogs) {
+        rawResult = await searchRawLogs(query, options, maxResults, maxSnippetChars);
+    }
+    const matches = [...contextResult.matches, ...rawResult.matches].slice(0, maxResults);
+    const truncated = contextResult.totalHits > maxResults || rawResult.truncated || rawResult.matches.length > maxResults;
+    return {
+        query,
+        terms,
+        matches,
+        truncated,
+        scannedSessions: contextResult.scannedSessions,
+        scannedRawLogFiles: rawResult.scannedFiles,
+    };
+}