opencode-gbk-tools 0.1.14 → 0.1.16

package/README.md

@@ -2,7 +2,7 @@
 
 为 OpenCode 提供一套自动识别编码的文本工具，以及面向 `GBK` / `GB18030` 的专用工具。
 
-解决 OpenCode 内置工具难以稳定处理非 UTF-8 文本文件的问题，并让所有 agents 默认优先使用可保留原编码的 `text_*` 工具。
+解决 OpenCode 内置工具难以稳定处理非 UTF-8 文本文件的问题，并通过 plugin 让所有 agents 默认获得这些工具与规则，无需单独切换专属 GBK agent。
 
 ---
 
@@ -17,7 +17,7 @@
 | `gbk_write` | 写入或追加内容到 GBK 文件（`append=true` 支持追加） |
 | `gbk_edit` | 精确替换 GBK 文件中的指定文本块 |
 | `gbk_search` | 在 GBK 文件中搜索关键词，返回行号和上下文 |
-| 本地/全局 plugin 规则 | 给所有 agents 注入“优先使用 `text_*`”的系统提示 |
+| 本地/全局 plugin 规则 | 给所有 agents 注入“优先使用 `text_*`”的系统提示，并统一开放 `gbk_*` 工具 |
 
 ---
 
@@ -27,7 +27,15 @@
 npx opencode-gbk-tools install
 ```
 
-安装完成后**重启 OpenCode**，工具立即生效。
+安装完成后会注册 `opencode-gbk-tools` plugin，由该 plugin 统一向全部 agents 暴露 `text_*` / `gbk_*` 工具与规则。
+
+重启 OpenCode 后，**全部 agents** 都会默认获得：
+
+- `text_read` / `text_write` / `text_edit`
+- `gbk_read` / `gbk_write` / `gbk_edit` / `gbk_search`
+- 对文本文件优先使用 `text_*` 的系统提示
+
+不再需要单独安装或切换专属 `gbk-engine` agent。
 
 ---
 
@@ -41,6 +49,8 @@ npx opencode-gbk-tools install
 npx opencode-gbk-tools uninstall
 ```
 
+卸载后会移除已安装的工具、plugin 与 manifest，所有 agents 恢复为未安装前的默认行为。
+
 ---
 
 ## 工具使用说明
@@ -181,7 +191,7 @@ A：重启 OpenCode。工具在 OpenCode 启动时加载，安装后需要重启
 A：请先安装 Node.js（https://nodejs.org/），版本需要 18 或以上。
 
 **Q：Windows 路径在哪？**
