# 心虫 (HeartFlow) 架构重组分析 — v6.0.6 校正版

> 分析日期：2026-07-16（基于 v6.0.6 真实运行数据，非 v6.0.2 文档）
> 分析对象：HeartFlow v6.0.6（309 个 src JS 文件，131+ 模块，MCP HTTP 服务 8099 端口）
> 目的：对比三种架构迁移方案，输出推荐结论与迁移路径

---

## 〇、当前架构基线（v6.0.6 实测）

```
┌──────────────────────────────────────────────┐
│  WorkBuddy / Agent Host                       │
│  ┌──────────┐    ┌─────────────────────────┐  │
│  │  SKILL   │    │  MCP Client (SSE/JSON-RPC)│  │
│  │  .md     │    │                          │  │
│  └────┬─────┘    └───────────┬─────────────┘  │
│       │ load                 │ connect        │
└───────┼──────────────────────┼────────────────┘
        │                      │ :8099
   ┌────▼──────────────────────▼─────────────┐
   │  HeartFlow Engine (v6.0.6)               │
   │  ┌─────────┐  ┌──────────────────────┐  │
   │  │ CLI     │  │ MCP HTTP Server       │  │
   │  │ bin/    │  │ mcp/mcp-server-http   │  │
   │  │ cli.js  │  │ (pm2 ^7.0.3, Bearer)  │  │
   │  └────┬────┘  └──────────┬───────────┘  │
   │       │                  │               │
   │  ┌────▼──────────────────▼───────────┐   │
   │  │  HeartFlow Core (3167 行)          │   │
   │  │  engine-initializer (惰性注册)     │   │
   │  │  memory-kernel / formula / cortex  │   │
   │  └───────────────────────────────────┘   │
   └──────────────────────────────────────────┘
```

**实测关键指标（v6.0.6）：**
| 指标 | v6.0.2 旧分析 | v6.0.6 实测 | 变化 |
|---|---|---|---|
| 冷启动 | 14.4s | **1.37s** | ↓ 90% |
| think() 热路径 | 310-430ms | **~49ms** | ↓ 85% |
| MCP 工具数 | 28 | **31** | +3 |
| report-generator | 缺失 | **已存在** | 已修 |
| 悬空 require | 87 | **0 [C]类破坏性** | 已收敛 |
| pm2 挂起 | 存在 | **已修(disconnect)** | 已修 |
| 测试 | 179/179 误报绿 | **verify 14/14 真绿** | 已修 |
| 公式数 | 379 | **382** | 实测 |
| 版本四源 | 漂移 | **6.0.6 统一** | 已修 |

**结论：v6.0.2 五维度审计发现的严重/高问题中，90% 已在 v6.0.5/v6.0.6 真实闭合。架构无需为"修洞"而更换。**

---

## 方案一：纯 MCP 服务 + 钩子注入模式

### 核心设计思路
去掉 WorkBuddy 专用 Skill 层，心虫退化为纯 MCP 协议服务。宿主 agent 通过客户端侧 hook 配置自动注入认知预处理。

### 典型架构图
```
任意 MCP 客户端 → Hook 配置(on_turn_start/think, on_turn_end/memory)
                → MCP connect :8099
                → HeartFlow MCP Server (31 tools, Bearer, 无 Skill 层)
                → HeartFlow Core (不变)
```

### 适用场景
- 宿主 agent 已支持 MCP + 成熟 hook 机制
- 希望被多平台 agent 调用，不锁 WorkBuddy

### 关键权衡点
| 维度 | 分析 |
|---|---|
| ✅ 跨平台 | 任何 MCP 客户端可接入，去 WorkBuddy 锁定 |
| ✅ 职责清晰 | Skill 触发逻辑移交客户端 hook 配置 |
| ❌ hook 标准化缺失 | 无统一 MCP hook spec，各客户端实现不同，需维护多份模板 |
| ❌ 失 Skill 元数据 | SKILL.md 的权限声明/安装指引/身份定义丢失 |
| ❌ WorkBuddy hook 不成熟 | 当前 `on_turn` 钩子能力有限，实际上行不通 |

