Skip to content

[Feature] 文件树支持 Workbench 独立 Pane 与文件路径拖拽引用 #661

Open
Open
[Feature] 文件树支持 Workbench 独立 Pane 与文件路径拖拽引用#661
Labels
enhancementNew feature or request

Description

@yovinchen
yovinchen
opened on Aug 28, 2026

Affected area

  • Desktop UI (agent-ui / agent-gui)
  • Gateway WebUI (agent-gateway/web)
  • Session Workbench / Right Dock
  • Composer references and terminal input

Problem statement (what should this solve)

当前右侧 File Tree 虽然由共享 agent-ui 组件提供，Desktop 与 WebUI 也已经具备文件列表、搜索、展开和文件操作能力，但它仍是依赖 Right Dock 上下文的单例工具，不是像终端一样拥有稳定身份、可拖入 Workbench 任意拼接的独立 Pane。

文件树节点也只支持打开、选择和右键插入引用，缺少直接拖拽语义：

  • 不能把整个 File Tree 从 Right Dock 拖到 Workbench 的左、右、上、下分屏区域。
  • 不能把文件或文件夹拖到某个 Composer，创建对应的结构化文件引用。
  • 不能把文件或文件夹拖到某个终端，插入经过当前 shell 正确转义的路径。
  • 多会话、多项目和多终端 Pane 下，如果仍依赖页面级“当前会话/当前项目”，拖放很容易被路由到错误的输入框或终端。
  • Desktop 原生文件拖放和 Web 外部文件上传表达的是“导入/上传”，不能替代工作区内部路径的“引用/插入”。

需要将 File Tree 从 Right Dock 专用面板解耦为共享 Workbench Surface，并建立独立于布局拖拽的工作区路径引用协议，使 Desktop 与 WebUI 保持相同交互和安全边界。

Proposed behavior

1. File Tree 成为独立 Workbench Surface

  • 把 FileTreePanel 的数据、状态和动作依赖从 RightDockContext 抽离为显式 Surface props/controller。
  • 新增 fileTree Workbench Surface，使用项目身份生成稳定 surface key，并支持四向分屏、Pane 移动、关闭、聚焦、尺寸约束与布局恢复。
  • Right Dock 的 File Tree 标签支持拖出和“在分屏中打开”，交互与现有终端入口一致。
  • 同一项目第一阶段只允许一个交互式 File Tree 视图；进入 Workbench 后，Right Dock 显示定位/聚焦入口，避免重复请求、订阅和状态竞争。
  • 关闭 File Tree Pane 只关闭视图，不改变项目、文件或会话状态。

2. 文件和文件夹拖到 Composer 时创建引用

  • 文件树行支持拖拽，payload 必须携带来源项目、工作区根、相对路径和 file | dir 类型。
  • 拖到具体 Composer 后，调用该 Pane 自己的 Composer 引用接口，插入与现有 @ 文件/文件夹 一致的结构化 Chip。
  • 插入后聚焦输入框，但不自动发送消息，也不把工作区文件复制到上传暂存区。
  • 目标路由必须使用实际命中的 paneId + conversationId + project，不能依赖页面级当前会话。
  • 当前引用模型只保存项目内相对路径，因此 v1 拒绝跨项目拖入并显示明确受阻提示；不得把来源路径静默解释为目标项目路径。

3. 文件和文件夹拖到终端时插入路径

  • 每个终端视图注册明确的文本插入目标，拖放后通过 xterm 的 paste/input 管线插入路径并聚焦终端。
  • 只插入文本，不附加换行，不自动执行命令。
  • 根据目标 shell 生成安全路径：POSIX shell、PowerShell 和 cmd.exe 分别使用各自的转义规则，并拒绝 NUL/控制字符。
  • 本地终端和 Gateway 项目终端插入该项目下的绝对路径，并要求来源项目与终端项目相同。
  • SSH 终端不能把本机路径直接当成远端路径。v1 在没有显式 localRoot -> remoteRoot 映射时拒绝投放；后续可在 SFTP/SSH 工作区映射建立后开放。

4. 布局拖拽与内容拖拽保持隔离

  • 整个 File Tree 标签/Pane 的移动继续使用 Workbench 布局拖拽协议。
  • 文件树节点使用独立的 workspacePath 内容拖拽协议，不能加入会触发 Pane 自动停靠的 WorkbenchDragPayload。
  • Composer、终端和不支持的目标应显示明确的接受/禁止状态，例如“引用文件”“引用文件夹”“插入路径”“不能引用其他项目”“SSH 未配置路径映射”。
  • 保留外部 Finder/Explorer/浏览器文件拖入的现有上传或工作区导入语义，不与内部路径拖拽互相覆盖。

