From 18a6996c9753a2f4bf51581e157397819be2ae7e Mon Sep 17 00:00:00 2001 From: Jiayuan Zhang Date: Sun, 15 Feb 2026 03:23:54 +0800 Subject: [PATCH] docs: slim down README and split into topic-specific docs Add local full-stack development section (pnpm dev:local) and move detailed content (credentials, CLI, skills/tools, time injection, development guide) into separate docs/ files. Co-Authored-By: Claude Opus 4.6 --- README.md | 242 +++++++-------------------------------- docs/cli.md | 30 +++++ docs/credentials.md | 39 +++++++ docs/development.md | 82 +++++++++++++ docs/skills-and-tools.md | 19 +++ docs/time-injection.md | 36 ++++++ 6 files changed, 250 insertions(+), 198 deletions(-) create mode 100644 docs/cli.md create mode 100644 docs/credentials.md create mode 100644 docs/development.md create mode 100644 docs/skills-and-tools.md create mode 100644 docs/time-injection.md diff --git a/README.md b/README.md index 9ff98045..4b43eb06 100644 --- a/README.md +++ b/README.md @@ -9,31 +9,27 @@ See [Memo](./docs/memo.md) for product vision, architecture, and roadmap. ## Project Structure ``` -src/ -├── agent/ # Core agent module -│ ├── context-window/ # Token-aware context management -│ ├── profile/ # Agent profile management -│ ├── session/ # Session persistence with compaction -│ ├── skills/ # Modular skill system -│ └── tools/ # Agent tools -│ └── web/ # Web fetch and search tools -├── gateway/ # WebSocket gateway for remote access -├── hub/ # Agent coordination hub -└── shared/ # Shared types - apps/ -├── desktop/ # Electron desktop app (recommended) -└── web/ # Next.js web application +├── cli/ # Command-line interface +├── desktop/ # Electron desktop app (recommended) +├── gateway/ # NestJS WebSocket gateway +├── server/ # NestJS REST API server +├── web/ # Next.js web app +└── mobile/ # React Native mobile app packages/ -├── sdk/ # Gateway client SDK -├── store/ # Zustand state management -└── ui/ # Shared UI components +├── core/ # Agent engine, hub, channels +├── sdk/ # Gateway client SDK +├── ui/ # Shared UI components (Shadcn/Tailwind v4) +├── store/ # Zustand state management +├── hooks/ # React hooks +├── types/ # Shared TypeScript types +└── utils/ # Utility functions -skills/ # Bundled skills (commit, code-review) +skills/ # Bundled agent skills ``` -## Getting Started +## Quick Start ```bash pnpm install @@ -42,149 +38,38 @@ pnpm install ### Development ```bash -# Desktop app (recommended for local development) -pnpm dev - -# Web app (for browser-based access) -pnpm dev:web # Start Web app on :3000 - -# Gateway (for remote/mobile clients) -pnpm dev:gateway # Start Gateway on :3000 -pnpm dev:all # Start both Gateway and Web app +pnpm dev # Desktop app (standalone, no Gateway needed) +pnpm dev:gateway # Gateway only +pnpm dev:web # Web app only +pnpm dev:all # Gateway + Web ``` -The Desktop app runs a standalone Hub with embedded Agent Engine - no Gateway required for local use. +### Local Full-Stack Development -### Environment Configuration +`pnpm dev:local` starts the entire stack locally (Gateway + Desktop + Web) with isolated data directories, useful for end-to-end development and testing. -**Desktop** (`apps/desktop/.env.*`): +**Setup:** -| Variable | Description | -|----------|-------------| -| `MAIN_VITE_GATEWAY_URL` | WebSocket Gateway URL for remote device pairing | -| `MAIN_VITE_WEB_URL` | Web app URL for OAuth login redirect | +1. Copy `.env.example` to `.env` at the repo root +2. Fill in `TELEGRAM_BOT_TOKEN` (get from [@BotFather](https://t.me/BotFather)) +3. Run `pnpm dev:local` -**Web** (`apps/web/next.config.ts`): +**What it starts:** -| Variable | Description | -|----------|-------------| -| `API_URL` | Backend API URL (default: `https://api-dev.copilothub.ai`) | +| Service | Address | Notes | +|---------|---------|-------| +| Gateway | `http://localhost:4000` | Telegram long-polling mode | +| Web | `http://localhost:3000` | OAuth login flow | +| Desktop | — | Connects to local Gateway + Web | -**Build for different environments:** +**Data isolation:** All data goes to `~/.super-multica-dev` and `~/Documents/Multica-dev`, separate from production `~/.super-multica`. + +**Related commands:** ```bash -# Desktop -pnpm --filter @multica/desktop build # Production (.env.production) -pnpm --filter @multica/desktop build:staging # Staging (.env.staging) - -# Web (Vercel) -# Set API_URL in Vercel Dashboard → Settings → Environment Variables +pnpm dev:local:archive # Archive dev data and start fresh ``` -See `apps/desktop/.env.example` and `apps/web/.env.example` for details. - -### Monorepo Development - -| Command | Purpose | -|---------|---------| -| `pnpm dev` | Full dev mode — watches `core`, `types`, `utils` packages | -| `pnpm dev:desktop` | Desktop only — skip package watching | - -**When modifying packages:** - -1. Edit code in `packages/core`, `packages/types`, or `packages/utils` -2. Terminal shows `[core] ESM ⚡️ Build success` (~100ms) -3. Restart Desktop to apply changes (Ctrl+C, then `pnpm dev`) - -> **Why restart?** Electron main process does not support hot reload — this is an Electron limitation, not ours. - -### Credentials - -```bash -multica credentials init -``` - -Creates: -- `~/.super-multica/credentials.json5` — LLM providers + tools -- `~/.super-multica/skills.env.json5` — skill/plugin API keys - -Example `credentials.json5`: - -```json5 -{ - version: 1, - llm: { - provider: "openai", - providers: { - openai: { apiKey: "sk-xxx", model: "gpt-4o" } - } - }, - tools: { - brave: { apiKey: "brv-..." } - } -} -``` - -### LLM Providers - -**OAuth Providers** (external CLI login): -- `claude-code` — requires `claude login` -- `openai-codex` — requires `codex login` - -**API Key Providers** (configure in `credentials.json5`): -- `anthropic`, `openai`, `kimi-coding`, `google`, `groq`, `mistral`, `xai`, `openrouter` - -Check status: `/provider` in interactive mode - -## CLI - -```bash -multica # Interactive mode -multica run "prompt" # Single prompt -multica chat --profile my-agent # Use profile -multica --session abc123 # Continue session -multica session list # List sessions -multica profile list # List profiles -multica skills list # List skills -multica help # Show help -``` - -Short alias: `mu` - -## Sessions - -Sessions persist to `~/.super-multica/sessions//` with JSONL message history and JSON metadata. Context windows are automatically managed with token-aware compaction. - -## Profiles - -Profiles define agent identity, personality, and memory in `~/.super-multica/agent-profiles//`. - -```bash -multica profile new my-agent # Create profile -multica profile list # List all -multica profile edit my-agent # Open in file manager -``` - -Profile files: `soul.md`, `user.md`, `workspace.md`, `memory.md`, `memory/*.md` - -## Skills - -Skills extend agent functionality via `SKILL.md` files. See [Skills Documentation](./src/agent/skills/README.md). - -```bash -multica skills list # List skills -multica skills add owner/repo # Install from GitHub -multica skills status # Check status -``` - -Built-in: `commit`, `code-review`, `skill-creator` - -## Tools - -Available tools: `read`, `write`, `edit`, `glob`, `exec`, `process`, `web_fetch`, `web_search`, `memory_search`, `sessions_spawn` - -See [Tools Documentation](./src/agent/tools/README.md) for details. - ## Architecture ``` @@ -202,52 +87,13 @@ Web/Mobile Clients - **Gateway**: WebSocket server for remote clients - **Hub**: Agent lifecycle and event distribution -## Time +## Documentation -Super Multica now uses **message-level timestamp injection** for time awareness. -Instead of placing dynamic time text in the system prompt, user turns are stamped at runtime. - -```mermaid -flowchart TD - A[Incoming turn] --> B{Entry point} - B -->|Desktop/Gateway/Cron/Subagent| C[AsyncAgent.write] - B -->|Heartbeat poll| D[AsyncAgent.write injectTimestamp=false] - C --> E{Already stamped or has 'Current time:'?} - E -->|Yes| F[Keep original message] - E -->|No| G[Prefix: [DOW YYYY-MM-DD HH:mm TZ]] - D --> H[Keep original heartbeat prompt] - F --> I[Agent.run] - G --> I - H --> I - I --> J[LLM receives final turn text] -``` - -### Injection Matrix - -| Path | Runtime call | Timestamp injected? | Notes | -| --- | --- | --- | --- | -| Desktop direct chat | `agent.write(content)` | Yes | Default behavior | -| Gateway/remote chat | `agent.write(content)` | Yes | Same entry path as desktop | -| `sessions_spawn` child task | `childAgent.write(task)` | Yes | Child turn gets current time context | -| Cron `agent-turn` payload | `agent.write(cronMessage)` | Yes (guarded) | Skips if message already carries `Current time:` | -| Heartbeat runner | `agent.write(prompt, { injectTimestamp: false })` | No | Prevents heartbeat prompt matching from breaking | -| Internal orchestration | `writeInternal(...)` | No | Uses separate internal run path | - -### Why this design - -- Keeps system prompt cache-stable (no per-turn date churn in system prompt text) -- Gives the model an explicit "now" reference on each user turn -- Uses guardrails to avoid double-stamping and heartbeat regressions - -## Scripts - -```bash -pnpm dev # Desktop app (recommended) -pnpm dev:gateway # Gateway only -pnpm dev:web # Web app only -pnpm dev:all # Gateway + Web - -pnpm build # Production build -pnpm typecheck # Type check -pnpm test # Run tests -``` +| Topic | Link | +|-------|------| +| Development guide | [docs/development.md](./docs/development.md) | +| Credentials & LLM providers | [docs/credentials.md](./docs/credentials.md) | +| CLI usage | [docs/cli.md](./docs/cli.md) | +| Skills & tools | [docs/skills-and-tools.md](./docs/skills-and-tools.md) | +| Time injection design | [docs/time-injection.md](./docs/time-injection.md) | +| Package management | [docs/package-management.md](./docs/package-management.md) | diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 00000000..ef4cdb33 --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,30 @@ +# CLI + +```bash +multica # Interactive mode +multica run "prompt" # Single prompt +multica chat --profile my-agent # Use profile +multica --session abc123 # Continue session +multica session list # List sessions +multica profile list # List profiles +multica skills list # List skills +multica help # Show help +``` + +Short alias: `mu` + +## Sessions + +Sessions persist to `~/.super-multica/sessions//` with JSONL message history and JSON metadata. Context windows are automatically managed with token-aware compaction. + +## Profiles + +Profiles define agent identity, personality, and memory in `~/.super-multica/agent-profiles//`. + +```bash +multica profile new my-agent # Create profile +multica profile list # List all +multica profile edit my-agent # Open in file manager +``` + +Profile files: `soul.md`, `user.md`, `workspace.md`, `memory.md`, `memory/*.md` diff --git a/docs/credentials.md b/docs/credentials.md new file mode 100644 index 00000000..558d499f --- /dev/null +++ b/docs/credentials.md @@ -0,0 +1,39 @@ +# Credentials & LLM Providers + +## Setup + +```bash +multica credentials init +``` + +Creates: +- `~/.super-multica/credentials.json5` — LLM providers + tools +- `~/.super-multica/skills.env.json5` — skill/plugin API keys + +Example `credentials.json5`: + +```json5 +{ + version: 1, + llm: { + provider: "openai", + providers: { + openai: { apiKey: "sk-xxx", model: "gpt-4o" } + } + }, + tools: { + brave: { apiKey: "brv-..." } + } +} +``` + +## LLM Providers + +**OAuth Providers** (external CLI login): +- `claude-code` — requires `claude login` +- `openai-codex` — requires `codex login` + +**API Key Providers** (configure in `credentials.json5`): +- `anthropic`, `openai`, `kimi-coding`, `google`, `groq`, `mistral`, `xai`, `openrouter` + +Check status: `/provider` in interactive mode diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 00000000..cd0144bc --- /dev/null +++ b/docs/development.md @@ -0,0 +1,82 @@ +# Development Guide + +## Dev Commands + +```bash +pnpm dev # Desktop app (recommended) +pnpm dev:desktop # Same as above +pnpm dev:gateway # Gateway only +pnpm dev:web # Web app only +pnpm dev:all # Gateway + Web + +pnpm build # Production build (turbo-orchestrated) +pnpm typecheck # Type check all packages +pnpm test # Run tests +pnpm test:watch # Watch mode +pnpm test:coverage # With v8 coverage +``` + +## Local Full-Stack Development + +`pnpm dev:local` starts Gateway + Desktop + Web together with isolated data directories. + +**Setup:** + +1. Copy `.env.example` to `.env` at the repo root +2. Fill in `TELEGRAM_BOT_TOKEN` (get from [@BotFather](https://t.me/BotFather)) +3. Run `pnpm dev:local` + +| Service | Address | Notes | +|---------|---------|-------| +| Gateway | `http://localhost:4000` | Telegram long-polling mode | +| Web | `http://localhost:3000` | OAuth login flow | +| Desktop | — | Connects to local Gateway + Web | + +Data is stored in `~/.super-multica-dev` and `~/Documents/Multica-dev`, isolated from production. + +```bash +pnpm dev:local:archive # Archive dev data and start fresh +``` + +## Environment Configuration + +**Desktop** (`apps/desktop/.env.*`): + +| Variable | Description | +|----------|-------------| +| `MAIN_VITE_GATEWAY_URL` | WebSocket Gateway URL for remote device pairing | +| `MAIN_VITE_WEB_URL` | Web app URL for OAuth login redirect | + +**Web** (`apps/web/next.config.ts`): + +| Variable | Description | +|----------|-------------| +| `API_URL` | Backend API URL (default: `https://api-dev.copilothub.ai`) | + +**Build for different environments:** + +```bash +# Desktop +pnpm --filter @multica/desktop build # Production (.env.production) +pnpm --filter @multica/desktop build:staging # Staging (.env.staging) + +# Web (Vercel) +# Set API_URL in Vercel Dashboard → Settings → Environment Variables +``` + +See `apps/desktop/.env.example` for the full variable reference. + +## Monorepo Workflow + +| Command | Purpose | +|---------|---------| +| `pnpm dev` | Full dev mode — watches `core`, `types`, `utils` packages | +| `pnpm dev:desktop` | Desktop only — skip package watching | + +**When modifying packages:** + +1. Edit code in `packages/core`, `packages/types`, or `packages/utils` +2. Terminal shows `[core] ESM ⚡️ Build success` (~100ms) +3. Restart Desktop to apply changes (Ctrl+C, then `pnpm dev`) + +> **Why restart?** Electron main process does not support hot reload — this is an Electron limitation, not ours. diff --git a/docs/skills-and-tools.md b/docs/skills-and-tools.md new file mode 100644 index 00000000..1c17a282 --- /dev/null +++ b/docs/skills-and-tools.md @@ -0,0 +1,19 @@ +# Skills & Tools + +## Skills + +Skills extend agent functionality via `SKILL.md` files. See [Skills Documentation](../packages/core/src/agent/skills/README.md). + +```bash +multica skills list # List skills +multica skills add owner/repo # Install from GitHub +multica skills status # Check status +``` + +Built-in: `commit`, `code-review`, `skill-creator` + +## Tools + +Available tools: `read`, `write`, `edit`, `glob`, `exec`, `process`, `web_fetch`, `web_search`, `memory_search`, `sessions_spawn` + +See [Tools Documentation](../packages/core/src/agent/tools/README.md) for details. diff --git a/docs/time-injection.md b/docs/time-injection.md new file mode 100644 index 00000000..71befcc6 --- /dev/null +++ b/docs/time-injection.md @@ -0,0 +1,36 @@ +# Time Injection Design + +Super Multica uses **message-level timestamp injection** for time awareness. +Instead of placing dynamic time text in the system prompt, user turns are stamped at runtime. + +```mermaid +flowchart TD + A[Incoming turn] --> B{Entry point} + B -->|Desktop/Gateway/Cron/Subagent| C[AsyncAgent.write] + B -->|Heartbeat poll| D[AsyncAgent.write injectTimestamp=false] + C --> E{Already stamped or has 'Current time:'?} + E -->|Yes| F[Keep original message] + E -->|No| G[Prefix: [DOW YYYY-MM-DD HH:mm TZ]] + D --> H[Keep original heartbeat prompt] + F --> I[Agent.run] + G --> I + H --> I + I --> J[LLM receives final turn text] +``` + +## Injection Matrix + +| Path | Runtime call | Timestamp injected? | Notes | +| --- | --- | --- | --- | +| Desktop direct chat | `agent.write(content)` | Yes | Default behavior | +| Gateway/remote chat | `agent.write(content)` | Yes | Same entry path as desktop | +| `sessions_spawn` child task | `childAgent.write(task)` | Yes | Child turn gets current time context | +| Cron `agent-turn` payload | `agent.write(cronMessage)` | Yes (guarded) | Skips if message already carries `Current time:` | +| Heartbeat runner | `agent.write(prompt, { injectTimestamp: false })` | No | Prevents heartbeat prompt matching from breaking | +| Internal orchestration | `writeInternal(...)` | No | Uses separate internal run path | + +## Why This Design + +- Keeps system prompt cache-stable (no per-turn date churn in system prompt text) +- Gives the model an explicit "now" reference on each user turn +- Uses guardrails to avoid double-stamping and heartbeat regressions