opencode-gbk-tools 0.1.3 → 0.1.5

package/README.md

@@ -92,6 +92,28 @@ opencode-gbk doctor
 opencode-gbk doctor --project
 ```
 
+## 卸载
+
+如果你是通过 `setup` 或手动修改 `opencode.json` / `opencode.jsonc` 启用 npm plugin：
+
+- 删除 `plugin` 数组中的 `"opencode-gbk-tools"`
+- 如果不再需要 `gbk-engine`，再删除对应 agent 文件
+  - 项目级：`.opencode/agents/gbk-engine.md`
+  - 全局：`~/.config/opencode/agents/gbk-engine.md`
+
+如果你是通过 CLI 安装 agent 或工具文件：
+
+```bash
+opencode-gbk uninstall
+opencode-gbk uninstall --project
+```
+
+说明：
+
+- `opencode-gbk uninstall` 会卸载全局安装到 `~/.config/opencode` 下的文件
+- `opencode-gbk uninstall --project` 会卸载当前项目 `.opencode/` 下的文件
+- `uninstall` 只会删除通过本包 manifest 记录过的文件，不会自动改写你的 `opencode.json` / `opencode.jsonc` plugin 配置
+
 ## Agent
 
 安装后会生成 `gbk-engine`。

package/dist/opencode-tools/gbk_edit.js

@@ -16315,6 +16315,13 @@ function assertPositiveInteger(value, name) {
     throw createGbkError("GBK_INVALID_ARGUMENT", `${name} \u5FC5\u987B\u662F\u6B63\u6574\u6570`);
   }
 }
+function normalizeOptionalPositiveInteger(value, name) {
+  if (value === void 0 || value === -1) {
+    return void 0;
+  }
+  assertPositiveInteger(value, name);
+  return Number(value);
+}
 function assertNotBinary(buffer) {
   if (buffer.includes(0)) {
     throw createGbkError("GBK_BINARY_FILE", "\u7591\u4F3C\u4E8C\u8FDB\u5236\u6587\u4EF6\uFF0C\u65E0\u6CD5\u6309 GBK \u6587\u672C\u5904\u7406");
@@ -16650,12 +16657,17 @@ async function replaceLargeGbkFileText(input) {
   }
 }
 async function replaceGbkFileText(input) {
+  const normalizedInput = {
+    ...input,
+    startLine: normalizeOptionalPositiveInteger(input.startLine, "startLine"),
+    endLine: normalizeOptionalPositiveInteger(input.endLine, "endLine")
+  };
   if (input.oldString.length === 0) {
     throw createGbkError("GBK_EMPTY_OLD_STRING", "oldString \u4E0D\u80FD\u4E3A\u7A7A");
   }
-  const replaceAll = input.replaceAll ?? false;
-  const resolved = await resolveReadableGbkFile(input);
-  const hasScopedRange = input.startLine !== void 0 || input.endLine !== void 0 || input.startAnchor !== void 0 || input.endAnchor !== void 0;
+  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;
   if (resolved.stat.size >= STREAMING_FILE_SIZE_THRESHOLD_BYTES && !hasScopedRange) {
     return await replaceLargeGbkFileText({
       ...resolved,
@@ -16665,10 +16677,10 @@ async function replaceGbkFileText(input) {
     });
   }
   const current = await readWholeGbkTextFile(resolved);
-  const scope = resolveEditScope(current.content, input);
-  const occurrencesBefore = countOccurrences(scope.selectedText, input.oldString);
+  const scope = resolveEditScope(current.content, normalizedInput);
+  const occurrencesBefore = countOccurrences(scope.selectedText, normalizedInput.oldString);
   if (!replaceAll && occurrencesBefore === 0) {
-    const loose = tryLooseBlockReplace(scope.selectedText, input.oldString, input.newString);
+    const loose = tryLooseBlockReplace(scope.selectedText, normalizedInput.oldString, normalizedInput.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);
@@ -16685,14 +16697,14 @@ 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, normalizedInput.oldString));
     }
   } else if (occurrencesBefore === 0) {
-    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
+    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, normalizedInput.oldString));
   } 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: ${normalizedInput.oldString}`);
   }
