Harness 多智能体 Web 应用构建插件。Command 作为 Harness 主控，以 claude -p 独立进程调度智能体。 技术栈固定：Spring Boot 3 + SQLite（后端）、React 18 + Vite（前端），无任何外部依赖。
graph TB
User(["👤 /build-app <需求>"]) --> CMD
subgraph CMD ["📋 build-app Command（Harness 主控）\n负责流程控制，不写任何业务代码"]
direction TB
Init["初始化\n.web-app-builder/ 目录\nbuild-state.json"]
Init --> P["claude -p\n🧠 需求规划师\n扩展需求 → product-spec.md\nfeature_list.json（passes 全 false）"]
P --> A["claude -p\n🏗️ 架构师\n设计数据模型、API、路由\n生成项目脚手架\narchitecture.md + start-dev.sh"]
A --> D["claude -p\n📋 任务拆解师\ntask-list.json（Sprint 划分）\napi-contract.md（接口契约）\nfeature_list.json（填 sprint 字段）"]
D --> Loop
subgraph Loop ["🔄 Ralph Loop — while PENDING Sprint exists"]
direction TB
Dev["claude -p\n💻 全栈开发者\n后端：Spring Boot 3 + SQLite\n前端：React 18 + data-testid\nPlaywright 测试文件编写\ndev-complete.json"]
Dev --> Rev["claude -p\n🔍 代码审查员\n接口契约符合性\ndata-testid 完整性\n无外部依赖检查\nreview-result.json"]
Rev --> RG{审查通过?}
RG -->|"❌ CHANGES_REQUESTED"| Dev
RG -->|"✅ APPROVED"| PW
PW["🧪 主控直接运行\nnpx playwright test\nsprint-N.spec.ts\n真实执行，输出 test-report.json"]
PW --> TG{测试通过?}
TG -->|"❌ 失败明细写入\nrejection-feedback.md\nSprint → PENDING"| Dev
TG -->|"✅ 全部通过"| Acc
Acc["claude -p\n🎯 产品验收官\n对照产品规格逐条核验\n抽查 smoke test\nacceptance-result.json"]
Acc --> AG{验收通过?}
AG -->|"❌ blocking_issues\n→ rejection-feedback.md\nSprint → PENDING"| RetryCheck
AG -->|"✅ ACCEPTED\nfeature passes = true"| SprintOK["Sprint 完成 ✅"]
RetryCheck{revert_count\n≥ 3?}
RetryCheck -->|否| Dev
RetryCheck -->|"是\nneeds_human_intervention=true"| Stop["⚠️ 暂停，等待人工介入"]
end
SprintOK --> NextCheck{还有\nPENDING?}
NextCheck -->|是| Loop
NextCheck -->|否| Final["📊 输出最终报告\n功能完成率统计"]
end
Final --> Done(["🎉 应用就绪\n前端 :3000 / 后端 :8080"])
sequenceDiagram
participant CMD as build-app Command
participant Dev as 全栈开发者进程
participant PW as Playwright（本机）
participant Acc as 产品验收官进程
CMD->>Dev: claude -p "开发 Sprint N"
Dev-->>CMD: 生成代码 + tests/sprint-N.spec.ts
Note over Dev: 进程退出，上下文销毁
CMD->>CMD: 读取 dev-complete.json，确认测试文件存在
CMD->>PW: npx playwright test sprint-N.spec.ts
Note over PW: 真实浏览器执行，非模拟
PW-->>CMD: test-report.json（实测结果）
CMD->>Acc: claude -p "验收 Sprint N"（附测试报告）
Note over Acc: 独立进程，基于真实测试结果决策
Acc-->>CMD: acceptance-result.json
Note over Acc: 进程退出，上下文销毁
graph LR
subgraph "每个 claude -p 调用 = 独立进程 + 独立上下文"
P1["需求规划师\n只知道：用户需求"]
P2["架构师\n只知道：product-spec.md"]
P3["任务拆解师\n只知道：规格 + 架构"]
P4["全栈开发者\n只知道：Sprint任务 + 架构 + 反馈"]
P5["代码审查员\n只知道：代码文件 + 契约"]
P6["产品验收官\n只知道：规格 + 测试报告"]
end
FS[("📁 文件系统\n唯一共享状态")]
P1 -->|写| FS
P2 -->|读写| FS
P3 -->|读写| FS
P4 -->|读写| FS
P5 -->|读写| FS
P6 -->|读写| FS
# 1. 安装插件(本地)
claude plugin marketplace add ./web-app-builder
claude plugin install web-app-builder
/reload-plugins
# 2. 启动构建
/build-app 做一个任务管理系统，支持创建、完成、删除待办事项
# 3. 查看进度
/build-status
# 4. 中断后继续
/build-resume| 技术 | 约束 | |
|---|---|---|
| 后端 | Spring Boot 3 + SQLite | 禁止 MySQL/Redis/MQ 等外部依赖 |
| 前端 | React 18 + Vite | 禁止 antd/MUI/Redux 等重型库 |
| 测试 | Playwright | 必须覆盖每个按钮、接口、状态 |
| 持久化 | SQLite 文件（./data/app.db） |
无需安装任何数据库服务 |
.web-app-builder/
├── build-state.json # 全局状态机
├── product-spec.md # 产品规格
├── architecture.md # 架构方案（数据模型、API、路由）
├── feature_list.json # 功能清单（passes 字段 = 进度真相）
├── task-list.json # Sprint 任务清单
├── api-contract.md # 接口契约
├── start-dev.sh # 启动开发环境脚本
├── playwright.config.ts # Playwright 配置
├── package.json # Playwright 依赖
├── tests/
│ ├── sprint-1.spec.ts # Sprint 1 的 Playwright 测试（开发者编写）
│ └── sprint-2.spec.ts
├── sprints/
│ └── 1/
│ ├── dev-complete.json
│ ├── review-result.json
│ ├── test-report.json # 主控实际执行 Playwright 产出
│ ├── acceptance-result.json
│ └── rejection-feedback.md # 失败反馈（给下一轮开发者）
└── logs/
backend/ # Spring Boot 3 项目
frontend/ # React 18 + Vite 项目
