opencode-gbk-tools 0.1.8 → 0.1.10

package/README.md

@@ -1,158 +1,167 @@
 # opencode-gbk-tools
 
-为 OpenCode 提供一套面向 `GBK` / `GB18030` 文本工程的自定义工具与专用 agent。
+为 OpenCode 提供一套自动识别编码的文本工具，以及面向 `GBK` / `GB18030` 的专用工具。
 
-## 功能
+解决 OpenCode 内置工具难以稳定处理非 UTF-8 文本文件的问题，并让所有 agents 默认优先使用可保留原编码的 `text_*` 工具。
 
-- `gbk_read`
-- `gbk_write`
-- `gbk_edit`
-- `gbk-engine` agent
+---
 
-## 安装
+## 提供的工具
+
+| 工具 | 用途 |
+|------|------|
+| `text_read` | 自动识别文件编码并按行读取，优先用于通用文本文件 |
+| `text_write` | 自动保持已有文件编码、BOM 和换行风格后写入 |
+| `text_edit` | 自动保持已有文件编码、BOM 和换行风格后编辑 |
+| `gbk_read` | 读取 GBK/GB18030 文件，支持分页、尾部预览 |
+| `gbk_write` | 写入或追加内容到 GBK 文件（`append=true` 支持追加） |
+| `gbk_edit` | 精确替换 GBK 文件中的指定文本块 |
+| `gbk_search` | 在 GBK 文件中搜索关键词，返回行号和上下文 |
+| 本地/全局 plugin 规则 | 给所有 agents 注入“优先使用 `text_*`”的系统提示 |
 
-推荐方式：直接作为 OpenCode npm plugin 加载工具。
+---
 
-最方便的一键接入：
+## 安装
 
 ```bash
-npx opencode-gbk-tools setup --project
+npx opencode-gbk-tools install
 ```
 
-这条命令会自动：
+安装完成后**重启 OpenCode**，工具立即生效。
 
-- 在当前项目写入或更新 `opencode.json`
-- 自动加入 `plugin: ["opencode-gbk-tools"]`
-- 安装 `.opencode/agents/gbk-engine.md`
+---
 
-如果你想装到用户全局 OpenCode 配置：
+## 卸载
 
-```bash
-npx opencode-gbk-tools setup
-```
+### 一键卸载（对应一键安装）
 
-`opencode.json`:
+如果当初是用 `npx opencode-gbk-tools install` 全局安装的，执行：
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-gbk-tools"]
-}
+```bash
+npx opencode-gbk-tools uninstall
 ```
 
-这样会直接注册：
+---
 
-- `gbk_read`
-- `gbk_write`
-- `gbk_edit`
+## 工具使用说明
 
-如果你还需要预置 `gbk-engine` agent，请继续使用下面的 CLI 安装方式把 agent 文件写入本地配置目录。
+### text_read / text_write / text_edit
 
-推荐优先使用 `setup`，`install` 更适合手动拆分安装流程。
+- 默认 `encoding=auto`
+- 已有文件会尽量保持：
+  - 原编码
+  - BOM
+  - 换行风格
+- 当前支持：
+  - `utf8`
+  - `utf8-bom`
+  - `utf16le`
+  - `utf16be`
+  - `gbk`
+  - `gb18030`
 
-一次性使用：
+优先使用建议：
 
