# CLAUDE.md

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

## 项目概述

LemonBoss / ArenaSK — 多智能体自主开发系统 + AI Skill 竞技平台。Node.js + Claude CLI 驱动，提供 Agent 协作（公司 / OKR / 招聘 / Pipeline / Task Timeline）与 Skill 市场 / Arena 评测两套能力。

> 品牌历史：项目早期叫 ArenaSK（Skill 竞技场），现演进为 LemonBoss（多 Agent 公司体）。两个名称在代码中并存属正常现象。

## 快速启动

```bash
# 一次性安装 + 拷贝 .env.example
npm run setup

# 开发模式（前后端分离，跑完整 ArenaSK + LemonBoss）
npm run dev                       # 后端 server/index.js:3010 + 前端 vite:5173

# 仅 Agent Chat 子系统（轻量，不依赖 Skill DB）
bash start.sh                     # server/agent-server.js:3010 + vite:5173
```

> 端口默认 **3010**（`server/config.js`），不是 3000。`start.sh` 会先 kill 占用 3010 / 5173 的进程。

## 常用命令

```bash
# 启动
npm run dev                       # 后端 + 前端
npm run server / server:dev       # 仅后端 (start / --watch)
npm run web / web:build           # 前端开发 / 构建到 web/dist/

# 测试
npm test                          # vitest watch
npm run test:unit                 # vitest run (CI 用)
npm run test:multi-cli            # multi-CLI 集成测试
npm run test:browser-logger
npm run test:design-validator

# CLI / 工具
npm run example                   # 单次 auto-dev：实现斐波那契
npm run example-bmi               # 单次 auto-dev：BMI 程序
npm run logs / analyze / parse    # 查看 / 分析 / 解析 Agent 运行日志
npm run skills:sync               # 同步 Skill 到 Claude CLI 配置目录
auto-dev "<task>"                 # bin 入口 → server/src/cli/auto-dev.js
```

## 架构

### 技术栈
- **后端**：Node.js (≥18) + Express + WebSocket + SQLite（better-sqlite3, FTS5）
- **前端**：Vue 3 + Vite + vue-router + vue-i18n
- **AI**：Claude CLI（本地子进程，`--dangerously-skip-permissions` 自动批准）
- **包管理**：pnpm workspace（monorepo），`package.json` 含 `module-alias: { "@server": "server" }`

### 两个 Server 入口（重要）

| 入口 | 端口 | 启动方式 | 挂载路由 |
|------|------|----------|----------|
| `server/index.js` | 3010 | `npm run dev`, `npm run server` | 全量：`/api/claude-chat` `/api/config` `/api/evolution` `/api/innovator` `/api/master` `/api/open` `/api/arena` `/api/auth` `/api/users` `/api/whatsapp` `/api/agent` `/api/goals` `/api/company` `/api/tasks`，WS `/ws/claude`，`NODE_ENV=production` 时托管 `web/dist/` 静态文件 |
| `server/agent-server.js` | 3010 | `bash start.sh` | 仅 LemonBoss 子集：`/api/agent` `/api/company` `/api/goals` `/api/tasks` |

两者**不要同时启动**（端口冲突）。需要 Skill / Arena / Master Agent 时跑 `index.js`；只调通 Agent Chat / Company / OKR 时跑 `agent-server.js`。

### 目录速查

