diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..7709a03 --- /dev/null +++ b/docs/user-guide.md @@ -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 错误失败）