安装器进阶与选项

了解安装器命令、options.jsonc 配置开关、rtk 压缩原理以及重装保留字段规则。

安装命令一览

模式	PowerShell	Bash	说明
安装（默认）	`pwsh install/install.ps1`	`./install/install.sh`	将当前清单应用到目标目录
强制重装	`pwsh install/install.ps1 install -Force`	`./install/install.sh install -f`	重新应用相同版本
查看状态	`pwsh install/install.ps1 status`	`./install/install.sh status`	显示已安装版本与仓库版本
初始化（全新开始）	`pwsh install/install.ps1 init`	`./install/install.sh init`	备份并清空整个目标目录
注册全局命令	`pwsh install/install.ps1 register`	`./install/install.sh register`	将 `opencode-prime` 与 `ocp` shim 安装到 `~/.local/bin`
注销全局命令	`pwsh install/install.ps1 unregister`	`./install/install.sh unregister`	移除全局 shims
启动 TUI	`pwsh install/install.ps1 tui`	`./install/install.sh tui`	启动 OpenCode 终端界面（`exec opencode`）
启动桌面端	`pwsh install/install.ps1 desktop`	`./install/install.sh desktop`	启动 OpenChamber 原生桌面应用（别名 `ui`）
启动 Web 界面	`pwsh install/install.ps1 web`	`./install/install.sh web`	启动 OpenChamber Web 界面（`openchamber --ui-password <自动生成>`）

安装选项（`options.jsonc`）

install/options.jsonc 是控制安装配置的单一事实来源（开关 MCP、外部插件、主控智能体与 rtk 压缩代理）。

安装前自定义流程

进入仓库目录（若使用 Git 克隆或解压了 release 包）：
bash
```
cd opencode-prime
```

编辑 install/options.jsonc 设定所需的可选功能开关：

jsonc

  // install/options.jsonc
{
  // 安装时将全局命令 shim（ocp / opencode-prime）注册到
  // ~/.local/bin，并把该目录追加进用户 PATH
  "global_commands": true,
  // 可选外部二进制，声明于 install/tools.jsonc
  "tools": {
    // 是否启用 rtk 输出压缩（60-90% token 节省）
     "rtk": true,
     // 可选外部全文检索缓存（microsoft/tgrep），缺失时由安装器自动拉取预编译包。
     // 它不是 MCP、LSP 或代码图谱；.tgrep/ 不可提交。
      "tgrep": { "enabled": true, "requestLog": false },
    // OpenChamber 拆分为三个独立面，各自一个开关：
     // 网页版 CLI（缺失时自动安装 @openchamber/web@2；提供 `ocp web`，需 Node.js 22+）
     // 锁定大版本 2：v2 内的修复照常更新，未来的 v3 不会被静默装上
     // 默认关闭：启用后会安装全局包。
     "openchamber_web": false,
    // `ocp desktop` / `ocp ui` 的原生桌面应用——始终需另行下载
    // （https://openchamber.dev/download）；安装时仅检测是否已安装
    "openchamber_desktop": true,
    // `ocp code` 的 VS Code 扩展（缺失时通过编辑器 CLI 自动安装
     // fedaykindev.openchamber）。默认关闭：启用后会修改编辑器。
     "openchamber_vscode": false,
     // 终端工作区管理器；所选 tui_mode 对应的工具会自动视为 true。
     "herdr": false,
     "luvus": false
  },
  // 默认主控智能体（lite: 默认精益日常驱动 / code: 直接开发 / build: 编排派发 / plan: 只读分析）
  "default_agent": "lite",
  // MCP 服务开关（启用且本地缺失 CLI 时自动拉取安装）
  "mcp": {
    // Serena LSP 语义代码检索与符号分析（需 uv / Python 3.13+；默认关闭，
    // 23 个工具约 7.7k tok/步；需要时手动开启）
    "serena": false,
    // CodeGraph AST 代码知识图谱（需 npm）
    "codegraph": true,
    // GitNexus 代码图谱（PolyForm 非商用许可；需自行索引）
    "gitnexus": false,
    // DBHub 通用数据库网关（PostgreSQL / MySQL / SQLite 等；需 npm）
    "dbhub": true,
    // Headroom 上下文压缩（Apache 2.0；安装较重 —— uv + Python 3.13，
    // 首次运行下载 ONNX 运行时 + Kompress 模型；详见 core/mcp-servers）
    "headroom": false,
    // JetBrains IDE 桥接（需先在 IDE 中启用 MCP 服务器：Settings → Tools → MCP Server）
    "idea": true
  },
   // 外部 npm 插件开关（true: 启用; false: 关闭）
   "plugin": {
     // Qoder 订阅桥接（通过官方 SDK 注入 qoder 服务商及模型，需 qoder login）
     "opencode-qoder-bridge": false,
     // 持久化项目记忆库（向量存储，空闲时产生额外 LLM 提炼调用）
     "opencode-mem@2.24.3": false
   }
}

