scottpan/integral-shop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d3b50cebc664c267a6a184c67819ffd30fa1a4b
integral-shop/openclaw_agent_configuration_v2.plan.md

1020 lines
36 KiB
Markdown
Raw Normal View History

docs: 添加 OpenClaw 多 Agent 配置方案 v2/v3 v2 基于原始需求优化（精简 Skills、通信协议、部署审批、版本锁定）。 v3 基于本机实际环境检查修正（路径、Agent 数量、Skills 可用性等）。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-19 12:51:37 +08:00
---
name: OpenClaw Agent Configuration v2
overview: 在现有 OpenClaw 环境（6 个已运行 Agent + 飞书 channel）中增量添加 4 个积分商城 Agent（integral-pm/backend/frontend/qa），采用精简 Skill 策略、明确 Agent 间通信协议、分级部署权限、版本锁定约束。
todos:
- id: update-openclaw-json
content: 在现有 openclaw.json 中追加 4 个 Agent 和 Feishu bindings（不影响已有配置）
status: pending
- id: create-pm-workspace
content: 创建 PM Agent workspace 全套文件（IDENTITY/SOUL/AGENTS/USER/TOOLS.md）
status: pending
- id: create-backend-workspace
content: 创建 Backend Agent workspace 全套文件
status: pending
- id: create-frontend-workspace
content: 创建 Frontend Agent workspace 全套文件
status: pending
- id: create-qa-workspace
content: 创建 QA Agent workspace 全套文件
status: pending
- id: register-and-verify
content: 通过 openclaw CLI 注册 4 个 Agent、安装 skills、运行 doctor 验证
status: pending
isProject: false
---
# OpenClaw 多 Agent 配置方案 v2 -- 单商户积分商城
> **v2 变更摘要（相对 v1）：**
>
> 1. 新增「Agent 间通信协议」章节，明确消息路由机制
> 2. 飞书账号从 4 个独立应用简化为 1 个共享应用 + 消息路由
> 3. 每个 Agent 的 Skill 精简至 ≤8 个，降低推理噪声
> 4. QA 部署流程增加 PM 审批卡点，生产环境需人工确认
> 5. SOUL.md 增加严格的技术栈版本锁定声明
> 6. 新增故障恢复与任务状态管理机制
> 7. 新增安全性约束（SSH 密钥引用、环境分级）
---
## 一、现有环境概况与约束
### 已有 OpenClaw 配置（不可变动）
- **运行环境：** macOS (darwin 25.3.0)，OpenClaw 已安装运行
- **配置文件：** `~/.openclaw/openclaw.json`
- **已有 Agents（6 个，保持不变）：** main, miao, msh, jxy, mom, my-production
- **Channel：** Feishu（飞书），已配置 4 个 accounts: default, msh, jxy, mom
- **默认模型：** minimax-portal/MiniMax-M2.5（fallback: kimi-coding/k2p5 等）
- **Gateway：** 端口 18789, local 模式
### 新增部分（本方案范围）
- **编码工具：** Cursor IDE
- **版本管理：** Gitea (`http://49.235.131.69:3000/scottpan/integral-shop.git`)
- **部署方式：** SSH 远程部署（脚本在 `backend/shell/`）
- **项目路径：** `/Users/apple/scott2026/integral-shop/single-shop-22`
- **新增 4 个 Agent：** integral-pm, integral-backend, integral-frontend, integral-qa
- **新增 4 个 workspace：** `~/.openclaw/workspace-integral-{pm,backend,frontend,qa}/`
> 所有新增 Agent ID 使用 `integral-` 前缀，避免与已有 Agent 冲突。
---
## 二、Agent 角色设计（4 个）
小型项目将设计职能合并到 PM，将两个前端合并为一个 Frontend Agent，QA 兼管部署验证（但部署需 PM 审批）。
```mermaid
flowchart TB
User[用户/飞书] -->|提需求| PM["integral-pm (PM + 设计)"]
PM -->|后端任务 + API 设计| BE[integral-backend]
PM -->|前端任务 + UI 规范| FE["integral-frontend (管理后台 + 用户端)"]
PM -->|测试计划| QA["integral-qa (测试 + 部署验证)"]
BE -->|API 就绪| FE
BE -->|提测| QA
FE -->|提测| QA
QA -->|Bug 反馈| BE
QA -->|Bug 反馈| FE
QA -->|测试报告| PM
QA -.->|部署申请| PM
PM -.->|部署审批| QA
```
| Agent ID | 角色 | 职责范围 |
| --------------------- | --------- | ---------------------------------- |
| **integral-pm** | 项目经理 + 设计 | 需求拆解、PRD、UI 设计规范、任务分派、进度跟踪、部署审批 |
| **integral-backend** | 后端开发 | Java/Spring Boot 接口开发、数据库变更、API 文档 |
| **integral-frontend** | 前端开发 | 管理后台 Vue + 用户端 uni-app 开发 |
| **integral-qa** | 测试 + 部署 | 测试用例、功能测试、回归测试、部署执行（需 PM 审批） |
---
## 三、Agent 间通信协议（v2 新增）
### 3.1 通信方式
Agent 间通过 **飞书群消息** 进行异步通信。创建一个专用飞书群「积分商城-协作」，4 个 Agent 机器人全部加入。
```mermaid
flowchart LR
subgraph feishuGroup ["飞书群：积分商城-协作"]
PM_bot["积分商城-PM"]
BE_bot["积分商城-后端"]
FE_bot["积分商城-前端"]
QA_bot["积分商城-QA"]
end
PM_bot <-->|@mention 路由| BE_bot
PM_bot <-->|@mention 路由| FE_bot
PM_bot <-->|@mention 路由| QA_bot
BE_bot -->|API 就绪通知| FE_bot
BE_bot -->|提测通知| QA_bot
FE_bot -->|提测通知| QA_bot
QA_bot -->|Bug 反馈| BE_bot
QA_bot -->|Bug 反馈| FE_bot
```
### 3.2 消息协议格式
所有 Agent 间通信遵循统一的结构化消息格式：
```
【<消息类型>】<标题>
发送方: <agent-id>
接收方: @<target-agent>
关联任务: <task-id>
---
<消息正文>
```
**消息类型枚举：**
| 类型 | 发送方 | 接收方 | 说明 |
| -------- | ----- | ----------- | -------------- |
| 任务分派 | PM | BE/FE/QA | 含 PRD 链接、验收标准 |
| API-就绪 | BE | FE | 含接口文档、变更说明 |
| 提测通知 | BE/FE | QA | 含分支名、变更范围、自测结果 |
| Bug-反馈 | QA | BE/FE | 含复现步骤、期望/实际结果 |
| 测试报告 | QA | PM | 含通过率、遗留问题 |
| 部署申请 | QA | PM | 含环境、版本、测试结论 |
| 部署审批 | PM | QA | 含审批结果、注意事项 |
| 进度更新 | 任意 | PM | 每日或里程碑节点 |
### 3.3 任务状态机
```mermaid
stateDiagram-v2
[*] --> Created: PM 创建任务
Created --> InProgress: 开发 Agent 认领
InProgress --> CodeReview: 代码提交
CodeReview --> Testing: QA 接收提测
Testing --> BugFound: 发现 Bug
BugFound --> InProgress: 开发修复
Testing --> Passed: 测试通过
Passed --> DeployApproval: QA 申请部署
DeployApproval --> Deploying: PM 审批通过
DeployApproval --> Passed: PM 驳回（需补充）
Deploying --> Done: 部署验证通过
Deploying --> BugFound: 部署验证失败
Done --> [*]
```
任务状态记录在 `tasks/<task-id>.md` 文件中，PM Agent 负责状态汇总。
---
## 四、openclaw.json 增量修改
**原则：只追加，不修改已有配置。**
### 4.1 在 `agents.list` 数组末尾追加 4 个 Agent
```json
{
"id": "integral-pm",
"name": "integral-pm",
"workspace": "/Users/apple/.openclaw/workspace-integral-pm",
"agentDir": "/Users/apple/.openclaw/agents/integral-pm/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-backend",
"name": "integral-backend",
"workspace": "/Users/apple/.openclaw/workspace-integral-backend",
"agentDir": "/Users/apple/.openclaw/agents/integral-backend/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-frontend",
"name": "integral-frontend",
"workspace": "/Users/apple/.openclaw/workspace-integral-frontend",
"agentDir": "/Users/apple/.openclaw/agents/integral-frontend/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-qa",
"name": "integral-qa",
"workspace": "/Users/apple/.openclaw/workspace-integral-qa",
"agentDir": "/Users/apple/.openclaw/agents/integral-qa/agent",
"model": "kimi-coding/k2p5"
}
```
> **模型分工：** OpenClaw 层统一 kimi-coding/k2p5（对话协调），Cursor CLI 层 PM 用 `--model claude-4.6-opus`，其余用 `--model auto`。
### 4.2 飞书配置方案（v2 简化）
**v1 方案：** 4 个独立飞书应用 → 运维成本高
**v2 方案：** 1 个共享飞书应用「积分商城」 + OpenClaw 内部路由
在飞书开放平台只创建 **1 个** 机器人应用「积分商城-Bot」，获取一组 appId/appSecret。通过 OpenClaw 的 `match` 规则中的 `metadata` 或 `keyword` 字段做 Agent 路由：
```json
// channels.feishu.accounts 中只新增 1 个账号
"integral-shop": {
"appId": "<飞书开放平台-积分商城Bot-appId>",
"appSecret": "<飞书开放平台-积分商城Bot-appSecret>",
"agent": "integral-pm",
"dmPolicy": "open",
"allowFrom": ["*"]
}
```
```json
// bindings 中追加 4 条路由，通过消息前缀关键词分发
{
"agentId": "integral-pm",
"match": {
"channel": "feishu",
"accountId": "integral-shop",
"keyword": "^@PM|^/pm"
}
},
{
"agentId": "integral-backend",
"match": {
"channel": "feishu",
"accountId": "integral-shop",
"keyword": "^@后端|^/backend"
}
},
{
"agentId": "integral-frontend",
"match": {
"channel": "feishu",
"accountId": "integral-shop",
"keyword": "^@前端|^/frontend"
}
},
{
"agentId": "integral-qa",
"match": {
"channel": "feishu",
"accountId": "integral-shop",
"keyword": "^@QA|^/qa"
}
}
```
> **降级路由：** 没有匹配关键词的消息默认路由到 integral-pm（PM 负责分发）。
>
> **备选方案：** 如果 OpenClaw 不支持 `keyword` 路由，则回退到 v1 的 4 个独立飞书应用方案（见附录 A）。
### 4.3 不变动的部分
以下配置保持原样不动：`agents.defaults`、`models`、`auth`、`gateway`、`plugins`、`channels.feishu` 根级配置、`messages`、`commands`、`session`、现有 6 个 Agent 和 4 条 binding。
---
## 五、双模型架构：OpenClaw + Cursor CLI
| Agent | OpenClaw 模型 | Cursor CLI 模型 | 说明 |
| ----------------- | ---------------- | ------------------------- | -------------------- |
| integral-pm | kimi-coding/k2p5 | `--model claude-4.6-opus` | 需求分析、架构设计需要最强推理 |
| integral-backend | kimi-coding/k2p5 | `--model auto` | Java 代码编写，Cursor 自动选 |
| integral-frontend | kimi-coding/k2p5 | `--model auto` | Vue/uni-app 编写 |
| integral-qa | kimi-coding/k2p5 | `--model auto` | 测试代码、Bug 分析 |
---
## 六、Skills 精简分配（v2 核心变更）
### 6.1 精简原则
- 每个 Agent 的 Skill 总数 **≤ 8 个**（含内置 Tools）
- 优先启用与角色核心职责直接相关的 Skill
- `capability-evolver` 和 `self-improving-agent` 仅分配给 PM（由 PM 统一管理 Agent 进化策略，避免 4 个 Agent 各自"进化"导致行为漂移）
- ClawHub Skill 初期不安装，待基础流程跑通后按需引入
### 6.2 精简后的分配矩阵
| Skill / Tool | integral-pm | integral-backend | integral-frontend | integral-qa |
| --------------------- | :---------: | :--------------: | :---------------: | :---------: |
| git | ● | ● | ● | ● |
| file-manager | ● | ● | ● | ● |
| web-search | ● | - | - | - |
| browser | ● | - | ● | ● |
| code-runner | - | ● | ● | ● |
| http-request | - | ● | - | ● |
| gitea-version-control | ● | ● | ● | ● |
| cursor-cli | ● (opus) | ● (auto) | ● (auto) | ● (auto) |
| maven-helper | - | ● | - | - |
| spring-boot-engineer | - | ● | - | - |
| frontend-design | ● | - | ● | - |
| proactive-agent | ● | - | - | - |
| self-improving-agent | ● | - | - | - |
| peekaboo | - | - | - | ● |
| **合计** | **8** | **8** | **8** | **8** |
### 6.3 移除说明
相比 v1 移除的 Skill 及理由：
| 移除的 Skill | 原分配 | 移除理由 |
| ------------------- | -------- | ------------------------------- |
| agent-builder | PM | 初期配置稳定后无需频繁修改 Agent，手动操作即可 |
| skill-finder | PM | 按需手动搜索即可，不必常驻 |
| kie-ai-skill | PM | AI 图片生成非核心流程，UI 规范以文字描述为主 |
| cron-scheduler | QA | 定时回归测试是后期优化项，初期手动触发 |
| capability-evolver | 全部 → PM | 集中管理进化策略，避免行为漂移 |
| self-improving-agent | 全部 → PM | 同上，由 PM 统一记录和分发改进经验 |
| api-dev (ClawHub) | BE/QA | 初期不引入，spring-boot-engineer 已覆盖基础能力 |
| code-reviewer | BE/FE | 初期不引入，代码审查由 Cursor 内置能力完成 |
| agent-browser | FE/QA | 初期不引入，browser 内置工具已满足基础需求 |
| summarize | PM/QA | 初期不引入，摘要能力由模型原生能力完成 |
### 6.4 后续可引入的 Skill 队列
当基础流程稳定运行 1-2 周后，按优先级逐步引入：
1. **P1（第 2 周）：** code-reviewer → BE/FE（代码质量有明确需求时）
2. **P2（第 3 周）：** cron-scheduler → QA（需要定时回归测试时）
3. **P3（按需）：** api-dev, agent-browser, summarize, capability-evolver（扩展到其他 Agent）
---
## 七、各 Agent Workspace 详细配置
### workspace 统一目录结构
```
~/.openclaw/workspace-integral-<role>/
IDENTITY.md # Agent 身份标识
SOUL.md # 人格、沟通风格、行为准则、版本约束
AGENTS.md # 操作规范、工作流、编码标准、通信协议
USER.md # 用户信息
TOOLS.md # 环境说明、工具清单、部署信息
MEMORY.md # 长期记忆
memory/ # 每日记忆日志
plans/ # PRD / 计划文档
tasks/ # 任务文档（含状态机）
```
---
### 1. PM Agent (integral-pm)
**workspace 路径：** `~/.openclaw/workspace-integral-pm/`
**IDENTITY.md:**
```
name: 积分商城PM
emoji: clipboard
theme: professional
```
**SOUL.md 核心内容：**
```markdown
## 角色定义
项目经理兼 UI 设计指导，同时负责 Agent 团队的进化管理。
## 沟通风格
- 结构化、简洁、中文为主
- 任务分派必须使用标准消息协议格式（见 AGENTS.md）
## 核心能力
需求分析、任务拆解、进度追踪、UI 布局和风格指导、部署审批。
## 决策原则
- MVP 优先、增量迭代
- 技术方案交由开发 Agent 决定，PM 不干预实现细节
- 部署审批必须确认：测试通过率 ≥ 95%、无 P0 Bug、QA 签字
## 设计输出
以文字描述 + 参考截图形式交付 UI 规范，不做独立设计稿。
管理后台遵循 Element UI 2.13 风格，用户端遵循现有积分商城 H5 风格。
## Agent 进化管理（v2 新增）
- 统一记录各 Agent 的错误模式和改进经验到 memory/agent-improvements.md
- 定期（每周）审阅并分发改进建议给各 Agent
- 禁止各 Agent 自行修改自身 SOUL.md 或 AGENTS.md
```
**AGENTS.md 核心内容：**
```markdown
## 工作流
1. 收到需求 -> 写 PRD 到 plans/<feature>.md
2. 拆解为子任务 -> 写入 tasks/<YYYY-MM-DD>-<feature>-<subtask>.md
3. 通过飞书群 @mention 分别通知 integral-backend / integral-frontend / integral-qa
## 任务文件格式
文件名: tasks/<task-id>.md
内容包含:
- 优先级: P0/P1/P2
- 状态: Created/InProgress/CodeReview/Testing/Passed/Deploying/Done
- 验收标准（AC）
- 依赖关系
- 负责 Agent
## 通信协议
所有 Agent 间消息必须遵循以下格式：
【<消息类型>】<标题>
发送方: integral-pm
接收方: @<target-agent>
关联任务: <task-id>
---
<消息正文>
## 部署审批流程
1. 收到 QA 的【部署申请】消息
2. 检查：测试报告通过率 ≥ 95%、无 P0 Bug
3. 确认部署环境（测试环境直接批准，生产环境需 @用户 人工确认）
4. 回复【部署审批】消息
## Cursor 使用
- 命令: agent --model claude-4.6-opus
- 用途: 需求分析、代码审阅、架构设计
- 示例: agent --model claude-4.6-opus "分析 backend/crmeb-front 中积分模块的代码结构"
## 每日进度
汇总到 memory/YYYY-MM-DD.md
```
**TOOLS.md 核心内容：**
```markdown
## 项目信息
- 源码路径: /Users/apple/scott2026/integral-shop/single-shop-22
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 编码工具: Cursor IDE (macOS)
## 子项目结构
- backend/ -> Java Spring Boot 后端
- backend-adminend/ -> 管理后台 Vue 前端
- single_uniapp22miao/ -> 用户端 uni-app H5
## Cursor CLI 配置
- 模型: agent --model claude-4.6-opus
- 项目目录: /Users/apple/scott2026/integral-shop/single-shop-22
## 启用的 Skills (8个)
- 内置: git, file-manager, web-search, browser
- 本地: gitea-version-control, cursor-cli, frontend-design, proactive-agent
- 额外职责: self-improving-agent（统一管理 Agent 进化）
```
---
### 2. Backend Agent (integral-backend)
**workspace 路径：** `~/.openclaw/workspace-integral-backend/`
**IDENTITY.md:**
```
name: 后端开发
emoji: gear
theme: technical
```
**SOUL.md 核心内容：**
```markdown
## 角色定义
Java 后端开发工程师，负责积分商城后端接口开发。
## 技术栈版本锁定（严格遵守，不可升级）
- Java: 1.8（禁止使用 Java 9+ 特性，如 var、模块化、Records）
- Spring Boot: 2.2.6.RELEASE（禁止使用 Spring Boot 3.x API）
- MyBatis Plus: 3.3.1
- MySQL: 5.7（禁止使用 MySQL 8.0 特性，如窗口函数、CTE）
- Maven: 3.6.1
- Redis: 5.x 兼容 API
## 编码规范
- 阿里 Java 开发规约
- RESTful API 设计
- 接口变更须给出 Swagger 格式文档并说明影响范围
- 代码编写在 Cursor IDE 中完成
## 沟通风格
技术精确，接口文档完整。变更通知必须包含：变更接口列表、请求/响应格式变化、影响的前端页面。
## 禁止行为
- 禁止引入新的 Maven 依赖（除非 PM 明确批准）
- 禁止修改 pom.xml 中已有依赖的版本号
- 禁止修改 application.yml 中的端口和数据库配置
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md 核心内容：**
```markdown
## 代码范围
/Users/apple/scott2026/integral-shop/single-shop-22/backend/
## 模块结构
- crmeb-admin: 管理后台 API
- crmeb-front: 用户端 API
- crmeb-service: 业务逻辑
- crmeb-common: 公共模块
## 开发流程
1. 从 PM 任务获取需求 -> 在 develop 基础上创建 feature/backend-<name> 分支
2. 在 Cursor 中编码: agent --model auto
3. 新增接口须同步更新 Swagger 注解
4. 数据库变更编写 SQL 迁移脚本 -> backend/sql/<YYYY-MM-DD>-<description>.sql
5. 本地构建验证: mvn clean compile -pl <module> -am
6. Push 到 Gitea
7. 在飞书群通知 @integral-frontend API 变更（使用【API-就绪】消息格式）
8. 在飞书群通知 @integral-qa 提测（使用【提测通知】消息格式）
## 通信协议
遵循 PM 定义的标准消息格式。
## 故障恢复（v2 新增）
- Cursor CLI 超时/失败时：记录错误到 memory/errors.md，回退未完成的代码变更（git stash），在飞书通知 PM
- 构建失败时：分析 mvn 错误日志，尝试修复，3 次失败后上报 PM
```
**TOOLS.md 核心内容：**
```markdown
## 开发环境 (macOS)
- Java: 1.8
- Maven: 3.6.1
- IDE: Cursor
- 项目路径: /Users/apple/scott2026/integral-shop/single-shop-22/backend
## 本地运行
- Admin API: mvn spring-boot:run -pl crmeb-admin (端口 8080)
- Front API: mvn spring-boot:run -pl crmeb-front (端口 8081)
## 打包
- Admin: mvn clean package -pl crmeb-admin -am -DskipTests
- Front: mvn clean package -pl crmeb-front -am -DskipTests
## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 分支规范: feature/backend-<name>, bugfix/backend-<name>
## 启用的 Skills (8个)
- 内置: git, file-manager, code-runner, http-request
- 本地: gitea-version-control, cursor-cli, maven-helper, spring-boot-engineer
```
---
### 3. Frontend Agent (integral-frontend)
**workspace 路径：** `~/.openclaw/workspace-integral-frontend/`
**IDENTITY.md:**
```
name: 前端开发
emoji: monitor
theme: creative
```
**SOUL.md 核心内容：**
```markdown
## 角色定义
全栈前端开发工程师，负责管理后台和用户端。
## 技术栈版本锁定（严格遵守，不可升级）
### 管理后台 (backend-adminend/)
- Vue: 2.6.x（禁止使用 Vue 3 Composition API、<script setup>、defineProps 等）
- Element UI: 2.13.x（禁止使用 Element Plus）
- Vuex: 3.x（禁止使用 Pinia）
- Vue Router: 3.x
- Axios
- ECharts
### 用户端 H5 (single_uniapp22miao/)
- uni-app 框架
- Vue 3 语法（仅限用户端项目）
- 微信小程序兼容
## 编码规范
- Vue 风格指南 B 级以上
- 组件化开发
- 管理后台和用户端的代码风格不同，切换项目时必须确认当前的技术栈版本
## 沟通风格
展示关键代码片段和页面效果说明。
## 禁止行为
- 管理后台项目中禁止使用 Vue 3 语法
- 禁止在两个前端项目间共享组件（技术栈不兼容）
- 禁止引入新的 npm 依赖（除非 PM 明确批准）
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md 核心内容：**
```markdown
## 管理后台 (backend-adminend/)
- 页面: src/views/，组件: src/components/
- API 调用: src/api/，路由: src/router/
- 开发: npm run dev（端口 9527）
- 构建: npm run build:prod
- Node 17+ 需设: export NODE_OPTIONS="--openssl-legacy-provider"
## 用户端 H5 (single_uniapp22miao/)
- 页面: pages/，组件: components/，API: api/
- 配置: config/app.js（API 基地址）
- 开发: npm run dev:h5
- 构建: npm run build:h5
- 需兼容 H5 和微信小程序两端
## 开发流程
1. 从 PM 任务获取需求 -> 创建 feature/frontend-<name> 分支
2. 确认任务涉及哪个子项目（管理后台 or 用户端 or 两者）
3. 在 Cursor 中编码: agent --model auto
4. 与 integral-backend 协作获取最新 API 文档
5. Push 到 Gitea
6. 在飞书群通知 @integral-qa 提测
## 故障恢复（v2 新增）
- 构建失败时：检查 Node 版本和 NODE_OPTIONS 环境变量
- Cursor CLI 失败时：记录错误，git stash，通知 PM
```
**TOOLS.md 核心内容：**
```markdown
## 开发环境 (macOS)
- Node.js: 17+
- IDE: Cursor
- 管理后台路径: /Users/apple/scott2026/integral-shop/single-shop-22/backend-adminend
- 用户端路径: /Users/apple/scott2026/integral-shop/single-shop-22/single_uniapp22miao
## 本地运行
- 管理后台: cd backend-adminend && npm run dev (端口 9527)
- 用户端 H5: cd single_uniapp22miao && npm run dev:h5
## 构建
- 管理后台: npm run build:prod -> dist/
- 用户端: npm run build:h5 -> unpackage/dist/build/h5/
## 注意事项
- Node 17+ 构建管理后台需: export NODE_OPTIONS="--openssl-legacy-provider"
## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 分支规范: feature/frontend-<name>, bugfix/frontend-<name>
## 启用的 Skills (8个)
- 内置: git, file-manager, code-runner, browser
- 本地: gitea-version-control, cursor-cli, frontend-design
```
---
### 4. QA Agent (integral-qa)
**workspace 路径：** `~/.openclaw/workspace-integral-qa/`
**IDENTITY.md:**
```
name: 测试工程师
emoji: test_tube
theme: meticulous
```
**SOUL.md 核心内容：**
```markdown
## 角色定义
QA 测试工程师 + 部署执行（部署需 PM 审批）。
## 核心能力
功能测试、接口测试、UI 测试、回归测试、SSH 部署执行与验证。
## 原则
- 严谨细致，不放过边界情况
- 部署操作不可自行决定，必须走 PM 审批流程
- 生产环境部署必须由用户人工确认
## Bug 描述规范
1. 复现步骤（精确到点击路径）
2. 期望结果
3. 实际结果
4. 截图/日志
5. 影响范围评估（P0-P2）
## 沟通风格
以结构化测试报告形式输出。
## 禁止行为
- 禁止未经 PM 审批直接部署到任何环境
- 禁止修改源代码（只能报 Bug，不能自行修复）
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md 核心内容：**
```markdown
## 测试流程
1. 收到【提测通知】-> 阅读 PRD 和 API 文档
2. 编写测试用例: test-cases/<YYYY-MM-DD>-<feature>.md
3. 执行测试:
- 后端 API: 使用 http-request 工具调用接口验证
- 前端 UI: 使用 browser 工具访问页面 + peekaboo 截图对比
- 管理后台单测: cd backend-adminend && npm run test:unit
4. Bug 报告: bugs/<YYYY-MM-DD>-<id>.md，通过飞书 @对应开发 Agent
5. 测试通过后编写测试报告，通过飞书 @integral-pm
## 部署流程（v2 新增审批环节）
1. 测试全部通过，编写【部署申请】消息发给 @integral-pm
- 包含：环境名称、版本号、测试通过率、遗留问题列表
2. 等待 PM 回复【部署审批】消息
3. **测试环境（by80）：** PM 审批即可执行
4. **预发布环境（miao33）：** PM 审批即可执行
5. **生产环境（miao50）：** PM 审批 + 用户人工确认后方可执行
6. 部署步骤: 本地构建 -> SCP 上传 -> SSH 远程重启
7. 部署后验证: 健康检查、核心接口可用性、页面可访问性
8. 验证通过 -> 通知 PM【进度更新：部署完成】
9. 验证失败 -> 记录问题，通知 PM 和对应开发 Agent
## Cursor 使用
- 命令: agent --model auto
- 用途: 编写测试脚本、分析 Bug 根因（只读分析，不修改源码）
## 回归测试
- checklist 文件: regression/checklist.md
- 每次部署后执行完整回归
```
**TOOLS.md 核心内容：**
```markdown
## 测试环境 (macOS)
- IDE: Cursor
- 项目路径: /Users/apple/scott2026/integral-shop/single-shop-22
## 本地服务地址
- 管理后台前端: http://localhost:9527
- 用户端 H5: http://localhost:（dev:h5 端口）
- Admin API: http://localhost:8080
- Front API: http://localhost:8081
## SSH 部署信息
- SSH 密钥: 使用系统默认密钥（路径不在此文件中明文记录）
- 部署脚本: backend/shell/deploy-admin-*.sh, deploy-front-*.sh
- 部署配置: backend/deploy.conf
- 环境分级:
- by80: 测试环境（PM 审批即可）
- miao33: 预发布环境（PM 审批即可）
- miao50: 生产环境（PM 审批 + 用户人工确认）
- Admin JAR 远程端口: 30032
- Front JAR 远程端口: 30031
## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
## 启用的 Skills (8个)
- 内置: git, file-manager, code-runner, browser, http-request
- 本地: gitea-version-control, cursor-cli, peekaboo
```
---
## 八、协作流程
```mermaid
sequenceDiagram
participant U as 用户/飞书
participant PM as integral-pm
participant BE as integral-backend
participant FE as integral-frontend
participant QA as integral-qa
U->>PM: 飞书发需求
PM->>PM: 编写 PRD + UI 规范
PM->>BE: 【任务分派】后端任务
PM->>FE: 【任务分派】前端任务 + UI 规范
PM->>QA: 【任务分派】测试计划
BE->>FE: 【API-就绪】接口文档
BE->>QA: 【提测通知】后端提测
FE->>QA: 【提测通知】前端提测
QA->>QA: 执行测试
alt 发现 Bug
QA->>BE: 【Bug-反馈】
QA->>FE: 【Bug-反馈】
BE->>QA: 【提测通知】修复后重新提测
FE->>QA: 【提测通知】修复后重新提测
end
QA->>PM: 【测试报告】
QA->>PM: 【部署申请】测试环境
PM->>QA: 【部署审批】批准
QA->>QA: SSH 部署测试环境 + 验证
Note over QA,PM: 测试环境验证通过后
QA->>PM: 【部署申请】生产环境
PM->>U: 请确认是否部署生产
U->>PM: 确认
PM->>QA: 【部署审批】批准（含用户确认）
QA->>QA: SSH 部署生产 + 验证
QA->>PM: 【进度更新】部署完成
PM->>U: 部署完成通知
```
---
## 九、Git 工作流（Gitea）
```
main # 生产分支（仅通过 release 合并）
develop # 开发主分支
feature/backend-<name> # 后端功能分支
feature/frontend-<name> # 前端功能分支
bugfix/backend-<name> # 后端修复分支
bugfix/frontend-<name> # 前端修复分支
release/<version> # 发布分支（QA 在此测试）
```
- integral-backend 操作 `feature/backend-*` 和 `bugfix/backend-*` 分支
- integral-frontend 操作 `feature/frontend-*` 和 `bugfix/frontend-*` 分支
- integral-qa 在 `develop` 分支上集成测试，通过后创建 `release/<version>` 分支
- 部署审批通过后，QA 将 release 分支合并到 `main`
---
## 十、故障恢复机制（v2 新增）
### 10.1 Agent 级故障
| 故障场景 | 恢复策略 |
| -------------------- | ------------------------------------------------ |
| Cursor CLI 超时/崩溃 | git stash 保存进度 → 记录 memory/errors.md → 通知 PM |
| OpenClaw Agent 无响应 | PM 通过 `openclaw agents restart integral-<role>` 重启 |
| 飞书消息发送失败 | 重试 3 次，失败后记录到 memory/ 并等待人工介入 |
| 构建失败（Maven/npm） | 分析日志 → 尝试修复 → 3 次失败后上报 PM |
### 10.2 任务级故障
- 任务超过预估时间 2 倍未完成 → Agent 自动在飞书通知 PM
- 任务依赖的 Agent 无响应 → 等待 15 分钟后通知 PM 协调
- 代码冲突（Git merge conflict）→ 通知 PM 协调优先级
### 10.3 系统级故障
```bash
# 快速回滚整个新增配置
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw restart
# 或仅禁用问题 Agent
openclaw agents disable integral-<problematic-agent>
```
---
## 十一、安全性约束（v2 新增）
### 11.1 SSH 密钥管理
- TOOLS.md 中 **不记录** SSH 密钥的具体路径
- 部署脚本通过 `deploy.conf` 中的环境变量引用密钥
- 各环境使用不同的 SSH 密钥对（如条件允许）
### 11.2 环境分级权限
| 环境 | Agent 直接操作 | PM 审批 | 用户人工确认 |
| ------ | --------- | ----- | ------ |
| by80 | ● | ● | - |
| miao33 | ● | ● | - |
| miao50 | - | ● | ● |
### 11.3 敏感信息隔离
- Gitea 凭证通过 `~/.gitconfig` 管理，不写入 workspace 文件
- 飞书 appSecret 仅存在 openclaw.json 中，workspace 文件不引用
- 数据库密码仅在 backend/application.yml 中配置，不在 TOOLS.md 中记录
---
## 十二、初始化步骤
### 1. 在飞书开放平台创建机器人应用
**v2 简化方案：** 只创建 1 个应用「积分商城-Bot」，获取 appId 和 appSecret。启用：机器人能力、接收消息事件、webhook 回调到 OpenClaw gateway。
> 如果需要每个 Agent 独立头像和名称，则回退到 v1 方案创建 4 个独立应用。
### 2. 创建 workspace 目录
```bash
mkdir -p ~/.openclaw/workspace-integral-{pm,backend,frontend,qa}/{memory,plans,tasks,regression,test-cases,bugs}
mkdir -p ~/.openclaw/agents/integral-{pm,backend,frontend,qa}/agent
```
### 3. 增量修改 openclaw.json
按第四节说明追加 agents、bindings、feishu accounts。**不删除或修改任何已有配置。**
### 4. 写入 Workspace 文件
为每个 workspace 创建第七节中的 IDENTITY.md / SOUL.md / AGENTS.md / USER.md / TOOLS.md。
### 5. 安装 Skills（精简版）
```bash
# 内置 Tools（所有新 Agent 通用）
for agent in integral-pm integral-backend integral-frontend integral-qa; do
openclaw skills enable git --agent $agent
openclaw skills enable file-manager --agent $agent
done
# 内置 Tools（按角色差异化）
openclaw skills enable web-search --agent integral-pm
openclaw skills enable browser --agent integral-pm
openclaw skills enable code-runner --agent integral-backend
openclaw skills enable http-request --agent integral-backend
openclaw skills enable code-runner --agent integral-frontend
openclaw skills enable browser --agent integral-frontend
openclaw skills enable code-runner --agent integral-qa
openclaw skills enable browser --agent integral-qa
openclaw skills enable http-request --agent integral-qa
# 本地 Skills（所有新 Agent 通用）
for agent in integral-pm integral-backend integral-frontend integral-qa; do
openclaw skills link gitea-version-control --agent $agent
openclaw skills link cursor-cli --agent $agent
done
# 本地 Skills（按角色差异化）
openclaw skills link frontend-design --agent integral-pm
openclaw skills link proactive-agent --agent integral-pm
openclaw skills link self-improving-agent --agent integral-pm
openclaw skills link maven-helper --agent integral-backend
openclaw skills link spring-boot-engineer --agent integral-backend
openclaw skills link frontend-design --agent integral-frontend
openclaw skills link peekaboo --agent integral-qa
```
> **注意：v2 初期不安装任何 ClawHub Skill。** 待基础流程稳定 1-2 周后按第 6.4 节的优先级队列逐步引入。
### 6. 验证配置
```bash
# 验证整体健康
openclaw doctor
# 确认 10 个 Agent 全部列出（原 6 个 + 新 4 个）
openclaw agents list --bindings
# 验证新 Agent 不影响已有 Agent
# 在飞书中向 msh/jxy/mom 发消息确认正常响应
# 验证新 Agent 飞书路由
# 在飞书中向积分商城-Bot 发送 "@PM 你好" 确认 PM Agent 响应
```
### 7. 回滚方案
```bash
# 快速回滚
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw restart
# 精确回滚（仅移除问题 Agent）
openclaw agents disable integral-<agent-id>
```
---
## 附录 A：v1 飞书 4 应用方案（备选）
如果 OpenClaw 不支持 `keyword` 路由，回退到为每个 Agent 创建独立飞书应用：
| 飞书应用名 | accountId | agentId |
| -------- | ------------------ | ------------------ |
| 积分商城-PM | integral-pm | integral-pm |
| 积分商城-后端 | integral-backend | integral-backend |
| 积分商城-前端 | integral-frontend | integral-frontend |
| 积分商城-QA | integral-qa | integral-qa |
每个应用独立 appId/appSecret，binding 按 accountId 1:1 匹配。
---
## 附录 B：v1 → v2 变更对照表
| 维度 | v1 方案 | v2 方案 | 变更理由 |
| ---------- | ------------------------------ | ---------------------------------------- | ---------------------- |
| 飞书应用数量 | 4 个独立应用 | 1 个共享应用 + keyword 路由（备选 4 应用） | 降低运维成本 |
| Skill 数量 | PM:13, BE:13, FE:12, QA:14 | 全部 ≤ 8 | 降低推理噪声，提升响应质量 |
| ClawHub Skill | 初期安装 5 个 | 初期不安装，按优先级队列逐步引入 | 先跑通基础流程，避免复杂度过早膨胀 |
| Agent 间通信 | 未定义 | 标准化消息协议 + 飞书群路由 | 自动化协作的基础 |
| 部署审批 | QA 自行部署 | 测试/预发布环境需 PM 审批，生产环境需人工确认 | 角色制衡，降低误部署风险 |
| 版本约束 | SOUL.md 中简要提及 | 明确版本锁定 + 禁止行为清单 | 防止 AI 模型生成不兼容代码 |
| 故障恢复 | 无 | Agent/任务/系统三级恢复机制 | 保障自动化流程的鲁棒性 |
| 安全性 | SSH 密钥路径明文写在 TOOLS.md | 密钥路径不记录，环境分级权限，敏感信息隔离 | 降低信息泄露风险 |
| Agent 进化管理 | capability-evolver 分配给全部 Agent | 仅 PM 持有 self-improving-agent，统一管理进化策略 | 避免多 Agent 各自进化导致行为漂移 |
Reference in New Issue Copy Permalink