opencode-gbk-tools

为 OpenCode 提供一套自动识别编码的文本工具，以及面向 GBK / GB18030 的专用工具。

解决 OpenCode 内置工具难以稳定处理非 UTF-8 文本文件的问题，并通过 plugin 让所有 agents 默认获得这些工具与规则，无需单独切换专属 GBK 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_*”的系统提示，并统一开放 gbk_* 工具 |

安装

npx opencode-gbk-tools install

安装完成后会注册 opencode-gbk-tools plugin，由该 plugin 统一向全部 agents 暴露 text_* / gbk_* 工具与规则。

重启 OpenCode 后，全部 agents 都会默认获得：

• text_read / text_write / text_edit
• gbk_read / gbk_write / gbk_edit / gbk_search
• 对文本文件优先使用 text_* 的系统提示

不再需要单独安装或切换专属 gbk-engine agent。

卸载

一键卸载（对应一键安装）

如果当初是用 npx opencode-gbk-tools install 全局安装的，执行：

npx opencode-gbk-tools uninstall

卸载后会移除已安装的工具、plugin 与 manifest，所有 agents 恢复为未安装前的默认行为。

工具使用说明

text_read / text_write / text_edit

• 默认 encoding=auto
• 已有文件会尽量保持：
  • 原编码
  • BOM
  • 换行风格
• 新文件在 encoding=auto 下不会自动默认成 utf8，需要显式指定 encoding
• 当前支持：
  • utf8
  • utf8-bom
  • utf16le
  • utf16be
  • gbk
  • gb18030

优先使用建议：

通用文本文件：text_read / text_write / text_edit
明确 GBK 文件：gbk_read / gbk_write / gbk_edit / gbk_search

编辑动作建议：

插入到标签前后：用 mode=insertAfter / insertBefore + anchor/content
精确替换现有文本：用 oldString/newString
文件末尾追加：用 text_write/gbk_write + append=true

text_edit — 通用文本编辑

插入模式示例：

text_edit(filePath="文件路径", mode="insertAfter", anchor="[@SkipCheck_Source]", content="\n你好")
text_edit(filePath="文件路径", mode="insertBefore", anchor="[@SkipCheck_Source]", content="你好\n")
text_edit(filePath="文件路径", mode="insertAfter", anchor="[@标签]", content="\n你好", occurrence=2, ifExists="skip")

替换模式示例：

text_edit(filePath="文件路径", oldString="原文内容", newString="新内容")
text_edit(filePath="文件路径", oldString="原文", newString="新文", startLine=100, endLine=200)

• mode 默认是 replace
• 插入模式下不需要 oldString
• ifExists 默认 skip，可避免重复插入

gbk_read — 读取文件

gbk_read(filePath="文件路径")
gbk_read(filePath="文件路径", offset=100, limit=50)   # 从第100行读取50行
gbk_read(filePath="文件路径", tail=true, limit=30)    # 读取最后30行

• 返回带行号的内容，格式为 行号: 内容
• limit 建议不超过 500 行，大文件请先用 gbk_search 定位

gbk_search — 搜索内容

gbk_search(filePath="文件路径", pattern="搜索关键词")
gbk_search(filePath="文件路径", pattern="[@标签名]", contextLines=5)

• 返回匹配行号及上下文，是处理大文件的第一步

gbk_edit — 编辑文件

gbk_edit(filePath="文件路径", oldString="原文内容", newString="新内容")
gbk_edit(filePath="文件路径", oldString="原文", newString="新文", startLine=100, endLine=200)
gbk_edit(filePath="文件路径", mode="insertAfter", anchor="[@SkipCheck_Source]", content="\n你好")

推荐：如果你的意图是“在标签后插入一行”，优先使用 mode="insertAfter" + anchor/content，不要再强依赖 oldString。

只有在精确替换已有文本时，oldString 才是推荐方案。并且 oldString 必须是文件的原始内容，不能包含 gbk_read 输出的行号前缀。

错误示范（包含行号前缀，会失败）：

oldString="3787: SENDMSG 0 内容"

正确示范（纯文件内容）：

oldString="SENDMSG 0 内容"

gbk_write — 写入文件

gbk_write(filePath="文件路径", content="内容", overwrite=true)   # 覆盖写入
gbk_write(filePath="文件路径", content="\r\n新增内容", append=true)  # 追加到末尾

• append=true：在文件末尾追加内容，文件不存在时自动创建
• overwrite=true：覆盖整个文件

大文件操作建议

对于行数超过 500 行的大文件，推荐以下工作流：

1. gbk_search(pattern="要找的内容") → 获取行号
2. gbk_read(offset=行号-5, limit=20)  → 读取目标区域
3. gbk_edit(oldString=..., newString=..., startLine=..., endLine=...) → 精确编辑

已知限制

• 只支持文本文件，不支持二进制文件
• 自动识别目前只覆盖 utf8、utf8-bom、utf16le、utf16be、gbk、gb18030
• 编码检测在歧义场景下可能返回 TEXT_UNKNOWN_ENCODING，此时应显式指定 encoding
• 对无法映射的字符沿用 iconv-lite 默认替代行为

常见问题

Q：安装后 OpenCode 里看不到工具？ A：重启 OpenCode。工具在 OpenCode 启动时加载，安装后需要重启才生效。

Q：npx 提示找不到命令？ A：请先安装 Node.js（https://nodejs.org/），版本需要 18 或以上。

Q：Windows 路径在哪？ A：全局安装的 plugin 文件位于 C:\Users\你的用户名\.config\opencode\plugins\opencode-gbk-tools.js

Q：gbk_edit 提示"未找到需要替换的文本"？ A：检查 oldString 是否包含了行号前缀（如 "3787: "），去掉行号前缀后重试。若要在文件末尾追加内容，请使用 gbk_write [append=true]。

Q：我只是想在某个标签后插入一行，还要不要传 oldString？ A：不要。现在优先用 mode="insertAfter" 或 mode="insertBefore"，并传 anchor/content。

版本历史

| 版本 | 说明 | |------|------| | 0.1.17 | 修复 OpenCode 以 npm plugin 方式加载包时缺少 ./server 导出导致的插件加载失败问题；补充 main 与 ./server 入口兼容性 | | 0.1.16 | 去掉专属 gbk-engine agent 安装链路，改为通过 plugin + tools 让全部 agents 统一支持 text_* / gbk_*；同步更新安装说明 | | 0.1.15 | 为 GBK 大文件统一引入行字节索引与流式读/搜/改路径，提升局部编辑、搜索与大块修改时的性能、稳定性与准确性 | | 0.1.14 | 重新发布当前稳定产物，核对 npm pack --dry-run 输出包含完整 dist/，为下一次公开发布提供一致的打包基线 | | 0.1.13 | text_write 在新文件 + encoding=auto 下改为显式报错，不再静默默认 utf8；同时优化 text_read 流式读取与 text_edit 预览生成，减少重复读取 | | 0.1.12 | 仅提升发布版本号，用于重新发布当前 0.1.11 的稳定内容 | | 0.1.11 | text_edit / gbk_edit 新增 insertAfter / insertBefore，插入内容不再依赖 oldString；README 与全局提示同步改为“插入优先用 anchor/content” | | 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 | 初始版本 |