# 架构（ARCHITECTURE.md）

> 持久对话 MCP 插件的完整技术架构

---

## 1. 整体拓扑

```
┌────────────────────┐
│   Trae / Cursor    │  IDE（SOLO Agent 窗口）
│   (MCP client)     │
└─────────┬──────────┘
          │ stdio JSON-RPC
          │ 4 tools: init / select / wait / merge
          ▼
┌────────────────────┐
│  ensure-hub.sh     │  stdio → HTTP 桥接
│  (MCP server)      │
└─────────┬──────────┘
          │ HTTP (13458)
          ▼
┌────────────────────┐
│   hub.js (主)      │  ┌─ 远端主链: 192.168.110.101:13458
│   Node 22 + HTTP   │  └─ 本地兜底: 127.0.0.1:13458
└─────────┬──────────┘
          │ 短轮询（10s）
          ▼
┌────────────────────┐
│   sessions.json    │  持久化层
│   bindings.json    │  - sessions: ct_xxx → 状态
│   plan-bindings    │  - bindings: workspace::title@ip → ct_
│   thread-bindings/ │  - plan: planName → ct_
└────────────────────┘  - thread: threadId → ct_

        ↓ 周期同步（可选）
┌────────────────────┐
│   MongoDB          │  远端数据库
│   karuo_site       │  (port 27017)
└────────────────────┘
```

---

## 2. 核心数据流

### 2.1 初始化

```
Agent → init_conversation(cursorTitle=标签, newPlan=true, planLabel=xxx)
  → ensure-hub.sh → POST /api/init
  → hub.js 创建 session（ct_xxx）
  → 写入 sessions.json
  → 写 binding：workspace::title@ip → ct_xxx
  → 返回 { token: ct_xxx, status: holding }
```

### 2.2 选择已有

```
Agent → select_conversation(token=ct_xxx, cursorTitle=标签)
  → ensure-hub.sh → POST /api/select
  → hub.js 验证垂直绑定（workspace::title@ip 三件指纹）
  → 不匹配 → 403 BINDING_REJECTED
  → 匹配 → 复用 session
```

### 2.3 真挂起

```
Agent → wait_for_user_input(token, message, timeout)
  → ensure-hub.sh → POST /api/wait/register
  → hub.js 设置 session.status = "waiting"
  → 注册到 pendingWaits[token]
  → 长连接（短轮询 10s 续约）
  → 收到 reply：
       a. 用户发消息 → deliverReply → 返回
       b. timedReply 触发（10s 间隔）→ deliverReply("保活续跑") → 返回
       c. POLL_TIMEOUT_MS=10s → renewal → 继续轮询
  → Agent 端按 status 决定：
       - "replied" → 返回 text
       - "renewal" → 继续 poll
       - "gone" → 重新 register
```

### 2.4 合并

```
Agent → merge_conversation(fromToken, toToken, cursorTitle)
  → ensure-hub.sh → POST /api/merge
  → hub.js 把 fromToken 的 messages 追加到 toToken
  → fromToken 标记 archived
  → 增量保存 sessions.json
```

---

## 3. 垂直绑定

### 3.1 绑定指纹

```
bindingKey = `${workspace}::${cursorTitle}@${hostIp}`
```

示例（默认公示用主链 IP）：
```
/Users/karuo/Documents/个人::持久对话永久续跑-20260626@192.168.110.101
```

### 3.2 验证时机

| 触发 | 验证 |
|:---|:---|
| `select_conversation` | 严校验（必须完全匹配） |
| `init_conversation` | 宽校验（可换 title 重新绑定） |
| `wait_for_user_input` | 中校验（容许 title 改名） |
| `merge_conversation` | 严校验（不匹配拒绝） |

### 3.3 改标签自动迁移

```javascript
// 用户在 Trae 改了标签 "A" → "B"
// wait 时传入新 title "B"
// hub.js 检测到旧 binding 有 token，旧 bindingKey 不匹配
// 允许迁移：把 bindingKey 改成新值，token 复用
```

---

## 4. session 状态机

```
   init
    │
    ▼
  holding ──────┐
    │            │ (每 10s 续约 / 接收新消息)
    │            │
    ▼            │
  waiting ───────┤
    │            │
    │ (用户发消息)│
    ▼            │
  replied ───────┘
    │
    │ (autoStreak 累加)
    ▼
  running
    │
    │ (merge / 结束持久对话)
    ▼
  merged / archived
```

---

## 5. autoStreak 与 keepAlive

### 5.1 概念

- `autoStreak`：连续"用户不发消息"的轮次计数
- `keepAlive`：Hub 在 autoStreak 超阈值时主动推"保活续跑"消息

### 5.2 真挂起模式（推荐）

```json
POST /api/session/config
{
  "sessionAutoContinue": false,
  "timedReplyEnabled": false,
  "timedReplyIntervalMs": 0
}
```

**效果**：
- 关闭 timedReply → 不会主动推"保活续跑"
- 关闭 autoContinue → 不会因为 idle 触发续跑
- wait 唯一返回源 = 用户真消息
- MCP 工具调用一直阻塞，agent turn 不会结束

### 5.3 自动模式（不推荐，会顶回 wait）

