153、【Agent】【OpenCode】启动分析（completion）

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

标题

背景

上篇 blog

分析了 usage 是 API 契约，在代码层面，是 Yargs/Commander 等主流 CLI 框架的固定方法签名，.usage() 的含义来源于框架源码与文档，这里官方明确写到，usage 设置一段用法提示文本，用于告诉用户这个工具该怎么用、有哪些命令可用，本质上就是在 opencode help 输出最顶端看到的那个 ASCII Logo 所在的位置，接着在传入的文本中，如果写了 $0 这个占位符，Yargs 会自动把它替换成当前 CLI 程序的实际名称，比如当前 CLI 入口文件叫 opencode，运行时 Yargs 会自动将 $0 替换为 opencode，实际输出变成

bash 复制代码

Usage: opencode <command> [options]

▄
█▀▀█ █▀▀█ ...

而现实是代码里没有这个 $0，只有一个换行符

所以没有出现 Usage 的提示符

OpenCode

下面来看 .completion() 的含义来源，这个比 .usage() 更有意思，因为它背后是一套操作系统级的隐藏协议。

Shell 补全的工作原理

当在终端输入 cli <TAB> 时，发生的事情是：

bash 复制代码

用户按 Tab
    ↓
Shell (Bash/Zsh) 拦截按键
    ↓
Shell 执行预注册的补全脚本
    ↓
补全脚本调用: cli completion --get-yargs-completions "当前已输入的部分"
    ↓
CLI 程序输出一系列候选词（每行一个）到 stdout
    ↓
Shell 读取这些候选词并展示给用户

Yargs 的 .completion("completion", ...) 做了两件事：

动作	说明
注册子命令	添加一个名为 `completion` 的命令到路由表
生成 Shell 脚本	当执行 `cli completion` 时，输出一段 Bash/Zsh 脚本，这段脚本可以被写入用户的 `~/.bashrc` 或 `~/.zshrc`

那段生成的脚本核心内容大致如下：

bash 复制代码

# 这段代码由 cli completion 自动生成
_cli_completion() {
    local cur="${COMP_WORDS[COMP_CWORD]}"
    COMPREPLY=( $(compgen -W "$(cli completion --get-yargs-completions "$cur")" -- "$cur") )
}
complete -F _cli_completion cli

在终端输入 opencode help，可以看到 opencode completion 命令

接着在终端输入 opencode completion

可以看到 opencode completion 命令，并不是用来触发自动补全的，而是用来生成一段 Bash 补全脚本的，这段输出的本质是一个【安装说明书】+【可执行代码】，其作用是告诉 Shell：当用户按下 Tab 键时，按照这套规则去查询候选词。

🔍 下面逐段拆解这段输出

安装指引（注释部分）

bash 复制代码

###-begin-opencode-completions-###
#
# yargs command completion script
#
# Installation: opencode completion >> ~/.bashrc
#    or opencode completion >> ~/.bash_profile on OSX.
#

这是给人类看的。它告诉如何激活补全功能：把这段脚本追加到 Shell 配置文件中，一旦写入并 source 生效，以后每次打开终端，补全就永久可用了

核心补全函数

bash 复制代码

_opencode_yargs_completions()
{
    local cur_word args type_list
    cur_word="${COMP_WORDS[COMP_CWORD]}"   # 当前光标所在的单词（用户正在输入的部分）
    args=("${COMP_WORDS[@]}")              # 完整的命令行参数数组

    # 关键：调用 opencode 自身来获取候选词列表
    mapfile -t type_list < <(opencode --get-yargs-completions "${args[@]}")
    
    # 将候选词填入 COMPREPLY（Bash 读取这个变量来展示补全菜单）
    mapfile -t COMPREPLY < <(compgen -W "$( printf '%q ' "${type_list[@]}" )" -- "${cur_word}" |
        awk '/ / { print "\""$0"\"" } /^[^ ]+$/ { print $0 }')

    # 如果没有匹配项，回退到文件名补全
    if [ ${#COMPREPLY[@]} -eq 0 ]; then
      COMPREPLY=()
    fi
    return 0
}

这里有一个隐藏的递归调用链，是理解整个机制的关键：

步骤	发生了什么	谁在执行
①	用户输入 `opencode <TAB>`	用户
②	Bash 拦截 Tab，调用 `_opencode_yargs_completions`	Bash
③	函数内部执行 `opencode --get-yargs-completions "..."`	同一个 CLI 程序
④	CLI 解析当前上下文，输出候选词（如 `acp`, `mcp`, `run`）	Yargs 框架
⑤	Bash 读取输出，展示补全菜单	Bash

⚠️ 关键洞察：opencode 这个程序身兼两职。正常调用时它是业务工具；带 --get-yargs-completions 参数时，它变成了一个纯粹的【补全数据提供者】。这就是为什么 .completion() 注册的是一个隐藏的内部协议，而不是一个面向用户的普通子命令。

注册绑定

bash 复制代码

complete -o bashdefault -o default -F _opencode_yargs_completions opencode

这行是真正的开关：

complete: Bash 内置命令，用于注册补全规则
-F _opencode_yargs_completions: 指定补全函数
opencode: 绑定到哪个命令
-o bashdefault -o default: 当自定义补全无结果时，回退到默认的文件名补全

如果想在当前终端启用 Tab 补全，有两种方式，执行：

bash 复制代码

# 方式一：临时生效（仅当前会话）
eval "$(opencode completion)"

# 方式二：永久生效
opencode completion >> ~/.bashrc && source ~/.bashrc

之后输入 opencode <TAB> 就能看到所有子命令，输入 opencode run --<TAB> 就能看到 run 命令的所有选项。

💡 回到 IoC 视角

这也正是回调注入在操作系统层面的体现：

CLI 程序不关心 Shell 怎么展示补全菜单（文本？模糊搜索？弹窗？）
Shell 不关心 CLI 内部有哪些命令、参数怎么校验
两者通过 --get-yargs-completions 这个约定接口解耦协作

CLI 只负责在正确的时机产出结构化数据，展示逻辑完全由 Shell 控制 ------和之前看到的 progress 回调是完全相同的控制反转模式，只不过这次的调用方从应用代码变成了操作系统本身。

OK，本篇先到这里，如有疑问，欢迎评论区留言讨论，祝各位功力大涨，技术更上一层楼！！！更多内容见下篇 blog

【Agent】【OpenCode】启动分析（completion补充）