wushenghua/hapi
1
0
Fork 0
mirror of https://github.com/wu736139669/hapi.git synced 2026-08-05 06:24:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update all README files with comprehensive documentation

Browse Source 
Update documentation across the project to reflect current state of codebase:
- cli/README.md: Add all commands (codex, gemini, daemon subcommands, doctor, mcp),
  configuration options, storage locations, and source structure references
- server/README.md: Add complete HTTP API reference, Socket.IO events, Telegram bot
  features, core logic descriptions, and source structure
- web/README.md: Add all routes, feature descriptions, authentication flow, data
  fetching, real-time updates, and source structure
- README.md: Improve feature list clarity, add HTTPS exposure instructions in
  quickstart, add multi-agent support section
This commit is contained in:
weishu
2025-12-24 17:56:07 +08:00
parent 852c7f4c4e
commit eee4489b0f
4 changed files with 387 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
server/README.md
+152 -30
View File
@@ -3,6 +3,7 @@
Telegram bot + HTTP API + realtime updates for hapi.
## What it does
- Telegram bot for notifications and the Mini App entrypoint.
- HTTP API for sessions, messages, permissions, machines, and files.
- Server-Sent Events stream for live updates in the web app.
@@ -10,29 +11,31 @@ Telegram bot + HTTP API + realtime updates for hapi.
- Serves the web app from `web/dist` or embedded assets in the single binary.
- Persists state in SQLite.
## Typical deployment flow
1. Configure env vars.
2. Expose the server to the internet (HTTPS) if you need Telegram Mini App access.
3. Run the server.
4. Point the CLI to the server and open the web app.
## Configuration
Required:
- `CLI_API_TOKEN` - shared secret used by CLI and web login.
Optional (Telegram):
- `TELEGRAM_BOT_TOKEN` - token from @BotFather.
- `ALLOWED_CHAT_IDS` - comma-separated chat IDs allowed to use the bot.
- `WEBAPP_URL` - public HTTPS URL for Telegram Mini App access.
See `src/configuration.ts` for all options.
### Required
- `CLI_API_TOKEN` - Shared secret used by CLI and web login. Auto-generated if not set.
### Optional (Telegram)
- `TELEGRAM_BOT_TOKEN` - Token from @BotFather.
- `ALLOWED_CHAT_IDS` - Comma-separated chat IDs allowed to use the bot.
- `WEBAPP_URL` - Public HTTPS URL for Telegram Mini App access.
### Optional
Optional:
- `WEBAPP_PORT` - HTTP port (default: 3006).
- `CORS_ORIGINS` - comma-separated origins, or `*`.
- `HAPI_HOME` - data directory (default: ~/.hapi).
- `DB_PATH` - SQLite database path.
- `CORS_ORIGINS` - Comma-separated origins, or `*`.
- `HAPI_HOME` - Data directory (default: ~/.hapi).
- `DB_PATH` - SQLite database path (default: HAPI_HOME/hapi.db).
## Running
Binary (single executable):
```bash
export TELEGRAM_BOT_TOKEN="..."
export ALLOWED_CHAT_IDS="12345678"
@@ -47,18 +50,146 @@ To enable Telegram, set TELEGRAM_BOT_TOKEN and WEBAPP_URL, start the server, sen
to the bot to get your chat ID, set ALLOWED_CHAT_IDS, and restart the server.
From source:
```bash
bun install
bun run dev:server
```
Or inside `server/`:
```bash
bun run start
```
## HTTP API
See `src/web/routes/` for all endpoints.
### Authentication (`src/web/routes/auth.ts`)
- `POST /api/auth` - Get JWT token (Telegram initData or CLI_API_TOKEN).
### Sessions (`src/web/routes/sessions.ts`)
- `GET /api/sessions` - List all sessions.
- `GET /api/sessions/:id` - Get session details.
- `POST /api/sessions/:id/abort` - Abort session.
- `POST /api/sessions/:id/switch` - Switch session mode (remote/local).
- `POST /api/sessions/:id/permission-mode` - Set permission mode.
- `POST /api/sessions/:id/model` - Set model preference.
### Messages (`src/web/routes/messages.ts`)
- `GET /api/sessions/:id/messages` - Get messages (paginated).
- `POST /api/sessions/:id/messages` - Send message.
### Permissions (`src/web/routes/permissions.ts`)
- `POST /api/sessions/:id/permissions/:requestId/approve` - Approve permission.
- `POST /api/sessions/:id/permissions/:requestId/deny` - Deny permission.
### Machines (`src/web/routes/machines.ts`)
- `GET /api/machines` - List online machines.
- `POST /api/machines/:id/spawn` - Spawn new session on machine.
### Git/Files (`src/web/routes/git.ts`)
- `GET /api/sessions/:id/git-status` - Git status.
- `GET /api/sessions/:id/git-diff-numstat` - Diff summary.
- `GET /api/sessions/:id/git-diff-file` - File-specific diff.
- `GET /api/sessions/:id/file` - Read file content.
- `GET /api/sessions/:id/files` - File search with ripgrep.
### Events (`src/web/routes/events.ts`)
- `GET /api/events` - SSE stream for live updates.
### CLI (`src/web/routes/cli.ts`)
- `POST /cli/sessions` - Create/load session.
- `GET /cli/sessions/:id` - Get session by ID.
- `POST /cli/machines` - Create/load machine.
- `GET /cli/machines/:id` - Get machine by ID.
## Socket.IO
See `src/socket/handlers/cli.ts` for event handlers.
Namespace: `/cli`
### Client events (CLI to server)
- `message` - Send message to session.
- `update-metadata` - Update session metadata.
- `update-state` - Update agent state.
- `session-alive` - Keep session active.
- `session-end` - Mark session ended.
- `machine-alive` - Keep machine online.
- `rpc-register` - Register RPC handler.
- `rpc-unregister` - Unregister RPC handler.
### Server events (server to clients)
- `update` - Broadcast session/message updates.
- `rpc-request` - Incoming RPC call.
See `src/socket/rpcRegistry.ts` for RPC routing.
## Telegram Bot
See `src/telegram/bot.ts` for bot implementation.
### Commands
- `/start` - Welcome message with chat ID.
- `/app` - Open Mini App.
### Features
- Permission request notifications with approve/deny buttons.
- Session ready notifications.
- Deep links to Mini App sessions.
See `src/telegram/callbacks.ts` for button handlers.
## Core Logic
See `src/sync/syncEngine.ts` for the main session/message manager:
- In-memory session cache with versioning.
- Message pagination and retrieval.
- Permission approval/denial.
- RPC method routing via Socket.IO.
- Event publishing to SSE and Telegram.
- Git operations and file search.
- Activity tracking and timeouts.
## Storage
See `src/store/index.ts` for SQLite persistence:
- Sessions with metadata and agent state.
- Messages with pagination support.
- Machines with daemon state.
- Todo extraction from messages.
## Source structure
- `src/web/` - HTTP server and routes.
- `src/socket/` - Socket.IO setup and handlers.
- `src/telegram/` - Telegram bot.
- `src/sync/` - Core session/message logic.
- `src/store/` - SQLite persistence.
- `src/sse/` - Server-Sent Events.
## Security model
Access is controlled by:
- Telegram chat ID allowlist (when Telegram is enabled).
- `CLI_API_TOKEN` shared secret for CLI and browser access.
Transport security depends on HTTPS in front of the server.
## Build for deployment
From the repo root:
```bash
bun run build:server
bun run build:web
@@ -67,15 +198,6 @@ bun run build:web
The server build output is `server/dist/index.js`, and the web assets are in `web/dist`.
## Networking notes
- Telegram Mini Apps require HTTPS and a public URL. If the server has no public IP, use Cloudflare Tunnel or Tailscale and set `WEBAPP_URL` to the HTTPS endpoint.
- If the web app is hosted on a different origin, set `CORS_ORIGINS` accordingly.
## Architecture overview
The server is the hub for direct-connect mode. It accepts CLI connections over Socket.IO, exposes HTTP endpoints for the web UI, and publishes live updates over SSE. A Telegram bot provides notifications and a Mini App entrypoint. Session and machine state are stored in a local SQLite database.
## Security model
Access is controlled by:
- Telegram chat ID allowlist (when Telegram is enabled).
- `CLI_API_TOKEN` shared secret for CLI and browser access.
Transport security depends on HTTPS in front of the server.