会话命令

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`	为子会话分配独立的工作树和分支
`--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 命令，VelaTerm 不会覆盖它。