# IM 双向通信会话命令

连接企业微信、飞书或 Slack 后，可以在机器人对话中使用 `!moi` 命令查看智能体、管理会话或停止当前任务。命令由 MOI 处理，执行后会在 IM 中返回结果。

## 发送规则

- 将命令作为**单独的一条文本消息**发送，不要在同一条消息中附带任务说明或文件。例如，发送 `!moi list sessions`；不要发送“请执行 !moi list sessions”。
- 在需要 @机器人的群聊或频道中，用平台的 @ 功能选择机器人，把一个 @ 放在命令前或后。例如：`@机器人 !moi list sessions`。
- 命令以英文半角感叹号 `!` 开头，命令关键字不区分大小写。参数中的会话 ID 和名称按实际值填写。
- 下表中 `[名称]` 表示可选参数，`<会话ID>`、`<新名称>` 表示必填参数；发送时不要输入方括号或尖括号。

格式不符合要求的消息可能被当作普通对话，而不会执行会话命令。收到回复后，请检查操作是否成功。

## 命令一览

| 命令 | 作用 |
| --- | --- |
| `!moi stop` | 请求停止当前会话中正在运行的任务。 |
| `!moi list agent` | 查看当前连接的智能体名称。 |
| `!moi list session` | 查看当前 IM 对话正在使用的会话 ID。 |
| `!moi list sessions` | 列出当前智能体的会话 ID，并用 `(current)` 标记当前会话。 |
| `!moi new session [名称]` | 新建会话，并立即将当前 IM 对话切换到该会话。名称可省略。 |
| `!moi switch session <会话ID>` | 将当前 IM 对话切换到指定会话。 |
| `!moi use session <会话ID>` | 与 `switch session` 作用相同。 |
| `!moi rename session <会话ID> <新名称>` | 重命名指定会话，不改变当前选中的会话。 |

## 查看智能体和会话

分别发送以下命令，可以查看机器人当前连接的智能体和正在使用的会话：

```text
!moi list agent
```

```text
!moi list session
```

需要查找其他会话时，发送：

```text
!moi list sessions
```

返回内容示例如下，`ctx_123` 和 `ctx_456` 仅用于说明：

```text
Agent sessions:
- ctx_123 (current)
- ctx_456
```

列表显示的是**会话 ID，不是会话名称**；带 `(current)` 的 ID 是当前 IM 对话使用的会话。命令最多查询连接用户在当前工作区、当前智能体下的 100 个活跃会话，并额外置顶当前会话。实际返回的 ID 以你的机器人回复为准。

## 停止当前任务

需要停止当前会话中正在运行的任务时，单独发送以下命令，无需附加参数：

```text
!moi stop
```

命令作用于发送位置当前选中的 MOI 会话。如果群聊或线程中的成员共同使用该会话，停止操作也会影响他们。该命令不会切换或删除会话，也不会清除对话记录或等待处理的消息；等待中的消息可能在当前任务停止后继续执行。

根据机器人回复确认结果：

- **任务已停止**：当前任务已取消。
- **停止请求已受理，任务仍在停止中**：请求已提交，但任务尚未确认停止，可稍后在 MOI 中查看会话状态。
- **任务仍在准备中**：稍后再次发送 `!moi stop`。
- **没有运行中的任务**或**任务已经结束**：本次命令没有停止中的目标任务；如果随后已有新任务开始，需要再次发送停止命令。
- **停止失败**：任务可能仍在运行，可再次发送 `!moi stop`，并在 MOI 中检查会话状态。

如果命令被当作普通消息处理，请联系管理员确认当前 MOI 环境是否已支持该命令。

## 新建会话

例如，发送以下命令，为新的分析任务创建会话：

```text
!moi new session 季度经营分析
```

机器人回复新会话的名称和 ID。创建成功后，当前 IM 对话会立即切换到新会话，后续消息从这个新会话继续。

名称可以包含空格，也可以省略；不填写名称时，默认名称为 `New session`：

```text
!moi new session
```

## 切换到已有会话

1. 发送 `!moi list sessions`，从机器人回复中复制目标会话的完整 ID。
2. 将下面的 `ctx_456` 替换为实际 ID，单独发送：

   ```text
   !moi switch session ctx_456
   ```

3. 确认机器人提示切换成功。必要时发送 `!moi list session`，检查当前会话 ID。

也可以使用等价命令 `!moi use session ctx_456`。切换时使用会话 **ID**，不能用列表序号或会话名称。如果会话不存在或不属于当前智能体，操作不会改变当前会话；请重新查看列表并复制 ID。

## 重命名会话

先通过 `!moi list sessions` 获取会话 ID，再将下面的示例 ID 和名称替换为实际值：

```text
!moi rename session ctx_456 季度经营分析
```

名称可以包含空格。重命名不会切换当前会话：如果还需要进入该会话，请另行发送 `!moi switch session <会话ID>`。如果目标会话不存在或不属于当前智能体，当前会话不会改变。

## 命令影响哪些对话

私聊、不同群聊以及平台支持的话题线程分别维护当前会话。新建或切换只改变**发送命令所在的 IM 对话或线程**；同一群聊或线程中的成员会共同使用该位置当前选中的会话，因此切换前请确认是否会影响其他成员。

会话也可以在 MOI 网页中查看。需要在不同入口继续已有工作时，先用 `!moi list session` 或 `!moi list sessions` 核对 ID，再切换到目标会话。

## 下一步

- [连接后的使用方式](usage.md)
- [连接状态与问题排查](troubleshoot.md)
