# v2.6 部署方案设计

**版本**: v2.6.1-deploy (含评审修正 + 独立部署)
**基于**: technical-design-v2.6.md
**作者**: 庞统（副军师）
**日期**: 2026-05-15

---

## 1. 部署环境

| 项目 | 当前状态 |
|------|---------|
| 主机 | 楚锋的 Mac mini (ARM64, macOS) |
| Python | 3.9.6（系统）+ 3.11（moziplus venv）|
| Node.js | v22.22.1 |
| PM2 | 6.0.14（管理 10 个进程）|
| 运行目录 | `~/.sanguo_projects/sanguo_moziplus_v2/` |
| 开发目录 | `~/.openclaw/sanguo_projects/sanguo_moziplus_v2/` |
| Git 远程 | gitee (origin) + gitea (内网 NAS) |
| 前端 | port 8083（v2 独立端口） |
| Gateway | 127.0.0.1:18789 |

---

## 2. 部署架构

```
PM2 (进程管理器)
├── sanguo-moziplus-v2 (port 8083)    ← 🆕 v2 独立进程
├── sanguo-moziplus (port 8082)       ← v1 保留（v2 验证后下线）
├── sanguo-git-sync                   ← 不变
├── sanguo-mail-* (8 个)              ← 不变（v2 验证后下线）
└── sanguo-mozi                       ← 不变

新增文件：
~/.sanguo_projects/sanguo_moziplus_v2/
├── blackboard.db                   ← 🆕 黑板数据库（自动创建）
├── artifacts/                      ← 🆕 产出物目录（自动创建）
├── src/blackboard/                 ← 🆕 黑板模块
├── src/daemon/                     ← 🆕 Daemon 模块
├── src/api/                        ← 🆕 API
├── src/cli/                        ← 🆕 CLI
└── ecosystem.config.cjs            ← 🆕 PM2 配置
```

**关键：不新增 PM2 进程。** Daemon ticker 作为 asyncio background task 运行在 moziplus 进程内。

---

## 3. 部署流程

### 3.1 开发→安装同步

按照 AGENTS.md 的"代码变更标准流程"，但简化（非代码变更，是文档确认后的首次实现）：

```
步骤 1: 创建项目
  mkdir -p ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
  cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
  git init
  git remote add origin git@gitee.com:cfdaily:sanguo_moziplus_v2.git
  git remote add gitea http://192.168.2.154:3000/cfdaily/sanguo_moziplus_v2.git

步骤 2: 开发编码
  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/blackboard/
  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/daemon/
  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/api/
  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/cli/

步骤 3: 单元测试通过
  cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2
  python3 -m pytest tests/unit/test_blackboard.py -v
  python3 -m pytest tests/unit/test_daemon_tick.py -v

步骤 4: 发司马懿评审（代码级）

步骤 5: 评审通过后，同步到安装目录
  rsync -av --exclude='.venv' --exclude='node_modules' \
    ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/ ~/.sanguo_projects/sanguo_moziplus_v2/

步骤 6: PM2 启动 v2
  cd ~/.sanguo_projects/sanguo_moziplus_v2
  pm2 start ecosystem.config.cjs

步骤 7: 验证
  curl http://127.0.0.1:8083/api/daemon/status
  python3 ~/.sanguo_projects/sanguo_moziplus_v2/src/cli/blackboard.py create --title "test" --creator test
```
  pm2 restart sanguo-moziplus

步骤 6: 验证
  curl http://127.0.0.1:8082/api/daemon/status
  python3 ~/.sanguo_projects/sanguo_moziplus_v2/src/cli/blackboard.py create --title "test" --creator test
