附录 F · 术语表（Glossary）与常见问题（FAQ）

把散落在全书的术语与高频疑问集中到一处，方便随时查阅。

第一部分：术语表

A

• ACP（Agent Client Protocol）：让 Zed 等外部客户端通过 opencode acp 子进程接入 OpenCode 引擎的开放协议，经 stdio 传输 JSON-RPC。
• AFP：Agent Plan 套餐的额度单位。5 小时窗口是滑动限流，周 / 月是订阅配额。
• AGENTS.md：V2 唯一识别的持久化规则文件（无 CLAUDE.md 回退）。全局位于 ~/.config/opencode/AGENTS.md，项目内各级文件会被合并加载。
• Agent（代理）：带预设指令与姿态的角色。mode 分 primary（可在 TUI 主用）与 subagent（被派出）；内置 build / plan 为 primary，general / explore 为 subagent。

C

• Command（命令）：用 Markdown 定义、以 /名字 触发的预设提示，可带参数与 $ARGUMENTS，shell 内联用反引号。
• Compaction（压缩）：上下文将满时把历史摘要化以腾出空间，<leader>c 可手动触发。
• Context（上下文）：当前会话中提供给模型的全部信息，含对话、附件、规则、打开的文件等。

F

• fork（分叉）：从已有会话复制出一条新分支做试验，不影响原会话；无头模式可用 --fork。

H

• headless（无头 / 非交互）：不开界面、提交即返回的用法，核心命令 opencode run，适合脚本与 CI。

L

• Leader 键：组合快捷键前缀，TUI 中为 Ctrl+X，写作 <leader>。

M

• MCP（Model Context Protocol）：接入外部工具 / 数据源服务器的标准协议。
• Model variant（模型变体）：同一模型的不同配置（如思考强度），Ctrl+T 选择，ID 中以 #variant 表示。

P

• Permissions（权限）：按 Agent 的工具规则，可取 allow / deny / ask，按顺序匹配。
• Plugin（插件）：用 TS/JS 编写、能注册工具与事件钩子的最强扩展，声明于 plugins 或放入 .opencode/plugins/。
• Policies（策略）：组织级、二元（allow/deny）、永不弹窗、只收紧不放宽的硬约束，位于 experimental.policies。
• Prompt（提示）：你发给 AI 的指令，是决定产出质量的第一基本功。
• Provider（供应商）：提供模型的服务方，如 anthropic、openai、opencode 及自定义供应商。

R

• References（引用）：给项目外目录 / Git 仓库起的别名，按需挂载查阅。

S

• Session（会话）：一段连续的工作上下文单元，可继续、分叉、恢复、删除。
• Skill（技能）：按主题组织、可渐进加载的说明性知识扩展。
• steer（引导）：在 AI 工作过程中直接按 Enter 输入新指令来实时纠偏。
• Subagent（子代理）：由主 Agent 派出、独立完成子任务后只汇报结果的 Agent，过程不污染主会话。

T

• Token：模型处理文本的计量单位（约等于词 / 字的片段），上下文长度与用量都按 token 计。
• TUI（Terminal User Interface）：OpenCode 的全屏终端界面。

---

第二部分：常见问题（FAQ）

Q1：OpenCode 收费吗？

OpenCode 本身是开源工具，但它调用的模型由各供应商提供，是否收费、如何计费取决于供应商与你的套餐。使用 Agent Plan / Coding Plan 时有订阅额度（AFP），超出或使用套餐外模型可能按量计费。

Q2：它和 Claude Code 有什么区别？

Claude Code 是 Anthropic 出品、绑定 Anthropic 模型的 CLI；OpenCode 是模型无关的开源 agent 平台，可接入多家供应商、自定义 Agent / Command / Skill / Plugin，并提供 TUI、无头模式、ACP 等多种入口。规则文件也不同：OpenCode V2 用 AGENTS.md。

Q3：为什么我写了 CLAUDE.md 但不生效？

V2 只识别 AGENTS.md，没有 CLAUDE.md 回退。把规则迁移到各级 AGENTS.md 即可（详见第 4 章与附录 E）。

Q4：我该用哪个模型？

难任务（规划、复杂调试、长上下文）用强模型；简单、高频、对延迟敏感的任务用轻量模型。也可使用自动路由（如 auto）由 Harness 按任务挑选。可用 <leader>m 切换，F2 快速循环。

Q5：AI 一直在改，我想中途纠正怎么办？

直接按 Enter 输入新指令（steer）即可实时纠偏；需要立刻停下按 Esc。想排好队等当前动作后再执行，用 Alt+Enter。

Q6：上下文满了会怎样？会丢东西吗？

接近上限时可触发 Compaction（<leader>c）把历史摘要化，保留要点、释放空间。它不是简单截断，但仍建议把长期重要规则写进 AGENTS.md，而非只留在对话里。

Q7：undo 能替代 Git 提交吗？

不能。undo（<leader>u）只覆盖近期、活动目录的快照；一次干净的 Git commit 才是可长期依赖、可推送、可回滚的安全网。任务验证通过后应及时提交。

Q8：在 CI 里怎么用？会卡住等确认吗？

用 opencode run --auto --format json：--auto 自动批准未被显式 deny 的权限，--format json 输出结构化结果；凭证通过环境变量注入。危险操作仍可用 Policies / deny 硬拦。

Q9：子代理（subagent）怎么用？为什么 Shift+Tab 切不到它？

Shift+Tab 只在 primary Agent 间循环。subagent（如 explore）应由主 Agent 在对话中「派出」，它独立调查后只汇报结果，避免污染主会话。

Q10：插件放进项目根的 plugins/ 目录为什么没反应？

项目根的 plugins/（不在 .opencode/ 下）不会被自动发现。要么在 plugins 配置数组中显式声明，要么把它挪到 .opencode/plugins/。

Q11：怎么把我的配置同步到另一台机器？

用 Git 管理 ~/.config/opencode/（见附录 G 的 dotfiles 方案），换机克隆并建立软链 / 拉取即可。注意不要提交含密钥的敏感文件。

Q12：教程对应哪个版本？以后功能变了怎么办？

以 README 顶部的「适用版本 + 最后校对日期」为准。OpenCode 迭代很快，遇到与教程不符之处，以官方 V2 文档（https://opencode.ai/v2/docs/）与 https://opencode.ai/config.json 模式为最终依据。