# 对话

对话是 JiuwenSwarm 最常用的使用入口，不只是聊天，而是接收任务并执行任务的主要入口。在这里，您可以提问、下达任务、补充要求、查看执行过程和结果。

> **注意**：在 Web 前端导航栏中，对话功能的入口名为「**工作**」。点击左侧导航栏的「工作」即可进入对话页面。

---

## 1. 对话入门

### 1.1 对话简介

**对话页的定位**

对话页是 JiuwenSwarm 的核心交互界面，它不仅仅是一个聊天窗口，而是一个**任务接收与执行的工作台**。通过对话，您可以：

- **提问咨询**：获取信息、解答疑问
- **下达任务**：让智能体执行具体操作
- **补充要求**：在执行过程中动态调整
- **查看进度**：实时了解任务执行状态和结果

![对话页面示意图](../assets/images/current-ui/10-工作页面-完整.png)

**核心能力**

| 能力 | 说明 |
|:---|:---|
| **自然语言理解** | 用日常语言描述需求，无需记忆复杂指令 |
| **任务规划** | 复杂任务自动拆解为可执行的子任务序列 |
| **动态调整** | 执行过程中可随时插入新需求或修改计划 |
| **工具编排** | 自动选择和组合合适的工具完成任务 |
| **结果反馈** | 清晰展示执行过程和最终结果 |

---

### 1.2 如何开始对话

**基本操作流程**

1. **输入需求**：在输入框中描述您的需求或任务
2. **发送消息**：点击发送或按 Enter 键
3. **查看回复**：智能体会理解您的需求并开始执行
4. **继续补充**：根据执行结果，可以继续补充要求或调整方向

![对话操作流程示意图](../assets/images/current-ui/10-工作页面-完整.png)

**需求描述建议**

为了获得更好的执行效果，建议在描述需求时包含以下要素：

| 要素 | 说明 | 示例 |
|:---|:---|:---|
| **目标** | 明确要达成什么 | "生成 API 文档" |
| **范围** | 指定作用范围 | "针对 src/api 目录下的所有接口" |
| **限制条件** | 特殊要求或约束 | "使用中文，格式为 Markdown" |
| **输出形式** | 期望的结果形式 | "输出到 docs/api.md 文件" |

**提问示例对比**

| 推荐写法 ✅ | 不够清晰 ❌ |
|:---|:---|
| "帮我整理 `docs/zh` 目录下的所有 Markdown 文档，检查标题层级、修复格式问题，并生成一份修改清单" | "整理文档" |
| "分析 `src/core` 目录的代码结构，生成架构图并输出为 PNG 格式，保存到 `docs/architecture.png`" | "分析代码" |
| "将 `README.md` 翻译成英文，保持原有格式，输出到 `README_EN.md`" | "翻译 README" |

**首次使用建议**

- 从**目标明确的小任务**开始，逐步熟悉智能体的能力
- 如果第一次结果不符合预期，可以**继续补充要求**，而不是重新开始
- 善用**追问和细化**，帮助智能体更好地理解您的需求

---

### 1.3 对话中的常见操作

在对话过程中，您可以随时进行以下操作来调整任务执行：

**动态调整操作**

| 操作 | 说明 | 使用场景 |
|:---|:---|:---|
| **补充要求** | 对当前正在执行的任务追加细节或修改方向 | 发现遗漏细节、需要调整输出格式或约束条件 |
| **插入新任务** | 在任务队列中插入一个全新的独立任务 | 有更高优先级的独立需求出现 |
| **打断任务** | 中断当前正在执行的任务 | 需要停止或改变当前任务方向 |
| **调整优先级** | 改变待执行任务的顺序 | 重新安排执行顺序 |
| **结束任务** | 标记某个任务为已完成或取消 | 任务不再需要执行 |
| **查看状态** | 查看当前任务列表和执行进度 | 了解整体进展 |

> **补充要求 vs 插入新任务**：补充要求是对**已有任务**的细化或扩展（如"报表也加上图表"），插入新任务则是添加一个**全新的独立任务**（如"顺便帮我翻译另一份文档"）。

**核心特性：边聊边调整**

JiuwenSwarm 的对话系统支持**实时动态调整**。当您在智能体执行任务过程中输入新需求时，系统会：

1. **理解新需求**：解析您的补充内容
2. **评估影响**：判断对当前任务的影响
3. **重新规划**：将新需求融入任务队列
4. **继续执行**：按照新的计划推进

