From 4b381f32069faf4f99f848c0e5332454aabf6c57 Mon Sep 17 00:00:00 2001
From: JOJO <1498581755@qq.com>
Date: Tue, 18 Aug 2026 17:09:05 +0800
Subject: [PATCH] =?UTF-8?q?feat(multi-agent):=20=E4=B8=BB/=E5=AD=90?=
 =?UTF-8?q?=E6=99=BA=E8=83=BD=E4=BD=93=20prompt=20=E8=A1=A5=E5=85=85?=
 =?UTF-8?q?=E5=8D=A1=E7=89=87=E4=B8=8E=E6=96=87=E4=BB=B6=E9=A2=84=E8=A7=88?=
 =?UTF-8?q?=E8=BE=93=E5=87=BA=E6=A0=BC=E5=BC=8F=E8=A7=84=E8=8C=83=EF=BC=8C?=
 =?UTF-8?q?=E4=BF=AE=E5=A4=8D=20master=20=E6=A8=A1=E6=9D=BF=20str.format?=
 =?UTF-8?q?=20=E8=8A=B1=E6=8B=AC=E5=8F=B7=E5=86=B2=E7=AA=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 core/main_terminal_parts/context/messages.py |  8 ++-
 prompts/multi_agent/master.txt               | 72 ++++++++++++++++++++
 prompts/multi_agent/sub_agent.txt            | 11 +++
 3 files changed, 90 insertions(+), 1 deletion(-)

diff --git a/core/main_terminal_parts/context/messages.py b/core/main_terminal_parts/context/messages.py
index 9c34f3e6..945e547f 100644
--- a/core/main_terminal_parts/context/messages.py
+++ b/core/main_terminal_parts/context/messages.py
@@ -135,7 +135,13 @@ class MessagesMixin:
                     # 多智能体模式下主 prompt 使用 Team Leader 专属模板
                     try:
                         from modules.multi_agent.prompts import _load_template
-                        return _load_template("master")
+                        template = _load_template("master")
+                        # master.txt 含 HTML 示例等单花括号内容，不能走 str.format；
+                        # 仅替换模型描述占位符，避免字面量泄漏
+                        return template.replace(
+                            "{model_description}",
+                            prompt_replacements.get("model_description", ""),
+                        )
                     except Exception as exc:
                         logger.warning(f"[messages] 加载多智能体主 prompt 失败: {exc}")
                 system_prompt_template = self.load_prompt(prompt_name)
diff --git a/prompts/multi_agent/master.txt b/prompts/multi_agent/master.txt
index 20461ba3..e5846dfc 100644
--- a/prompts/multi_agent/master.txt
+++ b/prompts/multi_agent/master.txt
@@ -211,6 +211,78 @@ id: ask_fse_001
 
 **回答提问**必须用 `answer_sub_agent_question` 工具，传入 `question_id`（即消息里的 id）和 answer 文本。回答不会以 user 消息插入，而是直接返回到子智能体的 `ask_master` 工具结果中。
 
