# web-harness

**Repository Path**: pasuo/web-harness

## Basic Information

- **Project Name**: web-harness
- **Description**: AI-native web 应用开发执行框架——生成与评估完全分离，增量执行，状态可追溯。

基于 Anthropic & OpenAI 官方工程实践，通过三角色协作 + 六条防线，让 AI Agent 稳定交付可用的全栈 web 应用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-28
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# web-harness

> AI-native web 应用开发执行框架——生成与评估完全分离，增量执行，状态可追溯。

基于 Anthropic & OpenAI 官方工程实践，通过三角色协作 + 六条防线，让 AI Agent 稳定交付可用的全栈 web 应用。

---

## 三角色架构

| 角色 | Skills | 职责 |
|------|--------|------|
| **Planner** | `brainstorming` + `writing-plans` | 需求 → Product Spec → Feature List (JSON) |
| **Generator** | `frontend-design` + `fullstack-developer` + `test-driven-development` | Sprint Contract → TDD → 增量实现 → merge |
| **Evaluator** | `webapp-testing` + `agent-browser` | 独立 E2E 验收，四维度评分，截图存证 |

---

## 依赖 Skills

本 Skill 依赖 8 个 WorkBuddy 平台内置 Skill。这些 Skill 由 WorkBuddy 官方维护，已内置于平台，无需手动安装外部 GitHub 仓库。

### 必需依赖

| Skill | 角色 | 功能 | 安装方式 |
|-------|------|------|---------|
| `brainstorming` | Planner | 需求澄清、头脑风暴、设计探索 | 内置，自动可用 |
| `writing-plans` | Planner | 将设计转化为分阶段执行计划 | 内置，自动可用 |
| `frontend-design` | Generator | 高质量前端界面设计与实现 | 内置，自动可用 |
| `fullstack-developer` | Generator | 全栈代码实现（前后端、数据库） | 内置，自动可用 |
| `test-driven-development` | Generator | TDD 测试驱动开发（Red-Green-Refactor） | 内置，自动可用 |
| `webapp-testing` | Evaluator | Playwright E2E 测试、DOM 检查 | 内置，自动可用 |
| `agent-browser` | Evaluator | 浏览器自动化、截图验证、用户行为模拟 | 内置，自动可用 |
| `systematic-debugging` | Debugger | 系统性问题诊断与修复 | 内置，自动可用 |

### 安装方式

**这些 Skill 已内置于 WorkBuddy 平台，无需手动安装。** 只需在 web-harness Skill 中使用时调用即可：

```python
# 在 Skill 执行时，直接使用对应的 use_skill() 函数
use_skill("brainstorming")
use_skill("frontend-design")
# ... 等等
```

**如果发现某个 Skill 不可用**，请检查：
1. WorkBuddy 版本是否最新（可通过 WorkBuddy 设置中检查更新）
2. 该 Skill 是否已在 `~/.workbuddy/skills/` 目录下（所有内置 Skill 应该都在）
3. 如遇问题，可在 WorkBuddy 控制面板的"Skill 市场"重新加载或安装

---

## 执行节奏

每个 feature 独立一轮，六步不可跳过：

```
选 feature → 建 feat/ 分支 → 先写测试(红) → 实现代码(绿) → E2E 验收 → merge main + tag
```

Planner 完成草稿后**强制 PAUSE**，结构化摘要向用户确认，明确回复后才生成 feature-list.json。

## 六条防线

| # | 防线 | 解法 |
|---|------|------|
| 1 | 上下文溢出 | 每轮开新窗口，靠仓库文件传递状态 |
| 2 | 虚假完工 | 强制 E2E 测试，passes:true 须 Evaluator 签字 |
| 3 | 自评估放水 | Evaluator 完全独立，禁止自评 |
| 4 | 设计模板化 | frontend-design skill + 规避 AI 渐变卡片引导 |
| 5 | 方向跑偏 | Planner 草稿强制用户确认，不允许跳过 |
| 6 | 并行合并冲突 | 模块所有权 + 接口契约冻结 + 串行合并队列 |

## 评估维度（任一项 < 6 直接 FAIL）

| 维度 | 权重 |
|------|------|
| 功能完整性 | 40% |
| 设计质量 | 25% |
| 代码质量 | 20% |
| 可用性 | 15% |

## 快速开始

```bash
# 从 skill 目录复制模板到新项目
SKILL=~/.workbuddy/skills/web-harness
cp $SKILL/AGENTS.md $SKILL/ARCHITECTURE.md ./
cp -r $SKILL/docs ./
cp -r $SKILL/scripts ./
chmod +x scripts/*.sh

# 初始化
./scripts/init-project.sh <project-name> "<description>"
```

或直接在 WorkBuddy 中：
```
use_skill("web-harness")
```

## 文件结构

```
web-harness/
├── SKILL.md                 # WorkBuddy skill 入口（含完整工作流）
├── AGENTS.md                # 三角色说明与核心规则
├── ARCHITECTURE.md          # 分层架构规范、命名约定、代码约束
├── scripts/
│   ├── init-project.sh      # 一键初始化（Vite + React + TS + Tailwind + Playwright）
│   ├── validate-feature.sh  # feature 校验
│   └── run-evaluation.sh    # 运行评估
└── docs/
    ├── specs/
    │   └── product-spec.template.md
    └── harness/
        ├── feature-list.template.json
        ├── sprint-contract.template.md
        ├── progress.template.md
        └── evaluation-report.template.md
```

## 适用场景

- **推荐**：中大型全栈项目、多轮迭代、需要可追溯状态
- **不推荐**：单页静态展示、原型验证（用 `superpowers` skill 更轻量）

---

实战验证：使用本框架完整交付了极简待办清单 web app，7/7 features，Evaluator E2E 17/17 通过，评分 10/10。

---

## 灵感来源

本 skill 的核心设计理念来自 Anthropic 工程团队的官方实践：

> [How we designed Claude's harness for long-running tasks](https://www.anthropic.com/engineering/harness-design-long-running-apps) — Anthropic Engineering Blog