sanguo_moziplus_v2/docs/user-guide.md

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/

路径覆盖示例：

# 部署到自定义位置
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/ → 构建产物

修改前端后的流程：

# 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 后端开发

修改后端后的流程：

# 1. 在开发目录改代码
# 2. 同步到安装目录（用 deploy.sh 或手动 rsync）
# 3. 重启
pm2 restart sanguo-moziplus-v2

后端入口：src/main.py

5. 配置

配置文件：config/default.yaml

daemon:
  api_port: 8083
  tick_interval: 30      # tick 间隔（秒）
  max_global_agents: 5   # 最大并发 Agent 数

6. 常见场景

创建一个任务

curl -X POST http://localhost:8083/api/projects/_general/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title": "调查 XXX", "description": "详细描述..."}'

查看 Agent 工作状态

# 服务状态
curl http://localhost:8083/api/daemon/status

# 所有 session
curl http://localhost:8083/api/daemon/sessions

清空测试数据

# 清空所有数据
bash scripts/reset-data.sh --confirm

# 只清某个项目
bash scripts/reset-data.sh --project=e2e-test --confirm

归档已完成的任务

# 单个任务
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 错误失败）