opencode-gbk-tools 0.1.10 → 0.1.11

package/README.md

@@ -67,6 +67,35 @@ npx opencode-gbk-tools uninstall
 明确 GBK 文件：gbk_read / gbk_write / gbk_edit / gbk_search
 ```
 
+编辑动作建议：
+
+```text
+插入到标签前后：用 mode=insertAfter / insertBefore + anchor/content
+精确替换现有文本：用 oldString/newString
+文件末尾追加：用 text_write/gbk_write + append=true
+```
+
+### text_edit — 通用文本编辑
+
+插入模式示例：
+
+```text
+text_edit(filePath="文件路径", mode="insertAfter", anchor="[@SkipCheck_Source]", content="\n你好")
+text_edit(filePath="文件路径", mode="insertBefore", anchor="[@SkipCheck_Source]", content="你好\n")
+text_edit(filePath="文件路径", mode="insertAfter", anchor="[@标签]", content="\n你好", occurrence=2, ifExists="skip")
+```
+
+替换模式示例：
+
+```text
+text_edit(filePath="文件路径", oldString="原文内容", newString="新内容")
+text_edit(filePath="文件路径", oldString="原文", newString="新文", startLine=100, endLine=200)
+```
+
+- `mode` 默认是 `replace`
+- 插入模式下不需要 `oldString`
+- `ifExists` 默认 `skip`，可避免重复插入
+
 ### gbk_read — 读取文件
 
 ```
@@ -92,9 +121,12 @@ gbk_search(filePath="文件路径", pattern="[@标签名]", contextLines=5)
 ```
 gbk_edit(filePath="文件路径", oldString="原文内容", newString="新内容")
 gbk_edit(filePath="文件路径", oldString="原文", newString="新文", startLine=100, endLine=200)
+gbk_edit(filePath="文件路径", mode="insertAfter", anchor="[@SkipCheck_Source]", content="\n你好")
 ```
 
