fe-harness 1.0.0

package/bin/install.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── 配置 ────────────────────────────────────────────
+
+const CONFIG_DIR = '.claude';
+const DIRS = {
+  commands: 'commands/fe',
+  agents: 'agents',
+  runtime: 'fe-harness',
+};
+
+// ─── 工具函数 ───────────────────────────────────────────
+
+function logOk(msg) { console.log(`  ✓ ${msg}`); }
+function logErr(msg) { console.error(`  ✗ ${msg}`); }
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function copyDirRecursive(src, dest, pathReplace) {
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  let count = 0;
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      count += copyDirRecursive(srcPath, destPath, pathReplace);
+    } else {
+      let content = fs.readFileSync(srcPath, 'utf8');
+
+      // 替换 .md 文件中的路径引用
+      if (entry.name.endsWith('.md') && pathReplace) {
+        content = content.replace(/~\/\.claude\/fe-harness\//g, pathReplace);
+      }
+
+      fs.writeFileSync(destPath, content, 'utf8');
+
+      // 保留 .cjs 文件的可执行权限
+      if (entry.name.endsWith('.cjs')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+
+      count++;
+    }
+  }
+
+  return count;
+}
+
+// ─── 安装 ───────────────────────────────────────────
+
+function install() {
+  const args = process.argv.slice(2);
+  const isLocal = args.includes('--local') || args.includes('-l');
+  const isHelp = args.includes('--help') || args.includes('-h');
+  const isUninstall = args.includes('--uninstall');
+  const isInit = args.includes('init');
+
+  if (isHelp) {
+    console.log(`
+  fe-harness — Figma 设计稿转代码工具（适用于 Claude Code）
+
+  用法：
+    npx fe-harness           全局安装到 ~/.claude/
+    npx fe-harness --local   本地安装到 ./.claude/
+    npx fe-harness init      在当前目录初始化项目配置
+    npx fe-harness --uninstall [--local]   卸载已安装的文件
+
+  安装后，可在 Claude Code 中使用以下命令：
+    /fe:plan      根据 Figma URL 创建任务计划
+    /fe:execute   使用子代理执行所有任务
+    /fe:complete  生成完成报告并归档
+    /fe:status    查看任务状态
+    /fe:help      显示帮助信息
+`);
+    return;
+  }
+
+  if (isInit) {
+    return initProject();
+  }
+
+  // 确定源目录（此包的安装位置）
+  const pkgRoot = path.resolve(__dirname, '..');
+
+  // 确定目标目录
+  let targetDir;
+  if (isLocal) {
+    targetDir = path.join(process.cwd(), CONFIG_DIR);
+  } else {
+    const home = process.env.HOME || process.env.USERPROFILE;
+    targetDir = path.join(home, CONFIG_DIR);
+  }
+
+  // 计算 .md 文件中引用的路径前缀
+  let pathPrefix;
+  if (isLocal) {
+    pathPrefix = path.resolve(targetDir, 'fe-harness') + '/';
+  } else {
+    pathPrefix = '~/.claude/fe-harness/';
+  }
+
+  if (isUninstall) {
+    return uninstall(targetDir);
+  }
+
+  console.log(`\n  ⚡ fe-harness 安装器\n`);
+  console.log(`  目标目录：${targetDir}`);
+  console.log(`  模式：    ${isLocal ? '本地' : '全局'}\n`);
+
+  // 0. 清理旧版安装
+  const cleanDirs = [
+    path.join(targetDir, DIRS.commands),
+    path.join(targetDir, DIRS.runtime),
+  ];
+  for (const dir of cleanDirs) {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true });
+    }
+  }
+  const agentCleanDir = path.join(targetDir, DIRS.agents);
+  if (fs.existsSync(agentCleanDir)) {
+    for (const f of fs.readdirSync(agentCleanDir).filter(f => f.startsWith('fe-'))) {
+      fs.unlinkSync(path.join(agentCleanDir, f));
+    }
+  }
+  logOk('已清理旧版安装文件');
+
+  // 1. 复制命令文件
+  const cmdSrc = path.join(pkgRoot, 'commands', 'fe');
+  const cmdDest = path.join(targetDir, DIRS.commands);
+  if (fs.existsSync(cmdSrc)) {
+    const count = copyDirRecursive(cmdSrc, cmdDest, pathPrefix);
+    logOk(`${count} 个命令文件 → ${DIRS.commands}/`);
+  } else {
+    logErr(`命令源目录未找到：${cmdSrc}`);
+  }
+
+  // 2. 复制代理文件
+  const agentSrc = path.join(pkgRoot, 'agents');
+  const agentDest = path.join(targetDir, DIRS.agents);
+  if (fs.existsSync(agentSrc)) {
+    const count = copyDirRecursive(agentSrc, agentDest, pathPrefix);
+    logOk(`${count} 个代理文件 → ${DIRS.agents}/`);
+  } else {
+    logErr(`代理源目录未找到：${agentSrc}`);
+  }
+
+  // 3. 复制运行时文件 (fe-harness/)
+  const rtSrc = path.join(pkgRoot, 'fe-harness');
+  const rtDest = path.join(targetDir, DIRS.runtime);
+  if (fs.existsSync(rtSrc)) {
+    const count = copyDirRecursive(rtSrc, rtDest, pathPrefix);
+    logOk(`${count} 个运行时文件 → ${DIRS.runtime}/`);
+  } else {
+    logErr(`运行时源目录未找到：${rtSrc}`);
+  }
+
+  // 4. 写入版本文件
+  let version = 'unknown';
+  try {
+    const srcPkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
+    version = srcPkg.version;
+  } catch (_) {}
+  fs.writeFileSync(path.join(targetDir, DIRS.runtime, 'VERSION'), version, 'utf8');
+
+  console.log(`\n  ✅ fe-harness v${version} 安装成功！\n`);
+
+  // 本地安装：将安装目录加入 .gitignore，避免提交大量文件
+  if (isLocal) {
+    const gitignorePath = path.join(process.cwd(), '.gitignore');
+    const ignoreEntries = [
+      '.claude/fe-harness/',
+      '.claude/commands/fe/',
+      '.claude/agents/fe-*',
+    ];
+    const ignoreBlock = '\n# fe-harness 安装文件（由 npx fe-harness --local 生成）\n'
+      + ignoreEntries.join('\n') + '\n';
+
+    if (fs.existsSync(gitignorePath)) {
+      const existing = fs.readFileSync(gitignorePath, 'utf8');
+      if (!existing.includes('.claude/fe-harness/')) {
+        fs.appendFileSync(gitignorePath, ignoreBlock, 'utf8');
+        logOk('已将安装目录添加到 .gitignore');
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, ignoreBlock.trimStart(), 'utf8');
+      logOk('已创建 .gitignore 并添加安装目录规则');
+    }
+
+    initProject();
+  } else {
+    console.log(`  后续步骤：`);
+    console.log(`    1. 进入你的项目目录`);
+    console.log(`    2. 运行：npx fe-harness init`);
+    console.log(`    3. 编辑 .fe/config.jsonc 配置 devServer 等`);
+    console.log(`    4. 使用 /fe:plan 创建任务计划\n`);
+  }
+}
+
+// ─── 初始化（项目配置）────────────────────────────
+
+function initProject() {
+  console.log(`\n  ⚡ fe-harness 项目初始化\n`);
+
+  const pkgRoot = path.resolve(__dirname, '..');
+  const feDir = path.join(process.cwd(), '.fe');
+
+  // 1. 从模板创建 .fe/config.jsonc
+  const feConfigPath = path.join(feDir, 'config.jsonc');
+  if (!fs.existsSync(feConfigPath)) {
+    const templatePath = path.join(pkgRoot, 'fe-harness', 'templates', 'config.jsonc');
+    if (fs.existsSync(templatePath)) {
+      ensureDir(feDir);
+      fs.copyFileSync(templatePath, feConfigPath);
+      logOk('已创建 .fe/config.jsonc（默认配置）');
+    } else {
+      logErr('配置模板未找到，请确认 fe-harness 已正确安装');
+      return;
+    }
+  } else {
+    logOk('.fe/config.jsonc 已存在，跳过');
+  }
+
+  // 2. 创建 .fe-runtime/context/ 目录
+  const runtimeDir = path.join(process.cwd(), '.fe-runtime');
+  ensureDir(path.join(runtimeDir, 'context'));
+
+  // 3. 将 .fe-runtime/ 添加到 .gitignore
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const feGitignoreContent = '\n# fe-harness 运行时产物（截图、分析文件、任务状态、临时结果）\n.fe-runtime/\n';
+  if (fs.existsSync(gitignorePath)) {
+    const existing = fs.readFileSync(gitignorePath, 'utf8');
+    if (!existing.includes('.fe-runtime')) {
+      fs.appendFileSync(gitignorePath, feGitignoreContent, 'utf8');
+      logOk('已将 .fe-runtime/ 添加到 .gitignore');
+    }
+  } else {
+    fs.writeFileSync(gitignorePath, feGitignoreContent.trimStart(), 'utf8');
+    logOk('已创建 .gitignore 并添加 .fe-runtime/ 规则');
+  }
+
+  console.log(`\n  ✅ 项目初始化完成！\n`);
+  console.log(`  后续步骤：`);
+  console.log(`    1. 编辑 .fe/config.jsonc 配置 devServer 等`);
+  console.log(`    2. 使用 /fe:plan 创建任务计划`);
+  console.log(`    3. 使用 /fe:execute 开始执行\n`);
+}
+
+// ─── 卸载 ─────────────────────────────────────────
+
+function uninstall(targetDir) {
+  console.log(`\n  🗑️  正在从 ${targetDir} 卸载 fe-harness\n`);
+
+  const dirsToRemove = [
+    path.join(targetDir, DIRS.commands),
+    path.join(targetDir, DIRS.runtime),
+  ];
+
+  // 删除 fe-* 代理文件（不删除整个 agents 目录）
+  const agentDir = path.join(targetDir, DIRS.agents);
+  if (fs.existsSync(agentDir)) {
+    const agents = fs.readdirSync(agentDir).filter(f => f.startsWith('fe-'));
+    for (const a of agents) {
+      fs.unlinkSync(path.join(agentDir, a));
+      logOk(`已删除代理：${a}`);
+    }
+  }
+
+  for (const dir of dirsToRemove) {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true });
+      logOk(`已删除：${path.relative(targetDir, dir)}`);
+    }
+  }
+
+  console.log(`\n  ✅ fe-harness 已卸载。\n`);
+}
+
+// ─── 主入口 ──────────────────────────────────────────
+
+install();

