CLAUDE.md

项目概述

LemonACP — Claude Code ACP 调用内核。通过 ACP 协议驱动本地 Claude CLI 进程，提供单 Agent 执行和 Master → Sub-Agent 多轮编排能力。Node.js + Express，无数据库依赖。

快速启动

npm install
cp .env.example .env
node server/index.js        # 端口 3010（server/config.js 配置）

架构

技术栈

• 后端：Node.js (≥18) + Express
• AI：Claude CLI（本地子进程，--dangerously-skip-permissions 自动批准）
• 包管理：pnpm workspace（monorepo）

目录速查

目录	说明
packages/acp-core/	ACP 协议层：Protocol / Transport / Launcher 抽象 + ClaudeCliProtocol
packages/agent-core/	Agent 运行时：目录驱动的 Agent、AgentBus、AgentRegistry、AgentScaffold
server/index.js	Express 入口（2 个路由：/api/master + /api/config）
server/src/core/	编排引擎：orchestrator、master-session、agent-manager、scheduler、session-pool、stream-executor、parser、prompt-builder
server/src/engine/	进程层：command-queue、process-guard、idle-timer、run-registry、failover-error
server/src/tools/	Master 工具：call-agent-tool、tool-registry
server/src/standalone-entry.js	编程 API 入口：runMasterSession / runOrchestration / runSingleAgent
server/routes/master-chat.js	SSE 流式对话路由（主入口）
server/routes/config.js	配置文件读写路由
server/services/	conversation-logger、file-parser、memory-service、claude-chat-service
server/config/backends.json	ACP Launcher / Client 配置
server/config/agents.json	（可选）静态 Agent 定义

API 路由

路径	说明
POST /api/master/chat	Master Agent 多轮对话（SSE）
POST /api/master/upload	文件上传注入对话
GET /api/master/sessions	列出活跃 session
DELETE /api/master/sessions/:id	关闭 session
GET /api/config/items	列出配置项
GET/PUT /api/config/items/:key	读写配置文件
GET /api/health	健康检查

配置文件

文件	说明
.env	PORT、CORS_ORIGINS 等环境变量；由 cp .env.example .env 生成
server/config.js	端口（默认 3010）、CORS、目录路径
server/config/backends.json	ACP Launcher 定义（command、args、protocol）
server/config/agents.json	静态 Agent 注册表（可选，也可由 system/agents/ 目录发现）

注意事项

• Claude CLI 进程默认带 --dangerously-skip-permissions，写入受限路径前自己评估风险。
• server/src/standalone-entry.js 的 loadConfig() 优先读 server/config/backends.json + server/config/agents.json，无需数据库。
• Agent 记忆存储在 Agent 目录的 memory/ 子目录，纯文件系统，无 SQLite 依赖。
• prompt-builder.js 的 getSystemStateXML() 只返回时间戳（公司/OKR 层已移除）。

!WARNING Master Agent 必读: 当你试图在 Bash tool 中使用带有多重双引号的复杂命令（例如 curl -d '{"id":"lemonv"}'）时，JSON 转义容易崩溃陷入死循环。 解决方案: 任何需要提交 JSON Payload 的操作，先写入 /tmp/*.json 文件，再通过 curl -d @/tmp/payload.json 发送。