From 36a0ae1afd2117567c644b60991c430329d44cdd Mon Sep 17 00:00:00 2001 From: Xiaoxia AI Date: Tue, 23 Jun 2026 14:34:01 +0800 Subject: [PATCH] docs(agents): establish automated eight-agent workflow --- docs/agents/AGENT-BOARD.md | 45 ++++++ docs/agents/AUTO-RUN-PROTOCOL.md | 94 +++++++++++ docs/agents/README.md | 14 ++ docs/agents/RUNBOOK.md | 207 +++++++++++++++++++++++++ docs/agents/checklists/general.md | 57 +++++++ docs/agents/roles/arch_agent.md | 19 +++ docs/agents/roles/build_pack_agent.md | 19 +++ docs/agents/roles/code_dev_agent.md | 19 +++ docs/agents/roles/lint_review_agent.md | 18 +++ docs/agents/roles/ops_monitor_agent.md | 19 +++ docs/agents/roles/release_agent.md | 20 +++ docs/agents/roles/requirement_agent.md | 20 +++ docs/agents/roles/test_agent.md | 18 +++ tests/unit/test_agent_docs.py | 35 +++++ 14 files changed, 604 insertions(+) create mode 100644 docs/agents/AGENT-BOARD.md create mode 100644 docs/agents/AUTO-RUN-PROTOCOL.md create mode 100644 docs/agents/README.md create mode 100644 docs/agents/RUNBOOK.md create mode 100644 docs/agents/checklists/general.md create mode 100644 docs/agents/roles/arch_agent.md create mode 100644 docs/agents/roles/build_pack_agent.md create mode 100644 docs/agents/roles/code_dev_agent.md create mode 100644 docs/agents/roles/lint_review_agent.md create mode 100644 docs/agents/roles/ops_monitor_agent.md create mode 100644 docs/agents/roles/release_agent.md create mode 100644 docs/agents/roles/requirement_agent.md create mode 100644 docs/agents/roles/test_agent.md create mode 100644 tests/unit/test_agent_docs.py diff --git a/docs/agents/AGENT-BOARD.md b/docs/agents/AGENT-BOARD.md new file mode 100644 index 000000000..b0da6d0dd --- /dev/null +++ b/docs/agents/AGENT-BOARD.md @@ -0,0 +1,45 @@ +# 小虾 SaaS 8 Agent 状态板 + +## 当前模式 + +- 执行模式：全自动执行，遇到高风险/费用/不可逆/方向变化/需要人工资料时暂停请示。 +- 当前阶段：稳定化体系落地。 +- 当前主线：先建立执行机制和 Playwright E2E，再继续新功能。 +- 禁止事项：不得修改 OpenClaw 自身配置、人格、记忆和启动规则文件。 + +## 8 Agent 状态 + +| Agent | 当前状态 | 当前任务 | 输出物 | 阻塞 | +| --- | --- | --- | --- | --- | +| `requirement_agent` | in_progress | 固化全自动授权范围、暂停条件、验收标准 | `docs/agents/AUTO-RUN-PROTOCOL.md` | 无 | +| `arch_agent` | pending | 设计 Playwright E2E 与 OSS 直传架构方案 | 待输出 | 等 requirement 完成 | +| `code_dev_agent` | pending | 按架构实现 E2E/上传链路/必要修复 | 待输出 | 等 arch 完成 | +| `lint_review_agent` | pending | 审查规则文件、代码改动和风险 | 待输出 | 等 code_dev 完成 | +| `test_agent` | pending | 接入 Playwright E2E，固化核心流程测试 | 待输出 | 等 code_dev 完成 | +| `build_pack_agent` | pending | 构建前端、校验发布产物 | 待输出 | 等 test 完成 | +| `release_agent` | pending | 发版、部署、版本验证 | 待输出 | 等 build_pack 完成 | +| `ops_monitor_agent` | pending | 生产日志、资源、duty_report、告警检查 | 待输出 | 等 release 完成 | + +## 当前核心验收目标 + +1. Playwright 能自动完成真实浏览器流程：登录 → 工作空间 → 项目 → 上传 MOV → 素材 ready → 页面无加载失败。 +2. 核心主流程保持可用：登录、工作空间、项目、上传、生成、下载。 +3. 每次发版前后都有自动门禁记录。 +4. 生产关键问题不再由老大首先人工发现。 + +## 最近关键事实 + +- 生产当前验证版本：`v0.1.20`。 +- 上传上限已提升到 `800MB`。 +- 前端上传 timeout 已提升到 30 分钟。 +- Worker 已修复：ingest 完成后素材写为 `ready`。 +- 历史卡在 `uploading` 的素材已回填为 `ready`。 +- `.MOV` 历史类型异常已回填为 `video`。 + +## 下一步队列 + +1. 完成 Agent Runbook。 +2. 接入 Playwright E2E。 +3. 写第一个浏览器上传 MOV 用例。 +4. 将 E2E 纳入发布门禁。 +5. 设计 OSS 直传上传方案。 diff --git a/docs/agents/AUTO-RUN-PROTOCOL.md b/docs/agents/AUTO-RUN-PROTOCOL.md new file mode 100644 index 000000000..f9980233b --- /dev/null +++ b/docs/agents/AUTO-RUN-PROTOCOL.md @@ -0,0 +1,94 @@ +# 小虾 SaaS 全自动执行协议 + +## 目标 + +把小虾 SaaS 的开发方式从“半自动逐步请示”改为“目标授权后全自动执行”。老大只确认方向、范围和验收目标；小虾在授权范围内连续完成分析、开发、测试、构建、发布、监控和汇报。 + +## 固定 8 Agent + +本项目只使用规则文档定义的 8 个 Agent 名称： + +1. `requirement_agent`：需求确认、范围冻结、验收标准 +2. `arch_agent`：架构方案、风险收敛、数据流/权限边界 +3. `code_dev_agent`：前端、后端、Worker、脚本实现 +4. `lint_review_agent`：代码规范、Review、安全和回归风险检查 +5. `test_agent`：单测、集成测试、Playwright E2E、公网 smoke +6. `build_pack_agent`：前端 build、镜像构建、产物校验、包完整性 +7. `release_agent`：tag、部署、版本一致性、上线验证 +8. `ops_monitor_agent`：生产巡检、日志、资源、告警和回滚建议 + +## 默认自动授权范围 + +当老大明确给出目标（例如“按全自动模式执行”“修复上传链路并上线验证”“启动开发包 2”）后，小虾默认可以自动执行以下动作： + +- 阅读项目代码、文档、日志和生产状态。 +- 修改 `F:\openclaw-saas` 项目内代码、测试、脚本和文档。 +- 新增必要测试、smoke、Playwright E2E 和发布检查。 +- 本地运行测试、构建、lint、smoke。 +- 提交到 `develop`。 +- 在测试通过后打 tag、触发发布、部署生产。 +- 运行公网 smoke、生产 health、日志检查和巡检。 +- 对明确可恢复、低风险的生产配置热修做备份后执行。 +- 对明显错误的派生数据做可审计回填，例如把已完成 ingest 的素材状态从 `uploading` 修为 `ready`。 +- 更新项目状态板、Runbook、发布记录和 UAT 记录。 + +## 必须暂停请示的情况 + +以下情况必须暂停并向老大说明风险、选项和推荐方案： + +- 涉及新增费用、扩容、购买云资源或启用付费服务。 +- 删除生产数据、删除备份、清库、重置仓库、不可逆清理。 +- 新增、暴露、轮换或修改敏感密钥、账号、安全策略。 +- 改变产品方向、MVP 范围、商业策略或砍掉已确认能力。 +- 高风险停机、数据库迁移、服务器重装、跨主机迁移。 +- 需要老大提供验证码、真实文件、云控制台操作或人工验收材料。 +- 自动修复连续 3 轮仍失败，且无法通过本地/生产证据继续收敛。 + +## 执行循环 + +每个目标按以下循环推进，默认不中途请示： + +```text +requirement_agent + → arch_agent + → code_dev_agent + → lint_review_agent + → test_agent + → build_pack_agent + → release_agent + → ops_monitor_agent +``` + +如果任一阶段失败： + +1. 记录失败证据。 +2. 回到对应 Agent 修复。 +3. 重新运行该阶段及之后所有门禁。 +4. 最多自动重试 3 轮。 +5. 仍失败才向老大汇报阻塞点。 + +## 完成标准 + +小虾不能只说“修好了”。完成必须同时满足： + +- 相关单元测试通过。 +- 前端改动通过 build。 +- 真实浏览器 Playwright E2E 通过，若任务涉及 UI。 +- 公网 smoke 通过，若任务涉及生产主流程。 +- 生产 `/health` 版本与目标版本一致，若发版。 +- 生产日志无新增关键 4xx/5xx/499 异常，若发版或热修。 +- Agent Board 已更新当前状态、证据和下一步。 + +## 配置文件保护 + +除非老大明确授权，小虾不得修改 OpenClaw/自身配置和人格/记忆规则文件，包括但不限于： + +- `AGENTS.md` +- `SOUL.md` +- `MEMORY.md` +- `USER.md` +- `TOOLS.md` +- `META.md` +- OpenClaw 运行时配置文件 + +日常开发只修改 `F:\openclaw-saas` 项目文件。记忆刷新只允许按用户明确要求追加到指定 `memory/YYYY-MM-DD.md`。 diff --git a/docs/agents/README.md b/docs/agents/README.md new file mode 100644 index 000000000..7b9c1007b --- /dev/null +++ b/docs/agents/README.md @@ -0,0 +1,14 @@ +# 8 Agent 角色索引 + +本目录只使用规则文档定义的固定 8 Agent： + +- `requirement_agent` +- `arch_agent` +- `code_dev_agent` +- `lint_review_agent` +- `test_agent` +- `build_pack_agent` +- `release_agent` +- `ops_monitor_agent` + +每个任务必须先更新 `docs/agents/AGENT-BOARD.md`，再按 `docs/agents/RUNBOOK.md` 流转。 diff --git a/docs/agents/RUNBOOK.md b/docs/agents/RUNBOOK.md new file mode 100644 index 000000000..136e0374c --- /dev/null +++ b/docs/agents/RUNBOOK.md @@ -0,0 +1,207 @@ +# 小虾 SaaS 8 Agent Runbook + +## 目的 + +本 Runbook 规定每个开发、修复、发布任务必须如何在 8 Agent 之间流转，避免临时散修、重复返工和生产上才暴露基础问题。 + +## 标准流转 + +```text +requirement_agent + → arch_agent + → code_dev_agent + → lint_review_agent + → test_agent + → build_pack_agent + → release_agent + → ops_monitor_agent +``` + +## 1. requirement_agent + +### 输入 + +- 老大的目标或问题反馈。 +- 当前 Phase / 开发包文档。 +- 生产现状和已知风险。 + +### 必须输出 + +- 本轮目标。 +- 范围内事项。 +- 范围外事项。 +- 验收标准。 +- 是否需要老大拍板。 + +### 阻止继续的条件 + +- 目标不清楚。 +- 涉及费用、不可逆操作、产品方向变化。 +- 验收标准不可验证。 + +## 2. arch_agent + +### 输入 + +- requirement_agent 的目标和验收标准。 +- 现有架构、数据流、权限边界、部署约束。 + +### 必须输出 + +- 根因分析或架构方案。 +- 涉及模块清单。 +- 数据流和失败路径。 +- 风险和回滚方案。 + +### 阻止继续的条件 + +- 方案只是表面补丁，不能解释根因。 +- 涉及生产高风险但无回滚方案。 +- 跨模块影响未列出。 + +## 3. code_dev_agent + +### 输入 + +- arch_agent 方案。 +- 相关代码和测试。 + +### 必须输出 + +- 最小必要代码改动。 +- 对应测试或测试待办。 +- 数据修复脚本（如需要）。 +- 不相关问题清单。 + +### 阻止继续的条件 + +- 改动超出需求范围。 +- 未处理核心异常路径。 +- 引入假成功、假入口或不可观测状态。 + +## 4. lint_review_agent + +### 输入 + +- code_dev_agent 的 diff。 +- 项目规范、权限边界、安全要求。 + +### 必须输出 + +- Review 结论：通过 / 需修改。 +- 安全和权限风险。 +- 回归风险。 +- 是否允许进入测试。 + +### 阻止继续的条件 + +- 权限边界不清。 +- 错误处理不明确。 +- 生产配置或密钥风险。 + +## 5. test_agent + +### 输入 + +- 已 review 的代码。 +- 验收标准。 + +### 必须输出 + +- 单元测试结果。 +- 集成/smoke 结果。 +- Playwright E2E 结果（涉及 UI 时必须）。 +- 失败截图、trace、日志（失败时）。 + +### 阻止继续的条件 + +- 相关测试失败。 +- UI 流程未通过真实浏览器验证。 +- 修复没有对应回归测试。 + +## 6. build_pack_agent + +### 输入 + +- 测试通过的代码。 +- 发布配置和构建脚本。 + +### 必须输出 + +- 前端 build 结果。 +- runtime image / release artifact 校验。 +- 构建环境确认。 +- 产物版本确认。 + +### 阻止继续的条件 + +- 生产机需要构建 API/Worker。 +- 产物缺失或版本不一致。 +- 构建脚本与发布约束冲突。 + +## 7. release_agent + +### 输入 + +- build_pack_agent 产物。 +- release checklist。 + +### 必须输出 + +- commit / tag。 +- 部署结果。 +- `/health` 版本。 +- 公网 smoke 结果。 +- 回滚点。 + +### 阻止继续的条件 + +- 部署失败。 +- health 版本不一致。 +- 公网 smoke 失败。 +- 回滚点缺失。 + +## 8. ops_monitor_agent + +### 输入 + +- release_agent 的生产版本。 +- 生产日志、资源、巡检报告。 + +### 必须输出 + +- Web/API/Worker/DB/Redis 状态。 +- 4xx/5xx/499 新增异常。 +- CPU/内存/磁盘/负载状态。 +- 是否进入观察期或回滚。 + +### 阻止继续的条件 + +- 生产关键告警未解释。 +- 资源不足影响可用性。 +- 用户主流程仍失败。 + +## 自动重试规则 + +- 每个失败最多自动修复 3 轮。 +- 每轮必须记录失败证据和修复动作。 +- 第 3 轮后仍失败，暂停并向老大汇报。 + +## 每轮交付报告格式 + +```text +目标：... +版本/提交：... +8 Agent 状态： +- requirement_agent: ... +- arch_agent: ... +- code_dev_agent: ... +- lint_review_agent: ... +- test_agent: ... +- build_pack_agent: ... +- release_agent: ... +- ops_monitor_agent: ... +验证证据：... +遗留风险：... +下一步：... +``` diff --git a/docs/agents/checklists/general.md b/docs/agents/checklists/general.md new file mode 100644 index 000000000..271daf5b4 --- /dev/null +++ b/docs/agents/checklists/general.md @@ -0,0 +1,57 @@ +# 8 Agent 通用检查清单 + +## requirement_agent + +- [ ] 目标清楚 +- [ ] 范围内/范围外明确 +- [ ] 验收标准可自动验证 +- [ ] 不涉及必须请示项，或已请示 + +## arch_agent + +- [ ] 说明根因或架构方案 +- [ ] 列出涉及模块 +- [ ] 列出失败路径 +- [ ] 有回滚或降级方案 + +## code_dev_agent + +- [ ] 改动聚焦根因 +- [ ] 不引入假成功 +- [ ] 不修改无关文件 +- [ ] 必要测试已补 + +## lint_review_agent + +- [ ] 权限边界无回退 +- [ ] 错误处理可观测 +- [ ] 无密钥/配置泄露 +- [ ] 无明显回归风险 + +## test_agent + +- [ ] 单元测试通过 +- [ ] 前端相关改动已 build +- [ ] UI 相关改动有 Playwright E2E +- [ ] 生产 bug 有回归测试 + +## build_pack_agent + +- [ ] 构建产物存在 +- [ ] 版本号一致 +- [ ] 生产机不构建 API/Worker +- [ ] artifact 可部署 + +## release_agent + +- [ ] tag/commit 明确 +- [ ] 部署完成 +- [ ] `/health` 版本正确 +- [ ] 公网 smoke 通过 + +## ops_monitor_agent + +- [ ] Web/API/Worker/DB/Redis 正常 +- [ ] 无新增关键 4xx/5xx/499 +- [ ] 资源状态可接受 +- [ ] duty_report 无关键告警 diff --git a/docs/agents/roles/arch_agent.md b/docs/agents/roles/arch_agent.md new file mode 100644 index 000000000..d47815fed --- /dev/null +++ b/docs/agents/roles/arch_agent.md @@ -0,0 +1,19 @@ +# arch_agent + +## 职责 + +- 给出架构方案和根因解释。 +- 明确数据流、权限边界、失败路径和回滚方案。 +- 阻止只修表象的补丁式改动。 + +## 输入 + +- requirement_agent 输出。 +- 当前代码结构、部署约束、生产证据。 + +## 输出 + +- 方案说明。 +- 涉及模块。 +- 风险和回滚。 +- 是否允许进入开发。 diff --git a/docs/agents/roles/build_pack_agent.md b/docs/agents/roles/build_pack_agent.md new file mode 100644 index 000000000..d66ff3f3b --- /dev/null +++ b/docs/agents/roles/build_pack_agent.md @@ -0,0 +1,19 @@ +# build_pack_agent + +## 职责 + +- 构建前端和发布产物。 +- 校验 runtime image、release artifact 和版本一致性。 +- 确保生产机不构建 API/Worker。 + +## 输入 + +- test_agent 通过的代码。 +- 发布脚本和构建配置。 + +## 输出 + +- build 结果。 +- artifact 清单。 +- 构建风险。 +- 是否允许发布。 diff --git a/docs/agents/roles/code_dev_agent.md b/docs/agents/roles/code_dev_agent.md new file mode 100644 index 000000000..549a60e87 --- /dev/null +++ b/docs/agents/roles/code_dev_agent.md @@ -0,0 +1,19 @@ +# code_dev_agent + +## 职责 + +- 实现前端、后端、Worker、脚本和文档改动。 +- 保持改动最小、聚焦根因。 +- 不制造假成功、假入口或不可观测状态。 + +## 输入 + +- arch_agent 方案。 +- 相关代码和测试。 + +## 输出 + +- 代码 diff。 +- 测试更新。 +- 数据修复脚本（如需要）。 +- 不相关问题记录。 diff --git a/docs/agents/roles/lint_review_agent.md b/docs/agents/roles/lint_review_agent.md new file mode 100644 index 000000000..cc9ea7e4c --- /dev/null +++ b/docs/agents/roles/lint_review_agent.md @@ -0,0 +1,18 @@ +# lint_review_agent + +## 职责 + +- 审查代码规范、安全、权限边界和回归风险。 +- 判断是否允许进入测试。 + +## 输入 + +- code_dev_agent diff。 +- 项目规则和安全要求。 + +## 输出 + +- Review 结论。 +- 风险清单。 +- 必须修复项。 +- 是否放行。 diff --git a/docs/agents/roles/ops_monitor_agent.md b/docs/agents/roles/ops_monitor_agent.md new file mode 100644 index 000000000..58278c684 --- /dev/null +++ b/docs/agents/roles/ops_monitor_agent.md @@ -0,0 +1,19 @@ +# ops_monitor_agent + +## 职责 + +- 监控生产 Web/API/Worker/DB/Redis。 +- 检查 4xx/5xx/499、资源、磁盘、duty_report。 +- 判断是否观察、继续、回滚或告警。 + +## 输入 + +- release_agent 发布结果。 +- 生产日志和巡检报告。 + +## 输出 + +- 生产健康结论。 +- 新增异常。 +- 资源风险。 +- 下一步建议。 diff --git a/docs/agents/roles/release_agent.md b/docs/agents/roles/release_agent.md new file mode 100644 index 000000000..490d5196b --- /dev/null +++ b/docs/agents/roles/release_agent.md @@ -0,0 +1,20 @@ +# release_agent + +## 职责 + +- 创建 tag、触发部署、验证生产版本。 +- 运行公网 smoke。 +- 保留回滚点和发布记录。 + +## 输入 + +- build_pack_agent 产物。 +- release checklist。 + +## 输出 + +- commit/tag。 +- 部署结果。 +- health/version。 +- 公网 smoke 结果。 +- 回滚信息。 diff --git a/docs/agents/roles/requirement_agent.md b/docs/agents/roles/requirement_agent.md new file mode 100644 index 000000000..c830cf756 --- /dev/null +++ b/docs/agents/roles/requirement_agent.md @@ -0,0 +1,20 @@ +# requirement_agent + +## 职责 + +- 确认目标、范围和验收标准。 +- 判断是否需要老大拍板。 +- 防止任务范围膨胀和临时散修。 + +## 输入 + +- 老大的需求或问题反馈。 +- 当前 Phase / 开发包文档。 +- `docs/agents/AGENT-BOARD.md` 当前状态。 + +## 输出 + +- 本轮目标。 +- 范围内 / 范围外。 +- 可验证验收标准。 +- 是否进入全自动执行。 diff --git a/docs/agents/roles/test_agent.md b/docs/agents/roles/test_agent.md new file mode 100644 index 000000000..cdd8be00a --- /dev/null +++ b/docs/agents/roles/test_agent.md @@ -0,0 +1,18 @@ +# test_agent + +## 职责 + +- 运行并维护单元测试、集成测试、公网 smoke 和 Playwright E2E。 +- UI 相关改动必须通过真实浏览器验证。 +- 每个生产 bug 必须补回归测试。 + +## 输入 + +- lint_review_agent 放行的代码。 +- 验收标准。 + +## 输出 + +- 测试命令和结果。 +- E2E 截图/trace/录像（失败时）。 +- 是否允许构建。 diff --git a/tests/unit/test_agent_docs.py b/tests/unit/test_agent_docs.py new file mode 100644 index 000000000..c23b26a76 --- /dev/null +++ b/tests/unit/test_agent_docs.py @@ -0,0 +1,35 @@ +from pathlib import Path + +AGENT_DOCS = Path("docs/agents") +EXPECTED_AGENTS = [ + "requirement_agent", + "arch_agent", + "code_dev_agent", + "lint_review_agent", + "test_agent", + "build_pack_agent", + "release_agent", + "ops_monitor_agent", +] + + +def test_agent_docs_use_canonical_eight_agents(): + combined = "\n".join(path.read_text(encoding="utf-8") for path in AGENT_DOCS.rglob("*.md")) + + for agent in EXPECTED_AGENTS: + assert agent in combined + + +def test_agent_runbook_defines_required_flow_order(): + runbook = (AGENT_DOCS / "RUNBOOK.md").read_text(encoding="utf-8") + positions = [runbook.index(agent) for agent in EXPECTED_AGENTS] + + assert positions == sorted(positions) + + +def test_auto_run_protocol_protects_openclaw_self_config_files(): + protocol = (AGENT_DOCS / "AUTO-RUN-PROTOCOL.md").read_text(encoding="utf-8") + + for filename in ["AGENTS.md", "SOUL.md", "MEMORY.md", "USER.md", "TOOLS.md", "META.md"]: + assert filename in protocol + assert "不得修改 OpenClaw" in protocol