AGENTS.md

AGENTS.md — opencode-windows-encoding

项目概述

OpenCode 插件，在 Windows + PowerShell 7 环境下自动为所有 bash/shell 工具调用注入 UTF-8 编码配置，解决 LLM 输出中文/非 ASCII 字符乱码问题。

技术栈

• TypeScript — 源码语言
• tsup — 构建工具（ESM 输出）
• Node.js 内置模块 — 零 npm 运行时依赖
• tsup — 构建工具（ESM 输出）
• Node.js 内置模块 — 零 npm 运行时依赖
• @opencode-ai/plugin — OpenCode 插件 API（import type，编译期擦除）

目录结构

src/
└── utf8-encoding.ts  # 插件源码（单文件，tool.execute.before hook）
dist/                 # 构建输出（gitignore）

构建

npm install      # 安装依赖
npm run build    # tsup 构建 → dist/
npm run typecheck # tsc --noEmit 类型检查

插件机制

插件注册到 OpenCode 的 tool.execute.before hook：

1. 拦截所有 bash/shell 工具调用
2. 在原命令前注入 [Console]::OutputEncoding=... 前缀
3. 跳过已包含 OutputEncoding 的命令（防重复注入）
4. 保留 set VAR="value" && 前缀顺序
5. 调试日志默认关闭，设 OPENCODE_UTF8_DEBUG=1 开启

编码规范

• 使用 strict TypeScript 模式
• 具名导出 Utf8EncodingPlugin + default 导出
• 零 npm 运行时依赖（import type 编译期擦除）
• 调试日志写入 $TMP/utf8-plugin.log，默认关闭（设 OPENCODE_UTF8_DEBUG=1 开启）

提交规范

遵循 Conventional Commits：

• feat: — 新功能
• fix: — 修复
• docs: — 文档
• ci: — CI/CD

发布流程

1. npm run build — 构建
2. npm version <patch|minor|major> — 版本号
3. git push --follow-tags — 推送标签触发 GitHub Actions 自动发布 npm