opencode-gbk-tools 0.1.4 → 0.1.6

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/agents/gbk-engine.md

@@ -1,5 +1,5 @@
 ---
-description: 处理 GBK/GB18030 编码文件的专用代理，只使用 gbk_read、gbk_write、gbk_edit
+description: 处理 GBK/GB18030 编码文件的专用代理，只使用 gbk_read、gbk_write、gbk_edit、gbk_search
 mode: primary
 permission:
   read: deny
@@ -18,6 +18,7 @@ permission:
 - 读取文件时优先使用 `gbk_read`
 - 创建或覆盖文件时优先使用 `gbk_write`
 - 修改已有文件时优先使用 `gbk_edit`
+- 在大文件中搜索内容时使用 `gbk_search`
 - 大文件读取优先使用 `gbk_read` 的分页或 `tail` 能力，避免一次读取过多内容
 - 修改时优先缩小编辑范围：能用 `startLine/endLine` 或 `startAnchor/endAnchor` 就不要全文替换
 - 文件发现可使用 `glob`，但文件内容读取必须使用 `gbk_read`
@@ -25,3 +26,14 @@ permission:
 - `edit: deny` 同时覆盖内置 `write`、`patch`、`multiedit`
 - 如果用户请求涉及 UTF-8 文件或二进制文件，先明确说明不适用
 - 若目标文件编码不确定，先提醒用户确认是 `gbk` 还是 `gb18030`
+
+## 大文件编辑工作流（必须遵守）
+
+当 `gbk_read` 返回 `truncated: true` 时，说明文件超出了读取窗口。
+此时若需要编辑文件，**必须按以下步骤操作，禁止直接猜测 oldString**：
+
+1. `gbk_search(filePath, pattern)` — 找到目标内容的精确行号和上下文
+2. `gbk_read(filePath, offset=<lineNumber>, limit=<N>)` — 读取目标行的精确内容
+3. `gbk_edit(filePath, oldString=<精确内容>, newString=<新内容>)` — 用精确内容替换
+
+**禁止**在未确认精确内容的情况下构造 `oldString`，否则 `gbk_edit` 必然报 `GBK_NO_MATCH`。

package/dist/opencode-tools/gbk_edit.js

@@ -16720,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.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("Restrict edit to 1-based start line"),
-    endLine: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).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

@@ -16604,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.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).optional().describe("1-based start line"),
-    limit: tool.schema.union([tool.schema.number().int().positive(), tool.schema.literal(-1)]).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) {