# 模式系统（Modes）

JiuwenSwarm 支持多种运行模式，不同模式对应不同的工具集、权限策略和记忆行为。

> **注意**：在 Web 前端中，用户可通过对话输入区域的**模式选择器**在「**单Agent模式**」和「**集群模式**」之间切换。`/mode` 命令主要用于 IM 受控通道和 TUI。

---

## Web 前端模式

Web 前端提供两种执行模式：

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **单Agent模式** | 单个智能体独立处理任务，支持任务规划与动态调整 | 大多数日常任务、问答、代码生成等 |
| **集群模式** | 多智能体协作模式，由 Leader 编排多个专业智能体分工协作 | 大型复杂任务、需要多角色协作的场景 |

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

---

## 命令行模式（IM/TUI）

通过 `/mode` 命令可切换更细粒度的模式。用户可通过 `/mode` 命令在对话中切换。

### 模式总览

| 模式 | 代号 | 说明 |
|------|------|------|
| Agent（规划） | `agent.plan` | 默认模式。全工具 + 主动记忆，侧重推理与规划 |
| Agent（快速） | `agent.fast` | 全工具 + 被动记忆，侧重快速响应 |
| Code（常规） | `code.normal` | 编码模式 + 编码记忆，侧重代码执行 |
| Code（团队） | `code.team` | 以 Code 配置启动的团队协作模式 |
| Team | `team` | 多 Agent 协作模式，基于配置中的 `team` 定义 |

---

## 切换命令

在频道对话中输入以下命令切换模式：

```
/mode agent          # 切换到 Agent 模式（默认使用 agent.plan）
/mode plan           # TUI 本地简写，等价于 agent.plan
/mode code           # 切换到 Code 模式（默认使用 code.normal）
/mode team           # 切换到 Team 模式
/mode agent.plan     # 直达 Agent 规划子模式
/mode agent.fast     # 直达 Agent 快速子模式
/mode code.normal    # 直达 Code 常规子模式
/mode code.team      # 直达 Code 团队子模式
/mode team.normal    # TUI 本地写法，等价于 team
```

> 兼容性：`/mode plan`、`/mode team.normal` 是 TUI 本地命令能力；Gateway 受控通道只接受 `agent`、`code`、`team`、`agent.plan`、`agent.fast`、`code.normal`、`code.team`。

也可用 `/switch` 在同一大类内切换子模式：

```
/switch plan         # Agent 下切到 plan；Code 下切到 plan
/switch fast         # Agent 下切到 fast
/switch normal       # Code 下切到 normal
/switch team         # Code 下切到 code.team
```

> 上述示例描述的是 IM 频道经过 Gateway 解析的受控命令。TUI 仅在 `agentos-tui` 托管启动（`AGENTOS_TUI_SUPERVISED=1`）时注册语义不同的同名命令：`/switch claude` 用于 handoff 到 Claude TUI，`/switch list` 用于查看可切换目标。独立启动的 TUI 不注册该命令；在 TUI 中切换模式请使用 `/mode ...` 或 `/plan`。

---

## 配置

在 `config/config.yaml` 的 `modes` 段中定义各模式的工具和约束：

```yaml
modes:
  agent:
    fast:
      memory:
        enabled: true
        is_proactive: false    # 被动记忆
      rails: []
      tools: []
    plan:
      memory:
        enabled: true
        is_proactive: true     # 主动记忆
      rails: []
      tools: []

  code:
    rails:
      - FileSystemRail          # 文件系统安全约束
      - SkillUseRail            # 技能调用约束
      - LspRail                 # LSP 辅助约束
    tools:
      - web_free_search
      - web_fetch_webpage
      - web_paid_search
      - user_todos
    embedding_config:
      model_name: null
      base_url: null
      api_key: null

  team:
    jiuwen_team:
      team_name: jiuwen_team
      lifecycle: persistent
      teammate_mode: build_mode
      spawn_mode: inprocess
      leader:
        member_name: team_leader
        display_name: 团队领导
        persona: "天才项目管理专家，擅长任务分解和团队协调"
      agents:
        leader:
          workspace:
            stable_base: true
          max_iterations: 200
          completion_timeout: 600.0
      workspace:
        enabled: true
      transport:
        type: inprocess
      storage:
        type: sqlite
```

### 各段说明

