A localized academic productivity assistant for university and research workflows. EZscholar unifies task planning, remote compute, focus management, report generation, literature analysis, and guided learning in one console.

Language / 语言 English (Default) · 简体中文

---

Why This Project

Typical tools fragment research workflows:

• Deadline reminders are time-based only, without task complexity awareness.
• Switching between local and remote GPU environments is expensive.
• Deep work is interrupted easily, and context is lost after breaks.
• Data processing, charting, and report export pipelines are long and error-prone.
• Long-paper retrieval often loses figure/table context across sources.
• Direct answers can weaken reasoning practice in learning scenarios.

EZscholar aims to unify these high-frequency pain points into one workflow.

---

Current Features

The repository now ships:

• frontend console (React + TypeScript + Vite)
• backend local Docs Maker bridge service (Express + Mammoth + Pandoc bridge)

Implemented capabilities:

• Routes and pages:
  • /: AI Chat (default home)
  • /overview: Overview dashboard (recent visits, activity timeline, module cards)
  • /activity: Global activity feed
  • /settings: Theme, provider, and workspace settings
  • /modules/*: Module detail pages (Deadline / Remote / Flow / Output / Research / Socratic)
  • /modules/slides-studio: Standalone Slides Studio (Markdown -> PPTX)
• Agentic AI chat:
  • OpenAI-compatible Chat Completions integration
  • Function-calling tools:
    • schedule_reminder / list_reminders / cancel_reminder
    • parse_word_draft / render_academic_report / generate_presentation_slides (async job)
  • In-chat tool action cards, plus local notifications and toast delivery
• Module 2 Docs Maker:
  • Upload .docx draft to workspace
  • Parse Word draft to Markdown with extracted image placeholders
  • Render polished Markdown to pdf/docx (typst first, pandoc fallback for PDF)
  • Standalone Slides Studio with async PPTX jobs (Marp CLI)
  • Markdown sources for PPTX: upload .md, existing markdown path, or external webhook prompt
  • Default output target: workspace/docs-maker/output/report-<timestamp>.pdf
  • Default PPTX output target: workspace/docs-maker/slides/output/slides-<timestamp>.pptx
  • Download stream endpoint and workspace file persistence
• Command palette: Ctrl/Cmd + K for navigation and simulated actions
• Theme system: dark/light mode with improved light-mode readability
• Workspace state persistence:
  • Config and history are stored under <workspace>/.ezscholar/
  • config.json (provider/url/key/theme/workspace), history/events.jsonl, state/module-snapshots.json
  • Module 1 reminders and module activities can be restored after refresh

Security note: API keys are currently stored in plaintext in <workspace>/.ezscholar/config.json. Do not commit this directory.

---

UI Preview

AI Chat Page (/, Dark/Light)

Dark	Light

Deadline Engine (Real Implementation, Dark/Light)

Dark	Light

Module 2 Docs Maker E2E (Chat-Driven)

Click to view rendered PDF

---

Quick Start

1. Install Dependencies

cd backend
npm install

cd frontend
npm install

2. Start Local Docs Maker Backend

cd backend
npm run dev

Default backend URL:

• http://127.0.0.1:8787

3. (Optional) Configure Local Environment Variables

Create/update frontend/.env.local:

VITE_LOCAL_API_BASE_URL=http://127.0.0.1:8045/v1
VITE_LOCAL_API_KEY=
VITE_LOCAL_MODEL=gemini-3-flash

VITE_QWEN_API_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VITE_QWEN_API_KEY=
VITE_QWEN_MODEL=qwen-plus

Note: .env.local is git-ignored. Do not commit real API keys into source code or README files.

4. Start Frontend Development Server

cd frontend
npm run dev

Default local URL (check terminal output first):

• http://127.0.0.1:5173

/api/docs-maker/* is proxied by Vite to the backend service in development.

5. Build and Preview Production

cd frontend
npm run build
npm run preview -- --host 127.0.0.1 --port 4173

Preview URL:

• http://127.0.0.1:4173

---

Test Commands

cd backend
npm test
npm run build

cd ../frontend
npm run lint
npm run test
npm run test:e2e

---

Project Structure

UniHelperCode/
├── README.md
├── README.zh-CN.md
├── docs/images/                 # README screenshot assets
├── backend/
│   ├── src/routes/              # docs-maker routes
│   ├── src/services/            # path guard / parser / renderer / slides jobs
│   └── src/types.ts             # zod schemas + response types
└── frontend/
    ├── src/
    │   ├── app/                 # Router, navigation, QueryClient
    │   ├── layouts/             # AppShell / Sidebar / TopHeader
    │   ├── pages/               # Chat / Overview / Activity / Settings / ModuleDetail
    │   ├── features/            # dashboard / settings / modules / command-palette
    │   ├── services/            # api mock + llm + agent tools + docs-maker client + notifier
    │   ├── stores/              # UI / LLM / Chat / Notifier / Workspace
    │   └── styles/              # tokens + component styles
    ├── e2e/                     # Playwright tests
    └── vitest.config.ts

---

Typical Usage Flow

1. Start the app and open AI Chat (/) by default.
2. Configure your active LLM provider in /settings.
3. Try prompts like "Remind me in 30 minutes to ..." to validate tool calling.
4. Open /modules/output-generator to process .docx and render pdf/docx.
5. Open /modules/slides-studio to create async PPTX jobs from markdown/webhook input.
6. Use Ctrl/Cmd + K for fast navigation and action simulation.

---

Roadmap

• Integrate real backend APIs (while keeping mock fallback)
• Add module-level real-time status subscriptions (WebSocket/SSE)
• Persist reminders and chat history
• Expand external slide providers (Canva/NotebookLM adapters on top of generic webhook)
• Expand bilingual UX across the product

---

License

Licensed under MIT License.