CLI 会话

本文重点介绍如何通过 CLI 管理会话生命周期与会话控制。

如果你想先了解安装、认证或服务器配置文件，请先参阅 CLI。

同一套规范的操作目录（action catalog）同时驱动着客户端、会话智能体、语音功能以及外部 MCP 服务器。因此，无论是会话 CLI、内置操作界面，还是外部 MCP 控制端，本质上都是通过不同的传输通道来描述相同的会话操作。

会话标识符

大多数命令支持以下任一参数：

完整的 ⟦K26⟧
或无歧义的前缀（⟦K27⟧）
本地存有会话元数据时，通常还支持精确的会话标签（来自 session create 的 --tag）

若前缀匹配到多个会话，命令将执行失败并列出候选会话（可使用 --json 获取结构化输出）。

挂载与恢复（Attach vs Resume）

当会话仍在运行、需要重新连接到运行中的本地或提供商进程时，使用 attach：

kaiwu attach <session-id>

当会话处于非活跃状态，但提供商支持重新激活时，使用 resume：

kaiwu resume <session-id>

简要说明：

attach = 重新连接到运行中的会话
resume = 通过提供商或后端重新打开非活跃会话

完整工作流程请参阅挂载到运行中的会话与恢复非活跃会话。

创建会话

kaiwu session create --title "My session" --message "Hello"

指定其他目录：

kaiwu session create --path /path/to/repo --title "Repo session"

指定后端（`--backend`）

--backend 需要传入一个后端目标标识键：

kaiwu session create --backend "agent:<agent-id>"
kaiwu session create --backend "acpBackend:<backend-id>"

如有疑问，可通过操作目录查看规范 Schema 及可用选项：

kaiwu session actions describe session.spawn_new --json

列出会话

kaiwu session list

便于脚本处理的用法：

kaiwu session list --json

常用过滤条件：

kaiwu session list --active
kaiwu session list --archived
kaiwu session list --resumable

查看状态

kaiwu session status <session-id-or-prefix>

实时状态（若支持）：

kaiwu session status <session-id-or-prefix> --live

发送消息

发送用户消息：

kaiwu session send <session-id-or-prefix> "ping"

等待智能体进入空闲状态：

kaiwu session send <session-id-or-prefix> "ping" --wait --timeout 60

或者仅等待而不发送消息：

kaiwu session wait <session-id-or-prefix> --timeout 60

说明：

若智能体离线、繁忙，或后端未发送“空闲”信号，--wait 可能会超时。
--permission-mode 允许在单次发送时覆盖权限意图。
当后端支持时，--model 允许针对该消息指定特定模型。
在脚本中建议同时使用 --json 与显式超时设置。

历史记录

获取最近的会话记录条目：

kaiwu session history <session-id-or-prefix> --limit 20

用于脚本或调试的变体命令：

kaiwu session history <session-id-or-prefix> --json
kaiwu session history <session-id-or-prefix> --format raw --include-meta --json
kaiwu session history <session-id-or-prefix> --format raw --include-meta --include-structured-payload --json

若希望获得更简洁、偏重文本的视图，请使用 compact。若需要查看提供商 Payload、元数据或结构化的工具与消息记录，请使用 raw。

会话控制

停止会话：

kaiwu session stop <session-id-or-prefix>

归档或取消归档：

kaiwu session archive <session-id-or-prefix>
kaiwu session unarchive <session-id-or-prefix>

更新元数据：

kaiwu session set-title <session-id-or-prefix> "New title"
kaiwu session set-model <session-id-or-prefix> <model-id>
kaiwu session set-permission-mode <session-id-or-prefix> <mode>

权限意图（`set-permission-mode` 与 `--permission-mode`）

Kaiwu 会为每个会话存储一个与提供商无关的权限意图字符串。

常见意图与别名：

default
read_only（也支持 read-only、readonly、ro）
safe-yolo（也支持旧版 acceptEdits）
yolo（也支持旧版 bypassPermissions）
plan

两种使用方式均可：

kaiwu session set-permission-mode <session-id-or-prefix> read_only
kaiwu session send <session-id-or-prefix> "ping" --permission-mode safe-yolo

说明：

set-permission-mode 会更新持久化保存的会话意图。
session send --permission-mode ... 仅对单条消息生效（临时覆盖）。
具体允许执行的操作仍取决于后端/提供商以及你的账户策略。
使用 --json 可查看存储或使用的规范化意图。

上述会话控制命令会映射到如下规范操作：

session.title.set
session.model.set
session.permission_mode.set
session.stop
session.archive
session.unarchive
session.wait.idle
session.message.send
session.run.start
session.run.send
session.run.stop

得益于这种映射机制，一旦启用了相应的界面或接入通道，这些操作不仅能在 CLI 中使用，还能在外部 MCP 宿主和会话智能体中调用。

审批与操作门禁

会话控制命令均实现为操作。

这意味着：

可以针对不同界面（UI / CLI / 会话智能体 / 语音 / 外部 MCP）分别启用或禁用每个操作
可以针对不同界面选择性地为每个操作配置审批要求

当命令受到审批门禁限制时，CLI 不会立即执行，而是返回“审批请求已创建”的 Payload。在客户端收件箱中进行批准或拒绝：

通过 CLI 裁定审批（高级）

对于重度依赖自动化的工作流，也可以通过通用操作执行器来走完同样的审批流程。

示例：

# 1) run an approval-gated command
kaiwu session set-title <session-id> "New title" --json

# 2) approve it through the generic action path
kaiwu session actions execute <session-id> approval.request.decide \
  --input-json '{"artifactId":"<approval-artifact-id>","decision":"approve"}' \
  --json

此对象与客户端收件箱中展示的审批对象完全一致。大部分用户应在客户端中完成审核，但对于脚本化运维人员，如果符合工作流需求，也可以直接通过操作界面裁定审批。

操作（高级脚本编写）

发现操作：

kaiwu session actions list --json
kaiwu session actions describe <action-id> --json

执行操作：

kaiwu session actions execute <session-id> <action-id> --input-json '<json>' --json

当前的 JSON 外层封装结构：

session actions list --json 返回 data.actionSpecs
session actions describe ⟦K28⟧ --json 返回 data.actionSpec
session actions execute ... --json 返回 data.result

执行运行

执行运行（Execution runs）是面向多步骤流程（审查 / 规划 / 委派 / 语音智能体）的结构化“运行”层：

kaiwu session run start <session-id> --intent <intent> --backend <backend-target-key> --json
kaiwu session run list <session-id> --json
kaiwu session run get <session-id> <run-id> --json
kaiwu session run send <session-id> <run-id> "message" --json
kaiwu session run stop <session-id> <run-id> --json
kaiwu session run wait <session-id> <run-id> --timeout 300 --json

高级运行控制：

kaiwu session run action <session-id> <run-id> <action-id> --input-json '<json>' --json
kaiwu session run stream-start <session-id> <run-id> "message" --json
kaiwu session run stream-read <session-id> <run-id> <stream-id> --cursor 0 --json
kaiwu session run stream-cancel <session-id> <run-id> <stream-id> --json

On this page