@best-agent/cli

Best-Agent v3 的本地 CLI、TUI 与 Application composition 入口。产品合同见：

• Composition
• Task and Session
• Orchestration
• Context
• Presentation
• External Services

当前命令

best-agent run [options] <prompt>
best-agent chat [options]
best-agent subagent [options] <task>
best-agent workflow --workflow <steps.json> [options] <prompt>
best-agent server --stdio [options]
best-agent serve [options]
best-agent daemon [options]
best-agent acp [options]
best-agent --version | -version | -v | version

运行 best-agent --help 查看当前 composition 与 transport 参数。

best-agent --version（等价 -version、-v、version）是只读查询：不进入任何 composition，只在 stdout 打印一行 CLI 版本后退出 （安装态 npm 包读自身 package manifest，SEA 单文件读构建时注入的版本；无法解析时打印 dev），便于在外部脚本或终端里确认当前安装的版本。

b8 是同一入口的短别名（b + 省略的 8 个字母）：安装该包后 b8 <subcommand> 与 best-agent <subcommand> 等价，帮助文本中的命令名仍为 best-agent。

TUI shell mode（! / !!）

Home 或 chat 的空输入框中，用前缀明确选择是否把结果交给模型：

| 输入 | 行为 | 模型上下文 | | --- | --- | --- | | !git status | 直接执行一次 | 完成后，命令、工作目录、输出尾和退出事实随该聊天的下一条消息发送；不自动触发回复 | | !!git status | 直接执行一次 | 命令和输出都不发送给模型 |

输入框和输出区会显示模式说明。第二个 ! 会切换为本地模式，粘贴 !!命令 也会完整识别前缀；前缀不会传给 shell。命令接受后回到普通消息输入，拒绝则保留草稿。使用 ↑ 回忆 shell 命令时，也会恢复它原来的上下文选择。

! 在首页会先建立一个空聊天固定结果归属，不调用模型；!! 无需创建聊天。切换聊天不会改变已经执行的命令的归属。输出区显示“结果已随消息提交”表示消息入口已接受，排队中的消息仍需等待派发。未提交的结果仅保留在当前 CLI 进程中；删除聊天或关闭进程会清理。输出超出保留窗口时会明确显示省略信息；结果过多时会提示先发一条消息。

执行中按 Esc 停止命令；结果显示时空输入框上的 Esc 收起输出区。Backspace / Ctrl+U 在空 shell 输入框上退出模式。既有优先层序保持：in-flight fork → 对话框 / inspect → shell stop/exit → Run interrupt / exit-confirm。/theme 等在 shell 输入框中是命令文本。

• 环境：命令由你的 shell 以交互式登录方式执行（POSIX 为 $SHELL -ilc <命令>，SHELL 为空时用 /bin/sh；Windows 为 cmd.exe /d /s /c <命令>）。子进程继承启动这次 TUI 的终端的全部环境变量，shell 再读你的登录文件与 rc 文件——因此 .zshrc / .bashrc 里定义的 alias 与函数（例如 gp、gpl）和只在那里赋值的变量都可用，与你在新开终端里执行一致。
• 代价（已声明）：每条命令都会执行一次 rc 文件，所以 rc 自己写到 stderr 的输出（例如 npm 的 warning）会如实出现在 block 里， 且重 rc（oh-my-zsh 之类）会让每条命令多花约 1 秒启动时间；这些都不做静默过滤，因为 block 是读取端的忠实副本。
• 仍不支持：需要 TTY 的交互式程序——vim、top、需要密码的 sudo / ssh、以及靠方向键选择的交互式命令（例如 fzf、某些 pnpm run 选择器、你自己的 prun）。子进程的 stdin/stdout 是管道而不是终端（[ -t 1 ] 为假、没有 raw mode、 没有光标寻址），所以这类程序要么直接报 "not a tty"，要么只输出纯文本帧；把终端真正交给子进程（PTY 归属与交接）是独立切片。
• 边界：!! 与 recall 历史不进入模型上下文；! 只有在下一条消息被接受后才进入既有消息历史，后续持久化与 compact 沿用消息本身的规则。
• 运行中的命令在你离开 chat 页面后继续运行，回到 chat 时以运行态恢复显示；离开期间结算的命令以结算态显示，不自动重放。

安装与发布

无需安装 Node 或 npm：在 GitHub Releases 下载当前系统与 CPU 对应的 best-agent-<version>-<target>.tar.gz（Windows 为 .zip），以及同名 .sha256。Linux 当前支持 glibc，不支持 Alpine/musl。

macOS / Linux：先在下载目录校验 shasum -a 256 -c <archive>.sha256（Linux 也可用 sha256sum -c），然后：

tar -xzf best-agent-<version>-<target>.tar.gz
cd best-agent-<version>-<target>
sh install.sh
"$HOME/.local/bin/best-agent" chat

默认安装到 $HOME/.local/lib/best-agent，命令位于 $HOME/.local/bin；把该 bin 目录加入 PATH 后可直接使用 best-agent 或 b8。自定义位置使用 sh install.sh "/absolute/install prefix"。安装脚本不修改 shell 配置；更新时安装新归档即可，用户配置与聊天记录保留。

Windows：用 Get-FileHash <archive>.zip -Algorithm SHA256 与同名 .sha256 中的值比对，解压后在 PowerShell 中执行：

powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1
& "$env:LOCALAPPDATA\Programs\best-agent\bin\best-agent.exe" chat

可用 -Prefix "C:\absolute\install prefix" 自定义目录；把安装目录的 bin 加入 PATH 后可使用 best-agent 和 b8。 归档已包含运行时、CPU supervisor 与所需依赖，解压目录可以在安装后删除。由用户配置启动的外部工具（例如依赖 npx 的 MCP server）仍需各自的运行环境。