-A：全局安装目录为 `C:\Users\你的用户名\.config\opencode\tools\`
+A：全局安装的 plugin 文件位于 `C:\Users\你的用户名\.config\opencode\plugins\opencode-gbk-tools.js`
 
 **Q：gbk_edit 提示"未找到需要替换的文本"？**
 A：检查 `oldString` 是否包含了行号前缀（如 `"3787: "`），去掉行号前缀后重试。若要在文件末尾追加内容，请使用 `gbk_write [append=true]`。
@@ -195,6 +205,8 @@ A：不要。现在优先用 `mode="insertAfter"` 或 `mode="insertBefore"`，
 
 | 版本 | 说明 |
 |------|------|
+| 0.1.16 | 去掉专属 `gbk-engine` agent 安装链路，改为通过 plugin + tools 让全部 agents 统一支持 `text_*` / `gbk_*`；同步更新安装说明 |
+| 0.1.15 | 为 GBK 大文件统一引入行字节索引与流式读/搜/改路径，提升局部编辑、搜索与大块修改时的性能、稳定性与准确性 |
 | 0.1.14 | 重新发布当前稳定产物，核对 `npm pack --dry-run` 输出包含完整 `dist/`，为下一次公开发布提供一致的打包基线 |
 | 0.1.13 | `text_write` 在新文件 + `encoding=auto` 下改为显式报错，不再静默默认 `utf8`；同时优化 `text_read` 流式读取与 `text_edit` 预览生成，减少重复读取 |
 | 0.1.12 | 仅提升发布版本号，用于重新发布当前 `0.1.11` 的稳定内容 |

package/dist/cli/index.js

@@ -60,10 +60,19 @@ function resolveTargetBase(target, cwd) {
 // src/cli/install.ts
 async function installCommand(args) {
   const targetBase = resolveTargetBase(args.target, args.cwd);
-  const allowedArtifacts = new Set(args.artifacts ?? ["tool", "agent", "plugin"]);
+  const allowedArtifacts = new Set(args.artifacts ?? ["plugin"]);
   const releaseManifest = JSON.parse(await fs3.readFile(path3.join(args.packageRoot, "dist", "release-manifest.json"), "utf8"));
   const selectedArtifacts = releaseManifest.artifacts.filter((artifact) => allowedArtifacts.has(artifact.kind));
   const existingManifest = await loadInstalledManifest(targetBase);
+  const selectedRelativePaths = new Set(selectedArtifacts.map((artifact) => artifact.relativePath));
+  if (existingManifest) {
+    for (const file of existingManifest.files) {
+      if (selectedRelativePaths.has(file.relativePath)) {
+        continue;
+      }
+      await fs3.rm(path3.join(targetBase, file.relativePath), { force: true });
+    }
+  }
   for (const artifact of selectedArtifacts) {
     const targetPath = path3.join(targetBase, artifact.relativePath);
     if (await pathExists(targetPath) && !existingManifest && !args.force) {
@@ -181,7 +190,7 @@ async function setupCommand(args) {
   await fs6.mkdir(configBase, { recursive: true });
   const configPath = await resolveConfigFile(configBase);
   await ensurePluginConfigured(configPath, pluginName);
-  const installResult = await installCommand({ ...args, force: true, artifacts: ["agent", "plugin"] });
+  const installResult = await installCommand({ ...args, force: true, artifacts: ["plugin"] });
   return {
     configPath,
     targetBase: installResult.targetBase

package/dist/opencode-tools/gbk_edit.js

@@ -16305,6 +16305,14 @@ async function assertPathAllowed(filePath, context, allowExternal = false) {
 
 // src/lib/gbk-file.ts
 var STREAMING_FILE_SIZE_THRESHOLD_BYTES = 1024 * 1024;
+var STREAM_READ_CHUNK_SIZE_BYTES = 1024 * 1024;
+var gbkLineIndexCache = /* @__PURE__ */ new Map();
+function toSafeNumber(value) {
+  return typeof value === "bigint" ? Number(value) : value;
+}
+function invalidateGbkLineIndex(filePath) {
+  gbkLineIndexCache.delete(filePath);
+}
 function assertStringArgument(value, name) {
   if (typeof value !== "string") {
     throw createGbkError("GBK_INVALID_ARGUMENT", `${name} \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
@@ -16417,6 +16425,18 @@ function detectNewlineStyle(text) {
   }
   return "none";
 }
