CLAUDE.md 5.47 KB

Edit Raw Blame History


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，无数据库依赖，数据完全本地化。
常用命令
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 调度流程

用户消息 → MasterSession.handleMessage()
PromptBuilder 组装系统提示（含工具描述 + 可用 Agent 列表）
Claude 响应中的工具调用用 [TOOL_CALL: tool_name] {...json...} [/TOOL_CALL] 格式标记
ToolRegistry.parseToolCalls() 解析后交给 AgentManager.callAgent()
SessionPool 按 agentName:client:deploy:workDir[:scope] 为 key 复用已有 session
工具结果注回对话，最多循环 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
Master Agent 必读：在 Bash tool 中使用含多重双引号的复杂命令（如 curl -d '{"id":"lemonv"}'）时，JSON 转义容易崩溃并陷入死循环。
解决方案：任何需要提交 JSON Payload 的操作，先写入 /tmp/*.json 文件，再通过 curl -d @/tmp/payload.json 发送。