| 路径 | 说明 |
|------|------|
| `modes.agent.fast` | Agent 快速模式：被动记忆，无额外 Rails |
| `modes.agent.plan` | Agent 规划模式：主动记忆，无额外 Rails |
| `modes.code.rails` | Code 模式的动态安全 Rails（固定 Rails 不在此配置） |
| `modes.code.tools` | Code 模式的动态工具白名单（`coding_memory_*` 和 `send_file_to_user` 由运行时自动注册） |
| `modes.code.embedding_config` | Code 模式专属 Embedding 配置（留空则用全局配置） |
| `modes.team.<name>` | Team 模式定义：团队名、lifecycle、leader/agents 配置 |

### 通道默认模式

每个频道可在 `config.yaml` 的 `channels.<channel>.default_mode` 中指定默认模式：

```yaml
channels:
  web:
    enabled: true
    default_mode: agent.plan    # 该频道对话默认使用 Agent 规划模式
```

---

## 模式行为差异

不同模式不只是 UI 名称不同，还会决定 AgentServer 选择哪个运行时 profile、挂载哪些 Rails、如何注入记忆与团队协作能力。

| 模式 | 运行时 profile | Agent 行为侧重点 | 主要 Rails / 工具差异 | 记忆策略 |
|------|----------------|------------------|------------------------|----------|
| `agent.plan` | Deep Agent（`mode=agent`, `sub_mode=plan`） | 默认规划型对话。更适合复杂任务拆解、长期推理、技能演进与需要子代理协助的任务。 | 注册 `TaskPlanningRail`、`SubagentRail`；按配置启用 `SkillEvolutionRail` / `SkillCreateRail`；保留通用搜索、多模态、技能等普通 Agent 工具。 | 使用 `modes.agent.plan.memory`；默认主动记忆（`is_proactive: true`），会更积极地检索/沉淀上下文。 |
| `agent.fast` | Deep Agent（`mode=agent`, `sub_mode=fast`） | 快速响应型对话。更少规划编排，更偏直接回答或按需调用工具。 | 卸载 `TaskPlanningRail`、`SkillEvolutionRail`、`SkillCreateRail`、`SubagentRail`；仍保留通用运行时提示、安全、权限、搜索/多模态/技能工具。 | 使用 `modes.agent.fast.memory`；默认被动记忆（`is_proactive: false`），通常按需读写。 |
| `code.normal` | Code Adapter（`mode=code`, `sub_mode=normal`） | 编码任务的执行阶段。适合改文件、跑命令、验证、交付结果。 | 使用 Code 专用英文系统提示；固定挂载 `LspRail`、`ProjectMemoryRail`、`CodingMemoryRail`、`AgentModeRail`、`StructuredAskUserRail`、`ConfirmInterruptRail`、文件系统/权限 Rails；动态启用 `modes.code.rails` / `modes.code.tools` 中的能力。 | 编码记忆 + 项目记忆。 |
| `code.team` | Code Adapter + Team sub-mode（`mode=code`, `sub_mode=team`） | 以 Code profile 启动团队协作。适合代码项目中让团队成员分工，同时继承编码工作区与代码工具语义。 | 主 Agent 仍使用 Code profile；Team 成员会通过 TeamManager 启动，并尽量继承 Code 侧项目目录、代码工具和成员技能工具包。 | 团队成员使用 Team 配置；编码/项目上下文由 Code profile 和团队运行时共同影响。 |
| `team` | Team runtime（`mode=team`） | 标准多 Agent 协作。Leader 负责分解、调度、汇总，成员按角色并行处理。 | Team 成员挂载 `RuntimePromptRail`、`ResponsePromptRail`、`SysOperationRail`、`TaskPlanningRail`、`SecurityRail`、`HeartbeatRail`、`AvatarPromptRail` 等；Leader 额外支持 Team 技能演进/创建；工具来自可继承白名单和团队配置。 | 由 `modes.team.<name>.memory` 决定，可启用共享 `TEAM_MEMORY.md`、自动提取、成员记忆注入等。 |

### 关键区别速记

- `agent.plan` 与 `agent.fast` 使用同一个 Deep Agent profile，但前者挂载规划、子代理、技能演进等 Rails，后者会卸载这些偏“重编排”的能力。
- `code.team` 与 `team` 都会进入团队协作，但入口不同：`code.team` 从 Code profile 进入，适合代码项目分工；`team` 是标准 Team runtime。

---

## 详见

- [配置信息](配置信息.md) — `config.yaml` 中 `modes` 段的完整字段说明
- [命令行指令](命令行指令.md) — `/mode` 和 `/switch` 的完整命令列表
- [Slash 命令架构](SLASH_COMMAND_ARCHITECTURE.md) — 命令解析的内部处理流程
- [分布式 Team](分布式Team.md) — Team 模式的分布式部署