opencode-gbk-tools 0.1.7 → 0.1.9

package/README.md

@@ -1,158 +1,140 @@
 # opencode-gbk-tools
 
-为 OpenCode 提供一套面向 `GBK` / `GB18030` 文本工程的自定义工具与专用 agent。
+为 OpenCode 提供一套面向 `GBK` / `GB18030` 编码文本文件的自定义工具与专用 agent。
 
-## 功能
+解决 OpenCode 内置工具无法正确读写 GBK 编码文件的问题。
 
-- `gbk_read`
-- `gbk_write`
-- `gbk_edit`
-- `gbk-engine` agent
+---
 
-## 安装
-
-推荐方式：直接作为 OpenCode npm plugin 加载工具。
-
-最方便的一键接入：
-
-```bash
-npx opencode-gbk-tools setup --project
-```
+## 提供的工具
 
-这条命令会自动：
+| 工具 | 用途 |
+|------|------|
+| `gbk_read` | 读取 GBK/GB18030 文件，支持分页、尾部预览 |
+| `gbk_write` | 写入或追加内容到 GBK 文件（`append=true` 支持追加） |
+| `gbk_edit` | 精确替换 GBK 文件中的指定文本块 |
+| `gbk_search` | 在 GBK 文件中搜索关键词，返回行号和上下文 |
+| `gbk-engine` | 专用 agent，引导 AI 正确使用上述工具 |
 
-- 在当前项目写入或更新 `opencode.json`
-- 自动加入 `plugin: ["opencode-gbk-tools"]`
-- 安装 `.opencode/agents/gbk-engine.md`
+---
 
-如果你想装到用户全局 OpenCode 配置：
+## 安装
 
 ```bash
-npx opencode-gbk-tools setup
-```
-
-`opencode.json`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-gbk-tools"]
-}
+npx opencode-gbk-tools install
 ```
 
-这样会直接注册：
+安装完成后**重启 OpenCode**，工具立即生效。
 
-- `gbk_read`
-- `gbk_write`
-- `gbk_edit`
+---
 
-如果你还需要预置 `gbk-engine` agent，请继续使用下面的 CLI 安装方式把 agent 文件写入本地配置目录。
+## 卸载
 
-推荐优先使用 `setup`，`install` 更适合手动拆分安装流程。
+### 一键卸载（对应一键安装）
 
-一次性使用：
+如果当初是用 `npx opencode-gbk-tools install` 全局安装的，执行：
 
 ```bash
-npx opencode-gbk-tools install
+npx opencode-gbk-tools uninstall
 ```
 
-全局安装后使用：
+---
 
-```bash
-npm install -g opencode-gbk-tools
-opencode-gbk install
-opencode-gbk setup
-```
+## 工具使用说明
 
-安装到当前项目：
+### gbk_read — 读取文件
 
-```bash
-opencode-gbk install --project
+```
+gbk_read(filePath="文件路径")
+gbk_read(filePath="文件路径", offset=100, limit=50)   # 从第100行读取50行
+gbk_read(filePath="文件路径", tail=true, limit=30)    # 读取最后30行
 ```
 
-## 目录
-
-- 全局安装目标：`~/.config/opencode`
-- 项目安装目标：当前命令执行目录下的 `.opencode`
+- 返回带行号的内容，格式为 `行号: 内容`
+- `limit` 建议不超过 500 行，大文件请先用 `gbk_search` 定位
 
-## CLI
+### gbk_search — 搜索内容
 