package/commands/fe/complete.md

@@ -0,0 +1,35 @@
+---
+name: fe:complete
+description: 完成所有任务后生成摘要报告、归档运行时产物并清理环境
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+<objective>
+在所有任务执行完毕后，汇总执行结果、生成完成报告、归档运行时产物并清理临时文件。
+
+这是 fe-harness 工作流的最后一步：plan → execute → complete。
+</objective>
+
+<execution_context>
+@~/.claude/fe-harness/workflows/complete.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<when_to_use>
+- 当 `/fe:execute` 执行完毕后，使用此命令收尾
+- 当想查看任务执行的最终摘要报告时
+- 当需要归档本轮任务数据、为下一轮做准备时
+
+不要在以下情况使用：
+- 还有 pending 或 in_progress 的任务（会提示先完成执行）
+- 还没有 tasks.json（会提示先运行 /fe:plan）
+</when_to_use>
+
+<process>
+严格按照 @~/.claude/fe-harness/workflows/complete.md 中的流程执行。
+</process>

package/commands/fe/execute.md

@@ -0,0 +1,46 @@
+---
+name: fe:execute
+description: 两级编排执行所有待处理任务（顶层 wave 调度 → wave-runner 内部闭环）
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - mcp__plugin_figma_figma__get_design_context
+  - mcp__plugin_figma_figma__get_screenshot
+---
+<objective>
+两级编排架构。顶层编排器按 Wave 串行调度，每个 Wave 委托给 fe-wave-runner 子代理在独立上下文窗口中完成：
+
+1. 并行调用 fe-executor（isolation=worktree）实现
+2. 合并 worktree + backpressure 检查
+3. 并行调用 fe-verifier/fe-reviewer 验证
+4. 串行修复循环（fe-fixer → 重新验证）
+5. 通过后 git commit，失败后传播到下游 Wave
+
+顶层编排器只做 wave 级调度，上下文消耗 O(waves)。
+</objective>
+
+<execution_context>
+@~/.claude/fe-harness/workflows/execute.md
+</execution_context>
+
+<process>
+严格按照 @~/.claude/fe-harness/workflows/execute.md 中的编排流程执行。
+
+关键要求：
+1. 使用 Agent 工具调用 fe-wave-runner（每个 wave 一次调用）
+2. fe-wave-runner 内部自行调用 fe-executor/fe-verifier/fe-reviewer/fe-fixer
+3. 不使用 isolation="worktree" 调用 wave-runner（它需要主仓库 git 访问）
+4. 不使用 run_in_background 调用 wave-runner（wave 间必须串行）
+5. 每个 wave 开始前从 tasks waves 刷新状态
+6. 读取 wave-result JSON 获取结果
+
+上下文管理：
+- 不复述 Agent 结果
+- 每个 wave 只输出一行摘要
+- 所有实现/验证/修复细节在 wave-runner 内部完成
+</process>

