@armadra/agent 0.7.4 → 0.7.5

package/dist/session/offload.js

@@ -0,0 +1,195 @@
+/**
+ * 会话图片卸载（#170）：被 `context_edit` 改写的旧消息不再进上下文，内存里只留它在会话文件中的行位置，
+ * 图片 base64 需要时再从文件回读。JSONL 格式不变。
+ *
+ * - 对象：活动分支上、被活动分支上的 `context_edit`（任何 reason）改写的 `message` 条目里的 `image` 块；
+ *   不在活动分支上的条目一律保持原文（rewind 回到编辑点之前、`/tree` 换分支时回读）；
+ * - 打开文件时先扫一遍 `context_edit` 行（只解码行首判断类型）收集目标，读条目时目标里的图片解析完
+ *   随即剥掉，峰值不再含全部旧图；随后按活动分支对齐（不在分支上的编辑目标回读）；
+ * - 卸载**不改共享的 ImageBlock**（驻留 block 被其它条目 / 会话共享）：`entry.message` 换成浅拷贝，
+ *   `content` 换新数组，image 块换成 `data: ""` 的占位；
+ * - 回读：按行位置 `readSync` 一行、`JSON.parse`，校验 id 与内容块数，图片经 `internImage` 驻留后
+ *   **就地**放回占位所在的数组（之前拿到同一消息对象的调用方随之看到原图）；读不回（文件被外部改写）时
+ *   保留 `""` 并告警，不再重试；
+ * - `original(entry)`：给 `getEntries` / `fork` 的原文副本，不改内存状态。
+ */
+import { closeSync, openSync, readSync } from "node:fs";
+import { internImage } from "../ai/image-intern.js";
+import { forEachLineSync, lineTypeOf } from "./line-reader.js";
+import { collectContextEdits } from "./projection.js";
+function isImage(block) {
+    return (typeof block === "object" &&
+        block !== null &&
+        block.type === "image" &&
+        typeof block.data === "string");
+}
+function contentOf(entry) {
+    if (entry.type !== "message")
+        return undefined;
+    const content = entry.message.content;
+    return Array.isArray(content) ? content : undefined;
+}
+/** `message` 条目的内容里有图片块。 */
+export function hasImages(entry) {
+    return contentOf(entry)?.some(isImage) === true;
+}
+/** 读文件里 `locator` 处的一行并解析。 */
+export function readLineAt(file, locator) {
+    const fd = openSync(file, "r");
+    try {
+        const buf = Buffer.allocUnsafe(locator.length);
+        let read = 0;
+        while (read < locator.length) {
+            const n = readSync(fd, buf, read, locator.length - read, locator.offset + read);
+            if (n === 0)
+                throw new Error("unexpected end of file");
+            read += n;
+        }
+        return JSON.parse(buf.toString("utf8"));
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** 文件里全部 `context_edit` 的目标 id（只解析 context_edit 行；读不了时为空集）。 */
+export function editTargets(file) {
+    const targets = new Set();
+    try {
+        forEachLineSync(file, (line) => {
+            if (lineTypeOf(line)?.type !== "context_edit")
+                return;
+            try {
+                const id = JSON.parse(line.toString("utf8")).targetId;
+                if (typeof id === "string")
+                    targets.add(id);
+            }
+            catch {
+                // 末尾半行：随后的 readSessionLines 修复
+            }
+        });
+    }
+    catch {
+        // 读不了：由随后的 readSessionLines 报错
+    }
+    return targets;
+}
+const placeholder = (block) => ({ ...block, data: "" });
+export class ImageOffload {
+    warn;
+    /** 含图 message 条目的行位置（只有已落盘的条目才有）。 */
+    locators = new Map();
+    offloaded = new Set();
+    constructor(warn = () => { }) {
+        this.warn = warn;
+    }
+    /** 记下条目的行位置；不含图片的条目忽略。 */
+    track(entry, locator) {
+        if (hasImages(entry))
+            this.locators.set(entry.id, locator);
+    }
+    /** 读文件时逐行调用：记下行位置；`strip` 时就地换成占位（刚解析的对象，别处没有引用）。 */
+    load(line, locator, strip) {
+        if (typeof line.id !== "string" || !hasImages(line))
+            return;
+        this.locators.set(line.id, locator);
+        if (!strip)
+            return;
+        const content = contentOf(line);
+        content.forEach((block, i) => {
+            if (isImage(block))
+                content[i] = placeholder(block);
+        });
+        this.offloaded.add(line.id);
+    }
+    isOffloaded(id) {
+        return this.offloaded.has(id);
+    }
+    /** 已卸载的条目数（测试与诊断用）。 */
+    get size() {
+        return this.offloaded.size;
+    }
+    /** 把条目里的图片换成占位；没有行位置（未落盘、不含图）或已卸载时返回 false。 */
+    offload(entry) {
+        if (entry.type !== "message" || this.offloaded.has(entry.id))
+            return false;
+        const content = contentOf(entry);
+        if (content === undefined || !this.locators.has(entry.id))
+            return false;
+        entry.message = {
+            ...entry.message,
+            content: content.map((block) => (isImage(block) ? placeholder(block) : block)),
+        };
+        this.offloaded.add(entry.id);
+        return true;
+    }
+    /** 就地放回图片；读不回时返回 false（占位保留，之后不再卸载 / 回读这一条）。 */
+    hydrate(file, entry) {
+        if (!this.offloaded.has(entry.id))
+            return true;
+        this.offloaded.delete(entry.id);
+        const source = this.read(file, entry);
+        const content = contentOf(entry);
+        if (source === undefined || content === undefined)
+            return false;
+        const originals = contentOf(source) ?? [];
+        content.forEach((block, i) => {
+            const original = originals[i];
+            if (isImage(block) && block.data === "" && isImage(original)) {
+                content[i] = internImage(original);
+            }
+        });
+        return true;
+    }
+    /** 原文：已卸载的条目从文件读一份新副本（图片驻留），否则原样返回。读不回时返回占位版本。 */
+    original(file, entry) {
+        if (!this.offloaded.has(entry.id))
+            return entry;
+        const copy = this.read(file, entry);
+        if (copy === undefined)
+            return entry;
+        const content = contentOf(copy) ?? [];
+        content.forEach((block, i) => {
+            if (isImage(block))
+                content[i] = internImage(block);
+        });
+        return copy;
+    }
+    /** 按活动分支对齐：分支上被生效编辑改写的含图条目卸载，其余已卸载的回读。 */
+    sync(file, branch, index) {
+        const edits = collectContextEdits(branch);
+        const onBranch = new Set();
+        for (const entry of branch)
+            if (edits.has(entry.id))
+                onBranch.add(entry.id);
+        for (const id of [...this.offloaded]) {
+            const entry = index.get(id);
+            if (entry !== undefined && !onBranch.has(id))
+                this.hydrate(file, entry);
+        }
+        for (const id of onBranch) {
+            const entry = index.get(id);
+            if (entry !== undefined)
+                this.offload(entry);
+        }
+    }
+    /** 从文件读回条目（新对象）；不成功时告警、忘掉行位置并返回 undefined。 */
+    read(file, entry) {
+        const locator = this.locators.get(entry.id);
+        try {
+            if (locator === undefined)
+                throw new Error("no line locator");
+            const line = readLineAt(file, locator);
+            const content = line.id === entry.id ? contentOf(line) : undefined;
+            if (content === undefined || content.length !== contentOf(entry)?.length) {
+                throw new Error("line does not match the entry");
+            }
+            return line;
+        }
+        catch (error) {
+            this.locators.delete(entry.id);
+            this.offloaded.delete(entry.id);
+            this.warn(`cannot read session entry ${entry.id} back from ${file}: ${String(error)}`);
+            return undefined;
+        }
+    }
+}

package/dist/session/store.d.ts

@@ -7,6 +7,7 @@
  * - 锁：`<file>.lock`（O_EXCL 创建，内容为 pid）；持锁进程已不在 → 视为陈旧锁并接管。
  * - prune：移到 `<sessionsRoot>/.trash/`，文件名前缀删除时间；`purgeTrash` 清理超过 7 天的。
  */
+import type { LineLocator } from "./offload.js";
 import type { SessionLine } from "./types.js";
 export declare const SESSION_FILE_SUFFIX = ".jsonl";
 export declare const TRASH_DIR_NAME = ".trash";
@@ -22,6 +23,8 @@ export interface ReadResult {
     lines: SessionLine[];
     /** 末尾半行被截掉时为 true。 */
     repairedTail: boolean;
+    /** 给了 `onLine` 时：读完（含修复）后的文件字节数。 */
+    bytes?: number;
 }
 /** 空白行（同旧口径 `trim() === ""`）：ASCII 空白直接判定，遇到非 ASCII 字节才解码再 trim。 */
 export declare function isBlankLine(line: Buffer): boolean;
@@ -31,11 +34,16 @@ export declare function isBlankLine(line: Buffer): boolean;
  */
 export declare function readSessionLines(file: string, options?: {
     repair?: boolean;
+    /** 每解析出一行就回调（行位置不含行尾；#170 图片卸载在这里就地剥掉图片）。 */
+    onLine?: (line: SessionLine, locator: LineLocator) => void;
 }): ReadResult;
-/** 追加若干行（一次 write，O_APPEND）。 */
-export declare function appendLines(file: string, lines: readonly SessionLine[]): void;
-/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
-export declare function writeNewSessionFile(file: string, lines: readonly SessionLine[]): void;
+/** 追加若干行（一次 write，O_APPEND），返回写入的字节数。 */
+export declare function appendLines(file: string, lines: readonly SessionLine[]): number;
+/**
+ * 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。返回每行的字节数（不含行尾，与
+ * `lines` 同序）。
+ */
+export declare function writeNewSessionFile(file: string, lines: readonly SessionLine[]): number[];
 export interface SessionLock {
     readonly path: string;
     release(): void;

package/dist/session/store.js

@@ -57,8 +57,9 @@ export function readSessionLines(file, options = {}) {
                 unterminated = true;
             if (isBlankLine(buf))
                 return;
+            let line;
             try {
-                lines.push(JSON.parse(buf.toString("utf8")));
+                line = JSON.parse(buf.toString("utf8"));
             }
             catch (error) {
                 if (last) {
@@ -71,6 +72,8 @@ export function readSessionLines(file, options = {}) {
                     cause: error,
                 });
             }
+            options.onLine?.(line, { offset, length: buf.length });
+            lines.push(line);
         });
     }
     catch (error) {
@@ -82,32 +85,39 @@ export function readSessionLines(file, options = {}) {
         // 最后一行完整但缺 LF：补上，保证后续追加另起一行。
         appendRaw(file, "\n");
     }
-    return { lines, repairedTail };
+    if (options.onLine === undefined)
+        return { lines, repairedTail };
+    return { lines, repairedTail, bytes: statSync(file).size };
 }
 function appendRaw(file, text) {
     const fd = openSync(file, "a");
     try {
-        writeSync(fd, text);
+        return writeSync(fd, text);
     }
     finally {
         closeSync(fd);
     }
 }
-/** 追加若干行（一次 write，O_APPEND）。 */
+/** 追加若干行（一次 write，O_APPEND），返回写入的字节数。 */
 export function appendLines(file, lines) {
     if (lines.length === 0)
-        return;
-    appendRaw(file, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
+        return 0;
+    return appendRaw(file, lines.map((line) => JSON.stringify(line)).join("\n") + "\n");
 }
-/** 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。 */
+/**
+ * 新建文件：先写临时文件再 rename，避免出现只有半个头的文件。返回每行的字节数（不含行尾，与
+ * `lines` 同序）。
+ */
 export function writeNewSessionFile(file, lines) {
     mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
     if (existsSync(file)) {
         throw new AmaError("session_exists", `session file already exists: ${file}`);
     }
     const tmp = `${file}.${process.pid}.tmp`;
-    writeFileSync(tmp, lines.map((line) => JSON.stringify(line)).join("\n") + "\n", { mode: 0o600 });
+    const texts = lines.map((line) => JSON.stringify(line));
+    writeFileSync(tmp, texts.join("\n") + "\n", { mode: 0o600 });
     renameSync(tmp, file);
+    return texts.map((text) => Buffer.byteLength(text));
 }
 // ---------------------------------------------------------------------------
 // 锁

package/dist/tools/read-lines.d.ts

@@ -10,6 +10,9 @@
  * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
  * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
  *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
  */
 /** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
 export declare const STREAM_READ_THRESHOLD: number;
@@ -25,8 +28,44 @@ export interface LineWindow {
 }
 /** 文件开头至多 `bytes` 字节（一次 `readSync`，用于二进制嗅探）。 */
 export declare function readHead(abs: string, bytes: number): Buffer;
+/** `readHead` 的异步版（#171）。 */
+export declare function readHeadAsync(abs: string, bytes: number): Promise<Buffer>;
+/**
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
+ */
+export declare class LineScanner {
+    private readonly first;
+    private readonly stop;
+    private readonly maxBytes;
+    private readonly lineCap;
+    private readonly lines;
+    private truncatedBy;
+    private collected;
+    private index;
+    private parts;
+    private partBytes;
+    private pending;
+    private skipLF;
+    private bom;
+    private firstChunk;
+    constructor(first: number, stop: number, maxBytes: number);
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf: Buffer, end: number, eof: boolean): number;
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish(): LineWindow;
+    private collecting;
+    private take;
+    private endLine;
+}
 /**
  * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
  * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
  */
 export declare function readLineWindow(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): LineWindow;
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export declare function readLineWindowAsync(abs: string, offset: number, limit: number | undefined, maxBytes: number, chunkBytes?: number): Promise<LineWindow>;

package/dist/tools/read-lines.js

@@ -10,8 +10,12 @@
  * - 按行解码：终止符都是 ASCII，不会落在多字节序列中间，无效字节的替换结果与整段解码相同；
  * - 窗口内单行超过 `maxBytes + LINE_SLACK` 字节时只留开头（这一行必然触发字节截断，
  *   `truncateHead` 至多取它开头 `maxBytes` 字节），超长行不会整行进内存。
+ *
+ * 解析状态机是 `LineScanner`，同步版 `readLineWindow` 与异步版 `readLineWindowAsync` 共用（#171）：
+ * 异步版每块一次 `await`，大文件扫描期间不独占事件循环；峰值内存相同（仍一块缓冲）。
  */
 import { closeSync, openSync, readSync } from "node:fs";
+import { open } from "node:fs/promises";
 /** 超过这个大小的文本文件走字节窗口；不超过的保留整读路径。 */
 export const STREAM_READ_THRESHOLD = 1024 * 1024;
 const CHUNK_BYTES = 64 * 1024;
@@ -37,111 +41,184 @@ export function readHead(abs, bytes) {
         closeSync(fd);
     }
 }
