# CLAUDE.md

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

## 项目概述

**lemonPCRM** — lemonAI 出品的 Local-First AI 个人人脉管理系统（Personal CRM）。以人为中心、以对话为链接，通过知识图谱管理微信、LinkedIn、X 等多平台社交关系，将每个联系人与其社媒动态、会议纪要、文件、照片全面关联。

AI 对话与编排层基于 ACP 协议驱动本地 Claude CLI 进程，提供单 Agent 执行和 Master → Sub-Agent 多轮编排能力。Node.js + Express，无数据库依赖，数据完全本地化。

## 常用命令

```bash
npm run setup        # 首次初始化：cp .env.example .env + npm install
npm start            # 生产模式（node server/index.js）
npm run dev          # 开发模式（node --watch server/index.js，热重载）
```

无测试框架，无 lint 脚本。

## 架构

### 技术栈
- **后端**：Node.js (≥18) + Express，pnpm workspace monorepo
- **AI**：Claude CLI（本地子进程，`--dangerously-skip-permissions` 自动批准）
- **文件解析**：mammoth（.docx）、pdf-parse（.pdf）

### 目录速查

| 目录 | 说明 |
|------|------|
| `packages/acp-core/` | ACP 协议层：Protocol / Transport / Launcher 三层抽象 + ClaudeCliProtocol / AcpProtocol |
| `packages/agent-core/` | Agent 运行时（ESM）：目录驱动的 Agent、AgentBus、AgentRegistry、AgentScaffold |
| `server/index.js` | Express 入口（路由：`/api/master` + `/api/config` + `/api/health`） |
| `server/src/core/` | 编排引擎：orchestrator、master-session、agent-manager、session-pool、stream-executor、prompt-builder、parser、runtime-resolver |
| `server/src/engine/` | 进程层：run-registry、command-queue、process-guard、idle-timer、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/services/` | conversation-logger、file-parser、memory-service、claude-chat-service |
| `server/config/backends.json` | ACP Launcher / Client 定义 |
| `server/config/agents.json` | 静态 Agent 注册表（可选，也可由 `system/agents/` 目录发现） |

### API 路由

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

### 配置文件

| 文件 | 说明 |
|------|------|
| `.env` | PORT（默认 3010）、HOST、CORS_ORIGINS 等 |
| `server/config.js` | 端口、CORS、目录路径的运行时配置对象 |
| `server/config/backends.json` | ACP Launcher 定义（command、args、protocol） |
| `server/config/agents.json` | 静态 Agent 注册（可选） |

## 关键架构模式

### ACP 协议四层结构

```
Application (AgentManager)
    ↓
Protocol  (ClaudeCliProtocol 直接 spawn / AcpProtocol JSON-RPC)
    ↓
Transport (ProcessTransport stdio / PipeTransport / WebSocketTransport)
    ↓
Launcher  (ProcessLauncher spawn / NoneLauncher 无操作)
```

`runtime-resolver.js` 根据 `backends.json` + `agents.json` 配置自动推断使用哪一层。

**ClaudeCliProtocol 调用方式**：
- 生成命令：`claude --input-format stream-json --output-format stream-json --verbose --include-partial-messages --dangerously-skip-permissions`
- 输入格式：`{"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}`
- 输出：NDJSON 事件流
- 单进程跨多轮复用（session reuse）

**Mock 模式**：设置 `LEMONBOSS_CLAUDE_MODE=mock` 可读取 fixture 文件而不启动真实进程，用于调试。

### Master → Sub-Agent 调度流程

1. 用户消息 → `MasterSession.handleMessage()`
2. `PromptBuilder` 组装系统提示（含工具描述 + 可用 Agent 列表）
3. Claude 响应中的工具调用用 `[TOOL_CALL: tool_name] {...json...} [/TOOL_CALL]` 格式标记
4. `ToolRegistry.parseToolCalls()` 解析后交给 `AgentManager.callAgent()`
5. `SessionPool` 按 `agentName:client:deploy:workDir[:scope]` 为 key 复用已有 session
6. 工具结果注回对话，最多循环 10 轮（`SAFETY_MAX_LOOPS=15`）

**Orchestrator** 额外提供格式自动修正（`MAX_REPAIRS=5`）与结果验证（`ResultTracker`）。

### Agent 发现与记忆

- Agent 优先从 `system/agents/` 目录发现（目录驱动），`agents.json` 作为静态补充
- 每个 Agent 的记忆存储在其目录下的 `memory/` 子目录，纯文件系统
- `AgentScaffold` 用于创建新 Agent 目录结构

## 注意事项

- `server/src/standalone-entry.js` 的 `loadConfig()` 优先读 `backends.json` + `agents.json`，无需数据库。
- `prompt-builder.js` 的 `getSystemStateXML()` 只返回时间戳（公司/OKR 层已移除）。
- Agent 目录内放 `SKILL.md` 文件会绕过协议封装，直接作为系统提示使用。

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