會話指令

VelaTerm 會在其啟動的每個會話中加入一組簡短的指令。您與您的智慧體可以用這些指令啟動其他會話、開啟檔案、閱讀與搜尋其他對話、查看哪些會話正在忙碌、在會話之間傳送訊息，以及等待耗時較長的指令完成。本章是每個指令及對應智慧體技能的參考說明。

1. 指令的使用範圍

VelaTerm 啟動的每個會話都可以在 PATH 中找到這些指令，包括一般終端機與智慧體會話，無論是終端機檢視還是會話檢視，遠端 VelaTerm 伺服器上的會話也不例外。這些指令無須安裝。在這類會話之外執行時，指令會停止並顯示「not inside a VelaTerm session」。

以 --help 執行指令即可顯示其用法。

指令	用途
`vspawn`、`vspawn-tree`	以一項任務啟動子會話
`vopen`	在文件分頁中開啟檔案，在瀏覽器分頁中開啟網址
`vrefer`	閱讀另一個會話的對話，或針對該對話提出問題
`vsearch`	搜尋所有會話的對話
`vstat`	顯示哪些會話正在工作、正在詢問或正在等待
`vtell`	傳送訊息給另一個會話
`vrun`	執行耗時較長的指令並等待其完成
`vkb`	查詢知識庫與程式碼圖譜
`vflow`	控制規劃與執行工作流程

有幾個指令接受會話參照：完整的會話 ID、至少 8 個字元的 ID 前綴、完全相同的會話名稱，或名稱中唯一的一部分。包含空格的名稱請加上引號。參照符合多個會話時，指令會列出候選項目。

2. 智慧體技能（Vela 技能）

設定 ▸ 一般 ▸「Vela 技能」會在 Claude Code 與 Codex 中安裝對應的技能；「重新安裝」可更新這些技能。安裝後，請開始新的 Claude 或 Codex 對話，讓智慧體載入這些技能。在 Claude Code 中以 /name 呼叫技能，在 Codex 中則以 $name 呼叫。

技能	呼叫者	作用
`vspawn`、`vspawn-tree`	您	根據目前的對話撰寫內容完整、可獨立理解的任務，並啟動子會話或規劃與執行工作流程
`vopen`	您	開啟檔案或網址
`vkb`	您	查詢知識庫與程式碼圖譜
`vrefer`、`vsearch`、`vask`	您或智慧體	閱讀、搜尋或詢問其他對話
`vstat`	您或智慧體	回報哪些會話正在忙碌
`vtell`	您或智慧體	傳送訊息給另一個會話

標示為「您」的技能只會在您呼叫時執行；其他技能在您提及另一個會話或先前的工作時，智慧體也可以自行使用。vask 只以技能形式存在，它會執行 vrefer <session> --ask "<question>"。

3. vspawn 與 vspawn-tree

vspawn [--worktree] [--cwd <path>] [--yes] [--claude|--codex|--copilot|--kiro] [--model <name>] [--effort <level>] <task description...>

在目前會話之下啟動新會話，並將任務作為其第一則訊息傳送。vspawn-tree 是同一個指令，但會使用獨立的 git worktree。

選項	意義
`--worktree`	為子會話提供獨立的 worktree 與分支
`--cwd <path>`	子會話的工作目錄與儲存庫
`--yes`	不顯示確認卡片，直接啟動
`--claude`、`--codex`、`--copilot`、`--kiro`	子會話的智慧體；預設為目前會話的智慧體（一般終端機則為 Claude Code）
`--model <name>`、`--effort <level>`	子會話的模型與推理強度
`--plan-execute` 及相關選項	啟動規劃與執行工作流程

詳細說明：會話派生與 Git 協作與規劃與執行。

4. vopen

vopen <file|url>...

在中央區域中開啟每個引數。Markdown 檔案會在 Markdown 編輯器中開啟，圖片會在圖片檢視器中開啟，其他檔案則在程式碼編輯器中開啟。網址（http 或 https）會在瀏覽器分頁中開啟，瀏覽器分頁僅在桌面版中提供。相對路徑會以目前目錄為基準解析。請參閱文件與瀏覽器分頁。

5. vrefer 與 vask

vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with <agent>] [--timeout N]
vrefer --list [--json]

輸出另一個會話的對話內容。該會話不需要正在執行，也不會有任何內容傳送給它。

選項	意義
`--last N`	只顯示最後 N 則訊息
`--range A:B`	從第 A 則到第 B 則訊息，不包含第 B 則（從 0 開始計算）
`--ask "<question>"`	讓智慧體閱讀對話並回答問題，而不是輸出對話內容
`--with <agent>`	負責回答的智慧體：`claude`、`codex`、`opencode`、`pi`、`omp`、`cursor`、`copilot` 或 `grok`；省略時會自動選擇
`--timeout N`	回答的時限秒數（預設 120）
`--list`	列出可讀取的會話
`--json`	機器可讀的輸出格式

--ask 會另外啟動一個智慧體處理程序來產生回答，並只傳回答案，因此長篇對話不會佔滿目前的上下文。設定 ▸ 行為 ▸「工作階段引用內容」決定如何將對話交給負責回答的智慧體：「使用完整記錄」（預設）或「先摘要」；後者會先以該處選擇的「摘要智慧體」、模型與推理強度精簡對話內容。如果無法產生回答，vrefer 會說明原因，並改為輸出對話內容。