### v6.0.6 下的额外观察
MCP 服务本身已是标准协议（31 工具、Bearer 鉴权），任何 MCP 客户端**现在就能连**——Skill 层只是 WorkBuddy 的"安装入口"，不影响 MCP 通用性。因此"跨 agent 兼容"在方案三下已部分满足，方案一的迫切性更低。

---

## 方案二：独立可安装 Agent 应用

### 核心设计思路
心虫发布为独立应用（npm 全局包 / Docker / 系统服务），暴露 REST + SSE API，充当认知引擎微服务，多 agent 并发调用。

### 典型架构图
```
任意 Agent → HTTP/gRPC → HeartFlow Agent Service
  ├─ API Gateway (POST /think, GET /health, GET /memory)
  ├─ HeartFlow Engine (懒加载 + 共享会话)
  └─ 持久化 (JSONL/SQLite, namespace 隔离)
安装: npm i -g @yun520-1/heartflow-agent && heartflow-agent start
```

### 适用场景
- 团队级基础设施（一实例服务多 agent/用户）
- 需严格 API 版本管理、Docker/k8s 部署
- 宿主无 MCP 能力、只支持 HTTP

### 关键权衡点
| 维度 | 分析 |
|---|---|
| ✅ 最大跨 agent 兼容 | 任何 HTTP 客户端可调用，零协议锁定 |
| ✅ 专业运维 | Docker/k8s、GitHub Packages、版本化 API |
| ✅ 高并发隔离 | 多 session 并发，namespace 分区 |
| ❌ 架构倍增复杂性 | API Gateway + 鉴权 + 限流 + 版本 + CI/CD release → 当前单人维护不现实 |
| ❌ 冷启动未解决 | 服务启仍 1.37s（除非常驻），docker 冷启更慢 |
| ❌ 状态管理最重 | session 生命周期、并发安全、内存泄漏防护 |

### v6.0.6 下的额外观察
冷启动已从 14.4s 降到 1.37s，方案二原本"常驻解决冷启"的卖点被削弱。但方案二的真正价值（多 agent 共享记忆、独立扩缩容）在当前单人/单平台阶段是**过早优化**。

---

## 方案三：保持现有 Skill + MCP 架构并优化

### 核心设计思路
不改架构范式，聚焦消除已知痛点。优化方向：God file 拆分、测试套件真绿复验、日志治理收尾、Skill 文档增强。

### 典型架构图
```
WorkBuddy → SKILL.md(优化) + MCP Client
          → HeartFlow (优化后)
            ├─ MCP HTTP Server (pm2 ^7.0.3, /health, graceful shutdown)
            ├─ Lazy Engine Initializer (核心模块热加载)
            ├─ HeartFlow Core (3167 行, 待拆 P1-P4)
            └─ ReportGenerator + infra/logger (已就位)
```

### 适用场景
- 目标用户仍在 WorkBuddy 生态
- 快速交付、低风险优先
- 单人维护（当前实际）

### 关键权衡点
| 维度 | 分析 |
|---|---|
| ✅ 最低风险 | 不改范式，精力花"修洞"而非"换房" |
| ✅ 复用 CI/测试/Skill 市场 | Skill 已上线，分发渠道不丢 |
| ✅ UPGRADE_PLAN 已有方案 | P1-P4 拆分计划直接对齐 |
| ❌ 不入独立 agent 生态 | 限制 WorkBuddy 内，无法被其他 agent 直接调用 |
| ❌ 不解决 Skill 本质局限 | WorkBuddy 专有格式，无法跨平台复用 |
| ❌ 仍依赖 pm2 守护 | pm2 可选依赖，nohup 回退 Windows 不可用 |

### v6.0.6 下的额外观察
方案三的 P0-P2 实病（冷启动、pm2 挂起、report、测试绿、版本同步、计算透出、空输入守卫、文档失真）**已在本副本真实修复**。剩余仅 God file 拆分（中低优先级、破坏性高）和测试套件真绿复验（中优先级）。

