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`）

對照探針：判斷問題出在哪一層

下一步