auto-sync: 2026-05-15 02:05:48

2026-05-15 02:05:48 +08:00
parent 57394e3734
commit c8d7d8a4a6
3 changed files with 1821 additions and 0 deletions
@@ -0,0 +1,212 @@
+# 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 |