# CLAUDE.md

## 项目概述

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

## 快速启动

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