docs: regenerate prioritized core documentation
This commit is contained in:
Jiayuan Zhang
parent
ecb0cd392e
commit
0ed46510ee
8 changed files with 628 additions and 0 deletions
92
CLAUDE.md
Normal file
92
CLAUDE.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file gives coding agents high-signal guidance for this repository.
|
||||
|
||||
## 1. Project Snapshot
|
||||
|
||||
Super Multica is a pnpm monorepo for a distributed AI agent system:
|
||||
|
||||
- Agent engine + Hub: `packages/core`
|
||||
- Desktop app (primary local runtime): `apps/desktop`
|
||||
- CLI: `apps/cli`
|
||||
- Remote access gateway: `apps/gateway`
|
||||
- Web client: `apps/web`
|
||||
|
||||
## 2. Monorepo Map
|
||||
|
||||
```text
|
||||
apps/
|
||||
cli desktop gateway server web mobile
|
||||
|
||||
packages/
|
||||
core sdk ui store hooks types utils
|
||||
|
||||
skills/
|
||||
skill assets and runtime helper scripts
|
||||
```
|
||||
|
||||
## 3. Core Commands
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm multica
|
||||
pnpm multica run "<prompt>"
|
||||
pnpm dev
|
||||
pnpm dev:gateway
|
||||
pnpm dev:web
|
||||
pnpm dev:local
|
||||
pnpm build
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## 4. Architecture Notes
|
||||
|
||||
- Desktop app embeds Hub + Agent runtime.
|
||||
- Gateway is optional for local desktop usage, required for remote/web-style access.
|
||||
- Web app depends on gateway/API setup.
|
||||
- Sessions are directory-based: `~/.super-multica/sessions/<session-id>/`.
|
||||
|
||||
## 5. Data and Credentials
|
||||
|
||||
- Default data dir: `~/.super-multica` (override with `SMC_DATA_DIR`)
|
||||
- Credentials: `~/.super-multica/credentials.json5` (override with `SMC_CREDENTIALS_PATH`)
|
||||
- Initialize credentials via `pnpm multica credentials init`
|
||||
|
||||
## 6. Coding Rules
|
||||
|
||||
- TypeScript strict mode is enabled; keep types explicit.
|
||||
- Keep comments in code **English only**.
|
||||
- Prefer existing patterns/components over introducing parallel abstractions.
|
||||
- Avoid broad refactors unless required by the task.
|
||||
- Keep docs concise and aligned with current code behavior.
|
||||
|
||||
## 7. Testing Rules
|
||||
|
||||
- Test runner: Vitest.
|
||||
- Mock policy: mock external/third-party dependencies only.
|
||||
- Do not mock internal modules when real integration can be tested.
|
||||
- Prefer temp directories and real file I/O for storage-related tests.
|
||||
|
||||
## 8. Commit Rules
|
||||
|
||||
- Use atomic commits grouped by logical intent.
|
||||
- Conventional format:
|
||||
- `feat(scope): ...`
|
||||
- `fix(scope): ...`
|
||||
- `refactor(scope): ...`
|
||||
- `docs: ...`
|
||||
- `test(scope): ...`
|
||||
- `chore(scope): ...`
|
||||
|
||||
## 9. Minimum Pre-Push Checks
|
||||
|
||||
```bash
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## 10. E2E Docs
|
||||
|
||||
- `docs/e2e-testing-guide.md`
|
||||
- `docs/e2e-finance-benchmark.md`
|
||||
88
README.md
Normal file
88
README.md
Normal file
|
|
@ -0,0 +1,88 @@
|
|||
# Super Multica
|
||||
|
||||
Super Multica is a monorepo for a distributed AI agent framework.
|
||||
It includes a local-first Desktop app, CLI, Gateway/Web access, and reusable core packages.
|
||||
|
||||
## Current Documentation Strategy
|
||||
|
||||
The docs set is intentionally **small and high-signal**.
|
||||
For current status and priorities, see:
|
||||
|
||||
- `docs/README.md`
|
||||
|
||||
## Monorepo Layout
|
||||
|
||||
```text
|
||||
apps/
|
||||
cli/ @multica/cli Command-line interface
|
||||
desktop/ @multica/desktop Electron desktop app (primary local runtime)
|
||||
gateway/ @multica/gateway NestJS WebSocket gateway
|
||||
server/ @multica/server NestJS REST server
|
||||
web/ @multica/web Next.js web app
|
||||
mobile/ @multica/mobile React Native app
|
||||
|
||||
packages/
|
||||
core/ @multica/core Agent, Hub, tools, channels, cron, heartbeat
|
||||
sdk/ @multica/sdk Gateway client SDK
|
||||
ui/ @multica/ui Shared React UI components
|
||||
store/ @multica/store Zustand stores
|
||||
hooks/ @multica/hooks Shared hooks
|
||||
types/ @multica/types Shared types
|
||||
utils/ @multica/utils Shared utilities
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm multica credentials init
|
||||
pnpm multica
|
||||
```
|
||||
|
||||
Run desktop app in dev mode:
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## Common Commands
|
||||
|
||||
```bash
|
||||
# CLI
|
||||
pnpm multica
|
||||
pnpm multica run "Hello"
|
||||
pnpm multica chat
|
||||
pnpm multica help
|
||||
|
||||
# Development
|
||||
pnpm dev
|
||||
pnpm dev:desktop
|
||||
pnpm dev:gateway
|
||||
pnpm dev:web
|
||||
pnpm dev:local
|
||||
|
||||
# Build / quality
|
||||
pnpm build
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## Runtime Data
|
||||
|
||||
By default, runtime data is stored under:
|
||||
|
||||
- `~/.super-multica`
|
||||
|
||||
You can isolate environments with:
|
||||
|
||||
- `SMC_DATA_DIR=~/.super-multica-dev` (or other path)
|
||||
|
||||
## Core Docs
|
||||
|
||||
- `CLAUDE.md` (AI coding guidance in this repo)
|
||||
- `docs/development.md`
|
||||
- `docs/cli.md`
|
||||
- `docs/credentials.md`
|
||||
- `docs/skills-and-tools.md`
|
||||
- `docs/e2e-testing-guide.md`
|
||||
- `docs/e2e-finance-benchmark.md`
|
||||
26
docs/README.md
Normal file
26
docs/README.md
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
# Documentation Index (Priority-Based)
|
||||
|
||||
This repo keeps documentation intentionally small to reduce stale AI context.
|
||||
|
||||
## P0 (Keep Fresh)
|
||||
|
||||
1. `README.md`
|
||||
2. `CLAUDE.md`
|
||||
3. `docs/development.md`
|
||||
4. `docs/cli.md`
|
||||
5. `docs/credentials.md`
|
||||
|
||||
## P1 (Operational)
|
||||
|
||||
1. `docs/skills-and-tools.md`
|
||||
2. `docs/package-management.md`
|
||||
3. `docs/e2e-testing-guide.md`
|
||||
|
||||
## P2 (Benchmarks / Specialized)
|
||||
|
||||
1. `docs/e2e-finance-benchmark.md`
|
||||
|
||||
## Regeneration Rule
|
||||
|
||||
When code behavior changes, update only impacted P0/P1 docs first.
|
||||
If unsure, prefer deleting stale sections over keeping speculative content.
|
||||
129
docs/cli.md
Normal file
129
docs/cli.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
# CLI Guide (`multica`)
|
||||
|
||||
## Entry
|
||||
|
||||
```bash
|
||||
pnpm multica
|
||||
```
|
||||
|
||||
Equivalent command names:
|
||||
|
||||
- `multica`
|
||||
- `mu`
|
||||
|
||||
## Core Commands
|
||||
|
||||
```bash
|
||||
multica # interactive chat (default)
|
||||
multica run "<prompt>" # one-shot run
|
||||
multica chat # explicit interactive mode
|
||||
multica session <command> # session management
|
||||
multica profile <command> # profile management
|
||||
multica skills <command> # skill management
|
||||
multica tools <command> # tool policy inspection
|
||||
multica credentials <command> # credentials management
|
||||
multica cron <command> # scheduled tasks
|
||||
multica dev [service] # start dev services
|
||||
multica help
|
||||
```
|
||||
|
||||
## Run Mode
|
||||
|
||||
```bash
|
||||
multica run [options] <prompt>
|
||||
echo "prompt" | multica run
|
||||
```
|
||||
|
||||
Common options:
|
||||
|
||||
- `--profile <id>`
|
||||
- `--provider <name>`
|
||||
- `--model <name>`
|
||||
- `--session <id>`
|
||||
- `--cwd <dir>`
|
||||
- `--run-log`
|
||||
- `--tools-allow a,b,c`
|
||||
- `--tools-deny a,b,c`
|
||||
- `--context-window <tokens>`
|
||||
|
||||
## Chat Mode
|
||||
|
||||
```bash
|
||||
multica chat [options]
|
||||
multica [options]
|
||||
```
|
||||
|
||||
In-chat commands:
|
||||
|
||||
- `/help`
|
||||
- `/exit`
|
||||
- `/clear`
|
||||
- `/session`
|
||||
- `/new`
|
||||
- `/multiline`
|
||||
- `/provider`
|
||||
- `/model`
|
||||
|
||||
## Sessions
|
||||
|
||||
```bash
|
||||
multica session list
|
||||
multica session show <id>
|
||||
multica session delete <id>
|
||||
```
|
||||
|
||||
Session data root:
|
||||
|
||||
- `~/.super-multica/sessions/`
|
||||
- or `SMC_DATA_DIR/sessions/`
|
||||
|
||||
## Profiles
|
||||
|
||||
```bash
|
||||
multica profile list
|
||||
multica profile new <id>
|
||||
multica profile setup <id>
|
||||
multica profile show <id>
|
||||
multica profile edit <id>
|
||||
multica profile delete <id>
|
||||
```
|
||||
|
||||
## Skills
|
||||
|
||||
```bash
|
||||
multica skills list
|
||||
multica skills status [id]
|
||||
multica skills install <id>
|
||||
multica skills add <owner/repo[/skill]>
|
||||
multica skills remove <name>
|
||||
```
|
||||
|
||||
## Tools
|
||||
|
||||
```bash
|
||||
multica tools list
|
||||
multica tools list --allow group:fs,web_fetch
|
||||
multica tools list --deny exec
|
||||
multica tools groups
|
||||
```
|
||||
|
||||
## Credentials
|
||||
|
||||
```bash
|
||||
multica credentials init
|
||||
multica credentials show
|
||||
multica credentials edit
|
||||
```
|
||||
|
||||
## Cron
|
||||
|
||||
```bash
|
||||
multica cron status
|
||||
multica cron list
|
||||
multica cron add -n "name" --every "30m" --message "..."
|
||||
multica cron run <id>
|
||||
multica cron enable <id>
|
||||
multica cron disable <id>
|
||||
multica cron remove <id>
|
||||
multica cron logs <id>
|
||||
```
|
||||
76
docs/credentials.md
Normal file
76
docs/credentials.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# Credentials Guide
|
||||
|
||||
## Initialize
|
||||
|
||||
```bash
|
||||
pnpm multica credentials init
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
- `~/.super-multica/credentials.json5`
|
||||
|
||||
## Path Resolution
|
||||
|
||||
Credential file lookup order:
|
||||
|
||||
1. `SMC_CREDENTIALS_PATH` (explicit override)
|
||||
2. `SMC_DATA_DIR/credentials.json5` (or default data dir)
|
||||
3. `~/.super-multica/credentials.json5` fallback
|
||||
|
||||
## Minimal Template
|
||||
|
||||
```json5
|
||||
{
|
||||
version: 1,
|
||||
llm: {
|
||||
provider: "kimi-coding",
|
||||
providers: {
|
||||
"kimi-coding": {
|
||||
apiKey: "your-key",
|
||||
},
|
||||
},
|
||||
},
|
||||
tools: {
|
||||
// tool-specific keys
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Multi-Key Rotation (Per Provider)
|
||||
|
||||
You can define multiple keys under one provider namespace:
|
||||
|
||||
```json5
|
||||
{
|
||||
llm: {
|
||||
providers: {
|
||||
"anthropic": { apiKey: "primary" },
|
||||
"anthropic:backup": { apiKey: "backup" },
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic", "anthropic:backup"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## OAuth Providers
|
||||
|
||||
- `claude-code`: run `claude login`
|
||||
- `openai-codex`: run `codex login`
|
||||
|
||||
API-key providers are configured directly in `credentials.json5`.
|
||||
|
||||
## Tool Credentials
|
||||
|
||||
Tool credentials are read from:
|
||||
|
||||
- `credentials.json5` under `tools`
|
||||
- skill-level `.env` files under skill directories
|
||||
|
||||
## Security
|
||||
|
||||
- Keep credentials file mode private (`600` on Unix-like systems).
|
||||
- Do not commit keys into the repository.
|
||||
- Prefer isolated data dirs (`SMC_DATA_DIR`) for test/dev environments.
|
||||
83
docs/development.md
Normal file
83
docs/development.md
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
# Development Guide
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 20+
|
||||
- pnpm 10+
|
||||
- macOS/Linux/Windows
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
`.npmrc` must keep:
|
||||
|
||||
```ini
|
||||
shamefully-hoist=true
|
||||
```
|
||||
|
||||
## Main Dev Entry Points
|
||||
|
||||
```bash
|
||||
# Recommended local desktop workflow
|
||||
pnpm dev
|
||||
|
||||
# Service-specific
|
||||
pnpm dev:desktop
|
||||
pnpm dev:gateway
|
||||
pnpm dev:web
|
||||
|
||||
# Full local stack with isolated dev data
|
||||
pnpm dev:local
|
||||
```
|
||||
|
||||
## What Each Command Does
|
||||
|
||||
- `pnpm dev`: builds shared packages, then runs `types + utils + core + desktop` watch flow.
|
||||
- `pnpm dev:desktop`: Electron desktop only.
|
||||
- `pnpm dev:gateway`: NestJS WebSocket gateway (`PORT`, default `3000`).
|
||||
- `pnpm dev:web`: Next.js web app (`3000` by script).
|
||||
- `pnpm dev:local`: gateway + web + desktop with dev-safe env defaults.
|
||||
|
||||
## Important Environment Variables
|
||||
|
||||
- `SMC_DATA_DIR`: override runtime data root (default `~/.super-multica`)
|
||||
- `GATEWAY_URL`: gateway endpoint for desktop/CLI hub connection
|
||||
- `MULTICA_API_URL`: required by web/data tools
|
||||
- `PORT`: gateway/server port
|
||||
- `MULTICA_WORKSPACE_DIR`: override workspace root
|
||||
- `MULTICA_RUN_LOG=1`: enable structured run-log output
|
||||
|
||||
## Local Full-Stack Notes
|
||||
|
||||
`pnpm dev:local` expects root `.env` with Telegram credentials:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
At minimum set:
|
||||
|
||||
- `TELEGRAM_BOT_TOKEN`
|
||||
|
||||
## Build / Quality
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
pnpm test:coverage
|
||||
```
|
||||
|
||||
## Useful Reset Commands
|
||||
|
||||
```bash
|
||||
# Reset default + dev data dirs used by desktop scripts
|
||||
pnpm dev:desktop:reset
|
||||
|
||||
# Reset and relaunch desktop onboarding flow
|
||||
pnpm dev:desktop:fresh
|
||||
pnpm dev:desktop:onboarding
|
||||
```
|
||||
48
docs/package-management.md
Normal file
48
docs/package-management.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
# Package Management
|
||||
|
||||
## Workspace
|
||||
|
||||
- Package manager: `pnpm` (workspace mode)
|
||||
- Build orchestrator: `turbo`
|
||||
|
||||
## Required `.npmrc`
|
||||
|
||||
Keep this in repo root:
|
||||
|
||||
```ini
|
||||
shamefully-hoist=true
|
||||
```
|
||||
|
||||
This is required for Electron packaging compatibility in this monorepo.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Clean Reinstall (When Needed)
|
||||
|
||||
Use this when lockfile/hoist state is corrupted or after major package-manager config changes:
|
||||
|
||||
```bash
|
||||
rm -rf node_modules apps/*/node_modules packages/*/node_modules
|
||||
rm -f pnpm-lock.yaml
|
||||
pnpm install
|
||||
```
|
||||
|
||||
## Build / Check
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```
|
||||
|
||||
## Targeted Commands
|
||||
|
||||
```bash
|
||||
pnpm --filter @multica/desktop build
|
||||
pnpm --filter @multica/core build
|
||||
pnpm --filter @multica/web dev
|
||||
```
|
||||
86
docs/skills-and-tools.md
Normal file
86
docs/skills-and-tools.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
# Skills and Tools
|
||||
|
||||
## Skills Loading Model
|
||||
|
||||
Skills are loaded from two sources with precedence:
|
||||
|
||||
1. Managed skills: `~/.super-multica/skills/`
|
||||
2. Profile skills: `~/.super-multica/agent-profiles/<profile-id>/skills/`
|
||||
|
||||
Profile skills override managed skills when IDs conflict.
|
||||
|
||||
## Skill File Contract
|
||||
|
||||
A valid skill directory must include:
|
||||
|
||||
- `SKILL.md`
|
||||
|
||||
Optional runtime files:
|
||||
|
||||
- `.env`
|
||||
- helper scripts/assets
|
||||
|
||||
## Current Repo Note
|
||||
|
||||
This repository intentionally keeps docs and bundled skill metadata minimal.
|
||||
If a directory under `skills/` does not contain `SKILL.md`, it will not be loaded as a skill.
|
||||
|
||||
## Skills CLI
|
||||
|
||||
```bash
|
||||
multica skills list
|
||||
multica skills status [id]
|
||||
multica skills install <id>
|
||||
multica skills add <owner/repo[/skill]>
|
||||
multica skills remove <name>
|
||||
```
|
||||
|
||||
## Tool System
|
||||
|
||||
`@multica/core` composes:
|
||||
|
||||
- base coding tools (`read/write/edit/...`)
|
||||
- extended tools (`exec`, `process`, `glob`, `web_fetch`, `web_search`, `data`, `cron`, `delegate`)
|
||||
- conditional tools (`memory_search`, `send_file`)
|
||||
|
||||
Tool errors are wrapped into structured tool results instead of crashing runs.
|
||||
|
||||
## Tool Groups
|
||||
|
||||
Supported group aliases:
|
||||
|
||||
- `group:fs` -> `read, write, edit, glob`
|
||||
- `group:runtime` -> `exec, process`
|
||||
- `group:web` -> `web_search, web_fetch`
|
||||
- `group:memory` -> `memory_search`
|
||||
- `group:subagent` -> `delegate`
|
||||
- `group:cron` -> `cron`
|
||||
- `group:data` -> `data`
|
||||
- `group:core` -> core local/web/data set
|
||||
|
||||
## Tool Policy Example
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
allow: ["group:fs", "web_search", "web_fetch"],
|
||||
deny: ["exec"],
|
||||
byProvider: {
|
||||
"openai": {
|
||||
deny: ["data"],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`deny` always has priority over `allow`.
|
||||
|
||||
## Inspect Effective Tools
|
||||
|
||||
```bash
|
||||
multica tools list
|
||||
multica tools list --allow group:fs,web_fetch
|
||||
multica tools list --deny exec
|
||||
multica tools groups
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue