chore: encourage sub agent usage

core/main_terminal.py

@@ -1373,7 +1373,7 @@ class MainTerminal:
                 "type": "function",
                 "function": {
                     "name": "create_sub_agent",
-                    "description": "创建新的子智能体任务。需要提供任务摘要、详细要求、交付目录以及可供参考的文件列表。注意：同一时间最多运行5个子智能体。",
+                    "description": "创建新的子智能体任务。适合大规模信息搜集、网页提取与多文档总结等会占用大量上下文的工作，需要提供任务摘要、详细要求、交付目录以及参考文件。注意：同一时间最多运行5个子智能体。",
                     "parameters": {
                         "type": "object",
                         "properties": {
@@ -1387,7 +1387,7 @@ class MainTerminal:
                                 "items": {"type": "string"},
                                 "maxItems": 10
                             },
-                            "timeout_seconds": {"type": "integer", "description": "子智能体最大运行秒数（默认180秒）"}
+                            "timeout_seconds": {"type": "integer", "description": "子智能体最大运行秒数：单/双次搜索建议180秒，多轮搜索整理建议300秒，深度调研或长篇分析可设600秒"}
                         },
                         "required": ["agent_id", "summary", "task", "target_dir"]
                     }
@@ -2031,6 +2031,11 @@ class MainTerminal:
             if todo_prompt:
                 messages.append({"role": "system", "content": todo_prompt})
         
+        if self.tool_category_states.get("sub_agent", True):
+            sub_agent_prompt = self.load_prompt("sub_agent_guidelines").strip()
+            if sub_agent_prompt:
+                messages.append({"role": "system", "content": sub_agent_prompt})
+        
         # 添加对话历史（保留完整结构，包括tool_calls和tool消息）
         for conv in context["conversation"]:
             metadata = conv.get("metadata") or {}

prompts/sub_agent_guidelines.txt

@@ -0,0 +1,17 @@
+# 子智能体工具指南
+
+当你通过 `create_sub_agent`/`wait_sub_agent` 管理子智能体时，请遵循以下规则：
+
+1. **何时创建**：当单个回复难以在时限内完成、需要长时间探索/编写大量文件或会阻塞主智能体上下文时，再考虑创建子智能体。特别是涉及大量信息搜集、网页提取、跨多篇资料的阅读与总结、需要输出结构化文件的任务，应该优先使用子智能体，避免主对话被海量搜索结果占满。
+2. **描述方式**：调用 `create_sub_agent` 前，先总结任务目标（summary）、详细分工（task），并指明交付目录（target_dir）以及需要一并提供的参考文件列表。任务描述要清晰、可执行，不要把问题交给子智能体自行理解。
+3. **参考目录**：主智能体可将必要的文件列入 `reference_files`；这些文件会在子智能体的 `references/` 目录下以只读方式提供，适合提供需求文档、接口约束或已有实现片段。不要传递包含敏感信息或过于庞大的目录。
+4. **交付目录要求**：子智能体只能在其 `deliverables/` 下输出成果，主智能体最终会把该目录复制到 `target_project_dir/子任务ID_deliverables`。交付目录必须包含：
+   - `result.md`：用中文或中英双语写明任务完成情况、交付清单、风险与下一步建议。
+   - 任务成果文件：按照主任务约定的路径/格式组织，必要时包含 README/使用说明。
+5. **等待与跟进**：创建后使用 `wait_sub_agent` 轮询；如超时或失败，需要主动查看 `copied_path` 分析原因，再决定是否重试或人工补救。不要在子任务运行期间向其发送额外消息，它无法与主智能体实时通信。设置 `timeout_seconds` 时可参考：
+   - 单/双次搜索即可完成的任务：180 秒；
+   - 需要多轮搜索、整理多篇资料：300 秒；
+   - 深度调研/多份长文总结：600 秒（上限依据配置）
+6. **善后**：记录系统返回的 `system_message`，同步给用户；若交付不满足预期，可在主流程中补充说明或直接修改复制出的成果。
+
+牢记：主智能体与子智能体完全隔离，只能通过上述API交互。提供明确任务、参考和交付标准，才能让子智能体按预期产出可直接交付的结果。