# lemonPCRM 分阶段开发计划

> 基于 [lemonPCRM.md](./lemonPCRM.md) 产品需求 + [user-flow.md](./user-flow.md) 用户流程制定。
> 目标：以最小可用单元逐步落地，每阶段交付可独立运行的功能切片。

---

## 总体架构回顾

```
[前端 HTML — 联系人列表 + 五标签画布]
        ↕ SSE / REST
[server — ACP 编排引擎]  ← 已有基础
        ↕ 工具调用
[MCP 工具箱]  ← 待构建
        ↕
[本地知识图谱 (Kùzu / SQLite)]  ← 待构建
```

---

## Phase 0｜地基夯实（已完成）

**目标**：确认现有 ACP 内核可稳定驱动 Claude CLI，作为后续所有阶段的底座。

| 任务 | 说明 | 状态 |
|------|------|------|
| ACP 协议层 | ClaudeCliProtocol + SessionPool + AgentManager | ✅ 完成 |
| SSE 对话路由 | `/api/master/chat` 多轮流式对话 | ✅ 完成 |
| 文件上传解析 | .docx / .pdf 注入对话上下文 | ✅ 完成 |
| 配置体系 | backends.json / agents.json / .env | ✅ 完成 |

**交付物**：可通过 `curl` 发起多轮 AI 对话，文件内容可注入上下文。

---

## Phase 1｜本体论数据层（第 1 个月）

**目标**：建立知识图谱数据模型，提供基础 CRUD 能力，AI 可通过工具写入/查询。

### 1.1 选型与初始化

- 使用 **Kùzu**（本地嵌入式图数据库，无服务进程）或 SQLite + JSON 图扩展
- 在 `server/db/` 目录初始化数据库，提供统一的 `GraphStore` 模块

### 1.2 核心本体模型

```
节点（Node）
├── Person        id, name, alias[], avatar, notes, analysisStatus, createdAt
├── Organization  id, name, type, domain
├── Project       id, name, status, description
├── Event         id, type(chat/meeting/post), date, summary, rawText
└── Asset         id, type(photo/video/doc), filePath, mimeType, vectorId

边（Edge）
├── Person  --[KNOWS]-->        Person       (channel, since)
├── Person  --[BELONGS_TO]-->   Organization (role, since)
├── Person  --[PARTICIPATED]--> Event
├── Event   --[CONTAINS]-->     Asset
├── Person  --[MENTIONED_IN]--> Event
└── Person  --[ASSOCIATED]-->   Project
```

`analysisStatus` 字段驱动前端联系人状态：`none` / `partial` / `complete`（对应 ⚪🔵🟢）

### 1.3 MCP 工具箱 v1（基础图操作）

在 `server/src/tools/graph/` 实现以下工具，供 Master Agent 调用：

| 工具名 | 功能 |
|--------|------|
| `create_person(name, meta)` | 创建 Person 节点 |
| `get_person(name_or_id)` | 查询 Person 及其所有关联边 |
| `link_persons(a, b, relation, meta)` | 建立两人之间的关系边 |
| `create_event(type, date, summary, persons[])` | 创建事件并关联参与者 |
| `search_graph(query)` | 全文 + 属性模糊搜索 |
| `get_relationship_path(a, b)` | 找两人之间的最短关系路径 |

**交付物**：可通过 AI 对话完成人脉节点的增删改查；`curl /api/master/chat` 说"新增联系人张三，来自字节跳动"即可写入图谱。

---

## Phase 2｜微信联系人导入（第 2 个月）

**目标**：将微信作为第一个数据源，批量导入联系人和聊天记录，为前端提供真实数据。

### 2.1 微信数据读取

实现 `server/services/wechat/` 模块，支持两种导入方式：
- **手动导出**：解析微信 PC 端导出的 CSV / JSON 联系人文件
- **本地数据库**（进阶）：读取 `EnMicroMsg.db`（需用户自行解密提供）

### 2.2 数据清洗与入图

```
原始微信联系人 → NLP 实体清洗 → Person 节点写入 → 关系边推断
```

