OpenCode 开源编码代理：安装通道、目录优先级与 build / plan / general Agent 体系详解

本文基于 OpenCode 仓库根目录的丹麦语版 README（README.da.md）及其对应的真实实现展开，覆盖三条主线：OpenCode 的完整安装通道（一键脚本与各包管理器）、安装脚本的目录优先级与 PATH 处理逻辑、以及内置 build / plan 双 Agent 加 general 子代理的权限模型。读完后你可以独立完成安装与升级、理解二进制落盘位置，并能从源码层面解释每个 Agent 的权限边界。

1. OpenCode 是什么

OpenCode 自称 “The open source AI-kodeagent”（开源 AI 编码代理）。它的主入口是一个终端 TUI：在项目目录中运行 opencode 命令即可进入交互式编码会话；同时项目提供了一个处于 BETA 阶段的桌面应用。本仓库是多包 monorepo，核心实现位于 packages/opencode 包中，本文涉及的关键证据包括：

• 安装脚本：install（仓库根目录的 bash 脚本）
• Agent 定义：packages/opencode/src/agent/agent.ts
• Agent 行为测试：packages/opencode/test/agent/agent.test.ts
• 卸载命令：packages/opencode/src/cli/cmd/uninstall.ts

2. 安装方式

README 提供了“YOLO”式一键安装与各包管理器安装两大类通道，以下完整继承原文档内容。

2.1 一键安装脚本

# YOLO
curl -fsSL https://opencode.ai/install | bash

仓库根目录的 install 脚本即该类安装器的参考实现。从脚本的 usage() 帮助文本（install#L10-L27）可以看到它实际支持的参数：

参数	说明
-h, --help	显示帮助信息
-v, --version <version>	安装指定版本（例如 1.0.180）
-b, --binary <path>	从本地二进制安装，跳过所有下载与检测逻辑
--no-modify-path	不修改 shell 配置文件（.zshrc、.bashrc 等）

对应的调用形态为：

curl -fsSL https://opencode.ai/install | bash -s -- --version 1.0.180
./install --binary /path/to/opencode

脚本内部还有几个值得注意的健壮性设计（均为源码可确认事实）：

• 平台矩阵：仅接受 linux-x64、linux-arm64、darwin-x64、darwin-arm64、windows-x64 五种组合，其余直接报错退出（install#L103-L110）。
• Rosetta 检测：在 Intel 转译运行的 macOS（sysctl.proc_translated = 1）上会自动改用 arm64 二进制。
• AVX2 baseline 检测：x64 平台上若 CPU 不支持 AVX2（Linux 查 /proc/cpuinfo、macOS 查 hw.optional.avx2_0、Windows 通过 PowerShell 调 IsProcessorFeaturePresent(40)），下载目标会自动追加 -baseline 后缀。
• musl 检测：Alpine 或 ldd --version 输出含 musl 的 Linux 会下载 -musl 变体。
• 版本校验：check_version() 会先执行已安装的 opencode --version，若目标版本已安装则直接退出（install#L221-L235）；指定版本时还会先对 release 做 HEAD 请求，404 则报 “Release vX not found”。
• PATH 自动写入：脚本按当前 shell（fish / zsh / bash / ash / sh）选择对应配置文件追加 PATH 语句，已有相同内容则跳过；在 GitHub Actions 环境中会额外写入 $GITHUB_PATH（install#L362-L444）。

2.2 包管理器安装

npm i -g opencode-ai@latest        # 或用 bun/pnpm/yarn
scoop install opencode             # Windows
choco install opencode             # Windows
brew install anomalyco/tap/opencode # macOS 与 Linux（推荐，始终最新）
brew install opencode              # macOS 与 Linux（官方 brew formula，更新频率较低）
sudo pacman -S opencode            # Arch Linux (Stable)
paru -S opencode-bin               # Arch Linux (AUR 最新版)
mise use -g opencode               # 所有操作系统
nix run nixpkgs#opencode           # 或 github:anomalyco/opencode 获取最新 dev 分支

提示（原文档 TIP）：安装前先移除 0.1.x 之前的旧版本。仓库中的卸载命令 packages/opencode/src/cli/cmd/uninstall.ts 会清理 .opencode/bin 相关的 PATH 配置行（包括 bash 的 export PATH=、fish 的 fish_add_path 以及 # opencode 标记注释），可作为移除旧安装的参考实现。

2.3 桌面应用（BETA）

OpenCode 也以桌面应用形式发布，可从 releases 页或官网下载页获取。各平台安装包命名如下（原文档表格）：

平台	下载文件
macOS (Apple Silicon)	opencode-desktop-mac-arm64.dmg
macOS (Intel)	opencode-desktop-mac-x64.dmg
Windows	opencode-desktop-windows-x64.exe
Linux	.deb、.rpm 或 AppImage

包管理器渠道：

# macOS (Homebrew)
brew install --cask opencode-desktop
# Windows (Scoop)
scoop bucket add extras; scoop install extras/opencode-desktop

