一台 Windows 中文系统上调好的 opencode 全局配置，打包成可在别的电脑上复现的形式。
内容 = 模型接入（3 个中转站 / 7 个模型） + Windows 中文编码修复 + 文本模型识图链路 + context7 查文档 + 4 个 skill。
仓库里只有源文件。PowerShell 7 离线安装包（108 MB）与打包好的 zip 在 Releases 里——GitHub 单文件上限 100 MB，二进制放不进仓库。
| 方式 | 做法 |
|---|---|
| 想要离线安装包（目标机不便下载 PS7） | 从 Releases 下载 opencode-optimization-pack-*.zip，解压即得完整包（含 vendor/PowerShell-7.6.5-win-x64.msi） |
| 只要配置文件 | 直接 clone 或下载仓库 zip。目标机已装 PowerShell 7 的话足够用；没装的话按 SETUP.md 3.1 的替代方案联网装 |
Release 里也单独附了 PowerShell-7.6.5-win-x64.msi，可只下它。校验值见 vendor/SHA256SUMS.txt。
- 把这个文件夹整体拷到目标机（U 盘 / 网盘 / 解压 zip 都行）。
- 在 opencode 里打开这个文件夹。
- 对 agent 说：「读 SETUP.md，按它给我这台电脑做配置」。
agent 会先检测环境、把要改的东西列给你确认，再逐步执行并验证。全过程需要你提供 API key、批准管理员提权（仅装 PowerShell 7 时）。
装完跑一次自检：
pwsh -NoProfile -File .\verify.ps1不想让 agent 动手就自己照 SETUP.md 做，步骤是一样的。
API key 的安全提醒：不要把 key 直接发在与 agent 的对话里——opencode 会把对话内容明文记进
~\.local\share\opencode\log\。自己在终端里用[Environment]::SetEnvironmentVariable(...)设置，让 agent 只做存在性验证（SETUP.md 第 5 章）。
| 模块 | 文件 | 解决什么问题 |
|---|---|---|
| 模型接入 | files/opencode.jsonc | 3 个中转站 provider、7 个模型声明；补齐 limit 与 reasoning 档位，附大量实测注释 |
| shell 钉死 | 同上 "shell": "pwsh" | 防止落到 PowerShell 5.1（不支持 &&/` |
| 中文编码 | files/plugins/encoding-fix.js | GBK 系统上 opencode 的 shell 输出乱码且不可逆丢字 |
| 识图（落盘） | files/plugins/vision-fallback.js | 贴的图只在消息库里，磁盘无文件，模型拿不到 |
| 识图（服务） | files/vision_server.py | MCP 服务器，把图发给视觉模型换回文字 |
| 识图（路由） | files/skills/vision-routing/ | 什么时候用原生视觉、什么时候调工具、不许猜路径 |
| 查文档 | files/opencode.jsonc 的 context7 + files/AGENTS.md | 第三方库 API 凭记忆写容易错 |
| 通用 skills | files/skills/ 另 3 个 | 系统化调试、完成前必须验证、并行派发子 agent |
| 终端 UTF-8 | files/snippets/pwsh-utf8-profile.ps1 | 可选；管你自己开的终端，不管 opencode |
| 安装自检 | verify.ps1 | 一次跑完可自动化的验证项，含 skill frontmatter 的静默失效检查 |
| 离线依赖 | vendor/PowerShell-7.6.5-win-x64.msi | 目标机没装 PS7 且不便下载时直接装 |
| 层 | 症状 | 本包的措施 |
|---|---|---|
| opencode 启动的 shell 进程 | 服务名、系统报错、原生 exe 输出里的中文变 U+FFFD，信息不可逆丢失 | encoding-fix 插件在每条命令前注入 $OutputEncoding=[Console]::OutputEncoding=UTF8 |
| shell 选型 | 落到 PS 5.1 → && 语法错 | "shell": "pwsh" + 自带 PS7 安装包 |
| git 输出 | 中文文件名显示成 "dist/PDF\345\233\276..." | git config --global core.quotepath false |
| 你自己的终端 | 手动跑 python/git 时中文乱码 | 可选的 profile 片段 |
第一层的插件为什么不能省：opencode 以 pwsh -NoLogo -NoProfile -NonInteractive 启动 shell，-NoProfile 让 profile 里的 UTF-8 设置失效；进程也没有 console，chcp 改不动。所以只能逐条命令注入。
实测（码点级）：不注入时中文行 = U+FFFD U+FFFD U+FFFD U+0132…，注入后 = U+4E2D U+6587 U+6D4B U+8BD5。
不动系统 ACP、不动注册表，因此依赖 GBK 的老软件（ArcGIS / ENVI 等）不受影响。
不支持原生视觉的模型（如 deepseek-v4-flash）遇到用户贴图时：
用户贴图
↓
vision-fallback 插件 读配置里的 modalities.input 判断模型是否原生支持视觉
↓ 不支持 支持 → 插件完全让路，什么都不做
把 base64 落盘到 %TEMP%\opencode-vision\，并注入一条含真实绝对路径的提示
↓
vision-routing skill 「意图看用户、能力看自己」的路由表，禁止猜路径、
↓ 禁止用剪贴板顶替
vision-helper MCP analyze_image(路径, prompt) → 视觉模型 → 文字描述
为什么需要落盘：opencode 里贴的图只存在消息库中（base64 data URL），磁盘上没有文件。模型即使知道要调 MCP 识图，也只能猜路径（必然失败）或误读系统剪贴板（拿到无关的旧图，得出完全错误的结论）。
落盘目录由插件自行回收：每次写入前删掉 7 天前的旧图。
给某个模型补上 modalities: { input: ["text","image"] } 后，插件会自动让路——本包给 gpt-5.6-sol 和几个 Claude 都补了，它们走原生视觉，不花识图调用的钱。
agentrouter 与 agentrouter-anthropic 指向同一个 baseURL，但走不同协议：
- OpenAI 兼容端点（
/v1/chat/completions）：Claude 的reasoning_effort被静默丢弃——任意档位（含非法值）都返回 200，响应里没有reasoning_content，reasoning_tokens恒为 0。等于看不见思考过程。 - Anthropic 原生端点（
/v1/messages）：能返回可读的 thinking 块。
所以 Claude 被 blacklist 从 OpenAI 兼容那侧删掉，统一走原生端点那侧。
顺带一个反直觉的实测结论：effort 档位对 Claude 的思考量没有可测影响（low/medium/high/xhigh/max 的结果非单调）。这个拆分换来的是"能看到思考过程"，不是"能控制思考深度"。
其余实测结论都写在 files/opencode.jsonc 的注释里，包括：
- 各模型实际支持的 reasoning 档位枚举（哪些档位会 400）
- 不被 models.dev 收录的 provider/模型必须显式写
limit，否则信息面板显示"上下文 0" claude-opus-4-8的 output 上限实测为 128000（填 200000 会报错）- JustWoker 上最小请求
hi就消耗 6847 input tokens（同请求在 AgentRouter 只消耗 8），说明上游注入了约 6.8K 隐藏系统提示，实际可用上下文比标称值少这一块 - 故意不填
cost：上游价格 ≠ 中转站转售价，填了会误导成本统计
| skill | 作用 |
|---|---|
vision-routing | 图片请求路由（与上面的识图链路配套） |
systematic-debugging | 先找根因再改，四阶段流程；3 次修复失败就质疑架构 |
verification-before-completion | 宣称"完成/通过"之前必须有当次验证输出 |
dispatching-parallel-agents | 多个独立任务时并行派发子 agent 的判据与提示写法 |
后三个源自 Anthropic 的 agent skills 生态（措辞里的 "your human partner" 即出处特征），按本地环境做了少量调整。
skill 会静默失效，务必跑 verify.ps1 确认。SKILL.md 的 YAML frontmatter 一旦解析失败，opencode 直接过滤掉这个 skill——不报错、不警告，只是它不在列表里。v20260830 的 vision-routing 就中过：description 里 involves images: 看图… 有个裸的半角冒号+空格，YAML 当成嵌套映射，整个 skill 被丢弃。更隐蔽的是识图照样能用（vision-fallback 插件注入的提示自带完整指引，把 skill 的活儿干了），所以"识图测试通过"不能证明 skill 加载成功。
.
├── README.md # 本文件
├── SETUP.md # 安装编排指南（给 agent 看的）
├── CHANGELOG.md # 版本变更
├── verify.ps1 # 安装后自检（需 pwsh）
├── files/ # 要放进目标机 opencode 配置目录的东西
│ ├── opencode.jsonc # ⚠ 模板：含 {{PYTHON_EXE}} / {{CONFIG_DIR}} 占位符
│ ├── AGENTS.md # 全局规则（context7 纪律 + 图片路由）
│ ├── vision_server.py # vision-helper MCP 服务器
│ ├── plugins/
│ │ ├── encoding-fix.js
│ │ └── vision-fallback.js
│ ├── skills/
│ │ ├── vision-routing/
│ │ ├── systematic-debugging/ # 含 5 个附属文件
│ │ ├── verification-before-completion/
│ │ └── dispatching-parallel-agents/
│ └── snippets/
│ └── pwsh-utf8-profile.ps1
└── vendor/
├── PowerShell-7.6.5-win-x64.msi
└── SHA256SUMS.txt
files/ 下的结构与 opencode 配置目录一一对应，除了 snippets/（那是给人抄的片段，不属于 opencode 配置）。verify.ps1 留在包根目录，不复制进配置目录。
本包不含任何密钥，配置里全部以 {env:XXX} 形式引用环境变量。
| 变量 | 用途 | 获取 |
|---|---|---|
AGENTROUTER_API_KEY | AgentRouter 的两个 provider | https://agentrouter.org/register?aff=87Iq |
JUSTWOKER_API_KEY | JustWoker provider + 识图调用 | https://api.justwoker.icu/register?aff=DSYa |
CONTEXT7_API_KEY | context7 MCP | context7 官网 |
上面两个是中转站的注册链接（含推荐参数）。要换成自己的端点，改 opencode.jsonc 里对应 provider 的 baseURL / apiKey 即可。
别把 key 发在对话里。 opencode 会把对话内容（包括交互式提问的自定义答案）明文写进 ~\.local\share\opencode\log\*.log，agent 不回显也拦不住——记录发生在 opencode 层。自己在终端里设置：
[Environment]::SetEnvironmentVariable('AGENTROUTER_API_KEY','<你的key>','User')设完完全退出并重启 opencode（含托盘进程）才生效。
- 识图不是免费的：每次
analyze_image约 6500+ tokens，走的是配置里指定的视觉模型。vision-routingskill 里写了何时该先问用户。 - 识图结果是文字转述，不是像素级视觉。转述与预期不符时，换更具体的 prompt 重试。
skills/systematic-debugging/find-polluter.sh是 bash 脚本，纯 Windows 环境用不了（需要 git-bash/WSL）。其余 skill 内容与平台无关。- 本包不含
package.json（v20260830 曾有）。它当初只声明@opencode-ai/plugin，而两个插件仅用 Node 内置模块、并未 import 它；留着会在启动时触发一次无用的bun install，还可能把目标机已有版本拉回旧版。 - skill 的 YAML frontmatter 很脆：
description里出现裸的半角:、#，或以[/{/*/&开头，都会让 opencode 静默丢弃整个 skill（不报错，只是不出现在列表里）。中文描述尤其容易踩。verify.ps1会检查这一项——新增 skill 后记得跑一次。 - 中转站会变：baseURL、模型 id、可用性、价格都可能变动，
opencode.jsonc里的实测数据有时效性。cost字段故意留空。装之前先拉一次GET <baseURL>/v1/models与配置对一下（SETUP.md 4.5）——上游已下线的 id 留在配置里会变成"选中即报错"的死条目，而且不报配置错误，只在实际对话时失败。本包 2026-09 的一次更新就是因为 JustWoker 下线了claude-opus-4-8系列。 - 额度耗尽 ≠ 配置错误：中转站账户没余额时报
Budget pool quota has been exhausted或Insufficient balance，配置是对的。装好后第一次对话就撞上这个，先去站点确认余额，别怀疑配置。默认模型建议指向余额确认可用的 provider。 files/AGENTS.md会被误当项目规则：如果你在这个包文件夹里开 opencode 会话，opencode 会把files/AGENTS.md当作项目指令加载。这不影响安装，知道即可。vendor/里的 MSI 只有 x64 版。arm64 / x86 请从 https://github.com/PowerShell/PowerShell/releases/tag/v7.6.5 自取。目标机已装 PS7 的话，vendor/整个删掉也行（能省 108 MB）。
两台机器上实际跑通过（不是移植的最低要求，只是"已知能跑"的参照）：
| 项 | 导出机 | 另一台目标机 |
|---|---|---|
| opencode | 桌面版 1.18.25 | 桌面版 1.18.23 |
| PowerShell | 7.6.5 | 7.6.5（由本包的 MSI 装的） |
| Python | 3.13.9 | 3.14.0 |
mcp | 1.27.2 | 2.1.1 |
openai / pillow | 3.5.0 / 12.2.0 | 3.6.0 / 12.2.0 |
| 系统代码页 | ACP/OEMCP = 936（GBK） | 同 |
| git | 2.52.0.windows.1 | 未安装（跳过 core.quotepath，不影响其余） |
配置目录都是 %USERPROFILE%\.config\opencode（未设 XDG_CONFIG_HOME）。
vision_server.py 里的 MCP 版本兼容 import 覆盖了两代 API：mcp 1.x 走 FastMCP 分支（导出机实测），2.x 走 MCPServer 分支（目标机 2.1.1 实测）。所以 mcp 装到哪个大版本都能用。
@opencode-ai/plugin 的版本跟随 opencode 本体（1.4.3 与 1.18.23 都出现过），本包不再声明它——两个插件只用 Node 内置模块。