feat: 更新软件手册，优化截图捕获流程和规则说明

2026-02-05 01:50:27 +08:00 · 2025-12-28 18:19:39 +08:00
parent 4419c50942
commit 3ef1e54412
3 changed files with 78 additions and 247 deletions
--- 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)                    │
--- 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 交互点必须插入截图标记:
+<!-- SCREENSHOT: id="ss-{功能}-{状态}" url="{路由}" selector="{CSS选择器}" wait_for="{等待元素}" description="{描述}" -->
+
+示例:
+- 页面全貌: <!-- SCREENSHOT: id="ss-dashboard-overview" url="/dashboard" description="仪表盘主界面" -->
+- 特定组件: <!-- SCREENSHOT: id="ss-login-form" url="/login" selector=".login-form" description="登录表单" -->
+- 交互状态: <!-- SCREENSHOT: id="ss-modal-open" url="/settings" selector=".modal" wait_for=".modal.show" description="设置弹窗" -->
+`
  },
  '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截图标记: <!-- SCREENSHOT: id="ss-xxx" url="/path" description="xxx" -->';
+
  return `
 [ROLE] ${cfg.role}

@@ -87,7 +100,7 @@ ${cfg.task}
 - 用户友好语言，避免技术术语
 - 步骤编号清晰
 - 代码块标注语言
- 截图标记: <!-- SCREENSHOT: id="ss-xxx" url="/path" description="xxx" -->
+${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": []
 }
 `;
--- 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": <n>,
+  "failed": <n>,
+  "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)