桌面端源码位于 packages/desktop，其主进程在 WSL 场景下还会探测 $HOME/.opencode/bin/opencode 这一典型安装路径（见 packages/desktop/src/main/wsl/runtime.ts），与下文安装目录的默认 fallback 相互印证。

3. 安装目录的优先级

README 指出安装脚本按以下顺序确定安装路径：

1. $OPENCODE_INSTALL_DIR —— 自定义安装目录
2. $XDG_BIN_DIR —— 遵循 XDG Base Directory Specification 的目录
3. $HOME/bin —— 标准用户 bin 目录（若存在或可创建）
4. $HOME/.opencode/bin —— 默认 fallback

配合环境变量的用法示例（原文档）：

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

需要说明的证据边界：仓库根目录的 install 脚本当前将安装目录硬编码为 $HOME/.opencode/bin（INSTALL_DIR=$HOME/.opencode/bin 并 mkdir -p）。因此上述四级优先级描述的是官方 https://opencode.ai/install 托管安装器的行为约定，而本仓库脚本可确认的是默认落盘位置、PATH 写入逻辑与 GITHUB_PATH 处理。若你在 CI 或受限环境中安装，以 $HOME/.opencode/bin 作为二进制落盘位置做后续引用（如桌面端 WSL 探测逻辑）是最稳妥的假设。

4. Agent 体系：build、plan 与 general

README 描述了 OpenCode 的两个内置 Agent——可在会话中用 Tab 键切换——以及一个内部子代理：

• build —— 默认 Agent，拥有完整的开发工作权限
• plan —— 只读 Agent，用于分析与代码探索
  • 默认拒绝文件编辑
  • 执行 bash 命令前会请求许可
  • 适合探索陌生代码库或规划改动
• general —— 面向复杂搜索与多步任务的子代理，内部使用，可通过在消息中 @general 调用

这段描述与源码高度吻合。三个原生 Agent 在 packages/opencode/src/agent/agent.ts 中以 mode: "primary"（build、plan）和 mode: "subagent"（general）的方式注册，其权限由 Permission.merge 分层合并：

4.1 build：默认 Agent

build 在默认权限之上放开了两个动作（agent.ts#L141-L155）：

• question: "allow" —— 允许 Agent 主动向用户提问
• plan_enter: "allow" —— 允许进入 plan 模式

默认权限基线（agent.ts#L119-L136）本身已包含若干安全约束：doom_loop: "ask"、外部目录写入 ask、读取 *.env / *.env.* 需要确认（*.env.example 除外）、question 默认 deny、plan_enter / plan_exit 默认 deny。build 之所以“全权限”，是相对这些收紧项的放开，而非无任何约束。用户配置（cfg.permission）始终通过 Permission.merge 叠加在最上层，可覆盖上述默认值。

4.2 plan：写保护 Agent

plan Agent 的权限覆盖（agent.ts#L156-L181）精确对应 README 的“拒绝文件编辑”描述：

• edit: { "*": "deny" } —— 拒绝一切编辑；
• 但允许写两个“计划文件”例外路径：.opencode/plans/*.md 与全局数据目录下的 plans/*.md，即 plan 模式可以落盘规划文档，只是不能改代码；
• task: { general: "deny" } —— plan 模式下默认禁止调用 general 子代理；
• plan_exit: "allow" —— 允许退出 plan 模式返回 build。

测试用例直接验证了这些行为：packages/opencode/test/agent/agent.test.ts 断言 “plan agent denies the general subagent by default”（Permission.evaluate("task", "general", plan.permission) 返回 deny），并在特定规则集下返回 allow。

4.3 general：多步子代理

general 的定义（agent.ts#L182-L195）描述为 “General-purpose agent for researching complex questions and executing multi-step tasks”，其唯一额外收紧项是 todowrite: "deny"（子代理不写 TODO 清单）。从源码结构看，CLI 的 run 命令在执行子任务时默认 subagent_type 即 general（见 packages/opencode/src/cli/cmd/run/tool.ts），这与 README “通过 @general 在消息中调用” 的说明一致。此外源码中还存在一个未在 README 展开的 explore 只读搜索子代理（agent.ts#L196-L218），其权限仅开放 grep / glob / list / read / web 检索等只读工具，可作为 plan 模式探索场景的补充参考。

5. 贡献与衍生项目命名约定

README 最后给出两条社区规范：

• 贡献：提交 pull request 前应先阅读 CONTRIBUTING.md。
• 衍生项目声明：如果你的项目名包含 “opencode”（例如 “opencode-dashboard”、“opencode-mobile”），但并非 OpenCode 团队开发，应在你的 README 中明确注明该项目与 OpenCode 团队无隶属关系。

6. 延伸阅读路径

主题	仓库路径
安装脚本（含参数、平台检测、PATH 写入）	install
Agent 注册与权限合并	packages/opencode/src/agent/agent.ts
Agent 权限测试	packages/opencode/test/agent/agent.test.ts
卸载 / PATH 清理	packages/opencode/src/cli/cmd/uninstall.ts
桌面端（BETA，含 WSL 集成）	packages/desktop
贡献规范	CONTRIBUTING.md
多语言 README 索引	README.md