-```bash
-npx opencode-gbk-tools install
+```text
+通用文本文件：text_read / text_write / text_edit
+明确 GBK 文件：gbk_read / gbk_write / gbk_edit / gbk_search
 ```
 
-全局安装后使用：
+### gbk_read — 读取文件
 
-```bash
-npm install -g opencode-gbk-tools
-opencode-gbk install
-opencode-gbk setup
 ```
-
-安装到当前项目：
-
-```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`
+- 自动识别目前只覆盖 `utf8`、`utf8-bom`、`utf16le`、`utf16be`、`gbk`、`gb18030`
+- 编码检测在歧义场景下可能返回 `TEXT_UNKNOWN_ENCODING`，此时应显式指定 `encoding`
 - 对无法映射的字符沿用 `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.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` 追加模式 |
+| 0.1.7 | `gbk_edit` 自动剥离行号前缀后重试匹配 |
+| 0.1.6 | 新增 `gbk_search` 搜索工具 |
+| 0.1.5 | 初始版本 |

package/dist/cli/index.js

@@ -60,7 +60,7 @@ 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"]);
+  const allowedArtifacts = new Set(args.artifacts ?? ["tool", "agent", "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);
@@ -70,7 +70,7 @@ async function installCommand(args) {
       throw new Error(`\u68C0\u6D4B\u5230\u672A\u53D7\u7BA1\u6587\u4EF6\u51B2\u7A81: ${targetPath}`);
     }
     await ensureDir(path3.dirname(targetPath));
-    const sourceRoot = artifact.kind === "tool" ? path3.join(args.packageRoot, "dist", "opencode-tools") : path3.join(args.packageRoot, "dist", "agents");
+    const sourceRoot = artifact.kind === "tool" ? path3.join(args.packageRoot, "dist", "opencode-tools") : artifact.kind === "agent" ? path3.join(args.packageRoot, "dist", "agents") : path3.join(args.packageRoot, "dist", "plugins");
     await fs3.copyFile(path3.join(sourceRoot, path3.basename(artifact.relativePath)), targetPath);
   }
   const installedManifest = {
@@ -181,7 +181,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"] });
+  const installResult = await installCommand({ ...args, force: true, artifacts: ["agent", "plugin"] });
   return {
     configPath,
     targetBase: installResult.targetBase

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);
@@ -16777,6 +16779,17 @@ and avoid false matches. Scoped edits also improve performance on very large fil
   },
   async execute(args, context) {
     const result = await replaceGbkFileText({ ...args, context });
+    context.metadata({
+      title: `GBK \u7F16\u8F91 ${result.encoding.toUpperCase()} x${result.replacements}`,
+      metadata: {
+        filePath: result.filePath,
+        encoding: result.encoding,
+        replacements: result.replacements,
+        occurrencesBefore: result.occurrencesBefore,
+        bytesRead: result.bytesRead,
+        bytesWritten: result.bytesWritten
+      }
+    });
     return JSON.stringify(result, null, 2);
   }
 });

package/dist/opencode-tools/gbk_read.js

@@ -16632,6 +16632,19 @@ Workflow when truncated=true:
   },
   async execute(args, context) {
     const result = await readGbkFile({ ...args, context });
+    const lineRange = `${result.startLine}-${result.endLine}`;
+    context.metadata({
+      title: `GBK \u8BFB\u53D6 ${result.encoding.toUpperCase()} ${lineRange}`,
+      metadata: {
+        filePath: result.filePath,
+        encoding: result.encoding,
+        lineRange,
+        totalLines: result.totalLines,
+        newlineStyle: result.newlineStyle,
+        truncated: result.truncated,
+        tail: result.tail
+      }
+    });
     return JSON.stringify(result, null, 2);
   }
 });

package/dist/opencode-tools/gbk_search.js

@@ -16454,6 +16454,15 @@ Workflow for large files:
   },
   async execute(args, context) {
     const result = await searchGbkFile({ ...args, context });
+    context.metadata({
+      title: `GBK \u641C\u7D22 ${result.encoding.toUpperCase()} ${result.matchCount} \u547D\u4E2D`,
+      metadata: {
+        filePath: result.filePath,
+        encoding: result.encoding,
+        totalLines: result.totalLines,
+        matchCount: result.matchCount
+      }
+    });
     return JSON.stringify(result, null, 2);
   }
 });

package/dist/opencode-tools/gbk_write.js

@@ -16432,6 +16432,18 @@ var gbk_write_default = tool({
   },
   async execute(args, context) {
     const result = await writeGbkFile({ ...args, context });
+    const action = result.appended ? "\u8FFD\u52A0" : result.overwritten ? "\u8986\u76D6" : "\u5199\u5165";
+    context.metadata({
+      title: `GBK ${action} ${result.encoding.toUpperCase()}`,
+      metadata: {
+        filePath: result.filePath,
+        encoding: result.encoding,
+        created: result.created,
+        overwritten: result.overwritten,
+        appended: result.appended ?? false,
+        bytesWritten: result.bytesWritten
+      }
+    });
     return JSON.stringify(result, null, 2);
   }
 });