auto-sync: 2026-05-23 13:33:44

2026-05-23 13:33:44 +08:00
parent 8894a59f25
commit 1ff023dd35
1 changed files with 265 additions and 0 deletions
@@ -0,0 +1,265 @@
+# moziplus v2 用户手册（Agent 版）
+
+> 本手册面向 Agent（庞统、诸葛亮），帮助快速理解和使用 moziplus v2 平台。
+> 人读版待后续补充。
+
+## 1. 项目概况
+
+- **定位**：多 Agent 任务编排平台（Blackboard 架构）
+- **版本**：v3.0（当前开发中）
+- **端口**：8083
+- **PM2 进程名**：`sanguo-moziplus-v2`
+- **前端**：http://localhost:8083/
+
+### 目录结构
+
+| 目录 | 说明 |
+|------|------|
+| `~/.openclaw/sanguo_projects/sanguo_moziplus_v2/` | 开发目录（改代码在这里） |
+| `~/.sanguo_projects/sanguo_moziplus_v2/` | 安装目录（运行在这里） |
+
+⚠️ **禁止直接改安装目录**，除非用户明文要求。
+
+## 2. 核心概念
+
+### 数据模型
+
+```
+Project（项目）→ Task（任务）→ SubTask（子任务/Stage）
+```
+
+- **Project**：逻辑分组，对应一个 Git 仓库或业务领域。每个 Project 有独立的 `blackboard.db`
+- **Task**：用户的一个需求/意图。有状态管线：pending → claimed → working → review → done
+- **SubTask**：Agent 执行的原子任务，存储在 Task 的 `stages_json` 字段中
+
+### 特殊项目
+
+| 项目 ID | 说明 |
+|---------|------|
+| `_general` | 默认项目，无归属的任务放这里 |
+| `_mail` | 虚拟项目，Sanguo Mail 邮件的存储 |
+
+### 任务状态
+
+```
+pending → claimed → working → review → done
+                                    ↘ failed / blocked / cancelled / paused
+```
+
+### 项目注册表
+
+- `registry.db`（SQLite）：项目注册信息
+- 自动发现：data 目录下的子目录有 `blackboard.db` 就会被发现
+- 手动注册：通过 API 或配置文件
+
+## 3. 数据目录结构
+
+```
+data/
+  registry.db              # 项目注册表（自动发现 + 手动注册）
+  _general/                # 默认项目
+    blackboard.db          # SQLite 任务数据
+  _mail/                   # 邮件虚拟项目
+  {project-name}/          # 用户项目
+    blackboard.db
+```
+
+## 4. 常用操作速查
+
+### 4.1 部署脚本
+
+所有脚本位于 `scripts/` 目录，支持 `--target=DIR` 和 `MOZIPLUS_V2_DIR` 环境变量覆盖安装路径。
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 部署 | `scripts/deploy.sh` | 开发目录同步到安装目录 + 依赖安装 + 启动 |
+| 清空数据 | `scripts/reset-data.sh --confirm` | 停服务 → 清所有项目数据 → 重启 |
+| 指定项目清空 | `scripts/reset-data.sh --project=demo --confirm` | 只清指定项目 |
+| 卸载 | `scripts/uninstall.sh --confirm` | 完全卸载 |
+| 查看状态 | `scripts/status.sh` | 版本/PM2/健康检查/数据统计 |
+| 详细状态 | `scripts/status.sh -v` | 含每个项目的任务数 |
+| 备份 | `scripts/backup.sh` | 备份数据到 .backup/ |
+| E2E 准备 | `scripts/e2e-prepare.sh` | 备份 → 清理测试残留 → 干净环境 |
+| E2E 恢复 | `scripts/e2e-restore.sh` | 从备份恢复数据 |
+| 前端构建 | `scripts/build-frontend.sh` | 构建前端到 dist/ |
+
+**路径覆盖示例**：
+```bash
+# 部署到自定义位置
+scripts/deploy.sh --target=/opt/moziplus_v2
+
+# 用环境变量
+MOZIPLUS_V2_DIR=/opt/moziplus_v2 scripts/status.sh
+```
+
+### 4.2 API 速查
+
+基础 URL：`http://localhost:8083`
+
+#### 项目管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/projects` | 项目列表（含 task_count 统计） |
+| POST | `/api/projects` | 创建项目 `{name, config_json}` |
+| GET | `/api/projects/{pid}` | 项目详情 |
+| PATCH | `/api/projects/{pid}` | 更新项目 |
+| DELETE | `/api/projects/{pid}` | 删除项目 |
+| POST | `/api/projects/{pid}/archive` | 归档项目 |
+| POST | `/api/projects/{pid}/tasks/{tid}/move` | 移动任务到其他项目 |
+
+#### 任务管理
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/projects/{pid}/tasks` | 任务列表（支持 `?status=done&archived=false` 过滤） |
+| POST | `/api/projects/{pid}/tasks` | 创建任务 `{title, description, must_haves}` |
+| GET | `/api/projects/{pid}/tasks/{tid}` | 任务详情 |
+| GET | `/api/projects/{pid}/tasks/{tid}?expand=all` | 含子任务/评论/产出/决策 |
+| PATCH | `/api/projects/{pid}/tasks/{tid}` | 更新任务（status/archived/priority 等） |
+| POST | `/api/projects/{pid}/tasks/{tid}/claim` | 认领任务 |
+| POST | `/api/projects/{pid}/tasks/{tid}/status` | 更新状态 `{status, note}` |
+| POST | `/api/projects/{pid}/tasks/{tid}/archive` | 归档任务 |
+| POST | `/api/projects/{pid}/tasks/archive-done` | 归档所有已完成任务 |
+| GET | `/api/projects/{pid}/tasks/{tid}/progress` | 任务进度 |
+| GET | `/api/projects/{pid}/tasks/{tid}/events` | 任务事件列表 |
+| GET | `/api/projects/{pid}/summary` | 项目任务汇总 |
+
+#### 评论 / 产出 / 决策 / 观测
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET/POST | `/api/projects/{pid}/tasks/{tid}/comments` | 评论 |
+| GET/POST | `/api/projects/{pid}/tasks/{tid}/outputs` | 产出 |
+| GET/POST | `/api/projects/{pid}/tasks/{tid}/decisions` | 决策 |
+| POST | `/api/projects/{pid}/tasks/{tid}/observations` | 观测 |
+| GET/POST | `/api/projects/{pid}/tasks/{tid}/reviews` | 评审 |
+
+#### Checkpoint（决策/验证/执行检查点）
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/projects/{pid}/tasks/{tid}/checkpoints` | 检查点列表 |
+| POST | `/api/projects/{pid}/tasks/{tid}/checkpoints` | 创建检查点 |
+| POST | `.../checkpoints/{cid}/approve` | 批准 |
+| POST | `.../checkpoints/{cid}/reject` | 驳回 |
+
+#### Daemon
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/daemon/status` | 服务状态（版本/tick数/配置） |
+| POST | `/api/daemon/tick` | 手动触发一次 tick |
+| GET | `/api/daemon/sessions` | Agent session 列表 |
+
+#### Mail（飞鸽传书）
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/mail` | 邮件列表（支持 `?from=x&is_read=false`） |
+| POST | `/api/mail` | 发送邮件 |
+| GET | `/api/mail/{mid}` | 邮件详情 |
+| PATCH | `/api/mail/{mid}` | 更新邮件（标记已读等） |
+| GET | `/api/mail/summary` | 邮件汇总 |
+| GET | `/api/mail/agents/list` | Agent 列表 |
+
+#### SSE 实时事件
+
+| 方法 | 端点 | 说明 |
+|------|------|------|
+| GET | `/api/events` | SSE 事件流（任务状态变更等） |
+
+### 4.3 前端开发
+
+```
+开发目录/src/frontend/    → 源码
+开发目录/src/frontend/dist/ → 构建产物
+```
+
+**修改前端后的流程**：
+```bash
+# 1. 构建前端
+cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/frontend
+npx vite build
+
+# 2. 同步到安装目录
+rsync -a --delete \
+  ~/.openclaw/sanguo_projects/sanguo_moziplus_v2/src/frontend/dist/ \
+  ~/.sanguo_projects/sanguo_moziplus_v2/src/frontend/dist/
+
+# 3. 重启服务
+pm2 restart sanguo-moziplus-v2
+```
+
+注意：`npm run build` 会先跑 `tsc -b`，如果有 TS 类型错误会失败。跳过类型检查直接构建用 `npx vite build`。
+
+### 4.4 后端开发
+
+**修改后端后的流程**：
+```bash
+# 1. 在开发目录改代码
+# 2. 同步到安装目录（用 deploy.sh 或手动 rsync）
+# 3. 重启
+pm2 restart sanguo-moziplus-v2
+```
+
+后端入口：`src/main.py`
+
+## 5. 配置
+
+配置文件：`config/default.yaml`
+
+```yaml
+daemon:
+  api_port: 8083
+  tick_interval: 30      # tick 间隔（秒）
+  max_global_agents: 5   # 最大并发 Agent 数
+```
+
+## 6. 常见场景
+
+### 创建一个任务
+
+```bash
+curl -X POST http://localhost:8083/api/projects/_general/tasks \
+  -H 'Content-Type: application/json' \
+  -d '{"title": "调查 XXX", "description": "详细描述..."}'
+```
+
+### 查看 Agent 工作状态
+
+```bash
+# 服务状态
+curl http://localhost:8083/api/daemon/status
+
+# 所有 session
+curl http://localhost:8083/api/daemon/sessions
+```
+
+### 清空测试数据
+
+```bash
+# 清空所有数据
+bash scripts/reset-data.sh --confirm
+
+# 只清某个项目
+bash scripts/reset-data.sh --project=e2e-test --confirm
+```
+
+### 归档已完成的任务
+
+```bash
+# 单个任务
+curl -X POST http://localhost:8083/api/projects/{pid}/tasks/{tid}/archive
+
+# 归档项目下所有已完成任务
+curl -X POST http://localhost:8083/api/projects/{pid}/tasks/archive-done
+```
+
+## 7. 注意事项
+
+1. **SQLite 并发**：每个项目独立 DB，写入串行化（asyncio.Lock），但多进程场景注意 busy_timeout
+2. **项目自动发现**：data 目录下有 `blackboard.db` 的子目录会被自动注册为项目
+3. **前端统计**：看板数字从 v2tasks 前端聚合（单数据源），不用后端 task_count
+4. **E2E 残留**：测试脚本会创建 `e2e-*` 项目，记得用 `reset-data.sh` 或 `e2e-prepare.sh` 清理
+5. **构建跳过 tsc**：`npx vite build` 跳过类型检查，`npm run build` 含 tsc（可能因已有 TS 错误失败）