From b91a45639f266538c7508d9348f8c52d44f19329 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Mon, 25 May 2026 20:23:33 +0800
Subject: [PATCH 01/10] =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E4=B8=8B=E6=8B=89?=
 =?UTF-8?q?=E6=A1=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/multi-agent-frontend-dev.md |  18 ++-
 .../pages/RoundtablePlanningPage.tsx          | 108 +++++++++++++++---
 .../backend/app/gateway/routers/intent.py     |  10 +-
 .../app/gateway/routers/multi_agent.py        |  10 +-
 .../backend/app/gateway/routers/recommend.py  |   7 +-
 5 files changed, 121 insertions(+), 32 deletions(-)

diff --git a/frontend-web/docs/multi-agent-frontend-dev.md b/frontend-web/docs/multi-agent-frontend-dev.md
index 298536ec..f4336e7c 100644
--- a/frontend-web/docs/multi-agent-frontend-dev.md
+++ b/frontend-web/docs/multi-agent-frontend-dev.md
@@ -10,7 +10,7 @@
 
 - **整页只有一个文件**：`RoundtablePlanningPage.tsx`（≈ 3 621 行）。三步 UI 通过 `currentStep ∈ {1,2,3}` 切换，不使用 React Router 子路由。
 - **不使用 LangGraph SDK**：所有 API 都是自研的 `apiFetch` + `ReadableStream` SSE 解析（见 `api/intent.ts`、`api/recommend.ts`、`api/multi-agent.ts`）。
-- **唯一默认模型**：`DEFAULT_MODEL = "deepseek-chat"`（页面常量，写在 `RoundtablePlanningPage.tsx`）。`useModels()` 只用于 Persona 抽屉的下拉选项。
+- **不写死模型名**：与 `/page/canvas/ai-writing` 同样的策略 —— 全局选中模型由 `selectedModel` state 维护，首次 `useModels()` 完成后初始化为 `availableModels[0].name`，顶栏「模型」下拉可切换。所有 API 调用统一传 `model: selectedModel || undefined`；后端缺省由 `lead_agent._resolve_model_name()` 回退到 `config.yaml` 的 `models[0]`。**内网部署只需在 `config.yaml` 配自家模型即可，前后端均无需改动**。
 - **席位区间硬约束**：推荐弹窗要求 **2 ≤ 选中数 ≤ 8**（`MIN_SELECTED` / `MAX_SELECTED`）。
 - **总控编排循环上限**：`MAX_CYCLES = 8`，超出后强制停止并 toast。
 - **席位派活策略**：**顺序**（不是并行）。旧实现并行触发多路 SSE 会让浏览器卡顿，现已改为顺序。
@@ -364,13 +364,22 @@ isOrchestrating = false
 - 抽屉控件：
   - **System Prompt**：仅前端记录（后端覆写未开放）
   - **Temp**：仅前端记录
-  - **推理模型**：选项来自 `useModels()`，默认 `DEFAULT_MODEL`
+  - **推理模型**：选项来自 `useModels()`；显示值优先级 `agentConfigs[seat]?.model > selectedModel`
 - 「参数覆盖并重启动算研讨」按钮 → `handleSaveAgentAndRecalculate`：
   - 把新的 `(seatId, model)` 写入 `agentConfigs`
   - 追加一条「⚡ [模型偏好已保存] ...」对话气泡
-  - **不**立即重启编排；下一轮该席位被派活时 `runOrchestration` 内会读 `agentConfigs[meta.speakerId]?.model` 作为 special 调用的 `model` 参数
+  - **不**立即重启编排；下一轮该席位被派活时 `runOrchestration` 内会读 `agentConfigs[meta.speakerId]?.model || selectedModel || undefined` 作为 special 调用的 `model` 参数
 
-### 5.6 草稿持久化（`utils/drafts.ts`）
+### 5.6 全局模型选择器（顶栏）
+
+- **位置**：顶栏右侧「新建任务」按钮左边，`<select>` 包在带 `Cpu` 图标的标签里
+- **state**：`const [selectedModel, setSelectedModel] = useState<string>("")`
+- **初始化**：`useEffect(() => ...)` 在 `availableModels` 首次返回后把 `selectedModel` 设为 `availableModels[0].name`；后端配置变化导致当前选中 model 不在列表里时也回退到首项
+- **传参规则**：所有 5 个 API 调用点（`initIntent` / `streamIntent` / `streamRecommend` / `initMultiAgent` / `streamMultiAgent` leader / `streamMultiAgent` special）都传 `selectedModel || undefined`；special 还会先看 `agentConfigs[seat]?.model` per-seat 覆盖
+- **禁用态**：`availableModels.length === 0` 或 `modelsLoading` → `disabled`，placeholder 显示「加载中…」或「未配置模型」
+- **可改换为 Radix Select**：当前用原生 `<select>` 与 Persona 抽屉保持一致；如需统一样式可改为 `@/components/ui/select`，行为不变
+
+### 5.7 草稿持久化（`utils/drafts.ts`）
 
 - Key：`roundtable-planning:drafts:v1`（`localStorage`）
 - 草稿快照含：`step1.{intentThreadId, intentReady, interactiveMessages, timelineEntries}`、`step2.{threadIds, coordinatorName, step2RoundtableDialogues, lastLeaderContent, hasConsensus, consensusPercentage, budgetLimit}`、`furthestStep`
@@ -544,7 +553,6 @@ interface StreamMultiAgentResult {
 
 | 常量 | 值 | 位置 |
 |------|----|------|
-| `DEFAULT_MODEL` | `"deepseek-chat"` | RoundtablePlanningPage |
 | `COMMANDER_SEAT_ID` | `1` | RoundtablePlanningPage |
 | `MAX_CYCLES` | `8` | RoundtablePlanningPage（`runOrchestration` 内） |
 | `MIN_SELECTED` / `MAX_SELECTED` | `2` / `8` | RecommendAgentsDialog |
diff --git a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
index abecde29..4ae16256 100644
--- a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
+++ b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
@@ -26,7 +26,13 @@
  * 7) **Persona 抽屉**改的 model 不会立即重启编排，下一轮该席位被派活时由 `runOrchestration`
  *    读 `agentConfigs[meta.speakerId]?.model` 传入 special。prompt / temp 当前**仅前端记录**。
  *
- * 8) **常量**：`DEFAULT_MODEL`、`MAX_CYCLES=8`、`COMMANDER_SEAT_ID=1`、`INTENT_READY_RE`。
+ * 8) **模型选择**：不再硬编码 "deepseek-chat"。全局选中 model 由 `selectedModel`
+ *    state 维护（首次 `useModels()` 完成后初始化为 `availableModels[0].name`），
+ *    顶栏「模型」下拉可切换；Persona 抽屉的 per-seat 覆盖更高优先级。所有 API 调用
+ *    传 `selectedModel || undefined`，后端缺省由 `lead_agent._resolve_model_name()`
+ *    回退到 `config.yaml` 的 `models[0]`。内网部署只需配 `config.yaml` 即可。
+ *
+ * 9) **常量**：`MAX_CYCLES=8`、`COMMANDER_SEAT_ID=1`、`INTENT_READY_RE`。
  *
  * 调试开关（默认开启）：
  *   window.__MULTI_AGENT_INIT_TIMING__   // /api/multi-agent/init 各阶段耗时
@@ -189,7 +195,13 @@ function getAvatar(type: string, size: string = "h-8 w-8") {
 }
 
 // --- Multi-agent backend wiring ---
