文件管理

本地工作目录文件面板

右侧文件管理面板用于管理当前项目的本地工作目录。上传文件、Agent 生成的输出，以及 action 创建的文件都会保存在这个工作目录中。

补充说明：

聊天 Agent 工具与 agent/action 默认都以“本地工作目录”作为工作根目录
当前 agent/action 输出文件默认保留在本地工作目录
文件型 agent 输入从本地工作目录解析
在容器和 Kubernetes Pod 内，项目工作目录始终暴露为 /workspace
宿主机侧或 JuiceFS 侧的真实项目目录会随运行模式变化：
- Docker / 本地默认：<workspace-root>/<projectId>
- Kubernetes 默认：当 K8S_WORKSPACE_ROOT_PATH=/projects 时为 <workspace-root>/projects/<projectId>
- 本地开发如果想模拟 Kubernetes 目录布局，可设置 AGENT_WORKSPACE_SUBPATH_ROOT=projects

树形结构与交互

文件与文件夹按树形展示，可展开/折叠目录
点击目录名可将其设为"上传目标目录"
鼠标悬停到行时显示操作按钮（预览、重命名、删除、下载、插入到对话等）
文件名过长时会截断显示；悬停可查看完整文件名
文件预览通过单独的"预览"按钮打开弹窗，不会直接占用文件树区域

插入文件引用到对话

在文件树中，悬停到文件行时会显示一个对话图标按钮，点击后可将文件引用插入到当前对话：

本地工作区文件：引用工作目录中的文件，Agent 可通过路径读取

插入后的文件引用会以内联淡蓝色文件标签显示在输入内容中，发送消息时会附带文件上下文，Agent 会自动读取相关文件内容。

操作方式：

在文件树中找到目标文件
悬停后点击「插入到对话」按钮（对话图标）
文件引用会添加到输入框当前光标位置
输入问题后发送，Agent 会自动读取引用的文件

注意：如需移除已插入的文件引用，将光标放在文件标签旁边后按 Backspace 或 Delete 即可。

输入框 `@` 快速附加文件

除了从文件树手动插入，你还可以在聊天输入框中直接使用 @ 搜索文件：

在输入框里输入 @
继续输入文件名或路径关键词
从下拉建议中选择目标文件
系统会自动把该文件作为附件加入本轮消息

适用场景：

当前会话中临时引用某个脚本、日志或输出文件
文件很多时，避免在文件树中反复展开目录查找

文件引用的复制粘贴

文件引用标签现在可以随消息一起复制：

从输入框或已发送的用户消息复制含文件标签的内容，再粘贴回 ResearchX 输入框时，系统会尽量恢复为文件标签
粘贴到普通文本工具时，会显示为文件名或路径，方便人工阅读
如果目标文件已不存在，系统会按普通文本处理，不会发送失效附件

建议在复用上一轮分析对象、对比多个文件或把文件引用转移到新会话时使用。

文件路径自动链接

聊天消息和工具输出中的工作区文件路径会自动转为可点击链接：

支持 /workspace/...、相对路径、裸路径和常见 file:// 链接
只有能解析到具体文件的路径才会被链接；目录路径会保持普通文本
链接会按当前项目的本地工作目录解析，不会跳到其他项目

如果路径没有自动识别，通常是因为路径不完整、文件不存在，或同名文件造成歧义。让助手输出完整相对路径通常可以解决。

支持操作

上传文件
上传到指定文件夹
上传时遇到同名文件可选择覆盖，或自动追加编号后保留两个文件
从其他项目导入文件/文件夹
新建文件夹
预览文件（弹窗）
重命名文件/文件夹
删除文件/文件夹
批量删除文件/文件夹
插入文件引用到对话

从其他项目导入本地工作区文件

本地工作目录新增跨项目导入能力，适合复用脚本、模板、数据样例或历史输出。

操作方式：

在右侧文件面板点击文件夹导入图标
选择来源项目
浏览来源项目的本地工作区并勾选一个或多个文件/文件夹
选择当前项目中的目标目录
执行导入

补充说明：

导入本质上是复制，不会移动来源项目中的原文件
.agent 目录不会出现在跨项目导入列表中
如果当前角色没有工作区写权限，导入按钮会被禁用

存储配额

当部署启用 PROJECT_STORAGE_QUOTA=juicefs 时，ResearchX 会按项目工作区路径读取和设置 JuiceFS 配额：

项目列表可显示已用空间、配额上限和当前状态
项目设置中可查看或调整项目存储配额，具体权限取决于部署和角色配置
上传本地工作区文件时，如果底层文件系统返回配额超限，页面会显示“项目存储配额已超限”
未设置配额时，系统会把项目视为不限额，而不是上传失败

使用建议：

大文件上传前先查看项目列表或项目设置中的剩余空间
如果上传失败但确实需要保留文件，先删除无用输出或联系管理员提高配额
Kubernetes 部署下，配额通常按 JuiceFS 中的真实项目目录计算，不按容器内 /workspace 字面路径计算

文件作为 Action / Agent 输入输出

当前文件型 action 使用当前项目本地工作目录中的真实文件作为输入。

聊天里引用文件时，系统会按以下规则匹配：

唯一命中：自动绑定
唯一 stem 命中：例如项目里只有 input.txt，输入 input 也可命中
找不到：系统会明确提示当前可用文件
同名歧义：系统会要求你进一步确认具体文件名或路径

当前文件型 action 的行为：