可讀取的對話包括 Claude Code、Codex、OpenCode、Pi、OMP、Grok Build 與 Kiro（僅限文字記錄）。其他會話類型，以及尚未記錄智慧體對話的會話，都無法讀取。

6. vsearch

vsearch <words...> [--session <session>] [--all|--archived] [--limit N] [--json]

搜尋所連線 VelaTerm 上所有會話的對話。所有詞語都必須符合，順序不限。

選項	意義
`--session <session>`	只搜尋此會話
`--all`	包含已封存的會話（預設只搜尋未封存的會話）
`--archived`	只搜尋已封存的會話
`--limit N`	符合條件的會話數量上限（預設 10）
`--json`	機器可讀的輸出格式

每筆結果會顯示會話名稱、ID 前綴、符合次數、幾段附有訊息編號的摘錄，以及可讀取完整對話的 vrefer 指令。訊息編號可搭配 vrefer --range 使用。結果僅來自智慧體對話；只存在於終端機錄製內容中的符合項目不會傳回。「no matches」是正常的結果。

7. vstat

vstat [--wait] [--follow] [--timeout N] [--json]

顯示每個會話的狀態：working、asking（正在等待權限或回答）、waiting（已結束其回合）或 unknown。狀態反映的是活動情況，而不是任務是否已完成。

選項	意義
`--wait`	等待下一次變化，而不是立即回應
`--follow`	持續輸出變化，直到所有智慧體都閒置
`--timeout N`	單次等待的時限秒數（預設 60，上限 300）
`--json`	機器可讀的輸出格式

選用的第一個引數可依舊版 VelaTerm 的編排 ID 進行篩選；規劃與執行工作流程請改用 vflow status。

8. vtell

vtell <session> [--steer] [--message-id msg-UUID] [message...]
vtell [planner-session] --report --round N [--message-id msg-UUID] [message...]

傳送訊息給另一個會話。沒有提供訊息引數時，會從標準輸入讀取文字。收件者會在其對話中看到寄件者的智慧體圖示與會話名稱，重新開啟後也會保留。

收件者必須是以會話檢視執行的 Claude Code、Codex、OpenCode、Pi 或 OMP 會話。已封存的會話與傳送端會話本身會遭到拒絕。
閒置的收件者會開始新的回合。忙碌的收件者會將訊息排入佇列，直到其回合結束；使用 --steer 則會改為將訊息加入執行中的回合。
每則訊息最多可包含 65,536 位元組的文字。
指令會輸出回條：sent、queued 或 steered。blocked 表示收件者正在等待權限或回答。回條只能確認訊息已送達，不代表收件者已完成工作。
指令會輸出訊息 ID。如要重試結果不確定的傳送，請以 --message-id 與相同的文字重新執行指令；訊息不會重複送達。
規劃與執行工作流程中的執行會話會使用 --report --round N 提交結果以供驗收，結果會送交該執行會話的規劃會話。請參閱規劃與執行。

9. vrun

vrun [-t <seconds>] <label> <command> [arguments...]
vrun --status <label>

啟動指令並等待其完成，然後輸出結束代碼、經過時間與日誌的末端內容。指令的結束代碼會原樣傳回。vrun 適用於耗時較長的建置與測試：智慧體以 vrun 執行這些工作時，結果一出來就能得知。

-t <seconds> 設定 vrun 的等待時間（預設 1800）。時間到時，vrun 會以代碼 124 結束，而指令會繼續執行。
--status <label> 會回報先前以該標籤啟動之指令的狀態。
指令執行期間，會話會維持「工作中」狀態。在終端機檢視中，終端機上方的「背景指令」列會列出執行中的指令，並提供「日誌」與「停止」；請參閱終端機使用方式 §6.1。

10. vkb

vkb explore <query> | search <query> | node <symbol-id> | callers <id> [depth] | callees <id> [depth]
    | impact <id> [depth] | path <from-id> <to-id> | files [path]
    | memories <query> | memory <entry-id> | notes <query> | note <vault-id> <path> | status

查詢目前簽出程式碼的程式碼圖譜，以及所連線 VelaTerm 的知識庫。程式碼查詢需要先在專案的程式碼圖譜頁面中啟用索引。vkb 只會讀取，不會變更任何知識條目。請參閱程式碼圖譜與知識庫、工作階段知識庫與本機知識庫。

11. vflow

vflow status|stop|propose|dispatch|accept|block <workflow-id> [--round N --message-id msg-UUID] < message.txt

控制規劃與執行工作流程。規劃會話會在工作流程中使用 propose、dispatch、accept 與 block。您通常只需要兩個操作：

vflow status <workflow-id> 會顯示工作流程的狀態、任務、會話與目前輪次。
vflow stop <workflow-id> 會停止後續輪次，並要求執行中的會話停止。

12. `vela` 指令

在 macOS 上，設定 ▸ 一般 ▸「Shell 指令」提供「安裝 ‘vela’ 指令」。它會將 vela <project-path> 加入您的 shell，類似 VS Code 的 code 指令。在任何終端機中執行此指令，都會在 VelaTerm 中開啟該專案；如果專案已開啟，則會切換到該專案。VelaTerm 不會覆寫並非由其安裝的現有 vela 指令。