-  const replaced = replaceAll ? scope.selectedText.split(input.oldString).join(input.newString) : scope.selectedText.replace(input.oldString, input.newString);
+  const replaced = replaceAll ? scope.selectedText.split(normalizedInput.oldString).join(normalizedInput.newString) : scope.selectedText.replace(normalizedInput.oldString, normalizedInput.newString);
   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);
@@ -16708,17 +16720,23 @@ async function replaceGbkFileText(input) {
 
 // src/tools/gbk_edit.ts
 var gbk_edit_default = tool({
-  description: "Edit GBK encoded text files with exact replacement",
+  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.
+Safe to use on files with more than 2000 lines.
+
+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.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    oldString: tool.schema.string().describe("Text to replace"),
+    oldString: tool.schema.string().describe("Exact text to replace (must match file content, not gbk_read output with line numbers)"),
     newString: tool.schema.string().describe("Replacement text"),
-    replaceAll: tool.schema.boolean().optional().describe("Replace all occurrences"),
-    startLine: tool.schema.number().int().positive().optional().describe("Restrict edit to 1-based start line"),
-    endLine: tool.schema.number().int().positive().optional().describe("Restrict edit to 1-based end line"),
-    startAnchor: tool.schema.string().optional().describe("Restrict edit to content after this anchor"),
-    endAnchor: tool.schema.string().optional().describe("Restrict edit to content before this anchor"),
-    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
+    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)"),
+    startAnchor: tool.schema.string().optional().describe("Restrict edit to content after this anchor string"),
+    endAnchor: tool.schema.string().optional().describe("Restrict edit to content before this anchor string"),
+    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding (default: gbk)"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {

package/dist/opencode-tools/gbk_read.js

@@ -16315,6 +16315,13 @@ function assertPositiveInteger(value, name) {
     throw createGbkError("GBK_INVALID_ARGUMENT", `${name} \u5FC5\u987B\u662F\u6B63\u6574\u6570`);
   }
 }
+function normalizeOptionalPositiveInteger(value, name) {
+  if (value === void 0 || value === -1) {
+    return void 0;
+  }
+  assertPositiveInteger(value, name);
+  return Number(value);
+}
 function assertNotBinary(buffer) {
   if (buffer.includes(0)) {
     throw createGbkError("GBK_BINARY_FILE", "\u7591\u4F3C\u4E8C\u8FDB\u5236\u6587\u4EF6\uFF0C\u65E0\u6CD5\u6309 GBK \u6587\u672C\u5904\u7406");
@@ -16556,8 +16563,8 @@ function createTailCollector(limit) {
   };
 }
 async function readGbkFile(input) {
-  const offset = input.offset ?? 1;
-  const limit = input.limit ?? 2e3;
+  const offset = normalizeOptionalPositiveInteger(input.offset, "offset") ?? 1;
+  const limit = normalizeOptionalPositiveInteger(input.limit, "limit") ?? 2e3;
   const tail = input.tail ?? false;
   const resolved = await resolveReadableGbkFile(input);
   if (resolved.stat.size < STREAMING_FILE_SIZE_THRESHOLD_BYTES) {
@@ -16597,13 +16604,21 @@ async function readGbkFile(input) {
 
 // src/tools/gbk_read.ts
 var gbk_read_default = tool({
-  description: "Read GBK encoded text files",
+  description: `Read GBK/GB18030 encoded text files with line numbers.
+
+Returns up to 'limit' lines (default 2000) starting from 'offset'.
+When the file has more lines than the window, 'truncated' is true and 'totalLines' shows the full count.
+
+IMPORTANT: If 'truncated' is true, the returned content is incomplete.
+DO NOT use the returned content as 'oldString' for gbk_edit on a truncated file.
+To edit content beyond the visible window, use gbk_edit with 'startLine'/'endLine' to target the exact range,
+or read the specific range first with 'offset' set to the desired line number.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    offset: tool.schema.number().int().positive().optional().describe("1-based start line"),
-    limit: tool.schema.number().int().positive().optional().describe("Number of lines to read"),
+    offset: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("1-based start line (default: 1)"),
+    limit: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("Number of lines to read (default: 2000). Use -1 to apply the default."),
     tail: tool.schema.boolean().optional().describe("Read last N lines instead of offset-based window"),
-    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
+    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding (default: gbk)"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {

package/dist/plugin/index.js

@@ -16315,6 +16315,13 @@ function assertPositiveInteger(value, name) {
     throw createGbkError("GBK_INVALID_ARGUMENT", `${name} \u5FC5\u987B\u662F\u6B63\u6574\u6570`);
   }
 }
+function normalizeOptionalPositiveInteger(value, name) {
+  if (value === void 0 || value === -1) {
+    return void 0;
+  }
+  assertPositiveInteger(value, name);
+  return Number(value);
+}
 function assertNotBinary(buffer) {
   if (buffer.includes(0)) {
     throw createGbkError("GBK_BINARY_FILE", "\u7591\u4F3C\u4E8C\u8FDB\u5236\u6587\u4EF6\uFF0C\u65E0\u6CD5\u6309 GBK \u6587\u672C\u5904\u7406");
@@ -16805,8 +16812,8 @@ async function replaceLargeGbkFileText(input) {
   }
 }
 async function readGbkFile(input) {
-  const offset = input.offset ?? 1;
-  const limit = input.limit ?? 2e3;
+  const offset = normalizeOptionalPositiveInteger(input.offset, "offset") ?? 1;
+  const limit = normalizeOptionalPositiveInteger(input.limit, "limit") ?? 2e3;
   const tail = input.tail ?? false;
   const resolved = await resolveReadableGbkFile(input);
   if (resolved.stat.size < STREAMING_FILE_SIZE_THRESHOLD_BYTES) {
@@ -16844,12 +16851,17 @@ async function readGbkFile(input) {
   };
 }
 async function replaceGbkFileText(input) {
+  const normalizedInput = {
+    ...input,
+    startLine: normalizeOptionalPositiveInteger(input.startLine, "startLine"),
+    endLine: normalizeOptionalPositiveInteger(input.endLine, "endLine")
+  };
   if (input.oldString.length === 0) {
     throw createGbkError("GBK_EMPTY_OLD_STRING", "oldString \u4E0D\u80FD\u4E3A\u7A7A");
   }
-  const replaceAll = input.replaceAll ?? false;
-  const resolved = await resolveReadableGbkFile(input);
-  const hasScopedRange = input.startLine !== void 0 || input.endLine !== void 0 || input.startAnchor !== void 0 || input.endAnchor !== void 0;
+  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;
   if (resolved.stat.size >= STREAMING_FILE_SIZE_THRESHOLD_BYTES && !hasScopedRange) {
     return await replaceLargeGbkFileText({
       ...resolved,
@@ -16859,10 +16871,10 @@ async function replaceGbkFileText(input) {
     });
   }
   const current = await readWholeGbkTextFile(resolved);
-  const scope = resolveEditScope(current.content, input);
-  const occurrencesBefore = countOccurrences(scope.selectedText, input.oldString);
+  const scope = resolveEditScope(current.content, normalizedInput);
+  const occurrencesBefore = countOccurrences(scope.selectedText, normalizedInput.oldString);
   if (!replaceAll && occurrencesBefore === 0) {
-    const loose = tryLooseBlockReplace(scope.selectedText, input.oldString, input.newString);
+    const loose = tryLooseBlockReplace(scope.selectedText, normalizedInput.oldString, normalizedInput.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);
@@ -16879,14 +16891,14 @@ 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, normalizedInput.oldString));
     }
   } else if (occurrencesBefore === 0) {
-    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, input.oldString));
+    throw createGbkError("GBK_NO_MATCH", buildNoMatchMessage(scope.selectedText, normalizedInput.oldString));
   } 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: ${normalizedInput.oldString}`);
   }
-  const replaced = replaceAll ? scope.selectedText.split(input.oldString).join(input.newString) : scope.selectedText.replace(input.oldString, input.newString);
+  const replaced = replaceAll ? scope.selectedText.split(normalizedInput.oldString).join(normalizedInput.newString) : scope.selectedText.replace(normalizedInput.oldString, normalizedInput.newString);
   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);
@@ -16959,17 +16971,23 @@ async function writeGbkFile(input) {
 
 // src/tools/gbk_edit.ts
 var gbk_edit_default = tool({
-  description: "Edit GBK encoded text files with exact replacement",
+  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.
+Safe to use on files with more than 2000 lines.
+
+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.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    oldString: tool.schema.string().describe("Text to replace"),
+    oldString: tool.schema.string().describe("Exact text to replace (must match file content, not gbk_read output with line numbers)"),
     newString: tool.schema.string().describe("Replacement text"),
-    replaceAll: tool.schema.boolean().optional().describe("Replace all occurrences"),
-    startLine: tool.schema.number().int().positive().optional().describe("Restrict edit to 1-based start line"),
-    endLine: tool.schema.number().int().positive().optional().describe("Restrict edit to 1-based end line"),
-    startAnchor: tool.schema.string().optional().describe("Restrict edit to content after this anchor"),
-    endAnchor: tool.schema.string().optional().describe("Restrict edit to content before this anchor"),
-    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
+    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)"),
+    startAnchor: tool.schema.string().optional().describe("Restrict edit to content after this anchor string"),
+    endAnchor: tool.schema.string().optional().describe("Restrict edit to content before this anchor string"),
+    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding (default: gbk)"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {
@@ -16980,13 +16998,21 @@ var gbk_edit_default = tool({
 
 // src/tools/gbk_read.ts
 var gbk_read_default = tool({
-  description: "Read GBK encoded text files",
+  description: `Read GBK/GB18030 encoded text files with line numbers.
+
+Returns up to 'limit' lines (default 2000) starting from 'offset'.
+When the file has more lines than the window, 'truncated' is true and 'totalLines' shows the full count.
+
+IMPORTANT: If 'truncated' is true, the returned content is incomplete.
+DO NOT use the returned content as 'oldString' for gbk_edit on a truncated file.
+To edit content beyond the visible window, use gbk_edit with 'startLine'/'endLine' to target the exact range,
+or read the specific range first with 'offset' set to the desired line number.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    offset: tool.schema.number().int().positive().optional().describe("1-based start line"),
-    limit: tool.schema.number().int().positive().optional().describe("Number of lines to read"),
+    offset: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("1-based start line (default: 1)"),
+    limit: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("Number of lines to read (default: 2000). Use -1 to apply the default."),
     tail: tool.schema.boolean().optional().describe("Read last N lines instead of offset-based window"),
-    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
+    encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding (default: gbk)"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {

package/dist/release-manifest.json

@@ -1,18 +1,18 @@
 {
   "manifestVersion": 1,
   "packageName": "opencode-gbk-tools",
-  "packageVersion": "0.1.3",
+  "packageVersion": "0.1.5",
   "artifacts": [
     {
       "relativePath": "tools/gbk_edit.js",
       "kind": "tool",
-      "expectedHash": "c23a8f2fe0dea3f6099cf5ecc27eecc7f5acd85b5f5beb41da09418646a4225a",
+      "expectedHash": "3d0eb2fab5e3eca869923c2a3cc00e58ed429a4be4dbed22d13e5a5343bd5acc",
       "hashAlgorithm": "sha256"
     },
     {
       "relativePath": "tools/gbk_read.js",
       "kind": "tool",
-      "expectedHash": "4ed95d744e6d5a70f578908fe0efc7b70b4a8c416e9a42fd2ed8726c02562cbe",
+      "expectedHash": "799c53835bfe7237c5bf1e4858a67d20fffe00f90958ef48b72877cb95c1c07f",
       "hashAlgorithm": "sha256"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-gbk-tools",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "GBK/GB18030 custom tools and agent for OpenCode",
   "type": "module",
   "license": "MIT",