-```bash
-opencode-gbk setup
-opencode-gbk setup --project
+```
+gbk_search(filePath="文件路径", pattern="搜索关键词")
+gbk_search(filePath="文件路径", pattern="[@标签名]", contextLines=5)
+```
 
-opencode-gbk install
-opencode-gbk install --project
-opencode-gbk install --force
+- 返回匹配行号及上下文，是处理大文件的第一步
 
-opencode-gbk uninstall
-opencode-gbk uninstall --project
+### gbk_edit — 编辑文件
 
-opencode-gbk doctor
-opencode-gbk doctor --project
+```
+gbk_edit(filePath="文件路径", oldString="原文内容", newString="新内容")
+gbk_edit(filePath="文件路径", oldString="原文", newString="新文", startLine=100, endLine=200)
 ```
 
-## 卸载
-
-如果你是通过 `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`
+**重要：`oldString` 必须是文件的原始内容，不能包含 `gbk_read` 输出的行号前缀。**
 
-如果你是通过 CLI 安装 agent 或工具文件：
+错误示范（包含行号前缀，会失败）：
+```
+oldString="3787: SENDMSG 0 内容"
+```
 
-```bash
-opencode-gbk uninstall
-opencode-gbk uninstall --project
+正确示范（纯文件内容）：
+```
+oldString="SENDMSG 0 内容"
 ```
 
-说明：
+### gbk_write — 写入文件
 
-- `opencode-gbk uninstall` 会卸载全局安装到 `~/.config/opencode` 下的文件
-- `opencode-gbk uninstall --project` 会卸载当前项目 `.opencode/` 下的文件
-- `uninstall` 只会删除通过本包 manifest 记录过的文件，不会自动改写你的 `opencode.json` / `opencode.jsonc` plugin 配置
+```
+gbk_write(filePath="文件路径", content="内容", overwrite=true)   # 覆盖写入
+gbk_write(filePath="文件路径", content="\r\n新增内容", append=true)  # 追加到末尾
+```
 
-## Agent
+- `append=true`：在文件末尾追加内容，文件不存在时自动创建
+- `overwrite=true`：覆盖整个文件
 
-安装后会生成 `gbk-engine`。
+---
 
-说明：
+## 大文件操作建议
 
-- npm `plugin` 方式负责注册 `gbk_read`、`gbk_write`、`gbk_edit`
-- `setup` 会自动写入 `plugin` 配置并安装 `gbk-engine`
-- `gbk-engine` 仍通过 CLI 安装到 `.opencode/agents/` 或 `~/.config/opencode/agents/`
-- 如果你只需要工具，不需要 agent，只配置 `plugin` 即可
+对于行数超过 500 行的大文件，推荐以下工作流：
 
-它的目标是：
+```
+1. gbk_search(pattern="要找的内容") → 获取行号
+2. gbk_read(offset=行号-5, limit=20)  → 读取目标区域
+3. gbk_edit(oldString=..., newString=..., startLine=..., endLine=...) → 精确编辑
+```
 
-- 文件内容读取必须走 `gbk_read`
-- 文件内容写入必须走 `gbk_write`
-- 文件内容修改必须走 `gbk_edit`
-- 内置 `read`、`edit`、`grep` 被限制
+---
 
 ## 已知限制
 
 - 只支持文本文件，不支持二进制文件
-- 首版不做自动编码识别
-- 只支持 `gbk` 和 `gb18030`
-- `edit: deny` 在 OpenCode 中会一起限制内置 `write`、`patch`、`multiedit`
+- 只支持 `gbk` 和 `gb18030` 编码
 - 对无法映射的字符沿用 `iconv-lite` 默认替代行为
 
-## 大文件建议
+---
 
-- `gbk_read` 支持 `tail` 预览最后 N 行
-- `gbk_read` 返回 `fileSize`、`newlineStyle`、`streamed`、`truncated`
-- `gbk_edit` 支持 `startLine/endLine`
-- `gbk_edit` 支持 `startAnchor/endAnchor`
-- 大文件会自动走更省内存的流式路径
+## 常见问题
 
-## 发布
+**Q：安装后 OpenCode 里看不到工具？**
+A：重启 OpenCode。工具在 OpenCode 启动时加载，安装后需要重启才生效。
 
