CLI 使用

启动后进入交互式 CLI，直接输入自然语言任务即可。提示符以 [模式][agent名] > 形式展示当前状态，如 [plan][code] > 。

内置命令

命令	说明
`/plan`	切换为计划模式（只读探索 + 计划提案）
`/interactive`	切换为交互式审批模式（默认）
`/auto`	切换为全自动模式（无需审批，高风险）
`/discuss`	切换为讨论模式（只读对话）
`/mode`	显示当前模式
`/connect`	连接 LLM（选 provider → key → 刷新模型列表 → 推理强度）
`/connect rm`	清除连接配置（回退到环境变量）
`/providers`	列出已配置的 LLM 供应商（`▶` 标记当前生效）
`/use <序号\|id>`	切换当前生效供应商
`/rm <序号\|id>`	删除指定供应商
`/link`	进入账号接入向导（Hub 地址 + 邮箱/手机号 + 密码或短信验证码）
`/link <接入码> [Hub地址]`	凭一次性接入码把本机节点接入用户中心
`/sessions`	列出已保存会话并选择恢复（切换后回显最近消息）
`/history`	列出当前会话的用户指令
`/model <id>`	切换 LLM 模型
`/agent <name>`	切换 agent（Prompt + 可选模型同步）
`/agents`	列出所有 agent（当前高亮）
`/agent add <name> <prompt...>`	新增自定义 agent
`/agent edit <name> <prompt...>`	修改 agent 的 Prompt（当前 agent 即时热更新）
`/agent rm <name>`	删除 agent
`/agent show [name]`	查看 agent 详情
`/mcp`	列出 MCP 服务器与连接状态
`/mcp add <name> stdio <cmd...>\|http <url>`	添加并连接 MCP 服务器（工具自动注入）
`/mcp rm\|enable\|disable\|refresh [name]`	移除 / 启用 / 禁用 / 刷新工具列表
`/tools`	列出所有工具（来源、风险、禁用状态）
`/tool add <name> <cmd...>`	添加命令工具（执行 shell 命令）
`/tool rm\|disable\|enable <name>`	移除 / 禁用 / 启用工具
`/clear`	清空当前会话
`quit` / `exit`	退出
`reset`	重置会话
运行中直接输入 + 回车	向当前任务补充信息（下一迭代生效）
运行中连按两次 ESC	中断当前任务

常见任务示例

直接输入自然语言即可，例如：

> 帮我在当前目录初始化一个 TypeScript 项目
> 读一下 src/ 下的代码，指出潜在问题
> 把 logs/ 里所有 .json 文件重命名为 .json.bak
> 运行测试并修复失败的用例

需要修改文件、执行命令时，交互模式下会弹出审批卡片等你确认。

运行模式

模式	行为
`discuss`	只读，禁止一切写入与执行
`plan`	只读，禁止一切写入与执行，面向计划提案
`interactive`	有副作用的操作需用户逐次审批（默认）
`auto`	有副作用的操作全部放行（高风险，需自行承担）

审批卡片

交互模式下，审批卡片支持：

Y 允许一次
A 总是允许此工具
D 拒绝
run_shell 额外支持 C 总是允许此命令（按具体命令白名单，比放行整个工具更安全）

运行中补充信息（steering）

任务执行期间无需等待完成即可追加指示：直接输入文字并回车，消息会作为一条 user 消息在下一个迭代间隙注入当前任务，agent 继续执行时自动纳入该补充信息。

需要另起新任务时请先等当前任务结束或连按两次 ESC 中断。（审批/提问挂起时，输入仍优先作为审批回答或提问答案。）

会话管理

/sessions 列出已保存会话并选择恢复，切换后回显最近消息，方便断点续接。
/clear 清空当前会话；reset 重置会话状态。
/history 列出当前会话的用户指令，快速回顾上下文。

多供应商管理

可以保存多套 LLM 连接（不同厂商或不同 Key），随时切换：

/providers           # 列出全部供应商，▶ 为当前生效
/use 2               # 按序号切换（也可用 /use <id>）
/rm 3                # 删除某个供应商

用 /connect 添加新的供应商。切换后立即生效，无需重启。

命令行子命令

除了直接 zqagent 进入交互式会话，CLI 还有四个子命令：

bash

zqagent serve [--port <n>] [--host <addr>] [--data-dir <dir>]   # 无界面常驻服务
zqagent link --hub <url> --username <邮箱/手机号> --password '<密码>'  # 账号接入（免重启）
zqagent link --hub <url> --code <接入码>                         # 一次性接入码接入（免重启）
zqagent rename <名称>                                            # 修改节点在 Hub 显示的名称
zqagent update [--status|--check|--now|--rollback]               # 查看/触发节点自动更新、回滚

zqagent 还支持 --resume <会话ID> 恢复上次会话、--debug 输出启动诊断日志。

