ResearchX Tutorial Guide

不止于研究

让灵感在 AI 的共鸣中生长与演化。

把研究从“灵感驱动”推进到“系统驱动”。

提出问题并快速验证假设
整合材料并沉淀可解释结论
把高频流程交给 Agent 持续执行

39 Slides

Beginner+

What We'll Cover

01 · CORE

Foundation

Getting Started

Login, projects, and workspace layout

02 · CORE

Foundation

Chat & Files

AI conversations, models, and file management

03 · FOUNDATION

Foundation

Skills & Settings

Slash commands, custom instructions, env vars

04 · EXECUTION

Execution

Agent System

Installing, running, and automating agents

05 · EXECUTION

Execution

Docker Containers

Persistent containers, GPU support, fixed mounts, and config

06 · EXECUTION

Execution

Advanced Features

Web search, cross-project import, best practices

07 · SCALE

Scale

Conversations & Branching

Branching, pinning, export, conversation lifecycle

08 · SCALE

Scale

Admin Panel

User management, model config, monitoring

09 · SCALE

Scale

Integrations & Desktop

MCP servers, scheduled tasks, tool permissions, Electron

Overview

What is ResearchX?

An AI-powered research workspace where you create Projects, chat with LLMs, upload files, and run agent tasks inside persistent Docker containers.

Project-scoped isolation — all data lives within a project boundary
Multi-model chat — choose and switch LLM models per conversation
Agent pipeline — automated tasks with ticket → run → step → artifact flow
Persistent containers — dedicated Docker environments per project

Capability Matrix

CORE SYSTEM

Project Boundary

Data, chat, files, and agent runs remain isolated by project.

Model Layer

Switch LLMs per conversation with shared workspace context.

Execution Plane

Agents execute in persistent containers for reproducible outcomes.

Traceability

Ticket → Run → Step → Artifact keeps process and outputs auditable.

Question → Evidence → Execution → Result

Architecture

Platform at a Glance

Foundation Layer

Frontend

Next.js 16 + React 19
Tailwind v4 + shadcn/ui

Backend

Next.js Route Handlers
JWT dual-token auth

Database

SQLite or PostgreSQL
Prisma ORM

Service Bridge

Capability Layer

Chat

SSE streaming
Multi-model

Agents

Ticket pipeline
Dedup via inputHash

Containers

Docker per-project
GPU support

Storage

Local workspace
Project files

Getting Started

Step 1: Login & Registration

Navigate to /auth — login or register tab
First user triggers bootstrap mode (auto-admin)
Password requirements: 8+ chars, uppercase, lowercase, number, special
Public registration is admin-configurable
Auth uses JWT dual-token (access + refresh, httpOnly cookies)

ResearchX 账户

使用邮箱和密码登录或注册。

Sign In

Register

当前未开放用户注册，请联系管理员由后台创建账号。

Email

邮箱

Password

密码（8-32 位，且包含大小写字母、数字和特殊字符）

保持登录 30 天

I'm not a robot

◔

Protected by ALTCHA

登录

Getting Started

Step 2: Project Dashboard

在这里快速定位项目状态，并进入具体工作空间。

支持关键词搜索与状态筛选（全部 / 活跃 / 已归档）
列表展示：名称、领域、角色、状态、最近更新时间
可一键进入项目，也可通过“更多操作”执行编辑与维护
按最近更新排序并支持分页，快速定位当前重点项目
面向多项目规模管理，保证项目入口清晰且可治理

Project Domain Role Status Updated At Actions

Oncology Discovery Showcase

oncology owner active 2026-04-21 16:42

Enter ···

Biomarker Validation

immunology manager active 2026-04-20 09:18

Enter ···

Prev 1 / 3 Next

Getting Started

Step 3: Create a Project

Click "New Project" from the sidebar or dashboard
Fill in project name (required), with optional domain and description
The creator is automatically assigned as owner
Manage members inside the project with owner / manager / editor / viewer roles

Create Project

Project Name *

Lung Cancer Biomarker Study

Domain

oncology

Description

Evaluate plasma protein markers for early NSCLC screening and cohort validation.

Cancel Create Project

Member Roles

