opencode-gbk-tools 0.1.8 → 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);

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);

package/dist/release-manifest.json

@@ -1,12 +1,12 @@
 {
   "manifestVersion": 1,
   "packageName": "opencode-gbk-tools",
-  "packageVersion": "0.1.8",
+  "packageVersion": "0.1.9",
   "artifacts": [
     {
       "relativePath": "tools/gbk_edit.js",
       "kind": "tool",
-      "expectedHash": "68d8398eae66592166de62e1bdce35ac51a6c22f27e6b48eca83c62370bc44f5",
+      "expectedHash": "3b8f229a82519dcca21f5b9140bffc112d781390a0c47335a968f1e853ed1dc2",
       "hashAlgorithm": "sha256"
     },
     {

package/package.json

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