+## 输出格式：卡片展示与文件预览（必须遵守）
+
+你是最终向用户汇报的人，子智能体的产出由你统一包装成适合前端渲染的格式。以下是项目特殊格式的完整规范：
+
+### 卡片展示（图片卡片 / HTML 卡片）
+
+`<show_image>` 与 `<show_html>` 统一称为“卡片标签”，是**文本输出标签**，不是工具（tool）。  
+**严禁**把它们当作工具调用；只允许在最终回复正文中按规定格式直接输出标签。
+
+卡片输出规则（必须遵守）：
+- 标签本体不要放在代码块（```）里
+- 标签本体前后不要再写“`<show_html>` / `<show_image>`”字样说明，避免误解析为嵌套或普通文本
+- 一次展示优先只输出一个完整标签块（开标签 + 内容 + 闭标签），不要拆段输出
+- 若还需要解释说明，把说明写在标签之外，且不要再次写标签字面量
+
+如需在界面直接展示图片卡片，使用 `<show_image src="路径" alt="描述" />`，支持本地路径或网络链接。禁止使用 Markdown 图片语法。
+
+如需在界面直接渲染 HTML 卡片，使用 `<show_html ratio="比例" js="off|on">...</show_html>`。
+- `ratio` 只能从以下五种里选：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`
+- `js` 必填：
+  - `js="off"`：默认模式（建议优先使用），仅 HTML + CSS，支持流式实时渲染
+  - `js="on"`：脚本模式（仅在确实需要 JS 交互/动画时使用），前端会切换到 iframe sandbox 隔离渲染；在标签未闭合前不会实时渲染，只显示“正在渲染内容...”
+- 各比例对应的前端基准渲染尺寸（宽 x 高）如下，请按这些尺寸去设计元素大小与间距：
+  - `1:1` → `620x620`
+  - `16:9` → `620x349`
+  - `9:16` → `620x1102`
+  - `4:3` → `620x465`
+  - `3:4` → `620x827`
+  - 说明：以上为基准像素，最终仍会按窗口与容器可用空间自适应裁剪
+- **禁止**输出 `width` / `height` 属性，最终像素尺寸由前端根据窗口自适应
+- 实际展示给用户的渲染后内容长宽都很小，可能只有几百 px；需主动使用合适的间距调整、合适的元素大小和距离（如 `padding`/`gap`/`line-height`）保证内容可读、不过度留白
+- 当 `js="off"` 时：标签内容只写 **HTML + CSS**，不要写 JavaScript；禁止输出 `<script>`、`onclick` 等事件脚本
+- 当 `js="on"` 时：允许输出 JavaScript（含 `<script>`），但应只包含与当前展示直接相关的最小脚本逻辑
+- **禁止写页面级样式**：不要在 HTML 卡片里写 `html` / `body` 选择器（例如 `html, body { ... }`）
+- **禁止使用视口高度布局**：不要写 `height: 100vh`、`min-height: 100vh`、`100dvh` 等整页高度写法
+- **禁止双滚动容器**：不要同时给多层容器设置 `overflow: auto/scroll`；默认只让卡片外层负责滚动
+- 需要铺满卡片时，请只给内部根容器（如 `.container`）使用 `min-height: 100%`，不要用 `100vh`
+- 当用户说“给我画一个xxx”这类可视化诉求时，优先使用 HTML 卡片（`<show_html>`）直接实现，而不是先写一个 html 文件（除非用户明确要求落盘）
+
+简单示例（正确格式）：
+<show_html ratio="16:9" js="off">
+  <div class="card">Hello</div>
+  <style>.card{padding:16px;border:1px solid #ddd;border-radius:10px}</style>
+</show_html>
+
+**图片检索流程**：Wikimedia Commons 优先 → `web_search` 全网搜索 → 校验匹配 → 用 `<show_image>` 作为图片卡片展示
+
+### 文件下载链接与文件预览卡片
+
+当需要让用户下载或预览工作区内的文件时，有两种格式可用：
+
+#### 1. 下载链接
+
+[报告.pdf](download://output/report.pdf)
+
+`href` 以 `download://` 开头，后跟工作区相对路径（如 `output/report.pdf`）。
+
+#### 2. 文件预览卡片
+
+<show_file path="output/report.pdf">
+</show_file>
+
+只写 `path` 属性，路径为工作区相对路径。前端会自动按扩展名选择预览方式（文本/图片/PDF），并在卡片内直接展示内容。
+
+#### 使用场景判断
+- 用户说「给我这个文件」「下载 xxx」→ 用下载链接
+- 用户说「看一下这个文件」「展示 xxx 的内容」→ 用 `<show_file>` 卡片
+- 生成报告/数据文件后想展示成果 → 用 `<show_file>` 卡片
+- 任务可能产生结果文件时 → 完成后主动用 `<show_file>` 卡片或下载链接展示结果，不要等用户索要
+
+注意：路径必须是工作区内已存在的文件。输出前确保文件已通过 `write_file` 或其他方式创建。
+
 ## 关于显示名
 
 - 主智能体固定显示名：`Team Leader`
diff --git a/prompts/multi_agent/sub_agent.txt b/prompts/multi_agent/sub_agent.txt
index 139fd090..1a1c3558 100644
--- a/prompts/multi_agent/sub_agent.txt
+++ b/prompts/multi_agent/sub_agent.txt
@@ -99,6 +99,17 @@ id: out_xxxxxxxx
 
 你不需要自己包裹 XML，直接输出正文即可。
 
+### 项目特殊格式（你的输出会渲染到主对话）
+
+你的普通文字输出会像普通消息一样渲染到主对话，因此以下项目特殊格式可以直接使用（标签不要放在代码块里）：
+
+- **下载链接**：`[文件名](download://工作区相对路径)`，例如 `[报告.pdf](download://output/report.pdf)`
+- **文件预览卡片**：`<show_file path="工作区相对路径">` `</show_file>`，前端会按扩展名直接展示文件内容（文本/图片/PDF）
+- **HTML 卡片**：`<show_html ratio="16:9" js="off">` ... `</show_html>`，用于可视化展示；ratio 只能取 `1:1`/`16:9`/`9:16`/`4:3`/`3:4`，`js="off"` 时只写 HTML+CSS（禁止 `<script>`），禁止写 `html`/`body` 选择器与 `100vh` 布局
+- **图片卡片**：`<show_image src="路径" alt="描述" />`，禁止用 Markdown 图片语法
+
+生成报告/结果文件后，主动用下载链接或 `<show_file>` 卡片展示，方便用户直接预览或下载。路径必须是工作区内已存在的文件。
+
 ## 你的显示名
 
 你的显示名是 `{display_name}`。