执行安装命令：

bash

# macOS / Linux / WSL
./install/install.sh

# Windows (PowerShell)
pwsh install/install.ps1

安装后修改与生效

安装器在每次运行时都会严格按照仓库中 install/options.jsonc 的开关状态重新计算并应用到目标 opencode.jsonc。若后续需要开启或关闭某项功能：

修改 install/options.jsonc 中的对应字段（true / false）。
在版本号未变的情况下，带 -Force（PowerShell）或 -f（Bash）重新运行安装即可生效：
powershell
```
pwsh install/install.ps1 install -Force
```
bash
```
./install/install.sh install -f
```

可选 tgrep 全文检索索引

tools.tgrep 默认启用。启用时若系统尚未安装外部 tgrep CLI，OCP 安装器会自动拉取官方发布的预编译包（同 rtk 机制）；若已自行安装在 PATH 上则直接复用。CLI 就位后,/project init 创建首次本地 .tgrep/ 索引;/project index 只重建已有但不健康的索引。健康的 tgrep serve . watcher 负责日常增量更新。将 tools.tgrep 设为 false 可完全退出。

索引检索适合重复、宽泛的文本或正则查询。刚保存后、验证修改时，或要断言没有匹配时，须使用 current/full scan（tgrep --no-index 或 rg），因为 watcher 更新是异步的。保持默认 64 MiB 文件大小策略以及 index/serve/search 参数一致。tgrep 不替代 Serena 符号导航或 CodeGraph/GitNexus 关系查询。

若磁盘上的索引是在不同策略（indexPath、maxFileSize、exclude、noRequireGit）或不同 tgrep 版本下构建的，OCP 会将其报告为 stale：索引检索回退到 full scan，直到 /project index 重建完成，结果因此不会违反已配置的策略。tgrep_search 工具除 -i/-F 标志外还接受 gitignore 风格的 glob 过滤器。

开发请求日志

如需临时查看开发请求，请在 ~/.config/opencode/options.jsonc 中将 tools.tgrep.requestLog 设为 true。OCP 会在工具 schema 校验后向 <project>/.ocp/logs/tgrep.jsonl 写入 JSONL 记录。记录包含规范化请求字段、选定模式、后端与结果总数，绝不包含匹配内容。默认值是 false，且生产环境必须保持禁用，因为它会记录请求的模式。

验证与基准测试（显式启用）

常规 OCP 测试不会下载二进制。自行安装固定版本 tgrep 后，可运行 OCP_TGREP_BIN=tgrep bun run tests/test-tgrep-integration.ts（PowerShell： $env:OCP_TGREP_BIN = "tgrep"）验证真实 CLI 契约。通过 bun run scripts/benchmark-tgrep.ts <repo> <literal> 在本地测量仓库；在宣传性能收益前，应保留 JSON 输出、tgrep 版本与仓库 revision。

外部 npm 插件

