File Management

Local Workspace File Panel

The right-side file panel manages the current project's local workspace. Uploaded files, agent-generated outputs, and files created by actions all live in this workspace.

Additional notes:

• Chat agent tools and agent/actions use the local workspace as their primary working root
• Agent/action output files remain in the local workspace by default
• File-oriented agents resolve input files from the local workspace
• Inside containers and Kubernetes Pods, the project workspace is always exposed at /workspace
• The host-side or JuiceFS-side project directory can differ by deployment mode:
  • Docker/local default: <workspace-root>/<projectId>
  • Kubernetes default: <workspace-root>/projects/<projectId> when K8S_WORKSPACE_ROOT_PATH=/projects
  • Local development can mirror the Kubernetes layout with AGENT_WORKSPACE_SUBPATH_ROOT=projects

Tree Structure and Interaction

• Files and folders are displayed as a tree with expand/collapse support
• Clicking a folder name sets it as the current upload target
• Action buttons (preview/rename/delete/download/insert into chat, etc.) appear on row hover
• Long names are truncated in-row; hovering shows the full name
• File preview opens in a modal via a dedicated Preview action instead of taking over the file tree area

Inserting File References into Chat

When hovering over a file row in the file tree, a chat icon button appears. Click it to insert a file reference into the current conversation:

• Local Workspace Files: References files in the workspace directory; Agent can read them by path

After insertion, file references appear inline in the message input as blue file chips. When you send a message, the file context is attached and the Agent automatically reads the referenced files.

How to use:

1. Find the target file in the file tree
2. Hover and click the "Insert into chat" button (chat icon)
3. The file reference is added at the current cursor position in the input box
4. Type your question and send; the Agent will automatically read the referenced file

Note: To remove an inserted file reference, place the cursor next to the file chip and press Backspace or Delete.

Composer @ File Search

You can also search files directly from the chat composer:

1. Type @ in the composer
2. Continue typing a file name or path keyword
3. Pick a suggested file
4. ResearchX attaches that file to the current message

Use this when you need to reference a script, log, output file, or dataset without expanding the file tree.

Supported Actions

• Upload files
• Upload into a specific folder
• Choose overwrite or automatic numbered rename when an uploaded file conflicts with an existing path
• Import files or folders from another project
• Create folders
• Preview files (modal)
• Rename files/folders
• Delete files/folders
• Batch delete files/folders
• Insert file reference into chat

Import Local Workspace Files from Another Project

Local workspace import is useful for reusing scripts, templates, sample data, or previous outputs from another project.

How to use:

1. Click the folder import icon in the right-side file panel
2. Choose a source project
3. Browse the source project's local workspace and select one or more files or folders
4. Choose the destination directory in the current project
5. Run the import

Notes:

• Import copies files; it does not move or delete anything from the source project
• The .agent directory is hidden from cross-project import
• If your role cannot write to the current workspace, the import action is disabled

Storage Quotas

When the deployment enables PROJECT_STORAGE_QUOTA=juicefs, ResearchX reads and manages project storage quotas through JuiceFS project paths:

• Project lists can show used storage, quota limit, and status
• Project settings can show or update the project's storage quota, depending on deployment and role permissions
• If local workspace upload exceeds the underlying filesystem quota, the page shows a clear project-storage-quota exceeded message
• Missing quota configuration is treated as unlimited rather than as an upload failure

Guidance:

• Check remaining space in the project list or settings before large uploads
• If an upload fails because quota is exceeded, remove unused outputs or ask an admin to raise the quota
• In Kubernetes deployments, quota is usually calculated from the real JuiceFS project directory, not from the literal in-container /workspace path

Files as Action / Agent Inputs and Outputs

File-oriented actions use real files already present in the current project's local workspace.

When chat references a file, matching works like this:

• unique match: auto-bind
• unique stem match: for example input can resolve to input.txt when it is unambiguous
• missing file: the assistant returns a clarification with available files
• ambiguous name: the assistant asks for a more specific file name or path

Current behavior for file-oriented actions:

• input files are read from the local workspace
• output files are written directly back into the local workspace
• generated files are shown on the agent card

Notes:

