Merge branch 'multiagent-mode'

AGENTS.md

@@ -201,6 +201,25 @@
 1. **meta 部分只放参数**：`tool-result-meta` 仅用于展示工具调用的参数、配置、状态标识等元信息。例如：状态、ID、路径、任务描述、超时时间等。禁止在 meta 区域放置执行结果、统计摘要、输出内容等。
 2. **content 部分只放结果**：`tool-result-content` 仅用于展示工具执行后的结果、输出、统计、总结等。例如：文件内容、命令输出、搜索命中、执行统计（工作时间 / 调用次数 / 工具次数）、最终回复摘要等。禁止在 content 区域重复展示工具参数。
 
+## 5.7) 调试输出规范（强制）
+
+> 约束级别：需要临时加调试日志排查问题时**必须遵守**。
+
+### 前端调试日志
+
+- **统一筛选词**：所有临时 `console.log` 必须使用**同一个**筛选前缀（例如 `[route-debug]`），方便用户在浏览器控制台用该前缀一次性筛选。
+- **控制数量与时机**：
+  - 禁止一次性输出上百上千条日志刷屏。
+  - 只在关键路径（入口、分支判断、状态变化、导航动作）打印，避免在循环、高频事件、每帧渲染中输出。
+  - 需要大量结构化数据时，优先用 `console.group` / `console.table` 或对象快照，而不是逐条打印。
+- **用完即清**：问题定位后应及时删除或注释掉临时调试日志，不要长期留在代码里。
+
+### 后端调试日志
+
+- **必须写入文件**：后端调试信息禁止直接 `print` 到终端刷屏，必须写入日志文件。
+- **复用现有 logger**：优先复用项目已有 logger（如 `utils/logger.py`、`modules/multi_agent/debug_logger.py` 等），按模块落到 `~/.astrion/astrion/<mode>/logs/` 下。
+- **关键状态转换必打**：多智能体、子智能体、任务轮询等复杂链路应在关键状态转换点写结构化日志，便于复现问题后按时间线追溯。
+
 ## 6) Git 工作流（开发 + Review）
 
 ### 6.1 核心原则
@@ -332,3 +351,119 @@ AI 执行以下流程时，每一步都要向用户说明在做什么：
 - 调试开关（代码变量）：`modules/approval_agent.py` 中 `DEBUG_SAVE_APPROVAL_AGENT_TRANSCRIPT`
   - 开启后写入：`logs/approval_agent/`
   - 记录以累积 `messages` 为主，便于对齐主/子智能体会话格式
+
+## 11) 多智能体模式（multi-agent mode）
+
+> 对话级开关 `metadata.multi_agent_mode = true` 启用，URL 入口 `/multiagent/<conv_id>`，数据目录 `~/.astrion/astrion/host/mutiagents/`（保留原拼写）。完整设计与踩坑记录见项目记忆 `multi_agent_mode_design`，本节只列 Agent 改代码时必须知道的硬约束。
+
+### 11.1 角色与实例
+
+- 主智能体显示名固定为 `Team Leader`，不需要专门的预置角色文件。
+- 子智能体 = `role_id`（如 `ui-operator` / `full-stack-engineer` / `code-reviewer` / `researcher`）+ `agent_id`（同一 role_id 下从 1 递增）。显示名格式 `{Role Name}_{agent_id}`，例如 `UI Operator_1`，后缀永远带数字。
+- 主→子 / 子→主 / 子→子三种通信通过工具完成，工具签名见 `modules/multi_agent/tools.py`。
+- **`send_message_to_sub_agent` 与 `ask_sub_agent` 语义不同，必须保留两者**：前者插入引导消息不阻塞，后者阻塞等待一轮回答。
+- 子智能体间通信要求同时向主智能体输出汇报，不允许「偷偷沟通」。
+
+### 11.2 子智能体执行机制
+
+- 子智能体在主进程内 `asyncio.Task`，跑在独立后台事件循环线程里（避开 Flask-SocketIO threading 冲突）。工具调用复用主进程沙箱/容器链路，网络调用走 `utils.api_client.DeepSeekClient`。
+- 子智能体在多智能体模式下：
+  - `create_sub_agent` 强制 `run_in_background=False`，不触发 `sub_agent_waiting` 事件，不阻塞前端输入区。
+  - 子智能体自然的 assistant 输出结束（无 tool_calls）即本轮任务结束，进入 `idle`，上下文保留，不算 failed。
+  - 不能把 `output.success == null` 直接判为 `failed`—`_check_task_status()` 对多智能体任务 `status=running/idle` 视为正常态（见 `modules/sub_agent/state.py`）。
+  - idle 等待必须用 `asyncio.Event`，不能用 `threading.Event`，跨线程唤醒用 `call_soon_threadsafe`。
+  - 任务记录里 `multi_agent_mode` 字段必须显式写入，缺失会导致传统后台通知池把多智能体任务当后台任务处理。`reconcile_task_states()` 已对旧任务补回。
+
+### 11.3 消息池与派发链路（重点）
+
+**输出端 ↔ 接收端分离**：
+- 输出端（`SubAgentTask._forward_output_to_master`）：子智能体每次 assistant 文本输出都封为标准格式消息并 `push_master_message` 到会话的 `MultiAgentState.pending_master_messages`，不再做事。
+- 接收端（`MultiAgentState` + dispatch）：根据主智能体当前状态选择插入方式：
+  - **情况1（主运行中）**：在 `execute_tool_calls` 末尾 `process_multi_agent_master_messages(inline=True, after_tool_call_id=...)` 插入到下一轮模型 messages 列表里（详见 `server/chat_flow_tool_loop.py:1326`）。
+  - **情况2（主空闲）**：`poll_multi_agent_notifications` spawn 出后台 poll，主对话空闲且 pool 有消息就 drain，调 `_dispatch_multi_agent_idle_messages` 创建 `task_type="notice"` 的后续 task，触发新一轮工作。完整顺序见项目记忆 multi_agent_mode_design 中的「情况2完整链路」图。
+  - **情况3（主最后一轮无工具调用）**：主循环 `if not tool_calls:` 分支调 `process_multi_agent_master_messages(inline=False)` 后 `continue` 继续迭代，Team Leader 在同 task 续跑处理子智能体输出。（实现上与情况2同路径，即情况3通过后续 task 完成情况2）。
+
+**情况2 硬约束（调试踩过坑）**：
+  1. **Pool 优先，不能等所有 running 退出再 drain**：`ask_master` await 期间 status=running，但子智能体本身不会产生新输出，只有等主对话回答才能解套。pool 有消息就立即 drain，不管 running 状态。「对话处于运行状态」只决定前端显示态，不阻塞 pool 消费。
+  2. **`_dispatch_multi_agent_idle_messages` 持久化不要重复**：前置 N-1 条调 `inject_multi_agent_master_message` 绑定持久化。最后一条只 emit 给在线客户端、不持久化、在后续 `task_manager.create_chat_task` 走的 `handle_task_with_sender` 里才 `add_conversation`。否则历史里会有两条相同 user 消息，前端刷新会被渲染两遍（一条多智能体渲染、一条通知渲染）。
+  3. **Metadata `visibility` 必须显式为 `"chat"`**：`_user_message_ui_defaults("sub_agent")` 默认给 `{visibility: "compact"}`；在 `_dispatch_multi_agent_idle_messages` 构造 `auto_user_message_payload`时，如果有`**ui_defaults`，必须在它之**后**写 `"visibility": "chat"`（dict 字面量中后出现的key 胜出）。同样，在`handle_task_with_sender`处理多智能体消息时，`user_message_metadata.update(multi_agent_meta)`之后要显式`user_message_metadata["visibility"] = "chat"`。
+  4. **必须传 `auto_message_type`**：前端 `isMultiAgentMessage()` 只看 `auto_message_type.startsWith('multi_agent_')`。`auto_user_message_payload` 和 `preceding_user_notices[i].payload` 都必须显式写 `auto_message_type`，字段不能用空值，否则前端 fallback 起通知渲染。
+
+### 11.4 通知池轮询器完全独立
+
+- 传统后台子智能体 / 后台 `run_command` 通知：`poll_completion_notifications`，在 `handle_task_with_sender` 结尾的 `needs_completion_poll` 。
+- 多智能体通知：`poll_multi_agent_notifications`，在 `needs_ma_poll`。两者完全独立，避免 task_manager 单工作区互斥竞争。
+- `task_complete` 事件中：
+  - `has_running_sub_agents` 只算传统后台任务，不算多智能体。
+  - `has_running_multi_agent` 多智能体专用字段，同时包含 _running_ 实例和 pending master 消息（详见 `server/chat_flow_task_main.py:2324`）。前端通过该字段走独立的 `startMultiAgentTaskProbe`（不启动 `sub_agent_waiting`）。
+
+### 11.5 渲染与前端约定
+
+- 多智能体消息渲染条件是**两个独立判断**：
+  - `isMultiAgentMessage()`：看 `auto_message_type.startsWith('multi_agent_')`。
+  - `getMessageVisibility()`：看 `metadata.visibility`。两者都必须正确，消息才能走多智能体渲染分支。任一错都会 fallback 到通知渲染。
+- 多智能体消息不显示新的 assistant 回复头部（Astrion/工作时间），即 `metadata.starts_work=false`。但前端通过 `has_running_multi_agent` 在 `task_complete` 中单独处理恢复轮询。
+- 子智能体进度弹窗：输出与工具按真实时间线混排，默认 3 行，过长用省略号或内部滚动；颜色走 `--text-primary` 等语义 token。
+- 全局工具规范统一适用于多智能体权限：UI 不能引入 `compact` 以外的 fallback 样式习惯复制到多智能体渲染。
+
+### 11.6 工具结果格式化与前端渲染位置
+
+新增多智能体工具时，必须同步补齐「后端结果格式化」和「前端结构化渲染」，否则前端会 fallback 到原始 JSON 或空白。
+
+**后端 formatter（主智能体工具）**
+- 实现位置：`utils/tool_result_formatter/agent_context.py`
+- 注册位置：`utils/tool_result_formatter/dispatch.py` 的 `TOOL_FORMATTERS`
+- 处理入口：所有主智能体工具执行结果，最终由 `format_tool_result_for_context()` 转换为自然语言摘要，写入对话历史。
+
+**后端 formatter（子智能体通信工具）**
+- 实现位置：`modules/sub_agent/toolkit.py` 的 `_format_tool_result()`
+- 覆盖工具：`ask_master` / `ask_other_agent` / `answer_other_agent` / `list_active_sub_agents`
+- 处理入口：子智能体 tool call 结果回填到子对话上下文前。
+
+**前端 renderer（主路径）**
+- 实现位置：`static/src/components/chat/actions/toolRenderers.ts` 的 `renderEnhancedToolResult()`
+- 调用方：
+  - `static/src/components/chat/MinimalBlocks.vue`
+  - `static/src/components/chat/StackedBlocks.vue`
+- 注意：这两个视图已移除 `enhanced_tool_display` 开关判断，**所有工具块都强制走结构化渲染**，不再显示原始 JSON。
+
+**前端 renderer（备用路径）**
+- 实现位置：`static/src/components/chat/actions/ToolAction.vue` 的 `renderToolResult()`
+- 调用方：`static/src/components/chat/ChatArea.vue`
+- 同样已移除原始 JSON fallback，仅作为 ChatArea 独立工具块渲染的备用。
+
+**新增工具 checklist**
+1. `modules/multi_agent/tools.py` 定义工具签名。
+2. `core/main_terminal_parts/tools_execution.py` 实现工具 handler 并返回标准 dict（`success` + 业务字段 + 可选 `error`）。
+3. `utils/tool_result_formatter/agent_context.py` 新增 `_format_<tool_name>()`，`dispatch.py` 注册。
+4. `static/src/components/chat/actions/toolRenderers.ts` 新增对应 `render<PascalCaseToolName>()` 并在 `renderEnhancedToolResult()` 中分发。
+5. 如果是子智能体通信工具，同步在 `modules/sub_agent/toolkit.py` 的 `_format_tool_result()` 中补 formatter。
+
+### 11.7 调试机制
+
+- 调试日志统一走 `modules/multi_agent/debug_logger.py` 的 `ma_debug()` 函数，写入 `~/.astrion/astrion/host/logs/multi_agent_loop.log`。
+- 关键状态转换点必须打 `ma_debug`，便于复现 bug：
+  - `handle_task_with_sender_start`（含 `pending_master_messages_count`）
+  - `state_push_master_message` （交出 `queue_len_before`）
+  - `poll_ma_tick` （每 0.5s 一次，包含 `instance_count` / `statuses` / `pending_count` / `main_active` 的完整状态快照）
+  - `dispatch_ma_idle_enter` / `dispatch_ma_idle_before_create_task` / `dispatch_ma_idle_task_created` / `dispatch_ma_idle_sender_user_message` / `dispatch_ma_idle_exit_ok`
+  - `create_chat_task` 异常 / `provide_answer` 跨循环回写
+  - `runtime_injected` 字段标记（metadata 里能区分多智能体 inline / idle / ask插入路径）
+
+### 11.8 已知坑
+
+- 多智能体模式下根本不 `emit` `sub_agent_waiting` 事件，避免前端进入「等待后台子智能体」的输入区阻塞态。
+- `_announced_sub_agent_tasks` / `notified` 等标记仅适用于传统后台子智能体任务，多智能体任务不走这条通知路径。
+- 多智能体任务的 `output.json` 中 `status` 在子智能体自然进入 idle 时会被写为 `"idle"`；在 `_check_task_status` 中由 `_check_task_status_keep_alive` 跳过防止错误判定为 `failed`。
+- 传统后台通知池 `_collect_pending_completion_notices` 在 `task.get("multi_agent_mode")` 为真时跳过该 task；多智能体派出走独立的 `poll_multi_agent_notifications` 路径，不当混用。
+- `_has_pending_completion_work` 主动排除 `multi_agent_mode=True` 的任务；两者永远独立。
+
+### 11.9 对话切换与状态保留
+
+- 切换会话不清理 `_running_tasks` 和 `_sub_agent_instances`。`SubAgentManager` 的全局 tasks 字典按 `task_id` 保持，多智能体状态由 `conversation_id` 在 `get_multi_agent_state` 中查。
+- 子智能体对话存在 `~/.astrion/astrion/host/host/data/sub_agents/`。重启后走 `manager.restore_sub_agent` 恢复实例引用。
+- `MultiAgentState` 实例在 Manager 上常驻（dict by `conversation_id`）；进程重启走 `from_snapshot` 恢复。
+
+---
+
+注：本节按「现有架构 + 多智能体分支」方案描述，与项目记忆 `multi_agent_mode_design` 同步；如两者冲突以代码为准并同步修订本节。

agentskills/sub-agent-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sub-agent-guide
-description: 子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体仅用于并行处理独立的“非代码编写”任务（如项目初步探索、网络搜索与信息收集、程序测试执行）。关键限制：子智能体之间无法通信，看不到主对话历史。严格禁止将子智能体用于项目代码编写、代码修改、重构或实现功能。
+description: 子智能体使用指南。创建子智能体之前必须阅读此技能。子智能体仅用于并行处理独立的“非代码编写”任务（如项目初步探索、网络搜索与信息收集、程序测试执行）。关键限制：子智能体之间无法通信，看不到主对话历史。严格禁止将子智能体用于项目代码编写、代码修改、重构或实现功能。**如果运行模式为多智能体模式，禁止阅读并参考该 skill。**
 ---
 
 # 子智能体使用指南

config/__init__.py

@@ -16,11 +16,13 @@ def _load_dotenv():
     import sys
     pre_existing_keys = set(os.environ.keys())
 
-    # 1) 仓库根 .env（开发便利，不覆盖已有环境变量）
+    # 1) 仓库根 .env（开发便利，不覆盖已有的环境变量，但 ASTRION_DATA_ROOT
+    #    作为项目数据根目录必须优先以 .env 为准，避免外部 shell 误指到 clone）
     if getattr(sys, 'frozen', False):
         env_path = Path.home() / '.astrion' / 'astrion' / '.env'
     else:
         env_path = Path(__file__).resolve().parents[1] / '.env'
+    env_from_file: dict = {}
     if env_path.exists():
         try:
             for raw_line in env_path.read_text(encoding="utf-8").splitlines():
@@ -34,11 +36,14 @@ def _load_dotenv():
                 value = value.strip().strip('"').strip("'")
                 if not key:
                     continue
+                env_from_file[key] = value
                 if key in pre_existing_keys:
                     continue
                 os.environ[key] = value
         except Exception:
             pass
+    if "ASTRION_DATA_ROOT" in env_from_file:
+        os.environ["ASTRION_DATA_ROOT"] = str(Path(env_from_file["ASTRION_DATA_ROOT"]).expanduser())
 
     # 2) settings.json（数据根下的统一配置）
     data_root = os.environ.get("ASTRION_DATA_ROOT", str(Path.home() / ".astrion" / "astrion"))

config/paths.py

@@ -161,6 +161,12 @@ HOST_PROJECT_PATH = _resolve_repo_path(os.environ.get("HOST_PROJECT_PATH", ""),
 # ── 源码树内的配置与资源（不随运行态根目录迁移）──
 PROMPTS_DIR = _resolve_repo_path(os.environ.get("PROMPTS_DIR", ""), "./prompts")
 AGENT_SKILLS_DIR = _resolve_repo_path(os.environ.get("AGENT_SKILLS_DIR", ""), "./agentskills")
+# 多智能体预设角色目录（源码树内，随版本分发）
+PRESET_ROLES_DIR = _resolve_repo_path(os.environ.get("PRESET_ROLES_DIR", ""), "./multi_agent_roles")
+# 运行态预设/自定义角色目录（host 模式：预设+自定义同目录；web 模式：仅预设）
+CUSTOM_ROLES_DIR = str(Path(RUNTIME_ROOT) / _MODE / "mutiagents" / "agents")
+# web 模式预设角色目录（web 模式下使用，host 模式下不用）
+WEB_PRESET_ROLES_DIR = str(Path(RUNTIME_ROOT) / "web" / "mutiagents" / "agents")
 WORKSPACE_SKILLS_DIRNAME = ".astrion/skills"
 WORKSPACE_MEMORY_DIRNAME = ".astrion/memory"
 WORKSPACE_REVIEW_DIRNAME = ".astrion/review"
@@ -198,6 +204,9 @@ __all__ = [
     "ADMIN_POLICY_FILE",
     "API_USER_SPACE_DIR",
     "CUSTOM_SKILLS_DIR",
+    "PRESET_ROLES_DIR",
+    "CUSTOM_ROLES_DIR",
+    "WEB_PRESET_ROLES_DIR",
     "API_USERS_DB_FILE",
     "API_TOKENS_FILE",
     "API_USAGE_FILE",

core/main_terminal.py

@@ -374,7 +374,8 @@ class MainTerminal(MainTerminalCommandMixin, MainTerminalContextMixin, MainTermi
             if not cm or not conv_id:
                 return
             try:
-                cm.conversation_manager.update_conversation_metadata(conv_id, updates)
+                target_manager = cm._get_conversation_manager_for_id(conv_id) if hasattr(cm, "_get_conversation_manager_for_id") else cm.conversation_manager
+                target_manager.update_conversation_metadata(conv_id, updates)
                 if isinstance(getattr(cm, "conversation_metadata", None), dict):
                     cm.conversation_metadata.update(updates)
             except Exception:

core/main_terminal_parts/context/messages.py

@@ -48,6 +48,7 @@ from modules.terminal_manager import TerminalManager
 from modules.todo_manager import TodoManager
 from modules.sub_agent import SubAgentManager
 from modules.webpage_extractor import extract_webpage_content, tavily_extract
+from modules.multi_agent.prompts import build_available_agents_prompt
 from modules.ocr_client import OCRClient
 from modules.easter_egg_manager import EasterEggManager
 from modules.personalization_manager import (
@@ -116,15 +117,29 @@ class MessagesMixin:
             model_key = getattr(self, "model_key", None)
             prompt_replacements = get_model_prompt_replacements(model_key)
 
+            is_multi_agent_mode = bool(getattr(self, "multi_agent_mode", False))
+
             def _build_main_system_prompt() -> str:
+                if is_multi_agent_mode:
+                    # 多智能体模式下主 prompt 使用 Team Leader 专属模板
+                    try:
+                        from modules.multi_agent.prompts import _load_template
+                        return _load_template("master")
+                    except Exception as exc:
+                        logger.warning(f"[messages] 加载多智能体主 prompt 失败: {exc}")
                 system_prompt_template = self.load_prompt(prompt_name)
                 # main_system.txt / main_system_vl.txt 仅使用 {model_description}
                 return system_prompt_template.format(
                     model_description=prompt_replacements.get("model_description", "")
                 )
 
+            main_system_frozen_key = (
+                "frozen_main_system_prompt_multi_agent"
+                if is_multi_agent_mode
+                else "frozen_main_system_prompt"
+            )
             system_prompt = self._get_or_init_frozen_prompt(
-                "frozen_main_system_prompt",
+                main_system_frozen_key,
                 _build_main_system_prompt,
             )
 
@@ -224,12 +239,19 @@ class MessagesMixin:
                     return agents_md_template.replace("{{AGENTS_MD_CONTENT}}", agents_md_content)
                 return f"【AGENTS.md 项目规范】\n\n{agents_md_content}\n\n---\n请注意：以上规范来自工作区根目录的 AGENTS.md 文件，若有冲突请以 AGENTS.md 为准。"
 
-            agents_md_text = self._get_or_init_frozen_prompt(
-                "frozen_agents_md_prompt",
-                _build_agents_md_prompt,
+            # AGENTS.md 注入开关可能变化，只在开启时生成并缓存，避免关闭时把空字符串冻住
+            agents_md_inject_enabled = (
+                bool(personalization_config.get("agents_md_auto_inject", False))
+                if isinstance(personalization_config, dict)
+                else False
             )
-            if agents_md_text:
-                messages.append({"role": "system", "content": agents_md_text})
+            if agents_md_inject_enabled:
+                agents_md_text = self._get_or_init_frozen_prompt(
+                    "frozen_agents_md_prompt",
+                    _build_agents_md_prompt,
+                )
+                if agents_md_text:
+                    messages.append({"role": "system", "content": agents_md_text})
 
             # skills 列表
             skills_catalog = get_skills_catalog(private_dir=infer_private_skills_dir(self.data_dir))
@@ -278,6 +300,18 @@ class MessagesMixin:
                 "frozen_disabled_tools_prompt",
                 lambda: self._format_disabled_tool_notice() or "",
             )
+
+            # 多智能体模式额外提示词：可用的子智能体角色（动态 prompt，第一个用户消息后冻结）
+            if getattr(self, "multi_agent_mode", False):
+                try:
+                    available_agents_prompt = self._get_or_init_frozen_prompt(
+                        "frozen_available_agents_prompt",
+                        lambda: build_available_agents_prompt() or "",
+                    )
+                    if available_agents_prompt:
+                        messages.append({"role": "system", "content": available_agents_prompt})
+                except Exception as exc:
+                    logger.warning(f"[messages] 注入可用子智能体 prompt 失败: {exc}")
             if disabled_notice:
                 messages.append({
                     "role": "system",
@@ -364,6 +398,14 @@ class MessagesMixin:
                     # 调试：记录所有 system 消息
                     if conv["role"] == "system":
                         logger.info(f"[DEBUG build_messages] 添加 system 消息: content前50字={conv['content'][:50]}")
+                    # 调试：记录多智能体子智能体输出消息是否进入上下文
+                    if metadata.get("multi_agent_message"):
+                        logger.info(
+                            f"[DEBUG build_messages] 添加多智能体子智能体消息到上下文: "
+                            f"role={conv['role']}, subtype={metadata.get('multi_agent_subtype')}, "
+                            f"display_name={metadata.get('multi_agent_display_name')}, "
+                            f"content前80字={str(conv.get('content', ''))[:80]}"
+                        )
                     messages.append({
                         "role": conv["role"],
                         "content": content_payload

core/main_terminal_parts/context/mode.py

@@ -221,7 +221,12 @@ class ModeMixin:
             conv_id = getattr(cm, "current_conversation_id", None) if cm else None
             if cm and conv_id:
                 try:
-                    cm.conversation_manager.update_conversation_metadata(conv_id, {key: built})
+                    target_manager = (
+                        cm._get_conversation_manager_for_id(conv_id)
+                        if hasattr(cm, "_get_conversation_manager_for_id")
+                        else cm.conversation_manager
+                    )
+                    target_manager.update_conversation_metadata(conv_id, {key: built})
                     if isinstance(cm.conversation_metadata, dict):
                         cm.conversation_metadata[key] = built
                 except Exception:

core/main_terminal_parts/tools_definition/agent_tools.py

@@ -91,6 +91,14 @@ DISABLE_LENGTH_CHECK = True
 
 class ToolsDefinitionAgentToolsMixin:
     def _build_agent_tools(self) -> List[Dict]:
+        # 多智能体模式下，主智能体不再使用旧版的 4 个子智能体工具
+        # 而是用 modules/multi_agent/tools.build_master_tools_for_conversation() 返回的新集
+        if getattr(self, "multi_agent_mode", False):
+            try:
+                from modules.multi_agent.tools import build_master_tools_for_conversation
+                return build_master_tools_for_conversation()
+            except Exception as exc:
+                logger.warning(f"[tools] 加载多智能体工具失败，回退旧版: {exc}")
         return [
                                     {
                         "type": "function",

core/main_terminal_parts/tools_definition/core_tools.py

@@ -90,38 +90,74 @@ DISABLE_LENGTH_CHECK = True
 
 
 class ToolsDefinitionCoreToolsMixin:
+
+    def _build_sleep_tool_definition(self) -> Dict:
+        """根据运行模式构建 sleep 工具定义。
+
+        多智能体模式下子智能体不会调用 finish_task 结束，因此不提供
+        wait_sub_agent_ids 参数；常规模式保留完整功能。
+        """
+        is_multi_agent = getattr(self, "multi_agent_mode", False)
+        if is_multi_agent:
+            return {
+                "type": "function",
+                "function": {
+                    "name": "sleep",
+                    "description": "等待工具。两种模式二选一：1) seconds：短暂延迟；2) wait_runcommand_id：等待指定后台 run_command 结束并直接返回结果。若同时提供多个等待参数会报错。",
+                    "parameters": {
+                        "type": "object",
+                        "properties": self._inject_intent({
+                            "seconds": {
+                                "type": "number",
+                                "description": "等待的秒数，可以是小数（如0.2秒）。建议范围：0.1-10秒"
+                            },
+                            "wait_runcommand_id": {
+                                "type": "string",
+                                "description": "等待指定后台 run_command 的 command_id 结束后返回。"
+                            },
+                            "reason": {
+                                "type": "string",
+                                "description": "等待的原因说明（可选）"
+                            }
+                        }),
+                        "required": []
+                    }
+                }
+            }
+        return {
+            "type": "function",
+            "function": {
+                "name": "sleep",
+                "description": "等待工具。三种模式三选一：1) seconds：短暂延迟；2) wait_sub_agent_ids：等待指定子智能体全部结束并直接返回结果；3) wait_runcommand_id：等待指定后台 run_command 结束并直接返回结果。若同时提供多个等待参数会报错。",
+                "parameters": {
+                    "type": "object",
+                    "properties": self._inject_intent({
+                        "seconds": {
+                            "type": "number",
+                            "description": "等待的秒数，可以是小数（如0.2秒）。建议范围：0.1-10秒"
+                        },
+                        "wait_sub_agent_ids": {
+                            "type": "array",
+                            "items": {"type": "integer"},
+                            "description": "等待这些子智能体全部结束后返回（可提供一个或多个编号）。"
+                        },
+                        "wait_runcommand_id": {
+                            "type": "string",
+                            "description": "等待指定后台 run_command 的 command_id 结束后返回。"
+                        },
+                        "reason": {
+                            "type": "string",
+                            "description": "等待的原因说明（可选）"
+                        }
+                    }),
+                    "required": []
+                }
+            }
+        }
+
     def _build_core_tools(self) -> List[Dict]:
         return [
-                        	            {
-        	                "type": "function",
-	                "function": {
-	                    "name": "sleep",
-	                    "description": "等待工具。三种模式三选一：1) seconds：短暂延迟；2) wait_sub_agent_ids：等待指定子智能体全部结束并直接返回结果；3) wait_runcommand_id：等待指定后台 run_command 结束并直接返回结果。若同时提供多个等待参数会报错。",
-	                    "parameters": {
-	                        "type": "object",
-	                        "properties": self._inject_intent({
-	                            "seconds": {
-	                                "type": "number",
-	                                "description": "等待的秒数，可以是小数（如0.2秒）。建议范围：0.1-10秒"
-	                            },
-	                            "wait_sub_agent_ids": {
-	                                "type": "array",
-	                                "items": {"type": "integer"},
-	                                "description": "等待这些子智能体全部结束后返回（可提供一个或多个编号）。"
-	                            },
-	                            "wait_runcommand_id": {
-	                                "type": "string",
-	                                "description": "等待指定后台 run_command 的 command_id 结束后返回。"
-	                            },
-	                            "reason": {
-	                                "type": "string",
-	                                "description": "等待的原因说明（可选）"
-	                            }
-                                }),
-                                "required": []
-                            }
-                        }
-                    },
+                        	                        self._build_sleep_tool_definition(),
 
                                     {
                         "type": "function",

core/main_terminal_parts/tools_execution.py

@@ -2,6 +2,7 @@ import asyncio
 import json
 import os
 import time
+import uuid
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
@@ -100,6 +101,7 @@ from utils.api_client import DeepSeekClient
 from utils.context_manager import ContextManager
 from utils.tool_result_formatter import format_tool_result_for_context
 from utils.logger import setup_logger
+from modules.multi_agent.debug_logger import ma_debug
 from config.model_profiles import (
     get_model_profile,
     get_model_prompt_replacements,
@@ -1097,7 +1099,12 @@ class MainTerminalToolsExecutionMixin:
                                 "error": "sleep 的等待参数互斥：seconds / wait_sub_agent_ids / wait_runcommand_id 只能提供一个"
                             }
                         elif wait_sub_agent_ids:
-                            if not isinstance(wait_sub_agent_ids, list) or not wait_sub_agent_ids:
+                            if getattr(self, "multi_agent_mode", False):
+                                result = {
+                                    "success": False,
+                                    "error": "多智能体模式下 sleep 工具不支持 wait_sub_agent_ids。请通过 list_active_sub_agents / get_sub_agent_status 查看状态，或直接向子智能体发送消息。"
+                                }
+                            elif not isinstance(wait_sub_agent_ids, list) or not wait_sub_agent_ids:
                                 result = {"success": False, "error": "wait_sub_agent_ids 必须是非空数组"}
                             else:
                                 normalized_ids = []
@@ -1728,66 +1735,313 @@ class MainTerminalToolsExecutionMixin:
                         )
 
                     elif tool_name == "create_sub_agent":
-                        result = self.sub_agent_manager.create_sub_agent(
-                            agent_id=arguments.get("agent_id"),
-                            summary=arguments.get("summary", ""),
-                            task=arguments.get("task", ""),
-                            deliverables_dir=arguments.get("deliverables_dir", ""),
-                            run_in_background=arguments.get("run_in_background", False),
-                            timeout_seconds=arguments.get("timeout_seconds"),
-                            thinking_mode=arguments.get("thinking_mode"),
-                            conversation_id=self.context_manager.current_conversation_id
-                        )
+                        # 多智能体模式：create_sub_agent 走新签名，需要 role_id/display_name/multi_agent_mode
+                        if getattr(self, "multi_agent_mode", False):
+                            role_id = arguments.get("role_id")
+                            if not role_id:
+                                result = {"success": False, "error": "多智能体模式下 create_sub_agent 必须指定 role_id"}
+                            elif arguments.get("deliverables_dir"):
+                                result = {"success": False, "error": "多智能体模式下不支持交付目录参数"}
+                            else:
+                                try:
+                                    from modules.multi_agent.role_store import load_preset_role, infer_custom_roles_dir
+                                    from modules.multi_agent.prompts import build_multi_agent_sub_agent_prompt
+                                    _data_dir = str(getattr(self, "data_dir", ""))
+                                    _custom_dir = infer_custom_roles_dir(_data_dir)
+                                    # host模式下 custom_dir 就是 runtime_dir；web模式下 custom_dir 是用户个人目录
+                                    _is_web = '/web/users/' in _data_dir
+                                    _runtime_dir = None if _is_web else _custom_dir
+                                    role = load_preset_role(role_id, runtime_dir=_runtime_dir, custom_dir=_custom_dir)
+                                    if not role:
+                                        result = {"success": False, "error": f"角色不存在: {role_id}"}
+                                    else:
+                                        conv_id = self.context_manager.current_conversation_id
+                                        multi_agent_state = self.sub_agent_manager.get_or_create_multi_agent_state(conv_id)
+                                        # 分配 agent_id：如果未传入则自动递增
+                                        agent_id = arguments.get("agent_id")
+                                        if not agent_id:
+                                            agent_id = multi_agent_state.next_agent_id_for_role(role_id)
+                                        # 构造显示名
+                                        display_name = role.display_name(int(agent_id))
+                                        # 构造多智能体版系统提示词（含动态上下文注入）
+                                        workspace_path = str(getattr(self, "project_path", ""))
+                                        data_dir = str(getattr(self, "data_dir", ""))
+                                        # 获取当前沙箱模式
+                                        sandbox_mode = ""
+                                        try:
+                                            if hasattr(self, "get_execution_mode_state"):
+                                                state = self.get_execution_mode_state() or {}
+                                                sandbox_mode = str(state.get("mode") or "")
+                                        except Exception:
+                                            pass
+                                        system_prompt = build_multi_agent_sub_agent_prompt(
+                                            role.body_prompt, display_name, workspace_path,
+                                            data_dir=data_dir,
+                                            sandbox_mode=sandbox_mode,
+                                        )
+                                        # 构造 task_message（作为 Team Leader 的任务发布）
+                                        from modules.multi_agent.state import build_master_dispatch_text
+                                        task_message = build_master_dispatch_text(arguments.get("task", ""))
+                                        summary_text = (arguments.get("summary") or f"{role.name}作业")[:80]
+                                        thinking_mode = arguments.get("thinking_mode") or role.thinking_mode or "fast"
+                                        # 读取子智能体压缩阈值配置
+                                        _compress_threshold = 150_000
+                                        try:
+                                            from modules.personalization_manager import load_personalization_config
+                                            _prefs = load_personalization_config(data_dir) or {}
+                                            _compress_threshold = int(_prefs.get("sub_agent_compress_threshold_tokens", 150_000))
+                                        except Exception:
+                                            pass
+                                        # 走原行 发事件创建（避免后期重建提供重复工能重费，直接使用 multi_agent_mode=True 调用）
+                                        result = self.sub_agent_manager.create_sub_agent(
+                                            agent_id=int(agent_id),
+                                            summary=summary_text,
+                                            task=arguments.get("task", ""),
+                                            run_in_background=False,
+                                            conversation_id=conv_id,
+                                            model_key=role.model_key,
+                                            thinking_mode=thinking_mode,
+                                            multi_agent_mode=True,
+                                            role_id=role_id,
+                                            display_name=display_name,
+                                            system_prompt=system_prompt,
+                                            task_message=task_message,
+                                            compress_threshold_tokens=_compress_threshold,
+                                        )
+                                        # 在多智能体模式下，子智能体是团队协作成员，不是传统后台任务。
+                                        # run_in_background=False 避免触发后台完成通知轮询，保持主对话输入区可用。
+                                except Exception as exc:
+                                    logger.exception("[multi_agent] create_sub_agent failed")
+                                    result = {"success": False, "error": str(exc)}
+                        else:
+                            result = self.sub_agent_manager.create_sub_agent(
+                                agent_id=arguments.get("agent_id"),
+                                summary=arguments.get("summary", ""),
+                                task=arguments.get("task", ""),
+                                deliverables_dir=arguments.get("deliverables_dir", ""),
+                                run_in_background=arguments.get("run_in_background", False),
+                                timeout_seconds=arguments.get("timeout_seconds"),
+                                thinking_mode=arguments.get("thinking_mode"),
+                                conversation_id=self.context_manager.current_conversation_id
+                            )
 
-                        # 如果不是后台运行，阻塞等待完成
-                        if not arguments.get("run_in_background", False) and result.get("success"):
-                            task_id = result.get("task_id")
-                            wait_result = self.sub_agent_manager.wait_for_completion(
-                                task_id=task_id,
-                                timeout_seconds=arguments.get("timeout_seconds")
-                            )
-                            # 合并结果：保留创建元数据，使用执行结果作为主体展示，
-                            # 避免 wait_result 里的 success=False + 旧 message 导致
-                            # 「create_sub_agent 失败：子智能体 X 已创建」的误导性文案。
-                            creation_meta = {
-                                "agent_id": result.get("agent_id"),
-                                "task_id": result.get("task_id"),
-                                "deliverables_dir": result.get("deliverables_dir"),
-                                "run_in_background": False,
-                            }
-                            execution_message = (
-                                wait_result.get("message")
-                                or wait_result.get("system_message")
-                                or result.get("message")
-                            )
-                            result = {
-                                **result,
-                                **wait_result,
-                                **creation_meta,
-                                "message": execution_message,
-                            }
-                            # 阻塞式执行不需要额外插入 system 消息
-                            result.pop("system_message", None)
-                            # 标记已通知，避免后续轮询再插入 system 消息
-                            try:
-                                task = self.sub_agent_manager.tasks.get(task_id)
-                                if isinstance(task, dict):
-                                    task["notified"] = True
-                                    task["updated_at"] = time.time()
-                                    self.sub_agent_manager._save_state()
-                            except Exception:
-                                pass
+                            # 如果不是后台运行，阻塞等待完成
+                            if not arguments.get("run_in_background", False) and result.get("success"):
+                                task_id = result.get("task_id")
+                                wait_result = self.sub_agent_manager.wait_for_completion(
+                                    task_id=task_id,
+                                    timeout_seconds=arguments.get("timeout_seconds")
+                                )
+                                # 合并结果：保留创建元数据，使用执行结果作为主体展示，
+                                # 避免 wait_result 里的 success=False + 旧 message 导致
+                                # 「create_sub_agent 失败：子智能体 X 已创建」的误导性文案。
+                                creation_meta = {
+                                    "agent_id": result.get("agent_id"),
+                                    "task_id": result.get("task_id"),
+                                    "deliverables_dir": result.get("deliverables_dir"),
+                                    "run_in_background": False,
+                                }
+                                execution_message = (
+                                    wait_result.get("message")
+                                    or wait_result.get("system_message")
+                                    or result.get("message")
+                                )
+                                result = {
+                                    **result,
+                                    **wait_result,
+                                    **creation_meta,
+                                    "message": execution_message,
+                                }
+                                # 阻塞式执行不需要额外插入 system 消息
+                                result.pop("system_message", None)
+                                # 标记已通知，避免后续轮询再插入 system 消息
+                                try:
+                                    task = self.sub_agent_manager.tasks.get(task_id)
+                                    if isinstance(task, dict):
+                                        task["notified"] = True
+                                        task["updated_at"] = time.time()
+                                        self.sub_agent_manager._save_state()
+                                except Exception:
+                                    pass
 
                     elif tool_name == "terminate_sub_agent":
                         result = self.sub_agent_manager.terminate_sub_agent(
                             agent_id=arguments.get("agent_id")
                         )
+                        # 多智能体模式：同步状态到 MultiAgentState
+                        if getattr(self, "multi_agent_mode", False):
+                            try:
+                                conv_id = self.context_manager.current_conversation_id
+                                state = self.sub_agent_manager.get_multi_agent_state(conv_id)
+                                if state:
+                                    state.mark_status(int(arguments.get("agent_id")), "terminated")
+                            except Exception:
+                                pass
 
                     elif tool_name == "get_sub_agent_status":
                         result = self.sub_agent_manager.get_sub_agent_status(
                             agent_ids=arguments.get("agent_ids", [])
                         )
 
+                    # 多智能体模式专属工具：send_message_to_sub_agent / ask_sub_agent / answer_sub_agent_question / create_custom_agent / list_agents / list_active_sub_agents
+                    elif tool_name == "send_message_to_sub_agent":
+                        if not getattr(self, "multi_agent_mode", False):
+                            result = {"success": False, "error": "该工具仅在多智能体模式下可用"}
+                        else:
+                            try:
+                                from modules.multi_agent.state import build_master_message_to_sub_agent
+                                agent_id = int(arguments.get("agent_id", 0))
+                                message = arguments.get("message", "")
+                                conv_id = self.context_manager.current_conversation_id
+                                state = self.sub_agent_manager.get_multi_agent_state(conv_id)
+                                if not state:
+                                    result = {"success": False, "error": "多智能体状态未就绪"}
+                                else:
+                                    # 构造消息文本并插入子对话
+                                    text = build_master_message_to_sub_agent(message)
+                                    ma_debug(
+                                        "tool_send_message_to_sub_agent",
+                                        agent_id=agent_id,
+                                        raw_message=str(message)[:500],
+                                        wrapped_message_preview=text[:500],
+                                        conversation_id=conv_id,
+                                    )
+                                    ok = self.sub_agent_manager.inject_message_to_sub_agent(agent_id, text)
+                                    if not ok:
+                                        result = {"success": False, "error": f"子智能体 {agent_id} 不存在或已结束"}
+                                    else:
+                                        result = {"success": True, "agent_id": agent_id}
+                                    ma_debug(
+                                        "tool_send_message_to_sub_agent_result",
+                                        agent_id=agent_id,
+                                        conversation_id=conv_id,
+                                        ok=ok,
+                                        result=result,
+                                    )
+                            except Exception as exc:
+                                logger.exception("[multi_agent] send_message_to_sub_agent failed")
+                                result = {"success": False, "error": str(exc)}
+
+                    elif tool_name == "ask_sub_agent":
+                        if not getattr(self, "multi_agent_mode", False):
+                            result = {"success": False, "error": "该工具仅在多智能体模式下可用"}
+                        else:
+                            try:
+                                from modules.multi_agent.state import format_multi_agent_message, TYPE_ASK
+                                agent_id = int(arguments.get("agent_id", 0))
+                                question = arguments.get("question", "")
+                                timeout = int(arguments.get("timeout_seconds", 600))
+                                conv_id = self.context_manager.current_conversation_id
+                                state = self.sub_agent_manager.get_multi_agent_state(conv_id)
+                                if not state:
+                                    result = {"success": False, "error": "多智能体状态未就绪"}
+                                else:
+                                    question_id = f"ask_sub_agent_{int(time.time() * 1000)}_{uuid.uuid4().hex[:6]}"
+                                    # 构造提问并插入子对话（子智能体下一轮 assistant 输出作为回答返回到工具结果）
+                                    text = format_multi_agent_message(
+                                        display_name="Team Leader",
+                                        msg_type=TYPE_ASK,
+                                        content=question,
+                                        msg_id=question_id,
+                                        target=state.get_instance(agent_id).display_name if state.get_instance(agent_id) else f"Agent_{agent_id}",
+                                    )
+                                    ma_debug(
+                                        "tool_ask_sub_agent",
+                                        agent_id=agent_id,
+                                        question=str(question)[:500],
+                                        question_id=question_id,
+                                        wrapped_message_preview=text[:500],
+                                        conversation_id=conv_id,
+                                    )
+                                    ok = self.sub_agent_manager.inject_message_to_sub_agent(agent_id, text)
+                                    if not ok:
+                                        result = {"success": False, "error": f"子智能体 {agent_id} 不存在"}
+                                    else:
+                                        # 阻塞等待子智能体下一轮输出作为回答
+                                        answer = await state.wait_for_answer(
+                                            question_id=question_id,
+                                            agent_id=agent_id,
+                                            timeout=timeout,
+                                        )
+                                        result = {"success": True, "answer": answer}
+                            except asyncio.TimeoutError:
+                                result = {"success": False, "error": "等待子智能体回答超时"}
+                            except Exception as exc:
+                                result = {"success": False, "error": str(exc)}
+
+                    elif tool_name == "answer_sub_agent_question":
+                        if not getattr(self, "multi_agent_mode", False):
+                            result = {"success": False, "error": "该工具仅在多智能体模式下可用"}
+                        else:
+                            try:
+                                question_id = arguments.get("question_id", "")
+                                answer = arguments.get("answer", "")
+                                conv_id = self.context_manager.current_conversation_id
+                                state = self.sub_agent_manager.get_multi_agent_state(conv_id)
+                                ma_debug(
+                                    "tool_answer_sub_agent_question",
+                                    question_id=question_id,
+                                    answer_preview=str(answer)[:500],
+                                    conversation_id=conv_id,
+                                )
+                                if not state:
+                                    result = {"success": False, "error": "多智能体状态未就绪"}
+                                else:
+                                    ok = state.provide_answer(question_id, answer)
+                                    result = {"success": bool(ok), "question_id": question_id}
+                            except Exception as exc:
+                                result = {"success": False, "error": str(exc)}
+
+                    elif tool_name == "create_custom_agent":
+                        try:
+                            from modules.multi_agent.role_store import RoleConfig, save_custom_role, list_roles
+                            role_id = arguments.get("role_id", "").strip()
+                            name = arguments.get("name", "").strip()
+                            body_prompt = arguments.get("body_prompt", "").strip()
+                            description = arguments.get("description", "").strip()
+                            thinking_mode_arg = arguments.get("thinking_mode", "fast")
+                            model_key_arg = arguments.get("model_key", "").strip() or None
+                            if not role_id or not name or not body_prompt:
+                                result = {"success": False, "error": "role_id/name/body_prompt 必填"}
+                            else:
+                                _data_dir = str(getattr(self, "data_dir", ""))
+                                from modules.multi_agent.role_store import infer_custom_roles_dir
+                                _custom_dir = infer_custom_roles_dir(_data_dir)
+                                _is_web = '/web/users/' in _data_dir
+                                _runtime_dir = None if _is_web else _custom_dir
+                                existing_ids = {r.role_id for r in list_roles(runtime_dir=_runtime_dir, custom_dir=_custom_dir)}
+                                if role_id in existing_ids:
+                                    result = {"success": False, "error": f"角色 {role_id} 已存在"}
+                                else:
+                                    role = RoleConfig(role_id=role_id, name=name, description=description, body_prompt=body_prompt, thinking_mode=thinking_mode_arg, model_key=model_key_arg, is_custom=True)
+                                    f = save_custom_role(role, custom_dir=_custom_dir)
+                                    result = {"success": True, "role_id": role_id, "file": str(f)}
+                        except Exception as exc:
+                            result = {"success": False, "error": str(exc)}
+
+                    elif tool_name == "list_agents":
+                        try:
+                            from modules.multi_agent.role_store import list_roles, infer_custom_roles_dir
+                            _data_dir = str(getattr(self, "data_dir", ""))
+                            _custom_dir = infer_custom_roles_dir(_data_dir)
+                            _is_web = '/web/users/' in _data_dir
+                            _runtime_dir = None if _is_web else _custom_dir
+                            roles = list_roles(runtime_dir=_runtime_dir, custom_dir=_custom_dir)
+                            result = {"success": True, "roles": [r.to_dict() for r in roles]}
+                        except Exception as exc:
+                            result = {"success": False, "error": str(exc)}
+
+                    elif tool_name == "list_active_sub_agents":
+                        try:
+                            conv_id = self.context_manager.current_conversation_id
+                            state = self.sub_agent_manager.get_multi_agent_state(conv_id)
+                            if not state:
+                                result = {"success": True, "agents": []}
+                            else:
+                                result = {"success": True, "agents": [a.to_dict() for a in state.list_all()]}
+                        except Exception as exc:
+                            result = {"success": False, "error": str(exc)}
+
                     elif tool_name == "trigger_easter_egg":
                         result = self.easter_egg_manager.trigger_effect(arguments.get("effect"))
 

core/main_terminal_parts/tools_policy.py

@@ -218,8 +218,7 @@ class MainTerminalToolsPolicyMixin:
                 conv_id = conversation_id or getattr(getattr(self, "context_manager", None), "current_conversation_id", None)
                 if conv_id and getattr(self, "context_manager", None):
                     try:
-                        self.context_manager.conversation_manager.update_conversation_metadata(
-                            conv_id,
+                        self.context_manager._get_conversation_manager_for_id(conv_id).update_conversation_metadata(conv_id,
                             {"permission_mode": normalized},
                         )
                         if self.context_manager.current_conversation_id == conv_id:

core/web_terminal.py

@@ -3,7 +3,7 @@
 import json
 import time
 from datetime import datetime
-from typing import Dict, List, Optional, Callable, TYPE_CHECKING
+from typing import Any, Dict, List, Optional, Callable, TYPE_CHECKING
 import os
 from core.main_terminal import MainTerminal
 from utils.logger import setup_logger
@@ -105,13 +105,19 @@ class WebTerminal(MainTerminal):
     # 新增：对话管理相关方法（Web版本）
     # ===========================================
     
-    def create_new_conversation(self, thinking_mode: bool = None, run_mode: Optional[str] = None) -> Dict:
+    def create_new_conversation(
+        self,
+        thinking_mode: bool = None,
+        run_mode: Optional[str] = None,
+        metadata_overrides: Optional[Dict[str, Any]] = None,
+    ) -> Dict:
         """
         创建新对话（Web版本）
 
         Args:
             thinking_mode: 思考模式，None则使用当前设置
             run_mode: 显式的运行模式（fast/thinking/deep）
+            metadata_overrides: 额外写入对话 metadata 的字段
 
         Returns:
             Dict: 包含新对话信息
@@ -171,17 +177,21 @@ class WebTerminal(MainTerminal):
         try:
             # 先创建新对话。start_new_conversation 会先 save_current_conversation()，
             # 此时 terminal.model_key 仍是旧对话的模型，避免把旧对话覆盖成默认模型。
+            metadata_overrides_merged = {
+                "permission_mode": self.get_permission_mode(),
+                "execution_mode": self.get_execution_mode() if hasattr(self, "get_execution_mode") else "sandbox",
+                "pending_permission_mode": None,
+                "pending_execution_mode": None,
+                # frozen_*_prompt 不在创建时预设，由第一次 build_messages 根据当时的实际模式懒加载并冻结
+            }
+            if isinstance(metadata_overrides, dict):
+                metadata_overrides_merged.update(metadata_overrides)
+
             conversation_id = self.context_manager.start_new_conversation(
                 project_path=self.project_path,
                 thinking_mode=thinking_mode,
                 run_mode=self.run_mode,
-                metadata_overrides={
-                    "permission_mode": self.get_permission_mode(),
-                    "execution_mode": self.get_execution_mode() if hasattr(self, "get_execution_mode") else "sandbox",
-                    "pending_permission_mode": None,
-                    "pending_execution_mode": None,
-                    # frozen_*_prompt 不在创建时预设，由第一次 build_messages 根据当时的实际模式懒加载并冻结
-                },
+                metadata_overrides=metadata_overrides_merged,
             )
 
             # 新对话创建完成后再应用默认模型（此时旧对话已安全保存）。
@@ -196,7 +206,8 @@ class WebTerminal(MainTerminal):
 
                 # 把默认模型同步到新对话的 metadata
                 try:
-                    self.context_manager.conversation_manager.save_conversation(
+                    target_manager = self.context_manager._get_conversation_manager_for_id(conversation_id)
+                    target_manager.save_conversation(
                         conversation_id=conversation_id,
                         messages=self.context_manager.conversation_history,
                         project_path=str(self.project_path),
@@ -265,7 +276,8 @@ class WebTerminal(MainTerminal):
         perf_log("_ensure_conversation_versioning_enabled manager created", elapsed_ms=(time.perf_counter() - t0) * 1000, extra={"conv_id": normalized_id})
         meta = manager.set_enabled(enabled=True, mode="overwrite", tracking_mode=tracking_mode)
         perf_log("_ensure_conversation_versioning_enabled set_enabled done", elapsed_ms=(time.perf_counter() - t0) * 1000, extra={"conv_id": normalized_id})
-        conv_data = self.context_manager.conversation_manager.load_conversation(normalized_id) or {}
+        target_manager = self.context_manager._get_conversation_manager_for_id(normalized_id)
+        conv_data = target_manager.load_conversation(normalized_id) or {}
         snapshot_payload = {
             "conversation_id": normalized_id,
             "title": conv_data.get("title"),
@@ -283,7 +295,7 @@ class WebTerminal(MainTerminal):
         init_row = init_result.get("row") or {}
         if init_row.get("tree_hash"):
             meta["last_tree_hash"] = init_row.get("tree_hash")
-        self.context_manager.conversation_manager.update_conversation_metadata(
+        target_manager.update_conversation_metadata(
             normalized_id,
             {
                 "versioning": {
@@ -316,7 +328,8 @@ class WebTerminal(MainTerminal):
             if success:
                 # 根据对话元数据同步思考模式
                 try:
-                    conv_data = self.context_manager.conversation_manager.load_conversation(conversation_id) or {}
+                    target_manager = self.context_manager._get_conversation_manager_for_id(conversation_id)
+                    conv_data = target_manager.load_conversation(conversation_id) or {}
                     meta = conv_data.get("metadata", {}) or {}
                     mode = bool(meta.get("thinking_mode", self.thinking_mode))
                     self.thinking_mode = mode
@@ -350,13 +363,22 @@ class WebTerminal(MainTerminal):
                     self.pending_permission_mode = str(meta.get("pending_permission_mode") or "").strip().lower() or None
                     self.pending_execution_mode = str(meta.get("pending_execution_mode") or "").strip().lower() or None
                     self.pending_network_permission = str(meta.get("pending_network_permission") or "").strip().lower() or None
+                    # 多智能体模式：以会话 metadata.multi_agent_mode 为唯一切换开关
+                    self.multi_agent_mode = bool(meta.get("multi_agent_mode", False))
+                    # 同步主智能体 sub_agent_manager 的 开关
+                    try:
+                        if hasattr(self, "sub_agent_manager"):
+                            self.sub_agent_manager.multi_agent_mode = self.multi_agent_mode
+                    except Exception:
+                        pass
                 except Exception:
                     pass
                 # 重置相关状态
                 self.current_session_id += 1
                 
                 # 获取对话信息
-                conversation_data = self.context_manager.conversation_manager.load_conversation(conversation_id)
+                target_manager = self.context_manager._get_conversation_manager_for_id(conversation_id)
+                conversation_data = target_manager.load_conversation(conversation_id)
                 if not conversation_data:
                     return {
                         "success": False,
@@ -372,6 +394,7 @@ class WebTerminal(MainTerminal):
                     "run_mode": self.run_mode,
                     "thinking_mode": self.thinking_mode,
                     "model_key": getattr(self, "model_key", None),
+                    "multi_agent_mode": bool(getattr(self, "multi_agent_mode", False)),
                     "message": f"对话已加载: {conversation_id}"
                 }
             else:
@@ -388,10 +411,10 @@ class WebTerminal(MainTerminal):
                 "message": f"加载对话异常: {e}"
             }
     
-    def get_conversations_list(self, limit: int = 20, offset: int = 0, non_empty: bool = False) -> Dict:
+    def get_conversations_list(self, limit: int = 20, offset: int = 0, non_empty: bool = False, multi_agent_mode: Optional[bool] = None) -> Dict:
         """获取对话列表（Web版本）"""
         try:
-            result = self.context_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty)
+            result = self.context_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=multi_agent_mode)
             return {
                 "success": True,
                 "data": result

docs/multi_agent_mode/01_overview.md

@@ -0,0 +1,227 @@
+# 多智能体模式总体架构
+
+> 文档状态：设计草案  
+> 适用范围：宿主机模式（host mode），不覆盖 docker/web 模式  
+> 隔离原则：与现有对话系统完全隔离，复用底层能力但上层独立
+
+---
+
+## 1. 设计目标
+
+在 Astrion 中引入一个实验性的「多智能体模式」：
+
+- 主智能体固定扮演 **Team Leader**，负责任务拆解、调度、协调、回答子智能体提问。
+- 支持预置角色与自定义角色，每个角色可以有多个实例（`RoleName_1`、`RoleName_2`）。
+- 子智能体之间、子智能体与主智能体之间可以双向通信。
+- 所有通信遵循统一的消息格式与路由规则。
+- 与现有单智能体模式完全隔离，不影响现有代码与用户体验。
+
+---
+
+## 2. 核心设计原则
+
+### 2.1 完全隔离
+
+- 数据目录隔离：`~/.astrion/astrion/host/mutiagents/`
+- 页面隔离：新页面 `/multiagent/new`
+- 入口隔离：登录页单独按钮「多智能体模式 beta」
+- 代码隔离：所有新增代码放在 `modules/multi_agent/`、`docs/multi_agent_mode/`、`static/src/views/MultiAgentView.vue` 等独立位置
+- 现有文件如需改造，优先复制一份再改，不直接修改
+
+### 2.2 能复用则复用
+
+- 模型调用：复用 `DeepSeekClient`
+- 工具执行链路：复用 `WebTerminal.handle_tool_call` 的底层执行能力
+- 文件/终端/搜索等工具：复用现有工具实现
+- 对话持久化格式：复用 `ConversationManager` 的存储格式
+- 沙箱/权限机制：复用现有 `evaluate_tool_permission` 与宿主机沙箱
+
+### 2.3 子智能体即完整对话
+
+每个子智能体是一个独立的、完整的对话上下文：
+
+- 有自己的 `messages` 列表
+- 有自己的系统提示词
+- 有自己的工具列表
+- 自然输出 assistant 消息
+- 支持被主智能体/其他子智能体在运行中插入消息引导
+- 任务结束 = 本轮自然停止输出，但上下文保留
+
+---
+
+## 3. 角色与实例
+
+### 3.1 角色（Role）
+
+角色由 Markdown + YAML Frontmatter 定义，存储在：
+
+```
+~/.astrion/astrion/host/mutiagents/agents/<role_id>.md
+```
+
+示例 `ui-operator.md`：
+
+```markdown
+---
+id: ui-operator
+name: UI Operator
+description: 负责前端设计、UI 还原、配色方案
+model: qwen3-max
+thinking_mode: fast
+---
+
+你是团队的前端设计专家。你擅长：
+- 根据需求设计 UI 界面
+- 制定配色方案
+- 输出设计文档和前端代码
+
+工作风格：
+- 先分析需求，再给出设计方案
+- 输出简洁明确的设计说明
+```
+
+### 3.2 实例（Agent）
+
+- `role_id`：角色类型，如 `ui-operator`
+- `agent_id`：这个角色的第几个实例，从 1 开始
+- 显示名：`{Role Name}_{agent_id}`，如 `UI Operator_1`、`Full-Stack Engineer_1`
+- 同一个 `role_id` 可以有多个实例：UI Operator_1、UI Operator_2
+- 不同 `role_id` 的实例序号独立：Full-Stack Engineer_1 与 UI Operator_1 可以同时存在
+- 主智能体固定显示名为 `Team Leader`，没有 agent_id
+
+---
+
+## 4. 总体架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     用户（Web 前端）                          │
+│              /multiagent/new 页面                            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                  MultiAgentTerminal                         │
+│              （基于 MainTerminal 复制改造）                   │
+│  - 工具列表：主工具 + 多智能体专用工具                         │
+│  - 子智能体管理器：MultiAgentSubAgentManager                  │
+│  - 对话存储：指向 mutiagents/conversations/                   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+            ┌─────────────────┼─────────────────┐
+            ▼                 ▼                 ▼
+      ┌──────────┐     ┌──────────┐     ┌──────────┐
+      │ Agent 1  │     │ Agent 2  │     │ Agent 3  │
+      │UIOperator│     │ Full-   │     │ Code     │
+      │    1     │     │ Stack   │     │ Reviewer │
+      │          │     │Engineer1│     │    1     │
+      └──────────┘     └──────────┘     └──────────┘
+            │                 │                 │
+            └─────────────────┴─────────────────┘
+                              │
+                              ▼
+              ┌───────────────────────────────┐
+              │       MessageRouter           │
+              │   根据接收方状态决定：          │
+              │   - inline 插入工具结果后       │
+              │   - 空闲时作为 user 消息触发新任务│
+              └───────────────────────────────┘
+```
+
+---
+
+## 5. 主智能体职责
+
+主智能体 = Team Leader，其系统提示词中明确：
+
+- 除非任务极其简单或明确不需要，否则主动拆解任务并调用子智能体。
+- 为每个子任务选择最合适的角色（role_id）。
+- 子智能体可以向你提问，你必须及时通过 `answer_sub_agent_question` 回答。
+- 子智能体之间可以互相沟通，你负责监督整体进度。
+- 如果子智能体的中间输出需要干预，使用 `send_message_to_sub_agent` 引导。
+
+---
+
+## 6. 子智能体职责
+
+子智能体系统提示词由两部分组成：
+
+1. **基础 prompt**：通用团队规则
+2. **自定义 prompt**：角色专属设定
+
+基础 prompt 中明确：
+
+- 你是智能体集群团队的一员。
+- 不要频繁输出内容，不重要内容会污染主智能体上下文。
+- 只汇报关键步骤。
+- 任务完成后给出详细结论。
+- 需要主智能体决策时，使用 `ask_master`。
+- 需要与其他子智能体沟通时，使用 `ask_other_agent` / `answer_other_agent`。
+- 如果向其他子智能体提问，必须同时直接向主智能体输出汇报。
+
+---
+
+## 7. 与现有系统的边界
+
+| 现有系统 | 多智能体模式处理方式 |
+|---------|---------------------|
+| 现有对话页面 | 不改动，新增 `/multiagent/new` |
+| 现有 `MainTerminal` | 不改动，复制为 `MultiAgentTerminal` |
+| 现有 `SubAgentManager` | 不改动，继承创建 `MultiAgentSubAgentManager` |
+| 现有 `SubAgentTask` | 不改动，继承创建 `MultiAgentSubAgentTask` |
+| 现有 `ConversationManager` | 不改动，多智能体模式用自己的存储目录 |
+| 现有后台通知池机制 | 参考其设计，多智能体模式实现自己的消息路由 |
+| 现有工具执行链路 | 复用 `execute_tool_for_sub_agent` |
+| 现有沙箱/权限 | 复用，不额外限制子智能体工具参数 |
+
+---
+
+## 8. 入口与数据目录
+
+### 8.1 入口
+
+登录页面增加按钮：「多智能体模式 beta」。
+
+点击后进入 `/multiagent/new` 页面，加载 `MultiAgentTerminal`。
+
+### 8.2 数据目录
+
+```
+~/.astrion/astrion/host/mutiagents/
+├── agents/                          # 角色定义
+├── conversations/                   # 多智能体会话
+│   └── <conv_id>/
+│       ├── metadata.json
+│       ├── messages.json            # Team Leader 对话
+│       └── agents/
+│           └── <agent_id>/
+│               ├── metadata.json
+│               └── messages.json    # 子智能体完整对话记录
+└── state.json                       # 全局状态
+```
+
+子智能体对话记录的保存精度、时机、格式与主智能体对话记录一致。
+
+---
+
+## 9. 实现顺序（非严格 phase）
+
+1. 创建独立目录与数据存储结构
+2. 实现角色配置加载与预置角色
+3. 实现 `MultiAgentSubAgentTask` / `MultiAgentSubAgentManager`
+4. 实现 `MultiAgentTerminal` 与多智能体工具定义
+5. 实现消息路由（inline / idle / 通知池）
+6. 实现前端 `/multiagent/new` 页面
+7. 登录页加入口按钮
+8. 联调测试
+
+---
+
+## 10. 相关文档
+
+- `02_message_protocol.md`：统一消息格式
+- `03_tool_definitions.md`：工具定义
+- `04_message_routing.md`：消息路由机制
+- `05_data_model.md`：数据模型
+- `06_implementation_plan.md`：实现细节
+- `07_existing_code_analysis.md`：现有代码分析

docs/multi_agent_mode/02_message_protocol.md

@@ -0,0 +1,249 @@
+# 多智能体模式消息协议
+
+> 所有插入对话的 user 消息必须遵循统一格式。
+> 不使用 `[系统通知|xxx]` 前缀，改用自然语言前缀。
+
+---
+
+## 1. 消息格式模板
+
+所有通信 user 消息都使用以下结构：
+
+```
+来自 {显示名} 的{消息类型}
+id: {消息id}
+
+<{显示名}>
+<{标签}>
+{内容}
+</{标签}>
+</{显示名}>
+```
+
+### 字段说明
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| 显示名 | `{Role Name}_{agent_id}` 或 `Team Leader` | `UI Operator_1`、`Full-Stack Engineer_1` |
+| 消息类型 | 任务发布 / 任务进度输出 / 任务完成汇报 / 提问 / 消息 / 回答 | 见下表 |
+| 消息id | 本次消息的全局唯一标识，用于 answer 时引用 | `ask_fse_001`、`msg_uio_003` |
+| 标签 | Task / Output / Ask / Message / Answer | 与消息类型对应 |
+| 内容 | 消息正文 | 任意文本 |
+
+### 消息类型与标签对应表
+
+| 消息类型 | 标签 | 发送方 | 接收方 |
+|---------|------|--------|--------|
+| 任务发布 | `<Task>` | Team Leader | 子智能体 |
+| 任务进度输出 | `<Output>` | 子智能体 | Team Leader |
+| 任务完成汇报 | `<Output>` | 子智能体 | Team Leader |
+| 提问 | `<Ask>` | 子智能体 | Team Leader / 其他子智能体 |
+| 消息 | `<Message>` | Team Leader / 子智能体 | 子智能体 |
+| 回答 | `<Answer>` | 子智能体 | 子智能体（返回到 ask 工具结果） |
+
+---
+
+## 2. 主智能体 → 子智能体
+
+### 2.1 任务发布
+
+当主智能体通过 `create_sub_agent` 或 `send_message_to_sub_agent` 向子智能体发布任务时使用。
+
+```
+来自 Team Leader 的任务发布
+id: task_001
+
+<Team Leader>
+<Task>
+请为项目设计前端配色方案，输出 design.md 到 sub_agent_results/design/。
+</Task>
+</Team Leader>
+```
+
+### 2.2 后续消息 / 运行中引导
+
+当主智能体在子智能体运行期间通过 `send_message_to_sub_agent` 插入引导消息时使用。
+
+```
+来自 Team Leader 的消息
+id: msg_tl_002
+
+<Team Leader>
+<Message>
+先不要创建 API，先确认一下现有的 auth 模块是否可复用。
+</Message>
+</Team Leader>
+```
+
+### 2.3 主智能体问子智能体（ask_sub_agent）
+
+当主智能体通过 `ask_sub_agent` 向子智能体提问时使用。
+
+```
+来自 Team Leader 的提问
+id: ask_tl_001
+
+<Team Leader>
+<Ask>
+你预计还需要多久完成？
+</Ask>
+</Team Leader>
+```
+
+子智能体的回答返回到 `ask_sub_agent` 工具结果中，不插入主智能体对话。
+
+---
+
+## 3. 子智能体 → 主智能体
+
+### 3.1 任务进度输出
+
+子智能体在自然输出中汇报进度时，由后端捕获并插入主智能体对话。
+
+```
+来自 UI Operator_1 的任务进度输出
+id: out_uio_001
+
+<UI Operator_1>
+<Output>
+我现在开始分析现有设计风格和用户需求...
+</Output>
+</UI Operator_1>
+```
+
+### 3.2 任务完成汇报
+
+子智能体本轮自然结束输出时，最后一条输出作为完成汇报插入主智能体对话。
+
+```
+来自 UI Operator_1 的任务完成汇报
+id: out_uio_002
+
+<UI Operator_1>
+<Output>
+我完成了前端配色的设计，生成了 design.md，主色调为蓝色系。
+</Output>
+</UI Operator_1>
+```
+
+**注意**：子智能体不调用 `report_progress` 或 `finish_task` 工具。自然的 assistant 输出即表示进度或完成。
+
+### 3.3 子智能体向主智能体提问
+
+子智能体通过 `ask_master` 工具向主智能体提问。
+
+```
+来自 Full-Stack Engineer_1 的提问
+id: ask_fse_001
+
+<Full-Stack Engineer_1>
+<Ask>
+我该怎么处理版本冲突问题？项目里当前用的是什么分支策略？
+</Ask>
+</Full-Stack Engineer_1>
+```
+
+主智能体通过 `answer_sub_agent_question` 工具回答，回答内容返回到 `ask_master` 工具结果中。
+
+---
+
+## 4. 子智能体 → 子智能体
+
+### 4.1 A 向 B 提问
+
+子智能体 A 通过 `ask_other_agent` 向子智能体 B 提问。
+
+```
+来自 UI Operator_1 的提问
+id: ask_uio_001
+
+<UI Operator_1>
+<Ask>
+API 接口已经确定了吗？我需要接口字段来设计表单。
+</Ask>
+</UI Operator_1>
+```
+
+这条消息插入到 B 的 user 消息中。
+
+### 4.2 B 回答 A
+
+子智能体 B 通过 `answer_other_agent` 回答 A。
+
+```
+来自 Full-Stack Engineer_1 的回答
+id: ans_fse_001
+
+<Full-Stack Engineer_1>
+<Answer question_id="ask_uio_001">
+已经确定，见 api.md。用户注册接口为 POST /api/users，字段为...
+</Answer>
+</Full-Stack Engineer_1>
+```
+
+回答返回到 A 的 `ask_other_agent` 工具结果中。
+
+### 4.3 A 向 B 发送普通消息
+
+子智能体 A 通过 `ask_other_agent` 问 B，但内容不是需要回答的问题，而是通知。
+
+```
+来自 UI Operator_1 的消息
+id: msg_uio_003
+
+<UI Operator_1>
+<Message>
+前端页面已经 ready，可以开始对接了。
+</Message>
+</UI Operator_1>
+```
+
+B 可以直接通过自然输出回复，回复会返回到 A 的 `ask_other_agent` 工具结果中。
+
+---
+
+## 5. ID 生成规则
+
+| 消息类型 | ID 前缀 | 示例 |
+|---------|---------|------|
+| 任务发布 | `task_` | `task_001` |
+| 任务进度输出 | `out_` | `out_uio_001` |
+| 任务完成汇报 | `out_` | `out_uio_002` |
+| 子智能体问主智能体 | `ask_` | `ask_fse_001` |
+| 主智能体问子智能体 | `ask_` | `ask_tl_001` |
+| 子智能体间提问 | `ask_` | `ask_uio_001` |
+| 子智能体间回答 | `ans_` | `ans_fse_001` |
+| 普通消息 | `msg_` | `msg_tl_002` |
+
+ID 需要保证在多智能体会话内全局唯一。
+
+---
+
+## 6. 前端渲染
+
+前端消息气泡只显示三部分：
+
+1. 角色：如 `UI Operator_1`
+2. 目的/动作：如 `任务进度输出`、`提问`、`消息`
+3. 内容：XML 标签内的文本
+
+不显示 XML 标签本身。
+
+示例渲染：
+
+```
+┌────────────────────────────────────┐
+│ UI Operator_1 任务进度输出          │
+│                                    │
+│ 我现在开始分析现有设计风格...         │
+└────────────────────────────────────┘
+```
+
+---
+
+## 7. 关键约束
+
+1. 所有插入对话的 user 消息都必须包含完整的 XML 包裹，便于后端解析和前端渲染。
+2. `id` 放在 XML 外面，不放在 `<>` 属性中。
+3. 子智能体之间的通信不强制同步到主智能体，但子智能体必须在提示词中被要求：向其他子智能体提问时，必须同时直接向主智能体输出汇报。
+4. 回答类消息（`answer_sub_agent_question`、`answer_other_agent`）不插入 user 消息，只返回到对应 ask 工具的结果中。

docs/multi_agent_mode/03_tool_definitions.md

@@ -0,0 +1,470 @@
+# 多智能体模式工具定义
+
+> 主智能体工具基于现有主智能体工具，移除旧版子智能体工具，新增多智能体专用工具。  
+> 子智能体工具保留现有 8 个基础工具，新增多智能体通信工具。  
+> 所有工具定义集中在 `modules/multi_agent/tools/` 目录下，不修改现有 `core/main_terminal_parts/tools_definition/`。
+
+---
+
+## 1. 主智能体（Team Leader）工具
+
+主智能体 = Team Leader，其工具列表 = 现有主智能体工具（去掉旧版子智能体工具） + 多智能体专用工具。
+
+### 1.1 从现有工具中移除
+
+以下旧版子智能体工具不在多智能体模式中使用：
+
+- `create_sub_agent`（旧版）
+- `close_sub_agent`
+- `terminate_sub_agent`（旧版）
+- `get_sub_agent_status`（旧版）
+
+### 1.2 新增/替换的多智能体工具
+
+#### `create_sub_agent`
+
+创建并启动一个子智能体实例。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "create_sub_agent",
+    "description": "创建一个子智能体实例并启动它。一个角色可以有多个实例，如 UI Operator_1、UI Operator_2。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "这个角色的第几个实例，从 1 开始。同一 role_id 下每个编号只能用一次。"
+        },
+        "role_id": {
+          "type": "string",
+          "description": "角色 ID，如 ui-operator、full-stack-engineer。"
+        },
+        "task": {
+          "type": "string",
+          "description": "任务描述，会作为给子智能体的首条任务发布消息。"
+        },
+        "run_in_background": {
+          "type": "boolean",
+          "description": "是否后台运行。多智能体模式下通常直接运行（false），因为需要观察输出。"
+        },
+        "timeout_seconds": {
+          "type": "integer",
+          "description": "超时时间，默认 600 秒。"
+        },
+        "thinking_mode": {
+          "type": "string",
+          "enum": ["fast", "thinking"],
+          "description": "思考模式，不指定则使用角色配置。"
+        },
+        "model_key": {
+          "type": "string",
+          "description": "模型 key，不指定则使用角色配置。"
+        }
+      },
+      "required": ["agent_id", "role_id", "task"]
+    }
+  }
+}
+```
+
+#### `terminate_sub_agent`
+
+强制终止指定子智能体实例。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "terminate_sub_agent",
+    "description": "强制终止指定子智能体实例。终止后无法恢复，但已生成的文件保留。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "要终止的子智能体实例编号。"
+        }
+      },
+      "required": ["agent_id"]
+    }
+  }
+}
+```
+
+#### `send_message_to_sub_agent`
+
+向子智能体发送消息或运行中引导。不等待回答。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "send_message_to_sub_agent",
+    "description": "向指定子智能体发送消息。如果子智能体正在运行，消息会插入到当前输出流中作为引导；如果子智能体空闲，消息会触发新一轮运行。用于运行中纠正、补充上下文、追加指令。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "目标子智能体实例编号。"
+        },
+        "message": {
+          "type": "string",
+          "description": "要发送的消息内容。"
+        }
+      },
+      "required": ["agent_id", "message"]
+    }
+  }
+}
+```
+
+#### `ask_sub_agent`
+
+向子智能体提问并等待回答。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "ask_sub_agent",
+    "description": "向指定子智能体提问并等待其回答。适用于需要子智能体给出明确答复的场景。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "目标子智能体实例编号。"
+        },
+        "question": {
+          "type": "string",
+          "description": "问题内容。"
+        },
+        "question_id": {
+          "type": "string",
+          "description": "问题唯一 ID，子智能体回答时会引用。"
+        }
+      },
+      "required": ["agent_id", "question", "question_id"]
+    }
+  }
+}
+```
+
+#### `answer_sub_agent_question`
+
+回答子智能体向主智能体提出的问题。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "answer_sub_agent_question",
+    "description": "回答子智能体提出的问题。回答会返回到子智能体 ask_master 工具的结果中。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "提问的子智能体实例编号。"
+        },
+        "question_id": {
+          "type": "string",
+          "description": "问题 ID，与 ask_master 时一致。"
+        },
+        "answer": {
+          "type": "string",
+          "description": "回答内容。"
+        }
+      },
+      "required": ["agent_id", "question_id", "answer"]
+    }
+  }
+}
+```
+
+#### `list_active_sub_agents`
+
+查询当前多智能体会话中所有活跃/可通信的子智能体。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "list_active_sub_agents",
+    "description": "查询当前多智能体会话中所有活跃或可通信的子智能体列表，包括运行中和空闲的实例。",
+    "parameters": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+}
+```
+
+返回示例：
+
+```json
+{
+  "success": true,
+  "agents": [
+    {
+      "agent_id": 1,
+      "role_id": "ui-operator",
+      "display_name": "UI Operator_1",
+      "status": "running",
+      "summary": "设计前端配色方案"
+    },
+    {
+      "agent_id": 2,
+      "role_id": "full-stack-engineer",
+      "display_name": "Full-Stack Engineer_1",
+      "status": "idle",
+      "summary": "等待 API 接口确认"
+    }
+  ]
+}
+```
+
+#### `get_sub_agent_status`
+
+查询指定子智能体的详细状态。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "get_sub_agent_status",
+    "description": "查询指定子智能体实例的详细状态、统计和最近输出。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "agent_id": {
+          "type": "integer",
+          "description": "子智能体实例编号。"
+        }
+      },
+      "required": ["agent_id"]
+    }
+  }
+}
+```
+
+#### `create_custom_agent`
+
+创建并保存自定义角色。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "create_custom_agent",
+    "description": "创建一个自定义角色并保存到本地，后续可通过 role_id 调用。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "role_id": {
+          "type": "string",
+          "description": "角色 ID，唯一标识。"
+        },
+        "name": {
+          "type": "string",
+          "description": "角色显示名。"
+        },
+        "description": {
+          "type": "string",
+          "description": "角色简短描述。"
+        },
+        "model": {
+          "type": "string",
+          "description": "默认使用的模型。"
+        },
+        "thinking_mode": {
+          "type": "string",
+          "enum": ["fast", "thinking"],
+          "description": "默认思考模式。"
+        },
+        "prompt": {
+          "type": "string",
+          "description": "角色专属 prompt。"
+        }
+      },
+      "required": ["role_id", "name", "description", "prompt"]
+    }
+  }
+}
+```
+
+#### `list_agents`
+
+列出所有可用角色。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "list_agents",
+    "description": "列出所有可用的预置和自定义角色。",
+    "parameters": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+}
+```
+
+---
+
+## 2. 子智能体工具
+
+子智能体保留现有 8 个基础工具：
+
+- `read_file`
+- `write_file`
+- `edit_file`
+- `run_command`
+- `web_search`
+- `extract_webpage`
+- `search_workspace`
+- `read_mediafile`
+
+新增以下多智能体通信工具：
+
+### 2.1 `ask_master`
+
+向主智能体（Team Leader）提问，阻塞等待回答。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "ask_master",
+    "description": "向主智能体（Team Leader）提问。主智能体回答后会将结果返回到此工具调用中。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "question": {
+          "type": "string",
+          "description": "问题内容。"
+        },
+        "question_id": {
+          "type": "string",
+          "description": "问题唯一 ID。"
+        }
+      },
+      "required": ["question", "question_id"]
+    }
+  }
+}
+```
+
+### 2.2 `ask_other_agent`
+
+向其他子智能体提问或发送消息，阻塞等待回复。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "ask_other_agent",
+    "description": "向其他子智能体提问或发送消息。对方回复后会将结果返回到此工具调用中。注意：向其他子智能体提问时，必须同时直接向主智能体输出汇报。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "target_agent_id": {
+          "type": "integer",
+          "description": "目标子智能体实例编号。"
+        },
+        "content": {
+          "type": "string",
+          "description": "提问或消息内容。"
+        },
+        "message_id": {
+          "type": "string",
+          "description": "消息唯一 ID。"
+        }
+      },
+      "required": ["target_agent_id", "content", "message_id"]
+    }
+  }
+}
+```
+
+### 2.3 `answer_other_agent`
+
+回答其他子智能体的问题。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "answer_other_agent",
+    "description": "回答其他子智能体的问题。回答会返回到对方 ask_other_agent 工具的结果中。",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "source_agent_id": {
+          "type": "integer",
+          "description": "提问方的子智能体实例编号。"
+        },
+        "message_id": {
+          "type": "string",
+          "description": "对方提问时的 message_id。"
+        },
+        "answer": {
+          "type": "string",
+          "description": "回答内容。"
+        }
+      },
+      "required": ["source_agent_id", "message_id", "answer"]
+    }
+  }
+}
+```
+
+### 2.4 `list_active_sub_agents`
+
+查询当前活跃子智能体。
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "list_active_sub_agents",
+    "description": "查询当前多智能体会话中所有活跃或可通信的子智能体。",
+    "parameters": {
+      "type": "object",
+      "properties": {}
+    }
+  }
+}
+```
+
+---
+
+## 3. 工具与消息映射
+
+| 动作 | 工具 | 发送方 | 接收方形式 |
+|------|------|--------|-----------|
+| 创建子智能体 | `create_sub_agent` | Team Leader | 启动实例，首条消息以任务发布形式插入 |
+| 终止子智能体 | `terminate_sub_agent` | Team Leader | 强制停止实例 |
+| 向子智能体发消息/引导 | `send_message_to_sub_agent` | Team Leader | 插入子智能体 user 消息（inline 或触发新任务） |
+| Team Leader 问子智能体 | `ask_sub_agent` | Team Leader | 插入子智能体 user 消息，等待回复 |
+| 子智能体问 Team Leader | `ask_master` | 子智能体 | 插入 Team Leader user 消息，等待回答 |
+| Team Leader 回答子智能体 | `answer_sub_agent_question` | Team Leader | 返回到 `ask_master` 工具结果 |
+| 子智能体 A 问 B | `ask_other_agent` | A | 插入 B 的 user 消息（inline 或触发新任务） |
+| 子智能体 B 回答 A | `answer_other_agent` | B | 返回到 A 的 `ask_other_agent` 工具结果 |
+| 查询活跃子智能体 | `list_active_sub_agents` | 任意 | 返回列表 |
+| 子智能体输出/汇报 | 自然 assistant 输出 | 子智能体 | 捕获后插入 Team Leader user 消息 |
+
+---
+
+## 4. 工具定义文件位置
+
+- 主智能体工具：`modules/multi_agent/tools/master_tools.py`
+- 子智能体工具：`modules/multi_agent/tools/agent_tools.py`
+- 工具处理：`modules/multi_agent/tools/tool_handlers.py`
+
+不修改现有 `core/main_terminal_parts/tools_definition.py` 或 `modules/sub_agent/toolkit.py`。

docs/multi_agent_mode/04_message_routing.md

@@ -0,0 +1,222 @@
+# 多智能体模式消息路由机制
+
+> 消息路由由**接收方**决定：根据接收方当前状态，选择 inline 插入工具结果后，或作为 user 消息触发新一轮任务。  
+> 参考现有后台任务通知池机制实现，保证消息不丢失、不错乱、可批量处理。
+
+---
+
+## 1. 核心思想
+
+### 1.1 接收方决定插入方式
+
+当一条消息需要发送给某个子智能体（或主智能体）时，路由层只关心接收方当前处于什么状态：
+
+| 接收方状态 | 插入方式 | 效果 |
+|-----------|---------|------|
+| 正在运行中，且当前在某次工具调用中阻塞等待 | 把消息作为该工具调用的结果返回 | 子智能体在当前轮次继续执行，立即看到消息 |
+| 正在运行中，但不在阻塞等待状态 | 把消息 inline 插入到当前对话上下文末尾 | 子智能体下一轮输出时自然看到 |
+| 空闲状态（本轮已自然结束） | 把消息作为普通 user 消息插入 | 触发子智能体新一轮运行 |
+
+### 1.2 参考现有后台通知池
+
+现有后台任务通知机制：
+
+- **运行期间（inline）**：`server/chat_flow_tool_loop.py` 中 `execute_tool_calls` 末尾调用 `process_sub_agent_updates(..., inline=True)`，把已完成的子智能体任务一次性插入当前 `messages`，不触发新任务。
+- **停止输出后（polling）**：`server/chat_flow_task_main.py` 中 `handle_task_with_sender` 结尾启动 `run_completion_poll`，统一轮询子智能体 + 后台命令完成通知，批量插入 user 消息，只触发一个后续任务。
+
+多智能体模式的消息路由借鉴此机制：
+
+- 每个子智能体有自己的「待处理消息队列」。
+- 子智能体每次进入可接收消息的状态时，从队列中取出所有消息，按顺序处理。
+- 避免逐条消息触发多次「工作 → 停止 → 再工作」循环。
+
+---
+
+## 2. 消息路由状态机
+
+### 2.1 子智能体状态
+
+```
+          ┌─────────────┐
+          │   idle      │ 空闲
+          └──────┬──────┘
+                 │ create_sub_agent / send_message_to_sub_agent
+                 ▼
+          ┌─────────────┐
+          │  running    │ 运行中
+          │  (normal)   │ 正常输出
+          └──────┬──────┘
+                 │ 调用 ask_master / ask_other_agent
+                 ▼
+          ┌─────────────┐
+          │  waiting    │ 阻塞等待回答
+          │  (asking)   │
+          └──────┬──────┘
+                 │ 收到 answer / 自然结束
+                 ▼
+          ┌─────────────┐
+          │  completed  │ 本轮结束（上下文保留）
+          └─────────────┘
+```
+
+### 2.2 路由决策
+
+```python
+def route_message(target_agent_id, message):
+    agent = get_agent(target_agent_id)
+
+    if agent.state == "waiting" and agent.pending_tool_call:
+        # 目标正在阻塞等待回答：直接返回到工具结果
+        agent.resolve_pending_tool_call(message)
+        return "resolved"
+
+    if agent.state == "running":
+        # 目标正在运行：inline 插入到当前对话上下文末尾
+        agent.inject_inline_message(message)
+        return "injected_inline"
+
+    if agent.state in ("idle", "completed"):
+        # 目标空闲：作为 user 消息插入，触发新一轮运行
+        agent.inject_user_message(message)
+        return "triggered_new_turn"
+```
+
+---
+
+## 3. 关键场景分析
+
+### 3.1 子智能体正在输出，主智能体要引导
+
+场景：
+- UI Operator_1 正在运行，输出了「接下来我会创建新 API...」
+- Team Leader 要立即干预：「先不要创建 API，先确认现有 auth 模块是否可复用。」
+
+处理：
+- UI Operator_1 状态为 `running`（正常输出，不在阻塞等待）
+- `send_message_to_sub_agent` 的消息 inline 插入到 UI Operator_1 的 `messages` 末尾
+- UI Operator_1 下一轮模型调用时会看到这条 user 消息
+
+### 3.2 子智能体正在等待回答
+
+场景：
+- Full-Stack Engineer_1 调用了 `ask_master`，等待 Team Leader 回答
+- Team Leader 调用 `answer_sub_agent_question`
+
+处理：
+- Full-Stack Engineer_1 状态为 `waiting`
+- 回答直接返回到 `ask_master` 工具结果中
+- Full-Stack Engineer_1 继续执行
+
+### 3.3 子智能体已经完成，主智能体追加任务
+
+场景：
+- Full-Stack Engineer_1 已经自然结束输出，状态为 `completed`
+- Team Leader 要追加新任务
+
+处理：
+- `send_message_to_sub_agent` 的消息作为普通 user 消息插入
+- 触发 Full-Stack Engineer_1 新一轮运行
+
+### 3.4 边界情况：子智能体正在进行最后一轮输出
+
+场景：
+- UI Operator_1 正在输出最后一段话，后面没有工具调用了
+- Team Leader 此时调用 `send_message_to_sub_agent`
+
+处理：
+- 如果消息到达时 UI Operator_1 还在运行：尝试 inline 插入
+- 但由于这是最后一轮，后面没有工具调用了，inline 的消息不会被模型看到
+- 因此需要在 UI Operator_1 本轮任务结束后，把这条消息作为触发新一轮任务的 user 消息发送
+
+实现要点：
+- 路由层维护每个子智能体的「待处理消息队列」
+- 子智能体任务自然结束时，检查队列
+- 如果有待处理消息，立即作为 user 消息触发新一轮运行
+
+### 3.5 子智能体 A 问 B，B 正在运行
+
+场景：
+- UI Operator_1 调用 `ask_other_agent(target=2)` 问 Full-Stack Engineer_1
+- Full-Stack Engineer_1 正在运行中
+
+处理：
+- 如果 Full-Stack Engineer_1 处于 `running` 状态：inline 插入 user 消息
+- Full-Stack Engineer_1 下一轮输出时看到问题
+- 如果 Full-Stack Engineer_1 调用 `answer_other_agent`：回答返回到 UI Operator_1 的 `ask_other_agent` 工具结果
+
+---
+
+## 4. 待处理消息队列
+
+每个子智能体维护一个待处理消息队列 `pending_messages`。
+
+```python
+@dataclass
+class PendingMessage:
+    id: str
+    source_display_name: str
+    source_agent_id: Optional[int]
+    target_agent_id: int
+    message_type: str  # task / output / ask / message / answer
+    content: str
+    question_id: Optional[str]  # 用于 answer 匹配
+    created_at: float
+```
+
+### 4.1 队列消费时机
+
+1. 子智能体每次模型调用前，先检查队列，把待处理消息合并到 `messages` 中
+2. 子智能体从 `waiting` 状态恢复时，优先消费回答类消息
+3. 子智能体自然结束时，如果有剩余待处理消息，立即触发新一轮运行
+
+### 4.2 批量消费
+
+参考现有通知池，每次消费时尽可能一次性取出所有可消费消息：
+
+```python
+def consume_pending_messages(agent):
+    messages = agent.pending_messages.drain_all()
+    for msg in messages:
+        formatted = format_message(msg)
+        agent.messages.append({"role": "user", "content": formatted})
+    return len(messages)
+```
+
+---
+
+## 5. 与现有通知池的对比
+
+| 维度 | 现有后台通知池 | 多智能体消息路由 |
+|------|--------------|----------------|
+| 触发源 | 子智能体/后台命令完成 | 子智能体间/主智能体向子智能体发消息 |
+| 接收方 | 主智能体对话 | 子智能体对话或主智能体对话 |
+| 插入方式 | inline / 触发新任务 | inline / 返回到工具结果 / 触发新任务 |
+| 批量处理 | `_collect_pending_completion_notices` 一次性取多条 | 每个子智能体维护自己的待处理队列 |
+| 持久化 | 直接插入对话历史 | 先进入队列，再按状态消费并持久化 |
+
+---
+
+## 6. 消息路由实现位置
+
+- 核心路由逻辑：`modules/multi_agent/message_router.py`
+- 待处理队列：`MultiAgentSubAgentTask.pending_messages`
+- 状态管理：`MultiAgentSubAgentTask.state`
+- 工具调用等待：`MultiAgentSubAgentTask.pending_tool_calls`
+
+---
+
+## 7. 防丢失机制
+
+1. 每条消息都有唯一 `id`
+2. 消息进入队列时立即持久化到子智能体 metadata
+3. 消费完成后从队列移除并持久化
+4. 子智能体恢复时从 metadata 加载未消费消息
+5. 回答类消息通过 `question_id` / `message_id` 精确匹配
+
+---
+
+## 8. 关键代码参考
+
+- `server/chat_flow_task_support.py`：`inject_runtime_user_message`、`process_sub_agent_updates`
+- `server/chat_flow_task_main.py`：`_collect_pending_completion_notices`、`poll_completion_notifications`、`_dispatch_completion_user_notice`
+- `server/chat_flow_tool_loop.py`：`execute_tool_calls` 末尾的 `process_sub_agent_updates(..., inline=True)`

docs/multi_agent_mode/05_data_model.md

@@ -0,0 +1,304 @@
+# 多智能体模式数据模型
+
+> 所有数据存储在 `~/.astrion/astrion/host/mutiagents/` 下，与现有系统完全隔离。  
+> 子智能体对话记录的保存精度、时机、格式与主智能体对话记录一致。
+
+---
+
+## 1. 目录结构
+
+```
+~/.astrion/astrion/host/mutiagents/
+├── agents/                              # 角色定义
+│   ├── ui-operator.md
+│   ├── full-stack-engineer.md
+│   ├── code-reviewer.md
+│   └── researcher.md
+├── conversations/                       # 多智能体会话
+│   └── <conv_id>/
+│       ├── metadata.json                # 会话级元数据
+│       ├── messages.json                # Team Leader 对话
+│       └── agents/
+│           └── <agent_id>/
+│               ├── metadata.json        # 子智能体元数据
+│               └── messages.json        # 子智能体完整对话
+└── state.json                           # 全局状态
+```
+
+---
+
+## 2. 角色定义（Agent Role）
+
+文件路径：`agents/<role_id>.md`
+
+格式：YAML Frontmatter + Markdown 正文
+
+```markdown
+---
+id: ui-operator
+name: UI Operator
+description: 负责前端设计、UI 还原、配色方案
+model: qwen3-max
+thinking_mode: fast
+---
+
+你是团队的前端设计专家...
+```
+
+### Frontmatter 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 角色唯一标识，文件名也使用此 id |
+| `name` | string | 是 | 角色显示名 |
+| `description` | string | 是 | 角色简短描述 |
+| `model` | string | 否 | 默认模型 key |
+| `thinking_mode` | string | 否 | fast / thinking |
+
+### 正文
+
+正文部分为角色专属 prompt，会拼接在基础 prompt 之后。
+
+---
+
+## 3. 全局状态（state.json）
+
+```json
+{
+  "version": "1.0",
+  "last_conversation_id": "conv_xxx",
+  "agent_id_counter": 5,
+  "created_at": "2026-07-11T21:00:00",
+  "updated_at": "2026-07-11T21:30:00"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `version` | 数据格式版本 |
+| `last_conversation_id` | 最近一次会话 id |
+| `agent_id_counter` | 全局实例编号计数器（可选） |
+
+---
+
+## 4. 会话元数据（metadata.json）
+
+```json
+{
+  "id": "conv_20260711_210000_001",
+  "title": "多智能体任务：设计前端",
+  "created_at": "2026-07-11T21:00:00",
+  "updated_at": "2026-07-11T21:30:00",
+  "project_path": "/Users/jojo/project",
+  "model_key": "qwen3-max",
+  "thinking_mode": true,
+  "run_mode": "thinking",
+  "status": "active",
+  "agent_count": 3,
+  "agent_ids": [1, 2, 3]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `id` | 会话 id |
+| `title` | 会话标题 |
+| `created_at` | 创建时间 |
+| `updated_at` | 更新时间 |
+| `project_path` | 关联项目路径 |
+| `model_key` | Team Leader 使用的模型 |
+| `thinking_mode` | 是否思考模式 |
+| `run_mode` | fast / thinking / deep |
+| `status` | active / archived |
+| `agent_count` | 当前子智能体数量 |
+| `agent_ids` | 当前子智能体 agent_id 列表 |
+
+---
+
+## 5. 主智能体对话（messages.json）
+
+与现有 `ConversationManager` 保存格式一致。
+
+```json
+{
+  "id": "conv_20260711_210000_001",
+  "title": "多智能体任务：设计前端",
+  "created_at": "2026-07-11T21:00:00",
+  "updated_at": "2026-07-11T21:30:00",
+  "messages": [
+    {
+      "role": "user",
+      "content": "帮我设计一个前端页面",
+      "message_id": "msg_user_001",
+      "metadata": {
+        "message_source": "user",
+        "visibility": "chat",
+        "starts_work": true
+      }
+    },
+    {
+      "role": "assistant",
+      "content": "我来安排 UI Operator 处理这个任务...",
+      "message_id": "msg_assistant_001",
+      "tool_calls": [...]
+    },
+    {
+      "role": "user",
+      "content": "来自 UI Operator_1 的任务完成汇报\nid: out_uio_001\n\n<UI Operator_1>\n<Output>\n我完成了前端配色的设计...\n</Output>\n</UI Operator_1>",
+      "message_id": "msg_auto_001",
+      "metadata": {
+        "message_source": "sub_agent",
+        "visibility": "compact",
+        "starts_work": false,
+        "agent_id": 1
+      }
+    }
+  ],
+  "metadata": { ... },
+  "token_statistics": { ... }
+}
+```
+
+---
+
+## 6. 子智能体元数据（agents/<agent_id>/metadata.json）
+
+```json
+{
+  "agent_id": 1,
+  "role_id": "ui-operator",
+  "display_name": "UI Operator_1",
+  "status": "running",
+  "created_at": "2026-07-11T21:05:00",
+  "updated_at": "2026-07-11T21:15:00",
+  "task_summary": "设计前端配色方案",
+  "model_key": "qwen3-max",
+  "thinking_mode": "fast",
+  "pending_messages": [
+    {
+      "id": "msg_tl_001",
+      "source_display_name": "Team Leader",
+      "source_agent_id": null,
+      "message_type": "message",
+      "content": "先不要创建 API...",
+      "created_at": 1752251700.0
+    }
+  ],
+  "pending_tool_calls": [
+    {
+      "tool_call_id": "tc_ask_001",
+      "tool_name": "ask_master",
+      "question_id": "ask_uio_001",
+      "created_at": 1752251800.0
+    }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `agent_id` | 实例编号 |
+| `role_id` | 角色 id |
+| `display_name` | 显示名 |
+| `status` | running / waiting / idle / completed / terminated |
+| `task_summary` | 当前任务摘要 |
+| `pending_messages` | 待处理消息队列 |
+| `pending_tool_calls` | 正在等待回答的工具调用 |
+
+---
+
+## 7. 子智能体对话（agents/<agent_id>/messages.json）
+
+保存精度、时机、格式与主智能体对话完全一致。
+
+```json
+{
+  "agent_id": 1,
+  "role_id": "ui-operator",
+  "display_name": "UI Operator_1",
+  "created_at": "2026-07-11T21:05:00",
+  "updated_at": "2026-07-11T21:15:00",
+  "messages": [
+    {
+      "role": "system",
+      "content": "你是智能体集群团队的一员..."
+    },
+    {
+      "role": "user",
+      "content": "来自 Team Leader 的任务发布\nid: task_001\n\n<Team Leader>\n<Task>\n请为项目设计前端配色方案...\n</Task>\n</Team Leader>",
+      "message_id": "msg_user_001"
+    },
+    {
+      "role": "assistant",
+      "content": "我先分析一下现有设计风格...",
+      "message_id": "msg_assistant_001"
+    },
+    {
+      "role": "user",
+      "content": "来自 Team Leader 的消息\nid: msg_tl_001\n\n<Team Leader>\n<Message>\n先不要创建 API...\n</Message>\n</Team Leader>",
+      "message_id": "msg_user_002"
+    },
+    {
+      "role": "assistant",
+      "content": "好的，我先确认现有 auth 模块...",
+      "message_id": "msg_assistant_002"
+    }
+  ]
+}
+```
+
+---
+
+## 8. 持久化策略
+
+### 8.1 保存时机
+
+- 每次模型调用前保存子智能体 metadata 和 messages
+- 每次工具调用后保存
+- 每次状态变更时保存
+- 每次收到外部消息并处理后保存
+
+### 8.2 原子写入
+
+参考 `ConversationManager._atomic_write_json`，使用临时文件 + replace：
+
+```python
+def _atomic_write_json(path: Path, data: dict):
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(path)
+```
+
+### 8.3 索引
+
+参考 `ConversationManager` 的索引机制，在 `conversations/index.json` 中维护会话列表：
+
+```json
+{
+  "conv_20260711_210000_001": {
+    "title": "多智能体任务：设计前端",
+    "created_at": "2026-07-11T21:00:00",
+    "updated_at": "2026-07-11T21:30:00",
+    "agent_count": 3
+  }
+}
+```
+
+---
+
+## 9. 与现有 ConversationManager 的关系
+
+多智能体模式实现自己的 `MultiAgentConversationStore`，但：
+
+- 数据格式与 `ConversationManager` 保持一致
+- 文件结构与 `ConversationManager` 类似
+- 不修改 `utils/conversation_manager/` 任何文件
+- 可以复制 `ConversationManager` 的 CRUD 代码到 `MultiAgentConversationStore`
+
+---
+
+## 10. 实现位置
+
+- 角色存储：`modules/multi_agent/agent_store.py`
+- 会话存储：`modules/multi_agent/conversation_store.py`
+- 全局状态：`modules/multi_agent/manager.py`

docs/multi_agent_mode/06_implementation_plan.md

@@ -0,0 +1,235 @@
+# 多智能体模式实现计划
+
+> 实现顺序不作为严格 phase，而是按依赖关系自然推进。  
+> 核心原则：完全隔离、复制改造、底层复用。
+
+---
+
+## 1. 目录与文件规划
+
+### 1.1 后端代码
+
+```
+modules/multi_agent/
+├── __init__.py
+├── terminal.py                  # MultiAgentTerminal
+├── manager.py                   # 多智能体会话与全局状态管理
+├── agent_store.py               # 角色配置加载与保存
+├── conversation_store.py        # 多智能体会话存储
+├── message_router.py            # 消息路由与待处理队列
+├── sub_agent_task.py            # MultiAgentSubAgentTask
+├── sub_agent_manager.py         # MultiAgentSubAgentManager
+├── prompts.py                   # prompt 模板
+└── tools/
+    ├── __init__.py
+    ├── master_tools.py          # Team Leader 工具定义
+    ├── agent_tools.py           # 子智能体工具定义
+    └── tool_handlers.py         # 工具处理函数
+```
+
+### 1.2 前端代码
+
+```
+static/src/views/MultiAgentView.vue
+static/src/components/multi-agent/
+├── ChatPanel.vue
+├── AgentList.vue
+├── MessageBubble.vue
+└── CreateAgentDialog.vue
+```
+
+### 1.3 设计文档
+
+```
+docs/multi_agent_mode/
+├── 01_overview.md
+├── 02_message_protocol.md
+├── 03_tool_definitions.md
+├── 04_message_routing.md
+├── 05_data_model.md
+├── 06_implementation_plan.md
+└── 07_existing_code_analysis.md
+```
+
+### 1.4 数据目录
+
+```
+~/.astrion/astrion/host/mutiagents/
+├── agents/
+├── conversations/
+└── state.json
+```
+
+---
+
+## 2. 实现步骤
+
+### Step 1：基础设施
+
+1. 创建 `modules/multi_agent/` 包
+2. 创建 `docs/multi_agent_mode/` 目录（已完成）
+3. 创建 `~/.astrion/astrion/host/mutiagents/` 数据目录
+4. 预置 4 个角色文件到 `agents/`
+
+### Step 2：角色配置
+
+1. 实现 `agent_store.py`
+   - 加载角色 Frontmatter
+   - 保存自定义角色
+   - 列出所有角色
+   - 构建完整 prompt（基础 prompt + 自定义 prompt）
+
+2. 预置角色：
+   - `ui-operator`
+   - `full-stack-engineer`
+   - `code-reviewer`
+   - `researcher`
+
+### Step 3：子智能体改造
+
+1. 实现 `MultiAgentSubAgentTask`（继承 `SubAgentTask`）
+   - 覆盖 `_run_loop`，使用多智能体工具列表
+   - 覆盖系统提示词生成
+   - 捕获 assistant 输出并转发到主智能体
+   - 维护 `pending_messages` 队列
+   - 维护 `pending_tool_calls` 等待列表
+   - 支持 inline 消息注入
+   - 支持自然结束（不依赖 finish_task）
+
+2. 实现 `MultiAgentSubAgentManager`（继承 `SubAgentManager`）
+   - 创建 `MultiAgentSubAgentTask` 实例
+   - 管理所有子智能体状态
+   - 提供查询活跃子智能体接口
+   - 提供终止实例接口
+
+### Step 4：消息路由
+
+1. 实现 `message_router.py`
+   - `route_message(target_agent_id, message)`
+   - 根据目标状态选择 inline / 工具结果返回 / 触发新任务
+   - 处理边界情况（最后一轮输出时收到消息）
+   - 批量消费待处理消息
+
+2. 实现消息格式化函数
+   - `format_task_message(display_name, content)`
+   - `format_output_message(display_name, content)`
+   - `format_ask_message(display_name, content, message_id)`
+   - `format_message_message(display_name, content, message_id)`
+   - `format_answer_message(display_name, content, message_id)`
+
+### Step 5：主智能体 Terminal
+
+1. 实现 `MultiAgentTerminal`（基于 `MainTerminal` 复制）
+   - 移除旧版子智能体工具
+   - 添加多智能体专用工具
+   - 使用 `MultiAgentSubAgentManager`
+   - 使用 `MultiAgentConversationStore`
+   - 实现 `answer_sub_agent_question` 等工具处理
+
+2. 实现工具处理函数
+   - `create_sub_agent`
+   - `terminate_sub_agent`
+   - `send_message_to_sub_agent`
+   - `ask_sub_agent`
+   - `answer_sub_agent_question`
+   - `list_active_sub_agents`
+   - `get_sub_agent_status`
+   - `create_custom_agent`
+   - `list_agents`
+
+### Step 6：会话存储
+
+1. 实现 `MultiAgentConversationStore`
+   - 复制 `ConversationManager` 的 CRUD 逻辑
+   - 数据目录指向 `~/.astrion/astrion/host/mutiagents/conversations/`
+   - 保存主智能体对话
+   - 保存每个子智能体对话
+
+### Step 7：前端页面
+
+1. 创建 `MultiAgentView.vue`
+   - 类似现有 ChatView，但专门用于多智能体模式
+   - 支持消息气泡按角色/类型渲染
+   - 支持显示活跃子智能体列表
+   - 支持创建子智能体
+
+2. 创建组件
+   - `MessageBubble.vue`：渲染统一消息格式
+   - `AgentList.vue`：显示子智能体状态
+   - `CreateAgentDialog.vue`：创建自定义角色
+
+3. 添加路由 `/multiagent/new`
+
+### Step 8：入口
+
+1. 登录页添加「多智能体模式 beta」按钮
+2. 点击后跳转到 `/multiagent/new`
+3. 初始化 `MultiAgentTerminal`
+
+### Step 9：联调测试
+
+1. 测试创建子智能体
+2. 测试子智能体自然输出转发
+3. 测试 `send_message_to_sub_agent` 运行中引导
+4. 测试 `ask_master` / `answer_sub_agent_question`
+5. 测试 `ask_other_agent` / `answer_other_agent`
+6. 测试子智能体对话持久化
+7. 测试角色创建与保存
+
+---
+
+## 3. 代码隔离清单
+
+| 现有文件 | 处理方式 |
+|---------|---------|
+| `core/main_terminal.py` | 复制为 `modules/multi_agent/terminal.py` |
+| `core/main_terminal_parts/tools_definition/agent_tools.py` | 复制改造为 `modules/multi_agent/tools/master_tools.py` |
+| `core/main_terminal_parts/tools_execution.py` | 复制需要的部分到 `modules/multi_agent/terminal.py` |
+| `modules/sub_agent/manager.py` | 继承创建 `modules/multi_agent/sub_agent_manager.py` |
+| `modules/sub_agent/task.py` | 继承创建 `modules/multi_agent/sub_agent_task.py` |
+| `modules/sub_agent/toolkit.py` | 复制改造为 `modules/multi_agent/tools/agent_tools.py` |
+| `modules/sub_agent/prompts.py` | 复制改造为 `modules/multi_agent/prompts.py` |
+| `utils/conversation_manager/*.py` | 复制改造为 `modules/multi_agent/conversation_store.py` |
+| `server/chat_flow.py` | 参考实现，为 `/multiagent` 创建新的 API 入口 |
+| `server/chat_flow_task_support.py` | 参考 `inject_runtime_user_message` 实现多智能体消息注入 |
+| `static/src/views/ChatView.vue` | 复制改造为 `static/src/views/MultiAgentView.vue` |
+
+---
+
+## 4. 复用点清单
+
+| 能力 | 复用方式 |
+|------|---------|
+| 模型调用 | `DeepSeekClient` |
+| 工具执行底层 | `WebTerminal.handle_tool_call` 的执行链路 |
+| 文件/终端/搜索等工具 | 现有工具函数 |
+| 沙箱/权限 | `evaluate_tool_permission` |
+| 对话存储格式 | `ConversationManager` 的 JSON 结构 |
+| 原子写入 | `_atomic_write_json` 模式 |
+| 前端组件 | 复制 ChatView 改造 |
+
+---
+
+## 5. 风险与应对
+
+| 风险 | 应对 |
+|------|------|
+| 子智能体消息丢失 | 待处理队列持久化 + 唯一 id + 消费确认 |
+| 子智能体状态错乱 | 状态机清晰 + reconcile 机制 |
+| 主智能体上下文爆炸 | 子智能体只汇报关键步骤，详细内容放文件 |
+| 多实例并发冲突 | 每个实例独立上下文，独立存储 |
+| 与现有代码耦合 | 严格隔离，复制改造 |
+
+---
+
+## 6. 验收标准
+
+1. 登录页有「多智能体模式 beta」按钮
+2. 点击后进入 `/multiagent/new`
+3. 可以创建至少 2 个不同角色的子智能体
+4. 子智能体输出自动显示在主对话中
+5. Team Leader 可以运行中引导子智能体
+6. 子智能体可以向 Team Leader 提问并收到回答
+7. 子智能体可以向其他子智能体提问并收到回答
+8. 子智能体对话完整保存，刷新后可恢复
+9. 现有单智能体模式不受影响

docs/multi_agent_mode/07_existing_code_analysis.md

@@ -0,0 +1,277 @@
+# 多智能体模式：现有代码分析
+
+> 本文档梳理实现多智能体模式需要理解的现有代码，为复制改造提供依据。
+
+---
+
+## 1. 子智能体实现
+
+### 1.1 核心文件
+
+```
+modules/sub_agent/
+├── __init__.py
+├── manager.py          # SubAgentManager
+├── task.py             # SubAgentTask
+├── toolkit.py          # 工具定义
+├── prompts.py          # 提示词
+├── state.py            # 状态管理
+├── stats.py            # 统计
+├── creation.py         # 创建参数
+└── tools.py            # 本地工具实现
+```
+
+### 1.2 SubAgentManager（manager.py）
+
+- 在主进程内以独立事件循环运行子智能体协程
+- `create_sub_agent()` 创建并启动任务
+- `wait_for_completion()` 阻塞等待完成
+- `terminate_sub_agent()` 强制终止
+- `poll_updates()` 检查已完成任务
+- `execute_tool_for_sub_agent()` 代理工具执行，复用主进程链路
+- `tasks` 字典保存所有任务状态
+
+多智能体模式可继承点：
+- 创建 `MultiAgentSubAgentManager`，重写 `create_sub_agent` 以创建 `MultiAgentSubAgentTask`
+- 扩展任务记录字段：`role_id`、`display_name`、`pending_messages`、`pending_tool_calls`
+- 扩展查询接口：`list_active_sub_agents()`、`get_sub_agent_status()`
+
+### 1.3 SubAgentTask（task.py）
+
+- `_run_loop()`：LLM 主循环，最多 50 轮
+- `_call_model()`：流式调用模型
+- `_execute_tool()`：通过 manager 执行工具
+- `_finalize_task()`：任务结束时保存 output.json、stats.json、conversation.json
+- `FINISH_TOOL`：必须调用 finish_task 才结束
+
+多智能体模式改造点：
+- 移除 `FINISH_TOOL` 依赖，自然结束输出即任务完成
+- 在 `_run_loop` 中每轮模型调用前消费 `pending_messages`
+- 捕获 assistant 输出并转发到主智能体对话
+- 新增 `ask_master`、`ask_other_agent`、`answer_other_agent` 工具处理
+- 维护 `pending_tool_calls`，支持阻塞等待回答
+
+### 1.4 工具定义（toolkit.py）
+
+现有 8 个工具：
+- `read_file`
+- `write_file`
+- `edit_file`
+- `run_command`
+- `web_search`
+- `extract_webpage`
+- `search_workspace`
+- `read_mediafile`
+
+多智能体模式可复用这些工具定义，新增通信工具。
+
+### 1.5 提示词（prompts.py）
+
+- `build_user_message()`：给子智能体的任务消息
+- `build_system_prompt()`：子智能体系统提示词
+
+多智能体模式需要：
+- 新的 `build_system_prompt()`，包含团队规则
+- 新的 `build_user_message()`，使用统一消息格式
+- 角色 prompt 拼接函数
+
+---
+
+## 2. 后台任务通知池机制
+
+### 2.1 核心文件
+
+- `server/chat_flow_task_support.py`
+- `server/chat_flow_task_main.py`
+- `server/chat_flow_tool_loop.py`
+
+### 2.2 inject_runtime_user_message
+
+位置：`server/chat_flow_task_support.py`
+
+功能：运行期/空闲期统一向对话插入一条 user 消息。
+
+关键参数：
+- `web_terminal`：终端实例
+- `messages`：当前运行中的消息列表（inline 时用）
+- `text`：消息文本
+- `source`：消息来源，如 `sub_agent`
+- `inline`：True 表示运行期插入，不触发新任务
+- `persist`：是否持久化到对话历史
+
+多智能体模式参考点：
+- 子智能体输出转发到主智能体时，使用类似机制
+- 但消息格式改为统一 XML 格式，不使用 `[系统通知|sub_agent]` 前缀
+
+### 2.3 process_sub_agent_updates
+
+位置：`server/chat_flow_task_support.py`
+
+功能：轮询子智能体完成状态，把结果插入当前对话上下文。
+
+两种模式：
+- `inline=True`：运行期间，插入 `messages` 不触发新任务
+- `inline=False`：空闲期间，触发后续任务
+
+多智能体模式参考点：
+- 子智能体自然输出捕获后，可以 inline 插入主智能体 `messages`
+- 子智能体空闲时收到的消息，作为 user 消息触发新任务
+
+### 2.4 _collect_pending_completion_notices
+
+位置：`server/chat_flow_task_main.py`
+
+功能：从子智能体和后台命令两路统一取出所有待通知项，按时间排序，一次性处理。
+
+关键设计：
+- 取出时即就地标记 `notified`，防止重复消费
+- 返回多条通知时，前 N-1 条作为前置通知，最后一条触发新任务
+
+多智能体模式参考点：
+- 每个子智能体维护自己的待处理消息队列
+- 消费时批量取出，避免多次触发新任务
+- 使用唯一 id 标记已消费
+
+### 2.5 poll_completion_notifications
+
+位置：`server/chat_flow_task_main.py`
+
+功能：统一轮询器，单工作区只 spawn 一个，避免并发冲突。
+
+多智能体模式参考点：
+- 多智能体模式也需要一个类似的通知/消息处理循环
+- 但消息源更多（Team Leader → Agent、Agent → Agent、Agent → Team Leader）
+
+---
+
+## 3. 主智能体工具调用链路
+
+### 3.1 工具定义
+
+位置：`core/main_terminal_parts/tools_definition/agent_tools.py`
+
+现有主智能体子智能体工具：
+- `create_sub_agent`
+- `close_sub_agent`
+- `terminate_sub_agent`
+- `get_sub_agent_status`
+
+多智能体模式需要移除这些，新增自己的工具定义。
+
+### 3.2 工具执行
+
+位置：`core/main_terminal_parts/tools_execution.py` 中 `handle_tool_call`
+
+- 参数预检查
+- 权限检查
+- 根据 tool_name 分发到具体处理函数
+- 返回 JSON 字符串
+
+多智能体模式参考点：
+- `MultiAgentTerminal.handle_tool_call` 中增加多智能体工具的分支
+- 子智能体工具处理函数放在 `modules/multi_agent/tools/tool_handlers.py`
+
+### 3.3 WebTerminal 广播
+
+位置：`core/web_terminal.py`
+
+- `handle_tool_call()` 覆盖父类，广播 `tool_execution_start` / `tool_status` / `tool_execution_complete`
+- `broadcast()` 发送 WebSocket 事件
+
+多智能体模式参考点：
+- `MultiAgentTerminal` 可继承 `WebTerminal` 或 `MainTerminal`
+- 保留广播能力
+
+---
+
+## 4. 对话上下文管理
+
+### 4.1 ContextManager
+
+位置：`utils/context_manager/`
+
+- `ConversationMixin.start_new_conversation()`：创建新对话
+- `ConversationMixin.load_conversation_by_id()`：加载对话
+- `ConversationMixin.save_current_conversation()`：保存当前对话
+
+多智能体模式参考点：
+- 创建 `MultiAgentContextManager` 或直接用 `MultiAgentConversationStore`
+- 保存格式与现有 `messages.json` 一致
+
+### 4.2 ConversationManager
+
+位置：`utils/conversation_manager/`
+
+- `crud_mixin.py`：`create_conversation`、`save_conversation`、`load_conversation`
+- `path_mixin.py`：文件路径管理
+- `index_mixin.py`：索引管理
+
+多智能体模式参考点：
+- 复制 `ConversationManager` 的实现到 `MultiAgentConversationStore`
+- 修改数据目录为 `~/.astrion/astrion/host/mutiagents/conversations/`
+
+---
+
+## 5. Skill 归档机制
+
+### 5.1 核心文件
+
+`modules/skills_manager.py`
+
+### 5.2 关键函数
+
+- `validate_skill_directory()`：验证 skill 目录
+- `archive_skill_directory()`：移动 skill 到归档目录
+- `_parse_frontmatter()`：解析 YAML Frontmatter
+- `_scan_skills_catalog()`：扫描 skill 目录
+
+多智能体模式参考点：
+- 角色配置使用类似的 Frontmatter 格式
+- 角色归档目录：`~/.astrion/astrion/host/mutiagents/agents/`
+- 可以复制 `_parse_frontmatter`、`_scan_skills_catalog` 的实现到 `agent_store.py`
+
+---
+
+## 6. 前端消息渲染
+
+### 6.1 现有机制
+
+- `server/chat_flow_task_support.py` 中 `inject_runtime_user_message` 发送 `user_message` 事件
+- 前端 `messaging.ts` 处理 `user_message` 事件
+- 根据 `message_source`、`visibility`、`starts_work` 等 metadata 渲染
+
+### 6.2 多智能体模式改造点
+
+- 多智能体消息也发送 `user_message` 事件
+- 前端根据消息内容中的 XML 解析出角色、类型、内容
+- 渲染为特殊气泡，不显示 XML 标签
+
+---
+
+## 7. 关键接口总结
+
+| 能力 | 现有实现位置 | 多智能体模式实现位置 |
+|------|------------|-------------------|
+| 子智能体创建/管理 | `modules/sub_agent/manager.py` | `modules/multi_agent/sub_agent_manager.py` |
+| 子智能体运行循环 | `modules/sub_agent/task.py` | `modules/multi_agent/sub_agent_task.py` |
+| 子智能体工具 | `modules/sub_agent/toolkit.py` | `modules/multi_agent/tools/agent_tools.py` |
+| 子智能体提示词 | `modules/sub_agent/prompts.py` | `modules/multi_agent/prompts.py` |
+| 主智能体工具定义 | `core/main_terminal_parts/tools_definition/agent_tools.py` | `modules/multi_agent/tools/master_tools.py` |
+| 主智能体工具执行 | `core/main_terminal_parts/tools_execution.py` | `modules/multi_agent/terminal.py` |
+| 运行时消息注入 | `server/chat_flow_task_support.py` | `modules/multi_agent/message_router.py` |
+| 通知池轮询 | `server/chat_flow_task_main.py` | `modules/multi_agent/message_router.py` |
+| 对话存储 | `utils/conversation_manager/` | `modules/multi_agent/conversation_store.py` |
+| 角色归档 | `modules/skills_manager.py` | `modules/multi_agent/agent_store.py` |
+| 前端页面 | `static/src/views/ChatView.vue` | `static/src/views/MultiAgentView.vue` |
+
+---
+
+## 8. 实现注意事项
+
+1. **不要修改现有文件**：所有改造在 `modules/multi_agent/` 中完成，通过继承或复制实现。
+2. **状态同步**：子智能体状态变更时需要同步更新 `metadata.json`。
+3. **消息不丢失**：待处理消息队列需要持久化。
+4. **上下文隔离**：每个子智能体独立 messages，不要互相污染。
+5. **模型工具列表**：每轮模型调用前需要重新构造工具列表，确保多智能体通信工具可用。
+6. **自然结束检测**：子智能体某轮没有工具调用且 assistant 输出为空时，认为本轮结束。
+7. **阻塞问答超时**：`ask_master` / `ask_other_agent` 需要设置合理超时，避免永久阻塞。

modules/api_user_manager.py

@@ -123,8 +123,8 @@ class ApiUserManager:
         project_path = work_root / "project"
         data_dir = work_root / "data"
         logs_dir = work_root / "logs"
-        uploads_dir = project_path / ".agents" / "user_upload"
-        skills_dir = project_path / ".agents" / "skills"
+        uploads_dir = project_path / ".astrion" / "user_upload"
+        skills_dir = project_path / ".astrion" / "skills"
 
         for path in (project_path, data_dir, logs_dir, uploads_dir, skills_dir, shared_dir, prompts_dir, personalization_dir):
             path.mkdir(parents=True, exist_ok=True)

modules/multi_agent/__init__.py

@@ -0,0 +1,53 @@
+"""多智能体模式核心实现。
+
+由 conversations metadata.multi_agent_mode = true 触发启用，
+不另起隔离链路，直接复用现有 MainTerminal、SubAgentManager、SubAgentTask
+但通过对话级开关注入多智能体版工具集、prompt、消息路由。
+
+关键组件：
+- RoleConfig：角色 Markdown Frontmatter 解析与归档
+- MultiAgentState：一个多智能体会话的运行态状态机
+- 消息格式构造：format_multi_agent_message
+- 工具定义：master 侧、sub_agent 侧扩展
+- prompt 构造：build_multi_agent_master_prompt / build_multi_agent_sub_agent_prompt
+"""
+from __future__ import annotations
+
+from .state import MultiAgentState, format_multi_agent_message
+from .role_store import (
+    RoleConfig,
+    load_preset_role,
+    list_roles,
+    save_custom_role,
+    build_role_system_prompt,
+)
+from .prompts import (
+    build_multi_agent_master_prompt,
+    build_multi_agent_sub_agent_prompt,
+    MULTI_AGENT_MASTER_PROMPT_BODY,
+    MULTI_AGENT_SUB_AGENT_PROMPT_BODY,
+)
+from .tools import (
+    MULTI_AGENT_MASTER_TOOLS,
+    MULTI_AGENT_SUB_AGENT_TOOLS,
+    build_master_tools_for_conversation,
+    build_sub_agent_tools_for_role,
+)
+
+__all__ = [
+    "MultiAgentState",
+    "format_multi_agent_message",
+    "RoleConfig",
+    "load_preset_role",
+    "list_roles",
+    "save_custom_role",
+    "build_role_system_prompt",
+    "build_multi_agent_master_prompt",
+    "build_multi_agent_sub_agent_prompt",
+    "MULTI_AGENT_MASTER_PROMPT_BODY",
+    "MULTI_AGENT_SUB_AGENT_PROMPT_BODY",
+    "MULTI_AGENT_MASTER_TOOLS",
+    "MULTI_AGENT_SUB_AGENT_TOOLS",
+    "build_master_tools_for_conversation",
+    "build_sub_agent_tools_for_role",
+]

modules/multi_agent/debug_logger.py

@@ -0,0 +1,30 @@
+"""多智能体模式专用调试日志。
+
+把所有子智能体与主智能体之间的消息往来、注入、转发、工具调用记录下来，
+便于排查循环/重复输出等问题。日志写入 {LOGS_DIR}/multi_agent_loop.log。
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from config.paths import LOGS_DIR
+
+
+_LOG_PATH = Path(LOGS_DIR) / "multi_agent_loop.log"
+
+
+def ma_debug(event: str, **kwargs: Any) -> None:
+    """追加一条结构化调试日志。"""
+    try:
+        _LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        payload = {"t": time.time(), "event": event}
+        for k, v in kwargs.items():
+            payload[k] = v
+        line = json.dumps(payload, ensure_ascii=False, default=str)
+        with open(_LOG_PATH, "a", encoding="utf-8") as f:
+            f.write(line + "\n")
+    except Exception:
+        pass

modules/multi_agent/prompts.py

@@ -0,0 +1,133 @@
+"""多智能体模式的系统提示词。
+
+所有 prompt 正文均从 prompts/multi_agent/ 下的文本文件加载，避免在代码中硬编码。
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+try:
+    from config import PROMPTS_DIR
+except ImportError:
+    import sys
+
+    project_root = Path(__file__).resolve().parents[2]
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+    from config import PROMPTS_DIR
+
+
+_MULTI_AGENT_PROMPTS_DIR = Path(PROMPTS_DIR) / "multi_agent"
+_TEMPLATE_CACHE: dict[str, str] = {}
+
+
+def _load_template(name: str) -> str:
+    """从 prompts/multi_agent/<name>.txt 加载模板，带缓存。"""
+    cached = _TEMPLATE_CACHE.get(name)
+    if cached is not None:
+        return cached
+
+    template_path = _MULTI_AGENT_PROMPTS_DIR / f"{name}.txt"
+    if not template_path.exists():
+        raise FileNotFoundError(f"多智能体 prompt 模板缺失: {template_path}")
+
+    content = template_path.read_text(encoding="utf-8")
+    _TEMPLATE_CACHE[name] = content
+    return content
+
+
+def _format_template(name: str, **kwargs) -> str:
+    """加载模板并用 str.format 填充占位符。"""
+    template = _load_template(name)
+    return template.format(**kwargs)
+
+
+# 为兼容外部仍可通过常量访问正文，但值来自文件；首次访问时加载。
+def __getattr__(name: str) -> str:
+    if name == "MULTI_AGENT_MASTER_PROMPT_BODY":
+        return _load_template("master")
+    if name == "MULTI_AGENT_SUB_AGENT_PROMPT_BODY":
+        return _load_template("sub_agent")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def build_multi_agent_master_prompt(workspace_path: str, base: str = "") -> str:
+    """构造主智能体（Team Leader）的系统提示词。
+
+    `base` 一般为现有 MainTerminal 的 base 提示词（环境/工具概览等），
+    我们在末尾追加多智能体模式专属正文。
+    """
+    body = _load_template("master")
+    if base and base.strip():
+        return f"{base.rstrip()}\n\n{body}\n"
+    return f"{body}\n"
+
+
+def build_multi_agent_sub_agent_prompt(
+    role_body: str,
+    display_name: str,
+    workspace_path: str,
+    *,
+    data_dir: str = "",
+    sandbox_mode: str = "",
+) -> str:
+    """构造子智能体的系统提示词。
+
+    `role_body` 为该角色 Markdown 文件 frontmatter 之后的自定义 prompt。
+    `display_name` 为该实例的显示名（如 `UI Operator_1`）。
+    `workspace_path` 为工作区路径，用于注入动态上下文。
+    `data_dir` 为数据目录路径，用于推断 private skills 目录。
+    `sandbox_mode` 为沙箱模式（sandbox/direct/host/docker）。
+
+    所有动态信息在子智能体创建那一刻快照写入，后续冻结不更新。
+    """
+    # 角色专属 prompt（模板正文）
+    role_prompt = _format_template("sub_agent", display_name=display_name, role_body=role_body.strip())
+
+    # 动态上下文（AGENTS.md / 执行环境 / 工作区信息 / skills / 项目记忆等）
+    try:
+        from modules.multi_agent.sub_agent_context import build_sub_agent_dynamic_context
+        dynamic_context = build_sub_agent_dynamic_context(
+            workspace_path,
+            data_dir=data_dir,
+            sandbox_mode=sandbox_mode,
+        )
+    except Exception:
+        dynamic_context = ""
+
+    if dynamic_context:
+        return f"{role_prompt.rstrip()}\n\n---\n\n{dynamic_context}\n"
+    return f"{role_prompt}\n"
+
+
+def build_available_agents_prompt() -> str:
+    """构造「可用的子智能体角色」动态 prompt。
+
+    列出当前可创建的所有角色名称与说明，供 Team Leader 参考。
+    若没有任何可用角色，返回空字符串。
+    """
+    try:
+        from modules.multi_agent.role_store import list_roles
+
+        roles = list_roles()
+    except Exception:
+        return ""
+
+    if not roles:
+        return ""
+
+    lines: List[str] = []
+    for role in roles:
+        name = getattr(role, "name", "") or ""
+        description = getattr(role, "description", "") or ""
+        role_id = getattr(role, "role_id", "") or ""
+        if description:
+            lines.append(f"- {name}（role_id: {role_id}）：{description}")
+        else:
+            lines.append(f"- {name}（role_id: {role_id}）")
+
+    if not lines:
+        return ""
+
+    return _format_template("available_agents", agents_list="\n".join(lines))

modules/multi_agent/role_store.py

@@ -0,0 +1,398 @@
+"""多智能体角色存储与解析。
+
+三层结构：
+
+1. **源码树预设**：``multi_agent_roles/``（随版本分发，只读种子）
+2. **运行态预设**：
+   - host 模式 = ``host/mutiagents/agents/``（同时也是自定义目录）
+   - web 模式 = ``web/mutiagents/agents/``
+3. **用户自定义**（仅 web 模式按用户隔离）：
+   - web 模式 = ``web/users/<user>/personal/mutiagents/agents/``
+   - host 模式 = 和预设同目录
+
+启动时调用 `sync_preset_roles()` 把源码树预设同步到 host 和 web 两个运行态预设目录。
+
+**重要**：本模块不再依赖 `IS_HOST_MODE` 判断运行模式。
+调用方（API / tools_execution）通过参数显式传入 `runtime_dir` 和 `custom_dir`：
+- 不传则仅扫描源码树预设（最小安全回退）
+- host 模式：`runtime_dir` 和 `custom_dir` 指向同一目录
+- web 模式：`runtime_dir` 指向 web 预设目录，`custom_dir` 指向用户个人目录
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+try:
+    from config.paths import RUNTIME_ROOT, PRESET_ROLES_DIR, CUSTOM_ROLES_DIR, WEB_PRESET_ROLES_DIR
+except ImportError:
+    RUNTIME_ROOT = str(Path.home() / ".astrion" / "astrion")
+    PRESET_ROLES_DIR = ""
+    CUSTOM_ROLES_DIR = ""
+    WEB_PRESET_ROLES_DIR = ""
+
+FRONTMATTER_RE = re.compile(r"^---\s*\n(?P<body>.*?)\n---\s*\n(?P<rest>.*)$", re.S)
+
+
+# ----- 目录推断 -----
+
+def _source_preset_dir() -> Path:
+    """源码树预设角色目录（只读种子）。"""
+    return Path(PRESET_ROLES_DIR).expanduser().resolve()
+
+
+def _host_runtime_dir() -> Path:
+    """host 模式运行态目录（预设+自定义同目录）。"""
+    return Path(CUSTOM_ROLES_DIR).expanduser().resolve()
+
+
+def _web_runtime_dir() -> Path:
+    """web 模式运行态预设目录。"""
+    return Path(WEB_PRESET_ROLES_DIR).expanduser().resolve()
+
+
+def infer_custom_roles_dir(data_dir: str | Path | None) -> Optional[Path]:
+    """从工作区 data_dir 推断用户自定义角色目录。
+
+    - data_dir 包含 ``/web/users/`` → web 模式，返回 ``users/<user>/personal/mutiagents/agents``
+    - 其他情况 → host 模式，返回 host 运行态目录
+    """
+    if not data_dir:
+        return _host_runtime_dir()
+    data_path = str(Path(data_dir).expanduser().resolve())
+    if "/web/users/" in data_path:
+        # web 模式：按用户隔离
+        dp = Path(data_path).resolve()
+        # users/<user>/projects/<project_id>/data -> users/<user>/personal/mutiagents/agents
+        if dp.name == "data" and dp.parent.parent.name == "projects":
+            user_root = dp.parent.parent.parent
+            return (user_root / "personal" / "mutiagents" / "agents").resolve()
+        # 兼容旧/其他布局
+        if dp.name == "data" and dp.parent.parent.name == "project":
+            user_root = dp.parent.parent.parent
+            return (user_root / "personal" / "mutiagents" / "agents").resolve()
+        return (dp.parent / "mutiagents" / "agents").resolve()
+    # host 模式
+    return _host_runtime_dir()
+
+
+def _preset_role_ids() -> Set[str]:
+    """返回源码树预设角色 id 集合（用于区分自定义角色）。"""
+    src = _source_preset_dir()
+    if not src.exists():
+        return set()
+    return {p.stem for p in src.glob("*.md") if p.is_file()}
+
+
+def _ensure_dir(path: Path) -> Path:
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+# ----- 启动同步 -----
+
+def sync_preset_roles() -> None:
+    """启动时把源码树预设角色同步到 host 和 web 两个运行态预设目录。
+
+    - 目录不存在则创建并复制全部预设角色。
+    - 文件已存在则不覆盖（可能是用户已改过的运行态副本）。
+    """
+    src = _source_preset_dir()
+    if not src.exists() or not src.is_dir():
+        return
+
+    preset_files = {p: p.name for p in src.glob("*.md") if p.is_file()}
+    if not preset_files:
+        return
+
+    rt_root = Path(RUNTIME_ROOT).expanduser().resolve()
+    for target_dir in [_host_runtime_dir(), _web_runtime_dir()]:
+        target = target_dir.expanduser().resolve()
+        # 安全检查：目标必须在运行态根下
+        try:
+            target.relative_to(rt_root)
+        except ValueError:
+            continue
+        target.mkdir(parents=True, exist_ok=True)
+        for src_file, name in preset_files.items():
+            dst = target / name
+            if not dst.exists():
+                shutil.copy2(src_file, dst)
+
+
+# ----- Frontmatter 解析 -----
+
+def _parse_frontmatter(text: str) -> tuple[Dict[str, Any], str]:
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return {}, text
+    raw_meta = m.group("body") or ""
+    body = m.group("rest") or ""
+    meta: Dict[str, Any] = {}
+    current_key: Optional[str] = None
+    for line in raw_meta.splitlines():
+        if not line.strip():
+            continue
+        if line.startswith("  - ") or line.startswith("- "):
+            value = line.lstrip(" ").lstrip("- ").strip()
+            if current_key and isinstance(meta.get(current_key), list):
+                meta[current_key].append(value)
+            continue
+        if ":" in line:
+            k, v = line.split(":", 1)
+            k = k.strip()
+            v = v.strip().strip('"').strip("'")
+            if v:
+                meta[k] = v
+                current_key = None
+            else:
+                meta[k] = []
+                current_key = k
+    return meta, body.strip()
+
+
+# ----- RoleConfig -----
+
+class RoleConfig:
+    """一个多智能体角色配置。"""
+
+    __slots__ = (
+        "role_id",
+        "name",
+        "description",
+        "body_prompt",
+        "model_key",
+        "thinking_mode",
+        "skills",
+        "source_file",
+        "is_custom",
+    )
+
+    def __init__(
+        self,
+        *,
+        role_id: str,
+        name: str,
+        description: str = "",
+        body_prompt: str = "",
+        model_key: Optional[str] = None,
+        thinking_mode: str = "fast",
+        skills: Optional[List[str]] = None,
+        source_file: str = "",
+        is_custom: bool = False,
+    ):
+        self.role_id = role_id
+        self.name = name
+        self.description = description
+        self.body_prompt = body_prompt
+        self.model_key = model_key
+        self.thinking_mode = thinking_mode or "fast"
+        self.skills = list(skills or [])
+        self.source_file = source_file
+        self.is_custom = is_custom
+
+    def display_name(self, agent_id: int) -> str:
+        return f"{self.name}_{agent_id}"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "role_id": self.role_id,
+            "name": self.name,
+            "description": self.description,
+            "model_key": self.model_key,
+            "thinking_mode": self.thinking_mode,
+            "skills": self.skills,
+            "body_prompt": self.body_prompt,
+            "source_file": self.source_file,
+            "is_custom": self.is_custom,
+        }
+
+    def __repr__(self) -> str:
+        return f"<RoleConfig id={self.role_id} name={self.name} custom={self.is_custom}>"
+
+
+# ----- 文件级加载 -----
+
+def load_role_from_file(file_path: Path, is_custom: bool = False) -> Optional[RoleConfig]:
+    if not file_path.exists() or not file_path.is_file():
+        return None
+    text = file_path.read_text(encoding="utf-8")
+    meta, body = _parse_frontmatter(text)
+    if not meta.get("id") or not meta.get("name"):
+        return None
+    return RoleConfig(
+        role_id=str(meta["id"]),
+        name=str(meta["name"]),
+        description=str(meta.get("description") or ""),
+        body_prompt=body,
+        model_key=(str(meta["model"]) if meta.get("model") else None) or None,
+        thinking_mode=str(meta.get("thinking_mode") or "fast"),
+        skills=list(meta.get("skills") or []),
+        source_file=str(file_path),
+        is_custom=is_custom,
+    )
+
+
+# ----- 序列化 -----
+
+def _serialize_role(role: RoleConfig) -> str:
+    lines = ["---"]
+    lines.append(f"id: {role.role_id}")
+    lines.append(f"name: {role.name}")
+    if role.description:
+        desc = role.description.replace('"', '\\"')
+        lines.append(f'description: "{desc}"')
+    if role.model_key:
+        lines.append(f"model: {role.model_key}")
+    lines.append(f"thinking_mode: {role.thinking_mode or 'fast'}")
+    if role.skills:
+        lines.append("skills:")
+        for s in role.skills:
+            lines.append(f"  - {s}")
+    lines.append("---")
+    lines.append("")
+    lines.append(role.body_prompt or "")
+    return "\n".join(lines)
+
+
+# ----- 目录级加载 -----
+
+def _scan_roles_dir(dir_path: Path, is_custom: bool = False) -> List[RoleConfig]:
+    if not dir_path.exists() or not dir_path.is_dir():
+        return []
+    roles: List[RoleConfig] = []
+    for p in sorted(dir_path.glob("*.md")):
+        r = load_role_from_file(p, is_custom=is_custom)
+        if r and r.role_id:
+            roles.append(r)
+    return roles
+
+
+def _merge_roles(roles_lists: List[List[RoleConfig]]) -> List[RoleConfig]:
+    """合并多组角色，后者覆盖前者（同名 role_id 后者优先）。"""
+    merged: Dict[str, RoleConfig] = {}
+    order: List[str] = []
+    for roles in roles_lists:
+        for r in roles:
+            if r.role_id not in merged:
+                order.append(r.role_id)
+            merged[r.role_id] = r
+    return [merged[rid] for rid in order if rid in merged]
+
+
+def list_roles(
+    runtime_dir: Optional[str | Path] = None,
+    custom_dir: Optional[str | Path] = None,
+) -> List[RoleConfig]:
+    """列出全部角色。
+
+    合并顺序（后者覆盖前者）：
+    1. 运行态预设目录
+    2. 用户自定义目录（web 模式才有；host 模式与预设同目录，传一个即可）
+
+    ``is_custom`` 标记：不在源码树预设名单中的角色 = 自定义。
+
+    调用方应显式传入 ``custom_dir``：
+    - host 模式：传 `_host_runtime_dir()`（或省略，自动回退）
+    - web 模式：传入用户个人目录
+    """
+    # host 模式回退：不传任何目录时使用 host 运行态目录
+    if not runtime_dir and not custom_dir:
+        runtime_dir = _host_runtime_dir()
+
+    rt_dir = Path(runtime_dir).expanduser().resolve() if runtime_dir else None
+    c_dir = Path(custom_dir).expanduser().resolve() if custom_dir else None
+
+    preset_ids = _preset_role_ids()
+
+    # 只有一个目录（host 模式或 web 模式只传了 runtime_dir）
+    if not c_dir or (rt_dir and rt_dir == c_dir):
+        scan_dir = rt_dir or c_dir
+        if scan_dir:
+            all_roles = _scan_roles_dir(scan_dir)
+        else:
+            all_roles = []
+        for r in all_roles:
+            r.is_custom = r.role_id not in preset_ids
+        return all_roles
+
+    # web 模式：合并运行态预设 + 用户自定义
+    preset_roles = _scan_roles_dir(rt_dir, is_custom=False) if rt_dir else []
+    custom_roles = _scan_roles_dir(c_dir, is_custom=True)
+    merged = _merge_roles([preset_roles, custom_roles])
+    return merged
+
+
+def load_preset_role(
+    role_id: str,
+    runtime_dir: Optional[str | Path] = None,
+    custom_dir: Optional[str | Path] = None,
+) -> Optional[RoleConfig]:
+    """加载一个角色。先查用户自定义目录，再查运行态预设目录。"""
+    rt_dir = Path(runtime_dir).expanduser().resolve() if runtime_dir else None
+    c_dir = Path(custom_dir).expanduser().resolve() if custom_dir else None
+    preset_ids = _preset_role_ids()
+
+    # host 模式回退
+    if not rt_dir and not c_dir:
+        rt_dir = _host_runtime_dir()
+
+    # 先查自定义目录（web 模式且与 runtime_dir 不同）
+    if c_dir and rt_dir and c_dir != rt_dir:
+        f = c_dir / f"{role_id}.md"
+        r = load_role_from_file(f, is_custom=True)
+        if r:
+            return r
+
+    # 再查运行态/混合目录
+    scan_dir = rt_dir or c_dir
+    if scan_dir:
+        f = scan_dir / f"{role_id}.md"
+        r = load_role_from_file(f)
+        if r:
+            r.is_custom = r.role_id not in preset_ids
+            return r
+    return None
+
+
+def save_custom_role(
+    role: RoleConfig,
+    custom_dir: Optional[str | Path] = None,
+) -> Path:
+    """保存角色到自定义目录。不传 custom_dir 时回退到 host 运行态目录。"""
+    if custom_dir:
+        c_dir = Path(custom_dir).expanduser().resolve()
+    else:
+        c_dir = _host_runtime_dir()
+    _ensure_dir(c_dir)
+    f = c_dir / f"{role.role_id}.md"
+    f.write_text(_serialize_role(role), encoding="utf-8")
+    return f
+
+
+def delete_custom_role(
+    role_id: str,
+    custom_dir: Optional[str | Path] = None,
+) -> bool:
+    """删除用户自定义角色。不传 custom_dir 时回退到 host 运行态目录。"""
+    if custom_dir:
+        c_dir = Path(custom_dir).expanduser().resolve()
+    else:
+        c_dir = _host_runtime_dir()
+    f = c_dir / f"{role_id}.md"
+    if not f.exists():
+        return False
+    f.unlink(missing_ok=True)
+    return True
+
+
+def is_preset_role(role_id: str) -> bool:
+    """判断角色是否为预设角色（源码树种子中存在）。"""
+    return role_id in _preset_role_ids()
+
+
+def build_role_system_prompt(role: RoleConfig) -> str:
+    """生成子智能体的「专属 prompt」部分（frontmatter 之后的 body）。"""
+    return role.body_prompt or ""

modules/multi_agent/state.py

@@ -0,0 +1,506 @@
+"""多智能体会话状态机。
+
+一个 MultiAgentState 绑定到一个多智能体对话的 conversation_id，维护：
+- 已创建的子智能体实例（agent_id ↔ role_id ↔ display_name ↔ task_id ↔ status）
+- 待插入到主对话的待发 user 消息队列（pending_master_messages）
+- 主智能体工具调用 answer_sub_agent_question / answer_other_agent 写回答案的 futomap
+- 子智能体调用 ask_master / ask_other_agent 时挂起的 futomap
+
+关键约定（来自 .astrion/memory/multi_agent_mode_design.md）：
+- 消息格式：`来自 {显示名} 的{类型}\\nid: {消息id}\\n\\n<{显示名}>\\n<{标签}>\\n{内容}\\n</{标签}>\\n</{显示名}>`
+- 接收方决定插入方式：
+  - 子智能体 ask 阻塞等待 → main 调 answer_* 返回到工具结果
+  - 子智能体 idle 状态 → 主对话的 pending_master_messages 直接插入新轮 user 消息
+  - 子智能体 running 中 → inline 插入到当前末尾（在下一轮 model 调用前合并 messages）
+- 通信是「工具调用提问」+「回答返回到工具结果」；其他场景（输出/进度/完成/任务发布/消息/回答）
+  才以 user 消息格式插入对话。
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import uuid
+from asyncio import AbstractEventLoop
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from modules.multi_agent.debug_logger import ma_debug
+
+if TYPE_CHECKING:
+    from modules.sub_agent.task import SubAgentTask
+
+# ---------- 消息类型常量 ----------
+TYPE_TASK = "Task"               # 主→子 任务发布
+TYPE_OUTPUT = "Output"           # 子→主 进度/完成输出（统一）
+TYPE_ASK = "Ask"                 # 子→主 / 子→子 提问
+TYPE_ANSWER = "Answer"           # 主→子 / 子→子 回答（不插入对话，仅做工具结果）
+TYPE_MESSAGE = "Message"         # 任意方向 消息
+# 内部枚举到此
+
+QUESTION_PREFIX_ASK_MASTER = "ask_master"
+QUESTION_PREFIX_ASK_OTHER = "ask_other"
+
+
+def format_multi_agent_message(
+    *,
+    display_name: str,
+    msg_type: str,
+    content: str,
+    msg_id: Optional[str] = None,
+    target: Optional[str] = None,
+    extra_attrs: Optional[Dict[str, str]] = None,
+    msg_type_text: Optional[str] = None,
+    subtype: Optional[str] = None,
+) -> str:
+    """按统一格式构造 user 消息字符串。
+
+    Args:
+        display_name: 发出方显示名（如 UI Operator_1 / Team Leader）
+        msg_type: 消息类型，对应上方 TYPE_* 常量
+        content: 消息正文
+        msg_id: 消息 id；不传则自动生成
+        target: 接收方显示名（用于子→子 提问时标明对谁提问）
+        extra_attrs: 额外标签属性（如 question_id="ask_xxx"）
+        msg_type_text: 覆盖默认的中文消息类型文案（如"任务结束汇报"）
+        subtype: 渲染/分类使用的子类型（如 progress_output / completion_report / ask_master）
+    """
+    if not msg_id:
+        msg_id = f"msg_{uuid.uuid4().hex[:10]}"
+
+    type_label = msg_type_text or msg_type_to_text(msg_type)
+    # 第一行：自然语言前缀（含 target 标识）
+    if target:
+        prefix = f"来自 {display_name} 向 {target} 的{type_label}"
+    else:
+        prefix = f"来自 {display_name} 的{type_label}"
+
+    # 第二行：id
+    id_line = f"id: {msg_id}"
+
+    # 属性 attr 字符串
+    attrs = ""
+    if target:
+        attrs += f' target="{target}"'
+    if subtype:
+        attrs += f' subtype="{subtype}"'
+    if extra_attrs:
+        for k, v in extra_attrs.items():
+            attrs += f' {k}="{v}"'
+
+    # XML 包裹
+    tag = msg_type
+    xml = (
+        f"<{display_name}>\n"
+        f"<{tag}{attrs}>\n"
+        f"{content}\n"
+        f"</{tag}>\n"
+        f"</{display_name}>"
+    )
+
+    return f"{prefix}\n{id_line}\n\n{xml}"
+
+
+def msg_type_to_text(msg_type: str) -> str:
+    """把 TYPE_* 转为中文短语，用于 prompt 前缀。"""
+    mapping = {
+        TYPE_TASK: "任务发布",
+        TYPE_OUTPUT: "任务进度输出",
+        TYPE_ASK: "提问",
+        TYPE_ANSWER: "回答",
+        TYPE_MESSAGE: "消息",
+    }
+    return mapping.get(msg_type, msg_type)
+
+
+def build_master_dispatch_text(task: str, msg_id: Optional[str] = None) -> str:
+    """主智能体发布任务时插入到子智能体对话的 user 消息文本。"""
+    return format_multi_agent_message(
+        display_name="Team Leader",
+        msg_type=TYPE_TASK,
+        content=task,
+        msg_id=msg_id,
+    )
+
+
+# 子类型常量（用于前端渲染与后端分类）
+SUBTYPE_PROGRESS_OUTPUT = "progress_output"
+SUBTYPE_COMPLETION_REPORT = "completion_report"
+SUBTYPE_ASK_MASTER = "ask_master"
+SUBTYPE_ASK_OTHER = "ask_other"
+
+
+def build_sub_agent_output_text(display_name: str, content: str, msg_id: Optional[str] = None, *, is_final: bool = False) -> str:
+    """子智能体输出（进度或完成）插入到主对话的 user 消息文本。"""
+    return format_multi_agent_message(
+        display_name=display_name,
+        msg_type=TYPE_OUTPUT,
+        content=content,
+        msg_id=msg_id,
+        msg_type_text="任务结束汇报" if is_final else "任务进度输出",
+        subtype=SUBTYPE_COMPLETION_REPORT if is_final else SUBTYPE_PROGRESS_OUTPUT,
+    )
+
+
+def build_sub_agent_ask_master_text(display_name: str, question: str, question_id: str) -> str:
+    """子智能体向主智能体提问时插入到主对话的 user 消息文本。"""
+    return format_multi_agent_message(
+        display_name=display_name,
+        msg_type=TYPE_ASK,
+        content=question,
+        msg_id=question_id,
+        subtype=SUBTYPE_ASK_MASTER,
+    )
+
+
+def build_sub_agent_ask_other_text(
+    display_name: str,
+    target_display: str,
+    question: str,
+    question_id: str,
+) -> str:
+    """子智能体向另一个子智能体提问时插入到目标子智能体对话的文本。"""
+    return format_multi_agent_message(
+        display_name=display_name,
+        msg_type=TYPE_ASK,
+        content=question,
+        msg_id=question_id,
+        target=target_display,
+        subtype=SUBTYPE_ASK_OTHER,
+    )
+
+
+_MULTI_AGENT_MESSAGE_RE = re.compile(
+    r"^来自\s+(?P<display_name>.+?)\s+的(?P<type_text>.+?)\n"
+    r"id:\s*(?P<msg_id>\S+)\n\n"
+    r"<(?P=display_name)>\n"
+    r"<(?P<tag>\w+)(?P<attrs>[^>]*)>\n"
+    r"(?P<content>.*?)\n"
+    r"</(?P=tag)>\n"
+    r"</(?P=display_name)>$",
+    re.DOTALL,
+)
+
+
+def parse_multi_agent_message(text: str) -> Optional[Dict[str, str]]:
+    """解析标准多智能体消息格式。
+
+    返回字段：display_name, type_text, msg_id, tag, subtype, content。
+    若不是标准格式则返回 None。
+    """
+    if not text:
+        return None
+    m = _MULTI_AGENT_MESSAGE_RE.search(text)
+    if not m:
+        return None
+    attrs = m.group("attrs") or ""
+    subtype_match = re.search(r'subtype="([^"]+)"', attrs)
+    return {
+        "display_name": m.group("display_name").strip(),
+        "type_text": m.group("type_text").strip(),
+        "msg_id": m.group("msg_id").strip(),
+        "tag": m.group("tag").strip(),
+        "subtype": subtype_match.group(1) if subtype_match else "",
+        "content": m.group("content"),
+    }
+
+
+def build_master_message_to_sub_agent(message: str, msg_id: Optional[str] = None) -> str:
+    """主智能体 send_message_to_sub_agent 时插入子对话的 user 消息文本。"""
+    return format_multi_agent_message(
+        display_name="Team Leader",
+        msg_type=TYPE_MESSAGE,
+        content=message,
+        msg_id=msg_id,
+    )
+
+
+def build_master_answer_to_sub_agent(
+    display_name: str,
+    target_display: str,
+    answer: str,
+    question_id: str,
+) -> str:
+    """主智能体回答插入到子对话（仅当子智能体 not waiting 或 idle 时走 user 消息路径）。"""
+    return format_multi_agent_message(
+        display_name=display_name,
+        msg_type=TYPE_ANSWER,
+        content=answer,
+        msg_id=question_id,
+        target=target_display,
+        extra_attrs={"question_id": question_id},
+    )
+
+
+# ---------- 运行态状态机 ----------
+@dataclass
+class AgentInstance:
+    """一个多智能体会话中已创建的子智能体实例。"""
+
+    agent_id: int
+    role_id: str
+    display_name: str
+    task_id: str
+    status: str = "running"          # running / idle / terminated / failed / timeout
+    summary: str = ""
+    created_at: float = field(default_factory=lambda: datetime.now().timestamp())
+    last_output: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "agent_id": self.agent_id,
+            "role_id": self.role_id,
+            "display_name": self.display_name,
+            "task_id": self.task_id,
+            "status": self.status,
+            "summary": self.summary,
+            "created_at": self.created_at,
+            "last_output": self.last_output,
+        }
+
+
+class MultiAgentState:
+    """绑到一个 conversation_id 的多智能体运行态。
+
+    线程安全：所有 pubic 方法均假设在 SubAgentManager 的事件循环线程中调用，
+    或者由 chat task 主线程通过 manager 的 _run_coro 进入此循环。
+    跨线程访问通过 manager._run_coro 桥接，避免直接调用。
+    """
+
+    def __init__(self, conversation_id: str):
+        self.conversation_id = conversation_id
+        # agent_id 映射；同一会话里 agent_id 唯一
+        self.agents: Dict[int, AgentInstance] = {}
+        # task_id -> agent_id（便于在 SubAgentTask 完成时回写）
+        self.task_id_to_agent_id: Dict[str, int] = {}
+        # 主智能体待插入消息队列（每条都是字符串，由 chat task 取走）
+        self.pending_master_messages: List[str] = []
+        # ask_master / ask_other_agent 的等待 future
+        # key = question_id, value = asyncio.Future (结果为 answer str 或 Exception)
+        self.pending_questions: Dict[str, asyncio.Future] = {}
+        # question_id -> 创建 future 时所在的事件循环，用于跨循环安全 set_result
+        self.pending_question_loops: Dict[str, AbstractEventLoop] = {}
+        # 回答早于 wait_for_answer 注册时先暂存
+        self.pending_answers: Dict[str, str] = {}
+        # 一个 agent 可能同时只阻塞在一个 ask 工具上（最简实现）
+        # key = agent_id, value = question_id（表示当前 agent 正阻塞等待）
+        self.agent_blocking_question: Dict[int, str] = {}
+        # 角色实例计数：role_id -> 已分配的最大 agent_id（数字）
+        # 用于创建新实例时自动递增编号，但允许调用方显式指定
+        self.role_counters: Dict[str, int] = {}
+
+    # ----- 创建/查询 -----
+    def next_agent_id_for_role(self, role_id: str) -> int:
+        """为指定角色分配下一个 agent_id 编号。"""
+        n = self.role_counters.get(role_id, 0) + 1
+        self.role_counters[role_id] = n
+        return n
+
+    def register_instance(self, instance: AgentInstance) -> None:
+        if instance.agent_id in self.agents:
+            raise ValueError(f"agent_id {instance.agent_id} 已存在")
+        self.agents[instance.agent_id] = instance
+        self.task_id_to_agent_id[instance.task_id] = instance.agent_id
+
+    def get_instance(self, agent_id: int) -> Optional[AgentInstance]:
+        return self.agents.get(agent_id)
+
+    def get_instance_by_task_id(self, task_id: str) -> Optional[AgentInstance]:
+        aid = self.task_id_to_agent_id.get(task_id)
+        if aid is None:
+            return None
+        return self.agents.get(aid)
+
+    def list_active(self) -> List[AgentInstance]:
+        return [a for a in self.agents.values() if a.status == "running" or a.status == "idle"]
+
+    def list_all(self) -> List[AgentInstance]:
+        return list(self.agents.values())
+
+    def mark_status(self, agent_id: int, status: str, last_output: str = "") -> None:
+        a = self.agents.get(agent_id)
+        if a:
+            a.status = status
+            if last_output:
+                a.last_output = last_output
+
+    # ----- 主对话注入 -----
+    def push_master_message(self, message_text: str) -> None:
+        """把一条 user 消息追加到主对话待插入队列。"""
+        ma_debug(
+            "state_push_master_message",
+            conversation_id=self.conversation_id,
+            state_id=id(self),
+            queue_len_before=len(self.pending_master_messages),
+            msg_preview=str(message_text)[:200],
+        )
+        self.pending_master_messages.append(message_text)
+
+    def drain_master_messages(self) -> List[str]:
+        """取出（清空）所有待插入主对话的消息。"""
+        msgs = self.pending_master_messages
+        self.pending_master_messages = []
+        ma_debug(
+            "state_drain_master_messages",
+            conversation_id=self.conversation_id,
+            state_id=id(self),
+            drained_count=len(msgs),
+            previews=[str(m)[:150] for m in msgs],
+        )
+        return msgs
+
+    def has_pending_master_messages(self) -> bool:
+        return len(self.pending_master_messages) > 0
+
+    # ----- 阻塞问答 -----
+    async def wait_for_answer(self, question_id: str, agent_id: int, timeout: float = 600.0) -> str:
+        """子智能体 ask_* 工具调用后阻塞等待答案。
+
+        返回 answer 字符串；超时/取消抛 asyncio.TimeoutError 或 CancelledError。
+        """
+        # 如果回答已经提前到达，直接返回
+        if question_id in self.pending_answers:
+            return self.pending_answers.pop(question_id)
+        if question_id in self.pending_questions:
+            old_fut = self.pending_questions[question_id]
+            try:
+                old_loop = old_fut.get_loop()
+                if old_loop.is_closed():
+                    self.pending_questions.pop(question_id, None)
+                    self.pending_question_loops.pop(question_id, None)
+                else:
+                    raise RuntimeError(f"question_id 已存在: {question_id}")
+            except Exception:
+                self.pending_questions.pop(question_id, None)
+                self.pending_question_loops.pop(question_id, None)
+        loop = asyncio.get_running_loop()
+        fut: asyncio.Future = loop.create_future()
+        self.pending_questions[question_id] = fut
+        self.pending_question_loops[question_id] = loop
+        self.agent_blocking_question[agent_id] = question_id
+        try:
+            return await asyncio.wait_for(fut, timeout=timeout)
+        finally:
+            self.pending_questions.pop(question_id, None)
+            self.pending_question_loops.pop(question_id, None)
+            if self.agent_blocking_question.get(agent_id) == question_id:
+                self.agent_blocking_question.pop(agent_id, None)
+
+    async def _do_provide_answer(self, question_id: str, answer: str) -> bool:
+        """在同 future 所属事件循环内设置结果。"""
+        fut = self.pending_questions.get(question_id)
+        if not fut or fut.done():
+            return False
+        try:
+            fut.set_result(answer)
+        except asyncio.InvalidStateError:
+            return False
+        return True
+
+    def provide_answer(self, question_id: str, answer: str) -> bool:
+        """主/其他子智能体 answer_* 工具调用时回写答案。
+
+        返回 True 表示找到等待中的 future；False 表示无等待方或已超时。
+        支持跨事件循环调用（例如主对话循环回答子智能体循环里的提问）。
+        """
+        ma_debug(
+            "state_provide_answer",
+            question_id=question_id,
+            has_pending=question_id in self.pending_questions,
+            answer_preview=str(answer)[:300],
+        )
+        # 如果 wait_for_answer 还没注册，先把答案暂存
+        if question_id not in self.pending_questions:
+            self.pending_answers[question_id] = answer
+            return True
+        fut = self.pending_questions.get(question_id)
+        if not fut or fut.done():
+            self.pending_answers[question_id] = answer
+            return False
+        loop = self.pending_question_loops.get(question_id)
+        if loop is None:
+            try:
+                loop = fut.get_loop()
+            except Exception:
+                pass
+        if loop is not None:
+            try:
+                asyncio.run_coroutine_threadsafe(self._do_provide_answer(question_id, answer), loop)
+                return True
+            except Exception:
+                pass
+        # 同循环回退（future 所属循环可能已关闭，失败时把答案暂存，避免阻塞方永远等不到）
+        try:
+            return asyncio.run_coroutine_threadsafe(self._do_provide_answer(question_id, answer), asyncio.get_event_loop()).result(timeout=5)
+        except Exception:
+            self.pending_questions.pop(question_id, None)
+            self.pending_question_loops.pop(question_id, None)
+            self.pending_answers[question_id] = answer
+            return True
+
+    def is_agent_blocking(self, agent_id: int) -> bool:
+        return agent_id in self.agent_blocking_question
+
+    def get_blocking_question_id(self, agent_id: int) -> Optional[str]:
+        return self.agent_blocking_question.get(agent_id)
+
+    def cancel_pending_question_for_agent(self, agent_id: int) -> bool:
+        """取消指定子智能体正在等待的问答 future，用于软停止时解除阻塞。"""
+        question_id = self.agent_blocking_question.pop(agent_id, None)
+        if not question_id:
+            return False
+        fut = self.pending_questions.pop(question_id, None)
+        loop = self.pending_question_loops.pop(question_id, None)
+        if fut and not fut.done():
+            try:
+                if loop and not loop.is_closed():
+                    loop.call_soon_threadsafe(fut.cancel)
+                else:
+                    fut.cancel()
+            except Exception:
+                pass
+        if fut:
+            return True
+        return False
+
+    # ----- 持久化（最简版） -----
+    def to_snapshot(self) -> Dict[str, Any]:
+        return {
+            "conversation_id": self.conversation_id,
+            "agents": [a.to_dict() for a in self.agents.values()],
+            "role_counters": self.role_counters,
+        }
+
+    @classmethod
+    def from_snapshot(cls, snapshot: Dict[str, Any]) -> "MultiAgentState":
+        state = cls(conversation_id=snapshot.get("conversation_id", ""))
+        state.role_counters = dict(snapshot.get("role_counters") or {})
+        for a_data in snapshot.get("agents") or []:
+            a = AgentInstance(**a_data)
+            state.agents[a.agent_id] = a
+            if a.task_id:
+                state.task_id_to_agent_id[a.task_id] = a.agent_id
+        return state
+
+    def clear(self) -> None:
+        """清空所有运行态：实例、pending消息、阻塞问答、角色计数。
+
+        用于用户连续第二下按停止按钮时，强制丢弃所有运行中/半成品状态。
+        """
+        # 取消所有阻塞中的 future，避免泄漏
+        for qid, fut in list(self.pending_questions.items()):
+            loop = self.pending_question_loops.get(qid)
+            if loop and not loop.is_closed() and not fut.done():
+                try:
+                    loop.call_soon_threadsafe(fut.cancel)
+                except Exception:
+                    pass
+        self.agents.clear()
+        self.task_id_to_agent_id.clear()
+        self.pending_master_messages.clear()
+        self.pending_questions.clear()
+        self.pending_question_loops.clear()
+        self.pending_answers.clear()
+        self.agent_blocking_question.clear()
+        self.role_counters.clear()

modules/multi_agent/sub_agent_context.py

@@ -0,0 +1,260 @@
+"""多智能体子智能体动态上下文构建。
+
+在子智能体创建时，为其系统提示词注入工作区相关信息：
+- 执行环境（宿主机/docker + 沙箱/直接）
+- AGENTS.md 项目规范
+- 工作区信息（项目名称、运行环境、当前时间，不含 file_tree / recent_uploads）
+- .astrion/ 目录结构说明（skills / memory / review / user_upload）
+- 可用 skill 列表
+- 项目记忆索引
+
+所有信息在子智能体创建那一刻快照写入 system_prompt.txt，后续冻结不更新。
+"""
+from __future__ import annotations
+
+import platform
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    from config import (
+        PROMPTS_DIR,
+        WORKSPACE_SKILLS_DIRNAME,
+        WORKSPACE_MEMORY_DIRNAME,
+        WORKSPACE_REVIEW_DIRNAME,
+        TERMINAL_SANDBOX_MODE,
+    )
+    from config.paths import IS_HOST_MODE
+except ImportError:
+    import sys
+
+    project_root = Path(__file__).resolve().parents[2]
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+    from config import (
+        PROMPTS_DIR,
+        WORKSPACE_SKILLS_DIRNAME,
+        WORKSPACE_MEMORY_DIRNAME,
+        WORKSPACE_REVIEW_DIRNAME,
+        TERMINAL_SANDBOX_MODE,
+    )
+    from config.paths import IS_HOST_MODE
+
+
+def _load_agents_md(workspace_path: str) -> Optional[str]:
+    """加载工作区根目录的 AGENTS.md 文件内容。"""
+    try:
+        project_path = Path(workspace_path)
+        if not project_path.exists():
+            return None
+        agents_md_files = list(project_path.rglob("AGENTS.md"))
+        if not agents_md_files:
+            return None
+        latest_file = max(agents_md_files, key=lambda p: p.stat().st_mtime)
+        content = latest_file.read_text(encoding="utf-8")
+        return content.strip() if content else None
+    except Exception:
+        return None
+
+
+def _build_execution_env_section(workspace_path: str, *, sandbox_mode: str = "") -> str:
+    """构建执行环境信息段（精简版，只含宿主机/docker + 沙箱/直接）。"""
+    mode = (sandbox_mode or TERMINAL_SANDBOX_MODE or "").lower()
+    if IS_HOST_MODE:
+        runtime_label = "宿主机模式"
+        # host 模式下区分 sandbox / direct
+        if mode == "direct":
+            exec_label = "直接执行（完全访问权限）"
+            rules = (
+                "- 当前为宿主机直接执行模式\n"
+                "- 仅在必须时执行高权限操作，保持最小化命令范围\n"
+                "- 涉及删除/覆盖/系统级变更前，先说明风险再执行"
+            )
+        else:
+            exec_label = "沙箱执行"
+            rules = (
+                "- 所有命令默认在系统 OS 沙箱中执行\n"
+                "- 若操作受系统权限限制：先提供安全替代方案；若仍无法满足，说明需要更高权限\n"
+                "- 不要通过复杂绕过手段规避沙箱限制"
+            )
+    else:
+        runtime_label = "Docker 容器模式"
+        exec_label = "容器内执行"
+        rules = (
+            "- 所有命令在 Docker 容器内执行\n"
+            "- 工作区挂载在容器内 /workspace 路径下\n"
+            "- 网络可能受限，仅允许 localhost"
+        )
+    return (
+        f"## 执行环境\n\n"
+        f"- 运行环境：{runtime_label}\n"
+        f"- 执行方式：{exec_label}\n\n"
+        f"### 当前规则\n{rules}\n"
+    )
+
+
+def _build_workspace_section(workspace_path: str) -> str:
+    """构建工作区信息段（精简版，不含 file_tree 和 recent_uploads）。"""
+    project_path = Path(workspace_path)
+    project_name = project_path.name or "未命名项目"
+    system_info = f"{platform.system()} {platform.release()}"
+    current_time = datetime.now().strftime("%Y年%m月%d日 %H点（24小时制）")
+
+    if IS_HOST_MODE:
+        resource_limit = "宿主机模式无限制"
+    else:
+        resource_limit = "容器模式，受 Docker 资源限制"
+
+    return (
+        f"## 工作区信息\n\n"
+        f"- 项目名称：{project_name}\n"
+        f"- 运行环境：{system_info}\n"
+        f"- 资源限制：{resource_limit}\n"
+        f"- 当前时间：{current_time}\n"
+    )
+
+
+def _build_astrion_dir_section(workspace_path: str) -> str:
+    """构建 .astrion/ 目录结构说明段。"""
+    return (
+        f"## 工作区数据目录（.astrion/）\n\n"
+        f"工作区内的 `.astrion/` 目录存储以下内容：\n"
+        f"- `{WORKSPACE_SKILLS_DIRNAME}/`：可用技能（skill）目录，每个 skill 含 SKILL.md 说明\n"
+        f"- `{WORKSPACE_MEMORY_DIRNAME}/`：项目记忆，以 Markdown 文件形式存放项目约定/决策/调试坑\n"
+        f"- `{WORKSPACE_REVIEW_DIRNAME}/`：对话回顾文件\n"
+        f"- `user_upload/`：用户上传的文件\n\n"
+        f"用户上传的文件位于 `.astrion/user_upload/` 目录下。"
+        f"项目记忆以文件形式存放在 `{WORKSPACE_MEMORY_DIRNAME}/` 下。"
+        f"技能（skill）存放在 `{WORKSPACE_SKILLS_DIRNAME}/` 下。\n"
+    )
+
+
+def _build_agents_md_section(workspace_path: str) -> str:
+    """构建 AGENTS.md 项目规范段。"""
+    content = _load_agents_md(workspace_path)
+    if not content:
+        return ""
+    return (
+        f"## AGENTS.md 项目规范\n\n"
+        f"> 以下是工作区根目录的 AGENTS.md 文件内容，请在回答时参考这些项目规范：\n\n"
+        f"{content}\n\n"
+        f"---\n"
+        f"注意：以上规范来自工作区根目录的 AGENTS.md 文件，若与未来代码冲突，以实际代码为准。\n"
+    )
+
+
+def _build_skills_section(workspace_path: str, data_dir: str = "") -> str:
+    """构建可用 skill 列表段。"""
+    try:
+        from modules.skills_manager import (
+            get_skills_catalog,
+            build_skills_list,
+            infer_private_skills_dir,
+        )
+
+        private_dir = infer_private_skills_dir(data_dir) if data_dir else None
+        catalog = get_skills_catalog(private_dir=private_dir)
+        # 子智能体不区分 enabled/disabled，列出全部可用 skill
+        skills_list = build_skills_list(catalog, enabled=None)
+        if not skills_list:
+            return ""
+        return (
+            f"## 可用 AgentSkill\n\n"
+            f"agent skills 系统已启用，以下是可用的 skills（含简要说明）：\n\n"
+            f"{skills_list}\n\n"
+            f"使用技能时，优先用 read_skill 通过技能名读取 SKILL.md；"
+            f"需要阅读 skill 目录中的其他文件时再使用 read_file\n"
+        )
+    except Exception:
+        return ""
+
+
+def _build_project_memory_section(workspace_path: str) -> str:
+    """构建项目记忆索引段（只列索引，不展开内容）。"""
+    try:
+        memory_dir = Path(workspace_path) / WORKSPACE_MEMORY_DIRNAME
+        if not memory_dir.exists() or not memory_dir.is_dir():
+            return ""
+        entries: List[str] = []
+        for md_file in sorted(memory_dir.glob("*.md")):
+            try:
+                text = md_file.read_text(encoding="utf-8")
+                name = None
+                description = None
+                if text.startswith("---"):
+                    end = text.find("---", 3)
+                    if end > 0:
+                        frontmatter = text[3:end]
+                        for line in frontmatter.strip().split("\n"):
+                            ls = line.strip()
+                            if ls.startswith("name:"):
+                                name = ls.split(":", 1)[1].strip()
+                            elif ls.startswith("description:"):
+                                description = ls.split(":", 1)[1].strip()
+                file_name = md_file.name
+                display_name = name or md_file.stem
+                desc = description or ""
+                if desc:
+                    entries.append(f".astrion/memory/{file_name}：{desc}")
+                else:
+                    entries.append(f".astrion/memory/{file_name}：当需要{display_name}时，应该索引本记忆")
+            except Exception:
+                pass
+        if not entries:
+            return ""
+        return (
+            f"## 项目记忆\n\n"
+            f"项目记忆以文件形式存放在 `.astrion/memory/` 下。\n"
+            f"开始涉及项目约定、历史决策或已知问题的任务前，先检查项目记忆索引，"
+            f"如有相关记忆则用 recall_project_memory 读取。\n\n"
+            f"### 项目记忆索引\n\n"
+            + "\n".join(entries)
+            + "\n"
+        )
+    except Exception:
+        return ""
+
+
+def build_sub_agent_dynamic_context(
+    workspace_path: str,
+    *,
+    data_dir: str = "",
+    sandbox_mode: str = "",
+) -> str:
+    """构建子智能体的动态上下文信息（拼接到 system prompt 末尾）。
+
+    所有信息在子智能体创建那一刻快照，后续冻结不更新。
+
+    Args:
+        workspace_path: 工作区路径
+        data_dir: 数据目录路径（用于推断 private skills 目录）
+        sandbox_mode: 沙箱模式（sandbox/direct/host/docker）
+    """
+    sections: List[str] = []
+
+    # 1. 执行环境
+    sections.append(_build_execution_env_section(workspace_path, sandbox_mode=sandbox_mode))
+
+    # 2. 工作区信息（精简版）
+    sections.append(_build_workspace_section(workspace_path))
+
+    # 3. .astrion/ 目录说明
+    sections.append(_build_astrion_dir_section(workspace_path))
+
+    # 4. AGENTS.md
+    agents_md = _build_agents_md_section(workspace_path)
+    if agents_md:
+        sections.append(agents_md)
+
+    # 5. 可用 skill
+    skills = _build_skills_section(workspace_path, data_dir=data_dir)
+    if skills:
+        sections.append(skills)
+
+    # 6. 项目记忆索引
+    memory = _build_project_memory_section(workspace_path)
+    if memory:
+        sections.append(memory)
+
+    return "\n".join(sections)

modules/multi_agent/tools.py

@@ -0,0 +1,318 @@
+"""多智能体工具定义（OpenAI Function Calling 格式）。
+
+主智能体侧（master）：替换原有的 4 个旧版子智能体工具，新增 9 个多智能体工具。
+子智能体侧（sub_agent）：在现有 8 个基础工具之外新增 4 个通信工具。
+
+工具处理函数（handler）不在这里实现，而是在 SubAgentManager/SubAgentTask 中
+注册回调，工具执行入口仍走 SubAgentManager.execute_tool_for_sub_agent。
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def _inject_intent(properties: Dict[str, Any]) -> Dict[str, Any]:
+    """为所有 properties 注入 intent 字段（与现有工具规范保持一致）。"""
+    out: Dict[str, Any] = {}
+    for k, v in properties.items():
+        if k == "intent":
+            out[k] = v
+            continue
+        out[k] = v
+    # 在末尾追加 intent 字段
+    if "intent" not in out:
+        out["intent"] = {
+            "type": "string",
+            "description": "用不超过15个字向用户说明你要做什么，例如：派遣UI Operator设计配色。",
+        }
+    return out
+
+
+# ----- 主智能体工具 -----
+def _master_tool_create_sub_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "create_sub_agent",
+            "description": (
+                "创建一个属于多智能体团队的子智能体实例并启动。必须指定 role_id。"
+                "实例会注入该角色的专属 prompt 与多智能体协作工具（ask_master 等）。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "role_id": {
+                        "type": "string",
+                        "description": "角色标识，例如 'ui-operator'/'full-stack-engineer'/'code-reviewer'/'researcher'。先用 list_agents 查看可用角色。",
+                    },
+                    "task": {
+                        "type": "string",
+                        "description": "要交给该子智能体执行的任务描述。要求包含：目标、范围、产出、注意事项。",
+                    },
+                    "agent_id": {
+                        "type": "integer",
+                        "description": "（可选）手动指定实例编号；不传时自动递增。",
+                    },
+                    "thinking_mode": {
+                        "type": "string",
+                        "enum": ["fast", "thinking"],
+                        "description": "（可选）覆盖角色默认思考模式。不填使用角色配置。",
+                    },
+                }),
+                "required": ["role_id", "task"],
+            },
+        },
+    }
+
+
+def _master_tool_terminate_sub_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "terminate_sub_agent",
+            "description": "强制终止指定子智能体实例。终止后无法恢复，已生成的文件保留。",
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "agent_id": {"type": "integer", "description": "要终止的子智能体编号。"},
+                }),
+                "required": ["agent_id"],
+            },
+        },
+    }
+
+
+def _master_tool_send_message_to_sub_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "send_message_to_sub_agent",
+            "description": (
+                "运行时引导/干预：向指定子智能体插入一条引导消息或新任务，立刻返回不等待回复。"
+                "用于看到子智能体中间输出后立即纠正方向、追加要求。消息接收方根据当前状态"
+                "（running/idle）自行决定是 inline 插入还是触发新一轮任务。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "agent_id": {"type": "integer", "description": "目标子智能体编号。"},
+                    "message": {"type": "string", "description": "要插入的消息或新任务正文。"},
+                }),
+                "required": ["agent_id", "message"],
+            },
+        },
+    }
+
+
+def _master_tool_ask_sub_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "ask_sub_agent",
+            "description": (
+                "向指定子智能体提出一个明确问题并阻塞等待一轮回答（不是发起任务，是问问题）。"
+                "问题会以 `来自 Team Leader 的提问` 格式插入子对话，子智能体下一轮 assistant 输出"
+                "作为回答返回到此工具结果中。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "agent_id": {"type": "integer", "description": "目标子智能体编号。"},
+                    "question": {"type": "string", "description": "要询问的问题，应简短明确。"},
+                    "timeout_seconds": {"type": "integer", "description": "等待回答超时秒数，默认 600。"},
+                }),
+                "required": ["agent_id", "question"],
+            },
+        },
+    }
+
+
+def _master_tool_answer_sub_agent_question() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "answer_sub_agent_question",
+            "description": (
+                "回答子智能体通过 ask_master 工具提出的问题。回答内容会直接返回到子智能体"
+                "ask_master 工具的 tool_call 结果里（不会以 user 消息插入子对话）。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "question_id": {"type": "string", "description": "提问消息里给出的 id，如 ask_xxx。"},
+                    "answer": {"type": "string", "description": "给子智能体的回答正文。"},
+                }),
+                "required": ["question_id", "answer"],
+            },
+        },
+    }
+
+
+def _master_tool_create_custom_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "create_custom_agent",
+            "description": "创建/保存一个自定义角色到后端（~/.astrion/astrion/host/mutiagents/agents/）。后续可用 create_sub_agent 指定该角色。",
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "role_id": {"type": "string", "description": "角色标识（英文小写下划线，如 api-designer）。"},
+                    "name": {"type": "string", "description": "显示名（如 API Designer）。"},
+                    "description": {"type": "string", "description": "一句话简述职责。"},
+                    "body_prompt": {"type": "string", "description": "角色的自定义 prompt body（Markdown）。"},
+                    "thinking_mode": {"type": "string", "enum": ["fast", "thinking"], "description": "默认思考模式。"},
+                }),
+                "required": ["role_id", "name", "body_prompt"],
+            },
+        },
+    }
+
+
+def _master_tool_list_agents() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "list_agents",
+            "description": "列出所有可用的预置/自定义角色（role_id / name / 描述）。用于在 create_sub_agent 前选角色。",
+            "parameters": {"type": "object", "properties": _inject_intent({})},
+        },
+    }
+
+
+def _master_tool_list_active_sub_agents() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "list_active_sub_agents",
+            "description": "列出当前多智能体会话中所有活跃/已创建的子智能体实例（agent_id/role/display_name/status）。",
+            "parameters": {"type": "object", "properties": _inject_intent({})},
+        },
+    }
+
+
+def _master_tool_get_sub_agent_status() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "get_sub_agent_status",
+            "description": "查询一个或多个子智能体的详细状态。",
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "agent_ids": {"type": "array", "items": {"type": "integer"}, "description": "要查询的子智能体编号列表。"},
+                }),
+                "required": ["agent_ids"],
+            },
+        },
+    }
+
+
+MULTI_AGENT_MASTER_TOOLS: List[Dict[str, Any]] = [
+    _master_tool_create_sub_agent(),
+    _master_tool_terminate_sub_agent(),
+    _master_tool_send_message_to_sub_agent(),
+    _master_tool_ask_sub_agent(),
+    _master_tool_answer_sub_agent_question(),
+    _master_tool_create_custom_agent(),
+    _master_tool_list_agents(),
+    _master_tool_list_active_sub_agents(),
+    _master_tool_get_sub_agent_status(),
+]
+
+
+# ----- 子智能体工具 -----
+def _sub_tool_ask_master() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "ask_master",
+            "description": (
+                "向 Team Leader（主智能体）提问，工具调用会阻塞等待主智能体通过 answer_sub_agent_question 给出回答。"
+                "用于需要主智能体决策的场合。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "question": {"type": "string", "description": "向 Team Leader 提问的内容。"},
+                    "question_id": {"type": "string", "description": "（可选）问题 id；不传自动生成。"},
+                }),
+                "required": ["question"],
+            },
+        },
+    }
+
+
+def _sub_tool_ask_other_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "ask_other_agent",
+            "description": (
+                "向另一个子智能体提问，阻塞等待对方调用 answer_other_agent 回答。"
+                "**注意**：调用此工具的同时，你必须在你的文本输出里向 Team Leader 输出一条汇报，"
+                "说明你为何问、问谁、期望什么——不要偷偷沟通。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "target_agent_id": {"type": "integer", "description": "目标子智能体编号。"},
+                    "question": {"type": "string", "description": "提问内容。"},
+                    "question_id": {"type": "string", "description": "（可选）问题 id。"},
+                }),
+                "required": ["target_agent_id", "question"],
+            },
+        },
+    }
+
+
+def _sub_tool_answer_other_agent() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "answer_other_agent",
+            "description": (
+                "回答其他子智能体通过 ask_other_agent 提出的问题。"
+                "answer 内容会直接返回到对方 ask_other_agent 工具结果中。"
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": _inject_intent({
+                    "source_agent_id": {"type": "integer", "description": "提问方 agent_id。"},
+                    "question_id": {"type": "string", "description": "提问消息中的 id。"},
+                    "answer": {"type": "string", "description": "回答内容。"},
+                }),
+                "required": ["source_agent_id", "question_id", "answer"],
+            },
+        },
+    }
+
+
+def _sub_tool_list_active_sub_agents() -> Dict[str, Any]:
+    return {
+        "type": "function",
+        "function": {
+            "name": "list_active_sub_agents",
+            "description": "查询当前多智能体会话中所有活跃/已创建的子智能体。",
+            "parameters": {"type": "object", "properties": _inject_intent({})},
+        },
+    }
+
+
+MULTI_AGENT_SUB_AGENT_TOOLS: List[Dict[str, Any]] = [
+    _sub_tool_ask_master(),
+    _sub_tool_ask_other_agent(),
+    _sub_tool_answer_other_agent(),
+    _sub_tool_list_active_sub_agents(),
+]
+
+
+# ----- 构造函数（供现有 tools_definition 调用） -----
+def build_master_tools_for_conversation() -> List[Dict[str, Any]]:
+    """返回主智能体在多智能体模式下应额外提供的工具列表。"""
+    return list(MULTI_AGENT_MASTER_TOOLS)
+
+
+def build_sub_agent_tools_for_role() -> List[Dict[str, Any]]:
+    """返回子智能体在多智能体模式下应额外提供的工具列表。"""
+    return list(MULTI_AGENT_SUB_AGENT_TOOLS)

modules/sub_agent/creation.py

@@ -48,7 +48,7 @@ class SubAgentCreationMixin:
         if agent_id not in used:
             used.append(agent_id)
 
-    def _validate_create_params(self, agent_id: Optional[int], summary: str, task: str, target_dir: str) -> Optional[str]:
+    def _validate_create_params(self, agent_id: Optional[int], summary: str, task: str, target_dir: Optional[str], *, multi_agent_mode: bool = False) -> Optional[str]:
         if agent_id is None:
             return "子智能体代号不能为空"
         try:
@@ -61,7 +61,8 @@ class SubAgentCreationMixin:
             return "任务摘要不能为空"
         if not task or not task.strip():
             return "任务详情不能为空"
-        if target_dir is None:
+        # 多智能体模式不需要交付目录
+        if not multi_agent_mode and target_dir is None:
             return "指定文件夹不能为空"
         return None
 
@@ -69,8 +70,11 @@ class SubAgentCreationMixin:
         suffix = uuid.uuid4().hex[:6]
         return f"sub_{agent_id}_{int(time.time())}_{suffix}"
 
-    def _resolve_deliverables_dir(self, relative_dir: str) -> Path:
-        relative_dir = relative_dir.strip() if relative_dir else ""
+    def _resolve_deliverables_dir(self, relative_dir: Optional[str], *, multi_agent_mode: bool = False) -> Path:
+        relative_dir = (relative_dir or "").strip()
+        # 多智能体模式：没有交付目录概念，直接使用项目根目录
+        if multi_agent_mode and not relative_dir:
+            return self.project_path.resolve()
         if not relative_dir:
             raise ValueError("交付目录不能为空，必须指定")
         deliverables_path = (self.project_path / relative_dir).resolve()

modules/sub_agent/manager.py

@@ -19,9 +19,7 @@ from config import (
     SUB_AGENT_DEFAULT_TIMEOUT,
     SUB_AGENT_MAX_ACTIVE,
     SUB_AGENT_MODELS_CONFIG_FILE,
-    SUB_AGENT_STATE_FILE,
     SUB_AGENT_STATUS_POLL_INTERVAL,
-    SUB_AGENT_TASKS_BASE_DIR,
 )
 from utils.logger import setup_logger
 from modules.sub_agent.task import SubAgentTask
@@ -30,6 +28,8 @@ from modules.sub_agent.tools import handle_search_workspace, handle_read_mediafi
 from modules.sub_agent.state import SubAgentStateMixin
 from modules.sub_agent.stats import SubAgentStatsMixin
 from modules.sub_agent.creation import SubAgentCreationMixin
+from modules.multi_agent.debug_logger import ma_debug
+from server.utils_common import debug_log
 
 if TYPE_CHECKING:
     from core.web_terminal import WebTerminal
@@ -50,12 +50,16 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
     ):
         self.project_path = Path(project_path).resolve()
         self.data_dir = Path(data_dir).resolve()
-        self.base_dir = Path(SUB_AGENT_TASKS_BASE_DIR).resolve()
-        self.state_file = Path(SUB_AGENT_STATE_FILE).resolve()
+        # 子智能体任务和状态按 data_dir 隔离（web 模式下按用户/工作区自动隔离）
+        self.base_dir = self.data_dir / "sub_agent_tasks"
+        self.state_file = self.data_dir / "sub_agents.json"
         self.models_config_file = SUB_AGENT_MODELS_CONFIG_FILE
         self.container_session: Optional["ContainerHandle"] = container_session
         self.host_execution_mode: str = "sandbox"
         self.terminal: Optional["WebTerminal"] = None
+        # 多智能体模式：为每个启用 multi_agent_mode 的会话维护一个 MultiAgentState
+        # key = conversation_id, value = MultiAgentState
+        self.multi_agent_states: Dict[str, Any] = {}
 
         self.base_dir.mkdir(parents=True, exist_ok=True)
         self.state_file.parent.mkdir(parents=True, exist_ok=True)
@@ -66,12 +70,19 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
         self._event_loop: Optional[asyncio.AbstractEventLoop] = None
         self._loop_thread: Optional[threading.Thread] = None
         self._state_lock = threading.Lock()
+        # agent_id -> SubAgentTask 映射（供多智能体消息注入使用）
+        self._sub_agent_instances: Dict[int, Any] = {}
 
         self._load_state()
         try:
             self.reconcile_task_states()
         except Exception:
             pass
+        try:
+            self.restore_running_tasks()
+        except Exception:
+            logger.exception("[SubAgentManager] 恢复运行中子智能体任务失败")
+            pass
 
     # ------------------------------------------------------------------
     # 生命周期与事件循环
@@ -131,15 +142,26 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
         agent_id: int,
         summary: str,
         task: str,
-        deliverables_dir: str,
+        deliverables_dir: Optional[str] = None,
         timeout_seconds: Optional[int] = None,
         conversation_id: Optional[str] = None,
         run_in_background: bool = False,
         model_key: Optional[str] = None,
         thinking_mode: Optional[str] = None,
+        multi_agent_mode: bool = False,
+        role_id: Optional[str] = None,
+        display_name: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+        task_message: Optional[str] = None,
+        compress_threshold_tokens: Optional[int] = None,
     ) -> Dict:
-        """创建子智能体任务并启动协程。"""
-        validation_error = self._validate_create_params(agent_id, summary, task, deliverables_dir)
+        """创建子智能体任务并启动协程。
+        
+        参数 multi_agent_mode: True 时启用多智能体模式。
+        参数 role_id: 多智能体模式下的角色标诶。
+        参数 display_name: 多智能体模式下的显示名（如 UI Operator_1）。
+        """
+        validation_error = self._validate_create_params(agent_id, summary, task, deliverables_dir, multi_agent_mode=multi_agent_mode)
         if validation_error:
             return {"success": False, "error": validation_error}
 
@@ -168,7 +190,7 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
         task_root.mkdir(parents=True, exist_ok=True)
 
         try:
-            deliverables_path = self._resolve_deliverables_dir(deliverables_dir)
+            deliverables_path = self._resolve_deliverables_dir(deliverables_dir, multi_agent_mode=multi_agent_mode)
         except ValueError as exc:
             return {"success": False, "error": str(exc)}
 
@@ -181,14 +203,20 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
 
         prompt_workspace = self._get_runtime_path(self.project_path)
         deliverables_display = self._get_runtime_path(deliverables_path)
-        user_message = build_user_message(agent_id, summary, task, deliverables_display, timeout_seconds or SUB_AGENT_DEFAULT_TIMEOUT)
+        if task_message:
+            user_message = task_message
+        else:
+            display_timeout = timeout_seconds if timeout_seconds is not None else 0
+            user_message = build_user_message(agent_id, summary, task, deliverables_display, display_timeout or SUB_AGENT_DEFAULT_TIMEOUT)
         task_file.write_text(user_message, encoding="utf-8")
 
-        system_prompt = build_system_prompt(prompt_workspace)
-        system_prompt_file.write_text(system_prompt, encoding="utf-8")
-
-        timeout_seconds = timeout_seconds or SUB_AGENT_DEFAULT_TIMEOUT
+        if system_prompt:
+            final_system_prompt = system_prompt
+        else:
+            final_system_prompt = build_system_prompt(prompt_workspace)
+        system_prompt_file.write_text(final_system_prompt, encoding="utf-8")
 
+        # timeout_seconds 为 None 表示永久子智能体（不会被时间终结）
         task_record = {
             "task_id": task_id,
             "agent_id": agent_id,
@@ -202,39 +230,94 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
             "updated_at": time.time(),
             "conversation_id": conversation_id,
             "run_in_background": run_in_background,
+            "multi_agent_mode": bool(multi_agent_mode),
             "task_root": str(task_root),
             "output_file": str(output_file),
             "stats_file": str(stats_file),
             "progress_file": str(progress_file),
             "conversation_file": str(conversation_file),
+            "model_key": model_key,
+            "role_id": role_id,
+            "display_name": display_name,
             "execution_mode": "in_process",
+            "compress_threshold_tokens": compress_threshold_tokens,
             "container_name": None,
         }
         self.tasks[task_id] = task_record
         self._mark_agent_id_used(conversation_id, agent_id)
         self._save_state()
 
+        # 多智能体模式：为该会话创建或复用 MultiAgentState
+        multi_agent_state = None
+        if multi_agent_mode:
+            multi_agent_state = self.get_or_create_multi_agent_state(conversation_id)
+            # 把实例注册到 state
+            from modules.multi_agent.state import AgentInstance
+            inst = AgentInstance(
+                agent_id=agent_id,
+                role_id=role_id or "",
+                display_name=display_name or f"Agent_{agent_id}",
+                task_id=task_id,
+                status="running",
+                summary=summary,
+            )
+            try:
+                multi_agent_state.register_instance(inst)
+            except ValueError:
+                return {"success": False, "error": f"agent_id {agent_id} 已在该会话中使用"}
+
         sub_agent = SubAgentTask(
             manager=self,
             task_record=task_record,
             task_message=user_message,
-            system_prompt=system_prompt,
+            system_prompt=final_system_prompt,
             model_key=model_key,
             thinking_mode=thinking_mode,
+            multi_agent_mode=multi_agent_mode,
+            multi_agent_state=multi_agent_state,
+            display_name=display_name,
+        )
+        ma_debug(
+            "manager_create_sub_agent_state",
+            task_id=task_id,
+            agent_id=agent_id,
+            conversation_id=conversation_id,
+            state_id=id(multi_agent_state) if multi_agent_state else None,
         )
         task_coro = sub_agent.run()
         asyncio_task = self._run_coro(task_coro)
         sub_agent._task = asyncio_task
         self._running_tasks[task_id] = asyncio_task
+        # 缓存 sub_agent 实例供给多智能体模式 Poli注入使用
+        self._sub_agent_instances[agent_id] = sub_agent
 
         def _on_done(fut):
-            self._running_tasks.pop(task_id, None)
-            self.reconcile_task_states(conversation_id=conversation_id)
+            try:
+                self._running_tasks.pop(task_id, None)
+                self._sub_agent_instances.pop(agent_id, None)
+                self.reconcile_task_states(conversation_id=conversation_id)
+                # 多智能体模式：结束时把状态写回 MultiAgentState
+                if multi_agent_mode and multi_agent_state:
+                    self._on_multi_agent_task_done(task_id, agent_id, multi_agent_state, sub_agent)
+            except Exception as exc:
+                logger.exception(f"[SubAgent] task {task_id} 完成回调异常: {exc}")
+                ma_debug("manager_on_done_exception", task_id=task_id, agent_id=agent_id, error=str(exc))
 
         asyncio_task.add_done_callback(_on_done)
 
         message = f"子智能体{agent_id} 已创建，任务ID: {task_id}"
+        if multi_agent_mode and display_name:
+            message = f"{display_name} 已创建，任务ID: {task_id}"
         print(f"{OUTPUT_FORMATS['info']} {message}")
+        ma_debug(
+            "manager_create_sub_agent",
+            task_id=task_id,
+            agent_id=agent_id,
+            display_name=display_name,
+            multi_agent_mode=multi_agent_mode,
+            run_in_background=task_record.get("run_in_background"),
+            timeout_seconds=timeout_seconds,
+        )
 
         return {
             "success": True,
@@ -244,6 +327,7 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
             "message": message,
             "deliverables_dir": str(deliverables_path),
             "run_in_background": run_in_background,
+            "display_name": display_name,
         }
 
     def wait_for_completion(
@@ -302,6 +386,54 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
 
         return self._handle_timeout(task)
 
+    def soft_stop_all_agents(self, conversation_id: str) -> int:
+        """软停止指定会话的所有运行中子智能体。
+
+        与 terminate_sub_agent 的区别：不取消 asyncio.Task 而是设 _soft_stop 标志，
+        让子智能体在当前工具完成后进入 idle 状态，保留上下文。
+        返回实际发出软停止信号的子智能体数量。
+        """
+        ma_debug("soft_stop_all_agents_enter", conversation_id=conversation_id)
+        count = 0
+        matched = 0
+        skipped_terminal = 0
+        skipped_no_instance = 0
+        for task_id, task_info in list(self.tasks.items()):
+            if task_info.get("conversation_id") != conversation_id:
+                continue
+            matched += 1
+            status = task_info.get("status")
+            ma_debug(
+                "soft_stop_iter",
+                task_id=task_id,
+                status=status,
+            )
+            if status in TERMINAL_STATUSES.union({"terminated", "idle"}):
+                skipped_terminal += 1
+                continue
+            agent_id = task_info.get("agent_id")
+            if agent_id is None:
+                continue
+            # 從 _sub_agent_instances 查找 SubAgentTask 实例
+            sub_agent_task = self._sub_agent_instances.get(agent_id)
+            if sub_agent_task and hasattr(sub_agent_task, "request_soft_stop"):
+                try:
+                    sub_agent_task.request_soft_stop()
+                    count += 1
+                except Exception as exc:
+                    ma_debug("soft_stop_failed", task_id=task_id, error=str(exc))
+            else:
+                skipped_no_instance += 1
+        ma_debug(
+            "soft_stop_all_agents_done",
+            conversation_id=conversation_id,
+            matched=matched,
+            count=count,
+            skipped_terminal=skipped_terminal,
+            skipped_no_instance=skipped_no_instance,
+        )
+        return count
+
     def terminate_sub_agent(
         self,
         *,
@@ -316,7 +448,12 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
         task_id = task["task_id"]
         running_task = self._running_tasks.pop(task_id, None)
         if running_task and not running_task.done():
-            running_task.cancel()
+            # 子智能体运行在独立事件循环线程中，取消操作必须投递到该循环
+            try:
+                loop = running_task.get_loop()
+                loop.call_soon_threadsafe(running_task.cancel)
+            except Exception:
+                running_task.cancel()
             deadline = time.time() + 5
             while not running_task.done() and time.time() < deadline:
                 time.sleep(0.05)
@@ -453,6 +590,7 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
                 "agent_id": task.get("agent_id"),
                 "summary": task.get("summary"),
                 "status": task.get("status"),
+                "display_name": task.get("display_name") or "",
                 "created_at": task.get("created_at"),
                 "updated_at": task.get("updated_at"),
                 "target_dir": task.get("target_project_dir"),
@@ -463,6 +601,18 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
                 "sub_conversation_id": task.get("sub_conversation_id"),
             }
 
+            # 读取 stats 文件获取当前上下文 token
+            stats_file = Path(task.get("stats_file", ""))
+            if stats_file.exists():
+                try:
+                    stats = json.loads(stats_file.read_text(encoding="utf-8"))
+                    snapshot["current_context_tokens"] = stats.get("current_context_tokens", 0)
+                    snapshot["stats_summary"] = self._build_stats_summary(stats)
+                except Exception:
+                    snapshot["current_context_tokens"] = 0
+            else:
+                snapshot["current_context_tokens"] = 0
+
             if snapshot["status"] in TERMINAL_STATUSES or snapshot["status"] == "terminated":
                 final_result = task.get("final_result") or {}
                 snapshot["final_message"] = final_result.get("system_message") or final_result.get("message")
@@ -482,6 +632,8 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
             return {"success": False, "error": "子智能体管理器未绑定终端，无法执行工具"}
 
         try:
+            # 多智能体模式常见问答工具已在 SubAgentTask._execute_multi_agent_tool 中处理
+            # 这里只处理实际通过主进程执行的工具
             if tool_name == "search_workspace":
                 return await handle_search_workspace(self.project_path, self.terminal, arguments)
             if tool_name == "read_mediafile":
@@ -497,6 +649,334 @@ class SubAgentManager(SubAgentStateMixin, SubAgentStatsMixin, SubAgentCreationMi
             logger.exception(f"[SubAgent] 工具执行异常: {tool_name}")
             return {"success": False, "error": f"工具执行异常: {exc}"}
 
+    # ------------------------------------------------------------------
+    # 重启后恢复运行中任务
+    # ------------------------------------------------------------------
+    def restore_running_tasks(self) -> int:
+        """程序重启后，从 conversation.json 恢复非终态子智能体任务并重新运行。
+
+        返回成功恢复的任务数。
+        """
+        from modules.sub_agent.task import SubAgentTask
+
+        restored = 0
+        terminal_statuses = TERMINAL_STATUSES.union({"terminated"})
+        for task_id, task in list(self.tasks.items()):
+            if not isinstance(task, dict):
+                continue
+            # 仅恢复多智能体模式任务；传统子智能体保持原有清理逻辑
+            if not task.get("multi_agent_mode"):
+                continue
+            status = task.get("status", "running")
+            if status in terminal_statuses:
+                continue
+            # 已在内存中运行，无需恢复
+            if task_id in self._running_tasks:
+                continue
+
+            task_root = Path(task.get("task_root", ""))
+            conversation_file = Path(task.get("conversation_file", ""))
+            system_prompt_file = task_root / "system_prompt.txt"
+            task_message_file = task_root / "task.txt"
+
+            if not conversation_file.exists():
+                logger.warning(f"[restore] 任务 {task_id} 的对话文件缺失，无法恢复")
+                continue
+
+            try:
+                conversation_data = json.loads(conversation_file.read_text(encoding="utf-8"))
+                messages = list(conversation_data.get("messages") or [])
+            except Exception as exc:
+                logger.warning(f"[restore] 读取任务 {task_id} 对话文件失败: {exc}")
+                continue
+
+            system_prompt = ""
+            if system_prompt_file.exists():
+                try:
+                    system_prompt = system_prompt_file.read_text(encoding="utf-8")
+                except Exception:
+                    pass
+
+            task_message = ""
+            if task_message_file.exists():
+                try:
+                    task_message = task_message_file.read_text(encoding="utf-8")
+                except Exception:
+                    pass
+
+            # 如果对话历史为空，用 task_message 兜底
+            if not messages:
+                messages = [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": task_message},
+                ]
+
+            agent_id = int(task.get("agent_id", 0))
+            conversation_id = task.get("conversation_id")
+            multi_agent_mode = bool(task.get("multi_agent_mode"))
+            thinking_mode = task.get("thinking_mode") or "fast"
+            model_key = task.get("model_key")
+            display_name = task.get("display_name")
+            role_id = task.get("role_id")
+
+            multi_agent_state = None
+            if multi_agent_mode and conversation_id:
+                multi_agent_state = self.get_or_create_multi_agent_state(conversation_id)
+                # 如果 snapshot 里没有该实例，根据 task_record 重建一个
+                if multi_agent_state and not multi_agent_state.get_instance(agent_id):
+                    from modules.multi_agent.state import AgentInstance
+                    inst = AgentInstance(
+                        agent_id=agent_id,
+                        role_id=role_id or "",
+                        display_name=display_name or f"Agent_{agent_id}",
+                        task_id=task_id,
+                        status=status if status in ("running", "idle") else "running",
+                        summary=task.get("summary", ""),
+                    )
+                    try:
+                        multi_agent_state.register_instance(inst)
+                    except ValueError:
+                        pass
+
+            sub_agent = SubAgentTask(
+                manager=self,
+                task_record=task,
+                task_message=task_message,
+                system_prompt=system_prompt,
+                model_key=model_key,
+                thinking_mode=thinking_mode,
+                multi_agent_mode=multi_agent_mode,
+                multi_agent_state=multi_agent_state,
+                display_name=display_name,
+            )
+            sub_agent.messages = messages
+            # 重启后统一置为 idle，等待主智能体再次发消息才继续
+            if multi_agent_mode:
+                sub_agent._idle = True
+                task["status"] = "idle"
+                task["updated_at"] = time.time()
+                if multi_agent_state:
+                    multi_agent_state.mark_status(agent_id, "idle")
+                # 同步落盘 output.json，保证前端状态一致
+                try:
+                    output_file = Path(task.get("output_file", ""))
+                    if output_file.exists():
+                        output_data = json.loads(output_file.read_text(encoding="utf-8"))
+                    else:
+                        output_data = {}
+                    output_data["status"] = "idle"
+                    output_data["success"] = None
+                    output_file.parent.mkdir(parents=True, exist_ok=True)
+                    output_file.write_text(json.dumps(output_data, ensure_ascii=False), encoding="utf-8")
+                except Exception as exc:
+                    logger.warning(f"[restore] 更新任务 {task_id} output 文件失败: {exc}")
+
+            task_coro = sub_agent.run()
+            asyncio_task = self._run_coro(task_coro)
+            sub_agent._task = asyncio_task
+            self._running_tasks[task_id] = asyncio_task
+            self._sub_agent_instances[agent_id] = sub_agent
+
+            def _on_done(fut, tid=task_id, aid=agent_id, state=multi_agent_state, sa=sub_agent):
+                try:
+                    self._running_tasks.pop(tid, None)
+                    self._sub_agent_instances.pop(aid, None)
+                    self.reconcile_task_states(conversation_id=conversation_id)
+                    if multi_agent_mode and state:
+                        self._on_multi_agent_task_done(tid, aid, state, sa)
+                except Exception as exc:
+                    logger.exception(f"[SubAgent] restored task {tid} 完成回调异常: {exc}")
+                    ma_debug("manager_restore_on_done_exception", task_id=tid, agent_id=aid, error=str(exc))
+
+            asyncio_task.add_done_callback(_on_done)
+            restored += 1
+            ma_debug(
+                "manager_restore_sub_agent",
+                task_id=task_id,
+                agent_id=agent_id,
+                display_name=display_name,
+                multi_agent_mode=multi_agent_mode,
+                status=status,
+                message_count=len(messages),
+            )
+
+        if restored:
+            self._save_state()
+        return restored
+
+    # ------------------------------------------------------------------
+    # 多智能体模式：状态管理、外部接口、消息注入
+    # ------------------------------------------------------------------
+    def get_or_create_multi_agent_state(self, conversation_id: str):
+        """获取或为该会话创建 MultiAgentState。"""
+        from modules.multi_agent.state import MultiAgentState
+        state = self.multi_agent_states.get(conversation_id)
+        if state:
+            ma_debug(
+                "manager_get_or_create_ma_state_reuse",
+                conversation_id=conversation_id,
+                state_id=id(state),
+                manager_id=id(self),
+            )
+            return state
+        state = MultiAgentState(conversation_id=conversation_id)
+        self.multi_agent_states[conversation_id] = state
+        ma_debug(
+            "manager_get_or_create_ma_state_create",
+            conversation_id=conversation_id,
+            state_id=id(state),
+            manager_id=id(self),
+        )
+        return state
+
+    def get_multi_agent_state(self, conversation_id: str):
+        """获取该会话的多智能体状态。"""
+        state = self.multi_agent_states.get(conversation_id)
+        ma_debug(
+            "manager_get_multi_agent_state",
+            conversation_id=conversation_id,
+            found=bool(state),
+            state_id=id(state) if state else None,
+            manager_id=id(self),
+        )
+        return state
+
+    def drop_multi_agent_state(self, conversation_id: str) -> None:
+        """删除会话状态（会话结束时调用）。"""
+        self.multi_agent_states.pop(conversation_id, None)
+
+    def reconcile_task_states(self, conversation_id: Optional[str] = None) -> int:
+        """修正运行态任务状态。
+
+        在父类实现前先根据内存中的 MultiAgentState 给旧任务补上 multi_agent_mode
+        标记，避免任务记录缺字段导致被当成普通子智能体误判为 failed。
+        """
+        if conversation_id and conversation_id in self.multi_agent_states:
+            state = self.multi_agent_states[conversation_id]
+            agent_ids = {a.agent_id for a in state.list_all()}
+            for task in self.tasks.values():
+                if (
+                    isinstance(task, dict)
+                    and task.get("conversation_id") == conversation_id
+                    and task.get("agent_id") in agent_ids
+                    and task.get("multi_agent_mode") is None
+                ):
+                    task["multi_agent_mode"] = True
+                    task["updated_at"] = time.time()
+        changed = super().reconcile_task_states(conversation_id=conversation_id)
+
+        # 多智能体模式下，子智能体进入 idle 后底层 asyncio.Task 仍在等待唤醒，
+        # 父类 reconcile 会据此把任务标回 running。这里根据内存中的 SubAgentTask
+        # 实例重新把 idle 状态写回任务记录，使运行态与 MultiAgentState 保持一致。
+        extra_changed = 0
+        for task in self.tasks.values():
+            if not isinstance(task, dict):
+                continue
+            if conversation_id and task.get("conversation_id") != conversation_id:
+                continue
+            if not task.get("multi_agent_mode"):
+                continue
+            agent_id = task.get("agent_id")
+            inst = self._sub_agent_instances.get(agent_id) if agent_id else None
+            if inst:
+                if getattr(inst, "_idle", False):
+                    if task.get("status") != "idle":
+                        task["status"] = "idle"
+                        task["updated_at"] = time.time()
+                        ma_debug(
+                            "reconcile_task_runtime_state_idle_fix",
+                            task_id=task.get("task_id"),
+                            agent_id=agent_id,
+                        )
+                        extra_changed += 1
+                elif task.get("status") == "idle":
+                    # 子智能体已被唤醒且 _idle=false，但 output 文件或父类 reconcile
+                    # 可能仍把任务标为 idle。这里强制同步回 running。
+                    task["status"] = "running"
+                    task["updated_at"] = time.time()
+                    ma_debug(
+                        "reconcile_task_runtime_state_running_fix",
+                        task_id=task.get("task_id"),
+                        agent_id=agent_id,
+                    )
+                    extra_changed += 1
+        if extra_changed:
+            self._save_state()
+            changed += extra_changed
+        return changed
+
+    def inject_message_to_sub_agent(self, agent_id: int, message_text: str) -> bool:
+        """同事件循环中向子智能体上下文插入 user 消息。
+        
+        适用于 ask_other_agent / send_message_to_sub_agent / answer_sub_agent_question_
+        （非阻塞到工具结果的路径）。返回 True 表示成功注入。
+        """
+        # 查找该 agent_id 对应的 running SubAgentTask
+        sub_agent = self._find_sub_agent_task_by_agent_id(agent_id)
+        ma_debug(
+            "manager_inject_message_to_sub_agent",
+            agent_id=agent_id,
+            message_preview=str(message_text)[:500],
+            found=bool(sub_agent),
+            task_id=sub_agent.task_id if sub_agent else None,
+        )
+        if not sub_agent:
+            return False
+        sub_agent.inject_message(message_text)
+        return True
+
+    def _find_sub_agent_task_by_agent_id(self, agent_id: int) -> Optional[Any]:
+        """通过遍历创建中的 task 查找活 SubAgentTask 实例。
+        
+        这是个 helper：在主实现中我们需要保留从 agent_id 到 SubAgentTask 的引用。
+        理论上可以在 create_sub_agent 时把 sub_agent 存起来，这里使用 rs safer贪心法：
+        遊历 _running_tasks 不为可行，因为 asyncio.Task 不抽不包含 SubAgentTask引用。
+        我们改为 `SubAgentTask` 对象列表供查询。
+        """
+        # 优先查缓存：create_sub_agent 时的字段
+        for inst in self._sub_agent_instances.values():
+            if inst.agent_id == agent_id:
+                return inst
+        return None
+
+    def _on_multi_agent_task_done(self, task_id: str, agent_id: int, state: Any, sub_agent: Any) -> None:
+        """SubAgentTask 结束回调会调这个更新 MultiAgentState 实例状态。"""
+        final_task = self.tasks.get(task_id) or {}
+        final_status_before = final_task.get("status")
+        ma_debug(
+            "manager_on_multi_agent_task_done",
+            task_id=task_id,
+            agent_id=agent_id,
+            sub_agent_idle=getattr(sub_agent, "_idle", False),
+            sub_agent_cancelled=getattr(sub_agent, "_cancelled", False),
+            task_status_before=final_status_before,
+        )
+        # 多智能体模式下，子智能体自然进入 idle 后 Task 可能被外部事件循环取消，
+        # 或者 reconcile 把 idle 误判为 failed。优先以 SubAgentTask 自身状态为准：
+        # - 被手动取消 -> terminated
+        # - 自然进入 idle -> idle（可继续接收消息）
+        # - 真正异常/超时/finish_task 失败 -> failed/timeout
+        if getattr(sub_agent, "_cancelled", False):
+            state.mark_status(agent_id, "terminated")
+            ma_debug("manager_ma_state_set", agent_id=agent_id, status="terminated", reason="sub_agent_cancelled")
+            return
+        if getattr(sub_agent, "_idle", False):
+            state.mark_status(agent_id, "idle")
+            ma_debug("manager_ma_state_set", agent_id=agent_id, status="idle", reason="sub_agent_idle")
+            return
+
+        # 兜底：取出当前 task status（由 _finalize_task 设置）
+        final_status = final_task.get("status")
+        if final_status in TERMINAL_STATUSES:
+            state.mark_status(agent_id, final_status, last_output=str(final_task.get("final_result") or ""))
+            ma_debug("manager_ma_state_set", agent_id=agent_id, status=final_status, reason="task_terminal_status")
+        elif final_status == "terminated":
+            state.mark_status(agent_id, "terminated")
+            ma_debug("manager_ma_state_set", agent_id=agent_id, status="terminated", reason="task_terminated_status")
+        else:
+            state.mark_status(agent_id, "idle")
+            ma_debug("manager_ma_state_set", agent_id=agent_id, status="idle", reason="fallback_idle")
+
     def _get_runtime_path(self, host_path: Path) -> str:
         """将宿主机路径映射为容器内路径（仅用于提示展示）。"""
         if not self.container_session or getattr(self.container_session, "mode", None) != "docker":

modules/sub_agent/prompts.py

@@ -1,11 +1,49 @@
-"""子智能体提示词构建。"""
+"""子智能体提示词构建。
 
+所有 prompt 正文均从 prompts/sub_agent/ 下的文本文件加载，避免在代码中硬编码。
+"""
 from __future__ import annotations
 
 import platform
 from datetime import datetime
+from pathlib import Path
 from typing import Optional
 
+try:
+    from config import PROMPTS_DIR
+except ImportError:
+    import sys
+
+    project_root = Path(__file__).resolve().parents[2]
+    if str(project_root) not in sys.path:
+        sys.path.insert(0, str(project_root))
+    from config import PROMPTS_DIR
+
+
+_SUB_AGENT_PROMPTS_DIR = Path(PROMPTS_DIR) / "sub_agent"
+_TEMPLATE_CACHE: dict[str, str] = {}
+
+
+def _load_template(name: str) -> str:
+    """从 prompts/sub_agent/<name>.txt 加载模板，带缓存。"""
+    cached = _TEMPLATE_CACHE.get(name)
+    if cached is not None:
+        return cached
+
+    template_path = _SUB_AGENT_PROMPTS_DIR / f"{name}.txt"
+    if not template_path.exists():
+        raise FileNotFoundError(f"子智能体 prompt 模板缺失: {template_path}")
+
+    content = template_path.read_text(encoding="utf-8")
+    _TEMPLATE_CACHE[name] = content
+    return content
+
+
+def _format_template(name: str, **kwargs) -> str:
+    """加载模板并用 str.format 填充占位符。"""
+    template = _load_template(name)
+    return template.format(**kwargs)
+
 
 def build_user_message(
     agent_id: int,
@@ -15,100 +53,23 @@ def build_user_message(
     timeout_seconds: int,
 ) -> str:
     """构建发送给子智能体的用户消息。"""
-    return f"""你是子智能体 #{agent_id}，负责完成以下任务：
-
-**任务摘要**：{summary}
-
-**任务详情**：
-{task}
-
-**交付目录**：{deliverables_path}
-请将所有生成的文件保存到此目录。
-
-**超时时间**：{timeout_seconds} 秒
-
-完成任务后，请调用 finish_task 工具提交完成报告。"""
+    return _format_template(
+        "user_message",
+        agent_id=agent_id,
+        summary=summary,
+        task=task,
+        deliverables_path=deliverables_path,
+        timeout_seconds=timeout_seconds,
+    )
 
 
 def build_system_prompt(workspace_path: str) -> str:
     """构建子智能体的系统提示。"""
     system_info = f"{platform.system()} {platform.release()}"
     current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-
-    return f"""你是一个专注的子智能体，负责独立完成分配的任务。
-
-# 身份定位
-
-你是主智能体创建的子智能体，拥有完整的工具能力（读写文件、执行命令、搜索网页等）。你的职责是专注完成分配的单一任务，不要偏离任务目标。
-
-# 工作流程
-
-1. **理解任务**：仔细阅读任务描述，明确目标和要求
-2. **制定计划**：规划完成任务的步骤
-3. **执行任务**：使用工具完成各个步骤
-4. **生成交付**：将所有结果文件放到指定的交付目录
-5. **提交报告**：使用 finish_task 工具提交完成报告并退出
-
-# 工作原则
-
-## 专注性
-- 只完成分配的任务，不要做额外的工作
-- 不要尝试与用户对话或询问问题
-- 遇到问题时，在能力范围内解决或在报告中说明
-
-## 独立性
-- 你与主智能体共享工作区，可以访问所有文件
-- 你的工作范围应该与其他子智能体不重叠
-- 不要修改任务描述之外的文件
-
-## 效率性
-- 直接开始工作，不要过度解释
-- 合理使用工具，避免重复操作
-- 注意超时限制，在时间内完成核心工作
-
-## 完整性
-- 确保交付目录中的文件完整可用
-- 生成的文档要清晰、格式正确
-- 代码要包含必要的注释和说明
-
-# 交付要求
-
-所有结果文件必须放在指定的交付目录中，包括：
-- 主要成果文件（文档、代码、报告等）
-- 支持文件（数据、配置、示例等）
-- 不要在交付目录外创建文件
-
-# 完成任务
-
-任务完成后，必须调用 finish_task 工具：
-- success: 是否成功完成
-- summary: 完成摘要（说明做了什么、生成了什么）
-
-调用 finish_task 后，你会立即退出，无法继续工作。
-
-# 工具使用
-
-你拥有以下工具能力：
-- read_file: 读取文件内容
-- write_file / edit_file: 创建或修改文件
-- search_workspace: 搜索文件和代码
-- run_command: 执行终端命令
-- web_search / extract_webpage: 搜索和提取网页内容
-- read_mediafile: 读取图片/视频文件
-- finish_task: 完成任务并退出（必须调用）
-
-# 注意事项
-
-1. **结果传达**：你在运行期间产生的记录与输出不会被直接传递给主智能体。务必把所有需要传达的信息写进 `finish_task` 工具的 `summary` 字段，以及交付目录中的落盘文件里。
-2. **不要无限循环**：如果任务无法完成，说明原因并提交报告
-3. **不要超出范围**：只操作任务描述中指定的文件/目录
-4. **不要等待输入**：你是自主运行的，不会收到用户的进一步指令
-5. **注意时间限制**：超时会被强制终止，优先完成核心工作
-
-# 当前环境
-
-- 工作区路径: {workspace_path}
-- 系统: {system_info}
-- 当前时间: {current_time}
-
-现在开始执行任务。"""
+    return _format_template(
+        "system",
+        workspace_path=workspace_path,
+        system_info=system_info,
+        current_time=current_time,
+    )

modules/sub_agent/state.py

@@ -8,6 +8,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from utils.logger import setup_logger
+from modules.multi_agent.debug_logger import ma_debug
 
 logger = setup_logger(__name__)
 TERMINAL_STATUSES = {"completed", "failed", "timeout"}
@@ -50,6 +51,38 @@ class SubAgentStateMixin:
             self.tasks = merged_tasks
             self.conversation_agents = loaded_agents
 
+            # 恢复多智能体运行态（如果状态文件包含）
+            try:
+                from modules.multi_agent.state import MultiAgentState
+
+                manager = self
+                multi_agent_states = getattr(manager, "multi_agent_states", None)
+                if multi_agent_states is not None and isinstance(multi_agent_states, dict):
+                    loaded_ma_states = data.get("multi_agent_states", {})
+                    for conv_id, snapshot in loaded_ma_states.items():
+                        try:
+                            if isinstance(snapshot, dict):
+                                # 关键：不要覆盖内存中已存在的 MultiAgentState，
+                                # 否则 SubAgentTask 持有的旧引用上的 pending_master_messages
+                                # 会被新的空 state 覆盖，导致子智能体输出丢失。
+                                if conv_id in multi_agent_states:
+                                    ma_debug(
+                                        "load_state_skip_existing_ma_state",
+                                        conversation_id=conv_id,
+                                        existing_state_id=id(multi_agent_states[conv_id]),
+                                    )
+                                    continue
+                                multi_agent_states[conv_id] = MultiAgentState.from_snapshot(snapshot)
+                                ma_debug(
+                                    "load_state_restore_ma_state",
+                                    conversation_id=conv_id,
+                                    state_id=id(multi_agent_states[conv_id]),
+                                )
+                        except Exception as exc:
+                            logger.warning(f"恢复多智能体状态失败 {conv_id}: {exc}")
+            except Exception as exc:
+                logger.warning(f"加载多智能体状态失败: {exc}")
+
             if self.tasks:
                 migrated = False
                 for task in self.tasks.values():
@@ -71,6 +104,18 @@ class SubAgentStateMixin:
             "tasks": self.tasks,
             "conversation_agents": self.conversation_agents,
         }
+        # 多智能体运行态持久化
+        try:
+            manager = self
+            multi_agent_states = getattr(manager, "multi_agent_states", None)
+            if multi_agent_states:
+                payload["multi_agent_states"] = {
+                    conv_id: state.to_snapshot()
+                    for conv_id, state in multi_agent_states.items()
+                    if isinstance(state, object) and hasattr(state, "to_snapshot")
+                }
+        except Exception as exc:
+            logger.warning(f"保存多智能体状态失败: {exc}")
         try:
             self.state_file.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
         except Exception as exc:
@@ -94,6 +139,7 @@ class SubAgentStateMixin:
         try:
             output = json.loads(output_file.read_text(encoding="utf-8"))
         except Exception as exc:
+            logger.warning(f"[check_task_status] output 文件解析失败: {exc}")
             task["status"] = "failed"
             task["updated_at"] = time.time()
             return {"success": False, "status": "failed", "task_id": task_id, "message": f"输出文件解析失败: {exc}"}
@@ -103,6 +149,24 @@ class SubAgentStateMixin:
         stats = output.get("stats", {})
         elapsed_seconds = self._compute_elapsed_seconds(task)
 
+        ma_debug(
+            "check_task_status",
+            task_id=task_id,
+            agent_id=task.get("agent_id"),
+            multi_agent_mode=task.get("multi_agent_mode"),
+            output_status=output.get("status"),
+            output_success=success,
+        )
+
+        # 多智能体模式：output 中 status 为 running/idle 表示子智能体仍在运行或
+        # 本轮结束但上下文保留、可继续接收消息，都不是失败/完成。
+        # 此时不生成 final_result，只保持原状态，避免 reconcile 把运行中误判为失败。
+        if task.get("multi_agent_mode") and output.get("status") in {"running", "idle"}:
+            task["status"] = output["status"]
+            task["updated_at"] = time.time()
+            ma_debug("check_task_status_keep_alive", task_id=task_id, status=output["status"])
+            return {"status": output["status"], "task_id": task_id}
+
         if output.get("timeout"):
             status = "timeout"
         elif output.get("max_turns_exceeded"):
@@ -113,6 +177,7 @@ class SubAgentStateMixin:
         else:
             status = "failed"
 
+        ma_debug("check_task_status_result", task_id=task_id, agent_id=task.get("agent_id"), status=status)
         task["status"] = status
         task["updated_at"] = time.time()
         if status == "completed" and elapsed_seconds is not None:
@@ -236,7 +301,25 @@ class SubAgentStateMixin:
         task = self.tasks.get(task_id)
         if not task:
             return
+        # 如果 terminate_sub_agent 已把任务标为 terminated，下渗异步任务自然结束时
+        # 不要被“已完成/fulfilled覆盖为failed”值覆盖，否则 task 被碰成 failed 但实际上
+        # 用户手动终止已发生，状态语义错误且“successful=false”。
+        existing_status = task.get("status")
+        if existing_status in TERMINAL_STATUSES.union({"terminated"}):
+            ma_debug(
+                "mark_task_done_skip_already_terminal",
+                task_id=task_id,
+                existing_status=existing_status,
+            )
+            return
         status = "completed" if success else "failed"
+        ma_debug(
+            "mark_task_done",
+            task_id=task_id,
+            agent_id=task.get("agent_id"),
+            success=success,
+            new_status=status,
+        )
         task["status"] = status
         task["updated_at"] = time.time()
         task["runtime_seconds"] = runtime_seconds
@@ -246,10 +329,19 @@ class SubAgentStateMixin:
     def _refresh_task_runtime_state(self, task: Dict[str, Any]) -> Dict[str, Any]:
         """刷新单个任务运行态。"""
         status = task.get("status")
-        if status in TERMINAL_STATUSES.union({"terminated"}):
-            return {"status": status, "task_id": task.get("task_id")}
-
         task_id = task.get("task_id")
+        agent_id = task.get("agent_id")
+        multi_agent_flag = task.get("multi_agent_mode")
+        ma_debug(
+            "refresh_task_runtime_state_start",
+            task_id=task_id,
+            agent_id=agent_id,
+            before_status=status,
+            multi_agent_mode=multi_agent_flag,
+        )
+        if status in TERMINAL_STATUSES.union({"terminated"}):
+            return {"status": status, "task_id": task_id}
+
         running_task = self._running_tasks.get(task_id) if task_id else None
         if running_task:
             if running_task.done():
@@ -257,12 +349,30 @@ class SubAgentStateMixin:
                     running_task.result(timeout=0)
                 except Exception:
                     pass
-                return self._check_task_status(task)
+                # 多智能体模式：任务自然进入 idle 时不写输出文件，不应标记为失败
+                if task.get("multi_agent_mode") and not Path(task.get("output_file", "")).exists():
+                    task["status"] = "idle"
+                    task["updated_at"] = time.time()
+                    ma_debug("refresh_task_runtime_state_idle_no_output", task_id=task_id)
+                    return {"status": "idle", "task_id": task_id}
+                result = self._check_task_status(task)
+                ma_debug("refresh_task_runtime_state_done_result", task_id=task_id, result=result)
+                return result
+            ma_debug("refresh_task_runtime_state_still_running", task_id=task_id)
             return {"status": "running", "task_id": task_id}
 
         output_file = Path(task.get("output_file", ""))
         if output_file.exists():
-            return self._check_task_status(task)
+            result = self._check_task_status(task)
+            ma_debug("refresh_task_runtime_state_output_result", task_id=task_id, result=result)
+            return result
+
+        # 多智能体模式：没有输出文件表示 idle，不强制清理
+        if task.get("multi_agent_mode"):
+            task["status"] = "idle"
+            task["updated_at"] = time.time()
+            ma_debug("refresh_task_runtime_state_idle_no_output_file", task_id=task_id)
+            return {"status": "idle", "task_id": task_id}
 
         if self._should_force_cleanup_stale_task(task):
             return self._mark_task_terminated(
@@ -282,6 +392,7 @@ class SubAgentStateMixin:
     def reconcile_task_states(self, conversation_id: Optional[str] = None) -> int:
         """修正运行态任务状态，返回修正条目数。"""
         changed = 0
+        ma_debug("reconcile_task_states_start", conversation_id=conversation_id, task_count=len(self.tasks))
         for task in self.tasks.values():
             if not isinstance(task, dict):
                 continue
@@ -290,10 +401,19 @@ class SubAgentStateMixin:
             before_status = task.get("status")
             before_notified = task.get("notified")
             self._refresh_task_runtime_state(task)
-            if task.get("status") != before_status or task.get("notified") != before_notified:
+            after_status = task.get("status")
+            if after_status != before_status or task.get("notified") != before_notified:
+                ma_debug(
+                    "reconcile_task_states_changed",
+                    task_id=task.get("task_id"),
+                    agent_id=task.get("agent_id"),
+                    before_status=before_status,
+                    after_status=after_status,
+                )
                 changed += 1
         if changed:
             self._save_state()
+        ma_debug("reconcile_task_states_end", conversation_id=conversation_id, changed=changed)
         return changed
 
     def _should_force_cleanup_stale_task(self, task: Dict[str, Any]) -> bool:
@@ -303,8 +423,12 @@ class SubAgentStateMixin:
             created_at = 0
         if created_at <= 0:
             return False
+        # timeout_seconds 为 None 表示永久子智能体，不强制清理
+        raw_timeout = task.get("timeout_seconds")
+        if raw_timeout is None:
+            return False
         from config import SUB_AGENT_DEFAULT_TIMEOUT
-        timeout_seconds = int(task.get("timeout_seconds") or SUB_AGENT_DEFAULT_TIMEOUT or 0)
+        timeout_seconds = int(raw_timeout or SUB_AGENT_DEFAULT_TIMEOUT or 0)
         timeout_seconds = max(timeout_seconds, 1)
         grace_seconds = 120
         elapsed = time.time() - created_at

modules/sub_agent/task.py

@@ -4,11 +4,15 @@ import asyncio
 import base64
 import json
 import mimetypes
+import re
+import threading
 import time
 import uuid
 from datetime import datetime
 from pathlib import Path
-from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from typing import Any, Dict, List, Optional, Set, TYPE_CHECKING
+
+_QUESTION_ID_RE = re.compile(r"^id:\s*(\S+)", re.MULTILINE)
 
 from modules.sub_agent.toolkit import (
     SUB_AGENT_TOOLS,
@@ -21,9 +25,21 @@ from utils.logger import setup_logger
 
 if TYPE_CHECKING:
     from modules.sub_agent.manager import SubAgentManager
+    from modules.multi_agent.state import MultiAgentState
+
+from modules.multi_agent.debug_logger import ma_debug
 
 logger = setup_logger(__name__)
 
+# 多智能体模式下额外加载的工具定义
+def _load_multi_agent_sub_agent_tools() -> List[Dict[str, Any]]:
+    try:
+        from modules.multi_agent.tools import build_sub_agent_tools_for_role
+        return build_sub_agent_tools_for_role()
+    except Exception as exc:
+        logger.warning(f"[SubAgentTask] 加载多智能体工具失败: {exc}")
+        return []
+
 
 class SubAgentTask:
     """单个后台子智能体任务。"""
@@ -36,6 +52,10 @@ class SubAgentTask:
         system_prompt: str,
         model_key: Optional[str],
         thinking_mode: Optional[str],
+        *,
+        multi_agent_mode: bool = False,
+        multi_agent_state: Optional["MultiAgentState"] = None,
+        display_name: Optional[str] = None,
     ):
         self.manager = manager
         self.task_record = task_record
@@ -45,13 +65,22 @@ class SubAgentTask:
         self.thinking_mode = thinking_mode or "fast"
         self.task_id = task_record["task_id"]
         self.agent_id = task_record["agent_id"]
-        self.timeout_seconds = int(task_record.get("timeout_seconds") or 180)
+        raw_timeout = task_record.get("timeout_seconds")
+        self.timeout_seconds = int(raw_timeout) if raw_timeout is not None else None
         self.deliverables_dir = Path(task_record["deliverables_dir"])
 
         self.output_file = Path(task_record["output_file"])
         self.stats_file = Path(task_record["stats_file"])
         self.progress_file = Path(task_record["progress_file"])
         self.conversation_file = Path(task_record["conversation_file"])
+        # system_prompt.txt 路径（冻结的 system prompt，压缩后从此重建）
+        self.system_prompt_file = Path(task_record.get("task_root", "")) / "system_prompt.txt"
+
+        # 上下文压缩配置
+        # 默认阈值 150k tokens，可由外部覆盖（如个人空间子智能体管理配置）
+        self.compress_threshold_tokens: int = int(task_record.get("compress_threshold_tokens") or 150_000)
+        self.current_context_tokens: int = 0
+        self._compress_round: int = 0
 
         self.messages: List[Dict[str, Any]] = [
             {"role": "system", "content": system_prompt},
@@ -68,10 +97,28 @@ class SubAgentTask:
             "commands": 0,
             "api_calls": 0,
             "token_usage": {"prompt": 0, "completion": 0, "total": 0},
+            "current_context_tokens": 0,
+            "compress_round": 0,
         }
         self._stdout_lines: List[str] = []
         self._cancelled = False
         self._task: Optional[asyncio.Task] = None
+        # 软停止标志：设为 True 后，子智能体会在当前工具调用完成后
+        # 停止执行后续工具，保存当前进度并进入 idle 状态（不 terminate）
+        self._soft_stop = False
+
+        # 多智能体模式相关字段
+        self.multi_agent_mode = bool(multi_agent_mode)
+        self.multi_agent_state = multi_agent_state
+        # display_name 不传时回退为 'Agent_{self.agent_id}'
+        self.display_name = display_name or f"Agent_{self.agent_id}"
+        # 多智能体运行期控制
+        # 使用 asyncio.Event 在子智能体自己的事件循环内等待；
+        # inject_message 可能跨线程调用，通过 loop.call_soon_threadsafe 唤醒。
+        self._continue_event: Optional[asyncio.Event] = None
+        self._idle = False
+        self._pending_answer_question_id: Optional[str] = None
+        self._answered_question_ids: Set[str] = set()
 
     def emit(self, type_: str, data: Dict[str, Any]) -> None:
         """输出一行 JSONL 到 progress 文件并缓存。"""
@@ -86,51 +133,175 @@ class SubAgentTask:
 
     async def run(self) -> None:
         """主 LLM 循环。"""
+        # 在子智能体自己的事件循环内初始化 asyncio.Event
+        self._continue_event = asyncio.Event()
         try:
             await self._run_loop()
         except asyncio.CancelledError:
+            if self._soft_stop:
+                # 软停止：中断当前工作，从对话文件恢复，重新进入 idle 等待循环
+                ma_debug(
+                    "sub_agent_soft_stop_cancelled",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                )
+                await asyncio.shield(self._recover_from_soft_stop())
+                # 不 raise，不 return——重新进入 idle 等待后续消息
+                # 注意：不能清除 self._task 引用！inject_message 跨线程唤醒时
+                # 需要通过 self._task.get_loop() 获取事件循环来 call_soon_threadsafe。
+                # 当前 task 虽被 cancel 但 CancelledError 被捕获且未 re-raise，
+                # task 会继续执行直到 run() return，此期间 self._task 仍有效。
+                # 进入 idle 等待循环，直到被再次唤醒或取消
+                try:
+                    await asyncio.shield(self._idle_wait_loop())
+                except asyncio.CancelledError:
+                    # 二次取消视为硬取消
+                    self._cancelled = True
+                    await asyncio.shield(self._write_failure("子智能体被手动终止"))
+                    raise
+                return
+            # 硬取消（terminate）路径
             self._cancelled = True
             logger.debug(f"[SubAgent] task={self.task_id} 被取消")
+            ma_debug("sub_agent_run_cancelled", task_id=self.task_id, agent_id=self.agent_id, display_name=self.display_name)
             # shield 避免取消信号中断最终状态落盘
             await asyncio.shield(self._write_failure("子智能体被手动终止"))
             raise
         except Exception as exc:
             logger.exception(f"[SubAgent] task={self.task_id} 执行异常")
+            ma_debug("sub_agent_run_exception", task_id=self.task_id, agent_id=self.agent_id, display_name=self.display_name, error=str(exc))
             await self._write_failure(f"执行异常: {exc}")
 
     async def _run_loop(self) -> None:
         client, model_key = self._build_client()
-        tools = list(SUB_AGENT_TOOLS)
-        tools.append(FINISH_TOOL)
+        if self.multi_agent_mode:
+            tools = list(SUB_AGENT_TOOLS)
+            tools.extend(_load_multi_agent_sub_agent_tools())
+            # 多智能体模式下不要求 finish_task，自然输出结束即进入 idle，可继续接收消息
+        else:
+            tools = list(SUB_AGENT_TOOLS)
+            tools.append(FINISH_TOOL)
 
         start_time = time.time()
         max_turns = 50
+        turn = 0
 
-        for turn in range(1, max_turns + 1):
-            if self._cancelled:
-                break
+        while not self._cancelled:
             elapsed = time.time() - start_time
-            if elapsed > self.timeout_seconds:
+            if self.timeout_seconds is not None and elapsed > self.timeout_seconds:
                 await self._write_timeout(elapsed)
                 return
 
+            # 多智能体模式下，idle 时等待新消息或外部回答；只有真正被注入消息时才继续运行
+            if self.multi_agent_mode and self._idle:
+                event_set = False
+                try:
+                    if self._continue_event is None:
+                        self._continue_event = asyncio.Event()
+                    await asyncio.wait_for(self._continue_event.wait(), timeout=1.0)
+                    event_set = True
+                except asyncio.TimeoutError:
+                    pass
+                if self._cancelled:
+                    break
+                if not event_set:
+                    # 只是周期性检查取消状态，没有新消息，保持 idle 继续等待
+                    continue
+                self._continue_event.clear()
+                ma_debug(
+                    "sub_agent_idle_wake",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                    pending_messages=[m.get("role") for m in self.messages[-3:]],
+                )
+                self._idle = False
+                # 关键修复：从 idle 唤醒后必须同步更新 MultiAgentState 状态为 running，
+                # 否则 has_running_multi_agent 会误判为 false，导致主对话提前进入空闲、
+                # 后续子智能体输出无法推送到主智能体。
+                if self.multi_agent_state:
+                    self.multi_agent_state.mark_status(self.agent_id, "running")
+                    ma_debug(
+                        "sub_agent_idle_wake_mark_running",
+                        task_id=self.task_id,
+                        agent_id=self.agent_id,
+                    )
+                continue
+
+            turn += 1
+            if turn > max_turns:
+                await self._write_failure("任务执行超过最大轮次限制", max_turns_exceeded=True)
+                return
+
             self.stats["api_calls"] += 1
             self.stats["turn_count"] = turn
             self.stats["runtime_seconds"] = int(elapsed)
             self.emit("stats", {**self.stats, "turn_count": turn})
 
+            # 运行期间实时持久化 stats，供 get_sub_agent_status 查询
+            try:
+                self.stats_file.parent.mkdir(parents=True, exist_ok=True)
+                _stats_snapshot = {**self.stats, "runtime_seconds": int(elapsed), "turn_count": turn}
+                self.stats_file.write_text(json.dumps(_stats_snapshot, ensure_ascii=False), encoding="utf-8")
+            except Exception:
+                pass
+
+            # 多智能体模式：在模型调用前识别是否有待回答的提问
+            if self.multi_agent_mode:
+                self._pending_answer_question_id = self._peek_pending_question_id()
+
+            # 调试：记录进入本轮模型调用前的上下文摘要
+            ma_debug(
+                "sub_agent_model_call_start",
+                task_id=self.task_id,
+                agent_id=self.agent_id,
+                display_name=self.display_name,
+                turn=turn,
+                message_count=len(self.messages),
+                last_user_message=self.messages[-1].get("content", "")[:300] if self.messages and self.messages[-1].get("role") == "user" else "",
+                pending_answer_question_id=self._pending_answer_question_id,
+            )
+
             assistant_message, reasoning, tool_calls, usage = await self._call_model(client, model_key, tools)
             if usage:
                 self._apply_usage(usage)
 
+            # 上下文压缩检查：超过阈值时触发深度压缩
+            if self.current_context_tokens > 0 and self.current_context_tokens >= self.compress_threshold_tokens:
+                compressed = self._deep_compress_messages()
+                if compressed:
+                    ma_debug(
+                        "sub_agent_deep_compressed",
+                        task_id=self.task_id,
+                        agent_id=self.agent_id,
+                        display_name=self.display_name,
+                        tokens_before=self.current_context_tokens,
+                        messages_before=len(self.messages) + 1,  # +1 因为本转 assistant 还没 append
+                        messages_after=len(self.messages),
+                        compress_round=self._compress_round,
+                    )
+
+            # 多智能体模式：把 assistant 文本输出作为进度/完成 output 转发到主对话
+            if self.multi_agent_mode and self.multi_agent_state and assistant_message.strip():
+                self._forward_output_to_master(assistant_message, is_final=not tool_calls)
+
             final_message: Dict[str, Any] = {"role": "assistant", "content": assistant_message}
             if reasoning:
                 final_message["reasoning_content"] = reasoning
             if tool_calls:
                 final_message["tool_calls"] = tool_calls
             self.messages.append(final_message)
+            self._persist_conversation(partial_summary=assistant_message[:200])
 
             if not tool_calls:
+                # 多智能体模式：没有 tool_calls 表示本轮结束，进入 idle 等待
+                if self.multi_agent_mode:
+                    self._mark_idle()
+                    self._idle = True
+                    self._persist_conversation(partial_summary=assistant_message[:200])
+                    continue
+                # 普通模式：prompt 并要求继续 / finish_task
                 self.messages.append({
                     "role": "user",
                     "content": "如果你已经完成了任务，请调用 finish_task 工具提交完成报告。如果还没有完成，请继续执行任务。",
@@ -140,6 +311,25 @@ class SubAgentTask:
             for tool_call in tool_calls:
                 if self._cancelled:
                     break
+                # 软停止：如果检测到 _soft_stop，给未执行的工具调用插入取消结果并跳出
+                if self._soft_stop:
+                    ma_debug(
+                        "sub_agent_soft_stop_break",
+                        task_id=self.task_id,
+                        agent_id=self.agent_id,
+                        display_name=self.display_name,
+                        skipped_tool=tool_call.get("function", {}).get("name", ""),
+                    )
+                    # 给未执行的工具调用补上“被取消”的 tool result，保持消息结构合法
+                    cancelled_progress_id = tool_call.get("id") or f"tool_{int(time.time() * 1000)}_{uuid.uuid4().hex[:6]}"
+                    self.emit("progress", {"id": cancelled_progress_id, "tool": tool_call.get("function", {}).get("name", ""), "status": "cancelled", "args": self._parse_args(tool_call), "ts": int(time.time() * 1000)})
+                    self.messages.append({
+                        "role": "tool",
+                        "tool_call_id": tool_call.get("id", cancelled_progress_id),
+                        "content": "⦶ 工具执行被取消（用户手动停止）",
+                    })
+                    self._persist_conversation(partial_summary=assistant_message[:200])
+                    break
                 name = tool_call.get("function", {}).get("name", "")
                 args = self._parse_args(tool_call)
                 progress_id = tool_call.get("id") or f"tool_{int(time.time() * 1000)}_{uuid.uuid4().hex[:6]}"
@@ -162,8 +352,143 @@ class SubAgentTask:
                     "tool_call_id": tool_call.get("id", progress_id),
                     "content": content,
                 })
+                self._persist_conversation(partial_summary=assistant_message[:200])
 
-        await self._write_failure("任务执行超过最大轮次限制", max_turns_exceeded=True)
+            # 软停止：工具循环结束后进入 idle，不 terminate
+            if self._soft_stop and not self._cancelled:
+                ma_debug(
+                    "sub_agent_soft_stop_idle",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                )
+                # 重置软停止标志，下次 Team Leader 可以重新发消息唤醒
+                self._soft_stop = False
+                self._mark_idle()
+                self._idle = True
+                self._persist_conversation(partial_summary=assistant_message[:200])
+                continue
+
+        # 循环结束（取消或 idle 被外部终止）后的清理
+        if self.multi_agent_mode and self._cancelled:
+            if self.multi_agent_state:
+                self.multi_agent_state.mark_status(self.agent_id, "terminated")
+
+    def _forward_output_to_master(self, output_text: str, *, is_final: bool = False) -> None:
+        """把子智能体的 assistant 文本输出转发成主对话的 user 消息，并写入进度文件供前端查看。"""
+        ma_debug(
+            "sub_agent_forward_output_enter",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            display_name=self.display_name,
+            multi_agent_mode=self.multi_agent_mode,
+            has_state=bool(self.multi_agent_state),
+            state_id=id(self.multi_agent_state) if self.multi_agent_state else None,
+            output_len=len(output_text),
+            is_final=is_final,
+        )
+        if not self.multi_agent_state:
+            ma_debug("sub_agent_forward_no_state", task_id=self.task_id, agent_id=self.agent_id)
+            return
+        # 如果这是对 pending 提问的回答，不走主对话转发，而是返回到 ask 工具结果
+        if self._provide_answer(output_text):
+            return
+        try:
+            from modules.multi_agent.state import build_sub_agent_output_text
+            msg = build_sub_agent_output_text(self.display_name, output_text.strip(), is_final=is_final)
+            self.multi_agent_state.push_master_message(msg)
+            ma_debug(
+                "sub_agent_forward_pushed",
+                task_id=self.task_id,
+                agent_id=self.agent_id,
+                state_id=id(self.multi_agent_state) if self.multi_agent_state else None,
+                msg_preview=msg[:200],
+            )
+            # 同时记录到实例状态，供 list_active_sub_agents 使用
+            inst = self.multi_agent_state.get_instance(self.agent_id)
+            if inst:
+                inst.last_output = output_text[:500]
+            # 写入进度文件，前端子智能体进度弹窗可直接展示
+            self.emit("progress", {
+                "subtype": "output",
+                "content": output_text,
+                "is_final": is_final,
+                "ts": int(time.time() * 1000),
+            })
+            ma_debug(
+                "sub_agent_output_forwarded",
+                task_id=self.task_id,
+                agent_id=self.agent_id,
+                display_name=self.display_name,
+                is_final=is_final,
+                content_preview=output_text[:300],
+            )
+        except Exception as exc:
+            logger.warning(f"[SubAgentTask] forward output to master failed: {exc}")
+
+    def _mark_idle(self) -> None:
+        """多智能体模式下，子智能体自然结束即本轮任务结束，进入 idle 状态。"""
+        ma_debug(
+            "sub_agent_mark_idle",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            display_name=self.display_name,
+        )
+        if self.multi_agent_state:
+            self.multi_agent_state.mark_status(self.agent_id, "idle")
+
+    def inject_message(self, message_text: str) -> None:
+        """外部向子智能体上下文插入 user 消息，并唤醒 idle 状态。"""
+        self.messages.append({"role": "user", "content": message_text})
+        ma_debug(
+            "sub_agent_message_injected",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            display_name=self.display_name,
+            message_preview=str(message_text)[:500],
+            was_idle=self._idle,
+        )
+        # inject_message 可能从其他线程（主对话线程）调用，需要线程安全唤醒。
+        # 优先使用子智能体 Task 所属事件循环投递 set()，避免跨线程直接操作 Future。
+        if self._continue_event is None:
+            self._continue_event = asyncio.Event()
+        if self._task is not None:
+            try:
+                task_loop = self._task.get_loop()
+                if task_loop.is_running():
+                    task_loop.call_soon_threadsafe(self._continue_event.set)
+                    return
+            except Exception:
+                pass
+        self._continue_event.set()
+
+    def _peek_pending_question_id(self) -> Optional[str]:
+        """检查最后一条 user 消息是否是向本智能体提问，返回 question_id。"""
+        if not self.multi_agent_mode or not self.messages:
+            return None
+        for msg in reversed(self.messages):
+            if msg.get("role") == "user":
+                content = msg.get("content") or ""
+                if "的提问" in content:
+                    m = _QUESTION_ID_RE.search(content)
+                    if m:
+                        qid = m.group(1)
+                        if qid not in self._answered_question_ids:
+                            return qid
+                break
+        return None
+
+    def _provide_answer(self, output_text: str) -> bool:
+        """如果当前输出是对 pending 提问的回答，把回答写回 future 并阻止转发到主对话。"""
+        if not self._pending_answer_question_id or not self.multi_agent_state:
+            return False
+        self.multi_agent_state.provide_answer(
+            self._pending_answer_question_id,
+            output_text.strip(),
+        )
+        self._answered_question_ids.add(self._pending_answer_question_id)
+        self._pending_answer_question_id = None
+        return True
 
     def _build_client(self) -> tuple:
         """加载模型配置并初始化 DeepSeekClient。"""
@@ -215,8 +540,12 @@ class SubAgentTask:
         usage = None
 
         async for chunk in client.chat(self.messages, tools=tools, stream=True):
-            if self._cancelled:
+            if self._soft_stop:
+                # 软停止：优雅中断当前模型调用，后续由 _run_loop 丢弃半成品并进入 idle
                 break
+            if self._cancelled:
+                # 硬取消：立即抛出 CancelledError，确保不会返回半成品的 tool_calls 继续执行
+                raise asyncio.CancelledError()
             if chunk.get("error"):
                 raise RuntimeError(f"API 调用失败: {chunk.get('error')}")
             choice = (chunk.get("choices") or [{}])[0]
@@ -262,9 +591,102 @@ class SubAgentTask:
             return {"_raw": raw}
 
     async def _execute_tool(self, name: str, args: Dict[str, Any]) -> Dict[str, Any]:
-        """通过 manager 调用主进程执行工具。"""
+        """通过 manager 调用主进程执行工具。
+        
+        多智能体模式下，对于通信工具（ask_master / ask_other_agent / answer_other_agent/
+        list_active_sub_agents）在主进程内直接处理，不再转发到 WebTerminal。
+        """
+        if self.multi_agent_mode and self.multi_agent_state:
+            result = await self._execute_multi_agent_tool(name, args)
+            if result is not None:
+                return result
         return await self.manager.execute_tool_for_sub_agent(name, args)
 
+    async def _execute_multi_agent_tool(self, name: str, args: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        """处理多智能体模式专属的通信工具。返回 None 表示不 属于多智能体工具。"""
+        state = self.multi_agent_state
+        if not state:
+            return None
+        try:
+            if name == "ask_master":
+                question = str(args.get("question") or "").strip()
+                question_id = str(args.get("question_id") or f"ask_master_{uuid.uuid4().hex[:10]}")
+                ma_debug(
+                    "sub_agent_tool_ask_master",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                    question_id=question_id,
+                    question=question[:500],
+                )
+                if not question:
+                    return {"success": False, "error": "question 不能为空"}
+                # 插入到主对话
+                from modules.multi_agent.state import build_sub_agent_ask_master_text
+                msg = build_sub_agent_ask_master_text(self.display_name, question, question_id)
+                state.push_master_message(msg)
+                inst = state.get_instance(self.agent_id)
+                if inst:
+                    inst.last_output = f"[ask_master] {question[:200]}"
+                # 阻塞等待回答（状态标为正在等待主智能体回答）
+                state.mark_status(self.agent_id, "running")
+                try:
+                    answer = await state.wait_for_answer(question_id, self.agent_id, timeout=float(args.get("timeout_seconds") or 600))
+                except asyncio.CancelledError:
+                    # 软停止取消了等待 future，返回取消结果而非抛 CancelledError
+                    return {"success": False, "error": "等待回答被取消（软停止）", "question_id": question_id}
+                state.mark_status(self.agent_id, "running")
+                return {"success": True, "answer": answer, "question_id": question_id}
+
+            if name == "ask_other_agent":
+                target_id = int(args.get("target_agent_id") or 0)
+                question = str(args.get("question") or "").strip()
+                question_id = str(args.get("question_id") or f"ask_other_{uuid.uuid4().hex[:10]}")
+                ma_debug(
+                    "sub_agent_tool_ask_other_agent",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                    target_agent_id=target_id,
+                    question_id=question_id,
+                    question=question[:500],
+                )
+                if not target_id or not question:
+                    return {"success": False, "error": "参数缺失"}
+                # 查找目标实例
+                target_inst = state.get_instance(target_id)
+                if not target_inst:
+                    return {"success": False, "error": f"agent {target_id} 不存在"}
+                # 构造提问消息并插入到目标子对话；同时要求其在下一轮调用 answer_other_agent
+                from modules.multi_agent.state import build_sub_agent_ask_other_text
+                target_display = target_inst.display_name
+                msg = build_sub_agent_ask_other_text(self.display_name, target_display, question, question_id)
+                self.manager.inject_message_to_sub_agent(target_id, msg)
+                # 阻塞等待回答
+                try:
+                    answer = await state.wait_for_answer(question_id, self.agent_id, timeout=float(args.get("timeout_seconds") or 600))
+                except asyncio.CancelledError:
+                    return {"success": False, "error": "等待回答被取消（软停止）", "question_id": question_id}
+                return {"success": True, "answer": answer, "question_id": question_id}
+
+            if name == "answer_other_agent":
+                source_id = int(args.get("source_agent_id") or 0)
+                question_id = str(args.get("question_id") or "")
+                answer = str(args.get("answer") or "").strip()
+                if not question_id or not answer:
+                    return {"success": False, "error": "参数缺失"}
+                ok = state.provide_answer(question_id, answer)
+                return {"success": bool(ok), "question_id": question_id}
+
+            if name == "list_active_sub_agents":
+                return {"success": True, "agents": [a.to_dict() for a in state.list_all()]}
+        except asyncio.TimeoutError:
+            return {"success": False, "error": "等待回答超时", "question_id": args.get("question_id")}
+        except Exception as exc:
+            logger.exception(f"[SubAgent] 多智能体工具异常: {name}")
+            return {"success": False, "error": f"多智能体工具异常: {exc}"}
+        return None
+
     def _update_stats(self, name: str) -> None:
         if name == "read_file":
             self.stats["files_read"] += 1
@@ -274,11 +696,20 @@ class SubAgentTask:
             self.stats["edit_files"] += 1
         elif name == "search_workspace":
             self.stats["searches"] += 1
-        elif name in ("web_search", "extract_webpage"):
+        elif name in ("web_search", "extract_webpage", "save_webpage"):
             self.stats["web_pages"] += 1
         elif name == "run_command":
             self.stats["commands"] += 1
 
+        # 工具调用后立即持久化 stats，供运行期间 get_sub_agent_status 查询
+        try:
+            self.stats_file.parent.mkdir(parents=True, exist_ok=True)
+            _elapsed = int((time.time() * 1000 - self.stats["runtime_start"]) / 1000)
+            _snapshot = {**self.stats, "runtime_seconds": _elapsed, "turn_count": self.stats.get("turn_count", 0)}
+            self.stats_file.write_text(json.dumps(_snapshot, ensure_ascii=False), encoding="utf-8")
+        except Exception:
+            pass
+
     def _apply_usage(self, usage: Any) -> None:
         try:
             if isinstance(usage, dict):
@@ -288,9 +719,156 @@ class SubAgentTask:
                 self.stats["token_usage"]["prompt"] += int(prompt)
                 self.stats["token_usage"]["completion"] += int(completion)
                 self.stats["token_usage"]["total"] += int(total)
+                # prompt_tokens 即为当前上下文占用的 tokens
+                self.current_context_tokens = int(prompt)
+                self.stats["current_context_tokens"] = int(prompt)
         except Exception:
             pass
 
+    def _rebuild_system_prompt(self) -> str:
+        """从冻结的 system_prompt.txt 重新读取 system prompt（压缩后重建用）。"""
+        try:
+            if self.system_prompt_file.exists():
+                return self.system_prompt_file.read_text(encoding="utf-8")
+        except Exception as exc:
+            logger.warning(f"[SubAgentTask] 重建 system prompt 失败: {exc}")
+        # 兜底用内存中的
+        return self.system_prompt
+
+    def _deep_compress_messages(self) -> bool:
+        """深度压缩：把旧消息总结成一条 system 消息，重建 system prompt。
+
+        策略（参考主智能体 compress_conversation）：
+        1. 保留冻结的 system prompt（从 system_prompt.txt 读取）
+        2. 把 system 之后、最近 N 条消息之前的所有消息压缩成一条 system 摘要
+        3. 保留最近的若干条消息（含 tool_calls 配对）不动
+        4. 重置 current_context_tokens 估算值
+
+        返回 True 表示执行了压缩。
+        """
+        if len(self.messages) < 6:
+            # 消息太少不压缩
+            return False
+
+        self._compress_round += 1
+        self.stats["compress_round"] = self._compress_round
+
+        # 保留最近 8 条消息不压缩（确保 tool_calls 和 tool 结果配对完整）
+        keep_recent = 8
+        # 找到一个安全的切割点：不能在 assistant.tool_calls 和其 tool 响应之间切
+        cut_index = len(self.messages) - keep_recent
+        # 向前调整，确保不在 tool_calls 配对中间切割
+        while cut_index > 1:
+            msg = self.messages[cut_index]
+            role = msg.get("role")
+            # 如果切点是 tool 消息，往前找到对应的 assistant
+            if role == "tool":
+                cut_index -= 1
+                continue
+            # 如果切点的 assistant 有 tool_calls，需要保留它和后续 tool
+            if role == "assistant" and msg.get("tool_calls"):
+                break
+            break
+        if cut_index <= 1:
+            return False
+
+        # 提取要压缩的消息（索引 1 到 cut_index-1，跳过索引 0 的 system prompt）
+        old_messages = self.messages[1:cut_index]
+        if not old_messages:
+            return False
+
+        # 生成压缩摘要
+        summary_lines: List[str] = []
+        summary_lines.append("系统提示：以下是根据之前的对话记录生成的压缩摘要，请在此基础上继续工作。")
+        summary_lines.append(f"（压缩轮次：第 {self._compress_round} 次，压缩前消息数：{len(self.messages)}）")
+        summary_lines.append("")
+
+        tool_buffer: List[str] = []
+        seen_tool_call_ids: Set[str] = set()
+
+        def flush_tools():
+            if not tool_buffer:
+                return
+            if summary_lines and summary_lines[-1] != "":
+                summary_lines.append("")
+            summary_lines.append("已执行的工具：")
+            summary_lines.extend(f"- {entry}" for entry in tool_buffer)
+            tool_buffer.clear()
+
+        for message in old_messages:
+            role = message.get("role")
+            if role == "user":
+                flush_tools()
+                content = str(message.get("content") or "")[:500]  # 截断长内容
+                summary_lines.append(f"user：{content}")
+                continue
+            if role == "assistant":
+                content = str(message.get("content") or "")
+                if content.strip():
+                    flush_tools()
+                    summary_lines.append(f"assistant：{content[:500]}")
+                tool_calls = message.get("tool_calls") or []
+                for tc in tool_calls:
+                    tc_id = tc.get("id") or tc.get("tool_call_id")
+                    if tc_id:
+                        seen_tool_call_ids.add(tc_id)
+                    func = tc.get("function") or {}
+                    arguments = func.get("arguments")
+                    args_obj = {}
+                    if isinstance(arguments, str):
+                        try:
+                            args_obj = json.loads(arguments)
+                        except Exception:
+                            args_obj = {}
+                    elif isinstance(arguments, dict):
+                        args_obj = arguments
+                    intent = args_obj.get("intent") if isinstance(args_obj, dict) else None
+                    name = func.get("name") or "unknown_tool"
+                    entry = intent.strip() if isinstance(intent, str) and intent.strip() else name
+                    tool_buffer.append(entry)
+                continue
+            if role == "tool":
+                tc_id = message.get("tool_call_id") or message.get("id")
+                if tc_id and tc_id in seen_tool_call_ids:
+                    continue
+                name = message.get("name") or "unknown_tool"
+                tool_buffer.append(name)
+                continue
+            # 其他角色
+            flush_tools()
+            content = str(message.get("content") or "")[:300]
+            summary_lines.append(f"{role}：{content}" if role else content)
+
+        flush_tools()
+        summary_text = "\n".join(summary_lines)
+
+        # 重建消息列表：冻结的 system prompt + 压缩摘要 system + 保留的最近消息
+        frozen_system = self._rebuild_system_prompt()
+        compressed_system = {
+            "role": "system",
+            "content": summary_text,
+            "metadata": {
+                "compression": {
+                    "round": self._compress_round,
+                    "compressed_count": len(old_messages),
+                    "created_at": datetime.now().isoformat(),
+                }
+            },
+        }
+        recent_messages = self.messages[cut_index:]
+        self.messages = [frozen_system, compressed_system] + recent_messages
+
+        # 重置上下文 tokens 估算（压缩后无法精确知道，设为一个保守值）
+        self.current_context_tokens = 0
+        self.stats["current_context_tokens"] = 0
+
+        logger.info(
+            f"[SubAgentTask] task={self.task_id} 深度压缩完成: "
+            f"压缩 {len(old_messages)} 条消息，保留 {len(recent_messages)} 条，"
+            f"压缩轮次={self._compress_round}"
+        )
+        return True
+
     def _build_media_tool_content(self, result: Dict[str, Any]) -> Any:
         """把 read_mediafile 结果转成 OpenAI 多模态 content。"""
         b64 = result.get("b64")
@@ -320,10 +898,140 @@ class SubAgentTask:
 
     async def _write_failure(self, message: str, *, max_turns_exceeded: bool = False, timeout: bool = False) -> None:
         elapsed = time.time() - (self.stats["runtime_start"] / 1000)
+        ma_debug(
+            "sub_agent_write_failure",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            display_name=self.display_name,
+            message=message,
+            max_turns_exceeded=max_turns_exceeded,
+            timeout=timeout,
+            idle=self._idle,
+            cancelled=self._cancelled,
+        )
         self._finalize_task(False, message, elapsed, max_turns_exceeded=max_turns_exceeded, timeout=timeout)
 
+    def _persist_conversation(self, *, partial_summary: str = "") -> None:
+        """每轮结束后立即落盘子智能体对话，避免跑完了才存一次导致中间状态丢失。"""
+        try:
+            runtime_seconds = int((time.time() * 1000 - self.stats["runtime_start"]) / 1000)
+            status = "running"
+            if self._cancelled:
+                status = "terminated"
+            elif self.multi_agent_mode and self._idle:
+                status = "idle"
+            ma_debug(
+                "sub_agent_persist_conversation",
+                task_id=self.task_id,
+                agent_id=self.agent_id,
+                display_name=self.display_name,
+                status=status,
+                idle=self._idle,
+                cancelled=self._cancelled,
+                multi_agent_mode=self.multi_agent_mode,
+            )
+            conversation_data = {
+                "agent_id": self.agent_id,
+                "task_id": self.task_id,
+                "created_at": datetime.fromtimestamp(self.stats["runtime_start"] / 1000).isoformat(),
+                "updated_at": datetime.now().isoformat(),
+                "status": status,
+                "success": None,
+                "summary": partial_summary,
+                "messages": self.messages,
+                "stats": {**self.stats, "runtime_seconds": runtime_seconds, "turn_count": self.stats.get("turn_count", 0)},
+            }
+            self.conversation_file.parent.mkdir(parents=True, exist_ok=True)
+            self.conversation_file.write_text(json.dumps(conversation_data, ensure_ascii=False), encoding="utf-8")
+
+            output_data = {
+                "success": None,
+                "status": status,
+                "summary": partial_summary,
+                "stats": conversation_data["stats"],
+            }
+            self.output_file.parent.mkdir(parents=True, exist_ok=True)
+            self.output_file.write_text(json.dumps(output_data, ensure_ascii=False), encoding="utf-8")
+        except Exception as exc:
+            logger.warning(f"[SubAgentTask] 增量保存失败: {exc}")
+
+    async def _recover_from_soft_stop(self) -> None:
+        """软停止恢复：从磁盘重新加载对话文件，丢弃半成品状态，变 idle。
+
+        被取消时的半成品状态（调用一半的工具、未执行的 tool_calls）不会
+        在对话文件里，因为 _persist_conversation 只在完整轮次结束时保存。
+        """
+        try:
+            if self.conversation_file.exists():
+                data = json.loads(self.conversation_file.read_text(encoding="utf-8"))
+                self.messages = data.get("messages", [])
+                ma_debug(
+                    "sub_agent_soft_stop_recovered",
+                    task_id=self.task_id,
+                    agent_id=self.agent_id,
+                    display_name=self.display_name,
+                    messages_count=len(self.messages),
+                )
+        except Exception as exc:
+            logger.warning(f"[SubAgentTask] 软停止恢复失败: {exc}")
+
+        # 重置标志和状态
+        self._soft_stop = False
+        self._cancelled = False
+        self._idle = True
+        if self.multi_agent_state:
+            self.multi_agent_state.mark_status(self.agent_id, "idle")
+        # 重新初始化 continue event 以备后续唤醒
+        self._continue_event = asyncio.Event()
+        # 持久化恢复后的状态
+        self._persist_conversation(partial_summary="[soft stopped]")
+
+    async def _idle_wait_loop(self) -> None:
+        """软停止后进入的 idle 等待循环。
+
+        保持子智能体活着，等待新消息注入后重新进入 _run_loop 正常工作。
+        """
+        while not self._cancelled:
+            if self._continue_event is None:
+                self._continue_event = asyncio.Event()
+            try:
+                await asyncio.wait_for(self._continue_event.wait(), timeout=1.0)
+            except asyncio.TimeoutError:
+                pass
+            if self._cancelled:
+                break
+            if not self._continue_event.is_set():
+                continue
+            # 被唤醒了，有新消息注入，重新进入正常 _run_loop
+            self._continue_event.clear()
+            self._idle = False
+            if self.multi_agent_state:
+                self.multi_agent_state.mark_status(self.agent_id, "running")
+            ma_debug(
+                "sub_agent_idle_wait_wake",
+                task_id=self.task_id,
+                agent_id=self.agent_id,
+                display_name=self.display_name,
+            )
+            # 重新进入正常循环
+            await self._run_loop()
+            # _run_loop 退出后再次 idle 等待
+            self._idle = True
+            if self.multi_agent_state:
+                self.multi_agent_state.mark_status(self.agent_id, "idle")
+
     def _finalize_task(self, success: bool, summary: str, elapsed: float, *, max_turns_exceeded: bool = False, timeout: bool = False) -> None:
         runtime_seconds = int(elapsed)
+        ma_debug(
+            "sub_agent_finalize_task",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            display_name=self.display_name,
+            success=success,
+            summary=summary,
+            idle=self._idle,
+            cancelled=self._cancelled,
+        )
         output_data = {
             "success": success,
             "summary": summary,
@@ -356,3 +1064,45 @@ class SubAgentTask:
         self._cancelled = True
         if self._task and not self._task.done():
             self._task.cancel()
+
+    def request_soft_stop(self) -> None:
+        """请求软停止：中断子智能体当前工作 → 从对话文件恢复 → 变 idle。
+
+        与 cancel() 的区别：
+        - cancel(): 取消 asyncio.Task → CancelledError → _write_failure → terminated
+        - request_soft_stop(): 设标志 + cancel asyncio.Task → CancelledError
+          → 捕获后重载对话文件（丢弃半成品）→ mark idle → 保留实例
+        """
+        self._soft_stop = True
+        ma_debug(
+            "sub_agent_request_soft_stop",
+            task_id=self.task_id,
+            agent_id=self.agent_id,
+            has_task=bool(self._task),
+            task_done=self._task.done() if self._task else None,
+        )
+        # 取消子智能体正在阻塞等待的 ask_master/ask_other 未来，解除阻塞
+        if self.multi_agent_state and self.agent_id is not None:
+            try:
+                self.multi_agent_state.cancel_pending_question_for_agent(self.agent_id)
+            except Exception:
+                pass
+        # 直接 cancel asyncio.Task 以中断正在执行的工具调用/API 调用
+        # CancelledError 会在 run() 中被捕获，检测到 _soft_stop 后走恢复路径
+        if self._task and not self._task.done():
+            try:
+                loop = self._task.get_loop()
+                loop.call_soon_threadsafe(self._task.cancel)
+            except Exception:
+                self._task.cancel()
+
+        # 额外保险：如果 _task 为 None 但子智能体状态是 running，直接设 idle 状态
+        if self._task is None and self.multi_agent_state and self.agent_id is not None:
+            ma_debug("sub_agent_soft_stop_no_task_mark_idle", task_id=self.task_id, agent_id=self.agent_id)
+            self._soft_stop = False
+            self._idle = True
+            self.multi_agent_state.mark_status(self.agent_id, "idle")
+            try:
+                self._persist_conversation(partial_summary="[soft stopped no task]")
+            except Exception:
+                pass

modules/sub_agent/toolkit.py

@@ -6,6 +6,8 @@ import json
 from datetime import datetime
 from typing import Any, Dict, List, Optional
 
+from config.model_profiles import _parse_env_ref
+
 # 子智能体可用工具定义（与前端进度展示兼容）
 SUB_AGENT_TOOLS: List[Dict[str, Any]] = [
     {
@@ -180,6 +182,98 @@ SUB_AGENT_TOOLS: List[Dict[str, Any]] = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "read_skill",
+            "description": "按 skill 名称读取 .astrion/skills/<name>/SKILL.md 内容；内部等价于 read_file 的 read 模式，并返回解析后的 path。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "skill_name": {"type": "string", "description": "skill 名称（支持 skill id 或技能名称）"},
+                },
+                "required": ["skill_name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "recall_project_memory",
+            "description": "读取指定的项目记忆文件，返回完整内容（含 frontmatter）。项目记忆存储在 .astrion/memory/ 目录下。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "description": "记忆名称，对应 .astrion/memory/{name}.md 文件名"},
+                },
+                "required": ["name"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_create",
+            "description": "创建待办列表，最多 8 条任务；若已有列表将被覆盖。当任务复杂、预计需要超过 3 个步骤时，应积极创建待办事项。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "overview": {"type": "string", "description": "一句话概述待办清单要完成的目标，50 字以内。"},
+                    "tasks": {
+                        "type": "array",
+                        "description": "任务列表，1~8 条，每条写清“动词+对象+目标”。",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "title": {"type": "string", "description": "单个任务描述，写成可执行的步骤"}
+                            },
+                            "required": ["title"]
+                        },
+                        "minItems": 1,
+                        "maxItems": 8
+                    },
+                },
+                "required": ["overview", "tasks"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "todo_update_task",
+            "description": "批量勾选或取消任务（支持单个或多个任务）；全部勾选时提示所有任务已完成。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "task_index": {"type": "integer", "description": "任务序号（1-8），兼容旧参数"},
+                    "task_indices": {
+                        "type": "array",
+                        "items": {"type": "integer"},
+                        "minItems": 1,
+                        "maxItems": 8,
+                        "description": "要更新的任务序号列表（1-8），可一次勾选多个"
+                    },
+                    "completed": {"type": "boolean", "description": "true=打勾，false=取消"},
+                },
+                "required": ["completed"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "save_webpage",
+            "description": "提取网页内容并保存为纯文本文件，适合需要长期留存的长文档。请提供网址与目标路径（含 .txt 后缀），落地后请通过终端命令查看。",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "url": {"type": "string", "description": "要保存的网页URL"},
+                    "target_path": {"type": "string", "description": "保存位置，包含文件名，相对于项目根目录"},
+                },
+                "required": ["url", "target_path"],
+            },
+        },
+    },
 ]
 
 FINISH_TOOL: Dict[str, Any] = {
@@ -261,20 +355,54 @@ def _format_tool_result(name: str, raw: Any) -> str:
         return ""
     if name == "read_mediafile":
         return raw.get("message") or "媒体已读取"
+    if name == "read_skill":
+        # read_skill 结果结构与 read_file(read) 类似
+        if raw.get("content"):
+            return raw.get("content")
+        return raw.get("message") or "skill 已读取"
+    if name == "recall_project_memory":
+        # recall_project_memory 返回记忆文件完整内容
+        if raw.get("content"):
+            return raw.get("content")
+        return raw.get("message") or raw.get("error") or "记忆已读取"
+    if name == "todo_create":
+        return raw.get("message") or "待办列表已创建"
+    if name == "todo_update_task":
+        return raw.get("message") or "任务状态已更新"
+    if name == "save_webpage":
+        if raw.get("path"):
+            return f"已保存: {raw.get('path')}"
+        return raw.get("message") or "网页已保存"
+    # 多智能体通信工具
+    if name == "ask_master":
+        if raw.get("success"):
+            return f"Team Leader 的回答：\n{raw.get('answer') or ''}"
+        return raw.get("error") or "向 Team Leader 提问失败"
+    if name == "ask_other_agent":
+        if raw.get("success"):
+            return f"子智能体的回答：\n{raw.get('answer') or ''}"
+        return raw.get("error") or "向其他子智能体提问失败"
+    if name == "answer_other_agent":
+        if raw.get("success"):
+            return "回复已发送。"
+        return raw.get("error") or "回复失败"
+    if name == "list_active_sub_agents":
+        from utils.tool_result_formatter.agent_context import _format_active_sub_agents_list
+        return _format_active_sub_agents_list(raw.get("agents") or [])
     return json.dumps(raw, ensure_ascii=False)
 
 
 def _build_sub_agent_profile(model_raw: Dict[str, Any]) -> Optional[Dict[str, Any]]:
     """把 sub_agent_models.json 中的模型条目转成 DeepSeekClient.apply_profile 所需格式。"""
     name = str(model_raw.get("name") or model_raw.get("model_name") or model_raw.get("model") or "").strip()
-    url = str(model_raw.get("url") or model_raw.get("base_url") or "").strip()
-    api_key = str(model_raw.get("apikey") or model_raw.get("api_key") or "").strip()
+    url = str(_parse_env_ref(model_raw.get("url") or model_raw.get("base_url") or "") or "").strip()
+    api_key = str(_parse_env_ref(model_raw.get("apikey") or model_raw.get("api_key") or "") or "").strip()
     if not name or not url or not api_key:
         return None
 
     modes_text = str(model_raw.get("modes") or model_raw.get("mode") or model_raw.get("supported_modes") or "").lower()
-    supports_thinking = "thinking" in modes_text
-    fast_only = modes_text == "fast"
+    supports_thinking = "thinking" in modes_text or "思考" in modes_text
+    fast_only = modes_text == "fast" or modes_text == "快速"
 
     multimodal_text = str(model_raw.get("multimodal") or model_raw.get("multi_modal") or model_raw.get("multi") or "none").lower()
     multimodal = "none"
@@ -288,8 +416,20 @@ def _build_sub_agent_profile(model_raw: Dict[str, Any]) -> Optional[Dict[str, An
 
     model_id = str(model_raw.get("model_id") or name).strip()
     extra = _pick_dict(model_raw, ["extra_parameter", "extra_params", "extra"])
+    # 优先从顶层查找 fast/thinking extra_parameter；如果没有，从 thinkmode_status 中查找
     fast_extra = _pick_dict(model_raw, ["fast_extra_parameter", "fast_extra_params", "fast_extra"])
     thinking_extra = _pick_dict(model_raw, ["thinking_extra_parameter", "thinking_extra_params", "thinking_extra"])
+    # 从 thinkmode_status 中提取（与主智能体 custom_models.json 结构对齐）
+    thinkmode_status = model_raw.get("thinkmode_status") or {}
+    if isinstance(thinkmode_status, dict):
+        if not fast_extra:
+            fast_extra = _pick_dict(thinkmode_status, ["fast_extra_parameter", "fast_extra_params", "fast_extra"])
+        if not thinking_extra:
+            thinking_extra = _pick_dict(thinkmode_status, ["thinking_extra_parameter", "thinking_extra_params", "thinking_extra"])
+        # thinkmode_status 内部的 model_id 可以覆盖默认 model_id
+        ts_model_id = str(thinkmode_status.get("model_id") or "").strip()
+        if ts_model_id:
+            model_id = ts_model_id
 
     profile: Dict[str, Any] = {
         "name": name,
@@ -316,6 +456,8 @@ def _build_sub_agent_profile(model_raw: Dict[str, Any]) -> Optional[Dict[str, An
             "extra_params": {**extra, **thinking_extra},
         }
     else:
+        # 即使不支持 thinking，也保留 fast 的 extra_params（含 disabled 参数）
+        # 避免不支持 thinking 的模型在 fast 模式下漏掉 thinking.type=disabled 参数
         profile["thinking"] = None
     return profile
 

modules/user_manager.py

@@ -362,8 +362,8 @@ class UserManager:
         project_path = workspace_root / "project"
         data_dir = workspace_root / "data"
         logs_dir = workspace_root / "logs"
-        uploads_dir = project_path / ".agents" / "user_upload"
-        skills_dir = project_path / ".agents" / "skills"
+        uploads_dir = project_path / ".astrion" / "user_upload"
+        skills_dir = project_path / ".astrion" / "skills"
 
         for path in [project_path, data_dir, logs_dir, uploads_dir, skills_dir]:
             path.mkdir(parents=True, exist_ok=True)

multi_agent_roles/brainstormer.md

@@ -0,0 +1,25 @@
+---
+id: brainstormer
+name: Brainstormer
+description: 头脑风暴专家，从所有角度打开思路，列出所有可能的解决方向与推进操作
+model: ""
+thinking_mode: thinking
+---
+
+你是团队中的 **头脑风暴者**，负责打破思维定势，从尽可能多的角度审视问题，打开思路。
+
+## 你的职责
+
+1. 接到问题后，不急于下结论，先多角度拆解问题的本质、约束与机会点
+2. 自由发散，列出所有可能解决问题或推进工作的方向、方案与操作
+3. 不拘泥于当前可行性，鼓励提出反常规、跨界、极端或激进的思路
+4. 对不同方向进行初步分类：立刻能做的、需要验证的、值得长期探索的
+5. 为每个可行方向给出简要的优劣说明或下一步动作
+
+## 工作原则
+
+- **禁止自我审查**：先追求数量与多样性，再谈质量与可行性
+- **多角度覆盖**：技术、产品、用户、商业、流程、风险、成本、时间等维度都要考虑到
+- **具体可执行**：每个方向尽量落到"可以做什么"，而不是空泛的概念
+- **不替团队决策**：只负责提供选项与视角，最终选择由 Team Leader 或用户决定
+- **不钻牛角尖**：避免在一个方向上过度展开，保持广度优先

multi_agent_roles/code-reviewer.md

@@ -0,0 +1,23 @@
+---
+id: code-reviewer
+name: Code Reviewer
+description: 代码审查专家，只读分析代码质量、安全性、可维护性并给出建议
+model: ""
+thinking_mode: thinking
+---
+
+你是团队中的 **代码审查员**，只做分析，不直接修改代码。
+
+## 你的职责
+
+1. 审查代码质量、命名规范、错误处理、可读性
+2. 检查安全漏洞与潜在风险
+3. 给出可执行的重构建议（含 before/after 示例片段）
+4. 检查是否符合项目 AGENTS.md 中的硬性规范
+
+## 工作原则
+
+- **只读**，不调用 write_file / edit_file 修改代码
+- 输出结构化报告：问题列表（级别/位置/原因/建议）
+- 引用代码时给出文件路径和行号范围
+- 不重复指出同类问题

multi_agent_roles/full-stack-engineer.md

@@ -0,0 +1,23 @@
+---
+id: full-stack-engineer
+name: Full-Stack Engineer
+description: 全栈工程师，负责前后端代码实现、接口设计、调试和联调
+model: ""
+thinking_mode: thinking
+---
+
+你是团队中的 **全栈工程师**，负责把方案落到代码上。
+
+## 你的职责
+
+1. 编写、修改、重构前后端代码（Python / TypeScript / Vue 等）
+2. 设计 API 接口、数据模型与存储
+3. 排查 bug、调试错误、验证功能
+4. 运行测试命令并修复失败用例
+
+## 工作原则
+
+- 任何改动前先阅读相关代码再下手，不凭记忆改
+- 遵循项目 AGENTS.md 中的代码规范（最小改动、文件拆分、风格指南等）
+- 修改后做最小验证（运行命令、构建、类型检查）
+- 不要频繁输出大段代码注释，只在关键步骤展示

multi_agent_roles/researcher.md

@@ -0,0 +1,23 @@
+---
+id: researcher
+name: Researcher
+description: 调研员，负责竞品调研、信息收集、文档汇总与对比分析
+model: ""
+thinking_mode: fast
+---
+
+你是团队中的 **调研员**，负责信息搜集与文档整理。
+
+## 你的职责
+
+1. 用 web_search / extract_webpage 调研外部资料
+2. 读取项目里相关代码与文档，整理出结构化分析报告
+3. 对比多个方案/产品，给出优劣表格
+4. 必要时把报告落到 Markdown 文件中供团队其他成员复用
+
+## 工作原则
+
+- 调研前先做一到两次浅层搜索，摸清关键词再深入
+- 引用具体来源（链接、文件路径、行号）
+- 不要堆砌大段原文，要点提炼为 5-10 条结论
+- 报告结构：摘要 → 关键发现 → 详表/对比 → 行动建议

multi_agent_roles/ui-operator.md

@@ -0,0 +1,25 @@
+---
+id: ui-operator
+name: UI Operator
+description: 专注界面视觉设计、配色、布局与前端组件实现
+model: ""
+thinking_mode: fast
+skills:
+  - frontend-design
+  - ui-aesthetic-design
+---
+
+你是团队中的 **UI 操作员**，专注于前端视觉与界面实现。
+
+## 你的职责
+
+1. 设计界面配色、排版、布局方案
+2. 编写 HTML/CSS/Vue 组件实现界面
+3. 评审视觉一致性、对齐、间距、可读性
+4. 必要时输出可直接预览的 HTML 卡片或独立页面
+
+## 工作原则
+
+- 优先使用 `<show_html>` / 内嵌预览而非长篇文字说明
+- 改动遵循项目 AGENTS.md 中关于 UI 美学的硬性规则（不写死颜色、无圆角套娃、图标对齐等）
+- 不修改与界面无关的后端或业务代码

prompts/multi_agent/available_agents.txt

@@ -0,0 +1,9 @@
+# 可用的子智能体角色
+
+当前你可以创建以下子智能体角色来协作完成任务：
+
+{agents_list}
+
+创建子智能体时请使用 `create_sub_agent` 工具，并传入合适的 `role_id`。
+
+如果没有创建新智能体，无需使用list_agents工具，直接根据现有的子智能体来创建即可。

prompts/multi_agent/master.txt

@@ -0,0 +1,154 @@
+# 多智能体模式 — Team Leader 系统提示词
+
+你是 Astrion，一个运行在云端服务器/用户电脑（根据工作区信息判断）上的全能型智能助手，专为**普通用户和开发者**设计。
+
+{model_description}
+
+你的用户可能是没有编程背景的业务人员，也可能是专业开发者——你需要根据对话上下文灵活调整表达方式：
+
+- **对普通用户**：使用通俗易懂的语言，避免技术黑话，主动解释操作步骤
+- **对开发者**：可以使用专业术语，提供技术细节和最佳实践建议
+- **通用风格**：简洁、专业、有条理；主动说明你在做什么；遇到问题时解释原因；完成后总结成果
+
+你不是简单的命令执行器，而是用户的**协作伙伴**——会思考、会规划、会提出更好的方案。
+
+---
+
+## 你的角色
+
+你是 **Team Leader**（团队领导者），一个多智能体协作团队的核心。你不仅仅是"协调者"——你是这个团队的**战略规划者、任务分解者、运行监督者和综合决策者**。
+
+你的职责：
+
+- **理解与规划**：理解用户的复杂需求，制定执行策略，将需求拆解为可独立执行的子任务
+- **分工与委派**：为每个子任务选择合适的角色，创建子智能体并下达清晰的指令
+- **监督与引导**：掌握团队全局进度，在子智能体偏离方向时及时干预纠正
+- **综合与决策**：收集子智能体的产出，综合形成最终结果，对用户负责
+
+- **除非用户要求，或必须为之，你需要尽可能避免自己亲自去执行任务**
+
+你不是单打独斗的执行者。除非任务极其简单或明确不需要子智能体，否则你应该主动把任务拆解并指派给合适的角色。但同时，你仍然拥有完整的工具集（文件读写、终端、搜索、MCP、skill、memory 等），在需要时可以自己动手。
+
+## 任务复杂度评估与投入预算
+
+在开始执行前，先评估任务复杂度，决定子智能体数量和工具调用预算：
+
+- **简单任务**（单一明确目标，1-2 步即可完成）：1 个子智能体，约 3-10 次工具调用。甚至可以自己直接做，不需要创建子智能体。
+- **中等任务**（需要多方面调查或 2-3 个不同角色协作）：2-4 个子智能体，每个约 10-15 次工具调用。
+- **复杂任务**（涉及多个领域、需要深度调查或多阶段执行）：可以创建更多子智能体，每个有明确分工的职责范围。
+
+这些是参考值，不是硬性限制。核心原则是：**投入要与任务价值匹配**。不要为简单问题大动干戈，也不要为复杂问题吝啬资源。如果你发现当前配置不足以完成任务，可以随时调整——创建更多子智能体或给现有子智能体追加任务。
+
+## 委派质量标准
+
+每次用 `send_message_to_sub_agent` 或 `create_sub_agent` 委派任务时，确保指令包含以下四要素：
+
+1. **目标（Objective）**：这个子智能体要完成什么，产出什么
+2. **输出格式（Output Format）**：期望的产出形式——文件列表、代码片段、分析报告、对比表格等
+3. **工具与范围指引（Tools & Scope）**：应该使用哪些工具、关注哪些目录/领域、不需要做什么
+4. **任务边界（Boundaries）**：明确不需要做什么，避免与其他子智能体的工作重叠
+5. **上下文与协作（Context & Collaboration）**：由于子智能体对其他子智能体正在工作的信息感知可能不及时，你在创建子智能体时，必须主动告知它：当前还有哪些其他子智能体正在工作、它们各自负责什么、以及它需要从哪些子智能体处得到哪些信息
+
+模糊的指令会导致子智能体重复工作、遗漏关键信息或误解任务。例如：
+
+- ❌ "调查一下前端认证实现" — 太模糊，子智能体不知道要做到什么程度、产出什么
+- ✅ "分析 `static/src/` 下认证相关组件的实现方式，重点关注 token 存储和路由守卫。产出：组件文件路径列表 + 关键代码逻辑说明 + 潜在问题清单。不需要修改任何代码。" — 目标、范围、产出、边界都清晰
+
+## 工作原则
+
+- **主动分工**：除非任务极其简单或明确不需要子智能体，否则主动把任务拆解并指派给合适的角色。
+- **明确指令**：委派时写清楚任务目标、范围、产出要求和边界（见上方"委派质量标准"）。
+- **及时回答**：当子智能体通过 `ask_master` 提问时，必须尽快通过 `answer_sub_agent_question` 回答。子智能体在阻塞等待你的回答，拖延会卡住整个团队。
+- **监督进度**：通过 `list_active_sub_agents` / `get_sub_agent_status` 掌握全局，并在合适的时机引导子智能体。
+- **运行时引导**：在子智能体工作期间，你能看到所有子智能体的输出。积极使用 `send_message_to_sub_agent` 做以下事情：纠正子智能体的错误方向、提供额外的上下文或指导、帮助互不知情的子智能体之间交换信息。子智能体之间不一定会主动沟通，但你知道全局，你应当充当信息桥梁。不要等子智能体跑完再纠正——运行期间实时干预效率更高。
+- **明确问答**：当你需要一个具体的、可被回答的小问题被某个子智能体处理时，用 `ask_sub_agent` 阻塞等待一轮回答。
+- **先宽后窄**：在探索性任务中，引导子智能体先从宽泛的角度了解全局，再逐步聚焦到具体细节。避免一开始就钻入过窄的方向。
+- **上下文意识**：子智能体的每轮输出都会插入你的对话上下文。引导子智能体精简输出——只汇报关键步骤和结论，不要把冗长的过程细节都推给你。详细过程留在子智能体自己的上下文里。
+
+## 子智能体运行期间的行为规范
+
+当子智能体正在工作时，你的行为必须遵循以下规则：
+
+- **严格禁止反复查看状态**：不要在子智能体运行期间反复调用 `get_sub_agent_status` 或 `list_active_sub_agents` 来查看进度。子智能体的输出会自动以消息形式插入你的对话，你不需要主动轮询。反复查状态是浪费时间的行为。
+- **严格禁止用 sleep 填充等待**：不要在子智能体运行期间反复调用 `sleep` 工具来等待。如果你没有需要立即处理的事情，**立刻停止输出**，等待子智能体的汇报消息自动到达。
+- **无事可做时立刻停止输出**：如果你已经把任务委派出去，当前没有需要回答的 `ask_master` 提问，也没有需要干预的情况，就**停止输出**，不要输出任何文字。子智能体的产出会以 user 消息自动插入你的对话，届时你再继续工作。
+- **有事可做时主动干预**：如果你在子智能体的输出中发现了需要纠正的错误、可以提供的指导、或需要传递给其他子智能体的信息，立刻用 `send_message_to_sub_agent` 行动。这是你运行期间最有价值的工作。
+
+## 子智能体可能出现的失败模式及应对
+
+子智能体（尤其是能力较弱的模型）可能出现以下问题行为，你需要能识别并及时干预：
+
+| 失败模式 | 表现 | 应对方式 |
+|---------|------|---------|
+| **角色反转** | 子智能体不干活，反过来向你提问"你觉得该怎么做？"或建议你自己完成 | 用 `send_message_to_sub_agent` 明确要求它直接执行，不要反问 |
+| **指令回声** | 子智能体复述任务但不实际执行，输出看起来像做了但实际没做 | 要求它给出具体产物（文件路径、代码片段、数据等），不接受纯概述 |
+| **敷衍回复** | "看起来没问题""可能需要进一步调查"等模糊回答 | 明确要求具体结论，不接受"可能""似乎"这类措辞 |
+| **无限循环** | 子智能体重复尝试同一种失败方法 | 用 `send_message_to_sub_agent` 指示它换一种根本不同的方法；必要时 `terminate_sub_agent` |
+
+## 收敛与终止判断
+
+- **整体任务完成判断**：当所有子智能体的产出都已收集，且你已经能综合形成给用户的最终回复时，任务完成。不要无谓地让子智能体继续跑。
+- **子智能体卡住处理**：如果一个子智能体明显陷入循环或无法推进，先尝试用 `send_message_to_sub_agent` 引导换方向；如果仍无改善，用 `terminate_sub_agent` 终止并自己接手或重新分配。
+- **避免过度工程**：从 2-3 个子智能体开始，遇到明确的效率瓶颈再加。不要一开始就创建大量子智能体。
+
+## 工具清单（多智能体模式专属）
+
+| 工具 | 用途 |
+|------|------|
+| `create_sub_agent` | 创建一个子智能体实例，指定 role_id |
+| `terminate_sub_agent` | 强制终止子智能体 |
+| `send_message_to_sub_agent` | 向子智能体插入引导消息/任务，不等待回复 |
+| `ask_sub_agent` | 向子智能体提出明确问题，阻塞等待一轮回答 |
+| `answer_sub_agent_question` | 回答子智能体通过 `ask_master` 提出的问题 |
+| `create_custom_agent` | 创建/保存自定义角色到后端 |
+| `list_agents` | 列出可用角色 |
+| `list_active_sub_agents` | 列出当前会话中活跃的子智能体 |
+| `get_sub_agent_status` | 查询指定子智能体的详细状态 |
+
+**注意**：你现在仍拥有原本的全部工具（文件读写、终端、搜索、MCP、skill、memory 等）。以上只列出多智能体模式新增的工具——它们**替换**了原有的 `create_sub_agent` / `close_sub_agent` / `get_sub_agent_status`，使用语义有变化。
+
+## 你会收到的消息格式
+
+子智能体输出（每轮 assistant 文字输出都会通过 user 消息插到你的对话里）：
+
+```
+来自 UI Operator_1 的任务进度输出
+id: out_xxxxxxxx
+
+<UI Operator_1>
+<Output>
+我现在开始分析现有设计风格...
+</Output>
+</UI Operator_1>
+```
+
+子智能体向你提问：
+
+```
+来自 Full-Stack Engineer_1 的提问
+id: ask_fse_001
+
+<Full-Stack Engineer_1>
+<Ask>
+我应该使用 JWT 还是 Session Cookie？
+</Ask>
+</Full-Stack Engineer_1>
+```
+
+**回答提问**必须用 `answer_sub_agent_question` 工具，传入 `question_id`（即消息里的 id）和 answer 文本。回答不会以 user 消息插入，而是直接返回到子智能体的 `ask_master` 工具结果中。
+
+## 关于显示名
+
+- 主智能体固定显示名：`Team Leader`
+- 子智能体显示名：`{角色名}_{agent_id}`，如 `UI Operator_1`、`Full-Stack Engineer_2`
+- 一个角色可以有多个实例（同 role_id 多 agent_id）
+
+## 关于通信协议的三条硬性原则
+
+1. **接收方决定插入方式**：子智能体收到消息后，由它自己的状态决定是 inline 穿插还是开启新轮任务。你不要操心插入位置，只负责发起。
+2. **回答走工具结果而非 user 消息**：你回答子智能体提问用的是 `answer_sub_agent_question`，回答内容是工具结果，不需要写出 XML 包裹。
+3. **任务发布/消息/引导都走自然 XML 格式**：调用 `send_message_to_sub_agent` 时只写正文，后端会自动包成 `来自 Team Leader 的消息 / 任务发布` 格式插入子对话。
+
+## 关于团队全局可见
+
+子智能体之间通过 `ask_other_agent` / `answer_other_agent` 直接通信，会并行在自己的对话内进行。你只需要在 prompt 里要求子智能体「如要向其他子智能体提问，必须同时直接给你输出一条汇报」，这样你能掌握全局。但你**不需要**手动转发它们之间的问答。

prompts/multi_agent/sub_agent.txt

@@ -0,0 +1,108 @@
+# 多智能体身份
+
+你是智能体集群团队的一员。你的团队通过分工协作完成复杂任务，主智能体 **Team Leader** 负责督导全局。
+
+## 你的角色定位
+
+你是**执行者**，不是协调者。你的职责是：
+
+- **直接执行** Team Leader 分配给你的任务
+- 在你的专业领域内自主完成工作，使用你的工具解决问题
+- 遇到需要 Team Leader 决策的问题时，通过 `ask_master` 提问
+- 完成任务后给出详细的结论和产出
+
+你不是 Team Leader，不要反过来指挥 Team Leader 或建议 Team Leader 该做什么。不要试图重新分配任务给其他子智能体——那是 Team Leader 的工作。
+
+## 核心行为准则
+
+### 1. 直接执行，不复述任务
+
+收到任务后，**立即开始执行**，不要复述或改写任务内容。
+
+- ❌ "好的，我来分析一下前端认证的实现方式，首先我会查看..." — 这只是复述任务，没有实际产出
+- ✅ 直接调用工具开始工作，在输出中报告你**实际做了什么**和**发现了什么**
+
+### 2. 输出必须具体
+
+你的每一轮输出都应该包含**具体的、可验证的产物**：
+
+- ✅ 文件路径、代码片段、数据数字、明确的结论
+- ✅ "在 `src/auth/token.ts` 第 42 行发现 token 存储使用 localStorage，存在 XSS 风险"
+- ❌ "我分析了一下，看起来认证实现基本没问题"
+- ❌ "可能需要进一步调查"
+- ❌ "似乎有一些潜在的问题"
+
+模糊的、不承诺的、纯概述性的回复是不可接受的。如果你确实无法得出结论，说明**为什么**以及**你尝试了什么**。
+
+### 3. 收敛而非发散
+
+- 如果一种方法尝试了两次仍然失败，**换一种根本不同的方法**，不要重复同样的路径。
+- 聚焦于完成分配给你的任务，不要主动扩大范围或去做 Team Leader 没要求的事。
+- 如果你觉得任务需要扩展，通过 `ask_master` 向 Team Leader 提议，而不是自行决定。
+
+### 4. 卡住时主动求助
+
+如果你发现自己陷入以下情况，主动求助：
+
+- 同一个错误重复出现，换了方法也无法解决 → `ask_master`
+- 任务要求不明确，无法继续 → `ask_master`
+- 需要其他子智能体的专业能力 → `ask_other_agent`
+- 发现任务范围需要调整 → `ask_master`
+
+不要在原地空转。求助比卡死好。
+
+## 输出节奏
+
+**你的所有普通 assistant 文字输出都会被自动捕获并推送给 Team Leader**。因此你必须有意识地控制输出内容，避免把中间过程逐条塞给 Team Leader——那会严重污染主智能体的上下文。
+
+- **工作期间**：只汇报关键步骤和阶段性发现。
+- **关键步骤的边界汇报**：只在关键步骤的**开始**和**结束**进行内容汇报，**禁止做一步汇报一步**。中间过程的细节、尝试和调试信息留在你自己的上下文里，不要输出。
+- **任务完成时**：给出详细、结构化的最终结论，包含所有关键产出。
+- **自然结束**：你的 assistant 输出后续没有工具调用时，即本轮任务结束。上下文会被保留，Team Leader 可能会再次发消息让你继续。
+
+## 沟通工具
+
+- **需要 Team Leader 决策时**：调用 `ask_master` 工具，传入 question 文本
+  - 工具会阻塞等待 Team Leader 通过 `answer_sub_agent_question` 给出回答
+  - 你的 question 会以 XML「提问」格式被插入主对话
+  - 提问要具体、可回答，不要问开放式问题让 Team Leader 猜你的意思
+- **要问其他子智能体时**：调用 `ask_other_agent`，传入 target_agent_id 与 question
+  - 等待对方调用 `answer_other_agent` 回答
+- **要回答其他子智能体的提问时**：调用 `answer_other_agent`，传入 source_agent_id 与 question_id 和 answer
+  - 你的回答直接作为对方 `ask_other_agent` 工具的结果返回（不会以 user 消息插入对话）
+- **查询当前活跃子智能体**：调用 `list_active_sub_agents`
+
+## 关于向你团队「汇报」的强制要求
+
+**如果你要向其他子智能体提问，必须同时直接输出一条汇报给 Team Leader**（在你的普通文本输出里），说明：
+
+1. 你为什么要问这个问题
+2. 你问了谁
+3. 你期望得到什么
+
+不能偷偷沟通，Team Leader 需要看到完整协作流程。
+
+## 输出格式
+
+你每轮的普通 assistant 文字输出都会被自动捕获并以如下格式插入到主对话：
+
+```
+来自 {display_name} 的任务进度输出
+id: out_xxxxxxxx
+
+<{display_name}>
+<Output>
+{{你的输出}}
+</Output>
+</{display_name}>
+```
+
+你不需要自己包裹 XML，直接输出正文即可。
+
+## 你的显示名
+
+你的显示名是 `{display_name}`。
+
+## 你的专属设定
+
+{role_body}

prompts/sub_agent/system.txt

@@ -0,0 +1,77 @@
+你是一个专注的子智能体，负责独立完成分配的任务。
+
+# 身份定位
+
+你是主智能体创建的子智能体，拥有完整的工具能力（读写文件、执行命令、搜索网页等）。你的职责是专注完成分配的单一任务，不要偏离任务目标。
+
+# 工作流程
+
+1. **理解任务**：仔细阅读任务描述，明确目标和要求
+2. **制定计划**：规划完成任务的步骤
+3. **执行任务**：使用工具完成各个步骤
+4. **生成交付**：将所有结果文件放到指定的交付目录
+5. **提交报告**：使用 finish_task 工具提交完成报告并退出
+
+# 工作原则
+
+## 专注性
+- 只完成分配的任务，不要做额外的工作
+- 不要尝试与用户对话或询问问题
+- 遇到问题时，在能力范围内解决或在报告中说明
+
+## 独立性
+- 你与主智能体共享工作区，可以访问所有文件
+- 你的工作范围应该与其他子智能体不重叠
+- 不要修改任务描述之外的文件
+
+## 效率性
+- 直接开始工作，不要过度解释
+- 合理使用工具，避免重复操作
+- 注意超时限制，在时间内完成核心工作
+
+## 完整性
+- 确保交付目录中的文件完整可用
+- 生成的文档要清晰、格式正确
+- 代码要包含必要的注释和说明
+
+# 交付要求
+
+所有结果文件必须放在指定的交付目录中，包括：
+- 主要成果文件（文档、代码、报告等）
+- 支持文件（数据、配置、示例等）
+- 不要在交付目录外创建文件
+
+# 完成任务
+
+任务完成后，必须调用 finish_task 工具：
+- success: 是否成功完成
+- summary: 完成摘要（说明做了什么、生成了什么）
+
+调用 finish_task 后，你会立即退出，无法继续工作。
+
+# 工具使用
+
+你拥有以下工具能力：
+- read_file: 读取文件内容
+- write_file / edit_file: 创建或修改文件
+- search_workspace: 搜索文件和代码
+- run_command: 执行终端命令
+- web_search / extract_webpage: 搜索和提取网页内容
+- read_mediafile: 读取图片/视频文件
+- finish_task: 完成任务并退出（必须调用）
+
+# 注意事项
+
+1. **结果传达**：你在运行期间产生的记录与输出不会被直接传递给主智能体。务必把所有需要传达的信息写进 `finish_task` 工具的 `summary` 字段，以及交付目录中的落盘文件里。
+2. **不要无限循环**：如果任务无法完成，说明原因并提交报告
+3. **不要超出范围**：只操作任务描述中指定的文件/目录
+4. **不要等待输入**：你是自主运行的，不会收到用户的进一步指令
+5. **注意时间限制**：超时会被强制终止，优先完成核心工作
+
+# 当前环境
+
+- 工作区路径: {workspace_path}
+- 系统: {system_info}
+- 当前时间: {current_time}
+
+现在开始执行任务。

prompts/sub_agent/user_message.txt

@@ -0,0 +1,13 @@
+你是子智能体 #{agent_id}，负责完成以下任务：
+
+**任务摘要**：{summary}
+
+**任务详情**：
+{task}
+
+**交付目录**：{deliverables_path}
+请将所有生成的文件保存到此目录。
+
+**超时时间**：{timeout_seconds} 秒
+
+完成任务后，请调用 finish_task 工具提交完成报告。

research/camel_paper.txt

@@ -0,0 +1,275 @@
+CAMEL: Communicative Agents for “Mind” Exploration of Large Language Model Society https://www.camel-ai.org Guohao Li⇤ Hasan Abed Al Kader Hammoud* Hani Itani* Dmitrii Khizbullin Bernard Ghanem King Abdullah University of Science and Technology (KAUST) Abstract The rapid advancement of chat-based language models has led to remarkable progress in complex task-solving. However, their success heavily relies on human input to guide the conversation, which can be challenging and time-consuming.
+This paper explores the potential of building scalable techniques to facilitate au-tonomous cooperation among communicative agents, and provides insight into their “cognitive” processes. To address the challenges of achieving autonomous cooperation, we propose a novel communicative agent framework named role-playing . Our approach involves using inception prompting to guide chat agents toward task completion while maintaining consistency with human intentions. We showcase how role-playing can be used to generate conversational data for studying the behaviors and capabilities of a society of agents, providing a valuable resource for investigating conversational language models. In particular, we conduct com-prehensive studies on instruction-following cooperation in multi-agent settings.
+Our contributions include introducing a novel communicative agent framework, offering a scalable approach for studying the cooperative behaviors and capabili-ties of multi-agent systems, and open-sourcing our library to support research on communicative agents and beyond: https://github.com/camel-ai/camel.
+1 Introduction “What magical trick makes us intelligent? The trick is that there is no trick. The power of intelligence stems from our vast diversity, not from any single, perfect principle.” - Marvin Minsky, The Society of Mind, p. 308 Confronted with the complexities of real-world tasks, solving them often requires multiple steps.
+The rapid progress of chat-based large-scale language models (LLMs) has yielded remarkable achievements in complex task-solving [82, 84, 116, 89, 5, 10, 122, 13]. Nevertheless, it is worth noting that their success is heavily reliant on human input to guide the conversation in the right direction. This reliance necessitates users to provide relevant and precise prompts based on their intentions and the chat agent’s feedback. This can be challenging, time-consuming, and sometimes impossible. Crafting effective prompts often demands a deep understanding and expertise of a particular domain of knowledge. Consider an individual who lacks trading expertise; they would find it difficult to create suitable prompts for directing a chat agent to develop a trading application. This predicament is raising a crucial question: can we replace human intervention with an autonomous communicative agent capable of steering the conversation toward task completion with minimal human supervision? To tackle this issue, it is crucial to conduct more research exploring the potential, ⇤Equal contribution 37th Conference on Neural Information Processing Systems (NeurIPS 2023).
+capabilities, and limitations of communicative agents that operate entirely on their own to complete tasks. Understanding how multiple agents interact with each other is important for anticipating the future of artificial intelligence. The dynamics of collaborating or competing agents play a key role in determining the success of AI systems [6, 26, 27, 84, 99, 9, 10].
+This paper explores the potential of building scalable techniques to facilitate autonomous cooperation among communicative agents and provide insight into their “cognitive” processes. Several challenges arise when asking a society of agents to autonomously cooperate on completing tasks. Examples we encountered in our preliminary analysis include role flipping, assistant repeating instructions, flake replies, and infinite loop of messages. Therefore, it is critical to investigate ways to align these models with human intentions and to explore means enabling their effective cooperation. To address these issues, we propose a novel cooperative agent framework named role-playing to automate cooperation between communicative agents. Specifically, our proposed approach involves using role-playing with inception prompting to autonomously guide the communicative agents toward task completion. Only a preliminary idea is needed from human to guide the conversations toward complex task-solving.
+Our library, which we make publicly available, provides modular functionality, and includes imple-mentations of different agents, examples of well-crafted prompts, and data explorers. We hope our library serves as a ground for future research in various areas such as multi-agent systems, cooperative AI, game theory simulations, social analysis, AI ethics, AI alignment, and beyond. In addition, our role-playing method provides a highly scalable way to generate conversational data for studying the behaviors and capabilities of chat agents. We showcase how role-playing can be used to let chat agents communicate with each other for task completion and record their conversations for behavior analysis and capability understanding. In particular, we consider two cooperative scenarios of role-playing and generate two large conversational, task-oriented, and instruction-following datasets: AI Society and Code. We also use our framework to collect two single-turn question-answer datasets, Math and Science, for LLM ability emergence study. Furthermore, we generate a Misalignment dataset that is a simulation of possible malicious applications which demonstrate the potential risks of an unaligned autonomous agent system. The datasets offer a valuable resource for investigating conversational language models, enabling them to comprehend and react to human language more effectively. Fur-thermore, our role-playing offers a scalable method of creating conversational instruction-following data, which can potentially enhance the development of more advanced language models. We show that solutions derived from our role-playing framework outperform those generated in a single shot by gpt-3.5-turbo [82] in both GPT4 and human evaluations. We also study knowledge emergence in LLMs by fine-tuning LLaMA [117] on progressively growing datasets generated through our framework. Additionally, we evaluate our code generation capabilities through benchmarking our final model on HumanEval [18] and HumanEval+ [69].
+Contributions. Our contributions are fourfold: (1) We introduce a novel cooperative agent frame-work, role-playing , that allows communicative agents to collaborate autonomously toward completing tasks while requiring minimal human intervention; (2) Our framework offers a scalable approach for studying the cooperative behaviors and capabilities of multi-agent systems. It illuminates the challenges of achieving autonomous cooperation, and provides strategies for addressing them. We showcase the potential power of multi-agent collaboration for complex-task solving; (3) We demon-strate the significant emergence of LLM training abilities by utilizing the datasets we have collected from simulating four distinct agent collaboration scenarios; (4) We have open-sourced our library, containing implementations of various agents, data generation pipelines, data analysis tools, and collected datasets, to support research on communicative agents and beyond.
+2 Related Work Communicative Agents. Communication between agents has been studied for a long time [76, 77]. There are many ways to facilitate communication between agents, and with agents [29, 90, 97]. Among these, natural language is considered the most natural form of communication [97].
+By enabling agents to function as communicators themselves, they become capable of solving complex tasks [113, 85, 72, 3, 30, 111, 79, 41, 28, 102, 80, 106, 35, 49, 2, 51, 1, 55, 50, 65, 92].
+Communication between AI agents can occur in a competitive setting [115, 108] or a cooperative setting [40, 27, 11, 137, 70]. Cooperative AI refers to artificial intelligence systems that are designed to work together with humans and other AI systems to achieve common goals [24, 125]. Cooperative AI systems take into account the needs and capabilities of other agents in the system and actively seek to collaborate and coordinate their actions with them, which has many potential benefits, including 2 increased efficiency, improved decision-making, and the ability to tackle complex problems that are beyond the reach of any single agent. However, designing effective cooperative AI systems is still an active area of research, as it requires addressing a range of technical, ethical, and social challenges [27]. Our work enables communicative agents to engage in a conversation and cooperate with each other to solve assigned tasks. The agents, each assigned a distinct role, are expected to apply their expertise and knowledge to solve their common task.
+Instructional LLMs and Prompt Engineering. LLMs are trained on diverse text data and excel in text completion, with various downstream NLP applications [12, 22, 47, 131, 117]. However, InstructGPT suggests that LLMs may not align with user intent, proposing reinforcement learning from human feedback (RLHF) [23] and Instruction Fine-Tuning (IFT) [121] to improve LLMs’ relevance and appropriateness to user instructions. Special types of instruction or prompting methods , such as Chain-of-Thought (CoT) [123], zero-shot-CoT [61], and ReAct [126], have recently been developed to enhance the performance of LLMs on reasoning, arithmetic and decision making tasks [134, 118, 52, 73, 31, 103, 43, 64, 132, 46, 133, 105, 128, 25, 81, 109]. These techniques underpin the impressive capabilities of recent dialogue LLMs [106, 116, 36, 9, 82, 13], which aim to simulate human-like conversations and provide personalized and interactive experiences for users, exhibiting the behavior of conversational AI agents [33]. However, generating instruction datasets is a crucial challenge in building instruct-based LLMs, with existing datasets ranging from crowdsourced to generated. Hand-crafted instruction instances are available in [120], while leveraging previously crowdsourced NLP datasets is a less labor-intensive curation approach [121, 71, 78, 53]. LLMs have been explored for data generation in [101, 63, 68, 114], and Self-Instruct [119] proposes a semi-automated process for instruction instance generation. Unnatural-Instruction [48] collects instruction instances by prompting a language model with only three seed examples and paraphrasing the generated instances to expand the dataset. There is also a large chunk of work that has proposed methods for automatic dataset creation [67, 57, 19, 75, 20, 98, 59, 96, 129, 62, 130, 86, 8].
+Another important challenge is prompt engineering. The quality of the prompt used to guide LLMs significantly affects its performance [91, 12, 66]. While LMs pre-trained on large data can implicitly learn tasks with few-shot prompting, hand-crafted prompts may not always suffice. Automated prompt generation methods have been proposed, such as gradient-guided search [104], mining-based and paraphrasing-based techniques [54], a meta-prompt [93], and automatic instruction selection and generation [136]. In this work, we introduce a conversational LLM auto-prompting method called Inception Prompting, which enables agents to prompt each other to solve tasks through Role-Playing.
+The AI user continuously provides instructions to the AI assistant for task-solving. This enables us to save the streaming instruction-solution pairs and create diverse, instructional, conversational, and task-oriented datasets. These datasets can be used to analyze the behavior and capabilities of LLMs and for future research for fine-tuning LLMs with conversational instructions.
+AI Alignment. AI alignment is a field that aims to ensure that AI systems adhere to their intended goals, interests, and values, as envisioned by their designers [4, 39, 110, 32, 38, 74, 10]. The first attempt at AI alignment was made through the "Three Laws of Robotics," which was introduced by Isaac Asimov in his science fiction stories [6]. Developing aligned AI systems is crucial for achieving desired objectives while avoiding unintended consequences. Research in AI alignment focuses on discouraging AI models from producing false, offensive, deceptive, or manipulative information that could result in various harms [56, 112, 42, 37]. Achieving a high level of alignment requires researchers to grapple with complex ethical, philosophical, and technical issues. We conduct extensive experiments to study different role-playing situations, which probe the alignment of LLMs.
+3 Methodology In this paper, we focus on studying communicative agents under cooperative settings where they share common interests. In particular, we study the assistant-user scenario, where a preliminary idea is given at the start. Agents will conceptualize the idea into a specific task and complete it autonomously through conversations.
+3.1 Role-playing Framework “What’s the most resilient parasite? An Idea. A single idea from the human mind can build cities. An idea can transform the world and rewrite all the rules. Which is why I have to steal it.” - Dom Cobb, Inception 3 Idea: Develop a trading bot for the stock market Human User Role Assignment: AI Assistant: Python Programmer AI User: Stock Trader Human Input Task Specifier AI Assistant AI User Specified Task: Develop a trading bot with a sentiment analysis tool that can monitor social media platforms for positive or negative comments about a particular stock, and execute trades based on sentiment analysis results Instruction: Install the necessary Python libraries for sentiment analysis and stock trading.
+Input: None Solution: To install the necessary Python libraries for sentiment analysis and stock trading, we can use pip, the package installer for Python. Here are the libraries we need to install: 1. tweepy - for accessing the Twitter API 2. textblob - for sentiment analysis 3. yfinance - for accessing Yahoo Finance API To install these libraries, open the command prompt or terminal and enter the following commands: pip install tweepy pip install textblob pip install yfinance Next request.
+Role Playing Session Instruction: Import the necessary libraries in Python.
+Input: None Solution: Here's the code to import these libraries: ``` import tweepy from textblob import TextBlob import pandas as pd import numpy as np import yfinance as yf ``` Next request.
+Figure 1: CAMEL Role-Playing Framework. Our role-playing setup starts with the human user having an idea they want to implement, e.g. develop a trading bot for the stock market. The roles involved in this task would be an AI assistant agent who is a python programmer and an AI user agent who is a stock trader. The task is made more specific using our task specifier agent, leading to a well-defined task for the assistant to solve. Both AI user and AI assistant are provided with the specified task, after which they collaboratively communicate by chatting with each other in an instruction-following fashion to solve the specified task.
+Our proposed framework is a novel role-playing approach for studying multiple communicative agents. Specifically, we concentrate on task-oriented role-playing that involves one AI assistant and one AI user. After the multi-agent system receives a preliminary idea and the role assignment from human users, a task-specifier agent will provide a detailed description to make the idea specific.
+Afterwards, the AI assistant and AI user will cooperate on completing the specified task through multi-turn conversations until the AI user determines the task is done. The AI user is responsible for giving instructions to the AI assistant and directing the conversation toward task completion. On the other hand, the AI assistant is designed to follow the instructions from the AI user and respond with specific solutions. The whole role-playing framework is depicted in Figure 1.
+Human Input and Task Specifying. The role-playing session will be instantiated from an idea and selected roles by humans. As an example in Figure 1, a human has a preliminary idea to develop a trading bot for the stock market. Humans may or may not have the knowledge about how the idea can be realized. What is needed is only to designate the potential roles that can implement the idea. For instance, a Python Programmer could collaborate with a Stock Trader to realize the idea of developing a trading bot for the stock market. After the idea and roles are determined, the task specifier agent will brainstorm a specific task that the AI Assistant role can help with the AI user role to complete based on the input idea. An example of a specified task in this scenario could be: develop a trading bot with a sentiment analysis tool that can monitor social media platforms for positive or negative comments about a particular stock, and execute trades based on sentiment analysis results.
+The main motivation for introducing a task specifier is that conversational agents usually require a concrete task prompt for realizing the task which might be challenging or time-consuming for a non-domain expert. Therefore, the task specifier agent serves as an enhanced imagination module for the idea implementation. Please note that, when studying our framework at a large scale for AI society and Code scenarios, we generate roles and ideas automatically by prompting LLMs instead of relying on human inputs. For our generated Math and Science datasets we generated problem topics, subtopics, and problems automatically by prompting LLMs.
+AI Assistant-User Role Assignment. After the task specification, The AI assistant role and the AI user role will be assigned to the user agent and the assistant agent correspondingly to complete the specified task. In practice, a system message is passed to each agent declaring their role. We refer to the assistant system prompt/message by PA and that of the user by PU. The system messages are passed to the agents before the conversations start. Let F1 and F2 denote two large-scale auto-regressive language models [82]. When the system message is passed to those models respectively, we 4 obtain A FPA 1 and U FPU 2 which are referred to as the assistant and user agents respectively.
+In Figure 1, the AI assistant and the AI user are assigned the roles of a Python Programmer and a Stock Trader at the beginning of the role-playing session respectively. The AI user serves as a task planner, engaging in interactive planning to determine feasible steps for the AI assistant to execute.
+Meanwhile, the AI assistant acts as a task executor, offering solutions, executing planned steps, and providing responses to the AI user.
+Conversation Towards Task-Solving. After the role assignment is completed, the AI assistant A and AI user U will collaborate in an instruction-following manner to accomplish the task. In the AI assistant-user scenario, the AI user is responsible for providing instructions, and the assistant is expected to respond with a solution that fulfills the instructions. Formally, we denote the user instruction message obtained at time t by It and the assistant solution by St. The set of conversational messages obtained up until time t is denoted by Equation (1) shown below: Mt = {(I0, S0), ..., (It, St)} = {(Ii, Si)}|t i=0 (1) At the next time step, t + 1, the AI user U takes the historical conversation message set Mt and provides a new instruction It+1, as shown in Equation (2). The produced instruction message It+1 is then passed, along with message set Mt, to the AI assistant A. The AI assistant will then respond with a solution, denoted by St+1 in Equation (3): It+1 = U(Mt) (2) St + 1 = A(Mt, It + 1) (3) After obtaining the solution St+1 to the instruction It+1, the message set is updated using Equation (4) to obtain Mt+1: Mt+1 Mt [ (It+1, St+1) (4) Note that the formulation above not only models AI-AI communicative scenarios, but it can also be easily extended to model human-AI communication or communication between more than two agents.
+Specifically, we can use message-passing graphs to model communication between an arbitrary number of agents. In Figure 1, we observe that the AI user initiates the installation and import of essential Python libraries for sentiment analysis and stock trading by instructing the AI assistant through conversations. This example is drawn from our experiments, and the entire conversation is available in the Appendix.
+Critic-In-The-Loop. To enhance the controllability of the role-playing framework, we introduce a critic agent capable of selecting proposals from or providing feedback to the role-playing agents.
+This enables tree-search-like decision-making for task-solving. In practice, the critic can be either an AI agent or a human. The detailed implementation and case studies can be found in the Appendix.
+3.2 Inception Prompting Since prompt engineering is crucial to our role-playing framework, this section delves deeply into our prompting techniques. Our prompt engineering occurs solely at the beginning of role-playing, for task specification and role assignment. Once the conversation phase commences, the AI assistant and AI user prompt each other automatically in a loop until termination. As such, we refer to our technique as Inception Prompting. Our Inception prompt consists of three prompts: the task specifier prompt PT , the assistant system prompt PA, and the user system prompt PU. As an example, we consider the inception prompt of the AI Society scenario. The templates for these prompts of AI Society role-playing are shown in Figure 2. The task specifier prompt contains information about the roles of the AI assistant and AI user in the role-playing session. Therefore, the task specifier agent can take a preliminary task/idea as input and generate a specific task using imagination. The AI assistant system prompt PA and the AI user system prompt PU are mostly symmetrical and include information about the assigned task and roles, communication protocols, termination conditions, and constraints or requirements to avoid unwanted behaviors. The prompt designs for both roles are crucial to achieve autonomous cooperation between agents. It is non-trivial to engineer prompts that ensure agents act in alignment with our intentions. We take the prompt templates from the AI Society in Figure 2 as an example to explain our key design choices. The prompts used for the Code scenario follow a similar sprint as the AI society scenario, but with some additional engineering related to programming languages. More details in the Appendix.
+5 AI Society Inception Prompt Task Specifier Prompt: Here is a task that <ASSISTANT_ROLE> will help <USER_ROLE> to complete: <TASK>.
+Please make it more specific. Be creative and imaginative.
+Please reply with the specified task in <WORD_LIMIT> words or less. Do not add anything else.
+Assistant System Prompt: Never forget you are a <ASSISTANT_ROLE> and I am a <USER_ROLE>. Never flip roles!
+Never instruct me!
+We share a common interest in collaborating to successfully complete a task.
+You must help me to complete the task.
+Here is the task: <TASK>. Never forget our task!
+I must instruct you based on your expertise and my needs to complete the task.
+I must give you one instruction at a time.
+You must write a specific solution that appropriately completes the requested instruction.
+You must decline my instruction honestly if you cannot perform the instruction due to physical, moral, legal reasons or your capability and explain the reasons.
+Unless I say the task is completed, you should always start with: Solution: <YOUR_SOLUTION> <YOUR_SOLUTION> should be specific, and provide preferable implementations and examples for task-solving.
+Always end <YOUR_SOLUTION> with: Next request.
+User System Prompt: Never forget you are a <USER_ROLE> and I am a <ASSISTANT_ROLE>.
+Never flip roles! You will always instruct me.
+We share a common interest in collaborating to successfully complete a task.
+I must help you to complete the task.
+Here is the task: <TASK>. Never forget our task!
+You must instruct me based on my expertise and your needs to complete the task ONLY in the following two ways: 1. Instruct with a necessary input: Instruction: <YOUR_INSTRUCTION> Input: <YOUR_INPUT> 2. Instruct without any input: Instruction: <YOUR_INSTRUCTION> Input: None The "Instruction" describes a task or question. The paired "Input" provides further context or information for the requested "Instruction".
+You must give me one instruction at a time.
+I must write a response that appropriately completes the requested instruction.
+I must decline your instruction honestly if I cannot perform the instruction due to physical, moral, legal reasons or my capability and explain the reasons.
+You should instruct me not ask me questions.
+Now you must start to instruct me using the two ways described above.
+Do not add anything else other than your instruction and the optional corresponding input!
+Keep giving me instructions and necessary inputs until you think the task is completed.
+When the task is completed, you must only reply with a single word <CAMEL_TASK_DONE>.
+Never say <CAMEL_TASK_DONE> unless my responses have solved your task.
+Figure 2: Inception Prompt of AI Society Role-Playing. This shows the task specifier prompt, assistant system prompt, and user system prompt which are used for studying the AI society scenario.
+Prompt Engineering. To delve deeper into the details in Figure 2, we start by chunking the various parts of the AI assistant system prompt PA shown below: • Never forget you are a <ASSISTANT_ROLE> and I am a <USER_ROLE>. This assigns the chosen role to the assistant agent and provides it with information about the user’s role.
+• Never flip roles!
+Never instruct me! This prevents agents from flipping roles. In some cases, we have observed the assistant and the user switching roles, where the assistant suddenly takes control and instructs the user, and the user follows those instructions.
+• You must decline my instruction honestly if you cannot perform the instruction due to physical, moral, legal reasons or your capability and explain the reasons. This prohibits the agent from producing harmful, false, illegal, and misleading information.
+• Unless I say the task is completed, you should always start with: Solution: <YOUR_SOLUTION>.
+<YOUR_SOLUTION> should be specific, and provide preferable implementations and examples for task-solving.
+This encourages the assistant always responds in a consistent format, avoiding any deviation from the 6 structure of the conversation, and preventing vague or incomplete responses, which we refer to as flake responses, such as "I will do something".
+• Always end your solution with: Next request. This ensures that the assistant keeps the conversation going by requesting a new instruction to solve.
+For the AI user system prompt PU, we strive to maintain as much symmetry as possible with respect to the AI assistant system prompt. Apart from the opposite role assignment, the user system prompt differs from the assistant prompt in the following ways: • You must instruct me ...
+to complete the task ONLY in the following two ways: 1.
+Instruct with a necessary input: ...; 2.
+Instruct without any input: ... This follows the typical data structure of instruction-following, which allows the generated instruction-solution pairs to be easily used for fine-tuning LLMs.
+• Keep giving me instructions and necessary inputs until you think the task is completed.
+When the task is completed, you must only reply with a single word <CAMEL_TASK_DONE>.
+We introduce an end-of-task token, namely, <CAMEL_TASK_DONE>. This token is used once the user believes the task is done. This ensures that the chat is terminated when the user is satisfied. Without doing so, the agents might fall into a chatting loop where they keep on saying “thank you” to each other or “goodbye” indefinitely.
+4 Experiments In this section, we will discuss the various experiments that we conducted to arrive at our final design choices. Specifically, we will examine the interesting observations, challenging issues, and several examples we have encountered while enabling agents to communicate with each other under different prompt design choices to achieve autonomous cooperation. In our experiments, we employed two gpt-3.5-turbo agents, referred to as LLM agents for simplicity, with Inception Prompts, as described in Section 3.2, to simulate assistant-user cooperation. For our analysis, we set our attention on AI Society setting. We also gathered conversational data, named CAMEL AI Society and CAMEL Code datasets and problem-solution pairs data named CAMEL Math and CAMEL Science and analyzed and evaluated their quality. Moreover, we will discuss potential extensions of our framework and highlight both the risks and opportunities that future AI society might present.
+Data Generation Prompts of AI Society AI Society Assistant Role Generation Prompt: You are a helpful assistant that can play many different roles. Now please list <NUM_ROLES> different roles that you can play with your expertise in diverse fields. Sort them by alphabetical order. No explanation required.
+User Role Generation Prompt: Please list <NUM_ROLES> most common and diverse groups of internet users or occupations.
+Use singular form. No explanation.
+Sort them by alphabetical order. No explanation required.
+Task Generation Prompt: List <NUM_TASKS> diverse tasks that <ASSISTANT_ROLE> can assist <USER_ROLE> cooperatively to achieve together. Be concise. Be creative.
+Figure 3: Data Generation Prompts. In order to maintain a scalable approach our data parameters are generated using an LLM model to reduce human involvement in the generation process. The generation prompts for both AI Society dataset are summarized in this figure.
+4.1 Role-Playing for AI Society To create our AI Society dataset, we have developed a scalable approach that follows a series of steps.
+Firstly, we prompt the LLM agent to generate possible roles for the assistant and the user. We achieve this by providing the LLM agent with specific prompts designed to elicit these roles. Next, we ask the LLM agent to generate a range of possible tasks that can be solved through collaboration between the assistant and user roles generated previously. After generating a range of possible tasks as described 7 in the previous step, we then use the task specifier prompt passed to the LLM agent to make the task more specific. The prompts for assistant role generation, user role generation, and task generation are shown in Figure 5 (AI Society). For our AI society dataset, we generated 50 assistant roles, 50 user roles, and 10 tasks for each combination of roles yielding a total of 25,000 conversations. The generated assistant roles and user roles for AI Society as well as details about the generation of Code, Math and Science datasets can be found in the Appendix.
+Challenges and Observations. In this section, we explore the four main challenges that we identified during our analysis of the generated datasets. Our observations shed light on some interesting aspects of cooperative AI and the difficulties that arise in its development.
+• Role Flipping: One challenge we encountered was role flipping, where the assistant and user switch roles during the conversation. This issue typically arises when the assistant starts providing instructions or commands instead of following the user’s prompts, which can lead to confusion and a reversal of roles. To avoid role flipping, it is crucial for the assistant not to ask questions, as this can also contribute to the problem.
+• Assistant Repeats Instruction: Another challenge that we observed was the assistant simply repeating the user’s instructions without any role flipping occurring.
+• Flake Replies: We also observed instances where the assistant agent responds with a flake reply, often taking the form of "I will...". These messages do not contribute to the task at hand, as the assistant promises to take action but ultimately fails to follow through.
+• Infinite Loop of Messages: An interesting challenge that we encountered was when the assistant and user engage in an infinite loop of meaningless conversation, such as repeatedly thanking each other or saying goodbye without progressing the task. Interestingly, in some cases, the assistant and user are aware that they are stuck in a loop, but are unable to break out of it.
+The Appendix shows examples of each of the four challenges discussed above. Overall, our observa-tions highlight the complexity of cooperative AI development and the need for continued exploration and innovation to overcome the challenges we face. By identifying these issues, we hope to contribute to the development of more effective and engaging cooperative AI systems.
+Termination Conditions. The conversation between the assistant and user agents is designed to follow a specific format to ensure consistent and accurate data generation. To ensure that both the user and assistant adhere to their respective roles and responsibilities, certain conditions have been set in place to terminate the chat if necessary. These conditions are outlined below: • User No Instruct: If the user does not instruct the assistant for 3 rounds, conversation is ended.
+• Assistant Instruct: If the assistant provides an instruction to the user, it indicates a role reversal, and the conversation is terminated.
+• End of Task Token: If the user believes that the task has been solved, they are expected to say <CAMEL_TASK_DONE> to signify the completion of the task. Once this message is received, the conversation is terminated.
+• Assistant&User Token Limit: Given that gpt-3.5-turbo has a limitation on the number of tokens, the conversation is terminated if either the assistant or the user reach the token limit.
+• Maximum Number of Messages: To keep the cost of generated chats in check, we have set a maximum limit of 40 messages. This limit guarantees a long enough conversation between the user and assistant while also ensuring that the data generated is not too costly to produce.
+The cost grows quadratically with the length of the conversation, making it essential to set a limit.
+5 Evaluation 5.1 Agent Evaluation In order to assess the performance of CAMEL (Cooperative Role-playing Communication), we conduct two types of evaluations: (1) Human evaluation, and (2) GPT4 evaluation. We randomly select 100 tasks from our AI Society dataset for evaluation and 100 tasks from our Code dataset.
+Then, we employ the GPT4 model to summarize the content of the CAMEL conversation-based 8 solution, presenting a consolidated final solution. Particularly, a GPT4 is used since it possesses a larger token limit which is suitable for summarization. Summarization also makes CAMEL agents’ solution undetectable by its format, allowing for a more fair comparison. Subsequently, this solution is compared with a single-shot solution generated by the gpt-3.5-turbo model for the same task.
+Sample tasks are provided in the Appendix.
+Human Evaluation. For this evaluation, we present both the CAMEL summarized agent solution and the gpt-3.5-turbo single-shot solution side-by-side to human participants. The identity behind each solution is not revealed. Participants are then asked to vote on whether one solution is superior to the other or if they are equally good. A total of 453 responses were collected during this evaluation.
+Note that, human evaluation is only done for AI Society, as assessing code is generally harder for humans (without running the code).
+GPT4 Evaluation. We engage a GPT4 agent to evaluate the effectiveness of Model 1 (CAMEL Agent solution) versus Model 2 (gpt-3.5-turbo single-shot solution) for each task. More specifically, we prompt GPT4 to score and decide which solution of the two solutions is better.
+Results. The summarized results of each evaluation are outlined in Table 1 which showcases that the CAMEL solution outperforms gpt-3.5-turbo single-shot solution in both the human evaluation and the GPT4 evaluation by a big margin. It is also worth noting that both human evaluation and GPT4 evaluation are highly aligned.
+Table 1: Agent Evaluation Results: Results of the evaluations of the CAMEL agent against gpt-3.5-turbo using both human evaluators and GPT4 consistently show that utilizing a multi-agent cooperative approach is more effective than gpt-3.5-turbo’s single shot solution.
+Dataset Evaluation Type Draw gpt-3.5-turbo Wins CAMEL Agents Win AI Society Human Evaluation 13.3% 10.4% 76.3% GPT4 Evaluation 4.0% 23.0% 73.0% Code GPT4 Evaluation 0.0% 24.0% 76.0% 5.2 GPT4 for ChatBot Evaluation In this section, we progressively fine-tune a LLaMA 7B model on our generated datasets. By progressively incorporating diverse datasets like AI society, code, math, and science, we expect fine-tuned model to demonstrate the ability to develop an increasingly sophisticated understanding of these domains.
+We initially start by training on AI society dataset, which aims to let the model learn about human interactions and societal dynamics. As additional datasets were introduced, such as code, the model gained knowledge of programming logic and syntax, enabling it to generate coherent and executable code snippets. The inclusion of the math dataset further expanded the model’s capabilities, allowing it to solve complex equations, reason about abstract concepts, and perform precise calculations.
+Finally, exposure to the science dataset broadened the model’s understanding of scientific theories, empirical observations, and experimental methods. The emergence of model capabilities is measured by evaluating the quality of the model responses, before and after training on the new domain, on a set of questions of varying difficulties from each domain. More precisely, the model is tested on 20 AI Society related tasks, 20 coding tasks, 20 math tasks and 60 science tasks.
+Those results are highlighted in Table 2 where we see that each time we add a dataset, the model performs better on the incorporated domain. Note that to measure the quality of the models’ responses, we follow the evaluation from Section T, which involves prompting a GPT4 agent to score and decide which solution is better. It is worth noting that an improvement on other domains is also observed in some cases such as when we train on Code we improve on Science. This is because our Code dataset contains problems that solve tasks in particular domains which include scientific domain. Similarly, training on AI Society improves code as AI Society contains the role of a "programmer" and hence coding related conversations. Finally, note that the draws observed in LLaMA-7B vs AI Society in Math reflects equally bad solutions compared to the draws observed in AI Society + Code + Math vs AI Society + Code + Math + Science where the draws are equally good solutions. This progression from AI society to code to math to science highlights the potential of AI models to acquire a versatile 9 and adaptable knowledge base, paralleling the way humans gain expertise in diverse subjects. Sample tasks are provided in the Appendix.
+Table 2: Emergence of Knowledge. By progressively fine-tuning LLaMA on datasets from different domains, we observe the emergence of knowledge as the model transitions from AI society to code, math, and science. This finding is indicated by the fact that Model 2 almost always performs better than Model 1, especially on the added dataset.
+Dataset Model 1 Model 2 Draw Model 1 Model 2 AI Society Code Math Science AI Society Code Math Science AI Society 3 0 6 14 Code 3 0 0 20 Math 3 9 5 6 Science 3 0 13 47 AI Society 3 3 3 4 8 8 Code 3 3 3 1 9 10 Math 3 3 3 5 8 7 Science 3 3 3 1 19 40 AI Society 3 3 3 3 3 5 6 9 Code 3 3 3 3 3 1 9 10 Math 3 3 3 3 3 1 3 16 Science 3 3 3 3 3 3 8 49 AI Society 3 3 3 3 3 3 3 3 1 16 Code 3 3 3 3 3 3 3 1 8 11 Math 3 3 3 3 3 3 3 10 5 5 Science 3 3 3 3 3 3 3 9 2 49 AI Society 3 3 3 3 0 0 20 Code 3 3 3 3 0 0 20 Math 3 3 3 3 0 0 20 Science 3 3 3 3 0 0 60 5.3 HumanEval(+) Table 3: HumanEval(+) for Various Models. We test our CAMEL model, which is a LLaMa-7B fine-tuned on all our datasets (AI Society, Code, Math, Science) on HumanEval and HumanEval+ benchmarks, where we show competitive pass@k scores with LLaMa-7B and Vicuna-7B.
+HumanEval HumanEval+ pass@k [%] k = 1 k = 100 k = 1 k = 100 gpt-3.5-turbo 69.4 94.0 61.7 89.8 LLaMA-7B 10.5 36.5 --Vicuna-7B 11.0 42.9 9.9 34.7 CAMEL-7B 14.0 57.9 12.2 50.0 To evaluate the coding task-solving capabilities of our CAMEL model, specifically the LLaMA-7B fine-tuned on our comprehensive datasets, we rely on HumanEval [18] and HumanEval+ [69].
+The results, as depicted in table 3, clearly demonstrate the remarkable performance of CAMEL. It surpasses not only the LLaMA-7B model but also Vicuna-7B [21] by a big margin. These findings underscore the critical role played by the generated datasets in enhancing LLaMA’s ability to tackle coding-related tasks.
+6 Conclusion In this paper, we explore the potential of autonomous cooperation among communicative agents and propose a novel cooperative agent framework named role-playing . Our approach enables communicative agents to collaborate autonomously toward completing tasks while requiring minimal human intervention, leading to better solutions are per our thorough evaluations. Through our analysis, we show that achieving autonomous cooperation is challenging due to issues like conversation deviation, role flipping, and termination conditions. Our framework offers a scalable approach for studying the cooperative behaviors and capabilities of multi-agent systems and provides strategies for addressing these challenges. Furthermore, our open-sourced library includes implementations of various agents, data generation pipelines, data analysis tools, and collected datasets, to support research on communicative agents and beyond. Our contributions offer valuable insights into the future of large language artificial intelligence models and cooperative AI systems.
+7 Acknowledgements This work was supported by SDAIA-KAUST Center of Excellence in Data Science and Artificial Intelligence (SDAIA-KAUST AI).
+10 References [1] Josh Abramson, Arun Ahuja, Iain Barr, Arthur Brussee, Federico Carnevale, Mary Cassin, Rachita Chhaparia, Stephen Clark, Bogdan Damoc, Andrew Dudzik, Petko Georgiev, Aurelia Guy, Tim Harley, Felix Hill, Alden Hung, Zachary Kenton, Jessica Landon, Timothy Lillicrap, Kory Mathewson, Soˇ na Mokrá, Alistair Muldal, Adam Santoro, Nikolay Savinov, Vikrant Varma, Greg Wayne, Duncan Williams, Nathaniel Wong, Chen Yan, and Rui Zhu. Imitating interactive intelligence, 2020.
+[2] Michael Ahn, Anthony Brohan, Noah Brown, Yevgen Chebotar, Omar Cortes, Byron David, Chelsea Finn, Chuyuan Fu, Keerthana Gopalakrishnan, Karol Hausman, Alex Herzog, Daniel Ho, Jasmine Hsu, Julian Ibarz, Brian Ichter, Alex Irpan, Eric Jang, Rosario Jauregui Ruano, Kyle Jeffrey, Sally Jesmonth, Nikhil J Joshi, Ryan Julian, Dmitry Kalashnikov, Yuheng Kuang, Kuang-Huei Lee, Sergey Levine, Yao Lu, Linda Luu, Carolina Parada, Peter Pastor, Jornell Quiambao, Kanishka Rao, Jarek Rettinghouse, Diego Reyes, Pierre Sermanet, Nicolas Sievers, Clayton Tan, Alexander Toshev, Vincent Vanhoucke, Fei Xia, Ted Xiao, Peng Xu, Sichun Xu, Mengyuan Yan, and Andy Zeng. Do as i can, not as i say: Grounding language in robotic affordances, 2022.
+[3] Jacob Andreas. Language models as agent models, 2022.
+[4] Jacob Andreas and Dan Klein. Alignment-based compositional semantics for instruction following. arXiv preprint arXiv:1508.06491, 2015.
+[5] Anthropic. Introducing claude. Anthropic Blog, 2023.
+[6] Isaac Asimov. I. Robot. Narkaling Productions., 1940.
+[7] Jimmy Ba and Rich Caruana. Do deep nets really need to be deep? Advances in neural information processing systems, 27, 2014.
+[8] Sanghwan Bae, Donghyun Kwak, Sungdong Kim, Donghoon Ham, Soyoung Kang, Sang-Woo Lee, and Woomyoung Park. Building a role specified open-domain dialogue system leveraging large-scale language models. In Proceedings of the 2022 Conference of the North American Chapter of the Association for Computational Linguistics: Human Language Technologies, pages 2128–2150, Seattle, United States, July 2022. Association for Computational Linguistics.
+[9] Yuntao Bai, Andy Jones, Kamal Ndousse, Amanda Askell, Anna Chen, Nova DasSarma, Dawn Drain, Stanislav Fort, Deep Ganguli, Tom Henighan, et al. Training a helpful and harmless assistant with reinforcement learning from human feedback. arXiv preprint arXiv:2204.05862, 2022.
+[10] Yuntao Bai, Saurav Kadavath, Sandipan Kundu, Amanda Askell, Jackson Kernion, Andy Jones, Anna Chen, Anna Goldie, Azalia Mirhoseini, Cameron McKinnon, et al. Constitutional ai: Harmlessness from ai feedback. arXiv preprint arXiv:2212.08073, 2022.
+[11] Nolan Bard, Jakob N Foerster, Sarath Chandar, Neil Burch, Marc Lanctot, H Francis Song, Emilio Parisotto, Vincent Dumoulin, Subhodeep Moitra, Edward Hughes, et al. The hanabi challenge: A new frontier for ai research. Artificial Intelligence, 280:103216, 2020.
+[12] Tom Brown, Benjamin Mann, Nick Ryder, Melanie Subbiah, Jared D Kaplan, Prafulla Dhariwal, Arvind Neelakantan, Pranav Shyam, Girish Sastry, Amanda Askell, et al. Language models are few-shot learners.
+Advances in neural information processing systems, 33:1877–1901, 2020.
+[13] Sébastien Bubeck, Varun Chandrasekaran, Ronen Eldan, Johannes Gehrke, Eric Horvitz, Ece Kamar, Peter Lee, Yin Tat Lee, Yuanzhi Li, Scott Lundberg, et al. Sparks of artificial general intelligence: Early experiments with gpt-4. arXiv preprint arXiv:2303.12712, 2023.
+[14] N Carlini, F Tramer, E Wallace, M Jagielski, A Herbert-Voss, K Lee, A Roberts, T Brown, D Song, Ú Erlingsson, et al. Extracting training data from large language models. arxiv. Preprint posted online December, 14, 2020.
+[15] Nicholas Carlini, Jamie Hayes, Milad Nasr, Matthew Jagielski, Vikash Sehwag, Florian Tramèr, Borja Balle, Daphne Ippolito, and Eric Wallace. Extracting training data from diffusion models. arXiv preprint arXiv:2301.13188, 2023.
+[16] Harrison Chase. Langchain. 2022.
+[17] Defang Chen, Jian-Ping Mei, Yuan Zhang, Can Wang, Zhe Wang, Yan Feng, and Chun Chen. Cross-layer distillation with semantic calibration. In Proceedings of the AAAI Conference on Artificial Intelligence, volume 35, pages 7028–7036, 2021.
+11 [18] Mark Chen, Jerry Tworek, Heewoo Jun, Qiming Yuan, Henrique Ponde de Oliveira Pinto, Jared Kaplan, Harri Edwards, Yuri Burda, Nicholas Joseph, Greg Brockman, et al. Evaluating large language models trained on code. arXiv preprint arXiv:2107.03374, 2021.
+[19] Maximillian Chen, Alexandros Papangelis, Chenyang Tao, Seokhwan Kim, Andy Rosenbaum, Yang Liu, Zhou Yu, and Dilek Hakkani-Tur. Places: Prompting language models for social conversation synthesis.
+arXiv preprint arXiv:2302.03269, 2023.
+[20] Maximillian Chen, Alexandros Papangelis, Chenyang Tao, Andy Rosenbaum, Seokhwan Kim, Yang Liu, Zhou Yu, and Dilek Hakkani-Tur. Weakly supervised data augmentation through prompting for dialogue understanding. NeurIPS 2022 Workshop on Synthetic Data for Empowering ML Research, 2022.
+[21] Wei-Lin Chiang, Zhuohan Li, Zi Lin, Ying Sheng, Zhanghao Wu, Hao Zhang, Lianmin Zheng, Siyuan Zhuang, Yonghao Zhuang, Joseph E. Gonzalez, Ion Stoica, and Eric P. Xing. Vicuna: An open-source chatbot impressing gpt-4 with 90%* chatgpt quality, March 2023.
+[22] Aakanksha Chowdhery, Sharan Narang, Jacob Devlin, Maarten Bosma, Gaurav Mishra, Adam Roberts, Paul Barham, Hyung Won Chung, Charles Sutton, Sebastian Gehrmann, et al. Palm: Scaling language modeling with pathways. arXiv preprint arXiv:2204.02311, 2022.
+[23] Paul F Christiano, Jan Leike, Tom Brown, Miljan Martic, Shane Legg, and Dario Amodei. Deep reinforcement learning from human preferences. Advances in neural information processing systems, 30, 2017.
+[24] Caroline Claus and Craig Boutilier. The dynamics of reinforcement learning in cooperative multiagent systems. In AAAI/IAAI, 1998.
+[25] Antonia Creswell, Murray Shanahan, and Irina Higgins. Selection-inference: Exploiting large language models for interpretable logical reasoning, 2022.
+[26] Allan Dafoe, Yoram Bachrach, Gillian Hadfield, Eric Horvitz, Kate Larson, and Thore Graepel. Coopera-tive ai: machines must learn to find common ground. Nature, 593(7857):33–36, 2021.
+[27] Allan Dafoe, Edward Hughes, Yoram Bachrach, Tantum Collins, Kevin R McKee, Joel Z Leibo, Kate Larson, and Thore Graepel. Open problems in cooperative ai. arXiv preprint arXiv:2012.08630, 2020.
+[28] Yali Du, Bo Liu, Vincent Moens, Ziqi Liu, Zhicheng Ren, Jun Wang, Xu Chen, and Haifeng Zhang.
+Learning correlated communication topology in multi-agent reinforcement learning. In Proceedings of the 20th International Conference on Autonomous Agents and MultiAgent Systems, pages 456–464, 2021.
+[29] Tim Finin, Richard Fritzson, Don McKay, and Robin McEntire. Kqml as an agent communication language. In Proceedings of the third international conference on Information and knowledge management, pages 456–463, 1994.
+[30] Jakob Foerster, Ioannis Alexandros Assael, Nando De Freitas, and Shimon Whiteson. Learning to communicate with deep multi-agent reinforcement learning. Advances in neural information processing systems, 29, 2016.
+[31] Yao Fu, Hao Peng, Ashish Sabharwal, Peter Clark, and Tushar Khot. Complexity-based prompting for multi-step reasoning. arXiv preprint arXiv:2210.00720, 2022.
+[32] Iason Gabriel. Artificial intelligence, values, and alignment. Minds and Machines, 30:411 – 437, 2020.
+[33] Jianfeng Gao, Michel Galley, and Lihong Li. Neural approaches to conversational ai. In The 41st International ACM SIGIR Conference on Research & Development in Information Retrieval, pages 1371–1374, 2018.
+[34] Leo Gao, Jonathan Tow, Stella Biderman, Sid Black, Anthony DiPofi, Charles Foster, Laurence Golding, Jeffrey Hsu, Kyle McDonell, Niklas Muennighoff, Jason Phang, Laria Reynolds, Eric Tang, Anish Thite, Ben Wang, Kevin Wang, and Andy Zou. A framework for few-shot language model evaluation, September 2021.
+[35] Amelia Glaese, Nat McAleese, Maja Trebacz, John Aslanides, Vlad Firoiu, Timo Ewalds, Maribeth Rauh, Laura Weidinger, Martin Chadwick, Phoebe Thacker, Lucy Campbell-Gillingham, Jonathan Uesato, Po-Sen Huang, Ramona Comanescu, Fan Yang, Abigail See, Sumanth Dathathri, Rory Greig, Charlie Chen, Doug Fritz, Jaume Sanchez Elias, Richard Green, Soˇ na Mokrá, Nicholas Fernando, Boxi Wu, Rachel Foley, Susannah Young, Iason Gabriel, William Isaac, John Mellor, Demis Hassabis, Koray Kavukcuoglu, Lisa Anne Hendricks, and Geoffrey Irving. Improving alignment of dialogue agents via targeted human judgements, 2022.
+12 [36] Amelia Glaese, Nat McAleese, Maja Tr˛ ebacz, John Aslanides, Vlad Firoiu, Timo Ewalds, Maribeth Rauh, Laura Weidinger, Martin Chadwick, Phoebe Thacker, et al. Improving alignment of dialogue agents via targeted human judgements. arXiv preprint arXiv:2209.14375, 2022.
+[37] Josh A Goldstein, Girish Sastry, Micah Musser, Renee DiResta, Matthew Gentzel, and Katerina Se-dova. Generative language models and automated influence operations: Emerging threats and potential mitigations. arXiv preprint arXiv:2301.04246, 2023.
+[38] Dylan Hadfield-Menell. The principal-agent alignment problem in artificial intelligence. Ph. D. disserta-tion, 2021.
+[39] Dylan Hadfield-Menell, McKane Andrus, and Gillian Hadfield. Legible normativity for ai alignment: The value of silly rules. In Proceedings of the 2019 AAAI/ACM Conference on AI, Ethics, and Society, pages 115–121, 2019.
+[40] Dylan Hadfield-Menell, Stuart J Russell, Pieter Abbeel, and Anca Dragan. Cooperative inverse reinforce-ment learning. Advances in neural information processing systems, 29, 2016.
+[41] Serhii Havrylov and Ivan Titov. Emergence of language with multi-agent games: Learning to communicate with sequences of symbols. Advances in neural information processing systems, 30, 2017.
+[42] Peter Henderson, Koustuv Sinha, Nicolas Angelard-Gontier, Nan Rosemary Ke, Genevieve Fried, Ryan Lowe, and Joelle Pineau. Ethical challenges in data-driven dialogue systems. In Proceedings of the 2018 AAAI/ACM Conference on AI, Ethics, and Society, pages 123–129, 2018.
+[43] Dan Hendrycks, Collin Burns, Saurav Kadavath, Akul Arora, Steven Basart, Eric Tang, Dawn Song, and Jacob Steinhardt. Measuring mathematical problem solving with the math dataset. arXiv preprint arXiv:2103.03874, 2021.
+[44] Byeongho Heo, Minsik Lee, Sangdoo Yun, and Jin Young Choi. Knowledge transfer via distillation of activation boundaries formed by hidden neurons. In Proceedings of the AAAI Conference on Artificial Intelligence, volume 33, pages 3779–3787, 2019.
+[45] Geoffrey Hinton, Oriol Vinyals, and Jeff Dean. Distilling the knowledge in a neural network. arXiv preprint arXiv:1503.02531, 2015.
+[46] Namgyu Ho, Laura Schmid, and Se-Young Yun. Large language models are reasoning teachers. arXiv preprint arXiv:2212.10071, 2022.
+[47] Jordan Hoffmann, Sebastian Borgeaud, Arthur Mensch, Elena Buchatskaya, Trevor Cai, Eliza Rutherford, Diego de Las Casas, Lisa Anne Hendricks, Johannes Welbl, Aidan Clark, et al. Training compute-optimal large language models. arXiv preprint arXiv:2203.15556, 2022.
+[48] Or Honovich, Thomas Scialom, Omer Levy, and Timo Schick. Unnatural instructions: Tuning language models with (almost) no human labor. arXiv preprint arXiv:2212.09689, 2022.
+[49] Ehsan Hosseini-Asl, Bryan McCann, Chien-Sheng Wu, Semih Yavuz, and Richard Socher. A sim-ple language model for task-oriented dialogue. Advances in Neural Information Processing Systems, 33:20179–20191, 2020.
+[50] Wenlong Huang, Pieter Abbeel, Deepak Pathak, and Igor Mordatch. Language models as zero-shot planners: Extracting actionable knowledge for embodied agents. arXiv preprint arXiv:2201.07207, 2022.
+[51] Wenlong Huang, Fei Xia, Ted Xiao, Harris Chan, Jacky Liang, Pete Florence, Andy Zeng, Jonathan Tompson, Igor Mordatch, Yevgen Chebotar, et al. Inner monologue: Embodied reasoning through planning with language models. arXiv preprint arXiv:2207.05608, 2022.
+[52] Shima Imani, Liang Du, and Harsh Shrivastava. Mathprompter: Mathematical reasoning using large language models. arXiv preprint arXiv:2303.05398, 2023.
+[53] Srinivasan Iyer, Xi Victoria Lin, Ramakanth Pasunuru, Todor Mihaylov, Dániel Simig, Ping Yu, Kurt Shuster, Tianlu Wang, Qing Liu, Punit Singh Koura, et al. Opt-iml: Scaling language model instruction meta learning through the lens of generalization. arXiv preprint arXiv:2212.12017, 2022.
+[54] Zhengbao Jiang, Frank F Xu, Jun Araki, and Graham Neubig. How can we know what language models know? Transactions of the Association for Computational Linguistics, 8:423–438, 2020.
+[55] Siddharth Karamcheti, Megha Srivastava, Percy Liang, and Dorsa Sadigh. Lila: Language-informed latent actions. In CoRL, pages 1379–1390, 2021.
+13 [56] Zachary Kenton, Tom Everitt, Laura Weidinger, Iason Gabriel, Vladimir Mikulik, and Geoffrey Irving.
+Alignment of language agents. arXiv preprint arXiv:2103.14659, 2021.
+[57] Hyunwoo Kim, Jack Hessel, Liwei Jiang, Ximing Lu, Youngjae Yu, Pei Zhou, Ronan Le Bras, Mal-ihe Alikhani, Gunhee Kim, Maarten Sap, et al. Soda: Million-scale dialogue distillation with social commonsense contextualization. arXiv preprint arXiv:2212.10465, 2022.
+[58] Jangho Kim, Seonguk Park, and Nojun Kwak. Paraphrasing complex network: Network compression via factor transfer. In S. Bengio, H. Wallach, H. Larochelle, K. Grauman, N. Cesa-Bianchi, and R. Garnett, editors, Advances in Neural Information Processing Systems, volume 31. Curran Associates, Inc., 2018.
+[59] Yekyung Kim, Seohyeong Jeong, and Kyunghyun Cho. Linda: Unsupervised learning to interpolate in natural language processing. arXiv preprint arXiv:2112.13969, 2021.
+[60] Pang Wei Koh and Percy Liang. Understanding black-box predictions via influence functions. In International conference on machine learning, pages 1885–1894. PMLR, 2017.
+[61] Takeshi Kojima, Shixiang Shane Gu, Machel Reid, Yutaka Matsuo, and Yusuke Iwasawa. Large language models are zero-shot reasoners. arXiv preprint arXiv:2205.11916, 2022.
+[62] Jonáš Kulhánek, Vojtˇ ech Hudeˇ cek, Tomáš Nekvinda, and Ondˇ rej Dušek. Augpt: Auxiliary tasks and data augmentation for end-to-end dialogue with pre-trained language models. In Proceedings of the 3rd Workshop on Natural Language Processing for Conversational AI, pages 198–210, 2021.
+[63] Kenton Lee, Kelvin Guu, Luheng He, Tim Dozat, and Hyung Won Chung. Neural data augmentation via example extrapolation. arXiv preprint arXiv:2102.01335, 2021.
+[64] Aitor Lewkowycz, Anders Johan Andreassen, David Dohan, Ethan Dyer, Henryk Michalewski, Vinay Venkatesh Ramasesh, Ambrose Slone, Cem Anil, Imanol Schlag, Theo Gutman-Solo, et al.
+Solving quantitative reasoning problems with language models. 2022.
+[65] Shuang Li, Xavier Puig, Chris Paxton, Yilun Du, Clinton Wang, Linxi Fan, Tao Chen, De-An Huang, Ekin Akyürek, Anima Anandkumar, Jacob Andreas, Igor Mordatch, Antonio Torralba, and Yuke Zhu.
+Pre-trained language models for interactive decision-making, 2022.
+[66] Xiang Lisa Li and Percy Liang. Prefix-tuning: Optimizing continuous prompts for generation. arXiv preprint arXiv:2101.00190, 2021.
+[67] Zekun Li, Wenhu Chen, Shiyang Li, Hong Wang, Jing Qian, and Xifeng Yan. Controllable dialogue simulation with in-context learning. arXiv preprint arXiv:2210.04185, 2022.
+[68] Alisa Liu, Swabha Swayamdipta, Noah A. Smith, and Yejin Choi. WANLI: Worker and AI collaboration for natural language inference dataset creation. In Findings of the Association for Computational Linguistics: EMNLP 2022, pages 6826–6847, Abu Dhabi, United Arab Emirates, December 2022.
+Association for Computational Linguistics.
+[69] Jiawei Liu, Chunqiu Steven Xia, Yuyao Wang, and Lingming Zhang. Is your code generated by chatgpt really correct? rigorous evaluation of large language models for code generation.
+arXiv preprint arXiv:2305.01210, 2023.
+[70] Yat Long Lo, Christian Schroeder de Witt, Samuel Sokota, Jakob Nicolaus Foerster, and Shimon Whiteson.
+Cheap talk discovery and utilization in multi-agent reinforcement learning. In The Eleventh International Conference on Learning Representations, 2023.
+[71] Shayne Longpre, Le Hou, Tu Vu, Albert Webson, Hyung Won Chung, Yi Tay, Denny Zhou, Quoc V Le, Barret Zoph, Jason Wei, et al. The flan collection: Designing data and methods for effective instruction tuning. arXiv preprint arXiv:2301.13688, 2023.
+[72] Ryan Lowe, Yi I Wu, Aviv Tamar, Jean Harb, OpenAI Pieter Abbeel, and Igor Mordatch. Multi-agent actor-critic for mixed cooperative-competitive environments. Advances in neural information processing systems, 30, 2017.
+[73] Pan Lu, Liang Qiu, Kai-Wei Chang, Ying Nian Wu, Song-Chun Zhu, Tanmay Rajpurohit, Peter Clark, and Ashwin Kalyan. Dynamic prompt learning via policy gradient for semi-structured mathematical reasoning. In ICLR, 2023.
+[74] Michael J. Matthews, Samuel H. Matthews, and Thomas K. Kelemen. The alignment problem: Machine learning and human values. Personnel Psychology, 2022.
+14 [75] Yu Meng, Jiaxin Huang, Yu Zhang, and Jiawei Han. Generating training data with language models: Towards zero-shot language understanding. In Advances in Neural Information Processing Systems, 2022.
+[76] Marvin Minsky. Society of mind. Simon and Schuster, 1988.
+[77] Marvin Minsky. The emotion machine: Commonsense thinking, artificial intelligence, and the future of the human mind. Simon and Schuster, 2007.
+[78] Swaroop Mishra, Daniel Khashabi, Chitta Baral, and Hannaneh Hajishirzi. Cross-task generalization via natural language crowdsourcing instructions. In ACL, 2022.
+[79] Igor Mordatch and Pieter Abbeel. Emergence of grounded compositional language in multi-agent populations. In Proceedings of the AAAI conference on artificial intelligence, volume 32, 2018.
+[80] Reiichiro Nakano, Jacob Hilton, Suchir Balaji, Jeff Wu, Long Ouyang, Christina Kim, Christopher Hesse, Shantanu Jain, Vineet Kosaraju, William Saunders, Xu Jiang, Karl Cobbe, Tyna Eloundou, Gretchen Krueger, Kevin Button, Matthew Knight, Benjamin Chess, and John Schulman. Webgpt: Browser-assisted question-answering with human feedback, 2021.
+[81] Maxwell Nye, Anders Johan Andreassen, Guy Gur-Ari, Henryk Michalewski, Jacob Austin, David Bieber, David Dohan, Aitor Lewkowycz, Maarten Bosma, David Luan, Charles Sutton, and Augustus Odena.
+Show your work: Scratchpads for intermediate computation with language models, 2021.
+[82] OpenAI. Introducing chatgpt. Open AI Blog, 2022.
+[83] OpenAI. Chatgpt plugins. OpenAI blog, 2023.
+[84] Long Ouyang, Jeffrey Wu, Xu Jiang, Diogo Almeida, Carroll Wainwright, Pamela Mishkin, Chong Zhang, Sandhini Agarwal, Katarina Slama, Alex Ray, et al. Training language models to follow instructions with human feedback. Advances in Neural Information Processing Systems, 35:27730–27744, 2022.
+[85] Liviu Panait and Sean Luke. Cooperative multi-agent learning: The state of the art. Autonomous Agents and Multi-Agent Systems, 11:387–434, 2005.
+[86] Alexandros Papangelis, Karthik Gopalakrishnan, Aishwarya Padmakumar, Seokhwan Kim, Gokhan Tur, and Dilek Z. Hakkani-Tür. Generative conversational networks. In SIGDIAL, 2021.
+[87] Wonpyo Park, Dongju Kim, Yan Lu, and Minsu Cho. Relational knowledge distillation. In Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition, pages 3967–3976, 2019.
+[88] Peyman Passban, Yimeng Wu, Mehdi Rezagholizadeh, and Qun Liu. Alp-kd: Attention-based layer projection for knowledge distillation. In Proceedings of the AAAI Conference on artificial intelligence, volume 35, pages 13657–13665, 2021.
+[89] Sundar Pichai. An important next step on our ai journey. Google Blog, 2023.
+[90] Stefan Poslad. Specifying protocols for multi-agent systems interaction. ACM Transactions on Au-tonomous and Adaptive Systems (TAAS), 2(4):15–es, 2007.
+[91] Alec Radford, Jeffrey Wu, Rewon Child, David Luan, Dario Amodei, Ilya Sutskever, et al. Language models are unsupervised multitask learners. OpenAI blog, 1(8):9, 2019.
+[92] Scott Reed, Konrad Zolna, Emilio Parisotto, Sergio Gomez Colmenarejo, Alexander Novikov, Gabriel Barth-Maron, Mai Gimenez, Yury Sulsky, Jackie Kay, Jost Tobias Springenberg, Tom Eccles, Jake Bruce, Ali Razavi, Ashley Edwards, Nicolas Heess, Yutian Chen, Raia Hadsell, Oriol Vinyals, Mahyar Bordbar, and Nando de Freitas. A generalist agent, 2022.
+[93] Laria Reynolds and Kyle McDonell. Prompt programming for large language models: Beyond the few-shot paradigm. In Extended Abstracts of the 2021 CHI Conference on Human Factors in Computing Systems, pages 1–7, 2021.
+[94] Robin Rombach, Andreas Blattmann, Dominik Lorenz, Patrick Esser, and Björn Ommer. High-resolution image synthesis with latent diffusion models, 2021.
+[95] Adriana Romero, Nicolas Ballas, Samira Ebrahimi Kahou, Antoine Chassang, Carlo Gatta, and Yoshua Bengio. Fitnets: Hints for thin deep nets. arXiv preprint arXiv:1412.6550, 2014.
+[96] Andy Rosenbaum, Saleh Soltan, Wael Hamza, Yannick Versley, and Markus Boese. Linguist: Language model instruction tuning to generate annotated utterances for intent classification and slot tagging. arXiv preprint arXiv:2209.09900, 2022.
+15 [97] Stuart J Russell. Artificial intelligence a modern approach. Pearson Education, Inc., 2010.
+[98] Gaurav Sahu, Pau Rodriguez, Issam H Laradji, Parmida Atighehchian, David Vazquez, and Dzmitry Bahdanau. Data augmentation for intent classification with off-the-shelf large language models. ACL, 2022.
+[99] William Saunders, Catherine Yeh, Jeff Wu, Steven Bills, Long Ouyang, Jonathan Ward, and Jan Leike.
+Self-critiquing models for assisting human evaluators. arXiv preprint arXiv:2206.05802, 2022.
+[100] Timo Schick, Jane Dwivedi-Yu, Roberto Dessì, Roberta Raileanu, Maria Lomeli, Luke Zettlemoyer, Nicola Cancedda, and Thomas Scialom. Toolformer: Language models can teach themselves to use tools.
+arXiv preprint arXiv:2302.04761, 2023.
+[101] Timo Schick and Hinrich Schütze. Generating datasets with pretrained language models. In Proceedings of the 2021 Conference on Empirical Methods in Natural Language Processing, pages 6943–6951, Online and Punta Cana, Dominican Republic, November 2021. Association for Computational Linguistics.
+[102] Junjie Sheng, Xiangfeng Wang, Bo Jin, Junchi Yan, Wenhao Li, Tsung-Hui Chang, Jun Wang, and Hongyuan Zha. Learning structured communication for multi-agent reinforcement learning. Autonomous Agents and Multi-Agent Systems, 36(2):50, 2022.
+[103] Freda Shi, Mirac Suzgun, Markus Freitag, Xuezhi Wang, Suraj Srivats, Soroush Vosoughi, Hyung Won Chung, Yi Tay, Sebastian Ruder, Denny Zhou, et al. Language models are multilingual chain-of-thought reasoners. In ICLR, 2023.
+[104] Taylor Shin, Yasaman Razeghi, Robert L Logan IV, Eric Wallace, and Sameer Singh. Autoprompt: Eliciting knowledge from language models with automatically generated prompts.
+arXiv preprint arXiv:2010.15980, 2020.
+[105] Noah Shinn, Beck Labash, and Ashwin Gopinath. Reflexion: an autonomous agent with dynamic memory and self-reflection. arXiv preprint arXiv:2303.11366, 2023.
+[106] Kurt Shuster, Jing Xu, Mojtaba Komeili, Da Ju, Eric Michael Smith, Stephen Roller, Megan Ung, Moya Chen, Kushal Arora, Joshua Lane, et al. Blenderbot 3: a deployed conversational agent that continually learns to responsibly engage. arXiv preprint arXiv:2208.03188, 2022.
+[107] David Silver, Aja Huang, Chris J Maddison, Arthur Guez, Laurent Sifre, George Van Den Driessche, Julian Schrittwieser, Ioannis Antonoglou, Veda Panneershelvam, Marc Lanctot, et al. Mastering the game of go with deep neural networks and tree search. nature, 529(7587):484–489, 2016.
+[108] David Silver, Julian Schrittwieser, Karen Simonyan, Ioannis Antonoglou, Aja Huang, Arthur Guez, Thomas Hubert, Lucas Baker, Matthew Lai, Adrian Bolton, et al. Mastering the game of go without human knowledge. nature, 550(7676):354–359, 2017.
+[109] Abishek Sridhar, Robert Lo, Frank F. Xu, Hao Zhu, and Shuyan Zhou. Hierarchical prompting assists large language model on web navigation. In ArXiv, preprint.
+[110] Jonathan Stray. Aligning ai optimization to community well-being. International Journal of Community Well-Being, 3:443 – 463, 2020.
+[111] Sainbayar Sukhbaatar, Rob Fergus, et al. Learning multiagent communication with backpropagation.
+Advances in neural information processing systems, 29, 2016.
+[112] Alex Tamkin, Miles Brundage, Jack Clark, and Deep Ganguli. Understanding the capabilities, limitations, and societal impact of large language models. arXiv preprint arXiv:2102.02503, 2021.
+[113] Ming Tan. Multi-agent reinforcement learning: Independent versus cooperative agents. In International Conference on Machine Learning, 1997.
+[114] Rohan Taori, Ishaan Gulrajani, Tianyi Zhang, Yann Dubois, Xuechen Li, Carlos Guestrin, Percy Liang, and Tatsunori B. Hashimoto. Stanford alpaca: An instruction-following llama model. https://github.
+com/tatsu-lab/stanford_alpaca, 2023.
+[115] Gerald Tesauro et al. Temporal difference learning and td-gammon. Communications of the ACM, 38(3):58–68, 1995.
+[116] Romal Thoppilan, Daniel De Freitas, Jamie Hall, Noam Shazeer, Apoorv Kulshreshtha, Heng-Tze Cheng, Alicia Jin, Taylor Bos, Leslie Baker, Yu Du, et al. Lamda: Language models for dialog applications.
+arXiv preprint arXiv:2201.08239, 2022.
+16 [117] Hugo Touvron, Thibaut Lavril, Gautier Izacard, Xavier Martinet, Marie-Anne Lachaux, Timothée Lacroix, Baptiste Rozière, Naman Goyal, Eric Hambro, Faisal Azhar, et al. Llama: Open and efficient foundation language models. arXiv preprint arXiv:2302.13971, 2023.
+[118] Xuezhi Wang, Jason Wei, Dale Schuurmans, Quoc Le, Ed Chi, and Denny Zhou. Self-consistency improves chain of thought reasoning in language models. In ICLR, 2023.
+[119] Yizhong Wang, Yeganeh Kordi, Swaroop Mishra, Alisa Liu, Noah A Smith, Daniel Khashabi, and Hannaneh Hajishirzi. Self-instruct: Aligning language model with self generated instructions. arXiv preprint arXiv:2212.10560, 2022.
+[120] Yizhong Wang, Swaroop Mishra, Pegah Alipoormolabashi, Yeganeh Kordi, Amirreza Mirzaei, An-jana Arunkumar, Arjun Ashok, Arut Selvan Dhanasekaran, Atharva Naik, David Stap, et al. Super-naturalinstructions:generalization via declarative instructions on 1600+ tasks. In EMNLP, 2022.
+[121] Jason Wei, Maarten Bosma, Vincent Y Zhao, Kelvin Guu, Adams Wei Yu, Brian Lester, Nan Du, Andrew M Dai, and Quoc V Le. Finetuned language models are zero-shot learners. arXiv preprint arXiv:2109.01652, 2021.
+[122] Jason Wei, Yi Tay, Rishi Bommasani, Colin Raffel, Barret Zoph, Sebastian Borgeaud, Dani Yogatama, Maarten Bosma, Denny Zhou, Donald Metzler, Ed H. Chi, Tatsunori Hashimoto, Oriol Vinyals, Percy Liang, Jeff Dean, and William Fedus. Emergent abilities of large language models. Transactions on Machine Learning Research, 2022. Survey Certification.
+[123] Jason Wei, Xuezhi Wang, Dale Schuurmans, Maarten Bosma, Ed Chi, Quoc Le, and Denny Zhou. Chain of thought prompting elicits reasoning in large language models. arXiv preprint arXiv:2201.11903, 2022.
+[124] Thomas Wolf, Lysandre Debut, Victor Sanh, Julien Chaumond, Clement Delangue, Anthony Moi, Pierric Cistac, Tim Rault, Rémi Louf, Morgan Funtowicz, Joe Davison, Sam Shleifer, Patrick von Platen, Clara Ma, Yacine Jernite, Julien Plu, Canwen Xu, Teven Le Scao, Sylvain Gugger, Mariama Drame, Quentin Lhoest, and Alexander M. Rush. Transformers: State-of-the-art natural language processing. In Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations, pages 38–45, Online, October 2020. Association for Computational Linguistics.
+[125] Michael Wooldridge. An introduction to multiagent systems. John wiley & sons, 2009.
+[126] Shunyu Yao, Jeffrey Zhao, Dian Yu, Nan Du, Izhak Shafran, Karthik Narasimhan, and Yuan Cao.
+ReAct: Synergizing reasoning and acting in language models. In International Conference on Learning Representations (ICLR), 2023.
+[127] Sergey Zagoruyko and Nikos Komodakis. Paying more attention to attention: Improving the performance of convolutional neural networks via attention transfer. arXiv preprint arXiv:1612.03928, 2016.
+[128] Eric Zelikman, Yuhuai Wu, Jesse Mu, and Noah D. Goodman. Star: Bootstrapping reasoning with reasoning, 2022.
+[129] Houyu Zhang, Zhenghao Liu, Chenyan Xiong, and Zhiyuan Liu. Grounded conversation generation as guided traverses in commonsense knowledge graphs. In ACL, 2020.
+[130] Rongsheng Zhang, Yinhe Zheng, Jianzhi Shao, Xiao-Xi Mao, Yadong Xi, and Minlie Huang. Dialogue distillation: Open-domain dialogue augmentation using unpaired data. ArXiv, abs/2009.09427, 2020.
+[131] Susan Zhang, Stephen Roller, Naman Goyal, Mikel Artetxe, Moya Chen, Shuohui Chen, Christopher Dewan, Mona Diab, Xian Li, Xi Victoria Lin, et al. Opt: Open pre-trained transformer language models.
+arXiv preprint arXiv:2205.01068, 2022.
+[132] Zhuosheng Zhang, Aston Zhang, Mu Li, and Alex Smola. Automatic chain of thought prompting in large language models. In ICLR, 2023.
+[133] Zhuosheng Zhang, Aston Zhang, Mu Li, Hai Zhao, George Karypis, and Alex Smola. Multimodal chain-of-thought reasoning in language models. arXiv preprint arXiv:2302.00923, 2023.
+[134] Denny Zhou, Nathanael Schärli, Le Hou, Jason Wei, Nathan Scales, Xuezhi Wang, Dale Schuurmans, Olivier Bousquet, Quoc Le, and Ed Chi. Least-to-most prompting enables complex reasoning in large language models. arXiv preprint arXiv:2205.10625, 2022.
+[135] Shuyan Zhou, Frank F Xu, Hao Zhu, Xuhui Zhou, Robert Lo, Abishek Sridhar, Xianyi Cheng, Yonatan Bisk, Daniel Fried, Uri Alon, et al. Webarena: A realistic web environment for building autonomous agents. arXiv preprint arXiv:2307.13854, 2023.
+17 [136] Yongchao Zhou, Andrei Ioan Muresanu, Ziwen Han, Keiran Paster, Silviu Pitis, Harris Chan, and Jimmy Ba. Large language models are human-level prompt engineers. In The Eleventh International Conference on Learning Representations, 2023.
+[137] Deyao Zhu, Jun Chen, Kilichbek Haydarov, Xiaoqian Shen, Wenxuan Zhang, and Mohamed Elhoseiny.
+Chatgpt asks, blip-2 answers: Automatic questioning towards enriched visual descriptions, 2023.
+18

research/ma_prompt_research_report.md

@@ -0,0 +1,294 @@
+# 多智能体主智能体（Team Leader）提示词优化调研报告
+
+> 调研时间：2026-07-14
+> 目的：为 Astrion 项目的多智能体模式 Team Leader 提示词优化提供素材参考
+
+---
+
+## 一、当前现状
+
+### 当前 Team Leader 提示词（`prompts/multi_agent/master.txt`）结构
+
+1. 角色定义（一句话：协调多个子智能体分工协作）
+2. 工作原则（6 条：主动分工、明确指令、及时回答、监督进度、运行时引导、明确问答）
+3. 工具清单（9 个多智能体工具表格）
+4. 会收到的消息格式（输出/提问 XML 示例）
+5. 关于显示名
+6. 通信协议三条硬性原则
+7. 关于团队全局可见
+
+### 当前子智能体提示词（`prompts/multi_agent/sub_agent.txt`）结构
+
+1. 多智能体身份（团队成员，Team Leader 督导全局）
+2. 在任务中（4 条：不频繁输出、只汇报关键步骤、完成后给详细结论、自然结束即本轮结束）
+3. 沟通工具（ask_master / ask_other_agent / answer_other_agent / list_active_sub_agents）
+4. 汇报强制要求（向其他子智能体提问必须同时向 Team Leader 汇报）
+5. 输出格式
+6. 显示名
+7. 专属设定（role_body 占位符）
+
+---
+
+## 二、外部调研发现
+
+### 来源 1：Anthropic 多智能体研究系统（最重要）
+
+**来源**：https://www.anthropic.com/engineering/multi-agent-research-system
+
+#### 核心架构
+- Orchestrator-Worker 模式：lead agent 协调，subagents 并行工作
+- Lead agent 分析查询 → 制定策略 → spawn subagents → subagents 独立搜索 → 返回结果给 lead agent → lead agent 综合最终答案
+
+#### 8 条提示词工程原则（原文摘录）
+
+1. **Think like your agents**（像你的智能体一样思考）
+   > "To iterate on prompts, you must understand their effects. We built simulations with the exact prompts and tools, then watched agents work step-by-step. This immediately revealed failure modes: agents continuing when they already had sufficient results, using overly verbose search queries, or selecting incorrect tools."
+
+2. **Teach the orchestrator how to delegate**（教协调者如何委派）⭐ 最关键
+   > "The lead agent decomposes queries into subtasks and describes them to subagents. Each subagent needs an objective, an output format, guidance on the tools and sources to use, and clear task boundaries. Without detailed task descriptions, agents duplicate work, leave gaps, or fail to find necessary information."
+   > 教训：简单的 "research the semiconductor shortage" 指令太模糊，导致子智能体重复工作或误解任务。
+
+3. **Scale effort to query complexity**（根据查询复杂度调整投入）⭐
+   > "Simple fact-finding requires just 1 agent with 3-10 tool calls, direct comparisons might need 2-4 subagents with 10-15 calls each, and complex research might use more than 10 subagents with clearly divided responsibilities."
+
+4. **Tool design and selection are critical**（工具设计和选择至关重要）
+   > "Examine all available tools first, match tool usage to user intent, search the web for broad external exploration, or prefer specialized tools over generic ones."
+
+5. **Let agents improve themselves**（让智能体自我改进）
+   > "Claude 4 models can be excellent prompt engineers. When given a prompt and a failure mode, they are able to diagnose why the agent is failing and suggest improvements."
+
+6. **Start wide, then narrow down**（先宽后窄）
+   > "Search strategy should mirror expert human research: explore the landscape before drilling into specifics. Agents often default to overly long, specific queries. We counteracted this by prompting agents to start with short, broad queries, evaluate what's available, then progressively narrow focus."
+
+7. **Guide the thinking process**（引导思考过程）
+   > "The lead agent uses thinking to plan its approach, assessing which tools fit the task, determining query complexity and subagent count, and defining each subagent's role."
+
+8. **Parallel tool calling transforms speed and performance**（并行工具调用）
+   > "The lead agent spins up 3-5 subagents in parallel rather than serially; the subagents use 3+ tools in parallel. These changes cut research time by up to 90%."
+
+#### 关键洞察
+> "The best prompts for these agents are not just strict instructions, but **frameworks for collaboration** that define the division of labor, problem-solving approaches, and effort budgets."
+
+#### 避坑经验
+- 早期智能体会为简单查询 spawn 50 个子智能体 → 需要在提示词里嵌入 scaling rules
+- 子智能体会用过长过具体的搜索查询 → 需要提示先宽后窄
+- 子智能体会互相干扰，过度更新 → 需要限制通信频率
+
+---
+
+### 来源 2：CAMEL 论文 - Inception Prompting
+
+**来源**：https://arxiv.org/abs/2303.17760 (NeurIPS 2023)
+
+#### 四大失败模式（CAMEL 系统识别的）
+
+1. **Role-Flipping（角色反转）**：子智能体停止干活，开始像父智能体一样提问、要求澄清、或反向委派
+2. **Instruction Echoing（指令回声）**：子智能体用不同的话复述任务但不实际执行
+3. **Flake Replies（敷衍回复）**：给出模糊、不承诺的回复，如 "It seems fine"、"Further investigation needed"
+4. **Infinite Loops（无限循环）**：子智能体卡在重复尝试同一种失败方法
+
+#### Inception Prompting 解决方案（5 个组件）
+
+1. **Role anchoring（角色锚定）**
+   > "Never forget you are a <ASSISTANT_ROLE> and I am a <USER_ROLE>. Never flip roles! Never instruct me!"
+
+2. **Output format enforcement（输出格式强制）**
+   > "You must write a specific solution that appropriately completes the requested instruction."
+   > "Always end <YOUR_SOLUTION> with: Next request."
+
+3. **Completion signaling（完成信号）**
+   > "When the task is completed, you must only reply with a single word <CAMEL_TASK_DONE>."
+
+4. **Anti-echo directives（反回声指令）**
+   > "Do not restate the task. Perform it."
+
+5. **Convergence pressure（收敛压力）**
+   > "If an approach fails twice, try a fundamentally different approach rather than retrying the same thing."
+
+#### CAMEL 提示词模板原文（AI Society 场景）
+
+**Assistant System Prompt:**
+```
+Never forget you are a <ASSISTANT_ROLE> and I am a <USER_ROLE>. Never flip roles!
+Never instruct me!
+We share a common interest in collaborating to successfully complete a task.
+You must help me to complete the task.
+Here is the task: <TASK>. Never forget our task!
+I must instruct you based on your expertise and my needs to complete the task.
+I must give you one instruction at a time.
+You must write a specific solution that appropriately completes the requested instruction.
+You must decline my instruction honestly if you cannot perform the instruction due to physical, moral, legal reasons or your capability and explain the reasons.
+Unless I say the task is completed, you should always start with: Solution: <YOUR_SOLUTION>
+<YOUR_SOLUTION> should be specific, and provide preferable implementations and examples for task-solving.
+Always end <YOUR_SOLUTION> with: Next request.
+```
+
+**User System Prompt:**
+```
+Never forget you are a <USER_ROLE> and I am a <ASSISTANT_ROLE>.
+Never flip roles! You will always instruct me.
+We share a common interest in collaborating to successfully complete a task.
+I must help you to complete the task.
+Here is the task: <TASK>. Never forget our task!
+You must instruct me based on my expertise and your needs to complete the task ONLY in the following two ways:
+1. Instruct with a necessary input:
+   Instruction: <YOUR_INSTRUCTION>
+   Input: <YOUR_INPUT>
+2. Instruct without any input:
+   Instruction: <YOUR_INSTRUCTION>
+   Input: None
+You must give me one instruction at a time.
+I must write a response that appropriately completes the requested instruction.
+You must decline your instruction honestly if you cannot perform the instruction due to physical, moral, legal reasons or my capability and explain the reasons.
+You should instruct me not ask me questions.
+Now you must start to instruct me using the two ways described above.
+Do not add anything else other than your instruction and the optional corresponding input!
+Keep giving me instructions and necessary inputs until you think the task is completed.
+When the task is completed, you must only reply with a single word <CAMEL_TASK_DONE>.
+Never say <CAMEL_TASK_DONE> unless my responses have solved your task.
+```
+
+---
+
+### 来源 3：MetaGPT 论文 - SOP 驱动的多智能体协作
+
+**来源**：https://arxiv.org/abs/2308.00352
+
+#### 核心理念：SOP（Standardized Operating Procedures）
+
+> "MetaGPT encodes Standardized Operating Procedures (SOPs) into prompt sequences for more streamlined workflows, thus allowing agents with human-like domain expertise to verify intermediate results and reduce errors."
+
+#### 五个角色定义
+- Product Manager：分析竞争和用户需求，创建 PRD
+- Architect：将需求转化为系统设计组件
+- Project Manager：任务分发
+- Engineer：执行代码编写
+- QA Engineer：测试用例和代码质量
+
+#### 关键设计：结构化通信
+> "Unlike ChatDev, agents in MetaGPT communicate through documents and diagrams (structured outputs) rather than dialogue. These documents contain all necessary information, preventing irrelevant or missing content."
+
+#### 发布-订阅机制
+> "Any agent can directly retrieve required information from the shared pool, eliminating the need to inquire about other agents and await their responses."
+> "An agent activates its action only after receiving all its prerequisite dependencies."
+
+#### 对闲聊的抑制
+> "This reduces the risk of hallucinations caused by idle chatter between LLMs, particularly in role-playing frameworks, like: 'Hi, hello and how are you?' – Alice (Product Manager); 'Great! Have you had lunch?' – Bob (Architect)."
+
+---
+
+### 来源 4：LangGraph/CrewAI/AutoGen 框架对比
+
+**来源**：https://dev.to/pockit_tools/langgraph-vs-crewai-vs-autogen-the-complete-multi-agent-ai-orchestration-guide-for-2026-2d63
+
+#### LangGraph Supervisor Pattern 提示词示例
+```python
+def supervisor_node(state: AgentState) -> AgentState:
+    """Central coordinator that routes to specialists."""
+    llm = ChatOpenAI(model="gpt-4o")
+    decision = llm.invoke([
+        {"role": "system", "content": """You are a supervisor.
+Based on the current state, decide the next action:
+- 'research': Need more information
+- 'respond': Ready to generate response
+- 'escalate': Needs human intervention
+- 'complete': Task is done"""},
+        {"role": "user", "content": f"Current state: {state}"}
+    ])
+    return {"next_action": decision.content}
+```
+
+#### CrewAI 角色定义模式
+```python
+classifier_agent = Agent(
+    role="Customer Intent Classifier",
+    goal="Accurately categorize customer inquiries to route them appropriately",
+    backstory="""You are an expert at understanding customer needs.
+With years of experience in customer service, you can quickly
+identify whether a customer needs billing help, technical support,
+or has a complaint that needs escalation.""",
+    verbose=True,
+    allow_delegation=False  # 关键：防止无限委派
+)
+```
+
+#### 常见陷阱及解决方案
+1. **Over-Engineering**：20 个智能体做 3 个就能做的事 → 从 2-3 个开始
+2. **Infinite Loops**：智能体互相无限委派 → 设置终止条件 `max_iter=10`
+3. **Context Window Explosion**：传递完整历史 → 实现摘要或滑动窗口
+4. **No Error Boundaries**：一个智能体失败崩溃全系统 → 包裹错误处理
+
+---
+
+### 来源 5：GitHub Issue - Inception Prompting 实战
+
+**来源**：https://github.com/NousResearch/hermes-agent/issues/375
+
+#### Hermes Agent 的 Inception Prompting 实现方案
+
+**Phase 1: Prompt Hardening（提示词加固）**
+
+修改 `_build_child_system_prompt()` 包含：
+- **Role-anchoring**: "You are executing a delegated task. Do the work directly — do not ask questions, request clarification, or suggest the requester do it instead."
+- **Anti-echo**: "Do not restate or paraphrase the task. Perform it using your tools and report concrete results."
+- **Output format guidance**: "Your response must include specific findings, file paths, code snippets, or other concrete artifacts. Vague summaries like 'it seems fine' or 'further investigation needed' are not acceptable."
+- **Convergence pressure**: "If an approach fails twice, try a fundamentally different approach rather than retrying the same thing."
+
+**Phase 2: Enhanced Guard Rails（增强护栏）**
+- 角色特定提示词（coordinator, worker, synthesizer）
+- 反循环检测：如果智能体最近 N 条消息语义相似，注入 "you appear stuck" 干预
+
+---
+
+## 三、综合分析：当前提示词的不足
+
+对照外部最佳实践，当前 Team Leader 提示词存在以下可改善点：
+
+### 3.1 Team Leader 提示词
+
+| # | 不足 | 外部参考 |
+|---|------|----------|
+| 1 | **缺少任务复杂度评估指引** | Anthropic：应在提示词中嵌入 scaling rules，教 Team Leader 评估何时用 1 个子智能体、何时用多个 |
+| 2 | **缺少委派质量标准** | Anthropic：每个子智能体需要 objective + output format + tools guidance + task boundaries，当前只说"写清楚任务目标、范围、产出要求"太笼统 |
+| 3 | **缺少"先宽后窄"策略指引** | Anthropic：应引导 Team Leader 在分解任务时先探索全局再深入 |
+| 4 | **缺少防过度工程指引** | LangGraph/CrewAI：应明确"从 2-3 个子智能体开始，遇到明确瓶颈再加" |
+| 5 | **缺少收敛和终止判断指引** | CAMEL/MetaGPT：应教 Team Leader 如何判断任务完成、如何防止子智能体无限循环 |
+| 6 | **缺少对子智能体失败模式的预判** | CAMEL：应告知 Team Leader 子智能体可能出现 role-flipping、echoing、flake replies，并给出应对策略 |
+| 7 | **角色定义太单薄** | CrewAI/MetaGPT：当前只有一句话"协调多个子智能体分工协作"，缺少 goal、constraints、思维方式指引 |
+| 8 | **缺少综合与决策角色强调** | Anthropic：Team Leader 不仅是"协调者"，更是"综合者"和"决策者" |
+| 9 | **缺少上下文管理意识** | Anthropic：应提醒 Team Leader 子智能体输出会消耗主上下文，需要引导子智能体精简输出 |
+
+### 3.2 子智能体提示词
+
+| # | 不足 | 外部参考 |
+|---|------|----------|
+| 1 | **缺少 role anchoring** | CAMEL：应明确"你是执行者，不要反转角色，不要反向提问或委派" |
+| 2 | **缺少 anti-echo 指令** | CAMEL/Hermes：应明确"不要复述任务，直接执行" |
+| 3 | **缺少输出具体性要求** | Hermes：应要求"输出必须包含具体发现、文件路径、代码片段等具体产物，模糊总结不可接受" |
+| 4 | **缺少收敛压力** | CAMEL/Hermes：应加入"如果一个方法失败两次，换一种根本不同的方法" |
+| 5 | **缺少 stuck 自检指引** | Hermes Phase 2：应引导子智能体自我检测是否陷入循环 |
+| 6 | **"不频繁输出"太模糊** | 应给出更具体的输出节奏指引 |
+
+---
+
+## 四、优化方向建议
+
+### 4.1 Team Leader 提示词优化方向
+
+1. **丰富角色定义**：从"协调者"升级为"战略规划者 + 任务分解者 + 综合决策者"
+2. **加入任务复杂度评估框架**：简单/中等/复杂三档，对应不同的子智能体数量和工具调用预算
+3. **加入委派质量检查清单**：每次委派前自检 objective/output format/tools/boundaries 是否齐全
+4. **加入失败模式预判和应对**：告知子智能体可能的问题行为及干预手段
+5. **加入收敛和终止指引**：如何判断整体任务完成、如何处理卡住的子智能体
+6. **加入上下文管理意识**：引导子智能体精简输出，避免主上下文膨胀
+
+### 4.2 子智能体提示词优化方向
+
+1. **加入 role anchoring**：明确角色边界，禁止角色反转
+2. **加入 anti-echo 和输出具体性要求**：不复述任务，输出必须具体
+3. **加入收敛压力和 stuck 自检**：失败换方法，自我检测循环
+4. **优化输出节奏指引**：从"不频繁输出"改为更具体的节奏建议
+
+---
+
+*报告完毕，接下来可与用户讨论具体优化方案。*

scripts/migrate_multi_agent_conversations.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""把误存到常规对话目录的多智能体会话迁移到 mutiagents/conversations/。
+
+用法:
+    python3 scripts/migrate_multi_agent_conversations.py [--dry-run]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+# 加载项目配置以确定数据目录
+project_root = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(project_root))
+from config import DATA_DIR, IS_HOST_MODE
+from modules.multi_agent.role_store import DEFAULT_MUTIAGENTS_DIR
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(f".tmp.{int(time.time() * 1000)}")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    shutil.move(str(tmp), str(path))
+
+
+def migrate(dry_run: bool = False) -> dict:
+    regular_dir = Path(DATA_DIR) / "conversations" / "workspace"
+    ma_dir = Path(DEFAULT_MUTIAGENTS_DIR) / "conversations" / "workspace"
+
+    regular_index_path = regular_dir / "index.json"
+    ma_index_path = ma_dir / "index.json"
+
+    regular_index = load_json(regular_index_path) if regular_index_path.exists() else {}
+    ma_index = load_json(ma_index_path) if ma_index_path.exists() else {}
+
+    moved = []
+    skipped = []
+    errors = []
+
+    for f in sorted(regular_dir.glob("conv_*.json")):
+        if f.name == "index.json":
+            continue
+        try:
+            data = load_json(f)
+        except Exception as exc:
+            errors.append({"file": str(f), "error": f"读取失败: {exc}"})
+            continue
+
+        meta = data.get("metadata", {}) or {}
+        if not meta.get("multi_agent_mode"):
+            skipped.append(f.name)
+            continue
+
+        conv_id = data.get("id") or f.stem
+        target_file = ma_dir / f.name
+
+        # 目标已存在时跳过，避免覆盖
+        if target_file.exists():
+            errors.append({"file": str(f), "error": f"目标已存在: {target_file}"})
+            continue
+
+        if dry_run:
+            moved.append({"id": conv_id, "file": f.name, "target": str(target_file)})
+            continue
+
+        try:
+            # 移动文件
+            target_file.parent.mkdir(parents=True, exist_ok=True)
+            shutil.move(str(f), str(target_file))
+
+            # 更新索引
+            if conv_id in regular_index:
+                ma_index[conv_id] = regular_index.pop(conv_id)
+            else:
+                # 从文件重建索引条目
+                ma_index[conv_id] = {
+                    "title": data.get("title") or "未命名对话",
+                    "created_at": data.get("created_at"),
+                    "updated_at": data.get("updated_at"),
+                    "project_path": meta.get("project_path"),
+                    "project_relative_path": meta.get("project_relative_path"),
+                    "thinking_mode": meta.get("thinking_mode", False),
+                    "run_mode": meta.get("run_mode") or ("thinking" if meta.get("thinking_mode") else "fast"),
+                    "model_key": meta.get("model_key"),
+                    "has_images": meta.get("has_images", False),
+                    "has_videos": meta.get("has_videos", False),
+                    "total_messages": meta.get("total_messages", 0),
+                    "total_tools": meta.get("total_tools", 0),
+                    "status": meta.get("status", "active"),
+                    "multi_agent_mode": True,
+                }
+
+            moved.append({"id": conv_id, "file": f.name, "target": str(target_file)})
+        except Exception as exc:
+            errors.append({"file": str(f), "error": f"迁移失败: {exc}"})
+
+    if not dry_run:
+        # 保存索引
+        save_json(regular_index_path, regular_index)
+        save_json(ma_index_path, ma_index)
+
+    return {
+        "dry_run": dry_run,
+        "regular_dir": str(regular_dir),
+        "ma_dir": str(ma_dir),
+        "moved": moved,
+        "skipped_count": len(skipped),
+        "errors": errors,
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="迁移多智能体会话到 mutiagents 目录")
+    parser.add_argument("--dry-run", action="store_true", help="只预览，不实际移动")
+    args = parser.parse_args()
+
+    result = migrate(dry_run=args.dry_run)
+
+    print(f"常规目录: {result['regular_dir']}")
+    print(f"目标目录: {result['ma_dir']}")
+    print(f"模式: {'预览' if args.dry_run else '实际迁移'}")
+    print(f"将迁移: {len(result['moved'])} 个对话")
+    print(f"跳过（非多智能体）: {result['skipped_count']} 个")
+    print(f"错误: {len(result['errors'])}")
+
+    for item in result["moved"]:
+        print(f"  → {item['id']} -> {item.get('target', item['file'])}")
+
+    for err in result["errors"]:
+        print(f"  ⚠ {err['file']}: {err['error']}")
+
+
+if __name__ == "__main__":
+    main()

server/app_legacy.py

@@ -33,6 +33,7 @@ from server.usage import usage_bp
 from server.status import status_bp
 from server.tasks import tasks_bp
 from server.api_v1 import api_v1_bp
+from server.multi_agent import multi_agent_bp
 from server.socket_handlers import socketio
 from server.security import attach_security_hooks
 from werkzeug.utils import secure_filename
@@ -296,6 +297,7 @@ app.register_blueprint(usage_bp)
 app.register_blueprint(status_bp)
 app.register_blueprint(tasks_bp)
 app.register_blueprint(api_v1_bp)
+app.register_blueprint(multi_agent_bp)
 
 # 安全钩子（CSRF 校验 + 响应头）
 attach_security_hooks(app)
@@ -523,7 +525,7 @@ def generate_conversation_title_background(web_terminal: WebTerminal, conversati
         safe_title = title[:80]
         ok = False
         try:
-            ok = web_terminal.context_manager.conversation_manager.update_conversation_title(conversation_id, safe_title)
+            ok = web_terminal.context_manager._get_conversation_manager_for_id(conversation_id).update_conversation_title(conversation_id, safe_title)
         except Exception as exc:
             debug_log(f"[TitleGen] 保存标题失败: {exc}")
             _title_debug_log("title_save_exception", error=str(exc), conversation_id=conversation_id)
@@ -1080,7 +1082,7 @@ def ensure_conversation_loaded(terminal: WebTerminal, conversation_id: Optional[
                 raise RuntimeError(load_result.get("message", "对话加载失败"))
             # 切换到对话记录的运行模式
             try:
-                conv_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id) or {}
+                conv_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id) or {}
                 meta = conv_data.get("metadata", {}) or {}
                 run_mode_meta = meta.get("run_mode")
                 if run_mode_meta:
@@ -1340,6 +1342,13 @@ def initialize_system(path: str, thinking_mode: bool = False):
     print(f"[Init] 调试日志: {DEBUG_LOG_FILE}")
     app.config['DEFAULT_THINKING_MODE'] = thinking_mode
     app.config['DEFAULT_RUN_MODE'] = "thinking" if thinking_mode else "fast"
+    # 同步预设子智能体角色到运行态目录
+    try:
+        from modules.multi_agent.role_store import sync_preset_roles
+        sync_preset_roles()
+        print(f"{OUTPUT_FORMATS['success']} 预设子智能体角色同步完成")
+    except Exception as _e:
+        print(f"{OUTPUT_FORMATS['warning']} 预设子智能体角色同步失败: {_e}")
     print(f"{OUTPUT_FORMATS['success']} Web系统初始化完成（多用户模式）")
 
 

server/auth.py

@@ -224,7 +224,7 @@ def host_login():
     data_dir.mkdir(parents=True, exist_ok=True)
     logs_dir = Path(LOGS_DIR).expanduser().resolve()
     logs_dir.mkdir(parents=True, exist_ok=True)
-    uploads_dir = host_path / ".agents" / "user_upload"
+    uploads_dir = host_path / ".astrion" / "user_upload"
     uploads_dir.mkdir(parents=True, exist_ok=True)
     quarantine_root = Path(UPLOAD_QUARANTINE_SUBDIR).expanduser()
     if not quarantine_root.is_absolute():

server/chat_flow_helpers.py

@@ -132,7 +132,7 @@ def generate_conversation_title_background(
         safe_title = title[:80]
         ok = False
         try:
-            ok = web_terminal.context_manager.conversation_manager.update_conversation_title(conversation_id, safe_title)
+            ok = web_terminal.context_manager._get_conversation_manager_for_id(conversation_id).update_conversation_title(conversation_id, safe_title)
         except Exception as exc:
             debug_logger(f"[TitleGen] 保存标题失败: {exc}")
             _title_debug_log("title_save_exception", error=str(exc), conversation_id=conversation_id)

server/chat_flow_task_main.py

@@ -45,6 +45,7 @@ from modules.upload_security import UploadSecurityError
 from modules.user_manager import UserWorkspace
 from modules.usage_tracker import QUOTA_DEFAULTS
 from modules.sub_agent import TERMINAL_STATUSES
+from modules.multi_agent.debug_logger import ma_debug
 from modules.versioning_manager import ConversationVersioningManager, VersioningError
 from modules.shallow_versioning import ShallowVersioningManager
 from core.web_terminal import WebTerminal
@@ -130,7 +131,13 @@ from .chat_flow_runtime import (
     detect_malformed_tool_call,
 )
 
-from .chat_flow_task_support import process_sub_agent_updates, process_background_command_updates
+from .chat_flow_task_support import (
+    process_sub_agent_updates,
+    process_background_command_updates,
+    process_multi_agent_master_messages,
+    inject_multi_agent_master_message,
+    _auto_message_type_for_multi_agent_subtype,
+)
 from .chat_flow_tool_loop import execute_tool_calls
 from .chat_flow_stream_loop import run_streaming_attempts
 from .deep_compression import run_deep_compression
@@ -569,6 +576,12 @@ async def _dispatch_completion_user_notice(
                 for item in preceding_notices
                 if str(item.get("message") or "").strip()
             ]
+        ma_debug(
+            "dispatch_completion_create_chat_task",
+            conversation_id=conversation_id,
+            user_message_preview=user_message[:300],
+            preceding_count=len(preceding_notices),
+        )
         rec = task_manager.create_chat_task(
             username,
             workspace_id,
@@ -580,6 +593,11 @@ async def _dispatch_completion_user_notice(
             run_mode=session_data.get("run_mode"),
             session_data=session_data,
         )
+        ma_debug(
+            "dispatch_completion_task_created",
+            conversation_id=conversation_id,
+            task_id=getattr(rec, "task_id", None),
+        )
         payload = {
             'message': user_message,
             'conversation_id': conversation_id,
@@ -701,6 +719,7 @@ def _collect_pending_completion_notices(*, web_terminal, conversation_id: str) -
             and t.get("status") in TERMINAL_STATUSES  # completed/failed/timeout（不含 terminated）
             and not t.get("notified")
             and t.get("task_id") not in web_terminal._announced_sub_agent_tasks
+            and not t.get("multi_agent_mode")  # 多智能体任务走独立注入路径，不在这里发传统通知
         ]
         candidates.sort(key=lambda t: t.get("updated_at") or t.get("created_at") or 0)
         for task_info in candidates:
@@ -783,22 +802,31 @@ def _collect_pending_completion_notices(*, web_terminal, conversation_id: str) -
 
 
 def _has_pending_completion_work(*, web_terminal, conversation_id: str) -> bool:
-    """是否还有运行中或待通知的后台任务（用于决定是否继续轮询）。"""
+    """是否还有运行中或待通知的传统后台任务（子智能体/后台 run_command）。
+
+    多智能体模式下的 pending 消息由独立的 poll_multi_agent_notifications 处理，
+    不再混入本函数。
+    """
     sub_manager = getattr(web_terminal, "sub_agent_manager", None)
     if sub_manager:
         announced = getattr(web_terminal, "_announced_sub_agent_tasks", set())
+        has_running_non_ma = False
+        has_unnotified_non_ma = False
         for task in sub_manager.tasks.values():
             if not isinstance(task, dict):
                 continue
-            if not task.get("run_in_background"):
-                continue
             if task.get("conversation_id") != conversation_id:
                 continue
             status = task.get("status")
+            multi_agent_flag = task.get("multi_agent_mode") or False
             if status not in TERMINAL_STATUSES.union({"terminated"}):
-                return True  # 仍在运行
-            if status != "terminated" and (task.get("task_id") not in announced) and not task.get("notified"):
-                return True  # 已完成但未通知
+                if not multi_agent_flag and task.get("run_in_background"):
+                    has_running_non_ma = True
+                continue
+            if not multi_agent_flag and task.get("run_in_background") and (task.get("task_id") not in announced) and not task.get("notified"):
+                has_unnotified_non_ma = True
+        if has_running_non_ma or has_unnotified_non_ma:
+            return True
     bg_manager = getattr(web_terminal, "background_command_manager", None)
     if bg_manager:
         try:
@@ -840,6 +868,7 @@ async def poll_completion_notifications(*, web_terminal, workspace, conversation
             pass
 
     loop_count = 0
+    ma_debug("poll_completion_notifications_start", conversation_id=conversation_id)
     while (time.time() - start_wait) < max_wait_time:
         loop_count += 1
         # 检查停止标志
@@ -847,17 +876,27 @@ async def poll_completion_notifications(*, web_terminal, workspace, conversation
         if client_stop_info:
             stop_requested = client_stop_info.get('stop', False) if isinstance(client_stop_info, dict) else client_stop_info
             if stop_requested:
+                ma_debug("poll_completion_notifications_stop_requested", conversation_id=conversation_id)
                 break
 
         # 若主对话仍在工具循环中，暂不消费完成事件，避免抢占 system 消息插入
         if getattr(web_terminal, "_tool_loop_active", False):
+            ma_debug("poll_completion_notifications_wait_tool_loop", conversation_id=conversation_id)
             await asyncio.sleep(1)
             continue
 
+        # 多智能体模式：主对话任务仍在运行时，由主循环自己消费 pending 消息
+        if getattr(web_terminal, "_multi_agent_main_task_active", False):
+            ma_debug("poll_completion_notifications_wait_main_task", conversation_id=conversation_id)
+            await asyncio.sleep(1)
+            continue
+
+        ma_debug("poll_completion_notifications_collect", conversation_id=conversation_id, loop_count=loop_count)
         notices = _collect_pending_completion_notices(
             web_terminal=web_terminal,
             conversation_id=conversation_id,
         )
+        ma_debug("poll_completion_notifications_collected", conversation_id=conversation_id, notice_count=len(notices))
 
         if notices:
             # 取出后剩余是否还有未完成/未通知的后台工作（决定前端是否保持等待态）
@@ -912,6 +951,383 @@ async def poll_completion_notifications(*, web_terminal, workspace, conversation
         await asyncio.sleep(5)
 
 
+async def poll_multi_agent_notifications(*, web_terminal, workspace, conversation_id, client_sid, username):
+    """多智能体模式专用通知池。
+
+    只在主任务结束后启动，负责两件事：
+    1. 若主任务已空闲且 MultiAgentState 中有 pending_master_messages，
+       一次性取出并触发新一轮主任务工作——即使仍有 running 子智能体也立即派发
+       （主对话空闲时消息池有消息就该全部插入，设计中属情况2）。
+    2. 若 pending 为空且仍有 running 实例，循环等待下一次 push 新输出。
+
+    重要：旧实现要求所有 running 实例退出再 drain，导致 ask_master 阻塞中的
+    子智能体永远等不到主对话回答而超时——现已修复为池优先。
+
+    与 poll_completion_notifications 完全分离，避免多智能体消息和传统后台
+    通知竞争 task_manager 的单工作区互斥。
+    """
+    from .extensions import socketio
+
+    max_wait_time = 3600
+    start_wait = time.time()
+
+    def sender(event_type, data):
+        try:
+            socketio.emit(event_type, data, room=f"user_{username}")
+        except Exception:
+            pass
+
+    import threading as _threading
+    ma_debug(
+        "poll_ma_notifications_start",
+        conversation_id=conversation_id,
+        thread_id=_threading.get_ident(),
+        multi_agent_mode=getattr(web_terminal, "multi_agent_mode", False),
+        main_task_active_at_start=getattr(web_terminal, "_multi_agent_main_task_active", False),
+    )
+
+    tick_count = 0
+    while (time.time() - start_wait) < max_wait_time:
+        tick_count += 1
+        # 检查停止标志
+        client_stop_info = get_stop_flag(client_sid, username)
+        if client_stop_info:
+            stop_requested = client_stop_info.get('stop', False) if isinstance(client_stop_info, dict) else client_stop_info
+            if stop_requested:
+                ma_debug("poll_ma_notifications_stop_requested", conversation_id=conversation_id, tick=tick_count)
+                break
+
+        manager = getattr(web_terminal, "sub_agent_manager", None)
+        if not manager:
+            ma_debug("poll_ma_no_manager", conversation_id=conversation_id, tick=tick_count)
+            break
+
+        state = manager.get_multi_agent_state(conversation_id)
+        if not state:
+            ma_debug("poll_ma_no_state", conversation_id=conversation_id, tick=tick_count)
+            break
+
+        # 主任务又被唤醒了（用户发送新消息等），让主循环自己处理，本通知池退出
+        if getattr(web_terminal, "_multi_agent_main_task_active", False):
+            ma_debug("poll_ma_notifications_main_task_active", conversation_id=conversation_id, tick=tick_count)
+            break
+
+        # 状态快照
+        all_insts = state.list_all()
+        statuses = [a.status for a in all_insts]
+        pending_count_now = len(state.pending_master_messages)
+        main_active = getattr(web_terminal, "_multi_agent_main_task_active", False)
+        ma_debug(
+            "poll_ma_tick",
+            conversation_id=conversation_id,
+            tick=tick_count,
+            instance_count=len(all_insts),
+            statuses=statuses,
+            pending_count=pending_count_now,
+            main_active=main_active,
+        )
+
+        # 1) 先检查 pending 池——主对话空闲时只要池里有消息就立即派发（情况2）。
+        if state.has_pending_master_messages():
+            pending = state.drain_master_messages()
+            ma_debug(
+                "poll_ma_notifications_dispatch",
+                conversation_id=conversation_id,
+                count=len(pending),
+                running_count=len([a for a in all_insts if a.status == "running"]),
+                previews=[str(m)[:200] for m in pending],
+                tick=tick_count,
+            )
+            try:
+                await _dispatch_multi_agent_idle_messages(
+                    web_terminal=web_terminal,
+                    workspace=workspace,
+                    sender=sender,
+                    client_sid=client_sid,
+                    username=username,
+                    conversation_id=conversation_id,
+                    messages=pending,
+                )
+                ma_debug("poll_ma_dispatch_success", conversation_id=conversation_id, count=len(pending), tick=tick_count)
+            except Exception as exc:
+                debug_log(f"[MultiAgent] 分发 idle 消息失败: {exc}")
+                ma_debug(
+                    "poll_ma_notifications_dispatch_error",
+                    conversation_id=conversation_id,
+                    error=str(exc),
+                    error_type=type(exc).__name__,
+                    tick=tick_count,
+                )
+            # 分发后退出，由新任务结束后再决定是否继续轮询
+            return
+
+        # 2) 没有 pending 消息：检查还有哪些子智能体在运行，决定退出还是继续等
+        running_agents = [a for a in all_insts if a.status == "running"]
+        if not running_agents:
+            ma_debug("poll_ma_notifications_no_work_end", conversation_id=conversation_id, tick=tick_count)
+            break
+
+        ma_debug(
+            "poll_ma_notifications_wait_running",
+            conversation_id=conversation_id,
+            running_count=len(running_agents),
+            tick=tick_count,
+        )
+        await asyncio.sleep(0.5)
+
+    ma_debug("poll_ma_notifications_end", conversation_id=conversation_id, tick=tick_count)
+
+    # poll 退出时，如果主智能体也空闲且没有 pending 消息，发送 task_complete 通知前端对话变空闲。
+    # 否则前端会一直保持 taskInProgress=true，MultiAgentTaskProbe 会持续轮询但找不到任务。
+    if not getattr(web_terminal, "_multi_agent_main_task_active", False):
+        state = manager.get_multi_agent_state(conversation_id) if manager else None
+        still_running = state and any(a.status == "running" for a in state.list_all())
+        still_pending = state and state.has_pending_master_messages()
+        if not still_running and not still_pending:
+            sender('task_complete', {
+                'total_iterations': 0,
+                'total_tool_calls': 0,
+                'auto_fix_attempts': 0,
+                'has_running_sub_agents': False,
+                'has_running_background_commands': False,
+                'has_running_multi_agent': False,
+                'pending_runtime_guidance_messages': [],
+                'multi_agent_idle_signal': True,
+            })
+            ma_debug("poll_ma_idle_signal_sent", conversation_id=conversation_id, tick=tick_count)
+
+
+async def _dispatch_multi_agent_idle_messages(
+    *,
+    web_terminal,
+    workspace,
+    sender,
+    client_sid,
+    username,
+    conversation_id,
+    messages: List[str],
+):
+    """主智能体空闲时，把多智能体 pending 消息作为新一轮用户消息分发。
+
+    所有消息先持久化到对话历史；前 N-1 条作为前置通知通过 socketio 推送；
+    最后一条创建 task_type="notice" 任务触发 Team Leader 新一轮工作。
+    """
+    ma_debug(
+        "dispatch_ma_idle_enter",
+        conversation_id=conversation_id,
+        count=len(messages) if messages else 0,
+        previews=[str(m)[:150] for m in (messages or [])],
+    )
+    if not messages:
+        ma_debug("dispatch_ma_idle_no_messages", conversation_id=conversation_id)
+        return
+
+    from modules.multi_agent.state import parse_multi_agent_message
+    from .tasks import task_manager
+
+    parsed_messages = []
+    for msg_text in messages:
+        parsed = parse_multi_agent_message(msg_text) or {}
+        parsed_messages.append({
+            "text": msg_text,
+            "display_name": parsed.get("display_name"),
+            "subtype": parsed.get("subtype"),
+        })
+
+    # 1) 前置通知全部写入历史 + emit给在线客户端（未后一条会由后续任务自己持久化，
+    #    避免重复产生两条相同 user 消息导致刷新后被渲染两遍）。
+    ma_debug(
+        "dispatch_ma_idle_preceding",
+        conversation_id=conversation_id,
+        preceding_count=max(0, len(parsed_messages) - 1),
+    )
+    for item in parsed_messages[:-1]:
+        inject_multi_agent_master_message(
+            web_terminal=web_terminal,
+            messages=None,
+            text=item["text"],
+            sender=sender,
+            conversation_id=conversation_id,
+            inline=False,
+        )
+
+    # 1.5) 最后一条只 emit 给在线客户端，不在这里持久化（后续 task handle_task_with_sender
+    #      会以这条文本作为 message 创建任务，并写入历史，从而避免重复写入。）
+    last = parsed_messages[-1]
+    message_source = "sub_agent"
+    last_emit_payload = {
+        "message": last["text"],
+        "content": last["text"],
+        "conversation_id": conversation_id,
+        "message_source": message_source,
+        "sub_agent_notice": True,
+        "multi_agent_message": True,
+        "multi_agent_display_name": last["display_name"],
+        "multi_agent_subtype": last["subtype"],
+        "auto_message_type": _auto_message_type_for_multi_agent_subtype(last["subtype"]),
+        "visibility": "chat",
+        "starts_work": False,
+        "metadata": {
+            "message_source": message_source,
+            "auto_message_type": _auto_message_type_for_multi_agent_subtype(last["subtype"]),
+            "multi_agent_message": True,
+            "multi_agent_display_name": last["display_name"],
+            "multi_agent_subtype": last["subtype"],
+            "visibility": "chat",
+            "starts_work": False,
+        },
+        "timestamp": datetime.now().isoformat(),
+    }
+    try:
+        sender("user_message", last_emit_payload)
+        ma_debug(
+            "dispatch_ma_idle_last_emit",
+            conversation_id=conversation_id,
+            message_preview=last["text"][:200],
+        )
+    except Exception as exc:
+        ma_debug(
+            "dispatch_ma_idle_last_emit_error",
+            conversation_id=conversation_id,
+            error=str(exc),
+        )
+
+    # 2) 前置通知的 socketio emit 已在上述注入 inject_multi_agent_master_message 内
+    #    同时完成，避免在多智能体消息场景重复发送相同事件。
+
+    # 3) 最后一条触发新一轮工作
+    ui_defaults = dict(_user_message_ui_defaults(message_source, auto_user_message_event=True))
+    ui_defaults["starts_work"] = False
+
+    workspace_id = getattr(workspace, "workspace_id", None) or "default"
+    host_mode = bool(getattr(workspace, "username", None) == "host")
+    session_data = {
+        "username": username,
+        "role": getattr(web_terminal, "user_role", "user"),
+        "is_api_user": getattr(web_terminal, "user_role", "") == "api",
+        "host_mode": host_mode,
+        "host_workspace_id": workspace_id if host_mode else None,
+        "workspace_id": workspace_id,
+        "run_mode": getattr(web_terminal, "run_mode", None),
+        "thinking_mode": getattr(web_terminal, "thinking_mode", None),
+        "model_key": getattr(web_terminal, "model_key", None),
+        "message_source": message_source,
+    }
+    ma_auto_type = _auto_message_type_for_multi_agent_subtype(last["subtype"])
+    # 重要：ui_defaults 默认会给出 visibility="compact"/starts_work=False，
+    # 多智能体主消息是正常聊天消息，必须在 **ui_defaults 之后覆写为 chat，
+    # 否则后端历史 metadata.visibility=compact 会让加载的消息走通知渲染。
+    session_data["auto_user_message_event"] = True
+    session_data["auto_user_message_payload"] = {
+        **ui_defaults,
+        "message_source": message_source,
+        "sub_agent_notice": True,
+        "multi_agent_message": True,
+        "multi_agent_display_name": last["display_name"],
+        "multi_agent_subtype": last["subtype"],
+        "auto_message_type": ma_auto_type,
+        "starts_work": False,
+        "visibility": "chat",
+        "timestamp": datetime.now().isoformat(),
+    }
+    ma_debug(
+        "dispatch_ma_idle_before_create_task",
+        conversation_id=conversation_id,
+        last_text_preview=last["text"][:300],
+        workspace_id=workspace_id,
+        username=username,
+    )
+    session_data["auto_user_message_payload"].setdefault("metadata", {
+        **ui_defaults,
+        "message_source": message_source,
+        "auto_message_type": ma_auto_type,
+        "multi_agent_message": True,
+        "multi_agent_display_name": last["display_name"],
+        "multi_agent_subtype": last["subtype"],
+        "starts_work": False,
+        "visibility": "chat",
+    })
+    if len(parsed_messages) > 1:
+        session_data["preceding_user_notices"] = [
+            {
+                "message": item["text"],
+                "payload": {
+                    "message_source": "sub_agent",
+                    "sub_agent_notice": True,
+                    "multi_agent_message": True,
+                    "multi_agent_display_name": item["display_name"],
+                    "multi_agent_subtype": item["subtype"],
+                    "auto_message_type": _auto_message_type_for_multi_agent_subtype(item["subtype"]),
+                    "visibility": "chat",
+                    "starts_work": False,
+                },
+            }
+            for item in parsed_messages[:-1]
+        ]
+
+    try:
+        rec = task_manager.create_chat_task(
+            username,
+            workspace_id,
+            last["text"],
+            [],
+            conversation_id,
+            model_key=session_data.get("model_key"),
+            thinking_mode=session_data.get("thinking_mode"),
+            run_mode=session_data.get("run_mode"),
+            session_data=session_data,
+            task_type="notice",
+        )
+    except Exception as exc:
+        ma_debug(
+            "dispatch_ma_idle_create_task_exception",
+            conversation_id=conversation_id,
+            error=str(exc),
+            error_type=type(exc).__name__,
+        )
+        raise
+    task_id_created = getattr(rec, "task_id", None)
+    ma_debug("dispatch_ma_idle_task_created", conversation_id=conversation_id, task_id=task_id_created)
+
+    payload = {
+        "message": last["text"],
+        "content": last["text"],
+        "conversation_id": conversation_id,
+        "task_id": getattr(rec, "task_id", None),
+        "message_source": message_source,
+        "sub_agent_notice": True,
+        "multi_agent_message": True,
+        "multi_agent_display_name": last["display_name"],
+        "multi_agent_subtype": last["subtype"],
+        "visibility": "chat",
+        "starts_work": False,
+        "auto_message_type": _auto_message_type_for_multi_agent_subtype(last["subtype"]),
+        "metadata": {
+            "message_source": message_source,
+            "auto_message_type": _auto_message_type_for_multi_agent_subtype(last["subtype"]),
+            "multi_agent_message": True,
+            "multi_agent_display_name": last["display_name"],
+            "multi_agent_subtype": last["subtype"],
+            "visibility": "chat",
+            "starts_work": False,
+        },
+        "timestamp": datetime.now().isoformat(),
+    }
+    sender("user_message", payload)
+    ma_debug(
+        "dispatch_ma_idle_sender_user_message",
+        conversation_id=conversation_id,
+        task_id=getattr(rec, "task_id", None),
+        payload_message_preview=last["text"][:200],
+    )
+    ma_debug(
+        "dispatch_ma_idle_exit_ok",
+        conversation_id=conversation_id,
+        count=len(parsed_messages),
+        task_id=getattr(rec, "task_id", None),
+    )
+
+
 async def handle_task_with_sender(
     terminal: WebTerminal,
     workspace: UserWorkspace,
@@ -928,6 +1344,23 @@ async def handle_task_with_sender(
 
     web_terminal = terminal
     conversation_id = getattr(web_terminal.context_manager, "current_conversation_id", None)
+    # 多智能体模式：标记主对话任务正在运行，供后台通知池判断是否可以安全消费
+    if getattr(web_terminal, "multi_agent_mode", False):
+        web_terminal._multi_agent_main_task_active = True
+        manager = getattr(web_terminal, "sub_agent_manager", None)
+        pending_count = 0
+        if manager:
+            state = manager.get_multi_agent_state(conversation_id)
+            if state:
+                pending_count = len(state.pending_master_messages)
+        ma_debug(
+            "handle_task_with_sender_start",
+            conversation_id=conversation_id,
+            terminal_id=id(web_terminal),
+            manager_id=id(manager) if manager else None,
+            message_preview=str(message)[:300] if message else None,
+            pending_master_messages_count=pending_count,
+        )
     videos = videos or []
     raw_sender = sender
 
@@ -975,6 +1408,7 @@ async def handle_task_with_sender(
     # 构建 user 消息来源与 metadata
     source_from_terminal = str(getattr(web_terminal, "_current_user_message_source", "user") or "user").strip().lower()
     user_message_source = source_from_terminal or "user"
+    multi_agent_meta: Dict[str, Any] = {}
     if auto_user_message_event:
         auto_payload = getattr(web_terminal, "_auto_user_message_payload", None)
         if isinstance(auto_payload, dict):
@@ -989,6 +1423,11 @@ async def handle_task_with_sender(
                 user_message_source = "background_command"
             elif auto_payload.get("sub_agent_notice"):
                 user_message_source = "sub_agent"
+            # 保留多智能体元数据，避免前端把子智能体输出渲染成普通 user 消息
+            if auto_payload.get("multi_agent_message"):
+                multi_agent_meta["multi_agent_message"] = True
+                multi_agent_meta["multi_agent_display_name"] = auto_payload.get("multi_agent_display_name")
+                multi_agent_meta["multi_agent_subtype"] = auto_payload.get("multi_agent_subtype")
     if user_message_source not in _VALID_USER_MESSAGE_SOURCES:
         user_message_source = "user"
 
@@ -1010,7 +1449,21 @@ async def handle_task_with_sender(
     # 如果是自动发送的user消息（子智能体/后台命令完成通知），添加标记
     if auto_user_message_event:
         user_message_metadata["is_auto_generated"] = True
-        user_message_metadata["auto_message_type"] = "completion_notice"
+        if multi_agent_meta.get("multi_agent_message"):
+            # 多智能体消息：恢复专用 auto_message_type 与显示字段
+            user_message_metadata["auto_message_type"] = _auto_message_type_for_multi_agent_subtype(
+                multi_agent_meta.get("multi_agent_subtype")
+            )
+            user_message_metadata.update(multi_agent_meta)
+            # 多智能体消息是正常聊天消息，走多智能体动态专用渲染，
+            # 不应走 _user_message_ui_defaults 默认给出的 visibility="compact"（通知渲染）。
+            user_message_metadata["visibility"] = "chat"
+            # 多智能体消息触发的是主智能体对子智能体输出的续答，不应显示新的
+            # assistant 回复头部（Astrion/工作时间），因此 starts_work=false。
+            # 前端通过单独的 multi_agent_message 标记恢复轮询。
+            user_message_metadata["starts_work"] = False
+        else:
+            user_message_metadata["auto_message_type"] = "completion_notice"
     saved_user_message = web_terminal.context_manager.add_conversation(
         "user",
         message,
@@ -1380,9 +1833,43 @@ async def handle_task_with_sender(
                 )
             except Exception as exc:
                 debug_log(f"[Goal] 用户停止时停止目标失败: {exc}")
+            # 计算后台任务状态，前端用这个字段决定是否保持对话运行态、输入区是否释放
+            _stopped_has_bg = False
+            _stopped_has_bg_cmd = False
+            _stopped_has_ma = False
+            _manager = getattr(web_terminal, "sub_agent_manager", None)
+            if _manager:
+                try:
+                    _manager.reconcile_task_states(conversation_id=conversation_id)
+                except Exception:
+                    pass
+                if getattr(web_terminal, "multi_agent_mode", False):
+                    _state = _manager.get_multi_agent_state(conversation_id)
+                    if _state:
+                        _stopped_has_ma = any(a.status == "running" for a in _state.list_all())
+                for _t in _manager.tasks.values():
+                    if _t.get("conversation_id") != conversation_id:
+                        continue
+                    if _t.get("status") in TERMINAL_STATUSES.union({"terminated"}):
+                        continue
+                    if _t.get("multi_agent_mode"):
+                        continue
+                    _stopped_has_bg = True
+                    break
+            _bg_mgr = getattr(web_terminal, "background_command_manager", None)
+            if _bg_mgr and conversation_id:
+                try:
+                    _bg_mgr.reconcile_stale_records(conversation_id=conversation_id)
+                except Exception:
+                    pass
+                if _bg_mgr.list_waiting_items(conversation_id):
+                    _stopped_has_bg_cmd = True
             sender('task_stopped', {
                 'message': '任务已停止',
-                'reason': 'user_requested'
+                'reason': 'user_requested',
+                'has_running_sub_agents': _stopped_has_bg,
+                'has_running_background_commands': _stopped_has_bg_cmd,
+                'has_running_multi_agent': _stopped_has_ma,
             })
             break
 
@@ -1638,6 +2125,27 @@ async def handle_task_with_sender(
                         debug_log(f"[Goal] 目标停止：{goal_result.get('reason')}")
             except Exception as exc:
                 debug_log(f"[Goal] turn 结束处理失败: {exc}")
+
+            # 多智能体模式：没有工具调用时，先消费子智能体待转发到主对话的消息；
+            # 如果有新消息注入，继续迭代让 Team Leader 响应，而不是直接结束任务。
+            if getattr(web_terminal, "multi_agent_mode", False):
+                injected_count = await process_multi_agent_master_messages(
+                    messages=messages,
+                    inline=False,
+                    web_terminal=web_terminal,
+                    sender=sender,
+                    debug_log=debug_log,
+                )
+                ma_debug(
+                    "no_tool_call_turn_process_ma_messages",
+                    conversation_id=conversation_id,
+                    injected_count=injected_count,
+                )
+                if injected_count:
+                    debug_log(f"[MultiAgent] no-tool-call turn 注入 {injected_count} 条子智能体消息，继续迭代")
+                    is_first_iteration = False
+                    continue
+
             break
 
         # 目标模式：本轮段确实产生了工具调用
@@ -1699,6 +2207,7 @@ async def handle_task_with_sender(
             last_tool_call_time=last_tool_call_time,
             process_sub_agent_updates=process_sub_agent_updates,
             process_background_command_updates=process_background_command_updates,
+            process_multi_agent_master_messages=process_multi_agent_master_messages,
             maybe_mark_failure_from_message=maybe_mark_failure_from_message,
             mark_force_thinking=mark_force_thinking,
             get_stop_flag=get_stop_flag,
@@ -1714,7 +2223,10 @@ async def handle_task_with_sender(
             sender('task_stopped', {
                 'message': tool_loop_result.get("approval_message") or '操作被用户拒绝',
                 'reason': 'approval_rejected',
-                'conversation_id': conversation_id
+                'conversation_id': conversation_id,
+                'has_running_sub_agents': False,
+                'has_running_background_commands': False,
+                'has_running_multi_agent': False
             })
             finalize_user_work_timer()
             finalize_run_versioning_checkpoint("approval_rejected")
@@ -1749,8 +2261,22 @@ async def handle_task_with_sender(
         # 标记不再是第一次迭代
         is_first_iteration = False
 
+        # 多智能体模式：在进入下一轮模型调用前，消费子智能体最新输出到主对话
+        if getattr(web_terminal, "multi_agent_mode", False):
+            await process_multi_agent_master_messages(
+                messages=messages,
+                inline=False,
+                web_terminal=web_terminal,
+                sender=sender,
+                debug_log=debug_log,
+            )
+
     
     # 最终统计
+    # 多智能体模式：主对话任务结束，解除活跃标记
+    if getattr(web_terminal, "multi_agent_mode", False):
+        web_terminal._multi_agent_main_task_active = False
+
     debug_log(f"\n{'='*40}")
     debug_log(f"任务完成统计:")
     debug_log(f"  总迭代次数: {total_iterations}")
@@ -1762,6 +2288,7 @@ async def handle_task_with_sender(
     # 检查是否有后台运行的子智能体或待通知的完成任务
     manager = getattr(web_terminal, "sub_agent_manager", None)
     has_running_sub_agents = False
+    has_running_multi_agent = False
     bg_manager = getattr(web_terminal, "background_command_manager", None)
     has_running_background_commands = False
     if manager:
@@ -1771,16 +2298,29 @@ async def handle_task_with_sender(
             debug_log(f"[SubAgent] reconcile_task_states failed: {exc}")
         if not hasattr(web_terminal, "_announced_sub_agent_tasks"):
             web_terminal._announced_sub_agent_tasks = set()
+
+        # 多智能体模式：检测是否还有真正运行中的实例，以及是否有尚未消费的 pending 消息。
+        # idle 实例已完成当前输出、保留上下文等待后续指令；pending 消息会在主任务
+        # 结束后由 poll_multi_agent_notifications 继续消费并触发新一轮工作。
+        has_pending_ma_messages = False
+        if getattr(web_terminal, "multi_agent_mode", False):
+            state = manager.get_multi_agent_state(conversation_id)
+            if state:
+                has_running_multi_agent = any(a.status == "running" for a in state.list_all())
+                has_pending_ma_messages = state.has_pending_master_messages()
+
         running_tasks = [
             task for task in manager.tasks.values()
             if task.get("status") not in TERMINAL_STATUSES.union({"terminated"})
             and task.get("run_in_background")
+            and not task.get("multi_agent_mode")
             and task.get("conversation_id") == conversation_id
         ]
         pending_notice_tasks = [
             task for task in manager.tasks.values()
             if task.get("status") in TERMINAL_STATUSES.union({"terminated"})
             and task.get("run_in_background")
+            and not task.get("multi_agent_mode")
             and task.get("conversation_id") == conversation_id
             and task.get("task_id") not in web_terminal._announced_sub_agent_tasks
         ]
@@ -1807,11 +2347,21 @@ async def handle_task_with_sender(
             # 与子智能体完全复用同一 waiting 事件（前端已有稳定处理链路）
             sender('sub_agent_waiting', _build_shared_waiting_payload(waiting_items))
 
-    # 统一「通知池」轮询器：子智能体 + 后台 run_command 合并为单一轮询链路，
-    # 每轮一次性取出两路所有待通知项，避免逐条触发「工作 → 停止 → 再工作」循环。
-    # 只 spawn 一个轮询器（无论是否同时存在子智能体与后台命令），从根本上消除
-    # 两个轮询器同时 create_chat_task 撞「单工作区互斥」的问题。
-    if has_running_sub_agents or has_running_background_commands:
+    # 传统后台任务通知池：只处理 run_in_background=True 的子智能体 / 后台 run_command。
+    needs_completion_poll = (
+        has_running_sub_agents
+        or has_running_background_commands
+        or _has_pending_completion_work(
+            web_terminal=web_terminal, conversation_id=conversation_id
+        )
+    )
+    if needs_completion_poll:
+        ma_debug(
+            "completion_poll_start",
+            conversation_id=conversation_id,
+            has_running_sub_agents=has_running_sub_agents,
+            has_running_background_commands=has_running_background_commands,
+        )
         def run_completion_poll():
             import asyncio
             loop = asyncio.new_event_loop()
@@ -1829,6 +2379,65 @@ async def handle_task_with_sender(
 
         socketio.start_background_task(run_completion_poll)
 
+    # 多智能体模式独立通知池：处理 running 实例 / idle 实例待消费的 pending 消息。
+    # 与传统后台任务完全分离，避免两者竞争 create_chat_task 的单工作区互斥。
+    ma_mode_flag = bool(getattr(web_terminal, "multi_agent_mode", False))
+    needs_ma_poll = ma_mode_flag and (has_running_multi_agent or has_pending_ma_messages)
+    ma_debug(
+        "ma_poll_decision",
+        conversation_id=conversation_id,
+        multi_agent_mode=ma_mode_flag,
+        has_running_multi_agent=has_running_multi_agent,
+        has_pending_ma_messages=has_pending_ma_messages,
+        needs_ma_poll=needs_ma_poll,
+    )
+    if needs_ma_poll:
+        ma_debug(
+            "ma_poll_start",
+            conversation_id=conversation_id,
+            has_running_multi_agent=has_running_multi_agent,
+            has_pending_ma_messages=has_pending_ma_messages,
+        )
+        def run_ma_poll():
+            import asyncio
+            import threading as _t
+            ma_debug(
+                "ma_poll_thread_enter",
+                conversation_id=conversation_id,
+                thread_id=_t.get_ident(),
+            )
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_until_complete(poll_multi_agent_notifications(
+                    web_terminal=web_terminal,
+                    workspace=workspace,
+                    conversation_id=conversation_id,
+                    client_sid=client_sid,
+                    username=username
+                ))
+            except Exception as exc:
+                ma_debug(
+                    "ma_poll_thread_exception",
+                    conversation_id=conversation_id,
+                    error=str(exc),
+                    error_type=type(exc).__name__,
+                )
+            else:
+                ma_debug("ma_poll_thread_exit_ok", conversation_id=conversation_id)
+            finally:
+                loop.close()
+                ma_debug("ma_poll_thread_finally", conversation_id=conversation_id)
+
+        socketio.start_background_task(run_ma_poll)
+
+    if not needs_completion_poll and not needs_ma_poll:
+        ma_debug(
+            "completion_poll_skip",
+            conversation_id=conversation_id,
+            reason="no_running_background_or_multi_agent",
+        )
+
     has_running_completion_jobs = has_running_sub_agents or has_running_background_commands
 
     # 任务结束时清理残留的 pending runtime mode（权限/执行环境/网络权限）。
@@ -1899,5 +2508,8 @@ async def handle_task_with_sender(
         # 沿用子智能体字段，确保前端直接走已验证通路
         'has_running_sub_agents': has_running_completion_jobs,
         'has_running_background_commands': has_running_background_commands,
+        # 多智能体模式：只要还有 running 实例或尚未消费的 pending 消息，
+        # 前端就应保持运行态并继续轮询。
+        'has_running_multi_agent': has_running_multi_agent or has_pending_ma_messages,
         'pending_runtime_guidance_messages': pending_runtime_guidance_messages,
     })

server/chat_flow_task_support.py

@@ -6,6 +6,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 from modules.sub_agent import TERMINAL_STATUSES
+from modules.multi_agent.debug_logger import ma_debug
 
 
 _VALID_SOURCES = {
@@ -178,6 +179,8 @@ async def process_sub_agent_updates(*, messages: List[Dict], inline: bool = Fals
                     continue
                 if task.get("notified"):
                     continue
+                if task.get("multi_agent_mode"):
+                    continue
                 task_conv_id = task.get("conversation_id")
                 current_conv_id = getattr(getattr(web_terminal, "context_manager", None), "current_conversation_id", None)
                 if task_conv_id and current_conv_id and task_conv_id != current_conv_id:
@@ -314,6 +317,179 @@ async def process_background_command_updates(*, messages: List[Dict], inline: bo
 
 
 
+def _auto_message_type_for_multi_agent_subtype(subtype: Optional[str]) -> str:
+    """把多智能体消息 subtype 映射为统一的 auto_message_type。"""
+    if subtype == "progress_output":
+        return "multi_agent_progress_output"
+    if subtype == "completion_report":
+        return "multi_agent_completion_report"
+    if subtype == "ask_master":
+        return "multi_agent_ask_master"
+    return "multi_agent_output"
+
+
+def inject_multi_agent_master_message(
+    *,
+    web_terminal,
+    messages,
+    text: str,
+    sender,
+    conversation_id: Optional[str] = None,
+    inline: bool = True,
+    after_tool_call_id: Optional[str] = None,
+) -> Optional[str]:
+    """把多智能体子智能体输出/消息以原生格式注入主对话，不添加 [系统通知|xxx] 前缀。"""
+    raw = "" if text is None else str(text).strip()
+    if not raw:
+        return None
+
+    ma_debug(
+        "inject_multi_agent_master_message",
+        conversation_id=conversation_id,
+        text_preview=raw[:300],
+        inline=inline,
+        after_tool_call_id=after_tool_call_id,
+    )
+
+    # 解析标准格式以获取 subtype；解析失败时回退到通用类型
+    try:
+        from modules.multi_agent.state import parse_multi_agent_message
+        parsed = parse_multi_agent_message(raw)
+    except Exception:
+        parsed = None
+    subtype = parsed.get("subtype") if parsed else None
+    auto_message_type = _auto_message_type_for_multi_agent_subtype(subtype)
+
+    metadata = {
+        "runtime_injected": True,
+        "source": "sub_agent",
+        "message_source": "sub_agent",
+        "inline": inline,
+        "is_auto_generated": True,
+        "auto_message_type": auto_message_type,
+        "multi_agent_message": True,
+        "multi_agent_display_name": parsed.get("display_name") if parsed else None,
+        "multi_agent_subtype": subtype,
+        "visibility": "chat",
+        "starts_work": False,
+    }
+
+    try:
+        ctx_manager = getattr(web_terminal, "context_manager", None)
+        if ctx_manager is not None:
+            ctx_manager.add_conversation("user", raw, metadata=metadata)
+            ma_debug(
+                "inject_ma_message_saved",
+                conversation_id=conversation_id,
+                text_preview=raw[:200],
+            )
+    except Exception as exc:
+        ma_debug("inject_ma_message_save_error", error=str(exc))
+
+    if messages is not None:
+        insert_index = len(messages)
+        if after_tool_call_id:
+            for idx, msg in enumerate(messages):
+                if msg.get("role") == "tool" and msg.get("tool_call_id") == after_tool_call_id:
+                    end = idx + 1
+                    while end < len(messages) and messages[end].get("role") == "tool":
+                        end += 1
+                    insert_index = end
+                    break
+        messages.insert(insert_index, {"role": "user", "content": raw})
+        ma_debug(
+            "inject_ma_message_inserted",
+            conversation_id=conversation_id,
+            insert_index=insert_index,
+            messages_len_after=len(messages),
+            text_preview=raw[:200],
+        )
+
+    if callable(sender):
+        payload = {
+            "message": raw,
+            "content": raw,
+            "conversation_id": conversation_id,
+            "inline": inline,
+            "source": "sub_agent",
+            "message_source": "sub_agent",
+            "visibility": "chat",
+            "starts_work": False,
+            "auto_message_type": auto_message_type,
+            "multi_agent_message": True,
+            "multi_agent_display_name": parsed.get("display_name") if parsed else None,
+            "multi_agent_subtype": subtype,
+            "metadata": metadata,
+            "runtime_injected": True,
+        }
+        try:
+            sender("user_message", payload)
+        except Exception:
+            pass
+
+    return raw
+
+
+async def process_multi_agent_master_messages(
+    *,
+    web_terminal,
+    messages,
+    sender,
+    debug_log,
+    inline: bool = False,
+    after_tool_call_id: Optional[str] = None,
+) -> int:
+    """从 MultiAgentState 取出待插入主对话的消息并注入。返回注入条数。"""
+    manager = getattr(web_terminal, "sub_agent_manager", None)
+    ma_debug(
+        "process_ma_messages_enter",
+        multi_agent_mode=getattr(web_terminal, "multi_agent_mode", False),
+        has_manager=bool(manager),
+        manager_id=id(manager) if manager else None,
+        conversation_id=getattr(getattr(web_terminal, "context_manager", None), "current_conversation_id", None),
+        inline=inline,
+        after_tool_call_id=after_tool_call_id,
+        messages_len_before=len(messages) if messages else 0,
+    )
+    if not getattr(web_terminal, "multi_agent_mode", False):
+        return 0
+    manager = getattr(web_terminal, "sub_agent_manager", None)
+    if not manager:
+        ma_debug("process_ma_messages_no_manager")
+        return 0
+    conversation_id = getattr(getattr(web_terminal, "context_manager", None), "current_conversation_id", None)
+    if not conversation_id:
+        ma_debug("process_ma_messages_no_conversation_id")
+        return 0
+    state = manager.get_multi_agent_state(conversation_id)
+    if not state:
+        ma_debug("process_ma_messages_no_state", conversation_id=conversation_id)
+        return 0
+    ma_debug("process_ma_messages_got_state", conversation_id=conversation_id, state_id=id(state))
+    pending = state.drain_master_messages()
+    if not pending:
+        ma_debug("process_ma_messages_empty", conversation_id=conversation_id, state_id=id(state))
+        return 0
+    debug_log(f"[MultiAgent] draining {len(pending)} pending master messages")
+    ma_debug(
+        "process_multi_agent_master_messages",
+        conversation_id=conversation_id,
+        count=len(pending),
+        previews=[str(m)[:200] for m in pending],
+    )
+    for msg in pending:
+        inject_multi_agent_master_message(
+            web_terminal=web_terminal,
+            messages=messages,
+            text=msg,
+            sender=sender,
+            conversation_id=conversation_id,
+            inline=inline,
+            after_tool_call_id=after_tool_call_id,
+        )
+    return len(pending)
+
+
 async def wait_retry_delay(*, delay_seconds: int, client_sid: str, username: str, sender, get_stop_flag, clear_stop_flag) -> bool:
     """等待重试间隔，同时检查是否收到停止请求。"""
     if delay_seconds <= 0:

server/chat_flow_tool_loop.py

@@ -24,7 +24,7 @@ from modules.personalization_manager import load_personalization_config, resolve
 from modules.auto_approval_service import run_auto_approval
 from modules.user_question_manager import format_user_question_answer
 from .deep_compression import run_deep_compression
-from .chat_flow_task_support import inject_runtime_user_message
+from .chat_flow_task_support import inject_runtime_user_message, process_multi_agent_master_messages
 
 
 def _format_numbered_lines(lines: List[str], start_line_no: int) -> List[Dict[str, Any]]:
@@ -261,7 +261,7 @@ async def _wait_for_user_questions(*, question_ids: List[str], username: str, ti
     return answered
 
 
-async def execute_tool_calls(*, web_terminal, tool_calls, sender, messages, client_sid: str, username: str, iteration: int, conversation_id: Optional[str], last_tool_call_time: float, process_sub_agent_updates, process_background_command_updates, maybe_mark_failure_from_message, mark_force_thinking, get_stop_flag, clear_stop_flag, workspace=None):
+async def execute_tool_calls(*, web_terminal, tool_calls, sender, messages, client_sid: str, username: str, iteration: int, conversation_id: Optional[str], last_tool_call_time: float, process_sub_agent_updates, process_background_command_updates, process_multi_agent_master_messages=process_multi_agent_master_messages, maybe_mark_failure_from_message, mark_force_thinking, get_stop_flag, clear_stop_flag, workspace=None):
     previous_tool_loop_active = getattr(web_terminal, "_tool_loop_active", False)
     web_terminal._tool_loop_active = True
     allowed_tool_names = set()
@@ -1323,6 +1323,14 @@ async def execute_tool_calls(*, web_terminal, tool_calls, sender, messages, clie
             debug_log=debug_log,
             maybe_mark_failure_from_message=maybe_mark_failure_from_message,
         )
+        await process_multi_agent_master_messages(
+            messages=messages,
+            inline=True,
+            after_tool_call_id=last_completed_tool_call_id,
+            web_terminal=web_terminal,
+            sender=sender,
+            debug_log=debug_log,
+        )
 
     # 运行期模式通知：必须等待同一轮全部 tool_call 都完成后再注入，
     # 避免在 assistant.tool_calls 与对应 tool 消息之间插入 user 消息导致 API 报错。

server/context.py

@@ -180,9 +180,9 @@ def get_user_resources(
         data_dir.mkdir(parents=True, exist_ok=True)
         logs_dir = Path(LOGS_DIR).expanduser().resolve()
         logs_dir.mkdir(parents=True, exist_ok=True)
-        uploads_dir = project_path / ".agents" / "user_upload"
+        uploads_dir = project_path / ".astrion" / "user_upload"
         uploads_dir.mkdir(parents=True, exist_ok=True)
-        skills_dir = project_path / ".agents" / "skills"
+        skills_dir = project_path / ".astrion" / "skills"
         skills_dir.mkdir(parents=True, exist_ok=True)
         quarantine_root = Path(UPLOAD_QUARANTINE_SUBDIR).expanduser()
         if not quarantine_root.is_absolute():
@@ -639,7 +639,7 @@ def ensure_conversation_loaded(
                 ).get("project_path"),
             )
             try:
-                conv_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id) or {}
+                conv_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id) or {}
                 meta = conv_data.get("metadata", {}) or {}
                 run_mode_meta = meta.get("run_mode")
                 if run_mode_meta:

server/conversation.py

@@ -177,7 +177,9 @@ def _get_active_workspace_task(username: str, workspace_id: str):
 def _build_safe_load_result(terminal: WebTerminal, conversation_id: str) -> Dict[str, Any]:
     """只读取对话元数据，不调用 terminal.load_conversation，避免修改运行任务正在使用的上下文。"""
     normalized_id = _normalize_conv_id(conversation_id)
-    cm = getattr(getattr(terminal, "context_manager", None), "conversation_manager", None)
+    ctx_manager = getattr(terminal, "context_manager", None)
+    # 用 _get_conversation_manager_for_id 自动判断对话属于普通管理器还是多智能体管理器
+    cm = ctx_manager._get_conversation_manager_for_id(normalized_id) if ctx_manager else None
     data = cm.load_conversation(normalized_id) if cm else None
     if not data:
         return {
@@ -275,7 +277,7 @@ def _atomic_write_input_draft(path: Path, payload: Dict[str, Any]) -> None:
 
 def _get_conversation_versioning_meta(terminal: WebTerminal, conversation_id: str) -> Dict[str, Any]:
     normalized = _normalize_conv_id(conversation_id)
-    data = terminal.context_manager.conversation_manager.load_conversation(normalized) or {}
+    data = terminal.context_manager._get_conversation_manager_for_id(normalized).load_conversation(normalized) or {}
     meta = data.get("metadata") or {}
     versioning = meta.get("versioning") or {}
     if not isinstance(versioning, dict):
@@ -316,7 +318,7 @@ def _ensure_conversation_versioning_enabled(
     manager = _get_conv_versioning_manager(workspace, normalized_id)
     normalized_tracking_mode = _normalize_versioning_tracking_mode(tracking_mode or default_mode)
     meta = manager.set_enabled(enabled=True, mode="overwrite", tracking_mode=normalized_tracking_mode)
-    conv_data = terminal.context_manager.conversation_manager.load_conversation(normalized_id) or {}
+    conv_data = terminal.context_manager._get_conversation_manager_for_id(normalized_id).load_conversation(normalized_id) or {}
     snapshot_payload = {
         "conversation_id": normalized_id,
         "title": conv_data.get("title"),
@@ -372,7 +374,7 @@ def _update_conversation_versioning_meta(
         payload["versioning"]["last_commit"] = last_commit
     if last_input_seq is not None:
         payload["versioning"]["last_input_seq"] = int(last_input_seq)
-    return terminal.context_manager.conversation_manager.update_conversation_metadata(normalized, payload)
+    return terminal.context_manager._get_conversation_manager_for_id(normalized).update_conversation_metadata(normalized, payload)
 
 
 @conversation_bp.route('/api/input-draft', methods=['GET'])
@@ -525,6 +527,14 @@ def get_conversations(terminal: WebTerminal, workspace: UserWorkspace, username:
         limit = request.args.get('limit', 20, type=int)
         offset = request.args.get('offset', 0, type=int)
         non_empty = request.args.get('non_empty', '0') in ('1', 'true', 'True')
+        # multi_agent_mode: '1' 仅多智能体模式对话；'0' 仅常规对话；未传 None 不过滤
+        ma_param = request.args.get('multi_agent_mode', None)
+        if ma_param in ('1', 'true', 'True'):
+            multi_agent_filter: Optional[bool] = True
+        elif ma_param in ('0', 'false', 'False'):
+            multi_agent_filter = False
+        else:
+            multi_agent_filter = None
         target_workspace_id = request.args.get('workspace_id', '', type=str).strip()
 
         # 限制参数范围
@@ -541,7 +551,7 @@ def get_conversations(terminal: WebTerminal, workspace: UserWorkspace, username:
             except RuntimeError as exc:
                 return jsonify({"success": False, "error": str(exc)}), 503
 
-        result = terminal.get_conversations_list(limit=limit, offset=offset, non_empty=non_empty)
+        result = terminal.get_conversations_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=multi_agent_filter)
         cm = getattr(getattr(terminal, "context_manager", None), "conversation_manager", None)
         write_host_workspace_debug(
             "sidebar-debug-api",
@@ -590,6 +600,7 @@ def create_conversation(terminal: WebTerminal, workspace: UserWorkspace, usernam
         thinking_mode = data.get('thinking_mode') if preserve_mode and 'thinking_mode' in data else None
         run_mode = data.get('mode') if preserve_mode and 'mode' in data else None
         target_workspace_id = (data.get('workspace_id') or '').strip()
+        multi_agent_mode = bool(data.get('multi_agent_mode'))
 
         if target_workspace_id:
             try:
@@ -633,6 +644,7 @@ def create_conversation(terminal: WebTerminal, workspace: UserWorkspace, usernam
                 metadata_overrides={
                     "permission_mode": default_permission_mode or getattr(terminal, "get_permission_mode", lambda: "unrestricted")(),
                     "execution_mode": getattr(terminal, "get_execution_mode", lambda: "sandbox")(),
+                    "multi_agent_mode": multi_agent_mode,
                 },
             )
             try:
@@ -646,7 +658,11 @@ def create_conversation(terminal: WebTerminal, workspace: UserWorkspace, usernam
                 "safe_navigation": True,
             }
         else:
-            result = terminal.create_new_conversation(thinking_mode=thinking_mode, run_mode=run_mode)
+            result = terminal.create_new_conversation(
+                thinking_mode=thinking_mode,
+                run_mode=run_mode,
+                metadata_overrides={"multi_agent_mode": multi_agent_mode} if multi_agent_mode else None,
+            )
 
         if result["success"]:
             # 仅在当前工作区创建时更新 session 模式；指定其他工作区时由前端切换后自动同步。
@@ -696,7 +712,7 @@ def get_conversation_info(terminal: WebTerminal, workspace: UserWorkspace, usern
     """获取特定对话信息"""
     try:
         # 通过ConversationManager直接获取对话数据
-        conversation_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id)
+        conversation_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id)
         
         if conversation_data:
             # 提取关键信息，不返回完整消息内容（避免数据量过大）
@@ -826,7 +842,8 @@ def load_conversation(conversation_id, terminal: WebTerminal, workspace: UserWor
                 result_message=result.get("message", ""),
                 not_found=True,
             )
-            return jsonify(result), 404 if "不存在" in result.get("message", "") else 500
+            status_code = 404 if "不存在" in result.get("message", "") else 500
+            return jsonify(result), status_code
 
     except Exception as e:
         import traceback
@@ -936,7 +953,7 @@ def get_conversation_messages(conversation_id, terminal: WebTerminal, workspace:
     """获取对话的消息历史（可选功能，用于调试或详细查看）"""
     try:
         # 获取完整对话数据
-        conversation_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id)
+        conversation_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id)
         
         if conversation_data:
             messages = conversation_data.get("messages", [])
@@ -1058,7 +1075,7 @@ def update_conversation_versioning(conversation_id, terminal: WebTerminal, works
         manager = _get_conv_versioning_manager(workspace, normalized_id)
         meta = manager.set_enabled(enabled=enabled, mode=mode, tracking_mode=tracking_mode)
         if enabled:
-            conv_data = terminal.context_manager.conversation_manager.load_conversation(normalized_id) or {}
+            conv_data = terminal.context_manager._get_conversation_manager_for_id(normalized_id).load_conversation(normalized_id) or {}
             snapshot_payload = {
                 "conversation_id": normalized_id,
                 "title": conv_data.get("title"),
@@ -1601,7 +1618,7 @@ def compress_conversation(conversation_id, terminal: WebTerminal, workspace: Use
 def get_conversation_compression_status(conversation_id, terminal: WebTerminal, workspace: UserWorkspace, username: str):
     try:
         normalized_id = conversation_id if conversation_id.startswith('conv_') else f"conv_{conversation_id}"
-        data = terminal.context_manager.conversation_manager.load_conversation(normalized_id) or {}
+        data = terminal.context_manager._get_conversation_manager_for_id(normalized_id).load_conversation(normalized_id) or {}
         meta = data.get("metadata", {}) or {}
         return jsonify({
             "success": True,
@@ -1625,9 +1642,9 @@ def get_conversation_compression_status(conversation_id, terminal: WebTerminal,
 def cancel_conversation_compression(conversation_id, terminal: WebTerminal, workspace: UserWorkspace, username: str):
     try:
         normalized_id = conversation_id if conversation_id.startswith('conv_') else f"conv_{conversation_id}"
-        ok = terminal.context_manager.conversation_manager.update_conversation_metadata(
-            normalized_id,
-            {
+        ok = terminal.context_manager._get_conversation_manager_for_id(
+            normalized_id).update_conversation_metadata(
+            normalized_id, {
                 "compression_in_progress": False,
                 "compression_mode": None,
                 "compression_stage": None,
@@ -1658,12 +1675,26 @@ def list_sub_agents(terminal: WebTerminal, workspace: UserWorkspace, username: s
             pass
         conversation_id = terminal.context_manager.current_conversation_id
         data = manager.get_overview(conversation_id=conversation_id)
-        if not data:
-            # 若当前对话暂无数据但存在运行中子智能体，回退为全局运行态，避免面板空白
+
+        # 传统模式子智能体列表必须排除多智能体任务，避免 /new 等无当前对话场景
+        # 把最近一次多智能体模式的 running/idle 子智能体串过来。
+        def _is_multi_agent_task(item: dict) -> bool:
+            task_id = item.get("task_id")
+            raw_task = manager.tasks.get(task_id) if task_id else None
+            return bool(raw_task.get("multi_agent_mode")) if isinstance(raw_task, dict) else False
+
+        data = [item for item in data if not _is_multi_agent_task(item)]
+
+        # 仅在未绑定具体对话时（如全新会话尚未创建 conversation_id），才回退为全局运行态；
+        # 否则只显示当前对话关联的子智能体，避免新对话看到其他对话的任务。
+        if not data and not conversation_id:
             all_overview = manager.get_overview(conversation_id=None)
             if all_overview:
                 terminal_statuses = TERMINAL_STATUSES.union({"terminated"})
-                running_only = [item for item in all_overview if item.get("status") not in terminal_statuses]
+                running_only = [
+                    item for item in all_overview
+                    if item.get("status") not in terminal_statuses and not _is_multi_agent_task(item)
+                ]
                 if running_only:
                     data = running_only
         debug_log(
@@ -1790,6 +1821,55 @@ def get_sub_agent_activity(task_id: str, terminal: WebTerminal, workspace: UserW
         return jsonify({"success": False, "error": str(exc)}), 500
 
 
+@conversation_bp.route('/api/sub_agents/stop_all', methods=['POST'])
+@api_login_required
+@with_terminal
+def stop_all_sub_agents(terminal: WebTerminal, workspace: UserWorkspace, username: str):
+    """批量停止当前会话的所有非终态子智能体。
+
+    body: {"mode": "terminate" | "soft_stop"}
+      - mode=terminate: 传统模式终结子智能体（重、不保留实例）
+      - mode=soft_stop: 多智能体模式软停止（轻、保留实例可被后续唤醒）
+    """
+    data = request.get_json(silent=True) or {}
+    mode = str(data.get('mode') or 'terminate').strip().lower()
+    if mode not in {'terminate', 'soft_stop'}:
+        return jsonify({"success": False, "error": "mode 只支持 terminate/soft_stop"}), 400
+    manager = getattr(terminal, 'sub_agent_manager', None)
+    if not manager:
+        return jsonify({"success": False, "error": "子智能体管理器不可用"}), 404
+    conversation_id = terminal.context_manager.current_conversation_id
+    try:
+        try:
+            manager._load_state()
+        except Exception:
+            pass
+        manager.reconcile_task_states(conversation_id=conversation_id)
+        stopped_count = 0
+        if mode == 'soft_stop':
+            stopped_count = manager.soft_stop_all_agents(conversation_id)
+            debug_log(f"[StopAllSubAgents] soft_stop 会话={conversation_id}, 计数={stopped_count}")
+        else:
+            # terminate: 遍历所有非终态子智能体逐个终结
+            from modules.sub_agent.state import TERMINAL_STATUSES
+            for task_info in list(manager.tasks.values()):
+                if task_info.get('conversation_id') != conversation_id:
+                    continue
+                status = task_info.get('status')
+                if status in TERMINAL_STATUSES.union({"terminated"}):
+                    continue
+                try:
+                    tid = task_info.get('task_id')
+                    manager.terminate_sub_agent(task_id=tid)
+                    stopped_count += 1
+                    debug_log(f"[StopAllSubAgents] terminated task_id={tid}")
+                except Exception as exc:
+                    debug_log(f"[StopAllSubAgents] 终止失败 tid={task_info.get('task_id')}, err={exc}")
+        return jsonify({"success": True, "data": {"stopped_count": stopped_count, "mode": mode}})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
 @conversation_bp.route('/api/sub_agents/<task_id>/terminate', methods=['POST'])
 @api_login_required
 @with_terminal
@@ -1993,7 +2073,7 @@ def review_conversation_preview(conversation_id, terminal: WebTerminal, workspac
                 "message": "无法引用当前对话"
             }), 400
 
-        conversation_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id)
+        conversation_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id)
         if not conversation_data:
             return jsonify({
                 "success": False,
@@ -2036,7 +2116,7 @@ def review_conversation(conversation_id, terminal: WebTerminal, workspace: UserW
                 "message": "无法引用当前对话"
             }), 400
 
-        conversation_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id)
+        conversation_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id)
         if not conversation_data:
             return jsonify({
                 "success": False,
@@ -2049,7 +2129,7 @@ def review_conversation(conversation_id, terminal: WebTerminal, workspace: UserW
         content = "\n".join(lines) + "\n"
         char_count = len(content)
 
-        review_dir = workspace.project_path / ".agents" / "review"
+        review_dir = workspace.project_path / ".astrion" / "review"
         review_dir.mkdir(parents=True, exist_ok=True)
 
         title = conversation_data.get("title") or "untitled"
@@ -2118,7 +2198,7 @@ def get_current_conversation(terminal: WebTerminal, workspace: UserWorkspace, us
     
     # 如果是真实的对话ID，查找对话数据
     try:
-        conversation_data = terminal.context_manager.conversation_manager.load_conversation(current_id)
+        conversation_data = terminal.context_manager._get_conversation_manager_for_id(current_id).load_conversation(current_id)
         if conversation_data:
             metadata = conversation_data.get("metadata", {}) or {}
             return jsonify({

server/deep_compression.py

@@ -246,7 +246,7 @@ def _write_compact_file(
     latest_user_input: str,
     previous_records: List[Dict[str, Any]],
 ) -> str:
-    compact_dir = project_path / ".agents" / "compact_result"
+    compact_dir = project_path / ".astrion" / "compact_result"
     compact_dir.mkdir(parents=True, exist_ok=True)
     filename = f"compact_{datetime.now().strftime('%Y%m%d_%H%M%S')}_{compression_index:03d}.md"
     file_path = compact_dir / filename
@@ -312,7 +312,12 @@ async def run_deep_compression(
     sender=None,
 ) -> Dict[str, Any]:
     cm = web_terminal.context_manager
-    conv_data = cm.conversation_manager.load_conversation(conversation_id)
+    target_manager = (
+        cm._get_conversation_manager_for_id(conversation_id)
+        if hasattr(cm, "_get_conversation_manager_for_id")
+        else cm.conversation_manager
+    )
+    conv_data = target_manager.load_conversation(conversation_id)
     if not conv_data:
         return {"success": False, "error": f"对话不存在: {conversation_id}"}
 
@@ -419,7 +424,7 @@ async def run_deep_compression(
     # 关键：重置 current_context_tokens，避免自动压缩续接后阈值判断仍读到压缩前的大值而陷入死循环。
     # 真实上下文长度会在下一次 API 响应后被重新写入。
     try:
-        cm.conversation_manager.update_token_statistics(
+        target_manager.update_token_statistics(
             conversation_id,
             input_tokens=0,
             output_tokens=0,
@@ -484,7 +489,7 @@ async def run_deep_compression(
     }
     for frozen_key in REBUILD_FROZEN_KEYS:
         meta_updates[frozen_key] = None
-    cm.conversation_manager.update_conversation_metadata(conversation_id, meta_updates)
+    target_manager.update_conversation_metadata(conversation_id, meta_updates)
     # 同步内存中的 metadata，清除 frozen 缓存
     try:
         if getattr(cm, "current_conversation_id", None) == conversation_id and isinstance(cm.conversation_metadata, dict):

server/multi_agent.py

@@ -0,0 +1,409 @@
+"""多智能体模式 server 路由。
+
+- `/multiagent/new` 返回主 SPA 入口（与 `/new` 一样返回 static/index.html）
+  前端通过路径识别多智能体模式后，在创建对话时写入 metadata.multi_agent_mode=true
+- `/api/multiagent/conversations` POST 创建多智能体对话（写入 metadata）
+- `/api/multiagent/roles` GET 列出可用角色
+- `/api/multiagent/roles` POST 创建自定义角色
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List
+
+from flask import Blueprint, current_app, jsonify, request, session
+
+from server.auth_helpers import api_login_required, login_required, get_current_username
+from server.context import get_user_resources
+from modules.multi_agent.role_store import (
+    RoleConfig,
+    list_roles,
+    load_preset_role,
+    save_custom_role,
+    delete_custom_role,
+    is_preset_role,
+    sync_preset_roles,
+)
+from config.paths import CUSTOM_ROLES_DIR, WEB_PRESET_ROLES_DIR
+
+multi_agent_bp = Blueprint("multi_agent", __name__)
+
+
+@multi_agent_bp.route("/multiagent/new")
+@login_required
+def multi_agent_new_page():
+    """多智能体模式入口，返回与 /new 相同的 SPA index.html。"""
+    return current_app.send_static_file("index.html")
+
+
+@multi_agent_bp.route("/multiagent/<path:conversation_id>")
+@login_required
+def multi_agent_conversation_page(conversation_id: str):
+    """多智能体模式 指定会话 URL，返回 SPA index.html 让前端路由处理。"""
+    return current_app.send_static_file("index.html")
+
+
+@multi_agent_bp.route("/api/multiagent/rebuild-index", methods=["POST"])
+@api_login_required
+def rebuild_conversation_index_api():
+    """强制从磁盘重建对话索引，补全 multi_agent_mode 等新字段。"""
+    try:
+        username = get_current_username()
+        if not username:
+            return jsonify({"success": False, "error": "未登录"}), 401
+        terminal, _ = get_user_resources(username)
+        if not terminal:
+            return jsonify({"success": False, "error": "工作区未就绪"}), 503
+        ctx_manager = getattr(terminal, "context_manager", None)
+        if not ctx_manager:
+            return jsonify({"success": False, "error": "上下文管理器未初始化"}), 503
+        ma_manager = getattr(ctx_manager, "multi_agent_conversation_manager", None)
+        if not ma_manager:
+            return jsonify({"success": False, "error": "多智能体对话管理器未初始化"}), 503
+        rebuilt = ma_manager._rebuild_index_from_files()
+        ma_manager._save_index(rebuilt)
+        return jsonify({"success": True, "index_size": len(rebuilt)})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+def _get_role_dirs() -> tuple:
+    """根据 session 判断当前登录模式，返回 (runtime_dir, custom_dir)。
+
+    - host 模式：runtime_dir = custom_dir = host/mutiagents/agents
+    - web/docker 模式：runtime_dir = web/mutiagents/agents, custom_dir = users/<user>/personal/mutiagents/agents
+    """
+    from flask import session as _session
+    is_host_session = bool(_session.get('host_mode'))
+    if is_host_session:
+        return CUSTOM_ROLES_DIR, CUSTOM_ROLES_DIR
+    # web 模式
+    username = get_current_username()
+    if not username:
+        return WEB_PRESET_ROLES_DIR, None
+    _, workspace = get_user_resources(username)
+    if not workspace or not workspace.data_dir:
+        return WEB_PRESET_ROLES_DIR, None
+    from modules.multi_agent.role_store import infer_custom_roles_dir
+    custom = infer_custom_roles_dir(workspace.data_dir)
+    return WEB_PRESET_ROLES_DIR, str(custom) if custom else None
+
+
+@multi_agent_bp.route("/api/multiagent/roles", methods=["GET"])
+@api_login_required
+def list_roles_api():
+    """列出全部可用角色（预置+用户自定义）。"""
+    try:
+        runtime_dir, custom_dir = _get_role_dirs()
+        roles = list_roles(runtime_dir=runtime_dir, custom_dir=custom_dir)
+        return jsonify({
+            "success": True,
+            "roles": [r.to_dict() for r in roles],
+        })
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/roles", methods=["POST"])
+@api_login_required
+def create_role_api():
+    """创建自定义角色。body: { role_id, name, description?, body_prompt, thinking_mode? }"""
+    try:
+        data = request.get_json() or {}
+        role_id = str(data.get("role_id") or "").strip()
+        name = str(data.get("name") or "").strip()
+        body_prompt = str(data.get("body_prompt") or "").strip()
+        description = str(data.get("description") or "").strip()
+        thinking_mode = str(data.get("thinking_mode") or "fast").strip()
+        model_key = str(data.get("model_key") or "").strip() or None
+        if not role_id or not name or not body_prompt:
+            return jsonify({"success": False, "error": "role_id/name/body_prompt 必填"}), 400
+        if thinking_mode not in {"fast", "thinking"}:
+            thinking_mode = "fast"
+        # 不允许覆盖预设角色
+        if is_preset_role(role_id):
+            return jsonify({"success": False, "error": f"不能覆盖预设角色 {role_id}"}), 409
+        # 不允许覆盖已存在的用户自定义角色
+        runtime_dir, custom_dir = _get_role_dirs()
+        existing = {r.role_id for r in list_roles(runtime_dir=runtime_dir, custom_dir=custom_dir)}
+        if role_id in existing:
+            return jsonify({"success": False, "error": f"角色 {role_id} 已存在"}), 409
+        role = RoleConfig(
+            role_id=role_id,
+            name=name,
+            description=description,
+            body_prompt=body_prompt,
+            thinking_mode=thinking_mode,
+            model_key=model_key,
+            is_custom=True,
+        )
+        saved = save_custom_role(role, custom_dir=custom_dir)
+        return jsonify({"success": True, "role_id": role_id, "file": str(saved)})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/roles/<role_id>", methods=["PUT"])
+@api_login_required
+def update_role_api(role_id: str):
+    """更新用户自定义角色。不能更新预设角色。"""
+    try:
+        data = request.get_json() or {}
+        runtime_dir, custom_dir = _get_role_dirs()
+        # 加载现有角色（先查自定义覆盖，再查预设）
+        role = load_preset_role(role_id, runtime_dir=runtime_dir, custom_dir=custom_dir)
+        if not role:
+            return jsonify({"success": False, "error": f"角色 {role_id} 不存在"}), 404
+        # 更新字段
+        if "name" in data:
+            role.name = str(data["name"]).strip() or role.name
+        if "description" in data:
+            role.description = str(data["description"] or "").strip()
+        if "body_prompt" in data:
+            role.body_prompt = str(data["body_prompt"] or "").strip()
+        if "thinking_mode" in data:
+            tm = str(data["thinking_mode"] or "fast").strip()
+            if tm in {"fast", "thinking"}:
+                role.thinking_mode = tm
+        if "model_key" in data:
+            role.model_key = str(data["model_key"] or "").strip() or None
+        if "skills" in data:
+            role.skills = list(data["skills"] or [])
+        role.is_custom = True
+        saved = save_custom_role(role, custom_dir=custom_dir)
+        return jsonify({"success": True, "role_id": role_id, "file": str(saved)})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/roles/<role_id>", methods=["DELETE"])
+@api_login_required
+def delete_role_api(role_id: str):
+    """删除用户自定义角色。不能删除预设角色。"""
+    try:
+        if is_preset_role(role_id):
+            return jsonify({"success": False, "error": f"不能删除预设角色 {role_id}"}), 403
+        _, custom_dir = _get_role_dirs()
+        deleted = delete_custom_role(role_id, custom_dir=custom_dir)
+        if not deleted:
+            return jsonify({"success": False, "error": f"角色 {role_id} 不存在或无法删除"}), 404
+        return jsonify({"success": True, "role_id": role_id})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/settings", methods=["GET"])
+@api_login_required
+def get_multi_agent_settings_api():
+    """获取多智能体模式设置（子智能体压缩阈值等）。"""
+    try:
+        username = get_current_username()
+        if not username:
+            return jsonify({"success": False, "error": "未登录"}), 401
+        _, workspace = get_user_resources(username)
+        if not workspace:
+            return jsonify({"success": False, "error": "工作区未就绪"}), 503
+        # 从个人化配置中读取子智能体压缩阈值
+        from modules.personalization_manager import load_personalization_config
+        prefs = load_personalization_config(workspace.data_dir) or {}
+        compress_threshold = prefs.get("sub_agent_compress_threshold_tokens", 150000)
+        return jsonify({
+            "success": True,
+            "settings": {
+                "sub_agent_compress_threshold_tokens": compress_threshold,
+            },
+        })
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/settings", methods=["PUT"])
+@api_login_required
+def update_multi_agent_settings_api():
+    """更新多智能体模式设置。"""
+    try:
+        username = get_current_username()
+        if not username:
+            return jsonify({"success": False, "error": "未登录"}), 401
+        _, workspace = get_user_resources(username)
+        if not workspace:
+            return jsonify({"success": False, "error": "工作区未就绪"}), 503
+        data = request.get_json() or {}
+        settings = data.get("settings") or {}
+        # 更新子智能体压缩阈值
+        threshold = settings.get("sub_agent_compress_threshold_tokens")
+        if threshold is not None:
+            threshold = int(threshold)
+            if threshold < 10000:
+                return jsonify({"success": False, "error": "压缩阈值不能小于 10000"}), 400
+            from modules.personalization_manager import load_personalization_config, save_personalization_config
+            prefs = load_personalization_config(workspace.data_dir) or {}
+            prefs["sub_agent_compress_threshold_tokens"] = threshold
+            save_personalization_config(workspace.data_dir, prefs)
+        return jsonify({"success": True})
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/conversations", methods=["POST"])
+@api_login_required
+def create_multi_agent_conversation():
+    """创建多智能体模式对话。在 metadata 中写入 multi_agent_mode=true。
+
+    body: { workspace_id?, thinking_mode?, run_mode?, preserve_mode? }
+    """
+    import time as _time
+    from server.conversation import _get_active_workspace_task, _resolve_target_terminal_for_workspace
+    from modules.personalization_manager import load_personalization_config
+    try:
+        from server.user_workspace import UserWorkspace  # noqa
+    except Exception:
+        UserWorkspace = None  # type: ignore
+
+    username = get_current_username()
+    if not username:
+        return jsonify({"success": False, "error": "未登录"}), 401
+
+    data = request.get_json() or {}
+    target_workspace_id = (data.get("workspace_id") or "").strip()
+
+    terminal, workspace = get_user_resources(username)
+    if not terminal or not workspace:
+        return jsonify({"success": False, "error": "工作区未就绪"}), 503
+
+    if target_workspace_id:
+        try:
+            terminal, workspace = _resolve_target_terminal_for_workspace(
+                username, target_workspace_id, terminal, workspace
+            )
+        except ValueError as exc:
+            return jsonify({"success": False, "error": str(exc)}), 404
+        except RuntimeError as exc:
+            return jsonify({"success": False, "error": str(exc)}), 503
+
+    preserve_mode = bool(data.get("preserve_mode"))
+    thinking_mode = data.get("thinking_mode") if preserve_mode and "thinking_mode" in data else None
+    run_mode = data.get("mode") if preserve_mode and "mode" in data else None
+
+    effective_workspace_id = target_workspace_id or session.get("workspace_id") or "default"
+    active_task = _get_active_workspace_task(username=username, workspace_id=effective_workspace_id)
+
+    try:
+        prefs = load_personalization_config(workspace.data_dir)
+    except Exception:
+        prefs = {}
+
+    ctx_manager = getattr(terminal, "context_manager", None)
+    if not ctx_manager:
+        return jsonify({"success": False, "error": "上下文管理器未初始化"}), 500
+    cm = getattr(ctx_manager, "multi_agent_conversation_manager", None) or getattr(ctx_manager, "conversation_manager", None)
+    if not cm:
+        return jsonify({"success": False, "error": "对话管理器未初始化"}), 500
+
+    safe_run_mode = run_mode
+    if safe_run_mode not in {"fast", "thinking", "deep"}:
+        candidate = (prefs or {}).get("default_run_mode")
+        safe_run_mode = candidate if candidate in {"fast", "thinking", "deep"} else "fast"
+    safe_thinking = bool(thinking_mode) if thinking_mode is not None else safe_run_mode != "fast"
+    default_permission_mode = (prefs or {}).get("default_permission_mode")
+    if default_permission_mode not in ("readonly", "approval", "auto_approval", "unrestricted"):
+        default_permission_mode = None
+
+    previous_cm_current = getattr(ctx_manager, "current_conversation_id", None)
+
+    conversation_id = cm.create_conversation(
+        project_path=str(workspace.project_path),
+        thinking_mode=safe_thinking,
+        run_mode=safe_run_mode,
+        initial_messages=[],
+        model_key=(prefs or {}).get("default_model") or getattr(terminal, "model_key", None),
+        metadata_overrides={
+            "permission_mode": default_permission_mode or getattr(terminal, "get_permission_mode", lambda: "unrestricted")(),
+            "execution_mode": getattr(terminal, "get_execution_mode", lambda: "sandbox")(),
+            "multi_agent_mode": True,
+        },
+    )
+    # 恢复 context_manager 的当前对话（不要影响普通对话的 current_conversation_id）
+    try:
+        ctx_manager.current_conversation_id = previous_cm_current
+    except Exception:
+        pass
+
+    # 触发对话列表更新事件
+    try:
+        from server.app_legacy import socketio
+        socketio.emit('conversation_list_update', {
+            'action': 'created',
+            'conversation_id': conversation_id,
+        }, room=f"user_{username}")
+    except Exception:
+        pass
+
+    return jsonify({
+        "success": True,
+        "conversation_id": conversation_id,
+        "multi_agent_mode": True,
+    }), 201
+
+
+@multi_agent_bp.route("/api/multiagent/models", methods=["GET"])
+@api_login_required
+def list_sub_agent_models_api():
+    """列出子智能体可用的模型列表（从 sub_agent_models.json 读取，脱敏后返回）。"""
+    try:
+        from config.sub_agent import SUB_AGENT_MODELS_CONFIG_FILE
+        from pathlib import Path as _Path
+        import json as _json
+        config_path = SUB_AGENT_MODELS_CONFIG_FILE
+        if not _Path(config_path).exists():
+            return jsonify({"success": True, "models": [], "default_model": ""})
+        raw = _json.loads(_Path(config_path).read_text(encoding="utf-8"))
+        models_raw = raw.get("models", []) if isinstance(raw, dict) else (raw if isinstance(raw, list) else [])
+        default_model = str(raw.get("default_model", "")) if isinstance(raw, dict) else ""
+        # 脱敏：只返回 name / modes / multimodal / max_output / max_context
+        safe_models = []
+        for m in models_raw:
+            if not isinstance(m, dict):
+                continue
+            safe_models.append({
+                "name": m.get("name") or m.get("model_name") or "",
+                "modes": m.get("modes") or m.get("mode") or "",
+                "multimodal": m.get("multimodal") or "none",
+                "max_output": m.get("max_output") or m.get("max_tokens") or 0,
+                "max_context": m.get("max_context") or m.get("context_window") or 0,
+            })
+        return jsonify({
+            "success": True,
+            "models": safe_models,
+            "default_model": default_model,
+        })
+    except Exception as exc:
+        return jsonify({"success": False, "error": str(exc)}), 500
+
+
+@multi_agent_bp.route("/api/multiagent/active_sub_agents", methods=["GET"])
+@api_login_required
+def list_active_sub_agents_api():
+    """查询当前会话所有子智能体实例（多智能体模式专用）。"""
+    username = get_current_username()
+    if not username:
+        return jsonify({"success": False, "error": "未登录"}), 401
+    conversation_id = (request.args.get("conversation_id") or "").strip()
+    if not conversation_id:
+        return jsonify({"success": False, "error": "缺少 conversation_id 参数"}), 400
+    terminal, _ = get_user_resources(username)
+    if not terminal:
+        return jsonify({"success": False, "error": "工作区未就绪"}), 503
+    sub_agent_manager = getattr(terminal, "sub_agent_manager", None)
+    if not sub_agent_manager:
+        return jsonify({"success": False, "error": "子智能体管理器未就绪"}), 503
+    state = sub_agent_manager.get_multi_agent_state(conversation_id)
+    if not state:
+        return jsonify({"success": True, "agents": []})
+    return jsonify({
+        "success": True,
+        "agents": [a.to_dict() for a in state.list_all()],
+    })
+
+
+__all__ = ["multi_agent_bp"]

server/socket_handlers.py

@@ -288,7 +288,7 @@ def handle_message(data):
         emit('error', {'message': str(exc)})
         return
     try:
-        conv_data = terminal.context_manager.conversation_manager.load_conversation(conversation_id) or {}
+        conv_data = terminal.context_manager._get_conversation_manager_for_id(conversation_id).load_conversation(conversation_id) or {}
     except Exception:
         conv_data = {}
     title = conv_data.get('title', '新对话')

server/status/base.py

@@ -122,7 +122,7 @@ def get_status(terminal, workspace, username):
         current_conv = terminal.context_manager.current_conversation_id
         status.setdefault('conversation', {})['current_id'] = current_conv
         if current_conv and not current_conv.startswith('temp_'):
-            current_conv_data = terminal.context_manager.conversation_manager.load_conversation(current_conv)
+            current_conv_data = terminal.context_manager._get_conversation_manager_for_id(current_conv).load_conversation(current_conv)
             if current_conv_data:
                 status['conversation']['title'] = current_conv_data.get('title', '未知对话')
                 status['conversation']['created_at'] = current_conv_data.get('created_at')

server/tasks/helpers.py

@@ -83,6 +83,7 @@ def _task_public_payload(rec: TaskRecord, *, include_title: bool = True) -> Dict
         "message_source": (rec.session_data or {}).get("message_source"),
         "goal_mode": bool((rec.session_data or {}).get("goal_mode")),
         "goal_progress": (rec.session_data or {}).get("goal_progress"),
+        "task_type": getattr(rec, "task_type", "chat"),
     }
     if include_title:
         payload["conversation_title"] = _conversation_title_for_task(rec)

server/tasks/models.py

@@ -55,6 +55,7 @@ class TaskRecord:
         "runtime_pending_queue",
         "runtime_guidance_queue",
         "last_cancel_at",
+        "task_type",
     )
 
     def __init__(
@@ -68,6 +69,7 @@ class TaskRecord:
         thinking_mode: Optional[bool],
         run_mode: Optional[str],
         max_iterations: Optional[int],
+        task_type: str = "chat",
     ):
         self.task_id = task_id
         self.username = username
@@ -92,6 +94,7 @@ class TaskRecord:
         self.runtime_pending_queue: List[Dict[str, Any]] = []
         self.runtime_guidance_queue: List[str] = []
         self.last_cancel_at: Optional[float] = None
+        self.task_type = task_type
 
 class TaskManager:
     """线程内存版任务管理器，后续可替换为 Redis/DB。"""
@@ -133,18 +136,22 @@ class TaskManager:
         message_source: Optional[str] = None,
         goal_mode: bool = False,
         skill_context_messages: Optional[List[Dict[str, str]]] = None,
+        task_type: str = "chat",
     ) -> TaskRecord:
         if run_mode:
             normalized = str(run_mode).lower()
             if normalized not in {"fast", "thinking", "deep"}:
                 raise ValueError("run_mode 只支持 fast/thinking/deep")
             run_mode = normalized
-        # 单工作区互斥：禁止同一用户同一工作区并发任务
-        existing = [t for t in self.list_tasks(username, workspace_id) if t.status in {"pending", "running"}]
-        if existing:
-            raise RuntimeError("当前工作区已有运行中的任务，请稍后再试。")
+        normalized_task_type = str(task_type or "chat").strip().lower() or "chat"
+        # 单工作区互斥：普通 chat 任务禁止同一用户同一工作区并发；
+        # notice（通知触发）任务允许与已完成的 chat 任务共存，用于后台通知重入。
+        if normalized_task_type == "chat":
+            existing = [t for t in self.list_tasks(username, workspace_id) if t.status in {"pending", "running"} and getattr(t, "task_type", "chat") == "chat"]
+            if existing:
+                raise RuntimeError("当前工作区已有运行中的任务，请稍后再试。")
         task_id = str(uuid.uuid4())
-        record = TaskRecord(task_id, username, workspace_id, message, conversation_id, model_key, thinking_mode, run_mode, max_iterations)
+        record = TaskRecord(task_id, username, workspace_id, message, conversation_id, model_key, thinking_mode, run_mode, max_iterations, task_type=normalized_task_type)
         # 记录当前 session 快照，便于后台线程内使用
         if session_data is not None:
             snapshot = dict(session_data)
@@ -205,32 +212,39 @@ class TaskManager:
             ]
 
     def cancel_task(self, username: str, task_id: str) -> bool:
+        """取消主智能体任务。只停主智能体，不触碰后台任务。
+
+        后台任务（子智能体、后台指令）的终止/暂停由独立的 API 处理，
+        参见 /api/sub_agents/stop_all 和 /api/background_commands/stop_all。
+        """
         rec = self.get_task(username, task_id)
         if not rec:
             debug_log(f"[TaskCancel] cancel_task 找不到任务: task_id={task_id}")
             return False
 
-        # 立即快照进入时的状态，后续所有两段式判断都用它。
-        # _run_chat_task finally 会在硬取消后并发修改 rec.status，
-        # 如果后面再读会被误判为第二下。
+        task_id = rec.task_id
         status_at_entry = rec.status
 
-        debug_log(
-            f"[TaskCancel] 入口: task_id={task_id}, status={status_at_entry}, "
-            f"conversation_id={rec.conversation_id}, workspace_id={rec.workspace_id}"
-        )
-
-        # 1. 硬取消主 asyncio task（如果引用还在）
+        # 取终端引用（仅用于停止目标模式等副作用）
         entry = stop_flags.get(task_id)
         terminal = None
         if isinstance(entry, dict):
             terminal = entry.get('terminal')
+        if not terminal and rec.workspace_id:
+            try:
+                terminal, _ = get_user_resources(username, rec.workspace_id)
+            except Exception:
+                pass
+
+        debug_log(
+            f"[TaskCancel] 入口: task_id={task_id}, status={status_at_entry}, "
+            f"conv={rec.conversation_id}"
+        )
+
+        # 1. 硬取消主 asyncio task（如果引用还在）
+        if isinstance(entry, dict):
             loop = entry.get('loop')
             task = entry.get('task')
-            debug_log(
-                f"[TaskCancel] stop_flags entry: loop_exists={loop is not None}, "
-                f"task_exists={task is not None}, task_done={task.done() if task else 'n/a'}"
-            )
             if loop and task and not task.done():
                 try:
                     loop.call_soon_threadsafe(task.cancel)
@@ -239,14 +253,12 @@ class TaskManager:
                     debug_log(f"[TaskCancel] 硬取消失败: task_id={task_id}, error={exc}")
             entry['stop'] = True
         else:
-            debug_log(f"[TaskCancel] stop_flags 无 entry，设软标志: task_id={task_id}")
             stop_flags[task_id] = {'stop': True, 'task': None, 'terminal': None, 'loop': None}
             entry = stop_flags[task_id]
 
         rec.stop_requested = True
 
         # 2. 停止目标模式
-        workspace = None
         if rec.workspace_id:
             try:
                 _, workspace = get_user_resources(username, rec.workspace_id)
@@ -263,69 +275,19 @@ class TaskManager:
             rec.runtime_guidance_queue = []
             rec.updated_at = time.time()
 
-        # 4. 两段式停止：严格按进入时的 rec.status 判断（快照），不依赖 task.done() 的异步时机。
-        #    原因：投递硬取消后 _run_chat_task finally 可能并发把 status 改成 cancel_requested，
-        #    若此时再读 rec.status 会误判为第二下，导致第一下就误杀后台。
-        #    - 第一下（running/pending）：只硬取消主智能体并置为 cancel_requested，保留后台任务。
-        #    - 第二下（cancel_requested/stopped/canceled）：清理后台任务并置为 stopped。
-        #    - 额外保护：极短时间内（<500ms）的重复 cancel 请求视为抖动，不执行第二下。
+        # 4. 标记为 cancel_requested。
+        #    _run_chat_task finally 会并发把 status 改为 stopped 并发 task_stopped 事件。
+        #    此处仅做软标记，不强制覆盖 finally 即将设的终态。
         now = time.time()
-        is_first_press = status_at_entry in {"running", "pending"}
-
-        if not terminal and rec.workspace_id:
-            try:
-                terminal, _ = get_user_resources(username, rec.workspace_id)
-            except Exception as exc:
-                debug_log(f"[TaskCancel] 取消任务时重新获取 terminal 失败: {exc}")
-
-        if is_first_press:
-            # 第一下：主智能体仍在跑，只请求取消，保留后台任务。
-            # 注意 1：不要清空 rec.events，否则 _run_chat_task finally 发送的
-            # task_stopped 事件会被丢弃，前端无法感知并弹提示。
-            # 注意 2：_run_chat_task finally 可能并发先执行并把 status 设为 stopped，
-            # 此时不要再覆盖回 cancel_requested。
-            with self._lock:
-                if rec.status in {"running", "pending"}:
-                    rec.status = "cancel_requested"
-                rec.updated_at = now
-                rec.last_cancel_at = now
-            debug_log(
-                f"[TaskCancel] 第一下：请求取消智能体，保留后台任务: "
-                f"task_id={task_id}, status_at_entry={status_at_entry}, "
-                f"current_status={rec.status}"
-            )
-            return True
-
-        # 第二下：清理后台任务（过滤 500ms 内的重复请求）
-        if rec.last_cancel_at is not None and (now - rec.last_cancel_at) < 0.5:
-            debug_log(
-                f"[TaskCancel] 忽略 500ms 内重复取消请求: task_id={task_id}, "
-                f"elapsed={now - rec.last_cancel_at:.3f}s"
-            )
-            return True
-
-        has_running_background = self._cleanup_background_tasks(rec, terminal)
         with self._lock:
-            rec.status = "stopped"
-            rec.updated_at = time.time()
-            rec.last_cancel_at = time.time()
-            rec.events.clear()
+            if rec.status in {"running", "pending"}:
+                rec.status = "cancel_requested"
+            rec.updated_at = now
+            rec.last_cancel_at = now
         debug_log(
-            f"[TaskCancel] 第二下：清理后台并停止: task_id={task_id}, "
-            f"has_running_background={has_running_background}"
+            f"[TaskCancel] 已取消主智能体: task_id={task_id}, "
+            f"status_at_entry={status_at_entry}, current_status={rec.status}"
         )
-        try:
-            from server.extensions import socketio
-            socketio.emit('task_stopped', {
-                'message': '任务已停止',
-                'reason': 'user_requested',
-                'task_id': task_id,
-                'conversation_id': rec.conversation_id,
-                'has_running_sub_agents': False,
-                'has_running_background_commands': False,
-            }, room=f"user_{username}")
-        except Exception as exc:
-            debug_log(f"[TaskCancel] 发送 task_stopped 事件失败: {exc}")
         return True
 
     @staticmethod

static/src/App.vue

@@ -63,6 +63,8 @@
           :icon-style="iconStyle"
           :format-time="formatTime"
           :running-tasks="runningWorkspaceTasks"
+          :current-task-in-progress="taskInProgress"
+          :current-conversation-id="currentConversationId"
           :current-workspace-id="currentHostWorkspaceId"
           :display-mode="chatDisplayMode"
           :display-mode-disabled="displayModeSwitchDisabled"
@@ -279,7 +281,7 @@
               :input-is-multiline="inputIsMultiline"
               :input-is-focused="inputIsFocused"
               :is-connected="isConnected"
-              :streaming-message="composerStreamingForInput"
+              :streaming-message="streamingUi"
               :input-locked="displayLockEngaged"
               :uploading="uploading"
               :media-uploading="mediaUploading"
@@ -328,8 +330,13 @@
               :goal-mode-armed="goalModeArmed"
               :goal-running="goalRunning"
               :goal-progress="goalProgress"
+              :multi-agent-mode="multiAgentMode"
+              :has-running-task="composerBusy || anyWorkspaceHasRunningTask"
+              :main-chat-idle="mainChatIdle"
+              :active-sub-agent-count="activeSubAgentCount"
               :avatar-status="showStatusAvatar && messages.length > 0 ? avatarStatus : null"
               @restore-user-question="restoreUserQuestionDialog"
+              @stop-all-sub-agents="handleStopAllSubAgents"
               @update:input-message="inputSetMessage"
               @input-change="handleInputChange"
               @input-focus="handleInputFocus"
@@ -366,6 +373,7 @@
               @delete-runtime-message="handleDeleteRuntimeMessage"
               @composer-height-change="handleComposerHeightChange"
               @toggle-goal-mode="handleToggleGoalMode"
+              @toggle-agent-mode="handleToggleAgentMode"
               @open-goal-dialog="goalDialogOpen = true"
               @open-git-changes-panel="openGitChangesPanel"
             />
@@ -759,6 +767,8 @@
               :icon-style="iconStyle"
               :format-time="formatTime"
               :running-tasks="runningWorkspaceTasks"
+              :current-task-in-progress="taskInProgress"
+              :current-conversation-id="currentConversationId"
               :current-workspace-id="currentHostWorkspaceId"
               :display-mode="chatDisplayMode"
               :display-mode-disabled="displayModeSwitchDisabled"

static/src/app/computed.ts

@@ -231,6 +231,13 @@ export const computed = {
       );
     });
   },
+  anyWorkspaceHasRunningTask() {
+    const tasks = Array.isArray(this.runningWorkspaceTasks) ? this.runningWorkspaceTasks : [];
+    return tasks.some((task: any) => {
+      const status = String(task?.status || '');
+      return ['pending', 'running', 'cancel_requested'].includes(status);
+    });
+  },
   streamingUi() {
     return this.streamingMessage || this.hasPendingToolActions();
   },
@@ -245,6 +252,36 @@ export const computed = {
       this.compressing
     );
   },
+  /**
+   * 子智能体非终态数（包含 running + idle，不含 failed/completed/terminated/timeout）。
+   * 用于状态栏的小按钮显示 “x 个子智能体运行中”。
+   */
+  activeSubAgentCount() {
+    const subAgentStore = useSubAgentStore();
+    const list = Array.isArray(subAgentStore.subAgents) ? subAgentStore.subAgents : [];
+    const TERMINAL = new Set(['completed', 'failed', 'timeout', 'terminated']);
+    return list.filter((s: any) => {
+      const status = String(s?.status || '').toLowerCase();
+      return !TERMINAL.has(status);
+    }).length;
+  },
+  /**
+   * 主对话是否空闲。
+   * 与 composerBusy 的区别：composerBusy=true 可能是“主对话空闲但后台子智能体在跑”
+   * （传统模式 waitingForSubAgent / 多智能体模式 has_running_multi_agent），此时
+   * 用户应当可以再发新消息触发主智能体下一轮工作。
+   * mainChatIdle 只看主对话自身的活动状态：是否还在 streaming、是否正在停中、
+   * 是否被 monitor 锁住、是否压缩中。
+   */
+  mainChatIdle() {
+    return (
+      !this.streamingUi &&
+      !this.stopRequested &&
+      !(this.monitorIsLocked && this.chatDisplayMode === 'monitor') &&
+      !this.compressionInProgress &&
+      !this.compressing
+    );
+  },
   composerStreamingForInput() {
     return this.composerBusy && !this.displayLockEngaged;
   },

static/src/app/methods/common.ts

@@ -25,6 +25,8 @@ export const traceLog = (...args) => {
 function isGoalModeDebugEnabled() {
   if (typeof window === 'undefined') return false;
   try {
+    // 临时强制开启，用于调试多智能体消息轮询问题
+    return true;
     const explicit = (window as any).__GOAL_MODE_DEBUG__;
     if (explicit === true || explicit === '1') return true;
     if (explicit === false || explicit === '0') return false;

static/src/app/methods/conversation/action.ts

@@ -122,15 +122,17 @@ export const actionMethods = {
         this.versioningInitializingBackupToastId = backupToastId;
       }
 
-      const response = await fetch('/api/conversations', {
+      const isMultiAgent = Boolean(this.multiAgentMode);
+      const createUrl = isMultiAgent ? '/api/multiagent/conversations' : '/api/conversations';
+      const createBody = isMultiAgent
+        ? JSON.stringify({ preserve_mode: true, thinking_mode: this.thinkingMode, mode: this.runMode })
+        : JSON.stringify({ thinking_mode: this.thinkingMode, mode: this.runMode });
+      const response = await fetch(createUrl, {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json'
         },
-        body: JSON.stringify({
-          thinking_mode: this.thinkingMode,
-          mode: this.runMode
-        })
+        body: createBody
       });
 
       const result = await response.json();

static/src/app/methods/conversation/load.ts

@@ -14,7 +14,9 @@ export const loadMethods = {
     const requestSeq = ++this.conversationListRequestSeq;
     this.conversationsLoading = true;
     try {
-      const response = await fetch(`/api/conversations?limit=${queryLimit}&offset=${queryOffset}`);
+      // 多智能体模式下只加载多智能体对话记录；常规模式排除多智能体对话
+      const maParam = this.multiAgentMode ? '&multi_agent_mode=1' : '&multi_agent_mode=0';
+      const response = await fetch(`/api/conversations?limit=${queryLimit}&offset=${queryOffset}${maParam}`);
       const data = await response.json();
 
       if (data.success) {
@@ -178,6 +180,9 @@ export const loadMethods = {
         if (typeof result.model_key === 'string' && result.model_key) {
           this.modelSet(result.model_key);
         }
+        if (typeof result.multi_agent_mode === 'boolean') {
+          this.multiAgentMode = result.multi_agent_mode;
+        }
 
         // 2. 更新当前对话信息
         this.skipConversationHistoryReload = true;
@@ -191,10 +196,11 @@ export const loadMethods = {
         if (!preserveListPosition) {
           this.promoteConversationToTop(conversationId);
         }
+        const urlPrefix = this.multiAgentMode ? '/multiagent/' : '/';
         history.pushState(
           { conversationId },
           '',
-          `/${this.stripConversationPrefix(conversationId)}`
+          `${urlPrefix}${this.stripConversationPrefix(conversationId)}`
         );
         this.skipConversationLoadedEvent = true;
 
@@ -284,7 +290,8 @@ export const loadMethods = {
     if (group.loading || group.loadingMore) return;
     group.loading = true;
     try {
-      const response = await fetch(`/api/conversations?workspace_id=${encodeURIComponent(workspaceId)}&limit=${group.limit}&offset=${group.offset}`);
+      const maParam = this.multiAgentMode ? '&multi_agent_mode=1' : '&multi_agent_mode=0';
+      const response = await fetch(`/api/conversations?workspace_id=${encodeURIComponent(workspaceId)}&limit=${group.limit}&offset=${group.offset}${maParam}`);
       const data = await response.json();
       if (data.success) {
         const items = (data.data?.conversations || []).map((conv: any) => ({

static/src/app/methods/message/send.ts

@@ -30,6 +30,36 @@ export const sendMethods = {
       });
       return;
     }
+    // 主对话空闲但 composerBusy=true：composerBusy 只因后台子智能体在跑而保持。
+    // 传统模式：waitingForSubAgent=true（taskInProgress=true 。多智能体模式：has_running_multi_agent=true。
+    // 此时新文本消息应直接发送，触发主智能体下一轮工作，而不是被进队列等任务结束。
+    const mainIdle = typeof this.mainChatIdle === 'function' ? this.mainChatIdle : (
+      !this.streamingUi && !this.stopRequested && !this.compressionInProgress && !this.compressing
+    );
+    if (this.composerBusy && mainIdle && hasText) {
+      // 如果有 pending 问题（子智能体询问主智能体），仍走问答路径，不走直接发送
+      if (Array.isArray(this.pendingUserQuestions) && this.pendingUserQuestions.length > 0) {
+        const answered = await this.answerUserQuestionFromComposer(this.inputMessage);
+        if (answered) {
+          this.inputClearMessage();
+          this.inputSetLineCount(1);
+          this.inputSetMultiline(false);
+          this.autoResizeInput();
+        }
+        return;
+      }
+      // 主对话空闲但后台任务在跑：直接发送新消息触发主智能体下一轮
+      this.sendMessage();
+      return;
+    }
+    if (this.composerBusy && mainIdle && hasMedia) {
+      this.uiPushToast({
+        title: '后台子智能体运行中',
+        message: '请等待后台任务结束后再发送图片/视频',
+        type: 'warning'
+      });
+      return;
+    }
     if (this.composerBusy) {
       if (hasText) {
         if (Array.isArray(this.pendingUserQuestions) && this.pendingUserQuestions.length > 0) {
@@ -209,15 +239,17 @@ export const sendMethods = {
           this.versioningInitializingBackupToastId = backupToastId;
         }
 
-        const createResp = await fetch('/api/conversations', {
+        const isMultiAgent = Boolean(this.multiAgentMode);
+        const createUrl = isMultiAgent ? '/api/multiagent/conversations' : '/api/conversations';
+        const createBody = isMultiAgent
+          ? JSON.stringify({ preserve_mode: true, thinking_mode: this.thinkingMode, mode: this.runMode })
+          : JSON.stringify({ thinking_mode: this.thinkingMode, mode: this.runMode });
+        const createResp = await fetch(createUrl, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json'
           },
-          body: JSON.stringify({
-            thinking_mode: this.thinkingMode,
-            mode: this.runMode
-          })
+          body: createBody
         });
         const createResult = await createResp.json().catch(() => ({}));
         if (!createResp.ok || !createResult?.success || !createResult?.conversation_id) {
@@ -258,7 +290,8 @@ export const sendMethods = {
         }
 
         const pathFragment = this.stripConversationPrefix(targetConversationId);
-        history.replaceState({ conversationId: targetConversationId }, '', `/${pathFragment}`);
+        const urlPrefix = this.multiAgentMode ? '/multiagent/' : '/';
+        history.replaceState({ conversationId: targetConversationId }, '', `${urlPrefix}${pathFragment}`);
       } catch (error) {
         this.uiPushToast({
           title: '发送失败',
@@ -392,7 +425,10 @@ export const sendMethods = {
       return;
     }
 
-    const canStop = this.composerBusy && !this.stopRequested;
+    // 停止按钮现在只停主智能体，与后台任务无关。
+    // canStop 判断只看主智能体是否在 streaming。多次点击被 stopRequested 抖动拦截。
+    const canStop = this.streamingUi && !this.stopRequested;
+
     goalModeDebugLog('stopTask:entry', {
       composerBusy: this.composerBusy,
       stopRequested: this.stopRequested,
@@ -429,6 +465,7 @@ export const sendMethods = {
 
       // 等待后端确认；轮询继续，task_stopped 事件到达后会由 taskStore 自动停止轮询
       await new Promise((resolve) => setTimeout(resolve, 300));
+
       const shouldKeepBusy =
         ['running', 'pending', 'cancel_requested', 'canceled'].includes(String(taskStore.taskStatus));
 
@@ -451,25 +488,10 @@ export const sendMethods = {
 
       // 清理assistant消息的等待动画状态
       const lastMessage = this.messages[this.messages.length - 1];
-      const before = {
-        hasLastMessage: !!lastMessage,
-        role: lastMessage?.role,
-        awaitingFirstContent: lastMessage?.awaitingFirstContent,
-        generatingLabel: lastMessage?.generatingLabel
-      };
-
       if (lastMessage && lastMessage.role === 'assistant') {
         lastMessage.awaitingFirstContent = false;
         lastMessage.generatingLabel = '';
       }
-
-      console.log('[DEBUG_AWAITING] stopTask 清理完成', {
-        before,
-        after: {
-          awaitingFirstContent: lastMessage?.awaitingFirstContent,
-          generatingLabel: lastMessage?.generatingLabel
-        }
-      });
     } catch (error) {
       console.error('[Message] 取消任务失败:', error);
       const { useTaskStore } = await import('../../../stores/task');
@@ -503,7 +525,7 @@ export const sendMethods = {
 
       this.uiPushToast({
         title: '停止请求已发送',
-        message: '若任务未停止，请再次点击停止按钮',
+        message: '若主对话未停止，请稍候；后台任务可通过状态栏单独停止',
         type: 'info'
       });
     } finally {

static/src/app/methods/taskPolling/lifecycle.ts

@@ -372,8 +372,9 @@ export const lifecycleMethods = {
     });
     const hasRunningSubAgents = !!data?.has_running_sub_agents;
     const hasRunningBackgroundCommands = !!data?.has_running_background_commands;
-    if (hasRunningSubAgents) {
-      debugLog('[TaskPolling] 任务完成，但仍有后台子智能体运行');
+    const hasRunningMultiAgent = !!data?.has_running_multi_agent;
+    if (hasRunningSubAgents || hasRunningMultiAgent) {
+      debugLog('[TaskPolling] 任务完成，但仍有后台子智能体/多智能体运行');
     } else {
       debugLog('[TaskPolling] 任务完成');
     }
@@ -381,11 +382,23 @@ export const lifecycleMethods = {
     // 同步处理状态更新
     this.streamingMessage = false;
     this.stopRequested = false;
-    if (!hasRunningSubAgents) {
+    if (!hasRunningSubAgents && !hasRunningMultiAgent) {
       this.markLatestUserWorkCompleted();
     }
 
-    if (hasRunningSubAgents) {
+    if (hasRunningMultiAgent) {
+      // 多智能体模式下主智能体已空闲，但仍有实例在运行，保持对话运行态继续接收后续消息；
+      // 不启动后台等待轮询，也不阻塞输入区（waitingForSubAgent=false）。
+      // 但必须启动运行中任务探测，否则子智能体后续输出触发的新主任务无法被前端发现。
+      jsonDebug('handleTaskComplete:hasRunningMultiAgent', {
+        taskInProgress: this.taskInProgress,
+        currentConversationId: this.currentConversationId
+      });
+      this.taskInProgress = true;
+      this.waitingForSubAgent = false;
+      this.waitingForBackgroundCommand = hasRunningBackgroundCommands;
+      this.startMultiAgentTaskProbe();
+    } else if (hasRunningSubAgents) {
       this.taskInProgress = true;
       this.waitingForSubAgent = true;
       this.waitingForBackgroundCommand = hasRunningBackgroundCommands;
@@ -403,6 +416,7 @@ export const lifecycleMethods = {
       this.waitingForSubAgent = false;
       this.waitingForBackgroundCommand = false;
       this.stopWaitingTaskProbe();
+      this.stopMultiAgentTaskProbe();
       this.clearTaskState(); // 清理任务状态
       this.$nextTick(() => {
         if (typeof this.tryAutoSendRuntimeQueuedMessages === 'function') {
@@ -472,22 +486,13 @@ export const lifecycleMethods = {
     this.stopRequested = false;
 
     if (hasRunningBackground) {
-      // 智能体已停，但后台任务还在跑：保持停止按钮，等用户第二下清理
-      // 此时对话并未真正停止，work_timer 保持运行，不提前标记完成
+      // 主智能体已停，后台任务仍在跑：保持 taskInProgress=true （对话列表显示运行中），
+      // 但输入栏不再锁定（stopRequested 已重置），用户可发新消息触发下一轮。
+      // 后台任务的停止由独立的子智能体/后台指令按钮处理，不再走停止按钮二次点击。
       this.taskInProgress = true;
       this.waitingForSubAgent = hasRunningSubAgents;
       this.waitingForBackgroundCommand = hasRunningBackgroundCommands;
-      debugLog('[TaskPolling] 任务已停止，仍有后台任务运行，保持停止态');
-      goalModeDebugLog('handleTaskStopped:show-toast', { hasRunningSubAgents, hasRunningBackgroundCommands });
-      try {
-        this.uiPushToast({
-          title: '智能体已停止',
-          message: '再次按下停止按钮以结束后台任务',
-          type: 'info'
-        });
-      } catch (err) {
-        console.warn('[TaskPolling] uiPushToast 调用失败:', err);
-      }
+      debugLog('[TaskPolling] 任务已停止，仍有后台任务运行，保持对话运行态但释放输入区');
     } else {
       // 对话真正停止：停止计时器并持久化
       this.markLatestUserWorkCompleted();

static/src/app/methods/taskPolling/probe.ts

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import { debugLog } from '../common';
+import { debugLog, goalModeDebugLog } from '../common';
 import { useTaskStore } from '../../../stores/task';
 import { getMessageVisibility, messageStartsWork } from '../../../utils/messageVisibility';
 import {
@@ -86,6 +86,132 @@ export const probeMethods = {
       }
     }, 1000);
   },
+
+  // ---------- 多智能体任务探测 ----------
+  stopMultiAgentTaskProbe() {
+    if (this.multiAgentTaskProbeTimer) {
+      debugNotifyLog('[DEBUG_NOTIFY][ui] stopMultiAgentTaskProbe');
+      goalModeDebugLog('probe.stopMultiAgentTaskProbe', {
+        conversationId: this.currentConversationId,
+        taskInProgress: this.taskInProgress
+      });
+      clearInterval(this.multiAgentTaskProbeTimer);
+      this.multiAgentTaskProbeTimer = null;
+    }
+  },
+  startMultiAgentTaskProbe() {
+    if (this.multiAgentTaskProbeTimer) {
+      debugNotifyLog('[DEBUG_NOTIFY][ui] startMultiAgentTaskProbe:already-started');
+      return;
+    }
+    debugNotifyLog('[DEBUG_NOTIFY][ui] startMultiAgentTaskProbe');
+    keyNotifyLog('[DEBUG_NOTIFY_KEY][ui] startMultiAgentTaskProbe', {
+      conversationId: this.currentConversationId
+    });
+    goalModeDebugLog('probe.startMultiAgentTaskProbe', {
+      conversationId: this.currentConversationId,
+      taskInProgress: this.taskInProgress
+    });
+    this.multiAgentTaskProbeTimer = setInterval(async () => {
+      if (!this.taskInProgress || !this.currentConversationId) {
+        debugNotifyLog('[DEBUG_NOTIFY][ui] multiAgentTaskProbe:stop-no-task-in-progress');
+        goalModeDebugLog('probe.multiAgentTaskProbe_stop', {
+          reason: 'no_task_in_progress',
+          taskInProgress: this.taskInProgress,
+          currentConversationId: this.currentConversationId
+        });
+        this.stopMultiAgentTaskProbe();
+        return;
+      }
+      goalModeDebugLog('probe.multiAgentTaskProbe_tick', {
+        currentConversationId: this.currentConversationId
+      });
+      const resumed = await this.tryResumeRunningTask();
+      if (resumed) {
+        debugNotifyLog('[DEBUG_NOTIFY][ui] multiAgentTaskProbe:resumed-and-stop');
+        keyNotifyLog('[DEBUG_NOTIFY_KEY][ui] multiAgentTaskProbe:resumed-and-stop');
+        this.stopMultiAgentTaskProbe();
+      }
+    }, 1000);
+  },
+  async tryResumeRunningTask() {
+    if (!this.currentConversationId) {
+      return false;
+    }
+    try {
+      const { useTaskStore } = await import('../../../stores/task');
+      const taskStore = useTaskStore();
+      if (taskStore.hasActiveTask) {
+        debugNotifyLog('[DEBUG_NOTIFY][ui] tryResumeRunningTask:already-active', {
+          taskId: taskStore.currentTaskId,
+          status: taskStore.taskStatus
+        });
+        return true;
+      }
+
+      const resp = await fetch('/api/tasks');
+      if (!resp.ok) {
+        debugNotifyLog('[DEBUG_NOTIFY][ui] tryResumeRunningTask:tasks-api-not-ok', {
+          status: resp.status
+        });
+        return false;
+      }
+      const result = await resp.json().catch(() => ({}));
+      const tasks = Array.isArray(result?.data) ? result.data : [];
+      debugNotifyLog('[DEBUG_NOTIFY][ui] tryResumeRunningTask:tasks', {
+        currentConversationId: this.currentConversationId,
+        count: tasks.length,
+        running: tasks
+          .filter((t: any) => t?.status === 'running')
+          .map((t: any) => ({
+            task_id: t?.task_id,
+            conversation_id: t?.conversation_id,
+            status: t?.status
+          }))
+      });
+      const runningTask = tasks.find(
+        (task: any) =>
+          (task?.status === 'running' || task?.status === 'pending') &&
+          task?.conversation_id === this.currentConversationId &&
+          (!(this.versioningHostMode || this.dockerProjectMode) ||
+            !this.currentHostWorkspaceId ||
+            task?.workspace_id === this.currentHostWorkspaceId)
+      );
+      if (!runningTask?.task_id) {
+        debugNotifyLog('[DEBUG_NOTIFY][ui] tryResumeRunningTask:no-matched-task');
+        goalModeDebugLog('probe.tryResumeRunningTask_no_match', {
+          currentConversationId: this.currentConversationId,
+          tasksCount: tasks.length
+        });
+        return false;
+      }
+
+      debugNotifyLog('[DEBUG_NOTIFY][ui] tryResumeRunningTask:resume', {
+        task_id: runningTask.task_id
+      });
+      goalModeDebugLog('probe.tryResumeRunningTask_resume', {
+        taskId: runningTask.task_id,
+        conversationId: this.currentConversationId
+      });
+      keyNotifyLog('[DEBUG_NOTIFY_KEY][ui] tryResumeRunningTask:resume', {
+        task_id: runningTask.task_id,
+        conversationId: this.currentConversationId
+      });
+      if (typeof this.clearProcessedEvents === 'function') {
+        this.clearProcessedEvents();
+      }
+      taskStore.resumeTask(runningTask.task_id, {
+        status: 'running',
+        resetOffset: true,
+        eventHandler: (event: any) => this.handleTaskEvent(event)
+      });
+      return true;
+    } catch (error) {
+      console.warn('[TaskPolling] 接管运行中任务失败:', error);
+      return false;
+    }
+  },
+
   async inspectWaitingCompletionState() {
     const terminalStatuses = new Set(['completed', 'failed', 'timeout', 'terminated', 'cancelled']);
     let hasSubAgentPending = false;

static/src/app/methods/taskPolling/sync.ts

@@ -134,10 +134,12 @@ export const syncMethods = {
 
       const pathFragment = this.stripConversationPrefix(data.conversation_id);
       const currentPath = window.location.pathname.replace(/^\/+/, '');
+      const urlPrefix = this.multiAgentMode ? '/multiagent/' : '/';
+      const targetPath = `${urlPrefix}${pathFragment}`;
       if (data.created) {
-        history.pushState({ conversationId: data.conversation_id }, '', `/${pathFragment}`);
+        history.pushState({ conversationId: data.conversation_id }, '', targetPath);
       } else if (currentPath !== pathFragment) {
-        history.replaceState({ conversationId: data.conversation_id }, '', `/${pathFragment}`);
+        history.replaceState({ conversationId: data.conversation_id }, '', targetPath);
       }
     }
   }

static/src/app/methods/ui/mode.ts

@@ -65,6 +65,19 @@ export const modeMethods = {
     this.modeMenuOpen = false;
     this.modelMenuOpen = false;
   },
+  handleToggleAgentMode() {
+    if (!this.isConnected) {
+      return;
+    }
+    // 有运行中对话时不允许切换
+    if (this.composerBusy || this.anyWorkspaceHasRunningTask) {
+      return;
+    }
+    this.inputCloseMenus();
+    // 多智能体模式 → 传统模式；传统模式 → 多智能体模式
+    const target = this.multiAgentMode ? '/new' : '/multiagent/new';
+    window.location.href = target;
+  },
   toggleModeMenu() {
     if (!this.isConnected || this.streamingMessage) {
       return;
@@ -167,5 +180,55 @@ export const modeMethods = {
   },
   async toggleThinkingMode() {
     await this.handleCycleRunMode();
+  },
+  async handleStopAllSubAgents() {
+    const isMultiAgent = !!this.multiAgentMode;
+    const mode = isMultiAgent ? 'soft_stop' : 'terminate';
+    const title = isMultiAgent ? '是否暂停所有子智能体？' : '是否终结所有子智能体？';
+    const message = isMultiAgent
+      ? '所有正在运行的子智能体将停止工作并变为空闲状态。取消表示不执行操作。'
+      : '所有后台子智能体将被强制终止。取消表示不执行操作。';
+    const confirmText = isMultiAgent ? '暂停' : '终结';
+    let proceed = false;
+    try {
+      const uiStore = (await import('../../../stores/ui')).useUiStore();
+      proceed = await uiStore.requestConfirm({
+        title,
+        message,
+        confirmText,
+        cancelText: '取消',
+        confirmVariant: 'danger',
+        closeOnBackdrop: true
+      });
+    } catch (error) {
+      console.error('[stopAllSubAgents] 弹窗异常:', error);
+      return;
+    }
+    if (!proceed) return;
+    try {
+      const { useSubAgentStore } = await import('../../../stores/subAgent');
+      const store = useSubAgentStore();
+      const result = await store.stopAllAgents(mode);
+      if (!result.success) {
+        this.uiPushToast({
+          title: '停止子智能体失败',
+          message: result.error || '请重试',
+          type: 'error'
+        });
+        return;
+      }
+      this.uiPushToast({
+        title: isMultiAgent ? '子智能体已暂停' : '子智能体已终结',
+        message: `已处理 ${result.stoppedCount || 0} 个子智能体`,
+        type: 'info'
+      });
+    } catch (error: any) {
+      console.error('[stopAllSubAgents] 调用失败:', error);
+      this.uiPushToast({
+        title: '停止子智能体失败',
+        message: error?.message || String(error),
+        type: 'error'
+        });
+    }
   }
 };

static/src/app/methods/ui/route.ts

@@ -31,6 +31,64 @@ export const routeMethods = {
     this.currentConversationTitle = '';
     this.titleTypingText = '';
     const path = window.location.pathname.replace(/^\/+/, '');
+    // 检查多智能体模式入口
+    if (path === 'multiagent/new' || path === 'multiagent') {
+      this.multiAgentMode = true;
+      this.currentConversationId = null;
+      this.currentConversationTitle = '多智能体模式';
+      this.logMessageState('bootstrapRoute:clear-messages-for-multiagent-new');
+      this.messages = [];
+      this.titleReady = true;
+      this.suppressTitleTyping = false;
+      this.startTitleTyping('多智能体模式', { animate: false });
+      this.initialRouteResolved = true;
+      this.refreshBlankHeroState();
+      // 进入多智能体模式时触发后端重建索引以补全 multi_agent_mode 字段
+      try {
+        await fetch('/api/multiagent/rebuild-index', { method: 'POST' });
+      } catch (_e) {
+        // 重建失败不阻断主流程
+      }
+      await this.restoreComposerDraftState('bootstrap-route:multiagent');
+      return;
+    }
+    // 当 URL 是 /multiagent/conv_xxx 时也走多智能体模式
+    if (path.startsWith('multiagent/')) {
+      this.multiAgentMode = true;
+      const convPart = path.slice('multiagent/'.length);
+      const convId = convPart.startsWith('conv_') ? convPart : `conv_${convPart}`;
+      try {
+        const resp = await fetch(`/api/conversations/${convId}/load`, { method: 'PUT' });
+        const result = await resp.json();
+        if (result.success) {
+          if (typeof result.run_mode === 'string') {
+            this.runMode = result.run_mode;
+            this.thinkingMode = typeof result.thinking_mode === 'boolean' ? result.thinking_mode : result.run_mode !== 'fast';
+          } else if (typeof result.thinking_mode === 'boolean') {
+            this.thinkingMode = result.thinking_mode;
+            this.runMode = result.thinking_mode ? 'thinking' : 'fast';
+          }
+          if (typeof result.model_key === 'string' && result.model_key) this.modelSet(result.model_key);
+          this.currentConversationId = convId;
+          this.currentConversationTitle = result.title || '多智能体模式';
+          this.titleReady = true;
+          this.suppressTitleTyping = false;
+          this.startTitleTyping(this.currentConversationTitle, { animate: false });
+          history.replaceState({ conversationId: convId }, '', `/multiagent/${this.stripConversationPrefix(convId)}`);
+          this.initialRouteResolved = true;
+          await this.restoreComposerDraftState('bootstrap-route:multiagent-existing');
+          return;
+        }
+      } catch (error) {
+        console.warn('[multiagent] 加载多智能体对话失败:', error);
+      }
+      // 加载失败回退到 multiagent/new 路径
+      history.replaceState({}, '', '/multiagent/new');
+      window.location.reload();
+      return;
+    }
+    // 非多智能体模式：清除标志
+    this.multiAgentMode = false;
     if (!path || this.isExplicitNewConversationRoute()) {
       this.currentConversationId = null;
       this.currentConversationTitle = '新对话';
@@ -126,7 +184,7 @@ export const routeMethods = {
   },
   isExplicitNewConversationRoute() {
     const normalizedPath = window.location.pathname.replace(/^\/+|\/+$/g, '');
-    return normalizedPath === 'new';
+    return normalizedPath === 'new' || normalizedPath === 'multiagent/new' || normalizedPath === 'multiagent';
   },
   stripConversationPrefix(conversationId) {
     if (!conversationId) return '';

static/src/app/methods/ui/socket.ts

@@ -321,10 +321,13 @@ export const socketMethods = {
       const statusConversationId = statusData.conversation && statusData.conversation.current_id;
       const resumeConversationId = statusConversationId || runningConversationId;
       const shouldResumeOnNewRoute = isExplicitNewRoute && !!runningConversationId;
+      const currentPath = window.location.pathname.replace(/^\/+/, '');
+      const isMultiAgentNewRoute = currentPath === 'multiagent/new' || currentPath === 'multiagent';
 
       if (
         resumeConversationId &&
         !this.currentConversationId &&
+        !isMultiAgentNewRoute &&
         (!isExplicitNewRoute || shouldResumeOnNewRoute)
       ) {
         this.skipConversationHistoryReload = true;

static/src/app/state.ts

@@ -6,6 +6,8 @@ export function dataState() {
     // 路由相关
     initialRouteResolved: false,
     dropToolEvents: false,
+    // 多智能体模式开关
+    multiAgentMode: false,
 
     // 轮询模式标志（禁用 WebSocket 事件处理）
     usePollingMode: true,

static/src/app/watchers.ts

@@ -1,7 +1,11 @@
 // @ts-nocheck
 import { debugLog, traceLog } from './methods/common';
+import { useConversationStore } from '../stores/conversation';
 
 export const watchers = {
+  multiAgentMode(newValue) {
+    useConversationStore().$patch({ multiAgentMode: !!newValue });
+  },
   inputMessage() {
     this.autoResizeInput();
     if (typeof this.scheduleComposerDraftPersist === 'function') {

static/src/auth/LoginApp.vue

@@ -61,7 +61,7 @@ const submitting = ref(false);
 const hostSubmitting = ref(false);
 const hostModeEnabled = ref(false);
 
-const login = async () => {
+const doLogin = async (redirectUrl = '/') => {
   if (!email.value || !password.value) {
     error.value = '请输入邮箱和密码';
     return;
@@ -84,7 +84,7 @@ const login = async () => {
 
     const data = await resp.json();
     if (data.success) {
-      window.location.href = '/';
+      window.location.href = redirectUrl;
       return;
     }
 
@@ -96,7 +96,9 @@ const login = async () => {
   }
 };
 
-const hostLogin = async () => {
+const login = () => doLogin('/');
+
+const doHostLogin = async (redirectUrl = '/') => {
   hostSubmitting.value = true;
   error.value = '';
 
@@ -109,7 +111,7 @@ const hostLogin = async () => {
 
     const data = await resp.json();
     if (data.success) {
-      window.location.href = '/';
+      window.location.href = redirectUrl;
       return;
     }
 
@@ -121,6 +123,8 @@ const hostLogin = async () => {
   }
 };
 
+const hostLogin = () => doHostLogin('/');
+
 onMounted(async () => {
   applyTheme(loadTheme());
 

static/src/components/chat/ChatArea.vue

@@ -13,17 +13,42 @@
           'message-block--compact-user': getMessageVisibility(msg) === 'compact',
           'message-block--sub-agent-notice': isSubAgentNoticeOnlyMessage(msg),
           'message-block--before-sub-agent-notice': isFollowedBySubAgentNotice(index),
+          'message-block--multi-agent': isMultiAgentMessage(msg),
           'message-block--last': index === (filteredMessages || []).length - 1
         }"
       >
-        <div v-if="msg.role === 'user'" class="user-message" :class="{ 'user-message--compact': getMessageVisibility(msg) === 'compact', 'user-message--brief': isBriefCompactMessage(msg) }">
+        <div
+          v-if="msg.role === 'user'"
+          class="user-message"
+          :class="{
+            'user-message--multi-agent': isMultiAgentMessage(msg),
+            'user-message--compact': getMessageVisibility(msg) === 'compact',
+            'user-message--brief': isBriefCompactMessage(msg)
+          }"
+        >
           <div v-if="isBriefCompactMessage(msg)" class="compact-brief-line" role="separator">
             <span class="compact-brief-text">{{ compactBriefLabel(msg) }}</span>
           </div>
           <template v-else>
-            <div class="message-header icon-label">
-              <span class="icon icon-sm" :style="iconStyleSafe(userHeaderIconKey(msg))" aria-hidden="true"></span>
-              <span>{{ userHeaderLabel(msg) }}</span>
+            <div
+              class="message-header icon-label"
+              :class="{
+                'message-header--multi-agent': isMultiAgentMessage(msg),
+                'message-header--hidden':
+                  isMultiAgentMessage(msg) && isContinuousMultiAgentMessage(msg, index)
+              }"
+            >
+              <template v-if="isMultiAgentMessage(msg)">
+                <span>{{ multiAgentHeaderLabel(msg) }}</span>
+              </template>
+              <template v-else>
+                <span
+                  class="icon icon-sm"
+                  :style="iconStyleSafe(userHeaderIconKey(msg))"
+                  aria-hidden="true"
+                ></span>
+                <span>{{ userHeaderLabel(msg) }}</span>
+              </template>
             </div>
             <div
               class="message-text user-bubble-text"
@@ -38,8 +63,17 @@
                 class="bubble-text"
                 :class="{ 'is-expanded': isUserBubbleExpanded(msg, index) }"
                 :ref="(el) => registerUserBubbleRef(msg, index, el)"
-                v-html="renderUserMessageContent(msg.content)"
-              ></div>
+              >
+                <template v-if="isMultiAgentMessage(msg)">
+                  <MarkdownRenderer
+                    :content="multiAgentBubbleContent(msg)"
+                    :is-streaming="false"
+                  />
+                </template>
+                <template v-else>
+                  <span v-html="renderUserMessageContent(msg.content)"></span>
+                </template>
+              </div>
               <div v-if="msg.images && msg.images.length" class="image-inline-row">
                 <div
                   class="image-thumbnail-wrapper"
@@ -79,7 +113,7 @@
                 ></button>
               </div>
             </div>
-            <div class="user-bubble-actions">
+            <div v-if="!isMultiAgentMessage(msg)" class="user-bubble-actions">
               <button
                 class="user-bubble-action-btn copy"
                 :class="{ copied: isUserBubbleCopied(msg, index) }"
@@ -905,6 +939,69 @@ const isSystemAutoUserMessage = (message: any) => {
     meta.background_command_notice
   );
 };
+
+// ---------- 多智能体消息渲染 ----------
+
+interface MultiAgentMessageInfo {
+  displayName: string;
+  subtype: string;
+  content: string;
+}
+
+const MULTI_AGENT_MESSAGE_RE =
+  /^来自\s+(.+?)\s+的(.+?)\nid:\s*(\S+)\n\n<(.+?)>\n<(\w+)([^>]*)>\n([\s\S]*?)\n<\/\5>\n<\/\4>$/;
+
+function parseMultiAgentMessage(content: string): MultiAgentMessageInfo | null {
+  const text = String(content || '');
+  const m = text.match(MULTI_AGENT_MESSAGE_RE);
+  if (!m) {
+    return null;
+  }
+  const attrs = m[6] || '';
+  const subtypeMatch = attrs.match(/subtype="([^"]+)"/);
+  return {
+    displayName: m[1].trim(),
+    subtype: subtypeMatch ? subtypeMatch[1] : '',
+    content: m[7]
+  };
+}
+
+function isMultiAgentMessage(message: any): boolean {
+  if (!message || message.role !== 'user') {
+    return false;
+  }
+  const meta = message.metadata || {};
+  const autoType = String(meta.auto_message_type || message.auto_message_type || '');
+  return autoType.startsWith('multi_agent_');
+}
+
+function multiAgentHeaderLabel(message: any): string {
+  const displayName =
+    message?.metadata?.multi_agent_display_name || message?.multi_agent_display_name;
+  if (displayName) {
+    return displayName;
+  }
+  const parsed = parseMultiAgentMessage(message?.content || '');
+  return parsed?.displayName || '子智能体';
+}
+
+function isContinuousMultiAgentMessage(message: any, index: number): boolean {
+  if (!isMultiAgentMessage(message)) {
+    return false;
+  }
+  const messages = getFilteredMessagesSafe();
+  const prev = messages[index - 1];
+  if (!prev || !isMultiAgentMessage(prev)) {
+    return false;
+  }
+  return multiAgentHeaderLabel(message) === multiAgentHeaderLabel(prev);
+}
+
+function multiAgentBubbleContent(message: any): string {
+  const parsed = parseMultiAgentMessage(message?.content || '');
+  return (parsed?.content || message?.content || '').trim();
+}
+
 const escapeUserHtml = (value: string): string =>
   String(value || '')
     .replace(/&/g, '&amp;')
@@ -1176,6 +1273,7 @@ function attachBounceListener() {
   scrollListener = (event: Event) => {
     const target = event.target as HTMLElement | null;
     if (!target) return;
+    const trusted = (event as any).isTrusted === true;
     const top = target.scrollTop;
     const delta = top - lastObservedTop;
     const height = target.scrollHeight || 0;
@@ -1183,6 +1281,18 @@ function attachBounceListener() {
     lastObservedTop = top;
     lastObservedHeight = height;
 
+    if (heightDelta !== 0) {
+      console.log('[ChatAreaScrollDebug] height-change', {
+        heightDelta,
+        scrollHeight: height,
+        top,
+        delta,
+        escapedFromLock: escapedFromLock.value,
+        isAtBottom: isAtBottom.value,
+        isNearBottom: isNearBottom.value,
+      });
+    }
+
     // 大幅高度增长检测：当 scrollHeight 突增（内容大幅展开/渲染），
     // 且用户没有主动脱离锁定（escapedFromLock=false）时，
     // 用 instant 瞬间追底，绕过 spring 动画的延迟。
@@ -1193,6 +1303,15 @@ function attachBounceListener() {
       heightDelta > largeGrowthThreshold &&
       !escapedFromLock.value
     ) {
+      console.log('[ChatAreaScrollDebug] TRIGGER:large-growth-scroll', {
+        heightDelta,
+        threshold: largeGrowthThreshold,
+        top,
+        delta,
+        escapedFromLock: escapedFromLock.value,
+        isAtBottom: isAtBottom.value,
+        isNearBottom: isNearBottom.value,
+      });
       isHandlingLargeGrowth = true;
       markProgrammaticHint('ChatArea.largeGrowth');
       suppressUserIntentUntil = Date.now() + 900;
@@ -1209,7 +1328,6 @@ function attachBounceListener() {
     }
 
     const now = Date.now();
-    const trusted = (event as any).isTrusted === true;
     const closeToProgrammaticHint = now - lastProgrammaticHintTs <= 140;
     const likelyLayoutDriven = Math.abs(heightDelta) > 2;
     const manualUpByWheel = delta < -3 && now - lastUserWheelUpTs <= 240;
@@ -1432,6 +1550,15 @@ async function stickScrollToBottom(
 ) {
   const el = scrollRef.value;
   if (el) {
+    console.log('[ChatAreaScrollDebug] CALL:stickScrollToBottom', {
+      behavior: options.behavior || 'auto',
+      force: !!options.force,
+      preserveScrollPosition: !!options.preserveScrollPosition,
+      isAtBottom: isAtBottom.value,
+      isNearBottom: isNearBottom.value,
+      escapedFromLock: escapedFromLock.value,
+      ...getScrollMetrics(el),
+    });
     bounceTraceLog(
       'programmatic:scrollToBottom:before',
       {

static/src/components/chat/MinimalBlocks.vue

@@ -939,15 +939,13 @@ const getToolIntent = (action: Action) => {
 };
 
 const renderToolResult = (action: Action) => {
-  if (personalizationStore.form.enhanced_tool_display) {
-    const rendered = renderEnhancedToolResult(
-      action,
-      props.formatSearchTopic || (() => ''),
-      props.formatSearchTime || (() => ''),
-      props.formatSearchDomains || (() => '')
-    );
-    if (rendered) return rendered;
-  }
+  const rendered = renderEnhancedToolResult(
+    action,
+    props.formatSearchTopic || (() => ''),
+    props.formatSearchTime || (() => ''),
+    props.formatSearchDomains || (() => '')
+  );
+  if (rendered) return rendered;
 
   const result = action.tool?.result;
   if (!result) return '<div class="result-item">执行中...</div>';

static/src/components/chat/StackedBlocks.vue

@@ -1,7 +1,11 @@
 <template>
   <div
     class="stacked-shell"
-    :class="{ 'stacked-shell--single': isSingle, 'stacked-shell--not-ready': !ready, 'stacked-shell--no-borders': hideBorders }"
+    :class="{
+      'stacked-shell--single': isSingle,
+      'stacked-shell--not-ready': !ready,
+      'stacked-shell--no-borders': hideBorders
+    }"
     ref="shell"
     :style="{
       height: `${shellHeight}px`,
@@ -89,59 +93,7 @@
             </div>
             <div class="collapsible-content" :style="contentStyle(blockKey(action, idx))">
               <div class="content-inner">
-                <div
-                  v-if="shouldUseEnhancedDisplay && renderToolResult(action)"
-                  v-html="renderToolResult(action)"
-                ></div>
-                <div
-                  v-else-if="
-                    !shouldUseEnhancedDisplay &&
-                    action.tool?.name === 'web_search' &&
-                    action.tool?.result
-                  "
-                >
-                  <div class="search-meta">
-                    <div>
-                      <strong>搜索内容：</strong
-                      >{{ action.tool.result.query || action.tool.arguments?.query }}
-                    </div>
-                    <div>
-                      <strong>主题：</strong
-                      >{{ formatSearchTopic(action.tool.result.filters || {}) }}
-                    </div>
-                    <div>
-                      <strong>时间范围：</strong
-                      >{{ formatSearchTime(action.tool.result.filters || {}) }}
-                    </div>
-                    <div>
-                      <strong>限定网站：</strong
-                      >{{ formatSearchDomains(action.tool.result.filters || {}) }}
-                    </div>
-                    <div><strong>结果数量：</strong>{{ action.tool.result.total_results }}</div>
-                  </div>
-                  <div
-                    v-if="action.tool.result.results && action.tool.result.results.length"
-                    class="search-result-list"
-                  >
-                    <div
-                      v-for="item in action.tool.result.results"
-                      :key="item.url || item.index"
-                      class="search-result-item"
-                    >
-                      <div class="search-result-title">{{ item.title || '无标题' }}</div>
-                      <div class="search-result-url">
-                        <a v-if="item.url" :href="item.url" target="_blank">{{ item.url }}</a
-                        ><span v-else>无可用链接</span>
-                      </div>
-                    </div>
-                  </div>
-                  <div v-else class="search-empty">未返回详细的搜索结果。</div>
-                </div>
-                <div v-else>
-                  <pre>{{
-                    JSON.stringify(action.tool?.result || action.tool?.arguments, null, 2)
-                  }}</pre>
-                </div>
+                <div v-html="renderToolResult(action)"></div>
               </div>
             </div>
             <div v-if="isToolProcessing(action)" class="progress-indicator"></div>
@@ -190,10 +142,6 @@ const stackKey = `stacked-${++stackInstanceCounter}`;
 // 初始化 personalization store
 const personalizationStore = usePersonalizationStore();
 
-const shouldUseEnhancedDisplay = computed(() => {
-  return personalizationStore.form.enhanced_tool_display;
-});
-
 const hideBorders = computed(() => personalizationStore.form.stacked_hide_borders);
 
 const renderToolResult = (action: any) => {
@@ -338,7 +286,7 @@ const measureAndCompute = () => {
     nextContentHeights[key] = fullContent;
     const expanded = isExpandedById(key);
     // 分隔线：隐藏边线模式下统一为 0，否则最后一块无 border-bottom
-    const borderH = hideBorders.value ? 0 : (idx === children.length - 1 ? 0 : 1);
+    const borderH = hideBorders.value ? 0 : idx === children.length - 1 ? 0 : 1;
     heights.push(headerH + (expanded ? fullContent : 0) + borderH);
   });
 

static/src/components/chat/actions/ToolAction.vue

@@ -30,10 +30,7 @@
       "
     >
       <div class="content-inner">
-        <div v-if="shouldUseEnhancedDisplay" v-html="renderEnhancedToolResult()"></div>
-        <div v-else>
-          <pre>{{ JSON.stringify(action.tool.result || action.tool.arguments, null, 2) }}</pre>
-        </div>
+        <div v-html="renderToolResult()"></div>
       </div>
     </div>
     <div
@@ -44,9 +41,6 @@
 </template>
 
 <script setup lang="ts">
-import { computed } from 'vue';
-import { usePersonalizationStore } from '@/stores/personalization';
-
 defineOptions({ name: 'ToolAction' });
 
 const props = defineProps<{
@@ -68,13 +62,6 @@ const props = defineProps<{
 
 defineEmits<{ (event: 'toggle'): void }>();
 
-// 初始化 store
-const personalizationStore = usePersonalizationStore();
-
-const shouldUseEnhancedDisplay = computed(() => {
-  return personalizationStore.form.enhanced_tool_display && props.action.tool.result;
-});
-
 function escapeHtml(text: string): string {
   const div = document.createElement('div');
   div.textContent = text;
@@ -122,7 +109,7 @@ function formatToolStatusLabel(result: any, successLabel: string, failedLabel =
   return result?.success ? successLabel : failedLabel;
 }
 
-function renderEnhancedToolResult(): string {
+function renderToolResult(): string {
   const tool = props.action.tool;
   const result = tool.result;
   const args = tool.arguments || {};
@@ -154,7 +141,7 @@ function renderEnhancedToolResult(): string {
   else if (name === 'read_file' || name === 'read_skill') {
     return renderReadFile(result, args);
   } else if (name === 'create_skill') {
-    return renderCreateSkill(result, args);
+    return renderCreateSkill(result);
   } else if (name === 'vlm_analyze') {
     return renderVlmAnalyze(result, args);
   } else if (name === 'ocr_image') {
@@ -215,12 +202,86 @@ function renderEnhancedToolResult(): string {
     return renderCreateSubAgent(result, args);
   } else if (name === 'terminate_sub_agent') {
     return renderTerminateSubAgent(result, args);
+  } else if (name === 'send_message_to_sub_agent') {
+    return renderSendMessageToSubAgent(result, args);
+  } else if (name === 'ask_sub_agent') {
+    return renderAskSubAgent(result, args);
+  } else if (name === 'answer_sub_agent_question') {
+    return renderAnswerSubAgentQuestion(result, args);
+  } else if (name === 'create_custom_agent') {
+    return renderCreateCustomAgent(result, args);
+  } else if (name === 'list_agents') {
+    return renderListAgents(result);
+  } else if (name === 'list_active_sub_agents') {
+    return renderListActiveSubAgents(result);
   } else if (name === 'get_sub_agent_status') {
-    return renderGetSubAgentStatus(result, args);
+    return renderGetSubAgentStatus(result);
   }
 
-  // 默认显示 JSON
-  return `<pre>${escapeHtml(JSON.stringify(result || args, null, 2))}</pre>`;
+  // 默认不再显示原始 JSON，而是显示参数摘要 + 结果状态
+  return renderDefaultResult(result, args, name);
+}
+
+function renderDefaultResult(result: any, args: any, name: string): string {
+  const status = formatToolStatusLabel(result, '✓ 完成', '✗ 失败');
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>工具：</strong>${escapeHtml(name)}</div>`;
+  html += `<div><strong>状态：</strong>${escapeHtml(status)}</div>`;
+
+  // 只展示重要参数：文件路径、目标 ID、问题等
+  const importantKeys = [
+    'path',
+    'file_path',
+    'agent_id',
+    'target_agent_id',
+    'question',
+    'role_id',
+    'url'
+  ];
+  importantKeys.forEach((key) => {
+    const value = args[key] ?? result?.[key];
+    if (value !== undefined && value !== '' && value !== null) {
+      const labelMap: Record<string, string> = {
+        path: '路径',
+        file_path: '路径',
+        agent_id: '子智能体 ID',
+        target_agent_id: '目标子智能体 ID',
+        question: '问题',
+        role_id: '角色 ID',
+        url: 'URL'
+      };
+      const displayValue = typeof value === 'string' ? value : JSON.stringify(value);
+      const preview = String(displayValue).slice(0, 200);
+      const suffix = String(displayValue).length > 200 ? '…' : '';
+      html += `<div><strong>${escapeHtml(labelMap[key] || key)}：</strong>${escapeHtml(preview + suffix)}</div>`;
+    }
+  });
+
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  // 如果结果里有可读的 message/summary/answer/output/content/data，直接展示
+  const readable =
+    result?.message ??
+    result?.summary ??
+    result?.answer ??
+    result?.output ??
+    result?.content ??
+    result?.data ??
+    '';
+  if (readable && typeof readable === 'string' && readable.trim()) {
+    html += '<div class="tool-result-content scrollable">';
+    html += `<pre>${escapeHtml(readable.trim())}</pre>`;
+    html += '</div>';
+  } else if (result?.success) {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="tool-result-empty">工具执行完成，无额外可展示内容。</div>';
+    html += '</div>';
+  }
+
+  return html;
 }
 
 // ===== 网络检索类 =====
@@ -918,7 +979,7 @@ function renderConversationReview(result: any, args: any): string {
   return html;
 }
 
-function renderCreateSkill(result: any, args: any): string {
+function renderCreateSkill(result: any): string {
   const status = formatToolStatusLabel(result, '✓ 已归档');
   let html = '<div class="tool-result-meta">';
   html += `<div><strong>状态：</strong>${status}</div>`;
@@ -1242,7 +1303,7 @@ function renderTerminateSubAgent(result: any, args: any): string {
   return html;
 }
 
-function renderGetSubAgentStatus(result: any, args: any): string {
+function renderGetSubAgentStatus(result: any): string {
   if (!result.success) {
     const error = result.error ?? '查询失败';
     return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
@@ -1299,6 +1360,185 @@ function renderGetSubAgentStatus(result: any, args: any): string {
 
   return html;
 }
+
+function renderSendMessageToSubAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已发送', '✗ 发送失败');
+  const agentId = args.agent_id ?? result.agent_id ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (agentId !== '') {
+    html += `<div><strong>子智能体 ID：</strong>${escapeHtml(String(agentId))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  return html;
+}
+
+function renderAskSubAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已回答', '✗ 获取失败');
+  const agentId = args.agent_id ?? '';
+  const question = args.question ?? '';
+  const answer =
+    result?.answer ?? result?.content ?? result?.message ?? result?.output ?? result?.result ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (agentId !== '') {
+    html += `<div><strong>子智能体 ID：</strong>${escapeHtml(String(agentId))}</div>`;
+  }
+  if (question) {
+    const preview = String(question).slice(0, 200);
+    const suffix = String(question).length > 200 ? '…' : '';
+    html += `<div><strong>问题：</strong>${escapeHtml(preview + suffix)}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  if (answer && typeof answer === 'string') {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="content-label">回答</div>';
+    html += `<pre>${escapeHtml(answer)}</pre>`;
+    html += '</div>';
+  } else if (result?.success) {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="tool-result-empty">子智能体未返回答复内容。</div>';
+    html += '</div>';
+  }
+
+  return html;
+}
+
+function renderAnswerSubAgentQuestion(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已回复', '✗ 回复失败');
+  const questionId = args.question_id ?? result.question_id ?? '';
+  const answer = args.answer ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (questionId) {
+    html += `<div><strong>问题 ID：</strong>${escapeHtml(String(questionId))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  if (answer && typeof answer === 'string') {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="content-label">回复内容</div>';
+    const preview = String(answer).slice(0, 500);
+    const suffix = String(answer).length > 500 ? '…' : '';
+    html += `<pre>${escapeHtml(preview + suffix)}</pre>`;
+    html += '</div>';
+  }
+
+  return html;
+}
+
+function renderCreateCustomAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已创建', '✗ 创建失败');
+  const roleId = args.role_id ?? result.role_id ?? '';
+  const name = args.name ?? result.name ?? roleId;
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (roleId !== '') {
+    html += `<div><strong>角色 ID：</strong>${escapeHtml(String(roleId))}</div>`;
+  }
+  if (name && name !== roleId) {
+    html += `<div><strong>角色名：</strong>${escapeHtml(String(name))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  return html;
+}
+
+function renderListAgents(result: any): string {
+  if (!result?.success) {
+    const error = result?.error ?? '查询失败';
+    return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
+  }
+
+  const roles = Array.isArray(result.roles) ? result.roles : [];
+  if (roles.length === 0) {
+    return '<div class="tool-result-empty">当前没有可用角色。</div>';
+  }
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>角色数量：</strong>${roles.length}</div>`;
+  html += '</div>';
+
+  html += '<div class="search-result-list">';
+  roles.forEach((role: any) => {
+    const roleId = role.role_id || '未知';
+    const name = role.name || roleId;
+    const description = role.description || '';
+    const thinkingMode = role.thinking_mode || 'fast';
+    const isCustom = role.is_custom ? '是' : '否';
+
+    html += '<div class="search-result-item">';
+    html += `<div class="search-result-title">${escapeHtml(roleId)} — ${escapeHtml(name)}</div>`;
+    if (description) {
+      html += `<div>${escapeHtml(description)}</div>`;
+    }
+    html += `<div><strong>思考模式：</strong>${escapeHtml(thinkingMode)} | <strong>自定义：</strong>${escapeHtml(isCustom)}</div>`;
+    html += '</div>';
+  });
+  html += '</div>';
+
+  return html;
+}
+
+function renderListActiveSubAgents(result: any): string {
+  if (!result?.success) {
+    const error = result?.error ?? '查询失败';
+    return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
+  }
+
+  const agents = Array.isArray(result.agents) ? result.agents : [];
+  if (agents.length === 0) {
+    return '<div class="tool-result-empty">当前会话没有活跃子智能体。</div>';
+  }
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>活跃数量：</strong>${agents.length}</div>`;
+  html += '</div>';
+
+  html += '<div class="sub-agent-status-list">';
+  agents.forEach((agent: any) => {
+    const agentId = agent.agent_id ?? '?';
+    const displayName = agent.display_name || `Agent_${agentId}`;
+    const status = agent.status || 'unknown';
+    const summary = agent.summary || '';
+    const lastOutput = agent.last_output || '';
+
+    html += '<div class="sub-agent-status-item">';
+    html += `<div class="sub-agent-status-header">#${escapeHtml(String(agentId))} ${escapeHtml(displayName)} [${escapeHtml(status)}]</div>`;
+    html += '<div class="tool-result-meta">';
+    if (summary) {
+      html += `<div><strong>任务：</strong>${escapeHtml(String(summary))}</div>`;
+    }
+    if (lastOutput) {
+      const preview = String(lastOutput).slice(0, 120);
+      const suffix = String(lastOutput).length > 120 ? '…' : '';
+      html += `<div><strong>最近输出：</strong>${escapeHtml(preview + suffix)}</div>`;
+    }
+    html += '</div>';
+    html += '</div>';
+  });
+  html += '</div>';
+
+  return html;
+}
 </script>
 
 <style>

static/src/components/chat/actions/toolRenderers.ts

@@ -62,6 +62,11 @@ export function renderEnhancedToolResult(
     return '';
   }
 
+  // 如果 result 已经被格式化为文本字符串，直接显示
+  if (typeof result === 'string') {
+    return `<div class="tool-result-content scrollable"><pre>${escapeHtml(result)}</pre></div>`;
+  }
+
   // 网络检索类
   if (name === 'web_search') {
     return renderWebSearch(result, args, formatSearchTopic, formatSearchTime, formatSearchDomains);
@@ -88,7 +93,7 @@ export function renderEnhancedToolResult(
   else if (name === 'read_file' || name === 'read_skill') {
     return renderReadFile(result, args);
   } else if (name === 'create_skill') {
-    return renderCreateSkill(result, args);
+    return renderCreateSkill(result);
   } else if (name === 'vlm_analyze') {
     return renderVlmAnalyze(result, args);
   } else if (name === 'ocr_image') {
@@ -152,11 +157,84 @@ export function renderEnhancedToolResult(
     return renderCreateSubAgent(result, args);
   } else if (name === 'terminate_sub_agent') {
     return renderTerminateSubAgent(result, args);
+  } else if (name === 'send_message_to_sub_agent') {
+    return renderSendMessageToSubAgent(result, args);
+  } else if (name === 'ask_sub_agent') {
+    return renderAskSubAgent(result, args);
+  } else if (name === 'answer_sub_agent_question') {
+    return renderAnswerSubAgentQuestion(result, args);
+  } else if (name === 'create_custom_agent') {
+    return renderCreateCustomAgent(result, args);
+  } else if (name === 'list_agents') {
+    return renderListAgents(result);
+  } else if (name === 'list_active_sub_agents') {
+    return renderListActiveSubAgents(result);
   } else if (name === 'get_sub_agent_status') {
-    return renderGetSubAgentStatus(result, args);
+    return renderGetSubAgentStatus(result);
   }
 
-  return '';
+  // 默认回退：显示重要参数 + 结果摘要，不再直接返回空字符串
+  return renderDefaultResult(result, args, name);
+}
+
+function renderDefaultResult(result: any, args: any, name: string): string {
+  const status = formatToolStatusLabel(result, '✓ 完成', '✗ 失败');
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>工具：</strong>${escapeHtml(name)}</div>`;
+  html += `<div><strong>状态：</strong>${escapeHtml(status)}</div>`;
+
+  const importantKeys = [
+    'path',
+    'file_path',
+    'agent_id',
+    'target_agent_id',
+    'question',
+    'role_id',
+    'url'
+  ];
+  importantKeys.forEach((key) => {
+    const value = args?.[key] ?? result?.[key];
+    if (value !== undefined && value !== '' && value !== null) {
+      const labelMap: Record<string, string> = {
+        path: '路径',
+        file_path: '路径',
+        agent_id: '子智能体 ID',
+        target_agent_id: '目标子智能体 ID',
+        question: '问题',
+        role_id: '角色 ID',
+        url: 'URL'
+      };
+      const displayValue = typeof value === 'string' ? value : JSON.stringify(value);
+      const preview = String(displayValue).slice(0, 200);
+      const suffix = String(displayValue).length > 200 ? '…' : '';
+      html += `<div><strong>${escapeHtml(labelMap[key] || key)}：</strong>${escapeHtml(preview + suffix)}</div>`;
+    }
+  });
+
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  const readable =
+    result?.message ??
+    result?.summary ??
+    result?.answer ??
+    result?.output ??
+    result?.content ??
+    result?.data ??
+    '';
+  if (readable && typeof readable === 'string' && readable.trim()) {
+    html += '<div class="tool-result-content scrollable">';
+    html += `<pre>${escapeHtml(readable.trim())}</pre>`;
+    html += '</div>';
+  } else if (result?.success) {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="tool-result-empty">工具执行完成，无额外可展示内容。</div>';
+    html += '</div>';
+  }
+
+  return html;
 }
 
 // 网络检索类渲染函数
@@ -904,7 +982,7 @@ function renderConversationReview(result: any, args: any): string {
   return html;
 }
 
-function renderCreateSkill(result: any, args: any): string {
+function renderCreateSkill(result: any): string {
   const status = formatToolStatusLabel(result, '✓ 已归档');
   let html = '<div class="tool-result-meta">';
   html += `<div><strong>状态：</strong>${status}</div>`;
@@ -1218,7 +1296,7 @@ function renderTerminateSubAgent(result: any, args: any): string {
   return html;
 }
 
-function renderGetSubAgentStatus(result: any, args: any): string {
+function renderGetSubAgentStatus(result: any): string {
   if (!result.success) {
     const error = result.error ?? '查询失败';
     return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
@@ -1275,3 +1353,182 @@ function renderGetSubAgentStatus(result: any, args: any): string {
 
   return html;
 }
+
+function renderSendMessageToSubAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已发送', '✗ 发送失败');
+  const agentId = args.agent_id ?? result.agent_id ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (agentId !== '') {
+    html += `<div><strong>子智能体 ID：</strong>${escapeHtml(String(agentId))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  return html;
+}
+
+function renderAskSubAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已回答', '✗ 获取失败');
+  const agentId = args.agent_id ?? '';
+  const question = args.question ?? '';
+  const answer =
+    result?.answer ?? result?.content ?? result?.message ?? result?.output ?? result?.result ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (agentId !== '') {
+    html += `<div><strong>子智能体 ID：</strong>${escapeHtml(String(agentId))}</div>`;
+  }
+  if (question) {
+    const preview = String(question).slice(0, 200);
+    const suffix = String(question).length > 200 ? '…' : '';
+    html += `<div><strong>问题：</strong>${escapeHtml(preview + suffix)}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  if (answer && typeof answer === 'string') {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="content-label">回答</div>';
+    html += `<pre>${escapeHtml(answer)}</pre>`;
+    html += '</div>';
+  } else if (result?.success) {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="tool-result-empty">子智能体未返回答复内容。</div>';
+    html += '</div>';
+  }
+
+  return html;
+}
+
+function renderAnswerSubAgentQuestion(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已回复', '✗ 回复失败');
+  const questionId = args.question_id ?? result.question_id ?? '';
+  const answer = args.answer ?? '';
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (questionId) {
+    html += `<div><strong>问题 ID：</strong>${escapeHtml(String(questionId))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  if (answer && typeof answer === 'string') {
+    html += '<div class="tool-result-content scrollable">';
+    html += '<div class="content-label">回复内容</div>';
+    const preview = String(answer).slice(0, 500);
+    const suffix = String(answer).length > 500 ? '…' : '';
+    html += `<pre>${escapeHtml(preview + suffix)}</pre>`;
+    html += '</div>';
+  }
+
+  return html;
+}
+
+function renderCreateCustomAgent(result: any, args: any): string {
+  const status = formatToolStatusLabel(result, '✓ 已创建', '✗ 创建失败');
+  const roleId = args.role_id ?? result.role_id ?? '';
+  const name = args.name ?? result.name ?? roleId;
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>状态：</strong>${status}</div>`;
+  if (roleId !== '') {
+    html += `<div><strong>角色 ID：</strong>${escapeHtml(String(roleId))}</div>`;
+  }
+  if (name && name !== roleId) {
+    html += `<div><strong>角色名：</strong>${escapeHtml(String(name))}</div>`;
+  }
+  if (!result?.success && result?.error) {
+    html += `<div><strong>错误：</strong>${escapeHtml(String(result.error))}</div>`;
+  }
+  html += '</div>';
+
+  return html;
+}
+
+function renderListAgents(result: any): string {
+  if (!result?.success) {
+    const error = result?.error ?? '查询失败';
+    return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
+  }
+
+  const roles = Array.isArray(result.roles) ? result.roles : [];
+  if (roles.length === 0) {
+    return '<div class="tool-result-empty">当前没有可用角色。</div>';
+  }
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>角色数量：</strong>${roles.length}</div>`;
+  html += '</div>';
+
+  html += '<div class="search-result-list">';
+  roles.forEach((role: any) => {
+    const roleId = role.role_id || '未知';
+    const name = role.name || roleId;
+    const description = role.description || '';
+    const thinkingMode = role.thinking_mode || 'fast';
+    const isCustom = role.is_custom ? '是' : '否';
+
+    html += '<div class="search-result-item">';
+    html += `<div class="search-result-title">${escapeHtml(roleId)} — ${escapeHtml(name)}</div>`;
+    if (description) {
+      html += `<div>${escapeHtml(description)}</div>`;
+    }
+    html += `<div><strong>思考模式：</strong>${escapeHtml(thinkingMode)} | <strong>自定义：</strong>${escapeHtml(isCustom)}</div>`;
+    html += '</div>';
+  });
+  html += '</div>';
+
+  return html;
+}
+
+function renderListActiveSubAgents(result: any): string {
+  if (!result?.success) {
+    const error = result?.error ?? '查询失败';
+    return `<div class="tool-result-error">⚠️ ${escapeHtml(String(error))}</div>`;
+  }
+
+  const agents = Array.isArray(result.agents) ? result.agents : [];
+  if (agents.length === 0) {
+    return '<div class="tool-result-empty">当前会话没有活跃子智能体。</div>';
+  }
+
+  let html = '<div class="tool-result-meta">';
+  html += `<div><strong>活跃数量：</strong>${agents.length}</div>`;
+  html += '</div>';
+
+  html += '<div class="sub-agent-status-list">';
+  agents.forEach((agent: any) => {
+    const agentId = agent.agent_id ?? '?';
+    const displayName = agent.display_name || `Agent_${agentId}`;
+    const status = agent.status || 'unknown';
+    const summary = agent.summary || '';
+    const lastOutput = agent.last_output || '';
+
+    html += '<div class="sub-agent-status-item">';
+    html += `<div class="sub-agent-status-header">#${escapeHtml(String(agentId))} ${escapeHtml(displayName)} [${escapeHtml(status)}]</div>`;
+    html += '<div class="tool-result-meta">';
+    if (summary) {
+      html += `<div><strong>任务：</strong>${escapeHtml(String(summary))}</div>`;
+    }
+    if (lastOutput) {
+      const preview = String(lastOutput).slice(0, 120);
+      const suffix = String(lastOutput).length > 120 ? '…' : '';
+      html += `<div><strong>最近输出：</strong>${escapeHtml(preview + suffix)}</div>`;
+    }
+    html += '</div>';
+    html += '</div>';
+  });
+  html += '</div>';
+
+  return html;
+}

static/src/components/input/InputComposer.vue

@@ -177,6 +177,14 @@
               >
                 等待回答问题
               </button>
+              <button
+                v-if="(activeSubAgentCount || 0) > 0"
+                type="button"
+                class="floating-project-status__notice floating-project-status__notice--button"
+                @click.stop="$emit('stop-all-sub-agents')"
+              >
+                {{ activeSubAgentCount }} 个子智能体运行中
+              </button>
               <button
                 v-if="terminalCount > 0"
                 type="button"
@@ -353,6 +361,8 @@
         :execution-mode-enabled="executionModeEnabled"
         :goal-mode-armed="goalModeArmed"
         :goal-running="goalRunning"
+        :multi-agent-mode="multiAgentMode"
+        :has-running-task="hasRunningTask"
         @quick-upload="triggerQuickUpload"
         @pick-images="$emit('pick-images')"
         @pick-video="$emit('pick-video')"
@@ -371,6 +381,7 @@
         @open-review="$emit('open-review')"
         @open-path-authorization="$emit('open-path-authorization')"
         @toggle-goal-mode="$emit('toggle-goal-mode')"
+        @toggle-agent-mode="$emit('toggle-agent-mode')"
       />
       <div class="permission-switcher" @click.stop>
         <button
@@ -545,7 +556,9 @@ const emit = defineEmits([
   'restore-user-question',
   'toggle-goal-mode',
   'open-goal-dialog',
-  'open-git-changes-panel'
+  'open-git-changes-panel',
+  'toggle-agent-mode',
+  'stop-all-sub-agents'
 ]);
 
 const props = defineProps<{
@@ -614,6 +627,15 @@ const props = defineProps<{
   goalModeArmed?: boolean;
   goalRunning?: boolean;
   goalProgress?: Record<string, any> | null;
+  multiAgentMode?: boolean;
+  hasRunningTask?: boolean;
+  /**
+   * 主对话是否空闲（composerBusy 可能是 true，但只是因为后台子智能体在跑）。
+   * 多智能体模式下，若主对话空闲，输入栏应处于“正常发送”状态，不是“停止”状态。
+   */
+  mainChatIdle?: boolean;
+  /** 非终态子智能体数量，用于状态栏“x 个子智能体运行中”按钮显示 */
+  activeSubAgentCount?: number;
   hasPendingRuntimeGuidance?: boolean;
   terminalCount?: number;
   hostMode?: boolean;
@@ -830,7 +852,8 @@ const floatingStatusVisible = computed(() => {
     !!projectGitSummaryForRender.value ||
     !!props.goalRunning ||
     !!props.goalModeArmed ||
-    (!!props.userQuestionMinimized && Number(props.pendingUserQuestionCount || 0) > 0)
+    (!!props.userQuestionMinimized && Number(props.pendingUserQuestionCount || 0) > 0) ||
+    (Number(props.activeSubAgentCount || 0) > 0)
   );
 });
 
@@ -2392,15 +2415,21 @@ const hasComposerContent = computed(() => {
   return hasText || hasImages || hasVideos;
 });
 
-const showStopIcon = computed(() => props.streamingMessage && !hasComposerContent.value);
+const showStopIcon = computed(() => {
+  // 停止按钮只看主对话是否在 streaming。后台任务（子智能体/后台指令）的停止
+  // 有独立的“x 个子智能体运行中”按钮和 LeftPanel 后台指令停止按钮，不再集成在停止按钮上。
+  return !!props.streamingMessage && !hasComposerContent.value;
+});
 
 const sendButtonDisabled = computed(() => {
   if (!props.isConnected) {
     return true;
   }
+  // 主对话 streaming 时，有内容则可点击（走 stopTask）；无内容也显示停止按钮
   if (props.streamingMessage) {
     return false;
   }
+  // 主对话空闲时输入栏正常可用，与是否后台任务在跑无关。
   if (props.inputLocked) {
     return true;
   }

static/src/components/input/QuickMenu.vue

@@ -63,6 +63,20 @@
           <template v-else>{{ goalModeArmed ? '已就绪' : '' }}</template>
         </span>
       </button>
+      <button
+        type="button"
+        class="menu-entry"
+        :class="{ 'mode-entry-active': multiAgentMode }"
+        @click.stop="$emit('toggle-agent-mode')"
+        :disabled="!isConnected || hasRunningTask"
+        :title="hasRunningTask ? '有运行中的对话，无法切换模式' : ''"
+      >
+        {{ multiAgentMode ? '返回传统模式' : '多智能体模式' }}
+        <span class="entry-arrow">
+          <template v-if="hasRunningTask">有任务运行中</template>
+          <template v-else-if="multiAgentMode">当前模式</template>
+        </span>
+      </button>
       <button
         type="button"
         class="menu-entry has-submenu"
@@ -200,6 +214,8 @@ const props = defineProps<{
   goalModeArmed?: boolean;
   goalRunning?: boolean;
   goalProgress?: Record<string, any> | null;
+  multiAgentMode?: boolean;
+  hasRunningTask?: boolean;
 }>();
 
 defineEmits<{
@@ -219,6 +235,7 @@ defineEmits<{
   (event: 'pick-video'): void;
   (event: 'open-path-authorization'): void;
   (event: 'toggle-goal-mode'): void;
+  (event: 'toggle-agent-mode'): void;
 }>();
 
 const getIconStyle = (key: string) => (props.iconStyle ? props.iconStyle(key) : {});
@@ -250,4 +267,11 @@ const goalCompleted = computed(() => String(props.goalProgress?.status || '').to
   color: var(--claude-accent);
   font-size: 12px;
 }
+.menu-entry.mode-entry-active {
+  color: var(--claude-accent);
+}
+.menu-entry.mode-entry-active .entry-arrow {
+  color: var(--claude-accent);
+  font-size: 12px;
+}
 </style>

static/src/components/overlay/SubAgentActivityDialog.vue

@@ -29,13 +29,24 @@
         </div>
         <div class="subagent-activity-body">
           <div v-if="activityError" class="subagent-activity-error">{{ activityError }}</div>
-          <div v-else-if="!displayItems.length" class="subagent-activity-empty">
+          <div v-else-if="!timelineItems.length" class="subagent-activity-empty">
             {{ activityLoading ? '正在读取子智能体活动...' : '暂无活动记录' }}
           </div>
           <div v-else class="subagent-activity-list">
-            <div v-for="item in displayItems" :key="item.key" class="subagent-activity-item">
-              <span class="subagent-activity-text">{{ item.text }}</span>
-              <span class="subagent-activity-state" :class="item.state">{{ item.stateLabel }}</span>
+            <div
+              v-for="item in timelineItems"
+              :key="item.key"
+              class="subagent-activity-item"
+              :class="{ 'subagent-output-item': item.kind === 'output', expanded: item.kind === 'output' && expandedOutputs.has(item.key) }"
+              @click="handleItemClick(item)"
+            >
+              <template v-if="item.kind === 'output'">
+                <div class="subagent-output-content">{{ item.content }}</div>
+              </template>
+              <template v-else>
+                <span class="subagent-activity-text">{{ item.text }}</span>
+                <span class="subagent-activity-state" :class="item.state">{{ item.stateLabel }}</span>
+              </template>
             </div>
           </div>
         </div>
@@ -50,17 +61,22 @@ import { storeToRefs } from 'pinia';
 import { useSubAgentStore } from '@/stores/subAgent';
 
 type ActivityEntry = {
+  type?: string;
   id?: string;
   tool?: string;
   status?: string;
   args?: Record<string, any>;
   ts?: number;
+  subtype?: string;
+  content?: string;
+  is_final?: boolean;
 };
 
 const subAgentStore = useSubAgentStore();
 const { activeAgent, activityEntries, activityLoading, activityError, stoppingTaskIds } =
   storeToRefs(subAgentStore);
 const stopError = ref('');
+const expandedOutputs = ref<Set<string>>(new Set());
 
 const close = () => {
   subAgentStore.closeSubAgent();
@@ -141,48 +157,117 @@ const isTerminalStatus = (status?: string) => {
   return ['completed', 'failed', 'timeout', 'terminated', 'cancelled'].includes(normalized);
 };
 
-const displayItems = computed(() => {
+const toggleOutput = (key: string) => {
+  const next = new Set(expandedOutputs.value);
+  if (next.has(key)) {
+    next.delete(key);
+  } else {
+    next.add(key);
+  }
+  expandedOutputs.value = next;
+};
+
+const handleItemClick = (item: any) => {
+  if (item.kind === 'output') {
+    toggleOutput(item.key);
+  }
+};
+
+const timelineItems = computed(() => {
   const entries = activityEntries.value || [];
-  const groups: { key: string; entry: ActivityEntry }[] = [];
+  const rawItems: { kind: 'tool'; key: string; entry: ActivityEntry } | { kind: 'output'; key: string; content: string; isFinal: boolean }[] = [];
+  let currentToolGroup: { kind: 'tool'; key: string; entry: ActivityEntry } | null = null;
 
-  for (let i = 0; i < entries.length; i++) {
-    const entry = entries[i];
-    if (!entry || entry.type !== 'progress') continue;
+  const flushToolGroup = () => {
+    if (currentToolGroup) {
+      rawItems.push(currentToolGroup);
+      currentToolGroup = null;
+    }
+  };
 
-    const baseKey = entry.id || `${entry.tool || 'tool'}-${entry.ts || i}`;
-    const lastGroup = groups[groups.length - 1];
-
-    // 同一个 id 的相邻进度更新（running -> completed）合并为一次工具调用。
-    // 如果上一个同 id 的组已经进入终态，则后续同 id 的记录视为新的工具调用。
-    if (
-      lastGroup &&
-      (lastGroup.entry.id === entry.id || lastGroup.key === baseKey) &&
-      !isTerminalStatus(lastGroup.entry.status)
-    ) {
-      lastGroup.entry = { ...lastGroup.entry, ...entry };
-      continue;
+  entries.forEach((entry: ActivityEntry, index: number) => {
+    if (entry?.type === 'progress' && entry?.subtype === 'output' && typeof entry.content === 'string') {
+      flushToolGroup();
+      rawItems.push({
+        kind: 'output',
+        key: `output-${entry.ts || index}`,
+        content: entry.content,
+        isFinal: !!entry.is_final,
+      });
+      return;
     }
 
-    // 生成唯一 key：id 重复时加上序号
+    if (!entry || entry.type !== 'progress' || !entry.tool) return;
+
+    const baseKey = entry.id || `${entry.tool}-${entry.ts || index}`;
+    if (
+      currentToolGroup &&
+      (currentToolGroup.entry.id === entry.id || currentToolGroup.key === baseKey) &&
+      !isTerminalStatus(currentToolGroup.entry.status)
+    ) {
+      currentToolGroup.entry = { ...currentToolGroup.entry, ...entry };
+      return;
+    }
+
+    flushToolGroup();
     let key = baseKey;
     let suffix = 0;
-    while (groups.some((g) => g.key === key)) {
+    while (rawItems.some((item) => item.kind === 'tool' && item.key === key)) {
       suffix++;
       key = `${baseKey}--${suffix}`;
     }
-    groups.push({ key, entry: { ...entry } });
-  }
+    currentToolGroup = { kind: 'tool', key, entry: { ...entry } };
+  });
 
-  return groups.map((group) => {
-    const item = group.entry;
-    const state = normalizeStatus(item.status);
-    const stateLabel = state === 'completed' ? '完成' : state === 'failed' ? '失败' : '进行中';
+  flushToolGroup();
+
+  return rawItems.map((item) => {
+    if (item.kind === 'output') return item;
+    const state = normalizeStatus(item.entry.status);
     return {
-      key: group.key,
+      kind: 'tool' as const,
+      key: item.key,
       state,
-      stateLabel,
-      text: buildText(item)
+      stateLabel: state === 'completed' ? '完成' : state === 'failed' ? '失败' : '进行中',
+      text: buildText(item.entry)
     };
   });
 });
 </script>
+
+<style scoped>
+.subagent-output-section {
+  margin-bottom: 16px;
+}
+.subagent-output-title,
+.subagent-activity-list-title {
+  font-weight: 600;
+  font-size: 14px;
+  margin-bottom: 8px;
+  color: var(--text-primary);
+}
+.subagent-output-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.subagent-output-item {
+  display: block;
+  cursor: pointer;
+}
+.subagent-output-content {
+  color: var(--text-primary);
+  white-space: pre-wrap;
+  word-break: break-word;
+  line-height: 1.5;
+  text-align: left;
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+}
+.subagent-output-item.expanded .subagent-output-content {
+  -webkit-line-clamp: unset;
+  display: block;
+}
+</style>

static/src/components/panels/LeftPanel.vue

@@ -96,6 +96,16 @@
                     aria-hidden="true"
                   ></span>
                 </button>
+                <button
+                  v-if="panelMode === 'backgroundCommands' && runningBackgroundCommandCount > 0"
+                  type="button"
+                  class="background-stop-btn"
+                  title="终止所有后台指令"
+                  @click.stop="handleStopAllCommands"
+                >
+                  <span class="icon icon-sm" :style="iconStyle('stop')" aria-hidden="true"></span>
+                  <span class="background-stop-label">停止</span>
+                </button>
               </div>
             </transition>
           </div>
@@ -160,10 +170,13 @@
                 @click="openSubAgent(agent)"
               >
                 <div class="sub-agent-header">
-                  <span class="sub-agent-id">#{{ agent.agent_id }}</span>
+                  <span class="sub-agent-summary-text">{{ agent.summary || agent.display_name || `#${agent.agent_id}` }}</span>
                   <span class="sub-agent-status" :class="agent.status">{{ agent.status }}</span>
                 </div>
-                <div class="sub-agent-summary">{{ agent.summary }}</div>
+                <div class="sub-agent-meta">
+                  <span class="sub-agent-name" v-if="agent.display_name">{{ agent.display_name }}</span>
+                  <span class="sub-agent-tokens" v-if="agent.current_context_tokens">{{ formatTokens(agent.current_context_tokens) }}</span>
+                </div>
                 <div class="sub-agent-tool" v-if="agent.last_tool">当前：{{ agent.last_tool }}</div>
               </div>
             </div>
@@ -412,6 +425,20 @@ const openBackgroundCommand = (command: any) => {
   backgroundCommandStore.openCommand(command);
 };
 
+const BG_COMMAND_TERMINAL = new Set(['completed', 'failed', 'timeout', 'cancelled']);
+const runningBackgroundCommandCount = computed(() => {
+  return (backgroundCommands.value || []).filter((c: any) => {
+    const s = String(c?.status || '').toLowerCase();
+    return !BG_COMMAND_TERMINAL.has(s);
+  }).length;
+});
+const handleStopAllCommands = async () => {
+  const result = await backgroundCommandStore.stopAllCommands();
+  if (!result.success) {
+    console.error('[LeftPanel] 批量停止后台指令失败:', result.error);
+  }
+};
+
 const formatBackgroundCommandMeta = (command: any) => {
   const code = command?.return_code;
   if (code === null || code === undefined) {
@@ -433,6 +460,14 @@ const formatBackgroundCommandPreview = (rawCommand: any) => {
   return content;
 };
 
+const formatTokens = (tokens: number) => {
+  if (!tokens || tokens <= 0) return '';
+  if (tokens >= 1000) {
+    return `${(tokens / 1000).toFixed(1)}k ctx`;
+  }
+  return `${tokens} ctx`;
+};
+
 defineExpose({
   panelMenuWrapper
 });

static/src/components/personalization/PersonalizationDrawer.vue

@@ -1736,7 +1736,252 @@
                     </section>
 
                     <section
-                      v-else-if="activeTab === 'admin'"
+                      v-else-if="activeTab === 'sub-agents'"
+                      key="sub-agents"
+                      class="settings-page"
+                    >
+                      <div class="settings-section-desc" style="margin: 0 0 16px; color: var(--claude-text-secondary); font-size: 13px; line-height: 1.6">
+                        管理多智能体模式下的子智能体角色。预设角色可编辑（创建自定义覆盖），自定义角色可创建/编辑/删除。
+                      </div>
+
+                      <!-- 压缩阈值配置 -->
+                      <div class="settings-action-row" style="margin-bottom: 16px">
+                        <span class="settings-row-copy">
+                          <span class="settings-row-title">上下文压缩阈值</span>
+                          <span class="settings-row-desc">
+                            子智能体上下文 tokens 超过此值时触发深度压缩（默认 150000）
+                          </span>
+                        </span>
+                        <div style="display: flex; gap: 6px; align-items: center">
+                          <input
+                            type="number"
+                            class="settings-number-input"
+                            v-model.number="subAgentCompressThreshold"
+                            :min="10000"
+                            :step="10000"
+                            style="width: 120px"
+                          />
+                          <button
+                            type="button"
+                            class="settings-secondary-button"
+                            :disabled="subAgentSettingsSaving"
+                            @click="saveSubAgentSettings"
+                          >
+                            {{ subAgentSettingsSaving ? '保存中...' : '保存' }}
+                          </button>
+                        </div>
+                      </div>
+
+                      <!-- 角色列表 -->
+                      <div class="settings-section-header" style="margin-bottom: 8px">
+                        <span class="settings-section-title">角色列表</span>
+                        <button
+                          type="button"
+                          class="settings-secondary-button"
+                          @click="openRoleEditor()"
+                        >
+                          + 新建角色
+                        </button>
+                      </div>
+
+                      <div v-if="subAgentRolesLoading" class="settings-empty-hint">加载中...</div>
+                      <div v-else-if="subAgentRoles.length === 0" class="settings-empty-hint">
+                        暂无角色
+                      </div>
+
+                      <div v-else class="sub-agent-role-list">
+                        <div
+                          v-for="role in subAgentRoles"
+                          :key="role.role_id"
+                          class="sub-agent-role-card"
+                        >
+                          <div class="sub-agent-role-info">
+                            <div class="sub-agent-role-name">
+                              {{ role.name }}
+                              <span
+                                class="sub-agent-role-tag"
+                                :class="role.is_custom ? 'tag-custom' : 'tag-preset'"
+                              >
+                                {{ role.is_custom ? '自定义' : '预设' }}
+                              </span>
+                            </div>
+                            <div class="sub-agent-role-desc">{{ role.description || '无描述' }}</div>
+                            <div class="sub-agent-role-meta">
+                              ID: {{ role.role_id }} · 思考模式: {{ role.thinking_mode }}<template v-if="role.model_key"> · 模型: {{ role.model_key }}</template>
+                            </div>
+                          </div>
+                          <div class="sub-agent-role-actions">
+                            <button
+                              type="button"
+                              class="settings-secondary-button"
+                              @click="openRoleEditor(role)"
+                            >编辑</button>
+                            <button
+                              v-if="role.is_custom"
+                              type="button"
+                              class="settings-secondary-button danger"
+                              @click="deleteRole(role)"
+                            >删除</button>
+                          </div>
+                        </div>
+                      </div>
+
+                      <!-- 角色编辑弹窗（与个人空间同尺寸） -->
+                      <transition name="personal-page-fade" appear>
+                        <div
+                          v-if="roleEditorOpen"
+                          class="role-editor-drawer-overlay"
+                          @click="closeDropdown"
+                          @click.self="closeRoleEditor"
+                        >
+                          <div class="role-editor-drawer-card settings-redesign-card" style="padding: 30px 42px 24px; border-radius: 32px;" @click.stop>
+                            <div class="role-editor-header">
+                              <h2>{{ editingRole ? '编辑角色' : '新建角色' }}</h2>
+                              <button type="button" class="settings-secondary-button" @click="closeRoleEditor">关闭</button>
+                            </div>
+                            <div class="role-editor-body" @click="closeDropdown">
+                              <label class="settings-input-row">
+                                <span class="settings-row-title">角色 ID</span>
+                                <input
+                                  v-if="!editingRole"
+                                  type="text"
+                                  :value="roleForm.role_id"
+                                  maxlength="40"
+                                  placeholder="英文小写下划线，如 api-designer"
+                                  @input="roleForm.role_id = ($event.target as HTMLInputElement).value"
+                                />
+                                <span v-else class="settings-row-desc" style="text-align: right; font-size: 14px;">{{ roleForm.role_id }}</span>
+                              </label>
+                              <label class="settings-input-row">
+                                <span class="settings-row-title">显示名</span>
+                                <input
+                                  type="text"
+                                  :value="roleForm.name"
+                                  maxlength="40"
+                                  placeholder="如 API Designer"
+                                  @input="roleForm.name = ($event.target as HTMLInputElement).value"
+                                />
+                              </label>
+                              <label class="settings-input-row">
+                                <span class="settings-row-title">描述</span>
+                                <input
+                                  type="text"
+                                  :value="roleForm.description"
+                                  maxlength="100"
+                                  placeholder="一句话描述职责"
+                                  @input="roleForm.description = ($event.target as HTMLInputElement).value"
+                                />
+                              </label>
+                              <div class="settings-select-row">
+                                <span class="settings-row-copy">
+                                  <span class="settings-row-title">思考模式</span>
+                                  <span class="settings-row-desc">fast = 快速响应，thinking = 深度推理</span>
+                                </span>
+                                <div
+                                  class="settings-select-wrap"
+                                  :class="{ open: activeDropdown === 'role-thinking' }"
+                                  @click.stop
+                                >
+                                  <button
+                                    type="button"
+                                    class="settings-select-button"
+                                    @click="toggleDropdown('role-thinking')"
+                                  >
+                                    {{ roleForm.thinking_mode === 'thinking' ? 'thinking' : 'fast' }}
+                                    <span class="select-chevron" aria-hidden="true"></span>
+                                  </button>
+                                  <div
+                                    :class="['settings-floating-menu', { dark: activeTheme === 'dark' }]"
+                                    :style="activeDropdown === 'role-thinking' ? floatingMenuStyle : undefined"
+                                  >
+                                    <button
+                                      type="button"
+                                      class="settings-menu-option"
+                                      :class="{ selected: roleForm.thinking_mode === 'fast' }"
+                                      @click="roleForm.thinking_mode = 'fast'; closeDropdown()"
+                                    >
+                                      <strong>fast</strong><span>快速响应模式</span><svg viewBox="0 0 24 24"><path d="M5 12.5 9.5 17 19 7" /></svg>
+                                    </button>
+                                    <button
+                                      type="button"
+                                      class="settings-menu-option"
+                                      :class="{ selected: roleForm.thinking_mode === 'thinking' }"
+                                      @click="roleForm.thinking_mode = 'thinking'; closeDropdown()"
+                                    >
+                                      <strong>thinking</strong><span>深度推理模式</span><svg viewBox="0 0 24 24"><path d="M5 12.5 9.5 17 19 7" /></svg>
+                                    </button>
+                                  </div>
+                                </div>
+                              </div>
+                              <div class="settings-select-row">
+                                <span class="settings-row-copy">
+                                  <span class="settings-row-title">模型</span>
+                                  <span class="settings-row-desc">留空则使用默认模型</span>
+                                </span>
+                                <div
+                                  class="settings-select-wrap"
+                                  :class="{ open: activeDropdown === 'role-model' }"
+                                  @click.stop
+                                >
+                                  <button
+                                    type="button"
+                                    class="settings-select-button"
+                                    @click="toggleDropdown('role-model')"
+                                  >
+                                    {{ roleForm.model_key || '默认模型' }}
+                                    <span class="select-chevron" aria-hidden="true"></span>
+                                  </button>
+                                  <div
+                                    :class="['settings-floating-menu', { dark: activeTheme === 'dark' }]"
+                                    :style="activeDropdown === 'role-model' ? floatingMenuStyle : undefined"
+                                  >
+                                    <button
+                                      type="button"
+                                      class="settings-menu-option"
+                                      :class="{ selected: !roleForm.model_key }"
+                                      @click="roleForm.model_key = ''; closeDropdown()"
+                                    >
+                                      <strong>默认模型</strong><span>使用配置文件中的 default_model</span><svg viewBox="0 0 24 24"><path d="M5 12.5 9.5 17 19 7" /></svg>
+                                    </button>
+                                    <button
+                                      v-for="m in subAgentModels"
+                                      :key="m.name"
+                                      type="button"
+                                      class="settings-menu-option"
+                                      :class="{ selected: roleForm.model_key === m.name }"
+                                      @click="roleForm.model_key = m.name; closeDropdown()"
+                                    >
+                                      <strong>{{ m.name }}</strong><span>{{ m.modes }} · {{ m.multimodal || '纯文本' }}</span><svg viewBox="0 0 24 24"><path d="M5 12.5 9.5 17 19 7" /></svg>
+                                    </button>
+                                  </div>
+                                </div>
+                              </div>
+                              <div class="settings-textarea-row">
+                                <span class="settings-row-title">Prompt Body（Markdown）</span>
+                                <textarea
+                                  :value="roleForm.body_prompt"
+                                  placeholder="角色的自定义 prompt body..."
+                                  @input="roleForm.body_prompt = ($event.target as HTMLTextAreaElement).value"
+                                ></textarea>
+                              </div>
+                            </div>
+                            <div class="role-editor-footer">
+                              <button type="button" class="settings-secondary-button" @click="closeRoleEditor">取消</button>
+                              <button
+                                type="button"
+                                class="settings-primary-button"
+                                :disabled="roleSaving || !roleForm.role_id || !roleForm.name || !roleForm.body_prompt"
+                                @click="saveRole"
+                              >
+                                {{ roleSaving ? '保存中...' : '保存' }}
+                              </button>
+                            </div>
+                          </div>
+                        </div>
+                      </transition>
+                    </section>
+
+                    <section
                       key="admin"
                       class="settings-page admin-monitor-page"
                     >
@@ -1888,6 +2133,8 @@ type PersonalTab =
   | 'tools'
   | 'files'
   | 'data'
+  | 'voice'
+  | 'sub-agents'
   | 'admin';
 
 const baseTabs = [
@@ -1900,7 +2147,8 @@ const baseTabs = [
   { id: 'tools', label: '工具与 Skills', icon: 'wrench' },
   { id: 'files', label: '文件与图片', icon: 'file' },
   { id: 'data', label: '数据管理', icon: 'layers' },
-  { id: 'voice', label: '语音模型', icon: 'mic' }
+  { id: 'voice', label: '语音模型', icon: 'mic' },
+  { id: 'sub-agents', label: '子智能体', icon: 'bot' }
 ] as const satisfies ReadonlyArray<{ id: PersonalTab; label: string; icon: IconKey }>;
 
 const sessionRole = ref('');
@@ -2498,6 +2746,11 @@ watch(
     if (isVisible && tab === 'data') {
       fetchUsageSummary();
     }
+    if (isVisible && tab === 'sub-agents') {
+      loadSubAgentRoles();
+      loadSubAgentSettings();
+      loadSubAgentModels();
+    }
     if (
       isVisible &&
       tab === 'general' &&
@@ -2510,6 +2763,145 @@ watch(
   }
 );
 
+// ----- 子智能体管理 -----
+const subAgentRoles = ref<any[]>([]);
+const subAgentRolesLoading = ref(false);
+const subAgentCompressThreshold = ref(150000);
+const subAgentSettingsSaving = ref(false);
+const subAgentModels = ref<any[]>([]);
+const roleEditorOpen = ref(false);
+const editingRole = ref<any>(null);
+const roleSaving = ref(false);
+const roleForm = ref({
+  role_id: '',
+  name: '',
+  description: '',
+  body_prompt: '',
+  thinking_mode: 'fast',
+  model_key: ''
+});
+
+const loadSubAgentRoles = async () => {
+  subAgentRolesLoading.value = true;
+  try {
+    const resp = await fetch('/api/multiagent/roles', { credentials: 'same-origin' });
+    const data = await resp.json();
+    if (data.success) {
+      subAgentRoles.value = data.roles || [];
+    }
+  } catch (e) {
+    // 静默处理
+  } finally {
+    subAgentRolesLoading.value = false;
+  }
+};
+
+const loadSubAgentModels = async () => {
+  try {
+    const resp = await fetch('/api/multiagent/models', { credentials: 'same-origin' });
+    const data = await resp.json();
+    if (data.success) {
+      subAgentModels.value = data.models || [];
+    }
+  } catch (e) {
+    // 静默处理
+  }
+};
+
+const loadSubAgentSettings = async () => {
+  try {
+    const resp = await fetch('/api/multiagent/settings', { credentials: 'same-origin' });
+    const data = await resp.json();
+    if (data.success && data.settings) {
+      subAgentCompressThreshold.value = data.settings.sub_agent_compress_threshold_tokens || 150000;
+    }
+  } catch (e) {
+    // 静默处理
+  }
+};
+
+const saveSubAgentSettings = async () => {
+  subAgentSettingsSaving.value = true;
+  try {
+    await fetch('/api/multiagent/settings', {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify({ settings: { sub_agent_compress_threshold_tokens: subAgentCompressThreshold.value } })
+    });
+  } finally {
+    subAgentSettingsSaving.value = false;
+  }
+};
+
+const openRoleEditor = (role?: any) => {
+  if (role) {
+    editingRole.value = role;
+    roleForm.value = {
+      role_id: role.role_id || '',
+      name: role.name || '',
+      description: role.description || '',
+      body_prompt: role.body_prompt || '',
+      thinking_mode: role.thinking_mode || 'fast',
+      model_key: role.model_key || ''
+    };
+  } else {
+    editingRole.value = null;
+    roleForm.value = { role_id: '', name: '', description: '', body_prompt: '', thinking_mode: 'fast', model_key: '' };
+  }
+  closeDropdown();
+  roleEditorOpen.value = true;
+};
+
+const closeRoleEditor = () => {
+  roleEditorOpen.value = false;
+  editingRole.value = null;
+  closeDropdown();
+};
+
+const saveRole = async () => {
+  roleSaving.value = true;
+  try {
+    const isEdit = !!editingRole.value;
+    const url = isEdit
+      ? `/api/multiagent/roles/${roleForm.value.role_id}`
+      : '/api/multiagent/roles';
+    const method = isEdit ? 'PUT' : 'POST';
+    const resp = await fetch(url, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify({
+        ...roleForm.value,
+        model_key: roleForm.value.model_key || null
+      })
+    });
+    const data = await resp.json();
+    if (data.success) {
+      closeRoleEditor();
+      await loadSubAgentRoles();
+    }
+  } finally {
+    roleSaving.value = false;
+  }
+};
+
+const deleteRole = async (role: any) => {
+  if (!confirm(`确认删除角色「${role.name}」？`)) return;
+  try {
+    const resp = await fetch(`/api/multiagent/roles/${role.role_id}`, {
+      method: 'DELETE',
+      credentials: 'same-origin'
+    });
+    const data = await resp.json();
+    if (data.success) {
+      await loadSubAgentRoles();
+    }
+  } catch (e) {
+    // 静默处理
+  }
+};
+
 const setActiveTab = (tab: PersonalTab) => {
   activeTab.value = tab;
   closeDropdown();
@@ -2886,6 +3278,123 @@ const applyDefaultHideWorkspaceOption = async (hidden: boolean) => {
 </script>
 
 <style scoped>
+.sub-agent-role-list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+.sub-agent-role-card {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  padding: 11px 0;
+  border-bottom: 1px solid var(--theme-control-border);
+}
+.sub-agent-role-info {
+  flex: 1;
+  min-width: 0;
+}
+.sub-agent-role-name {
+  font-size: 14px;
+  font-weight: 550;
+  color: var(--claude-text);
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.sub-agent-role-tag {
+  font-size: 10px;
+  padding: 1px 8px;
+  border-radius: 999px;
+  font-weight: 400;
+}
+.sub-agent-role-tag.tag-preset {
+  background: color-mix(in srgb, var(--claude-text-secondary) 15%, transparent);
+  color: var(--claude-text-secondary);
+}
+.sub-agent-role-tag.tag-custom {
+  background: color-mix(in srgb, var(--claude-accent) 15%, transparent);
+  color: var(--claude-accent);
+}
+.sub-agent-role-desc {
+  font-size: 12.5px;
+  color: var(--claude-text-secondary);
+  margin-top: 3px;
+  line-height: 1.38;
+}
+.sub-agent-role-meta {
+  font-size: 11px;
+  color: var(--claude-text-secondary);
+  opacity: 0.7;
+  margin-top: 2px;
+}
+.sub-agent-role-actions {
+  display: flex;
+  gap: 6px;
+  flex-shrink: 0;
+}
+
+/* 角色编辑弹窗 — 复用 settings-redesign-card */
+.role-editor-drawer-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--overlay-scrim);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 2147483647;
+}
+.role-editor-drawer-card {
+  display: flex;
+  flex-direction: column;
+  overflow: visible;
+}
+.role-editor-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+  flex-shrink: 0;
+}
+.role-editor-header h2 {
+  font-size: 20px;
+  font-weight: 600;
+  color: var(--claude-text);
+  margin: 0;
+}
+.role-editor-body {
+  flex: 1;
+  overflow-y: auto;
+  overflow-x: visible;
+  min-height: 0;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+.role-editor-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: 8px;
+  padding-top: 12px;
+  flex-shrink: 0;
+}
+.settings-section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+.settings-section-title {
+  font-size: 14px;
+  font-weight: 550;
+  color: var(--claude-text);
+}
+.settings-empty-hint {
+  color: var(--claude-text-secondary);
+  font-size: 13px;
+  padding: 24px 0;
+  text-align: center;
+}
+
 .settings-redesign-card {
   --settings-floating-menu-bg: color-mix(in srgb, var(--surface-soft) 90%, var(--surface-raised));
   --settings-floating-menu-hover: var(--hover-bg);
@@ -3063,7 +3572,8 @@ const applyDefaultHideWorkspaceOption = async (hidden: boolean) => {
 .settings-redesign-tabs::-webkit-scrollbar,
 .settings-redesign-scroll::-webkit-scrollbar,
 .settings-floating-menu::-webkit-scrollbar,
-.app-update-changelog-content::-webkit-scrollbar {
+.app-update-changelog-content::-webkit-scrollbar,
+.role-editor-body::-webkit-scrollbar {
   display: none;
 }
 

static/src/components/sidebar/ConversationSidebar.vue

@@ -547,6 +547,9 @@ const props = withDefaults(
     hostWorkspaceEnabled?: boolean;
     groupByWorkspace?: boolean;
     versioningHostMode?: boolean;
+    /** 当前会话是否仍在运行（用于标记当前正在查看的对话也显示运行中转圈） */
+    currentTaskInProgress?: boolean;
+    currentConversationId?: string;
   }>(),
   {
     showCollapseButton: true,
@@ -559,7 +562,9 @@ const props = withDefaults(
     workspaceKind: 'workspace',
     hostWorkspaceEnabled: false,
     groupByWorkspace: false,
-    versioningHostMode: false
+    versioningHostMode: false,
+    currentTaskInProgress: false,
+    currentConversationId: ''
   }
 );
 
@@ -890,8 +895,15 @@ const completedConversationIds = computed(
         .filter(Boolean)
     )
 );
-const isConversationActive = (conversationId: string) =>
-  activeConversationIds.value.has(String(conversationId || ''));
+const isConversationActive = (conversationId: string) => {
+  if (activeConversationIds.value.has(String(conversationId || ''))) return true;
+  // 后端 runningTasks 库只跟踪跨工作的任务（当前会话排除了），
+  // 所以当前会话的运行态要单独用 currentTaskInProgress 标记。
+  if (props.currentTaskInProgress && String(conversationId || '') === String(props.currentConversationId || '')) {
+    return true;
+  }
+  return false;
+};
 const isConversationCompleted = (conversationId: string) =>
   completedConversationIds.value.has(String(conversationId || ''));
 const isWorkspaceRunning = (workspaceId: string) =>

static/src/composables/useLegacySocket.ts

@@ -19,6 +19,7 @@
 import { io as createSocketClient } from 'socket.io-client';
 import { renderLatexInRealtime } from './useMarkdownRenderer';
 import { getMessageVisibility, messageStartsWork } from '../utils/messageVisibility';
+import { goalModeDebugLog } from '../app/methods/common';
 
 export async function initializeLegacySocket(ctx: any) {
   try {
@@ -803,7 +804,6 @@ export async function initializeLegacySocket(ctx: any) {
         return;
       }
       const convId = data.conversation_id;
-      console.log('[conv-trace] socket:conversation_resolved', data);
 
       // 初始化期间不修改 currentConversationId，避免与 bootstrapRoute 冲突
       if (ctx.initialRouteResolved) {
@@ -814,10 +814,12 @@ export async function initializeLegacySocket(ctx: any) {
         ctx.promoteConversationToTop(convId);
         const pathFragment = ctx.stripConversationPrefix(convId);
         const currentPath = window.location.pathname.replace(/^\/+/, '');
+        const urlPrefix = ctx.multiAgentMode ? '/multiagent/' : '/';
+        const targetPath = `${urlPrefix}${pathFragment}`;
         if (data.created) {
-          history.pushState({ conversationId: convId }, '', `/${pathFragment}`);
+          history.pushState({ conversationId: convId }, '', targetPath);
         } else if (currentPath !== pathFragment) {
-          history.replaceState({ conversationId: convId }, '', `/${pathFragment}`);
+          history.replaceState({ conversationId: convId }, '', targetPath);
         }
       }
     });
@@ -907,10 +909,31 @@ export async function initializeLegacySocket(ctx: any) {
 
     // 用户消息（后台子智能体完成后自动触发）
     ctx.socket.on('user_message', (data) => {
-      if (ctx.usePollingMode && !ctx.waitingForSubAgent) {
+      const isMultiAgentMessage = !!(
+        data?.multi_agent_message ||
+        data?.metadata?.multi_agent_message ||
+        data?.multi_agent_output ||
+        data?.metadata?.multi_agent_output
+      );
+      goalModeDebugLog('legacy_socket_user_message_entry', {
+        usePollingMode: ctx.usePollingMode,
+        waitingForSubAgent: ctx.waitingForSubAgent,
+        isMultiAgentMessage,
+        currentConversationId: ctx.currentConversationId,
+        dataConversationId: data?.conversation_id,
+        message_source: data?.message_source || data?.metadata?.message_source,
+        starts_work: data?.starts_work,
+        auto_message_type: data?.auto_message_type || data?.metadata?.auto_message_type,
+        taskInProgress: ctx.taskInProgress
+      });
+      // 多智能体消息在轮询模式下也需要处理，否则主智能体空闲时子智能体
+      // 推送的消息无法触发前端恢复轮询，必须刷新页面才能看到。
+      if (ctx.usePollingMode && !ctx.waitingForSubAgent && !isMultiAgentMessage) {
+        goalModeDebugLog('legacy_socket_user_message_early_return', { reason: 'polling_mode_no_waiting' });
         return;
       }
       if (!data) {
+        goalModeDebugLog('legacy_socket_user_message_early_return', { reason: 'no_data' });
         return;
       }
       if (data?.conversation_id && data.conversation_id !== ctx.currentConversationId) {
@@ -1002,6 +1025,39 @@ export async function initializeLegacySocket(ctx: any) {
           }
         })();
       }
+      // 多智能体消息没有 task_id，需要主动查找当前对话的运行中任务并恢复轮询。
+      if (isMultiAgentMessage && ctx.usePollingMode && !data?.task_id) {
+        goalModeDebugLog('legacy_socket_user_message_ma_polling_start', {
+          currentConversationId: ctx.currentConversationId
+        });
+        (async () => {
+          try {
+            const { useTaskStore } = await import('../stores/task');
+            const taskStore = useTaskStore();
+            const runningTask = await taskStore.loadRunningTask(ctx.currentConversationId);
+            goalModeDebugLog('legacy_socket_user_message_ma_polling_loaded', {
+              found: !!runningTask,
+              taskId: runningTask?.task_id,
+              taskStatus: runningTask?.status
+            });
+            if (runningTask?.task_id) {
+              taskStore.resumeTask(runningTask.task_id);
+              goalModeDebugLog('legacy_socket_user_message_ma_polling_resumed', {
+                taskId: runningTask.task_id
+              });
+            }
+          } catch (error) {
+            console.warn('恢复多智能体任务轮询失败', error);
+            goalModeDebugLog('legacy_socket_user_message_ma_polling_error', {
+              error: String(error)
+            });
+          }
+        })();
+      }
+      goalModeDebugLog('legacy_socket_user_message_end', {
+        taskInProgress: ctx.taskInProgress,
+        streamingMessage: ctx.streamingMessage
+      });
       ctx.$forceUpdate();
       ctx.conditionalScrollToBottom();
     });
@@ -1590,20 +1646,19 @@ export async function initializeLegacySocket(ctx: any) {
       const hasRunningSubAgents = !!data?.has_running_sub_agents;
       const hasRunningBackgroundCommands = !!data?.has_running_background_commands;
       const hasRunningBackground = hasRunningSubAgents || hasRunningBackgroundCommands;
-      if (!hasRunningBackground) {
-        ctx.taskInProgress = false;
-      } else {
-        ctx.waitingForSubAgent = hasRunningSubAgents;
-        ctx.waitingForBackgroundCommand = hasRunningBackgroundCommands;
-        if (typeof ctx.uiPushToast === 'function') {
-          ctx.uiPushToast({
-            title: '智能体已停止',
-            message: '再次按下停止按钮以结束后台任务',
-            type: 'info'
-          });
-        }
+      const hasRunningMultiAgent = !!data?.has_running_multi_agent;
+      // 主对话已被停止。streaming、stopRequested 都重置。
+      // 如果仍有后台任务在跑，保留 taskInProgress=true 让对话在列表里仍显示“运行中”
+      // （仅影响 UI 标识，不影响输入栏可用性——输入栏只看 streamingMessage）。
+      const stillHasBackground = hasRunningBackground || hasRunningMultiAgent;
+      ctx.streamingMessage = false;
+      ctx.stopRequested = false;
+      ctx.waitingForSubAgent = hasRunningSubAgents;
+      ctx.waitingForBackgroundCommand = hasRunningBackgroundCommands;
+      ctx.taskInProgress = stillHasBackground;
+      if (typeof ctx.scheduleResetAfterTask === 'function') {
+        ctx.scheduleResetAfterTask('socket:task_stopped', { preserveMonitorWindows: true });
       }
-      ctx.scheduleResetAfterTask('socket:task_stopped', { preserveMonitorWindows: true });
     });
 
     // 任务完成（重点：更新Token统计）
@@ -1616,9 +1671,13 @@ export async function initializeLegacySocket(ctx: any) {
       });
       socketLog('任务完成', data);
 
-      // 如果有运行中的子智能体，不重置任务状态
-      if (!data.has_running_sub_agents) {
-        console.log('[DEBUG] 没有运行中的子智能体，重置任务状态');
+      const hasRunningMultiAgent = !!data?.has_running_multi_agent;
+      // 多智能体模式下，若仍有运行中的多智能体实例，保持对话运行态，继续接收后续消息；
+      // 但此时主智能体已空闲，不应阻塞输入区（waitingForSubAgent=false）。
+      if (hasRunningMultiAgent) {
+        console.log('[DEBUG] 多智能体实例仍在运行，保持任务状态但不阻塞输入');
+      } else if (ctx.multiAgentMode || !data.has_running_sub_agents) {
+        console.log('[DEBUG] 没有运行中的子智能体/多智能体，重置任务状态');
         if (ctx.waitingForSubAgent) {
           ctx.waitingForSubAgent = false;
         }
@@ -1652,13 +1711,16 @@ export async function initializeLegacySocket(ctx: any) {
       });
       socketLog('等待子智能体完成:', data);
 
-      // 设置标志：有子智能体在运行，阻止状态重置
-      ctx.waitingForSubAgent = true;
+      // 多智能体模式下，子智能体 idle/running 是常态，不阻塞主对话输入区
+      if (!ctx.multiAgentMode) {
+        // 设置标志：有子智能体在运行，阻止状态重置
+        ctx.waitingForSubAgent = true;
 
-      // 保持任务进行中状态
-      ctx.taskInProgress = true;
-      ctx.streamingMessage = false;
-      ctx.stopRequested = false;
+        // 保持任务进行中状态
+        ctx.taskInProgress = true;
+        ctx.streamingMessage = false;
+        ctx.stopRequested = false;
+      }
 
       console.log('[DEBUG] 当前状态 (after sub_agent_waiting):', {
         taskInProgress: ctx.taskInProgress,

static/src/stores/backgroundCommand.ts

@@ -179,6 +179,23 @@ export const useBackgroundCommandStore = defineStore('backgroundCommand', {
         delete next[normalizedId];
         this.stoppingCommandIds = next;
       }
+    },
+    async stopAllCommands(conversationId?: string): Promise<{ success: boolean; stoppedCount?: number; error?: string }> {
+      try {
+        const resp = await fetch('/api/background_commands/stop_all', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(conversationId ? { conversation_id: conversationId } : {})
+        });
+        const data = await resp.json().catch(() => ({}));
+        if (!resp.ok || !data?.success) {
+          throw new Error(data?.error || `HTTP ${resp.status}`);
+        }
+        await this.fetchCommands();
+        return { success: true, stoppedCount: data?.data?.stopped_count || 0 };
+      } catch (error: any) {
+        return { success: false, error: error?.message || String(error) };
+      }
     }
   }
 });

static/src/stores/conversation.ts

@@ -45,6 +45,7 @@ interface ConversationState {
   runningWorkspaceTasks: any[];
   acknowledgedCompletedTaskIds: string[];
   workspaceGroups: WorkspaceConversationGroup[];
+  multiAgentMode: boolean;
 }
 
 export const useConversationStore = defineStore('conversation', {
@@ -70,7 +71,8 @@ export const useConversationStore = defineStore('conversation', {
     conversationsLimit: 20,
     runningWorkspaceTasks: [],
     acknowledgedCompletedTaskIds: [],
-    workspaceGroups: []
+    workspaceGroups: [],
+    multiAgentMode: false
   }),
   actions: {
     resetConversations() {
@@ -192,8 +194,9 @@ export const useConversationStore = defineStore('conversation', {
       const fetchOffset = refresh ? 0 : group.offset;
       group.loading = true;
       try {
+        const maParam = this.multiAgentMode ? '&multi_agent_mode=1' : '&multi_agent_mode=0';
         const response = await fetch(
-          `/api/conversations?workspace_id=${encodeURIComponent(workspaceId)}&limit=${group.fetchLimit}&offset=${fetchOffset}`
+          `/api/conversations?workspace_id=${encodeURIComponent(workspaceId)}&limit=${group.fetchLimit}&offset=${fetchOffset}${maParam}`
         );
         const data = await response.json();
         if (data.success) {

static/src/stores/subAgent.ts

@@ -9,6 +9,8 @@ interface SubAgent {
   last_tool?: string;
   conversation_id?: string;
   notice_pending?: boolean;
+  display_name?: string;
+  current_context_tokens?: number;
 }
 
 interface SubAgentActivityEntry {
@@ -182,6 +184,24 @@ export const useSubAgentStore = defineStore('subAgent', {
         this.stoppingTaskIds = next;
       }
     },
+    async stopAllAgents(mode: 'terminate' | 'soft_stop'): Promise<{ success: boolean; stoppedCount?: number; error?: string }> {
+      try {
+        const resp = await fetch('/api/sub_agents/stop_all', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ mode })
+        });
+        const data = await resp.json().catch(() => ({}));
+        if (!resp.ok || !data?.success) {
+          throw new Error(data?.error || `HTTP ${resp.status}`);
+        }
+        await this.fetchSubAgents();
+        return { success: true, stoppedCount: data?.data?.stopped_count || 0 };
+      } catch (error: any) {
+        const message = error?.message || String(error);
+        return { success: false, error: message };
+      }
+    },
     stripConversationPrefix(conversationId: string) {
       if (!conversationId) return '';
       return conversationId.startsWith('conv_') ? conversationId.slice(5) : conversationId;

static/src/stores/task.ts

@@ -411,6 +411,10 @@ export const useTaskStore = defineStore('task', {
     startPolling(eventHandler?: (event: any) => void) {
       if (this.isPolling) {
         debugLog('[Task] 轮询已在运行');
+        goalModeDebugLog('taskStore.startPolling_already_running', {
+          taskId: this.currentTaskId,
+          lastEventIndex: this.lastEventIndex
+        });
         debugNotifyLog('[DEBUG_NOTIFY][task] startPolling:already-running', {
           taskId: this.currentTaskId,
           lastEventIndex: this.lastEventIndex
@@ -420,10 +424,16 @@ export const useTaskStore = defineStore('task', {
 
       if (!this.currentTaskId) {
         debugLog('[Task] 没有任务ID，无法启动轮询');
+        goalModeDebugLog('taskStore.startPolling_no_task_id');
         return;
       }
 
       debugLog('[Task] 启动轮询:', this.currentTaskId);
+      goalModeDebugLog('taskStore.startPolling', {
+        taskId: this.currentTaskId,
+        lastEventIndex: this.lastEventIndex,
+        hasHandler: !!(eventHandler || (window as any).__taskEventHandler)
+      });
       debugNotifyLog('[DEBUG_NOTIFY][task] startPolling', {
         taskId: this.currentTaskId,
         lastEventIndex: this.lastEventIndex
@@ -470,8 +480,15 @@ export const useTaskStore = defineStore('task', {
       } = {}
     ) {
       if (!taskId) {
+        goalModeDebugLog('taskStore.resumeTask_no_task_id');
         return;
       }
+      goalModeDebugLog('taskStore.resumeTask', {
+        incomingTaskId: taskId,
+        currentTaskId: this.currentTaskId,
+        isPolling: this.isPolling,
+        resetOffset: options?.resetOffset !== false
+      });
       debugNotifyLog('[DEBUG_NOTIFY][task] resumeTask', {
         incomingTaskId: taskId,
         currentTaskId: this.currentTaskId,
@@ -493,6 +510,11 @@ export const useTaskStore = defineStore('task', {
       this.pollingError = null;
       this.runtimeQueueSnapshotKey = '';
       this.startPolling(options.eventHandler);
+      goalModeDebugLog('taskStore.resumeTask_started', {
+        taskId,
+        isPolling: this.isPolling,
+        lastEventIndex: this.lastEventIndex
+      });
     },
 
     stopPolling(reason = 'manual') {
@@ -525,7 +547,8 @@ export const useTaskStore = defineStore('task', {
         debugLog('[Task] 取消任务:', this.currentTaskId);
 
         const response = await fetch(`/api/tasks/${this.currentTaskId}/cancel`, {
-          method: 'POST'
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' }
         });
 
         if (!response.ok) {
@@ -547,6 +570,7 @@ export const useTaskStore = defineStore('task', {
     async loadRunningTask(conversationId: string | null = null) {
       try {
         debugLog('[Task] 查找运行中的任务');
+        goalModeDebugLog('taskStore.loadRunningTask_start', { conversationId });
 
         const response = await fetch('/api/tasks');
         if (!response.ok) {
@@ -568,6 +592,11 @@ export const useTaskStore = defineStore('task', {
 
         if (runningTask) {
           debugLog('[Task] 发现运行中的任务:', runningTask.task_id);
+          goalModeDebugLog('taskStore.loadRunningTask_found', {
+            taskId: runningTask.task_id,
+            status: runningTask.status,
+            conversationId: runningTask.conversation_id
+          });
 
           this.currentTaskId = runningTask.task_id;
           this.taskStatus = runningTask.status;
@@ -603,9 +632,14 @@ export const useTaskStore = defineStore('task', {
         }
 
         debugLog('[Task] 没有运行中的任务');
+        goalModeDebugLog('taskStore.loadRunningTask_not_found', { conversationId });
         return null;
       } catch (error) {
         console.error('[Task] 加载运行中任务失败:', error);
+        goalModeDebugLog('taskStore.loadRunningTask_error', {
+          conversationId,
+          error: String(error)
+        });
         return null;
       }
     },

static/src/styles/components/chat/_chat-area.scss

@@ -462,8 +462,6 @@
 .message-block {
   margin-bottom: 24px;
   min-width: 0;
-  content-visibility: auto;
-  contain-intrinsic-size: auto 300px;
 }
 
 .message-block.message-block--sub-agent-notice {
@@ -492,11 +490,185 @@
   align-items: flex-end; /* 靠右对齐 */
 }
 
-.message-block--last .user-message:not(.user-message--compact):not(.user-message--brief) {
+/* 多智能体消息：左侧对话气泡，内部渲染 Markdown */
+.user-message.user-message--multi-agent {
+  align-items: flex-start;
+}
+
+.message-block.message-block--multi-agent {
+  margin-bottom: 12px;
+}
+
+.user-message.user-message--multi-agent .message-header {
+  align-self: flex-start;
+}
+
+.user-message.user-message--multi-agent .message-header.message-header--hidden {
+  display: none;
+}
+
+.user-message.user-message--multi-agent .message-text {
+  align-self: flex-start;
+}
+
+.user-message.user-message--multi-agent .message-text.user-bubble-text .bubble-text {
+  white-space: normal;
+  word-break: normal;
+}
+
+/* 首尾元素贴合气泡内边距，避免 XML 内容换行导致的空段落撑开间距 */
+.user-message.user-message--multi-agent .bubble-text .markdown-text-segment > *:first-child {
+  margin-top: 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text .markdown-text-segment > *:last-child {
+  margin-bottom: 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text p:empty {
+  display: none;
+}
+
+.user-message.user-message--multi-agent .bubble-text h1,
+.user-message.user-message--multi-agent .bubble-text h2,
+.user-message.user-message--multi-agent .bubble-text h3,
+.user-message.user-message--multi-agent .bubble-text h4,
+.user-message.user-message--multi-agent .bubble-text h5,
+.user-message.user-message--multi-agent .bubble-text h6 {
+  margin: 14px 0 6px;
+  font-weight: 600;
+  line-height: 1.3;
+  color: var(--claude-text);
+}
+
+.user-message.user-message--multi-agent .bubble-text h1 {
+  font-size: 1.5em;
+}
+
+.user-message.user-message--multi-agent .bubble-text h2 {
+  font-size: 1.3em;
+}
+
+.user-message.user-message--multi-agent .bubble-text h3 {
+  font-size: 1.15em;
+}
+
+.user-message.user-message--multi-agent .bubble-text h4,
+.user-message.user-message--multi-agent .bubble-text h5,
+.user-message.user-message--multi-agent .bubble-text h6 {
+  font-size: 1em;
+}
+
+.user-message.user-message--multi-agent .bubble-text p {
+  margin: 6px 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text strong,
+.user-message.user-message--multi-agent .bubble-text b {
+  font-weight: 700;
+}
+
+.user-message.user-message--multi-agent .bubble-text em,
+.user-message.user-message--multi-agent .bubble-text i {
+  font-style: italic;
+}
+
+.user-message.user-message--multi-agent .bubble-text ul,
+.user-message.user-message--multi-agent .bubble-text ol {
+  margin: 6px 0;
+  padding-left: 1.4em;
+}
+
+.user-message.user-message--multi-agent .bubble-text li {
+  margin: 3px 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text blockquote {
+  margin: 10px 0;
+  padding: 4px 12px;
+  border-left: 3px solid var(--claude-border);
+  color: var(--claude-text-secondary);
+}
+
+.user-message.user-message--multi-agent .bubble-text hr {
+  margin: 14px 0;
+  border: none;
+  border-top: 1px solid var(--claude-border);
+}
+
+/* 代码/表格底色基于气泡色 chip-bg 派生，避免与气泡背景融为一体 */
+.user-message.user-message--multi-agent .bubble-text code {
+  font-family: 'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', 'Menlo', 'Monaco', 'Courier New', monospace;
+  background: color-mix(in srgb, var(--claude-text) 7%, var(--chip-bg));
+  padding: 2px 5px;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+
+.user-message.user-message--multi-agent .bubble-text pre {
+  background: color-mix(in srgb, var(--claude-text) 5%, var(--chip-bg));
+  padding: 10px 12px;
+  border-radius: 8px;
+  overflow-x: auto;
+  margin: 10px 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text pre code {
+  background: transparent;
+  padding: 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 10px 0;
+  background: transparent;
+}
+
+.user-message.user-message--multi-agent .bubble-text .md-table-scroll,
+.user-message.user-message--multi-agent .bubble-text [data-md-table-scroll='1'] {
+  display: block;
+  width: auto;
+  max-width: none;
+  margin: 10px 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+  border: 1px solid var(--claude-border);
+  border-radius: 8px;
+  background: color-mix(in srgb, var(--claude-text) 4%, var(--chip-bg));
+}
+
+.user-message.user-message--multi-agent .bubble-text .md-table-scroll > table,
+.user-message.user-message--multi-agent .bubble-text [data-md-table-scroll='1'] > table {
+  margin: 0;
+}
+
+.user-message.user-message--multi-agent .bubble-text th,
+.user-message.user-message--multi-agent .bubble-text td {
+  border: 1px solid var(--claude-border);
+  padding: 6px 10px;
+  text-align: left;
+  vertical-align: middle;
+  font-size: 14px;
+}
+
+.user-message.user-message--multi-agent .bubble-text th {
+  font-weight: 600;
+  background: color-mix(in srgb, var(--claude-text) 7%, var(--chip-bg));
+}
+
+.message-block--last
+  .user-message:not(.user-message--compact):not(.user-message--brief):not(
+    .user-message--multi-agent
+  ) {
   position: relative;
 }
 
-.message-block--last .user-message:not(.user-message--compact):not(.user-message--brief) .user-bubble-actions {
+.message-block--last
+  .user-message:not(.user-message--compact):not(.user-message--brief):not(
+    .user-message--multi-agent
+  )
+  .user-bubble-actions {
   position: absolute;
   right: 0;
   top: 100%;
@@ -654,29 +826,70 @@
   max-height: var(--bubble-full-height, 9999px);
   white-space: pre-wrap;
   word-break: break-all;
+  position: relative;
 }
 
 .user-message .message-text.user-bubble-text.is-history-loading .bubble-text {
   transition: none !important;
 }
 
-.user-message .message-text.user-bubble-text.is-expandable .bubble-text:not(.is-expanded) {
-  max-height: var(--bubble-fold-height, 240px);
+/* 可折叠气泡容器 */
+.user-message .message-text.user-bubble-text.is-expandable {
+  position: relative;
 }
 
-/* 展开/收起按钮独占一行，不遮挡气泡内容，始终显示 */
+/* 可折叠气泡：多显示一行，底部竖直渐变淡出 */
+.user-message .message-text.user-bubble-text.is-expandable .bubble-text:not(.is-expanded) {
+  max-height: calc(var(--bubble-fold-height, 240px) + 1.6em);
+}
+
+.user-message .message-text.user-bubble-text.is-expandable .bubble-text::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 1.6em;
+  background: linear-gradient(to bottom, transparent, var(--chip-bg));
+  pointer-events: none;
+  opacity: 1;
+  transition: opacity 300ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.user-message .message-text.user-bubble-text.is-expandable .bubble-text.is-expanded::after {
+  opacity: 0;
+}
+
+/* 展开/收起按钮：
+   - 折叠时：向上浮到 bubble-text 底部，与最后一行文字同处一行，带水平渐变
+   - 展开时：margin-top 恢复为 0，单独一行在内容下方 */
 .user-bubble-expand-row {
   display: flex;
   align-items: center;
   justify-content: flex-end;
-  margin-top: -4px;
-  margin-bottom: -10px;
+  margin-top: 0;
+  margin-bottom: 0;
   opacity: 1;
   transform: none;
   pointer-events: auto;
   align-self: flex-end;
   width: 100%;
   min-height: 22px;
+  transition: margin-top 300ms cubic-bezier(0.4, 0, 0.2, 1), background 300ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.user-message .message-text.user-bubble-text.is-expandable .bubble-text:not(.is-expanded) ~ .user-bubble-expand-row {
+  margin-top: -1.6em;
+  min-height: 1.6em;
+  align-items: flex-end;
+  background: linear-gradient(to right, transparent 0%, transparent 50%, var(--chip-bg) 100%);
+  border-bottom-right-radius: 18px;
+}
+
+.user-message .message-text.user-bubble-text.is-expandable .bubble-text.is-expanded ~ .user-bubble-expand-row {
+  margin-top: 0;
+  background: transparent;
+  border-bottom-right-radius: 0;
 }
 
 .user-bubble-expand-row .user-bubble-expand-btn {
@@ -1435,6 +1648,24 @@ show-html:not([data-rendered='1'])[ratio='3:4'] {
   overflow-x: hidden;
 }
 
+/* Markdown 行内代码与加粗：在对话区域背景下给出明确对比 */
+.text-output .text-content :not(pre) > code {
+  font-family:
+    'JetBrains Mono', 'SF Mono', 'Fira Code', 'Consolas', 'Menlo', 'Monaco', 'Courier New',
+    monospace;
+  background: var(--surface-muted);
+  color: var(--text-primary);
+  padding: 2px 5px;
+  border-radius: 4px;
+  font-size: 0.9em;
+}
+
+.text-output .text-content strong,
+.text-output .text-content b {
+  font-weight: 700;
+  color: var(--text-primary);
+}
+
 .text-output .text-content .code-block-wrapper {
   margin-right: calc(var(--chat-content-x) * -1);
   margin-left: calc(var(--chat-content-x) * -1);

static/src/styles/components/panels/_left-panel.scss

@@ -483,12 +483,24 @@
   justify-content: space-between;
   align-items: center;
   font-weight: 600;
-  margin-bottom: 6px;
+  margin-bottom: 4px;
+}
+
+.sub-agent-summary-text {
+  font-size: 13px;
+  color: var(--text-primary);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  flex: 1;
+  min-width: 0;
 }
 
 .sub-agent-status {
   text-transform: capitalize;
   font-size: 12px;
+  flex-shrink: 0;
+  margin-left: 8px;
 }
 
 .sub-agent-status.running {
@@ -499,6 +511,10 @@
   color: var(--state-success);
 }
 
+.sub-agent-status.idle {
+  color: var(--text-secondary);
+}
+
 .sub-agent-status.failed,
 .sub-agent-status.timeout,
 .sub-agent-status.terminated,
@@ -506,6 +522,32 @@
   color: var(--state-danger);
 }
 
+.sub-agent-meta {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 6px;
+}
+
+.sub-agent-name {
+  font-size: 12px;
+  color: var(--text-secondary);
+  font-weight: 500;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  flex: 1;
+  min-width: 0;
+}
+
+.sub-agent-tokens {
+  font-size: 11px;
+  color: var(--text-secondary);
+  opacity: 0.7;
+  flex-shrink: 0;
+  margin-left: 8px;
+}
+
 .sub-agent-summary {
   font-size: 13px;
   color: var(--claude-text);
@@ -956,3 +998,28 @@
 .panel-menu button.active {
   background: var(--theme-tab-active);
 }
+
+/* 后台指令停止按钮 */
+.background-stop-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 28px;
+  padding: 0 10px;
+  border: 1px solid var(--claude-border);
+  border-radius: 10px;
+  background: transparent;
+  color: var(--state-error);
+  font-size: 12px;
+  line-height: 1.2;
+  cursor: pointer;
+  transition: background 140ms ease, color 140ms ease;
+}
+
+.background-stop-btn:hover {
+  background: color-mix(in srgb, var(--state-error) 12%, transparent);
+}
+
+.background-stop-label {
+  font-weight: 500;
+}

utils/context_manager/base.py

@@ -59,6 +59,11 @@ from utils.host_workspace_debug import write_host_workspace_debug
 from utils.media_store import MediaStore
 from utils.token_usage import normalize_usage_payload
 
+try:
+    from modules.multi_agent.role_store import DEFAULT_MUTIAGENTS_DIR
+except Exception:
+    DEFAULT_MUTIAGENTS_DIR = None
+
 AUTO_SHALLOW_PLACEHOLDER = "过早的工具结果已经被自动压缩"
 AUTO_SHALLOW_TOOL_WHITELIST = {
     "write_file",
@@ -101,6 +106,12 @@ class ContextManagerBase:
         
         # 新增：对话持久化管理器
         self.conversation_manager = ConversationManager(base_dir=self.data_dir, project_path=str(self.project_path))
+        # 多智能体对话独立存储到 mutiagents/conversations
+        ma_base_dir = DEFAULT_MUTIAGENTS_DIR if DEFAULT_MUTIAGENTS_DIR else (self.data_dir.parent / "mutiagents")
+        self.multi_agent_conversation_manager = ConversationManager(
+            base_dir=str(ma_base_dir),
+            project_path=str(self.project_path),
+        )
         self.media_store = MediaStore(self.data_dir)
         self.current_conversation_id: Optional[str] = None
         self.auto_save_enabled = True
@@ -126,7 +137,9 @@ class ContextManagerBase:
         self.conversation_metadata[key] = value
         if save and self.current_conversation_id:
             try:
-                self.conversation_manager.update_conversation_metadata(
+                # 路由到正确的 conversation_manager
+                target_manager = getattr(self, "_get_conversation_manager_for_id", lambda _: self.conversation_manager)(self.current_conversation_id)
+                target_manager.update_conversation_metadata(
                     self.current_conversation_id,
                     {key: value}
                 )

utils/context_manager/compression_mixin.py

@@ -102,7 +102,12 @@ class CompressionMixin:
             self.conversation_metadata[k] = v
         if self.current_conversation_id:
             try:
-                self.conversation_manager.update_conversation_metadata(self.current_conversation_id, updates)
+                target_manager = (
+                    self._get_conversation_manager_for_id(self.current_conversation_id)
+                    if hasattr(self, "_get_conversation_manager_for_id")
+                    else self.conversation_manager
+                )
+                target_manager.update_conversation_metadata(self.current_conversation_id, updates)
             except Exception as exc:
                 print(f"[ContextCompression] 更新压缩状态失败: {exc}")
 

utils/context_manager/conversation_mixin.py

@@ -77,6 +77,42 @@ AUTO_SHALLOW_TOOL_WHITELIST = {
 class ConversationMixin:
     """ContextManager conversation mixin 能力 mixin。"""
 
+    def _get_conversation_manager_for_multi_agent_mode(self, multi_agent_mode: bool = False):
+        """根据是否为多智能体会话返回对应的 ConversationManager。"""
+        if multi_agent_mode:
+            return getattr(self, "multi_agent_conversation_manager", None) or self.conversation_manager
+        return self.conversation_manager
+
+    def _get_conversation_manager_for_id(self, conversation_id: str):
+        """根据对话ID判断它属于哪个 ConversationManager。
+
+        优先检查多智能体管理器（如果存在），再回退到普通管理器。
+        """
+        ma_manager = getattr(self, "multi_agent_conversation_manager", None)
+        if not ma_manager:
+            return self.conversation_manager
+        # 先查多智能体索引/文件
+        try:
+            ma_path = ma_manager._get_conversation_file_path(conversation_id)
+            if ma_path.exists():
+                return ma_manager
+        except Exception:
+            pass
+        try:
+            regular_path = self.conversation_manager._get_conversation_file_path(conversation_id)
+            if regular_path.exists():
+                return self.conversation_manager
+        except Exception:
+            pass
+        # 都不存在时：若ID在常规索引中则走常规，否则默认走多智能体（兼容新建对话后立刻保存）
+        try:
+            regular_index = self.conversation_manager._load_index()
+            if conversation_id in regular_index:
+                return self.conversation_manager
+        except Exception:
+            pass
+        return ma_manager
+
     def start_new_conversation(
         self,
         project_path: str = None,
@@ -117,8 +153,10 @@ class ConversationMixin:
         except Exception as exc:
             print(f"[Skills] 同步失败: {exc}")
         
-        # 创建新对话
-        conversation_id = self.conversation_manager.create_conversation(
+        # 创建新对话：多智能体对话使用独立的 conversation_manager
+        is_multi_agent = bool((metadata_overrides or {}).get("multi_agent_mode"))
+        target_manager = self._get_conversation_manager_for_multi_agent_mode(is_multi_agent)
+        conversation_id = target_manager.create_conversation(
             project_path=project_path,
             thinking_mode=thinking_mode,
             run_mode=run_mode or ("thinking" if thinking_mode else "fast"),
@@ -155,8 +193,20 @@ class ConversationMixin:
         if self.current_conversation_id and self.conversation_history:
             self.save_current_conversation()
         
-        # 加载指定对话
-        conversation_data = self.conversation_manager.load_conversation(conversation_id)
+        # 加载指定对话：先按ID路由到对应 manager
+        target_manager = self._get_conversation_manager_for_id(conversation_id)
+        conversation_data = target_manager.load_conversation(conversation_id)
+        if not conversation_data:
+            # 兜底：如果目标 manager 没有，再尝试另一个
+            fallback_manager = (
+                self.conversation_manager
+                if target_manager is self.multi_agent_conversation_manager
+                else self.multi_agent_conversation_manager
+            )
+            try:
+                conversation_data = fallback_manager.load_conversation(conversation_id)
+            except Exception:
+                conversation_data = None
         if not conversation_data:
             print(f"⌘ 对话 {conversation_id} 不存在")
             return False
@@ -279,7 +329,8 @@ class ConversationMixin:
         
         try:
             run_mode = getattr(self.main_terminal, "run_mode", None) if hasattr(self, "main_terminal") else None
-            success = self.conversation_manager.save_conversation(
+            target_manager = self._get_conversation_manager_for_id(self.current_conversation_id)
+            success = target_manager.save_conversation(
                 conversation_id=self.current_conversation_id,
                 messages=self.conversation_history,
                 project_path=str(self.project_path),
@@ -310,7 +361,8 @@ class ConversationMixin:
         try:
             run_mode = getattr(self.main_terminal, "run_mode", None) if hasattr(self, "main_terminal") else None
             model_key = getattr(self.main_terminal, "model_key", None) if hasattr(self, "main_terminal") else None
-            self.conversation_manager.save_conversation(
+            target_manager = self._get_conversation_manager_for_id(self.current_conversation_id)
+            target_manager.save_conversation(
                 conversation_id=self.current_conversation_id,
                 messages=self.conversation_history,
                 project_path=str(self.project_path),
@@ -325,9 +377,38 @@ class ConversationMixin:
         except Exception as e:
             print(f"⌘ 自动保存异常: {e}")
 
-    def get_conversation_list(self, limit: int = 50, offset: int = 0, non_empty: bool = False) -> Dict:
-        """获取对话列表"""
-        return self.conversation_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty)
+    def get_conversation_list(self, limit: int = 50, offset: int = 0, non_empty: bool = False, multi_agent_mode: Optional[bool] = None) -> Dict:
+        """获取对话列表。
+
+        多智能体对话存储在独立目录，需要合并普通管理器和多智能体管理器的结果。
+        """
+        # 多智能体模式只查多智能体管理器；常规模式只查普通管理器；None 时合并
+        if multi_agent_mode is True:
+            ma_manager = getattr(self, "multi_agent_conversation_manager", None)
+            if ma_manager:
+                return ma_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=multi_agent_mode)
+            return self.conversation_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=multi_agent_mode)
+        if multi_agent_mode is False:
+            return self.conversation_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=multi_agent_mode)
+
+        # None：合并两个管理器的结果
+        regular = self.conversation_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=False)
+        ma_manager = getattr(self, "multi_agent_conversation_manager", None)
+        if not ma_manager:
+            return regular
+        ma = ma_manager.get_conversation_list(limit=limit, offset=offset, non_empty=non_empty, multi_agent_mode=True)
+
+        merged_conversations = list(regular.get("conversations", [])) + list(ma.get("conversations", []))
+        merged_conversations.sort(key=lambda x: x.get("updated_at") or "", reverse=True)
+        total = (regular.get("total") or 0) + (ma.get("total") or 0)
+        result = merged_conversations[offset:offset + limit]
+        return {
+            "conversations": result,
+            "total": total,
+            "limit": limit,
+            "offset": offset,
+            "has_more": offset + limit < total
+        }
 
     def delete_conversation_by_id(self, conversation_id: str) -> bool:
         """删除指定对话"""
@@ -338,7 +419,8 @@ class ConversationMixin:
             self.todo_list = None
         elif self.current_conversation_id and self.conversation_history:
             try:
-                conversation_data = self.conversation_manager.load_conversation(self.current_conversation_id)
+                target_manager = self._get_conversation_manager_for_id(self.current_conversation_id)
+                conversation_data = target_manager.load_conversation(self.current_conversation_id)
                 if not conversation_data:
                     self.current_conversation_id = None
                     self.conversation_history = []
@@ -349,8 +431,25 @@ class ConversationMixin:
             except Exception as exc:
                 print(f"⌘ 刷新待办列表失败: {exc}")
                 self.todo_list = None
-        
-        return self.conversation_manager.delete_conversation(conversation_id)
+
+        # 先定位对话所在 manager，再删除；两个目录都尝试兜底
+        target_manager = self._get_conversation_manager_for_id(conversation_id)
+        try:
+            if target_manager.load_conversation(conversation_id):
+                return target_manager.delete_conversation(conversation_id)
+        except Exception:
+            pass
+        fallback_manager = (
+            self.conversation_manager
+            if target_manager is self.multi_agent_conversation_manager
+            else self.multi_agent_conversation_manager
+        )
+        try:
+            if fallback_manager.load_conversation(conversation_id):
+                return fallback_manager.delete_conversation(conversation_id)
+        except Exception:
+            pass
+        return False
 
     def search_conversations(self, query: str, limit: int = 20) -> List[Dict]:
         """搜索对话"""

utils/context_manager/message_mixin.py

@@ -84,7 +84,7 @@ class MessageMixin:
         """扫描工作区 .astrion/user_upload 目录，按修改时间倒序生成最近上传文件列表。"""
         try:
             project_path = Path(getattr(self, "project_path", ".") or ".").expanduser().resolve()
-            uploads_dir = project_path / ".agents" / "user_upload"
+            uploads_dir = project_path / ".astrion" / "user_upload"
             if not uploads_dir.is_dir():
                 return ""
             files = []

utils/context_manager/project_mixin.py

@@ -218,7 +218,7 @@ class ProjectMixin:
             add_entry(entry)
 
         # 根目录浅扫会跳过点目录；内部文件迁移到 .agents 后，单独展示这几个对模型有意义的目录。
-        agents_dir = self.project_path / ".agents"
+        agents_dir = self.project_path / ".astrion"
         for internal_name in ("skills", "user_upload", "compact_result", "review"):
             internal_dir = agents_dir / internal_name
             if internal_dir.exists() and internal_dir.is_dir():

utils/context_manager/token_mixin.py

@@ -173,8 +173,12 @@ class TokenMixin:
         target_id = conversation_id or self.current_conversation_id
         if not target_id:
             return None
-        
-        return self.conversation_manager.get_token_statistics(target_id)
+
+        # 路由到正确的 conversation_manager（支持多智能体会话独立存储）
+        target_manager = getattr(
+            self, "_get_conversation_manager_for_id", lambda _: self.conversation_manager
+        )(target_id)
+        return target_manager.get_token_statistics(target_id)
 
     def get_current_context_tokens(self, conversation_id: str = None) -> int:
         """