install/options.jsonc 的 plugin 块控制 opencode.jsonc 中 plugins 数组的成员资格：开关置 true 即把对应包名作为插件条目注入，置 false 则移除。安装器自身不执行任何包下载——v2 运行时会在服务启动时立即加载已缓存的包插件，并在后台安装缺失的包（见 OpenCode 插件指南），因此启用某插件后的首次启动可能要等后台安装完成才会看到它。

零配置目录污染：包插件不会向 ~/.config/opencode 写入任何内容，其安装完全由运行时托管。
离线容忍：断网时条目留在配置里，OpenCode 在后续启动时自动拉取。开/关只需翻转开关并重跑安装器。

Token 节省（rtk）

安装时自动配置 rtk —— 一个在命令输出（git status、测试、构建等）到达模型前将其压缩 60-90% 的 CLI 代理。

若 PATH 中没有 rtk，安装器会将固定版本的二进制下载到 ~/.local/bin。opencode 插件以内置的 plugins/rtk-write/ 目录形式随配置分发（v1 的根入口文件 plugins/rtk-write.ts 已不再发布；升级时残留的旧文件会被清单清理机制移除）。

若不需要：在 install/options.jsonc 中设 "rtk": false 后重新安装即可。

防止模型陷入重写循环

压缩是有损的：当模型需要被省略的数据时，可能反复重跑同一条命令却始终拿不到完整输出。钩子因此做了柔性降级：

省略感知熔断 —— 一旦某条命令的输出被省略（RTK 的 [see remaining: ...] 标记），该命令在本会话后续运行中原样放行。这是最精准的循环信号，同时保留了对"因编辑后复查等正常原因重复"的命令的压缩。
重复次数兜底 —— 针对有损但无标记的输出：同一条命令运行满 loopThreshold 次后（默认 3）也原样放行。
逃生舱 —— 命令加 RTK_RAW=1 前缀即可完全绕过重写，例如 RTK_RAW=1 git status。
恢复提示 —— 当 RTK 省略了输出时，钩子会追加一行提示，给出可直接复制的重跑命令。

可在 ~/.config/opencode/options.jsonc 的 tools.rtkWrite 中调整（所有键可选，下列为默认值）：

jsonc

"tools": {
  "rtkWrite": {
    "enabled": true,          // 总开关（默认 true）
    "loopThreshold": 3,       // 同命令第 N 次直通原始输出（0 = 从不熔断）
    "blocklist": ["git diff"] // 永不重写的命令前缀
  }
}

工作区包装 TUI（`ocp tui`）

安装向导可选择 ocp tui 背后的工作区集成：Herdr 或 Luvus。裸 ocp 始终在当前 shell 中直接启动 OpenCode。

模式	集成	OCP 的配置行为
`"herdr"`	Herdr	建立以当前目录为根的工作区；OCP 会配置 Herdr、其 OpenCode 集成与内置自动启动插件。
`"luvus"`	Luvus	建立以当前目录为根的工作区；OCP 运行 Luvus 官方安装器，配置其 OpenCode 会话集成，并链接内置自动启动模块（新标签页/窗格自动开启 opencode）；启动时若模块未生效则回退为显式启动一个 OpenCode agent。
`"direct"` （默认）	无	在当前 shell 中直接运行 OpenCode。

可在向导中选择默认值，也可手动设置：

jsonc

// install/options.jsonc
"tui_mode": "luvus"   // "direct"（默认） | "herdr" | "luvus"

选择工作区模式会自动启用匹配的 tools 项，即使它显式设为 false。单次覆盖可使用 ocp tui --direct、ocp tui --herdr 或 ocp tui --luvus。

OpenChamber（`ocp desktop` / `ocp web` / `ocp code`）

安装时可供应 OpenChamber —— 运行在本地 OpenCode 引擎之上的图形界面层（双栏 Diff 审查、多模型对比、会话时间线）。它拆分为三个独立面，各自对应一个 tools.openchamber_* 开关；Web 与 VS Code 默认按需启用：