Member Role Scope

you@lab.org Owner All settings

pi-assistant@lab.org Editor Chat + files

Workspace

The 3-Panel Layout

The project workspace is your central hub — everything happens here.

Sidebar

📁 Project tree

💬 Conversations

🔍 Search

➕ New chat

📌 Pinned chats2

Chat Area

86% · 112k / 128k streaming

🤖 AI response bubbles stream here...

Compressed context summary is shown inline in the message flow.

User messages appear above

Tool: read_file status: success · 42ms

Thinking expandable reasoning block

@file: cohort_summary.csv Task: run-2026-04-21

Model: ▾ @ to attach files · / for commands ▶

File Panel

Local Workspace Files

📁 Workspace files

📂 Local Workspace

⬆️ Upload files

👁️ Preview & download

↔ Resizable panel width

Chat & AI

Chatting with AI

New Chat — click the button in sidebar or use keyboard
Type your message in the composer bar at the bottom
AI responds via SSE streaming — real-time message bubbles
Attach file references by clicking files in the right panel
Attach task references to include agent output as context
Use slash commands like /task:code_execution

project chat

streaming

请根据我附加的项目文件，先总结关键结果，再给下一步实验建议。

已读取相关上下文，我先给出结果摘要，再列出可执行的下一步计划。

Tool: read status: success · 51ms

Thinking click to expand

@file: cohort_summary.csv task: ticket_2417 (completed)

@ 引用文件，/ 调用命令，然后输入你的问题...

Model: GPT-5.4 ▾ Context: 42k / 128k

Send

@ mention

cohort_summary.csv

/ commands

/task:code_execution

Chat & AI

Model Selection & Context Window

Pick any configured model from the composer dropdown
Models are managed by admins at /workspace/admin/models
A default model is set system-wide
Context ring indicator shows token usage vs. model limit
Automatic context compaction kicks in near the limit

models-context

live

Current model

GPT-5.4 ▾

default /workspace/models

gpt-5.4 image

my-gpt-4o-mini image private

text-only-llm no image private

67%

CONTEXT

86K / 128K

Context compaction triggered

Older turns were compressed into a short summary to keep the conversation within model limits.

Recent window last 28 turns kept

Reserved budget 2K tokens

Compaction status completed

Summary text is injected back into the message flow, so downstream answers still keep continuity.

Files

File Management

One local workspace file panel for uploads, outputs, and references
Uploads and agent-generated files live together in the project local workspace
Available actions: upload, folder create, rename, move, delete, download
Preview supports text/code/markdown/html, plus plugin-based preview for richer formats
Workspace files stay project-scoped and can be attached into chat context as file references
Use the same panel controls to refresh, switch target path, and track upload progress

◂ Project Files

↻ 📁 ↑

Upload target: /workspace

Workspace Files Local Workspace

📁 datasets

└─ cohort_summary.csv

📁 protocols

analysis_notes.md

survival_plot.xlsx

cohort_summary.csv

Uploading · 2/3

Agent System

Agent Pipeline Overview

Tasks execute through a structured pipeline with deduplication and artifact tracking.

Ticket receives the request with normalized input.
Run deduplicates by inputHash and reuses matching executions.
Step runs actions in sequence and persists each output.
Artifact stores generated files for later preview and reuse.
Event stream keeps status and progress visible in real time.

智能体资源管理

agent / action / mcp

搜索智能体、智能工具、内置工具、运行环境或可视化

本地安装资源目录

已选智能体: 0 ✓ ↓

GEO Metadata Preview Agent

Preview GEO metadata before differential analysis.

RNA-seq Differential Expression Analysis Agent

Complete RNA-seq analysis workflow with downstream outputs.

RNA-seq Differential Expression Analysis Agent

本地安装

Quality control, differential analysis, enrichment, and report generation.

Installing & Managing Agents

Open Assets modal from the header "Agents" button
5 tabs: Agents, Actions, Runtimes, Visualizers, Built-in
Install from Git repositories or import from other projects
Agents installed to .agent/agents/, actions to .agent/actions/
Built-in chat tools: read, bash, edit, write, web_search

assets_modal tabs

