当前位置： 首页 > news >正文

opencode 调试环境搭建手记：从 bun install 到 VSCode 断点

news 2026/7/15 9:42:25

🔭 如果让你接手一个 29 个 packages 的 monorepo，你会怎么开始读它的源码？

一个直觉是直接看文档——但文档只能告诉你"做了什么"，不能告诉你"怎么跑的"。

另一个直觉是从入口文件开始一行行看——但你很快会发现，TypeScript 带 Effect-ts 的代码比普通 Node.js 项目复杂得多，没有调试器根本跟不动。

opencode 的作者留了一把钥匙：.vscode/launch.example.json。一个文件，三行配置，就能让你从源码跑起来，在任何文件设断点，跟着执行流走完整个 Agent 循环。

这篇文章就是这把钥匙的使用说明书。

【问题】为什么要从源码跑起来？

直接跑 binary 不行吗？

opencode 发布到 npm 的二进制版本是编译后的——你用 npx opencode 启动的是一个打包好的可执行文件。它工作得很好，但当你想要理解它的运行时行为时：

❌ console.log 加不了 — 二进制无法修改
❌ 断点打不了 — 没有源码映射
❌ 变量看不了 — 不知道中间状态
❌ 调用栈跟不了 — 不知道谁调了谁

源码调试解决什么？

源码调试给你三样二进制版本给不了的东西：

  1. 断点可控 — 在任何 .ts 文件任意一行按 F9，执行到那里自动停
  2. 变量可见 — 悬停看值，Watch 窗口跟踪表达式，不需要猜
  3. 调用链可跟 — 看 Call Stack 知道从哪来到哪去，理解代码路径

本文目标

读完本文，你将能：

  • 从 GitHub clone opencode 并 bun install 跑起来
  • 配置 VSCode 调试器，F5 启动带断点
  • 找到项目入口 index.ts，理解 CLI 的 23 个子命令注册
  • 选择适合你的调试方式：F5 / bun --inspect / console.log

【设计】调试环境的四要素

搭建 opencode 的调试环境，需要理解四个要素的选择：

要素 选型 为什么
包管理器 Bun 1.3.x monorepo workspace + catalog 原生支持，替代 npm/pnpm
运行时 Bun (Node.js 兼容) dev 脚本用了 --conditions=browser flag
IDE VSCode launch.example.json 预设了 attach 配置
入口 packages/opencode/src/index.ts dev 脚本的 CWD 是 packages/opencode

依赖安装

先把代码拉下来装依赖：

bun install 输出

关键数据确认：

  • 709 个依赖包安装完成，耗时约 11 秒
  • 29 个 workspace packages 全部用 workspace:* 协议链接
  • Bun 1.3.14 是项目要求的版本（package.json 中 packageManager: "bun@1.3.14"）

启动命令

装完依赖就能跑：

bun run dev

这条命令实际执行的是（来自 packages/opencode/package.json）：

"dev": "bun run --conditions=browser ./src/index.ts"

bun run dev 启动输出

--conditions=browser 是 Bun 的 exports conditions 特性——它让 TypeScript 在解析 package.json 的 exports 字段时走 browser 条件分支。这在 opencode 的很多跨平台模块中用到，比如 #db 导入：

"imports": {"#db": {"bun": "./src/storage/db.bun.ts","node": "./src/storage/db.node.ts","default": "./src/storage/db.bun.ts"}
}

调试架构

VSCode 调试 opencode 的架构是这样的：

调试架构：VSCode → Bun Inspector → opencode

流程很清晰：

  1. VSCode 通过 Bun Debug Extension 连接 Bun Runtime 的 WebSocket Inspector
  2. Bun Runtime 监听在 ws://localhost:6499/
  3. opencode 进程跑在 Bun Runtime 之上，任何 .ts 文件都可断点

【源码】从 bun run dev 到 index.ts 到断点

第一步：配 VSCode launch.json

opencode 源码里已经给了示例配置：

cp .vscode/launch.example.json .vscode/launch.json

这是最终的 launch.json：

VSCode launch.json 调试配置

两个配置：

配置名 方式 用途
opencode (attach) attach 先 bun --inspect 启动，再 F5 attach
opencode (launch) launch F5 直接启动，自动带 inspector

推荐用 launch 方式——F5 一键启动，不需要手动敲命令。

第二步：找到入口

CLI 的真正入口是 packages/opencode/src/index.ts：

index.ts CLI 入口

文件路径： sources/opencode/packages/opencode/src/index.ts — 第 1–46 行

