# 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 错误失败）