7db59c9290
- 创建 pnpm monorepo 结构 (pnpm-workspace.yaml) - 添加 @ricardweii/claw-market CLI 包 - register/heartbeat/task/config 命令 - 中英文国际化支持 - JSON 输出格式支持 - 更新 openclaw-reporter skill 使用 CLI 替代 curl - 修复注册 API 返回缺少 name 字段的问题 - 更新 CLAUDE.md 文档说明 monorepo 结构
121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
OpenClaw Market is a real-time global heatmap dashboard that visualizes AI agent ("claw") activity worldwide. Agents install the `openclaw-reporter` skill or `@ricardweii/claw-market` CLI, which sends anonymous heartbeats and task summaries to this server. The frontend renders a 3D globe and dashboard panels showing live activity via SSE.
|
|
|
|
## Monorepo Structure
|
|
|
|
This is a pnpm monorepo with two packages:
|
|
|
|
```
|
|
openclaw-market/
|
|
├── app/ # Next.js application (main web app)
|
|
├── lib/ # Shared libraries for web app
|
|
├── packages/
|
|
│ └── claw-market/ # CLI tool (published to npm)
|
|
│ ├── src/
|
|
│ │ ├── index.ts # CLI entry point
|
|
│ │ ├── commands/ # register, heartbeat, task, config
|
|
│ │ ├── lib/ # api, config, validate, platform
|
|
│ │ └── i18n/ # en.json, zh.json
|
|
│ └── package.json
|
|
├── skill/
|
|
│ └── openclaw-reporter/ # Claude Code skill (uses CLI)
|
|
└── pnpm-workspace.yaml
|
|
```
|
|
|
|
## Commands
|
|
|
|
### Main App
|
|
|
|
```bash
|
|
pnpm dev # Start dev server with Turbopack (localhost:3000)
|
|
pnpm build # Production build
|
|
pnpm lint # ESLint
|
|
pnpm db:generate # Generate Drizzle migrations
|
|
pnpm db:push # Push schema to database (no migration files)
|
|
pnpm db:migrate # Run migrations
|
|
pnpm db:studio # Open Drizzle Studio GUI
|
|
bash scripts/deploy.sh # Build locally, rsync to server, restart PM2
|
|
```
|
|
|
|
### CLI Package
|
|
|
|
```bash
|
|
pnpm --filter claw-market build # Build CLI
|
|
pnpm --filter claw-market lint # Type check CLI
|
|
pnpm --filter claw-market dev # Build with watch mode
|
|
|
|
# Or from packages/claw-market:
|
|
cd packages/claw-market
|
|
pnpm build
|
|
node dist/index.js --help
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Data Flow
|
|
|
|
1. **Reporter sources**:
|
|
- **CLI** (`packages/claw-market/`) — Standalone npm package `@ricardweii/claw-market`
|
|
- **Skill** (`skill/openclaw-reporter/SKILL.md`) — Claude Code skill that wraps the CLI
|
|
2. **API routes** (`app/api/v1/`) validate requests, update MySQL via Drizzle, cache state in Redis, and publish events to a Redis Pub/Sub channel (`channel:realtime`).
|
|
3. **SSE endpoint** (`/api/v1/stream`) subscribes to Redis Pub/Sub and streams events to the browser.
|
|
4. **Frontend** is a single-page "use client" app. The homepage renders a 3D globe (`react-globe.gl`), dashboard panels, and a continent drill-down page. Data arrives via polling (`use-heatmap-data`) and SSE (`use-sse`).
|
|
|
|
### Key Layers
|
|
|
|
- **Auth**: Bearer token via `lib/auth/api-key.ts`. API keys are generated at registration, cached in Redis for 1 hour.
|
|
- **Geo**: IP geolocation via `ip-api.com`, results cached in `geo_cache` MySQL table. Country-to-continent mapping in `lib/geo/ip-location.ts`.
|
|
- **Real-time**: Redis Pub/Sub (`lib/redis/index.ts`) for event broadcasting. SSE stream route creates a per-connection Redis subscriber.
|
|
- **Validation**: Zod schemas in `lib/validators/schemas.ts`. Shared with CLI via copy (same structure).
|
|
- **Database**: Drizzle ORM with MySQL (`mysql2` driver). Schema in `lib/db/schema.ts`. Tables: `claws`, `heartbeats`, `tasks`, `geo_cache`.
|
|
- **Redis**: ioredis with two singleton clients (main + subscriber). Stores online status, active claw sorted sets, global/region stats, hourly activity, heatmap cache.
|
|
- **i18n**: `next-intl` with locale-prefixed routing (`/en/...`, `/zh/...`). Config in `i18n/routing.ts`, middleware in `middleware.ts`, translations in `messages/en.json` and `messages/zh.json`.
|
|
|
|
### Frontend Structure
|
|
|
|
- `app/[locale]/page.tsx` — Homepage (globe + dashboard)
|
|
- `app/[locale]/continent/[slug]/page.tsx` — Continent drill-down page
|
|
- `components/globe/` — 3D globe view using `react-globe.gl` (dynamically imported, no SSR)
|
|
- `components/map/` — 2D continent maps using `react-simple-maps`
|
|
- `components/dashboard/` — Stats panel, region ranking, activity timeline, claw feed
|
|
- `components/layout/` — Navbar, particle background, view switcher, install banner, language switcher
|
|
- `messages/` — i18n translation files (en, zh)
|
|
|
|
### CLI Structure (`packages/claw-market/`)
|
|
|
|
- `src/index.ts` — CLI entry point (commander)
|
|
- `src/commands/` — Command implementations (register, heartbeat, task, config)
|
|
- `src/lib/api.ts` — HTTP client for API calls
|
|
- `src/lib/config.ts` — Config file management (~/.openclaw/config.json)
|
|
- `src/lib/validate.ts` — Zod validation schemas
|
|
- `src/lib/platform.ts` — Platform/model detection
|
|
- `src/i18n/` — Translation files (en, zh)
|
|
|
|
## Environment Variables
|
|
|
|
See `.env.example`: `DATABASE_URL` (MySQL), `REDIS_URL`, `IP_API_URL`, `NEXT_PUBLIC_APP_URL`.
|
|
|
|
## Deployment
|
|
|
|
Production runs on a remote server via `scripts/deploy.sh` — builds locally, rsyncs to server, installs prod deps, restarts via PM2 on port 3003.
|
|
|
|
## CLI Publishing
|
|
|
|
The CLI is published to npm as `@ricardweii/claw-market`:
|
|
|
|
```bash
|
|
cd packages/claw-market
|
|
npm publish --access public --otp=<OTP>
|
|
```
|
|
|
|
Install globally:
|
|
|
|
```bash
|
|
npm install -g @ricardweii/claw-market
|
|
```
|