关键结构（摘录自 packages/opencode/src/index.ts 第 33–135 行）：

const args = hideBin(process.argv)                          // 33const cli = yargs(args)                                     // 45.parserConfiguration({ "populate--": true }).scriptName("opencode").wrap(100).help("help", "show help").version("version", "show version number", InstallationVersion).option("print-logs", {                                   // 53describe: "print logs to stderr", type: "boolean",}).option("pure", {                                         // 62describe: "run without external plugins", type: "boolean",}).middleware(async (opts) => {                              // 66if (opts.printLogs) process.env.OPENCODE_PRINT_LOGS = "1"if (opts.pure) process.env.OPENCODE_PURE = "1"Heap.start()process.env.AGENT = "1"process.env.OPENCODE = "1"process.env.OPENCODE_PID = String(process.pid)}).usage("")                                                // 79.completion("completion", "generate shell completion script")  // 80.command(AcpCommand)                                      // 81.command(McpCommand).command(TuiThreadCommand).command(AttachCommand).command(RunCommand)// ... (23 个子命令，见完整源码).command(DbCommand)                                       // 103.fail((msg, err) => {                                     // 104if (msg?.startsWith("Unknown argument") /* ... */) {cli.showHelp(show)}if (err) throw errprocess.exit(1)}).strict()                                                 // 116try {                                                       // 118if (args.includes("-h") || args.includes("--help")) {await cli.parse(args, (err, _argv, out) => {if (!out) return; show(out)})} else {await cli.parse()}
} catch (e) {                                               // 128const formatted = FormatError(e)if (formatted) UI.error(formatted)process.exitCode = 1
} finally { process.exit() }                                // 136

入口做的事很清楚：

  1. hideBin(process.argv) — 去掉 bun run 自身参数，拿到 [ "run", "--model", "..." ]
  2. .middleware() — 在命令执行前设环境变量：AGENT=1、OPENCODE=1、启动 Heap 监控
  3. .command(XxxCommand) — 注册 23个子命令，每个 XxxCommand 是一个 yargs.CommandModule
  4. await cli.parse() — yargs 自动匹配命令并执行

第三步：设断点

这是最关键的一步——调试器不是为了"看代码高亮"，而是为了在特定执行点停下来观察状态。

以 run 命令为例——这是 opencode 最核心的命令，启动 Agent 循环。断点设在哪？

推荐的第一个断点：packages/opencode/src/cli/cmd/run/runtime.ts

这个文件包含 runInteractiveRuntime() 函数——整个 Agent 的主循环就在这里。

断点设置步骤：

  1. 打开 packages/opencode/src/index.ts
  2. 在 await cli.parse() 这一行按 F9（设断点）
  3. 按 F5（选择 opencode (launch) 配置）
  4. CLI 启动后会停在 await cli.parse()，然后按 F8（Step Into）跟进 yargs 内部
  5. 或者更直接：直接在 runtime.ts 的 runInteractiveRuntime() 函数第一行设断点

查看 package.json 的 scripts

确认一下 dev 脚本的完整配置：

packages/opencode/package.json scripts

文件路径： sources/opencode/packages/opencode/package.json — 第 4–17 行

总共 8 个 scripts，开发最常用的是 dev 和 build：

命令 实际执行的代码 用途
dev bun run --conditions=browser ./src/index.ts 源码模式启动 CLI
build bun run script/build.ts 编译打包为二进制
test bun test --timeout 30000 --only-failures 运行失败用例
typecheck tsgo --noEmit 类型检查

【权衡】VSCode debug vs bun --inspect vs console.log

三种调试方式各有适用场景：

三种调试方式对比

方式一：VSCode F5 Launch（推荐用于源码阅读）

# 一键启动调试 —— 在 VSCode 里按 F5，选择 "opencode (launch)"

VSCode 自动启动 Bun Inspector 模式，所有 .ts 文件可断点。

优点：

  • 断点可控，想停哪停哪
  • Variable 窗口查看运行时状态
  • Call Stack 跟踪调用链
  • Debug Console 执行表达式

缺点：

  • 需要一次 launch.json 配置
  • 启动略慢（Bun 要编译 TypeScript）

方式二：bun --inspect（适合快速排查）

bun --inspect run --conditions=browser ./src/index.ts run

然后在 Chrome 打开 chrome://inspect，找到 opencode 进程，点击 inspect。

优点：

  • 不需要 VSCode，任何编辑器可用
  • Chrome DevTools 的调试体验很成熟
  • 适合 Server 端排查

缺点：

  • 每次要手动打开浏览器连 WebSocket
  • 不如 VSCode 的变量监视方便

