From c5852617b137e89c1b275d507f1488346d42f095 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 21:28:00 +0800
Subject: [PATCH 01/15] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E4=B8=AA?=
 =?UTF-8?q?=E4=BA=BA=E5=B7=A5=E4=BD=9C=E5=8C=BA=E9=A2=84=E8=A7=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增独立用户级 workspace 只读接口和工作区页面，支持文件列表浏览及宽屏内嵌/窄屏弹窗预览，便于后续扩展团队空间与知识库浏览。

Co-authored-by: Copilot <copilot@github.com>
---
 .../yuxi/services/workspace_service.py        | 124 +++++++
 backend/server/routers/__init__.py            |   2 +
 backend/server/routers/workspace_router.py    |  33 ++
 docs/develop-guides/roadmap.md                |   3 +
 web/src/apis/workspace_api.js                 |  26 ++
 web/src/assets/css/main.css                   |   1 -
 .../workspace/WorkspaceFileList.vue           | 213 +++++++++++
 .../workspace/WorkspacePreviewPane.vue        |  91 +++++
 .../components/workspace/WorkspaceSidebar.vue | 138 +++++++
 web/src/layouts/AppLayout.vue                 |   8 +
 web/src/router/index.js                       |  13 +
 web/src/views/WorkspaceView.vue               | 343 ++++++++++++++++++
 12 files changed, 994 insertions(+), 1 deletion(-)
 create mode 100644 backend/package/yuxi/services/workspace_service.py
 create mode 100644 backend/server/routers/workspace_router.py
 create mode 100644 web/src/apis/workspace_api.js
 create mode 100644 web/src/components/workspace/WorkspaceFileList.vue
 create mode 100644 web/src/components/workspace/WorkspacePreviewPane.vue
 create mode 100644 web/src/components/workspace/WorkspaceSidebar.vue
 create mode 100644 web/src/views/WorkspaceView.vue

diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
new file mode 100644
index 00000000..b4427b6b
--- /dev/null
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import asyncio
+import io
+import mimetypes
+from pathlib import Path, PurePosixPath
+from urllib.parse import quote
+
+from fastapi import HTTPException
+from fastapi.responses import FileResponse, StreamingResponse
+
+from yuxi.agents.backends.sandbox.paths import _global_user_data_dir
+from yuxi.services.viewer_filesystem_service import _detect_preview_type
+from yuxi.storage.postgres.models_business import User
+from yuxi.utils.datetime_utils import utc_isoformat_from_timestamp
+from yuxi.utils.paths import WORKSPACE_DIR_NAME
+
+
+def _workspace_root(user: User) -> Path:
+    try:
+        root = _global_user_data_dir(str(user.id)) / WORKSPACE_DIR_NAME
+    except ValueError as exc:
+        raise HTTPException(status_code=403, detail="Access denied") from exc
+    root.mkdir(parents=True, exist_ok=True)
+    return root.resolve()
+
+
+def _normalize_workspace_path(path: str | None) -> PurePosixPath:
+    raw_path = (path or "/").strip() or "/"
+    if not raw_path.startswith("/"):
+        raw_path = f"/{raw_path}"
+    normalized = PurePosixPath(raw_path)
+    if ".." in normalized.parts:
+        raise HTTPException(status_code=403, detail="Access denied")
+    return normalized
+
+
+def _resolve_workspace_path(user: User, path: str | None) -> Path:
+    root = _workspace_root(user)
+    normalized = _normalize_workspace_path(path)
+    relative_parts = [part for part in normalized.parts if part not in {"/", ""}]
+    target = (root.joinpath(*relative_parts) if relative_parts else root).resolve()
+    try:
+        target.relative_to(root)
+    except ValueError as exc:
+        raise HTTPException(status_code=403, detail="Access denied") from exc
+    return target
+
+
+def _entry_for_path(root: Path, path: Path) -> dict:
+    stat = path.stat()
+    is_dir = path.is_dir()
+    relative = path.relative_to(root).as_posix()
+    display_path = f"/{relative}" if relative else "/"
+    if is_dir and display_path != "/" and not display_path.endswith("/"):
+        display_path = f"{display_path}/"
+    return {
+        "path": display_path,
+        "name": path.name or "工作区",
+        "is_dir": is_dir,
+        "size": 0 if is_dir else stat.st_size,
+        "modified_at": utc_isoformat_from_timestamp(stat.st_mtime) or "",
+    }
+
+
+def _sort_entries(entries: list[dict]) -> list[dict]:
+    return sorted(entries, key=lambda item: (not bool(item.get("is_dir")), str(item.get("name") or "").lower()))
+
+
+def _list_directory(root: Path, target: Path) -> list[dict]:
+    entries = [_entry_for_path(root, child) for child in target.iterdir()]
+    return _sort_entries(entries)
+
+
+async def list_workspace_tree(*, path: str, current_user: User) -> dict:
+    root = _workspace_root(current_user)
+    target = _resolve_workspace_path(current_user, path)
+    if not target.exists():
+        return {"entries": []}
+    if not target.is_dir():
+        raise HTTPException(status_code=400, detail="当前路径不是目录")
+    entries = await asyncio.to_thread(_list_directory, root, target)
+    return {"entries": entries}
+
+
+async def read_workspace_file_content(*, path: str, current_user: User) -> dict:
+    target = _resolve_workspace_path(current_user, path)
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="文件不存在")
+    if not target.is_file():
+        raise HTTPException(status_code=400, detail="当前路径是目录")
+
+    raw_content = await asyncio.to_thread(target.read_bytes)
+    preview_type, supported, message = _detect_preview_type(path, raw_content)
+    if preview_type in {"image", "pdf"} or not supported:
+        return {
+            "content": None,
+            "preview_type": preview_type,
+            "supported": supported,
+            "message": message,
+        }
+    return {
+        "content": raw_content.decode("utf-8"),
+        "preview_type": preview_type,
+        "supported": supported,
+        "message": message,
+    }
+
+
+async def download_workspace_file(*, path: str, current_user: User) -> StreamingResponse | FileResponse:
+    target = _resolve_workspace_path(current_user, path)
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="文件不存在")
+    if not target.is_file():
+        raise HTTPException(status_code=400, detail="当前路径是目录")
+
+    file_name = target.name or "download"
+    media_type = mimetypes.guess_type(file_name)[0] or "application/octet-stream"
+    headers = {"Content-Disposition": f"attachment; filename*=UTF-8''{quote(file_name)}"}
+    if target.stat().st_size > 1024 * 1024 * 16:
+        return FileResponse(path=target, media_type=media_type, headers=headers)
+
+    content = await asyncio.to_thread(target.read_bytes)
+    return StreamingResponse(io.BytesIO(content), media_type=media_type, headers=headers)
diff --git a/backend/server/routers/__init__.py b/backend/server/routers/__init__.py
index 86112ec4..0413eea3 100644
--- a/backend/server/routers/__init__.py
+++ b/backend/server/routers/__init__.py
@@ -15,6 +15,7 @@
 from server.routers.tool_router import tools
 from server.routers.apikey_router import apikey_router
 from server.routers.filesystem_router import filesystem_router
+from server.routers.workspace_router import workspace
 
 _LITE_MODE = os.environ.get("LITE_MODE", "").lower() in ("true", "1")
 
@@ -36,6 +37,7 @@
 router.include_router(tools)  # /api/system/tools/* 工具列表与配置
 router.include_router(apikey_router)  # /api/apikey/* API Key 管理
 router.include_router(filesystem_router)  # /api/viewer/filesystem/* 工作台文件系统视图
+router.include_router(workspace)  # /api/workspace/* 用户个人工作区
 
 if not _LITE_MODE:
     from server.routers.graph_router import graph
diff --git a/backend/server/routers/workspace_router.py b/backend/server/routers/workspace_router.py
new file mode 100644
index 00000000..31c5472d
--- /dev/null
+++ b/backend/server/routers/workspace_router.py
@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, Query
+
+from server.utils.auth_middleware import get_required_user
+from yuxi.services.workspace_service import download_workspace_file, list_workspace_tree, read_workspace_file_content
+from yuxi.storage.postgres.models_business import User
+
+workspace = APIRouter(prefix="/workspace", tags=["workspace"])
+
+
+@workspace.get("/tree", response_model=dict)
+async def get_workspace_tree(
+    path: str = Query("/", description="工作区目录路径"),
+    current_user: User = Depends(get_required_user),
+):
+    return await list_workspace_tree(path=path, current_user=current_user)
+
+
+@workspace.get("/file", response_model=dict)
+async def get_workspace_file(
+    path: str = Query(..., description="工作区文件路径"),
+    current_user: User = Depends(get_required_user),
+):
+    return await read_workspace_file_content(path=path, current_user=current_user)
+
+
+@workspace.get("/download")
+async def download_workspace(
+    path: str = Query(..., description="工作区文件路径"),
+    current_user: User = Depends(get_required_user),
+):
+    return await download_workspace_file(path=path, current_user=current_user)
diff --git a/docs/develop-guides/roadmap.md b/docs/develop-guides/roadmap.md
index a969a546..6641ac7e 100644
--- a/docs/develop-guides/roadmap.md
+++ b/docs/develop-guides/roadmap.md
@@ -18,6 +18,8 @@
 - 完善 Skills 的环境变量注入
 - 拓宽检索的知识源，统一多知识源（channel），目前已知知识库/知识图谱/网页，可拓展：个人知识库、数据库、历史对话等
     - 前置任务，多知识库并行检索（扩展 query_kb）
+    - 新增 query_keywords 工具，专门用于基于关键词命中的排序，也结合词频（和 BM25 的区别？）
+- 评估
 
 ### Bugs
 - 目前的知识库的图片存在公开访问风险
@@ -35,6 +37,7 @@
 ### 0.6.2 开发记录
 
 <!-- 0.6.2 的内容请放在这里 -->
+- 新增个人工作区预览：提供独立于对话 thread 的用户级 workspace 只读 API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；知识库与团队空间入口先展示到占位层级。
 - 扩展管理界面交互逻辑重构：将 MCP / Subagents / Skills 三个标签页从「左侧边栏 + 右侧详情面板」布局重构为「卡片式网格布局 + 路由跳转二级页面」布局，工具标签页改为卡片网格布局 + 弹窗详情（保持弹窗内容不变）。新增共享组件 `ExtensionCard`、`ExtensionCardGrid`、`ExtensionToolbar`、`ExtensionDetailLayout`，详情页（`McpDetailView`、`SubagentDetailView`、`SkillDetailView`）使用居中宽度限制，路由规划为 `/extensions/mcp/:name`、`/extensions/subagent/:name`、`/extensions/skill/:slug`。
 - 统一卡片样式：`ExtensionCard` 新增 `tags` prop 支持传入 `[{label, color}]` 数组，内部使用 `<a-tag bordered=false size=small>` 渲染，与知识库卡片标签风格统一；知识库列表页 `DataBaseView` 改用 `ExtensionCard` + `ExtensionCardGrid` 替代原有自定义卡片，移除冗余 card 样式。
 - 调整应用主导航：`AppLayout` 从默认窄栏升级为默认展开的侧边栏，保留折叠态图标导航；侧边栏样式收敛为 14px 文本 + 18px 图标的标准紧凑密度，并统一导航项、任务中心、GitHub、用户信息的图标与文字对齐。折叠态改为仅通过显式按钮展开，避免空白区域误触发。
