opencode-gbk-tools

为 OpenCode 提供一套面向 GBK 的专用工具，并保留普通 UTF 文本优先使用 OpenCode 内置工具的路由规则。

解决 OpenCode 内置工具难以稳定处理非 UTF-8 文本文件的问题，并通过 plugin 为所有 agents 注入 GBK 路由规则与 gbk_* 工具；同时提供一个只允许调用 gbk_* 自定义工具的 gbk-engine agent。

提供的工具

| 工具 | 用途 | |------|------| | gbk_read | 读取 GBK 文件，支持分页、尾部预览 | | gbk_write | 写入或追加内容到 GBK 文件（append=true 支持追加） | | gbk_edit | 精确替换 GBK 文件中的指定文本块 | | gbk_search | 在 GBK 文件中搜索关键词，返回行号和上下文 | | 本地/全局 plugin 规则 | 给所有 agents 注入“UTF-8 优先内置工具，GBK/乱码风险优先 gbk_*”的系统提示，并在 /gbk-on 时强制拦截内置工具 | | gbk-engine agent | 禁用 OpenCode 内置读写编辑工具，只保留 gbk_* 自定义工具 |

安装

npx opencode-gbk-tools setup

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

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

• gbk_read / gbk_write / gbk_edit / gbk_search
• 按编码分流的系统提示：UTF-8 优先内置工具，GBK/乱码风险优先 gbk_*
• .opencode/agents/gbk-engine.md 或 ~/.config/opencode/agents/gbk-engine.md
• .opencode/commands/gbk-on.md / .opencode/commands/gbk-off.md 或 ~/.config/opencode/commands/gbk-on.md / gbk-off.md

如果你希望强制禁用内置 read / write / edit / apply_patch，可以直接切换到专属 gbk-engine agent。

卸载

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

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

npx opencode-gbk-tools uninstall

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

工具使用说明

普通会话与 GBK 模式

• 普通 UTF-8 / UTF-16 文本：优先使用 OpenCode 内置 read、write、edit
• 遇到 GBK 文件、中文乱码、非 UTF-8 旧文本：优先使用 gbk_read、gbk_write、gbk_edit、gbk_search
• 新建 .txt 文件时，优先直接使用 gbk_write 创建；plugin 会把这类创建请求优先路由到 gbk_*
• 普通会话下不会因为历史记忆或自动检测结果就强制改走 gbk_*
• 只有手动执行 /gbk-on 或 gbk_mode(mode="on") 后，当前会话与子会话才会统一强制改走 gbk_*
• /gbk-off 或 gbk_mode(mode="off") 会恢复普通混合路由

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你好")

批量模式示例：

gbk_edit(
  filePath="文件路径",
  operations=[
    {"type":"insertAfterLine","line":50,"content":"新增内容A\n"},
    {"type":"insertAfterLine","line":60,"content":"新增内容B\n"},
    {"type":"replace","oldString":"旧内容","newString":"新内容","replaceAll":true}
  ]
)

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

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

批量模式下，所有 line / anchor / replace 都按原始文件坐标解析，然后一次性写回；前面的插入不会把后面的原始行号挤偏。若多个批量操作命中重叠原始区域，会直接报错，不会自动猜测。

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

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
• 编码检测在歧义场景下可能返回 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。

Q：我想让当前会话都走 GBK 工具，但不想切换 agent，怎么做？ A：最方便的方式是直接在 OpenCode 里输入 /gbk-on。它会先调用 gbk_mode(mode="on")，然后把当前会话切成 GBK 模式；需要恢复普通模式时，输入 /gbk-off。

版本历史

