ouyangbo/EvoScientist-WebUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial

Browse Source
This commit is contained in:
Xi Zhang
2026-06-10 22:42:16 +01:00
parent 4e7901018f
commit a874e0681b
2 changed files with 243 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+115
View File
@@ -0,0 +1,115 @@
# Contributing to EvoScientist WebUI
We appreciate your interest and the time you spend helping improve the EvoScientist WebUI. Please read the following guidelines before contributing.
## How you can contribute
- **Report bugs and request features:** open an issue describing the problem, steps to reproduce, and your environment (Node version, backend version).
- **Propose design changes:** use issues to outline the problem, alternatives, and trade-offs before implementing.
- **Contribute code or docs:** submit PRs that address an open issue, with a clear rationale.
## The zero-touch-backend principle
> [!IMPORTANT]
> The WebUI is a **runtime client only**. It must work against an unmodified EvoScientist backend — it talks to a running deployment over the LangGraph SDK and thin same-origin `/api/` routes, and never requires changes to the EvoScientist repo. Keep all new features within this constraint (the one sanctioned exception, the `webui` launch mode, already lives in EvoScientist).
## Prerequisites
- **Node.js 20+**.
- A running **EvoScientist backend** (the LangGraph deployment). From your EvoScientist install:
```bash
EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174
```
Keep it running in its own terminal.
## Development setup
1. **Fork and clone** the repository:
```bash
git clone https://github.com/<your-username>/EvoScientist-WebUI.git
cd EvoScientist-WebUI
```
2. **Install dependencies** (package manager is **npm**):
```bash
npm install
```
3. **Start the dev server:**
```bash
npm run dev
```
Open <http://localhost:4716>. In the configuration dialog, enter your **Deployment URL** (default `http://127.0.0.1:6174`) and click **Save**.
> You need two things running: the EvoScientist backend (`EvoSci deploy`, port `6174`) and this UI (`npm run dev`, port `4716`).
## Scripts
| Command | Description |
| ---------------------- | --------------------------------------- |
| `npm run dev` | Start the dev server on port 4716 |
| `npm run build` | Production build + assemble `dist/` |
| `npm start` | Serve the production build on port 4716 |
| `npm run start:dist` | Run the assembled standalone `dist/` |
| `npm run lint` | Lint with ESLint |
| `npm run lint:fix` | Lint and auto-fix |
| `npm run format` | Format with Prettier |
| `npm run format:check` | Check formatting (used in CI) |
## Production build
```bash
npm run build # next build + assemble standalone into dist/
npm start # serves the production build on http://localhost:4716
```
## Project structure
```txt
EvoScientist-WebUI/
bin/ # npx launcher (evoscientist-webui.mjs → dist/server.js)
scripts/ # assemble-standalone.mjs (packs dist/, strips *.map)
src/
app/
api/ # thin same-origin server routes
evosci-config/ # detect backend port
skills/ # install / list / remove skills
memory/ # read / edit global memory
workspace/ # browse / edit / download files
components/ # React components (chat, panels, dialogs)
hooks/ # useChat, useThreads, useAsyncAgents, …
page.tsx # multi-view shell (routes via nuqs)
components/ # shared UI primitives
lib/ # client + server helpers (asyncAgents, memory, …)
server/ # server-only fs helpers with path guards
providers/ # Theme / Client providers
```
## Architecture & connection contract
Three independent layers:
1. **Frontend** (Next.js standalone, port `4716`) — browser connects directly to the LangGraph backend; pure client-side chat + streaming.
2. **Next `/api/` routes** (server tool layer, same-origin) — the reason distribution is `output: "standalone"` rather than a static export.
3. **Backend** (EvoScientist's `langgraph dev`, default port `6174`) — the anchor process: runs async agents, holds state, serves the SDK.
The backend exposes graphs `EvoScientist` (main, UI-locked), `writing-agent`, `data-analysis-agent`, and the `evomemory` workers. The UI filters thread lists by `metadata.graph_id == "EvoScientist"` so worker/sub-agent threads stay hidden.
## Code style
- **TypeScript** — keep `npm run lint` (ESLint) clean and run `tsc --noEmit` before pushing.
- **Formatting** — `prettier --check .` must pass (run `npm run format` to fix).
- **Tailwind gotcha:** this project's `tailwind.config.mjs` overrides named tokens like `bg-primary`/`text-primary` to undefined LangSmith vars, so those classes render transparent. Use arbitrary values such as `bg-[var(--brand-solid)]` instead, and never apply a `/NN` opacity modifier to a `var()`-based color (it silently drops the declaration).
- Follow the existing patterns and conventions in the area you're modifying; keep changes minimal and focused.
## Submitting a pull request
1. Create a branch from `main` with a descriptive name (e.g. `fix/stream-tail`, `feat/command-palette`).
2. Make your changes, keeping commits focused. Use semantic prefixes: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`.
3. Ensure `npm run lint`, `tsc --noEmit`, and `npm run format:check` pass locally — these also run in CI.
4. Open a PR against `main` describing what changed and why. Include screenshots or screen recordings for any UI change.
5. A maintainer will review your PR. Please be responsive to feedback.
## Need help?
Open an [issue](https://github.com/EvoScientist/EvoScientist-WebUI/issues) if you have a question or run into a problem.
README.md
+128 -44
View File
@@ -1,66 +1,150 @@
# EvoScientist WebUI
# 🌐 EvoScientist WebUI
Web UI for **EvoScientist** — a self-evolving AI scientist built on DeepAgents/LangGraph.
**The desktop-level browser workspace for [EvoScientist](https://github.com/EvoScientist/EvoScientist), designed to make Vibe Research feel natural. By bringing evolving memory, research skills, multi-agent workflows, and workspace management together in one place, it helps researchers spend less time managing information and more time exploring ideas — so scientific discovery can move faster.**
The browser connects directly to a running EvoScientist deployment and gives you a
chat interface with streaming responses, tool calls, sub-agent activity, files, and tasks.
<div align="center">
## Prerequisites
<a href="https://www.npmjs.com/package/@evoscientist/webui"><img alt="npm" src="https://img.shields.io/npm/v/@evoscientist/webui?color=00BCD4&label=npm" height="28"></a>
<a href="https://github.com/EvoScientist/EvoScientist"><img alt="Powered by EvoScientist" src="https://img.shields.io/badge/powered%20by-EvoScientist-066679" height="28"></a>
<a href="https://nextjs.org/"><img alt="Next.js 16" src="https://img.shields.io/badge/Next.js-16-black" height="28"></a>
<a href="./LICENSE"><img alt="License Apache 2.0" src="https://img.shields.io/badge/license-Apache%202.0-blue" height="28"></a>
- **Node.js 20+**
- A running **EvoScientist backend** (the LangGraph deployment). From your EvoScientist
install, start it with:
</div>
```bash
EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174
```
---
Keep this running in its own terminal.
<table>
<tr>
<td align="center">
<video src="https://github.com/user-attachments/assets/b977f2d5-488a-428d-9c02-b6b27c1521f8" autoplay loop muted playsinline width="100%">
<a href="https://github.com/user-attachments/assets/b977f2d5-488a-428d-9c02-b6b27c1521f8">View WebUI demo</a>
</video>
</td>
</tr>
</table>
## Quick start (development)
> [!TIP]
> Looking for the engine behind this UI? Check out [**EvoScientist**](https://github.com/EvoScientist/EvoScientist) — the multi-agent AI scientist — and [**EvoSkills**](https://github.com/EvoScientist/EvoSkills), its ready-to-use research skill packs. This WebUI is a thin, zero-touch client: it talks to a running EvoScientist deployment over the LangGraph SDK and adds **nothing** to your backend.
## ✨ Features
- **💬 Streaming Chat** — Real-time responses with Markdown, GFM tables, code highlighting, and collapsible thinking/reasoning blocks.
- **👋 Human-in-the-Loop** — Approve / reject / edit tool calls, and answer the agent's structured questions (text + multiple-choice) inline.
- **⚡ Per-Thread Auto-Approve** — Persisted per conversation; survives view and thread switches and reloads.
- **🤖 Sub-Agent Activity** — Live step tracking for sub-agents, rendered exactly like the main agent (tool calls + paired results + tables).
- **🗂️ Workspace Browser** — Tree and by-type (Papers / Figures / Data / Code) views with preview, edit, download, and zip-all.
- **🧠 Memory Browser** — View, edit, and manage EvoScientist's global cross-session memory, with "recently updated" highlights and a nav badge.
- **🔌 Skills Marketplace** — Install, update, and uninstall the official [EvoSkills](https://github.com/EvoScientist/EvoSkills) catalog with version detection and a detail dialog.
- **📡 Agents Monitor Board** — Watch async background agents (writing / data-analysis) with real run status, live duration, and a side-chat for direct worker debugging.
- **🔁 Async Agent Communication** — Optional per-thread auto-report loops finished background results back to the main agent.
- **🪄 Compaction Summary** — When the backend compacts a long conversation, the summary is shown as a clean collapsible block instead of flashing by.
- **🩺 Connection Health & Resilience** — Health light, stale-URL one-click reconnect, and refresh-resumable streams.
- **🎨 Themed & Responsive** — Light/dark warm "paper" theme with EvoScientist cyan accent; desktop split panes and mobile drawers.
## 📖 Table of Contents
- [📦 Prerequisites](#-prerequisites)
- [⚡ Quick Start](#-quick-start)
- [🔑 Configuration](#-configuration)
- [🎨 Designed By](#-designed-by)
- [🤝 Contributing](#-contributing)
- [📚 Acknowledgments](#-acknowledgments)
- [📜 License](#-license)
## 📦 Prerequisites
- [**EvoScientist**](https://github.com/EvoScientist/EvoScientist) installed and configured (`EvoSci onboard`).
- **Node.js 20+** — the WebUI mode launches the front-end for you.
## ⚡ Quick Start
### Option A — via EvoScientist (recommended)
The WebUI ships with EvoScientist — just pick it during setup. Run the onboarding wizard and choose **WebUI** as your UI mode:
```bash
npm install
npm run dev
EvoSci onboard # select "WebUI" when asked for the UI mode
```
Open <http://localhost:4716>. In the configuration dialog, enter your **Deployment URL**
(default `http://127.0.0.1:6174`) and click **Save**. That's it — start chatting.
> You need two things running: the EvoScientist backend (`EvoSci deploy`, port 6174)
> and this UI (`npm run dev`, port 4716).
## Production build
Then launch EvoScientist as usual — it starts the backend and the WebUI together and opens your browser:
```bash
npm run build # outputs the optimized app
npm start # serves it on http://localhost:4716
EvoSci # opens http://localhost:4716
```
## Configuration
That's it — start chatting.
- **Deployment URL** — the EvoScientist LangGraph endpoint (default `http://127.0.0.1:6174`,
the `EvoSci deploy` default port). Saved in your browser's local storage.
- The UI always talks to the **EvoScientist** main agent; its sub-agents
(`writing-agent`, `data-analysis-agent`) are internal and not user-selectable.
- _(Optional, advanced)_ Set `NEXT_PUBLIC_LANGSMITH_API_KEY` if you connect to a
deployment that requires LangSmith authentication.
### Option B — standalone
## Scripts
Start the EvoScientist backend in one terminal:
| Command | Description |
| ---------------------- | --------------------------------------- |
| `npm run dev` | Start the dev server on port 4716 |
| `npm run build` | Production build |
| `npm start` | Serve the production build on port 4716 |
| `npm run lint` | Lint with ESLint |
| `npm run format` | Format with Prettier |
| `npm run format:check` | Check formatting (used in CI) |
```bash
EvoSci deploy # serves the LangGraph API at http://127.0.0.1:6174
```
## Tech stack
Then launch the WebUI in another (no install required):
Next.js 16 · React 19 · TypeScript · Tailwind CSS · `@langchain/langgraph-sdk`.
```bash
npx @evoscientist/webui@latest # opens http://localhost:4716
npx @evoscientist/webui@latest --port 5000 # or pick a custom front-end port
```
## License
Open the URL, confirm the prefilled **Deployment URL** (auto-detected, default `http://127.0.0.1:6174`), click **Save**, and start chatting.
Apache-2.0 — see [LICENSE](LICENSE).
<p align="right"><a href="#top">🔝Back to top</a></p>
## 🔑 Configuration
- **Deployment URL** — the EvoScientist LangGraph endpoint (default `http://127.0.0.1:6174`, the `EvoSci deploy` default port). Saved in your browser's local storage.
- The UI always talks to the **EvoScientist** main agent; its sub-agents (`writing-agent`, `data-analysis-agent`) are internal and not user-selectable.
- _(Optional, advanced)_ Set `NEXT_PUBLIC_LANGSMITH_API_KEY` if you connect to a deployment that requires LangSmith authentication.
> [!TIP]
> If the backend changes ports, the health light detects the dead connection and offers a one-click **Reconnect** to the newly detected port.
<p align="right"><a href="#top">🔝Back to top</a></p>
## 🎨 Designed By
<table>
<tbody>
<tr>
<td align="center">
<a href="https://x-izhang.github.io/">
<img src="https://x-izhang.github.io/author/xi-zhang/avatar_hu13660783057866068725.jpg"
width="100" height="100"
style="object-fit: cover; border-radius: 20%;" alt="Xi Zhang"/>
<br />
<sub><b>Xi Zhang</b></sub>
</a>
</td>
</tr>
</tbody>
</table>
<p align="right"><a href="#top">🔝Back to top</a></p>
## 🤝 Contributing
We welcome contributions! See the [Contributing Guidelines](./CONTRIBUTING.md) for development setup, project structure, the zero-touch-backend principle, scripts, and the release flow.
Every contribution brings us one step closer to a future where AI accelerates scientific breakthroughs for all of humanity.
<p align="right"><a href="#top">🔝Back to top</a></p>
## 📚 Acknowledgments
This project builds upon the following outstanding open-source work:
- [**LangGraph**](https://github.com/langchain-ai/langgraph) — A low-level orchestration framework for building, managing, and deploying long-running, stateful agents.
- [**deep-agents-ui**](https://github.com/langchain-ai/deep-agents-ui) — The LangChain reference UI for deep agents, which this project builds upon.
We thank the authors for their valuable contributions to the open-source community.
<p align="right"><a href="#top">🔝Back to top</a></p>
## 📜 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](./LICENSE) file for details.
<p align="right"><a href="#top">🔝Back to top</a></p>