# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

ArenaSK — AI Skill 竞技平台 + 多智能体自主开发系统。使用 Node.js + Claude CLI 实现 Skill 的创建、评测、进化和管理。

## 快速启动

```bash
# 安装
npm install && cd server && npm install && cd ../web && npm install

# 开发模式 (前后端分离)
npm run dev
# 后端: localhost:3000 | 前端: localhost:5173

# 生产启动
bash start.sh
```

## 常用命令

```bash
npm run dev              # 启动后端 + 前端 (开发)
npm run server:dev       # 仅后端 (localhost:3000)
npm run web              # 仅前端 (localhost:5173, proxy→3000)
npm run web:build        # 编译前端 → web/dist/
npm test                 # 运行 vitest
npm run skills:sync      # 同步 Skill 到 CLI 配置目录
```

## 架构

### 技术栈
- **后端**: Node.js + Express + WebSocket + SQLite (better-sqlite3)
- **前端**: Vue 3 + Vite + vue-router + vue-i18n (6 语言)
- **数据**: SQLite FTS5 全文搜索, 无 PostgreSQL
- **AI**: Claude CLI (本地进程)
- **包管理**: pnpm workspace (monorepo)

### 目录结构

| 目录 | 说明 |
|------|------|
| `server/index.js` | Express 入口 (API + WS + Plugin) |
| `server/routes/` | 11 个 API 路由模块 |
| `server/services/` | 16 个业务服务 (skill-db, job-manager 等) |
| `server/src/core/` | 核心引擎 (orchestrator, master-session, agent-manager) |
| `server/src/plugins/` | 插件系统 (PluginManager, channel monitor) |
| `web/src/views/` | 21 个 Vue 页面组件 |
| `skills/` | 系统级 Skill 定义 (19 个) |
| `scripts/` | 运维脚本 |
| `packages/` | 子包 (acp-core, evolution 等) |

### 关键 API 路由

| 路径 | 说明 |
|------|------|
| `/api/open/skills` | Open API: Skill 搜索/下载 |
| `/api/open/arena/leaderboard` | Arena 排行榜 |
| `/api/innovator/skills` | Skill 管理 (Admin) |
| `/api/master/chat` | Master Agent 对话 (SSE) |
| `/api/auth/*` | 认证 (JWT + GitHub OAuth) |
| `/ws/claude` | Claude 对话 (WebSocket) |

### 数据存储

- `data/skills/` — 27,000+ Skill 目录
- `data/skills.sqlite` — Skill 主数据库 (FTS5)
- `data/benchmark.sqlite` — Benchmark 运行数据
- `data/users.sqlite` — 用户数据

### 配置文件

| 文件 | 说明 |
|------|------|
| `.env` | 环境变量 (密钥、目录、CORS) |
| `server/config.js` | 服务器配置 |
| `server/config/taxonomy.js` | 三维标签分类 |

## 注意事项

- 数据库使用 SQLite (better-sqlite3)，无需 PostgreSQL
- 生产环境 Express 同时提供 API 和 `web/dist/` 静态文件
- `start.sh` 一键启动: 同步 Skill → 编译前端 → 启动 Server → 启动 Bot
- Claude CLI 使用 `--dangerously-skip-permissions` 自动批准模式
- Skill 目录在 `data/skills/`（代码仓库外部），通过 `config.skillsDataDir` 配置

> [!WARNING] (Agentic Self-Correction Loop Prevention)
> **Master Agent 必读**: 你目前存在一个已知的底层 Tool Calling JSON 解析缺陷。当你试图在 `Bash` tool 中使用带有多重双引号的复杂命令（例如 `curl -d '{"id":"lemonv", "name":"Lemonv"}'`）时，你的 JSON 转义会崩溃并导致你陷入"修复格式"的无限死循环，最终进程会被强制终止退出 (code=143)。
> **解决方案**: 
> 任何需要提交复杂 Payload (如 JSON) 的操作，**绝对禁止**直接在 `Bash` 的 command 参数里写 inline JSON 字符串。
> 如果你要创建公司或执行类似 API 请求，**必须先通过写入简单的 shell 脚本将 JSON 写入一个 /tmp/ 目录下的 `.json` 文件（确保你的 JSON 是单行紧凑格式/严格转义换行符，不要包含真回车换行 `\n`，以免引起 SyntaxError: Bad control character 崩溃），然后再通过 `curl -d @/tmp/payload.json` 发送。**
> 
> 【创建公司/招聘的正确方式示例】
> 创建 /tmp/lemonv.json，然后执行 `Bash`: `curl -X POST http://localhost:3000/api/company/create -H "Content-Type: application/json" -d @/tmp/lemonv.json`