@next-open-ai/easyai

EasyAI

EasyAI — a cross-platform, local-first AI workspace for digital employees.

Languages: 中文 (zh-CN) · English

本项目 README 采用「根 README 为索引 + 语言分档」结构（语言分档见上）。

EasyAI is a desktop agent workspace whose agents ("digital employees") can chat, run projects, use Skills, query knowledge bases / MCP connectors / web search, and be driven from external channels (Telegram / Feishu / a remote relay) through a local gateway. Every heavy piece of orchestration lives in a server-side state machine, so the desktop UI, IM channels and future remote terminals all share one consistent view of sessions, runs, approvals and project scheduling.

The repository deliberately keeps the Electron shell thin:

Electron shell  →  local Fastify API  →  agent-core (pi-agent-core / pi-ai)  →  providers
Vue renderer ────── HTTP / SSE ────────┘
channel gateway ─── HTTP / SSE ─────────┘   (Telegram / Feishu / remote relay)

Highlights

Capability	Description
Digital employees	Responsibility/authorization units with configurable model, Skills, runtime prefs and permission tiers
Skills (progressive disclosure)	Authorize → SKILL.md on demand → resources/scripts within an isolated run workspace
Project orchestration	Goal → Plan vN (DAG) → confirm → Run; follow-ups apply a ChangeSet (stale cascade); roster changes bump Plan and keep reusable completed nodes
Resumable approvals	Tool approval parks a run (waiting-approval); deciding it re-runs the same turn automatically
Session rolling memory	Per-session memory.summary + watermark; auto-summarize over budget, flush on leave; transcript stays source of truth
Dual project workspaces	Process files stay in per-run agent workspaces; final deliverables use publish_to_project into the shared project tree
Knowledge / MCP / Web search	Local LanceDB + cloud KBs, MCP connectors (http/sse/stdio), multi-provider search with masking
Channels & remote office	Gateway child process: Telegram & Feishu adapters, personal allowlist, remote relay device link (WS outbound) for terminals
Local-first storage	One durable domain store owned by the API process; secrets stay encrypted in the main process (safeStorage) and are only released over fork IPC
Desktop "Remote & Channels" portal	P1 view to manage Telegram/Feishu credentials, allowlist, default employee, gateway status/restart

Repository layout (pnpm monorepo)

Path	Role
apps/desktop	Electron main (thin), IPC, sql.js secret/asset store, forks api + gateway
apps/renderer	Browser-only Vue 3 UI (Vite + Tailwind); talks HTTP/SSE + IPC
apps/api	Localhost Fastify service; hosts the orchestrator (/api/orch/**)
apps/gateway	Channel-gateway child process (Telegram/Feishu/relay adapters, allowlist)
packages/contracts	Shared Zod contract source of truth
packages/agent-core	The only layer that calls the Vercel AI SDK
packages/tools	Tool contracts + risk labels
packages/orchestrator	Server-side session/project state machines, storage service, resumable runs
packages/channel	Transport-agnostic channel protocol (UnifiedMessage/IChannel/registry/StreamSink)
packages/storage, packages/ui-kit	Reserved placeholders

See docs/design/architecture.md for the full current architecture and module responsibilities.

Quick start

Requirements: Node.js ≥ 22, pnpm ≥ 10 (pinned via packageManager).

pnpm install
pnpm dev        # desktop (builds workspace packages, starts Vite + Electron)
pnpm typecheck
pnpm build
pnpm package    # electron-builder installers

For the standalone browser runtime:

pnpm build
pnpm web:start  # start the local web launcher

For the packaged CLI / npm payload:

easyai doctor
easyai init
easyai start

For Docker build validation:

pnpm build
docker build -t easyai:local .

No model credentials are stored or used until you configure a provider in Settings → Models. Headless/CI smoke scripts are also provided (see scripts/*-smoke.mjs, docs/runtime-modes.md, and docs/deployment.md).

Runtime modes

EasyAI currently supports four runtime shapes with different parity levels:

Runtime	Entry	Support level	Notes
Desktop	pnpm dev / packaged app	Full	Reference experience: Electron IPC, safeStorage, native file actions, desktop-managed gateway
Web launcher	pnpm build && pnpm web:start	Supported	Runs the built renderer from the local Fastify API; no Electron-only capabilities
npm / CLI	easyai start	Supported	Same runtime shape as the web launcher
Docker	root Dockerfile	Build-supported	Image build is validated, but runtime parity is still partial

Current web/npm degradations versus desktop:

• no Electron IPC bridge or native file picker/reveal flows
• no safeStorage; server settings are persisted under EASYAI_DATA_DIR
• asset/project file actions fall back to browser open/download behavior
• channel/gateway credentials are handled by server-side files instead of the desktop keyring bridge

Current Docker caveat:

• the image packages the same standalone web runtime payload
• however apps/api still binds 127.0.0.1, so published container ports should not yet be documented as fully equivalent to the local launcher

See docs/runtime-modes.md for the full parity matrix and docs/deployment.md for deployment notes.

Release

Push a SemVer tag such as v0.1.0; the release workflow first re-validates the web runtime + Docker build on Ubuntu, then packages and publishes two installers:

Platform	Architecture	Installer
macOS	Apple Silicon (arm64)	.dmg
Windows	x64	NSIS .exe

Intel macOS and Linux packaging stay disabled in CI for now (see the workflow comments in .github/workflows/release.yml).

Documentation

Language	Index
Runtime / deployment	runtime modes · deployment notes
中文	docs/design/architecture.md · docs/design README · 网关设计 (M0) / M1 / M2
English	See the feature/milestone tables inside the design docs above (deep design notes are currently maintained in Chinese).

Status of the channel-gateway milestones

Milestone	Result
M0 Orchestration layer	✅ sessions/projects state machines, storage service, resumable approvals, /api/orch REST+SSE
M1 Gateway + Telegram	✅ @easyai/channel, apps/gateway, Telegram adapter + allowlist, stub acceptance ALL PASS
M2 Remote-office portal, Feishu, relay	✅ P1 portal & credential channel (IPC + safeStorage), P2 Feishu adapter, P3 minimal remote relay — stub acceptances ALL PASS

License

The project does not yet declare a public license file — treat it as internal until a LICENSE is added by the owner.