- 调用 `extract_entities_from_text()` 工具让 AI 从备注/标签中推断关系
- 去重策略：以微信 ID 为主键，姓名 / 手机号辅助合并
- 写入后设置 `analysisStatus = partial`

### 2.3 聊天记录导入

- 解析聊天记录 txt/html 导出文件
- 每段对话创建 `Event:ChatSession` 节点，关联发言人
- AI 自动提取对话中提及的第三方人名、公司、项目，扩充图谱

**交付物**：微信通讯录和聊天记录完整入图；联系人列表有真实数据，状态为 ⚪ 或 🔵。

---

## Phase 3｜前端主界面 + 档案激活流程（第 2–3 个月）

**目标**：构建本地 HTML 单页应用，实现「搜索联系人 → 点击激活 → 多维画布」的完整主流程。

### 3.1 技术选型

- **图渲染**：AntV G6（关系图谱画布专用）
- **框架**：原生 HTML + Vanilla JS（Local-First，零构建工具依赖）
- **通信**：SSE 接收 AI 分析输出，REST 查询图谱数据

### 3.2 页面布局

```
┌────────────────────────────────────────────────────────┐
│  lemonPCRM                                 [设置] [同步] │
├──────────────────────────┬─────────────────────────────┤
│  搜索（姓名/公司/标签）    │  [档案][图谱][时间轴]         │
│                           │  [对话洞察][AI报告]           │
│  联系人列表                │                             │
│  🟢 张三  字节跳动         │     ← 右侧五标签画布区        │
│  🔵 李四  OpenAI          │                             │
│  ⚪ 王五  （未激活）        │                             │
└──────────────────────────┴─────────────────────────────┘
```

### 3.3 档案激活流程（核心交互）

点击联系人后触发 AI 并发分析，右侧实时显示进度：

```
✅ 微信通讯记录读取完成
✅ 图谱基础数据加载完成
🔄 LinkedIn 数据匹配中...
⏳ 对话内容分析（等待中）
```

新增 MCP 工具支撑激活流程：

| 工具名 | 功能 |
|--------|------|
| `activate_contact_profile(personId)` | 触发全量聚合分析，以 SSE 返回进度流 |
| `get_conversation_insights(personId)` | 统计对话话题分布、承诺事项、关系温度 |
| `generate_profile_report(personId)` | 生成结构化 Markdown 分析报告 |

### 3.4 五个画布标签

| 标签 | 核心内容 |
|------|---------|
| 📋 档案视图 | 联系方式、性格与沟通风格、职业轨迹、与我的关系描述 |
| 🕸️ 关系图谱 | 以此人为中心的 G6 关系网络，支持节点下钻跳转 |
| 📅 时间轴 | 微信 + 会议纪要的互动事件时序，支持按类型筛选 |
| 💬 对话洞察 | 话题分布图、待跟进承诺事项、关系热度趋势 |
| 🤖 AI 报告 | 一键生成可导出 Markdown 的结构化人脉分析报告 |

所有标签右下角均常驻 AI 对话框（SSE 流式）。

**交付物**：`/frontend/index.html` 可直接浏览器打开；点击任意联系人后 5 个画布均可用；AI 对话框可对当前联系人随时追问。

---

## Phase 4｜多源数据接入（第 3–4 个月）

**目标**：接入 LinkedIn、X（Twitter）等平台数据，丰富每个 Person 节点的数字画像，让档案视图更完整。

### 4.1 LinkedIn 数据导入

- 解析 LinkedIn 官方数据导出包（`Connections.csv`、`Messages.csv`）
- 合并到现有 Person 节点，补充职位 / 公司 / 教育背景

### 4.2 X（Twitter）动态关联

- 通过 X API v2 或本地导出的 `tweets.js` 解析用户动态
- 每条推文创建 `Event:Post` 节点，AI 提取高频话题标签
- 定期摘要：*"该联系人近 30 天在 X 上高频词：#AI #创业"*

### 4.3 会议纪要自动处理