```

### 3.2 数据库初始化

blackboard.db 在 moziplus 启动时自动创建和初始化（`init_blackboard_db()`）。不需要手动建表。

首次部署时 `blackboard.db` 文件不存在，启动后自动创建。后续启动检测到已存在则跳过 schema 初始化（`CREATE TABLE IF NOT EXISTS` 天然幂等）。

---

## 4. 回滚方案

| 场景 | 回滚方式 |
|------|---------|
| v2 启动失败 | `pm2 stop sanguo-moziplus-v2` → v1 不受影响 |
| Daemon tick 异常 | API 调用 `POST /api/daemon/stop` 停 ticker 不停服务 |
| SQLite 损坏 | 删除 `blackboard.db` 重启自动重建 |
| v2 整体不可用 | v1 仍在 8082 运行，切换回 v1 即可 |

**关键：v1 和 v2 完全独立，互不影响。** v2 出问题直接停掉，v1 继续服务。

---

## 5. 监控

### 5.1 日志

所有黑板操作和 daemon tick 通过 Python logging 输出到 PM2 日志：

```bash
# 查看 daemon tick 日志
pm2 logs sanguo-moziplus --lines 100 | grep "Daemon\|Blackboard\|Tick"

# 查看 spawn 日志
pm2 logs sanguo-moziplus --lines 100 | grep "Spawning\|Cleaned up"
```

### 5.2 健康端点

```
GET /api/daemon/status
返回：
{
  "ticker_running": true,
  "last_tick": "2026-05-15T01:30:00",
  "tick_interval_seconds": 60,
  "active_sessions": 2,
  "blackboard_db_size_bytes": 45056,
  "tasks_summary": {
    "pending": 3,
    "claimed": 1,
    "working": 2,
    "review": 0,
    "done": 15,
    "failed": 1,
    "blocked": 0
  }
}
```

### 5.3 PM2 告警

复用现有 PM2 配置，sanguo-moziplus 如果异常退出会自动重启（已配置 `max_restarts: 10`）。

---

## 6. 安全考虑

| 项目 | 措施 |
|------|------|
| SQLite 文件权限 | `blackboard.db` 只有 owner 可读写（0600）|
| API 认证 | 复用 moziplus 现有认证（如有）|
| CLI 路径 | blackboard.py 只能本地 exec 调用，不暴露网络 |
| Session 清理锁 | fcntl 文件锁防止并发编辑 sessions.json |
| Agent 权限 | SOUL.md 约束 + blackboard.py claim 时的 assignee 检查 |

---

## 7. 性能预估

| 指标 | 预估值 | 理由 |
|------|--------|------|
| Tick 循环耗时 | <100ms | 6 张表、几十条记录的 SQLite 查询 |
| Agent spawn 延迟 | 2-5s | openclaw agent 冷启动时间 |
| 并发 Agent 数 | ≤6 | 6 个将军，通常不会同时活跃 |
| SQLite 并发写入 | WAL 模式支持读写并发 | 已验证 |
| blackboard.db 大小 | 初期 <1MB | 每个任务几 KB，100 个任务 < 1MB |

---

## 8. 交付检查清单

Phase 1 部署前逐项验证：

- [ ] 项目创建、git init、远程配置完成
- [ ] `blackboard.db` 自动创建且 schema 正确
- [ ] CLI `blackboard.py read/claim/output/comment/decide/observe/create` 全部可用
- [ ] Daemon tick 60s 循环正常运行
- [ ] Agent spawn 成功创建隔离 session
- [ ] Session 完成后自动存档 + sessions.json 清理
- [ ] API `/api/blackboard/tasks` 可创建/查询任务
- [ ] API `/api/daemon/status` 返回正确状态
- [ ] API `/api/daemon/tick` 可手动触发
- [ ] PM2 启动后 daemon ticker 自动恢复
- [ ] `pm2 logs` 中能看到 tick 和 spawn 日志
- [ ] v1 (8082) 不受 v2 (8083) 影响

---

## 9. 后续 Phase 规划

| Phase | 内容 | 依赖 |
|-------|------|------|
| **Phase 1** | 黑板 + Daemon + CLI + API（本方案） | 无 |
| Phase 2 | 前端黑板视图 + Agent 黑板 Skill | Phase 1 |
| Phase 3 | 依赖自动推进 + 产出验证门禁 | Phase 2 |
| Phase 4 | 庞统 AI 规划 + Agent 自主领活 | Phase 3 |
| Phase 5 | 经验沉淀 + Mail 完全移除 | Phase 4 |