**案例：动态调整全流程演示**

以下案例串联了常见的动态调整操作，展示从任务规划到执行、调整、查看的完整过程：

**步骤一：下达任务**

```
用户：处理 12 月的发票数据，生成汇总报表。先生成待办列表

智能体：任务列表：
  [1]	获取12月发票数据文件	🔄 进行中
  [2]	读取并解析发票数据	⏳ 待执行
  [3]	数据清洗与校验	⏳ 待执行
  [4]	生成汇总报表	⏳ 待执行
  [5]	输出报表文件	⏳ 待执行

▶ 开始执行任务 [1]...
```

**步骤二：插入新任务**

```
用户：对了，1 月的发票也要处理，两份合并后发邮件给财务

智能体：任务列表更新：
  [1]	获取12月和1月发票数据文件	🔄 进行中
  [2]	读取并解析12月和1月发票数据	⏳ 待执行
  [3]	数据清洗与校验（12月+1月）	⏳ 待执行
  [4]	合并数据并生成汇总报表	⏳ 待执行
  [5]	导出报表文件并发邮件给财务	⏳ 待执行

▶ 继续执行...
```



---

## 2. 执行模式

### 2.1 模式概览

JiuwenSwarm 支持两种执行模式，不同模式适用于不同的场景。您可以根据任务特点选择合适的模式。

![模式选择器](../assets/images/current-ui/12-模式选择器.png)

**模式对比**

| 模式 | 运行方式 | 适用场景 | 特点 |
|:---|:---|:---|:---|
| **单Agent模式** | 单个智能体独立处理任务，支持任务规划与动态调整 | 大多数日常任务、问答、代码生成 | 灵活高效，适用面广 |
| **集群模式** | 多智能体协作执行，由 Leader 编排分工 | 大规模任务、需要专业分工 | 能力互补，协同处理 |

**模式切换**

您可以通过以下方式切换执行模式：