输入文件读取自本地工作目录
输出文件直接写回当前项目的本地工作目录
agent 卡片会显示生成的文件

说明：

本地工作目录是 agent/action 的主要工作目录
.agent 目录用于内部元数据，不建议手动修改其中内容
当 PROJECT_STORAGE_QUOTA=juicefs 时，存储配额是基于底层 JuiceFS 项目路径计算，而不是基于容器内的 /workspace 挂载路径

文件预览

在文件行右侧悬浮操作区点击"预览"按钮后，会打开预览弹窗。

支持的文件类型

图片文件

支持格式：png、jpg、jpeg、gif、webp、svg、bmp
预览方式：图片会在弹窗内按可视区域自适应缩放显示

PDF 文档

支持格式：pdf
预览方式：在弹窗内以内嵌阅读器展示，支持工具栏和页面导航

Office 文档

Word 文档：支持 docx 格式，在浏览器中尽量保留原文档样式渲染
PowerPoint 演示文稿：支持 pptx 格式，打开时按需加载独立预览组件
Excel 表格：支持 xlsx、xls 格式，打开时按需加载表格预览组件，支持工作表切换

代码文件

支持格式：js、jsx、ts、tsx、mjs、cjs、json、html、css、scss、py、rb、go、rs、java、kt、swift、php、sh、bash、zsh、sql、yml、yaml、toml、xml、c、cc、cpp、h、hpp
预览方式：以带行号的代码视图展示，支持语法高亮和滚动查看

文本文件

支持格式：txt、md、csv、log、ini、conf、env
预览方式：以纯文本或 Markdown 格式展示，支持滚动查看

Visualizer 插件接管的文件

项目可在 .agent/visualizers 中放置自定义预览插件
系统会读取插件的 VISUALIZER.yaml，根据其中的 match 规则判断某个文件是否由插件支持
命中后，预览弹窗会加载该插件的 Web 页面进行展示
适合 pdb/cif、csv/tsv、特殊图格式或其他宿主默认不支持的文件

预览功能说明

代码文件以带行号的代码视图展示，支持语法高亮
文本和代码预览支持滚动查看长内容
PDF 在弹窗内以内嵌阅读器展示，保留工具栏和导航面板
Word/PowerPoint/Excel 预览组件在打开时按需加载，减少初始加载时间
图片在弹窗内按可视区域自适应缩放显示
HTML 文件和 Visualizer 插件可以在预览弹窗中安全打开，便于查看自定义可视化页面
当前不支持的文件类型会提示"暂不支持预览"
过大的文件不会进入预览，以避免加载过慢
visualizer 是否接管预览，不是写死在宿主里的，而是由 .agent/visualizers 中插件自己的匹配规则决定

使用提示

预览弹窗支持点击遮罩层或关闭按钮关闭
可在预览的同时继续在文件树中进行其他操作
本地工作目录中的文件可预览

Agent Skills（项目级）

本地工作目录支持项目级 skill 目录，统一放在：

/workspace/.agent/skills

建议结构：

.agent/skills/
  <skill-name>/
    SKILL.md
    scripts/
    references/

使用方式：

通过项目顶部的 Skills 弹框安装或删除 skill
在对话输入 /skill:<name> 显式调用 skill
可附带参数：/skill:<name> <arguments>
SKILL.md 建议包含 frontmatter：name、description

注意：

仅会从 .agent/skills 发现项目 skills
右侧 Local Workspace 文件树默认隐藏 .agent 目录，但不会影响 skill 发现和调用
skills 位于 .agent/skills 下，与普通工作区文件夹分开管理

Visualizers（项目级）

本地工作目录还支持项目级 visualizer 插件目录：

/workspace/.agent/visualizers

推荐结构：

.agent/visualizers/
  <namespace>/<visualizer-name>/
    VISUALIZER.yaml
    web/
      index.html
      ...

使用方式：

将 visualizer 目录放入 .agent/visualizers
通过项目顶部 Agents 弹框中的 Visualizers 标签页查看和管理
打开文件预览时，系统会自动根据 VISUALIZER.yaml 的 match 规则匹配插件

注意：

.agent 默认在文件树中隐藏，但不会影响 visualizer 发现
visualizer 当前是只读预览插件，主要负责文件展示
预览插件建议避免把 text/plain 作为过宽的匹配规则，以免误命中普通文本文件
Visualizer 适合做只读前端渲染；如需访问其他文件，请通过插件配置和预览载入的数据完成，不要依赖页面外部状态

全局 Skill 仓库（管理员）

管理员可从左下角入口进入 Skill 管理 页面，对全局 skill 仓库统一维护：

添加 GitHub 或其他 Git 仓库地址
手动同步单个 repository
搜索 repository 与 skills
折叠/展开 repository
删除单个 skill
删除整个 repository

说明：

repository 加入后，系统会自动拉取仓库并扫描其中的 SKILL.md
系统以包含 SKILL.md 的目录作为一个 skill 目录
解析出的 skills 可在项目的 Skills 弹框中按 repository 选择安装

关键规则

文件默认仅属于当前项目；如需复用其他项目内容，请通过“从其他项目导入”显式复制
删除文件夹会删除该目录下全部子文件和子目录
docker 形态下，Agent 工具和 action 在容器内看到的工作目录根为 /workspace

使用建议

使用统一的文件夹命名规范，按主题或阶段划分目录
将“上传目标目录”切到正确文件夹后再执行上传，避免后续整理成本

文件管理

On this page