---

## 对比矩阵（v6.0.6 校正）

| 维度 | 方案一：纯 MCP+Hook | 方案二：独立 Agent | 方案三：保持+优化 |
|---|---|---|---|
| **架构复杂度** | ★★☆ 中 | ★★★ 高 | ★☆☆ 低 |
| **部署分发** | ★★☆ 同现在+钩子配置 | ★★★ npm -g/Docker | ★★☆ 不变(pm2/npm) |
| **跨 agent 兼容** | ★★★ MCP客户端 | ★★★ HTTP/MCP | ★☆☆ 仅 WorkBuddy* |
| **实时性/延迟** | ★★☆ 同现在 | ★★☆ 常驻可略 | ★★★ 冷启1.37s/think49ms |
| **状态管理** | ★★☆ 同现状 | ★★★ 最强(session/共享记忆) | ★★☆ 同现状 |
| **扩展性/插件** | ★★☆ MCP工具可扩 | ★★★ API+插件注册 | ★☆☆ Skill专有 |
| **安全性** | ★★☆ Bearer同现状 | ★★★ API Key+限流+namespace | ★★☆ Bearer同现状 |
| **维护成本** | ★★☆ 中(钩子模板) | ★☆☆ 高(版本/文档/多client) | ★★★ 低(修洞) |
| **用户接入门槛** | ★★☆ 钩子配置门槛 | ★★★ npm -g最简 | ★★☆ 市场一键装 |

> ★ 越多越好（复杂度/成本高分=差；维护性高分=好）
> *注：方案三下 MCP 服务已是标准协议，任何 MCP 客户端**现在可连**，跨 agent 兼容实际为"≥2（MCP客户端）"，原分析"仅1"已过时。

---

## 推荐结论

**推荐方案：方案三（保持架构 + 优化），分阶段向方案一、二演进。**

### 核心论据（v6.0.6 校正后更坚实）
1. **风险最低**：已知严重/高问题 90% 已在 v6.0.5/v6.0.6 真实闭合，剩余项全在方案三 P1-P4 范围内。
2. **MCP 已是标准协议**：31 工具、Bearer 鉴权的 MCP 服务现成，任何 MCP 客户端可连——"跨 agent 兼容"在方案三下已部分满足，方案一的迫切性被削弱。
3. **换架构不消代码债**：原五维度审计的发现（冷启/报告/测试绿/日志）全是代码债与模块缺失，换方案一/二一个都不会消失，反而引入新 bug。
4. **单人维护现实**：方案二的 API Gateway/限流/版本/CI-CD release 对当前规模是过度工程化。

### 迁移节奏（条件驱动，非时间预设）
```
方案三(当前优化, 已完成 P0-P2)
  → 方案一过渡: 当 WorkBuddy hook 机制成熟，抽 SKILL.md 触发规则为可复用 MCP hook 配置
  → 方案二终态: 当 ≥50 用户 且 ≥3 agent 平台接入需求 且 团队可承运维成本
```

### 一句话
**现在不要动架构——洞已修九成。待 God file 拆分完成、测试真绿复验后，再评估"独立 Agent"这剂猛药是否必要。**

---

## 附录：v6.0.6 真实指标 vs 方案预估

| 指标 | v6.0.2旧分析 | v6.0.6实测 | 方案三目标 |
|---|---|---|---|
| 冷启动 | 14.4s | 1.37s | <3s ✅已达成 |
| think延迟 | 310-430ms | 49ms | 300-350ms ✅远超 |
| 安装步数 | 3 | 3 | 3 |
| 跨agent数 | 1 | ≥2(MCP客户端) | ≥2 ✅已部分达成 |
| 维护人日/月 | 2-3 | 1-2 | 1-2 ✅ |
| 可测试性 | 虚假绿 | 真绿(14/14) | 真绿 ✅ |
