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

1101 lines
35 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 v3
overview: 基于本机实际 OpenClaw 环境检查结果修正的配置方案。在现有 1 个 main Agent + 1 个飞书应用的基础上，增量添加 4 个积分商城 Agent，不影响已有配置。
todos:
- id: create-feishu-apps
content: 在飞书开放平台创建 4 个机器人应用（或复用现有应用做路由）
status: pending
- id: update-openclaw-json
content: 在现有 openclaw.json 中追加 4 个 Agent、bindings 和飞书账号
status: pending
- id: create-workspaces
content: 创建 4 个 Agent workspace 目录和全套 .md 文件
status: pending
- id: install-skills
content: 安装本地 Skills 和 ClawHub Skills
status: pending
- id: register-and-verify
content: 运行 openclaw doctor 验证配置
status: pending
isProject: false
---
# OpenClaw 多 Agent 配置方案 v3 -- 单商户积分商城
> **v3 核心变更（基于实际环境检查）：**
>
> v1/v2 方案假设已有 6 个 Agent、4 个飞书账号、多个本地 Skills 等，**与实际环境严重不符**。
> v3 基于 2026-03-19 对 `/Users/mac/.openclaw/` 的实际检查结果重写。
---
## 一、实际环境检查结果
### 1.1 与 v1/v2 假设的差异对照
| 项目 | v1/v2 假设 | 实际情况 |
| ----------- | --------------------------------------------------- | ------------------------------------ |
| macOS 用户目录 | `/Users/apple/` | **`/Users/mac/`** |
| 已有 Agent | 6 个（main, miao, msh, jxy, mom, my-production） | **仅 1 个（main）** |
| 已有飞书账号 | 4 个（default, msh, jxy, mom） | **仅 1 个（default）** |
| 已有 binding | 4 条 | **仅 1 条**（main → feishu:default） |
| 本地 Skills | 13 个已安装 | **0 个**（无 skills 目录） |
| 已安装 plugins | feishu, acpx, maven-connector, minimax-portal-auth | **仅 feishu** |
| 模型 provider | minimax-portal, kimi-coding 等多个 | **仅 moonshot + kimi-coding**（共用同一 API key） |
| workspace | 多个独立 workspace 目录 | **1 个共享 workspace**（模板状态，未自定义） |
| 默认模型 | minimax-portal/MiniMax-M2.5 | **kimi-coding/k2p5** |
| OpenClaw 版本 | 未指定 | **2026.3.13** |
| 飞书连接方式 | 未指定 | **websocket** |
### 1.2 实际配置详情
```
~/.openclaw/
├── openclaw.json # 主配置文件
├── openclaw.json.bak # 自动备份（共 3 份）
├── agents/
│ └── main/ # 唯一的 Agent
│ ├── agent/ # models.json, auth-profiles.json
│ └── sessions/ # 会话记录
├── workspace/ # 共享 workspace（默认模板状态）
│ ├── IDENTITY.md # 未填写
│ ├── SOUL.md # 默认模板
│ ├── AGENTS.md # 默认模板
│ ├── TOOLS.md # 默认模板
│ ├── USER.md # 未填写
│ ├── BOOTSTRAP.md # 仍存在（说明未完成初始化引导）
│ └── HEARTBEAT.md # 空（无定时任务）
├── extensions/
│ └── feishu/ # 飞书插件（含 feishu-doc/drive/perm/wiki 4 个 skill）
├── memory/
│ └── main.sqlite # 记忆数据库
├── cron/
│ └── jobs.json # 空
├── feishu/
│ └── dedup/ # 飞书消息去重
├── completions/ # shell 补全脚本
├── canvas/ # Web UI
├── devices/ # 设备信息
├── identity/ # 设备认证
└── logs/ # 日志
```
**模型配置：**
- `moonshot`：Kimi K2.5（OpenAI 兼容 API），256K 上下文，非推理模型
- `kimi-coding`：Kimi for Coding / k2p5（Anthropic 兼容 API），262K 上下文，推理模型
- 两个 provider 共用同一 API key
- 默认模型：`kimi-coding/k2p5`
**飞书配置：**
- 1 个应用：`cli_a930893990799cba`
- 连接模式：websocket
- 策略：groupPolicy=open, dmPolicy=open, allowFrom=*
**Gateway：**
- 端口 18789，local 模式，loopback 绑定，token 鉴权
---
## 二、Agent 角色设计（4 个）
与 v2 保持一致，不再赘述。
```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 间通信协议
### 3.1 通信方式
由于当前飞书只有 1 个应用，Agent 间通信有两种选择：
**方案 A（推荐）：共享飞书群 + @mention 路由**
创建一个飞书群「积分商城-协作」，所有 Agent 加入。通过消息中 `@Agent名` 或 `/命令前缀` 触发对应 Agent。
**方案 B：4 个独立飞书应用**
在飞书开放平台新建 4 个机器人应用，各自独立 appId/appSecret。私聊直达对应 Agent。
> v3 以**方案 B** 为主方案（更可靠），方案 A 作为降低运维成本的备选。原因：OpenClaw 的 binding 路由目前以 `accountId` 为主要匹配字段，keyword 路由是否支持需验证。
### 3.2 消息协议格式
所有 Agent 间通信遵循统一格式：
```
【<消息类型>】<标题>
发送方: <agent-id>
接收方: @<target-agent>
关联任务: <task-id>
---
<消息正文>
```
消息类型：任务分派、API-就绪、提测通知、Bug-反馈、测试报告、部署申请、部署审批、进度更新。
### 3.3 任务状态机
```
Created → InProgress → CodeReview → Testing → Passed → DeployApproval → Deploying → Done
↓ ↓
BugFound ← ─ ─ ─ ─ ─ ─ ─ ┘
↓
InProgress（修复后重新流转）
```
---
## 四、openclaw.json 增量修改
**原则：只追加，不修改已有配置。** 当前 openclaw.json 中仅有 1 个 main Agent 和 1 条 binding，以下为增量部分。
### 4.1 在 `agents.list` 中追加 4 个 Agent
当前 `agents` 节点只有 `defaults`，没有 `list` 数组。需要新增 `list` 字段：
```json
"agents": {
"defaults": {
... // 保持不变
},
"list": [
{
"id": "integral-pm",
"name": "integral-pm",
"workspace": "/Users/mac/.openclaw/workspace-integral-pm",
"agentDir": "/Users/mac/.openclaw/agents/integral-pm/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-backend",
"name": "integral-backend",
"workspace": "/Users/mac/.openclaw/workspace-integral-backend",
"agentDir": "/Users/mac/.openclaw/agents/integral-backend/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-frontend",
"name": "integral-frontend",
"workspace": "/Users/mac/.openclaw/workspace-integral-frontend",
"agentDir": "/Users/mac/.openclaw/agents/integral-frontend/agent",
"model": "kimi-coding/k2p5"
},
{
"id": "integral-qa",
"name": "integral-qa",
"workspace": "/Users/mac/.openclaw/workspace-integral-qa",
"agentDir": "/Users/mac/.openclaw/agents/integral-qa/agent",
"model": "kimi-coding/k2p5"
}
]
}
```
> **路径修正：** 所有路径以 `/Users/mac/` 为基础，非 v1 中的 `/Users/apple/`。
### 4.2 在 `bindings` 数组中追加 4 条飞书路由
当前只有 1 条 binding（main → feishu:default）。在其后追加：
```json
"bindings": [
{
"agentId": "main",
"match": {
"channel": "feishu",
"accountId": "default"
}
},
{
"agentId": "integral-pm",
"match": {
"channel": "feishu",
"accountId": "integral-pm"
}
},
{
"agentId": "integral-backend",
"match": {
"channel": "feishu",
"accountId": "integral-backend"
}
},
{
"agentId": "integral-frontend",
"match": {
"channel": "feishu",
"accountId": "integral-frontend"
}
},
{
"agentId": "integral-qa",
"match": {
"channel": "feishu",
"accountId": "integral-qa"
}
}
]
```
### 4.3 在 `channels.feishu` 中追加 `accounts`
当前飞书配置是单应用模式（appId/appSecret 在根级）。需要追加 `accounts` 字段支持多应用：
```json
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_a930893990799cba",
"appSecret": "FfpFz93MKBx0ytC1ceTPF0BnjM7vFVhQ",
"connectionMode": "websocket",
"domain": "feishu",
"groupPolicy": "open",
"dmPolicy": "open",
"allowFrom": ["*"],
"accounts": {
"integral-pm": {
"appId": "<飞书开放平台创建后填入>",
"appSecret": "<飞书开放平台创建后填入>",
"agent": "integral-pm",
"dmPolicy": "open",
"allowFrom": ["*"]
},
"integral-backend": {
"appId": "<飞书开放平台创建后填入>",
"appSecret": "<飞书开放平台创建后填入>",
"agent": "integral-backend",
"dmPolicy": "open",
"allowFrom": ["*"]
},
"integral-frontend": {
"appId": "<飞书开放平台创建后填入>",
"appSecret": "<飞书开放平台创建后填入>",
"agent": "integral-frontend",
"dmPolicy": "open",
"allowFrom": ["*"]
},
"integral-qa": {
"appId": "<飞书开放平台创建后填入>",
"appSecret": "<飞书开放平台创建后填入>",
"agent": "integral-qa",
"dmPolicy": "open",
"allowFrom": ["*"]
}
}
}
}
```
> **注意：** 根级 appId/appSecret（`cli_a930893990799cba`）保持不变，这是 main Agent 使用的默认应用。新增的 4 个账号各自独立。
### 4.4 不变动的部分
- `meta`、`wizard` — 系统自动管理
- `auth` — 保持现有 2 个 profile（moonshot:default, kimi-coding:default）
- `models` — 保持现有 2 个 provider（moonshot, kimi-coding）
- `tools` — 保持 web search 配置
- `commands`、`session` — 保持现有配置
- `gateway` — 端口 18789，鉴权 token 不变
- `plugins` — 仅 feishu，保持不变
- main Agent 的 binding — 保持不变
---
## 五、双模型架构
当前环境只有 2 个模型 provider，都使用 Kimi API。Cursor CLI 作为第二层编码工具：
| 层 | 用途 | Agent | 模型 |
| -------- | ---------- | ------------ | --------------------------- |
| OpenClaw | 飞书对话、任务协调 | 全部 | kimi-coding/k2p5（已有，无需新增） |
| Cursor | 代码编写、项目修改 | PM | `agent --model claude-4.6-opus` |
| Cursor | 代码编写、项目修改 | BE/FE/QA | `agent --model auto` |
> **前提：** Cursor IDE 已在本机安装并可通过 CLI 调用。若 Cursor 未安装，需先安装。
---
## 六、Skills 配置（基于实际情况修正）
### 6.1 实际可用资源盘点
当前**无任何本地 Skills**。v1/v2 中提到的 `gitea-version-control`、`maven-helper`、`spring-boot-engineer` 等 13 个 skill **均不存在**，需要从头安装或创建。
已有的 skill 仅限飞书插件自带的 4 个：`feishu-doc`、`feishu-drive`、`feishu-perm`、`feishu-wiki`。
### 6.2 Skills 安装计划
分三个阶段，从最小可用集开始：
**阶段一：最小启动集（Day 1）**
仅使用 OpenClaw 内置 Tools，不安装任何额外 Skill：
| 内置 Tool | integral-pm | integral-backend | integral-frontend | integral-qa |
| ------------ | :---------: | :--------------: | :---------------: | :---------: |
| git | ● | ● | ● | ● |
| file-manager | ● | ● | ● | ● |
| web-search | ● | ● | ● | ● |
| browser | ● | - | ● | ● |
| code-runner | - | ● | ● | ● |
| http-request | - | ● | - | ● |
| **合计** | **4** | **5** | **5** | **6** |
> 此阶段目标：验证 Agent 注册、飞书路由、基本对话功能正常。
**阶段二：核心 Skills 安装（Day 2-3）**
从 ClawHub 安装或本地创建以下 Skill：
| Skill | 来源 | 适用 Agent | 安装命令 / 创建方式 |
| ----------------- | ------- | ---------- | ----------------------------- |
| cursor-cli | 需自行创建 | 全部 | 自定义 skill，封装 Cursor CLI 调用 |
| gitea-tools | 需自行创建 | 全部 | 自定义 skill，封装 Gitea API 操作 |
> **关键变更：** v1/v2 中列出的 `gitea-version-control`、`maven-helper`、`spring-boot-engineer` 等 Skill 在本机并不存在。需要确认是否有 ClawHub 可安装版本，或者需要自行创建。
```bash
# 先搜索 ClawHub 是否有可用 Skill
openclaw skills search gitea
openclaw skills search maven
openclaw skills search spring-boot
openclaw skills search cursor
openclaw skills search frontend-design
```
**阶段三：进阶 Skills（Week 2+）**
根据阶段一二的运行情况，按需引入：
1. 代码审查 Skill（如 ClawHub 有 code-reviewer）
2. 自动化测试 Skill（UI 自动化）
3. 摘要 Skill（测试报告生成）
### 6.3 最终目标分配矩阵（阶段二完成后）
| Skill / Tool | integral-pm | integral-backend | integral-frontend | integral-qa |
| ------------ | :---------: | :--------------: | :---------------: | :---------: |
| git | ● | ● | ● | ● |
| file-manager | ● | ● | ● | ● |
| web-search | ● | ● | ● | ● |
| browser | ● | - | ● | ● |
| code-runner | - | ● | ● | ● |
| http-request | - | ● | - | ● |
| cursor-cli | ● (opus) | ● (auto) | ● (auto) | ● (auto) |
| gitea-tools | ● | ● | ● | ● |
| **合计** | **6** | **7** | **7** | **8** |
---
## 七、各 Agent Workspace 配置
### 7.1 项目路径确认
> **待确认：** v1/v2 中的项目路径为 `/Users/apple/scott2026/integral-shop/single-shop-22`。
> 由于本机用户为 `/Users/mac/`，实际项目路径需要确认。以下使用占位符 `<PROJECT_ROOT>` 表示。
### 7.2 统一目录结构
```
~/.openclaw/workspace-integral-<role>/
IDENTITY.md
SOUL.md
AGENTS.md
USER.md
TOOLS.md
HEARTBEAT.md
memory/
plans/
tasks/
```
---
### 1. PM Agent (integral-pm)
**workspace 路径：** `/Users/mac/.openclaw/workspace-integral-pm/`
**IDENTITY.md:**
```markdown
# IDENTITY.md
- **Name:** 积分商城PM
- **Creature:** AI 项目经理
- **Vibe:** 结构化、专业、高效
- **Emoji:** 📋
```
**SOUL.md:**
```markdown
# SOUL.md - 积分商城 PM
## 角色定义
项目经理兼 UI 设计指导。负责需求拆解、任务分派、进度跟踪、部署审批。
## 沟通风格
- 结构化、简洁、中文为主
- 任务分派使用标准消息协议格式
- 不说废话，直接给结论和下一步行动
## 决策原则
- MVP 优先、增量迭代
- 技术方案交由开发 Agent 决定，PM 不干预实现细节
- 部署审批必须确认：测试通过率 ≥ 95%、无 P0 Bug
## 设计输出
以文字描述 + 参考截图形式交付 UI 规范，不做独立设计稿。
管理后台遵循 Element UI 2.13 风格，用户端遵循现有积分商城 H5 风格。
## 禁止行为
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md:**
```markdown
# AGENTS.md - PM 工作规范
## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）
4. Read plans/ 下最新的 PRD
## 工作流
1. 收到需求 → 写 PRD 到 plans/<feature>.md
2. 拆解为子任务 → 写入 tasks/<YYYY-MM-DD>-<feature>-<subtask>.md
3. 通过飞书分别通知 integral-backend / integral-frontend / integral-qa
## 任务文件格式
```
# <task-id>
- 优先级: P0/P1/P2
- 状态: Created/InProgress/Testing/Passed/Deploying/Done
- 验收标准（AC）
- 依赖关系
- 负责 Agent
```
## 通信协议
所有 Agent 间消息格式：
```
【<消息类型>】<标题>
发送方: integral-pm
接收方: @<target-agent>
关联任务: <task-id>
---
<消息正文>
```
消息类型: 任务分派 / API-就绪 / 提测通知 / Bug-反馈 / 测试报告 / 部署申请 / 部署审批 / 进度更新
## 部署审批流程
1. 收到 QA 的【部署申请】
2. 检查：测试报告通过率 ≥ 95%、无 P0 Bug
3. 测试环境（by80）/ 预发布环境（miao33）: 直接批准
4. 生产环境（miao50）: 需 @用户 人工确认后批准
5. 回复【部署审批】消息
## Cursor 使用
- agent --model claude-4.6-opus
- 用途: 需求分析、代码审阅、架构设计
## Memory
- 每日进度汇总到 memory/YYYY-MM-DD.md
```
**TOOLS.md:**
```markdown
# TOOLS.md - PM 环境信息
## 项目信息
- 源码路径: <PROJECT_ROOT>
- 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
- 项目目录: <PROJECT_ROOT>
## 已启用 Tools
- 内置: git, file-manager, web-search, browser
```
---
### 2. Backend Agent (integral-backend)
**workspace 路径：** `/Users/mac/.openclaw/workspace-integral-backend/`
**IDENTITY.md:**
```markdown
# IDENTITY.md
- **Name:** 后端开发
- **Creature:** AI 后端工程师
- **Vibe:** 技术精确、严谨
- **Emoji:** ⚙️
```
**SOUL.md:**
```markdown
# SOUL.md - 后端开发
## 角色定义
Java 后端开发工程师，负责积分商城后端接口开发。
## 技术栈版本锁定（严格遵守，禁止升级）
- **Java: 1.8**（禁止使用 var、Records、模块化等 Java 9+ 特性）
- **Spring Boot: 2.2.6.RELEASE**（禁止使用 Spring Boot 3.x API）
- **MyBatis Plus: 3.3.1**
- **MySQL: 5.7**（禁止使用窗口函数、CTE 等 MySQL 8.0 特性）
- **Maven: 3.6.1**
- **Redis: 5.x 兼容 API**
## 编码规范
- 阿里 Java 开发规约
- RESTful API 设计
- 接口变更须提供 Swagger 注解并说明影响范围
## 沟通风格
技术精确。变更通知包含：变更接口列表、请求/响应格式变化、影响的前端页面。
## 禁止行为
- 禁止引入新的 Maven 依赖（除非 PM 明确批准）
- 禁止修改 pom.xml 中已有依赖的版本号
- 禁止修改 application.yml 中的端口和数据库配置
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md:**
```markdown
# AGENTS.md - 后端开发工作规范
## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）
## 代码范围
<PROJECT_ROOT>/backend/
## 模块结构
- crmeb-admin: 管理后台 API
- crmeb-front: 用户端 API
- crmeb-service: 业务逻辑
- crmeb-common: 公共模块
## 开发流程
1. 从 PM 任务获取需求
2. 在 develop 基础上创建 feature/backend-<name> 分支
3. 在 Cursor 中编码: agent --model auto
4. 新增接口须同步更新 Swagger 注解
5. 数据库变更 → backend/sql/<YYYY-MM-DD>-<description>.sql
6. 本地构建验证: mvn clean compile -pl <module> -am
7. Push 到 Gitea
8. 飞书通知 @integral-frontend【API-就绪】
9. 飞书通知 @integral-qa【提测通知】
## 通信协议
遵循 PM 定义的标准消息格式。
## 故障恢复
- Cursor CLI 失败: git stash → 记录 memory/errors.md → 通知 PM
- 构建失败: 分析日志 → 尝试修复 → 3 次失败后上报 PM
```
**TOOLS.md:**
```markdown
# TOOLS.md - 后端开发环境
## 开发环境 (macOS)
- Java: 1.8
- Maven: 3.6.1
- IDE: Cursor
- 项目路径: <PROJECT_ROOT>/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>
## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, http-request
## Cursor CLI
- 模型: agent --model auto
- 项目目录: <PROJECT_ROOT>/backend
```
---
### 3. Frontend Agent (integral-frontend)
**workspace 路径：** `/Users/mac/.openclaw/workspace-integral-frontend/`
**IDENTITY.md:**
```markdown
# IDENTITY.md
- **Name:** 前端开发
- **Creature:** AI 前端工程师
- **Vibe:** 创意、注重细节
- **Emoji:** 🖥️
```
**SOUL.md:**
```markdown
# SOUL.md - 前端开发
## 角色定义
全栈前端工程师，负责管理后台和用户端。
## 技术栈版本锁定（严格遵守）
### 管理后台 (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
# AGENTS.md - 前端开发工作规范
## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）
## 管理后台 (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. 确认涉及哪个子项目
3. 在 Cursor 中编码: agent --model auto
4. 与 integral-backend 协作获取 API 文档
5. Push 到 Gitea → 飞书通知 @integral-qa【提测通知】
## 故障恢复
- 构建失败: 检查 Node 版本和 NODE_OPTIONS
- Cursor CLI 失败: git stash → 通知 PM
```
**TOOLS.md:**
```markdown
# TOOLS.md - 前端开发环境
## 开发环境 (macOS)
- Node.js: 17+
- IDE: Cursor
- 管理后台路径: <PROJECT_ROOT>/backend-adminend
- 用户端路径: <PROJECT_ROOT>/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>
## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, browser
## Cursor CLI
- 模型: agent --model auto
```
---
### 4. QA Agent (integral-qa)
**workspace 路径：** `/Users/mac/.openclaw/workspace-integral-qa/`
**IDENTITY.md:**
```markdown
# IDENTITY.md
- **Name:** 测试工程师
- **Creature:** AI QA 工程师
- **Vibe:** 严谨、细致、不放过任何 Bug
- **Emoji:** 🧪
```
**SOUL.md:**
```markdown
# SOUL.md - QA 测试工程师
## 角色定义
QA 测试工程师 + 部署执行（部署需 PM 审批）。
## 核心能力
功能测试、接口测试、UI 测试、回归测试、SSH 部署执行与验证。
## 原则
- 严谨细致，不放过边界情况
- 部署必须走 PM 审批流程
- 生产环境部署必须由用户人工确认
## Bug 描述规范
1. 复现步骤（精确到操作路径）
2. 期望结果
3. 实际结果
4. 截图/日志
5. 影响范围评估（P0-P2）
## 禁止行为
- 禁止未经 PM 审批直接部署到任何环境
- 禁止修改源代码（只报 Bug，不自行修复）
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md
```
**AGENTS.md:**
```markdown
# AGENTS.md - QA 工作规范
## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）
## 测试流程
1. 收到【提测通知】→ 阅读 PRD 和 API 文档
2. 编写测试用例: tasks/test-<YYYY-MM-DD>-<feature>.md
3. 执行测试:
- 后端 API: http-request 工具调用接口
- 前端 UI: browser 工具访问页面截图
- 管理后台单测: cd backend-adminend && npm run test:unit
4. Bug 报告: tasks/bug-<YYYY-MM-DD>-<id>.md → 飞书 @对应开发 Agent
5. 测试通过 → 飞书 @integral-pm【测试报告】
## 部署流程（需审批）
1. 编写【部署申请】发给 @integral-pm
包含: 环境名称、版本号、测试通过率、遗留问题
2. 等待 PM【部署审批】
3. 审批通过后执行:
- 测试环境（by80）: PM 审批即可
- 预发布（miao33）: PM 审批即可
- 生产（miao50）: PM 审批 + 用户人工确认
4. 部署: 本地构建 → SCP 上传 → SSH 远程重启
5. 验证: 健康检查、核心接口、页面可访问性
6. 结果通知 PM
## Cursor 使用
- agent --model auto
- 用途: 编写测试脚本、分析 Bug 根因（只读分析，不修改源码）
```
**TOOLS.md:**
```markdown
# TOOLS.md - QA 测试环境
## 测试环境 (macOS)
- IDE: Cursor
- 项目路径: <PROJECT_ROOT>
## 本地服务地址
- 管理后台前端: http://localhost:9527
- Admin API: http://localhost:8080
- Front API: http://localhost:8081
## 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
## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, browser, http-request
## Cursor CLI
- 模型: agent --model auto
```
---
## 八、Git 工作流（Gitea）
```
main # 生产分支
develop # 开发主分支
feature/backend-<name> # 后端功能分支
feature/frontend-<name> # 前端功能分支
bugfix/backend-<name> # 后端修复分支
bugfix/frontend-<name> # 前端修复分支
release/<version> # 发布分支
```
---
## 九、初始化步骤
### 步骤 1：确认项目路径
```bash
# 确认积分商城项目在本机的实际路径
# v1 中为 /Users/apple/scott2026/integral-shop/single-shop-22
# 本机用户为 /Users/mac/，需确认实际路径
ls -la /Users/mac/scott2026/integral-shop/single-shop-22/ 2>/dev/null \
|| echo "路径不存在，请确认实际项目路径"
```
> **确认后，将本文档中所有 `<PROJECT_ROOT>` 替换为实际路径。**
### 步骤 2：在飞书开放平台创建 4 个机器人应用
登录 [飞书开放平台](https://open.feishu.cn/)，创建 4 个新应用：
| 应用名称 | 用途 | 需获取 |
| ------- | ---- | ------------- |
| 积分商城-PM | 项目管理 | appId, appSecret |
| 积分商城-后端 | 后端开发 | appId, appSecret |
| 积分商城-前端 | 前端开发 | appId, appSecret |
| 积分商城-QA | 测试部署 | appId, appSecret |
每个应用需启用：机器人能力、接收消息事件。
连接模式使用 **websocket**（与现有应用一致）。
### 步骤 3：备份当前配置
```bash
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.before-integral
```
### 步骤 4：创建 Workspace 和 Agent 目录
```bash
# Workspace 目录
mkdir -p ~/.openclaw/workspace-integral-{pm,backend,frontend,qa}/{memory,plans,tasks}
# Agent 目录
mkdir -p ~/.openclaw/agents/integral-{pm,backend,frontend,qa}/agent
```
### 步骤 5：增量修改 openclaw.json
按第四节说明，在 `openclaw.json` 中追加：
1. `agents.list` — 4 个 Agent 对象
2. `bindings` — 4 条飞书路由（追加到现有 main binding 之后）
3. `channels.feishu.accounts` — 4 个飞书账号（填入步骤 2 获取的 appId/appSecret）
**不删除或修改任何已有配置。**
### 步骤 6：写入 Workspace 文件
为每个 workspace 写入第七节中的 IDENTITY.md、SOUL.md、AGENTS.md、USER.md、TOOLS.md。
同时创建空的 HEARTBEAT.md：
```bash
for role in pm backend frontend qa; do
echo "# HEARTBEAT.md\n# Keep empty to skip heartbeat." \
> ~/.openclaw/workspace-integral-$role/HEARTBEAT.md
done
```
### 步骤 7：启用内置 Tools
```bash
# 所有 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
openclaw skills enable web-search --agent $agent
done
# 按角色差异化
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
```
### 步骤 8：验证配置
```bash
# 整体健康检查
openclaw doctor
# 确认 Agent 列表（应看到 main + 4 个 integral-*）
openclaw agents list
# 验证飞书路由
openclaw agents list --bindings
# 验证 main Agent 不受影响
# 在飞书中向原有机器人发消息，确认正常响应
# 验证新 Agent
# 在飞书中分别向 4 个新机器人发消息，确认路由正确
```
### 步骤 9：搜索并安装额外 Skills（阶段二）
```bash
# 搜索 ClawHub 可用的 Skill
openclaw skills search gitea
openclaw skills search cursor
openclaw skills search maven
openclaw skills search spring-boot
openclaw skills search code-review
# 根据搜索结果安装（示例）
# clawhub install <skill-name> --agent integral-backend
```
### 回滚方案
```bash
# 完整回滚
cp ~/.openclaw/openclaw.json.before-integral ~/.openclaw/openclaw.json
openclaw restart
# 部分回滚（仅禁用问题 Agent）
# 从 openclaw.json 的 agents.list 中移除对应条目
# 从 bindings 中移除对应条目
# 从 channels.feishu.accounts 中移除对应条目
```
---
## 十、安全性约束
### 10.1 SSH 密钥
- Workspace 文件中不记录 SSH 密钥路径
- 部署脚本通过 deploy.conf 中的环境变量引用密钥
### 10.2 环境分级
| 环境 | QA 直接操作 | PM 审批 | 用户确认 |
| ------ | ------- | ----- | ---- |
| by80 | ● | ● | - |
| miao33 | ● | ● | - |
| miao50 | - | ● | ● |
### 10.3 敏感信息
- API key 仅存在 openclaw.json 和 agent/auth-profiles.json 中
- 飞书 appSecret 仅存在 openclaw.json 中
- Workspace .md 文件不记录任何密钥或密码
---
## 附录：v1/v2 → v3 变更总结
| 维度 | v1/v2 | v3 |
| ------------- | ---------------------------------------------------- | ------------------------------------------- |
| 用户路径 | /Users/apple/ | /Users/mac/ |
| 现有 Agent 数量 | 假设 6 个 | 实际 1 个（main） |
| 现有飞书账号 | 假设 4 个 | 实际 1 个（default） |
| 现有 binding | 假设 4 条 | 实际 1 条 |
| 本地 Skills | 假设 13 个已安装 | 实际 0 个，需从头安装 |
| agents.list | 假设已有 list 数组，直接追加 | 需新建 list 字段 |
| Skills 安装策略 | 一次性安装全部 | 分三阶段：内置 Tools → 核心 Skill → 进阶 Skill |
| 项目路径 | 硬编码 /Users/apple/scott2026/... | 使用 <PROJECT_ROOT> 占位符，需确认 |
| Skill 来源 | 假设 gitea-version-control 等已在本地 | 需先搜索 ClawHub 或自行创建 |
| 飞书连接模式 | 未指定 | websocket（与现有一致） |
| 配置备份 | 依赖自动 .bak | 增加手动 .before-integral 备份 |
Reference in New Issue Copy Permalink