-**重要：`oldString` 必须是文件的原始内容，不能包含 `gbk_read` 输出的行号前缀。**
+**推荐：如果你的意图是“在标签后插入一行”，优先使用 `mode="insertAfter"` + `anchor/content`，不要再强依赖 `oldString`。**
+
+**只有在精确替换已有文本时，`oldString` 才是推荐方案。并且 `oldString` 必须是文件的原始内容，不能包含 `gbk_read` 输出的行号前缀。**
 
 错误示范（包含行号前缀，会失败）：
 ```
@@ -153,12 +185,16 @@ A：全局安装目录为 `C:\Users\你的用户名\.config\opencode\tools\`
 **Q：gbk_edit 提示"未找到需要替换的文本"？**
 A：检查 `oldString` 是否包含了行号前缀（如 `"3787: "`），去掉行号前缀后重试。若要在文件末尾追加内容，请使用 `gbk_write [append=true]`。
 
+**Q：我只是想在某个标签后插入一行，还要不要传 `oldString`？**
+A：不要。现在优先用 `mode="insertAfter"` 或 `mode="insertBefore"`，并传 `anchor/content`。
+
 ---
 
 ## 版本历史
 
 | 版本 | 说明 |
 |------|------|
+| 0.1.11 | `text_edit` / `gbk_edit` 新增 `insertAfter` / `insertBefore`，插入内容不再依赖 `oldString`；README 与全局提示同步改为“插入优先用 anchor/content” |
 | 0.1.10 | 新增 `text_read` / `text_write` / `text_edit`，自动识别并保持原编码、BOM 与换行风格；同时通过 plugin 规则让所有 agents 默认优先使用 `text_*` |
 | 0.1.9 | `gbk_edit` 修复精确匹配路径写入 CRLF 文件时换行风格变 mixed 的 bug |
 | 0.1.8 | `gbk_write` 新增 `append=true` 追加模式 |

package/dist/opencode-tools/gbk_edit.js

@@ -16305,6 +16305,82 @@ async function assertPathAllowed(filePath, context, allowExternal = false) {
 
 // src/lib/gbk-file.ts
 var STREAMING_FILE_SIZE_THRESHOLD_BYTES = 1024 * 1024;
+function assertStringArgument(value, name) {
+  if (typeof value !== "string") {
+    throw createGbkError("GBK_INVALID_ARGUMENT", `${name} \u5FC5\u987B\u662F\u5B57\u7B26\u4E32`);
+  }
+}
+function assertReplaceArguments(input) {
+  assertStringArgument(input.oldString, "oldString");
+  assertStringArgument(input.newString, "newString");
+}
+function assertInsertArguments(input) {
+  assertStringArgument(input.anchor, "anchor");
+  assertStringArgument(input.content, "content");
+  if (input.content.length === 0) {
+    throw createGbkError("GBK_INVALID_ARGUMENT", "content \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (input.replaceAll !== void 0) {
+    throw createGbkError("GBK_INVALID_ARGUMENT", "\u63D2\u5165\u6A21\u5F0F\u4E0D\u652F\u6301 replaceAll");
+  }
+  if (input.startLine !== void 0 || input.endLine !== void 0 || input.startAnchor !== void 0 || input.endAnchor !== void 0) {
+    throw createGbkError("GBK_INVALID_ARGUMENT", "\u63D2\u5165\u6A21\u5F0F\u4E0D\u652F\u6301 startLine/endLine/startAnchor/endAnchor");
+  }
+}
+function findOccurrenceIndex(text, token, occurrence) {
+  assertStringArgument(text, "text");
+  assertStringArgument(token, "anchor");
+  assertPositiveInteger(occurrence, "occurrence");
+  if (token.length === 0) {
+    throw createGbkError("GBK_INVALID_ARGUMENT", "anchor \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  let count = 0;
+  let searchFrom = 0;
+  while (true) {
+    const index = text.indexOf(token, searchFrom);
+    if (index === -1) {
+      break;
+    }
+    count += 1;
+    if (count === occurrence) {
+      return { index, total: countOccurrences(text, token) };
+    }
+    searchFrom = index + token.length;
+  }
+  if (count === 0) {
+    throw createGbkError("GBK_NO_MATCH", `\u672A\u627E\u5230\u951A\u70B9: ${token}`);
+  }
+  throw createGbkError("GBK_NO_MATCH", `\u951A\u70B9 ${token} \u53EA\u627E\u5230 ${count} \u5904\uFF0C\u65E0\u6CD5\u4F7F\u7528\u7B2C ${occurrence} \u5904`);
+}
+function insertByAnchor(text, mode, anchor, content, occurrence, ifExists, newlineStyle) {
+  const alignedContent = newlineStyle === "crlf" ? content.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n") : newlineStyle === "lf" ? content.replace(/\r\n/g, "\n") : content;
+  const located = findOccurrenceIndex(text, anchor, occurrence);
+  const insertionPoint = mode === "insertAfter" ? located.index + anchor.length : located.index;
+  const alreadyExists = mode === "insertAfter" ? text.slice(insertionPoint, insertionPoint + alignedContent.length) === alignedContent : text.slice(Math.max(0, insertionPoint - alignedContent.length), insertionPoint) === alignedContent;
+  if (alreadyExists) {
+    if (ifExists === "error") {
+      throw createGbkError("GBK_INVALID_ARGUMENT", "\u63D2\u5165\u4F4D\u7F6E\u5DF2\u5B58\u5728\u76F8\u540C\u5185\u5BB9");
+    }
+    if (ifExists === "skip") {
+      return {
+        outputText: text,
+        inserted: false,
+        skipped: true,
+        anchorMatches: located.total,
+        occurrence,
+        anchor
+      };
+    }
+  }
+  return {
+    outputText: `${text.slice(0, insertionPoint)}${alignedContent}${text.slice(insertionPoint)}`,
+    inserted: true,
+    skipped: false,
+    anchorMatches: located.total,
+    occurrence,
+    anchor
+  };
+}
 function assertEncodingSupported(encoding) {
   if (encoding !== "gbk" && encoding !== "gb18030") {
     throw createGbkError("GBK_INVALID_ENCODING", `\u4E0D\u652F\u6301\u7684\u7F16\u7801: ${encoding}`);
@@ -16423,9 +16499,11 @@ function resolveEditScope(text, input) {
   };
 }
 function normalizeNewlines(text) {
+  assertStringArgument(text, "text");
   return text.replace(/\r\n/g, "\n");
 }
 function trimRightSpaces(text) {
+  assertStringArgument(text, "text");
   return text.replace(/[ \t]+$/g, "");
 }
 function splitNormalizedLines(text) {
@@ -16521,6 +16599,8 @@ function tryLooseBlockReplace(content, oldString, newString) {
   return null;
 }
 function countOccurrences(text, target) {
+  assertStringArgument(text, "text");
+  assertStringArgument(target, "oldString");
   if (target.length === 0) {
     throw createGbkError("GBK_EMPTY_OLD_STRING", "oldString \u4E0D\u80FD\u4E3A\u7A7A");
   }
@@ -16677,11 +16757,56 @@ async function replaceLargeGbkFileText(input) {
   }
 }
 async function replaceGbkFileText(input) {
+  const mode = input.mode ?? "replace";
   const normalizedInput = {
     ...input,
     startLine: normalizeOptionalPositiveInteger(input.startLine, "startLine"),
     endLine: normalizeOptionalPositiveInteger(input.endLine, "endLine")
   };
+  if (mode === "insertAfter" || mode === "insertBefore") {
+    assertInsertArguments(input);
+    const resolved2 = await resolveReadableGbkFile(normalizedInput);
+    const current2 = await readWholeGbkTextFile(resolved2);
+    const occurrence = normalizeOptionalPositiveInteger(input.occurrence, "occurrence") ?? 1;
+    const insertResult = insertByAnchor(
+      current2.content,
+      mode,
+      input.anchor,
+      input.content,
+      occurrence,
+      input.ifExists ?? "skip",
+      detectNewlineStyle(current2.content)
+    );
+    if (insertResult.skipped) {
+      return {
+        mode,
+        filePath: current2.filePath,
+        encoding: current2.encoding,
+        anchor: insertResult.anchor,
+        occurrence: insertResult.occurrence,
+        anchorMatches: insertResult.anchorMatches,
+        inserted: false,
+        skipped: true,
+        bytesRead: current2.bytesRead,
+        bytesWritten: 0
+      };
+    }
+    const buffer2 = import_iconv_lite.default.encode(insertResult.outputText, current2.encoding);
+    await fs2.writeFile(current2.filePath, buffer2);
+    return {
+      mode,
+      filePath: current2.filePath,
+      encoding: current2.encoding,
+      anchor: insertResult.anchor,
+      occurrence: insertResult.occurrence,
+      anchorMatches: insertResult.anchorMatches,
+      inserted: true,
+      skipped: false,
+      bytesRead: current2.bytesRead,
+      bytesWritten: buffer2.byteLength
+    };
+  }
+  assertReplaceArguments(input);
   if (input.oldString.length === 0) {
     throw createGbkError("GBK_EMPTY_OLD_STRING", "oldString \u4E0D\u80FD\u4E3A\u7A7A");
   }
@@ -16698,14 +16823,15 @@ async function replaceGbkFileText(input) {
   }
   const current = await readWholeGbkTextFile(resolved);
   const scope = resolveEditScope(current.content, normalizedInput);
-  const occurrencesBefore = countOccurrences(scope.selectedText, normalizedInput.oldString);
+  const occurrencesBefore = countOccurrences(scope.selectedText, input.oldString);
   if (!replaceAll && occurrencesBefore === 0) {
-    const loose = tryLooseBlockReplace(scope.selectedText, normalizedInput.oldString, normalizedInput.newString);
+    const loose = tryLooseBlockReplace(scope.selectedText, input.oldString, 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);
       return {
+        mode: "replace",
         filePath: current.filePath,
         encoding: current.encoding,
         replacements: 1,
@@ -16717,20 +16843,21 @@ async function replaceGbkFileText(input) {
   }
   if (replaceAll) {
     if (occurrencesBefore === 0) {
-      throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, normalizedInput.oldString));
+      throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
     }
   } else if (occurrencesBefore === 0) {
-    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, normalizedInput.oldString));
+    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
   } else if (occurrencesBefore > 1) {
-    throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${normalizedInput.oldString}`);
+    throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${input.oldString}`);
   }
   const fileNewlineStyle = detectNewlineStyle(current.content);
-  const alignedNewString = fileNewlineStyle === "crlf" ? normalizedInput.newString.replace(/\r\n/g, "\n").replace(/\n/g, "\r\n") : fileNewlineStyle === "lf" ? normalizedInput.newString.replace(/\r\n/g, "\n") : normalizedInput.newString;
-  const replaced = replaceAll ? scope.selectedText.split(normalizedInput.oldString).join(alignedNewString) : scope.selectedText.replace(normalizedInput.oldString, alignedNewString);
+  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 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);
   return {
+    mode: "replace",
     filePath: current.filePath,
     encoding: current.encoding,
     replacements: replaceAll ? occurrencesBefore : 1,
@@ -16764,11 +16891,20 @@ Recommended workflow for large files (when gbk_read returned truncated=true):
 3. gbk_edit(oldString=<content without prefixes>, newString=<new content>)
 
 For large files, use 'startLine'/'endLine' or 'startAnchor'/'endAnchor' to narrow the search scope
-and avoid false matches. Scoped edits also improve performance on very large files.`,
+and avoid false matches. Scoped edits also improve performance on very large files.
+
+Insert mode:
+- Use mode=insertAfter or mode=insertBefore with anchor/content
+- This is recommended when the intent is "insert after label" instead of exact replacement.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    oldString: tool.schema.string().describe("Exact text to replace \u2014 raw file content only, no 'N: ' line number prefixes from gbk_read output"),
-    newString: tool.schema.string().describe("Replacement text \u2014 raw content only, no line number prefixes"),
+    mode: tool.schema.enum(["replace", "insertAfter", "insertBefore"]).optional().describe("Edit mode, default replace"),
+    oldString: tool.schema.string().optional().describe("Exact text to replace in replace mode"),
+    newString: tool.schema.string().optional().describe("Replacement text in replace mode"),
+    anchor: tool.schema.string().optional().describe("Anchor text used by insertAfter/insertBefore"),
+    content: tool.schema.string().optional().describe("Inserted content used by insertAfter/insertBefore"),
+    occurrence: tool.schema.number().int().positive().optional().describe("1-based anchor occurrence for insert mode"),
+    ifExists: tool.schema.enum(["allow", "skip", "error"]).optional().describe("What to do when inserted content already exists at target position"),
     replaceAll: tool.schema.boolean().optional().describe("Replace all occurrences (default: false, requires unique match)"),
     startLine: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("Restrict edit scope to 1-based start line (inclusive)"),
     endLine: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("Restrict edit scope to 1-based end line (inclusive)"),
@@ -16779,13 +16915,21 @@ and avoid false matches. Scoped edits also improve performance on very large fil
   },
   async execute(args, context) {
     const result = await replaceGbkFileText({ ...args, context });
+    const isReplace = !("mode" in result) || result.mode === "replace";
+    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: `GBK \u7F16\u8F91 ${result.encoding.toUpperCase()} x${result.replacements}`,
+      title,
       metadata: {
         filePath: result.filePath,
         encoding: result.encoding,
-        replacements: result.replacements,
-        occurrencesBefore: result.occurrencesBefore,
+        mode: isReplace ? "replace" : result.mode,
+        replacements: isReplace ? result.replacements : void 0,
+        occurrencesBefore: isReplace ? result.occurrencesBefore : void 0,
+        anchor: isReplace ? void 0 : result.anchor,
+        occurrence: isReplace ? void 0 : result.occurrence,
+        anchorMatches: isReplace ? void 0 : result.anchorMatches,
+        inserted: isReplace ? void 0 : result.inserted,
+        skipped: isReplace ? void 0 : result.skipped,
         bytesRead: result.bytesRead,
         bytesWritten: result.bytesWritten
       }