• npm install -g @best-agent/cli@beta：安装当前平台的 CLI 包；
• pnpm pack:tui：构建当前平台 npm 包和独立归档，执行安装与启动验收；
• pnpm release:tui [version]：未指定版本时通过 bumpp 交互选择，从干净 main 更新并提交 CLI 版本，等待六平台构建验收和 GitHub Release，再经 OIDC 发布七个 npm 包，等待 npm 扫描完成；
• pnpm distribute:cli：从干净的源码 commit 推送六平台 CI 请求，全部验收通过后分发 GitHub Release，不发布 npm；
• pnpm release:cli --artifact-root .tmp/sea --tag beta --dry-run：验证发布产物。

只打包当前机器的平台，不发布：

pnpm install --frozen-lockfile
pnpm pack:tui

六平台公开分发使用 best-agent-releases。先提交源码改动，再运行 pnpm distribute:cli：命令会推送当前私有源码 commit，仅将公开构建模板和 commit/version 请求同步到分发仓库并触发 CI。CI 使用源码仓库的只读 deploy key；源码仓库保持 private。

完整发版在私有仓库的干净 main 工作目录执行一条命令。不带版本号时，通过 bumpp 交互选择尚未使用的版本号，随后自动继续发布：

pnpm release:tui

也可以显式指定版本号，跳过选择菜单。例如：

pnpm release:tui 0.0.17-beta.3

命令会快进同步远端 main，仅更新、提交 apps/cli/package.json 的版本，推送源码和公开构建请求，跟踪本次 public commit 对应的六平台 CI。全部验收及装包成功后，自动调用既有 publish.yml，等待六个平台包可见且内容一致后发布入口包，并等待入口包可见。预发布版本使用 npm beta，无预发布后缀的正式版本使用 latest。当前锁文件不记录 CLI 自身版本；此命令不重算依赖版本或更新其他工作区包。

只查看计划，不改版本、不提交／推送、不触发 CI 或发布；省略版本号时仍可交互选择，取消选择会停止整个流程：

pnpm release:tui 0.0.17-beta.3 --dry-run

需要当前仓库的 Node/pnpm 环境，以及已登录、可推送两个仓库的 GitHub CLI（gh 2.92 或更新版本）。七个 npm 包既有的 Trusted Publisher 授权继续使用，不需要本机 npm 登录、Access Token 或逐次 2FA。命令需保持运行以衔接后续阶段；任一步失败都会返回非零并停止。中断后若本轮 CI 仍运行，先等待该轮结束，再重跑命令。若 main 仍指向同一发布提交，可显式传入同一版本重跑；已验收的相同 Release 会被复用，不重复修改版本或构建。main 已有新提交时，应按输出的 Release 标签在公开仓库手动恢复原发布，避免把相同 npm 版本用于另一份源码。

全部六平台的免 Node／不可用旧 Node 安装和真实 PTY／ConPTY 交互、原生依赖及 CPU supervisor 检查通过后，Release 提供六份独立归档、六份平台 npm tarball 和一份完整入口 npm tarball，以及校验值和验收摘要。失败时保留未发布草稿，原始诊断及内部构建报告只以加密形式传输；最终 Release 不携带它们。该命令不发布 npm registry。公开分发的 SEA 仍包含可被分析的程序代码，不提供不可逆向的保证。

在 Apple Silicon Mac 上，产物为：

.tmp/npm/best-agent-cli-<version>.tgz
.tmp/npm/best-agent-cli-darwin-arm64-<version>.tgz
.tmp/sea/darwin-arm64/best-agent-<version>-darwin-arm64.tar.gz
.tmp/sea/darwin-arm64/best-agent-<version>-darwin-arm64.tar.gz.sha256

npm 分发需要入口包和匹配的平台包两者；可将两个 .tgz 一并交给对方，通过 npm install -g <platform.tgz> <cli.tgz> 安装，运行依赖仍由 npm 获取。免 Node 的独立分发使用 .tar.gz/.zip。Intel Mac 在 x64 Mac/runner 上运行同一命令，产物 target 为 darwin-x64；不能把 arm64 包重命名为 x64 包。

已有单平台产物时，只做发布预检（不发布）：

pnpm release:cli --artifact-root .tmp/sea --targets darwin-arm64 --allow-partial --tag beta --dry-run

其余平台在对应 OS/CPU 环境运行同一条 pnpm pack:tui，再收集 .tmp/sea/<target>/。构建机需要 .nvmrc 中的 Node、pnpm、原生 C 编译器（macOS/Linux 的 clang，Windows 中目标架构与 Node 一致的 Developer PowerShell / MSVC cl）；POSIX 验收还需要 Python 3 和 pip。Linux 验收环境使用 Ubuntu 24.04；按需安装的 OCR 原生库要求 glibc ≥2.38，不能把 Debian 12 上的 OCR 失败当成 Node 启动失败。

Linux 构建还需要 binutils 的 strip：仅在注入 SEA 前去除 SDK 原生调试信息，保留函数符号；不要对已注入的产物再次执行 strip。

Windows 打包验收会在 .tmp/standalone-pty-runner 安装固定版本的 ConPTY 驱动及终端屏幕解析器，POSIX 屏幕解析器放在 .tmp/standalone-python；它们都不进入 npm 包或独立归档。最终独立归档的安装和启动不要求用户安装 Node、Python 或编译器。

本地开发使用仓库根目录的 pnpm build、pnpm test:cli 与相关 capability 测试。