diff --git a/.claude/skills/software-manual/SKILL.md b/.claude/skills/software-manual/SKILL.md index 38c5d2e1..b3331756 100644 --- a/.claude/skills/software-manual/SKILL.md +++ b/.claude/skills/software-manual/SKILL.md @@ -63,8 +63,8 @@ Generate comprehensive, interactive software manuals in TiddlyWiki-style single- │ → 质量检查: 一致性、交叉引用、截图标记 │ │ → Output: consolidation-summary.md, screenshots-list.json │ ├─────────────────────────────────────────────────────────────────┤ -│ Phase 4: Screenshot Capture (主 Agent + Chrome MCP) │ -│ → 批量截图: 根据 screenshots-list.json │ +│ Phase 4: Screenshot Capture (universal-executor + Chrome MCP) │ +│ → 批量截图: 调用 mcp__chrome__screenshot │ │ → Output: screenshots/*.png + manifest.json │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 5: HTML Assembly (universal-executor) │ diff --git a/.claude/skills/software-manual/phases/03-parallel-analysis.md b/.claude/skills/software-manual/phases/03-parallel-analysis.md index 4e86a34f..a4c3c49e 100644 --- a/.claude/skills/software-manual/phases/03-parallel-analysis.md +++ b/.claude/skills/software-manual/phases/03-parallel-analysis.md @@ -16,9 +16,18 @@ const AGENT_CONFIGS = { 'ui-guide': { role: 'UX Expert', output: 'section-ui-guide.md', - task: '撰写界面操作指南，分步骤说明各功能使用方法', + task: '撰写界面操作指南，标注所有需要截图的 UI 元素', focus: '界面布局、导航流程、功能操作、快捷键', - input: ['exploration-ui-routes.json', 'pages/**', 'views/**'] + input: ['exploration-ui-routes.json', 'pages/**', 'views/**'], + screenshot_rules: ` +每个关键 UI 交互点必须插入截图标记: + + +示例: +- 页面全貌: +- 特定组件: +- 交互状态: +` }, 'api-docs': { role: 'API Architect', @@ -72,6 +81,10 @@ const results = await Promise.all(tasks); ```javascript function buildAgentPrompt(name, cfg, config, workDir) { + const screenshotSection = cfg.screenshot_rules + ? `\n[SCREENSHOT RULES]\n${cfg.screenshot_rules}` + : '\n[SCREENSHOT]\n截图标记: '; + return ` [ROLE] ${cfg.role} @@ -87,7 +100,7 @@ ${cfg.task} - 用户友好语言，避免技术术语 - 步骤编号清晰 - 代码块标注语言 -- 截图标记: +${screenshotSection} [FOCUS] ${cfg.focus} @@ -97,7 +110,7 @@ ${cfg.focus} "status": "completed", "output_file": "sections/${cfg.output}", "summary": "<50字>", - "screenshots_needed": [], + "screenshots_needed": [{ "id": "ss-xxx", "url": "/path", "selector": ".class", "description": "..." }], "cross_references": [] } `; diff --git a/.claude/skills/software-manual/phases/04-screenshot-capture.md b/.claude/skills/software-manual/phases/04-screenshot-capture.md index 453328d9..21d67883 100644 --- a/.claude/skills/software-manual/phases/04-screenshot-capture.md +++ b/.claude/skills/software-manual/phases/04-screenshot-capture.md @@ -1,271 +1,89 @@ # Phase 4: Screenshot Capture -Capture screenshots using Chrome MCP for all identified UI elements. +使用 `universal-executor` 子 Agent 调用 Chrome MCP 截图。 -## Objective +## 核心原则 -- Check Chrome MCP availability -- Start development server -- Capture all required screenshots -- Convert to Base64 for embedding +**主 Agent 负责编排，子 Agent 负责截图采集。** -## Prerequisites - -- Chrome MCP configured and available -- Development server can be started -- All screenshot URLs accessible - -## Execution Steps - -### Step 1: Load Screenshot List +## 执行流程 ```javascript -const consolidation = Read(`${workDir}/consolidation-summary.md`); const config = JSON.parse(Read(`${workDir}/manual-config.json`)); +const screenshotsList = JSON.parse(Read(`${workDir}/screenshots-list.json`)); -// Parse screenshot table from consolidation -const screenshots = parseScreenshotTable(consolidation); -``` - -### Step 2: Check Chrome MCP Availability - -```javascript -async function checkChromeMCP() { - try { - // Attempt to call Chrome MCP - const version = await mcp__chrome__getVersion(); - return { - available: true, - version: version.version, - browser: version.browser - }; - } catch (error) { - return { - available: false, - error: error.message - }; - } -} - -const chromeMCP = await checkChromeMCP(); - -if (!chromeMCP.available) { - // Fallback: generate manual screenshot instructions - generateManualScreenshotGuide(screenshots); - return { - status: 'skipped', - reason: 'Chrome MCP not available', - manual_guide: `${workDir}/screenshots/MANUAL_CAPTURE.md` - }; -} -``` - -### Step 3: Start Development Server - -```javascript -const devConfig = config.screenshot_config; - -// Start dev server in background -const serverTask = Bash({ - command: devConfig.dev_command, - run_in_background: true +// 委托给 universal-executor 执行截图 +const result = Task({ + subagent_type: 'universal-executor', + run_in_background: false, + prompt: buildScreenshotPrompt(config, screenshotsList, workDir) }); -// Wait for server to be ready -async function waitForServer(url, timeout = 30000) { - const start = Date.now(); - while (Date.now() - start < timeout) { - try { - const response = await fetch(url); - if (response.ok) return true; - } catch (e) { - // Server not ready yet - } - await sleep(1000); - } - throw new Error(`Server at ${url} did not start within ${timeout}ms`); -} - -await waitForServer(devConfig.dev_url, devConfig.wait_timeout); +const captureResult = JSON.parse(result); ``` -### Step 4: Batch Screenshot Capture +## Prompt 构建 ```javascript -const capturedScreenshots = []; -const failedScreenshots = []; +function buildScreenshotPrompt(config, screenshotsList, workDir) { + return ` +[ROLE] Screenshot Capturer -for (const ss of screenshots) { - try { - const fullUrl = new URL(ss.url, devConfig.dev_url).href; +[TASK] +使用 Chrome MCP 批量截图 - // Configure capture options - const captureOptions = { - url: fullUrl, - viewport: { width: 1280, height: 800 }, - fullPage: ss.fullPage || false, - waitFor: ss.wait_for || null, - delay: 500 // Wait for animations - }; +[INPUT] +- 配置: ${workDir}/manual-config.json +- 截图清单: ${workDir}/screenshots-list.json - // Add selector for partial screenshot - if (ss.selector) { - captureOptions.selector = ss.selector; - } +[STEPS] +1. 检查 Chrome MCP 可用性 (mcp__chrome__*) +2. 启动开发服务器: ${config.screenshot_config?.dev_command || 'npm run dev'} +3. 等待服务器就绪: ${config.screenshot_config?.dev_url || 'http://localhost:3000'} +4. 遍历截图清单，逐个调用 mcp__chrome__screenshot +5. 保存截图到 ${workDir}/screenshots/ +6. 生成 manifest: ${workDir}/screenshots/screenshots-manifest.json +7. 停止开发服务器 - // Capture screenshot - const result = await mcp__chrome__screenshot(captureOptions); +[MCP CALLS] +- mcp__chrome__screenshot({ url, selector?, viewport }) +- 保存为 PNG 文件 - // Save screenshot - const filename = `${ss.id}.png`; - Write(`${workDir}/screenshots/${filename}`, result.data, { encoding: 'base64' }); +[FALLBACK] +若 Chrome MCP 不可用，生成手动截图指南: MANUAL_CAPTURE.md - capturedScreenshots.push({ - ...ss, - file: filename, - base64_size: result.data.length, - captured_at: new Date().toISOString() - }); - - } catch (error) { - failedScreenshots.push({ - ...ss, - error: error.message - }); - } -} -``` - -### Step 5: Generate Screenshot Manifest - -```javascript -const manifest = { - total: screenshots.length, - captured: capturedScreenshots.length, - failed: failedScreenshots.length, - screenshots: capturedScreenshots, - failures: failedScreenshots, - dev_server: { - url: devConfig.dev_url, - command: devConfig.dev_command - }, - capture_config: { - viewport: { width: 1280, height: 800 }, - format: 'png' - }, - timestamp: new Date().toISOString() -}; - -Write(`${workDir}/screenshots/screenshots-manifest.json`, JSON.stringify(manifest, null, 2)); -``` - -### Step 6: Stop Development Server - -```javascript -// Kill the dev server process -KillShell({ shell_id: serverTask.task_id }); -``` - -### Step 7: Handle Failures - -If any screenshots failed: - -```javascript -if (failedScreenshots.length > 0) { - // Generate manual capture instructions - const manualGuide = ` -# Manual Screenshot Capture Required - -The following screenshots could not be captured automatically: - -${failedScreenshots.map(s => ` -## ${s.id} -- **URL**: ${s.url} -- **Description**: ${s.description} -- **Error**: ${s.error} - -**Instructions**: -1. Navigate to ${s.url} -2. Capture screenshot of ${s.selector || 'full page'} -3. Save as \`${s.id}.png\` -4. Place in \`screenshots/\` directory -`).join('\n')} -`; - - Write(`${workDir}/screenshots/MANUAL_CAPTURE.md`, manualGuide); -} -``` - -## Fallback: Manual Screenshot Mode - -When Chrome MCP is not available: - -```javascript -function generateManualScreenshotGuide(screenshots) { - const guide = ` -# Manual Screenshot Capture Guide - -Chrome MCP is not available. Please capture screenshots manually. - -## Setup - -1. Start your development server: - \`\`\`bash - ${config.screenshot_config.dev_command} - \`\`\` - -2. Open browser to: ${config.screenshot_config.dev_url} - -## Screenshots Required - -${screenshots.map((s, i) => ` -### ${i + 1}. ${s.id} -- **URL**: ${s.url} -- **Description**: ${s.description} -- **Save as**: \`screenshots/${s.id}.png\` -${s.selector ? `- **Element**: Capture only \`${s.selector}\`` : '- **Type**: Full page'} -`).join('\n')} - -## After Capturing - -Place all PNG files in the \`screenshots/\` directory, then run Phase 5 to continue. -`; - - Write(`${workDir}/screenshots/MANUAL_CAPTURE.md`, guide); -} -``` - -## Chrome MCP Configuration Reference - -Expected MCP configuration: - -```json +[RETURN JSON] { - "mcpServers": { - "chrome": { - "command": "npx", - "args": ["@anthropic-ai/mcp-chrome"], - "env": { - "CHROME_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" - } - } - } + "status": "completed|skipped", + "captured": , + "failed": , + "manifest_file": "screenshots-manifest.json" +} +`; } ``` -## Output +## Agent 职责 -- **Files**: `screenshots/*.png` -- **Manifest**: `screenshots/screenshots-manifest.json` -- **Fallback**: `screenshots/MANUAL_CAPTURE.md` (if needed) +1. **检查 MCP** → Chrome MCP 可用性 +2. **启动服务** → 开发服务器 +3. **批量截图** → 调用 mcp__chrome__screenshot +4. **保存文件** → screenshots/*.png +5. **生成清单** → screenshots-manifest.json -## Quality Checks +## 输出 -- [ ] All high-priority screenshots captured -- [ ] Screenshot dimensions consistent (1280x800) -- [ ] No broken/blank screenshots -- [ ] Manifest file complete +- `screenshots/*.png` - 截图文件 +- `screenshots/screenshots-manifest.json` - 清单 +- `screenshots/MANUAL_CAPTURE.md` - 手动指南（fallback） -## Next Phase +## 质量门禁 -Proceed to [Phase 5: HTML Assembly](05-html-assembly.md) with captured screenshots. +- [ ] 高优先级截图完成 +- [ ] 尺寸一致 (1280×800) +- [ ] 无空白截图 +- [ ] Manifest 完整 + +## 下一阶段 + +→ [Phase 5: HTML Assembly](05-html-assembly.md)