Agents — task execution definitions

Actions — process & prompt actions

Runtimes — execution runtimes

Visualizers — file preview plugins

Built-in — web search, task tool

Agent System

Running Agent Tasks

Inline in chat — agents triggered automatically during conversation
Manual run — trigger with custom input from Assets modal
Slash commands — type /skill:name to invoke directly
View all tasks via "Tasks" button in header
Filter by project-scope or conversation-scope

agent_tasks_view

All Running Completed Failed

web_search ● running

code_execution ✓ completed

web_search ✓ completed

Agent System

Auto Mode vs Manual Confirmation

Auto Mode — ON

Agent tools run without confirmation
Faster execution, hands-off workflow
Best for trusted, well-tested agents
Toggled via "Auto Mode" switch in header

Auto Mode — OFF

Each agent tool call requires approval
Inline confirmation cards appear in chat
Review parameters before execution
Safer for new or untested agents

Dev Mode adds agent-authoring and visualizer-authoring skills automatically. Quick-fix broken agents directly in chat.

Agent System

Agent Definition: AGENT.yaml

An Agent is a multi-step workflow defined in YAML. Each step calls an Action and chains results together.

name — unique identifier for the agent
input_schema — JSON Schema defining user inputs
steps — ordered list of action calls
result — which step's output is the final result
Steps can have depends_on for parallel execution
Optional when condition for conditional execution

                    # AGENT.yaml

                    name: paper_summary

                    title: Paper Summary Agent

                    input_schema:

                      properties:

                        paper_title:

                          type: string

                    steps:

                      - step_id: lookup

                        action_ref: fetch_abstract

                        input:

                          query: ${input.paper_title}

                      - step_id: summarize

                        action_ref: summarize_text

                        input:

                          text: ${steps.lookup.output}

Agent System

Action Types: Process vs Prompt

Actions are the building blocks of Agents. Two execution modes cover both code and AI tasks.

Process Action

Runs a script (Node.js, Python, R...)
Requires a Runtime (local or container)
Entry point defined in ACTION.yaml
Input/output via stdin/stdout JSON
Supports container-level GPU config
Best for: data processing, API calls, file I/O

Prompt Action

No script needed — config-only
Define system and user prompts
Output mode: text or JSON
JSON mode uses internal tool call for reliability
capabilities block to scope tools & skills
Best for: summarization, classification, extraction

Tip: Use merge_from_actions in Agent to auto-merge input_schema descriptions from referenced Actions — reduces duplication.

Agent System

Runtime & Execution Environment

Runtimes define where and how Actions execute. Two kinds available:

Local Runtime

Runs on host machine
Fast startup, no isolation

Container Runtime

Runs in Docker
Isolated, GPU support

RUNTIME.yaml — defines kind, source, config
Config includes: protocol, timeout, resources
Action-level container config overrides Runtime defaults
Container can specify image, workdir, GPU, mounts

                    # RUNTIME.yaml

                    name: python-runner

                    kind: container

                    config:

                      protocol: stdio

                      timeout_sec: 300

                    # Action-level container override

                    config:

                      container:

                        image: python:3.11

                        gpu: 1

                        workdir: /workspace

Visualizer

Visualizer Plugin System

Custom file preview plugins that render inside the platform. Auto-discovered from the project workspace.

Located at .agent/visualizers/<ns>/<name>/
VISUALIZER.yaml — declares file matching rules
Match by: extensions, MIME types, file names, max size
Web entry: web/index.html — rendered in iframe
Priority system — higher priority wins conflicts
Create via visualizer-authoring skill in Dev Mode

                    # VISUALIZER.yaml

                    name: csv-grid

                    title: CSV Grid Preview

                    version: 1

                    priority: 80

                    match:

                      extensions:

                        - .csv

                        - .tsv

                      mime_types:

                        - text/csv

                      max_size_mb: 20

                    entry:

                      type: web

                      path: ./web/index.html

Agent System

Creating Agents in Dev Mode

Switch to Dev Mode to unlock agent creation directly in chat.