-const DEFAULT_MODEL = "deepseek-chat";
+//
+// 模型选择策略（与 /page/canvas/ai-writing 对齐,不再写死 "deepseek-chat"）:
+// - 全局选中模型由 selectedModel state 维护(首次 useModels 完成后初始化为 models[0].name)
+// - 所有 API 调用传 model 时统一用 selectedModel || undefined;后端缺省由
+//   lead_agent._resolve_model_name() 回退到 config.yaml 的 models[0]
+// - Persona 抽屉的 per-seat 覆盖优先(agentConfigs[seat]?.model > selectedModel)
+// 内网部署只需在 config.yaml 配自家模型,前后端都不需要再硬编码具体模型名。
 
 type RoleEntry = {
   id: number;
@@ -373,16 +385,24 @@ export default function RoundtablePlanningPage() {
   // for each of them concurrently instead of only the most recently set one.
   const [activeSpeakerSet, setActiveSpeakerSet] = useState<Set<number>>(new Set());
 
-  // Custom presets for agent model, weight, temperature and prompt editors
+  // Custom presets for agent model, weight, temperature and prompt editors.
+  // model 字段留空,运行时由 runOrchestration 解析为
+  //   agentConfigs[seat]?.model || selectedModel || undefined
+  // 即「席位覆盖优先,否则跟随全局选中模型,否则让后端回退到 config.yaml models[0]」。
   const [agentConfigs, setAgentConfigs] = useState<{ [key: number]: { model: string; weight: number; prompt: string; temp: number } }>({
-    2: { model: DEFAULT_MODEL, weight: 90, temp: 0.2, prompt: "你负责解析核心任务、资源极限和用户目标偏好，监督全局研商收敛。" },
-    3: { model: DEFAULT_MODEL, weight: 85, temp: 0.3, prompt: "你负责搜集电力、通信系统、历史极端部署条件情报，支持备灾架构体系。" },
-    4: { model: DEFAULT_MODEL, weight: 88, temp: 0.1, prompt: "你评估服务器机房热载荷、算力并发承载极限，预报运行瓶颈与风险时钟。" },
-    5: { model: DEFAULT_MODEL, weight: 92, temp: 0.4, prompt: "你负责双全栈主备建模设计，高内聚低耦合，规避不可预知停机崩溃。" },
-    6: { model: DEFAULT_MODEL, weight: 95, temp: 0.1, prompt: "你作为安全主管，严厉把控预算开销与合规通过率防线，识别计划漏洞。" },
-    7: { model: DEFAULT_MODEL, weight: 80, temp: 0.4, prompt: "你负责对72小时里程碑执行路径规划、重排和资源调配演练序列。" },
+    2: { model: "", weight: 90, temp: 0.2, prompt: "你负责解析核心任务、资源极限和用户目标偏好，监督全局研商收敛。" },
+    3: { model: "", weight: 85, temp: 0.3, prompt: "你负责搜集电力、通信系统、历史极端部署条件情报，支持备灾架构体系。" },
+    4: { model: "", weight: 88, temp: 0.1, prompt: "你评估服务器机房热载荷、算力并发承载极限，预报运行瓶颈与风险时钟。" },
+    5: { model: "", weight: 92, temp: 0.4, prompt: "你负责双全栈主备建模设计，高内聚低耦合，规避不可预知停机崩溃。" },
+    6: { model: "", weight: 95, temp: 0.1, prompt: "你作为安全主管，严厉把控预算开销与合规通过率防线，识别计划漏洞。" },
+    7: { model: "", weight: 80, temp: 0.4, prompt: "你负责对72小时里程碑执行路径规划、重排和资源调配演练序列。" },
   });
 
+  // 全局选中模型(对应顶栏「模型」下拉)。
+  // 首次 useModels 加载完成后由下面的 useEffect 初始化为 availableModels[0].name,
+  // 用户可以通过下拉框切换;Persona 抽屉的 per-seat 覆盖更高优先级。
+  const [selectedModel, setSelectedModel] = useState<string>("");
+
   // Message lists state representation to mimic image items & enable actual conversations
   const [interactiveMessages, setInteractiveMessages] = useState([
     {
@@ -561,6 +581,17 @@ export default function RoundtablePlanningPage() {
     }
   }, []);
 
+  // 首次 /api/models 返回后,把 selectedModel 初始化为列表第一个 —— 与
+  // AIWritingForm 的行为对齐。若 selectedModel 已经被用户在下拉框里选过,不再覆盖。
+  // 若当前选中的 model 已不在 availableModels 里(后端配置变了),也回退到首项。
+  useEffect(() => {
+    if (availableModels.length === 0) return;
+    const stillExists = availableModels.some((m) => m.name === selectedModel);
+    if (!selectedModel || !stillExists) {
+      setSelectedModel(availableModels[0].name);
+    }
+  }, [availableModels, selectedModel]);
+
   // Toast auto-dismiss logic
   useEffect(() => {
     if (showToast) {
@@ -837,7 +868,7 @@ export default function RoundtablePlanningPage() {
             dAgentThreadId: ids,
             agentName: coord,
             newMessage: nextLeaderTask,
-            model: DEFAULT_MODEL,
+            model: selectedModel || undefined,
             signal: leaderAborter.signal,
             onTextDelta: (text) => appendToDialogue(leaderBubbleId, text),
             onPhaseChange: (phase, toolName) => {
@@ -918,7 +949,8 @@ export default function RoundtablePlanningPage() {
               dAgentThreadId: ids,
               agentName: subName,
               newMessage: task,
-              model: perSeatModel || DEFAULT_MODEL,
+              // 优先级: 席位 Persona 覆盖 → 全局选中模型 → 让后端回退到 config.yaml models[0]
+              model: perSeatModel || selectedModel || undefined,
               signal: subAborter.signal,
               onTextDelta: (text) => appendToDialogue(subBubbleId, text),
               onPhaseChange: (phase, toolName) => {
@@ -1026,7 +1058,7 @@ export default function RoundtablePlanningPage() {
         const initRes = await initMultiAgent({
           agentNames: roundtableAgentIds,
           mainAgentName: coord,
-          model: DEFAULT_MODEL,
+          model: selectedModel || undefined,
           // As each sub-agent's thread comes online, flip every role that
           // shares the agentId to "在线". Some seats reuse the same agent
           // (e.g. seat 8 reuses roundtable-summary) so we match on agentId
@@ -1148,7 +1180,9 @@ export default function RoundtablePlanningPage() {
     const role = roles.find(r => r.id === id);
     const roleName = role?.name || "专家智能体";
     const cfg = agentConfigs[id];
-    const targetModel = cfg?.model || DEFAULT_MODEL;
+    // Persona 抽屉里的「保存」反馈文字: 优先显示用户在抽屉里选的 model,
+    // 没选时退回全局 selectedModel,最后才显示「默认」二字。
+    const targetModel = cfg?.model || selectedModel || "默认模型";
 
     const avatarColor =
       id === 2 ? "blue"
@@ -1206,7 +1240,9 @@ export default function RoundtablePlanningPage() {
     ]);
     (async () => {
       try {
-        const res = await initIntent(DEFAULT_MODEL);
+        // initIntent 当前不在 thread 上落盘 model,只为占位与兼容;空时由后端
+         // 走 lead_agent._resolve_model_name 回退到 config.yaml models[0]
+        const res = await initIntent(selectedModel || undefined);
         if (step1InitGenRef.current !== myGen) return;
         setIntentThreadId(res.thread_id);
         setTimelineEntries([
@@ -1540,7 +1576,7 @@ export default function RoundtablePlanningPage() {
       const res = await streamIntent({
         threadId: intentThreadId,
         message: trimmed,
-        model: DEFAULT_MODEL,
+        model: selectedModel || undefined,
         signal: aborter.signal,
         onTextDelta: (delta) => {
           setInteractiveMessages(prev =>
@@ -1791,7 +1827,7 @@ export default function RoundtablePlanningPage() {
       <RecommendAgentsDialog
         open={isRecommendDialogOpen}
         intent={intentReady}
-        model={DEFAULT_MODEL}
+        model={selectedModel || undefined}
         onCancel={() => setIsRecommendDialogOpen(false)}
         onConfirm={handleConfirmAgents}
       />
@@ -1919,6 +1955,41 @@ export default function RoundtablePlanningPage() {
 
         {/* Right Actions */}
         <div className="flex items-center gap-2">
+          {/* 全局模型选择器
+              ─────────────────────────────────────────────
+              影响 Step 1 / 推荐 / Step 2 init / 总控 leader / 子席位 special
+              所有 API 调用。Persona 抽屉里 per-seat 设置的 model 优先级更高。
+              选项来自 /api/models(由 config.yaml 配置),内网部署只需配自家模型。 */}
+          <label className="flex items-center gap-1.5 bg-white border border-[#e2e8f0] rounded-xl px-2.5 py-1.5 text-xs font-bold text-[#334155] dark:border-border dark:bg-secondary dark:text-foreground">
+            <Cpu className="w-3.5 h-3.5 text-primary" />
+            <span className="text-[10px] text-slate-400 font-mono">模型</span>
+            <select
+              id="global-model-select"
+              value={selectedModel}
+              onChange={(e) => setSelectedModel(e.target.value)}
+              disabled={modelsLoading || availableModels.length === 0}
+              title={
+                modelsLoading
+                  ? "正在加载模型列表…"
+                  : availableModels.length === 0
+                    ? "未在 config.yaml 中配置任何模型"
+                    : "切换全局推理模型;不影响 Persona 抽屉里已设置的 per-seat 覆盖"
+              }
+              className="bg-transparent border-none outline-none text-xs font-bold text-slate-700 cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed dark:text-foreground"
+            >
+              {availableModels.length === 0 && (
+                <option value="">{modelsLoading ? "加载中…" : "未配置模型"}</option>
+              )}
+              {availableModels.map((m) => (
+                <option key={m.name} value={m.name}>
+                  {m.display_name && m.display_name !== m.name
+                    ? `${m.display_name} (${m.name})`
+                    : m.name}
+                </option>
+              ))}
+            </select>
+          </label>
+
           <button
             id="new-task-btn"
             onClick={handleStartNewTask}
@@ -3091,7 +3162,8 @@ export default function RoundtablePlanningPage() {
                         <div className="space-y-1">
                           <label className="text-[9px] font-black text-slate-500 uppercase tracking-wider block">推理本源模型</label>
                           <select
-                            value={agentConfigs[selectedAgentId]?.model || DEFAULT_MODEL}
+                            // 抽屉里显示的「当前模型」:Persona 覆盖优先,否则跟随全局 selectedModel
+                            value={agentConfigs[selectedAgentId]?.model || selectedModel || ""}
                             onChange={(e) => {
                               const val = e.target.value;
                               setAgentConfigs(prev => ({
@@ -3106,7 +3178,7 @@ export default function RoundtablePlanningPage() {
                             disabled={modelsLoading}
                           >
                             {availableModels.length === 0 && (
-                              <option value={DEFAULT_MODEL}>{DEFAULT_MODEL}</option>
+                              <option value="">{modelsLoading ? "加载中…" : "未配置模型"}</option>
                             )}
                             {availableModels.map((m) => (
                               <option key={m.name} value={m.name}>
diff --git a/offline-backend-20260512/backend/app/gateway/routers/intent.py b/offline-backend-20260512/backend/app/gateway/routers/intent.py
index becb393f..b97397d6 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/intent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/intent.py
@@ -94,8 +94,9 @@ _INTENT_READY_PATTERN = re.compile(
 async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str, Any]:
     """创建任务理解会话用的空 thread。
 
-    请求体：``{ "model": "deepseek-chat" }``（可选，当前 init 未把 model 写入 thread，
-    实际模型在 ``/stream`` 的每次 run 里指定）。
+    请求体：``{ "model": "<可选>" }``（可选，当前 init 未把 model 写入 thread，
+    实际模型在 ``/stream`` 的每次 run 里指定；缺省由 lead_agent 回退到
+    ``config.yaml`` 的 ``models[0]``，前端通常传当前下拉框选中的 model 名）。
 
     响应::
 
@@ -138,7 +139,10 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
     """
     thread_id = str(payload.get("thread_id") or "").strip()
     message = str(payload.get("message") or "").strip()
-    model_name = str(payload.get("model") or "deepseek-chat")
+    # 不写死任何默认模型名:空串会让 lead_agent._resolve_model_name() 回退到
+    # config.yaml 的 models[0],与 /api/ai-writing 等其它路由一致,内网部署只配
+    # 自己的本地模型即可工作。
+    model_name = str(payload.get("model") or "")
     if not thread_id:
         raise HTTPException(status_code=400, detail="thread_id is required")
     if not message:
diff --git a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
index f09b8305..afcd3de1 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
@@ -303,7 +303,7 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
         {
           "agent_names": ["roundtable-intelligence", ...],  // 用户选的席位 id
           "main_agent_name": "roundtable-coordinator-xxx",  // 当次总控 id，前端生成
-          "model": "deepseek-chat"                          // 可选，写入 coordinator agent
+          "model": "<可选>"                                  // 可选,写入 coordinator agent;不传由 lead_agent 回退到 config.yaml models[0]
         }
 
     SSE 事件（每条 ``data: {...}\\n\\n``）::
@@ -843,8 +843,8 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
           "d_agent_thread_id": { "<agent_id>": "<thread_id>", ... },  // init_done.thread_ids
           "agent_name": "<本次运行的 agent_id>",
           "new_message": "<用户消息或派活 task 文本>",
-          "model": "deepseek-chat",
-          "skill_stop_names": []   // 可选，leader 一般留空，由网关注入 agent_orchestration
+          "model": "<可选>",       // 不传由 lead_agent 回退到 config.yaml models[0]
+          "skill_stop_names": []   // 可选,leader 一般留空,由网关注入 agent_orchestration
         }
 
     响应：上游 SSE 行透传 + 末尾一条 ``data:`` JSON（leader 为 dict，special 同上）。
@@ -855,7 +855,9 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
     agent_name: str = str(payload.get("agent_name") or "").lower()
     new_message: str = str(payload.get("new_message") or "")
     skill_stop_names: list[str] = payload.get("skill_stop_names") or []
-    model_name: str = str(payload.get("model") or "deepseek-chat")
+    # 不写死任何默认模型;空串会让 lead_agent._resolve_model_name() 回退到
+    # config.yaml 的 models[0],与 /api/ai-writing 等其它路由一致。
+    model_name: str = str(payload.get("model") or "")
 
     if not agent_name or agent_name not in agent_threads:
         raise HTTPException(
diff --git a/offline-backend-20260512/backend/app/gateway/routers/recommend.py b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
index 9acc527f..5035cb4c 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/recommend.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
@@ -151,7 +151,7 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
         {
           "intent": {"objective": "...", "constraints": [...], "assumptions": [...]},
           "candidates": [{"agent_id": "...", "name": "...", "description": "..."}, ...],
-          "model": "deepseek-chat"   # optional
+          "model": "<可选>"           # optional;不传由 lead_agent 回退到 config.yaml models[0]
         }
 
     Stream: transparent upstream LangGraph frames, followed by one status
@@ -169,7 +169,10 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
     """
     intent = payload.get("intent") or {}
     candidates = payload.get("candidates") or []
-    model_name = str(payload.get("model") or "deepseek-chat")
+    # 不写死任何默认模型;空串会让 lead_agent._resolve_model_name() 回退到
+    # config.yaml 的 models[0]。内网部署可能没有 deepseek-chat,前端传当前选中的
+    # model 名即可,缺失也不会硬错。
+    model_name = str(payload.get("model") or "")
 
     if not isinstance(intent, dict) or not str(intent.get("objective") or "").strip():
         raise HTTPException(status_code=400, detail="intent.objective is required")

From 114ee8f6aca0c5fcfa80593e7ef343c165ab6e68 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Mon, 25 May 2026 20:34:46 +0800
Subject: [PATCH 02/10] =?UTF-8?q?=E4=BB=A3=E7=A0=81=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/multi-agent-backend-dev.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/frontend-web/docs/multi-agent-backend-dev.md b/frontend-web/docs/multi-agent-backend-dev.md
index dcfcc807..fa254fa1 100644
--- a/frontend-web/docs/multi-agent-backend-dev.md
+++ b/frontend-web/docs/multi-agent-backend-dev.md
@@ -18,6 +18,7 @@
 - **澄清协议统一**：Step 1 与 Step 2 leader 都借 `ask_clarification` + 终态 `clarification` 帧驱动同一套选项卡片组件；`allow_multiple` 默认 false（单选、点击即发送）。
 - **leader 共识 = `status: []` 空数组**；澄清 = `status: "clarification"`（字符串）；派活 = `status: [[name, task], ...]`。这三者**互斥不混用**。
 - **后端 picks clamp 2–6，前端用户可手动加到 8**。
+- **不写死任何具体模型名**：`intent / recommend / multi_agent` 三个 router 的 `model_name = str(payload.get("model") or "")`，空串会被下游 `lead_agent._resolve_model_name()` 自动回退到 `config.yaml` 的 `models[0]`（与 `/api/ai-writing` 行为一致）。内网部署只需配 `config.yaml`，前后端均无需改硬编码。
 
 ---
 
@@ -664,6 +665,14 @@ grep "special-timing"   .runtime/logs/*.log   # payload_built / first_upstream_l
 
 `model` 写入 run 的 `context.model_name`；前端可按席位覆盖 special 调用的模型（见前端文档 §5.5 Persona 抽屉）。
 
+**绝不在路由里硬编码具体模型名**。三个 router 一律 `str(payload.get("model") or "")`：
+
+- 前端不传 / 传空串 → 下游 `lead_agent._resolve_model_name("")` 命中 falsy 分支，返回 `app_config.models[0].name`（`config.yaml` 配置顺序里的第一项）
+- 前端传了一个不在 `config.yaml` 里的 model 名 → 同样回退到首项，并 `logger.warning("Model 'x' not found ... fallback to ...")`
+- 前端传了合法 model 名 → 直接使用
+
+这是 `/api/ai-writing` 与圆桌三路由的统一行为，让本地 / 内网部署只需要改 `config.yaml`，不需要触前端常量或路由代码。详见 `deerflow/agents/lead_agent/agent.py:_resolve_model_name`。
+
 ### 11.3 新增席位
 
 1. `.deer-flow/agents/roundtable-xxx/` 增加 `config.yaml` + `SOUL.md`

From fd2c8d1d6451b6331fafec13b067954b74b4a5ce Mon Sep 17 00:00:00 2001
From: fengxiangdebaozi <10845145+fengxiangdebaozi@user.noreply.gitee.com>
Date: Mon, 25 May 2026 21:21:54 +0800
Subject: [PATCH 03/10] =?UTF-8?q?ui=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/ui修改-深蓝.md | 600 +++++++++++++++++++++++++++++++
 1 file changed, 600 insertions(+)

diff --git a/frontend-web/docs/ui修改-深蓝.md b/frontend-web/docs/ui修改-深蓝.md
index 357c7b31..3aaa8028 100644
--- a/frontend-web/docs/ui修改-深蓝.md
+++ b/frontend-web/docs/ui修改-深蓝.md
@@ -233,3 +233,603 @@
 |------|----------|
 | 16px Regular | 表格横纵轴数字 |
 | 14px Regular | 表格横轴数字（空间有限） |
+
+---
+
+## 3. 阴影
+
+### 3.1 容器与卡片配色
+
+阴影组通过深浅层级叠加形成空间感：外层容器最深，内层卡片次之，边框与高亮文字使用主色或字体色。
+
+#### 3.1.1 外层容器
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 页面 / 最外层背景 | `#060E24` | ZS-004-10 |
+| 分栏容器背景 | `#0C1836` | ZS-004-09 |
+
+#### 3.1.2 卡片（标题 + 操作）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#122347` | ZS-004-08 |
+| 卡片边框 | `#1A2F5A` | ZS-004-07 |
+| 卡片阴影（外发光） | `rgba(22, 119, 255, 0.12)` | 基于 ZS-002-06 主色蓝 12% 透明度 |
+| 标题文字（16px Bold） | `#C5CFE0` | ZS-004-02（正常字体色） |
+| 操作按钮文字 | `#4096FF` | ZS-002-05（标准蓝，链接） |
+| 次级操作图标（✏️ / ⋯） | `#6E88B0` | ZS-004-04（次级字体色） |
+
+#### 3.1.3 卡片新增（占位卡片）
+
+虚线描边的"新增入口"卡片，用于引导用户添加内容。
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#0C1836` | ZS-004-09（与外层同色，营造凹陷感） |
+| 虚线边框 | `#4096FF` | ZS-002-05 |
+| 加号图标 | `#4096FF` | ZS-002-05 |
+
+#### 3.1.4 阴影投影规则
+
+| 层级 | 阴影值 | 使用场景 |
+|------|--------|----------|
+| 一级阴影（卡片悬浮） | `0 2px 8px rgba(22, 119, 255, 0.12)` | 普通卡片 |
+| 二级阴影（hover / 强调） | `0 4px 16px rgba(22, 119, 255, 0.24)` | 卡片 hover、弹出层 |
+| 三级阴影（弹窗 / Modal） | `0 8px 32px rgba(6, 14, 36, 0.6)` | Dialog、Drawer |
+
+---
+
+## 4. 圆角
+
+### 4.1 圆角统一规范
+
+| 元素 | 圆角值 | 说明 |
+|------|--------|------|
+| 按钮 | `2px` | 所有按钮（主按钮 / 次按钮 / 文本按钮）统一使用 |
+| 卡片 | `4px` | 内容卡片、标题+操作卡片、卡片新增占位 |
+| 页面分栏框 | `4px` | 外层容器、分栏区域 |
+| 输入框 / 选择器 | `2px` | 与按钮一致，保持表单内对齐 |
+| Tag / Badge | `2px` | 与按钮一致 |
+| Modal / Drawer | `4px` | 与卡片一致 |
+
+### 4.2 按钮配色（圆角 2px）
+
+#### 4.2.1 主按钮（Primary）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 背景 | `#1677FF` | ZS-002-06 |
+| 文字 | `#FFFFFF` | — |
+| Hover 背景 | `#0958D9` | ZS-002-07 |
+| Active 背景 | `#003EB3` | ZS-002-08 |
+| 禁用背景 | `#4A6491` | ZS-004-05 |
+| 禁用文字 | `#6E88B0` | ZS-004-04 |
+
+#### 4.2.2 次按钮（Outline / Default）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 背景 | `transparent` | — |
+| 边框 | `#6E88B0` | ZS-004-04 |
+| 文字 | `#C5CFE0` | ZS-004-02 |
+| Hover 边框 | `#4096FF` | ZS-002-05 |
+| Hover 文字 | `#4096FF` | ZS-002-05 |
+| Active 边框 | `#1677FF` | ZS-002-06 |
+
+### 4.3 卡片与分栏（圆角 4px）
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 卡片背景 | `#122347` | ZS-004-08 |
+| 卡片边框 | `#1A2F5A` | ZS-004-07 |
+| 分栏框背景 | `#0C1836` | ZS-004-09 |
+| 分栏框边框 | `#1A2F5A` | ZS-004-07 |
+
+---
+
+## 5. 按钮
+
+> 全部圆角 `2px`，文字字号 14px（小尺寸）/ 14px（正常尺寸），字体 Noto Sans S Chinese Regular。
+
+### 5.1 按钮尺寸
+
+| 规格 | 高度 | 内边距 | 使用场景 |
+|------|------|--------|----------|
+| 小 | `28px` | `0 10px` | 空间小的板块内部，如表格中、卡片标题等 |
+| 正常 | `32px` | `0 14px` | 默认尺寸，所有常用按钮 |
+
+### 5.2 按钮类型与配色
+
+#### 5.2.1 主按钮（Primary）
+
+> 一个操作区域只能有一个主按钮。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `#1677FF` (ZS-002-06) | — | `#FFFFFF` |
+| Hover | `#0958D9` (ZS-002-07) | — | `#FFFFFF` |
+| Active | `#003EB3` (ZS-002-08) | — | `#FFFFFF` |
+| 失效 | `rgba(22, 119, 255, 0.35)` | — | `#6E88B0` (ZS-004-04) |
+
+#### 5.2.2 默认按钮（Default / Outline）
+
+用于"取消 / 返回"等次要操作，与主按钮成对出现时主按钮在右。
+
+| 状态 | 背景 | 边框 | 文字 |
+|------|------|------|------|
+| 默认 | `transparent` | `#6E88B0` (ZS-004-04) | `#C5CFE0` (ZS-004-02) |
+| Hover | `rgba(22, 119, 255, 0.08)` | `#4096FF` (ZS-002-05) | `#4096FF` (ZS-002-05) |
+| Active | `rgba(22, 119, 255, 0.16)` | `#1677FF` (ZS-002-06) | `#1677FF` (ZS-002-06) |
+| 失效 | `transparent` | `#4A6491` (ZS-004-05) | `#4A6491` (ZS-004-05) |
+
+#### 5.2.3 文本按钮（Text）
+
+用于表格操作、文件下载等。无背景与边框，靠文字色识别。
+
+| 状态 | 文字 | 装饰 |
+|------|------|------|
+| 默认 | `#4096FF` (ZS-002-05) | 无下划线 |
+| Hover | `#1677FF` (ZS-002-06) | 显示下划线（与文字同色） |
+| Active | `#0958D9` (ZS-002-07) | 下划线 |
+| 失效 | `#4A6491` (ZS-004-05) | 无装饰 |
+
+#### 5.2.4 图标按钮（Icon-only）
+
+用于增强辨识度或节省空间。仅图标，无文字。
+
+| 变体 | 背景 | 图标颜色 |
+|------|------|----------|
+| 主色（常用） | `#1677FF` (ZS-002-06) | `#FFFFFF` |
+| 主色 Hover | `#0958D9` (ZS-002-07) | `#FFFFFF` |
+| 危险（删除等） | `#F5222D` (ZS-001-06) | `#FFFFFF` |
+| 危险 Hover | `#CF1322` (ZS-001-07) | `#FFFFFF` |
+| 透明（仅图标） | `transparent` | `#6E88B0` (ZS-004-04) → hover `#4096FF` (ZS-002-05) |
+
+### 5.3 按钮组合
+
+#### 5.3.1 文字 + 下拉按钮（含 ▾）
+
+两种填充：
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.2 默认按钮，箭头 ▾ 与文字同色 `#C5CFE0` |
+| 主色（Filled） | 沿用 §5.2.1 主按钮，箭头 ▾ 同步白色 `#FFFFFF` |
+
+#### 5.3.2 图标 + 文字按钮（如 `+ 正常`）
+
+| 形态 | 配色规则 |
+|------|----------|
+| 默认（Outline） | 沿用 §5.2.2，左侧图标颜色与文字一致 `#C5CFE0` |
+| 主色（Filled） | 沿用 §5.2.1，左侧图标与文字一致 `#FFFFFF` |
+
+#### 5.3.3 文本按钮 + 图标（"更多 »"、"展开 ⌄"、"下一页 »"、"« 上一页"）
+
+| 角色 | 色值 |
+|------|------|
+| 文字 + 图标（默认） | `#4096FF` (ZS-002-05) |
+| 文字 + 图标（Hover） | `#1677FF` (ZS-002-06) |
+| 失效 | `#4A6491` (ZS-004-05) |
+
+> 图标可在文字前或后；多个文本按钮排成一行时，间距 `16px`，无分隔符。
+
+#### 5.3.4 主按钮 + 默认按钮组合（如"确定 / 取消 / 返回"）
+
+- **排列顺序**：默认按钮在左，主按钮在右（最右侧为主操作）
+- **按钮间距**：`8px`
+- **示例**：`[ 返回 ] [ 取消 ] [ 确定 ]`
+- **配色**：主按钮沿用 §5.2.1，其余沿用 §5.2.2
+
+### 5.4 其他按钮
+
+#### 5.4.1 悬浮状态（Floating）
+
+用于 Banner / 登录 / 视觉冲击强等展示场景。配色与主按钮一致，叠加阴影抬升。
+
+| 状态 | 阴影 |
+|------|------|
+| 默认 | `0 2px 8px rgba(22, 119, 255, 0.12)`（§3.1.4 一级阴影） |
+| Hover | `0 4px 16px rgba(22, 119, 255, 0.24)`（§3.1.4 二级阴影） |
+| Active | 阴影消失，按下感 |
+
+#### 5.4.2 加载中（Loading）
+
+用于异步操作等待反馈。点击瞬间将按钮锁定，文字前显示旋转图标。
+
+| 角色 | 色值 |
+|------|------|
+| 背景 | `#1677FF` (ZS-002-06) |
+| 文字 | `#FFFFFF` |
+| 加载图标 | `#FFFFFF`，旋转动画 `1.2s linear infinite` |
+| 不可点击 | 鼠标 `cursor: not-allowed` |
+
+> 与失效态的区别：失效是"不可操作"，加载是"操作进行中"——保留品牌主色，只是不可再次触发。
+
+---
+
+## 6. 分割线
+
+> 统一线宽 `1px`，颜色全部从 ZS-004 深蓝系取色，与深色背景保持低对比度但仍可识别。
+
+### 6.1 水平分割线
+
+水平分割线常用来对不同元素内容进行分割。
+
+| 类型 | 色值 | 来源 | 样式 | 使用场景 |
+|------|------|------|------|----------|
+| 实线（默认） | `#4A6491` | ZS-004-05 | `border-top: 1px solid` | 模块间、列表项间分割 |
+| 实线（强调） | `#6E88B0` | ZS-004-04 | `border-top: 1px solid` | 主区块标题下方、卡片头部分割 |
+| 实线（弱化） | `#2D4473` | ZS-004-06 | `border-top: 1px solid` | 卡片内部、密集列表分隔 |
+| 虚线 | `#4A6491` | ZS-004-05 | `border-top: 1px dashed` | 次级 / 层级内分割，提示"非主结构" |
+| 主色实线（高亮） | `#1677FF` | ZS-002-06 | `border-top: 1px solid` | 强调分隔，少量使用（如当前激活区块底边） |
+
+### 6.2 垂直分割线
+
+垂直分割线常用来做行内分割（如导航项之间、状态指示之间、表格列头之间）。
+
+| 类型 | 色值 | 来源 | 样式 | 使用场景 |
+|------|------|------|------|----------|
+| 实线（默认） | `#4A6491` | ZS-004-05 | `border-left: 1px solid` | 行内 inline 元素分割（面包屑、操作按钮组） |
+| 实线（弱化） | `#2D4473` | ZS-004-06 | `border-left: 1px solid` | 表格列分割、紧凑布局 |
+| 虚线 | `#4A6491` | ZS-004-05 | `border-left: 1px dashed` | 多列对齐辅助、辅助参考线 |
+
+### 6.3 规格与间距
+
+| 规则 | 取值 |
+|------|------|
+| 线宽 | `1px` |
+| 水平分割线与上下元素间距 | `≥ 8px`（紧凑布局可用 `4px`） |
+| 垂直分割线与左右元素间距 | `≥ 8px`（行内紧凑 `4px`） |
+| 垂直分割线高度 | 与文字行高一致，约 `12–14px`（也可全高跟随容器） |
+| 透明度 | 必要时叠 `opacity: 0.6` 实现"更弱"层级 |
+
+### 6.4 CSS 参考
+
+```css
+/* 默认水平分割线 */
+.divider-h        { border-top: 1px solid #4A6491; }
+.divider-h-strong { border-top: 1px solid #6E88B0; }
+.divider-h-weak   { border-top: 1px solid #2D4473; }
+.divider-h-dashed { border-top: 1px dashed #4A6491; }
+.divider-h-accent { border-top: 1px solid #1677FF; }
+
+/* 垂直分割线 */
+.divider-v        { border-left: 1px solid #4A6491; height: 14px; display: inline-block; vertical-align: middle; }
+.divider-v-weak   { border-left: 1px solid #2D4473; height: 14px; display: inline-block; vertical-align: middle; }
+.divider-v-dashed { border-left: 1px dashed #4A6491; height: 14px; display: inline-block; vertical-align: middle; }
+```
+
+---
+
+## 7. 间距
+
+> 全站以 `8px (0.5rem)` 为对照基准单位，划分"密 / 疏"两个层次。所有间距取值均来自下列阶梯，禁止使用非阶梯值（如 5px、13px）。
+
+### 7.1 间距阶梯
+
+| 阶 | px | rem | 分组 | 典型场景 |
+|----|------|--------|------|----------|
+| 1 | `4px` | `0.25rem` | 密 | 图标与文字间距、Tag 内边距、紧凑徽标 |
+| 2 | `8px` | `0.5rem` | 密 | 行内元素相邻、按钮组间距、表单 label 与控件 |
+| 3 | `12px` | `0.75rem` | 密 | 表单项垂直间距、列表项内边距 |
+| 4 | `16px` | `1rem` | 密 | 卡片内容内边距、模块内分隔 |
+| 5 | `24px` | `1.5rem` | 疏 | 模块之间、Section 内边距 |
+| 6 | `32px` | `2rem` | 疏 | 卡片之间、表单组之间 |
+| 7 | `40px` | `2.5rem` | 疏 | 主区块之间、页面 Header / Footer 内边距 |
+| 8 | `56px` | `3.5rem` | 疏 | 页面段落级隔断、Banner 区域 |
+
+> "密"对应紧凑信息密度（表格、表单、卡片内部）；"疏"对应视觉呼吸（模块之间、页面整体留白）。**16px 是"密"的上限，24px 是"疏"的下限**，两者之间不应再插入自定义值。
+
+### 7.2 使用原则
+
+- **同层级一致**：同一布局层级内的间距必须使用同一阶值；多种取值会破坏节奏。
+- **就近取阶**：相邻区块的间距尽量从相邻阶梯取值（如 `16px → 24px`），跨越过多阶（如 `8px → 56px`）会让视觉断裂。
+- **密疏不混用**：一个组件内部全部用"密"，外部用"疏"，避免内/外间距颠倒。
+- **优先 8 的倍数**：除最小阶 `4px` 外，所有阶皆为 8 的倍数，方便 4/8 网格对齐。
+- **响应式按比例衰减**：移动端可整体降一阶（如 `24px → 16px`），但仍在阶梯内。
+
+### 7.3 CSS Token 建议
+
+```css
+:root {
+  --spacing-1: 4px;   /* 0.25rem */
+  --spacing-2: 8px;   /* 0.5rem  */
+  --spacing-3: 12px;  /* 0.75rem */
+  --spacing-4: 16px;  /* 1rem    */
+  --spacing-5: 24px;  /* 1.5rem  */
+  --spacing-6: 32px;  /* 2rem    */
+  --spacing-7: 40px;  /* 2.5rem  */
+  --spacing-8: 56px;  /* 3.5rem  */
+}
+```
+
+### 7.4 与已有规范的对齐
+
+| 已有规则 | 对应阶 |
+|----------|--------|
+| §4.x 卡片圆角内边距 | `--spacing-4` (16px) |
+| §5.3.4 主+默认按钮组合间距 `8px` | `--spacing-2` |
+| §5.3.3 文本按钮间距 `16px` | `--spacing-4` |
+| §6.3 分割线与上下元素间距 `≥ 8px` | `--spacing-2` 起 |
+
+---
+
+## 8. 导航组件
+
+> 适用于"大屏后台 / 控制台"类深蓝主题界面。整体结构 = 顶部导航 + 左侧分级菜单 + 多级下拉。所有颜色取自 ZS-002 / ZS-004 两个色系。
+
+### 8.1 整体结构
+
+```
+┌─ 顶部导航（Header）─ 高 56px ──────────────────────────────────────────────┐
+│ ≡ 二级菜单 二级菜单 二级菜单  〈一级菜单〉〈一级菜单〉  ⟪ XXXX系统 ⟫  〈一级菜单〉  ⟳ 时间  ⌂ 返回首页 │
+├──┬──────────────────────────────────────────────────────────────────────────┤
+│ 三│  ┌─ 四级菜单（下拉面板）──┐                                              │
+│ 级│  │ ▾ 四级菜单             │                                              │
+│ 菜│  │   ▾ 五级菜单           │                                              │
+│ 单│  │     - 六级菜单 (active)│                                              │
+│ 三│  │     - 六级菜单         │                                              │
+│ 级│  │   ▸ 五级菜单           │                                              │
+│ 菜│  │ ▸ 四级菜单             │                                              │
+│ 单│  └────────────────────────┘                                              │
+│ …│                                                                          │
+└──┴──────────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.2 顶部导航（Header）
+
+#### 8.2.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 高度 | `56px` |
+| 左右 padding | `--spacing-4` (16px) |
+| 背景 | 渐变 `linear-gradient(180deg, #122347 0%, #0C1836 100%)`（ZS-004-08 → ZS-004-09） |
+| 底边 | `border-bottom: 1px solid #1A2F5A` (ZS-004-07) |
+| 阴影 | `0 2px 8px rgba(6, 14, 36, 0.6)`（§3.1.4 一级阴影变体） |
+| 文字基线 | `Noto Sans S Chinese`，垂直居中 |
+
+#### 8.2.2 二级菜单（左侧 Tabs，小号 14px）
+
+| 状态 | 文字 | 背景 | 装饰 |
+|------|------|------|------|
+| 默认 | `#6E88B0` (ZS-004-04) | `transparent` | — |
+| Hover | `#C5CFE0` (ZS-004-02) | `rgba(22,119,255,0.08)` | — |
+| 激活 | `#4096FF` (ZS-002-05) | `transparent` | 底部 `2px solid #4096FF` 高亮线 |
+
+- 字号 `14px Regular`，间距 `--spacing-3` (12px)
+- 与最左侧的"折叠菜单 ≡"图标间距 `--spacing-4` (16px)
+
+#### 8.2.3 一级菜单（中部主导航，16px 带切角装饰）
+
+| 状态 | 文字 | 装饰 |
+|------|------|------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 两端切角斜边，`border: 1px solid #1A2F5A` |
+| Hover | `#4096FF` (ZS-002-05) | 切角线变 `#4096FF` |
+| 激活 | `#FFFFFF` | 切角线 `#1677FF` (ZS-002-06)，背景 `rgba(22,119,255,0.16)` |
+
+- 字号 `16px Medium`
+- 切角推荐 `clip-path: polygon(8px 0, calc(100% - 8px) 0, 100% 100%, 0 100%)`
+- 项间距 `--spacing-2` (8px)
+
+#### 8.2.4 系统标题（XXXX系统）
+
+- 字号 `20px Bold`，颜色 `#FFFFFF`
+- 字体 `DOUYUFont` 或 Noto Sans Medium
+- 左右装饰用主色蓝渐变线条：`linear-gradient(90deg, transparent 0%, #1677FF 50%, transparent 100%)`，线宽 `1px`
+- 居中相对 Header 几何中心，左右最少留 `--spacing-6` (32px) 间距给一级菜单
+
+#### 8.2.5 右侧工具区（时间 / 图标 / 返回首页）
+
+| 元素 | 字号/尺寸 | 颜色 |
+|------|----------|------|
+| 更新时间文字 | `12px Regular` | `#6E88B0` (ZS-004-04) |
+| 时间数值（数字） | `12px D-DIN Regular` | `#C5CFE0` (ZS-004-02) |
+| 工具图标（刷新/上/家） | `16px` | `#6E88B0`，hover → `#4096FF` |
+| 返回首页文字 | `14px Regular` | `#C5CFE0`，hover → `#4096FF` |
+
+- 元素间距 `--spacing-3` (12px)
+- 整体右 padding `--spacing-4` (16px)
+
+### 8.3 侧边栏（三级菜单）
+
+#### 8.3.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 宽度 | `64px`（仅图标 / 竖排文字） |
+| 背景 | `#0C1836` (ZS-004-09) |
+| 右边界 | `border-right: 1px solid #1A2F5A` (ZS-004-07) |
+| 项高度 | `64px`（与宽度一致，呈正方形） |
+| 项内间距 | 上下 `--spacing-3` (12px) |
+| 字号 | `14px Medium`，竖排（`writing-mode: vertical-rl`）或正常排两行 |
+
+#### 8.3.2 状态配色
+
+| 状态 | 背景 | 文字 | 左侧指示条 |
+|------|------|------|-----------|
+| 默认 | `transparent` | `#6E88B0` (ZS-004-04) | 无 |
+| Hover | `rgba(22,119,255,0.08)` | `#C5CFE0` (ZS-004-02) | 无 |
+| 激活 | `#1A2F5A` (ZS-004-07) | `#FFFFFF` | 左侧 `2px solid #1677FF` (ZS-002-06) |
+
+### 8.4 下拉菜单面板（四级 / 五级 / 六级）
+
+#### 8.4.1 面板规格
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#122347` (ZS-004-08) |
+| 边框 | `1px solid #1A2F5A` (ZS-004-07) |
+| 阴影 | `0 4px 16px rgba(6, 14, 36, 0.6)`（§3.1.4 三级阴影变体） |
+| 圆角 | `4px` |
+| 内边距 | 上下 `--spacing-2` (8px) |
+| 最小宽度 | `150px` |
+
+#### 8.4.2 菜单项规格
+
+| 层级 | 缩进（padding-left） | 字号 | 展开图标 | 前缀 |
+|------|---------------------|------|----------|------|
+| 四级菜单 | `--spacing-3` (12px) | `14px Medium` | `▾ / ▸` | — |
+| 五级菜单 | `--spacing-5` (24px) | `14px Regular` | `▾ / ▸` | — |
+| 六级菜单 | `--spacing-6` (32px) | `14px Regular` | — | `-` 短横线 |
+
+- 行高 `32px`
+- 项之间无分割线（靠缩进与图标区分层级）
+
+#### 8.4.3 菜单项配色
+
+| 状态 | 背景 | 文字 | 展开图标 |
+|------|------|------|----------|
+| 默认 | `transparent` | `#C5CFE0` (ZS-004-02) | `#6E88B0` (ZS-004-04) |
+| Hover | `rgba(22,119,255,0.08)` | `#4096FF` (ZS-002-05) | `#4096FF` |
+| 激活（当前选中） | `rgba(22,119,255,0.16)` | `#4096FF` (ZS-002-05) | `#1677FF` (ZS-002-06) |
+| 父级（含激活子项） | `transparent` | `#FFFFFF` | `#1677FF` |
+| 失效 | `transparent` | `#4A6491` (ZS-004-05) | `#4A6491` |
+
+### 8.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 下拉面板展开 | `transform-origin: top; transform: scaleY(0.95) → scaleY(1); opacity 0 → 1`，`200ms ease-out` |
+| 展开图标旋转 | `transform: rotate(0 → 90deg)`，`200ms ease-out` |
+| Hover 背景过渡 | `background-color 120ms ease-out` |
+| 激活底部高亮线（二级菜单） | `width 0% → 100%`，`240ms ease-out` |
+
+### 8.6 间距引用
+
+| 位置 | 取值 |
+|------|------|
+| Header 内部元素间距 | `--spacing-2 / --spacing-3` |
+| Header 与下方内容间距 | `0`（贴合，靠底边线与阴影区分） |
+| 侧边栏与下拉面板间距 | `--spacing-1` (4px) |
+| 下拉面板与触发元素间距 | `--spacing-1` (4px) |
+| 同级菜单项之间 | `0`（紧贴排列，靠 hover/active 背景区分） |
+
+---
+
+## 9. 锚点与页签
+
+> 对应"4.2 导航组件-锚点"。三类组件共用主色蓝指示当前位置：**页签 / 锚点 / 回到顶部**。
+
+### 9.1 页签（Tabs）
+
+#### 9.1.1 横向页签（下划线-横向）
+
+| 状态 | 文字 | 下划线 |
+|------|------|--------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | `2px solid #4096FF`，宽度与文字齐 |
+| 失效 | `#4A6491` (ZS-004-05) | 无 |
+
+- 字号 `14px Medium`
+- 项间距 `--spacing-5` (24px)
+- 下划线与文字底部间距 `--spacing-2` (8px)
+- 容器底边可叠一条 `1px solid #1A2F5A` (ZS-004-07) 作为基线，激活态的高亮线压在上面
+
+#### 9.1.2 纵向页签（下划线-纵向）
+
+| 状态 | 文字 | 右侧指示线 |
+|------|------|-----------|
+| 默认 | `#C5CFE0` (ZS-004-02) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | 右侧 `2px solid #4096FF`，高度与文字齐 |
+| 失效 | `#4A6491` (ZS-004-05) | 无 |
+
+- 字号 `14px Medium`，项高度 `32px`
+- 项间距 `--spacing-2` (8px)
+- 容器右边可叠一条 `1px solid #1A2F5A` 基线，激活指示线压在上面
+
+### 9.2 锚点（Anchor）
+
+用于长内容页（如详情页、文档页）的章节快速跳转。
+
+#### 9.2.1 结构
+
+```
+│ 一级
+│ 一级          (active)
+│    二级
+│    二级
+│ 一级
+│ 一级
+```
+
+#### 9.2.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器背景 | `#122347` (ZS-004-08) 或 `transparent`（嵌入页面侧栏时） |
+| 左侧基线 | `1px solid #1A2F5A` (ZS-004-07) 通栏 |
+| 项高度 | `32px` |
+| 一级项左 padding | `--spacing-3` (12px) |
+| 二级项左 padding | `--spacing-5` (24px) |
+| 项间距 | `0`（贴合排列） |
+| 字号 | `14px Regular` |
+
+#### 9.2.3 状态配色
+
+| 状态 | 一级文字 | 二级文字 | 左侧指示条 |
+|------|----------|----------|-----------|
+| 默认 | `#C5CFE0` (ZS-004-02) | `#6E88B0` (ZS-004-04) | 无 |
+| Hover | `#4096FF` (ZS-002-05) | `#4096FF` (ZS-002-05) | 无 |
+| 激活 | `#4096FF` (ZS-002-05) | — | 左侧 `2px solid #4096FF`，覆盖容器基线 |
+| 父级（含激活子项） | `#FFFFFF` | — | — |
+
+- 激活态指示条与基线重合，宽 `2px`，色压主色蓝 `#4096FF`
+- 二级项**不单独支持激活态**：当二级被点中时，其父级一级显示激活态，左侧指示条按父级位置渲染
+
+#### 9.2.4 滚动同步
+
+| 行为 | 规则 |
+|------|------|
+| 页面滚动 | 监听锚点对应区块进入视口的相对位置，自动切换激活态 |
+| 点击锚点 | `behavior: smooth` 滚动到目标，激活指示条 `top` 过渡 `200ms ease-out` |
+| 边界处理 | 滚动到页面顶部 → 第一个锚点激活；到页尾 → 最后一个锚点激活 |
+
+### 9.3 回到顶部（BackToTop）
+
+固定在视口右下角的悬浮按钮，向上滚动到页面顶部。
+
+#### 9.3.1 规格
+
+| 属性 | 取值 |
+|------|------|
+| 形状 | 圆形 `40px × 40px`（`border-radius: 50%`） |
+| 图标 | `↑` 上箭头，`16px`，`#FFFFFF` |
+| 距视口右边 | `--spacing-5` (24px) |
+| 距视口下边 | `--spacing-6` (32px) |
+| 出现时机 | 页面 `scrollTop > 200px` 时淡入；回到顶部后淡出 |
+| 淡入/淡出 | `opacity 0 → 1` / `1 → 0`，`200ms ease-out` |
+
+#### 9.3.2 状态配色
+
+| 状态 | 背景 | 阴影 | 图标 |
+|------|------|------|------|
+| 正常（默认） | `#1677FF` (ZS-002-06) | `0 2px 8px rgba(22,119,255,0.12)` (§3.1.4 一级阴影) | `#FFFFFF` |
+| 悬停（Hover） | `#0958D9` (ZS-002-07) | `0 4px 16px rgba(22,119,255,0.24)` (§3.1.4 二级阴影) | `#FFFFFF` |
+| 点按（Active） | `#003EB3` (ZS-002-08) | 阴影消失，按下感 | `#FFFFFF` |
+| 失效 / 不显示 | — | — | 整体 `opacity: 0`，`pointer-events: none` |
+
+#### 9.3.3 悬停 Tooltip
+
+Hover 状态下方显示 `回到顶部` 提示气泡：
+
+| 属性 | 取值 |
+|------|------|
+| 文字 | `回到顶部`，`12px Regular` |
+| 文字颜色 | `#C5CFE0` (ZS-004-02) |
+| 背景 | `#1677FF` (ZS-002-06) |
+| 圆角 | `2px` |
+| 内边距 | 上下 `4px`，左右 `--spacing-2` (8px) |
+| 与按钮间距 | `--spacing-2` (8px) |
+| 出现时机 | Hover 进入 `300ms` 后显示，离开立即消失 |
+
+### 9.4 三者的差异与选用
+
+| 组件 | 主要用途 | 视觉特征 |
+|------|----------|---------|
+| 页签 | 同层级内容切换（多 Tab 互斥） | 文字 + 下划线（横/纵） |
+| 锚点 | 长页面内章节跳转 | 文字 + 左侧指示条 + 层级缩进 |
+| 回到顶部 | 长页面快速返回起点 | 圆形悬浮按钮 + 上箭头 |

From e3d8e534f6e5ac79a661dedad4ef9e81b2060765 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Mon, 25 May 2026 22:39:50 +0800
Subject: [PATCH 04/10] =?UTF-8?q?=E6=A0=B7=E5=BC=8F=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/multi-agent-backend-dev.md  | 405 ++++++++++++++++++
 frontend-web/docs/multi-agent-frontend-dev.md |   4 +-
 .../src/roundtable-planning/api/intent.ts     |  96 ++++-
 .../pages/RoundtablePlanningPage.tsx          | 134 ++++--
 .../backend/app/gateway/routers/intent.py     |  52 ++-
 .../app/gateway/routers/multi_agent.py        |  96 +++++
 6 files changed, 739 insertions(+), 48 deletions(-)

diff --git a/frontend-web/docs/multi-agent-backend-dev.md b/frontend-web/docs/multi-agent-backend-dev.md
index fa254fa1..c4724d83 100644
--- a/frontend-web/docs/multi-agent-backend-dev.md
+++ b/frontend-web/docs/multi-agent-backend-dev.md
@@ -13,6 +13,7 @@
 - 三个圆桌 Router（`intent / recommend / multi_agent`）**全部走 HTTP loopback**：在同进程内通过 `httpx.AsyncClient` 调本机 `127.0.0.1` 的 `/api/threads`、`/api/agents`、`/api/threads/{id}/runs/stream`。
 - **所有 loopback `httpx.AsyncClient` 必须 `trust_env=False`**。开发机若设了 `HTTP_PROXY` / `HTTPS_PROXY`，httpx 默认会把 loopback 也走代理 → 不可达 → 单次请求多出 40 秒超时（典型症状日志：`headers_in=42.160s`）。
 - **席位 agent 持久注册**（磁盘 `.deer-flow/agents/` + `_sync_legacy_agents`），**协调智能体每次新建**（命名 `roundtable-coordinator-{timestamp36}`，DB 累积，需后续 GC）。
+- **`.deer-flow/` 整个目录被 git ignore**（仓库根 `.gitignore` 第 64 / 74 行），`git clone` 后内置 agent 目录在部署机上**不会存在**——任何环境都必须把 `roundtable-intent` + `roundtable-recommender` 两个**功能型 agent** 持久化进发布物，否则 `/api/intent/stream` 报 500。**互联网 demo 还需要 6 个示例研讨席位**（`roundtable-intelligence` 等），**内网部署用客户自有 agent 替代**这些席位，无需打包。详见 §11.7。
 - **`init` 是 SSE 而非一次性 JSON**：用 `asyncio.as_completed` 按真实完成顺序推送 `seat_ready`，前端因此能逐个点亮席位。
 - **`init_done.thread_ids` 包含协调智能体自身**（`agent_threads[main_agent_name] = coord_thread`），前端 Step 3 列文件时需自行过滤。
 - **澄清协议统一**：Step 1 与 Step 2 leader 都借 `ask_clarification` + 终态 `clarification` 帧驱动同一套选项卡片组件；`allow_multiple` 默认 false（单选、点击即发送）。
@@ -679,6 +680,235 @@ grep "special-timing"   .runtime/logs/*.log   # payload_built / first_upstream_l
 2. 前端候选池 / 推荐逻辑纳入该 id
 3. Step 2 `agent_names` 传入即可 — **multi_agent 路由无需改**
 
+### 11.7 内置 agent 部署持久化（必读，关系到内网部署能否启动）
+
+#### 11.7.1 问题背景
+
+圆桌功能涉及的 agent 都靠**磁盘文件**激活（`.deer-flow/agents/<id>/{config.yaml,SOUL.md}`），但仓库根 `.gitignore` 第 64 / 74 行有：
+
+```
+offline-backend-20260512/backend/.deer-flow/*
+```
+
+整个 `.deer-flow/` 被 git 排除。新机器 `git clone` 后 `.deer-flow/agents/` 不存在 → 圆桌相关 agent 缺失 → 进入 `/api/intent/init` 后 `_create_thread` 本身能成功，但下一步 `/api/intent/stream` 真正调用 LangGraph 时会因为 agent 解析失败抛 500（典型表现：前端 Step 1 init 一次成功，下一句话发出去就 500）。
+
+#### 11.7.1.1 哪些 agent **必须**打包，哪些**不需要**
+
+圆桌涉及的 agent 分**两类**，部署侧需求完全不同：
+
+| Agent | 角色 | 是否必须打包发布 |
+|-------|------|------------------|
+| `roundtable-intent` | **功能型**：Step 1 任务理解，所有部署都用它 | ✅ **必须**（任何环境） |
+| `roundtable-recommender` | **功能型**：Step 1→2 之间从候选池里挑推荐，所有部署都用它 | ✅ **必须**（任何环境） |
+| `roundtable-intelligence` | 示例研讨席位（情报收集） | ⚠️ **互联网 demo 用**，内网不需要 |
+| `roundtable-environment` | 示例研讨席位（环境评估） | ⚠️ 同上 |
+| `roundtable-solution-design` | 示例研讨席位（方案设计） | ⚠️ 同上 |
+| `roundtable-risk-review` | 示例研讨席位（风险审查） | ⚠️ 同上 |
+| `roundtable-execution-plan` | 示例研讨席位（执行规划） | ⚠️ 同上 |
+| `roundtable-summary` | 示例研讨席位（总结陈述） | ⚠️ 同上 |
+| `roundtable-coordinator-*` | 协调智能体壳，每次会话动态新建 | ❌ **不打包**（运行时生成） |
+
+**关键区分**：
+- `roundtable-intent` / `roundtable-recommender` 是**圆桌功能本身的一部分**——没有它们，整个 Step 1 + 推荐流程跑不起来，跟客户业务无关
+- 6 个 `roundtable-<领域>` 席位只是**互联网 demo 用的示例研讨者**，让访客打开页面就能看到完整三步流程。内网部署面对的是客户自己的业务场景，会把客户自有的领域 agent（行业专家、合规审查员、业务规则引擎……）注册成候选 agent；这时 6 个示例席位反而成噪声
+
+**对应的部署组合**：
+
+| 部署场景 | 打包内容 |
+|----------|----------|
+| **互联网 demo** | `roundtable-intent` + `roundtable-recommender` + **6 个示例席位** |
+| **内网客户部署** | `roundtable-intent` + `roundtable-recommender`（仅此 2 个，**不带** 6 个示例席位） |
+| **本地开发** | 全要（方便快速跑通） |
+
+**内网部署的额外注意**（去掉 6 个示例席位时）：
+
+1. **客户自有的候选 agent 必须先存在**：内网部署落地时，客户的业务 agent 应该已经注册进 `.deer-flow/agents/`（手工建目录或通过 `POST /api/agents` 创建）。否则候选池为空，推荐拿不到任何 picks。
+2. **前端 `FALLBACK_AGENT_IDS` 需要适配**：前端 `RecommendAgentsDialog.tsx` 里硬编码了 6 个示例席位 id 作为 fallback；若推荐失败回退路径会拿这 6 个去 `candidates` 里交集，内网部署该交集恒为空，**fallback 会失败**。建议要么：
+   - **方案 1**（最稳）：内网客户的候选池足够丰富 + recommender SOUL 调好，让推荐成功率 ~100%，不依赖 fallback
+   - **方案 2**：把 `FALLBACK_AGENT_IDS` 改成从后端 `/api/agents` 取前 6 个 `published=true` 的候选 agent（动态 fallback）。改动点见前端文档 §6.2 `RecommendAgentsDialog`
+3. **推荐 SOUL（`roundtable-recommender/SOUL.md`）通常无需改**：SOUL 本身没写死候选 id，只描述「从给的候选池里挑」；候选池由前端传入，模型读到客户自有 agent 后会照样工作。
+
+下文给出三种修复方案，**推荐方案 A**（最简单，无需写代码）。
+
+#### 11.7.2 方案 A：`.gitignore` 白名单（推荐）
+
+让 git 只跟踪 **`roundtable-intent` + `roundtable-recommender` 两个功能型 agent** 的 `config.yaml` 与 `SOUL.md`，其它一律忽略。6 个示例席位**不进白名单**——互联网 demo 部署机如果需要它们，按 §11.7.2.A 在该分支单独追加白名单；内网部署机直接享受「干净的 `.deer-flow/`」。
+
+**步骤 1：编辑仓库根 `.gitignore`**
+
+在最后追加白名单段（位置很重要，**必须在 `offline-backend-20260512/backend/.deer-flow/*` 之后**，否则被前面的通配符吃掉）：
+
+```gitignore
+# === 圆桌功能型 agent 跟随仓库发布(任何部署都需要) ===
+# 父目录先 unignore,git 才能往下递归
+!offline-backend-20260512/backend/.deer-flow/
+!offline-backend-20260512/backend/.deer-flow/agents/
+# 仅放行 2 个功能型 agent;6 个示例席位由互联网分支自行放行
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender/SOUL.md
+```
+
+⚠️ **不要**直接写 `!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/**`——`git` 不会进入还在 ignore 的父目录，必须逐层 un-ignore，再精确放行文件。
+
+**步骤 2：强制 add 并提交**
+
+```bash
+# 验证白名单生效
+git check-ignore -v offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent/config.yaml
+# 期望输出无任何匹配,或最后一条匹配是上面的 ! 行
+
+# 加入索引(只加 2 个功能型 agent)
+git add offline-backend-20260512/backend/.deer-flow/agents/roundtable-intent
+git add offline-backend-20260512/backend/.deer-flow/agents/roundtable-recommender
+
+git status   # 应只看到 2 × 2 = 4 个新文件,绝不出现 users/、threads/、data/、6 个示例席位
+
+git commit -m "chore: 把圆桌功能型 agent(intent + recommender)纳入版本管理"
+```
+
+**步骤 3：部署机验证**
+
+```bash
+# clone 之后立刻
+ls offline-backend-20260512/backend/.deer-flow/agents/
+# 内网部署:应看到 roundtable-intent/ + roundtable-recommender/(+ 客户自有 agent)
+# 互联网 demo:还应看到 6 个 roundtable-<领域>/ 示例席位
+```
+
+启动后端，前端打开圆桌规划页，Step 1 第一句话发出去能正常拿到 streaming 响应而不是 500，就说明 OK。
+
+##### 11.7.2.A 互联网 demo 分支：追加 6 个示例席位
+
+互联网 demo 维护一条独立分支（或独立 `.gitignore` 段，用 build flag 切），在白名单后追加：
+
+```gitignore
+# === 仅互联网 demo 需要的 6 个示例研讨席位 ===
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intelligence/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intelligence/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-intelligence/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-environment/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-environment/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-environment/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-solution-design/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-solution-design/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-solution-design/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-risk-review/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-risk-review/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-risk-review/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-execution-plan/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-execution-plan/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-execution-plan/SOUL.md
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-summary/
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-summary/config.yaml
+!offline-backend-20260512/backend/.deer-flow/agents/roundtable-summary/SOUL.md
+```
+
+`git add` 对应 6 个目录、提交，互联网分支即拿到全部 8 个内置 agent。两条分支共享同一份 `roundtable-intent / roundtable-recommender`，SOUL 调整对两边都生效，避免双维护。
+
+**优点**：
+
+- 零代码改动；新机器 `git clone` 即可，部署文档不用单独说「记得拷一下 `.deer-flow/agents/`」
+- 修改 SOUL 直接走 git 走 review 流程
+- 多人协作时 SOUL 改动可见
+
+**注意事项**：
+
+- `git status` 检查时确保**只**有 16 个内置文件进了索引，**绝对不能**包括 `users/`、`threads/`、`data/*.db`、`roundtable-coordinator-*/` 这些运行时数据
+- `roundtable-coordinator-mp*/` 这类历史会话残留目录会被 ignore 规则自动忽略（白名单没放行它们），无需手动清理
+- 部署机如果之前手动建过 `.deer-flow/agents/roundtable-intent/`，`git pull` 会把仓库版本覆盖上去——这是期望行为
+
+#### 11.7.3 方案 B：源码内置 + 启动时种子化
+
+如果不想让 `.deer-flow/` 这种「运行时目录」出现在 git 里，可以把 SOUL/config 放进 `packages/harness/` 里作为只读资源，启动时检查 `.deer-flow/agents/<id>/` 不存在就从源拷过去。
+
+**步骤大纲**：
+
+1. 在 `packages/harness/deerflow/agents/builtin_personas/` 下建 8 个目录（`roundtable-intent/` 等），把 SOUL.md + config.yaml 搬过去
+2. 在 `app/gateway/app.py` 的 `lifespan` 启动阶段新增 `_seed_builtin_roundtable_agents()`：
+   ```python
+   def _seed_builtin_roundtable_agents() -> None:
+       from importlib.resources import files
+       src_root = files("deerflow.agents.builtin_personas")
+       dst_root = get_paths().agents_dir()  # .deer-flow/agents/
+       for agent_id in BUILTIN_ROUNDTABLE_AGENT_IDS:  # 8 个常量
+           dst = dst_root / agent_id
+           if dst.exists():
+               continue   # 已有(可能是用户改过的),不覆盖
+           dst.mkdir(parents=True)
+           for fname in ("config.yaml", "SOUL.md"):
+               (dst / fname).write_bytes((src_root / agent_id / fname).read_bytes())
+   ```
+3. 紧接着调一次 `_sync_legacy_agents(store)`，把这些刚落地的目录 upsert 进 `agents` 表
+4. 把 `BUILTIN_ROUNDTABLE_AGENT_IDS` 常量也导出给 `recommend.py` / `multi_agent.py` 共享
+
+**优点**：
+
+- `.deer-flow/` 仍然作为「运行时数据目录」语义干净
+- 运维可以手动改 `.deer-flow/agents/roundtable-intent/SOUL.md` 临时调试，重启不被覆盖（`if dst.exists(): continue`）
+- 升级时如果想强制刷新，加个 `--force-reseed-builtins` 启动参数即可
+
+**缺点**：
+
+- 多一段 bootstrap 代码 + 一份 `pyproject.toml` 的 `package-data` 声明（确保 SOUL.md 跟着 wheel 一起发布）
+- 「现场改 SOUL 不被覆盖」既是优点也是坑——A 改了 SOUL 但忘了同步源码，下次新机器部署又回到旧版本
+
+#### 11.7.4 方案 C：纯运维流程（最弱，不推荐）
+
+不动代码、不动 .gitignore，发布说明里写一行：
+
+> 部署前请将 `<开发机>:offline-backend-20260512/backend/.deer-flow/agents/` 整个目录 `scp` 到部署机同位置。
+
+只在「不允许改仓库结构」或「初期试跑」时用。长期维护几乎一定会有人忘记拷而部署失败。
+
+#### 11.7.5 方案选择决策
+
+| 场景 | 推荐方案 |
+|------|----------|
+| 单仓库多人协作、SOUL 经常调整 | **A**（.gitignore 白名单） |
+| SOUL 极少改，希望严格区分代码与运行时数据 | **B**（源码 + lifespan 种子化） |
+| 一次性 POC / 即将切换到 B | C |
+
+无论选哪种，部署机第一次启动后都建议跑这条 smoke test 验证：
+
+```bash
+curl -X POST http://127.0.0.1:8001/api/intent/init \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+# 期望: 200 + {"status":"success","agent_id":"roundtable-intent","thread_id":"..."}
+
+curl -X POST http://127.0.0.1:8001/api/intent/stream \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"thread_id":"<上一步返回的>","message":"测试一下"}'
+# 期望: 200 + SSE 长连接,最后一帧 status 为 asking 或 clarification
+# 若 500 → 看后端日志,大概率是 SOUL.md 找不到或 LLM 外网不通(看上一条排查项)
+```
+
+#### 11.7.6 推荐智能体（`roundtable-recommender`）与研讨席位的关系（注：完整定制流程见 §11.8）
+
+推荐路由 `recommend.py` 用到的 `roundtable-recommender` 与「研讨席位」是**两件事**：
+
+- **`roundtable-recommender`**：负责从候选池里挑 picks 的「推荐者」本身，是个 LLM agent，**功能型**，所有部署必须有
+- **研讨席位**（无论是 6 个示例还是客户自有 agent）：是「被挑选的候选」，前端 `filterRecommendCandidates` 过滤后送进 `/api/recommend/stream` 的 `candidates` 数组；recommender 在 SOUL 里看到候选池后才能输出 `[RECOMMEND_READY]` JSON
+
+「推荐改成动态」改的是**从池子里挑哪几个**，不是「池子可以没有」。**池子的来源在两类部署里不同**：
+
+| 部署 | 候选池来源 |
+|------|------------|
+| 互联网 demo | 仓库自带的 6 个 `roundtable-<领域>` 示例席位（+ 用户自建的） |
+| 内网客户 | 客户自有的业务 agent（通过 `POST /api/agents` 或 `.deer-flow/agents/<id>/` 注册）|
+
+`roundtable-recommender/SOUL.md` 本身没写死任何候选 id（只描述「从给的候选池里挑」），所以内网部署即使候选池从「6 个示例」换成「客户自有 agent」，**recommender 的 SOUL 无需改动**，候选池由前端传入。
+
+**前端 fallback 行为差异**：
+
+互联网 demo 因为有这 6 个内置示例席位垫底，推荐失败时 `FALLBACK_AGENT_IDS ∩ candidates` 还能拿到回退选项；**内网部署该交集恒为空**，回退路径失效——所以内网部署应通过「候选池足够丰富 + recommender SOUL 调好」让推荐成功率接近 100%，或改造前端 `FALLBACK_AGENT_IDS` 为动态从 `/api/agents` 取前 N 个（见前端文档 §6.2）。
+
 ### 11.4 新增 Step 1 工具
 
 若需新工具，须同步修改 `intent.py` 的 `excluded_tools` 黑名单（当前默认禁 15 个工具，仅 `ask_clarification` 实际可用）。
@@ -691,6 +921,181 @@ grep "special-timing"   .runtime/logs/*.log   # payload_built / first_upstream_l
 
 `_append_thread_message` 通过 `GET state → mutate → POST state` 实现，是为了与 LangGraph checkpoint 一致；如果将来 Gateway 提供 `POST /api/threads/{id}/messages/append` 这类原子接口，可换上，降低并发竞争（虽然圆桌当前不会并发广播同一 thread）。
 
+### 11.8 添加 / 替换任务推荐智能体（`roundtable-recommender`）
+
+推荐智能体 id 在后端是**硬编码**常量（`recommend.py:63` → `RECOMMENDER_AGENT_ID = "roundtable-recommender"`），路由不接收 `agent_id` 参数。因此「添加推荐智能体」**不是新增一个 id**，而是落地这个固定 id 对应的文件（首次部署）或**就地改 SOUL**（定制行为）。
+
+#### 11.8.1 何时需要动它
+
+| 场景 | 是否需要动 SOUL |
+|------|-----------------|
+| 全新部署，目录还不存在 | ✅ 必须先把目录搭起来（§11.8.2） |
+| 候选池从 6 个互联网示例换成客户自有 agent | ❌ **不用改**——SOUL 没写死候选 id，候选池由前端传入 |
+| 想改变推荐风格（更激进 / 更保守 / 偏好某领域） | ✅ 改 SOUL（§11.8.4） |
+| 想让模型偏好你新加的领域 agent | ⚠️ **优先**改新 agent 的 `description`（候选池 prompt 用的就是它），其次才改 recommender SOUL |
+| 想改输出 JSON 格式 | ❌ **不要**——后端正则 `_RECOMMEND_READY_PATTERN` 写死了 `[RECOMMEND_READY]` + ```json ``` 块；改 SOUL 输出会让后端解析失败走 fallback |
+
+#### 11.8.2 标准目录结构
+
+```
+.deer-flow/agents/roundtable-recommender/
+├── config.yaml      # id / name / description(只是 DB 元数据,不进 prompt)
+└── SOUL.md          # 行为契约,详见 11.8.4
+```
+
+**`config.yaml` 模板**（**id 必须严格等于 `roundtable-recommender`**，否则 `recommend.py` 找不到）：
+
+```yaml
+description: 智能体推荐专员,基于用户的任务目标与约束,从候选智能体池中挑选最相关的 2-6 个智能体并给出推荐理由,为多智能体圆桌研讨准备最终参会名单
+id: roundtable-recommender
+name: 智能体推荐
+```
+
+字段说明：
+- `id`：**不可改**，与 `RECOMMENDER_AGENT_ID` 常量绑死
+- `name`：DB 显示名，候选池过滤时不参与（`filterRecommendCandidates` 按 id 排除）
+- `description`：DB 元数据，不进 prompt；改了不会影响推荐效果
+
+**SOUL.md** 内容见 §11.8.4 模板。新增之后按 §11.7.2 把这两个文件加入 git 白名单 + commit 即可。
+
+#### 11.8.3 后端给推荐智能体喂的 prompt 长什么样
+
+`recommend.py:_build_prompt()` 把前端传的 intent + candidates 拼成下面这段，作为**唯一一条 user message** 投递：
+
+```
+任务目标:对生产系统进行安全改造,满足等保 2.0 合规要求
+约束:预算 ≤ 500 万元; 工期 ≤ 6 个月; 必须满足等保 2.0
+关键假设:现有系统具备基础数字化能力; 允许预定窗口停机
+
+候选智能体池:
+- roundtable-intelligence (情报收集): 检索同类历史案例、行业最佳实践与外部情报
+- roundtable-solution-design (方案设计): 产出主备方案与关键路径
+- my-cost-calc (成本测算): 基于预算和资源单价计算总成本
+- ...
+
+请按 SOUL 中规定的格式输出推荐结果(自然语言思路 + [RECOMMEND_READY] + json 块)。
+```
+
+**关键事实**：
+- **候选 agent 的 `name` 与 `description` 在 prompt 里就是它的「介绍」**——这是模型判断「这个 agent 适不适合本任务」的全部信息。客户自有 agent 想被推荐准确，`description` 必须写**任务导向**的能力描述，不要写 "由 XX 团队维护" 这种元信息
+- **候选池由前端过滤后传入**，后端不读 DB；前端 `filterRecommendCandidates` 已剔除 `roundtable-intent / roundtable-recommender / roundtable-coordinator-*`
+- SOUL 看不到「intent agent 上一轮说了什么 / 用户原始 message」，只看到结构化的 `objective / constraints / assumptions`——这是设计选择，让推荐稳定
+
+#### 11.8.4 SOUL 设计要点（模板 + 注解）
+
+SOUL **必须**满足三件事，其它都可定制：
+
+1. **输出格式严格**：自然语言思路 → `[RECOMMEND_READY]` 单独成行 → ```json {"picks": [{"agent_id": "...", "reason": "..."}, ...]} ```
+2. **`agent_id` 严格来自候选池**：模型造词出来会被 `_validate_picks` 过滤掉
+3. **2 ≤ picks ≤ 6**：少于 2 → 整轮判 `asking` 走 fallback；多于 6 → 后端截断
+
+下面是一份可直接用的最小 SOUL，重点行带注释（**真正落盘时去掉 `<!-- -->`**）：
+
+```markdown
+# 智能体推荐专员
+
+## 角色定位
+你是多智能体圆桌研讨的"智能体推荐专员"。任务理解专员已经把用户需求整理成
+「任务目标 + 约束 + 关键假设」交给你,你的工作是从一个**候选智能体池**里,
+挑出**最适合**参加这次圆桌研讨的 2-6 个智能体,并为每一位写一句推荐理由。
+
+## 核心职责
+- 仔细阅读用户的任务目标与约束
+- 浏览候选池中每个智能体的 `name` 与 `description`
+- 选出与本次任务**最相关**的 2-6 个智能体(数量动态,不必凑齐 6 个)
+- 为每个推荐的智能体写一句**具体、可验证**的推荐理由
+- 不推荐重复职能 / 不推荐与任务明显无关的智能体(宁缺毋滥)
+
+## 数量约束
+- **下限**:至少 2 个 / **上限**:最多 6 个
+- 候选池不足 2 个时,有几个推几个
+
+## 输出协议(后端用正则识别,严格执行)
+1. 先用自然语言简短说明推荐思路(1-3 句话)
+2. 输出标记 `[RECOMMEND_READY]` 单独成行
+3. 紧接一个 ```json 代码块:
+
+   ```json
+   {
+     "picks": [
+       {"agent_id": "<候选池中的 id>", "reason": "<一句推荐理由>"},
+       ...
+     ]
+   }
+   ```
+
+格式注意:
+- `[RECOMMEND_READY]` **单独成行**,前后无其他字符
+- `agent_id` **严格**来自候选池,不要造词
+- `reason` **具体**,不要"很合适"这种空话
+
+## 边界
+- 不调用任何工具(已被后端 excluded_tools 屏蔽)
+- 不评价候选 agent 优劣,只判断"是否适合本次任务"
+- 不发起对话、不反问用户
+
+## 示例
+<!-- 示例对模型的引导能力远超规则文字,
+     建议示例的候选池里**包含一两个你部署里的客户自有 agent**,
+     让模型知道这种"非 roundtable-* 前缀"的 id 也是合法的。 -->
+```
+
+##### 定制方向
+
+- **偏好新加的 agent**：在「示例」里把它列进候选池并出现在推荐结果中，模型会学到这种 id 也可推荐。比单纯在「核心职责」里加文字约束有效
+- **行业偏向**：在「角色定位」加一句「优先考虑能直接对接 <行业> 合规要求的智能体」
+- **激进 vs 保守**：调「数量约束」——例如「能挑出强相关的 3 个就不要凑 6 个」会让 picks 缩到 3-4 个
+- **不要做的事**：
+  - ❌ 改 `[RECOMMEND_READY]` 为别的标记 → 解析失败
+  - ❌ 把 JSON 结构改成 `{"recommendations": [...]}` 之类 → 解析失败
+  - ❌ 让模型只输出 JSON 不带前面的自然语言 → 前端 `parseRecommendStreamContent` 把整段当 `rationale`，弹窗顶部为空白
+
+#### 11.8.5 验证流程
+
+部署完成后跑 smoke test 确认推荐路径通：
+
+```bash
+# 1. 确认 agent 文件落地
+ls .deer-flow/agents/roundtable-recommender/
+# 期望: SOUL.md  config.yaml
+
+# 2. 确认 DB 已 upsert(任意 /api/agents 请求会触发 _sync_legacy_agents)
+curl -H "Authorization: Bearer <TOKEN>" http://127.0.0.1:8001/api/agents | \
+  python -c "import sys,json; ids=[a['id'] for a in json.load(sys.stdin).get('agents',[])]; print('roundtable-recommender' in ids)"
+# 期望: True
+
+# 3. 触发一次推荐(用最小 intent + 候选池)
+curl -X POST http://127.0.0.1:8001/api/recommend/stream \
+  -H "Authorization: Bearer <TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "intent": {
+      "objective": "测试推荐链路",
+      "constraints": ["响应时间 < 30s"],
+      "assumptions": []
+    },
+    "candidates": [
+      {"agent_id": "agent-a", "name": "A", "description": "做 X"},
+      {"agent_id": "agent-b", "name": "B", "description": "做 Y"},
+      {"agent_id": "agent-c", "name": "C", "description": "做 Z"}
+    ]
+  }'
+# 期望(SSE 流):最后一帧 data: {"status":"done","content":"...","picks":[...]}
+# 若 picks 是空 → SOUL 没产生合法 [RECOMMEND_READY] / agent_id 不在候选池
+# 若整轮 status=error → 看后端 _diagnose_exception 输出的 hint
+```
+
+#### 11.8.6 故障排查清单
+
+| 现象 | 排查方向 |
+|------|----------|
+| 推荐永远走 fallback（status=asking） | 后端日志 grep `recommend stream`，看 `last_ai_content` 是不是不含 `[RECOMMEND_READY]`——SOUL 没遵守协议 |
+| `picks` 数量被截断到 6 | 后端 `_MAX_PICKS=6` 故意限制，前端用户可再手加到 8 |
+| 模型推荐了候选池里没有的 id | `_validate_picks` 会丢掉，但若有效项不足 2 个会整轮走 fallback；改 SOUL 强调「严格来自候选池」 |
+| 推荐结果不偏向客户自有 agent | 先检查该 agent 的 `description` 是不是写得「任务导向」；再考虑在 SOUL 示例里加它 |
+| 推荐稳定性差（同 intent 重跑结果飘） | 推荐 model 用低 temperature（在 `roundtable-recommender/config.yaml` 加 `model: <某个低 temp 模型>` 或直接前端选 deterministic 模型） |
+| 前端弹窗顶部 rationale 区空白 | SOUL 让模型只输出 JSON 没有自然语言；恢复成「先思路 + 后 JSON」 |
+
 ---
 
 ## 12. 故障排查
diff --git a/frontend-web/docs/multi-agent-frontend-dev.md b/frontend-web/docs/multi-agent-frontend-dev.md
index f4336e7c..6b7de99d 100644
--- a/frontend-web/docs/multi-agent-frontend-dev.md
+++ b/frontend-web/docs/multi-agent-frontend-dev.md
@@ -370,9 +370,9 @@ isOrchestrating = false
   - 追加一条「⚡ [模型偏好已保存] ...」对话气泡
   - **不**立即重启编排；下一轮该席位被派活时 `runOrchestration` 内会读 `agentConfigs[meta.speakerId]?.model || selectedModel || undefined` 作为 special 调用的 `model` 参数
 
-### 5.6 全局模型选择器（顶栏）
+### 5.6 全局模型选择器（右侧 sidebar 顶部）
 
-- **位置**：顶栏右侧「新建任务」按钮左边，`<select>` 包在带 `Cpu` 图标的标签里
+- **位置**：右侧 sidebar `currentStep !== 3` 时显示的第一个面板 —— 在「当前意图摘要」**正上方**。Step 3 时整个 sidebar 切换成「最终共识结论 / 风险与预算摘要 / 导出与交付」，所以模型选择器仅在 Step 1 / Step 2 可见（此时也是唯一会发起新模型调用的阶段）
 - **state**：`const [selectedModel, setSelectedModel] = useState<string>("")`
 - **初始化**：`useEffect(() => ...)` 在 `availableModels` 首次返回后把 `selectedModel` 设为 `availableModels[0].name`；后端配置变化导致当前选中 model 不在列表里时也回退到首项
 - **传参规则**：所有 5 个 API 调用点（`initIntent` / `streamIntent` / `streamRecommend` / `initMultiAgent` / `streamMultiAgent` leader / `streamMultiAgent` special）都传 `selectedModel || undefined`；special 还会先看 `agentConfigs[seat]?.model` per-seat 覆盖
diff --git a/frontend-web/src/roundtable-planning/api/intent.ts b/frontend-web/src/roundtable-planning/api/intent.ts
index dabcdb3e..206c9335 100644
--- a/frontend-web/src/roundtable-planning/api/intent.ts
+++ b/frontend-web/src/roundtable-planning/api/intent.ts
@@ -21,9 +21,80 @@ export interface IntentInitResponse {
   thread_id: string;
 }
 
+/**
+ * Structured diagnostic payload surfaced by the backend whenever an intent
+ * route raises (init) or yields a final `status: "error"` frame (stream).
+ * Same shape across `init_intent` / `stream_intent`; renderer keys off `code`
+ * for quick visual triage, but also shows `hint` + `trace_tail` as a panel
+ * so deployment-time issues (config.yaml unreachable LLM, missing builtin
+ * agent dirs, loopback going through proxy) are debuggable from the UI alone
+ * without tail-ing backend logs.
+ */
+export interface IntentErrorDetail {
+  /** Stable short category — see backend `_diagnose_exception`. */
+  code: string;
+  /** One-line human-readable description (already includes exception type). */
+  message: string;
+  exception_type: string;
+  exception_repr: string;
+  /** Root of the `__cause__` chain when distinct from the outer exception. */
+  root_type?: string | null;
+  root_repr?: string | null;
+  /** Actionable hint in Chinese, keyed by `code`. May be null for unrecognized errors. */
+  hint?: string | null;
+  /** Last ~12 lines of the traceback for in-UI inspection. */
+  trace_tail?: string[];
+  /** Caller-supplied label (e.g. "intent_init"). */
+  context?: string | null;
+}
+
+/**
+ * Thrown by `initIntent` when the HTTP call fails. Carries the parsed
+ * `IntentErrorDetail` (if the backend emitted one) so the page can render
+ * a rich diagnostic panel instead of a one-line message.
+ */
+export class IntentInitError extends Error {
+  /** HTTP status (typically 500 for diagnosed failures, 401/403 for auth). */
+  readonly status: number;
+  /** Structured detail when the backend emitted `_diagnose_exception` output. */
+  readonly detail: IntentErrorDetail | null;
+  /** Raw body text when JSON parse failed (kept for completeness). */
+  readonly rawBody: string;
+
+  constructor(status: number, detail: IntentErrorDetail | null, rawBody: string) {
+    super(detail?.message || `init intent failed (${status}): ${rawBody}`);
+    this.name = "IntentInitError";
+    this.status = status;
+    this.detail = detail;
+    this.rawBody = rawBody;
+  }
+}
+
+function parseIntentErrorDetail(value: unknown): IntentErrorDetail | null {
+  if (!value || typeof value !== "object") return null;
+  const obj = value as Record<string, unknown>;
+  if (typeof obj.code !== "string" || typeof obj.message !== "string") return null;
+  return {
+    code: obj.code,
+    message: obj.message,
+    exception_type: typeof obj.exception_type === "string" ? obj.exception_type : "",
+    exception_repr: typeof obj.exception_repr === "string" ? obj.exception_repr : "",
+    root_type: typeof obj.root_type === "string" ? obj.root_type : null,
+    root_repr: typeof obj.root_repr === "string" ? obj.root_repr : null,
+    hint: typeof obj.hint === "string" ? obj.hint : null,
+    trace_tail: Array.isArray(obj.trace_tail) ? obj.trace_tail.filter((l): l is string => typeof l === "string") : [],
+    context: typeof obj.context === "string" ? obj.context : null,
+  };
+}
+
 /**
  * Create a fresh thread for an intent-clarification session.
  * The backend returns the built-in agent id so the frontend doesn't hardcode it.
+ *
+ * On failure throws `IntentInitError` whose `.detail` carries the backend's
+ * `_diagnose_exception` payload — the page should surface `detail.hint` /
+ * `detail.trace_tail` to help diagnose intranet deployment issues without
+ * shell access to the server.
  */
 export async function initIntent(model?: string): Promise<IntentInitResponse> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/intent/init`, {
@@ -32,8 +103,18 @@ export async function initIntent(model?: string): Promise<IntentInitResponse> {
     body: JSON.stringify({ model }),
   });
   if (!res.ok) {
-    const text = await res.text().catch(() => "");
-    throw new Error(`init intent failed (${res.status}): ${text}`);
+    const raw = await res.text().catch(() => "");
+    let detail: IntentErrorDetail | null = null;
+    try {
+      const parsed = JSON.parse(raw);
+      // FastAPI HTTPException(detail=dict) → { "detail": {...} }
+      if (parsed && typeof parsed === "object" && parsed !== null) {
+        detail = parseIntentErrorDetail((parsed as { detail?: unknown }).detail) || parseIntentErrorDetail(parsed);
+      }
+    } catch {
+      // body wasn't JSON — fall through with raw text only.
+    }
+    throw new IntentInitError(res.status, detail, raw);
   }
   return (await res.json()) as IntentInitResponse;
 }
@@ -89,6 +170,12 @@ export interface StreamIntentResult {
    * cards + custom input instead of treating the turn as plain text only.
    */
   clarification: ClarificationPayload | null;
+  /**
+   * Populated only when status === "error" and the backend emitted a
+   * structured diagnostic (new in `_diagnose_exception`). UI uses this to show
+   * the same rich panel as init failures.
+   */
+  errorDetail: IntentErrorDetail | null;
 }
 
 /**
@@ -106,6 +193,7 @@ function isFinalIntentFrame(value: unknown): value is {
   options?: unknown[];
   allow_custom?: boolean;
   allow_multiple?: boolean;
+  error_detail?: unknown;
 } {
   if (!value || typeof value !== "object") return false;
   if (!("status" in value) || !("content" in value)) return false;
@@ -192,6 +280,7 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
     content: "",
     summary: null,
     clarification: null,
+    errorDetail: null,
   };
 
   while (true) {
@@ -231,6 +320,9 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
         if (parsed.summary && typeof parsed.summary === "object") {
           result.summary = parsed.summary as IntentSummary;
         }
+        if (parsed.status === "error") {
+          result.errorDetail = parseIntentErrorDetail(parsed.error_detail);
+        }
         if (parsed.status === "clarification") {
           const clarificationType =
             typeof parsed.clarification_type === "string" ? parsed.clarification_type : "";
diff --git a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
index 4ae16256..40379cd4 100644
--- a/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
+++ b/frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx
@@ -57,7 +57,9 @@ import {
 } from "@/roundtable-planning/api/multi-agent";
 import {
   initIntent,
+  IntentInitError,
   streamIntent,
+  type IntentErrorDetail,
   type IntentStreamPhase,
   type IntentSummary,
 } from "@/roundtable-planning/api/intent";
@@ -504,6 +506,8 @@ export default function RoundtablePlanningPage() {
   const [intentThreadId, setIntentThreadId] = useState<string | null>(null);
   const [intentReady, setIntentReady] = useState<IntentSummary | null>(null);
   const [intentInitError, setIntentInitError] = useState<string | null>(null);
+  // 后端 _diagnose_exception 输出的结构化诊断,有就额外渲染 hint + trace_tail 面板。
+  const [intentInitErrorDetail, setIntentInitErrorDetail] = useState<IntentErrorDetail | null>(null);
   const [isIntentSending, setIsIntentSending] = useState<boolean>(false);
   const [pendingIntentClarificationMsgId, setPendingIntentClarificationMsgId] = useState<number | null>(null);
   const [intentClarificationSelections, setIntentClarificationSelections] = useState<
@@ -1225,6 +1229,7 @@ export default function RoundtablePlanningPage() {
     const myGen = ++step1InitGenRef.current;
     setIntentReady(null);
     setIntentInitError(null);
+    setIntentInitErrorDetail(null);
     setIntentThreadId(null);
     setPendingIntentClarificationMsgId(null);
     setIntentClarificationSelections(new Map());
@@ -1256,7 +1261,14 @@ export default function RoundtablePlanningPage() {
       } catch (err) {
         if (step1InitGenRef.current !== myGen) return;
         console.error("init intent failed:", err);
-        setIntentInitError((err as Error).message);
+        if (err instanceof IntentInitError) {
+          // 优先使用后端的可读 message;若 detail 在,渲染诊断面板。
+          setIntentInitError(err.detail?.message || err.message);
+          setIntentInitErrorDetail(err.detail);
+        } else {
+          setIntentInitError((err as Error).message);
+          setIntentInitErrorDetail(null);
+        }
       }
     })();
   }, []);
@@ -1420,6 +1432,7 @@ export default function RoundtablePlanningPage() {
       setIntentThreadId(draft.step1.intentThreadId);
       setIntentReady(draft.step1.intentReady);
       setIntentInitError(null);
+      setIntentInitErrorDetail(null);
       setInteractiveMessages(draft.step1.interactiveMessages as typeof interactiveMessages);
       setTimelineEntries(draft.step1.timelineEntries as typeof timelineEntries);
       step1InitRef.current = true;
@@ -1629,6 +1642,15 @@ export default function RoundtablePlanningPage() {
           return next;
         });
       } else if (res.status === "error") {
+        // 同时把诊断信息写到顶部面板:toast 一闪而过,面板能稳定展示 hint + trace_tail
+        // 方便用户截图发给后端排查。
+        if (res.errorDetail) {
+          setIntentInitError(res.errorDetail.message || res.content);
+          setIntentInitErrorDetail(res.errorDetail);
+        } else {
+          setIntentInitError(res.content);
+          setIntentInitErrorDetail(null);
+        }
         triggerToast(`❌ 智能体调用失败: ${res.content}`);
       }
     } catch (err) {
@@ -1955,41 +1977,6 @@ export default function RoundtablePlanningPage() {
 
         {/* Right Actions */}
         <div className="flex items-center gap-2">
-          {/* 全局模型选择器
-              ─────────────────────────────────────────────
-              影响 Step 1 / 推荐 / Step 2 init / 总控 leader / 子席位 special
-              所有 API 调用。Persona 抽屉里 per-seat 设置的 model 优先级更高。
-              选项来自 /api/models(由 config.yaml 配置),内网部署只需配自家模型。 */}
-          <label className="flex items-center gap-1.5 bg-white border border-[#e2e8f0] rounded-xl px-2.5 py-1.5 text-xs font-bold text-[#334155] dark:border-border dark:bg-secondary dark:text-foreground">
-            <Cpu className="w-3.5 h-3.5 text-primary" />
-            <span className="text-[10px] text-slate-400 font-mono">模型</span>
-            <select
-              id="global-model-select"
-              value={selectedModel}
-              onChange={(e) => setSelectedModel(e.target.value)}
-              disabled={modelsLoading || availableModels.length === 0}
-              title={
-                modelsLoading
-                  ? "正在加载模型列表…"
-                  : availableModels.length === 0
-                    ? "未在 config.yaml 中配置任何模型"
-                    : "切换全局推理模型;不影响 Persona 抽屉里已设置的 per-seat 覆盖"
-              }
-              className="bg-transparent border-none outline-none text-xs font-bold text-slate-700 cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed dark:text-foreground"
-            >
-              {availableModels.length === 0 && (
-                <option value="">{modelsLoading ? "加载中…" : "未配置模型"}</option>
-              )}
-              {availableModels.map((m) => (
-                <option key={m.name} value={m.name}>
-                  {m.display_name && m.display_name !== m.name
-                    ? `${m.display_name} (${m.name})`
-                    : m.name}
-                </option>
-              ))}
-            </select>
-          </label>
-
           <button
             id="new-task-btn"
             onClick={handleStartNewTask}
@@ -2512,9 +2499,40 @@ export default function RoundtablePlanningPage() {
                       </button>
                     </div>
                     {intentInitError && (
-                      <p className="mt-2 text-[11px] text-red-500 font-medium">
-                        智能体初始化失败: {intentInitError}
-                      </p>
+                      <div className="mt-2 rounded-lg border border-red-200 bg-red-50/70 p-3 text-[11px] leading-relaxed">
+                        <div className="flex items-center gap-2 mb-1.5">
+                          <span className="font-bold text-red-700">智能体初始化失败</span>
+                          {intentInitErrorDetail?.code && (
+                            <span className="px-1.5 py-0.5 bg-red-100 text-red-700 rounded font-mono text-[10px]">
+                              {intentInitErrorDetail.code}
+                            </span>
+                          )}
+                          {intentInitErrorDetail?.exception_type && (
+                            <span className="text-[10px] text-red-600 font-mono">
+                              {intentInitErrorDetail.exception_type}
+                              {intentInitErrorDetail.root_type && intentInitErrorDetail.root_type !== intentInitErrorDetail.exception_type
+                                ? ` → ${intentInitErrorDetail.root_type}`
+                                : ""}
+                            </span>
+                          )}
+                        </div>
+                        <p className="text-red-700 font-medium break-all">{intentInitError}</p>
+                        {intentInitErrorDetail?.hint && (
+                          <p className="mt-1.5 text-red-800 bg-amber-50 border-l-2 border-amber-400 px-2 py-1 rounded-sm">
+                            <span className="font-bold">💡 建议:</span> {intentInitErrorDetail.hint}
+                          </p>
+                        )}
+                        {intentInitErrorDetail?.trace_tail && intentInitErrorDetail.trace_tail.length > 0 && (
+                          <details className="mt-1.5">
+                            <summary className="cursor-pointer text-red-600 hover:text-red-800 select-none text-[10px] font-bold">
+                              展开 traceback 末段(共 {intentInitErrorDetail.trace_tail.length} 行)
+                            </summary>
+                            <pre className="mt-1 max-h-48 overflow-auto bg-slate-900 text-slate-100 text-[10px] leading-snug p-2 rounded font-mono whitespace-pre">
+{intentInitErrorDetail.trace_tail.join("\n")}
+                            </pre>
+                          </details>
+                        )}
+                      </div>
                     )}
                   </div>
                 )}
@@ -3652,6 +3670,44 @@ export default function RoundtablePlanningPage() {
             </>
           ) : (
             <>
+              {/* Panel 0: 推理模型选择器
+                  ─────────────────────────────────────────────────────
+                  全局选中模型(selectedModel)影响 Step 1 / 推荐 / Step 2 init /
+                  总控 leader / 子席位 special 所有 API 调用。Persona 抽屉里
+                  per-seat 覆盖优先级更高。
+                  选项来自 /api/models(由 config.yaml 配置),内网部署只需配自家模型。 */}
+              <div className="bg-white border border-slate-200/50 rounded-2xl p-4 shadow-[0_2px_8px_rgba(0,0,0,0.01)]">
+                <div className="flex items-center gap-2 border-b border-slate-100 pb-2.5 mb-2.5">
+                  <Cpu className="w-4 h-4 text-primary" strokeWidth={2.5} />
+                  <h2 className="text-xs font-bold text-slate-900 uppercase tracking-widest">推理模型</h2>
+                </div>
+                <select
+                  id="global-model-select"
+                  value={selectedModel}
+                  onChange={(e) => setSelectedModel(e.target.value)}
+                  disabled={modelsLoading || availableModels.length === 0}
+                  title={
+                    modelsLoading
+                      ? "正在加载模型列表…"
+                      : availableModels.length === 0
+                        ? "未在 config.yaml 中配置任何模型"
+                        : "切换全局推理模型;不影响 Persona 抽屉里已设置的 per-seat 覆盖"
+                  }
+                  className="w-full bg-slate-50/50 border border-slate-100 rounded-xl px-3 py-2 text-xs font-bold text-slate-700 cursor-pointer focus:outline-none focus:border-primary focus:ring-1 focus:ring-[var(--brand-200)]/50 disabled:opacity-50 disabled:cursor-not-allowed dark:bg-secondary dark:text-foreground dark:border-border"
+                >
+                  {availableModels.length === 0 && (
+                    <option value="">{modelsLoading ? "加载中…" : "未配置模型"}</option>
+                  )}
+                  {availableModels.map((m) => (
+                    <option key={m.name} value={m.name}>
+                      {m.display_name && m.display_name !== m.name
+                        ? `${m.display_name} (${m.name})`
+                        : m.name}
+                    </option>
+                  ))}
+                </select>
+              </div>
+
               {/* Panel 1: 当前意图摘要 */}
               <div className="bg-white border border-slate-200/50 rounded-2xl p-4.5 shadow-[0_2px_8px_rgba(0,0,0,0.01)]">
                 <div className="flex items-center gap-2 border-b border-slate-100 pb-2.5 mb-2.5">
diff --git a/offline-backend-20260512/backend/app/gateway/routers/intent.py b/offline-backend-20260512/backend/app/gateway/routers/intent.py
index b97397d6..425b24db 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/intent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/intent.py
@@ -66,6 +66,7 @@ from fastapi.responses import StreamingResponse
 from app.gateway.routers.multi_agent import (
     _auth_headers,
     _create_thread,
+    _diagnose_exception,
     _find_dispatch_message,
     _find_trailing_ai_text,
     _flatten_content,
@@ -112,8 +113,20 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
     # on the dev machine) makes httpx route loopback calls through an upstream
     # proxy that can't reach 127.0.0.1, costing 40+ seconds of timeout per
     # request before falling back. Symptom in logs: `headers_in=42.160s`.
-    async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
-        thread_id = await _create_thread(client, base, headers)
+    try:
+        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+            thread_id = await _create_thread(client, base, headers)
+    except HTTPException:
+        # 上游已用结构化方式失败,原样传给前端不需要二次包装。
+        raise
+    except Exception as exc:
+        # 把根因暴露给前端而不是吞成裸 500——内网部署常见的「config.yaml 模型外网不通」
+        # / 「内置 agent 目录缺失」/ 「loopback 走代理」都能在前端面板直接看到。
+        # FastAPI 把 detail=dict 序列化为 {"detail": {...}};前端 initIntent
+        # 在 !res.ok 分支里读 detail.hint / trace_tail 渲染诊断面板。
+        diagnostic = _diagnose_exception(exc, context="intent_init")
+        logger.error("intent init failed: %s", diagnostic, exc_info=exc)
+        raise HTTPException(status_code=500, detail=diagnostic) from exc
     return {
         "status": "success",
         "agent_id": INTENT_AGENT_ID,
@@ -270,11 +283,40 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
 
             except HTTPException as exc:
                 logger.warning("intent stream HTTPException: %s %s", exc.status_code, exc.detail)
-                err = {"status": "error", "content": f"[{exc.status_code}] {exc.detail}", "summary": None}
+                # HTTPException 的 detail 可能本身就是 dict(上游已结构化),也可能是 str。
+                # 统一包装成与 _diagnose_exception 同构的字段,便于前端按一种模型渲染。
+                detail_payload: Any = exc.detail
+                error_detail: dict[str, Any]
+                if isinstance(detail_payload, dict) and "code" in detail_payload:
+                    error_detail = detail_payload
+                else:
+                    error_detail = {
+                        "code": "http_exception",
+                        "message": f"[{exc.status_code}] {detail_payload}",
+                        "exception_type": "HTTPException",
+                        "exception_repr": repr(exc),
+                        "root_type": None,
+                        "root_repr": None,
+                        "hint": None,
+                        "trace_tail": [],
+                        "context": "intent_stream",
+                    }
+                err = {
+                    "status": "error",
+                    "content": error_detail["message"],
+                    "summary": None,
+                    "error_detail": error_detail,
+                }
                 yield f"data: {json.dumps(err, ensure_ascii=False)}\n\n"
             except Exception as exc:
-                logger.exception("intent stream unexpected failure")
-                err = {"status": "error", "content": f"unexpected: {exc!r}", "summary": None}
+                diagnostic = _diagnose_exception(exc, context="intent_stream")
+                logger.error("intent stream failed: %s", diagnostic, exc_info=exc)
+                err = {
+                    "status": "error",
+                    "content": diagnostic["message"],
+                    "summary": None,
+                    "error_detail": diagnostic,
+                }
                 yield f"data: {json.dumps(err, ensure_ascii=False)}\n\n"
 
     return StreamingResponse(
diff --git a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
index afcd3de1..ce41e820 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
@@ -51,6 +51,7 @@ import json
 import logging
 import re
 import time
+import traceback
 from typing import Any, AsyncIterator
 
 import httpx
@@ -62,6 +63,101 @@ logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/multi-agent", tags=["multi-agent"])
 
 
+# ---------------------------------------------------------------------------
+# 共享:异常诊断器(intent/recommend/multi-agent 共用)
+# ---------------------------------------------------------------------------
+
+
+def _diagnose_exception(exc: BaseException, *, context: str = "") -> dict[str, Any]:
+    """把后端异常转成结构化诊断 dict,直接给前端展示用。
+
+    设计目标:让运维 / 前端开发不用翻 backend 日志就能看到根因和处置建议。
+    返回字段:
+      - code:           短稳定分类(loopback_connect_failed / upstream_connect_failed / ...)
+      - message:        一行人类可读
+      - exception_type: 表层异常类名
+      - exception_repr: repr(exc)
+      - root_type / root_repr: 沿 __cause__ 链找到的最深异常(若与表层不同)
+      - hint:           针对常见失败模式的可执行建议(中文)
+      - trace_tail:     traceback 最后 ~12 行(避免响应体过大)
+      - context:        调用方标签(如 "intent_init")
+    """
+    exc_type = type(exc).__name__
+    exc_repr = repr(exc)
+
+    # 沿 __cause__ 链找最深异常:httpx 经常把 ConnectError 包成 RemoteProtocolError 等。
+    root: BaseException = exc
+    seen: set[int] = {id(root)}
+    while getattr(root, "__cause__", None) is not None and id(root.__cause__) not in seen:
+        root = root.__cause__  # type: ignore[assignment]
+        seen.add(id(root))
+
+    code = "unexpected"
+    hint = "查看 trace_tail 最后一帧定位代码位置;若信息不足请到 backend 日志找完整 traceback。"
+
+    if isinstance(root, httpx.ConnectError):
+        target = str(root).strip().lower()
+        # loopback 失败 = Gateway 自己没起 / 代理拦回环;outbound 失败 = LLM 提供商不可达。
+        if "127.0.0.1" in target or "localhost" in target or "loopback" in target:
+            code = "loopback_connect_failed"
+            hint = (
+                "本地 Gateway loopback 连接失败:确认后端进程在 8001 端口监听;"
+                "另检查 HTTP_PROXY / HTTPS_PROXY 是否把 127.0.0.1 也走了代理"
+                "(代码已显式 trust_env=False,理论上不该走代理)。"
+            )
+        else:
+            code = "upstream_connect_failed"
+            hint = (
+                "外网/上游服务连接失败:大概率是 LLM 提供商不可达"
+                "(如 api.deepseek.com 在内网被防火墙拦截)。"
+                "把 config.yaml 里所有 base_url 改成内网可达的 LLM endpoint,"
+                "或加白名单/正向代理(HTTPS_PROXY)。"
+            )
+    elif isinstance(root, httpx.TimeoutException):
+        code = "upstream_timeout"
+        hint = (
+            "上游请求超时:网络抖动 / 模型推理过慢。"
+            "先 curl <base_url>/v1/models 确认可达,再看模型是否过载或 max_tokens 过大。"
+        )
+    elif isinstance(root, httpx.HTTPStatusError):
+        code = "upstream_http_error"
+        status = getattr(getattr(root, "response", None), "status_code", "?")
+        hint = (
+            f"上游接口返回 HTTP {status}:可能是 API key 失效、模型名不对、"
+            "或目标服务自身报错。查看 backend 日志里 response.text 拿详细错误体。"
+        )
+    elif isinstance(root, FileNotFoundError):
+        code = "file_not_found"
+        hint = (
+            f"找不到路径:{root}。常见原因:内置 agent 目录(.deer-flow/agents/<id>/)缺失,"
+            "或 SOUL.md 没拷过来;详见后端开发文档 §11.7。"
+        )
+    elif isinstance(root, KeyError):
+        code = "key_error"
+        hint = (
+            f"缺少 key:{root}。若 key 是 agent_name/agent_id 类:大概率内置 agent 目录缺失;"
+            "若是配置 key:检查 config.yaml schema。"
+        )
+    elif isinstance(root, ValueError) and "model" in str(root).lower():
+        code = "no_models_configured"
+        hint = "config.yaml 没有任何 models[],或所有条目都解析失败。检查 yaml 语法与 $ENV 引用。"
+
+    trace_lines = traceback.format_exception(type(exc), exc, exc.__traceback__)
+    trace_tail = "".join(trace_lines).splitlines()[-12:]
+
+    return {
+        "code": code,
+        "message": f"{exc_type}: {exc}" if str(exc) else exc_type,
+        "exception_type": exc_type,
+        "exception_repr": exc_repr,
+        "root_type": type(root).__name__ if root is not exc else None,
+        "root_repr": repr(root) if root is not exc else None,
+        "hint": hint,
+        "trace_tail": trace_tail,
+        "context": context or None,
+    }
+
+
 # ---------------------------------------------------------------------------
 # Loopback 辅助函数（Gateway → Gateway，同进程）
 # ---------------------------------------------------------------------------

From 48d22e0d420ea753cb6893f1f758d7135671ff83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Mon, 25 May 2026 22:51:38 +0800
Subject: [PATCH 05/10] =?UTF-8?q?ui=E8=A7=84=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/ui修改-深蓝.md | 702 +++++++++++++++++++++++++++++++
 1 file changed, 702 insertions(+)

diff --git a/frontend-web/docs/ui修改-深蓝.md b/frontend-web/docs/ui修改-深蓝.md
index 3aaa8028..a2d6a432 100644
--- a/frontend-web/docs/ui修改-深蓝.md
+++ b/frontend-web/docs/ui修改-深蓝.md
@@ -711,6 +711,8 @@
 ## 9. 锚点与页签
 
 > 对应"4.2 导航组件-锚点"。三类组件共用主色蓝指示当前位置：**页签 / 锚点 / 回到顶部**。
+>
+> 视觉参考：标签横向 / 标签纵向 / 锚点的三联图见设计稿「选项卡.png」——三种形态在本节均已规范化（§9.1 = 标签横纵向、§9.2 = 锚点）。
 
 ### 9.1 页签（Tabs）
 
@@ -833,3 +835,703 @@ Hover 状态下方显示 `回到顶部` 提示气泡：
 | 页签 | 同层级内容切换（多 Tab 互斥） | 文字 + 下划线（横/纵） |
 | 锚点 | 长页面内章节跳转 | 文字 + 左侧指示条 + 层级缩进 |
 | 回到顶部 | 长页面快速返回起点 | 圆形悬浮按钮 + 上箭头 |
+
+---
+
+## 10. 步骤条
+
+> 对应「4.7 导航组件-步骤条」。用于多步流程的进度指引，按布局方向分**横向**与**纵向**两类，按使用场景分**弹窗步骤条**、**页面步骤条**、**纵向步骤条**三种。所有颜色取自 ZS-002 主色蓝与 ZS-004 深蓝系。
+
+### 10.1 步骤节点（公共）
+
+每个步骤由「指示圆 + 标题（可选描述）」组成。指示圆按状态切换三种形态：
+
+| 状态 | 圆形外观 | 圆内符号 | 来源 |
+|------|----------|----------|------|
+| 已完成（Completed） | 描边圆，`2px solid #1677FF`，背景 `transparent` | `✓`（对勾，`#1677FF`） | ZS-002-06 |
+| 当前（Current / Active） | 实心圆，背景 `#1677FF` | 步骤数字，`#FFFFFF` | ZS-002-06 / 白 |
+| 未开始（Upcoming） | 描边圆，`1px solid #4A6491`，背景 `transparent` | 步骤数字，`#6E88B0` | ZS-004-05 / ZS-004-04 |
+| 失效（Disabled） | 描边圆，`1px solid #2D4473`，背景 `transparent` | 步骤数字，`#4A6491` | ZS-004-06 / ZS-004-05 |
+
+**指示圆规格**：
+
+| 属性 | 取值 |
+|------|------|
+| 直径 | `24px` |
+| 圆内字号 | `12px Bold`（D-DIN 或 Noto Sans Bold） |
+| 对勾图标 | `12px`，居中 |
+| 字体水平居中 | 数字 / 对勾 在圆几何中心 |
+
+**标题与描述文字**：
+
+| 元素 | 状态 | 字号 / 颜色 | 来源 |
+|------|------|-------------|------|
+| 标题 | 已完成 / 当前 | `14px Medium`，`#FFFFFF` | — |
+| 标题 | 未开始 | `14px Medium`，`#6E88B0` | ZS-004-04 |
+| 标题 | 失效 | `14px Medium`，`#4A6491` | ZS-004-05 |
+| 描述 | 已完成 / 当前 | `12px Regular`，`#C5CFE0` | ZS-004-02 |
+| 描述 | 未开始 / 失效 | `12px Regular`，`#6E88B0` → `#4A6491` | ZS-004-04 → ZS-004-05 |
+
+**连接线（步骤之间）**：
+
+| 类型 | 色值 | 来源 | 样式 |
+|------|------|------|------|
+| 已完成段（前一节点已完成） | `#1677FF` | ZS-002-06 | `1px dashed`（弹窗）/ `1px solid`（页面） |
+| 未完成段 | `#4A6491` | ZS-004-05 | `1px dashed` |
+
+> 连接线在指示圆**两侧水平居中**（横向）或**正下方垂直**（纵向）；线两端与圆外缘留 `--spacing-1` (4px) 间隙，避免线穿圆。
+
+### 10.2 弹窗步骤条（横向 · 描边圆为主）
+
+用于 Modal / Drawer 内引导多步操作的紧凑步骤条。指示圆**完成态用描边 + 对勾**而非实心，避免在弹窗背景上过于抢眼。
+
+#### 10.2.1 布局
+
+```
+( ✓ ) ┄┄┄┄┄ (●2) ┄┄┄┄┄ ( 3 ) ┄┄┄┄┄ ( 4 ) ┄┄┄┄┄ ( 5 )
+ 标题         标题         标题         标题         标题
+(描述)      (描述)       (描述)       (描述)       (描述)
+```
+
+#### 10.2.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器水平 padding | `--spacing-5` (24px) |
+| 指示圆 → 标题间距 | `--spacing-2` (8px) |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 节点之间水平间距 | 节点间距自适应等分；连接线占用中间空间 |
+| 连接线 | `1px dashed`，已完成段 `#1677FF`，未完成段 `#4A6491` |
+| 文字对齐 | 标题、描述居中对齐于指示圆下方 |
+
+#### 10.2.3 两种变体
+
+| 变体 | 适用 |
+|------|------|
+| **仅标题** | 步骤含义已经清晰（如「填写信息 / 确认 / 完成」），节省垂直空间 |
+| **标题 + 描述** | 步骤名抽象需要一行小字补充时使用 |
+
+### 10.3 页面步骤条（横向 · 实心圆 + 自定义首项标题）
+
+用于页面级流程（如「新建集群」类向导）。和弹窗步骤条相比，**已完成态指示圆改为实心填充 + 白色对勾**，视觉权重更高；首步标题可显示具体名称（如「新建集群」）而非「标题」占位。
+
+#### 10.3.1 布局
+
+```
+(✓) ────── (●2) ┄┄┄┄┄ ( 3 ) ┄┄┄┄┄ ( 4 ) ┄┄┄┄┄ ( 5 )
+新建集群     标题       标题       标题       标题
+(描述文本)  (描述文本) (描述文本) (描述文本) (描述文本)
+```
+
+#### 10.3.2 与 §10.2 弹窗步骤条的差异
+
+| 维度 | 弹窗步骤条 | 页面步骤条 |
+|------|-----------|-----------|
+| 完成态圆形 | 描边圆 + 蓝色对勾 | 实心蓝圆 + 白色对勾 |
+| 完成段连接线样式 | `1px dashed #1677FF` | `1px solid #1677FF` |
+| 标题文字号 | `14px Medium` | `14px Medium`（同） |
+| 第一项 | 通用「标题」占位 | 可显示具体名称（自定义文案） |
+
+#### 10.3.3 完成态指示圆补充
+
+| 角色 | 色值 | 来源 |
+|------|------|------|
+| 已完成圆背景 | `#1677FF` | ZS-002-06 |
+| 已完成圆内对勾 | `#FFFFFF` | — |
+| 已完成圆边框 | 无（实心） | — |
+
+### 10.4 纵向步骤条
+
+用于侧栏 / 详情页内的纵向流程指引。两种变体——「仅标题」与「标题 + 描述」。
+
+#### 10.4.1 布局
+
+```
+仅标题:                       标题 + 描述:
+
+(✓) 新建集群                   (✓) 新建集群
+ ┊                                  描述文本描述
+(●2) 标题                      ┊
+ ┊                             (●2) 标题
+( 3 ) 标题                          描述文本描述
+ ┊                             ┊
+( 4 ) 标题                     ( 3 ) 标题
+                                    描述文本描述
+                               ┊
+                               ( 4 ) 标题
+                                    描述文本描述
+```
+
+#### 10.4.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 指示圆 → 标题水平间距 | `--spacing-2` (8px) |
+| 节点垂直间距（仅标题） | `--spacing-5` (24px)，圆心到圆心 |
+| 节点垂直间距（标题 + 描述） | `--spacing-6` (32px)，圆心到圆心 |
+| 标题 → 描述间距 | `--spacing-1` (4px) |
+| 连接线位置 | 上下两个指示圆**正下方垂直**，居中于圆心 |
+| 连接线样式 | `1px dashed`，已完成段 `#1677FF`，未完成段 `#4A6491` |
+| 文字左对齐 | 标题与描述左对齐，与指示圆右侧对齐基线 |
+
+#### 10.4.3 与横向步骤条共用规则
+
+- 指示圆三态规格沿用 §10.1
+- 已完成态默认用**描边 + 对勾**（与 §10.2 弹窗一致）；若纵向步骤条用于页面级主流程，可切换为 §10.3 的实心圆变体
+
+### 10.5 交互与动画
+
+| 行为 | 动效 |
+|------|------|
+| 步骤切换（next） | 当前圆 `background: transparent → #1677FF`，`200ms ease-out`；同时上一步圆 `border-color: #4A6491 → #1677FF`，再用 `200ms` 切换为对勾图标淡入 |
+| 步骤切换（prev / 回退） | 反向，未完成态恢复 `#4A6491` 边框，圆内数字淡入 |
+| 连接线高亮 | 完成段 `border-color: #4A6491 → #1677FF`，`240ms ease-out` |
+| Hover 节点（可点击） | 圆边框色暂时变 `#4096FF` (ZS-002-05)，标题文字 `#4096FF`，`120ms ease-out`；不可点击节点（未来步骤）无 hover |
+| 点击节点 | 节点必须**已完成**才能点（回看），否则视为禁用；点击合法节点触发 `step:change` 事件 |
+
+### 10.6 状态机与可达性
+
+| 当前步 = N | 节点 i 的状态 |
+|-----------|----------------|
+| `i < N` | Completed（已完成，可点回看） |
+| `i === N` | Current（当前，不可点） |
+| `i > N` | Upcoming（未开始，不可点） |
+| `i.disabled` | Disabled（被显式禁用，例如条件未满足） |
+
+**键盘导航**：
+- `Tab` 顺序在「已完成」节点之间流转，跳过 `Current / Upcoming / Disabled`
+- 焦点节点圆外加 `2px solid #4096FF` 焦点环（`outline`，`offset 2px`）
+
+**屏幕阅读器**：
+- 指示圆 `role="img"`，`aria-label="已完成第 N 步"` / `"当前第 N 步"` / `"未开始第 N 步"`
+- 容器 `role="list"`，节点 `role="listitem"`
+- 当前节点额外 `aria-current="step"`
+
+### 10.7 CSS Token 参考
+
+```css
+:root {
+  /* 步骤条节点 */
+  --step-circle-size: 24px;
+  --step-circle-current-bg: #1677FF;       /* ZS-002-06 */
+  --step-circle-current-text: #FFFFFF;
+  --step-circle-done-border: #1677FF;      /* ZS-002-06 */
+  --step-circle-done-icon: #1677FF;        /* 弹窗变体 */
+  --step-circle-done-bg-page: #1677FF;     /* 页面变体:实心 */
+  --step-circle-done-icon-page: #FFFFFF;
+  --step-circle-upcoming-border: #4A6491;  /* ZS-004-05 */
+  --step-circle-upcoming-text: #6E88B0;    /* ZS-004-04 */
+  --step-circle-disabled-border: #2D4473;  /* ZS-004-06 */
+  --step-circle-disabled-text: #4A6491;    /* ZS-004-05 */
+
+  /* 连接线 */
+  --step-line-done: #1677FF;               /* 已完成段 */
+  --step-line-upcoming: #4A6491;           /* 未完成段:ZS-004-05 */
+
+  /* 文字 */
+  --step-title-active: #FFFFFF;
+  --step-title-inactive: #6E88B0;          /* ZS-004-04 */
+  --step-desc-active: #C5CFE0;             /* ZS-004-02 */
+  --step-desc-inactive: #6E88B0;           /* ZS-004-04 */
+}
+```
+
+### 10.8 三种步骤条的选用决策
+
+| 场景 | 选择 |
+|------|------|
+| Modal / Drawer 内多步表单 | §10.2 弹窗步骤条（描边圆，紧凑） |
+| 页面级向导（独占大区域） | §10.3 页面步骤条（实心圆，视觉重） |
+| 侧栏 / 详情页纵向流程 | §10.4 纵向步骤条 |
+| 步骤数 ≤ 3 且无描述 | 优先「仅标题」变体 |
+| 步骤名抽象需补充说明 | 用「标题 + 描述」变体 |
+| 步骤数 > 7 | 不推荐用步骤条，改用「锚点」（§9.2）或分页 |
+
+---
+
+## 11. 面包屑
+
+> 对应「4.3 导航组件-面包屑」。用于显示当前位置在整个站点层级中的路径，配合「← 返回」按钮支持逐级回溯。颜色取自 ZS-002 主色蓝与 ZS-004 深蓝系。
+
+### 11.1 标准形态
+
+容器顶部带一个独立的容器 / 边框包裹：
+
+```
+🏠 | 概况 / 总概况
+```
+
+带「返回」按钮的层级形态（一级到四级）：
+
+```
+一级:   ← 返回 │ 现在位置
+二级:   ← 返回 │ 上一级位置 / 现在位置
+三级:   ← 返回 │ 上二级位置 / 上一级位置 / 现在位置
+四级:   ← 返回 │ 上三级位置 / 上二级位置 / 上一级位置 / 现在位置
+```
+
+### 11.2 规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器高度 | `40px` |
+| 容器背景 | `#0C1836` (ZS-004-09) |
+| 容器底边 | `1px solid #1A2F5A` (ZS-004-07) |
+| 容器水平 padding | `--spacing-4` (16px) |
+| 字号 | `14px Regular` |
+| 元素间距（图标 / 文字 / 分隔符之间） | `--spacing-2` (8px) |
+| 「返回」与首段路径之间分隔符 `│` | `1px solid #4A6491`，高度 `14px` |
+
+### 11.3 配色
+
+| 角色 | 色值 | 来源 | 备注 |
+|------|------|------|------|
+| Home 图标 🏠 | `#4096FF` | ZS-002-05 | 默认主色，hover → `#1677FF` (ZS-002-06) |
+| 「← 返回」图标 + 文字 | `#4096FF` | ZS-002-05 | 链接样式，hover 显示下划线 |
+| 历史路径文字（可点击） | `#4096FF` | ZS-002-05 | 同链接配色 |
+| 当前位置文字（最后一段） | `#FFFFFF` | — | 加粗 `14px Medium`，不可点击 |
+| 分隔符 `/` | `#4A6491` | ZS-004-05 | 静态、不可点 |
+| 分隔符 `│`（返回按钮与路径之间） | `#4A6491` | ZS-004-05 | 同上 |
+| Hover 路径项 | `#1677FF` | ZS-002-06 | 文字色 + 下划线 |
+| 失效路径项（无对应页） | `#4A6491` | ZS-004-05 | `cursor: not-allowed` |
+
+### 11.4 交互规则
+
+- **点击「← 返回」**：逐步向上返回一级（等同浏览器 back）
+- **点击文字路径**：快速跳回到对应任意上级页面
+- **当前位置**（最后一段）：不响应点击，仅作展示
+- **层级建议**：尽可能不超过 **4 级**；超过 4 级会让面包屑过长，应改用侧栏 / 锚点辅助
+
+### 11.5 与导航的关系
+
+面包屑**不替代**主导航（§8）：
+
+- 主导航 = 「我能去哪些地方」（站点结构）
+- 面包屑 = 「我当前在哪里」（路径回溯）
+
+两者并存时，面包屑紧贴页面主内容区顶部，位于主导航下方、页头（§12）上方。
+
+### 11.6 CSS 参考
+
+```css
+.breadcrumb {
+  display: flex;
+  align-items: center;
+  height: 40px;
+  padding: 0 var(--spacing-4);
+  background: #0C1836;
+  border-bottom: 1px solid #1A2F5A;
+  font-size: 14px;
+  gap: var(--spacing-2);
+}
+.breadcrumb-back     { color: #4096FF; cursor: pointer; }
+.breadcrumb-back:hover { color: #1677FF; text-decoration: underline; }
+.breadcrumb-sep-bar  { width: 1px; height: 14px; background: #4A6491; }
+.breadcrumb-sep      { color: #4A6491; }
+.breadcrumb-link     { color: #4096FF; cursor: pointer; }
+.breadcrumb-link:hover { color: #1677FF; text-decoration: underline; }
+.breadcrumb-current  { color: #FFFFFF; font-weight: 500; }
+```
+
+---
+
+## 12. 页头
+
+> 对应「4.6 导航组件-分页」上半段示意。用于页面主内容区顶部、面包屑下方，承载页面标题与可选的说明 / Tabs。共有 4 种变体。
+
+### 12.1 通用规格
+
+| 属性 | 取值 |
+|------|------|
+| 容器高度 | `56px`（仅标题）/ `64px`（含 Tabs） |
+| 背景 | `#0C1836` (ZS-004-09) |
+| 底边 | `1px solid #1A2F5A` (ZS-004-07) |
+| 水平 padding | `--spacing-5` (24px) |
+| 文字基线 | 垂直居中 |
+
+### 12.2 四种变体
+
+#### 12.2.1 基础页头
+
+只有标题：
+
+```
+页头标题
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+
+#### 12.2.2 页头 + 说明
+
+标题后跟一段灰色说明文字：
+
+```
+页头标题  （这是一句简要说明）
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+| 说明文字 | `14px Regular`，`#6E88B0` | ZS-004-04 |
+| 标题 → 说明间距 | `--spacing-3` (12px) | — |
+
+说明用半角圆括号包裹，颜色与括号一致（不要让括号比文字更醒目）。
+
+#### 12.2.3 页头 + 说明 icon
+
+标题后跟一个可悬停查看说明的图标：
+
+```
+页头标题  ⓘ
+```
+
+| 角色 | 色值 / 字号 | 来源 |
+|------|-------------|------|
+| 标题 | `18px Bold`，`#FFFFFF` | — |
+| 说明 icon `ⓘ` 或 `?` | `16px`，`#6E88B0` | ZS-004-04 |
+| Icon hover | `#4096FF` | ZS-002-05 |
+| 标题 → 图标间距 | `--spacing-2` (8px) | — |
+
+Hover 弹出 Tooltip（沿用 §9.3.3 Tooltip 配色），承载完整说明文字。
+
+#### 12.2.4 分 Tabs 页头
+
+标题位置直接放横向页签（沿用 §9.1.1 横向页签配色），点击切换右侧主内容区：
+
+```
+标题   标题   标题
+─────
+```
+
+| 复用规则 | 说明 |
+|----------|------|
+| Tab 配色 | 完全沿用 §9.1.1 横向页签 |
+| Tab 字号 | `16px Medium`（页头位置比一般 tab 略大） |
+| Tab 间距 | `--spacing-5` (24px) |
+| 激活态下划线 | `2px solid #4096FF`，宽与文字齐 |
+
+### 12.3 与右侧操作区的组合
+
+页头右侧常承载主操作按钮（「+ 新建」、「导出」等）。规则：
+
+- 按钮组靠右对齐，右 padding 与左 padding 一致 (`--spacing-5`)
+- 多按钮排列顺序参照 §5.3.4（默认按钮在左、主按钮在右），按钮间距 `--spacing-2`
+- Tabs 页头中右侧操作区与 Tabs 同高居中
+
+---
+
+## 13. 分页
+
+> 对应「4.6 导航组件-分页」下半段。三种形态——**正常分页 / 精简分页 / 导航式分页**——按页面信息量与可用空间选用。
+
+### 13.1 正常分页
+
+承载大列表，提供页码、跳转、每页条数选择：
+
+```
+共 240 项   < ① 2 3 4 5 … 24 >   每页 [10▾] 条   前往 [   ] 页
+```
+
+#### 13.1.1 元素配色与规格
+
+| 元素 | 字号 / 色值 | 来源 / 说明 |
+|------|-------------|-------------|
+| 「共 N 项」总数文字 | `14px Regular`，`#6E88B0` | ZS-004-04 |
+| 页码按钮（默认） | `14px Regular`，`#C5CFE0`，背景 `transparent` | ZS-004-02 |
+| 页码按钮（hover） | `#4096FF`，背景 `rgba(22,119,255,0.08)` | ZS-002-05 |
+| 页码按钮（激活/当前页） | `#FFFFFF`，背景 `#1677FF`（实心圆） | ZS-002-06 |
+| 页码按钮（失效） | `#4A6491`，背景 `transparent` | ZS-004-05 |
+| 左右翻页箭头 `<` `>` | `14px`，`#6E88B0`，hover → `#4096FF` | ZS-004-04 → ZS-002-05 |
+| 翻页箭头失效（首/末页） | `#4A6491` | ZS-004-05 |
+| 省略号 `…` | `#6E88B0` | ZS-004-04，静态展示，不可点 |
+| 每页条数下拉 `[10▾]` | 沿用 §14.1 输入框规格 | 高度 `28px`，宽 `60px` |
+| 「前往 N 页」输入框 | 沿用 §14.1 输入框规格 | 高度 `28px`，宽 `48px` |
+
+#### 13.1.2 页码按钮规格
+
+| 属性 | 取值 |
+|------|------|
+| 形状 | 圆形 `28px × 28px`（`border-radius: 50%`） |
+| 默认背景 | `transparent` |
+| 当前页背景 | `#1677FF` (ZS-002-06)，实心圆，白色数字 |
+| 字号 | `14px Regular`（数字 D-DIN 或 Noto Sans） |
+| 项间距 | `--spacing-1` (4px) |
+
+#### 13.1.3 元素间距
+
+| 区段 | 间距 |
+|------|------|
+| 「共 N 项」→ 翻页区 | `--spacing-4` (16px) |
+| 翻页区内（箭头 / 页码） | `--spacing-1` (4px) |
+| 翻页区 → 每页下拉 | `--spacing-5` (24px) |
+| 每页下拉 → 前往输入 | `--spacing-4` (16px) |
+
+### 13.2 精简分页
+
+承载弹窗 / 表格紧凑场景，只暴露「当前页 / 总页数」与左右翻页：
+
+```
+共 1 项   < [ 1 ] / 10 >
+```
+
+#### 13.2.1 规格
+
+| 元素 | 配色 / 备注 |
+|------|------------|
+| 「共 N 项」 | 同 §13.1.1 |
+| `<` `>` 翻页箭头 | 同 §13.1.1 |
+| `[ 1 ]` 当前页输入框 | 沿用 §14.1 输入框规格，高 `28px`，宽 `40px`，居中文字 |
+| `/ N` 总页数 | `14px Regular`，`#6E88B0` (ZS-004-04) |
+| 元素间距 | `--spacing-2` (8px) |
+
+#### 13.2.2 与正常分页的差异
+
+| 维度 | 正常分页 | 精简分页 |
+|------|----------|----------|
+| 页码 | 点击式数字列表 | 输入框 + 总页数文字 |
+| 跳转方式 | 点击数字 / 前往输入 | 直接修改输入框 |
+| 每页条数 | 暴露下拉 | 不暴露（默认值由调用方决定） |
+| 适用 | 列表 / 表格主内容区 | 弹窗、抽屉、卡片内嵌列表 |
+
+### 13.3 导航式分页
+
+承载长文 / 详情页的「上一篇 / 下一篇」式翻页，只有方向，不暴露页码：
+
+```
+下一页  »
+«   上一页
+```
+
+#### 13.3.1 规格
+
+| 元素 | 配色 / 备注 |
+|------|------------|
+| 「下一页」/「上一页」文字 + 箭头 | `14px Regular`，`#4096FF` (ZS-002-05) |
+| Hover | `#1677FF` (ZS-002-06) + 下划线 |
+| 失效（首/末篇） | `#4A6491` (ZS-004-05)，`cursor: not-allowed` |
+| 箭头位置 | `下一页 »`（箭头在后）/ `« 上一页`（箭头在前） |
+| 文字 → 箭头间距 | `--spacing-2` (8px) |
+| 两个按钮纵向排列时项间距 | `--spacing-3` (12px) |
+
+### 13.4 三种分页的选用决策
+
+| 场景 | 选择 |
+|------|------|
+| 后台列表 / 表格 | §13.1 正常分页 |
+| Modal / Drawer 内嵌列表 | §13.2 精简分页 |
+| 详情页前后翻 | §13.3 导航式分页 |
+| 列表少于 1 页（项数 ≤ pageSize） | **不显示**分页 |
+| 项数明确但页码可能很多（>50 页） | 用正常分页 + 隐藏中间页码（`...` 省略） |
+
+---
+
+## 14. 输入框（搜索框）
+
+> 对应设计稿「输入框.png」。按使用场景分三类：**基本搜索框 / 后台系统搜索框 / 页面头部搜索框**。配色全部从 ZS-002 主色蓝与 ZS-004 深蓝系取。
+
+### 14.1 公共规格
+
+所有搜索框共用同一套尺寸 / 边框规格：
+
+| 属性 | 默认（正常） | 小号 |
+|------|--------------|------|
+| 高度 | `32px` | `28px` |
+| 水平 padding | `--spacing-3` (12px) | `--spacing-2` (8px) |
+| 圆角 | `2px`（§4.1） | `2px` |
+| 字号 | `14px Regular` | `14px Regular` |
+| 文字色 | `#C5CFE0` (ZS-004-02) | 同 |
+| 占位符色 | `#6E88B0` (ZS-004-04) | 同 |
+| 背景 | `#0C1836` (ZS-004-09) | 同 |
+
+#### 14.1.1 边框状态
+
+| 状态 | 边框 | 来源 |
+|------|------|------|
+| 默认 | `1px solid #1A2F5A` | ZS-004-07 |
+| Hover | `1px solid #4096FF` | ZS-002-05 |
+| Focus | `1px solid #1677FF` + 外发光 `0 0 0 2px rgba(22,119,255,0.16)` | ZS-002-06 |
+| 失效 | `1px solid #2D4473`，背景 `rgba(22,119,255,0.04)` | ZS-004-06 |
+| 错误 | `1px solid #F5222D` + 外发光 `0 0 0 2px rgba(245,34,45,0.16)` | ZS-001-06 |
+
+### 14.2 基本搜索框
+
+#### 14.2.1 基础搜索框
+
+输入框尾部带 🔍 图标，回车或点击图标触发搜索：
+
+```
+[ 搜索                  🔍 ]
+```
+
+| 角色 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 搜索图标 🔍 | `16px`，`#6E88B0` | ZS-004-04 |
+| 图标 hover | `#4096FF` | ZS-002-05 |
+| 图标 → 输入边缘间距 | `--spacing-2` (8px) | — |
+
+#### 14.2.2 分类搜索框（带前缀下拉）
+
+输入框左侧拼一个分类下拉，常用于「按协议搜 IP」等场景：
+
+```
+[ http:// ▾ ] [ 搜索 IP 地址          🔍 ]
+```
+
+| 角色 | 色值 / 规格 | 备注 |
+|------|-------------|------|
+| 前缀下拉宽度 | `auto`，最小 `72px` | 内容自适应 |
+| 前缀下拉与输入框 | 共用同一组边框，**中间无缝**（公用一条 `1px #1A2F5A` 分隔） | 视为一体控件 |
+| 前缀下拉箭头 `▾` | `12px`，`#6E88B0` | hover → `#4096FF` |
+| 整体 focus 行为 | 焦点落到输入框时，**前缀下拉的边框也同步高亮** | — |
+
+### 14.3 后台系统常用搜索框
+
+输入框 + 紧贴右侧的**实心蓝色搜索按钮**，常用于后台主内容区列表筛选：
+
+```
+[ 🔍  搜索任务集名称/负责人        ] [ 搜索 ]
+```
+
+#### 14.3.1 规格
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 左侧搜索图标 🔍 | `16px`，`#6E88B0` | ZS-004-04 |
+| 图标 → 文字间距 | `--spacing-2` (8px) | — |
+| 输入框右边框 | **无**（与按钮无缝拼接） | — |
+| 按钮 | 沿用 §5.2.1 主按钮，圆角 `2px`，文字 `搜索` | — |
+| 按钮高度 | 与输入框一致 `32px` | — |
+| 按钮左侧 | 与输入框紧贴，**无间距** | — |
+
+### 14.4 页面头部搜索框
+
+页头位置的搜索控件，支持四种扩展：**单行 / 高级搜索 / 历史记录 / 输入联想**。
+
+#### 14.4.1 单行（最简）
+
+```
+[ 输入的文字                    ] [ 搜索 ]
+```
+
+规格同 §14.3，仅省略左侧 🔍 图标，让输入文字占满。
+
+#### 14.4.2 含高级搜索切换
+
+右侧叠加一个文字按钮「高级搜索 ▾」，展开后显示模式选项：
+
+```
+[ 输入的文字              ] [ 搜索 ]   高级搜索 ▾
+                                       ○ 模糊匹配   ● 精准匹配
+```
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 「高级搜索 ▾」文字按钮 | `14px Regular`，`#4096FF`，hover `#1677FF` | ZS-002-05 → ZS-002-06 |
+| 「高级搜索」与「搜索」按钮间距 | `--spacing-3` (12px) | — |
+| 单选项「模糊匹配 / 精准匹配」 | 沿用通用 Radio 配色：未选 `1px solid #6E88B0`，已选实心 `#1677FF` | — |
+| 单选项 → 搜索框纵向间距 | `--spacing-2` (8px) | — |
+
+#### 14.4.3 含历史记录
+
+输入框下方显示最近搜索词列表，点击直接用该词搜索：
+
+```
+[ 输入的文字              ] [ 搜索 ]
+
+搜索记录词、搜索记录词、记录词
+```
+
+| 元素 | 色值 / 规格 | 来源 |
+|------|-------------|------|
+| 历史记录文字 | `12px Regular`，`#4096FF` | ZS-002-05 |
+| 项间分隔符（顿号 `、`） | `#4A6491` | ZS-004-05（与文字色不同，弱化分隔） |
+| 历史项 hover | `#1677FF` + 下划线 | ZS-002-06 |
+| 历史区与搜索框纵向间距 | `--spacing-2` (8px) | — |
+
+#### 14.4.4 含输入联想下拉
+
+用户输入时，下方弹出联想词面板：
+
+```
+[ 这是                    ] [ 搜索 ]
+┌─────────────────────────────────┐
+│ 这是搜索输入联想词              │
+│ 这是搜索输入联想词              │
+│ 这是搜索输入联想词              │
+│ 这是联想词                      │
+│ 这是联想词悬浮         ←hovered │
+│ ……                              │
+└─────────────────────────────────┘
+```
+
+##### 面板规格
+
+| 属性 | 取值 |
+|------|------|
+| 背景 | `#122347` (ZS-004-08) |
+| 边框 | `1px solid #1A2F5A` (ZS-004-07) |
+| 阴影 | `0 4px 16px rgba(6, 14, 36, 0.6)`（§3.1.4 三级阴影变体） |
+| 圆角 | `2px`（与输入框一致） |
+| 项高度 | `36px` |
+| 项水平 padding | `--spacing-3` (12px) |
+| 项字号 | `14px Regular`，`#C5CFE0` (ZS-004-02) |
+| 面板宽度 | 与输入框等宽（不含右侧按钮） |
+| 面板与输入框纵向间距 | `--spacing-1` (4px) |
+
+##### 项状态
+
+| 状态 | 背景 | 文字 |
+|------|------|------|
+| 默认 | `transparent` | `#C5CFE0` |
+| Hover（鼠标 / 键盘焦点） | `rgba(22,119,255,0.16)` 或 `#1A2F5A` (ZS-004-07) | `#FFFFFF` |
+| 已点击（点选后回填输入框） | — | — |
+
+##### 键盘导航
+
+- `↑` / `↓` 在联想词之间移动焦点（焦点项视觉等价于 Hover）
+- `Enter` 选中焦点项并回填输入框 + 触发搜索
+- `Esc` 关闭面板，焦点回到输入框
+
+#### 14.4.5 联想下拉 + 历史记录的关系
+
+- **未输入时**：可显示历史记录（§14.4.3 横向展开形态）
+- **开始输入时**：历史记录被联想下拉**取代**，不要并存
+- **清空输入框**：回到历史记录显示
+
+### 14.5 三种搜索框的选用决策
+
+| 场景 | 选择 |
+|------|------|
+| 表单内 / 卡片内的辅助搜索 | §14.2.1 基础搜索框（图标内嵌） |
+| 需要按类型 / 协议过滤的搜索 | §14.2.2 分类搜索框（带前缀下拉） |
+| 后台列表 / 表格顶部筛选 | §14.3 后台搜索框（输入 + 实心按钮） |
+| 页面头部全局搜索 | §14.4 页面头部搜索框（按需开启高级 / 历史 / 联想） |
+
+### 14.6 CSS Token 参考
+
+```css
+:root {
+  --search-bg:            #0C1836;  /* ZS-004-09 */
+  --search-border:        #1A2F5A;  /* ZS-004-07 */
+  --search-border-hover:  #4096FF;  /* ZS-002-05 */
+  --search-border-focus:  #1677FF;  /* ZS-002-06 */
+  --search-border-error:  #F5222D;  /* ZS-001-06 */
+  --search-text:          #C5CFE0;  /* ZS-004-02 */
+  --search-placeholder:   #6E88B0;  /* ZS-004-04 */
+  --search-icon:          #6E88B0;
+  --search-icon-hover:    #4096FF;
+
+  /* 联想下拉 */
+  --suggest-bg:           #122347;  /* ZS-004-08 */
+  --suggest-item-hover:   rgba(22,119,255,0.16);
+  --suggest-item-text:    #C5CFE0;
+  --suggest-item-hover-text: #FFFFFF;
+
+  /* 历史记录 */
+  --history-text:         #4096FF;
+  --history-text-hover:   #1677FF;
+  --history-sep:          #4A6491;
+}
+```

From cf8c17d08b960b5314ea6848302e43cb2bf1ce8f Mon Sep 17 00:00:00 2001
From: fengxiangdebaozi <10845145+fengxiangdebaozi@user.noreply.gitee.com>
Date: Tue, 26 May 2026 09:15:32 +0800
Subject: [PATCH 06/10] =?UTF-8?q?=E6=95=8F=E6=84=9F=E8=AF=8D=E4=BF=AE?=
 =?UTF-8?q?=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/components/workspace/workspace-nav-chat-list.tsx     | 4 ++--
 frontend-web/src/lib/desensitize.ts                          | 5 ++++-
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
index 99f69bf8..24b099af 100644
--- a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
@@ -119,7 +119,7 @@ export function WorkspaceNavChatList({
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
-            <SidebarMenuItem>
+            {/* <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname.startsWith("/page/workspace/roundtable/planning")}
                 asChild
@@ -130,7 +130,7 @@ export function WorkspaceNavChatList({
                   <span>多智能体规划</span>
                 </Link>
               </SidebarMenuButton>
-            </SidebarMenuItem>
+            </SidebarMenuItem> */}
             <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname === "/page/workspace/scheduled/tasks"}
diff --git a/frontend-web/src/lib/desensitize.ts b/frontend-web/src/lib/desensitize.ts
index f1ea860c..963da195 100644
--- a/frontend-web/src/lib/desensitize.ts
+++ b/frontend-web/src/lib/desensitize.ts
@@ -26,7 +26,10 @@ export const DESENSITIZE_MAP: Record<string, string> = {
   模拟: "MN",
   推演: "TY",
   认知: "RZ",
-  触及: "CJ"
+  触及: "CJ",
+  军: "J",
+  美军: "MJ",
+  台军: "TJ",
 };
 
 /**

From 6d02e2c89e972a1952cddcd94f44cb3e77095f27 Mon Sep 17 00:00:00 2001
From: fengxiangdebaozi <10845145+fengxiangdebaozi@user.noreply.gitee.com>
Date: Tue, 26 May 2026 09:50:24 +0800
Subject: [PATCH 07/10] =?UTF-8?q?ai=E5=86=99=E4=BD=9C=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/src/core/config/index.ts         |  2 +-
 .../components/ai-writing/AIWritingForm.tsx   | 39 ++-----------------
 .../src/open-canvas/types/ai-writing.ts       |  2 +-
 3 files changed, 5 insertions(+), 38 deletions(-)

diff --git a/frontend-web/src/core/config/index.ts b/frontend-web/src/core/config/index.ts
index 1eb5cc28..822d9869 100644
--- a/frontend-web/src/core/config/index.ts
+++ b/frontend-web/src/core/config/index.ts
@@ -5,7 +5,7 @@ import { env } from "@/env";
  * 素材的 recUuid 直接拼接在其后即为完整原文链接。
  */
 export const INTRANET_SOURCE_URL_BASE =
-  "https://chlib.b.uat.4.cn/knowlibrary/#/knowledge/mid_detail?recUuid=";
+  "https://chlib.b.uat.4.cn/knowlibrary/#/knowledge/mid-detail?recUuid=";
 
 /** 由 recUuid 构造内网原文详情页地址；recUuid 为空时返回空串。 */
 export function buildIntranetSourceUrl(recUuid?: string | null): string {
diff --git a/frontend-web/src/open-canvas/components/ai-writing/AIWritingForm.tsx b/frontend-web/src/open-canvas/components/ai-writing/AIWritingForm.tsx
index 63ef8472..dafe4a4b 100644
--- a/frontend-web/src/open-canvas/components/ai-writing/AIWritingForm.tsx
+++ b/frontend-web/src/open-canvas/components/ai-writing/AIWritingForm.tsx
@@ -19,7 +19,7 @@ import { useArticleTypes } from '../../hooks/useArticleTypes';
 interface AIWritingFormProps {
   onSubmit: (req: AIWritingRequest) => void;
   disabled?: boolean;
-  /** workspace 入口：隐藏检索关键词数量、严格模式、目标读者 */
+  /** workspace 入口：隐藏严格模式、目标读者 */
   hideAdvancedFields?: boolean;
 }
 
@@ -33,7 +33,7 @@ const INPUT_CLASS =
   'placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 ' +
   'focus-visible:ring-ring disabled:opacity-50';
 
-const DEFAULT_KEYWORD_COUNT = 6;
+const DEFAULT_KEYWORD_COUNT = 1;
 const DEFAULT_AUDIENCE = '普通读者';
 const MAX_INTENT_LENGTH = 500;
 
@@ -50,7 +50,6 @@ export function AIWritingForm({
   const [articleType, setArticleType] = useState('analysis');
   const [audience, setAudience] = useState('普通读者');
   const [wordCountInput, setWordCountInput] = useState('800');
-  const [keywordCountInput, setKeywordCountInput] = useState('1');
   const [strictMode, setStrictMode] = useState(false);
   const [modelName, setModelName] = useState('');
   const [models, setModels] = useState<ModelOption[]>([]);
@@ -110,23 +109,10 @@ export function AIWritingForm({
     }
   }
 
-  // 检索关键词数量限定 1~10，非法值回退默认 6
-  function handleKeywordCountBlur() {
-    const num = parseInt(keywordCountInput, 10);
-    if (isNaN(num)) {
-      setKeywordCountInput('1');
-    } else {
-      setKeywordCountInput(String(Math.max(1, Math.min(10, num))));
-    }
-  }
-
   function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
     if (!intent.trim()) return;
     const wordCount = Math.max(100, parseInt(wordCountInput, 10) || 800);
-    const keywordCount = hideAdvancedFields
-      ? DEFAULT_KEYWORD_COUNT
-      : Math.max(1, Math.min(10, parseInt(keywordCountInput, 10) || DEFAULT_KEYWORD_COUNT));
     onSubmit({
       userIntent: intent.trim(),
       articleType,
@@ -134,7 +120,7 @@ export function AIWritingForm({
         ? DEFAULT_AUDIENCE
         : audience.trim() || DEFAULT_AUDIENCE,
       wordCountTarget: wordCount,
-      keywordCount,
+      keywordCount: DEFAULT_KEYWORD_COUNT,
       writingMode: hideAdvancedFields ? 'loose' : strictMode ? 'strict' : 'loose',
       modelName: modelName || undefined,
     });
@@ -235,25 +221,6 @@ export function AIWritingForm({
 
       {!hideAdvancedFields && (
         <>
-          <div className="space-y-2">
-            <label className="text-sm font-semibold text-foreground">检索关键词数量（1~10）</label>
-            <input
-              type="number"
-              min={1}
-              max={10}
-              step={1}
-              className={INPUT_CLASS}
-              placeholder="6"
-              value={keywordCountInput}
-              onChange={(e) => setKeywordCountInput(e.target.value)}
-              onBlur={handleKeywordCountBlur}
-              disabled={disabled}
-            />
-            <p className="text-xs text-muted-foreground/80">
-              素材收集专家用几个关键词检索，越多素材越全面但耗时更长。
-            </p>
-          </div>
-
           <div className="flex items-start gap-2 rounded-xl border border-[#e8dedd] bg-[#f9f5f5] px-3 py-3">
             <input
               type="checkbox"
diff --git a/frontend-web/src/open-canvas/types/ai-writing.ts b/frontend-web/src/open-canvas/types/ai-writing.ts
index 339676eb..76fac065 100644
--- a/frontend-web/src/open-canvas/types/ai-writing.ts
+++ b/frontend-web/src/open-canvas/types/ai-writing.ts
@@ -158,7 +158,7 @@ export interface AIWritingRequest {
   targetAudience: string;
   wordCountTarget: number;
   modelName?: string;
-  /** 素材检索关键词数量（1~10，默认 6） */
+  /** 素材检索关键词数量（1~10，默认 1） */
   keywordCount: number;
   /** 写作模式：strict=严格依据素材 / loose=可结合通用知识（默认 loose） */
   writingMode: 'strict' | 'loose';

From eeb7f305851d75cd9ce9f4f5df8cbe0a2072ac14 Mon Sep 17 00:00:00 2001
From: fengxiangdebaozi <10845145+fengxiangdebaozi@user.noreply.gitee.com>
Date: Tue, 26 May 2026 11:47:47 +0800
Subject: [PATCH 08/10] =?UTF-8?q?=E4=BB=A3=E7=A0=81=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/docs/multi-agent-backend-dev.md  | 29 +++++----
 frontend-web/docs/multi-agent-frontend-dev.md | 16 ++---
 .../backend/app/gateway/routers/intent.py     | 18 +++---
 .../app/gateway/routers/multi_agent.py        | 61 +++++++++++++------
 .../backend/app/gateway/routers/recommend.py  |  9 ++-
 5 files changed, 81 insertions(+), 52 deletions(-)

diff --git a/frontend-web/docs/multi-agent-backend-dev.md b/frontend-web/docs/multi-agent-backend-dev.md
index c4724d83..e759d19d 100644
--- a/frontend-web/docs/multi-agent-backend-dev.md
+++ b/frontend-web/docs/multi-agent-backend-dev.md
@@ -10,8 +10,8 @@
 
 ## 0. 速读
 
-- 三个圆桌 Router（`intent / recommend / multi_agent`）**全部走 HTTP loopback**：在同进程内通过 `httpx.AsyncClient` 调本机 `127.0.0.1` 的 `/api/threads`、`/api/agents`、`/api/threads/{id}/runs/stream`。
-- **所有 loopback `httpx.AsyncClient` 必须 `trust_env=False`**。开发机若设了 `HTTP_PROXY` / `HTTPS_PROXY`，httpx 默认会把 loopback 也走代理 → 不可达 → 单次请求多出 40 秒超时（典型症状日志：`headers_in=42.160s`）。
+- 三个圆桌 Router（`intent / recommend / multi_agent`）**通过 httpx ASGITransport 进程内直调本机 ASGI app**，复用既有 `/api/threads`、`/api/agents`、`/api/threads/{id}/runs/stream` 路由——**不走 TCP / 不经过网络栈**。所有 client 都由 `multi_agent._make_loopback_client(request)` 工厂统一构造。
+- 历史包袱：早期实现走 `httpx.AsyncClient(trust_env=False)` + `127.0.0.1:<port>`，遇到开发机 `HTTP_PROXY` / `HTTPS_PROXY` 时仍可能把回环走代理（症状 `headers_in=42.160s`）。**改用 ASGITransport 后此问题不再存在**，相关 `trust_env=False` workaround 全部移除。
 - **席位 agent 持久注册**（磁盘 `.deer-flow/agents/` + `_sync_legacy_agents`），**协调智能体每次新建**（命名 `roundtable-coordinator-{timestamp36}`，DB 累积，需后续 GC）。
 - **`.deer-flow/` 整个目录被 git ignore**（仓库根 `.gitignore` 第 64 / 74 行），`git clone` 后内置 agent 目录在部署机上**不会存在**——任何环境都必须把 `roundtable-intent` + `roundtable-recommender` 两个**功能型 agent** 持久化进发布物，否则 `/api/intent/stream` 报 500。**互联网 demo 还需要 6 个示例研讨席位**（`roundtable-intelligence` 等），**内网部署用客户自有 agent 替代**这些席位，无需打包。详见 §11.7。
 - **`init` 是 SSE 而非一次性 JSON**：用 `asyncio.as_completed` 按真实完成顺序推送 `seat_ready`，前端因此能逐个点亮席位。
@@ -59,7 +59,7 @@ Step 3  最终方案展示
 | 2 | 2 | `multi_agent.py` | 协调智能体（每次新建）+ 用户选定的 `roundtable-*` 席位 |
 | 3 | 3 | `artifacts.py`（通用） | 无新 agent |
 
-所有接口需 `Authorization: Bearer <JWT>`。Loopback 调用统一 `trust_env=False`，避免本机 `HTTP_PROXY` 把 `127.0.0.1` 指到不可达代理（症状：`headers_in=40s+`，前端表现为「Step 1 init 卡顿 / Step 2 init 永远不发 seat_ready」）。
+所有接口需 `Authorization: Bearer <JWT>`。Loopback 调用一律由 `_make_loopback_client(request)` 构造（`httpx.ASGITransport(app=request.app)`，base_url 占位 `http://loopback`），**不经 TCP**，因此不再受本机 `HTTP_PROXY` 干扰。
 
 ---
 
@@ -499,7 +499,7 @@ async def _broadcast(client, base, headers, message, agent_threads, skip):
 (None, captured)    — 流结束，captured 是所有 data: 行的字符串列表
 ```
 
-日志 `[upstream-timing] <agent> headers_in=<>` / `first_line=<>`：排查首 token 慢、代理导致 loopback 超时（见 `trust_env=False`）。
+日志 `[upstream-timing] <agent> headers_in=<>` / `first_line=<>`：排查上游首字节延迟；改 ASGITransport 后通常 `headers_in` < 10ms，长尾大概率出在路由 handler 内部（不再是网络/代理问题）。
 
 `_parse_last_messages(captured)` 从倒数往前扫，**跳过 trailing `data: null` end 帧**，找第一条解析为 dict 且含 `messages` key 的 frame；取 `messages` 列表。无可解析帧抛 `502`。
 
@@ -593,14 +593,21 @@ Step 3 **没有** 单独的 `multi_agent` 路由；使用既有 artifacts 能力
 
 ## 9. 关键设计决策
 
-### 9.1 HTTP loopback + `trust_env=False`
+### 9.1 ASGITransport 进程内 loopback（替代旧的 HTTP loopback）
 
-三个 router 均通过 `httpx` 调本机 Gateway（`127.0.0.1`），复用鉴权与 LangGraph 路由，代价是额外 HTTP 开销；init 已用 `asyncio.as_completed` 并行化席位准备。
+三个 router 通过 `httpx.ASGITransport(app=request.app)` 直调本机 ASGI app，**不走 TCP / 不开 socket / 不经网络栈**，但仍然完整复用 FastAPI 路由分发、鉴权 middleware、Pydantic 校验、SSE 流式响应。代价仅是路由层的少量 dispatch 开销（< 1ms），相对 LLM run 本身的数百 ms~数十秒可忽略。
 
-**每个 `httpx.AsyncClient(timeout=None, trust_env=False)` 都是必须的**：
+统一入口：`multi_agent._make_loopback_client(request)`，返回：
 
-- `timeout=None` — SSE 长连接需要
-- `trust_env=False` — 否则 httpx 会读取 `HTTP_PROXY` / `HTTPS_PROXY` 环境变量，把 loopback `127.0.0.1` 也走代理。开发机常配的「校园网代理 / 公司代理」会把回环地址丢弃，导致单次请求 40+ 秒超时（日志典型症状：`headers_in=42.160s`）
+```python
+httpx.AsyncClient(
+    transport=httpx.ASGITransport(app=request.app),
+    base_url="http://loopback",   # 占位 host，ASGITransport 不在意
+    timeout=None,                 # SSE 长连接仍需 None
+)
+```
+
+**已废止的 `trust_env=False` workaround**：旧版本走 `127.0.0.1:<port>` 真实 HTTP，需要 `trust_env=False` 阻止 httpx 读 `HTTP_PROXY` 把回环也走代理（症状日志 `headers_in=42.160s`）。改 ASGITransport 后这个问题在物理上已不存在——根本没走网络栈。
 
 ### 9.2 协调智能体每次新建
 
@@ -1105,7 +1112,7 @@ curl -X POST http://127.0.0.1:8001/api/recommend/stream \
 | Step 1 一直有澄清、无法进入 Step 2 | 未产出 `[INTENT_READY]` 或终态被 `clarification` 覆盖 | 看 SOUL、最后一帧 `status`；确认 intent 先扫 READY（§4.3 顺序） |
 | 选项全是多选 | 旧前端默认 `allow_multiple !== false` | 确认 `allow_multiple` 字段与 `resolve_allow_multiple`（缺省 false） |
 | Step 2 init SSE `error` | 协调 agent 创建失败 / agent_orchestration 缺失 / `_validate_agent_id` 命中 | Network + 后端 `multi_agent` 日志 |
-| Step 2 init 完全卡住 ~40 秒 | `httpx` 走了 `HTTP_PROXY` | 确认 `trust_env=False` 仍在；grep `headers_in=` 看时长 |
+| Step 2 init 完全卡住（历史症状，ASGITransport 改造后已不应再出现） | 旧版 `httpx` 走 `HTTP_PROXY` 拦回环 → 40s 超时 | 自改 ASGITransport 起此现象物理上不可能复现；若仍卡，看后端日志栈、检查路由 handler 是否阻塞 |
 | leader 立即 `status: []` | 未调用 orchestration 技能 / SkillStopMiddleware 没拦到 / SOUL 没声明派活 | 换模型或加强 SOUL；检查 `skill_stop_names` 是否包含 `agent_orchestration` |
 | dispatch 失败但 leader 文本看着正常 | 模型把 `roundtable-x（中文）` 整段塞进 `agent_name` | `_strip_display_suffix` 会兜底；若仍报 400，强化 SOUL 的「严格英文 id」 |
 | 推荐 picks 为空 | 未输出 `[RECOMMEND_READY]` 或 picks 不在候选池 | 看 recommend 终态帧；检查 `candidate_ids` 集合 |
@@ -1122,7 +1129,7 @@ grep "dispatch failed"     .runtime/logs/*.log
 grep "upstream-timing"     .runtime/logs/*.log
 grep "leader-timing"       .runtime/logs/*.log
 grep "special-timing"      .runtime/logs/*.log
-grep "headers_in="         .runtime/logs/*.log   # 走代理症状
+grep "headers_in="         .runtime/logs/*.log   # 上游首字节延迟;ASGITransport 改造后通常 < 10ms
 ```
 
 ---
diff --git a/frontend-web/docs/multi-agent-frontend-dev.md b/frontend-web/docs/multi-agent-frontend-dev.md
index 6b7de99d..fe1c781d 100644
--- a/frontend-web/docs/multi-agent-frontend-dev.md
+++ b/frontend-web/docs/multi-agent-frontend-dev.md
@@ -124,17 +124,17 @@ frontend-web/src/roundtable-planning/
 
 [进入 Step 3]
   HighFidelityReport
-    consensusText ← lastLeaderContent
-    seatDeliveries ← step2RoundtableDialogues.filter(d => d.confidence === "子智能体交付")
-    Object.entries(threadIds).filter(name !== coordinatorName).map → listSessionArtifacts(threadId)
-    文本类文件 → ArtifactPreviewModal；其它 → window.open(downloadUrl)
-```
+      consensusText ← lastLeaderContent
+      seatDeliveries ← step2RoundtableDialogues.filter(d => d.confidence === "子智能体交付")
+      Object.entries(threadIds).filter(name !== coordinatorName).map → listSessionArtifacts(threadId)
+      文本类文件 → ArtifactPreviewModal；其它 → window.open(downloadUrl)
+  ```
 
----
+  ---
 
-## 4. API 层
+  ## 4. API 层
 
-### 4.1 `api/intent.ts` — Step 1
+  ### 4.1 `api/intent.ts` — Step 1
 
 | 函数 | 说明 |
 |------|------|
diff --git a/offline-backend-20260512/backend/app/gateway/routers/intent.py b/offline-backend-20260512/backend/app/gateway/routers/intent.py
index 425b24db..5a83873c 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/intent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/intent.py
@@ -71,6 +71,7 @@ from app.gateway.routers.multi_agent import (
     _find_trailing_ai_text,
     _flatten_content,
     _loopback_base,
+    _make_loopback_client,
     _parse_last_messages,
     _run_payload,
     _stream_upstream,
@@ -108,13 +109,10 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
     """
     base = _loopback_base(request)
     headers = _auth_headers(request)
-    # trust_env=False: this client only talks to the same-process gateway at
-    # 127.0.0.1, so honoring HTTP_PROXY / HTTPS_PROXY env vars (set system-wide
-    # on the dev machine) makes httpx route loopback calls through an upstream
-    # proxy that can't reach 127.0.0.1, costing 40+ seconds of timeout per
-    # request before falling back. Symptom in logs: `headers_in=42.160s`.
+    # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
+    # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
     try:
-        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+        async with _make_loopback_client(request) as client:
             thread_id = await _create_thread(client, base, headers)
     except HTTPException:
         # 上游已用结构化方式失败,原样传给前端不需要二次包装。
@@ -165,11 +163,9 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
     headers = _auth_headers(request)
 
     async def stream_generator() -> AsyncIterator[str]:
-        # trust_env=False: same-process loopback to 127.0.0.1 — honoring
-        # HTTP_PROXY / HTTPS_PROXY env vars (commonly set on dev machines)
-        # causes httpx to route loopback calls through an unreachable upstream
-        # proxy and wait ~40 seconds for timeout before falling back.
-        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
+        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        async with _make_loopback_client(request) as client:
             try:
                 body = _run_payload(
                     agent_name=INTENT_AGENT_ID,
diff --git a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
index ce41e820..27527643 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
@@ -97,13 +97,12 @@ def _diagnose_exception(exc: BaseException, *, context: str = "") -> dict[str, A
 
     if isinstance(root, httpx.ConnectError):
         target = str(root).strip().lower()
-        # loopback 失败 = Gateway 自己没起 / 代理拦回环;outbound 失败 = LLM 提供商不可达。
+        # loopback 已改用 ASGITransport(进程内直调),不再经网络;ConnectError 几乎全部来自上游 LLM。
         if "127.0.0.1" in target or "localhost" in target or "loopback" in target:
             code = "loopback_connect_failed"
             hint = (
-                "本地 Gateway loopback 连接失败:确认后端进程在 8001 端口监听;"
-                "另检查 HTTP_PROXY / HTTPS_PROXY 是否把 127.0.0.1 也走了代理"
-                "(代码已显式 trust_env=False,理论上不该走代理)。"
+                "本地 Gateway ASGI loopback 失败:这种情况罕见,通常意味着 ASGI app "
+                "未正确注入到 request.app,或路由层抛出未捕获异常。请查后端日志栈。"
             )
         else:
             code = "upstream_connect_failed"
@@ -160,12 +159,44 @@ def _diagnose_exception(exc: BaseException, *, context: str = "") -> dict[str, A
 
 # ---------------------------------------------------------------------------
 # Loopback 辅助函数（Gateway → Gateway，同进程）
+#
+# 通过 httpx ASGITransport 直接调用本进程的 ASGI app，**不走 TCP / 不经过网络栈**：
+#   - 彻底规避「开发机 HTTP_PROXY 把 loopback 也走代理」导致的 40s 超时
+#   - 不再需要 trust_env=False / 真实端口 / 真实 host
+#   - 路由分发、鉴权 middleware、Pydantic 校验、SSE 流式响应一切照旧
+#
+# 历史背景：早期实现走 `httpx.AsyncClient(trust_env=False)` + `127.0.0.1:<port>`，
+# 见 git log 与 multi-agent-backend-dev.md §9.1。改用 ASGITransport 后已不需要
+# 防代理 workaround，但 _loopback_base 仍返回一个占位 base_url 以保持原有 helper
+# 函数签名（_create_thread / _stream_upstream 等）零改动。
 # ---------------------------------------------------------------------------
 
 
+# ASGITransport 不在意 host，仅作 URL 拼接占位。
+_LOOPBACK_BASE_URL = "http://loopback"
+
+
 def _loopback_base(request: Request) -> str:
-    """当前请求的 scheme+host，用于 httpx 打回本机 Gateway。"""
-    return f"{request.url.scheme}://{request.url.netloc}"
+    """返回 loopback base URL 占位串。
+
+    ASGI transport 模式下不再用真实 scheme+host，但保留此函数以兼容
+    `_create_thread / _stream_upstream` 等内部 helper 的 `base` 参数。
+    """
+    return _LOOPBACK_BASE_URL
+
+
+def _make_loopback_client(request: Request) -> httpx.AsyncClient:
+    """构造一个走 ASGITransport 的 httpx.AsyncClient，**不走网络栈**。
+
+    所有圆桌路由（intent / recommend / multi_agent）的 loopback 调用都走这里，
+    替代原先的 `httpx.AsyncClient(timeout=None, trust_env=False)` + 127.0.0.1。
+    """
+    transport = httpx.ASGITransport(app=request.app)
+    return httpx.AsyncClient(
+        transport=transport,
+        base_url=_LOOPBACK_BASE_URL,
+        timeout=None,
+    )
 
 
 def _auth_headers(request: Request) -> dict[str, str]:
@@ -431,11 +462,9 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
         return f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"
 
     async def stream_generator() -> AsyncIterator[str]:
-        # trust_env=False: same-process loopback to 127.0.0.1 — honoring
-        # HTTP_PROXY / HTTPS_PROXY env vars (commonly set on dev machines)
-        # causes httpx to route loopback calls through an unreachable upstream
-        # proxy and wait ~40 seconds for timeout before falling back.
-        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
+        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        async with _make_loopback_client(request) as client:
             try:
                 # Per-seat prepare task — same body as before, but we no longer
                 # await them with asyncio.gather. Instead, asyncio.as_completed
@@ -552,7 +581,7 @@ async def _stream_upstream(
     - ``(None, captured)`` — 流结束，``captured`` 为所有 ``data:`` 行文本列表，
       供 ``_parse_last_messages`` 从倒数 values 快照提取 ``messages``。
 
-    日志 ``[upstream-timing]``：排查首 token 慢、代理导致 loopback 超时（见 trust_env=False）。
+    日志 ``[upstream-timing]``：排查首 token 慢；loopback 已走 ASGITransport，不会再有代理超时。
     """
 
     url = f"{base}/api/threads/{thread_id}/runs/stream"
@@ -968,11 +997,9 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
     headers = _auth_headers(request)
 
     async def stream_generator() -> AsyncIterator[str]:
-        # trust_env=False: same-process loopback to 127.0.0.1 — honoring
-        # HTTP_PROXY / HTTPS_PROXY env vars (commonly set on dev machines)
-        # causes httpx to route loopback calls through an unreachable upstream
-        # proxy and wait ~40 seconds for timeout before falling back.
-        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
+        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        async with _make_loopback_client(request) as client:
             try:
                 if agent_type == "leader":
                     gen = _leader_run(
diff --git a/offline-backend-20260512/backend/app/gateway/routers/recommend.py b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
index 5035cb4c..45b0cb81 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/recommend.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
@@ -52,6 +52,7 @@ from app.gateway.routers.multi_agent import (
     _create_thread,
     _flatten_content,
     _loopback_base,
+    _make_loopback_client,
     _parse_last_messages,
     _run_payload,
     _stream_upstream,
@@ -193,11 +194,9 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
     headers = _auth_headers(request)
 
     async def stream_generator() -> AsyncIterator[str]:
-        # trust_env=False: same-process loopback to 127.0.0.1 — honoring
-        # HTTP_PROXY / HTTPS_PROXY env vars (commonly set on dev machines)
-        # causes httpx to route loopback calls through an unreachable upstream
-        # proxy and wait ~40 seconds for timeout before falling back.
-        async with httpx.AsyncClient(timeout=None, trust_env=False) as client:
+        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
+        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        async with _make_loopback_client(request) as client:
             try:
                 # 每次推荐独立 thread；prompt 已包含完整 intent + 候选列表，无需多轮。
                 thread_id = await _create_thread(client, base, headers)

From d1e6cd5a8f530373c1fc021376b94ee194177775 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Tue, 26 May 2026 13:01:01 +0800
Subject: [PATCH 09/10] =?UTF-8?q?=E5=A4=9A=E6=99=BA=E8=83=BD=E4=BD=93?=
 =?UTF-8?q?=E5=8D=8F=E4=BD=9C=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../app/gateway/routers/_roundtable_seed.py   | 411 ++++++++++++++++++
 .../backend/app/gateway/routers/intent.py     |   8 +
 .../backend/app/gateway/routers/recommend.py  |   5 +
 3 files changed, 424 insertions(+)
 create mode 100644 offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py

diff --git a/offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py b/offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py
new file mode 100644
index 00000000..791206e5
--- /dev/null
+++ b/offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py
@@ -0,0 +1,411 @@
+"""圆桌功能型 agent 的「调用前自检 + 缺失自动补建」工具。
+
+适用场景
+--------
+``roundtable-intent`` / ``roundtable-recommender`` 是圆桌 Step 1 + 推荐链路的
+**功能型** 内置 agent,任何部署都必须存在。但仓库根 ``.gitignore`` 把整个
+``.deer-flow/`` 目录排除,新机器 ``git clone`` 之后这两个目录**不会存在**,
+直接调 ``/api/intent/stream`` 会因为 agent 解析失败抛 500。
+
+本模块在三个路由入口(``intent.init``、``intent.stream``、``recommend.stream``)
+被调用,检查磁盘文件是否齐全;缺失则用下方嵌入的标准模板写回去。
+``_sync_legacy_agents`` 会在下一次 ``GET /api/agents`` 时把目录 upsert 进 DB,
+所以这里只关心磁盘文件,不直接动 DB。
+
+为什么嵌入字符串而不是用 importlib.resources 资源文件
+------------------------------------------------------
+SOUL 体量不大(两个加起来 ~200 行),嵌入到 Python 文件里是**单一可信源**——改
+SOUL 走代码 review、commit 走 git 历史,且不会因为 wheel 打包漏配
+``package-data`` 导致部署机拿不到。
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Iterable
+
+import yaml
+
+from deerflow.config.paths import get_paths
+
+logger = logging.getLogger(__name__)
+
+
+INTENT_AGENT_ID = "roundtable-intent"
+INTENT_AGENT_NAME = "任务理解"
+INTENT_AGENT_DESCRIPTION = (
+    "任务理解智能体,通过 2-5 轮简短追问把用户模糊需求转化成结构化的"
+    "「任务目标+约束+关键假设」,为多智能体圆桌研讨准备输入"
+)
+
+# 与 .deer-flow/agents/roundtable-intent/SOUL.md 保持完全一致;
+# 改动请同步两处或以本文件为准 + 删除磁盘旧目录让下一次请求重建。
+INTENT_AGENT_SOUL = """# 任务理解智能体
+
+你是多智能体圆桌研讨 **Step 1** 的「任务理解专员」。本提示词定义了 Step 1 的完整流程与边界;若管理员为你配置了 Skill,可结合 Skill 补充领域话术或检查清单,但**不得偏离**下文的工作流、`ask_clarification` 用法与 `[INTENT_READY]` 结束协议。
+
+---
+
+## 1. 你的目标
+
+通过 **2–5 轮**简短对话,把用户模糊的需求整理成结构化输入,供 Step 2 圆桌使用:
+
+| 字段 | 含义 |
+|------|------|
+| `objective` | 一句话任务目标 |
+| `constraints` | 硬约束列表(预算/时间/合规/范围等,至少 1 条) |
+| `assumptions` | 你替用户做的合理假设(可空数组) |
+
+**优先级**:目标 > 硬约束 > 软偏好。已经清楚的信息不要再问。
+
+---
+
+## 2. 工作流(必须遵守)
+
+```
+用户描述任务
+    ↓
+信息够不够?
+    ├─ 不够 / 有歧义 → 调用 ask_clarification(可带 options 卡片)
+    ↓
+用户回复(可能是「我选择:…」或自由文本)
+    ↓
+重复 2–5 轮
+    ↓
+信息充分 → 自然语言汇总 + [INTENT_READY] + JSON
+    ↓
+停止追问(本轮及之后都不要再 ask_clarification)
+```
+
+**关键规则**:
+- 澄清阶段 **只** 用 `ask_clarification` 提问;不要用纯文本空问「还有什么补充吗」。
+- 一旦输出 `[INTENT_READY]`,**同一轮对话立即结束**,不要再追加追问或工具调用。
+- **不做方案、不给技术建议、不写文件、不联网、不派活**——那是 Step 2 六个席位的事。
+
+---
+
+## 3. 唯一工具:`ask_clarification`
+
+当缺少信息、存在歧义、需要用户拍板时,**必须**调用此工具(不要只在正文里提问)。
+
+### 3.1 参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `question` | ✅ | 一个聚焦的问题,一次只问一个决策点 |
+| `clarification_type` | ✅ | 见下表 |
+| `context` | 推荐 | 为什么需要用户确认(1 句话) |
+| `options` | 有离散选项时必填 | 字符串列表,如 `["≤500万", "500–1000万", "暂不确定"]` |
+| `allow_multiple` | 可选 | 默认 **不传 / False = 单选**;仅当用户**确实可同时选多项**时传 `True` |
+
+### 3.2 `clarification_type` 怎么选
+
+| 类型 | 何时使用 | 选项 UI |
+|------|----------|---------|
+| `missing_info` | 缺预算、时间、范围等关键事实 | 默认单选;多项约束可同时成立时 `allow_multiple=True` |
+| `ambiguous_requirement` | 同一句话多种理解 | 默认单选 |
+| `approach_choice` | 在若干方案/路径中选一个 | **单选**(点击即发送) |
+| `risk_confirmation` | 需要用户明确确认风险 | **单选** |
+| `suggestion` | 你有建议,需用户批准 | **单选** |
+
+### 3.3 选项卡片(前端行为)
+
+- 你提供 `options` 后,前端会渲染**可点击卡片**。
+- **默认单选**:用户点一项即发送,无需再点「发送」。
+- **多选**(仅 `allow_multiple=True`):用户可多选后点「发送回答」。
+- 用户也可能在自定义输入框里打字;回复常见格式:`我选择:A、B;补充:…`——请据此更新理解并继续流程。
+
+### 3.4 调用示例
+
+**缺信息 + 单选预算档:**
+```
+ask_clarification(
+  question="这次任务的预算大致在哪个区间?",
+  clarification_type="missing_info",
+  context="预算会影响后续圆桌的可行方案范围",
+  options=["≤ 300 万", "300–800 万", "≥ 800 万", "暂不确定"]
+)
+```
+
+**选部署方式(单选):**
+```
+ask_clarification(
+  question="优先采用哪种部署方式?",
+  clarification_type="approach_choice",
+  context="不同部署方式对工期和合规要求差异很大",
+  options=["仅内网私有化", "混合云", "全公有云"]
+)
+```
+
+**多项硬约束可同时满足(多选):**
+```
+ask_clarification(
+  question="以下哪些约束必须同时满足?(可多选)",
+  clarification_type="missing_info",
+  context="我需要确认哪些是硬性底线",
+  options=["预算上限", "72 小时内交付", "等保三级", "零停机"],
+  allow_multiple=True
+)
+```
+
+### 3.5 同轮多个独立问题
+
+若 **多个互不依赖** 的信息都缺失,可在 **同一轮** 多次调用 `ask_clarification`(每个问题一次调用,各自带 `options`)。
+若后一个问题依赖前一个答案,**只问第一个**,等用户回复后再问下一个。
+
+---
+
+## 4. 信息充分性判定
+
+满足 **全部** 条件即可结束澄清:
+
+1. 能写出一句明确的 `objective`(用户希望实现 X)
+2. `constraints` 至少 1 条硬约束(预算 / 时间 / 合规 / 范围 之一)
+3. 没有会妨碍 Step 2 研讨的明显歧义
+
+若用户**首条消息**已包含目标 + 约束,**直接汇总**,不要多余追问。
+
+---
+
+## 5. 结束协议:`[INTENT_READY]`
+
+信息充分时,回复结构必须是:
+
+1. **自然语言**向用户复述「我理解的任务是 …」(📋 汇总,让用户 review)
+2. **紧接着**输出下方固定标记 + JSON(后端靠此解锁「进入 Step 2」)
+
+格式要求(**严格**):
+
+```
+[INTENT_READY]
+```json
+{
+  "objective": "用一句话写出用户最终要做的事",
+  "constraints": ["预算 ≤ XXX 万", "时间 ≤ XXX 天", ...],
+  "assumptions": ["假设 1", "假设 2"]
+}
+```
+```
+
+- `[INTENT_READY]` **单独成行**,前后不要夹其他字符
+- 标记后**紧跟** ```json 代码块
+- 字段名必须是 `objective` / `constraints` / `assumptions`
+- `constraints` 至少 1 条;`assumptions` 可为 `[]`
+
+**输出 `[INTENT_READY]` 后禁止再调用 `ask_clarification` 或继续追问。**
+
+---
+
+## 6. 输出风格
+
+- 普通澄清轮:不超过 **3 句话**(工具调用前的引导语可更短)
+- 提问要**具体**(❓),汇总要**结构化**(✅ 📋)
+- 适度 emoji:❓ 提问、✅ 已明确、📋 汇总
+
+---
+
+## 7. 禁止事项
+
+- ❌ `agent_orchestration`、读写文件、bash、联网搜索、memory 等——你无权使用
+- ❌ 输出具体实施方案、架构图、代码
+- ❌ 在已输出 `[INTENT_READY]` 之后继续提问
+- ❌ 用「还有什么要补充的吗」代替 `ask_clarification`
+
+---
+
+## 8. 完整对话示例
+
+**用户**:帮我规划一个生产系统安全改造
+
+**你**(调用工具):
+```
+ask_clarification(
+  question="预算大致在哪个区间?工期有没有硬性上限?",
+  clarification_type="missing_info",
+  context="这两项是后续圆桌排期的基础",
+  options=["预算 ≤300万 / 6个月内", "预算 300–800万 / 6–12个月", "预算 ≥800万 / 时间较灵活", "暂不确定,需先评估"]
+)
+```
+
+**用户**:我选择:预算 300–800万 / 6–12个月
+
+**你**(若还需确认合规):
+```
+ask_clarification(
+  question="是否需要满足特定合规标准?",
+  clarification_type="missing_info",
+  options=["等保 2.0", "等保 3.0", "行业监管无特殊要求", "暂不确定"]
+)
+```
+
+**用户**:我选择:等保 2.0
+
+**你**(汇总,不再调用工具):
+✅ 我理解的任务是:在 300–800 万预算、6–12 个月工期内,对生产系统做安全改造并满足等保 2.0。
+
+📋
+
+[INTENT_READY]
+```json
+{
+  "objective": "对生产系统进行安全改造,满足等保 2.0 合规要求",
+  "constraints": ["预算 300–800 万元", "工期 6–12 个月", "必须满足等保 2.0"],
+  "assumptions": ["允许在预定窗口内安排必要停机", "现有系统具备基础数字化能力"]
+}
+```
+"""
+
+
+RECOMMENDER_AGENT_ID = "roundtable-recommender"
+RECOMMENDER_AGENT_NAME = "智能体推荐"
+RECOMMENDER_AGENT_DESCRIPTION = (
+    "智能体推荐专员,基于用户的任务目标与约束,从候选智能体池中挑选最相关的 "
+    "2-6 个智能体并给出推荐理由,为多智能体圆桌研讨准备最终参会名单"
+)
+
+RECOMMENDER_AGENT_SOUL = """# 智能体推荐专员
+
+## 角色定位
+你是多智能体圆桌研讨的"智能体推荐专员"。任务理解专员已经把用户需求整理成「任务目标 + 约束 + 关键假设」交给你,你的工作是从一个**候选智能体池**里,挑出**最适合**参加这次圆桌研讨的 2-6 个智能体,并为每一位写一句推荐理由。
+
+## 核心职责
+- 仔细阅读用户的任务目标与约束
+- 浏览候选池中每个智能体的 `name` 与 `description`
+- 选出与本次任务**最相关**的 2-6 个智能体(数量动态,不必凑齐 6 个)
+- 为每个推荐的智能体写一句**具体、可验证**的推荐理由——必须能回答"它能为这次任务做什么"
+- 不推荐重复职能的智能体(如果两个智能体能力高度重叠,只选一个)
+- 不推荐与任务明显无关的智能体(宁缺毋滥)
+
+## 数量约束
+- **下限**:至少推荐 2 个(单个智能体谈不上"圆桌")
+- **上限**:最多推荐 6 个(超过 6 个会让协调智能体派活混乱、上下文膨胀)
+- 候选池不足 2 个时,有几个推几个
+
+## 输出协议
+**你必须严格按下述格式输出**(后端用正则识别):
+
+1. 先用自然语言简短说明你的推荐思路(1-3 句话,让用户能 review)
+2. 然后输出标记 `[RECOMMEND_READY]` 单独成行
+3. 紧接一个 ```json 代码块,内容为:
+
+```json
+{
+  "picks": [
+    {"agent_id": "<候选池中的智能体 id>", "reason": "<一句推荐理由>"},
+    ...
+  ]
+}
+```
+
+格式注意:
+- `[RECOMMEND_READY]` 标记必须**单独成行**,前后无其他字符
+- 标记紧接着一个 ```json 代码块
+- `picks` 数组长度严格在 [2, 6] 之间(候选池不足时按实际数量,但不要少于 2 除非候选池本身就 < 2)
+- `agent_id` 必须**严格**来自候选池(不要造词)
+- `reason` 必须**具体**,不要"很合适"、"很强"这类空话
+
+## 输出风格
+- 思路部分简短:用一句话概括你为什么挑这些(例如"按情报→设计→风险→执行的研讨节奏挑选了 4 位")
+- 推荐理由要**具体到任务**,例如"负责检索同类合规改造案例,直接对应本次等保 2.0 的对标需求"
+- 适度用 emoji:📋 表示开始汇总
+
+## 边界
+- 不调用任何工具(不联网、不执行命令、不读写文件)
+- 不评价候选智能体的优劣(只判断"是否适合本次任务")
+- 不发起对话、不反问用户——你只产出推荐结果
+- 候选池里没有的智能体绝不出现在 `picks` 中
+
+## 示例
+
+**用户输入**(由后端拼装):
+```
+任务目标:对生产系统进行安全改造,满足等保 2.0 合规要求
+约束:预算 ≤ 500 万元;工期 ≤ 6 个月;必须满足等保 2.0
+关键假设:现有系统具备基础数字化能力;允许预定窗口停机
+
+候选智能体池:
+- roundtable-intelligence (情报收集):检索同类历史案例、行业最佳实践与外部情报
+- roundtable-environment (环境评估):评估硬件容量与系统量化承载力
+- roundtable-solution-design (方案设计):产出主备方案与关键路径
+- roundtable-risk-review (风险审查):合规红线检查与收敛建议
+- roundtable-execution-plan (执行规划):里程碑与资源排布
+- roundtable-summary (总结陈述):归纳冲突标记与盖印
+- my-cost-calc (成本测算):基于预算和资源单价计算总成本
+```
+
+**你的输出**:
+按"情报→设计→风险→执行"的研讨节奏,挑选 5 位最贴合本次等保 2.0 改造任务的智能体,并加入成本测算覆盖预算硬约束。📋
+
+[RECOMMEND_READY]
+```json
+{
+  "picks": [
+    {"agent_id": "roundtable-intelligence", "reason": "检索同类等保 2.0 改造案例与监管口径,直接支撑本次合规对标"},
+    {"agent_id": "roundtable-solution-design", "reason": "在 6 个月工期约束下产出主备改造方案与关键路径"},
+    {"agent_id": "roundtable-risk-review", "reason": "对照等保 2.0 合规红线审查方案,避免后期返工"},
+    {"agent_id": "roundtable-execution-plan", "reason": "把改造拆成可在 6 个月内交付的里程碑与资源排布"},
+    {"agent_id": "my-cost-calc", "reason": "校验整体方案落在 500 万元预算硬约束内"}
+  ]
+}
+```
+"""
+
+
+_BUILTIN_FUNCTIONAL_AGENTS: tuple[tuple[str, str, str, str], ...] = (
+    (INTENT_AGENT_ID, INTENT_AGENT_NAME, INTENT_AGENT_DESCRIPTION, INTENT_AGENT_SOUL),
+    (RECOMMENDER_AGENT_ID, RECOMMENDER_AGENT_NAME, RECOMMENDER_AGENT_DESCRIPTION, RECOMMENDER_AGENT_SOUL),
+)
+
+
+def _ensure_one(agent_id: str, name: str, description: str, soul: str) -> bool:
+    """Create the on-disk files for one functional agent if missing.
+
+    Returns True if files were just created, False if the directory already
+    existed (and we didn't touch it — respect any local edits).
+    """
+    agent_dir = get_paths().agent_dir(agent_id)
+    if agent_dir.exists():
+        return False
+
+    agent_dir.mkdir(parents=True, exist_ok=True)
+
+    # newline="\n" 强制 LF;否则 Windows 下 open() 把 \n 翻成 \r\n,跨 OS 部署时与
+    # Linux 部署机字节级不一致(功能上 YAML/Markdown 都兼容,但 git diff / 哈希对不齐)。
+    config_yaml = yaml.dump(
+        {"id": agent_id, "name": name, "description": description},
+        default_flow_style=False,
+        allow_unicode=True,
+    )
+    (agent_dir / "config.yaml").write_bytes(config_yaml.encode("utf-8"))
+    (agent_dir / "SOUL.md").write_bytes(soul.encode("utf-8"))
+    return True
+
+
+def ensure_roundtable_functional_agents() -> list[str]:
+    """Seed `roundtable-intent` + `roundtable-recommender` if their directories
+    are missing. Idempotent — fast no-op when both exist.
+
+    Called from the entry of intent/init, intent/stream, and recommend/stream
+    so the routes self-heal on fresh internal deployments where `.deer-flow/`
+    is gitignored and the agent directories were never shipped.
+
+    Returns the list of agent ids that were just created (empty when nothing
+    needed seeding). Errors are logged but never raised — a partial failure
+    must not block the request; the downstream route will surface its own
+    actionable error if the agent really cannot be resolved.
+    """
+    created: list[str] = []
+    for agent_id, name, description, soul in _BUILTIN_FUNCTIONAL_AGENTS:
+        try:
+            if _ensure_one(agent_id, name, description, soul):
+                created.append(agent_id)
+        except Exception:
+            logger.exception("Failed to seed roundtable functional agent '%s'", agent_id)
+    if created:
+        logger.info("Seeded missing roundtable functional agents: %s", ", ".join(created))
+    return created
+
+
+def required_agent_ids() -> Iterable[str]:
+    """Stable ids of agents this seeder owns — exposed for tests/diagnostics."""
+    return tuple(a[0] for a in _BUILTIN_FUNCTIONAL_AGENTS)
diff --git a/offline-backend-20260512/backend/app/gateway/routers/intent.py b/offline-backend-20260512/backend/app/gateway/routers/intent.py
index 5a83873c..050d560b 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/intent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/intent.py
@@ -63,6 +63,7 @@ from fastapi.responses import StreamingResponse
 
 # Reuse the building blocks already in multi_agent.py — keeps both routers
 # identical in connection handling, payload shape, and error mapping.
+from app.gateway.routers._roundtable_seed import ensure_roundtable_functional_agents
 from app.gateway.routers.multi_agent import (
     _auth_headers,
     _create_thread,
@@ -107,6 +108,10 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
     与 ``POST /api/multi-agent/init`` 的区别：不创建协调智能体、不建多席位
     thread 映射；agent 本身已通过磁盘 ``.deer-flow/agents/`` 同步注册。
     """
+    # 调用前自检:内网部署 .deer-flow/ 被 gitignore,首次启动时本 agent 目录可能不存在,
+    # 缺失则就地用嵌入模板补建,避免下一步 /stream 报 500。
+    ensure_roundtable_functional_agents()
+
     base = _loopback_base(request)
     headers = _auth_headers(request)
     # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
@@ -159,6 +164,9 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
     if not message:
         raise HTTPException(status_code=400, detail="message is required")
 
+    # 调用前自检:防御性二次检查——若管理员在 init 之后手动删了目录,这里也能自愈。
+    ensure_roundtable_functional_agents()
+
     base = _loopback_base(request)
     headers = _auth_headers(request)
 
diff --git a/offline-backend-20260512/backend/app/gateway/routers/recommend.py b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
index 45b0cb81..14945c8a 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/recommend.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
@@ -47,6 +47,7 @@ import httpx
 from fastapi import APIRouter, Body, HTTPException, Request
 from fastapi.responses import StreamingResponse
 
+from app.gateway.routers._roundtable_seed import ensure_roundtable_functional_agents
 from app.gateway.routers.multi_agent import (
     _auth_headers,
     _create_thread,
@@ -189,6 +190,10 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
     if not candidate_ids:
         raise HTTPException(status_code=400, detail="candidates must contain at least one valid agent_id")
 
+    # 调用前自检:内网部署 .deer-flow/ 被 gitignore,roundtable-recommender 目录可能不存在,
+    # 缺失则用嵌入模板补建,避免下游 lead_agent 解析失败抛 500。
+    ensure_roundtable_functional_agents()
+
     prompt = _build_prompt(intent, candidates)
     base = _loopback_base(request)
     headers = _auth_headers(request)

From daba5c05992505458bf35570aad08cbdbca694d1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=91=A3=E5=AE=8F=E5=87=AF?= <hkdong@kland.com.cn>
Date: Tue, 26 May 2026 14:18:00 +0800
Subject: [PATCH 10/10] =?UTF-8?q?=E4=BB=A3=E7=A0=81=E4=BF=AE=E6=94=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../workspace/workspace-nav-chat-list.tsx     |   4 +-
 .../backend/app/gateway/routers/intent.py     |   5 +-
 .../app/gateway/routers/multi_agent.py        | 137 ++++++++++++++----
 .../backend/app/gateway/routers/recommend.py  |   5 +-
 offline-backend-20260512/backend/config.yaml  |   7 +
 .../harness/deerflow/config/__init__.py       |   2 +
 .../harness/deerflow/config/app_config.py     |   2 +
 .../harness/deerflow/config/gateway_config.py |  46 ++++++
 8 files changed, 174 insertions(+), 34 deletions(-)
 create mode 100644 offline-backend-20260512/backend/packages/harness/deerflow/config/gateway_config.py

diff --git a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
index 24b099af..99f69bf8 100644
--- a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
@@ -119,7 +119,7 @@ export function WorkspaceNavChatList({
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
-            {/* <SidebarMenuItem>
+            <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname.startsWith("/page/workspace/roundtable/planning")}
                 asChild
@@ -130,7 +130,7 @@ export function WorkspaceNavChatList({
                   <span>多智能体规划</span>
                 </Link>
               </SidebarMenuButton>
-            </SidebarMenuItem> */}
+            </SidebarMenuItem>
             <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname === "/page/workspace/scheduled/tasks"}
diff --git a/offline-backend-20260512/backend/app/gateway/routers/intent.py b/offline-backend-20260512/backend/app/gateway/routers/intent.py
index 050d560b..7990aed8 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/intent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/intent.py
@@ -114,8 +114,9 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
 
     base = _loopback_base(request)
     headers = _auth_headers(request)
-    # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
-    # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+    # TCP loopback 到 127.0.0.1:<gateway port>(详见 multi_agent._make_loopback_client)。
+    # 不要在这里替换成 httpx.ASGITransport——曾试过,会整段 buffer SSE 流导致前端
+    # 看不到逐 token 增量。
     try:
         async with _make_loopback_client(request) as client:
             thread_id = await _create_thread(client, base, headers)
diff --git a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
index 27527643..d7d3e8ae 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/multi_agent.py
@@ -49,12 +49,14 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import os
 import re
 import time
 import traceback
 from typing import Any, AsyncIterator
 
 import httpx
+from deerflow.config import get_app_config
 from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple
 from fastapi import APIRouter, Body, HTTPException, Request
 from fastapi.responses import StreamingResponse
@@ -97,12 +99,15 @@ def _diagnose_exception(exc: BaseException, *, context: str = "") -> dict[str, A
 
     if isinstance(root, httpx.ConnectError):
         target = str(root).strip().lower()
-        # loopback 已改用 ASGITransport(进程内直调),不再经网络;ConnectError 几乎全部来自上游 LLM。
+        # loopback 走真 TCP 到 127.0.0.1:<gateway port>;失败 = Gateway 进程没起 / 端口被占。
+        # outbound 失败(其它 host)= LLM 提供商不可达。
         if "127.0.0.1" in target or "localhost" in target or "loopback" in target:
             code = "loopback_connect_failed"
             hint = (
-                "本地 Gateway ASGI loopback 失败:这种情况罕见,通常意味着 ASGI app "
-                "未正确注入到 request.app,或路由层抛出未捕获异常。请查后端日志栈。"
+                "本地 Gateway loopback 连接失败:确认后端进程正在监听配置的端口。"
+                "端口配置优先级(高→低):env DEER_FLOW_GATEWAY_PORT > config.yaml 的 "
+                "gateway.port > 默认 8001。若部署机改了端口,在 config.yaml 加 "
+                "`gateway:\\n  port: <端口>` 即可。"
             )
         else:
             code = "upstream_connect_failed"
@@ -160,42 +165,116 @@ def _diagnose_exception(exc: BaseException, *, context: str = "") -> dict[str, A
 # ---------------------------------------------------------------------------
 # Loopback 辅助函数（Gateway → Gateway，同进程）
 #
-# 通过 httpx ASGITransport 直接调用本进程的 ASGI app，**不走 TCP / 不经过网络栈**：
-#   - 彻底规避「开发机 HTTP_PROXY 把 loopback 也走代理」导致的 40s 超时
-#   - 不再需要 trust_env=False / 真实端口 / 真实 host
-#   - 路由分发、鉴权 middleware、Pydantic 校验、SSE 流式响应一切照旧
+# 圆桌三路由（intent / recommend / multi_agent）需要从一个 FastAPI handler 里
+# 调用本机 Gateway 的另一个 endpoint（`/api/threads`、`/api/agents`、
+# `/api/threads/{id}/runs/stream`）。这里用真 TCP loopback 到本机的 127.0.0.1
+# + Gateway 监听端口。
 #
-# 历史背景：早期实现走 `httpx.AsyncClient(trust_env=False)` + `127.0.0.1:<port>`，
-# 见 git log 与 multi-agent-backend-dev.md §9.1。改用 ASGITransport 后已不需要
-# 防代理 workaround，但 _loopback_base 仍返回一个占位 base_url 以保持原有 helper
-# 函数签名（_create_thread / _stream_upstream 等）零改动。
+# ⚠️ 历史踩坑(三个) ⚠️
+# 1. 直接走系统代理:开发机若设了 HTTP_PROXY / HTTPS_PROXY,httpx 默认会把
+#    127.0.0.1 也走代理 → 上游代理不可达,40s 超时(典型日志 headers_in=42.160s)。
+#    → 修法:client 用 `trust_env=False`,强制忽略代理 env vars。
+#
+# 2. 用 request.url.netloc 拼 base URL:Nginx 反代部署时,客户端打到 nginx 的
+#    public host(如 example.com),nginx 把请求转给 gateway 时 Host header
+#    通常是 `gateway:8001` 或 public host;后者 httpx 会真的去 DNS 解析,
+#    在 gateway 容器内可能不可达 → 连接失败。
+#    → 修法:**写死 127.0.0.1**,完全无视 request.url.netloc。
+#
+# 3. 一度尝试用 httpx.ASGITransport(app=request.app) 进程内直调,看似一劳永逸,
+#    但 httpx 0.28 的 ASGITransport 对 streaming response **整段 buffer**,
+#    一直收齐所有 body chunks 才一次性把响应给消费方 → SSE 完全失效,前端表现
+#    为"调度阶段很长 + 流式结果一次性出现"。已弃用。
+#    → 详见:git log 6e3a07b(那次改 ASGI 引入)及随后回退。
+#
+# 端口策略(优先级,从高到低):
+#   1. 环境变量 DEER_FLOW_GATEWAY_PORT
+#      ── 部署侧紧急覆盖通道,适合 docker-compose / k8s 注入或临时调试
+#   2. config.yaml 的 `gateway.port`
+#      ── 部署侧**推荐**的配置方式,改完不需要重启二进制(get_app_config 有 mtime
+#         热加载,但仍建议跑一次 reload 以确保所有 worker 拿到新值)
+#   3. request.url.port
+#      ── 浏览器直连 gateway:8001 时拿得到;走 Nginx 80/443 反代时会落到下一档
+#   4. 默认 8001(与 `make dev` / `make gateway` / `scripts/start-all.sh` 写死的一致)
+#
+# 端口在哪里改(给运维 / 部署侧的提示):
+#   - yaml 配置:打开 config.yaml,加 / 改:
+#       gateway:
+#         port: 9999
+#   - 环境变量:
+#       export DEER_FLOW_GATEWAY_PORT=9999
+#
+# 修改这两个函数时务必跑一次 SSE 流式 smoke 验证(见 multi-agent-backend-dev.md
+# §13 测试建议),确认 chunks 是逐个到达而不是一次喷出。
 # ---------------------------------------------------------------------------
 
 
-# ASGITransport 不在意 host，仅作 URL 拼接占位。
-_LOOPBACK_BASE_URL = "http://loopback"
+# 写死的最终 fallback。**不要**为了改端口而修改这个常量——优先用 config.yaml /
+# env 这两层(它们在部署侧不需要改源码即可生效)。这个值只在 yaml 缺失 + env
+# 没设 + 请求里也拿不到合法 port 时才会用到。
+_DEFAULT_GATEWAY_PORT = 8001
+
+
+def _resolve_gateway_port(request: Request) -> int:
+    """按四档 fallback 解析 Gateway 监听端口。详见模块顶部「端口策略」。"""
+    # 第 1 档:环境变量。允许非法值(garbage),只警告并继续下一档,不抛异常。
+    env_port = os.environ.get("DEER_FLOW_GATEWAY_PORT", "").strip()
+    if env_port:
+        try:
+            port = int(env_port)
+            if 1 <= port <= 65535:
+                return port
+            raise ValueError("out of range")
+        except ValueError:
+            logger.warning(
+                "DEER_FLOW_GATEWAY_PORT=%r 不是合法端口,fallback 到 config.yaml / request / %d",
+                env_port,
+                _DEFAULT_GATEWAY_PORT,
+            )
+
+    # 第 2 档:config.yaml 的 gateway.port。GatewayConfig.port 的 pydantic 校验
+    # 已经保证它在 1-65535 范围内,无需再次校验。读 config 失败时降级,不阻断业务。
+    try:
+        configured = get_app_config().gateway.port
+        if configured:
+            return configured
+    except Exception as exc:
+        # 极端场景:config.yaml 不存在或解析失败。这种情况下 gateway 本身也起不来,
+        # loopback 端口"猜错"也已经无所谓。仅记 debug 日志方便排查。
+        logger.debug("read gateway.port from app config failed: %s", exc)
+
+    # 第 3 档:从当前请求拿 port。浏览器直连 gateway 时是真实监听端口;
+    # 走 Nginx 反代时通常是 80/443(public port),那就跳过,落到最终默认。
+    inbound_port = request.url.port
+    if inbound_port is not None and inbound_port not in (80, 443):
+        return inbound_port
+
+    # 第 4 档:写死默认。
+    return _DEFAULT_GATEWAY_PORT
 
 
 def _loopback_base(request: Request) -> str:
-    """返回 loopback base URL 占位串。
+    """返回 `http://127.0.0.1:<port>`,供 loopback 调用拼 URL。
 
-    ASGI transport 模式下不再用真实 scheme+host，但保留此函数以兼容
-    `_create_thread / _stream_upstream` 等内部 helper 的 `base` 参数。
+    强制 127.0.0.1 是为了避免 Nginx 反代场景下读到经过 Host 改写的 netloc。
+    端口按 `_resolve_gateway_port` 的四档 fallback 解析。
     """
-    return _LOOPBACK_BASE_URL
+    return f"http://127.0.0.1:{_resolve_gateway_port(request)}"
 
 
 def _make_loopback_client(request: Request) -> httpx.AsyncClient:
-    """构造一个走 ASGITransport 的 httpx.AsyncClient，**不走网络栈**。
+    """构造同进程 loopback 用的 httpx.AsyncClient(真 TCP)。
 
-    所有圆桌路由（intent / recommend / multi_agent）的 loopback 调用都走这里，
-    替代原先的 `httpx.AsyncClient(timeout=None, trust_env=False)` + 127.0.0.1。
+    所有圆桌路由(intent / recommend / multi_agent)的 loopback 调用必须走这里,
+    保持配置一致。
+    - `trust_env=False`:**关键**,忽略 HTTP_PROXY / HTTPS_PROXY,防代理拦截 127.0.0.1
+    - `timeout=None`:SSE 长连接需要,LangGraph runs/stream 可能跑数十秒
+    - `request` 参数当前未被使用,保留是为了:(a) 未来若需要从 request 取部署
+      上下文(如多租户端口隔离)可以无侵入扩展;(b) 与调用方现有签名兼容。
     """
-    transport = httpx.ASGITransport(app=request.app)
     return httpx.AsyncClient(
-        transport=transport,
-        base_url=_LOOPBACK_BASE_URL,
         timeout=None,
+        trust_env=False,
     )
 
 
@@ -462,8 +541,8 @@ async def init_multi_agent(request: Request, payload: dict = Body(...)) -> Strea
         return f"data: {json.dumps(payload, ensure_ascii=False)}\n\n"
 
     async def stream_generator() -> AsyncIterator[str]:
-        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
-        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        # TCP loopback 到 127.0.0.1:<gateway port>。client 配置见 _make_loopback_client：
+        # trust_env=False 防 HTTP_PROXY 拦截,timeout=None 容纳 SSE 长连接。
         async with _make_loopback_client(request) as client:
             try:
                 # Per-seat prepare task — same body as before, but we no longer
@@ -581,7 +660,9 @@ async def _stream_upstream(
     - ``(None, captured)`` — 流结束，``captured`` 为所有 ``data:`` 行文本列表，
       供 ``_parse_last_messages`` 从倒数 values 快照提取 ``messages``。
 
-    日志 ``[upstream-timing]``：排查首 token 慢；loopback 已走 ASGITransport，不会再有代理超时。
+    日志 ``[upstream-timing]``：排查首 token 慢；headers_in 长尾若 >> 网络往返(loopback
+    本机往返通常 <10ms),怀疑 HTTP_PROXY 拦了回环——检查 client 是否走 _make_loopback_client
+    (trust_env=False)。
     """
 
     url = f"{base}/api/threads/{thread_id}/runs/stream"
@@ -997,8 +1078,8 @@ async def run_multi_agent_stream(request: Request, payload: dict = Body(...)) ->
     headers = _auth_headers(request)
 
     async def stream_generator() -> AsyncIterator[str]:
-        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
-        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        # TCP loopback 到 127.0.0.1:<gateway port>。client 配置见 _make_loopback_client：
+        # trust_env=False 防 HTTP_PROXY 拦截,timeout=None 容纳 SSE 长连接。
         async with _make_loopback_client(request) as client:
             try:
                 if agent_type == "leader":
diff --git a/offline-backend-20260512/backend/app/gateway/routers/recommend.py b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
index 14945c8a..8ff444d7 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/recommend.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/recommend.py
@@ -199,8 +199,9 @@ async def stream_recommend(request: Request, payload: dict = Body(...)) -> Strea
     headers = _auth_headers(request)
 
     async def stream_generator() -> AsyncIterator[str]:
-        # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
-        # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
+        # TCP loopback 到 127.0.0.1:<gateway port>(详见 multi_agent._make_loopback_client)。
+        # 不要在这里替换成 httpx.ASGITransport——曾试过,会整段 buffer SSE 流导致前端
+        # 看不到逐 token 增量。
         async with _make_loopback_client(request) as client:
             try:
                 # 每次推荐独立 thread；prompt 已包含完整 intent + 候选列表，无需多轮。
diff --git a/offline-backend-20260512/backend/config.yaml b/offline-backend-20260512/backend/config.yaml
index 3208a97c..219b4b9e 100644
--- a/offline-backend-20260512/backend/config.yaml
+++ b/offline-backend-20260512/backend/config.yaml
@@ -2,6 +2,13 @@
 config_version: 8
 log_level: info
 
+# Gateway FastAPI 监听端口。圆桌三路由(intent / recommend / multi_agent)的同进程
+# loopback 调用会拼 http://127.0.0.1:<port> 打到本机其它 endpoint,所以必须与
+# 实际监听端口一致(scripts/start-all.sh、Makefile 默认 8001)。
+# 部署机改了端口请同步改这里;也可设环境变量 DEER_FLOW_GATEWAY_PORT 临时覆盖。
+gateway:
+  port: 8001
+
 models:
   - name: deepseek-chat
     display_name: DeepSeek Chat
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/__init__.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/__init__.py
index 42a91757..7d9cb6e1 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/__init__.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/__init__.py
@@ -1,5 +1,6 @@
 from .app_config import get_app_config
 from .extensions_config import ExtensionsConfig, get_extensions_config
+from .gateway_config import GatewayConfig
 from .memory_config import MemoryConfig, get_memory_config
 from .paths import Paths, get_paths
 from .skill_evolution_config import SkillEvolutionConfig
@@ -20,6 +21,7 @@ __all__ = [
     "SkillsConfig",
     "ExtensionsConfig",
     "get_extensions_config",
+    "GatewayConfig",
     "MemoryConfig",
     "get_memory_config",
     "get_tracing_config",
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py
index 2d56d443..a8d9b58b 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py
@@ -13,6 +13,7 @@ from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_c
 from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
 from deerflow.config.database_config import DatabaseConfig
 from deerflow.config.extensions_config import ExtensionsConfig
+from deerflow.config.gateway_config import GatewayConfig
 from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
 from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
@@ -122,6 +123,7 @@ class AppConfig(BaseModel):
     skill_stop: SkillStopConfig = Field(default_factory=SkillStopConfig, description="Skill stop middleware configuration")
     model_config = ConfigDict(extra="allow")
     database: DatabaseConfig = Field(default_factory=DatabaseConfig, description="Unified database backend configuration")
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig, description="Gateway FastAPI listening port (used by intra-process loopback)")
     run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
     checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
     stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/gateway_config.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/gateway_config.py
new file mode 100644
index 00000000..008324b1
--- /dev/null
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/gateway_config.py
@@ -0,0 +1,46 @@
+"""Gateway 进程的本机绑定配置。
+
+目前唯一字段是 ``port``——Gateway FastAPI 的监听端口。圆桌三路由
+(intent / recommend / multi_agent) 内部用 loopback 调本机的其它 endpoint
+(``/api/threads``、``/api/agents`` 等),需要知道这个端口才能拼出 base URL。
+
+为什么放在配置里而不是写死
+--------------------------
+- 部署方常常会改 Gateway 监听端口(端口被占用、合规要求、容器化端口映射),
+  写死代码意味着每次改端口都得改源码 + 重新构建/分发,**改 config 不需要重启二进制**
+- ``DEER_FLOW_GATEWAY_PORT`` 环境变量仍然是更高优先级的紧急覆盖通道,适合
+  临时调试或者 docker-compose / k8s 注入
+
+修改方式(部署侧)
+------------------
+在 ``config.yaml`` 顶层加:
+
+.. code-block:: yaml
+
+    gateway:
+      port: 9999        # 默认 8001;部署机改了 gateway 端口时改这里
+
+只想临时改一次(不动 yaml)→ 设环境变量:
+
+.. code-block:: bash
+
+    export DEER_FLOW_GATEWAY_PORT=9999
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class GatewayConfig(BaseModel):
+    """Gateway 本机 loopback 端口配置。"""
+
+    port: int = Field(
+        default=8001,
+        ge=1,
+        le=65535,
+        description=(
+            "Gateway FastAPI 监听端口。圆桌内部 loopback 调用会拼到 "
+            "``http://127.0.0.1:<port>``。默认 8001(与 Makefile/scripts/start-all.sh 对齐)。"
+        ),
+    )