web-app-builder

Web App Builder v3

english

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"])

关键设计：Command 直接执行 Playwright

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 项目