【声明】本博客所有内容均为个人业余时间创作，所述技术案例均来自公开开源项目（如Github，Apache基金会），不涉及任何企业机密或未公开技术，如有侵权请联系删除

标题

135、【Agent】【OpenCode】项目配置（分隔符）

背景

上篇 blog
【Agent】【OpenCode】项目配置（hidebin）
继续分析了 TS 中的箭头函数，提到了函数体没有返回值，是因为 process.on 注册的回调函数，其返回值会被运行时完全忽略，和嵌入式中断 ISR 是一样的道理，并且 process.on("uncaughtException", callback) 触发后，运行时只是调用这个回调记录日志，根本不关心它返回什么，所以不写返回值是故意省略，接着分析了 index.ts 后面的内容，首先是 OpenCode 的 CLI 定义层，使用的是命令行解析库 yargs，其作用等同于嵌入式系统中的命令解析器，或 Shell 前端，把用户输入的原始字符串参数，结构化为程序内部可消费的选项对象，接着分析了 process.argv 原始命令行参数数组，以及 hidebin 是如何在后台会构建一个包含完整执行上下文的参数数组 process.argv 的，下面继续分析

OpenCode

OK，接下来继续看配置项解析

.parserConfiguration({ "populate--": true })

这里启用 -- 分隔符支持，当用户写 opencode -- some-extra-args 时，-- 后面的内容会被单独收集到 argv["--"] 数组中，不会被当做 opencode 自身的选项解析，这在 CLI 工具中很常见，比如 opencode -- node script.ts 表示把后面的参数透传给子命令

---

这里详细说下分隔符 -- 机制，-- 分隔符是 Unix/POSIX 命令行设计中最重要，但也最容易被忽视的约定之一，下面来看 opencode 命令，这个命令支持 --help 选项，同时 opencode 还有一个 run 子命令，这个子命令可以接收透传给 AI 的消息

当终端输入

opencode run 分析一下这个选项 --help

问题来了，这个选项 --help 到底是给 opencode 命令的，还是作为消息通过 run 子命令传递给 AI 的？yargs（以及几乎所有 POSIX 兼容的解析器），都会贪婪地把所有 --xxx 都当做自己的选项来解析，结果就是，opencode 命令吃掉了 --help 选项，而发送给 AI 的消息，只有【分析一下这个选项】的提示词，没带上后面的关键词 --help

这里分隔符 -- 的作用就来了，可以划清边界，-- 分隔符的含义是，从这里开始，后面的所有内容都不是我的选项，请原样保留，比如

opencode run 分析一下这个选项 -- --help

而启用 populate-- 配置项为 true 之后，yargs 会把 -- 后面的内容放到一个特殊数组里，这里 --help 选项将会原封不动地被放入这个特殊数组 argv["--"] 中

const argv = yargs(hideBin(process.argv))
  .parserConfiguration({ "populate--": true })
  .option("verbose", { type: "boolean" })
  .parse();

console.log(argv.verbose);  // true
console.log(argv["--"]);    // ["--help"]

然后代码就可以这样透传

if (argv["--"]?.length) {
  // 把 -- 后面的参数完整地传给子命令
}

再举个不一样的例子

• 没有 --，--watch 被 bun run 自己消费掉了

bun run test --watch

• 有 --，--watch 明确传给 test 脚本

bun run test -- --watch

此外，如果 test 脚本的选项和 bun run 命令一样的话，不加 -- 就无法区分

再举个例子 git log + 文件路径，比如

• ❌ git 以为 --main.c 是一个选项

git log --main.c

• ✅ 明确告诉 git，这是文件路径，不是选项

git log -- main.c

最后总结，-- 分隔符是命令行参数中的楚河汉界，左边归当前程序解析，右边原样保留，由当前程序自行决定如何使用，通常是透传给子命令，没有它，当两层程序共享相同的选项名时，就会产生无法消除的歧义，yags 默认不启用 populate，大多数简单的 CLI 不需要透传参数，只有当明确知道程序需要把一部分参数交给别人处理时，才需要打开

而在 OpenCode 中，也只有 run 子命令用到了这个透传功能

---

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog
【Agent】【OpenCode】项目配置（链式调用）