| 目录 | 说明 |
|------|------|
| `server/index.js` | 完整 ArenaSK 服务（API + WS + 插件 + 前端托管） |
| `server/agent-server.js` | 独立 Agent Chat 服务（LemonBoss 子集） |
| `server/routes/` | 15 个 API 路由 |
| `server/services/` | 26 个业务服务（skill-db, benchmark-runner, company-service, heartbeat, pipeline-service, retrain-pipeline, …） |
| `server/src/core/` | Agent 引擎核心（orchestrator, master-session, agent-manager, scheduler, session-pool, prompt-builder, runtime-resolver, …） |
| `server/src/engine/` | 进程层（command-queue, idle-timer, process-guard, run-registry, failover-error） |
| `server/src/plugins/` | 插件系统（plugin-manager, agent-bridge, config-bridge, bootstrap） |
| `server/src/tools/` | Master Agent 可调用的工具（call-agent, marketplace, orchestrate, train-skill, …） |
| `web/src/views/` | 10 个页面：AgentChat, AgentList, CompanyDashboard, JobsPanel, OkrDashboard, PipelineEditor, QuotaMonitor, SkillsMarket, TaskTimeline, TemplateAgents |
| `packages/` | `acp-core`, `agent-core`, `evolution`, `plugin-bootstrap` |
| `data/skills/` | Skill 仓库（代码外部目录，路径由 `config.skillsDataDir` 控制） |
| `scripts/` | 运维脚本（含 `sync-skills.js`） |
| `docs/` | 设计文档（`LEMONBOSS-SYSTEM-DESIGN.md`, `architecture-v5.md`, `open-api-manual.md`, `system-design/`, `user-guides/` …） |

### 关键 API 路由

| 路径 | 说明 |
|------|------|
| `/api/open/skills` | Open API: Skill 搜索 / 下载（FTS5） |
| `/api/open/arena/leaderboard` | Arena ELO 排行榜 |
| `/api/innovator/skills` | Skill 管理（Admin） |
| `/api/master/chat` | Master Agent 对话（SSE） |
| `/api/agent/*` | LemonBoss Agent Chat |
| `/api/company/*` `/api/goals/*` `/api/tasks/*` | 公司 / OKR / Task 管理 |
| `/api/auth/*` | JWT + GitHub OAuth |
| `/ws/claude` | Claude 实时对话（仅 `index.js`） |
| `/api/health` `/api/plugins` | 健康检查 / 插件状态 |

### 数据存储（SQLite，无需 PostgreSQL）

- `data/skills/` — Skill 目录（数万条）
- `data/skills.sqlite` — Skill 主库 + FTS5
- `data/benchmark.sqlite` — Benchmark 运行数据
- `data/users.sqlite` — 用户数据
- `data/trained_skills/` — 用户训练产物（按 userId 隔离）
- `server/conversations/` — 会话持久化

### 配置文件

| 文件 | 说明 |
|------|------|
| `.env` | 端口、CORS、`OPEN_API_KEYS`、各类目录覆盖；由 `npm run setup` 从 `.env.example` 生成 |
| `server/config.js` | 端口（默认 3010）、CORS、Skill / Conversations 路径 |
| `server/config/taxonomy.js` | 三维标签分类 |

## 注意事项

- 生产环境只跑 `server/index.js`：它会同时托管 API + `web/dist/` 静态文件（`NODE_ENV=production`）。
- `start.sh` **只**做：kill 端口 → 起 `agent-server.js` → 起 `vite`。**不**会自动 `skills:sync` / `web:build` / 起 bot —— 那些要单独跑。
- `server/index.js` 与 `agent-server.js` 都内置了 **body-sanitizer 中间件**：在 `express.json()` 之前清掉 `\x00-\x1F` 控制字符，避免外部 Agent 通过 `curl` 传未转义换行/制表符导致的 `Bad control character` 报错。修改请求体解析链路前先看这两段。
- 模块别名 `@server` → `server/`（`module-alias` 注册），跨子包 require 时可用。
- Claude CLI 进程默认带 `--dangerously-skip-permissions`，写入受限路径前自己评估风险。
- DevLoop 规范阅读：Coder/Architect Agent **优先读 `docs/prd/newfunction/_spec/*.md`**（机器可读规范，含 `CONVENTIONS.md` 跨切约定），需要 wireframe / SVG 图表 / 完整人类阅读版时才回查同名 `*.html`。`_spec/` 由 `npm run spec:extract` 从 HTML 自动生成，**不要手改**；改完 HTML 后必须重跑（pre-commit hook 会校验）。

> [!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`