-```bash
-npm run check
-npm test
-npm run build
-npm pack --dry-run
-```
+**Q：`npx` 提示找不到命令？**
+A：请先安装 Node.js（https://nodejs.org/），版本需要 18 或以上。
+
+**Q：Windows 路径在哪？**
+A：全局安装目录为 `C:\Users\你的用户名\.config\opencode\tools\`
+
+**Q：gbk_edit 提示"未找到需要替换的文本"？**
+A：检查 `oldString` 是否包含了行号前缀（如 `"3787: "`），去掉行号前缀后重试。若要在文件末尾追加内容，请使用 `gbk_write [append=true]`。
+
+---
+
+## 版本历史
+
+| 版本 | 说明 |
+|------|------|
+| 0.1.9 | `gbk_edit` 修复精确匹配路径写入 CRLF 文件时换行风格变 mixed 的 bug |
+| 0.1.8 | `gbk_write` 新增 `append=true` 追加模式 |
+| 0.1.7 | `gbk_edit` 自动剥离行号前缀后重试匹配 |
+| 0.1.6 | 新增 `gbk_search` 搜索工具 |
+| 0.1.5 | 初始版本 |

package/dist/opencode-tools/gbk_edit.js

@@ -16724,7 +16724,9 @@ async function replaceGbkFileText(input) {
   } else if (occurrencesBefore > 1) {
     throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${normalizedInput.oldString}`);
   }
-  const replaced = replaceAll ? scope.selectedText.split(normalizedInput.oldString).join(normalizedInput.newString) : scope.selectedText.replace(normalizedInput.oldString, normalizedInput.newString);
+  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 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);
@@ -16750,6 +16752,12 @@ gbk_read output looks like "3787: SENDMSG 0 content". The "3787: " is a navigati
 oldString must be the raw file content: "SENDMSG 0 content" (no line number prefix).
 Including line numbers in oldString will cause GBK_NO_MATCH even if the content exists.
 
+CRITICAL \u2014 do NOT use bare newlines or whitespace-only as oldString:
+Using oldString="
+" or oldString="" to append content will always fail.
+To append content to the END of a file, use gbk_write with append=true instead:
+  gbk_write(filePath=..., content="\\r\\n\u65B0\u5185\u5BB9", append=true)
+
 Recommended workflow for large files (when gbk_read returned truncated=true):
 1. gbk_search(pattern) \u2192 find exact lineNumber
 2. gbk_read(offset=<lineNumber>, limit=20) \u2192 get the exact block (strip "N: " prefixes)

package/dist/opencode-tools/gbk_write.js

