fe-harness 1.0.0

package/fe-harness/workflows/complete.md

@@ -0,0 +1,143 @@
+# 完成工作流
+
+## 概述
+
+在所有任务执行完毕后，生成完成报告、归档运行时产物、清理临时文件。
+
+---
+
+## 流程
+
+### 第一步：获取完成摘要
+
+```bash
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks summary
+```
+
+解析返回的 JSON，检查 `isAllFinished` 字段：
+
+- **`isAllFinished: true`** → 所有任务已完成（done/failed/skipped），继续下一步
+- **`isAllFinished: false`** → 还有未完成的任务，输出提示并终止：
+  ```
+  ⚠️ 还有 N 个任务未完成（pending: X, in_progress: Y）。
+  请先运行 /fe:execute 完成剩余任务，或手动处理后再运行 /fe:complete。
+  ```
+
+### 第二步：输出完成报告
+
+将摘要数据格式化为可读报告：
+
+```markdown
+## ✅ fe-harness 执行完成
+
+### 任务统计
+
+| 指标 | 值 |
+|------|-----|
+| 总任务数 | {total} |
+| ✅ 完成 | {done} |
+| ❌ 失败 | {failed} |
+| ⏭️ 跳过 | {skipped} |
+| 🔄 总重试次数 | {totalRetries} |
+| ⏱️ 总耗时 | {duration.totalFormatted} |
+| 🕐 开始时间 | {duration.startedAt} |
+| 🕐 结束时间 | {duration.completedAt} |
+
+### 任务类型
+
+| 类型 | 完成 / 总计 |
+|------|-------------|
+| 🎨 设计任务 | {designTasks.done} / {designTasks.total} |
+| ⚙️ 逻辑任务 | {logicTasks.done} / {logicTasks.total} |
+
+### 任务详情
+
+| ID | 名称 | 类型 | 状态 | 重试 | 实现耗时 | 总耗时 |
+|----|------|------|------|------|----------|--------|
+| {id} | {name} | {type} | {status} | {retryCount} | {executorDuration} | {duration} |
+...
+
+> **实现耗时** = executor 独立实现阶段的耗时（startedAt → executorFinishedAt）
+> **总耗时** = 含合并、验证、修复的端到端耗时（startedAt → completedAt）
+> 同 wave 内多个任务的实现耗时重叠说明并行执行生效。
+```
+
+### 第三步：输出警告（如有）
+
+如果 `hasWarnings: true`，在报告后追加：
+
+```markdown
+### ⚠️ 未解决的问题
+
+| ID | 名称 | 状态 | 错误信息 |
+|----|------|------|----------|
+| {id} | {name} | {status} | {error} |
+...
+
+> 这些任务未成功完成。可以使用 `node ~/.claude/fe-harness/bin/fe-tools.cjs tasks reset-all-failed` 重置后重新执行。
+```
+
+### 第四步：输出 Token 消耗
+
+在报告末尾追加当前会话的 token 消耗信息。通过以下 bash 命令获取：
+
+```bash
+claude --print-session-usage 2>/dev/null || echo '{"error":"unavailable"}'
+```
+
+如果命令不可用或报错，直接输出提示：
+
+```markdown
+### 💰 Token 消耗
+
+> 当前会话的 token 消耗请通过 `/cost` 命令查看。
+```
+
+如果命令返回了有效数据，格式化输出：
+
+```markdown
+### 💰 Token 消耗
+
+| 指标 | 值 |
+|------|-----|
+| 输入 tokens | {input_tokens} |
+| 输出 tokens | {output_tokens} |
+| 总 tokens | {total_tokens} |
+| 估算费用 | ${cost} |
+```
+
+### 第五步：归档运行时产物
+
+```bash
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks archive
+```
+
+这会：
+1. 将 `tasks.json`、`progress.md` 和 `context/` 下的所有文件复制到 `.fe-runtime/history/{timestamp}/`
+2. 删除原始 `tasks.json` 和 `progress.md`
+3. 清空 `context/` 目录
+
+输出归档结果：
+```
+📦 已归档到 {archiveDir}
+```
+
+### 第六步：提示后续操作
+
+```markdown
+### 后续操作
+
+- 查看归档数据：`ls .fe-runtime/history/`
+- 开始新一轮任务：准备功能列表后运行 `/fe:plan`
+- 如需重新执行失败任务：从归档恢复 tasks.json 后运行 `/fe:execute`
+```
+
+---
+
+## 参数支持
+
+- `--no-archive`：只生成报告，不归档和清理（通过 `$ARGUMENTS` 传入）
+- `--force`：即使有未完成任务也强制完成（跳过第一步检查）
+
+如果 `$ARGUMENTS` 包含 `--no-archive`，跳过第四步。
+如果 `$ARGUMENTS` 包含 `--force`，跳过第一步的未完成检查。