```json
{
  "sessionAutoContinue": true,
  "timedReplyEnabled": true,
  "timedReplyIntervalMs": 10000
}
```

**效果**：
- 每 10s 推"保活续跑"
- wait 立即返回
- agent turn 结束（UI 显示"任务完成"）

---

## 6. 短轮询 vs 长连接

| 方案 | 优点 | 缺点 | 采用 |
|:---|:---|:---|:---|
| 短轮询（10s） | 简单、跨网段友好、稳 | 续约频繁 | ✅ |
| WebSocket | 实时、省资源 | 需配 wss、断线重连复杂 | ❌ |
| Server-Sent Events | 单向实时 | 不支持双向 | ❌ |
| Long Polling | 接近实时 | 服务器维护成本 | ❌（短轮询已够） |

短轮询间隔：`POLL_TIMEOUT_MS = 10000`（10s），可在 `hub.js` 改。

---

## 7. 数据持久化

### 7.1 文件布局

```
~/.persistent-chat-local/
├── sessions.json              # 主 session 数据
├── bindings.json              # workspace::title@ip → ct_
├── plan-bindings.json         # planName → ct_
├── thread-bindings/           # threadId → ct_  (mkdir)
├── archive/                   # 归档 session
│   └── 2026-06/
│       └── ct_xxx.json
├── replies/                   # 历史用户回复缓存
├── logs/
│   ├── hub.log                # Hub 主日志
│   ├── launchd.log            # macOS launchd 日志
│   └── launchd.err
├── templates/                 # 面板模板
├── server.js                  # MCP server（41KB）
├── hub.js                     # Hub 主服务（89KB）
├── panel.html                 # 浏览器面板（84KB）
├── cursor-title.js            # 标签解析器（4KB）
├── ensure-hub.sh              # 启动器
└── mongo_sync.py              # → MongoDB 同步
```

### 7.2 sessions.json 格式

```json
{
  "ct_xxxx": {
    "token": "ct_xxxx",
    "title": "永久续跑三段式",
    "displayTitle": "",
    "status": "holding",
    "workspace": "/Users/karuo/Documents/个人",
    "createdAt": 1782448693854,
    "lastActiveAt": 1782449356228,
    "msgCount": 10,
    "autoStreak": 1,
    "bindingKey": "/Users/karuo/Documents/个人::标签@192.168.110.101",
    "hostIp": "192.168.110.101",
    "hub": "192.168.110.101:13458",
    "bindingCheckCount": 17,
    "continueMode": "optimize",
    "sessionAutoContinue": false,
    "timedReplyEnabled": false,
    "timedReplyIntervalMs": 0,
    "messages": [
      { "role": "user", "content": "...", "at": 1782448794716, "auto": false },
      { "role": "assistant", "content": "...", "at": 1782449116363, "auto": false }
    ],
    "lastReview": {
      "hasReview": false,
      "completionPct": null,
      "nextStep": "",
      "isIdleNext": true
    }
  }
}
```

### 7.3 周期保存

- 每次 register / deliverReply / merge 后 `saveSessions()`
- 写盘：原子 rename（先写 .tmp，再 rename）
- 加载：启动时一次 loadSessions()，之后只内存操作

---

## 8. 与 MongoDB 同步（可选）

`mongo_sync.py` 把 sessions.json 周期同步到 MongoDB `karuo_site.sessions`：

```python
# 触发
python3 mongo_sync.py
# 或 cron 每 5 分钟
*/5 * * * * cd ~/.persistent-chat-local && python3 mongo_sync.py
```

用途：
- 多机同步（局域网内多 Hub）
- 长期归档（超过 1000 个 session 不卡）
- 跨平台（Mac / NAS / Linux）

---

## 9. 安全性

| 维度 | 措施 |
|:---|:---|
| 端口 | 13458 默认仅 LAN 监听，不暴露公网 |
| 鉴权 | 垂直绑定（三件指纹），无 token → 拒绝 |
| 数据 | sessions.json 落在 ~/.persistent-chat-local/，权限 600 |
| 跨网段 | 靠 SSH 隧道 / VPN |
| 日志 | 不记录用户隐私内容（只记 metadata） |
| 卡密激活 | **已删除**（v1.6.37 不再有 license 校验） |

---

## 10. 性能

| 指标 | 值 |
|:---|:---|
| Hub 内存 | ~50MB（1000 个 session） |
| Hub CPU | < 1%（空闲） |
| 单 session 占内存 | ~5KB（仅 metadata） |
| 单消息占内存 | ~1KB |
| 短轮询带宽 | ~1KB/10s/session |
| 启动时间 | < 1s（Node 22） |
| sessions.json 加载 | 10000 个 session < 500ms |

---

## 11. 版本演进

| 版本 | 日期 | 关键变化 |
|:---|:---|:---|
| v1.1 | 2025-12 | 初版（仅 hub.js） |
| v1.5 | 2026-03 | 加 server.js / MCP 4 工具 |
| v1.6.30 | 2026-05 | autoStreak / timedReply |
| v1.6.37 | 2026-06-07 | **删除卡密激活** / 加 MongoDB 同步 |
| v1.6.68 | 2026-06-20 | 本地增强（VSIX 4.6 兼容） |

---

> 最后更新：2026-06-26 · 卡若AI