diff --git a/web/src/apis/workspace_api.js b/web/src/apis/workspace_api.js
new file mode 100644
index 00000000..37519b5e
--- /dev/null
+++ b/web/src/apis/workspace_api.js
@@ -0,0 +1,26 @@
+import { apiGet } from './base'
+
+const buildQuery = (params) => {
+  const query = new URLSearchParams()
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== undefined && value !== null && value !== '') {
+      query.set(key, String(value))
+    }
+  })
+  return query.toString()
+}
+
+export const getWorkspaceTree = (path = '/') => {
+  const query = buildQuery({ path })
+  return apiGet(`/api/workspace/tree?${query}`)
+}
+
+export const getWorkspaceFileContent = (path) => {
+  const query = buildQuery({ path })
+  return apiGet(`/api/workspace/file?${query}`)
+}
+
+export const downloadWorkspaceFile = (path) => {
+  const query = buildQuery({ path })
+  return apiGet(`/api/workspace/download?${query}`, {}, true, 'blob')
+}
diff --git a/web/src/assets/css/main.css b/web/src/assets/css/main.css
index df6d4255..16b51757 100644
--- a/web/src/assets/css/main.css
+++ b/web/src/assets/css/main.css
@@ -39,7 +39,6 @@ body {
 
 .layout-container {
   width: 100%;
-  padding: 0 var(--page-padding);
 
   h2 {
     margin: 20px 0 10px 0;
diff --git a/web/src/components/workspace/WorkspaceFileList.vue b/web/src/components/workspace/WorkspaceFileList.vue
new file mode 100644
index 00000000..2f492001
--- /dev/null
+++ b/web/src/components/workspace/WorkspaceFileList.vue
@@ -0,0 +1,213 @@
+<template>
+  <section class="workspace-file-list">
+    <div class="file-list-header">
+      <div class="path-line">
+        <button
+          type="button"
+          class="path-action"
+          :disabled="currentPath === '/'"
+          aria-label="返回上级目录"
+          @click="$emit('go-parent')"
+        >
+          <ChevronLeft :size="16" />
+        </button>
+        <span class="path-text" :title="currentPath">{{ currentPath }}</span>
+      </div>
+      <span class="entry-count">{{ entries.length }} 项</span>
+    </div>
+
+    <div class="file-table" role="table" aria-label="工作区文件列表">
+      <div class="file-row table-head" role="row">
+        <span>名称</span>
+        <span>大小</span>
+        <span>修改时间</span>
+      </div>
+      <button
+        v-for="entry in entries"
+        :key="entry.path"
+        type="button"
+        class="file-row"
+        :class="{ selected: selectedPath === entry.path }"
+        role="row"
+        @click="$emit('select-entry', entry)"
+      >
+        <span class="name-cell">
+          <Folder v-if="entry.is_dir" :size="17" class="folder-icon" />
+          <component
+            v-else
+            :is="getFileIcon(entry.path)"
+            :style="{ color: getFileIconColor(entry.path), fontSize: '16px' }"
+          />
+          <span class="entry-name" :title="entry.name">{{ entry.name }}</span>
+        </span>
+        <span>{{ entry.is_dir ? '-' : formatFileSize(entry.size) }}</span>
+        <span>{{ formatRelativeTime(entry.modified_at) }}</span>
+      </button>
+    </div>
+
+    <div v-if="loading" class="list-state">
+      <a-spin />
+      <span>正在加载文件...</span>
+    </div>
+    <a-empty v-else-if="!entries.length" class="list-empty" description="当前文件夹为空" />
+  </section>
+</template>
+
+<script setup>
+import { ChevronLeft, Folder } from 'lucide-vue-next'
+import { formatFileSize, formatRelativeTime, getFileIcon, getFileIconColor } from '@/utils/file_utils'
+
+defineProps({
+  entries: { type: Array, default: () => [] },
+  currentPath: { type: String, default: '/' },
+  selectedPath: { type: String, default: '' },
+  loading: { type: Boolean, default: false }
+})
+
+defineEmits(['select-entry', 'go-parent'])
+</script>
+
+<style scoped lang="less">
+.workspace-file-list {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  background: var(--gray-0);
+}
+
+.file-list-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  min-height: 44px;
+  padding: 0 14px;
+  border-bottom: 1px solid var(--gray-100);
+}
+
+.path-line {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  gap: 8px;
+}
+
+.path-action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  border: 1px solid var(--gray-150);
+  border-radius: 8px;
+  background: var(--gray-0);
+  color: var(--gray-600);
+  cursor: pointer;
+
+  &:disabled {
+    color: var(--gray-300);
+    cursor: not-allowed;
+  }
+
+  &:hover:not(:disabled) {
+    background: var(--main-20);
+    color: var(--main-color);
+  }
+}
+
+.path-text {
+  min-width: 0;
+  overflow: hidden;
+  color: var(--gray-900);
+  font-size: 14px;
+  font-weight: 600;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.entry-count {
+  flex: 0 0 auto;
+  color: var(--gray-500);
+  font-size: 12px;
+}
+
+.file-table {
+  min-height: 0;
+  overflow-y: auto;
+}
+
+.file-row {
+  display: grid;
+  grid-template-columns: minmax(160px, 1fr) 86px 130px;
+  align-items: center;
+  gap: 12px;
+  width: 100%;
+  min-height: 38px;
+  padding: 0 14px;
+  border: 0;
+  border-bottom: 1px solid var(--gray-50);
+  background: transparent;
+  color: var(--gray-700);
+  font-size: 13px;
+  text-align: left;
+
+  &:not(.table-head) {
+    cursor: pointer;
+  }
+
+  &:hover:not(.table-head),
+  &.selected {
+    background: var(--main-20);
+    color: var(--gray-1000);
+  }
+
+  &.selected {
+    box-shadow: inset 3px 0 0 var(--main-color);
+  }
+}
+
+.table-head {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  min-height: 34px;
+  background: var(--gray-25);
+  color: var(--gray-500);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.name-cell {
+  display: flex;
+  align-items: center;
+  min-width: 0;
+  gap: 8px;
+}
+
+.folder-icon {
+  color: var(--main-500);
+  fill: var(--main-500);
+  fill-opacity: 0.16;
+}
+
+.entry-name {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.list-state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: 180px;
+  color: var(--gray-500);
+}
+
+.list-empty {
+  margin-top: 48px;
+}
+</style>
diff --git a/web/src/components/workspace/WorkspacePreviewPane.vue b/web/src/components/workspace/WorkspacePreviewPane.vue
new file mode 100644
index 00000000..3c0b172f
--- /dev/null
+++ b/web/src/components/workspace/WorkspacePreviewPane.vue
@@ -0,0 +1,91 @@
+<template>
+  <aside class="workspace-preview-pane">
+    <AgentFilePreview
+      v-if="file"
+      :file="file"
+      :file-path="filePath"
+      :show-download="false"
+      :show-fullscreen="true"
+      :full-height="true"
+      container-class="workspace-preview-container"
+      content-class="workspace-preview-content"
+    />
+    <div v-else-if="loading" class="preview-state">
+      <a-spin />
+      <span>正在加载预览...</span>
+    </div>
+    <div v-else class="preview-empty">
+      <FileSearch :size="28" />
+      <h3>选择文件以预览</h3>
+      <p>支持 Markdown、文本、代码、图片与 PDF 的只读预览。</p>
+    </div>
+  </aside>
+</template>
+
+<script setup>
+import { FileSearch } from 'lucide-vue-next'
+import AgentFilePreview from '@/components/AgentFilePreview.vue'
+
+defineProps({
+  file: { type: Object, default: null },
+  filePath: { type: String, default: '' },
+  loading: { type: Boolean, default: false }
+})
+</script>
+
+<style scoped lang="less">
+.workspace-preview-pane {
+  min-width: 0;
+  min-height: 0;
+  border-left: 1px solid var(--gray-100);
+  background: var(--gray-0);
+  overflow: hidden;
+}
+
+:deep(.workspace-preview-container) {
+  height: 100%;
+  border-radius: 0;
+}
+
+:deep(.workspace-preview-content) {
+  flex: 1 1 auto;
+  max-height: none;
+  min-height: 0;
+}
+
+.preview-state,
+.preview-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  min-height: 260px;
+  padding: 24px;
+  color: var(--gray-500);
+  text-align: center;
+}
+
+.preview-state {
+  gap: 10px;
+}
+
+.preview-empty {
+  gap: 8px;
+
+  h3 {
+    margin: 6px 0 0;
+    color: var(--gray-800);
+    font-size: 15px;
+    font-weight: 600;
+  }
+
+  p {
+    max-width: 240px;
+    margin: 0;
+    color: var(--gray-500);
+    font-size: 13px;
+    line-height: 1.6;
+  }
+}
+</style>
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
new file mode 100644
index 00000000..5d90bfe5
--- /dev/null
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -0,0 +1,138 @@
+<template>
+  <aside class="workspace-sidebar">
+    <section class="sidebar-section">
+      <button
+        type="button"
+        class="workspace-nav-item"
+        :class="{ active: activeKey === 'personal' }"
+        @click="$emit('select-personal')"
+      >
+        <FolderKanban :size="16" />
+        <span>个人工作区</span>
+      </button>
+    </section>
+
+    <section class="sidebar-section">
+      <div class="section-title">知识库</div>
+      <button
+        v-for="database in databases"
+        :key="database.db_id || database.id || database.name"
+        type="button"
+        class="workspace-nav-item secondary"
+        :class="{ active: activeKey === `database:${database.db_id}` }"
+        @click="$emit('select-database', database)"
+      >
+        <LibraryBig :size="15" />
+        <span>{{ database.name }}</span>
+      </button>
+      <div v-if="loadingDatabases" class="sidebar-muted">正在加载知识库...</div>
+      <div v-else-if="!databases.length" class="sidebar-muted">暂无可访问知识库</div>
+    </section>
+
+    <section class="sidebar-section">
+      <div class="section-title">共享空间</div>
+      <button type="button" class="workspace-nav-item secondary disabled" disabled>
+        <UsersRound :size="15" />
+        <span>团队工作区</span>
+        <span class="soon-tag">即将支持</span>
+      </button>
+    </section>
+  </aside>
+</template>
+
+<script setup>
+import { FolderKanban, LibraryBig, UsersRound } from 'lucide-vue-next'
+
+defineProps({
+  activeKey: { type: String, default: 'personal' },
+  databases: { type: Array, default: () => [] },
+  loadingDatabases: { type: Boolean, default: false }
+})
+
+defineEmits(['select-personal', 'select-database'])
+</script>
+
+<style scoped lang="less">
+.workspace-sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  min-width: 0;
+  padding: 14px calc(var(--page-padding) - 8px);
+  border-right: 1px solid var(--gray-100);
+  background: var(--gray-25);
+  overflow-y: auto;
+}
+
+.sidebar-section {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.section-title {
+  padding: 0 8px;
+  color: var(--gray-500);
+  font-size: 12px;
+  font-weight: 600;
+  line-height: 20px;
+}
+
+.workspace-nav-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  min-height: 36px;
+  padding: 0 10px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  background: transparent;
+  color: var(--gray-700);
+  font-size: 14px;
+  text-align: left;
+  cursor: pointer;
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease,
+    border-color 0.2s ease;
+
+  span:first-of-type {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &:hover:not(:disabled),
+  &.active {
+    border-color: transparent;
+    background: var(--main-20);
+    color: var(--main-color);
+  }
+
+  &.secondary {
+    min-height: 32px;
+    font-size: 13px;
+  }
+
+  &.disabled {
+    color: var(--gray-400);
+    cursor: not-allowed;
+  }
+}
+
+.soon-tag {
+  flex: 0 0 auto;
+  margin-left: auto;
+  color: var(--gray-400);
+  font-size: 11px;
+}
+
+.sidebar-muted {
+  padding: 6px 8px;
+  color: var(--gray-500);
+  font-size: 12px;
+  line-height: 1.5;
+}
+</style>
diff --git a/web/src/layouts/AppLayout.vue b/web/src/layouts/AppLayout.vue
index e6d17ced..f5520446 100644
--- a/web/src/layouts/AppLayout.vue
+++ b/web/src/layouts/AppLayout.vue
@@ -8,6 +8,7 @@ import {
   ClipboardList,
   Blocks,
   Box,
+  FolderKanban,
   PanelLeftClose,
   PanelLeftOpen,
   MessageCirclePlus
@@ -131,6 +132,13 @@ const mainList = computed(() => {
     }
   ]
 
+  items.push({
+    name: '工作区',
+    path: '/workspace',
+    icon: FolderKanban,
+    activeIcon: FolderKanban
+  })
+
   if (userStore.isAdmin) {
     if (!isLiteMode) {
       items.push({
diff --git a/web/src/router/index.js b/web/src/router/index.js
index 6de4557f..8ab901c6 100644
--- a/web/src/router/index.js
+++ b/web/src/router/index.js
@@ -51,6 +51,19 @@ const router = createRouter({
         }
       ]
     },
+    {
+      path: '/workspace',
+      name: 'workspace',
+      component: AppLayout,
+      children: [
+        {
+          path: '',
+          name: 'WorkspaceComp',
+          component: () => import('../views/WorkspaceView.vue'),
+          meta: { keepAlive: true, requiresAuth: true }
+        }
+      ]
+    },
     {
       path: '/graph',
       name: 'graph',
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
new file mode 100644
index 00000000..045d0bf7
--- /dev/null
+++ b/web/src/views/WorkspaceView.vue
@@ -0,0 +1,343 @@
+<template>
+  <div class="workspace-view layout-container">
+    <PageHeader title="工作区" :loading="loadingTree || loadingPreview" :show-border="true">
+      <template #info>
+        <span class="workspace-info">个人文件的只读预览空间</span>
+      </template>
+      <template #actions>
+        <a-tooltip title="即将支持">
+          <a-button type="primary" disabled>新建文件夹</a-button>
+        </a-tooltip>
+      </template>
+    </PageHeader>
+
+    <div class="workspace-shell">
+      <WorkspaceSidebar
+        :active-key="activeSourceKey"
+        :databases="databases"
+        :loading-databases="loadingDatabases"
+        @select-personal="selectPersonalWorkspace"
+        @select-database="selectDatabase"
+      />
+
+      <main
+        ref="workspaceMainRef"
+        class="workspace-main"
+        :class="{ 'is-inline-preview': useInlinePreview }"
+      >
+        <template v-if="activeSourceKey === 'personal'">
+          <WorkspaceFileList
+            :entries="filteredEntries"
+            :current-path="currentPath"
+            :selected-path="selectedEntry?.path || ''"
+            :loading="loadingTree"
+            @select-entry="handleSelectEntry"
+            @go-parent="goParentDirectory"
+          />
+          <WorkspacePreviewPane
+            v-if="useInlinePreview"
+            :file="previewFile"
+            :file-path="selectedEntry?.path || ''"
+            :loading="loadingPreview"
+          />
+        </template>
+
+        <div v-else class="workspace-placeholder">
+          <LibraryBig :size="32" />
+          <h2>{{ selectedDatabase?.name || '知识库' }}</h2>
+          <p>当前版本仅展示可访问知识库到列表级别，知识库文件浏览后续支持。</p>
+        </div>
+      </main>
+    </div>
+
+    <a-modal
+      :open="previewModalVisible && !useInlinePreview"
+      width="880px"
+      :style="{ maxWidth: '92vw', top: '5vh' }"
+      :bodyStyle="{ maxHeight: '90vh', overflow: 'auto' }"
+      :footer="null"
+      :closable="false"
+      wrapClassName="workspace-file-preview-modal"
+      @cancel="closePreview"
+    >
+      <AgentFilePreview
+        :file="previewFile"
+        :filePath="selectedEntry?.path || ''"
+        :showClose="true"
+        :showDownload="false"
+        :showFullscreen="true"
+        @close="closePreview"
+      />
+    </a-modal>
+  </div>
+</template>
+
+<script setup>
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
+import { message } from 'ant-design-vue'
+import { LibraryBig } from 'lucide-vue-next'
+import PageHeader from '@/components/shared/PageHeader.vue'
+import AgentFilePreview from '@/components/AgentFilePreview.vue'
+import WorkspaceFileList from '@/components/workspace/WorkspaceFileList.vue'
+import WorkspacePreviewPane from '@/components/workspace/WorkspacePreviewPane.vue'
+import WorkspaceSidebar from '@/components/workspace/WorkspaceSidebar.vue'
+import { databaseApi } from '@/apis/knowledge_api'
+import { downloadWorkspaceFile, getWorkspaceFileContent, getWorkspaceTree } from '@/apis/workspace_api'
+
+const activeSourceKey = ref('personal')
+const currentPath = ref('/')
+const entries = ref([])
+const selectedEntry = ref(null)
+const previewFile = ref(null)
+const previewObjectUrl = ref('')
+const previewModalVisible = ref(false)
+const loadingTree = ref(false)
+const loadingPreview = ref(false)
+const loadingDatabases = ref(false)
+const databases = ref([])
+const selectedDatabase = ref(null)
+const searchQuery = ref('')
+const workspaceMainRef = ref(null)
+const workspaceMainWidth = ref(0)
+const INLINE_PREVIEW_MIN_WIDTH = 960
+
+const useInlinePreview = computed(() => workspaceMainWidth.value >= INLINE_PREVIEW_MIN_WIDTH)
+
+const filteredEntries = computed(() => {
+  const keyword = searchQuery.value.trim().toLowerCase()
+  if (!keyword) return entries.value
+  return entries.value.filter((entry) => String(entry.name || '').toLowerCase().includes(keyword))
+})
+
+const revokePreviewObjectUrl = () => {
+  if (!previewObjectUrl.value) return
+  URL.revokeObjectURL(previewObjectUrl.value)
+  previewObjectUrl.value = ''
+}
+
+const normalizePreviewFile = async (entry, response) => {
+  const previewType = response.preview_type || response.previewType || 'text'
+  const file = {
+    ...response,
+    previewType,
+    supported: response.supported !== false
+  }
+
+  if (previewType === 'image' || previewType === 'pdf') {
+    const blob = await downloadWorkspaceFile(entry.path)
+    revokePreviewObjectUrl()
+    previewObjectUrl.value = URL.createObjectURL(blob)
+    file.previewUrl = previewObjectUrl.value
+  }
+
+  return file
+}
+
+const loadWorkspaceEntries = async (path = '/') => {
+  loadingTree.value = true
+  try {
+    const response = await getWorkspaceTree(path)
+    entries.value = response.entries || []
+    currentPath.value = path
+  } catch (error) {
+    console.warn('加载工作区目录失败:', error)
+    message.error('加载工作区目录失败')
+  } finally {
+    loadingTree.value = false
+  }
+}
+
+const loadDatabases = async () => {
+  loadingDatabases.value = true
+  try {
+    const response = await databaseApi.getAccessibleDatabases()
+    databases.value = response?.databases || []
+  } catch (error) {
+    console.warn('加载可访问知识库失败:', error)
+    databases.value = []
+  } finally {
+    loadingDatabases.value = false
+  }
+}
+
+const selectPersonalWorkspace = async () => {
+  activeSourceKey.value = 'personal'
+  selectedDatabase.value = null
+  if (!entries.value.length) {
+    await loadWorkspaceEntries(currentPath.value)
+  }
+}
+
+const selectDatabase = (database) => {
+  selectedDatabase.value = database
+  activeSourceKey.value = `database:${database.db_id}`
+}
+
+const handleSelectEntry = async (entry) => {
+  if (entry.is_dir) {
+    closePreview()
+    await loadWorkspaceEntries(entry.path)
+    return
+  }
+
+  selectedEntry.value = entry
+  revokePreviewObjectUrl()
+  previewFile.value = {
+    ...entry,
+    content: 'Loading...',
+    supported: true,
+    previewType: 'text',
+    message: '',
+    previewUrl: ''
+  }
+  previewModalVisible.value = !useInlinePreview.value
+  loadingPreview.value = true
+  try {
+    const response = await getWorkspaceFileContent(entry.path)
+    previewFile.value = await normalizePreviewFile(entry, response)
+  } catch (error) {
+    console.warn('加载文件预览失败:', error)
+    previewFile.value = {
+      ...entry,
+      content: `Error loading file: ${error?.message || 'unknown error'}`,
+      supported: false,
+      previewType: 'unsupported',
+      message: error?.message || '文件预览失败',
+      previewUrl: ''
+    }
+    message.error('加载文件预览失败')
+  } finally {
+    loadingPreview.value = false
+  }
+}
+
+const closePreview = () => {
+  previewModalVisible.value = false
+  selectedEntry.value = null
+  previewFile.value = null
+  revokePreviewObjectUrl()
+}
+
+const goParentDirectory = async () => {
+  if (currentPath.value === '/') return
+  const trimmed = currentPath.value.replace(/\/$/, '')
+  const parent = trimmed.slice(0, trimmed.lastIndexOf('/')) || '/'
+  closePreview()
+  await loadWorkspaceEntries(parent)
+}
+
+let workspaceResizeObserver = null
+
+onMounted(async () => {
+  await Promise.all([loadWorkspaceEntries('/'), loadDatabases()])
+
+  if (workspaceMainRef.value && typeof ResizeObserver !== 'undefined') {
+    workspaceMainWidth.value = workspaceMainRef.value.clientWidth || 0
+    workspaceResizeObserver = new ResizeObserver((entries) => {
+      const entry = entries[0]
+      if (!entry) return
+      workspaceMainWidth.value = entry.contentRect.width
+    })
+    workspaceResizeObserver.observe(workspaceMainRef.value)
+  }
+})
+
+onUnmounted(() => {
+  workspaceResizeObserver?.disconnect()
+  workspaceResizeObserver = null
+  revokePreviewObjectUrl()
+})
+
+watch(useInlinePreview, (isInline) => {
+  if (!previewFile.value) {
+    previewModalVisible.value = false
+    return
+  }
+  previewModalVisible.value = !isInline
+})
+</script>
+
+<style scoped lang="less">
+.workspace-view {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+}
+
+.workspace-info {
+  color: var(--gray-500);
+  font-size: 13px;
+}
+
+.workspace-shell {
+  display: grid;
+  grid-template-columns: clamp(210px, 18vw, 280px) minmax(0, 1fr);
+  flex: 1 1 auto;
+  min-height: 0;
+  // margin: 16px var(--page-padding) var(--page-padding);
+  // border: 1px solid var(--gray-100);
+  // border-radius: 12px;
+  background: var(--gray-0);
+  overflow: hidden;
+}
+
+.workspace-main {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr);
+  min-width: 0;
+  min-height: 0;
+}
+
+.workspace-main.is-inline-preview {
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+}
+
+.workspace-placeholder {
+  grid-column: 1 / -1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  min-height: 360px;
+  padding: 32px;
+  color: var(--gray-500);
+  text-align: center;
+
+  h2 {
+    margin: 8px 0 0;
+    color: var(--gray-900);
+    font-size: 18px;
+    font-weight: 600;
+  }
+
+  p {
+    max-width: 360px;
+    margin: 0;
+    font-size: 14px;
+    line-height: 1.6;
+  }
+}
+
+</style>
+
+<style lang="less">
+.workspace-file-preview-modal {
+  .ant-modal {
+    z-index: 1050;
+
+    .ant-modal-content {
+      padding: 0;
+      overflow: hidden;
+      border: 1px solid var(--gray-200);
+      border-radius: 8px;
+      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+    }
+
+    .ant-modal-body {
+      padding: 0;
+    }
+  }
+}
+</style>

From 35f09f0bc8681e43a8e7acd48043799baa131e7b Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 22:07:48 +0800
Subject: [PATCH 02/15] =?UTF-8?q?feat:=20=E5=AE=8C=E5=96=84=E5=B7=A5?=
 =?UTF-8?q?=E4=BD=9C=E5=8C=BA=E6=96=87=E4=BB=B6=E7=AE=A1=E7=90=86=E8=83=BD?=
 =?UTF-8?q?=E5=8A=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../yuxi/services/workspace_service.py        |  97 ++++-
 backend/server/routers/workspace_router.py    |  46 +-
 docs/develop-guides/roadmap.md                |   2 +-
 web/src/apis/workspace_api.js                 |  21 +-
 .../workspace/WorkspaceFileList.vue           | 192 ++++++++-
 .../components/workspace/WorkspaceSidebar.vue |   2 +-
 web/src/views/WorkspaceView.vue               | 400 ++++++++++++++++--
 7 files changed, 712 insertions(+), 48 deletions(-)

diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
index b4427b6b..081e218d 100644
--- a/backend/package/yuxi/services/workspace_service.py
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -1,12 +1,15 @@
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import io
 import mimetypes
+import shutil
 from pathlib import Path, PurePosixPath
 from urllib.parse import quote
 
-from fastapi import HTTPException
+import aiofiles
+from fastapi import HTTPException, UploadFile
 from fastapi.responses import FileResponse, StreamingResponse
 
 from yuxi.agents.backends.sandbox.paths import _global_user_data_dir
@@ -67,6 +70,37 @@ def _sort_entries(entries: list[dict]) -> list[dict]:
     return sorted(entries, key=lambda item: (not bool(item.get("is_dir")), str(item.get("name") or "").lower()))
 
 
+def _validate_child_name(name: str, *, field_name: str) -> str:
+    clean_name = str(name or "").strip()
+    if not clean_name:
+        raise HTTPException(status_code=422, detail=f"{field_name} 不能为空")
+    if clean_name in {".", ".."} or "/" in clean_name or "\\" in clean_name:
+        raise HTTPException(status_code=422, detail=f"{field_name} 不能包含路径分隔符")
+    if PurePosixPath(clean_name).name != clean_name:
+        raise HTTPException(status_code=422, detail=f"{field_name} 不能包含路径分隔符")
+    return clean_name
+
+
+def _resolve_parent_directory(user: User, parent_path: str) -> Path:
+    parent = _resolve_workspace_path(user, parent_path)
+    if not parent.exists():
+        raise HTTPException(status_code=404, detail="目标目录不存在")
+    if not parent.is_dir():
+        raise HTTPException(status_code=400, detail="目标路径不是目录")
+    return parent
+
+
+def _resolve_new_child(root: Path, parent: Path, name: str) -> Path:
+    target = parent / name
+    try:
+        target.resolve(strict=False).relative_to(root)
+    except ValueError as exc:
+        raise HTTPException(status_code=403, detail="Access denied") from exc
+    if target.exists():
+        raise HTTPException(status_code=400, detail="同名文件或文件夹已存在")
+    return target
+
+
 def _list_directory(root: Path, target: Path) -> list[dict]:
     entries = [_entry_for_path(root, child) for child in target.iterdir()]
     return _sort_entries(entries)
@@ -107,6 +141,67 @@ async def read_workspace_file_content(*, path: str, current_user: User) -> dict:
     }
 
 
+async def delete_workspace_path(*, path: str, current_user: User) -> dict:
+    root = _workspace_root(current_user)
+    target = _resolve_workspace_path(current_user, path)
+    if target == root:
+        raise HTTPException(status_code=400, detail="工作区根目录不允许删除")
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="文件不存在")
+
+    try:
+        if target.is_dir():
+            await asyncio.to_thread(shutil.rmtree, target)
+        else:
+            await asyncio.to_thread(target.unlink)
+    except PermissionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {"success": True, "path": _normalize_workspace_path(path).as_posix()}
+
+
+async def create_workspace_directory(*, parent_path: str, name: str, current_user: User) -> dict:
+    root = _workspace_root(current_user)
+    directory_name = _validate_child_name(name, field_name="文件夹名")
+    parent = _resolve_parent_directory(current_user, parent_path)
+    target = _resolve_new_child(root, parent, directory_name)
+
+    try:
+        await asyncio.to_thread(target.mkdir)
+    except FileExistsError as exc:
+        raise HTTPException(status_code=400, detail="同名文件或文件夹已存在") from exc
+    except PermissionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {"success": True, "entry": _entry_for_path(root, target)}
+
+
+async def upload_workspace_file(*, parent_path: str, file: UploadFile, current_user: User) -> dict:
+    root = _workspace_root(current_user)
+    file_name = _validate_child_name(Path(file.filename or "").name, field_name="文件名")
+    parent = _resolve_parent_directory(current_user, parent_path)
+    target = _resolve_new_child(root, parent, file_name)
+    created_file = False
+    upload_completed = False
+
+    try:
+        async with aiofiles.open(target, "xb") as buffer:
+            created_file = True
+            while chunk := await file.read(1024 * 1024):
+                await buffer.write(chunk)
+        upload_completed = True
+    except FileExistsError as exc:
+        raise HTTPException(status_code=400, detail="同名文件或文件夹已存在") from exc
+    except PermissionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    finally:
+        if created_file and not upload_completed and target.exists():
+            with contextlib.suppress(OSError):
+                await asyncio.to_thread(target.unlink)
+
+    return {"success": True, "entry": _entry_for_path(root, target)}
+
+
 async def download_workspace_file(*, path: str, current_user: User) -> StreamingResponse | FileResponse:
     target = _resolve_workspace_path(current_user, path)
     if not target.exists():
diff --git a/backend/server/routers/workspace_router.py b/backend/server/routers/workspace_router.py
index 31c5472d..ba713266 100644
--- a/backend/server/routers/workspace_router.py
+++ b/backend/server/routers/workspace_router.py
@@ -1,14 +1,27 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends, Query
+from fastapi import APIRouter, Depends, File, Form, Query, UploadFile
+from pydantic import BaseModel
 
 from server.utils.auth_middleware import get_required_user
-from yuxi.services.workspace_service import download_workspace_file, list_workspace_tree, read_workspace_file_content
+from yuxi.services.workspace_service import (
+    create_workspace_directory,
+    delete_workspace_path,
+    download_workspace_file,
+    list_workspace_tree,
+    read_workspace_file_content,
+    upload_workspace_file,
+)
 from yuxi.storage.postgres.models_business import User
 
 workspace = APIRouter(prefix="/workspace", tags=["workspace"])
 
 
+class CreateWorkspaceDirectoryRequest(BaseModel):
+    parent_path: str
+    name: str
+
+
 @workspace.get("/tree", response_model=dict)
 async def get_workspace_tree(
     path: str = Query("/", description="工作区目录路径"),
@@ -25,6 +38,35 @@ async def get_workspace_file(
     return await read_workspace_file_content(path=path, current_user=current_user)
 
 
+@workspace.delete("/file", response_model=dict)
+async def delete_workspace_file_route(
+    path: str = Query(..., description="工作区文件或目录路径"),
+    current_user: User = Depends(get_required_user),
+):
+    return await delete_workspace_path(path=path, current_user=current_user)
+
+
+@workspace.post("/directory", response_model=dict)
+async def create_workspace_directory_route(
+    payload: CreateWorkspaceDirectoryRequest,
+    current_user: User = Depends(get_required_user),
+):
+    return await create_workspace_directory(
+        parent_path=payload.parent_path,
+        name=payload.name,
+        current_user=current_user,
+    )
+
+
+@workspace.post("/upload", response_model=dict)
+async def upload_workspace_file_route(
+    parent_path: str = Form(..., description="父目录路径"),
+    file: UploadFile = File(..., description="上传文件"),
+    current_user: User = Depends(get_required_user),
+):
+    return await upload_workspace_file(parent_path=parent_path, file=file, current_user=current_user)
+
+
 @workspace.get("/download")
 async def download_workspace(
     path: str = Query(..., description="工作区文件路径"),
diff --git a/docs/develop-guides/roadmap.md b/docs/develop-guides/roadmap.md
index 6641ac7e..10fd42d1 100644
--- a/docs/develop-guides/roadmap.md
+++ b/docs/develop-guides/roadmap.md
@@ -37,7 +37,7 @@
 ### 0.6.2 开发记录
 
 <!-- 0.6.2 的内容请放在这里 -->
-- 新增个人工作区预览：提供独立于对话 thread 的用户级 workspace 只读 API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；知识库与团队空间入口先展示到占位层级。
+- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；支持新建文件夹、上传文件、下载文件、删除文件/文件夹和多选删除；知识库与团队空间入口先展示到占位层级。
 - 扩展管理界面交互逻辑重构：将 MCP / Subagents / Skills 三个标签页从「左侧边栏 + 右侧详情面板」布局重构为「卡片式网格布局 + 路由跳转二级页面」布局，工具标签页改为卡片网格布局 + 弹窗详情（保持弹窗内容不变）。新增共享组件 `ExtensionCard`、`ExtensionCardGrid`、`ExtensionToolbar`、`ExtensionDetailLayout`，详情页（`McpDetailView`、`SubagentDetailView`、`SkillDetailView`）使用居中宽度限制，路由规划为 `/extensions/mcp/:name`、`/extensions/subagent/:name`、`/extensions/skill/:slug`。
 - 统一卡片样式：`ExtensionCard` 新增 `tags` prop 支持传入 `[{label, color}]` 数组，内部使用 `<a-tag bordered=false size=small>` 渲染，与知识库卡片标签风格统一；知识库列表页 `DataBaseView` 改用 `ExtensionCard` + `ExtensionCardGrid` 替代原有自定义卡片，移除冗余 card 样式。
 - 调整应用主导航：`AppLayout` 从默认窄栏升级为默认展开的侧边栏，保留折叠态图标导航；侧边栏样式收敛为 14px 文本 + 18px 图标的标准紧凑密度，并统一导航项、任务中心、GitHub、用户信息的图标与文字对齐。折叠态改为仅通过显式按钮展开，避免空白区域误触发。
diff --git a/web/src/apis/workspace_api.js b/web/src/apis/workspace_api.js
index 37519b5e..83a56715 100644
--- a/web/src/apis/workspace_api.js
+++ b/web/src/apis/workspace_api.js
@@ -1,4 +1,4 @@
-import { apiGet } from './base'
+import { apiDelete, apiGet, apiPost } from './base'
 
 const buildQuery = (params) => {
   const query = new URLSearchParams()
@@ -20,6 +20,25 @@ export const getWorkspaceFileContent = (path) => {
   return apiGet(`/api/workspace/file?${query}`)
 }
 
+export const deleteWorkspacePath = (path) => {
+  const query = buildQuery({ path })
+  return apiDelete(`/api/workspace/file?${query}`)
+}
+
+export const createWorkspaceDirectory = (parentPath, name) => {
+  return apiPost('/api/workspace/directory', {
+    parent_path: parentPath,
+    name
+  })
+}
+
+export const uploadWorkspaceFile = (parentPath, file) => {
+  const formData = new FormData()
+  formData.append('parent_path', parentPath)
+  formData.append('file', file)
+  return apiPost('/api/workspace/upload', formData)
+}
+
 export const downloadWorkspaceFile = (path) => {
   const query = buildQuery({ path })
   return apiGet(`/api/workspace/download?${query}`, {}, true, 'blob')
diff --git a/web/src/components/workspace/WorkspaceFileList.vue b/web/src/components/workspace/WorkspaceFileList.vue
index 2f492001..0373c8c1 100644
--- a/web/src/components/workspace/WorkspaceFileList.vue
+++ b/web/src/components/workspace/WorkspaceFileList.vue
@@ -13,24 +13,62 @@
         </button>
         <span class="path-text" :title="currentPath">{{ currentPath }}</span>
       </div>
-      <span class="entry-count">{{ entries.length }} 项</span>
+      <div class="list-actions">
+        <span class="entry-count">{{ entries.length }} 项</span>
+        <a-button size="small" :type="selectionMode ? 'primary' : 'default'" @click="toggleSelectionMode">
+          多选
+        </a-button>
+        <a-button
+          v-if="selectionMode"
+          size="small"
+          danger
+          :disabled="!selectedPaths.length"
+          :loading="deletingPaths.length > 0"
+          @click="$emit('delete-selected')"
+        >
+          删除选中
+        </a-button>
+      </div>
     </div>
 
     <div class="file-table" role="table" aria-label="工作区文件列表">
-      <div class="file-row table-head" role="row">
+      <div class="file-row table-head" :class="{ 'selection-enabled': selectionMode }" role="row">
+        <span v-if="selectionMode" class="selection-cell">
+          <a-checkbox
+            :checked="allSelected"
+            :indeterminate="partiallySelected"
+            :disabled="!entries.length"
+            aria-label="全选当前目录文件"
+            @change="toggleAllSelection"
+          />
+        </span>
         <span>名称</span>
         <span>大小</span>
         <span>修改时间</span>
+        <span class="action-head">操作</span>
       </div>
-      <button
+      <div
         v-for="entry in entries"
         :key="entry.path"
-        type="button"
         class="file-row"
-        :class="{ selected: selectedPath === entry.path }"
+        :class="{
+          selected: selectedPath === entry.path,
+          deleting: isDeleting(entry.path),
+          'selection-enabled': selectionMode
+        }"
         role="row"
+        tabindex="0"
         @click="$emit('select-entry', entry)"
+        @keydown.enter="$emit('select-entry', entry)"
       >
+        <span v-if="selectionMode" class="selection-cell" @click.stop>
+          <a-checkbox
+            :checked="selectedPathSet.has(entry.path)"
+            :disabled="isDeleting(entry.path)"
+            :aria-label="`选择 ${entry.name}`"
+            @change="(event) => toggleEntrySelection(entry.path, event.target.checked)"
+          />
+        </span>
         <span class="name-cell">
           <Folder v-if="entry.is_dir" :size="17" class="folder-icon" />
           <component
@@ -42,7 +80,36 @@
         </span>
         <span>{{ entry.is_dir ? '-' : formatFileSize(entry.size) }}</span>
         <span>{{ formatRelativeTime(entry.modified_at) }}</span>
-      </button>
+        <span class="action-cell" @click.stop>
+          <a-dropdown :trigger="['click']">
+            <button
+              type="button"
+              class="more-action"
+              :disabled="isDeleting(entry.path)"
+              aria-label="更多操作"
+              @click.stop
+            >
+              <MoreHorizontal :size="16" />
+            </button>
+            <template #overlay>
+              <a-menu>
+                <a-menu-item v-if="!entry.is_dir" key="download" @click="$emit('download-entry', entry)">
+                  <span class="menu-item-content">
+                    <Download :size="14" />
+                    <span>下载</span>
+                  </span>
+                </a-menu-item>
+                <a-menu-item key="delete" danger @click="$emit('delete-entry', entry)">
+                  <span class="menu-item-content">
+                    <Trash2 :size="14" />
+                    <span>删除</span>
+                  </span>
+                </a-menu-item>
+              </a-menu>
+            </template>
+          </a-dropdown>
+        </span>
+      </div>
     </div>
 
     <div v-if="loading" class="list-state">
@@ -54,17 +121,65 @@
 </template>
 
 <script setup>
-import { ChevronLeft, Folder } from 'lucide-vue-next'
+import { computed } from 'vue'
+import { ChevronLeft, Download, Folder, MoreHorizontal, Trash2 } from 'lucide-vue-next'
 import { formatFileSize, formatRelativeTime, getFileIcon, getFileIconColor } from '@/utils/file_utils'
 
-defineProps({
+const props = defineProps({
   entries: { type: Array, default: () => [] },
   currentPath: { type: String, default: '/' },
   selectedPath: { type: String, default: '' },
+  selectedPaths: { type: Array, default: () => [] },
+  deletingPaths: { type: Array, default: () => [] },
+  selectionMode: { type: Boolean, default: false },
   loading: { type: Boolean, default: false }
 })
 
-defineEmits(['select-entry', 'go-parent'])
+const emit = defineEmits([
+  'select-entry',
+  'go-parent',
+  'update:selectedPaths',
+  'update:selectionMode',
+  'delete-selected',
+  'delete-entry',
+  'download-entry'
+])
+
+const selectedPathSet = computed(() => new Set(props.selectedPaths))
+const deletingPathSet = computed(() => new Set(props.deletingPaths))
+const entryPaths = computed(() => props.entries.map((entry) => entry.path))
+
+const allSelected = computed(() => {
+  return entryPaths.value.length > 0 && entryPaths.value.every((path) => selectedPathSet.value.has(path))
+})
+
+const partiallySelected = computed(() => {
+  return !allSelected.value && entryPaths.value.some((path) => selectedPathSet.value.has(path))
+})
+
+const isDeleting = (path) => deletingPathSet.value.has(path)
+
+const toggleSelectionMode = () => {
+  const nextMode = !props.selectionMode
+  emit('update:selectionMode', nextMode)
+  if (!nextMode) {
+    emit('update:selectedPaths', [])
+  }
+}
+
+const toggleAllSelection = (event) => {
+  emit('update:selectedPaths', event.target.checked ? [...entryPaths.value] : [])
+}
+
+const toggleEntrySelection = (path, checked) => {
+  const nextSelectedPaths = new Set(props.selectedPaths)
+  if (checked) {
+    nextSelectedPaths.add(path)
+  } else {
+    nextSelectedPaths.delete(path)
+  }
+  emit('update:selectedPaths', [...nextSelectedPaths].filter((selectedPath) => entryPaths.value.includes(selectedPath)))
+}
 </script>
 
 <style scoped lang="less">
@@ -86,13 +201,18 @@ defineEmits(['select-entry', 'go-parent'])
   border-bottom: 1px solid var(--gray-100);
 }
 
-.path-line {
+.path-line,
+.list-actions {
   display: flex;
   align-items: center;
   min-width: 0;
   gap: 8px;
 }
 
+.list-actions {
+  flex: 0 0 auto;
+}
+
 .path-action {
   display: inline-flex;
   align-items: center;
@@ -139,9 +259,9 @@ defineEmits(['select-entry', 'go-parent'])
 
 .file-row {
   display: grid;
-  grid-template-columns: minmax(160px, 1fr) 86px 130px;
+  grid-template-columns: minmax(150px, 1fr) 76px 118px 34px;
   align-items: center;
-  gap: 12px;
+  gap: 10px;
   width: 100%;
   min-height: 38px;
   padding: 0 14px;
@@ -152,6 +272,10 @@ defineEmits(['select-entry', 'go-parent'])
   font-size: 13px;
   text-align: left;
 
+  &.selection-enabled {
+    grid-template-columns: 34px minmax(150px, 1fr) 76px 118px 34px;
+  }
+
   &:not(.table-head) {
     cursor: pointer;
   }
@@ -165,6 +289,10 @@ defineEmits(['select-entry', 'go-parent'])
   &.selected {
     box-shadow: inset 3px 0 0 var(--main-color);
   }
+
+  &.deleting {
+    opacity: 0.62;
+  }
 }
 
 .table-head {
@@ -178,6 +306,46 @@ defineEmits(['select-entry', 'go-parent'])
   font-weight: 600;
 }
 
+.selection-cell,
+.action-cell {
+  display: inline-flex;
+  align-items: center;
+}
+
+.action-head,
+.action-cell {
+  justify-content: center;
+}
+
+.more-action {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--gray-500);
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    background: var(--gray-100);
+    color: var(--gray-900);
+  }
+
+  &:disabled {
+    color: var(--gray-300);
+    cursor: not-allowed;
+  }
+}
+
+.menu-item-content {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
 .name-cell {
   display: flex;
   align-items: center;
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index 5d90bfe5..267299a6 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -58,7 +58,7 @@ defineEmits(['select-personal', 'select-database'])
   flex-direction: column;
   gap: 18px;
   min-width: 0;
-  padding: 14px calc(var(--page-padding) - 8px);
+  padding: 14px 10px;
   border-right: 1px solid var(--gray-100);
   background: var(--gray-25);
   overflow-y: auto;
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index 045d0bf7..60b2203a 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -1,41 +1,79 @@
 <template>
   <div class="workspace-view layout-container">
     <PageHeader title="工作区" :loading="loadingTree || loadingPreview" :show-border="true">
-      <template #info>
-        <span class="workspace-info">个人文件的只读预览空间</span>
-      </template>
       <template #actions>
-        <a-tooltip title="即将支持">
-          <a-button type="primary" disabled>新建文件夹</a-button>
-        </a-tooltip>
+        <a-button :disabled="activeSourceKey !== 'personal'" @click="openCreateDirectoryModal">
+          新建文件夹
+        </a-button>
+        <a-button :loading="uploadingFile" :disabled="activeSourceKey !== 'personal'" @click="openUploadFilePicker">
+          上传文件
+        </a-button>
       </template>
     </PageHeader>
 
-    <div class="workspace-shell">
-      <WorkspaceSidebar
-        :active-key="activeSourceKey"
-        :databases="databases"
-        :loading-databases="loadingDatabases"
-        @select-personal="selectPersonalWorkspace"
-        @select-database="selectDatabase"
-      />
+    <input ref="uploadInputRef" class="upload-input" type="file" @change="handleUploadInputChange" />
+
+    <div class="workspace-shell" :class="{ 'is-sidebar-collapsed': sidebarCollapsed }">
+      <div v-if="!sidebarCollapsed" class="workspace-sidebar-slot">
+        <button
+          type="button"
+          class="sidebar-collapse-action"
+          aria-label="收起工作区侧边栏"
+          @click="sidebarCollapsed = true"
+        >
+          <ChevronLeft :size="16" />
+        </button>
+        <WorkspaceSidebar
+          :active-key="activeSourceKey"
+          :databases="databases"
+          :loading-databases="loadingDatabases"
+          @select-personal="selectPersonalWorkspace"
+          @select-database="selectDatabase"
+        />
+      </div>
+      <button
+        v-else
+        type="button"
+        class="sidebar-expand-action"
+        aria-label="展开工作区侧边栏"
+        @click="sidebarCollapsed = false"
+      >
+        <ChevronRight :size="16" />
+      </button>
 
       <main
         ref="workspaceMainRef"
         class="workspace-main"
-        :class="{ 'is-inline-preview': useInlinePreview }"
+        :class="{ 'is-inline-preview': showInlinePreview }"
+        :style="workspaceMainStyle"
       >
         <template v-if="activeSourceKey === 'personal'">
           <WorkspaceFileList
             :entries="filteredEntries"
             :current-path="currentPath"
             :selected-path="selectedEntry?.path || ''"
+            :selected-paths="selectedPaths"
+            :deleting-paths="deletingPaths"
+            :selection-mode="selectionMode"
             :loading="loadingTree"
             @select-entry="handleSelectEntry"
             @go-parent="goParentDirectory"
+            @update:selected-paths="selectedPaths = $event"
+            @update:selection-mode="handleSelectionModeChange"
+            @delete-selected="confirmDeleteEntries(selectedEntries)"
+            @delete-entry="(entry) => confirmDeleteEntries([entry])"
+            @download-entry="downloadEntry"
           />
+          <div
+            v-if="showInlinePreview"
+            class="workspace-preview-resizer"
+            role="separator"
+            aria-label="调整预览宽度"
+            tabindex="0"
+            @pointerdown="startPreviewResize"
+          ></div>
           <WorkspacePreviewPane
-            v-if="useInlinePreview"
+            v-if="showInlinePreview"
             :file="previewFile"
             :file-path="selectedEntry?.path || ''"
             :loading="loadingPreview"
@@ -50,6 +88,22 @@
       </main>
     </div>
 
+    <a-modal
+      v-model:open="createDirectoryModalVisible"
+      title="新建文件夹"
+      okText="创建"
+      cancelText="取消"
+      :confirm-loading="creatingDirectory"
+      @ok="createDirectory"
+    >
+      <a-input
+        v-model:value="newDirectoryName"
+        placeholder="请输入文件夹名称"
+        :disabled="creatingDirectory"
+        @keyup.enter="createDirectory"
+      />
+    </a-modal>
+
     <a-modal
       :open="previewModalVisible && !useInlinePreview"
       width="880px"
@@ -74,20 +128,29 @@
 
 <script setup>
 import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
-import { message } from 'ant-design-vue'
-import { LibraryBig } from 'lucide-vue-next'
+import { message, Modal } from 'ant-design-vue'
+import { ChevronLeft, ChevronRight, LibraryBig } from 'lucide-vue-next'
 import PageHeader from '@/components/shared/PageHeader.vue'
 import AgentFilePreview from '@/components/AgentFilePreview.vue'
 import WorkspaceFileList from '@/components/workspace/WorkspaceFileList.vue'
 import WorkspacePreviewPane from '@/components/workspace/WorkspacePreviewPane.vue'
 import WorkspaceSidebar from '@/components/workspace/WorkspaceSidebar.vue'
 import { databaseApi } from '@/apis/knowledge_api'
-import { downloadWorkspaceFile, getWorkspaceFileContent, getWorkspaceTree } from '@/apis/workspace_api'
+import {
+  createWorkspaceDirectory,
+  deleteWorkspacePath,
+  downloadWorkspaceFile,
+  getWorkspaceFileContent,
+  getWorkspaceTree,
+  uploadWorkspaceFile
+} from '@/apis/workspace_api'
 
 const activeSourceKey = ref('personal')
 const currentPath = ref('/')
 const entries = ref([])
 const selectedEntry = ref(null)
+const selectedPaths = ref([])
+const selectionMode = ref(false)
 const previewFile = ref(null)
 const previewObjectUrl = ref('')
 const previewModalVisible = ref(false)
@@ -99,9 +162,25 @@ const selectedDatabase = ref(null)
 const searchQuery = ref('')
 const workspaceMainRef = ref(null)
 const workspaceMainWidth = ref(0)
+const createDirectoryModalVisible = ref(false)
+const newDirectoryName = ref('')
+const creatingDirectory = ref(false)
+const uploadingFile = ref(false)
+const uploadInputRef = ref(null)
+const deletingPaths = ref([])
+const sidebarCollapsed = ref(false)
+const previewWidthPercent = ref(50)
 const INLINE_PREVIEW_MIN_WIDTH = 960
 
 const useInlinePreview = computed(() => workspaceMainWidth.value >= INLINE_PREVIEW_MIN_WIDTH)
+const showInlinePreview = computed(() => useInlinePreview.value && Boolean(previewFile.value))
+const workspaceMainStyle = computed(() => {
+  if (!showInlinePreview.value) return {}
+  const listWidthPercent = 100 - previewWidthPercent.value
+  return {
+    gridTemplateColumns: `minmax(0, ${listWidthPercent}%) 6px minmax(280px, ${previewWidthPercent.value}%)`
+  }
+})
 
 const filteredEntries = computed(() => {
   const keyword = searchQuery.value.trim().toLowerCase()
@@ -109,6 +188,11 @@ const filteredEntries = computed(() => {
   return entries.value.filter((entry) => String(entry.name || '').toLowerCase().includes(keyword))
 })
 
+const selectedEntries = computed(() => {
+  const selectedPathSet = new Set(selectedPaths.value)
+  return entries.value.filter((entry) => selectedPathSet.has(entry.path))
+})
+
 const revokePreviewObjectUrl = () => {
   if (!previewObjectUrl.value) return
   URL.revokeObjectURL(previewObjectUrl.value)
@@ -124,7 +208,8 @@ const normalizePreviewFile = async (entry, response) => {
   }
 
   if (previewType === 'image' || previewType === 'pdf') {
-    const blob = await downloadWorkspaceFile(entry.path)
+    const response = await downloadWorkspaceFile(entry.path)
+    const blob = await response.blob()
     revokePreviewObjectUrl()
     previewObjectUrl.value = URL.createObjectURL(blob)
     file.previewUrl = previewObjectUrl.value
@@ -133,12 +218,32 @@ const normalizePreviewFile = async (entry, response) => {
   return file
 }
 
+const syncSelectedPaths = () => {
+  const entryPathSet = new Set(entries.value.map((entry) => entry.path))
+  selectedPaths.value = selectedPaths.value.filter((path) => entryPathSet.has(path))
+}
+
+const clearWorkspaceSelection = () => {
+  selectedPaths.value = []
+}
+
+const handleSelectionModeChange = (enabled) => {
+  selectionMode.value = enabled
+  if (!enabled) {
+    clearWorkspaceSelection()
+  }
+}
+
 const loadWorkspaceEntries = async (path = '/') => {
   loadingTree.value = true
   try {
     const response = await getWorkspaceTree(path)
     entries.value = response.entries || []
     currentPath.value = path
+    syncSelectedPaths()
+    if (!selectedPaths.value.length) {
+      selectionMode.value = false
+    }
   } catch (error) {
     console.warn('加载工作区目录失败:', error)
     message.error('加载工作区目录失败')
@@ -163,12 +268,15 @@ const loadDatabases = async () => {
 const selectPersonalWorkspace = async () => {
   activeSourceKey.value = 'personal'
   selectedDatabase.value = null
+  clearWorkspaceSelection()
   if (!entries.value.length) {
     await loadWorkspaceEntries(currentPath.value)
   }
 }
 
 const selectDatabase = (database) => {
+  closePreview()
+  clearWorkspaceSelection()
   selectedDatabase.value = database
   activeSourceKey.value = `database:${database.db_id}`
 }
@@ -176,6 +284,7 @@ const selectDatabase = (database) => {
 const handleSelectEntry = async (entry) => {
   if (entry.is_dir) {
     closePreview()
+    clearWorkspaceSelection()
     await loadWorkspaceEntries(entry.path)
     return
   }
@@ -223,9 +332,183 @@ const goParentDirectory = async () => {
   const trimmed = currentPath.value.replace(/\/$/, '')
   const parent = trimmed.slice(0, trimmed.lastIndexOf('/')) || '/'
   closePreview()
+  clearWorkspaceSelection()
   await loadWorkspaceEntries(parent)
 }
 
+const openCreateDirectoryModal = () => {
+  if (activeSourceKey.value !== 'personal') return
+  newDirectoryName.value = ''
+  createDirectoryModalVisible.value = true
+}
+
+const createDirectory = async () => {
+  if (creatingDirectory.value) return
+  const directoryName = newDirectoryName.value.trim()
+  if (!directoryName) {
+    message.warning('请输入文件夹名')
+    return
+  }
+
+  creatingDirectory.value = true
+  try {
+    await createWorkspaceDirectory(currentPath.value, directoryName)
+    await loadWorkspaceEntries(currentPath.value)
+    createDirectoryModalVisible.value = false
+    newDirectoryName.value = ''
+    message.success('文件夹创建成功')
+  } catch (error) {
+    console.warn('创建文件夹失败:', error)
+    message.error(error?.message || '创建文件夹失败')
+  } finally {
+    creatingDirectory.value = false
+  }
+}
+
+const openUploadFilePicker = () => {
+  if (activeSourceKey.value !== 'personal' || uploadingFile.value) return
+  if (uploadInputRef.value) {
+    uploadInputRef.value.value = ''
+    uploadInputRef.value.click()
+  }
+}
+
+const handleUploadInputChange = async (event) => {
+  const file = event.target?.files?.[0]
+  if (!file || uploadingFile.value) return
+
+  uploadingFile.value = true
+  try {
+    await uploadWorkspaceFile(currentPath.value, file)
+    await loadWorkspaceEntries(currentPath.value)
+    message.success('文件上传成功')
+  } catch (error) {
+    console.warn('上传文件失败:', error)
+    message.error(error?.message || '上传文件失败')
+  } finally {
+    uploadingFile.value = false
+    event.target.value = ''
+  }
+}
+
+const comparablePath = (path) => String(path || '/').replace(/\/$/, '') || '/'
+
+const isSameOrChildPath = (path, targetPath) => {
+  const normalizedPath = comparablePath(path)
+  const normalizedTargetPath = comparablePath(targetPath)
+  return normalizedPath === normalizedTargetPath || normalizedPath.startsWith(`${normalizedTargetPath}/`)
+}
+
+const confirmDeleteEntries = (targetEntries) => {
+  const validEntries = (targetEntries || []).filter(Boolean)
+  if (!validEntries.length) return
+
+  const isBatch = validEntries.length > 1
+  const firstEntry = validEntries[0]
+  Modal.confirm({
+    title: isBatch
+      ? `确认删除选中的 ${validEntries.length} 项？`
+      : firstEntry.is_dir
+        ? `确认删除文件夹「${firstEntry.name}」？`
+        : `确认删除文件「${firstEntry.name}」？`,
+    content: isBatch || firstEntry.is_dir ? '将删除文件夹及其所有内容，删除后不可恢复。' : '删除后不可恢复。',
+    okText: '删除',
+    okType: 'danger',
+    cancelText: '取消',
+    onOk: () => deleteEntries(validEntries)
+  })
+}
+
+const deleteEntries = async (targetEntries) => {
+  const paths = targetEntries.map((entry) => entry.path)
+  deletingPaths.value = paths
+  try {
+    await Promise.all(paths.map((path) => deleteWorkspacePath(path)))
+    if (selectedEntry.value && paths.some((path) => isSameOrChildPath(selectedEntry.value.path, path))) {
+      closePreview()
+    }
+    clearWorkspaceSelection()
+    await loadWorkspaceEntries(currentPath.value)
+    message.success(paths.length > 1 ? '选中项删除成功' : '删除成功')
+  } catch (error) {
+    console.warn('删除工作区文件失败:', error)
+    message.error(error?.message || '删除失败')
+    await loadWorkspaceEntries(currentPath.value)
+  } finally {
+    deletingPaths.value = []
+  }
+}
+
+const parseDownloadFilename = (contentDisposition) => {
+  if (!contentDisposition) return ''
+
+  const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i)
+  if (utf8Match && utf8Match[1]) {
+    try {
+      return decodeURIComponent(utf8Match[1])
+    } catch (error) {
+      console.warn('解析 UTF-8 文件名失败:', error)
+    }
+  }
+
+  const asciiMatch = contentDisposition.match(/filename="?([^";]+)"?/i)
+  if (asciiMatch && asciiMatch[1]) {
+    return asciiMatch[1]
+  }
+
+  return ''
+}
+
+const downloadEntry = async (entry) => {
+  if (!entry?.path || entry.is_dir) return
+
+  try {
+    const response = await downloadWorkspaceFile(entry.path)
+    const blob = await response.blob()
+    const contentDisposition =
+      response.headers.get('Content-Disposition') || response.headers.get('content-disposition')
+    const filename = parseDownloadFilename(contentDisposition) || entry.name || 'download'
+    const url = window.URL.createObjectURL(blob)
+    const link = document.createElement('a')
+    link.href = url
+    link.download = filename
+    document.body.appendChild(link)
+    link.click()
+    document.body.removeChild(link)
+    window.URL.revokeObjectURL(url)
+  } catch (error) {
+    console.warn('下载文件失败:', error)
+    message.error(error?.message || '下载文件失败')
+  }
+}
+
+let resizePointerId = null
+
+const stopPreviewResize = () => {
+  resizePointerId = null
+  document.body.style.cursor = ''
+  document.body.style.userSelect = ''
+  window.removeEventListener('pointermove', resizePreview)
+  window.removeEventListener('pointerup', stopPreviewResize)
+}
+
+const resizePreview = (event) => {
+  if (!workspaceMainRef.value || resizePointerId === null) return
+  const rect = workspaceMainRef.value.getBoundingClientRect()
+  const relativeX = event.clientX - rect.left
+  const nextPreviewPercent = Math.round(((rect.width - relativeX) / rect.width) * 100)
+  previewWidthPercent.value = Math.min(70, Math.max(30, nextPreviewPercent))
+}
+
+const startPreviewResize = (event) => {
+  if (!showInlinePreview.value) return
+  resizePointerId = event.pointerId
+  document.body.style.cursor = 'col-resize'
+  document.body.style.userSelect = 'none'
+  window.addEventListener('pointermove', resizePreview)
+  window.addEventListener('pointerup', stopPreviewResize)
+}
+
 let workspaceResizeObserver = null
 
 onMounted(async () => {
@@ -245,6 +528,7 @@ onMounted(async () => {
 onUnmounted(() => {
   workspaceResizeObserver?.disconnect()
   workspaceResizeObserver = null
+  stopPreviewResize()
   revokePreviewObjectUrl()
 })
 
@@ -265,21 +549,69 @@ watch(useInlinePreview, (isInline) => {
   min-height: 0;
 }
 
-.workspace-info {
-  color: var(--gray-500);
-  font-size: 13px;
+.upload-input {
+  display: none;
 }
 
 .workspace-shell {
+  position: relative;
   display: grid;
-  grid-template-columns: clamp(210px, 18vw, 280px) minmax(0, 1fr);
+  grid-template-columns: 195px minmax(0, 1fr);
   flex: 1 1 auto;
   min-height: 0;
-  // margin: 16px var(--page-padding) var(--page-padding);
-  // border: 1px solid var(--gray-100);
-  // border-radius: 12px;
   background: var(--gray-0);
   overflow: hidden;
+
+  &.is-sidebar-collapsed {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}
+
+.workspace-sidebar-slot {
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+}
+
+.workspace-sidebar-slot :deep(.workspace-sidebar) {
+  height: 100%;
+}
+
+.sidebar-collapse-action,
+.sidebar-expand-action {
+  width: 26px;
+  height: 26px;
+  position: absolute;
+  top: 50%;
+  z-index: 4;
+  padding: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--gray-150);
+  background: var(--gray-0);
+  color: var(--gray-600);
+  cursor: pointer;
+  transform: translateY(-50%);
+  box-shadow: 0 4px 12px rgba(15, 23, 42, 0.08);
+
+  &:hover {
+    background: var(--main-20);
+    color: var(--main-color);
+  }
+}
+
+.sidebar-collapse-action {
+  right: -13px;
+  width: 26px;
+  border-radius: 50%;
+}
+
+.sidebar-expand-action {
+  left: 0;
+  width: 22px;
+  border-left: 0;
+  border-radius: 0 12px 12px 0;
 }
 
 .workspace-main {
@@ -289,8 +621,17 @@ watch(useInlinePreview, (isInline) => {
   min-height: 0;
 }
 
-.workspace-main.is-inline-preview {
-  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+.workspace-preview-resizer {
+  width: 6px;
+  min-width: 6px;
+  border-left: 1px solid var(--gray-100);
+  border-right: 1px solid var(--gray-100);
+  background: var(--gray-25);
+  cursor: col-resize;
+
+  &:hover {
+    background: var(--main-20);
+  }
 }
 
 .workspace-placeholder {
@@ -319,7 +660,6 @@ watch(useInlinePreview, (isInline) => {
     line-height: 1.6;
   }
 }
-
 </style>
 
 <style lang="less">

From 2c4c2e06c1ac9fb81c8ce52463d412013a1c7caa Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 22:21:44 +0800
Subject: [PATCH 03/15] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E4=BF=AE?=
 =?UTF-8?q?=E6=94=B9=20CLAUDE.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 59 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8a0e4af0..6ee3826c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -7,15 +7,69 @@ Yuxi 是一个基于大模型的智能知识库与知识图谱智能体开发平
 
 ## 开发准则
 
-Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
 
-Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability.
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
 
-Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use backwards-compatibility shims when you can just change the code.
+## 1. Think Before Coding
 
-Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task. Reuse existing abstractions where possible and follow the DRY principle.
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
 
-To ensure readability, it is necessary to add essential comments at key points, particularly to explain the functionality of a function and the design intent.
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
 
 ## 开发与调试工作流 (Development & Debugging Workflow)
 

From 874767d4bd6518cdf4b2f1ab8388f36d613ef8d7 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 22:26:12 +0800
Subject: [PATCH 04/15] =?UTF-8?q?feat:=20=E6=9B=BF=E6=8D=A2=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E5=9B=BE=E6=A0=87=E5=B9=B6=E4=BC=98=E5=8C=96=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6=E9=9D=A2=E6=9D=BF=E5=B8=83=E5=B1=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/src/components/AgentInputArea.vue |   4 +-
 web/src/components/AgentPanel.vue     | 427 +++-----------------------
 2 files changed, 46 insertions(+), 385 deletions(-)

diff --git a/web/src/components/AgentInputArea.vue b/web/src/components/AgentInputArea.vue
index 6c60c0bd..a7445535 100644
--- a/web/src/components/AgentInputArea.vue
+++ b/web/src/components/AgentInputArea.vue
@@ -94,7 +94,7 @@
           @click.stop="$emit('toggle-panel')"
           title="查看文件"
         >
-          <FolderCode :size="18" />
+          <FolderKanban :size="18" />
           <span>文件</span>
         </button>
         <slot name="actions-left-extra"></slot>
@@ -108,7 +108,7 @@ import { computed, ref, watch } from 'vue'
 import MessageInputComponent from '@/components/MessageInputComponent.vue'
 import ImagePreviewComponent from '@/components/ImagePreviewComponent.vue'
 import AttachmentOptionsComponent from '@/components/AttachmentOptionsComponent.vue'
-import { FolderCode, SquareCheck } from 'lucide-vue-next'
+import { FolderKanban, SquareCheck } from 'lucide-vue-next'
 import {
   CheckCircleOutlined,
   ClockCircleOutlined,
diff --git a/web/src/components/AgentPanel.vue b/web/src/components/AgentPanel.vue
index a64d9b60..618f8e51 100644
--- a/web/src/components/AgentPanel.vue
+++ b/web/src/components/AgentPanel.vue
@@ -2,12 +2,15 @@
   <div ref="panelRef" class="agent-panel" :class="{ resizing: isResizing }">
     <!-- 拖拽手柄 -->
     <div class="resize-handle" @pointerdown="startResize"></div>
-    <div class="panel-header" :class="{ 'is-compact': isCompactHeader }">
+    <div class="panel-header">
       <div class="panel-header-main">
         <div class="panel-title">
           <span><strong>文件系统</strong></span>
         </div>
         <div class="window-actions">
+          <button class="header-action-btn" title="刷新" @click="emitRefresh">
+            <RefreshCw :size="15" />
+          </button>
           <button
             class="header-action-btn"
             :title="isExpanded ? '恢复高度' : '向上展开'"
@@ -20,34 +23,7 @@
           </button>
         </div>
       </div>
-      <div class="file-toolbar">
-        <button
-          class="header-action-btn"
-          title="新建文件夹"
-          :disabled="!threadId"
-          @click="openCreateDirectoryModal"
-        >
-          <FolderPlus :size="15" />
-        </button>
-        <button
-          class="header-action-btn"
-          title="上传文件"
-          :disabled="!threadId"
-          @click="openUploadFilePicker"
-        >
-          <Upload :size="15" />
-        </button>
-        <button class="header-action-btn" title="刷新" @click="emitRefresh">
-          <RefreshCw :size="15" />
-        </button>
-      </div>
     </div>
-    <input
-      ref="uploadInputRef"
-      class="hidden-file-input"
-      type="file"
-      @change="handleUploadInputChange"
-    />
     <div class="tab-content">
       <div class="files-display">
         <div v-if="!threadId" class="empty">创建对话后可查看工作区</div>
@@ -142,24 +118,6 @@
         @close="closePreview"
       />
     </a-modal>
-
-    <a-modal
-      v-model:open="createDirectoryModalVisible"
-      title="新建文件夹"
-      okText="创建"
-      cancelText="取消"
-      :confirmLoading="creatingDirectory"
-      @ok="createDirectory"
-      @cancel="closeCreateDirectoryModal"
-    >
-      <p>文件夹将创建在{{ resolveWorkspaceTargetDirectory() }}下</p>
-      <a-input
-        v-model:value="newDirectoryName"
-        placeholder="输入文件夹名"
-        :maxlength="120"
-        @pressEnter="createDirectory"
-      />
-    </a-modal>
   </div>
 </template>
 
@@ -169,22 +127,18 @@ import {
   ChevronsDownUp,
   ChevronsUpDown,
   Download,
-  FolderPlus,
   RefreshCw,
   Trash2,
-  Upload,
   X
 } from 'lucide-vue-next'
 import { Modal, message } from 'ant-design-vue'
 import FileTreeComponent from '@/components/FileTreeComponent.vue'
 import AgentFilePreview from '@/components/AgentFilePreview.vue'
 import {
-  createViewerDirectory,
   deleteViewerFile,
   downloadViewerFile,
   getViewerFileContent,
-  getViewerFileSystemTree,
-  uploadViewerFile
+  getViewerFileSystemTree
 } from '@/apis/viewer_filesystem'
 
 const props = defineProps({
@@ -220,20 +174,15 @@ const props = defineProps({
 
 const emit = defineEmits(['refresh', 'close', 'resize', 'resizing', 'toggle-expand'])
 const INLINE_PREVIEW_MIN_WIDTH = 920
-const WORKSPACE_PATH = '/home/gem/user-data/workspace'
+const DEFAULT_EXPANDED_ROOT_DIRECTORY_NAME = 'user-data'
 
 const panelRef = ref(null)
-const uploadInputRef = ref(null)
 const modalVisible = ref(false)
-const createDirectoryModalVisible = ref(false)
 const currentFile = ref(null)
 const currentFilePath = ref('')
 const loadingFiles = ref(false)
 const filesystemError = ref('')
 const panelWidth = ref(0)
-const newDirectoryName = ref('')
-const creatingDirectory = ref(false)
-const uploadingFile = ref(false)
 
 const dynamicTreeData = ref([])
 const selectedKeys = ref([])
@@ -241,7 +190,6 @@ const expandedKeys = ref([])
 const deletingPaths = ref(new Set())
 
 const useInlinePreview = computed(() => panelWidth.value >= INLINE_PREVIEW_MIN_WIDTH)
-const isCompactHeader = computed(() => panelWidth.value > 0 && panelWidth.value < 360)
 
 const buildDisplayName = (fullPath) => {
   const normalized = String(fullPath || '').replace(/\/+$/, '')
@@ -329,43 +277,6 @@ const removeTreeNode = (nodes, targetKey) => {
 
 const normalizePathKey = (path) => String(path || '').replace(/\/+$/, '')
 
-const isWorkspacePath = (path) => {
-  const normalizedPath = normalizePathKey(path)
-  return normalizedPath === WORKSPACE_PATH || normalizedPath.startsWith(`${WORKSPACE_PATH}/`)
-}
-
-const parentPathOf = (path) => {
-  const normalizedPath = normalizePathKey(path)
-  if (!normalizedPath || normalizedPath === '/') return '/'
-  const parts = normalizedPath.split('/').filter(Boolean)
-  parts.pop()
-  return parts.length ? `/${parts.join('/')}` : '/'
-}
-
-const findTreeNode = (nodes, targetKey) => {
-  const normalizedTargetKey = normalizePathKey(targetKey)
-  for (const node of nodes) {
-    if (normalizePathKey(node.key) === normalizedTargetKey) return node
-    if (node.children?.length) {
-      const child = findTreeNode(node.children, targetKey)
-      if (child) return child
-    }
-  }
-  return null
-}
-
-const resolveWorkspaceTargetDirectory = () => {
-  const selectedKey = selectedKeys.value[0]
-  if (!selectedKey) return WORKSPACE_PATH
-
-  // 根据当前选中节点推断写入目录，避免把文件上传到只读命名空间。
-  const selectedNode = findTreeNode(dynamicTreeData.value, selectedKey)
-  const targetPath = selectedNode?.isLeaf
-    ? parentPathOf(selectedKey)
-    : normalizePathKey(selectedKey)
-  return isWorkspacePath(targetPath) ? targetPath : ''
-}
-
 const isSameOrChildPath = (path, targetPath) => {
   const normalizedPath = normalizePathKey(path)
   const normalizedTargetPath = normalizePathKey(targetPath)
@@ -402,6 +313,22 @@ const getFileName = (fileItem) => {
   return '未知文件'
 }
 
+const loadDirectoryChildren = async (directoryPath) => {
+  const res = await getViewerFileSystemTree(
+    props.threadId,
+    directoryPath,
+    props.agentId,
+    props.agentConfigId
+  )
+  return sortEntries(res?.entries || []).map((entry) => createTreeNode(entry))
+}
+
+const findDefaultExpandedRootNode = (nodes) => {
+  return nodes.find(
+    (node) => !node.isLeaf && buildDisplayName(node.key) === DEFAULT_EXPANDED_ROOT_DIRECTORY_NAME
+  )
+}
+
 const refreshFileSystem = async () => {
   if (!props.threadId) {
     dynamicTreeData.value = []
@@ -420,9 +347,21 @@ const refreshFileSystem = async () => {
       props.agentConfigId
     )
     if (res?.entries) {
-      dynamicTreeData.value = sortEntries(res.entries).map((entry) => createTreeNode(entry))
-      expandedKeys.value = []
+      const rootNodes = sortEntries(res.entries).map((entry) => createTreeNode(entry))
+      const defaultExpandedNode = findDefaultExpandedRootNode(rootNodes)
+
+      dynamicTreeData.value = rootNodes
+      expandedKeys.value = defaultExpandedNode ? [defaultExpandedNode.key] : []
       selectedKeys.value = []
+
+      if (defaultExpandedNode) {
+        try {
+          const children = await loadDirectoryChildren(defaultExpandedNode.key)
+          dynamicTreeData.value = updateTreeChildren(rootNodes, defaultExpandedNode.key, children)
+        } catch (error) {
+          console.error('Failed to load default expanded directory', error)
+        }
+      }
     } else {
       dynamicTreeData.value = []
     }
@@ -435,47 +374,14 @@ const refreshFileSystem = async () => {
   }
 }
 
-const loadData = (treeNode) => {
-  return new Promise((resolve) => {
-    if (treeNode.isLeaf || (treeNode.children && treeNode.children.length > 0) || !props.threadId) {
-      resolve()
-      return
-    }
-
-    getViewerFileSystemTree(props.threadId, treeNode.key, props.agentId, props.agentConfigId)
-      .then((res) => {
-        if (res?.entries) {
-          const children = sortEntries(res.entries).map((entry) => createTreeNode(entry))
-          dynamicTreeData.value = updateTreeChildren(dynamicTreeData.value, treeNode.key, children)
-        }
-        resolve()
-      })
-      .catch((error) => {
-        console.error('Failed to load children for', treeNode.key, error)
-        resolve()
-      })
-  })
-}
-
-const refreshDirectoryChildren = async (directoryPath) => {
-  const normalizedDirectoryPath = normalizePathKey(directoryPath)
-  const targetNode = findTreeNode(dynamicTreeData.value, normalizedDirectoryPath)
-  if (!targetNode || targetNode.isLeaf) {
-    return
-  }
+const loadData = async (treeNode) => {
+  if (treeNode.isLeaf || treeNode.children?.length || !props.threadId) return
 
-  const res = await getViewerFileSystemTree(
-    props.threadId,
-    normalizedDirectoryPath,
-    props.agentId,
-    props.agentConfigId
-  )
-  if (res?.entries) {
-    const children = sortEntries(res.entries).map((entry) => createTreeNode(entry))
-    dynamicTreeData.value = updateTreeChildren(dynamicTreeData.value, targetNode.key, children)
-    if (!expandedKeys.value.includes(targetNode.key)) {
-      expandedKeys.value = [...expandedKeys.value, targetNode.key]
-    }
+  try {
+    const children = await loadDirectoryChildren(treeNode.key)
+    dynamicTreeData.value = updateTreeChildren(dynamicTreeData.value, treeNode.key, children)
+  } catch (error) {
+    console.error('Failed to load children for', treeNode.key, error)
   }
 }
 
@@ -595,100 +501,6 @@ const confirmDeleteNode = (node) => {
   })
 }
 
-const openCreateDirectoryModal = () => {
-  if (!props.threadId) return
-  const targetDirectory = resolveWorkspaceTargetDirectory()
-  if (!targetDirectory) {
-    message.warning('只能在 workspace 目录下新建文件夹')
-    return
-  }
-  newDirectoryName.value = ''
-  createDirectoryModalVisible.value = true
-}
-
-const closeCreateDirectoryModal = () => {
-  createDirectoryModalVisible.value = false
-  newDirectoryName.value = ''
-}
-
-const createDirectory = async () => {
-  if (creatingDirectory.value) return
-  const targetDirectory = resolveWorkspaceTargetDirectory()
-  const directoryName = newDirectoryName.value.trim()
-
-  if (!targetDirectory) {
-    message.warning('只能在 workspace 目录下新建文件夹')
-    return
-  }
-  if (!directoryName) {
-    message.warning('请输入文件夹名')
-    return
-  }
-
-  creatingDirectory.value = true
-  try {
-    await createViewerDirectory(
-      props.threadId,
-      targetDirectory,
-      directoryName,
-      props.agentId,
-      props.agentConfigId
-    )
-    await refreshDirectoryChildren(targetDirectory)
-    closeCreateDirectoryModal()
-    message.success('文件夹创建成功')
-  } catch (error) {
-    console.error('创建文件夹失败:', error)
-    message.error(error?.message || '创建文件夹失败')
-  } finally {
-    creatingDirectory.value = false
-  }
-}
-
-const openUploadFilePicker = () => {
-  if (!props.threadId || uploadingFile.value) return
-  const targetDirectory = resolveWorkspaceTargetDirectory()
-  if (!targetDirectory) {
-    message.warning('只能上传到 workspace 目录')
-    return
-  }
-  if (uploadInputRef.value) {
-    uploadInputRef.value.value = ''
-    uploadInputRef.value.click()
-  }
-}
-
-const handleUploadInputChange = async (event) => {
-  const file = event.target?.files?.[0]
-  if (!file || uploadingFile.value) return
-
-  const targetDirectory = resolveWorkspaceTargetDirectory()
-  if (!targetDirectory) {
-    message.warning('只能上传到 workspace 目录')
-    event.target.value = ''
-    return
-  }
-
-  uploadingFile.value = true
-  try {
-    await uploadViewerFile(
-      props.threadId,
-      targetDirectory,
-      file,
-      props.agentId,
-      props.agentConfigId
-    )
-    await refreshDirectoryChildren(targetDirectory)
-    message.success('文件上传成功')
-  } catch (error) {
-    console.error('上传文件失败:', error)
-    message.error(error?.message || '上传文件失败')
-  } finally {
-    uploadingFile.value = false
-    event.target.value = ''
-  }
-}
-
 const downloadFile = async (fileItem) => {
   if (!props.threadId || !fileItem?.path) return
 
@@ -869,37 +681,11 @@ watch(useInlinePreview, (isInline) => {
   display: flex;
   align-items: center;
   justify-content: space-between;
-  gap: 8px;
+  gap: 2px;
   padding: 4px 16px;
   min-height: 44px;
   background: var(--gray-25);
   flex-shrink: 0;
-
-  &.is-compact {
-    align-items: stretch;
-    flex-direction: column;
-    gap: 6px;
-    padding: 8px 12px;
-
-    .panel-header-main {
-      display: flex;
-      align-items: center;
-      justify-content: space-between;
-      gap: 8px;
-      min-width: 0;
-    }
-
-    .file-toolbar {
-      order: 2;
-      width: 100%;
-      justify-content: flex-start;
-      padding: 4px;
-      border-right: none;
-      border: 1px solid var(--gray-150);
-      border-radius: 8px;
-      background: var(--gray-0);
-    }
-  }
 }
 
 .panel-header-main {
@@ -964,8 +750,6 @@ watch(useInlinePreview, (isInline) => {
 
 .file-toolbar {
   order: 2;
-  padding-right: 8px;
-  border-right: 1px solid var(--gray-300);
 }
 
 .window-actions {
@@ -973,10 +757,6 @@ watch(useInlinePreview, (isInline) => {
   flex-shrink: 0;
 }
 
-.hidden-file-input {
-  display: none;
-}
-
 .close-btn {
   border: none;
   background: transparent;
@@ -1130,125 +910,6 @@ watch(useInlinePreview, (isInline) => {
   }
 }
 
-.todo-list {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.todo-item {
-  display: flex;
-  align-items: flex-start;
-  gap: 10px;
-  padding: 6px 12px;
-  border-radius: 8px;
-  border: 1px solid var(--gray-150);
-  transition: all 0.15s ease;
-
-  &:hover {
-    background: var(--main-10);
-    border-color: var(--gray-200);
-  }
-}
-
-.todo-status {
-  flex-shrink: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  margin-top: 2px;
-
-  .icon {
-    font-size: 16px;
-
-    &.completed {
-      color: #52c41a;
-    }
-    &.in-progress {
-      color: #1890ff;
-    }
-    &.pending {
-      color: #faad14;
-    }
-    &.cancelled {
-      color: #ff4d4f;
-    }
-    &.unknown {
-      color: var(--gray-400);
-    }
-  }
-}
-
-.todo-text {
-  flex: 1;
-  font-size: 13px;
-  line-height: 1.5;
-  color: var(--gray-1000);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-
-  .todo-item.completed & {
-    color: var(--gray-500);
-    text-decoration: line-through;
-  }
-}
-
-.list-header {
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-  margin-bottom: 12px;
-  padding: 0 4px;
-
-  .list-header-left {
-    display: flex;
-    align-items: center;
-    gap: 6px;
-  }
-
-  .count {
-    font-size: 13px;
-    color: var(--gray-500);
-  }
-
-  .info-icon {
-    color: var(--gray-400);
-    cursor: help;
-    transition: color 0.2s;
-
-    &:hover {
-      color: var(--main-500);
-    }
-  }
-
-  .add-btn {
-    display: flex;
-    align-items: center;
-    gap: 4px;
-    padding: 4px 10px;
-    height: 28px;
-    border: 1px solid var(--gray-200);
-    border-radius: 6px;
-    background: var(--gray-0);
-    color: var(--gray-700);
-    font-size: 13px;
-    cursor: pointer;
-    transition: all 0.2s;
-
-    &:hover:not(:disabled) {
-      background: var(--gray-50);
-      color: var(--main-700);
-      border-color: var(--main-300);
-    }
-
-    &:disabled {
-      opacity: 0.5;
-      cursor: not-allowed;
-    }
-  }
-}
-
 /* File Tree Styles - VS Code Style Refined */
 .file-tree-container {
   margin: 0 -4px;

From 9ff925e4dfa4beec192d799501b5dc04bf058d18 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 22:29:22 +0800
Subject: [PATCH 05/15] =?UTF-8?q?feat(workspace):=20=E5=A2=9E=E5=BC=BA?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E4=BE=A7=E8=BE=B9=E6=A0=8F=EF=BC=8C?=
 =?UTF-8?q?=E6=96=B0=E5=A2=9E=E5=BF=AB=E9=80=9F=E8=AE=BF=E9=97=AE=E5=8A=9F?=
 =?UTF-8?q?=E8=83=BD=E5=B9=B6=E4=BC=98=E5=8C=96=E8=B7=AF=E5=BE=84=E9=80=89?=
 =?UTF-8?q?=E6=8B=A9=E9=80=BB=E8=BE=91?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../components/workspace/WorkspaceSidebar.vue | 22 ++++++++++++++++---
 web/src/views/WorkspaceView.vue               | 15 +++++++++++--
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index 267299a6..5cb6259d 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -4,7 +4,7 @@
       <button
         type="button"
         class="workspace-nav-item"
-        :class="{ active: activeKey === 'personal' }"
+        :class="{ active: activeKey === 'personal' && currentPath !== savedArtifactsPath }"
         @click="$emit('select-personal')"
       >
         <FolderKanban :size="16" />
@@ -12,6 +12,19 @@
       </button>
     </section>
 
+    <section class="sidebar-section">
+      <div class="section-title">快速访问</div>
+      <button
+        type="button"
+        class="workspace-nav-item secondary"
+        :class="{ active: activeKey === 'personal' && currentPath === savedArtifactsPath }"
+        @click="$emit('select-path', savedArtifactsPath)"
+      >
+        <Archive :size="15" />
+        <span>Saved Artifacts</span>
+      </button>
+    </section>
+
     <section class="sidebar-section">
       <div class="section-title">知识库</div>
       <button
@@ -41,15 +54,18 @@
 </template>
 
 <script setup>
-import { FolderKanban, LibraryBig, UsersRound } from 'lucide-vue-next'
+import { Archive, FolderKanban, LibraryBig, UsersRound } from 'lucide-vue-next'
+
+const savedArtifactsPath = '/saved_artifacts'
 
 defineProps({
   activeKey: { type: String, default: 'personal' },
+  currentPath: { type: String, default: '/' },
   databases: { type: Array, default: () => [] },
   loadingDatabases: { type: Boolean, default: false }
 })
 
-defineEmits(['select-personal', 'select-database'])
+defineEmits(['select-personal', 'select-database', 'select-path'])
 </script>
 
 <style scoped lang="less">
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index 60b2203a..4864198a 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -25,10 +25,12 @@
         </button>
         <WorkspaceSidebar
           :active-key="activeSourceKey"
+          :current-path="currentPath"
           :databases="databases"
           :loading-databases="loadingDatabases"
           @select-personal="selectPersonalWorkspace"
           @select-database="selectDatabase"
+          @select-path="selectWorkspacePath"
         />
       </div>
       <button
@@ -268,12 +270,21 @@ const loadDatabases = async () => {
 const selectPersonalWorkspace = async () => {
   activeSourceKey.value = 'personal'
   selectedDatabase.value = null
+  closePreview()
   clearWorkspaceSelection()
-  if (!entries.value.length) {
-    await loadWorkspaceEntries(currentPath.value)
+  if (currentPath.value !== '/' || !entries.value.length) {
+    await loadWorkspaceEntries('/')
   }
 }
 
+const selectWorkspacePath = async (path) => {
+  activeSourceKey.value = 'personal'
+  selectedDatabase.value = null
+  closePreview()
+  clearWorkspaceSelection()
+  await loadWorkspaceEntries(path)
+}
+
 const selectDatabase = (database) => {
   closePreview()
   clearWorkspaceSelection()

From 6fcfb090de776f2f35f612d640483b7878966d84 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Thu, 30 Apr 2026 22:40:55 +0800
Subject: [PATCH 06/15] =?UTF-8?q?feat(workspace):=20=E9=87=8D=E6=9E=84?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E7=BB=84=E4=BB=B6=EF=BC=8C=E4=BC=98?=
 =?UTF-8?q?=E5=8C=96=E8=B7=AF=E5=BE=84=E9=80=89=E6=8B=A9=E5=92=8C=E9=9D=A2?=
 =?UTF-8?q?=E5=8C=85=E5=B1=91=E5=AF=BC=E8=88=AA=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Copilot <copilot@github.com>
---
 .../workspace/WorkspaceFileList.vue           | 108 +++++++++++-------
 .../workspace/WorkspacePreviewPane.vue        |   4 +
 .../components/workspace/WorkspaceSidebar.vue |   7 +-
 web/src/views/WorkspaceView.vue               |  12 +-
 4 files changed, 77 insertions(+), 54 deletions(-)

diff --git a/web/src/components/workspace/WorkspaceFileList.vue b/web/src/components/workspace/WorkspaceFileList.vue
index 0373c8c1..8902ec55 100644
--- a/web/src/components/workspace/WorkspaceFileList.vue
+++ b/web/src/components/workspace/WorkspaceFileList.vue
@@ -2,22 +2,34 @@
   <section class="workspace-file-list">
     <div class="file-list-header">
       <div class="path-line">
-        <button
-          type="button"
-          class="path-action"
-          :disabled="currentPath === '/'"
-          aria-label="返回上级目录"
-          @click="$emit('go-parent')"
-        >
-          <ChevronLeft :size="16" />
-        </button>
-        <span class="path-text" :title="currentPath">{{ currentPath }}</span>
+        <a-breadcrumb class="path-breadcrumb">
+          <a-breadcrumb-item v-for="item in breadcrumbItems" :key="item.path">
+            <button
+              type="button"
+              class="breadcrumb-action"
+              :class="{ current: item.path === currentPath }"
+              :disabled="item.path === currentPath"
+              :title="item.path"
+              @click="$emit('select-path', item.path)"
+            >
+              {{ item.name }}
+            </button>
+          </a-breadcrumb-item>
+        </a-breadcrumb>
       </div>
       <div class="list-actions">
         <span class="entry-count">{{ entries.length }} 项</span>
-        <a-button size="small" :type="selectionMode ? 'primary' : 'default'" @click="toggleSelectionMode">
-          多选
-        </a-button>
+        <a-tooltip title="多选">
+          <a-button
+            size="small"
+            class="lucide-icon-btn"
+            :type="selectionMode ? 'primary' : 'default'"
+            aria-label="多选"
+            @click="toggleSelectionMode"
+          >
+            <ListChecks :size="14" />
+          </a-button>
+        </a-tooltip>
         <a-button
           v-if="selectionMode"
           size="small"
@@ -122,7 +134,7 @@
 
 <script setup>
 import { computed } from 'vue'
-import { ChevronLeft, Download, Folder, MoreHorizontal, Trash2 } from 'lucide-vue-next'
+import { Download, Folder, ListChecks, MoreHorizontal, Trash2 } from 'lucide-vue-next'
 import { formatFileSize, formatRelativeTime, getFileIcon, getFileIconColor } from '@/utils/file_utils'
 
 const props = defineProps({
@@ -137,7 +149,7 @@ const props = defineProps({
 
 const emit = defineEmits([
   'select-entry',
-  'go-parent',
+  'select-path',
   'update:selectedPaths',
   'update:selectionMode',
   'delete-selected',
@@ -148,6 +160,23 @@ const emit = defineEmits([
 const selectedPathSet = computed(() => new Set(props.selectedPaths))
 const deletingPathSet = computed(() => new Set(props.deletingPaths))
 const entryPaths = computed(() => props.entries.map((entry) => entry.path))
+const breadcrumbItems = computed(() => {
+  const normalizedPath = props.currentPath || '/'
+  if (normalizedPath === '/') {
+    return [{ name: '工作区', path: '/' }]
+  }
+
+  const segments = normalizedPath.split('/').filter(Boolean)
+  return segments.reduce(
+    (items, segment) => {
+      const parentPath = items[items.length - 1].path
+      const path = parentPath === '/' ? `/${segment}` : `${parentPath}/${segment}`
+      items.push({ name: segment, path })
+      return items
+    },
+    [{ name: '工作区', path: '/' }]
+  )
+})
 
 const allSelected = computed(() => {
   return entryPaths.value.length > 0 && entryPaths.value.every((path) => selectedPathSet.value.has(path))
@@ -213,37 +242,34 @@ const toggleEntrySelection = (path, checked) => {
   flex: 0 0 auto;
 }
 
-.path-action {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 30px;
-  height: 30px;
-  border: 1px solid var(--gray-150);
-  border-radius: 8px;
-  background: var(--gray-0);
-  color: var(--gray-600);
-  cursor: pointer;
-
-  &:disabled {
-    color: var(--gray-300);
-    cursor: not-allowed;
-  }
-
-  &:hover:not(:disabled) {
-    background: var(--main-20);
-    color: var(--main-color);
-  }
-}
-
-.path-text {
+.path-breadcrumb {
   min-width: 0;
   overflow: hidden;
-  color: var(--gray-900);
   font-size: 14px;
-  font-weight: 600;
+}
+
+.breadcrumb-action {
+  max-width: 180px;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  background: transparent;
+  color: var(--main-800);
+  cursor: pointer;
+  font: inherit;
   text-overflow: ellipsis;
   white-space: nowrap;
+  font-weight: 400;
+
+  &:hover:not(:disabled) {
+    color: var(--main-600);
+  }
+
+  &.current,
+  &:disabled {
+    color: var(--gray-900);
+    cursor: default;
+  }
 }
 
 .entry-count {
diff --git a/web/src/components/workspace/WorkspacePreviewPane.vue b/web/src/components/workspace/WorkspacePreviewPane.vue
index 3c0b172f..2935a3f6 100644
--- a/web/src/components/workspace/WorkspacePreviewPane.vue
+++ b/web/src/components/workspace/WorkspacePreviewPane.vue
@@ -5,10 +5,12 @@
       :file="file"
       :file-path="filePath"
       :show-download="false"
+      :show-close="true"
       :show-fullscreen="true"
       :full-height="true"
       container-class="workspace-preview-container"
       content-class="workspace-preview-content"
+      @close="$emit('close')"
     />
     <div v-else-if="loading" class="preview-state">
       <a-spin />
@@ -31,6 +33,8 @@ defineProps({
   filePath: { type: String, default: '' },
   loading: { type: Boolean, default: false }
 })
+
+defineEmits(['close'])
 </script>
 
 <style scoped lang="less">
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index 5cb6259d..5be7eafb 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -104,8 +104,9 @@ defineEmits(['select-personal', 'select-database', 'select-path'])
   border: 1px solid transparent;
   border-radius: 8px;
   background: transparent;
-  color: var(--gray-700);
+  color: var(--gray-600);
   font-size: 14px;
+  font-weight: 600;
   text-align: left;
   cursor: pointer;
   transition:
@@ -118,13 +119,13 @@ defineEmits(['select-personal', 'select-database', 'select-path'])
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
+    font-weight: 500;
   }
 
   &:hover:not(:disabled),
   &.active {
     border-color: transparent;
-    background: var(--main-20);
-    color: var(--main-color);
+    color: var(--main-600);
   }
 
   &.secondary {
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index 4864198a..c7dd95d9 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -59,7 +59,7 @@
             :selection-mode="selectionMode"
             :loading="loadingTree"
             @select-entry="handleSelectEntry"
-            @go-parent="goParentDirectory"
+            @select-path="selectWorkspacePath"
             @update:selected-paths="selectedPaths = $event"
             @update:selection-mode="handleSelectionModeChange"
             @delete-selected="confirmDeleteEntries(selectedEntries)"
@@ -79,6 +79,7 @@
             :file="previewFile"
             :file-path="selectedEntry?.path || ''"
             :loading="loadingPreview"
+            @close="closePreview"
           />
         </template>
 
@@ -338,15 +339,6 @@ const closePreview = () => {
   revokePreviewObjectUrl()
 }
 
-const goParentDirectory = async () => {
-  if (currentPath.value === '/') return
-  const trimmed = currentPath.value.replace(/\/$/, '')
-  const parent = trimmed.slice(0, trimmed.lastIndexOf('/')) || '/'
-  closePreview()
-  clearWorkspaceSelection()
-  await loadWorkspaceEntries(parent)
-}
-
 const openCreateDirectoryModal = () => {
   if (activeSourceKey.value !== 'personal') return
   newDirectoryName.value = ''

From 981fd3170db2f6f34758f388dd9e3063d45dcdc0 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Fri, 1 May 2026 21:00:58 +0800
Subject: [PATCH 07/15] =?UTF-8?q?feat(workspace):=20=E5=A2=9E=E5=BC=BA?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=8A=9F=E8=83=BD=EF=BC=8C=E6=96=B0?=
 =?UTF-8?q?=E5=A2=9E=E9=BB=98=E8=AE=A4=20agents=20=E6=96=87=E4=BB=B6?=
 =?UTF-8?q?=E5=88=9B=E5=BB=BA=E5=8F=8A=E8=B7=AF=E5=BE=84=E7=AE=A1=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md                                     |  2 +
 .../yuxi/agents/backends/sandbox/__init__.py  |  4 ++
 .../yuxi/agents/backends/sandbox/paths.py     | 41 +++++++++++++-
 backend/package/yuxi/services/chat_service.py | 45 ++++++++++++++--
 .../yuxi/services/workspace_service.py        |  6 ++-
 backend/package/yuxi/utils/paths.py           |  4 ++
 .../unit/services/test_chat_service_sync.py   | 53 +++++++++++++++++++
 .../unit/services/test_workspace_service.py   | 40 ++++++++++++++
 docs/develop-guides/roadmap.md                |  2 +-
 .../components/workspace/WorkspaceSidebar.vue | 25 +++++++--
 10 files changed, 210 insertions(+), 12 deletions(-)
 create mode 100644 backend/test/unit/services/test_workspace_service.py

diff --git a/AGENTS.md b/AGENTS.md
index 6ee3826c..2d43c64b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,8 @@ make format        # 格式化代码
 - 尽量使用较新的语法，避免使用旧版本的语法（版本兼容到 3.12+）
 - 更新 [roadmap.md](docs/develop-guides/roadmap.md) 文档记录本次修改，多个类似的功能更新已经补充在一起
 - 开发完成后务必在 docker 中进行测试，可以读取 .env 获取管理员账户和密码
+- 不允许把代码写得稀碎：不要为简单线性逻辑拆出一堆细碎 helper；优先写成职责清晰、结构完整、可一眼读懂的实现。
+- 拆函数必须服务于明确的复用、隔离副作用或降低认知负担；如果拆分后调用链更绕、上下文更分散，就应合并回更直接的实现。
 
 **其他**：
 
diff --git a/backend/package/yuxi/agents/backends/sandbox/__init__.py b/backend/package/yuxi/agents/backends/sandbox/__init__.py
index d4417bfd..4dc1498d 100644
--- a/backend/package/yuxi/agents/backends/sandbox/__init__.py
+++ b/backend/package/yuxi/agents/backends/sandbox/__init__.py
@@ -2,10 +2,12 @@
 from .paths import (
     VIRTUAL_PATH_PREFIX,
     ensure_thread_dirs,
+    ensure_workspace_default_files,
     resolve_virtual_path,
     sandbox_outputs_dir,
     sandbox_uploads_dir,
     sandbox_user_data_dir,
+    sandbox_workspace_agents_prompt_file,
     sandbox_workspace_dir,
     virtual_path_for_thread_file,
 )
@@ -51,6 +53,7 @@
     "ProvisionerSandboxProvider",
     "VIRTUAL_PATH_PREFIX",
     "ensure_thread_dirs",
+    "ensure_workspace_default_files",
     "get_sandbox_provider",
     "init_sandbox_provider",
     "resolve_virtual_path",
@@ -58,6 +61,7 @@
     "sandbox_outputs_dir",
     "sandbox_uploads_dir",
     "sandbox_user_data_dir",
+    "sandbox_workspace_agents_prompt_file",
     "sandbox_workspace_dir",
     "shutdown_sandbox_provider",
     "virtual_path_for_thread_file",
diff --git a/backend/package/yuxi/agents/backends/sandbox/paths.py b/backend/package/yuxi/agents/backends/sandbox/paths.py
index b7dd23b9..598d7fde 100644
--- a/backend/package/yuxi/agents/backends/sandbox/paths.py
+++ b/backend/package/yuxi/agents/backends/sandbox/paths.py
@@ -4,7 +4,15 @@
 from pathlib import Path
 
 from yuxi import config as conf
-from yuxi.utils.paths import OUTPUTS_DIR_NAME, UPLOADS_DIR_NAME, VIRTUAL_PATH_PREFIX, WORKSPACE_DIR_NAME
+from yuxi.utils.logging_config import logger
+from yuxi.utils.paths import (
+    OUTPUTS_DIR_NAME,
+    UPLOADS_DIR_NAME,
+    VIRTUAL_PATH_PREFIX,
+    WORKSPACE_AGENTS_DIR_NAME,
+    WORKSPACE_AGENTS_PROMPT_FILE_NAME,
+    WORKSPACE_DIR_NAME,
+)
 
 _SAFE_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
 
@@ -51,6 +59,33 @@ def sandbox_workspace_dir(thread_id: str, user_id: str) -> Path:
     return _global_user_data_dir(user_id) / WORKSPACE_DIR_NAME
 
 
+def sandbox_workspace_agents_prompt_file(thread_id: str, user_id: str) -> Path:
+    return sandbox_workspace_dir(thread_id, user_id) / WORKSPACE_AGENTS_DIR_NAME / WORKSPACE_AGENTS_PROMPT_FILE_NAME
+
+
+def ensure_workspace_default_files(workspace_dir: Path) -> None:
+    agents_dir = workspace_dir / WORKSPACE_AGENTS_DIR_NAME
+    agents_file = agents_dir / WORKSPACE_AGENTS_PROMPT_FILE_NAME
+
+    try:
+        agents_dir.mkdir(parents=True, exist_ok=True)
+    except FileExistsError:
+        logger.warning("工作区默认 Agents 目录创建失败：路径已被文件占用")
+        return
+    except OSError as exc:
+        logger.warning(f"工作区默认 Agents 目录初始化失败: {exc}")
+        return
+
+    try:
+        with agents_file.open("xb"):
+            pass
+    except FileExistsError:
+        if agents_file.is_dir():
+            logger.warning("工作区默认 AGENTS.md 创建失败：路径已被目录占用")
+    except OSError as exc:
+        logger.warning(f"工作区默认 Agents 文件初始化失败: {exc}")
+
+
 def sandbox_uploads_dir(thread_id: str) -> Path:
     return _thread_root_dir(thread_id) / UPLOADS_DIR_NAME
 
@@ -61,7 +96,9 @@ def sandbox_outputs_dir(thread_id: str) -> Path:
 
 def ensure_thread_dirs(thread_id: str, user_id: str) -> None:
     _global_user_data_dir(user_id).mkdir(parents=True, exist_ok=True)
-    sandbox_workspace_dir(thread_id, user_id).mkdir(parents=True, exist_ok=True)
+    workspace_dir = sandbox_workspace_dir(thread_id, user_id)
+    workspace_dir.mkdir(parents=True, exist_ok=True)
+    ensure_workspace_default_files(workspace_dir)
     sandbox_uploads_dir(thread_id).mkdir(parents=True, exist_ok=True)
     sandbox_outputs_dir(thread_id).mkdir(parents=True, exist_ok=True)
 
diff --git a/backend/package/yuxi/services/chat_service.py b/backend/package/yuxi/services/chat_service.py
index b9cb9def..3430a318 100644
--- a/backend/package/yuxi/services/chat_service.py
+++ b/backend/package/yuxi/services/chat_service.py
@@ -9,6 +9,7 @@
 from langchain.messages import AIMessage, AIMessageChunk, HumanMessage
 from langgraph.types import Command
 from yuxi import config as conf
+from yuxi.agents.backends.sandbox.paths import sandbox_workspace_agents_prompt_file
 from yuxi.agents.buildin import agent_manager
 from yuxi.agents.state import AgentStatePayload
 from yuxi.plugins.guard import content_guard
@@ -30,6 +31,43 @@
     normalize_questions as _normalize_interrupt_questions,
 )
 
+WORKSPACE_AGENTS_PROMPT_MAX_BYTES = 64 * 1024
+
+
+def _load_workspace_agents_prompt(thread_id: str, user_id: str) -> str:
+    prompt_file = sandbox_workspace_agents_prompt_file(thread_id, user_id)
+    try:
+        with prompt_file.open("rb") as buffer:
+            content = buffer.read(WORKSPACE_AGENTS_PROMPT_MAX_BYTES + 1)
+    except FileNotFoundError:
+        return ""
+    except IsADirectoryError:
+        logger.warning("读取工作区 AGENTS.md 失败: 路径是目录")
+        return ""
+    except OSError as exc:
+        logger.warning(f"读取工作区 AGENTS.md 失败: {exc}")
+        return ""
+
+    prompt = content[:WORKSPACE_AGENTS_PROMPT_MAX_BYTES].decode("utf-8", errors="replace").strip()
+    if not prompt:
+        return ""
+    if len(content) > WORKSPACE_AGENTS_PROMPT_MAX_BYTES:
+        return f"{prompt}\n\n[AGENTS.md 内容已截断]"
+    return prompt
+
+
+async def _build_agent_input_context(agent_config: dict, *, thread_id: str, user_id: str) -> dict:
+    input_context = dict(agent_config or {})
+    agents_prompt = await asyncio.to_thread(_load_workspace_agents_prompt, thread_id, user_id)
+
+    if agents_prompt:
+        agents_section = f"用户工作区 agents/AGENTS.md 内容：\n{agents_prompt}"
+        base_prompt = str(input_context.get("system_prompt") or "").rstrip()
+        input_context["system_prompt"] = f"{base_prompt}\n\n{agents_section}" if base_prompt else agents_section
+
+    input_context.update({"user_id": user_id, "thread_id": thread_id})
+    return input_context
+
 
 def _build_state_files(attachments: list[dict]) -> dict:
     """将附件列表转换为 StateBackend 格式的 files 字典
@@ -560,7 +598,7 @@ async def agent_chat(
         thread_id = str(uuid.uuid4())
         logger.warning(f"No thread_id provided, generated new thread_id: {thread_id}")
 
-    input_context = agent_config | {"user_id": user_id, "thread_id": thread_id}
+    input_context = await _build_agent_input_context(agent_config, thread_id=thread_id, user_id=user_id)
     langfuse_run = _build_langfuse_run_context(
         current_user=current_user,
         thread_id=thread_id,
@@ -776,7 +814,7 @@ def make_chunk(content=None, **kwargs):
         thread_id = str(uuid.uuid4())
         logger.warning(f"No thread_id provided, generated new thread_id: {thread_id}")
 
-    input_context = agent_config | {"user_id": user_id, "thread_id": thread_id}
+    input_context = await _build_agent_input_context(agent_config, thread_id=thread_id, user_id=user_id)
     langfuse_run = _build_langfuse_run_context(
         current_user=current_user,
         thread_id=thread_id,
@@ -1011,8 +1049,7 @@ def make_resume_chunk(content=None, **kwargs):
         return
 
     context = agent.context_schema()
-    context.update(agent_config or {})
-    context.update({"user_id": user_id, "thread_id": thread_id})
+    context.update(await _build_agent_input_context(agent_config or {}, thread_id=thread_id, user_id=user_id))
     graph = await agent.get_graph(context=context)
     langfuse_run = _build_langfuse_run_context(
         current_user=current_user,
diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
index 081e218d..14fe0e74 100644
--- a/backend/package/yuxi/services/workspace_service.py
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -12,7 +12,7 @@
 from fastapi import HTTPException, UploadFile
 from fastapi.responses import FileResponse, StreamingResponse
 
-from yuxi.agents.backends.sandbox.paths import _global_user_data_dir
+from yuxi.agents.backends.sandbox.paths import _global_user_data_dir, ensure_workspace_default_files
 from yuxi.services.viewer_filesystem_service import _detect_preview_type
 from yuxi.storage.postgres.models_business import User
 from yuxi.utils.datetime_utils import utc_isoformat_from_timestamp
@@ -25,7 +25,9 @@ def _workspace_root(user: User) -> Path:
     except ValueError as exc:
         raise HTTPException(status_code=403, detail="Access denied") from exc
     root.mkdir(parents=True, exist_ok=True)
-    return root.resolve()
+    resolved_root = root.resolve()
+    ensure_workspace_default_files(resolved_root)
+    return resolved_root
 
 
 def _normalize_workspace_path(path: str | None) -> PurePosixPath:
diff --git a/backend/package/yuxi/utils/paths.py b/backend/package/yuxi/utils/paths.py
index 8c91a0d9..304b5514 100644
--- a/backend/package/yuxi/utils/paths.py
+++ b/backend/package/yuxi/utils/paths.py
@@ -4,6 +4,8 @@
 
 VIRTUAL_PATH_PREFIX = config.sandbox_virtual_path_prefix
 WORKSPACE_DIR_NAME = "workspace"
+WORKSPACE_AGENTS_DIR_NAME = "agents"
+WORKSPACE_AGENTS_PROMPT_FILE_NAME = "AGENTS.md"
 UPLOADS_DIR_NAME = "uploads"
 OUTPUTS_DIR_NAME = "outputs"
 VIRTUAL_SKILLS_PATH = "/home/gem/skills"
@@ -16,6 +18,8 @@
 __all__ = [
     "VIRTUAL_PATH_PREFIX",
     "WORKSPACE_DIR_NAME",
+    "WORKSPACE_AGENTS_DIR_NAME",
+    "WORKSPACE_AGENTS_PROMPT_FILE_NAME",
     "UPLOADS_DIR_NAME",
     "OUTPUTS_DIR_NAME",
     "VIRTUAL_PATH_WORKSPACE",
diff --git a/backend/test/unit/services/test_chat_service_sync.py b/backend/test/unit/services/test_chat_service_sync.py
index d00ac9c9..16a14763 100644
--- a/backend/test/unit/services/test_chat_service_sync.py
+++ b/backend/test/unit/services/test_chat_service_sync.py
@@ -8,6 +8,21 @@
 from yuxi.services import chat_service as svc
 
 
+def _empty_agents_prompt(_thread_id: str, _user_id: str) -> str:
+    return ""
+
+
+class _FakeAgentConfigRepo:
+    def __init__(self, _db):
+        pass
+
+    async def get_by_id(self, config_id: int):
+        return SimpleNamespace(id=config_id)
+
+    async def get_or_create_default(self, *, department_id: str, agent_id: str, created_by: str):
+        return SimpleNamespace(id=999, department_id=department_id, agent_id=agent_id, created_by=created_by)
+
+
 class _FakeConvRepo:
     def __init__(self, _db):
         self.saved_messages: list[dict] = []
@@ -112,10 +127,12 @@ def fake_get_trace_info(_run_context):
     monkeypatch.setattr(svc, "_build_langfuse_run_context", fake_build_langfuse_run_context)
     monkeypatch.setattr(svc, "get_trace_info", fake_get_trace_info)
     monkeypatch.setattr(svc, "flush_langfuse", lambda: calls.setdefault("flushed", True))
+    monkeypatch.setattr(svc, "_load_workspace_agents_prompt", _empty_agents_prompt)
 
     monkeypatch.setattr(svc.agent_manager, "get_agent", lambda agent_id: FakeAgent())
     monkeypatch.setattr(svc, "get_agent_config_by_id", fake_get_agent_config_by_id)
     monkeypatch.setattr(svc, "ConversationRepository", _FakeConvRepo)
+    monkeypatch.setattr(svc, "AgentConfigRepository", _FakeAgentConfigRepo)
     monkeypatch.setattr(svc, "save_messages_from_langgraph_state", fake_save_messages_from_langgraph_state)
     monkeypatch.setattr(svc.content_guard, "check", fake_guard_check)
 
@@ -193,10 +210,12 @@ async def fake_guard_check(_content):
     )
     monkeypatch.setattr(svc, "get_trace_info", lambda _run_context: {})
     monkeypatch.setattr(svc, "flush_langfuse", lambda: None)
+    monkeypatch.setattr(svc, "_load_workspace_agents_prompt", _empty_agents_prompt)
 
     monkeypatch.setattr(svc.agent_manager, "get_agent", lambda agent_id: FakeAgent())
     monkeypatch.setattr(svc, "get_agent_config_by_id", fake_get_agent_config_by_id)
     monkeypatch.setattr(svc, "ConversationRepository", _FakeConvRepo)
+    monkeypatch.setattr(svc, "AgentConfigRepository", _FakeAgentConfigRepo)
     monkeypatch.setattr(svc, "save_messages_from_langgraph_state", fake_save_messages_from_langgraph_state)
     monkeypatch.setattr(svc.content_guard, "check", fake_guard_check)
 
@@ -214,3 +233,37 @@ async def fake_guard_check(_content):
     assert result["response"] == "Need input later"
     assert result["thread_id"] == "thread-2"
     assert result["request_id"] == "req-2"
+
+
+@pytest.mark.asyncio
+async def test_build_agent_input_context_merges_workspace_agents_prompt(monkeypatch: pytest.MonkeyPatch):
+    def fake_agents_prompt(_thread_id: str, _user_id: str) -> str:
+        return "回答前先读取 AGENTS.md"
+
+    monkeypatch.setattr(svc, "_load_workspace_agents_prompt", fake_agents_prompt)
+
+    context = await svc._build_agent_input_context(
+        {"system_prompt": "原始系统提示词", "temperature": 0.1},
+        thread_id="thread-1",
+        user_id="user-1",
+    )
+
+    assert context["system_prompt"] == "原始系统提示词\n\n用户工作区 agents/AGENTS.md 内容：\n回答前先读取 AGENTS.md"
+    assert context["temperature"] == 0.1
+    assert context["thread_id"] == "thread-1"
+    assert context["user_id"] == "user-1"
+
+
+@pytest.mark.asyncio
+async def test_build_agent_input_context_keeps_prompt_when_workspace_agents_prompt_empty(
+    monkeypatch: pytest.MonkeyPatch,
+):
+    monkeypatch.setattr(svc, "_load_workspace_agents_prompt", _empty_agents_prompt)
+
+    context = await svc._build_agent_input_context(
+        {"system_prompt": "原始系统提示词"},
+        thread_id="thread-1",
+        user_id="user-1",
+    )
+
+    assert context["system_prompt"] == "原始系统提示词"
diff --git a/backend/test/unit/services/test_workspace_service.py b/backend/test/unit/services/test_workspace_service.py
new file mode 100644
index 00000000..38d3b0ee
--- /dev/null
+++ b/backend/test/unit/services/test_workspace_service.py
@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+from types import SimpleNamespace
+
+from yuxi.agents.backends.sandbox import paths as workspace_paths
+from yuxi.services import workspace_service as svc
+
+
+def test_workspace_root_creates_default_agents_prompt_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+
+    root = svc._workspace_root(SimpleNamespace(id="user-1"))
+
+    agents_file = root / "agents" / "AGENTS.md"
+    assert agents_file.is_file()
+    assert agents_file.read_text(encoding="utf-8") == ""
+
+
+def test_ensure_thread_dirs_creates_default_agents_prompt_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+
+    workspace_paths.ensure_thread_dirs("thread-1", "user-1")
+
+    agents_file = tmp_path / "threads" / "shared" / "user-1" / "workspace" / "agents" / "AGENTS.md"
+    assert agents_file.is_file()
+    assert agents_file.read_text(encoding="utf-8") == ""
+
+
+def test_workspace_root_keeps_existing_agents_prompt_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    agents_dir = tmp_path / "threads" / "shared" / "user-1" / "workspace" / "agents"
+    agents_dir.mkdir(parents=True)
+    agents_file = agents_dir / "AGENTS.md"
+    agents_file.write_text("保留已有内容", encoding="utf-8")
+
+    root = svc._workspace_root(SimpleNamespace(id="user-1"))
+
+    assert root == tmp_path / "threads" / "shared" / "user-1" / "workspace"
+    assert agents_file.read_text(encoding="utf-8") == "保留已有内容"
diff --git a/docs/develop-guides/roadmap.md b/docs/develop-guides/roadmap.md
index 10fd42d1..f7bdb033 100644
--- a/docs/develop-guides/roadmap.md
+++ b/docs/develop-guides/roadmap.md
@@ -37,7 +37,7 @@
 ### 0.6.2 开发记录
 
 <!-- 0.6.2 的内容请放在这里 -->
-- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；支持新建文件夹、上传文件、下载文件、删除文件/文件夹和多选删除；知识库与团队空间入口先展示到占位层级。
+- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；支持新建文件夹、上传文件、下载文件、删除文件/文件夹和多选删除；知识库与团队空间入口先展示到占位层级；默认创建 `agents/AGENTS.md`，并在 Agent 执行时将其内容追加到系统提示词。
 - 扩展管理界面交互逻辑重构：将 MCP / Subagents / Skills 三个标签页从「左侧边栏 + 右侧详情面板」布局重构为「卡片式网格布局 + 路由跳转二级页面」布局，工具标签页改为卡片网格布局 + 弹窗详情（保持弹窗内容不变）。新增共享组件 `ExtensionCard`、`ExtensionCardGrid`、`ExtensionToolbar`、`ExtensionDetailLayout`，详情页（`McpDetailView`、`SubagentDetailView`、`SkillDetailView`）使用居中宽度限制，路由规划为 `/extensions/mcp/:name`、`/extensions/subagent/:name`、`/extensions/skill/:slug`。
 - 统一卡片样式：`ExtensionCard` 新增 `tags` prop 支持传入 `[{label, color}]` 数组，内部使用 `<a-tag bordered=false size=small>` 渲染，与知识库卡片标签风格统一；知识库列表页 `DataBaseView` 改用 `ExtensionCard` + `ExtensionCardGrid` 替代原有自定义卡片，移除冗余 card 样式。
 - 调整应用主导航：`AppLayout` 从默认窄栏升级为默认展开的侧边栏，保留折叠态图标导航；侧边栏样式收敛为 14px 文本 + 18px 图标的标准紧凑密度，并统一导航项、任务中心、GitHub、用户信息的图标与文字对齐。折叠态改为仅通过显式按钮展开，避免空白区域误触发。
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index 5be7eafb..832e3dff 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -4,7 +4,7 @@
       <button
         type="button"
         class="workspace-nav-item"
-        :class="{ active: activeKey === 'personal' && currentPath !== savedArtifactsPath }"
+        :class="{ active: activeKey === 'personal' && !isQuickAccessPath(currentPath) }"
         @click="$emit('select-personal')"
       >
         <FolderKanban :size="16" />
@@ -17,12 +17,21 @@
       <button
         type="button"
         class="workspace-nav-item secondary"
-        :class="{ active: activeKey === 'personal' && currentPath === savedArtifactsPath }"
+        :class="{ active: activeKey === 'personal' && isSameOrChildPath(currentPath, savedArtifactsPath) }"
         @click="$emit('select-path', savedArtifactsPath)"
       >
         <Archive :size="15" />
         <span>Saved Artifacts</span>
       </button>
+      <button
+        type="button"
+        class="workspace-nav-item secondary"
+        :class="{ active: activeKey === 'personal' && isSameOrChildPath(currentPath, agentsPath) }"
+        @click="$emit('select-path', agentsPath)"
+      >
+        <Bot :size="15" />
+        <span>Agents</span>
+      </button>
     </section>
 
     <section class="sidebar-section">
@@ -54,9 +63,19 @@
 </template>
 
 <script setup>
-import { Archive, FolderKanban, LibraryBig, UsersRound } from 'lucide-vue-next'
+import { Archive, Bot, FolderKanban, LibraryBig, UsersRound } from 'lucide-vue-next'
 
 const savedArtifactsPath = '/saved_artifacts'
+const agentsPath = '/agents/'
+const quickAccessPaths = [savedArtifactsPath, agentsPath]
+
+const normalizePath = (path) => String(path || '/').replace(/\/$/, '') || '/'
+const isSameOrChildPath = (path, targetPath) => {
+  const current = normalizePath(path)
+  const target = normalizePath(targetPath)
+  return current === target || current.startsWith(`${target}/`)
+}
+const isQuickAccessPath = (path) => quickAccessPaths.some((targetPath) => isSameOrChildPath(path, targetPath))
 
 defineProps({
   activeKey: { type: String, default: 'personal' },

From 596eeeaaaca674c909b1b66ac8aaabc366ae3d0e Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Fri, 1 May 2026 21:26:51 +0800
Subject: [PATCH 08/15] =?UTF-8?q?feat(workspace):=20=E6=96=B0=E5=A2=9E?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E6=96=87=E4=BB=B6=E5=86=85=E5=AE=B9?=
 =?UTF-8?q?=E7=BC=96=E8=BE=91=E5=8A=9F=E8=83=BD=EF=BC=8C=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=20Markdown=20=E5=92=8C=20TXT=20=E6=96=87=E4=BB=B6=E7=9A=84?=
 =?UTF-8?q?=E4=BF=9D=E5=AD=98=E4=B8=8E=E9=A2=84=E8=A7=88?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../yuxi/services/workspace_service.py        |  34 +++++
 backend/server/routers/workspace_router.py    |  18 +++
 .../unit/services/test_workspace_service.py   |  76 +++++++++++
 docs/develop-guides/roadmap.md                |   2 +-
 web/src/apis/workspace_api.js                 |   6 +-
 web/src/components/AgentFilePreview.vue       | 129 +++++++++++++++++-
 .../workspace/WorkspacePreviewPane.vue        |  11 +-
 web/src/views/WorkspaceView.vue               |  31 +++++
 8 files changed, 296 insertions(+), 11 deletions(-)

diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
index 14fe0e74..970c2d18 100644
--- a/backend/package/yuxi/services/workspace_service.py
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -19,6 +19,9 @@
 from yuxi.utils.paths import WORKSPACE_DIR_NAME
 
 
+EDITABLE_WORKSPACE_SUFFIXES = {".md", ".markdown", ".mdx", ".txt"}
+
+
 def _workspace_root(user: User) -> Path:
     try:
         root = _global_user_data_dir(str(user.id)) / WORKSPACE_DIR_NAME
@@ -143,6 +146,37 @@ async def read_workspace_file_content(*, path: str, current_user: User) -> dict:
     }
 
 
+async def write_workspace_file_content(*, path: str, content: str, current_user: User) -> dict:
+    root = _workspace_root(current_user)
+    target = _resolve_workspace_path(current_user, path)
+    if not target.exists():
+        raise HTTPException(status_code=404, detail="文件不存在")
+    if not target.is_file():
+        raise HTTPException(status_code=400, detail="当前路径是目录")
+    if target.suffix.lower() not in EDITABLE_WORKSPACE_SUFFIXES:
+        raise HTTPException(status_code=400, detail="当前文件类型不支持编辑")
+
+    raw_content = await asyncio.to_thread(target.read_bytes)
+    preview_type, supported, _message = _detect_preview_type(path, raw_content)
+    if preview_type not in {"markdown", "text"} or not supported:
+        raise HTTPException(status_code=400, detail="当前文件类型不支持编辑")
+    try:
+        raw_content.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise HTTPException(status_code=400, detail="当前文件不是 UTF-8 文本") from exc
+
+    try:
+        await asyncio.to_thread(target.write_text, content, encoding="utf-8")
+    except PermissionError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    return {
+        "success": True,
+        "path": _normalize_workspace_path(path).as_posix(),
+        "entry": _entry_for_path(root, target),
+    }
+
+
 async def delete_workspace_path(*, path: str, current_user: User) -> dict:
     root = _workspace_root(current_user)
     target = _resolve_workspace_path(current_user, path)
diff --git a/backend/server/routers/workspace_router.py b/backend/server/routers/workspace_router.py
index ba713266..671c08a4 100644
--- a/backend/server/routers/workspace_router.py
+++ b/backend/server/routers/workspace_router.py
@@ -11,6 +11,7 @@
     list_workspace_tree,
     read_workspace_file_content,
     upload_workspace_file,
+    write_workspace_file_content,
 )
 from yuxi.storage.postgres.models_business import User
 
@@ -22,6 +23,11 @@ class CreateWorkspaceDirectoryRequest(BaseModel):
     name: str
 
 
+class UpdateWorkspaceFileContentRequest(BaseModel):
+    path: str
+    content: str
+
+
 @workspace.get("/tree", response_model=dict)
 async def get_workspace_tree(
     path: str = Query("/", description="工作区目录路径"),
@@ -38,6 +44,18 @@ async def get_workspace_file(
     return await read_workspace_file_content(path=path, current_user=current_user)
 
 
+@workspace.put("/file", response_model=dict)
+async def update_workspace_file(
+    payload: UpdateWorkspaceFileContentRequest,
+    current_user: User = Depends(get_required_user),
+):
+    return await write_workspace_file_content(
+        path=payload.path,
+        content=payload.content,
+        current_user=current_user,
+    )
+
+
 @workspace.delete("/file", response_model=dict)
 async def delete_workspace_file_route(
     path: str = Query(..., description="工作区文件或目录路径"),
diff --git a/backend/test/unit/services/test_workspace_service.py b/backend/test/unit/services/test_workspace_service.py
index 38d3b0ee..798fe47d 100644
--- a/backend/test/unit/services/test_workspace_service.py
+++ b/backend/test/unit/services/test_workspace_service.py
@@ -3,6 +3,9 @@
 from pathlib import Path
 from types import SimpleNamespace
 
+import pytest
+from fastapi import HTTPException
+
 from yuxi.agents.backends.sandbox import paths as workspace_paths
 from yuxi.services import workspace_service as svc
 
@@ -38,3 +41,76 @@ def test_workspace_root_keeps_existing_agents_prompt_file(tmp_path: Path, monkey
 
     assert root == tmp_path / "threads" / "shared" / "user-1" / "workspace"
     assert agents_file.read_text(encoding="utf-8") == "保留已有内容"
+
+
+@pytest.mark.asyncio
+async def test_write_workspace_file_content_updates_markdown_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    target = root / "note.md"
+    target.write_text("旧内容", encoding="utf-8")
+
+    result = await svc.write_workspace_file_content(path="/note.md", content="# 新内容", current_user=user)
+
+    assert result["success"] is True
+    assert result["path"] == "/note.md"
+    assert result["entry"]["path"] == "/note.md"
+    assert target.read_text(encoding="utf-8") == "# 新内容"
+
+
+@pytest.mark.asyncio
+async def test_write_workspace_file_content_updates_txt_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    target = root / "note.txt"
+    target.write_text("old", encoding="utf-8")
+
+    await svc.write_workspace_file_content(path="/note.txt", content="new", current_user=user)
+
+    assert target.read_text(encoding="utf-8") == "new"
+
+
+@pytest.mark.asyncio
+async def test_write_workspace_file_content_rejects_unsupported_suffix(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    target = root / "script.py"
+    target.write_text("print('hello')", encoding="utf-8")
+
+    with pytest.raises(HTTPException) as exc_info:
+        await svc.write_workspace_file_content(path="/script.py", content="print('bye')", current_user=user)
+
+    assert exc_info.value.status_code == 400
+    assert target.read_text(encoding="utf-8") == "print('hello')"
+
+
+@pytest.mark.asyncio
+async def test_write_workspace_file_content_rejects_directory_and_missing_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    svc._workspace_root(user)
+
+    with pytest.raises(HTTPException) as directory_error:
+        await svc.write_workspace_file_content(path="/agents/", content="x", current_user=user)
+    with pytest.raises(HTTPException) as missing_error:
+        await svc.write_workspace_file_content(path="/missing.md", content="x", current_user=user)
+
+    assert directory_error.value.status_code == 400
+    assert missing_error.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_write_workspace_file_content_blocks_path_traversal(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+
+    with pytest.raises(HTTPException) as exc_info:
+        await svc.write_workspace_file_content(
+            path="/../outside.md",
+            content="x",
+            current_user=SimpleNamespace(id="user-1"),
+        )
+
+    assert exc_info.value.status_code == 403
diff --git a/docs/develop-guides/roadmap.md b/docs/develop-guides/roadmap.md
index f7bdb033..9b59a963 100644
--- a/docs/develop-guides/roadmap.md
+++ b/docs/develop-guides/roadmap.md
@@ -37,7 +37,7 @@
 ### 0.6.2 开发记录
 
 <!-- 0.6.2 的内容请放在这里 -->
-- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；支持新建文件夹、上传文件、下载文件、删除文件/文件夹和多选删除；知识库与团队空间入口先展示到占位层级；默认创建 `agents/AGENTS.md`，并在 Agent 执行时将其内容追加到系统提示词。
+- 新增个人工作区预览与管理：提供独立于对话 thread 的用户级 workspace API，并增加“工作区”页面，用于浏览个人 workspace 文件、预览 Markdown/文本/代码/图片/PDF；支持新建文件夹、上传文件、下载文件、删除文件/文件夹和多选删除；工作区预览支持 Markdown/TXT 在右侧预览框内切换编辑并保存，其他格式和非工作区预览默认只读；知识库与团队空间入口先展示到占位层级；默认创建 `agents/AGENTS.md`，并在 Agent 执行时将其内容追加到系统提示词。
 - 扩展管理界面交互逻辑重构：将 MCP / Subagents / Skills 三个标签页从「左侧边栏 + 右侧详情面板」布局重构为「卡片式网格布局 + 路由跳转二级页面」布局，工具标签页改为卡片网格布局 + 弹窗详情（保持弹窗内容不变）。新增共享组件 `ExtensionCard`、`ExtensionCardGrid`、`ExtensionToolbar`、`ExtensionDetailLayout`，详情页（`McpDetailView`、`SubagentDetailView`、`SkillDetailView`）使用居中宽度限制，路由规划为 `/extensions/mcp/:name`、`/extensions/subagent/:name`、`/extensions/skill/:slug`。
 - 统一卡片样式：`ExtensionCard` 新增 `tags` prop 支持传入 `[{label, color}]` 数组，内部使用 `<a-tag bordered=false size=small>` 渲染，与知识库卡片标签风格统一；知识库列表页 `DataBaseView` 改用 `ExtensionCard` + `ExtensionCardGrid` 替代原有自定义卡片，移除冗余 card 样式。
 - 调整应用主导航：`AppLayout` 从默认窄栏升级为默认展开的侧边栏，保留折叠态图标导航；侧边栏样式收敛为 14px 文本 + 18px 图标的标准紧凑密度，并统一导航项、任务中心、GitHub、用户信息的图标与文字对齐。折叠态改为仅通过显式按钮展开，避免空白区域误触发。
diff --git a/web/src/apis/workspace_api.js b/web/src/apis/workspace_api.js
index 83a56715..a4cdbf03 100644
--- a/web/src/apis/workspace_api.js
+++ b/web/src/apis/workspace_api.js
@@ -1,4 +1,4 @@
-import { apiDelete, apiGet, apiPost } from './base'
+import { apiDelete, apiGet, apiPost, apiPut } from './base'
 
 const buildQuery = (params) => {
   const query = new URLSearchParams()
@@ -20,6 +20,10 @@ export const getWorkspaceFileContent = (path) => {
   return apiGet(`/api/workspace/file?${query}`)
 }
 
+export const saveWorkspaceFileContent = (path, content) => {
+  return apiPut('/api/workspace/file', { path, content })
+}
+
 export const deleteWorkspacePath = (path) => {
   const query = buildQuery({ path })
   return apiDelete(`/api/workspace/file?${query}`)
diff --git a/web/src/components/AgentFilePreview.vue b/web/src/components/AgentFilePreview.vue
index 8eab4a69..9fd0956d 100644
--- a/web/src/components/AgentFilePreview.vue
+++ b/web/src/components/AgentFilePreview.vue
@@ -9,6 +9,42 @@
         <span class="file-path-title">{{ filePath }}</span>
       </div>
       <div class="modal-actions">
+        <div v-if="canEdit" class="preview-mode-switch">
+          <button
+            class="preview-mode-btn"
+            :class="{ active: editMode === 'preview' }"
+            @click="editMode = 'preview'"
+            title="预览"
+          >
+            <Eye :size="16" />
+          </button>
+          <button
+            class="preview-mode-btn"
+            :class="{ active: editMode === 'edit' }"
+            @click="editMode = 'edit'"
+            title="编辑"
+          >
+            <Pencil :size="16" />
+          </button>
+        </div>
+        <button
+          v-if="canEdit && editMode === 'edit'"
+          class="modal-action-btn"
+          :disabled="saving || !draftChanged"
+          @click="requestSave"
+          title="保存"
+        >
+          <Save :size="18" />
+        </button>
+        <button
+          v-if="canEdit && editMode === 'edit'"
+          class="modal-action-btn"
+          :disabled="saving"
+          @click="cancelEdit"
+          title="取消编辑"
+        >
+          <X :size="18" />
+        </button>
         <div v-if="isHtmlFile" class="preview-mode-switch">
           <button
             class="preview-mode-btn"
@@ -50,7 +86,15 @@
     </div>
 
     <div class="file-content" :class="contentClass">
-      <template v-if="file?.previewType === 'image' && file?.previewUrl">
+      <template v-if="canEdit && editMode === 'edit'">
+        <textarea
+          v-model="draftContent"
+          class="file-edit-textarea"
+          :disabled="saving"
+          spellcheck="false"
+        />
+      </template>
+      <template v-else-if="file?.previewType === 'image' && file?.previewUrl">
         <div class="image-preview-wrapper">
           <img :src="file.previewUrl" :alt="filePath" class="image-preview" />
         </div>
@@ -190,13 +234,20 @@
 
 <script setup>
 import { computed, onUnmounted, ref, watch } from 'vue'
-import { Code2, Download, Globe, Maximize2, X } from 'lucide-vue-next'
+import { Code2, Download, Eye, Globe, Maximize2, Pencil, Save, X } from 'lucide-vue-next'
 import { MdPreview } from 'md-editor-v3'
 import hljs from 'highlight.js/lib/common'
 import 'md-editor-v3/lib/preview.css'
 import { useThemeStore } from '@/stores/theme'
 import { getFileIcon, getFileIconColor } from '@/utils/file_utils'
-import { getCodeLanguageByPath, isHtmlPreview, isMarkdownPreview } from '@/utils/file_preview'
+import {
+  getCodeLanguageByPath,
+  getPreviewFileExtension,
+  isHtmlPreview,
+  isMarkdownPreview
+} from '@/utils/file_preview'
+
+const EDITABLE_EXTENSIONS = new Set(['.md', '.markdown', '.mdx', '.txt'])
 
 const props = defineProps({
   file: {
@@ -227,6 +278,14 @@ const props = defineProps({
     type: Boolean,
     default: false
   },
+  editable: {
+    type: Boolean,
+    default: false
+  },
+  saving: {
+    type: Boolean,
+    default: false
+  },
   containerClass: {
     type: [String, Array, Object],
     default: ''
@@ -237,15 +296,26 @@ const props = defineProps({
   }
 })
 
-defineEmits(['close', 'download'])
+const emit = defineEmits(['close', 'download', 'save'])
 
 const themeStore = useThemeStore()
 const theme = computed(() => (themeStore.isDark ? 'dark' : 'light'))
 const htmlPreviewMode = ref('render')
+const editMode = ref('preview')
+const draftContent = ref('')
 const fullscreenPreviewVisible = ref(false)
 const htmlPreviewRenderKey = ref(0)
 
 const isMarkdown = computed(() => isMarkdownPreview(props.filePath, props.file?.previewType))
+const canEdit = computed(
+  () =>
+    props.editable &&
+    props.file?.supported !== false &&
+    typeof props.file?.content === 'string' &&
+    EDITABLE_EXTENSIONS.has(getPreviewFileExtension(props.filePath))
+)
+const savedContent = computed(() => formatContent(props.file?.content))
+const draftChanged = computed(() => draftContent.value !== savedContent.value)
 const isHtmlFile = computed(
   () =>
     props.file?.previewType === 'text' &&
@@ -293,6 +363,20 @@ const formatContent = (content) => {
   return String(content)
 }
 
+const syncDraftContent = () => {
+  draftContent.value = savedContent.value
+  editMode.value = 'preview'
+}
+
+const requestSave = () => {
+  if (!canEdit.value || props.saving) return
+  emit('save', draftContent.value)
+}
+
+const cancelEdit = () => {
+  syncDraftContent()
+}
+
 const openFullscreenPreview = () => {
   if (!props.file) return
   fullscreenPreviewVisible.value = true
@@ -309,6 +393,8 @@ watch(
   }
 )
 
+watch([() => props.filePath, () => props.file?.content, canEdit], syncDraftContent, { immediate: true })
+
 watch([() => props.filePath, () => props.file?.previewType, () => props.file?.content], () => {
   if (isHtmlFile.value) {
     htmlPreviewRenderKey.value += 1
@@ -381,8 +467,8 @@ onUnmounted(() => {
 
 .modal-action-btn,
 .preview-mode-btn {
-  width: 32px;
-  height: 32px;
+  width: 24px;
+  height: 24px;
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -401,6 +487,18 @@ onUnmounted(() => {
   color: var(--gray-900);
 }
 
+.modal-action-btn:disabled,
+.preview-mode-btn:disabled {
+  color: var(--gray-300);
+  cursor: not-allowed;
+}
+
+.modal-action-btn:disabled:hover,
+.preview-mode-btn:disabled:hover {
+  background: transparent;
+  color: var(--gray-300);
+}
+
 .preview-mode-btn.active {
   background: var(--gray-0);
   color: var(--gray-900);
@@ -436,6 +534,25 @@ onUnmounted(() => {
   }
 }
 
+.file-edit-textarea {
+  width: 100%;
+  min-height: calc(80vh - 40px);
+  padding: 12px;
+  border: 0;
+  outline: none;
+  resize: none;
+  background: var(--gray-0);
+  color: var(--gray-1000);
+  font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+.file-edit-textarea:disabled {
+  color: var(--gray-600);
+  background: var(--gray-25);
+}
+
 .file-content pre,
 .file-content-pre {
   font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
diff --git a/web/src/components/workspace/WorkspacePreviewPane.vue b/web/src/components/workspace/WorkspacePreviewPane.vue
index 2935a3f6..37d24fe2 100644
--- a/web/src/components/workspace/WorkspacePreviewPane.vue
+++ b/web/src/components/workspace/WorkspacePreviewPane.vue
@@ -8,9 +8,12 @@
       :show-close="true"
       :show-fullscreen="true"
       :full-height="true"
+      :editable="editable"
+      :saving="saving"
       container-class="workspace-preview-container"
       content-class="workspace-preview-content"
       @close="$emit('close')"
+      @save="$emit('save', $event)"
     />
     <div v-else-if="loading" class="preview-state">
       <a-spin />
@@ -19,7 +22,7 @@
     <div v-else class="preview-empty">
       <FileSearch :size="28" />
       <h3>选择文件以预览</h3>
-      <p>支持 Markdown、文本、代码、图片与 PDF 的只读预览。</p>
+      <p>支持 Markdown、TXT 编辑，其他格式保持只读预览。</p>
     </div>
   </aside>
 </template>
@@ -31,10 +34,12 @@ import AgentFilePreview from '@/components/AgentFilePreview.vue'
 defineProps({
   file: { type: Object, default: null },
   filePath: { type: String, default: '' },
-  loading: { type: Boolean, default: false }
+  loading: { type: Boolean, default: false },
+  editable: { type: Boolean, default: false },
+  saving: { type: Boolean, default: false }
 })
 
-defineEmits(['close'])
+defineEmits(['close', 'save'])
 </script>
 
 <style scoped lang="less">
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index c7dd95d9..aa485bed 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -79,7 +79,10 @@
             :file="previewFile"
             :file-path="selectedEntry?.path || ''"
             :loading="loadingPreview"
+            :editable="true"
+            :saving="savingPreviewFile"
             @close="closePreview"
+            @save="handleSavePreviewFile"
           />
         </template>
 
@@ -123,7 +126,10 @@
         :showClose="true"
         :showDownload="false"
         :showFullscreen="true"
+        :editable="activeSourceKey === 'personal'"
+        :saving="savingPreviewFile"
         @close="closePreview"
+        @save="handleSavePreviewFile"
       />
     </a-modal>
   </div>
@@ -145,6 +151,7 @@ import {
   downloadWorkspaceFile,
   getWorkspaceFileContent,
   getWorkspaceTree,
+  saveWorkspaceFileContent,
   uploadWorkspaceFile
 } from '@/apis/workspace_api'
 
@@ -159,6 +166,7 @@ const previewObjectUrl = ref('')
 const previewModalVisible = ref(false)
 const loadingTree = ref(false)
 const loadingPreview = ref(false)
+const savingPreviewFile = ref(false)
 const loadingDatabases = ref(false)
 const databases = ref([])
 const selectedDatabase = ref(null)
@@ -339,6 +347,29 @@ const closePreview = () => {
   revokePreviewObjectUrl()
 }
 
+const handleSavePreviewFile = async (content) => {
+  if (!selectedEntry.value?.path || savingPreviewFile.value) return
+
+  savingPreviewFile.value = true
+  try {
+    const response = await saveWorkspaceFileContent(selectedEntry.value.path, content)
+    if (response.entry) {
+      selectedEntry.value = response.entry
+    }
+    previewFile.value = {
+      ...previewFile.value,
+      content
+    }
+    await loadWorkspaceEntries(currentPath.value)
+    message.success('文件保存成功')
+  } catch (error) {
+    console.warn('保存工作区文件失败:', error)
+    message.error(error?.message || '文件保存失败')
+  } finally {
+    savingPreviewFile.value = false
+  }
+}
+
 const openCreateDirectoryModal = () => {
   if (activeSourceKey.value !== 'personal') return
   newDirectoryName.value = ''

From 5fb6af8cb8b0c6d3a48e2281c9a0a21bb10089de Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Fri, 1 May 2026 21:39:14 +0800
Subject: [PATCH 09/15] =?UTF-8?q?feat(workspace):=20=E5=A2=9E=E5=BC=BA?=
 =?UTF-8?q?=E9=A2=84=E8=A7=88=E9=9D=A2=E6=9D=BF=E5=8A=9F=E8=83=BD=EF=BC=8C?=
 =?UTF-8?q?=E6=94=AF=E6=8C=81=E5=85=B3=E9=97=AD=E5=92=8C=E6=8A=98=E5=8F=A0?=
 =?UTF-8?q?=E6=93=8D=E4=BD=9C=EF=BC=8C=E4=BC=98=E5=8C=96=E6=A0=B7=E5=BC=8F?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/src/components/AgentFilePreview.vue       | 19 ++++++++++++++++---
 web/src/components/AgentPanel.vue             |  1 +
 .../workspace/WorkspacePreviewPane.vue        |  1 +
 .../components/workspace/WorkspaceSidebar.vue |  2 +-
 web/src/views/WorkspaceView.vue               | 12 ++++++++++--
 5 files changed, 29 insertions(+), 6 deletions(-)

diff --git a/web/src/components/AgentFilePreview.vue b/web/src/components/AgentFilePreview.vue
index 9fd0956d..66163af2 100644
--- a/web/src/components/AgentFilePreview.vue
+++ b/web/src/components/AgentFilePreview.vue
@@ -79,8 +79,14 @@
         >
           <Maximize2 :size="18" />
         </button>
-        <button v-if="showClose" class="modal-action-btn" @click="$emit('close')" title="关闭">
-          <X :size="18" />
+        <button
+          v-if="showClose"
+          class="modal-action-btn"
+          @click="$emit('close')"
+          :title="closeTitle"
+          :aria-label="closeTitle"
+        >
+          <component :is="closeIconComponent" :size="18" />
         </button>
       </div>
     </div>
@@ -234,7 +240,7 @@
 
 <script setup>
 import { computed, onUnmounted, ref, watch } from 'vue'
-import { Code2, Download, Eye, Globe, Maximize2, Pencil, Save, X } from 'lucide-vue-next'
+import { Code2, Download, Eye, Globe, Maximize2, PanelRightClose, Pencil, Save, X } from 'lucide-vue-next'
 import { MdPreview } from 'md-editor-v3'
 import hljs from 'highlight.js/lib/common'
 import 'md-editor-v3/lib/preview.css'
@@ -274,6 +280,11 @@ const props = defineProps({
     type: Boolean,
     default: false
   },
+  closeVariant: {
+    type: String,
+    default: 'close',
+    validator: (value) => ['close', 'collapse-right'].includes(value)
+  },
   fullHeight: {
     type: Boolean,
     default: false
@@ -300,6 +311,8 @@ const emit = defineEmits(['close', 'download', 'save'])
 
 const themeStore = useThemeStore()
 const theme = computed(() => (themeStore.isDark ? 'dark' : 'light'))
+const closeTitle = computed(() => (props.closeVariant === 'collapse-right' ? '收起预览面板' : '关闭预览'))
+const closeIconComponent = computed(() => (props.closeVariant === 'collapse-right' ? PanelRightClose : X))
 const htmlPreviewMode = ref('render')
 const editMode = ref('preview')
 const draftContent = ref('')
diff --git a/web/src/components/AgentPanel.vue b/web/src/components/AgentPanel.vue
index 618f8e51..db8309b0 100644
--- a/web/src/components/AgentPanel.vue
+++ b/web/src/components/AgentPanel.vue
@@ -82,6 +82,7 @@
               :filePath="currentFilePath"
               :fullHeight="true"
               :showClose="true"
+              closeVariant="collapse-right"
               :showDownload="true"
               :showFullscreen="true"
               @download="downloadFile"
diff --git a/web/src/components/workspace/WorkspacePreviewPane.vue b/web/src/components/workspace/WorkspacePreviewPane.vue
index 37d24fe2..697c6867 100644
--- a/web/src/components/workspace/WorkspacePreviewPane.vue
+++ b/web/src/components/workspace/WorkspacePreviewPane.vue
@@ -6,6 +6,7 @@
       :file-path="filePath"
       :show-download="false"
       :show-close="true"
+      close-variant="collapse-right"
       :show-fullscreen="true"
       :full-height="true"
       :editable="editable"
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index 832e3dff..be6a542c 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -95,7 +95,7 @@ defineEmits(['select-personal', 'select-database', 'select-path'])
   min-width: 0;
   padding: 14px 10px;
   border-right: 1px solid var(--gray-100);
-  background: var(--gray-25);
+  background: var(--gray-0);
   overflow-y: auto;
 }
 
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index aa485bed..82704842 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -566,12 +566,20 @@ onUnmounted(() => {
   revokePreviewObjectUrl()
 })
 
-watch(useInlinePreview, (isInline) => {
+watch(useInlinePreview, (isInline, wasInline) => {
   if (!previewFile.value) {
     previewModalVisible.value = false
     return
   }
-  previewModalVisible.value = !isInline
+
+  if (isInline) {
+    previewModalVisible.value = false
+    return
+  }
+
+  if (wasInline) {
+    closePreview()
+  }
 })
 </script>
 

From cbd265fea85bf5aad11ea72426560fc420d23d1a Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Fri, 1 May 2026 22:17:27 +0800
Subject: [PATCH 10/15] =?UTF-8?q?feat(workspace):=20=E5=A2=9E=E5=BC=BA?=
 =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E5=8C=BA=E5=8A=9F=E8=83=BD=EF=BC=8C=E5=A4=84?=
 =?UTF-8?q?=E7=90=86=E7=AC=A6=E5=8F=B7=E9=93=BE=E6=8E=A5=E5=92=8C=E9=9D=9E?=
 =?UTF-8?q?=20UTF-8=20=E6=96=87=E6=9C=AC=E6=96=87=E4=BB=B6=E7=9A=84?=
 =?UTF-8?q?=E9=A2=84=E8=A7=88=E6=94=AF=E6=8C=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../yuxi/services/workspace_service.py        | 22 ++++++++--
 .../unit/services/test_workspace_service.py   | 32 ++++++++++++++
 web/src/components/AgentFilePreview.vue       | 24 ++++++++--
 web/src/components/AgentPanel.vue             |  9 +---
 web/src/components/ConversationNavSection.vue |  6 ++-
 web/src/components/ShareConfigForm.vue        |  5 ++-
 .../components/extensions/McpDetailView.vue   |  2 -
 .../components/extensions/SkillDetailView.vue |  4 --
 web/src/components/shared/InfoCard.vue        | 16 ++-----
 .../workspace/WorkspaceFileList.vue           | 22 ++++++++--
 .../components/workspace/WorkspaceSidebar.vue |  7 ++-
 web/src/views/DataBaseView.vue                |  6 +--
 web/src/views/WorkspaceView.vue               | 44 ++++++++++++++++---
 13 files changed, 145 insertions(+), 54 deletions(-)

diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
index 970c2d18..c34aa3a0 100644
--- a/backend/package/yuxi/services/workspace_service.py
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -11,24 +11,29 @@
 import aiofiles
 from fastapi import HTTPException, UploadFile
 from fastapi.responses import FileResponse, StreamingResponse
-
 from yuxi.agents.backends.sandbox.paths import _global_user_data_dir, ensure_workspace_default_files
 from yuxi.services.viewer_filesystem_service import _detect_preview_type
 from yuxi.storage.postgres.models_business import User
 from yuxi.utils.datetime_utils import utc_isoformat_from_timestamp
 from yuxi.utils.paths import WORKSPACE_DIR_NAME
 
-
 EDITABLE_WORKSPACE_SUFFIXES = {".md", ".markdown", ".mdx", ".txt"}
 
 
 def _workspace_root(user: User) -> Path:
     try:
-        root = _global_user_data_dir(str(user.id)) / WORKSPACE_DIR_NAME
+        user_data_root = _global_user_data_dir(str(user.id)).resolve()
+        root = user_data_root / WORKSPACE_DIR_NAME
     except ValueError as exc:
         raise HTTPException(status_code=403, detail="Access denied") from exc
+    if root.is_symlink():
+        raise HTTPException(status_code=403, detail="Access denied")
     root.mkdir(parents=True, exist_ok=True)
     resolved_root = root.resolve()
+    try:
+        resolved_root.relative_to(user_data_root)
+    except ValueError as exc:
+        raise HTTPException(status_code=403, detail="Access denied") from exc
     ensure_workspace_default_files(resolved_root)
     return resolved_root
 
@@ -138,8 +143,17 @@ async def read_workspace_file_content(*, path: str, current_user: User) -> dict:
             "supported": supported,
             "message": message,
         }
+    try:
+        content = raw_content.decode("utf-8")
+    except UnicodeDecodeError:
+        return {
+            "content": None,
+            "preview_type": "unsupported",
+            "supported": False,
+            "message": "当前文件不是 UTF-8 文本，暂不支持预览",
+        }
     return {
-        "content": raw_content.decode("utf-8"),
+        "content": content,
         "preview_type": preview_type,
         "supported": supported,
         "message": message,
diff --git a/backend/test/unit/services/test_workspace_service.py b/backend/test/unit/services/test_workspace_service.py
index 798fe47d..24233ce8 100644
--- a/backend/test/unit/services/test_workspace_service.py
+++ b/backend/test/unit/services/test_workspace_service.py
@@ -43,6 +43,38 @@ def test_workspace_root_keeps_existing_agents_prompt_file(tmp_path: Path, monkey
     assert agents_file.read_text(encoding="utf-8") == "保留已有内容"
 
 
+def test_workspace_root_rejects_symlink_root(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user_root = tmp_path / "threads" / "shared" / "user-1"
+    outside_root = tmp_path / "outside"
+    user_root.mkdir(parents=True)
+    outside_root.mkdir()
+    (user_root / "workspace").symlink_to(outside_root, target_is_directory=True)
+
+    with pytest.raises(HTTPException) as exc_info:
+        svc._workspace_root(SimpleNamespace(id="user-1"))
+
+    assert exc_info.value.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_read_workspace_file_content_returns_unsupported_for_non_utf8_text(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    target = root / "bad.txt"
+    target.write_bytes(b"\xff\xfe\x00")
+
+    result = await svc.read_workspace_file_content(path="/bad.txt", current_user=user)
+
+    assert result["content"] is None
+    assert result["preview_type"] == "unsupported"
+    assert result["supported"] is False
+
+
 @pytest.mark.asyncio
 async def test_write_workspace_file_content_updates_markdown_file(tmp_path: Path, monkeypatch) -> None:
     monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
diff --git a/web/src/components/AgentFilePreview.vue b/web/src/components/AgentFilePreview.vue
index 66163af2..98d25aa5 100644
--- a/web/src/components/AgentFilePreview.vue
+++ b/web/src/components/AgentFilePreview.vue
@@ -240,7 +240,17 @@
 
 <script setup>
 import { computed, onUnmounted, ref, watch } from 'vue'
-import { Code2, Download, Eye, Globe, Maximize2, PanelRightClose, Pencil, Save, X } from 'lucide-vue-next'
+import {
+  Code2,
+  Download,
+  Eye,
+  Globe,
+  Maximize2,
+  PanelRightClose,
+  Pencil,
+  Save,
+  X
+} from 'lucide-vue-next'
 import { MdPreview } from 'md-editor-v3'
 import hljs from 'highlight.js/lib/common'
 import 'md-editor-v3/lib/preview.css'
@@ -311,8 +321,12 @@ const emit = defineEmits(['close', 'download', 'save'])
 
 const themeStore = useThemeStore()
 const theme = computed(() => (themeStore.isDark ? 'dark' : 'light'))
-const closeTitle = computed(() => (props.closeVariant === 'collapse-right' ? '收起预览面板' : '关闭预览'))
-const closeIconComponent = computed(() => (props.closeVariant === 'collapse-right' ? PanelRightClose : X))
+const closeTitle = computed(() =>
+  props.closeVariant === 'collapse-right' ? '收起预览面板' : '关闭预览'
+)
+const closeIconComponent = computed(() =>
+  props.closeVariant === 'collapse-right' ? PanelRightClose : X
+)
 const htmlPreviewMode = ref('render')
 const editMode = ref('preview')
 const draftContent = ref('')
@@ -406,7 +420,9 @@ watch(
   }
 )
 
-watch([() => props.filePath, () => props.file?.content, canEdit], syncDraftContent, { immediate: true })
+watch([() => props.filePath, () => props.file?.content, canEdit], syncDraftContent, {
+  immediate: true
+})
 
 watch([() => props.filePath, () => props.file?.previewType, () => props.file?.content], () => {
   if (isHtmlFile.value) {
diff --git a/web/src/components/AgentPanel.vue b/web/src/components/AgentPanel.vue
index db8309b0..d13c8ad1 100644
--- a/web/src/components/AgentPanel.vue
+++ b/web/src/components/AgentPanel.vue
@@ -124,14 +124,7 @@
 
 <script setup>
 import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
-import {
-  ChevronsDownUp,
-  ChevronsUpDown,
-  Download,
-  RefreshCw,
-  Trash2,
-  X
-} from 'lucide-vue-next'
+import { ChevronsDownUp, ChevronsUpDown, Download, RefreshCw, Trash2, X } from 'lucide-vue-next'
 import { Modal, message } from 'ant-design-vue'
 import FileTreeComponent from '@/components/FileTreeComponent.vue'
 import AgentFilePreview from '@/components/AgentFilePreview.vue'
diff --git a/web/src/components/ConversationNavSection.vue b/web/src/components/ConversationNavSection.vue
index c497cf90..657936b9 100644
--- a/web/src/components/ConversationNavSection.vue
+++ b/web/src/components/ConversationNavSection.vue
@@ -266,7 +266,11 @@ const renameChat = async (chatId) => {
 
     .actions-mask {
       opacity: 1;
-      background: linear-gradient(to right, transparent, color-mix(in srgb, var(--main-color) 6%, var(--gray-0)) 20px);
+      background: linear-gradient(
+        to right,
+        transparent,
+        color-mix(in srgb, var(--main-color) 6%, var(--gray-0)) 20px
+      );
     }
   }
 
diff --git a/web/src/components/ShareConfigForm.vue b/web/src/components/ShareConfigForm.vue
index 93189136..9b1d563b 100644
--- a/web/src/components/ShareConfigForm.vue
+++ b/web/src/components/ShareConfigForm.vue
@@ -259,7 +259,10 @@ defineExpose({
       background: var(--gray-0);
       text-align: left;
       cursor: pointer;
-      transition: border-color 0.2s ease, background-color 0.2s ease, box-shadow 0.2s ease;
+      transition:
+        border-color 0.2s ease,
+        background-color 0.2s ease,
+        box-shadow 0.2s ease;
 
       &:hover,
       &:focus-visible {
diff --git a/web/src/components/extensions/McpDetailView.vue b/web/src/components/extensions/McpDetailView.vue
index 2da9bb46..545e3b0f 100644
--- a/web/src/components/extensions/McpDetailView.vue
+++ b/web/src/components/extensions/McpDetailView.vue
@@ -469,7 +469,6 @@ onMounted(() => {
 @import '@/assets/css/extensions.less';
 @import '@/assets/css/extension-detail.less';
 
-
 /* 工具列表样式 */
 .tools-tab {
   .tools-toolbar {
@@ -607,7 +606,6 @@ onMounted(() => {
   }
 }
 
-
 .mcp-detail {
   .detail-content-wrapper {
     flex: 1;
diff --git a/web/src/components/extensions/SkillDetailView.vue b/web/src/components/extensions/SkillDetailView.vue
index 111dc83a..167fa2ba 100644
--- a/web/src/components/extensions/SkillDetailView.vue
+++ b/web/src/components/extensions/SkillDetailView.vue
@@ -323,10 +323,6 @@ const currentSkillStatusLabel = computed(() => {
   return '已上传'
 })
 
-const currentSkillStatusTone = computed(() => {
-  return currentSkill.value?.status === 'update_available' ? 'warning' : 'default'
-})
-
 const canSave = computed(() => {
   if (!selectedPath.value || selectedIsDir.value) return false
   return fileContent.value !== originalFileContent.value
diff --git a/web/src/components/shared/InfoCard.vue b/web/src/components/shared/InfoCard.vue
index fc3fee04..9c261d06 100644
--- a/web/src/components/shared/InfoCard.vue
+++ b/web/src/components/shared/InfoCard.vue
@@ -1,9 +1,5 @@
 <template>
-  <div
-    class="info-card"
-    :class="{ 'info-card-disabled': disabled }"
-    @click="$emit('click')"
-  >
+  <div class="info-card" :class="{ 'info-card-disabled': disabled }" @click="$emit('click')">
     <div class="info-card-header">
       <div class="info-card-icon">
         <slot name="icon">
@@ -12,9 +8,7 @@
       </div>
       <div class="info-card-info">
         <span class="info-card-name" :title="title">{{ title }}</span>
-        <span v-if="subtitle" class="info-card-subtitle" :title="subtitle">{{
-          subtitle
-        }}</span>
+        <span v-if="subtitle" class="info-card-subtitle" :title="subtitle">{{ subtitle }}</span>
       </div>
       <div class="info-card-status">
         <slot name="status" />
@@ -54,10 +48,7 @@
       </div>
     </div>
 
-    <div
-      v-if="$slots.tags || (normalizedTags && normalizedTags.length > 0)"
-      class="info-card-tags"
-    >
+    <div v-if="$slots.tags || (normalizedTags && normalizedTags.length > 0)" class="info-card-tags">
       <slot name="tags">
         <span
           v-for="(tag, idx) in normalizedTags"
@@ -254,7 +245,6 @@ const normalizedTags = computed(() => {
   }
 }
 
-
 .card-action-btn {
   display: inline-flex;
   align-items: center;
diff --git a/web/src/components/workspace/WorkspaceFileList.vue b/web/src/components/workspace/WorkspaceFileList.vue
index 8902ec55..c8a9d2a9 100644
--- a/web/src/components/workspace/WorkspaceFileList.vue
+++ b/web/src/components/workspace/WorkspaceFileList.vue
@@ -105,7 +105,11 @@
             </button>
             <template #overlay>
               <a-menu>
-                <a-menu-item v-if="!entry.is_dir" key="download" @click="$emit('download-entry', entry)">
+                <a-menu-item
+                  v-if="!entry.is_dir"
+                  key="download"
+                  @click="$emit('download-entry', entry)"
+                >
                   <span class="menu-item-content">
                     <Download :size="14" />
                     <span>下载</span>
@@ -135,7 +139,12 @@
 <script setup>
 import { computed } from 'vue'
 import { Download, Folder, ListChecks, MoreHorizontal, Trash2 } from 'lucide-vue-next'
-import { formatFileSize, formatRelativeTime, getFileIcon, getFileIconColor } from '@/utils/file_utils'
+import {
+  formatFileSize,
+  formatRelativeTime,
+  getFileIcon,
+  getFileIconColor
+} from '@/utils/file_utils'
 
 const props = defineProps({
   entries: { type: Array, default: () => [] },
@@ -179,7 +188,9 @@ const breadcrumbItems = computed(() => {
 })
 
 const allSelected = computed(() => {
-  return entryPaths.value.length > 0 && entryPaths.value.every((path) => selectedPathSet.value.has(path))
+  return (
+    entryPaths.value.length > 0 && entryPaths.value.every((path) => selectedPathSet.value.has(path))
+  )
 })
 
 const partiallySelected = computed(() => {
@@ -207,7 +218,10 @@ const toggleEntrySelection = (path, checked) => {
   } else {
     nextSelectedPaths.delete(path)
   }
-  emit('update:selectedPaths', [...nextSelectedPaths].filter((selectedPath) => entryPaths.value.includes(selectedPath)))
+  emit(
+    'update:selectedPaths',
+    [...nextSelectedPaths].filter((selectedPath) => entryPaths.value.includes(selectedPath))
+  )
 }
 </script>
 
diff --git a/web/src/components/workspace/WorkspaceSidebar.vue b/web/src/components/workspace/WorkspaceSidebar.vue
index be6a542c..582f0b60 100644
--- a/web/src/components/workspace/WorkspaceSidebar.vue
+++ b/web/src/components/workspace/WorkspaceSidebar.vue
@@ -17,7 +17,9 @@
       <button
         type="button"
         class="workspace-nav-item secondary"
-        :class="{ active: activeKey === 'personal' && isSameOrChildPath(currentPath, savedArtifactsPath) }"
+        :class="{
+          active: activeKey === 'personal' && isSameOrChildPath(currentPath, savedArtifactsPath)
+        }"
         @click="$emit('select-path', savedArtifactsPath)"
       >
         <Archive :size="15" />
@@ -75,7 +77,8 @@ const isSameOrChildPath = (path, targetPath) => {
   const target = normalizePath(targetPath)
   return current === target || current.startsWith(`${target}/`)
 }
-const isQuickAccessPath = (path) => quickAccessPaths.some((targetPath) => isSameOrChildPath(path, targetPath))
+const isQuickAccessPath = (path) =>
+  quickAccessPaths.some((targetPath) => isSameOrChildPath(path, targetPath))
 
 defineProps({
   activeKey: { type: String, default: 'personal' },
diff --git a/web/src/views/DataBaseView.vue b/web/src/views/DataBaseView.vue
index 25660647..02e3749b 100644
--- a/web/src/views/DataBaseView.vue
+++ b/web/src/views/DataBaseView.vue
@@ -43,9 +43,7 @@
       <div class="new-database-form">
         <!-- 知识库类型选择 -->
         <div class="form-section">
-          <h3 class="section-title">
-            知识库类型<span class="required-mark">*</span>
-          </h3>
+          <h3 class="section-title">知识库类型<span class="required-mark">*</span></h3>
           <div class="kb-type-cards">
             <div
               v-for="(typeInfo, typeKey) in orderedKbTypes"
@@ -156,7 +154,7 @@
           />
         </div>
 
-      <!-- 隐私设置（暂时隐藏）
+        <!-- 隐私设置（暂时隐藏）
       <h3 style="margin-top: 20px">隐私设置</h3>
       <div class="privacy-config">
         <a-switch
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index 82704842..dbbbc958 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -5,13 +5,22 @@
         <a-button :disabled="activeSourceKey !== 'personal'" @click="openCreateDirectoryModal">
           新建文件夹
         </a-button>
-        <a-button :loading="uploadingFile" :disabled="activeSourceKey !== 'personal'" @click="openUploadFilePicker">
+        <a-button
+          :loading="uploadingFile"
+          :disabled="activeSourceKey !== 'personal'"
+          @click="openUploadFilePicker"
+        >
           上传文件
         </a-button>
       </template>
     </PageHeader>
 
-    <input ref="uploadInputRef" class="upload-input" type="file" @change="handleUploadInputChange" />
+    <input
+      ref="uploadInputRef"
+      class="upload-input"
+      type="file"
+      @change="handleUploadInputChange"
+    />
 
     <div class="workspace-shell" :class="{ 'is-sidebar-collapsed': sidebarCollapsed }">
       <div v-if="!sidebarCollapsed" class="workspace-sidebar-slot">
@@ -181,6 +190,7 @@ const uploadInputRef = ref(null)
 const deletingPaths = ref([])
 const sidebarCollapsed = ref(false)
 const previewWidthPercent = ref(50)
+const previewRequestId = ref(0)
 const INLINE_PREVIEW_MIN_WIDTH = 960
 
 const useInlinePreview = computed(() => workspaceMainWidth.value >= INLINE_PREVIEW_MIN_WIDTH)
@@ -196,7 +206,11 @@ const workspaceMainStyle = computed(() => {
 const filteredEntries = computed(() => {
   const keyword = searchQuery.value.trim().toLowerCase()
   if (!keyword) return entries.value
-  return entries.value.filter((entry) => String(entry.name || '').toLowerCase().includes(keyword))
+  return entries.value.filter((entry) =>
+    String(entry.name || '')
+      .toLowerCase()
+      .includes(keyword)
+  )
 })
 
 const selectedEntries = computed(() => {
@@ -309,6 +323,8 @@ const handleSelectEntry = async (entry) => {
     return
   }
 
+  const requestId = previewRequestId.value + 1
+  previewRequestId.value = requestId
   selectedEntry.value = entry
   revokePreviewObjectUrl()
   previewFile.value = {
@@ -323,8 +339,10 @@ const handleSelectEntry = async (entry) => {
   loadingPreview.value = true
   try {
     const response = await getWorkspaceFileContent(entry.path)
+    if (previewRequestId.value !== requestId || selectedEntry.value?.path !== entry.path) return
     previewFile.value = await normalizePreviewFile(entry, response)
   } catch (error) {
+    if (previewRequestId.value !== requestId || selectedEntry.value?.path !== entry.path) return
     console.warn('加载文件预览失败:', error)
     previewFile.value = {
       ...entry,
@@ -336,14 +354,18 @@ const handleSelectEntry = async (entry) => {
     }
     message.error('加载文件预览失败')
   } finally {
-    loadingPreview.value = false
+    if (previewRequestId.value === requestId) {
+      loadingPreview.value = false
+    }
   }
 }
 
 const closePreview = () => {
+  previewRequestId.value += 1
   previewModalVisible.value = false
   selectedEntry.value = null
   previewFile.value = null
+  loadingPreview.value = false
   revokePreviewObjectUrl()
 }
 
@@ -430,7 +452,9 @@ const comparablePath = (path) => String(path || '/').replace(/\/$/, '') || '/'
 const isSameOrChildPath = (path, targetPath) => {
   const normalizedPath = comparablePath(path)
   const normalizedTargetPath = comparablePath(targetPath)
-  return normalizedPath === normalizedTargetPath || normalizedPath.startsWith(`${normalizedTargetPath}/`)
+  return (
+    normalizedPath === normalizedTargetPath || normalizedPath.startsWith(`${normalizedTargetPath}/`)
+  )
 }
 
 const confirmDeleteEntries = (targetEntries) => {
@@ -445,7 +469,10 @@ const confirmDeleteEntries = (targetEntries) => {
       : firstEntry.is_dir
         ? `确认删除文件夹「${firstEntry.name}」？`
         : `确认删除文件「${firstEntry.name}」？`,
-    content: isBatch || firstEntry.is_dir ? '将删除文件夹及其所有内容，删除后不可恢复。' : '删除后不可恢复。',
+    content:
+      isBatch || firstEntry.is_dir
+        ? '将删除文件夹及其所有内容，删除后不可恢复。'
+        : '删除后不可恢复。',
     okText: '删除',
     okType: 'danger',
     cancelText: '取消',
@@ -458,7 +485,10 @@ const deleteEntries = async (targetEntries) => {
   deletingPaths.value = paths
   try {
     await Promise.all(paths.map((path) => deleteWorkspacePath(path)))
-    if (selectedEntry.value && paths.some((path) => isSameOrChildPath(selectedEntry.value.path, path))) {
+    if (
+      selectedEntry.value &&
+      paths.some((path) => isSameOrChildPath(selectedEntry.value.path, path))
+    ) {
       closePreview()
     }
     clearWorkspaceSelection()

From 02b371851da4c995742074659143c231bd9c3061 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Mon, 4 May 2026 07:42:47 +0800
Subject: [PATCH 11/15] fix: preview

---
 web/src/components/workspace/WorkspacePreviewPane.vue | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/web/src/components/workspace/WorkspacePreviewPane.vue b/web/src/components/workspace/WorkspacePreviewPane.vue
index 697c6867..4553a6ce 100644
--- a/web/src/components/workspace/WorkspacePreviewPane.vue
+++ b/web/src/components/workspace/WorkspacePreviewPane.vue
@@ -63,6 +63,13 @@ defineEmits(['close', 'save'])
   min-height: 0;
 }
 
+:deep(.workspace-preview-content .html-preview),
+:deep(.workspace-preview-content .pdf-preview) {
+  display: block;
+  height: 100%;
+  min-height: 100%;
+}
+
 .preview-state,
 .preview-empty {
   display: flex;

From a450be57e34e55a669d9d43b65889b53fa06ad42 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Mon, 4 May 2026 08:24:13 +0800
Subject: [PATCH 12/15] =?UTF-8?q?fix(workspace):=20=E4=BF=AE=E6=94=B9?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E4=B8=8A=E4=BC=A0=E9=80=BB=E8=BE=91=EF=BC=8C?=
 =?UTF-8?q?=E6=96=B0=E5=A2=9E=E4=B8=8A=E4=BC=A0=E5=B7=A5=E5=85=B7=E5=87=BD?=
 =?UTF-8?q?=E6=95=B0=EF=BC=8C=E6=94=AF=E6=8C=81=E6=96=87=E4=BB=B6=E5=A4=A7?=
 =?UTF-8?q?=E5=B0=8F=E9=99=90=E5=88=B6=E5=92=8C=E9=94=99=E8=AF=AF=E5=A4=84?=
 =?UTF-8?q?=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../yuxi/services/conversation_service.py     | 23 +++-------
 backend/package/yuxi/services/upload_utils.py | 43 +++++++++++++++++++
 .../yuxi/services/workspace_service.py        | 12 +++++-
 .../unit/services/test_workspace_service.py   | 37 +++++++++++++++-
 4 files changed, 96 insertions(+), 19 deletions(-)
 create mode 100644 backend/package/yuxi/services/upload_utils.py

diff --git a/backend/package/yuxi/services/conversation_service.py b/backend/package/yuxi/services/conversation_service.py
index e71dfa0f..b24c16b9 100644
--- a/backend/package/yuxi/services/conversation_service.py
+++ b/backend/package/yuxi/services/conversation_service.py
@@ -2,7 +2,6 @@
 from dataclasses import dataclass
 from pathlib import Path
 
-import aiofiles
 from fastapi import HTTPException, UploadFile
 from sqlalchemy.ext.asyncio import AsyncSession
 from yuxi.agents.backends.sandbox import (
@@ -13,6 +12,7 @@
 from yuxi.config import config as app_config
 from yuxi.plugins.parser import Parser
 from yuxi.repositories.conversation_repository import ConversationRepository
+from yuxi.services.upload_utils import write_upload_to_path
 from yuxi.utils.datetime_utils import utc_isoformat
 from yuxi.utils.logging_config import logger
 from yuxi.utils.paths import VIRTUAL_PATH_UPLOADS
@@ -41,21 +41,12 @@ def _ensure_workdir() -> Path:
 
 
 async def _write_upload_to_disk(upload: UploadFile, dest: Path) -> int:
-    await upload.seek(0)
-    written = 0
-    chunk_size = 1024 * 1024
-
-    async with aiofiles.open(dest, "wb") as buffer:
-        while True:
-            chunk = await upload.read(chunk_size)
-            if not chunk:
-                break
-            written += len(chunk)
-            if written > MAX_ATTACHMENT_SIZE_BYTES:
-                raise ValueError("附件过大，当前仅支持 5 MB 以内的文件")
-            await buffer.write(chunk)
-
-    return written
+    return await write_upload_to_path(
+        upload,
+        dest,
+        max_size_bytes=MAX_ATTACHMENT_SIZE_BYTES,
+        too_large_message="附件过大，当前仅支持 5 MB 以内的文件",
+    )
 
 
 def _truncate_markdown(markdown: str) -> tuple[str, bool]:
diff --git a/backend/package/yuxi/services/upload_utils.py b/backend/package/yuxi/services/upload_utils.py
new file mode 100644
index 00000000..6a1b7902
--- /dev/null
+++ b/backend/package/yuxi/services/upload_utils.py
@@ -0,0 +1,43 @@
+from pathlib import Path
+
+import aiofiles
+from fastapi import UploadFile
+
+
+async def write_upload_to_buffer(
+    upload: UploadFile,
+    buffer,
+    *,
+    max_size_bytes: int,
+    too_large_message: str,
+    chunk_size: int = 1024 * 1024,
+) -> int:
+    await upload.seek(0)
+    written = 0
+
+    while chunk := await upload.read(chunk_size):
+        written += len(chunk)
+        if written > max_size_bytes:
+            raise ValueError(too_large_message)
+        await buffer.write(chunk)
+
+    return written
+
+
+async def write_upload_to_path(
+    upload: UploadFile,
+    dest: Path,
+    *,
+    max_size_bytes: int,
+    too_large_message: str,
+    mode: str = "wb",
+    chunk_size: int = 1024 * 1024,
+) -> int:
+    async with aiofiles.open(dest, mode) as buffer:
+        return await write_upload_to_buffer(
+            upload,
+            buffer,
+            max_size_bytes=max_size_bytes,
+            too_large_message=too_large_message,
+            chunk_size=chunk_size,
+        )
diff --git a/backend/package/yuxi/services/workspace_service.py b/backend/package/yuxi/services/workspace_service.py
index c34aa3a0..509a0d3d 100644
--- a/backend/package/yuxi/services/workspace_service.py
+++ b/backend/package/yuxi/services/workspace_service.py
@@ -12,12 +12,14 @@
 from fastapi import HTTPException, UploadFile
 from fastapi.responses import FileResponse, StreamingResponse
 from yuxi.agents.backends.sandbox.paths import _global_user_data_dir, ensure_workspace_default_files
+from yuxi.services.upload_utils import write_upload_to_buffer
 from yuxi.services.viewer_filesystem_service import _detect_preview_type
 from yuxi.storage.postgres.models_business import User
 from yuxi.utils.datetime_utils import utc_isoformat_from_timestamp
 from yuxi.utils.paths import WORKSPACE_DIR_NAME
 
 EDITABLE_WORKSPACE_SUFFIXES = {".md", ".markdown", ".mdx", ".txt"}
+MAX_WORKSPACE_UPLOAD_SIZE_BYTES = 100 * 1024 * 1024
 
 
 def _workspace_root(user: User) -> Path:
@@ -237,11 +239,17 @@ async def upload_workspace_file(*, parent_path: str, file: UploadFile, current_u
     try:
         async with aiofiles.open(target, "xb") as buffer:
             created_file = True
-            while chunk := await file.read(1024 * 1024):
-                await buffer.write(chunk)
+            await write_upload_to_buffer(
+                file,
+                buffer,
+                max_size_bytes=MAX_WORKSPACE_UPLOAD_SIZE_BYTES,
+                too_large_message="文件过大，当前仅支持 100 MB 以内的文件",
+            )
         upload_completed = True
     except FileExistsError as exc:
         raise HTTPException(status_code=400, detail="同名文件或文件夹已存在") from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
     except PermissionError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
     finally:
diff --git a/backend/test/unit/services/test_workspace_service.py b/backend/test/unit/services/test_workspace_service.py
index 24233ce8..55de5bfd 100644
--- a/backend/test/unit/services/test_workspace_service.py
+++ b/backend/test/unit/services/test_workspace_service.py
@@ -1,10 +1,11 @@
 from __future__ import annotations
 
+from io import BytesIO
 from pathlib import Path
 from types import SimpleNamespace
 
 import pytest
-from fastapi import HTTPException
+from fastapi import HTTPException, UploadFile
 
 from yuxi.agents.backends.sandbox import paths as workspace_paths
 from yuxi.services import workspace_service as svc
@@ -146,3 +147,37 @@ async def test_write_workspace_file_content_blocks_path_traversal(tmp_path: Path
         )
 
     assert exc_info.value.status_code == 403
+
+
+@pytest.mark.asyncio
+async def test_upload_workspace_file_writes_file(tmp_path: Path, monkeypatch) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    upload = UploadFile(filename="demo.txt", file=BytesIO(b"hello"))
+
+    result = await svc.upload_workspace_file(parent_path="/", file=upload, current_user=user)
+
+    assert result["success"] is True
+    assert result["entry"]["path"] == "/demo.txt"
+    assert result["entry"]["size"] == 5
+    assert (root / "demo.txt").read_bytes() == b"hello"
+
+
+@pytest.mark.asyncio
+async def test_upload_workspace_file_rejects_oversized_file_and_cleans_partial_file(
+    tmp_path: Path,
+    monkeypatch,
+) -> None:
+    monkeypatch.setattr(workspace_paths.conf, "save_dir", str(tmp_path))
+    monkeypatch.setattr(svc, "MAX_WORKSPACE_UPLOAD_SIZE_BYTES", 5)
+    user = SimpleNamespace(id="user-1")
+    root = svc._workspace_root(user)
+    upload = UploadFile(filename="large.txt", file=BytesIO(b"123456"))
+
+    with pytest.raises(HTTPException) as exc_info:
+        await svc.upload_workspace_file(parent_path="/", file=upload, current_user=user)
+
+    assert exc_info.value.status_code == 400
+    assert "100 MB" in exc_info.value.detail
+    assert not (root / "large.txt").exists()

From 016dfb457a0aadee3024e9d47d00f9b63b31324e Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Mon, 4 May 2026 08:24:25 +0800
Subject: [PATCH 13/15] =?UTF-8?q?fix(workspace):=20=E4=BF=AE=E5=A4=8D?=
 =?UTF-8?q?=E9=9D=A2=E5=8C=85=E5=B1=91=E8=B7=AF=E5=BE=84=E9=80=BB=E8=BE=91?=
 =?UTF-8?q?=EF=BC=8C=E7=A1=AE=E4=BF=9D=E5=BD=93=E5=89=8D=E8=B7=AF=E5=BE=84?=
 =?UTF-8?q?=E6=AD=A3=E5=B8=B8=E5=8C=96=EF=BC=9B=E4=BC=98=E5=8C=96=E9=A2=84?=
 =?UTF-8?q?=E8=A7=88=E6=96=87=E4=BB=B6=E4=B8=8B=E8=BD=BD=E5=92=8C=E8=B0=83?=
 =?UTF-8?q?=E6=95=B4=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/src/components/workspace/WorkspaceFileList.vue | 7 ++++---
 web/src/views/WorkspaceView.vue                    | 8 +++++---
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/web/src/components/workspace/WorkspaceFileList.vue b/web/src/components/workspace/WorkspaceFileList.vue
index c8a9d2a9..0f7387f0 100644
--- a/web/src/components/workspace/WorkspaceFileList.vue
+++ b/web/src/components/workspace/WorkspaceFileList.vue
@@ -7,8 +7,8 @@
             <button
               type="button"
               class="breadcrumb-action"
-              :class="{ current: item.path === currentPath }"
-              :disabled="item.path === currentPath"
+              :class="{ current: item.path === normalizedCurrentPath }"
+              :disabled="item.path === normalizedCurrentPath"
               :title="item.path"
               @click="$emit('select-path', item.path)"
             >
@@ -169,8 +169,9 @@ const emit = defineEmits([
 const selectedPathSet = computed(() => new Set(props.selectedPaths))
 const deletingPathSet = computed(() => new Set(props.deletingPaths))
 const entryPaths = computed(() => props.entries.map((entry) => entry.path))
+const normalizedCurrentPath = computed(() => (props.currentPath || '/').replace(/\/+$/, '') || '/')
 const breadcrumbItems = computed(() => {
-  const normalizedPath = props.currentPath || '/'
+  const normalizedPath = normalizedCurrentPath.value
   if (normalizedPath === '/') {
     return [{ name: '工作区', path: '/' }]
   }
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index dbbbc958..f3aa8e4b 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -233,8 +233,8 @@ const normalizePreviewFile = async (entry, response) => {
   }
 
   if (previewType === 'image' || previewType === 'pdf') {
-    const response = await downloadWorkspaceFile(entry.path)
-    const blob = await response.blob()
+    const downloadResponse = await downloadWorkspaceFile(entry.path)
+    const blob = await downloadResponse.blob()
     revokePreviewObjectUrl()
     previewObjectUrl.value = URL.createObjectURL(blob)
     file.previewUrl = previewObjectUrl.value
@@ -554,10 +554,11 @@ const stopPreviewResize = () => {
   document.body.style.userSelect = ''
   window.removeEventListener('pointermove', resizePreview)
   window.removeEventListener('pointerup', stopPreviewResize)
+  window.removeEventListener('pointercancel', stopPreviewResize)
 }
 
 const resizePreview = (event) => {
-  if (!workspaceMainRef.value || resizePointerId === null) return
+  if (!workspaceMainRef.value || resizePointerId === null || event.pointerId !== resizePointerId) return
   const rect = workspaceMainRef.value.getBoundingClientRect()
   const relativeX = event.clientX - rect.left
   const nextPreviewPercent = Math.round(((rect.width - relativeX) / rect.width) * 100)
@@ -571,6 +572,7 @@ const startPreviewResize = (event) => {
   document.body.style.userSelect = 'none'
   window.addEventListener('pointermove', resizePreview)
   window.addEventListener('pointerup', stopPreviewResize)
+  window.addEventListener('pointercancel', stopPreviewResize)
 }
 
 let workspaceResizeObserver = null

From 9e6348206e97b54c66106b800ff085d32a20c7f0 Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Mon, 4 May 2026 08:25:23 +0800
Subject: [PATCH 14/15] =?UTF-8?q?style:=20=E6=A0=BC=E5=BC=8F=E5=8C=96?=
 =?UTF-8?q?=E5=AF=BC=E5=85=A5=E8=AF=AD=E5=8F=A5=EF=BC=8C=E6=8F=90=E5=8D=87?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=E5=8F=AF=E8=AF=BB=E6=80=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 web/src/components/DatabaseHeader.vue    |  9 ++++++++-
 web/src/components/KnowledgeBaseCard.vue |  8 +++++++-
 web/src/views/DataBaseView.vue           | 14 ++++++++++++--
 web/src/views/WorkspaceView.vue          |  3 ++-
 4 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/web/src/components/DatabaseHeader.vue b/web/src/components/DatabaseHeader.vue
index 99ba673d..e2c457d9 100644
--- a/web/src/components/DatabaseHeader.vue
+++ b/web/src/components/DatabaseHeader.vue
@@ -75,7 +75,14 @@
 import { ref, reactive, computed } from 'vue'
 import { useRouter } from 'vue-router'
 import { useDatabaseStore } from '@/stores/database'
-import { getKbTypeLabel, getKbTypeIcon, getKbTypeColor, parseModelSpec, buildDisplaySpec, buildLlmInfoPayload } from '@/utils/kb_utils'
+import {
+  getKbTypeLabel,
+  getKbTypeIcon,
+  getKbTypeColor,
+  parseModelSpec,
+  buildDisplaySpec,
+  buildLlmInfoPayload
+} from '@/utils/kb_utils'
 import { LeftOutlined, EditOutlined, DeleteOutlined } from '@ant-design/icons-vue'
 import HeaderComponent from '@/components/HeaderComponent.vue'
 import ModelSelectorComponent from '@/components/ModelSelectorComponent.vue'
diff --git a/web/src/components/KnowledgeBaseCard.vue b/web/src/components/KnowledgeBaseCard.vue
index 04ca9072..da5184cf 100644
--- a/web/src/components/KnowledgeBaseCard.vue
+++ b/web/src/components/KnowledgeBaseCard.vue
@@ -158,7 +158,13 @@ import { ref, reactive, computed, h, onMounted } from 'vue'
 import { useRouter } from 'vue-router'
 import { useDatabaseStore } from '@/stores/database'
 import { useUserStore } from '@/stores/user'
-import { getKbTypeLabel, getKbTypeColor, parseModelSpec, buildDisplaySpec, buildLlmInfoPayload } from '@/utils/kb_utils'
+import {
+  getKbTypeLabel,
+  getKbTypeColor,
+  parseModelSpec,
+  buildDisplaySpec,
+  buildLlmInfoPayload
+} from '@/utils/kb_utils'
 import {
   CHUNK_PRESET_OPTIONS,
   CHUNK_PRESET_LABEL_MAP,
diff --git a/web/src/views/DataBaseView.vue b/web/src/views/DataBaseView.vue
index 02e3749b..6bf07ba9 100644
--- a/web/src/views/DataBaseView.vue
+++ b/web/src/views/DataBaseView.vue
@@ -248,7 +248,14 @@ import ExtensionCardGrid from '@/components/extensions/ExtensionCardGrid.vue'
 import InfoCard from '@/components/shared/InfoCard.vue'
 import dayjs, { parseToShanghai } from '@/utils/time'
 import AiTextarea from '@/components/AiTextarea.vue'
-import { getKbTypeLabel, getKbTypeIcon, getKbTypeColor, parseModelSpec, buildDisplaySpec, buildLlmInfoPayload } from '@/utils/kb_utils'
+import {
+  getKbTypeLabel,
+  getKbTypeIcon,
+  getKbTypeColor,
+  parseModelSpec,
+  buildDisplaySpec,
+  buildLlmInfoPayload
+} from '@/utils/kb_utils'
 import { CHUNK_PRESET_OPTIONS, getChunkPresetDescription } from '@/utils/chunk_presets'
 
 const route = useRoute()
@@ -456,7 +463,10 @@ const buildRequestData = () => {
 
   if (newDatabase.kb_type === 'lightrag') {
     requestData.additional_params.language = newDatabase.language || 'English'
-    if (newDatabase.llm_info.model_spec || (newDatabase.llm_info.provider && newDatabase.llm_info.model_name)) {
+    if (
+      newDatabase.llm_info.model_spec ||
+      (newDatabase.llm_info.provider && newDatabase.llm_info.model_name)
+    ) {
       requestData.llm_info = buildLlmInfoPayload(newDatabase.llm_info)
     }
   }
diff --git a/web/src/views/WorkspaceView.vue b/web/src/views/WorkspaceView.vue
index f3aa8e4b..c00fd8a8 100644
--- a/web/src/views/WorkspaceView.vue
+++ b/web/src/views/WorkspaceView.vue
@@ -558,7 +558,8 @@ const stopPreviewResize = () => {
 }
 
 const resizePreview = (event) => {
-  if (!workspaceMainRef.value || resizePointerId === null || event.pointerId !== resizePointerId) return
+  if (!workspaceMainRef.value || resizePointerId === null || event.pointerId !== resizePointerId)
+    return
   const rect = workspaceMainRef.value.getBoundingClientRect()
   const relativeX = event.clientX - rect.left
   const nextPreviewPercent = Math.round(((rect.width - relativeX) / rect.width) * 100)

From 8b03c507b56ebea78fce08346074a4b4efccb61c Mon Sep 17 00:00:00 2001
From: Wenjie Zhang <xerrors@163.com>
Date: Mon, 4 May 2026 08:40:14 +0800
Subject: [PATCH 15/15] =?UTF-8?q?docs(workspace):=20=E6=B7=BB=E5=8A=A0?=
 =?UTF-8?q?=E7=94=A8=E6=88=B7=E5=B7=A5=E4=BD=9C=E5=8C=BA=E7=9A=84=20AGENTS?=
 =?UTF-8?q?.md=20=E6=96=87=E4=BB=B6=E6=94=AF=E6=8C=81=EF=BC=8C=E5=A2=9E?=
 =?UTF-8?q?=E5=BC=BA=20Agent=20=E7=9A=84=E9=95=BF=E6=9C=9F=E6=8C=87?=
 =?UTF-8?q?=E4=BB=A4=E7=AE=A1=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/agents/agents-config.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/agents/agents-config.md b/docs/agents/agents-config.md
index f5d26bef..d8d42634 100644
--- a/docs/agents/agents-config.md
+++ b/docs/agents/agents-config.md
@@ -183,6 +183,18 @@ Context 的价值不只在“配置页面”。它贯穿了从配置加载到实
 
 也就是说，运行期 Context 的基础来源并不是前端临时状态，而是数据库中保存的 AgentConfig。
 
+此外，用户工作区会默认创建 `agents/AGENTS.md`。当 Agent 开始执行时，后端会读取当前用户工作区下的这个文件，并将其内容追加到 `system_prompt`，用于补充该用户对 Agent 的长期指令或工作区约定。该文件属于用户级共享工作区，内容会随 `user_id` 和当前 `thread_id` 映射到运行时工作区路径；文件不存在、为空或不可读时不会影响 Agent 启动，单次注入内容最多读取 64 KiB，超出部分会截断并追加提示。
+
+合并后的提示词结构可以理解为：
+
+```text
+AgentConfig.config_json.context.system_prompt
+  + 用户工作区 agents/AGENTS.md 内容
+  + 运行期中间件继续追加的系统提示段
+```
+
+因此，`agents/AGENTS.md` 适合放置用户维度的稳定约束，不适合放置一次性任务要求；一次性要求仍应直接写在当前对话中。
+
 ### 4.2 Context 实例化阶段
 
 `BaseAgent` 在运行前会创建 `context_schema()` 实例，并通过 `update_from_dict()` 注入配置值。