• the local workspace is the primary working directory for agent/action execution
• .agent is reserved for internal metadata and should not be edited manually
• when PROJECT_STORAGE_QUOTA=juicefs, storage quotas are evaluated against the underlying JuiceFS project path rather than the in-container /workspace mount path

File Preview

Click the Preview action in a file row to open the preview modal.

Supported File Types

Image Files

• Supported formats: png, jpg, jpeg, gif, webp, svg, bmp
• Preview method: Images scale to fit the modal viewport

PDF Documents

• Supported formats: pdf
• Preview method: Rendered inside the modal with an embedded viewer including toolbar and navigation

Office Documents

• Word documents: supports docx format, rendered in-browser preserving original styling
• PowerPoint presentations: supports pptx format with a lazy-loaded dedicated renderer
• Excel spreadsheets: supports xlsx and xls formats with a lazy-loaded spreadsheet renderer and worksheet switching

Code Files

• Supported formats: 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
• Preview method: Displayed in a code-style view with line numbers and syntax highlighting, supports scrolling

Text Files

• Supported formats: txt, md, csv, log, ini, conf, env
• Preview method: Displayed as plain text or Markdown, supports scrolling

Files handled by Visualizer plugins

• Projects can place custom preview plugins under .agent/visualizers
• The system reads each plugin's VISUALIZER.yaml and uses its match rules to decide whether the plugin supports a file
• When matched, the preview modal loads the plugin's Web page as the renderer
• This is useful for pdb/cif, csv/tsv, special graph formats, and other file types not covered well by the built-in previewers

Preview Behavior

• Code files are shown with line numbers and syntax highlighting
• Text and code previews support scrolling for long content
• PDFs render inside the preview modal with an embedded viewer
• Word/PowerPoint/Excel renderers are lazy-loaded when opened to reduce initial load time
• Images scale to fit the modal viewport
• HTML files and Visualizer plugins can open safely inside the preview modal, which is useful for custom visualization pages
• Unsupported file types show a clear unsupported-preview message
• Very large files are not previewed to avoid slow loading
• Whether a visualizer takes over preview is not hardcoded in the host; it is determined by the plugins currently discovered under .agent/visualizers

Usage Tips

• Close the preview modal by clicking the overlay or the close button
• Continue working in the file tree while the preview is open
• Local workspace files can be previewed

Agent Skills (Project-level)

The local workspace supports a single project-level skill directory:

• /workspace/.agent/skills

Recommended structure:

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

How to use:

• Install or remove skills from the project Skills modal in the header
• Use /skill:<name> in chat to invoke a skill explicitly
• Add arguments if needed: /skill:<name> <arguments>
• SKILL.md should include frontmatter with name and description

Notes:

• Skills are discovered only from .agent/skills
• The right-side Local Workspace tree hides .agent by default, but skill discovery and invocation still work
• Skills live under .agent/skills and are separate from ordinary workspace folders

Visualizers (Project-level)

The local workspace also supports a project-level visualizer plugin directory:

• /workspace/.agent/visualizers

Recommended structure:

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

How to use:

• place a visualizer directory under .agent/visualizers
• inspect and manage it from the Visualizers tab inside the project Agents modal
• when opening file preview, the system automatically matches plugins using the match rules declared in VISUALIZER.yaml

Notes:

• .agent is hidden by default in the file tree, but that does not affect visualizer discovery
• visualizers are currently read-only preview plugins focused on rendering files
• avoid overly broad rules such as text/plain unless you really want the plugin to match generic text files
• Visualizers are best for read-only frontend rendering. If a visualizer needs other files, use the plugin configuration and the data loaded by preview instead of relying on external page state

Global Skill Repositories (Admin)

Admins can open Skill Management from the lower-left menu to maintain the shared skill catalog:

• Add GitHub or other Git repository URLs
• Manually sync a repository
• Search repositories and skills
• Collapse or expand repositories
• Delete individual skills
• Delete an entire repository

Notes:

• After a repository is added, the system downloads it and scans for SKILL.md
• Each directory containing a SKILL.md is treated as one skill
• Parsed skills become available in the project Skills modal, grouped by repository

Key Rules

• Files belong to the current project only; cross-project access is blocked
• Deleting a folder removes all nested files and subfolders
• In docker-backed execution, the in-container workspace root is /workspace

Best Practice

Use a consistent folder naming convention and always confirm the upload target folder before uploading.