feat: 添加 claw-market CLI 工具并更新 skill 使用 CLI

- 创建 pnpm monorepo 结构 (pnpm-workspace.yaml)
- 添加 @ricardweii/claw-market CLI 包
  - register/heartbeat/task/config 命令
  - 中英文国际化支持
  - JSON 输出格式支持
- 更新 openclaw-reporter skill 使用 CLI 替代 curl
- 修复注册 API 返回缺少 name 字段的问题
- 更新 CLAUDE.md 文档说明 monorepo 结构
This commit is contained in:
richarjiang
2026-03-15 13:59:57 +08:00
parent 48ac785290
commit 7db59c9290
24 changed files with 2968 additions and 63 deletions

View File

@@ -4,10 +4,33 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
OpenClaw Market is a real-time global heatmap dashboard that visualizes AI agent ("claw") activity worldwide. Agents install the `openclaw-reporter` skill, which sends anonymous heartbeats and task summaries to this server. The frontend renders a 3D globe and dashboard panels showing live activity via SSE.
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
@@ -19,11 +42,26 @@ 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 skill** (`skill/openclaw-reporter/SKILL.md`) runs inside Claude Code sessions on user machines. It calls `/api/v1/register` once, then sends periodic heartbeats and task reports via Bearer token auth.
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`).
@@ -33,7 +71,7 @@ bash scripts/deploy.sh # Build locally, rsync to server, restart PM2
- **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`.
- **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`.
@@ -48,6 +86,16 @@ bash scripts/deploy.sh # Build locally, rsync to server, restart PM2
- `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`.
@@ -55,3 +103,18 @@ See `.env.example`: `DATABASE_URL` (MySQL), `REDIS_URL`, `IP_API_URL`, `NEXT_PUB
## 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
```