cfdaily
266 lines
8.5 KiB
Markdown
266 lines
8.5 KiB
Markdown
# 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 错误失败）
|