From cabfef8f47a353d2333213cbee2adf105f914c37 Mon Sep 17 00:00:00 2001 From: yibo Date: Wed, 13 May 2026 12:18:38 +0800 Subject: [PATCH] docs(claude-md): rewrite to reflect dual server entrypoints + LemonBoss/ArenaSK split --- CLAUDE.md | 130 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------- 1 file changed, 81 insertions(+), 49 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b1108f6..713a552 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,95 +4,127 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 项目概述 -ArenaSK — AI Skill 竞技平台 + 多智能体自主开发系统。使用 Node.js + Claude CLI 实现 Skill 的创建、评测、进化和管理。 +LemonBoss / ArenaSK — 多智能体自主开发系统 + AI Skill 竞技平台。Node.js + Claude CLI 驱动，提供 Agent 协作（公司 / OKR / 招聘 / Pipeline / Task Timeline）与 Skill 市场 / Arena 评测两套能力。 + +> 品牌历史：项目早期叫 ArenaSK（Skill 竞技场），现演进为 LemonBoss（多 Agent 公司体）。两个名称在代码中并存属正常现象。 ## 快速启动 ```bash -# 安装 -npm install && cd server && npm install && cd ../web && npm install +# 一次性安装 + 拷贝 .env.example +npm run setup -# 开发模式 (前后端分离) -npm run dev -# 后端: localhost:3000 | 前端: localhost:5173 +# 开发模式（前后端分离，跑完整 ArenaSK + LemonBoss） +npm run dev # 后端 server/index.js:3010 + 前端 vite:5173 -# 生产启动 -bash start.sh +# 仅 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: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 配置目录 +# 启动 +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 "" # bin 入口 → server/src/cli/auto-dev.js ``` ## 架构 ### 技术栈 -- **后端**: Node.js + Express + WebSocket + SQLite (better-sqlite3) -- **前端**: Vue 3 + Vite + vue-router + vue-i18n (6 语言) -- **数据**: SQLite FTS5 全文搜索, 无 PostgreSQL -- **AI**: Claude CLI (本地进程) -- **包管理**: pnpm workspace (monorepo) +- **后端**：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` | 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 等) | +| `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 搜索/下载 | -| `/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) +| `/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) | -| `server/config.js` | 服务器配置 | +| `.env` | 端口、CORS、`OPEN_API_KEYS`、各类目录覆盖；由 `npm run setup` 从 `.env.example` 生成 | +| `server/config.js` | 端口（默认 3010）、CORS、Skill / Conversations 路径 | | `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` 配置 +- 生产环境只跑 `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`，写入受限路径前自己评估风险。 > [!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` -- libgit2 0.21.4