OpenCode 指导书（中文版）

这是一份把 OpenCode 当作“可控工程工具”来用的手册：先稳定、再安全、最后提效。

推荐阅读路线

1. 01-quickstart.md：30 分钟跑通闭环
2. 02-config-loading.md：解决“配置不生效/被覆盖”
3. 04-models-variants.md：搞定 variants（含 xhigh）与切换验证
4. 07-permissions-baseline.md：团队安全基线（allow/ask/deny）
5. 10-troubleshooting.md：日志/缓存/插件三板斧

目录

• 01 快速上手（30 分钟闭环）
• 02 配置加载与覆盖（排障第一章）
• 03 Providers 与 OpenAI-compatible 接入
• 04 Models 与 Variants（含 xhigh）
• 05 Keybinds（默认键、冲突矩阵、重映射）
• 07 Permissions（安全与权限基线）
• 10 Troubleshooting（日志/缓存/插件三板斧）
• 11 Windows / WSL（官方推荐路径）
• 12 团队落地计划（1 周上线）
• 附录：10 个团队命令模板

最重要的 3 个提醒

• provider 配置入口是顶层 provider；默认模型引用必须是 provider_id/model_id。
• variants 只有在切换到对应 variant 后才生效；Ctrl+T 常与终端冲突，推荐把 variant_cycle 绑定到 <leader>v。
• 任何 API Key/Token 都不要写进仓库或聊天；用 /connect 管理本地凭据。