+function finalizeNewlineStyle(crlfCount, lfCount) {
+  if (crlfCount > 0 && lfCount === 0) {
+    return "crlf";
+  }
+  if (lfCount > 0 && crlfCount === 0) {
+    return "lf";
+  }
+  if (crlfCount > 0 && lfCount > 0) {
+    return "mixed";
+  }
+  return "none";
+}
 function applyLineRange(text, startLine, endLine) {
   if (startLine === void 0 && endLine === void 0) {
     return {
@@ -16542,6 +16562,29 @@ function hasLineNumberPrefixes(lines) {
 function stripLineNumberPrefixes(lines) {
   return lines.map((l) => l.replace(/^\d+: /, ""));
 }
+function parseLineNumberPrefixedBlock(text) {
+  const lines = splitNormalizedLines(text);
+  if (!hasLineNumberPrefixes(lines)) {
+    return null;
+  }
+  const lineNumbers = [];
+  const strippedLines = [];
+  for (const line of lines) {
+    const match = /^(\d+): ?(.*)$/.exec(line);
+    if (!match) {
+      return null;
+    }
+    lineNumbers.push(Number(match[1]));
+    strippedLines.push(match[2]);
+  }
+  return {
+    lineNumbers,
+    strippedText: strippedLines.join("\n"),
+    isContiguous: lineNumbers.every((lineNumber, index) => index === 0 || lineNumber === lineNumbers[index - 1] + 1),
+    startLine: lineNumbers[0],
+    endLine: lineNumbers[lineNumbers.length - 1]
+  };
+}
 function matchLooseBlock(contentLines, oldLines, newLines, newlineStyle, content) {
   for (let start = 0; start < contentLines.length; start += 1) {
     let contentIndex = start;
@@ -16658,7 +16701,7 @@ async function readWholeGbkTextFile(input) {
 }
 async function visitDecodedTextChunks(input, visitor) {
   const decoder = import_iconv_lite.default.getDecoder(input.encoding);
-  const stream = createReadStream(input.filePath);
+  const stream = createReadStream(input.filePath, { highWaterMark: STREAM_READ_CHUNK_SIZE_BYTES });
   try {
     for await (const chunk of stream) {
       const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
@@ -16681,6 +16724,90 @@ async function visitDecodedTextChunks(input, visitor) {
     stream.destroy();
   }
 }
+async function getGbkLineIndex(input) {
+  const cached2 = gbkLineIndexCache.get(input.filePath);
+  if (cached2 && cached2.fileSize === toSafeNumber(input.stat.size) && cached2.mtimeMs === toSafeNumber(input.stat.mtimeMs)) {
+    return cached2;
+  }
+  const lineStartOffsets = [0];
+  let byteOffset = 0;
+  let previousByteWasCR = false;
+  let crlfCount = 0;
+  let lfCount = 0;
+  const stream = createReadStream(input.filePath, { highWaterMark: STREAM_READ_CHUNK_SIZE_BYTES });
+  try {
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      assertNotBinary(buffer);
+      for (let index = 0; index < buffer.length; index += 1) {
+        const byte = buffer[index];
+        if (byte === 10) {
+          if (previousByteWasCR) {
+            crlfCount += 1;
+          } else {
+            lfCount += 1;
+          }
+          lineStartOffsets.push(byteOffset + index + 1);
+          previousByteWasCR = false;
+          continue;
+        }
+        previousByteWasCR = byte === 13;
+      }
+      byteOffset += buffer.length;
+    }
+  } catch (error45) {
+    if (error45 instanceof Error && "code" in error45) {
+      throw error45;
+    }
+    throw createGbkError("GBK_IO_ERROR", `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25: ${input.filePath}`, error45);
+  } finally {
+    stream.destroy();
+  }
+  const result = {
+    filePath: input.filePath,
+    fileSize: toSafeNumber(input.stat.size),
+    mtimeMs: toSafeNumber(input.stat.mtimeMs),
+    lineStartOffsets,
+    totalLines: lineStartOffsets.length,
+    newlineStyle: finalizeNewlineStyle(crlfCount, lfCount)
+  };
+  gbkLineIndexCache.set(input.filePath, result);
+  return result;
+}
+async function readDecodedGbkByteRange(input, start, endExclusive) {
+  if (endExclusive <= start) {
+    return "";
+  }
+  const decoder = import_iconv_lite.default.getDecoder(input.encoding);
+  const stream = createReadStream(input.filePath, {
+    start,
+    end: endExclusive - 1,
+    highWaterMark: STREAM_READ_CHUNK_SIZE_BYTES
+  });
+  const parts = [];
+  try {
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      assertNotBinary(buffer);
+      const text = decoder.write(buffer);
+      if (text.length > 0) {
+        parts.push(text);
+      }
+    }
+    const trailingText = decoder.end() ?? "";
+    if (trailingText.length > 0) {
+      parts.push(trailingText);
+    }
+    return parts.join("");
+  } catch (error45) {
+    if (error45 instanceof Error && "code" in error45) {
+      throw error45;
+    }
+    throw createGbkError("GBK_IO_ERROR", `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25: ${input.filePath}`, error45);
+  } finally {
+    stream.destroy();
+  }
+}
 async function writeAll(handle, buffer) {
   let offset = 0;
   while (offset < buffer.length) {
@@ -16696,6 +16823,249 @@ async function writeEncodedText(handle, encoding, text) {
   await writeAll(handle, buffer);
   return buffer.byteLength;
 }
+async function copyFileByteRangeToHandle(sourcePath, handle, start, endExclusive) {
+  if (endExclusive <= start) {
+    return 0;
+  }
+  const stream = createReadStream(sourcePath, {
+    start,
+    end: endExclusive - 1,
+    highWaterMark: STREAM_READ_CHUNK_SIZE_BYTES
+  });
+  let bytesWritten = 0;
+  try {
+    for await (const chunk of stream) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      await writeAll(handle, buffer);
+      bytesWritten += buffer.byteLength;
+    }
+    return bytesWritten;
+  } catch (error45) {
+    if (error45 instanceof Error && "code" in error45) {
+      throw error45;
+    }
+    throw createGbkError("GBK_IO_ERROR", `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25: ${sourcePath}`, error45);
+  } finally {
+    stream.destroy();
+  }
+}
+function alignTextToNewlineStyle(text, newlineStyle) {
+  return newlineStyle === "crlf" ? text.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n") : newlineStyle === "lf" ? text.replace(/\r\n/g, "\n") : text;
+}
+function replaceScopedTextContent(scopeText, oldString, newString, replaceAll, newlineStyle) {
+  const occurrencesBefore = countOccurrences(scopeText, oldString);
+  if (!replaceAll && occurrencesBefore === 0) {
+    const loose = tryLooseBlockReplace(scopeText, oldString, newString);
+    if (loose !== null) {
+      return {
+        replacedText: loose.content,
+        replacements: 1,
+        occurrencesBefore: loose.occurrencesBefore
+      };
+    }
+  }
+  if (replaceAll) {
+    if (occurrencesBefore === 0) {
+      throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scopeText, oldString));
+    }
+  } else if (occurrencesBefore === 0) {
+    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scopeText, oldString));
+  } else if (occurrencesBefore > 1) {
+    throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${oldString}`);
+  }
+  const alignedNewString = alignTextToNewlineStyle(newString, newlineStyle);
+  return {
+    replacedText: replaceAll ? scopeText.split(oldString).join(alignedNewString) : scopeText.replace(oldString, alignedNewString),
+    replacements: replaceAll ? occurrencesBefore : 1,
+    occurrencesBefore
+  };
+}
+async function replaceLargeGbkFileTextInLineRange(input) {
+  const lineIndex = await getGbkLineIndex(input);
+  const requestedStartLine = input.startLine ?? 1;
+  const requestedEndLine = input.endLine ?? lineIndex.totalLines;
+  if (requestedEndLine < requestedStartLine) {
+    throw createGbkError("GBK_INVALID_ARGUMENT", "endLine \u4E0D\u80FD\u5C0F\u4E8E startLine");
+  }
+  const actualStartLine = Math.min(requestedStartLine, lineIndex.totalLines);
+  const actualEndLine = Math.min(requestedEndLine, lineIndex.totalLines);
+  const rangeStart = lineIndex.lineStartOffsets[Math.max(0, actualStartLine - 1)] ?? toSafeNumber(input.stat.size);
+  const rangeEnd = actualEndLine < lineIndex.totalLines ? lineIndex.lineStartOffsets[actualEndLine] : toSafeNumber(input.stat.size);
+  const scopeText = await readDecodedGbkByteRange(input, rangeStart, rangeEnd);
+  const replaced = replaceScopedTextContent(
+    scopeText,
+    input.oldString,
+    input.newString,
+    input.replaceAll,
+    lineIndex.newlineStyle
+  );
+  const tempPath = path2.join(
+    path2.dirname(input.filePath),
+    `${path2.basename(input.filePath)}.opencode-gbk-${crypto.randomUUID()}.tmp`
+  );
+  const handle = await fs2.open(tempPath, "w");
+  let bytesWritten = 0;
+  try {
+    bytesWritten += await copyFileByteRangeToHandle(input.filePath, handle, 0, rangeStart);
+    bytesWritten += await writeEncodedText(handle, input.encoding, replaced.replacedText);
+    bytesWritten += await copyFileByteRangeToHandle(input.filePath, handle, rangeEnd, toSafeNumber(input.stat.size));
+    await handle.close();
+    const mode = typeof input.stat.mode === "bigint" ? Number(input.stat.mode) : input.stat.mode;
+    await fs2.chmod(tempPath, mode);
+    await fs2.rename(tempPath, input.filePath);
+    return {
+      mode: "replace",
+      filePath: input.filePath,
+      encoding: input.encoding,
+      replacements: replaced.replacements,
+      occurrencesBefore: replaced.occurrencesBefore,
+      bytesRead: input.stat.size,
+      bytesWritten
+    };
+  } catch (error45) {
+    await handle.close().catch(() => void 0);
+    await fs2.rm(tempPath, { force: true }).catch(() => void 0);
+    throw error45;
+  }
+}
+async function replaceLargeGbkFileByAnchor(input) {
+  const tempPath = path2.join(
+    path2.dirname(input.filePath),
+    `${path2.basename(input.filePath)}.opencode-gbk-${crypto.randomUUID()}.tmp`
+  );
+  const handle = await fs2.open(tempPath, "w");
+  const alignedContent = input.content.replace(/\r\n/g, "\n");
+  const anchorLength = input.anchor.length;
+  const carryLength = Math.max(anchorLength + alignedContent.length, 1);
+  let decoded = "";
+  let scanFrom = 0;
+  let totalMatches = 0;
+  let inserted = false;
+  let skipped = false;
+  let bytesWritten = 0;
+  const flushPrefix = async (preserveTailLength) => {
+    const flushLength = Math.max(0, decoded.length - preserveTailLength);
+    if (flushLength === 0) {
+      return;
+    }
+    bytesWritten += await writeEncodedText(handle, input.encoding, decoded.slice(0, flushLength));
+    decoded = decoded.slice(flushLength);
+    scanFrom = Math.max(0, scanFrom - flushLength);
+  };
+  const finalizeInserted = async () => {
+    bytesWritten += await writeEncodedText(handle, input.encoding, decoded);
+    decoded = "";
+  };
+  try {
+    await visitDecodedTextChunks(input, async (text) => {
+      decoded += text;
+      while (!inserted) {
+        const foundAt = decoded.indexOf(input.anchor, scanFrom);
+        if (foundAt === -1) {
+          break;
+        }
+        totalMatches += 1;
+        const afterAnchor = foundAt + anchorLength;
+        if (totalMatches !== input.occurrence) {
+          scanFrom = afterAnchor;
+          continue;
+        }
+        const before = decoded.slice(0, foundAt);
+        const after = decoded.slice(afterAnchor);
+        const anchorAndAfter = decoded.slice(foundAt);
+        const alreadyExists = input.mode === "insertAfter" ? after.startsWith(alignedContent) : before.endsWith(alignedContent);
+        if (alreadyExists) {
+          if (input.ifExists === "error") {
+            throw createGbkError("GBK_INVALID_ARGUMENT", "\u63D2\u5165\u4F4D\u7F6E\u5DF2\u5B58\u5728\u76F8\u540C\u5185\u5BB9");
+          }
+          if (input.ifExists === "skip") {
+            skipped = true;
+            inserted = true;
+            bytesWritten += await writeEncodedText(handle, input.encoding, decoded);
+            decoded = "";
+            return;
+          }
+        }
+        if (input.mode === "insertAfter") {
+          bytesWritten += await writeEncodedText(handle, input.encoding, before);
+          bytesWritten += await writeEncodedText(handle, input.encoding, input.anchor);
+          bytesWritten += await writeEncodedText(handle, input.encoding, alignedContent);
+          bytesWritten += await writeEncodedText(handle, input.encoding, after);
+        } else {
+          bytesWritten += await writeEncodedText(handle, input.encoding, before);
+          bytesWritten += await writeEncodedText(handle, input.encoding, alignedContent);
+          bytesWritten += await writeEncodedText(handle, input.encoding, anchorAndAfter);
+        }
+        decoded = "";
+        scanFrom = 0;
+        inserted = true;
+        return;
+      }
+      if (!inserted) {
+        await flushPrefix(carryLength);
+      }
+    });
+    if (!inserted) {
+      while (true) {
+        const foundAt = decoded.indexOf(input.anchor, scanFrom);
+        if (foundAt === -1) {
+          break;
+        }
+        totalMatches += 1;
+        const afterAnchor = foundAt + anchorLength;
+        if (totalMatches !== input.occurrence) {
+          scanFrom = afterAnchor;
+          continue;
+        }
+        const before = decoded.slice(0, foundAt);
+        const after = decoded.slice(afterAnchor);
+        const anchorAndAfter = decoded.slice(foundAt);
+        const alreadyExists = input.mode === "insertAfter" ? after.startsWith(alignedContent) : before.endsWith(alignedContent);
+        if (alreadyExists) {
+          if (input.ifExists === "error") {
+            throw createGbkError("GBK_INVALID_ARGUMENT", "\u63D2\u5165\u4F4D\u7F6E\u5DF2\u5B58\u5728\u76F8\u540C\u5185\u5BB9");
+          }
+          if (input.ifExists === "skip") {
+            skipped = true;
+            inserted = true;
+            break;
+          }
+        }
+        decoded = input.mode === "insertAfter" ? `${before}${input.anchor}${alignedContent}${after}` : `${before}${alignedContent}${anchorAndAfter}`;
+        inserted = true;
+        break;
+      }
+    }
+    if (!inserted && totalMatches === 0) {
+      throw createGbkError("GBK_NO_MATCH", `\u672A\u627E\u5230\u951A\u70B9: ${input.anchor}`);
+    }
+    if (!inserted && totalMatches > 0) {
+      throw createGbkError("GBK_NO_MATCH", `\u951A\u70B9 ${input.anchor} \u53EA\u627E\u5230 ${totalMatches} \u5904\uFF0C\u65E0\u6CD5\u4F7F\u7528\u7B2C ${input.occurrence} \u5904`);
+    }
+    await finalizeInserted();
+    await handle.close();
+    const mode = typeof input.stat.mode === "bigint" ? Number(input.stat.mode) : input.stat.mode;
+    await fs2.chmod(tempPath, mode);
+    await fs2.rename(tempPath, input.filePath);
+    invalidateGbkLineIndex(input.filePath);
+    return {
+      mode: input.mode,
+      filePath: input.filePath,
+      encoding: input.encoding,
+      anchor: input.anchor,
+      occurrence: input.occurrence,
+      anchorMatches: totalMatches,
+      inserted: !skipped,
+      skipped,
+      bytesRead: input.stat.size,
+      bytesWritten
+    };
+  } catch (error45) {
+    await handle.close().catch(() => void 0);
+    await fs2.rm(tempPath, { force: true }).catch(() => void 0);
+    throw error45;
+  }
+}
 async function replaceLargeGbkFileText(input) {
   const tempPath = path2.join(
     path2.dirname(input.filePath),
@@ -16742,6 +17112,7 @@ async function replaceLargeGbkFileText(input) {
     const mode = typeof input.stat.mode === "bigint" ? Number(input.stat.mode) : input.stat.mode;
     await fs2.chmod(tempPath, mode);
     await fs2.rename(tempPath, input.filePath);
+    invalidateGbkLineIndex(input.filePath);
     return {
       filePath: input.filePath,
       encoding: input.encoding,
@@ -16766,8 +17137,18 @@ async function replaceGbkFileText(input) {
   if (mode === "insertAfter" || mode === "insertBefore") {
     assertInsertArguments(input);
     const resolved2 = await resolveReadableGbkFile(normalizedInput);
-    const current2 = await readWholeGbkTextFile(resolved2);
     const occurrence = normalizeOptionalPositiveInteger(input.occurrence, "occurrence") ?? 1;
+    if (resolved2.stat.size >= STREAMING_FILE_SIZE_THRESHOLD_BYTES) {
+      return await replaceLargeGbkFileByAnchor({
+        ...resolved2,
+        mode,
+        anchor: input.anchor,
+        content: input.content,
+        occurrence,
+        ifExists: input.ifExists ?? "skip"
+      });
+    }
+    const current2 = await readWholeGbkTextFile(resolved2);
     const insertResult = insertByAnchor(
       current2.content,
       mode,
@@ -16812,24 +17193,47 @@ async function replaceGbkFileText(input) {
   }
   const replaceAll = normalizedInput.replaceAll ?? false;
   const resolved = await resolveReadableGbkFile(normalizedInput);
-  const hasScopedRange = normalizedInput.startLine !== void 0 || normalizedInput.endLine !== void 0 || normalizedInput.startAnchor !== void 0 || normalizedInput.endAnchor !== void 0;
+  const prefixedBlock = parseLineNumberPrefixedBlock(input.oldString);
+  const derivedScopedRange = prefixedBlock?.isContiguous ? {
+    startLine: normalizedInput.startLine ?? prefixedBlock.startLine,
+    endLine: normalizedInput.endLine ?? prefixedBlock.endLine,
+    oldString: prefixedBlock.strippedText
+  } : null;
+  const effectiveOldString = derivedScopedRange?.oldString ?? input.oldString;
+  const hasScopedRange = normalizedInput.startLine !== void 0 || normalizedInput.endLine !== void 0 || normalizedInput.startAnchor !== void 0 || normalizedInput.endAnchor !== void 0 || derivedScopedRange !== null;
   if (resolved.stat.size >= STREAMING_FILE_SIZE_THRESHOLD_BYTES && !hasScopedRange) {
     return await replaceLargeGbkFileText({
       ...resolved,
-      oldString: input.oldString,
+      oldString: effectiveOldString,
       newString: input.newString,
       replaceAll
     });
   }
+  if (resolved.stat.size >= STREAMING_FILE_SIZE_THRESHOLD_BYTES && normalizedInput.startAnchor === void 0 && normalizedInput.endAnchor === void 0 && (normalizedInput.startLine !== void 0 || normalizedInput.endLine !== void 0 || derivedScopedRange !== null)) {
+    return await replaceLargeGbkFileTextInLineRange({
+      ...resolved,
+      oldString: effectiveOldString,
+      newString: input.newString,
+      replaceAll,
+      startLine: derivedScopedRange?.startLine ?? normalizedInput.startLine,
+      endLine: derivedScopedRange?.endLine ?? normalizedInput.endLine
+    });
+  }
   const current = await readWholeGbkTextFile(resolved);
-  const scope = resolveEditScope(current.content, normalizedInput);
-  const occurrencesBefore = countOccurrences(scope.selectedText, input.oldString);
+  const scopedInput = derivedScopedRange === null ? normalizedInput : {
+    ...normalizedInput,
+    startLine: derivedScopedRange.startLine,
+    endLine: derivedScopedRange.endLine
+  };
+  const scope = resolveEditScope(current.content, scopedInput);
+  const occurrencesBefore = countOccurrences(scope.selectedText, effectiveOldString);
   if (!replaceAll && occurrencesBefore === 0) {
-    const loose = tryLooseBlockReplace(scope.selectedText, input.oldString, input.newString);
+    const loose = tryLooseBlockReplace(scope.selectedText, effectiveOldString, input.newString);
     if (loose !== null) {
       const outputText2 = `${current.content.slice(0, scope.rangeStart)}${loose.content}${current.content.slice(scope.rangeEnd)}`;
       const buffer2 = import_iconv_lite.default.encode(outputText2, current.encoding);
       await fs2.writeFile(current.filePath, buffer2);
+      invalidateGbkLineIndex(current.filePath);
       return {
         mode: "replace",
         filePath: current.filePath,
@@ -16843,19 +17247,20 @@ async function replaceGbkFileText(input) {
   }
   if (replaceAll) {
     if (occurrencesBefore === 0) {
-      throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
+      throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, effectiveOldString));
     }
   } else if (occurrencesBefore === 0) {
-    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
+    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, effectiveOldString));
   } else if (occurrencesBefore > 1) {
-    throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${input.oldString}`);
+    throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${effectiveOldString}`);
   }
   const fileNewlineStyle = detectNewlineStyle(current.content);
   const alignedNewString = fileNewlineStyle === "crlf" ? input.newString.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n") : fileNewlineStyle === "lf" ? input.newString.replace(/\r\n/g, "\n") : input.newString;
-  const replaced = replaceAll ? scope.selectedText.split(input.oldString).join(alignedNewString) : scope.selectedText.replace(input.oldString, alignedNewString);
+  const replaced = replaceAll ? scope.selectedText.split(effectiveOldString).join(alignedNewString) : scope.selectedText.replace(effectiveOldString, alignedNewString);
   const outputText = `${current.content.slice(0, scope.rangeStart)}${replaced}${current.content.slice(scope.rangeEnd)}`;
   const buffer = import_iconv_lite.default.encode(outputText, current.encoding);
   await fs2.writeFile(current.filePath, buffer);
+  invalidateGbkLineIndex(current.filePath);
   return {
     mode: "replace",
     filePath: current.filePath,
@@ -16871,7 +17276,8 @@ async function replaceGbkFileText(input) {
 var gbk_edit_default = tool({
   description: `Edit GBK/GB18030 encoded text files with exact string replacement.
 
-Reads the FULL file content regardless of file size \u2014 not limited by gbk_read's line window.
+For whole-file replace, large files use a streaming path.
+For line-scoped replace, large files use a cached line-byte index and only decode the selected line window.
 Safe to use on files with more than 2000 lines.
 
 CRITICAL \u2014 do NOT include line number prefixes in oldString or newString:
@@ -16915,7 +17321,7 @@ Insert mode:
   },
   async execute(args, context) {
     const result = await replaceGbkFileText({ ...args, context });
-    const isReplace = !("mode" in result) || result.mode === "replace";
+    const isReplace = "replacements" in result;
     const title = isReplace ? `GBK \u7F16\u8F91 ${result.encoding.toUpperCase()} x${result.replacements}` : result.inserted ? `GBK \u63D2\u5165 ${result.encoding.toUpperCase()} #${result.occurrence}` : `GBK \u8DF3\u8FC7 ${result.encoding.toUpperCase()} #${result.occurrence}`;
     context.metadata({
       title,