5. Desktop 与 WebUI 共用核心实现

  • File Tree Surface、节点拖拽状态机、目标注册、路径校验、shell 转义和提示样式下沉到 @liveagent/ui。
  • Desktop 只保留 Tauri 文件系统和原生 drop 适配；WebUI 继续通过 Gateway shim 访问文件系统。
  • 使用 Pointer Events 和统一 hit testing 实现应用内部拖拽，不通过浏览器 File/DataTransfer 伪造工作区文件。
  • 鼠标和触控笔支持拖拽；Touch v1 保留菜单式“引用到当前输入框/在分屏中打开”降级入口。

Acceptance criteria

  • Desktop 与 WebUI 均可把 File Tree 从 Right Dock 拖入 Workbench 四向分屏，也可通过菜单打开。
  • File Tree Pane 拖动和调整布局时保持稳定身份，不因位置变化重复挂载。
  • 同一项目不会同时出现两个竞争数据订阅的交互式 File Tree 实例。
  • 文件与文件夹可以拖到指定会话 Pane 的 Composer，生成正确的 file/dir 引用 Chip。
  • Composer 拖放按实际 conversationId 路由，不串到焦点之外的其他会话。
  • 文件引用拖放不会上传、复制文件或自动发送消息。
  • 文件与文件夹可以拖到同项目本地/Gateway 终端，并插入正确转义的路径。
  • 终端插入不附加换行、不自动执行，并继续遵守 stdin 禁用和输入背压。
  • POSIX、PowerShell 和 cmd 路径中的空格、引号、非 ASCII 字符有自动化测试。
  • 跨项目 Composer/终端目标明确拒绝，不发生路径身份混淆。
  • 未配置路径映射的 SSH 终端明确拒绝本地文件投放。
  • Desktop 原生 drop 与 Web 外部上传行为无回归。
  • Workbench 布局拖拽和文件内容拖拽分别有 Desktop/Web 回归测试。

Estimated change scope

  • crates/agent-ui/src/components/project-tools/file-tree/**
  • crates/agent-ui/src/components/project-tools/RightDock*
  • crates/agent-ui/src/components/workbench/**
  • crates/agent-ui/src/components/chat/MentionComposer*
  • crates/agent-ui/src/components/project-tools/XTermViewport.tsx
  • crates/agent-ui/src/lib/workbench/**
  • crates/agent-ui/src/lib/chat/mentionReferences.ts
  • crates/agent-ui/src/lib/projectTools/**
  • crates/agent-gui/src/pages/ChatPage.tsx
  • crates/agent-gui/src/pages/chat/surfaces/**
  • crates/agent-gateway/web/src/app/GatewayApp*
  • crates/agent-gateway/web/src/app/workbench/**
  • Desktop / WebUI targeted tests

Alternatives considered

  • 只在 Right Dock 内给文件行增加 HTML5 drag/drop：无法进入任意 Workbench Pane，也会让 Desktop/Web 与原生文件上传协议混杂，不采用。
  • 把文件节点加入现有 Workbench 布局 payload：Pane 中心命中可能被解释为分屏/停靠，内容引用与布局操作语义冲突，不采用。
  • 同时渲染 Right Dock 和 Workbench 两棵完整文件树：当前数据 hook 会形成重复请求、订阅和状态竞争；v1 使用单交互视图租约。
  • 终端直接写 PTY 后端：会绕过 xterm paste、stdin 禁用和背压管线；应通过终端视图输入 sink 插入。
  • SSH 终端直接插入本机绝对路径：本地项目根与远端目录没有可靠对应关系，容易执行错误命令，不采用。

Non-goals

  • v1 不支持没有显式映射的本地路径到 SSH 远端路径转换。
  • v1 不把文件树改造成多根工作区权限模型；仍遵循一个 WorkspaceProject.path 的项目权威边界。
  • v1 不允许拖放自动发送消息或自动执行终端命令。
  • v1 不改变外部文件上传、目录授权或工作区导入协议。

Related issues / pull requests

Pre-submit checklist

  • I searched existing issues and pull requests and found no duplicates.
  • This proposal is focused on a single feature or improvement.
  • I understand a PR should come after this issue is confirmed by maintainers, otherwise it will be converted to draft.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions