integral-shop/openclaw_agent_configuration_v2.plan.md

---
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 各自进化导致行为漂移   |