方式三：console.log（不推荐用于源码学习）

console.log(">>> 到这儿了", variable)

优点： 零配置，任何环境都能用。

缺点：

  • 改源码有 PR 残留风险
  • 看不到调用栈
  • 看不到变量当前状态
  • 每次改了要重新启动

选型建议

场景 推荐方式
通读源码，理解架构 VSCode F5 Launch
查一个特定的 bug bun --inspect + Chrome
快速验证一个小改动 console.log（记得删）
远程服务器排查 bun --inspect + 端口转发

【锚点】

调试环境搭好，源码就变成你的游乐场了。

本篇总结

知识点 一句话
怎么从源码跑起来？ bun install → bun run dev
怎么配 VSCode 调试？ cp launch.example.json launch.json → F5
入口在哪？ packages/opencode/src/index.ts → yargs CLI
第一个断点放哪？ runtime.ts 的 runInteractiveRuntime()
调试方式怎么选？ F5 读源码，--inspect 查 bug，console.log 速验

实操清单

# 1. 前置检查
bash demo/setup-check.sh# 2. 装依赖
cd sources/opencode && bun install# 3. 配调试
cp .vscode/launch.example.json .vscode/launch.json# 4. VSCode 打开项目
code sources/opencode# 5. 在 index.ts 第 118 行设断点（await cli.parse()）
# 6. F5 → 选择 "opencode (launch)" → 开始调试

下篇预告

下篇文章讲 Effect-ts 预备课——不学 Effect-ts 语法，而是理解为什么 opencode 选择它作为编程基石，以及你看源码时最需要知道的 3 个 Effect-ts 模式。

篇目 核心主题
1.2 (本文) 调试环境搭建
1.3 Effect-ts 预备课
2.1 yargs CLI 构建
http://www.jsqmd.com/news/1192841/

相关文章：

  • ngx-ui对话框与抽屉组件：打造现代化模态交互体验的终极指南
  • 自身免疫“风暴眼“——GM-CSF/IFN-γ/IFN-α/IL-12/IL-17/IL-23/IL-6七联Panel锁定Th17/Treg失衡的分子推手
  • 基于PLC与多传感器协同的智能物料分拣系统课程设计
  • AMIC110串行通信接口硬件设计：I2C、SPI、UART引脚配置与电气特性实战
  • CANN/cannbot-skills CP2.2方案检查验收标准
  • 开源方案解析 | 基于多传感器融合的智能消防机器人自主巡检与灭火系统
  • Blender license 放大器，三款优化方案哪个最好
  • TradingView Webhooks Bot架构深度解析：事件驱动交易框架的核心原理
  • 系统硬件工程师实战指南--本安电路关键参数计算与选型
  • CANNBot直调算子工作流状态结构
  • openEuler OpenStack SIG：打造原生OpenStack云平台的终极指南
  • 电子器件系列：三输入与门芯片74LS11的实战应用与选型指南
  • 从接口到设备：MICIN、LINEIN、LINEOUT、HPOUT的电路原理与选型避坑指南
  • UDS DTC老化机制：从Pending到Confirmed再到Aging的完整生命周期解析
  • 保山边境特种作业考证中心｜云南安崇职业技能培训学校市区校区，覆盖全市所有县域 - 资讯焦点
  • datalib核心功能详解：从统计分析到字符串模板的完整指南
  • 终极MMPlayerView使用教程：掌握视频缩放与全屏切换技巧
  • DS90UR910-Q1桥接芯片：FPD-Link转CSI-2接口的硬件设计与驱动开发实战
  • Kmesh在Istio环境中的部署与集成：提升服务网格性能的最佳实践
  • 2026官方认证！常州高端家居定制实测推荐与真实口碑盘点 - 热点速览
  • CANN/cannbot-skills编码红线与解决方案
  • CANN / hcomm 实验性NIC插件指南
  • 【技术解析】基于双矢量优化MPC的MMC-PET光储系统谐波抑制与电网稳定策略
  • 2026官方认证！泉州晋江代理记账首选，透明无套路 - 热点速览
  • openEuler/deepin-rpm-installer开发实战：构建高效RPM安装服务的10个核心技术
  • FileSync终极指南：如何实现跨设备实时文件传输的完整教程
  • 批处理（bat）中的数组进阶：从模拟到实战应用
  • CANN/hcomm集群心跳监控模块
  • Neural Artistic Style开发者指南：如何扩展项目功能与自定义风格网络
  • Linux PAM 故障排除完全手册：解决常见认证问题的10个方法