#架构与运行机制

本章从工程视角说明 OpenCode 如何完成一次任务：配置如何合并、Agent 如何选工具、Plan/Build 如何通过权限分流。

#1. Agent 执行循环

OpenCode 的 TUI 会话是典型的 工具增强型 Agent 循环：

flowchart LR
  A[用户输入] --> B[加载配置 + AGENTS.md]
  B --> C[Primary Agent 推理]
  C --> D{调用工具?}
  D -->|是| E[权限检查 ask/allow/deny]
  E --> F[执行 read/edit/bash/MCP/LSP...]
  F --> G[结果回传模型]
  G --> C
  D -->|否| H[回复用户]
  C --> I{委派 Subagent?}
  I -->|task 工具| J[子会话 Explore/General...]
  J --> G

与纯 Chat 的区别：状态在工具输出与 LSP 诊断中延续，且每次工具调用都过 permission 闸门。

#2. Primary 与 Subagent

#Primary Agent

• 用户通过 Tab 直接切换（Build / Plan）
• 承载主对话线程
• 配置在 opencode.json 的 agent.build、agent.plan 等

#Subagent

• 由 Primary 通过 task 工具自动委派，或用户 @explore 手动调用
• 可创建 子会话（child session），用方向键在父子会话间导航：
  • 进入子会话：默认 Leader+Down
  • 子会话间切换：Right / Left
  • 返回父会话：Up

设计意图： Explore/Scout 只读，避免主线程被大量 glob/grep 输出淹没；General 可并行执行独立子任务。

#3. 配置合并优先级

OpenCode 从多处加载配置并浅层合并（冲突键以后者为准）：

1. Remote config（.well-known/opencode，组织默认）
2. Global ~/.config/opencode/opencode.json
3. OPENCODE_CONFIG 指向的文件
4. 项目根 opencode.json（向上找到 Git 根）
5. .opencode/ 目录（agents、commands、plugins、skills…）
6. OPENCODE_CONFIG_CONTENT 内联 JSON
7. Managed config（企业托管，macOS 等）
8. MDM .mobileconfig（最高优先级，用户不可覆盖）

实践含义：

• 个人偏好放 global
• 团队规范放 项目 opencode.json + AGENTS.md`
• 企业策略走 remote / managed

TUI 外观与快捷键在 tui.json，与 opencode.json 分离。

#4. 权限系统（Permission）

权限是 OpenCode 架构的核心，替代旧版单纯的 tools: true/false。

每个 permission key 映射一组工具：

取值：

• allow — 静默执行
• ask — 弹审批
• deny — 禁用

Plan Agent 默认对 edit、bash 等为 ask 或 deny，从而实现「只说不做」。

支持 bash 命令级规则，例如：

"bash": {
  "*": "ask",
  "git status*": "allow",
  "git diff*": "allow"
}

后匹配规则覆盖先匹配的 * 规则。

#5. 多会话（Multi-session）

OpenCode 可在同一项目并行多个会话，例如：

• 会话 A：Plan 新功能
• 会话 B：Build 修 bug
• 会话 C：Explore 专用查代码

这在长任务互不干扰时很有用。注意并行 Build 会话可能产生 Git 冲突，建议分分支或串行合并。

#6. Headless 模式

适合团队内统一 Agent 网关或 CI 集成。

#7. 隐私模型

OpenCode 宣称 不存储用户代码与上下文（见 官方 FAQ）。实际数据仍流经：

• 你所选的 LLM Provider（云 API）
• 本地 LSP / MCP 进程

在合规场景中应：

• 选用允许离线的本地模型
• 禁用不必要的 websearch
• 审查 MCP Server 权限

#8. 心智模型小结

#下一步

• Agent 与权限系统
• AGENTS.md 与项目初始化
• 配置与 CLI 参考