+/** `readHead` 的异步版（#171）。 */
+export async function readHeadAsync(abs, bytes) {
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(bytes);
+        let got = 0;
+        while (got < bytes) {
+            const { bytesRead } = await handle.read(buf, got, bytes - got, null);
+            if (bytesRead === 0)
+                break;
+            got += bytesRead;
+        }
+        return buf.subarray(0, got);
+    }
+    finally {
+        await handle.close();
+    }
+}
 /**
- * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
- * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 按块喂入文件字节的行扫描状态机：第 `first` 行（0 起）到第 `stop` 行（不含）之间的行被收集，
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行），其余行只计数。
  */
-export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
-    const first = offset - 1;
-    const stop = limit === undefined ? Infinity : first + limit;
-    const lineCap = maxBytes + LINE_SLACK;
-    const lines = [];
-    let truncatedBy;
-    let collected = 0;
-    let index = 0; // 已完成的行数
-    let parts = [];
-    let partBytes = 0;
-    let pending = false; // 最后一个终止符之后已有字节
-    let skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
-    let bom = false;
-    const collecting = () => truncatedBy === undefined && index >= first && index < stop;
-    const take = (buf, from, to) => {
-        if (to <= from || partBytes >= lineCap)
+export class LineScanner {
+    first;
+    stop;
+    maxBytes;
+    lineCap;
+    lines = [];
+    truncatedBy;
+    collected = 0;
+    index = 0; // 已完成的行数
+    parts = [];
+    partBytes = 0;
+    pending = false; // 最后一个终止符之后已有字节
+    skipLF = false; // 上一块以 `\r` 结尾：下一块开头的 `\n` 属于同一终止符
+    bom = false;
+    firstChunk = true;
+    constructor(first, stop, maxBytes) {
+        this.first = first;
+        this.stop = stop;
+        this.maxBytes = maxBytes;
+        this.lineCap = maxBytes + LINE_SLACK;
+    }
+    /**
+     * 处理 `buf[0, end)`；`eof` 表示这是最后一块。返回调用方下次读取前应保留在 `buf` 开头的字节数
+     * （只在首块不足 3 字节、还判断不了 BOM 时非零）。
+     */
+    feed(buf, end, eof) {
+        let pos = 0;
+        if (this.firstChunk) {
+            if (end < 3 && !eof)
+                return end;
+            this.firstChunk = false;
+            if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+                this.bom = true;
+                pos = 3;
+            }
+        }
+        if (this.skipLF && pos < end) {
+            if (buf[pos] === LF)
+                pos++;
+            this.skipLF = false;
+        }
+        let nextLF = buf.indexOf(LF, pos);
+        let nextCR = buf.indexOf(CR, pos);
+        while (pos < end) {
+            if (nextLF !== -1 && nextLF < pos)
+                nextLF = buf.indexOf(LF, pos);
+            if (nextCR !== -1 && nextCR < pos)
+                nextCR = buf.indexOf(CR, pos);
+            const lf = nextLF === -1 || nextLF >= end ? end : nextLF;
+            const cr = nextCR === -1 || nextCR >= end ? end : nextCR;
+            const at = Math.min(lf, cr);
+            if (at > pos) {
+                this.pending = true;
+                if (this.collecting())
+                    this.take(buf, pos, at);
+            }
+            if (at === end)
+                break;
+            this.endLine();
+            pos = at + 1;
+            if (at === cr) {
+                if (pos < end) {
+                    if (buf[pos] === LF)
+                        pos++;
+                }
+                else {
+                    this.skipLF = true;
+                }
+            }
+        }
+        return 0;
+    }
+    /** 文件读完：收尾最后一行并给出结果。 */
+    finish() {
+        if (this.pending)
+            this.endLine();
+        const { lines, truncatedBy, bom } = this;
+        return { lines, totalLines: this.index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+    }
+    collecting() {
+        return this.truncatedBy === undefined && this.index >= this.first && this.index < this.stop;
+    }
+    take(buf, from, to) {
+        if (to <= from || this.partBytes >= this.lineCap)
             return;
-        const end = Math.min(to, from + lineCap - partBytes);
-        parts.push(Buffer.from(buf.subarray(from, end)));
-        partBytes += end - from;
-    };
-    const finish = () => {
-        if (collecting()) {
+        const end = Math.min(to, from + this.lineCap - this.partBytes);
+        this.parts.push(Buffer.from(buf.subarray(from, end)));
+        this.partBytes += end - from;
+    }
+    endLine() {
+        if (this.collecting()) {
+            const { parts } = this;
             const line = (parts.length === 1 ? parts[0] : Buffer.concat(parts)).toString("utf8");
-            lines.push(line);
-            collected += Buffer.byteLength(line) + 1;
-            if (collected > maxBytes)
-                truncatedBy = "bytes";
+            this.lines.push(line);
+            this.collected += Buffer.byteLength(line) + 1;
+            if (this.collected > this.maxBytes)
+                this.truncatedBy = "bytes";
         }
-        if (partBytes > 0)
-            parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
-        partBytes = 0;
-        pending = false;
-        index++;
-    };
+        if (this.partBytes > 0)
+            this.parts = []; // 窗口外的行不分配：40 万行时每行一个空数组就是十几 MB 临时垃圾
+        this.partBytes = 0;
+        this.pending = false;
+        this.index++;
+    }
+}
+function scanner(offset, limit, maxBytes) {
+    const first = offset - 1;
+    return new LineScanner(first, limit === undefined ? Infinity : first + limit, maxBytes);
+}
+/**
+ * 读取 `abs` 第 `offset` 行（1 起）开始的至多 `limit` 行（`undefined` 不限，`0` 只计数）；
+ * 收集的行累计 `字节 + 1` 超过 `maxBytes` 后停止收集（含越界的那一行）。`chunkBytes` 只供测试。
+ * 同步版，保留给单测与口径比对；`read` 工具用 `readLineWindowAsync`。
+ */
+export function readLineWindow(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
     const size = Math.max(3, chunkBytes);
     const fd = openSync(abs, "r");
     try {
         const buf = Buffer.alloc(size);
         let carry = 0; // 首块凑满 3 字节判断 BOM
-        let firstChunk = true;
         for (;;) {
             const n = readSync(fd, buf, carry, size - carry, null);
             const end = carry + n;
-            carry = 0;
-            if (n === 0 && end === 0)
+            if (end === 0)
                 break;
-            let pos = 0;
-            if (firstChunk) {
-                if (end < 3 && n > 0) {
-                    carry = end;
-                    continue;
-                }
-                firstChunk = false;
-                if (end >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
-                    bom = true;
-                    pos = 3;
-                }
-            }
-            if (skipLF && pos < end) {
-                if (buf[pos] === LF)
-                    pos++;
-                skipLF = false;
-            }
-            let nextLF = buf.indexOf(LF, pos);
-            let nextCR = buf.indexOf(CR, pos);
-            while (pos < end) {
-                if (nextLF !== -1 && nextLF < pos)
-                    nextLF = buf.indexOf(LF, pos);
-                if (nextCR !== -1 && nextCR < pos)
-                    nextCR = buf.indexOf(CR, pos);
-                const lf = nextLF === -1 || nextLF >= end ? end : nextLF;
-                const cr = nextCR === -1 || nextCR >= end ? end : nextCR;
-                const at = Math.min(lf, cr);
-                if (at > pos) {
-                    pending = true;
-                    if (collecting())
-                        take(buf, pos, at);
-                }
-                if (at === end)
-                    break;
-                finish();
-                pos = at + 1;
-                if (at === cr) {
-                    if (pos < end) {
-                        if (buf[pos] === LF)
-                            pos++;
-                    }
-                    else {
-                        skipLF = true;
-                    }
-                }
-            }
+            carry = scan.feed(buf, end, n === 0);
             if (n === 0)
                 break;
         }
-        if (pending)
-            finish();
     }
     finally {
         closeSync(fd);
     }
-    return { lines, totalLines: index, ...(truncatedBy ? { truncatedBy } : {}), bom };
+    return scan.finish();
+}
+/** `readLineWindow` 的异步版（#171）：每块一次 `await`，结果与同步版相同。 */
+export async function readLineWindowAsync(abs, offset, limit, maxBytes, chunkBytes = CHUNK_BYTES) {
+    const scan = scanner(offset, limit, maxBytes);
+    const size = Math.max(3, chunkBytes);
+    const handle = await open(abs, "r");
+    try {
+        const buf = Buffer.alloc(size);
+        let carry = 0;
+        for (;;) {
+            const { bytesRead: n } = await handle.read(buf, carry, size - carry, null);
+            const end = carry + n;
+            if (end === 0)
+                break;
+            carry = scan.feed(buf, end, n === 0);
+            if (n === 0)
+                break;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return scan.finish();
 }

package/dist/tools/read.js

@@ -13,7 +13,7 @@ import { internImage } from "../ai/image-intern.js";
 import { displayPath, resolvePath } from "./paths.js";
 import { DEFAULT_MAX_LINES, formatSize, toolOutputBytes, truncateHead } from "./truncate.js";
 import { normalizeToLF, splitBom } from "./edit-fuzzy.js";
-import { STREAM_READ_THRESHOLD, readHead, readLineWindow } from "./read-lines.js";
+import { STREAM_READ_THRESHOLD, readHeadAsync, readLineWindowAsync } from "./read-lines.js";
 import { MAX_IMAGE_FILE_BYTES, fitImage, imageMimeFromPath, imageSize, sniffImageMime, } from "./image-file.js";
 export { imageSize } from "./image-file.js";
 const SNIFF_BYTES = 8000;
@@ -99,10 +99,10 @@ export async function executeRead(input, ctx, options = {}) {
     let selected;
     if (info.size > (options.streamThreshold ?? STREAM_READ_THRESHOLD)) {
         // [M-E] 大文件按字节窗口读：只解码要显示的行，结果与整读逐字节相同（D1）
-        if (isBinary(readHead(abs, SNIFF_BYTES)))
+        if (isBinary(await readHeadAsync(abs, SNIFF_BYTES)))
             return error(binaryMessage(shown));
         const want = Math.min(input.limit ?? Infinity, DEFAULT_MAX_LINES + 1);
-        const win = readLineWindow(abs, badOffset ? 1 : offset, badOffset || badLimit ? 0 : want, maxBytes);
+        const win = await readLineWindowAsync(abs, badOffset ? 1 : offset, badOffset || badLimit ? 0 : want, maxBytes);
         totalLines = win.totalLines;
         selected = win.lines;
     }