- **界面切换**：在对话输入区域点击模式选择器切换
- **命令切换**：使用 `/mode` 或 `/switch` 命令（详见[命令行指令](#3-命令行指令)）

---

### 2.2 单Agent模式

#### 2.2.1 概念科普

**什么是单Agent模式？**

单Agent模式是 JiuwenSwarm 的默认工作模式。在此模式下，单个智能体独立处理您的任务，具备以下能力：

- **任务规划**：复杂请求自动分解为可执行的子任务序列
- **动态调整**：支持中途追加需求、插入紧急事项
- **工具调用**：自动选择和组合合适的工具完成任务
- **实时追踪**：每完成一个子任务，状态实时更新，进度清晰可控

**适用场景**

- 大多数日常任务、问答、代码生成
- 步骤较多、需要分阶段完成的任务
- 任务中途可能发生变化或调整
- 希望过程清晰可跟踪的任务

---

### 2.3 集群模式

#### 2.3.1 概念科普

**什么是集群模式？**

集群模式（Team Mode）是 JiuwenSwarm 的多智能体协作模式。在此模式下，多个专业智能体协同工作，各自负责擅长的领域，共同完成复杂任务。

**核心特点**

- **专业分工**：不同智能体负责不同领域
- **协同处理**：智能体之间可以通信协作
- **能力互补**：组合多种专业能力
- **结果整合**：汇总各智能体的输出

**适用场景**

- 大规模、多领域的复杂任务
- 需要多种专业技能的任务
- 单一智能体难以完成的任务

#### 2.3.2 案例实践

**案例：全栈项目开发**

```
用户：开发一个用户管理系统，包括前端界面、后端 API 和数据库设计

智能体：🤖 启动集群模式，分配任务：
[team_leader] 我来帮你开发一个用户管理系统。在开始之前，我需要确认几个关键信息以确保方案符合你的需求...

用户：使用默认方案

智能体：
[team_leader] ✅ 团队已组建并启动！
[frontend-dev] 收到！我已查看任务板
[backend-dev] 收到项目启动通知！
[qa-engineer] 收到项目启动通知！

```

集群模式下的典型流程：

1. **对齐需求**：Team Leader 在集群启动前与用户确认需求与关键信息
2. **认领与并行启动**：子任务拆分后，各角色智能体认领工作、并行启动
3. **协作推进**：多智能体持续协作、同步进展
4. **结果整合**：Leader 汇总各智能体的输出，生成最终结果

> **提示**：集群模式下的案例展示了多智能体协作的基本流程。实际使用中，请根据项目需求验证集群模式是否能完整交付您的工程目标。

---

## 3. 命令行指令

### 3.1 指令概览

JiuwenSwarm 支持通过「特殊前缀指令」控制会话和模式。这些指令在消息到达智能体之前就被系统识别并处理，**不需要智能体来执行**，而是直接改变系统的运行状态（比如切换模式或创建新会话）。

> **所有命令行指令都可以直接在对话框中输入即可**，无需使用命令行终端。只需在聊天输入框中输入以 `/` 开头的指令，系统会自动识别并执行。

> **重要：指令的生效范围取决于通道类型**。部分指令仅在特定通道中由系统拦截并执行，在其他通道中可能被当作普通消息转发给智能体。详见下方「通道适用范围」说明。

**通道适用范围**

JiuwenSwarm 的指令按处理层级分为两类：

| 层级 | 处理方 | 适用通道 | 说明 |
| :--- | :--- | :--- | :--- |
| **Gateway 拦截** | 网关层 | 飞书、钉钉、企微、微信、WhatsApp、小艺 | 指令在网关层被拦截，不转发给智能体，直接改变系统状态 |
| **客户端处理** | 客户端侧 | TUI（终端） | 指令由 TUI 客户端本地处理，通过 `session.create` 等请求与 AgentServer 协同完成状态变更 |
| **不拦截** | — | Web 对话页 | 指令不会被系统拦截，而是作为普通消息转发给智能体，由智能体自行理解和响应 |

> **Web 对话页**：以 `/` 开头的指令不会被网关拦截，会当作普通消息发给智能体，**不会让会话或模式真实切换**。要在 Web 里开新对话、换模式等，请用页面上的按钮或菜单（如「新建对话」、模式选择器）；需要靠指令精确控制时，请使用 IM 受控通道或 TUI。

**一级模式与二级模式说明**

JiuwenSwarm 的执行模式分为两层：

- **一级模式**：决定智能体的整体工作方式，如智能体模式（`agent`）、代码模式（`code`）、团队协作模式（`team`）
- **二级模式**：在一级模式下的细化执行策略，如规划模式（`plan`）会先拆解任务再执行，快速模式（`fast`）则直接执行

> **注意**：并非所有一级模式都有二级模式。目前 `agent` 和 `code` 模式支持二级模式（`plan`/`fast`/`normal`），而 `team` 模式暂不支持二级模式切换。使用 `/mode` 可以直接指定一级+二级组合（如 `/mode agent.plan`），使用 `/switch` 则只切换当前一级模式下的二级模式。

**指令分类**

| 类型 | 指令 | 说明 | 适用通道 |
| :--- | :--- | :--- | :--- |
| **会话控制** | `/new_session` | 创建新会话 | IM 受控通道 |
| **模式切换** | `/mode` | 切换一级模式（也可指定一级+二级组合） | IM 受控通道 |
| **模式切换** | `/switch` | 切换二级模式（在当前一级模式下切换） | IM 受控通道 |
| **技能管理** | `/skills list` | 列出可用技能 | IM 受控通道 |
| **工作区** | `/workspace_dir` | 设置工作区路径 | TUI |
| **会话重置** | `/clear`（别名 `/new`、`/reset`） | 清空对话历史并创建新会话 | TUI |

**使用建议**

- **自然语言优先**：大多数情况下，直接用自然语言描述需求即可
- **命令行辅助**：在需要快速切换或精确控制时使用命令
- **避免混用**：同一消息中不要同时包含命令和自然语言
- **注意通道**：确认您使用的通道支持该指令，否则指令只会被当作普通消息处理

---

### 3.2 常用指令详解

#### `/new_session` —— 新建会话

**作用**

可以把它理解成：**在当前通道里开一段新的空白对话**。新对话里**没有**上一段会话的聊天历史，智能体只按新会话继续聊。上一段会话里的记录**不会因此被删掉**，仍保留在系统里，需要时可以通过历史或会话列表等方式**自行找回、恢复**。

在 IM 等受支持通道里，系统会先切到新的 `session_id` 再处理后续消息，并取消旧会话上仍在跑的任务。工作区里 `workspace/session/` 下的会话目录通常会在**首次产生待办、保存文件等写入**时按需创建，而不必在意「是否在输入指令的那一瞬就立刻建文件夹」。

**适用通道**

| 通道 | 说明 |
| :--- | :--- |
| **IM 受控通道**（飞书、钉钉、企微、微信、WhatsApp、小艺） | ✅ 可用：网关拦截后新建会话上下文，后续消息走新会话 |
| **TUI（终端）** | 终端**没有**网关里的 `/new_session`，请用 **`/clear`**（与 **`/reset`、`/new`** 同上表）新开空白会话 |
| **Web 对话页** | ❌ **勿用指令**：`/new_session` 不会真正生效，请用页面上的「新建对话」等控件 |

**使用方式**

IM 受控通道里单独发送一行：**整行必须恰好为 `/new_session`，不能带后缀参数。**

```
/new_session
```

终端 TUI **没有这一条网关指令**。要在 TUI 新开空白会话，请发送 **`/clear`**（与 **`/reset`、`/new`** 等价，由同一内置指令处理）。

**IM 受控通道的实际处理**（网关：先识别控制指令再更新会话）

- **不**把该消息交给智能体解析。
- 为当前通道轮换新的 `session_id` 并写入状态；对**旧会话**在网关与 AgentServer 侧发起取消（含进行中的任务）。
- 向会话回一条固定通知：`[收到 CLI 指令], session_id 已变更为 <new_sid>`。
- IM 聊天窗口里仍可看到**此前**的消息；**从下一条你发出的消息开始**，走新 `session_id`，智能体侧按新会话上下文处理。

**TUI：`/clear` 的实际处理**

- 若当前没有在跑任务：携带 `create_token` 调用 `session.create`，由 AgentServer 分配并返回新 `session_id`；成功后切换当前会话并**清空终端消息列表**，再拉取新会话的空历史，并显示：`Started a fresh conversation in <session_id>`。若创建失败，TUI 保持在原会话。

**workspace/session/ 示意（按需落盘）**

```
workspace/session/
  feishu_17f2b4b32e0_ab12cd/   ← 新会话目录（有写入时再出现即可）
    todo.md                     ← 待办等事项（首次写入时生成）
```

**注意事项**

- 旧会话的数据与历史仍然保留，与「新开一段空白上下文」可以同时成立
- 在 IM 受控通道中，`/new_session` 会取消旧会话上正在执行的任务（含网关与 AgentServer 侧）
- 指令须**单独一行且完全匹配** `/new_session`；写成 `/new_session xxx` 等会被视为无效

---

#### `/mode` —— 切换一级模式

**作用**

为当前通道设置一级执行模式，影响 Agent 的行为策略。也可以直接指定一级+二级组合。

**适用通道**

| 通道 | 处理方式 | 实际效果 |
| :--- | :--- | :--- |
| **IM 受控通道**（飞书、钉钉、企微、微信、WhatsApp、小艺） | Gateway 拦截 → 更新 channel 状态 → 取消旧任务 → 不转发给智能体 | ✅ 真正切换模式 |
| **TUI（终端）** | 客户端侧处理 | ✅ 真正切换模式 |
| **Web 对话页** | Gateway **不拦截** → 当作普通消息转发给智能体 | ❌ 不会真正切换模式 |

**支持的模式**

| 模式 | 说明 |
| :--- | :--- |
| `agent` | 智能体模式（默认） |
| `code` | 代码模式 |
| `team` | 团队协作模式 |
| `agent.plan` | 智能体模式 + 规划二级模式 |
| `agent.fast` | 智能体模式 + 快速二级模式 |
| `code.plan` | 代码模式 + 规划二级模式 |
| `code.normal` | 代码模式 + 普通二级模式 |

> `/mode agent.plan` 和先 `/mode agent` 再 `/switch plan` 效果相同，前者更简洁。

**使用方式**

**模板**：`/mode` + `<模式字段>`

`<模式字段>` 可以是一级模式名（如 `agent`、`code`、`team`），也可以是一级与二级用 `.` 连接的组合（与上表「支持的模式」一致）。

**示例**：切换到智能体模式并指定二级「快速」：

```
/mode agent.fast
```

**系统响应**

```
mode 已变更为 agent.fast
```

---

#### `/switch` —— 切换二级模式

**作用**

在当前一级模式下，切换二级执行策略。仅对支持二级模式的一级模式有效（目前 `agent` 和 `code` 支持，`team` 暂不支持）。

**适用通道**

与 `/mode` 相同，仅在 IM 受控通道和 TUI 中真正生效，在 Web 对话页中作为普通消息处理。

**支持的模式**

| 模式 | 说明 |
| :--- | :--- |
| `plan` | 规划模式 —— 先拆解任务再逐步执行 |
| `fast` | 快速模式 —— 减少规划，直接执行 |
| `normal` | 普通模式 —— 默认执行策略 |

**使用方式**

```
/switch plan
/switch fast
/switch normal
```

---

#### `/skills list` —— 列出技能

**作用**

列出当前可用的所有技能。

**适用通道**

| 通道 | 处理方式 | 实际效果 |
| :--- | :--- | :--- |
| **IM 受控通道**（飞书、钉钉、企微、微信、WhatsApp、小艺） | Gateway 拦截 → 调用 `skills.list` → 以通知回复 | ✅ 真正列出技能 |
| **TUI（终端）** | 客户端侧处理 | ✅ 真正列出技能 |
| **Web 对话页** | Gateway **不拦截** → 当作普通消息转发给智能体 | ❌ 智能体以自然语言回复，可能不准确 |

**使用方式**

```
/skills list
```

**系统响应**

```
【技能列表】
1. document-writer (skillnet)
   文档写作与优化
2. code-analyzer (skillnet)
   代码分析与重构
3. data-processor (clawhub)
   数据处理与转换
...
```

---

#### `/workspace` —— 管理项目作用域与可信目录（TUI 专用）

**作用**

管理终端 UI 的项目作用域，以及文件操作可以访问的可信目录。此指令仅在 TUI 中可用。

**适用通道**

仅 TUI（终端）客户端支持，其他通道不可用。

**使用方式**

```
/workspace get                  # 查看工作空间、项目作用域与可信目录
/workspace add C:\Shared         # 为当前项目添加可信目录
/workspace set C:\Projects       # 切换项目作用域并信任该目录
/workspace remove C:\Shared      # 移除可信目录
/workspace clear                # 清空当前项目的可信目录
```

兼容别名：`/workspace_dir`、`/workspace-dir`。

**持久化**

可信目录按项目保存到 `~/.jiuwenswarm-tui/config.json`。通过 `/workspace set` 选择的项目作用域仅在当前 TUI 进程中有效；重启后重新以启动目录作为项目作用域。

后续请求会携带 `trusted_dirs`、`project_dir` 和 `cwd`，供 Gateway 与 AgentServer 应用项目上下文和文件访问策略。

📢更详细的指令详见：[Slash 命令速查表](Slash命令表.md)。

---

## 4. 对话逻辑

### 4.1 执行流程

JiuwenSwarm 在对话背后的基本逻辑：

```
用户输入 → 意图理解 → 模式判断 → 任务处理 → 结果反馈
```

**详细流程**

1. **意图理解**：解析用户自然语言，识别真实需求
2. **模式判断**：根据任务特点和当前模式，决定执行策略
3. **任务处理**：
   - **单Agent模式**：单个智能体独立处理，支持任务规划与动态调整
   - **集群模式**：分配给多个智能体协同执行
4. **结果反馈**：以清晰的方式向用户呈现执行结果

### 4.2 动态调整机制

JiuwenSwarm 支持在执行过程中根据用户新输入重新规划任务列表：

- **实时监听**：持续接收用户的新输入
- **影响评估**：判断新需求对当前任务的影响
- **智能合并**：将新需求合理融入任务队列
- **无缝衔接**：保证执行流程的连贯性

### 4.3 任务规划机制详解

**核心机制**

任务规划模式的核心逻辑：

1. **需求解析**：将用户请求解析为可执行的子任务序列
2. **任务记录**：通过待办工具系统性记录所有子任务
3. **状态追踪**：实时更新每个子任务的执行状态
4. **动态调整**：支持用户随时插入、修改或取消任务

**工具赋能**

JiuwenSwarm 提供了完整的待办事项工具包（`TodoToolkit`），任务以 Markdown 形式持久化至 `workspace/session/{session_id}/todo.md`，按会话隔离，支持并发安全读写。

| 工具 | 说明 |
| :--- | :--- |
| `todo_create` | 创建初始待办清单 |
| `todo_insert` | 在指定位置插入新任务 |
| `todo_complete` | 标记任务为已完成 |
| `todo_remove` | 删除指定任务 |
| `todo_list` | 列出当前所有待办事项 |

**任务状态**

| 状态 | 说明 |
| :--- | :--- |
| `waiting` | 待执行 |
| `running` | 执行中 |
| `completed` | 已完成 |
| `cancelled` | 已取消 |