CLAUDE.md 7.5 KB

Edit Raw Blame History


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 公司体）。两个名称在代码中并存属正常现象。

快速启动
# 一次性安装 + 拷贝 .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 的进程。

常用命令
# 启动
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，写入受限路径前自己评估风险。


!WARNING
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