- 集成 **Whisper**（本地语音转文字）：音频文件 → Markdown 纪要
- 会议纪要作为 `Event:Meeting` 节点入图，AI 提取参与者和提及的第三方
- 支持通过 `/api/master/upload` 直接上传音频/纪要文件

### 4.4 MCP 工具箱 v2（多源数据）

| 工具名 | 功能 |
|--------|------|
| `import_linkedin_export(filePath)` | 解析 LinkedIn 导出包 |
| `import_x_timeline(userId, data)` | 导入 X 用户动态 |
| `transcribe_audio(filePath)` | Whisper 本地转写 |
| `import_meeting_notes(text, participants[])` | 会议纪要入图 |

**交付物**：档案视图和对话洞察标签中出现 LinkedIn + X + 会议纪要的多维数据；联系人 `analysisStatus` 升为 🟢 complete。

---

## Phase 5｜AI 深度分析能力（第 4–5 个月）

**目标**：在完整图谱数据基础上，提供超越单人视角的跨网络洞察能力。

### 5.1 关系路径分析

> "我和王总没有直接关系，帮我找最短关系链"

- 调用图算法（BFS/Dijkstra）计算最短路径
- AI 用自然语言解释路径：*"你 → 张三（前同事）→ 李四（LinkedIn 好友）→ 王总"*

### 5.2 圈子识别（Community Detection）

- 运行 Louvain 社区发现算法，自动识别人脉圈子
- 在图谱画布上用不同颜色区域标注圈子（如"AI 创业圈"、"前公司同事圈"）

### 5.3 跟进提醒 Agent

- 后台定时 Agent，扫描"超过 N 天未互动"的重要联系人
- 生成跟进建议：*"张三 60 天未联系，上次聊到他在看新机会，建议主动询问近况"*
- 前端首页展示提醒卡片

**交付物**：关系图谱画布展示圈子色块；首页出现跟进提醒；可查询任意两人之间的关系路径。

---

## Phase 6｜多模态资产关联（第 5–6 个月，可选）

**目标**：将本地照片/视频与人脉图谱关联，实现多模态检索。

### 6.1 人脸识别关联

- 集成 `face_recognition`（Python 本地库）扫描相册
- 匹配到已知联系人后，照片作为 `Asset:Photo` 节点挂载到对应 Person
- 在档案视图的「关联资产」区域展示

### 6.2 多模态向量化

- 使用 CLIP 模型提取图片语义向量，存入向量索引（如 `hnswlib`）
- 支持语义搜索：*"找出所有和张三在户外的照片"*

### 6.3 时空轨迹重现

- 在时间轴画布集成地图组件（Leaflet.js）
- 根据照片 EXIF、会议地点等数据，可视化联系人的时空轨迹

**交付物**：照片/视频可与人脉节点关联；时间轴画布增加地图视角；支持自然语言多模态检索。

---

## 里程碑汇总

| 阶段 | 时间 | 核心交付 |
|------|------|---------|
| Phase 0 | 完成 | ACP 编排内核可用 |
| Phase 1 | 第 1 个月 | 知识图谱数据层 + 基础 MCP 工具 |
| Phase 2 | 第 2 个月 | 微信联系人 & 聊天记录入图 |
| Phase 3 | 第 2–3 个月 | 前端主界面 + 档案激活 + 五标签画布全通 |
| Phase 4 | 第 3–4 个月 | LinkedIn / X / 会议纪要多源数据接入 |
| Phase 5 | 第 4–5 个月 | 关系路径分析、圈子识别、跟进提醒 Agent |
| Phase 6 | 第 5–6 个月 | 多模态照片关联（可选扩展） |

---

## 开发原则

- **Local-First**：每个 Phase 的数据和计算全部在本地完成，不依赖云 API
- **主流程优先**：Phase 3 之前必须打通「搜索 → 点击 → 激活 → 五画布」完整链路
- **AI 驱动数据写入**：图谱更新优先通过自然语言对话触发，避免手动 UI 表单
- **向后兼容**：每阶段新增工具不破坏现有 ACP 编排接口