serve 也可在启动时直接接入：--hub <url> --enroll-code <码> --label <名称>，或用账号方式 --hub <url> --username <邮箱/手机号> --password <密码>。

Windows 单文件把 zqagent 换成 zqagent.exe（未加入 PATH 时用 .\zqagent.exe）：

bat

zqagent.exe serve --port 8787 --data-dir "%APPDATA%\zqagent"
zqagent.exe link --hub https://hub.cd-zq.com --username you@example.com --password <密码>
zqagent.exe link --hub https://hub.cd-zq.com --code <接入码>

zqagent link 不带凭据参数时进入交互向导；密码也可用 ZQAGENT_HUB_PASSWORD 提供。

Windows 上 link 同样会自动发现桌面端安装的节点服务，一般不需要 --data-dir；只有手动配置了计划任务、且数据目录不在默认位置时才需要显式指定。

详见启动节点。

启动诊断（`--debug`）

遇到「启动即退出、控制台没有任何输出」这类问题时，用 --debug 打开诊断：

bash

zqagent --debug              # 单文件可执行程序（macOS / Linux）
node bin/zqagent --debug     # npm 安装的入口

bat

zqagent.exe --debug          :: Windows 单文件
set ZQAGENT_DEBUG=1          :: Windows cmd，等价写法

bash

export ZQAGENT_DEBUG=1       # bash/zsh

诊断日志同步写盘（不经过 stdout 缓冲，进程崩溃或秒退都不会丢），同时回显到 stderr。日志路径按以下顺序解析：

环境变量	含义
`ZQAGENT_DEBUG_LOG`	日志文件完整路径（优先）
`ZQAGENT_DEBUG_DIR`	日志目录，文件名固定为 `zqagent-debug.log`
均未设置	系统临时目录（`os.tmpdir()`）下的 `zqagent-debug.log`

日志包含环境快照、启动各阶段与崩溃堆栈（其中 OPENAI_API_KEY 等凭据只记录「是否设置 + 长度」，不打印明文）。日志停在哪一行，就是失败位置。 取消 --debug 即完全关闭：不写任何文件、不注册处理器。

对照探针：判断问题出在哪一层

单文件产物 = 官方 node 基座 + 注入的 SEA blob + 里面的业务代码。启动即退出时，先用最小样本把三层分开，比直接猜业务代码快得多：

样本	生成方式	跑不起来的含义
`_node-base-<ver>-<platform>-<arch>`	官方 node，零修改	系统/安全软件/加载器层面就拦了，与打包无关
`_sea-minimal-probe-<platform>-<arch>`	最小 SEA 探针，`useCodeCache: false`	SEA 注入或加载失败（看退出码，如 `0xC0000005`）
`_sea-cc-probe-<platform>-<arch>`	同上但 `useCodeCache: true`	交叉构建带了构建机的 V8 code cache
`zqagent-windows-x64.exe`	真实产物	前三个都正常时，问题在业务代码的初始化，用 `--debug` 继续

bash

pnpm run probes:sea                                   # win32-x64（默认）
pnpm run probes:sea -- --arch arm64                   # win32-arm64
pnpm run probes:sea -- --platform linux --arch x64    # 在 Linux 上生成 linux 探针（本机可跑）
pnpm run probes:sea -- --platform darwin --arch arm64 # 在 macOS 上生成 macos 探针（本机可跑）

探针在打印 stdout 之外，还会往临时目录写 zqagent-probe.log——万一是「控制台看不到输出」，落盘日志仍能证明 JS 是否真的执行过。

注入后产物的 sha256 每次构建都会变（blob 里记着构建机上的 main 脚本绝对路径），所以只把基座 _node-base-* 的 hash 当作「文件是否完整/一致」的凭据。

在 macOS 上生成/使用的注意点：SEA 需要 Node ≥ 20；darwin 产物注入前要先 codesign --remove-signature、注入后再 codesign --sign - --force 临时签名（脚本在本机生成 macos 探针时会自动处理），arm64 内核会拒绝运行未签名二进制。为 Windows 生成产物则是纯交叉组装（postject 只写文件、不执行），在 macOS/Linux 上都能直接产出 .exe。

Windows 上把整套文件放在同一目录后直接运行 release/cli/diagnose.cmd：它会依次执行 node -e、两个探针、zqagent --debug，打印每个样本的退出码，并输出诊断日志与探针落盘日志；把整屏文本拷回来即可定位。

CLI 使用 ​

内置命令 ​

常见任务示例 ​

运行模式 ​

审批卡片 ​

运行中补充信息（steering） ​

会话管理 ​

多供应商管理 ​

命令行子命令 ​

启动诊断（--debug） ​

对照探针：判断问题出在哪一层 ​

下一步 ​

CLI 使用

内置命令

常见任务示例

运行模式

审批卡片

运行中补充信息（steering）

会话管理

多供应商管理

命令行子命令

启动诊断（`--debug`）

对照探针：判断问题出在哪一层

下一步