package/commands/fe/help.md

@@ -0,0 +1,17 @@
+---
+name: fe:help
+description: 显示 fe-harness 可用命令和使用指南
+---
+<objective>
+显示完整的 fe-harness 命令参考。
+
+只输出参考内容，不做项目分析、git 状态检查或其他额外操作。
+</objective>
+
+<execution_context>
+@~/.claude/fe-harness/workflows/help.md
+</execution_context>
+
+<process>
+直接输出 @~/.claude/fe-harness/workflows/help.md 中的帮助文档内容，不做修改或补充。
+</process>

package/commands/fe/map-codebase.md

@@ -0,0 +1,60 @@
+---
+name: fe:map-codebase
+description: 分析前端代码库，使用并行映射代理生成 .fe/codebase/ 下的结构化文档
+argument-hint: "[可选: 聚焦区域, 如 'components' 或 'routing']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Agent
+---
+
+<objective>
+使用并行 fe-codebase-mapper 代理分析现有前端代码库，生成结构化的前端代码库文档。
+
+每个映射代理探索一个聚焦领域，并**直接写入文档**到 `.fe/codebase/`。编排器仅接收确认信息，保持上下文占用最小。
+
+输出: .fe/codebase/ 目录，包含 7 个前端专属的结构化文档。
+</objective>
+
+<execution_context>
+@~/.claude/fe-harness/workflows/map-codebase.md
+</execution_context>
+
+<context>
+聚焦区域: $ARGUMENTS (可选 - 如果提供，告知代理聚焦特定子系统)
+
+**如果已有配置则加载:**
+检查 .fe/config.jsonc - 如果项目已初始化则加载上下文
+
+**此命令可在以下时机运行:**
+- /fe:plan 之前 (基于代码库理解生成更好的计划)
+- 任何时候刷新代码库理解
+</context>
+
+<when_to_use>
+**使用 map-codebase:**
+- 已有前端项目，需要在规划前理解代码库
+- 代码发生重大变更后刷新代码库映射
+- 接手不熟悉的前端代码库
+- 大型重构前理解当前状态
+- 团队新成员快速了解项目
+
+**跳过 map-codebase:**
+- 全新项目，还没有代码
+- 极简代码库 (<5 个文件)
+</when_to_use>
+
+<process>
+严格按照 @~/.claude/fe-harness/workflows/map-codebase.md 中的编排流程执行。
+</process>
+
+<success_criteria>
+- [ ] .fe/codebase/ 目录已创建
+- [ ] 所有 7 个代码库文档由映射代理写入
+- [ ] 文档遵循模板结构
+- [ ] 并行代理无错误完成
+- [ ] 用户知晓下一步操作
+</success_criteria>