package/fe-harness/workflows/execute.md

@@ -0,0 +1,227 @@
+# 执行编排工作流
+
+## 概述
+两级编排架构：顶层编排器串行调度 wave，每个 wave 委托 `fe-wave-runner` 子代理在独立上下文中完成。
+
+**架构：**
+```
+顶层编排器 (本文件)
+  └─ per wave → Agent(fe-wave-runner)      ← 独立上下文
+       ├─ Agent(fe-executor) ×N (worktree 隔离, 并行)
+       ├─ 合并 worktree + backpressure 检查
+       ├─ Agent(fe-verifier/reviewer) ×N (并行)
+       ├─ 修复循环
+       └─ git commit + 写 wave-result
+```
+
+**核心原则：**
+- 编排器只调度，不执行实现/验证/修复
+- 每个 wave 在独立上下文中闭环完成
+- 状态持久化到 tasks.json，支持断点续跑
+
+## 前置检查
+
+```bash
+INIT=$(node ~/.claude/fe-harness/bin/fe-tools.cjs init execute)
+```
+
+- `error` → 输出错误，终止
+- 成功 → 提取 config 和任务统计
+
+```bash
+CONFIG=$(node ~/.claude/fe-harness/bin/fe-tools.cjs config get)
+```
+
+提取关键配置：`devServerCommand`, `maxRetries`, `verifyThreshold`, `reviewThreshold`, `dimensionThreshold`, `scoreDropTolerance`, `backpressureCommand`, `maxParallelBrowsers`
+
+## 获取 Wave 执行计划
+
+```bash
+WAVES=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks waves)
+```
+
+提取：`waves`（按 wave 分组）、`waveOrder`（执行顺序）、`taskCount`
+
+> `circularWarning` 不为 null 时**必须**输出警告。
+
+输出计划概览：
+```
+Wave 执行计划: {waveOrder.length} 个 wave, {taskCount} 个任务
+Wave 1: {n} 个任务 | Wave 2: {n} 个任务 | ...
+```
+
+## 自动解决文件冲突
+
+检查同 wave 内是否有任务修改相同文件，自动添加依赖关系将冲突任务分到不同 wave：
+
+```bash
+RESOLVE=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks resolve-conflicts)
+```
+
+- `resolved > 0` → 输出提示：`⚠️ 检测到 {resolved} 个文件冲突，已自动添加依赖关系。重新计算 wave 分组。`，然后重新获取 wave 计划：
+  ```bash
+  WAVES=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks waves)
+  ```
+  重新输出计划概览。
+- `resolved = 0` 或 `ok: true` 且无冲突 → 静默继续
+
+## 启动开发服务器
+
+> 仅设计任务需要开发服务器。全部为逻辑任务时跳过本节。
+
+**前置校验：** 有设计任务但 `devServerCommand` 未配置时：
+- 输出：`ERROR: 存在设计任务但 devServerCommand 未配置，请编辑 .fe/config.jsonc 填写。`
+- 终止执行
+
+```bash
+# 分配随机端口（存在微小竞态窗口，若端口冲突可重试）
+DEV_PORT=$(node -e "const s=require('net').createServer();s.listen(0,()=>{console.log(s.address().port);s.close()})")
+DEV_SERVER_URL="http://localhost:$DEV_PORT"
+
+# 启动开发服务器（后台运行）
+PORT=$DEV_PORT ${devServerCommand} &
+DEV_SERVER_PID=$!
+
+# 等待服务器启动（最多 30 秒）
+SERVER_READY=false
+for i in $(seq 1 30); do
+  if curl -s $DEV_SERVER_URL > /dev/null 2>&1; then
+    SERVER_READY=true
+    break
+  fi
+  sleep 1
+done
+
+if [ "$SERVER_READY" = "false" ]; then
+  echo "ERROR: Dev server failed to start within 30 seconds on port $DEV_PORT"
+  # 终止编排循环
+fi
+```
+
+**后续 `${devServerUrl}` 均使用 `$DEV_SERVER_URL`。**
+
+## 主执行循环
+
+逐 wave 串行执行：
+
+### 1. 刷新状态
+
+```bash
+WAVES=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks waves)
+```
+
+> `circularWarning` 不为 null 时**必须**输出。
+
+### 2. 跳过检查
+
+当前 wave 所有任务 status 为 `done` → 输出 `Wave {N}: 已完成，跳过` 并继续下一个。
+
+### 3. 读取 wave 任务
+
+从 `tasks.json` 读取当前 wave 的完整任务对象：
+
+```bash
+WAVE_TASKS=$(node -e "
+  const tasks = JSON.parse(require('fs').readFileSync('.fe-runtime/tasks.json','utf8'));
+  const waveTaskIds = [${wave_task_ids}];
+  const waveTasks = tasks.filter(t => waveTaskIds.includes(t.id));
+  console.log(JSON.stringify(waveTasks));
+")
+```
+
+### 4. 委托给 fe-wave-runner
+
+```
+Agent(
+  subagent_type="fe-wave-runner",
+  model="opus",
+  description="执行 Wave ${N}: ${taskNames}",
+  prompt="""
+<wave_context>
+waveNumber: ${N}
+totalWaves: ${totalWaves}
+devServerUrl: ${DEV_SERVER_URL}
+devServerCommand: ${devServerCommand}
+backpressureCommand: ${backpressureCommand}
+maxRetries: ${maxRetries}
+verifyThreshold: ${verifyThreshold}
+reviewThreshold: ${reviewThreshold}
+dimensionThreshold: ${dimensionThreshold}
+scoreDropTolerance: ${scoreDropTolerance}
+maxParallelBrowsers: ${maxParallelBrowsers}
+feToolsPath: ~/.claude/fe-harness/bin/fe-tools.cjs
+browserPath: ~/.claude/fe-harness/bin/browser.cjs
+</wave_context>
+
+<wave_tasks>
+${WAVE_TASKS}
+</wave_tasks>
+""")
+```
+
+**注意：**
+- **禁用** `isolation="worktree"` — wave-runner 需要主仓库 git 访问
+- **禁用** `run_in_background` — wave 间必须串行
+- wave-runner 内部自行调度 fe-executor（带 worktree）、fe-verifier、fe-reviewer、fe-fixer
+
+### 5. 读取 wave 结果
+
+```bash
+cat .fe-runtime/context/wave-result-${N}.json
+```
+
+输出摘要：`--- Wave {N} 完成: {passed} 通过, {failed} 失败 ---`
+
+### 6. 下一个 Wave
+
+回到步骤 1。
+
+## 断点续跑
+
+重新执行时自动恢复：
+- 已完成的任务（status 为 `done`）和 wave 自动跳过
+- 从首个含 pending 任务的 wave 继续
+- 失败任务（status 为 `failed`）不会重试，保留失败状态
+
+**残留状态清理：**
+- `fe-checkpoint-*` 标签：来自中断的修复循环，重新执行前会被新的检查点覆盖（`git tag -f`），无需手动清理
+- `fe-wave-*-baseline` 标签：来自中断的 wave，新 wave 执行时会覆盖同名标签
+- `.fe-runtime/context/` 下的中间文件：每个 wave 验证前会通过 `init context` 清理
+
+**如需完全重置：**
+```bash
+# 重置所有任务状态为 pending（慎用）
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks reset
+# 清理所有检查点标签
+git tag -l 'fe-checkpoint-*' | xargs git tag -d 2>/dev/null || true
+git tag -l 'fe-wave-*-baseline' | xargs git tag -d 2>/dev/null || true
+```
+
+## 完成
+
+所有 wave 处理完毕后：
+
+```bash
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks status
+```
+
+输出摘要：
+```
+--- 执行完成 ---
+完成: {done}/{total} | 失败: {failed} | 跳过: {skipped}
+```
+
+```bash
+# 停止开发服务器
+kill $DEV_SERVER_PID 2>/dev/null || true
+
+# 清理残留浏览器实例
+node ~/.claude/fe-harness/bin/browser.cjs cleanup
+```
+
+## 上下文管理
+
+1. **不复述 Agent 结果** — 返回摘要已在上下文中
+2. **每 wave 一行摘要** — 不逐任务展开
+3. **状态从磁盘读** — 每轮循环通过 `tasks waves` 刷新
+4. **实现/验证/修复均在 wave-runner 内** — 编排器不介入细节