agent-authoring skill auto-synced in Dev Mode
Just describe what you want in natural language
The skill generates AGENT.yaml + ACTION.yaml files
Automatically reuses existing Actions when possible
Quick-fix broken agents directly in conversation
Also supports visualizer-authoring for preview plugins

dev_mode_workflow

1 Toggle Dev Mode in project header

↓

2 Chat: "Create an agent that..."

↓

3 Skill generates .agent/agents/ + .agent/actions/

↓

4 Test, iterate, quick-fix if needed

↓

5 Switch back to Standard Mode

Agent System

Asset Directory Structure

All project assets live under the .agent/ directory with a clear namespace layout.

agents/ — Agent definitions (AGENT.yaml)
actions/ — Action definitions + entry scripts
runtimes/ — Runtime environments
skills/ — Installed skills (SKILL.md)
visualizers/ — Preview plugins
memory.md — Project memory (auto-injected into system prompt)
memory/ — Supporting memory notes
.env — Environment variables

                    .agent/

                    ├── memory.md # project memory

                    ├── memory/ # supporting notes

                    ├── .env # env variables

                    ├── agents/

                    │  └── paper-summary/

                    │    └── AGENT.yaml

                    ├── actions/

                    │  ├── fetch_abstract/

                    │  │  ├── ACTION.yaml

                    │  │  └── index.js

                    │  └── summarize/

                    │    └── ACTION.yaml

                    ├── runtimes/

                    │  └── python-runner/

                    │    └── RUNTIME.yaml

                    ├── skills/

                    │  └── system/

                    │    └── agent-authoring/

                    └── visualizers/

                        └── my-namespace/

                            └── csv-grid/

                                ├── VISUALIZER.yaml

                                └── web/index.html

Docker Containers

Persistent Containers

Each project can have a dedicated Docker environment where agents execute code, run analyses, and produce outputs.

One long-running container per project
Named: researchx-{projectId}
Auto-sleep after 3 minutes of inactivity
Status polled every 10 minutes
Real-time status via SSE event streaming

container_status

🟢

Running

jupyter/datascience-notebook

Docker Containers

Container Setup

Enable via Project Settings → Container tab
Default image: harbor.bio-it.cn:5000/project/researchx:amd64-2e5d68e
Choose from local images or enter a custom image URL
Container runs with host UID/GID to prevent mount permission issues
Workspace bind-mounted: host_path → /workspace

Project Settings · Container Running

Enable Container

Container Image

harbor.bio-it.cn:5000/project/researchx:amd64-2e5d68e

HOST_UID

1000

HOST_GID

1000

./data/agent-workspaces/<projectId> → /workspace

Lifecycle

Start Stop Retry

Docker Containers

GPU & Advanced Config

Configure GPU count, driver, and memory per container
GPU settings are persistent — saved with project config
Container status indicator shows real-time state in header
Colors: 🟢 running · 🟡 stopped · 🔵 creating · 🔴 error
Status syncs across browser tabs via SSE events

gpu_config

GPU Count 1

Driver NVIDIA

Memory 8 GB

Docker Containers

Container Fixed Mounts

Admin-configured bind mounts auto-injected into all containers
Manage at Admin → Container Mounts (/workspace/admin/container-mounts)
Each entry: Host Path + Container Path + optional Read-only
New containers pick up mounts automatically
Running containers require a restart to apply changes
Paths are validated for uniqueness and no workspace conflicts

Tip: Use read-only mounts for shared datasets to prevent accidental modification from inside containers.

container_mounts

Host Path Container Path RO

/srv/datasets /mnt/datasets ✓

/srv/shared /mnt/output —

/etc/config /etc/config ✓

Skills

Skill System & Slash Commands

Skills live in .agent/skills/<ns>/<name>
Defined via SKILL.md frontmatter with parameters
Invoke in chat: /skill:<name> <args>
Admin manages Git-based skill repositories
Suggestions appear when typing / in the composer

                    // Slash command example

                    User types: /task:code_execution

                                        lung cancer biomarkers

                    // Equivalent to sending a structured

                    // prompt with skill parameters

                    → Agent ticket created

                    → Runs through pipeline

                    → Artifacts appear in chat

Settings

Project Settings & Memory