@@ -16314,9 +16314,49 @@ async function writeGbkFile(input) {
   const encoding = input.encoding ?? "gbk";
   const createDirectories = input.createDirectories ?? true;
   const overwrite = input.overwrite ?? false;
+  const append = input.append ?? false;
   const { candidatePath } = await assertPathAllowed(input.filePath, input.context, input.allowExternal ?? false);
   const parent = path2.dirname(candidatePath);
   assertEncodingSupported(encoding);
+  if (append) {
+    try {
+      const parentStat = await fs2.stat(parent);
+      if (!parentStat.isDirectory()) {
+        throw createGbkError("GBK_PARENT_DIRECTORY_MISSING", `\u7236\u76EE\u5F55\u4E0D\u5B58\u5728: ${parent}`);
+      }
+    } catch (error45) {
+      if (error45 instanceof Error && "code" in error45 && error45.code === "ENOENT") {
+        if (!createDirectories) {
+          throw createGbkError("GBK_PARENT_DIRECTORY_MISSING", `\u7236\u76EE\u5F55\u4E0D\u5B58\u5728: ${parent}`);
+        }
+        await fs2.mkdir(parent, { recursive: true });
+      } else if (error45 instanceof Error && "code" in error45) {
+        throw error45;
+      }
+    }
+    let existingContent = "";
+    let existed = false;
+    try {
+      const existingBuffer = await fs2.readFile(candidatePath);
+      existingContent = import_iconv_lite.default.decode(existingBuffer, encoding);
+      existed = true;
+    } catch (error45) {
+      if (!(error45 instanceof Error && "code" in error45 && error45.code === "ENOENT")) {
+        throw createGbkError("GBK_IO_ERROR", `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25: ${candidatePath}`, error45);
+      }
+    }
+    const combined = existingContent + input.content;
+    const buffer = import_iconv_lite.default.encode(combined, encoding);
+    await fs2.writeFile(candidatePath, buffer);
+    return {
+      filePath: candidatePath,
+      encoding,
+      bytesWritten: buffer.byteLength,
+      created: !existed,
+      overwritten: false,
+      appended: true
+    };
+  }
   try {
     const stat = await fs2.stat(candidatePath);
     if (stat.isDirectory()) {
@@ -16370,13 +16410,24 @@ async function writeGbkFile(input) {
 
 // src/tools/gbk_write.ts
 var gbk_write_default = tool({
-  description: "Write GBK encoded text files",
+  description: `Write GBK encoded text files.
+
+**append=true** (recommended for adding content to existing files):
+- Reads the existing file content and appends new content at the end.
+- Works whether the file exists or not (creates it if missing).
+- Use this whenever you want to add lines/content to an existing GBK file.
+- Example: gbk_write(filePath=..., content="\\r\\n\u65B0\u5185\u5BB9", append=true)
+
+**overwrite=true**: Replace the entire file with new content.
+
+**Default (overwrite=false, append=false)**: Fails if the file already exists.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    content: tool.schema.string().describe("Text content to write"),
+    content: tool.schema.string().describe("Text content to write (or append)"),
     encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
     createDirectories: tool.schema.boolean().optional().describe("Create parent directories"),
-    overwrite: tool.schema.boolean().optional().describe("Overwrite existing file"),
+    overwrite: tool.schema.boolean().optional().describe("Overwrite existing file (replaces entire content)"),
+    append: tool.schema.boolean().optional().describe("Append content to existing file instead of overwriting; creates the file if it does not exist"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {

package/dist/plugin/index.js

@@ -16934,7 +16934,9 @@ async function replaceGbkFileText(input) {
   } else if (occurrencesBefore > 1) {
     throw createGbkError("GBK_MULTIPLE_MATCHES", `\u627E\u5230\u591A\u4E2A\u5339\u914D\u9879: ${normalizedInput.oldString}`);
   }
-  const replaced = replaceAll ? scope.selectedText.split(normalizedInput.oldString).join(normalizedInput.newString) : scope.selectedText.replace(normalizedInput.oldString, normalizedInput.newString);
+  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 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);
@@ -16984,9 +16986,49 @@ async function writeGbkFile(input) {
   const encoding = input.encoding ?? "gbk";
   const createDirectories = input.createDirectories ?? true;
   const overwrite = input.overwrite ?? false;
+  const append = input.append ?? false;
   const { candidatePath } = await assertPathAllowed(input.filePath, input.context, input.allowExternal ?? false);
   const parent = path2.dirname(candidatePath);
   assertEncodingSupported(encoding);
+  if (append) {
+    try {
+      const parentStat = await fs2.stat(parent);
+      if (!parentStat.isDirectory()) {
+        throw createGbkError("GBK_PARENT_DIRECTORY_MISSING", `\u7236\u76EE\u5F55\u4E0D\u5B58\u5728: ${parent}`);
+      }
+    } catch (error45) {
+      if (error45 instanceof Error && "code" in error45 && error45.code === "ENOENT") {
+        if (!createDirectories) {
+          throw createGbkError("GBK_PARENT_DIRECTORY_MISSING", `\u7236\u76EE\u5F55\u4E0D\u5B58\u5728: ${parent}`);
+        }
+        await fs2.mkdir(parent, { recursive: true });
+      } else if (error45 instanceof Error && "code" in error45) {
+        throw error45;
+      }
+    }
+    let existingContent = "";
+    let existed = false;
+    try {
+      const existingBuffer = await fs2.readFile(candidatePath);
+      existingContent = import_iconv_lite.default.decode(existingBuffer, encoding);
+      existed = true;
+    } catch (error45) {
+      if (!(error45 instanceof Error && "code" in error45 && error45.code === "ENOENT")) {
+        throw createGbkError("GBK_IO_ERROR", `\u8BFB\u53D6\u6587\u4EF6\u5931\u8D25: ${candidatePath}`, error45);
+      }
+    }
+    const combined = existingContent + input.content;
+    const buffer = import_iconv_lite.default.encode(combined, encoding);
+    await fs2.writeFile(candidatePath, buffer);
+    return {
+      filePath: candidatePath,
+      encoding,
+      bytesWritten: buffer.byteLength,
+      created: !existed,
+      overwritten: false,
+      appended: true
+    };
+  }
   try {
     const stat = await fs2.stat(candidatePath);
     if (stat.isDirectory()) {
@@ -17050,6 +17092,12 @@ gbk_read output looks like "3787: SENDMSG 0 content". The "3787: " is a navigati
 oldString must be the raw file content: "SENDMSG 0 content" (no line number prefix).
 Including line numbers in oldString will cause GBK_NO_MATCH even if the content exists.
 
+CRITICAL \u2014 do NOT use bare newlines or whitespace-only as oldString:
+Using oldString="
+" or oldString="" to append content will always fail.
+To append content to the END of a file, use gbk_write with append=true instead:
+  gbk_write(filePath=..., content="\\r\\n\u65B0\u5185\u5BB9", append=true)
+
 Recommended workflow for large files (when gbk_read returned truncated=true):
 1. gbk_search(pattern) \u2192 find exact lineNumber
 2. gbk_read(offset=<lineNumber>, limit=20) \u2192 get the exact block (strip "N: " prefixes)
@@ -17138,13 +17186,24 @@ Workflow for large files:
 
 // src/tools/gbk_write.ts
 var gbk_write_default = tool({
-  description: "Write GBK encoded text files",
+  description: `Write GBK encoded text files.
+
+**append=true** (recommended for adding content to existing files):
+- Reads the existing file content and appends new content at the end.
+- Works whether the file exists or not (creates it if missing).
+- Use this whenever you want to add lines/content to an existing GBK file.
+- Example: gbk_write(filePath=..., content="\\r\\n\u65B0\u5185\u5BB9", append=true)
+
+**overwrite=true**: Replace the entire file with new content.
+
+**Default (overwrite=false, append=false)**: Fails if the file already exists.`,
   args: {
     filePath: tool.schema.string().describe("Target file path"),
-    content: tool.schema.string().describe("Text content to write"),
+    content: tool.schema.string().describe("Text content to write (or append)"),
     encoding: tool.schema.enum(["gbk", "gb18030"]).optional().describe("Text encoding"),
     createDirectories: tool.schema.boolean().optional().describe("Create parent directories"),
-    overwrite: tool.schema.boolean().optional().describe("Overwrite existing file"),
+    overwrite: tool.schema.boolean().optional().describe("Overwrite existing file (replaces entire content)"),
+    append: tool.schema.boolean().optional().describe("Append content to existing file instead of overwriting; creates the file if it does not exist"),
     allowExternal: tool.schema.boolean().optional().describe("Allow paths outside workspace root")
   },
   async execute(args, context) {

package/dist/release-manifest.json

@@ -1,12 +1,12 @@
 {
   "manifestVersion": 1,
   "packageName": "opencode-gbk-tools",
-  "packageVersion": "0.1.7",
+  "packageVersion": "0.1.9",
   "artifacts": [
     {
       "relativePath": "tools/gbk_edit.js",
       "kind": "tool",
-      "expectedHash": "783a97cc6f7d1378f0b841ce0c6809e93db104aa192a64f72878ce6d432c997e",
+      "expectedHash": "3b8f229a82519dcca21f5b9140bffc112d781390a0c47335a968f1e853ed1dc2",
       "hashAlgorithm": "sha256"
     },
     {
@@ -24,7 +24,7 @@
     {
       "relativePath": "tools/gbk_write.js",
       "kind": "tool",
-      "expectedHash": "fcb35107b599a9d2a60a1549372ef39f9b4e7f3759b5242faca3ed4b0170330f",
+      "expectedHash": "fa69eecf0c6133ebcd670fa81983a2acb5d011128f1ebc4a99fea4f5f1c37136",
       "hashAlgorithm": "sha256"
     },
     {

package/package.json

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