| 版本 | 说明 | |------|------| | 1.6.0 | 固定为单一 GBK 编码：移除 gb18030 分支；新增 gbk_tags 结构索引；gbk_search 批量搜索与输出瘦身，显著提升大脚本维护效率 | | 1.4.1 | 放宽 gbk_search 校验：空 pattern + patterns 数组自动忽略空串；LLM 同时传参不再误报错 | | 1.3.0 | gbk_read / gbk_search 输出纯文本化（去除 JSON 包裹）；工具输出截断保护增强；协议截断适配完成 | | 1.1.22 | gbk_search 输出从全量 JSON 改为结构化文本；流式阈值 1MB→4MB；粘贴占位符拦截；错误消息泛化；matchLooseBlock 加速 | | 1.1.18 | 彻底移除编辑链路中的 diff 生成与回传：gbk_edit、text_edit 及其底层库不再生成或暴露 diffPreview，避免 diff 内容污染会话；同时把锚点/替换失败等错误信息改为泛化文案，不再把用户原始粘贴内容、锚点文本或待替换原文直接拼进报错里 | | 1.1.17 | 彻底收紧普通会话工具暴露与卸载清理：普通会话不再向模型暴露 text_read、text_write、text_edit，避免模型在未被要求时自动选择 ⚙ text_edit；同时修复 uninstall 在 manifest 丢失时不会兜底清理 .opencode/plugins、.opencode/agents、.opencode/commands 残留的问题，降低“明明卸载了但行为还像装着”的复发概率 | | 1.1.16 | 删除会话完成系统通知相关逻辑：此前多轮修复后在真实 OpenCode 使用中仍未达到可接受效果，因此移除 session.idle / session.status 通知状态机、安装入口默认通知接线与对应测试，避免继续让插件声明一个实际无效的右下角系统弹窗能力；插件回归只提供 GBK/GB18030 与自动编码文本工具 | | 1.1.14 | 修复正式安装版会话完成系统通知在真实 Windows 环境下不弹的问题：此前全局插件文件仍沿用 CreateToastNotifier("PowerShell") 的旧实现，手动测试命令可弹但 OpenCode 正式加载的已安装插件不会稳定显示；现已将安装版与构建产物统一改为使用有效的 Windows PowerShell AppUserModelID，并保留主会话过滤、session.status idle 兼容、延迟触发与 busy/error 抑制逻辑 | | 1.1.13 | 继续加固会话完成系统通知的真实运行时链路：除 session.idle 外，同时兼容 session.status 的 idle 状态；新增短延迟触发、busy/retry 取消、error 抑制与同一会话后续轮次可再次通知的时序控制，减少主会话通知漏发、误发或只触发一次的问题 | | 1.1.12 | 调整会话完成系统通知文案：标题继续使用会话标题，正文从“完成本次对话！”统一改为“完成本次会话”；保留仅主会话通知、过滤子代理、与 GBK 工具链隔离的行为不变 | | 1.1.11 | 修复已发布安装版不弹会话完成通知的问题：此前全局/本地安装实际加载的是 dist/plugins/opencode-gbk-tools.js 对应的本地插件入口，但该入口没有接入默认通知回调，导致“源码调试可弹、npm 安装后不弹”；现已统一主插件入口与本地插件入口的默认接线，并新增安装入口回归测试，确保已安装版本在主会话 session.idle 时也会正常触发系统通知 | | 1.1.10 | 修复 Windows 终端下的会话完成系统通知后端：将原先不稳定的 PowerShell 内联 XML Toast 实现改为更可靠的 EncodedCommand + ToastTemplateType 方案，继续保留“仅主会话通知、过滤子代理、标题为会话标题、内容为‘完成本次对话！’”的行为；该修复与 GBK 工具链隔离，不影响现有 gbk_*、/gbk-on、编码记忆与路由逻辑 | | 1.1.9 | 新增会话完成系统通知：主会话在 session.idle 时会弹出系统通知，标题使用会话标题，内容固定为“完成本次对话！”，并默认过滤所有子代理/子会话通知；通知逻辑与 GBK 工具链隔离，失败时静默忽略，不影响现有 gbk_*、/gbk-on、编码记忆与路由行为 | | 1.1.8 | 调整 GBK 记忆与路由策略：保留编码记忆，但默认不再因为历史记忆或首次自动检测就在普通会话里强制拦截内置 read/write/edit 与 text_*；只有手动开启 /gbk-on 或 gbk_mode(mode=on) 时，当前会话及子会话才统一强制改走 gbk_* | | 1.1.7 | 新增 /gbk-on、/gbk-off 与 gbk_mode 会话级开关：允许普通 agent 在当前主会话内一键开启/关闭 GBK 模式，并让后续子代理会话自动继承父会话的 GBK 状态。开启后，plugin 会拦截内置 read/write/edit 与 text_*，统一要求改用 gbk_read、gbk_write、gbk_edit、gbk_search；关闭后当前会话与后续子会话一起恢复普通混合路由 | | 1.1.6 | 为 gbk_edit 新增批量编辑能力：支持 operations=[...] 一次性执行批量按行号插入、批量按锚点插入和批量替换，并统一按原始文件坐标解析后再一次写回，避免前序插入导致后续 line / anchor 漂移；同时新增重叠原始区域冲突检测，冲突时直接报错，防止静默错改 | | 1.1.5 | 补齐 text_read / gbk_read 的负 offset 语义：支持用负数直接从文件尾部回看；同时继续加固插件会话防御，对 tool.execute.after 的 metadata 做通用裁剪，不再只截断 diffPreview，降低大字符串、深层对象或超长数组再次把宿主会话/压缩链路拖爆的风险 | | 1.1.4 | 修复 setup/uninstall 的插件配置链路：不再把配置写成 opencode-gbk-tools 包名，改为稳定写入已安装本地插件文件的 file://.../plugins/opencode-gbk-tools.js 引用，并在 setup 时自动迁移旧包名配置、在 uninstall 时同时清理新旧两种配置，避免 OpenCode 继续走 npm/cache 插件解析链路而误加载旧缓存版本（如 0.1.24）导致 diff.before.length 一类旧逻辑再次生效 | | 1.1.3 | 规避 OpenCode 会话压缩阶段的宿主侧异常：移除插件自定义 compaction 提示注入，缩短默认系统提示，并进一步收紧 diffPreview metadata 截断上限，降低发送大段日志或长文本后触发会话压缩报错的概率 | | 1.1.2 | 增强 GBK 路由可观测性：区分“已记忆命中 / 当前会话已锁定 / 首次检测命中”三种拦截提示，并为同一会话内已判定为 GBK 的目标文件增加会话级路径锁，减少反复误用 text_* 或内置工具；其余路由规则保持不变 | | 1.1.1 | 收敛最终路由规则并修正文档：继续保留“新建 .txt 强制走 gbk_write”，已有文件则严格按真实检测结果路由；一旦检测/记忆为 GBK/GB18030，就对该目标文件直接禁用内置 read/write/edit 与 text_*，后续统一走 gbk_*；同时把安装说明统一更正为 npx opencode-gbk-tools setup | | 1.1.0 | 首个 1.x 稳定版本：保留 GBK/GB18030 路由、记忆与新建 .txt 走 gbk_write 的规则；对已确认或首次检测为 GBK/GB18030 的目标文件，统一禁止内置读写编辑工具与 text_*，直接改走 gbk_*；同时修复插件层同步自动 summarize 可能导致的会话卡住问题，并为会话状态与 gbk-file 行索引缓存增加边界控制，降低长会话和多文件场景下的阻塞与内存累积风险 | | 0.1.31 | 在 0.1.30 基础上继续收紧新建文件路由：新建 .txt 文件必须优先直接使用 gbk_write，不再先走 text_write 或内置 write/edit；并新增“当前会话一旦成功使用过 gbk_*，后续新建文件继续优先走 gbk_*”的插件级约束与测试覆盖 | | 0.1.30 | 补强 text_* 针对真实 GBK 样本与大体积重复样本的高强度测试：新增 QFunction-0.txt 真实样本读取、编辑、追加与端到端工作流覆盖，并补充大文件重复样本下的 text_read / text_edit 行为验证；同时继续收紧路由规则：新建 .txt 文件直接要求改用 gbk_write，且当前会话一旦使用过 gbk_*，后续新建文件也继续要求走 gbk_* | | 0.1.29 | 在方案 B 基础上新增 GBK 文件持久记忆：普通 agent 继续按编码分流，UTF-8 优先使用 OpenCode 内置工具；对现有文件，已确认或首次检测到是 GBK/GB18030 的路径会按完整路径 + mtime/size 持久记忆；后续再次操作同一路径时，text_* 与内置 read / write / edit 都会被直接拦截并提示改用 gbk_*，避免先误走 text_edit / edit 再失败；gbk-engine 继续保持为强制 GBK 专属模式 | | 0.1.28 | 调整为方案 B：普通 agent 按编码分流，UTF-8 优先使用 OpenCode 内置工具，GBK/乱码风险优先使用 gbk_*；gbk-engine 保持为强制 GBK 专属模式；同时修复 src/lib/gbk-file.ts 中多处用户可见乱码错误文案，并增强 text_* 的匹配容错与大文件流式替换稳定性 | | 0.1.27 | 重新发布当前稳定内容，包含：新建 .txt 文件在 encoding=auto 下默认使用 gbk；保留已有文件的原编码检测与保持逻辑；修复 plugin 追加 system 规则时可能触发部分 Jinja/chat template 的“System message must be at the beginning”异常；同步更新工具提示、README 与测试覆盖 | | 0.1.26 | 仅提升发布版本号，用于重新发布当时的稳定内容 | | 0.1.25 | 恢复并正式发布专属 gbk-engine agent；通过 agent 白名单禁用内置 read / write / edit / apply_patch，只保留 text_* / gbk_* 自定义工具，并把 agent 纳入构建、安装与 release manifest | | 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 | 初始版本 |