Open via Project Settings button in header
Project Memory — edit .agent/memory.md
Supporting notes in .agent/memory/ directory
Memory injected into the AI system prompt for every conversation
Env Variables — stored in .agent/.env
Members — invite users, set roles (owner/member)

                    # .agent/memory.md

                    ## Overview

                    - Cancer biomarker discovery

                      project focused on NSCLC.

                    ## Durable Facts

                    - Prefer concise bullet-point

                      answers.

                    ## Known Gotchas

                    - Container must not run

                      as root.

                    # .agent/.env

                    NCBI_API_KEY=your_key

                    CUSTOM_DB_URL=postgres://...

Advanced

Cross-Project Features

Cross-Project Import — bring skills, agents, visualizers from other projects
Export agents as archives for reuse
Share assets across your team's project ecosystem
Conversation export to Markdown for documentation
Assistant messages can be saved to workspace for Agent reuse

Import from Project

Import installed assets from another project.

✕

Source Project

Oncology Research▾

Search installed skills, agents, actions, or visualizers

◼ code_execution

same-name match

Reusable analysis agent with local runtime support.

Import

◼ pubmed_search

skill

Search biomedical papers and return normalized citations.

Import

2 items available

Cancel Import Selected

Advanced

Web Search & Page Agent

Web Search

Powered by Tavily API with admin configuration
Users set personal API keys in Profile
Built-in web_search tool in chat

Page Agent

Floating draggable panel at bottom-right corner
Use natural language to manipulate page elements
Debug mode for visual highlights of AI operations

web_search_result

🔍 "lung cancer biomarkers 2026"

1. Novel protein biomarkers in NSCLC... [PubMed]

2. Liquid biopsy approaches for early... [Nature]

3. AI-driven biomarker discovery using... [arXiv]

Administration

Admin Panel Overview

Access at /workspace/admin — admin-only area
User Management — create accounts, edit roles, deactivate, reset passwords
System Settings — toggle public registration, web search config
Skill Repositories — manage Git-based skill sources with auto-sync
Asset Repositories — manage agent, action, and runtime sources
Token Usage — per-project, per-user consumption reporting

admin_navigation

Overview — platform stats dashboard

Users — accounts, roles, lock/unlock

Models — providers, API keys, defaults

Repositories — skills & assets

Container Mounts — shared host volumes

Administration

Models, Web Search & Monitoring

Add model providers: OpenAI, Anthropic, Google, custom OpenAI-compatible
Configure per-model parameters: context window, temperature, max tokens
Set a default model for all new conversations
Web search powered by Tavily — configure API key, rate limits, timeout
Token usage reporting — filter by project, user, date range

                    // Model configuration

                    provider: openai

                    model_id: gpt-4o

                    context_window: 128000

                    default: true

                    // Web search settings

                    provider: tavily

                    max_results: 5

                    allow_user_keys: true

Conversations

Conversation Management & Branching

Branch from any message — explore alternate paths without losing original thread
Pin important conversations for quick access in sidebar
Stop / Abort — cancel active chat runs and in-progress agent tickets
Export to Markdown for external documentation and sharing
Conversation kinds: user, agent, prompt_action, scheduled

Tip: Use branching to test different prompts on the same context — switch between branches to compare results side by side.

conversations

📌 Biomarker Analysis

Pinned · 12 messages · 2 branches

Literature Review

Active · 28 messages

Data Exploration

Archived · 45 messages

Integration

MCP Server Integration

Connect external AI tools via the Model Context Protocol — expose tools, resources, and prompts to your project chats.

Add MCP servers per project with SSE or stdio transport
Configure authentication: none, bearer, basic, custom headers
Toggle expose tools / resources / prompts to chat independently
Set allowed_tools allowlist and confirmation_tools for approval flow
Per-server timeout and cache TTL settings

                    # MCP Server config

                    name: pubmed-mcp

                    transport: sse

                    url: http://localhost:3001/sse

                    auth:

                      type: bearer

                      token: sk-••••

                    expose_tools_to_chat: true

                    timeout_ms: 30000

Automation

Scheduled Tasks & Automation

