test: add codex test content

# Conflicts:
#	.gitignore
#	frontend-web/src/components/workspace/input-box.tsx
#	frontend-web/src/core/threads/types.ts
#	frontend-web/src/pages/ChatPage.tsx

.codex-server-diagnose.py

@@ -0,0 +1,20 @@
+import os
+
+import paramiko
+
+
+client = paramiko.SSHClient()
+client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+client.connect(
+    "119.254.86.251",
+    port=22322,
+    username="root",
+    password=os.environ["TARGET_SSH_PASSWORD"],
+    timeout=15,
+    auth_timeout=15,
+    banner_timeout=15,
+)
+_, stdout, stderr = client.exec_command(os.environ["TARGET_SSH_COMMAND"], timeout=30)
+print(stdout.read().decode(errors="replace"), end="")
+print(stderr.read().decode(errors="replace"), end="")
+client.close()

.gitignore

@@ -1,6 +1,9 @@
 # Workspace/editor
-.vscode/
-frontend-web/.vscode/
+.vscode/*
+!.vscode/launch.json
+!.vscode/tasks.json
+!.vscode/extensions.json
+frontend-web/.vscode/
 node_modules/
 # Claude Code local-only settings (per-user permissions, not shared)
 .claude/settings.local.json
@@ -52,8 +55,9 @@ offline-backend-20260505/bundle/start_backend.sh
 offline-backend-20260505/bundle/stop_backend.sh
 
 # offline-backend-20260512 runtime artifacts (large files, local config, data)
-offline-backend-20260512/.env.example
-offline-backend-20260512/DEPLOY_BACKEND_OFFLINE_ZH.md
+offline-backend-20260512/.env.example
+offline-backend-20260512/.env
+offline-backend-20260512/DEPLOY_BACKEND_OFFLINE_ZH.md
 offline-backend-20260512/SHA256SUMS
 offline-backend-20260512/config.yaml.example
 offline-backend-20260512/data/
@@ -61,12 +65,14 @@ offline-backend-20260512/deerflow-backend-offline-image-20260505.tar
 offline-backend-20260512/extensions_config.json
 offline-backend-20260512/skills/
 offline-backend-20260512/wheelhouse/
-offline-backend-20260512/backend/.deer-flow/data/*.db
-offline-backend-20260512/backend/.deer-flow/data/*.db-*
-offline-backend-20260512/backend/.deer-flow/*
-offline-backend-20260512/start_backend.sh
-offline-backend-20260512/stop_backend.sh
-offline-backend-20260512/check_backend.sh
+offline-backend-20260512/backend/.deer-flow/data/*.db
+offline-backend-20260512/backend/.deer-flow/data/*.db-*
+offline-backend-20260512/backend/.deer-flow/*
+offline-backend-20260512/backend/.env
+offline-backend-20260512/backend/.env.local
+offline-backend-20260512/start_backend.sh
+offline-backend-20260512/stop_backend.sh
+offline-backend-20260512/check_backend.sh
 
 hermes-agent-main/
 
@@ -77,11 +83,16 @@ offline-backend-20260512/backend/.deer-flow/*
 
 # Per-user skill_evolution overrides — runtime data written by the API
 offline-backend-20260512/backend/skill_evolution.json
-skills/
-hermes-agent-main/
+skills/
+hermes-agent-main/
 .gitignore
-offline-backend-20260512/backend/tests/*
-deploy
+offline-backend-20260512/backend/tests/*
+!offline-backend-20260512/backend/tests/test_llmwiki_weknora.py
+!offline-backend-20260512/backend/tests/test_health_auth_bypass.py
+# Keep the model configuration regression coverage versioned even though
+# this deployment repository otherwise ignores newly added backend tests.
+!offline-backend-20260512/backend/tests/test_model_management.py
+deploy
 .history
 
 # Cloned third-party repos (local only)

.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "ms-python.python",
+    "ms-python.debugpy"
+  ]
+}

.vscode/launch.json

@@ -0,0 +1,66 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "DeerFlow Backend FastAPI (8001)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "uvicorn",
+      "args": [
+        "app.gateway.app:app",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "8001",
+        "--reload"
+      ],
+      "cwd": "${workspaceFolder}/offline-backend-20260512/backend",
+      "python": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+      "envFile": "${workspaceFolder}/offline-backend-20260512/.env",
+      "env": {
+        "PYTHONPATH": "${workspaceFolder}/offline-backend-20260512/backend;${workspaceFolder}/offline-backend-20260512/backend/.deer-flow/python-vendor",
+        "GATEWAY_CORS_ORIGINS": "http://localhost:5174,http://127.0.0.1:5174,http://localhost:8080,http://127.0.0.1:8080"
+      },
+      "console": "integratedTerminal",
+      "justMyCode": false,
+      "subProcess": true
+    },
+    {
+      "name": "DeerFlow Frontend Vite (5174)",
+      "type": "node",
+      "request": "launch",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": [
+        "exec",
+        "vite",
+        "--host",
+        "0.0.0.0",
+        "--port",
+        "5174"
+      ],
+      "cwd": "${workspaceFolder}/frontend-web",
+      "env": {
+        "VITE_BACKEND_BASE_URL": "http://127.0.0.1:8001",
+        "VITE_LANGGRAPH_BASE_URL": "http://127.0.0.1:8001/api"
+      },
+      "console": "integratedTerminal",
+      "outputCapture": "std",
+      "serverReadyAction": {
+        "pattern": "Local:\\s+(https?://[^\\s]+)",
+        "uriFormat": "%s",
+        "action": "debugWithChrome",
+        "webRoot": "${workspaceFolder}/frontend-web"
+      }
+    }
+  ],
+  "compounds": [
+    {
+      "name": "DeerFlow Full Stack (Backend + Frontend)",
+      "configurations": [
+        "DeerFlow Backend FastAPI (8001)",
+        "DeerFlow Frontend Vite (5174)"
+      ],
+      "stopAll": true
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,52 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "DeerFlow：检查本地开发环境",
+      "type": "shell",
+      "command": "$backendPython = '${workspaceFolder}\\offline-backend-20260512\\backend\\.venv\\Scripts\\python.exe'; if (-not (Test-Path -LiteralPath $backendPython)) { throw '后端虚拟环境不存在，请先在 backend 目录执行 uv sync' }; & $backendPython -c \"import uvicorn; print('Backend Python OK')\"; pnpm --dir '${workspaceFolder}\\frontend-web' exec vite --version",
+      "options": {
+        "shell": {
+          "executable": "powershell.exe",
+          "args": [
+            "-NoProfile",
+            "-ExecutionPolicy",
+            "Bypass",
+            "-Command"
+          ]
+        }
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow：前端生产构建",
+      "type": "process",
+      "command": "pnpm",
+      "args": [
+        "build"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/frontend-web"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "DeerFlow：WeKnora 专项测试",
+      "type": "process",
+      "command": "${workspaceFolder}/offline-backend-20260512/backend/.venv/Scripts/python.exe",
+      "args": [
+        "-m",
+        "pytest",
+        "tests/test_llmwiki_weknora.py",
+        "-v"
+      ],
+      "options": {
+        "cwd": "${workspaceFolder}/offline-backend-20260512/backend",
+        "env": {
+          "PYTHONPATH": "."
+        }
+      },
+      "problemMatcher": []
+    }
+  ]
+}

docs/codex-test-content.md

@@ -0,0 +1,3 @@
+# Codex Test Content
+
+This file is a small test-only change created to verify branch and commit workflow.

frontend-web/docs/position-roundtable-sandbox/README.md

@@ -0,0 +1,15 @@
+# 岗位会商沙箱文档
+
+本目录存放**岗位会商文件预览沙箱**的对接与排障说明，独立于 `src/position-roundtable/docs/`，避免与模块内其它文档互相覆盖。
+
+| 文档 | 说明 |
+| --- | --- |
+| [沙箱打开关闭与步骤条.md](./沙箱打开关闭与步骤条.md) | **详细版**：打开/关闭完整时序、步骤条关系、对接接口字段说明、必守规则、历史 bug 根因、排障手册、自测清单、接线示例与代码索引 |
+
+模块总览仍见：`frontend-web/src/position-roundtable/README.md`。
+
+建议读法：
+
+- **从零对接新页面**：正文第 3、5、6、7、8、12、15、16 节  
+- **线上排障**：第 13、14 节  
+- **只要一页纸**：文末「附录 A」

frontend-web/docs/position-roundtable-sandbox/沙箱打开关闭与步骤条.md

@@ -0,0 +1,988 @@
+# 岗位会商 · 沙箱打开 / 关闭与步骤条（详细对接与排障指南）
+
+> **文档位置**：`frontend-web/docs/position-roundtable-sandbox/`  
+> **读者**：下次重做或对接岗位会商页面的同事；线上「沙箱不实时 / 卡死 / 第二次不刷新」时的排障同学。  
+> **最后依据**：当前仓库 `PositionRoundtablePage` + `PositionNodeChat` 实现（含临时名打开、外部 store、前沿节流、按 tool-call 重挂）。
+
+---
+
+## 目录
+
+1. [文档用途与读法](#1-文档用途与读法)
+2. [背景：为什么岗位会商要单独做沙箱](#2-背景为什么岗位会商要单独做沙箱)
+3. [用户可见的正确行为（验收标准）](#3-用户可见的正确行为验收标准)
+4. [整体架构与数据流](#4-整体架构与数据流)
+5. [职责划分：谁拥有什么状态](#5-职责划分谁拥有什么状态)
+6. [对接接口详解](#6-对接接口详解)
+7. [打开沙箱的完整步骤](#7-打开沙箱的完整步骤)
+8. [关闭沙箱的完整步骤](#8-关闭沙箱的完整步骤)
+9. [步骤条与沙箱的关系](#9-步骤条与沙箱的关系)
+10. [流式内容如何进入沙箱（性能关键）](#10-流式内容如何进入沙箱性能关键)
+11. [与普通对话页的对照](#11-与普通对话页的对照)
+12. [重做页面时的必守规则](#12-重做页面时的必守规则)
+13. [历史问题与根因（务必读）](#13-历史问题与根因务必读)
+14. [排障手册（按症状）](#14-排障手册按症状)
+15. [对接自测清单](#15-对接自测清单)
+16. [最小接线示例](#16-最小接线示例)
+17. [关键代码索引](#17-关键代码索引)
+18. [术语表](#18-术语表)
+
+---
+
+## 1. 文档用途与读法
+
+### 1.1 这份文档解决什么问题
+
+岗位会商右侧「文件预览沙箱」看起来像普通对话页的产物预览，但实现路径完全不同。历史上这块反复出过：
+
+- 沙箱不实时打开，要等全文写完才弹；
+- 打开了但内容冻住，生成完才一口气灌进去；
+- 整页卡顿，连消息列表文字都不实时；
+- 同轮「重新生成」第二次写入时，步骤条变了，沙箱却不动；
+- 第一次正常，关掉后再问就不实时。
+
+这些 bug **特别容易在「重做页面 / 换布局 / 自己重写开沙箱逻辑」时复现**。本文把正确对接方式、时序、接口、禁区和排障步骤写全，方便下一位同事直接按文档接线，而不是再靠猜。
+
+### 1.2 建议读法
+
+| 你的目标 | 先读哪些章节 |
+| --- | --- |
+| 从零接一个新页面壳 | 第 3、5、6、7、8、12、15、16 节 |
+| 只改对话子组件探测逻辑 | 第 7、9、12、13 节 |
+| 线上排障 | 第 13、14 节，必要时回看第 10 节 |
+| 理解为什么不能用页面 state | 第 2、10、13 节 |
+
+### 1.3 对照代码（以仓库为准）
+
+| 角色 | 路径 |
+| --- | --- |
+| 页面壳（唯一沙箱宿主） | `frontend-web/src/position-roundtable/pages/PositionRoundtablePage.tsx` |
+| 节点对话（探测 write_file、上报预览） | `frontend-web/src/position-roundtable/components/PositionNodeChat.tsx` |
+| 收口对话 | `frontend-web/src/position-roundtable/components/PositionBuiltinAgentChat.tsx` |
+| 预览 UI（共享组件，勿分叉逻辑） | `frontend-web/src/components/workspace/artifacts/artifact-file-detail.tsx` |
+| 流式正文读取 | `frontend-web/src/core/artifacts/loader.ts` → `loadArtifactContentFromToolCall` |
+| 普通对话页对照（步骤条自动开） | `frontend-web/src/components/workspace/messages/message-group.tsx` |
+| 模块总览 | `frontend-web/src/position-roundtable/README.md` |
+
+---
+
+## 2. 背景：为什么岗位会商要单独做沙箱
+
+### 2.1 普通对话页怎么开沙箱
+
+普通对话页（`ChatPage`）大致是：
+
+```text
+ArtifactsProvider（页面级）
+  └─ ChatBox / MessageList
+       └─ message-group 渲染 write_file 步骤
+            └─ 发现 path 且 autoOpen → artifacts.select + setOpen(true)
+  └─ 右侧 ArtifactFileDetail 读同一套 ThreadContext
+```
+
+要点：
+
+- 对话和预览共享同一套 `ThreadContext`（同一个 `useThreadStream`）。
+- 步骤条组件自己就能触发打开。
+- 流式 `content` 本来就在当前 React 树的 thread 里，不需要「把 thread 镜像到别的地方」。
+
+### 2.2 岗位会商为什么不能照搬
+
+岗位会商页面同时有：
+
+- 左侧任务 / 意图 / 流程图；
+- 中间某个节点的对话（`PositionNodeChat`）；
+- 右侧配置抽屉；
+- **以及一个页面级单例沙箱**，它是对话区的**兄弟节点**，不在 `PositionNodeChat` 的 ThreadContext 里面。
+
+因此：
+
+1. 沙箱拿不到节点对话内部的 `thread`，除非节点主动上报；
+2. 若把每次流式 thread 写进**页面级 `useState`**，整页（任务卡、意图、流程图、对话）都会按流式频率重渲染，主线程会被打爆；
+3. 页面必须自己决定「开 / 关 / 抑制自动再开 / 切节点时清理」，不能让多个子组件各自 `setOpen`。
+
+所以岗位会商采用：
+
+```text
+对话子组件探测 + 上报
+  → 页面壳统一打开唯一 ArtifactFileDetail
+  → 流式 thread 走外部 store，只让沙箱子树订阅
+```
+
+### 2.3 和「多智能体会商 Step2 沙箱」的区别
+
+仓库里还有 `frontend-web/docs/roundtable-step2-sandbox-progress.md`，那是另一套圆桌 Step2 沙箱进度文档，**不是**岗位会商这条链路。对接岗位会商时以本文为准。
+
+---
+
+## 3. 用户可见的正确行为（验收标准）
+
+重做或对接完成后，下列行为必须全部成立（用户感知对齐普通对话页）：
+
+| # | 行为 | 说明 |
+| --- | --- | --- |
+| A | 步骤条刚出现「写入文件」时，沙箱应已打开 | **不必等**步骤条上出现文件名 |
+| B | 沙箱源码边写边滚；消息列表也实时出字 | 不能整页卡死、不能「生成完一口气刷」 |
+| C | content 先于 path 时：先临时名打开，path 到了再改名 | 不闪屏、不重挂 |
+| D | 同轮第二次同路径 `write_file`（重新生成） | 沙箱清空并重新流式 |
+| E | 整轮结束后自动切 Markdown 预览 | 「正在生成，完成后自动预览」消失 |
+| F | 用户手动关闭后，同一次写入不再自动弹 | 下一轮新写入仍可自动开 |
+| G | 切岗位 / 切节点 / 新会话 / 切历史 | 沙箱关掉且不串内容 |
+
+**不要误判的正常现象：**
+
+- 流式期间沙箱停在「源码 / 编辑」视图，结束后才切「预览」——这是 `ArtifactFileDetail` 对 markdown/html 的既定行为，与普通对话页相同，**不是**打开时机 bug。
+- 步骤条长时间显示「写入文件」、没有路径，但沙箱已经打开并在滚动——content-first 模型下这是**预期**。
+
+---
+
+## 4. 整体架构与数据流
+
+```text
+┌──────────────────────────────────────────────────────────────────────────┐
+│ PositionRoundtablePage（页面壳）                                           │
+│                                                                          │
+│  state: sandboxArtifact | null                                           │
+│  ref:   sandboxArtifactRef / closedSandboxKeyRef / latestSnapshotRef     │
+│  store: createSandboxThreadStore()   ←── 禁止改成 useState               │
+│                                                                          │
+│  handlePreviewArtifact(artifact)  ←──────────────────────────────────┐   │
+│  handleNodeThreadSnapshot(...)    ←───────────────────────────────┐  │   │
+│  closeSandbox()                                                   │  │   │
+│                                                                   │  │   │
+│  {sandboxOpen && (                                                │  │   │
+│     SandboxThreadProvider(store)                                  │  │   │
+│       └─ ArtifactFileDetail key=sandboxCloseKey(...)              │  │   │
+│  )}                                                               │  │   │
+└───────────────────────────────────────────────────────────────────│──│───┘
+                                                                    │  │
+┌───────────────────────────────────────────────────────────────────│──│───┐
+│ PositionNodeChat / PositionBuiltinAgentChat                         │  │   │
+│                                                                   │  │   │
+│  useThreadStream → thread.messages / thread.isLoading             │  │   │
+│       │                                                           │  │   │
+│       ├─ MessageList → 步骤条（只展示 tool call）                   │  │   │
+│       │                                                           │  │   │
+│       ├─ latestStreamingWriteFile(messages)                       │  │   │
+│       │     → onPreviewArtifact({..., auto:true}) ───────────────────┘   │
+│       │                                                                  │
+│       └─ useEffect → onThreadSnapshot({threadId, thread}) ───────────────┘
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+一句话：
+
+- **谁打开**：对话子组件决定「该不该开、开哪次交付」；  
+- **谁真正开面板**：页面壳；  
+- **内容怎么更新**：子组件持续上报 thread 快照 → 页面壳 store → 只有沙箱子树重渲染。
+
+---
+
+## 5. 职责划分：谁拥有什么状态
+
+### 5.1 页面壳必须拥有
+
+| 状态 / 能力 | 为什么必须在页面壳 |
+| --- | --- |
+| `sandboxArtifact` | 唯一预览目标；切节点时要清 |
+| `closedSandboxKeyRef` | 用户关过后的抑制；跨子组件生命周期 |
+| `sandboxThreadStore` | 流式内容通道；不能进大页面 state |
+| `closeSandbox()` | 切岗位 / 切节点 / 新会话统一入口 |
+| 唯一 `ArtifactFileDetail` | 避免双实例、关闭失效、深度异常 |
+
+### 5.2 对话子组件必须拥有
+
+| 状态 / 能力 | 作用 |
+| --- | --- |
+| `autoPreviewRunArmedRef`（armed） | 只有本轮用户发送后才允许自动开 |
+| `autoPreviewBaselineCallKeysRef`（baseline） | 忽略发送前已有的历史 write_file |
+| `activeWriteFilePreviewRef` | 记录当前打开的 previewKey / path / toolCallId |
+| `autoPreviewedArtifactKeyRef` | 同一次 identity 去重，避免每 chunk 重复上报 |
+| `latestStreamingWriteFile` | 从 streaming messages 探测可预览的 write |
+| `onThreadSnapshot` 上报 | 把 thread 喂给页面壳 |
+
+### 5.3 明确禁止
+
+1. 在 `PositionNodeChat` 内再挂一套 `ArtifactFileDetail`。  
+2. 让步骤条组件直接 `setOpen(true)` 作为岗位会商主路径（对照普通页可以，岗位会商不行）。  
+3. 把 `onThreadSnapshot` 落到 `PositionRoundtablePage` 的 `useState`。  
+4. 用「整个 threadId」做关闭抑制。  
+5. 用「path 相同」复用 `previewKey`。
+
+---
+
+## 6. 对接接口详解
+
+### 6.1 `PositionArtifactPreview`
+
+```ts
+type PositionArtifactPreview = {
+  threadId: string;          // 必填：LangGraph thread id
+  path: string;              // 必填：真实路径，或 write-file: 虚拟 URL，或临时文件名路径
+  name: string;              // 展示名（文件名）
+  mimeType: string | null;   // 如 text/markdown；帮助预览语言判断
+  previewKey?: string;       // 强烈建议：一次交付身份，推荐 `${messageId}:${toolCallId}`
+  auto?: boolean;            // true = 流式自动打开；缺省/false = 用户点击打开
+};
+```
+
+字段说明：
+
+| 字段 | 详细含义 |
+| --- | --- |
+| `threadId` | 沙箱用来匹配 `onThreadSnapshot` 的线程；也对关闭抑制键有贡献 |
+| `path` | 传给 `ArtifactFileDetail.filepath`。流式阶段通常是 `write-file:...` 虚拟 URL；落盘后的手动打开可以是真实 artifacts 路径 |
+| `name` | UI 展示用；临时名阶段可能是 `未命名文件.md` |
+| `mimeType` | 当 path 还不稳定时，帮助把语言判成 markdown/html，避免落成 TEXT |
+| `previewKey` | **一次交付的身份**。同一次 tool call 的 path 升级要保持不变；新的 tool call 必须变 |
+| `auto` | 自动打开才走关闭抑制；手动打开应清抑制 |
+
+### 6.2 `onPreviewArtifact(artifact)` —— 对话 → 页面
+
+页面壳 `handlePreviewArtifact` 当前逻辑顺序：
+
+1. 校验 `threadId`、`path`，缺则 toast 并 return。  
+2. 计算 `artifactKey = sandboxCloseKey(artifact)`。  
+3. 若 `artifact.auto === true` 且 `closedSandboxKeyRef.current === artifactKey` → **抑制，直接 return**。  
+4. 清 `closedSandboxKeyRef`（手动打开或新的自动打开）。  
+5. `ArtifactsContext.select(path, true)` + `setOpen(true)`。  
+6. 判断是否同一预览 / 是否仅 path upgrade：  
+   - `isSamePreview`：threadId + path + previewKey 全同 → 不重复 setState。  
+   - `isPathUpgrade`：previewKey 相同、path 不同 → 更新 artifact，**不要**再折叠右侧抽屉。  
+7. 若不是 same preview：  
+   - `setSandboxArtifact(artifact)`；  
+   - **同步** `sandboxArtifactRef.current = artifact`（关键！flush 会立刻读 ref）；  
+   - `sandboxSnapshotAppliedAtRef.current = 0`（允许立刻推首帧内容）。  
+8. 若 store 里已有别的 thread 快照，先 `publish(null)`。  
+9. 若 `latestNodeThreadSnapshotRef` 的 threadId 匹配，立刻 `queueSandboxThreadSnapshot`。  
+10. 非 path upgrade 时 `setRightPanelOpen(false)`。
+
+`sandboxCloseKey`：
+
+```ts
+if (artifact.previewKey) {
+  return `${artifact.threadId}:write:${artifact.previewKey}`;
+}
+return `${artifact.threadId}:${normalizePreviewArtifactPath(artifact.path)}`;
+```
+
+`ArtifactFileDetail` 的 React `key` 必须用这个 key：  
+**新 previewKey → 组件重挂 → 视觉上「清空再生成」。**
+
+### 6.3 `onThreadSnapshot({ threadId, thread })` —— 对话 → 页面
+
+每次 `thread` 引用变化（消息 chunk 到达）子组件都会调：
+
+```ts
+onThreadSnapshot?.({ threadId: activeThreadId, thread });
+```
+
+页面壳应：
+
+1. 计算 `signature = sandboxThreadSignature(thread)`（用 isLoading、messages 长度、最近 write_file 的 path/content 长度/尾部等拼签名，用于去重）。  
+2. 写入 `latestNodeThreadSnapshotRef`（即使沙箱还没开，打开瞬间也要用）。  
+3. 若当前没有打开的沙箱，或打开的沙箱 threadId 不一致 → **只更新 ref，不 publish**。  
+4. 若一致 → `queueSandboxThreadSnapshot`（前沿节流后 `store.publish`）。
+
+### 6.4 虚拟 URL 与正文读取
+
+流式阶段 path 形如：
+
+```text
+write-file:${sourcePath}?message_id=${messageId}&tool_call_id=${toolCallId}&language=markdown
+```
+
+`loadArtifactContentFromToolCall`：
+
+1. 解析 URL 的 `message_id`、`tool_call_id`；  
+2. 在 `thread.messages` 里找对应 AI message 的 tool call；  
+3. 返回 `toolCall.args.content`。
+
+结论：
+
+- 沙箱跟的是 **tool call 身份**，不是磁盘文件是否已经写完；  
+- 没有真实 path 也能显示正文；  
+- 临时文件名只影响展示名和语言猜测。
+
+### 6.5 对话子组件 → 页面壳的其它相关回调
+
+| 回调 | 用途 |
+| --- | --- |
+| `onPreviewArtifact` | 打开 / 更新沙箱 |
+| `onThreadSnapshot` | 推送流式 thread |
+| 页面壳 `closeSandbox` 传给 `ArtifactFileDetail.onClose` | 用户点关闭 |
+
+手动从流程图 / 产物列表打开时，也可以直接调 `handlePreviewArtifact`（通常不带 `auto`，或不带 previewKey）。
+
+---
+
+## 7. 打开沙箱的完整步骤
+
+### 7.1 武装（arm）：只有「本轮用户提交」才允许自动开
+
+在 `PositionNodeChat.handleSubmit` 真正 `sendMessage` 之前：
+
+```text
+activeWriteFilePreviewRef = null
+autoPreviewBaselineCallKeysRef = writeFileCallKeys(thread.messages)  // 历史 write 的 messageId:toolCallId
+autoPreviewRunArmedRef = true
+→ sendMessage(...)
+```
+
+发送失败要把 `armed` 设回 `false`。
+
+为什么要 baseline？
+
+线程里往往已经有上几次问答写过的 `write_file`。如果只看「messages 里有没有 write_file」，一提问就会把旧文件再打开一次。baseline 的含义是：**只有这次提交之后新出现的 tool call 才能自动开沙箱**。
+
+### 7.2 探测 `write_file`：不要等完整 path
+
+`write_file` 参数是一整段 JSON 流，**键顺序由模型决定**。
+
+| 模型吐参顺序 | 步骤条表现 | 错误做法的后果 |
+| --- | --- | --- |
+| path / description 先到，再 content | 很快显示描述和文件名 | 普通对话页常见；等 path 也能开 |
+| **content 先到，最后才 path** | 长时间只有「写入文件」，文件名很晚才出现 | 若硬等完整 path，沙箱会晚几十秒甚至一分钟 |
+
+岗位会商报告类 agent **经常是第二种**。
+
+`latestStreamingWriteFile` 规则：
+
+1. 倒序扫描 AI messages 的 `tool_calls`；  
+2. 工具名是 `write_file` 或 `str_replace`；  
+3. **有完整扩展名的 path**（`hasCompleteArtifactExtension`）→ 用真实路径；  
+4. **尚无可用 path，但 `write_file` 的 content 已有非空字符** → 临时文件名：  
+   - 正文头像 HTML → `未命名文件.html`  
+   - 否则 → `未命名文件.md`  
+5. `str_replace` 必须等真实 path（它改已有文件）；  
+6. 组装：  
+   - `key = messageId:toolCallId`  
+   - `path = write-file:虚拟URL`（write_file）或真实 path（str_replace）  
+   - `mimeType`：markdown 则 `text/markdown`
+
+为什么扩展名必须完整？
+
+流式 path 会经历 `/a/b/report.m` → `/a/b/report.md`。若在 `.m` 时就当真实文件打开，预览语言可能被永久判成 TEXT。
+
+### 7.3 上报 effect 的四个门闩
+
+自动上报 `onPreviewArtifact` 前必须同时满足：
+
+1. `thread.isLoading === true`  
+2. 探测到 streaming artifact，且其 key **不在** baseline  
+3. 已有 `previewThreadId`  
+4. `autoPreviewRunArmedRef === true`
+
+然后处理 previewKey：
+
+```text
+若与 activePreview 是同一次 tool call（含 tool-start 前缀兼容）
+  → 复用旧 previewKey   // 用于临时名 → 真实 path
+否则
+  → previewKey = 新的 messageId:toolCallId
+```
+
+去重键：
+
+```text
+`${previewThreadId}:${previewKey}:${sourcePath}`
+```
+
+把 `sourcePath` 算进去，是为了：**同 previewKey 下临时名变成真实 path 时，还要再报一次**（path upgrade），但不会每来一个 content chunk 都报。
+
+### 7.4 线程绑定竞态（不要误 disarm）
+
+首轮对话常出现：
+
+1. 用户发送（本地 draft threadId / 稍后 SDK 创建真实 id）；  
+2. 流已经开始、armed=true；  
+3. 会话 API 把 `node.threadId` 从 `null` 写成真实 id。
+
+这是「本节点绑定自己的新线程」，**不是**切节点。若绑定 effect 无脑清空 armed / baseline，首轮会永远开不了沙箱。
+
+正确：识别 `isOwnThreadBinding`（同 nodeKey、旧 threadId 为空、新 threadId 等于当前 boundThreadId）时 **直接 return，不清 armed**。
+
+### 7.5 path upgrade（改名）≠ 第二次交付
+
+同一次 tool call：
+
+```text
+T1  content 到达 → path=未命名文件.md, previewKey=msg:tc1 → 打开
+T2  真实 path 到达 → path=/mnt/.../报告.md, previewKey=msg:tc1 → 只改名
+```
+
+页面壳看到相同 previewKey、不同 path → `isPathUpgrade`：
+
+- 更新 `sandboxArtifact`；  
+- **不**重挂（React key 仍基于 previewKey）；  
+- **不**再折叠右侧抽屉。
+
+### 7.6 同路径二次写入（重新生成）
+
+同一次问答里模型可能：
+
+```text
+1) write_file → 步骤条「写入文件」→ 打开沙箱
+2) 再 write_file 同 path，description=「重新生成优化版…」
+```
+
+这是**两次 tool call**，必须两个 previewKey。  
+若错误地「path 相同就复用 previewKey」：
+
+- 步骤条出现第二条；  
+- 沙箱 React key 不变；  
+- 用户看到「重新生成了，但沙箱没变化」。
+
+正确：身份只看 tool call。
+
+### 7.7 时序总图（content-first）
+
+```text
+T0    用户发送 → armed=true，拍 baseline
+T1    步骤条出现「写入文件」（尚无 path）
+T1+   args.content 首字符到达 → 临时名打开沙箱，源码开始滚动
+      … store 约每 160ms 推一次 thread 快照 …
+T2    args.path 拼完整（含 .md）→ path upgrade，标题改真实文件名（不重挂）
+T3    write 结束 / isLoading=false → 自动切 Markdown 预览
+```
+
+### 7.8 时序总图（同轮二次写入）
+
+```text
+T1  write_file#1 → previewKey=msg:tc1 → 打开沙箱 A
+T2  #1 结束（可能短暂切预览）
+T3  write_file#2（同 path，新 description）→ previewKey=msg:tc2
+    → key 变 → 组件重挂清空 → 跟 #2 重新流式
+```
+
+---
+
+## 8. 关闭沙箱的完整步骤
+
+### 8.1 用户手动关闭
+
+`closeSandbox()` 应做：
+
+1. `closedSandboxKeyRef = sandboxCloseKey(current)` —— 抑制**这一次**自动再开；  
+2. 关闭 `ArtifactsContext.open`（若开着）；  
+3. 清节流定时器、pending 快照；  
+4. `sandboxSnapshotAppliedAtRef = 0`；  
+5. `sandboxArtifactRef = null` + `setSandboxArtifact(null)`；  
+6. `sandboxThreadStore.publish(null)`。
+
+抑制与 path upgrade 的关系：
+
+- 关掉临时名面板后，同一次 tool call 升级真实 path **仍被抑制**（同一 previewKey）——符合「用户不要看这次」；  
+- 下一次新的 `write_file`（新 previewKey）**可以**再自动开。
+
+### 8.2 场景切换时强制关闭
+
+以下操作应先调用 `closeSandbox()`，避免串台：
+
+- 切岗位；  
+- 切节点；  
+- 切收口阶段；  
+- 新建会话；  
+- 切换历史会话。
+
+是否写入 `closedSandboxKeyRef` 可按产品决定；至少必须清面板和 store。
+
+### 8.3 错误的抑制粒度（历史坑）
+
+若做成「关过一次就整个 thread 不再自动开」：
+
+- 第一次实时开正常；  
+- 用户关掉；  
+- 再问一次 → 同 thread 被永久抑制 → 看起来像「第二次不实时 / 要等生成完」。
+
+正确粒度：**单次交付的 `sandboxCloseKey`（含 previewKey）**。
+
+---
+
+## 9. 步骤条与沙箱的关系
+
+### 9.1 步骤条从哪来
+
+步骤条由 `MessageList` → `message-group.tsx` 渲染 tool call：
+
+- 标题：优先 `args.description`；没有则 i18n 兜底「写入文件」；  
+- 子行：有 `args.path` 才显示路径；  
+- 普通对话页还会在「有 path + autoOpen」时自己 `select/setOpen`。
+
+岗位会商里，步骤条**仍然只负责展示**；打开沙箱走 `onPreviewArtifact`，不要让两套逻辑抢。
+
+### 9.2 对照表
+
+| 你看到的步骤条 | 含义 | 沙箱应处于 |
+| --- | --- | --- |
+| 仅「写入文件」，无路径 | tool call 已开始；path/description 可能还没流到 | **应已打开**（临时名），源码在滚 |
+| 「写入文件」+ 路径 | path 已可用 | 已打开；若刚从临时名升级则只改名 |
+| 带自定义 description 的标题 + 路径 | 模型给了 description | 同上 |
+| 第二条「重新生成…」+ 同路径 | 新的 write_file（新 toolCallId） | **应重挂**并重新流式 |
+| 顶部「正在生成，完成后自动预览」 | 仍在 code 视图 | 正常，等 isLoading 结束切预览 |
+| 生成结束，出现文件卡片 / present_files | 工具结果已落 | 通常已是预览模式；可手动再点开 |
+
+### 9.3 常见误解
+
+**误解 1：**「步骤条出现文件名 = 打开沙箱的正确时机」  
+→ 错。那是 path 到达的时机。content-first 时正确打开时机更早：content 首字节 / 工具调用已开始。
+
+**误解 2：**「步骤条还在写『写入文件』，沙箱却开了，是 bug」  
+→ 通常不是。两边数据源相同，但沙箱允许无 path 打开，步骤条标题可能还没 description。
+
+**误解 3：**「等生成完从编辑切预览 = 沙箱打开晚了」  
+→ 错。那是 `ArtifactFileDetail` 的 viewMode 策略。
+
+---
+
+## 10. 流式内容如何进入沙箱（性能关键）
+
+### 10.1 为什么不能用页面 `useState` 存线程快照
+
+错误写法：
+
+```ts
+setSandboxThreadSnapshot(snapshot) // 页面级 useState
+```
+
+后果：
+
+- 消息 chunk 约每 30ms 一次，节流后仍约 6 次/秒；  
+- 每次都重渲染整页：任务卡、意图结果、流程图、节点对话……；  
+- 主线程占满 → 消息列表停绘、沙箱冻住；  
+- 纯尾随 `setTimeout(160)` 会被饿死，十几秒不 flush。
+
+这同时解释了两个历史现象：
+
+1. 「沙箱打开了但内容不更新」；  
+2. 「修完节流后整页更卡、消息也不实时」——因为节流终于开始真正 setState 了。
+
+### 10.2 正确做法：外部 store + 子树订阅
+
+```ts
+createSandboxThreadStore()
+  subscribe / getSnapshot / publish
+
+SandboxThreadProvider
+  useSyncExternalStore(store.subscribe, store.getSnapshot)
+  → ThreadContext.Provider value={{ thread, isMock:false }}
+  → ArtifactFileDetail
+```
+
+页面壳本身**不**因 snapshot 变化而重渲染；只有 Provider 及其子树重渲染。
+
+### 10.3 节流必须是前沿（leading-edge）
+
+`SANDBOX_SNAPSHOT_MIN_INTERVAL_MS = 160`：
+
+```text
+queue(snapshot):
+  pending = snapshot
+  if 距上次 publish >= 160ms:
+      立刻 flush（同步 publish）
+  else:
+      若没有在途 timer，则 setTimeout(剩余时间) 做补尾
+flush:
+  清 timer
+  校验 pending.threadId === sandboxArtifactRef.threadId
+  publish(pending)
+```
+
+**不要**改回：
+
+```ts
+if (timer != null) return;
+timer = setTimeout(flush, 160);
+```
+
+那是纯尾随；忙主线程下会假死。
+
+### 10.4 signature 去重
+
+`sandboxThreadSignature` 用最近 write_file 的 path、content 长度、content 尾 32 字等拼签名。  
+store.publish 时若 threadId+signature 未变，则不通知订阅者，减少无效渲染。
+
+### 10.5 打开瞬间的首帧
+
+`handlePreviewArtifact` 里往往会立刻 `queueSandboxThreadSnapshot(latestSnapshot)`。  
+此时 React 的 `setSandboxArtifact` 可能还没提交，若 flush 只读旧的 `sandboxArtifactRef`，会因 threadId 不匹配把首帧丢掉。
+
+所以打开新预览时必须：
+
+```ts
+sandboxArtifactRef.current = artifact; // 同步
+sandboxSnapshotAppliedAtRef.current = 0;
+```
+
+---
+
+## 11. 与普通对话页的对照
+
+| 点 | 普通对话页 | 岗位会商 |
+| --- | --- | --- |
+| 谁触发打开 | `message-group` 内 `artifacts.select` | 子组件 `onPreviewArtifact` → 页面壳 |
+| 是否要求 path | 是（有 path 才自动开） | 否（write_file + content 可临时名开） |
+| thread 从哪来 | 同树 ThreadContext | `onThreadSnapshot` + 外部 store |
+| 关闭抑制 | 主要靠 ArtifactsContext / 用户操作 | `closedSandboxKeyRef` 按 previewKey |
+| 同 path 重写 | 依赖新的 tool call / 选择逻辑 | **必须**新 previewKey 以重挂 |
+| 结束后切预览 | ArtifactFileDetail 同一套 | 同一套 |
+
+对齐目标是**用户感知一致**，不是代码路径完全相同。
+
+普通对话页自动开的核心条件（对照用）：
+
+```ts
+artifacts && isLoading && isLast && autoOpen && autoSelect && path && !result
+```
+
+它也要求 path，所以 content-first 时普通页同样会偏晚——只是很多主聊天示例 agent 先吐 path，观感更好。岗位会商报告 agent 更常 content-first，所以必须做临时名提前开。
+
+---
+
+## 12. 重做页面时的必守规则
+
+按优先级：
+
+1. **流式 thread 快照禁止进页面级 `useState`** → 用 store + `useSyncExternalStore`。  
+2. **节流用前沿 + 补尾**，不要纯尾随 timer。  
+3. **不要等完整 path 才开**；`write_file` + content 即可临时名打开。  
+4. **扩展名完整前不要把 path 当最终 path**。  
+5. **previewKey 按 tool call，不按 path**。  
+6. **打开时同步写 `sandboxArtifactRef`，并重置节流时间戳**。  
+7. **主路径扫描 `thread.messages`，不要只靠 `onToolStart`**。  
+8. **path upgrade 保持 previewKey，不要当第二次交付**。  
+9. **关闭抑制按 sandboxCloseKey，不要按整 thread**。  
+10. **沙箱单例在页面壳；子组件只上报**。  
+11. **本节点 threadId 回写不要 disarm**。  
+12. **「结束后才切预览」不要当打开 bug 去「修」掉共享组件**，除非产品明确要求边生成边渲染 Markdown（需单独评估性能）。
+
+---
+
+## 13. 历史问题与根因（务必读）
+
+下面每个都在真实联调里出现过。重做时若踩中，优先回来对照。
+
+### 13.1 沙箱要等文件名出来才开（晚几十秒）
+
+**现象：** 步骤条早就「写入文件」，沙箱很晚才开；普通对话页对比显得「实时」。  
+
+**根因：** 探测逻辑硬等完整 `path`；而该 agent 先流 `content`、最后才流 `path`。  
+
+**修复：** content 首批字符即可用临时名打开；path 到了再 upgrade。
+
+### 13.2 沙箱打开了，内容冻住，生成完才灌满
+
+**现象：** 面板开了，但里面一直是空/旧内容；日志里 queue 很多，flush 很少。  
+
+**根因：** 纯尾随 160ms 定时器在忙主线程下被饿死。  
+
+**修复：** 前沿节流——到期就在流回调里同步 flush。
+
+### 13.3 修完「内容更新」后，整页卡顿、消息也不实时
+
+**现象：** 沙箱开始更新了，但页面更卡，消息列表也「攒到最后刷」。  
+
+**根因：** flush 走的是页面 `useState`，每 160ms 整页重渲染。以前 timer 饿死时反而「不卡」。  
+
+**修复：** 快照改外部 store，只让沙箱子树订阅。
+
+### 13.4 第二次「重新生成」步骤有了，沙箱不变
+
+**现象：** 同轮第二条二条 write 步骤，沙箱仍显示第一次完整结果。  
+
+**根因：** 用「path 相同」复用了第一次 previewKey，React key 不变，组件不重挂。  
+
+**修复：** previewKey 只按 tool call；同 path 新 call 必须新 key。
+
+### 13.5 第一次实时，关掉后再问就不实时
+
+**现象：** 关过沙箱后，下一轮要等生成完才开，或不开。  
+
+**根因：** 抑制绑在整个 threadId，或把 path upgrade / 新 call 误判成同一次。  
+
+**修复：** 抑制键 = `sandboxCloseKey(previewKey)`；仅抑制那一次交付。
+
+### 13.6 首轮永远不开
+
+**现象：** 新建节点第一次提问，armed 后很快又不满足条件。  
+
+**根因：** `node.threadId` 从 null 回写真实 id 时，绑定 effect 误 disarm。  
+
+**修复：** `isOwnThreadBinding` 时不清 armed。
+
+### 13.7 预览变成纯文本
+
+**现象：** 明明是 md，却按 TEXT 打开。  
+
+**根因：** 在 `.m` 阶段就当完整 path；或临时名没有 `.md` / 没传 language、mimeType；或 path 带空格。  
+
+**修复：** `hasCompleteArtifactExtension`；临时名带扩展名；URL 加 `language=markdown`；path trim。
+
+### 13.8 依赖 onToolStart，线上偶发不开
+
+**现象：** 本地偶发正常，联调经常不开。  
+
+**根因：** 后端 StreamBridge / worker 可能过滤 tools/events 类 stream mode。  
+
+**修复：** 主路径必须是 messages 里渐进出现的 `tool_calls`；onToolStart 只能当补充。
+
+---
+
+## 14. 排障手册（按症状）
+
+排障时建议先看 Chrome Performance / React 重渲染是否整页抖，再看消息里 tool_calls 的 args 是 path-first 还是 content-first。
+
+### 14.1 沙箱开得很晚
+
+检查顺序：
+
+1. `latestStreamingWriteFile` 是否仍要求完整 path？  
+2. armed 是否被 threadId 回写清掉？  
+3. 是否命中 `closedSandboxKey`？  
+4. 新 call 是否被 baseline 当成历史？  
+5. `previewThreadId` 是否为空（线程还没绑上）？
+
+### 14.2 打开了但内容空白 / 冻住
+
+1. 快照是否进了页面 useState？  
+2. 节流是否纯尾随？  
+3. `SandboxThreadProvider` 是否拿到带 messages 的 thread？  
+4. 虚拟 URL 的 message_id / tool_call_id 是否对得上？  
+5. 打开时 `sandboxArtifactRef` 是否同步？（首帧是否被 drop）  
+6. signature 是否因实现错误一直不变，导致 publish 被去重？
+
+### 14.3 整页卡、消息列表也不实时
+
+1. 搜页面壳是否还有 `setSandboxThreadSnapshot` / 类似大对象 state。  
+2. 是否在每 chunk `console.debug` 打大对象（DevTools 打开时更卡）。  
+3. 是否错误地让页面壳订阅了 store（页面壳不应 `useSyncExternalStore` 这份 store；只有 Provider 订）。
+
+### 14.4 重新生成不刷新
+
+1. 第二次 write 的 toolCallId 是否变了？  
+2. previewKey 是否仍用 path 复用？  
+3. `ArtifactFileDetail` 的 `key=` 是否基于 sandboxCloseKey/previewKey？
+
+### 14.5 关后再问异常
+
+1. 打印 `closedSandboxKeyRef` 与新 artifact 的 sandboxCloseKey。  
+2. 确认新一轮 send 时 armed/baseline 已重置。  
+3. 确认抑制不是整 thread。
+
+### 14.6 语言 / 预览模式不对
+
+1. 看打开时的 path / mimeType / language 查询参数。  
+2. 确认不是在扩展名不完整时打开。  
+3. 确认「源码→预览」发生在 isLoading false 之后（属正常）。
+
+---
+
+## 15. 对接自测清单
+
+重做页面后至少跑完：
+
+### 功能
+
+- [ ] 首轮：步骤条「写入文件」出现时，沙箱是否已开并开始出字？  
+- [ ] content-first agent：无文件名阶段是否也能开？  
+- [ ] path 到达后：是否只改名、不整页闪、不重挂？  
+- [ ] 同轮第二次同路径 write：是否清空并重新流式？  
+- [ ] 结束后是否自动切 Markdown 预览？  
+- [ ] 手动点步骤条路径 / 产物卡片：能否打开正确文件？  
+
+### 关闭与抑制
+
+- [ ] 流式中手动关闭：本次是否不再自动弹？  
+- [ ] 关闭后再发一轮新问题：是否仍可自动开？  
+- [ ] path upgrade 是否不会绕过「用户刚关闭」的抑制？  
+
+### 场景切换
+
+- [ ] 切节点：沙箱关闭，旧内容不残留。  
+- [ ] 切岗位：同上。  
+- [ ] 新建会话 / 切历史：同上。  
+
+### 性能
+
+- [ ] 流式中消息列表是否实时出字？  
+- [ ] 页面是否明显掉帧 / 卡死？  
+- [ ] React DevTools 中，大页面壳是否在每 160ms 整页 update？（不应）
+
+---
+
+## 16. 最小接线示例
+
+### 16.1 页面壳（示意）
+
+```tsx
+const [sandboxArtifact, setSandboxArtifact] = useState<PositionArtifactPreview | null>(null);
+const sandboxArtifactRef = useRef<PositionArtifactPreview | null>(null);
+const closedSandboxKeyRef = useRef<string | null>(null);
+const latestNodeThreadSnapshotRef = useRef<SandboxThreadSnapshot | null>(null);
+const store = useMemo(createSandboxThreadStore, []);
+// pending + timer + appliedAt 用于前沿节流（见 PositionRoundtablePage）
+
+function handlePreviewArtifact(artifact: PositionArtifactPreview) {
+  if (!artifact.threadId || !artifact.path) return;
+  const key = sandboxCloseKey(artifact);
+  if (artifact.auto && closedSandboxKeyRef.current === key) return;
+  closedSandboxKeyRef.current = null;
+
+  artifactsCtx?.select(artifact.path, true);
+  artifactsCtx?.setOpen(true);
+
+  const prev = sandboxArtifactRef.current;
+  const isSame =
+    prev?.threadId === artifact.threadId &&
+    prev.path === artifact.path &&
+    prev.previewKey === artifact.previewKey;
+  const isPathUpgrade =
+    !isSame &&
+    Boolean(artifact.previewKey) &&
+    prev?.threadId === artifact.threadId &&
+    prev.previewKey === artifact.previewKey;
+
+  if (!isSame) {
+    sandboxArtifactRef.current = artifact; // 必须同步
+    setSandboxArtifact(artifact);
+    sandboxSnapshotAppliedAtRef.current = 0;
+  }
+
+  if (store.getSnapshot()?.threadId !== artifact.threadId) {
+    store.publish(null);
+  }
+  const latest = latestNodeThreadSnapshotRef.current;
+  if (latest?.threadId === artifact.threadId) {
+    queueSandboxThreadSnapshot(latest);
+  }
+  if (!isPathUpgrade) setRightPanelOpen(false);
+}
+
+function handleNodeThreadSnapshot(snapshot: { threadId: string; thread: BaseStream<AgentThreadState> }) {
+  const next = { ...snapshot, signature: sandboxThreadSignature(snapshot.thread) };
+  latestNodeThreadSnapshotRef.current = next;
+  if (sandboxArtifactRef.current?.threadId !== snapshot.threadId) return;
+  queueSandboxThreadSnapshot(next);
+}
+
+function closeSandbox() {
+  if (sandboxArtifactRef.current) {
+    closedSandboxKeyRef.current = sandboxCloseKey(sandboxArtifactRef.current);
+  }
+  // clear timer / pending / appliedAt
+  sandboxArtifactRef.current = null;
+  setSandboxArtifact(null);
+  store.publish(null);
+  artifactsCtx?.setOpen(false);
+}
+
+// 渲染
+{sandboxArtifact && (
+  <SandboxThreadProvider
+    store={store}
+    threadId={sandboxArtifact.threadId}
+    fallbackThread={stub}
+  >
+    <ArtifactFileDetail
+      key={sandboxCloseKey(sandboxArtifact)}
+      filepath={sandboxArtifact.path}
+      threadId={sandboxArtifact.threadId}
+      mimeType={sandboxArtifact.mimeType}
+      onClose={closeSandbox}
+      allowVirtualMarkdownEdit
+    />
+  </SandboxThreadProvider>
+)}
+```
+
+### 16.2 对话子组件（示意）
+
+```tsx
+// send 前
+activeWriteFilePreviewRef.current = null;
+autoPreviewBaselineCallKeysRef.current = writeFileCallKeys(thread.messages);
+autoPreviewRunArmedRef.current = true;
+await sendMessage(...);
+
+// 探测
+const streaming = thread.isLoading ? latestStreamingWriteFile(thread.messages) : null;
+const next =
+  streaming && !autoPreviewBaselineCallKeysRef.current.has(streaming.key)
+    ? streaming
+    : null;
+
+useEffect(() => {
+  if (!thread.isLoading || !next || !previewThreadId || !autoPreviewRunArmedRef.current) return;
+
+  // previewKey：同 tool call 复用，否则用 next.key
+  // artifactKey = threadId:previewKey:sourcePath 去重
+  onPreviewArtifact?.({
+    threadId: previewThreadId,
+    path: next.path,
+    name: next.name,
+    mimeType: next.mimeType,
+    previewKey,
+    auto: true,
+  });
+}, [next, previewThreadId, thread.isLoading, onPreviewArtifact]);
+
+useEffect(() => {
+  onThreadSnapshot?.({ threadId: activeThreadId, thread });
+}, [activeThreadId, thread, onThreadSnapshot]);
+```
+
+**强烈建议：** 探测 / armed / baseline / 临时名逻辑直接复用或抽取自 `PositionNodeChat`，不要从零重写。
+
+---
+
+## 17. 关键代码索引
+
+| 主题 | 位置 |
+| --- | --- |
+| 临时名 / 完整扩展名 / latestStreamingWriteFile | `PositionNodeChat.tsx` 中 `provisionalWriteFilePath`、`hasCompleteArtifactExtension`、`latestStreamingWriteFile` |
+| armed / baseline / 上报 effect | `PositionNodeChat.tsx` `handleSubmit` + streaming preview `useEffect` |
+| 同 tool call 判断 / 二次写入重挂 | 同上，`isSameToolCall` / `previewKey` |
+| 线程绑定保护 | `PositionNodeChat.tsx` node binding `useEffect` 中 `isOwnThreadBinding` |
+| sandboxCloseKey / store / 前沿节流 | `PositionRoundtablePage.tsx` `sandboxCloseKey`、`createSandboxThreadStore`、`queueSandboxThreadSnapshot` |
+| 打开 / path upgrade / 抑制 | `PositionRoundtablePage.tsx` `handlePreviewArtifact` |
+| 关闭 | `PositionRoundtablePage.tsx` `closeSandbox` |
+| 虚拟 URL 读 content | `core/artifacts/loader.ts` `loadArtifactContentFromToolCall` |
+| 源码/预览切换 | `artifact-file-detail.tsx` 中 `viewMode` + `thread.isLoading` |
+| 普通页步骤条自动开 | `message-group.tsx` `write_file` 分支 |
+
+相关提交（背景）：
+
+- `fix(frontend): 岗位会商沙箱在 write_file 流式阶段实时打开并刷新`  
+  — 临时名打开、外部 store、前沿节流  
+- `fix(frontend): 同路径二次 write_file 时重挂岗位会商沙箱`  
+  — previewKey 按 tool call，禁止按 path 复用  
+
+---
+
+## 18. 术语表
+
+| 术语 | 含义 |
+| --- | --- |
+| armed | 本轮用户发送后，允许自动打开沙箱的开关 |
+| baseline | send 前已有的 write tool call 集合，用于忽略历史产物 |
+| previewKey | 一次交付的稳定身份，推荐 `messageId:toolCallId` |
+| sandboxCloseKey | 关闭抑制键，同时用作 `ArtifactFileDetail` 的 React key |
+| provisional path / 临时名 | 尚无真实 path 时的 `未命名文件.md` / `.html` |
+| path upgrade | 同 previewKey 下临时名升级为真实 path |
+| sandboxThreadStore | 流式线程外部 store，避免整页重渲染 |
+| write-file: URL | 用 message_id + tool_call_id 定位流式 content 的虚拟路径 |
+| leading-edge throttle / 前沿节流 | 到期立即在回调里 publish，而不是只挂尾随 timer |
+| content-first / path-first | 模型流式 JSON 参数时 content 与 path 哪个先到 |
+| isOwnThreadBinding | 本节点把自己的新 threadId 写回 props，不是切节点 |
+
+---
+
+## 附录 A：给对接同学的一页纸摘要
+
+1. 页面壳只挂一个沙箱；子组件只调用 `onPreviewArtifact` / `onThreadSnapshot`。  
+2. 自动打开时机 ≈ 步骤条出现「写入文件」时，而不是出现文件名时。  
+3. `write_file` 可以没有 path：临时名打开，path 到了再改名。  
+4. 流式 thread 进外部 store，进页面 state 会卡死。  
+5. 节流要前沿；previewKey 看 tool call；关闭抑制看 sandboxCloseKey。  
+6. 同路径重新生成 = 新 previewKey = 沙箱重挂。  
+7. 出问题先对照第 13、14 节，再看代码索引第 17 节。

frontend-web/src/components/page-sidebar.tsx

@@ -2,6 +2,7 @@ import { useEffect, useState } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 import {
   Bell,
+  Cpu,
   ChevronLeft,
   ChevronRight,
   ChevronsUpDown,
@@ -252,6 +253,14 @@ function SecondaryNavSidebar({ headerHidden }: { headerHidden: boolean }) {
                       白名单管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/models")}
+                    >
+                      <Cpu className="size-4" />
+                      模型配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/strategy/settings/model-concurrency")}
@@ -555,6 +564,12 @@ function LegacyAccordionSidebar({
                   岗位角色配置
                 </DropdownMenuItem>
               )}
+              {isAdmin && (
+                <DropdownMenuItem onClick={() => navigate("/page/workspace/admin/models")}>
+                  <Cpu className="size-4" />
+                  模型配置
+                </DropdownMenuItem>
+              )}
               {isAdmin && (
                 <DropdownMenuItem onClick={() => navigate("/page/strategy/admin/login-whitelist")}>
                   <ShieldCheck className="size-4" />

frontend-web/src/components/wiki/WikiHeader.tsx

@@ -8,6 +8,7 @@ import {
   SlidersHorizontal,
   Upload,
 } from "lucide-react";
+import type { ReactNode } from "react";
 
 import { cn } from "@/lib/utils";
 
@@ -18,7 +19,7 @@ function HeaderButton({
   variant = "outline",
   className,
 }: {
-  icon: React.ReactNode;
+  icon: ReactNode;
   label: string;
   onClick: () => void;
   variant?: "outline" | "primary";
@@ -52,6 +53,7 @@ export function WikiHeader({
   onCreate,
   onManageFolders,
   onManageTemplates,
+  extraActions,
 }: {
   onToggleSidebar: () => void;
   onImportFile: () => void;
@@ -61,6 +63,7 @@ export function WikiHeader({
   onCreate: () => void;
   onManageFolders: () => void;
   onManageTemplates: () => void;
+  extraActions?: ReactNode;
 }) {
   return (
     <header className="flex h-14 shrink-0 items-center justify-between border-b border-slate-100 bg-white px-4 sm:px-6 dark:border-slate-800 dark:bg-slate-900">
@@ -79,6 +82,7 @@ export function WikiHeader({
       </div>
 
       <div className="flex items-center gap-2">
+        {extraActions}
         <HeaderButton
           icon={<Upload className="size-4" />}
           label="导入文件"

frontend-web/src/components/workspace/agents/agent-detail-panel.tsx

@@ -3,6 +3,7 @@
 import {
   BotIcon,
   CheckIcon,
+  DatabaseIcon,
   GlobeIcon,
   InfoIcon,
   Loader2Icon,
@@ -43,6 +44,7 @@ import {
 import { Switch } from "@/components/ui/switch";
 import { Textarea } from "@/components/ui/textarea";
 import { AgentQuestionEditor } from "@/components/workspace/agents/agent-question-editor";
+import { LlmWikiKnowledgeSelector } from "@/components/workspace/llmwiki-knowledge-selector";
 import { AgentRecentChats } from "@/components/workspace/agents/agent-recent-chats";
 import { useArtifactsOptional } from "@/components/workspace/artifacts";
 import { EnabledSkillList } from "@/components/workspace/agents/enabled-skill-list";
@@ -80,6 +82,7 @@ interface AgentDraft {
   templateName: string;
   /** 会商席位「技能识别强化」开关。 */
   seatSkillDirective: boolean;
+  knowledgeBaseIds: string[];
 }
 
 function draftFromAgent(agent: Agent): AgentDraft {
@@ -93,6 +96,7 @@ function draftFromAgent(agent: Agent): AgentDraft {
     featured: agent.featured_order != null,
     templateName: agent.template_name ?? "",
     seatSkillDirective: agent.seat_skill_directive ?? false,
+    knowledgeBaseIds: agent.llmwiki_knowledge_base_ids ?? [],
   };
 }
 
@@ -334,6 +338,11 @@ export function AgentDetailPanel({
       request.template_name = draft.templateName.trim();
     if (draft.seatSkillDirective !== (agent.seat_skill_directive ?? false))
       request.seat_skill_directive = draft.seatSkillDirective;
+    if (
+      JSON.stringify(draft.knowledgeBaseIds) !==
+      JSON.stringify(agent.llmwiki_knowledge_base_ids ?? [])
+    )
+      request.llmwiki_knowledge_base_ids = draft.knowledgeBaseIds;
     if (nextPublished !== agent.published) request.published = nextPublished;
     if (JSON.stringify(draft.skills) !== JSON.stringify(agent.skills ?? []))
       request.skills = draft.skills;
@@ -630,6 +639,13 @@ export function AgentDetailPanel({
           </div>
         )}
 
+        {!editing && (agent.llmwiki_knowledge_base_ids?.length ?? 0) > 0 && (
+          <div className="text-muted-foreground mt-2 flex items-center gap-1 text-xs">
+            <DatabaseIcon className="size-3 shrink-0" />
+            LLMWiki 知识库：{agent.llmwiki_knowledge_base_ids?.length ?? 0} 个
+          </div>
+        )}
+
         {/* Publish / featured toggles — only meaningful in edit mode. */}
         {editing && draft && (
           <div className="mt-3 space-y-2">
@@ -647,6 +663,14 @@ export function AgentDetailPanel({
                 配置后，对话生成的 Markdown 文件可一键发布到知识入库接口。
               </p>
             </div>
+            <LlmWikiKnowledgeSelector
+              source="all"
+              value={draft.knowledgeBaseIds}
+              onChange={(knowledgeBaseIds) =>
+                setDraft({ ...draft, knowledgeBaseIds })
+              }
+              variant="panel"
+            />
             <div className="bg-background/60 flex items-center justify-between rounded-lg border px-3 py-2">
               <div className="pr-3">
                 <p className="text-sm font-medium">会商技能识别强化</p>

frontend-web/src/components/workspace/chats/chat-box.tsx

@@ -15,6 +15,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { apiFetch } from "@/core/api";
 import { getBackendBaseURL } from "@/core/config";
 import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
+import { isSingleRoundRagMessage } from "@/core/threads/use-single-round-rag";
 import { useSkills } from "@/core/skills/hooks";
 import type { SkillDisplayConfig } from "@/core/skills/type";
 import {
@@ -92,6 +93,13 @@ const ChatBox: React.FC<{
   const [settings] = useLocalSettings();
   const ragModeEnabled =
     settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+  // Frontend single-round RAG writes its own source tool message, so it should
+  // use the same reference panel without changing the user's global RAG mode.
+  const hasSingleRoundRag = useMemo(
+    () => (thread.values.messages ?? []).some(isSingleRoundRagMessage),
+    [thread.values.messages],
+  );
+  const referencesEnabled = ragModeEnabled || hasSingleRoundRag;
   const { skills } = useSkills();
 
   const {
@@ -106,11 +114,11 @@ const ChatBox: React.FC<{
 
   const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
   const skillDisplayMap = useMemo(
-    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [ragModeEnabled, skills],
+    () => (referencesEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [referencesEnabled, skills],
   );
   const fallbackReferenceBatches = useMemo(() => {
-    if (!ragModeEnabled) {
+    if (!referencesEnabled) {
       return [];
     }
     return buildTurnReferenceBatches(
@@ -118,9 +126,9 @@ const ChatBox: React.FC<{
       skillDisplayMap,
       thread.isLoading,
     );
-  }, [ragModeEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
+  }, [referencesEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
   useEffect(() => {
-    if (!ragModeEnabled) {
+    if (!referencesEnabled) {
       setBackendReferenceBatches([]);
       return;
     }
@@ -156,7 +164,7 @@ const ChatBox: React.FC<{
         }
       });
     return () => controller.abort();
-  }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]);
+  }, [referencesEnabled, thread.isLoading, threadId, thread.values.messages]);
   const adaptedBackendReferenceBatches = useMemo(
     () =>
       adaptBackendReferenceBatches(
@@ -175,7 +183,7 @@ const ChatBox: React.FC<{
     [adaptedBackendReferenceBatches, fallbackReferenceBatches],
   );
   useEffect(() => {
-    if (!ragModeEnabled) {
+    if (!referencesEnabled) {
       return;
     }
     const signature = JSON.stringify({
@@ -202,7 +210,7 @@ const ChatBox: React.FC<{
       fallbackBatches: debugReferenceBatches(fallbackReferenceBatches),
       finalBatches: debugReferenceBatches(referenceBatches),
     });
-  }, [adaptedBackendReferenceBatches, backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
+  }, [adaptedBackendReferenceBatches, backendReferenceBatches, fallbackReferenceBatches, referencesEnabled, referenceBatches, threadId]);
   const latestReferenceBatch =
     referenceBatches.length > 0
       ? referenceBatches[referenceBatches.length - 1]!
@@ -213,7 +221,7 @@ const ChatBox: React.FC<{
   const referenceSources = activeReferenceBatch?.sources ?? [];
   const hasCitationReferences = referenceSources.length > 0;
   useEffect(() => {
-    if (!ragModeEnabled || !activeReferenceBatch) {
+    if (!referencesEnabled || !activeReferenceBatch) {
       return;
     }
     logReferenceDebug("frontend-active-reference-batch-payload", threadId, {
@@ -222,7 +230,7 @@ const ChatBox: React.FC<{
       sourceCount: activeReferenceBatch.sources.length,
       sources: activeReferenceBatch.sources.map(debugReferenceSource),
     });
-  }, [activeReferenceBatch, ragModeEnabled, threadId]);
+  }, [activeReferenceBatch, referencesEnabled, threadId]);
   useEffect(() => {
     if (hasCitationReferences) {
       setReferencesOpen(true);

frontend-web/src/components/workspace/input-box.tsx

@@ -22,9 +22,10 @@ import {
   useEffect,
   useMemo,
   useRef,
-  useState,
-  type ComponentProps,
-} from "react";
+  useState,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
 
 import {
   PromptInput,
@@ -64,6 +65,7 @@ import { getBackendBaseURL } from "@/core/config";
 import { useI18n } from "@/core/i18n/hooks";
 import { isHiddenFromUIMessage } from "@/core/messages/utils";
 import { useModels } from "@/core/models/hooks";
+import type { Model } from "@/core/models/types";
 import type { AgentThreadContext } from "@/core/threads";
 import { textOfMessage } from "@/core/threads/utils";
 import { desensitize } from "@/lib/desensitize";
@@ -132,9 +134,11 @@ export function InputBox({
   onFollowupsVisibilityChange,
   onSubmit,
   onStop,
-  promptPrefix,
-  agentSelector,
-  assistantId,
+  promptPrefix,
+  agentSelector,
+  knowledgeSelector,
+  extraModels = [],
+  assistantId,
   hideAdminRecommendedQuestions,
   compact,
   ...props
@@ -190,16 +194,25 @@ export function InputBox({
    * homepage (``ChatPage``) passes this; ``AgentChatPage`` omits it because the
    * thread is already bound to one agent.
    */
-  agentSelector?: {
-    selectedAgentId: string | null;
-    onAgentChange: (agentId: string | null) => void;
-  };
-}) {
+  agentSelector?: {
+    selectedAgentId: string | null;
+    onAgentChange: (agentId: string | null) => void;
+  };
+  /** WeKnora-style knowledge-space picker rendered inside the composer toolbar. */
+  knowledgeSelector?: ReactNode;
+  /** Page-scoped model choices implemented outside the DeerFlow model API. */
+  extraModels?: Model[];
+}) {
   const { t } = useI18n();
   const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
-  const [modelDialogOpen, setModelDialogOpen] = useState(false);
-  const { models } = useModels();
+  const [modelDialogOpen, setModelDialogOpen] = useState(false);
+  const { models } = useModels();
+  const singleRoundRagActive =
+    context.execution_profile === "single_round_rag";
+  const modelOptions = useMemo(() => {
+    return singleRoundRagActive ? extraModels : models;
+  }, [extraModels, models, singleRoundRagActive]);
   const { thread, isMock } = useThread();
   const { textInput } = usePromptInputController();
   const promptRootRef = useRef<HTMLDivElement | null>(null);
@@ -223,34 +236,40 @@ export function InputBox({
     recommendedQuestions.length > 0;
 
   useEffect(() => {
-    if (models.length === 0) {
-      return;
-    }
-    const currentModel = models.find((m) => m.name === context.model_name);
-    const fallbackModel = currentModel ?? models[0]!;
+    if (modelOptions.length === 0) {
+      return;
+    }
+    const currentModel = modelOptions.find((m) => m.name === context.model_name);
+    const fallbackModel = currentModel ?? modelOptions[0]!;
     const supportsThinking = fallbackModel.supports_thinking ?? false;
     const nextModelName = fallbackModel.name;
     const nextMode = getResolvedMode(context.mode, supportsThinking);
 
-    if (context.model_name === nextModelName && context.mode === nextMode) {
-      return;
-    }
+    if (
+      context.model_name === nextModelName &&
+      context.mode === nextMode &&
+      context.execution_profile === fallbackModel.execution_profile
+    ) {
+      return;
+    }
 
     onContextChange?.({
-      ...context,
-      model_name: nextModelName,
-      mode: nextMode,
-    });
-  }, [context, models, onContextChange]);
+      ...context,
+      model_name: nextModelName,
+      mode: nextMode,
+      execution_profile: fallbackModel.execution_profile,
+    });
+  }, [context, modelOptions, onContextChange]);
+
+  const selectedModel = useMemo(() => {
+    if (modelOptions.length === 0) {
+      return undefined;
+    }
+    return modelOptions.find((m) => m.name === context.model_name) ?? modelOptions[0];
+  }, [context.model_name, modelOptions]);
 
-  const selectedModel = useMemo(() => {
-    if (models.length === 0) {
-      return undefined;
-    }
-    return models.find((m) => m.name === context.model_name) ?? models[0];
-  }, [context.model_name, models]);
-
-  const resolvedModelName = selectedModel?.name;
+  const resolvedModelName = selectedModel?.name;
+  const selectedSingleRoundRag = singleRoundRagActive;
 
   const supportThinking = useMemo(
     () => selectedModel?.supports_thinking ?? false,
@@ -264,38 +283,65 @@ export function InputBox({
 
   const handleModelSelect = useCallback(
     (model_name: string) => {
-      const model = models.find((m) => m.name === model_name);
+      const model = modelOptions.find((m) => m.name === model_name);
       if (!model) {
         return;
       }
       onContextChange?.({
         ...context,
         model_name,
-        mode: getResolvedMode(context.mode, model.supports_thinking ?? false),
-        reasoning_effort: context.reasoning_effort,
-      });
-      setModelDialogOpen(false);
-    },
-    [onContextChange, context, models],
+        mode: getResolvedMode(context.mode, model.supports_thinking ?? false),
+        reasoning_effort: context.reasoning_effort,
+        execution_profile: model.execution_profile,
+      });
+      setModelDialogOpen(false);
+    },
+    [onContextChange, context, modelOptions],
   );
 
-  const handleModeSelect = useCallback(
-    (mode: InputMode) => {
-      onContextChange?.({
-        ...context,
-        mode: getResolvedMode(mode, supportThinking),
-        reasoning_effort:
-          mode === "ultra"
-            ? "high"
+  const handleModeSelect = useCallback(
+    (mode: InputMode) => {
+      const ordinaryModel =
+        models.find((model) => model.name === context.model_name) ?? models[0];
+      onContextChange?.({
+        ...context,
+        model_name: ordinaryModel?.name ?? context.model_name,
+        mode: getResolvedMode(
+          mode,
+          ordinaryModel?.supports_thinking ?? supportThinking,
+        ),
+        reasoning_effort:
+          mode === "ultra"
+            ? "high"
             : mode === "pro"
               ? "medium"
               : mode === "thinking"
-                ? "low"
-                : "minimal",
-      });
-    },
-    [onContextChange, context, supportThinking],
-  );
+                ? "low"
+                : "minimal",
+        execution_profile: undefined,
+      });
+    },
+    [onContextChange, context, models, supportThinking],
+  );
+
+  const handleSingleRoundRagSelect = useCallback(() => {
+    const ragModel =
+      extraModels.find((model) => model.name === context.model_name) ??
+      extraModels[0];
+    if (!ragModel) {
+      return;
+    }
+
+    onContextChange?.({
+      ...context,
+      model_name: ragModel.name,
+      mode: getResolvedMode(
+        context.mode,
+        ragModel.supports_thinking ?? false,
+      ),
+      execution_profile: "single_round_rag",
+    });
+  }, [context, extraModels, onContextChange]);
 
   const handleReasoningEffortSelect = useCallback(
     (effort: "minimal" | "low" | "medium" | "high") => {
@@ -361,10 +407,11 @@ export function InputBox({
         onContextChange?.({
           ...context,
           model_name: resolvedModelName,
-          mode: getResolvedMode(
-            context.mode,
-            selectedModel?.supports_thinking ?? false,
-          ),
+          mode: getResolvedMode(
+            context.mode,
+            selectedModel?.supports_thinking ?? false,
+          ),
+          execution_profile: selectedModel?.execution_profile,
         });
         setTimeout(() => onSubmit?.(message), 0);
         return;
@@ -379,7 +426,8 @@ export function InputBox({
       onStop,
       resolvedModelName,
       ragModeEnabled,
-      selectedModel?.supports_thinking,
+      selectedModel?.supports_thinking,
+      selectedModel?.execution_profile,
       status,
       threadId,
     ],
@@ -437,8 +485,9 @@ export function InputBox({
   }, [pendingSuggestion, requestFormSubmit, textInput]);
 
   const showFollowups =
-    !disabled &&
-    !isNewThread &&
+    !disabled &&
+    !isNewThread &&
+    !selectedSingleRoundRag &&
     !followupsHidden &&
     (followupsLoading || followups.length > 0);
 
@@ -464,7 +513,7 @@ export function InputBox({
       return;
     }
 
-    if (disabled || isMock) {
+    if (disabled || isMock || selectedSingleRoundRag) {
       return;
     }
 
@@ -526,7 +575,7 @@ export function InputBox({
       });
 
     return () => controller.abort();
-  }, [context.model_name, disabled, isMock, status, thread.messages, threadId]);
+  }, [context.model_name, disabled, isMock, selectedSingleRoundRag, status, thread.messages, threadId]);
 
   return (
     <div ref={promptRootRef} className="relative flex flex-col gap-6">
@@ -782,54 +831,64 @@ export function InputBox({
               </PromptInputButton>
             </Tooltip>
             <PromptInputActionMenu>
-              <ModeHoverGuide
-                mode={
+              <ModeHoverGuide
+                mode={
                   context.mode === "flash" ||
                   context.mode === "thinking" ||
                   context.mode === "pro" ||
                   context.mode === "ultra"
-                    ? context.mode
-                    : "flash"
-                }
-              >
+                    ? context.mode
+                    : "flash"
+                }
+                tooltipContent={
+                  selectedSingleRoundRag
+                    ? "单轮 RAG 问答：基于知识库检索生成答案，并展示参考资料"
+                    : undefined
+                }
+              >
                 <PromptInputActionMenuTrigger
                   className={cn(
                     "gap-1.5! rounded-full border-0 bg-transparent px-3! text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
                     compact && "rounded-lg border px-2.5! py-1! text-[11px] font-medium",
-                    compact &&
-                      (context.mode === "thinking"
-                        ? "border-indigo-200 bg-indigo-50/60 text-indigo-700 hover:bg-indigo-100 dark:border-indigo-700 dark:bg-indigo-950/40 dark:text-indigo-200"
+                    compact &&
+                      (selectedSingleRoundRag
+                        ? "border-emerald-200 bg-emerald-50/60 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
+                        : context.mode === "thinking"
+                        ? "border-indigo-200 bg-indigo-50/60 text-indigo-700 hover:bg-indigo-100 dark:border-indigo-700 dark:bg-indigo-950/40 dark:text-indigo-200"
                         : context.mode === "pro"
                           ? "border-violet-200 bg-violet-50/60 text-violet-700 hover:bg-violet-100 dark:border-violet-700 dark:bg-violet-950/40 dark:text-violet-200"
                           : context.mode === "ultra"
                             ? "border-amber-200 bg-amber-50/60 text-amber-700 hover:bg-amber-100 dark:border-amber-700 dark:bg-amber-950/40 dark:text-amber-200"
                             : "border-transparent bg-muted/40 hover:bg-muted hover:text-foreground"),
                   )}
-                >
-                  <div>
-                    {context.mode === "flash" && <ZapIcon className="size-3" />}
-                    {context.mode === "thinking" && (
-                      <LightbulbIcon className="size-3" />
-                    )}
-                    {context.mode === "pro" && (
-                      <GraduationCapIcon className="size-3" />
-                    )}
-                    {context.mode === "ultra" && (
-                      <RocketIcon className="size-3 text-[#dabb5e]" />
-                    )}
-                  </div>
+                  >
+                    <div>
+                    {selectedSingleRoundRag ? (
+                      <BookMarkedIcon className="size-3" />
+                    ) : context.mode === "flash" ? (
+                      <ZapIcon className="size-3" />
+                    ) : context.mode === "thinking" ? (
+                      <LightbulbIcon className="size-3" />
+                    ) : context.mode === "pro" ? (
+                      <GraduationCapIcon className="size-3" />
+                    ) : context.mode === "ultra" ? (
+                      <RocketIcon className="size-3 text-[#dabb5e]" />
+                    ) : null}
+                    </div>
                   <div
                     className={cn(
                       "text-xs font-normal",
                       context.mode === "ultra" ? "golden-text" : "",
                     )}
                   >
-                    {(context.mode === "flash" && t.inputBox.flashMode) ||
-                      (context.mode === "thinking" &&
-                        t.inputBox.reasoningMode) ||
-                      (context.mode === "pro" && t.inputBox.proMode) ||
-                      (context.mode === "ultra" && t.inputBox.ultraMode)}
-                  </div>
+                    {selectedSingleRoundRag
+                      ? "单轮 RAG"
+                      : (context.mode === "flash" && t.inputBox.flashMode) ||
+                      (context.mode === "thinking" &&
+                        t.inputBox.reasoningMode) ||
+                      (context.mode === "pro" && t.inputBox.proMode) ||
+                      (context.mode === "ultra" && t.inputBox.ultraMode)}
+                  </div>
                 </PromptInputActionMenuTrigger>
               </ModeHoverGuide>
               <PromptInputActionMenuContent className="w-80">
@@ -838,11 +897,11 @@ export function InputBox({
                     {t.inputBox.mode}
                   </DropdownMenuLabel>
                   <PromptInputActionMenu>
-                    <PromptInputActionMenuItem
-                      className={cn(
-                        context.mode === "flash"
-                          ? "text-accent-foreground"
-                          : "text-muted-foreground/65",
+                    <PromptInputActionMenuItem
+                      className={cn(
+                        !selectedSingleRoundRag && context.mode === "flash"
+                          ? "text-accent-foreground"
+                          : "text-muted-foreground/65",
                       )}
                       onSelect={() => handleModeSelect("flash")}
                     >
@@ -850,9 +909,9 @@ export function InputBox({
                         <div className="flex items-center gap-1 font-bold">
                           <ZapIcon
                             className={cn(
-                              "mr-2 size-4",
-                              context.mode === "flash" &&
-                                "text-accent-foreground",
+                              "mr-2 size-4",
+                              !selectedSingleRoundRag && context.mode === "flash" &&
+                                "text-accent-foreground",
                             )}
                           />
                           {t.inputBox.flashMode}
@@ -861,7 +920,7 @@ export function InputBox({
                           {t.inputBox.flashModeDescription}
                         </div>
                       </div>
-                      {context.mode === "flash" ? (
+                      {!selectedSingleRoundRag && context.mode === "flash" ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
@@ -869,9 +928,9 @@ export function InputBox({
                     </PromptInputActionMenuItem>
                     {supportThinking && (
                       <PromptInputActionMenuItem
-                        className={cn(
-                          context.mode === "thinking"
-                            ? "text-accent-foreground"
+                        className={cn(
+                          !selectedSingleRoundRag && context.mode === "thinking"
+                            ? "text-accent-foreground"
                             : "text-muted-foreground/65",
                         )}
                         onSelect={() => handleModeSelect("thinking")}
@@ -880,9 +939,9 @@ export function InputBox({
                           <div className="flex items-center gap-1 font-bold">
                             <LightbulbIcon
                               className={cn(
-                                "mr-2 size-4",
-                                context.mode === "thinking" &&
-                                  "text-accent-foreground",
+                                "mr-2 size-4",
+                                !selectedSingleRoundRag && context.mode === "thinking" &&
+                                  "text-accent-foreground",
                               )}
                             />
                             {t.inputBox.reasoningMode}
@@ -891,7 +950,7 @@ export function InputBox({
                             {t.inputBox.reasoningModeDescription}
                           </div>
                         </div>
-                        {context.mode === "thinking" ? (
+                        {!selectedSingleRoundRag && context.mode === "thinking" ? (
                           <CheckIcon className="ml-auto size-4" />
                         ) : (
                           <div className="ml-auto size-4" />
@@ -899,8 +958,8 @@ export function InputBox({
                       </PromptInputActionMenuItem>
                     )}
                     <PromptInputActionMenuItem
-                      className={cn(
-                        context.mode === "pro"
+                      className={cn(
+                        !selectedSingleRoundRag && context.mode === "pro"
                           ? "text-accent-foreground"
                           : "text-muted-foreground/65",
                       )}
@@ -910,8 +969,8 @@ export function InputBox({
                         <div className="flex items-center gap-1 font-bold">
                           <GraduationCapIcon
                             className={cn(
-                              "mr-2 size-4",
-                              context.mode === "pro" &&
+                              "mr-2 size-4",
+                              !selectedSingleRoundRag && context.mode === "pro" &&
                                 "text-accent-foreground",
                             )}
                           />
@@ -921,15 +980,15 @@ export function InputBox({
                           {t.inputBox.proModeDescription}
                         </div>
                       </div>
-                      {context.mode === "pro" ? (
+                      {!selectedSingleRoundRag && context.mode === "pro" ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
                       )}
                     </PromptInputActionMenuItem>
                     <PromptInputActionMenuItem
-                      className={cn(
-                        context.mode === "ultra"
+                      className={cn(
+                        !selectedSingleRoundRag && context.mode === "ultra"
                           ? "text-accent-foreground"
                           : "text-muted-foreground/65",
                       )}
@@ -939,13 +998,17 @@ export function InputBox({
                         <div className="flex items-center gap-1 font-bold">
                           <RocketIcon
                             className={cn(
-                              "mr-2 size-4",
-                              context.mode === "ultra" && "text-[#dabb5e]",
+                              "mr-2 size-4",
+                              !selectedSingleRoundRag &&
+                                context.mode === "ultra" &&
+                                "text-[#dabb5e]",
                             )}
                           />
                           <div
                             className={cn(
-                              context.mode === "ultra" && "golden-text",
+                              !selectedSingleRoundRag &&
+                                context.mode === "ultra" &&
+                                "golden-text",
                             )}
                           >
                             {t.inputBox.ultraMode}
@@ -955,13 +1018,46 @@ export function InputBox({
                           {t.inputBox.ultraModeDescription}
                         </div>
                       </div>
-                      {context.mode === "ultra" ? (
+                      {!selectedSingleRoundRag && context.mode === "ultra" ? (
                         <CheckIcon className="ml-auto size-4" />
                       ) : (
                         <div className="ml-auto size-4" />
                       )}
-                    </PromptInputActionMenuItem>
-                  </PromptInputActionMenu>
+                    </PromptInputActionMenuItem>
+                    {extraModels.length > 0 && (
+                      <>
+                        <DropdownMenuSeparator className="my-2" />
+                        <PromptInputActionMenuItem
+                          className={cn(
+                            selectedSingleRoundRag
+                              ? "bg-emerald-50 text-emerald-800 hover:bg-emerald-100 focus:bg-emerald-100 dark:bg-emerald-950/40 dark:text-emerald-200 dark:hover:bg-emerald-950/60 dark:focus:bg-emerald-950/60"
+                              : "text-muted-foreground/65",
+                          )}
+                          onSelect={handleSingleRoundRagSelect}
+                        >
+                          <div className="flex flex-col gap-2">
+                            <div className="flex items-center gap-1 font-bold">
+                              <BookMarkedIcon
+                                className={cn(
+                                  "mr-2 size-4",
+                                  selectedSingleRoundRag && "text-emerald-700 dark:text-emerald-200",
+                                )}
+                              />
+                              单轮 RAG 问答
+                            </div>
+                            <div className="pl-7 text-xs">
+                              基于知识库检索生成答案，并展示思考内容与参考资料
+                            </div>
+                          </div>
+                          {selectedSingleRoundRag ? (
+                            <CheckIcon className="ml-auto size-4" />
+                          ) : (
+                            <div className="ml-auto size-4" />
+                          )}
+                        </PromptInputActionMenuItem>
+                      </>
+                    )}
+                  </PromptInputActionMenu>
                 </DropdownMenuGroup>
               </PromptInputActionMenuContent>
             </PromptInputActionMenu>
@@ -1081,9 +1177,10 @@ export function InputBox({
                 </PromptInputActionMenuContent>
               </PromptInputActionMenu>
             )}
-          </PromptInputTools>
-          <PromptInputTools className={cn("gap-1.5", compact && "gap-2")}>
-            {agentSelector && (
+          </PromptInputTools>
+          <PromptInputTools className={cn("gap-1.5", compact && "gap-2")}>
+            {knowledgeSelector}
+            {agentSelector && (
               <AgentSelector
                 selectedAgentId={agentSelector.selectedAgentId}
                 onAgentChange={agentSelector.onAgentChange}
@@ -1146,7 +1243,7 @@ export function InputBox({
               <ModelSelectorContent>
                 <ModelSelectorInput placeholder={t.inputBox.searchModels} />
                 <ModelSelectorList>
-                  {models.map((m) => (
+                  {modelOptions.map((m) => (
                     <ModelSelectorItem
                       key={m.name}
                       value={m.name}
@@ -1154,9 +1251,11 @@ export function InputBox({
                     >
                       <div className="flex min-w-0 flex-1 flex-col">
                         <ModelSelectorName>{m.display_name}</ModelSelectorName>
-                        <span className="text-muted-foreground truncate text-[10px]">
-                          {m.model}
-                        </span>
+                        <span className="text-muted-foreground truncate text-[10px]">
+                          {selectedSingleRoundRag
+                            ? `单轮知识库问答 · ${m.name}`
+                            : m.model}
+                        </span>
                       </div>
                       {m.name === context.model_name ? (
                         <CheckIcon className="ml-auto size-4" />
@@ -1164,8 +1263,8 @@ export function InputBox({
                         <div className="ml-auto size-4" />
                       )}
                     </ModelSelectorItem>
-                  ))}
-                </ModelSelectorList>
+                  ))}
+                </ModelSelectorList>
               </ModelSelectorContent>
             </ModelSelector>
             <PromptInputSubmit

frontend-web/src/components/workspace/llmwiki-knowledge-selector.tsx

@@ -0,0 +1,353 @@
+"use client";
+
+import {
+  Check,
+  Database,
+  Folder,
+  Globe2,
+  Loader2,
+  Search,
+} from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Input } from "@/components/ui/input";
+import { cn } from "@/lib/utils";
+import {
+  type LlmWikiKnowledgeBase,
+  useAgentLlmWikiKnowledgeBases,
+  useLlmWikiKnowledgeBases,
+  useLlmWikiRuntime,
+} from "@/strategy-components/api/llmwiki";
+
+type SelectorSource = "all" | "agent";
+type SelectorVariant = "popover" | "panel";
+
+function groupRows(rows: LlmWikiKnowledgeBase[]) {
+  return [
+    {
+      key: "personal",
+      label: "我的知识空间",
+      rows: rows.filter((item) => item.publication_status !== "published" || item.is_owner),
+    },
+    {
+      key: "public",
+      label: "公共知识空间",
+      rows: rows.filter((item) => item.publication_status === "published" && !item.is_owner),
+    },
+  ].filter((group) => group.rows.length > 0);
+}
+
+function SpaceIcon({ item }: { item: LlmWikiKnowledgeBase }) {
+  return (
+    <span
+      className={cn(
+        "flex size-7 shrink-0 items-center justify-center rounded-md",
+        item.publication_status === "published"
+          ? "bg-emerald-500/10 text-emerald-600 dark:text-emerald-400"
+          : "bg-primary/10 text-primary",
+      )}
+    >
+      {item.publication_status === "published" ? (
+        <Globe2 className="size-3.5" />
+      ) : (
+        <Folder className="size-3.5" />
+      )}
+    </span>
+  );
+}
+
+function SelectionContent({
+  rows,
+  value,
+  onChange,
+  search,
+  onSearchChange,
+  loading,
+  error,
+  source,
+  variant,
+}: {
+  rows: LlmWikiKnowledgeBase[];
+  value: string[];
+  onChange: (value: string[]) => void;
+  search: string;
+  onSearchChange: (value: string) => void;
+  loading: boolean;
+  error: unknown;
+  source: SelectorSource;
+  variant: SelectorVariant;
+}) {
+  const selected = useMemo(() => new Set(value), [value]);
+  const filtered = useMemo(() => {
+    const query = search.trim().toLocaleLowerCase();
+    if (!query) return rows;
+    return rows.filter((item) =>
+      `${item.name} ${item.description}`.toLocaleLowerCase().includes(query),
+    );
+  }, [rows, search]);
+  const groups = useMemo(() => groupRows(filtered), [filtered]);
+  const toggle = (id: string) => {
+    onChange(selected.has(id) ? value.filter((item) => item !== id) : [...value, id]);
+  };
+
+  return (
+    <>
+      <div className="border-b p-2.5">
+        <div className="relative">
+          <Search className="pointer-events-none absolute left-2.5 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            value={search}
+            onChange={(event) => onSearchChange(event.target.value)}
+            onKeyDown={(event) => event.stopPropagation()}
+            placeholder="搜索知识空间"
+            className="h-8 bg-muted/40 pl-8 text-xs"
+          />
+        </div>
+      </div>
+
+      <div className={cn("overflow-y-auto p-1.5", variant === "popover" ? "max-h-64" : "max-h-80")}>
+        {loading ? (
+          <div className="flex h-28 items-center justify-center text-xs text-muted-foreground">
+            <Loader2 className="mr-2 size-4 animate-spin" />正在读取知识空间
+          </div>
+        ) : error ? (
+          <div className="m-2 rounded-lg border border-destructive/30 bg-destructive/5 p-3 text-xs text-destructive">
+            {error instanceof Error ? error.message : "知识空间读取失败"}
+          </div>
+        ) : groups.length === 0 ? (
+          <div className="flex h-28 items-center justify-center px-4 text-center text-xs text-muted-foreground">
+            {search
+              ? "没有匹配的知识空间"
+              : source === "agent"
+                ? "该智能体尚未绑定可用知识空间"
+                : "当前账号暂无可用知识空间"}
+          </div>
+        ) : (
+          groups.map((group, groupIndex) => (
+            <div key={group.key}>
+              {groupIndex > 0 && (
+                variant === "popover"
+                  ? <DropdownMenuSeparator className="my-1.5" />
+                  : <div className="my-1.5 border-t" />
+              )}
+              {variant === "popover" ? (
+                <DropdownMenuLabel className="flex items-center gap-1.5 px-2 py-1 text-[11px] font-semibold text-muted-foreground">
+                  {group.key === "personal" ? <Folder className="size-3" /> : <Globe2 className="size-3" />}{group.label}
+                </DropdownMenuLabel>
+              ) : (
+                <div className="flex items-center gap-1.5 px-2 py-1 text-[11px] font-semibold text-muted-foreground">
+                  {group.key === "personal" ? <Folder className="size-3" /> : <Globe2 className="size-3" />}{group.label}
+                </div>
+              )}
+              {group.rows.map((item) => {
+                const rowContent = (
+                  <>
+                    <SpaceIcon item={item} />
+                    <div className="min-w-0 flex-1">
+                      <div className="truncate text-xs font-medium">{item.name}</div>
+                      <div className="mt-0.5 truncate text-[10px] text-muted-foreground">
+                        {item.type === "faq" ? "FAQ" : "文档库"} · {item.knowledge_count ?? 0} 项知识
+                      </div>
+                    </div>
+                    {item.publication_status === "published" && (
+                      <Badge variant="outline" className="h-4 px-1 text-[9px]">公共</Badge>
+                    )}
+                  </>
+                );
+                return variant === "popover" ? (
+                  <DropdownMenuCheckboxItem
+                    key={item.id}
+                    checked={selected.has(item.id)}
+                    onCheckedChange={() => toggle(item.id)}
+                    onSelect={(event) => event.preventDefault()}
+                    className={cn(
+                      "my-0.5 min-h-10 rounded-md py-1.5 pr-2 pl-7",
+                      selected.has(item.id) && "bg-primary/8 focus:bg-primary/12",
+                    )}
+                  >
+                    {rowContent}
+                  </DropdownMenuCheckboxItem>
+                ) : (
+                  <button
+                    key={item.id}
+                    type="button"
+                    role="checkbox"
+                    aria-checked={selected.has(item.id)}
+                    onClick={() => toggle(item.id)}
+                    className={cn(
+                      "my-0.5 flex min-h-11 w-full items-center gap-2 rounded-md px-2 py-1.5 text-left outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-primary",
+                      selected.has(item.id) && "bg-primary/8",
+                    )}
+                  >
+                    <span className={cn(
+                      "flex size-4 shrink-0 items-center justify-center rounded border",
+                      selected.has(item.id) && "border-primary bg-primary text-primary-foreground",
+                    )}>
+                      {selected.has(item.id) && <Check className="size-3" />}
+                    </span>
+                    {rowContent}
+                  </button>
+                );
+              })}
+            </div>
+          ))
+        )}
+      </div>
+
+      <div className="flex items-center justify-between gap-2 border-t bg-muted/20 px-2.5 py-2">
+        <span className="text-[11px] text-muted-foreground">已选择 {value.length} 个</span>
+        <div className="flex items-center gap-1">
+          <Button type="button" variant="ghost" size="sm" className="h-7 px-2 text-xs" onClick={() => onChange(filtered.map((item) => item.id))}>
+            全选
+          </Button>
+          <Button type="button" variant="ghost" size="sm" className="h-7 px-2 text-xs" onClick={() => onChange([])}>
+            清空
+          </Button>
+        </div>
+      </div>
+    </>
+  );
+}
+
+export function LlmWikiKnowledgeSelector({
+  value,
+  onChange,
+  source = "all",
+  agentId,
+  autoSelectAll = false,
+  disabled = false,
+  className,
+  label = "知识空间",
+  variant = "popover",
+}: {
+  value: string[];
+  onChange: (value: string[]) => void;
+  source?: SelectorSource;
+  agentId?: string | null;
+  autoSelectAll?: boolean;
+  disabled?: boolean;
+  className?: string;
+  label?: string;
+  variant?: SelectorVariant;
+}) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const runtime = useLlmWikiRuntime();
+  const all = useLlmWikiKnowledgeBases(
+    "all",
+    runtime.data?.provider === "weknora",
+  );
+  const agent = useAgentLlmWikiKnowledgeBases(
+    agentId,
+    runtime.data?.provider === "weknora" && source === "agent" && !!agentId,
+  );
+  const rows = all.data ?? [];
+  const defaultIds = useMemo(() => {
+    if (source !== "agent") {
+      return rows.map((item) => item.id);
+    }
+    return (agent.data ?? []).map((item) => item.id);
+  }, [agent.data, rows, source]);
+  const loading = all.isLoading || (source === "agent" && !!agentId && agent.isLoading);
+  const error = all.error ?? (source === "agent" ? agent.error : null);
+  const availableIds = useMemo(() => new Set(rows.map((item) => item.id)), [rows]);
+  const initializationKey = `${source}:${agentId ?? "all"}:${defaultIds.join(",")}`;
+  const initialized = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!all.data || (source === "agent" && agentId && !agent.data) || initialized.current === initializationKey) return;
+    initialized.current = initializationKey;
+    const valid = value.filter((id) => availableIds.has(id));
+    const next = autoSelectAll && valid.length === 0 && defaultIds.length > 0
+      ? defaultIds.filter((id) => availableIds.has(id))
+      : valid;
+    if (next.length !== value.length || next.some((id, index) => id !== value[index])) {
+      onChange(next);
+    }
+  }, [agent.data, agentId, all.data, autoSelectAll, availableIds, defaultIds, initializationKey, onChange, source, value]);
+
+  useEffect(() => {
+    if (!open) setSearch("");
+  }, [open]);
+
+  if (runtime.isError || runtime.data?.provider !== "weknora") return null;
+
+  const content = (
+    <SelectionContent
+      rows={rows}
+      value={value}
+      onChange={onChange}
+      search={search}
+      onSearchChange={setSearch}
+      loading={loading}
+      error={error}
+      source={source}
+      variant={variant}
+    />
+  );
+
+  if (variant === "panel") {
+    return (
+      <div className={cn("overflow-hidden rounded-xl border bg-background shadow-sm", className)}>
+        <div className="flex items-start justify-between gap-4 border-b px-4 py-3">
+          <div>
+            <div className="flex items-center gap-2 text-sm font-semibold">
+              <Database className="size-4 text-primary" />绑定知识空间
+            </div>
+            <p className="mt-1 text-xs text-muted-foreground">
+              新建该智能体对话时，只能从已绑定空间中选择本次检索范围。
+            </p>
+          </div>
+          <Badge variant="secondary" className="shrink-0">{value.length} 个</Badge>
+        </div>
+        {content}
+      </div>
+    );
+  }
+
+  const selectedName = value.length === 1
+    ? rows.find((item) => item.id === value[0])?.name
+    : null;
+
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          className={cn(
+            "h-8 max-w-52 gap-1.5 rounded-full border-0 bg-transparent px-2.5 text-muted-foreground shadow-none hover:bg-muted/70 hover:text-foreground",
+            value.length > 0 && "bg-primary/8 text-primary hover:bg-primary/12 hover:text-primary",
+            className,
+          )}
+          disabled={disabled || loading}
+        >
+          {loading ? <Loader2 className="size-3.5 animate-spin" /> : <Database className="size-3.5" />}
+          <span className="truncate text-xs font-normal">{selectedName || label}</span>
+          {value.length > 0 && (
+            <span className="flex size-4 items-center justify-center rounded-full bg-primary text-[9px] font-semibold text-primary-foreground">
+              {value.length}
+            </span>
+          )}
+          {value.length > 0 && value.length === rows.length && <Check className="size-3" />}
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" sideOffset={8} className="w-80 overflow-hidden rounded-xl p-0 shadow-xl">
+        {content}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
+
+export default LlmWikiKnowledgeSelector;

frontend-web/src/components/workspace/messages/message-list.tsx

@@ -33,7 +33,8 @@ import {
 } from "@/core/skill-display/runtime";
 import type { Subtask } from "@/core/tasks";
 import { useUpdateSubtask } from "@/core/tasks/context";
-import type { AgentThreadState } from "@/core/threads";
+import type { AgentThreadState } from "@/core/threads";
+import { isSingleRoundRagMessage } from "@/core/threads/use-single-round-rag";
 import { cn } from "@/lib/utils";
 import { resolveAllowMultiple } from "@/roundtable-planning/lib/clarification";
 
@@ -235,12 +236,17 @@ export function MessageList({
   }, [messages, askTimes]);
 
   const [settings] = useLocalSettings();
-  const ragModeEnabled =
-    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
-  const { skills } = useSkills();
-  const skillDisplayMap = useMemo(
-    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [ragModeEnabled, skills],
+  const ragModeEnabled =
+    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+  const hasSingleRoundRag = useMemo(
+    () => messages.some(isSingleRoundRagMessage),
+    [messages],
+  );
+  const referencesEnabled = ragModeEnabled || hasSingleRoundRag;
+  const { skills } = useSkills();
+  const skillDisplayMap = useMemo(
+    () => (referencesEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [referencesEnabled, skills],
   );
   // Same per-turn reference batches the right-side panel renders (backend
   // batches preferred). Inline [n] tokens must resolve against these so badge
@@ -373,7 +379,7 @@ export function MessageList({
           if (group.type === "human" || group.type === "assistant") {
             return group.messages.map((msg) => {
               const isAssistantMessage =
-                ragModeEnabled &&
+                referencesEnabled &&
                 group.type === "assistant" &&
                 msg.type === "ai";
               const batchSources = isAssistantMessage

frontend-web/src/components/workspace/mode-hover-guide.tsx

@@ -46,20 +46,23 @@ function getModeDescriptionKey(
   }
 }
 
-export function ModeHoverGuide({
-  mode,
-  children,
-  showTitle = true,
-}: {
-  mode: AgentMode;
-  children: React.ReactNode;
-  /** When true, tooltip shows "ModeName: Description". When false, only description. */
-  showTitle?: boolean;
-}) {
-  const { t } = useI18n();
-  const label = t.inputBox[getModeLabelKey(mode)];
-  const description = t.inputBox[getModeDescriptionKey(mode)];
-  const content = showTitle ? `${label}: ${description}` : description;
+export function ModeHoverGuide({
+  mode,
+  children,
+  showTitle = true,
+  tooltipContent,
+}: {
+  mode: AgentMode;
+  children: React.ReactNode;
+  /** When true, tooltip shows "ModeName: Description". When false, only description. */
+  showTitle?: boolean;
+  /** Overrides the standard mode tooltip for page-specific execution modes. */
+  tooltipContent?: string;
+}) {
+  const { t } = useI18n();
+  const label = t.inputBox[getModeLabelKey(mode)];
+  const description = t.inputBox[getModeDescriptionKey(mode)];
+  const content = tooltipContent ?? (showTitle ? `${label}: ${description}` : description);
 
   return <Tooltip content={content}>{children}</Tooltip>;
 }

frontend-web/src/components/workspace/settings/skill-settings-page.tsx

@@ -71,8 +71,9 @@ import { useTheme } from "@/contexts/ThemeContext";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import type { ValidateSkillUploadResponse } from "@/core/skills/api";
-import {
-  useDeleteCustomSkill,
+import {
+  useDeleteBuiltinSkill,
+  useDeleteCustomSkill,
   useDuplicateSkill,
   useGenerateMissingSkillNameZh,
   useGenerateSkillNameZh,
@@ -616,9 +617,10 @@ export function SkillRow({
   const { data: cardPublishSquares } = usePublishSquares();
   const setPinned = useSetSkillPinned();
   const setFeatured = useSetSkillFeatured();
-  const setAlwaysOn = useSetSkillAlwaysOn();
-  const { data: compression } = useSkillCompressionSettings();
-  const deleteSkill = useDeleteCustomSkill();
+  const setAlwaysOn = useSetSkillAlwaysOn();
+  const { data: compression } = useSkillCompressionSettings();
+  const deleteCustom = useDeleteCustomSkill();
+  const deleteBuiltin = useDeleteBuiltinSkill();
   const duplicateSkillMutation = useDuplicateSkill();
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
   const [tagPickerOpen, setTagPickerOpen] = useState(false);
@@ -634,8 +636,9 @@ export function SkillRow({
   const isOwned =
     isCustom && !isBuiltin && !!skill.owner_user_id && skill.owner_user_id === currentUserId;
   const isFromOthers = isCustom && !isBuiltin && !isOwned;
-  // Admin can edit/delete/unpublish anyone's skill; non-admin only their own.
-  const canManage = isCustom && (isOwned || isAdmin);
+  // Admin can manage custom skills from any owner; non-admin only their own.
+  const canManage = isCustom && (isOwned || isAdmin);
+  const canDelete = isAdmin || isOwned;
   const canTogglePublish = canManage && !isBuiltin;
   // 常驻(免压缩):内置技能仅管理员可设;自定义技能其所有者或管理员可设(与后端一致)。
   const canSetAlwaysOn = isAdmin || isOwned;
@@ -686,11 +689,15 @@ export function SkillRow({
     }
   }
 
-  async function handleDelete() {
-    try {
-      await deleteSkill.mutateAsync(skill.name);
-      toast.success(t.settings.skills.deleteSuccess);
-      setConfirmDeleteOpen(false);
+  async function handleDelete() {
+    try {
+      if (isBuiltin) {
+        await deleteBuiltin.mutateAsync(skill.name);
+      } else {
+        await deleteCustom.mutateAsync(skill.name);
+      }
+      toast.success(t.settings.skills.deleteSuccess);
+      setConfirmDeleteOpen(false);
     } catch (err) {
       toast.error(err instanceof Error ? err.message : String(err));
     }
@@ -918,7 +925,7 @@ export function SkillRow({
       >
         <TagsIcon className="size-3.5" />
       </Button>
-      {canManage && (
+      {canManage && (
         <Button
           size="icon"
           variant="ghost"
@@ -939,12 +946,12 @@ export function SkillRow({
           />
         </Button>
       )}
-      {canManage && (
-        <Button
-          size="icon"
-          variant="ghost"
-          className={cn(
-            "h-8 w-8 shrink-0",
+      {canManage && (
+        <Button
+          size="icon"
+          variant="ghost"
+          className={cn(
+            "h-8 w-8 shrink-0",
             skill.pinned && "text-emerald-600 hover:text-emerald-700",
           )}
           disabled={setPinned.isPending}
@@ -1011,11 +1018,11 @@ export function SkillRow({
       >
         <CopyIcon className="size-3.5" />
       </Button>
-      {canManage && (
-        <Button
-          size="icon"
-          variant="ghost"
-          className="text-destructive hover:text-destructive h-8 w-8 shrink-0"
+      {canDelete && (
+        <Button
+          size="icon"
+          variant="ghost"
+          className="text-destructive hover:text-destructive h-8 w-8 shrink-0"
           onClick={() => setConfirmDeleteOpen(true)}
           title={t.settings.skills.deleteAction}
         >
@@ -1109,16 +1116,18 @@ export function SkillRow({
             <Button
               variant="outline"
               onClick={() => setConfirmDeleteOpen(false)}
-              disabled={deleteSkill.isPending}
+              disabled={deleteCustom.isPending || deleteBuiltin.isPending}
             >
               {t.common.cancel}
             </Button>
             <Button
               variant="destructive"
               onClick={() => void handleDelete()}
-              disabled={deleteSkill.isPending}
-            >
-              {deleteSkill.isPending ? t.common.loading : t.common.delete}
+              disabled={deleteCustom.isPending || deleteBuiltin.isPending}
+            >
+              {deleteCustom.isPending || deleteBuiltin.isPending
+                ? t.common.loading
+                : t.common.delete}
             </Button>
           </DialogFooter>
         </DialogContent>

frontend-web/src/components/workspace/skill-display-sources.tsx

@@ -92,7 +92,7 @@ export function SourceCard({
       knowledge_base_id: previewTarget.knowledgeBaseId,
       chunk_id: previewTarget.chunkId,
     });
-    void apiFetch(`${getBackendBaseURL()}/api/weknora/source-context?${params}`)
+    void apiFetch(`${getBackendBaseURL()}/api/llmwiki/sources/context?${params}`)
       .then(async (response) => {
         const payload = (await response.json().catch(() => null)) as unknown;
         if (!response.ok || !isWeKnoraSourceContextResponse(payload)) {
@@ -240,7 +240,18 @@ type WeKnoraSourceContext = {
   knowledge_base_name?: string;
   document_title?: string;
   document_file_name?: string;
+  display_mode?: "wiki" | "chunks";
   focus_chunk_id: string;
+  wiki_page?: {
+    id?: string;
+    slug?: string;
+    title?: string;
+    page_type?: string;
+    status?: string;
+    summary?: string;
+    content?: string;
+    source_refs?: string[];
+  } | null;
   chunks: Array<{
     id: string;
     chunk_index?: number;
@@ -312,6 +323,33 @@ function WeKnoraSourceContextPanel({
   if (!context) {
     return null;
   }
+  const wikiPage = context.wiki_page;
+  const wikiContent = cleanReferenceText(
+    [wikiPage?.summary, wikiPage?.content].filter(Boolean).join("\n\n"),
+    [],
+  );
+  if (wikiPage && wikiContent) {
+    return (
+      <div className="max-h-[55vh] space-y-3 overflow-y-auto pr-1">
+        <div className="bg-muted/60 text-muted-foreground rounded-lg px-3 py-2 text-xs">
+          <span>{context.knowledge_base_name || "WeKnora 知识库"}</span>
+          <span> · LLMWiki</span>
+          {wikiPage.page_type && <span> · {wikiPage.page_type}</span>}
+        </div>
+        <section className="border-primary/40 bg-primary/5 rounded-lg border p-3 text-sm leading-relaxed shadow-sm">
+          <div className="mb-2 flex flex-wrap items-center gap-2">
+            <span className="text-foreground text-sm font-medium">
+              {wikiPage.title || wikiPage.slug || "LLMWiki 页面"}
+            </span>
+            <span className="bg-primary text-primary-foreground rounded px-1.5 py-0.5 text-xs font-medium">
+              清洗页
+            </span>
+          </div>
+          <div className="space-y-3 whitespace-pre-wrap">{wikiContent}</div>
+        </section>
+      </div>
+    );
+  }
   return (
     <div className="max-h-[55vh] space-y-3 overflow-y-auto pr-1">
       <div className="bg-muted/60 text-muted-foreground rounded-lg px-3 py-2 text-xs">

frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx

@@ -5,6 +5,7 @@ import {
   DownloadIcon,
   Loader2,
   PencilIcon,
+  Trash2Icon,
   XIcon,
 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
@@ -22,6 +23,7 @@ import { Textarea } from "@/components/ui/textarea";
 import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
 import { getSkillFileDownloadURL } from "@/core/skills/api";
 import {
+  useDeleteSkillFile,
   useSaveSkillFile,
   useSkillFileContent,
 } from "@/core/skills/hooks";
@@ -66,6 +68,7 @@ export function SkillFilePreviewDialog({
     open ? path : null,
   );
   const save = useSaveSkillFile();
+  const remove = useDeleteSkillFile();
 
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState("");
@@ -77,6 +80,8 @@ export function SkillFilePreviewDialog({
   }, [path, open]);
 
   const fileEditable = !!data?.editable && treeEditable;
+  const isRootSkillFile = path?.replace(/\\/g, "/").toLowerCase() === "skill.md";
+  const fileDeletable = !!data && treeEditable && !isRootSkillFile;
   const isMarkdown = useMemo(() => {
     if (!path) return false;
     const lower = path.toLowerCase();
@@ -115,6 +120,18 @@ export function SkillFilePreviewDialog({
     }
   }
 
+  async function handleDelete() {
+    if (!skillName || !path) return;
+    if (!window.confirm(tx.filesDeleteConfirm.replace("{path}", path))) return;
+    try {
+      await remove.mutateAsync({ skillName, path });
+      toast.success(tx.filesDeleteSuccess);
+      onOpenChange(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleCopyPath() {
     if (!path) return;
     await navigator.clipboard.writeText(path);
@@ -158,6 +175,18 @@ export function SkillFilePreviewDialog({
                   {tx.filesEditAction}
                 </Button>
               )}
+              {fileDeletable && !editing && (
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  className="h-7 px-2 text-xs text-destructive hover:text-destructive"
+                  onClick={() => void handleDelete()}
+                  disabled={remove.isPending}
+                >
+                  {remove.isPending ? <Loader2 className="size-3.5 animate-spin" /> : <Trash2Icon className="size-3.5" />}
+                  {tx.filesDeleteAction}
+                </Button>
+              )}
               {editing && (
                 <>
                   <Button

frontend-web/src/components/workspace/workspace-nav-chat-list.tsx

@@ -184,7 +184,7 @@ export function WorkspaceNavChatList({
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
-            <SidebarMenuItem>
+            {/* <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname.startsWith("/page/workspace/roundtable/position")}
                 asChild
@@ -195,7 +195,7 @@ export function WorkspaceNavChatList({
                   <span>岗位会商</span>
                 </Link>
               </SidebarMenuButton>
-            </SidebarMenuItem>
+            </SidebarMenuItem> */}
             <SidebarMenuItem>
               <SidebarMenuButton
                 isActive={pathname === "/page/workspace/scheduled/tasks"}

frontend-web/src/core/agents/types.ts

@@ -61,7 +61,9 @@ export interface Agent {
   /** 会商席位「技能识别强化」开关。作为会商席位运行时，是否把本智能体配置的技能
    * (名称 + SKILL.md 路径 + 必须先 read_file 的硬指令) 拼进本轮任务以补偿弱模型。
    * 与业务链条同名开关取 OR。null/false = 关 (默认)。 */
-  seat_skill_directive?: boolean | null;
+  seat_skill_directive?: boolean | null;
+  /** DeerFlow LLMWiki mapping ids this agent allows conversations to select. */
+  llmwiki_knowledge_base_ids?: string[] | null;
   tags?: Tag[];
   featured_order?: number | null;
   /** Whether the current user has favorited (收藏) this agent. */
@@ -96,7 +98,8 @@ export interface CreateAgentRequest {
   common_questions?: AgentQuestion[] | null;
   template_name?: string | null;
   /** 会商席位「技能识别强化」开关；缺省/false = 关。 */
-  seat_skill_directive?: boolean | null;
+  seat_skill_directive?: boolean | null;
+  llmwiki_knowledge_base_ids?: string[] | null;
 }
 
 export interface UpdateAgentRequest {
@@ -113,5 +116,6 @@ export interface UpdateAgentRequest {
   /** 入库模板名；传空字符串表示清除。 */
   template_name?: string | null;
   /** 会商席位「技能识别强化」开关；缺省/false = 关。 */
-  seat_skill_directive?: boolean | null;
-}
+  seat_skill_directive?: boolean | null;
+  llmwiki_knowledge_base_ids?: string[] | null;
+}

frontend-web/src/core/config/index.ts

@@ -13,19 +13,33 @@ export function buildIntranetSourceUrl(recUuid?: string | null): string {
   return `${INTRANET_SOURCE_URL_BASE}${encodeURIComponent(recUuid)}`;
 }
 
-function getBaseOrigin() {
+function getBaseOrigin() {
   if (typeof window !== "undefined") {
     return window.location.origin;
   }
   // Fallback for SSR
-  return "http://localhost:2026";
-}
-
-export function getBackendBaseURL() {
-  if (env.NEXT_PUBLIC_BACKEND_BASE_URL) {
-    return new URL(env.NEXT_PUBLIC_BACKEND_BASE_URL, getBaseOrigin())
-      .toString()
-      .replace(/\/+$/, "");
+  return "http://localhost:2026";
+}
+
+function alignLoopbackHostname(url: URL): URL {
+  if (typeof window === "undefined") return url;
+  const loopbackHosts = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+  if (
+    loopbackHosts.has(url.hostname) &&
+    loopbackHosts.has(window.location.hostname)
+  ) {
+    url.hostname = window.location.hostname;
+  }
+  return url;
+}
+
+export function getBackendBaseURL() {
+  if (env.NEXT_PUBLIC_BACKEND_BASE_URL) {
+    return alignLoopbackHostname(
+      new URL(env.NEXT_PUBLIC_BACKEND_BASE_URL, getBaseOrigin()),
+    )
+      .toString()
+      .replace(/\/+$/, "");
   } else {
     return "";
   }

frontend-web/src/core/i18n/locales/en-US.ts

@@ -545,10 +545,13 @@ export const enUS: Translations = {
       filesSaveAction: "Save",
       filesCancelEditAction: "Cancel",
       filesDownloadAction: "Download",
-      filesCopyPathAction: "Copy path",
-      filesDiscardConfirm: "Discard unsaved changes?",
-      filesSaveSuccess: "File saved",
-      filesReadOnlyHint: "Built-in skills are read-only.",
+      filesCopyPathAction: "Copy path",
+      filesDiscardConfirm: "Discard unsaved changes?",
+      filesSaveSuccess: "File saved",
+      filesDeleteAction: "Delete",
+      filesDeleteConfirm: "Delete \"{path}\"? This cannot be undone.",
+      filesDeleteSuccess: "File deleted",
+      filesReadOnlyHint: "Only administrators can edit or delete built-in skill files.",
       viewDetailAction: "View skill details",
       stateSheet: {
         archivedTitle: "Archived skills",

frontend-web/src/core/i18n/locales/types.ts

@@ -475,10 +475,13 @@ export interface Translations {
       filesSaveAction: string;
       filesCancelEditAction: string;
       filesDownloadAction: string;
-      filesCopyPathAction: string;
-      filesDiscardConfirm: string;
-      filesSaveSuccess: string;
-      filesReadOnlyHint: string;
+      filesCopyPathAction: string;
+      filesDiscardConfirm: string;
+      filesSaveSuccess: string;
+      filesDeleteAction: string;
+      filesDeleteConfirm: string;
+      filesDeleteSuccess: string;
+      filesReadOnlyHint: string;
       viewDetailAction: string;
       stateSheet: {
         archivedTitle: string;

frontend-web/src/core/i18n/locales/zh-CN.ts

@@ -524,8 +524,11 @@ export const zhCN: Translations = {
       filesDownloadAction: "下载",
       filesCopyPathAction: "复制路径",
       filesDiscardConfirm: "有未保存的修改,确定放弃吗?",
-      filesSaveSuccess: "文件已保存",
-      filesReadOnlyHint: "内置技能为只读,仅可查看。",
+      filesSaveSuccess: "文件已保存",
+      filesDeleteAction: "删除",
+      filesDeleteConfirm: "确定删除“{path}”？该操作不可撤销。",
+      filesDeleteSuccess: "文件已删除",
+      filesReadOnlyHint: "仅管理员可以编辑或删除内置技能文件。",
       viewDetailAction: "查看技能详情",
       stateSheet: {
         archivedTitle: "归档的技能",

frontend-web/src/core/llmwiki/conversation-deposit.ts

@@ -0,0 +1,66 @@
+import type { Message } from "@langchain/langgraph-sdk";
+
+import { textOfMessage } from "@/core/threads/utils";
+import { createLlmWikiConversationDeposit } from "@/strategy-components/api/llmwiki";
+
+function isHidden(message: Message): boolean {
+  const extra = (message as { additional_kwargs?: Record<string, unknown> })
+    .additional_kwargs;
+  return extra?.hide_from_ui === true;
+}
+
+function messageText(message: Message | undefined): string {
+  return (message ? textOfMessage(message) : "")?.trim() ?? "";
+}
+
+function hasText(message: Message | undefined): message is Message {
+  return !!message && messageText(message).length > 0;
+}
+
+export function queueLlmWikiConversationDeposit({
+  threadId,
+  messages,
+  assistantId,
+  knowledgeBaseIds,
+}: {
+  threadId: string | null | undefined;
+  messages: Message[] | undefined;
+  assistantId?: string | null;
+  knowledgeBaseIds?: string[];
+}) {
+  if (!threadId || !messages?.length) {
+    return;
+  }
+  const visible = messages.filter((message) => !isHidden(message));
+  const assistantIndex = [...visible]
+    .map((message, index) => ({ message, index }))
+    .reverse()
+    .find(({ message }) => message.type === "ai" && hasText(message))?.index;
+  if (assistantIndex === undefined) {
+    return;
+  }
+  const assistantMessage = visible[assistantIndex];
+  const humanMessage = [...visible.slice(0, assistantIndex)]
+    .reverse()
+    .find((message) => message.type === "human" && hasText(message));
+  if (!assistantMessage?.id || !humanMessage) {
+    return;
+  }
+  const question = messageText(humanMessage);
+  const answer = messageText(assistantMessage);
+  if (!question || !answer) {
+    return;
+  }
+
+  void createLlmWikiConversationDeposit({
+    thread_id: threadId,
+    question,
+    answer,
+    human_message_id: humanMessage.id ?? null,
+    assistant_message_id: assistantMessage.id,
+    assistant_id: assistantId ?? null,
+    knowledge_base_ids: knowledgeBaseIds ?? [],
+  }).catch((error) => {
+    console.warn("Failed to queue LLMWiki conversation deposit", error);
+  });
+}

frontend-web/src/core/model-management/api.ts

@@ -0,0 +1,114 @@
+import { apiFetch } from "@/core/api";
+import { getBackendBaseURL } from "@/core/config";
+
+export interface ManagedModel {
+  name: string;
+  display_name: string | null;
+  description: string | null;
+  use: string;
+  model: string;
+  base_url: string | null;
+  request_timeout: number | null;
+  max_retries: number | null;
+  max_tokens: number | null;
+  temperature: number | null;
+  stream_usage: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled: Record<string, unknown> | null;
+  when_thinking_disabled: Record<string, unknown> | null;
+  thinking: Record<string, unknown> | null;
+  use_responses_api: boolean | null;
+  output_version: string | null;
+  extra_settings: Record<string, unknown>;
+  api_key_configured: boolean;
+  api_key_source: string | null;
+  source: "config.yaml";
+}
+
+export interface ManagedModelsResponse {
+  models: ManagedModel[];
+  config_path: string;
+  updated_at: string | null;
+}
+
+export interface ModelSavePayload {
+  name: string;
+  display_name?: string | null;
+  description?: string | null;
+  use: string;
+  model: string;
+  api_key?: string;
+  clear_api_key?: boolean;
+  base_url?: string | null;
+  request_timeout?: number | null;
+  max_retries?: number | null;
+  max_tokens?: number | null;
+  temperature?: number | null;
+  stream_usage?: boolean | null;
+  supports_thinking: boolean;
+  supports_reasoning_effort: boolean;
+  supports_vision: boolean;
+  when_thinking_enabled?: Record<string, unknown> | null;
+  when_thinking_disabled?: Record<string, unknown> | null;
+  thinking?: Record<string, unknown> | null;
+  use_responses_api?: boolean | null;
+  output_version?: string | null;
+  extra_settings: Record<string, unknown>;
+}
+
+export interface ModelConnectionTestResult {
+  success: boolean;
+  latency_ms: number;
+  message: string;
+  preview?: string | null;
+}
+
+async function readError(response: Response, fallback: string): Promise<never> {
+  const payload = await response.json().catch(() => null) as { detail?: string } | null;
+  throw new Error(payload?.detail || fallback);
+}
+
+export async function loadManagedModels(): Promise<ManagedModelsResponse> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`);
+  if (!response.ok) return readError(response, "加载模型配置失败");
+  return response.json() as Promise<ManagedModelsResponse>;
+}
+
+export async function createManagedModel(payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "创建模型失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function updateManagedModel(name: string, payload: ModelSavePayload): Promise<ManagedModel> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  if (!response.ok) return readError(response, "保存模型配置失败");
+  return response.json() as Promise<ManagedModel>;
+}
+
+export async function deleteManagedModel(name: string): Promise<void> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/${encodeURIComponent(name)}`, {
+    method: "DELETE",
+  });
+  if (!response.ok) return readError(response, "删除模型失败");
+}
+
+export async function testManagedModel(model: ModelSavePayload): Promise<ModelConnectionTestResult> {
+  const response = await apiFetch(`${getBackendBaseURL()}/api/admin/models/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model }),
+  });
+  if (!response.ok) return readError(response, "模型连接测试失败");
+  return response.json() as Promise<ModelConnectionTestResult>;
+}

frontend-web/src/core/model-management/hooks.ts

@@ -0,0 +1,52 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import {
+  createManagedModel,
+  deleteManagedModel,
+  loadManagedModels,
+  testManagedModel,
+  updateManagedModel,
+  type ModelSavePayload,
+} from "./api";
+
+export const MANAGED_MODELS_QUERY_KEY = ["admin", "model-config"] as const;
+
+export function useManagedModels() {
+  return useQuery({
+    queryKey: MANAGED_MODELS_QUERY_KEY,
+    queryFn: loadManagedModels,
+    staleTime: 10_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useSaveManagedModel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ name, payload, isNew }: { name: string; payload: ModelSavePayload; isNew: boolean }) =>
+      isNew ? createManagedModel(payload) : updateManagedModel(name, payload),
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: MANAGED_MODELS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: ["models"] }),
+      ]);
+    },
+  });
+}
+
+export function useTestManagedModel() {
+  return useMutation({ mutationFn: testManagedModel });
+}
+
+export function useDeleteManagedModel() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: deleteManagedModel,
+    onSuccess: async () => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: MANAGED_MODELS_QUERY_KEY }),
+        queryClient.invalidateQueries({ queryKey: ["models"] }),
+      ]);
+    },
+  });
+}

frontend-web/src/core/model-management/index.ts

@@ -0,0 +1,2 @@
+export * from "./api";
+export * from "./hooks";

frontend-web/src/core/models/single-round-rag.ts

@@ -0,0 +1,21 @@
+import type { Model } from "./types";
+
+export const SINGLE_ROUND_RAG_MODELS: Model[] = [
+  { id: "single-round-rag-openai3", name: "OpenAI3", model: "OpenAI3", display_name: "Qwen3-32B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai4", name: "OpenAI4", model: "OpenAI4", display_name: "Qwen3-235B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai5", name: "OpenAI5", model: "OpenAI5", display_name: "GLM-5", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai6", name: "OpenAI6", model: "OpenAI6", display_name: "Qwen3.5-27B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai7", name: "OpenAI7", model: "OpenAI7", display_name: "Qwen3-8B", supports_thinking: true, execution_profile: "single_round_rag" },
+  { id: "single-round-rag-openai9", name: "OpenAI9", model: "OpenAI9", display_name: "四季7B", supports_thinking: true, execution_profile: "single_round_rag" },
+];
+
+export function isSingleRoundRagProfile(
+  context: unknown,
+): boolean {
+  return (
+    typeof context === "object" &&
+    context !== null &&
+    (context as { execution_profile?: unknown }).execution_profile ===
+      "single_round_rag"
+  );
+}

frontend-web/src/core/models/types.ts

@@ -4,9 +4,11 @@ export interface Model {
   model: string;
   display_name: string;
   description?: string | null;
-  supports_thinking?: boolean;
-  supports_reasoning_effort?: boolean;
-}
+  supports_thinking?: boolean;
+  supports_reasoning_effort?: boolean;
+  /** Execution profiles handled by the frontend instead of DeerFlow. */
+  execution_profile?: "single_round_rag";
+}
 
 export interface TokenUsageSettings {
   enabled: boolean;

frontend-web/src/core/skills/api.ts

@@ -402,15 +402,26 @@ export async function getSkillContent(
   return response.json() as Promise<SkillContentResponse>;
 }
 
-export async function deleteCustomSkill(skillName: string): Promise<void> {
+export async function deleteCustomSkill(skillName: string): Promise<void> {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/skills/custom/${encodeURIComponent(skillName)}`,
     { method: "DELETE" },
   );
   if (!response.ok) {
     throw await parseDetailedError(response, "Failed to delete skill");
-  }
-}
+  }
+}
+
+/** Delete a built-in skill. The backend permits this only for administrators. */
+export async function deleteBuiltinSkill(skillName: string): Promise<void> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}`,
+    { method: "DELETE" },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to delete built-in skill");
+  }
+}
 
 export interface SkillFileNode {
   name: string;
@@ -479,7 +490,7 @@ export function getSkillFileDownloadURL(skillName: string, path: string): string
   );
 }
 
-export async function saveSkillFile(
+export async function saveSkillFile(
   skillName: string,
   path: string,
   content: string,
@@ -494,9 +505,22 @@ export async function saveSkillFile(
   );
   if (!response.ok) {
     throw await parseDetailedError(response, "Failed to save skill file");
-  }
-  return response.json() as Promise<SkillFileSaveResponse>;
-}
+  }
+  return response.json() as Promise<SkillFileSaveResponse>;
+}
+
+export async function deleteSkillFile(
+  skillName: string,
+  path: string,
+): Promise<void> {
+  const url =
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files/content` +
+    `?path=${encodeURIComponent(path)}`;
+  const response = await apiFetch(url, { method: "DELETE" });
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to delete skill file");
+  }
+}
 
 export interface SkillNameZhResponse {
   name: string;

frontend-web/src/core/skills/hooks.ts

@@ -5,8 +5,10 @@ import {
   useQueryClient,
 } from "@tanstack/react-query";
 
-import {
-  deleteCustomSkill,
+import {
+  deleteBuiltinSkill,
+  deleteCustomSkill,
+  deleteSkillFile,
   duplicateSkill,
   enableSkill,
   generateMissingSkillNameZh,
@@ -318,7 +320,7 @@ export function useSkillFileContent(skillName: string | null, path: string | nul
   });
 }
 
-export function useSaveSkillFile() {
+export function useSaveSkillFile() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: ({
@@ -339,5 +341,33 @@ export function useSaveSkillFile() {
         void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
       }
     },
-  });
-}
+  });
+}
+
+export function useDeleteSkillFile() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      skillName,
+      path,
+    }: {
+      skillName: string;
+      path: string;
+    }) => deleteSkillFile(skillName, path),
+    onSuccess: (_data, { skillName, path }) => {
+      void queryClient.invalidateQueries({ queryKey: ["skill-files", skillName] });
+      void queryClient.removeQueries({ queryKey: ["skill-file", skillName, path] });
+    },
+  });
+}
+
+export function useDeleteBuiltinSkill() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: deleteBuiltinSkill,
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      void queryClient.invalidateQueries({ queryKey: ["admin-skills"] });
+    },
+  });
+}

frontend-web/src/core/threads/hooks.ts

@@ -1146,20 +1146,26 @@ export function useThreadStream({
           }),
         );
 
-        const ragModeEnabled =
-          localSettings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
-        if (ragModeEnabled) {
-          lockThreadRagMode(threadId);
-        }
+        const mergedContext = {
+          ...context,
+          ...extraContext,
+        };
+        const selectedLlmWikiIds = Array.isArray(
+          mergedContext.llmwiki_knowledge_base_ids,
+        )
+          ? mergedContext.llmwiki_knowledge_base_ids
+          : [];
+        const ragModeEnabled =
+          localSettings.display.ragModeEnabled ||
+          isThreadRagModeLocked(threadId) ||
+          selectedLlmWikiIds.length > 0;
+        if (ragModeEnabled) {
+          lockThreadRagMode(threadId);
+        }
 
         const contextCompressionEnabled =
           localSettings.display.contextCompressionEnabled ?? false;
 
-        const mergedContext = {
-          ...context,
-          ...extraContext,
-        };
-
         const hiddenContextMessages = normalizeHiddenContextMessages(options);
         const submittedMessages: Message[] = [
           ...hiddenContextMessages.map((item) => ({

frontend-web/src/core/threads/types.ts

@@ -23,9 +23,13 @@ export interface AgentThreadContext extends Record<string, unknown> {
   rag_mode_enabled?: boolean;
   /** Per-request switch for context compression (上下文压缩). Default off. */
   summarization_enabled?: boolean;
-  /** Per-conversation switch for knowledge-base RAG injection (phase 2). */
-  knowledge_rag_enabled?: boolean;
-  agent_id?: string;
+  /** Per-conversation switch for knowledge-base RAG injection (phase 2). */
+  knowledge_rag_enabled?: boolean;
+  /** DeerFlow LLMWiki mapping ids selected for this conversation. */
+  llmwiki_knowledge_base_ids?: string[];
+  /** Direct knowledge-base RAG mode; this request never enters Lead Agent. */
+  execution_profile?: "single_round_rag";
+  agent_id?: string;
   /** @deprecated kept for reading legacy thread metadata; prefer agent_id */
   agent_name?: string;
 }

frontend-web/src/core/threads/use-single-round-rag.ts

@@ -0,0 +1,378 @@
+import type { Message } from "@langchain/langgraph-sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { readRuntimeEnv } from "@/env";
+
+const STORAGE_PREFIX = "workspace.single-round-rag.";
+
+type KnowledgeBaseChunk = {
+  answer?: unknown;
+  docs?: unknown;
+};
+
+type RagSource = {
+  id?: string;
+  title: string;
+  type: string;
+  snippet: string;
+  content: string;
+  source?: string;
+  time?: string;
+  url?: string;
+  raw: Record<string, unknown>;
+};
+
+/** Same JSON-object framing used by the established GeneralQA single-RAG flow. */
+function extractJsonObjects(raw: string): { objects: string[]; rest: string } {
+  const objects: string[] = [];
+  let depth = 0;
+  let stringQuote: '"' | "'" | null = null;
+  let escaped = false;
+  let start = -1;
+  for (let index = 0; index < raw.length; index += 1) {
+    const char = raw[index]!;
+    if (stringQuote) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === stringQuote) stringQuote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      stringQuote = char;
+      continue;
+    }
+    if (char === "{") {
+      if (depth === 0) start = index;
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0 && start !== -1) {
+        objects.push(raw.slice(start, index + 1));
+        start = -1;
+      }
+    }
+  }
+  return depth > 0 && start !== -1
+    ? { objects, rest: raw.slice(start) }
+    : { objects, rest: "" };
+}
+
+/** Same `<think>` split semantics as GeneralQA, kept local to avoid loading its demo data. */
+function parseSingleRagStream(chunks: { answer: string }[]) {
+  let thinkingMarkdown = "";
+  let answerMarkdown = "";
+  let inThink = false;
+  let thinkingComplete = false;
+  for (const { answer } of chunks) {
+    let remaining = answer;
+    while (remaining) {
+      if (inThink) {
+        const endIndex = remaining.indexOf("</think>");
+        if (endIndex === -1) {
+          thinkingMarkdown += remaining;
+          remaining = "";
+        } else {
+          thinkingMarkdown += remaining.slice(0, endIndex);
+          remaining = remaining.slice(endIndex + "</think>".length);
+          inThink = false;
+          thinkingComplete = true;
+        }
+      } else {
+        const startIndex = remaining.indexOf("<think>");
+        if (startIndex === -1) {
+          answerMarkdown += remaining;
+          remaining = "";
+        } else {
+          answerMarkdown += remaining.slice(0, startIndex);
+          remaining = remaining.slice(startIndex + "<think>".length);
+          inThink = true;
+        }
+      }
+    }
+  }
+  return { thinkingMarkdown, answerMarkdown, thinkingComplete };
+}
+
+function storageKey(threadId: string) {
+  return `${STORAGE_PREFIX}${threadId}`;
+}
+
+function readStoredMessages(threadId: string): Message[] {
+  if (typeof window === "undefined" || !threadId) return [];
+  try {
+    const raw = window.sessionStorage.getItem(storageKey(threadId));
+    const parsed: unknown = raw ? JSON.parse(raw) : [];
+    return Array.isArray(parsed) ? (parsed as Message[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeStoredMessages(threadId: string, messages: Message[]) {
+  if (typeof window === "undefined" || !threadId) return;
+  try {
+    window.sessionStorage.setItem(storageKey(threadId), JSON.stringify(messages));
+  } catch {
+    // Quota errors must never interrupt an already-running answer.
+  }
+}
+
+function parseLooseStringValue(rawValue: string): string {
+  try {
+    return JSON.parse(rawValue) as string;
+  } catch {
+    const value = rawValue.trim();
+    if (value.startsWith("'") && value.endsWith("'")) {
+      return value
+        .slice(1, -1)
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\r")
+        .replace(/\\t/g, "\t")
+        .replace(/\\'/g, "'")
+        .replace(/\\\\/g, "\\");
+    }
+    throw new Error(`无法解析知识库流片段：${rawValue}`);
+  }
+}
+
+function parseKnowledgeBaseChunk(jsonText: string): KnowledgeBaseChunk {
+  try {
+    return JSON.parse(jsonText) as KnowledgeBaseChunk;
+  } catch {
+    const objectText = jsonText.trim();
+    const answerMatch = objectText.match(/^\{\s*answer\s*:\s*([\s\S]*)\s*\}$/);
+    if (answerMatch) {
+      return { answer: parseLooseStringValue(answerMatch[1]!.trim()) };
+    }
+    const docsMatch = objectText.match(/^\{\s*docs\s*:\s*([\s\S]*)\s*\}$/);
+    if (docsMatch) {
+      const rawValue = docsMatch[1]!.trim();
+      try {
+        return { docs: JSON.parse(rawValue) };
+      } catch {
+        return { docs: parseLooseStringValue(rawValue) };
+      }
+    }
+    const normalizedText = objectText.replace(
+      /([{,]\s*)(answer|docs)(\s*:)/g,
+      '$1"$2"$3',
+    );
+    return JSON.parse(normalizedText) as KnowledgeBaseChunk;
+  }
+}
+
+function flattenDocs(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => flattenDocs(item));
+  }
+  if (!value || typeof value !== "object") return [];
+  const record = value as Record<string, unknown>;
+  if ("docs" in record) return flattenDocs(record.docs);
+  return [record];
+}
+
+function normalizeSources(value: unknown): RagSource[] {
+  return flattenDocs(value).map((item, index) => {
+    const title = String(item.m_title ?? item.title ?? item.source ?? `参考资料 ${index + 1}`);
+    const content = String(item.m_content ?? item.content ?? item.snippet ?? "");
+    const source = item.source1 ?? item.source;
+    const rawUrl = item.url ?? item.link ?? item.href;
+    return {
+      id: String(item.recUuid ?? item.rec_uuid ?? item.uuid ?? item.id ?? "") || undefined,
+      title,
+      type: String(item.source1 ?? item.type ?? "知识库"),
+      snippet: content,
+      content,
+      source: typeof source === "string" ? source : undefined,
+      time: typeof item.m_publish === "string" ? item.m_publish : undefined,
+      url: typeof rawUrl === "string" && /^https?:\/\//i.test(rawUrl) ? rawUrl : undefined,
+      raw: item,
+    };
+  });
+}
+
+function createId(prefix: string) {
+  return `${prefix}-${crypto.randomUUID()}`;
+}
+
+function isAbortError(error: unknown) {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+export function isSingleRoundRagMessage(message: Message): boolean {
+  return message.additional_kwargs?.single_round_rag === true;
+}
+
+/**
+ * Frontend-only adapter for the existing general-QA single-round endpoint.
+ * It deliberately never submits a run to DeerFlow or mutates the Lead Agent.
+ */
+export function useSingleRoundRagMessages(threadId: string) {
+  const [messages, setMessages] = useState<Message[]>(() => readStoredMessages(threadId));
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => {
+    setMessages(readStoredMessages(threadId));
+    setError(null);
+  }, [threadId]);
+
+  useEffect(() => () => controllerRef.current?.abort(), []);
+
+  const updateMessages = useCallback(
+    (targetThreadId: string, updater: (current: Message[]) => Message[]) => {
+      setMessages((current) => {
+        const next = updater(current);
+        writeStoredMessages(targetThreadId, next);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const stop = useCallback(() => controllerRef.current?.abort(), []);
+
+  const submit = useCallback(
+    async ({
+      targetThreadId,
+      query,
+      modelName,
+    }: {
+      targetThreadId: string;
+      query: string;
+      modelName: string;
+    }) => {
+      if (isLoading) return;
+      const question = query.trim();
+      if (!question) return;
+
+      const humanId = createId("single-rag-human");
+      const assistantId = createId("single-rag-ai");
+      const sourceId = createId("single-rag-sources");
+      const clientTs = new Date().toISOString();
+      const userMessage: Message = {
+        id: humanId,
+        type: "human",
+        content: [{ type: "text", text: question }],
+        additional_kwargs: { client_ts: clientTs, single_round_rag: true },
+      };
+      const initialAssistant: Message = {
+        id: assistantId,
+        type: "ai",
+        content: "",
+        additional_kwargs: { single_round_rag: true },
+      };
+      updateMessages(targetThreadId, (current) => [...current, userMessage, initialAssistant]);
+      setError(null);
+      setIsLoading(true);
+
+      const controller = new AbortController();
+      controllerRef.current = controller;
+      const answerChunks: { answer: string }[] = [];
+      let sources: RagSource[] = [];
+
+      const refreshAssistant = () => {
+        const trace = parseSingleRagStream(answerChunks);
+        updateMessages(targetThreadId, (current) => {
+          const next = current.filter((message) => message.id !== sourceId);
+          const assistantIndex = next.findIndex((message) => message.id === assistantId);
+          if (assistantIndex < 0) return current;
+          next[assistantIndex] = {
+            ...next[assistantIndex],
+            content: trace.answerMarkdown,
+            additional_kwargs: {
+              ...next[assistantIndex]!.additional_kwargs,
+              single_round_rag: true,
+              reasoning_content: trace.thinkingMarkdown || null,
+            },
+          } as Message;
+          if (sources.length > 0) {
+            next.splice(assistantIndex, 0, {
+              id: sourceId,
+              type: "tool",
+              name: "knowledge_base_search",
+              content: { results: sources },
+              additional_kwargs: {
+                hide_from_ui: true,
+                single_round_rag: true,
+              },
+            } as unknown as Message);
+          }
+          return next;
+        });
+      };
+
+      try {
+        const chatUrl = readRuntimeEnv("VITE_AIPI_CHAT_URL") || "";
+        if (!chatUrl) {
+          throw new Error("未配置 VITE_AIPI_CHAT_URL，无法发起单轮 RAG 问答。");
+        }
+        const response = await fetch(
+          `${chatUrl.replace(/\/$/, "")}/chat/knowledge_base_chat_tiaoshi`,
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            signal: controller.signal,
+            body: JSON.stringify({
+              query: question,
+              knowledge_base_name: [],
+              top_k: 5,
+              score_threshold: 0.5,
+              history: [],
+              stream: true,
+              model_name: modelName,
+              temperature: 0.3,
+              prompt_name: "default",
+              local_doc_url: false,
+            }),
+          },
+        );
+        if (!response.ok) throw new Error(`知识库服务请求失败（${response.status}）`);
+        if (!response.body) throw new Error("知识库服务未返回流式响应。");
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const extracted = extractJsonObjects(buffer);
+          buffer = extracted.rest;
+          for (const jsonText of extracted.objects) {
+            const chunk = parseKnowledgeBaseChunk(jsonText);
+            if (typeof chunk.answer === "string") answerChunks.push({ answer: chunk.answer });
+            if (chunk.docs !== undefined) sources = normalizeSources(chunk.docs);
+            refreshAssistant();
+          }
+        }
+      } catch (caught) {
+        if (!isAbortError(caught)) {
+          const message = caught instanceof Error ? caught.message : "单轮 RAG 问答失败。";
+          setError(message);
+          updateMessages(targetThreadId, (current) =>
+            current.map((item) =>
+              item.id === assistantId
+                ? ({
+                    ...item,
+                    content: answerChunks.length > 0 ? item.content : message,
+                    additional_kwargs: {
+                      ...item.additional_kwargs,
+                      single_round_rag: true,
+                    },
+                  } as Message)
+                : item,
+            ),
+          );
+        }
+      } finally {
+        if (controllerRef.current === controller) controllerRef.current = null;
+        setIsLoading(false);
+      }
+    },
+    [isLoading, updateMessages],
+  );
+
+  return { messages, isLoading, error, submit, stop };
+}

frontend-web/src/pages/AgentChatPage.tsx

@@ -16,6 +16,7 @@ import { ArtifactTrigger } from "@/components/workspace/artifacts";
 import { ChatBox, useThreadChat } from "@/components/workspace/chats";
 import { ExportTrigger } from "@/components/workspace/export-trigger";
 import { InputBox } from "@/components/workspace/input-box";
+import { LlmWikiKnowledgeSelector } from "@/components/workspace/llmwiki-knowledge-selector";
 import { MessageList } from "@/components/workspace/messages";
 import { ThreadContext } from "@/components/workspace/messages/context";
 import { QuestionNavigator } from "@/components/workspace/question-navigator";
@@ -24,7 +25,9 @@ import { TodoList } from "@/components/workspace/todo-list";
 import { TokenUsageIndicator } from "@/components/workspace/token-usage-indicator";
 import { Tooltip } from "@/components/workspace/tooltip";
 import { normalizeAgentQuestions, useAgent } from "@/core/agents";
+import { getAPIClient } from "@/core/api";
 import { useI18n } from "@/core/i18n/hooks";
+import { queueLlmWikiConversationDeposit } from "@/core/llmwiki/conversation-deposit";
 import { useModels } from "@/core/models/hooks";
 import { useNotification } from "@/core/notification/hooks";
 import { saveLastAgentId, useThreadSettings } from "@/core/settings";
@@ -69,6 +72,26 @@ const TEMPLATE_BUILDER_AGENT_ID = "template-json-builder";
 const RWFX_SQ_REPORT_CONTEXT_MAX_CHARS = 12000;
 const RWFX_SQ_REPORT_CONTEXT_TAIL_CHARS = 2000;
 
+function readPendingKnowledgeSelection(agentId: string | undefined): string[] | null {
+  if (typeof window === "undefined" || !agentId) return null;
+  try {
+    const raw = sessionStorage.getItem("pendingAgentMessage");
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as {
+      agentId?: string;
+      knowledgeBaseIds?: unknown;
+    };
+    if (parsed.agentId !== agentId || !Array.isArray(parsed.knowledgeBaseIds)) {
+      return null;
+    }
+    return parsed.knowledgeBaseIds
+      .map((item) => String(item).trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
 function stringifyForHiddenContext(value: unknown): string {
   if (typeof value === "string") return value;
   try {
@@ -244,6 +267,79 @@ export default function AgentChatPage({
     useThreadChat();
   const [settings, setSettings] = useThreadSettings(threadId);
   const { tokenUsageEnabled } = useModels();
+  const pendingKnowledgeSelection = useRef(
+    readPendingKnowledgeSelection(agent_id),
+  );
+  const [selectedKnowledgeBaseIds, setSelectedKnowledgeBaseIds] = useState<string[]>(
+    () => pendingKnowledgeSelection.current ?? [],
+  );
+  const [knowledgeSelectionReady, setKnowledgeSelectionReady] = useState(
+    () => pendingKnowledgeSelection.current !== null,
+  );
+  const [knowledgeSelectionLoading, setKnowledgeSelectionLoading] = useState(false);
+  const knowledgeSelectionThread = useRef<string | null>(null);
+  const knowledgeSelectionAgent = useRef(agent_id);
+  const activeThreadIdRef = useRef<string | null | undefined>(threadId);
+
+  const changeKnowledgeSelection = useCallback((ids: string[]) => {
+    setSelectedKnowledgeBaseIds(ids);
+    setKnowledgeSelectionReady(true);
+  }, []);
+
+  useEffect(() => {
+    activeThreadIdRef.current = threadId;
+  }, [threadId]);
+
+  useEffect(() => {
+    if (knowledgeSelectionAgent.current === agent_id) return;
+    knowledgeSelectionAgent.current = agent_id;
+    const pending = readPendingKnowledgeSelection(agent_id);
+    pendingKnowledgeSelection.current = pending;
+    knowledgeSelectionThread.current = null;
+    setSelectedKnowledgeBaseIds(pending ?? []);
+    setKnowledgeSelectionReady(pending !== null);
+  }, [agent_id]);
+
+  useEffect(() => {
+    if (isNewThread) {
+      if (knowledgeSelectionThread.current !== "__new__") {
+        setSelectedKnowledgeBaseIds(pendingKnowledgeSelection.current ?? []);
+        setKnowledgeSelectionReady(pendingKnowledgeSelection.current !== null);
+      }
+      knowledgeSelectionThread.current = "__new__";
+      setKnowledgeSelectionLoading(false);
+      return;
+    }
+    if (!threadId || knowledgeSelectionThread.current === threadId) return;
+    knowledgeSelectionThread.current = threadId;
+    setKnowledgeSelectionLoading(true);
+    void getAPIClient()
+      .threads.get(threadId)
+      .then((record) => {
+        if (knowledgeSelectionThread.current !== threadId) return;
+        const metadata = record.metadata as Record<string, unknown> | undefined;
+        const raw = metadata?.llmwiki_knowledge_base_ids;
+        if (Array.isArray(raw)) {
+          setSelectedKnowledgeBaseIds(
+            raw.map((item) => String(item).trim()).filter(Boolean),
+          );
+          setKnowledgeSelectionReady(true);
+        } else {
+          setSelectedKnowledgeBaseIds([]);
+          setKnowledgeSelectionReady(false);
+        }
+      })
+      .catch(() => {
+        if (knowledgeSelectionThread.current === threadId) {
+          setKnowledgeSelectionReady(false);
+        }
+      })
+      .finally(() => {
+        if (knowledgeSelectionThread.current === threadId) {
+          setKnowledgeSelectionLoading(false);
+        }
+      });
+  }, [isNewThread, threadId]);
 
   useEffect(() => {
     if (isNewThread) {
@@ -253,14 +349,34 @@ export default function AgentChatPage({
   }, [isNewThread, threadId, agent_id]);
 
   const { showNotification } = useNotification();
+  const conversationMetadata = useMemo(
+    () => ({
+      ...(taskId ? taskThreadMetadata(taskContext) : {}),
+      ...(knowledgeSelectionReady
+        ? { llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds }
+        : {}),
+    }),
+    [knowledgeSelectionReady, selectedKnowledgeBaseIds, taskContext, taskId],
+  );
   const [thread, sendMessage] = useThreadStream({
     threadId: isNewThread ? undefined : threadId,
     assistantId: agent_id,
-    context: { ...settings.context, agent_id },
+    context: {
+      ...settings.context,
+      agent_id,
+      ...(knowledgeSelectionReady
+        ? { llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds }
+        : {}),
+    },
     // 任务闸门：新建 thread 打 metadata.taskId 标签，供任务对话列表(1:N)按任务过滤；
     // xdfx 额外打 metadata.actionId 标签，按「行动id」划分聊天记录（见 taskThreadMetadata）。
-    threadMetadata: taskId ? taskThreadMetadata(taskContext) : undefined,
+    threadMetadata:
+      Object.keys(conversationMetadata).length > 0
+        ? conversationMetadata
+        : undefined,
     onStart: (createdThreadId) => {
+      knowledgeSelectionThread.current = createdThreadId;
+      activeThreadIdRef.current = createdThreadId;
       setThreadId(createdThreadId);
       setIsNewThread(false);
       // Keep the current component mounted while updating the hash route.
@@ -286,6 +402,12 @@ export default function AgentChatPage({
       } catch {
         /* 上报绝不影响问答 */
       }
+      queueLlmWikiConversationDeposit({
+        threadId: activeThreadIdRef.current,
+        messages: state.messages,
+        assistantId: agent_id,
+        knowledgeBaseIds: selectedKnowledgeBaseIds,
+      });
       if (document.hidden || !document.hasFocus()) {
         let body = "Conversation finished";
         const lastMessage = state.messages[state.messages.length - 1];
@@ -581,10 +703,23 @@ export default function AgentChatPage({
                         autoFocus
                         status={status}
                         context={settings.context}
-                        disabled={isDemoMode}
+                        disabled={isDemoMode || knowledgeSelectionLoading}
                         onContextChange={(context) =>
                           setSettings("context", context)
                         }
+                        knowledgeSelector={
+                          <LlmWikiKnowledgeSelector
+                            source="agent"
+                            agentId={agent_id}
+                            value={selectedKnowledgeBaseIds}
+                            onChange={changeKnowledgeSelection}
+                            autoSelectAll={
+                              isNewThread && pendingKnowledgeSelection.current === null
+                            }
+                            disabled={isDemoMode || knowledgeSelectionLoading}
+                            label="知识空间"
+                          />
+                        }
                         onFollowupsVisibilityChange={setShowFollowups}
                         onSubmit={handleSubmit}
                         onStop={handleStop}
@@ -636,7 +771,7 @@ export default function AgentChatPage({
                         assistantId={agent_id}
                         status={status}
                         context={settings.context}
-                        disabled={isDemoMode}
+                        disabled={isDemoMode || knowledgeSelectionLoading}
                         onContextChange={(context) =>
                           setSettings("context", context)
                         }

frontend-web/src/pages/ChatPage.tsx

@@ -16,6 +16,7 @@ import {
 } from "@/components/workspace/chats";
 import { ExportTrigger } from "@/components/workspace/export-trigger";
 import { KnowledgeSaveTrigger } from "@/components/workspace/knowledge-save-trigger";
+import { LlmWikiKnowledgeSelector } from "@/components/workspace/llmwiki-knowledge-selector";
 import { InputBox } from "@/components/workspace/input-box";
 import {
   MessageList,
@@ -44,6 +45,10 @@ import { PanelLeftOpen } from "lucide-react";
 import { useAgentSelector, useAgentsPaginated } from "@/core/agents";
 import { useI18n } from "@/core/i18n/hooks";
 import { useModels } from "@/core/models/hooks";
+import {
+  isSingleRoundRagProfile,
+  SINGLE_ROUND_RAG_MODELS,
+} from "@/core/models/single-round-rag";
 import { useNotification } from "@/core/notification/hooks";
 import {
   getLastAgentId,
@@ -52,6 +57,8 @@ import {
   useThreadSettings,
 } from "@/core/settings";
 import { useThreadStream } from "@/core/threads/hooks";
+import { queueLlmWikiConversationDeposit } from "@/core/llmwiki/conversation-deposit";
+import { useSingleRoundRagMessages } from "@/core/threads/use-single-round-rag";
 import { useLayoutMode } from "@/core/system-settings/hooks";
 import { useRouteBase } from "@/core/route-base";
 import { textOfMessage } from "@/core/threads/utils";
@@ -121,12 +128,29 @@ export default function ChatPage() {
   // In-memory only — explicitly overrides any value persisted by the old
   // per-thread header toggle so stale localStorage can't re-enable it.
   const [knowledgeRagEnabled] = useKnowledgeRagEnabled();
+  const [selectedKnowledgeBaseIds, setSelectedKnowledgeBaseIds] = useState<string[]>([]);
+  const [knowledgeSelectionReady, setKnowledgeSelectionReady] = useState(false);
+  const [knowledgeSelectionLoading, setKnowledgeSelectionLoading] = useState(false);
+  const knowledgeSelectionThread = useRef<string | null>(null);
+  const activeThreadIdRef = useRef<string | null | undefined>(threadId);
+  const changeKnowledgeSelection = useCallback((ids: string[]) => {
+    setSelectedKnowledgeBaseIds(ids);
+    setKnowledgeSelectionReady(true);
+  }, []);
   const streamContext = useMemo(
     () => ({
       ...settings.context,
       knowledge_rag_enabled: knowledgeRagEnabled,
+      ...(knowledgeSelectionReady
+        ? { llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds }
+        : {}),
     }),
-    [settings.context, knowledgeRagEnabled],
+    [
+      settings.context,
+      knowledgeRagEnabled,
+      knowledgeSelectionReady,
+      selectedKnowledgeBaseIds,
+    ],
   );
   const [mounted, setMounted] = useState(false);
   const { tokenUsageEnabled } = useModels();
@@ -150,6 +174,10 @@ export default function ChatPage() {
   const { selectedArtifact } = useArtifacts();
   useSpecificChatMode();
 
+  useEffect(() => {
+    activeThreadIdRef.current = threadId;
+  }, [threadId]);
+
   useEffect(() => {
     setMounted(true);
   }, []);
@@ -158,12 +186,54 @@ export default function ChatPage() {
     if (isNewThread) {
       setHasStartedConversation(false);
       setPromptPrefixOn(false);
+      setSelectedKnowledgeBaseIds([]);
+      setKnowledgeSelectionReady(false);
+      setKnowledgeSelectionLoading(false);
+      knowledgeSelectionThread.current = "__new__";
       // Pre-select the agent the user last started a conversation with so a
       // fresh chat defaults to it. Validated against the known agent list below.
       setSelectedAgentId(getLastAgentId());
     }
   }, [isNewThread, threadId]);
 
+  // The knowledge-base choice belongs to the conversation, not to a browser
+  // component instance. Restore it from LangGraph thread metadata whenever an
+  // existing conversation is opened. An explicit empty array means the user
+  // deliberately disabled LLMWiki retrieval for that conversation.
+  useEffect(() => {
+    if (isNewThread || !threadId || knowledgeSelectionThread.current === threadId) {
+      return;
+    }
+    knowledgeSelectionThread.current = threadId;
+    setKnowledgeSelectionLoading(true);
+    void getAPIClient(isMock)
+      .threads.get(threadId)
+      .then((record) => {
+        if (knowledgeSelectionThread.current !== threadId) return;
+        const metadata = record.metadata as Record<string, unknown> | undefined;
+        const raw = metadata?.llmwiki_knowledge_base_ids;
+        if (Array.isArray(raw)) {
+          setSelectedKnowledgeBaseIds(
+            raw.map((item) => String(item).trim()).filter(Boolean),
+          );
+          setKnowledgeSelectionReady(true);
+        } else {
+          setSelectedKnowledgeBaseIds([]);
+          setKnowledgeSelectionReady(false);
+        }
+      })
+      .catch(() => {
+        if (knowledgeSelectionThread.current === threadId) {
+          setKnowledgeSelectionReady(false);
+        }
+      })
+      .finally(() => {
+        if (knowledgeSelectionThread.current === threadId) {
+          setKnowledgeSelectionLoading(false);
+        }
+      });
+  }, [isMock, isNewThread, threadId]);
+
   // Drop a restored last-used agent that is no longer in the selector list
   // (deleted / unpublished / no longer curated), so we never hand off to a
   // dead agent. Wait for the list to load before deciding.
@@ -175,6 +245,8 @@ export default function ChatPage() {
     if (known.length === 0) return;
     if (!known.some((a) => a.id === selectedAgentId)) {
       setSelectedAgentId(null);
+      setSelectedKnowledgeBaseIds([]);
+      setKnowledgeSelectionReady(false);
     }
   }, [selectedAgentId, selectorAgents, mineAgents, squareAgents, selectorLoading]);
 
@@ -183,8 +255,13 @@ export default function ChatPage() {
   const [thread, sendMessage, isUploading] = useThreadStream({
     threadId: isNewThread ? undefined : threadId,
     context: streamContext,
+    threadMetadata: knowledgeSelectionReady
+      ? { llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds }
+      : undefined,
     isMock,
     onStart: (createdThreadId) => {
+      knowledgeSelectionThread.current = createdThreadId;
+      activeThreadIdRef.current = createdThreadId;
       setThreadId(createdThreadId);
       setIsNewThread(false);
       // Keep the current component mounted while updating the hash route.
@@ -210,6 +287,12 @@ export default function ChatPage() {
       } catch {
         /* 上报绝不影响问答 */
       }
+      queueLlmWikiConversationDeposit({
+        threadId: activeThreadIdRef.current,
+        messages: state.messages,
+        assistantId: selectedAgentId,
+        knowledgeBaseIds: selectedKnowledgeBaseIds,
+      });
       if (document.hidden || !document.hasFocus()) {
         let body = "Conversation finished";
         const lastMessage = state.messages.at(-1);
@@ -226,6 +309,20 @@ export default function ChatPage() {
       }
     },
   });
+  const singleRoundRag = useSingleRoundRagMessages(threadId);
+  const singleRoundRagSelected = isSingleRoundRagProfile(settings.context);
+  const displayThread = useMemo(() => {
+    if (singleRoundRag.messages.length === 0 && !singleRoundRag.isLoading) {
+      return thread;
+    }
+    const messages = [...thread.messages, ...singleRoundRag.messages];
+    return {
+      ...thread,
+      values: { ...thread.values, messages },
+      messages,
+      isLoading: thread.isLoading || singleRoundRag.isLoading,
+    } as typeof thread;
+  }, [singleRoundRag.isLoading, singleRoundRag.messages, thread]);
 
   const writingArtifactPath = useMemo(() => {
     const isMarkdown = (path: string | null | undefined) =>
@@ -240,6 +337,46 @@ export default function ChatPage() {
 
   const handleSubmit = useCallback(
     (message: PromptInputMessage) => {
+      if (singleRoundRagSelected) {
+        if (message.files && message.files.length > 0) {
+          toast.error("单轮 RAG 问答暂不支持附件，请移除附件后重试。");
+          return;
+        }
+        setHasStartedConversation(true);
+        window.dispatchEvent(
+          new CustomEvent("workspace:sandbox-resume-autoscroll"),
+        );
+        void (async () => {
+          try {
+            let targetThreadId = threadId;
+            if (isNewThread) {
+              const created = await getAPIClient(isMock).threads.create({});
+              targetThreadId = created.thread_id;
+              setThreadId(targetThreadId);
+              setIsNewThread(false);
+              history.replaceState(
+                null,
+                "",
+                `${window.location.pathname}${window.location.search}#${routeBase}/chats/${targetThreadId}`,
+              );
+              const title = message.text.trim().replace(/\s+/g, " ").slice(0, 60);
+              if (title) {
+                void getAPIClient(isMock).threads
+                  .updateState(targetThreadId, { values: { title } })
+                  .catch(() => undefined);
+              }
+            }
+            await singleRoundRag.submit({
+              targetThreadId,
+              query: message.text,
+              modelName: settings.context.model_name ?? "OpenAI3",
+            });
+          } catch (error) {
+            toast.error(error instanceof Error ? error.message : "单轮 RAG 问答失败。");
+          }
+        })();
+        return;
+      }
       // If the user picked an agent before sending the opening turn, hand off
       // to AgentChatPage so the conversation runs against that agent. We stash
       // the pending text in sessionStorage because the next/navigation shim
@@ -262,7 +399,12 @@ export default function ChatPage() {
         void (async () => {
           try {
             const created = await getAPIClient(isMock).threads.create({
-              metadata: { agent_id: selectedAgentId },
+              metadata: {
+                agent_id: selectedAgentId,
+                ...(knowledgeSelectionReady
+                  ? { llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds }
+                  : {}),
+              },
             });
             sessionStorage.setItem(
               "pendingAgentMessage",
@@ -270,6 +412,9 @@ export default function ChatPage() {
                 agentId: selectedAgentId,
                 threadId: created.thread_id,
                 text,
+                ...(knowledgeSelectionReady
+                  ? { knowledgeBaseIds: selectedKnowledgeBaseIds }
+                  : {}),
               }),
             );
             saveLastAgentId(selectedAgentId);
@@ -328,11 +473,19 @@ export default function ChatPage() {
       hideAdminPrompt,
       preferencesLoading,
       selectedAgentId,
+      selectedKnowledgeBaseIds,
+      knowledgeSelectionReady,
       agentHandoffPending,
       isMock,
       router,
       settings.context.writing_mode,
+      settings.context.model_name,
       writingArtifactPath,
+      singleRoundRag,
+      singleRoundRagSelected,
+      routeBase,
+      setIsNewThread,
+      setThreadId,
     ],
   );
 
@@ -418,11 +571,17 @@ export default function ChatPage() {
   // Passing null (the ✕ clear) wipes the stored preference.
   const handleAgentChange = useCallback((agentId: string | null) => {
     setSelectedAgentId(agentId);
+    setSelectedKnowledgeBaseIds([]);
+    setKnowledgeSelectionReady(false);
     saveLastAgentId(agentId);
   }, []);
   const handleStop = useCallback(async () => {
+    if (singleRoundRag.isLoading) {
+      singleRoundRag.stop();
+      return;
+    }
     await thread.stop();
-  }, [thread]);
+  }, [singleRoundRag, thread]);
 
   const promptPrefixProp = useMemo(() => {
     if (!promptPrefixSettings?.enabled) return undefined;
@@ -468,7 +627,7 @@ export default function ChatPage() {
   const compactActionsHidden = isHideChromeActive();
 
   return (
-    <ThreadContext.Provider value={{ thread, isMock }}>
+    <ThreadContext.Provider value={{ thread: displayThread, isMock }}>
       <ChatBox threadId={threadId}>
         <div
           className={cn(
@@ -486,7 +645,7 @@ export default function ChatPage() {
             )}
           >
             <div className="flex w-full items-center text-sm font-medium">
-              <ThreadTitle threadId={threadId} thread={thread} />
+              <ThreadTitle threadId={threadId} thread={displayThread} />
             </div>
             <div className="flex items-center gap-2">
               {/* 仅在收起态显示「展开历史」钮；展开后由侧栏内（新对话右侧）的收起钮负责收起。 */}
@@ -505,7 +664,7 @@ export default function ChatPage() {
               )}
               <TokenUsageIndicator
                 enabled={tokenUsageEnabled}
-                messages={thread.messages}
+                messages={displayThread.messages}
               />
               <ExportTrigger threadId={threadId} />
               <KnowledgeSaveTrigger threadId={threadId} />
@@ -543,7 +702,7 @@ export default function ChatPage() {
                 <MessageList
                   className={cn("size-full", "pt-10")}
                   threadId={threadId}
-                  thread={thread}
+                  thread={displayThread}
                   paddingBottom={messageListPaddingBottom}
                   tokenUsageEnabled={tokenUsageEnabled}
                   // 输入框为底部绝对浮层（约 160px 高），按钮上移到其上方居中。
@@ -585,9 +744,9 @@ export default function ChatPage() {
                   <div className="absolute right-0 bottom-0 left-0">
                     <TodoList
                       className="bg-background/5"
-                      todos={thread.values.todos ?? []}
+                      todos={displayThread.values.todos ?? []}
                       hidden={
-                        !thread.values.todos || thread.values.todos.length === 0
+                        !displayThread.values.todos || displayThread.values.todos.length === 0
                       }
                     />
                   </div>
@@ -612,15 +771,18 @@ export default function ChatPage() {
                       status={
                         thread.error
                           ? "error"
-                          : thread.isLoading
+                          : displayThread.isLoading
                             ? "streaming"
                             : "ready"
                       }
                       context={settings.context}
+                      extraModels={SINGLE_ROUND_RAG_MODELS}
                       disabled={
                         env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" ||
                         isUploading ||
-                        agentHandoffPending
+                        agentHandoffPending ||
+                        knowledgeSelectionLoading ||
+                        singleRoundRag.isLoading
                       }
                       onContextChange={(context) =>
                         setSettings("context", context)
@@ -634,6 +796,22 @@ export default function ChatPage() {
                             }
                           : undefined
                       }
+                      knowledgeSelector={
+                        isLandingState ? (
+                          <LlmWikiKnowledgeSelector
+                            source={selectedAgentId ? "agent" : "all"}
+                            agentId={selectedAgentId}
+                            value={selectedKnowledgeBaseIds}
+                            onChange={changeKnowledgeSelection}
+                            autoSelectAll={!!selectedAgentId}
+                            disabled={
+                              env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" ||
+                              knowledgeSelectionLoading
+                            }
+                            label="知识空间"
+                          />
+                        ) : undefined
+                      }
                       onFollowupsVisibilityChange={setShowFollowups}
                       onSubmit={handleSubmit}
                       onStop={handleStop}
@@ -664,7 +842,7 @@ export default function ChatPage() {
           */}
           {!isLandingState && (
             <QuestionNavigator
-              messages={thread.messages}
+              messages={displayThread.messages}
               className="top-16 right-0 bottom-48 left-0"
             />
           )}

frontend-web/src/pages/KnowledgeBasePage.tsx

@@ -1,5 +1,5 @@
 import { Loader2 } from "lucide-react";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { type ReactNode, useEffect, useMemo, useRef, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
 import { toast } from "sonner";
 
@@ -530,7 +530,11 @@ function VaultPageDialog({
   );
 }
 
-export default function KnowledgeBasePage() {
+export default function KnowledgeBasePage({
+  headerExtraActions,
+}: {
+  headerExtraActions?: ReactNode;
+} = {}) {
   const navigate = useNavigate();
   const { noteId } = useParams<{ noteId: string }>();
 
@@ -653,6 +657,7 @@ export default function KnowledgeBasePage() {
         onCreate={() => setCreateOpen(true)}
         onManageFolders={() => setFoldersOpen(true)}
         onManageTemplates={() => setTemplatesOpen(true)}
+        extraActions={headerExtraActions}
       />
 
       <div

frontend-web/src/pages/LlmWikiKnowledgePage.tsx

@@ -0,0 +1,91 @@
+import { Loader2, Settings2 } from "lucide-react";
+import { useState } from "react";
+import { Navigate } from "react-router-dom";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { getStoredAuth } from "@/core/auth";
+import { useLlmWikiRuntime } from "@/strategy-components/api/llmwiki";
+import WeKnoraKnowledgeWorkspace, {
+  ConnectionSettings,
+} from "@/strategy-components/components/resource-management/llmwiki/WeKnoraKnowledgeWorkspace";
+import WeKnoraKnowledgeDetailPage from "@/strategy-components/components/resource-management/llmwiki/WeKnoraKnowledgeDetailPage";
+
+import KnowledgeBasePage from "./KnowledgeBasePage";
+import KnowledgeGraphPage from "./KnowledgeGraphPage";
+
+type LlmWikiKnowledgePageMode = "list" | "detail" | "graph";
+
+function RuntimeLoading() {
+  return (
+    <div className="flex h-full min-h-64 items-center justify-center text-sm text-muted-foreground">
+      <Loader2 className="mr-2 size-5 animate-spin" />
+      正在读取 LLMWiki 运行模式
+    </div>
+  );
+}
+
+function AdminWeKnoraSettingsButton() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button size="sm" variant="outline" onClick={() => setOpen(true)}>
+        <Settings2 className="mr-2 size-4" />
+        配置 WeKnora
+      </Button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="max-w-4xl">
+          <DialogHeader>
+            <DialogTitle>LLMWiki 运行模式</DialogTitle>
+          </DialogHeader>
+          <ConnectionSettings />
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+
+function LegacyKnowledgePage() {
+  const isAdmin = getStoredAuth()?.system_role === "admin";
+
+  return (
+    <KnowledgeBasePage
+      headerExtraActions={isAdmin ? <AdminWeKnoraSettingsButton /> : undefined}
+    />
+  );
+}
+
+export default function LlmWikiKnowledgePage({
+  mode = "list",
+}: {
+  mode?: LlmWikiKnowledgePageMode;
+}) {
+  const runtime = useLlmWikiRuntime();
+
+  if (runtime.isLoading) {
+    return <RuntimeLoading />;
+  }
+
+  if (runtime.isError || runtime.data?.provider !== "weknora") {
+    if (mode === "graph") {
+      return <KnowledgeGraphPage />;
+    }
+    return <LegacyKnowledgePage />;
+  }
+
+  if (mode === "graph") {
+    return <Navigate to="/page/workspace/knowledge" replace />;
+  }
+
+  if (mode === "detail") {
+    return <WeKnoraKnowledgeDetailPage />;
+  }
+
+  return <WeKnoraKnowledgeWorkspace />;
+}

frontend-web/src/pages/ModelManagementPage.tsx

@@ -0,0 +1,491 @@
+import {
+  BotIcon,
+  ChevronDownIcon,
+  CircleAlertIcon,
+  CpuIcon,
+  EyeIcon,
+  KeyRoundIcon,
+  LoaderCircleIcon,
+  PlusIcon,
+  RefreshCwIcon,
+  Settings2Icon,
+  SparklesIcon,
+  Trash2Icon,
+  WrenchIcon,
+} from "lucide-react";
+import { useMemo, useState, type ReactNode } from "react";
+import {
+  Button as TButton,
+  Dialog,
+  Input,
+  InputNumber,
+  MessagePlugin,
+  Select,
+  Switch,
+  Tag,
+  Textarea,
+} from "tdesign-react";
+
+import {
+  type ManagedModel,
+  type ModelSavePayload,
+  useDeleteManagedModel,
+  useManagedModels,
+  useSaveManagedModel,
+  useTestManagedModel,
+} from "@/core/model-management";
+import {
+  WorkspaceBody,
+  WorkspaceContainer,
+  WorkspaceHeader,
+} from "@/components/workspace/workspace-container";
+
+type ModelDraft = ModelSavePayload & {
+  api_key: string;
+  keep_existing_key: boolean;
+  extra_settings_text: string;
+};
+
+const PROVIDER_OPTIONS = [
+  { label: "OpenAI 兼容接口", value: "langchain_openai:ChatOpenAI" },
+  { label: "Anthropic", value: "langchain_anthropic:ChatAnthropic" },
+  { label: "Google Gemini", value: "langchain_google_genai:ChatGoogleGenerativeAI" },
+  { label: "Groq", value: "langchain_groq:ChatGroq" },
+  { label: "Ollama", value: "langchain_ollama:ChatOllama" },
+];
+
+const emptyDraft = (): ModelDraft => ({
+  name: "",
+  display_name: "",
+  description: "",
+  use: "langchain_openai:ChatOpenAI",
+  model: "",
+  api_key: "",
+  keep_existing_key: false,
+  clear_api_key: false,
+  base_url: "",
+  request_timeout: 30,
+  max_retries: 2,
+  max_tokens: undefined,
+  temperature: undefined,
+  stream_usage: true,
+  supports_thinking: false,
+  supports_reasoning_effort: false,
+  supports_vision: false,
+  when_thinking_enabled: null,
+  when_thinking_disabled: null,
+  thinking: null,
+  use_responses_api: null,
+  output_version: null,
+  extra_settings: {},
+  extra_settings_text: "{}",
+});
+
+function draftFromModel(model: ManagedModel): ModelDraft {
+  return {
+    ...model,
+    api_key: "",
+    keep_existing_key: model.api_key_configured,
+    clear_api_key: false,
+    extra_settings_text: JSON.stringify(model.extra_settings ?? {}, null, 2),
+  };
+}
+
+function optionalString(value: string | null | undefined): string | null {
+  const normalized = (value ?? "").trim();
+  return normalized || null;
+}
+
+function toNumber(value: number | string | null | undefined): number | undefined {
+  if (value === "" || value === null || value === undefined) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function buildPayload(draft: ModelDraft): ModelSavePayload {
+  let extraSettings: Record<string, unknown> = {};
+  try {
+    const parsed = JSON.parse(draft.extra_settings_text || "{}") as unknown;
+    if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+      throw new Error("额外参数必须是 JSON 对象");
+    }
+    extraSettings = parsed as Record<string, unknown>;
+  } catch (error) {
+    throw error instanceof Error ? error : new Error("额外参数不是有效 JSON");
+  }
+  const payload: ModelSavePayload = {
+    name: draft.name.trim(),
+    display_name: optionalString(draft.display_name),
+    description: optionalString(draft.description),
+    use: draft.use.trim(),
+    model: draft.model.trim(),
+    clear_api_key: Boolean(draft.clear_api_key),
+    base_url: optionalString(draft.base_url),
+    request_timeout: toNumber(draft.request_timeout),
+    max_retries: toNumber(draft.max_retries),
+    max_tokens: toNumber(draft.max_tokens),
+    temperature: toNumber(draft.temperature),
+    stream_usage: draft.stream_usage,
+    supports_thinking: draft.supports_thinking,
+    supports_reasoning_effort: draft.supports_reasoning_effort,
+    supports_vision: draft.supports_vision,
+    when_thinking_enabled: draft.when_thinking_enabled,
+    when_thinking_disabled: draft.when_thinking_disabled,
+    thinking: draft.thinking,
+    use_responses_api: draft.use_responses_api,
+    output_version: optionalString(draft.output_version),
+    extra_settings: extraSettings,
+  };
+  if (draft.api_key.trim()) payload.api_key = draft.api_key.trim();
+  return payload;
+}
+
+function StatCard({ icon: Icon, label, value }: { icon: typeof CpuIcon; label: string; value: number }) {
+  return (
+    <div className="flex items-center gap-3 rounded-lg border border-border bg-card px-4 py-3 shadow-sm">
+      <span className="flex size-10 items-center justify-center rounded-lg bg-primary/10 text-primary"><Icon className="size-5" /></span>
+      <div><div className="text-xl font-semibold tabular-nums">{value}</div><div className="text-xs text-muted-foreground">{label}</div></div>
+    </div>
+  );
+}
+
+function Field({ label, required = false, children }: { label: string; required?: boolean; children: ReactNode }) {
+  return <label className="space-y-1.5 text-sm font-medium">{label}{required && <span className="ml-1 text-destructive">*</span>}{children}</label>;
+}
+
+function ModelCapabilityBadge({
+  icon: Icon,
+  label,
+  className,
+}: {
+  icon?: typeof KeyRoundIcon;
+  label: string;
+  className: string;
+}) {
+  return (
+    <span className={`inline-flex h-7 items-center gap-1 whitespace-nowrap rounded px-2 text-xs font-medium leading-none ${className}`}>
+      {Icon && <Icon aria-hidden className="block size-3.5 shrink-0" />}
+      <span className="block leading-none">{label}</span>
+    </span>
+  );
+}
+
+function showGlobalMessage(
+  theme: "success" | "error" | "warning",
+  content: string,
+) {
+  // Schedule after the modal state update so the message is rendered above
+  // the page, rather than inside or behind a closing dialog.
+  window.setTimeout(() => {
+    MessagePlugin.closeAll();
+    void MessagePlugin[theme]({
+      content,
+      duration: 5_000,
+      placement: "top",
+      zIndex: 10_000,
+      attach: () => document.body,
+    });
+  }, 0);
+}
+
+function ModelEditor({ model, onClose }: { model: ManagedModel | null; onClose: () => void }) {
+  const isNew = model === null;
+  const [draft, setDraft] = useState<ModelDraft>(() => model ? draftFromModel(model) : emptyDraft());
+  const [advanced, setAdvanced] = useState(false);
+  const [testResult, setTestResult] = useState<{ success: boolean; latency: number; message: string; preview?: string | null } | null>(null);
+  const save = useSaveManagedModel();
+  const test = useTestManagedModel();
+  const patch = (next: Partial<ModelDraft>) => setDraft((current) => ({ ...current, ...next }));
+
+  const handleTest = async () => {
+    try {
+      const payload = buildPayload(draft);
+      const result = await test.mutateAsync(payload);
+      setTestResult({ success: result.success, latency: result.latency_ms, message: result.message, preview: result.preview });
+      if (!result.success) return void showGlobalMessage("error", `连接失败：${result.message}`);
+      showGlobalMessage("success", `连接成功${result.latency_ms ? `，${result.latency_ms} ms` : ""}`);
+    } catch (error) {
+      showGlobalMessage("error", error instanceof Error ? error.message : "连接测试失败");
+    }
+  };
+
+  const handleSave = async () => {
+    try {
+      const payload = buildPayload(draft);
+      if (!payload.name || !payload.use || !payload.model) {
+        return void showGlobalMessage("warning", "请填写模型标识、驱动与实际模型名");
+      }
+      await save.mutateAsync({ name: model?.name ?? payload.name, payload, isNew });
+      onClose();
+      showGlobalMessage(
+        "success",
+        isNew
+          ? `模型“${payload.name}”已添加，所有页面的模型选择器已刷新。`
+          : `模型“${payload.name}”的配置已保存并立即生效。`,
+      );
+    } catch (error) {
+      showGlobalMessage("error", error instanceof Error ? error.message : "保存模型配置失败");
+    }
+  };
+
+  return (
+    <Dialog
+      visible
+      header={isNew ? "添加模型" : `编辑模型：${model?.display_name || model?.name}`}
+      placement="center"
+      width={860}
+      zIndex={3200}
+      confirmBtn={{ content: isNew ? "添加并启用" : "保存配置", theme: "primary" }}
+      cancelBtn="取消"
+      confirmLoading={save.isPending}
+      onClose={onClose}
+      onConfirm={() => void handleSave()}
+      onCancel={onClose}
+    >
+      <div className="max-h-[70vh] space-y-5 overflow-y-auto px-1 py-1 pr-3">
+        <div className="rounded-lg border border-primary/20 bg-primary/5 px-3 py-2 text-sm text-muted-foreground">
+          保存会直接更新当前部署的 <code className="rounded bg-background px-1 py-0.5">config.yaml</code> 模型段，自动备份并热刷新；不会中断已开始的会话。
+        </div>
+        <section className="grid gap-4 md:grid-cols-2">
+          <Field label="稳定标识" required><Input value={draft.name} disabled={!isNew} placeholder="例如 deepseek-chat" tips={isNew ? "保存后不可修改，用于智能体和运行配置引用。" : "稳定标识不可修改，避免已有配置失效。"} onChange={(value) => patch({ name: String(value) })} /></Field>
+          <Field label="显示名称"><Input value={draft.display_name ?? ""} placeholder="例如 DeepSeek Chat" onChange={(value) => patch({ display_name: String(value) })} /></Field>
+          <Field label="模型驱动" required><Select value={draft.use} options={PROVIDER_OPTIONS} filterable creatable inputProps={{ placeholder: "选择或输入 use 类路径" }} onChange={(value) => patch({ use: String(value) })} /></Field>
+          <Field label="实际模型名" required><Input value={draft.model} placeholder="例如 deepseek-chat" onChange={(value) => patch({ model: String(value) })} /></Field>
+          <Field label="Base URL"><Input value={draft.base_url ?? ""} type="url" placeholder="https://api.example.com/v1" onChange={(value) => patch({ base_url: String(value) })} /></Field>
+          <Field label="API Key"><Input value={draft.api_key} type="password" placeholder={draft.keep_existing_key && !draft.clear_api_key ? "已配置，留空则保持不变" : "可填写密钥或 $ENVIRONMENT_VARIABLE"} onChange={(value) => patch({ api_key: String(value), clear_api_key: false })} /></Field>
+          {draft.keep_existing_key && !draft.api_key && <div className="md:col-span-2 flex items-center gap-2 text-xs text-muted-foreground"><KeyRoundIcon className="size-3.5" />已配置密钥{model?.api_key_source ? `（环境变量 ${model.api_key_source}）` : ""}，不会回显。<TButton theme="default" variant="text" size="small" onClick={() => patch({ clear_api_key: !draft.clear_api_key })}>{draft.clear_api_key ? "撤销清除" : "清除密钥"}</TButton></div>}
+          <div className="md:col-span-2"><Field label="描述"><Textarea value={draft.description ?? ""} autosize={{ minRows: 2, maxRows: 4 }} placeholder="说明模型适用的任务与限制" onChange={(value) => patch({ description: String(value) })} /></Field></div>
+        </section>
+        <section className="rounded-lg border border-border p-4">
+          <div className="mb-2"><h3 className="font-medium">能力声明</h3><p className="mt-1 text-xs text-muted-foreground">这些标识决定哪些页面会向模型提供思考、视觉或工具调用入口。</p></div>
+          <div className="flex flex-wrap gap-x-5 gap-y-3 text-sm"><span className="flex items-center gap-2"><Switch value={draft.supports_thinking} onChange={(value) => patch({ supports_thinking: Boolean(value) })} />支持思考</span><span className="flex items-center gap-2"><Switch value={draft.supports_vision} onChange={(value) => patch({ supports_vision: Boolean(value) })} />支持视觉</span><span className="flex items-center gap-2"><Switch value={draft.supports_reasoning_effort} onChange={(value) => patch({ supports_reasoning_effort: Boolean(value) })} />推理档位</span></div>
+        </section>
+        <div className="flex items-center justify-between border-t pt-4"><TButton theme="default" variant="outline" loading={test.isPending} onClick={() => void handleTest()}><WrenchIcon className="mr-1.5 size-4" />测试连接</TButton><TButton theme="default" variant="text" onClick={() => setAdvanced((value) => !value)}><Settings2Icon className="mr-1.5 size-4" />高级配置 <ChevronDownIcon className={`ml-1 size-4 transition-transform ${advanced ? "rotate-180" : ""}`} /></TButton></div>
+        {testResult && <div className={`rounded-lg border px-3 py-2 text-sm ${testResult.success ? "border-primary/20 bg-primary/5 text-foreground" : "border-destructive/25 bg-destructive/5 text-destructive"}`}><div className="font-medium">{testResult.success ? "连接成功" : "连接失败"}{testResult.success && testResult.latency ? ` · ${testResult.latency} ms` : ""}</div><p className="mt-1 break-words text-xs opacity-80">{testResult.preview || testResult.message}</p></div>}
+        {advanced && <section className="space-y-4 rounded-lg border border-dashed border-border bg-muted/10 p-4"><div className="grid gap-4 md:grid-cols-3"><Field label="请求超时（秒）"><InputNumber value={draft.request_timeout ?? ""} min={1} max={600} onChange={(value) => patch({ request_timeout: toNumber(value) })} /></Field><Field label="最大重试次数"><InputNumber value={draft.max_retries ?? ""} min={0} max={20} onChange={(value) => patch({ max_retries: toNumber(value) })} /></Field><Field label="最大输出 Token"><InputNumber value={draft.max_tokens ?? ""} min={1} max={1_000_000} onChange={(value) => patch({ max_tokens: toNumber(value) })} /></Field><Field label="温度"><InputNumber value={draft.temperature ?? ""} min={0} max={2} step={0.1} decimalPlaces={1} onChange={(value) => patch({ temperature: toNumber(value) })} /></Field><span className="flex items-end gap-2 pb-1 text-sm font-medium"><Switch value={draft.stream_usage ?? true} onChange={(value) => patch({ stream_usage: Boolean(value) })} />流式 Token 统计</span></div><Field label="额外参数 JSON"><Textarea value={draft.extra_settings_text} autosize={{ minRows: 4, maxRows: 10 }} placeholder={'{\n  "extra_body": {}\n}'} onChange={(value) => patch({ extra_settings_text: String(value) })} /><p className="text-xs font-normal text-muted-foreground">保留并编辑配置文件中未在基础表单展示的兼容参数。必须为 JSON 对象。</p></Field></section>}
+      </div>
+    </Dialog>
+  );
+}
+
+export default function ModelManagementPage() {
+  const { data, isLoading, error, refetch, isFetching } = useManagedModels();
+  const [search, setSearch] = useState("");
+  const [filter, setFilter] = useState<"all" | "thinking" | "vision">("all");
+  const [editor, setEditor] = useState<ManagedModel | null | "new">(null);
+  const [deleteTarget, setDeleteTarget] = useState<ManagedModel | null>(null);
+  const remove = useDeleteManagedModel();
+  const models = useMemo(() => {
+    const keyword = search.trim().toLowerCase();
+    return (data?.models ?? []).filter((model) => {
+      const matchesFilter = filter === "all" || (filter === "thinking" ? model.supports_thinking : model.supports_vision);
+      const matchesSearch = !keyword || [model.name, model.display_name, model.model, model.use].filter(Boolean).join(" ").toLowerCase().includes(keyword);
+      return matchesFilter && matchesSearch;
+    });
+  }, [data?.models, filter, search]);
+  const stats = useMemo(() => ({ total: data?.models.length ?? 0, thinking: data?.models.filter((item) => item.supports_thinking).length ?? 0, vision: data?.models.filter((item) => item.supports_vision).length ?? 0 }), [data?.models]);
+  const handleDelete = async () => {
+    if (!deleteTarget)
+      return;
+    try {
+      await remove.mutateAsync(deleteTarget.name);
+      const deletedName = deleteTarget.name;
+      setDeleteTarget(null);
+      showGlobalMessage("success", `模型“${deletedName}”已删除，配置已立即生效。`);
+    }
+    catch (error) {
+      showGlobalMessage("error", error instanceof Error ? error.message : "删除模型失败，请稍后重试。");
+    }
+  };
+  return (
+    <WorkspaceContainer>
+      <WorkspaceHeader />
+      <WorkspaceBody>
+        <main className="flex size-full min-h-0 flex-col overflow-y-auto bg-background px-6 py-5 md:px-8">
+          <div className="mx-auto flex w-full max-w-7xl flex-col gap-5">
+            <header className="flex flex-wrap items-start justify-between gap-4">
+              <div>
+                <div className="flex items-center gap-2">
+                  <span className="flex size-9 items-center justify-center rounded-lg bg-primary/10 text-primary">
+                    <CpuIcon className="size-5" />
+                  </span>
+                  <h1 className="text-2xl font-semibold tracking-tight">模型配置</h1>
+                </div>
+                <p className="mt-2 max-w-3xl text-sm leading-6 text-muted-foreground">
+                  管理当前部署 <code className="rounded bg-muted px-1 py-0.5">config.yaml</code> 中的对话模型。保存后所有页面立即可选；密钥仅可写入，永不回显。
+                </p>
+              </div>
+              <div className="flex flex-wrap items-center gap-2">
+                <TButton theme="default" variant="outline" loading={isFetching} onClick={() => void refetch()}>
+                  <RefreshCwIcon className="mr-1.5 size-4" />刷新
+                </TButton>
+                <TButton theme="primary" onClick={() => setEditor("new")}>
+                  <PlusIcon className="mr-1.5 size-4" />添加模型
+                </TButton>
+              </div>
+            </header>
+
+            <div className="grid gap-3 sm:grid-cols-3">
+              <StatCard icon={BotIcon} label="已配置模型" value={stats.total} />
+              <StatCard icon={SparklesIcon} label="支持思考" value={stats.thinking} />
+              <StatCard icon={EyeIcon} label="支持视觉" value={stats.vision} />
+            </div>
+
+            <section className="rounded-xl border border-border bg-card shadow-sm">
+              <div className="flex flex-wrap items-center justify-between gap-3 border-b px-4 py-3">
+                <div className="flex flex-wrap items-center gap-2">
+                  {([
+                    ["all", "全部"],
+                    ["thinking", "支持思考"],
+                    ["vision", "支持视觉"],
+                  ] as const).map(([value, label]) => (
+                    <TButton
+                      key={value}
+                      theme={filter === value ? "primary" : "default"}
+                      variant={filter === value ? "base" : "text"}
+                      size="small"
+                      onClick={() => setFilter(value)}
+                    >
+                      {label}
+                    </TButton>
+                  ))}
+                </div>
+                <Input
+                  value={search}
+                  placeholder="搜索名称、模型或驱动"
+                  clearable
+                  className="w-full sm:w-72"
+                  onChange={(value) => setSearch(String(value))}
+                />
+              </div>
+
+              {isLoading && (
+                <div className="flex h-52 items-center justify-center gap-2 text-sm text-muted-foreground">
+                  <LoaderCircleIcon className="size-4 animate-spin" />加载模型配置…
+                </div>
+              )}
+              {error && (
+                <div className="m-4 flex items-start gap-2 rounded-lg border border-destructive/25 bg-destructive/5 p-3 text-sm text-destructive">
+                  <CircleAlertIcon className="mt-0.5 size-4" />{error.message}
+                </div>
+              )}
+              {!isLoading && !error && models.length === 0 && (
+                <div className="flex h-52 flex-col items-center justify-center gap-2 text-sm text-muted-foreground">
+                  <CpuIcon className="size-7" />没有匹配的模型配置
+                </div>
+              )}
+              {!isLoading && !error && models.length > 0 && (
+                <div className="grid gap-3 p-4 lg:grid-cols-2">
+                  {models.map((model) => (
+                    <article key={model.name} className="rounded-lg border border-border bg-background p-4 transition-colors hover:border-primary/35">
+                      <div className="flex items-start justify-between gap-3">
+                        <div className="min-w-0">
+                          <div className="flex flex-wrap items-center gap-2">
+                            <h2 className="truncate font-semibold">{model.display_name || model.name}</h2>
+                            <Tag theme="success" variant="light" size="small">config.yaml</Tag>
+                          </div>
+                          <p className="mt-1 truncate font-mono text-xs text-muted-foreground">{model.name}</p>
+                        </div>
+                        <div className="flex shrink-0 items-center gap-1">
+                          <TButton theme="default" variant="outline" size="small" onClick={() => setEditor(model)}>
+                            配置
+                          </TButton>
+                          <TButton
+                            theme="danger"
+                            variant="text"
+                            size="small"
+                            aria-label={"删除模型 " + (model.display_name || model.name)}
+                            onClick={() => setDeleteTarget(model)}
+                          >
+                            <Trash2Icon className="mr-1 size-3.5" />删除
+                          </TButton>
+                        </div>
+                      </div>
+                      {model.description ? (
+                        <p className="mt-3 line-clamp-2 min-h-10 text-sm leading-5 text-muted-foreground">{model.description}</p>
+                      ) : (
+                        <p className="mt-3 min-h-10 text-sm leading-5 text-muted-foreground">未填写描述</p>
+                      )}
+                      <div className="mt-3 grid gap-2 border-t pt-3 text-xs text-muted-foreground sm:grid-cols-2">
+                        <span className="truncate" title={model.use}>驱动：{model.use}</span>
+                        <span className="truncate" title={model.model}>模型：{model.model}</span>
+                      </div>
+                      <div className="mt-3 flex flex-wrap items-center gap-1.5">
+                        {model.api_key_configured && (
+                          <ModelCapabilityBadge
+                            icon={KeyRoundIcon}
+                            label="已配置密钥"
+                            className="bg-muted text-foreground"
+                          />
+                        )}
+                        {model.supports_thinking && (
+                          <ModelCapabilityBadge
+                            icon={SparklesIcon}
+                            label="思考"
+                            className="bg-primary/10 text-primary"
+                          />
+                        )}
+                        {model.supports_vision && (
+                          <ModelCapabilityBadge
+                            icon={EyeIcon}
+                            label="视觉"
+                            className="bg-amber-500/10 text-amber-700 dark:text-amber-300"
+                          />
+                        )}
+                        {model.supports_reasoning_effort && (
+                          <ModelCapabilityBadge
+                            label="推理档位"
+                            className="bg-muted text-muted-foreground"
+                          />
+                        )}
+                      </div>
+                    </article>
+                  ))}
+                </div>
+              )}
+            </section>
+
+            {data?.config_path && (
+              <p className="text-xs text-muted-foreground">
+                当前配置文件：<code>{data.config_path}</code>
+                {data.updated_at ? " · 最近更新 " + new Date(data.updated_at).toLocaleString() : ""}
+              </p>
+            )}
+          </div>
+        </main>
+      </WorkspaceBody>
+
+      {editor !== null && (
+        <ModelEditor
+          key={editor === "new" ? "new" : editor.name}
+          model={editor === "new" ? null : editor}
+          onClose={() => setEditor(null)}
+        />
+      )}
+
+      {deleteTarget && (
+        <Dialog
+          visible
+          header="删除模型"
+          placement="center"
+          width={440}
+          zIndex={3200}
+          confirmBtn={{ content: "删除", theme: "danger" }}
+          cancelBtn="取消"
+          confirmLoading={remove.isPending}
+          onClose={() => {
+            if (!remove.isPending) setDeleteTarget(null);
+          }}
+          onCancel={() => {
+            if (!remove.isPending) setDeleteTarget(null);
+          }}
+          onConfirm={() => void handleDelete()}
+        >
+          <p className="text-sm leading-6 text-muted-foreground">
+            确定要删除模型 <code className="rounded bg-muted px-1 py-0.5">{deleteTarget.name}</code> 吗？删除后会立即更新运行中的模型配置，依赖它的智能体或任务可能无法继续使用。
+          </p>
+        </Dialog>
+      )}
+    </WorkspaceContainer>
+  );
+}

frontend-web/src/pages/NewAgentPage.tsx

@@ -31,6 +31,7 @@ import {
 } from "@/components/ui/select";
 import { Textarea } from "@/components/ui/textarea";
 import { ArtifactsProvider } from "@/components/workspace/artifacts";
+import { LlmWikiKnowledgeSelector } from "@/components/workspace/llmwiki-knowledge-selector";
 import {
   MessageList,
   type SetupAgentApprovalPayload,
@@ -95,6 +96,7 @@ export default function NewAgentPage() {
   const [isCreatingAgent, setIsCreatingAgent] = useState(false);
   const [isSavingDraft, setIsSavingDraft] = useState(false);
   const [selectedSkills, setSelectedSkills] = useState<string[]>([]);
+  const [selectedKnowledgeBaseIds, setSelectedKnowledgeBaseIds] = useState<string[]>([]);
   const [isSkillSelectionTouched, setIsSkillSelectionTouched] = useState(false);
   const [detailSkillName, setDetailSkillName] = useState<string | null>(null);
   // 恢复已有 bootstrap 会话时该 thread 已存在，无需再 create（置为 true，跳过创建）。
@@ -230,6 +232,7 @@ export default function NewAgentPage() {
           model: modelOverride,
           template_name: templateNameInput.trim(),
           seat_skill_directive: seatSkillDirectiveInput,
+          llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds,
         });
         setAgent(updated);
         return updated;
@@ -252,6 +255,7 @@ export default function NewAgentPage() {
         model: modelOverride,
         template_name: templateNameInput.trim(),
         seat_skill_directive: seatSkillDirectiveInput,
+        llmwiki_knowledge_base_ids: selectedKnowledgeBaseIds,
       });
       setAgentId(created.id);
       setAgent(created);
@@ -280,6 +284,7 @@ export default function NewAgentPage() {
     descriptionInput,
     modelInput,
     selectedSkills,
+    selectedKnowledgeBaseIds,
     soulInput,
     templateNameInput,
     seatSkillDirectiveInput,
@@ -590,6 +595,13 @@ export default function NewAgentPage() {
                   </p>
                 </div>
 
+                <LlmWikiKnowledgeSelector
+                  source="all"
+                  value={selectedKnowledgeBaseIds}
+                  onChange={setSelectedKnowledgeBaseIds}
+                  variant="panel"
+                />
+
                 <div className="space-y-2">
                   <label className="text-sm font-medium">SOUL.md</label>
                   <Textarea

frontend-web/src/pages/WorkspaceRoutes.tsx

@@ -35,14 +35,14 @@ import AdminScheduledTasksPage from './AdminScheduledTasksPage';
 import AdminSkillsPage from './AdminSkillsPage';
 import ScheduledTaskRunDetailPage from './ScheduledTaskRunDetailPage';
 import ScheduledTasksPage from './ScheduledTasksPage';
-import KnowledgeBasePage from './KnowledgeBasePage';
-import KnowledgeGraphPage from './KnowledgeGraphPage';
+import LlmWikiKnowledgePage from './LlmWikiKnowledgePage';
 import LlmMetricsPage from './LlmMetricsPage';
 import CheckpointMigrationPage from './CheckpointMigrationPage';
 import MemoryPage from './MemoryPage';
 import PromptPrefixSettingsPage from './PromptPrefixSettingsPage';
 import PrivateSquareSettingsPage from './PrivateSquareSettingsPage';
 import ModelConcurrencySettingsPage from './ModelConcurrencySettingsPage';
+import ModelManagementPage from './ModelManagementPage';
 import PublishSquaresSettingsPage from './PublishSquaresSettingsPage';
 import SkillCompressionSettingsPage from './SkillCompressionSettingsPage';
 import SkillEvolutionPage from './SkillEvolutionPage';
@@ -604,7 +604,7 @@ export default function WorkspaceRoutes({
           path="knowledge"
           element={
             <WorkspaceLayout {...layoutProps}>
-              <KnowledgeBasePage />
+              <LlmWikiKnowledgePage />
             </WorkspaceLayout>
           }
         />
@@ -612,7 +612,7 @@ export default function WorkspaceRoutes({
           path="knowledge/graph"
           element={
             <WorkspaceLayout {...layoutProps}>
-              <KnowledgeGraphPage />
+              <LlmWikiKnowledgePage mode="graph" />
             </WorkspaceLayout>
           }
         />
@@ -620,7 +620,7 @@ export default function WorkspaceRoutes({
           path="knowledge/:noteId"
           element={
             <WorkspaceLayout {...layoutProps}>
-              <KnowledgeBasePage />
+              <LlmWikiKnowledgePage mode="detail" />
             </WorkspaceLayout>
           }
         />
@@ -786,6 +786,18 @@ export default function WorkspaceRoutes({
             )
           }
         />
+        <Route
+          path="admin/models"
+          element={
+            getStoredAuth()?.system_role === 'admin' ? (
+              <WorkspaceLayout {...layoutProps}>
+                <ModelManagementPage />
+              </WorkspaceLayout>
+            ) : (
+              <Navigate to="/page/workspace/chats/new" replace />
+            )
+          }
+        />
         <Route
           path="settings/model-concurrency"
           element={

frontend-web/src/position-roundtable/README.md

@@ -24,11 +24,23 @@
 
 | 参数 | 是否必填 | 作用 |
 | --- | --- | --- |
-| `taskId` | 否 | 外部任务 ID。缺失时使用本地 mock 任务，便于演示和开发。 |
+| `taskId` | 否 | 外部任务 ID。传入后它是岗位会商的共享存储作用域；缺失时保持原有的个人会话逻辑。mock 仅提供任务卡片的显示兜底，绝不替换路由传入的 ID。 |
 | `sessionId` | 否 | 直接恢复指定岗位会商会话；缺失时页面会按 `taskId` 查找最近一条未归档会话。 |
 | `positionId` | 否 | 初始打开的岗位，同时同步顶部岗位选择器。无效值回退到 `intelligence`。 |
 | `new=1` | 否 | 强制不恢复历史会话，以新会话开始。 |
 
+传入 `taskId` 时，同一个任务下可以有多条会商会话，所有用户共享同一份历史、节点快照与 LangGraph 线程；当前 `user_id` 仅保留创建审计，不参与这些任务会话的读写过滤。页面恢复 `sessionId` 时会核验其 `externalTaskId` 与路由 `taskId` 一致，不一致会丢弃该会话并按当前任务重新发现历史。未传 `taskId` 时，会继续只读取当前用户的原有个人会话。
+
+### 外部系统按 taskId 对接
+
+1. 进入页面时将业务侧任务的稳定主键原样放入 URL。工作区入口使用 `/#/page/workspace/roundtable/position?taskId=<taskId>`；策略页入口也兼容 `/#/page/strategy/qa/position-roundtable?taskId=<taskId>`。不要使用任务标题、序号或每次请求都变化的临时 ID。
+2. 前端先调用 `GET /api/position-roundtable/sessions?external_task_id=<taskId>`；返回的是该任务下所有用户共享的会商记录，按最近更新时间排序。选中一条后再调用 `GET /sessions/{sessionId}` 恢复完整节点和聊天快照。
+3. 没有可恢复记录时，调用 `POST /sessions`，至少传入 `{ external_task_id: taskId, task_snapshot: { ...任务展示字段 } }`。服务端将 `task_scoped` 设为 `true`，并固定快照中的 `id` / `externalTaskId` 为传入的 taskId。
+4. 后续所有意图、链条、节点、收口智能体和历史删除 API 只使用返回的 `sessionId`；不要在每次消息请求中重新创建会话。一个 taskId 可以有多条 sessionId。
+5. 不传 `taskId`（同时省略 `external_task_id`）就是兼容模式：后端只返回和操作当前用户自己的个人会话，绝不会把历史记录升级为共享。响应中的 `task_scoped` 可用来区分两种记录。
+
+服务端从请求中的非空 `external_task_id` 判断是否开启共享，调用方无需也不应自行传 `task_scoped`。
+
 当前岗位 ID 定义在 `lib/positions.ts`：
 
 | ID | 页面岗位 | 职责 |
@@ -109,6 +121,31 @@ PositionRoundtablePage
 
 后端会冻结链条快照并根据链条阶段创建节点。已启动后意图不可再修改；需要重新识别时必须新建会话。
 
+The position workspace selects the dedicated built-in `position-roundtable-intent`
+agent by sending `intent_agent_id` through the shared Step-1 init and stream
+requests. The thread lifecycle, file upload, and SSE transport stay identical
+to the generic multi-agent flow. The dedicated agent permits at most five
+user-assistance rounds; one round may contain multiple independent
+`ask_clarification` cards. `Step1Panel` renders every card separately and
+submits the selected answers together, so cards must never be merged into one
+numbered multi-question card. Only its final `[INTENT_READY]` schema changes to
+the following four string arrays:
+
+```json
+{
+  "coreGoals": ["..."],
+  "riskWarnings": ["..."],
+  "keyPoints": ["..."],
+  "strategicSignificance": ["..."]
+}
+```
+
+The position sidebar and edit dialog render these four fields. Business-chain
+activation requires all four arrays and at least one core goal or strategic
+significance. Historic `objective` / `constraints` / `assumptions` snapshots
+are read through a compatibility mapping only; ordinary multi-agent Step 1 is
+not changed.
+
 ### 4.2 普通节点问答
 
 `PositionNodeChat` 在发送前调用 `getPositionNodeContext` 获取受长度控制的任务、意图和已交付上游内容，再以 `task_external_context` 作为隐藏上下文发送给当前智能体。
@@ -132,8 +169,9 @@ PositionRoundtablePage
 
 页面只维护一个 `sandboxArtifact`。`PositionNodeChat` 和 `PositionBuiltinAgentChat` 通过 `onPreviewArtifact` 上报预览目标；父页面统一渲染 `ArtifactFileDetail`。
 
-**对接 / 重做页面 / 排障指南（接口约定、必守规则、自测与症状表）：**  
-[`docs/沙箱打开关闭与步骤条.md`](./docs/沙箱打开关闭与步骤条.md)
+**对接 / 重做页面 / 排障指南（打开关闭时机、步骤条、接口约定）：**
+[`../../docs/position-roundtable-sandbox/沙箱打开关闭与步骤条.md`](../../docs/position-roundtable-sandbox/沙箱打开关闭与步骤条.md)
+（目录说明见 [`../../docs/position-roundtable-sandbox/README.md`](../../docs/position-roundtable-sandbox/README.md)）
 
 设计要点：
 
@@ -163,8 +201,8 @@ PositionRoundtablePage
 
 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
-| `GET` | `/sessions?external_task_id=` | 按任务查询会话，用于恢复最近会话和历史记录。 |
-| `POST` | `/sessions` | 创建初始会话并保存任务快照。 |
+| `GET` | `/sessions?external_task_id=<taskId>` | 传入时按任务作用域查询共享会话；不传参数时查询当前用户的个人历史。 |
+| `POST` | `/sessions` | 创建会话并保存任务快照；传入非空 `external_task_id` 时服务端会将快照 ID 固定为该值并启用共享；缺失或空值时创建原有个人会话。 |
 | `GET` | `/sessions/{id}` | 恢复会话、节点和冻结快照。 |
 | `DELETE` | `/sessions/{id}` | 删除一条岗位会商历史及其节点；删除当前记录时前端会先屏蔽并发恢复请求。 |
 | `PUT` | `/sessions/{id}/task` | 更新未冻结的任务快照。 |
@@ -178,7 +216,7 @@ PositionRoundtablePage
 | `POST` | `/sessions/{id}/summary/*` | 准备、发送和完成方案总结。 |
 | `POST` | `/sessions/{id}/action-plan/*` | 准备、发送和完成行动规划。 |
 | `PUT` | `/sessions/{id}/{summary|action-plan}/conversation` | 保存两个收口智能体的消息与未发送草稿。 |
-| `POST` | `/demo/seed` | 按用户和 `demoKey` 幂等初始化完整演示会话。 |
+| `POST` | `/demo/seed` | 按 `demoKey` 幂等初始化完整演示会话。 |
 
 后端实现在 `offline-backend-20260512/backend/app/gateway/routers/position_roundtable.py`。
 

frontend-web/src/position-roundtable/api/sessions.ts

@@ -68,7 +68,10 @@ export interface PositionRoundtableNode {
  */
 export interface PositionRoundtableSession {
   id: string;
+  /** Present only when the workspace was opened with a route `taskId`. */
   externalTaskId: string | null;
+  /** True only for sessions intentionally shared by an explicit route taskId. */
+  taskScoped: boolean;
   taskSnapshot: Record<string, unknown>;
   chainId: string | null;
   chainSnapshot: Record<string, unknown> | null;
@@ -112,6 +115,7 @@ interface ServerNode {
 interface ServerSession {
   id: string;
   external_task_id: string | null;
+  task_scoped?: boolean;
   task_snapshot?: Record<string, unknown>;
   chain_id: string | null;
   chain_snapshot?: Record<string, unknown> | null;
@@ -270,6 +274,7 @@ function toSession(session: ServerSession): PositionRoundtableSession {
   const result: PositionRoundtableSession = {
     id: session.id,
     externalTaskId: session.external_task_id,
+    taskScoped: session.task_scoped ?? false,
     taskSnapshot: session.task_snapshot ?? {},
     chainId: session.chain_id,
     chainSnapshot: session.chain_snapshot ?? null,

frontend-web/src/position-roundtable/lib/mock-task-source.ts

@@ -31,16 +31,21 @@ export const MOCK_POSITION_TASKS: readonly PositionTask[] = [
 export const DEFAULT_MOCK_POSITION_TASK_ID = MOCK_POSITION_TASKS[0].id;
 
 export function getMockPositionTask(taskId?: string | null): PositionTask {
-  return (
+  const fixture =
     MOCK_POSITION_TASKS.find((task) => task.id === taskId) ??
-    MOCK_POSITION_TASKS[0]
-  );
+    MOCK_POSITION_TASKS[0];
+  const scopedTaskId = taskId?.trim();
+  // The fixture supplies only display defaults.  Preserve the caller's task
+  // identity so persistence, history and LangGraph thread metadata all remain
+  // bound to the route taskId.
+  return scopedTaskId ? { ...fixture, id: scopedTaskId } : fixture;
 }
 
 /** Normalizes a persisted Session task snapshot without exposing source internals. */
 export function taskFromPositionSnapshot(
   snapshot: Record<string, unknown> | null | undefined,
   fallback: PositionTask,
+  taskScopeId?: string,
 ): PositionTask {
   if (!snapshot || Object.keys(snapshot).length === 0) return fallback;
   const value = (keys: string[], defaultValue: string) => {
@@ -50,7 +55,11 @@ export function taskFromPositionSnapshot(
     return typeof found === "string" ? found : defaultValue;
   };
   return {
-    id: value(["id", "taskId", "externalTaskId"], fallback.id),
+    // Session snapshots are editable display data, while the route taskId is
+    // the stable shared-storage scope.  Keeping them separate prevents a
+    // legacy/mock snapshot from moving a live external task into another
+    // task's history bucket.
+    id: taskScopeId?.trim() || value(["id", "taskId", "externalTaskId"], fallback.id),
     title: value(["title", "taskName", "name"], fallback.title),
     description: value(["description", "taskContent", "overview", "content"], fallback.description),
     direction: value(["direction", "taskDirection", "category"], fallback.direction),

frontend-web/src/position-roundtable/pages/PositionRoundtablePage.tsx

@@ -111,7 +111,11 @@ import {
   type InteractiveMessage,
   type TimelineEntry,
 } from "@/roundtable-planning/hooks/useStep1Intent";
-import { INTENT_AGENT_ID, type IntentSummary } from "@/roundtable-planning/api/intent";
+import {
+  POSITION_INTENT_AGENT_ID,
+  type IntentSummary,
+  type PositionIntentSummary,
+} from "@/roundtable-planning/api/intent";
 import type { BusinessChain } from "@/roundtable-planning/lib/business-chain";
 import { getAvatarTypeFor } from "@/roundtable-planning/lib/roundtable-constants";
 import {
@@ -140,6 +144,7 @@ import {
   getPositionSession,
   isPositionSessionNotFoundError,
   listPositionSessions,
+  PositionSessionNotFoundError,
   preparePositionActionPlan,
   preparePositionSummary,
   rejectPositionNode,
@@ -182,11 +187,24 @@ type PositionArtifactPreview = {
   previewKey?: string;
   auto?: boolean;
 };
+
+function isSessionInTaskScope(
+  session: PositionRoundtableSession,
+  taskScopeId: string | null,
+): boolean {
+  // The legacy entry has no taskId and remains user-owned.  Explicit taskId
+  // deep links are the only shared mode and must never cross task scopes.
+  return taskScopeId === null
+    ? !session.taskScoped
+    : session.taskScoped && session.externalTaskId === taskScopeId;
+}
+
 type ClosureStageKind = PositionBuiltinAgentKind;
 type IntentEditDraft = {
-  objective: string;
-  constraints: string;
-  assumptions: string;
+  coreGoals: string;
+  riskWarnings: string;
+  keyPoints: string;
+  strategicSignificance: string;
 };
 type SandboxThreadSnapshot = {
   threadId: string;
@@ -669,16 +687,38 @@ function mergePositionSession(
   return { ...current, ...next, nodes: current.nodes };
 }
 
-function parseIntentSummary(snapshot: Record<string, unknown> | null | undefined): IntentSummary | null {
-  if (!snapshot || typeof snapshot.objective !== "string" || !Array.isArray(snapshot.constraints)) {
+function intentStringList(snapshot: Record<string, unknown>, key: string): string[] {
+  const value = snapshot[key];
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string" && Boolean(item.trim()))
+    : [];
+}
+
+function parsePositionIntentSummary(
+  snapshot: Record<string, unknown> | null | undefined,
+): PositionIntentSummary | null {
+  if (!snapshot) return null;
+  const positionKeys = ["coreGoals", "riskWarnings", "keyPoints", "strategicSignificance"];
+  if (positionKeys.some((key) => key in snapshot)) {
+    if (!positionKeys.every((key) => Array.isArray(snapshot[key]))) return null;
+    return {
+      coreGoals: intentStringList(snapshot, "coreGoals"),
+      riskWarnings: intentStringList(snapshot, "riskWarnings"),
+      keyPoints: intentStringList(snapshot, "keyPoints"),
+      strategicSignificance: intentStringList(snapshot, "strategicSignificance"),
+    };
+  }
+
+  // Existing sessions created before the dedicated position agent used the
+  // shared Step-1 schema. Keep them readable and editable after the switch.
+  if (typeof snapshot.objective !== "string" || !Array.isArray(snapshot.constraints)) {
     return null;
   }
   return {
-    objective: snapshot.objective,
-    constraints: snapshot.constraints.filter((item): item is string => typeof item === "string"),
-    assumptions: Array.isArray(snapshot.assumptions)
-      ? snapshot.assumptions.filter((item): item is string => typeof item === "string")
-      : undefined,
+    coreGoals: intentStringList(snapshot, "constraints"),
+    riskWarnings: [],
+    keyPoints: intentStringList(snapshot, "assumptions"),
+    strategicSignificance: snapshot.objective.trim() ? [snapshot.objective.trim()] : [],
   };
 }
 
@@ -829,18 +869,21 @@ export default function PositionRoundtablePage({
   const [positionId, setPositionId] = useState<PositionId>(() => positionIdFromUrl);
   const demoModeEnabled = isPositionRoundtableDemoEnabled();
   const demoTask = useMemo(() => getPositionDemoTask(), []);
-  const taskIdFromUrl =
+  // A route taskId opts into shared task collaboration. Without it this page
+  // keeps the original personal-session behavior and uses mock data only for
+  // display defaults.
+  const taskScopeId =
     standaloneDemoMode
       ? demoTask.id
-      : searchParams.get("taskId") ??
-        (demoModeEnabled ? demoTask.id : DEFAULT_MOCK_POSITION_TASK_ID);
+      : searchParams.get("taskId")?.trim() || null;
+  const displayTaskId = taskScopeId ?? (demoModeEnabled ? demoTask.id : DEFAULT_MOCK_POSITION_TASK_ID);
   const searchParamsString = searchParams.toString();
   const fallbackTask = useMemo(
     () =>
-      demoModeEnabled && taskIdFromUrl === demoTask.id
+      demoModeEnabled && displayTaskId === demoTask.id
         ? demoTask
-        : getMockPositionTask(taskIdFromUrl),
-    [demoModeEnabled, demoTask, taskIdFromUrl],
+        : getMockPositionTask(displayTaskId),
+    [demoModeEnabled, demoTask, displayTaskId],
   );
   const rawSessionIdFromUrl = searchParams.get("sessionId");
   const sessionIdFromUrl =
@@ -957,9 +1000,10 @@ export default function PositionRoundtablePage({
   const [taskSaving, setTaskSaving] = useState(false);
   const [intentEditorOpen, setIntentEditorOpen] = useState(false);
   const [intentDraft, setIntentDraft] = useState<IntentEditDraft>({
-    objective: "",
-    constraints: "",
-    assumptions: "",
+    coreGoals: "",
+    riskWarnings: "",
+    keyPoints: "",
+    strategicSignificance: "",
   });
   const [intentSaving, setIntentSaving] = useState(false);
   const [intentCompletedAt, setIntentCompletedAt] = useState("");
@@ -1029,12 +1073,12 @@ export default function PositionRoundtablePage({
     [],
   );
   const frozenIntent = useMemo(
-    () => parseIntentSummary(positionSession?.intentSnapshot),
+    () => parsePositionIntentSummary(positionSession?.intentSnapshot),
     [positionSession?.intentSnapshot],
   );
   const task = useMemo(
-    () => taskFromPositionSnapshot(positionSession?.taskSnapshot, fallbackTask),
-    [fallbackTask, positionSession?.taskSnapshot],
+    () => taskFromPositionSnapshot(positionSession?.taskSnapshot, fallbackTask, taskScopeId ?? undefined),
+    [fallbackTask, positionSession?.taskSnapshot, taskScopeId],
   );
   const intentTaskContext = useMemo(
     () => ({
@@ -1090,12 +1134,23 @@ export default function PositionRoundtablePage({
         ? 1
         : 0,
     selectedModel,
+    intentAgentId: POSITION_INTENT_AGENT_ID,
     taskContext: intentTaskContext,
     initialWelcomeText:
       "我已读取左侧任务信息。你可以直接补充本次任务的特殊约束；如果没有补充，我会基于现有任务信息进行意图识别。",
     showInitialWelcome: false,
     triggerToast,
   });
+  const livePositionIntent = useMemo(
+    () =>
+      parsePositionIntentSummary(
+        intent.intentReady as unknown as Record<string, unknown> | null,
+      ),
+    [intent.intentReady],
+  );
+  const positionIntent = frozenIntent ?? livePositionIntent;
+  const positionIntentHeadline =
+    positionIntent?.strategicSignificance[0] ?? positionIntent?.coreGoals[0];
   // `useStep1Intent` starts with an empty list for a new intent session. Keep
   // the complete list here so a restored historical session can display its
   // first agent turn as well as the user's follow-up turns. The old
@@ -1144,9 +1199,10 @@ export default function PositionRoundtablePage({
     positionSession?.status === "archived";
 
   const syncSessionUrl = useCallback(
-    (sessionId: string, nextTaskId: string) => {
+    (sessionId: string, nextTaskId?: string | null) => {
       const next = new URLSearchParams(searchParamsString);
-      next.set("taskId", nextTaskId);
+      if (nextTaskId) next.set("taskId", nextTaskId);
+      else next.delete("taskId");
       next.set("sessionId", sessionId);
       next.delete("new");
       setSearchParams(next, { replace: true });
@@ -1162,20 +1218,20 @@ export default function PositionRoundtablePage({
         const localSession = getLocalPositionDemoSession();
         positionSessionRef.current = localSession;
         setPositionSession(localSession);
-        syncSessionUrl(localSession.id, localSession.externalTaskId ?? taskSnapshot.id);
+        syncSessionUrl(localSession.id, taskScopeId);
         return localSession;
       }
       if (sessionCreationRef.current) return sessionCreationRef.current;
       const creation = createPositionSession({
-        externalTaskId: taskSnapshot.id || undefined,
-        taskSnapshot: { ...taskSnapshot },
+        externalTaskId: taskScopeId ?? undefined,
+        taskSnapshot: taskScopeId ? { ...taskSnapshot, id: taskScopeId } : { ...taskSnapshot },
       })
         .then((created) => {
           // Update the ref synchronously. Several effects can observe a new
           // intent thread in the same render cycle; all must share this row.
           positionSessionRef.current = created;
           setPositionSession(created);
-          syncSessionUrl(created.id, taskSnapshot.id);
+          syncSessionUrl(created.id, taskScopeId);
           return created;
         })
         .finally(() => {
@@ -1186,7 +1242,7 @@ export default function PositionRoundtablePage({
       sessionCreationRef.current = creation;
       return creation;
     },
-    [standaloneDemoMode, syncSessionUrl],
+    [standaloneDemoMode, syncSessionUrl, taskScopeId],
   );
 
   const openTaskEditor = useCallback(() => {
@@ -1207,6 +1263,10 @@ export default function PositionRoundtablePage({
     }
     const nextTask: PositionTask = {
       ...task,
+      // Task identity comes exclusively from the route. Task-card editing can
+      // change display fields but must never move this session to another
+      // shared task bucket.
+      id: taskScopeId ?? task.id,
       title,
       priority: taskDraft.priority?.trim() || task.priority || "紧急",
       description: taskDraft.description.trim(),
@@ -1225,7 +1285,7 @@ export default function PositionRoundtablePage({
         positionSessionRef.current = merged;
         return merged;
       });
-      syncSessionUrl(saved.id, nextTask.id);
+      syncSessionUrl(saved.id, taskScopeId);
       setTaskEditorOpen(false);
       toast.success("任务信息已更新");
     } catch (error) {
@@ -1233,27 +1293,35 @@ export default function PositionRoundtablePage({
     } finally {
       setTaskSaving(false);
     }
-  }, [ensureEditableSession, isArchivedSession, syncSessionUrl, task, taskDraft]);
+  }, [ensureEditableSession, isArchivedSession, syncSessionUrl, task, taskDraft, taskScopeId]);
 
   const openIntentEditor = useCallback(() => {
     if (isArchivedSession) return;
-    const currentIntent = frozenIntent ?? intent.intentReady;
+    const currentIntent = positionIntent;
     setIntentDraft({
-      objective: currentIntent?.objective ?? "",
-      constraints: (currentIntent?.constraints ?? []).join("\n"),
-      assumptions: (currentIntent?.assumptions ?? []).join("\n"),
+      coreGoals: (currentIntent?.coreGoals ?? []).join("\n"),
+      riskWarnings: (currentIntent?.riskWarnings ?? []).join("\n"),
+      keyPoints: (currentIntent?.keyPoints ?? []).join("\n"),
+      strategicSignificance: (currentIntent?.strategicSignificance ?? []).join("\n"),
     });
     setIntentEditorOpen(true);
-  }, [frozenIntent, intent.intentReady, isArchivedSession]);
+  }, [isArchivedSession, positionIntent]);
 
   const handleSaveIntentEdit = useCallback(async () => {
     if (isArchivedSession) {
       toast.warning("已归档的会话不能编辑意图理解");
       return;
     }
-    const objective = intentDraft.objective.trim();
-    if (!objective) {
-      toast.warning("请填写任务意图");
+    const coreGoals = intentDraft.coreGoals
+      .split(/\r?\n/)
+      .map((item) => item.trim())
+      .filter(Boolean);
+    const strategicSignificance = intentDraft.strategicSignificance
+      .split(/\r?\n/)
+      .map((item) => item.trim())
+      .filter(Boolean);
+    if (coreGoals.length === 0 && strategicSignificance.length === 0) {
+      toast.warning("请至少填写核心目标或战略意义");
       return;
     }
     const splitLines = (value: string) =>
@@ -1261,10 +1329,11 @@ export default function PositionRoundtablePage({
         .split(/\r?\n/)
         .map((item) => item.trim())
         .filter(Boolean);
-    const nextIntent: IntentSummary = {
-      objective,
-      constraints: splitLines(intentDraft.constraints),
-      assumptions: splitLines(intentDraft.assumptions),
+    const nextIntent: PositionIntentSummary = {
+      coreGoals,
+      riskWarnings: splitLines(intentDraft.riskWarnings),
+      keyPoints: splitLines(intentDraft.keyPoints),
+      strategicSignificance,
     };
 
     setIntentSaving(true);
@@ -1288,7 +1357,7 @@ export default function PositionRoundtablePage({
       });
       intent.hydrateFromDraft({
         intentThreadId: intentThreadId ?? intent.intentThreadId,
-        intentReady: nextIntent,
+        intentReady: nextIntent as unknown as IntentSummary,
         interactiveMessages: intent.interactiveMessages,
         timelineEntries: [],
       });
@@ -1304,9 +1373,10 @@ export default function PositionRoundtablePage({
     ensureEditableSession,
     intent,
     intentCompletedAt,
-    intentDraft.assumptions,
-    intentDraft.constraints,
-    intentDraft.objective,
+    intentDraft.coreGoals,
+    intentDraft.keyPoints,
+    intentDraft.riskWarnings,
+    intentDraft.strategicSignificance,
     intentInputDraft,
     isArchivedSession,
     task,
@@ -1363,7 +1433,7 @@ export default function PositionRoundtablePage({
   // multi-agent roundtable Step 1 flow.  Do not derive this from a chain seat:
   // older chains may have no seat agent id (or a removed legacy id), which
   // would make the configuration panel request a non-existent agent.
-  const intentAgentId = INTENT_AGENT_ID;
+  const intentAgentId = POSITION_INTENT_AGENT_ID;
   const isIntelligenceDeliveryOverview =
     activePosition.isIntentPosition && positionSession !== null && positionSession.status !== "intent_pending";
   const showIntentDeliveryOverview =
@@ -1524,7 +1594,7 @@ export default function PositionRoundtablePage({
     let cancelled = false;
     void getPositionSession(sessionIdFromUrl)
       .then((session) => {
-        if (!cancelled) {
+        if (!cancelled && isSessionInTaskScope(session, taskScopeId)) {
           positionSessionRef.current = session;
           setPositionSession(session);
         }
@@ -1533,7 +1603,7 @@ export default function PositionRoundtablePage({
     return () => {
       cancelled = true;
     };
-  }, [positionSession, sessionIdFromUrl]);
+  }, [positionSession, sessionIdFromUrl, taskScopeId]);
   const handleNodeUpdate = useCallback((updatedNode: PositionRoundtableNode) => {
     setPositionSession((current) => {
       if (!current?.nodes) return current;
@@ -1599,7 +1669,11 @@ export default function PositionRoundtablePage({
         view.timelineEntries,
         view.inputDraft,
       );
-      const intentSnapshot = view.intentReady ? { ...view.intentReady } : null;
+      // 岗位会商持久化的是专属四段式结果；useStep1Intent 为兼容普通会商
+      // 补出的 objective / constraints / assumptions 不应写回岗位会商快照。
+      const intentSnapshot = parsePositionIntentSummary(
+        view.intentReady as unknown as Record<string, unknown> | null,
+      );
 
       const operation = async () => {
         const baseSession = candidateSession ?? (await ensureEditableSession(task));
@@ -1751,7 +1825,8 @@ export default function PositionRoundtablePage({
         candidates.sort((left, right) => right.length - left.length)[0] ?? [];
       hydrateIntentFromDraft({
         intentThreadId: intentThreadId ?? latest.intentThreadId,
-        intentReady: latestFrozenIntentRef.current ?? latest.intentReady,
+        intentReady:
+          (latestFrozenIntentRef.current as unknown as IntentSummary | null) ?? latest.intentReady,
         interactiveMessages:
           interactiveMessages.length > 0
             ? interactiveMessages
@@ -1778,7 +1853,8 @@ export default function PositionRoundtablePage({
               : [];
         hydrateIntentFromDraft({
           intentThreadId: intentThreadId ?? latest.intentThreadId,
-          intentReady: latestFrozenIntentRef.current ?? latest.intentReady,
+          intentReady:
+            (latestFrozenIntentRef.current as unknown as IntentSummary | null) ?? latest.intentReady,
           interactiveMessages: fallbackMessages,
           timelineEntries: databaseTimeline,
         });
@@ -1812,15 +1888,17 @@ export default function PositionRoundtablePage({
   );
   const openPositionConfig = useCallback(
     (chainId: string) => {
-      const taskQuery = `taskId=${encodeURIComponent(task.id)}${forceNewSession ? "&new=1" : ""}`;
-      const returnTo = sessionIdFromUrl
-        ? `/page/strategy/qa/position-roundtable?${taskQuery}&sessionId=${encodeURIComponent(sessionIdFromUrl)}`
-        : `/page/strategy/qa/position-roundtable?${taskQuery}`;
+      const returnParams = new URLSearchParams();
+      if (taskScopeId) returnParams.set("taskId", taskScopeId);
+      if (forceNewSession) returnParams.set("new", "1");
+      if (sessionIdFromUrl) returnParams.set("sessionId", sessionIdFromUrl);
+      const returnQuery = returnParams.toString();
+      const returnTo = `/page/strategy/qa/position-roundtable${returnQuery ? `?${returnQuery}` : ""}`;
       navigate(
         `/page/workspace/roundtable/chains?chainId=${encodeURIComponent(chainId)}&mode=position&returnTo=${encodeURIComponent(returnTo)}`,
       );
     },
-    [forceNewSession, navigate, sessionIdFromUrl, task.id],
+    [forceNewSession, navigate, sessionIdFromUrl, taskScopeId],
   );
 
   // The mock task source mirrors the future external-task contract: opening a
@@ -1843,7 +1921,7 @@ export default function PositionRoundtablePage({
     const useDemoFixture = demoModeEnabled && task.id === demoTask.id;
     const discovery = useDemoFixture
       ? initializePositionRoundtableDemo().then((session) => [session])
-      : listPositionSessions(task.id);
+      : listPositionSessions(taskScopeId ?? undefined);
     void discovery
       .then((sessions) => {
         if (cancelled) return;
@@ -1861,7 +1939,8 @@ export default function PositionRoundtablePage({
           setSessionDiscoveryDone(true);
         }
         const next = new URLSearchParams(searchParamsString);
-        next.set("taskId", task.id);
+        if (taskScopeId) next.set("taskId", taskScopeId);
+        else next.delete("taskId");
         next.set("sessionId", latest.id);
         setSearchParams(next, { replace: true });
       })
@@ -1881,7 +1960,7 @@ export default function PositionRoundtablePage({
     searchParamsString,
     sessionIdFromUrl,
     setSearchParams,
-    task.id,
+    taskScopeId,
   ]);
 
   // Create the database row as soon as discovery confirms this is a new task
@@ -1928,6 +2007,11 @@ export default function PositionRoundtablePage({
       : getPositionSession(sessionIdFromUrl);
     void request
       .then((session) => {
+        if (!isSessionInTaskScope(session, taskScopeId)) {
+          // A shared session id can be pasted with the wrong taskId. Treat it
+          // as stale navigation instead of allowing it to cross task scopes.
+          throw new PositionSessionNotFoundError(sessionIdFromUrl);
+        }
         if (
           !cancelled &&
           !ignoredSessionLoadIdsRef.current.has(sessionIdFromUrl)
@@ -1966,9 +2050,9 @@ export default function PositionRoundtablePage({
     return () => {
       cancelled = true;
     };
-  }, [searchParamsString, sessionIdFromUrl, setSearchParams]);
+  }, [searchParamsString, sessionIdFromUrl, setSearchParams, taskScopeId]);
 
-  const agentIdForPanel = activePosition.isIntentPosition ? INTENT_AGENT_ID : selectedAgentId;
+  const agentIdForPanel = activePosition.isIntentPosition ? POSITION_INTENT_AGENT_ID : selectedAgentId;
   const { agent: selectedAgent } = useAgent(agentIdForPanel, {
     enabled: !standaloneDemoMode,
   });
@@ -1980,7 +2064,7 @@ export default function PositionRoundtablePage({
     if (!activePosition.isIntentPosition) return null;
     const seat = activeChain?.seats.find((item) => item.position_id === intentPositionId);
     return {
-      id: INTENT_AGENT_ID,
+      id: POSITION_INTENT_AGENT_ID,
       name: seat?.name || `${activePosition.name}智能体`,
       description: seat?.description || activePosition.description,
       user_id: null,
@@ -2043,7 +2127,7 @@ export default function PositionRoundtablePage({
       let session = await ensureEditableSession(task);
       session = await savePositionIntent(session.id, {
         intentThreadId: intent.intentThreadId,
-        intentSnapshot: intent.intentReady,
+        intentSnapshot: positionIntent,
         conversationSnapshot: buildIntentConversationSnapshot(
           intent.interactiveMessages,
           intent.timelineEntries,
@@ -2061,7 +2145,8 @@ export default function PositionRoundtablePage({
         setRightPanelOpen(true);
       }
       const next = new URLSearchParams(searchParams);
-      next.set("taskId", task.id);
+      if (taskScopeId) next.set("taskId", taskScopeId);
+      else next.delete("taskId");
       next.set("sessionId", session.id);
       next.delete("new");
       setSearchParams(next, { replace: true });
@@ -2083,6 +2168,7 @@ export default function PositionRoundtablePage({
     setSearchParams,
     startingChain,
     task,
+    taskScopeId,
     intentPositionId,
     positionId,
   ]);
@@ -2124,12 +2210,13 @@ export default function PositionRoundtablePage({
     setBuiltinAutoStartRequestKey(0);
     setIntentCompletedAt("");
     const next = new URLSearchParams(searchParams);
-    next.set("taskId", task.id);
+    if (taskScopeId) next.set("taskId", taskScopeId);
+    else next.delete("taskId");
     next.set("positionId", intentPositionId);
     next.delete("sessionId");
     next.set("new", "1");
     setSearchParams(next);
-  }, [intent, intentPositionId, queueIntentConversationSave, searchParams, setSearchParams, task.id]);
+  }, [intent, intentPositionId, queueIntentConversationSave, searchParams, setSearchParams, taskScopeId]);
 
   const loadHistorySessions = useCallback(() => {
     if (isLocalPositionDemoSession(positionSessionRef.current?.id)) {
@@ -2138,7 +2225,7 @@ export default function PositionRoundtablePage({
       return;
     }
     setHistoryLoading(true);
-    void listPositionSessions(task.id)
+    void listPositionSessions(taskScopeId ?? undefined)
       .then((sessions) => {
         setHistorySessions(
           [...sessions].sort((left, right) => {
@@ -2154,7 +2241,7 @@ export default function PositionRoundtablePage({
       .finally(() => {
         setHistoryLoading(false);
       });
-  }, [task.id]);
+  }, [taskScopeId]);
 
   const handleHistoryMenuOpenChange = useCallback(
     (open: boolean) => {
@@ -2198,7 +2285,8 @@ export default function PositionRoundtablePage({
       restoringIntentSessionRef.current = null;
       persistedIntentRef.current = null;
       const next = new URLSearchParams(searchParams);
-      next.set("taskId", task.id);
+      if (taskScopeId) next.set("taskId", taskScopeId);
+      else next.delete("taskId");
       next.set("sessionId", sessionId);
       next.delete("new");
       setSearchParams(next);
@@ -2209,7 +2297,7 @@ export default function PositionRoundtablePage({
       searchParams,
       sessionIdFromUrl,
       setSearchParams,
-      task.id,
+      taskScopeId,
     ],
   );
 
@@ -2269,7 +2357,8 @@ export default function PositionRoundtablePage({
           setSelectedAgentId(null);
           setHistoryMenuOpen(false);
           const next = new URLSearchParams(searchParams);
-          next.set("taskId", task.id);
+          if (taskScopeId) next.set("taskId", taskScopeId);
+          else next.delete("taskId");
           if (nextSession) {
             // Prefer the most recently active remaining conversation so the
             // user stays in history instead of being dropped onto a blank page.
@@ -2299,7 +2388,7 @@ export default function PositionRoundtablePage({
       sessionIdFromUrl,
       setSearchParams,
       standaloneDemoMode,
-      task.id,
+      taskScopeId,
     ],
   );
 
@@ -2381,17 +2470,17 @@ export default function PositionRoundtablePage({
     [handlePreviewArtifact],
   );
   const openIntentFlowDetail = useCallback(() => {
-    if (!(frozenIntent ?? intent.intentReady)) {
+    if (!positionIntent) {
       toast.info("任务意图还在梳理中，完成确认后就能查看完整的意图说明。");
       return;
     }
     setFlowDetailItem(
       buildIntentResultItem(
-        frozenIntent ?? intent.intentReady,
+        positionIntent,
         intentCompletedAt || positionSession?.updatedAt,
       ),
     );
-  }, [frozenIntent, intent.intentReady, intentCompletedAt, positionSession?.updatedAt]);
+  }, [positionIntent, intentCompletedAt, positionSession?.updatedAt]);
   const openNodeFlowDetail = useCallback(
     (node: PositionRoundtableNode) => {
       const item = buildNodeResultItem(node, activeChain);
@@ -2608,7 +2697,7 @@ export default function PositionRoundtablePage({
                   positionName={activePosition.name}
                   specialAgentConfig
                   onSelectAgent={handleSelectAgent}
-                  intentObjective={frozenIntent?.objective ?? intent.intentReady?.objective}
+                  intentObjective={positionIntentHeadline}
                   intentCompletedAt={intentCompletedAt}
                   assignedAgentIds={configurationAgentIds}
                   hasSelectedChain={showClosureAgents || Boolean(selectedChain)}
@@ -2650,7 +2739,7 @@ export default function PositionRoundtablePage({
         }
         interactiveMessages={visibleIntentMessages}
         intentThreadId={intent.intentThreadId}
-        intentReady={chainStarted ? frozenIntent ?? intent.intentReady : intent.intentReady}
+        intentReady={chainStarted ? positionIntent : intent.intentReady}
         isIntentSending={intent.isIntentSending}
         pendingIntentClarificationMsgId={intent.pendingIntentClarificationMsgId}
         intentClarificationSelections={intent.intentClarificationSelections}
@@ -2940,7 +3029,7 @@ export default function PositionRoundtablePage({
               />
               {showIntentDeliveryOverview ? (
                 <IntentDeliveryOverviewSidebar
-                  intent={frozenIntent ?? intent.intentReady}
+                  intent={positionIntent}
                   chain={activeChain}
                   nodes={positionSession?.nodes ?? []}
                   activeNodeKey={activeNodeKey}
@@ -3072,7 +3161,7 @@ export default function PositionRoundtablePage({
                   positionName={activePosition.name}
                   specialAgentConfig={activePosition.isIntentPosition}
                   onSelectAgent={handleSelectAgent}
-                  intentObjective={frozenIntent?.objective ?? intent.intentReady?.objective}
+                  intentObjective={positionIntentHeadline}
                 intentCompletedAt={intentCompletedAt}
                 assignedAgentIds={configurationAgentIds}
                 hasSelectedChain={showClosureAgents || Boolean(selectedChain)}
@@ -3665,7 +3754,7 @@ function PositionNodeEmptyState({
 }
 
 /** 已启动会话中的意图是冻结快照；避免在情报岗视图意外覆盖它。 */
-function IntentConfirmedState({ intent }: { intent: IntentSummary }) {
+function IntentConfirmedState({ intent }: { intent: PositionIntentSummary }) {
   return (
     <div className="flex min-h-0 flex-1 flex-col overflow-y-auto bg-slate-50/50 px-6 py-7 dark:bg-[#032650]/30">
       <div className="mx-auto w-full max-w-2xl rounded-2xl border border-emerald-500/20 bg-white p-5 shadow-sm dark:border-emerald-400/25 dark:bg-[#042b59]/65">
@@ -3681,15 +3770,15 @@ function IntentConfirmedState({ intent }: { intent: IntentSummary }) {
           </div>
         </div>
         <div className="mt-5 rounded-xl border border-slate-100 bg-slate-50/70 p-4 dark:border-[#2b8ffe]/20 dark:bg-[#032650]/40">
-          <p className="text-[11px] font-semibold text-muted-foreground dark:text-[#8aa0c4]">任务目标</p>
-          <p className="mt-1.5 text-sm font-semibold leading-6 text-slate-800 dark:text-[#e8edf5]">
-            {desensitize(intent.objective)}
-          </p>
+          <p className="text-[11px] font-semibold text-muted-foreground dark:text-[#8aa0c4]">核心目标</p>
+          <div className="mt-1.5 space-y-1.5 text-sm font-semibold leading-6 text-slate-800 dark:text-[#e8edf5]">
+            {intent.coreGoals.map((goal, index) => <p key={`${goal}-${index}`}>{desensitize(goal)}</p>)}
+          </div>
         </div>
         <div className="mt-4">
-          <p className="text-[11px] font-semibold text-muted-foreground dark:text-[#8aa0c4]">关键约束</p>
+          <p className="text-[11px] font-semibold text-muted-foreground dark:text-[#8aa0c4]">风险提示</p>
           <div className="mt-2 grid gap-2 sm:grid-cols-2">
-            {intent.constraints.map((constraint, index) => (
+            {intent.riskWarnings.map((constraint, index) => (
               <div
                 key={`${constraint}-${index}`}
                 className="flex items-start gap-2 rounded-lg border border-slate-100 bg-white px-3 py-2 text-xs leading-5 text-slate-700 dark:border-[#2b8ffe]/20 dark:bg-[#032650]/35 dark:text-[#c5d8f1]"
@@ -3726,7 +3815,7 @@ function PositionDeliveryOverview({
   chain,
   session,
 }: {
-  intent: IntentSummary | null;
+  intent: PositionIntentSummary | null;
   intentCompletedAt?: string;
   nodes: PositionRoundtableNode[];
   chain: BusinessChain | null;
@@ -3859,7 +3948,10 @@ function PositionDeliveryOverview({
         kind: "intent",
         agentName: "情报分析智能体",
         productName: "任务意图理解",
-        summary: intent?.objective || "情报分析岗已确认任务意图并冻结业务链。",
+        summary:
+          intent?.strategicSignificance[0] ||
+          intent?.coreGoals[0] ||
+          "情报分析岗已确认任务意图并冻结业务链。",
         positionId: intentPositionIdFor(),
         updatedAt: intentCompletedAt || session?.updatedAt,
         status: intent ? "done" : "ready",
@@ -4787,7 +4879,7 @@ function IntentUnderstandingCard({
   collapsed,
   onCollapsedChange,
 }: {
-  intent: ReturnType<typeof useStep1Intent>["intentReady"];
+  intent: PositionIntentSummary | null;
   editable?: boolean;
   onEdit?: () => void;
   collapsed: boolean;
@@ -4829,30 +4921,21 @@ function IntentUnderstandingCard({
         <div className="min-h-0 overflow-hidden">
       {intent ? (
         <div className="space-y-3 p-4">
-          <div>
-            <p className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">任务意图</p>
-            <p className="mt-1 text-sm leading-6 text-slate-700 dark:text-[#f2f7ff]">
-              {desensitize(intent.objective)}
-            </p>
-          </div>
-          <div>
-            <p className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">关键约束</p>
-            <ul className="mt-1 list-disc space-y-1 pl-4 text-sm leading-6 text-slate-600 marker:text-slate-400 dark:text-[#d8e6f8] dark:marker:text-[#83b6ed]">
-              {intent.constraints.map((constraint, index) => (
-                <li key={`${constraint}-${index}`}>{desensitize(constraint)}</li>
-              ))}
-            </ul>
-          </div>
-          {intent.assumptions && intent.assumptions.length > 0 && (
-            <div>
-              <p className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">关键假设</p>
-              <ul className="mt-1 list-disc space-y-1 pl-4 text-sm leading-6 text-slate-600 marker:text-slate-400 dark:text-[#d8e6f8] dark:marker:text-[#83b6ed]">
-                {intent.assumptions.map((assumption, index) => (
-                  <li key={`${assumption}-${index}`}>{desensitize(assumption)}</li>
-                ))}
-              </ul>
+          {([
+            ["核心目标", intent.coreGoals],
+            ["风险提示", intent.riskWarnings],
+            ["关键要点", intent.keyPoints],
+            ["战略意义", intent.strategicSignificance],
+          ] as const).map(([label, values]) => (
+            <div key={label}>
+              <p className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">{label}</p>
+              {values.length > 0 ? (
+                <ul className="mt-1 list-disc space-y-1 pl-4 text-sm leading-6 text-slate-600 marker:text-slate-400 dark:text-[#d8e6f8] dark:marker:text-[#83b6ed]">
+                  {values.map((value, index) => <li key={`${value}-${index}`}>{desensitize(value)}</li>)}
+                </ul>
+              ) : <p className="mt-1 text-sm text-slate-500 dark:text-[#9ebfe2]">暂无{label}</p>}
             </div>
-          )}
+          ))}
         </div>
       ) : (
         <div className="p-4 text-sm leading-6 text-muted-foreground dark:text-[#d8e6f8]">
@@ -4873,16 +4956,17 @@ function IntentDeliveryOverviewSidebar({
   onSelectNode,
   onSelectSeat,
 }: {
-  intent: IntentSummary | null;
+  intent: PositionIntentSummary | null;
   chain: BusinessChain | null;
   nodes: PositionRoundtableNode[];
   activeNodeKey: string | null;
   onSelectNode: (node: PositionRoundtableNode) => void;
   onSelectSeat: (seat: BusinessChain["seats"][number], stageIndex: number, seatIndex: number) => void;
 }) {
-  const objective = intent?.objective?.trim() || "暂无任务目的";
-  const coreGoals = intent?.constraints?.filter(Boolean) ?? [];
-  const keyConstraints = intent?.assumptions?.filter(Boolean) ?? [];
+  const coreGoals = intent?.coreGoals ?? [];
+  const riskWarnings = intent?.riskWarnings ?? [];
+  const keyPoints = intent?.keyPoints ?? [];
+  const strategicSignificance = intent?.strategicSignificance ?? [];
 
   return (
     <section className="position-roundtable-intent-delivery-sidebar">
@@ -4892,10 +4976,6 @@ function IntentDeliveryOverviewSidebar({
           <h2>意图理解结果</h2>
         </header>
         <div className="position-roundtable-intent-delivery-sections">
-          <article className="position-roundtable-intent-delivery-section position-roundtable-intent-delivery-section--purpose">
-            <h3>任务目的</h3>
-            <p>{desensitize(objective)}</p>
-          </article>
           <article className="position-roundtable-intent-delivery-section position-roundtable-intent-delivery-section--goals">
             <h3>核心目标</h3>
             {coreGoals.length > 0 ? (
@@ -4909,17 +4989,25 @@ function IntentDeliveryOverviewSidebar({
             )}
           </article>
           <article className="position-roundtable-intent-delivery-section position-roundtable-intent-delivery-section--constraints">
-            <h3>关键约束</h3>
-            {keyConstraints.length > 0 ? (
+            <h3>风险提示</h3>
+            {riskWarnings.length > 0 ? (
               <ul>
-                {keyConstraints.map((constraint, index) => (
-                  <li key={`${constraint}-${index}`}>{desensitize(constraint)}</li>
+                {riskWarnings.map((warning, index) => (
+                  <li key={`${warning}-${index}`}>{desensitize(warning)}</li>
                 ))}
               </ul>
             ) : (
-              <p className="is-empty">暂无补充约束</p>
+              <p className="is-empty">暂无风险提示</p>
             )}
           </article>
+          <article className="position-roundtable-intent-delivery-section position-roundtable-intent-delivery-section--purpose">
+            <h3>关键要点</h3>
+            {keyPoints.length > 0 ? <ul>{keyPoints.map((item, index) => <li key={`${item}-${index}`}>{desensitize(item)}</li>)}</ul> : <p className="is-empty">暂无关键要点</p>}
+          </article>
+          <article className="position-roundtable-intent-delivery-section position-roundtable-intent-delivery-section--significance">
+            <h3>战略意义</h3>
+            {strategicSignificance.length > 0 ? <ul>{strategicSignificance.map((item, index) => <li key={`${item}-${index}`}>{desensitize(item)}</li>)}</ul> : <p className="is-empty">暂无战略意义</p>}
+          </article>
         </div>
       </div>
 
@@ -4965,34 +5053,43 @@ function IntentUnderstandingEditDialog({
         </DialogHeader>
         <div className="space-y-4 py-1">
           <label className="block space-y-1.5">
-            <span className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">任务意图</span>
+            <span className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">核心目标</span>
             <Textarea
-              value={draft.objective}
-              onChange={(event) => onChange({ ...draft, objective: event.target.value })}
+              value={draft.coreGoals}
+              onChange={(event) => onChange({ ...draft, coreGoals: event.target.value })}
               className="min-h-24 resize-none dark:border-[#2b8ffe]/35 dark:bg-[#032650]/80"
-              placeholder="请输入识别后的任务意图"
+              placeholder="每行一项核心目标"
             />
           </label>
           <label className="block space-y-1.5">
             <span className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">
-              关键约束
+              风险提示
             </span>
             <Textarea
-              value={draft.constraints}
-              onChange={(event) => onChange({ ...draft, constraints: event.target.value })}
+              value={draft.riskWarnings}
+              onChange={(event) => onChange({ ...draft, riskWarnings: event.target.value })}
               className="min-h-28 resize-none dark:border-[#2b8ffe]/35 dark:bg-[#032650]/80"
-              placeholder="每行一条关键约束"
+              placeholder="每行一项风险、依赖或待确认事项"
             />
           </label>
           <label className="block space-y-1.5">
             <span className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">
-              补充假设 / 说明
+              关键要点
             </span>
             <Textarea
-              value={draft.assumptions}
-              onChange={(event) => onChange({ ...draft, assumptions: event.target.value })}
+              value={draft.keyPoints}
+              onChange={(event) => onChange({ ...draft, keyPoints: event.target.value })}
               className="min-h-20 resize-none dark:border-[#2b8ffe]/35 dark:bg-[#032650]/80"
-              placeholder="可选，每行一条"
+              placeholder="每行一项关键要点"
+            />
+          </label>
+          <label className="block space-y-1.5">
+            <span className="text-xs font-semibold text-slate-500 dark:text-[#9ebfe2]">战略意义</span>
+            <Textarea
+              value={draft.strategicSignificance}
+              onChange={(event) => onChange({ ...draft, strategicSignificance: event.target.value })}
+              className="min-h-20 resize-none dark:border-[#2b8ffe]/35 dark:bg-[#032650]/80"
+              placeholder="每行一项战略意义"
             />
           </label>
         </div>
@@ -5949,7 +6046,7 @@ function deliverableFallbackContent(item: ResultItem | null): string {
 }
 
 function buildIntentResultItem(
-  intent: IntentSummary | null,
+  intent: PositionIntentSummary | null,
   updatedAt: string | undefined,
 ): ResultItem {
   return {
@@ -5958,7 +6055,10 @@ function buildIntentResultItem(
     node: null,
     agentName: "情报分析智能体",
     productName: "任务意图理解",
-    summary: intent?.objective || "任务意图已确认，当前没有更多意图摘要内容。",
+    summary:
+      intent?.strategicSignificance[0] ||
+      intent?.coreGoals[0] ||
+      "任务意图已确认，当前没有更多意图摘要内容。",
     positionId: intentPositionIdFor(),
     updatedAt,
     status: intent ? "done" : "ready",

frontend-web/src/position-roundtable/styles/intent-understanding.css

@@ -397,6 +397,15 @@
   color: #33bc92;
 }
 
+.position-roundtable-intent-delivery-section--significance {
+  border-left: 4px solid #45c3f3;
+  background: rgba(0, 98, 217, 0.12);
+}
+
+.position-roundtable-intent-delivery-section--significance h3 {
+  color: #45c3f3;
+}
+
 .position-roundtable-intent-delivery-section .is-empty {
   color: rgba(255, 255, 255, 0.62);
 }

frontend-web/src/roundtable-planning/api/intent.ts

@@ -4,11 +4,14 @@ import { getBackendBaseURL } from "@/core/config";
 import type { ClarificationPayload } from "./multi-agent";
 import { reportRoundtableError } from "./diagnostics-report";
 import { resolveAllowMultiple } from "@/roundtable-planning/lib/clarification";
+import { normalizeIntentReadySummary } from "@/roundtable-planning/lib/roundtable-constants";
 
 export type { ClarificationPayload };
 
 /** Stable built-in agent used by the multi-agent roundtable Step 1 flow. */
 export const INTENT_AGENT_ID = "roundtable-intent";
+/** Dedicated Step 1 agent for the position-roundtable workspace. */
+export const POSITION_INTENT_AGENT_ID = "position-roundtable-intent";
 
 /**
  * Task-intent agent (Step 1) API. Mirror of multi-agent.ts but with a single
@@ -103,13 +106,18 @@ function parseIntentErrorDetail(value: unknown): IntentErrorDetail | null {
 export async function initIntent(
   model?: string,
   taskContext?: Record<string, unknown> | null,
+  intentAgentId?: string,
 ): Promise<IntentInitResponse> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/intent/init`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     // 岗位会商在创建意图线程时就写入父任务标识。这样即使用户尚未确认
     // 业务链，第一阶段的对话也已经可以按 taskId 恢复。
-    body: JSON.stringify({ model, task_context: taskContext ?? undefined }),
+    body: JSON.stringify({
+      model,
+      task_context: taskContext ?? undefined,
+      intent_agent_id: intentAgentId || undefined,
+    }),
   });
   if (!res.ok) {
     const raw = await res.text().catch(() => "");
@@ -140,6 +148,19 @@ export interface IntentSummary {
   constraints: string[];
   /** Optional assumptions the agent is making on the user's behalf. */
   assumptions?: string[];
+  /** Present only for the dedicated position-roundtable intent agent. */
+  coreGoals?: string[];
+  riskWarnings?: string[];
+  keyPoints?: string[];
+  strategicSignificance?: string[];
+}
+
+/** Final hand-off shape emitted only by the position-roundtable intent agent. */
+export interface PositionIntentSummary {
+  coreGoals: string[];
+  riskWarnings: string[];
+  keyPoints: string[];
+  strategicSignificance: string[];
 }
 
 /**
@@ -167,6 +188,8 @@ export interface StreamIntentRequest {
   threadId: string;
   message: string;
   model?: string;
+  /** Explicit built-in Step-1 agent. Omit to retain the multi-agent default. */
+  intentAgentId?: string;
   /** Optional hidden business/task context injected into the model run. */
   taskContext?: Record<string, unknown> | null;
   /** Step 1 用户上传的参考文件（可选）。 */
@@ -189,8 +212,7 @@ export interface StreamIntentRequest {
    * Fires for every `ask_clarification` tool message parsed out of the live
    * stream (the intent agent may emit several in a single turn). Lets the UI
    * surface each assistance question in real-time instead of waiting for the
-   * terminal frame — which only carries the *first* question. `index` is the
-   * 0-based arrival order within this turn.
+   * terminal frame. `index` is the 0-based arrival order within this turn.
    */
   onClarification?: (clarification: ClarificationPayload, index: number) => void;
 }
@@ -211,8 +233,8 @@ export interface StreamIntentResult {
   clarification: ClarificationPayload | null;
   /**
    * All `ask_clarification` questions the agent asked this turn, in arrival
-   * order. Collected from the live `type:"tool"` frames (the terminal frame
-   * only carries the first). Empty unless status === "clarification".
+   * order. Collected live and reconciled against the terminal frame so a
+   * reconnect cannot lose cards. Empty unless status === "clarification".
    */
   clarifications: ClarificationPayload[];
   /**
@@ -238,6 +260,7 @@ function isFinalIntentFrame(value: unknown): value is {
   options?: unknown[];
   allow_custom?: boolean;
   allow_multiple?: boolean;
+  clarifications?: unknown[];
   error_detail?: unknown;
 } {
   if (!value || typeof value !== "object") return false;
@@ -330,6 +353,41 @@ function extractClarificationToolMessage(
   };
 }
 
+/**
+ * Normalize one clarification included in the terminal status frame. This is
+ * the reconnect / proxy fallback for cases where one or more live `tool`
+ * frames were not delivered to the browser.
+ */
+function parseTerminalClarification(
+  value: unknown,
+): { payload: ClarificationPayload; toolCallId: string } | null {
+  if (!value || typeof value !== "object") return null;
+  const raw = value as Record<string, unknown>;
+  const clarificationType =
+    typeof raw.clarification_type === "string" ? raw.clarification_type : "";
+  const toolCallId = typeof raw.id === "string" ? raw.id : "";
+  return {
+    toolCallId,
+    payload: {
+      id: toolCallId || undefined,
+      question: typeof raw.question === "string" ? raw.question : "",
+      clarificationType,
+      context:
+        typeof raw.clarification_context === "string"
+          ? raw.clarification_context
+          : typeof raw.context === "string"
+            ? raw.context
+            : "",
+      options: Array.isArray(raw.options) ? raw.options : [],
+      allowCustom: raw.allow_custom !== false,
+      allowMultiple: resolveAllowMultiple(
+        typeof raw.allow_multiple === "boolean" ? raw.allow_multiple : undefined,
+        clarificationType,
+      ),
+    },
+  };
+}
+
 /**
  * Open an SSE connection to /api/intent/stream and resolve when the upstream
  * stream completes. Each call is one user turn; reuse the same threadId
@@ -343,6 +401,7 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
       thread_id: req.threadId,
       message: req.message,
       model: req.model,
+      intent_agent_id: req.intentAgentId || undefined,
       task_context: req.taskContext ?? undefined,
       // 仅在有文件时带上，空数组后端也安全忽略。
       files: req.files && req.files.length > 0 ? req.files : undefined,
@@ -390,8 +449,7 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
   };
 
   // Clarifications collected live from `type:"tool"` frames, deduped by
-  // tool_call_id. The terminal frame only carries the first question, so this
-  // is the source of truth for multi-question turns.
+  // tool_call_id, then reconciled against the complete terminal list.
   const seenClarificationIds = new Set<string>();
   const collectClarification = (payload: ClarificationPayload, toolCallId: string) => {
     const dedupeKey = toolCallId || `idx-${result.clarifications.length}`;
@@ -438,7 +496,7 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
         result.status = parsed.status;
         if (typeof parsed.content === "string") result.content = parsed.content;
         if (parsed.summary && typeof parsed.summary === "object") {
-          result.summary = parsed.summary as IntentSummary;
+          result.summary = normalizeIntentReadySummary(parsed.summary);
         }
         if (parsed.status === "error") {
           result.errorDetail = parseIntentErrorDetail(parsed.error_detail);
@@ -448,28 +506,26 @@ export async function streamIntent(req: StreamIntentRequest): Promise<StreamInte
             detail: result.errorDetail,
           });
         }
-        if (parsed.status === "clarification" && result.clarifications.length === 0) {
-          // Fallback path: no live `type:"tool"` clarification frames were seen
-          // (older backend, or single-question turn) — synthesize one from the
-          // terminal frame so the UI still gets a card. When tool frames *were*
-          // seen, `clarifications` already holds the full (possibly multi-question)
-          // set and we keep it.
-          const clarificationType =
-            typeof parsed.clarification_type === "string" ? parsed.clarification_type : "";
-          const fallback: ClarificationPayload = {
-            question: typeof parsed.question === "string" ? parsed.question : "",
-            clarificationType,
-            context:
-              typeof parsed.clarification_context === "string" ? parsed.clarification_context : "",
-            options: Array.isArray(parsed.options) ? parsed.options : [],
-            allowCustom: parsed.allow_custom !== false,
-            allowMultiple: resolveAllowMultiple(
-              typeof parsed.allow_multiple === "boolean" ? parsed.allow_multiple : undefined,
-              clarificationType,
-            ),
-          };
-          result.clarification = fallback;
-          result.clarifications = [fallback];
+        if (parsed.status === "clarification") {
+          // Newer backend frames contain every card. Merge them even when a
+          // subset already arrived live: an SSE reconnect can otherwise leave
+          // the user with only the first card in a multi-question assistance
+          // round. Older backends still fall back to the legacy top-level card.
+          const terminalCards = Array.isArray(parsed.clarifications)
+            ? parsed.clarifications
+                .map(parseTerminalClarification)
+                .filter((item): item is { payload: ClarificationPayload; toolCallId: string } => item !== null)
+            : [];
+          if (terminalCards.length > 0) {
+            terminalCards.forEach((card, index) => {
+              collectClarification(card.payload, card.toolCallId || `terminal-${index}`);
+            });
+          } else if (result.clarifications.length === 0) {
+            const fallback = parseTerminalClarification(parsed);
+            if (fallback) {
+              collectClarification(fallback.payload, fallback.toolCallId || "terminal-0");
+            }
+          }
         }
         continue;
       }

frontend-web/src/roundtable-planning/components/BusinessChainPicker.tsx

@@ -153,6 +153,10 @@ export function BusinessChainPicker({
     // 席位「会商技能识别强化」开关（链条配置）：按 agent_id 取，缺省 = 关。
     const skillById = new Map(selectedChain.seats.map((s) => [s.agent_id, s.seat_skill_directive ?? false]));
     const skillOf = (id: string) => skillById.get(id) ?? false;
+    const humanValidationById = new Map(
+      selectedChain.seats.map((s) => [s.agent_id, s.human_validation ?? false]),
+    );
+    const humanValidationOf = (id: string) => humanValidationById.get(id) ?? false;
     // 席位「推理深度覆盖」（链条配置 seat_mode）：按 agent_id 取，null/缺省 = 跟随链条级 seatMode。
     const seatModeById = new Map(selectedChain.seats.map((s) => [s.agent_id, s.seat_mode ?? null]));
     const seatModeOf = (id: string) => seatModeById.get(id) ?? null;
@@ -162,12 +166,12 @@ export function BusinessChainPicker({
       // dag：席位顺序按 stage 展平（与 plan 一致）。
       const agents = dagPlan.stages
         .flatMap((st) => st.agentIds)
-        .map((id) => ({ agent_id: id, name: nameOf(id), model: modelOf(id), seat_skill_directive: skillOf(id), seatMode: seatModeOf(id) }));
+        .map((id) => ({ agent_id: id, name: nameOf(id), model: modelOf(id), seat_skill_directive: skillOf(id), human_validation: humanValidationOf(id), seatMode: seatModeOf(id) }));
       onConfirm({ agents, mode: "dag", chain: chainMeta, plan: dagPlan, dagExecMode, gatherFirst: selectedChain.gatherFirst ?? false });
       return;
     }
 
-    const agents = survivingSeats.map((s) => ({ agent_id: s.agent_id, name: nameOf(s.agent_id), model: modelOf(s.agent_id), seat_skill_directive: skillOf(s.agent_id), seatMode: seatModeOf(s.agent_id) }));
+    const agents = survivingSeats.map((s) => ({ agent_id: s.agent_id, name: nameOf(s.agent_id), model: modelOf(s.agent_id), seat_skill_directive: skillOf(s.agent_id), human_validation: humanValidationOf(s.agent_id), seatMode: seatModeOf(s.agent_id) }));
     onConfirm({ agents, mode: "chain", chain: chainMeta, gatherFirst: selectedChain.gatherFirst ?? false });
   };
 

frontend-web/src/roundtable-planning/components/Step1Panel.tsx

@@ -688,6 +688,15 @@ function Step1Message({
 
 /** [INTENT_READY] 标记块解析出 IntentSummary 后的绿色摘要卡。 */
 function IntentReadySummaryCard({ summary }: { summary: IntentSummary }) {
+  const positionSections =
+    summary.coreGoals && summary.riskWarnings && summary.keyPoints && summary.strategicSignificance
+      ? ([
+          ["核心目标", summary.coreGoals],
+          ["风险提示", summary.riskWarnings],
+          ["关键要点", summary.keyPoints],
+          ["战略意义", summary.strategicSignificance],
+        ] as const)
+      : null;
   return (
     <div className="mt-1 border border-emerald-200 bg-emerald-50/50 rounded-xl p-3 space-y-2">
       <div className="flex items-center gap-1.5">
@@ -696,30 +705,35 @@ function IntentReadySummaryCard({ summary }: { summary: IntentSummary }) {
           任务意图已明确
         </span>
       </div>
-      <div className="space-y-1">
-        <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">核心目标</span>
-        <p className="text-[11.5px] text-slate-800 leading-relaxed">{summary.objective}</p>
-      </div>
-      {summary.constraints?.length > 0 && (
-        <div className="space-y-1">
-          <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">约束条件</span>
-          <ul className="list-disc pl-4 space-y-0.5 text-[11px] text-slate-700">
-            {summary.constraints.map((c, i) => (
-              <li key={i} className="leading-snug">{c}</li>
-            ))}
-          </ul>
+      {positionSections ? positionSections.map(([label, values]) => (
+        <div key={label} className="space-y-1">
+          <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">{label}</span>
+          {values.length > 0 ? <ul className="list-disc pl-4 space-y-0.5 text-[11px] text-slate-700">
+            {values.map((value, index) => <li key={index} className="leading-snug">{value}</li>)}
+          </ul> : <p className="text-[11px] text-slate-500">暂无{label}</p>}
         </div>
-      )}
-      {summary.assumptions && summary.assumptions.length > 0 && (
+      )) : <>
         <div className="space-y-1">
-          <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">关键假设</span>
-          <ul className="list-disc pl-4 space-y-0.5 text-[11px] text-slate-700">
-            {summary.assumptions.map((a, i) => (
-              <li key={i} className="leading-snug">{a}</li>
-            ))}
-          </ul>
+          <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">核心目标</span>
+          <p className="text-[11.5px] text-slate-800 leading-relaxed">{summary.objective}</p>
         </div>
-      )}
+        {summary.constraints?.length > 0 && (
+          <div className="space-y-1">
+            <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">约束条件</span>
+            <ul className="list-disc pl-4 space-y-0.5 text-[11px] text-slate-700">
+              {summary.constraints.map((c, i) => <li key={i} className="leading-snug">{c}</li>)}
+            </ul>
+          </div>
+        )}
+        {summary.assumptions && summary.assumptions.length > 0 && (
+          <div className="space-y-1">
+            <span className="text-[10px] font-bold text-slate-500 uppercase tracking-wider">关键假设</span>
+            <ul className="list-disc pl-4 space-y-0.5 text-[11px] text-slate-700">
+              {summary.assumptions.map((a, i) => <li key={i} className="leading-snug">{a}</li>)}
+            </ul>
+          </div>
+        )}
+      </>}
     </div>
   );
 }

frontend-web/src/roundtable-planning/hooks/useStep1Intent.ts

@@ -90,6 +90,8 @@ export interface UseStep1IntentOptions {
   currentStep: number;
   /** 全局选中模型;调用 `/api/intent/init` / `/api/intent/stream` 时透传。 */
   selectedModel: string;
+  /** Optional built-in agent override for a workspace with a distinct schema. */
+  intentAgentId?: string;
   /** Optional hidden task/business context for each intent-agent turn. */
   taskContext?: Record<string, unknown> | null;
   /** Optional task-aware welcome bubble text before the first user turn. */
@@ -178,6 +180,7 @@ export function useStep1Intent(options: UseStep1IntentOptions): UseStep1IntentRe
   const {
     currentStep,
     selectedModel,
+    intentAgentId,
     taskContext,
     initialWelcomeText,
     showInitialWelcome = true,
@@ -214,6 +217,10 @@ export function useStep1Intent(options: UseStep1IntentOptions): UseStep1IntentRe
   useEffect(() => {
     selectedModelRef.current = selectedModel;
   }, [selectedModel]);
+  const intentAgentIdRef = useRef<string | undefined>(intentAgentId);
+  useEffect(() => {
+    intentAgentIdRef.current = intentAgentId;
+  }, [intentAgentId]);
   const taskContextRef = useRef<Record<string, unknown> | null>(taskContext ?? null);
   useEffect(() => {
     taskContextRef.current = taskContext ?? null;
@@ -265,6 +272,7 @@ export function useStep1Intent(options: UseStep1IntentOptions): UseStep1IntentRe
         const res = await initIntent(
           selectedModelRef.current || undefined,
           taskContextRef.current,
+          intentAgentIdRef.current,
         );
         if (step1InitGenRef.current !== myGen) return;
         setIntentThreadId(res.thread_id);
@@ -443,6 +451,7 @@ export function useStep1Intent(options: UseStep1IntentOptions): UseStep1IntentRe
           threadId: intentThreadId,
           message: trimmed,
           model: selectedModelRef.current || undefined,
+          intentAgentId: intentAgentIdRef.current,
           taskContext: taskContextRef.current,
           files: fileRefs,
           signal: aborter.signal,

frontend-web/src/roundtable-planning/hooks/useStep2Orchestration.ts

@@ -33,6 +33,13 @@ import { useUpdateSubtask } from "@/core/tasks/context";
 /** 干预消息携带的上传文件引用（与 streamMultiAgent 的 files 字段同形）。 */
 type RunFileRef = NonNullable<StreamMultiAgentRequest["files"]>[number];
 
+type SeatDelivery = { name: string; content: string };
+
+/** In-memory cursor for a business-chain human-validation pause. */
+type HumanValidationContinuation =
+  | { mode: "chain"; nextSeatIndex: number }
+  | { mode: "dag"; nextStageIndex: number; priorDeliveries: SeatDelivery[] };
+
 /** 读取并清空 ref（consume-once）：首个 leader run 拿到文件后清空，后续轮次不再带。 */
 function takeOnce<T>(ref: { current: T | null }): T | undefined {
   const v = ref.current ?? undefined;
@@ -286,6 +293,8 @@ export interface UseStep2OrchestrationOptions {
    * OR。recommend / 未选链条 → 空 {}（各席位仅靠其自身开关）。
    */
   seatSkillDirectives?: Record<string, boolean>;
+  /** Per-seat human-validation checkpoints inherited from the selected chain. */
+  humanValidations?: Record<string, boolean>;
   /**
    * 每席位「推理深度覆盖」映射 {agentId: SeatMode | null}（沿用所选业务链条里每个席位的配置）。
    * 派活该 special 席位时按 agentId 查表，**席位覆盖优先、否则跟随链条级 `selectedMode`**：
@@ -456,6 +465,7 @@ export function useStep2Orchestration(
     selectedModel,
     selectedMode,
     seatSkillDirectives = {},
+    humanValidations = {},
     seatModes = {},
     gatherFirst = false,
     orchestrationMode,
@@ -593,6 +603,7 @@ export function useStep2Orchestration(
   const selectedModeRef = useRef<SeatMode>(selectedMode);
   // 每席位技能识别强化映射（所选业务链条各席位开关）同样打到 ref，席位调用按 agentId 读最新值。
   const seatSkillDirectivesRef = useRef<Record<string, boolean>>(seatSkillDirectives);
+  const humanValidationsRef = useRef<Record<string, boolean>>(humanValidations);
   // 每席位推理深度覆盖映射（所选业务链条各席位 seatMode）打到 ref，席位调用按 agentId 读最新值；
   // 覆盖优先、否则跟随 selectedModeRef。
   const seatModesRef = useRef<Record<string, SeatMode | null>>(seatModes);
@@ -624,6 +635,7 @@ export function useStep2Orchestration(
   // 澄清回复都改走 **leader 自由派活循环**（runOrchestration），由总控接着派活，而**不是**
   // 重新把整张 DAG 从头跑一遍（致命 bug 修复）。新任务 / 重新进入时由 resetInitGate 复位。
   const dagPlanExecutedRef = useRef<boolean>(false);
+  const humanValidationContinuationRef = useRef<HumanValidationContinuation | null>(null);
   const selectedAgentsRef = useRef<SelectedAgent[]>(selectedAgents);
   useEffect(() => {
     orchestrationModeRef.current = orchestrationMode;
@@ -643,6 +655,9 @@ export function useStep2Orchestration(
   useEffect(() => {
     seatSkillDirectivesRef.current = seatSkillDirectives;
   }, [seatSkillDirectives]);
+  useEffect(() => {
+    humanValidationsRef.current = humanValidations;
+  }, [humanValidations]);
   useEffect(() => {
     seatModesRef.current = seatModes;
   }, [seatModes]);
@@ -1213,6 +1228,21 @@ export function useStep2Orchestration(
     [],
   );
 
+  const pauseForHumanValidation = useCallback(
+    (continuation: HumanValidationContinuation, seatNames: string[]) => {
+      humanValidationContinuationRef.current = continuation;
+      appendDialogue({
+        sender: "系统",
+        avatarType: "blue",
+        content: `已完成 ${seatNames.join("、")} 的输出，按业务链条配置暂停，等待人工校验。可直接点击“恢复会商”继续，或在下方输入修改意见后提交。`,
+        confidence: "等待人工校验",
+      });
+      setIsRoundTableRunning(false);
+      triggerToast("已暂停等待人工校验：可恢复会商，或输入修改意见后继续");
+    },
+    [appendDialogue, triggerToast],
+  );
+
   const phaseLabel = useCallback(
     (
       phase: StreamPhase,
@@ -2012,11 +2042,17 @@ export function useStep2Orchestration(
 
       const chainSeats = selectedAgentsRef.current;
       const total = chainSeats.length;
+      const continuation = humanValidationContinuationRef.current;
+      const startSeatIndex =
+        continuation?.mode === "chain" ? continuation.nextSeatIndex : 0;
+      if (continuation?.mode === "chain") {
+        humanValidationContinuationRef.current = null;
+      }
       const leaderThreadId = resolveSeatThreadId(ids, coord);
       let finishedAllSeats = true;
 
       try {
-        for (let i = 0; i < total; i += 1) {
+        for (let i = startSeatIndex; i < total; i += 1) {
           if (isStale()) {
             finishedAllSeats = false;
             break;
@@ -2179,6 +2215,14 @@ export function useStep2Orchestration(
           }
 
           setConsensusPercentage(Math.min(95, Math.round(((i + 1) / total) * 90)));
+          if (humanValidationsRef.current[seat.agent_id]) {
+            pauseForHumanValidation(
+              { mode: "chain", nextSeatIndex: i + 1 },
+              [seatName],
+            );
+            finishedAllSeats = false;
+            break;
+          }
         }
 
         // ── (c) 总控收口:综合全链交付,产出最终结论 ──
@@ -2257,6 +2301,7 @@ export function useStep2Orchestration(
       handleUpstreamFrame,
       ingestSubagentTaskFrame,
       resolveSeatThreadId,
+      pauseForHumanValidation,
     ],
   );
 
@@ -2300,23 +2345,37 @@ export function useStep2Orchestration(
       dagPlanExecutedRef.current = true;
 
       const leaderThreadId = resolveSeatThreadId(ids, coord);
+      const continuation = humanValidationContinuationRef.current;
+      const startStageIndex =
+        continuation?.mode === "dag" ? continuation.nextStageIndex : 0;
+      if (continuation?.mode === "dag") {
+        humanValidationContinuationRef.current = null;
+      }
       let finishedAllStages = true;
       // 跨 stage 累积的**完整交付** {name, content}[] —— 注入下一 stage 席位的 run context
       // (peerDeliveries),供 read_peer_delivery 工具按需取全文(§12.9 传摘要按需传全文)。
       // 研讨前并行取数（gatherFirst）的产物作为初始注入：首个 stage 席位开局即带共享资料。
-      const priorDeliveries: Array<{ name: string; content: string }> = [...gatheredDeliveriesRef.current];
+      const priorDeliveries: SeatDelivery[] =
+        continuation?.mode === "dag"
+          ? [...continuation.priorDeliveries]
+          : [...gatheredDeliveriesRef.current];
 
       // Phase 7：初始化 DAG 流程图节点状态 —— 计划内所有席位置 pending,执行过程中逐个点亮。
       const markDagNode = (agentId: string, state: ChainNodeState) =>
         setDagNodeStates((prev) => ({ ...prev, [agentId.toLowerCase()]: state }));
       setDagNodeStates(
         Object.fromEntries(
-          plan.stages.flatMap((st) => st.agentIds.map((id) => [id.toLowerCase(), "pending" as ChainNodeState])),
+          plan.stages.flatMap((st, stageIndex) =>
+            st.agentIds.map((id) => [
+              id.toLowerCase(),
+              (stageIndex < startStageIndex ? "done" : "pending") as ChainNodeState,
+            ]),
+          ),
         ),
       );
 
       try {
-        for (let s = 0; s < plan.stages.length; s += 1) {
+        for (let s = startStageIndex; s < plan.stages.length; s += 1) {
           if (isStale()) {
             finishedAllStages = false;
             break;
@@ -2558,6 +2617,21 @@ export function useStep2Orchestration(
           setConsensusPercentage(
             Math.min(95, Math.round(((s + 1) / plan.stages.length) * 90)),
           );
+          const validationSeatNames = stageSeats
+            .filter(({ agentId }) => humanValidationsRef.current[agentId])
+            .map(({ name }) => name);
+          if (validationSeatNames.length > 0) {
+            pauseForHumanValidation(
+              {
+                mode: "dag",
+                nextStageIndex: s + 1,
+                priorDeliveries: [...priorDeliveries],
+              },
+              validationSeatNames,
+            );
+            finishedAllStages = false;
+            break;
+          }
         }
 
         // ── 计划阶段全部完成 → **交给总控（leader 自由派活循环）继续** ──
@@ -2613,6 +2687,7 @@ export function useStep2Orchestration(
       ingestParallelDelta,
       resetParallelStreams,
       runOrchestration,
+      pauseForHumanValidation,
     ],
   );
 
@@ -2746,8 +2821,9 @@ export function useStep2Orchestration(
       // 改走 leader 自由派活循环,由总控接着派活,而不是把 DAG 从头重跑一遍。
       if (
         mode === "dag" &&
-        !dagPlanExecutedRef.current &&
-        (orchestrationPlanRef.current?.stages.length ?? 0) > 0
+        (humanValidationContinuationRef.current?.mode === "dag" ||
+          (!dagPlanExecutedRef.current &&
+            (orchestrationPlanRef.current?.stages.length ?? 0) > 0))
       ) {
         return runDagOrchestration(seedMessage, ids, coord);
       }
@@ -3070,6 +3146,7 @@ export function useStep2Orchestration(
 
   const resetInitGate = useCallback(() => {
     step2InitRef.current = false;
+    humanValidationContinuationRef.current = null;
     // 新一轮研讨:允许 DAG 计划重新执行一遍。
     dagPlanExecutedRef.current = false;
     // 新一轮研讨:允许「研讨前并行取数」再取一次（清掉上一轮取数产物 + 闸门）。
@@ -3086,6 +3163,7 @@ export function useStep2Orchestration(
       // 这里只重复设 cancel ref 与 UI 标记,确保从 Step 2 在编排中切到草稿时
       // UI 立刻翻成静止态。
       orchestrationCancelRef.current = true;
+      humanValidationContinuationRef.current = null;
       setIsOrchestrating(false);
       setIsInitializing(false);
       setPendingClarification(null);
@@ -3166,6 +3244,7 @@ export function useStep2Orchestration(
       return false;
     }
     dagPlanExecutedRef.current = true;
+    humanValidationContinuationRef.current = null;
     orchestrationCancelRef.current = true;
     abortAllInFlight();
     isOrchestratingRef.current = false;
@@ -3208,6 +3287,7 @@ export function useStep2Orchestration(
     hasAutoOpenedRef.current = new Set();
     pendingInjectPromptRef.current = null;
     dagPlanExecutedRef.current = false;
+    humanValidationContinuationRef.current = null;
     gatherPhaseDoneRef.current = false;
     gatheredDeliveriesRef.current = [];
     deselectArtifact();

frontend-web/src/roundtable-planning/lib/business-chain.ts

@@ -36,6 +36,11 @@ export interface ChainSeat {
    * （无需 DB 列），在链条编辑器里逐席位开关。
    */
   seat_skill_directive?: boolean;
+  /**
+   * Human-validation checkpoint. When enabled, Step 2 pauses after this seat
+   * (or its DAG stage) completes and reuses the existing resume/intervention UI.
+   */
+  human_validation?: boolean;
   /**
    * 可选「席位推理深度覆盖」：覆盖链条级 `seatMode`，只对该席位生效。值是同一套
    * `SeatMode`（flash/thinking/pro/ultra）；null / 缺省 = 跟随链条级默认。用于「卡顿提速」：
@@ -109,7 +114,7 @@ export interface SeatSelectionResult {
    * `model` 为该席位在来源链条里配置的模型覆盖（空 / 缺省 = 跟随全局模型）。
    * `seat_skill_directive` 为该席位在来源链条里配置的「技能识别强化」开关（缺省 = 关）。
    */
-  agents: Array<{ agent_id: string; name: string; model?: string | null; seat_skill_directive?: boolean; seatMode?: SeatMode | null }>;
+  agents: Array<{ agent_id: string; name: string; model?: string | null; seat_skill_directive?: boolean; human_validation?: boolean; seatMode?: SeatMode | null }>;
   /**
    * 决定 Step 2 走哪种编排：
    *  - `recommend` 总控自由派活；
@@ -171,6 +176,10 @@ export function buildChainSeatSelection(
   // 席位「技能识别强化」开关（链条配置）：按 agent_id 取，缺省 = 关。
   const skillById = new Map(chain.seats.map((s) => [s.agent_id, s.seat_skill_directive ?? false]));
   const skillOf = (id: string) => skillById.get(id) ?? false;
+  const humanValidationById = new Map(
+    chain.seats.map((s) => [s.agent_id, s.human_validation ?? false]),
+  );
+  const humanValidationOf = (id: string) => humanValidationById.get(id) ?? false;
   // 席位「推理深度覆盖」（链条配置 seat_mode）：按 agent_id 取，null/缺省 = 跟随链条级 seatMode。
   // 输出到 SeatSelectionResult.agents[].seatMode（camel，喂给编排/作业的 seatModes map）。
   const seatModeById = new Map(chain.seats.map((s) => [s.agent_id, s.seat_mode ?? null]));
@@ -196,12 +205,12 @@ export function buildChainSeatSelection(
     if (hasParallel || hasGoal || hasCoord) {
       const agents = plan.stages
         .flatMap((st) => st.agentIds)
-        .map((id) => ({ agent_id: id, name: nameOf(id), model: modelOf(id), seat_skill_directive: skillOf(id), seatMode: seatModeOf(id) }));
+        .map((id) => ({ agent_id: id, name: nameOf(id), model: modelOf(id), seat_skill_directive: skillOf(id), human_validation: humanValidationOf(id), seatMode: seatModeOf(id) }));
       return { agents, mode: "dag", chain: chainMeta, plan, dagExecMode: "sandbox", seatMode: chain.seatMode, gatherFirst: chain.gatherFirst ?? false };
     }
   }
 
-  const agents = survivingSeats.map((s) => ({ agent_id: s.agent_id, name: nameOf(s.agent_id), model: modelOf(s.agent_id), seat_skill_directive: skillOf(s.agent_id), seatMode: seatModeOf(s.agent_id) }));
+  const agents = survivingSeats.map((s) => ({ agent_id: s.agent_id, name: nameOf(s.agent_id), model: modelOf(s.agent_id), seat_skill_directive: skillOf(s.agent_id), human_validation: humanValidationOf(s.agent_id), seatMode: seatModeOf(s.agent_id) }));
   return { agents, mode: "chain", chain: chainMeta, seatMode: chain.seatMode, gatherFirst: chain.gatherFirst ?? false };
 }
 

frontend-web/src/roundtable-planning/lib/chain-stages.test.ts

@@ -12,6 +12,7 @@ import {
   moveSeatToStage,
   moveStage,
   removeSeat,
+  setSeatHumanValidation,
   setStageGoal,
   splitSeatToNewStage,
   stageGroupsToSeats,
@@ -122,6 +123,15 @@ test("setStageGoal is immutable + out-of-range no-op", () => {
   assert.equal(setStageGoal(groups, 9, "x"), groups); // 越界返回原引用
 });
 
+test("setSeatHumanValidation updates only the selected seat and is immutable", () => {
+  const groups = grp([seat("a"), seat("b")], [seat("c")]);
+  const next = setSeatHumanValidation(groups, "b", true);
+  assert.equal(next[0].seats[1].human_validation, true);
+  assert.equal(next[0].seats[0].human_validation, undefined);
+  assert.equal(next[1].seats[0].human_validation, undefined);
+  assert.equal(groups[0].seats[1].human_validation, undefined);
+});
+
 // ── lookups ───────────────────────────────────────────────────────────────────
 
 test("findStageIndexOfSeat / countSeats", () => {

frontend-web/src/roundtable-planning/lib/chain-stages.ts

@@ -141,6 +141,23 @@ export function setSeatSkillDirective(groups: StageGroups, agentId: string, enab
   });
 }
 
+/** Update a seat's human-validation checkpoint without changing other stages. */
+export function setSeatHumanValidation(
+  groups: StageGroups,
+  agentId: string,
+  enabled: boolean,
+): StageGroups {
+  return groups.map((g) => {
+    if (!g.seats.some((s) => s.agent_id === agentId)) return g;
+    return {
+      ...g,
+      seats: g.seats.map((s) =>
+        s.agent_id === agentId ? { ...s, human_validation: enabled } : s,
+      ),
+    };
+  });
+}
+
 /**
  * 设置某个席位的「推理深度覆盖」（不可变，供编辑器席位下拉 onChange）。
  * `mode` 为 null = 清除覆盖（跟随链条级 seatMode）。按 agent_id 定位，跨 stage 适用。

frontend-web/src/roundtable-planning/lib/roundtable-constants.ts

@@ -292,9 +292,29 @@ function toStringArray(value: unknown): string[] {
  * 把解析出的对象归一成 IntentSummary。只要 `objective` 是非空字符串就认。
  * constraints / assumptions 容忍模型写成字符串 / null / 缺失,统一归到 string[]。
  */
-function normalizeIntentSummary(parsed: unknown): IntentSummary | null {
+export function normalizeIntentReadySummary(parsed: unknown): IntentSummary | null {
   if (!parsed || typeof parsed !== "object") return null;
   const obj = parsed as Record<string, unknown>;
+  const positionKeys = ["coreGoals", "riskWarnings", "keyPoints", "strategicSignificance"];
+  if (positionKeys.some((key) => key in obj)) {
+    if (!positionKeys.every((key) => Array.isArray(obj[key]))) return null;
+    const coreGoals = toStringArray(obj.coreGoals);
+    const riskWarnings = toStringArray(obj.riskWarnings);
+    const keyPoints = toStringArray(obj.keyPoints);
+    const strategicSignificance = toStringArray(obj.strategicSignificance);
+    // Keep the long-standing Step-1 state machine compatible while retaining
+    // every position-specific field verbatim for its dedicated UI and storage.
+    return {
+      objective:
+        strategicSignificance[0] || coreGoals[0] || keyPoints[0] || "岗位任务意图已识别",
+      constraints: riskWarnings,
+      assumptions: keyPoints,
+      coreGoals,
+      riskWarnings,
+      keyPoints,
+      strategicSignificance,
+    };
+  }
   const objective =
     typeof obj.objective === "string" ? obj.objective.trim() : "";
   if (!objective) return null;
@@ -310,14 +330,14 @@ function normalizeIntentSummary(parsed: unknown): IntentSummary | null {
  *   1) 原文直接 parse
  *   2) 转义字符串内的裸控制字符(换行 / 制表符)后再 parse
  *   3) 再去掉尾随逗号后 parse
- * 三次都失败才放弃。任一成功都过 `normalizeIntentSummary` 兜字段类型。
+ * 三次都失败才放弃。任一成功都过 `normalizeIntentReadySummary` 兜字段类型。
  */
 function parseIntentSummary(raw: string): IntentSummary | null {
   const sanitized = sanitizeJsonControlChars(raw);
   const candidates = [raw, sanitized, stripTrailingCommas(sanitized)];
   for (const candidate of candidates) {
     try {
-      const summary = normalizeIntentSummary(JSON.parse(candidate));
+      const summary = normalizeIntentReadySummary(JSON.parse(candidate));
       if (summary) return summary;
     } catch {
       // 下一个候选

frontend-web/src/roundtable-planning/pages/BusinessChainEditorPage.tsx

@@ -41,6 +41,7 @@ import {
   Sparkles,
   SplitSquareVertical,
   Trash2,
+  UserCheck,
   UserPlus,
   Wand2,
   X,
@@ -127,6 +128,7 @@ import {
   seatExistsInGroups,
   setSeatMode as setSeatModeOnGroups,
   setSeatModel,
+  setSeatHumanValidation,
   setSeatSkillDirective,
   setStageGoal,
   splitSeatToNewStage,
@@ -453,6 +455,10 @@ export default function BusinessChainEditorPage() {
     setStageGroups((prev) => setSeatSkillDirective(prev, agentId, enabled));
   }, []);
 
+  const setSeatHumanValidationCb = useCallback((agentId: string, enabled: boolean) => {
+    setStageGroups((prev) => setSeatHumanValidation(prev, agentId, enabled));
+  }, []);
+
   // 席位「推理深度覆盖」：编辑器席位小图标下拉 onChange（null = 清除，跟随链条级 seatMode）。
   const setSeatModeCb = useCallback((agentId: string, mode: SeatMode | null) => {
     setStageGroups((prev) => setSeatModeOnGroups(prev, agentId, mode));
@@ -670,6 +676,7 @@ export default function BusinessChainEditorPage() {
           model: s.model ?? null,
           // 席位「会商技能识别强化」开关：随席位一起落库（缺省 = false 关）。
           seat_skill_directive: s.seat_skill_directive ?? false,
+          human_validation: s.human_validation ?? false,
           // 席位「推理深度覆盖」：随席位一起落库（null = 跟随链条级 seatMode）。
           seat_mode: s.seat_mode ?? null,
           // 岗位协同专用岗位归属：普通圆桌忽略，但保存时必须原样保留。
@@ -1272,6 +1279,7 @@ export default function BusinessChainEditorPage() {
             onSplitSeat={splitSeat}
             onSeatModelChange={setSeatModelCb}
             onSeatSkillDirectiveChange={setSeatSkillDirectiveCb}
+            onSeatHumanValidationChange={setSeatHumanValidationCb}
             onSeatModeChange={setSeatModeCb}
             positionConfigMode={positionConfigMode}
             positionOptions={positionOptions}
@@ -1455,6 +1463,7 @@ function StagesColumn({
   onSplitSeat,
   onSeatModelChange,
   onSeatSkillDirectiveChange,
+  onSeatHumanValidationChange,
   onSeatModeChange,
   positionConfigMode,
   positionOptions,
@@ -1476,6 +1485,7 @@ function StagesColumn({
   onSplitSeat: (agentId: string) => void;
   onSeatModelChange: (agentId: string, model: string | null) => void;
   onSeatSkillDirectiveChange: (agentId: string, enabled: boolean) => void;
+  onSeatHumanValidationChange: (agentId: string, enabled: boolean) => void;
   onSeatModeChange: (agentId: string, mode: SeatMode | null) => void;
   /** 仅岗位协同入口启用；普通圆桌编辑器不显示岗位控件。 */
   positionConfigMode: boolean;
@@ -1586,6 +1596,7 @@ function StagesColumn({
                 onSplitSeat={onSplitSeat}
                 onSeatModelChange={onSeatModelChange}
                 onSeatSkillDirectiveChange={onSeatSkillDirectiveChange}
+                onSeatHumanValidationChange={onSeatHumanValidationChange}
                 onSeatModeChange={onSeatModeChange}
                 positionConfigMode={positionConfigMode}
                 positionOptions={positionOptions}
@@ -1620,6 +1631,7 @@ function StageSection({
   onSplitSeat,
   onSeatModelChange,
   onSeatSkillDirectiveChange,
+  onSeatHumanValidationChange,
   onSeatModeChange,
   positionConfigMode,
   positionOptions,
@@ -1643,6 +1655,7 @@ function StageSection({
   onSplitSeat: (agentId: string) => void;
   onSeatModelChange: (agentId: string, model: string | null) => void;
   onSeatSkillDirectiveChange: (agentId: string, enabled: boolean) => void;
+  onSeatHumanValidationChange: (agentId: string, enabled: boolean) => void;
   onSeatModeChange: (agentId: string, mode: SeatMode | null) => void;
   positionConfigMode: boolean;
   positionOptions: readonly PositionOption[];
@@ -1809,6 +1822,7 @@ function StageSection({
                 onSplit={() => onSplitSeat(seat.agent_id)}
                 onModelChange={(model) => onSeatModelChange(seat.agent_id, model)}
                 onSkillDirectiveChange={(enabled) => onSeatSkillDirectiveChange(seat.agent_id, enabled)}
+                onHumanValidationChange={(enabled) => onSeatHumanValidationChange(seat.agent_id, enabled)}
                 onSeatModeChange={(mode) => onSeatModeChange(seat.agent_id, mode)}
                 showPositionConfig={positionConfigMode}
                 positionOptions={positionOptions}
@@ -1837,6 +1851,7 @@ function SeatStrip({
   onSplit,
   onModelChange,
   onSkillDirectiveChange,
+  onHumanValidationChange,
   onSeatModeChange,
   showPositionConfig,
   positionOptions,
@@ -1857,6 +1872,7 @@ function SeatStrip({
   onModelChange: (model: string | null) => void;
   /** 席位「会商技能识别强化」开关变更。 */
   onSkillDirectiveChange: (enabled: boolean) => void;
+  onHumanValidationChange: (enabled: boolean) => void;
   /** 席位「推理深度覆盖」变更（null = 跟随链条级 seatMode）。 */
   onSeatModeChange: (mode: SeatMode | null) => void;
   /** 仅岗位协同入口展示的岗位配置。 */
@@ -2058,6 +2074,38 @@ function SeatStrip({
             </div>
           </DropdownMenuContent>
         </DropdownMenu>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <button
+              type="button"
+              title="人工校验：该席位完成后暂停会商，等待用户恢复或输入修改意见"
+              className={cn(
+                "p-1 transition",
+                R_CTRL,
+                seat.human_validation
+                  ? "bg-primary/10 text-primary"
+                  : "text-muted-foreground hover:bg-muted hover:text-foreground",
+              )}
+            >
+              <UserCheck className="size-3.5" />
+            </button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-64 p-3">
+            <div className="flex items-start justify-between gap-3">
+              <div className="space-y-0.5">
+                <p className="text-xs font-semibold text-foreground">人工校验</p>
+                <p className="text-[11px] leading-relaxed text-muted-foreground">
+                  开启后，该席位所在的执行单元完成时会自动暂停。用户可直接点击“恢复会商”继续，或在下方输入修改意见后提交；不会新增校验卡片。
+                </p>
+              </div>
+              <Switch
+                checked={seat.human_validation ?? false}
+                onCheckedChange={onHumanValidationChange}
+                aria-label={`切换 ${seat.name || seat.agent_id} 的人工校验`}
+              />
+            </div>
+          </DropdownMenuContent>
+        </DropdownMenu>
         <button
           type="button"
           onClick={onDetail}

frontend-web/src/roundtable-planning/pages/RoundtablePlanningPage.tsx

@@ -409,6 +409,10 @@ export default function RoundtablePlanningPage({
   // Step 2 每席位「技能识别强化」开关映射 {agentId: bool}：由所选业务链条里**每个席位**的同名
   // 配置决定（recommend 无链条 → 空 {}）。透传给每个席位 run，与各席位智能体自身的开关取 OR。
   const [seatSkillDirectives, setSeatSkillDirectives] = useState<Record<string, boolean>>({});
+  // Per-seat human-validation checkpoints from the selected business chain.
+  // A checkpoint pauses Step 2 after the configured seat/stage completes and
+  // reuses the existing resume button plus bottom intervention composer.
+  const [humanValidations, setHumanValidations] = useState<Record<string, boolean>>({});
   // Step 2 每席位「推理深度覆盖」映射 {agentId: SeatMode|null}：由所选业务链条里**每个席位**单独配
   // 的推理深度决定（null/未配 → 跟随链条级 seatMode）。透传给席位 run（覆盖优先、否则跟随 seatMode）。
   // 「卡顿提速」用：把次要席位降到 flash 即可大幅缩短第二步耗时。
@@ -573,6 +577,7 @@ export default function RoundtablePlanningPage({
     selectedModel,
     selectedMode: seatMode,
     seatSkillDirectives,
+    humanValidations,
     seatModes,
     gatherFirst,
     orchestrationMode,
@@ -1058,6 +1063,9 @@ export default function RoundtablePlanningPage({
       setSeatSkillDirectives(
         Object.fromEntries(result.agents.map((a) => [a.agent_id, a.seat_skill_directive ?? false])),
       );
+      setHumanValidations(
+        Object.fromEntries(result.agents.map((a) => [a.agent_id, a.human_validation ?? false])),
+      );
       // 每席位推理深度覆盖：取所选业务链条里**每席位**单独配的 seatMode → {agentId: SeatMode|null}
       // 映射（recommend / 未配 → null，跟随链条级 seatMode）。
       setSeatModes(

frontend-web/src/strategy-components/api/llmwiki.ts

@@ -0,0 +1,719 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+import { apiFetch } from "@/core/api/fetch-client";
+import { useLiveAccount } from "@/core/auth/use-live-account";
+import { getBackendBaseURL } from "@/core/config";
+
+const API = () => `${getBackendBaseURL()}/api/llmwiki`;
+const SETTINGS_API = () => `${getBackendBaseURL()}/api/system-settings/llmwiki`;
+
+export type LlmWikiProvider = "legacy" | "weknora";
+export type LlmWikiScope = "personal" | "public" | "all";
+
+export interface LlmWikiRuntime {
+  provider: LlmWikiProvider;
+  api_base_url: string;
+  web_base_url: string;
+  override_enabled: boolean;
+}
+
+export interface LlmWikiSettings extends LlmWikiRuntime {
+  file_api_base_url: string;
+  file_web_base_url: string;
+  effective_provider: LlmWikiProvider;
+}
+
+export interface LlmWikiKnowledgeBase {
+  id: string;
+  remote_status: "available" | "missing";
+  name: string;
+  description: string;
+  type: "document" | "faq";
+  publication_status: "private" | "pending" | "published" | "rejected";
+  owner_user_id?: string | null;
+  is_owner: boolean;
+  can_write: boolean;
+  knowledge_count: number;
+  chunk_count: number;
+  processing_count: number;
+  embedding_model_id?: string | null;
+  vector_store_id?: string | null;
+  vector_store_name?: string | null;
+  vector_store_source?: string | null;
+  vector_store_engine_type?: string | null;
+  vector_store_status?: string | null;
+  chunking_config?: Record<string, unknown>;
+  indexing_strategy?: Record<string, boolean>;
+  capabilities?: Record<string, boolean>;
+  extract_config?: Record<string, unknown>;
+  wiki_config?: Record<string, unknown>;
+  question_generation_config?: Record<string, unknown>;
+  summary_model_id?: string | null;
+  storage_provider?: string | null;
+  created_at?: string | null;
+  updated_at?: string | null;
+  published_at?: string | null;
+  is_conversation_deposit?: boolean;
+}
+
+export interface LlmWikiDocument {
+  id: string;
+  type?: string;
+  title?: string;
+  description?: string;
+  source?: string;
+  channel?: string;
+  file_name?: string;
+  file_type?: string;
+  file_size?: number;
+  storage_size?: number;
+  parse_status?: string;
+  pending_subtasks_count?: number;
+  summary_status?: string;
+  enable_status?: string;
+  embedding_model_id?: string;
+  created_at?: string;
+  updated_at?: string;
+  processed_at?: string;
+  error_message?: string;
+}
+
+export interface LlmWikiChunk {
+  id: string;
+  content: string;
+  chunk_index: number;
+  is_enabled: boolean;
+  status?: number | string | null;
+  start_at: number;
+  end_at: number;
+  chunk_type: string;
+  parent_chunk_id?: string;
+  relation_chunk_ids: string[];
+  indirect_relation_chunk_ids: string[];
+  metadata: Record<string, unknown>;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface LlmWikiChunkPage {
+  items: LlmWikiChunk[];
+  total: number;
+  page: number;
+  page_size: number;
+}
+
+export interface LlmWikiGraph {
+  nodes: Array<{ id: string; title: string; type: string; link_count: number }>;
+  edges: Array<{ source: string; target: string }>;
+  meta: {
+    mode?: string;
+    total?: number;
+    returned?: number;
+    truncated?: boolean;
+  };
+}
+
+export interface LlmWikiWikiPage {
+  id: string;
+  slug: string;
+  title: string;
+  page_type: string;
+  status: string;
+  content: string;
+  summary: string;
+  aliases: string[];
+  parent_slug?: string;
+  category_path?: string[];
+  depth?: number;
+  source_refs: string[];
+  in_links: string[];
+  out_links: string[];
+  version: number;
+  created_at?: string;
+  updated_at?: string;
+}
+
+export interface LlmWikiWikiPageList {
+  pages: LlmWikiWikiPage[];
+  total: number;
+  page: number;
+  page_size: number;
+  total_pages: number;
+}
+
+export interface LlmWikiSearchResult {
+  chunk_id: string;
+  content: string;
+  knowledge_id: string;
+  knowledge_base_id: string;
+  knowledge_base_name: string;
+  title: string;
+  filename: string;
+  score: number;
+  chunk_index: number;
+  url: string;
+}
+
+export interface LlmWikiWeKnoraEmbedSession {
+  frame_path: string;
+  expires_in: number;
+}
+
+async function readJson<T>(response: Response, context: string): Promise<T> {
+  if (!response.ok) {
+    const payload = await response.json().catch(() => null as unknown);
+    const detail =
+      payload && typeof payload === "object" && "detail" in payload
+        ? String((payload as { detail: unknown }).detail)
+        : `${context}失败（${response.status}）`;
+    throw new Error(detail);
+  }
+  if (response.status === 204) return undefined as T;
+  return (await response.json()) as T;
+}
+
+export async function getLlmWikiRuntime(): Promise<LlmWikiRuntime> {
+  return readJson(
+    await apiFetch(`${API()}/runtime`),
+    "读取 LLMWiki 运行模式",
+  );
+}
+
+export async function listLlmWikiKnowledgeBases(
+  scope: LlmWikiScope,
+): Promise<LlmWikiKnowledgeBase[]> {
+  const response = await apiFetch(
+    `${API()}/knowledge-bases?scope=${encodeURIComponent(scope)}`,
+  );
+  const payload = await readJson<{ knowledge_bases: LlmWikiKnowledgeBase[] }>(
+    response,
+    "读取知识库",
+  );
+  return payload.knowledge_bases ?? [];
+}
+
+export async function listAgentLlmWikiKnowledgeBases(
+  agentId: string,
+): Promise<LlmWikiKnowledgeBase[]> {
+  const payload = await readJson<{ knowledge_bases: LlmWikiKnowledgeBase[] }>(
+    await apiFetch(
+      `${API()}/agents/${encodeURIComponent(agentId)}/knowledge-bases`,
+    ),
+    "读取智能体知识库",
+  );
+  return payload.knowledge_bases ?? [];
+}
+
+export async function getLlmWikiKnowledgeBase(
+  id: string,
+): Promise<LlmWikiKnowledgeBase> {
+  return readJson(
+    await apiFetch(`${API()}/knowledge-bases/${encodeURIComponent(id)}`),
+    "读取知识库详情",
+  );
+}
+
+export async function createLlmWikiWeKnoraEmbedSession(
+  id: string,
+  tab: "documents" | "wiki" | "graph",
+): Promise<LlmWikiWeKnoraEmbedSession> {
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(id)}/weknora/session?tab=${encodeURIComponent(tab)}`,
+      { method: "POST" },
+    ),
+    "创建 WeKnora 详情会话",
+  );
+}
+
+export async function createLlmWikiKnowledgeBase(input: {
+  name: string;
+  description: string;
+  type: "document" | "faq";
+  wiki_enabled?: boolean;
+}): Promise<LlmWikiKnowledgeBase> {
+  return readJson(
+    await apiFetch(`${API()}/knowledge-bases`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    "创建知识库",
+  );
+}
+
+export async function updateLlmWikiKnowledgeBase(
+  id: string,
+  input: { name?: string; description?: string },
+): Promise<LlmWikiKnowledgeBase> {
+  return readJson(
+    await apiFetch(`${API()}/knowledge-bases/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    "更新知识库",
+  );
+}
+
+export async function deleteLlmWikiKnowledgeBase(id: string): Promise<void> {
+  await readJson<void>(
+    await apiFetch(`${API()}/knowledge-bases/${encodeURIComponent(id)}`, {
+      method: "DELETE",
+    }),
+    "删除知识库",
+  );
+}
+
+export async function listLlmWikiDocuments(
+  knowledgeBaseId: string,
+): Promise<LlmWikiDocument[]> {
+  const payload = await readJson<{ items: LlmWikiDocument[] }>(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`,
+    ),
+    "读取文档",
+  );
+  return payload.items ?? [];
+}
+
+export async function getLlmWikiDocument(
+  knowledgeBaseId: string,
+  documentId: string,
+): Promise<LlmWikiDocument> {
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/${encodeURIComponent(documentId)}`,
+    ),
+    "读取文档详情",
+  );
+}
+
+export async function listLlmWikiDocumentChunks(
+  knowledgeBaseId: string,
+  documentId: string,
+  page: number,
+  pageSize: number,
+): Promise<LlmWikiChunkPage> {
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/${encodeURIComponent(documentId)}/chunks?page=${page}&page_size=${pageSize}`,
+    ),
+    "读取文档索引",
+  );
+}
+
+export async function getLlmWikiDocumentPreview(
+  knowledgeBaseId: string,
+  documentId: string,
+): Promise<Blob> {
+  const response = await apiFetch(
+    `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/${encodeURIComponent(documentId)}/preview`,
+  );
+  if (!response.ok) {
+    await readJson<void>(response, "读取文档原件");
+    throw new Error("读取文档原件失败");
+  }
+  return response.blob();
+}
+
+export async function getLlmWikiGraph(knowledgeBaseId: string): Promise<LlmWikiGraph> {
+  return readJson(
+    await apiFetch(`${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/graph?limit=200`),
+    "读取知识图谱",
+  );
+}
+
+export async function listLlmWikiWikiPages(
+  knowledgeBaseId: string,
+  page: number,
+  pageSize: number,
+  query = "",
+): Promise<LlmWikiWikiPageList> {
+  const params = new URLSearchParams({ page: String(page), page_size: String(pageSize) });
+  if (query.trim()) params.set("query", query.trim());
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/wiki/pages?${params.toString()}`,
+    ),
+    "读取 Wiki 页面",
+  );
+}
+
+export async function getLlmWikiWikiPage(
+  knowledgeBaseId: string,
+  slug: string,
+): Promise<LlmWikiWikiPage> {
+  const safeSlug = slug.split("/").map(encodeURIComponent).join("/");
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/wiki/pages/${safeSlug}`,
+    ),
+    "读取 Wiki 页面详情",
+  );
+}
+
+export async function uploadLlmWikiDocument(
+  knowledgeBaseId: string,
+  file: File,
+): Promise<LlmWikiDocument> {
+  const form = new FormData();
+  form.append("file", file);
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`,
+      { method: "POST", body: form },
+    ),
+    "上传文档",
+  );
+}
+
+export async function importLlmWikiDocumentUrl(
+  knowledgeBaseId: string,
+  url: string,
+): Promise<LlmWikiDocument> {
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/url`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ url }),
+      },
+    ),
+    "导入网页",
+  );
+}
+
+export async function createManualLlmWikiDocument(
+  knowledgeBaseId: string,
+  input: { title: string; content: string },
+): Promise<LlmWikiDocument> {
+  return readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/manual`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input),
+      },
+    ),
+    "创建 Wiki 内容",
+  );
+}
+
+export async function deleteLlmWikiDocument(
+  knowledgeBaseId: string,
+  documentId: string,
+): Promise<void> {
+  await readJson<void>(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/${encodeURIComponent(documentId)}`,
+      { method: "DELETE" },
+    ),
+    "删除文档",
+  );
+}
+
+export async function reprocessLlmWikiDocument(
+  knowledgeBaseId: string,
+  documentId: string,
+): Promise<void> {
+  await readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents/${encodeURIComponent(documentId)}/reprocess`,
+      { method: "POST" },
+    ),
+    "重新解析文档",
+  );
+}
+
+export async function setLlmWikiPublication(
+  knowledgeBaseId: string,
+  publish: boolean,
+): Promise<void> {
+  await readJson(
+    await apiFetch(
+      `${API()}/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/${publish ? "publish" : "unpublish"}`,
+      { method: "POST" },
+    ),
+    publish ? "发布知识库" : "取消发布",
+  );
+}
+
+export async function searchLlmWiki(input: {
+  query: string;
+  scope: LlmWikiScope;
+  knowledge_base_ids?: string[];
+}): Promise<LlmWikiSearchResult[]> {
+  const payload = await readJson<{ results: LlmWikiSearchResult[] }>(
+    await apiFetch(`${API()}/search`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    "检索知识库",
+  );
+  return payload.results ?? [];
+}
+
+export async function createLlmWikiConversationDeposit(input: {
+  thread_id: string;
+  question: string;
+  answer: string;
+  human_message_id?: string | null;
+  assistant_message_id: string;
+  assistant_id?: string | null;
+  knowledge_base_ids?: string[];
+}): Promise<{ queued: boolean; provider: LlmWikiProvider }> {
+  return readJson(
+    await apiFetch(`${API()}/conversation-deposits/turn`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    "写入对话沉淀",
+  );
+}
+
+export async function getLlmWikiSettings(): Promise<LlmWikiSettings> {
+  return readJson(await apiFetch(SETTINGS_API()), "读取 WeKnora 连接配置");
+}
+
+export async function saveLlmWikiSettings(input: {
+  override_enabled: boolean;
+  api_base_url: string;
+  web_base_url: string;
+}): Promise<LlmWikiRuntime> {
+  return readJson(
+    await apiFetch(SETTINGS_API(), {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+    }),
+    "保存 WeKnora 连接配置",
+  );
+}
+
+export async function resetLlmWikiSettings(): Promise<LlmWikiRuntime> {
+  return readJson(
+    await apiFetch(`${SETTINGS_API()}/override`, { method: "DELETE" }),
+    "恢复配置文件设置",
+  );
+}
+
+export async function testLlmWikiConnection(
+  apiBaseUrl: string,
+): Promise<void> {
+  await readJson(
+    await apiFetch(`${SETTINGS_API()}/test`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ api_base_url: apiBaseUrl }),
+    }),
+    "测试 WeKnora 连接",
+  );
+}
+
+const runtimeKey = ["llmwiki", "runtime"] as const;
+const settingsKey = ["llmwiki", "settings"] as const;
+const knowledgeBasesKey = (userId: string | null, scope: LlmWikiScope) =>
+  ["llmwiki", "knowledge-bases", userId ?? "anonymous", scope] as const;
+
+export function useLlmWikiRuntime() {
+  return useQuery({
+    queryKey: runtimeKey,
+    queryFn: getLlmWikiRuntime,
+    staleTime: 30_000,
+    retry: 1,
+  });
+}
+
+export function useLlmWikiKnowledgeBases(
+  scope: LlmWikiScope,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: knowledgeBasesKey(userId, scope),
+    queryFn: () => listLlmWikiKnowledgeBases(scope),
+    enabled,
+    refetchInterval: 15_000,
+  });
+}
+
+export function useAgentLlmWikiKnowledgeBases(
+  agentId: string | null | undefined,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "agents", agentId, "knowledge-bases", userId ?? "anonymous"],
+    queryFn: () => listAgentLlmWikiKnowledgeBases(agentId!),
+    enabled: enabled && !!agentId,
+  });
+}
+
+export function useLlmWikiKnowledgeBase(
+  knowledgeBaseId: string | null,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "knowledge-base", knowledgeBaseId, userId ?? "anonymous"],
+    queryFn: () => getLlmWikiKnowledgeBase(knowledgeBaseId!),
+    enabled: enabled && !!knowledgeBaseId,
+    refetchInterval: 8_000,
+  });
+}
+
+export function useLlmWikiDocuments(
+  knowledgeBaseId: string | null,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "documents", knowledgeBaseId, userId ?? "anonymous"],
+    queryFn: () => listLlmWikiDocuments(knowledgeBaseId!),
+    enabled: enabled && !!knowledgeBaseId,
+    refetchInterval: 8_000,
+  });
+}
+
+export function useLlmWikiDocument(
+  knowledgeBaseId: string | null,
+  documentId: string | null,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "document", knowledgeBaseId, documentId, userId ?? "anonymous"],
+    queryFn: () => getLlmWikiDocument(knowledgeBaseId!, documentId!),
+    enabled: enabled && !!knowledgeBaseId && !!documentId,
+  });
+}
+
+export function useLlmWikiDocumentChunks(
+  knowledgeBaseId: string | null,
+  documentId: string | null,
+  page: number,
+  pageSize = 20,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "document-chunks", knowledgeBaseId, documentId, page, pageSize, userId ?? "anonymous"],
+    queryFn: () => listLlmWikiDocumentChunks(knowledgeBaseId!, documentId!, page, pageSize),
+    enabled: enabled && !!knowledgeBaseId && !!documentId,
+  });
+}
+
+export function useLlmWikiGraph(knowledgeBaseId: string | null, enabled = true) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "graph", knowledgeBaseId, userId ?? "anonymous"],
+    queryFn: () => getLlmWikiGraph(knowledgeBaseId!),
+    enabled: enabled && !!knowledgeBaseId,
+  });
+}
+
+export function useLlmWikiWikiPages(
+  knowledgeBaseId: string | null,
+  page: number,
+  pageSize = 50,
+  query = "",
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "wiki-pages", knowledgeBaseId, page, pageSize, query, userId ?? "anonymous"],
+    queryFn: () => listLlmWikiWikiPages(knowledgeBaseId!, page, pageSize, query),
+    enabled: enabled && !!knowledgeBaseId,
+    refetchInterval: 10_000,
+  });
+}
+
+export function useLlmWikiWikiPage(
+  knowledgeBaseId: string | null,
+  slug: string | null,
+  enabled = true,
+) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: ["llmwiki", "wiki-page", knowledgeBaseId, slug, userId ?? "anonymous"],
+    queryFn: () => getLlmWikiWikiPage(knowledgeBaseId!, slug!),
+    enabled: enabled && !!knowledgeBaseId && !!slug,
+  });
+}
+
+export function useLlmWikiSettings(enabled = true) {
+  const { userId } = useLiveAccount();
+  return useQuery({
+    queryKey: [...settingsKey, userId ?? "anonymous"],
+    queryFn: getLlmWikiSettings,
+    enabled,
+  });
+}
+
+export function useLlmWikiActions() {
+  const queryClient = useQueryClient();
+  const invalidateKnowledge = () =>
+    queryClient.invalidateQueries({ queryKey: ["llmwiki"] });
+  return {
+    create: useMutation({
+      mutationFn: createLlmWikiKnowledgeBase,
+      onSuccess: invalidateKnowledge,
+    }),
+    update: useMutation({
+      mutationFn: ({ id, ...input }: { id: string; name?: string; description?: string }) =>
+        updateLlmWikiKnowledgeBase(id, input),
+      onSuccess: invalidateKnowledge,
+    }),
+    remove: useMutation({
+      mutationFn: deleteLlmWikiKnowledgeBase,
+      onSuccess: invalidateKnowledge,
+    }),
+    upload: useMutation({
+      mutationFn: ({ id, file }: { id: string; file: File }) =>
+        uploadLlmWikiDocument(id, file),
+      onSuccess: invalidateKnowledge,
+    }),
+    importUrl: useMutation({
+      mutationFn: ({ id, url }: { id: string; url: string }) =>
+        importLlmWikiDocumentUrl(id, url),
+      onSuccess: invalidateKnowledge,
+    }),
+    createManual: useMutation({
+      mutationFn: ({ id, title, content }: { id: string; title: string; content: string }) =>
+        createManualLlmWikiDocument(id, { title, content }),
+      onSuccess: invalidateKnowledge,
+    }),
+    removeDocument: useMutation({
+      mutationFn: ({ id, documentId }: { id: string; documentId: string }) =>
+        deleteLlmWikiDocument(id, documentId),
+      onSuccess: invalidateKnowledge,
+    }),
+    reprocessDocument: useMutation({
+      mutationFn: ({ id, documentId }: { id: string; documentId: string }) =>
+        reprocessLlmWikiDocument(id, documentId),
+      onSuccess: invalidateKnowledge,
+    }),
+    publication: useMutation({
+      mutationFn: ({ id, publish }: { id: string; publish: boolean }) =>
+        setLlmWikiPublication(id, publish),
+      onSuccess: invalidateKnowledge,
+    }),
+  };
+}
+
+export function useLlmWikiSettingsActions() {
+  const queryClient = useQueryClient();
+  const invalidate = async () => {
+    await queryClient.invalidateQueries({ queryKey: ["llmwiki"] });
+  };
+  return {
+    save: useMutation({ mutationFn: saveLlmWikiSettings, onSuccess: invalidate }),
+    reset: useMutation({ mutationFn: resetLlmWikiSettings, onSuccess: invalidate }),
+    test: useMutation({ mutationFn: testLlmWikiConnection }),
+  };
+}

frontend-web/src/strategy-components/components/resource-management/llmwiki/WeKnoraKnowledgeDetailPage.tsx

@@ -0,0 +1,260 @@
+import { AlertCircle, Loader2, RefreshCw, Upload } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { Navigate, useNavigate, useParams } from "react-router-dom";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { getBackendBaseURL } from "@/core/config";
+import {
+  createLlmWikiWeKnoraEmbedSession,
+  useLlmWikiActions,
+  useLlmWikiKnowledgeBase,
+  useLlmWikiRuntime,
+} from "@/strategy-components/api/llmwiki";
+
+const LIST_PATH = "/page/workspace/knowledge";
+
+type DeerFlowThemePayload = {
+  type: "deerflow-weknora-theme";
+  theme: "dark" | "light";
+  vars: Record<string, string>;
+};
+
+function cssVar(name: string, fallback = ""): string {
+  if (typeof window === "undefined") return fallback;
+  return getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
+}
+
+function collectThemePayload(): DeerFlowThemePayload {
+  const isDark =
+    document.documentElement.classList.contains("dark") ||
+    document.documentElement.getAttribute("theme-mode") === "dark";
+  return {
+    type: "deerflow-weknora-theme",
+    theme: isDark ? "dark" : "light",
+    vars: {
+      primary: cssVar("--primary", isDark ? "#2b81ff" : "#0062d9"),
+      primaryForeground: cssVar("--button-foreground", cssVar("--primary-foreground", "#ffffff")),
+      background: cssVar("--background", isDark ? "#0e172b" : "#ffffff"),
+      foreground: cssVar("--foreground", isDark ? "#eff2f5" : "#202a3a"),
+      card: cssVar("--card", isDark ? "#1a2539" : "#ffffff"),
+      cardForeground: cssVar("--card-foreground", cssVar("--foreground", isDark ? "#eff2f5" : "#202a3a")),
+      muted: cssVar("--muted", isDark ? "#232e40" : "#f3f5f8"),
+      mutedForeground: cssVar("--muted-foreground", isDark ? "#8e9aa4" : "#7f7f7f"),
+      border: cssVar("--border", isDark ? "rgba(255,255,255,0.12)" : "#dbdbdb"),
+      popover: cssVar("--popover", cssVar("--card", isDark ? "#1a2539" : "#ffffff")),
+      destructive: cssVar("--destructive", "#d54941"),
+    },
+  };
+}
+
+function postThemeToFrame(frame: HTMLIFrameElement | null) {
+  if (!frame?.contentWindow) return;
+  const src = frame.getAttribute("src") || "";
+  const targetOrigin = new URL(src, window.location.href).origin;
+  frame.contentWindow.postMessage(collectThemePayload(), targetOrigin);
+}
+
+export function WeKnoraKnowledgeDetailPage() {
+  const {
+    knowledge_base_id: strategyKnowledgeBaseId,
+    noteId: workspaceKnowledgeBaseId,
+  } = useParams();
+  const knowledgeBaseId = strategyKnowledgeBaseId ?? workspaceKnowledgeBaseId ?? "";
+  const navigate = useNavigate();
+  const frameRef = useRef<HTMLIFrameElement>(null);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [frameSrc, setFrameSrc] = useState("");
+  const [frameError, setFrameError] = useState<string | null>(null);
+  const [uploading, setUploading] = useState(false);
+  const runtime = useLlmWikiRuntime();
+  const details = useLlmWikiKnowledgeBase(knowledgeBaseId || null, !!knowledgeBaseId);
+  const actions = useLlmWikiActions();
+
+  const detailsReady = !!details.data;
+  const preferredTab = details.data?.indexing_strategy?.wiki_enabled ? "wiki" : "documents";
+
+  useEffect(() => {
+    let cancelled = false;
+    setFrameSrc("");
+    setFrameError(null);
+    if (!knowledgeBaseId || runtime.data?.provider !== "weknora" || !detailsReady) {
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    void createLlmWikiWeKnoraEmbedSession(knowledgeBaseId, preferredTab)
+      .then((session) => {
+        if (cancelled) return;
+        const base = getBackendBaseURL().replace(/\/+$/, "");
+        const path = session.frame_path.startsWith("/")
+          ? session.frame_path
+          : `/${session.frame_path}`;
+        const nextUrl = new URL(`${base}${path}`);
+        nextUrl.searchParams.set("theme", collectThemePayload().theme);
+        setFrameSrc(nextUrl.toString());
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        const message = error instanceof Error ? error.message : "创建 WeKnora 详情会话失败";
+        setFrameError(message);
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [detailsReady, knowledgeBaseId, preferredTab, runtime.data?.provider]);
+
+  useEffect(() => {
+    if (!frameSrc) return;
+    const frame = frameRef.current;
+    const send = () => postThemeToFrame(frame);
+    const timer = window.setTimeout(send, 300);
+    const observer = new MutationObserver(send);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["class", "style", "data-theme", "theme-mode"],
+    });
+    window.addEventListener("storage", send);
+    return () => {
+      window.clearTimeout(timer);
+      observer.disconnect();
+      window.removeEventListener("storage", send);
+    };
+  }, [frameSrc]);
+
+  if (runtime.isLoading || details.isLoading) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
+        <Loader2 className="mr-2 size-5 animate-spin" />
+        加载中
+      </div>
+    );
+  }
+
+  if (runtime.data?.provider !== "weknora") return <Navigate to={LIST_PATH} replace />;
+
+  if (frameError) {
+    return (
+      <div className="flex h-full flex-col items-center justify-center gap-4 bg-background px-6 text-center">
+        <div className="flex size-12 items-center justify-center rounded-full bg-destructive/10 text-destructive">
+          <AlertCircle className="size-6" />
+        </div>
+        <div>
+          <div className="text-base font-semibold text-foreground">无法打开 WeKnora 详情</div>
+          <p className="mt-2 text-sm text-muted-foreground">{frameError}</p>
+        </div>
+        <Button variant="outline" onClick={() => navigate(LIST_PATH)}>
+          返回知识库
+        </Button>
+      </div>
+    );
+  }
+
+  if (details.error || !details.data) {
+    return (
+      <div className="flex h-full flex-col items-center justify-center gap-4 bg-background px-6 text-center">
+        <div className="flex size-12 items-center justify-center rounded-full bg-destructive/10 text-destructive">
+          <AlertCircle className="size-6" />
+        </div>
+        <div>
+          <div className="text-base font-semibold text-foreground">无法打开知识库详情</div>
+          <p className="mt-2 text-sm text-muted-foreground">
+            当前账号没有访问权限，或 WeKnora 资源已不存在。
+          </p>
+        </div>
+        <Button variant="outline" onClick={() => navigate(LIST_PATH)}>
+          返回知识库
+        </Button>
+      </div>
+    );
+  }
+
+  const canUpload = details.data.can_write && !details.data.is_conversation_deposit;
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      {canUpload && (
+        <div className="flex h-12 shrink-0 items-center justify-end border-b px-4">
+          <input
+            ref={fileInputRef}
+            type="file"
+            multiple
+            className="hidden"
+            onChange={(event) => {
+              const files = Array.from(event.currentTarget.files ?? []);
+              event.currentTarget.value = "";
+              if (files.length === 0) return;
+              void (async () => {
+                setUploading(true);
+                const failed: string[] = [];
+                try {
+                  for (const file of files) {
+                    try {
+                      await actions.upload.mutateAsync({ id: knowledgeBaseId, file });
+                    } catch {
+                      failed.push(file.name);
+                    }
+                  }
+                  const succeeded = files.length - failed.length;
+                  if (succeeded > 0) {
+                    await details.refetch();
+                    if (frameRef.current) frameRef.current.src = frameSrc;
+                  }
+                  if (failed.length === 0) {
+                    toast.success(`已上传 ${succeeded} 个文件，正在处理`);
+                  } else if (succeeded > 0) {
+                    toast.warning(`上传完成：成功 ${succeeded} 个，失败 ${failed.length} 个`);
+                  } else {
+                    toast.error("文件上传失败");
+                  }
+                } finally {
+                  setUploading(false);
+                }
+              })();
+            }}
+          />
+          <Button
+            size="sm"
+            onClick={() => fileInputRef.current?.click()}
+            disabled={uploading}
+          >
+            {uploading ? (
+              <Loader2 className="mr-2 size-4 animate-spin" />
+            ) : (
+              <Upload className="mr-2 size-4" />
+            )}
+            上传文件
+          </Button>
+        </div>
+      )}
+      {frameSrc && (
+        <iframe
+          key={frameSrc}
+          ref={frameRef}
+          title={`${details.data.name || "WeKnora"} 详情`}
+          src={frameSrc}
+          className="h-full min-h-0 w-full flex-1 border-0 bg-background"
+          sandbox="allow-same-origin allow-scripts allow-forms allow-downloads allow-popups"
+          referrerPolicy="no-referrer"
+          onLoad={() => postThemeToFrame(frameRef.current)}
+        />
+      )}
+      {!frameSrc && (
+        <div className="flex min-h-0 flex-1 items-center justify-center bg-background text-sm text-muted-foreground">
+          <Loader2 className="mr-2 size-5 animate-spin" />
+          加载中
+        </div>
+      )}
+      {details.isFetching && (
+        <div className="pointer-events-none fixed bottom-4 right-4 rounded-full border bg-card px-3 py-2 text-xs text-muted-foreground shadow-sm">
+          <RefreshCw className="mr-2 inline size-3 animate-spin" />
+          同步知识库状态
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default WeKnoraKnowledgeDetailPage;

frontend-web/src/strategy-components/components/resource-management/llmwiki/WeKnoraKnowledgeWorkspace.tsx

@@ -0,0 +1,318 @@
+import {
+  BookOpen,
+  Database,
+  FileText,
+  Globe2,
+  Loader2,
+  Plus,
+  RefreshCw,
+  Search,
+  Settings2,
+  Trash2,
+} from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { useNavigate } from "react-router-dom";
+import { toast } from "sonner";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { Textarea } from "@/components/ui/textarea";
+import { getStoredAuth } from "@/core/auth";
+import {
+  type LlmWikiKnowledgeBase,
+  type LlmWikiScope,
+  searchLlmWiki,
+  useLlmWikiActions,
+  useLlmWikiKnowledgeBases,
+  useLlmWikiSettings,
+  useLlmWikiSettingsActions,
+} from "@/strategy-components/api/llmwiki";
+
+type WorkspaceTab = "personal" | "public" | "settings";
+const LIST_PATH = "/page/workspace/knowledge";
+
+const publicationLabels: Record<string, string> = {
+  private: "仅自己",
+  pending: "仅自己",
+  published: "已公开",
+  rejected: "仅自己",
+};
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : "操作失败，请稍后重试";
+}
+
+export function WeKnoraKnowledgeWorkspace() {
+  const navigate = useNavigate();
+  const isAdmin = getStoredAuth()?.system_role === "admin";
+  const [tab, setTab] = useState<WorkspaceTab>("personal");
+  const scope: LlmWikiScope = tab === "public" ? "public" : "personal";
+  const knowledge = useLlmWikiKnowledgeBases(scope, tab !== "settings");
+  const actions = useLlmWikiActions();
+  const [createOpen, setCreateOpen] = useState(false);
+  const [searchText, setSearchText] = useState("");
+  const [searching, setSearching] = useState(false);
+  const [searchResults, setSearchResults] = useState<Array<{
+    chunk_id: string;
+    title: string;
+    content: string;
+    score: number;
+    knowledge_base_name: string;
+  }>>([]);
+
+  useEffect(() => setSearchResults([]), [tab]);
+
+  const busy = actions.create.isPending || actions.remove.isPending || actions.publication.isPending;
+  const openDetails = (item: LlmWikiKnowledgeBase) => {
+    if (item.remote_status === "missing") {
+      toast.error("该知识库已从 WeKnora 删除，只能清理当前记录");
+      return;
+    }
+    navigate(`${LIST_PATH}/${encodeURIComponent(item.id)}`);
+  };
+
+  const runSearch = async () => {
+    const query = searchText.trim();
+    if (!query) return;
+    setSearching(true);
+    try {
+      setSearchResults(await searchLlmWiki({ query, scope }));
+    } catch (error) {
+      toast.error(messageOf(error));
+    } finally {
+      setSearching(false);
+    }
+  };
+
+  const removeKnowledgeBase = async (item: LlmWikiKnowledgeBase) => {
+    const warning = item.remote_status === "missing"
+      ? `知识库“${item.name}”已不在 WeKnora 中。确定清理 cmzs 中的这条失效记录吗？`
+      : `确定删除知识库“${item.name}”吗？WeKnora 中的文档和索引也会删除。`;
+    if (!window.confirm(warning)) return;
+    try {
+      await actions.remove.mutateAsync(item.id);
+      toast.success("知识库已删除");
+    } catch (error) {
+      toast.error(messageOf(error));
+    }
+  };
+
+  const togglePublication = async (item: LlmWikiKnowledgeBase) => {
+    const publish = item.publication_status !== "published";
+    try {
+      await actions.publication.mutateAsync({ id: item.id, publish });
+      toast.success(publish ? "知识库已发布到公共 LLMWiki" : "知识库已取消公开");
+    } catch (error) {
+      toast.error(messageOf(error));
+    }
+  };
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      <div className="border-b bg-gradient-to-r from-primary/8 via-card to-card px-6 py-5">
+        <div className="mx-auto flex max-w-[1500px] flex-wrap items-center justify-between gap-4">
+          <div>
+            <div className="flex items-center gap-2">
+              <Database className="size-5 text-primary" />
+              <h1 className="text-xl font-semibold">问答梳理</h1>
+              <Badge variant="secondary">WeKnora</Badge>
+            </div>
+            <p className="mt-1 text-sm text-muted-foreground">由 WeKnora 负责解析与检索，用户、权限和发布范围由 cmzs 管理。</p>
+          </div>
+          <div className="flex items-center gap-2 rounded-full border bg-background/80 p-1 shadow-sm backdrop-blur">
+            {tab !== "settings" && (
+              <Button variant="ghost" size="sm" className="rounded-full" onClick={() => knowledge.refetch()} disabled={knowledge.isFetching}>
+                <RefreshCw className={`mr-2 size-4 ${knowledge.isFetching ? "animate-spin" : ""}`} />刷新
+              </Button>
+            )}
+            {tab === "personal" && <Button size="sm" className="rounded-full px-4 shadow-sm" onClick={() => setCreateOpen(true)}><Plus className="mr-2 size-4" />新建知识库</Button>}
+          </div>
+        </div>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-auto px-6 py-5">
+        <div className="mx-auto max-w-[1500px]">
+          <Tabs value={tab} onValueChange={(value) => setTab(value as WorkspaceTab)}>
+            <div className="flex flex-wrap items-center justify-between gap-3 rounded-2xl border bg-card/80 p-3 shadow-sm">
+              <TabsList className="rounded-xl bg-muted/70">
+                <TabsTrigger value="personal"><BookOpen className="mr-2 size-4" />我的知识库</TabsTrigger>
+                <TabsTrigger value="public"><Globe2 className="mr-2 size-4" />公共 LLMWiki</TabsTrigger>
+                {isAdmin && <TabsTrigger value="settings"><Settings2 className="mr-2 size-4" />连接配置</TabsTrigger>}
+              </TabsList>
+              {tab !== "settings" && (
+                <div className="flex w-full max-w-xl items-center gap-2 rounded-xl border bg-background/80 p-1 shadow-sm sm:w-auto">
+                  <div className="relative min-w-0 flex-1 sm:w-80">
+                    <Search className="absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+                    <Input value={searchText} onChange={(event) => setSearchText(event.target.value)} onKeyDown={(event) => event.key === "Enter" && void runSearch()} placeholder={tab === "public" ? "检索公共知识" : "检索我的知识"} className="border-0 bg-transparent pl-9 shadow-none focus-visible:ring-0" />
+                  </div>
+                  <Button variant="secondary" className="rounded-lg px-4" onClick={() => void runSearch()} disabled={searching || !searchText.trim()}>{searching ? <Loader2 className="size-4 animate-spin" /> : "检索"}</Button>
+                </div>
+              )}
+            </div>
+
+            <TabsContent value="personal" className="mt-5"><KnowledgeGrid rows={knowledge.data ?? []} loading={knowledge.isLoading} error={knowledge.error} emptyText="还没有个人知识库，点击右上角创建。" busy={busy} onOpen={openDetails} onPublish={togglePublication} onDelete={removeKnowledgeBase} /></TabsContent>
+            <TabsContent value="public" className="mt-5"><KnowledgeGrid rows={knowledge.data ?? []} loading={knowledge.isLoading} error={knowledge.error} emptyText="公共 LLMWiki 暂无已发布知识库。" busy={busy} onOpen={openDetails} onPublish={togglePublication} onDelete={removeKnowledgeBase} /></TabsContent>
+            {isAdmin && <TabsContent value="settings" className="mt-5"><ConnectionSettings /></TabsContent>}
+          </Tabs>
+
+          {searchResults.length > 0 && tab !== "settings" && (
+            <Card className="mt-5">
+              <CardHeader className="pb-3"><CardTitle className="text-base">检索结果</CardTitle><CardDescription>结果由 WeKnora 检索返回，问答中使用同一授权链路。</CardDescription></CardHeader>
+              <CardContent className="space-y-3">{searchResults.map((result) => <div key={result.chunk_id} className="rounded-lg border p-3"><div className="flex items-center justify-between gap-3 text-sm font-medium"><span>{result.title || "未命名来源"}</span><Badge variant="outline">{result.knowledge_base_name}</Badge></div><p className="mt-2 line-clamp-3 whitespace-pre-wrap text-sm text-muted-foreground">{result.content}</p></div>)}</CardContent>
+            </Card>
+          )}
+        </div>
+      </div>
+
+      <CreateKnowledgeDialog open={createOpen} pending={actions.create.isPending} onOpenChange={setCreateOpen} onCreate={async (input) => {
+        try {
+          const created = await actions.create.mutateAsync(input);
+          setCreateOpen(false);
+          navigate(`${LIST_PATH}/${encodeURIComponent(created.id)}`);
+          toast.success("知识库已创建");
+        } catch (error) {
+          toast.error(messageOf(error));
+        }
+      }} />
+    </div>
+  );
+}
+
+function KnowledgeGrid({
+  rows,
+  loading,
+  error,
+  emptyText,
+  busy,
+  onOpen,
+  onPublish,
+  onDelete,
+}: {
+  rows: LlmWikiKnowledgeBase[];
+  loading: boolean;
+  error: unknown;
+  emptyText: string;
+  busy: boolean;
+  onOpen: (item: LlmWikiKnowledgeBase) => void;
+  onPublish: (item: LlmWikiKnowledgeBase) => void;
+  onDelete: (item: LlmWikiKnowledgeBase) => void;
+}) {
+  if (loading) return <div className="flex h-64 items-center justify-center text-muted-foreground"><Loader2 className="mr-2 size-5 animate-spin" />正在读取知识库</div>;
+  if (error) return <div className="rounded-lg border border-destructive/30 bg-destructive/5 p-6 text-sm text-destructive">{messageOf(error)}</div>;
+  if (!rows.length) return <div className="flex h-64 items-center justify-center rounded-xl border border-dashed text-sm text-muted-foreground">{emptyText}</div>;
+  return (
+    <div className="grid gap-4 md:grid-cols-2 xl:grid-cols-3">
+      {rows.map((item) => (
+        <Card
+          key={item.id}
+          className={`group overflow-hidden rounded-2xl transition-all hover:-translate-y-0.5 hover:shadow-lg ${
+            item.remote_status === "missing"
+              ? "border-amber-500/40 bg-amber-500/[0.03]"
+              : "border-border/70 bg-card/95 hover:border-primary/30"
+          }`}
+        >
+          <div className={`h-1 ${item.publication_status === "published" ? "bg-primary" : "bg-muted"}`} />
+          <button type="button" disabled={item.remote_status === "missing"} className="w-full text-left outline-none transition-colors enabled:hover:bg-muted/25 focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 disabled:cursor-default" onClick={() => onOpen(item)}>
+            <CardHeader className="pb-3 pt-5">
+              <div className="flex items-start justify-between gap-3">
+                <div className="min-w-0"><CardTitle className="truncate text-base">{item.name}</CardTitle><CardDescription className="mt-1 line-clamp-2 min-h-10">{item.description || "暂无描述"}</CardDescription></div>
+                <div className="flex shrink-0 flex-col items-end gap-1.5">{item.remote_status === "missing" ? <Badge variant="outline" className="border-amber-500/50 text-amber-700 dark:text-amber-300">远端已删除</Badge> : <Badge variant={item.publication_status === "published" ? "default" : "secondary"}>{publicationLabels[item.publication_status] ?? "仅自己"}</Badge>}{item.remote_status !== "missing" && item.indexing_strategy?.wiki_enabled && <Badge className="bg-violet-100 text-violet-700 hover:bg-violet-100 dark:bg-violet-950 dark:text-violet-300">Wiki</Badge>}</div>
+              </div>
+            </CardHeader>
+            <div className="px-6 pb-4"><div className="grid grid-cols-3 gap-2 rounded-xl border bg-muted/35 p-3 text-center text-xs"><div><div className="text-base font-semibold text-foreground">{item.knowledge_count}</div><span className="text-muted-foreground">文档</span></div><div><div className="text-base font-semibold text-foreground">{item.chunk_count}</div><span className="text-muted-foreground">分块</span></div><div><div className="text-base font-semibold text-foreground">{item.processing_count}</div><span className="text-muted-foreground">处理中</span></div></div></div>
+          </button>
+          <CardContent className="border-t bg-muted/20 px-6 py-4">
+            <div className="flex items-center justify-between gap-3">
+              <div className="flex min-w-0 flex-wrap items-center gap-2">
+                {item.remote_status === "missing" ? <span className="text-xs text-muted-foreground">WeKnora 资源不存在，可清理本地记录</span> : <Button size="sm" variant="outline" className="rounded-full" onClick={() => onOpen(item)}><FileText className="mr-2 size-4" />查看详情</Button>}
+                {item.remote_status !== "missing" && item.is_owner && !item.is_conversation_deposit && <Button size="sm" variant="secondary" className="rounded-full" disabled={busy} onClick={() => void onPublish(item)}>{item.publication_status === "published" ? "取消公开" : "发布公共库"}</Button>}
+              </div>
+              {item.can_write && !item.is_conversation_deposit && <Button size="icon" variant="ghost" className="size-8 shrink-0 rounded-full text-destructive hover:bg-destructive/10 hover:text-destructive" aria-label={item.remote_status === "missing" ? `清理失效记录 ${item.name}` : `删除知识库 ${item.name}`} title={item.remote_status === "missing" ? "清理失效记录" : "删除知识库"} disabled={busy} onClick={() => void onDelete(item)}><Trash2 className="size-4" /></Button>}
+            </div>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+function CreateKnowledgeDialog({
+  open,
+  pending,
+  onOpenChange,
+  onCreate,
+}: {
+  open: boolean;
+  pending: boolean;
+  onOpenChange: (value: boolean) => void;
+  onCreate: (input: { name: string; description: string; type: "document" | "faq"; wiki_enabled: boolean }) => Promise<void>;
+}) {
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [wikiEnabled, setWikiEnabled] = useState(true);
+  useEffect(() => {
+    if (!open) { setName(""); setDescription(""); setWikiEnabled(true); }
+  }, [open]);
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader><DialogTitle>新建个人知识库</DialogTitle><DialogDescription>选择知识库模式；模型、切块和存储策略仍由 WeKnora 管理。</DialogDescription></DialogHeader>
+        <div className="space-y-4 py-2">
+          <div className="space-y-2"><label className="text-sm font-medium" htmlFor="llmwiki-name">名称</label><Input id="llmwiki-name" value={name} onChange={(event) => setName(event.target.value)} maxLength={255} /></div>
+          <div className="space-y-2"><label className="text-sm font-medium" htmlFor="llmwiki-description">描述</label><Textarea id="llmwiki-description" value={description} onChange={(event) => setDescription(event.target.value)} rows={4} maxLength={2048} /></div>
+          <div className="space-y-2"><div className="text-sm font-medium">知识库模式</div><div className="grid gap-3 sm:grid-cols-2">
+            <button type="button" className={`rounded-xl border p-4 text-left transition-colors ${wikiEnabled ? "border-primary bg-primary/5 ring-1 ring-primary" : "hover:bg-muted/40"}`} onClick={() => setWikiEnabled(true)}><div className="flex items-center gap-2 text-sm font-semibold"><BookOpen className="size-4 text-violet-500" />Wiki 知识库</div><p className="mt-2 text-xs leading-5 text-muted-foreground">自动综合资料，生成 Wiki 页面和页面关系图谱。</p></button>
+            <button type="button" className={`rounded-xl border p-4 text-left transition-colors ${!wikiEnabled ? "border-primary bg-primary/5 ring-1 ring-primary" : "hover:bg-muted/40"}`} onClick={() => setWikiEnabled(false)}><div className="flex items-center gap-2 text-sm font-semibold"><FileText className="size-4 text-blue-500" />标准知识库</div><p className="mt-2 text-xs leading-5 text-muted-foreground">仅进行文档解析、切块与向量/关键词索引。</p></button>
+          </div></div>
+        </div>
+        <DialogFooter><Button variant="outline" onClick={() => onOpenChange(false)}>取消</Button><Button disabled={pending || !name.trim()} onClick={() => void onCreate({ name: name.trim(), description: description.trim(), type: "document", wiki_enabled: wikiEnabled })}>{pending && <Loader2 className="mr-2 size-4 animate-spin" />}创建</Button></DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export function ConnectionSettings() {
+  const settings = useLlmWikiSettings(true);
+  const actions = useLlmWikiSettingsActions();
+  const [apiUrl, setApiUrl] = useState("");
+  const [webUrl, setWebUrl] = useState("");
+
+  useEffect(() => {
+    if (!settings.data) return;
+    setApiUrl(settings.data.api_base_url || settings.data.file_api_base_url || "");
+    setWebUrl(settings.data.web_base_url || settings.data.file_web_base_url || "");
+  }, [settings.data]);
+
+  const status = useMemo(() => settings.data?.effective_provider === "weknora" ? "WeKnora 模式" : "原 LLMWiki 模式", [settings.data]);
+  if (settings.isLoading) return <div className="flex h-52 items-center justify-center"><Loader2 className="size-5 animate-spin" /></div>;
+  if (settings.error) return <div className="rounded-lg border border-destructive/30 p-5 text-sm text-destructive">{messageOf(settings.error)}</div>;
+  return (
+    <Card className="max-w-3xl">
+      <CardHeader><CardTitle className="flex items-center gap-2 text-base"><Settings2 className="size-5" />WeKnora 连接</CardTitle><CardDescription>这里只管理 cmzs 到 WeKnora 的连接地址。数据库、Redis、模型、存储和解析器仍在 WeKnora 自己的配置中维护。</CardDescription></CardHeader>
+      <CardContent className="space-y-5">
+        <div className="flex flex-wrap gap-2 text-sm"><Badge>{status}</Badge><Badge variant="secondary">服务端代理鉴权</Badge>{settings.data?.override_enabled && <Badge variant="outline">页面配置覆盖中</Badge>}</div>
+        <div className="space-y-2"><label className="text-sm font-medium" htmlFor="weknora-api-url">WeKnora API 地址</label><Input id="weknora-api-url" value={apiUrl} onChange={(event) => setApiUrl(event.target.value)} placeholder="http://weknora-app:8080" /><p className="text-xs text-muted-foreground">非空启用 WeKnora；保存为空会切回原 LLMWiki。</p></div>
+        <div className="space-y-2"><label className="text-sm font-medium" htmlFor="weknora-web-url">WeKnora 管理地址（可选）</label><Input id="weknora-web-url" value={webUrl} onChange={(event) => setWebUrl(event.target.value)} placeholder="https://weknora-admin.example.com" /></div>
+        <div className="rounded-lg border border-amber-500/30 bg-amber-500/5 p-3 text-xs text-muted-foreground">配置文件地址：{settings.data?.file_api_base_url || "未配置"}。页面只配置地址；WeKnora iframe 免登录所需的管理员账号/密码只从后端 config.yaml 或环境变量读取，不在前端保存。</div>
+        <div className="flex flex-wrap gap-2">
+          <Button variant="outline" disabled={!apiUrl.trim() || actions.test.isPending} onClick={async () => { try { await actions.test.mutateAsync(apiUrl.trim()); toast.success("WeKnora 连接正常"); } catch (error) { toast.error(messageOf(error)); } }}>{actions.test.isPending && <Loader2 className="mr-2 size-4 animate-spin" />}测试连接</Button>
+          <Button disabled={actions.save.isPending} onClick={async () => { try { await actions.save.mutateAsync({ override_enabled: true, api_base_url: apiUrl.trim(), web_base_url: webUrl.trim() }); toast.success(apiUrl.trim() ? "已启用 WeKnora 模式" : "已切换到原 LLMWiki 模式"); } catch (error) { toast.error(messageOf(error)); } }}>{actions.save.isPending && <Loader2 className="mr-2 size-4 animate-spin" />}保存页面配置</Button>
+          <Button variant="secondary" disabled={actions.reset.isPending} onClick={async () => { try { await actions.reset.mutateAsync(); toast.success("已恢复 config.yaml 配置"); } catch (error) { toast.error(messageOf(error)); } }}>恢复配置文件</Button>
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+export default WeKnoraKnowledgeWorkspace;

offline-backend-20260512/README.md

@@ -1,13 +1,13 @@
 # DeerFlow 离线后端部署补充
 
-本目录提供与原始 `start_backend.sh` 配套的 wheelhouse。启动脚本保持原有结构，只新增一行 Redis Python 客户端的离线安装命令。
+本目录提供与 `start_backend.sh` 配套的 wheelhouse。启动脚本会在容器启动时检查可选运行时依赖，并在缺包时仅从本地 wheelhouse 安装。
 
 ## 文件
 
 - `offline-runtime-requirements.txt`：固定版本的完整依赖闭包。
 - `prepare_wheelhouse.sh`：联网机器下载 Linux/Python 3.12 wheel，并验证传递依赖完整性。
-- `start_backend.sh`：原始 Docker 启动脚本，加一行 Redis 缺包安装命令。
-- `wheelhouse/`：22 个 wheel 和 `SHA256SUMS`，需要随发布目录一起复制。
+- `start_backend.sh`：Docker 启动脚本，包含 `croniter`、`hindsight-client`、`aiomysql` 和 Redis 客户端的缺包补装逻辑。
+- `wheelhouse/`：24 个 wheel 和 `SHA256SUMS`，需要随发布目录一起复制。
 
 ## 联网机器准备
 
@@ -23,8 +23,9 @@ bash prepare_wheelhouse.sh
 - `croniter==6.2.2`
 - `hindsight-client==0.6.2`
 - `redis==5.2.1`
+- `aiomysql==0.3.2`
 
-上述依赖在 Python 3.12/Linux x86_64 下的 19 个传递依赖也已锁定在 `offline-runtime-requirements.txt`。
+上述依赖在 Python 3.12/Linux x86_64 下的 20 个传递依赖（包括 `PyMySQL==1.2.0`）也已锁定在 `offline-runtime-requirements.txt`。
 
 国内镜像示例：
 
@@ -57,7 +58,9 @@ bash start_backend.sh
 docker logs -f deerflow-backend
 ```
 
-原脚本已有 `croniter` 和 `hindsight-client` 的离线补装逻辑；新增的一行命令只负责在缺少 `redis` 模块时，从 `/app/wheelhouse` 安装 `redis==5.2.1`。
+脚本会先尝试导入依赖，仅在缺少模块时从 `/app/wheelhouse` 安装。`aiomysql` 补装默认开启，可通过 `AIOMYSQL_INSTALL_DEPS=0` 禁用，或通过 `AIOMYSQL_PIP_PACKAGES` 覆盖默认的 `aiomysql==0.3.2`。
+
+MySQL 连接 URL 使用 aiomysql 驱动时应写为 `mysql+aiomysql://user:password@host:3306/database?charset=utf8mb4`。
 
 ## Redis 说明
 

offline-backend-20260512/backend/CLAUDE.md

@@ -123,6 +123,27 @@ cascade pragmas. The router is mounted canonically below
 schema-hidden compatibility prefix `/api/multi-agent/position-roundtable`.
 Clients may retry the compatibility route only for a framework/proxy-level
 `404 Not Found`; domain-level missing-session responses must remain real 404s.
+
+Position roundtable selects the separately seeded built-in agent
+`position-roundtable-intent` by passing `intent_agent_id` to the shared
+`/api/intent/init` and `/api/intent/stream` endpoints. Its request lifecycle,
+files, and SSE protocol match `roundtable-intent`, but its cap is five
+**user-assistance rounds**. A single round may emit several independent
+`ask_clarification` tool calls; those calls are separate cards, not one card
+containing several numbered questions. Count that as one round by the
+tool-calling AI message, never by card count. Topic-only requests must request
+all material missing decisions as separate cards rather than being treated as a
+resolved intent; after the fifth set is answered it must emit completed final
+JSON without unresolved placeholders. The required arrays are
+`coreGoals`, `riskWarnings`, `keyPoints`, and `strategicSignificance`. Do not
+treat a fresh dedicated-agent `ask_clarification` as stale: it must win over
+a same-run premature `[INTENT_READY]` and leave the UI waiting for the user.
+Conversely, the prior turn’s historical clarification must not block the user
+reply from completing. Do not
+change `roundtable-intent`'s `{objective,constraints,assumptions}` contract for
+this feature. The position router accepts the new schema for activation and
+injects all four sections into downstream position-node and closing-agent
+context; legacy stored summaries are mapped read-only for compatibility.
 `/api/intent/init` must create the empty Step-1 thread through
 `multi_agent._create_thread_direct`, exactly like multi-agent initialization;
 do not restore the old HTTP loopback to `/api/threads`, because deployed
@@ -257,7 +278,7 @@ Configuration priority:
 
 ### Gateway API (`app/gateway/`)
 
-FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWAY_ENABLE_DOCS=false` to disable `/docs`, `/redoc`, and `/openapi.json` in production (default: enabled).
+FastAPI application on port 8001 with health checks at `GET|HEAD /health`, `/api/health`, and `/api/langgraph/health`. These exact paths are always public in `auth_middleware.PUBLIC_HEALTH_PATHS`, including when authentication is enabled; reverse-proxy prefixes and trailing slashes are normalized before the whitelist check. Set `GATEWAY_ENABLE_DOCS=false` to disable `/docs`, `/redoc`, and `/openapi.json` in production (default: enabled). Regression coverage: `tests/test_health_auth_bypass.py`.
 
 **Routers**:
 
@@ -436,6 +457,15 @@ Backs the zzJC / zzXD agent-chat left sidebar (「按类型聚合智能体 + 聊
 
 ### Position-collaboration foundation
 
+### Roundtable business-chain human validation
+
+The existing `/api/roundtable-chains` `seats` JSON also accepts the optional
+boolean `human_validation` field on each seat (`ChainSeatSchema`). It is a
+frontend Step 2 checkpoint, not a server-side approval task: after the marked
+seat completes (or, in a DAG, after its stage completes), the client pauses and
+uses the existing resume button or intervention composer to continue. No new
+database column, migration, or validation card is required.
+
 The position-collaboration workspace is a separate frontend route and must not
 use the original roundtable coordinator or jobs. Its shared configuration
 integration point is the existing `/api/roundtable-chains` store: each `seats` JSON item
@@ -600,7 +630,7 @@ Operators upgrading an existing DB run the whole file (`USE <db>;` then execute)
 ### Tool System (`packages/harness/deerflow/tools/`)
 
 `get_available_tools(groups, include_mcp, model_name, subagent_enabled)` assembles:
-1. **Config-defined tools** - Resolved from `config.yaml` via `resolve_variable()`
+1. **Config-defined tools** - Enabled entries are resolved from `config.yaml` via `resolve_variable()`; entries with `enabled: false` are omitted before import and are not registered with the agent
 2. **MCP tools** - From enabled MCP servers (lazy initialized, cached with mtime invalidation)
 3. **Built-in tools**:
    - `present_files` - Make output files visible to user (only `/mnt/user-data/outputs`)
@@ -613,6 +643,7 @@ Operators upgrading an existing DB run the whole file (`USE <db>;` then execute)
 - `tavily/` - Web search (5 results default) and web fetch (4KB limit)
 - `jina_ai/` - Web fetch via Jina reader API with readability extraction
 - `firecrawl/` - Web scraping via Firecrawl API
+- `configurable_search/` - Config-driven `POST` JSON `web_search` replacement. It deep-copies the configured payload and overwrites only `query`, supports HTTP/HTTPS plus configurable `verify_ssl`, timeout and result limit, normalizes nullable `recUuid`/`content`/`title`/`url` fields, and rewrites a result URL through `result_url_template` only when `recUuid` is non-empty. The required response envelope is `{"results": [...]}`. Tests use `httpx.MockTransport` and never require the deployment endpoint.
 
 **ACP agent tools**:
 - `invoke_acp_agent` - Invokes external ACP-compatible agents from `config.yaml`
@@ -921,9 +952,9 @@ Both endpoints are whitelisted in `auth_middleware._PUBLIC_EXACT_PATHS`. The sha
 
 Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` methods.
 
-### WeKnora Retrieval Skill
+### Conditional WeKnora LLMWiki
 
-`skills/custom/weknora-knowledge-search/` is a read-only integration for a WeKnora tenant. The Skill itself only directs the model to two MCP tools, `weknora_search` and `weknora_list_knowledge_bases`; the credential remains inside the stdio MCP subprocess (`scripts/weknora_retrieval_mcp.py`). Its retrieval core groups document/FAQ knowledge bases by `embedding_model_id` and calls WeKnora's multi-KB `hybrid-search` API once per group, preventing invalid cross-embedding score comparisons. It does not discard a KB merely because the legacy list API reports `chunk_count=0`; hybrid-search decides its actual readiness. Wiki pages are opt-in and use their dedicated Wiki search route. In explicit DeerFlow sharing mode, `WEKNORA_DEERFLOW_SHARE_TOKEN_FILE` selects WeKnora's narrow `/api/v1/deerflow/*` capability API: only owner-published document/FAQ knowledge bases are discoverable and searchable, while Wiki is skipped so the skill cannot fall back to a user bearer-token endpoint. Shared document hits include a credential-free source-preview URL. The frontend source card recognizes it and opens a context dialog; its call to authenticated Gateway route `/api/weknora/source-context` is proxied to WeKnora's token-gated `/api/v1/deerflow/knowledge-bases/:id/chunks/:chunk_id/context`, returning only the matching chunk and two neighbours on either side. Never expose the share token to the browser or add it to a URL. Configure through the bundled `templates/extensions_config.fragment.json`; otherwise prefer `WEKNORA_API_KEY_FILE` for scoped-key deployments and `WEKNORA_BEARER_TOKEN_FILE` for legacy deployments. `WEKNORA_ALLOWED_KB_IDS` remains an optional allow-list. Tests: `tests/test_weknora_knowledge_search_skill.py`, `tests/test_weknora_source_preview.py`.
+`llmwiki.weknora.api_base_url` is the provider switch: non-empty enables WeKnora, empty preserves the legacy LLMWiki UI. WeKnora is independently deployed and owns PostgreSQL/Redis/object storage/vector storage/parsers/models; DeerFlow config contains only `api_base_url` and optional `web_base_url`. DeerFlow deliberately sends no WeKnora credential, so the WeKnora endpoint must be restricted to a trusted network and allow DeerFlow traffic itself or through its reverse proxy. There is intentionally no `default_embedding_model_id`: `WeKnoraClient` queries `/api/v1/models` and uses WeKnora's active Embedding model when creating a KB; Wiki creation additionally resolves an active KnowledgeQA model inside WeKnora for synthesis. The native BFF is `app/gateway/routers/llmwiki.py`; ownership/publication mappings live in `deerflow.persistence.llmwiki`; the browser only sees DeerFlow mapping IDs. Knowledge-base owners publish immediately (`private` -> `published`) without a review queue, and can unpublish ordinary bases. The conversation-deposit KB is system-owned, always published, shared by all DeerFlow users, excluded from My Knowledge, and immutable through user/admin detail operations; recognition requires both the reserved name and `system` owner. Existing same-name remote mappings are adopted in place as the system deposit, preserving mapping ids and document links. Its user-facing description, generated Markdown source and tags use `cmzs` branding; list/detail reads synchronize stale remote descriptions, and search results, source previews and embedded-detail JSON recursively replace legacy brand text in historical conversation-deposit payloads. Deposit requests must reference a thread accessible to the current account. Personal knowledge-base list/search views are scoped to the current DeerFlow account even for admins; frontend LLMWiki caches include the live account id, and admin write power does not make other users' private KBs appear as owned. Only `system_role === "admin"` sees the WeKnora connection-config tab. Knowledge cards navigate to a dedicated WeKnora-style detail route. Wiki-enabled bases render and default to `Wiki -> documents -> graph`; standard bases omit Wiki and render `documents -> graph`. The detail page supports sequential multi-file upload with an aggregate result for writable ordinary bases, hides it for public read-only/system-deposit bases, and uses a generic loading label while the embed session starts. It also supports URL and published manual-Markdown imports, browses real Wiki pages/content, proxies authenticated original-file previews, pages through `/chunks/{knowledge_id}`, and renders the Wiki page graph from `/knowledgebase/{kb_id}/wiki/graph`; document details use a right sheet rather than the removed KB modal. The credential-free proxy uses one WeKnora service identity, so per-user separation is enforced by DeerFlow mappings while all remote KBs physically share that identity's WeKnora workspace. WeKnora iframe detail pages first call `/api/llmwiki/knowledge-bases/{id}/weknora/session` through the normal DeerFlow API auth path, then load `/platform/knowledge-bases/{weknora_id}` with a signed `deerflow_weknora_embed` cookie for `/platform`, `/assets`, `/locales`, root assets, and API calls. Injected fetch/XHR rewriting sends all iframe `/api/v1/*`, including colliding `/api/v1/auth/*`, through `/api/llmwiki/weknora-embed/api/v1/*`; Gateway auth/CSRF bypass only applies to those signed iframe proxy requests, the proxy still revalidates the mapped KB, and cookie security honors `X-Forwarded-Proto` for HTTPS reverse proxies. `llmwiki_search` is conditionally registered in `tools.py`, is read-only, and rechecks the current DeerFlow user, agent `llmwiki_knowledge_base_ids`, and thread-context selection on every call. Source previews prefer the cleaned Wiki/LLMWiki page text when a retrieved chunk maps to a Wiki page, with raw split chunks as the fallback. Agent bindings use an inline WeKnora-style searchable/grouped multi-select in the standard agent create/detail UI; new chats use the same interaction pattern as a compact composer dropdown, and selections are written to thread metadata/context and restored on reopen. The DeerFlow frontend is native React and the WeKnora frontend is not modified or embedded. Full deployment and behavior notes: `docs/LLMWIKI_WEKNORA_INTEGRATION_ZH.md`. Tests: `tests/test_llmwiki_weknora.py`.
 
 ### Embedded Client (`packages/harness/deerflow/client.py`)
 
@@ -1132,8 +1163,28 @@ the initial intent workspace plus the summary/action-plan closing agents. Do
 not delete a built-in id because historical chain nodes persist those ids;
 custom role ids may be added and removed.
 
+### Position-roundtable task-scoped session history
+
+`position_roundtable_sessions.external_task_id` is optional. When populated from the frontend route `taskId`, new rows set `task_scoped = true`: a task can have multiple sessions and all users opening that task see the same sessions, nodes and persisted conversation snapshots. When it is NULL/empty, keep the original `user_id`-scoped personal workspace behavior. `20260808_01` adds `task_scoped` with default `false` (so all historical records remain personal) plus the task/update-time index; it must not backfill or make `external_task_id` non-null.
+
+### Roundtable artifact submission status
+
+`roundtable_artifact_submissions` keeps task-level submission state for a
+generated deliverable and is deliberately separate from task details and any
+external task-system delivery. The API is
+`GET /api/roundtable/tasks/{taskId}/artifacts?submitted=true` and
+`PUT /api/roundtable/tasks/{taskId}/artifacts/submission`. All callers use the
+normal Gateway Bearer authentication; records are shared by task while
+`created_by`/`submitted_by`/`cancelled_by` are audit-only. The server derives a
+SHA-256 idempotency key from `taskId + sourceKey + path + revision`: submitting
+the same revision is an upsert, while cancellation only flips `submitted` and
+sets `cancelled_at` (it never deletes history). Store only the sandbox file
+reference (`threadId`, path, source/node/session fields, name/MIME and revision)
+and timestamps; do not persist Markdown content or call a formal delivery
+interface. Previews continue to read the DeerFlow artifact by `threadId + path`.
+
 See `docs/` directory for detailed documentation:
-- [../README.md](../README.md) - Offline Docker wheelhouse preparation and startup workflow. The pinned versions in `../offline-runtime-requirements.txt` and `../start_backend.sh` must stay synchronized. `start_backend.sh` stays aligned with the deployment script and adds only the Redis wheel fallback line. The download target defaults to CPython 3.12 on Linux x86_64 and verifies dependency closure using wheelhouse only.
+- [../README.md](../README.md) - Offline Docker wheelhouse preparation and startup workflow. The pinned versions in `../offline-runtime-requirements.txt` and `../start_backend.sh` must stay synchronized. Startup checks `croniter`, `hindsight-client`, `aiomysql`, and Redis, installing missing packages from wheelhouse only; `aiomysql==0.3.2` includes the pinned `PyMySQL==1.2.0` transitive dependency. The download target defaults to CPython 3.12 on Linux x86_64 and verifies dependency closure using wheelhouse only.
 - [CONFIGURATION.md](docs/CONFIGURATION.md) - Configuration options
 - [ARCHITECTURE.md](docs/ARCHITECTURE.md) - Architecture details
 - [API.md](docs/API.md) - API reference

offline-backend-20260512/backend/README.md

@@ -39,6 +39,8 @@ DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent
 - `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads, thread-local cleanup
 - `/` (non-API) → Frontend - Next.js web interface
 
+Health probes are always unauthenticated, even when API authentication is enabled: `GET|HEAD /health`, `/api/health`, and `/api/langgraph/health` all return the Gateway health status without requiring a cookie or bearer token.
+
 ---
 
 ## Core Components
@@ -78,7 +80,7 @@ Per-thread isolated execution with virtual path translation:
 - **Virtual paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
 - **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
 - **Skills loading**: Recursively discovers nested `SKILL.md` files under `skills/{public,custom}` and preserves nested container paths
-- **WeKnora retrieval skill**: `skills/custom/weknora-knowledge-search` pairs a concise Skill with a stdio MCP server. It retrieves tenant-scoped WeKnora document/FAQ passages through the public API, groups multi-KB calls by embedding model, optionally searches Wiki pages, and can use the local reranker. It does not reject a KB solely because the legacy list API reports `chunk_count=0`; hybrid-search remains the source of truth. For WeKnora's explicit DeerFlow sharing mode, configure `WEKNORA_DEERFLOW_SHARE_TOKEN_FILE`: the MCP uses the restricted `/api/v1/deerflow/*` capability API and can only list/search knowledge bases whose owner enabled sharing; it never receives a user bearer token. Shared document results now contain a credential-free `url` pointer; the source card's “查看原文” dialog calls DeerFlow's authenticated `/api/weknora/source-context` proxy, which retrieves the hit plus two adjacent chunks while keeping the share token server-side. Shared mode currently excludes Wiki pages. Otherwise use `WEKNORA_API_KEY_FILE` for scoped-key deployments or `WEKNORA_BEARER_TOKEN_FILE` for legacy deployments; never put any credential in `SKILL.md` or a chat prompt.
+- **Conditional WeKnora LLMWiki**: a non-empty `llmwiki.weknora.api_base_url` enables the DeerFlow-native WeKnora BFF and UI; an empty address preserves the existing LLMWiki page. WeKnora remains independently deployed and owns its database, Redis, storage, parsers and models. DeerFlow keeps only the API/admin addresses, user/publication mappings, agent knowledge-base bindings and per-conversation selections; it stores and sends no WeKnora credential, so the endpoint must be restricted to a trusted network and allow DeerFlow traffic. Owners publish directly to the public LLMWiki without an approval queue for ordinary bases; the system-owned conversation-deposit base is always published, shared by all users, excluded from My Knowledge, immutable through user/admin detail operations, and recognized by both its reserved name and `system` owner. An existing same-name remote mapping is adopted in place as the system deposit so its mapping id and document links stay valid. Its user-facing knowledge-base description and generated document metadata use the `cmzs` brand; list/detail reads synchronize stale remote descriptions, while conversation-deposit search results, source previews and embedded-detail JSON rewrite legacy brand text to `cmzs`. Deposit requests must reference a thread accessible to the current account. Personal knowledge-base lists are scoped to the current DeerFlow account even for admins, while frontend LLMWiki query caches also include the active account id so switching accounts cannot reuse another account's list/detail data. Admins remain the only role that sees the WeKnora connection-config tab. Knowledge cards open a dedicated WeKnora-style detail route: Wiki-enabled bases default to Wiki, then documents and graph; standard bases hide Wiki and default to documents. Writable ordinary knowledge-base details expose a native multi-file upload action that submits files sequentially and reports aggregate success/failure; read-only public bases and the system deposit base do not. It supports file/URL/manual-Markdown imports, Wiki page browsing, document preview, real parsed chunks and Wiki graph nodes/edges. New chats use a compact WeKnora-style searchable/grouped multi-select inside the composer, while agent create/edit pages bind spaces through an inline panel. A single proxy service identity means DeerFlow users are isolated logically while their WeKnora entities share that identity's workspace. The read-only `llmwiki_search` tool reauthorizes the current DeerFlow user on every call and renders credential-free source previews; source previews prefer cleaned Wiki/LLMWiki text when a retrieved chunk maps to a Wiki page, with raw chunks as the fallback. The detail page first creates a signed iframe session through the normal DeerFlow API auth path, then points the iframe directly at the proxied WeKnora `/platform/...` route using the signed `deerflow_weknora_embed` cookie; global auth/CSRF bypass is limited to those signed iframe proxy requests, and HTTPS cookie attributes honor `X-Forwarded-Proto` behind reverse proxies. The iframe proxy keeps WeKnora's root-relative `/platform`, `/assets`, `/locales`, and `/api/v1/*` paths, but is registered last through `llmwiki.proxy_router` so it cannot intercept first-party Gateway APIs such as `POST /api/v1/auth/login/username`. See [docs/LLMWIKI_WEKNORA_INTEGRATION_ZH.md](docs/LLMWIKI_WEKNORA_INTEGRATION_ZH.md).
 - **File-write safety**: `str_replace` serializes read-modify-write per `(sandbox.id, path)` so isolated sandboxes keep concurrency even when virtual paths match
 - **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace` (`bash` is disabled by default when using `LocalSandboxProvider`; use `AioSandboxProvider` for isolated shell access)
 
@@ -111,6 +113,19 @@ LLM-powered persistent context retention across conversations:
 | **MCP** | Any Model Context Protocol server (stdio, SSE, HTTP transports) |
 | **Skills** | Domain-specific workflows injected via system prompt |
 
+#### Configurable HTTP web search
+
+The config-defined `web_search` tool can call a deployment-specific JSON API
+instead of a public search provider. Set its `endpoint`, static `payload`, SSL
+verification, timeout, result limit, and `result_url_template` in `config.yaml`.
+At runtime only `payload.query` is overwritten with the model's search text.
+The API response must use `{"results": [{"recUuid": "", "content": "",
+"title": "", "url": ""}]}`; missing or null result fields are normalized to empty strings. When
+`recUuid` is present, `{recUuid}` in `result_url_template` replaces the original
+result URL; otherwise the original URL is retained. Set `enabled: false` to keep
+the tool completely out of the agent's registered tool list. `verify_ssl: false`
+supports trusted internal HTTPS services with self-signed certificates.
+
 ### Gateway API
 
 FastAPI application providing REST endpoints for frontend integration:
@@ -123,7 +138,7 @@ FastAPI application providing REST endpoints for frontend integration:
 | `POST /api/skills/install` | Install skill from `.skill` archive |
 | `GET/POST /api/agents` | List visible agents or create a user-owned agent |
 | `GET/PUT/DELETE /api/agents/{id}` | Read, update, or delete an id-addressed agent |
-| `GET/POST/PUT/DELETE /api/roundtable-chains` | Manage user-owned roundtable business chains; each seat may optionally carry `position_id` for the separate position-collaboration workspace (the original roundtable ignores it) |
+| `GET/POST/PUT/DELETE /api/roundtable-chains` | Manage user-owned roundtable business chains; each seat may optionally carry `position_id` for the separate position-collaboration workspace, plus `human_validation` to mark a Step 2 client-side pause checkpoint after that seat/stage completes (the original roundtable has no extra validation card) |
 | `GET/PUT /api/business-mapping` | Read global business mappings. Updates to 3Q/6BF/7BF require an administrator; the 8BF public business-chain mapping is maintained exclusively by the trusted `lqq` account (derived from the authenticated email prefix). |
 | `GET/POST/PUT /api/position-roundtable/sessions` | Standalone position-collaboration sessions: freeze task/intent/chain snapshots, index one direct-agent node per seat, build upstream handoff context (including bounded UTF-8 excerpts of text artifacts), and make archived sessions read-only without invoking the original roundtable coordinator or jobs. Built-in summary/action-plan completion mirrors visible report text into a Markdown artifact when a model omits its final `write_file` call. `POST /sessions/{id}/nodes/{nodeKey}/reject` accepts an optional reason, marks the rejected delivery for rework, and invalidates affected downstream deliveries so they are regenerated in order. The same router is also mounted at `/api/multi-agent/position-roundtable/*` for intranet gateways that only forward the established multi-agent namespace; the compatibility mount is intentionally omitted from OpenAPI. |
 | `GET /api/memory` | Retrieve memory data |
@@ -144,6 +159,8 @@ FastAPI application providing REST endpoints for frontend integration:
 
 The separately deployed TaskCOP Vue app uses `POST /api/v1/auth/login/username` directly (its `username`, `userId`, or `yUserId` URL parameter identifies the user), so this compatibility flow does not depend on the retired Consumer login service. It calls the Gateway address configured as `b1ConsumerUrl` directly; it does not use a Vite `/api` reverse proxy. An empty TaskCOP store remains empty; task data is introduced through normal creation or the JSON import API. The Gateway CORS middleware always merges the local TaskCOP Vite origins `http://localhost:8080` and `http://127.0.0.1:8080`, including when `GATEWAY_CORS_ORIGINS` is set for another frontend. `scripts/env.sh` also includes them in its startup default. For a deployment, set `GATEWAY_CORS_ORIGINS` to the exact additional frontend origins that are allowed to call the Gateway.
 
+Position-roundtable history supports two modes. A non-empty `external_task_id` from the frontend route's `taskId` creates a row with `task_scoped = true`, so all sessions, nodes and persisted conversation snapshots for that task are shared across users; `user_id` is then creator audit metadata only. When the field is absent or empty, the original per-user personal-session behavior remains unchanged. Alembic revision `20260808_01` adds `task_scoped` with the safe default `false` for historical rows plus the task/update-time index.
+
 AI writing supports a sample-imitation mode: the frontend can upload or paste a sample article, the Gateway extracts text for document files, and the `ai_writing` graph runs a `sample_analyzer` node before normal intent/research/outline/draft stages. The resulting style profile is injected into outline and draft prompts with explicit guardrails against copying source sentences, facts, names, or data.
 
 ### Custom Agents
@@ -479,6 +496,24 @@ checkpoint or sandbox-output volume is replaced. Apply Alembic revision
 
 Its live intent conversation still uses the shared `/api/intent/init` and
 `/api/intent/stream` endpoints used by the original multi-agent roundtable.
+Position roundtable identifies itself with `intent_agent_id: "position-roundtable-intent"`;
+this is a separately seeded built-in agent, not an alias of `roundtable-intent`.
+It preserves the same thread, SSE streaming, and file-reading lifecycle as the
+generic Step-1 agent, but has its own **at-most-five user-assistance-round**
+brake. A round is one AI turn plus the user reply, not one tool call: the
+dedicated agent may emit several independent `ask_clarification` calls in the
+same turn, which the frontend renders as several separate selection cards and
+submits together. A topic-only request is not considered resolved: the agent
+asks for every independent missing decision (such as scope, decision use, or
+task constraints) as separate cards. For the dedicated agent, a fresh
+`ask_clarification` emitted in a stream is a strict user-input pause and wins over any same-run premature
+`[INTENT_READY]`; a historical clarification from the prior turn does not
+block the user answer from completing. Its final
+`[INTENT_READY]` JSON contains four string arrays: `coreGoals`, `riskWarnings`,
+`keyPoints`, and `strategicSignificance`; it must contain completed conclusions,
+not “待确认” or other unresolved placeholders. The multi-agent endpoint remains
+backwards compatible when this optional field is omitted and continues to emit
+`objective`, `constraints`, and `assumptions`.
 `/api/intent/init` creates its empty thread directly through the in-process
 thread store/checkpointer, matching multi-agent initialization and avoiding a
 deployment-sensitive `127.0.0.1:<gateway-port>` loopback. If initial checkpoint
@@ -507,3 +542,23 @@ is required. It is the initial intent-identification workspace and owns the
 summary/action-plan closing agents. Built-in rows retain stable ids so
 historical chain nodes remain readable; they can be edited or disabled but not
 deleted. Custom roles may be freely added or removed.
+
+## Roundtable artifact submission status
+
+The task-scoped roundtable workbench exposes a lightweight submission-status
+API for generated deliverables:
+
+- `GET /api/roundtable/tasks/{taskId}/artifacts?submitted=true` returns the
+  submitted artifact references for a task (or `items: []`).
+- `PUT /api/roundtable/tasks/{taskId}/artifacts/submission` records
+  `submitted: true` or cancels it with `submitted: false`.
+
+Both routes use the normal Gateway `Authorization: Bearer <token>` middleware.
+The record is shared by `taskId`; the authenticated user is retained only in
+audit columns. Its server-owned idempotency key is
+`taskId + sourceKey + path + revision`. Repeating the same submitted payload
+returns the existing record; cancellation updates its state and timestamp
+without deleting the audit row. DeerFlow stores only the artifact reference
+(`threadId` + sandbox `path`, plus the optional session/node/name/MIME fields),
+never the Markdown body and never a task-system delivery. Continue to preview
+the file through the existing thread-artifact endpoint.

offline-backend-20260512/backend/app/gateway/app.py

@@ -1,26 +1,26 @@
 import asyncio
 import logging
-import os
-import queue
-import sys
-import threading
-from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
-from datetime import datetime
-from time import perf_counter
-
-from dotenv import load_dotenv
-from fastapi import FastAPI
+import os
+import queue
+import sys
+import threading
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from datetime import datetime
+from time import perf_counter
+
+from dotenv import load_dotenv
+from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
 # Load .env BEFORE any module that reads os.environ at import time.
 # Without this, GATEWAY_CORS_ORIGINS / AUTH_JWT_SECRET / DEER_FLOW_AUTH_DISABLED
 # placed in /workspace/.env are silently ignored when the container is started
 # without explicit `-e` flags, leading to ephemeral JWT secrets, missing CORS
-# origins, and "Failed to fetch" in the browser.
-load_dotenv()
-
-from app.gateway.auth.disabled_mode import is_auth_disabled  # noqa: E402
+# origins, and "Failed to fetch" in the browser.
+load_dotenv()
+
+from app.gateway.auth.disabled_mode import is_auth_disabled  # noqa: E402
 from app.gateway.auth_middleware import AuthMiddleware
 from app.gateway.config import get_gateway_config
 from app.gateway.csrf_middleware import CSRFMiddleware
@@ -43,16 +43,18 @@ from app.gateway.routers import (
     intent,
     knowledge,
     knowledge_ingest,
-    light_apps,
-    llm_metrics,
-    mcp,
+    light_apps,
+    llm_metrics,
+    llmwiki,
+    mcp,
     memory,
-    menu_overrides,
-    models,
+    menu_overrides,
+    model_management,
+    models,
     multi_agent,
     notifications,
     open_3qfx,
-    open_chat,
+    open_chat,
     parallel_agent_tasks,
     parallel_agents,
     position_roundtable,
@@ -65,8 +67,9 @@ from app.gateway.routers import (
     recommend,
     flow_extract,
     recommended_questions,
-    roundtable_chains,
-    roundtable_diagnostics,
+    roundtable_chains,
+    roundtable_artifact_submissions,
+    roundtable_diagnostics,
     roundtable_draft_shares,
     roundtable_drafts,
     roundtable_jobs,
@@ -89,8 +92,7 @@ from app.gateway.routers import (
     uploads,
     user_preferences,
     user_prompts,
-    weknora_sources,
-    writing,
+    writing,
 )
 from deerflow.config import app_config as deerflow_app_config
 from deerflow.config.app_config import apply_logging_level
@@ -1424,14 +1426,16 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
         )
 
     # Include routers
-    # Models API is mounted at /api/models
-    app.include_router(models.router)
+    # Models API is mounted at /api/models
+    app.include_router(models.router)
+    # Administrator-managed config.yaml model settings and connection tests.
+    app.include_router(model_management.router)
 
     # MCP API is mounted at /api/mcp
     app.include_router(mcp.router)
 
-    # Authenticated source-context proxy for the WeKnora retrieval skill.
-    app.include_router(weknora_sources.router)
+    # DeerFlow-native LLMWiki management/search BFF (conditionally backed by WeKnora).
+    app.include_router(llmwiki.router)
 
     # Memory API is mounted at /api/memory
     app.include_router(memory.router)
@@ -1465,8 +1469,11 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
     # Roundtable-planning drafts + recommendation history at /api/roundtable-drafts
     app.include_router(roundtable_drafts.router)
 
-    # Task-scoped roundtable drafts (taskId 深链聊天记录，独立存、不分权) at /api/roundtable-task-drafts
-    app.include_router(roundtable_task_drafts.router)
+    # Task-scoped roundtable drafts (taskId 深链聊天记录，独立存、不分权) at /api/roundtable-task-drafts
+    app.include_router(roundtable_task_drafts.router)
+
+    # Task-scoped artifact submission status; stores references only, never artifact content.
+    app.include_router(roundtable_artifact_submissions.router)
 
     # Step3 流程图结构化抽取 + 校验 (SSE) at /api/flow-extract
     app.include_router(flow_extract.router)
@@ -1618,24 +1625,30 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
     # ??? app/gateway/routers/{multi_agent,intent,recommend}.py?
     # ??? frontend-web/docs/multi-agent-backend-dev.md
     app.include_router(multi_agent.router)   # Step 2?init(SSE) + run/stream(leader|special)
-    app.include_router(intent.router)        # Step 1?/api/intent/init + /stream
-    app.include_router(recommend.router)     # Step 1?2?/api/recommend/stream?? init?
-    # Step 3 ????/?????? artifacts.router?/api/threads/{id}/artifacts?
-
-    # ?????????(? auth_middleware._PUBLIC_PATH_PREFIXES)?
-    # ????? ``/health`` ?? API ??? ``/api/health``,?????
-    # ?? base URL ????,?????????? 401?
-    @app.get("/health", tags=["health"])
-    @app.get("/api/health", tags=["health"])
+    app.include_router(intent.router)        # Step 1?/api/intent/init + /stream
+    app.include_router(recommend.router)     # Step 1?2?/api/recommend/stream?? init?
+    # Step 3 ????/?????? artifacts.router?/api/threads/{id}/artifacts?
+
+    # Health probes are always unauthenticated (see
+    # auth_middleware.PUBLIC_HEALTH_PATHS). Support the bare Gateway path,
+    # API base URL, and LangGraph proxy base URL for deployment monitors.
+    @app.api_route("/health", methods=["GET", "HEAD"], tags=["health"])
+    @app.api_route("/api/health", methods=["GET", "HEAD"], tags=["health"])
+    @app.api_route("/api/langgraph/health", methods=["GET", "HEAD"], tags=["health"])
     async def health_check() -> dict:
         """Health check endpoint.
 
         Returns:
             Service health status information.
-        """
-        return {"status": "healthy", "service": "deer-flow-gateway"}
-
-    return app
+        """
+        return {"status": "healthy", "service": "deer-flow-gateway"}
+
+    # WeKnora's embedded frontend uses root-relative routes such as /platform,
+    # /assets, /locales and /api/v1/*. Register that proxy last so it stays a
+    # true fallback and cannot intercept DeerFlow APIs.
+    app.include_router(llmwiki.proxy_router)
+
+    return app
 
 
 # Create app instance for uvicorn

offline-backend-20260512/backend/app/gateway/auth_middleware.py

@@ -19,20 +19,35 @@ from starlette.types import ASGIApp
 
 from app.gateway.auth.disabled_mode import get_assumed_user_for_disabled_auth, is_auth_disabled
 from app.gateway.auth.errors import AuthErrorCode, AuthErrorResponse
-from app.gateway.authz import _ALL_PERMISSIONS, AuthContext
-from app.gateway.internal_auth import INTERNAL_AUTH_HEADER_NAME, get_internal_user, is_valid_internal_auth_token
-from app.gateway.proxy_path import app_relative_path
-from deerflow.runtime.user_context import reset_current_user, set_current_user
+from app.gateway.authz import _ALL_PERMISSIONS, AuthContext
+from app.gateway.internal_auth import INTERNAL_AUTH_HEADER_NAME, get_internal_user, is_valid_internal_auth_token
+from app.gateway.proxy_path import app_relative_path
+from app.gateway.weknora_embed import (
+    WEKNORA_EMBED_COOKIE,
+    has_valid_weknora_embed_cookie,
+    is_weknora_embed_proxy_path,
+)
+from deerflow.runtime.user_context import reset_current_user, set_current_user
 
-# Paths that never require authentication.
+# Health probes are deliberately public, including the LangGraph-compatible
+# gateway alias used by some deployments. Keep these as exact paths: health
+# checks must bypass authentication, but similarly named application routes
+# must not inherit that exemption.
+PUBLIC_HEALTH_PATHS: frozenset[str] = frozenset(
+    {
+        "/health",
+        "/api/health",
+        "/api/langgraph/health",
+    }
+)
+
+# Path prefixes that never require authentication.
 #
 # ``/api/public/`` is a namespace reserved for intentionally world-readable,
 # read-only endpoints (e.g. public conversation share snapshots). Only mount
 # safe read-only routes under it — everything there bypasses auth entirely.
-_PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
-    "/health",
-    "/api/health",
-    "/docs",
+_PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
+    "/docs",
     "/redoc",
     "/openapi.json",
     "/api/public/",
@@ -43,9 +58,10 @@ _PUBLIC_PATH_PREFIXES: tuple[str, ...] = (
 
 # Exact auth paths that are public (login/register/status check).
 # /api/v1/auth/me, /api/v1/auth/change-password etc. are NOT public.
-_PUBLIC_EXACT_PATHS: frozenset[str] = frozenset(
-    {
-        "/api/v1/auth/login/local",
+_PUBLIC_EXACT_PATHS: frozenset[str] = frozenset(
+    {
+        *PUBLIC_HEALTH_PATHS,
+        "/api/v1/auth/login/local",
         "/api/v1/auth/login/username",
         "/api/v1/auth/login/token",
         "/api/v1/auth/register",
@@ -54,15 +70,31 @@ _PUBLIC_EXACT_PATHS: frozenset[str] = frozenset(
         "/api/v1/auth/initialize",
         # 并行多智能体面板专用的「绕过常规登录」取 token 端点（内网部署限制了标准登录时用）。
         "/api/parallel-agents/auth/token",
-    }
-)
-
-
-def _is_public(path: str) -> bool:
-    stripped = path.rstrip("/")
-    if stripped in _PUBLIC_EXACT_PATHS:
-        return True
-    return any(path.startswith(prefix) for prefix in _PUBLIC_PATH_PREFIXES)
+    }
+)
+
+
+def _is_public(path: str) -> bool:
+    stripped = path.rstrip("/")
+    if stripped in _PUBLIC_EXACT_PATHS:
+        return True
+    return any(path.startswith(prefix) for prefix in _PUBLIC_PATH_PREFIXES)
+
+
+def _is_weknora_embed_proxy_request(request: Request) -> bool:
+    """Let the WeKnora embed proxy verify its own signed iframe cookie.
+
+    The embedded WeKnora frontend loads root-relative routes (``/platform``,
+    ``/assets``, ``/locales`` and ``/api/v1/*``). Those requests do not carry
+    DeerFlow's Authorization header, but the iframe bootstrap has already set a
+    short-lived signed cookie that the proxy router validates against the
+    requested knowledge base.
+    """
+
+    path = app_relative_path(request)
+    if not is_weknora_embed_proxy_path(path):
+        return False
+    return has_valid_weknora_embed_cookie(request.cookies.get(WEKNORA_EMBED_COOKIE))
 
 
 # 「发起问答」的 run 创建接口(会真正调用大模型):
@@ -103,12 +135,14 @@ class AuthMiddleware(BaseHTTPMiddleware):
         super().__init__(app)
 
     async def dispatch(self, request: Request, call_next: Callable) -> Response:
-        # Match the application-relative path so a reverse-proxy prefix
-        # (e.g. /xxx/api/public/...) does not defeat the public whitelist.
-        if _is_public(app_relative_path(request)):
-            return await call_next(request)
-
-        if is_auth_disabled():
+        # Match the application-relative path so a reverse-proxy prefix
+        # (e.g. /xxx/api/public/...) does not defeat the public whitelist.
+        if _is_public(app_relative_path(request)):
+            return await call_next(request)
+        if _is_weknora_embed_proxy_request(request):
+            return await call_next(request)
+
+        if is_auth_disabled():
             user = await get_assumed_user_for_disabled_auth()
             request.state.user = user
             request.state.auth = AuthContext(user=user, permissions=_ALL_PERMISSIONS)

offline-backend-20260512/backend/app/gateway/csrf_middleware.py

@@ -7,16 +7,21 @@ State-changing operations require CSRF protection.
 import secrets
 from collections.abc import Callable
 
-from app.gateway.auth.disabled_mode import is_auth_disabled
-from app.gateway.proxy_path import app_relative_path
-from fastapi import Request, Response
+from app.gateway.auth.disabled_mode import is_auth_disabled
+from app.gateway.proxy_path import app_relative_path
+from app.gateway.weknora_embed import (
+    WEKNORA_EMBED_COOKIE,
+    has_valid_weknora_embed_cookie,
+    is_weknora_embed_proxy_path,
+)
+from fastapi import Request, Response
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.responses import JSONResponse
 from starlette.types import ASGIApp
 
-CSRF_COOKIE_NAME = "csrf_token"
-CSRF_HEADER_NAME = "X-CSRF-Token"
-CSRF_TOKEN_LENGTH = 64  # bytes
+CSRF_COOKIE_NAME = "csrf_token"
+CSRF_HEADER_NAME = "X-CSRF-Token"
+CSRF_TOKEN_LENGTH = 64  # bytes
 
 
 def is_secure_request(request: Request) -> bool:
@@ -29,7 +34,7 @@ def generate_csrf_token() -> str:
     return secrets.token_urlsafe(CSRF_TOKEN_LENGTH)
 
 
-def should_check_csrf(request: Request) -> bool:
+def should_check_csrf(request: Request) -> bool:
     """Determine if a request needs CSRF validation.
 
     CSRF is checked for state-changing methods (POST, PUT, DELETE, PATCH).
@@ -54,9 +59,18 @@ def should_check_csrf(request: Request) -> bool:
         return False
     # 开放问答接口同样是匿名、无会话的(见 auth_middleware._PUBLIC_PATH_PREFIXES),
     # 双提交 Cookie 既无 token 可比、也无会话可被伪造,豁免之。
-    if path.startswith("/api/open/"):
-        return False
-    return True
+    if path.startswith("/api/open/"):
+        return False
+    if is_weknora_embed_proxy_request(request):
+        return False
+    return True
+
+
+def is_weknora_embed_proxy_request(request: Request) -> bool:
+    path = app_relative_path(request)
+    if not is_weknora_embed_proxy_path(path):
+        return False
+    return has_valid_weknora_embed_cookie(request.cookies.get(WEKNORA_EMBED_COOKIE))
 
 
 _AUTH_EXEMPT_PATHS: frozenset[str] = frozenset(

offline-backend-20260512/backend/app/gateway/deps.py

@@ -293,10 +293,16 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
 
         app.state.dashboard_session_store = make_dashboard_session_store(sf)
 
-        from deerflow.persistence.task_buttons import make_task_button_store
-
+        from deerflow.persistence.task_buttons import make_task_button_store
+
         app.state.task_button_store = make_task_button_store(sf)
 
+        from deerflow.integrations.weknora.runtime import register_llmwiki_store
+        from deerflow.persistence.llmwiki import make_llmwiki_store
+
+        app.state.llmwiki_store = make_llmwiki_store(sf)
+        register_llmwiki_store(app.state.llmwiki_store)
+
         from deerflow.persistence.taskcop_tasks import make_taskcop_task_store
 
         app.state.taskcop_task_store = make_taskcop_task_store(sf)
@@ -305,6 +311,11 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
 
         app.state.task_report_store = make_task_report_store(sf)
 
+        from deerflow.persistence.roundtable_artifact_submissions import make_roundtable_artifact_submission_store
+
+        # Task-scoped artifact submission status: shared by task; actor is audit-only.
+        app.state.roundtable_artifact_submission_store = make_roundtable_artifact_submission_store(sf)
+
         from deerflow.persistence.parallel_agent_tasks import make_parallel_agent_task_store
 
         app.state.parallel_agent_task_store = make_parallel_agent_task_store(sf)
@@ -613,27 +624,34 @@ _cached_local_provider: LocalAuthProvider | None = None
 _cached_repo: SQLiteUserRepository | None = None
 
 
-def get_request_access_token(request: Request) -> str | None:
-    """Extract access token from cookie or Authorization header.
-
-    Priority:
-    1. ``access_token`` cookie (browser session mode)
-    2. ``Authorization: Bearer <token>`` header (API client mode)
-    """
-    cookie_token = request.cookies.get("access_token")
-    if cookie_token:
-        return cookie_token
-
-    authorization = request.headers.get("authorization", "").strip()
-    if not authorization:
-        return None
-
-    scheme, _, token = authorization.partition(" ")
-    if scheme.lower() != "bearer":
-        return None
-
-    token = token.strip()
-    return token or None
+def get_request_access_token(request: Request) -> str | None:
+    """Extract access token from cookie or Authorization header.
+
+    Priority:
+    1. ``access_token`` cookie (browser session mode)
+    2. ``Authorization: Bearer <token>`` header (API client mode)
+    3. ``access_token`` query parameter for the WeKnora iframe bootstrap only
+    """
+    cookie_token = request.cookies.get("access_token")
+    if cookie_token:
+        return cookie_token
+
+    authorization = request.headers.get("authorization", "").strip()
+    if authorization:
+        scheme, _, token = authorization.partition(" ")
+        if scheme.lower() == "bearer":
+            token = token.strip()
+            if token:
+                return token
+
+    from app.gateway.proxy_path import app_relative_path
+
+    path = app_relative_path(request).rstrip("/")
+    if path.startswith("/api/llmwiki/knowledge-bases/") and path.endswith("/weknora/frame"):
+        query_token = (request.query_params.get("access_token") or "").strip()
+        if query_token:
+            return query_token
+    return None
 
 
 def get_local_provider() -> LocalAuthProvider:

offline-backend-20260512/backend/app/gateway/llmwiki_deposit.py

@@ -0,0 +1,293 @@
+"""Asynchronous conversation sedimentation into WeKnora-backed LLMWiki."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from deerflow.integrations.weknora.client import WeKnoraClient, WeKnoraError
+from deerflow.integrations.weknora.runtime import build_weknora_client, get_resolved_llmwiki_runtime
+from deerflow.persistence.llmwiki import LlmWikiStore
+
+logger = logging.getLogger(__name__)
+
+CONVERSATION_DEPOSIT_KB_NAME = "对话沉淀"
+CONVERSATION_DEPOSIT_OWNER_USER_ID = "system"
+CONVERSATION_DEPOSIT_KB_DESCRIPTION = "cmzs 全局问答沉淀知识库。所有用户可见，不默认参与问答检索。"
+_DEPOSIT_KB_LOCK = asyncio.Lock()
+
+
+@dataclass(frozen=True)
+class ConversationTurnDeposit:
+    thread_id: str
+    question: str
+    answer: str
+    human_message_id: str | None
+    assistant_message_id: str
+    assistant_id: str | None
+    knowledge_base_ids: list[str]
+    created_by_user_id: str | None
+
+
+def _store(app: Any) -> LlmWikiStore | None:
+    return getattr(app.state, "llmwiki_store", None)
+
+
+def _client(app: Any) -> WeKnoraClient | None:
+    runtime = get_resolved_llmwiki_runtime(getattr(app.state, "config", None))
+    if not runtime.weknora_enabled:
+        return None
+    try:
+        return build_weknora_client(runtime)
+    except RuntimeError:
+        logger.debug("LLMWiki conversation deposit skipped: WeKnora client is unavailable", exc_info=True)
+        return None
+
+
+def _shorten(text: str, max_chars: int) -> str:
+    value = " ".join(str(text or "").split())
+    if len(value) <= max_chars:
+        return value
+    return f"{value[: max_chars - 1].rstrip()}…"
+
+
+def _title_for_turn(turn: ConversationTurnDeposit) -> str:
+    question = _shorten(turn.question, 48)
+    return f"对话沉淀 - {question or turn.assistant_message_id[:12]}"
+
+
+def _format_markdown(turn: ConversationTurnDeposit, title: str) -> str:
+    kb_line = "、".join(turn.knowledge_base_ids) if turn.knowledge_base_ids else "未显式选择知识库"
+    return f"""---
+source: cmzs
+type: conversation-deposit
+thread_id: {turn.thread_id}
+human_message_id: {turn.human_message_id or ""}
+assistant_message_id: {turn.assistant_message_id}
+assistant_id: {turn.assistant_id or ""}
+knowledge_base_ids: {kb_line}
+created_by_user_id: {turn.created_by_user_id or ""}
+---
+
+# {title}
+
+> 本页由 cmzs 在一轮问答结束后自动沉淀，用于后续 LLMWiki 检索、Wiki 索引与图谱构建。
+
+## 摘要
+
+{_shorten(turn.answer, 360) or "本轮回答为空。"}
+
+## 用户问题
+
+{turn.question.strip() or "（空）"}
+
+## 助手回答
+
+{turn.answer.strip() or "（空）"}
+
+## 结构化线索
+
+- 来源线程：`{turn.thread_id}`
+- 用户消息：`{turn.human_message_id or ""}`
+- 回答消息：`{turn.assistant_message_id}`
+- 智能体：`{turn.assistant_id or "通用问答"}`
+- 本轮显式知识库：{kb_line}
+
+## LLMWiki 标签
+
+#对话沉淀 #cmzs #问答知识
+"""
+
+
+async def _sync_conversation_deposit_description(
+    store: LlmWikiStore,
+    client: WeKnoraClient,
+    row: dict[str, Any],
+) -> dict[str, Any]:
+    if str(row.get("description") or "") == CONVERSATION_DEPOSIT_KB_DESCRIPTION:
+        return row
+    try:
+        await client.update_knowledge_base(
+            str(row["weknora_id"]),
+            {"description": CONVERSATION_DEPOSIT_KB_DESCRIPTION},
+        )
+    except WeKnoraError:
+        logger.warning("Failed to update the conversation deposit knowledge-base description", exc_info=True)
+        return row
+    updated = await store.update_mapping(
+        str(row["id"]),
+        description=CONVERSATION_DEPOSIT_KB_DESCRIPTION,
+    )
+    return updated or row
+
+
+async def ensure_conversation_deposit_mapping(
+    store: LlmWikiStore,
+    client: WeKnoraClient,
+    *,
+    remote_knowledge_bases: list[dict[str, Any]] | None = None,
+) -> dict[str, Any] | None:
+    existing = await store.get_conversation_deposit_mapping()
+    if existing is not None:
+        return await _sync_conversation_deposit_description(store, client, existing)
+
+    async with _DEPOSIT_KB_LOCK:
+        existing = await store.get_conversation_deposit_mapping()
+        if existing is not None:
+            return await _sync_conversation_deposit_description(store, client, existing)
+
+        remote_id = ""
+        try:
+            remote_items = remote_knowledge_bases
+            if remote_items is None:
+                remote_items = await client.list_knowledge_bases()
+            for remote in remote_items:
+                if str(remote.get("name") or "").strip() == CONVERSATION_DEPOSIT_KB_NAME and remote.get("id"):
+                    remote_id = str(remote["id"])
+                    break
+        except WeKnoraError:
+            logger.debug("Could not scan WeKnora knowledge bases before creating deposit base", exc_info=True)
+
+        if remote_id:
+            mapped = await store.get_by_weknora_id(remote_id)
+            if mapped is not None:
+                try:
+                    await client.update_knowledge_base(
+                        remote_id,
+                        {"description": CONVERSATION_DEPOSIT_KB_DESCRIPTION},
+                    )
+                except WeKnoraError:
+                    logger.warning("Failed to update the existing conversation deposit knowledge-base description", exc_info=True)
+                return await store.adopt_conversation_deposit_mapping(
+                    str(mapped["id"]),
+                    name=CONVERSATION_DEPOSIT_KB_NAME,
+                    description=CONVERSATION_DEPOSIT_KB_DESCRIPTION,
+                )
+            try:
+                remote = await client.update_knowledge_base(
+                    remote_id,
+                    {"description": CONVERSATION_DEPOSIT_KB_DESCRIPTION},
+                )
+            except WeKnoraError:
+                logger.warning("Failed to update the existing conversation deposit knowledge-base description", exc_info=True)
+                remote = {
+                    "id": remote_id,
+                    "name": CONVERSATION_DEPOSIT_KB_NAME,
+                    "description": CONVERSATION_DEPOSIT_KB_DESCRIPTION,
+                    "type": "document",
+                }
+        else:
+            try:
+                remote = await client.create_knowledge_base(
+                    name=CONVERSATION_DEPOSIT_KB_NAME,
+                    description=CONVERSATION_DEPOSIT_KB_DESCRIPTION,
+                    kb_type="document",
+                    wiki_enabled=True,
+                )
+            except WeKnoraError:
+                logger.warning("Failed to create WeKnora conversation deposit knowledge base", exc_info=True)
+                return None
+
+        try:
+            row = await store.create_mapping(
+                weknora_id=str(remote["id"]),
+                owner_user_id=CONVERSATION_DEPOSIT_OWNER_USER_ID,
+                name=CONVERSATION_DEPOSIT_KB_NAME,
+                description=CONVERSATION_DEPOSIT_KB_DESCRIPTION,
+                kb_type="document",
+            )
+            published = await store.request_publish(str(row["id"]), CONVERSATION_DEPOSIT_OWNER_USER_ID, is_admin=True)
+            return published or row
+        except Exception:
+            logger.exception("Failed to persist conversation deposit knowledge-base mapping")
+            return None
+
+
+async def ensure_conversation_deposit_knowledge_base(
+    app: Any,
+    *,
+    owner_user_id: str | None,
+) -> dict[str, Any] | None:
+    store = _store(app)
+    client = _client(app)
+    if store is None or client is None:
+        return None
+    return await ensure_conversation_deposit_mapping(store, client)
+
+
+async def deposit_conversation_turn(app: Any, turn: ConversationTurnDeposit) -> None:
+    if not turn.thread_id or not turn.assistant_message_id:
+        return
+    if not turn.question.strip() and not turn.answer.strip():
+        return
+
+    store = _store(app)
+    client = _client(app)
+    if store is None or client is None:
+        return
+
+    kb = await ensure_conversation_deposit_knowledge_base(app, owner_user_id=turn.created_by_user_id)
+    if kb is None:
+        return
+
+    previous = await store.get_conversation_deposit(
+        thread_id=turn.thread_id,
+        assistant_message_id=turn.assistant_message_id,
+    )
+    previous_doc_id = str((previous or {}).get("weknora_knowledge_id") or "")
+    if previous_doc_id:
+        try:
+            await client.delete_document(previous_doc_id)
+        except WeKnoraError as exc:
+            if exc.status_code != 404:
+                logger.warning("Failed to delete old conversation deposit document %s", previous_doc_id, exc_info=True)
+
+    title = _title_for_turn(turn)
+    content = _format_markdown(turn, title)
+    try:
+        remote_doc = await client.create_manual_document(
+            str(kb["weknora_id"]),
+            title=title,
+            content=content,
+        )
+    except WeKnoraError:
+        logger.warning("Failed to create conversation deposit document", exc_info=True)
+        return
+
+    await store.upsert_conversation_deposit(
+        thread_id=turn.thread_id,
+        human_message_id=turn.human_message_id,
+        assistant_message_id=turn.assistant_message_id,
+        knowledge_base_mapping_id=str(kb["id"]),
+        weknora_knowledge_id=str(remote_doc.get("id") or remote_doc.get("knowledge_id") or ""),
+        title=title,
+        created_by_user_id=turn.created_by_user_id,
+    )
+
+
+async def delete_conversation_deposit_documents(
+    app: Any,
+    *,
+    thread_id: str,
+    message_ids: list[str] | None = None,
+) -> None:
+    store = _store(app)
+    client = _client(app)
+    if store is None or client is None:
+        return
+    try:
+        rows = await store.delete_conversation_deposits(thread_id=thread_id, message_ids=message_ids)
+    except Exception:
+        logger.debug("Failed to delete local conversation deposit rows", exc_info=True)
+        return
+    for row in rows:
+        doc_id = str(row.get("weknora_knowledge_id") or "")
+        if not doc_id:
+            continue
+        try:
+            await client.delete_document(doc_id)
+        except WeKnoraError as exc:
+            if exc.status_code != 404:
+                logger.warning("Failed to delete WeKnora conversation deposit document %s", doc_id, exc_info=True)

offline-backend-20260512/backend/app/gateway/llmwiki_rag.py

@@ -0,0 +1,290 @@
+"""LLMWiki retrieval helpers for normal DeerFlow chat runs.
+
+The public chat API accepts DeerFlow-local LLMWiki knowledge-base mapping ids.
+When WeKnora mode is enabled, this module resolves those local ids under the
+current DeerFlow user's permissions, searches WeKnora once before the model
+call, and attaches both:
+
+* a hidden prompt with numbered context snippets, and
+* structured citation sources for the existing reference panel.
+
+The helper lives in ``app.gateway`` because it needs Gateway auth state and the
+DeerFlow-owned mapping store.  Harness code remains app-import free.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode
+
+from fastapi import HTTPException, Request
+from langchain_core.messages import HumanMessage
+
+from app.gateway.deps import get_optional_user_from_request
+from app.gateway.utils import sanitize_log_param
+from deerflow.config.agents_config import load_agent_config, validate_agent_id
+from deerflow.integrations.weknora.client import WeKnoraError
+from deerflow.integrations.weknora.runtime import build_weknora_client, get_resolved_llmwiki_runtime
+from deerflow.persistence.llmwiki import LlmWikiStore
+from deerflow.runtime.user_context import get_effective_user_id
+
+logger = logging.getLogger(__name__)
+
+_MAX_SOURCES = 8
+_MAX_SOURCE_CHARS = 1400
+
+
+@dataclass(frozen=True)
+class LlmWikiRagContext:
+    knowledge_base_ids: list[str]
+    source_count: int
+    prompt: str
+    sources: list[dict[str, Any]]
+    query: str
+
+
+def _store(request: Request) -> LlmWikiStore | None:
+    return getattr(request.app.state, "llmwiki_store", None)
+
+
+async def _actor(request: Request) -> tuple[str, bool]:
+    user = await get_optional_user_from_request(request)
+    if user is None:
+        return get_effective_user_id(), True
+    return str(user.id), getattr(user, "system_role", None) == "admin"
+
+
+def _as_id_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        parts = [value]
+    elif isinstance(value, (list, tuple, set)):
+        parts = list(value)
+    else:
+        return []
+    return list(dict.fromkeys(str(item).strip() for item in parts if str(item).strip()))
+
+
+def _body_selected_ids(body: Any) -> list[str]:
+    for source in (getattr(body, "context", None), getattr(body, "metadata", None)):
+        if isinstance(source, Mapping) and "llmwiki_knowledge_base_ids" in source:
+            return _as_id_list(source.get("llmwiki_knowledge_base_ids"))
+    return []
+
+
+def _assistant_agent_id(body: Any) -> str | None:
+    assistant_id = validate_agent_id(getattr(body, "assistant_id", None))
+    if assistant_id:
+        return assistant_id
+    context = getattr(body, "context", None)
+    if isinstance(context, Mapping):
+        return validate_agent_id(str(context.get("agent_id") or "")) if context.get("agent_id") else None
+    metadata = getattr(body, "metadata", None)
+    if isinstance(metadata, Mapping):
+        return validate_agent_id(str(metadata.get("agent_id") or "")) if metadata.get("agent_id") else None
+    return None
+
+
+def _agent_bound_ids(body: Any) -> list[str]:
+    agent_id = _assistant_agent_id(body)
+    if not agent_id:
+        return []
+    try:
+        config = load_agent_config(agent_id)
+    except (FileNotFoundError, ValueError):
+        return []
+    return _as_id_list(config.llmwiki_knowledge_base_ids if config else None)
+
+
+def resolve_requested_llmwiki_knowledge_base_ids(body: Any) -> list[str]:
+    """Return selected ids plus custom-agent defaults, de-duplicated in order."""
+
+    return list(dict.fromkeys([*_agent_bound_ids(body), *_body_selected_ids(body)]))
+
+
+def llmwiki_selection_requested(body: Any) -> bool:
+    return bool(resolve_requested_llmwiki_knowledge_base_ids(body))
+
+
+def _latest_human_query(graph_input: dict[str, Any]) -> str:
+    messages = graph_input.get("messages")
+    if not isinstance(messages, list):
+        return ""
+    for message in reversed(messages):
+        if isinstance(message, HumanMessage):
+            return _message_text(getattr(message, "content", ""))
+        if isinstance(message, dict) and str(message.get("type") or message.get("role") or "") in {"human", "user"}:
+            return _message_text(message.get("content"))
+    return ""
+
+
+def _message_text(content: Any) -> str:
+    if isinstance(content, str):
+        return content.strip()
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, Mapping):
+                text = item.get("text") or item.get("content")
+                if isinstance(text, str):
+                    parts.append(text)
+        return "\n".join(part.strip() for part in parts if part and part.strip()).strip()
+    return str(content or "").strip()
+
+
+def _truncate(text: str, max_chars: int) -> str:
+    value = text.strip()
+    if len(value) <= max_chars:
+        return value
+    return f"{value[: max_chars - 1].rstrip()}…"
+
+
+def _source_from_result(result: dict[str, Any], mapping: dict[str, Any], index: int) -> dict[str, Any]:
+    chunk_id = str(result.get("chunk_id") or "")
+    title = str(result.get("title") or result.get("filename") or mapping.get("name") or f"LLMWiki 片段 {index}")
+    content = str(result.get("content") or "")
+    params = urlencode({"knowledge_base_id": mapping["id"], "chunk_id": chunk_id})
+    raw = {
+        **result,
+        "knowledge_base_id": mapping["id"],
+        "knowledge_base_name": mapping.get("name") or "",
+        "source": mapping.get("name") or "LLMWiki",
+        "url": f"/weknora-source-preview?{params}",
+    }
+    return {
+        "index": index,
+        "id": chunk_id or str(result.get("knowledge_id") or f"{mapping['id']}:{index}"),
+        "title": title,
+        "type": "llmwiki",
+        "snippet": _truncate(content, 360),
+        "content": content,
+        "source": mapping.get("name") or "LLMWiki",
+        "score": float(result.get("score") or 0),
+        "url": f"/weknora-source-preview?{params}",
+        "skillName": "llmwiki_search",
+        "mode": "citation",
+        "raw": raw,
+    }
+
+
+def _build_prompt(query: str, sources: list[dict[str, Any]]) -> str:
+    if not sources:
+        return (
+            "当前用户选择了 LLMWiki 知识库，但 DeerFlow 未检索到可用片段。"
+            "请直接说明没有检索到可用背景资料，不要编造知识库内容或引用编号。"
+        )
+
+    lines = [
+        "当前用户选择了 LLMWiki 知识库。DeerFlow 已在模型回答前自动检索到以下背景资料。",
+        "请优先依据这些资料回答；如果资料不足，请明确说明不足之处，不要编造。",
+        "引用规则：正文关键结论必须使用 [1]、[2] 这样的编号引用下方资料；只能引用存在的编号；不要在正文末尾重复输出完整参考文献列表，前端会展示引用卡片。",
+        "",
+        f"用户问题：{query}",
+        "",
+        f"<llmwiki_reference_batch source_count=\"{len(sources)}\">",
+    ]
+    for source in sources:
+        meta = " / ".join(
+            str(item)
+            for item in (
+                source.get("source"),
+                f"score={source.get('score'):.4f}" if isinstance(source.get("score"), float) else None,
+            )
+            if item
+        )
+        lines.append(f"[{source['index']}] {source.get('title') or 'LLMWiki 片段'}")
+        if meta:
+            lines.append(f"来源：{meta}")
+        lines.append(_truncate(str(source.get("content") or source.get("snippet") or ""), _MAX_SOURCE_CHARS))
+        lines.append("")
+    lines.append("</llmwiki_reference_batch>")
+    return "\n".join(lines).strip()
+
+
+async def build_llmwiki_rag_context(
+    *,
+    request: Request,
+    body: Any,
+    graph_input: dict[str, Any],
+) -> LlmWikiRagContext:
+    selected_ids = resolve_requested_llmwiki_knowledge_base_ids(body)
+    if not selected_ids:
+        return LlmWikiRagContext([], 0, "", [], "")
+
+    runtime = get_resolved_llmwiki_runtime(getattr(request.app.state, "config", None))
+    if not runtime.weknora_enabled:
+        return LlmWikiRagContext(selected_ids, 0, "", [], "")
+    store = _store(request)
+    if store is None:
+        return LlmWikiRagContext(selected_ids, 0, "", [], "")
+
+    query = _latest_human_query(graph_input)
+    if not query:
+        return LlmWikiRagContext(selected_ids, 0, "", [], "")
+
+    user_id, is_admin = await _actor(request)
+    rows: list[dict[str, Any]] = []
+    for mapping_id in selected_ids:
+        row = await store.get_authorized(mapping_id, user_id, write=False, is_admin=is_admin)
+        if row is None:
+            raise HTTPException(status_code=404, detail=f"Knowledge base {mapping_id} not found")
+        rows.append(row)
+    remote_to_local = {str(row["weknora_id"]): row for row in rows}
+
+    try:
+        results = await build_weknora_client(runtime).search(query, [str(row["weknora_id"]) for row in rows])
+    except WeKnoraError as exc:
+        logger.warning(
+            "LLMWiki pre-retrieval failed for user=%s kb_count=%s: %s",
+            sanitize_log_param(user_id),
+            len(rows),
+            exc,
+        )
+        return LlmWikiRagContext(
+            selected_ids,
+            0,
+            f"当前用户选择了 LLMWiki 知识库，但自动检索失败：{exc}。请说明暂时无法检索知识库背景资料，不要编造引用。",
+            [],
+            query,
+        )
+
+    sources: list[dict[str, Any]] = []
+    for result in results:
+        mapping = remote_to_local.get(str(result.get("knowledge_base_id") or ""))
+        if mapping is None or not str(result.get("content") or "").strip():
+            continue
+        sources.append(_source_from_result(result, mapping, len(sources) + 1))
+        if len(sources) >= _MAX_SOURCES:
+            break
+    return LlmWikiRagContext(selected_ids, len(sources), _build_prompt(query, sources), sources, query)
+
+
+def attach_llmwiki_rag_to_graph_input(
+    graph_input: dict[str, Any],
+    rag: LlmWikiRagContext,
+) -> dict[str, Any]:
+    if not rag.prompt and not rag.sources:
+        return graph_input
+    messages = graph_input.get("messages")
+    if not isinstance(messages, list) or not messages:
+        return graph_input
+    new_messages = list(messages)
+    for index, message in enumerate(new_messages):
+        if not isinstance(message, HumanMessage):
+            continue
+        extra = dict(getattr(message, "additional_kwargs", None) or {})
+        existing = str(extra.get("prompt_prefix") or "").strip()
+        extra["prompt_prefix"] = f"{existing}\n\n{rag.prompt}".strip() if existing else rag.prompt
+        extra["llmwiki_knowledge_base_ids"] = rag.knowledge_base_ids
+        extra["llmwiki_reference_query"] = rag.query
+        if rag.sources:
+            extra["llmwiki_reference_sources"] = rag.sources
+        new_messages[index] = message.model_copy(update={"additional_kwargs": extra})
+        break
+    return {**graph_input, "messages": new_messages}

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed.py

@@ -30,7 +30,9 @@ Python 三引号字符串,导致「磁盘上的验证版」与「代码里的内
 
 > ⚠️ 维护提示:资源文件(``_roundtable_seed_assets/``)是**发布默认值**的唯一可信源。
 > 线上调优后,请把改动写回对应的资源 .md,否则下次新机器补建出来的还是旧版。
-> ``_ensure_one`` 只在目录缺失时复制,**不覆盖**已存在目录(尊重运维现场手改)。
+> ``_ensure_one`` 通常只在目录缺失时复制,**不覆盖**已存在目录(尊重运维现场手改)。
+> 例外是 position intent 的实现契约刷新，以及行动规划智能体新增平台自带 Skill 时的
+> ``skills`` 列表合并；后者不会覆盖已编辑的 SOUL 或既有 Skill。
 
 为什么 ``roundtable-coordinator`` 是单例而不是每次会话新建
 ------------------------------------------------------------
@@ -52,12 +54,18 @@ import logging
 from collections.abc import Iterable
 from pathlib import Path
 
+import yaml
+
 from deerflow.config.paths import get_paths
 
 logger = logging.getLogger(__name__)
 
 
 INTENT_AGENT_ID = "roundtable-intent"
+# Position roundtable deliberately owns a separate intent agent.  Its dialogue
+# lifecycle is shared with Step 1 above, but its final structured hand-off is
+# different and must not change the multi-agent roundtable contract.
+POSITION_INTENT_AGENT_ID = "position-roundtable-intent"
 RECOMMENDER_AGENT_ID = "roundtable-recommender"
 COORDINATOR_AGENT_ID = "roundtable-coordinator"
 # Step 3「结果绘制」用的方案可视化总结智能体:读各席位交付 + 共识,画自包含图表 HTML。
@@ -92,6 +100,7 @@ _ASSETS_DIR = Path(__file__).parent / "_roundtable_seed_assets"
 # roundtable-dashboard 支撑 Step 3 大屏多页结构化数据(report-json + 问答/增量改)。
 _FUNCTIONAL_AGENT_IDS: tuple[str, ...] = (
     INTENT_AGENT_ID,
+    POSITION_INTENT_AGENT_ID,
     RECOMMENDER_AGENT_ID,
     COORDINATOR_AGENT_ID,
     REPORT_AGENT_ID,
@@ -103,20 +112,61 @@ _FUNCTIONAL_AGENT_IDS: tuple[str, ...] = (
 
 # seeder 会复制资源目录里的这些文件(存在即复制,缺失则跳过)。
 _SEED_FILES: tuple[str, ...] = ("config.yaml", "SOUL.md")
+_ACTION_PLAN_SKILL = "position-roundtable-action-create"
+
+
+def _ensure_action_plan_skill(agent_dir: Path) -> bool:
+    """Merge the owned batch-create Skill into an existing action planner.
+
+    The planner SOUL remains editable in the agent configuration drawer and is
+    therefore never overwritten here. The skill binding, however, is a runtime
+    integration contract: without it an already-deployed planner cannot read
+    the new SKILL.md or invoke the batch API script after a code upgrade.
+    """
+    config_path = agent_dir / "config.yaml"
+    try:
+        config = yaml.safe_load(config_path.read_text(encoding="utf-8")) if config_path.exists() else {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("Unable to read action planner config for skill binding: %s", config_path)
+        return False
+    if not isinstance(config, dict):
+        logger.warning("Action planner config is not a mapping; skip skill binding: %s", config_path)
+        return False
+    skills = config.get("skills")
+    if skills is None:
+        normalized: list[str] = []
+    elif isinstance(skills, list):
+        normalized = [str(name).strip() for name in skills if str(name).strip()]
+    else:
+        logger.warning("Action planner skills is not a list; skip skill binding: %s", config_path)
+        return False
+    if _ACTION_PLAN_SKILL in normalized:
+        return False
+
+    config["skills"] = [*normalized, _ACTION_PLAN_SKILL]
+    try:
+        config_path.write_text(
+            yaml.safe_dump(config, allow_unicode=True, sort_keys=False),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.warning("Unable to write action planner skill binding: %s", config_path)
+        return False
+    return True
 
 
 def _ensure_one(agent_id: str) -> bool:
     """Copy the verified SOUL.md + config.yaml for one functional agent into
     ``.deer-flow/agents/<id>/`` if that directory is missing.
 
-    Returns True if the files were just created, False if the directory already
-    existed (we never overwrite — respect any local edits) or the seed assets
-    are missing.
-    """
-    agent_dir = get_paths().agent_dir(agent_id)
-    if agent_dir.exists():
-        return False
+    The position-roundtable intent agent is an implementation-owned compatibility
+    contract: unlike user-managed agents, its schema must stay aligned with the
+    position workspace. Its two seed files are therefore refreshed when they
+    differ, so a previously seeded incorrect prompt is repaired after deployment.
 
+    Returns True if files were created or refreshed, False if no work was needed
+    or the seed assets are missing.
+    """
     src_dir = _ASSETS_DIR / agent_id
     if not src_dir.is_dir():
         # Assets should always ship with the code; if they don't, surface a loud
@@ -128,6 +178,27 @@ def _ensure_one(agent_id: str) -> bool:
         )
         return False
 
+    agent_dir = get_paths().agent_dir(agent_id)
+    if agent_dir.exists():
+        if agent_id == ACTION_PLAN_AGENT_ID:
+            return _ensure_action_plan_skill(agent_dir)
+        if agent_id != POSITION_INTENT_AGENT_ID:
+            # Other built-in agents may have been tuned on a deployed machine;
+            # preserve the long-standing no-overwrite behavior for them.
+            return False
+
+        refreshed = False
+        for fname in _SEED_FILES:
+            src = src_dir / fname
+            if not src.exists():
+                continue
+            target = agent_dir / fname
+            source_bytes = src.read_bytes()
+            if not target.exists() or target.read_bytes() != source_bytes:
+                target.write_bytes(source_bytes)
+                refreshed = True
+        return refreshed
+
     agent_dir.mkdir(parents=True, exist_ok=True)
     for fname in _SEED_FILES:
         src = src_dir / fname
@@ -138,9 +209,9 @@ def _ensure_one(agent_id: str) -> bool:
 
 
 def ensure_roundtable_functional_agents() -> list[str]:
-    """Seed the three roundtable functional agents (``roundtable-intent`` /
-    ``roundtable-recommender`` / ``roundtable-coordinator``) if their on-disk
-    directories are missing. Idempotent — fast no-op when all exist.
+    """Seed the built-in roundtable functional agents when their on-disk
+    directories are missing, and refresh the implementation-owned position
+    intent schema when it has changed. Idempotent after synchronization.
 
     Called from the startup lifespan and from the entry of intent/init,
     intent/stream, recommend/stream, and multi_agent/init so the routes

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/position-action-planner/SOUL.md

@@ -26,23 +26,29 @@
 
 ```json
 {
-  "id": "subtask-001",
-  "title": "简短任务名称",
-  "goal": "任务目标",
-  "basis": ["方案总结章节或岗位交付依据"],
-  "owner_position": "建议责任岗位",
-  "dependencies": ["前置子任务 id"],
-  "deliverable": "可核验交付物",
-  "acceptance_criteria": ["验收条件"],
-  "priority": "P0"
+  "actionName": "行动名称",
+  "actionDescription": "行动描述",
+  "actionType": 0,
+  "publishChannel": 0,
+  "infoFormat": 0,
+  "responsiblePosition": 0,
+  "startTime": "",
+  "endTime": "",
+  "taskId": 0
 }
 ```
 
-`priority` 仅使用 `P0`、`P1`、`P2`。`dependencies` 没有前置时使用空数组。不要输出注释、尾逗号或额外字段来替代这些必填字段。
+`actionType`、`publishChannel`、`infoFormat`、`responsiblePosition` 必须从隐藏上下文传入的对应字典选择，并将该项 `dictValue` 写为整数。`taskId` 必须等于隐藏上下文中前端传入的任务 ID。不要输出注释、尾逗号、旧的 `id/title/goal/basis` 等字段，不能用 0 或空值代替未选择的字典项。
+
+## 行动批量新增
+
+首次生成完整行动清单后：仅当隐藏上下文的 `taskId` 是正整数且四类字典（发布渠道、行动类型、信息形式、责任岗位）均完整时，必须先用 `read_file` 读取 `position-roundtable-action-create` Skill 的 `SKILL.md` 全文，再按其说明调用脚本批量新增行动。若 taskId 为本地演示标识/为空，或字典接口未就绪，只生成报告与 JSON；枚举字段可暂填 `0` 占位，并明确说明未调用外部任务系统。不得逐条调用旧的 `/task/action/add`，也不得自行用 curl 或 requests 替代脚本。
+
+脚本成功时才可以说明行动已入库；脚本失败时如实报告失败原因。相同任务、相同行动清单会由脚本自动幂等跳过。已经成功新增后，如用户要求修改行动，先重写 Markdown 和 JSON；因为当前没有删除/更新行动接口，只有用户明确说“确认新增行动”或“重新批量新增”时才可以按 Skill 使用 `--force` 再次新增，并需提示重复风险。
 
 ## 边界
 
 - 只依据用户消息中提供的任务信息、意图、方案总结和岗位交付。
-- 不调用联网、派活、澄清、展示文件等工具。
+- 不调用联网、派活、澄清、展示文件等工具；仅可为行动批量新增按专属 Skill 使用 `read_file` 与 `bash`。
 - 不删除或修改上游岗位产物。
 - 不在报告中添加“AI 生成”类水印。

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/position-action-planner/config.yaml

@@ -1,3 +1,5 @@
 id: position-action-planner
 name: 行动规划智能体
 description: 岗位会商内置行动规划智能体，基于已生效的方案总结与岗位交付，生成可执行的 Markdown 行动规划报告和结构化子任务清单。
+skills:
+  - position-roundtable-action-create

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/position-roundtable-intent/SOUL.md

@@ -0,0 +1,145 @@
+# 岗位会商任务意图理解智能体
+
+你是岗位多智能体会商 Step 1 的“意图理解专员”。你的唯一职责是把用户输入背后的任务意图结构化后交给后续岗位业务链处理。
+
+你不写报告、不答题、不创作、不规划、不执行、不调用任何操作工具。这些都是后续岗位业务链的事。你只负责听懂、整理、澄清和交接。
+
+---
+
+## 0. 四条不可违背的硬规则
+
+### 硬规则 1 · 不替代后续岗位干活
+
+无论用户让你“写报告 / 写代码 / 写诗 / 查资料 / 做规划 / 出方案”，你都不要直接产出具体内容。
+
+- 正确做法：把诉求结构化成任务意图，输出 [INTENT_READY]，交给后续岗位业务链。
+- 错误做法：用户说“帮我写一份市场分析报告”后，开始写报告正文。
+
+### 硬规则 2 · 最多 5 轮用户协助，确认完整后才收敛
+
+一次“同一轮中调用一个或多个 ask_clarification + 用户统一回答”算一轮用户协助。
+
+- 首轮：若任务卡和用户输入已经足以形成可执行的四项意图，可直接输出 [INTENT_READY]。
+- 第 1 至第 5 轮用户协助：若信息不足，必须发起用户协助；不能把“主题已识别”误判为“意图已明确”。
+- 同一轮可发起多张用户协助卡：一个相互独立的决策点对应一次 ask_clarification 调用和一张卡。不得把多个问题塞进一张卡；用户可逐卡选择后一次性提交。
+- 第 5 次协助应覆盖所有剩余关键项。收到该轮回答后，必须基于明确答案收敛为最终意图。
+- 绝不进入第 6 次用户协助。系统会在达到上限后移除 ask_clarification。
+
+### 硬规则 3 · 输出 [INTENT_READY] 后立刻闭嘴
+
+最终 JSON 代码块闭合后，禁止再输出任何字符：不继续解释、不问“还需要补充吗”、不调用工具、不复述、不展望。
+
+### 硬规则 4 · 只做理解和澄清，不当守门员
+
+这是内网任务分析场景。无论用户提出什么要求，你都不拒绝、不评价、不设限；只负责理解并交接。风险、依赖、信息缺口可以作为风险提示记录，但不构成拒绝或中断。不得说“不能帮你”“不在职责范围内”“请换一个问题”，也不得进行合规、价值或敏感性审查。
+
+---
+
+## 1. 任务意图字段定义
+
+最终结构必须包含以下四个字段，且都必须是字符串数组：
+
+| 字段 | 含义 | 填写原则 |
+| --- | --- | --- |
+| coreGoals | 用户想实现或想获得的核心结果 | 将原本的一句话任务目标拆为 1 个或多个清晰目标 |
+| riskWarnings | 已知风险、依赖或执行风险 | 必须分析任务级风险；范围、地区、周期、数据来源、对象或决策用途缺失时，应先通过用户协助确认，最终结果不得保留待确认表述 |
+| keyPoints | 范围、对象、优先级、时间、资源、交付形式等关键要点 | 仅汇总用户已明确的事实与结论，最终结果不得保留待确认项 |
+| strategicSignificance | 任务对后续岗位协同、业务链或决策推进的意义 | 必须分析该任务将支撑哪类后续决策、业务链协同或资源投入；可以作出任务级合理推断，但不得虚构组织现状或业务数据 |
+
+核心原则：
+
+- 用户已给出任务目标、范围、用途和约束时，直接汇总，不要追问。
+- “只给出一个主题或一句极短诉求”不等于任务意图完整。任何任务若缺少范围、对象、时间、决策用途、重点维度或成功标准等关键信息时，必须请求用户协助。
+- 同一轮应识别所有仍会影响后续业务链的关键缺口，并为每个相互独立的缺口各调用一次 ask_clarification，避免一个问题一轮地消耗用户；不要把它们合并为一张多题卡。
+- 最终 [INTENT_READY] 中禁止出现“待确认”“未明确”“需补充”“暂无”“缺少”等未完成表述；信息不足时继续协助，不得提前交接。
+- 空数组只适用于用户明确说明“不涉及/没有”这一项时。
+
+---
+
+## 2. 工作流
+
+~~~
+用户输入
+   ↓
+是否能形成可执行的四项意图？
+   ├─ 能 → 立即输出 [INTENT_READY]，结束
+   └─ 不能 → 同一轮可分别调多个 ask_clarification（每张卡只问一个决策点）
+              ↓
+        用户回答 → 再判断
+              ↓
+        最多 5 轮用户协助 → 收到明确答案后输出 [INTENT_READY]
+~~~
+
+### 提问前自检清单
+
+任一项为“否”，就应发起用户协助；同轮把全部为“否”的独立决策点分别做成卡片：
+
+1. 我是否不仅能写出核心目标，也能明确主要分析范围或决策用途？
+2. 我是否能基于任务给出至少一项任务级风险提示和战略意义？
+3. 用户是否已经在任务卡、当前消息或历史消息中给出这些关键信息？
+4. 这些缺口是否已经在本轮协助中一次性列出？
+5. 是否已达到第 5 次用户协助？若是，等待用户对最后一组问题的回答，不再发起第 6 次协助。
+
+---
+
+## 3. 唯一允许的工具：ask_clarification
+
+除 ask_clarification 外，禁止调用任何工具、技能或操作。尤其禁止搜索、写文件、读写沙箱、展示文件、创建任务、编排智能体或生成交付物。
+
+当任务只有主题、或缺少决定范围/用途/风险判断的关键信息时，必须调用它。每个协助问题只包含一个决策点；同一轮需要确认多个点时，连续调用多次工具，生成多张独立选择卡：
+
+~~~
+ask_clarification(
+  question="本次分析主要面向哪个范围？",
+  clarification_type="analysis_scope",
+  context="范围会决定后续岗位的分析边界",
+  options=["选项 A", "选项 B", "其他，我补充说明"],
+  allow_multiple=False
+)
+~~~
+
+若还需要确认交付用途、时间边界、对象、风险限制等，必须在同一次回复中继续分别调用 ask_clarification，而不是将它们写进上面这张卡。不得重复询问用户已经回答过的问题。
+
+---
+
+## 4. 结束协议：[INTENT_READY]
+
+可以收敛时，先用 1–2 句话、30 字以内复述理解，然后严格以 JSON 代码块结束。JSON 代码块后不得有任何内容。
+
+输出示例的文本顺序必须是：
+
+~~~
+✅ 我理解的任务是：<一句话复述>
+
+[INTENT_READY]
+JSON 代码块（语言标识 json）：
+{
+  "coreGoals": ["..."],
+  "riskWarnings": [],
+  "keyPoints": ["..."],
+  "strategicSignificance": []
+}
+~~~
+
+格式要求：
+
+- [INTENT_READY] 单独成行。
+- [INTENT_READY] 后紧跟语言标识为 json 的 Markdown 代码块，包裹合法 JSON 对象。
+- 四个字段名称必须严格为 coreGoals / riskWarnings / keyPoints / strategicSignificance。
+- 四个字段必须都是字符串数组；除用户明确说明不涉及外，不要输出空数组。
+- 输出前逐项检查：四个数组中不得出现“待确认”“未明确”“需补充”“暂无”“缺少”等词语。
+- JSON 必须严格合法：英文双引号、无注释、无尾随逗号；字符串中不可直接换行。
+- JSON 代码块闭合后，禁止再写任何字符。
+- 不得输出旧字段 objective、constraints、assumptions。
+
+---
+
+## 5. 禁止事项
+
+- 禁止直接产出报告、代码、诗、方案、分析或任何交付物。
+- 禁止调用任何非 ask_clarification 的工具。
+- 禁止第 5 次用户协助后再发起第 6 次协助。
+- 禁止重复询问用户已回答的问题。
+- 禁止拒绝用户、要求用户换问题或以风险为由中断。
+- 禁止编造外部事实、组织现状或业务数据；信息缺口必须在用户协助阶段确认，最终只输出明确的执行风险和战略意义。
+- 禁止在 [INTENT_READY] 后再输出一个字。

offline-backend-20260512/backend/app/gateway/routers/_roundtable_seed_assets/position-roundtable-intent/config.yaml

@@ -0,0 +1,3 @@
+id: position-roundtable-intent
+name: 岗位会商任务意图理解
+description: 岗位会商专用的任务意图理解智能体。通过必要的简短追问，将任务整理为核心目标、风险提示、关键要点与战略意义，供后续岗位业务链执行。

offline-backend-20260512/backend/app/gateway/routers/agents.py

@@ -64,10 +64,15 @@ class AgentResponse(BaseModel):
         description="入库模板名 (external knowledge-ingest templateName). When set, markdown artifacts produced in this agent's chats can be published to the external knowledge-ingest API.",
     )
 
-    seat_skill_directive: bool | None = Field(
+    seat_skill_directive: bool | None = Field(
         default=None,
         description="会商席位「技能识别强化」开关 (config.yaml). True = 本智能体作为会商席位时强化技能识别 (与业务链条同名开关取 OR). None/False = 关 (默认).",
-    )
+    )
+
+    llmwiki_knowledge_base_ids: list[str] | None = Field(
+        default=None,
+        description="DeerFlow LLMWiki mapping ids this agent may offer for conversation retrieval.",
+    )
 
     tags: list[dict] = Field(default_factory=list, description="Tags assigned to this agent")
 
@@ -120,7 +125,12 @@ class AgentCreateRequest(BaseModel):
     tool_groups: list[str] | None = Field(default=None, description="Optional tool group whitelist persisted to config.yaml")
     common_questions: list[CommonQuestion] | None = Field(default=None, description="Recommended questions (常用问题) persisted to config.yaml. Each item is {title, prompt}; legacy strings are coerced.")
     template_name: str | None = Field(default=None, description="入库模板名 persisted to config.yaml. Enables publishing markdown artifacts to the external knowledge-ingest API.")
-    seat_skill_directive: bool | None = Field(default=None, description="会商席位「技能识别强化」开关 persisted to config.yaml. None/False = off (默认).")
+    seat_skill_directive: bool | None = Field(default=None, description="会商席位「技能识别强化」开关 persisted to config.yaml. None/False = off (默认).")
+    llmwiki_knowledge_base_ids: list[str] | None = Field(
+        default=None,
+        max_length=100,
+        description="Allowed DeerFlow LLMWiki mapping ids persisted to config.yaml.",
+    )
 
 
 class AgentUpdateRequest(BaseModel):
@@ -137,7 +147,12 @@ class AgentUpdateRequest(BaseModel):
     tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist (config.yaml)")
     common_questions: list[CommonQuestion] | None = Field(default=None, description="Updated recommended questions (常用问题, config.yaml). Each item is {title, prompt}; legacy strings are coerced.")
     template_name: str | None = Field(default=None, description="Updated 入库模板名 (config.yaml). Empty string clears it.")
-    seat_skill_directive: bool | None = Field(default=None, description="Updated 会商席位「技能识别强化」开关 (config.yaml).")
+    seat_skill_directive: bool | None = Field(default=None, description="Updated 会商席位「技能识别强化」开关 (config.yaml).")
+    llmwiki_knowledge_base_ids: list[str] | None = Field(
+        default=None,
+        max_length=100,
+        description="Updated allowed DeerFlow LLMWiki mapping ids (config.yaml).",
+    )
 
 
 class AgentSelectorResponse(BaseModel):
@@ -178,10 +193,38 @@ def _current_user_id(request: Request) -> str:
     return get_effective_user_id()
 
 
-def _is_admin_user(request: Request) -> bool:
+def _is_admin_user(request: Request) -> bool:
     """Return True when the request is authenticated as a system admin."""
     user = getattr(request.state, "user", None)
-    return getattr(user, "system_role", None) == "admin"
+    return getattr(user, "system_role", None) == "admin"
+
+
+async def _validate_llmwiki_bindings(
+    request: Request,
+    mapping_ids: list[str] | None,
+) -> list[str] | None:
+    """Normalize bindings and require read access for the editing actor."""
+
+    if mapping_ids is None:
+        return None
+    normalized = list(dict.fromkeys(item.strip() for item in mapping_ids if item.strip()))
+    if not normalized:
+        return []
+    store = getattr(request.app.state, "llmwiki_store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="LLMWiki metadata store is unavailable")
+    user_id = _current_user_id(request)
+    is_admin = _is_admin_user(request)
+    for mapping_id in normalized:
+        row = await store.get_authorized(
+            mapping_id,
+            user_id,
+            write=False,
+            is_admin=is_admin,
+        )
+        if row is None:
+            raise HTTPException(status_code=422, detail=f"LLMWiki knowledge base '{mapping_id}' is unavailable")
+    return normalized
 
 
 def _email_local_part(email: str | None) -> str | None:
@@ -233,7 +276,7 @@ def _validate_storage_id(agent_id: str) -> str:
         raise HTTPException(status_code=422, detail=str(exc)) from exc
 
 
-def _write_agent_config(
+def _write_agent_config(
     agent_id: str,
     *,
     name: str,
@@ -243,8 +286,9 @@ def _write_agent_config(
     tool_groups: list[str] | None = None,
     common_questions: list[CommonQuestion] | None = None,
     template_name: str | None = None,
-    seat_skill_directive: bool | None = None,
-) -> None:
+    seat_skill_directive: bool | None = None,
+    llmwiki_knowledge_base_ids: list[str] | None = None,
+) -> None:
     agent_dir = get_paths().agent_dir(agent_id)
     agent_dir.mkdir(parents=True, exist_ok=True)
     config_file = agent_dir / "config.yaml"
@@ -273,15 +317,19 @@ def _write_agent_config(
     if template_name is not None and template_name.strip():
         config_data["template_name"] = template_name.strip()
     # 会商席位技能识别强化开关：仅当显式设置时写入（None = 不写, 由 AgentConfig 默认为关）。
-    if seat_skill_directive is not None:
-        config_data["seat_skill_directive"] = bool(seat_skill_directive)
+    if seat_skill_directive is not None:
+        config_data["seat_skill_directive"] = bool(seat_skill_directive)
+    if llmwiki_knowledge_base_ids is not None:
+        config_data["llmwiki_knowledge_base_ids"] = list(
+            dict.fromkeys(item.strip() for item in llmwiki_knowledge_base_ids if item.strip())
+        )
     with open(config_file, "w", encoding="utf-8") as f:
         yaml.dump(config_data, f, default_flow_style=False, allow_unicode=True)
 
 
 def _load_config_extras(agent_id: str) -> dict[str, Any]:
     """Read skills/model/tool_groups/common_questions from the agent's config.yaml, tolerant of missing files."""
-    empty = {"skills": None, "model": None, "tool_groups": None, "common_questions": None, "template_name": None, "seat_skill_directive": None}
+    empty = {"skills": None, "model": None, "tool_groups": None, "common_questions": None, "template_name": None, "seat_skill_directive": None, "llmwiki_knowledge_base_ids": None}
     try:
         cfg = load_agent_config(agent_id)
     except (FileNotFoundError, ValueError):
@@ -294,7 +342,8 @@ def _load_config_extras(agent_id: str) -> dict[str, Any]:
         "tool_groups": cfg.tool_groups,
         "common_questions": cfg.common_questions,
         "template_name": cfg.template_name,
-        "seat_skill_directive": cfg.seat_skill_directive,
+        "seat_skill_directive": cfg.seat_skill_directive,
+        "llmwiki_knowledge_base_ids": cfg.llmwiki_knowledge_base_ids,
     }
 
 
@@ -455,7 +504,7 @@ def _record_to_response(
             can happen lazily when the agent is actually opened.
     """
     soul: str | None = None
-    extras: dict[str, Any] = {"skills": None, "model": None, "tool_groups": None, "common_questions": None, "template_name": None, "seat_skill_directive": None}
+    extras: dict[str, Any] = {"skills": None, "model": None, "tool_groups": None, "common_questions": None, "template_name": None, "seat_skill_directive": None, "llmwiki_knowledge_base_ids": None}
     if include_extras:
         _ensure_agent_dir_from_record(record)
         extras = _load_config_extras(record["id"])
@@ -479,7 +528,8 @@ def _record_to_response(
         skills=extras["skills"],
         common_questions=extras.get("common_questions"),
         template_name=extras.get("template_name"),
-        seat_skill_directive=extras.get("seat_skill_directive"),
+        seat_skill_directive=extras.get("seat_skill_directive"),
+        llmwiki_knowledge_base_ids=extras.get("llmwiki_knowledge_base_ids"),
         featured_order=record.get("featured_order"),
     )
 
@@ -780,7 +830,7 @@ async def get_agent(agent_id: str, request: Request) -> AgentResponse:
     summary="Create Agent",
     description="Create a new user-owned agent. The display name can be Chinese and may duplicate existing names.",
 )
-async def create_agent_endpoint(request: AgentCreateRequest, http_request: Request) -> AgentResponse:
+async def create_agent_endpoint(request: AgentCreateRequest, http_request: Request) -> AgentResponse:
     _require_agents_api_enabled()
     name = _validate_display_name(request.name)
     store = get_agent_store(http_request)
@@ -789,9 +839,13 @@ async def create_agent_endpoint(request: AgentCreateRequest, http_request: Reque
         agent_id = _validate_storage_id(request.id)
         if await store.get_any(agent_id) is not None:
             raise HTTPException(status_code=409, detail=f"Agent id '{agent_id}' already exists")
-    else:
-        agent_id = uuid4().hex
-    agent_dir = get_paths().agent_dir(agent_id)
+    else:
+        agent_id = uuid4().hex
+    agent_dir = get_paths().agent_dir(agent_id)
+    llmwiki_ids = await _validate_llmwiki_bindings(
+        http_request,
+        request.llmwiki_knowledge_base_ids,
+    )
 
     try:
         if agent_dir.exists():
@@ -806,7 +860,8 @@ async def create_agent_endpoint(request: AgentCreateRequest, http_request: Reque
             tool_groups=request.tool_groups,
             common_questions=request.common_questions,
             template_name=request.template_name,
-            seat_skill_directive=request.seat_skill_directive,
+            seat_skill_directive=request.seat_skill_directive,
+            llmwiki_knowledge_base_ids=llmwiki_ids,
         )
         _write_agent_soul(agent_id, request.soul)
 
@@ -887,9 +942,14 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
         next_tool_groups = request.tool_groups if "tool_groups" in fields_set else existing_extras["tool_groups"]
         next_common_questions = request.common_questions if "common_questions" in fields_set else existing_extras["common_questions"]
         next_template_name = request.template_name if "template_name" in fields_set else existing_extras["template_name"]
-        next_seat_skill_directive = request.seat_skill_directive if "seat_skill_directive" in fields_set else existing_extras["seat_skill_directive"]
-
-        config_dirty = bool(update_data) or any(key in fields_set for key in ("skills", "model", "tool_groups", "common_questions", "template_name", "seat_skill_directive"))
+        next_seat_skill_directive = request.seat_skill_directive if "seat_skill_directive" in fields_set else existing_extras["seat_skill_directive"]
+        next_llmwiki_ids = (
+            await _validate_llmwiki_bindings(http_request, request.llmwiki_knowledge_base_ids)
+            if "llmwiki_knowledge_base_ids" in fields_set
+            else existing_extras["llmwiki_knowledge_base_ids"]
+        )
+
+        config_dirty = bool(update_data) or any(key in fields_set for key in ("skills", "model", "tool_groups", "common_questions", "template_name", "seat_skill_directive", "llmwiki_knowledge_base_ids"))
         if config_dirty:
             _write_agent_config(
                 agent_id,
@@ -900,7 +960,8 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
                 tool_groups=next_tool_groups,
                 common_questions=next_common_questions,
                 template_name=next_template_name,
-                seat_skill_directive=next_seat_skill_directive,
+                seat_skill_directive=next_seat_skill_directive,
+                llmwiki_knowledge_base_ids=next_llmwiki_ids,
             )
             # Keep the listing cache in lock-step with config.yaml, but only
             # when the cached fields were actually touched — a partial update

offline-backend-20260512/backend/app/gateway/routers/intent.py

@@ -34,6 +34,7 @@ SSE 协议（与前端 ``streamIntent`` 对齐）
    仅 ``status == "done"`` 时带 ``summary``；澄清时还带
    ``question``、``clarification_type``、``clarification_context``、
    ``options``、``allow_custom``、``allow_multiple``（见 ``resolve_allow_multiple``）。
+   多卡回合还带 ``clarifications`` 完整数组；顶层字段始终镜像第一张卡以兼容旧客户端。
 
 终态判定优先级（实现细节，勿随意调整）
 ------------------------------------
@@ -65,7 +66,10 @@ from app.gateway.roundtable_diag import record_foreground_diag
 
 # 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._roundtable_seed import (
+    POSITION_INTENT_AGENT_ID,
+    ensure_roundtable_functional_agents,
+)
 from app.gateway.routers.multi_agent import (
     _ROUNDTABLE_THREAD_METADATA,
     _auth_headers,
@@ -87,6 +91,7 @@ router = APIRouter(prefix="/api/intent", tags=["intent"])
 
 # 内置 agent 目录名，须与 ``.deer-flow/agents/roundtable-intent/`` 一致。
 INTENT_AGENT_ID = "roundtable-intent"
+_SUPPORTED_INTENT_AGENT_IDS = frozenset({INTENT_AGENT_ID, POSITION_INTENT_AGENT_ID})
 
 # SOUL 规定的交接信号：``[INTENT_READY]`` + markdown json 代码块。
 # group(1) 解析为 IntentSummary；解析失败则继续走澄清/asking 分支。
@@ -96,7 +101,49 @@ _INTENT_READY_PATTERN = re.compile(
 )
 
 
-def _intent_thread_metadata(task_context: dict[str, Any] | None) -> dict[str, Any]:
+def _requested_intent_agent_id(payload: dict[str, Any]) -> str:
+    """Resolve the explicitly supported Step-1 agent without opening a route
+    for arbitrary custom-agent execution.
+
+    Existing multi-agent callers omit the field and therefore keep using
+    ``roundtable-intent``.  Position roundtable sends the dedicated ID so its
+    prompt and final JSON schema remain isolated.
+    """
+    requested = str(payload.get("intent_agent_id") or "").strip()
+    if not requested:
+        return INTENT_AGENT_ID
+    if requested not in _SUPPORTED_INTENT_AGENT_IDS:
+        raise HTTPException(status_code=400, detail="Unsupported intent agent")
+    return requested
+
+
+def _clarification_blocks_ready(
+    intent_agent_id: str,
+    clarification_calls: Any,
+    *,
+    is_fresh: bool,
+) -> bool:
+    """Position intent must wait for a fresh clarification answer.
+
+    The generic Step-1 route intentionally preserves READY-first behavior for
+    stale tool calls in historical snapshots. Position roundtable instead has
+    a four-part hand-off whose missing context is requested interactively, so
+    a newly dispatched clarification is a strict terminal pause. A historical
+    tool call from the preceding user-assistance turn must not block the next
+    user answer from reaching READY.
+    """
+    return (
+        intent_agent_id == POSITION_INTENT_AGENT_ID
+        and bool(clarification_calls)
+        and is_fresh
+    )
+
+
+def _intent_thread_metadata(
+    task_context: dict[str, Any] | None,
+    *,
+    intent_agent_id: str = INTENT_AGENT_ID,
+) -> dict[str, Any]:
     """Build task-scoped metadata for a newly-created intent thread.
 
     Normal roundtable Step 1 calls still use the original system-thread tag.
@@ -122,6 +169,8 @@ def _intent_thread_metadata(task_context: dict[str, Any] | None) -> dict[str, An
             "position_roundtable_phase": "intent",
         }
     )
+    if intent_agent_id == POSITION_INTENT_AGENT_ID:
+        metadata["position_roundtable_intent_agent_id"] = intent_agent_id
     return metadata
 
 
@@ -190,6 +239,32 @@ def _count_past_clarifications(messages: list[dict[str, Any]]) -> int:
     return count
 
 
+def _count_past_clarification_rounds(messages: list[dict[str, Any]]) -> int:
+    """Count completed assistance *rounds*, rather than question cards.
+
+    The generic roundtable agent retains its historic three-tool-call brake.
+    Position roundtable deliberately lets one model turn emit several
+    independent ``ask_clarification`` cards, so using the tool-call count
+    there would accidentally spend all five user-assistance rounds at once.
+    One AI message containing one or more clarification calls is one round.
+    """
+    if not isinstance(messages, list):
+        return 0
+    rounds = 0
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        if (msg.get("type") or "").lower() not in ("ai", "aimessage", "aimessagechunk"):
+            continue
+        if any(
+            (tc.get("name") or "").lower() == "ask_clarification"
+            for tc in msg.get("tool_calls") or []
+            if isinstance(tc, dict)
+        ):
+            rounds += 1
+    return rounds
+
+
 async def _fetch_thread_messages(
     client: httpx.AsyncClient,
     base: str,
@@ -225,8 +300,18 @@ async def _fetch_thread_messages(
 
 
 # 硬上限:超过这个轮数,无论模型怎么想,都强制移除 ask_clarification 工具。
-# 与 SOUL.md §0 「硬规则 2」对齐——"绝不存在第 4 轮"。
+# 通用会商沿用 3 次工具调用的历史保护；岗位会商按"一轮可多张卡"计数，
+# 允许最多 5 次用户协助。
 _MAX_CLARIFICATION_ROUNDS = 3
+_POSITION_MAX_CLARIFICATION_ROUNDS = 5
+
+
+def _max_clarification_rounds(intent_agent_id: str) -> int:
+    return (
+        _POSITION_MAX_CLARIFICATION_ROUNDS
+        if intent_agent_id == POSITION_INTENT_AGENT_ID
+        else _MAX_CLARIFICATION_ROUNDS
+    )
 
 
 def _is_repeated_clarification(
@@ -310,6 +395,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
     # 调用前自检:内网部署 .deer-flow/ 被 gitignore,首次启动时本 agent 目录可能不存在,
     # 缺失则就地用嵌入模板补建,避免下一步 /stream 报 500。
     ensure_roundtable_functional_agents()
+    intent_agent_id = _requested_intent_agent_id(payload)
 
     # Keep Step-1 initialization aligned with multi-agent initialization:
     # create the empty thread in-process rather than looping back through
@@ -321,7 +407,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
     try:
         thread_id = await _create_thread_direct(
             request,
-            metadata=_intent_thread_metadata(task_context),
+            metadata=_intent_thread_metadata(task_context, intent_agent_id=intent_agent_id),
         )
     except HTTPException:
         # 上游已用结构化方式失败,原样传给前端不需要二次包装。
@@ -341,7 +427,7 @@ async def init_intent(request: Request, payload: dict = Body(...)) -> dict[str,
         raise HTTPException(status_code=500, detail=diagnostic) from exc
     return {
         "status": "success",
-        "agent_id": INTENT_AGENT_ID,
+        "agent_id": intent_agent_id,
         "thread_id": thread_id,
     }
 
@@ -363,6 +449,7 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
       }
     """
     thread_id = str(payload.get("thread_id") or "").strip()
+    intent_agent_id = _requested_intent_agent_id(payload)
     message = str(payload.get("message") or "").strip()
     # 不写死任何默认模型名:空串会让 lead_agent._resolve_model_name() 回退到
     # config.yaml 的 models[0],与 /api/ai-writing 等其它路由一致,内网部署只配
@@ -386,21 +473,30 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
 
     base = _loopback_base(request)
     headers = _auth_headers(request)
+    fallback_instruction = (
+        "四个岗位会商字段都必须保留为字符串数组，依据已获得的用户确认形成明确结论，"
+        "不得写待确认、未明确、需补充、暂无或缺少"
+        if intent_agent_id == POSITION_INTENT_AGENT_ID
+        else "缺的字段用 assumptions 兜底"
+    )
 
     async def stream_generator() -> AsyncIterator[str]:
         # ASGITransport：进程内直调本机 ASGI app，**不走 TCP / 不经过网络栈**，
         # 因此既无须 trust_env=False 防代理，也不存在 loopback 40s 超时这种坑。
         async with _make_loopback_client(request) as client:
             try:
-                # —— 3 轮硬上限兜底 ——
-                # 在发起 run 之前先读一次 thread state,数当前 ask_clarification 已发出次数:
-                #   past=0/1 → 正常,不动 message,不动工具白名单
-                #   past=2(本轮即将变成第 3 轮)→ 给消息加前缀,强提示"必须 INTENT_READY"
-                #   past≥3 → 直接把 ask_clarification 也加进 excluded_tools,工具物理消失
-                # 这一步是个"刹车":SOUL 让模型自律,这里让系统兜底。
-                past_clarifications = _count_past_clarifications(
-                    await _fetch_thread_messages(client, base, headers, thread_id)
+                # —— 澄清轮次硬上限兜底 ——
+                # 通用会商保持原来的 3 次 ask 工具调用上限；岗位会商允许一个
+                # AI turn 同时产生多张独立协助卡，所以必须按 AI 消息（一次
+                # "提问 + 用户回答"）计轮，不能按卡片数计轮。
+                past_messages = await _fetch_thread_messages(client, base, headers, thread_id)
+                past_clarifications = _count_past_clarifications(past_messages)
+                past_rounds = (
+                    _count_past_clarification_rounds(past_messages)
+                    if intent_agent_id == POSITION_INTENT_AGENT_ID
+                    else past_clarifications
                 )
+                max_rounds = _max_clarification_rounds(intent_agent_id)
 
                 # 1. ask_clarification 的工具白名单——超过硬上限就移除。
                 base_excluded_tools = [
@@ -420,13 +516,13 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                     "task",
                     "write_todos",
                 ]
-                if past_clarifications >= _MAX_CLARIFICATION_ROUNDS:
+                if past_rounds >= max_rounds:
                     base_excluded_tools.append("ask_clarification")
                     logger.info(
-                        "intent stream: past_clarifications=%d >= %d, force-disabling "
+                        "intent stream: past_rounds=%d >= %d, force-disabling "
                         "ask_clarification to break the loop",
-                        past_clarifications,
-                        _MAX_CLARIFICATION_ROUNDS,
+                        past_rounds,
+                        max_rounds,
                     )
 
                 # 带了上传文件时，解锁「读」类工具（read_file / ls / grep / view_image），
@@ -440,22 +536,42 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                 # 2. message 前缀——给模型一个明确的"本轮必须收敛"信号。
                 # 仅文件、无文本时给一句兜底引导，让模型先读文件再澄清意图。
                 effective_message = message or "我上传了文件，请先阅读文件内容，再据此理解并澄清我的任务意图。"
-                if past_clarifications >= _MAX_CLARIFICATION_ROUNDS:
+                if intent_agent_id == POSITION_INTENT_AGENT_ID and past_rounds < max_rounds:
+                    # The position flow needs an actionable four-part hand-off,
+                    # not merely a recognizable topic. One turn may ask several
+                    # independent decisions, each rendered as its own selection
+                    # card by the existing Step-1 UI.
                     effective_message = (
-                        f"[系统强制] 已澄清 {past_clarifications} 轮,触发硬上限。"
-                        f"本轮请直接输出 [INTENT_READY],缺的字段用 assumptions 兜底,"
+                        "[岗位会商收敛检查] 仅识别出主题不等于意图已明确。"
+                        "若当前任务还无法判断分析范围、决策用途、关键风险或战略意义，"
+                        "请在同一次回复中为每个相互独立的关键缺口分别调用一次 "
+                        "ask_clarification；每个工具调用只能问一个决策点，不能把多项"
+                        "问题合并成一张卡片。用户会一次性回答这些卡片。"
+                        "如果四项意图已经足够明确，则直接输出最终结果。"
+                        "不要以风险提示和战略意义为空的 [INTENT_READY] 结束。"
+                        "本轮是第 %d/%d 轮用户协助；第 %d 轮若仍有缺口，必须把所有"
+                        "剩余关键缺口分别发成卡片，收到回答后立即收敛。\n\n"
+                        f"用户最新输入:{effective_message}"
+                    ) % (past_rounds + 1, max_rounds, max_rounds)
+                if past_rounds >= max_rounds:
+                    effective_message = (
+                        f"[系统强制] 已澄清 {past_rounds} 轮,触发硬上限。"
+                        f"本轮请直接输出 [INTENT_READY],{fallback_instruction},"
                         f"绝对不要再调任何工具,也不要再询问任何问题。\n\n"
                         f"用户最新输入:{message}"
                     )
-                elif past_clarifications >= _MAX_CLARIFICATION_ROUNDS - 1:
+                elif (
+                    intent_agent_id != POSITION_INTENT_AGENT_ID
+                    and past_rounds >= max_rounds - 1
+                ):
                     effective_message = (
-                        f"[系统提示] 已澄清 {past_clarifications} 轮,这是最后一轮。"
-                        f"本轮请直接输出 [INTENT_READY],未明确的字段用 assumptions 兜底。\n\n"
+                        f"[系统提示] 已澄清 {past_rounds} 轮,这是最后一轮。"
+                        f"本轮请直接输出 [INTENT_READY],{fallback_instruction}。\n\n"
                         f"用户最新输入:{message}"
                     )
 
                 body = _run_payload(
-                    agent_name=INTENT_AGENT_ID,
+                    agent_name=intent_agent_id,
                     model_name=model_name,
                     thread_id=thread_id,
                     new_message=effective_message,
@@ -479,6 +595,26 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                         captured = done
 
                 messages = _parse_last_messages(captured)
+                current_rounds = (
+                    _count_past_clarification_rounds(messages)
+                    if intent_agent_id == POSITION_INTENT_AGENT_ID
+                    else _count_past_clarifications(messages)
+                )
+                clarification_is_fresh = current_rounds > past_rounds
+
+                # A position-roundtable clarification is an explicit pause.
+                # Some models emit a premature [INTENT_READY] text after the
+                # tool call in the same upstream run. For this dedicated flow
+                # the fresh clarification must win so the user can answer it;
+                # generic roundtable keeps its historical READY-first order.
+                dispatch_msg = _find_dispatch_message(messages)
+                tool_calls = dispatch_msg.get("tool_calls") or []
+                clarification_calls = [
+                    tc
+                    for tc in tool_calls
+                    if isinstance(tc, dict)
+                    and (tc.get("name") or "").lower() == "ask_clarification"
+                ]
 
                 # --- 终态分支 1：结构化意图已就绪（最高优先级）---
                 # 模型可能在较早的 AIMessage 里已输出 [INTENT_READY]，而最后一轮
@@ -507,7 +643,15 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                         # Step1Panel 已经把 `parts.after` 隐藏掉,体验闭环。
                         ready_text = msg_text[: m.end()].rstrip() + "\n"
                         break
-                if summary and ready_text:
+                if (
+                    summary
+                    and ready_text
+                    and not _clarification_blocks_ready(
+                        intent_agent_id,
+                        clarification_calls,
+                        is_fresh=clarification_is_fresh,
+                    )
+                ):
                     final_frame = {
                         "status": "done",
                         "content": ready_text,
@@ -519,42 +663,49 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                 # --- 终态分支 2：本轮以 ask_clarification 结束 ---
                 # _find_dispatch_message：从后往前找带 tool_calls 的 AIMessage
                 # （SkillStop/澄清 ToolMessage 之后的那条 AI 消息）。
-                dispatch_msg = _find_dispatch_message(messages)
                 content = _flatten_content(dispatch_msg.get("content", ""))
-                tool_calls = dispatch_msg.get("tool_calls") or []
 
-                clarification_call = next(
-                    (tc for tc in tool_calls if (tc.get("name") or "").lower() == "ask_clarification"),
-                    None,
-                )
-                if clarification_call is not None:
-                    cargs = clarification_call.get("args") or {}
-                    question = str(cargs.get("question") or "").strip()
+                if clarification_calls:
                     # ClarificationMiddleware 常在 tool 之后还有一条纯文本 AIMessage，
                     # 比 tool_call 旁的短 preamble 更适合作为气泡正文。
                     follow_up = _find_trailing_ai_text(messages, exclude_text=content)
-                    display_content = follow_up or content or question
-
-                    # 兜底:模型偶尔会复述上一轮的同一澄清问题(SOUL §2.5 prompt
-                    # 已经强约束,但小模型 / 长上下文仍可能漏跟随)。检测到完全
-                    # 重复时,把 status 从 clarification 降级为 asking,前端只渲染
-                    # 文本气泡不弹卡片,避免用户看到"同样选项又出现一次"。
-                    if _is_repeated_clarification(
-                        messages,
-                        new_question=question,
-                        new_options=cargs.get("options"),
-                        new_tool_call_id=clarification_call.get("id"),
-                    ):
-                        logger.warning(
-                            "intent stream: dropping duplicate ask_clarification "
-                            "(question=%r) — already asked & answered earlier in thread",
-                            question[:80],
+                    clarification_payloads: list[dict[str, Any]] = []
+                    for clarification_call in clarification_calls:
+                        cargs = clarification_call.get("args") or {}
+                        question = str(cargs.get("question") or "").strip()
+                        # 逐卡过滤已被用户回答过的重复问题，不能因为其中一张
+                        # 重复卡而吞掉同轮其它有效的协助卡。
+                        if _is_repeated_clarification(
+                            messages,
+                            new_question=question,
+                            new_options=cargs.get("options"),
+                            new_tool_call_id=clarification_call.get("id"),
+                        ):
+                            logger.warning(
+                                "intent stream: dropping duplicate ask_clarification "
+                                "(question=%r) — already asked & answered earlier in thread",
+                                question[:80],
+                            )
+                            continue
+                        clarification_payloads.append(
+                            {
+                                "id": str(clarification_call.get("id") or ""),
+                                "question": question,
+                                "clarification_type": str(cargs.get("clarification_type") or ""),
+                                "clarification_context": str(cargs.get("context") or ""),
+                                "options": cargs.get("options") or [],
+                                "allow_custom": bool(cargs.get("allow_custom", True)),
+                                "allow_multiple": resolve_allow_multiple(cargs),
+                            }
                         )
+
+                    if not clarification_payloads:
                         fallback_msg = (
-                            display_content
+                            follow_up
+                            or content
                             or "(系统识别到智能体重复了上一问题,已自动跳过。请补充其他信息继续推进。)"
                         )
-                        final_frame: dict[str, Any] = {
+                        final_frame = {
                             "status": "asking",
                             "content": fallback_msg,
                             "summary": None,
@@ -562,15 +713,15 @@ async def stream_intent(request: Request, payload: dict = Body(...)) -> Streamin
                         yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"
                         return
 
+                    first = clarification_payloads[0]
+                    display_content = follow_up or content or str(first["question"])
                     final_frame: dict[str, Any] = {
                         "status": "clarification",
                         "content": display_content,
-                        "question": question,
-                        "clarification_type": str(cargs.get("clarification_type") or ""),
-                        "clarification_context": str(cargs.get("context") or ""),
-                        "options": cargs.get("options") or [],
-                        "allow_custom": bool(cargs.get("allow_custom", True)),
-                        "allow_multiple": resolve_allow_multiple(cargs),
+                        # 兼容旧客户端保留首张卡的顶层字段；完整列表使得网络
+                        # 重连、缓存重放等没有实时 tool frame 的路径也能还原多卡。
+                        **first,
+                        "clarifications": clarification_payloads,
                         "summary": None,
                     }
                     yield f"data: {json.dumps(final_frame, ensure_ascii=False)}\n\n"

offline-backend-20260512/backend/app/gateway/routers/model_management.py

@@ -0,0 +1,451 @@
+"""Administrator model configuration backed by DeerFlow's ``config.yaml``.
+
+The public ``/api/models`` endpoint intentionally stays small and never
+returns secrets.  This router is the complementary administrator surface: it
+edits only the top-level ``models:`` section in the active DeerFlow config,
+keeps a disk backup before every write, and swaps the gateway's runtime config
+after validation so new requests can use the change without a restart.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import logging
+import os
+import re
+import shutil
+import tempfile
+from datetime import UTC, datetime
+from pathlib import Path
+from time import perf_counter
+from typing import Any
+
+import yaml
+from fastapi import APIRouter, HTTPException, Request
+from langchain_core.messages import HumanMessage
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.gateway.deps import get_optional_user_from_request
+from deerflow.config.app_config import AppConfig, reload_app_config
+from deerflow.config.model_config import ModelConfig
+from deerflow.models.factory import create_chat_model
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/admin/models", tags=["admin-models"])
+
+_MODEL_BLOCK_RE = re.compile(r"(?m)^models:[^\r\n]*(?:\r?\n|$)")
+_TOP_LEVEL_KEY_RE = re.compile(r"(?m)^[A-Za-z_][A-Za-z0-9_-]*:[^\r\n]*(?:\r?\n|$)")
+_BACKUP_DIR_NAME = ".model-config-backups"
+_MUTATION_LOCK = asyncio.Lock()
+
+_EDITOR_FIELDS = frozenset(
+    {
+        "name",
+        "display_name",
+        "description",
+        "use",
+        "model",
+        "api_key",
+        "base_url",
+        "request_timeout",
+        "max_retries",
+        "max_tokens",
+        "temperature",
+        "stream_usage",
+        "supports_thinking",
+        "supports_reasoning_effort",
+        "supports_vision",
+        "when_thinking_enabled",
+        "when_thinking_disabled",
+        "thinking",
+        "use_responses_api",
+        "output_version",
+    }
+)
+_PRESERVED_FIELDS = frozenset(ModelConfig.model_fields) | _EDITOR_FIELDS
+
+
+class ModelAdminItem(BaseModel):
+    """A model configuration safe to return to an administrator browser."""
+
+    name: str
+    display_name: str | None = None
+    description: str | None = None
+    use: str
+    model: str
+    base_url: str | None = None
+    request_timeout: float | None = None
+    max_retries: int | None = None
+    max_tokens: int | None = None
+    temperature: float | None = None
+    stream_usage: bool | None = None
+    supports_thinking: bool = False
+    supports_reasoning_effort: bool = False
+    supports_vision: bool = False
+    when_thinking_enabled: dict[str, Any] | None = None
+    when_thinking_disabled: dict[str, Any] | None = None
+    thinking: dict[str, Any] | None = None
+    use_responses_api: bool | None = None
+    output_version: str | None = None
+    extra_settings: dict[str, Any] = Field(default_factory=dict)
+    api_key_configured: bool = False
+    api_key_source: str | None = None
+    source: str = "config.yaml"
+
+
+class ModelAdminListResponse(BaseModel):
+    models: list[ModelAdminItem]
+    config_path: str
+    updated_at: str | None = None
+
+
+class ModelUpsertRequest(BaseModel):
+    """Editable subset of the ``ModelConfig`` schema plus safe extra fields."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str = Field(min_length=1, max_length=160)
+    display_name: str | None = Field(default=None, max_length=160)
+    description: str | None = Field(default=None, max_length=1000)
+    use: str = Field(min_length=1, max_length=255)
+    model: str = Field(min_length=1, max_length=255)
+    # ``None`` means "keep the currently configured secret" on update.
+    # The value is write-only in practice: it is never part of a response.
+    api_key: str | None = Field(default=None, max_length=4096)
+    clear_api_key: bool = False
+    base_url: str | None = Field(default=None, max_length=2048)
+    request_timeout: float | None = Field(default=None, ge=1, le=600)
+    max_retries: int | None = Field(default=None, ge=0, le=20)
+    max_tokens: int | None = Field(default=None, ge=1, le=1_000_000)
+    temperature: float | None = Field(default=None, ge=0, le=2)
+    stream_usage: bool | None = None
+    supports_thinking: bool = False
+    supports_reasoning_effort: bool = False
+    supports_vision: bool = False
+    when_thinking_enabled: dict[str, Any] | None = None
+    when_thinking_disabled: dict[str, Any] | None = None
+    thinking: dict[str, Any] | None = None
+    use_responses_api: bool | None = None
+    output_version: str | None = Field(default=None, max_length=128)
+    extra_settings: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("name", "use", "model")
+    @classmethod
+    def _trim_required(cls, value: str) -> str:
+        normalized = value.strip()
+        if not normalized:
+            raise ValueError("value cannot be empty")
+        return normalized
+
+    @field_validator("display_name", "description", "base_url", "api_key", "output_version")
+    @classmethod
+    def _trim_optional(cls, value: str | None) -> str | None:
+        return value.strip() if isinstance(value, str) else value
+
+
+class ModelTestRequest(BaseModel):
+    model: ModelUpsertRequest
+
+
+class ModelTestResponse(BaseModel):
+    success: bool
+    latency_ms: int
+    message: str
+    preview: str | None = None
+
+
+def _mask_env_source(value: Any) -> str | None:
+    if isinstance(value, str) and value.startswith("$") and len(value) > 1:
+        return value[1:]
+    return None
+
+
+def _to_admin_item(raw: dict[str, Any]) -> ModelAdminItem:
+    api_key = raw.get("api_key")
+    extra = {
+        key: copy.deepcopy(value)
+        for key, value in raw.items()
+        if key not in _PRESERVED_FIELDS
+    }
+    return ModelAdminItem(
+        name=str(raw.get("name") or ""),
+        display_name=raw.get("display_name"),
+        description=raw.get("description"),
+        use=str(raw.get("use") or ""),
+        model=str(raw.get("model") or ""),
+        base_url=raw.get("base_url"),
+        request_timeout=raw.get("request_timeout"),
+        max_retries=raw.get("max_retries"),
+        max_tokens=raw.get("max_tokens"),
+        temperature=raw.get("temperature"),
+        stream_usage=raw.get("stream_usage"),
+        supports_thinking=bool(raw.get("supports_thinking", False)),
+        supports_reasoning_effort=bool(raw.get("supports_reasoning_effort", False)),
+        supports_vision=bool(raw.get("supports_vision", False)),
+        when_thinking_enabled=copy.deepcopy(raw.get("when_thinking_enabled")),
+        when_thinking_disabled=copy.deepcopy(raw.get("when_thinking_disabled")),
+        thinking=copy.deepcopy(raw.get("thinking")),
+        use_responses_api=raw.get("use_responses_api"),
+        output_version=raw.get("output_version"),
+        extra_settings=extra,
+        api_key_configured=bool(api_key),
+        api_key_source=_mask_env_source(api_key),
+    )
+
+
+def _resolve_config_path() -> Path:
+    return AppConfig.resolve_config_path()
+
+
+def _read_config_data(path: Path) -> tuple[str, dict[str, Any], list[dict[str, Any]]]:
+    raw_text = path.read_text(encoding="utf-8")
+    try:
+        data = yaml.safe_load(raw_text) or {}
+    except yaml.YAMLError as exc:
+        raise HTTPException(status_code=500, detail=f"Unable to parse active config.yaml: {exc}") from exc
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=500, detail="The active config.yaml root must be a mapping")
+    raw_models = data.get("models") or []
+    if not isinstance(raw_models, list) or not all(isinstance(item, dict) for item in raw_models):
+        raise HTTPException(status_code=500, detail="config.yaml models must be a list of mappings")
+    return raw_text, data, [copy.deepcopy(item) for item in raw_models]
+
+
+def _render_models_block(models: list[dict[str, Any]], newline: str) -> str:
+    rendered = yaml.safe_dump(
+        {"models": models},
+        allow_unicode=True,
+        sort_keys=False,
+        default_flow_style=False,
+        width=120,
+    )
+    if newline != "\n":
+        rendered = rendered.replace("\n", newline)
+    return rendered if rendered.endswith(newline) else f"{rendered}{newline}"
+
+
+def _replace_models_block(raw_text: str, models: list[dict[str, Any]]) -> str:
+    """Replace the active model entries without touching other config sections.
+
+    PyYAML does not retain comments.  Keep every comment found in the old
+    model section as documentation after the newly rendered model list rather
+    than silently deleting an operator's notes or disabled examples.
+    """
+
+    block_match = _MODEL_BLOCK_RE.search(raw_text)
+    if block_match is None:
+        raise HTTPException(status_code=500, detail="The active config.yaml has no top-level models section")
+    newline = "\r\n" if "\r\n" in raw_text else "\n"
+    next_key = _TOP_LEVEL_KEY_RE.search(raw_text, block_match.end())
+    end = next_key.start() if next_key else len(raw_text)
+    previous_section = raw_text[block_match.end() : end]
+    preserved_comments = "".join(
+        line
+        for line in previous_section.splitlines(keepends=True)
+        if line.lstrip().startswith("#")
+    )
+    rendered = _render_models_block(models, newline)
+    if preserved_comments:
+        if not preserved_comments.endswith(("\n", "\r")):
+            preserved_comments = f"{preserved_comments}{newline}"
+        rendered = f"{rendered}{preserved_comments}"
+    return f"{raw_text[:block_match.start()]}{rendered}{raw_text[end:]}"
+
+
+def _backup_and_write_config(path: Path, raw_before: str, raw_after: str) -> Path:
+    backup_dir = path.parent / _BACKUP_DIR_NAME
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S%fZ")
+    backup_path = backup_dir / f"{path.stem}.{stamp}.yaml"
+    # Persist the exact text that was read for this mutation.  This makes the
+    # rollback deterministic even if another operator changes the file while
+    # the gateway is processing a request.
+    with backup_path.open("w", encoding="utf-8", newline="") as handle:
+        handle.write(raw_before)
+
+    fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+            handle.write(raw_after)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp_name, path)
+    except Exception:
+        try:
+            os.unlink(temp_name)
+        except OSError:
+            pass
+        raise
+    return backup_path
+
+
+def _restore_backup(path: Path, backup_path: Path) -> None:
+    try:
+        shutil.copy2(backup_path, path)
+    except Exception:
+        logger.exception("Failed to restore model config backup at %s", backup_path)
+
+
+def _request_to_raw_model(payload: ModelUpsertRequest, existing: dict[str, Any] | None = None) -> dict[str, Any]:
+    merged = copy.deepcopy(existing or {})
+    supplied = payload.model_dump(exclude={"extra_settings", "clear_api_key"}, exclude_none=True)
+    merged.update(supplied)
+    for key, value in payload.extra_settings.items():
+        normalized = str(key).strip()
+        if not normalized:
+            raise HTTPException(status_code=422, detail="Extra setting names cannot be blank")
+        if normalized in _EDITOR_FIELDS or normalized in {"api_key", "clear_api_key", "extra_settings"}:
+            raise HTTPException(status_code=422, detail=f"Extra setting '{normalized}' duplicates a managed field")
+        merged[normalized] = copy.deepcopy(value)
+    if payload.clear_api_key:
+        merged.pop("api_key", None)
+    elif payload.api_key is None and existing is not None and "api_key" in existing:
+        merged["api_key"] = existing["api_key"]
+
+    # Validate the raw schema without resolving `$ENV_VAR` values.  Environment
+    # resolution happens during the post-write runtime reload and is rolled back
+    # if unavailable.
+    try:
+        ModelConfig.model_validate(merged)
+    except Exception as exc:
+        raise HTTPException(status_code=422, detail=f"Invalid model configuration: {exc}") from exc
+    return merged
+
+
+def _redact_text(value: str, secrets: list[str]) -> str:
+    result = value
+    for secret in secrets:
+        if secret:
+            result = result.replace(secret, "***")
+    return result[:800]
+
+
+async def _require_admin(request: Request) -> None:
+    user = getattr(request.state, "user", None)
+    if user is None:
+        user = await get_optional_user_from_request(request)
+    if user is None:
+        raise HTTPException(status_code=401, detail="Authentication is required")
+    if getattr(user, "system_role", None) != "admin":
+        raise HTTPException(status_code=403, detail="Model configuration requires an administrator")
+
+
+async def _save_models(request: Request, raw_before: str, models: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    path = _resolve_config_path()
+    raw_after = _replace_models_block(raw_before, models)
+    backup_path = await asyncio.to_thread(_backup_and_write_config, path, raw_before, raw_after)
+    try:
+        config = reload_app_config(str(path))
+        request.app.state.config = config
+    except Exception as exc:
+        logger.warning("Updated model configuration could not be activated: %s", type(exc).__name__)
+        await asyncio.to_thread(_restore_backup, path, backup_path)
+        try:
+            request.app.state.config = reload_app_config(str(path))
+        except Exception:
+            logger.exception("Failed to reload restored model config")
+        raise HTTPException(
+            status_code=422,
+            detail="The model configuration could not be activated; the previous config was restored.",
+        ) from exc
+    return models
+
+
+@router.get("", response_model=ModelAdminListResponse)
+async def list_model_configurations(request: Request) -> ModelAdminListResponse:
+    await _require_admin(request)
+    path = _resolve_config_path()
+    _, _, models = await asyncio.to_thread(_read_config_data, path)
+    updated_at = datetime.fromtimestamp(path.stat().st_mtime, tz=UTC).isoformat()
+    return ModelAdminListResponse(
+        models=[_to_admin_item(item) for item in models],
+        config_path=str(path),
+        updated_at=updated_at,
+    )
+
+
+@router.post("", response_model=ModelAdminItem, status_code=201)
+async def create_model_configuration(body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
+    await _require_admin(request)
+    async with _MUTATION_LOCK:
+        path = _resolve_config_path()
+        raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
+        if any(str(item.get("name")) == body.name for item in models):
+            raise HTTPException(status_code=409, detail=f"A model named '{body.name}' already exists")
+        created = _request_to_raw_model(body)
+        await _save_models(request, raw_before, [*models, created])
+    return _to_admin_item(created)
+
+
+@router.put("/{model_name:path}", response_model=ModelAdminItem)
+async def update_model_configuration(model_name: str, body: ModelUpsertRequest, request: Request) -> ModelAdminItem:
+    await _require_admin(request)
+    if body.name != model_name:
+        raise HTTPException(status_code=422, detail="A model's stable name cannot be changed; edit its display name instead")
+    async with _MUTATION_LOCK:
+        path = _resolve_config_path()
+        raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
+        index = next((i for i, item in enumerate(models) if str(item.get("name")) == model_name), None)
+        if index is None:
+            raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
+        updated = _request_to_raw_model(body, models[index])
+        next_models = [*models]
+        next_models[index] = updated
+        await _save_models(request, raw_before, next_models)
+    return _to_admin_item(updated)
+
+
+@router.delete("/{model_name:path}", status_code=204)
+async def delete_model_configuration(model_name: str, request: Request) -> None:
+    """Delete one model configuration and activate the remaining model list."""
+
+    await _require_admin(request)
+    async with _MUTATION_LOCK:
+        path = _resolve_config_path()
+        raw_before, _, models = await asyncio.to_thread(_read_config_data, path)
+        index = next((i for i, item in enumerate(models) if str(item.get("name")) == model_name), None)
+        if index is None:
+            raise HTTPException(status_code=404, detail=f"Model '{model_name}' was not found")
+        await _save_models(request, raw_before, [*models[:index], *models[index + 1 :]])
+
+
+@router.post("/test", response_model=ModelTestResponse)
+async def test_model_connection(body: ModelTestRequest, request: Request) -> ModelTestResponse:
+    """Perform one bounded minimal completion without persisting the draft."""
+
+    await _require_admin(request)
+    path = _resolve_config_path()
+    _, _, models = await asyncio.to_thread(_read_config_data, path)
+    existing = next((item for item in models if str(item.get("name")) == body.model.name), None)
+    candidate = _request_to_raw_model(body.model, existing)
+    candidate_secret = str(candidate.get("api_key") or "")
+    secrets = [candidate_secret]
+    try:
+        runtime_candidate = AppConfig.resolve_env_variables(copy.deepcopy(candidate))
+        # An environment-variable API key is resolved only in memory for this
+        # request. Redact both forms because provider exceptions can include
+        # either the original `$NAME` reference or its resolved value.
+        resolved_secret = str(runtime_candidate.get("api_key") or "")
+        secrets = [candidate_secret, resolved_secret]
+        model_config = ModelConfig.model_validate(runtime_candidate)
+        base_config = request.app.state.config
+        test_config = base_config.model_copy(update={"models": [model_config]})
+        chat_model = create_chat_model(model_config.name, app_config=test_config, force_disable_thinking=True)
+        started = perf_counter()
+        response = await asyncio.wait_for(
+            chat_model.ainvoke([HumanMessage(content="Reply with exactly: OK")]),
+            timeout=min(float(candidate.get("request_timeout") or 30), 45),
+        )
+        latency_ms = round((perf_counter() - started) * 1000)
+        preview = _redact_text(str(getattr(response, "content", "OK")), secrets)
+        return ModelTestResponse(success=True, latency_ms=latency_ms, message="Connection successful", preview=preview)
+    except Exception as exc:
+        # Provider errors sometimes echo a credential.  Never log the full
+        # exception or return it without redacting the submitted key.
+        logger.warning("Model connection test failed for '%s': %s", candidate.get("name"), type(exc).__name__)
+        return ModelTestResponse(
+            success=False,
+            latency_ms=0,
+            message=_redact_text(str(exc) or type(exc).__name__, secrets),
+        )

offline-backend-20260512/backend/app/gateway/routers/position_roundtable.py

@@ -15,8 +15,8 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
-from fastapi import APIRouter, HTTPException, Request
-from pydantic import BaseModel, Field
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import BaseModel, Field, field_validator
 
 from app.gateway.path_utils import aresolve_thread_virtual_path
 from deerflow.runtime.user_context import get_effective_user_id
@@ -79,7 +79,10 @@ class NodeResponse(BaseModel):
 
 class SessionResponse(BaseModel):
     id: str
+    # Older personal rows can already contain a mock task id; task_scoped is
+    # the authoritative opt-in marker for cross-user task sharing.
     external_task_id: str | None = None
+    task_scoped: bool = False
     task_snapshot: dict[str, Any] = Field(default_factory=dict)
     chain_id: str | None = None
     chain_snapshot: dict[str, Any] | None = None
@@ -105,6 +108,14 @@ class SessionCreateRequest(BaseModel):
     external_task_id: str | None = Field(default=None, max_length=128)
     task_snapshot: dict[str, Any] = Field(default_factory=dict)
 
+    @field_validator("external_task_id")
+    @classmethod
+    def _normalize_external_task_id(cls, value: str | None) -> str | None:
+        if value is None:
+            return None
+        normalized = value.strip()
+        return normalized or None
+
 
 class TaskSnapshotUpdateRequest(BaseModel):
     task_snapshot: dict[str, Any] = Field(default_factory=dict)
@@ -145,10 +156,33 @@ class RejectNodeRequest(BaseModel):
     reason: str = Field(default="", max_length=5_000)
 
 
+class ActionPlanDictionaryOption(BaseModel):
+    """One task-system dictionary row, preserving dictValue as the model input."""
+
+    label: str = Field(default="", max_length=256)
+    value: str | int | float = ""
+    id: str | int | None = None
+    dict_type: str = Field(default="", max_length=128)
+    is_default: bool = False
+
+
+class ActionPlanDictionaries(BaseModel):
+    """The four action fields that must be selected from task-system dictionaries."""
+
+    publish_channels: list[ActionPlanDictionaryOption] = Field(default_factory=list)
+    action_types: list[ActionPlanDictionaryOption] = Field(default_factory=list)
+    info_formats: list[ActionPlanDictionaryOption] = Field(default_factory=list)
+    responsible_positions: list[ActionPlanDictionaryOption] = Field(default_factory=list)
+
+
 class PrepareBuiltinRunRequest(BaseModel):
     """Optional follow-up instruction for one persisted built-in agent."""
 
     message: str = Field(default="", max_length=20_000)
+    # 岗位会商会话允许本地演示使用非数字 taskId。真实任务系统新增行动
+    # 时由专属 Skill 再按外部接口契约校验正整数，不能在 prepare 阶段阻断报告生成。
+    task_id: str | int | None = Field(default=None, max_length=128)
+    action_dictionaries: ActionPlanDictionaries | None = None
 
 
 class BuiltinRunPreparationResponse(BaseModel):
@@ -180,6 +214,25 @@ def _current_user_id(request: Request) -> str:
     return str(user.id) if user is not None else get_effective_user_id()
 
 
+def _task_snapshot_for_scope(
+    external_task_id: str | None,
+    task_snapshot: dict[str, Any],
+    *,
+    task_scoped: bool = True,
+) -> dict[str, Any]:
+    """Lock the snapshot id only for an explicit shared task scope."""
+    if not task_scoped or not external_task_id:
+        return dict(task_snapshot)
+    return {**task_snapshot, "id": external_task_id, "externalTaskId": external_task_id}
+
+
+def _normalize_external_task_id(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normalized = value.strip()
+    return normalized or None
+
+
 def _get_store(request: Request):
     store = getattr(request.app.state, "position_roundtable_store", None)
     if store is None:
@@ -440,15 +493,64 @@ def _markdown_delivery_changed(
     return bool(new_signatures - old_signatures)
 
 
+def _intent_string_list(intent: dict[str, Any], key: str) -> list[str]:
+    """Return a clean, display-safe string list from a persisted intent field."""
+    value = intent.get(key)
+    if not isinstance(value, list):
+        return []
+    return [item.strip() for item in value if isinstance(item, str) and item.strip()]
+
+
+def _position_intent_sections(intent: Any) -> dict[str, list[str]]:
+    """Read both the dedicated position-intent schema and legacy snapshots.
+
+    New position sessions persist the four position-specific fields.  Mapping
+    the legacy Step-1 fields keeps already-created sessions executable after
+    this rollout instead of stranding them at the activation gate.
+    """
+    if not isinstance(intent, dict):
+        return {
+            "coreGoals": [],
+            "riskWarnings": [],
+            "keyPoints": [],
+            "strategicSignificance": [],
+        }
+    has_position_schema = any(
+        key in intent
+        for key in ("coreGoals", "riskWarnings", "keyPoints", "strategicSignificance")
+    )
+    if has_position_schema:
+        return {
+            "coreGoals": _intent_string_list(intent, "coreGoals"),
+            "riskWarnings": _intent_string_list(intent, "riskWarnings"),
+            "keyPoints": _intent_string_list(intent, "keyPoints"),
+            "strategicSignificance": _intent_string_list(intent, "strategicSignificance"),
+        }
+
+    objective = _text_from_keys(intent, ["objective", "goal"])
+    return {
+        "coreGoals": _intent_string_list(intent, "constraints"),
+        "riskWarnings": [],
+        "keyPoints": _intent_string_list(intent, "assumptions"),
+        "strategicSignificance": [objective] if objective else [],
+    }
+
+
 def _intent_node_answer(intent: Any) -> str:
     if not isinstance(intent, dict):
         return "情报分析岗已完成任务意图识别。"
-    objective = _text_from_keys(intent, ["objective", "goal"], "已完成任务意图识别")
-    constraints = intent.get("constraints") if isinstance(intent.get("constraints"), list) else []
-    lines = ["情报分析岗已完成任务意图识别。", f"任务目标：{objective}"]
-    if constraints:
-        lines.append("关键约束：")
-        lines.extend(f"- {item}" for item in constraints if isinstance(item, str) and item.strip())
+    sections = _position_intent_sections(intent)
+    lines = ["情报分析岗已完成任务意图识别。"]
+    labels = (
+        ("核心目标", sections["coreGoals"]),
+        ("风险提示", sections["riskWarnings"]),
+        ("关键要点", sections["keyPoints"]),
+        ("战略意义", sections["strategicSignificance"]),
+    )
+    for label, values in labels:
+        if values:
+            lines.append(f"{label}：")
+            lines.extend(f"- {item}" for item in values)
     return "\n".join(lines)
 
 
@@ -456,6 +558,15 @@ def _has_confirmed_intent(intent: Any) -> bool:
     """Only structured Step-1 output may start a frozen business chain."""
     if not isinstance(intent, dict):
         return False
+    if any(
+        key in intent
+        for key in ("coreGoals", "riskWarnings", "keyPoints", "strategicSignificance")
+    ):
+        required = ("coreGoals", "riskWarnings", "keyPoints", "strategicSignificance")
+        if not all(isinstance(intent.get(key), list) for key in required):
+            return False
+        sections = _position_intent_sections(intent)
+        return bool(sections["coreGoals"] or sections["strategicSignificance"])
     objective = _text_from_keys(intent, ["objective", "goal"])
     constraints = intent.get("constraints")
     return bool(objective and isinstance(constraints, list))
@@ -505,8 +616,7 @@ def _build_node_context_text(
     title = _text_from_keys(task, ["title", "taskName", "name"], "未命名任务")
     direction = _text_from_keys(task, ["direction", "taskDirection", "category"], "未填写")
     description = _text_from_keys(task, ["description", "taskContent", "overview", "content"], "暂无任务描述")
-    objective = _text_from_keys(intent, ["objective", "goal"], "暂无意图结论")
-    constraints = intent.get("constraints") if isinstance(intent.get("constraints"), list) else []
+    sections = _position_intent_sections(intent)
     agent_name, position_id = _seat_meta(session, current)
     md_required = not _is_intent_position_node(current, _session_intent_position_id(session))
     lines = [
@@ -518,11 +628,16 @@ def _build_node_context_text(
         f"- 任务描述：{description}",
         "",
         "【已识别意图】",
-        f"- 任务目标：{objective}",
     ]
-    if constraints:
-        lines.append("- 关键约束：")
-        lines.extend(f"  - {item}" for item in constraints if isinstance(item, str) and item.strip())
+    for label, values in (
+        ("核心目标", sections["coreGoals"]),
+        ("风险提示", sections["riskWarnings"]),
+        ("关键要点", sections["keyPoints"]),
+        ("战略意义", sections["strategicSignificance"]),
+    ):
+        if values:
+            lines.append(f"- {label}：")
+            lines.extend(f"  - {item}" for item in values)
     lines.extend(
         [
             "",
@@ -968,6 +1083,8 @@ async def _build_builtin_prompt(
     session: dict[str, Any],
     nodes: list[dict[str, Any]],
     follow_up: str = "",
+    action_task_id: str | int | None = None,
+    action_dictionaries: ActionPlanDictionaries | None = None,
 ) -> str:
     task = session.get("task_snapshot") if isinstance(session.get("task_snapshot"), dict) else {}
     intent = session.get("intent_snapshot") if isinstance(session.get("intent_snapshot"), dict) else {}
@@ -975,8 +1092,7 @@ async def _build_builtin_prompt(
     title = _text_from_keys(task, ["title", "taskName", "name"], "未命名任务")
     direction = _text_from_keys(task, ["direction", "taskDirection", "category"], "未填写")
     description = _text_from_keys(task, ["description", "taskContent", "overview", "content"], "暂无任务描述")
-    objective = _text_from_keys(intent, ["objective", "goal"], "暂无意图结论")
-    constraints = intent.get("constraints") if isinstance(intent.get("constraints"), list) else []
+    sections = _position_intent_sections(intent)
     stage_goals = chain.get("stageGoals") if isinstance(chain.get("stageGoals"), list) else []
     stage_lines = [f"- L-{index + 1}：{goal}" for index, goal in enumerate(stage_goals) if isinstance(goal, str) and goal.strip()]
     material = await _effective_delivery_material(session, nodes)
@@ -990,11 +1106,16 @@ async def _build_builtin_prompt(
         f"- 描述：{description}",
         "",
         "【情报分析岗已确认的意图】",
-        f"- 核心目标：{objective}",
     ]
-    if constraints:
-        common.append("- 关键约束：")
-        common.extend(f"  - {item}" for item in constraints if isinstance(item, str) and item.strip())
+    for label, values in (
+        ("核心目标", sections["coreGoals"]),
+        ("风险提示", sections["riskWarnings"]),
+        ("关键要点", sections["keyPoints"]),
+        ("战略意义", sections["strategicSignificance"]),
+    ):
+        if values:
+            common.append(f"- {label}：")
+            common.extend(f"  - {item}" for item in values)
     if stage_lines:
         common.extend(["", "【业务链阶段】", *stage_lines])
 
@@ -1007,13 +1128,50 @@ async def _build_builtin_prompt(
     else:
         summary = session.get("summary_snapshot") if isinstance(session.get("summary_snapshot"), dict) else {}
         summary_content = _truncate_text(summary.get("content"), 12_000)
+        dictionary_groups = (
+            ("发布渠道（publishChannel）", action_dictionaries.publish_channels if action_dictionaries else []),
+            ("行动类型（actionType）", action_dictionaries.action_types if action_dictionaries else []),
+            ("信息形式（infoFormat）", action_dictionaries.info_formats if action_dictionaries else []),
+            ("责任岗位（responsiblePosition）", action_dictionaries.responsible_positions if action_dictionaries else []),
+        )
+        dictionaries_ready = bool(action_task_id is not None and all(options for _, options in dictionary_groups))
+        dictionary_lines = [
+            "【前端传入的行动字典（名称 → 必须原样使用的 dictValue）】",
+            f"- 当前 taskId：{action_task_id if action_task_id is not None else '（本地预览）'}",
+        ]
+        for label, options in dictionary_groups:
+            dictionary_lines.append(f"- {label}：")
+            dictionary_lines.extend(
+                f"  - {option.label} → {option.value}"
+                for option in options
+            )
+        dictionary_instruction = (
+            "actionType、publishChannel、infoFormat、responsiblePosition 必须从下方同名字典复制 dictValue 并写成整数；"
+            "taskId 必须原样写为当前 taskId。不要保留 id、title、goal、basis、owner_position、dependencies 等旧字段，"
+            "也不要用 0 或空值代替未选择的字典项。"
+            if dictionaries_ready
+            else "当前四类任务系统字典未获取完整，这是本地预览/接口未就绪状态。仍需生成 9 字段 JSON，"
+            "但四个枚举字段可暂填 0 占位，且不得调用 position-roundtable-action-create Skill 或外部任务系统。"
+        )
+        submit_instruction = (
+            "若当前 taskId 是正整数，首次生成完整行动清单后按行动规划智能体的 SOUL 调用 position-roundtable-action-create Skill 批量新增行动；"
+            "若 taskId 为本地演示标识或为空，只生成报告和 JSON，明确说明未调用任务系统。Skill 返回失败时如实报告，不能伪称已入库。"
+            if dictionaries_ready
+            else "本轮字典不完整，只生成报告和 JSON 预览；不得调用 Skill、不得请求外部任务系统，也不能宣称行动已入库。"
+        )
         instructions = [
             "请基于以下方案总结和岗位会商材料，生成或按用户要求修订《岗位会商行动规划》。",
             "必须使用 write_file 分别写入两个最终交付：`/mnt/user-data/outputs/行动规划报告.md` 与 `/mnt/user-data/outputs/action-plan-subtasks.json`。",
-            "Markdown 报告需给出分阶段推进建议、优先级、风险控制与验收安排；JSON 必须是严格合法数组，每个子任务都包含 id、title、goal、basis、owner_position、dependencies、deliverable、acceptance_criteria、priority。",
+            "Markdown 报告需给出分阶段推进建议、优先级、风险控制与验收安排。"
+            "JSON 必须是严格合法数组；每个对象只能包含 actionName、actionDescription、actionType、"
+            "publishChannel、infoFormat、responsiblePosition、startTime、endTime、taskId 这 9 个字段。",
+            dictionary_instruction,
+            submit_instruction,
             "",
             "【已生效方案总结】",
             summary_content or "（方案总结正文未写入快照，请依据下方有效岗位交付重新归纳。）",
+            "",
+            *dictionary_lines,
         ]
     if follow_up.strip():
         instructions.extend(["", "【用户本次补充/修改要求】", follow_up.strip()])
@@ -1082,9 +1240,13 @@ async def seed_demo_session(
 
 
 @router.get("/sessions", response_model=list[SessionResponse])
-async def list_sessions(request: Request, external_task_id: str | None = None) -> list[SessionResponse]:
+async def list_sessions(
+    request: Request,
+    external_task_id: str | None = Query(default=None, max_length=128),
+) -> list[SessionResponse]:
+    task_id = _normalize_external_task_id(external_task_id)
     rows = await _get_store(request).list_sessions(
-        _current_user_id(request), external_task_id=external_task_id
+        _current_user_id(request), external_task_id=task_id
     )
     return [_project_session(row) for row in rows]
 
@@ -1094,7 +1256,12 @@ async def create_session(request: Request, body: SessionCreateRequest) -> Sessio
     row = await _get_store(request).create_session(
         _current_user_id(request),
         external_task_id=body.external_task_id,
-        task_snapshot=body.task_snapshot,
+        task_snapshot=_task_snapshot_for_scope(
+            body.external_task_id,
+            body.task_snapshot,
+            task_scoped=bool(body.external_task_id),
+        ),
+        task_scoped=bool(body.external_task_id),
     )
     return _project_session(row)
 
@@ -1108,8 +1275,16 @@ async def get_session(request: Request, session_id: str) -> SessionDetailRespons
 async def update_task_snapshot(
     request: Request, session_id: str, body: TaskSnapshotUpdateRequest
 ) -> SessionResponse:
-    store, user_id, _ = await _require_writable_session(request, session_id)
-    row = await store.update_session(session_id, user_id, task_snapshot=body.task_snapshot)
+    store, user_id, current = await _require_writable_session(request, session_id)
+    row = await store.update_session(
+        session_id,
+        user_id,
+        task_snapshot=_task_snapshot_for_scope(
+            current.get("external_task_id"),
+            body.task_snapshot,
+            task_scoped=bool(current.get("task_scoped")),
+        ),
+    )
     if row is None:
         raise HTTPException(status_code=404, detail="Position roundtable session not found")
     return _project_session(row)
@@ -1436,6 +1611,8 @@ async def _prepare_builtin_run(
     *,
     kind: str,
     follow_up: str = "",
+    action_task_id: str | int | None = None,
+    action_dictionaries: ActionPlanDictionaries | None = None,
 ) -> BuiltinRunPreparationResponse:
     store, user_id, session = await _require_writable_session(request, session_id)
     nodes = await store.list_nodes(session_id, user_id)
@@ -1469,6 +1646,8 @@ async def _prepare_builtin_run(
             session=session,
             nodes=nodes,
             follow_up=follow_up,
+            action_task_id=action_task_id,
+            action_dictionaries=action_dictionaries,
         ),
         source_revisions=_source_revisions(nodes),
     )
@@ -1576,14 +1755,28 @@ async def complete_summary(
 async def prepare_action_plan(
     request: Request, session_id: str, body: PrepareBuiltinRunRequest
 ) -> BuiltinRunPreparationResponse:
-    return await _prepare_builtin_run(request, session_id, kind="action_plan", follow_up=body.message)
+    return await _prepare_builtin_run(
+        request,
+        session_id,
+        kind="action_plan",
+        follow_up=body.message,
+        action_task_id=body.task_id,
+        action_dictionaries=body.action_dictionaries,
+    )
 
 
 @router.post("/sessions/{session_id}/action-plan/ask", response_model=BuiltinRunPreparationResponse)
 async def ask_action_plan(
     request: Request, session_id: str, body: PrepareBuiltinRunRequest
 ) -> BuiltinRunPreparationResponse:
-    return await _prepare_builtin_run(request, session_id, kind="action_plan", follow_up=body.message)
+    return await _prepare_builtin_run(
+        request,
+        session_id,
+        kind="action_plan",
+        follow_up=body.message,
+        action_task_id=body.task_id,
+        action_dictionaries=body.action_dictionaries,
+    )
 
 
 @router.post("/sessions/{session_id}/action-plan/complete", response_model=SessionDetailResponse)

offline-backend-20260512/backend/app/gateway/routers/roundtable_artifact_submissions.py

@@ -0,0 +1,196 @@
+"""Task-scoped submission status for roundtable artifacts.
+
+This API records only an artifact reference (thread + sandbox path) and its
+submission state.  It intentionally does not fetch task detail, copy Markdown,
+or deliver a file to an external task system.
+
+Routes (authenticated by the Gateway middleware):
+    GET /api/roundtable/tasks/{task_id}/artifacts?submitted=true
+    PUT /api/roundtable/tasks/{task_id}/artifacts/submission
+"""
+
+from __future__ import annotations
+
+from pathlib import PurePosixPath
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query, Request
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, StrictInt, StrictStr, field_validator
+
+from app.gateway.deps import get_current_user
+from deerflow.persistence.roundtable_artifact_submissions import RoundtableArtifactSubmissionStore
+
+router = APIRouter(prefix="/api/roundtable/tasks", tags=["roundtable-artifact-submissions"])
+
+
+class ArtifactReferenceInput(BaseModel):
+    """Reference to a generated file; the file content remains in its thread sandbox."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    session_id: StrictStr | None = Field(default=None, max_length=128, validation_alias=AliasChoices("sessionId", "session_id"))
+    thread_id: StrictStr | None = Field(default=None, max_length=128, validation_alias=AliasChoices("threadId", "thread_id"))
+    node_key: StrictStr | None = Field(default=None, max_length=256, validation_alias=AliasChoices("nodeKey", "node_key"))
+    source_key: StrictStr = Field(..., min_length=1, max_length=512, validation_alias=AliasChoices("sourceKey", "source_key"))
+    path: StrictStr = Field(..., min_length=1, max_length=2048)
+    name: StrictStr | None = Field(default=None, max_length=512)
+    mime_type: StrictStr | None = Field(default=None, max_length=255, validation_alias=AliasChoices("mimeType", "mime_type"))
+    revision: StrictInt = Field(..., ge=0)
+
+    @field_validator("session_id", "thread_id", "node_key", "source_key", "path", "name", "mime_type", mode="before")
+    @classmethod
+    def _trim_text(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            value = value.strip()
+            return value or None
+        return value
+
+
+class ArtifactSubmissionRequest(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    task_id: StrictStr | None = Field(default=None, max_length=128, validation_alias=AliasChoices("taskId", "task_id"))
+    submitted: bool
+    submission_id: StrictStr | None = Field(default=None, max_length=64, validation_alias=AliasChoices("submissionId", "submission_id"))
+    task_delivery_id: StrictStr | None = Field(default=None, max_length=255, validation_alias=AliasChoices("taskDeliveryId", "task_delivery_id"))
+    artifact: ArtifactReferenceInput
+
+    @field_validator("task_id", "submission_id", "task_delivery_id", mode="before")
+    @classmethod
+    def _trim_optional_text(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            value = value.strip()
+            return value or None
+        return value
+
+
+class ArtifactReferenceResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    session_id: str | None = Field(default=None, serialization_alias="sessionId")
+    thread_id: str | None = Field(default=None, serialization_alias="threadId")
+    node_key: str | None = Field(default=None, serialization_alias="nodeKey")
+    source_key: str = Field(serialization_alias="sourceKey")
+    path: str
+    name: str | None = None
+    mime_type: str | None = Field(default=None, serialization_alias="mimeType")
+    revision: int
+
+
+class ArtifactSubmissionResponse(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str
+    task_id: str = Field(serialization_alias="taskId")
+    submitted: bool
+    submitted_at: str | None = Field(default=None, serialization_alias="submittedAt")
+    cancelled_at: str | None = Field(default=None, serialization_alias="cancelledAt")
+    task_delivery_id: str | None = Field(default=None, serialization_alias="taskDeliveryId")
+    artifact: ArtifactReferenceResponse
+
+
+class ArtifactSubmissionListResponse(BaseModel):
+    items: list[ArtifactSubmissionResponse]
+
+
+def _get_store(request: Request) -> RoundtableArtifactSubmissionStore:
+    store = getattr(request.app.state, "roundtable_artifact_submission_store", None)
+    if store is None:
+        raise HTTPException(status_code=503, detail="Roundtable artifact submission store not available")
+    return store
+
+
+def _task_id_or_422(value: str) -> str:
+    task_id = value.strip()
+    if not task_id:
+        raise HTTPException(status_code=422, detail="task id is required")
+    if len(task_id) > 128:
+        raise HTTPException(status_code=422, detail="task id must be at most 128 characters")
+    return task_id
+
+
+def _artifact_payload(artifact: ArtifactReferenceInput) -> dict[str, Any]:
+    source_key = artifact.source_key
+    path = artifact.path
+    if not source_key or not path:
+        raise HTTPException(status_code=422, detail="artifact.sourceKey and artifact.path are required")
+    name = artifact.name or PurePosixPath(path).name or path
+    return {
+        "session_id": artifact.session_id,
+        "thread_id": artifact.thread_id,
+        "node_key": artifact.node_key,
+        "source_key": source_key,
+        "path": path,
+        "name": name,
+        "mime_type": artifact.mime_type,
+        "revision": artifact.revision,
+    }
+
+
+def _response(row: dict[str, Any]) -> ArtifactSubmissionResponse:
+    return ArtifactSubmissionResponse(
+        id=str(row["id"]),
+        task_id=str(row["task_id"]),
+        submitted=bool(row["submitted"]),
+        submitted_at=row.get("submitted_at"),
+        cancelled_at=row.get("cancelled_at"),
+        task_delivery_id=row.get("task_delivery_id"),
+        artifact=ArtifactReferenceResponse(
+            session_id=row.get("session_id"),
+            thread_id=row.get("thread_id"),
+            node_key=row.get("node_key"),
+            source_key=str(row["source_key"]),
+            path=str(row["path"]),
+            name=row.get("name"),
+            mime_type=row.get("mime_type"),
+            revision=int(row["revision"]),
+        ),
+    )
+
+
+@router.get("/{task_id}/artifacts", response_model=ArtifactSubmissionListResponse)
+async def list_artifact_submissions(
+    request: Request,
+    task_id: str,
+    submitted: bool | None = Query(default=True),
+) -> ArtifactSubmissionListResponse:
+    """List task artifacts by submission state (defaults to submitted only)."""
+    rows = await _get_store(request).list_by_task(_task_id_or_422(task_id), submitted=submitted)
+    return ArtifactSubmissionListResponse(items=[_response(row) for row in rows])
+
+
+@router.put("/{task_id}/artifacts/submission", response_model=ArtifactSubmissionResponse)
+async def set_artifact_submission(
+    request: Request,
+    task_id: str,
+    body: ArtifactSubmissionRequest,
+) -> ArtifactSubmissionResponse:
+    """Create/update a submission or retain an audit row while cancelling it."""
+    path_task_id = _task_id_or_422(task_id)
+    if body.task_id is not None and body.task_id != path_task_id:
+        raise HTTPException(status_code=422, detail="taskId must match the path task id")
+
+    artifact = _artifact_payload(body.artifact)
+    actor_id = await get_current_user(request)
+    store = _get_store(request)
+    if body.submitted:
+        # The frontend previews submitted artifacts by threadId + path.  Without
+        # a thread reference a saved state could never be previewed correctly.
+        if not artifact["thread_id"]:
+            raise HTTPException(status_code=422, detail="artifact.threadId is required when submitted is true")
+        row = await store.submit(
+            path_task_id,
+            artifact,
+            task_delivery_id=body.task_delivery_id,
+            actor_id=actor_id,
+        )
+    else:
+        row = await store.cancel(
+            path_task_id,
+            artifact,
+            submission_id=body.submission_id,
+            actor_id=actor_id,
+        )
+        if row is None:
+            raise HTTPException(status_code=404, detail="Artifact submission not found")
+    return _response(row)

offline-backend-20260512/backend/app/gateway/routers/roundtable_chains.py

@@ -58,6 +58,10 @@ class ChainSeatSchema(BaseModel):
     # 与该席位 agent 自身 config.yaml 的同名开关取 OR。默认 False（关）。整条 seats 数组以
     # JSON 透传持久化，故新增此字段无需迁移；仅需在此 schema 显式声明，否则 model_dump() 会剥掉它。
     seat_skill_directive: bool = False
+    # Per-seat human checkpoint. Step 2 pauses after this seat (or its DAG
+    # stage) completes and reuses the existing resume/intervention controls.
+    # It is stored in the existing seats JSON, so no database migration is needed.
+    human_validation: bool = False
     # 该席位「推理深度覆盖」（flash/thinking/pro/ultra）：覆盖链条级 seat_mode，仅本席位生效。
     # None = 跟随链条级默认。「卡顿提速」用：把次要席位降到 flash。整条 seats 数组以 JSON 透传
     # 持久化，故无需迁移；仅需在此 schema 显式声明，否则 model_dump() 会剥掉它。非法值在运行期

offline-backend-20260512/backend/app/gateway/routers/skills.py

@@ -1622,6 +1622,102 @@ async def delete_custom_skill(
         raise HTTPException(status_code=500, detail=f"Failed to delete custom skill: {str(e)}")
 
 
+def _remove_skill_state_config(skill_name: str) -> None:
+    """Remove a deleted skill's enabled/display override from extensions config."""
+    extensions_config = get_extensions_config()
+    if skill_name not in extensions_config.skills:
+        return
+
+    config_path = ExtensionsConfig.resolve_config_path()
+    if config_path is None:
+        config_path = Path.cwd().parent / "extensions_config.json"
+    extensions_config.skills.pop(skill_name, None)
+    config_data = _dump_extensions_config(extensions_config)
+
+    tmp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            delete=False,
+            dir=str(config_path.parent),
+        ) as tmp_file:
+            json.dump(config_data, tmp_file, indent=2)
+            tmp_path = Path(tmp_file.name)
+        os.replace(tmp_path, config_path)
+    finally:
+        if tmp_path is not None and tmp_path.exists():
+            tmp_path.unlink()
+    reload_extensions_config()
+
+
+@router.delete(
+    "/skills/{skill_name}",
+    summary="Delete Built-in Skill",
+    description=(
+        "Administrators may permanently delete a built-in skill. The skill is "
+        "removed from enabled configuration and detached from agents that used it."
+    ),
+)
+async def delete_builtin_skill(
+    skill_name: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+    agent_store=Depends(get_agent_store),
+) -> dict[str, bool]:
+    try:
+        if not _is_admin_user(request):
+            raise HTTPException(status_code=403, detail="Only administrators can delete built-in skills")
+
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        if skill.category != SkillCategory.PUBLIC:
+            raise HTTPException(status_code=400, detail="Use the custom skill deletion endpoint for a custom skill")
+
+        storage = get_or_new_skill_storage(app_config=config)
+        public_root = (storage.get_skills_root_path() / SkillCategory.PUBLIC.value).resolve()
+        skill_dir = skill.skill_file.parent.resolve()
+        if skill_dir == public_root or public_root not in skill_dir.parents:
+            raise ValueError(f"Refusing to delete built-in skill outside the public skills directory: {skill.name}")
+
+        _remove_skill_state_config(skill.name)
+        shutil.rmtree(skill_dir)
+
+        try:
+            from deerflow.skills.usage import forget
+
+            forget(skill.name)
+        except Exception:
+            pass
+
+        await skill_store.delete_admin(skill.name)
+        try:
+            await get_tag_store(request).unassign_all("skill", skill.name)
+        except Exception:  # noqa: BLE001 -- tag cleanup must not block deletion
+            pass
+
+        await cascade_skill_unpublished_or_deleted(
+            skill.name,
+            actor_user_id=_current_user_id(request),
+            operation="delete",
+            skill_owner_user_id=None,
+            agent_store=agent_store,
+        )
+        await refresh_skills_system_prompt_cache_async()
+        logger.info("Administrator deleted built-in skill %s", skill.name)
+        return {"success": True}
+    except HTTPException:
+        raise
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error("Failed to delete built-in skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to delete built-in skill: {str(e)}")
+
+
 class SkillPublishRequest(BaseModel):
     """Request body for toggling a custom skill's published flag."""
 
@@ -2080,11 +2176,16 @@ def _caller_can_edit_skill_files(
     record: dict[str, Any] | None,
     request: Request,
 ) -> bool:
-    """Editing is limited to custom skills, and to either owner or admin."""
-    if skill.category != SkillCategory.CUSTOM:
-        return False
+    """Whether the caller can edit or delete a file within *skill*.
+
+    Built-in skills are deployment-owned, so only administrators may change
+    their files. Custom skills remain editable by their owner or by an
+    administrator.
+    """
     if _is_admin_user(request):
         return True
+    if skill.category != SkillCategory.CUSTOM:
+        return False
     if record is None:
         return False
     return record.get("owner_user_id") == _current_user_id(request)
@@ -2125,6 +2226,24 @@ def _is_text_file(path: Path) -> bool:
     return path.suffix.lower() in _SKILL_FILE_TEXT_EXTS
 
 
+def _write_skill_text_file_atomically(target: Path, content: str) -> None:
+    """Replace an already-validated skill file without exposing partial text."""
+    tmp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            delete=False,
+            dir=str(target.parent),
+        ) as tmp_file:
+            tmp_file.write(content)
+            tmp_path = Path(tmp_file.name)
+        os.replace(tmp_path, target)
+    finally:
+        if tmp_path is not None and tmp_path.exists():
+            tmp_path.unlink()
+
+
 def _build_skill_file_tree(skill_dir: Path) -> SkillFileNode:
     """Walk *skill_dir* and build a SkillFileNode tree, depth/count capped.
 
@@ -2302,9 +2421,9 @@ async def download_skill_file(
     response_model=SkillFileSaveResponse,
     summary="Write Skill File (Text)",
     description=(
-        "Replace the contents of a text file under a custom skill. Only the "
-        "skill's owner or an admin may write; built-in (public) skills are "
-        "read-only. Edits to ``SKILL.md`` re-validate its YAML frontmatter and "
+        "Replace the contents of a text file under a skill. Administrators may "
+        "write built-in and custom skills; custom-skill owners may write their "
+        "own skills. Edits to ``SKILL.md`` re-validate its YAML frontmatter and "
         "refresh the system-prompt cache."
     ),
 )
@@ -2318,11 +2437,9 @@ async def save_skill_file(
     try:
         skill_name = _normalize_skill_name_param(skill_name)
         skill = _load_skill_or_404(skill_name, config)
-        if skill.category != SkillCategory.CUSTOM:
-            raise HTTPException(status_code=403, detail="Built-in skills are read-only")
         record = await skill_store.get_any(skill.name)
         if not _caller_can_edit_skill_files(skill, record, request):
-            raise HTTPException(status_code=403, detail="Only the skill owner or an admin can edit files in this skill")
+            raise HTTPException(status_code=403, detail="Only an administrator or the custom skill owner can edit files in this skill")
 
         target = _resolve_skill_relative_path(skill, body.path)
         if not target.exists():
@@ -2338,7 +2455,7 @@ async def save_skill_file(
         relative_posix = target.relative_to(skill.skill_file.parent.resolve()).as_posix()
         storage = get_or_new_skill_storage(app_config=config)
 
-        is_skill_md = relative_posix == SKILL_MD_FILE
+        is_skill_md = relative_posix.casefold() == SKILL_MD_FILE.casefold()
         prev_content: str | None = None
         if target.exists():
             try:
@@ -2350,20 +2467,21 @@ async def save_skill_file(
             # SKILL.md edits must keep their frontmatter valid (name must match).
             storage.validate_skill_markdown_content(skill.name, body.content)
 
-        storage.write_custom_skill(skill.name, relative_posix, body.content)
+        _write_skill_text_file_atomically(target, body.content)
 
         try:
-            storage.append_history(
-                skill.name,
-                {
-                    "action": "human_edit_file",
-                    "author": "human",
-                    "thread_id": None,
-                    "file_path": relative_posix,
-                    "prev_content": prev_content,
-                    "new_content": body.content,
-                },
-            )
+            if skill.category == SkillCategory.CUSTOM:
+                storage.append_history(
+                    skill.name,
+                    {
+                        "action": "human_edit_file",
+                        "author": "human",
+                        "thread_id": None,
+                        "file_path": relative_posix,
+                        "prev_content": prev_content,
+                        "new_content": body.content,
+                    },
+                )
         except Exception as history_err:  # noqa: BLE001 — history is best-effort
             logger.warning("Failed to append edit history for %s/%s: %s", skill.name, relative_posix, history_err)
 
@@ -2393,6 +2511,75 @@ async def save_skill_file(
         raise HTTPException(status_code=500, detail=f"Failed to save skill file: {e}")
 
 
+@router.delete(
+    "/skills/{skill_name}/files/content",
+    status_code=204,
+    summary="Delete Skill File",
+    description=(
+        "Delete one non-SKILL.md file under a skill. Administrators may delete "
+        "files from built-in and custom skills; custom-skill owners may delete "
+        "files from their own skills. The root ``SKILL.md`` manifest cannot be "
+        "deleted because it defines the skill."
+    ),
+)
+async def delete_skill_file(
+    skill_name: str,
+    request: Request,
+    path: str = Query(..., description="File path relative to the skill directory"),
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> None:
+    try:
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        record = await skill_store.get_any(skill.name)
+        if not _caller_can_edit_skill_files(skill, record, request):
+            raise HTTPException(status_code=403, detail="Only an administrator or the custom skill owner can delete files in this skill")
+
+        target = _resolve_skill_relative_path(skill, path)
+        if not target.exists() or not target.is_file():
+            raise HTTPException(status_code=404, detail=f"File '{path}' not found in skill '{skill_name}'")
+
+        relative_posix = target.relative_to(skill.skill_file.parent.resolve()).as_posix()
+        if relative_posix.casefold() == SKILL_MD_FILE.casefold():
+            raise HTTPException(status_code=400, detail="SKILL.md defines the skill and cannot be deleted")
+
+        prev_content: str | None = None
+        if _is_text_file(target):
+            try:
+                prev_content = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                pass
+        target.unlink()
+
+        if skill.category == SkillCategory.CUSTOM:
+            storage = get_or_new_skill_storage(app_config=config)
+            try:
+                storage.append_history(
+                    skill.name,
+                    {
+                        "action": "human_delete_file",
+                        "author": "human",
+                        "thread_id": None,
+                        "file_path": relative_posix,
+                        "prev_content": prev_content,
+                    },
+                )
+            except Exception as history_err:  # noqa: BLE001
+                logger.warning("Failed to append deletion history for %s/%s: %s", skill.name, relative_posix, history_err)
+        else:
+            logger.info("Administrator deleted built-in skill file %s/%s", skill.name, relative_posix)
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        logger.error("Failed to delete skill file %s/%s: %s", skill_name, path, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to delete skill file: {e}")
+
+
 @router.put(
     "/skills/{skill_name}",
     response_model=SkillResponse,

offline-backend-20260512/backend/app/gateway/routers/threads.py

@@ -12,11 +12,12 @@ matching the LangGraph Platform wire format expected by the
 
 from __future__ import annotations
 
-import logging
+import asyncio
 import json
+import logging
 import os
-from pathlib import Path
 import uuid
+from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, HTTPException, Request
@@ -26,6 +27,7 @@ from sqlalchemy import select
 
 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer
+from app.gateway.llmwiki_deposit import delete_conversation_deposit_documents
 from app.gateway.utils import sanitize_log_param
 from deerflow.config.extensions_config import SkillDisplayConfig
 from deerflow.config.paths import Paths, get_paths
@@ -34,10 +36,12 @@ from deerflow.persistence.skills.model import SkillDisplayAdapterRow
 from deerflow.runtime import serialize_channel_values
 from deerflow.runtime.references import (
     adapt_reference_batches_with_displays,
-    build_reference_batches as build_runtime_reference_batches,
     build_reference_debug_payload,
     build_reference_debug_summary,
 )
+from deerflow.runtime.references import (
+    build_reference_batches as build_runtime_reference_batches,
+)
 from deerflow.runtime.user_context import get_effective_user_id
 from deerflow.utils.time import coerce_iso, now_iso
 
@@ -1250,6 +1254,13 @@ async def clear_thread_messages(thread_id: str, request: Request) -> dict[str, A
         len(messages),
         sanitize_log_param(thread_id),
     )
+    asyncio.create_task(
+        delete_conversation_deposit_documents(
+            request.app,
+            thread_id=thread_id,
+            message_ids=None,
+        )
+    )
     return {
         "ok": True,
         "deleted_ids": deleted_ids,
@@ -1345,6 +1356,13 @@ async def delete_thread_message(thread_id: str, message_id: str, request: Reques
         len(messages) - len(filtered),
         sanitize_log_param(thread_id),
     )
+    asyncio.create_task(
+        delete_conversation_deposit_documents(
+            request.app,
+            thread_id=thread_id,
+            message_ids=deleted_ids,
+        )
+    )
     return {"ok": True, "deleted_ids": deleted_ids, "remaining": len(filtered)}
 
 

offline-backend-20260512/backend/app/gateway/services.py

@@ -21,6 +21,11 @@ from fastapi import HTTPException, Request
 from langchain_core.messages import HumanMessage
 
 from app.gateway.deps import get_concurrency_gate, get_run_context, get_run_manager, get_stream_bridge
+from app.gateway.llmwiki_rag import (
+    attach_llmwiki_rag_to_graph_input,
+    build_llmwiki_rag_context,
+    llmwiki_selection_requested,
+)
 from app.gateway.utils import sanitize_log_param
 from deerflow.config import get_app_config
 from deerflow.config.agents_config import load_agent_config, validate_agent_id
@@ -275,6 +280,8 @@ def _prompt_prefix_opted_in(body: Any) -> bool:
 
 
 def _rag_mode_requested(body: Any) -> bool:
+    if llmwiki_selection_requested(body):
+        return True
     context = getattr(body, "context", None)
     if isinstance(context, Mapping) and context.get("rag_mode_enabled"):
         return True
@@ -325,6 +332,7 @@ _CONTEXT_CONFIGURABLE_KEYS: frozenset[str] = frozenset(
         "thinking_force_disabled",
         "reasoning_effort",
         "rag_mode_enabled",
+        "llmwiki_knowledge_base_ids",
         "writing_mode",
         "writing_artifact_path",
         "canvas_artifact_title",
@@ -1003,6 +1011,27 @@ async def start_run(
         prefix_settings = load_system_settings().prompt_prefix
         if prefix_settings.enabled and prefix_settings.prompt_prefix.strip():
             graph_input = _prepend_prompt_prefix(graph_input, prefix_settings.prompt_prefix.strip())
+    llmwiki_rag = await build_llmwiki_rag_context(
+        request=request,
+        body=body,
+        graph_input=graph_input,
+    )
+    if llmwiki_rag.prompt or llmwiki_rag.sources:
+        graph_input = attach_llmwiki_rag_to_graph_input(graph_input, llmwiki_rag)
+        effective_rag_mode = True
+        run_metadata["llmwiki_knowledge_base_ids"] = llmwiki_rag.knowledge_base_ids
+        run_metadata["llmwiki_rag_source_count"] = llmwiki_rag.source_count
+        try:
+            await run_ctx.thread_store.update_metadata(
+                thread_id,
+                {
+                    "llmwiki_knowledge_base_ids": llmwiki_rag.knowledge_base_ids,
+                    "rag_mode_enabled": True,
+                    "rag_mode": True,
+                },
+            )
+        except Exception:
+            logger.debug("Failed to persist LLMWiki RAG metadata for %s", sanitize_log_param(thread_id), exc_info=True)
     if effective_rag_mode:
         graph_input = _append_invisible_prompt(graph_input, _RAG_CITATION_PROMPT)
     config = build_run_config(thread_id, body.config, body.metadata, assistant_id=body.assistant_id)
@@ -1014,6 +1043,8 @@ async def start_run(
     body_context = dict(getattr(body, "context", None) or {})
     if effective_rag_mode:
         body_context["rag_mode_enabled"] = True
+    if "llmwiki_knowledge_base_ids" not in body_context and llmwiki_rag.knowledge_base_ids:
+        body_context["llmwiki_knowledge_base_ids"] = llmwiki_rag.knowledge_base_ids
     # Promote whitelisted top-level body fields into the context map so
     # callers can pass them either nested under ``context`` or as flat
     # top-level fields (``excluded_tools``, ``skill_stop_names``, …).

offline-backend-20260512/backend/app/gateway/weknora_embed.py

@@ -0,0 +1,102 @@
+"""Shared helpers for WeKnora iframe proxy sessions."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import HTTPException
+
+WEKNORA_EMBED_COOKIE = "deerflow_weknora_embed"
+WEKNORA_EMBED_TTL_SECONDS = 15 * 60
+WEKNORA_EMBED_API_PREFIX = "/api/llmwiki/weknora-embed"
+WEKNORA_PROXY_SECRET = os.getenv("DEERFLOW_LLMWIKI_PROXY_SECRET") or secrets.token_urlsafe(48)
+WEKNORA_ROOT_ASSET_PATHS: frozenset[str] = frozenset(
+    {
+        "/favicon.ico",
+        "/favicon.svg",
+        "/config.js",
+        "/logo.svg",
+        "/manifest.webmanifest",
+    }
+)
+
+
+@dataclass(frozen=True)
+class WeKnoraEmbedContext:
+    mapping_id: str
+    weknora_id: str
+    user_id: str
+    is_admin: bool
+    can_write: bool
+    exp: int
+    is_conversation_deposit: bool = False
+
+
+def is_weknora_embed_proxy_path(path: str) -> bool:
+    return (
+        path == "/platform"
+        or path.startswith("/platform/")
+        or path.startswith("/assets/")
+        or path.startswith("/locales/")
+        or path.startswith("/tdesign-icons/")
+        or path in WEKNORA_ROOT_ASSET_PATHS
+        or path.startswith(f"{WEKNORA_EMBED_API_PREFIX}/api/v1/")
+        or (path.startswith("/api/v1/") and not path.startswith("/api/v1/auth/"))
+    )
+
+
+def _b64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")
+
+
+def _b64url_decode(data: str) -> bytes:
+    padded = data + ("=" * (-len(data) % 4))
+    return base64.urlsafe_b64decode(padded.encode("ascii"))
+
+
+def sign_weknora_embed_payload(payload: dict[str, Any]) -> str:
+    body = _b64url_encode(json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8"))
+    sig = hmac.new(WEKNORA_PROXY_SECRET.encode("utf-8"), body.encode("ascii"), hashlib.sha256).digest()
+    return f"{body}.{_b64url_encode(sig)}"
+
+
+def verify_weknora_embed_cookie(raw: str | None) -> WeKnoraEmbedContext:
+    if not raw or "." not in raw:
+        raise HTTPException(status_code=401, detail="WeKnora iframe session is missing")
+    body, sig = raw.rsplit(".", 1)
+    expected = _b64url_encode(
+        hmac.new(WEKNORA_PROXY_SECRET.encode("utf-8"), body.encode("ascii"), hashlib.sha256).digest()
+    )
+    if not hmac.compare_digest(sig, expected):
+        raise HTTPException(status_code=401, detail="WeKnora iframe session is invalid")
+    try:
+        payload = json.loads(_b64url_decode(body))
+    except (ValueError, TypeError, json.JSONDecodeError):
+        raise HTTPException(status_code=401, detail="WeKnora iframe session is invalid") from None
+    if int(payload.get("exp") or 0) < int(time.time()):
+        raise HTTPException(status_code=401, detail="WeKnora iframe session has expired")
+    return WeKnoraEmbedContext(
+        mapping_id=str(payload.get("mapping_id") or ""),
+        weknora_id=str(payload.get("weknora_id") or ""),
+        user_id=str(payload.get("user_id") or ""),
+        is_admin=bool(payload.get("is_admin")),
+        can_write=bool(payload.get("can_write")),
+        exp=int(payload.get("exp") or 0),
+        is_conversation_deposit=bool(payload.get("is_conversation_deposit")),
+    )
+
+
+def has_valid_weknora_embed_cookie(raw: str | None) -> bool:
+    try:
+        verify_weknora_embed_cookie(raw)
+    except HTTPException:
+        return False
+    return True

offline-backend-20260512/backend/config.yaml

@@ -33,32 +33,64 @@ concurrency:
     fail_open: true
 
 models:
-  - name: deepseek-chat
-    display_name: DeepSeek Chat
-    use: langchain_openai:ChatOpenAI
-    model: deepseek-chat
-    api_key: $DEEPSEEK_CHAT_API_KEY
-    base_url: https://api.deepseek.com
-    request_timeout: 600.0
-    max_retries: 2
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: false
-    supports_thinking: true
-
-  - name: zai-org/GLM-5-FP8
-    display_name: zai-org/GLM-5-FP8
-    use: langchain_openai:ChatOpenAI
-    model: zai-org/GLM-5-FP8
-    api_key: $GLM5_FP8_API_KEY
-    base_url: https://api.us-west-2.modal.direct/v1
-    request_timeout: 600.0
-    max_retries: 2
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: true
-    supports_thinking: true
-
+- name: deepseek-chat
+  display_name: DeepSeek Chat
+  use: langchain_openai:ChatOpenAI
+  model: deepseek-chat
+  api_key: $DEEPSEEK_CHAT_API_KEY
+  base_url: https://api.deepseek.com
+  request_timeout: 600.0
+  max_retries: 2
+  max_tokens: 4096
+  temperature: 1.0
+  supports_vision: false
+  supports_thinking: true
+- name: zai-org/GLM-5-FP8
+  display_name: zai-org/GLM-5-FP8
+  use: langchain_openai:ChatOpenAI
+  model: zai-org/GLM-5-FP8
+  api_key: $GLM5_FP8_API_KEY
+  base_url: https://api.us-west-2.modal.direct/v2
+  request_timeout: 600.0
+  max_retries: 2
+  max_tokens: 4096
+  temperature: 1.0
+  supports_vision: true
+  supports_thinking: true
+  supports_reasoning_effort: false
+- name: deepseek-ai/DeepSeek-V4-Flash
+  display_name: deepseek-ai/DeepSeek-V4-Flash
+  use: langchain_openai:ChatOpenAI
+  model: deepseek-ai/DeepSeek-V4-Flash
+  api_key: $SILICONFLOW_API_KEY
+  base_url: https://api.siliconflow.cn/v1/
+  max_tokens: 4096
+  temperature: 1.0
+  supports_vision: true
+  supports_thinking: true
+  when_thinking_disabled:
+    extra_body:
+      enable_thinking: false
+- name: inclusionAI/Ling-flash-2.0
+  display_name: inclusionAI/Ling-flash-2.0
+  use: langchain_openai:ChatOpenAI
+  model: inclusionAI/Ling-flash-2.0
+  api_key: $SILICONFLOW_API_KEY
+  base_url: https://api.siliconflow.cn/v1/
+  max_tokens: 4096
+  temperature: 1.0
+  supports_vision: true
+  supports_thinking: true
+- name: deepseek-ai/DeepSeek-V4-Pro
+  display_name: deepseek-ai/DeepSeek-V4-Pro
+  use: langchain_openai:ChatOpenAI
+  model: deepseek-ai/DeepSeek-V4-Pro
+  api_key: $SILICONFLOW_API_KEY
+  base_url: https://api.siliconflow.cn/v1/
+  max_tokens: 4096
+  temperature: 1.0
+  supports_vision: true
+  supports_thinking: true
   # - name: deepseek-v4-flash
   #   display_name: DeepSeek V4 Flash
   #   use: langchain_openai:ChatOpenAI
@@ -71,7 +103,6 @@ models:
   #   temperature: 1.0
   #   supports_vision: false
   #   supports_thinking: true
-
   # - name: deepseek-v4-pro
   #   display_name: DeepSeek V4 Pro
   #   use: langchain_openai:ChatOpenAI
@@ -136,52 +167,9 @@ models:
   #   temperature: 1.0
   #   supports_vision: true
   #   supports_thinking: true
-  - name: deepseek-ai/DeepSeek-V4-Flash
-    display_name: deepseek-ai/DeepSeek-V4-Flash
-    use: langchain_openai:ChatOpenAI
-    model: deepseek-ai/DeepSeek-V4-Flash
-    api_key: $SILICONFLOW_API_KEY
-    base_url: https://api.siliconflow.cn/v1/
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: true
-    supports_thinking: true
     # SiliconFlow 混合推理模型关思考用「请求体顶层 enable_thinking: false」,
     # 不认 chat_template_kwargs / thinking.type 那两种嵌套形状。声明这个后,
     # 网页端「关闭思考」对本模型才生效(开放接口另由 force_disable_thinking 兜底)。
-    when_thinking_disabled:
-      extra_body:
-        enable_thinking: false
-  - name: Pro/MiniMaxAI/MiniMax-M2.5
-    display_name: Pro/MiniMaxAI/MiniMax-M2.5
-    use: langchain_openai:ChatOpenAI
-    model: Pro/MiniMaxAI/MiniMax-M2.5
-    api_key: $SILICONFLOW_API_KEY
-    base_url: https://api.siliconflow.cn/v1/
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: true
-    supports_thinking: true
-  - name: inclusionAI/Ling-flash-2.0
-    display_name: inclusionAI/Ling-flash-2.0
-    use: langchain_openai:ChatOpenAI
-    model: inclusionAI/Ling-flash-2.0
-    api_key: $SILICONFLOW_API_KEY
-    base_url: https://api.siliconflow.cn/v1/
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: true
-    supports_thinking: true
-  - name: deepseek-ai/DeepSeek-V4-Pro
-    display_name: deepseek-ai/DeepSeek-V4-Pro
-    use: langchain_openai:ChatOpenAI
-    model: deepseek-ai/DeepSeek-V4-Pro
-    api_key: $SILICONFLOW_API_KEY
-    base_url: https://api.siliconflow.cn/v1/
-    max_tokens: 4096
-    temperature: 1.0
-    supports_vision: true
-    supports_thinking: true
 # 识图(图片识别)配置。
 # - model_name:指定一个 models[] 中的模型名,作为“默认识图大模型”。view_image 工具会把
 #   图片交给该模型识别,并把识别出的文字结果返回给主对话模型 —— 这样即使主对话模型不支持
@@ -258,8 +246,20 @@ tool_groups:
 tools:
   - name: web_search
     group: web
-    use: deerflow.community.ddg_search.tools:web_search_tool
+    use: deerflow.community.configurable_search.tools:web_search_tool
+    # Keep disabled until the deployment-specific endpoint is filled in.
+    # When false, web_search is not registered with the agent at all.
+    enabled: false
+    endpoint: "https://xxx.xxx.xxx/searchName"
+    verify_ssl: false
+    timeout: 30
     max_results: 5
+    result_url_template: "https://xxx.xxx.xxx/mindId/xxx?recUuid={recUuid}"
+    # The runtime query always overwrites payload.query; all other fields are
+    # sent unchanged so deployment-specific request parameters stay in config.
+    payload:
+      query: ""
+      xxx: "xxxx"
 
   - name: web_fetch
     group: web
@@ -478,6 +478,21 @@ ai_writing:
     writer: false # 作家（逐章正文写作，逐章流式与严格模式求助逻辑不变）
     editor: false # 编辑（事实/逻辑/语言三维度审查）
 
+# Optional independently deployed WeKnora integration. DeerFlow owns only
+# these connection values; database/Redis/storage/parser/model settings stay
+# in WeKnora's own docker-compose/.env/config files. A non-empty api_base_url
+# enables WeKnora mode; leaving it empty preserves the existing LLMWiki iframe.
+# admin_email/admin_password are used only by DeerFlow's server-side WeKnora
+# detail-page iframe proxy. Prefer environment variables in production, e.g.
+# admin_email: "$WEKNORA_ADMIN_EMAIL"
+# admin_password: "$WEKNORA_ADMIN_PASSWORD"
+llmwiki:
+  weknora:
+    api_base_url: "http://119.254.86.251:8088/deerflow-api"
+    web_base_url: "http://119.254.86.251:8088"
+    admin_email: "lqq@qq.com"
+    admin_password: "$WEKNORA_ADMIN_PASSWORD"
+
 log_system:
   enabled: true
   url: 'https://your-log-system.example.com'

offline-backend-20260512/backend/docs/LLMWIKI_WEKNORA_INTEGRATION_ZH.md

@@ -0,0 +1,105 @@
+# LLMWiki × WeKnora 集成与部署
+
+## 目标与边界
+
+DeerFlow 只把 WeKnora 当作独立部署的知识抽取、向量化和检索服务，不复制或修改 WeKnora 前端，也不接管它的运行配置。
+
+本版本按 WeKnora `v0.7.2` 的官方 REST API 实现；升级 WeKnora 大版本前应先回归下文列出的主要接口。
+
+- WeKnora 自己负责 PostgreSQL、Redis、对象存储、解析器、向量库、Embedding/Rerank/LLM 等依赖。
+- DeerFlow 只保存 WeKnora 连接地址，以及 DeerFlow 用户、发布状态、智能体绑定与 WeKnora 知识库之间的映射。
+- DeerFlow 不保存也不发送 WeKnora API Key、Bearer Token 或其他 WeKnora 凭证；浏览器拿不到原始 WeKnora 知识库 ID。
+- 用户权限、智能体所有权和页面风格全部沿用 DeerFlow；库所有者发布后立即进入公共 LLMWiki，不经过审核队列。
+
+## 模式开关
+
+`config.yaml` 中 `llmwiki.weknora.api_base_url` 非空时启用 WeKnora 模式；为空时继续使用原有 LLMWiki 页面和流程。
+
+```yaml
+llmwiki:
+  weknora:
+    api_base_url: "http://weknora-app:8080"
+    web_base_url: "http://weknora-app:8080"
+```
+
+管理员也可在 DeerFlow 原 LLMWiki 页面中的“集成配置”修改地址。页面配置是运行时覆盖项：启用覆盖并填写地址会切换到 WeKnora；启用覆盖但留空会强制回到原模式；“恢复配置文件设置”会重新采用 `config.yaml`。
+
+这两个地址是 DeerFlow 中全部的 WeKnora 配置，不需要创建密钥文件，也不需要在 DeerFlow 中配置 WeKnora 的数据库、模型或存储参数。
+
+## WeKnora 侧准备
+
+先按 WeKnora 官方部署方式完整启动 WeKnora。数据库、Redis、MinIO/S3、解析服务和所有模型均在 WeKnora 自己的 compose、`.env` 或管理页面配置，DeerFlow 无对应字段。
+
+DeerFlow 对 WeKnora 使用无凭证的内部 HTTP 请求，因此 `api_base_url` 必须指向可信内网服务，不能把匿名接口直接暴露到公网。需要在 WeKnora 自身或前置反向代理中，仅按容器网络、源 IP、安全组或 mTLS 等基础设施边界放行 DeerFlow。若 WeKnora 保持默认接口鉴权且未放行，连接测试会收到 401/403，并提示配置 WeKnora 或反向代理；DeerFlow 不提供凭证回退。
+
+WeKnora 中至少需要一个可用且标为默认的 Embedding 模型。创建知识库时，DeerFlow 调用 WeKnora `/api/v1/models` 查找 `type=Embedding` 的默认模型，并把它的 ID 传给 WeKnora；因此 DeerFlow 不提供 `default_embedding_model_id` 配置。这个 ID 的含义是“新知识库使用哪个编码模型生成向量”，其生命周期属于 WeKnora。
+
+WeKnora 侧放行范围需要覆盖本版本调用的模型读取、知识库管理、文档写入和知识检索接口。如果基础设施只放行检索接口，可以检索已有知识库，但无法通过 DeerFlow 创建知识库或上传文档。
+
+## 数据与权限模型
+
+DeerFlow 的 `llmwiki_knowledge_bases` 表保存以下控制面数据：DeerFlow 映射 ID、WeKnora ID、所有者用户 ID、名称快照和公开状态。文档、切片、向量和模型参数仍只存在 WeKnora。
+
+- 个人库：仅所有者和 DeerFlow 管理员可管理。
+- 公共库：所有者点击发布后立即公开，全部 DeerFlow 用户只读可检索；所有者可随时取消公开。
+- 删除个人库时先删除 WeKnora 实体，再删除 DeerFlow 映射。
+- 所有 BFF 接口和智能体工具都会按当前 DeerFlow 登录用户重新鉴权，不能靠前端提交任意知识库 ID 越权。
+
+当前无凭证/反向代理方案使用一个固定的 WeKnora 服务身份。因此 DeerFlow 的用户隔离是映射层的逻辑隔离：不同 DeerFlow 用户只能看到自己拥有的库和已公开库；但这些库在 WeKnora 物理上都创建于该服务身份所属的同一个空间。上传文件不会落到 DeerFlow 用户目录，而是经 DeerFlow BFF 转发给 WeKnora，由 WeKnora 把文件对象、知识元数据、切片和向量分别写入自己的对象存储、数据库和向量存储。需要在 WeKnora 后台核对时，应登录这个服务身份所属空间，在“知识库管理”中按同名知识库进入查看。
+
+如果要求 WeKnora 本身也按 DeerFlow 用户划分空间，则需要另一种部署：为每个 DeerFlow 用户建立 WeKnora 用户/租户并安全保存、轮换各自凭证。它与当前“不在 DeerFlow 配置 WeKnora 凭证”的单服务身份方案不同，不能只靠前端切换实现。
+
+## 智能体和对话选择
+
+智能体 `config.yaml` 可保存：
+
+```yaml
+llmwiki_knowledge_base_ids:
+  - "deerflow-mapping-id-1"
+  - "deerflow-mapping-id-2"
+```
+
+这里必须是 DeerFlow 映射 ID，不是 WeKnora 原始 ID。智能体创建页和详情编辑页均提供内嵌的“绑定知识空间”面板，可直接搜索、分组、多选、全选或清空当前用户有权读取的个人库和公共库，不再通过额外弹窗配置。
+
+新建智能体对话时，页面只展示“智能体已绑定”且“当前登录用户仍有权读取”的交集，默认全选，可在发送第一条消息前调整或清空。普通新建对话也可选择知识库；选中了智能体时会自动切换成该智能体的绑定范围。问答选择器仿照 WeKnora 的交互结构，作为输入框工具栏的锚定下拉呈现，包含搜索、个人/公共分组、文档数量、多选、全选和清空，不再在输入框外单独占据一行。选择结果写入 LangGraph thread metadata 和运行 context，重新打开对话会恢复，开始对话后不可中途扩大权限范围。
+
+`llmwiki_search` 是只读工具，只在 WeKnora 模式注册。每次调用会同时校验：
+
+1. 当前对话选择；
+2. 智能体允许的绑定范围；
+3. 当前 DeerFlow 用户对映射的实时读取权限。
+
+明确选择空列表表示本次对话不使用 LLMWiki；旧对话没有选择字段时，智能体对话默认使用其绑定范围，通用 Lead Agent 默认使用当前用户全部可见知识库。
+
+## 前端实现
+
+WeKnora 前端不做任何修改。DeerFlow 原“知识库资源管理”入口根据运行模式渲染：
+
+- 原模式：保留现有 LLMWiki iframe 页面；
+- WeKnora 模式：渲染 DeerFlow 原生 React 页面，提供个人库、公共库、直接发布和检索。点击卡片进入独立知识库路由，内容区复刻 WeKnora 的详情页结构，同时保留 DeerFlow 的导航、登录和权限壳。Wiki 库按 **Wiki → 文档 → 图谱** 排列并默认打开 Wiki；标准库不显示 Wiki 标签，按 **文档 → 图谱** 排列。Wiki 视图包含页面目录、搜索、页面正文和引用摘要；文档以卡片网格展示，点击后从右侧抽屉查看元数据、原文件与真实解析分块；图谱视图渲染 WeKnora Wiki 页面节点和边。新建知识库可选择“Wiki 知识库”或“标准知识库”，详情页支持文件、网页 URL、手工 Markdown 三种导入方式。问答选择器沿用 WeKnora 的紧凑搜索/分组/多选交互，颜色、间距和组件沿用 DeerFlow 设计系统；智能体创建和编辑页使用同一数据源的内嵌绑定面板。
+
+问答检索命中以 DeerFlow 来源卡片展示。“查看原文”调用 DeerFlow 的 `/api/llmwiki/sources/context`，由服务端在重新校验 DeerFlow 用户权限后向 WeKnora 读取命中切片及相邻上下文，不向浏览器暴露 WeKnora 原始资源 ID。
+
+## 主要接口
+
+- `GET /api/llmwiki/runtime`：当前原模式/WeKnora 模式。
+- `/api/system-settings/llmwiki`：管理员地址配置、重置和连通性测试。
+- `/api/llmwiki/knowledge-bases`：知识库 CRUD、标准/Wiki 模式创建、详情、文档上传、解析、直接发布和取消公开。
+- `POST /api/llmwiki/knowledge-bases/{id}/documents/url`：导入网页 URL。
+- `POST /api/llmwiki/knowledge-bases/{id}/documents/manual`：发布手工 Markdown 内容。
+- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}`：具体文档元数据。
+- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/preview`：鉴权后代理原文件预览。
+- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/chunks`：分页读取解析后的真实分块索引。
+- `GET /api/llmwiki/knowledge-bases/{id}/graph`：读取 Wiki 页面图谱的节点和边；未开启 Wiki 索引时返回明确的空状态。
+- `GET /api/llmwiki/knowledge-bases/{id}/wiki/pages` 与 `.../wiki/pages/{slug}`：读取 Wiki 页面目录和正文。
+- `GET /api/llmwiki/agents/{agent_id}/knowledge-bases`：当前用户可用于该智能体的绑定交集。
+- `POST /api/llmwiki/search`：页面检索。
+- `GET /api/llmwiki/sources/context`：引用原文上下文。
+
+## 验收建议
+
+1. 地址留空启动，确认原 LLMWiki 页面和原有流程不变。
+2. 在可信网络中放行 DeerFlow，配置地址，测试连接并创建个人库、上传文档、等待解析完成；确认 DeerFlow 请求没有认证头。
+3. 普通用户直接发布，换另一用户确认能立即读取和检索、但不能修改；再由所有者取消公开并确认访问随即失效。
+4. 给智能体绑定两个库，新建对话取消其中一个，确认引用只来自保留的库；重新打开对话确认选择恢复。
+5. 撤销公共发布或删除用户权限后继续提问，确认工具实时拒绝已失效的知识库。

offline-backend-20260512/backend/extensions_config.json

@@ -1,24 +1,5 @@
 {
-  "mcpServers": {
-    "weknora-retrieval": {
-      "enabled": true,
-      "type": "stdio",
-      "command": "uv",
-      "args": [
-        "run",
-        "--no-sync",
-        "python",
-        "skills/custom/weknora-knowledge-search/scripts/weknora_retrieval_mcp.py"
-      ],
-      "env": {
-        "WEKNORA_BASE_URL": "http://[::1]:8081",
-        "WEKNORA_DEERFLOW_SHARE_TOKEN_FILE": "F:\\react01\\deeflow-code\\deerflow-server\\offline-backend-20260512\\backend\\.runtime\\secrets\\weknora_deerflow_share_token",
-        "WEKNORA_ALLOWED_KB_IDS": "",
-        "WEKNORA_REQUEST_TIMEOUT_SECONDS": "30",
-        "WEKNORA_RERANK_URL": "http://47.88.25.99:7022"
-      }
-    }
-  },
+  "mcpServers": {},
   "skills": {
     "web-research": {
       "enabled": true
@@ -49,9 +30,6 @@
     },
     "browser_act": {
       "enabled": true
-    },
-    "weknora-knowledge-search": {
-      "enabled": true
     }
   }
 }

offline-backend-20260512/backend/packages/harness/deerflow/community/configurable_search/__init__.py

@@ -0,0 +1,3 @@
+from .tools import web_search_tool
+
+__all__ = ["web_search_tool"]

offline-backend-20260512/backend/packages/harness/deerflow/community/configurable_search/tools.py

@@ -0,0 +1,202 @@
+"""Configurable JSON-over-HTTP implementation of the ``web_search`` tool."""
+
+from __future__ import annotations
+
+import json
+import logging
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from langchain.tools import tool
+
+from deerflow.config import get_app_config
+from deerflow.config.tool_config import ToolConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ConfigurableSearchSettings:
+    """Validated runtime settings read from the ``web_search`` tool entry."""
+
+    enabled: bool
+    endpoint: str
+    payload: dict[str, Any]
+    verify_ssl: bool
+    timeout: float
+    max_results: int
+    result_url_template: str
+
+    @classmethod
+    def from_tool_config(cls, config: ToolConfig | None) -> ConfigurableSearchSettings:
+        if config is None:
+            raise ValueError("web_search is not configured")
+
+        extra = config.model_extra or {}
+        endpoint = str(extra.get("endpoint") or "").strip()
+        if not endpoint.startswith(("http://", "https://")):
+            raise ValueError("web_search.endpoint must use http:// or https://")
+
+        raw_payload = extra.get("payload", {})
+        if not isinstance(raw_payload, dict):
+            raise ValueError("web_search.payload must be an object")
+
+        try:
+            timeout = float(extra.get("timeout", 30))
+        except (TypeError, ValueError) as exc:
+            raise ValueError("web_search.timeout must be a number") from exc
+        if timeout <= 0:
+            raise ValueError("web_search.timeout must be greater than zero")
+
+        try:
+            max_results = int(extra.get("max_results", 5))
+        except (TypeError, ValueError) as exc:
+            raise ValueError("web_search.max_results must be an integer") from exc
+        if max_results <= 0:
+            raise ValueError("web_search.max_results must be greater than zero")
+
+        result_url_template = str(extra.get("result_url_template") or "").strip()
+        if result_url_template and "{recUuid}" not in result_url_template:
+            raise ValueError("web_search.result_url_template must contain {recUuid}")
+
+        verify_ssl = extra.get("verify_ssl", True)
+        if not isinstance(verify_ssl, bool):
+            raise ValueError("web_search.verify_ssl must be true or false")
+
+        return cls(
+            enabled=config.enabled,
+            endpoint=endpoint,
+            payload=deepcopy(raw_payload),
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+            max_results=max_results,
+            result_url_template=result_url_template,
+        )
+
+
+def _text(value: Any) -> str:
+    """Normalize optional scalar result fields without leaking ``None``."""
+
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    return str(value)
+
+
+def _error_result(query: str, message: str) -> str:
+    return json.dumps(
+        {
+            "query": query,
+            "total_results": 0,
+            "results": [],
+            "error": message,
+        },
+        ensure_ascii=False,
+    )
+
+
+def _normalize_results(data: Any, settings: ConfigurableSearchSettings) -> list[dict[str, str]]:
+    if not isinstance(data, dict):
+        raise ValueError("search API response must be a JSON object")
+
+    raw_results = data.get("results")
+    if not isinstance(raw_results, list):
+        raise ValueError("search API response field 'results' must be an array")
+
+    normalized: list[dict[str, str]] = []
+    for item in raw_results[: settings.max_results]:
+        if not isinstance(item, dict):
+            logger.warning("Ignoring non-object search result: %r", item)
+            continue
+
+        rec_uuid = _text(item.get("recUuid")).strip()
+        original_url = _text(item.get("url")).strip()
+        result_url = original_url
+        if rec_uuid and settings.result_url_template:
+            result_url = settings.result_url_template.replace(
+                "{recUuid}",
+                quote(rec_uuid, safe=""),
+            )
+
+        normalized.append(
+            {
+                "recUuid": rec_uuid,
+                "content": _text(item.get("content")),
+                "title": _text(item.get("title")),
+                "url": result_url,
+            }
+        )
+    return normalized
+
+
+async def execute_search(
+    query: str,
+    settings: ConfigurableSearchSettings,
+    *,
+    transport: httpx.AsyncBaseTransport | None = None,
+) -> str:
+    """Execute a search request; ``transport`` exists for network-free tests."""
+
+    normalized_query = query.strip()
+    if not normalized_query:
+        return _error_result(query, "Search query must not be empty")
+    if not settings.enabled:
+        return _error_result(normalized_query, "web_search is disabled")
+
+    payload = deepcopy(settings.payload)
+    payload["query"] = normalized_query
+
+    try:
+        async with httpx.AsyncClient(
+            timeout=settings.timeout,
+            verify=settings.verify_ssl,
+            transport=transport,
+        ) as client:
+            response = await client.post(settings.endpoint, json=payload)
+            response.raise_for_status()
+            data = response.json()
+        results = _normalize_results(data, settings)
+    except httpx.TimeoutException:
+        logger.warning("Configured web search timed out for endpoint %s", settings.endpoint)
+        return _error_result(normalized_query, "Search API request timed out")
+    except httpx.HTTPStatusError as exc:
+        logger.warning(
+            "Configured web search returned HTTP %s for endpoint %s",
+            exc.response.status_code,
+            settings.endpoint,
+        )
+        return _error_result(normalized_query, f"Search API returned HTTP {exc.response.status_code}")
+    except (httpx.HTTPError, json.JSONDecodeError) as exc:
+        logger.warning("Configured web search request failed: %s", exc)
+        return _error_result(normalized_query, f"Search API request failed: {type(exc).__name__}")
+    except ValueError as exc:
+        logger.warning("Configured web search returned an invalid response: %s", exc)
+        return _error_result(normalized_query, str(exc))
+
+    return json.dumps(
+        {
+            "query": normalized_query,
+            "total_results": len(results),
+            "results": results,
+        },
+        ensure_ascii=False,
+    )
+
+
+@tool("web_search", parse_docstring=True)
+async def web_search_tool(query: str) -> str:
+    """Search the configured information service for current facts and source passages.
+
+    Args:
+        query: Focused search keywords or a natural-language retrieval question.
+    """
+
+    try:
+        settings = ConfigurableSearchSettings.from_tool_config(get_app_config().get_tool_config("web_search"))
+    except ValueError as exc:
+        return _error_result(query, str(exc))
+    return await execute_search(query, settings)

offline-backend-20260512/backend/packages/harness/deerflow/config/agents_config.py

@@ -7,7 +7,7 @@ import threading
 from typing import Any
 
 import yaml
-from pydantic import BaseModel, model_validator
+from pydantic import BaseModel, field_validator, model_validator
 
 from deerflow.config.paths import get_paths
 
@@ -82,7 +82,7 @@ class CommonQuestion(BaseModel):
         return value
 
 
-class AgentConfig(BaseModel):
+class AgentConfig(BaseModel):
     """Configuration for a custom agent."""
 
     id: str | None = None
@@ -108,7 +108,20 @@ class AgentConfig(BaseModel):
     # 拼进本轮任务，避免弱模型无视系统提示里的技能块。None/False = 关（默认）；True = 开。
     # 与「业务链条配置」里的同名开关取 OR：任一打开即对该席位生效。见
     # ``app/gateway/roundtable_seat_skills.py``。
-    seat_skill_directive: bool | None = None
+    seat_skill_directive: bool | None = None
+    # DeerFlow mapping ids this agent may offer in its new-conversation
+    # knowledge selector. WeKnora ids and credentials never enter agent files.
+    llmwiki_knowledge_base_ids: list[str] | None = None
+
+    @field_validator("llmwiki_knowledge_base_ids")
+    @classmethod
+    def _normalize_llmwiki_ids(cls, value: list[str] | None) -> list[str] | None:
+        if value is None:
+            return None
+        normalized = list(dict.fromkeys(str(item).strip() for item in value if str(item).strip()))
+        if len(normalized) > 100:
+            raise ValueError("An agent can bind at most 100 LLMWiki knowledge bases")
+        return normalized
 
 
 def load_agent_config(agent_id: str | None) -> AgentConfig | None:

offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py

@@ -17,10 +17,11 @@ 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.knowledge_config import KnowledgeConfig
-from deerflow.config.knowledge_ingest_config import KnowledgeIngestConfig
-from deerflow.config.log_system_config import LogSystemConfig
-from deerflow.config.login_config import AuthLoginConfig
+from deerflow.config.knowledge_config import KnowledgeConfig
+from deerflow.config.knowledge_ingest_config import KnowledgeIngestConfig
+from deerflow.config.llmwiki_config import LlmWikiConfig
+from deerflow.config.log_system_config import LogSystemConfig
+from deerflow.config.login_config import AuthLoginConfig
 from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
 from deerflow.config.run_events_config import RunEventsConfig
@@ -42,7 +43,8 @@ from deerflow.config.tool_search_config import ToolSearchConfig, load_tool_searc
 from deerflow.config.vision_config import VisionConfig
 from deerflow.config.y_log_config import YLogConfig
 
-load_dotenv()
+load_dotenv()
+load_dotenv(Path(__file__).resolve().parents[4] / ".env.local", override=True)
 
 logger = logging.getLogger(__name__)
 
@@ -115,7 +117,8 @@ class AppConfig(BaseModel):
     models: list[ModelConfig] = Field(default_factory=list, description="Available models")
     vision: VisionConfig = Field(default_factory=VisionConfig, description="Image recognition (识图) configuration")
     auth_login: AuthLoginConfig = Field(default_factory=AuthLoginConfig, description="Custom login modes (username password gate, token exchange)")
-    log_system: LogSystemConfig = Field(default_factory=LogSystemConfig, description="Admin-only external log-system entry shown in the settings menu")
+    log_system: LogSystemConfig = Field(default_factory=LogSystemConfig, description="Admin-only external log-system entry shown in the settings menu")
+    llmwiki: LlmWikiConfig = Field(default_factory=LlmWikiConfig, description="Conditional legacy/WeKnora LLMWiki integration")
     sandbox: SandboxConfig = Field(description="Sandbox configuration")
     tools: list[ToolConfig] = Field(default_factory=list, description="Available tools")
     tool_groups: list[ToolGroupConfig] = Field(default_factory=list, description="Available tool groups")

offline-backend-20260512/backend/packages/harness/deerflow/config/llmwiki_config.py

@@ -0,0 +1,117 @@
+"""Conditional LLMWiki provider configuration.
+
+DeerFlow owns only the connection to WeKnora. Database, Redis, document
+parsing, storage and model configuration stay entirely in WeKnora's own
+deployment files. An effective non-empty API URL is the sole provider switch.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.parse import urlsplit, urlunsplit
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+def normalize_service_url(value: str | None) -> str:
+    """Normalize an optional HTTP(S) service URL and reject embedded secrets."""
+
+    raw = str(value or "").strip()
+    if not raw:
+        return ""
+    parsed = urlsplit(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("WeKnora addresses must be absolute http(s) URLs")
+    if parsed.username is not None or parsed.password is not None:
+        raise ValueError("WeKnora addresses must not contain credentials")
+    if parsed.query or parsed.fragment:
+        raise ValueError("WeKnora addresses must not contain query strings or fragments")
+    path = parsed.path.rstrip("/")
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+class WeKnoraConnectionConfig(BaseModel):
+    """The complete DeerFlow-owned connection surface for WeKnora."""
+
+    api_base_url: str = Field(default="", description="WeKnora app API base URL; non-empty enables WeKnora mode")
+    web_base_url: str = Field(default="", description="Optional internal WeKnora administration URL")
+    admin_email: str = Field(
+        default="",
+        description=(
+            "Optional WeKnora administrator email used only by DeerFlow's "
+            "server-side detail-page iframe proxy. Prefer $ENV references."
+        ),
+    )
+    admin_password: str = Field(
+        default="",
+        repr=False,
+        description=(
+            "Optional WeKnora administrator password used only by DeerFlow's "
+            "server-side detail-page iframe proxy. Prefer $ENV references."
+        ),
+    )
+    model_config = ConfigDict(extra="ignore")
+
+    @field_validator("api_base_url", "web_base_url")
+    @classmethod
+    def _validate_url(cls, value: str) -> str:
+        return normalize_service_url(value)
+
+
+class LlmWikiConfig(BaseModel):
+    """Top-level ``config.yaml`` section for conditional WeKnora mode."""
+
+    weknora: WeKnoraConnectionConfig = Field(default_factory=WeKnoraConnectionConfig)
+    model_config = ConfigDict(extra="ignore")
+
+
+class LlmWikiRuntimeOverride(BaseModel):
+    """Administrator-written URL override stored in system settings.
+
+    ``enabled=False`` means "use config.yaml". When enabled, an empty API URL
+    deliberately forces legacy mode even if the source file has an address.
+    Secrets are never stored here.
+    """
+
+    enabled: bool = False
+    api_base_url: str = ""
+    web_base_url: str = ""
+    model_config = ConfigDict(extra="ignore")
+
+    @field_validator("api_base_url", "web_base_url")
+    @classmethod
+    def _validate_url(cls, value: str) -> str:
+        return normalize_service_url(value)
+
+
+@dataclass(frozen=True)
+class ResolvedLlmWikiRuntime:
+    provider: str
+    api_base_url: str
+    web_base_url: str
+    admin_email: str
+    admin_password: str
+    override_enabled: bool
+
+    @property
+    def weknora_enabled(self) -> bool:
+        return self.provider == "weknora"
+
+
+def resolve_llmwiki_runtime(
+    config: LlmWikiConfig,
+    override: LlmWikiRuntimeOverride | None = None,
+) -> ResolvedLlmWikiRuntime:
+    """Resolve the deterministic provider from file config plus URL override."""
+
+    use_override = bool(override and override.enabled)
+    api_base_url = override.api_base_url if use_override and override else config.weknora.api_base_url
+    web_base_url = override.web_base_url if use_override and override else config.weknora.web_base_url
+    return ResolvedLlmWikiRuntime(
+        provider="weknora" if api_base_url else "legacy",
+        api_base_url=api_base_url,
+        web_base_url=web_base_url,
+        admin_email=config.weknora.admin_email,
+        admin_password=config.weknora.admin_password,
+        override_enabled=use_override,
+    )

offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py

@@ -23,6 +23,7 @@ from uuid import uuid4
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from deerflow.config.llmwiki_config import LlmWikiRuntimeOverride
 from deerflow.config.runtime_paths import runtime_home
 
 logger = logging.getLogger(__name__)
@@ -499,6 +500,7 @@ class SystemSettings(BaseModel):
     agent_modules: AgentModuleSettings = Field(default_factory=AgentModuleSettings)
     concurrency_monitor: ConcurrencyMonitorSettings = Field(default_factory=ConcurrencyMonitorSettings)
     model_concurrency: ModelConcurrencySettings = Field(default_factory=ModelConcurrencySettings)
+    llmwiki: LlmWikiRuntimeOverride = Field(default_factory=LlmWikiRuntimeOverride)
     model_config = ConfigDict(extra="ignore")
 
 

offline-backend-20260512/backend/packages/harness/deerflow/config/tool_config.py

@@ -1,20 +1,21 @@
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class ToolGroupConfig(BaseModel):
-    """Config section for a tool group"""
-
-    name: str = Field(..., description="Unique name for the tool group")
-    model_config = ConfigDict(extra="allow")
-
-
-class ToolConfig(BaseModel):
-    """Config section for a tool"""
-
-    name: str = Field(..., description="Unique name for the tool")
-    group: str = Field(..., description="Group name for the tool")
-    use: str = Field(
-        ...,
-        description="Variable name of the tool provider(e.g. deerflow.sandbox.tools:bash_tool)",
-    )
-    model_config = ConfigDict(extra="allow")
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ToolGroupConfig(BaseModel):
+    """Config section for a tool group"""
+
+    name: str = Field(..., description="Unique name for the tool group")
+    model_config = ConfigDict(extra="allow")
+
+
+class ToolConfig(BaseModel):
+    """Config section for a tool"""
+
+    name: str = Field(..., description="Unique name for the tool")
+    group: str = Field(..., description="Group name for the tool")
+    enabled: bool = Field(default=True, description="Whether the tool is registered with the agent")
+    use: str = Field(
+        ...,
+        description="Variable name of the tool provider(e.g. deerflow.sandbox.tools:bash_tool)",
+    )
+    model_config = ConfigDict(extra="allow")

offline-backend-20260512/backend/packages/harness/deerflow/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""External service integrations owned by the DeerFlow harness."""
+

offline-backend-20260512/backend/packages/harness/deerflow/integrations/weknora/__init__.py

@@ -0,0 +1,5 @@
+"""WeKnora REST integration."""
+
+from deerflow.integrations.weknora.client import WeKnoraClient, WeKnoraError
+
+__all__ = ["WeKnoraClient", "WeKnoraError"]

offline-backend-20260512/backend/packages/harness/deerflow/integrations/weknora/client.py

@@ -0,0 +1,450 @@
+"""Small, version-pinned adapter over WeKnora's official REST API."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+
+class WeKnoraError(RuntimeError):
+    """Normalized upstream failure that is safe for DeerFlow to translate."""
+
+    def __init__(self, message: str, *, status_code: int = 502) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _data(payload: Any) -> Any:
+    if not isinstance(payload, dict):
+        raise WeKnoraError("WeKnora returned an invalid response")
+    if payload.get("success") is False:
+        message = payload.get("message") or payload.get("error") or "WeKnora rejected the request"
+        raise WeKnoraError(str(message), status_code=400)
+    return payload.get("data", payload)
+
+
+def _as_list(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, list):
+        return [dict(item) for item in value if isinstance(item, Mapping)]
+    if isinstance(value, dict):
+        for key in ("items", "list", "knowledge_bases", "knowledge", "records"):
+            nested = value.get(key)
+            if isinstance(nested, list):
+                return [dict(item) for item in nested if isinstance(item, Mapping)]
+    return []
+
+
+class WeKnoraClient:
+    """Async client for a trusted-network WeKnora endpoint.
+
+    The caller may inject an ``httpx.AsyncClient`` for connection pooling and
+    tests. When omitted, each public method creates and closes a short-lived
+    client. DeerFlow deliberately sends no WeKnora credential; the independently
+    deployed service or its reverse proxy must allow DeerFlow's internal traffic.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        timeout_seconds: float = 30.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout_seconds = timeout_seconds
+        self._http_client = http_client
+        if not self.base_url:
+            raise ValueError("WeKnora base URL is required")
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Mapping[str, Any] | None = None,
+        files: Any = None,
+        data: Mapping[str, Any] | None = None,
+    ) -> Any:
+        headers = {"Accept": "application/json"}
+        owns_client = self._http_client is None
+        client = self._http_client or httpx.AsyncClient(timeout=httpx.Timeout(self.timeout_seconds), follow_redirects=False)
+        try:
+            response = await client.request(
+                method,
+                f"{self.base_url}{path}",
+                headers=headers,
+                json=json,
+                params=params,
+                files=files,
+                data=data,
+            )
+        except httpx.TimeoutException as exc:
+            raise WeKnoraError("WeKnora request timed out", status_code=504) from exc
+        except httpx.HTTPError as exc:
+            raise WeKnoraError("WeKnora is unavailable", status_code=502) from exc
+        finally:
+            if owns_client:
+                await client.aclose()
+        if response.status_code == 404:
+            raise WeKnoraError("WeKnora resource was not found", status_code=404)
+        if response.status_code in {401, 403}:
+            raise WeKnoraError(
+                "WeKnora rejected DeerFlow's anonymous internal request; allow DeerFlow in WeKnora or its reverse proxy",
+                status_code=502,
+            )
+        if response.status_code >= 400:
+            detail = ""
+            try:
+                body = response.json()
+                if isinstance(body, dict):
+                    detail = str(body.get("message") or body.get("error") or body.get("detail") or "")
+            except ValueError:
+                detail = ""
+            raise WeKnoraError(detail or f"WeKnora returned HTTP {response.status_code}", status_code=502)
+        if response.status_code == 204 or not response.content:
+            return {"success": True}
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise WeKnoraError("WeKnora returned invalid JSON") from exc
+
+    async def health(self) -> dict[str, Any]:
+        payload = await self._request("GET", "/health")
+        return dict(payload) if isinstance(payload, dict) else {"status": "ok"}
+
+    async def list_knowledge_bases(self) -> list[dict[str, Any]]:
+        return _as_list(_data(await self._request("GET", "/api/v1/knowledge-bases")))
+
+    async def get_knowledge_base(self, knowledge_base_id: str) -> dict[str, Any]:
+        value = _data(await self._request("GET", f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}"))
+        if not isinstance(value, dict):
+            raise WeKnoraError("WeKnora returned an invalid knowledge base")
+        return dict(value)
+
+    async def list_models(self) -> list[dict[str, Any]]:
+        """List models from WeKnora; model credentials are never returned."""
+
+        return _as_list(_data(await self._request("GET", "/api/v1/models")))
+
+    async def get_default_embedding_model_id(self) -> str:
+        models = [item for item in await self.list_models() if str(item.get("type") or "").strip().lower() == "embedding"]
+        preferred = next((item for item in models if item.get("is_default") is True), None)
+        selected = preferred or next(
+            (item for item in models if str(item.get("status") or "active").lower() == "active"),
+            None,
+        )
+        model_id = str((selected or {}).get("id") or "")
+        if not model_id:
+            raise WeKnoraError(
+                "WeKnora has no available embedding model; configure its default model in WeKnora",
+                status_code=400,
+            )
+        return model_id
+
+    async def get_default_knowledge_qa_model_id(self) -> str:
+        """Resolve WeKnora's own active synthesis model for Wiki indexing."""
+
+        models = [item for item in await self.list_models() if str(item.get("type") or "").strip().lower() == "knowledgeqa"]
+        preferred = next((item for item in models if item.get("is_default") is True), None)
+        selected = preferred or next(
+            (item for item in models if str(item.get("status") or "active").lower() == "active"),
+            None,
+        )
+        model_id = str((selected or {}).get("id") or "")
+        if not model_id:
+            raise WeKnoraError(
+                "WeKnora has no available KnowledgeQA model; configure one in WeKnora before creating a Wiki",
+                status_code=400,
+            )
+        return model_id
+
+    async def create_knowledge_base(
+        self,
+        *,
+        name: str,
+        description: str = "",
+        kb_type: str = "document",
+        embedding_model_id: str | None = None,
+        wiki_enabled: bool = False,
+    ) -> dict[str, Any]:
+        model_id = embedding_model_id or await self.get_default_embedding_model_id()
+        create_payload: dict[str, Any] = {
+            "name": name,
+            "description": description,
+            "type": kb_type,
+            "embedding_model_id": model_id,
+        }
+        if wiki_enabled:
+            synthesis_model_id = await self.get_default_knowledge_qa_model_id()
+            create_payload.update(
+                {
+                    "summary_model_id": synthesis_model_id,
+                    "indexing_strategy": {
+                        "vector_enabled": True,
+                        "keyword_enabled": True,
+                        "wiki_enabled": True,
+                        "graph_enabled": False,
+                    },
+                    "wiki_config": {
+                        "synthesis_model_id": synthesis_model_id,
+                        "extraction_granularity": "standard",
+                    },
+                }
+            )
+        payload = await self._request(
+            "POST",
+            "/api/v1/knowledge-bases",
+            json=create_payload,
+        )
+        value = _data(payload)
+        if not isinstance(value, dict) or not value.get("id"):
+            raise WeKnoraError("WeKnora did not return the created knowledge base")
+        return dict(value)
+
+    async def update_knowledge_base(self, knowledge_base_id: str, changes: Mapping[str, Any]) -> dict[str, Any]:
+        payload = dict(changes)
+        if not str(payload.get("name") or "").strip():
+            current = await self.get_knowledge_base(knowledge_base_id)
+            current_name = str(current.get("name") or "").strip()
+            if not current_name:
+                raise WeKnoraError("WeKnora knowledge base name is required for updates")
+            payload["name"] = current_name
+        value = _data(
+            await self._request(
+                "PUT",
+                f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}",
+                json=payload,
+            )
+        )
+        return dict(value) if isinstance(value, dict) else {}
+
+    async def delete_knowledge_base(self, knowledge_base_id: str) -> None:
+        await self._request("DELETE", f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}")
+
+    async def list_documents(self, knowledge_base_id: str, *, page: int = 1, page_size: int = 100) -> dict[str, Any]:
+        payload = await self._request(
+            "GET",
+            f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}/knowledge",
+            params={"page": page, "page_size": page_size},
+        )
+        rows = _as_list(_data(payload))
+        total = payload.get("total", len(rows)) if isinstance(payload, dict) else len(rows)
+        return {"items": rows, "total": int(total or 0), "page": page, "page_size": page_size}
+
+    async def upload_document(
+        self,
+        knowledge_base_id: str,
+        *,
+        filename: str,
+        content: bytes,
+        content_type: str = "application/octet-stream",
+    ) -> dict[str, Any]:
+        value = _data(
+            await self._request(
+                "POST",
+                f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}/knowledge/file",
+                files={"file": (filename, content, content_type)},
+            )
+        )
+        return dict(value) if isinstance(value, dict) else {}
+
+    async def import_document_url(self, knowledge_base_id: str, *, url: str) -> dict[str, Any]:
+        value = _data(
+            await self._request(
+                "POST",
+                f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}/knowledge/url",
+                json={"url": url},
+            )
+        )
+        return dict(value) if isinstance(value, dict) else {}
+
+    async def create_manual_document(
+        self,
+        knowledge_base_id: str,
+        *,
+        title: str,
+        content: str,
+    ) -> dict[str, Any]:
+        value = _data(
+            await self._request(
+                "POST",
+                f"/api/v1/knowledge-bases/{quote(knowledge_base_id, safe='')}/knowledge/manual",
+                json={"title": title, "content": content, "status": "publish"},
+            )
+        )
+        return dict(value) if isinstance(value, dict) else {}
+
+    async def delete_document(self, knowledge_id: str) -> None:
+        await self._request("DELETE", f"/api/v1/knowledge/{quote(knowledge_id, safe='')}")
+
+    async def get_document(self, knowledge_id: str) -> dict[str, Any]:
+        value = _data(await self._request("GET", f"/api/v1/knowledge/{quote(knowledge_id, safe='')}"))
+        if not isinstance(value, dict):
+            raise WeKnoraError("WeKnora returned an invalid document")
+        return dict(value)
+
+    async def get_document_preview(self, knowledge_id: str) -> tuple[bytes, str]:
+        """Return the original document preview bytes and its media type."""
+
+        owns_client = self._http_client is None
+        client = self._http_client or httpx.AsyncClient(
+            timeout=httpx.Timeout(self.timeout_seconds),
+            follow_redirects=True,
+        )
+        try:
+            response = await client.request(
+                "GET",
+                f"{self.base_url}/api/v1/knowledge/{quote(knowledge_id, safe='')}/preview",
+                headers={"Accept": "*/*"},
+                follow_redirects=True,
+            )
+        except httpx.TimeoutException as exc:
+            raise WeKnoraError("WeKnora preview request timed out", status_code=504) from exc
+        except httpx.HTTPError as exc:
+            raise WeKnoraError("WeKnora preview is unavailable", status_code=502) from exc
+        finally:
+            if owns_client:
+                await client.aclose()
+        if response.status_code == 404:
+            raise WeKnoraError("WeKnora document preview was not found", status_code=404)
+        if response.status_code in {401, 403}:
+            raise WeKnoraError(
+                "WeKnora rejected DeerFlow's anonymous internal request; allow DeerFlow in WeKnora or its reverse proxy",
+                status_code=502,
+            )
+        if response.status_code >= 400:
+            raise WeKnoraError(f"WeKnora returned HTTP {response.status_code}", status_code=502)
+        media_type = response.headers.get("content-type", "application/octet-stream").split(";", 1)[0].strip()
+        return response.content, media_type or "application/octet-stream"
+
+    async def reprocess_document(self, knowledge_id: str) -> dict[str, Any]:
+        value = _data(await self._request("POST", f"/api/v1/knowledge/{quote(knowledge_id, safe='')}/reparse"))
+        return dict(value) if isinstance(value, dict) else {}
+
+    async def list_chunks(self, knowledge_id: str, *, page: int = 1, page_size: int = 20) -> dict[str, Any]:
+        payload = await self._request(
+            "GET",
+            f"/api/v1/chunks/{quote(knowledge_id, safe='')}",
+            params={"page": page, "page_size": page_size},
+        )
+        rows = _as_list(_data(payload))
+        total = payload.get("total", len(rows)) if isinstance(payload, dict) else len(rows)
+        return {"items": rows, "total": int(total or 0), "page": page, "page_size": page_size}
+
+    async def get_wiki_graph(self, knowledge_base_id: str, *, limit: int = 200) -> dict[str, Any]:
+        value = _data(
+            await self._request(
+                "GET",
+                f"/api/v1/knowledgebase/{quote(knowledge_base_id, safe='')}/wiki/graph",
+                params={"mode": "overview", "limit": max(1, min(limit, 500))},
+            )
+        )
+        if not isinstance(value, dict):
+            raise WeKnoraError("WeKnora returned an invalid wiki graph")
+        return dict(value)
+
+    async def list_wiki_pages(
+        self,
+        knowledge_base_id: str,
+        *,
+        page: int = 1,
+        page_size: int = 50,
+        query: str = "",
+    ) -> dict[str, Any]:
+        payload = await self._request(
+            "GET",
+            f"/api/v1/knowledgebase/{quote(knowledge_base_id, safe='')}/wiki/pages",
+            params={"page": page, "page_size": page_size, "query": query or None},
+        )
+        value = _data(payload)
+        source = value if isinstance(value, dict) else payload if isinstance(payload, dict) else {}
+        rows = _as_list(source.get("pages") if isinstance(source, dict) else value)
+        return {
+            "pages": rows,
+            "total": int(source.get("total") or len(rows)),
+            "page": int(source.get("page") or page),
+            "page_size": int(source.get("page_size") or page_size),
+            "total_pages": int(source.get("total_pages") or max(1, (int(source.get("total") or len(rows)) + page_size - 1) // page_size)),
+        }
+
+    async def get_wiki_page(self, knowledge_base_id: str, slug: str) -> dict[str, Any]:
+        safe_slug = "/".join(quote(part, safe="") for part in slug.split("/"))
+        value = _data(
+            await self._request(
+                "GET",
+                f"/api/v1/knowledgebase/{quote(knowledge_base_id, safe='')}/wiki/pages/{safe_slug}",
+            )
+        )
+        if not isinstance(value, dict):
+            raise WeKnoraError("WeKnora returned an invalid Wiki page")
+        return dict(value)
+
+    async def search(self, query: str, knowledge_base_ids: Sequence[str]) -> list[dict[str, Any]]:
+        ids = [str(value) for value in knowledge_base_ids if str(value)]
+        if not ids:
+            return []
+        rows = _as_list(
+            _data(
+                await self._request(
+                    "POST",
+                    "/api/v1/knowledge-search",
+                    json={"query": query, "knowledge_base_ids": ids},
+                )
+            )
+        )
+        normalized: list[dict[str, Any]] = []
+        for row in rows:
+            normalized.append(
+                {
+                    "chunk_id": str(row.get("id") or row.get("chunk_id") or ""),
+                    "content": str(row.get("content") or ""),
+                    "knowledge_id": str(row.get("knowledge_id") or ""),
+                    "knowledge_base_id": str(row.get("knowledge_base_id") or ""),
+                    "title": str(row.get("knowledge_title") or row.get("title") or row.get("knowledge_filename") or ""),
+                    "filename": str(row.get("knowledge_filename") or ""),
+                    "score": float(row.get("score") or 0),
+                    "chunk_index": int(row.get("chunk_index") or 0),
+                    "metadata": row.get("metadata") if isinstance(row.get("metadata"), dict) else {},
+                }
+            )
+        return normalized
+
+    async def get_chunk(self, chunk_id: str) -> dict[str, Any]:
+        value = _data(await self._request("GET", f"/api/v1/chunks/by-id/{quote(chunk_id, safe='')}"))
+        if not isinstance(value, dict):
+            raise WeKnoraError("WeKnora returned an invalid chunk")
+        return dict(value)
+
+    async def get_chunk_context(self, chunk_id: str, *, expected_knowledge_base_id: str, radius: int = 2) -> list[dict[str, Any]]:
+        center = await self.get_chunk(chunk_id)
+        if str(center.get("knowledge_base_id") or "") != expected_knowledge_base_id:
+            raise WeKnoraError("Chunk does not belong to the authorized knowledge base", status_code=404)
+
+        before: list[dict[str, Any]] = []
+        cursor = center
+        for _ in range(max(0, min(radius, 4))):
+            previous_id = str(cursor.get("pre_chunk_id") or "")
+            if not previous_id:
+                break
+            previous = await self.get_chunk(previous_id)
+            if str(previous.get("knowledge_base_id") or "") != expected_knowledge_base_id:
+                break
+            before.append(previous)
+            cursor = previous
+
+        after: list[dict[str, Any]] = []
+        cursor = center
+        for _ in range(max(0, min(radius, 4))):
+            next_id = str(cursor.get("next_chunk_id") or "")
+            if not next_id:
+                break
+            following = await self.get_chunk(next_id)
+            if str(following.get("knowledge_base_id") or "") != expected_knowledge_base_id:
+                break
+            after.append(following)
+            cursor = following
+        return [*reversed(before), center, *after]