package/fe-harness/workflows/help.md

@@ -0,0 +1,89 @@
+# 帮助文档
+
+## fe-harness 命令参考
+
+### 可用命令
+
+| 命令 | 说明 |
+|------|------|
+| `/fe:plan` | 解析功能列表和 Figma URL，创建优化的任务列表 |
+| `/fe:execute` | 执行所有待处理任务（实现 → 验证 → 修复循环） |
+| `/fe:complete` | 生成完成报告、归档运行时产物并清理环境 |
+| `/fe:status` | 查看任务状态概览 |
+| `/fe:help` | 显示此帮助信息 |
+
+### 快速开始
+
+```
+1. npx fe-harness              ← 安装并生成 .fe/config.jsonc
+2. 编辑 .fe/config.jsonc        ← 配置开发服务器等参数
+3. 输入功能列表后执行 /fe:plan   ← 创建任务
+4. /fe:execute                 ← 自动执行所有任务
+5. /fe:complete                ← 生成报告并归档
+```
+
+### 输入格式
+
+```
+功能1: 用户头像组件, figma设计稿: https://figma.com/design/xxx?node-id=1-2
+功能2: 登录页面, figma设计稿: https://figma.com/design/xxx?node-id=3-4
+功能3: 用户登录 API 对接
+功能4: 全局状态管理
+```
+
+- 有 `figma设计稿:` URL 的 → 设计任务（视觉验证）
+- 无 URL 的 → 逻辑任务（代码审查）
+
+### 执行流程
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  fe-executor │────→│ fe-verifier  │────→│  fe-fixer   │
+│  实现代码    │     │ 或 fe-reviewer│     │  修复问题   │
+└─────────────┘     └──────┬───────┘     └──────┬──────┘
+                           │                     │
+                           │  未通过              │
+                           │←────────────────────┘
+                           │  
+                           │  通过 ✓
+                           ▼
+                    ┌──────────────┐
+                    │  git commit  │
+                    └──────────────┘
+```
+
+每个任务最多重试 maxRetries 次（默认 5 次）。
+
+### 配置说明
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| maxRetries | 5 | 每个任务的最大重试次数 |
+| devServerCommand | "" | 开发服务器启动命令（自动分配随机端口） |
+| verifyThreshold | 80 | 视觉验证通过阈值 (%) |
+| reviewThreshold | 80 | 代码审查通过阈值 (%) |
+| dimensionThreshold | 6 | 单维度最低分 (0-10) |
+| scoreDropTolerance | 3 | 修复后允许的最大分数下降 |
+| backpressureCommand | "" | 硬性校验命令 |
+| maxParallelBrowsers | 3 | 同时运行的最大浏览器实例数（防止系统资源耗尽） |
+
+### fe-tools CLI
+
+状态管理工具，在 Bash 中直接调用：
+
+```bash
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks status    # 状态概览
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks next      # 下一个任务
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks reset 1   # 重置任务
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks reset-all-failed  # 重置所有失败任务
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks summary           # 完成摘要
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks archive           # 归档并清理
+node ~/.claude/fe-harness/bin/fe-tools.cjs config get      # 查看配置
+```
+
+### 安装方式
+
+```bash
+npx fe-harness          # 全局安装到 ~/.claude/
+npx fe-harness --local  # 本地安装到 ./.claude/
+```