package/commands/fe/plan.md

@@ -0,0 +1,36 @@
+---
+name: fe:plan
+description: 解析功能列表和 Figma URL，智能分析后创建优化的任务列表
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+  - mcp__plugin_figma_figma__get_screenshot
+  - mcp__plugin_figma_figma__get_design_context
+---
+<objective>
+解析用户提供的功能列表和 Figma 设计稿 URL，通过智能分析创建优化的任务计划。
+
+输入格式示例：
+```
+功能1: 用户头像组件, figma设计稿: https://figma.com/design/xxx?node-id=1-2
+功能2: 登录页面, figma设计稿: https://figma.com/design/xxx?node-id=3-4
+功能3: 用户登录 API 对接
+```
+</objective>
+
+<execution_context>
+@~/.claude/fe-harness/workflows/plan.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+按照 @~/.claude/fe-harness/workflows/plan.md 中的流程端到端执行任务规划。
+使用 $ARGUMENTS 中的功能列表作为输入。
+</process>

package/commands/fe/status.md

@@ -0,0 +1,39 @@
+---
+name: fe:status
+description: 查看任务状态概览
+allowed-tools:
+  - Read
+  - Bash
+---
+<objective>
+显示当前任务的状态概览，包括任务总数、各状态分布、每个任务的详细信息。
+</objective>
+
+<process>
+1. 调用状态工具获取概览：
+```bash
+node ~/.claude/fe-harness/bin/fe-tools.cjs tasks status
+```
+
+2. 将返回的 JSON 格式化为可读的表格输出：
+
+```
+## Figma Implementation Status
+
+| ID | 名称 | 类型 | 状态 | 重试次数 | 验证通过 |
+|----|------|------|------|----------|----------|
+| 1  | xxx  | 设计 | done | 0        | ✓        |
+| 2  | yyy  | 逻辑 | pending | 0     | -        |
+...
+
+### 统计
+- 总计: N 个任务
+- ✅ 完成: N
+- ⏳ 进行中: N
+- 📋 待处理: N
+- ❌ 失败: N
+- ⏭️ 跳过: N
+```
+
+3. 如果没有 tasks.json，提示用户先运行 `/fe:plan`。
+</process>