Create cron-like scheduled prompts that run automatically
Set timezone and model per scheduled task
Toggle tasks active / paused without deletion
"Run Now" for manual trigger — view run history
Each run creates a scheduled-kind conversation

Tip: Use scheduled tasks for recurring literature scans, data pipeline checks, or periodic report generation.

Scheduled Tasks

Automate recurring prompts with cron schedules.

TZ: Asia/Shanghai

All Active Paused

New Task

Weekly Literature Scan

active

Cron: 0 9 * * MON

Model: GPT-5.4

Next Run: Mon 09:00

Last Run: success · 2h ago

Run Now Pause

Recent Runs

2026-04-22 09:00 · success · 38s

2026-04-15 09:00 · success · 41s

2026-04-08 09:00 · success · 36s

Safety

Tool Permissions & Change Tracking

When Auto Mode is OFF, tool calls generate permission requests
Diff preview — see proposed file changes before approving
Status flow: pending → approved/denied → executed/expired
Change records track all file modifications made by agent tools
Revert any individual change with one click — undo mistakes instantly

permission_request

🔧 write_file

path: /workspace/analysis.py

+23 lines / -5 lines modified

Approve Deny View Diff

Agent System

Agent Output & Advanced Config

Deep dive into output management, ACTION.yaml entry config, and container execution modes.

Outputs at agents-output/<date>/<agent>-<ticket>/
result.outputs in AGENT.yaml — WDL-style type/value declarations
entry.args — WDL-style command-line argument declarations
entry.env — environment variable injection, entry.stdin: json | none
Ephemeral container — custom image → docker run --rm per invocation

                    # ACTION.yaml entry config

                    entry:

                      path: ./analyze.py

                      args:

                        - name: query

                          type: string

                      env:

                        API_KEY: ${input.key}

                      stdin: json

                    # Agent result.outputs

                    result:

                      outputs:

                        report:

                          type: file

                          value: ${steps.gen.output.path}

AI Chat

Context Compaction & Token Management

Context ring indicator shows real-time token usage vs model limit
Automatic compaction triggers when approaching the preemptive threshold
Per-model settings: keep_recent_tokens, reserve_tokens, threshold ratio
Env overrides: COMPACTION_KEEP_RECENT_TOKENS, COMPACTION_RESERVE_TOKENS
Compaction preserves latest context while summarizing older messages

                    // Per-model compaction config

                    compaction_enabled: true

                    keep_recent_tokens: 20000

                    reserve_tokens: 16384

                    preemptive_threshold: 0.75

                    // Compaction flow

                    1. Token count → 75% of limit

                    2. Summarize older messages

                    3. Keep last 20K tokens intact

                    4. Reserve 16K for new replies

Desktop

Electron Desktop App

ResearchX can run as a native desktop application wrapping the Next.js web interface with Electron.

pnpm electron:dev — start Next.js, then open Electron shell
pnpm electron:pack — build unpacked directory for testing
pnpm electron:dist — installable packages: DMG, NSIS, AppImage
Code signing disabled by default — set RESEARCHX_ELECTRON_SIGN=true
Desktop data paths under userData/data/ — separate from web deployment

desktop_workflow

1 Run pnpm electron:dev

↓

2 Next.js starts → splash screen

↓

3 Health check passes → main window

↓

4 Package with electron:dist

Best Practices

Tips for Success

🎯

Clear Instructions

Write specific memory notes in .agent/memory.md for better AI responses

🔒

Use Auto Mode Wisely

Start manual, switch to auto when agents are trusted

📂

Organize Files

Keep project files organized by workspace folders

🐳

Container Hygiene

Disable containers when idle — auto-sleep after 3 minutes; use fixed mounts for shared data

🔧

Dev Mode

Enable for agent authoring — quick-fix broken agents in chat

🌐

Leverage Skills

Use slash commands to chain powerful workflows

🔀

Branch Conversations

Use branching to explore alternate approaches without losing your original thread

⏰

Automate Repetitively

Set up scheduled tasks for recurring scans, reports, and data pipeline checks

🛡️

Review Changes

Keep Auto Mode off for new agents — review diffs and use revert for safety

Questions? Visit /docs for full documentation.

Happy Researching!