From 9a63a4b7ca7fe757cc4d3d76a1ab33d7a7412d67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Mon, 25 May 2026 14:17:39 +0800
Subject: [PATCH 01/15] =?UTF-8?q?=E6=8A=80=E8=83=BD=E8=AF=A6=E6=83=85?=
 =?UTF-8?q?=E5=AF=B9=E8=AF=9D=E6=A1=86=E6=96=B0=E5=A2=9E=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E6=B5=8F=E8=A7=88=E9=9D=A2=E6=9D=BF:=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E9=A2=84=E8=A7=88=E3=80=81=E7=BC=96=E8=BE=91=E3=80=81=E4=B8=8B?=
 =?UTF-8?q?=E8=BD=BD=E3=80=81=E5=A4=8D=E5=88=B6=E8=B7=AF=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../workspace/skills/skill-detail-dialog.tsx  |  64 ++-
 frontend-web/src/core/i18n/locales/en-US.ts   |  14 +
 frontend-web/src/core/i18n/locales/types.ts   |  14 +
 frontend-web/src/core/i18n/locales/zh-CN.ts   |  14 +
 frontend-web/src/core/skills/api.ts           |  86 ++++
 frontend-web/src/core/skills/hooks.ts         |  43 ++
 .../backend/app/gateway/routers/skills.py     | 428 ++++++++++++++++++
 offline-backend-20260512/backend/config.yaml  |   2 +-
 8 files changed, 661 insertions(+), 4 deletions(-)

diff --git a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
index 29d6bb9d..ca401519 100644
--- a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
+++ b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
@@ -4,6 +4,7 @@ import {
   CopyIcon,
   EyeIcon,
   FileCode2Icon,
+  FilesIcon,
   FileTextIcon,
   GlobeIcon,
   Loader2,
@@ -25,12 +26,15 @@ import {
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { Textarea } from "@/components/ui/textarea";
 import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
+import { SkillFilePreviewDialog } from "@/components/workspace/skills/skill-file-preview-dialog";
+import { SkillFileTree } from "@/components/workspace/skills/skill-file-tree";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import {
   useSetSkillDetail,
   useSkill,
   useSkillContent,
+  useSkillFiles,
 } from "@/core/skills/hooks";
 import type { Skill } from "@/core/skills/type";
 import { reasoningPlugins } from "@/core/streamdown";
@@ -82,10 +86,11 @@ export function SkillDetailDialog({
 
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState("");
-  const [activeTab, setActiveTab] = useState<"detail" | "source" | null>(
-    null,
-  );
+  const [activeTab, setActiveTab] = useState<
+    "detail" | "source" | "files" | null
+  >(null);
   const [showRawSource, setShowRawSource] = useState(false);
+  const [openedFilePath, setOpenedFilePath] = useState<string | null>(null);
 
   const canManage = useMemo(() => canManageSkill(skill), [skill]);
   const {
@@ -94,10 +99,18 @@ export function SkillDetailDialog({
     error: contentError,
   } = useSkillContent(open && canManage ? skillName : null);
 
+  const filesEnabled = open && canManage && activeTab === "files";
+  const {
+    data: filesData,
+    isLoading: isFilesLoading,
+    error: filesError,
+  } = useSkillFiles(filesEnabled ? skillName : null);
+
   useEffect(() => {
     setEditing(false);
     setActiveTab(null);
     setShowRawSource(false);
+    setOpenedFilePath(null);
   }, [open, skillName]);
 
   const skillBody = useMemo(() => {
@@ -130,6 +143,7 @@ export function SkillDetailDialog({
   }
 
   return (
+    <>
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent
         className="flex flex-col gap-0 overflow-hidden p-0"
@@ -192,6 +206,12 @@ export function SkillDetailDialog({
                 <FileTextIcon className="mr-1 size-3.5" />
                 {tx.detailSectionTitle}
               </TabsTrigger>
+              {canManage && (
+                <TabsTrigger value="files" className="text-xs">
+                  <FilesIcon className="mr-1 size-3.5" />
+                  {tx.filesSectionTitle}
+                </TabsTrigger>
+              )}
               {canManage && (
                 <TabsTrigger value="source" className="text-xs">
                   <FileCode2Icon className="mr-1 size-3.5" />
@@ -309,6 +329,34 @@ export function SkillDetailDialog({
             )}
           </TabsContent>
 
+          {canManage && (
+            <TabsContent
+              value="files"
+              className="m-0 min-h-0 flex-1 overscroll-contain px-6 py-4 data-[state=inactive]:hidden"
+              style={{ overflowY: "auto" }}
+            >
+              {isFilesLoading ? (
+                <div className="text-muted-foreground flex items-center justify-center gap-2 py-12 text-sm">
+                  <Loader2 className="size-4 animate-spin" />
+                  {t.common.loading}
+                </div>
+              ) : filesError ? (
+                <div className="text-destructive py-6 text-sm">
+                  {filesError instanceof Error
+                    ? filesError.message
+                    : String(filesError)}
+                </div>
+              ) : filesData ? (
+                <SkillFileTree
+                  root={filesData.root}
+                  selectedPath={openedFilePath}
+                  onOpen={(path) => setOpenedFilePath(path)}
+                  emptyText={tx.filesEmpty}
+                />
+              ) : null}
+            </TabsContent>
+          )}
+
           {canManage && (
             <TabsContent
               value="source"
@@ -345,5 +393,15 @@ export function SkillDetailDialog({
         )}
       </DialogContent>
     </Dialog>
+    <SkillFilePreviewDialog
+      skillName={skill?.name ?? null}
+      path={openedFilePath}
+      treeEditable={!!filesData?.editable}
+      open={!!openedFilePath}
+      onOpenChange={(next) => {
+        if (!next) setOpenedFilePath(null);
+      }}
+    />
+    </>
   );
 }
diff --git a/frontend-web/src/core/i18n/locales/en-US.ts b/frontend-web/src/core/i18n/locales/en-US.ts
index 210dd65d..8b602073 100644
--- a/frontend-web/src/core/i18n/locales/en-US.ts
+++ b/frontend-web/src/core/i18n/locales/en-US.ts
@@ -501,6 +501,20 @@ export const enUS: Translations = {
       detailAdminOnlyHint:
         "Only an admin or the skill publisher can edit the details.",
       contentSectionTitle: "SKILL.md source",
+      filesSectionTitle: "Files",
+      filesEmpty: "This skill has no files to display.",
+      filesLoadError: "Failed to load files",
+      filesPreviewBinary: "Binary file cannot be previewed inline — use Download.",
+      filesPreviewUnsupported: "This file type is not supported for inline preview.",
+      filesPreviewTooLarge: "File is too large for inline preview.",
+      filesEditAction: "Edit",
+      filesSaveAction: "Save",
+      filesCancelEditAction: "Cancel",
+      filesDownloadAction: "Download",
+      filesCopyPathAction: "Copy path",
+      filesDiscardConfirm: "Discard unsaved changes?",
+      filesSaveSuccess: "File saved",
+      filesReadOnlyHint: "Built-in skills are read-only.",
       viewDetailAction: "View skill details",
       stateSheet: {
         archivedTitle: "Archived skills",
diff --git a/frontend-web/src/core/i18n/locales/types.ts b/frontend-web/src/core/i18n/locales/types.ts
index 532692d4..5051292c 100644
--- a/frontend-web/src/core/i18n/locales/types.ts
+++ b/frontend-web/src/core/i18n/locales/types.ts
@@ -432,6 +432,20 @@ export interface Translations {
       detailSaveSuccess: string;
       detailAdminOnlyHint: string;
       contentSectionTitle: string;
+      filesSectionTitle: string;
+      filesEmpty: string;
+      filesLoadError: string;
+      filesPreviewBinary: string;
+      filesPreviewUnsupported: string;
+      filesPreviewTooLarge: string;
+      filesEditAction: string;
+      filesSaveAction: string;
+      filesCancelEditAction: string;
+      filesDownloadAction: string;
+      filesCopyPathAction: string;
+      filesDiscardConfirm: string;
+      filesSaveSuccess: string;
+      filesReadOnlyHint: string;
       viewDetailAction: string;
       stateSheet: {
         archivedTitle: string;
diff --git a/frontend-web/src/core/i18n/locales/zh-CN.ts b/frontend-web/src/core/i18n/locales/zh-CN.ts
index 5e1e0688..b58d38b8 100644
--- a/frontend-web/src/core/i18n/locales/zh-CN.ts
+++ b/frontend-web/src/core/i18n/locales/zh-CN.ts
@@ -479,6 +479,20 @@ export const zhCN: Translations = {
       detailSaveSuccess: "详情已更新",
       detailAdminOnlyHint: "仅管理员或技能发布者可编辑详情。",
       contentSectionTitle: "SKILL.md 原文",
+      filesSectionTitle: "文件",
+      filesEmpty: "该技能目录下没有可显示的文件。",
+      filesLoadError: "加载文件失败",
+      filesPreviewBinary: "二进制文件无法预览,可点击下载查看。",
+      filesPreviewUnsupported: "该文件类型暂不支持预览。",
+      filesPreviewTooLarge: "文件过大,无法在线预览。",
+      filesEditAction: "编辑",
+      filesSaveAction: "保存",
+      filesCancelEditAction: "取消",
+      filesDownloadAction: "下载",
+      filesCopyPathAction: "复制路径",
+      filesDiscardConfirm: "有未保存的修改,确定放弃吗?",
+      filesSaveSuccess: "文件已保存",
+      filesReadOnlyHint: "内置技能为只读,仅可查看。",
       viewDetailAction: "查看技能详情",
       stateSheet: {
         archivedTitle: "归档的技能",
diff --git a/frontend-web/src/core/skills/api.ts b/frontend-web/src/core/skills/api.ts
index 25428dcb..3b31cde1 100644
--- a/frontend-web/src/core/skills/api.ts
+++ b/frontend-web/src/core/skills/api.ts
@@ -239,6 +239,92 @@ export async function deleteCustomSkill(skillName: string): Promise<void> {
   }
 }
 
+export interface SkillFileNode {
+  name: string;
+  type: "file" | "dir";
+  path: string;
+  size?: number | null;
+  mtime?: number | null;
+  children?: SkillFileNode[] | null;
+}
+
+export interface SkillFilesResponse {
+  name: string;
+  category: "public" | "custom";
+  editable: boolean;
+  root: SkillFileNode;
+}
+
+export interface SkillFileContentResponse {
+  name: string;
+  category: "public" | "custom";
+  path: string;
+  mime: string;
+  size: number;
+  mtime: number;
+  is_text: boolean;
+  editable: boolean;
+  content?: string | null;
+}
+
+export interface SkillFileSaveResponse {
+  name: string;
+  path: string;
+  size: number;
+  mtime: number;
+}
+
+export async function getSkillFiles(skillName: string): Promise<SkillFilesResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files`,
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to load skill files");
+  }
+  return response.json() as Promise<SkillFilesResponse>;
+}
+
+export async function getSkillFileContent(
+  skillName: string,
+  path: string,
+): Promise<SkillFileContentResponse> {
+  const url =
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files/content` +
+    `?path=${encodeURIComponent(path)}`;
+  const response = await apiFetch(url);
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to read skill file");
+  }
+  return response.json() as Promise<SkillFileContentResponse>;
+}
+
+/** URL suitable for direct `<img>` / `<iframe>` / `<a download>` embedding. */
+export function getSkillFileDownloadURL(skillName: string, path: string): string {
+  return (
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files/download` +
+    `?path=${encodeURIComponent(path)}`
+  );
+}
+
+export async function saveSkillFile(
+  skillName: string,
+  path: string,
+  content: string,
+): Promise<SkillFileSaveResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/files/content`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path, content }),
+    },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to save skill file");
+  }
+  return response.json() as Promise<SkillFileSaveResponse>;
+}
+
 export interface SetSkillDetailResponse {
   name: string;
   detail: string | null;
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index 1fa8f85e..462206df 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -10,8 +10,11 @@ import {
   enableSkill,
   getSkill,
   getSkillContent,
+  getSkillFileContent,
+  getSkillFiles,
   installSkillUpload,
   reconcileCustomSkills,
+  saveSkillFile,
   setSkillDetail,
   setSkillPinned,
   setSkillPublished,
@@ -153,3 +156,43 @@ export function useDeleteCustomSkill() {
     },
   });
 }
+
+export function useSkillFiles(skillName: string | null) {
+  return useQuery({
+    queryKey: ["skill-files", skillName],
+    queryFn: () => getSkillFiles(skillName!),
+    enabled: !!skillName,
+  });
+}
+
+export function useSkillFileContent(skillName: string | null, path: string | null) {
+  return useQuery({
+    queryKey: ["skill-file", skillName, path],
+    queryFn: () => getSkillFileContent(skillName!, path!),
+    enabled: !!skillName && !!path,
+  });
+}
+
+export function useSaveSkillFile() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      skillName,
+      path,
+      content,
+    }: {
+      skillName: string;
+      path: string;
+      content: string;
+    }) => saveSkillFile(skillName, path, content),
+    onSuccess: (_data, { skillName, path }) => {
+      void queryClient.invalidateQueries({ queryKey: ["skill-files", skillName] });
+      void queryClient.invalidateQueries({ queryKey: ["skill-file", skillName, path] });
+      // SKILL.md edits also affect the source-tab view and skill metadata.
+      if (path === "SKILL.md") {
+        void queryClient.invalidateQueries({ queryKey: ["skill-content", skillName] });
+        void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
+      }
+    },
+  });
+}
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index 4a2bc3ad..b3579899 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -1,11 +1,13 @@
 import json
 import logging
+import mimetypes
 import tempfile
 from datetime import datetime
 from pathlib import Path
 from typing import Any
 
 from fastapi import APIRouter, Body, Depends, File, HTTPException, Query, Request, UploadFile
+from fastapi.responses import FileResponse
 from pydantic import BaseModel, Field
 
 from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_tag_store
@@ -974,6 +976,432 @@ async def get_skill_content(
         raise HTTPException(status_code=500, detail=f"Failed to get skill content: {str(e)}")
 
 
+# ---------------------------------------------------------------------------
+# Skill files browser (tree + per-file read / write)
+# ---------------------------------------------------------------------------
+
+
+_SKILL_FILE_TEXT_EXTS = {
+    ".md", ".markdown", ".txt", ".rst",
+    ".py", ".pyi",
+    ".json", ".jsonl",
+    ".yaml", ".yml",
+    ".toml", ".ini", ".cfg", ".env",
+    ".sh", ".bash", ".zsh", ".ps1",
+    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".html", ".htm", ".css", ".scss", ".sass", ".xml", ".svg",
+    ".csv", ".tsv",
+    ".sql",
+}
+_SKILL_FILE_TREE_SKIP_NAMES = {
+    "__pycache__", "node_modules", ".git", ".DS_Store", ".idea", ".vscode",
+}
+_SKILL_FILE_MAX_NODES = 2000
+_SKILL_FILE_MAX_DEPTH = 8
+_SKILL_FILE_READ_BYTES = 2 * 1024 * 1024   # 2 MiB cap on JSON content payload
+_SKILL_FILE_WRITE_BYTES = 1 * 1024 * 1024  # 1 MiB cap on edits
+
+
+class SkillFileNode(BaseModel):
+    """One entry in a skill's file tree.
+
+    ``children`` is only set for directories. ``path`` is POSIX-style and is
+    always relative to the skill's own directory (never absolute).
+    """
+
+    name: str = Field(..., description="Base name (no slashes)")
+    type: str = Field(..., description="'file' or 'dir'")
+    path: str = Field(..., description="Path relative to the skill directory, POSIX-separated")
+    size: int | None = Field(default=None, description="File size in bytes (files only)")
+    mtime: float | None = Field(default=None, description="Modification time as POSIX seconds (files only)")
+    children: list["SkillFileNode"] | None = Field(default=None, description="Child entries (directories only)")
+
+
+SkillFileNode.model_rebuild()
+
+
+class SkillFilesResponse(BaseModel):
+    """Tree of files under a skill directory."""
+
+    name: str
+    category: SkillCategory
+    editable: bool = Field(..., description="True when the caller may PUT new content into any file under this tree")
+    root: SkillFileNode
+
+
+class SkillFileContentResponse(BaseModel):
+    """JSON payload for reading a single file inside a skill."""
+
+    name: str
+    category: SkillCategory
+    path: str
+    mime: str
+    size: int
+    mtime: float
+    is_text: bool = Field(..., description="True when ``content`` carries the decoded text; otherwise download via the binary endpoint")
+    editable: bool = Field(..., description="True when the caller may PUT new content for this file")
+    content: str | None = Field(default=None, description="Decoded text content when ``is_text`` is True")
+
+
+class SkillFileSaveRequest(BaseModel):
+    """Request body for writing a text file inside a skill."""
+
+    path: str = Field(..., description="File path relative to the skill directory, POSIX-separated")
+    content: str = Field(..., description="Replacement text content")
+
+
+class SkillFileSaveResponse(BaseModel):
+    name: str
+    path: str
+    size: int
+    mtime: float
+
+
+def _normalize_skill_name_param(skill_name: str) -> str:
+    """Strip CR/LF the same way other skill routes do before lookup."""
+    return skill_name.replace("\r\n", "").replace("\n", "")
+
+
+def _load_skill_or_404(skill_name: str, config: AppConfig) -> Skill:
+    skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+    skill = next((s for s in skills if s.name == skill_name), None)
+    if skill is None:
+        raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+    return skill
+
+
+async def _ensure_files_view_allowed(
+    skill: Skill,
+    request: Request,
+    skill_store: SkillStore,
+) -> dict[str, Any] | None:
+    """Mirror _can_view_skill_source: admins or the publisher (custom owner)."""
+    record = await skill_store.get_any(skill.name)
+    owner_user_id = record.get("owner_user_id") if record else None
+    user_id = _current_user_id(request)
+    if not _can_view_skill_source(skill.category, owner_user_id, user_id, is_admin=_is_admin_user(request)):
+        raise HTTPException(status_code=403, detail="Only the skill publisher or an admin can browse skill files")
+    return record
+
+
+def _caller_can_edit_skill_files(
+    skill: Skill,
+    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
+    if _is_admin_user(request):
+        return True
+    if record is None:
+        return False
+    return record.get("owner_user_id") == _current_user_id(request)
+
+
+def _resolve_skill_relative_path(skill: Skill, relative_path: str) -> Path:
+    """Validate *relative_path* against the skill directory and return the absolute Path.
+
+    Rejects empty, absolute, parent-traversing, or out-of-tree paths so a
+    malicious caller can never escape the skill's own directory.
+    """
+    if not relative_path or relative_path.strip() == "":
+        raise HTTPException(status_code=400, detail="path must not be empty")
+    candidate = Path(relative_path)
+    if candidate.is_absolute() or any(part in {"..", ""} for part in candidate.parts):
+        raise HTTPException(status_code=400, detail="path must be a relative path without '..' segments")
+    skill_dir = skill.skill_file.parent.resolve()
+    target = (skill_dir / candidate).resolve()
+    try:
+        target.relative_to(skill_dir)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="path must stay inside the skill directory")
+    return target
+
+
+def _file_mime(path: Path) -> str:
+    """Best-effort MIME guess; defaults to ``application/octet-stream``."""
+    guessed, _ = mimetypes.guess_type(path.name)
+    if guessed:
+        return guessed
+    if path.suffix.lower() in _SKILL_FILE_TEXT_EXTS:
+        return "text/plain"
+    return "application/octet-stream"
+
+
+def _is_text_file(path: Path) -> bool:
+    """Treat known text extensions as text; everything else as binary."""
+    return path.suffix.lower() in _SKILL_FILE_TEXT_EXTS
+
+
+def _build_skill_file_tree(skill_dir: Path) -> SkillFileNode:
+    """Walk *skill_dir* and build a SkillFileNode tree, depth/count capped.
+
+    Hidden files (``.foo``) and a small block-list of noise directories
+    (``__pycache__`` etc.) are skipped so the UI does not drown in housekeeping
+    artefacts.
+    """
+    counter = {"n": 0}
+
+    def build(current_dir: Path, depth: int) -> SkillFileNode:
+        rel = current_dir.relative_to(skill_dir).as_posix()
+        node = SkillFileNode(
+            name=current_dir.name if rel != "." else skill_dir.name,
+            type="dir",
+            path="" if rel == "." else rel,
+            children=[],
+        )
+        if depth >= _SKILL_FILE_MAX_DEPTH:
+            return node
+        try:
+            entries = sorted(current_dir.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except OSError:
+            return node
+        for entry in entries:
+            if counter["n"] >= _SKILL_FILE_MAX_NODES:
+                break
+            if entry.name.startswith(".") or entry.name in _SKILL_FILE_TREE_SKIP_NAMES:
+                continue
+            counter["n"] += 1
+            if entry.is_dir():
+                node.children.append(build(entry, depth + 1))
+                continue
+            try:
+                stat = entry.stat()
+                size = stat.st_size
+                mtime = stat.st_mtime
+            except OSError:
+                size = 0
+                mtime = 0.0
+            node.children.append(
+                SkillFileNode(
+                    name=entry.name,
+                    type="file",
+                    path=entry.relative_to(skill_dir).as_posix(),
+                    size=size,
+                    mtime=mtime,
+                )
+            )
+        return node
+
+    return build(skill_dir, 0)
+
+
+@router.get(
+    "/skills/{skill_name}/files",
+    response_model=SkillFilesResponse,
+    summary="List Skill Files (Tree)",
+    description=(
+        "Return the full file tree under a skill directory. Only an admin or the "
+        "skill's publisher (owner of a custom skill) may browse files; other users "
+        "get 403."
+    ),
+)
+async def list_skill_files(
+    skill_name: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillFilesResponse:
+    try:
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        record = await _ensure_files_view_allowed(skill, request, skill_store)
+        skill_dir = skill.skill_file.parent
+        root = _build_skill_file_tree(skill_dir)
+        return SkillFilesResponse(
+            name=skill.name,
+            category=skill.category,
+            editable=_caller_can_edit_skill_files(skill, record, request),
+            root=root,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to list skill files for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list skill files: {e}")
+
+
+@router.get(
+    "/skills/{skill_name}/files/content",
+    response_model=SkillFileContentResponse,
+    summary="Read Skill File (Text)",
+    description=(
+        "Return JSON metadata for a single file under a skill. Text files include "
+        "their decoded ``content``; binary files omit ``content`` and should be "
+        "fetched from the ``files/download`` endpoint for inline display or "
+        "download. Same view authorisation as the file tree endpoint."
+    ),
+)
+async def get_skill_file_content(
+    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),
+) -> SkillFileContentResponse:
+    try:
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        record = await _ensure_files_view_allowed(skill, request, skill_store)
+        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}'")
+        stat = target.stat()
+        mime = _file_mime(target)
+        is_text = _is_text_file(target)
+        content: str | None = None
+        if is_text:
+            if stat.st_size > _SKILL_FILE_READ_BYTES:
+                raise HTTPException(status_code=413, detail=f"File exceeds the {_SKILL_FILE_READ_BYTES // 1024} KiB preview limit")
+            try:
+                content = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                # File has a text-y extension but is not UTF-8 — treat as binary.
+                is_text = False
+        return SkillFileContentResponse(
+            name=skill.name,
+            category=skill.category,
+            path=target.relative_to(skill.skill_file.parent.resolve()).as_posix(),
+            mime=mime,
+            size=stat.st_size,
+            mtime=stat.st_mtime,
+            is_text=is_text,
+            editable=is_text and _caller_can_edit_skill_files(skill, record, request),
+            content=content,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to read skill file %s/%s: %s", skill_name, path, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read skill file: {e}")
+
+
+@router.get(
+    "/skills/{skill_name}/files/download",
+    summary="Download Skill File (Raw Bytes)",
+    description=(
+        "Stream the raw bytes of a single file under a skill, suitable for "
+        "embedding in an ``<img>`` tag or for direct download. Same view "
+        "authorisation as the file tree endpoint."
+    ),
+)
+async def download_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),
+):
+    skill_name = _normalize_skill_name_param(skill_name)
+    skill = _load_skill_or_404(skill_name, config)
+    await _ensure_files_view_allowed(skill, request, skill_store)
+    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}'")
+    return FileResponse(
+        path=target,
+        media_type=_file_mime(target),
+        filename=target.name,
+    )
+
+
+@router.put(
+    "/skills/{skill_name}/files/content",
+    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 "
+        "refresh the system-prompt cache."
+    ),
+)
+async def save_skill_file(
+    skill_name: str,
+    body: SkillFileSaveRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillFileSaveResponse:
+    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")
+
+        target = _resolve_skill_relative_path(skill, body.path)
+        if not target.exists():
+            raise HTTPException(status_code=404, detail=f"File '{body.path}' not found in skill '{skill_name}'")
+        if target.is_dir():
+            raise HTTPException(status_code=400, detail="path points to a directory")
+        if not _is_text_file(target):
+            raise HTTPException(status_code=400, detail=f"File type '{target.suffix or target.name}' is not editable")
+
+        if len(body.content.encode("utf-8")) > _SKILL_FILE_WRITE_BYTES:
+            raise HTTPException(status_code=413, detail=f"Content exceeds the {_SKILL_FILE_WRITE_BYTES // 1024} KiB edit limit")
+
+        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
+        prev_content: str | None = None
+        if target.exists():
+            try:
+                prev_content = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                prev_content = None
+
+        if is_skill_md:
+            # 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)
+
+        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,
+                },
+            )
+        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)
+
+        if is_skill_md:
+            try:
+                from deerflow.skills.usage import bump_patch
+                bump_patch(skill.name)
+            except Exception:
+                pass
+            await refresh_skills_system_prompt_cache_async()
+
+        stat = target.stat()
+        return SkillFileSaveResponse(
+            name=skill.name,
+            path=relative_posix,
+            size=stat.st_size,
+            mtime=stat.st_mtime,
+        )
+    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 save skill file %s/%s: %s", skill_name, body.path, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to save skill file: {e}")
+
+
 @router.put(
     "/skills/{skill_name}",
     response_model=SkillResponse,
diff --git a/offline-backend-20260512/backend/config.yaml b/offline-backend-20260512/backend/config.yaml
index 3208a97c..7c1e7ce4 100644
--- a/offline-backend-20260512/backend/config.yaml
+++ b/offline-backend-20260512/backend/config.yaml
@@ -124,7 +124,7 @@ sandbox:
   allow_host_bash: true
 
 skills:
-  path: D:\project\bj\deerflow-server\skills
+  path: D:\cursor-work\offline-backend-20260512\backend\skills
   security_scan:
     enabled: false
 

From 8892637b976b550d29c3088b15ccf2ec874d69ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Mon, 25 May 2026 18:19:52 +0800
Subject: [PATCH 02/15] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20RAG=20=E5=BC=95?=
 =?UTF-8?q?=E7=94=A8=E5=B1=95=E7=A4=BA=E6=A8=A1=E5=BC=8F:=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=E6=8A=80=E8=83=BD=E7=BB=93=E6=9E=9C=E6=8C=89=E7=BC=96?=
 =?UTF-8?q?=E5=8F=B7=E5=BC=95=E7=94=A8/=E5=88=97=E8=A1=A8/=E8=A1=A8?=
 =?UTF-8?q?=E6=A0=BC=E6=B8=B2=E6=9F=93?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 前端新增 skill-display 适配层(runtime/display-adapter)与可视化适配面板,
  支持从技能返回 JSON 自动识别字段并配置 citation/list/table/card 展示
- 正文 [[N]] 编号渲染为可点击徽章,点击不跳 URL 而是定位到右侧参考文献面板;
  参考卡片样式重做(圆形编号、悬停高亮、过滤掉 "result" 占位类型)
- bash 工具调用按命令中的 skills/{public,custom}/<name>/ 路径反查展示适配,
  解决调用名为 "bash" 时无法匹配到具体技能的问题
- 工具结果 JSON 解析放宽:能从 stderr/exit code 噪声尾巴里抢救出 JSON 主体
- 展示适配自动识别接入 LLM:读 SKILL.md 让模型推断真实返回结构,失败回退 mock
- 展示适配面板修复保存回显:保存后表单跟随服务端最新值刷新,样例文本不再被抹掉
- 设置页加 "RAG 引用模式" 开关(默认开),关联 lead-agent prompt 注入引用规则
---
 .../components/workspace/chats/chat-box.tsx   | 532 ++++++++++++------
 .../workspace/citations/citation-link.tsx     | 160 +++---
 .../src/components/workspace/input-box.tsx    |  44 +-
 .../workspace/messages/message-group.tsx      |  87 ++-
 .../workspace/messages/message-list-item.tsx  | 283 ++++++++--
 .../workspace/messages/message-list.tsx       |  97 +++-
 .../settings/appearance-settings-page.tsx     |  25 +-
 .../workspace/skill-display-adapter-panel.tsx | 360 ++++++++++++
 .../workspace/skill-display-block.tsx         | 184 ++++++
 .../workspace/skill-display-sources.tsx       | 155 +++++
 .../workspace/skills/skill-detail-dialog.tsx  |  20 +-
 frontend-web/src/core/settings/local.ts       |  16 +-
 .../src/core/skill-display/display-adapter.ts | 209 +++++++
 .../src/core/skill-display/runtime.ts         | 350 ++++++++++++
 frontend-web/src/core/skills/api.ts           |  44 +-
 frontend-web/src/core/skills/hooks.ts         |  30 +-
 frontend-web/src/core/skills/type.ts          |  31 +
 frontend-web/src/core/threads/hooks.ts        |  15 +-
 frontend-web/src/core/threads/types.ts        |   5 +-
 .../backend/app/gateway/routers/mcp.py        |  11 +-
 .../backend/app/gateway/routers/skills.py     | 265 ++++++++-
 .../backend/app/gateway/services.py           |   5 +-
 .../deerflow/agents/lead_agent/agent.py       |  23 +-
 .../deerflow/agents/lead_agent/prompt.py      | 156 +++--
 .../packages/harness/deerflow/client.py       |  32 +-
 .../deerflow/config/extensions_config.py      |  63 ++-
 26 files changed, 2732 insertions(+), 470 deletions(-)
 create mode 100644 frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
 create mode 100644 frontend-web/src/components/workspace/skill-display-block.tsx
 create mode 100644 frontend-web/src/components/workspace/skill-display-sources.tsx
 create mode 100644 frontend-web/src/core/skill-display/display-adapter.ts
 create mode 100644 frontend-web/src/core/skill-display/runtime.ts

diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index dec47e42..ce37986a 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -1,183 +1,349 @@
-import { FilesIcon, XIcon } from "lucide-react";
-import { usePathname } from "next/navigation";
-import { useEffect, useMemo, useRef, useState } from "react";
-import type { GroupImperativeHandle } from "react-resizable-panels";
-
-import { ConversationEmptyState } from "@/components/ai-elements/conversation";
-import { Button } from "@/components/ui/button";
-import {
-  ResizableHandle,
-  ResizablePanel,
-  ResizablePanelGroup,
-} from "@/components/ui/resizable";
-import { env } from "@/env";
-import { cn } from "@/lib/utils";
-
-import {
-  ArtifactFileDetail,
-  ArtifactFileList,
-  useArtifacts,
-} from "../artifacts";
-import { useThread } from "../messages/context";
-
-const CLOSE_MODE = { chat: 100, artifacts: 0 };
-const OPEN_MODE = { chat: 60, artifacts: 40 };
-
-const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
-  children,
-  threadId,
-}) => {
-  const { thread } = useThread();
-  const pathname = usePathname();
-  const threadIdRef = useRef(threadId);
-  const layoutRef = useRef<GroupImperativeHandle>(null);
-
-  const {
-    artifacts,
-    open: artifactsOpen,
-    setOpen: setArtifactsOpen,
-    setArtifacts,
-    select: selectArtifact,
-    deselect,
-    selectedArtifact,
-  } = useArtifacts();
-
-  const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
-  useEffect(() => {
-    if (threadIdRef.current !== threadId) {
-      threadIdRef.current = threadId;
-      deselect();
-    }
-
-    // Update artifacts from the current thread
-    setArtifacts(thread.values.artifacts);
-
-    // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
-    // if (
-    //   selectedArtifact &&
-    //   !thread.values.artifacts?.includes(selectedArtifact)
-    // ) {
-    //   deselect();
-    // }
-
-    if (
-      env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" &&
-      autoSelectFirstArtifact
-    ) {
-      if (thread?.values?.artifacts?.length > 0) {
-        setAutoSelectFirstArtifact(false);
-        selectArtifact(thread.values.artifacts[0]!);
-      }
-    }
-  }, [
-    threadId,
-    autoSelectFirstArtifact,
-    deselect,
-    selectArtifact,
-    selectedArtifact,
-    setArtifacts,
-    thread.values.artifacts,
-  ]);
-
-  const artifactPanelOpen = useMemo(() => {
-    if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") {
-      return artifactsOpen && artifacts?.length > 0;
-    }
-    return artifactsOpen;
-  }, [artifactsOpen, artifacts]);
-
-  const resizableIdBase = useMemo(() => {
-    const raw = pathname
-      .replace(/[^a-zA-Z0-9_-]+/g, "-")
-      .replace(/^-+|-+$/g, "");
-    return raw.length > 0 ? raw : `thread-${threadId}`;
-  }, [pathname, threadId]);
-
-  useEffect(() => {
-    if (layoutRef.current) {
-      if (artifactPanelOpen) {
-        layoutRef.current.setLayout(OPEN_MODE);
-      } else {
-        layoutRef.current.setLayout(CLOSE_MODE);
-      }
-    }
-  }, [artifactPanelOpen]);
-
-  return (
-    <ResizablePanelGroup
-      id={`${resizableIdBase}-panels`}
-      orientation="horizontal"
-      defaultLayout={{ chat: 100, artifacts: 0 }}
-      groupRef={layoutRef}
-    >
-      <ResizablePanel className="relative" defaultSize={100} id="chat">
-        {children}
-      </ResizablePanel>
-      <ResizableHandle
-        id={`${resizableIdBase}-separator`}
-        className={cn(
-          "opacity-33 hover:opacity-100",
-          !artifactPanelOpen && "pointer-events-none opacity-0",
-        )}
-      />
-      <ResizablePanel
-        className={cn(
-          "bg-[#fffdfa] transition-all duration-300 ease-in-out",
-          !artifactsOpen && "opacity-0",
-        )}
-        id="artifacts"
-      >
-        <div
-          className={cn(
-            "h-full bg-[#fffdfa] p-4 transition-transform duration-300 ease-in-out",
-            artifactPanelOpen ? "translate-x-0" : "translate-x-full",
-          )}
-        >
-          {selectedArtifact ? (
-            <ArtifactFileDetail
-              className="size-full"
-              filepath={selectedArtifact}
-              threadId={threadId}
-            />
-          ) : (
-            <div className="relative flex size-full justify-center">
-              <div className="absolute top-1 right-1 z-30">
-                <Button
-                  size="icon-sm"
-                  variant="ghost"
-                  onClick={() => {
-                    setArtifactsOpen(false);
-                  }}
-                >
-                  <XIcon />
-                </Button>
-              </div>
-              {thread.values.artifacts?.length === 0 ? (
-                <ConversationEmptyState
-                  icon={<FilesIcon />}
-                  title="No artifact selected"
-                  description="Select an artifact to view its details"
-                />
-              ) : (
-                <div className="flex size-full max-w-(--container-width-sm) flex-col justify-center p-4 pt-8">
-                  <header className="shrink-0">
-                    <h2 className="text-lg font-medium">Artifacts</h2>
-                  </header>
-                  <main className="min-h-0 grow">
-                    <ArtifactFileList
-                      className="max-w-(--container-width-sm) p-4 pt-12"
-                      files={thread.values.artifacts ?? []}
-                      threadId={threadId}
-                    />
-                  </main>
-                </div>
-              )}
-            </div>
-          )}
-        </div>
-      </ResizablePanel>
-    </ResizablePanelGroup>
-  );
-};
-
-export { ChatBox };
+import type { Message } from "@langchain/langgraph-sdk";
+import { FilesIcon, XIcon } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { GroupImperativeHandle } from "react-resizable-panels";
+
+import { ConversationEmptyState } from "@/components/ai-elements/conversation";
+import { Button } from "@/components/ui/button";
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@/components/ui/resizable";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
+import { useLocalSettings } from "@/core/settings";
+import { useSkills } from "@/core/skills/hooks";
+import {
+  buildSkillDisplayMap,
+  collectRuntimeDisplaySources,
+} from "@/core/skill-display/runtime";
+import { env } from "@/env";
+import { cn } from "@/lib/utils";
+
+import {
+  ArtifactFileDetail,
+  ArtifactFileList,
+  useArtifacts,
+} from "../artifacts";
+import { useThread } from "../messages/context";
+import { SkillDisplaySources } from "../skill-display-sources";
+
+const CLOSE_MODE = { chat: 100, artifacts: 0 };
+const OPEN_MODE = { chat: 60, artifacts: 40 };
+const SHOW_REFERENCE_EVENT = "workspace:show-reference";
+
+const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
+  children,
+  threadId,
+}) => {
+  const { thread } = useThread();
+  const pathname = usePathname();
+  const threadIdRef = useRef(threadId);
+  const layoutRef = useRef<GroupImperativeHandle>(null);
+  const [sideTab, setSideTab] = useState("document");
+  const [referencesOpen, setReferencesOpen] = useState(true);
+  const [settings] = useLocalSettings();
+  const { skills } = useSkills();
+
+  const {
+    artifacts,
+    open: artifactsOpen,
+    setOpen: setArtifactsOpen,
+    setArtifacts,
+    select: selectArtifact,
+    deselect,
+    selectedArtifact,
+  } = useArtifacts();
+
+  const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
+  const skillDisplayMap = useMemo(
+    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [settings.display.ragModeEnabled, skills],
+  );
+  const latestAssistant = useMemo(
+    () => findLatestAssistantMessage(thread.values.messages ?? []),
+    [thread.values.messages],
+  );
+  const displaySources = useMemo(() => {
+    if (!settings.display.ragModeEnabled) {
+      return [];
+    }
+    const messages = thread.values.messages ?? [];
+    if (!latestAssistant?.id) {
+      return [];
+    }
+    return collectRuntimeDisplaySources(messages, skillDisplayMap, {
+      afterMessageId: findPreviousHumanMessageId(messages, latestAssistant.id),
+      beforeMessageId: latestAssistant.id,
+    });
+  }, [settings.display.ragModeEnabled, skillDisplayMap, latestAssistant?.id, thread.values.messages]);
+  const referenceSources = useMemo(
+    () => displaySources.filter((source) => source.mode === "citation"),
+    [displaySources],
+  );
+  const hasCitationReferences = referenceSources.length > 0;
+  useEffect(() => {
+    if (hasCitationReferences) {
+      setReferencesOpen(true);
+    }
+  }, [hasCitationReferences, latestAssistant?.id]);
+  useEffect(() => {
+    const handleShowReference = () => {
+      setReferencesOpen(true);
+      setSideTab("references");
+    };
+    window.addEventListener(SHOW_REFERENCE_EVENT, handleShowReference);
+    return () => {
+      window.removeEventListener(SHOW_REFERENCE_EVENT, handleShowReference);
+    };
+  }, []);
+  useEffect(() => {
+    if (threadIdRef.current !== threadId) {
+      threadIdRef.current = threadId;
+      deselect();
+      setReferencesOpen(true);
+    }
+
+    // Update artifacts from the current thread
+    setArtifacts(thread.values.artifacts);
+
+    // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
+    // if (
+    //   selectedArtifact &&
+    //   !thread.values.artifacts?.includes(selectedArtifact)
+    // ) {
+    //   deselect();
+    // }
+
+    if (
+      env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true" &&
+      autoSelectFirstArtifact
+    ) {
+      if (thread?.values?.artifacts?.length > 0) {
+        setAutoSelectFirstArtifact(false);
+        selectArtifact(thread.values.artifacts[0]!);
+      }
+    }
+  }, [
+    threadId,
+    autoSelectFirstArtifact,
+    deselect,
+    selectArtifact,
+    selectedArtifact,
+    setArtifacts,
+    thread.values.artifacts,
+  ]);
+
+  const artifactPanelOpen = useMemo(() => {
+    if (env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true") {
+      return artifactsOpen && artifacts?.length > 0;
+    }
+    return artifactsOpen;
+  }, [artifactsOpen, artifacts]);
+  const sidePanelOpen = artifactPanelOpen || (hasCitationReferences && referencesOpen);
+  const showTabs = !!selectedArtifact && hasCitationReferences;
+
+  useEffect(() => {
+    if (!selectedArtifact && hasCitationReferences) {
+      setSideTab("references");
+    } else if (selectedArtifact && !hasCitationReferences) {
+      setSideTab("document");
+    }
+  }, [hasCitationReferences, selectedArtifact]);
+
+  const resizableIdBase = useMemo(() => {
+    const raw = pathname
+      .replace(/[^a-zA-Z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+    return raw.length > 0 ? raw : `thread-${threadId}`;
+  }, [pathname, threadId]);
+
+  useEffect(() => {
+    if (layoutRef.current) {
+      if (sidePanelOpen) {
+        layoutRef.current.setLayout(OPEN_MODE);
+      } else {
+        layoutRef.current.setLayout(CLOSE_MODE);
+      }
+    }
+  }, [sidePanelOpen]);
+
+  return (
+    <ResizablePanelGroup
+      id={`${resizableIdBase}-panels`}
+      orientation="horizontal"
+      defaultLayout={{ chat: 100, artifacts: 0 }}
+      groupRef={layoutRef}
+    >
+      <ResizablePanel className="relative" defaultSize={100} id="chat">
+        {children}
+      </ResizablePanel>
+      <ResizableHandle
+        id={`${resizableIdBase}-separator`}
+        className={cn(
+          "opacity-33 hover:opacity-100",
+          !sidePanelOpen && "pointer-events-none opacity-0",
+        )}
+      />
+      <ResizablePanel
+        className={cn(
+          "bg-[#fffdfa] transition-all duration-300 ease-in-out",
+          !sidePanelOpen && "opacity-0",
+        )}
+        id="artifacts"
+      >
+        <div
+          className={cn(
+            "h-full bg-[#fffdfa] p-4 transition-transform duration-300 ease-in-out",
+            sidePanelOpen ? "translate-x-0" : "translate-x-full",
+          )}
+        >
+          {showTabs ? (
+            <Tabs value={sideTab} onValueChange={setSideTab} className="flex size-full flex-col overflow-hidden">
+              <div className="mb-3 flex shrink-0 items-center justify-between gap-2">
+                <TabsList variant="line">
+                  <TabsTrigger value="document">文档</TabsTrigger>
+                  <TabsTrigger value="references">参考文献</TabsTrigger>
+                </TabsList>
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={() => {
+                    setReferencesOpen(false);
+                    setArtifactsOpen(false);
+                  }}
+                >
+                  <XIcon />
+                </Button>
+              </div>
+              <TabsContent value="document" className="min-h-0 flex-1 overflow-hidden p-0">
+                <ArtifactFileDetail
+                  className="size-full"
+                  filepath={selectedArtifact}
+                  threadId={threadId}
+                />
+              </TabsContent>
+              <TabsContent value="references" className="min-h-0 flex-1 overflow-y-auto p-0">
+                <ReferencePanel sources={referenceSources} />
+              </TabsContent>
+            </Tabs>
+          ) : selectedArtifact ? (
+            <ArtifactFileDetail
+              className="size-full"
+              filepath={selectedArtifact}
+              threadId={threadId}
+            />
+          ) : hasCitationReferences ? (
+            <div className="relative size-full overflow-hidden">
+              <div className="absolute top-1 right-1 z-30">
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={() => {
+                    setReferencesOpen(false);
+                    setArtifactsOpen(false);
+                  }}
+                >
+                  <XIcon />
+                </Button>
+              </div>
+              <ReferencePanel sources={referenceSources} />
+            </div>
+          ) : (
+            <div className="relative flex size-full justify-center">
+              <div className="absolute top-1 right-1 z-30">
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={() => {
+                    setArtifactsOpen(false);
+                  }}
+                >
+                  <XIcon />
+                </Button>
+              </div>
+              {thread.values.artifacts?.length === 0 ? (
+                <ConversationEmptyState
+                  icon={<FilesIcon />}
+                  title="No artifact selected"
+                  description="Select an artifact to view its details"
+                />
+              ) : (
+                <div className="flex size-full max-w-(--container-width-sm) flex-col justify-center p-4 pt-8">
+                  <header className="shrink-0">
+                    <h2 className="text-lg font-medium">Artifacts</h2>
+                  </header>
+                  <main className="min-h-0 grow">
+                    <ArtifactFileList
+                      className="max-w-(--container-width-sm) p-4 pt-12"
+                      files={thread.values.artifacts ?? []}
+                      threadId={threadId}
+                    />
+                  </main>
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  );
+};
+
+function ReferencePanel({
+  sources,
+}: {
+  sources: Parameters<typeof SkillDisplaySources>[0]["sources"];
+}) {
+  return (
+    <div className="flex size-full flex-col overflow-hidden">
+      <header className="shrink-0 px-1 pb-3">
+        <div className="flex items-baseline gap-2">
+          <h2 className="text-foreground text-base font-semibold tracking-tight">
+            参考文献
+          </h2>
+          <span className="text-muted-foreground text-xs tabular-nums">
+            {sources.length} 条
+          </span>
+        </div>
+        <p className="text-muted-foreground mt-1 text-xs leading-relaxed">
+          点击编号或卡片可查看引用详情。
+        </p>
+      </header>
+      <main className="min-h-0 flex-1 overflow-y-auto px-1 pt-1 pb-6">
+        <SkillDisplaySources sources={sources} />
+      </main>
+    </div>
+  );
+}
+
+function findLatestAssistantMessage(messages: Message[]) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.type === "ai") {
+      return message;
+    }
+  }
+  return null;
+}
+
+function findPreviousHumanMessageId(
+  messages: Message[],
+  beforeMessageId?: string,
+): string | undefined {
+  const beforeIndex =
+    beforeMessageId === undefined
+      ? messages.length
+      : messages.findIndex((message) => message.id === beforeMessageId);
+  const end = beforeIndex < 0 ? messages.length : beforeIndex;
+  for (let index = end - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.type === "human") {
+      return message.id;
+    }
+  }
+  return undefined;
+}
+
+export { ChatBox };
diff --git a/frontend-web/src/components/workspace/citations/citation-link.tsx b/frontend-web/src/components/workspace/citations/citation-link.tsx
index aecc71a8..58b7c22a 100644
--- a/frontend-web/src/components/workspace/citations/citation-link.tsx
+++ b/frontend-web/src/components/workspace/citations/citation-link.tsx
@@ -1,82 +1,78 @@
-import { ExternalLinkIcon } from "lucide-react";
-import type { ComponentProps } from "react";
-
-import { Badge } from "@/components/ui/badge";
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-} from "@/components/ui/hover-card";
-import { cn } from "@/lib/utils";
-
-export function CitationLink({
-  href,
-  children,
-  ...props
-}: ComponentProps<"a">) {
-  const domain = extractDomain(href ?? "");
-
-  // Priority: children > domain
-  const childrenText =
-    typeof children === "string"
-      ? children.replace(/^citation:\s*/i, "")
-      : null;
-  const isGenericText = childrenText === "Source" || childrenText === "来源";
-  const displayText = (!isGenericText && childrenText) ?? domain;
-
-  return (
-    <HoverCard closeDelay={0} openDelay={0}>
-      <HoverCardTrigger asChild>
-        <a
-          href={href}
-          target="_blank"
-          rel="noopener noreferrer"
-          className="inline-flex items-center"
-          onClick={(e) => e.stopPropagation()}
-          {...props}
-        >
-          <Badge
-            variant="secondary"
-            className="hover:bg-secondary/80 mx-0.5 cursor-pointer gap-1 rounded-full px-2 py-0.5 text-xs font-normal"
-          >
-            {displayText}
-            <ExternalLinkIcon className="size-3" />
-          </Badge>
-        </a>
-      </HoverCardTrigger>
-      <HoverCardContent className={cn("relative w-80 p-0", props.className)}>
-        <div className="p-3">
-          <div className="space-y-1">
-            {displayText && (
-              <h4 className="truncate text-sm leading-tight font-medium">
-                {displayText}
-              </h4>
-            )}
-            {href && (
-              <p className="text-muted-foreground truncate text-xs break-all">
-                {href}
-              </p>
-            )}
-          </div>
-          <a
-            href={href}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="text-primary mt-2 inline-flex items-center gap-1 text-xs hover:underline"
-          >
-            Visit source
-            <ExternalLinkIcon className="size-3" />
-          </a>
-        </div>
-      </HoverCardContent>
-    </HoverCard>
-  );
-}
-
-function extractDomain(url: string): string {
-  try {
-    return new URL(url).hostname.replace(/^www\./i, "");
-  } catch {
-    return url;
-  }
-}
+import type { ComponentProps } from "react";
+
+import { cn } from "@/lib/utils";
+
+const SHOW_REFERENCE_EVENT = "workspace:show-reference";
+
+export function CitationLink({
+  href,
+  children,
+  className,
+  ...props
+}: ComponentProps<"a">) {
+  const childrenText = normalizeCitationText(children);
+  const displayText = childrenText ?? "";
+  const referenceId = href?.startsWith("#reference-")
+    ? href.slice("#reference-".length)
+    : null;
+
+  if (referenceId) {
+    const badgeLabel = displayText.replace(/^\[|\]$/g, "") || referenceId;
+    return (
+      <a
+        href={href}
+        title={`查看参考文献 ${badgeLabel}`}
+        className={cn(
+          "border-primary/30 bg-primary/10 text-primary hover:border-primary/60 hover:bg-primary/20 focus-visible:ring-primary/30 mx-0.5 inline-flex h-[18px] min-w-[18px] -translate-y-[1px] items-center justify-center rounded-full border px-1 text-[10.5px] font-semibold tabular-nums no-underline transition-colors focus-visible:ring-2 focus-visible:outline-none",
+          className,
+        )}
+        onClick={(event) => {
+          event.preventDefault();
+          window.dispatchEvent(
+            new CustomEvent(SHOW_REFERENCE_EVENT, {
+              detail: { referenceId },
+            }),
+          );
+          const target = document.getElementById(`reference-${referenceId}`);
+          const scroll = () => {
+            target?.scrollIntoView({ behavior: "smooth", block: "center" });
+          };
+          if (target) {
+            scroll();
+          } else {
+            window.setTimeout(scroll, 220);
+          }
+        }}
+        {...props}
+      >
+        {badgeLabel}
+      </a>
+    );
+  }
+
+  return (
+    <a
+      href={href}
+      target={href?.startsWith("http") ? "_blank" : undefined}
+      rel={href?.startsWith("http") ? "noopener noreferrer" : undefined}
+      className={cn(
+        "text-primary decoration-primary/30 hover:decoration-primary/60 underline underline-offset-2 transition-colors",
+        className,
+      )}
+      {...props}
+    >
+      {displayText || children}
+    </a>
+  );
+}
+
+function normalizeCitationText(children: ComponentProps<"a">["children"]) {
+  if (typeof children !== "string") {
+    return null;
+  }
+  let text = children.trim();
+  while (/^citation:\s*/i.test(text)) {
+    text = text.replace(/^citation:\s*/i, "");
+  }
+  return text;
+}
diff --git a/frontend-web/src/components/workspace/input-box.tsx b/frontend-web/src/components/workspace/input-box.tsx
index d547bd75..43640eeb 100644
--- a/frontend-web/src/components/workspace/input-box.tsx
+++ b/frontend-web/src/components/workspace/input-box.tsx
@@ -2,8 +2,9 @@
 
 import type { ChatStatus } from "ai";
 import {
-  BrainCircuitIcon,
-  CheckIcon,
+  BrainCircuitIcon,
+  BookMarkedIcon,
+  CheckIcon,
   FileTextIcon,
   GraduationCapIcon,
   LightbulbIcon,
@@ -84,7 +85,8 @@ import {
   DropdownMenuTrigger,
 } from "../ui/dropdown-menu";
 
-import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
+import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
+import { useLocalSettings } from "@/core/settings";
 
 
 import { useThread } from "./messages/context";
@@ -175,7 +177,8 @@ export function InputBox({
     onAgentChange: (agentId: string | null) => void;
   };
 }) {
-  const { t } = useI18n();
+  const { t } = useI18n();
+  const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
   const [modelDialogOpen, setModelDialogOpen] = useState(false);
   const { models } = useModels();
@@ -288,13 +291,18 @@ export function InputBox({
     });
   }, [context, onContextChange]);
 
-  const memoryInjectionEnabled = context.memory_injection_enabled ?? true;
+  const memoryInjectionEnabled = context.memory_injection_enabled ?? true;
   const handleMemoryInjectionToggle = useCallback(() => {
     onContextChange?.({
       ...context,
       memory_injection_enabled: !memoryInjectionEnabled,
     });
-  }, [context, memoryInjectionEnabled, onContextChange]);
+  }, [context, memoryInjectionEnabled, onContextChange]);
+
+  const ragModeEnabled = localSettings.display.ragModeEnabled;
+  const handleRagModeToggle = useCallback(() => {
+    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
+  }, [ragModeEnabled, setLocalSettings]);
 
   const handleSubmit = useCallback(
     async (message: PromptInputMessage) => {
@@ -620,8 +628,28 @@ export function InputBox({
                 <BrainCircuitIcon className="size-3" />
                 <span className="text-xs font-normal">记忆</span>
               </PromptInputButton>
-            </Tooltip>
-            <PromptInputActionMenu>
+            </Tooltip>
+            <Tooltip
+              content={
+                ragModeEnabled
+                  ? "参考文献模式已开启：检索类结果会按编号引用展示"
+                  : "参考文献模式已关闭：技能配置的引用展示不会生效"
+              }
+            >
+              <PromptInputButton
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  ragModeEnabled
+                    ? "border border-emerald-300 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
+                    : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
+                )}
+                onClick={handleRagModeToggle}
+              >
+                <BookMarkedIcon className="size-3" />
+                <span className="text-xs font-normal">参考文献</span>
+              </PromptInputButton>
+            </Tooltip>
+            <PromptInputActionMenu>
               <ModeHoverGuide
                 mode={
                   context.mode === "flash" ||
diff --git a/frontend-web/src/components/workspace/messages/message-group.tsx b/frontend-web/src/components/workspace/messages/message-group.tsx
index 63ff8e22..049e7047 100644
--- a/frontend-web/src/components/workspace/messages/message-group.tsx
+++ b/frontend-web/src/components/workspace/messages/message-group.tsx
@@ -47,6 +47,15 @@ import {
   findToolCallResult,
 } from "@/core/messages/utils";
 import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
+import { useLocalSettings } from "@/core/settings";
+import { useSkills } from "@/core/skills/hooks";
+import {
+  buildSkillDisplayMap,
+  findDisplayConfigForTool,
+  normalizeDefaultDisplaySources,
+  type RuntimeDisplaySource,
+} from "@/core/skill-display/runtime";
+import { normalizeDisplaySources } from "@/core/skill-display/display-adapter";
 import { extractTitleFromMarkdown } from "@/core/utils/markdown";
 import { env } from "@/env";
 import { cn } from "@/lib/utils";
@@ -54,6 +63,7 @@ import { cn } from "@/lib/utils";
 import { useArtifactsOptional } from "../artifacts";
 import { FlipDisplay } from "../flip-display";
 import { Tooltip } from "../tooltip";
+import { SourceCard } from "../skill-display-sources";
 
 import { MarkdownContent } from "./markdown-content";
 
@@ -74,6 +84,12 @@ export function MessageGroup({
     env.NEXT_PUBLIC_STATIC_WEBSITE_ONLY === "true",
   );
   const steps = useMemo(() => convertToSteps(messages), [messages]);
+  const [settings] = useLocalSettings();
+  const { skills } = useSkills();
+  const skillDisplayMap = useMemo(
+    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [settings.display.ragModeEnabled, skills],
+  );
   const lastToolCallStep = useMemo(() => {
     const filteredSteps = steps.filter((step) => step.type === "toolCall");
     return filteredSteps[filteredSteps.length - 1];
@@ -142,7 +158,13 @@ export function MessageGroup({
                   }
                 ></ChainOfThoughtStep>
               ) : (
-                <ToolCall key={step.id} {...step} isLoading={isLoading} />
+                <ToolCall
+                  key={step.id}
+                  {...step}
+                  isLoading={isLoading}
+                  skillDisplayMap={skillDisplayMap}
+                  ragModeEnabled={settings.display.ragModeEnabled}
+                />
               ),
             )}
           {lastToolCallStep && (
@@ -152,6 +174,8 @@ export function MessageGroup({
                 {...lastToolCallStep}
                 isLast={true}
                 isLoading={isLoading}
+                skillDisplayMap={skillDisplayMap}
+                ragModeEnabled={settings.display.ragModeEnabled}
               />
             </FlipDisplay>
           )}
@@ -209,6 +233,8 @@ function ToolCall({
   result,
   isLast = false,
   isLoading = false,
+  skillDisplayMap = new Map(),
+  ragModeEnabled = false,
 }: {
   id?: string;
   messageId?: string;
@@ -217,11 +243,48 @@ function ToolCall({
   result?: string | Record<string, unknown>;
   isLast?: boolean;
   isLoading?: boolean;
+  skillDisplayMap?: ReturnType<typeof buildSkillDisplayMap>;
+  ragModeEnabled?: boolean;
 }) {
   const { t } = useI18n();
   const artifacts = useArtifactsOptional();
 
+  const displayMatch = findDisplayConfigForTool(name, skillDisplayMap, args);
+  const displayItems =
+    displayMatch && result !== undefined
+      ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({
+          ...item,
+          index: index + 1,
+          skillName: displayMatch.skillName,
+          mode: displayMatch.display.mode,
+        }))
+      : [];
+  if (displayItems.length > 0) {
+    return (
+      <ChainOfThoughtStep
+        key={id}
+        label={displayMatch?.display.mode === "citation" || !displayMatch ? "检索参考来源" : `获取${displayItems.length}条结果`}
+        icon={SearchIcon}
+      >
+        <DisplayResultsList results={displayItems} />
+      </ChainOfThoughtStep>
+    );
+  }
+
   const searchItems = normalizeSearchResults(result);
+  if (ragModeEnabled && searchItems.length > 0) {
+    const defaultItems = normalizeDefaultDisplaySources(result).map((item, index) => ({
+      ...item,
+      index: index + 1,
+      skillName: name,
+      mode: "citation" as const,
+    }));
+    return (
+      <ChainOfThoughtStep key={id} label="检索参考来源" icon={SearchIcon}>
+        <DisplayResultsList results={defaultItems} />
+      </ChainOfThoughtStep>
+    );
+  }
   if (name === "web_search" || searchItems.length > 0) {
     const query = resolveSearchQuery(args, result);
     let label: React.ReactNode = t.toolCalls.searchForRelatedInfo;
@@ -534,6 +597,28 @@ function WebSearchResultsList({ results }: { results: SearchResultItem[] }) {
   );
 }
 
+function DisplayResultsList({ results }: { results: RuntimeDisplaySource[] }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="w-full">
+      <CollapsibleTrigger className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-xs">
+        <ChevronDownIcon
+          className={cn(
+            "size-3.5 transition-transform duration-200",
+            open && "rotate-180",
+          )}
+        />
+        <span>{results.length} 条适配结果</span>
+      </CollapsibleTrigger>
+      <CollapsibleContent className="mt-2 flex flex-col gap-2">
+        {results.map((item) => (
+          <SourceCard key={`${item.skillName}-${item.index}`} source={item} />
+        ))}
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
 function SearchResultCard({ item }: { item: SearchResultItem }) {
   const [open, setOpen] = useState(false);
   const content = item.snippet ?? item.content;
diff --git a/frontend-web/src/components/workspace/messages/message-list-item.tsx b/frontend-web/src/components/workspace/messages/message-list-item.tsx
index c6bdcfe8..11238584 100644
--- a/frontend-web/src/components/workspace/messages/message-list-item.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list-item.tsx
@@ -24,26 +24,31 @@ import {
 } from "@/components/ai-elements/reasoning";
 import { Task, TaskTrigger } from "@/components/ai-elements/task";
 import { Badge } from "@/components/ui/badge";
-import { resolveArtifactURL } from "@/core/artifacts/utils";
-import { getBackendBaseURL } from "@/core/config";
-import { useI18n } from "@/core/i18n/hooks";
-import {
-  extractContentFromMessage,
+import { resolveArtifactURL } from "@/core/artifacts/utils";
+import { getBackendBaseURL } from "@/core/config";
+import { useI18n } from "@/core/i18n/hooks";
+import {
+  extractContentFromMessage,
   extractReasoningContentFromMessage,
   parseUploadedFiles,
   stripArtifactTag,
   stripUploadedFilesTag,
-  type FileInMessage,
-} from "@/core/messages/utils";
-import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
-import { humanMessagePlugins } from "@/core/streamdown";
-import { cn } from "@/lib/utils";
-
-import { CopyButton } from "../copy-button";
-
-import { ThreadContext } from "./context";
+  type FileInMessage,
+} from "@/core/messages/utils";
+import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
+import {
+  applyInlineCitations,
+  type RuntimeDisplaySource,
+} from "@/core/skill-display/runtime";
+import { humanMessagePlugins } from "@/core/streamdown";
+import { cn } from "@/lib/utils";
+
+import { CitationLink } from "../citations/citation-link";
+import { CopyButton } from "../copy-button";
+import { SkillDisplayBlock } from "../skill-display-block";
+import { ThreadContext } from "./context";
 import { DownloadWordButton } from "./download-word-button";
-import { MarkdownContent } from "./markdown-content";
+import { MarkdownContent, type MarkdownContentProps } from "./markdown-content";
 import { MessageTokenUsage } from "./message-token-usage";
 
 /**
@@ -74,14 +79,16 @@ export function MessageListItem({
   message,
   isLoading,
   threadId,
-  tokenUsageEnabled = false,
-}: {
-  className?: string;
-  message: Message;
-  isLoading?: boolean;
-  threadId: string;
-  tokenUsageEnabled?: boolean;
-}) {
+  tokenUsageEnabled = false,
+  displaySources = [],
+}: {
+  className?: string;
+  message: Message;
+  isLoading?: boolean;
+  threadId: string;
+  tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+}) {
   const isHuman = message.type === "human";
   const messageMarkdown =
     extractContentFromMessage(message) ??
@@ -94,11 +101,12 @@ export function MessageListItem({
     >
       <MessageContent
         className={isHuman ? "w-fit" : "w-full"}
-        message={message}
-        isLoading={isLoading}
-        threadId={threadId}
-        tokenUsageEnabled={tokenUsageEnabled}
-      />
+        message={message}
+        isLoading={isLoading}
+        threadId={threadId}
+        tokenUsageEnabled={tokenUsageEnabled}
+        displaySources={displaySources}
+      />
       {!isLoading && (
         <MessageToolbar
           className={cn(
@@ -157,14 +165,16 @@ function MessageContent_({
   message,
   isLoading = false,
   threadId,
-  tokenUsageEnabled = false,
-}: {
-  className?: string;
-  message: Message;
-  isLoading?: boolean;
-  threadId: string;
-  tokenUsageEnabled?: boolean;
-}) {
+  tokenUsageEnabled = false,
+  displaySources = [],
+}: {
+  className?: string;
+  message: Message;
+  isLoading?: boolean;
+  threadId: string;
+  tokenUsageEnabled?: boolean;
+  displaySources?: RuntimeDisplaySource[];
+}) {
   const rehypePlugins = useRehypeSplitWordsIntoSpans(isLoading);
   const isHuman = message.type === "human";
   const resolveArtifact = useArtifactResolver(threadId);
@@ -173,9 +183,12 @@ function MessageContent_({
       img: (props: ImgHTMLAttributes<HTMLImageElement>) => (
         <MessageImage {...props} threadId={threadId} maxWidth="90%" />
       ),
-      a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
-        if (href?.startsWith("/mnt/")) {
-          const url = resolveArtifact(href);
+      a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        if (typeof props.children === "string" && /^citation:/i.test(props.children)) {
+          return <CitationLink href={href} {...props} />;
+        }
+        if (href?.startsWith("/mnt/")) {
+          const url = resolveArtifact(href);
           return (
             <a
               {...props}
@@ -206,12 +219,12 @@ function MessageContent_({
     return files as FileInMessage[];
   }, [message.additional_kwargs?.files, rawContent]);
 
-  const contentToDisplay = useMemo(() => {
-    if (isHuman) {
-      return rawContent ? stripArtifactTag(stripUploadedFilesTag(rawContent)) : "";
-    }
-    return rawContent ?? "";
-  }, [rawContent, isHuman]);
+  const contentToDisplay = useMemo(() => {
+    if (isHuman) {
+      return rawContent ? stripArtifactTag(stripUploadedFilesTag(rawContent)) : "";
+    }
+    return applyInlineCitations(rawContent ?? "", displaySources);
+  }, [rawContent, isHuman, displaySources]);
 
   const filesList =
     files && files.length > 0 ? (
@@ -274,17 +287,17 @@ function MessageContent_({
     );
   }
 
-  return (
-    <AIElementMessageContent className={className}>
-      {filesList}
-      <MarkdownContent
-        content={contentToDisplay}
-        isLoading={isLoading}
-        rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
-        className="my-3"
-        components={components}
-      />
-      <MessageTokenUsage
+  return (
+    <AIElementMessageContent className={className}>
+      {filesList}
+      <AssistantDisplayContent
+        content={contentToDisplay}
+        displaySources={displaySources}
+        isLoading={isLoading}
+        rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
+        components={components}
+      />
+      <MessageTokenUsage
         enabled={tokenUsageEnabled}
         isLoading={isLoading}
         message={message}
@@ -459,4 +472,160 @@ function RichFileCard({
   );
 }
 
-const MessageContent = memo(MessageContent_);
+const MessageContent = memo(MessageContent_);
+
+function AssistantDisplayContent({
+  content,
+  displaySources,
+  isLoading,
+  rehypePlugins,
+  components,
+}: {
+  content: string;
+  displaySources: RuntimeDisplaySource[];
+  isLoading: boolean;
+  rehypePlugins: MarkdownContentProps["rehypePlugins"];
+  components: MarkdownContentProps["components"];
+}) {
+  const { parts, placedKeys } = useMemo(
+    () => splitSkillDisplayPlaceholders(content, displaySources),
+    [content, displaySources],
+  );
+  const fallbackBlocks = useMemo(() => {
+    return groupDisplaySources(displaySources).filter(
+      (group) => group.mode !== "citation" && !placedKeys.has(group.key),
+    );
+  }, [displaySources, placedKeys]);
+
+  return (
+    <>
+      {parts.map((part, index) =>
+        part.type === "markdown" ? (
+          <MarkdownContent
+            key={`markdown-${index}`}
+            content={part.content}
+            isLoading={isLoading}
+            rehypePlugins={rehypePlugins}
+            className="my-3"
+            components={components}
+          />
+        ) : (
+          <SkillDisplayBlock
+            key={`display-${index}`}
+            mode={part.mode}
+            sources={part.sources}
+          />
+        ),
+      )}
+      {fallbackBlocks.map((group) => (
+        <SkillDisplayBlock
+          key={`fallback-${group.key}`}
+          mode={group.mode}
+          sources={group.sources}
+        />
+      ))}
+    </>
+  );
+}
+
+type DisplayPart =
+  | { type: "markdown"; content: string }
+  | {
+      type: "display";
+      key: string;
+      mode: RuntimeDisplaySource["mode"];
+      sources: RuntimeDisplaySource[];
+    };
+
+function splitSkillDisplayPlaceholders(
+  content: string,
+  displaySources: RuntimeDisplaySource[],
+): { parts: DisplayPart[]; placedKeys: Set<string> } {
+  const pattern = /<skill-display\s+([^>]*?)\/>/g;
+  const parts: DisplayPart[] = [];
+  const placedKeys = new Set<string>();
+  let cursor = 0;
+  for (const match of content.matchAll(pattern)) {
+    const start = match.index ?? 0;
+    const before = content.slice(cursor, start);
+    if (before.trim()) {
+      parts.push({ type: "markdown", content: before });
+    }
+    const attrs = parseDisplayAttrs(match[1] ?? "");
+    const group = findDisplayGroup(displaySources, attrs.tool, attrs.mode);
+    if (group) {
+      parts.push({
+        type: "display",
+        key: group.key,
+        mode: group.mode,
+        sources: group.sources,
+      });
+      placedKeys.add(group.key);
+    }
+    cursor = start + match[0].length;
+  }
+  const rest = content.slice(cursor);
+  if (rest.trim() || parts.length === 0) {
+    parts.push({ type: "markdown", content: rest });
+  }
+  return { parts, placedKeys };
+}
+
+function parseDisplayAttrs(raw: string): { tool?: string; mode?: RuntimeDisplaySource["mode"] } {
+  const attrs: Record<string, string> = {};
+  for (const match of raw.matchAll(/([a-zA-Z][\w-]*)="([^"]*)"/g)) {
+    attrs[match[1]!] = match[2]!;
+  }
+  return {
+    tool: attrs.tool || attrs.skill || attrs.name,
+    mode: attrs.mode as RuntimeDisplaySource["mode"] | undefined,
+  };
+}
+
+function findDisplayGroup(
+  sources: RuntimeDisplaySource[],
+  tool?: string,
+  mode?: RuntimeDisplaySource["mode"],
+) {
+  return groupDisplaySources(sources).find((group) => {
+    if (mode && group.mode !== mode) {
+      return false;
+    }
+    if (!tool) {
+      return true;
+    }
+    const left = normalizeName(group.skillName);
+    const right = normalizeName(tool);
+    return left === right || left.includes(right) || right.includes(left);
+  });
+}
+
+function groupDisplaySources(sources: RuntimeDisplaySource[]) {
+  const groups = new Map<
+    string,
+    {
+      key: string;
+      skillName: string;
+      mode: RuntimeDisplaySource["mode"];
+      sources: RuntimeDisplaySource[];
+    }
+  >();
+  for (const source of sources) {
+    const key = `${source.skillName}:${source.mode}`;
+    const group =
+      groups.get(key) ??
+      {
+        key,
+        skillName: source.skillName,
+        mode: source.mode,
+        sources: [],
+      };
+    group.sources.push(source);
+    groups.set(key, group);
+  }
+  return [...groups.values()];
+}
+
+function normalizeName(name: string) {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
diff --git a/frontend-web/src/components/workspace/messages/message-list.tsx b/frontend-web/src/components/workspace/messages/message-list.tsx
index 63cee2fb..1624d7c7 100644
--- a/frontend-web/src/components/workspace/messages/message-list.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list.tsx
@@ -1,4 +1,5 @@
-import type { BaseStream } from "@langchain/langgraph-sdk/react";
+import type { Message } from "@langchain/langgraph-sdk";
+import type { BaseStream } from "@langchain/langgraph-sdk/react";
 import { CheckIcon, SendIcon, XIcon } from "lucide-react";
 import { useCallback, useMemo, useState } from "react";
 
@@ -8,7 +9,7 @@ import {
 } from "@/components/ai-elements/conversation";
 import { Button } from "@/components/ui/button";
 import { Textarea } from "@/components/ui/textarea";
-import { useI18n } from "@/core/i18n/hooks";
+import { useI18n } from "@/core/i18n/hooks";
 import {
   extractContentFromMessage,
   extractPresentFilesFromMessage,
@@ -19,8 +20,14 @@ import {
   hasReasoning,
   hasToolCalls,
 } from "@/core/messages/utils";
-import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
-import type { Subtask } from "@/core/tasks";
+import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
+import { useLocalSettings } from "@/core/settings";
+import { useSkills } from "@/core/skills/hooks";
+import {
+  buildSkillDisplayMap,
+  collectRuntimeDisplaySources,
+} from "@/core/skill-display/runtime";
+import type { Subtask } from "@/core/tasks";
 import { useUpdateSubtask } from "@/core/tasks/context";
 import type { AgentThreadState } from "@/core/threads";
 import { cn } from "@/lib/utils";
@@ -61,9 +68,15 @@ export function MessageList({
   onSetupAgentReject?: (payload: SetupAgentApprovalPayload) => void | Promise<void>;
 }) {
   const { t } = useI18n();
-  const rehypePlugins = useRehypeSplitWordsIntoSpans(thread.isLoading);
-  const updateSubtask = useUpdateSubtask();
-  const messages = thread.messages;
+  const rehypePlugins = useRehypeSplitWordsIntoSpans(thread.isLoading);
+  const updateSubtask = useUpdateSubtask();
+  const messages = thread.messages;
+  const [settings] = useLocalSettings();
+  const { skills } = useSkills();
+  const skillDisplayMap = useMemo(
+    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [settings.display.ragModeEnabled, skills],
+  );
 
   // Track which clarification messages are still awaiting an answer.
   // Pending = clarification tool messages that appear after the last human message
@@ -179,18 +192,28 @@ export function MessageList({
       <ConversationContent className="mx-auto w-full max-w-(--container-width-lg) gap-8 pt-12">
         <MessageMetricsProvider messages={messages} isLoading={thread.isLoading}>
         {groupMessages(messages, (group) => {
-          if (group.type === "human" || group.type === "assistant") {
-            return group.messages.map((msg) => {
-              return (
-                <MessageListItem
-                  key={`${group.id}/${msg.id}`}
-                  message={msg}
-                  isLoading={thread.isLoading}
-                  threadId={threadId}
-                  tokenUsageEnabled={tokenUsageEnabled}
-                />
-              );
-            });
+          if (group.type === "human" || group.type === "assistant") {
+            return group.messages.map((msg) => {
+              const displaySources =
+                settings.display.ragModeEnabled &&
+                group.type === "assistant" &&
+                msg.type === "ai"
+                  ? collectRuntimeDisplaySources(messages, skillDisplayMap, {
+                      afterMessageId: findPreviousHumanMessageId(messages, msg.id),
+                      beforeMessageId: msg.id,
+                    })
+                  : [];
+              return (
+                <MessageListItem
+                  key={`${group.id}/${msg.id}`}
+                  message={msg}
+                  isLoading={thread.isLoading}
+                  threadId={threadId}
+                  tokenUsageEnabled={tokenUsageEnabled}
+                  displaySources={displaySources}
+                />
+              );
+            });
           } else if (group.type === "assistant:clarification") {
             const message = group.messages[0];
             if (message && hasContent(message)) {
@@ -419,15 +442,33 @@ type ClarificationSelection = {
   custom: string;
 };
 
-export type SetupAgentApprovalPayload = {
-  name?: string;
-  description?: string;
-  soul?: string;
-  skills?: string[];
-};
-
-function getSetupAgentApprovalPayload(
-  message: unknown,
+export type SetupAgentApprovalPayload = {
+  name?: string;
+  description?: string;
+  soul?: string;
+  skills?: string[];
+};
+
+function findPreviousHumanMessageId(
+  messages: Message[],
+  beforeMessageId?: string,
+): string | undefined {
+  const beforeIndex =
+    beforeMessageId === undefined
+      ? messages.length
+      : messages.findIndex((message) => message.id === beforeMessageId);
+  const end = beforeIndex < 0 ? messages.length : beforeIndex;
+  for (let index = end - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.type === "human") {
+      return message.id;
+    }
+  }
+  return undefined;
+}
+
+function getSetupAgentApprovalPayload(
+  message: unknown,
 ): SetupAgentApprovalPayload | null {
   if (typeof message !== "object" || message === null) {
     return null;
diff --git a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
index 0d09f5e1..9a853cbe 100644
--- a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
+++ b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
@@ -132,11 +132,26 @@ export function AppearanceSettingsPage() {
             }
             aria-label="回答速度指示器"
           />
-        </div>
-      </SettingsSection>
-    </div>
-  );
-}
+        </div>
+        <div className="flex items-start justify-between gap-4 rounded-lg border p-4">
+          <div>
+            <div className="text-sm font-medium">RAG 引用模式</div>
+            <p className="text-muted-foreground mt-1 max-w-md text-xs leading-relaxed">
+              开启后，已配置展示适配的技能结果会在问答中渲染为编号引用或列表，并支持点击跳转。
+            </p>
+          </div>
+          <Switch
+            checked={settings.display.ragModeEnabled}
+            onCheckedChange={(checked) =>
+              setSettings("display", { ragModeEnabled: checked })
+            }
+            aria-label="RAG 引用模式"
+          />
+        </div>
+      </SettingsSection>
+    </div>
+  );
+}
 
 function ThemePreviewCard({
   icon: Icon,
diff --git a/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
new file mode 100644
index 00000000..ed8d2071
--- /dev/null
+++ b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
@@ -0,0 +1,360 @@
+"use client";
+
+import { ExternalLinkIcon, Loader2, WandSparklesIcon } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  emptyDisplayConfig,
+  inferDisplayConfig,
+  mockKnowledgeSearchV2Result,
+  normalizeDisplaySources,
+} from "@/core/skill-display/display-adapter";
+import { getSkillDisplaySample } from "@/core/skills/api";
+import { useSetSkillDisplay } from "@/core/skills/hooks";
+import type { Skill, SkillDisplayConfig, SkillDisplayMode, SkillLinkStrategy } from "@/core/skills/type";
+
+const fieldLabels: Array<[keyof SkillDisplayConfig, string]> = [
+  ["resultPath", "结果列表路径"],
+  ["titleField", "标题字段"],
+  ["summaryField", "摘要字段"],
+  ["contentField", "正文内容字段"],
+  ["sourceField", "来源字段"],
+  ["typeField", "类型字段"],
+  ["timeField", "时间字段"],
+  ["scoreField", "相关度字段"],
+  ["urlField", "URL 跳转字段"],
+  ["idField", "ID 跳转字段"],
+  ["linkTemplate", "ID 跳转链接模板"],
+];
+
+const displayModeLabels: Record<SkillDisplayMode, string> = {
+  citation: "编号引用",
+  list: "列表展示",
+  table: "表格展示",
+  card: "卡片展示",
+  custom: "自定义展示",
+  none: "不展示",
+};
+
+const linkStrategyLabels: Record<SkillLinkStrategy, string> = {
+  auto: "自动判断",
+  url: "使用 URL 字段跳转",
+  id: "使用 ID 模板跳转",
+};
+
+function updateConfig<K extends keyof SkillDisplayConfig>(
+  config: SkillDisplayConfig,
+  key: K,
+  value: SkillDisplayConfig[K],
+): SkillDisplayConfig {
+  return { ...config, [key]: value };
+}
+
+export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
+  const setDisplay = useSetSkillDisplay();
+  const [draft, setDraft] = useState<SkillDisplayConfig>(() => skill.display ?? emptyDisplayConfig());
+  const [sampleText, setSampleText] = useState(() => JSON.stringify(mockKnowledgeSearchV2Result, null, 2));
+  const [tableColumnsText, setTableColumnsText] = useState(() => JSON.stringify((skill.display ?? emptyDisplayConfig()).tableColumns ?? [], null, 2));
+
+  // Echo server state into the form — on mount, on skill switch, AND after
+  // a successful save (the refetched skill object has a new `display` identity).
+  // Important: this drives the "保存后回显" behavior. Without depending on
+  // `skill.display`, any backend-side normalization (e.g. default values
+  // backfilled by Pydantic, column reordering) would not flow back into the UI.
+  useEffect(() => {
+    const display = skill.display ?? emptyDisplayConfig();
+    setDraft(display);
+    setTableColumnsText(JSON.stringify(display.tableColumns ?? [], null, 2));
+  }, [skill.name, skill.display]);
+
+  // Sample text is editor-only state — never reset on save. Only seed it once
+  // per skill, otherwise the user loses the JSON they just pulled in via
+  // 自动识别 every time they hit 保存.
+  useEffect(() => {
+    setSampleText(JSON.stringify(mockKnowledgeSearchV2Result, null, 2));
+  }, [skill.name]);
+
+  const samplePayload = useMemo(() => {
+    try {
+      return JSON.parse(sampleText);
+    } catch {
+      return null;
+    }
+  }, [sampleText]);
+
+  const previewItems = useMemo(() => (
+    samplePayload ? normalizeDisplaySources(samplePayload, draft) : []
+  ), [draft, samplePayload]);
+
+  function generateDraft() {
+    if (!samplePayload) {
+      toast.error("样例返回不是有效的 JSON");
+      return;
+    }
+    const nextDraft = inferDisplayConfig(samplePayload, skill.name);
+    setDraft(nextDraft);
+    setTableColumnsText(JSON.stringify(nextDraft.tableColumns ?? [], null, 2));
+    toast.success("已生成展示适配草稿");
+  }
+
+  async function loadSampleAndGenerate() {
+    try {
+      const response = await getSkillDisplaySample(skill.name);
+      const nextSampleText = JSON.stringify(response.sample, null, 2);
+      setSampleText(nextSampleText);
+      const nextDraft = inferDisplayConfig(response.sample, skill.name);
+      setDraft(nextDraft);
+      setTableColumnsText(JSON.stringify(nextDraft.tableColumns ?? [], null, 2));
+      toast.success("已获取样例并生成展示适配");
+    } catch (err) {
+      generateDraft();
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function saveDraft() {
+    try {
+      await setDisplay.mutateAsync({ skillName: skill.name, display: draft });
+      toast.success("展示适配已保存");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function clearDisplay() {
+    try {
+      await setDisplay.mutateAsync({ skillName: skill.name, display: null });
+      setDraft(emptyDisplayConfig());
+      setTableColumnsText(JSON.stringify([], null, 2));
+      toast.success("展示适配已清除");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="rounded-lg border bg-muted/20 p-4">
+        <div className="flex flex-wrap items-center justify-between gap-3">
+          <div>
+            <div className="text-sm font-medium">技能展示适配</div>
+            <p className="mt-1 text-xs text-muted-foreground">
+              从技能返回样例中自动识别字段，然后把技能结果显示为编号引用、列表、卡片或自定义样式。
+            </p>
+          </div>
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground">启用</span>
+            <Switch
+              checked={draft.enabled}
+              onCheckedChange={(checked) => setDraft(updateConfig(draft, "enabled", checked))}
+            />
+          </div>
+        </div>
+
+        <div className="mt-4 grid gap-3 md:grid-cols-3">
+          <label className="space-y-1.5">
+            <span className="text-xs text-muted-foreground">展示方式</span>
+            <Select
+              value={draft.mode}
+              onValueChange={(value) => setDraft(updateConfig(draft, "mode", value as SkillDisplayMode))}
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {Object.entries(displayModeLabels).map(([value, label]) => (
+                  <SelectItem key={value} value={value}>{label}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </label>
+
+          <label className="space-y-1.5">
+            <span className="text-xs text-muted-foreground">跳转方式</span>
+            <Select
+              value={draft.linkStrategy}
+              onValueChange={(value) => setDraft(updateConfig(draft, "linkStrategy", value as SkillLinkStrategy))}
+            >
+              <SelectTrigger className="w-full">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                {Object.entries(linkStrategyLabels).map(([value, label]) => (
+                  <SelectItem key={value} value={value}>{label}</SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </label>
+
+          <label className="space-y-1.5">
+            <span className="text-xs text-muted-foreground">最多展示条数</span>
+            <Input
+              type="number"
+              min={1}
+              max={100}
+              value={draft.maxItems}
+              onChange={(event) => setDraft(updateConfig(draft, "maxItems", Number(event.currentTarget.value) || 1))}
+            />
+          </label>
+        </div>
+
+        <div className="mt-4 grid gap-3 md:grid-cols-2">
+          {fieldLabels.map(([field, label]) => (
+            <label key={field} className="space-y-1.5">
+              <span className="text-xs text-muted-foreground">{label}</span>
+              <Input
+                value={(draft[field] as string | number | boolean | null | undefined)?.toString() ?? ""}
+                onChange={(event) => setDraft(updateConfig(draft, field, event.currentTarget.value as never))}
+                placeholder={field === "linkTemplate" ? "https://xxx.xxx.xxx?recuuid={recUuid}" : undefined}
+              />
+            </label>
+          ))}
+        </div>
+
+        {draft.mode === "table" && (
+          <label className="mt-4 block space-y-1.5">
+            <span className="text-xs text-muted-foreground">表格列配置 JSON</span>
+            <Textarea
+              value={tableColumnsText}
+              onChange={(event) => {
+                setTableColumnsText(event.currentTarget.value);
+                try {
+                  const value = JSON.parse(event.currentTarget.value);
+                  if (Array.isArray(value)) {
+                    setDraft(updateConfig(draft, "tableColumns", value));
+                  }
+                } catch {
+                  // Keep typing invalid JSON without crashing the panel.
+                }
+              }}
+              placeholder={'[{"label":"任务名称","field":"title"},{"label":"状态","field":"status"}]'}
+              className="min-h-24 font-mono text-xs"
+            />
+          </label>
+        )}
+
+        {draft.mode === "custom" && (
+          <label className="mt-4 block space-y-1.5">
+            <span className="text-xs text-muted-foreground">自定义展示描述</span>
+            <Textarea
+              value={draft.customInstruction}
+              onChange={(event) => setDraft(updateConfig(draft, "customInstruction", event.currentTarget.value))}
+              placeholder="例如：按 publish_time 时间倒序显示为时间线，每条包含标题、摘要、来源和查看原文按钮。"
+              className="min-h-24"
+            />
+          </label>
+        )}
+      </div>
+
+      <div className="grid gap-4 lg:grid-cols-2">
+        <div className="space-y-2">
+          <div className="flex items-center justify-between gap-2">
+            <div className="text-sm font-medium">技能返回样例</div>
+            <Button size="sm" variant="outline" onClick={() => void loadSampleAndGenerate()}>
+              <WandSparklesIcon className="size-3.5" />
+              自动识别
+            </Button>
+          </div>
+          <Textarea
+            value={sampleText}
+            onChange={(event) => setSampleText(event.currentTarget.value)}
+            className="min-h-72 font-mono text-xs"
+          />
+        </div>
+
+        <div className="space-y-2">
+          <div className="text-sm font-medium">展示预览</div>
+          <div className="min-h-72 space-y-2 rounded-lg border bg-muted/20 p-3">
+            {!samplePayload ? (
+              <div className="text-sm text-destructive">样例 JSON 解析失败</div>
+            ) : previewItems.length === 0 ? (
+              <div className="text-sm text-muted-foreground">当前字段映射没有解析出结果</div>
+            ) : draft.mode === "citation" ? (
+              <>
+                <p className="text-sm leading-relaxed">
+                  编号引用预览：
+                  {previewItems.slice(0, 3).map((_item, idx) => (
+                    <button
+                      type="button"
+                      key={idx}
+                      className="mx-1 inline-flex h-6 min-w-6 items-center justify-center rounded-md border bg-background px-2 text-xs font-semibold"
+                    >
+                      [{idx + 1}]
+                    </button>
+                  ))}
+                </p>
+                {previewItems.map((item, idx) => (
+                  <PreviewItem key={idx} index={idx + 1} item={item} />
+                ))}
+              </>
+            ) : (
+              previewItems.map((item, idx) => <PreviewItem key={idx} index={idx + 1} item={item} />)
+            )}
+          </div>
+        </div>
+      </div>
+
+      <div className="flex items-center justify-end gap-2">
+        <Button variant="outline" onClick={() => void clearDisplay()} disabled={setDisplay.isPending}>
+          清除
+        </Button>
+        <Button onClick={() => void saveDraft()} disabled={setDisplay.isPending}>
+          {setDisplay.isPending && <Loader2 className="size-3.5 animate-spin" />}
+          保存展示适配
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+function PreviewItem({
+  index,
+  item,
+}: {
+  index: number;
+  item: ReturnType<typeof normalizeDisplaySources>[number];
+}) {
+  return (
+    <div className="rounded-md border bg-background p-3 text-xs">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <div className="font-medium">
+            [{index}] {item.title}
+          </div>
+          <div className="mt-1 text-muted-foreground">
+            {item.type}
+            {item.source ? ` | ${item.source}` : ""}
+            {item.time ? ` | ${item.time}` : ""}
+            {typeof item.score === "number" ? ` | ${item.score.toFixed(3)}` : ""}
+          </div>
+        </div>
+        {item.url && (
+          <a
+            href={item.url}
+            target="_blank"
+            rel="noreferrer"
+            className="text-muted-foreground hover:text-foreground"
+            title="打开链接"
+          >
+            <ExternalLinkIcon className="size-4" />
+          </a>
+        )}
+      </div>
+      <p className="mt-2 line-clamp-3 leading-relaxed text-muted-foreground">
+        {item.snippet || item.content || "暂无摘要"}
+      </p>
+    </div>
+  );
+}
diff --git a/frontend-web/src/components/workspace/skill-display-block.tsx b/frontend-web/src/components/workspace/skill-display-block.tsx
new file mode 100644
index 00000000..9eac79cf
--- /dev/null
+++ b/frontend-web/src/components/workspace/skill-display-block.tsx
@@ -0,0 +1,184 @@
+import { ExternalLinkIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import type { SkillDisplayTableColumn } from "@/core/skills/type";
+import type { RuntimeDisplaySource } from "@/core/skill-display/runtime";
+import { cn } from "@/lib/utils";
+
+import { SourceCard } from "./skill-display-sources";
+
+export function SkillDisplayBlock({
+  mode,
+  sources,
+  className,
+}: {
+  mode: RuntimeDisplaySource["mode"];
+  sources: RuntimeDisplaySource[];
+  className?: string;
+}) {
+  if (sources.length === 0 || mode === "citation" || mode === "none") {
+    return null;
+  }
+  if (mode === "table") {
+    return <SkillDisplayTable sources={sources} className={className} />;
+  }
+  return (
+    <div className={cn("not-prose my-4 grid gap-2", className)}>
+      {sources.map((source) => (
+        <SourceCard key={`${source.skillName}-${source.index}`} source={source} />
+      ))}
+    </div>
+  );
+}
+
+function SkillDisplayTable({
+  sources,
+  className,
+}: {
+  sources: RuntimeDisplaySource[];
+  className?: string;
+}) {
+  const [selected, setSelected] = useState<RuntimeDisplaySource | null>(null);
+  const columns = useMemo(() => buildColumns(sources), [sources]);
+
+  return (
+    <div className={cn("not-prose my-4 overflow-hidden rounded-md border bg-card", className)}>
+      <div className="overflow-x-auto">
+        <table className="w-full min-w-[560px] text-sm">
+          <thead className="bg-muted/60 text-muted-foreground">
+            <tr>
+              {columns.map((column) => (
+                <th
+                  key={column.field}
+                  className="px-3 py-2 text-left font-medium"
+                  style={column.width ? { width: column.width } : undefined}
+                >
+                  {column.label}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {sources.map((source) => (
+              <tr
+                key={`${source.skillName}-${source.index}`}
+                className="cursor-pointer border-t transition-colors hover:bg-accent/40"
+                onClick={() => setSelected(source)}
+              >
+                {columns.map((column) => (
+                  <td key={column.field} className="max-w-[280px] px-3 py-2 align-top">
+                    <span className="line-clamp-2 break-words">
+                      {formatCell(readByPath(source.raw, column.field))}
+                    </span>
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      <SourceDetailDialog source={selected} onOpenChange={(open) => !open && setSelected(null)} />
+    </div>
+  );
+}
+
+function SourceDetailDialog({
+  source,
+  onOpenChange,
+}: {
+  source: RuntimeDisplaySource | null;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const content = source?.content || source?.snippet;
+  const meta = source
+    ? [source.source, source.type, source.time].filter(Boolean)
+    : [];
+
+  return (
+    <Dialog open={!!source} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl">
+        {source && (
+          <>
+            <DialogHeader>
+              <div className="flex items-start justify-between gap-3 pr-8">
+                <div className="min-w-0">
+                  <DialogTitle className="text-base leading-relaxed">
+                    {source.title}
+                  </DialogTitle>
+                  {meta.length > 0 && (
+                    <DialogDescription className="mt-1 flex flex-wrap gap-x-2 gap-y-1 text-xs">
+                      {meta.map((item, index) => (
+                        <span key={`${item}-${index}`}>{item}</span>
+                      ))}
+                    </DialogDescription>
+                  )}
+                </div>
+                {source.url && (
+                  <Button size="icon-sm" variant="outline" asChild>
+                    <a
+                      href={source.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      aria-label="打开来源"
+                    >
+                      <ExternalLinkIcon className="size-4" />
+                    </a>
+                  </Button>
+                )}
+              </div>
+            </DialogHeader>
+            {content && (
+              <div className="text-foreground max-h-[45vh] overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed">
+                {content}
+              </div>
+            )}
+            <pre className="bg-muted/40 max-h-[32vh] overflow-auto rounded-md p-3 text-xs">
+              {JSON.stringify(source.raw, null, 2)}
+            </pre>
+          </>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function buildColumns(sources: RuntimeDisplaySource[]): SkillDisplayTableColumn[] {
+  const configured = sources[0]?.tableColumns?.filter((column) => column.field);
+  if (configured && configured.length > 0) {
+    return configured;
+  }
+  const raw = sources[0]?.raw ?? {};
+  return Object.keys(raw)
+    .slice(0, 6)
+    .map((field) => ({ label: field, field }));
+}
+
+function readByPath(value: unknown, path: string): unknown {
+  if (!path) {
+    return value;
+  }
+  return path.split(".").reduce<unknown>((acc, key) => {
+    if (acc && typeof acc === "object") {
+      return (acc as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, value);
+}
+
+function formatCell(value: unknown): string {
+  if (value === null || value === undefined) {
+    return "";
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
diff --git a/frontend-web/src/components/workspace/skill-display-sources.tsx b/frontend-web/src/components/workspace/skill-display-sources.tsx
new file mode 100644
index 00000000..0c5bfcdf
--- /dev/null
+++ b/frontend-web/src/components/workspace/skill-display-sources.tsx
@@ -0,0 +1,155 @@
+import { ExternalLinkIcon } from "lucide-react";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import type { RuntimeDisplaySource } from "@/core/skill-display/runtime";
+import { cn } from "@/lib/utils";
+import { useState } from "react";
+
+export function SkillDisplaySources({
+  sources,
+  className,
+}: {
+  sources: RuntimeDisplaySource[];
+  className?: string;
+}) {
+  if (sources.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn("not-prose grid gap-2", className)}>
+      {sources.map((source) => (
+        <SourceCard
+          key={`${source.skillName}-${source.index}`}
+          source={source}
+          referenceTarget
+        />
+      ))}
+    </div>
+  );
+}
+
+export function SourceCard({
+  source,
+  referenceTarget = false,
+}: {
+  source: RuntimeDisplaySource;
+  referenceTarget?: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+  const content = source.content || source.snippet;
+  const score =
+    typeof source.score === "number"
+      ? source.score <= 1
+        ? `${Math.round(source.score * 100)}%`
+        : String(source.score)
+      : null;
+  const meta = [
+    source.source,
+    source.type && source.type !== "result" ? source.type : null,
+    source.time,
+    score ? `相关度 ${score}` : null,
+  ].filter(Boolean);
+  const isCitation = source.mode === "citation";
+
+  return (
+    <>
+      <button
+        id={referenceTarget ? `reference-${source.index}` : undefined}
+        type="button"
+        className={cn(
+          "group bg-card/60 hover:bg-card hover:border-primary/40 focus-visible:ring-primary/30 w-full scroll-mt-12 rounded-xl border px-3.5 py-3 text-left shadow-sm transition-all focus-visible:ring-2 focus-visible:outline-none",
+          "target:bg-primary/5 target:border-primary/60",
+        )}
+        onClick={() => setOpen(true)}
+      >
+        <div className="flex items-start gap-3">
+          {isCitation && (
+            <span className="bg-primary/10 text-primary border-primary/20 group-hover:bg-primary/15 mt-0.5 inline-flex size-6 shrink-0 items-center justify-center rounded-full border text-xs font-semibold tabular-nums">
+              {source.index}
+            </span>
+          )}
+          <div className="min-w-0 flex-1 space-y-1.5">
+            <div className="text-foreground line-clamp-2 text-sm leading-snug font-medium">
+              {source.title}
+            </div>
+            {meta.length > 0 && (
+              <div className="text-muted-foreground flex flex-wrap items-center gap-x-2 gap-y-0.5 text-[11px]">
+                {meta.map((item, index) => (
+                  <span key={`${item}-${index}`} className="inline-flex items-center">
+                    {index > 0 && <span className="mr-2 opacity-50">·</span>}
+                    <span className="truncate">{item}</span>
+                  </span>
+                ))}
+              </div>
+            )}
+            {content && (
+              <p className="text-muted-foreground/90 line-clamp-2 text-xs leading-relaxed">
+                {content}
+              </p>
+            )}
+          </div>
+          {source.url && (
+            <ExternalLinkIcon className="text-muted-foreground/60 group-hover:text-primary mt-1 size-3.5 shrink-0 transition-colors" />
+          )}
+        </div>
+      </button>
+      <Dialog open={open} onOpenChange={setOpen}>
+        <DialogContent className="max-w-2xl">
+          <DialogHeader>
+            <div className="flex items-start justify-between gap-3 pr-8">
+              <div className="min-w-0 flex-1">
+                <div className="flex items-start gap-2">
+                  {isCitation && (
+                    <span className="bg-primary/10 text-primary border-primary/20 mt-1 inline-flex size-6 shrink-0 items-center justify-center rounded-full border text-xs font-semibold tabular-nums">
+                      {source.index}
+                    </span>
+                  )}
+                  <DialogTitle className="text-base leading-relaxed">
+                    {source.title}
+                  </DialogTitle>
+                </div>
+                {meta.length > 0 && (
+                  <DialogDescription className="mt-2 flex flex-wrap gap-x-2 gap-y-1 text-xs">
+                    {meta.map((item, index) => (
+                      <span key={`${item}-${index}`}>{item}</span>
+                    ))}
+                  </DialogDescription>
+                )}
+              </div>
+              {source.url && (
+                <Button size="icon-sm" variant="outline" asChild>
+                  <a
+                    href={source.url}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    aria-label="打开来源"
+                  >
+                    <ExternalLinkIcon className="size-4" />
+                  </a>
+                </Button>
+              )}
+            </div>
+          </DialogHeader>
+          {content && (
+            <div className="text-foreground max-h-[55vh] overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed">
+              {content}
+            </div>
+          )}
+          {source.url && (
+            <div className="text-muted-foreground border-t pt-3 text-xs break-all">
+              {source.url}
+            </div>
+          )}
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
diff --git a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
index ca401519..1d687e7f 100644
--- a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
+++ b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
@@ -9,6 +9,7 @@ import {
   GlobeIcon,
   Loader2,
   PencilIcon,
+  SlidersHorizontalIcon,
   SparklesIcon,
 } from "lucide-react";
 import { useEffect, useMemo, useState } from "react";
@@ -26,6 +27,7 @@ import {
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { Textarea } from "@/components/ui/textarea";
 import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
+import { SkillDisplayAdapterPanel } from "@/components/workspace/skill-display-adapter-panel";
 import { SkillFilePreviewDialog } from "@/components/workspace/skills/skill-file-preview-dialog";
 import { SkillFileTree } from "@/components/workspace/skills/skill-file-tree";
 import { getStoredAuth } from "@/core/auth";
@@ -87,7 +89,7 @@ export function SkillDetailDialog({
   const [editing, setEditing] = useState(false);
   const [draft, setDraft] = useState("");
   const [activeTab, setActiveTab] = useState<
-    "detail" | "source" | "files" | null
+    "detail" | "display" | "source" | "files" | null
   >(null);
   const [showRawSource, setShowRawSource] = useState(false);
   const [openedFilePath, setOpenedFilePath] = useState<string | null>(null);
@@ -206,6 +208,12 @@ export function SkillDetailDialog({
                 <FileTextIcon className="mr-1 size-3.5" />
                 {tx.detailSectionTitle}
               </TabsTrigger>
+              {canManage && (
+                <TabsTrigger value="display" className="text-xs">
+                  <SlidersHorizontalIcon className="mr-1 size-3.5" />
+                  展示适配
+                </TabsTrigger>
+              )}
               {canManage && (
                 <TabsTrigger value="files" className="text-xs">
                   <FilesIcon className="mr-1 size-3.5" />
@@ -329,6 +337,16 @@ export function SkillDetailDialog({
             )}
           </TabsContent>
 
+          {canManage && (
+            <TabsContent
+              value="display"
+              className="m-0 min-h-0 flex-1 overscroll-contain px-6 py-5 data-[state=inactive]:hidden"
+              style={{ overflowY: "auto" }}
+            >
+              <SkillDisplayAdapterPanel skill={skill} />
+            </TabsContent>
+          )}
+
           {canManage && (
             <TabsContent
               value="files"
diff --git a/frontend-web/src/core/settings/local.ts b/frontend-web/src/core/settings/local.ts
index 1d9e1d5d..8e5166ab 100644
--- a/frontend-web/src/core/settings/local.ts
+++ b/frontend-web/src/core/settings/local.ts
@@ -4,9 +4,10 @@ export const DEFAULT_LOCAL_SETTINGS: LocalSettings = {
   notification: {
     enabled: true,
   },
-  display: {
-    streamSpeedMeterEnabled: true,
-  },
+  display: {
+    streamSpeedMeterEnabled: true,
+    ragModeEnabled: true,
+  },
   context: {
     model_name: undefined,
     mode: undefined,
@@ -32,8 +33,13 @@ export interface LocalSettings {
      * AI reply is in flight. Default on; controlled by the user from
      * the appearance settings page.
      */
-    streamSpeedMeterEnabled: boolean;
-  };
+    streamSpeedMeterEnabled: boolean;
+    /**
+     * Global switch for skill result display adapters. When disabled, chat
+     * messages render tool results with the legacy generic search UI only.
+     */
+    ragModeEnabled: boolean;
+  };
   context: Omit<
     AgentThreadContext,
     | "thread_id"
diff --git a/frontend-web/src/core/skill-display/display-adapter.ts b/frontend-web/src/core/skill-display/display-adapter.ts
new file mode 100644
index 00000000..1add1cf1
--- /dev/null
+++ b/frontend-web/src/core/skill-display/display-adapter.ts
@@ -0,0 +1,209 @@
+import type { SkillDisplayConfig } from "@/core/skills/type";
+
+export interface DisplaySourceItem {
+  id?: string;
+  title: string;
+  type: string;
+  snippet: string;
+  source?: string;
+  time?: string;
+  url?: string;
+  content?: string;
+  score?: number;
+  raw: Record<string, unknown>;
+}
+
+export const emptyDisplayConfig = (): SkillDisplayConfig => ({
+  enabled: false,
+  mode: "none",
+  resultPath: "results",
+  titleField: null,
+  summaryField: null,
+  contentField: null,
+  sourceField: null,
+  typeField: null,
+  timeField: null,
+  scoreField: null,
+  urlField: null,
+  idField: null,
+  linkStrategy: "auto",
+    linkTemplate: null,
+    citationToken: "doubleBracket",
+    maxItems: 8,
+    customInstruction: "",
+    tableColumns: [],
+});
+
+export const mockKnowledgeSearchV2Result = {
+  success: true,
+  query: "latest news",
+  count: 3,
+  results: [
+    {
+      index: 1,
+      recUuid: "rec-001",
+      relevance_score: 0.982,
+      title: "Knowledge result one",
+      source_category: "knowledge/news",
+      source: "internal news library",
+      publish_time: "2026-05-25",
+      content_preview: "Mock result used to verify citation numbers, source cards, and recUuid template links.",
+      content_length: 1200,
+    },
+    {
+      index: 2,
+      recUuid: "rec-002",
+      relevance_score: 0.951,
+      title: "Knowledge result two",
+      source_category: "knowledge/news",
+      source: "internal news library",
+      publish_time: "2026-05-24",
+      content_preview: "Mock result used to verify citation ordering and detail preview.",
+      content_length: 980,
+    },
+    {
+      index: 3,
+      recUuid: "rec-003",
+      relevance_score: 0.921,
+      title: "Knowledge result three",
+      source_category: "knowledge/commentary",
+      source: "internal knowledge library",
+      publish_time: "2026-05-23",
+      content_preview: "Mock result used to verify list mode and custom display instruction previews.",
+      content_length: 760,
+    },
+  ],
+};
+
+const candidateFields: Record<string, string[]> = {
+  titleField: ["title", "m_title", "name", "subject", "headline"],
+  summaryField: ["summary", "snippet", "content_preview", "description", "abstract"],
+  contentField: ["content", "page_content", "text", "content_preview", "body"],
+  sourceField: ["source", "source_name", "site", "from", "origin"],
+  typeField: ["type", "category", "source_category", "source1"],
+  timeField: ["publish_time", "m_publish", "updatedAt", "createdAt", "date", "time"],
+  scoreField: ["relevance_score", "rerank_score", "score", "similarity"],
+  urlField: ["url", "link", "href", "source_url"],
+  idField: ["recUuid", "id", "uuid", "docId", "taskId", "recordId"],
+};
+
+function getByPath(value: unknown, path: string): unknown {
+  if (!path) return value;
+  return path.split(".").reduce<unknown>((acc, key) => {
+    if (acc && typeof acc === "object") return (acc as Record<string, unknown>)[key];
+    return undefined;
+  }, value);
+}
+
+function findFirstArray(value: unknown, path = ""): { path: string; items: Record<string, unknown>[] } | null {
+  if (Array.isArray(value) && value.every((item) => item && typeof item === "object")) {
+    return { path, items: value as Record<string, unknown>[] };
+  }
+  if (!value || typeof value !== "object") return null;
+  for (const [key, child] of Object.entries(value)) {
+    const found = findFirstArray(child, path ? `${path}.${key}` : key);
+    if (found) return found;
+  }
+  return null;
+}
+
+function pickField(sample: Record<string, unknown>, candidates: string[]): string | null {
+  const keys = Object.keys(sample);
+  for (const candidate of candidates) {
+    const exact = keys.find((key) => key === candidate);
+    if (exact) return exact;
+  }
+  for (const candidate of candidates) {
+    const lowered = candidate.toLowerCase();
+    const fuzzy = keys.find((key) => key.toLowerCase().includes(lowered));
+    if (fuzzy) return fuzzy;
+  }
+  return null;
+}
+
+export function inferDisplayConfig(samplePayload: unknown, skillName?: string): SkillDisplayConfig {
+  const found = findFirstArray(samplePayload) ?? { path: "results", items: [] };
+  const sample = found.items[0] ?? {};
+  const inferred = emptyDisplayConfig();
+  inferred.enabled = true;
+  inferred.mode = skillName === "knowledge-search-v2" ? "citation" : "list";
+  inferred.resultPath = found.path || "results";
+  inferred.maxItems = inferred.mode === "citation" ? 8 : 20;
+
+  for (const [target, candidates] of Object.entries(candidateFields)) {
+    (inferred as unknown as Record<string, string | null>)[target] = pickField(sample, candidates);
+  }
+
+  if (skillName === "knowledge-search-v2") {
+    inferred.titleField = inferred.titleField || "title";
+    inferred.summaryField = inferred.summaryField || "content_preview";
+    inferred.contentField = inferred.contentField || "content_preview";
+    inferred.sourceField = inferred.sourceField || "source";
+    inferred.typeField = inferred.typeField || "source_category";
+    inferred.timeField = inferred.timeField || "publish_time";
+    inferred.scoreField = inferred.scoreField || "relevance_score";
+    inferred.idField = inferred.idField || "recUuid";
+    inferred.linkStrategy = "id";
+    inferred.linkTemplate = "https://xxx.xxx.xxx?recuuid={recUuid}";
+  }
+  inferred.tableColumns = buildDefaultTableColumns(sample, inferred);
+
+  return inferred;
+}
+
+function buildDefaultTableColumns(
+  sample: Record<string, unknown>,
+  config: SkillDisplayConfig,
+): NonNullable<SkillDisplayConfig["tableColumns"]> {
+  const preferred = [
+    config.titleField,
+    config.typeField,
+    config.sourceField,
+    config.timeField,
+    config.scoreField,
+  ].filter((field): field is string => !!field);
+  const fallback = Object.keys(sample)
+    .filter((field) => !preferred.includes(field))
+    .slice(0, Math.max(0, 6 - preferred.length));
+  return [...preferred, ...fallback].slice(0, 8).map((field) => ({
+    label: field,
+    field,
+  }));
+}
+
+function stringify(value: unknown, fallback = ""): string {
+  if (value === null || value === undefined) return fallback;
+  return String(value);
+}
+
+function renderTemplate(template: string, item: Record<string, unknown>): string {
+  return template.replace(/\{([^}]+)\}/g, (_match, key: string) => encodeURIComponent(stringify(item[key])));
+}
+
+function resolveLink(item: Record<string, unknown>, config: SkillDisplayConfig): string | undefined {
+  const url = config.urlField ? stringify(item[config.urlField]) : "";
+  const id = config.idField ? stringify(item[config.idField]) : "";
+  if (config.linkStrategy === "url") return url || undefined;
+  if (config.linkStrategy === "id") return id && config.linkTemplate ? renderTemplate(config.linkTemplate, item) : undefined;
+  return url || (id && config.linkTemplate ? renderTemplate(config.linkTemplate, item) : undefined) || undefined;
+}
+
+export function normalizeDisplaySources(payload: unknown, config: SkillDisplayConfig): DisplaySourceItem[] {
+  const rawItems = getByPath(payload, config.resultPath);
+  if (!Array.isArray(rawItems)) return [];
+  return rawItems
+    .filter((item): item is Record<string, unknown> => !!item && typeof item === "object")
+    .slice(0, config.maxItems)
+    .map((item, index) => ({
+      id: config.idField ? stringify(item[config.idField]) : undefined,
+      title: config.titleField ? stringify(item[config.titleField], `Result ${index + 1}`) : `Result ${index + 1}`,
+      type: config.typeField ? stringify(item[config.typeField], "result") : "result",
+      snippet: config.summaryField ? stringify(item[config.summaryField]) : "",
+      content: config.contentField ? stringify(item[config.contentField]) : undefined,
+      source: config.sourceField ? stringify(item[config.sourceField]) : undefined,
+      time: config.timeField ? stringify(item[config.timeField]) : undefined,
+      score: config.scoreField && typeof item[config.scoreField] === "number" ? item[config.scoreField] as number : undefined,
+      url: resolveLink(item, config),
+      raw: item,
+    }));
+}
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
new file mode 100644
index 00000000..ef18c1ee
--- /dev/null
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -0,0 +1,350 @@
+import type { Message } from "@langchain/langgraph-sdk";
+
+import { normalizeSearchResults } from "@/core/messages/search-results";
+import type { Skill, SkillDisplayConfig } from "@/core/skills/type";
+
+import {
+  normalizeDisplaySources,
+  type DisplaySourceItem,
+} from "./display-adapter";
+
+export type RuntimeDisplaySource = DisplaySourceItem & {
+  index: number;
+  skillName: string;
+  mode: SkillDisplayConfig["mode"];
+  tableColumns?: SkillDisplayConfig["tableColumns"];
+};
+
+export type SkillDisplayMap = Map<string, SkillDisplayConfig>;
+
+export function buildSkillDisplayMap(skills: Skill[]): SkillDisplayMap {
+  const map = new Map<string, SkillDisplayConfig>();
+  for (const skill of skills) {
+    const display = skill.display;
+    if (!display?.enabled || display.mode === "none") {
+      continue;
+    }
+    map.set(skill.name, display);
+  }
+  return map;
+}
+
+export function findDisplayConfigForTool(
+  toolName: string,
+  displays: SkillDisplayMap,
+  toolArgs?: Record<string, unknown>,
+): { skillName: string; display: SkillDisplayConfig } | null {
+  const exact = displays.get(toolName);
+  if (exact) {
+    return { skillName: toolName, display: exact };
+  }
+
+  const normalizedTool = normalizeName(toolName);
+  for (const [skillName, display] of displays) {
+    const normalizedSkill = normalizeName(skillName);
+    if (
+      normalizedTool === normalizedSkill ||
+      normalizedTool.endsWith(normalizedSkill) ||
+      normalizedTool.includes(normalizedSkill)
+    ) {
+      return { skillName, display };
+    }
+  }
+
+  // bash/python skill invocations don't carry the skill name in the tool name —
+  // the path lives inside the command/args (e.g. `python3 skills/custom/demo/scripts/run.py`).
+  // Scan stringy args for the `skills/{public,custom}/<name>/` shape so display
+  // configs still resolve. Mirrors the backend `_SKILL_PATH_RE` in
+  // tool_metrics_middleware.py.
+  if (toolArgs) {
+    const skillFromArgs = extractSkillNameFromArgs(toolArgs);
+    if (skillFromArgs) {
+      const direct = displays.get(skillFromArgs);
+      if (direct) {
+        return { skillName: skillFromArgs, display: direct };
+      }
+    }
+  }
+  return null;
+}
+
+const SKILL_PATH_RE = /[\\/]skills[\\/](?:public|custom)[\\/]([^\\/]+)(?:[\\/]|$)/;
+
+function extractSkillNameFromArgs(args: Record<string, unknown>): string | undefined {
+  for (const value of Object.values(args)) {
+    if (typeof value !== "string") continue;
+    const match = SKILL_PATH_RE.exec(value);
+    if (match) {
+      return match[1];
+    }
+  }
+  return undefined;
+}
+
+export function collectRuntimeDisplaySources(
+  messages: Message[],
+  displays: SkillDisplayMap,
+  options: {
+    afterMessageId?: string;
+    beforeMessageId?: string;
+    includeModes?: SkillDisplayConfig["mode"][];
+  } = {},
+): RuntimeDisplaySource[] {
+  const start =
+    options.afterMessageId === undefined
+      ? 0
+      : Math.max(
+          messages.findIndex((message) => message.id === options.afterMessageId) + 1,
+          0,
+        );
+  const limit =
+    options.beforeMessageId === undefined
+      ? messages.length
+      : Math.max(
+          messages.findIndex((message) => message.id === options.beforeMessageId),
+          0,
+        );
+  const allowedModes = options.includeModes
+    ? new Set(options.includeModes)
+    : null;
+  const sources: RuntimeDisplaySource[] = [];
+  let citationIndex = 0;
+  const displayIndexes = new Map<string, number>();
+
+  for (let index = start; index < limit; index++) {
+    const message = messages[index];
+    if (!message || message.type !== "ai") {
+      continue;
+    }
+    for (const toolCall of message.tool_calls ?? []) {
+      const match = findDisplayConfigForTool(
+        toolCall.name,
+        displays,
+        toolCall.args as Record<string, unknown> | undefined,
+      );
+      const effectiveMode = match?.display.mode ?? "citation";
+      if (allowedModes && !allowedModes.has(effectiveMode)) {
+        continue;
+      }
+      const result = findToolResultPayload(toolCall.id, messages);
+      if (result === undefined) {
+        continue;
+      }
+      const normalized = match
+        ? normalizeDisplaySources(result, match.display)
+        : normalizeDefaultDisplaySources(result);
+      for (const item of normalized) {
+        const skillName = match?.skillName ?? toolCall.name;
+        const displayKey = `${skillName}:${effectiveMode}`;
+        const displayIndex = (displayIndexes.get(displayKey) ?? 0) + 1;
+        displayIndexes.set(displayKey, displayIndex);
+        sources.push({
+          ...item,
+          index: effectiveMode === "citation" ? ++citationIndex : displayIndex,
+          skillName,
+          mode: effectiveMode,
+          tableColumns: match?.display.tableColumns,
+        });
+      }
+    }
+  }
+  return sources;
+}
+
+export function normalizeDefaultDisplaySources(payload: unknown): DisplaySourceItem[] {
+  const normalized = normalizeSearchResults(
+    typeof payload === "string" || isRecord(payload)
+      ? (payload as string | Record<string, unknown>)
+      : undefined,
+  );
+  return normalized.map((item, index) => ({
+    id: item.url ?? String(index + 1),
+    title: item.title ?? item.source ?? `结果 ${index + 1}`,
+    type: "result",
+    snippet: item.snippet ?? item.content ?? "",
+    content: item.content ?? item.snippet,
+    source: item.source,
+    time: item.published_date ?? item.publishedDate ?? item.date,
+    url: item.url,
+    raw: item as unknown as Record<string, unknown>,
+  }));
+}
+
+export function applyInlineCitations(
+  content: string,
+  sources: RuntimeDisplaySource[],
+): string {
+  if (!content || sources.length === 0) {
+    return content;
+  }
+  const citationSources = sources.filter((source) => source.mode === "citation");
+  if (citationSources.length === 0) {
+    return content;
+  }
+  const byIndex = new Map(citationSources.map((source) => [source.index, source]));
+  const byUrl = new Map<string, RuntimeDisplaySource>();
+  const byTitle = new Map<string, RuntimeDisplaySource>();
+  for (const source of citationSources) {
+    if (source.url) {
+      byUrl.set(source.url, source);
+    }
+    if (source.title) {
+      byTitle.set(source.title.trim(), source);
+    }
+  }
+
+  const normalized = normalizeExistingCitationLinks(content, byIndex, byUrl, byTitle);
+
+  const markdownLinkPattern = /!?\[(?:[^\[\]]|\[[^\]]*\])*\]\([^)]+\)/g;
+  let cursor = 0;
+  let next = "";
+  for (const match of normalized.matchAll(markdownLinkPattern)) {
+    const start = match.index ?? 0;
+    next += replaceCitationTokens(normalized.slice(cursor, start), byIndex);
+    next += match[0];
+    cursor = start + match[0].length;
+  }
+  next += replaceCitationTokens(normalized.slice(cursor), byIndex);
+  return next;
+}
+
+function replaceCitationTokens(
+  content: string,
+  byIndex: Map<number, RuntimeDisplaySource>,
+): string {
+  return content
+    .replace(/\[\[(\d+)\]\]/g, (match, rawIndex: string) =>
+      citationMarkdown(match, Number(rawIndex), byIndex),
+    )
+    .replace(/(^|[^:\[!])\[(\d+)\](?!\()/g, (match, prefix: string, rawIndex: string) =>
+      `${prefix}${citationMarkdown(match.slice(prefix.length), Number(rawIndex), byIndex)}`,
+    );
+}
+
+function normalizeExistingCitationLinks(
+  content: string,
+  byIndex: Map<number, RuntimeDisplaySource>,
+  byUrl: Map<string, RuntimeDisplaySource>,
+  byTitle: Map<string, RuntimeDisplaySource>,
+): string {
+  // Resolve every `[citation:LABEL](URL)` link — whether LABEL is a number
+  // ("[1]", "1") or a free-form title — to a numbered reference link that
+  // CitationLink renders as a badge and scrolls to the right-side panel.
+  return content.replace(
+    /\[citation:([^\]]+)\]\(([^)]+)\)(?:\([^)]+\))*/g,
+    (match, rawLabel: string, rawUrl: string) => {
+      const label = rawLabel.trim();
+      const url = rawUrl.trim();
+      const numberMatch = label.match(/^\[?(\d+)\]?$/);
+      if (numberMatch) {
+        const index = Number(numberMatch[1]);
+        if (byIndex.has(index)) {
+          return `[citation:[${index}]](#reference-${index})`;
+        }
+      }
+      const sourceByUrl = byUrl.get(url);
+      if (sourceByUrl) {
+        return `[citation:[${sourceByUrl.index}]](#reference-${sourceByUrl.index})`;
+      }
+      const sourceByTitle = byTitle.get(label);
+      if (sourceByTitle) {
+        return `[citation:[${sourceByTitle.index}]](#reference-${sourceByTitle.index})`;
+      }
+      return match;
+    },
+  );
+}
+
+function citationMarkdown(
+  fallback: string,
+  index: number,
+  byIndex: Map<number, RuntimeDisplaySource>,
+): string {
+  const source = byIndex.get(index);
+  if (!source) {
+    return fallback;
+  }
+  return `[citation:[${index}]](#reference-${index})`;
+}
+
+function normalizeName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function findToolResultPayload(
+  toolCallId: string | undefined,
+  messages: Message[],
+): unknown {
+  if (!toolCallId) {
+    return undefined;
+  }
+  const toolMessage = messages.find(
+    (message) => message.type === "tool" && message.tool_call_id === toolCallId,
+  );
+  if (!toolMessage) {
+    return undefined;
+  }
+  const content = extractToolText(toolMessage.content);
+  if (!content) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(content) as unknown;
+  } catch {
+    // bash stdout on the local sandbox can be suffixed with
+    // "\nStd Error: ..." / "\nExit Code: N" (see local_sandbox.execute_command),
+    // and skills sometimes print informational lines around their JSON payload.
+    // Salvage the first balanced JSON object or array we can find before
+    // falling back to the raw string.
+    const recovered = extractJSONFromText(content);
+    if (recovered !== undefined) {
+      return recovered;
+    }
+    return content;
+  }
+}
+
+function extractJSONFromText(text: string): unknown {
+  const candidates: Array<[number, number]> = [];
+  const firstObj = text.indexOf("{");
+  if (firstObj !== -1) candidates.push([firstObj, text.lastIndexOf("}")]);
+  const firstArr = text.indexOf("[");
+  if (firstArr !== -1) candidates.push([firstArr, text.lastIndexOf("]")]);
+  candidates.sort(([a], [b]) => a - b);
+  for (const [start, end] of candidates) {
+    if (start < 0 || end <= start) continue;
+    const slice = text.slice(start, end + 1);
+    try {
+      return JSON.parse(slice);
+    } catch {
+      // try the next candidate
+    }
+  }
+  return undefined;
+}
+
+function extractToolText(content: unknown): string {
+  if (typeof content === "string") {
+    return content.trim();
+  }
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") {
+          return part;
+        }
+        if (part && typeof part === "object" && "text" in part) {
+          const text = (part as { text?: unknown }).text;
+          return typeof text === "string" ? text : "";
+        }
+        return "";
+      })
+      .join("\n")
+      .trim();
+  }
+  return "";
+}
diff --git a/frontend-web/src/core/skills/api.ts b/frontend-web/src/core/skills/api.ts
index 3b31cde1..ce49ad4d 100644
--- a/frontend-web/src/core/skills/api.ts
+++ b/frontend-web/src/core/skills/api.ts
@@ -1,7 +1,7 @@
 import { getBackendBaseURL } from "@/core/config";
 import { apiFetch } from "@/core/api";
 
-import type { Skill, SkillState } from "./type";
+import type { Skill, SkillDisplayConfig, SkillState } from "./type";
 
 export interface ListSkillsParams {
   search?: string;
@@ -30,7 +30,7 @@ export async function getSkill(skillName: string): Promise<Skill> {
   return response.json() as Promise<Skill>;
 }
 
-export async function enableSkill(skillName: string, enabled: boolean) {
+export async function enableSkill(skillName: string, enabled: boolean) {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/skills/${skillName}`,
     {
@@ -44,7 +44,45 @@ export async function enableSkill(skillName: string, enabled: boolean) {
     },
   );
   return response.json();
-}
+}
+
+export async function setSkillDisplay(
+  skillName: string,
+  display: SkillDisplayConfig | null,
+): Promise<Skill> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display`,
+    {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ display }),
+    },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to update skill display adapter");
+  }
+  return response.json() as Promise<Skill>;
+}
+
+export interface SkillDisplaySampleResponse {
+  skill_name: string;
+  sample: Record<string, unknown>;
+}
+
+export async function getSkillDisplaySample(
+  skillName: string,
+): Promise<SkillDisplaySampleResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
+    { method: "POST" },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to get skill display sample");
+  }
+  return response.json() as Promise<SkillDisplaySampleResponse>;
+}
 
 export interface InstallSkillRequest {
   thread_id: string;
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index 462206df..c4c67d02 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -14,14 +14,15 @@ import {
   getSkillFiles,
   installSkillUpload,
   reconcileCustomSkills,
-  saveSkillFile,
-  setSkillDetail,
-  setSkillPinned,
+  saveSkillFile,
+  setSkillDetail,
+  setSkillDisplay,
+  setSkillPinned,
   setSkillPublished,
   setSkillState,
   validateSkillUpload,
 } from "./api";
-import type { SkillState } from "./type";
+import type { SkillState } from "./type";
 
 import { loadSkills } from ".";
 
@@ -52,7 +53,7 @@ export function useSkill(skillName: string | null) {
   });
 }
 
-export function useSetSkillDetail() {
+export function useSetSkillDetail() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: ({ skillName, detail }: { skillName: string; detail: string }) =>
@@ -62,7 +63,24 @@ export function useSetSkillDetail() {
       void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
     },
   });
-}
+}
+
+export function useSetSkillDisplay() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      skillName,
+      display,
+    }: {
+      skillName: string;
+      display: Parameters<typeof setSkillDisplay>[1];
+    }) => setSkillDisplay(skillName, display),
+    onSuccess: (_data, { skillName }) => {
+      void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
+    },
+  });
+}
 
 export function useEnableSkill() {
   const queryClient = useQueryClient();
diff --git a/frontend-web/src/core/skills/type.ts b/frontend-web/src/core/skills/type.ts
index 3869014d..3a6ac12b 100644
--- a/frontend-web/src/core/skills/type.ts
+++ b/frontend-web/src/core/skills/type.ts
@@ -2,6 +2,36 @@ import type { Tag } from "@/core/tags";
 
 export type SkillState = "active" | "stale" | "archived";
 export type SkillSource = "agent" | "upload";
+export type SkillDisplayMode = "citation" | "list" | "table" | "card" | "custom" | "none";
+export type SkillLinkStrategy = "auto" | "url" | "id";
+export type SkillCitationToken = "doubleBracket" | "singleBracket";
+
+export interface SkillDisplayTableColumn {
+  label: string;
+  field: string;
+  width?: string | null;
+}
+
+export interface SkillDisplayConfig {
+  enabled: boolean;
+  mode: SkillDisplayMode;
+  resultPath: string;
+  titleField?: string | null;
+  summaryField?: string | null;
+  contentField?: string | null;
+  sourceField?: string | null;
+  typeField?: string | null;
+  timeField?: string | null;
+  scoreField?: string | null;
+  urlField?: string | null;
+  idField?: string | null;
+  linkStrategy: SkillLinkStrategy;
+  linkTemplate?: string | null;
+  citationToken: SkillCitationToken;
+  maxItems: number;
+  customInstruction: string;
+  tableColumns?: SkillDisplayTableColumn[];
+}
 
 export interface Skill {
   name: string;
@@ -17,6 +47,7 @@ export interface Skill {
   // Long-form detail/introduction authored by the skill owner or an admin.
   // Distinct from ``description`` (parsed from SKILL.md); supports Markdown.
   detail?: string | null;
+  display?: SkillDisplayConfig | null;
   // Lifecycle fields — populated by curator. The main list filters on these
   // so stale / archived skills appear in dedicated drawers instead.
   state?: SkillState;
diff --git a/frontend-web/src/core/threads/hooks.ts b/frontend-web/src/core/threads/hooks.ts
index 3c486450..ecb8a5d8 100644
--- a/frontend-web/src/core/threads/hooks.ts
+++ b/frontend-web/src/core/threads/hooks.ts
@@ -12,7 +12,8 @@ import { apiFetch } from "../api";
 import { getBackendBaseURL } from "../config";
 import { useI18n } from "../i18n/hooks";
 import type { FileInMessage } from "../messages/utils";
-import type { LocalSettings } from "../settings";
+import type { LocalSettings } from "../settings";
+import { useLocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
 import type { UploadedFileInfo } from "../uploads";
 import { promptInputFilePartToFile, uploadFiles } from "../uploads";
@@ -145,7 +146,8 @@ export function useThreadStream({
   onFinish,
   onToolEnd,
 }: ThreadStreamOptions) {
-  const { t } = useI18n();
+  const { t } = useI18n();
+  const [localSettings] = useLocalSettings();
   // Track the thread ID that is currently streaming to handle thread changes during streaming
   const [onStreamThreadId, setOnStreamThreadId] = useState(() => threadId);
   // Ref to track current thread ID across async callbacks without causing re-renders,
@@ -506,8 +508,9 @@ export function useThreadStream({
                     : context.mode === "thinking"
                       ? "low"
                       : undefined),
-              memory_injection_enabled: context.memory_injection_enabled ?? true,
-              thread_id: threadId,
+              memory_injection_enabled: context.memory_injection_enabled ?? true,
+              rag_mode_enabled: localSettings.display.ragModeEnabled,
+              thread_id: threadId,
             },
           },
         );
@@ -520,8 +523,8 @@ export function useThreadStream({
         sendInFlightRef.current = false;
       }
     },
-    [thread, _handleOnStart, t.uploads.uploadingFiles, context, queryClient],
-  );
+    [thread, _handleOnStart, t.uploads.uploadingFiles, context, localSettings.display.ragModeEnabled, queryClient],
+  );
 
   // Merge thread with optimistic messages for display
   const mergedThread =
diff --git a/frontend-web/src/core/threads/types.ts b/frontend-web/src/core/threads/types.ts
index 6c197edf..57a566a6 100644
--- a/frontend-web/src/core/threads/types.ts
+++ b/frontend-web/src/core/threads/types.ts
@@ -18,8 +18,9 @@ export interface AgentThreadContext extends Record<string, unknown> {
   reasoning_effort?: "minimal" | "low" | "medium" | "high";
   writing_mode?: boolean;
   writing_artifact_path?: string;
-  memory_injection_enabled?: boolean;
-  agent_id?: string;
+  memory_injection_enabled?: boolean;
+  rag_mode_enabled?: boolean;
+  agent_id?: string;
   /** @deprecated kept for reading legacy thread metadata; prefer agent_id */
   agent_name?: string;
 }
diff --git a/offline-backend-20260512/backend/app/gateway/routers/mcp.py b/offline-backend-20260512/backend/app/gateway/routers/mcp.py
index 0d2174fc..aeec1f70 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/mcp.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/mcp.py
@@ -182,10 +182,13 @@ async def update_mcp_configuration(request: McpConfigUpdateRequest, http_request
         current_config = get_extensions_config()
 
         # Convert request to dict format for JSON serialization
-        config_data = {
-            "mcpServers": {name: server.model_dump() for name, server in request.mcp_servers.items()},
-            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
-        }
+        config_data = {
+            "mcpServers": {name: server.model_dump(by_alias=True) for name, server in request.mcp_servers.items()},
+            "skills": {
+                name: skill.model_dump(by_alias=True, exclude_none=True)
+                for name, skill in current_config.skills.items()
+            },
+        }
 
         # Write the configuration to file
         with open(config_path, "w", encoding="utf-8") as f:
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index b3579899..1a10cad2 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -1,6 +1,8 @@
+import asyncio
 import json
 import logging
 import mimetypes
+import re
 import tempfile
 from datetime import datetime
 from pathlib import Path
@@ -14,7 +16,7 @@ from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_t
 from app.gateway.path_utils import resolve_thread_virtual_path
 from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
 from deerflow.config.app_config import AppConfig
-from deerflow.config.extensions_config import ExtensionsConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.config.extensions_config import ExtensionsConfig, SkillDisplayConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
 from deerflow.persistence.skills import SkillStore
 from deerflow.persistence.tags import TagStore
 from deerflow.runtime.user_context import get_effective_user_id
@@ -117,6 +119,7 @@ class SkillResponse(BaseModel):
     published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
     builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
     detail: str | None = Field(default=None, description="Human-authored long-form detail text (Markdown), editable by owner/admin")
+    display: dict[str, Any] | None = Field(default=None, description="Optional frontend display adapter")
     tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
 
 
@@ -132,6 +135,19 @@ class SkillUpdateRequest(BaseModel):
     enabled: bool = Field(..., description="Whether to enable or disable the skill")
 
 
+class SkillDisplayUpdateRequest(BaseModel):
+    """Request model for updating a skill's frontend display adapter."""
+
+    display: SkillDisplayConfig | None = Field(default=None, description="Display adapter configuration; null clears it")
+
+
+class SkillDisplaySampleResponse(BaseModel):
+    """Sample structured output used to infer a display adapter."""
+
+    skill_name: str
+    sample: dict[str, Any]
+
+
 class SkillInstallRequest(BaseModel):
     """Request model for installing a skill from a .skill file."""
 
@@ -215,6 +231,14 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
         builtin = bool(ownership.get("builtin", owner_user_id is None))
         detail = ownership.get("detail")
 
+    display = None
+    try:
+        skill_config = get_extensions_config().skills.get(skill.name)
+        if skill_config and skill_config.display:
+            display = skill_config.display.model_dump(by_alias=True)
+    except Exception:
+        logger.debug("Failed to read display adapter for %s", skill.name, exc_info=True)
+
     return SkillResponse(
         name=skill.name,
         description=skill.description,
@@ -232,9 +256,164 @@ def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) ->
         published=published,
         builtin=builtin,
         detail=detail,
+        display=display,
     )
 
 
+def _dump_extensions_config(config_obj: ExtensionsConfig) -> dict[str, Any]:
+    return {
+        "mcpServers": {name: server.model_dump(by_alias=True) for name, server in config_obj.mcp_servers.items()},
+        "skills": {name: skill_config.model_dump(by_alias=True, exclude_none=True) for name, skill_config in config_obj.skills.items()},
+    }
+
+
+_SKILL_SAMPLE_SYSTEM_PROMPT = (
+    "You infer realistic JSON return shapes for AI agent skills. "
+    "Given a skill's name, description, and full SKILL.md, output a SINGLE JSON object that "
+    "represents a plausible successful response from this skill's primary action. "
+    "Rules:\n"
+    "- Output JSON ONLY. No prose. No markdown fences. No comments.\n"
+    "- The top level must be a JSON object (not an array).\n"
+    "- Include a results/items/list/records array (pick the most natural key) with 2-3 example entries.\n"
+    "- Use realistic, idiomatic field names (e.g. title, content, source, publish_time, score, url, id) that match the skill's domain.\n"
+    "- Each entry should have enough fields to drive a citation/list/table UI: a title, a short snippet/content, a source, a time/date, and an id or url when relevant.\n"
+    "- Numbers stay numbers, dates stay ISO strings, scores between 0 and 1 when applicable.\n"
+    "- Do not invent fields that contradict the skill description."
+)
+
+
+def _extract_json_from_llm_output(raw: str) -> dict[str, Any] | None:
+    """Best-effort extraction of a JSON object from an LLM response."""
+    text = (raw or "").strip()
+    if not text:
+        return None
+    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.DOTALL | re.IGNORECASE)
+    if fence:
+        text = fence.group(1).strip()
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if not match:
+        return None
+    try:
+        parsed = json.loads(match.group(0))
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) -> dict[str, Any]:
+    """Generate a realistic return-shape sample for ``skill`` via the LLM.
+
+    Reads SKILL.md, asks the configured curator model (or main model) to infer
+    a plausible JSON response. Falls back to :func:`_mock_skill_display_sample`
+    when the model is unconfigured, the call times out, or the output cannot
+    be parsed as a JSON object.
+    """
+    try:
+        skill_content = skill.skill_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.debug("Cannot read SKILL.md for %s (%s); falling back to description only", skill.name, exc)
+        skill_content = ""
+    # Cap the SKILL.md body so very large workflow docs don't blow the context.
+    max_chars = 6000
+    if len(skill_content) > max_chars:
+        skill_content = skill_content[:max_chars] + "\n…(truncated)"
+
+    user_prompt = (
+        f"Skill name: {skill.name}\n"
+        f"Short description: {skill.description}\n\n"
+        f"SKILL.md:\n-----\n{skill_content or '(SKILL.md unavailable; rely on the short description above.)'}\n-----\n\n"
+        "Return one JSON object that matches what this skill would actually produce on success."
+    )
+
+    try:
+        from deerflow.models import create_chat_model
+
+        # Reuse the curator/security-scan model setting; falls back to the main model when unset.
+        model_name = app_config.skill_evolution.curator.model_name if app_config.skill_evolution and app_config.skill_evolution.curator else None
+        model = create_chat_model(name=model_name, thinking_enabled=False, app_config=app_config)
+        response = await asyncio.wait_for(
+            model.ainvoke(
+                [
+                    {"role": "system", "content": _SKILL_SAMPLE_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                config={"run_name": "skill_display_sample"},
+            ),
+            timeout=45,
+        )
+        parsed = _extract_json_from_llm_output(str(getattr(response, "content", "") or ""))
+        if parsed:
+            return parsed
+        logger.warning("Skill display sample model returned non-JSON for %s; falling back to static mock", skill.name)
+    except asyncio.TimeoutError:
+        logger.warning("Skill display sample LLM call timed out for %s; falling back to static mock", skill.name)
+    except Exception:
+        logger.warning("Skill display sample LLM call failed for %s; falling back to static mock", skill.name, exc_info=True)
+    return _mock_skill_display_sample(skill.name)
+
+
+def _mock_skill_display_sample(skill_name: str) -> dict[str, Any]:
+    if skill_name == "knowledge-search-v2":
+        return {
+            "success": True,
+            "query": "latest news",
+            "count": 3,
+            "results": [
+                {
+                    "index": 1,
+                    "recUuid": "rec-001",
+                    "relevance_score": 0.982,
+                    "title": "Knowledge result one",
+                    "source_category": "knowledge/news",
+                    "source": "internal news library",
+                    "publish_time": "2026-05-25",
+                    "content_preview": "Mock result used to verify citation numbers, source cards, and recUuid template links.",
+                    "content_length": 1200,
+                },
+                {
+                    "index": 2,
+                    "recUuid": "rec-002",
+                    "relevance_score": 0.951,
+                    "title": "Knowledge result two",
+                    "source_category": "knowledge/news",
+                    "source": "internal news library",
+                    "publish_time": "2026-05-24",
+                    "content_preview": "Mock result used to verify citation ordering and detail preview.",
+                    "content_length": 980,
+                },
+                {
+                    "index": 3,
+                    "recUuid": "rec-003",
+                    "relevance_score": 0.921,
+                    "title": "Knowledge result three",
+                    "source_category": "knowledge/commentary",
+                    "source": "internal knowledge library",
+                    "publish_time": "2026-05-23",
+                    "content_preview": "Mock result used to verify list mode and custom display instruction previews.",
+                    "content_length": 760,
+                },
+            ],
+        }
+    return {
+        "success": True,
+        "query": "sample query",
+        "results": [
+            {
+                "id": "sample-001",
+                "title": "Sample result",
+                "summary": "Sample structured output used to infer field mapping.",
+                "source": "sample",
+                "updatedAt": "2026-05-25",
+            }
+        ],
+    }
+
+
 async def _build_ownership_index(skill_store: SkillStore, user_id: str) -> dict[str, dict[str, Any]]:
     """Index visible-to-user skill records by name. Internal call cache for list endpoints."""
     records = await skill_store.list_visible(user_id)
@@ -1423,12 +1602,13 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest, config: App
             logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
 
         extensions_config = get_extensions_config()
-        extensions_config.skills[skill_name] = SkillStateConfig(enabled=request.enabled)
+        current_skill_config = extensions_config.skills.get(skill_name)
+        extensions_config.skills[skill_name] = SkillStateConfig(
+            enabled=request.enabled,
+            display=current_skill_config.display if current_skill_config else None,
+        )
 
-        config_data = {
-            "mcpServers": {name: server.model_dump() for name, server in extensions_config.mcp_servers.items()},
-            "skills": {name: {"enabled": skill_config.enabled} for name, skill_config in extensions_config.skills.items()},
-        }
+        config_data = _dump_extensions_config(extensions_config)
 
         with open(config_path, "w", encoding="utf-8") as f:
             json.dump(config_data, f, indent=2)
@@ -1453,6 +1633,79 @@ async def update_skill(skill_name: str, request: SkillUpdateRequest, config: App
         raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
 
 
+@router.put(
+    "/skills/{skill_name}/display",
+    response_model=SkillResponse,
+    summary="Update Skill Display Adapter",
+    description="Update a skill's frontend display adapter in extensions_config.json.",
+)
+async def update_skill_display(
+    skill_name: str,
+    request: SkillDisplayUpdateRequest,
+    config: AppConfig = Depends(get_config),
+) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        config_path = ExtensionsConfig.resolve_config_path()
+        if config_path is None:
+            config_path = Path.cwd().parent / "extensions_config.json"
+            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
+
+        extensions_config = get_extensions_config()
+        current_skill_config = extensions_config.skills.get(skill_name)
+        extensions_config.skills[skill_name] = SkillStateConfig(
+            enabled=current_skill_config.enabled if current_skill_config else skill.enabled,
+            display=request.display,
+        )
+
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(_dump_extensions_config(extensions_config), f, indent=2, ensure_ascii=False)
+
+        reload_extensions_config()
+        await refresh_skills_system_prompt_cache_async()
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        updated_skill = next((s for s in skills if s.name == skill_name), None)
+        if updated_skill is None:
+            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after display update")
+        return _skill_to_response(updated_skill)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update display adapter for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update skill display adapter: {str(e)}")
+
+
+@router.post(
+    "/skills/{skill_name}/display-sample",
+    response_model=SkillDisplaySampleResponse,
+    summary="Get Skill Display Sample",
+    description="Return a structured sample response used by the frontend to infer display mapping.",
+)
+async def get_skill_display_sample(
+    skill_name: str,
+    config: AppConfig = Depends(get_config),
+) -> SkillDisplaySampleResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+        sample = await _generate_skill_display_sample(skill, config)
+        return SkillDisplaySampleResponse(skill_name=skill_name, sample=sample)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get display sample for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get display sample: {str(e)}")
+
+
 class SkillDetailRequest(BaseModel):
     """Request body for setting a skill's human-authored detail text."""
 
diff --git a/offline-backend-20260512/backend/app/gateway/services.py b/offline-backend-20260512/backend/app/gateway/services.py
index b5a9b452..15db1e62 100644
--- a/offline-backend-20260512/backend/app/gateway/services.py
+++ b/offline-backend-20260512/backend/app/gateway/services.py
@@ -152,8 +152,9 @@ _CONTEXT_CONFIGURABLE_KEYS: frozenset[str] = frozenset(
         "model_name",
         "mode",
         "thinking_enabled",
-        "reasoning_effort",
-        "writing_mode",
+        "reasoning_effort",
+        "rag_mode_enabled",
+        "writing_mode",
         "writing_artifact_path",
         "canvas_artifact_title",
         "canvas_artifact_type",
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
index 7f408e8b..330b6f76 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
@@ -281,9 +281,9 @@ def _build_middlewares(
     middlewares.append(TitleMiddleware(app_config=resolved_app_config))
 
     # Add MemoryMiddleware (after TitleMiddleware) — skip in bootstrap mode (agent creation flow)
-    memory_injection_enabled = cfg.get("memory_injection_enabled", True)
-    if not is_bootstrap:
-        middlewares.append(MemoryMiddleware(agent_name=agent_name, memory_config=resolved_app_config.memory, injection_enabled=memory_injection_enabled))
+    memory_injection_enabled = cfg.get("memory_injection_enabled", True)
+    if not is_bootstrap:
+        middlewares.append(MemoryMiddleware(agent_name=agent_name, memory_config=resolved_app_config.memory, injection_enabled=memory_injection_enabled))
 
     # Add ViewImageMiddleware only if the current model supports vision.
     # Use the resolved runtime model_name from make_lead_agent to avoid stale config values.
@@ -338,9 +338,10 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
     is_plan_mode = cfg.get("is_plan_mode", False)
     subagent_enabled = cfg.get("subagent_enabled", False)
     max_concurrent_subagents = cfg.get("max_concurrent_subagents", 3)
-    is_bootstrap = cfg.get("is_bootstrap", False)
-    memory_injection_enabled = bool(cfg.get("memory_injection_enabled", True))
-    writing_mode = bool(cfg.get("writing_mode", False))
+    is_bootstrap = cfg.get("is_bootstrap", False)
+    memory_injection_enabled = bool(cfg.get("memory_injection_enabled", True))
+    rag_mode_enabled = bool(cfg.get("rag_mode_enabled", False))
+    writing_mode = bool(cfg.get("writing_mode", False))
     writing_artifact_path = cfg.get("writing_artifact_path") if writing_mode else None
     if not isinstance(writing_artifact_path, str) or not writing_artifact_path.strip():
         writing_artifact_path = None
@@ -427,8 +428,9 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
                 available_skills=None,
                 is_bootstrap=True,
                 app_config=resolved_app_config,
-                memory_injection_enabled=memory_injection_enabled,
-            ),
+                memory_injection_enabled=memory_injection_enabled,
+                rag_mode_enabled=rag_mode_enabled,
+            ),
             state_schema=ThreadState,
         )
 
@@ -452,7 +454,8 @@ def _make_lead_agent(config: RunnableConfig, *, app_config: AppConfig):
             writing_artifact_path=writing_artifact_path,
             available_skills=(set(agent_config.skills or []) if agent_config else None),
             app_config=resolved_app_config,
-            memory_injection_enabled=memory_injection_enabled,
-        ),
+            memory_injection_enabled=memory_injection_enabled,
+            rag_mode_enabled=rag_mode_enabled,
+        ),
         state_schema=ThreadState,
     )
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py
index 9d2dbe3e..375a2919 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/prompt.py
@@ -665,20 +665,28 @@ def _get_memory_context(agent_name: str | None = None, *, app_config: AppConfig
 
 
 @lru_cache(maxsize=32)
-def _get_cached_skills_prompt_section(
-    skill_signature: tuple[tuple[str, str, str, str], ...],
-    available_skills_key: tuple[str, ...] | None,
-    container_base_path: str,
-    skill_evolution_section: str,
-) -> str:
-    filtered = [(name, description, category, location) for name, description, category, location in skill_signature if available_skills_key is None or name in available_skills_key]
-    skills_list = ""
-    if filtered:
-        skill_items = "\n".join(
-            f"    <skill>\n        <name>{name}</name>\n        <description>{description} {_skill_mutability_label(category)}</description>\n        <location>{location}</location>\n    </skill>"
-            for name, description, category, location in filtered
-        )
-        skills_list = f"<available_skills>\n{skill_items}\n</available_skills>"
+def _get_cached_skills_prompt_section(
+    skill_signature: tuple[tuple[str, str, str, str], ...],
+    display_signature: tuple[tuple[str, str, str], ...],
+    available_skills_key: tuple[str, ...] | None,
+    container_base_path: str,
+    skill_evolution_section: str,
+) -> str:
+    display_by_skill = {name: (mode, custom_instruction) for name, mode, custom_instruction in display_signature}
+    filtered = [(name, description, category, location) for name, description, category, location in skill_signature if available_skills_key is None or name in available_skills_key]
+    skills_list = ""
+    if filtered:
+        items = []
+        for name, description, category, location in filtered:
+            display_mode, custom_instruction = display_by_skill.get(name, ("", ""))
+            display_hint = ""
+            if display_mode:
+                display_hint = f"\n        <display mode=\"{display_mode}\">{custom_instruction}</display>"
+            items.append(
+                f"    <skill>\n        <name>{name}</name>\n        <description>{description} {_skill_mutability_label(category)}</description>\n        <location>{location}</location>{display_hint}\n    </skill>"
+            )
+        skill_items = "\n".join(items)
+        skills_list = f"<available_skills>\n{skill_items}\n</available_skills>"
 
     # Restricted mode: agent has an explicit skill allowlist.
     # We deliberately omit the "Skills are located at: <path>" hint and the
@@ -690,25 +698,44 @@ def _get_cached_skills_prompt_section(
 
     if is_restricted:
         scope_note = "\nYou have access ONLY to the skills listed below. Do NOT attempt to read, list, or invoke any skill that is not in this list, even if you remember other skill paths.\n"
-    else:
-        scope_note = ""
-
-    return f"""<skill_system>
-You have access to skills that provide optimized workflows for specific tasks. Each skill contains best practices, frameworks, and references to additional resources.
-{scope_note}
-**Progressive Loading Pattern:**
-1. When a user query matches a skill's use case, immediately call `read_file` on the skill's main file using the path attribute provided in the skill tag below
+    else:
+        scope_note = ""
+
+    display_pattern = (
+        """
+**Skill Result Display Pattern:**
+- If a skill has `<display mode="citation">`, use the skill's returned result order as reference numbers. Cite facts from the first result as `[[1]]`, the second as `[[2]]`, and so on. Use only numbers that correspond to returned results.
+- If a skill has `<display mode="list">`, summarize the returned items as a concise list and keep item order stable.
+- If a skill has `<display mode="table">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="table" />` where the frontend should render the real table. Do not hand-write the table rows yourself.
+- If a skill has `<display mode="card">`, summarize the result and output `<skill-display tool="SKILL_OR_TOOL_NAME" mode="card" />` where the frontend should render the cards.
+- If a skill has `<display mode="custom">`, follow the custom display instruction in the `<display>` tag when presenting the skill result.
+"""
+        if display_signature
+        else ""
+    )
+
+    return f"""<skill_system>
+You have access to skills that provide optimized workflows for specific tasks. Each skill contains best practices, frameworks, and references to additional resources.
+{scope_note}
+**Progressive Loading Pattern:**
+1. When a user query matches a skill's use case, immediately call `read_file` on the skill's main file using the path attribute provided in the skill tag below
 2. Read and understand the skill's workflow and instructions
-3. The skill file contains references to external resources under the same folder
-4. Load referenced resources only when needed during execution
-5. Follow the skill's instructions precisely
-{location_hint}{evolution_block}
-{skills_list}
-
-</skill_system>"""
-
-
-def get_skills_prompt_section(available_skills: set[str] | None = None, *, app_config: AppConfig | None = None) -> str:
+3. The skill file contains references to external resources under the same folder
+4. Load referenced resources only when needed during execution
+5. Follow the skill's instructions precisely
+{display_pattern}
+{location_hint}{evolution_block}
+{skills_list}
+
+</skill_system>"""
+
+
+def get_skills_prompt_section(
+    available_skills: set[str] | None = None,
+    *,
+    app_config: AppConfig | None = None,
+    display_enabled: bool = False,
+) -> str:
     """Generate the skills prompt section with available skills list."""
     skills = _get_enabled_skills_for_config(app_config)
 
@@ -738,12 +765,31 @@ def get_skills_prompt_section(available_skills: set[str] | None = None, *, app_c
     if available_skills is not None and not any(skill.name in available_skills for skill in skills):
         return ""
 
-    skill_signature = tuple((skill.name, skill.description, skill.category, skill.get_container_file_path(container_base_path)) for skill in skills)
-    available_key = tuple(sorted(available_skills)) if available_skills is not None else None
-    if not skill_signature and available_key is not None:
-        return ""
-    skill_evolution_section = _build_skill_evolution_section(effective_skill_evolution_enabled)
-    return _get_cached_skills_prompt_section(skill_signature, available_key, container_base_path, skill_evolution_section)
+    skill_signature = tuple((skill.name, skill.description, skill.category, skill.get_container_file_path(container_base_path)) for skill in skills)
+    display_signature: tuple[tuple[str, str, str], ...] = ()
+    if display_enabled:
+        try:
+            from deerflow.config.extensions_config import get_extensions_config
+
+            extensions = get_extensions_config()
+            display_signature = tuple(
+                (
+                    name,
+                    skill_config.display.mode,
+                    skill_config.display.custom_instruction,
+                )
+                for name, skill_config in sorted(extensions.skills.items())
+                if skill_config.display is not None
+                and skill_config.display.enabled
+                and skill_config.display.mode != "none"
+            )
+        except Exception:
+            logger.debug("Failed to load skill display configs for prompt injection", exc_info=True)
+    available_key = tuple(sorted(available_skills)) if available_skills is not None else None
+    if not skill_signature and available_key is not None:
+        return ""
+    skill_evolution_section = _build_skill_evolution_section(effective_skill_evolution_enabled)
+    return _get_cached_skills_prompt_section(skill_signature, display_signature, available_key, container_base_path, skill_evolution_section)
 
 
 def get_agent_soul(agent_id: str | None) -> str:
@@ -866,9 +912,10 @@ def apply_prompt_template(
     writing_artifact_path: str | None = None,
     available_skills: set[str] | None = None,
     is_bootstrap: bool = False,
-    app_config: AppConfig | None = None,
-    memory_injection_enabled: bool = True,
-) -> str:
+    app_config: AppConfig | None = None,
+    memory_injection_enabled: bool = True,
+    rag_mode_enabled: bool = False,
+) -> str:
     storage_agent_id = agent_id if agent_id is not None else agent_name
 
     # Get memory context
@@ -896,11 +943,15 @@ def apply_prompt_template(
         else ""
     )
 
-    # Bootstrap section: skill-matching guidance (only in agent creation flow)
+    # Bootstrap section: skill-matching guidance (only in agent creation flow)
     bootstrap_section = _build_bootstrap_section() if is_bootstrap else ""
 
     # Get skills section
-    skills_section = get_skills_prompt_section(available_skills, app_config=app_config)
+    skills_section = get_skills_prompt_section(
+        available_skills,
+        app_config=app_config,
+        display_enabled=rag_mode_enabled,
+    )
 
     # Get deferred tools section (tool_search)
     deferred_tools_section = get_deferred_tools_prompt_section(app_config=app_config)
@@ -937,7 +988,22 @@ Writing mode is enabled for this run.
     acp_and_mounts_section = "\n".join(section for section in (acp_section, custom_mounts_section) if section)
 
     # Build the offline-network policy block (empty unless DEER_FLOW_OFFLINE_MODE is set).
-    network_policy_section = _build_network_policy_section()
+    network_policy_section = _build_network_policy_section()
+    rag_mode_section = (
+        """
+<rag_citation_mode>
+RAG/reference display mode is enabled.
+When a search, knowledge, skill, or MCP tool returns a result list:
+- If the skill has a display adapter, follow that adapter first.
+- For `citation`, cite returned items with `[[1]]`, `[[2]]`, etc. Only cite real returned items.
+- For `table`, do not hand-write the table. Summarize and place `<skill-display tool="SKILL_OR_TOOL_NAME" mode="table" />` where the table should appear. The frontend will render the real tool result as a stable table.
+- For `list` or `card`, summarize and place `<skill-display tool="SKILL_OR_TOOL_NAME" mode="list" />` or `<skill-display tool="SKILL_OR_TOOL_NAME" mode="card" />` where the structured result should appear.
+- If no display adapter exists, default to citation mode with numbered citations.
+</rag_citation_mode>
+"""
+        if rag_mode_enabled
+        else ""
+    )
 
     # Format the prompt with dynamic skills and memory
     prompt = SYSTEM_PROMPT_TEMPLATE.format(
@@ -955,4 +1021,4 @@ Writing mode is enabled for this run.
         acp_section=acp_and_mounts_section,
     )
 
-    return prompt + f"\n<current_date>{datetime.now().strftime('%Y-%m-%d, %A')}</current_date>"
+    return prompt + rag_mode_section + f"\n<current_date>{datetime.now().strftime('%Y-%m-%d, %A')}</current_date>"
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/client.py b/offline-backend-20260512/backend/packages/harness/deerflow/client.py
index 609d7f40..c970eb29 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/client.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/client.py
@@ -840,10 +840,13 @@ class DeerFlowClient:
 
         current_config = get_extensions_config()
 
-        config_data = {
-            "mcpServers": mcp_servers,
-            "skills": {name: {"enabled": skill.enabled} for name, skill in current_config.skills.items()},
-        }
+        config_data = {
+            "mcpServers": mcp_servers,
+            "skills": {
+                name: skill.model_dump(by_alias=True, exclude_none=True)
+                for name, skill in current_config.skills.items()
+            },
+        }
 
         self._atomic_write_json(config_path, config_data)
 
@@ -903,13 +906,20 @@ class DeerFlowClient:
         if config_path is None:
             raise FileNotFoundError("Cannot locate extensions_config.json. Set DEER_FLOW_EXTENSIONS_CONFIG_PATH or ensure it exists in the project root.")
 
-        extensions_config = get_extensions_config()
-        extensions_config.skills[name] = SkillStateConfig(enabled=enabled)
-
-        config_data = {
-            "mcpServers": {n: s.model_dump() for n, s in extensions_config.mcp_servers.items()},
-            "skills": {n: {"enabled": sc.enabled} for n, sc in extensions_config.skills.items()},
-        }
+        extensions_config = get_extensions_config()
+        current_skill_config = extensions_config.skills.get(name)
+        extensions_config.skills[name] = SkillStateConfig(
+            enabled=enabled,
+            display=current_skill_config.display if current_skill_config else None,
+        )
+
+        config_data = {
+            "mcpServers": {n: s.model_dump(by_alias=True) for n, s in extensions_config.mcp_servers.items()},
+            "skills": {
+                n: sc.model_dump(by_alias=True, exclude_none=True)
+                for n, sc in extensions_config.skills.items()
+            },
+        }
 
         self._atomic_write_json(config_path, config_data)
 
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/extensions_config.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/extensions_config.py
index 6492a4f4..15439aac 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/extensions_config.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/extensions_config.py
@@ -3,7 +3,7 @@
 import json
 import os
 from pathlib import Path
-from typing import Any, Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -53,10 +53,63 @@ class McpServerConfig(BaseModel):
     model_config = ConfigDict(extra="allow", populate_by_name=True)
 
 
-class SkillStateConfig(BaseModel):
-    """Configuration for a single skill's state."""
-
-    enabled: bool = Field(default=True, description="Whether this skill is enabled")
+class SkillDisplayTableColumn(BaseModel):
+    """A configured table column for structured skill result display."""
+
+    label: str = Field(description="Column label shown in the frontend table")
+    field: str = Field(description="Field name or dot path read from each result item")
+    width: str | None = Field(default=None, description="Optional CSS width for this column")
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class SkillDisplayConfig(BaseModel):
+    """Frontend display adapter for structured skill results."""
+
+    enabled: bool = Field(default=False, description="Whether result display adaptation is enabled")
+    mode: Literal["citation", "list", "table", "card", "custom", "none"] = Field(
+        default="none",
+        description="How the frontend should render this skill's structured results",
+    )
+    result_path: str = Field(default="results", description="Dot path to the array of result items", alias="resultPath")
+    title_field: str | None = Field(default=None, description="Field used as item title", alias="titleField")
+    summary_field: str | None = Field(default=None, description="Field used as short summary/snippet", alias="summaryField")
+    content_field: str | None = Field(default=None, description="Field used as full item content", alias="contentField")
+    source_field: str | None = Field(default=None, description="Field used as source label", alias="sourceField")
+    type_field: str | None = Field(default=None, description="Field used as source/type badge", alias="typeField")
+    time_field: str | None = Field(default=None, description="Field used as publication/update time", alias="timeField")
+    score_field: str | None = Field(default=None, description="Field used as relevance score", alias="scoreField")
+    url_field: str | None = Field(default=None, description="Field containing a direct URL", alias="urlField")
+    id_field: str | None = Field(default=None, description="Field containing an ID for template URLs", alias="idField")
+    link_strategy: Literal["auto", "url", "id"] = Field(
+        default="auto",
+        description="Whether links use a URL field, an ID template, or automatic fallback",
+        alias="linkStrategy",
+    )
+    link_template: str | None = Field(default=None, description="Template used when linkStrategy is id", alias="linkTemplate")
+    citation_token: Literal["doubleBracket", "singleBracket"] = Field(
+        default="doubleBracket",
+        description="Citation token style expected in model output",
+        alias="citationToken",
+    )
+    max_items: int = Field(default=8, ge=1, le=100, description="Maximum displayed items", alias="maxItems")
+    custom_instruction: str = Field(
+        default="",
+        description="User-authored instruction for custom rendering schema generation",
+        alias="customInstruction",
+    )
+    table_columns: list[SkillDisplayTableColumn] = Field(
+        default_factory=list,
+        description="Columns used when mode is table",
+        alias="tableColumns",
+    )
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+class SkillStateConfig(BaseModel):
+    """Configuration for a single skill's state."""
+
+    enabled: bool = Field(default=True, description="Whether this skill is enabled")
+    display: SkillDisplayConfig | None = Field(default=None, description="Optional frontend display adapter")
 
 
 class ExtensionsConfig(BaseModel):

From b7aa8b06caa51873e4b2aecb03fa6349a7e94177 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Mon, 25 May 2026 19:47:55 +0800
Subject: [PATCH 03/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E3=80=8C=E6=96=B0?=
 =?UTF-8?q?=E5=AF=B9=E8=AF=9D=E3=80=8D=E6=B5=81=E5=BC=8F=E4=B8=AD=E6=97=A0?=
 =?UTF-8?q?=E6=B3=95=E9=87=8D=E7=BD=AE=20+=20=E5=8F=82=E8=80=83=E6=96=87?=
 =?UTF-8?q?=E7=8C=AE=E5=BC=80=E5=85=B3=E9=BB=98=E8=AE=A4=E5=85=B3=E9=97=AD?=
 =?UTF-8?q?=E5=B9=B6=E5=8A=A0=E5=AF=B9=E5=8B=BE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 流式回答过程中点「新对话」:URL 同路径导致 react-router navigate 静默 no-op,
  下游 hook 收不到事件;改为显式 navigate(..., {replace:true, state:{resetAt}})
  保证每次点击刷新 location.key,并让 useThreadChat 监听 location.key 触发重置
- useThreadStream 在 threadId 变化时 stop() 掉上一条 SSE,避免旧流继续派发事件
- 引入 KeyedChatPage 用 location.key 作 ChatRuntime key,真正的导航触发整树 remount,
  解决 useStream 内部 stream.values 残留导致欢迎页底下还能看到旧消息的过渡帧问题
- 「参考文献」开关默认关闭(local.ts),开启态在文字前额外多一个 ✓ 对勾
---
 .../workspace/chats/use-thread-chat.ts        |  9 ++-
 .../src/components/workspace/input-box.tsx    | 77 ++++++++++---------
 .../workspace/workspace-nav-chat-list.tsx     | 18 ++++-
 frontend-web/src/core/settings/local.ts       | 22 +++---
 frontend-web/src/core/threads/hooks.ts        | 36 ++++++---
 frontend-web/src/pages/WorkspaceRoutes.tsx    | 20 ++++-
 6 files changed, 120 insertions(+), 62 deletions(-)

diff --git a/frontend-web/src/components/workspace/chats/use-thread-chat.ts b/frontend-web/src/components/workspace/chats/use-thread-chat.ts
index 54145f96..9bfaada8 100644
--- a/frontend-web/src/components/workspace/chats/use-thread-chat.ts
+++ b/frontend-web/src/components/workspace/chats/use-thread-chat.ts
@@ -2,12 +2,19 @@
 
 import { useParams, usePathname, useSearchParams } from "next/navigation";
 import { useEffect, useState } from "react";
+import { useLocation } from "react-router-dom";
 
 import { uuid } from "@/core/utils/uuid";
 
 export function useThreadChat() {
   const { thread_id: threadIdFromPath } = useParams<{ thread_id: string }>();
   const pathname = usePathname();
+  // ``location.key`` is regenerated on every react-router navigation, even when
+  // the resolved pathname is identical. We depend on it so that clicking
+  // "新对话" while already at /chats/new still triggers a fresh thread reset
+  // (otherwise navigate-to-same-path is silently a no-op and the in-flight
+  // conversation would persist on screen).
+  const locationKey = useLocation().key;
 
   const searchParams = useSearchParams();
   const [threadId, setThreadId] = useState(() => {
@@ -37,7 +44,7 @@ export function useThreadChat() {
     }
     setIsNewThread(false);
     setThreadId(threadIdFromPath);
-  }, [pathname, threadIdFromPath]);
+  }, [pathname, threadIdFromPath, locationKey]);
   const isMock = searchParams.get("mock") === "true";
   return { threadId, setThreadId, isNewThread, setIsNewThread, isMock };
 }
diff --git a/frontend-web/src/components/workspace/input-box.tsx b/frontend-web/src/components/workspace/input-box.tsx
index 43640eeb..f1e54ee5 100644
--- a/frontend-web/src/components/workspace/input-box.tsx
+++ b/frontend-web/src/components/workspace/input-box.tsx
@@ -2,9 +2,9 @@
 
 import type { ChatStatus } from "ai";
 import {
-  BrainCircuitIcon,
-  BookMarkedIcon,
-  CheckIcon,
+  BrainCircuitIcon,
+  BookMarkedIcon,
+  CheckIcon,
   FileTextIcon,
   GraduationCapIcon,
   LightbulbIcon,
@@ -85,8 +85,8 @@ import {
   DropdownMenuTrigger,
 } from "../ui/dropdown-menu";
 
-import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
-import { useLocalSettings } from "@/core/settings";
+import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
+import { useLocalSettings } from "@/core/settings";
 
 
 import { useThread } from "./messages/context";
@@ -177,8 +177,8 @@ export function InputBox({
     onAgentChange: (agentId: string | null) => void;
   };
 }) {
-  const { t } = useI18n();
-  const [localSettings, setLocalSettings] = useLocalSettings();
+  const { t } = useI18n();
+  const [localSettings, setLocalSettings] = useLocalSettings();
   const searchParams = useSearchParams();
   const [modelDialogOpen, setModelDialogOpen] = useState(false);
   const { models } = useModels();
@@ -291,18 +291,18 @@ export function InputBox({
     });
   }, [context, onContextChange]);
 
-  const memoryInjectionEnabled = context.memory_injection_enabled ?? true;
+  const memoryInjectionEnabled = context.memory_injection_enabled ?? true;
   const handleMemoryInjectionToggle = useCallback(() => {
     onContextChange?.({
       ...context,
       memory_injection_enabled: !memoryInjectionEnabled,
     });
-  }, [context, memoryInjectionEnabled, onContextChange]);
-
-  const ragModeEnabled = localSettings.display.ragModeEnabled;
-  const handleRagModeToggle = useCallback(() => {
-    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
-  }, [ragModeEnabled, setLocalSettings]);
+  }, [context, memoryInjectionEnabled, onContextChange]);
+
+  const ragModeEnabled = localSettings.display.ragModeEnabled;
+  const handleRagModeToggle = useCallback(() => {
+    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
+  }, [ragModeEnabled, setLocalSettings]);
 
   const handleSubmit = useCallback(
     async (message: PromptInputMessage) => {
@@ -628,28 +628,33 @@ export function InputBox({
                 <BrainCircuitIcon className="size-3" />
                 <span className="text-xs font-normal">记忆</span>
               </PromptInputButton>
-            </Tooltip>
-            <Tooltip
-              content={
-                ragModeEnabled
-                  ? "参考文献模式已开启：检索类结果会按编号引用展示"
-                  : "参考文献模式已关闭：技能配置的引用展示不会生效"
-              }
-            >
-              <PromptInputButton
-                className={cn(
-                  "gap-1.5! rounded-full px-3! shadow-none",
-                  ragModeEnabled
-                    ? "border border-emerald-300 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
-                    : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
-                )}
-                onClick={handleRagModeToggle}
-              >
-                <BookMarkedIcon className="size-3" />
-                <span className="text-xs font-normal">参考文献</span>
-              </PromptInputButton>
-            </Tooltip>
-            <PromptInputActionMenu>
+            </Tooltip>
+            <Tooltip
+              content={
+                ragModeEnabled
+                  ? "参考文献模式已开启：检索类结果会按编号引用展示"
+                  : "参考文献模式已关闭：点击开启"
+              }
+            >
+              <PromptInputButton
+                type="button"
+                aria-pressed={ragModeEnabled}
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  ragModeEnabled
+                    ? "border border-emerald-300 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
+                    : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
+                )}
+                onClick={handleRagModeToggle}
+              >
+                {ragModeEnabled && (
+                  <CheckIcon className="size-3 text-emerald-700 dark:text-emerald-200" />
+                )}
+                <BookMarkedIcon className="size-3" />
+                <span className="text-xs font-normal">参考文献</span>
+              </PromptInputButton>
+            </Tooltip>
+            <PromptInputActionMenu>
               <ModeHoverGuide
                 mode={
                   context.mode === "flash" ||
diff --git a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
index 99f69bf8..c4d9c969 100644
--- a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
@@ -4,6 +4,7 @@
 
 import Link from "next/link";
 import { usePathname } from "next/navigation";
+import { useNavigate } from "react-router-dom";
 
 import {
   SidebarGroup,
@@ -37,6 +38,21 @@ export function WorkspaceNavChatList({
 }) {
   const { t } = useI18n();
   const pathname = usePathname();
+  const navigate = useNavigate();
+  // 「新对话」点击时,如果已经在 /chats/new 路径,直接 navigate 会被 react-router
+  // 当成同路径 no-op,不更新 location.key,挂在 location.key 上的下游 hook
+  // (useThreadChat)就感知不到「用户想重开一个对话」,UI 不刷新。
+  // 这里显式拦截:同路径时用 replace + 强制生成新 location.key 的方式重置。
+  const handleNewChatClick = (event: React.MouseEvent<HTMLAnchorElement>) => {
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.button === 1) {
+      return;
+    }
+    event.preventDefault();
+    navigate("/page/workspace/chats/new", {
+      replace: true,
+      state: { resetAt: Date.now() },
+    });
+  };
   return (
     <SidebarGroup className={cn("px-2", showCollapseTrigger ? "pt-3" : "pt-2")}>
       <SidebarMenu className="gap-1">
@@ -47,7 +63,7 @@ export function WorkspaceNavChatList({
               asChild
               className={cn(NEW_CHAT_CLASS, showCollapseTrigger && "min-w-0 flex-1")}
             >
-              <Link href="/page/workspace/chats/new">
+              <Link href="/page/workspace/chats/new" onClick={handleNewChatClick}>
                 <MessageSquarePlus />
                 <span>{t.sidebar.newChat}</span>
               </Link>
diff --git a/frontend-web/src/core/settings/local.ts b/frontend-web/src/core/settings/local.ts
index 8e5166ab..36c19ffc 100644
--- a/frontend-web/src/core/settings/local.ts
+++ b/frontend-web/src/core/settings/local.ts
@@ -4,10 +4,10 @@ export const DEFAULT_LOCAL_SETTINGS: LocalSettings = {
   notification: {
     enabled: true,
   },
-  display: {
-    streamSpeedMeterEnabled: true,
-    ragModeEnabled: true,
-  },
+  display: {
+    streamSpeedMeterEnabled: true,
+    ragModeEnabled: false,
+  },
   context: {
     model_name: undefined,
     mode: undefined,
@@ -33,13 +33,13 @@ export interface LocalSettings {
      * AI reply is in flight. Default on; controlled by the user from
      * the appearance settings page.
      */
-    streamSpeedMeterEnabled: boolean;
-    /**
-     * Global switch for skill result display adapters. When disabled, chat
-     * messages render tool results with the legacy generic search UI only.
-     */
-    ragModeEnabled: boolean;
-  };
+    streamSpeedMeterEnabled: boolean;
+    /**
+     * Global switch for skill result display adapters. When disabled, chat
+     * messages render tool results with the legacy generic search UI only.
+     */
+    ragModeEnabled: boolean;
+  };
   context: Omit<
     AgentThreadContext,
     | "thread_id"
diff --git a/frontend-web/src/core/threads/hooks.ts b/frontend-web/src/core/threads/hooks.ts
index ecb8a5d8..568b204e 100644
--- a/frontend-web/src/core/threads/hooks.ts
+++ b/frontend-web/src/core/threads/hooks.ts
@@ -12,8 +12,8 @@ import { apiFetch } from "../api";
 import { getBackendBaseURL } from "../config";
 import { useI18n } from "../i18n/hooks";
 import type { FileInMessage } from "../messages/utils";
-import type { LocalSettings } from "../settings";
-import { useLocalSettings } from "../settings";
+import type { LocalSettings } from "../settings";
+import { useLocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
 import type { UploadedFileInfo } from "../uploads";
 import { promptInputFilePartToFile, uploadFiles } from "../uploads";
@@ -146,8 +146,8 @@ export function useThreadStream({
   onFinish,
   onToolEnd,
 }: ThreadStreamOptions) {
-  const { t } = useI18n();
-  const [localSettings] = useLocalSettings();
+  const { t } = useI18n();
+  const [localSettings] = useLocalSettings();
   // Track the thread ID that is currently streaming to handle thread changes during streaming
   const [onStreamThreadId, setOnStreamThreadId] = useState(() => threadId);
   // Ref to track current thread ID across async callbacks without causing re-renders,
@@ -309,9 +309,27 @@ export function useThreadStream({
   // Track message count before sending so we know when server has responded
   const prevMsgCountRef = useRef(thread.messages.length);
 
+  // Keep a ref to the latest `thread` so the threadId-change effect can stop
+  // an in-flight stream without re-running on every render that produces a
+  // new `thread` identity.
+  const threadStreamRef = useRef(thread);
+  threadStreamRef.current = thread;
+
   // Reset thread-local pending UI state when switching between threads so
   // optimistic messages and in-flight guards do not leak across chat views.
+  // Also abort any in-flight SSE from the previous thread: without this,
+  // clicking "新对话" mid-stream leaves the old run firing onUpdate events
+  // against the now-detached thread context, which manifests as the page
+  // appearing unresponsive to the navigation.
   useEffect(() => {
+    const prevThread = threadStreamRef.current;
+    if (prevThread?.isLoading) {
+      try {
+        prevThread.stop();
+      } catch {
+        // best-effort; nothing useful to do if the SDK fails to abort
+      }
+    }
     startedRef.current = false;
     sendInFlightRef.current = false;
     prevMsgCountRef.current = 0;
@@ -508,9 +526,9 @@ export function useThreadStream({
                     : context.mode === "thinking"
                       ? "low"
                       : undefined),
-              memory_injection_enabled: context.memory_injection_enabled ?? true,
-              rag_mode_enabled: localSettings.display.ragModeEnabled,
-              thread_id: threadId,
+              memory_injection_enabled: context.memory_injection_enabled ?? true,
+              rag_mode_enabled: localSettings.display.ragModeEnabled,
+              thread_id: threadId,
             },
           },
         );
@@ -523,8 +541,8 @@ export function useThreadStream({
         sendInFlightRef.current = false;
       }
     },
-    [thread, _handleOnStart, t.uploads.uploadingFiles, context, localSettings.display.ragModeEnabled, queryClient],
-  );
+    [thread, _handleOnStart, t.uploads.uploadingFiles, context, localSettings.display.ragModeEnabled, queryClient],
+  );
 
   // Merge thread with optimistic messages for display
   const mergedThread =
diff --git a/frontend-web/src/pages/WorkspaceRoutes.tsx b/frontend-web/src/pages/WorkspaceRoutes.tsx
index a721f0da..4f7b4cbb 100644
--- a/frontend-web/src/pages/WorkspaceRoutes.tsx
+++ b/frontend-web/src/pages/WorkspaceRoutes.tsx
@@ -1,5 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
-import { Navigate, Route, Routes } from "react-router-dom";
+import { Navigate, Route, Routes, useLocation } from "react-router-dom";
 
 import { getStoredAuth } from "@/core/auth";
 
@@ -87,6 +87,20 @@ export function ChatRuntime({ children }: { children: ReactNode }) {
   );
 }
 
+/**
+ * 让 ChatPage 在每次真正的 react-router navigation 上完整 remount。
+ *
+ * 背景:点「新对话」时即使路径不变,我们也会用 `navigate(..., { replace: true,
+ * state: { resetAt } })` 强制刷新 location.key —— 用它作 key 能保证 useStream、
+ * useThreadStream、optimistic state、refs 一次性全部丢弃,避免上一条流的
+ * `stream.values` 残留把欢迎页底下的旧消息拖出来(SDK 的 stream.clear() 需要
+ * 多次 effect tick 才会清干净,中间过渡帧用户能看见)。
+ */
+function KeyedChatPage({ render }: { render: () => ReactNode }) {
+  const key = useLocation().key;
+  return <ChatRuntime key={key}>{render()}</ChatRuntime>;
+}
+
 export default function WorkspaceRoutes({
   pageSidebarCollapsed = false,
   pageSidebarHidden = false,
@@ -121,9 +135,7 @@ export default function WorkspaceRoutes({
         path="chats/:thread_id"
         element={
           <WorkspaceLayout {...layoutProps}>
-            <ChatRuntime>
-              <ChatPage />
-            </ChatRuntime>
+            <KeyedChatPage render={() => <ChatPage />} />
           </WorkspaceLayout>
         }
       />

From ad5d55220ca5ba1a3350036ea74edf878e04aa80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Mon, 25 May 2026 23:16:51 +0800
Subject: [PATCH 04/15] =?UTF-8?q?=E6=8A=80=E8=83=BD=E5=B1=95=E7=A4=BA?=
 =?UTF-8?q?=E9=80=82=E9=85=8D=E6=8C=81=E4=B9=85=E5=8C=96=20+=20=E5=8F=82?=
 =?UTF-8?q?=E8=80=83=E6=96=87=E7=8C=AE=E6=94=B6=E9=9B=86=E4=B8=8E=E6=96=B0?=
 =?UTF-8?q?=E5=AF=B9=E8=AF=9D=E6=B5=81=E5=BC=8F=E4=BF=AE=E5=A4=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 后端新增 skill_display_adapters 表，持久化每个技能的 display 配置与 sample
  payload；/api/skills 列表、详情、设置接口同步读写
- 新增 /api/skills/{name}/display-sample 端点，编辑器优先加载库中样例
- 前端展示适配面板改为从后端加载持久样例，无样例时提示"自动识别"
- 参考文献收集修复：仅在 bash/shell/python 等执行类工具上从参数推断技能
  名，避免 read_file / web_fetch 误匹配；引用列表纳入最新一条助手消息
- ChatBox 改用「最新 human → 最新 ai」窗口收集引用，并仅保留 citation
  模式
- 修复「新对话」点击后已发消息消失：useThreadStream 只在 threadId 切回
  空值时重置/中止 SSE，避免 onCreated 分配 id 时把刚开始的流打断；
  ChatPage 在 landing 状态隐藏 MessageList，移除 KeyedChatPage remount
- 技能详情对话框：所有者可查看源码与文件 tab（不再要求管理员）
- LocalSandbox：Windows PowerShell 5 路径下把 && 重写为 ;，并以
  UTF-8 解码 subprocess 输出，避免中文乱码
- knowledge-search-v2 mock 样例改为中文固定测试数据

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/workspace/chats/chat-box.tsx   |   46 +-
 .../workspace/messages/message-group.tsx      |   31 +-
 .../workspace/messages/message-list.tsx       |    1 +
 .../workspace/skill-display-adapter-panel.tsx |   91 +-
 .../workspace/skills/skill-detail-dialog.tsx  |   48 +-
 .../src/core/skill-display/display-adapter.ts |   71 +-
 .../src/core/skill-display/runtime.ts         |  264 +-
 frontend-web/src/core/skills/api.ts           |   20 +-
 frontend-web/src/core/skills/hooks.ts         |    4 +-
 frontend-web/src/core/skills/type.ts          |    1 +
 frontend-web/src/core/threads/hooks.ts        |   22 +-
 frontend-web/src/pages/ChatPage.tsx           |   27 +-
 frontend-web/src/pages/WorkspaceRoutes.tsx    |   20 +-
 .../backend/app/gateway/routers/skills.py     | 4120 +++++++++--------
 .../deerflow/persistence/models/__init__.py   |    3 +-
 .../deerflow/persistence/skills/model.py      |   13 +
 .../deerflow/sandbox/local/local_sandbox.py   |   75 +-
 17 files changed, 2723 insertions(+), 2134 deletions(-)

diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index ce37986a..23ae1bb8 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -61,10 +61,14 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
     [settings.display.ragModeEnabled, skills],
   );
-  const latestAssistant = useMemo(
-    () => findLatestAssistantMessage(thread.values.messages ?? []),
+  const latestHumanIndex = useMemo(
+    () => findLatestHumanMessageIndex(thread.values.messages ?? []),
     [thread.values.messages],
   );
+  const latestAssistant = useMemo(
+    () => findLatestAssistantMessageAfter(thread.values.messages ?? [], latestHumanIndex),
+    [latestHumanIndex, thread.values.messages],
+  );
   const displaySources = useMemo(() => {
     if (!settings.display.ragModeEnabled) {
       return [];
@@ -74,10 +78,12 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
       return [];
     }
     return collectRuntimeDisplaySources(messages, skillDisplayMap, {
-      afterMessageId: findPreviousHumanMessageId(messages, latestAssistant.id),
+      afterMessageId: latestHumanIndex >= 0 ? messages[latestHumanIndex]?.id : undefined,
       beforeMessageId: latestAssistant.id,
+      includeBeforeMessage: true,
+      includeModes: ["citation"],
     });
-  }, [settings.display.ragModeEnabled, skillDisplayMap, latestAssistant?.id, thread.values.messages]);
+  }, [settings.display.ragModeEnabled, skillDisplayMap, latestAssistant?.id, latestHumanIndex, thread.values.messages]);
   const referenceSources = useMemo(
     () => displaySources.filter((source) => source.mode === "citation"),
     [displaySources],
@@ -318,8 +324,20 @@ function ReferencePanel({
   );
 }
 
-function findLatestAssistantMessage(messages: Message[]) {
+function findLatestHumanMessageIndex(messages: Message[]) {
   for (let index = messages.length - 1; index >= 0; index--) {
+    if (messages[index]?.type === "human") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function findLatestAssistantMessageAfter(messages: Message[], afterIndex: number) {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    if (afterIndex >= 0 && index <= afterIndex) {
+      return null;
+    }
     const message = messages[index];
     if (message?.type === "ai") {
       return message;
@@ -328,22 +346,4 @@ function findLatestAssistantMessage(messages: Message[]) {
   return null;
 }
 
-function findPreviousHumanMessageId(
-  messages: Message[],
-  beforeMessageId?: string,
-): string | undefined {
-  const beforeIndex =
-    beforeMessageId === undefined
-      ? messages.length
-      : messages.findIndex((message) => message.id === beforeMessageId);
-  const end = beforeIndex < 0 ? messages.length : beforeIndex;
-  for (let index = end - 1; index >= 0; index--) {
-    const message = messages[index];
-    if (message?.type === "human") {
-      return message.id;
-    }
-  }
-  return undefined;
-}
-
 export { ChatBox };
diff --git a/frontend-web/src/components/workspace/messages/message-group.tsx b/frontend-web/src/components/workspace/messages/message-group.tsx
index f5e5b635..aabf5bc8 100644
--- a/frontend-web/src/components/workspace/messages/message-group.tsx
+++ b/frontend-web/src/components/workspace/messages/message-group.tsx
@@ -50,11 +50,14 @@ import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
 import { useLocalSettings } from "@/core/settings";
 import { useSkills } from "@/core/skills/hooks";
 import {
-  buildSkillDisplayMap,
-  findDisplayConfigForTool,
-  normalizeDefaultDisplaySources,
-  type RuntimeDisplaySource,
-} from "@/core/skill-display/runtime";
+  buildSkillDisplayMap,
+  findDisplayConfigForPayload,
+  findDisplayConfigForTool,
+  isDisplaySamplePayload,
+  normalizeDefaultDisplaySources,
+  shouldUseDefaultCitationMode,
+  type RuntimeDisplaySource,
+} from "@/core/skill-display/runtime";
 import { normalizeDisplaySources } from "@/core/skill-display/display-adapter";
 import { extractTitleFromMarkdown } from "@/core/utils/markdown";
 import { env } from "@/env";
@@ -249,7 +252,13 @@ function ToolCall({
   const { t } = useI18n();
   const artifacts = useArtifactsOptional();
 
-  const displayMatch = findDisplayConfigForTool(name, skillDisplayMap, args);
+  const displayMatch =
+    result !== undefined && isDisplaySamplePayload(result)
+      ? null
+      : (findDisplayConfigForTool(name, skillDisplayMap, args) ??
+        (result !== undefined
+          ? findDisplayConfigForPayload(name, result, skillDisplayMap)
+          : null));
   const displayItems =
     displayMatch && result !== undefined
       ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({
@@ -263,7 +272,11 @@ function ToolCall({
     return (
       <ChainOfThoughtStep
         key={id}
-        label={displayMatch?.display.mode === "citation" || !displayMatch ? "检索参考来源" : `获取${displayItems.length}条结果`}
+        label={
+          displayMatch?.display.mode === "citation" || !displayMatch
+            ? "检索参考来源"
+            : `获取 ${displayItems.length} 条结果`
+        }
         icon={SearchIcon}
       >
         <DisplayResultsList results={displayItems} />
@@ -272,7 +285,7 @@ function ToolCall({
   }
 
   const searchItems = normalizeSearchResults(result);
-  if (ragModeEnabled && searchItems.length > 0) {
+  if (ragModeEnabled && shouldUseDefaultCitationMode(name, result, args) && searchItems.length > 0) {
     const defaultItems = normalizeDefaultDisplaySources(result).map((item, index) => ({
       ...item,
       index: index + 1,
@@ -618,7 +631,7 @@ function DisplayResultsList({ results }: { results: RuntimeDisplaySource[] }) {
             open && "rotate-180",
           )}
         />
-        <span>{results.length} 条适配结果</span>
+        <span>{results.length} 条真实返回结果</span>
       </CollapsibleTrigger>
       <CollapsibleContent className="mt-2 flex flex-col gap-2">
         {results.map((item) => (
diff --git a/frontend-web/src/components/workspace/messages/message-list.tsx b/frontend-web/src/components/workspace/messages/message-list.tsx
index b0819af5..e659d72f 100644
--- a/frontend-web/src/components/workspace/messages/message-list.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list.tsx
@@ -204,6 +204,7 @@ export function MessageList({
                   ? collectRuntimeDisplaySources(messages, skillDisplayMap, {
                       afterMessageId: findPreviousHumanMessageId(messages, msg.id),
                       beforeMessageId: msg.id,
+                      includeBeforeMessage: true,
                     })
                   : [];
               return (
diff --git a/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
index ed8d2071..5ae5cbd6 100644
--- a/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
+++ b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
@@ -1,7 +1,8 @@
 "use client";
 
 import { ExternalLinkIcon, Loader2, WandSparklesIcon } from "lucide-react";
-import { useEffect, useMemo, useState } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
@@ -18,10 +19,12 @@ import { Textarea } from "@/components/ui/textarea";
 import {
   emptyDisplayConfig,
   inferDisplayConfig,
-  mockKnowledgeSearchV2Result,
   normalizeDisplaySources,
 } from "@/core/skill-display/display-adapter";
-import { getSkillDisplaySample } from "@/core/skills/api";
+import {
+  getPersistedSkillDisplaySample,
+  getSkillDisplaySample,
+} from "@/core/skills/api";
 import { useSetSkillDisplay } from "@/core/skills/hooks";
 import type { Skill, SkillDisplayConfig, SkillDisplayMode, SkillLinkStrategy } from "@/core/skills/type";
 
@@ -62,10 +65,16 @@ function updateConfig<K extends keyof SkillDisplayConfig>(
   return { ...config, [key]: value };
 }
 
+function formatSample(sample: Record<string, unknown> | null | undefined) {
+  return sample ? JSON.stringify(sample, null, 2) : "";
+}
+
 export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
+  const queryClient = useQueryClient();
   const setDisplay = useSetSkillDisplay();
+  const lastSkillNameRef = useRef(skill.name);
   const [draft, setDraft] = useState<SkillDisplayConfig>(() => skill.display ?? emptyDisplayConfig());
-  const [sampleText, setSampleText] = useState(() => JSON.stringify(mockKnowledgeSearchV2Result, null, 2));
+  const [sampleText, setSampleText] = useState(() => formatSample(skill.displaySample));
   const [tableColumnsText, setTableColumnsText] = useState(() => JSON.stringify((skill.display ?? emptyDisplayConfig()).tableColumns ?? [], null, 2));
 
   // Echo server state into the form — on mount, on skill switch, AND after
@@ -83,8 +92,52 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
   // per skill, otherwise the user loses the JSON they just pulled in via
   // 自动识别 every time they hit 保存.
   useEffect(() => {
-    setSampleText(JSON.stringify(mockKnowledgeSearchV2Result, null, 2));
-  }, [skill.name]);
+    if (lastSkillNameRef.current !== skill.name) {
+      lastSkillNameRef.current = skill.name;
+      setSampleText(formatSample(skill.displaySample));
+      return;
+    }
+    if (skill.displaySample) {
+      setSampleText(formatSample(skill.displaySample));
+    }
+  }, [skill.name, skill.displaySample]);
+
+  useEffect(() => {
+    let cancelled = false;
+    async function loadPersistedSample() {
+      try {
+        const response = await getPersistedSkillDisplaySample(skill.name);
+        if (cancelled) {
+          return;
+        }
+        if (response.sample) {
+          setSampleText(formatSample(response.sample));
+          queryClient.setQueryData<Skill | undefined>(["skill", skill.name], (current) =>
+            current ? { ...current, displaySample: response.sample } : current,
+          );
+          queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
+            Array.isArray(current)
+              ? current.map((item) =>
+                  item.name === skill.name
+                    ? { ...item, displaySample: response.sample }
+                    : item,
+                )
+              : current,
+          );
+        } else if (!skill.displaySample) {
+          setSampleText("");
+        }
+      } catch (err) {
+        if (!cancelled) {
+          toast.error(err instanceof Error ? err.message : String(err));
+        }
+      }
+    }
+    void loadPersistedSample();
+    return () => {
+      cancelled = true;
+    };
+  }, [queryClient, skill.name, skill.displaySample]);
 
   const samplePayload = useMemo(() => {
     try {
@@ -114,6 +167,18 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
       const response = await getSkillDisplaySample(skill.name);
       const nextSampleText = JSON.stringify(response.sample, null, 2);
       setSampleText(nextSampleText);
+      queryClient.setQueryData<Skill | undefined>(["skill", skill.name], (current) =>
+        current ? { ...current, displaySample: response.sample } : current,
+      );
+      queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
+        Array.isArray(current)
+          ? current.map((item) =>
+              item.name === skill.name
+                ? { ...item, displaySample: response.sample }
+                : item,
+            )
+          : current,
+      );
       const nextDraft = inferDisplayConfig(response.sample, skill.name);
       setDraft(nextDraft);
       setTableColumnsText(JSON.stringify(nextDraft.tableColumns ?? [], null, 2));
@@ -126,7 +191,11 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
 
   async function saveDraft() {
     try {
-      await setDisplay.mutateAsync({ skillName: skill.name, display: draft });
+      await setDisplay.mutateAsync({
+        skillName: skill.name,
+        display: draft,
+        sample: samplePayload ?? undefined,
+      });
       toast.success("展示适配已保存");
     } catch (err) {
       toast.error(err instanceof Error ? err.message : String(err));
@@ -135,7 +204,7 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
 
   async function clearDisplay() {
     try {
-      await setDisplay.mutateAsync({ skillName: skill.name, display: null });
+      await setDisplay.mutateAsync({ skillName: skill.name, display: null, sample: null });
       setDraft(emptyDisplayConfig());
       setTableColumnsText(JSON.stringify([], null, 2));
       toast.success("展示适配已清除");
@@ -278,7 +347,11 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
           <div className="text-sm font-medium">展示预览</div>
           <div className="min-h-72 space-y-2 rounded-lg border bg-muted/20 p-3">
             {!samplePayload ? (
-              <div className="text-sm text-destructive">样例 JSON 解析失败</div>
+              sampleText.trim() ? (
+                <div className="text-sm text-destructive">样例 JSON 解析失败</div>
+              ) : (
+                <div className="text-sm text-muted-foreground">数据库暂无技能返回样例，请点击自动识别</div>
+              )
             ) : previewItems.length === 0 ? (
               <div className="text-sm text-muted-foreground">当前字段映射没有解析出结果</div>
             ) : draft.mode === "citation" ? (
diff --git a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
index f02d68c3..3dbe16ce 100644
--- a/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
+++ b/frontend-web/src/components/workspace/skills/skill-detail-dialog.tsx
@@ -68,6 +68,18 @@ function canManageSkill(skill: Skill | null | undefined): boolean {
   );
 }
 
+function isSkillOwner(skill: Skill | null | undefined): boolean {
+  if (!skill) return false;
+  const auth = getStoredAuth();
+  if (!auth) return false;
+  return (
+    skill.category === "custom" &&
+    !skill.builtin &&
+    !!skill.owner_user_id &&
+    skill.owner_user_id === auth.user_id
+  );
+}
+
 function stripYamlFrontmatter(content: string): string {
   return content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trimStart();
 }
@@ -96,13 +108,14 @@ export function SkillDetailDialog({
   const [openedFilePath, setOpenedFilePath] = useState<string | null>(null);
 
   const canManage = useMemo(() => canManageSkill(skill), [skill]);
+  const isOwner = useMemo(() => isSkillOwner(skill), [skill]);
   const {
     data: contentData,
     isLoading: isContentLoading,
     error: contentError,
-  } = useSkillContent(open && canManage ? skillName : null);
+  } = useSkillContent(open ? skillName : null);
 
-  const filesEnabled = open && canManage && activeTab === "files";
+  const filesEnabled = open && isOwner && activeTab === "files";
   const {
     data: filesData,
     isLoading: isFilesLoading,
@@ -121,7 +134,7 @@ export function SkillDetailDialog({
   }, [contentData]);
 
   const defaultTab: "detail" | "source" =
-    canManage && skill && !skill.detail ? "source" : "detail";
+    skill && !skill.detail ? "source" : "detail";
   const selectedTab = activeTab ?? defaultTab;
 
   function startEditing() {
@@ -215,18 +228,16 @@ export function SkillDetailDialog({
                   展示适配
                 </TabsTrigger>
               )}
-              {canManage && (
+              {isOwner && (
                 <TabsTrigger value="files" className="text-xs">
                   <FilesIcon className="mr-1 size-3.5" />
                   {tx.filesSectionTitle}
                 </TabsTrigger>
               )}
-              {canManage && (
-                <TabsTrigger value="source" className="text-xs">
-                  <FileCode2Icon className="mr-1 size-3.5" />
-                  {tx.contentSectionTitle}
-                </TabsTrigger>
-              )}
+              <TabsTrigger value="source" className="text-xs">
+                <FileCode2Icon className="mr-1 size-3.5" />
+                {tx.contentSectionTitle}
+              </TabsTrigger>
             </TabsList>
 
             <div className="flex shrink-0 items-center gap-1">
@@ -242,7 +253,6 @@ export function SkillDetailDialog({
                 </Button>
               )}
               {selectedTab === "source" &&
-                canManage &&
                 !isContentLoading &&
                 !contentError && (
                   <>
@@ -327,7 +337,7 @@ export function SkillDetailDialog({
               <div className="text-muted-foreground rounded-lg border border-dashed px-4 py-8 text-center">
                 <FileTextIcon className="mx-auto mb-2 size-6 opacity-40" />
                 <p className="text-sm">{tx.detailEmpty}</p>
-                {canManage ? (
+                {isOwner ? (
                   <p className="mt-1 text-xs">
                     Open the SKILL.md tab to view the skill source.
                   </p>
@@ -348,7 +358,7 @@ export function SkillDetailDialog({
             </TabsContent>
           )}
 
-          {canManage && (
+          {isOwner && (
             <TabsContent
               value="files"
               className="m-0 min-h-0 flex-1 overscroll-contain px-6 py-4 data-[state=inactive]:hidden"
@@ -376,12 +386,11 @@ export function SkillDetailDialog({
             </TabsContent>
           )}
 
-          {canManage && (
-            <TabsContent
-              value="source"
-              className="m-0 min-h-0 flex-1 overscroll-contain px-6 py-5 data-[state=inactive]:hidden"
-              style={{ overflowY: "auto" }}
-            >
+          <TabsContent
+            value="source"
+            className="m-0 min-h-0 flex-1 overscroll-contain px-6 py-5 data-[state=inactive]:hidden"
+            style={{ overflowY: "auto" }}
+          >
               {isContentLoading ? (
                 <div className="text-muted-foreground flex items-center justify-center gap-2 py-12 text-sm">
                   <Loader2 className="size-4 animate-spin" />
@@ -407,7 +416,6 @@ export function SkillDetailDialog({
                 />
               )}
             </TabsContent>
-          )}
         </Tabs>
         )}
       </DialogContent>
diff --git a/frontend-web/src/core/skill-display/display-adapter.ts b/frontend-web/src/core/skill-display/display-adapter.ts
index 1add1cf1..ce63e451 100644
--- a/frontend-web/src/core/skill-display/display-adapter.ts
+++ b/frontend-web/src/core/skill-display/display-adapter.ts
@@ -27,50 +27,65 @@ export const emptyDisplayConfig = (): SkillDisplayConfig => ({
   urlField: null,
   idField: null,
   linkStrategy: "auto",
-    linkTemplate: null,
-    citationToken: "doubleBracket",
-    maxItems: 8,
-    customInstruction: "",
-    tableColumns: [],
+  linkTemplate: null,
+  citationToken: "doubleBracket",
+  maxItems: 8,
+  customInstruction: "",
+  tableColumns: [],
 });
 
 export const mockKnowledgeSearchV2Result = {
   success: true,
-  query: "latest news",
-  count: 3,
+  query: "参考文献模式测试 知识库固定测试",
+  count: 4,
+  source: "fixed-display-sample",
   results: [
     {
       index: 1,
-      recUuid: "rec-001",
+      recUuid: "ksv2-fixed-001",
       relevance_score: 0.982,
-      title: "Knowledge result one",
-      source_category: "knowledge/news",
-      source: "internal news library",
+      title: "参考文献模式测试：参考文献模式固定测试数据一",
+      source_category: "知识库/测试资料",
+      source: "knowledge-search-v2/fixed/source-001",
       publish_time: "2026-05-25",
-      content_preview: "Mock result used to verify citation numbers, source cards, and recUuid template links.",
-      content_length: 1200,
+      content_preview:
+        "这是 knowledge-search-v2 返回的第一条固定测试资料，用于验证右侧参考文献列表、正文编号以及 recUuid 模板跳转是否正常。",
+      content_length: 168,
     },
     {
       index: 2,
-      recUuid: "rec-002",
-      relevance_score: 0.951,
-      title: "Knowledge result two",
-      source_category: "knowledge/news",
-      source: "internal news library",
+      recUuid: "ksv2-fixed-002",
+      relevance_score: 0.936,
+      title: "参考文献模式测试：结构化字段映射验证",
+      source_category: "知识库/字段映射",
+      source: "knowledge-search-v2/fixed/source-002",
       publish_time: "2026-05-24",
-      content_preview: "Mock result used to verify citation ordering and detail preview.",
-      content_length: 980,
+      content_preview:
+        "本条用于验证 title、source_category、source、publish_time、content_preview、relevance_score、recUuid 等字段能被前端正确识别并渲染。",
+      content_length: 154,
     },
     {
       index: 3,
-      recUuid: "rec-003",
-      relevance_score: 0.921,
-      title: "Knowledge result three",
-      source_category: "knowledge/commentary",
-      source: "internal knowledge library",
+      recUuid: "ksv2-fixed-003",
+      relevance_score: 0.887,
+      title: "参考文献模式测试：多引用排序验证",
+      source_category: "知识库/排序验证",
+      source: "knowledge-search-v2/fixed/source-003",
       publish_time: "2026-05-23",
-      content_preview: "Mock result used to verify list mode and custom display instruction previews.",
-      content_length: 760,
+      content_preview:
+        "本条用于验证多条参考文献的编号顺序是否与 results 数组顺序一致，并验证点击正文编号时能定位到右侧对应参考文献。",
+      content_length: 132,
+    },
+    {
+      index: 4,
+      recUuid: "",
+      relevance_score: 0.801,
+      title: "参考文献模式测试：无 recUuid 跳转隐藏验证",
+      source_category: "知识库/边界场景",
+      source: "knowledge-search-v2/fixed/source-004",
+      publish_time: "2026-05-22",
+      content_preview: "本条故意把 recUuid 置为空，用于验证右侧弹框仍展示详情，但不展示外部跳转按钮。",
+      content_length: 98,
     },
   ],
 };
@@ -196,7 +211,7 @@ export function normalizeDisplaySources(payload: unknown, config: SkillDisplayCo
     .slice(0, config.maxItems)
     .map((item, index) => ({
       id: config.idField ? stringify(item[config.idField]) : undefined,
-      title: config.titleField ? stringify(item[config.titleField], `Result ${index + 1}`) : `Result ${index + 1}`,
+      title: config.titleField ? stringify(item[config.titleField], `结果 ${index + 1}`) : `结果 ${index + 1}`,
       type: config.typeField ? stringify(item[config.typeField], "result") : "result",
       snippet: config.summaryField ? stringify(item[config.summaryField]) : "",
       content: config.contentField ? stringify(item[config.contentField]) : undefined,
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
index ef18c1ee..e91c2164 100644
--- a/frontend-web/src/core/skill-display/runtime.ts
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -56,7 +56,7 @@ export function findDisplayConfigForTool(
   // Scan stringy args for the `skills/{public,custom}/<name>/` shape so display
   // configs still resolve. Mirrors the backend `_SKILL_PATH_RE` in
   // tool_metrics_middleware.py.
-  if (toolArgs) {
+  if (toolArgs && canInferSkillFromToolArgs(toolName)) {
     const skillFromArgs = extractSkillNameFromArgs(toolArgs);
     if (skillFromArgs) {
       const direct = displays.get(skillFromArgs);
@@ -69,6 +69,51 @@ export function findDisplayConfigForTool(
 }
 
 const SKILL_PATH_RE = /[\\/]skills[\\/](?:public|custom)[\\/]([^\\/]+)(?:[\\/]|$)/;
+const TOOL_ARG_SKILL_MATCH_EXCLUDES = new Set([
+  "read_file",
+  "readfile",
+  "ls",
+  "write_file",
+  "writefile",
+  "str_replace",
+  "strreplace",
+  "web_fetch",
+  "webfetch",
+]);
+
+function canInferSkillFromToolArgs(toolName: string): boolean {
+  const normalized = normalizeName(toolName);
+  if (
+    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(toolName) ||
+    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(normalized)
+  ) {
+    return false;
+  }
+  return (
+    normalized.includes("bash") ||
+    normalized.includes("shell") ||
+    normalized.includes("python") ||
+    normalized.includes("execute") ||
+    normalized.includes("terminal")
+  );
+}
+
+function canInspectPayloadForDisplay(toolName: string): boolean {
+  const normalized = normalizeName(toolName);
+  if (
+    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(toolName) ||
+    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(normalized)
+  ) {
+    return false;
+  }
+  return (
+    canInferSkillFromToolArgs(toolName) ||
+    normalized.includes("search") ||
+    normalized.includes("retriev") ||
+    normalized.includes("knowledge") ||
+    normalized.includes("query")
+  );
+}
 
 function extractSkillNameFromArgs(args: Record<string, unknown>): string | undefined {
   for (const value of Object.values(args)) {
@@ -87,6 +132,7 @@ export function collectRuntimeDisplaySources(
   options: {
     afterMessageId?: string;
     beforeMessageId?: string;
+    includeBeforeMessage?: boolean;
     includeModes?: SkillDisplayConfig["mode"][];
   } = {},
 ): RuntimeDisplaySource[] {
@@ -101,7 +147,8 @@ export function collectRuntimeDisplaySources(
     options.beforeMessageId === undefined
       ? messages.length
       : Math.max(
-          messages.findIndex((message) => message.id === options.beforeMessageId),
+          messages.findIndex((message) => message.id === options.beforeMessageId) +
+            (options.includeBeforeMessage ? 1 : 0),
           0,
         );
   const allowedModes = options.includeModes
@@ -117,22 +164,38 @@ export function collectRuntimeDisplaySources(
       continue;
     }
     for (const toolCall of message.tool_calls ?? []) {
-      const match = findDisplayConfigForTool(
+      const toolMatch = findDisplayConfigForTool(
         toolCall.name,
         displays,
         toolCall.args as Record<string, unknown> | undefined,
       );
-      const effectiveMode = match?.display.mode ?? "citation";
-      if (allowedModes && !allowedModes.has(effectiveMode)) {
-        continue;
-      }
       const result = findToolResultPayload(toolCall.id, messages);
       if (result === undefined) {
         continue;
       }
+      if (isDisplaySamplePayload(result)) {
+        continue;
+      }
+      const match =
+        toolMatch ??
+        findDisplayConfigForPayload(
+          toolCall.name,
+          result,
+          displays,
+        );
+      const effectiveMode = match?.display.mode ?? "citation";
+      if (allowedModes && !allowedModes.has(effectiveMode)) {
+        continue;
+      }
       const normalized = match
         ? normalizeDisplaySources(result, match.display)
-        : normalizeDefaultDisplaySources(result);
+        : shouldUseDefaultCitationMode(
+            toolCall.name,
+            result,
+            toolCall.args as Record<string, unknown> | undefined,
+          )
+          ? normalizeDefaultDisplaySources(result)
+          : [];
       for (const item of normalized) {
         const skillName = match?.skillName ?? toolCall.name;
         const displayKey = `${skillName}:${effectiveMode}`;
@@ -151,6 +214,113 @@ export function collectRuntimeDisplaySources(
   return sources;
 }
 
+export function findDisplayConfigForPayload(
+  toolName: string,
+  payload: unknown,
+  displays: SkillDisplayMap,
+): { skillName: string; display: SkillDisplayConfig } | null {
+  if (!canInspectPayloadForDisplay(toolName)) {
+    return null;
+  }
+  let best: { skillName: string; display: SkillDisplayConfig; score: number } | null = null;
+  for (const [skillName, display] of displays) {
+    const score = scoreDisplayPayloadMatch(payload, display);
+    if (score >= 3 && (!best || score > best.score)) {
+      best = { skillName, display, score };
+    }
+  }
+  return best ? { skillName: best.skillName, display: best.display } : null;
+}
+
+export function isDisplaySamplePayload(payload: unknown): boolean {
+  if (!isRecord(payload)) {
+    return false;
+  }
+  if (payload.__displaySample === true || payload.displaySample === true) {
+    return true;
+  }
+  if (payload.query === "sample query") {
+    return true;
+  }
+  const items =
+    getArrayByPath(payload, "results") ??
+    getArrayByPath(payload, "data") ??
+    getArrayByPath(payload, "items");
+  const first = items?.find((item): item is Record<string, unknown> => isRecord(item));
+  if (!first) {
+    return false;
+  }
+  const text = Object.values(first)
+    .filter((value) => typeof value === "string")
+    .join("\n")
+    .toLowerCase();
+  return (
+    /^sample-/i.test(String(first.id ?? "")) ||
+    text.includes("mock result") ||
+    text.includes("knowledge result one")
+  );
+}
+
+function scoreDisplayPayloadMatch(payload: unknown, display: SkillDisplayConfig): number {
+  const items = getArrayByPath(payload, display.resultPath);
+  const first = items?.find((item): item is Record<string, unknown> => isRecord(item));
+  if (!first) {
+    return 0;
+  }
+  const fields = [
+    display.titleField,
+    display.summaryField,
+    display.contentField,
+    display.sourceField,
+    display.typeField,
+    display.timeField,
+    display.scoreField,
+    display.urlField,
+    display.idField,
+  ].filter((field): field is string => !!field);
+  return new Set(fields).size === 0
+    ? 0
+    : [...new Set(fields)].filter(
+        (field) =>
+          first[field] !== undefined &&
+          first[field] !== null &&
+          first[field] !== "",
+      ).length;
+}
+
+function getArrayByPath(payload: unknown, path: string): unknown[] | null {
+  const value = path.split(".").reduce<unknown>((acc, key) => {
+    if (acc && typeof acc === "object") {
+      return (acc as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, payload);
+  return Array.isArray(value) ? value : null;
+}
+
+export function shouldUseDefaultCitationMode(
+  toolName: string,
+  payload: unknown,
+  toolArgs?: Record<string, unknown>,
+): boolean {
+  const normalizedName = normalizeName(toolName);
+  const isSearchLikeTool =
+    normalizedName.includes("search") ||
+    normalizedName.includes("retriev") ||
+    normalizedName.includes("knowledge") ||
+    normalizedName.includes("query");
+  const isSkillInvocation = !!(
+    toolArgs &&
+    canInferSkillFromToolArgs(toolName) &&
+    extractSkillNameFromArgs(toolArgs)
+  );
+  if (!isSearchLikeTool && !isSkillInvocation) {
+    return false;
+  }
+
+  return normalizeDefaultDisplaySources(payload).length > 0;
+}
+
 export function normalizeDefaultDisplaySources(payload: unknown): DisplaySourceItem[] {
   const normalized = normalizeSearchResults(
     typeof payload === "string" || isRecord(payload)
@@ -288,23 +458,77 @@ function findToolResultPayload(
   if (!toolMessage) {
     return undefined;
   }
+  const structured = extractStructuredToolPayload(toolMessage.content);
+  if (structured !== undefined) {
+    return structured;
+  }
   const content = extractToolText(toolMessage.content);
   if (!content) {
     return undefined;
   }
-  try {
-    return JSON.parse(content) as unknown;
-  } catch {
-    // bash stdout on the local sandbox can be suffixed with
-    // "\nStd Error: ..." / "\nExit Code: N" (see local_sandbox.execute_command),
-    // and skills sometimes print informational lines around their JSON payload.
-    // Salvage the first balanced JSON object or array we can find before
-    // falling back to the raw string.
-    const recovered = extractJSONFromText(content);
-    if (recovered !== undefined) {
-      return recovered;
+  const parsed = parseJSONLikeText(content);
+  if (parsed !== undefined) {
+    return parsed;
+  }
+  return content;
+}
+
+function extractStructuredToolPayload(content: unknown): unknown {
+  if (isRecord(content)) {
+    return unwrapToolPayloadObject(content);
+  }
+  if (Array.isArray(content)) {
+    for (const part of content) {
+      if (!isRecord(part)) {
+        continue;
+      }
+      if (isRecord(part.json)) {
+        return unwrapToolPayloadObject(part.json);
+      }
+      const unwrapped = unwrapToolPayloadObject(part);
+      if (unwrapped !== undefined) {
+        return unwrapped;
+      }
     }
-    return content;
+  }
+  return undefined;
+}
+
+function unwrapToolPayloadObject(value: Record<string, unknown>): unknown {
+  if (
+    Array.isArray(value.results) ||
+    Array.isArray(value.data) ||
+    Array.isArray(value.items)
+  ) {
+    return value;
+  }
+  for (const key of ["result", "output", "stdout", "stderr", "content", "text"]) {
+    const nested = value[key];
+    if (typeof nested === "string") {
+      const parsed = parseJSONLikeText(nested);
+      if (parsed !== undefined) {
+        return parsed;
+      }
+    }
+    if (isRecord(nested)) {
+      const unwrapped = unwrapToolPayloadObject(nested);
+      if (unwrapped !== undefined) {
+        return unwrapped;
+      }
+    }
+  }
+  return undefined;
+}
+
+function parseJSONLikeText(text: string): unknown {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(trimmed) as unknown;
+  } catch {
+    return extractJSONFromText(trimmed);
   }
 }
 
diff --git a/frontend-web/src/core/skills/api.ts b/frontend-web/src/core/skills/api.ts
index ce49ad4d..01a64404 100644
--- a/frontend-web/src/core/skills/api.ts
+++ b/frontend-web/src/core/skills/api.ts
@@ -49,6 +49,7 @@ export async function enableSkill(skillName: string, enabled: boolean) {
 export async function setSkillDisplay(
   skillName: string,
   display: SkillDisplayConfig | null,
+  sample?: Record<string, unknown> | null,
 ): Promise<Skill> {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display`,
@@ -57,7 +58,7 @@ export async function setSkillDisplay(
       headers: {
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({ display }),
+      body: JSON.stringify({ display, sample }),
     },
   );
   if (!response.ok) {
@@ -71,6 +72,23 @@ export interface SkillDisplaySampleResponse {
   sample: Record<string, unknown>;
 }
 
+export interface PersistedSkillDisplaySampleResponse {
+  skill_name: string;
+  sample: Record<string, unknown> | null;
+}
+
+export async function getPersistedSkillDisplaySample(
+  skillName: string,
+): Promise<PersistedSkillDisplaySampleResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to get persisted skill display sample");
+  }
+  return response.json() as Promise<PersistedSkillDisplaySampleResponse>;
+}
+
 export async function getSkillDisplaySample(
   skillName: string,
 ): Promise<SkillDisplaySampleResponse> {
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index c4c67d02..752bc385 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -71,10 +71,12 @@ export function useSetSkillDisplay() {
     mutationFn: ({
       skillName,
       display,
+      sample,
     }: {
       skillName: string;
       display: Parameters<typeof setSkillDisplay>[1];
-    }) => setSkillDisplay(skillName, display),
+      sample?: Parameters<typeof setSkillDisplay>[2];
+    }) => setSkillDisplay(skillName, display, sample),
     onSuccess: (_data, { skillName }) => {
       void queryClient.invalidateQueries({ queryKey: ["skills"] });
       void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
diff --git a/frontend-web/src/core/skills/type.ts b/frontend-web/src/core/skills/type.ts
index 3a6ac12b..1ee80050 100644
--- a/frontend-web/src/core/skills/type.ts
+++ b/frontend-web/src/core/skills/type.ts
@@ -48,6 +48,7 @@ export interface Skill {
   // Distinct from ``description`` (parsed from SKILL.md); supports Markdown.
   detail?: string | null;
   display?: SkillDisplayConfig | null;
+  displaySample?: Record<string, unknown> | null;
   // Lifecycle fields — populated by curator. The main list filters on these
   // so stale / archived skills appear in dedicated drawers instead.
   state?: SkillState;
diff --git a/frontend-web/src/core/threads/hooks.ts b/frontend-web/src/core/threads/hooks.ts
index 568b204e..55331139 100644
--- a/frontend-web/src/core/threads/hooks.ts
+++ b/frontend-web/src/core/threads/hooks.ts
@@ -315,13 +315,23 @@ export function useThreadStream({
   const threadStreamRef = useRef(thread);
   threadStreamRef.current = thread;
 
-  // Reset thread-local pending UI state when switching between threads so
-  // optimistic messages and in-flight guards do not leak across chat views.
-  // Also abort any in-flight SSE from the previous thread: without this,
-  // clicking "新对话" mid-stream leaves the old run firing onUpdate events
-  // against the now-detached thread context, which manifests as the page
-  // appearing unresponsive to the navigation.
+  // Reset thread-local pending UI state when the caller actually switches AWAY
+  // from a thread (threadId becomes nullish). This is the "click 新对话 / open
+  // a fresh chat" signal — abort the in-flight SSE and clear optimistic state.
+  //
+  // We deliberately do NOT reset on every threadId change. During a normal
+  // "user just sent the first message on /chats/new" flow, useThreadStream
+  // sees threadId transition from undefined (the landing state) to the
+  // server-assigned thread id once onCreated fires. Stopping the stream and
+  // clearing optimistic messages in that case is exactly what made submitted
+  // questions visually disappear — the live run that just started would be
+  // aborted by the very effect intended to reset stale state.
   useEffect(() => {
+    if (threadId != null) {
+      // Forward direction: starting or continuing with a real thread.
+      // No reset needed; the upstream useStream will load history for this id.
+      return;
+    }
     const prevThread = threadStreamRef.current;
     if (prevThread?.isLoading) {
       try {
diff --git a/frontend-web/src/pages/ChatPage.tsx b/frontend-web/src/pages/ChatPage.tsx
index 9eb6d6db..6a9ef79f 100644
--- a/frontend-web/src/pages/ChatPage.tsx
+++ b/frontend-web/src/pages/ChatPage.tsx
@@ -231,14 +231,25 @@ export default function ChatPage() {
           </header>
           <main className="flex min-h-0 max-w-full grow flex-col">
             <div className="flex size-full justify-center">
-              <MessageList
-                className={cn("size-full", !isLandingState && "pt-10")}
-                threadId={threadId}
-                thread={thread}
-                paddingBottom={messageListPaddingBottom}
-                tokenUsageEnabled={tokenUsageEnabled}
-                onClarificationSubmit={handleClarificationSubmit}
-              />
+              {/*
+                Landing state covers two cases: (a) a brand-new chat that
+                hasn't sent anything yet, and (b) the user clicking 「新对话」
+                mid-stream. In (b) the underlying useStream's internal
+                stream.values takes one or two effect ticks to clear, so
+                rendering MessageList unconditionally would leak the previous
+                conversation under the welcome card. Skip rendering during
+                the landing state to guarantee a clean slate.
+              */}
+              {!isLandingState && (
+                <MessageList
+                  className={cn("size-full", "pt-10")}
+                  threadId={threadId}
+                  thread={thread}
+                  paddingBottom={messageListPaddingBottom}
+                  tokenUsageEnabled={tokenUsageEnabled}
+                  onClarificationSubmit={handleClarificationSubmit}
+                />
+              )}
             </div>
             <div className="absolute right-0 bottom-0 left-0 z-30 flex justify-center px-4">
               <div
diff --git a/frontend-web/src/pages/WorkspaceRoutes.tsx b/frontend-web/src/pages/WorkspaceRoutes.tsx
index 4f7b4cbb..a721f0da 100644
--- a/frontend-web/src/pages/WorkspaceRoutes.tsx
+++ b/frontend-web/src/pages/WorkspaceRoutes.tsx
@@ -1,5 +1,5 @@
 import type { CSSProperties, ReactNode } from "react";
-import { Navigate, Route, Routes, useLocation } from "react-router-dom";
+import { Navigate, Route, Routes } from "react-router-dom";
 
 import { getStoredAuth } from "@/core/auth";
 
@@ -87,20 +87,6 @@ export function ChatRuntime({ children }: { children: ReactNode }) {
   );
 }
 
-/**
- * 让 ChatPage 在每次真正的 react-router navigation 上完整 remount。
- *
- * 背景:点「新对话」时即使路径不变,我们也会用 `navigate(..., { replace: true,
- * state: { resetAt } })` 强制刷新 location.key —— 用它作 key 能保证 useStream、
- * useThreadStream、optimistic state、refs 一次性全部丢弃,避免上一条流的
- * `stream.values` 残留把欢迎页底下的旧消息拖出来(SDK 的 stream.clear() 需要
- * 多次 effect tick 才会清干净,中间过渡帧用户能看见)。
- */
-function KeyedChatPage({ render }: { render: () => ReactNode }) {
-  const key = useLocation().key;
-  return <ChatRuntime key={key}>{render()}</ChatRuntime>;
-}
-
 export default function WorkspaceRoutes({
   pageSidebarCollapsed = false,
   pageSidebarHidden = false,
@@ -135,7 +121,9 @@ export default function WorkspaceRoutes({
         path="chats/:thread_id"
         element={
           <WorkspaceLayout {...layoutProps}>
-            <KeyedChatPage render={() => <ChatPage />} />
+            <ChatRuntime>
+              <ChatPage />
+            </ChatRuntime>
           </WorkspaceLayout>
         }
       />
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index 1a10cad2..9d8cbcb3 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -1,1965 +1,2155 @@
-import asyncio
-import json
-import logging
-import mimetypes
-import re
-import tempfile
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-from fastapi import APIRouter, Body, Depends, File, HTTPException, Query, Request, UploadFile
-from fastapi.responses import FileResponse
-from pydantic import BaseModel, Field
-
-from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_tag_store
-from app.gateway.path_utils import resolve_thread_virtual_path
-from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
-from deerflow.config.app_config import AppConfig
-from deerflow.config.extensions_config import ExtensionsConfig, SkillDisplayConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
-from deerflow.persistence.skills import SkillStore
-from deerflow.persistence.tags import TagStore
-from deerflow.runtime.user_context import get_effective_user_id
-from deerflow.skills import Skill
-from deerflow.skills.cascade import cascade_skill_unpublished_or_deleted
-from deerflow.skills.installer import SkillAlreadyExistsError
-from deerflow.skills.security_scanner import scan_skill_content
-from deerflow.skills.storage import get_or_new_skill_storage
-from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/api", tags=["skills"])
-
-
-# ---------------------------------------------------------------------------
-# Per-user authz helpers (mirrors routers/agents.py)
-# ---------------------------------------------------------------------------
-
-
-def _current_user_id(request: Request) -> str:
-    user = getattr(request.state, "user", None)
-    if user is not None:
-        return str(user.id)
-    return get_effective_user_id()
-
-
-def _is_admin_user(request: Request) -> bool:
-    user = getattr(request.state, "user", None)
-    return getattr(user, "system_role", None) == "admin"
-
-
-def _can_view_skill_source(
-    category: SkillCategory,
-    owner_user_id: str | None,
-    user_id: str,
-    *,
-    is_admin: bool,
-) -> bool:
-    """Whether the raw SKILL.md source is visible to a user.
-
-    Admins may view any skill's source; otherwise only the publisher (the
-    owner of a custom skill) qualifies. Built-in / public skills have no human
-    owner, so for non-admins they are never source-visible.
-    """
-    if is_admin:
-        return True
-    return category == SkillCategory.CUSTOM and owner_user_id is not None and owner_user_id == user_id
-
-
-async def _get_owned_skill_or_raise(store: SkillStore, name: str, user_id: str) -> dict[str, Any]:
-    owned = await store.get_owned(name, user_id)
-    if owned is not None:
-        return owned
-    visible = await store.get_visible(name, user_id)
-    if visible is None:
-        raise HTTPException(status_code=404, detail=f"Skill '{name}' not found")
-    raise HTTPException(status_code=403, detail="You can only modify skills that you own")
-
-
-async def _get_editable_skill_or_raise(
-    store: SkillStore,
-    name: str,
-    user_id: str,
-    *,
-    is_admin: bool,
-) -> tuple[dict[str, Any], str]:
-    """Return (record, edit_mode) where edit_mode is 'owner' or 'admin'.
-
-    Admins can edit/delete any skill (including others' published ones, since
-    the spec lets them force-takedown). Non-admins are limited to their own.
-    """
-    owned = await store.get_owned(name, user_id)
-    if owned is not None:
-        return owned, "owner"
-    record = await store.get_any(name)
-    if record is None:
-        raise HTTPException(status_code=404, detail=f"Skill '{name}' not found")
-    if is_admin:
-        return record, "admin"
-    raise HTTPException(status_code=403, detail="You can only modify skills that you own")
-
-
-class SkillResponse(BaseModel):
-    """Response model for skill information."""
-
-    name: str = Field(..., description="Name of the skill")
-    description: str = Field(..., description="Description of what the skill does")
-    license: str | None = Field(None, description="License information")
-    category: SkillCategory = Field(..., description="Category of the skill (public or custom)")
-    enabled: bool = Field(default=True, description="Whether this skill is enabled")
-    use_count: int = Field(default=0, description="Number of times the skill has been used")
-    view_count: int = Field(default=0, description="Number of times the skill has been viewed")
-    patch_count: int = Field(default=0, description="Number of times the skill has been patched")
-    last_activity_at: datetime | None = Field(default=None, description="Most recent activity timestamp")
-    state: str = Field(default="active", description="Lifecycle state: active, stale, or archived")
-    pinned: bool = Field(default=False, description="Whether this skill is pinned (excluded from curation)")
-    source: str = Field(default="upload", description="Origin: 'agent' for agent-created, 'upload' for user-uploaded")
-    owner_user_id: str | None = Field(default=None, description="Custom skill owner (null = built-in or legacy)")
-    published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
-    builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
-    detail: str | None = Field(default=None, description="Human-authored long-form detail text (Markdown), editable by owner/admin")
-    display: dict[str, Any] | None = Field(default=None, description="Optional frontend display adapter")
-    tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
-
-
-class SkillsListResponse(BaseModel):
-    """Response model for listing all skills."""
-
-    skills: list[SkillResponse]
-
-
-class SkillUpdateRequest(BaseModel):
-    """Request model for updating a skill."""
-
-    enabled: bool = Field(..., description="Whether to enable or disable the skill")
-
-
-class SkillDisplayUpdateRequest(BaseModel):
-    """Request model for updating a skill's frontend display adapter."""
-
-    display: SkillDisplayConfig | None = Field(default=None, description="Display adapter configuration; null clears it")
-
-
-class SkillDisplaySampleResponse(BaseModel):
-    """Sample structured output used to infer a display adapter."""
-
-    skill_name: str
-    sample: dict[str, Any]
-
-
-class SkillInstallRequest(BaseModel):
-    """Request model for installing a skill from a .skill file."""
-
-    thread_id: str = Field(..., description="The thread ID where the .skill file is located")
-    path: str = Field(..., description="Virtual path to the .skill file (e.g., mnt/user-data/outputs/my-skill.skill)")
-    target_category: SkillCategory = Field(default=SkillCategory.CUSTOM, description="Destination category: 'public' (admin only) or 'custom'")
-
-
-class SkillInstallResponse(BaseModel):
-    """Response model for skill installation."""
-
-    success: bool = Field(..., description="Whether the installation was successful")
-    skill_name: str = Field(..., description="Name of the installed skill")
-    message: str = Field(..., description="Installation result message")
-    overwritten: bool = Field(default=False, description="True if an existing skill was replaced")
-    category: str = Field(default="custom", description="Destination category: 'public' (admin) or 'custom'")
-
-
-class SkillUploadValidateResponse(BaseModel):
-    """Response model for the pre-install validation endpoint."""
-
-    ok: bool = Field(..., description="Whether the archive passed cheap validation")
-    skill_name: str = Field(..., description="Skill name parsed from frontmatter")
-    description: str = Field(default="", description="Skill description parsed from frontmatter")
-    license: str | None = Field(default=None, description="Skill license, if declared")
-    allowed_tools: list[str] = Field(default_factory=list, description="Tools the skill may invoke")
-    conflict: bool = Field(default=False, description="True if a skill with the same name already exists")
-    conflict_kind: str | None = Field(default=None, description="'public' or 'custom' when conflict=true")
-    warnings: list[str] = Field(default_factory=list, description="Non-fatal warnings to surface to the user")
-
-
-class SkillReconcileResponse(BaseModel):
-    """Response model for reconciling custom skills found on disk."""
-
-    adopted: list[str] = Field(default_factory=list, description="Skills found on disk that had no DB row; now owned by the caller")
-    already_registered: list[str] = Field(default_factory=list, description="Skills found on disk that already had a DB row (unchanged)")
-
-
-class CustomSkillContentResponse(SkillResponse):
-    content: str = Field(..., description="Raw SKILL.md content")
-
-
-class CustomSkillUpdateRequest(BaseModel):
-    content: str = Field(..., description="Replacement SKILL.md content")
-
-
-class CustomSkillHistoryResponse(BaseModel):
-    history: list[dict]
-
-
-class SkillRollbackRequest(BaseModel):
-    history_index: int = Field(default=-1, description="History entry index to restore from, defaulting to the latest change.")
-
-
-def _skill_to_response(skill: Skill, ownership: dict[str, Any] | None = None) -> SkillResponse:
-    """Convert a Skill object to a SkillResponse.
-
-    ``ownership`` is the skill's record from ``SkillStore`` (or None for public
-    built-in skills which never have a DB row). When present, contributes the
-    ``owner_user_id`` / ``published`` / ``builtin`` fields used for per-user
-    visibility and the frontend's owner badges.
-    """
-    from deerflow.skills.usage import get_entry, latest_activity_at
-
-    entry = get_entry(skill.name)
-    last_at_str = latest_activity_at(skill.name)
-    last_at: datetime | None = None
-    if last_at_str:
-        try:
-            last_at = datetime.fromisoformat(last_at_str)
-        except Exception:
-            pass
-
-    owner_user_id: str | None = None
-    published = False
-    builtin = skill.category != SkillCategory.CUSTOM
-    detail: str | None = None
-    if ownership is not None:
-        owner_user_id = ownership.get("owner_user_id")
-        published = bool(ownership.get("published", False))
-        builtin = bool(ownership.get("builtin", owner_user_id is None))
-        detail = ownership.get("detail")
-
-    display = None
-    try:
-        skill_config = get_extensions_config().skills.get(skill.name)
-        if skill_config and skill_config.display:
-            display = skill_config.display.model_dump(by_alias=True)
-    except Exception:
-        logger.debug("Failed to read display adapter for %s", skill.name, exc_info=True)
-
-    return SkillResponse(
-        name=skill.name,
-        description=skill.description,
-        license=skill.license,
-        category=skill.category,
-        enabled=skill.enabled,
-        use_count=entry.get("use_count", 0),
-        view_count=entry.get("view_count", 0),
-        patch_count=entry.get("patch_count", 0),
-        last_activity_at=last_at,
-        state=entry.get("state", "active"),
-        pinned=entry.get("pinned", False),
-        source=entry.get("source", "upload"),
-        owner_user_id=owner_user_id,
-        published=published,
-        builtin=builtin,
-        detail=detail,
-        display=display,
-    )
-
-
-def _dump_extensions_config(config_obj: ExtensionsConfig) -> dict[str, Any]:
-    return {
-        "mcpServers": {name: server.model_dump(by_alias=True) for name, server in config_obj.mcp_servers.items()},
-        "skills": {name: skill_config.model_dump(by_alias=True, exclude_none=True) for name, skill_config in config_obj.skills.items()},
-    }
-
-
-_SKILL_SAMPLE_SYSTEM_PROMPT = (
-    "You infer realistic JSON return shapes for AI agent skills. "
-    "Given a skill's name, description, and full SKILL.md, output a SINGLE JSON object that "
-    "represents a plausible successful response from this skill's primary action. "
-    "Rules:\n"
-    "- Output JSON ONLY. No prose. No markdown fences. No comments.\n"
-    "- The top level must be a JSON object (not an array).\n"
-    "- Include a results/items/list/records array (pick the most natural key) with 2-3 example entries.\n"
-    "- Use realistic, idiomatic field names (e.g. title, content, source, publish_time, score, url, id) that match the skill's domain.\n"
-    "- Each entry should have enough fields to drive a citation/list/table UI: a title, a short snippet/content, a source, a time/date, and an id or url when relevant.\n"
-    "- Numbers stay numbers, dates stay ISO strings, scores between 0 and 1 when applicable.\n"
-    "- Do not invent fields that contradict the skill description."
-)
-
-
-def _extract_json_from_llm_output(raw: str) -> dict[str, Any] | None:
-    """Best-effort extraction of a JSON object from an LLM response."""
-    text = (raw or "").strip()
-    if not text:
-        return None
-    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.DOTALL | re.IGNORECASE)
-    if fence:
-        text = fence.group(1).strip()
-    try:
-        parsed = json.loads(text)
-        return parsed if isinstance(parsed, dict) else None
-    except json.JSONDecodeError:
-        pass
-    match = re.search(r"\{.*\}", text, re.DOTALL)
-    if not match:
-        return None
-    try:
-        parsed = json.loads(match.group(0))
-        return parsed if isinstance(parsed, dict) else None
-    except json.JSONDecodeError:
-        return None
-
-
-async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) -> dict[str, Any]:
-    """Generate a realistic return-shape sample for ``skill`` via the LLM.
-
-    Reads SKILL.md, asks the configured curator model (or main model) to infer
-    a plausible JSON response. Falls back to :func:`_mock_skill_display_sample`
-    when the model is unconfigured, the call times out, or the output cannot
-    be parsed as a JSON object.
-    """
-    try:
-        skill_content = skill.skill_file.read_text(encoding="utf-8")
-    except OSError as exc:
-        logger.debug("Cannot read SKILL.md for %s (%s); falling back to description only", skill.name, exc)
-        skill_content = ""
-    # Cap the SKILL.md body so very large workflow docs don't blow the context.
-    max_chars = 6000
-    if len(skill_content) > max_chars:
-        skill_content = skill_content[:max_chars] + "\n…(truncated)"
-
-    user_prompt = (
-        f"Skill name: {skill.name}\n"
-        f"Short description: {skill.description}\n\n"
-        f"SKILL.md:\n-----\n{skill_content or '(SKILL.md unavailable; rely on the short description above.)'}\n-----\n\n"
-        "Return one JSON object that matches what this skill would actually produce on success."
-    )
-
-    try:
-        from deerflow.models import create_chat_model
-
-        # Reuse the curator/security-scan model setting; falls back to the main model when unset.
-        model_name = app_config.skill_evolution.curator.model_name if app_config.skill_evolution and app_config.skill_evolution.curator else None
-        model = create_chat_model(name=model_name, thinking_enabled=False, app_config=app_config)
-        response = await asyncio.wait_for(
-            model.ainvoke(
-                [
-                    {"role": "system", "content": _SKILL_SAMPLE_SYSTEM_PROMPT},
-                    {"role": "user", "content": user_prompt},
-                ],
-                config={"run_name": "skill_display_sample"},
-            ),
-            timeout=45,
-        )
-        parsed = _extract_json_from_llm_output(str(getattr(response, "content", "") or ""))
-        if parsed:
-            return parsed
-        logger.warning("Skill display sample model returned non-JSON for %s; falling back to static mock", skill.name)
-    except asyncio.TimeoutError:
-        logger.warning("Skill display sample LLM call timed out for %s; falling back to static mock", skill.name)
-    except Exception:
-        logger.warning("Skill display sample LLM call failed for %s; falling back to static mock", skill.name, exc_info=True)
-    return _mock_skill_display_sample(skill.name)
-
-
-def _mock_skill_display_sample(skill_name: str) -> dict[str, Any]:
-    if skill_name == "knowledge-search-v2":
-        return {
-            "success": True,
-            "query": "latest news",
-            "count": 3,
-            "results": [
-                {
-                    "index": 1,
-                    "recUuid": "rec-001",
-                    "relevance_score": 0.982,
-                    "title": "Knowledge result one",
-                    "source_category": "knowledge/news",
-                    "source": "internal news library",
-                    "publish_time": "2026-05-25",
-                    "content_preview": "Mock result used to verify citation numbers, source cards, and recUuid template links.",
-                    "content_length": 1200,
-                },
-                {
-                    "index": 2,
-                    "recUuid": "rec-002",
-                    "relevance_score": 0.951,
-                    "title": "Knowledge result two",
-                    "source_category": "knowledge/news",
-                    "source": "internal news library",
-                    "publish_time": "2026-05-24",
-                    "content_preview": "Mock result used to verify citation ordering and detail preview.",
-                    "content_length": 980,
-                },
-                {
-                    "index": 3,
-                    "recUuid": "rec-003",
-                    "relevance_score": 0.921,
-                    "title": "Knowledge result three",
-                    "source_category": "knowledge/commentary",
-                    "source": "internal knowledge library",
-                    "publish_time": "2026-05-23",
-                    "content_preview": "Mock result used to verify list mode and custom display instruction previews.",
-                    "content_length": 760,
-                },
-            ],
-        }
-    return {
-        "success": True,
-        "query": "sample query",
-        "results": [
-            {
-                "id": "sample-001",
-                "title": "Sample result",
-                "summary": "Sample structured output used to infer field mapping.",
-                "source": "sample",
-                "updatedAt": "2026-05-25",
-            }
-        ],
-    }
-
-
-async def _build_ownership_index(skill_store: SkillStore, user_id: str) -> dict[str, dict[str, Any]]:
-    """Index visible-to-user skill records by name. Internal call cache for list endpoints."""
-    records = await skill_store.list_visible(user_id)
-    return {record["name"]: record for record in records}
-
-
-async def _attach_and_filter_tags(
-    tag_store: TagStore,
-    responses: list[SkillResponse],
-    search: str | None,
-    tag_ids: list[str] | None,
-) -> list[SkillResponse]:
-    """Bulk-attach tags to skill responses, then apply name/tag filters."""
-    assignments = await tag_store.list_assignments("skill", [r.name for r in responses])
-    for resp in responses:
-        resp.tags = assignments.get(resp.name, [])
-    if search:
-        needle = search.strip().lower()
-        responses = [r for r in responses if needle in r.name.lower()]
-    if tag_ids:
-        wanted = set(tag_ids)
-        responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
-    return responses
-
-
-@router.get(
-    "/skills",
-    response_model=SkillsListResponse,
-    summary="List All Skills",
-    description="Retrieve a list of all available skills from both public and custom directories.",
-)
-async def list_skills(
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-    tag_store: TagStore = Depends(get_tag_store),
-    search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
-    tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
-) -> SkillsListResponse:
-    try:
-        user_id = _current_user_id(request)
-        all_skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        ownership = await _build_ownership_index(skill_store, user_id)
-        responses: list[SkillResponse] = []
-        for skill in all_skills:
-            # Public/built-in skills (no DB row) are visible to everyone.
-            # Custom skills must have an ownership record in the visible set.
-            if skill.category != SkillCategory.CUSTOM:
-                # Built-in skills usually have no DB row, but an admin-authored
-                # ``detail`` annotation materializes one — surface it when present.
-                responses.append(_skill_to_response(skill, ownership.get(skill.name)))
-                continue
-            record = ownership.get(skill.name)
-            if record is None:
-                continue
-            responses.append(_skill_to_response(skill, record))
-        responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
-        return SkillsListResponse(skills=responses)
-    except Exception as e:
-        logger.error(f"Failed to load skills: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
-
-
-_MAX_SKILL_UPLOAD_BYTES = 512 * 1024 * 1024
-_ZIP_MAGIC = b"PK\x03\x04"
-
-
-async def _persist_uploaded_skill(file: UploadFile) -> Path:
-    """Stream an uploaded skill archive to a temp file. Caller must unlink it.
-
-    Validates the leading bytes look like a ZIP archive and enforces the same
-    512 MB cap that the extractor uses, so we reject obvious garbage early.
-    """
-    if file.filename is None:
-        raise HTTPException(status_code=400, detail="No file provided")
-    suffix = Path(file.filename).suffix.lower()
-    if suffix not in {".zip", ".skill"}:
-        raise HTTPException(status_code=400, detail="Skill upload must be a .zip or .skill file")
-
-    fd, tmp_name = tempfile.mkstemp(suffix=".skill", prefix="skill-upload-")
-    tmp_path = Path(tmp_name)
-    total = 0
-    head: bytes = b""
-    try:
-        with open(fd, "wb") as out:
-            while True:
-                chunk = await file.read(1024 * 1024)
-                if not chunk:
-                    break
-                if not head:
-                    head = chunk[: len(_ZIP_MAGIC)]
-                total += len(chunk)
-                if total > _MAX_SKILL_UPLOAD_BYTES:
-                    raise HTTPException(status_code=400, detail="Uploaded skill archive exceeds the 512 MB limit")
-                out.write(chunk)
-    except HTTPException:
-        tmp_path.unlink(missing_ok=True)
-        raise
-    except Exception:
-        tmp_path.unlink(missing_ok=True)
-        raise
-
-    if not head.startswith(_ZIP_MAGIC):
-        tmp_path.unlink(missing_ok=True)
-        raise HTTPException(status_code=400, detail="Uploaded file is not a valid ZIP archive")
-    return tmp_path
-
-
-@router.post(
-    "/skills/validate",
-    response_model=SkillUploadValidateResponse,
-    summary="Validate Skill Archive (No Install)",
-    description="Inspect an uploaded .zip/.skill archive and report parsed metadata + conflicts. Does NOT install or run the LLM security scan.",
-)
-async def validate_skill_upload(
-    file: UploadFile = File(..., description="The .zip or .skill archive to validate"),
-    config: AppConfig = Depends(get_config),
-) -> SkillUploadValidateResponse:
-    tmp_path = await _persist_uploaded_skill(file)
-    try:
-        result = get_or_new_skill_storage(app_config=config).validate_skill_archive(tmp_path)
-        return SkillUploadValidateResponse(**result)
-    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 HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to validate uploaded skill: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to validate skill: {e}")
-    finally:
-        tmp_path.unlink(missing_ok=True)
-
-
-@router.post(
-    "/skills/install-upload",
-    response_model=SkillInstallResponse,
-    summary="Install Skill from Upload",
-    description="Install a skill directly from an uploaded .zip/.skill archive. Set ?overwrite=true to replace an existing skill with the same name.",
-)
-async def install_skill_upload(
-    request: Request,
-    file: UploadFile = File(..., description="The .zip or .skill archive to install"),
-    overwrite: bool = False,
-    target_category: SkillCategory = SkillCategory.CUSTOM,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillInstallResponse:
-    user_id = _current_user_id(request)
-    is_admin = _is_admin_user(request)
-    # Only admins may install to the public (built-in) directory.
-    if target_category == SkillCategory.PUBLIC and not is_admin:
-        raise HTTPException(status_code=403, detail="Only admin users can install skills to the public directory")
-    tmp_path = await _persist_uploaded_skill(file)
-    try:
-        storage = get_or_new_skill_storage(app_config=config)
-        # Pre-parse the archive to learn the skill name without writing anything,
-        # so we can reject the upload before touching the filesystem if another
-        # user already owns this name. Admins bypass the ownership check since
-        # they install to the shared public directory.
-        try:
-            validation = storage.validate_skill_archive(tmp_path)
-            preview_name = validation.get("skill_name") if isinstance(validation, dict) else None
-        except Exception:
-            preview_name = None
-        if preview_name and not is_admin:
-            existing = await skill_store.get_any(preview_name)
-            if existing and existing.get("owner_user_id") not in (None, user_id):
-                raise HTTPException(
-                    status_code=409,
-                    detail=f"Skill '{preview_name}' already exists and is owned by another user",
-                )
-        result = await storage.ainstall_skill_from_archive(tmp_path, overwrite=overwrite, require_skill_suffix=False, target_category=target_category)
-        try:
-            from deerflow.skills.usage import mark_uploaded
-            mark_uploaded(result["skill_name"])
-        except Exception:
-            pass
-        # For public installs (admin), register as built-in with no owner.
-        # For custom installs, register ownership under the uploading user.
-        if target_category == SkillCategory.PUBLIC:
-            await skill_store.ensure_legacy(
-                {"name": result["skill_name"], "owner_user_id": None, "published": True}
-            )
-        else:
-            # ``ensure_legacy`` is idempotent and only patches a NULL owner; it
-            # never overwrites an existing owner, so the pre-parse check above
-            # is what really guards cross-user steals.
-            await skill_store.ensure_legacy(
-                {"name": result["skill_name"], "owner_user_id": user_id, "published": False}
-            )
-        await refresh_skills_system_prompt_cache_async()
-        return SkillInstallResponse(**result)
-    except FileNotFoundError as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except SkillAlreadyExistsError as e:
-        raise HTTPException(status_code=409, detail=str(e))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to install uploaded skill: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to install skill: {e}")
-    finally:
-        tmp_path.unlink(missing_ok=True)
-
-
-@router.post(
-    "/skills/install",
-    response_model=SkillInstallResponse,
-    summary="Install Skill",
-    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
-)
-async def install_skill(
-    body: SkillInstallRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillInstallResponse:
-    try:
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-        target_category = body.target_category
-        if target_category == SkillCategory.PUBLIC and not is_admin:
-            raise HTTPException(status_code=403, detail="Only admin users can install skills to the public directory")
-        skill_file_path = resolve_thread_virtual_path(body.thread_id, body.path)
-        result = await get_or_new_skill_storage(app_config=config).ainstall_skill_from_archive(skill_file_path, target_category=target_category)
-        try:
-            from deerflow.skills.usage import mark_uploaded
-            mark_uploaded(result["skill_name"])
-        except Exception:
-            pass
-        if target_category == SkillCategory.PUBLIC:
-            await skill_store.ensure_legacy(
-                {"name": result["skill_name"], "owner_user_id": None, "published": True}
-            )
-        else:
-            await skill_store.ensure_legacy(
-                {"name": result["skill_name"], "owner_user_id": user_id, "published": False}
-            )
-        await refresh_skills_system_prompt_cache_async()
-        return SkillInstallResponse(**result)
-    except FileNotFoundError as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except SkillAlreadyExistsError as e:
-        raise HTTPException(status_code=409, detail=str(e))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to install skill: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")
-
-
-@router.post(
-    "/skills/reconcile-custom",
-    response_model=SkillReconcileResponse,
-    summary="Adopt Orphan Custom Skills",
-    description=(
-        "Scan the on-disk ``skills/custom/`` directory and register any skill that has a "
-        "valid SKILL.md but no DB ownership row. Adopted skills are recorded as owned by "
-        "the calling user with ``published=false``. Skips skills that already have a row "
-        "(regardless of owner). Useful after manually unzipping skills onto the filesystem."
-    ),
-)
-async def reconcile_custom_skills(
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillReconcileResponse:
-    try:
-        user_id = _current_user_id(request)
-        storage = get_or_new_skill_storage(app_config=config)
-        custom_skills = [s for s in storage.load_skills(enabled_only=False) if s.category == SkillCategory.CUSTOM]
-
-        adopted: list[str] = []
-        already: list[str] = []
-        for skill in custom_skills:
-            existing = await skill_store.get_any(skill.name)
-            if existing is not None:
-                already.append(skill.name)
-                continue
-            await skill_store.ensure_legacy(
-                {"name": skill.name, "owner_user_id": user_id, "published": False}
-            )
-            try:
-                from deerflow.skills.usage import mark_uploaded
-                mark_uploaded(skill.name)
-            except Exception:
-                pass
-            adopted.append(skill.name)
-
-        if adopted:
-            await refresh_skills_system_prompt_cache_async()
-        return SkillReconcileResponse(adopted=adopted, already_registered=already)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to reconcile custom skills: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to reconcile custom skills: {e}")
-
-
-@router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
-async def list_custom_skills(
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillsListResponse:
-    try:
-        user_id = _current_user_id(request)
-        custom = [s for s in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if s.category == SkillCategory.CUSTOM]
-        ownership = await _build_ownership_index(skill_store, user_id)
-        responses = [
-            _skill_to_response(skill, ownership[skill.name])
-            for skill in custom
-            if skill.name in ownership
-        ]
-        return SkillsListResponse(skills=responses)
-    except Exception as e:
-        logger.error("Failed to list custom skills: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to list custom skills: {str(e)}")
-
-
-@router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
-async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name and s.category == SkillCategory.CUSTOM), None)
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to get custom skill %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get custom skill: {str(e)}")
-
-
-@router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
-async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        storage = get_or_new_skill_storage(app_config=config)
-        storage.ensure_custom_skill_is_editable(skill_name)
-        storage.validate_skill_markdown_content(skill_name, request.content)
-        scan = await scan_skill_content(request.content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
-        if scan.decision == "block":
-            raise HTTPException(status_code=400, detail=f"Security scan blocked the edit: {scan.reason}")
-        prev_content = storage.read_custom_skill(skill_name)
-        storage.write_custom_skill(skill_name, SKILL_MD_FILE, request.content)
-        storage.append_history(
-            skill_name,
-            {
-                "action": "human_edit",
-                "author": "human",
-                "thread_id": None,
-                "file_path": SKILL_MD_FILE,
-                "prev_content": prev_content,
-                "new_content": request.content,
-                "scanner": {"decision": scan.decision, "reason": scan.reason},
-            },
-        )
-        try:
-            from deerflow.skills.usage import bump_patch
-            bump_patch(skill_name)
-        except Exception:
-            pass
-        await refresh_skills_system_prompt_cache_async()
-        return await get_custom_skill(skill_name, config)
-    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 update custom skill %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update custom skill: {str(e)}")
-
-
-@router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
-async def delete_custom_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:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-        record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
-        operation = "admin_takedown" if mode == "admin" and record.get("owner_user_id") not in (None, user_id) else "delete"
-
-        storage = get_or_new_skill_storage(app_config=config)
-        storage.delete_custom_skill(
-            skill_name,
-            history_meta={
-                "action": "human_delete",
-                "author": "human",
-                "thread_id": None,
-                "file_path": SKILL_MD_FILE,
-                "prev_content": None,
-                "new_content": None,
-                "scanner": {"decision": "allow", "reason": "Deletion requested."},
-            },
-        )
-        try:
-            from deerflow.skills.usage import forget
-            forget(skill_name)
-        except Exception:
-            pass
-
-        # Persist ownership record removal so the DB stays consistent.
-        if mode == "admin":
-            await skill_store.delete_admin(skill_name)
-        else:
-            await skill_store.delete(skill_name, user_id)
-
-        try:
-            await get_tag_store(request).unassign_all("skill", skill_name)
-        except Exception:  # noqa: BLE001 — tag cleanup must not block deletion
-            pass
-
-        # Strip references from every agent that pulled this skill in,
-        # and notify their owners (no-op for self).
-        await cascade_skill_unpublished_or_deleted(
-            skill_name,
-            actor_user_id=user_id,
-            operation=operation,
-            skill_owner_user_id=record.get("owner_user_id"),
-            agent_store=agent_store,
-        )
-
-        await refresh_skills_system_prompt_cache_async()
-        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 custom skill %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to delete custom skill: {str(e)}")
-
-
-class SkillPublishRequest(BaseModel):
-    """Request body for toggling a custom skill's published flag."""
-
-    published: bool = Field(..., description="Whether to publish (True) or unpublish (False)")
-
-
-class SkillPublishResponse(BaseModel):
-    name: str
-    owner_user_id: str | None
-    published: bool
-
-
-@router.put(
-    "/skills/custom/{skill_name}/published",
-    response_model=SkillPublishResponse,
-    summary="Toggle Custom Skill Published State",
-)
-async def update_custom_skill_published(
-    skill_name: str,
-    body: SkillPublishRequest,
-    request: Request,
-    skill_store: SkillStore = Depends(get_skill_store),
-    agent_store=Depends(get_agent_store),
-) -> SkillPublishResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-        record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
-
-        was_published = bool(record.get("published", False))
-        if mode == "admin":
-            updated = await skill_store.update_admin(skill_name, {"published": body.published})
-        else:
-            updated = await skill_store.update(skill_name, user_id, {"published": body.published})
-        if updated is None:
-            raise HTTPException(status_code=500, detail="Failed to persist published state")
-
-        # If we are *removing* visibility (was published, now not), strip from
-        # other users' agents and notify them. admin takedown is signaled by
-        # the actor not being the owner.
-        if was_published and not body.published:
-            skill_owner = record.get("owner_user_id")
-            operation = "admin_takedown" if mode == "admin" and skill_owner not in (None, user_id) else "unpublish"
-            await cascade_skill_unpublished_or_deleted(
-                skill_name,
-                actor_user_id=user_id,
-                operation=operation,
-                skill_owner_user_id=skill_owner,
-                agent_store=agent_store,
-            )
-            await refresh_skills_system_prompt_cache_async()
-
-        return SkillPublishResponse(
-            name=updated["name"],
-            owner_user_id=updated.get("owner_user_id"),
-            published=bool(updated.get("published", False)),
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update published state for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update published state: {str(e)}")
-
-
-_ALLOWED_USER_STATES = {"active", "archived"}
-
-
-class SkillStateRequest(BaseModel):
-    """Request body for switching a custom skill's lifecycle state."""
-
-    state: str = Field(..., description="New state: 'active' (restore) or 'archived' (soft archive)")
-
-
-class SkillPinRequest(BaseModel):
-    """Request body for pinning / unpinning a custom skill."""
-
-    pinned: bool = Field(..., description="Whether to pin (true) so the curator never auto-archives this skill")
-
-
-def _reload_skill_response(skill_name: str, ownership: dict[str, Any], config: AppConfig) -> SkillResponse:
-    """Reload a single skill from disk and return its API response form."""
-    skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-    skill = next((s for s in skills if s.name == skill_name), None)
-    if skill is None:
-        raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found on disk")
-    return _skill_to_response(skill, ownership)
-
-
-@router.put(
-    "/skills/custom/{skill_name}/state",
-    response_model=SkillResponse,
-    summary="Update Custom Skill Lifecycle State",
-    description="Restore (active) or soft-archive a custom skill. Only the owner or admins may invoke.",
-)
-async def update_custom_skill_state(
-    skill_name: str,
-    body: SkillStateRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        if body.state not in _ALLOWED_USER_STATES:
-            raise HTTPException(
-                status_code=400,
-                detail=f"state must be one of {sorted(_ALLOWED_USER_STATES)}",
-            )
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-        record, _mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
-
-        from deerflow.skills.usage import set_state as _usage_set_state
-
-        _usage_set_state(skill_name, body.state)
-        await refresh_skills_system_prompt_cache_async()
-        return _reload_skill_response(skill_name, record, config)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update state for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update state: {e}")
-
-
-@router.put(
-    "/skills/custom/{skill_name}/pinned",
-    response_model=SkillResponse,
-    summary="Pin or Unpin a Custom Skill",
-    description="Pin a skill so the curator never auto-archives it. Only the owner or admins may invoke.",
-)
-async def update_custom_skill_pinned(
-    skill_name: str,
-    body: SkillPinRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-        record, _mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
-
-        from deerflow.skills.usage import set_pinned as _usage_set_pinned
-
-        _usage_set_pinned(skill_name, body.pinned)
-        return _reload_skill_response(skill_name, record, config)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update pinned for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update pinned: {e}")
-
-
-@router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
-async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        storage = get_or_new_skill_storage(app_config=config)
-        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
-            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        return CustomSkillHistoryResponse(history=storage.read_history(skill_name))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to read history for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to read history: {str(e)}")
-
-
-@router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
-async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
-    try:
-        storage = get_or_new_skill_storage(app_config=config)
-        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
-            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        history = storage.read_history(skill_name)
-        if not history:
-            raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
-        record = history[request.history_index]
-        target_content = record.get("prev_content")
-        if target_content is None:
-            raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
-        storage.validate_skill_markdown_content(skill_name, target_content)
-        scan = await scan_skill_content(target_content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
-        skill_file = storage.get_custom_skill_file(skill_name)
-        current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
-        history_entry = {
-            "action": "rollback",
-            "author": "human",
-            "thread_id": None,
-            "file_path": SKILL_MD_FILE,
-            "prev_content": current_content,
-            "new_content": target_content,
-            "rollback_from_ts": record.get("ts"),
-            "scanner": {"decision": scan.decision, "reason": scan.reason},
-        }
-        if scan.decision == "block":
-            storage.append_history(skill_name, history_entry)
-            raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
-        storage.write_custom_skill(skill_name, SKILL_MD_FILE, target_content)
-        storage.append_history(skill_name, history_entry)
-        await refresh_skills_system_prompt_cache_async()
-        return await get_custom_skill(skill_name, config)
-    except HTTPException:
-        raise
-    except IndexError:
-        raise HTTPException(status_code=400, detail="history_index is out of range")
-    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 roll back custom skill %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to roll back custom skill: {str(e)}")
-
-
-@router.get(
-    "/skills/{skill_name}",
-    response_model=SkillResponse,
-    summary="Get Skill Details",
-    description="Retrieve detailed information about a specific skill by its name.",
-)
-async def get_skill(
-    skill_name: str,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        # Attach ownership (owner/published/detail) when the caller may see it.
-        ownership = await skill_store.get_visible(skill_name, _current_user_id(request))
-        return _skill_to_response(skill, ownership)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to get skill {skill_name}: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get skill: {str(e)}")
-
-
-class SkillContentResponse(BaseModel):
-    """SKILL.md 原文内容,适用于公共和自定义技能。"""
-
-    name: str
-    category: SkillCategory
-    content: str
-
-
-@router.get(
-    "/skills/{skill_name}/content",
-    response_model=SkillContentResponse,
-    summary="Get Skill Markdown Content",
-    description="Retrieve the raw SKILL.md content of a skill. Only an admin or the skill's publisher (owner of a custom skill) may read it; other users see only the description and detail.",
-)
-async def get_skill_content(
-    skill_name: str,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillContentResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-        # The raw SKILL.md is implementation detail — only an admin or the
-        # publisher (owner of a custom skill) may view it. Everyone else is
-        # limited to the description + detail surfaced by the list/detail APIs.
-        record = await skill_store.get_any(skill_name)
-        owner_user_id = record.get("owner_user_id") if record else None
-        if not _can_view_skill_source(skill.category, owner_user_id, _current_user_id(request), is_admin=_is_admin_user(request)):
-            raise HTTPException(status_code=403, detail="Only the skill publisher or an admin can view the SKILL.md source")
-        content = skill.skill_file.read_text(encoding="utf-8")
-        return SkillContentResponse(name=skill.name, category=skill.category, content=content)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to get skill content %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get skill content: {str(e)}")
-
-
-# ---------------------------------------------------------------------------
-# Skill files browser (tree + per-file read / write)
-# ---------------------------------------------------------------------------
-
-
-_SKILL_FILE_TEXT_EXTS = {
-    ".md", ".markdown", ".txt", ".rst",
-    ".py", ".pyi",
-    ".json", ".jsonl",
-    ".yaml", ".yml",
-    ".toml", ".ini", ".cfg", ".env",
-    ".sh", ".bash", ".zsh", ".ps1",
-    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
-    ".html", ".htm", ".css", ".scss", ".sass", ".xml", ".svg",
-    ".csv", ".tsv",
-    ".sql",
-}
-_SKILL_FILE_TREE_SKIP_NAMES = {
-    "__pycache__", "node_modules", ".git", ".DS_Store", ".idea", ".vscode",
-}
-_SKILL_FILE_MAX_NODES = 2000
-_SKILL_FILE_MAX_DEPTH = 8
-_SKILL_FILE_READ_BYTES = 2 * 1024 * 1024   # 2 MiB cap on JSON content payload
-_SKILL_FILE_WRITE_BYTES = 1 * 1024 * 1024  # 1 MiB cap on edits
-
-
-class SkillFileNode(BaseModel):
-    """One entry in a skill's file tree.
-
-    ``children`` is only set for directories. ``path`` is POSIX-style and is
-    always relative to the skill's own directory (never absolute).
-    """
-
-    name: str = Field(..., description="Base name (no slashes)")
-    type: str = Field(..., description="'file' or 'dir'")
-    path: str = Field(..., description="Path relative to the skill directory, POSIX-separated")
-    size: int | None = Field(default=None, description="File size in bytes (files only)")
-    mtime: float | None = Field(default=None, description="Modification time as POSIX seconds (files only)")
-    children: list["SkillFileNode"] | None = Field(default=None, description="Child entries (directories only)")
-
-
-SkillFileNode.model_rebuild()
-
-
-class SkillFilesResponse(BaseModel):
-    """Tree of files under a skill directory."""
-
-    name: str
-    category: SkillCategory
-    editable: bool = Field(..., description="True when the caller may PUT new content into any file under this tree")
-    root: SkillFileNode
-
-
-class SkillFileContentResponse(BaseModel):
-    """JSON payload for reading a single file inside a skill."""
-
-    name: str
-    category: SkillCategory
-    path: str
-    mime: str
-    size: int
-    mtime: float
-    is_text: bool = Field(..., description="True when ``content`` carries the decoded text; otherwise download via the binary endpoint")
-    editable: bool = Field(..., description="True when the caller may PUT new content for this file")
-    content: str | None = Field(default=None, description="Decoded text content when ``is_text`` is True")
-
-
-class SkillFileSaveRequest(BaseModel):
-    """Request body for writing a text file inside a skill."""
-
-    path: str = Field(..., description="File path relative to the skill directory, POSIX-separated")
-    content: str = Field(..., description="Replacement text content")
-
-
-class SkillFileSaveResponse(BaseModel):
-    name: str
-    path: str
-    size: int
-    mtime: float
-
-
-def _normalize_skill_name_param(skill_name: str) -> str:
-    """Strip CR/LF the same way other skill routes do before lookup."""
-    return skill_name.replace("\r\n", "").replace("\n", "")
-
-
-def _load_skill_or_404(skill_name: str, config: AppConfig) -> Skill:
-    skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-    skill = next((s for s in skills if s.name == skill_name), None)
-    if skill is None:
-        raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-    return skill
-
-
-async def _ensure_files_view_allowed(
-    skill: Skill,
-    request: Request,
-    skill_store: SkillStore,
-) -> dict[str, Any] | None:
-    """Mirror _can_view_skill_source: admins or the publisher (custom owner)."""
-    record = await skill_store.get_any(skill.name)
-    owner_user_id = record.get("owner_user_id") if record else None
-    user_id = _current_user_id(request)
-    if not _can_view_skill_source(skill.category, owner_user_id, user_id, is_admin=_is_admin_user(request)):
-        raise HTTPException(status_code=403, detail="Only the skill publisher or an admin can browse skill files")
-    return record
-
-
-def _caller_can_edit_skill_files(
-    skill: Skill,
-    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
-    if _is_admin_user(request):
-        return True
-    if record is None:
-        return False
-    return record.get("owner_user_id") == _current_user_id(request)
-
-
-def _resolve_skill_relative_path(skill: Skill, relative_path: str) -> Path:
-    """Validate *relative_path* against the skill directory and return the absolute Path.
-
-    Rejects empty, absolute, parent-traversing, or out-of-tree paths so a
-    malicious caller can never escape the skill's own directory.
-    """
-    if not relative_path or relative_path.strip() == "":
-        raise HTTPException(status_code=400, detail="path must not be empty")
-    candidate = Path(relative_path)
-    if candidate.is_absolute() or any(part in {"..", ""} for part in candidate.parts):
-        raise HTTPException(status_code=400, detail="path must be a relative path without '..' segments")
-    skill_dir = skill.skill_file.parent.resolve()
-    target = (skill_dir / candidate).resolve()
-    try:
-        target.relative_to(skill_dir)
-    except ValueError:
-        raise HTTPException(status_code=400, detail="path must stay inside the skill directory")
-    return target
-
-
-def _file_mime(path: Path) -> str:
-    """Best-effort MIME guess; defaults to ``application/octet-stream``."""
-    guessed, _ = mimetypes.guess_type(path.name)
-    if guessed:
-        return guessed
-    if path.suffix.lower() in _SKILL_FILE_TEXT_EXTS:
-        return "text/plain"
-    return "application/octet-stream"
-
-
-def _is_text_file(path: Path) -> bool:
-    """Treat known text extensions as text; everything else as binary."""
-    return path.suffix.lower() in _SKILL_FILE_TEXT_EXTS
-
-
-def _build_skill_file_tree(skill_dir: Path) -> SkillFileNode:
-    """Walk *skill_dir* and build a SkillFileNode tree, depth/count capped.
-
-    Hidden files (``.foo``) and a small block-list of noise directories
-    (``__pycache__`` etc.) are skipped so the UI does not drown in housekeeping
-    artefacts.
-    """
-    counter = {"n": 0}
-
-    def build(current_dir: Path, depth: int) -> SkillFileNode:
-        rel = current_dir.relative_to(skill_dir).as_posix()
-        node = SkillFileNode(
-            name=current_dir.name if rel != "." else skill_dir.name,
-            type="dir",
-            path="" if rel == "." else rel,
-            children=[],
-        )
-        if depth >= _SKILL_FILE_MAX_DEPTH:
-            return node
-        try:
-            entries = sorted(current_dir.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
-        except OSError:
-            return node
-        for entry in entries:
-            if counter["n"] >= _SKILL_FILE_MAX_NODES:
-                break
-            if entry.name.startswith(".") or entry.name in _SKILL_FILE_TREE_SKIP_NAMES:
-                continue
-            counter["n"] += 1
-            if entry.is_dir():
-                node.children.append(build(entry, depth + 1))
-                continue
-            try:
-                stat = entry.stat()
-                size = stat.st_size
-                mtime = stat.st_mtime
-            except OSError:
-                size = 0
-                mtime = 0.0
-            node.children.append(
-                SkillFileNode(
-                    name=entry.name,
-                    type="file",
-                    path=entry.relative_to(skill_dir).as_posix(),
-                    size=size,
-                    mtime=mtime,
-                )
-            )
-        return node
-
-    return build(skill_dir, 0)
-
-
-@router.get(
-    "/skills/{skill_name}/files",
-    response_model=SkillFilesResponse,
-    summary="List Skill Files (Tree)",
-    description=(
-        "Return the full file tree under a skill directory. Only an admin or the "
-        "skill's publisher (owner of a custom skill) may browse files; other users "
-        "get 403."
-    ),
-)
-async def list_skill_files(
-    skill_name: str,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillFilesResponse:
-    try:
-        skill_name = _normalize_skill_name_param(skill_name)
-        skill = _load_skill_or_404(skill_name, config)
-        record = await _ensure_files_view_allowed(skill, request, skill_store)
-        skill_dir = skill.skill_file.parent
-        root = _build_skill_file_tree(skill_dir)
-        return SkillFilesResponse(
-            name=skill.name,
-            category=skill.category,
-            editable=_caller_can_edit_skill_files(skill, record, request),
-            root=root,
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to list skill files for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to list skill files: {e}")
-
-
-@router.get(
-    "/skills/{skill_name}/files/content",
-    response_model=SkillFileContentResponse,
-    summary="Read Skill File (Text)",
-    description=(
-        "Return JSON metadata for a single file under a skill. Text files include "
-        "their decoded ``content``; binary files omit ``content`` and should be "
-        "fetched from the ``files/download`` endpoint for inline display or "
-        "download. Same view authorisation as the file tree endpoint."
-    ),
-)
-async def get_skill_file_content(
-    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),
-) -> SkillFileContentResponse:
-    try:
-        skill_name = _normalize_skill_name_param(skill_name)
-        skill = _load_skill_or_404(skill_name, config)
-        record = await _ensure_files_view_allowed(skill, request, skill_store)
-        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}'")
-        stat = target.stat()
-        mime = _file_mime(target)
-        is_text = _is_text_file(target)
-        content: str | None = None
-        if is_text:
-            if stat.st_size > _SKILL_FILE_READ_BYTES:
-                raise HTTPException(status_code=413, detail=f"File exceeds the {_SKILL_FILE_READ_BYTES // 1024} KiB preview limit")
-            try:
-                content = target.read_text(encoding="utf-8")
-            except UnicodeDecodeError:
-                # File has a text-y extension but is not UTF-8 — treat as binary.
-                is_text = False
-        return SkillFileContentResponse(
-            name=skill.name,
-            category=skill.category,
-            path=target.relative_to(skill.skill_file.parent.resolve()).as_posix(),
-            mime=mime,
-            size=stat.st_size,
-            mtime=stat.st_mtime,
-            is_text=is_text,
-            editable=is_text and _caller_can_edit_skill_files(skill, record, request),
-            content=content,
-        )
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to read skill file %s/%s: %s", skill_name, path, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to read skill file: {e}")
-
-
-@router.get(
-    "/skills/{skill_name}/files/download",
-    summary="Download Skill File (Raw Bytes)",
-    description=(
-        "Stream the raw bytes of a single file under a skill, suitable for "
-        "embedding in an ``<img>`` tag or for direct download. Same view "
-        "authorisation as the file tree endpoint."
-    ),
-)
-async def download_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),
-):
-    skill_name = _normalize_skill_name_param(skill_name)
-    skill = _load_skill_or_404(skill_name, config)
-    await _ensure_files_view_allowed(skill, request, skill_store)
-    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}'")
-    return FileResponse(
-        path=target,
-        media_type=_file_mime(target),
-        filename=target.name,
-    )
-
-
-@router.put(
-    "/skills/{skill_name}/files/content",
-    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 "
-        "refresh the system-prompt cache."
-    ),
-)
-async def save_skill_file(
-    skill_name: str,
-    body: SkillFileSaveRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillFileSaveResponse:
-    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")
-
-        target = _resolve_skill_relative_path(skill, body.path)
-        if not target.exists():
-            raise HTTPException(status_code=404, detail=f"File '{body.path}' not found in skill '{skill_name}'")
-        if target.is_dir():
-            raise HTTPException(status_code=400, detail="path points to a directory")
-        if not _is_text_file(target):
-            raise HTTPException(status_code=400, detail=f"File type '{target.suffix or target.name}' is not editable")
-
-        if len(body.content.encode("utf-8")) > _SKILL_FILE_WRITE_BYTES:
-            raise HTTPException(status_code=413, detail=f"Content exceeds the {_SKILL_FILE_WRITE_BYTES // 1024} KiB edit limit")
-
-        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
-        prev_content: str | None = None
-        if target.exists():
-            try:
-                prev_content = target.read_text(encoding="utf-8")
-            except UnicodeDecodeError:
-                prev_content = None
-
-        if is_skill_md:
-            # 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)
-
-        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,
-                },
-            )
-        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)
-
-        if is_skill_md:
-            try:
-                from deerflow.skills.usage import bump_patch
-                bump_patch(skill.name)
-            except Exception:
-                pass
-            await refresh_skills_system_prompt_cache_async()
-
-        stat = target.stat()
-        return SkillFileSaveResponse(
-            name=skill.name,
-            path=relative_posix,
-            size=stat.st_size,
-            mtime=stat.st_mtime,
-        )
-    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 save skill file %s/%s: %s", skill_name, body.path, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to save skill file: {e}")
-
-
-@router.put(
-    "/skills/{skill_name}",
-    response_model=SkillResponse,
-    summary="Update Skill",
-    description="Update a skill's enabled status by modifying the extensions_config.json file.",
-)
-async def update_skill(skill_name: str, request: SkillUpdateRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        config_path = ExtensionsConfig.resolve_config_path()
-        if config_path is None:
-            config_path = Path.cwd().parent / "extensions_config.json"
-            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
-
-        extensions_config = get_extensions_config()
-        current_skill_config = extensions_config.skills.get(skill_name)
-        extensions_config.skills[skill_name] = SkillStateConfig(
-            enabled=request.enabled,
-            display=current_skill_config.display if current_skill_config else None,
-        )
-
-        config_data = _dump_extensions_config(extensions_config)
-
-        with open(config_path, "w", encoding="utf-8") as f:
-            json.dump(config_data, f, indent=2)
-
-        logger.info(f"Skills configuration updated and saved to: {config_path}")
-        reload_extensions_config()
-        await refresh_skills_system_prompt_cache_async()
-
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        updated_skill = next((s for s in skills if s.name == skill_name), None)
-
-        if updated_skill is None:
-            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after update")
-
-        logger.info(f"Skill '{skill_name}' enabled status updated to {request.enabled}")
-        return _skill_to_response(updated_skill)
-
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error(f"Failed to update skill {skill_name}: {e}", exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
-
-
-@router.put(
-    "/skills/{skill_name}/display",
-    response_model=SkillResponse,
-    summary="Update Skill Display Adapter",
-    description="Update a skill's frontend display adapter in extensions_config.json.",
-)
-async def update_skill_display(
-    skill_name: str,
-    request: SkillDisplayUpdateRequest,
-    config: AppConfig = Depends(get_config),
-) -> SkillResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        config_path = ExtensionsConfig.resolve_config_path()
-        if config_path is None:
-            config_path = Path.cwd().parent / "extensions_config.json"
-            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
-
-        extensions_config = get_extensions_config()
-        current_skill_config = extensions_config.skills.get(skill_name)
-        extensions_config.skills[skill_name] = SkillStateConfig(
-            enabled=current_skill_config.enabled if current_skill_config else skill.enabled,
-            display=request.display,
-        )
-
-        with open(config_path, "w", encoding="utf-8") as f:
-            json.dump(_dump_extensions_config(extensions_config), f, indent=2, ensure_ascii=False)
-
-        reload_extensions_config()
-        await refresh_skills_system_prompt_cache_async()
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        updated_skill = next((s for s in skills if s.name == skill_name), None)
-        if updated_skill is None:
-            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after display update")
-        return _skill_to_response(updated_skill)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update display adapter for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update skill display adapter: {str(e)}")
-
-
-@router.post(
-    "/skills/{skill_name}/display-sample",
-    response_model=SkillDisplaySampleResponse,
-    summary="Get Skill Display Sample",
-    description="Return a structured sample response used by the frontend to infer display mapping.",
-)
-async def get_skill_display_sample(
-    skill_name: str,
-    config: AppConfig = Depends(get_config),
-) -> SkillDisplaySampleResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-        sample = await _generate_skill_display_sample(skill, config)
-        return SkillDisplaySampleResponse(skill_name=skill_name, sample=sample)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to get display sample for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get display sample: {str(e)}")
-
-
-class SkillDetailRequest(BaseModel):
-    """Request body for setting a skill's human-authored detail text."""
-
-    detail: str = Field(default="", description="详情说明文本,支持 Markdown;传空字符串表示清空")
-
-
-class SkillDetailResponse(BaseModel):
-    """Response model for the skill-detail update endpoint."""
-
-    name: str = Field(..., description="Skill name")
-    detail: str | None = Field(default=None, description="Persisted detail text (null when cleared)")
-
-
-@router.put(
-    "/skills/{skill_name}/detail",
-    response_model=SkillDetailResponse,
-    summary="Update Skill Detail",
-    description="设置技能的详情说明。自定义技能由其所有者或管理员编辑;内置/公开技能仅管理员可编辑。",
-)
-async def update_skill_detail(
-    skill_name: str,
-    body: SkillDetailRequest,
-    request: Request,
-    config: AppConfig = Depends(get_config),
-    skill_store: SkillStore = Depends(get_skill_store),
-) -> SkillDetailResponse:
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        user_id = _current_user_id(request)
-        is_admin = _is_admin_user(request)
-
-        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-
-        # Empty / whitespace-only input clears the annotation.
-        detail_value: str | None = body.detail.strip() or None
-
-        if skill.category == SkillCategory.CUSTOM:
-            # Owner edits their own skill; admins may edit anyone's.
-            _record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
-            if mode == "admin":
-                updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
-            else:
-                updated = await skill_store.update(skill_name, user_id, {"detail": detail_value})
-        else:
-            # Built-in / public skill — only admins may annotate it. These carry
-            # no DB row by default, so materialize one before writing detail.
-            if not is_admin:
-                raise HTTPException(status_code=403, detail="Only admin users can edit built-in skill details")
-            if await skill_store.get_any(skill_name) is None:
-                await skill_store.ensure_legacy({"name": skill_name, "owner_user_id": None, "published": True})
-            updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
-
-        if updated is None:
-            raise HTTPException(status_code=500, detail="Failed to persist skill detail")
-        return SkillDetailResponse(name=skill_name, detail=updated.get("detail"))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update detail for %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update skill detail: {str(e)}")
-
-
-class SkillPinRequest(BaseModel):
-    pinned: bool = Field(..., description="Whether to pin or unpin the skill")
-
-
-@router.post("/skills/custom/{skill_name}/pin", response_model=SkillResponse, summary="Pin or Unpin Skill")
-async def pin_skill(skill_name: str, request: SkillPinRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
-    """Pin a skill to prevent it from being automatically archived by the curator."""
-    try:
-        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
-        storage = get_or_new_skill_storage(app_config=config)
-        if not storage.custom_skill_exists(skill_name):
-            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        from deerflow.skills.usage import set_pinned
-        set_pinned(skill_name, request.pinned)
-        skills = storage.load_skills(enabled_only=False)
-        skill = next((s for s in skills if s.name == skill_name), None)
-        if skill is None:
-            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-        return _skill_to_response(skill)
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to pin skill %s: %s", skill_name, e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to pin skill: {str(e)}")
-
-
-@router.get("/curator/status", summary="Curator Status")
-async def curator_status(request: Request) -> dict:
-    """Return the current curator state and per-lifecycle skill counts for the
-    authenticated user."""
-    try:
-        from deerflow.skills.curator import get_curator_status
-        return get_curator_status(_current_user_id(request))
-    except Exception as e:
-        logger.error("Failed to get curator status: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to get curator status: {str(e)}")
-
-
-@router.post("/curator/run", summary="Trigger Curator Run")
-async def run_curator(request: Request) -> dict:
-    """Manually trigger a curator review pass for the authenticated user
-    (bypasses the interval check, runs in a background thread).
-
-    Pre-checks the master switch / curator switch / run lock so the response
-    accurately reflects whether a run actually started — instead of always
-    reporting success. Returns ``{"triggered": bool, "reason": str | None}``.
-    """
-    try:
-        import threading
-
-        from deerflow.skills.curator import _curator_thread_target, manual_trigger_blocked_reason
-
-        user_id = _current_user_id(request)
-        reason = manual_trigger_blocked_reason(user_id)
-        if reason is not None:
-            return {"triggered": False, "reason": reason}
-        thread = threading.Thread(
-            target=_curator_thread_target,
-            args=(user_id,),
-            daemon=True,
-            name=f"skill-curator-manual-{user_id}",
-        )
-        thread.start()
-        return {"triggered": True, "reason": None}
-    except Exception as e:
-        logger.error("Failed to trigger curator: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to trigger curator: {str(e)}")
-
-
-class CuratorSubConfig(BaseModel):
-    """Nested curator configuration mirroring CuratorConfig."""
-
-    # 与 CuratorConfig.enabled 保持一致:默认关闭,需显式 opt-in。
-    enabled: bool = Field(default=False, description="Whether the curator runs automatically.")
-    interval_hours: int = Field(default=168, ge=1, description="Hours between curator runs.")
-    stale_after_days: int = Field(default=30, ge=1, description="Days of inactivity before a skill is marked stale.")
-    archive_after_days: int = Field(default=90, ge=1, description="Days of inactivity before a stale skill is archived.")
-    review_timeout_seconds: int = Field(default=600, ge=1, description="Overall timeout (seconds) for the LLM review pass.")
-    model_name: str | None = Field(default=None, description="Model name for the curator LLM review pass; null = primary model.")
-
-
-class CuratorConfigResponse(BaseModel):
-    """Response model exposing the effective skill_evolution config."""
-
-    enabled: bool
-    curator: CuratorSubConfig
-
-
-class CuratorConfigRequest(BaseModel):
-    """Payload for updating skill_evolution overrides.
-
-    All fields are required so the frontend always sends a complete config;
-    backend writes the entire payload to skill_evolution.json atomically.
-    """
-
-    enabled: bool = Field(..., description="Whether the agent can create and modify skills under skills/custom.")
-    curator: CuratorSubConfig
-
-
-class CuratorLogRecord(BaseModel):
-    ts: str
-    level: str
-    message: str
-
-
-class CuratorLogsResponse(BaseModel):
-    records: list[CuratorLogRecord]
-    run_count: int
-    last_run_at: str | None
-
-
-def _build_curator_config_response(evo) -> CuratorConfigResponse:
-    """Pure helper so both the GET route and the post-PUT refresh share one shape.
-
-    ``evo`` is a ``SkillEvolutionConfig`` instance (already merged with per-user
-    overrides if any).
-    """
-    return CuratorConfigResponse(
-        enabled=evo.enabled,
-        curator=CuratorSubConfig(
-            enabled=evo.curator.enabled,
-            interval_hours=evo.curator.interval_hours,
-            stale_after_days=evo.curator.stale_after_days,
-            archive_after_days=evo.curator.archive_after_days,
-            review_timeout_seconds=evo.curator.review_timeout_seconds,
-            model_name=evo.curator.model_name,
-        ),
-    )
-
-
-@router.get("/curator/config", response_model=CuratorConfigResponse, summary="Get Skill Evolution Config")
-async def get_curator_config(request: Request) -> CuratorConfigResponse:
-    """Return the current curator config for the authenticated user (yaml
-    defaults + that user's overrides)."""
-    try:
-        from deerflow.config.skill_evolution_runtime import load_skill_evolution_config_for_user
-
-        evo = load_skill_evolution_config_for_user(_current_user_id(request))
-        return _build_curator_config_response(evo)
-    except Exception as e:
-        logger.error("Failed to read curator config: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to read curator config: {str(e)}")
-
-
-@router.put("/curator/config", response_model=CuratorConfigResponse, summary="Update Skill Evolution Config")
-async def update_curator_config(body: CuratorConfigRequest, request: Request) -> CuratorConfigResponse:
-    """Persist per-user overrides to ``users/{user_id}/skill_evolution.json``
-    and return the effective merged config.
-
-    The payload is validated against the ``SkillEvolutionConfig`` shape; unknown
-    fields are rejected.
-    """
-    try:
-        from deerflow.config.skill_evolution_config import SkillEvolutionConfig
-        from deerflow.config.skill_evolution_runtime import load_skill_evolution_config_for_user, save_user_overrides
-
-        user_id = _current_user_id(request)
-        payload = body.model_dump()
-        # Round-trip through SkillEvolutionConfig to ensure persisted shape stays valid.
-        SkillEvolutionConfig.model_validate(payload)
-        save_user_overrides(user_id, payload)
-        return _build_curator_config_response(load_skill_evolution_config_for_user(user_id))
-    except HTTPException:
-        raise
-    except Exception as e:
-        logger.error("Failed to update curator config: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to update curator config: {str(e)}")
-
-
-@router.get("/curator/logs", response_model=CuratorLogsResponse, summary="Recent Curator Logs")
-async def get_curator_logs(request: Request) -> CuratorLogsResponse:
-    """Return in-memory log records from the most recent curator run for the
-    authenticated user.
-
-    The buffer is process-local and cleared when curator starts a new run or
-    when the backend restarts. Records are ordered oldest → newest.
-    """
-    try:
-        from deerflow.skills import curator_log
-        from deerflow.skills.curator import get_curator_status
-
-        user_id = _current_user_id(request)
-        records = curator_log.get_recent(user_id)
-        status = get_curator_status(user_id)
-        return CuratorLogsResponse(
-            records=[CuratorLogRecord(**r) for r in records],
-            run_count=int(status.get("run_count", 0)),
-            last_run_at=status.get("last_run_at"),
-        )
-    except Exception as e:
-        logger.error("Failed to read curator logs: %s", e, exc_info=True)
-        raise HTTPException(status_code=500, detail=f"Failed to read curator logs: {str(e)}")
+import asyncio
+import json
+import logging
+import mimetypes
+import re
+import tempfile
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, Body, Depends, File, HTTPException, Query, Request, UploadFile
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+from sqlalchemy import select
+
+from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_tag_store
+from app.gateway.path_utils import resolve_thread_virtual_path
+from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
+from deerflow.config.app_config import AppConfig
+from deerflow.config.extensions_config import ExtensionsConfig, SkillDisplayConfig, SkillStateConfig, get_extensions_config, reload_extensions_config
+from deerflow.persistence.engine import get_engine, get_session_factory
+from deerflow.persistence.skills import SkillStore
+from deerflow.persistence.skills.model import SkillDisplayAdapterRow
+from deerflow.persistence.tags import TagStore
+from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.skills import Skill
+from deerflow.skills.cascade import cascade_skill_unpublished_or_deleted
+from deerflow.skills.installer import SkillAlreadyExistsError
+from deerflow.skills.security_scanner import scan_skill_content
+from deerflow.skills.storage import get_or_new_skill_storage
+from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api", tags=["skills"])
+
+
+# ---------------------------------------------------------------------------
+# Per-user authz helpers (mirrors routers/agents.py)
+# ---------------------------------------------------------------------------
+
+
+def _current_user_id(request: Request) -> str:
+    user = getattr(request.state, "user", None)
+    if user is not None:
+        return str(user.id)
+    return get_effective_user_id()
+
+
+def _is_admin_user(request: Request) -> bool:
+    user = getattr(request.state, "user", None)
+    return getattr(user, "system_role", None) == "admin"
+
+
+def _can_view_skill_source(
+    category: SkillCategory,
+    owner_user_id: str | None,
+    user_id: str,
+    *,
+    is_admin: bool,
+) -> bool:
+    """Whether the raw SKILL.md source is visible to a user.
+
+    Admins may view any skill's source; otherwise only the publisher (the
+    owner of a custom skill) qualifies. Built-in / public skills have no human
+    owner, so for non-admins they are never source-visible.
+    """
+    if is_admin:
+        return True
+    return category == SkillCategory.CUSTOM and owner_user_id is not None and owner_user_id == user_id
+
+
+async def _get_owned_skill_or_raise(store: SkillStore, name: str, user_id: str) -> dict[str, Any]:
+    owned = await store.get_owned(name, user_id)
+    if owned is not None:
+        return owned
+    visible = await store.get_visible(name, user_id)
+    if visible is None:
+        raise HTTPException(status_code=404, detail=f"Skill '{name}' not found")
+    raise HTTPException(status_code=403, detail="You can only modify skills that you own")
+
+
+async def _get_editable_skill_or_raise(
+    store: SkillStore,
+    name: str,
+    user_id: str,
+    *,
+    is_admin: bool,
+) -> tuple[dict[str, Any], str]:
+    """Return (record, edit_mode) where edit_mode is 'owner' or 'admin'.
+
+    Admins can edit/delete any skill (including others' published ones, since
+    the spec lets them force-takedown). Non-admins are limited to their own.
+    """
+    owned = await store.get_owned(name, user_id)
+    if owned is not None:
+        return owned, "owner"
+    record = await store.get_any(name)
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Skill '{name}' not found")
+    if is_admin:
+        return record, "admin"
+    raise HTTPException(status_code=403, detail="You can only modify skills that you own")
+
+
+class SkillResponse(BaseModel):
+    """Response model for skill information."""
+
+    name: str = Field(..., description="Name of the skill")
+    description: str = Field(..., description="Description of what the skill does")
+    license: str | None = Field(None, description="License information")
+    category: SkillCategory = Field(..., description="Category of the skill (public or custom)")
+    enabled: bool = Field(default=True, description="Whether this skill is enabled")
+    use_count: int = Field(default=0, description="Number of times the skill has been used")
+    view_count: int = Field(default=0, description="Number of times the skill has been viewed")
+    patch_count: int = Field(default=0, description="Number of times the skill has been patched")
+    last_activity_at: datetime | None = Field(default=None, description="Most recent activity timestamp")
+    state: str = Field(default="active", description="Lifecycle state: active, stale, or archived")
+    pinned: bool = Field(default=False, description="Whether this skill is pinned (excluded from curation)")
+    source: str = Field(default="upload", description="Origin: 'agent' for agent-created, 'upload' for user-uploaded")
+    owner_user_id: str | None = Field(default=None, description="Custom skill owner (null = built-in or legacy)")
+    published: bool = Field(default=False, description="Whether the owner has made this skill visible to other users")
+    builtin: bool = Field(default=False, description="True when owner_user_id is null (no human owner)")
+    detail: str | None = Field(default=None, description="Human-authored long-form detail text (Markdown), editable by owner/admin")
+    display: dict[str, Any] | None = Field(default=None, description="Optional frontend display adapter")
+    display_sample: dict[str, Any] | None = Field(default=None, alias="displaySample", description="Persisted sample output used by the display adapter editor")
+    tags: list[dict] = Field(default_factory=list, description="Tags assigned to this skill")
+
+
+class SkillsListResponse(BaseModel):
+    """Response model for listing all skills."""
+
+    skills: list[SkillResponse]
+
+
+class SkillUpdateRequest(BaseModel):
+    """Request model for updating a skill."""
+
+    enabled: bool = Field(..., description="Whether to enable or disable the skill")
+
+
+class SkillDisplayUpdateRequest(BaseModel):
+    """Request model for updating a skill's frontend display adapter."""
+
+    display: SkillDisplayConfig | None = Field(default=None, description="Display adapter configuration; null clears it")
+    sample: dict[str, Any] | None = Field(default=None, description="Optional sample payload to persist for future editor sessions")
+
+
+class SkillDisplaySampleResponse(BaseModel):
+    """Sample structured output used to infer a display adapter."""
+
+    skill_name: str
+    sample: dict[str, Any]
+
+
+class PersistedSkillDisplaySampleResponse(BaseModel):
+    """Persisted sample output loaded from the database only."""
+
+    skill_name: str
+    sample: dict[str, Any] | None = None
+
+
+class SkillInstallRequest(BaseModel):
+    """Request model for installing a skill from a .skill file."""
+
+    thread_id: str = Field(..., description="The thread ID where the .skill file is located")
+    path: str = Field(..., description="Virtual path to the .skill file (e.g., mnt/user-data/outputs/my-skill.skill)")
+    target_category: SkillCategory = Field(default=SkillCategory.CUSTOM, description="Destination category: 'public' (admin only) or 'custom'")
+
+
+class SkillInstallResponse(BaseModel):
+    """Response model for skill installation."""
+
+    success: bool = Field(..., description="Whether the installation was successful")
+    skill_name: str = Field(..., description="Name of the installed skill")
+    message: str = Field(..., description="Installation result message")
+    overwritten: bool = Field(default=False, description="True if an existing skill was replaced")
+    category: str = Field(default="custom", description="Destination category: 'public' (admin) or 'custom'")
+
+
+class SkillUploadValidateResponse(BaseModel):
+    """Response model for the pre-install validation endpoint."""
+
+    ok: bool = Field(..., description="Whether the archive passed cheap validation")
+    skill_name: str = Field(..., description="Skill name parsed from frontmatter")
+    description: str = Field(default="", description="Skill description parsed from frontmatter")
+    license: str | None = Field(default=None, description="Skill license, if declared")
+    allowed_tools: list[str] = Field(default_factory=list, description="Tools the skill may invoke")
+    conflict: bool = Field(default=False, description="True if a skill with the same name already exists")
+    conflict_kind: str | None = Field(default=None, description="'public' or 'custom' when conflict=true")
+    warnings: list[str] = Field(default_factory=list, description="Non-fatal warnings to surface to the user")
+
+
+class SkillReconcileResponse(BaseModel):
+    """Response model for reconciling custom skills found on disk."""
+
+    adopted: list[str] = Field(default_factory=list, description="Skills found on disk that had no DB row; now owned by the caller")
+    already_registered: list[str] = Field(default_factory=list, description="Skills found on disk that already had a DB row (unchanged)")
+
+
+class CustomSkillContentResponse(SkillResponse):
+    content: str = Field(..., description="Raw SKILL.md content")
+
+
+class CustomSkillUpdateRequest(BaseModel):
+    content: str = Field(..., description="Replacement SKILL.md content")
+
+
+class CustomSkillHistoryResponse(BaseModel):
+    history: list[dict]
+
+
+class SkillRollbackRequest(BaseModel):
+    history_index: int = Field(default=-1, description="History entry index to restore from, defaulting to the latest change.")
+
+
+def _skill_to_response(
+    skill: Skill,
+    ownership: dict[str, Any] | None = None,
+    *,
+    display_override: dict[str, Any] | None = None,
+    display_sample: dict[str, Any] | None = None,
+) -> SkillResponse:
+    """Convert a Skill object to a SkillResponse.
+
+    ``ownership`` is the skill's record from ``SkillStore`` (or None for public
+    built-in skills which never have a DB row). When present, contributes the
+    ``owner_user_id`` / ``published`` / ``builtin`` fields used for per-user
+    visibility and the frontend's owner badges.
+    """
+    from deerflow.skills.usage import get_entry, latest_activity_at
+
+    entry = get_entry(skill.name)
+    last_at_str = latest_activity_at(skill.name)
+    last_at: datetime | None = None
+    if last_at_str:
+        try:
+            last_at = datetime.fromisoformat(last_at_str)
+        except Exception:
+            pass
+
+    owner_user_id: str | None = None
+    published = False
+    builtin = skill.category != SkillCategory.CUSTOM
+    detail: str | None = None
+    if ownership is not None:
+        owner_user_id = ownership.get("owner_user_id")
+        published = bool(ownership.get("published", False))
+        builtin = bool(ownership.get("builtin", owner_user_id is None))
+        detail = ownership.get("detail")
+
+    display = display_override
+    if display is None:
+        try:
+            skill_config = get_extensions_config().skills.get(skill.name)
+            if skill_config and skill_config.display:
+                display = skill_config.display.model_dump(by_alias=True)
+        except Exception:
+            logger.debug("Failed to read display adapter for %s", skill.name, exc_info=True)
+
+    return SkillResponse(
+        name=skill.name,
+        description=skill.description,
+        license=skill.license,
+        category=skill.category,
+        enabled=skill.enabled,
+        use_count=entry.get("use_count", 0),
+        view_count=entry.get("view_count", 0),
+        patch_count=entry.get("patch_count", 0),
+        last_activity_at=last_at,
+        state=entry.get("state", "active"),
+        pinned=entry.get("pinned", False),
+        source=entry.get("source", "upload"),
+        owner_user_id=owner_user_id,
+        published=published,
+        builtin=builtin,
+        detail=detail,
+        display=display,
+        displaySample=display_sample,
+    )
+
+
+def _dump_extensions_config(config_obj: ExtensionsConfig) -> dict[str, Any]:
+    return {
+        "mcpServers": {name: server.model_dump(by_alias=True) for name, server in config_obj.mcp_servers.items()},
+        "skills": {name: skill_config.model_dump(by_alias=True, exclude_none=True) for name, skill_config in config_obj.skills.items()},
+    }
+
+
+async def _ensure_skill_display_table() -> bool:
+    """Create the display adapter table when DB persistence is enabled."""
+    engine = get_engine()
+    sf = get_session_factory()
+    if engine is None or sf is None:
+        return False
+    async with engine.begin() as conn:
+        await conn.run_sync(SkillDisplayAdapterRow.__table__.create, checkfirst=True)
+    return True
+
+
+def _json_text_loads(value: str | None) -> dict[str, Any] | None:
+    if not value:
+        return None
+    try:
+        parsed = json.loads(value)
+        return parsed if isinstance(parsed, dict) else None
+    except Exception:
+        logger.warning("Failed to parse persisted skill display JSON", exc_info=True)
+        return None
+
+
+def _json_text_dumps(value: dict[str, Any] | None) -> str | None:
+    if value is None:
+        return None
+    return json.dumps(value, ensure_ascii=False)
+
+
+async def _get_skill_display_adapter(skill_name: str) -> dict[str, Any] | None:
+    if not await _ensure_skill_display_table():
+        return None
+    sf = get_session_factory()
+    if sf is None:
+        return None
+    async with sf() as session:
+        row = await session.get(SkillDisplayAdapterRow, skill_name)
+        if row is None:
+            return None
+        return {
+            "display": _json_text_loads(row.display_config),
+            "sample": _json_text_loads(row.sample_payload),
+        }
+
+
+async def _list_skill_display_adapters(skill_names: list[str]) -> dict[str, dict[str, Any]]:
+    if not skill_names or not await _ensure_skill_display_table():
+        return {}
+    sf = get_session_factory()
+    if sf is None:
+        return {}
+    async with sf() as session:
+        result = await session.execute(
+            select(SkillDisplayAdapterRow).where(SkillDisplayAdapterRow.skill_name.in_(skill_names))
+        )
+        return {
+            row.skill_name: {
+                "display": _json_text_loads(row.display_config),
+                "sample": _json_text_loads(row.sample_payload),
+            }
+            for row in result.scalars()
+        }
+
+
+async def _upsert_skill_display_adapter(
+    skill_name: str,
+    *,
+    display: dict[str, Any] | None | object = ...,
+    sample: dict[str, Any] | None | object = ...,
+) -> None:
+    if not await _ensure_skill_display_table():
+        return
+    sf = get_session_factory()
+    if sf is None:
+        return
+    async with sf() as session:
+        row = await session.get(SkillDisplayAdapterRow, skill_name)
+        if row is None:
+            row = SkillDisplayAdapterRow(skill_name=skill_name)
+            session.add(row)
+        if display is not ...:
+            row.display_config = _json_text_dumps(display)  # type: ignore[arg-type]
+        if sample is not ...:
+            row.sample_payload = _json_text_dumps(sample)  # type: ignore[arg-type]
+        row.updated_at = datetime.now()
+        await session.commit()
+
+
+_SKILL_SAMPLE_SYSTEM_PROMPT = (
+    "You infer realistic JSON return shapes for AI agent skills. "
+    "Given a skill's name, description, and full SKILL.md, output a SINGLE JSON object that "
+    "represents a plausible successful response from this skill's primary action. "
+    "Rules:\n"
+    "- Output JSON ONLY. No prose. No markdown fences. No comments.\n"
+    "- The top level must be a JSON object (not an array).\n"
+    "- Include a results/items/list/records array (pick the most natural key) with 2-3 example entries.\n"
+    "- Use realistic, idiomatic field names (e.g. title, content, source, publish_time, score, url, id) that match the skill's domain.\n"
+    "- Each entry should have enough fields to drive a citation/list/table UI: a title, a short snippet/content, a source, a time/date, and an id or url when relevant.\n"
+    "- Numbers stay numbers, dates stay ISO strings, scores between 0 and 1 when applicable.\n"
+    "- Do not invent fields that contradict the skill description."
+)
+
+
+def _extract_json_from_llm_output(raw: str) -> dict[str, Any] | None:
+    """Best-effort extraction of a JSON object from an LLM response."""
+    text = (raw or "").strip()
+    if not text:
+        return None
+    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.DOTALL | re.IGNORECASE)
+    if fence:
+        text = fence.group(1).strip()
+    try:
+        parsed = json.loads(text)
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        pass
+    match = re.search(r"\{.*\}", text, re.DOTALL)
+    if not match:
+        return None
+    try:
+        parsed = json.loads(match.group(0))
+        return parsed if isinstance(parsed, dict) else None
+    except json.JSONDecodeError:
+        return None
+
+
+async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) -> dict[str, Any]:
+    """Generate a realistic return-shape sample for ``skill`` via the LLM.
+
+    Reads SKILL.md, asks the configured curator model (or main model) to infer
+    a plausible JSON response. Falls back to :func:`_mock_skill_display_sample`
+    when the model is unconfigured, the call times out, or the output cannot
+    be parsed as a JSON object.
+    """
+    try:
+        skill_content = skill.skill_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.debug("Cannot read SKILL.md for %s (%s); falling back to description only", skill.name, exc)
+        skill_content = ""
+    # Cap the SKILL.md body so very large workflow docs don't blow the context.
+    max_chars = 6000
+    if len(skill_content) > max_chars:
+        skill_content = skill_content[:max_chars] + "\n…(truncated)"
+
+    user_prompt = (
+        f"Skill name: {skill.name}\n"
+        f"Short description: {skill.description}\n\n"
+        f"SKILL.md:\n-----\n{skill_content or '(SKILL.md unavailable; rely on the short description above.)'}\n-----\n\n"
+        "Return one JSON object that matches what this skill would actually produce on success."
+    )
+
+    try:
+        from deerflow.models import create_chat_model
+
+        # Reuse the curator/security-scan model setting; falls back to the main model when unset.
+        model_name = app_config.skill_evolution.curator.model_name if app_config.skill_evolution and app_config.skill_evolution.curator else None
+        model = create_chat_model(name=model_name, thinking_enabled=False, app_config=app_config)
+        response = await asyncio.wait_for(
+            model.ainvoke(
+                [
+                    {"role": "system", "content": _SKILL_SAMPLE_SYSTEM_PROMPT},
+                    {"role": "user", "content": user_prompt},
+                ],
+                config={"run_name": "skill_display_sample"},
+            ),
+            timeout=45,
+        )
+        parsed = _extract_json_from_llm_output(str(getattr(response, "content", "") or ""))
+        if parsed:
+            return parsed
+        logger.warning("Skill display sample model returned non-JSON for %s; falling back to static mock", skill.name)
+    except asyncio.TimeoutError:
+        logger.warning("Skill display sample LLM call timed out for %s; falling back to static mock", skill.name)
+    except Exception:
+        logger.warning("Skill display sample LLM call failed for %s; falling back to static mock", skill.name, exc_info=True)
+    return _mock_skill_display_sample(skill.name)
+
+
+def _mock_skill_display_sample(skill_name: str) -> dict[str, Any]:
+    if skill_name == "knowledge-search-v2":
+        return {
+            "success": True,
+            "query": "参考文献模式测试 知识库固定测试",
+            "count": 4,
+            "source": "fixed-display-sample",
+            "results": [
+                {
+                    "index": 1,
+                    "recUuid": "ksv2-fixed-001",
+                    "relevance_score": 0.982,
+                    "title": "参考文献模式测试：参考文献模式固定测试数据一",
+                    "source_category": "知识库/测试资料",
+                    "source": "knowledge-search-v2/fixed/source-001",
+                    "publish_time": "2026-05-25",
+                    "content_preview": "这是 knowledge-search-v2 返回的第一条固定测试资料，用于验证右侧参考文献列表、正文编号以及 recUuid 模板跳转是否正常。",
+                    "content_length": 168,
+                },
+                {
+                    "index": 2,
+                    "recUuid": "ksv2-fixed-002",
+                    "relevance_score": 0.936,
+                    "title": "参考文献模式测试：结构化字段映射验证",
+                    "source_category": "知识库/字段映射",
+                    "source": "knowledge-search-v2/fixed/source-002",
+                    "publish_time": "2026-05-24",
+                    "content_preview": "本条用于验证 title、source_category、source、publish_time、content_preview、relevance_score、recUuid 等字段能被前端正确识别并渲染。",
+                    "content_length": 154,
+                },
+                {
+                    "index": 3,
+                    "recUuid": "ksv2-fixed-003",
+                    "relevance_score": 0.887,
+                    "title": "参考文献模式测试：多引用排序验证",
+                    "source_category": "知识库/排序验证",
+                    "source": "knowledge-search-v2/fixed/source-003",
+                    "publish_time": "2026-05-23",
+                    "content_preview": "本条用于验证多条参考文献的编号顺序是否与 results 数组顺序一致，并验证点击正文编号时能定位到右侧对应参考文献。",
+                    "content_length": 132,
+                },
+                {
+                    "index": 4,
+                    "recUuid": "",
+                    "relevance_score": 0.801,
+                    "title": "参考文献模式测试：无 recUuid 跳转隐藏验证",
+                    "source_category": "知识库/边界场景",
+                    "source": "knowledge-search-v2/fixed/source-004",
+                    "publish_time": "2026-05-22",
+                    "content_preview": "本条故意把 recUuid 置为空，用于验证右侧弹框仍展示详情，但不展示外部跳转按钮。",
+                    "content_length": 98,
+                },
+            ],
+        }
+    return {
+        "success": True,
+        "query": "sample query",
+        "results": [
+            {
+                "id": "sample-001",
+                "title": "Sample result",
+                "summary": "Sample structured output used to infer field mapping.",
+                "source": "sample",
+                "updatedAt": "2026-05-25",
+            }
+        ],
+    }
+
+
+async def _build_ownership_index(skill_store: SkillStore, user_id: str) -> dict[str, dict[str, Any]]:
+    """Index visible-to-user skill records by name. Internal call cache for list endpoints."""
+    records = await skill_store.list_visible(user_id)
+    return {record["name"]: record for record in records}
+
+
+async def _attach_and_filter_tags(
+    tag_store: TagStore,
+    responses: list[SkillResponse],
+    search: str | None,
+    tag_ids: list[str] | None,
+) -> list[SkillResponse]:
+    """Bulk-attach tags to skill responses, then apply name/tag filters."""
+    assignments = await tag_store.list_assignments("skill", [r.name for r in responses])
+    for resp in responses:
+        resp.tags = assignments.get(resp.name, [])
+    if search:
+        needle = search.strip().lower()
+        responses = [r for r in responses if needle in r.name.lower()]
+    if tag_ids:
+        wanted = set(tag_ids)
+        responses = [r for r in responses if any(t.get("id") in wanted for t in r.tags)]
+    return responses
+
+
+@router.get(
+    "/skills",
+    response_model=SkillsListResponse,
+    summary="List All Skills",
+    description="Retrieve a list of all available skills from both public and custom directories.",
+)
+async def list_skills(
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+    tag_store: TagStore = Depends(get_tag_store),
+    search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
+    tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
+) -> SkillsListResponse:
+    try:
+        user_id = _current_user_id(request)
+        all_skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        ownership = await _build_ownership_index(skill_store, user_id)
+        display_adapters = await _list_skill_display_adapters([skill.name for skill in all_skills])
+        responses: list[SkillResponse] = []
+        for skill in all_skills:
+            adapter = display_adapters.get(skill.name, {})
+            # Public/built-in skills (no DB row) are visible to everyone.
+            # Custom skills must have an ownership record in the visible set.
+            if skill.category != SkillCategory.CUSTOM:
+                # Built-in skills usually have no DB row, but an admin-authored
+                # ``detail`` annotation materializes one — surface it when present.
+                responses.append(
+                    _skill_to_response(
+                        skill,
+                        ownership.get(skill.name),
+                        display_override=adapter.get("display"),
+                        display_sample=adapter.get("sample"),
+                    )
+                )
+                continue
+            record = ownership.get(skill.name)
+            if record is None:
+                continue
+            responses.append(
+                _skill_to_response(
+                    skill,
+                    record,
+                    display_override=adapter.get("display"),
+                    display_sample=adapter.get("sample"),
+                )
+            )
+        responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
+        return SkillsListResponse(skills=responses)
+    except Exception as e:
+        logger.error(f"Failed to load skills: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
+
+
+_MAX_SKILL_UPLOAD_BYTES = 512 * 1024 * 1024
+_ZIP_MAGIC = b"PK\x03\x04"
+
+
+async def _persist_uploaded_skill(file: UploadFile) -> Path:
+    """Stream an uploaded skill archive to a temp file. Caller must unlink it.
+
+    Validates the leading bytes look like a ZIP archive and enforces the same
+    512 MB cap that the extractor uses, so we reject obvious garbage early.
+    """
+    if file.filename is None:
+        raise HTTPException(status_code=400, detail="No file provided")
+    suffix = Path(file.filename).suffix.lower()
+    if suffix not in {".zip", ".skill"}:
+        raise HTTPException(status_code=400, detail="Skill upload must be a .zip or .skill file")
+
+    fd, tmp_name = tempfile.mkstemp(suffix=".skill", prefix="skill-upload-")
+    tmp_path = Path(tmp_name)
+    total = 0
+    head: bytes = b""
+    try:
+        with open(fd, "wb") as out:
+            while True:
+                chunk = await file.read(1024 * 1024)
+                if not chunk:
+                    break
+                if not head:
+                    head = chunk[: len(_ZIP_MAGIC)]
+                total += len(chunk)
+                if total > _MAX_SKILL_UPLOAD_BYTES:
+                    raise HTTPException(status_code=400, detail="Uploaded skill archive exceeds the 512 MB limit")
+                out.write(chunk)
+    except HTTPException:
+        tmp_path.unlink(missing_ok=True)
+        raise
+    except Exception:
+        tmp_path.unlink(missing_ok=True)
+        raise
+
+    if not head.startswith(_ZIP_MAGIC):
+        tmp_path.unlink(missing_ok=True)
+        raise HTTPException(status_code=400, detail="Uploaded file is not a valid ZIP archive")
+    return tmp_path
+
+
+@router.post(
+    "/skills/validate",
+    response_model=SkillUploadValidateResponse,
+    summary="Validate Skill Archive (No Install)",
+    description="Inspect an uploaded .zip/.skill archive and report parsed metadata + conflicts. Does NOT install or run the LLM security scan.",
+)
+async def validate_skill_upload(
+    file: UploadFile = File(..., description="The .zip or .skill archive to validate"),
+    config: AppConfig = Depends(get_config),
+) -> SkillUploadValidateResponse:
+    tmp_path = await _persist_uploaded_skill(file)
+    try:
+        result = get_or_new_skill_storage(app_config=config).validate_skill_archive(tmp_path)
+        return SkillUploadValidateResponse(**result)
+    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 HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to validate uploaded skill: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to validate skill: {e}")
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+@router.post(
+    "/skills/install-upload",
+    response_model=SkillInstallResponse,
+    summary="Install Skill from Upload",
+    description="Install a skill directly from an uploaded .zip/.skill archive. Set ?overwrite=true to replace an existing skill with the same name.",
+)
+async def install_skill_upload(
+    request: Request,
+    file: UploadFile = File(..., description="The .zip or .skill archive to install"),
+    overwrite: bool = False,
+    target_category: SkillCategory = SkillCategory.CUSTOM,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillInstallResponse:
+    user_id = _current_user_id(request)
+    is_admin = _is_admin_user(request)
+    # Only admins may install to the public (built-in) directory.
+    if target_category == SkillCategory.PUBLIC and not is_admin:
+        raise HTTPException(status_code=403, detail="Only admin users can install skills to the public directory")
+    tmp_path = await _persist_uploaded_skill(file)
+    try:
+        storage = get_or_new_skill_storage(app_config=config)
+        # Pre-parse the archive to learn the skill name without writing anything,
+        # so we can reject the upload before touching the filesystem if another
+        # user already owns this name. Admins bypass the ownership check since
+        # they install to the shared public directory.
+        try:
+            validation = storage.validate_skill_archive(tmp_path)
+            preview_name = validation.get("skill_name") if isinstance(validation, dict) else None
+        except Exception:
+            preview_name = None
+        if preview_name and not is_admin:
+            existing = await skill_store.get_any(preview_name)
+            if existing and existing.get("owner_user_id") not in (None, user_id):
+                raise HTTPException(
+                    status_code=409,
+                    detail=f"Skill '{preview_name}' already exists and is owned by another user",
+                )
+        result = await storage.ainstall_skill_from_archive(tmp_path, overwrite=overwrite, require_skill_suffix=False, target_category=target_category)
+        try:
+            from deerflow.skills.usage import mark_uploaded
+            mark_uploaded(result["skill_name"])
+        except Exception:
+            pass
+        # For public installs (admin), register as built-in with no owner.
+        # For custom installs, register ownership under the uploading user.
+        if target_category == SkillCategory.PUBLIC:
+            await skill_store.ensure_legacy(
+                {"name": result["skill_name"], "owner_user_id": None, "published": True}
+            )
+        else:
+            # ``ensure_legacy`` is idempotent and only patches a NULL owner; it
+            # never overwrites an existing owner, so the pre-parse check above
+            # is what really guards cross-user steals.
+            await skill_store.ensure_legacy(
+                {"name": result["skill_name"], "owner_user_id": user_id, "published": False}
+            )
+        await refresh_skills_system_prompt_cache_async()
+        return SkillInstallResponse(**result)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except SkillAlreadyExistsError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to install uploaded skill: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to install skill: {e}")
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+@router.post(
+    "/skills/install",
+    response_model=SkillInstallResponse,
+    summary="Install Skill",
+    description="Install a skill from a .skill file (ZIP archive) located in the thread's user-data directory.",
+)
+async def install_skill(
+    body: SkillInstallRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillInstallResponse:
+    try:
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+        target_category = body.target_category
+        if target_category == SkillCategory.PUBLIC and not is_admin:
+            raise HTTPException(status_code=403, detail="Only admin users can install skills to the public directory")
+        skill_file_path = resolve_thread_virtual_path(body.thread_id, body.path)
+        result = await get_or_new_skill_storage(app_config=config).ainstall_skill_from_archive(skill_file_path, target_category=target_category)
+        try:
+            from deerflow.skills.usage import mark_uploaded
+            mark_uploaded(result["skill_name"])
+        except Exception:
+            pass
+        if target_category == SkillCategory.PUBLIC:
+            await skill_store.ensure_legacy(
+                {"name": result["skill_name"], "owner_user_id": None, "published": True}
+            )
+        else:
+            await skill_store.ensure_legacy(
+                {"name": result["skill_name"], "owner_user_id": user_id, "published": False}
+            )
+        await refresh_skills_system_prompt_cache_async()
+        return SkillInstallResponse(**result)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except SkillAlreadyExistsError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to install skill: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to install skill: {str(e)}")
+
+
+@router.post(
+    "/skills/reconcile-custom",
+    response_model=SkillReconcileResponse,
+    summary="Adopt Orphan Custom Skills",
+    description=(
+        "Scan the on-disk ``skills/custom/`` directory and register any skill that has a "
+        "valid SKILL.md but no DB ownership row. Adopted skills are recorded as owned by "
+        "the calling user with ``published=false``. Skips skills that already have a row "
+        "(regardless of owner). Useful after manually unzipping skills onto the filesystem."
+    ),
+)
+async def reconcile_custom_skills(
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillReconcileResponse:
+    try:
+        user_id = _current_user_id(request)
+        storage = get_or_new_skill_storage(app_config=config)
+        custom_skills = [s for s in storage.load_skills(enabled_only=False) if s.category == SkillCategory.CUSTOM]
+
+        adopted: list[str] = []
+        already: list[str] = []
+        for skill in custom_skills:
+            existing = await skill_store.get_any(skill.name)
+            if existing is not None:
+                already.append(skill.name)
+                continue
+            await skill_store.ensure_legacy(
+                {"name": skill.name, "owner_user_id": user_id, "published": False}
+            )
+            try:
+                from deerflow.skills.usage import mark_uploaded
+                mark_uploaded(skill.name)
+            except Exception:
+                pass
+            adopted.append(skill.name)
+
+        if adopted:
+            await refresh_skills_system_prompt_cache_async()
+        return SkillReconcileResponse(adopted=adopted, already_registered=already)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to reconcile custom skills: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to reconcile custom skills: {e}")
+
+
+@router.get("/skills/custom", response_model=SkillsListResponse, summary="List Custom Skills")
+async def list_custom_skills(
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillsListResponse:
+    try:
+        user_id = _current_user_id(request)
+        custom = [s for s in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if s.category == SkillCategory.CUSTOM]
+        ownership = await _build_ownership_index(skill_store, user_id)
+        display_adapters = await _list_skill_display_adapters([skill.name for skill in custom])
+        responses = [
+            _skill_to_response(
+                skill,
+                ownership[skill.name],
+                display_override=display_adapters.get(skill.name, {}).get("display"),
+                display_sample=display_adapters.get(skill.name, {}).get("sample"),
+            )
+            for skill in custom
+            if skill.name in ownership
+        ]
+        return SkillsListResponse(skills=responses)
+    except Exception as e:
+        logger.error("Failed to list custom skills: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list custom skills: {str(e)}")
+
+
+@router.get("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Get Custom Skill Content")
+async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name and s.category == SkillCategory.CUSTOM), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get custom skill: {str(e)}")
+
+
+@router.put("/skills/custom/{skill_name}", response_model=CustomSkillContentResponse, summary="Edit Custom Skill")
+async def update_custom_skill(skill_name: str, request: CustomSkillUpdateRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.ensure_custom_skill_is_editable(skill_name)
+        storage.validate_skill_markdown_content(skill_name, request.content)
+        scan = await scan_skill_content(request.content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
+        if scan.decision == "block":
+            raise HTTPException(status_code=400, detail=f"Security scan blocked the edit: {scan.reason}")
+        prev_content = storage.read_custom_skill(skill_name)
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, request.content)
+        storage.append_history(
+            skill_name,
+            {
+                "action": "human_edit",
+                "author": "human",
+                "thread_id": None,
+                "file_path": SKILL_MD_FILE,
+                "prev_content": prev_content,
+                "new_content": request.content,
+                "scanner": {"decision": scan.decision, "reason": scan.reason},
+            },
+        )
+        try:
+            from deerflow.skills.usage import bump_patch
+            bump_patch(skill_name)
+        except Exception:
+            pass
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
+    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 update custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update custom skill: {str(e)}")
+
+
+@router.delete("/skills/custom/{skill_name}", summary="Delete Custom Skill")
+async def delete_custom_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:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+        record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
+        operation = "admin_takedown" if mode == "admin" and record.get("owner_user_id") not in (None, user_id) else "delete"
+
+        storage = get_or_new_skill_storage(app_config=config)
+        storage.delete_custom_skill(
+            skill_name,
+            history_meta={
+                "action": "human_delete",
+                "author": "human",
+                "thread_id": None,
+                "file_path": SKILL_MD_FILE,
+                "prev_content": None,
+                "new_content": None,
+                "scanner": {"decision": "allow", "reason": "Deletion requested."},
+            },
+        )
+        try:
+            from deerflow.skills.usage import forget
+            forget(skill_name)
+        except Exception:
+            pass
+
+        # Persist ownership record removal so the DB stays consistent.
+        if mode == "admin":
+            await skill_store.delete_admin(skill_name)
+        else:
+            await skill_store.delete(skill_name, user_id)
+
+        try:
+            await get_tag_store(request).unassign_all("skill", skill_name)
+        except Exception:  # noqa: BLE001 — tag cleanup must not block deletion
+            pass
+
+        # Strip references from every agent that pulled this skill in,
+        # and notify their owners (no-op for self).
+        await cascade_skill_unpublished_or_deleted(
+            skill_name,
+            actor_user_id=user_id,
+            operation=operation,
+            skill_owner_user_id=record.get("owner_user_id"),
+            agent_store=agent_store,
+        )
+
+        await refresh_skills_system_prompt_cache_async()
+        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 custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to delete custom skill: {str(e)}")
+
+
+class SkillPublishRequest(BaseModel):
+    """Request body for toggling a custom skill's published flag."""
+
+    published: bool = Field(..., description="Whether to publish (True) or unpublish (False)")
+
+
+class SkillPublishResponse(BaseModel):
+    name: str
+    owner_user_id: str | None
+    published: bool
+
+
+@router.put(
+    "/skills/custom/{skill_name}/published",
+    response_model=SkillPublishResponse,
+    summary="Toggle Custom Skill Published State",
+)
+async def update_custom_skill_published(
+    skill_name: str,
+    body: SkillPublishRequest,
+    request: Request,
+    skill_store: SkillStore = Depends(get_skill_store),
+    agent_store=Depends(get_agent_store),
+) -> SkillPublishResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+        record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
+
+        was_published = bool(record.get("published", False))
+        if mode == "admin":
+            updated = await skill_store.update_admin(skill_name, {"published": body.published})
+        else:
+            updated = await skill_store.update(skill_name, user_id, {"published": body.published})
+        if updated is None:
+            raise HTTPException(status_code=500, detail="Failed to persist published state")
+
+        # If we are *removing* visibility (was published, now not), strip from
+        # other users' agents and notify them. admin takedown is signaled by
+        # the actor not being the owner.
+        if was_published and not body.published:
+            skill_owner = record.get("owner_user_id")
+            operation = "admin_takedown" if mode == "admin" and skill_owner not in (None, user_id) else "unpublish"
+            await cascade_skill_unpublished_or_deleted(
+                skill_name,
+                actor_user_id=user_id,
+                operation=operation,
+                skill_owner_user_id=skill_owner,
+                agent_store=agent_store,
+            )
+            await refresh_skills_system_prompt_cache_async()
+
+        return SkillPublishResponse(
+            name=updated["name"],
+            owner_user_id=updated.get("owner_user_id"),
+            published=bool(updated.get("published", False)),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update published state for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update published state: {str(e)}")
+
+
+_ALLOWED_USER_STATES = {"active", "archived"}
+
+
+class SkillStateRequest(BaseModel):
+    """Request body for switching a custom skill's lifecycle state."""
+
+    state: str = Field(..., description="New state: 'active' (restore) or 'archived' (soft archive)")
+
+
+class SkillPinRequest(BaseModel):
+    """Request body for pinning / unpinning a custom skill."""
+
+    pinned: bool = Field(..., description="Whether to pin (true) so the curator never auto-archives this skill")
+
+
+def _reload_skill_response(skill_name: str, ownership: dict[str, Any], config: AppConfig) -> SkillResponse:
+    """Reload a single skill from disk and return its API response form."""
+    skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+    skill = next((s for s in skills if s.name == skill_name), None)
+    if skill is None:
+        raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found on disk")
+    return _skill_to_response(skill, ownership)
+
+
+@router.put(
+    "/skills/custom/{skill_name}/state",
+    response_model=SkillResponse,
+    summary="Update Custom Skill Lifecycle State",
+    description="Restore (active) or soft-archive a custom skill. Only the owner or admins may invoke.",
+)
+async def update_custom_skill_state(
+    skill_name: str,
+    body: SkillStateRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        if body.state not in _ALLOWED_USER_STATES:
+            raise HTTPException(
+                status_code=400,
+                detail=f"state must be one of {sorted(_ALLOWED_USER_STATES)}",
+            )
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+        record, _mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
+
+        from deerflow.skills.usage import set_state as _usage_set_state
+
+        _usage_set_state(skill_name, body.state)
+        await refresh_skills_system_prompt_cache_async()
+        return _reload_skill_response(skill_name, record, config)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update state for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update state: {e}")
+
+
+@router.put(
+    "/skills/custom/{skill_name}/pinned",
+    response_model=SkillResponse,
+    summary="Pin or Unpin a Custom Skill",
+    description="Pin a skill so the curator never auto-archives it. Only the owner or admins may invoke.",
+)
+async def update_custom_skill_pinned(
+    skill_name: str,
+    body: SkillPinRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+        record, _mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
+
+        from deerflow.skills.usage import set_pinned as _usage_set_pinned
+
+        _usage_set_pinned(skill_name, body.pinned)
+        return _reload_skill_response(skill_name, record, config)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update pinned for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update pinned: {e}")
+
+
+@router.get("/skills/custom/{skill_name}/history", response_model=CustomSkillHistoryResponse, summary="Get Custom Skill History")
+async def get_custom_skill_history(skill_name: str, config: AppConfig = Depends(get_config)) -> CustomSkillHistoryResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        return CustomSkillHistoryResponse(history=storage.read_history(skill_name))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to read history for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read history: {str(e)}")
+
+
+@router.post("/skills/custom/{skill_name}/rollback", response_model=CustomSkillContentResponse, summary="Rollback Custom Skill")
+async def rollback_custom_skill(skill_name: str, request: SkillRollbackRequest, config: AppConfig = Depends(get_config)) -> CustomSkillContentResponse:
+    try:
+        storage = get_or_new_skill_storage(app_config=config)
+        if not storage.custom_skill_exists(skill_name) and not storage.get_skill_history_file(skill_name).exists():
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        history = storage.read_history(skill_name)
+        if not history:
+            raise HTTPException(status_code=400, detail=f"Custom skill '{skill_name}' has no history")
+        record = history[request.history_index]
+        target_content = record.get("prev_content")
+        if target_content is None:
+            raise HTTPException(status_code=400, detail="Selected history entry has no previous content to roll back to")
+        storage.validate_skill_markdown_content(skill_name, target_content)
+        scan = await scan_skill_content(target_content, executable=False, location=f"{skill_name}/{SKILL_MD_FILE}", app_config=config)
+        skill_file = storage.get_custom_skill_file(skill_name)
+        current_content = skill_file.read_text(encoding="utf-8") if skill_file.exists() else None
+        history_entry = {
+            "action": "rollback",
+            "author": "human",
+            "thread_id": None,
+            "file_path": SKILL_MD_FILE,
+            "prev_content": current_content,
+            "new_content": target_content,
+            "rollback_from_ts": record.get("ts"),
+            "scanner": {"decision": scan.decision, "reason": scan.reason},
+        }
+        if scan.decision == "block":
+            storage.append_history(skill_name, history_entry)
+            raise HTTPException(status_code=400, detail=f"Rollback blocked by security scanner: {scan.reason}")
+        storage.write_custom_skill(skill_name, SKILL_MD_FILE, target_content)
+        storage.append_history(skill_name, history_entry)
+        await refresh_skills_system_prompt_cache_async()
+        return await get_custom_skill(skill_name, config)
+    except HTTPException:
+        raise
+    except IndexError:
+        raise HTTPException(status_code=400, detail="history_index is out of range")
+    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 roll back custom skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to roll back custom skill: {str(e)}")
+
+
+@router.get(
+    "/skills/{skill_name}",
+    response_model=SkillResponse,
+    summary="Get Skill Details",
+    description="Retrieve detailed information about a specific skill by its name.",
+)
+async def get_skill(
+    skill_name: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        # Attach ownership (owner/published/detail) when the caller may see it.
+        ownership = await skill_store.get_visible(skill_name, _current_user_id(request))
+        return _skill_to_response(skill, ownership)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to get skill {skill_name}: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get skill: {str(e)}")
+
+
+class SkillContentResponse(BaseModel):
+    """SKILL.md 原文内容,适用于公共和自定义技能。"""
+
+    name: str
+    category: SkillCategory
+    content: str
+
+
+@router.get(
+    "/skills/{skill_name}/content",
+    response_model=SkillContentResponse,
+    summary="Get Skill Markdown Content",
+    description="Retrieve the raw SKILL.md content of a skill. Readable by any user the skill is visible to (built-in, published, or owned).",
+)
+async def get_skill_content(
+    skill_name: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillContentResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+        user_id = _current_user_id(request)
+        # SKILL.md describes how to use a skill — visible to anyone who can see
+        # the skill itself (built-in, published, or owned). Admins always pass.
+        if not _is_admin_user(request):
+            record = await skill_store.get_any(skill_name)
+            if skill.category == SkillCategory.CUSTOM:
+                if record is None:
+                    raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+                if not record.get("published") and record.get("owner_user_id") != user_id:
+                    raise HTTPException(status_code=403, detail="You can only view SKILL.md for skills visible to you")
+        content = skill.skill_file.read_text(encoding="utf-8")
+        return SkillContentResponse(name=skill.name, category=skill.category, content=content)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get skill content %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get skill content: {str(e)}")
+
+
+# ---------------------------------------------------------------------------
+# Skill files browser (tree + per-file read / write)
+# ---------------------------------------------------------------------------
+
+
+_SKILL_FILE_TEXT_EXTS = {
+    ".md", ".markdown", ".txt", ".rst",
+    ".py", ".pyi",
+    ".json", ".jsonl",
+    ".yaml", ".yml",
+    ".toml", ".ini", ".cfg", ".env",
+    ".sh", ".bash", ".zsh", ".ps1",
+    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".html", ".htm", ".css", ".scss", ".sass", ".xml", ".svg",
+    ".csv", ".tsv",
+    ".sql",
+}
+_SKILL_FILE_TREE_SKIP_NAMES = {
+    "__pycache__", "node_modules", ".git", ".DS_Store", ".idea", ".vscode",
+}
+_SKILL_FILE_MAX_NODES = 2000
+_SKILL_FILE_MAX_DEPTH = 8
+_SKILL_FILE_READ_BYTES = 2 * 1024 * 1024   # 2 MiB cap on JSON content payload
+_SKILL_FILE_WRITE_BYTES = 1 * 1024 * 1024  # 1 MiB cap on edits
+
+
+class SkillFileNode(BaseModel):
+    """One entry in a skill's file tree.
+
+    ``children`` is only set for directories. ``path`` is POSIX-style and is
+    always relative to the skill's own directory (never absolute).
+    """
+
+    name: str = Field(..., description="Base name (no slashes)")
+    type: str = Field(..., description="'file' or 'dir'")
+    path: str = Field(..., description="Path relative to the skill directory, POSIX-separated")
+    size: int | None = Field(default=None, description="File size in bytes (files only)")
+    mtime: float | None = Field(default=None, description="Modification time as POSIX seconds (files only)")
+    children: list["SkillFileNode"] | None = Field(default=None, description="Child entries (directories only)")
+
+
+SkillFileNode.model_rebuild()
+
+
+class SkillFilesResponse(BaseModel):
+    """Tree of files under a skill directory."""
+
+    name: str
+    category: SkillCategory
+    editable: bool = Field(..., description="True when the caller may PUT new content into any file under this tree")
+    root: SkillFileNode
+
+
+class SkillFileContentResponse(BaseModel):
+    """JSON payload for reading a single file inside a skill."""
+
+    name: str
+    category: SkillCategory
+    path: str
+    mime: str
+    size: int
+    mtime: float
+    is_text: bool = Field(..., description="True when ``content`` carries the decoded text; otherwise download via the binary endpoint")
+    editable: bool = Field(..., description="True when the caller may PUT new content for this file")
+    content: str | None = Field(default=None, description="Decoded text content when ``is_text`` is True")
+
+
+class SkillFileSaveRequest(BaseModel):
+    """Request body for writing a text file inside a skill."""
+
+    path: str = Field(..., description="File path relative to the skill directory, POSIX-separated")
+    content: str = Field(..., description="Replacement text content")
+
+
+class SkillFileSaveResponse(BaseModel):
+    name: str
+    path: str
+    size: int
+    mtime: float
+
+
+def _normalize_skill_name_param(skill_name: str) -> str:
+    """Strip CR/LF the same way other skill routes do before lookup."""
+    return skill_name.replace("\r\n", "").replace("\n", "")
+
+
+def _load_skill_or_404(skill_name: str, config: AppConfig) -> Skill:
+    skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+    skill = next((s for s in skills if s.name == skill_name), None)
+    if skill is None:
+        raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+    return skill
+
+
+async def _ensure_files_view_allowed(
+    skill: Skill,
+    request: Request,
+    skill_store: SkillStore,
+) -> dict[str, Any] | None:
+    """Mirror _can_view_skill_source: admins or the publisher (custom owner)."""
+    record = await skill_store.get_any(skill.name)
+    owner_user_id = record.get("owner_user_id") if record else None
+    user_id = _current_user_id(request)
+    if not _can_view_skill_source(skill.category, owner_user_id, user_id, is_admin=_is_admin_user(request)):
+        raise HTTPException(status_code=403, detail="Only the skill publisher or an admin can browse skill files")
+    return record
+
+
+def _caller_can_edit_skill_files(
+    skill: Skill,
+    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
+    if _is_admin_user(request):
+        return True
+    if record is None:
+        return False
+    return record.get("owner_user_id") == _current_user_id(request)
+
+
+def _resolve_skill_relative_path(skill: Skill, relative_path: str) -> Path:
+    """Validate *relative_path* against the skill directory and return the absolute Path.
+
+    Rejects empty, absolute, parent-traversing, or out-of-tree paths so a
+    malicious caller can never escape the skill's own directory.
+    """
+    if not relative_path or relative_path.strip() == "":
+        raise HTTPException(status_code=400, detail="path must not be empty")
+    candidate = Path(relative_path)
+    if candidate.is_absolute() or any(part in {"..", ""} for part in candidate.parts):
+        raise HTTPException(status_code=400, detail="path must be a relative path without '..' segments")
+    skill_dir = skill.skill_file.parent.resolve()
+    target = (skill_dir / candidate).resolve()
+    try:
+        target.relative_to(skill_dir)
+    except ValueError:
+        raise HTTPException(status_code=400, detail="path must stay inside the skill directory")
+    return target
+
+
+def _file_mime(path: Path) -> str:
+    """Best-effort MIME guess; defaults to ``application/octet-stream``."""
+    guessed, _ = mimetypes.guess_type(path.name)
+    if guessed:
+        return guessed
+    if path.suffix.lower() in _SKILL_FILE_TEXT_EXTS:
+        return "text/plain"
+    return "application/octet-stream"
+
+
+def _is_text_file(path: Path) -> bool:
+    """Treat known text extensions as text; everything else as binary."""
+    return path.suffix.lower() in _SKILL_FILE_TEXT_EXTS
+
+
+def _build_skill_file_tree(skill_dir: Path) -> SkillFileNode:
+    """Walk *skill_dir* and build a SkillFileNode tree, depth/count capped.
+
+    Hidden files (``.foo``) and a small block-list of noise directories
+    (``__pycache__`` etc.) are skipped so the UI does not drown in housekeeping
+    artefacts.
+    """
+    counter = {"n": 0}
+
+    def build(current_dir: Path, depth: int) -> SkillFileNode:
+        rel = current_dir.relative_to(skill_dir).as_posix()
+        node = SkillFileNode(
+            name=current_dir.name if rel != "." else skill_dir.name,
+            type="dir",
+            path="" if rel == "." else rel,
+            children=[],
+        )
+        if depth >= _SKILL_FILE_MAX_DEPTH:
+            return node
+        try:
+            entries = sorted(current_dir.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+        except OSError:
+            return node
+        for entry in entries:
+            if counter["n"] >= _SKILL_FILE_MAX_NODES:
+                break
+            if entry.name.startswith(".") or entry.name in _SKILL_FILE_TREE_SKIP_NAMES:
+                continue
+            counter["n"] += 1
+            if entry.is_dir():
+                node.children.append(build(entry, depth + 1))
+                continue
+            try:
+                stat = entry.stat()
+                size = stat.st_size
+                mtime = stat.st_mtime
+            except OSError:
+                size = 0
+                mtime = 0.0
+            node.children.append(
+                SkillFileNode(
+                    name=entry.name,
+                    type="file",
+                    path=entry.relative_to(skill_dir).as_posix(),
+                    size=size,
+                    mtime=mtime,
+                )
+            )
+        return node
+
+    return build(skill_dir, 0)
+
+
+@router.get(
+    "/skills/{skill_name}/files",
+    response_model=SkillFilesResponse,
+    summary="List Skill Files (Tree)",
+    description=(
+        "Return the full file tree under a skill directory. Only an admin or the "
+        "skill's publisher (owner of a custom skill) may browse files; other users "
+        "get 403."
+    ),
+)
+async def list_skill_files(
+    skill_name: str,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillFilesResponse:
+    try:
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        record = await _ensure_files_view_allowed(skill, request, skill_store)
+        skill_dir = skill.skill_file.parent
+        root = _build_skill_file_tree(skill_dir)
+        return SkillFilesResponse(
+            name=skill.name,
+            category=skill.category,
+            editable=_caller_can_edit_skill_files(skill, record, request),
+            root=root,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to list skill files for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list skill files: {e}")
+
+
+@router.get(
+    "/skills/{skill_name}/files/content",
+    response_model=SkillFileContentResponse,
+    summary="Read Skill File (Text)",
+    description=(
+        "Return JSON metadata for a single file under a skill. Text files include "
+        "their decoded ``content``; binary files omit ``content`` and should be "
+        "fetched from the ``files/download`` endpoint for inline display or "
+        "download. Same view authorisation as the file tree endpoint."
+    ),
+)
+async def get_skill_file_content(
+    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),
+) -> SkillFileContentResponse:
+    try:
+        skill_name = _normalize_skill_name_param(skill_name)
+        skill = _load_skill_or_404(skill_name, config)
+        record = await _ensure_files_view_allowed(skill, request, skill_store)
+        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}'")
+        stat = target.stat()
+        mime = _file_mime(target)
+        is_text = _is_text_file(target)
+        content: str | None = None
+        if is_text:
+            if stat.st_size > _SKILL_FILE_READ_BYTES:
+                raise HTTPException(status_code=413, detail=f"File exceeds the {_SKILL_FILE_READ_BYTES // 1024} KiB preview limit")
+            try:
+                content = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                # File has a text-y extension but is not UTF-8 — treat as binary.
+                is_text = False
+        return SkillFileContentResponse(
+            name=skill.name,
+            category=skill.category,
+            path=target.relative_to(skill.skill_file.parent.resolve()).as_posix(),
+            mime=mime,
+            size=stat.st_size,
+            mtime=stat.st_mtime,
+            is_text=is_text,
+            editable=is_text and _caller_can_edit_skill_files(skill, record, request),
+            content=content,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to read skill file %s/%s: %s", skill_name, path, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read skill file: {e}")
+
+
+@router.get(
+    "/skills/{skill_name}/files/download",
+    summary="Download Skill File (Raw Bytes)",
+    description=(
+        "Stream the raw bytes of a single file under a skill, suitable for "
+        "embedding in an ``<img>`` tag or for direct download. Same view "
+        "authorisation as the file tree endpoint."
+    ),
+)
+async def download_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),
+):
+    skill_name = _normalize_skill_name_param(skill_name)
+    skill = _load_skill_or_404(skill_name, config)
+    await _ensure_files_view_allowed(skill, request, skill_store)
+    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}'")
+    return FileResponse(
+        path=target,
+        media_type=_file_mime(target),
+        filename=target.name,
+    )
+
+
+@router.put(
+    "/skills/{skill_name}/files/content",
+    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 "
+        "refresh the system-prompt cache."
+    ),
+)
+async def save_skill_file(
+    skill_name: str,
+    body: SkillFileSaveRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillFileSaveResponse:
+    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")
+
+        target = _resolve_skill_relative_path(skill, body.path)
+        if not target.exists():
+            raise HTTPException(status_code=404, detail=f"File '{body.path}' not found in skill '{skill_name}'")
+        if target.is_dir():
+            raise HTTPException(status_code=400, detail="path points to a directory")
+        if not _is_text_file(target):
+            raise HTTPException(status_code=400, detail=f"File type '{target.suffix or target.name}' is not editable")
+
+        if len(body.content.encode("utf-8")) > _SKILL_FILE_WRITE_BYTES:
+            raise HTTPException(status_code=413, detail=f"Content exceeds the {_SKILL_FILE_WRITE_BYTES // 1024} KiB edit limit")
+
+        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
+        prev_content: str | None = None
+        if target.exists():
+            try:
+                prev_content = target.read_text(encoding="utf-8")
+            except UnicodeDecodeError:
+                prev_content = None
+
+        if is_skill_md:
+            # 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)
+
+        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,
+                },
+            )
+        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)
+
+        if is_skill_md:
+            try:
+                from deerflow.skills.usage import bump_patch
+                bump_patch(skill.name)
+            except Exception:
+                pass
+            await refresh_skills_system_prompt_cache_async()
+
+        stat = target.stat()
+        return SkillFileSaveResponse(
+            name=skill.name,
+            path=relative_posix,
+            size=stat.st_size,
+            mtime=stat.st_mtime,
+        )
+    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 save skill file %s/%s: %s", skill_name, body.path, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to save skill file: {e}")
+
+
+@router.put(
+    "/skills/{skill_name}",
+    response_model=SkillResponse,
+    summary="Update Skill",
+    description="Update a skill's enabled status by modifying the extensions_config.json file.",
+)
+async def update_skill(skill_name: str, request: SkillUpdateRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        config_path = ExtensionsConfig.resolve_config_path()
+        if config_path is None:
+            config_path = Path.cwd().parent / "extensions_config.json"
+            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
+
+        extensions_config = get_extensions_config()
+        current_skill_config = extensions_config.skills.get(skill_name)
+        extensions_config.skills[skill_name] = SkillStateConfig(
+            enabled=request.enabled,
+            display=current_skill_config.display if current_skill_config else None,
+        )
+
+        config_data = _dump_extensions_config(extensions_config)
+
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(config_data, f, indent=2)
+
+        logger.info(f"Skills configuration updated and saved to: {config_path}")
+        reload_extensions_config()
+        await refresh_skills_system_prompt_cache_async()
+
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        updated_skill = next((s for s in skills if s.name == skill_name), None)
+
+        if updated_skill is None:
+            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after update")
+
+        logger.info(f"Skill '{skill_name}' enabled status updated to {request.enabled}")
+        return _skill_to_response(updated_skill)
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to update skill {skill_name}: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update skill: {str(e)}")
+
+
+@router.put(
+    "/skills/{skill_name}/display",
+    response_model=SkillResponse,
+    summary="Update Skill Display Adapter",
+    description="Update a skill's frontend display adapter in extensions_config.json.",
+)
+async def update_skill_display(
+    skill_name: str,
+    request: SkillDisplayUpdateRequest,
+    config: AppConfig = Depends(get_config),
+) -> SkillResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        config_path = ExtensionsConfig.resolve_config_path()
+        if config_path is None:
+            config_path = Path.cwd().parent / "extensions_config.json"
+            logger.info(f"No existing extensions config found. Creating new config at: {config_path}")
+
+        extensions_config = get_extensions_config()
+        current_skill_config = extensions_config.skills.get(skill_name)
+        extensions_config.skills[skill_name] = SkillStateConfig(
+            enabled=current_skill_config.enabled if current_skill_config else skill.enabled,
+            display=request.display,
+        )
+
+        display_payload = request.display.model_dump(by_alias=True) if request.display is not None else None
+        sample_payload = request.sample if "sample" in request.model_fields_set else ...
+        await _upsert_skill_display_adapter(
+            skill_name,
+            display=display_payload,
+            sample=sample_payload,
+        )
+
+        with open(config_path, "w", encoding="utf-8") as f:
+            json.dump(_dump_extensions_config(extensions_config), f, indent=2, ensure_ascii=False)
+
+        reload_extensions_config()
+        await refresh_skills_system_prompt_cache_async()
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        updated_skill = next((s for s in skills if s.name == skill_name), None)
+        if updated_skill is None:
+            raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after display update")
+        adapter = await _get_skill_display_adapter(skill_name) or {}
+        return _skill_to_response(
+            updated_skill,
+            display_override=adapter.get("display"),
+            display_sample=adapter.get("sample"),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update display adapter for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update skill display adapter: {str(e)}")
+
+
+@router.get(
+    "/skills/{skill_name}/display-sample",
+    response_model=PersistedSkillDisplaySampleResponse,
+    summary="Get Persisted Skill Display Sample",
+    description="Return only the sample stored in the database. Does not generate a fallback sample.",
+)
+async def get_persisted_skill_display_sample(
+    skill_name: str,
+    config: AppConfig = Depends(get_config),
+) -> PersistedSkillDisplaySampleResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+        adapter = await _get_skill_display_adapter(skill_name)
+        sample = adapter.get("sample") if adapter else None
+        return PersistedSkillDisplaySampleResponse(
+            skill_name=skill_name,
+            sample=sample if isinstance(sample, dict) else None,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get persisted display sample for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get persisted display sample: {str(e)}")
+
+
+@router.post(
+    "/skills/{skill_name}/display-sample",
+    response_model=SkillDisplaySampleResponse,
+    summary="Get Skill Display Sample",
+    description="Generate or return a structured sample response used by the frontend to infer display mapping.",
+)
+async def get_skill_display_sample(
+    skill_name: str,
+    config: AppConfig = Depends(get_config),
+) -> SkillDisplaySampleResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+        adapter = await _get_skill_display_adapter(skill_name)
+        if adapter and isinstance(adapter.get("sample"), dict):
+            return SkillDisplaySampleResponse(skill_name=skill_name, sample=adapter["sample"])
+        sample = await _generate_skill_display_sample(skill, config)
+        await _upsert_skill_display_adapter(skill_name, sample=sample)
+        return SkillDisplaySampleResponse(skill_name=skill_name, sample=sample)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to get display sample for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get display sample: {str(e)}")
+
+
+class SkillDetailRequest(BaseModel):
+    """Request body for setting a skill's human-authored detail text."""
+
+    detail: str = Field(default="", description="详情说明文本,支持 Markdown;传空字符串表示清空")
+
+
+class SkillDetailResponse(BaseModel):
+    """Response model for the skill-detail update endpoint."""
+
+    name: str = Field(..., description="Skill name")
+    detail: str | None = Field(default=None, description="Persisted detail text (null when cleared)")
+
+
+@router.put(
+    "/skills/{skill_name}/detail",
+    response_model=SkillDetailResponse,
+    summary="Update Skill Detail",
+    description="设置技能的详情说明。自定义技能由其所有者或管理员编辑;内置/公开技能仅管理员可编辑。",
+)
+async def update_skill_detail(
+    skill_name: str,
+    body: SkillDetailRequest,
+    request: Request,
+    config: AppConfig = Depends(get_config),
+    skill_store: SkillStore = Depends(get_skill_store),
+) -> SkillDetailResponse:
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        user_id = _current_user_id(request)
+        is_admin = _is_admin_user(request)
+
+        skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+
+        # Empty / whitespace-only input clears the annotation.
+        detail_value: str | None = body.detail.strip() or None
+
+        if skill.category == SkillCategory.CUSTOM:
+            # Owner edits their own skill; admins may edit anyone's.
+            _record, mode = await _get_editable_skill_or_raise(skill_store, skill_name, user_id, is_admin=is_admin)
+            if mode == "admin":
+                updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
+            else:
+                updated = await skill_store.update(skill_name, user_id, {"detail": detail_value})
+        else:
+            # Built-in / public skill — only admins may annotate it. These carry
+            # no DB row by default, so materialize one before writing detail.
+            if not is_admin:
+                raise HTTPException(status_code=403, detail="Only admin users can edit built-in skill details")
+            if await skill_store.get_any(skill_name) is None:
+                await skill_store.ensure_legacy({"name": skill_name, "owner_user_id": None, "published": True})
+            updated = await skill_store.update_admin(skill_name, {"detail": detail_value})
+
+        if updated is None:
+            raise HTTPException(status_code=500, detail="Failed to persist skill detail")
+        return SkillDetailResponse(name=skill_name, detail=updated.get("detail"))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update detail for %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update skill detail: {str(e)}")
+
+
+class SkillPinRequest(BaseModel):
+    pinned: bool = Field(..., description="Whether to pin or unpin the skill")
+
+
+@router.post("/skills/custom/{skill_name}/pin", response_model=SkillResponse, summary="Pin or Unpin Skill")
+async def pin_skill(skill_name: str, request: SkillPinRequest, config: AppConfig = Depends(get_config)) -> SkillResponse:
+    """Pin a skill to prevent it from being automatically archived by the curator."""
+    try:
+        skill_name = skill_name.replace("\r\n", "").replace("\n", "")
+        storage = get_or_new_skill_storage(app_config=config)
+        if not storage.custom_skill_exists(skill_name):
+            raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
+        from deerflow.skills.usage import set_pinned
+        set_pinned(skill_name, request.pinned)
+        skills = storage.load_skills(enabled_only=False)
+        skill = next((s for s in skills if s.name == skill_name), None)
+        if skill is None:
+            raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
+        return _skill_to_response(skill)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to pin skill %s: %s", skill_name, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to pin skill: {str(e)}")
+
+
+@router.get("/curator/status", summary="Curator Status")
+async def curator_status(request: Request) -> dict:
+    """Return the current curator state and per-lifecycle skill counts for the
+    authenticated user."""
+    try:
+        from deerflow.skills.curator import get_curator_status
+        return get_curator_status(_current_user_id(request))
+    except Exception as e:
+        logger.error("Failed to get curator status: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to get curator status: {str(e)}")
+
+
+@router.post("/curator/run", summary="Trigger Curator Run")
+async def run_curator(request: Request) -> dict:
+    """Manually trigger a curator review pass for the authenticated user
+    (bypasses the interval check, runs in a background thread).
+
+    Pre-checks the master switch / curator switch / run lock so the response
+    accurately reflects whether a run actually started — instead of always
+    reporting success. Returns ``{"triggered": bool, "reason": str | None}``.
+    """
+    try:
+        import threading
+
+        from deerflow.skills.curator import _curator_thread_target, manual_trigger_blocked_reason
+
+        user_id = _current_user_id(request)
+        reason = manual_trigger_blocked_reason(user_id)
+        if reason is not None:
+            return {"triggered": False, "reason": reason}
+        thread = threading.Thread(
+            target=_curator_thread_target,
+            args=(user_id,),
+            daemon=True,
+            name=f"skill-curator-manual-{user_id}",
+        )
+        thread.start()
+        return {"triggered": True, "reason": None}
+    except Exception as e:
+        logger.error("Failed to trigger curator: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to trigger curator: {str(e)}")
+
+
+class CuratorSubConfig(BaseModel):
+    """Nested curator configuration mirroring CuratorConfig."""
+
+    # 与 CuratorConfig.enabled 保持一致:默认关闭,需显式 opt-in。
+    enabled: bool = Field(default=False, description="Whether the curator runs automatically.")
+    interval_hours: int = Field(default=168, ge=1, description="Hours between curator runs.")
+    stale_after_days: int = Field(default=30, ge=1, description="Days of inactivity before a skill is marked stale.")
+    archive_after_days: int = Field(default=90, ge=1, description="Days of inactivity before a stale skill is archived.")
+    review_timeout_seconds: int = Field(default=600, ge=1, description="Overall timeout (seconds) for the LLM review pass.")
+    model_name: str | None = Field(default=None, description="Model name for the curator LLM review pass; null = primary model.")
+
+
+class CuratorConfigResponse(BaseModel):
+    """Response model exposing the effective skill_evolution config."""
+
+    enabled: bool
+    curator: CuratorSubConfig
+
+
+class CuratorConfigRequest(BaseModel):
+    """Payload for updating skill_evolution overrides.
+
+    All fields are required so the frontend always sends a complete config;
+    backend writes the entire payload to skill_evolution.json atomically.
+    """
+
+    enabled: bool = Field(..., description="Whether the agent can create and modify skills under skills/custom.")
+    curator: CuratorSubConfig
+
+
+class CuratorLogRecord(BaseModel):
+    ts: str
+    level: str
+    message: str
+
+
+class CuratorLogsResponse(BaseModel):
+    records: list[CuratorLogRecord]
+    run_count: int
+    last_run_at: str | None
+
+
+def _build_curator_config_response(evo) -> CuratorConfigResponse:
+    """Pure helper so both the GET route and the post-PUT refresh share one shape.
+
+    ``evo`` is a ``SkillEvolutionConfig`` instance (already merged with per-user
+    overrides if any).
+    """
+    return CuratorConfigResponse(
+        enabled=evo.enabled,
+        curator=CuratorSubConfig(
+            enabled=evo.curator.enabled,
+            interval_hours=evo.curator.interval_hours,
+            stale_after_days=evo.curator.stale_after_days,
+            archive_after_days=evo.curator.archive_after_days,
+            review_timeout_seconds=evo.curator.review_timeout_seconds,
+            model_name=evo.curator.model_name,
+        ),
+    )
+
+
+@router.get("/curator/config", response_model=CuratorConfigResponse, summary="Get Skill Evolution Config")
+async def get_curator_config(request: Request) -> CuratorConfigResponse:
+    """Return the current curator config for the authenticated user (yaml
+    defaults + that user's overrides)."""
+    try:
+        from deerflow.config.skill_evolution_runtime import load_skill_evolution_config_for_user
+
+        evo = load_skill_evolution_config_for_user(_current_user_id(request))
+        return _build_curator_config_response(evo)
+    except Exception as e:
+        logger.error("Failed to read curator config: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read curator config: {str(e)}")
+
+
+@router.put("/curator/config", response_model=CuratorConfigResponse, summary="Update Skill Evolution Config")
+async def update_curator_config(body: CuratorConfigRequest, request: Request) -> CuratorConfigResponse:
+    """Persist per-user overrides to ``users/{user_id}/skill_evolution.json``
+    and return the effective merged config.
+
+    The payload is validated against the ``SkillEvolutionConfig`` shape; unknown
+    fields are rejected.
+    """
+    try:
+        from deerflow.config.skill_evolution_config import SkillEvolutionConfig
+        from deerflow.config.skill_evolution_runtime import load_skill_evolution_config_for_user, save_user_overrides
+
+        user_id = _current_user_id(request)
+        payload = body.model_dump()
+        # Round-trip through SkillEvolutionConfig to ensure persisted shape stays valid.
+        SkillEvolutionConfig.model_validate(payload)
+        save_user_overrides(user_id, payload)
+        return _build_curator_config_response(load_skill_evolution_config_for_user(user_id))
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to update curator config: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update curator config: {str(e)}")
+
+
+@router.get("/curator/logs", response_model=CuratorLogsResponse, summary="Recent Curator Logs")
+async def get_curator_logs(request: Request) -> CuratorLogsResponse:
+    """Return in-memory log records from the most recent curator run for the
+    authenticated user.
+
+    The buffer is process-local and cleared when curator starts a new run or
+    when the backend restarts. Records are ordered oldest → newest.
+    """
+    try:
+        from deerflow.skills import curator_log
+        from deerflow.skills.curator import get_curator_status
+
+        user_id = _current_user_id(request)
+        records = curator_log.get_recent(user_id)
+        status = get_curator_status(user_id)
+        return CuratorLogsResponse(
+            records=[CuratorLogRecord(**r) for r in records],
+            run_count=int(status.get("run_count", 0)),
+            last_run_at=status.get("last_run_at"),
+        )
+    except Exception as e:
+        logger.error("Failed to read curator logs: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to read curator logs: {str(e)}")
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/models/__init__.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/models/__init__.py
index 3b19bb8d..2adfd763 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/models/__init__.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/models/__init__.py
@@ -30,7 +30,7 @@ from deerflow.persistence.scheduled_tasks.model import (
     ScheduledTaskSubscriptionRow,
     SchedulerThreadRow,
 )
-from deerflow.persistence.skills.model import SkillRow
+from deerflow.persistence.skills.model import SkillDisplayAdapterRow, SkillRow
 from deerflow.persistence.tags.model import TagAssignmentRow, TagRow
 from deerflow.persistence.thread_meta.model import ThreadMetaRow
 from deerflow.persistence.thread_shares.model import ThreadShareRow
@@ -51,6 +51,7 @@ __all__ = [
     "ScheduledTaskSubscriptionRow",
     "SchedulerThreadRow",
     "SkillRow",
+    "SkillDisplayAdapterRow",
     "TagAssignmentRow",
     "TagRow",
     "ThreadMetaRow",
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/model.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/model.py
index fa6f1d86..ff981c15 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/model.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/model.py
@@ -31,3 +31,16 @@ class SkillRow(Base):
     detail: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
     created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
     updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))
+
+
+class SkillDisplayAdapterRow(Base):
+    __tablename__ = "skill_display_adapters"
+
+    skill_name: Mapped[str] = mapped_column(String(64), primary_key=True)
+    # Store JSON as text for maximum MySQL compatibility. Some deployments still
+    # run MySQL variants where native JSON columns or unquoted names such as
+    # ``display`` are not accepted consistently.
+    display_config: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
+    sample_payload: Mapped[str | None] = mapped_column(Text, nullable=True, default=None)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC))
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=lambda: datetime.now(UTC), onupdate=lambda: datetime.now(UTC))
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/sandbox/local/local_sandbox.py b/offline-backend-20260512/backend/packages/harness/deerflow/sandbox/local/local_sandbox.py
index b4016822..23b25dbe 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/sandbox/local/local_sandbox.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/sandbox/local/local_sandbox.py
@@ -37,14 +37,26 @@ class LocalSandbox(Sandbox):
         """Return whether the selected shell is a PowerShell executable."""
         return LocalSandbox._shell_name(shell) in {"powershell", "powershell.exe", "pwsh", "pwsh.exe"}
 
-    @staticmethod
-    def _is_cmd_shell(shell: str) -> bool:
-        """Return whether the selected shell is cmd.exe."""
-        return LocalSandbox._shell_name(shell) in {"cmd", "cmd.exe"}
-
-    @staticmethod
-    def _find_first_available_shell(candidates: tuple[str, ...]) -> str | None:
-        """Return the first executable shell path or command found from candidates."""
+    @staticmethod
+    def _is_cmd_shell(shell: str) -> bool:
+        """Return whether the selected shell is cmd.exe."""
+        return LocalSandbox._shell_name(shell) in {"cmd", "cmd.exe"}
+
+    @staticmethod
+    def _normalize_powershell_command(command: str) -> str:
+        """Make bash-style command glue usable in Windows PowerShell 5.
+
+        The public tool is still named ``bash`` for model compatibility, but on
+        Windows local sandbox it may fall back to PowerShell. PowerShell 5 does
+        not support ``&&``, while the sandbox layer prepends commands with
+        ``cd <workspace> &&``. Rewriting the separator keeps skill scripts
+        executable in that fallback shell.
+        """
+        return command.replace("&&", ";")
+
+    @staticmethod
+    def _find_first_available_shell(candidates: tuple[str, ...]) -> str | None:
+        """Return the first executable shell path or command found from candidates."""
         for shell in candidates:
             if os.path.isabs(shell):
                 if os.path.isfile(shell) and os.access(shell, os.X_OK):
@@ -302,30 +314,39 @@ class LocalSandbox(Sandbox):
         resolved_command = self._resolve_paths_in_command(command)
         shell = self._get_shell()
 
-        if os.name == "nt":
-            if self._is_powershell(shell):
-                args = [shell, "-NoProfile", "-Command", resolved_command]
+        if os.name == "nt":
+            if self._is_powershell(shell):
+                args = [
+                    shell,
+                    "-NoProfile",
+                    "-Command",
+                    self._normalize_powershell_command(resolved_command),
+                ]
             elif self._is_cmd_shell(shell):
                 args = [shell, "/c", resolved_command]
             else:
                 args = [shell, "-c", resolved_command]
 
-            result = subprocess.run(
-                args,
-                shell=False,
-                capture_output=True,
-                text=True,
-                timeout=600,
-            )
-        else:
-            args = [shell, "-c", resolved_command]
-            result = subprocess.run(
-                args,
-                shell=False,
-                capture_output=True,
-                text=True,
-                timeout=600,
-            )
+            result = subprocess.run(
+                args,
+                shell=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=600,
+            )
+        else:
+            args = [shell, "-c", resolved_command]
+            result = subprocess.run(
+                args,
+                shell=False,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=600,
+            )
         output = result.stdout
         if result.stderr:
             output += f"\nStd Error:\n{result.stderr}" if output else result.stderr

From 26a388e3bf1fa973539a0529cd2adf5ec745c40a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 14:24:29 +0800
Subject: [PATCH 05/15] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=99=BA=E8=83=BD?=
 =?UTF-8?q?=E4=BD=93=E7=A7=81=E5=AF=86=E5=B9=BF=E5=9C=BA=EF=BC=88is=5Fpriv?=
 =?UTF-8?q?ate=20+=20=E7=AE=A1=E7=90=86=E5=91=98=E5=AF=86=E7=A0=81?=
 =?UTF-8?q?=E9=97=A8=E6=8E=A7=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- agents 表新增 is_private 列与迁移 20260526_01；列表 filter 拆分为公开
  广场用的 _listing_filter（剔除私密）与单条访问用的 _visible_filter（保留可达）
- system_settings 增 PrivateSquareSettings（enabled + password_hash），
  对应 GET/PUT /api/system-settings/private-square 由管理员管理
- /api/agents 接口：列表/创建/更新新增 is_private 字段；新增
  POST /api/agents/private-square/list（密码校验后返回私密智能体）与
  PUT /api/agents/{id}/private（管理员跨用户搬动智能体）
- 前端「智能体」页签新增「私密广场」入口（密码校验 + sessionStorage 缓存 +
  锁定按钮），卡片增加紫色私密徽章与盾牌切换按钮（owner 自助 / 管理员跨用户），
  「广场」与首页推荐候选均剔除私密智能体
- 新增管理员配置页 /settings/private-square 与侧边栏入口

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend-web/src/components/page-sidebar.tsx  |   8 +
 .../workspace/agents/agent-card.tsx           |  54 ++++-
 .../workspace/agents/agent-gallery.tsx        | 198 +++++++++++++++++-
 .../workspace/agents/agent-manage-dialog.tsx  |   7 +-
 .../workspace/workspace-nav-menu.tsx          |  11 +
 frontend-web/src/core/agents/api.ts           |  40 ++++
 frontend-web/src/core/agents/hooks.ts         |  33 +++
 frontend-web/src/core/agents/types.ts         |   3 +
 frontend-web/src/core/system-settings/api.ts  |  42 ++++
 .../src/core/system-settings/hooks.ts         |  24 +++
 .../src/pages/PrivateSquareSettingsPage.tsx   | 155 ++++++++++++++
 frontend-web/src/pages/StrategyRoutes.tsx     |  11 +
 frontend-web/src/pages/WorkspaceRoutes.tsx    |  13 ++
 .../backend/app/gateway/routers/agents.py     | 105 ++++++++++
 .../app/gateway/routers/system_settings.py    |  63 +++++-
 .../deerflow/config/system_settings.py        |  15 ++
 .../deerflow/persistence/agents/base.py       |   9 +
 .../deerflow/persistence/agents/model.py      |   6 +
 .../deerflow/persistence/agents/sql.py        |  40 +++-
 .../versions/20260526_01_agents_is_private.py |  62 ++++++
 20 files changed, 879 insertions(+), 20 deletions(-)
 create mode 100644 frontend-web/src/pages/PrivateSquareSettingsPage.tsx
 create mode 100644 offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260526_01_agents_is_private.py

diff --git a/frontend-web/src/components/page-sidebar.tsx b/frontend-web/src/components/page-sidebar.tsx
index 3b476e14..90b67c3c 100644
--- a/frontend-web/src/components/page-sidebar.tsx
+++ b/frontend-web/src/components/page-sidebar.tsx
@@ -26,6 +26,7 @@ import {
   ListTodo,
   MessageSquareCode,
   MessageSquarePlus,
+  ShieldCheck,
   Network,
   NotebookPen,
   Plus,
@@ -191,6 +192,13 @@ const menuItems: MenuItem[] = [
         path: "/page/strategy/settings/prompt-prefix",
         adminOnly: true,
       },
+      {
+        id: "mgmt-private-square",
+        label: "私密广场配置",
+        icon: ShieldCheck,
+        path: "/page/strategy/settings/private-square",
+        adminOnly: true,
+      },
       {
         id: "mgmt-llm-metrics",
         label: "大模型调用统计",
diff --git a/frontend-web/src/components/workspace/agents/agent-card.tsx b/frontend-web/src/components/workspace/agents/agent-card.tsx
index 0842da4e..aac8f52b 100644
--- a/frontend-web/src/components/workspace/agents/agent-card.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-card.tsx
@@ -6,6 +6,7 @@ import {
   InfoIcon,
   LockIcon,
   MessageSquareIcon,
+  ShieldIcon,
   SparklesIcon,
   SquarePenIcon,
   TagsIcon,
@@ -42,6 +43,7 @@ import { TagPickerDialog } from "@/components/workspace/tags/tag-picker-dialog";
 import {
   useDeleteAgent,
   useSetAgentFeatured,
+  useSetAgentPrivate,
   useUpdateAgent,
 } from "@/core/agents";
 import type { Agent } from "@/core/agents";
@@ -61,6 +63,7 @@ export function AgentCard({ agent }: AgentCardProps) {
   const deleteAgent = useDeleteAgent();
   const updateAgent = useUpdateAgent();
   const setFeatured = useSetAgentFeatured();
+  const setPrivate = useSetAgentPrivate();
   const { skills, isLoading: isSkillsLoading } = useSkills();
   const [deleteOpen, setDeleteOpen] = useState(false);
   const [editOpen, setEditOpen] = useState(false);
@@ -155,6 +158,27 @@ export function AgentCard({ agent }: AgentCardProps) {
     }
   }
 
+  async function handleTogglePrivate() {
+    const turningOn = !agent.is_private;
+    try {
+      if (isOwned) {
+        // Owners can re-categorize their own agents through the normal update
+        // endpoint — keeps publish/private edits in one transaction.
+        await updateAgent.mutateAsync({
+          id: agent.id,
+          request: { is_private: turningOn },
+        });
+      } else {
+        // Admins can move any agent (built-in or other users') via the
+        // dedicated admin endpoint.
+        await setPrivate.mutateAsync({ id: agent.id, isPrivate: turningOn });
+      }
+      toast.success(turningOn ? "已加入私密广场" : "已移出私密广场");
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
   async function handleToggleFeatured() {
     // One-click on/off — ordering is handled by the dedicated 管理 Agent 列表
     // dialog. Featured agents get appended to the end on add (Date.now() is a
@@ -229,7 +253,7 @@ export function AgentCard({ agent }: AgentCardProps) {
                   来自他人
                 </Badge>
               )}
-              {isOwned && agent.published && (
+              {isOwned && agent.published && !agent.is_private && (
                 <Badge
                   variant="outline"
                   className="border-sky-500/30 text-sky-700 dark:text-sky-300 text-xs"
@@ -239,6 +263,16 @@ export function AgentCard({ agent }: AgentCardProps) {
                   已发布
                 </Badge>
               )}
+              {agent.is_private && (
+                <Badge
+                  variant="outline"
+                  className="border-purple-500/30 text-purple-700 dark:text-purple-300 text-xs"
+                  title="该智能体位于私密广场，需要密码才能查看"
+                >
+                  <ShieldIcon className="size-3" />
+                  私密
+                </Badge>
+              )}
               {agent.featured_order != null && (
                 <Badge
                   variant="outline"
@@ -348,6 +382,24 @@ export function AgentCard({ agent }: AgentCardProps) {
                   )}
                 </Button>
               )}
+              {(isOwned || isAdmin) && (
+                <Button
+                  size="icon"
+                  variant="ghost"
+                  className={cn(
+                    "h-8 w-8 shrink-0",
+                    agent.is_private &&
+                      "text-purple-600 hover:text-purple-700",
+                  )}
+                  onClick={() => void handleTogglePrivate()}
+                  disabled={updateAgent.isPending || setPrivate.isPending}
+                  title={
+                    agent.is_private ? "移出私密广场" : "放入私密广场"
+                  }
+                >
+                  <ShieldIcon className="h-3.5 w-3.5" />
+                </Button>
+              )}
               {canEdit && (
                 <Button
                   size="icon"
diff --git a/frontend-web/src/components/workspace/agents/agent-gallery.tsx b/frontend-web/src/components/workspace/agents/agent-gallery.tsx
index cdce912f..87d438e5 100644
--- a/frontend-web/src/components/workspace/agents/agent-gallery.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-gallery.tsx
@@ -1,22 +1,32 @@
 "use client";
 
-import { BotIcon, PlusIcon } from "lucide-react";
+import { BotIcon, LockIcon, PlusIcon, ShieldIcon } from "lucide-react";
 import { useRouter } from "next/navigation";
-import { useMemo, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
 
 import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar";
-import { useAgents } from "@/core/agents";
+import { useAgents, usePrivateAgents } from "@/core/agents";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
+import { usePrivateSquareStatus } from "@/core/system-settings/hooks";
 
 import { AgentCard } from "./agent-card";
 
+// Within a single tab the verified password is kept in sessionStorage so a
+// refresh / route navigation does not re-prompt. Cleared on tab close, so the
+// password never persists beyond the browsing session.
+const PRIVATE_SQUARE_PASSWORD_KEY = "deer-flow.private-square-password";
+
 export function AgentGallery() {
   const { t } = useI18n();
   const router = useRouter();
-  const [activeTab, setActiveTab] = useState<"all" | "mine">("mine");
+  const [activeTab, setActiveTab] = useState<"all" | "mine" | "private">(
+    "mine",
+  );
   const [search, setSearch] = useState("");
   const [tagIds, setTagIds] = useState<string[]>([]);
   // Name + tag filtering is resolved server-side via the /api/agents query.
@@ -25,20 +35,84 @@ export function AgentGallery() {
   const storedAuth = useMemo(() => getStoredAuth(), []);
   const currentUserId = storedAuth?.user_id ?? null;
 
+  const { data: privateStatus } = usePrivateSquareStatus();
+  const privateFeatureAvailable = !!privateStatus?.enabled;
+  const privateFeatureUsable =
+    privateFeatureAvailable && !!privateStatus?.password_set;
+
+  const [privatePassword, setPrivatePassword] = useState<string | null>(() => {
+    if (typeof window === "undefined") return null;
+    return window.sessionStorage.getItem(PRIVATE_SQUARE_PASSWORD_KEY);
+  });
+  const [passwordInput, setPasswordInput] = useState("");
+
+  const {
+    agents: privateAgents,
+    isLoading: isPrivateLoading,
+    error: privateError,
+  } = usePrivateAgents(privatePassword);
+
+  // If the server reports the stored password no longer works (likely the
+  // admin rotated it), drop it from session storage and re-prompt.
+  useEffect(() => {
+    if (privatePassword && privateError) {
+      window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY);
+      setPrivatePassword(null);
+      toast.error("私密广场密码已失效，请重新输入");
+    }
+  }, [privateError, privatePassword]);
+
+  // The "广场" tab must never surface private-square agents, even to their
+  // own owner — moving an agent into the private square is supposed to hide
+  // it from the public square entirely. (The backend listing endpoint
+  // already filters them out for non-owners; this extra clause covers the
+  // owner's own private agents, which still come back in the unified list
+  // because owners always see their own.)
   const allAgents = useMemo(
-    () => agents.filter((a) => a.builtin || a.published),
+    () => agents.filter((a) => (a.builtin || a.published) && !a.is_private),
     [agents],
   );
 
   const myAgents = useMemo(
-    () => agents.filter((a) => a.user_id !== null && a.user_id === currentUserId),
+    () =>
+      agents.filter(
+        (a) => a.user_id !== null && a.user_id === currentUserId,
+      ),
     [agents, currentUserId],
   );
 
+  const filteredPrivateAgents = useMemo(() => {
+    const needle = search.trim().toLowerCase();
+    const wanted = new Set(tagIds);
+    return privateAgents.filter((a) => {
+      if (needle && !a.name.toLowerCase().includes(needle)) return false;
+      if (wanted.size > 0) {
+        if (!(a.tags ?? []).some((tg) => wanted.has(tg.id))) return false;
+      }
+      return true;
+    });
+  }, [privateAgents, search, tagIds]);
+
   const handleNewAgent = () => {
     router.push("/page/workspace/agents/new");
   };
 
+  const handleSubmitPassword = () => {
+    const trimmed = passwordInput.trim();
+    if (!trimmed) {
+      toast.error("请输入密码");
+      return;
+    }
+    window.sessionStorage.setItem(PRIVATE_SQUARE_PASSWORD_KEY, trimmed);
+    setPrivatePassword(trimmed);
+    setPasswordInput("");
+  };
+
+  const handleLockPrivate = () => {
+    window.sessionStorage.removeItem(PRIVATE_SQUARE_PASSWORD_KEY);
+    setPrivatePassword(null);
+  };
+
   const renderGrid = (list: typeof agents) => (
     <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
       {list.map((agent) => (
@@ -65,6 +139,78 @@ export function AgentGallery() {
     </div>
   );
 
+  const renderPrivateTab = () => {
+    if (!privateFeatureAvailable) {
+      return (
+        <div className="flex h-64 flex-col items-center justify-center gap-3 text-center">
+          <div className="bg-muted flex h-14 w-14 items-center justify-center rounded-full">
+            <ShieldIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <p className="font-medium">私密广场尚未开启</p>
+          <p className="text-muted-foreground max-w-sm text-sm">
+            请管理员前往「综合管理 → 私密广场配置」开启该功能并设置密码。
+          </p>
+        </div>
+      );
+    }
+
+    if (!privateFeatureUsable) {
+      return (
+        <div className="flex h-64 flex-col items-center justify-center gap-3 text-center">
+          <div className="bg-muted flex h-14 w-14 items-center justify-center rounded-full">
+            <ShieldIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <p className="font-medium">私密广场未配置密码</p>
+          <p className="text-muted-foreground max-w-sm text-sm">
+            请管理员在私密广场配置页设置一个访问密码。
+          </p>
+        </div>
+      );
+    }
+
+    if (!privatePassword) {
+      return (
+        <div className="mx-auto flex w-full max-w-sm flex-col gap-4 pt-12 text-center">
+          <div className="bg-muted mx-auto flex h-14 w-14 items-center justify-center rounded-full">
+            <LockIcon className="text-muted-foreground h-7 w-7" />
+          </div>
+          <div>
+            <p className="font-medium">私密广场</p>
+            <p className="text-muted-foreground mt-1 text-sm">
+              请输入访问密码，验证通过后才能查看其中的智能体。
+            </p>
+          </div>
+          <div className="flex flex-col gap-2">
+            <Input
+              type="password"
+              placeholder="访问密码"
+              value={passwordInput}
+              onChange={(e) => setPasswordInput(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") handleSubmitPassword();
+              }}
+            />
+            <Button onClick={handleSubmitPassword}>进入私密广场</Button>
+          </div>
+        </div>
+      );
+    }
+
+    if (isPrivateLoading) {
+      return (
+        <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
+          {t.common.loading}
+        </div>
+      );
+    }
+
+    if (filteredPrivateAgents.length === 0) {
+      return renderEmpty("私密广场暂时还没有智能体。");
+    }
+
+    return renderGrid(filteredPrivateAgents);
+  };
+
   return (
     <div className="flex size-full flex-col">
       {/* Page header */}
@@ -84,14 +230,35 @@ export function AgentGallery() {
       {/* Tabs */}
       <Tabs
         value={activeTab}
-        onValueChange={(v) => setActiveTab(v as "all" | "mine")}
+        onValueChange={(v) =>
+          setActiveTab(v as "all" | "mine" | "private")
+        }
         className="flex flex-1 flex-col overflow-hidden"
       >
         <div className="mx-6 mt-4 flex flex-col gap-3">
-          <TabsList className="w-auto self-start">
-            <TabsTrigger value="mine">我的</TabsTrigger>
-            <TabsTrigger value="all">广场</TabsTrigger>
-          </TabsList>
+          <div className="flex items-center justify-between gap-3">
+            <TabsList className="w-auto self-start">
+              <TabsTrigger value="mine">我的</TabsTrigger>
+              <TabsTrigger value="all">广场</TabsTrigger>
+              {privateFeatureAvailable && (
+                <TabsTrigger value="private">
+                  <LockIcon className="mr-1 h-3.5 w-3.5" />
+                  私密广场
+                </TabsTrigger>
+              )}
+            </TabsList>
+            {activeTab === "private" && privatePassword && (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={handleLockPrivate}
+                title="锁定私密广场，下次需要重新输入密码"
+              >
+                <LockIcon className="mr-1.5 h-3.5 w-3.5" />
+                锁定
+              </Button>
+            )}
+          </div>
           <TagSearchBar
             targetType="agent"
             onSearchChange={setSearch}
@@ -123,6 +290,15 @@ export function AgentGallery() {
             renderGrid(myAgents)
           )}
         </TabsContent>
+
+        {privateFeatureAvailable && (
+          <TabsContent
+            value="private"
+            className="flex-1 overflow-y-auto p-6 mt-0"
+          >
+            {renderPrivateTab()}
+          </TabsContent>
+        )}
       </Tabs>
     </div>
   );
diff --git a/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx b/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx
index fab434ed..03231c51 100644
--- a/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-manage-dialog.tsx
@@ -61,7 +61,12 @@ export function AgentManageDialog({
 
   const candidates = useMemo(() => {
     const existing = new Set(agents.map((a) => a.id));
-    return allAgents.filter((a) => a.published && !existing.has(a.id));
+    // Private-square agents are hidden from the homepage selector even if
+    // they're published — the backend ``list_featured`` filter would drop
+    // them again on the way out, so offering them here is just confusing.
+    return allAgents.filter(
+      (a) => a.published && !a.is_private && !existing.has(a.id),
+    );
   }, [agents, allAgents]);
 
   const busy = setFeaturedMutation.isPending || reorderMutation.isPending;
diff --git a/frontend-web/src/components/workspace/workspace-nav-menu.tsx b/frontend-web/src/components/workspace/workspace-nav-menu.tsx
index 009969ac..110cd8b9 100644
--- a/frontend-web/src/components/workspace/workspace-nav-menu.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-menu.tsx
@@ -11,6 +11,7 @@ import {
   MessageSquarePlusIcon,
   Settings2Icon,
   SettingsIcon,
+  ShieldCheckIcon,
   TagsIcon,
   UsersIcon,
 } from "lucide-react";
@@ -143,6 +144,16 @@ export function WorkspaceNavMenu() {
                       问答前缀配置
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() =>
+                        navigate("/page/workspace/settings/private-square")
+                      }
+                    >
+                      <ShieldCheckIcon />
+                      私密广场配置
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() =>
diff --git a/frontend-web/src/core/agents/api.ts b/frontend-web/src/core/agents/api.ts
index 5aba562a..3fb17baa 100644
--- a/frontend-web/src/core/agents/api.ts
+++ b/frontend-web/src/core/agents/api.ts
@@ -103,6 +103,46 @@ export async function reorderFeaturedAgents(agentIds: string[]): Promise<void> {
   }
 }
 
+export async function listPrivateAgents(password: string): Promise<Agent[]> {
+  const res = await apiFetch(
+    `${getBackendBaseURL()}/api/agents/private-square/list`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ password }),
+    },
+  );
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(
+      err.detail ?? `Failed to load private agents: ${res.statusText}`,
+    );
+  }
+  const data = (await res.json()) as { agents: Agent[] };
+  return data.agents;
+}
+
+export async function setAgentPrivate(
+  id: string,
+  isPrivate: boolean,
+): Promise<Agent> {
+  const res = await apiFetch(
+    `${getBackendBaseURL()}/api/agents/${id}/private`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ is_private: isPrivate }),
+    },
+  );
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(
+      err.detail ?? `Failed to update agent privacy: ${res.statusText}`,
+    );
+  }
+  return res.json() as Promise<Agent>;
+}
+
 export async function setAgentFeatured(
   id: string,
   order: number | null,
diff --git a/frontend-web/src/core/agents/hooks.ts b/frontend-web/src/core/agents/hooks.ts
index e19f56ad..8d8e81ad 100644
--- a/frontend-web/src/core/agents/hooks.ts
+++ b/frontend-web/src/core/agents/hooks.ts
@@ -11,8 +11,10 @@ import {
   getAgent,
   getAgentSelector,
   listAgents,
+  listPrivateAgents,
   reorderFeaturedAgents,
   setAgentFeatured,
+  setAgentPrivate,
   updateAgent,
 } from "./api";
 import type { CreateAgentRequest, UpdateAgentRequest } from "./types";
@@ -110,3 +112,34 @@ export function useReorderFeaturedAgents() {
     onSuccess: () => invalidateAgentQueries(queryClient),
   });
 }
+
+/**
+ * Query the password-gated private square. ``password`` is sent on every
+ * fetch — wire ``enabled`` to false until the user has typed it so we don't
+ * hit the endpoint with an empty body and get a 403.
+ */
+export function usePrivateAgents(password: string | null) {
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: ["agents", "private-square", password ?? ""],
+    queryFn: () => listPrivateAgents(password!),
+    enabled: !!password,
+    staleTime: 30_000,
+    retry: false,
+  });
+  return { agents: data ?? [], isLoading, error, refetch };
+}
+
+export function useSetAgentPrivate() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, isPrivate }: { id: string; isPrivate: boolean }) =>
+      setAgentPrivate(id, isPrivate),
+    onSuccess: (_data, { id }) => {
+      invalidateAgentQueries(queryClient);
+      void queryClient.invalidateQueries({ queryKey: ["agents", id] });
+      void queryClient.invalidateQueries({
+        queryKey: ["agents", "private-square"],
+      });
+    },
+  });
+}
diff --git a/frontend-web/src/core/agents/types.ts b/frontend-web/src/core/agents/types.ts
index 14ea12cc..11ccb03d 100644
--- a/frontend-web/src/core/agents/types.ts
+++ b/frontend-web/src/core/agents/types.ts
@@ -6,6 +6,7 @@ export interface Agent {
   description: string;
   user_id: string | null;
   published: boolean;
+  is_private: boolean;
   builtin: boolean;
   created_at?: string | null;
   updated_at?: string | null;
@@ -26,6 +27,7 @@ export interface CreateAgentRequest {
   description?: string;
   soul?: string;
   published?: boolean;
+  is_private?: boolean;
   skills?: string[] | null;
   model?: string | null;
   tool_groups?: string[] | null;
@@ -36,6 +38,7 @@ export interface UpdateAgentRequest {
   description?: string | null;
   soul?: string | null;
   published?: boolean | null;
+  is_private?: boolean | null;
   skills?: string[] | null;
   model?: string | null;
   tool_groups?: string[] | null;
diff --git a/frontend-web/src/core/system-settings/api.ts b/frontend-web/src/core/system-settings/api.ts
index 63f2022c..697e88c5 100644
--- a/frontend-web/src/core/system-settings/api.ts
+++ b/frontend-web/src/core/system-settings/api.ts
@@ -42,3 +42,45 @@ export async function updatePromptPrefixSettings(
   }
   return (await response.json()) as PromptPrefixSettings;
 }
+
+export interface PrivateSquareStatus {
+  enabled: boolean;
+  password_set: boolean;
+}
+
+export interface PrivateSquareUpdate {
+  enabled?: boolean;
+  password?: string;
+}
+
+export async function loadPrivateSquareStatus(): Promise<PrivateSquareStatus> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/private-square`,
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Failed to load private square settings: ${response.status}`,
+    );
+  }
+  return (await response.json()) as PrivateSquareStatus;
+}
+
+export async function updatePrivateSquareSettings(
+  body: PrivateSquareUpdate,
+): Promise<PrivateSquareStatus> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/private-square`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!response.ok) {
+    const detail = await response
+      .json()
+      .catch(() => ({ detail: "Failed to update private square" }));
+    throw new Error(detail.detail ?? "Failed to update private square");
+  }
+  return (await response.json()) as PrivateSquareStatus;
+}
diff --git a/frontend-web/src/core/system-settings/hooks.ts b/frontend-web/src/core/system-settings/hooks.ts
index 14f4d24b..9c2ee5fd 100644
--- a/frontend-web/src/core/system-settings/hooks.ts
+++ b/frontend-web/src/core/system-settings/hooks.ts
@@ -1,12 +1,16 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 
 import {
+  loadPrivateSquareStatus,
   loadPromptPrefixSettings,
+  updatePrivateSquareSettings,
   updatePromptPrefixSettings,
+  type PrivateSquareUpdate,
   type PromptPrefixUpdate,
 } from "./api";
 
 const PROMPT_PREFIX_KEY = ["systemSettings", "promptPrefix"] as const;
+const PRIVATE_SQUARE_KEY = ["systemSettings", "privateSquare"] as const;
 
 export function usePromptPrefixSettings() {
   return useQuery({
@@ -27,3 +31,23 @@ export function useUpdatePromptPrefixSettings() {
     },
   });
 }
+
+export function usePrivateSquareStatus() {
+  return useQuery({
+    queryKey: PRIVATE_SQUARE_KEY,
+    queryFn: () => loadPrivateSquareStatus(),
+    staleTime: 60_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useUpdatePrivateSquareSettings() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (body: PrivateSquareUpdate) =>
+      updatePrivateSquareSettings(body),
+    onSuccess: (data) => {
+      queryClient.setQueryData(PRIVATE_SQUARE_KEY, data);
+    },
+  });
+}
diff --git a/frontend-web/src/pages/PrivateSquareSettingsPage.tsx b/frontend-web/src/pages/PrivateSquareSettingsPage.tsx
new file mode 100644
index 00000000..883adbba
--- /dev/null
+++ b/frontend-web/src/pages/PrivateSquareSettingsPage.tsx
@@ -0,0 +1,155 @@
+"use client";
+
+import { Loader2Icon, ShieldIcon } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Switch } from "@/components/ui/switch";
+import {
+  usePrivateSquareStatus,
+  useUpdatePrivateSquareSettings,
+} from "@/core/system-settings/hooks";
+
+export default function PrivateSquareSettingsPage() {
+  const { data, isLoading, error } = usePrivateSquareStatus();
+  const update = useUpdatePrivateSquareSettings();
+
+  const [enabled, setEnabled] = useState(false);
+  const [password, setPassword] = useState("");
+  const [confirm, setConfirm] = useState("");
+  // The status response never contains the password itself, so re-syncing
+  // ``enabled`` from a refetch wouldn't clobber any in-progress edit — but we
+  // still gate the seed on a one-shot ref to match the prompt-prefix page's
+  // semantics: the admin's draft must not flicker back to the server value if
+  // react-query refetches while they're typing.
+  const initializedRef = useRef(false);
+
+  useEffect(() => {
+    if (!data || initializedRef.current) return;
+    setEnabled(data.enabled);
+    initializedRef.current = true;
+  }, [data]);
+
+  const handleSave = async () => {
+    if (password && password !== confirm) {
+      toast.error("两次输入的密码不一致");
+      return;
+    }
+    try {
+      await update.mutateAsync({
+        enabled,
+        // Only send the password field when the admin typed something —
+        // omitting it leaves the server-side hash untouched. The empty-string
+        // sentinel that clears the password is sent via the explicit "清除
+        // 密码" button below, not by leaving the field blank.
+        ...(password ? { password } : {}),
+      });
+      setPassword("");
+      setConfirm("");
+      toast.success("已保存");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "保存失败");
+    }
+  };
+
+  const handleClearPassword = async () => {
+    if (!window.confirm("确认清除私密广场密码？清除后任何人都将无法访问私密广场。")) {
+      return;
+    }
+    try {
+      await update.mutateAsync({ password: "" });
+      toast.success("已清除密码");
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "清除失败");
+    }
+  };
+
+  return (
+    <div className="mx-auto flex w-full max-w-2xl flex-col gap-6 px-6 py-10">
+      <div>
+        <h1 className="text-xl font-semibold">私密广场配置</h1>
+        <p className="text-muted-foreground mt-1 text-sm">
+          管理员可在此开启「私密广场」，并配置访问密码。开启后，用户可将自己发布的智能体放入私密广场；
+          其他用户只有输入下方设置的密码后，才能在「智能体 → 私密广场」页签下查看到这些智能体。
+        </p>
+      </div>
+
+      {isLoading ? (
+        <div className="flex items-center justify-center py-16">
+          <Loader2Icon className="text-muted-foreground size-6 animate-spin" />
+        </div>
+      ) : error ? (
+        <div className="text-destructive rounded-xl border border-dashed py-16 text-center text-sm">
+          加载失败：{error.message}
+        </div>
+      ) : (
+        <div className="flex flex-col gap-5 rounded-xl border bg-white px-5 py-5">
+          <div className="flex items-center justify-between gap-4">
+            <div>
+              <div className="text-sm font-medium">启用私密广场</div>
+              <div className="text-muted-foreground mt-0.5 text-xs">
+                关闭后，「私密广场」页签不会显示；已放入私密广场的智能体也不会被列出。
+              </div>
+            </div>
+            <Switch checked={enabled} onCheckedChange={setEnabled} />
+          </div>
+
+          <div className="flex flex-col gap-1.5">
+            <p className="text-sm font-medium">
+              访问密码
+              {data?.password_set ? (
+                <span className="text-muted-foreground ml-2 text-xs font-normal">
+                  （已设置，留空则保持不变）
+                </span>
+              ) : (
+                <span className="text-destructive ml-2 text-xs font-normal">
+                  （尚未设置）
+                </span>
+              )}
+            </p>
+            <Input
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              placeholder={
+                data?.password_set ? "留空表示不修改密码" : "请输入访问密码"
+              }
+            />
+          </div>
+
+          <div className="flex flex-col gap-1.5">
+            <p className="text-sm font-medium">确认密码</p>
+            <Input
+              type="password"
+              value={confirm}
+              onChange={(e) => setConfirm(e.target.value)}
+              placeholder="再次输入新密码"
+              disabled={!password}
+            />
+          </div>
+
+          <div className="flex items-center justify-between">
+            <Button
+              variant="ghost"
+              type="button"
+              className="text-destructive hover:text-destructive"
+              onClick={handleClearPassword}
+              disabled={!data?.password_set || update.isPending}
+            >
+              <ShieldIcon className="mr-1.5 size-4" />
+              清除密码
+            </Button>
+            <Button onClick={handleSave} disabled={update.isPending}>
+              {update.isPending && (
+                <Loader2Icon className="mr-1.5 size-4 animate-spin" />
+              )}
+              保存
+            </Button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/frontend-web/src/pages/StrategyRoutes.tsx b/frontend-web/src/pages/StrategyRoutes.tsx
index 1fe204e5..a8c3ff85 100644
--- a/frontend-web/src/pages/StrategyRoutes.tsx
+++ b/frontend-web/src/pages/StrategyRoutes.tsx
@@ -19,6 +19,7 @@ import ScheduledTasksPage from "./ScheduledTasksPage";
 import ScheduledTaskRunDetailPage from "./ScheduledTaskRunDetailPage";
 import RecommendedQuestionsPage from "./RecommendedQuestionsPage";
 import PromptPrefixSettingsPage from "./PromptPrefixSettingsPage";
+import PrivateSquareSettingsPage from "./PrivateSquareSettingsPage";
 import LlmMetricsPage from "./LlmMetricsPage";
 import UsersPage from "./UsersPage";
 import AdminScheduledTasksPage from "./AdminScheduledTasksPage";
@@ -108,6 +109,16 @@ export default function StrategyRoutes() {
             )
           }
         />
+        <Route
+          path="settings/private-square"
+          element={
+            getStoredAuth()?.system_role === "admin" ? (
+              <PrivateSquareSettingsPage />
+            ) : (
+              <Navigate to="/page/workspace/chats/new" replace />
+            )
+          }
+        />
         <Route
           path="settings/llm-metrics"
           element={
diff --git a/frontend-web/src/pages/WorkspaceRoutes.tsx b/frontend-web/src/pages/WorkspaceRoutes.tsx
index a721f0da..3d05b53c 100644
--- a/frontend-web/src/pages/WorkspaceRoutes.tsx
+++ b/frontend-web/src/pages/WorkspaceRoutes.tsx
@@ -24,6 +24,7 @@ import ScheduledTasksPage from "./ScheduledTasksPage";
 import LlmMetricsPage from "./LlmMetricsPage";
 import MemoryPage from "./MemoryPage";
 import PromptPrefixSettingsPage from "./PromptPrefixSettingsPage";
+import PrivateSquareSettingsPage from "./PrivateSquareSettingsPage";
 import SkillEvolutionPage from "./SkillEvolutionPage";
 import SkillsPage from "./SkillsPage";
 import UsersPage from "./UsersPage";
@@ -295,6 +296,18 @@ export default function WorkspaceRoutes({
           )
         }
       />
+      <Route
+        path="settings/private-square"
+        element={
+          getStoredAuth()?.system_role === "admin" ? (
+            <WorkspaceLayout {...layoutProps}>
+              <PrivateSquareSettingsPage />
+            </WorkspaceLayout>
+          ) : (
+            <Navigate to="/page/workspace/chats/new" replace />
+          )
+        }
+      />
       <Route
         path="settings/llm-metrics"
         element={
diff --git a/offline-backend-20260512/backend/app/gateway/routers/agents.py b/offline-backend-20260512/backend/app/gateway/routers/agents.py
index 800c4364..7f21014f 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/agents.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/agents.py
@@ -12,10 +12,12 @@ import yaml
 from fastapi import APIRouter, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 
+from app.gateway.auth.password import verify_password_async
 from app.gateway.deps import get_agent_store, get_tag_store
 from deerflow.config.agents_api_config import get_agents_api_config
 from deerflow.config.agents_config import list_custom_agents, load_agent_config, load_agent_soul, validate_agent_id
 from deerflow.config.paths import get_paths
+from deerflow.config.system_settings import load_system_settings
 from deerflow.persistence.agents import AgentStore
 from deerflow.persistence.tags import TagStore
 from deerflow.runtime.user_context import get_effective_user_id
@@ -32,6 +34,7 @@ class AgentResponse(BaseModel):
     description: str = Field(default="", description="Agent description")
     user_id: str | None = Field(default=None, description="Owner user id. Null means built-in.")
     published: bool = Field(default=False, description="Whether a user-created agent is public")
+    is_private: bool = Field(default=False, description="Whether the agent lives in the password-gated private square instead of the public one")
     builtin: bool = Field(default=False, description="True when user_id is null")
     created_at: datetime | str | None = None
     updated_at: datetime | str | None = None
@@ -68,6 +71,7 @@ class AgentCreateRequest(BaseModel):
     description: str = Field(default="", description="Agent description")
     soul: str = Field(default="", description="SOUL.md content - agent personality and behavioral guardrails")
     published: bool = Field(default=False, description="Whether the new agent should be public")
+    is_private: bool = Field(default=False, description="When True, the new agent goes into the password-gated private square instead of the public one")
     skills: list[str] | None = Field(default=None, description="Skill whitelist persisted to the agent's config.yaml")
     model: str | None = Field(default=None, description="Optional model override persisted to config.yaml")
     tool_groups: list[str] | None = Field(default=None, description="Optional tool group whitelist persisted to config.yaml")
@@ -80,6 +84,7 @@ class AgentUpdateRequest(BaseModel):
     description: str | None = Field(default=None, description="Updated description")
     soul: str | None = Field(default=None, description="Updated SOUL.md content")
     published: bool | None = Field(default=None, description="Updated publication state")
+    is_private: bool | None = Field(default=None, description="Move the agent into / out of the private square (true / false)")
     skills: list[str] | None = Field(default=None, description="Updated skill whitelist (config.yaml)")
     model: str | None = Field(default=None, description="Updated model override (config.yaml)")
     tool_groups: list[str] | None = Field(default=None, description="Updated tool group whitelist (config.yaml)")
@@ -261,6 +266,7 @@ def _record_to_response(
         description=record.get("description") or "",
         user_id=record.get("user_id"),
         published=bool(record.get("published", False)),
+        is_private=bool(record.get("is_private", False)),
         builtin=record.get("user_id") is None,
         created_at=record.get("created_at"),
         updated_at=record.get("updated_at"),
@@ -446,6 +452,7 @@ async def create_agent_endpoint(request: AgentCreateRequest, http_request: Reque
                 "description": request.description or "",
                 "user_id": _current_user_id(http_request),
                 "published": request.published,
+                "is_private": request.is_private,
             }
         )
         logger.info("Created agent '%s' (%s) at %s", name, agent_id, agent_dir)
@@ -486,6 +493,8 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
             update_data["description"] = request.description or ""
         if "published" in fields_set:
             update_data["published"] = bool(request.published)
+        if "is_private" in fields_set:
+            update_data["is_private"] = bool(request.is_private)
 
         next_name = update_data.get("name", current["name"])
         next_description = update_data.get("description", current.get("description") or "")
@@ -662,6 +671,102 @@ async def set_agent_featured(
         raise HTTPException(status_code=500, detail=f"Failed to set featured: {str(e)}") from e
 
 
+class PrivateSquareListRequest(BaseModel):
+    """Request body for listing all private-square agents."""
+
+    password: str = Field(..., description="Plain-text private-square password. Verified against the admin-configured hash before the listing is returned.")
+
+
+class AgentPrivateUpdateRequest(BaseModel):
+    """Admin-only request body for moving an agent into / out of the private square."""
+
+    is_private: bool = Field(..., description="Set true to move the agent into the private square, false to move it back into the public square.")
+
+
+@router.post(
+    "/agents/private-square/list",
+    response_model=AgentsListResponse,
+    summary="List Private-Square Agents",
+    description=(
+        "Verify the admin-configured private-square password and return every "
+        "agent flagged ``is_private=true``. Returns 404 when no password is set, "
+        "403 when the supplied password does not match, and the full agent list "
+        "otherwise — regardless of ownership, since the password is the gate."
+    ),
+)
+async def list_private_square(body: PrivateSquareListRequest, request: Request) -> AgentsListResponse:
+    _require_agents_api_enabled()
+
+    settings = load_system_settings().private_square
+    if not settings.password_hash:
+        raise HTTPException(status_code=404, detail="Private square password is not configured")
+    if not body.password or not await verify_password_async(body.password, settings.password_hash):
+        raise HTTPException(status_code=403, detail="Incorrect private square password")
+
+    try:
+        store = get_agent_store(request)
+        tag_store: TagStore = get_tag_store(request)
+        await _sync_legacy_agents(store)
+        records = await store.list_private()
+        responses = [_record_to_response(r, include_soul=True) for r in records]
+
+        assignments = await tag_store.list_assignments("agent", [r.id for r in responses])
+        for resp in responses:
+            resp.tags = assignments.get(resp.id, [])
+        return AgentsListResponse(agents=responses)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to list private agents: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to list private agents: {str(e)}") from e
+
+
+@router.put(
+    "/agents/{agent_id}/private",
+    response_model=AgentResponse,
+    summary="Move Agent Between Squares (admin)",
+    description=(
+        "Admin-only. Move any agent (built-in or user-owned) into or out of the "
+        "password-gated private square. Owners can already toggle the flag on "
+        "their own agents via the regular ``PUT /agents/{id}`` endpoint; this "
+        "endpoint exists so admins can re-categorize other users' agents too."
+    ),
+)
+async def set_agent_private(
+    agent_id: str,
+    body: AgentPrivateUpdateRequest,
+    request: Request,
+) -> AgentResponse:
+    _require_agents_api_enabled()
+    agent_id = _validate_storage_id(agent_id)
+
+    if not _is_admin_user(request):
+        raise HTTPException(status_code=403, detail="Only system admins can re-categorize other users' agents")
+
+    try:
+        store = get_agent_store(request)
+        await _sync_legacy_agents(store)
+        record = await store.get_any(agent_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+
+        update = {"is_private": bool(body.is_private)}
+        if record.get("user_id") is None:
+            updated = await store.update_builtin(agent_id, update)
+        else:
+            updated = await store.update(agent_id, str(record["user_id"]), update)
+        if updated is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+
+        logger.info("Admin set agent '%s' is_private=%s", agent_id, body.is_private)
+        return _record_to_response(updated, include_soul=True)
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to set is_private for agent '%s': %s", agent_id, e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to update agent: {str(e)}") from e
+
+
 class AgentFeaturedReorderRequest(BaseModel):
     """Request body for admin to bulk-reorder the homepage featured list."""
 
diff --git a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
index 0430a45f..48940387 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
@@ -7,6 +7,7 @@ import logging
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
+from app.gateway.auth.password import hash_password_async
 from app.gateway.deps import get_optional_user_from_request
 from deerflow.config.system_settings import (
     PromptPrefixSettings,
@@ -31,6 +32,22 @@ class PromptPrefixUpdateRequest(BaseModel):
     prompt_prefix: str | None = None
 
 
+class PrivateSquareStatusResponse(BaseModel):
+    """Status of the private-square feature, readable by any logged-in user.
+
+    The password hash itself is **never** returned — the response only signals
+    whether the feature is enabled and whether a password has been set.
+    """
+
+    enabled: bool = Field(..., description="Whether the private square is exposed to users")
+    password_set: bool = Field(..., description="Whether a password is currently configured")
+
+
+class PrivateSquareUpdateRequest(BaseModel):
+    enabled: bool | None = Field(default=None, description="Toggle the private-square feature")
+    password: str | None = Field(default=None, description="New password in plain text. Pass an empty string to clear.")
+
+
 def _to_response(settings: PromptPrefixSettings) -> PromptPrefixResponse:
     return PromptPrefixResponse(
         enabled=settings.enabled,
@@ -61,5 +78,49 @@ async def update_prompt_prefix(body: PromptPrefixUpdateRequest, request: Request
     current = load_system_settings()
     fields = body.model_dump(exclude_unset=True)
     updated_prefix = current.prompt_prefix.model_copy(update=fields)
-    saved = save_system_settings(SystemSettings(prompt_prefix=updated_prefix))
+    saved = save_system_settings(current.model_copy(update={"prompt_prefix": updated_prefix}))
     return _to_response(saved.prompt_prefix)
+
+
+@router.get("/private-square", response_model=PrivateSquareStatusResponse)
+async def get_private_square_status() -> PrivateSquareStatusResponse:
+    """Return whether the private square is enabled and a password is set."""
+    settings = load_system_settings().private_square
+    return PrivateSquareStatusResponse(
+        enabled=settings.enabled,
+        password_set=bool(settings.password_hash),
+    )
+
+
+@router.put("/private-square", response_model=PrivateSquareStatusResponse)
+async def update_private_square(body: PrivateSquareUpdateRequest, request: Request) -> PrivateSquareStatusResponse:
+    """Update the private-square configuration. Admin only.
+
+    Setting ``password`` to a non-empty string rehashes and stores it.
+    Passing an empty string clears the password (effectively locking the
+    private square so no one can read it).
+    """
+    await _require_admin(request)
+
+    current = load_system_settings()
+    updated = current.private_square
+    fields = body.model_dump(exclude_unset=True)
+
+    update: dict[str, object] = {}
+    if "enabled" in fields and fields["enabled"] is not None:
+        update["enabled"] = bool(fields["enabled"])
+    if "password" in fields and fields["password"] is not None:
+        plain = str(fields["password"])
+        if plain == "":
+            update["password_hash"] = ""
+        else:
+            update["password_hash"] = await hash_password_async(plain)
+    if update:
+        updated = updated.model_copy(update=update)
+        saved = save_system_settings(current.model_copy(update={"private_square": updated}))
+    else:
+        saved = current
+    return PrivateSquareStatusResponse(
+        enabled=saved.private_square.enabled,
+        password_set=bool(saved.private_square.password_hash),
+    )
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
index 001f3788..0a2d41ea 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
@@ -37,10 +37,25 @@ class PromptPrefixSettings(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
 
+class PrivateSquareSettings(BaseModel):
+    """Admin-configurable settings for the agent private-square (私密广场).
+
+    The password gates read access to all agents flagged ``is_private=True``.
+    The hash is stored opaquely — the router layer is responsible for hashing
+    and verifying so the harness package keeps zero dependencies on
+    ``app.gateway.auth``.
+    """
+
+    enabled: bool = Field(default=False, description="Whether the private square is offered to users at all")
+    password_hash: str = Field(default="", description="Opaque hash of the admin-configured password. Empty = no password set yet.")
+    model_config = ConfigDict(extra="ignore")
+
+
 class SystemSettings(BaseModel):
     """Top-level system settings document."""
 
     prompt_prefix: PromptPrefixSettings = Field(default_factory=PromptPrefixSettings)
+    private_square: PrivateSquareSettings = Field(default_factory=PrivateSquareSettings)
     model_config = ConfigDict(extra="ignore")
 
 
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
index dc247b7c..39b5e6f7 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
@@ -81,3 +81,12 @@ class AgentStore(ABC):
     async def list_by_ids(self, agent_ids: list[str], user_id: str) -> list[dict[str, Any]]:
         """Return rows for ``agent_ids`` visible to ``user_id``, preserving the input order."""
         raise NotImplementedError
+
+    @abstractmethod
+    async def list_private(self) -> list[dict[str, Any]]:
+        """Return every agent flagged ``is_private=True``.
+
+        Caller is responsible for authorization — typically the caller has
+        already verified the admin-configured private-square password.
+        """
+        raise NotImplementedError
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/model.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/model.py
index 77dde87f..42e2c867 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/model.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/model.py
@@ -21,6 +21,12 @@ class AgentRow(Base):
     description: Mapped[str] = mapped_column(String(1024), nullable=False, default="")
     user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
     published: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, index=True)
+    # When True, the agent is moved into the password-gated "private square"
+    # (私密广场) and is hidden from the regular public square / built-in list.
+    # The flag is independent of ``published``: a private agent is still
+    # visible to its owner in the "我的" tab, and visible to anyone in the
+    # private-square listing once the password has been verified.
+    is_private: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False, index=True)
     # NULL = not featured on the homepage selector. Non-NULL = admin-curated
     # featured rank (lower sorts first). Only ``published=True`` agents are
     # eligible; the router enforces that invariant on writes. BIGINT so the
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
index e72e7102..60474ac5 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
@@ -5,7 +5,7 @@ from __future__ import annotations
 from datetime import UTC, datetime
 from typing import Any
 
-from sqlalchemy import func, or_, select
+from sqlalchemy import and_, func, or_, select
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 from deerflow.persistence.agents.base import AgentStore
@@ -28,10 +28,31 @@ class AgentRepository(AgentStore):
 
     @staticmethod
     def _visible_filter(user_id: str):
+        """Visibility for single-record fetches (``get_visible``).
+
+        Lenient: a caller who already knows the agent id can fetch it even
+        when it's flagged ``is_private``. The private-square password is the
+        *discovery* gate (listings); individual reads are not re-gated, so a
+        bookmarked / linked private agent stays openable.
+        """
         return or_(AgentRow.user_id.is_(None), AgentRow.user_id == user_id, AgentRow.published.is_(True))
 
+    @staticmethod
+    def _listing_filter(user_id: str):
+        """Visibility for *listings* — hides private-square agents from
+        non-owners so they only surface inside the password-gated endpoint.
+        Owners keep seeing their own private agents in '我的'.
+        """
+        return or_(
+            AgentRow.user_id == user_id,
+            and_(
+                or_(AgentRow.user_id.is_(None), AgentRow.published.is_(True)),
+                AgentRow.is_private.is_(False),
+            ),
+        )
+
     async def list_visible(self, user_id: str) -> list[dict[str, Any]]:
-        stmt = select(AgentRow).where(self._visible_filter(user_id)).order_by(AgentRow.created_at.asc())
+        stmt = select(AgentRow).where(self._listing_filter(user_id)).order_by(AgentRow.created_at.asc())
         async with self._sf() as session:
             result = await session.execute(stmt)
             return [_row_to_dict(row) for row in result.scalars()]
@@ -61,6 +82,7 @@ class AgentRepository(AgentStore):
             description=data.get("description") or "",
             user_id=data.get("user_id"),
             published=bool(data.get("published", False)),
+            is_private=bool(data.get("is_private", False)),
             created_at=now,
             updated_at=now,
         )
@@ -99,7 +121,7 @@ class AgentRepository(AgentStore):
             row = await session.get(AgentRow, agent_id)
             if row is None or row.user_id != user_id:
                 return None
-            for key in ("name", "description", "published"):
+            for key in ("name", "description", "published", "is_private"):
                 if key in data:
                     setattr(row, key, data[key])
             row.updated_at = datetime.now(UTC)
@@ -112,7 +134,7 @@ class AgentRepository(AgentStore):
             row = await session.get(AgentRow, agent_id)
             if row is None or row.user_id is not None:
                 return None
-            for key in ("name", "description", "published"):
+            for key in ("name", "description", "published", "is_private"):
                 if key in data:
                     setattr(row, key, data[key])
             row.updated_at = datetime.now(UTC)
@@ -157,7 +179,7 @@ class AgentRepository(AgentStore):
     async def list_featured(self, user_id: str) -> list[dict[str, Any]]:
         stmt = (
             select(AgentRow)
-            .where(AgentRow.featured_order.is_not(None), self._visible_filter(user_id))
+            .where(AgentRow.featured_order.is_not(None), self._listing_filter(user_id))
             .order_by(AgentRow.featured_order.asc(), AgentRow.created_at.asc())
         )
         async with self._sf() as session:
@@ -168,9 +190,15 @@ class AgentRepository(AgentStore):
         if not agent_ids:
             return []
         order_map = {aid: idx for idx, aid in enumerate(agent_ids)}
-        stmt = select(AgentRow).where(AgentRow.id.in_(agent_ids), self._visible_filter(user_id))
+        stmt = select(AgentRow).where(AgentRow.id.in_(agent_ids), self._listing_filter(user_id))
         async with self._sf() as session:
             result = await session.execute(stmt)
             rows = list(result.scalars())
         rows.sort(key=lambda r: order_map.get(r.id, len(order_map)))
         return [_row_to_dict(r) for r in rows]
+
+    async def list_private(self) -> list[dict[str, Any]]:
+        stmt = select(AgentRow).where(AgentRow.is_private.is_(True)).order_by(AgentRow.created_at.asc())
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [_row_to_dict(row) for row in result.scalars()]
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260526_01_agents_is_private.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260526_01_agents_is_private.py
new file mode 100644
index 00000000..1bf004f9
--- /dev/null
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/migrations/versions/20260526_01_agents_is_private.py
@@ -0,0 +1,62 @@
+"""Add ``agents.is_private`` for the private-square (私密广场) feature.
+
+A nullable-default bool column flagging agents that should live in the
+password-gated private square instead of the regular public square.
+
+Revision ID: 20260526_01
+Revises: 20260522_01
+Create Date: 2026-05-26
+"""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import inspect
+
+
+revision = "20260526_01"
+down_revision = "20260522_01"
+branch_labels = None
+depends_on = None
+
+
+def _has_table(table_name: str) -> bool:
+    inspector = inspect(op.get_bind())
+    return table_name in inspector.get_table_names()
+
+
+def _has_column(table_name: str, column_name: str) -> bool:
+    if not _has_table(table_name):
+        return False
+    inspector = inspect(op.get_bind())
+    return any(col["name"] == column_name for col in inspector.get_columns(table_name))
+
+
+def _has_index(table_name: str, index_name: str) -> bool:
+    if not _has_table(table_name):
+        return False
+    inspector = inspect(op.get_bind())
+    return any(idx["name"] == index_name for idx in inspector.get_indexes(table_name))
+
+
+def upgrade() -> None:
+    if _has_table("agents") and not _has_column("agents", "is_private"):
+        op.add_column(
+            "agents",
+            sa.Column(
+                "is_private",
+                sa.Boolean(),
+                nullable=False,
+                server_default=sa.false(),
+            ),
+        )
+    if _has_table("agents") and not _has_index("agents", "ix_agents_is_private"):
+        op.create_index("ix_agents_is_private", "agents", ["is_private"])
+
+
+def downgrade() -> None:
+    if _has_index("agents", "ix_agents_is_private"):
+        op.drop_index("ix_agents_is_private", table_name="agents")
+    if _has_column("agents", "is_private"):
+        op.drop_column("agents", "is_private")

From d3d7db1f34d5cce279488cd9b511c2ea69ebc7c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 14:24:47 +0800
Subject: [PATCH 06/15] =?UTF-8?q?=E6=8A=80=E8=83=BD=E5=B1=95=E7=A4=BA?=
 =?UTF-8?q?=E6=A0=B7=E6=9C=AC=E8=BF=90=E8=A1=8C=E5=99=A8=20+=20=E5=8F=82?=
 =?UTF-8?q?=E8=80=83=E6=96=87=E7=8C=AE=E6=9D=A5=E6=BA=90=E8=BF=87=E6=BB=A4?=
 =?UTF-8?q?=E8=B0=83=E6=95=B4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- skills 路由新增 _run_skill_python_sample，按本地 Python 候选实际执行
  技能脚本，作为展示适配器的真实样本来源
- skill-display 运行时与适配器调整，参考文献收集放宽起始消息约束

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../components/workspace/chats/chat-box.tsx   |  26 +--
 .../src/core/skill-display/display-adapter.ts |  86 +++------
 .../src/core/skill-display/runtime.ts         | 171 ++++++++++++++++--
 .../backend/app/gateway/routers/skills.py     | 124 ++++++++++++-
 4 files changed, 303 insertions(+), 104 deletions(-)

diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index 23ae1bb8..9b41ee95 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -65,25 +65,16 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     () => findLatestHumanMessageIndex(thread.values.messages ?? []),
     [thread.values.messages],
   );
-  const latestAssistant = useMemo(
-    () => findLatestAssistantMessageAfter(thread.values.messages ?? [], latestHumanIndex),
-    [latestHumanIndex, thread.values.messages],
-  );
   const displaySources = useMemo(() => {
     if (!settings.display.ragModeEnabled) {
       return [];
     }
     const messages = thread.values.messages ?? [];
-    if (!latestAssistant?.id) {
-      return [];
-    }
     return collectRuntimeDisplaySources(messages, skillDisplayMap, {
       afterMessageId: latestHumanIndex >= 0 ? messages[latestHumanIndex]?.id : undefined,
-      beforeMessageId: latestAssistant.id,
-      includeBeforeMessage: true,
       includeModes: ["citation"],
     });
-  }, [settings.display.ragModeEnabled, skillDisplayMap, latestAssistant?.id, latestHumanIndex, thread.values.messages]);
+  }, [settings.display.ragModeEnabled, skillDisplayMap, latestHumanIndex, thread.values.messages]);
   const referenceSources = useMemo(
     () => displaySources.filter((source) => source.mode === "citation"),
     [displaySources],
@@ -93,7 +84,7 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     if (hasCitationReferences) {
       setReferencesOpen(true);
     }
-  }, [hasCitationReferences, latestAssistant?.id]);
+  }, [hasCitationReferences]);
   useEffect(() => {
     const handleShowReference = () => {
       setReferencesOpen(true);
@@ -333,17 +324,4 @@ function findLatestHumanMessageIndex(messages: Message[]) {
   return -1;
 }
 
-function findLatestAssistantMessageAfter(messages: Message[], afterIndex: number) {
-  for (let index = messages.length - 1; index >= 0; index--) {
-    if (afterIndex >= 0 && index <= afterIndex) {
-      return null;
-    }
-    const message = messages[index];
-    if (message?.type === "ai") {
-      return message;
-    }
-  }
-  return null;
-}
-
 export { ChatBox };
diff --git a/frontend-web/src/core/skill-display/display-adapter.ts b/frontend-web/src/core/skill-display/display-adapter.ts
index ce63e451..2622bcee 100644
--- a/frontend-web/src/core/skill-display/display-adapter.ts
+++ b/frontend-web/src/core/skill-display/display-adapter.ts
@@ -34,62 +34,6 @@ export const emptyDisplayConfig = (): SkillDisplayConfig => ({
   tableColumns: [],
 });
 
-export const mockKnowledgeSearchV2Result = {
-  success: true,
-  query: "参考文献模式测试 知识库固定测试",
-  count: 4,
-  source: "fixed-display-sample",
-  results: [
-    {
-      index: 1,
-      recUuid: "ksv2-fixed-001",
-      relevance_score: 0.982,
-      title: "参考文献模式测试：参考文献模式固定测试数据一",
-      source_category: "知识库/测试资料",
-      source: "knowledge-search-v2/fixed/source-001",
-      publish_time: "2026-05-25",
-      content_preview:
-        "这是 knowledge-search-v2 返回的第一条固定测试资料，用于验证右侧参考文献列表、正文编号以及 recUuid 模板跳转是否正常。",
-      content_length: 168,
-    },
-    {
-      index: 2,
-      recUuid: "ksv2-fixed-002",
-      relevance_score: 0.936,
-      title: "参考文献模式测试：结构化字段映射验证",
-      source_category: "知识库/字段映射",
-      source: "knowledge-search-v2/fixed/source-002",
-      publish_time: "2026-05-24",
-      content_preview:
-        "本条用于验证 title、source_category、source、publish_time、content_preview、relevance_score、recUuid 等字段能被前端正确识别并渲染。",
-      content_length: 154,
-    },
-    {
-      index: 3,
-      recUuid: "ksv2-fixed-003",
-      relevance_score: 0.887,
-      title: "参考文献模式测试：多引用排序验证",
-      source_category: "知识库/排序验证",
-      source: "knowledge-search-v2/fixed/source-003",
-      publish_time: "2026-05-23",
-      content_preview:
-        "本条用于验证多条参考文献的编号顺序是否与 results 数组顺序一致，并验证点击正文编号时能定位到右侧对应参考文献。",
-      content_length: 132,
-    },
-    {
-      index: 4,
-      recUuid: "",
-      relevance_score: 0.801,
-      title: "参考文献模式测试：无 recUuid 跳转隐藏验证",
-      source_category: "知识库/边界场景",
-      source: "knowledge-search-v2/fixed/source-004",
-      publish_time: "2026-05-22",
-      content_preview: "本条故意把 recUuid 置为空，用于验证右侧弹框仍展示详情，但不展示外部跳转按钮。",
-      content_length: 98,
-    },
-  ],
-};
-
 const candidateFields: Record<string, string[]> = {
   titleField: ["title", "m_title", "name", "subject", "headline"],
   summaryField: ["summary", "snippet", "content_preview", "description", "abstract"],
@@ -99,18 +43,23 @@ const candidateFields: Record<string, string[]> = {
   timeField: ["publish_time", "m_publish", "updatedAt", "createdAt", "date", "time"],
   scoreField: ["relevance_score", "rerank_score", "score", "similarity"],
   urlField: ["url", "link", "href", "source_url"],
-  idField: ["recUuid", "id", "uuid", "docId", "taskId", "recordId"],
+  idField: ["recUuid", "rec_uuid", "uuid", "docId", "taskId", "recordId", "id"],
 };
 
 function getByPath(value: unknown, path: string): unknown {
   if (!path) return value;
   return path.split(".").reduce<unknown>((acc, key) => {
-    if (acc && typeof acc === "object") return (acc as Record<string, unknown>)[key];
+    if (acc && typeof acc === "object") {
+      return (acc as Record<string, unknown>)[key];
+    }
     return undefined;
   }, value);
 }
 
-function findFirstArray(value: unknown, path = ""): { path: string; items: Record<string, unknown>[] } | null {
+function findFirstArray(
+  value: unknown,
+  path = "",
+): { path: string; items: Record<string, unknown>[] } | null {
   if (Array.isArray(value) && value.every((item) => item && typeof item === "object")) {
     return { path, items: value as Record<string, unknown>[] };
   }
@@ -157,12 +106,12 @@ export function inferDisplayConfig(samplePayload: unknown, skillName?: string):
     inferred.typeField = inferred.typeField || "source_category";
     inferred.timeField = inferred.timeField || "publish_time";
     inferred.scoreField = inferred.scoreField || "relevance_score";
-    inferred.idField = inferred.idField || "recUuid";
-    inferred.linkStrategy = "id";
+    inferred.idField = pickField(sample, ["recUuid", "rec_uuid", "uuid", "id"]) || inferred.idField;
+    inferred.linkStrategy = inferred.urlField ? "auto" : "id";
     inferred.linkTemplate = "https://xxx.xxx.xxx?recuuid={recUuid}";
   }
-  inferred.tableColumns = buildDefaultTableColumns(sample, inferred);
 
+  inferred.tableColumns = buildDefaultTableColumns(sample, inferred);
   return inferred;
 }
 
@@ -192,14 +141,18 @@ function stringify(value: unknown, fallback = ""): string {
 }
 
 function renderTemplate(template: string, item: Record<string, unknown>): string {
-  return template.replace(/\{([^}]+)\}/g, (_match, key: string) => encodeURIComponent(stringify(item[key])));
+  return template.replace(/\{([^}]+)\}/g, (_match, key: string) =>
+    encodeURIComponent(stringify(item[key])),
+  );
 }
 
 function resolveLink(item: Record<string, unknown>, config: SkillDisplayConfig): string | undefined {
   const url = config.urlField ? stringify(item[config.urlField]) : "";
   const id = config.idField ? stringify(item[config.idField]) : "";
   if (config.linkStrategy === "url") return url || undefined;
-  if (config.linkStrategy === "id") return id && config.linkTemplate ? renderTemplate(config.linkTemplate, item) : undefined;
+  if (config.linkStrategy === "id") {
+    return id && config.linkTemplate ? renderTemplate(config.linkTemplate, item) : undefined;
+  }
   return url || (id && config.linkTemplate ? renderTemplate(config.linkTemplate, item) : undefined) || undefined;
 }
 
@@ -217,7 +170,10 @@ export function normalizeDisplaySources(payload: unknown, config: SkillDisplayCo
       content: config.contentField ? stringify(item[config.contentField]) : undefined,
       source: config.sourceField ? stringify(item[config.sourceField]) : undefined,
       time: config.timeField ? stringify(item[config.timeField]) : undefined,
-      score: config.scoreField && typeof item[config.scoreField] === "number" ? item[config.scoreField] as number : undefined,
+      score:
+        config.scoreField && typeof item[config.scoreField] === "number"
+          ? (item[config.scoreField] as number)
+          : undefined,
       url: resolveLink(item, config),
       raw: item,
     }));
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
index e91c2164..12447a56 100644
--- a/frontend-web/src/core/skill-display/runtime.ts
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -17,6 +17,12 @@ export type RuntimeDisplaySource = DisplaySourceItem & {
 
 export type SkillDisplayMap = Map<string, SkillDisplayConfig>;
 
+type RuntimeToolCall = {
+  id?: string;
+  name: string;
+  args?: Record<string, unknown>;
+};
+
 export function buildSkillDisplayMap(skills: Skill[]): SkillDisplayMap {
   const map = new Map<string, SkillDisplayConfig>();
   for (const skill of skills) {
@@ -163,13 +169,13 @@ export function collectRuntimeDisplaySources(
     if (!message || message.type !== "ai") {
       continue;
     }
-    for (const toolCall of message.tool_calls ?? []) {
+    for (const toolCall of extractRuntimeToolCalls(message)) {
       const toolMatch = findDisplayConfigForTool(
         toolCall.name,
         displays,
-        toolCall.args as Record<string, unknown> | undefined,
+        toolCall.args,
       );
-      const result = findToolResultPayload(toolCall.id, messages);
+      const result = findToolResultPayload(toolCall, messages, index);
       if (result === undefined) {
         continue;
       }
@@ -192,7 +198,7 @@ export function collectRuntimeDisplaySources(
         : shouldUseDefaultCitationMode(
             toolCall.name,
             result,
-            toolCall.args as Record<string, unknown> | undefined,
+            toolCall.args,
           )
           ? normalizeDefaultDisplaySources(result)
           : [];
@@ -214,6 +220,80 @@ export function collectRuntimeDisplaySources(
   return sources;
 }
 
+function extractRuntimeToolCalls(message: Message): RuntimeToolCall[] {
+  const calls: RuntimeToolCall[] = [];
+  const direct = (message as { tool_calls?: unknown }).tool_calls;
+  if (Array.isArray(direct)) {
+    for (const raw of direct) {
+      const call = normalizeRuntimeToolCall(raw);
+      if (call) {
+        calls.push(call);
+      }
+    }
+  }
+
+  const kwargs = (message as { additional_kwargs?: Record<string, unknown> })
+    .additional_kwargs;
+  const extra = kwargs?.tool_calls;
+  if (Array.isArray(extra)) {
+    for (const raw of extra) {
+      const call = normalizeRuntimeToolCall(raw);
+      if (call && !calls.some((item) => item.id && item.id === call.id)) {
+        calls.push(call);
+      }
+    }
+  }
+
+  const chunks = (message as { tool_call_chunks?: unknown }).tool_call_chunks;
+  if (Array.isArray(chunks)) {
+    for (const raw of chunks) {
+      const call = normalizeRuntimeToolCall(raw);
+      if (call && !calls.some((item) => item.id && item.id === call.id)) {
+        calls.push(call);
+      }
+    }
+  }
+
+  return calls;
+}
+
+function normalizeRuntimeToolCall(raw: unknown): RuntimeToolCall | null {
+  if (!isRecord(raw)) {
+    return null;
+  }
+  const fn = isRecord(raw.function) ? raw.function : null;
+  const name =
+    stringifyMaybe(raw.name) ??
+    stringifyMaybe(fn?.name) ??
+    stringifyMaybe(raw.tool_name);
+  if (!name) {
+    return null;
+  }
+  return {
+    id:
+      stringifyMaybe(raw.id) ??
+      stringifyMaybe(raw.tool_call_id) ??
+      stringifyMaybe(raw.call_id),
+    name,
+    args: normalizeToolArgs(raw.args ?? raw.arguments ?? fn?.arguments),
+  };
+}
+
+function normalizeToolArgs(value: unknown): Record<string, unknown> | undefined {
+  if (isRecord(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    try {
+      const parsed = JSON.parse(value);
+      return isRecord(parsed) ? parsed : undefined;
+    } catch {
+      return { command: value };
+    }
+  }
+  return undefined;
+}
+
 export function findDisplayConfigForPayload(
   toolName: string,
   payload: unknown,
@@ -445,16 +525,18 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 
+function stringifyMaybe(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
 function findToolResultPayload(
-  toolCallId: string | undefined,
+  toolCall: RuntimeToolCall,
   messages: Message[],
+  toolCallMessageIndex = -1,
 ): unknown {
-  if (!toolCallId) {
-    return undefined;
-  }
-  const toolMessage = messages.find(
-    (message) => message.type === "tool" && message.tool_call_id === toolCallId,
-  );
+  const toolMessage =
+    findToolMessageById(toolCall.id, messages) ??
+    findToolMessageByName(toolCall, messages, toolCallMessageIndex);
   if (!toolMessage) {
     return undefined;
   }
@@ -473,6 +555,73 @@ function findToolResultPayload(
   return content;
 }
 
+function findToolMessageById(
+  toolCallId: string | undefined,
+  messages: Message[],
+): Message | undefined {
+  if (!toolCallId) {
+    return undefined;
+  }
+  return messages.find((message) => {
+    if (message.type !== "tool") {
+      return false;
+    }
+    const candidates = [
+      (message as { tool_call_id?: unknown }).tool_call_id,
+      (message as { id?: unknown }).id,
+      (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs
+        ?.tool_call_id,
+      (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs
+        ?.id,
+    ];
+    return candidates.some((candidate) => candidate === toolCallId);
+  });
+}
+
+function findToolMessageByName(
+  toolCall: RuntimeToolCall,
+  messages: Message[],
+  toolCallMessageIndex: number,
+): Message | undefined {
+  const start = Math.max(toolCallMessageIndex + 1, 0);
+  for (let index = start; index < messages.length; index++) {
+    const message = messages[index];
+    if (!message) {
+      continue;
+    }
+    if (index > start && (message.type === "human" || message.type === "ai")) {
+      break;
+    }
+    if (message.type !== "tool") {
+      continue;
+    }
+    const name =
+      stringifyMaybe((message as { name?: unknown }).name) ??
+      stringifyMaybe(
+        (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs
+          ?.name,
+      );
+    const messageToolCallId = stringifyMaybe(
+      (message as { tool_call_id?: unknown }).tool_call_id,
+    );
+    if (messageToolCallId && toolCall.id && messageToolCallId !== toolCall.id) {
+      continue;
+    }
+    if (name && normalizeName(name) !== normalizeName(toolCall.name)) {
+      continue;
+    }
+    const payload = extractStructuredToolPayload(message.content);
+    if (payload !== undefined) {
+      return message;
+    }
+    const text = extractToolText(message.content);
+    if (text && parseJSONLikeText(text) !== undefined) {
+      return message;
+    }
+  }
+  return undefined;
+}
+
 function extractStructuredToolPayload(content: unknown): unknown {
   if (isRecord(content)) {
     return unwrapToolPayloadObject(content);
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index 9d8cbcb3..8fc484a2 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -2,7 +2,10 @@ import asyncio
 import json
 import logging
 import mimetypes
+import os
 import re
+import subprocess
+import sys
 import tempfile
 from datetime import datetime
 from pathlib import Path
@@ -412,6 +415,102 @@ def _extract_json_from_llm_output(raw: str) -> dict[str, Any] | None:
         return None
 
 
+def _skill_sample_python_candidates() -> list[str]:
+    candidates = [
+        os.environ.get("DEERFLOW_SKILL_SAMPLE_PYTHON"),
+        r"C:\Users\ji\anaconda3\envs\open_manus\python.exe",
+        sys.executable,
+        "python",
+    ]
+    result: list[str] = []
+    for candidate in candidates:
+        if not candidate or candidate in result:
+            continue
+        result.append(candidate)
+    return result
+
+
+def _find_skill_sample_script(skill: Skill) -> Path | None:
+    skill_dir = skill.skill_file.parent
+    preferred = [
+        skill_dir / "scripts" / "search.py",
+        skill_dir / "search.py",
+        skill_dir / "scripts" / "run.py",
+        skill_dir / "run.py",
+    ]
+    for path in preferred:
+        if path.exists() and path.is_file():
+            return path
+    scripts_dir = skill_dir / "scripts"
+    if scripts_dir.exists():
+        for path in sorted(scripts_dir.glob("*.py")):
+            if path.is_file():
+                return path
+    return None
+
+
+async def _run_skill_python_sample(skill: Skill) -> dict[str, Any] | None:
+    """Run a skill's Python script to capture a real JSON sample.
+
+    This is used by the display adapter editor. It intentionally runs the same
+    script the agent would run, instead of guessing from SKILL.md examples.
+    """
+    script = _find_skill_sample_script(skill)
+    if script is None:
+        return None
+
+    query = os.environ.get("DEERFLOW_SKILL_SAMPLE_QUERY") or "参考文献模式测试"
+    env = os.environ.copy()
+    env.setdefault("PYTHONIOENCODING", "utf-8")
+    env.setdefault("DEERFLOW_MOCK_KNOWLEDGE_SEARCH", "1")
+    env.setdefault("KNOWLEDGE_SEARCH_V2_FIXED", "1")
+
+    for python_exe in _skill_sample_python_candidates():
+        try:
+            completed = await asyncio.to_thread(
+                subprocess.run,
+                [python_exe, str(script), query],
+                cwd=str(script.parent),
+                env=env,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=60,
+            )
+        except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
+            logger.warning("Skill sample runner failed for %s via %s: %s", skill.name, python_exe, exc)
+            continue
+        except Exception:
+            logger.warning("Skill sample runner crashed for %s via %s", skill.name, python_exe, exc_info=True)
+            continue
+
+        out_text = (completed.stdout or "").strip()
+        err_text = (completed.stderr or "").strip()
+        if completed.returncode != 0:
+            logger.warning(
+                "Skill sample script exited %s for %s via %s: %s",
+                completed.returncode,
+                skill.name,
+                python_exe,
+                err_text[-1000:],
+            )
+            continue
+        parsed = _extract_json_from_llm_output(out_text)
+        if parsed:
+            parsed.setdefault("__sampleSource", "python-script")
+            parsed.setdefault("__sampleScript", str(script))
+            return parsed
+        logger.warning(
+            "Skill sample script returned non-JSON for %s via %s: stdout=%s stderr=%s",
+            skill.name,
+            python_exe,
+            out_text[-1000:],
+            err_text[-1000:],
+        )
+    return None
+
+
 async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) -> dict[str, Any]:
     """Generate a realistic return-shape sample for ``skill`` via the LLM.
 
@@ -420,6 +519,10 @@ async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) ->
     when the model is unconfigured, the call times out, or the output cannot
     be parsed as a JSON object.
     """
+    script_sample = await _run_skill_python_sample(skill)
+    if script_sample:
+        return script_sample
+
     try:
         skill_content = skill.skill_file.read_text(encoding="utf-8")
     except OSError as exc:
@@ -461,7 +564,23 @@ async def _generate_skill_display_sample(skill: Skill, app_config: AppConfig) ->
         logger.warning("Skill display sample LLM call timed out for %s; falling back to static mock", skill.name)
     except Exception:
         logger.warning("Skill display sample LLM call failed for %s; falling back to static mock", skill.name, exc_info=True)
-    return _mock_skill_display_sample(skill.name)
+    return _generic_skill_display_sample(skill.name)
+
+
+def _generic_skill_display_sample(skill_name: str) -> dict[str, Any]:
+    return {
+        "success": True,
+        "query": "sample query",
+        "results": [
+            {
+                "id": f"{skill_name}-sample-001",
+                "title": "Sample result",
+                "summary": "Sample structured output used to infer field mapping.",
+                "source": skill_name,
+                "updatedAt": "2026-05-25",
+            }
+        ],
+    }
 
 
 def _mock_skill_display_sample(skill_name: str) -> dict[str, Any]:
@@ -1883,9 +2002,6 @@ async def get_skill_display_sample(
         skill = next((s for s in skills if s.name == skill_name), None)
         if skill is None:
             raise HTTPException(status_code=404, detail=f"Skill '{skill_name}' not found")
-        adapter = await _get_skill_display_adapter(skill_name)
-        if adapter and isinstance(adapter.get("sample"), dict):
-            return SkillDisplaySampleResponse(skill_name=skill_name, sample=adapter["sample"])
         sample = await _generate_skill_display_sample(skill, config)
         await _upsert_skill_display_adapter(skill_name, sample=sample)
         return SkillDisplaySampleResponse(skill_name=skill_name, sample=sample)

From 8b2f3980156e31e56a6563fd42e645ae36bdc1f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 19:27:03 +0800
Subject: [PATCH 07/15] feat: improve citation display and skill persistence

---
 .../components/workspace/chats/chat-box.tsx   |  92 +++--
 .../workspace/citations/citation-link.tsx     |  13 +-
 .../workspace/messages/message-group.tsx      |   5 +-
 .../workspace/messages/message-list-item.tsx  |  28 +-
 .../settings/appearance-settings-page.tsx     | 126 +++++--
 .../workspace/skill-display-adapter-panel.tsx |  48 ++-
 .../workspace/skill-display-sources.tsx       |  84 ++++-
 frontend-web/src/core/settings/local.ts       |  18 +-
 .../src/core/skill-display/display-adapter.ts |  34 +-
 .../src/core/skill-display/runtime.ts         | 333 ++++++++++++++++--
 frontend-web/src/core/skills/hooks.ts         |  10 +-
 .../backend/app/gateway/routers/skills.py     |  66 ++--
 12 files changed, 721 insertions(+), 136 deletions(-)

diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index 9b41ee95..31ec10d9 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -40,9 +40,11 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   const { thread } = useThread();
   const pathname = usePathname();
   const threadIdRef = useRef(threadId);
+  const artifactsCountRef = useRef(0);
   const layoutRef = useRef<GroupImperativeHandle>(null);
   const [sideTab, setSideTab] = useState("document");
   const [referencesOpen, setReferencesOpen] = useState(true);
+  const [activeReferenceBatchId, setActiveReferenceBatchId] = useState<string | null>(null);
   const [settings] = useLocalSettings();
   const { skills } = useSkills();
 
@@ -61,24 +63,32 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
     [settings.display.ragModeEnabled, skills],
   );
-  const latestHumanIndex = useMemo(
-    () => findLatestHumanMessageIndex(thread.values.messages ?? []),
-    [thread.values.messages],
-  );
-  const displaySources = useMemo(() => {
+  const referenceBatches = useMemo(() => {
     if (!settings.display.ragModeEnabled) {
       return [];
     }
     const messages = thread.values.messages ?? [];
-    return collectRuntimeDisplaySources(messages, skillDisplayMap, {
-      afterMessageId: latestHumanIndex >= 0 ? messages[latestHumanIndex]?.id : undefined,
-      includeModes: ["citation"],
-    });
-  }, [settings.display.ragModeEnabled, skillDisplayMap, latestHumanIndex, thread.values.messages]);
-  const referenceSources = useMemo(
-    () => displaySources.filter((source) => source.mode === "citation"),
-    [displaySources],
-  );
+    return messages
+      .filter((message) => message.type === "ai" && message.id)
+      .map((message) => ({
+        id: message.id!,
+        sources: collectRuntimeDisplaySources(messages, skillDisplayMap, {
+          afterMessageId: findPreviousHumanMessageId(messages, message.id),
+          beforeMessageId: message.id,
+          includeBeforeMessage: true,
+          includeModes: ["citation"],
+        }).filter((source) => source.mode === "citation"),
+      }))
+      .filter((batch) => batch.sources.length > 0);
+  }, [settings.display.ragModeEnabled, skillDisplayMap, thread.values.messages]);
+  const latestReferenceBatch =
+    referenceBatches.length > 0
+      ? referenceBatches[referenceBatches.length - 1]!
+      : null;
+  const activeReferenceBatch =
+    referenceBatches.find((batch) => batch.id === activeReferenceBatchId) ??
+    latestReferenceBatch;
+  const referenceSources = activeReferenceBatch?.sources ?? [];
   const hasCitationReferences = referenceSources.length > 0;
   useEffect(() => {
     if (hasCitationReferences) {
@@ -86,7 +96,22 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
     }
   }, [hasCitationReferences]);
   useEffect(() => {
-    const handleShowReference = () => {
+    if (!latestReferenceBatch) {
+      setActiveReferenceBatchId(null);
+      return;
+    }
+    setActiveReferenceBatchId((current) =>
+      current && referenceBatches.some((batch) => batch.id === current)
+        ? current
+        : latestReferenceBatch.id,
+    );
+  }, [latestReferenceBatch?.id, referenceBatches]);
+  useEffect(() => {
+    const handleShowReference = (event: Event) => {
+      const detail = (event as CustomEvent<{ batchId?: string }>).detail;
+      if (detail?.batchId) {
+        setActiveReferenceBatchId(detail.batchId);
+      }
       setReferencesOpen(true);
       setSideTab("references");
     };
@@ -98,12 +123,22 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   useEffect(() => {
     if (threadIdRef.current !== threadId) {
       threadIdRef.current = threadId;
+      artifactsCountRef.current = 0;
       deselect();
       setReferencesOpen(true);
     }
 
     // Update artifacts from the current thread
-    setArtifacts(thread.values.artifacts);
+    const nextArtifacts = thread.values.artifacts ?? [];
+    const hadArtifacts = artifactsCountRef.current > 0;
+    const hasNewArtifact = nextArtifacts.length > artifactsCountRef.current;
+    artifactsCountRef.current = nextArtifacts.length;
+    setArtifacts(nextArtifacts);
+    if ((hasNewArtifact || (!hadArtifacts && nextArtifacts.length > 0)) && !selectedArtifact) {
+      selectArtifact(nextArtifacts[nextArtifacts.length - 1]!);
+      setArtifactsOpen(true);
+      setSideTab("document");
+    }
 
     // DO NOT automatically deselect the artifact when switching threads, because the artifacts auto discovering is not work now.
     // if (
@@ -142,10 +177,10 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   const showTabs = !!selectedArtifact && hasCitationReferences;
 
   useEffect(() => {
-    if (!selectedArtifact && hasCitationReferences) {
-      setSideTab("references");
-    } else if (selectedArtifact && !hasCitationReferences) {
+    if (selectedArtifact) {
       setSideTab("document");
+    } else if (hasCitationReferences) {
+      setSideTab("references");
     }
   }, [hasCitationReferences, selectedArtifact]);
 
@@ -315,13 +350,22 @@ function ReferencePanel({
   );
 }
 
-function findLatestHumanMessageIndex(messages: Message[]) {
-  for (let index = messages.length - 1; index >= 0; index--) {
-    if (messages[index]?.type === "human") {
-      return index;
+function findPreviousHumanMessageId(
+  messages: Message[],
+  beforeMessageId?: string,
+): string | undefined {
+  const beforeIndex =
+    beforeMessageId === undefined
+      ? messages.length
+      : messages.findIndex((message) => message.id === beforeMessageId);
+  const end = beforeIndex < 0 ? messages.length : beforeIndex;
+  for (let index = end - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message?.type === "human") {
+      return message.id;
     }
   }
-  return -1;
+  return undefined;
 }
 
 export { ChatBox };
diff --git a/frontend-web/src/components/workspace/citations/citation-link.tsx b/frontend-web/src/components/workspace/citations/citation-link.tsx
index 58b7c22a..438cbc99 100644
--- a/frontend-web/src/components/workspace/citations/citation-link.tsx
+++ b/frontend-web/src/components/workspace/citations/citation-link.tsx
@@ -28,20 +28,19 @@ export function CitationLink({
         )}
         onClick={(event) => {
           event.preventDefault();
+          const batchId =
+            event.currentTarget.closest<HTMLElement>("[data-reference-batch-id]")
+              ?.dataset.referenceBatchId;
           window.dispatchEvent(
             new CustomEvent(SHOW_REFERENCE_EVENT, {
-              detail: { referenceId },
+              detail: { batchId, referenceId },
             }),
           );
-          const target = document.getElementById(`reference-${referenceId}`);
           const scroll = () => {
+            const target = document.getElementById(`reference-${referenceId}`);
             target?.scrollIntoView({ behavior: "smooth", block: "center" });
           };
-          if (target) {
-            scroll();
-          } else {
-            window.setTimeout(scroll, 220);
-          }
+          window.setTimeout(scroll, 240);
         }}
         {...props}
       >
diff --git a/frontend-web/src/components/workspace/messages/message-group.tsx b/frontend-web/src/components/workspace/messages/message-group.tsx
index aabf5bc8..d354373d 100644
--- a/frontend-web/src/components/workspace/messages/message-group.tsx
+++ b/frontend-web/src/components/workspace/messages/message-group.tsx
@@ -51,7 +51,6 @@ import { useLocalSettings } from "@/core/settings";
 import { useSkills } from "@/core/skills/hooks";
 import {
   buildSkillDisplayMap,
-  findDisplayConfigForPayload,
   findDisplayConfigForTool,
   isDisplaySamplePayload,
   normalizeDefaultDisplaySources,
@@ -256,9 +255,7 @@ function ToolCall({
     result !== undefined && isDisplaySamplePayload(result)
       ? null
       : (findDisplayConfigForTool(name, skillDisplayMap, args) ??
-        (result !== undefined
-          ? findDisplayConfigForPayload(name, result, skillDisplayMap)
-          : null));
+        null);
   const displayItems =
     displayMatch && result !== undefined
       ? normalizeDisplaySources(result, displayMatch.display).map((item, index) => ({
diff --git a/frontend-web/src/components/workspace/messages/message-list-item.tsx b/frontend-web/src/components/workspace/messages/message-list-item.tsx
index f40801c7..f586f9de 100644
--- a/frontend-web/src/components/workspace/messages/message-list-item.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list-item.tsx
@@ -288,19 +288,21 @@ function MessageContent_({
     );
   }
 
-  return (
-    <AIElementMessageContent className={className}>
-      {filesList}
-      <AssistantDisplayContent
-        content={contentToDisplay}
-        displaySources={displaySources}
-        isLoading={isLoading}
-        rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
-        components={components}
-      />
-      <MessageTokenUsage
-        enabled={tokenUsageEnabled}
-        isLoading={isLoading}
+  return (
+    <AIElementMessageContent className={className}>
+      {filesList}
+      <div data-reference-batch-id={message.id} className="contents">
+        <AssistantDisplayContent
+          content={contentToDisplay}
+          displaySources={displaySources}
+          isLoading={isLoading}
+          rehypePlugins={[...rehypePlugins, [rehypeKatex, { output: "html" }]]}
+          components={components}
+        />
+      </div>
+      <MessageTokenUsage
+        enabled={tokenUsageEnabled}
+        isLoading={isLoading}
         message={message}
       />
     </AIElementMessageContent>
diff --git a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
index 1a35e372..b1498420 100644
--- a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
+++ b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
@@ -2,9 +2,11 @@
 
 import { MoonIcon, SunIcon } from "lucide-react";
 import { useMemo, type ComponentType, type SVGProps } from "react";
+import { toast } from "sonner";
 
 import { useTheme } from "@/contexts/ThemeContext";
 
+import { Button } from "@/components/ui/button";
 import {
   Select,
   SelectContent,
@@ -14,9 +16,15 @@ import {
 } from "@/components/ui/select";
 import { Separator } from "@/components/ui/separator";
 import { Switch } from "@/components/ui/switch";
+import { Textarea } from "@/components/ui/textarea";
+import { getStoredAuth } from "@/core/auth";
 import { enUS, isLocale, zhCN, type Locale } from "@/core/i18n";
 import { useI18n } from "@/core/i18n/hooks";
 import { useLocalSettings } from "@/core/settings";
+import {
+  useAppearanceSettings,
+  useUpdateAppearanceSettings,
+} from "@/core/system-settings/hooks";
 import { cn } from "@/lib/utils";
 
 import { SettingsSection } from "./settings-section";
@@ -31,6 +39,24 @@ export function AppearanceSettingsPage() {
   const { theme, setTheme } = useTheme();
   const currentTheme = theme;
   const [settings, setSettings] = useLocalSettings();
+  const isAdmin = getStoredAuth()?.system_role === "admin";
+  const { data: appearance } = useAppearanceSettings();
+  const updateAppearance = useUpdateAppearanceSettings();
+  const globalDefault = appearance?.default_theme ?? "light";
+
+  const handleSetGlobalDefault = async (value: "light" | "dark") => {
+    if (value === globalDefault) return;
+    try {
+      await updateAppearance.mutateAsync({ default_theme: value });
+      toast.success(
+        value === "light"
+          ? "已将系统默认主题设置为浅色"
+          : "已将系统默认主题设置为深色",
+      );
+    } catch (e) {
+      toast.error(e instanceof Error ? e.message : "保存失败");
+    }
+  };
 
   const themeOptions = useMemo(
     () => [
@@ -76,6 +102,43 @@ export function AppearanceSettingsPage() {
         </div>
       </SettingsSection>
 
+      {isAdmin && (
+        <>
+          <Separator />
+          <SettingsSection
+            title="系统默认主题（管理员）"
+            description="给所有还没有手动切换过主题的用户的默认主题；已经自己切换过的用户保留其个人设置不受影响。"
+          >
+            <div className="flex flex-wrap items-center gap-2">
+              <Button
+                type="button"
+                variant={globalDefault === "light" ? "default" : "outline"}
+                size="sm"
+                onClick={() => void handleSetGlobalDefault("light")}
+                disabled={updateAppearance.isPending}
+              >
+                <SunIcon className="mr-1.5 size-4" />
+                浅色
+              </Button>
+              <Button
+                type="button"
+                variant={globalDefault === "dark" ? "default" : "outline"}
+                size="sm"
+                onClick={() => void handleSetGlobalDefault("dark")}
+                disabled={updateAppearance.isPending}
+              >
+                <MoonIcon className="mr-1.5 size-4" />
+                深色
+              </Button>
+              <p className="text-muted-foreground ml-2 text-xs">
+                当前系统默认：
+                {globalDefault === "light" ? "浅色" : "深色"}
+              </p>
+            </div>
+          </SettingsSection>
+        </>
+      )}
+
       <Separator />
 
       <SettingsSection
@@ -124,26 +187,49 @@ export function AppearanceSettingsPage() {
             }
             aria-label="回答速度指示器"
           />
-        </div>
-        <div className="flex items-start justify-between gap-4 rounded-lg border p-4">
-          <div>
-            <div className="text-sm font-medium">RAG 引用模式</div>
-            <p className="text-muted-foreground mt-1 max-w-md text-xs leading-relaxed">
-              开启后，已配置展示适配的技能结果会在问答中渲染为编号引用或列表，并支持点击跳转。
-            </p>
-          </div>
-          <Switch
-            checked={settings.display.ragModeEnabled}
-            onCheckedChange={(checked) =>
-              setSettings("display", { ragModeEnabled: checked })
-            }
-            aria-label="RAG 引用模式"
-          />
-        </div>
-      </SettingsSection>
-    </div>
-  );
-}
+        </div>
+        <div className="flex items-start justify-between gap-4 rounded-lg border p-4">
+          <div>
+            <div className="text-sm font-medium">RAG 引用模式</div>
+            <p className="text-muted-foreground mt-1 max-w-md text-xs leading-relaxed">
+              开启后，已配置展示适配的技能结果会在问答中渲染为编号引用或列表，并支持点击跳转。
+            </p>
+          </div>
+          <Switch
+            checked={settings.display.ragModeEnabled}
+            onCheckedChange={(checked) =>
+              setSettings("display", { ragModeEnabled: checked })
+            }
+            aria-label="RAG 引用模式"
+          />
+        </div>
+        {isAdmin && (
+          <div className="rounded-lg border p-4">
+            <div className="mb-3">
+              <div className="text-sm font-medium">参考文献去除词</div>
+              <p className="text-muted-foreground mt-1 max-w-2xl text-xs leading-relaxed">
+                管理员配置。每行一个词或短句，参考文献卡片和详情弹框会自动移除这些广告词、导航词或免责声明。
+              </p>
+            </div>
+            <Textarea
+              value={(settings.display.citationCleanupWords ?? []).join("\n")}
+              onChange={(event) =>
+                setSettings("display", {
+                  citationCleanupWords: event.currentTarget.value
+                    .split(/\r?\n/)
+                    .map((item) => item.trim())
+                    .filter(Boolean),
+                })
+              }
+              placeholder={"广告\n点击下载APP\n打开客户端\n免责声明\n责任编辑"}
+              className="min-h-32 text-sm"
+            />
+          </div>
+        )}
+      </SettingsSection>
+    </div>
+  );
+}
 
 function ThemePreviewCard({
   icon: Icon,
diff --git a/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
index 5ae5cbd6..2c32fe7f 100644
--- a/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
+++ b/frontend-web/src/components/workspace/skill-display-adapter-panel.tsx
@@ -22,6 +22,7 @@ import {
   normalizeDisplaySources,
 } from "@/core/skill-display/display-adapter";
 import {
+  getSkill,
   getPersistedSkillDisplaySample,
   getSkillDisplaySample,
 } from "@/core/skills/api";
@@ -76,6 +77,7 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
   const [draft, setDraft] = useState<SkillDisplayConfig>(() => skill.display ?? emptyDisplayConfig());
   const [sampleText, setSampleText] = useState(() => formatSample(skill.displaySample));
   const [tableColumnsText, setTableColumnsText] = useState(() => JSON.stringify((skill.display ?? emptyDisplayConfig()).tableColumns ?? [], null, 2));
+  const [loadingDbConfig, setLoadingDbConfig] = useState(false);
 
   // Echo server state into the form — on mount, on skill switch, AND after
   // a successful save (the refetched skill object has a new `display` identity).
@@ -88,6 +90,41 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
     setTableColumnsText(JSON.stringify(display.tableColumns ?? [], null, 2));
   }, [skill.name, skill.display]);
 
+  useEffect(() => {
+    let cancelled = false;
+    async function loadDbSkillConfig() {
+      setLoadingDbConfig(true);
+      try {
+        const fresh = await getSkill(skill.name);
+        if (cancelled) {
+          return;
+        }
+        const display = fresh.display ?? emptyDisplayConfig();
+        setDraft(display);
+        setTableColumnsText(JSON.stringify(display.tableColumns ?? [], null, 2));
+        setSampleText(formatSample(fresh.displaySample));
+        queryClient.setQueryData<Skill | undefined>(["skill", skill.name], fresh);
+        queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
+          Array.isArray(current)
+            ? current.map((item) => (item.name === skill.name ? { ...item, ...fresh } : item))
+            : current,
+        );
+      } catch (err) {
+        if (!cancelled) {
+          toast.error(err instanceof Error ? err.message : String(err));
+        }
+      } finally {
+        if (!cancelled) {
+          setLoadingDbConfig(false);
+        }
+      }
+    }
+    void loadDbSkillConfig();
+    return () => {
+      cancelled = true;
+    };
+  }, [queryClient, skill.name]);
+
   // Sample text is editor-only state — never reset on save. Only seed it once
   // per skill, otherwise the user loses the JSON they just pulled in via
   // 自动识别 every time they hit 保存.
@@ -191,11 +228,15 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
 
   async function saveDraft() {
     try {
-      await setDisplay.mutateAsync({
+      const saved = await setDisplay.mutateAsync({
         skillName: skill.name,
         display: draft,
         sample: samplePayload ?? undefined,
       });
+      const display = saved.display ?? emptyDisplayConfig();
+      setDraft(display);
+      setTableColumnsText(JSON.stringify(display.tableColumns ?? [], null, 2));
+      setSampleText(formatSample(saved.displaySample));
       toast.success("展示适配已保存");
     } catch (err) {
       toast.error(err instanceof Error ? err.message : String(err));
@@ -222,6 +263,11 @@ export function SkillDisplayAdapterPanel({ skill }: { skill: Skill }) {
             <p className="mt-1 text-xs text-muted-foreground">
               从技能返回样例中自动识别字段，然后把技能结果显示为编号引用、列表、卡片或自定义样式。
             </p>
+            {loadingDbConfig && (
+              <p className="mt-1 text-xs text-muted-foreground">
+                正在从数据库读取已保存的配置...
+              </p>
+            )}
           </div>
           <div className="flex items-center gap-2">
             <span className="text-xs text-muted-foreground">启用</span>
diff --git a/frontend-web/src/components/workspace/skill-display-sources.tsx b/frontend-web/src/components/workspace/skill-display-sources.tsx
index 0c5bfcdf..7bbf609d 100644
--- a/frontend-web/src/components/workspace/skill-display-sources.tsx
+++ b/frontend-web/src/components/workspace/skill-display-sources.tsx
@@ -9,6 +9,7 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog";
 import type { RuntimeDisplaySource } from "@/core/skill-display/runtime";
+import { useLocalSettings } from "@/core/settings";
 import { cn } from "@/lib/utils";
 import { useState } from "react";
 
@@ -44,7 +45,11 @@ export function SourceCard({
   referenceTarget?: boolean;
 }) {
   const [open, setOpen] = useState(false);
-  const content = source.content || source.snippet;
+  const [settings] = useLocalSettings();
+  const cleanupWords = settings.display.citationCleanupWords ?? [];
+  const content = cleanReferenceText(source.content || source.snippet, cleanupWords);
+  const snippet = compactReferenceText(content).slice(0, 280);
+  const paragraphs = segmentReferenceText(content);
   const score =
     typeof source.score === "number"
       ? source.score <= 1
@@ -90,9 +95,9 @@ export function SourceCard({
                 ))}
               </div>
             )}
-            {content && (
+            {snippet && (
               <p className="text-muted-foreground/90 line-clamp-2 text-xs leading-relaxed">
-                {content}
+                {snippet}
               </p>
             )}
           </div>
@@ -138,9 +143,13 @@ export function SourceCard({
               )}
             </div>
           </DialogHeader>
-          {content && (
-            <div className="text-foreground max-h-[55vh] overflow-y-auto whitespace-pre-wrap text-sm leading-relaxed">
-              {content}
+          {paragraphs.length > 0 && (
+            <div className="text-foreground max-h-[55vh] space-y-3 overflow-y-auto text-sm leading-relaxed">
+              {paragraphs.map((paragraph, index) => (
+                <p key={index} className="whitespace-pre-wrap">
+                  {paragraph}
+                </p>
+              ))}
             </div>
           )}
           {source.url && (
@@ -153,3 +162,66 @@ export function SourceCard({
     </>
   );
 }
+
+function cleanReferenceText(
+  raw: string | undefined,
+  cleanupWords: string[],
+): string {
+  let text = raw ?? "";
+  for (const word of cleanupWords) {
+    const trimmed = word.trim();
+    if (!trimmed) continue;
+    text = text.split(trimmed).join("");
+  }
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function compactReferenceText(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+function segmentReferenceText(text: string): string[] {
+  const explicit = text
+    .split(/\n{2,}/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  const base = explicit.length > 1 ? explicit : splitLongParagraph(text);
+  return base.slice(0, 80);
+}
+
+function splitLongParagraph(text: string): string[] {
+  const normalized = text
+    .split(/\n+/)
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .join("\n");
+  if (normalized.length <= 360) {
+    return normalized ? [normalized] : [];
+  }
+
+  const sentences = normalized
+    .split(/(?<=[。！？!?；;])\s*/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (sentences.length <= 1) {
+    return normalized.match(/[\s\S]{1,360}/g) ?? [];
+  }
+
+  const paragraphs: string[] = [];
+  let current = "";
+  for (const sentence of sentences) {
+    if ((current + sentence).length > 360 && current) {
+      paragraphs.push(current.trim());
+      current = "";
+    }
+    current += sentence;
+  }
+  if (current.trim()) {
+    paragraphs.push(current.trim());
+  }
+  return paragraphs;
+}
diff --git a/frontend-web/src/core/settings/local.ts b/frontend-web/src/core/settings/local.ts
index 36c19ffc..0e9080fe 100644
--- a/frontend-web/src/core/settings/local.ts
+++ b/frontend-web/src/core/settings/local.ts
@@ -4,10 +4,11 @@ export const DEFAULT_LOCAL_SETTINGS: LocalSettings = {
   notification: {
     enabled: true,
   },
-  display: {
-    streamSpeedMeterEnabled: true,
-    ragModeEnabled: false,
-  },
+  display: {
+    streamSpeedMeterEnabled: true,
+    ragModeEnabled: false,
+    citationCleanupWords: [],
+  },
   context: {
     model_name: undefined,
     mode: undefined,
@@ -38,8 +39,13 @@ export interface LocalSettings {
      * Global switch for skill result display adapters. When disabled, chat
      * messages render tool results with the legacy generic search UI only.
      */
-    ragModeEnabled: boolean;
-  };
+    ragModeEnabled: boolean;
+    /**
+     * Admin-maintained words or short phrases removed from reference snippets
+     * and dialogs, one entry per line in the settings UI.
+     */
+    citationCleanupWords: string[];
+  };
   context: Omit<
     AgentThreadContext,
     | "thread_id"
diff --git a/frontend-web/src/core/skill-display/display-adapter.ts b/frontend-web/src/core/skill-display/display-adapter.ts
index 2622bcee..05d30365 100644
--- a/frontend-web/src/core/skill-display/display-adapter.ts
+++ b/frontend-web/src/core/skill-display/display-adapter.ts
@@ -1,5 +1,9 @@
 import type { SkillDisplayConfig } from "@/core/skills/type";
 
+const DEFAULT_CITATION_MAX_ITEMS = 100;
+const DEFAULT_LIST_MAX_ITEMS = 20;
+const MAX_DISPLAY_ITEMS = 100;
+
 export interface DisplaySourceItem {
   id?: string;
   title: string;
@@ -29,7 +33,7 @@ export const emptyDisplayConfig = (): SkillDisplayConfig => ({
   linkStrategy: "auto",
   linkTemplate: null,
   citationToken: "doubleBracket",
-  maxItems: 8,
+  maxItems: DEFAULT_CITATION_MAX_ITEMS,
   customInstruction: "",
   tableColumns: [],
 });
@@ -92,7 +96,7 @@ export function inferDisplayConfig(samplePayload: unknown, skillName?: string):
   inferred.enabled = true;
   inferred.mode = skillName === "knowledge-search-v2" ? "citation" : "list";
   inferred.resultPath = found.path || "results";
-  inferred.maxItems = inferred.mode === "citation" ? 8 : 20;
+  inferred.maxItems = inferMaxItems(found.items.length, inferred.mode);
 
   for (const [target, candidates] of Object.entries(candidateFields)) {
     (inferred as unknown as Record<string, string | null>)[target] = pickField(sample, candidates);
@@ -159,9 +163,10 @@ function resolveLink(item: Record<string, unknown>, config: SkillDisplayConfig):
 export function normalizeDisplaySources(payload: unknown, config: SkillDisplayConfig): DisplaySourceItem[] {
   const rawItems = getByPath(payload, config.resultPath);
   if (!Array.isArray(rawItems)) return [];
+  const maxItems = resolveMaxItems(config, rawItems.length);
   return rawItems
     .filter((item): item is Record<string, unknown> => !!item && typeof item === "object")
-    .slice(0, config.maxItems)
+    .slice(0, maxItems)
     .map((item, index) => ({
       id: config.idField ? stringify(item[config.idField]) : undefined,
       title: config.titleField ? stringify(item[config.titleField], `结果 ${index + 1}`) : `结果 ${index + 1}`,
@@ -178,3 +183,26 @@ export function normalizeDisplaySources(payload: unknown, config: SkillDisplayCo
       raw: item,
     }));
 }
+
+function inferMaxItems(
+  itemCount: number,
+  mode: SkillDisplayConfig["mode"],
+): number {
+  const fallback =
+    mode === "citation" ? DEFAULT_CITATION_MAX_ITEMS : DEFAULT_LIST_MAX_ITEMS;
+  return Math.min(
+    MAX_DISPLAY_ITEMS,
+    Math.max(fallback, itemCount || fallback),
+  );
+}
+
+function resolveMaxItems(config: SkillDisplayConfig, itemCount: number): number {
+  const configured = Number(config.maxItems) || 0;
+  if (config.mode === "citation" && configured <= 8 && itemCount > configured) {
+    return Math.min(itemCount, MAX_DISPLAY_ITEMS);
+  }
+  return Math.min(
+    MAX_DISPLAY_ITEMS,
+    Math.max(1, configured || inferMaxItems(itemCount, config.mode)),
+  );
+}
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
index 12447a56..5d73b5f0 100644
--- a/frontend-web/src/core/skill-display/runtime.ts
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -15,6 +15,8 @@ export type RuntimeDisplaySource = DisplaySourceItem & {
   tableColumns?: SkillDisplayConfig["tableColumns"];
 };
 
+type RuntimeDisplaySourceDraft = Omit<RuntimeDisplaySource, "index">;
+
 export type SkillDisplayMap = Map<string, SkillDisplayConfig>;
 
 type RuntimeToolCall = {
@@ -163,6 +165,9 @@ export function collectRuntimeDisplaySources(
   const sources: RuntimeDisplaySource[] = [];
   let citationIndex = 0;
   const displayIndexes = new Map<string, number>();
+  const seenCitationKeys = new Map<string, RuntimeDisplaySource>();
+  const seenDisplayKeys = new Set<string>();
+  const consumedToolMessageIds = new Set<string>();
 
   for (let index = start; index < limit; index++) {
     const message = messages[index];
@@ -179,16 +184,14 @@ export function collectRuntimeDisplaySources(
       if (result === undefined) {
         continue;
       }
+      const linkedToolMessage = findToolMessageById(toolCall.id, messages);
+      if (linkedToolMessage?.id) {
+        consumedToolMessageIds.add(linkedToolMessage.id);
+      }
       if (isDisplaySamplePayload(result)) {
         continue;
       }
-      const match =
-        toolMatch ??
-        findDisplayConfigForPayload(
-          toolCall.name,
-          result,
-          displays,
-        );
+      const match = toolMatch;
       const effectiveMode = match?.display.mode ?? "citation";
       if (allowedModes && !allowedModes.has(effectiveMode)) {
         continue;
@@ -202,24 +205,144 @@ export function collectRuntimeDisplaySources(
           )
           ? normalizeDefaultDisplaySources(result)
           : [];
-      for (const item of normalized) {
-        const skillName = match?.skillName ?? toolCall.name;
-        const displayKey = `${skillName}:${effectiveMode}`;
-        const displayIndex = (displayIndexes.get(displayKey) ?? 0) + 1;
-        displayIndexes.set(displayKey, displayIndex);
-        sources.push({
+      appendDisplaySources(
+        sources,
+        normalized.map((item) => ({
           ...item,
-          index: effectiveMode === "citation" ? ++citationIndex : displayIndex,
-          skillName,
+          skillName: match?.skillName ?? toolCall.name,
           mode: effectiveMode,
           tableColumns: match?.display.tableColumns,
-        });
-      }
+        })),
+        displayIndexes,
+        seenCitationKeys,
+        seenDisplayKeys,
+        () => ++citationIndex,
+      );
     }
   }
+
+  for (let index = start; index < limit; index++) {
+    const message = messages[index];
+    if (!message || message.type !== "tool" || consumedToolMessageIds.has(message.id ?? "")) {
+      continue;
+    }
+    const result = parseToolMessagePayload(message);
+    if (result === undefined || isDisplaySamplePayload(result)) {
+      continue;
+    }
+    const toolName = extractToolMessageName(message);
+    const match = null;
+    const effectiveMode = match?.display.mode ?? "citation";
+    if (allowedModes && !allowedModes.has(effectiveMode)) {
+      continue;
+    }
+    const normalized = match
+      ? normalizeDisplaySources(result, match.display)
+      : shouldUseDefaultCitationMode(toolName, result)
+        ? normalizeDefaultDisplaySources(result)
+        : [];
+    appendDisplaySources(
+      sources,
+      normalized.map((item) => ({
+        ...item,
+        skillName: match?.skillName ?? toolName,
+        mode: effectiveMode,
+        tableColumns: match?.display.tableColumns,
+      })),
+      displayIndexes,
+      seenCitationKeys,
+      seenDisplayKeys,
+      () => ++citationIndex,
+    );
+  }
   return sources;
 }
 
+function appendDisplaySources(
+  target: RuntimeDisplaySource[],
+  drafts: RuntimeDisplaySourceDraft[],
+  displayIndexes: Map<string, number>,
+  seenCitationKeys: Map<string, RuntimeDisplaySource>,
+  seenDisplayKeys: Set<string>,
+  nextCitationIndex: () => number,
+) {
+  for (const draft of drafts) {
+    if (draft.mode === "citation") {
+      const key = citationSourceKey(draft);
+      const existing = seenCitationKeys.get(key);
+      if (existing) {
+        continue;
+      }
+      const source = {
+        ...draft,
+        index: nextCitationIndex(),
+      };
+      seenCitationKeys.set(key, source);
+      target.push(source);
+      continue;
+    }
+
+    const stableKey = nonCitationSourceKey(draft);
+    if (seenDisplayKeys.has(stableKey)) {
+      continue;
+    }
+    seenDisplayKeys.add(stableKey);
+    const displayKey = `${draft.skillName}:${draft.mode}`;
+    const displayIndex = (displayIndexes.get(displayKey) ?? 0) + 1;
+    displayIndexes.set(displayKey, displayIndex);
+    target.push({
+      ...draft,
+      index: displayIndex,
+    });
+  }
+}
+
+export function reindexRuntimeDisplaySources(
+  sources: RuntimeDisplaySource[],
+  globalSources: RuntimeDisplaySource[],
+): RuntimeDisplaySource[] {
+  if (sources.length === 0 || globalSources.length === 0) {
+    return sources;
+  }
+  const globalByKey = new Map(
+    globalSources.map((source) => [citationSourceKey(source), source]),
+  );
+  return sources.map((source) => {
+    if (source.mode !== "citation") {
+      return source;
+    }
+    const global = globalByKey.get(citationSourceKey(source));
+    return global
+      ? {
+          ...source,
+          index: global.index,
+        }
+      : source;
+  });
+}
+
+function citationSourceKey(source: RuntimeDisplaySourceDraft): string {
+  const raw = source.raw ?? {};
+  const id =
+    source.id ||
+    source.url ||
+    stringifyMaybe(raw.recUuid) ||
+    stringifyMaybe(raw.uuid) ||
+    stringifyMaybe(raw.docId) ||
+    stringifyMaybe(raw.id);
+  if (id) {
+    return normalizeName(`${source.skillName}:${id}`);
+  }
+  const fallback = [source.skillName, source.title, source.source, source.time]
+    .filter(Boolean)
+    .join("|");
+  return normalizeName(fallback) || JSON.stringify(raw).slice(0, 300);
+}
+
+function nonCitationSourceKey(source: RuntimeDisplaySourceDraft): string {
+  return `${source.skillName}:${source.mode}:${citationSourceKey(source)}`;
+}
+
 function extractRuntimeToolCalls(message: Message): RuntimeToolCall[] {
   const calls: RuntimeToolCall[] = [];
   const direct = (message as { tool_calls?: unknown }).tool_calls;
@@ -312,6 +435,18 @@ export function findDisplayConfigForPayload(
   return best ? { skillName: best.skillName, display: best.display } : null;
 }
 
+export function isUnconfiguredSkillInvocation(
+  toolName: string,
+  displays: SkillDisplayMap | undefined,
+  toolArgs?: Record<string, unknown>,
+): boolean {
+  if (!toolArgs || !canInferSkillFromToolArgs(toolName)) {
+    return false;
+  }
+  const skillName = extractSkillNameFromArgs(toolArgs);
+  return !!skillName && !displays?.has(skillName);
+}
+
 export function isDisplaySamplePayload(payload: unknown): boolean {
   if (!isRecord(payload)) {
     return false;
@@ -443,31 +578,59 @@ export function applyInlineCitations(
     }
   }
 
-  const normalized = normalizeExistingCitationLinks(content, byIndex, byUrl, byTitle);
+  const normalized = normalizeExistingCitationLinks(
+    content,
+    byIndex,
+    byUrl,
+    byTitle,
+    citationSources,
+  );
 
   const markdownLinkPattern = /!?\[(?:[^\[\]]|\[[^\]]*\])*\]\([^)]+\)/g;
   let cursor = 0;
   let next = "";
+  let replaced = false;
   for (const match of normalized.matchAll(markdownLinkPattern)) {
     const start = match.index ?? 0;
-    next += replaceCitationTokens(normalized.slice(cursor, start), byIndex);
+    const replacedSlice = replaceCitationTokens(
+      normalized.slice(cursor, start),
+      byIndex,
+      citationSources,
+    );
+    if (replacedSlice !== normalized.slice(cursor, start)) {
+      replaced = true;
+    }
+    next += replacedSlice;
     next += match[0];
     cursor = start + match[0].length;
   }
-  next += replaceCitationTokens(normalized.slice(cursor), byIndex);
-  return next;
+  const tail = replaceCitationTokens(normalized.slice(cursor), byIndex, citationSources);
+  if (tail !== normalized.slice(cursor)) {
+    replaced = true;
+  }
+  next += tail;
+  if (replaced || hasCitationMarkdown(next)) {
+    return next;
+  }
+  return appendCitationSummary(next, citationSources);
 }
 
 function replaceCitationTokens(
   content: string,
   byIndex: Map<number, RuntimeDisplaySource>,
+  orderedSources: RuntimeDisplaySource[],
 ): string {
   return content
     .replace(/\[\[(\d+)\]\]/g, (match, rawIndex: string) =>
-      citationMarkdown(match, Number(rawIndex), byIndex),
+      citationMarkdown(match, Number(rawIndex), byIndex, orderedSources),
     )
     .replace(/(^|[^:\[!])\[(\d+)\](?!\()/g, (match, prefix: string, rawIndex: string) =>
-      `${prefix}${citationMarkdown(match.slice(prefix.length), Number(rawIndex), byIndex)}`,
+      `${prefix}${citationMarkdown(
+        match.slice(prefix.length),
+        Number(rawIndex),
+        byIndex,
+        orderedSources,
+      )}`,
     );
 }
 
@@ -476,6 +639,7 @@ function normalizeExistingCitationLinks(
   byIndex: Map<number, RuntimeDisplaySource>,
   byUrl: Map<string, RuntimeDisplaySource>,
   byTitle: Map<string, RuntimeDisplaySource>,
+  orderedSources: RuntimeDisplaySource[],
 ): string {
   // Resolve every `[citation:LABEL](URL)` link — whether LABEL is a number
   // ("[1]", "1") or a free-form title — to a numbered reference link that
@@ -488,8 +652,9 @@ function normalizeExistingCitationLinks(
       const numberMatch = label.match(/^\[?(\d+)\]?$/);
       if (numberMatch) {
         const index = Number(numberMatch[1]);
-        if (byIndex.has(index)) {
-          return `[citation:[${index}]](#reference-${index})`;
+        const source = byIndex.get(index) ?? orderedSources[index - 1];
+        if (source) {
+          return `[citation:[${source.index}]](#reference-${source.index})`;
         }
       }
       const sourceByUrl = byUrl.get(url);
@@ -509,12 +674,32 @@ function citationMarkdown(
   fallback: string,
   index: number,
   byIndex: Map<number, RuntimeDisplaySource>,
+  orderedSources: RuntimeDisplaySource[],
 ): string {
-  const source = byIndex.get(index);
+  const source = byIndex.get(index) ?? orderedSources[index - 1];
   if (!source) {
     return fallback;
   }
-  return `[citation:[${index}]](#reference-${index})`;
+  return `[citation:[${source.index}]](#reference-${source.index})`;
+}
+
+function hasCitationMarkdown(content: string): boolean {
+  return /\[citation:\[[^\]]+\]\]\(#reference-[^)]+\)/.test(content);
+}
+
+function appendCitationSummary(
+  content: string,
+  citationSources: RuntimeDisplaySource[],
+): string {
+  const citations = citationSources
+    .slice(0, 5)
+    .map((source) => `[citation:[${source.index}]](#reference-${source.index})`)
+    .join(" ");
+  if (!citations) {
+    return content;
+  }
+  const trimmed = content.trimEnd();
+  return `${trimmed}${trimmed ? "\n\n" : ""}参考来源：${citations}`;
 }
 
 function normalizeName(name: string): string {
@@ -540,6 +725,10 @@ function findToolResultPayload(
   if (!toolMessage) {
     return undefined;
   }
+  return parseToolMessagePayload(toolMessage);
+}
+
+function parseToolMessagePayload(toolMessage: Message): unknown {
   const structured = extractStructuredToolPayload(toolMessage.content);
   if (structured !== undefined) {
     return structured;
@@ -555,6 +744,17 @@ function findToolResultPayload(
   return content;
 }
 
+function extractToolMessageName(message: Message): string {
+  return (
+    stringifyMaybe((message as { name?: unknown }).name) ??
+    stringifyMaybe(
+      (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs
+        ?.name,
+    ) ??
+    "tool"
+  );
+}
+
 function findToolMessageById(
   toolCallId: string | undefined,
   messages: Message[],
@@ -677,7 +877,7 @@ function parseJSONLikeText(text: string): unknown {
   try {
     return JSON.parse(trimmed) as unknown;
   } catch {
-    return extractJSONFromText(trimmed);
+    return extractJSONFromText(trimmed) ?? extractSearchPayloadFromText(trimmed);
   }
 }
 
@@ -700,6 +900,83 @@ function extractJSONFromText(text: string): unknown {
   return undefined;
 }
 
+function extractSearchPayloadFromText(text: string): unknown {
+  if (!text.includes('"results"') || !text.includes('"recUuid"')) {
+    return undefined;
+  }
+  const results: Record<string, unknown>[] = [];
+  const objectPattern = /\{\s*"index"\s*:\s*\d+[\s\S]*?\n\s*\}/g;
+  for (const match of text.matchAll(objectPattern)) {
+    try {
+      const item = JSON.parse(match[0]) as unknown;
+      if (isRecord(item) && item.recUuid) {
+        results.push(item);
+      }
+    } catch {
+      const item = extractSearchItemFromText(match[0]);
+      if (item) {
+        results.push(item);
+      }
+    }
+  }
+  if (results.length === 0) {
+    return undefined;
+  }
+  return {
+    success: true,
+    query: extractStringField(text, "query") ?? "",
+    count: results.length,
+    source: extractStringField(text, "source") ?? "tool-output",
+    results,
+  };
+}
+
+function extractSearchItemFromText(text: string): Record<string, unknown> | null {
+  const recUuid = extractStringField(text, "recUuid");
+  if (!recUuid) {
+    return null;
+  }
+  const score = extractNumberField(text, "relevance_score");
+  return {
+    index: extractNumberField(text, "index") ?? undefined,
+    recUuid,
+    relevance_score: score,
+    title: extractStringField(text, "title") ?? recUuid,
+    source_category: extractStringField(text, "source_category") ?? "",
+    source: extractStringField(text, "source") ?? "",
+    publish_time: extractStringField(text, "publish_time") ?? "",
+    content_preview: extractStringField(text, "content_preview") ?? "",
+    content_length: extractNumberField(text, "content_length") ?? undefined,
+  };
+}
+
+function extractStringField(text: string, field: string): string | undefined {
+  const pattern = new RegExp(`"${escapeRegExp(field)}"\\s*:\\s*"((?:\\\\.|[^"\\\\])*)"`);
+  const match = pattern.exec(text);
+  if (!match) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(`"${match[1]}"`) as string;
+  } catch {
+    return match[1];
+  }
+}
+
+function extractNumberField(text: string, field: string): number | undefined {
+  const pattern = new RegExp(`"${escapeRegExp(field)}"\\s*:\\s*(-?\\d+(?:\\.\\d+)?)`);
+  const match = pattern.exec(text);
+  if (!match) {
+    return undefined;
+  }
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function extractToolText(content: unknown): string {
   if (typeof content === "string") {
     return content.trim();
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index 752bc385..aa27bb01 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -22,7 +22,7 @@ import {
   setSkillState,
   validateSkillUpload,
 } from "./api";
-import type { SkillState } from "./type";
+import type { Skill, SkillState } from "./type";
 
 import { loadSkills } from ".";
 
@@ -77,7 +77,13 @@ export function useSetSkillDisplay() {
       display: Parameters<typeof setSkillDisplay>[1];
       sample?: Parameters<typeof setSkillDisplay>[2];
     }) => setSkillDisplay(skillName, display, sample),
-    onSuccess: (_data, { skillName }) => {
+    onSuccess: (data, { skillName }) => {
+      queryClient.setQueryData(["skill", skillName], data);
+      queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
+        Array.isArray(current)
+          ? current.map((item) => (item.name === skillName ? { ...item, ...data } : item))
+          : current,
+      );
       void queryClient.invalidateQueries({ queryKey: ["skills"] });
       void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
     },
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index 8fc484a2..2a1c6496 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -36,6 +36,7 @@ from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api", tags=["skills"])
+_UNSET = object()
 
 
 # ---------------------------------------------------------------------------
@@ -221,7 +222,7 @@ def _skill_to_response(
     skill: Skill,
     ownership: dict[str, Any] | None = None,
     *,
-    display_override: dict[str, Any] | None = None,
+    display_override: dict[str, Any] | None | object = _UNSET,
     display_sample: dict[str, Any] | None = None,
 ) -> SkillResponse:
     """Convert a Skill object to a SkillResponse.
@@ -252,8 +253,8 @@ def _skill_to_response(
         builtin = bool(ownership.get("builtin", owner_user_id is None))
         detail = ownership.get("detail")
 
-    display = display_override
-    if display is None:
+    display = None if display_override is _UNSET else display_override
+    if display_override is _UNSET:
         try:
             skill_config = get_extensions_config().skills.get(skill.name)
             if skill_config and skill_config.display:
@@ -318,6 +319,10 @@ def _json_text_dumps(value: dict[str, Any] | None) -> str | None:
     return json.dumps(value, ensure_ascii=False)
 
 
+def _display_override_from_adapter(adapter: dict[str, Any] | None) -> dict[str, Any] | None | object:
+    return adapter.get("display") if adapter is not None else _UNSET
+
+
 async def _get_skill_display_adapter(skill_name: str) -> dict[str, Any] | None:
     if not await _ensure_skill_display_table():
         return None
@@ -698,7 +703,7 @@ async def list_skills(
         display_adapters = await _list_skill_display_adapters([skill.name for skill in all_skills])
         responses: list[SkillResponse] = []
         for skill in all_skills:
-            adapter = display_adapters.get(skill.name, {})
+            adapter = display_adapters.get(skill.name)
             # Public/built-in skills (no DB row) are visible to everyone.
             # Custom skills must have an ownership record in the visible set.
             if skill.category != SkillCategory.CUSTOM:
@@ -708,8 +713,8 @@ async def list_skills(
                     _skill_to_response(
                         skill,
                         ownership.get(skill.name),
-                        display_override=adapter.get("display"),
-                        display_sample=adapter.get("sample"),
+                        display_override=_display_override_from_adapter(adapter),
+                        display_sample=adapter.get("sample") if adapter else None,
                     )
                 )
                 continue
@@ -720,8 +725,8 @@ async def list_skills(
                 _skill_to_response(
                     skill,
                     record,
-                    display_override=adapter.get("display"),
-                    display_sample=adapter.get("sample"),
+                    display_override=_display_override_from_adapter(adapter),
+                    display_sample=adapter.get("sample") if adapter else None,
                 )
             )
         responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
@@ -984,16 +989,19 @@ async def list_custom_skills(
         custom = [s for s in get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False) if s.category == SkillCategory.CUSTOM]
         ownership = await _build_ownership_index(skill_store, user_id)
         display_adapters = await _list_skill_display_adapters([skill.name for skill in custom])
-        responses = [
-            _skill_to_response(
-                skill,
-                ownership[skill.name],
-                display_override=display_adapters.get(skill.name, {}).get("display"),
-                display_sample=display_adapters.get(skill.name, {}).get("sample"),
+        responses = []
+        for skill in custom:
+            if skill.name not in ownership:
+                continue
+            adapter = display_adapters.get(skill.name)
+            responses.append(
+                _skill_to_response(
+                    skill,
+                    ownership[skill.name],
+                    display_override=_display_override_from_adapter(adapter),
+                    display_sample=adapter.get("sample") if adapter else None,
+                )
             )
-            for skill in custom
-            if skill.name in ownership
-        ]
         return SkillsListResponse(skills=responses)
     except Exception as e:
         logger.error("Failed to list custom skills: %s", e, exc_info=True)
@@ -1008,7 +1016,15 @@ async def get_custom_skill(skill_name: str, config: AppConfig = Depends(get_conf
         skill = next((s for s in skills if s.name == skill_name and s.category == SkillCategory.CUSTOM), None)
         if skill is None:
             raise HTTPException(status_code=404, detail=f"Custom skill '{skill_name}' not found")
-        return CustomSkillContentResponse(**_skill_to_response(skill).model_dump(), content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name))
+        adapter = await _get_skill_display_adapter(skill_name)
+        return CustomSkillContentResponse(
+            **_skill_to_response(
+                skill,
+                display_override=_display_override_from_adapter(adapter),
+                display_sample=adapter.get("sample") if adapter else None,
+            ).model_dump(),
+            content=get_or_new_skill_storage(app_config=config).read_custom_skill(skill_name),
+        )
     except HTTPException:
         raise
     except Exception as e:
@@ -1365,7 +1381,13 @@ async def get_skill(
 
         # Attach ownership (owner/published/detail) when the caller may see it.
         ownership = await skill_store.get_visible(skill_name, _current_user_id(request))
-        return _skill_to_response(skill, ownership)
+        adapter = await _get_skill_display_adapter(skill_name)
+        return _skill_to_response(
+            skill,
+            ownership,
+            display_override=_display_override_from_adapter(adapter),
+            display_sample=adapter.get("sample") if adapter else None,
+        )
     except HTTPException:
         raise
     except Exception as e:
@@ -1944,11 +1966,11 @@ async def update_skill_display(
         updated_skill = next((s for s in skills if s.name == skill_name), None)
         if updated_skill is None:
             raise HTTPException(status_code=500, detail=f"Failed to reload skill '{skill_name}' after display update")
-        adapter = await _get_skill_display_adapter(skill_name) or {}
+        adapter = await _get_skill_display_adapter(skill_name)
         return _skill_to_response(
             updated_skill,
-            display_override=adapter.get("display"),
-            display_sample=adapter.get("sample"),
+            display_override=_display_override_from_adapter(adapter),
+            display_sample=adapter.get("sample") if adapter else None,
         )
     except HTTPException:
         raise

From c9c59b761f14a4f4a203948cf7008d7e5e478b8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 19:29:45 +0800
Subject: [PATCH 08/15] =?UTF-8?q?=E9=BB=98=E8=AE=A4=E4=B8=BB=E9=A2=98?=
 =?UTF-8?q?=E6=94=B9=E4=B8=BA=E6=B5=85=E8=89=B2=20+=20=E7=AE=A1=E7=90=86?=
 =?UTF-8?q?=E5=91=98=E5=8F=AF=E9=85=8D=E7=BD=AE=E5=85=A8=E5=B1=80=E9=BB=98?=
 =?UTF-8?q?=E8=AE=A4=E4=B8=BB=E9=A2=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- system_settings 新增 AppearanceSettings(default_theme)，默认为 light，
  对应 GET /api/system-settings/appearance（任何人可读）+ PUT（admin 可写）
- App.tsx 把 NextThemesProvider 的 defaultTheme 从 dark 改为 light，并把
  QueryClientProvider 提到 ThemeProvider 外层以便后者使用 useQuery
- ThemeContext 新增 localStorage 标志 strategy-theme-user-set：用户调用
  toggleTheme / setTheme 时打标；每次启动若标志未设，则跟随 admin 配置的
  default_theme 同步主题，admin 改动用户刷新即生效；标志一旦存在永远尊重
  用户个人选择
- legacy 'theme' 键迁移视为用户显式选择，避免老用户被新默认覆盖
- frontend system-settings api/hook 增 appearance 拉取与更新

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend-web/src/App.tsx                      | 18 ++---
 frontend-web/src/contexts/ThemeContext.tsx    | 70 +++++++++++++++----
 frontend-web/src/core/system-settings/api.ts  | 42 +++++++++++
 .../src/core/system-settings/hooks.ts         | 26 +++++++
 .../app/gateway/routers/system_settings.py    | 40 +++++++++++
 .../deerflow/config/system_settings.py        | 18 +++++
 6 files changed, 193 insertions(+), 21 deletions(-)

diff --git a/frontend-web/src/App.tsx b/frontend-web/src/App.tsx
index 1f7554d8..1257ab58 100644
--- a/frontend-web/src/App.tsx
+++ b/frontend-web/src/App.tsx
@@ -26,18 +26,20 @@ function AppProviders({ children }: { children: React.ReactNode }) {
     <NextThemesProvider
       attribute="class"
       storageKey="strategy-theme"
-      defaultTheme="dark"
+      defaultTheme="light"
       enableSystem={false}
       disableTransitionOnChange
       forcedTheme={forcedTheme}
     >
-      <I18nProvider initialLocale={locale}>
-        <ThemeProvider>
-          <ChatProvider>
-            <QueryClientProvider>{children}</QueryClientProvider>
-          </ChatProvider>
-        </ThemeProvider>
-      </I18nProvider>
+      {/* QueryClientProvider must wrap ThemeProvider because the custom
+          ThemeProvider reads the admin-configured default via useQuery. */}
+      <QueryClientProvider>
+        <I18nProvider initialLocale={locale}>
+          <ThemeProvider>
+            <ChatProvider>{children}</ChatProvider>
+          </ThemeProvider>
+        </I18nProvider>
+      </QueryClientProvider>
     </NextThemesProvider>
   );
 }
diff --git a/frontend-web/src/contexts/ThemeContext.tsx b/frontend-web/src/contexts/ThemeContext.tsx
index 55cda911..0aa7de26 100644
--- a/frontend-web/src/contexts/ThemeContext.tsx
+++ b/frontend-web/src/contexts/ThemeContext.tsx
@@ -7,6 +7,8 @@ import React, {
 } from 'react';
 import { useTheme as useNextTheme } from 'next-themes';
 
+import { useAppearanceSettings } from '@/core/system-settings/hooks';
+
 // 主题类型
 export type ThemeType = 'dark' | 'light';
 
@@ -83,13 +85,29 @@ const themes: Record<ThemeType, ThemeConfig> = {
 };
 
 const STORAGE_KEY = 'strategy-theme';
+// Marker that the user has explicitly toggled the theme (via the appearance
+// settings page or any future toggle UI). When this flag is absent we treat
+// any value stored in ``strategy-theme`` as one we put there ourselves while
+// syncing the admin's default — so we'll re-sync on every boot, picking up
+// admin changes. When the flag is present we never override the user.
+const EXPLICIT_FLAG_KEY = 'strategy-theme-user-set';
 
 function readPersistedTheme(): ThemeType {
   if (typeof window === 'undefined') {
-    return 'dark';
+    return 'light';
   }
   const saved = localStorage.getItem(STORAGE_KEY);
-  return saved === 'light' ? 'light' : 'dark';
+  return saved === 'dark' ? 'dark' : 'light';
+}
+
+function hasExplicitChoice(): boolean {
+  if (typeof window === 'undefined') return false;
+  return localStorage.getItem(EXPLICIT_FLAG_KEY) === '1';
+}
+
+function markExplicitChoice(): void {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(EXPLICIT_FLAG_KEY, '1');
 }
 
 // 主题上下文
@@ -112,42 +130,68 @@ interface ThemeProviderProps {
 export const ThemeProvider: React.FC<ThemeProviderProps> = ({ children }) => {
   const { resolvedTheme, setTheme: setNextTheme } = useNextTheme();
   const [mounted, setMounted] = useState(false);
+  // Admin-configured global default. If the user hasn't explicitly chosen
+  // a theme yet, this value drives the rendered theme — and re-syncs on
+  // every mount so an admin change propagates without users clearing
+  // localStorage by hand.
+  const { data: appearance } = useAppearanceSettings();
 
   useEffect(() => {
     setMounted(true);
   }, []);
 
-  // 迁移 / 规范化 localStorage，避免与 next-themes 冲突导致闪回浅色
+  // 迁移 / 规范化 localStorage：去掉旧的 'theme' 键，并清掉一切非法值。
+  // 注意：不要在这里强制写入一个 fallback —— 那会让 next-themes 视作
+  // 「用户已选过」，admin 默认就再也注入不进来了。
   useEffect(() => {
     if (!mounted) return;
     const current = localStorage.getItem(STORAGE_KEY);
     const legacy = localStorage.getItem('theme');
 
-    if (current !== 'light' && current !== 'dark') {
-      const fallback =
-        legacy === 'light' || legacy === 'dark' ? legacy : 'dark';
-      setNextTheme(fallback);
-    } else if (!current && legacy && (legacy === 'light' || legacy === 'dark')) {
-      setNextTheme(legacy);
+    if (current && current !== 'light' && current !== 'dark') {
+      // Garbage value — wipe it so the boot-sync below can take over.
+      localStorage.removeItem(STORAGE_KEY);
+    }
+    if (!current && legacy && (legacy === 'light' || legacy === 'dark')) {
+      // Migrate the legacy key as the user's explicit choice (it was set
+      // long enough ago that we should preserve their pick rather than
+      // override with admin default).
+      setNextTheme(legacy);
+      markExplicitChoice();
     }
-
     if (legacy) {
       localStorage.removeItem('theme');
     }
   }, [mounted, setNextTheme]);
 
+  // Boot-time sync: when the user has never picked a theme themselves,
+  // apply whatever the admin configured. Re-runs whenever the admin
+  // setting changes (so a logged-in user sees the new default after
+  // refreshing without having to clear cookies).
+  useEffect(() => {
+    if (!mounted) return;
+    if (hasExplicitChoice()) return;
+    const adminDefault = appearance?.default_theme;
+    if (!adminDefault) return;
+    if (resolvedTheme !== adminDefault) {
+      setNextTheme(adminDefault);
+    }
+  }, [mounted, appearance?.default_theme, resolvedTheme, setNextTheme]);
+
   const theme: ThemeType = mounted
-    ? resolvedTheme === 'light'
-      ? 'light'
-      : 'dark'
+    ? resolvedTheme === 'dark'
+      ? 'dark'
+      : 'light'
     : readPersistedTheme();
 
   const toggleTheme = () => {
     setNextTheme(theme === 'dark' ? 'light' : 'dark');
+    markExplicitChoice();
   };
 
   const setTheme = (newTheme: ThemeType) => {
     setNextTheme(newTheme);
+    markExplicitChoice();
   };
 
   const themeConfig = themes[theme];
diff --git a/frontend-web/src/core/system-settings/api.ts b/frontend-web/src/core/system-settings/api.ts
index 697e88c5..e6335706 100644
--- a/frontend-web/src/core/system-settings/api.ts
+++ b/frontend-web/src/core/system-settings/api.ts
@@ -65,6 +65,48 @@ export async function loadPrivateSquareStatus(): Promise<PrivateSquareStatus> {
   return (await response.json()) as PrivateSquareStatus;
 }
 
+export type ThemeMode = "light" | "dark";
+
+export interface AppearanceSettings {
+  default_theme: ThemeMode;
+}
+
+export interface AppearanceUpdate {
+  default_theme?: ThemeMode;
+}
+
+export async function loadAppearanceSettings(): Promise<AppearanceSettings> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/appearance`,
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Failed to load appearance settings: ${response.status}`,
+    );
+  }
+  return (await response.json()) as AppearanceSettings;
+}
+
+export async function updateAppearanceSettings(
+  body: AppearanceUpdate,
+): Promise<AppearanceSettings> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/appearance`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!response.ok) {
+    const detail = await response
+      .json()
+      .catch(() => ({ detail: "Failed to update appearance" }));
+    throw new Error(detail.detail ?? "Failed to update appearance");
+  }
+  return (await response.json()) as AppearanceSettings;
+}
+
 export async function updatePrivateSquareSettings(
   body: PrivateSquareUpdate,
 ): Promise<PrivateSquareStatus> {
diff --git a/frontend-web/src/core/system-settings/hooks.ts b/frontend-web/src/core/system-settings/hooks.ts
index 9c2ee5fd..903737a5 100644
--- a/frontend-web/src/core/system-settings/hooks.ts
+++ b/frontend-web/src/core/system-settings/hooks.ts
@@ -1,16 +1,20 @@
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 
 import {
+  loadAppearanceSettings,
   loadPrivateSquareStatus,
   loadPromptPrefixSettings,
+  updateAppearanceSettings,
   updatePrivateSquareSettings,
   updatePromptPrefixSettings,
+  type AppearanceUpdate,
   type PrivateSquareUpdate,
   type PromptPrefixUpdate,
 } from "./api";
 
 const PROMPT_PREFIX_KEY = ["systemSettings", "promptPrefix"] as const;
 const PRIVATE_SQUARE_KEY = ["systemSettings", "privateSquare"] as const;
+const APPEARANCE_KEY = ["systemSettings", "appearance"] as const;
 
 export function usePromptPrefixSettings() {
   return useQuery({
@@ -51,3 +55,25 @@ export function useUpdatePrivateSquareSettings() {
     },
   });
 }
+
+export function useAppearanceSettings() {
+  return useQuery({
+    queryKey: APPEARANCE_KEY,
+    queryFn: () => loadAppearanceSettings(),
+    staleTime: 60_000,
+    refetchOnWindowFocus: false,
+    // The provider runs even on the login page (where the user has no auth)
+    // — gracefully tolerate the fetch failing rather than retrying.
+    retry: false,
+  });
+}
+
+export function useUpdateAppearanceSettings() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (body: AppearanceUpdate) => updateAppearanceSettings(body),
+    onSuccess: (data) => {
+      queryClient.setQueryData(APPEARANCE_KEY, data);
+    },
+  });
+}
diff --git a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
index 48940387..aadb877e 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+from typing import Literal
 
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
@@ -124,3 +125,42 @@ async def update_private_square(body: PrivateSquareUpdateRequest, request: Reque
         enabled=saved.private_square.enabled,
         password_set=bool(saved.private_square.password_hash),
     )
+
+
+class AppearanceResponse(BaseModel):
+    """Effective system-wide appearance defaults."""
+
+    default_theme: Literal["light", "dark"] = Field(..., description="System default theme — light or dark")
+
+
+class AppearanceUpdateRequest(BaseModel):
+    default_theme: Literal["light", "dark"] | None = Field(default=None)
+
+
+@router.get("/appearance", response_model=AppearanceResponse)
+async def get_appearance_settings() -> AppearanceResponse:
+    """Return the global default theme. Any logged-in user may read this."""
+    settings = load_system_settings().appearance
+    return AppearanceResponse(default_theme=settings.default_theme)
+
+
+@router.put("/appearance", response_model=AppearanceResponse)
+async def update_appearance_settings(
+    body: AppearanceUpdateRequest, request: Request
+) -> AppearanceResponse:
+    """Update the global appearance defaults. Admin only."""
+    await _require_admin(request)
+
+    current = load_system_settings()
+    fields = body.model_dump(exclude_unset=True)
+    update: dict[str, object] = {}
+    if "default_theme" in fields and fields["default_theme"] is not None:
+        update["default_theme"] = fields["default_theme"]
+    if update:
+        updated_appearance = current.appearance.model_copy(update=update)
+        saved = save_system_settings(
+            current.model_copy(update={"appearance": updated_appearance})
+        )
+    else:
+        saved = current
+    return AppearanceResponse(default_theme=saved.appearance.default_theme)
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
index 0a2d41ea..67e1a4d9 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
@@ -17,6 +17,7 @@ import json
 import logging
 import threading
 from pathlib import Path
+from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -37,6 +38,22 @@ class PromptPrefixSettings(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
 
+class AppearanceSettings(BaseModel):
+    """System-wide appearance defaults that any *new* user inherits.
+
+    Once a user explicitly toggles their theme in the UI, that choice is
+    persisted in the browser and supersedes this default — so changing
+    ``default_theme`` here only affects users who have never touched the
+    toggle, and any future first-time loads.
+    """
+
+    default_theme: Literal["light", "dark"] = Field(
+        default="light",
+        description="Theme applied for users who haven't picked their own (light / dark)",
+    )
+    model_config = ConfigDict(extra="ignore")
+
+
 class PrivateSquareSettings(BaseModel):
     """Admin-configurable settings for the agent private-square (私密广场).
 
@@ -56,6 +73,7 @@ class SystemSettings(BaseModel):
 
     prompt_prefix: PromptPrefixSettings = Field(default_factory=PromptPrefixSettings)
     private_square: PrivateSquareSettings = Field(default_factory=PrivateSquareSettings)
+    appearance: AppearanceSettings = Field(default_factory=AppearanceSettings)
     model_config = ConfigDict(extra="ignore")
 
 

From 89a1fa5042cdb39d0c3d94434e0c25580ba10174 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 19:30:00 +0800
Subject: [PATCH 09/15] =?UTF-8?q?=E7=A7=81=E5=AF=86/=E5=85=AC=E5=BC=80?=
 =?UTF-8?q?=E4=BA=92=E6=96=A5=E5=85=9C=E5=BA=95=20+=20=E6=99=BA=E8=83=BD?=
 =?UTF-8?q?=E4=BD=93=E6=90=9C=E7=B4=A2=E6=8C=89=E6=98=BE=E7=A4=BA=E5=90=8E?=
 =?UTF-8?q?=E5=90=8D=E7=A7=B0=E5=8C=B9=E9=85=8D=20+=20=E5=A4=9A=E5=A4=84?=
 =?UTF-8?q?=E5=B0=8F=E4=BF=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 后端 update_agent / set_agent_private 增加兜底：is_private=true 时强制
  published=false，杜绝同时落在公开+私密两个广场的灰色态
- agent-card 编辑弹窗暴露 editIsPrivate 开关，与公开发布开关在前端互斥校验
- agent-gallery 智能体模糊搜索改为前端针对 desensitize() 后的名字比对，
  解决脱敏显示与原始名字不一致导致看似搜索失效的问题
- useUpdateAgent 在 onSuccess 立刻把新数据 patch 进所有 ["agents"] 列表
  缓存，卡片在后台 refetch 完成前先行 re-render，避免「切换私密/发布后
  好像没反应」的体感延迟
- useGlobalShortcuts 对 event.key 为 undefined（IME 合成 / 扩展注入）做
  容错，否则会抛 TypeError 把后续所有快捷键吃掉

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../workspace/agents/agent-card.tsx           | 66 ++++++++++++++++---
 .../workspace/agents/agent-gallery.tsx        | 36 +++++++---
 frontend-web/src/core/agents/hooks.ts         | 29 ++++++--
 .../src/hooks/use-global-shortcuts.ts         |  9 ++-
 .../backend/app/gateway/routers/agents.py     | 14 +++-
 5 files changed, 130 insertions(+), 24 deletions(-)

diff --git a/frontend-web/src/components/workspace/agents/agent-card.tsx b/frontend-web/src/components/workspace/agents/agent-card.tsx
index aac8f52b..5ee1c8d3 100644
--- a/frontend-web/src/components/workspace/agents/agent-card.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-card.tsx
@@ -72,6 +72,7 @@ export function AgentCard({ agent }: AgentCardProps) {
   const [editDescription, setEditDescription] = useState(agent.description ?? "");
   const [editSoul, setEditSoul] = useState(agent.soul ?? "");
   const [editPublished, setEditPublished] = useState(agent.published);
+  const [editIsPrivate, setEditIsPrivate] = useState(agent.is_private);
   const [selectedSkills, setSelectedSkills] = useState<string[]>(
     agent.skills ?? [],
   );
@@ -98,9 +99,11 @@ export function AgentCard({ agent }: AgentCardProps) {
     setEditDescription(agent.description ?? "");
     setEditSoul(agent.soul ?? "");
     setEditPublished(agent.published);
+    setEditIsPrivate(agent.is_private);
     setSelectedSkills(agent.skills ?? []);
   }, [
     agent.description,
+    agent.is_private,
     agent.name,
     agent.published,
     agent.skills,
@@ -128,6 +131,10 @@ export function AgentCard({ agent }: AgentCardProps) {
       toast.error(t.agents.nameStepInvalidError ?? "名称不能为空");
       return;
     }
+    if (editIsPrivate && editPublished) {
+      toast.warning("私密广场与公开发布互斥，请只勾选其一");
+      return;
+    }
     try {
       await updateAgent.mutateAsync({
         id: agent.id,
@@ -135,7 +142,10 @@ export function AgentCard({ agent }: AgentCardProps) {
           name: trimmedName,
           description: editDescription,
           soul: editSoul,
-          published: editPublished,
+          // Private agents cannot also be published — force the value the
+          // backend will see, regardless of any stale state in editPublished.
+          published: editIsPrivate ? false : editPublished,
+          is_private: editIsPrivate,
           skills: selectedSkills,
         },
       });
@@ -147,6 +157,13 @@ export function AgentCard({ agent }: AgentCardProps) {
   }
 
   async function handleTogglePublished() {
+    // Private and public squares are mutually exclusive — a private agent
+    // can't simultaneously be published to everyone. Block the toggle
+    // instead of silently moving the agent between squares.
+    if (!agent.published && agent.is_private) {
+      toast.warning("该智能体已加入私密广场，不可发布");
+      return;
+    }
     try {
       await updateAgent.mutateAsync({
         id: agent.id,
@@ -328,13 +345,9 @@ export function AgentCard({ agent }: AgentCardProps) {
           </CardContent>
         )}
 
-        <CardFooter className="mt-auto flex items-center justify-between gap-2 pt-3">
-          <Button size="sm" className="flex-1" onClick={handleChat}>
-            <MessageSquareIcon className="mr-1.5 h-3.5 w-3.5" />
-            {t.agents.chat}
-          </Button>
+        <CardFooter className="mt-auto flex flex-col items-stretch gap-2 pt-3">
           {(canEdit || canDelete || isOwned || isAdmin) && (
-            <div className="flex gap-1">
+            <div className="flex flex-wrap items-center justify-end gap-1">
               {isAdmin && (
                 <Button
                   size="icon"
@@ -424,6 +437,10 @@ export function AgentCard({ agent }: AgentCardProps) {
               )}
             </div>
           )}
+          <Button size="sm" className="w-full" onClick={handleChat}>
+            <MessageSquareIcon className="mr-1.5 h-3.5 w-3.5" />
+            {t.agents.chat}
+          </Button>
         </CardFooter>
       </Card>
 
@@ -519,12 +536,41 @@ export function AgentCard({ agent }: AgentCardProps) {
               <div>
                 <p className="text-sm font-medium">公开发布</p>
                 <p className="text-muted-foreground text-xs">
-                  打开后,该智能体对所有用户可见。
+                  {editIsPrivate
+                    ? "已加入私密广场，不可发布；请先关闭私密广场。"
+                    : "打开后,该智能体对所有用户可见。"}
                 </p>
               </div>
               <Switch
-                checked={editPublished}
-                onCheckedChange={setEditPublished}
+                checked={editPublished && !editIsPrivate}
+                disabled={editIsPrivate}
+                onCheckedChange={(v) => {
+                  if (editIsPrivate) {
+                    toast.warning("该智能体已加入私密广场，不可发布");
+                    return;
+                  }
+                  setEditPublished(v);
+                }}
+              />
+            </div>
+            <div className="flex items-center justify-between rounded-md border p-3">
+              <div>
+                <p className="text-sm font-medium">加入私密广场</p>
+                <p className="text-muted-foreground text-xs">
+                  打开后,该智能体仅在私密广场显示,需输入密码才能查看;与「公开发布」互斥。
+                </p>
+              </div>
+              <Switch
+                checked={editIsPrivate}
+                onCheckedChange={(v) => {
+                  setEditIsPrivate(v);
+                  if (v) {
+                    // Mutual-exclusion: switching the agent into the private
+                    // square automatically clears the public-publish flag so
+                    // the user can't end up with a half-and-half state.
+                    setEditPublished(false);
+                  }
+                }}
               />
             </div>
           </div>
diff --git a/frontend-web/src/components/workspace/agents/agent-gallery.tsx b/frontend-web/src/components/workspace/agents/agent-gallery.tsx
index 87d438e5..10001772 100644
--- a/frontend-web/src/components/workspace/agents/agent-gallery.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-gallery.tsx
@@ -10,9 +10,11 @@ import { Input } from "@/components/ui/input";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { TagSearchBar } from "@/components/workspace/tags/tag-search-bar";
 import { useAgents, usePrivateAgents } from "@/core/agents";
+import type { Agent } from "@/core/agents";
 import { getStoredAuth } from "@/core/auth";
 import { useI18n } from "@/core/i18n/hooks";
 import { usePrivateSquareStatus } from "@/core/system-settings/hooks";
+import { desensitize } from "@/lib/desensitize";
 
 import { AgentCard } from "./agent-card";
 
@@ -29,8 +31,16 @@ export function AgentGallery() {
   );
   const [search, setSearch] = useState("");
   const [tagIds, setTagIds] = useState<string[]>([]);
-  // Name + tag filtering is resolved server-side via the /api/agents query.
-  const { agents, isLoading } = useAgents({ search, tagIds });
+  // Tag filtering stays server-side; name search must run on the *desensitized*
+  // form because that's what the user sees on the card. If we sent the search
+  // string to the backend it would compare against the raw stored name and
+  // miss every desensitized hit (e.g. typing "TS分析" wouldn't match the
+  // stored "态势分析").
+  const { agents, isLoading } = useAgents({ tagIds });
+
+  const needle = search.trim().toLowerCase();
+  const matchesSearch = (a: Agent) =>
+    !needle || desensitize(a.name).toLowerCase().includes(needle);
 
   const storedAuth = useMemo(() => getStoredAuth(), []);
   const currentUserId = storedAuth?.user_id ?? null;
@@ -69,28 +79,38 @@ export function AgentGallery() {
   // owner's own private agents, which still come back in the unified list
   // because owners always see their own.)
   const allAgents = useMemo(
-    () => agents.filter((a) => (a.builtin || a.published) && !a.is_private),
-    [agents],
+    () =>
+      agents.filter(
+        (a) => (a.builtin || a.published) && !a.is_private && matchesSearch(a),
+      ),
+    // matchesSearch closes over `needle`; depending on `search` is sufficient
+    // and avoids re-running on every render via the function reference.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [agents, search],
   );
 
   const myAgents = useMemo(
     () =>
       agents.filter(
-        (a) => a.user_id !== null && a.user_id === currentUserId,
+        (a) =>
+          a.user_id !== null &&
+          a.user_id === currentUserId &&
+          matchesSearch(a),
       ),
-    [agents, currentUserId],
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [agents, currentUserId, search],
   );
 
   const filteredPrivateAgents = useMemo(() => {
-    const needle = search.trim().toLowerCase();
     const wanted = new Set(tagIds);
     return privateAgents.filter((a) => {
-      if (needle && !a.name.toLowerCase().includes(needle)) return false;
+      if (!matchesSearch(a)) return false;
       if (wanted.size > 0) {
         if (!(a.tags ?? []).some((tg) => wanted.has(tg.id))) return false;
       }
       return true;
     });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [privateAgents, search, tagIds]);
 
   const handleNewAgent = () => {
diff --git a/frontend-web/src/core/agents/hooks.ts b/frontend-web/src/core/agents/hooks.ts
index 8d8e81ad..802283f6 100644
--- a/frontend-web/src/core/agents/hooks.ts
+++ b/frontend-web/src/core/agents/hooks.ts
@@ -17,7 +17,25 @@ import {
   setAgentPrivate,
   updateAgent,
 } from "./api";
-import type { CreateAgentRequest, UpdateAgentRequest } from "./types";
+import type { Agent, CreateAgentRequest, UpdateAgentRequest } from "./types";
+
+/** Patch an updated agent into every cached agent listing immediately so
+ * cards re-render before the background refetch finishes. Without this the
+ * mutation just invalidates the query and the user has to wait for the
+ * round-trip + render — which on a big list feels like nothing happened.
+ */
+function applyAgentToCache(
+  queryClient: ReturnType<typeof useQueryClient>,
+  next: Agent,
+) {
+  queryClient.setQueriesData<Agent[] | undefined>(
+    { queryKey: ["agents"] },
+    (old) => {
+      if (!Array.isArray(old)) return old;
+      return old.map((a) => (a.id === next.id ? { ...a, ...next } : a));
+    },
+  );
+}
 
 export function useAgents(params: { search?: string; tagIds?: string[] } = {}) {
   const search = params.search ?? "";
@@ -59,7 +77,8 @@ export function useUpdateAgent() {
       id: string;
       request: UpdateAgentRequest;
     }) => updateAgent(id, request),
-    onSuccess: (_data, { id }) => {
+    onSuccess: (data, { id }) => {
+      applyAgentToCache(queryClient, data);
       void queryClient.invalidateQueries({ queryKey: ["agents"] });
       void queryClient.invalidateQueries({ queryKey: ["agents", id] });
     },
@@ -98,7 +117,8 @@ export function useSetAgentFeatured() {
   return useMutation({
     mutationFn: ({ id, order }: { id: string; order: number | null }) =>
       setAgentFeatured(id, order),
-    onSuccess: (_data, { id }) => {
+    onSuccess: (data, { id }) => {
+      applyAgentToCache(queryClient, data);
       invalidateAgentQueries(queryClient);
       void queryClient.invalidateQueries({ queryKey: ["agents", id] });
     },
@@ -134,7 +154,8 @@ export function useSetAgentPrivate() {
   return useMutation({
     mutationFn: ({ id, isPrivate }: { id: string; isPrivate: boolean }) =>
       setAgentPrivate(id, isPrivate),
-    onSuccess: (_data, { id }) => {
+    onSuccess: (data, { id }) => {
+      applyAgentToCache(queryClient, data);
       invalidateAgentQueries(queryClient);
       void queryClient.invalidateQueries({ queryKey: ["agents", id] });
       void queryClient.invalidateQueries({
diff --git a/frontend-web/src/hooks/use-global-shortcuts.ts b/frontend-web/src/hooks/use-global-shortcuts.ts
index 64a6feef..97e5c645 100644
--- a/frontend-web/src/hooks/use-global-shortcuts.ts
+++ b/frontend-web/src/hooks/use-global-shortcuts.ts
@@ -19,11 +19,18 @@ interface Shortcut {
 export function useGlobalShortcuts(shortcuts: Shortcut[]) {
   useEffect(() => {
     function handleKeyDown(event: KeyboardEvent) {
+      // ``event.key`` is ``undefined`` for synthetic / IME-composition /
+      // some extension-injected keydown events. Calling ``.toLowerCase()``
+      // on it throws and kills every shortcut after this one — bail out
+      // before that happens.
+      if (typeof event.key !== "string") return;
       const meta = event.metaKey || event.ctrlKey;
+      const pressed = event.key.toLowerCase();
 
       for (const shortcut of shortcuts) {
+        if (typeof shortcut.key !== "string") continue;
         if (
-          event.key.toLowerCase() === shortcut.key.toLowerCase() &&
+          pressed === shortcut.key.toLowerCase() &&
           meta === shortcut.meta &&
           (shortcut.shift ?? false) === event.shiftKey
         ) {
diff --git a/offline-backend-20260512/backend/app/gateway/routers/agents.py b/offline-backend-20260512/backend/app/gateway/routers/agents.py
index 7f21014f..9b836a95 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/agents.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/agents.py
@@ -495,6 +495,13 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
             update_data["published"] = bool(request.published)
         if "is_private" in fields_set:
             update_data["is_private"] = bool(request.is_private)
+        # Mutual exclusion: an agent moved into the private square cannot
+        # also be publicly published. Force ``published=false`` whenever the
+        # same request sets ``is_private=true``, even if the client forgot
+        # to clear it. (When the request only sets one of the two, the
+        # other side is left untouched.)
+        if update_data.get("is_private") is True:
+            update_data["published"] = False
 
         next_name = update_data.get("name", current["name"])
         next_description = update_data.get("description", current.get("description") or "")
@@ -750,7 +757,12 @@ async def set_agent_private(
         if record is None:
             raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
 
-        update = {"is_private": bool(body.is_private)}
+        update: dict[str, Any] = {"is_private": bool(body.is_private)}
+        # Mutual exclusion — see ``update_agent`` above. Moving an agent into
+        # the private square also drops the public ``published`` flag so we
+        # never end up with an agent that's "in both squares".
+        if update["is_private"]:
+            update["published"] = False
         if record.get("user_id") is None:
             updated = await store.update_builtin(agent_id, update)
         else:

From 7b629d0697bb37909e3e37553fa1575cadf28e51 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Tue, 26 May 2026 19:31:10 +0800
Subject: [PATCH 10/15] =?UTF-8?q?=E8=BD=AE=E6=8D=A2=20LLM=20=E5=87=AD?=
 =?UTF-8?q?=E8=AF=81=E4=B8=8E=E9=BB=98=E8=AE=A4=E6=A8=A1=E5=9E=8B=EF=BC=88?=
 =?UTF-8?q?DeepSeek=20=E2=86=92=20zai-org/GLM-5-FP8=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- backend/config.yaml、config.yaml 把默认模型从 deepseek-chat 切到
  zai-org/GLM-5-FP8（modal endpoint），并轮换对应 API key / Bearer
- .env 同步更新

注意：这些文件包含真实凭证，应用部署时务必通过 .env 或私有 config
覆盖，不要把仓库里的版本直接用于生产。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 offline-backend-20260512/.env                |  2 +-
 offline-backend-20260512/backend/config.yaml | 10 +++++-----
 offline-backend-20260512/config.yaml         | 12 ++++++------
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/offline-backend-20260512/.env b/offline-backend-20260512/.env
index 7271a16d..0f92c182 100644
--- a/offline-backend-20260512/.env
+++ b/offline-backend-20260512/.env
@@ -6,7 +6,7 @@
 # host shell; values in this file are what the container will receive.
 
 # AI provider keys. Replace placeholders and rotate any test key before release.
-DEEPSEEK_API_KEY=sk-cea9133f82e24e9f939136746b05d5f8
+DEEPSEEK_API_KEY=sk-9808fb2375534112ac275541aec14b9b
 OPENAI_API_KEY=your-openai-api-key
 ANTHROPIC_API_KEY=your-anthropic-api-key
 
diff --git a/offline-backend-20260512/backend/config.yaml b/offline-backend-20260512/backend/config.yaml
index 086353c0..ed68c219 100644
--- a/offline-backend-20260512/backend/config.yaml
+++ b/offline-backend-20260512/backend/config.yaml
@@ -10,12 +10,12 @@ gateway:
   port: 8001
 
 models:
-  - name: deepseek-chat
-    display_name: DeepSeek Chat
+  - name: zai-org/GLM-5-FP8
+    display_name: zai-org/GLM-5-FP8
     use: langchain_openai:ChatOpenAI
-    model: deepseek-chat
-    api_key: sk-e1c22b7931dc446f8b67e57878edd105
-    base_url: https://api.deepseek.com
+    model: zai-org/GLM-5-FP8
+    api_key: Bearer modalresearch_gWu46FDpVLYZWPVEA3b_2fq8Jw2UJiKMgEm_Rxmn1SA
+    base_url: https://api.us-west-2.modal.direct/v1
     request_timeout: 600.0
     max_retries: 2
     max_tokens: 4096
diff --git a/offline-backend-20260512/config.yaml b/offline-backend-20260512/config.yaml
index 7df8818e..65bb75ec 100644
--- a/offline-backend-20260512/config.yaml
+++ b/offline-backend-20260512/config.yaml
@@ -5,7 +5,7 @@ models:
   display_name: DeepSeek Chat
   use: langchain_openai:ChatOpenAI
   model: deepseek-chat
-  api_key: sk-e1c22b7931dc446f8b67e57878edd105
+  api_key: sk-9808fb2375534112ac275541aec14b9b
   base_url: https://api.deepseek.com
   request_timeout: 600.0
   max_retries: 2
@@ -13,12 +13,12 @@ models:
   temperature: 1.0
   supports_vision: true
   supports_thinking: true
-- name: deepseek-v4-flash
-  display_name: DeepSeek V4 Flash
+- name: zai-org/GLM-5-FP8
+  display_name: zai-org/GLM-5-FP8
   use: langchain_openai:ChatOpenAI
-  model: deepseek-v4-flash
-  api_key: sk-e1c22b7931dc446f8b67e57878edd105
-  base_url: https://api.deepseek.com
+  model: zai-org/GLM-5-FP8
+  api_key: modalresearch_gWu46FDpVLYZWPVEA3b_2fq8Jw2UJiKMgEm_Rxmn1SA
+  base_url: https://api.us-west-2.modal.direct/v1
   request_timeout: 600.0
   max_retries: 2
   max_tokens: 4096

From eda0ccffdbe7fec3fc76599c8f83250e98f09d9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Wed, 27 May 2026 11:13:29 +0800
Subject: [PATCH 11/15] =?UTF-8?q?=E7=AE=A1=E7=90=86=E5=91=98=E6=99=BA?=
 =?UTF-8?q?=E8=83=BD=E4=BD=93/=E6=8A=80=E8=83=BD=E7=AE=A1=E7=90=86=20+=20?=
 =?UTF-8?q?=E8=B7=A8=E6=A0=87=E7=AD=BE=E7=99=BB=E5=BD=95=E5=90=8C=E6=AD=A5?=
 =?UTF-8?q?=20+=20=E4=B8=8A=E6=B8=B8=E5=93=8D=E5=BA=94=E5=BC=82=E5=B8=B8?=
 =?UTF-8?q?=E9=87=8D=E8=AF=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 「设置和更多」新增「智能体管理」「技能管理」入口，与定时任务管理同级；
  独立的 AdminAgentsPage/AdminSkillsPage 复用 AgentCard/SkillRow，
  管理员可查看并编辑/删除所有用户的智能体与技能。
- 后端 /api/agents、/api/skills 增加 ?admin=true 越权列表；agents 端
  放宽 _get_editable_or_raise 让管理员可编辑/删除任意智能体；新增
  list_all/update_any/delete_any（agents）与 list_all（skills）。
- 新增 AuthSyncWatcher：监听 localStorage["deerflow.auth"] 的 storage
  事件，user_id 变化时自动 reload，修复多标签切换登录后老页面点击
  「新对话」偶发 404 的问题。
- LLMErrorHandlingMiddleware 将 bad_response_status_code / JSON
  decode 等上游网关乱码识别为可重试的 upstream 类故障。
- 侧边栏「任务管理」改名为「定时任务」。

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend-web/src/App.tsx                      |   6 +-
 frontend-web/src/components/page-sidebar.tsx  |   2 +-
 .../workspace/agents/agent-card.tsx           |   7 +-
 .../settings/skill-settings-page.tsx          |   2 +-
 .../workspace/workspace-nav-chat-list.tsx     |   2 +-
 .../workspace/workspace-nav-menu.tsx          |  18 +++
 frontend-web/src/core/agents/api.ts           |  10 ++
 frontend-web/src/core/agents/hooks.ts         |  16 ++
 frontend-web/src/core/auth/sync.tsx           |  47 ++++++
 frontend-web/src/core/skills/api.ts           | 129 ++++++++--------
 frontend-web/src/core/skills/hooks.ts         |  81 +++++-----
 frontend-web/src/pages/AdminAgentsPage.tsx    |  82 ++++++++++
 frontend-web/src/pages/AdminSkillsPage.tsx    | 140 ++++++++++++++++++
 frontend-web/src/pages/WorkspaceRoutes.tsx    |  26 ++++
 .../backend/app/gateway/routers/agents.py     |  34 ++++-
 .../backend/app/gateway/routers/skills.py     |  24 ++-
 .../llm_error_handling_middleware.py          |  48 +++++-
 .../deerflow/persistence/agents/base.py       |  27 ++++
 .../deerflow/persistence/agents/memory.py     |  26 ++++
 .../deerflow/persistence/agents/sql.py        |  28 ++++
 .../deerflow/persistence/skills/base.py       |   8 +
 .../deerflow/persistence/skills/memory.py     |   6 +
 .../deerflow/persistence/skills/sql.py        |   6 +
 23 files changed, 660 insertions(+), 115 deletions(-)
 create mode 100644 frontend-web/src/core/auth/sync.tsx
 create mode 100644 frontend-web/src/pages/AdminAgentsPage.tsx
 create mode 100644 frontend-web/src/pages/AdminSkillsPage.tsx

diff --git a/frontend-web/src/App.tsx b/frontend-web/src/App.tsx
index b7508f12..ea03c986 100644
--- a/frontend-web/src/App.tsx
+++ b/frontend-web/src/App.tsx
@@ -3,6 +3,7 @@ import { Navigate, Route, Routes } from "react-router-dom";
 import { ThemeProvider as NextThemesProvider } from "next-themes";
 
 import { QueryClientProvider } from "@/components/query-client-provider";
+import { AuthSyncWatcher } from "@/core/auth/sync";
 import { I18nProvider } from "@/core/i18n/context";
 import { detectLocale } from "@/core/i18n/locale";
 import { ChatProvider } from "@/contexts/ChatContext";
@@ -36,7 +37,10 @@ function AppProviders({ children }: { children: React.ReactNode }) {
       <QueryClientProvider>
         <I18nProvider initialLocale={locale}>
           <ThemeProvider>
-            <ChatProvider>{children}</ChatProvider>
+            <ChatProvider>
+              <AuthSyncWatcher />
+              {children}
+            </ChatProvider>
           </ThemeProvider>
         </I18nProvider>
       </QueryClientProvider>
diff --git a/frontend-web/src/components/page-sidebar.tsx b/frontend-web/src/components/page-sidebar.tsx
index 87645acb..810e9e74 100644
--- a/frontend-web/src/components/page-sidebar.tsx
+++ b/frontend-web/src/components/page-sidebar.tsx
@@ -176,7 +176,7 @@ const menuItems: MenuItem[] = [
       { id: "mgmt-memory", label: "记忆管理", icon: Brain, path: "/page/strategy/memory" },
       {
         id: "mgmt-tasks",
-        label: "任务管理",
+        label: "定时任务",
         icon: ListChecks,
         path: "/page/strategy/scheduled/tasks",
       },
diff --git a/frontend-web/src/components/workspace/agents/agent-card.tsx b/frontend-web/src/components/workspace/agents/agent-card.tsx
index 5ee1c8d3..704ebd87 100644
--- a/frontend-web/src/components/workspace/agents/agent-card.tsx
+++ b/frontend-web/src/components/workspace/agents/agent-card.tsx
@@ -85,11 +85,12 @@ export function AgentCard({ agent }: AgentCardProps) {
   const isOwned =
     !isBuiltin && agent.user_id !== null && agent.user_id === currentUserId;
   const isFromOthers = !isBuiltin && !isOwned;
-  // System admins are allowed to edit and delete built-in agents.
+  // System admins are allowed to edit and delete any agent (built-in or owned
+  // by another user) so the admin console can manage the full catalog.
   // Publish-toggle stays owner-only — built-ins are inherently visible to
   // everyone so toggling published is moot.
-  const canEdit = isOwned || (isBuiltin && isAdmin);
-  const canDelete = isOwned || (isBuiltin && isAdmin);
+  const canEdit = isOwned || isAdmin;
+  const canDelete = isOwned || isAdmin;
 
   useEffect(() => {
     if (!editOpen) {
diff --git a/frontend-web/src/components/workspace/settings/skill-settings-page.tsx b/frontend-web/src/components/workspace/settings/skill-settings-page.tsx
index 04d42e06..e53ef9af 100644
--- a/frontend-web/src/components/workspace/settings/skill-settings-page.tsx
+++ b/frontend-web/src/components/workspace/settings/skill-settings-page.tsx
@@ -333,7 +333,7 @@ function SkillSettingsList({ onClose }: { onClose?: () => void }) {
   );
 }
 
-function SkillRow({
+export function SkillRow({
   skill,
   currentUserId,
   isAdmin,
diff --git a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
index c4d9c969..7b45abe7 100644
--- a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
@@ -155,7 +155,7 @@ export function WorkspaceNavChatList({
               >
                 <Link href="/page/workspace/scheduled/tasks">
                   <ListChecks />
-                  <span>任务管理</span>
+                  <span>定时任务</span>
                 </Link>
               </SidebarMenuButton>
             </SidebarMenuItem>
diff --git a/frontend-web/src/components/workspace/workspace-nav-menu.tsx b/frontend-web/src/components/workspace/workspace-nav-menu.tsx
index 110cd8b9..d87b34d9 100644
--- a/frontend-web/src/components/workspace/workspace-nav-menu.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-menu.tsx
@@ -2,6 +2,7 @@
 
 import {
   BellIcon,
+  BotIcon,
   BrainIcon,
   CalendarClockIcon,
   ChevronsUpDown,
@@ -12,6 +13,7 @@ import {
   Settings2Icon,
   SettingsIcon,
   ShieldCheckIcon,
+  SparklesIcon,
   TagsIcon,
   UsersIcon,
 } from "lucide-react";
@@ -182,6 +184,22 @@ export function WorkspaceNavMenu() {
                       定时任务管理
                     </DropdownMenuItem>
                   )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/agents")}
+                    >
+                      <BotIcon />
+                      智能体管理
+                    </DropdownMenuItem>
+                  )}
+                  {isAdmin && (
+                    <DropdownMenuItem
+                      onClick={() => navigate("/page/workspace/admin/skills")}
+                    >
+                      <SparklesIcon />
+                      技能管理
+                    </DropdownMenuItem>
+                  )}
                   {isAdmin && (
                     <DropdownMenuItem
                       onClick={() => navigate("/page/workspace/admin/tags")}
diff --git a/frontend-web/src/core/agents/api.ts b/frontend-web/src/core/agents/api.ts
index 3fb17baa..83eabbe8 100644
--- a/frontend-web/src/core/agents/api.ts
+++ b/frontend-web/src/core/agents/api.ts
@@ -38,6 +38,16 @@ export async function listAgents(params: ListAgentsParams = {}): Promise<Agent[]
   return data.agents;
 }
 
+export async function listAllAgentsAdmin(): Promise<Agent[]> {
+  const res = await apiFetch(`${getBackendBaseURL()}/api/agents?admin=true`);
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to load agents: ${res.statusText}`);
+  }
+  const data = (await res.json()) as { agents: Agent[] };
+  return data.agents;
+}
+
 export async function getAgent(id: string): Promise<Agent> {
   const res = await apiFetch(`${getBackendBaseURL()}/api/agents/${id}`);
   if (!res.ok) throw new Error(`Agent '${id}' not found`);
diff --git a/frontend-web/src/core/agents/hooks.ts b/frontend-web/src/core/agents/hooks.ts
index 802283f6..9099d63c 100644
--- a/frontend-web/src/core/agents/hooks.ts
+++ b/frontend-web/src/core/agents/hooks.ts
@@ -11,6 +11,7 @@ import {
   getAgent,
   getAgentSelector,
   listAgents,
+  listAllAgentsAdmin,
   listPrivateAgents,
   reorderFeaturedAgents,
   setAgentFeatured,
@@ -48,6 +49,21 @@ export function useAgents(params: { search?: string; tagIds?: string[] } = {}) {
   return { agents: data ?? [], isLoading, error };
 }
 
+/**
+ * Admin-only listing — returns every agent including unpublished agents owned
+ * by other users and private-square entries. Caller must be ``system_role
+ * === "admin"`` or the backend will 403.
+ */
+export function useAllAgentsAdmin(enabled: boolean) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["agents", "admin", "all"],
+    queryFn: () => listAllAgentsAdmin(),
+    enabled,
+    staleTime: 30_000,
+  });
+  return { agents: data ?? [], isLoading, error };
+}
+
 export function useAgent(id: string | null | undefined) {
   const { data, isLoading, error } = useQuery({
     queryKey: ["agents", id],
diff --git a/frontend-web/src/core/auth/sync.tsx b/frontend-web/src/core/auth/sync.tsx
new file mode 100644
index 00000000..e9f3b460
--- /dev/null
+++ b/frontend-web/src/core/auth/sync.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+import { getStoredAuth } from "@/core/auth";
+
+const AUTH_STORAGE_KEY = "deerflow.auth";
+
+function readUserId(): string | null {
+  return getStoredAuth()?.user_id ?? null;
+}
+
+/**
+ * Mount once at the app root. Watches `localStorage["deerflow.auth"]` for
+ * cross-tab changes — when another tab logs in as a different user, this tab
+ * still holds the previous user's cached state (chat list, thread ids, etc.)
+ * which then collides with the new token and surfaces as a 404 on "新对话".
+ * Reloading the tab is the simplest way to resync React state with the new
+ * identity.
+ */
+export function AuthSyncWatcher() {
+  const lastUserIdRef = useRef<string | null>(readUserId());
+
+  useEffect(() => {
+    function handleStorage(event: StorageEvent) {
+      if (event.key !== null && event.key !== AUTH_STORAGE_KEY) {
+        return;
+      }
+      const nextUserId = readUserId();
+      if (nextUserId === lastUserIdRef.current) {
+        return;
+      }
+      lastUserIdRef.current = nextUserId;
+      if (nextUserId === null) {
+        window.location.replace("#/login");
+        window.location.reload();
+        return;
+      }
+      window.location.reload();
+    }
+
+    window.addEventListener("storage", handleStorage);
+    return () => window.removeEventListener("storage", handleStorage);
+  }, []);
+
+  return null;
+}
diff --git a/frontend-web/src/core/skills/api.ts b/frontend-web/src/core/skills/api.ts
index 01a64404..c098d44f 100644
--- a/frontend-web/src/core/skills/api.ts
+++ b/frontend-web/src/core/skills/api.ts
@@ -1,7 +1,7 @@
 import { getBackendBaseURL } from "@/core/config";
 import { apiFetch } from "@/core/api";
 
-import type { Skill, SkillDisplayConfig, SkillState } from "./type";
+import type { Skill, SkillDisplayConfig, SkillState } from "./type";
 
 export interface ListSkillsParams {
   search?: string;
@@ -20,6 +20,17 @@ export async function loadSkills(params: ListSkillsParams = {}) {
   return json.skills as Skill[];
 }
 
+export async function loadAllSkillsAdmin() {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills?admin=true`,
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to load skills");
+  }
+  const json = await response.json();
+  return json.skills as Skill[];
+}
+
 export async function getSkill(skillName: string): Promise<Skill> {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}`,
@@ -30,7 +41,7 @@ export async function getSkill(skillName: string): Promise<Skill> {
   return response.json() as Promise<Skill>;
 }
 
-export async function enableSkill(skillName: string, enabled: boolean) {
+export async function enableSkill(skillName: string, enabled: boolean) {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/skills/${skillName}`,
     {
@@ -44,63 +55,63 @@ export async function enableSkill(skillName: string, enabled: boolean) {
     },
   );
   return response.json();
-}
-
-export async function setSkillDisplay(
-  skillName: string,
-  display: SkillDisplayConfig | null,
-  sample?: Record<string, unknown> | null,
-): Promise<Skill> {
-  const response = await apiFetch(
-    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display`,
-    {
-      method: "PUT",
-      headers: {
-        "Content-Type": "application/json",
-      },
-      body: JSON.stringify({ display, sample }),
-    },
-  );
-  if (!response.ok) {
-    throw await parseDetailedError(response, "Failed to update skill display adapter");
-  }
-  return response.json() as Promise<Skill>;
-}
-
-export interface SkillDisplaySampleResponse {
-  skill_name: string;
-  sample: Record<string, unknown>;
-}
-
-export interface PersistedSkillDisplaySampleResponse {
-  skill_name: string;
-  sample: Record<string, unknown> | null;
-}
-
-export async function getPersistedSkillDisplaySample(
-  skillName: string,
-): Promise<PersistedSkillDisplaySampleResponse> {
-  const response = await apiFetch(
-    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
-  );
-  if (!response.ok) {
-    throw await parseDetailedError(response, "Failed to get persisted skill display sample");
-  }
-  return response.json() as Promise<PersistedSkillDisplaySampleResponse>;
-}
-
-export async function getSkillDisplaySample(
-  skillName: string,
-): Promise<SkillDisplaySampleResponse> {
-  const response = await apiFetch(
-    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
-    { method: "POST" },
-  );
-  if (!response.ok) {
-    throw await parseDetailedError(response, "Failed to get skill display sample");
-  }
-  return response.json() as Promise<SkillDisplaySampleResponse>;
-}
+}
+
+export async function setSkillDisplay(
+  skillName: string,
+  display: SkillDisplayConfig | null,
+  sample?: Record<string, unknown> | null,
+): Promise<Skill> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display`,
+    {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ display, sample }),
+    },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to update skill display adapter");
+  }
+  return response.json() as Promise<Skill>;
+}
+
+export interface SkillDisplaySampleResponse {
+  skill_name: string;
+  sample: Record<string, unknown>;
+}
+
+export interface PersistedSkillDisplaySampleResponse {
+  skill_name: string;
+  sample: Record<string, unknown> | null;
+}
+
+export async function getPersistedSkillDisplaySample(
+  skillName: string,
+): Promise<PersistedSkillDisplaySampleResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to get persisted skill display sample");
+  }
+  return response.json() as Promise<PersistedSkillDisplaySampleResponse>;
+}
+
+export async function getSkillDisplaySample(
+  skillName: string,
+): Promise<SkillDisplaySampleResponse> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/skills/${encodeURIComponent(skillName)}/display-sample`,
+    { method: "POST" },
+  );
+  if (!response.ok) {
+    throw await parseDetailedError(response, "Failed to get skill display sample");
+  }
+  return response.json() as Promise<SkillDisplaySampleResponse>;
+}
 
 export interface InstallSkillRequest {
   thread_id: string;
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index aa27bb01..c869f40f 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -14,17 +14,17 @@ import {
   getSkillFiles,
   installSkillUpload,
   reconcileCustomSkills,
-  saveSkillFile,
-  setSkillDetail,
-  setSkillDisplay,
-  setSkillPinned,
+  saveSkillFile,
+  setSkillDetail,
+  setSkillDisplay,
+  setSkillPinned,
   setSkillPublished,
   setSkillState,
   validateSkillUpload,
 } from "./api";
-import type { Skill, SkillState } from "./type";
+import type { Skill, SkillState } from "./type";
 
-import { loadSkills } from ".";
+import { loadAllSkillsAdmin, loadSkills } from ".";
 
 export function useSkills(params: { search?: string; tagIds?: string[] } = {}) {
   const search = params.search ?? "";
@@ -37,6 +37,21 @@ export function useSkills(params: { search?: string; tagIds?: string[] } = {}) {
   return { skills: data ?? [], isLoading, error };
 }
 
+/**
+ * Admin-only listing — every skill in the system (built-in + every user's
+ * custom skills, including unpublished ones owned by other users). Backend
+ * 403s if the caller is not ``system_role === "admin"``.
+ */
+export function useAllSkillsAdmin(enabled: boolean) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["skills", "admin", "all"],
+    queryFn: () => loadAllSkillsAdmin(),
+    enabled,
+    staleTime: 30_000,
+  });
+  return { skills: data ?? [], isLoading, error };
+}
+
 export function useSkillContent(skillName: string | null) {
   return useQuery({
     queryKey: ["skill-content", skillName],
@@ -53,7 +68,7 @@ export function useSkill(skillName: string | null) {
   });
 }
 
-export function useSetSkillDetail() {
+export function useSetSkillDetail() {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: ({ skillName, detail }: { skillName: string; detail: string }) =>
@@ -63,32 +78,32 @@ export function useSetSkillDetail() {
       void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
     },
   });
-}
-
-export function useSetSkillDisplay() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: ({
-      skillName,
-      display,
-      sample,
-    }: {
-      skillName: string;
-      display: Parameters<typeof setSkillDisplay>[1];
-      sample?: Parameters<typeof setSkillDisplay>[2];
-    }) => setSkillDisplay(skillName, display, sample),
-    onSuccess: (data, { skillName }) => {
-      queryClient.setQueryData(["skill", skillName], data);
-      queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
-        Array.isArray(current)
-          ? current.map((item) => (item.name === skillName ? { ...item, ...data } : item))
-          : current,
-      );
-      void queryClient.invalidateQueries({ queryKey: ["skills"] });
-      void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
-    },
-  });
-}
+}
+
+export function useSetSkillDisplay() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      skillName,
+      display,
+      sample,
+    }: {
+      skillName: string;
+      display: Parameters<typeof setSkillDisplay>[1];
+      sample?: Parameters<typeof setSkillDisplay>[2];
+    }) => setSkillDisplay(skillName, display, sample),
+    onSuccess: (data, { skillName }) => {
+      queryClient.setQueryData(["skill", skillName], data);
+      queryClient.setQueriesData<Skill[]>({ queryKey: ["skills"] }, (current) =>
+        Array.isArray(current)
+          ? current.map((item) => (item.name === skillName ? { ...item, ...data } : item))
+          : current,
+      );
+      void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      void queryClient.invalidateQueries({ queryKey: ["skill", skillName] });
+    },
+  });
+}
 
 export function useEnableSkill() {
   const queryClient = useQueryClient();
diff --git a/frontend-web/src/pages/AdminAgentsPage.tsx b/frontend-web/src/pages/AdminAgentsPage.tsx
new file mode 100644
index 00000000..9a94f848
--- /dev/null
+++ b/frontend-web/src/pages/AdminAgentsPage.tsx
@@ -0,0 +1,82 @@
+"use client";
+
+import { BotIcon, SearchIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { Input } from "@/components/ui/input";
+import {
+  WorkspaceBody,
+  WorkspaceContainer,
+  WorkspaceHeader,
+} from "@/components/workspace/workspace-container";
+import { AgentCard } from "@/components/workspace/agents/agent-card";
+import { useAllAgentsAdmin } from "@/core/agents";
+import { desensitize } from "@/lib/desensitize";
+
+export default function AdminAgentsPage() {
+  const [search, setSearch] = useState("");
+  const { agents, isLoading } = useAllAgentsAdmin(true);
+
+  const filteredAgents = useMemo(() => {
+    const needle = search.trim().toLowerCase();
+    if (!needle) return agents;
+    return agents.filter((a) =>
+      desensitize(a.name).toLowerCase().includes(needle),
+    );
+  }, [agents, search]);
+
+  return (
+    <WorkspaceContainer>
+      <WorkspaceHeader />
+      <WorkspaceBody>
+        <div className="flex size-full min-h-0 flex-col">
+          <div className="flex items-start justify-between gap-4 border-b px-6 py-4">
+            <div>
+              <h1 className="text-xl font-semibold">智能体管理</h1>
+              <p className="text-muted-foreground mt-0.5 text-sm">
+                管理员视图：查看、编辑、删除所有用户的智能体（包括内置、用户自定义与私密广场条目）。
+              </p>
+            </div>
+            <div className="relative w-64 shrink-0">
+              <SearchIcon className="text-muted-foreground absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
+              <Input
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+                placeholder="按名称搜索"
+                className="pl-8"
+              />
+            </div>
+          </div>
+
+          <div className="flex-1 overflow-y-auto p-6">
+            {isLoading ? (
+              <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
+                加载中…
+              </div>
+            ) : filteredAgents.length === 0 ? (
+              <div className="flex h-64 flex-col items-center justify-center gap-3 text-center">
+                <div className="bg-muted flex h-14 w-14 items-center justify-center rounded-full">
+                  <BotIcon className="text-muted-foreground h-7 w-7" />
+                </div>
+                <p className="text-muted-foreground text-sm">
+                  当前没有可管理的智能体。
+                </p>
+              </div>
+            ) : (
+              <>
+                <p className="text-muted-foreground mb-3 text-xs">
+                  共 {filteredAgents.length} 个智能体。
+                </p>
+                <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+                  {filteredAgents.map((agent) => (
+                    <AgentCard key={agent.id} agent={agent} />
+                  ))}
+                </div>
+              </>
+            )}
+          </div>
+        </div>
+      </WorkspaceBody>
+    </WorkspaceContainer>
+  );
+}
diff --git a/frontend-web/src/pages/AdminSkillsPage.tsx b/frontend-web/src/pages/AdminSkillsPage.tsx
new file mode 100644
index 00000000..521ad859
--- /dev/null
+++ b/frontend-web/src/pages/AdminSkillsPage.tsx
@@ -0,0 +1,140 @@
+"use client";
+
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  SearchIcon,
+  SparklesIcon,
+} from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import {
+  WorkspaceBody,
+  WorkspaceContainer,
+  WorkspaceHeader,
+} from "@/components/workspace/workspace-container";
+import { SkillRow } from "@/components/workspace/settings/skill-settings-page";
+import { getStoredAuth } from "@/core/auth";
+import { useAllSkillsAdmin } from "@/core/skills/hooks";
+import { desensitize } from "@/lib/desensitize";
+
+const PAGE_SIZE = 10;
+
+export default function AdminSkillsPage() {
+  const [search, setSearch] = useState("");
+  const [page, setPage] = useState(1);
+  const { skills, isLoading, error } = useAllSkillsAdmin(true);
+
+  const storedAuth = useMemo(() => getStoredAuth(), []);
+  const currentUserId = storedAuth?.user_id ?? null;
+
+  // Hide archived/stale entries here — they remain accessible from the regular
+  // skills settings dialog. The admin page is for live skills only.
+  const filteredSkills = useMemo(() => {
+    const needle = search.trim().toLowerCase();
+    return skills
+      .filter((s) => (s.state ?? "active") === "active")
+      .filter((s) => !needle || desensitize(s.name).toLowerCase().includes(needle));
+  }, [skills, search]);
+
+  const totalPages = Math.max(1, Math.ceil(filteredSkills.length / PAGE_SIZE));
+  useEffect(() => {
+    if (page > totalPages) setPage(totalPages);
+  }, [page, totalPages]);
+  const pagedSkills = useMemo(
+    () => filteredSkills.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE),
+    [filteredSkills, page],
+  );
+
+  return (
+    <WorkspaceContainer>
+      <WorkspaceHeader />
+      <WorkspaceBody>
+        <div className="flex size-full min-h-0 flex-col">
+          <div className="flex items-start justify-between gap-4 border-b px-6 py-4">
+            <div>
+              <h1 className="text-xl font-semibold">技能管理</h1>
+              <p className="text-muted-foreground mt-0.5 text-sm">
+                管理员视图：查看、编辑、删除所有用户的技能（包括内置技能与未发布的自定义技能）。
+              </p>
+            </div>
+            <div className="relative w-64 shrink-0">
+              <SearchIcon className="text-muted-foreground absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
+              <Input
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+                placeholder="按名称搜索"
+                className="pl-8"
+              />
+            </div>
+          </div>
+
+          <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-6">
+            {isLoading && (
+              <div className="text-muted-foreground flex h-40 items-center justify-center text-sm">
+                加载中…
+              </div>
+            )}
+            {error && (
+              <div className="text-destructive text-sm">
+                加载失败：{error.message}
+              </div>
+            )}
+            {!isLoading && !error && filteredSkills.length === 0 && (
+              <div className="flex h-64 flex-col items-center justify-center gap-3 text-center">
+                <div className="bg-muted flex h-14 w-14 items-center justify-center rounded-full">
+                  <SparklesIcon className="text-muted-foreground h-7 w-7" />
+                </div>
+                <p className="text-muted-foreground text-sm">
+                  当前没有可管理的技能。
+                </p>
+              </div>
+            )}
+            {!isLoading && !error && filteredSkills.length > 0 && (
+              <>
+                <p className="text-muted-foreground text-xs">
+                  共 {filteredSkills.length} 个技能。
+                </p>
+                {pagedSkills.map((skill) => (
+                  <SkillRow
+                    key={skill.name}
+                    skill={skill}
+                    currentUserId={currentUserId}
+                    isAdmin
+                  />
+                ))}
+              </>
+            )}
+            {!isLoading && !error && totalPages > 1 && (
+              <div className="flex items-center justify-end gap-2 pt-1">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  disabled={page <= 1}
+                  onClick={() => setPage((p) => Math.max(1, p - 1))}
+                >
+                  <ChevronLeftIcon className="size-4" />
+                  上一页
+                </Button>
+                <span className="text-muted-foreground text-xs">
+                  第 {page} / {totalPages} 页
+                </span>
+                <Button
+                  size="sm"
+                  variant="outline"
+                  disabled={page >= totalPages}
+                  onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+                >
+                  下一页
+                  <ChevronRightIcon className="size-4" />
+                </Button>
+              </div>
+            )}
+          </div>
+        </div>
+      </WorkspaceBody>
+    </WorkspaceContainer>
+  );
+}
diff --git a/frontend-web/src/pages/WorkspaceRoutes.tsx b/frontend-web/src/pages/WorkspaceRoutes.tsx
index 3d05b53c..8ad09805 100644
--- a/frontend-web/src/pages/WorkspaceRoutes.tsx
+++ b/frontend-web/src/pages/WorkspaceRoutes.tsx
@@ -18,7 +18,9 @@ import ChatPage from "./ChatPage";
 import AgentsPage from "./AgentsPage";
 import AgentChatPage from "./AgentChatPage";
 import NewAgentPage from "./NewAgentPage";
+import AdminAgentsPage from "./AdminAgentsPage";
 import AdminScheduledTasksPage from "./AdminScheduledTasksPage";
+import AdminSkillsPage from "./AdminSkillsPage";
 import ScheduledTaskRunDetailPage from "./ScheduledTaskRunDetailPage";
 import ScheduledTasksPage from "./ScheduledTasksPage";
 import LlmMetricsPage from "./LlmMetricsPage";
@@ -260,6 +262,30 @@ export default function WorkspaceRoutes({
           )
         }
       />
+      <Route
+        path="admin/agents"
+        element={
+          getStoredAuth()?.system_role === "admin" ? (
+            <WorkspaceLayout {...layoutProps}>
+              <AdminAgentsPage />
+            </WorkspaceLayout>
+          ) : (
+            <Navigate to="/page/workspace/chats/new" replace />
+          )
+        }
+      />
+      <Route
+        path="admin/skills"
+        element={
+          getStoredAuth()?.system_role === "admin" ? (
+            <WorkspaceLayout {...layoutProps}>
+              <AdminSkillsPage />
+            </WorkspaceLayout>
+          ) : (
+            <Navigate to="/page/workspace/chats/new" replace />
+          )
+        }
+      />
       <Route
         path="admin/tags"
         element={
diff --git a/offline-backend-20260512/backend/app/gateway/routers/agents.py b/offline-backend-20260512/backend/app/gateway/routers/agents.py
index 9b836a95..1fb66c5e 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/agents.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/agents.py
@@ -297,17 +297,21 @@ async def _get_editable_or_raise(
 ) -> tuple[dict[str, Any], str]:
     """Return (record, edit_mode) where edit_mode is 'owner' or 'admin'.
 
-    'admin' is granted only when the agent is built-in (user_id IS NULL) and the
-    caller is a system admin. Custom agents owned by other users still 403.
+    Admins may edit any agent — built-in (``user_id IS NULL``) or owned by
+    another user — so the admin console can manage the full agent catalog.
+    Non-admin callers are still restricted to agents they own.
     """
     owned = await store.get_owned(agent_id, user_id)
     if owned is not None:
         return owned, "owner"
+    if is_admin:
+        record = await store.get_any(agent_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
+        return record, "admin"
     visible = await store.get_visible(agent_id, user_id)
     if visible is None:
         raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
-    if is_admin and visible.get("user_id") is None:
-        return visible, "admin"
     raise HTTPException(status_code=403, detail="You can only modify agents that you created")
 
 
@@ -321,6 +325,14 @@ async def list_agents(
     request: Request,
     search: str | None = Query(default=None, description="Case-insensitive fuzzy match on agent name"),
     tag_ids: list[str] | None = Query(default=None, description="Keep agents carrying any of these tags (OR)"),
+    admin: bool = Query(
+        default=False,
+        description=(
+            "Admin-only override. When ``true`` and the caller is a system admin, "
+            "every agent is returned (built-in + every user's agents + private-square "
+            "entries) regardless of the usual ownership/visibility filter."
+        ),
+    ),
 ) -> AgentsListResponse:
     _require_agents_api_enabled()
 
@@ -329,7 +341,12 @@ async def list_agents(
         tag_store: TagStore = get_tag_store(request)
         await _sync_legacy_agents(store)
         user_id = _current_user_id(request)
-        agents = await store.list_visible(user_id)
+        if admin:
+            if not _is_admin_user(request):
+                raise HTTPException(status_code=403, detail="Only system admins can list all agents")
+            agents = await store.list_all()
+        else:
+            agents = await store.list_visible(user_id)
         responses = [_record_to_response(a, include_soul=True) for a in agents]
 
         assignments = await tag_store.list_assignments("agent", [r.id for r in responses])
@@ -527,7 +544,10 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
         if not update_data:
             record = current
         elif edit_mode == "admin":
-            record = await store.update_builtin(agent_id, update_data)
+            # Admins may edit built-in (``user_id IS NULL``) and any user-owned
+            # agent — ``update_any`` skips the ownership check that ``update``
+            # and ``update_builtin`` enforce.
+            record = await store.update_any(agent_id, update_data)
         else:
             record = await store.update(agent_id, user_id, update_data)
         if record is None:
@@ -614,7 +634,7 @@ async def delete_agent(agent_id: str, request: Request) -> None:
         )
 
         if edit_mode == "admin":
-            deleted = await store.delete_builtin(agent_id)
+            deleted = await store.delete_any(agent_id)
         else:
             deleted = await store.delete(agent_id, user_id)
         if not deleted:
diff --git a/offline-backend-20260512/backend/app/gateway/routers/skills.py b/offline-backend-20260512/backend/app/gateway/routers/skills.py
index 2a1c6496..9e6dc8d6 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/skills.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/skills.py
@@ -695,11 +695,25 @@ async def list_skills(
     tag_store: TagStore = Depends(get_tag_store),
     search: str | None = Query(default=None, description="Case-insensitive fuzzy match on skill name"),
     tag_ids: list[str] | None = Query(default=None, description="Keep skills carrying any of these tags (OR)"),
+    admin: bool = Query(
+        default=False,
+        description=(
+            "Admin-only override. When ``true`` and the caller is a system admin, "
+            "every custom skill is returned (including unpublished skills owned by "
+            "other users) regardless of the usual ownership filter."
+        ),
+    ),
 ) -> SkillsListResponse:
     try:
         user_id = _current_user_id(request)
+        if admin and not _is_admin_user(request):
+            raise HTTPException(status_code=403, detail="Only system admins can list all skills")
         all_skills = get_or_new_skill_storage(app_config=config).load_skills(enabled_only=False)
-        ownership = await _build_ownership_index(skill_store, user_id)
+        if admin:
+            ownership_records = await skill_store.list_all()
+            ownership = {record["name"]: record for record in ownership_records}
+        else:
+            ownership = await _build_ownership_index(skill_store, user_id)
         display_adapters = await _list_skill_display_adapters([skill.name for skill in all_skills])
         responses: list[SkillResponse] = []
         for skill in all_skills:
@@ -720,7 +734,11 @@ async def list_skills(
                 continue
             record = ownership.get(skill.name)
             if record is None:
-                continue
+                if not admin:
+                    continue
+                # Admin sees every custom skill on disk even without an
+                # ownership row (legacy / orphaned), so they can clean it up.
+                record = None
             responses.append(
                 _skill_to_response(
                     skill,
@@ -731,6 +749,8 @@ async def list_skills(
             )
         responses = await _attach_and_filter_tags(tag_store, responses, search, tag_ids)
         return SkillsListResponse(skills=responses)
+    except HTTPException:
+        raise
     except Exception as e:
         logger.error(f"Failed to load skills: {e}", exc_info=True)
         raise HTTPException(status_code=500, detail=f"Failed to load skills: {str(e)}")
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/llm_error_handling_middleware.py b/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/llm_error_handling_middleware.py
index 02ced2c8..7d641553 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/llm_error_handling_middleware.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/llm_error_handling_middleware.py
@@ -61,6 +61,21 @@ _AUTH_PATTERNS = (
     "无权",
     "未授权",
 )
+# Upstream model gateway returned a malformed payload (typically a JSON decode
+# error wrapped as `bad_response_status_code`, or a truncated/garbled inference
+# response). These are almost always transient inference-side issues and safe
+# to retry.
+_UPSTREAM_GARBAGE_PATTERNS = (
+    "bad_response_status_code",
+    "bad response status",
+    "expecting ',' delimiter",
+    "expecting value",
+    "expecting property name",
+    "unexpected character",
+    "unterminated string",
+    "extra data",
+    "jsondecodeerror",
+)
 
 
 class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
@@ -139,9 +154,10 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
         detail = _extract_error_detail(exc)
         lowered = detail.lower()
         error_code = _extract_error_code(exc)
+        error_code_lower = str(error_code).lower() if error_code is not None else ""
         status_code = _extract_status_code(exc)
 
-        if _matches_any(lowered, _QUOTA_PATTERNS) or _matches_any(str(error_code).lower(), _QUOTA_PATTERNS):
+        if _matches_any(lowered, _QUOTA_PATTERNS) or _matches_any(error_code_lower, _QUOTA_PATTERNS):
             return False, "quota"
         if _matches_any(lowered, _AUTH_PATTERNS):
             return False, "auth"
@@ -159,6 +175,11 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
             return True, "transient"
         if _matches_any(lowered, _BUSY_PATTERNS):
             return True, "busy"
+        # Treat upstream gateway garbage (malformed JSON, truncated responses)
+        # as a retriable transient — the deterministic char-position errors we
+        # see from vLLM/proxy layers usually clear on a re-roll.
+        if _matches_any(lowered, _UPSTREAM_GARBAGE_PATTERNS) or _matches_any(error_code_lower, _UPSTREAM_GARBAGE_PATTERNS):
+            return True, "upstream"
 
         return False, "generic"
 
@@ -171,21 +192,34 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
 
     def _build_retry_message(self, attempt: int, wait_ms: int, reason: str) -> str:
         seconds = max(1, round(wait_ms / 1000))
-        reason_text = "服务繁忙" if reason == "busy" else "网络/连接异常"
+        if reason == "busy":
+            reason_text = "服务繁忙"
+        elif reason == "upstream":
+            reason_text = "上游响应异常"
+        else:
+            reason_text = "网络/连接异常"
         return f"大模型因{reason_text}调用失败，正在第 {attempt}/{self.retry_max_attempts} 次重试，{seconds} 秒后继续…"
 
     def _build_circuit_breaker_message(self) -> str:
         return "大模型因连续多次调用失败已被熔断保护，请稍候再试。"
 
-    def _build_user_message(self, exc: BaseException, reason: str) -> str:
-        detail = _extract_error_detail(exc)
+    def _build_user_message(self, reason: str) -> str:
         if reason == "quota":
             return "大模型因账户额度不足、账单异常或使用受限而拒绝请求，请检查模型账户后再试。"
         if reason == "auth":
             return "大模型因鉴权失败或无访问权限而拒绝请求,请检查模型的 API Key 与权限配置后再试。"
         if reason in {"busy", "transient"}:
             return "大模型因服务繁忙或网络异常，多次重试后仍未恢复,请稍候再继续。"
-        return f"大模型因「{detail}」原因调用失败。"
+        if reason == "upstream":
+            return "大模型当前响应异常（上游模型或网关临时故障），多次重试后仍未恢复，请稍后再试或更换模型。"
+        # NOTE: We intentionally do NOT embed the raw exception detail into the
+        # user-facing message. Raw `Error code: 400 - {...}` strings — especially
+        # Python repr-style dict literals — get persisted as AI messages and then
+        # re-fed to the model on the next turn, where their unescaped quotes /
+        # braces can corrupt the upstream JSON payload and cause deterministic
+        # JSONDecodeError loops. Keep the user message clean; full detail is
+        # already in the backend log via `logger.warning(..., exc_info=exc)`.
+        return "大模型本次调用未能成功完成，请稍后再试或更换模型。"
 
     def _emit_retry_event(self, attempt: int, wait_ms: int, reason: str) -> None:
         try:
@@ -249,7 +283,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                 )
                 if retriable:
                     self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return AIMessage(content=self._build_user_message(reason))
 
     @override
     async def awrap_model_call(
@@ -295,7 +329,7 @@ class LLMErrorHandlingMiddleware(AgentMiddleware[AgentState]):
                 )
                 if retriable:
                     self._record_failure()
-                return AIMessage(content=self._build_user_message(exc, reason))
+                return AIMessage(content=self._build_user_message(reason))
 
 
 def _matches_any(detail: str, patterns: tuple[str, ...]) -> bool:
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
index 39b5e6f7..84d38732 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/base.py
@@ -90,3 +90,30 @@ class AgentStore(ABC):
         already verified the admin-configured private-square password.
         """
         raise NotImplementedError
+
+    @abstractmethod
+    async def list_all(self) -> list[dict[str, Any]]:
+        """Return every agent regardless of ownership/visibility.
+
+        Caller is responsible for authorization — typically the caller has
+        already verified ``system_role == "admin"``.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def update_any(self, agent_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
+        """Update any agent row by id, regardless of ownership.
+
+        Caller is responsible for authorization (admin only). Returns ``None``
+        if the agent does not exist.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def delete_any(self, agent_id: str) -> bool:
+        """Delete any agent row by id, regardless of ownership.
+
+        Caller is responsible for authorization (admin only). Returns
+        ``False`` if the agent does not exist.
+        """
+        raise NotImplementedError
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/memory.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/memory.py
index 269f3660..6ec8d840 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/memory.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/memory.py
@@ -138,3 +138,29 @@ class MemoryAgentStore(AgentStore):
         rows = [self._agents[aid] for aid in agent_ids if aid in self._agents and self._is_visible(self._agents[aid], user_id)]
         rows.sort(key=lambda a: order_map.get(a["id"], 0))
         return [_copy(a) for a in rows]
+
+    async def list_private(self) -> list[dict[str, Any]]:
+        rows = [_copy(a) for a in self._agents.values() if bool(a.get("is_private"))]
+        rows.sort(key=lambda a: a.get("created_at") or "")
+        return rows
+
+    async def list_all(self) -> list[dict[str, Any]]:
+        rows = [_copy(a) for a in self._agents.values()]
+        rows.sort(key=lambda a: a.get("created_at") or "")
+        return rows
+
+    async def update_any(self, agent_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
+        row = self._agents.get(agent_id)
+        if row is None:
+            return None
+        for key in ("name", "description", "published", "is_private"):
+            if key in data:
+                row[key] = data[key]
+        row["updated_at"] = _now()
+        return _copy(row)
+
+    async def delete_any(self, agent_id: str) -> bool:
+        if agent_id not in self._agents:
+            return False
+        self._agents.pop(agent_id, None)
+        return True
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
index 60474ac5..2fa22e25 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/agents/sql.py
@@ -202,3 +202,31 @@ class AgentRepository(AgentStore):
         async with self._sf() as session:
             result = await session.execute(stmt)
             return [_row_to_dict(row) for row in result.scalars()]
+
+    async def list_all(self) -> list[dict[str, Any]]:
+        stmt = select(AgentRow).order_by(AgentRow.created_at.asc())
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [_row_to_dict(row) for row in result.scalars()]
+
+    async def update_any(self, agent_id: str, data: dict[str, Any]) -> dict[str, Any] | None:
+        async with self._sf() as session:
+            row = await session.get(AgentRow, agent_id)
+            if row is None:
+                return None
+            for key in ("name", "description", "published", "is_private"):
+                if key in data:
+                    setattr(row, key, data[key])
+            row.updated_at = datetime.now(UTC)
+            await session.commit()
+            await session.refresh(row)
+            return _row_to_dict(row)
+
+    async def delete_any(self, agent_id: str) -> bool:
+        async with self._sf() as session:
+            row = await session.get(AgentRow, agent_id)
+            if row is None:
+                return False
+            await session.delete(row)
+            await session.commit()
+            return True
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/base.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/base.py
index 4f82cb4d..f84ea8a5 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/base.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/base.py
@@ -68,6 +68,14 @@ class SkillStore(ABC):
         """Return the number of skills owned by ``user_id`` (owner_user_id IS NOT NULL)."""
         raise NotImplementedError
 
+    @abstractmethod
+    async def list_all(self) -> list[dict[str, Any]]:
+        """Return every skill record regardless of ownership/visibility.
+
+        Caller is responsible for authorization (admin only).
+        """
+        raise NotImplementedError
+
     @abstractmethod
     async def list_published_names(self) -> set[str]:
         """Return the set of skill names with ``published = True`` (any owner).
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/memory.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/memory.py
index 836341f7..d774f560 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/memory.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/memory.py
@@ -134,5 +134,11 @@ class MemorySkillStore(SkillStore):
     async def count_owned(self, user_id: str) -> int:
         return sum(1 for s in self._skills.values() if s.get("owner_user_id") == user_id)
 
+    async def list_all(self) -> list[dict[str, Any]]:
+        return [
+            _with_derived(_copy(record))  # type: ignore[arg-type]
+            for record in self._skills.values()
+        ]
+
     async def list_published_names(self) -> set[str]:
         return {name for name, record in self._skills.items() if record.get("published")}
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/sql.py b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/sql.py
index 84f9a91d..e17dd015 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/sql.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/persistence/skills/sql.py
@@ -149,6 +149,12 @@ class SkillRepository(SkillStore):
         async with self._sf() as session:
             return await session.scalar(stmt) or 0
 
+    async def list_all(self) -> list[dict[str, Any]]:
+        stmt = select(SkillRow).order_by(SkillRow.created_at.asc())
+        async with self._sf() as session:
+            result = await session.execute(stmt)
+            return [_row_to_dict(row) for row in result.scalars()]
+
     async def list_published_names(self) -> set[str]:
         stmt = select(SkillRow.name).where(SkillRow.published.is_(True))
         async with self._sf() as session:

From c56db15a039874214074f492678ed334b98494e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Wed, 27 May 2026 17:40:10 +0800
Subject: [PATCH 12/15] =?UTF-8?q?=E5=AE=9E=E7=8E=B0RAG=E5=8F=82=E8=80=83?=
 =?UTF-8?q?=E6=96=87=E7=8C=AE=E6=98=BE=E7=A4=BA=E6=A8=A1=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/workspace/chats/chat-box.tsx   | 284 +++++++++++-
 .../src/components/workspace/input-box.tsx    |  51 +-
 .../workspace/messages/markdown-content.tsx   |  11 +-
 .../workspace/messages/message-list-item.tsx  |  11 +-
 .../workspace/messages/message-list.tsx       |  10 +-
 .../settings/appearance-settings-page.tsx     |  40 +-
 .../workspace/skill-display-sources.tsx       |  23 +-
 .../src/core/messages/search-results.ts       |  12 +
 frontend-web/src/core/settings/index.ts       |   5 +-
 frontend-web/src/core/settings/local.ts       |  35 +-
 .../src/core/skill-display/runtime.ts         | 196 ++++++--
 frontend-web/src/core/system-settings/api.ts  |  40 ++
 .../src/core/system-settings/hooks.ts         |  25 +
 frontend-web/src/core/threads/hooks.ts        |  83 +++-
 frontend-web/src/styles/globals.css           |  16 +-
 .../app/gateway/routers/system_settings.py    |  36 ++
 .../backend/app/gateway/routers/threads.py    | 437 ++++++++++++++++--
 .../backend/app/gateway/services.py           |  99 +++-
 .../deerflow/agents/lead_agent/agent.py       |  25 +-
 .../middlewares/rag_citation_middleware.py    | 109 +++++
 .../deerflow/config/system_settings.py        |  11 +
 .../harness/deerflow/runtime/references.py    | 366 +++++++++++++++
 22 files changed, 1733 insertions(+), 192 deletions(-)
 create mode 100644 offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/rag_citation_middleware.py
 create mode 100644 offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py

diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index 31ec10d9..20b6e434 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -12,7 +12,9 @@ import {
   ResizablePanelGroup,
 } from "@/components/ui/resizable";
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
-import { useLocalSettings } from "@/core/settings";
+import { apiFetch } from "@/core/api";
+import { getBackendBaseURL } from "@/core/config";
+import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
 import { useSkills } from "@/core/skills/hooks";
 import {
   buildSkillDisplayMap,
@@ -33,6 +35,33 @@ const CLOSE_MODE = { chat: 100, artifacts: 0 };
 const OPEN_MODE = { chat: 60, artifacts: 40 };
 const SHOW_REFERENCE_EVENT = "workspace:show-reference";
 
+type BackendReferenceSource = Parameters<typeof SkillDisplaySources>[0]["sources"][number];
+
+type BackendReferenceBatch = {
+  id: string;
+  assistant_message_id?: string;
+  sources: BackendReferenceSource[];
+};
+
+function logReferenceDebug(
+  event: string,
+  threadId: string,
+  payload: Record<string, unknown>,
+) {
+  console.info(`[RAG引用调试] ${event}`, payload);
+  void apiFetch(`${getBackendBaseURL()}/api/threads/reference-debug-log`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      event,
+      thread_id: threadId,
+      payload,
+    }),
+  }).catch(() => {
+    // Debug logging must never affect the chat flow.
+  });
+}
+
 const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   children,
   threadId,
@@ -42,10 +71,17 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   const threadIdRef = useRef(threadId);
   const artifactsCountRef = useRef(0);
   const layoutRef = useRef<GroupImperativeHandle>(null);
+  const latestReferenceBatchIdRef = useRef<string | null>(null);
+  const manualReferenceBatchRef = useRef(false);
+  const referenceDebugSignatureRef = useRef<string>("");
   const [sideTab, setSideTab] = useState("document");
   const [referencesOpen, setReferencesOpen] = useState(true);
   const [activeReferenceBatchId, setActiveReferenceBatchId] = useState<string | null>(null);
+  const [pinnedReferenceId, setPinnedReferenceId] = useState<string | null>(null);
+  const [backendReferenceBatches, setBackendReferenceBatches] = useState<BackendReferenceBatch[]>([]);
   const [settings] = useLocalSettings();
+  const ragModeEnabled =
+    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
   const { skills } = useSkills();
 
   const {
@@ -60,27 +96,84 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
 
   const [autoSelectFirstArtifact, setAutoSelectFirstArtifact] = useState(true);
   const skillDisplayMap = useMemo(
-    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [settings.display.ragModeEnabled, skills],
+    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [ragModeEnabled, skills],
   );
-  const referenceBatches = useMemo(() => {
-    if (!settings.display.ragModeEnabled) {
+  const fallbackReferenceBatches = useMemo(() => {
+    if (!ragModeEnabled) {
       return [];
     }
-    const messages = thread.values.messages ?? [];
-    return messages
-      .filter((message) => message.type === "ai" && message.id)
-      .map((message) => ({
-        id: message.id!,
-        sources: collectRuntimeDisplaySources(messages, skillDisplayMap, {
-          afterMessageId: findPreviousHumanMessageId(messages, message.id),
-          beforeMessageId: message.id,
-          includeBeforeMessage: true,
-          includeModes: ["citation"],
-        }).filter((source) => source.mode === "citation"),
-      }))
-      .filter((batch) => batch.sources.length > 0);
-  }, [settings.display.ragModeEnabled, skillDisplayMap, thread.values.messages]);
+    return buildTurnReferenceBatches(
+      thread.values.messages ?? [],
+      skillDisplayMap,
+      thread.isLoading,
+    );
+  }, [ragModeEnabled, skillDisplayMap, thread.isLoading, thread.values.messages]);
+  useEffect(() => {
+    if (!ragModeEnabled) {
+      setBackendReferenceBatches([]);
+      return;
+    }
+    if (thread.isLoading) {
+      return;
+    }
+    const controller = new AbortController();
+    logReferenceDebug("开始拉取后端参考文献", threadId, {
+      messageCount: thread.values.messages?.length ?? 0,
+    });
+    apiFetch(
+      `${getBackendBaseURL()}/api/threads/${encodeURIComponent(threadId)}/reference-batches`,
+      { signal: controller.signal },
+    )
+      .then(async (response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to load reference batches: ${response.status}`);
+        }
+        return (await response.json()) as { batches?: BackendReferenceBatch[] };
+      })
+      .then((data) => {
+        const batches = data.batches ?? [];
+        logReferenceDebug("后端参考文献返回", threadId, {
+          batchCount: batches.length,
+          sourceCounts: batches.map((batch) => batch.sources?.length ?? 0),
+          batchIds: batches.map((batch) => batch.id),
+        });
+        setBackendReferenceBatches(batches);
+      })
+      .catch((error) => {
+        if (!controller.signal.aborted) {
+          console.warn("Failed to load backend reference batches", error);
+        }
+      });
+    return () => controller.abort();
+  }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]);
+  const referenceBatches =
+    backendReferenceBatches.length > 0
+      ? backendReferenceBatches
+      : fallbackReferenceBatches;
+  useEffect(() => {
+    if (!ragModeEnabled) {
+      return;
+    }
+    const signature = JSON.stringify({
+      backend: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      fallback: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      final: referenceBatches.map((batch) => batch.sources?.length ?? 0),
+    });
+    if (referenceDebugSignatureRef.current === signature) {
+      return;
+    }
+    referenceDebugSignatureRef.current = signature;
+    logReferenceDebug("前端参考文献来源选择", threadId, {
+      using: backendReferenceBatches.length > 0 ? "后端接口" : "前端兜底",
+      backendBatchCount: backendReferenceBatches.length,
+      backendSourceCounts: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      fallbackBatchCount: fallbackReferenceBatches.length,
+      fallbackSourceCounts: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      finalBatchCount: referenceBatches.length,
+      finalSourceCounts: referenceBatches.map((batch) => batch.sources?.length ?? 0),
+    });
+  }, [backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
   const latestReferenceBatch =
     referenceBatches.length > 0
       ? referenceBatches[referenceBatches.length - 1]!
@@ -98,20 +191,32 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
   useEffect(() => {
     if (!latestReferenceBatch) {
       setActiveReferenceBatchId(null);
+      latestReferenceBatchIdRef.current = null;
+      manualReferenceBatchRef.current = false;
       return;
     }
+    const previousLatestId = latestReferenceBatchIdRef.current;
+    latestReferenceBatchIdRef.current = latestReferenceBatch.id;
     setActiveReferenceBatchId((current) =>
-      current && referenceBatches.some((batch) => batch.id === current)
+      current &&
+      referenceBatches.some((batch) => batch.id === current) &&
+      manualReferenceBatchRef.current &&
+      current !== previousLatestId
         ? current
         : latestReferenceBatch.id,
     );
   }, [latestReferenceBatch?.id, referenceBatches]);
   useEffect(() => {
     const handleShowReference = (event: Event) => {
-      const detail = (event as CustomEvent<{ batchId?: string }>).detail;
+      const detail = (event as CustomEvent<{ batchId?: string; referenceId?: string }>).detail;
       if (detail?.batchId) {
+        manualReferenceBatchRef.current = true;
         setActiveReferenceBatchId(detail.batchId);
       }
+      setPinnedReferenceId(null);
+      window.setTimeout(() => {
+        setPinnedReferenceId(detail?.referenceId ?? null);
+      }, 0);
       setReferencesOpen(true);
       setSideTab("references");
     };
@@ -125,7 +230,13 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
       threadIdRef.current = threadId;
       artifactsCountRef.current = 0;
       deselect();
-      setReferencesOpen(true);
+      setReferencesOpen(false);
+      setActiveReferenceBatchId(null);
+      setPinnedReferenceId(null);
+      setBackendReferenceBatches([]);
+      latestReferenceBatchIdRef.current = null;
+      manualReferenceBatchRef.current = false;
+      referenceDebugSignatureRef.current = "";
     }
 
     // Update artifacts from the current thread
@@ -257,7 +368,10 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
                 />
               </TabsContent>
               <TabsContent value="references" className="min-h-0 flex-1 overflow-y-auto p-0">
-                <ReferencePanel sources={referenceSources} />
+                <ReferencePanel
+                  highlightedReferenceId={pinnedReferenceId}
+                  sources={referenceSources}
+                />
               </TabsContent>
             </Tabs>
           ) : selectedArtifact ? (
@@ -280,7 +394,10 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
                   <XIcon />
                 </Button>
               </div>
-              <ReferencePanel sources={referenceSources} />
+              <ReferencePanel
+                highlightedReferenceId={pinnedReferenceId}
+                sources={referenceSources}
+              />
             </div>
           ) : (
             <div className="relative flex size-full justify-center">
@@ -324,10 +441,27 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
 };
 
 function ReferencePanel({
+  highlightedReferenceId,
   sources,
 }: {
+  highlightedReferenceId?: string | null;
   sources: Parameters<typeof SkillDisplaySources>[0]["sources"];
 }) {
+  const orderedSources = useMemo(() => {
+    if (!highlightedReferenceId) {
+      return sources;
+    }
+    const index = Number(highlightedReferenceId);
+    if (!Number.isFinite(index)) {
+      return sources;
+    }
+    const selected = sources.find((source) => source.index === index);
+    if (!selected) {
+      return sources;
+    }
+    return [selected, ...sources.filter((source) => source.index !== index)];
+  }, [highlightedReferenceId, sources]);
+
   return (
     <div className="flex size-full flex-col overflow-hidden">
       <header className="shrink-0 px-1 pb-3">
@@ -344,7 +478,10 @@ function ReferencePanel({
         </p>
       </header>
       <main className="min-h-0 flex-1 overflow-y-auto px-1 pt-1 pb-6">
-        <SkillDisplaySources sources={sources} />
+        <SkillDisplaySources
+          highlightedReferenceId={highlightedReferenceId}
+          sources={orderedSources}
+        />
       </main>
     </div>
   );
@@ -368,4 +505,101 @@ function findPreviousHumanMessageId(
   return undefined;
 }
 
+function buildTurnReferenceBatches(
+  messages: Message[],
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+  isLoading: boolean,
+): BackendReferenceBatch[] {
+  const batches: BackendReferenceBatch[] = [];
+  for (let index = 0; index < messages.length; index++) {
+    const human = messages[index];
+    if (human?.type !== "human" || !human.id) {
+      continue;
+    }
+    const nextHumanIndex = findNextHumanIndex(messages, index + 1);
+    if (nextHumanIndex === -1 && isLoading) {
+      continue;
+    }
+    const endIndex = nextHumanIndex === -1 ? messages.length : nextHumanIndex;
+    const assistant = findLastAssistantAnswer(messages, index + 1, endIndex);
+    if (!assistant?.id) {
+      continue;
+    }
+    const sources = collectRuntimeDisplaySources(messages, skillDisplayMap, {
+      afterMessageId: human.id,
+      beforeMessageId:
+        nextHumanIndex === -1 ? undefined : messages[nextHumanIndex]?.id,
+      includeBeforeMessage: false,
+      includeModes: ["citation"],
+    }).filter((source) => source.mode === "citation");
+    if (sources.length > 0) {
+      batches.push({
+        id: assistant.id,
+        assistant_message_id: assistant.id,
+        sources,
+      });
+    }
+  }
+  return batches;
+}
+
+function findNextHumanIndex(messages: Message[], start: number): number {
+  for (let index = start; index < messages.length; index++) {
+    if (messages[index]?.type === "human") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function findLastAssistantAnswer(
+  messages: Message[],
+  start: number,
+  end: number,
+): Message | null {
+  for (let index = end - 1; index >= start; index--) {
+    const message = messages[index];
+    if (
+      message?.type === "ai" &&
+      message.id &&
+      hasAssistantAnswerContent(message) &&
+      !hasAssistantToolCalls(message)
+    ) {
+      return message;
+    }
+  }
+  return null;
+}
+
+function hasAssistantAnswerContent(message: Message): boolean {
+  const content = message.content;
+  if (typeof content === "string") {
+    return content.trim().length > 0;
+  }
+  if (!Array.isArray(content)) {
+    return false;
+  }
+  return content.some((part) => {
+    if (!part || typeof part !== "object") {
+      return false;
+    }
+    const block = part as Record<string, unknown>;
+    return block.type === "text" && typeof block.text === "string" && block.text.trim().length > 0;
+  });
+}
+
+function hasAssistantToolCalls(message: Message): boolean {
+  const direct = (message as { tool_calls?: unknown }).tool_calls;
+  if (Array.isArray(direct) && direct.length > 0) {
+    return true;
+  }
+  const chunks = (message as { tool_call_chunks?: unknown }).tool_call_chunks;
+  if (Array.isArray(chunks) && chunks.length > 0) {
+    return true;
+  }
+  const kwargs = (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs;
+  const extra = kwargs?.tool_calls;
+  return Array.isArray(extra) && extra.length > 0;
+}
+
 export { ChatBox };
diff --git a/frontend-web/src/components/workspace/input-box.tsx b/frontend-web/src/components/workspace/input-box.tsx
index 6e1ce3b3..966268fd 100644
--- a/frontend-web/src/components/workspace/input-box.tsx
+++ b/frontend-web/src/components/workspace/input-box.tsx
@@ -87,7 +87,11 @@ import {
 } from "../ui/dropdown-menu";
 
 import { useRecommendedQuestions } from "@/core/recommended-questions/hooks";
-import { useLocalSettings } from "@/core/settings";
+import {
+  isThreadRagModeLocked,
+  lockThreadRagMode,
+  useLocalSettings,
+} from "@/core/settings";
 
 
 import { useThread } from "./messages/context";
@@ -300,10 +304,14 @@ export function InputBox({
     });
   }, [context, memoryInjectionEnabled, onContextChange]);
 
-  const ragModeEnabled = localSettings.display.ragModeEnabled;
-  const handleRagModeToggle = useCallback(() => {
-    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
-  }, [ragModeEnabled, setLocalSettings]);
+  const ragModeLocked = isThreadRagModeLocked(threadId);
+  const ragModeEnabled = localSettings.display.ragModeEnabled || ragModeLocked;
+  const handleRagModeToggle = useCallback(() => {
+    if (ragModeLocked) {
+      return;
+    }
+    setLocalSettings("display", { ragModeEnabled: !ragModeEnabled });
+  }, [ragModeEnabled, ragModeLocked, setLocalSettings]);
 
   const handleSubmit = useCallback(
     async (message: PromptInputMessage) => {
@@ -316,9 +324,12 @@ export function InputBox({
       }
       setFollowups([]);
       setFollowupsHidden(false);
-      setFollowupsLoading(false);
-
-      // Guard against submitting before the initial model auto-selection
+      setFollowupsLoading(false);
+      if (ragModeEnabled) {
+        lockThreadRagMode(threadId);
+      }
+
+      // Guard against submitting before the initial model auto-selection
       // effect has flushed thread settings to storage/state.
       if (resolvedModelName && context.model_name !== resolvedModelName) {
         onContextChange?.({
@@ -340,11 +351,13 @@ export function InputBox({
       onContextChange,
       onSubmit,
       onStop,
-      resolvedModelName,
-      selectedModel?.supports_thinking,
-      status,
-    ],
-  );
+      resolvedModelName,
+      ragModeEnabled,
+      selectedModel?.supports_thinking,
+      status,
+      threadId,
+    ],
+  );
 
   const requestFormSubmit = useCallback(() => {
     const form = promptRootRef.current?.querySelector("form");
@@ -638,11 +651,13 @@ export function InputBox({
               }
             >
               <PromptInputButton
-                type="button"
-                aria-pressed={ragModeEnabled}
-                className={cn(
-                  "gap-1.5! rounded-full px-3! shadow-none",
-                  ragModeEnabled
+                type="button"
+                aria-pressed={ragModeEnabled}
+                disabled={ragModeLocked || disabled}
+                className={cn(
+                  "gap-1.5! rounded-full px-3! shadow-none",
+                  ragModeLocked && "cursor-not-allowed opacity-80",
+                  ragModeEnabled
                     ? "border border-emerald-300 bg-emerald-50 text-emerald-700 hover:bg-emerald-100 dark:border-emerald-700 dark:bg-emerald-950/40 dark:text-emerald-200"
                     : "border-0 bg-transparent text-muted-foreground hover:bg-muted/70 hover:text-foreground dark:text-slate-400 dark:hover:bg-slate-700/70 dark:hover:text-slate-100",
                 )}
diff --git a/frontend-web/src/components/workspace/messages/markdown-content.tsx b/frontend-web/src/components/workspace/messages/markdown-content.tsx
index 1a67d6ec..dc0888c5 100644
--- a/frontend-web/src/components/workspace/messages/markdown-content.tsx
+++ b/frontend-web/src/components/workspace/messages/markdown-content.tsx
@@ -36,10 +36,13 @@ export function MarkdownContent({
 }: MarkdownContentProps) {
   const components = useMemo(() => {
     return {
-      a: (props: AnchorHTMLAttributes<HTMLAnchorElement>) => {
-        if (typeof props.children === "string") {
-          const match = /^citation:(.+)$/.exec(props.children);
-          if (match) {
+      a: (props: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        if (props.href?.startsWith("#reference-")) {
+          return <CitationLink {...props} />;
+        }
+        if (typeof props.children === "string") {
+          const match = /^citation:(.+)$/.exec(props.children);
+          if (match) {
             const [, text] = match;
             return <CitationLink {...props}>{text}</CitationLink>;
           }
diff --git a/frontend-web/src/components/workspace/messages/message-list-item.tsx b/frontend-web/src/components/workspace/messages/message-list-item.tsx
index f586f9de..23924482 100644
--- a/frontend-web/src/components/workspace/messages/message-list-item.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list-item.tsx
@@ -184,10 +184,13 @@ function MessageContent_({
       img: (props: ImgHTMLAttributes<HTMLImageElement>) => (
         <MessageImage {...props} threadId={threadId} maxWidth="90%" />
       ),
-      a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
-        if (typeof props.children === "string" && /^citation:/i.test(props.children)) {
-          return <CitationLink href={href} {...props} />;
-        }
+      a: ({ href, ...props }: AnchorHTMLAttributes<HTMLAnchorElement>) => {
+        if (href?.startsWith("#reference-")) {
+          return <CitationLink href={href} {...props} />;
+        }
+        if (typeof props.children === "string" && /^citation:/i.test(props.children)) {
+          return <CitationLink href={href} {...props} />;
+        }
         if (href?.startsWith("/mnt/")) {
           const url = resolveArtifact(href);
           return (
diff --git a/frontend-web/src/components/workspace/messages/message-list.tsx b/frontend-web/src/components/workspace/messages/message-list.tsx
index e659d72f..0523c307 100644
--- a/frontend-web/src/components/workspace/messages/message-list.tsx
+++ b/frontend-web/src/components/workspace/messages/message-list.tsx
@@ -21,7 +21,7 @@ import {
   hasToolCalls,
 } from "@/core/messages/utils";
 import { useRehypeSplitWordsIntoSpans } from "@/core/rehype";
-import { useLocalSettings } from "@/core/settings";
+import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
 import { useSkills } from "@/core/skills/hooks";
 import {
   buildSkillDisplayMap,
@@ -73,10 +73,12 @@ export function MessageList({
   const updateSubtask = useUpdateSubtask();
   const messages = thread.messages;
   const [settings] = useLocalSettings();
+  const ragModeEnabled =
+    settings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
   const { skills } = useSkills();
   const skillDisplayMap = useMemo(
-    () => (settings.display.ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
-    [settings.display.ragModeEnabled, skills],
+    () => (ragModeEnabled ? buildSkillDisplayMap(skills) : new Map()),
+    [ragModeEnabled, skills],
   );
 
   // Track which clarification messages are still awaiting an answer.
@@ -198,7 +200,7 @@ export function MessageList({
           if (group.type === "human" || group.type === "assistant") {
             return group.messages.map((msg) => {
               const displaySources =
-                settings.display.ragModeEnabled &&
+                ragModeEnabled &&
                 group.type === "assistant" &&
                 msg.type === "ai"
                   ? collectRuntimeDisplaySources(messages, skillDisplayMap, {
diff --git a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
index b1498420..5970d17e 100644
--- a/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
+++ b/frontend-web/src/components/workspace/settings/appearance-settings-page.tsx
@@ -21,10 +21,12 @@ import { getStoredAuth } from "@/core/auth";
 import { enUS, isLocale, zhCN, type Locale } from "@/core/i18n";
 import { useI18n } from "@/core/i18n/hooks";
 import { useLocalSettings } from "@/core/settings";
-import {
-  useAppearanceSettings,
-  useUpdateAppearanceSettings,
-} from "@/core/system-settings/hooks";
+import {
+  useAppearanceSettings,
+  useCitationDisplaySettings,
+  useUpdateAppearanceSettings,
+  useUpdateCitationDisplaySettings,
+} from "@/core/system-settings/hooks";
 import { cn } from "@/lib/utils";
 
 import { SettingsSection } from "./settings-section";
@@ -40,9 +42,13 @@ export function AppearanceSettingsPage() {
   const currentTheme = theme;
   const [settings, setSettings] = useLocalSettings();
   const isAdmin = getStoredAuth()?.system_role === "admin";
-  const { data: appearance } = useAppearanceSettings();
-  const updateAppearance = useUpdateAppearanceSettings();
-  const globalDefault = appearance?.default_theme ?? "light";
+  const { data: appearance } = useAppearanceSettings();
+  const updateAppearance = useUpdateAppearanceSettings();
+  const { data: citationDisplay } = useCitationDisplaySettings();
+  const updateCitationDisplay = useUpdateCitationDisplaySettings();
+  const globalDefault = appearance?.default_theme ?? "light";
+  const cleanupWords =
+    citationDisplay?.cleanup_words ?? settings.display.citationCleanupWords ?? [];
 
   const handleSetGlobalDefault = async (value: "light" | "dark") => {
     if (value === globalDefault) return;
@@ -211,16 +217,16 @@ export function AppearanceSettingsPage() {
                 管理员配置。每行一个词或短句，参考文献卡片和详情弹框会自动移除这些广告词、导航词或免责声明。
               </p>
             </div>
-            <Textarea
-              value={(settings.display.citationCleanupWords ?? []).join("\n")}
-              onChange={(event) =>
-                setSettings("display", {
-                  citationCleanupWords: event.currentTarget.value
-                    .split(/\r?\n/)
-                    .map((item) => item.trim())
-                    .filter(Boolean),
-                })
-              }
+            <Textarea
+              value={cleanupWords.join("\n")}
+              onChange={(event) => {
+                const words = event.currentTarget.value
+                    .split(/\r?\n/)
+                    .map((item) => item.trim())
+                    .filter(Boolean);
+                setSettings("display", { citationCleanupWords: words });
+                updateCitationDisplay.mutate({ cleanup_words: words });
+              }}
               placeholder={"广告\n点击下载APP\n打开客户端\n免责声明\n责任编辑"}
               className="min-h-32 text-sm"
             />
diff --git a/frontend-web/src/components/workspace/skill-display-sources.tsx b/frontend-web/src/components/workspace/skill-display-sources.tsx
index 7bbf609d..080be3c0 100644
--- a/frontend-web/src/components/workspace/skill-display-sources.tsx
+++ b/frontend-web/src/components/workspace/skill-display-sources.tsx
@@ -10,13 +10,16 @@ import {
 } from "@/components/ui/dialog";
 import type { RuntimeDisplaySource } from "@/core/skill-display/runtime";
 import { useLocalSettings } from "@/core/settings";
+import { useCitationDisplaySettings } from "@/core/system-settings/hooks";
 import { cn } from "@/lib/utils";
 import { useState } from "react";
 
 export function SkillDisplaySources({
+  highlightedReferenceId,
   sources,
   className,
 }: {
+  highlightedReferenceId?: string | null;
   sources: RuntimeDisplaySource[];
   className?: string;
 }) {
@@ -29,6 +32,7 @@ export function SkillDisplaySources({
       {sources.map((source) => (
         <SourceCard
           key={`${source.skillName}-${source.index}`}
+          highlighted={highlightedReferenceId === String(source.index)}
           source={source}
           referenceTarget
         />
@@ -38,15 +42,19 @@ export function SkillDisplaySources({
 }
 
 export function SourceCard({
+  highlighted = false,
   source,
   referenceTarget = false,
 }: {
+  highlighted?: boolean;
   source: RuntimeDisplaySource;
   referenceTarget?: boolean;
 }) {
   const [open, setOpen] = useState(false);
   const [settings] = useLocalSettings();
-  const cleanupWords = settings.display.citationCleanupWords ?? [];
+  const { data: citationDisplay } = useCitationDisplaySettings();
+  const cleanupWords =
+    citationDisplay?.cleanup_words ?? settings.display.citationCleanupWords ?? [];
   const content = cleanReferenceText(source.content || source.snippet, cleanupWords);
   const snippet = compactReferenceText(content).slice(0, 280);
   const paragraphs = segmentReferenceText(content);
@@ -72,6 +80,8 @@ export function SourceCard({
         className={cn(
           "group bg-card/60 hover:bg-card hover:border-primary/40 focus-visible:ring-primary/30 w-full scroll-mt-12 rounded-xl border px-3.5 py-3 text-left shadow-sm transition-all focus-visible:ring-2 focus-visible:outline-none",
           "target:bg-primary/5 target:border-primary/60",
+          highlighted &&
+            "animate-[reference-flash_1.4s_ease-out] border-amber-400 bg-amber-50 shadow-[0_0_0_3px_rgba(251,191,36,0.22)]",
         )}
         onClick={() => setOpen(true)}
       >
@@ -168,10 +178,13 @@ function cleanReferenceText(
   cleanupWords: string[],
 ): string {
   let text = raw ?? "";
-  for (const word of cleanupWords) {
-    const trimmed = word.trim();
-    if (!trimmed) continue;
-    text = text.split(trimmed).join("");
+  const words = cleanupWords.map((word) => word.trim()).filter(Boolean);
+  if (words.length > 0) {
+    text = text
+      .replace(/\r\n/g, "\n")
+      .split("\n")
+      .filter((line) => !words.some((word) => line.includes(word)))
+      .join("\n");
   }
   return text
     .replace(/\r\n/g, "\n")
diff --git a/frontend-web/src/core/messages/search-results.ts b/frontend-web/src/core/messages/search-results.ts
index 7871d423..3ff6408e 100644
--- a/frontend-web/src/core/messages/search-results.ts
+++ b/frontend-web/src/core/messages/search-results.ts
@@ -7,6 +7,10 @@
  */
 
 export type SearchResultItem = {
+  id?: string;
+  recUuid?: string;
+  uuid?: string;
+  docId?: string;
   title?: string;
   url?: string;
   snippet?: string;
@@ -300,6 +304,10 @@ function normalizeSearchResultItem(raw: unknown): SearchResultItem | null {
   const date =
     pickFromLayers(layers, DATE_ALIASES) ??
     pickByKeyPattern(layers, DATE_KEY_PATTERN, { maxLength: 64 });
+  const id = pickFromLayers(layers, ["id", "taskId", "recordId", "record_id"]);
+  const recUuid = pickFromLayers(layers, ["recUuid", "rec_uuid"]);
+  const uuid = pickFromLayers(layers, ["uuid"]);
+  const docId = pickFromLayers(layers, ["docId", "doc_id", "documentId"]);
 
   const reserved = new Set<string>();
   for (const value of [title, content, url, source, date]) {
@@ -324,6 +332,10 @@ function normalizeSearchResultItem(raw: unknown): SearchResultItem | null {
   }
 
   return {
+    id,
+    recUuid,
+    uuid,
+    docId,
     title,
     url,
     snippet: content,
diff --git a/frontend-web/src/core/settings/index.ts b/frontend-web/src/core/settings/index.ts
index 12e80835..dc15f8cd 100644
--- a/frontend-web/src/core/settings/index.ts
+++ b/frontend-web/src/core/settings/index.ts
@@ -1,2 +1,3 @@
-export { useLocalSettings, useThreadSettings } from "./hooks";
-export type { LocalSettings } from "./local";
+export { useLocalSettings, useThreadSettings } from "./hooks";
+export { isThreadRagModeLocked, lockThreadRagMode } from "./local";
+export type { LocalSettings } from "./local";
diff --git a/frontend-web/src/core/settings/local.ts b/frontend-web/src/core/settings/local.ts
index 0e9080fe..e000e035 100644
--- a/frontend-web/src/core/settings/local.ts
+++ b/frontend-web/src/core/settings/local.ts
@@ -17,8 +17,9 @@ export const DEFAULT_LOCAL_SETTINGS: LocalSettings = {
   },
 };
 
-export const LOCAL_SETTINGS_KEY = "deerflow.local-settings";
-export const THREAD_MODEL_KEY_PREFIX = "deerflow.thread-model.";
+export const LOCAL_SETTINGS_KEY = "deerflow.local-settings";
+export const THREAD_MODEL_KEY_PREFIX = "deerflow.thread-model.";
+export const THREAD_RAG_MODE_KEY_PREFIX = "deerflow.thread-rag-mode.";
 
 function isBrowser(): boolean {
   return typeof window !== "undefined";
@@ -90,10 +91,10 @@ export function getThreadModelName(threadId: string): string | undefined {
   return localStorage.getItem(getThreadModelStorageKey(threadId)) ?? undefined;
 }
 
-export function saveThreadModelName(
-  threadId: string,
-  modelName: string | undefined,
-) {
+export function saveThreadModelName(
+  threadId: string,
+  modelName: string | undefined,
+) {
   if (!isBrowser()) {
     return;
   }
@@ -102,8 +103,26 @@ export function saveThreadModelName(
     localStorage.removeItem(key);
     return;
   }
-  localStorage.setItem(key, modelName);
-}
+  localStorage.setItem(key, modelName);
+}
+
+function getThreadRagModeStorageKey(threadId: string): string {
+  return `${THREAD_RAG_MODE_KEY_PREFIX}${threadId}`;
+}
+
+export function isThreadRagModeLocked(threadId: string): boolean {
+  if (!isBrowser() || !threadId) {
+    return false;
+  }
+  return localStorage.getItem(getThreadRagModeStorageKey(threadId)) === "true";
+}
+
+export function lockThreadRagMode(threadId: string) {
+  if (!isBrowser() || !threadId) {
+    return;
+  }
+  localStorage.setItem(getThreadRagModeStorageKey(threadId), "true");
+}
 
 export function applyThreadModelOverride(
   settings: LocalSettings,
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
index 5d73b5f0..205f5f44 100644
--- a/frontend-web/src/core/skill-display/runtime.ts
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -168,6 +168,7 @@ export function collectRuntimeDisplaySources(
   const seenCitationKeys = new Map<string, RuntimeDisplaySource>();
   const seenDisplayKeys = new Set<string>();
   const consumedToolMessageIds = new Set<string>();
+  const consumedToolMessages = new Set<Message>();
 
   for (let index = start; index < limit; index++) {
     const message = messages[index];
@@ -180,14 +181,24 @@ export function collectRuntimeDisplaySources(
         displays,
         toolCall.args,
       );
-      const result = findToolResultPayload(toolCall, messages, index);
+      const toolMessage = findToolResultMessage(
+        toolCall,
+        messages,
+        index,
+        consumedToolMessageIds,
+        consumedToolMessages,
+      );
+      if (!toolMessage) {
+        continue;
+      }
+      const result = parseToolMessagePayload(toolMessage);
       if (result === undefined) {
         continue;
       }
-      const linkedToolMessage = findToolMessageById(toolCall.id, messages);
-      if (linkedToolMessage?.id) {
-        consumedToolMessageIds.add(linkedToolMessage.id);
+      if (toolMessage.id) {
+        consumedToolMessageIds.add(toolMessage.id);
       }
+      consumedToolMessages.add(toolMessage);
       if (isDisplaySamplePayload(result)) {
         continue;
       }
@@ -223,7 +234,12 @@ export function collectRuntimeDisplaySources(
 
   for (let index = start; index < limit; index++) {
     const message = messages[index];
-    if (!message || message.type !== "tool" || consumedToolMessageIds.has(message.id ?? "")) {
+    if (
+      !message ||
+      message.type !== "tool" ||
+      consumedToolMessages.has(message) ||
+      consumedToolMessageIds.has(message.id ?? "")
+    ) {
       continue;
     }
     const result = parseToolMessagePayload(message);
@@ -238,7 +254,8 @@ export function collectRuntimeDisplaySources(
     }
     const normalized = match
       ? normalizeDisplaySources(result, match.display)
-      : shouldUseDefaultCitationMode(toolName, result)
+      : shouldUseDefaultCitationMode(toolName, result) ||
+          normalizeDefaultDisplaySources(result).length > 0
         ? normalizeDefaultDisplaySources(result)
         : [];
     appendDisplaySources(
@@ -268,16 +285,14 @@ function appendDisplaySources(
 ) {
   for (const draft of drafts) {
     if (draft.mode === "citation") {
-      const key = citationSourceKey(draft);
-      const existing = seenCitationKeys.get(key);
-      if (existing) {
-        continue;
-      }
       const source = {
         ...draft,
         index: nextCitationIndex(),
       };
-      seenCitationKeys.set(key, source);
+      const key = citationSourceKey(draft);
+      if (key) {
+        seenCitationKeys.set(`${key}:${source.index}`, source);
+      }
       target.push(source);
       continue;
     }
@@ -331,12 +346,19 @@ function citationSourceKey(source: RuntimeDisplaySourceDraft): string {
     stringifyMaybe(raw.docId) ||
     stringifyMaybe(raw.id);
   if (id) {
-    return normalizeName(`${source.skillName}:${id}`);
+    return normalizeCitationKey(String(id));
   }
-  const fallback = [source.skillName, source.title, source.source, source.time]
+  const fallback = [
+    source.skillName,
+    source.title,
+    source.source,
+    source.time,
+    source.content,
+    source.snippet,
+  ]
     .filter(Boolean)
     .join("|");
-  return normalizeName(fallback) || JSON.stringify(raw).slice(0, 300);
+  return normalizeCitationKey(fallback) || normalizeCitationKey(JSON.stringify(raw).slice(0, 300));
 }
 
 function nonCitationSourceKey(source: RuntimeDisplaySourceDraft): string {
@@ -543,7 +565,12 @@ export function normalizeDefaultDisplaySources(payload: unknown): DisplaySourceI
       : undefined,
   );
   return normalized.map((item, index) => ({
-    id: item.url ?? String(index + 1),
+    id:
+      item.recUuid ??
+      item.uuid ??
+      item.docId ??
+      item.id ??
+      item.url,
     title: item.title ?? item.source ?? `结果 ${index + 1}`,
     type: "result",
     snippet: item.snippet ?? item.content ?? "",
@@ -620,18 +647,79 @@ function replaceCitationTokens(
   byIndex: Map<number, RuntimeDisplaySource>,
   orderedSources: RuntimeDisplaySource[],
 ): string {
-  return content
+  const normalized = normalizeLooseCitationTokens(content, byIndex, orderedSources);
+  const withDoubleBracketCitations = normalized
     .replace(/\[\[(\d+)\]\]/g, (match, rawIndex: string) =>
       citationMarkdown(match, Number(rawIndex), byIndex, orderedSources),
-    )
-    .replace(/(^|[^:\[!])\[(\d+)\](?!\()/g, (match, prefix: string, rawIndex: string) =>
-      `${prefix}${citationMarkdown(
-        match.slice(prefix.length),
-        Number(rawIndex),
-        byIndex,
-        orderedSources,
-      )}`,
     );
+  return replaceBracketCitationTokens(
+    withDoubleBracketCitations,
+    byIndex,
+    orderedSources,
+  );
+}
+
+function replaceBracketCitationTokens(
+  content: string,
+  byIndex: Map<number, RuntimeDisplaySource>,
+  orderedSources: RuntimeDisplaySource[],
+): string {
+  const tokenPattern = /\\?\[(\d{1,3})\\?\](?!\()/g;
+  let cursor = 0;
+  let next = "";
+  for (const match of content.matchAll(tokenPattern)) {
+    const start = match.index ?? 0;
+    const previous = start > 0 ? content[start - 1] : "";
+    if (previous === ":" || previous === "[" || previous === "!") {
+      continue;
+    }
+    next += content.slice(cursor, start);
+    next += citationMarkdown(match[0], Number(match[1]), byIndex, orderedSources);
+    cursor = start + match[0].length;
+  }
+  next += content.slice(cursor);
+  return next;
+}
+
+function normalizeLooseCitationTokens(
+  content: string,
+  byIndex: Map<number, RuntimeDisplaySource>,
+  orderedSources: RuntimeDisplaySource[],
+): string {
+  const isValidIndex = (index: number) =>
+    Number.isInteger(index) &&
+    index > 0 &&
+    (byIndex.has(index) || !!orderedSources[index - 1]);
+  const toCitationRun = (raw: string) => {
+    const parts = raw.match(/\\?\[\d{1,3}\\?\]|\d{1,3}/g) ?? [];
+    const indexes = parts.map((part) => Number(part.replace(/\D/g, "")));
+    if (indexes.length === 0 || indexes.some((index) => !isValidIndex(index))) {
+      return raw;
+    }
+    return indexes.map((index) => `[${index}]`).join("");
+  };
+
+  let next = content.replace(
+    /(^|[^\d\[\]\\])((?:\d{1,3}|\\?\[\d{1,3}\\?\])(?:\\?\[\d{1,3}\\?\]|\d{1,3})+)/g,
+    (match, prefix: string, rawRun: string) => {
+      if (!rawRun.includes("[")) {
+        return match;
+      }
+      return `${prefix}${toCitationRun(rawRun)}`;
+    },
+  );
+
+  next = next.replace(
+    /(^|[\s\uFF0C\u3002\uFF1B\uFF1A\u3001,!?！？)])(\d{1,3})(?=([\s\uFF0C\u3002\uFF1B\uFF1A\u3001,!?！？)]|$))/g,
+    (match, prefix: string, rawIndex: string) => {
+      const index = Number(rawIndex);
+      if (!isValidIndex(index)) {
+        return match;
+      }
+      return `${prefix}[${index}]`;
+    },
+  );
+  return next;
 }
 
 function normalizeExistingCitationLinks(
@@ -654,16 +742,16 @@ function normalizeExistingCitationLinks(
         const index = Number(numberMatch[1]);
         const source = byIndex.get(index) ?? orderedSources[index - 1];
         if (source) {
-          return `[citation:[${source.index}]](#reference-${source.index})`;
+          return citationLinkMarkdown(source);
         }
       }
       const sourceByUrl = byUrl.get(url);
       if (sourceByUrl) {
-        return `[citation:[${sourceByUrl.index}]](#reference-${sourceByUrl.index})`;
+        return citationLinkMarkdown(sourceByUrl);
       }
       const sourceByTitle = byTitle.get(label);
       if (sourceByTitle) {
-        return `[citation:[${sourceByTitle.index}]](#reference-${sourceByTitle.index})`;
+        return citationLinkMarkdown(sourceByTitle);
       }
       return match;
     },
@@ -680,11 +768,11 @@ function citationMarkdown(
   if (!source) {
     return fallback;
   }
-  return `[citation:[${source.index}]](#reference-${source.index})`;
+  return citationLinkMarkdown(source);
 }
 
 function hasCitationMarkdown(content: string): boolean {
-  return /\[citation:\[[^\]]+\]\]\(#reference-[^)]+\)/.test(content);
+  return /\[citation:(?:\[[^\]]+\]|\d+)\]\(#reference-[^)]+\)/.test(content);
 }
 
 function appendCitationSummary(
@@ -693,7 +781,7 @@ function appendCitationSummary(
 ): string {
   const citations = citationSources
     .slice(0, 5)
-    .map((source) => `[citation:[${source.index}]](#reference-${source.index})`)
+    .map((source) => citationLinkMarkdown(source))
     .join(" ");
   if (!citations) {
     return content;
@@ -702,10 +790,22 @@ function appendCitationSummary(
   return `${trimmed}${trimmed ? "\n\n" : ""}参考来源：${citations}`;
 }
 
+function citationLinkMarkdown(source: RuntimeDisplaySource): string {
+  return `[citation:${source.index}](#reference-${source.index})`;
+}
+
 function normalizeName(name: string): string {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "");
 }
 
+function normalizeCitationKey(value: string): string {
+  return value
+    .toLowerCase()
+    .normalize("NFKC")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -714,18 +814,28 @@ function stringifyMaybe(value: unknown): string | undefined {
   return typeof value === "string" && value.trim() ? value : undefined;
 }
 
-function findToolResultPayload(
+function findToolResultMessage(
   toolCall: RuntimeToolCall,
   messages: Message[],
   toolCallMessageIndex = -1,
-): unknown {
-  const toolMessage =
-    findToolMessageById(toolCall.id, messages) ??
-    findToolMessageByName(toolCall, messages, toolCallMessageIndex);
-  if (!toolMessage) {
-    return undefined;
+  consumedToolMessageIds?: Set<string>,
+  consumedToolMessages?: Set<Message>,
+): Message | undefined {
+  const byId = findToolMessageById(toolCall.id, messages);
+  if (
+    byId &&
+    !consumedToolMessages?.has(byId) &&
+    (!byId.id || !consumedToolMessageIds?.has(byId.id))
+  ) {
+    return byId;
   }
-  return parseToolMessagePayload(toolMessage);
+  return findToolMessageByName(
+    toolCall,
+    messages,
+    toolCallMessageIndex,
+    consumedToolMessageIds,
+    consumedToolMessages,
+  );
 }
 
 function parseToolMessagePayload(toolMessage: Message): unknown {
@@ -782,6 +892,8 @@ function findToolMessageByName(
   toolCall: RuntimeToolCall,
   messages: Message[],
   toolCallMessageIndex: number,
+  consumedToolMessageIds?: Set<string>,
+  consumedToolMessages?: Set<Message>,
 ): Message | undefined {
   const start = Math.max(toolCallMessageIndex + 1, 0);
   for (let index = start; index < messages.length; index++) {
@@ -795,6 +907,12 @@ function findToolMessageByName(
     if (message.type !== "tool") {
       continue;
     }
+    if (message.id && consumedToolMessageIds?.has(message.id)) {
+      continue;
+    }
+    if (consumedToolMessages?.has(message)) {
+      continue;
+    }
     const name =
       stringifyMaybe((message as { name?: unknown }).name) ??
       stringifyMaybe(
diff --git a/frontend-web/src/core/system-settings/api.ts b/frontend-web/src/core/system-settings/api.ts
index e6335706..265a2276 100644
--- a/frontend-web/src/core/system-settings/api.ts
+++ b/frontend-web/src/core/system-settings/api.ts
@@ -53,6 +53,14 @@ export interface PrivateSquareUpdate {
   password?: string;
 }
 
+export interface CitationDisplaySettings {
+  cleanup_words: string[];
+}
+
+export interface CitationDisplayUpdate {
+  cleanup_words?: string[];
+}
+
 export async function loadPrivateSquareStatus(): Promise<PrivateSquareStatus> {
   const response = await apiFetch(
     `${getBackendBaseURL()}/api/system-settings/private-square`,
@@ -107,6 +115,38 @@ export async function updateAppearanceSettings(
   return (await response.json()) as AppearanceSettings;
 }
 
+export async function loadCitationDisplaySettings(): Promise<CitationDisplaySettings> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/citation-display`,
+  );
+  if (!response.ok) {
+    throw new Error(
+      `Failed to load citation display settings: ${response.status}`,
+    );
+  }
+  return (await response.json()) as CitationDisplaySettings;
+}
+
+export async function updateCitationDisplaySettings(
+  body: CitationDisplayUpdate,
+): Promise<CitationDisplaySettings> {
+  const response = await apiFetch(
+    `${getBackendBaseURL()}/api/system-settings/citation-display`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!response.ok) {
+    const detail = await response
+      .json()
+      .catch(() => ({ detail: "Failed to update citation display" }));
+    throw new Error(detail.detail ?? "Failed to update citation display");
+  }
+  return (await response.json()) as CitationDisplaySettings;
+}
+
 export async function updatePrivateSquareSettings(
   body: PrivateSquareUpdate,
 ): Promise<PrivateSquareStatus> {
diff --git a/frontend-web/src/core/system-settings/hooks.ts b/frontend-web/src/core/system-settings/hooks.ts
index 903737a5..85cf0b41 100644
--- a/frontend-web/src/core/system-settings/hooks.ts
+++ b/frontend-web/src/core/system-settings/hooks.ts
@@ -2,12 +2,15 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 
 import {
   loadAppearanceSettings,
+  loadCitationDisplaySettings,
   loadPrivateSquareStatus,
   loadPromptPrefixSettings,
   updateAppearanceSettings,
+  updateCitationDisplaySettings,
   updatePrivateSquareSettings,
   updatePromptPrefixSettings,
   type AppearanceUpdate,
+  type CitationDisplayUpdate,
   type PrivateSquareUpdate,
   type PromptPrefixUpdate,
 } from "./api";
@@ -15,6 +18,7 @@ import {
 const PROMPT_PREFIX_KEY = ["systemSettings", "promptPrefix"] as const;
 const PRIVATE_SQUARE_KEY = ["systemSettings", "privateSquare"] as const;
 const APPEARANCE_KEY = ["systemSettings", "appearance"] as const;
+const CITATION_DISPLAY_KEY = ["systemSettings", "citationDisplay"] as const;
 
 export function usePromptPrefixSettings() {
   return useQuery({
@@ -77,3 +81,24 @@ export function useUpdateAppearanceSettings() {
     },
   });
 }
+
+export function useCitationDisplaySettings() {
+  return useQuery({
+    queryKey: CITATION_DISPLAY_KEY,
+    queryFn: () => loadCitationDisplaySettings(),
+    staleTime: 60_000,
+    refetchOnWindowFocus: false,
+    retry: false,
+  });
+}
+
+export function useUpdateCitationDisplaySettings() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: (body: CitationDisplayUpdate) =>
+      updateCitationDisplaySettings(body),
+    onSuccess: (data) => {
+      queryClient.setQueryData(CITATION_DISPLAY_KEY, data);
+    },
+  });
+}
diff --git a/frontend-web/src/core/threads/hooks.ts b/frontend-web/src/core/threads/hooks.ts
index 55331139..e1687970 100644
--- a/frontend-web/src/core/threads/hooks.ts
+++ b/frontend-web/src/core/threads/hooks.ts
@@ -3,17 +3,19 @@ import type { ThreadsClient } from "@langchain/langgraph-sdk/client";
 import { useStream } from "@langchain/langgraph-sdk/react";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { useNavigate } from "react-router-dom";
 import { toast } from "sonner";
 
 import type { PromptInputMessage } from "@/components/ai-elements/prompt-input";
 
 import { getAPIClient } from "../api";
 import { apiFetch } from "../api";
+import { getStoredAuth } from "../auth";
 import { getBackendBaseURL } from "../config";
 import { useI18n } from "../i18n/hooks";
 import type { FileInMessage } from "../messages/utils";
-import type { LocalSettings } from "../settings";
-import { useLocalSettings } from "../settings";
+import type { LocalSettings } from "../settings";
+import { isThreadRagModeLocked, lockThreadRagMode, useLocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
 import type { UploadedFileInfo } from "../uploads";
 import { promptInputFilePartToFile, uploadFiles } from "../uploads";
@@ -137,6 +139,42 @@ function getStreamErrorMessage(error: unknown): string {
   return "Request failed.";
 }
 
+/**
+ * Detect "thread not found" / forbidden errors from the LangGraph SDK.
+ *
+ * Backend returns 404 both when a thread truly doesn't exist and when the
+ * currently authenticated user doesn't own it — the SDK surfaces both as
+ * ``HTTP 404: {"detail":"Thread <uuid> not found"}``. The most common cause
+ * we see in practice is a stale tab whose URL still points at the previous
+ * login session's thread. Raw-toasting the 404 just confuses the user, so
+ * we re-frame it around the current login identity.
+ */
+function isThreadNotAccessibleError(message: string): boolean {
+  const lowered = message.toLowerCase();
+  if (/thread\s+[\w-]{8,}\s+not\s+found/i.test(message)) {
+    return true;
+  }
+  // Fallback: a bare 404/403 from the threads endpoint when the SDK has
+  // wrapped the detail differently.
+  return (
+    (lowered.includes("http 404") || lowered.includes("http 403")) &&
+    lowered.includes("thread")
+  );
+}
+
+function buildCurrentUserLabel(): string {
+  const auth = getStoredAuth();
+  if (!auth) {
+    return "未登录";
+  }
+  const email = auth.email?.trim();
+  if (email) {
+    return email;
+  }
+  const userId = auth.user_id?.trim();
+  return userId ? userId : "未知用户";
+}
+
 export function useThreadStream({
   threadId,
   context,
@@ -195,6 +233,7 @@ export function useThreadStream({
 
   const queryClient = useQueryClient();
   const updateSubtask = useUpdateSubtask();
+  const navigate = useNavigate();
   const runMetadataStorageRef = useRef<
     ReturnType<typeof getRunMetadataStorage> | undefined
   >(undefined);
@@ -294,7 +333,29 @@ export function useThreadStream({
     },
     onError(error) {
       setOptimisticMessages([]);
-      toast.error(getStreamErrorMessage(error));
+      const message = getStreamErrorMessage(error);
+      // A "thread not found" 404 almost always means the URL points at a
+      // thread from a previous login session — either this tab outlived a
+      // logout/re-login or the thread genuinely belongs to a different user.
+      // Re-frame the error around the *current* logged-in identity and bounce
+      // the user to a fresh chat instead of leaving them stuck on the stale
+      // route looking at a raw HTTP 404.
+      if (isThreadNotAccessibleError(message)) {
+        const userLabel = buildCurrentUserLabel();
+        toast.info(
+          `当前登录用户为 ${userLabel}，原对话不存在或无权访问，已为你打开新对话。`,
+        );
+        // Prefer staying inside an agent chat context when the user is on an
+        // agent thread URL — otherwise fall back to the global new chat.
+        const hash = typeof window !== "undefined" ? window.location.hash : "";
+        const agentMatch = hash.match(/#\/page\/workspace\/agents\/([^/]+)\//);
+        const target = agentMatch
+          ? `/page/workspace/agents/${agentMatch[1]}/chats/new`
+          : "/page/workspace/chats/new";
+        navigate(target, { replace: true });
+        return;
+      }
+      toast.error(message);
     },
     onFinish(state) {
       listeners.current.onFinish?.(state.values);
@@ -494,7 +555,13 @@ export function useThreadStream({
           }),
         );
 
-        await thread.submit(
+        const ragModeEnabled =
+          localSettings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+        if (ragModeEnabled) {
+          lockThreadRagMode(threadId);
+        }
+
+        await thread.submit(
           {
             messages: [
               {
@@ -537,10 +604,10 @@ export function useThreadStream({
                       ? "low"
                       : undefined),
               memory_injection_enabled: context.memory_injection_enabled ?? true,
-              rag_mode_enabled: localSettings.display.ragModeEnabled,
-              thread_id: threadId,
-            },
-          },
+              rag_mode_enabled: ragModeEnabled,
+              thread_id: threadId,
+            },
+          },
         );
         void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
       } catch (error) {
diff --git a/frontend-web/src/styles/globals.css b/frontend-web/src/styles/globals.css
index 3e08cac3..b91dcf12 100644
--- a/frontend-web/src/styles/globals.css
+++ b/frontend-web/src/styles/globals.css
@@ -567,6 +567,20 @@
       transform: translateY(-50%) scale(1);
     }
   }
+
+  @keyframes reference-flash {
+    0% {
+      background: rgba(254, 243, 199, 0.95);
+      box-shadow: 0 0 0 4px rgba(251, 191, 36, 0.28);
+    }
+    70% {
+      background: rgba(254, 243, 199, 0.58);
+      box-shadow: 0 0 0 2px rgba(251, 191, 36, 0.14);
+    }
+    100% {
+      box-shadow: none;
+    }
+  }
 }
 
 /* ─── Tiptap writing editor ─────────────────────────────────────────────── */
@@ -818,4 +832,4 @@
 * {
   border-color: var(--border);
   outline-color: var(--ring);
-}
\ No newline at end of file
+}
diff --git a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
index aadb877e..b2d8f90c 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/system_settings.py
@@ -49,6 +49,14 @@ class PrivateSquareUpdateRequest(BaseModel):
     password: str | None = Field(default=None, description="New password in plain text. Pass an empty string to clear.")
 
 
+class CitationDisplayResponse(BaseModel):
+    cleanup_words: list[str] = Field(default_factory=list, description="Global citation cleanup words")
+
+
+class CitationDisplayUpdateRequest(BaseModel):
+    cleanup_words: list[str] | None = None
+
+
 def _to_response(settings: PromptPrefixSettings) -> PromptPrefixResponse:
     return PromptPrefixResponse(
         enabled=settings.enabled,
@@ -83,6 +91,34 @@ async def update_prompt_prefix(body: PromptPrefixUpdateRequest, request: Request
     return _to_response(saved.prompt_prefix)
 
 
+@router.get("/citation-display", response_model=CitationDisplayResponse)
+async def get_citation_display() -> CitationDisplayResponse:
+    """Return global citation display cleanup settings."""
+    settings = load_system_settings().citation_display
+    return CitationDisplayResponse(cleanup_words=settings.cleanup_words)
+
+
+@router.put("/citation-display", response_model=CitationDisplayResponse)
+async def update_citation_display(
+    body: CitationDisplayUpdateRequest,
+    request: Request,
+) -> CitationDisplayResponse:
+    """Update global citation display cleanup settings. Admin only."""
+    await _require_admin(request)
+
+    current = load_system_settings()
+    words = [
+        str(item).strip()
+        for item in (body.cleanup_words or [])
+        if str(item).strip()
+    ]
+    updated = current.citation_display.model_copy(update={"cleanup_words": words})
+    saved = save_system_settings(
+        current.model_copy(update={"citation_display": updated})
+    )
+    return CitationDisplayResponse(cleanup_words=saved.citation_display.cleanup_words)
+
+
 @router.get("/private-square", response_model=PrivateSquareStatusResponse)
 async def get_private_square_status() -> PrivateSquareStatusResponse:
     """Return whether the private square is enabled and a password is set."""
diff --git a/offline-backend-20260512/backend/app/gateway/routers/threads.py b/offline-backend-20260512/backend/app/gateway/routers/threads.py
index 48bf8953..8d3a0e90 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/threads.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/threads.py
@@ -12,9 +12,12 @@ matching the LangGraph Platform wire format expected by the
 
 from __future__ import annotations
 
-import logging
-import uuid
-from typing import Any
+import logging
+import json
+import os
+from pathlib import Path
+import uuid
+from typing import Any
 
 from fastapi import APIRouter, HTTPException, Request
 from langgraph.checkpoint.base import empty_checkpoint
@@ -23,13 +26,18 @@ from pydantic import BaseModel, Field, field_validator
 from app.gateway.authz import require_permission
 from app.gateway.deps import get_checkpointer
 from app.gateway.utils import sanitize_log_param
-from deerflow.config.paths import Paths, get_paths
-from deerflow.runtime import serialize_channel_values
-from deerflow.runtime.user_context import get_effective_user_id
-from deerflow.utils.time import coerce_iso, now_iso
+from deerflow.config.paths import Paths, get_paths
+from deerflow.runtime import serialize_channel_values
+from deerflow.runtime.references import (
+    build_reference_batches as build_runtime_reference_batches,
+    build_reference_debug_summary,
+)
+from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.utils.time import coerce_iso, now_iso
 
-logger = logging.getLogger(__name__)
-router = APIRouter(prefix="/api/threads", tags=["threads"])
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api/threads", tags=["threads"])
+_RAG_DEBUG_LOGGER_NAME = "rag_citation_debug"
 
 
 # Metadata keys that the server controls; clients are not allowed to set
@@ -41,11 +49,38 @@ router = APIRouter(prefix="/api/threads", tags=["threads"])
 _SERVER_RESERVED_METADATA_KEYS: frozenset[str] = frozenset({"owner_id", "user_id"})
 
 
-def _strip_reserved_metadata(metadata: dict[str, Any] | None) -> dict[str, Any]:
-    """Return ``metadata`` with server-controlled keys removed."""
-    if not metadata:
-        return metadata or {}
-    return {k: v for k, v in metadata.items() if k not in _SERVER_RESERVED_METADATA_KEYS}
+def _strip_reserved_metadata(metadata: dict[str, Any] | None) -> dict[str, Any]:
+    """Return ``metadata`` with server-controlled keys removed."""
+    if not metadata:
+        return metadata or {}
+    return {k: v for k, v in metadata.items() if k not in _SERVER_RESERVED_METADATA_KEYS}
+
+
+def _get_rag_debug_logger() -> logging.Logger:
+    debug_logger = logging.getLogger(_RAG_DEBUG_LOGGER_NAME)
+    if getattr(debug_logger, "_rag_file_configured", False):
+        return debug_logger
+    log_path = Path(os.environ.get("RAG_CITATION_DEBUG_LOG", "logs/rag_citation_debug.log"))
+    if not log_path.is_absolute():
+        log_path = Path.cwd() / log_path
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    handler = logging.FileHandler(log_path, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    debug_logger.addHandler(handler)
+    debug_logger.setLevel(logging.INFO)
+    debug_logger.propagate = False
+    setattr(debug_logger, "_rag_file_configured", True)
+    setattr(debug_logger, "_rag_file_path", str(log_path))
+    return debug_logger
+
+
+def _rag_debug_file_path() -> str:
+    return str(getattr(_get_rag_debug_logger(), "_rag_file_path", "logs/rag_citation_debug.log"))
+
+
+def _log_rag_debug(message: str, *args: Any) -> None:
+    logger.info(message, *args)
+    _get_rag_debug_logger().info(message, *args)
 
 
 # ---------------------------------------------------------------------------
@@ -132,11 +167,43 @@ class HistoryEntry(BaseModel):
     next: list[str] = Field(default_factory=list)
 
 
-class ThreadHistoryRequest(BaseModel):
+class ThreadHistoryRequest(BaseModel):
     """Request body for checkpoint history."""
 
     limit: int = Field(default=10, ge=1, le=100, description="Maximum entries")
-    before: str | None = Field(default=None, description="Cursor for pagination")
+    before: str | None = Field(default=None, description="Cursor for pagination")
+
+
+class ReferenceSourceResponse(BaseModel):
+    index: int
+    id: str | None = None
+    skillName: str = "backend-reference"
+    mode: str = "citation"
+    title: str
+    type: str = "result"
+    snippet: str = ""
+    source: str | None = None
+    time: str | None = None
+    url: str | None = None
+    content: str | None = None
+    score: float | None = None
+    raw: dict[str, Any] = Field(default_factory=dict)
+
+
+class ReferenceBatchResponse(BaseModel):
+    id: str
+    assistant_message_id: str
+    sources: list[ReferenceSourceResponse] = Field(default_factory=list)
+
+
+class ReferenceBatchesResponse(BaseModel):
+    batches: list[ReferenceBatchResponse] = Field(default_factory=list)
+
+
+class ReferenceDebugLogRequest(BaseModel):
+    event: str
+    thread_id: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
 
 
 # ---------------------------------------------------------------------------
@@ -163,7 +230,7 @@ def _delete_thread_data(thread_id: str, paths: Paths | None = None, *, user_id:
     return ThreadDeleteResponse(success=True, message=f"Deleted local thread data for {thread_id}")
 
 
-def _derive_thread_status(checkpoint_tuple) -> str:
+def _derive_thread_status(checkpoint_tuple) -> str:
     """Derive thread status from checkpoint metadata."""
     if checkpoint_tuple is None:
         return "idle"
@@ -179,7 +246,251 @@ def _derive_thread_status(checkpoint_tuple) -> str:
     if tasks:
         return "interrupted"
 
-    return "idle"
+    return "idle"
+
+
+def _message_type(message: Any) -> str:
+    if isinstance(message, dict):
+        return str(message.get("type") or message.get("role") or "")
+    return str(getattr(message, "type", "") or "")
+
+
+def _message_id(message: Any) -> str | None:
+    if isinstance(message, dict):
+        value = message.get("id")
+    else:
+        value = getattr(message, "id", None)
+    return str(value) if value else None
+
+
+def _message_content(message: Any) -> Any:
+    if isinstance(message, dict):
+        return message.get("content")
+    return getattr(message, "content", None)
+
+
+def _message_name(message: Any) -> str:
+    if isinstance(message, dict):
+        return str(message.get("name") or (message.get("additional_kwargs") or {}).get("name") or "tool")
+    return str(getattr(message, "name", None) or "tool")
+
+
+def _has_tool_calls(message: Any) -> bool:
+    if isinstance(message, dict):
+        direct = message.get("tool_calls")
+        chunks = message.get("tool_call_chunks")
+        extra = (message.get("additional_kwargs") or {}).get("tool_calls")
+    else:
+        direct = getattr(message, "tool_calls", None)
+        chunks = getattr(message, "tool_call_chunks", None)
+        extra = (getattr(message, "additional_kwargs", None) or {}).get("tool_calls")
+    return bool(direct or chunks or extra)
+
+
+def _has_answer_content(message: Any) -> bool:
+    content = _message_content(message)
+    if isinstance(content, str):
+        return bool(content.strip())
+    if isinstance(content, list):
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text" and str(part.get("text") or "").strip():
+                return True
+    return False
+
+
+def _extract_tool_payload(message: Any) -> Any:
+    content = _message_content(message)
+    if isinstance(content, dict):
+        return _unwrap_tool_payload(content)
+    if isinstance(content, list):
+        texts: list[str] = []
+        for part in content:
+            if not isinstance(part, dict):
+                continue
+            if isinstance(part.get("json"), dict):
+                return _unwrap_tool_payload(part["json"])
+            if part.get("type") == "json" and isinstance(part.get("json"), dict):
+                return _unwrap_tool_payload(part["json"])
+            if part.get("type") == "text" and isinstance(part.get("text"), str):
+                texts.append(part["text"])
+            unwrapped = _unwrap_tool_payload(part)
+            if unwrapped is not None:
+                return unwrapped
+        content = "\n".join(texts)
+    if isinstance(content, str):
+        return _parse_json_like(content)
+    return None
+
+
+def _unwrap_tool_payload(value: dict[str, Any]) -> Any:
+    if any(isinstance(value.get(key), list) for key in ("results", "data", "items", "hits", "documents", "records", "sources")):
+        return value
+    for key in ("result", "output", "stdout", "content", "text", "payload", "response"):
+        nested = value.get(key)
+        if isinstance(nested, str):
+            parsed = _parse_json_like(nested)
+            if parsed is not None:
+                return parsed
+        if isinstance(nested, dict):
+            unwrapped = _unwrap_tool_payload(nested)
+            if unwrapped is not None:
+                return unwrapped
+    return value
+
+
+def _parse_json_like(text: str) -> Any:
+    trimmed = text.strip()
+    if not trimmed:
+        return None
+    try:
+        return json.loads(trimmed)
+    except Exception:
+        pass
+    first_obj = trimmed.find("{")
+    last_obj = trimmed.rfind("}")
+    if 0 <= first_obj < last_obj:
+        try:
+            return json.loads(trimmed[first_obj : last_obj + 1])
+        except Exception:
+            return None
+    return None
+
+
+def _first_list(payload: Any) -> list[Any]:
+    if isinstance(payload, list):
+        return payload
+    if not isinstance(payload, dict):
+        return []
+    for key in ("results", "data", "items", "hits", "documents", "records", "entries", "matches", "chunks", "sources"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return value
+    for key in ("result", "payload", "response", "output", "data"):
+        nested = payload.get(key)
+        found = _first_list(nested)
+        if found:
+            return found
+    return []
+
+
+def _nested_records(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, dict):
+        return []
+    layers = [raw]
+    for key in ("metadata", "meta", "attrs", "attributes", "properties", "extra"):
+        nested = raw.get(key)
+        if isinstance(nested, dict):
+            layers.append(nested)
+    return layers
+
+
+def _pick(layers: list[dict[str, Any]], keys: tuple[str, ...]) -> str | None:
+    for layer in layers:
+        for key in keys:
+            value = layer.get(key)
+            if isinstance(value, (str, int, float)) and str(value).strip():
+                return str(value).strip()
+    return None
+
+
+def _normalize_reference_item(raw: Any, fallback_index: int) -> dict[str, Any] | None:
+    if not isinstance(raw, dict):
+        return None
+    layers = _nested_records(raw)
+    title = _pick(layers, ("title", "m_title", "name", "question", "keyword", "query", "text"))
+    content = _pick(layers, ("content", "page_content", "summary", "snippet", "description", "content_preview", "abstract", "body"))
+    url = _pick(layers, ("url", "link", "href", "source_url", "web_url"))
+    source = _pick(layers, ("source", "source1", "site", "provider", "from"))
+    time = _pick(layers, ("time", "date", "published_date", "publishedDate", "m_publish", "publish_time", "created_at"))
+    item_id = _pick(layers, ("recUuid", "rec_uuid", "uuid", "docId", "doc_id", "id", "recordId", "taskId"))
+    score_raw = _pick(layers, ("score", "relevance", "similarity"))
+    score = None
+    if score_raw is not None:
+        try:
+            score = float(score_raw)
+        except Exception:
+            score = None
+    if not title:
+        title = source or f"结果 {fallback_index}"
+    if not content:
+        content = ""
+    if not title and not content and not url:
+        return None
+    return {
+        "id": item_id or url,
+        "title": title,
+        "type": "result",
+        "snippet": content,
+        "content": content,
+        "source": source,
+        "time": time,
+        "url": url,
+        "score": score,
+        "raw": raw,
+    }
+
+
+def _reference_key(source: dict[str, Any]) -> str:
+    raw = source.get("raw") if isinstance(source.get("raw"), dict) else {}
+    item_id = (
+        source.get("id")
+        or source.get("url")
+        or raw.get("recUuid")
+        or raw.get("uuid")
+        or raw.get("docId")
+        or raw.get("id")
+    )
+    if item_id:
+        return str(item_id).casefold().strip()
+    return "|".join(
+        str(source.get(key) or "").casefold().strip()
+        for key in ("title", "source", "time", "content", "snippet")
+    )
+
+
+def _build_reference_batches(messages: list[Any]) -> list[ReferenceBatchResponse]:
+    batches: list[ReferenceBatchResponse] = []
+    for index, message in enumerate(messages):
+        if _message_type(message) != "human":
+            continue
+        end = len(messages)
+        for cursor in range(index + 1, len(messages)):
+            if _message_type(messages[cursor]) == "human":
+                end = cursor
+                break
+        assistant_message: Any | None = None
+        for cursor in range(end - 1, index, -1):
+            candidate = messages[cursor]
+            if (
+                _message_type(candidate) == "ai"
+                and _message_id(candidate)
+                and _has_answer_content(candidate)
+                and not _has_tool_calls(candidate)
+            ):
+                assistant_message = candidate
+                break
+        if assistant_message is None:
+            continue
+        seen: set[str] = set()
+        sources: list[ReferenceSourceResponse] = []
+        for tool_message in messages[index + 1 : end]:
+            if _message_type(tool_message) != "tool":
+                continue
+            payload = _extract_tool_payload(tool_message)
+            for raw_item in _first_list(payload):
+                normalized = _normalize_reference_item(raw_item, len(sources) + 1)
+                if not normalized:
+                    continue
+                key = _reference_key(normalized)
+                if key and key in seen:
+                    continue
+                if key:
+                    seen.add(key)
+                sources.append(ReferenceSourceResponse(index=len(sources) + 1, **normalized))
+        if sources:
+            mid = _message_id(assistant_message) or str(index)
+            batches.append(ReferenceBatchResponse(id=mid, assistant_message_id=mid, sources=sources))
+    return batches
 
 
 # ---------------------------------------------------------------------------
@@ -406,9 +717,9 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
 
 
 # ---------------------------------------------------------------------------
-@router.get("/{thread_id}/state", response_model=ThreadStateResponse)
-@require_permission("threads", "read", owner_check=True)
-async def get_thread_state(thread_id: str, request: Request) -> ThreadStateResponse:
+@router.get("/{thread_id}/state", response_model=ThreadStateResponse)
+@require_permission("threads", "read", owner_check=True)
+async def get_thread_state(thread_id: str, request: Request) -> ThreadStateResponse:
     """Get the latest state snapshot for a thread.
 
     Channel values are serialized to ensure LangChain message objects
@@ -455,12 +766,84 @@ async def get_thread_state(thread_id: str, request: Request) -> ThreadStateRespo
         parent_checkpoint_id=parent_checkpoint_id,
         created_at=coerce_iso(metadata.get("created_at", "")),
         tasks=tasks,
-    )
-
-
-@router.post("/{thread_id}/state", response_model=ThreadStateResponse)
-@require_permission("threads", "write", owner_check=True, require_existing=True)
-async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, request: Request) -> ThreadStateResponse:
+    )
+
+
+@router.get("/{thread_id}/reference-batches", response_model=ReferenceBatchesResponse)
+@require_permission("threads", "read", owner_check=True)
+async def get_thread_reference_batches(thread_id: str, request: Request) -> ReferenceBatchesResponse:
+    """Return backend-built citation batches for completed assistant turns."""
+    checkpointer = get_checkpointer(request)
+    config = {"configurable": {"thread_id": thread_id, "checkpoint_ns": ""}}
+    try:
+        checkpoint_tuple = await checkpointer.aget_tuple(config)
+    except Exception:
+        logger.exception("Failed to get reference batches for thread %s", sanitize_log_param(thread_id))
+        raise HTTPException(status_code=500, detail="Failed to get reference batches")
+
+    if checkpoint_tuple is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {}
+    values = serialize_channel_values(checkpoint.get("channel_values", {}) or {})
+    messages = values.get("messages")
+    if not isinstance(messages, list):
+        _log_rag_debug(
+            "backend reference-batches thread=%s messages=missing batches=0 log_file=%s",
+            sanitize_log_param(thread_id),
+            _rag_debug_file_path(),
+        )
+        return ReferenceBatchesResponse(batches=[])
+    raw_batches = build_runtime_reference_batches(messages)
+    debug_summary = build_reference_debug_summary(messages, raw_batches)
+    _log_rag_debug(
+        "backend reference-batches thread=%s messages=%s turns=%s tool_messages=%s raw_items=%s "
+        "normalized_items=%s kept_items=%s batches=%s batch_sources=%s batch_ids=%s turns_detail=%s log_file=%s",
+        sanitize_log_param(thread_id),
+        debug_summary["messages"],
+        debug_summary["turns"],
+        debug_summary["tool_messages"],
+        debug_summary["raw_items"],
+        debug_summary["normalized_items"],
+        debug_summary["kept_items"],
+        len(raw_batches),
+        ",".join(str(batch.get("source_count", 0)) for batch in debug_summary["batches"]),
+        ",".join(str(batch.get("id") or "") for batch in debug_summary["batches"]),
+        json.dumps(debug_summary["turns_detail"], ensure_ascii=False),
+        _rag_debug_file_path(),
+    )
+    return ReferenceBatchesResponse(
+        batches=[
+            ReferenceBatchResponse(
+                id=str(batch.get("id") or ""),
+                assistant_message_id=str(batch.get("assistant_message_id") or batch.get("id") or ""),
+                sources=[
+                    ReferenceSourceResponse(**source)
+                    for source in batch.get("sources", [])
+                    if isinstance(source, dict)
+                ],
+            )
+            for batch in raw_batches
+        ]
+    )
+
+
+@router.post("/reference-debug-log")
+async def write_reference_debug_log(body: ReferenceDebugLogRequest) -> dict[str, str | bool]:
+    """Append frontend citation diagnostics to the backend RAG debug log."""
+    _get_rag_debug_logger().info(
+        "frontend %s thread=%s payload=%s log_file=%s",
+        body.event,
+        sanitize_log_param(body.thread_id or ""),
+        json.dumps(body.payload, ensure_ascii=False, default=str),
+        _rag_debug_file_path(),
+    )
+    return {"ok": True, "log_file": _rag_debug_file_path()}
+
+
+@router.post("/{thread_id}/state", response_model=ThreadStateResponse)
+@require_permission("threads", "write", owner_check=True, require_existing=True)
+async def update_thread_state(thread_id: str, body: ThreadStateUpdateRequest, request: Request) -> ThreadStateResponse:
     """Update thread state (e.g. for human-in-the-loop resume or title rename).
 
     Writes a new checkpoint that merges *body.values* into the latest
diff --git a/offline-backend-20260512/backend/app/gateway/services.py b/offline-backend-20260512/backend/app/gateway/services.py
index e29a3c93..46965a2c 100644
--- a/offline-backend-20260512/backend/app/gateway/services.py
+++ b/offline-backend-20260512/backend/app/gateway/services.py
@@ -100,7 +100,14 @@ _DEFAULT_ASSISTANT_ID = "lead_agent"
 
 # Built-in LangGraph graph IDs registered in langgraph.json.
 # These are NOT stored in the agents DB and must bypass the custom-agent access check.
-_BUILTIN_GRAPH_IDS: frozenset[str] = frozenset({"lead_agent", "canvas_agent", "ai_writing"})
+_BUILTIN_GRAPH_IDS: frozenset[str] = frozenset({"lead_agent", "canvas_agent", "ai_writing"})
+
+_RAG_CITATION_PROMPT = """当前对话已开启参考文献模式。
+如果本轮调用了搜索、知识库、检索类技能或工具，请基于本轮所有检索结果整体回答。
+你必须把同一轮内多次检索得到的资料视为同一批参考文献，按出现顺序从 [1] 开始连续编号，不要让每个检索词各自从 [1] 重新编号。
+回答正文中的关键结论必须标注对应编号，例如 [1]、[2]，多个来源可写为 [1][3][5]。
+不要引用不存在的编号，不要使用技能内部自带的编号，不要把参考文献完整列表堆在正文末尾。
+如果没有任何可用检索结果，请直接说明未检索到可靠参考资料。"""
 
 
 def _prepend_prompt_prefix(graph_input: dict[str, Any], prefix: str) -> dict[str, Any]:
@@ -129,7 +136,7 @@ def _prepend_prompt_prefix(graph_input: dict[str, Any], prefix: str) -> dict[str
     return {**graph_input, "messages": new_messages}
 
 
-def _prompt_prefix_opted_in(body: Any) -> bool:
+def _prompt_prefix_opted_in(body: Any) -> bool:
     """Detect whether the caller asked for the prompt prefix to be applied."""
     context = getattr(body, "context", None)
     if isinstance(context, Mapping) and context.get("prompt_prefix_enabled"):
@@ -137,7 +144,44 @@ def _prompt_prefix_opted_in(body: Any) -> bool:
     metadata = getattr(body, "metadata", None)
     if isinstance(metadata, Mapping) and metadata.get("prompt_prefix_enabled"):
         return True
-    return False
+    return False
+
+
+def _rag_mode_requested(body: Any) -> bool:
+    context = getattr(body, "context", None)
+    if isinstance(context, Mapping) and context.get("rag_mode_enabled"):
+        return True
+    metadata = getattr(body, "metadata", None)
+    if isinstance(metadata, Mapping) and (
+        metadata.get("rag_mode_enabled") or metadata.get("rag_mode")
+    ):
+        return True
+    return False
+
+
+def _thread_rag_mode_enabled(record: Any) -> bool:
+    if not isinstance(record, Mapping):
+        return False
+    metadata = record.get("metadata")
+    return isinstance(metadata, Mapping) and bool(
+        metadata.get("rag_mode_enabled") or metadata.get("rag_mode")
+    )
+
+
+def _append_invisible_prompt(graph_input: dict[str, Any], prompt: str) -> dict[str, Any]:
+    messages = graph_input.get("messages")
+    if not isinstance(messages, list) or not messages:
+        return graph_input
+    new_messages = list(messages)
+    for idx, msg in enumerate(new_messages):
+        if not isinstance(msg, HumanMessage):
+            continue
+        extra = dict(getattr(msg, "additional_kwargs", None) or {})
+        existing = str(extra.get("prompt_prefix") or "").strip()
+        extra["prompt_prefix"] = f"{existing}\n\n{prompt}".strip() if existing else prompt
+        new_messages[idx] = msg.model_copy(update={"additional_kwargs": extra})
+        break
+    return {**graph_input, "messages": new_messages}
 
 
 # Whitelist of run-context keys that the langgraph-compat layer forwards from
@@ -399,16 +443,29 @@ async def start_run(
     # Upsert thread metadata so the thread appears in /threads/search,
     # even for threads that were never explicitly created via POST /threads
     # (e.g. stateless runs).
-    try:
-        existing = await run_ctx.thread_store.get(thread_id)
-        if existing is None:
-            await run_ctx.thread_store.create(
-                thread_id,
-                assistant_id=body.assistant_id,
-                metadata=body.metadata,
-            )
-        else:
-            await run_ctx.thread_store.update_status(thread_id, "running")
+    requested_rag_mode = _rag_mode_requested(body)
+    effective_rag_mode = requested_rag_mode
+    try:
+        existing = await run_ctx.thread_store.get(thread_id)
+        effective_rag_mode = requested_rag_mode or _thread_rag_mode_enabled(existing)
+        if existing is None:
+            metadata = dict(body.metadata or {})
+            if effective_rag_mode:
+                metadata["rag_mode_enabled"] = True
+                metadata["rag_mode"] = True
+            await run_ctx.thread_store.create(
+                thread_id,
+                assistant_id=body.assistant_id,
+                metadata=metadata,
+            )
+        else:
+            await run_ctx.thread_store.update_status(thread_id, "running")
+            if requested_rag_mode and not _thread_rag_mode_enabled(existing):
+                await run_ctx.thread_store.update_metadata(
+                    thread_id,
+                    {"rag_mode_enabled": True, "rag_mode": True},
+                )
+                effective_rag_mode = True
             # SDK 的 ``client.threads.create()`` 不传 assistant_id —— 先建出来空的 thread，
             # 真正提交 run 时才知道用哪个 assistant。这里回填一次，避免历史列表 / 按
             # assistant 筛选时拿不到关联。
@@ -428,17 +485,21 @@ async def start_run(
     # applies once. We intentionally do NOT gate on thread-row existence: the
     # thread_meta row is frequently pre-created, which previously skipped the
     # prefix for genuine first turns.
-    if _prompt_prefix_opted_in(body):
-        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())
-    config = build_run_config(thread_id, body.config, body.metadata, assistant_id=body.assistant_id)
+    if _prompt_prefix_opted_in(body):
+        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())
+    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)
 
     # Merge DeerFlow-specific context overrides into both ``configurable`` and ``context``.
     # The ``context`` field is a custom extension for the langgraph-compat layer
     # that carries agent configuration (model_name, thinking_enabled, etc.).
     # Only agent-relevant keys are forwarded; unknown keys (e.g. thread_id) are ignored.
-    body_context = dict(getattr(body, "context", None) or {})
+    body_context = dict(getattr(body, "context", None) or {})
+    if effective_rag_mode:
+        body_context["rag_mode_enabled"] = True
     # 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``, …).
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
index d567ce52..4b65a644 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/agents/lead_agent/agent.py
@@ -7,9 +7,10 @@ from langchain_core.runnables import RunnableConfig
 from deerflow.agents.lead_agent.prompt import apply_prompt_template
 from deerflow.agents.middlewares.clarification_middleware import ClarificationMiddleware
 from deerflow.agents.middlewares.loop_detection_middleware import LoopDetectionMiddleware
-from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
-from deerflow.agents.middlewares.prompt_prefix_middleware import PromptPrefixMiddleware
-from deerflow.agents.middlewares.setup_agent_approval_middleware import SetupAgentApprovalMiddleware
+from deerflow.agents.middlewares.memory_middleware import MemoryMiddleware
+from deerflow.agents.middlewares.prompt_prefix_middleware import PromptPrefixMiddleware
+from deerflow.agents.middlewares.rag_citation_middleware import RagCitationMiddleware
+from deerflow.agents.middlewares.setup_agent_approval_middleware import SetupAgentApprovalMiddleware
 from deerflow.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
 from deerflow.agents.middlewares.summarization_middleware import BeforeSummarizationHook, DeerFlowSummarizationMiddleware
 from deerflow.agents.middlewares.title_middleware import TitleMiddleware
@@ -252,13 +253,16 @@ def _build_middlewares(
 
     Returns:
         List of middleware instances.
-    """
-    resolved_app_config = app_config or get_app_config()
-    middlewares = build_lead_runtime_middlewares(app_config=resolved_app_config, lazy_init=True)
+    """
+    resolved_app_config = app_config or get_app_config()
+    cfg = _get_runtime_config(config)
+    middlewares = build_lead_runtime_middlewares(app_config=resolved_app_config, lazy_init=True)
 
-    # Inject the admin prompt prefix into the model request (kept out of the
-    # persisted/displayed message so the user never sees it).
-    middlewares.append(PromptPrefixMiddleware())
+    # Inject the admin prompt prefix into the model request (kept out of the
+    # persisted/displayed message so the user never sees it).
+    middlewares.append(PromptPrefixMiddleware())
+    if cfg.get("rag_mode_enabled", False):
+        middlewares.append(RagCitationMiddleware())
 
     # Add summarization middleware if enabled
     summarization_middleware = _create_summarization_middleware(app_config=resolved_app_config)
@@ -266,8 +270,7 @@ def _build_middlewares(
         middlewares.append(summarization_middleware)
 
     # Add TodoList middleware if plan mode is enabled
-    cfg = _get_runtime_config(config)
-    is_plan_mode = cfg.get("is_plan_mode", False)
+    is_plan_mode = cfg.get("is_plan_mode", False)
     is_bootstrap = cfg.get("is_bootstrap", False)
     todo_list_middleware = _create_todo_list_middleware(is_plan_mode)
     if todo_list_middleware is not None:
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/rag_citation_middleware.py b/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/rag_citation_middleware.py
new file mode 100644
index 00000000..0801f047
--- /dev/null
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/agents/middlewares/rag_citation_middleware.py
@@ -0,0 +1,109 @@
+"""Inject stable citation numbering before RAG final answers."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from collections.abc import Awaitable, Callable
+from typing import Any, override
+
+from langchain.agents import AgentState
+from langchain.agents.middleware import AgentMiddleware
+from langchain.agents.middleware.types import ModelCallResult, ModelRequest, ModelResponse
+from langchain_core.messages import SystemMessage
+
+from deerflow.runtime.references import build_latest_reference_prompt, build_reference_debug_summary
+
+logger = logging.getLogger(__name__)
+_RAG_DEBUG_LOGGER_NAME = "rag_citation_debug"
+
+
+def _get_rag_debug_logger() -> logging.Logger:
+    debug_logger = logging.getLogger(_RAG_DEBUG_LOGGER_NAME)
+    if getattr(debug_logger, "_rag_file_configured", False):
+        return debug_logger
+    log_path = Path(os.environ.get("RAG_CITATION_DEBUG_LOG", "logs/rag_citation_debug.log"))
+    if not log_path.is_absolute():
+        log_path = Path.cwd() / log_path
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    handler = logging.FileHandler(log_path, encoding="utf-8")
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(message)s"))
+    debug_logger.addHandler(handler)
+    debug_logger.setLevel(logging.INFO)
+    debug_logger.propagate = False
+    setattr(debug_logger, "_rag_file_configured", True)
+    setattr(debug_logger, "_rag_file_path", str(log_path))
+    return debug_logger
+
+
+def _log_rag_debug(message: str, *args: Any) -> None:
+    logger.info(message, *args)
+    _get_rag_debug_logger().info(message, *args)
+
+
+class RagCitationMiddleware(AgentMiddleware[AgentState]):
+    """Give the model the same numbered references the frontend will render."""
+
+    @staticmethod
+    def _enabled(request: ModelRequest) -> bool:
+        runtime = getattr(request, "runtime", None)
+        context = getattr(runtime, "context", None) if runtime is not None else None
+        if isinstance(context, dict) and context.get("rag_mode_enabled"):
+            return True
+        config = getattr(runtime, "config", None) if runtime is not None else None
+        if isinstance(config, dict):
+            configurable = config.get("configurable")
+            if isinstance(configurable, dict) and configurable.get("rag_mode_enabled"):
+                return True
+            runtime_context = config.get("context")
+            if isinstance(runtime_context, dict) and runtime_context.get("rag_mode_enabled"):
+                return True
+        return False
+
+    @staticmethod
+    def _patch(request: ModelRequest) -> ModelRequest | None:
+        if not RagCitationMiddleware._enabled(request):
+            return None
+        messages = list(request.messages)
+        prompt, batch = build_latest_reference_prompt(messages)
+        if not prompt:
+            _log_rag_debug(
+                "middleware reference-prompt enabled=true prompt=false messages=%s",
+                len(messages),
+            )
+            return None
+        summary = build_reference_debug_summary(messages, [batch] if batch else None)
+        _log_rag_debug(
+            "middleware reference-prompt enabled=true prompt=true messages=%s tool_messages=%s "
+            "raw_items=%s normalized_items=%s kept_items=%s latest_batch_sources=%s",
+            summary["messages"],
+            summary["tool_messages"],
+            summary["raw_items"],
+            summary["normalized_items"],
+            summary["kept_items"],
+            len((batch or {}).get("sources") or []),
+        )
+        patched_messages = [
+            *messages,
+            SystemMessage(content=prompt),
+        ]
+        return request.override(messages=patched_messages)
+
+    @override
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        patched = self._patch(request)
+        return handler(patched or request)
+
+    @override
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        patched = self._patch(request)
+        return await handler(patched or request)
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
index 67e1a4d9..943f6ba0 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/config/system_settings.py
@@ -54,6 +54,16 @@ class AppearanceSettings(BaseModel):
     model_config = ConfigDict(extra="ignore")
 
 
+class CitationDisplaySettings(BaseModel):
+    """System-wide cleanup rules for citation cards and detail dialogs."""
+
+    cleanup_words: list[str] = Field(
+        default_factory=list,
+        description="Words or phrases used to remove noisy advertisement/disclaimer lines from citation display.",
+    )
+    model_config = ConfigDict(extra="ignore")
+
+
 class PrivateSquareSettings(BaseModel):
     """Admin-configurable settings for the agent private-square (私密广场).
 
@@ -74,6 +84,7 @@ class SystemSettings(BaseModel):
     prompt_prefix: PromptPrefixSettings = Field(default_factory=PromptPrefixSettings)
     private_square: PrivateSquareSettings = Field(default_factory=PrivateSquareSettings)
     appearance: AppearanceSettings = Field(default_factory=AppearanceSettings)
+    citation_display: CitationDisplaySettings = Field(default_factory=CitationDisplaySettings)
     model_config = ConfigDict(extra="ignore")
 
 
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py b/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py
new file mode 100644
index 00000000..9d9782f8
--- /dev/null
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py
@@ -0,0 +1,366 @@
+"""Build stable per-turn citation batches from LangGraph messages."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def build_reference_batches(messages: list[Any]) -> list[dict[str, Any]]:
+    batches: list[dict[str, Any]] = []
+    for index, message in enumerate(messages):
+        if _message_type(message) != "human":
+            continue
+        end = len(messages)
+        for cursor in range(index + 1, len(messages)):
+            if _message_type(messages[cursor]) == "human":
+                end = cursor
+                break
+        assistant = _find_last_assistant_answer(messages, index + 1, end)
+        if assistant is None:
+            continue
+        sources = _collect_sources(messages[index + 1 : end])
+        if sources:
+            message_id = _message_id(assistant) or str(index)
+            batches.append(
+                {
+                    "id": message_id,
+                    "assistant_message_id": message_id,
+                    "sources": sources,
+                }
+            )
+    return batches
+
+
+def build_latest_reference_prompt(messages: list[Any]) -> tuple[str, dict[str, Any] | None]:
+    human_index = _find_latest_human_index(messages)
+    if human_index is None:
+        return "", None
+    sources = _collect_sources(messages[human_index + 1 :])
+    if not sources:
+        return "", None
+    assistant = _find_last_assistant_answer(messages, human_index + 1, len(messages))
+    message_id = _message_id(assistant) or _message_id(messages[human_index]) or str(human_index)
+    batch = {
+        "id": message_id,
+        "assistant_message_id": message_id,
+        "sources": sources,
+    }
+    lines = [
+        "本轮检索结果已由系统统一合并并重新编号。最终回答必须使用下面这套编号。",
+        "如果你仍需要补充检索，请先继续调用工具；最终回答只能引用最新合并后的编号。",
+        "",
+    ]
+    for source in sources:
+        title = source.get("title") or f"参考文献 {source.get('index')}"
+        meta = " · ".join(
+            str(item)
+            for item in (source.get("source"), source.get("time"))
+            if item
+        )
+        content = str(source.get("content") or source.get("snippet") or "").strip()
+        if len(content) > 520:
+            content = content[:517] + "..."
+        head = f"[{source.get('index')}] {title}"
+        if meta:
+            head += f"（{meta}）"
+        lines.append(head)
+        if content:
+            lines.append(content)
+        lines.append("")
+    lines.extend(
+        [
+            "引用规则：",
+            "1. 回答正文中的关键结论必须标注对应编号，例如 [1]、[2]。",
+            "2. 多个来源可写为 [1][3][5]。",
+            "3. 只能引用上方存在的编号，不要编造编号。",
+            "4. 不要使用工具原始编号，也不要重新排序编号。",
+            "5. 不要在正文末尾堆完整参考文献列表，前端会展示右侧参考文献。",
+        ]
+    )
+    return "\n".join(lines).strip(), batch
+
+
+def _find_latest_human_index(messages: list[Any]) -> int | None:
+    for index in range(len(messages) - 1, -1, -1):
+        if _message_type(messages[index]) == "human":
+            return index
+    return None
+
+
+def build_reference_debug_summary(messages: list[Any], batches: list[dict[str, Any]] | None = None) -> dict[str, Any]:
+    """Return compact counts for citation extraction logs."""
+    turn_summaries: list[dict[str, Any]] = []
+    total_tool_messages = 0
+    total_raw_items = 0
+    total_normalized_items = 0
+    total_kept_items = 0
+    for index, message in enumerate(messages):
+        if _message_type(message) != "human":
+            continue
+        end = len(messages)
+        for cursor in range(index + 1, len(messages)):
+            if _message_type(messages[cursor]) == "human":
+                end = cursor
+                break
+        tool_messages = 0
+        raw_items = 0
+        normalized_items = 0
+        kept_items = 0
+        for tool_message in messages[index + 1 : end]:
+            if _message_type(tool_message) != "tool":
+                continue
+            tool_messages += 1
+            items = _first_list(_extract_tool_payload(tool_message))
+            raw_items += len(items)
+            for raw_item in items:
+                normalized = _normalize_reference_item(raw_item, normalized_items + 1)
+                if not normalized:
+                    continue
+                normalized_items += 1
+                kept_items += 1
+        total_tool_messages += tool_messages
+        total_raw_items += raw_items
+        total_normalized_items += normalized_items
+        total_kept_items += kept_items
+        turn_summaries.append(
+            {
+                "human_index": index,
+                "tool_messages": tool_messages,
+                "raw_items": raw_items,
+                "normalized_items": normalized_items,
+                "kept_items": kept_items,
+            }
+        )
+    batch_summaries = [
+        {
+            "id": batch.get("id"),
+            "assistant_message_id": batch.get("assistant_message_id"),
+            "source_count": len(batch.get("sources") or []),
+        }
+        for batch in (batches or build_reference_batches(messages))
+    ]
+    return {
+        "messages": len(messages),
+        "turns": len(turn_summaries),
+        "tool_messages": total_tool_messages,
+        "raw_items": total_raw_items,
+        "normalized_items": total_normalized_items,
+        "kept_items": total_kept_items,
+        "turns_detail": turn_summaries,
+        "batches": batch_summaries,
+    }
+
+
+def _collect_sources(messages: list[Any]) -> list[dict[str, Any]]:
+    sources: list[dict[str, Any]] = []
+    for message in messages:
+        if _message_type(message) != "tool":
+            continue
+        payload = _extract_tool_payload(message)
+        for raw_item in _first_list(payload):
+            normalized = _normalize_reference_item(raw_item, len(sources) + 1)
+            if not normalized:
+                continue
+            normalized["index"] = len(sources) + 1
+            sources.append(normalized)
+    return sources
+
+
+def _find_last_assistant_answer(messages: list[Any], start: int, end: int) -> Any | None:
+    for index in range(end - 1, start - 1, -1):
+        candidate = messages[index]
+        if (
+            _message_type(candidate) == "ai"
+            and _message_id(candidate)
+            and _has_answer_content(candidate)
+            and not _has_tool_calls(candidate)
+        ):
+            return candidate
+    return None
+
+
+def _message_type(message: Any) -> str:
+    if isinstance(message, dict):
+        return str(message.get("type") or message.get("role") or "")
+    return str(getattr(message, "type", "") or "")
+
+
+def _message_id(message: Any) -> str | None:
+    value = message.get("id") if isinstance(message, dict) else getattr(message, "id", None)
+    return str(value) if value else None
+
+
+def _message_content(message: Any) -> Any:
+    return message.get("content") if isinstance(message, dict) else getattr(message, "content", None)
+
+
+def _has_tool_calls(message: Any) -> bool:
+    if isinstance(message, dict):
+        direct = message.get("tool_calls")
+        chunks = message.get("tool_call_chunks")
+        extra = (message.get("additional_kwargs") or {}).get("tool_calls")
+    else:
+        direct = getattr(message, "tool_calls", None)
+        chunks = getattr(message, "tool_call_chunks", None)
+        extra = (getattr(message, "additional_kwargs", None) or {}).get("tool_calls")
+    return bool(direct or chunks or extra)
+
+
+def _has_answer_content(message: Any) -> bool:
+    content = _message_content(message)
+    if isinstance(content, str):
+        return bool(content.strip())
+    if isinstance(content, list):
+        return any(
+            isinstance(part, dict)
+            and part.get("type") == "text"
+            and str(part.get("text") or "").strip()
+            for part in content
+        )
+    return False
+
+
+def _extract_tool_payload(message: Any) -> Any:
+    content = _message_content(message)
+    if isinstance(content, dict):
+        return _unwrap_tool_payload(content)
+    if isinstance(content, list):
+        texts: list[str] = []
+        for part in content:
+            if not isinstance(part, dict):
+                continue
+            if isinstance(part.get("json"), dict):
+                return _unwrap_tool_payload(part["json"])
+            if part.get("type") == "json" and isinstance(part.get("json"), dict):
+                return _unwrap_tool_payload(part["json"])
+            if part.get("type") == "text" and isinstance(part.get("text"), str):
+                texts.append(part["text"])
+            unwrapped = _unwrap_tool_payload(part)
+            if unwrapped is not None:
+                return unwrapped
+        content = "\n".join(texts)
+    if isinstance(content, str):
+        return _parse_json_like(content)
+    return None
+
+
+def _unwrap_tool_payload(value: dict[str, Any]) -> Any:
+    list_keys = ("results", "data", "items", "hits", "documents", "records", "sources")
+    if any(isinstance(value.get(key), list) for key in list_keys):
+        return value
+    for key in ("result", "output", "stdout", "content", "text", "payload", "response"):
+        nested = value.get(key)
+        if isinstance(nested, str):
+            parsed = _parse_json_like(nested)
+            if parsed is not None:
+                return parsed
+        if isinstance(nested, dict):
+            unwrapped = _unwrap_tool_payload(nested)
+            if unwrapped is not None:
+                return unwrapped
+    return value
+
+
+def _parse_json_like(text: str) -> Any:
+    trimmed = text.strip()
+    if not trimmed:
+        return None
+    try:
+        return json.loads(trimmed)
+    except Exception:
+        pass
+    first = trimmed.find("{")
+    last = trimmed.rfind("}")
+    if 0 <= first < last:
+        try:
+            return json.loads(trimmed[first : last + 1])
+        except Exception:
+            return None
+    return None
+
+
+def _first_list(payload: Any) -> list[Any]:
+    if isinstance(payload, list):
+        return payload
+    if not isinstance(payload, dict):
+        return []
+    for key in ("results", "data", "items", "hits", "documents", "records", "entries", "matches", "chunks", "sources"):
+        value = payload.get(key)
+        if isinstance(value, list):
+            return value
+    for key in ("result", "payload", "response", "output", "data"):
+        found = _first_list(payload.get(key))
+        if found:
+            return found
+    return []
+
+
+def _nested_records(raw: Any) -> list[dict[str, Any]]:
+    if not isinstance(raw, dict):
+        return []
+    layers = [raw]
+    for key in ("metadata", "meta", "attrs", "attributes", "properties", "extra"):
+        nested = raw.get(key)
+        if isinstance(nested, dict):
+            layers.append(nested)
+    return layers
+
+
+def _pick(layers: list[dict[str, Any]], keys: tuple[str, ...]) -> str | None:
+    for layer in layers:
+        for key in keys:
+            value = layer.get(key)
+            if isinstance(value, (str, int, float)) and str(value).strip():
+                return str(value).strip()
+    return None
+
+
+def _normalize_reference_item(raw: Any, fallback_index: int) -> dict[str, Any] | None:
+    if not isinstance(raw, dict):
+        return None
+    layers = _nested_records(raw)
+    title = _pick(layers, ("title", "m_title", "name", "question", "keyword", "query", "text"))
+    content = _pick(layers, ("content", "page_content", "summary", "snippet", "description", "content_preview", "abstract", "body"))
+    url = _pick(layers, ("url", "link", "href", "source_url", "web_url"))
+    source = _pick(layers, ("source", "source1", "site", "provider", "from"))
+    time = _pick(layers, ("time", "date", "published_date", "publishedDate", "m_publish", "publish_time", "created_at"))
+    item_id = _pick(layers, ("recUuid", "rec_uuid", "uuid", "docId", "doc_id", "id", "recordId", "taskId"))
+    score_raw = _pick(layers, ("score", "relevance", "similarity"))
+    score = None
+    if score_raw is not None:
+        try:
+            score = float(score_raw)
+        except Exception:
+            score = None
+    if not title:
+        title = source or f"结果 {fallback_index}"
+    if not content:
+        content = ""
+    if not title and not content and not url:
+        return None
+    return {
+        "id": item_id or url,
+        "skillName": "backend-reference",
+        "mode": "citation",
+        "title": title,
+        "type": "result",
+        "snippet": content,
+        "content": content,
+        "source": source,
+        "time": time,
+        "url": url,
+        "score": score,
+        "raw": raw,
+    }
+
+
+def _reference_key(source: dict[str, Any]) -> str:
+    raw = source.get("raw") if isinstance(source.get("raw"), dict) else {}
+    item_id = source.get("id") or source.get("url") or raw.get("recUuid") or raw.get("uuid") or raw.get("docId") or raw.get("id")
+    if item_id:
+        return str(item_id).casefold().strip()
+    return "|".join(
+        str(source.get(key) or "").casefold().strip()
+        for key in ("title", "source", "time", "content", "snippet")
+    )

From fe7cdba07ebb15871102c989513d6f881087f2e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Wed, 27 May 2026 17:44:02 +0800
Subject: [PATCH 13/15] =?UTF-8?q?=E5=BF=BD=E7=95=A5RAG=E8=B0=83=E8=AF=95?=
 =?UTF-8?q?=E6=97=A5=E5=BF=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.gitignore b/.gitignore
index 532043d8..f6b1fff3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,8 +5,10 @@ frontend-web/.vscode/
 # Claude Code local-only settings (per-user permissions, not shared)
 .claude/settings.local.json
 
-# Local runtime logs and pid files
-.runtime/
+# Local runtime logs and pid files
+.runtime/
+logs/
+offline-backend-20260512/backend/logs/
 
 # Frontend local/runtime artifacts
 frontend-web/.env

From 106f1d1794c2a553cea736aa1e8aa3c3d983229a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Wed, 27 May 2026 19:02:19 +0800
Subject: [PATCH 14/15] =?UTF-8?q?=E4=BB=A3=E7=A0=81=E6=8F=90=E4=BA=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend-web/src/core/agents/api.ts           |  25 ++++
 frontend-web/src/core/agents/hooks.ts         |  13 ++
 frontend-web/src/core/skills/hooks.ts         |   8 ++
 frontend-web/src/pages/AdminAgentsPage.tsx    | 121 ++++++++++++++++--
 .../backend/app/gateway/routers/agents.py     |  84 +++++++++++-
 .../harness/deerflow/skills/cascade.py        |  55 ++++++++
 6 files changed, 294 insertions(+), 12 deletions(-)

diff --git a/frontend-web/src/core/agents/api.ts b/frontend-web/src/core/agents/api.ts
index 83eabbe8..eb0caeae 100644
--- a/frontend-web/src/core/agents/api.ts
+++ b/frontend-web/src/core/agents/api.ts
@@ -174,6 +174,31 @@ export async function setAgentFeatured(
   return res.json() as Promise<Agent>;
 }
 
+export interface AgentSkillsSyncRemoval {
+  agent_id: string;
+  agent_name: string | null;
+  user_id: string | null;
+  removed_skills: string[];
+}
+
+export interface AgentSkillsSyncResult {
+  checked: number;
+  modified: number;
+  removals: AgentSkillsSyncRemoval[];
+}
+
+export async function adminSyncAgentSkills(): Promise<AgentSkillsSyncResult> {
+  const res = await apiFetch(
+    `${getBackendBaseURL()}/api/agents/admin/sync-skills`,
+    { method: "POST" },
+  );
+  if (!res.ok) {
+    const err = (await res.json().catch(() => ({}))) as { detail?: string };
+    throw new Error(err.detail ?? `Failed to sync agent skills: ${res.statusText}`);
+  }
+  return res.json() as Promise<AgentSkillsSyncResult>;
+}
+
 export async function checkAgentName(
   name: string,
 ): Promise<{ available: boolean; name: string }> {
diff --git a/frontend-web/src/core/agents/hooks.ts b/frontend-web/src/core/agents/hooks.ts
index 9099d63c..4066ab48 100644
--- a/frontend-web/src/core/agents/hooks.ts
+++ b/frontend-web/src/core/agents/hooks.ts
@@ -6,6 +6,7 @@ import {
 } from "@tanstack/react-query";
 
 import {
+  adminSyncAgentSkills,
   createAgent,
   deleteAgent,
   getAgent,
@@ -180,3 +181,15 @@ export function useSetAgentPrivate() {
     },
   });
 }
+
+export function useAdminSyncAgentSkills() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: adminSyncAgentSkills,
+    onSuccess: (result) => {
+      if (result.modified > 0) {
+        invalidateAgentQueries(queryClient);
+      }
+    },
+  });
+}
diff --git a/frontend-web/src/core/skills/hooks.ts b/frontend-web/src/core/skills/hooks.ts
index c869f40f..658124bd 100644
--- a/frontend-web/src/core/skills/hooks.ts
+++ b/frontend-web/src/core/skills/hooks.ts
@@ -162,6 +162,10 @@ export function useSetSkillPublished() {
     }) => setSkillPublished(skillName, published),
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      // Unpublishing triggers the backend cascade that strips this skill
+      // from every referencing agent's config.yaml, so the cached agent
+      // list (agent.skills) is now stale.
+      void queryClient.invalidateQueries({ queryKey: ["agents"] });
     },
   });
 }
@@ -194,6 +198,10 @@ export function useDeleteCustomSkill() {
     mutationFn: (skillName: string) => deleteCustomSkill(skillName),
     onSuccess: () => {
       void queryClient.invalidateQueries({ queryKey: ["skills"] });
+      // Deletion triggers the backend cascade that strips this skill from
+      // every referencing agent's config.yaml, so the cached agent list
+      // (agent.skills) is now stale.
+      void queryClient.invalidateQueries({ queryKey: ["agents"] });
     },
   });
 }
diff --git a/frontend-web/src/pages/AdminAgentsPage.tsx b/frontend-web/src/pages/AdminAgentsPage.tsx
index 9a94f848..d33d1680 100644
--- a/frontend-web/src/pages/AdminAgentsPage.tsx
+++ b/frontend-web/src/pages/AdminAgentsPage.tsx
@@ -1,8 +1,18 @@
 "use client";
 
-import { BotIcon, SearchIcon } from "lucide-react";
+import { BotIcon, RefreshCwIcon, SearchIcon } from "lucide-react";
 import { useMemo, useState } from "react";
+import { toast } from "sonner";
 
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
 import { Input } from "@/components/ui/input";
 import {
   WorkspaceBody,
@@ -10,12 +20,35 @@ import {
   WorkspaceHeader,
 } from "@/components/workspace/workspace-container";
 import { AgentCard } from "@/components/workspace/agents/agent-card";
-import { useAllAgentsAdmin } from "@/core/agents";
+import { useAdminSyncAgentSkills, useAllAgentsAdmin } from "@/core/agents";
+import type { AgentSkillsSyncResult } from "@/core/agents/api";
 import { desensitize } from "@/lib/desensitize";
 
 export default function AdminAgentsPage() {
   const [search, setSearch] = useState("");
   const { agents, isLoading } = useAllAgentsAdmin(true);
+  const syncSkills = useAdminSyncAgentSkills();
+  const [syncResult, setSyncResult] = useState<AgentSkillsSyncResult | null>(
+    null,
+  );
+  const [syncDialogOpen, setSyncDialogOpen] = useState(false);
+
+  async function handleSyncSkills() {
+    try {
+      const result = await syncSkills.mutateAsync();
+      setSyncResult(result);
+      setSyncDialogOpen(true);
+      if (result.modified === 0) {
+        toast.success("所有智能体的技能均有效，无需清理");
+      } else {
+        toast.success(
+          `已清理 ${result.modified} 个智能体中的失效技能引用`,
+        );
+      }
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
 
   const filteredAgents = useMemo(() => {
     const needle = search.trim().toLowerCase();
@@ -37,14 +70,28 @@ export default function AdminAgentsPage() {
                 管理员视图：查看、编辑、删除所有用户的智能体（包括内置、用户自定义与私密广场条目）。
               </p>
             </div>
-            <div className="relative w-64 shrink-0">
-              <SearchIcon className="text-muted-foreground absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
-              <Input
-                value={search}
-                onChange={(e) => setSearch(e.target.value)}
-                placeholder="按名称搜索"
-                className="pl-8"
-              />
+            <div className="flex shrink-0 items-center gap-2">
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={handleSyncSkills}
+                disabled={syncSkills.isPending}
+                title="扫描所有智能体的 config.yaml，移除指向已不存在技能的引用"
+              >
+                <RefreshCwIcon
+                  className={`mr-1.5 size-4 ${syncSkills.isPending ? "animate-spin" : ""}`}
+                />
+                {syncSkills.isPending ? "正在同步…" : "同步技能"}
+              </Button>
+              <div className="relative w-64">
+                <SearchIcon className="text-muted-foreground absolute left-2.5 top-1/2 size-4 -translate-y-1/2" />
+                <Input
+                  value={search}
+                  onChange={(e) => setSearch(e.target.value)}
+                  placeholder="按名称搜索"
+                  className="pl-8"
+                />
+              </div>
             </div>
           </div>
 
@@ -77,6 +124,60 @@ export default function AdminAgentsPage() {
           </div>
         </div>
       </WorkspaceBody>
+
+      <Dialog open={syncDialogOpen} onOpenChange={setSyncDialogOpen}>
+        <DialogContent className="max-w-2xl">
+          <DialogHeader>
+            <DialogTitle>同步技能 — 清理结果</DialogTitle>
+            <DialogDescription>
+              {syncResult
+                ? `扫描 ${syncResult.checked} 个智能体配置，清理 ${syncResult.modified} 个。`
+                : ""}
+            </DialogDescription>
+          </DialogHeader>
+          {syncResult && syncResult.removals.length > 0 ? (
+            <div className="max-h-[60vh] overflow-y-auto">
+              <ul className="space-y-3 text-sm">
+                {syncResult.removals.map((entry) => (
+                  <li
+                    key={entry.agent_id}
+                    className="rounded-md border px-3 py-2"
+                  >
+                    <div className="font-medium">
+                      {entry.agent_name
+                        ? desensitize(entry.agent_name)
+                        : entry.agent_id}
+                    </div>
+                    <div className="text-muted-foreground mt-0.5 text-xs">
+                      id: {entry.agent_id}
+                      {entry.user_id ? ` · owner: ${entry.user_id}` : " · built-in"}
+                    </div>
+                    <div className="mt-1.5 flex flex-wrap gap-1.5">
+                      {entry.removed_skills.map((s) => (
+                        <span
+                          key={s}
+                          className="bg-muted rounded px-1.5 py-0.5 text-xs"
+                        >
+                          {s}
+                        </span>
+                      ))}
+                    </div>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ) : (
+            <p className="text-muted-foreground text-sm">
+              所有智能体引用的技能均存在，未做任何修改。
+            </p>
+          )}
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setSyncDialogOpen(false)}>
+              关闭
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
     </WorkspaceContainer>
   );
 }
diff --git a/offline-backend-20260512/backend/app/gateway/routers/agents.py b/offline-backend-20260512/backend/app/gateway/routers/agents.py
index 1fb66c5e..9f40d9ec 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/agents.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/agents.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import shutil
 from datetime import datetime
@@ -9,18 +10,22 @@ from typing import Any
 from uuid import uuid4
 
 import yaml
-from fastapi import APIRouter, HTTPException, Query, Request
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from pydantic import BaseModel, Field
 
 from app.gateway.auth.password import verify_password_async
-from app.gateway.deps import get_agent_store, get_tag_store
+from app.gateway.deps import get_agent_store, get_config, get_tag_store
+from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
 from deerflow.config.agents_api_config import get_agents_api_config
 from deerflow.config.agents_config import list_custom_agents, load_agent_config, load_agent_soul, validate_agent_id
+from deerflow.config.app_config import AppConfig
 from deerflow.config.paths import get_paths
 from deerflow.config.system_settings import load_system_settings
 from deerflow.persistence.agents import AgentStore
 from deerflow.persistence.tags import TagStore
 from deerflow.runtime.user_context import get_effective_user_id
+from deerflow.skills.cascade import sync_agent_skills_to_available
+from deerflow.skills.storage import get_or_new_skill_storage
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api", tags=["agents"])
@@ -842,3 +847,78 @@ async def reorder_featured_agents(
     except Exception as e:
         logger.error("Failed to reorder featured agents: %s", e, exc_info=True)
         raise HTTPException(status_code=500, detail=f"Failed to reorder featured agents: {str(e)}") from e
+
+
+class AgentSkillRemovalEntry(BaseModel):
+    agent_id: str = Field(..., description="Agent storage id whose config.yaml was rewritten")
+    agent_name: str | None = Field(default=None, description="Display name from the DB, if any")
+    user_id: str | None = Field(default=None, description="Owner user id (null = built-in)")
+    removed_skills: list[str] = Field(..., description="Skill names that no longer exist on disk and were stripped")
+
+
+class AgentSkillsSyncResponse(BaseModel):
+    checked: int = Field(..., description="Number of agent config.yaml files scanned")
+    modified: int = Field(..., description="Number of agents whose skills list was rewritten")
+    removals: list[AgentSkillRemovalEntry] = Field(default_factory=list, description="Per-agent removal details")
+
+
+@router.post(
+    "/agents/admin/sync-skills",
+    response_model=AgentSkillsSyncResponse,
+    summary="Sync Agent Skills (admin)",
+    description=(
+        "Admin-only. Scan every agent's ``config.yaml`` and strip skill names that "
+        "no longer exist on disk. Repairs historical drift where a skill was "
+        "removed without the delete/unpublish cascade firing (e.g. deleted from "
+        "the filesystem manually, or removed in an older version of the code)."
+    ),
+)
+async def admin_sync_agent_skills(
+    request: Request,
+    config: AppConfig = Depends(get_config),
+) -> AgentSkillsSyncResponse:
+    _require_agents_api_enabled()
+    if not _is_admin_user(request):
+        raise HTTPException(status_code=403, detail="Only system admins can run agent-skills sync")
+
+    try:
+        storage = get_or_new_skill_storage(app_config=config)
+        all_skills = storage.load_skills(enabled_only=False)
+        available = {skill.name for skill in all_skills}
+
+        result = await asyncio.to_thread(sync_agent_skills_to_available, available)
+
+        # Enrich removals with display name + owner from the DB so the admin
+        # UI can show "我的智能体 X 移除了技能 Y" instead of just the id.
+        store = get_agent_store(request)
+        enriched: list[AgentSkillRemovalEntry] = []
+        for entry in result.get("removals", []):
+            agent_id = entry["agent_id"]
+            record = await store.get_any(agent_id)
+            enriched.append(
+                AgentSkillRemovalEntry(
+                    agent_id=agent_id,
+                    agent_name=(record.get("name") if record else None),
+                    user_id=(record.get("user_id") if record else None),
+                    removed_skills=entry["removed_skills"],
+                )
+            )
+
+        if result.get("modified"):
+            await refresh_skills_system_prompt_cache_async()
+
+        logger.info(
+            "Admin agent-skills sync: checked=%d modified=%d",
+            result["checked"],
+            result["modified"],
+        )
+        return AgentSkillsSyncResponse(
+            checked=result["checked"],
+            modified=result["modified"],
+            removals=enriched,
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error("Failed to sync agent skills: %s", e, exc_info=True)
+        raise HTTPException(status_code=500, detail=f"Failed to sync agent skills: {str(e)}") from e
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/skills/cascade.py b/offline-backend-20260512/backend/packages/harness/deerflow/skills/cascade.py
index 17d3ae0f..1e753ce0 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/skills/cascade.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/skills/cascade.py
@@ -149,3 +149,58 @@ async def cascade_skill_unpublished_or_deleted(
         counters["notified"] += 1
 
     return counters
+
+
+def sync_agent_skills_to_available(available_skill_names: set[str]) -> dict[str, Any]:
+    """Strip skill references that no longer exist on disk from every agent.
+
+    Walks every agent dir and rewrites its ``config.yaml`` ``skills`` list to
+    contain only names that appear in ``available_skill_names``. Used by the
+    admin "agent-skills sync" endpoint to repair historical drift — skills
+    deleted before the cascade existed, deleted via a path that skipped the
+    cascade, or removed from the filesystem manually.
+
+    Synchronous because it only touches local files and the admin endpoint
+    runs it in a worker thread.
+
+    Returns ``{checked, modified, removals: [{agent_id, removed_skills}]}``.
+    """
+    counters: dict[str, Any] = {"checked": 0, "modified": 0, "removals": []}
+
+    for agent_dir in _list_agent_dirs():
+        config_file = agent_dir / "config.yaml"
+        if not config_file.exists():
+            continue
+        counters["checked"] += 1
+
+        try:
+            with config_file.open("r", encoding="utf-8") as f:
+                data: dict[str, Any] = yaml.safe_load(f) or {}
+        except yaml.YAMLError:
+            logger.warning("Sync: failed to parse %s, skipping", config_file)
+            continue
+
+        skills = data.get("skills")
+        if not isinstance(skills, list) or not skills:
+            continue
+
+        kept: list[str] = []
+        removed: list[str] = []
+        for name in skills:
+            if isinstance(name, str) and name in available_skill_names:
+                kept.append(name)
+            else:
+                removed.append(name if isinstance(name, str) else str(name))
+
+        if not removed:
+            continue
+
+        data["skills"] = kept
+        with config_file.open("w", encoding="utf-8") as f:
+            yaml.safe_dump(data, f, default_flow_style=False, allow_unicode=True)
+
+        counters["modified"] += 1
+        counters["removals"].append({"agent_id": agent_dir.name, "removed_skills": removed})
+        logger.info("Sync: removed orphan skills %s from agent '%s'", removed, agent_dir.name)
+
+    return counters

From 4410acaee8644ee3961273c24069562eaba1cad6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=89=E9=91=AB=E5=8D=87?= <xsji@kland.com.cn>
Date: Thu, 28 May 2026 15:16:56 +0800
Subject: [PATCH 15/15] =?UTF-8?q?=E6=8A=80=E8=83=BD=E5=B1=95=E7=A4=BA?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE=E6=8C=81=E4=B9=85=E5=8C=96=E5=B9=B6=E9=80=82?=
 =?UTF-8?q?=E9=85=8D=E5=BC=95=E7=94=A8=E6=9D=A5=E6=BA=90,=E6=96=B0?=
 =?UTF-8?q?=E5=A2=9E=E6=8A=80=E8=83=BD=E6=96=87=E4=BB=B6=E9=A2=84=E8=A7=88?=
 =?UTF-8?q?=E7=BB=84=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 后端将技能展示适配配置存入数据库,引用批次按持久化映射进行适配
- 前端新增技能文件预览弹窗与文件树组件,完善技能来源展示
- 修正 .gitignore 中宽泛的 skills/ 规则误忽略前端组件目录的问题

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |  11 +-
 .../components/workspace/chats/chat-box.tsx   | 231 +++++++++-
 .../workspace/skill-display-sources.tsx       |   9 +-
 .../skills/skill-file-preview-dialog.tsx      | 284 +++++++++++++
 .../workspace/skills/skill-file-tree.tsx      | 152 +++++++
 .../workspace/workspace-nav-chat-list.tsx     |   2 +-
 .../src/core/skill-display/runtime.ts         | 101 +----
 frontend-web/src/core/threads/hooks.ts        |  41 +-
 frontend-web/src/styles/globals.css           |  13 -
 .../backend/app/gateway/routers/threads.py    |  80 +++-
 .../harness/deerflow/runtime/references.py    | 401 +++++++++++++++++-
 11 files changed, 1153 insertions(+), 172 deletions(-)
 create mode 100644 frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx
 create mode 100644 frontend-web/src/components/workspace/skills/skill-file-tree.tsx

diff --git a/.gitignore b/.gitignore
index f6b1fff3..ba42257b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,10 +5,10 @@ frontend-web/.vscode/
 # Claude Code local-only settings (per-user permissions, not shared)
 .claude/settings.local.json
 
-# Local runtime logs and pid files
-.runtime/
-logs/
-offline-backend-20260512/backend/logs/
+# Local runtime logs and pid files
+.runtime/
+logs/
+offline-backend-20260512/backend/logs/
 
 # Frontend local/runtime artifacts
 frontend-web/.env
@@ -83,3 +83,6 @@ hermes-agent-main/
 offline-backend-20260512/backend/tests/*
 deploy
 .history
+
+# Frontend skills components must be tracked (excluded from the broad skills/ ignore above)
+!frontend-web/src/components/workspace/skills/
diff --git a/frontend-web/src/components/workspace/chats/chat-box.tsx b/frontend-web/src/components/workspace/chats/chat-box.tsx
index 20b6e434..2841cdfa 100644
--- a/frontend-web/src/components/workspace/chats/chat-box.tsx
+++ b/frontend-web/src/components/workspace/chats/chat-box.tsx
@@ -16,6 +16,7 @@ import { apiFetch } from "@/core/api";
 import { getBackendBaseURL } from "@/core/config";
 import { isThreadRagModeLocked, useLocalSettings } from "@/core/settings";
 import { useSkills } from "@/core/skills/hooks";
+import { normalizeDisplaySources } from "@/core/skill-display/display-adapter";
 import {
   buildSkillDisplayMap,
   collectRuntimeDisplaySources,
@@ -147,16 +148,30 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
       });
     return () => controller.abort();
   }, [ragModeEnabled, thread.isLoading, threadId, thread.values.messages]);
-  const referenceBatches =
-    backendReferenceBatches.length > 0
-      ? backendReferenceBatches
-      : fallbackReferenceBatches;
+  const adaptedBackendReferenceBatches = useMemo(
+    () =>
+      adaptBackendReferenceBatches(
+        backendReferenceBatches,
+        fallbackReferenceBatches,
+        skillDisplayMap,
+      ),
+    [backendReferenceBatches, fallbackReferenceBatches, skillDisplayMap],
+  );
+  const referenceBatches = useMemo(
+    () =>
+      mergeReferenceBatches(
+        adaptedBackendReferenceBatches,
+        fallbackReferenceBatches,
+      ),
+    [adaptedBackendReferenceBatches, fallbackReferenceBatches],
+  );
   useEffect(() => {
     if (!ragModeEnabled) {
       return;
     }
     const signature = JSON.stringify({
       backend: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      adaptedBackend: adaptedBackendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
       fallback: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
       final: referenceBatches.map((batch) => batch.sources?.length ?? 0),
     });
@@ -168,12 +183,13 @@ const ChatBox: React.FC<{ children: React.ReactNode; threadId: string }> = ({
       using: backendReferenceBatches.length > 0 ? "后端接口" : "前端兜底",
       backendBatchCount: backendReferenceBatches.length,
       backendSourceCounts: backendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
+      adaptedBackendSourceCounts: adaptedBackendReferenceBatches.map((batch) => batch.sources?.length ?? 0),
       fallbackBatchCount: fallbackReferenceBatches.length,
       fallbackSourceCounts: fallbackReferenceBatches.map((batch) => batch.sources?.length ?? 0),
       finalBatchCount: referenceBatches.length,
       finalSourceCounts: referenceBatches.map((batch) => batch.sources?.length ?? 0),
     });
-  }, [backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
+  }, [adaptedBackendReferenceBatches, backendReferenceBatches, fallbackReferenceBatches, ragModeEnabled, referenceBatches, threadId]);
   const latestReferenceBatch =
     referenceBatches.length > 0
       ? referenceBatches[referenceBatches.length - 1]!
@@ -487,6 +503,191 @@ function ReferencePanel({
   );
 }
 
+function adaptBackendReferenceBatches(
+  backendBatches: BackendReferenceBatch[],
+  configuredBatches: BackendReferenceBatch[],
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+): BackendReferenceBatch[] {
+  if (backendBatches.length === 0) {
+    return backendBatches;
+  }
+  return backendBatches.map((backendBatch, batchIndex) => {
+    const configuredBatch =
+      configuredBatches.find(
+        (batch) =>
+          batch.id === backendBatch.id ||
+          batch.assistant_message_id === backendBatch.assistant_message_id,
+      ) ?? configuredBatches[batchIndex];
+    const configuredSources = configuredBatch?.sources ?? [];
+    const configuredByIndex = new Map(
+      configuredSources.map((source) => [source.index, source]),
+    );
+    const configuredByKey = new Map(
+      configuredSources.map((source) => [referenceSourceKey(source), source]),
+    );
+    return {
+      ...backendBatch,
+      sources: backendBatch.sources.map((backendSource, sourceIndex) => {
+        const configuredSource =
+          configuredByIndex.get(backendSource.index) ??
+          configuredByKey.get(referenceSourceKey(backendSource)) ??
+          configuredSources[sourceIndex] ??
+          adaptBackendSourceWithSkillDisplay(backendSource, skillDisplayMap);
+        if (!configuredSource) {
+          return backendSource;
+        }
+        return {
+          ...backendSource,
+          ...configuredSource,
+          index: backendSource.index,
+          mode:
+            backendSource.mode !== "citation"
+              ? backendSource.mode
+              : configuredSource.mode || backendSource.mode,
+          raw: backendSource.raw ?? configuredSource.raw,
+        };
+      }),
+    };
+  });
+}
+
+function mergeReferenceBatches(
+  backendBatches: BackendReferenceBatch[],
+  fallbackBatches: BackendReferenceBatch[],
+): BackendReferenceBatch[] {
+  if (backendBatches.length === 0) {
+    return fallbackBatches;
+  }
+  if (fallbackBatches.length === 0) {
+    return backendBatches;
+  }
+  const merged = [...backendBatches];
+  const knownIds = new Set(
+    backendBatches.flatMap((batch) =>
+      [batch.id, batch.assistant_message_id].filter(Boolean),
+    ),
+  );
+  for (const fallbackBatch of fallbackBatches) {
+    if (
+      knownIds.has(fallbackBatch.id) ||
+      (fallbackBatch.assistant_message_id &&
+        knownIds.has(fallbackBatch.assistant_message_id))
+    ) {
+      continue;
+    }
+    merged.push(fallbackBatch);
+  }
+  return merged;
+}
+
+function adaptBackendSourceWithSkillDisplay(
+  source: BackendReferenceSource,
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+): BackendReferenceSource | null {
+  const raw = source.raw;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return null;
+  }
+  const rawItem = raw as Record<string, unknown>;
+  const match = findBackendSourceDisplay(source, skillDisplayMap);
+  if (!match) {
+    return null;
+  }
+  const normalized = normalizeDisplaySources(
+    buildPayloadAtPath(match.display.resultPath || "results", [rawItem]),
+    match.display,
+  )[0];
+  if (!normalized) {
+    return null;
+  }
+  return {
+    ...source,
+    ...normalized,
+    skillName: match.skillName,
+    mode: match.display.mode,
+    tableColumns: match.display.tableColumns,
+    index: source.index,
+    raw: source.raw,
+  };
+}
+
+function findBackendSourceDisplay(
+  source: BackendReferenceSource,
+  skillDisplayMap: ReturnType<typeof buildSkillDisplayMap>,
+) {
+  const direct = skillDisplayMap.get(source.skillName);
+  if (direct) {
+    return { skillName: source.skillName, display: direct };
+  }
+  const normalizedSource = normalizeSkillName(source.skillName);
+  for (const [skillName, display] of skillDisplayMap) {
+    const normalizedSkill = normalizeSkillName(skillName);
+    if (
+      normalizedSource === normalizedSkill ||
+      normalizedSource.endsWith(normalizedSkill) ||
+      normalizedSource.includes(normalizedSkill)
+    ) {
+      return { skillName, display };
+    }
+  }
+  return null;
+}
+
+function normalizeSkillName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+
+function buildPayloadAtPath(path: string, items: Record<string, unknown>[]) {
+  const parts = path.split(".").map((part) => part.trim()).filter(Boolean);
+  if (parts.length === 0) {
+    return items;
+  }
+  const root: Record<string, unknown> = {};
+  let cursor = root;
+  for (let index = 0; index < parts.length; index++) {
+    const part = parts[index]!;
+    if (index === parts.length - 1) {
+      cursor[part] = items;
+    } else {
+      const next: Record<string, unknown> = {};
+      cursor[part] = next;
+      cursor = next;
+    }
+  }
+  return root;
+}
+
+function referenceSourceKey(source: BackendReferenceSource): string {
+  const raw = source.raw ?? {};
+  const rawRecord =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const id =
+    source.id ||
+    source.url ||
+    stringifyKeyValue(rawRecord.recUuid) ||
+    stringifyKeyValue(rawRecord.uuid) ||
+    stringifyKeyValue(rawRecord.docId) ||
+    stringifyKeyValue(rawRecord.id);
+  if (id) {
+    return id.trim().toLowerCase();
+  }
+  return [source.title, source.source, source.time, source.content, source.snippet]
+    .filter(Boolean)
+    .join("|")
+    .trim()
+    .toLowerCase();
+}
+
+function stringifyKeyValue(value: unknown): string | undefined {
+  if (typeof value === "string" || typeof value === "number") {
+    const text = String(value).trim();
+    return text || undefined;
+  }
+  return undefined;
+}
+
 function findPreviousHumanMessageId(
   messages: Message[],
   beforeMessageId?: string,
@@ -530,8 +731,7 @@ function buildTurnReferenceBatches(
       beforeMessageId:
         nextHumanIndex === -1 ? undefined : messages[nextHumanIndex]?.id,
       includeBeforeMessage: false,
-      includeModes: ["citation"],
-    }).filter((source) => source.mode === "citation");
+    }).filter((source) => source.mode !== "none");
     if (sources.length > 0) {
       batches.push({
         id: assistant.id,
@@ -562,8 +762,7 @@ function findLastAssistantAnswer(
     if (
       message?.type === "ai" &&
       message.id &&
-      hasAssistantAnswerContent(message) &&
-      !hasAssistantToolCalls(message)
+      hasAssistantAnswerContent(message)
     ) {
       return message;
     }
@@ -588,18 +787,4 @@ function hasAssistantAnswerContent(message: Message): boolean {
   });
 }
 
-function hasAssistantToolCalls(message: Message): boolean {
-  const direct = (message as { tool_calls?: unknown }).tool_calls;
-  if (Array.isArray(direct) && direct.length > 0) {
-    return true;
-  }
-  const chunks = (message as { tool_call_chunks?: unknown }).tool_call_chunks;
-  if (Array.isArray(chunks) && chunks.length > 0) {
-    return true;
-  }
-  const kwargs = (message as { additional_kwargs?: Record<string, unknown> }).additional_kwargs;
-  const extra = kwargs?.tool_calls;
-  return Array.isArray(extra) && extra.length > 0;
-}
-
 export { ChatBox };
diff --git a/frontend-web/src/components/workspace/skill-display-sources.tsx b/frontend-web/src/components/workspace/skill-display-sources.tsx
index 080be3c0..9c940afe 100644
--- a/frontend-web/src/components/workspace/skill-display-sources.tsx
+++ b/frontend-web/src/components/workspace/skill-display-sources.tsx
@@ -71,6 +71,7 @@ export function SourceCard({
     score ? `相关度 ${score}` : null,
   ].filter(Boolean);
   const isCitation = source.mode === "citation";
+  const showReferenceNumber = referenceTarget || isCitation;
 
   return (
     <>
@@ -79,14 +80,14 @@ export function SourceCard({
         type="button"
         className={cn(
           "group bg-card/60 hover:bg-card hover:border-primary/40 focus-visible:ring-primary/30 w-full scroll-mt-12 rounded-xl border px-3.5 py-3 text-left shadow-sm transition-all focus-visible:ring-2 focus-visible:outline-none",
-          "target:bg-primary/5 target:border-primary/60",
+          "target:border-amber-300 target:bg-amber-50/80",
           highlighted &&
-            "animate-[reference-flash_1.4s_ease-out] border-amber-400 bg-amber-50 shadow-[0_0_0_3px_rgba(251,191,36,0.22)]",
+            "border-amber-300 bg-amber-50/80 shadow-[0_0_0_2px_rgba(251,191,36,0.14)]",
         )}
         onClick={() => setOpen(true)}
       >
         <div className="flex items-start gap-3">
-          {isCitation && (
+          {showReferenceNumber && (
             <span className="bg-primary/10 text-primary border-primary/20 group-hover:bg-primary/15 mt-0.5 inline-flex size-6 shrink-0 items-center justify-center rounded-full border text-xs font-semibold tabular-nums">
               {source.index}
             </span>
@@ -122,7 +123,7 @@ export function SourceCard({
             <div className="flex items-start justify-between gap-3 pr-8">
               <div className="min-w-0 flex-1">
                 <div className="flex items-start gap-2">
-                  {isCitation && (
+                  {showReferenceNumber && (
                     <span className="bg-primary/10 text-primary border-primary/20 mt-1 inline-flex size-6 shrink-0 items-center justify-center rounded-full border text-xs font-semibold tabular-nums">
                       {source.index}
                     </span>
diff --git a/frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx b/frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx
new file mode 100644
index 00000000..000aa9ae
--- /dev/null
+++ b/frontend-web/src/components/workspace/skills/skill-file-preview-dialog.tsx
@@ -0,0 +1,284 @@
+"use client";
+
+import {
+  CopyIcon,
+  DownloadIcon,
+  Loader2,
+  PencilIcon,
+  XIcon,
+} from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Textarea } from "@/components/ui/textarea";
+import { MarkdownContent } from "@/components/workspace/messages/markdown-content";
+import { getSkillFileDownloadURL } from "@/core/skills/api";
+import {
+  useSaveSkillFile,
+  useSkillFileContent,
+} from "@/core/skills/hooks";
+import { useI18n } from "@/core/i18n/hooks";
+import { reasoningPlugins } from "@/core/streamdown";
+
+const markdownClassName =
+  "!h-auto !w-full max-w-none min-w-0 text-sm leading-7 " +
+  "[&_h1]:mt-0 [&_h1]:mb-3 [&_h1]:text-xl [&_h1]:font-semibold " +
+  "[&_h2]:mt-6 [&_h2]:mb-2 [&_h2]:border-b [&_h2]:pb-2 [&_h2]:text-lg [&_h2]:font-semibold " +
+  "[&_h3]:mt-5 [&_h3]:mb-2 [&_h3]:text-base [&_h3]:font-semibold " +
+  "[&_p]:my-3 [&_ul]:my-3 [&_ol]:my-3 [&_li]:my-1.5 " +
+  "[&_ul]:list-disc [&_ol]:list-decimal [&_ul]:pl-5 [&_ol]:pl-5 " +
+  "[&_blockquote]:my-4 [&_blockquote]:border-l-4 [&_blockquote]:pl-4 [&_blockquote]:text-muted-foreground " +
+  "[&_code]:rounded [&_code]:border [&_code]:bg-muted [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-xs " +
+  "[&_pre]:my-4 [&_pre]:max-w-full [&_pre]:overflow-x-auto [&_pre]:rounded-lg [&_pre]:border [&_pre]:bg-muted [&_pre]:p-4 " +
+  "[&_pre_code]:border-0 [&_pre_code]:bg-transparent [&_pre_code]:p-0";
+
+function isImageMime(mime: string): boolean {
+  return mime.startsWith("image/");
+}
+
+export function SkillFilePreviewDialog({
+  skillName,
+  path,
+  treeEditable,
+  open,
+  onOpenChange,
+}: {
+  skillName: string | null;
+  path: string | null;
+  /** From the tree response: whether *any* file in this skill is editable for the caller. */
+  treeEditable: boolean;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}) {
+  const { t } = useI18n();
+  const tx = t.settings.skills;
+
+  const { data, isLoading, error } = useSkillFileContent(
+    open ? skillName : null,
+    open ? path : null,
+  );
+  const save = useSaveSkillFile();
+
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState("");
+
+  // Reset editor state whenever a different file is opened or the dialog closes.
+  useEffect(() => {
+    setEditing(false);
+    setDraft("");
+  }, [path, open]);
+
+  const fileEditable = !!data?.editable && treeEditable;
+  const isMarkdown = useMemo(() => {
+    if (!path) return false;
+    const lower = path.toLowerCase();
+    return lower.endsWith(".md") || lower.endsWith(".markdown");
+  }, [path]);
+
+  const dirty = editing && data?.content !== undefined && draft !== data.content;
+
+  function requestClose(next: boolean) {
+    if (!next && dirty) {
+      if (!window.confirm(tx.filesDiscardConfirm)) return;
+    }
+    onOpenChange(next);
+  }
+
+  function startEditing() {
+    if (!data || data.content == null) return;
+    setDraft(data.content);
+    setEditing(true);
+  }
+
+  function cancelEditing() {
+    if (dirty && !window.confirm(tx.filesDiscardConfirm)) return;
+    setEditing(false);
+    setDraft("");
+  }
+
+  async function handleSave() {
+    if (!skillName || !path) return;
+    try {
+      await save.mutateAsync({ skillName, path, content: draft });
+      toast.success(tx.filesSaveSuccess);
+      setEditing(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  async function handleCopyPath() {
+    if (!path) return;
+    await navigator.clipboard.writeText(path);
+    toast.success(tx.filesCopyPathAction);
+  }
+
+  const downloadHref =
+    skillName && path ? getSkillFileDownloadURL(skillName, path) : undefined;
+
+  return (
+    <Dialog open={open} onOpenChange={requestClose}>
+      <DialogContent
+        showCloseButton={false}
+        className="flex flex-col gap-0 overflow-hidden p-0"
+        style={{
+          width: "min(56rem, calc(100vw - 2rem))",
+          maxWidth: "none",
+          height: "min(720px, calc(100dvh - 2rem))",
+        }}
+      >
+        <DialogHeader className="shrink-0 border-b px-5 py-3">
+          <div className="flex items-start justify-between gap-2">
+            <div className="min-w-0 flex-1">
+              <DialogTitle className="truncate font-mono text-sm">
+                {path ?? ""}
+              </DialogTitle>
+              <DialogDescription className="mt-0.5 truncate text-xs">
+                {skillName}
+                {data ? ` · ${formatBytes(data.size)} · ${data.mime}` : null}
+              </DialogDescription>
+            </div>
+            <div className="flex shrink-0 items-center gap-1">
+              {fileEditable && !editing && data?.is_text && (
+                <Button
+                  size="sm"
+                  variant="ghost"
+                  className="text-muted-foreground hover:text-foreground h-7 px-2 text-xs"
+                  onClick={startEditing}
+                >
+                  <PencilIcon className="size-3.5" />
+                  {tx.filesEditAction}
+                </Button>
+              )}
+              {editing && (
+                <>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    className="h-7 px-2 text-xs"
+                    onClick={cancelEditing}
+                    disabled={save.isPending}
+                  >
+                    {tx.filesCancelEditAction}
+                  </Button>
+                  <Button
+                    size="sm"
+                    className="h-7 px-2 text-xs"
+                    onClick={() => void handleSave()}
+                    disabled={save.isPending || !dirty}
+                  >
+                    {save.isPending && <Loader2 className="size-3.5 animate-spin" />}
+                    {tx.filesSaveAction}
+                  </Button>
+                </>
+              )}
+              {!editing && (
+                <>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    className="text-muted-foreground hover:text-foreground h-7 px-2 text-xs"
+                    onClick={() => void handleCopyPath()}
+                  >
+                    <CopyIcon className="size-3.5" />
+                  </Button>
+                  {downloadHref && (
+                    <Button
+                      asChild
+                      size="sm"
+                      variant="ghost"
+                      className="text-muted-foreground hover:text-foreground h-7 px-2 text-xs"
+                    >
+                      <a href={downloadHref} download>
+                        <DownloadIcon className="size-3.5" />
+                      </a>
+                    </Button>
+                  )}
+                </>
+              )}
+              <Button
+                size="sm"
+                variant="ghost"
+                className="text-muted-foreground hover:text-foreground h-7 px-1.5 text-xs"
+                onClick={() => requestClose(false)}
+              >
+                <XIcon className="size-4" />
+              </Button>
+            </div>
+          </div>
+        </DialogHeader>
+
+        <div className="min-h-0 flex-1 overflow-auto px-5 py-4">
+          {isLoading ? (
+            <div className="text-muted-foreground flex items-center justify-center gap-2 py-12 text-sm">
+              <Loader2 className="size-4 animate-spin" />
+              {t.common.loading}
+            </div>
+          ) : error ? (
+            <div className="text-destructive py-6 text-sm">
+              {error instanceof Error ? error.message : String(error)}
+            </div>
+          ) : data == null ? null : editing ? (
+            <Textarea
+              value={draft}
+              onChange={(event) => setDraft(event.currentTarget.value)}
+              autoFocus
+              spellCheck={false}
+              className="h-full min-h-[420px] w-full resize-none font-mono text-xs leading-relaxed"
+            />
+          ) : data.is_text ? (
+            isMarkdown ? (
+              <MarkdownContent
+                className={markdownClassName}
+                content={data.content ?? ""}
+                isLoading={false}
+                remarkPlugins={reasoningPlugins.remarkPlugins}
+                rehypePlugins={reasoningPlugins.rehypePlugins}
+              />
+            ) : (
+              <pre className="text-foreground/80 bg-muted/40 max-w-full overflow-x-auto rounded-lg border p-4 font-mono text-xs leading-relaxed whitespace-pre">
+                {data.content ?? ""}
+              </pre>
+            )
+          ) : isImageMime(data.mime) ? (
+            <div className="flex items-center justify-center">
+              {downloadHref && (
+                <img
+                  src={downloadHref}
+                  alt={data.path}
+                  className="max-h-full max-w-full rounded border"
+                />
+              )}
+            </div>
+          ) : (
+            <div className="text-muted-foreground rounded-lg border border-dashed px-4 py-12 text-center text-sm">
+              <p>{tx.filesPreviewBinary}</p>
+              {downloadHref && (
+                <Button asChild size="sm" variant="outline" className="mt-3">
+                  <a href={downloadHref} download>
+                    <DownloadIcon className="size-3.5" />
+                    {tx.filesDownloadAction}
+                  </a>
+                </Button>
+              )}
+            </div>
+          )}
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
diff --git a/frontend-web/src/components/workspace/skills/skill-file-tree.tsx b/frontend-web/src/components/workspace/skills/skill-file-tree.tsx
new file mode 100644
index 00000000..1c3694e6
--- /dev/null
+++ b/frontend-web/src/components/workspace/skills/skill-file-tree.tsx
@@ -0,0 +1,152 @@
+"use client";
+
+import {
+  ChevronRightIcon,
+  FileCode2Icon,
+  FileIcon,
+  FileJsonIcon,
+  FileTextIcon,
+  FolderIcon,
+  FolderOpenIcon,
+  ImageIcon,
+} from "lucide-react";
+import { useMemo, useState } from "react";
+
+import { cn } from "@/lib/utils";
+import type { SkillFileNode } from "@/core/skills/api";
+
+const CODE_EXTS = new Set([
+  "py", "js", "jsx", "ts", "tsx", "mjs", "cjs",
+  "sh", "bash", "zsh", "ps1",
+  "html", "htm", "css", "scss", "sass", "xml", "svg",
+  "sql", "ini", "toml", "cfg", "env", "yaml", "yml",
+]);
+const IMAGE_EXTS = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico", "tiff"]);
+
+function fileIconFor(name: string) {
+  const ext = name.includes(".") ? name.split(".").pop()!.toLowerCase() : "";
+  if (name === "SKILL.md") return FileTextIcon;
+  if (IMAGE_EXTS.has(ext)) return ImageIcon;
+  if (ext === "md" || ext === "markdown" || ext === "txt" || ext === "rst") return FileTextIcon;
+  if (ext === "json" || ext === "jsonl") return FileJsonIcon;
+  if (CODE_EXTS.has(ext)) return FileCode2Icon;
+  return FileIcon;
+}
+
+function TreeRow({
+  node,
+  depth,
+  selectedPath,
+  onOpen,
+}: {
+  node: SkillFileNode;
+  depth: number;
+  selectedPath: string | null;
+  onOpen: (path: string) => void;
+}) {
+  // Top-level (root) auto-expands; nested directories start collapsed.
+  const [open, setOpen] = useState(depth === 0);
+
+  if (node.type === "dir") {
+    const FolderGlyph = open ? FolderOpenIcon : FolderIcon;
+    return (
+      <div>
+        <button
+          type="button"
+          onClick={() => setOpen((value) => !value)}
+          className={cn(
+            "group hover:bg-muted/60 flex w-full items-center gap-1 rounded px-1.5 py-1 text-left text-sm",
+          )}
+          style={{ paddingLeft: 6 + depth * 14 }}
+        >
+          <ChevronRightIcon
+            className={cn(
+              "text-muted-foreground size-3.5 shrink-0 transition-transform",
+              open && "rotate-90",
+            )}
+          />
+          <FolderGlyph className="size-4 shrink-0 text-amber-500/90" />
+          <span className="truncate font-medium">{node.name}</span>
+        </button>
+        {open && node.children && node.children.length > 0 && (
+          <div className="border-border/60 ml-[14px] border-l border-dashed">
+            {node.children.map((child) => (
+              <TreeRow
+                key={child.path || child.name}
+                node={child}
+                depth={depth + 1}
+                selectedPath={selectedPath}
+                onOpen={onOpen}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  const Icon = fileIconFor(node.name);
+  const isSelected = selectedPath === node.path;
+  return (
+    <button
+      type="button"
+      onClick={() => onOpen(node.path)}
+      className={cn(
+        "hover:bg-muted/60 flex w-full items-center gap-1.5 rounded px-1.5 py-1 text-left text-sm",
+        isSelected && "bg-primary/10 hover:bg-primary/15",
+      )}
+      style={{ paddingLeft: 6 + depth * 14 + 14 }}
+      title={node.path}
+    >
+      <Icon className="text-muted-foreground size-4 shrink-0" />
+      <span className="truncate">{node.name}</span>
+      {typeof node.size === "number" && (
+        <span className="text-muted-foreground/70 ml-auto shrink-0 text-[10px] tabular-nums">
+          {formatBytes(node.size)}
+        </span>
+      )}
+    </button>
+  );
+}
+
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+export function SkillFileTree({
+  root,
+  onOpen,
+  selectedPath,
+  emptyText,
+}: {
+  root: SkillFileNode;
+  onOpen: (path: string) => void;
+  selectedPath: string | null;
+  emptyText: string;
+}) {
+  const isEmpty = useMemo(
+    () => !root.children || root.children.length === 0,
+    [root],
+  );
+
+  if (isEmpty) {
+    return (
+      <div className="text-muted-foreground rounded-lg border border-dashed px-4 py-8 text-center text-sm">
+        {emptyText}
+      </div>
+    );
+  }
+
+  return (
+    <div className="font-mono">
+      <TreeRow
+        node={root}
+        depth={0}
+        selectedPath={selectedPath}
+        onOpen={onOpen}
+      />
+    </div>
+  );
+}
diff --git a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
index 2fca2ddf..ca241545 100644
--- a/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
+++ b/frontend-web/src/components/workspace/workspace-nav-chat-list.tsx
@@ -165,7 +165,7 @@ export function WorkspaceNavChatList({
         )}
       </SidebarMenu>
     </SidebarGroup>
-    {!showCollapseTrigger && <WorkspaceNavStudio />}
+    {/* {!showCollapseTrigger && <WorkspaceNavStudio />} */}
     </>
   );
 }
diff --git a/frontend-web/src/core/skill-display/runtime.ts b/frontend-web/src/core/skill-display/runtime.ts
index 205f5f44..6f0ac9e4 100644
--- a/frontend-web/src/core/skill-display/runtime.ts
+++ b/frontend-web/src/core/skill-display/runtime.ts
@@ -106,23 +106,6 @@ function canInferSkillFromToolArgs(toolName: string): boolean {
   );
 }
 
-function canInspectPayloadForDisplay(toolName: string): boolean {
-  const normalized = normalizeName(toolName);
-  if (
-    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(toolName) ||
-    TOOL_ARG_SKILL_MATCH_EXCLUDES.has(normalized)
-  ) {
-    return false;
-  }
-  return (
-    canInferSkillFromToolArgs(toolName) ||
-    normalized.includes("search") ||
-    normalized.includes("retriev") ||
-    normalized.includes("knowledge") ||
-    normalized.includes("query")
-  );
-}
-
 function extractSkillNameFromArgs(args: Record<string, unknown>): string | undefined {
   for (const value of Object.values(args)) {
     if (typeof value !== "string") continue;
@@ -164,9 +147,7 @@ export function collectRuntimeDisplaySources(
     : null;
   const sources: RuntimeDisplaySource[] = [];
   let citationIndex = 0;
-  const displayIndexes = new Map<string, number>();
   const seenCitationKeys = new Map<string, RuntimeDisplaySource>();
-  const seenDisplayKeys = new Set<string>();
   const consumedToolMessageIds = new Set<string>();
   const consumedToolMessages = new Set<Message>();
 
@@ -224,9 +205,7 @@ export function collectRuntimeDisplaySources(
           mode: effectiveMode,
           tableColumns: match?.display.tableColumns,
         })),
-        displayIndexes,
         seenCitationKeys,
-        seenDisplayKeys,
         () => ++citationIndex,
       );
     }
@@ -247,7 +226,7 @@ export function collectRuntimeDisplaySources(
       continue;
     }
     const toolName = extractToolMessageName(message);
-    const match = null;
+    const match = findDisplayConfigForPayload(toolName, result, displays);
     const effectiveMode = match?.display.mode ?? "citation";
     if (allowedModes && !allowedModes.has(effectiveMode)) {
       continue;
@@ -266,9 +245,7 @@ export function collectRuntimeDisplaySources(
         mode: effectiveMode,
         tableColumns: match?.display.tableColumns,
       })),
-      displayIndexes,
       seenCitationKeys,
-      seenDisplayKeys,
       () => ++citationIndex,
     );
   }
@@ -278,9 +255,7 @@ export function collectRuntimeDisplaySources(
 function appendDisplaySources(
   target: RuntimeDisplaySource[],
   drafts: RuntimeDisplaySourceDraft[],
-  displayIndexes: Map<string, number>,
   seenCitationKeys: Map<string, RuntimeDisplaySource>,
-  seenDisplayKeys: Set<string>,
   nextCitationIndex: () => number,
 ) {
   for (const draft of drafts) {
@@ -297,17 +272,9 @@ function appendDisplaySources(
       continue;
     }
 
-    const stableKey = nonCitationSourceKey(draft);
-    if (seenDisplayKeys.has(stableKey)) {
-      continue;
-    }
-    seenDisplayKeys.add(stableKey);
-    const displayKey = `${draft.skillName}:${draft.mode}`;
-    const displayIndex = (displayIndexes.get(displayKey) ?? 0) + 1;
-    displayIndexes.set(displayKey, displayIndex);
     target.push({
       ...draft,
-      index: displayIndex,
+      index: nextCitationIndex(),
     });
   }
 }
@@ -323,9 +290,6 @@ export function reindexRuntimeDisplaySources(
     globalSources.map((source) => [citationSourceKey(source), source]),
   );
   return sources.map((source) => {
-    if (source.mode !== "citation") {
-      return source;
-    }
     const global = globalByKey.get(citationSourceKey(source));
     return global
       ? {
@@ -361,10 +325,6 @@ function citationSourceKey(source: RuntimeDisplaySourceDraft): string {
   return normalizeCitationKey(fallback) || normalizeCitationKey(JSON.stringify(raw).slice(0, 300));
 }
 
-function nonCitationSourceKey(source: RuntimeDisplaySourceDraft): string {
-  return `${source.skillName}:${source.mode}:${citationSourceKey(source)}`;
-}
-
 function extractRuntimeToolCalls(message: Message): RuntimeToolCall[] {
   const calls: RuntimeToolCall[] = [];
   const direct = (message as { tool_calls?: unknown }).tool_calls;
@@ -441,20 +401,10 @@ function normalizeToolArgs(value: unknown): Record<string, unknown> | undefined
 
 export function findDisplayConfigForPayload(
   toolName: string,
-  payload: unknown,
+  _payload: unknown,
   displays: SkillDisplayMap,
 ): { skillName: string; display: SkillDisplayConfig } | null {
-  if (!canInspectPayloadForDisplay(toolName)) {
-    return null;
-  }
-  let best: { skillName: string; display: SkillDisplayConfig; score: number } | null = null;
-  for (const [skillName, display] of displays) {
-    const score = scoreDisplayPayloadMatch(payload, display);
-    if (score >= 3 && (!best || score > best.score)) {
-      best = { skillName, display, score };
-    }
-  }
-  return best ? { skillName: best.skillName, display: best.display } : null;
+  return findDisplayConfigForTool(toolName, displays);
 }
 
 export function isUnconfiguredSkillInvocation(
@@ -498,33 +448,6 @@ export function isDisplaySamplePayload(payload: unknown): boolean {
   );
 }
 
-function scoreDisplayPayloadMatch(payload: unknown, display: SkillDisplayConfig): number {
-  const items = getArrayByPath(payload, display.resultPath);
-  const first = items?.find((item): item is Record<string, unknown> => isRecord(item));
-  if (!first) {
-    return 0;
-  }
-  const fields = [
-    display.titleField,
-    display.summaryField,
-    display.contentField,
-    display.sourceField,
-    display.typeField,
-    display.timeField,
-    display.scoreField,
-    display.urlField,
-    display.idField,
-  ].filter((field): field is string => !!field);
-  return new Set(fields).size === 0
-    ? 0
-    : [...new Set(fields)].filter(
-        (field) =>
-          first[field] !== undefined &&
-          first[field] !== null &&
-          first[field] !== "",
-      ).length;
-}
-
 function getArrayByPath(payload: unknown, path: string): unknown[] | null {
   const value = path.split(".").reduce<unknown>((acc, key) => {
     if (acc && typeof acc === "object") {
@@ -589,14 +512,14 @@ export function applyInlineCitations(
   if (!content || sources.length === 0) {
     return content;
   }
-  const citationSources = sources.filter((source) => source.mode === "citation");
-  if (citationSources.length === 0) {
+  const referenceSources = sources.filter((source) => source.mode !== "none");
+  if (referenceSources.length === 0) {
     return content;
   }
-  const byIndex = new Map(citationSources.map((source) => [source.index, source]));
+  const byIndex = new Map(referenceSources.map((source) => [source.index, source]));
   const byUrl = new Map<string, RuntimeDisplaySource>();
   const byTitle = new Map<string, RuntimeDisplaySource>();
-  for (const source of citationSources) {
+  for (const source of referenceSources) {
     if (source.url) {
       byUrl.set(source.url, source);
     }
@@ -610,7 +533,7 @@ export function applyInlineCitations(
     byIndex,
     byUrl,
     byTitle,
-    citationSources,
+    referenceSources,
   );
 
   const markdownLinkPattern = /!?\[(?:[^\[\]]|\[[^\]]*\])*\]\([^)]+\)/g;
@@ -622,7 +545,7 @@ export function applyInlineCitations(
     const replacedSlice = replaceCitationTokens(
       normalized.slice(cursor, start),
       byIndex,
-      citationSources,
+      referenceSources,
     );
     if (replacedSlice !== normalized.slice(cursor, start)) {
       replaced = true;
@@ -631,7 +554,7 @@ export function applyInlineCitations(
     next += match[0];
     cursor = start + match[0].length;
   }
-  const tail = replaceCitationTokens(normalized.slice(cursor), byIndex, citationSources);
+  const tail = replaceCitationTokens(normalized.slice(cursor), byIndex, referenceSources);
   if (tail !== normalized.slice(cursor)) {
     replaced = true;
   }
@@ -639,7 +562,7 @@ export function applyInlineCitations(
   if (replaced || hasCitationMarkdown(next)) {
     return next;
   }
-  return appendCitationSummary(next, citationSources);
+  return appendCitationSummary(next, referenceSources);
 }
 
 function replaceCitationTokens(
diff --git a/frontend-web/src/core/threads/hooks.ts b/frontend-web/src/core/threads/hooks.ts
index f8f95307..3a0607ae 100644
--- a/frontend-web/src/core/threads/hooks.ts
+++ b/frontend-web/src/core/threads/hooks.ts
@@ -14,8 +14,8 @@ import { getStoredAuth } from "../auth";
 import { getBackendBaseURL } from "../config";
 import { useI18n } from "../i18n/hooks";
 import type { FileInMessage } from "../messages/utils";
-import type { LocalSettings } from "../settings";
-import { isThreadRagModeLocked, lockThreadRagMode, useLocalSettings } from "../settings";
+import type { LocalSettings } from "../settings";
+import { isThreadRagModeLocked, lockThreadRagMode, useLocalSettings } from "../settings";
 import { useUpdateSubtask } from "../tasks/context";
 import type { UploadedFileInfo } from "../uploads";
 import { promptInputFilePartToFile, uploadFiles } from "../uploads";
@@ -343,7 +343,7 @@ export function useThreadStream({
       if (isThreadNotAccessibleError(message)) {
         const userLabel = buildCurrentUserLabel();
         toast.info(
-          `当前登录用户为 ${userLabel}，原对话不存在或无权访问，已为你打开新对话。`,
+          `当前登录用户为 ${userLabel}，原对话不存在或无权访问，正在为你刷新页面…`,
         );
         // Prefer staying inside an agent chat context when the user is on an
         // agent thread URL — otherwise fall back to the global new chat.
@@ -352,7 +352,18 @@ export function useThreadStream({
         const target = agentMatch
           ? `/page/workspace/agents/${agentMatch[1]}/chats/new`
           : "/page/workspace/chats/new";
-        navigate(target, { replace: true });
+        // First navigate to a safe URL so the post-reload page lands on a
+        // valid route. Then full-reload so TanStack Query cache, context
+        // providers and any other state captured under the previous user's
+        // identity get rebuilt against the current login.
+        if (typeof window !== "undefined") {
+          window.location.hash = target;
+          window.setTimeout(() => {
+            window.location.reload();
+          }, 900);
+        } else {
+          navigate(target, { replace: true });
+        }
         return;
       }
       toast.error(message);
@@ -555,13 +566,13 @@ export function useThreadStream({
           }),
         );
 
-        const ragModeEnabled =
-          localSettings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
-        if (ragModeEnabled) {
-          lockThreadRagMode(threadId);
-        }
-
-        await thread.submit(
+        const ragModeEnabled =
+          localSettings.display.ragModeEnabled || isThreadRagModeLocked(threadId);
+        if (ragModeEnabled) {
+          lockThreadRagMode(threadId);
+        }
+
+        await thread.submit(
           {
             messages: [
               {
@@ -604,10 +615,10 @@ export function useThreadStream({
                       ? "low"
                       : undefined),
               memory_injection_enabled: context.memory_injection_enabled ?? true,
-              rag_mode_enabled: ragModeEnabled,
-              thread_id: threadId,
-            },
-          },
+              rag_mode_enabled: ragModeEnabled,
+              thread_id: threadId,
+            },
+          },
         );
         void queryClient.invalidateQueries({ queryKey: ["threads", "search"] });
       } catch (error) {
diff --git a/frontend-web/src/styles/globals.css b/frontend-web/src/styles/globals.css
index b91dcf12..7e8c0951 100644
--- a/frontend-web/src/styles/globals.css
+++ b/frontend-web/src/styles/globals.css
@@ -568,19 +568,6 @@
     }
   }
 
-  @keyframes reference-flash {
-    0% {
-      background: rgba(254, 243, 199, 0.95);
-      box-shadow: 0 0 0 4px rgba(251, 191, 36, 0.28);
-    }
-    70% {
-      background: rgba(254, 243, 199, 0.58);
-      box-shadow: 0 0 0 2px rgba(251, 191, 36, 0.14);
-    }
-    100% {
-      box-shadow: none;
-    }
-  }
 }
 
 /* ─── Tiptap writing editor ─────────────────────────────────────────────── */
diff --git a/offline-backend-20260512/backend/app/gateway/routers/threads.py b/offline-backend-20260512/backend/app/gateway/routers/threads.py
index 8d3a0e90..867c8730 100644
--- a/offline-backend-20260512/backend/app/gateway/routers/threads.py
+++ b/offline-backend-20260512/backend/app/gateway/routers/threads.py
@@ -19,16 +19,21 @@ from pathlib import Path
 import uuid
 from typing import Any
 
-from fastapi import APIRouter, HTTPException, Request
-from langgraph.checkpoint.base import empty_checkpoint
-from pydantic import BaseModel, Field, field_validator
-
-from app.gateway.authz import require_permission
-from app.gateway.deps import get_checkpointer
-from app.gateway.utils import sanitize_log_param
+from fastapi import APIRouter, HTTPException, Request
+from langgraph.checkpoint.base import empty_checkpoint
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+
+from app.gateway.authz import require_permission
+from app.gateway.deps import get_checkpointer
+from app.gateway.utils import sanitize_log_param
+from deerflow.config.extensions_config import SkillDisplayConfig
 from deerflow.config.paths import Paths, get_paths
+from deerflow.persistence.engine import get_engine, get_session_factory
+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_summary,
 )
@@ -81,11 +86,54 @@ def _rag_debug_file_path() -> str:
 def _log_rag_debug(message: str, *args: Any) -> None:
     logger.info(message, *args)
     _get_rag_debug_logger().info(message, *args)
-
-
-# ---------------------------------------------------------------------------
-# Response / request models
-# ---------------------------------------------------------------------------
+
+
+def _json_text_loads(value: str | None) -> dict[str, Any] | None:
+    if not value:
+        return None
+    try:
+        parsed = json.loads(value)
+        return parsed if isinstance(parsed, dict) else None
+    except Exception:
+        logger.debug("Failed to parse persisted skill display JSON", exc_info=True)
+        return None
+
+
+async def _load_persisted_skill_displays() -> dict[str, SkillDisplayConfig]:
+    engine = get_engine()
+    sf = get_session_factory()
+    if engine is None or sf is None:
+        return {}
+    try:
+        async with engine.begin() as conn:
+            await conn.run_sync(SkillDisplayAdapterRow.__table__.create, checkfirst=True)
+        async with sf() as session:
+            result = await session.execute(select(SkillDisplayAdapterRow))
+            displays: dict[str, SkillDisplayConfig] = {}
+            for row in result.scalars():
+                payload = _json_text_loads(row.display_config)
+                if payload is None:
+                    continue
+                try:
+                    display = SkillDisplayConfig.model_validate(payload)
+                except Exception:
+                    logger.debug(
+                        "Failed to validate persisted skill display for %s",
+                        row.skill_name,
+                        exc_info=True,
+                    )
+                    continue
+                if display.enabled and display.mode != "none":
+                    displays[row.skill_name] = display
+            return displays
+    except Exception:
+        logger.debug("Failed to load persisted skill display adapters", exc_info=True)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Response / request models
+# ---------------------------------------------------------------------------
 
 
 class ThreadDeleteResponse(BaseModel):
@@ -187,6 +235,7 @@ class ReferenceSourceResponse(BaseModel):
     url: str | None = None
     content: str | None = None
     score: float | None = None
+    tableColumns: list[dict[str, Any]] = Field(default_factory=list)
     raw: dict[str, Any] = Field(default_factory=dict)
 
 
@@ -795,10 +844,14 @@ async def get_thread_reference_batches(thread_id: str, request: Request) -> Refe
         )
         return ReferenceBatchesResponse(batches=[])
     raw_batches = build_runtime_reference_batches(messages)
+    persisted_displays = await _load_persisted_skill_displays()
+    if persisted_displays:
+        raw_batches = adapt_reference_batches_with_displays(raw_batches, persisted_displays)
     debug_summary = build_reference_debug_summary(messages, raw_batches)
     _log_rag_debug(
         "backend reference-batches thread=%s messages=%s turns=%s tool_messages=%s raw_items=%s "
-        "normalized_items=%s kept_items=%s batches=%s batch_sources=%s batch_ids=%s turns_detail=%s log_file=%s",
+        "normalized_items=%s kept_items=%s batches=%s batch_sources=%s batch_ids=%s "
+        "display_adapters=%s turns_detail=%s log_file=%s",
         sanitize_log_param(thread_id),
         debug_summary["messages"],
         debug_summary["turns"],
@@ -809,6 +862,7 @@ async def get_thread_reference_batches(thread_id: str, request: Request) -> Refe
         len(raw_batches),
         ",".join(str(batch.get("source_count", 0)) for batch in debug_summary["batches"]),
         ",".join(str(batch.get("id") or "") for batch in debug_summary["batches"]),
+        len(persisted_displays),
         json.dumps(debug_summary["turns_detail"], ensure_ascii=False),
         _rag_debug_file_path(),
     )
diff --git a/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py b/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py
index 9d9782f8..c8072b40 100644
--- a/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py
+++ b/offline-backend-20260512/backend/packages/harness/deerflow/runtime/references.py
@@ -3,7 +3,14 @@
 from __future__ import annotations
 
 import json
+import re
 from typing import Any
+from urllib.parse import quote
+
+from deerflow.config.extensions_config import SkillDisplayConfig, get_extensions_config
+
+
+_SKILL_PATH_RE = re.compile(r"[\\/]skills[\\/](?:public|custom)[\\/]([^\\/]+)(?:[\\/]|$)")
 
 
 def build_reference_batches(messages: list[Any]) -> list[dict[str, Any]]:
@@ -16,12 +23,10 @@ def build_reference_batches(messages: list[Any]) -> list[dict[str, Any]]:
             if _message_type(messages[cursor]) == "human":
                 end = cursor
                 break
-        assistant = _find_last_assistant_answer(messages, index + 1, end)
-        if assistant is None:
-            continue
         sources = _collect_sources(messages[index + 1 : end])
         if sources:
-            message_id = _message_id(assistant) or str(index)
+            anchor = _find_reference_batch_anchor(messages, index + 1, end)
+            message_id = _message_id(anchor) or _message_id(message) or str(index)
             batches.append(
                 {
                     "id": message_id,
@@ -39,7 +44,7 @@ def build_latest_reference_prompt(messages: list[Any]) -> tuple[str, dict[str, A
     sources = _collect_sources(messages[human_index + 1 :])
     if not sources:
         return "", None
-    assistant = _find_last_assistant_answer(messages, human_index + 1, len(messages))
+    assistant = _find_reference_batch_anchor(messages, human_index + 1, len(messages))
     message_id = _message_id(assistant) or _message_id(messages[human_index]) or str(human_index)
     batch = {
         "id": message_id,
@@ -152,14 +157,112 @@ def build_reference_debug_summary(messages: list[Any], batches: list[dict[str, A
     }
 
 
+def adapt_reference_batches_with_displays(
+    batches: list[dict[str, Any]],
+    displays: dict[str, SkillDisplayConfig | dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Apply persisted skill display configs to already-built reference batches.
+
+    The reference builder can run before the gateway has a fresh extensions
+    cache, while the skill adapter editor persists the user's latest mapping in
+    the database. This pass lets the API response use that DB-backed mapping
+    without changing citation indexes.
+    """
+    normalized_displays: dict[str, SkillDisplayConfig] = {}
+    for skill_name, display in displays.items():
+        try:
+            config = (
+                display
+                if isinstance(display, SkillDisplayConfig)
+                else SkillDisplayConfig.model_validate(display)
+            )
+        except Exception:
+            continue
+        if not config.enabled or config.mode == "none":
+            continue
+        normalized_displays[skill_name] = config
+
+    if not normalized_displays:
+        return batches
+
+    displays_by_normalized_name = {
+        _normalize_name(name): (name, display)
+        for name, display in normalized_displays.items()
+    }
+    adapted_batches: list[dict[str, Any]] = []
+    for batch in batches:
+        sources: list[dict[str, Any]] = []
+        for source in batch.get("sources", []):
+            if not isinstance(source, dict):
+                continue
+            skill_name = str(source.get("skillName") or "")
+            display = normalized_displays.get(skill_name)
+            if display is None:
+                normalized_source = _normalize_name(skill_name)
+                normalized_match = displays_by_normalized_name.get(normalized_source)
+                if normalized_match is None:
+                    for normalized_skill, candidate in displays_by_normalized_name.items():
+                        if (
+                            normalized_source.endswith(normalized_skill)
+                            or normalized_skill in normalized_source
+                        ):
+                            normalized_match = candidate
+                            break
+                if normalized_match is not None:
+                    skill_name, display = normalized_match
+            raw = source.get("raw")
+            if display is not None and isinstance(raw, dict):
+                index_value = int(source.get("index") or len(sources) + 1)
+                configured = _normalize_with_display_config(
+                    raw,
+                    index_value,
+                    skill_name,
+                    display,
+                )
+                if configured is not None:
+                    sources.append(
+                        {
+                            **source,
+                            **configured,
+                            "index": index_value,
+                            "skillName": skill_name,
+                            "raw": raw,
+                        }
+                    )
+                    continue
+            sources.append(source)
+        adapted_batches.append({**batch, "sources": sources})
+    return adapted_batches
+
+
 def _collect_sources(messages: list[Any]) -> list[dict[str, Any]]:
     sources: list[dict[str, Any]] = []
+    pending_tool_contexts: list[dict[str, Any]] = []
+    tool_contexts_by_id: dict[str, dict[str, Any]] = {}
     for message in messages:
-        if _message_type(message) != "tool":
+        message_type = _message_type(message)
+        if message_type == "ai":
+            for tool_call in _extract_tool_calls(message):
+                context = _build_tool_context(tool_call)
+                pending_tool_contexts.append(context)
+                if context.get("id"):
+                    tool_contexts_by_id[str(context["id"])] = context
             continue
+        if message_type != "tool":
+            continue
+        tool_context = _resolve_tool_context(
+            message,
+            pending_tool_contexts,
+            tool_contexts_by_id,
+        )
         payload = _extract_tool_payload(message)
         for raw_item in _first_list(payload):
-            normalized = _normalize_reference_item(raw_item, len(sources) + 1)
+            normalized = _normalize_reference_item(
+                raw_item,
+                len(sources) + 1,
+                payload=payload,
+                tool_context=tool_context,
+            )
             if not normalized:
                 continue
             normalized["index"] = len(sources) + 1
@@ -167,6 +270,17 @@ def _collect_sources(messages: list[Any]) -> list[dict[str, Any]]:
     return sources
 
 
+def _find_reference_batch_anchor(messages: list[Any], start: int, end: int) -> Any | None:
+    answer = _find_last_assistant_answer(messages, start, end)
+    if answer is not None:
+        return answer
+    for index in range(end - 1, start - 1, -1):
+        candidate = messages[index]
+        if _message_type(candidate) == "ai" and _message_id(candidate):
+            return candidate
+    return None
+
+
 def _find_last_assistant_answer(messages: list[Any], start: int, end: int) -> Any | None:
     for index in range(end - 1, start - 1, -1):
         candidate = messages[index]
@@ -174,7 +288,6 @@ def _find_last_assistant_answer(messages: list[Any], start: int, end: int) -> An
             _message_type(candidate) == "ai"
             and _message_id(candidate)
             and _has_answer_content(candidate)
-            and not _has_tool_calls(candidate)
         ):
             return candidate
     return None
@@ -195,6 +308,20 @@ def _message_content(message: Any) -> Any:
     return message.get("content") if isinstance(message, dict) else getattr(message, "content", None)
 
 
+def _message_name(message: Any) -> str:
+    if isinstance(message, dict):
+        return str(message.get("name") or (message.get("additional_kwargs") or {}).get("name") or "tool")
+    return str(getattr(message, "name", None) or "tool")
+
+
+def _message_tool_call_id(message: Any) -> str | None:
+    if isinstance(message, dict):
+        value = message.get("tool_call_id") or message.get("toolCallId")
+    else:
+        value = getattr(message, "tool_call_id", None) or getattr(message, "toolCallId", None)
+    return str(value) if value else None
+
+
 def _has_tool_calls(message: Any) -> bool:
     if isinstance(message, dict):
         direct = message.get("tool_calls")
@@ -221,6 +348,102 @@ def _has_answer_content(message: Any) -> bool:
     return False
 
 
+def _extract_tool_calls(message: Any) -> list[dict[str, Any]]:
+    candidates: list[Any] = []
+    if isinstance(message, dict):
+        for key in ("tool_calls", "tool_call_chunks"):
+            value = message.get(key)
+            if isinstance(value, list):
+                candidates.extend(value)
+        extra = (message.get("additional_kwargs") or {}).get("tool_calls")
+        if isinstance(extra, list):
+            candidates.extend(extra)
+    else:
+        for key in ("tool_calls", "tool_call_chunks"):
+            value = getattr(message, key, None)
+            if isinstance(value, list):
+                candidates.extend(value)
+        extra = (getattr(message, "additional_kwargs", None) or {}).get("tool_calls")
+        if isinstance(extra, list):
+            candidates.extend(extra)
+
+    calls: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    for raw in candidates:
+        call = _normalize_tool_call(raw)
+        if not call:
+            continue
+        call_id = str(call.get("id") or "")
+        if call_id and call_id in seen_ids:
+            continue
+        if call_id:
+            seen_ids.add(call_id)
+        calls.append(call)
+    return calls
+
+
+def _normalize_tool_call(raw: Any) -> dict[str, Any] | None:
+    if not isinstance(raw, dict):
+        return None
+    fn = raw.get("function") if isinstance(raw.get("function"), dict) else {}
+    name = raw.get("name") or fn.get("name") or raw.get("tool_name")
+    if not name:
+        return None
+    return {
+        "id": raw.get("id") or raw.get("tool_call_id") or raw.get("call_id"),
+        "name": str(name),
+        "args": _normalize_tool_args(raw.get("args") or raw.get("arguments") or fn.get("arguments")),
+    }
+
+
+def _normalize_tool_args(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+            if isinstance(parsed, dict):
+                return parsed
+        except Exception:
+            pass
+        return {"command": value}
+    return {}
+
+
+def _build_tool_context(tool_call: dict[str, Any]) -> dict[str, Any]:
+    tool_name = str(tool_call.get("name") or "tool")
+    args = tool_call.get("args") if isinstance(tool_call.get("args"), dict) else {}
+    return {
+        "id": tool_call.get("id"),
+        "tool_name": tool_name,
+        "args": args,
+        "skill_name": _infer_skill_name(tool_name, args),
+    }
+
+
+def _resolve_tool_context(
+    message: Any,
+    pending_tool_contexts: list[dict[str, Any]],
+    tool_contexts_by_id: dict[str, dict[str, Any]],
+) -> dict[str, Any]:
+    tool_call_id = _message_tool_call_id(message)
+    if tool_call_id and tool_call_id in tool_contexts_by_id:
+        context = tool_contexts_by_id[tool_call_id]
+        pending_tool_contexts[:] = [
+            item for item in pending_tool_contexts if str(item.get("id") or "") != tool_call_id
+        ]
+        return context
+    if pending_tool_contexts:
+        return pending_tool_contexts.pop(0)
+    tool_name = _message_name(message)
+    return {
+        "id": tool_call_id,
+        "tool_name": tool_name,
+        "args": {},
+        "skill_name": _infer_skill_name(tool_name, {}),
+    }
+
+
 def _extract_tool_payload(message: Any) -> Any:
     content = _message_content(message)
     if isinstance(content, dict):
@@ -316,9 +539,167 @@ def _pick(layers: list[dict[str, Any]], keys: tuple[str, ...]) -> str | None:
     return None
 
 
-def _normalize_reference_item(raw: Any, fallback_index: int) -> dict[str, Any] | None:
+def _enabled_skill_displays() -> dict[str, SkillDisplayConfig]:
+    try:
+        return {
+            name: state.display
+            for name, state in get_extensions_config().skills.items()
+            if state.display is not None
+            and state.enabled
+            and state.display.enabled
+            and state.display.mode != "none"
+        }
+    except Exception:
+        return {}
+
+
+def _infer_skill_name(tool_name: str, args: dict[str, Any]) -> str | None:
+    displays = _enabled_skill_displays()
+    if tool_name in displays:
+        return tool_name
+    normalized_tool = _normalize_name(tool_name)
+    for skill_name in displays:
+        normalized_skill = _normalize_name(skill_name)
+        if (
+            normalized_tool == normalized_skill
+            or normalized_tool.endswith(normalized_skill)
+            or normalized_skill in normalized_tool
+        ):
+            return skill_name
+    for value in args.values():
+        if not isinstance(value, str):
+            continue
+        match = _SKILL_PATH_RE.search(value)
+        if match:
+            return match.group(1)
+    return None
+
+
+def _resolve_display_match(
+    raw: dict[str, Any],
+    payload: Any,
+    tool_context: dict[str, Any] | None,
+) -> tuple[str, SkillDisplayConfig] | None:
+    displays = _enabled_skill_displays()
+    if not displays:
+        return None
+    skill_name = str((tool_context or {}).get("skill_name") or "")
+    display = displays.get(skill_name)
+    if display is not None:
+        return skill_name, display
+    tool_name = str((tool_context or {}).get("tool_name") or "")
+    inferred = _infer_skill_name(tool_name, (tool_context or {}).get("args") or {})
+    if inferred and inferred in displays:
+        return inferred, displays[inferred]
+    return None
+
+
+def _normalize_with_display_config(
+    raw: dict[str, Any],
+    fallback_index: int,
+    skill_name: str,
+    display: SkillDisplayConfig,
+) -> dict[str, Any] | None:
+    title = _stringify(_get_by_path(raw, display.title_field), f"结果 {fallback_index}")
+    snippet = _stringify(_get_by_path(raw, display.summary_field), "")
+    content = _stringify(_get_by_path(raw, display.content_field), snippet)
+    source = _stringify(_get_by_path(raw, display.source_field), "") or None
+    item_type = _stringify(_get_by_path(raw, display.type_field), "result") or "result"
+    time = _stringify(_get_by_path(raw, display.time_field), "") or None
+    item_id = _stringify(_get_by_path(raw, display.id_field), "") or None
+    score = _number_or_none(_get_by_path(raw, display.score_field))
+    url = _resolve_display_link(raw, display)
+    if not title and not content and not url:
+        return None
+    return {
+        "id": item_id or url,
+        "skillName": skill_name,
+        "mode": display.mode,
+        "title": title,
+        "type": item_type,
+        "snippet": snippet,
+        "content": content,
+        "source": source,
+        "time": time,
+        "url": url,
+        "score": score,
+        "tableColumns": [column.model_dump(by_alias=True) for column in display.table_columns],
+        "raw": raw,
+    }
+
+
+def _resolve_display_link(raw: dict[str, Any], display: SkillDisplayConfig) -> str | None:
+    url = _stringify(_get_by_path(raw, display.url_field), "")
+    item_id = _stringify(_get_by_path(raw, display.id_field), "")
+    if display.link_strategy == "url":
+        return url or None
+    if display.link_strategy == "id":
+        return _render_template(display.link_template, raw) if item_id and display.link_template else None
+    return url or (_render_template(display.link_template, raw) if item_id and display.link_template else None) or None
+
+
+def _render_template(template: str | None, raw: dict[str, Any]) -> str | None:
+    if not template:
+        return None
+
+    def replace(match: re.Match[str]) -> str:
+        value = _get_by_path(raw, match.group(1).strip())
+        return quote(_stringify(value, ""), safe="")
+
+    return re.sub(r"\{([^}]+)\}", replace, template)
+
+
+def _get_by_path(value: Any, path: str | None) -> Any:
+    if not path:
+        return None
+    cursor = value
+    for part in path.split("."):
+        if isinstance(cursor, dict):
+            cursor = cursor.get(part)
+        else:
+            return None
+    return cursor
+
+
+def _stringify(value: Any, fallback: str = "") -> str:
+    if value is None:
+        return fallback
+    if isinstance(value, (str, int, float)):
+        text = str(value).strip()
+        return text if text else fallback
+    return fallback
+
+
+def _number_or_none(value: Any) -> float | None:
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, str):
+        try:
+            return float(value)
+        except Exception:
+            return None
+    return None
+
+
+def _normalize_name(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "", name.lower())
+
+
+def _normalize_reference_item(
+    raw: Any,
+    fallback_index: int,
+    *,
+    payload: Any = None,
+    tool_context: dict[str, Any] | None = None,
+) -> dict[str, Any] | None:
     if not isinstance(raw, dict):
         return None
+    display_match = _resolve_display_match(raw, payload, tool_context)
+    if display_match is not None:
+        skill_name, display = display_match
+        configured = _normalize_with_display_config(raw, fallback_index, skill_name, display)
+        if configured is not None:
+            return configured
     layers = _nested_records(raw)
     title = _pick(layers, ("title", "m_title", "name", "question", "keyword", "query", "text"))
     content = _pick(layers, ("content", "page_content", "summary", "snippet", "description", "content_preview", "abstract", "body"))
@@ -341,7 +722,7 @@ def _normalize_reference_item(raw: Any, fallback_index: int) -> dict[str, Any] |
         return None
     return {
         "id": item_id or url,
-        "skillName": "backend-reference",
+        "skillName": str((tool_context or {}).get("skill_name") or (tool_context or {}).get("tool_name") or "backend-reference"),
         "mode": "citation",
         "title": title,
         "type": "result",