开关	表面	安装时的行为
`tools.openchamber_web`	网页版 —— `@openchamber/web@2` CLI，提供 `ocp web`	默认：false。启用后，本地缺少 `openchamber` 命令时通过检测到的第一个包管理器（pnpm > bun > yarn > npm）全局安装（需 Node.js 22+）。大版本锁定为 2（semver 范围 `@2`），`ocp update` 只在 v2 内升级——v3 发布时按跨大版本规则拒绝
`tools.openchamber_desktop`	桌面版 —— 提供 `ocp desktop` / `ocp ui` 的原生应用	仅检测是否已安装，缺失时打印下载链接——安装器从不下载桌面应用（openchamber.dev/download）
`tools.openchamber_vscode`	VS Code 扩展 —— 提供 `ocp code`	默认：false。启用后，本地缺少扩展时通过检测到的第一个编辑器 CLI（`code`、`code-insiders`、`codium`、`cursor`、`windsurf`）安装 `fedaykindev.openchamber`

安装完成后即可启动：

bash

ocp desktop      # 原生桌面应用（别名：ocp ui）
ocp web          # OpenChamber Web 界面（自动生成 --ui-password）
ocp code         # 打开 VS Code 并保证 OpenChamber 扩展就绪
ocp tui          # OpenCode 终端界面

若需要 Web 或 VS Code：在 install/options.jsonc 中把对应开关设为 true 后重新安装即可。任何面设为 false 都会跳过（已安装的组件不受影响）；被关闭的面同样会被 ocp code 的自动安装跳过。

重装时保留的字段

当 opencode.jsonc 被新模板覆盖时，以下字段会从你的现有配置中快照并在覆盖后恢复：

字段	保留原因
`provider.<name>.options.baseURL`	你的 API 端点
`provider.<name>.options.apiKey`	你的 API 密钥
`provider.<name>.models`	你的模型定义（自定义 model id、用户自加的模型）
`model`（根级别）	你为 standard 层级选择的模型
`agent.<name>.model`（每个层级）	你为各层级分配的模型

全局命令 (`ocp` / `opencode-prime`)

首次安装后，可将仓库注册为全局快捷命令（ocp、opencode-prime）：

powershell

pwsh install/install.ps1 register

bash

./install/install.sh register

注册完成后，ocp 同时也是运行时启动器：ocp（或 ocp tui）启动 OpenCode 终端界面，ocp desktop（别名 ocp ui）启动 OpenChamber 原生桌面应用，ocp web 则在 localhost 上提供带自动生成 --ui-password 的 OpenChamber Web 界面。

若不想在安装时自动注册 shim，可在 install/options.jsonc 中设置 "global_commands": false —— 上方的 register / unregister 独立操作仍然随时可用。

👉 完整命令清单与启动器语义（ocp web 的端口与密码策略）见独立章节 OCP 命令行参考。

安装器进阶与选项 ​

安装命令一览 ​

安装选项（options.jsonc） ​

安装前自定义流程 ​

安装后修改与生效 ​

可选 tgrep 全文检索索引 ​

开发请求日志 ​

验证与基准测试（显式启用） ​

外部 npm 插件 ​

Token 节省（rtk） ​

防止模型陷入重写循环 ​

工作区包装 TUI（ocp tui） ​

OpenChamber（ocp desktop / ocp web / ocp code） ​

重装时保留的字段 ​

全局命令 (ocp / opencode-prime) ​

安装器进阶与选项

安装命令一览

安装选项（`options.jsonc`）

安装前自定义流程

安装后修改与生效

可选 tgrep 全文检索索引

开发请求日志

验证与基准测试（显式启用）

外部 npm 插件

Token 节省（rtk）

防止模型陷入重写循环

工作区包装 TUI（`ocp tui`）

OpenChamber（`ocp desktop` / `ocp web` / `ocp code`）

重装时保留的字段

全局命令 (`ocp` / `opencode-prime`)