claude-code-workflow 6.3.9 → 6.3.11

package/.claude/skills/software-manual/scripts/extract_apis.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""
+API 文档提取脚本
+支持 FastAPI、TypeScript、Python 模块
+"""
+
+import subprocess
+import sys
+import json
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+# 项目配置
+PROJECTS = {
+    'backend': {
+        'path': Path('D:/dongdiankaifa9/backend'),
+        'type': 'fastapi',
+        'entry': 'app.main:app',
+        'output': 'api-docs/backend'
+    },
+    'frontend': {
+        'path': Path('D:/dongdiankaifa9/frontend'),
+        'type': 'typescript',
+        'entries': ['lib', 'hooks', 'components'],
+        'output': 'api-docs/frontend'
+    },
+    'hydro_generator_module': {
+        'path': Path('D:/dongdiankaifa9/hydro_generator_module'),
+        'type': 'python',
+        'output': 'api-docs/hydro_generator'
+    },
+    'multiphysics_network': {
+        'path': Path('D:/dongdiankaifa9/multiphysics_network'),
+        'type': 'python',
+        'output': 'api-docs/multiphysics'
+    }
+}
+
+
+def extract_fastapi(name: str, config: Dict[str, Any], output_base: Path) -> bool:
+    """提取 FastAPI OpenAPI 文档"""
+    path = config['path']
+    output_dir = output_base / config['output']
+    output_dir.mkdir(parents=True, exist_ok=True)
+    
+    # 添加路径到 sys.path
+    if str(path) not in sys.path:
+        sys.path.insert(0, str(path))
+    
+    try:
+        # 动态导入 app
+        from app.main import app
+        
+        # 获取 OpenAPI schema
+        openapi_schema = app.openapi()
+        
+        # 保存 JSON
+        json_path = output_dir / 'openapi.json'
+        with open(json_path, 'w', encoding='utf-8') as f:
+            json.dump(openapi_schema, f, indent=2, ensure_ascii=False)
+        
+        # 生成 Markdown 摘要
+        md_path = output_dir / 'API_SUMMARY.md'
+        generate_api_markdown(openapi_schema, md_path)
+        
+        endpoints = len(openapi_schema.get('paths', {}))
+        print(f"  ✓ Extracted {endpoints} endpoints → {output_dir}")
+        return True
+        
+    except ImportError as e:
+        print(f"  ✗ Import error: {e}")
+        return False
+    except Exception as e:
+        print(f"  ✗ Error: {e}")
+        return False
+
+
+def generate_api_markdown(schema: Dict, output_path: Path):
+    """从 OpenAPI schema 生成 Markdown"""
+    lines = [
+        f"# {schema.get('info', {}).get('title', 'API Reference')}",
+        "",
+        f"Version: {schema.get('info', {}).get('version', '1.0.0')}",
+        "",
+        "## Endpoints",
+        "",
+        "| Method | Path | Summary |",
+        "|--------|------|---------|"
+    ]
+    
+    for path, methods in schema.get('paths', {}).items():
+        for method, details in methods.items():
+            if method in ('get', 'post', 'put', 'delete', 'patch'):
+                summary = details.get('summary', details.get('operationId', '-'))
+                lines.append(f"| `{method.upper()}` | `{path}` | {summary} |")
+    
+    lines.extend([
+        "",
+        "## Schemas",
+        ""
+    ])
+    
+    for name, schema_def in schema.get('components', {}).get('schemas', {}).items():
+        lines.append(f"### {name}")
+        lines.append("")
+        if 'properties' in schema_def:
+            lines.append("| Property | Type | Required |")
+            lines.append("|----------|------|----------|")
+            required = schema_def.get('required', [])
+            for prop, prop_def in schema_def['properties'].items():
+                prop_type = prop_def.get('type', prop_def.get('$ref', 'any'))
+                is_required = '✓' if prop in required else ''
+                lines.append(f"| `{prop}` | {prop_type} | {is_required} |")
+            lines.append("")
+    
+    with open(output_path, 'w', encoding='utf-8') as f:
+        f.write('\n'.join(lines))
+
+
+def extract_typescript(name: str, config: Dict[str, Any], output_base: Path) -> bool:
+    """提取 TypeScript 文档 (TypeDoc)"""
+    path = config['path']
+    output_dir = output_base / config['output']
+    
+    # 检查 TypeDoc 是否已安装
+    try:
+        result = subprocess.run(
+            ['npx', 'typedoc', '--version'],
+            cwd=path,
+            capture_output=True,
+            text=True
+        )
+        if result.returncode != 0:
+            print(f"  ⚠ TypeDoc not installed, installing...")
+            subprocess.run(
+                ['npm', 'install', '--save-dev', 'typedoc', 'typedoc-plugin-markdown'],
+                cwd=path,
+                check=True
+            )
+    except FileNotFoundError:
+        print(f"  ✗ npm/npx not found")
+        return False
+    
+    # 运行 TypeDoc
+    try:
+        entries = config.get('entries', ['lib'])
+        cmd = [
+            'npx', 'typedoc',
+            '--plugin', 'typedoc-plugin-markdown',
+            '--out', str(output_dir),
+            '--entryPointStrategy', 'expand',
+            '--exclude', '**/node_modules/**',
+            '--exclude', '**/*.test.*',
+            '--readme', 'none'
+        ]
+        for entry in entries:
+            entry_path = path / entry
+            if entry_path.exists():
+                cmd.extend(['--entryPoints', str(entry_path)])
+        
+        result = subprocess.run(cmd, cwd=path, capture_output=True, text=True)
+        
+        if result.returncode == 0:
+            print(f"  ✓ TypeDoc generated → {output_dir}")
+            return True
+        else:
+            print(f"  ✗ TypeDoc error: {result.stderr[:200]}")
+            return False
+            
+    except Exception as e:
+        print(f"  ✗ Error: {e}")
+        return False
+
+
+def extract_python_module(name: str, config: Dict[str, Any], output_base: Path) -> bool:
+    """提取 Python 模块文档 (pdoc)"""
+    path = config['path']
+    output_dir = output_base / config['output']
+    module_name = path.name
+    
+    # 检查 pdoc
+    try:
+        subprocess.run(['pdoc', '--version'], capture_output=True, check=True)
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        print(f"  ⚠ pdoc not installed, installing...")
+        subprocess.run([sys.executable, '-m', 'pip', 'install', 'pdoc'], check=True)
+    
+    # 运行 pdoc
+    try:
+        result = subprocess.run(
+            [
+                'pdoc', module_name,
+                '--output-dir', str(output_dir),
+                '--format', 'markdown'
+            ],
+            cwd=path.parent,
+            capture_output=True,
+            text=True
+        )
+        
+        if result.returncode == 0:
+            # 统计生成的文件
+            md_files = list(output_dir.glob('**/*.md'))
+            print(f"  ✓ pdoc generated {len(md_files)} files → {output_dir}")
+            return True
+        else:
+            print(f"  ✗ pdoc error: {result.stderr[:200]}")
+            return False
+            
+    except Exception as e:
+        print(f"  ✗ Error: {e}")
+        return False
+
+
+EXTRACTORS = {
+    'fastapi': extract_fastapi,
+    'typescript': extract_typescript,
+    'python': extract_python_module
+}
+
+
+def main(output_base: Optional[str] = None, projects: Optional[list] = None):
+    """主入口"""
+    base = Path(output_base) if output_base else Path.cwd()
+    
+    print("=" * 50)
+    print("API Documentation Extraction")
+    print("=" * 50)
+    
+    results = {}
+    
+    for name, config in PROJECTS.items():
+        if projects and name not in projects:
+            continue
+            
+        print(f"\n[{name}] ({config['type']})")
+        
+        if not config['path'].exists():
+            print(f"  ✗ Path not found: {config['path']}")
+            results[name] = False
+            continue
+        
+        extractor = EXTRACTORS.get(config['type'])
+        if extractor:
+            results[name] = extractor(name, config, base)
+        else:
+            print(f"  ✗ Unknown type: {config['type']}")
+            results[name] = False
+    
+    # 汇总
+    print("\n" + "=" * 50)
+    print("Summary")
+    print("=" * 50)
+    success = sum(1 for v in results.values() if v)
+    print(f"Success: {success}/{len(results)}")
+    
+    return all(results.values())
+
+
+if __name__ == '__main__':
+    import argparse
+    
+    parser = argparse.ArgumentParser(description='Extract API documentation')
+    parser.add_argument('--output', '-o', default='.', help='Output base directory')
+    parser.add_argument('--projects', '-p', nargs='+', help='Specific projects to extract')
+    
+    args = parser.parse_args()
+    
+    success = main(args.output, args.projects)
+    sys.exit(0 if success else 1)

package/.claude/skills/software-manual/scripts/screenshot-helper.md

@@ -0,0 +1,447 @@
+# Screenshot Helper
+
+Guide for capturing screenshots using Chrome MCP.
+
+## Overview
+
+This script helps capture screenshots of web interfaces for the software manual using Chrome MCP or fallback methods.
+
+## Chrome MCP Prerequisites
+
+### Check MCP Availability
+
+```javascript
+async function checkChromeMCPAvailability() {
+  try {
+    // Attempt to get Chrome version via MCP
+    const version = await mcp__chrome__getVersion();
+    return {
+      available: true,
+      browser: version.browser,
+      version: version.version
+    };
+  } catch (error) {
+    return {
+      available: false,
+      error: error.message
+    };
+  }
+}
+```
+
+### MCP Configuration
+
+Expected Claude configuration for Chrome MCP:
+
+```json
+{
+  "mcpServers": {
+    "chrome": {
+      "command": "npx",
+      "args": ["@anthropic-ai/mcp-chrome"],
+      "env": {
+        "CHROME_PATH": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
+      }
+    }
+  }
+}
+```
+
+## Screenshot Workflow
+
+### Step 1: Prepare Environment
+
+```javascript
+async function prepareScreenshotEnvironment(workDir, config) {
+  const screenshotDir = `${workDir}/screenshots`;
+
+  // Create directory
+  Bash({ command: `mkdir -p "${screenshotDir}"` });
+
+  // Check Chrome MCP
+  const chromeMCP = await checkChromeMCPAvailability();
+
+  if (!chromeMCP.available) {
+    console.log('Chrome MCP not available. Will generate manual guide.');
+    return { mode: 'manual' };
+  }
+
+  // Start development server if needed
+  if (config.screenshot_config?.dev_command) {
+    const server = await startDevServer(config);
+    return { mode: 'auto', server, screenshotDir };
+  }
+
+  return { mode: 'auto', screenshotDir };
+}
+```
+
+### Step 2: Start Development Server
+
+```javascript
+async function startDevServer(config) {
+  const devCommand = config.screenshot_config.dev_command;
+  const devUrl = config.screenshot_config.dev_url;
+
+  // Start server in background
+  const server = Bash({
+    command: devCommand,
+    run_in_background: true
+  });
+
+  console.log(`Starting dev server: ${devCommand}`);
+
+  // Wait for server to be ready
+  const ready = await waitForServer(devUrl, 30000);
+
+  if (!ready) {
+    throw new Error(`Server at ${devUrl} did not start in time`);
+  }
+
+  console.log(`Dev server ready at ${devUrl}`);
+
+  return server;
+}
+
+async function waitForServer(url, timeout = 30000) {
+  const start = Date.now();
+
+  while (Date.now() - start < timeout) {
+    try {
+      const response = await fetch(url, { method: 'HEAD' });
+      if (response.ok) return true;
+    } catch (e) {
+      // Server not ready
+    }
+    await sleep(1000);
+  }
+
+  return false;
+}
+```
+
+### Step 3: Capture Screenshots
+
+```javascript
+async function captureScreenshots(screenshots, config, workDir) {
+  const results = {
+    captured: [],
+    failed: []
+  };
+
+  const devUrl = config.screenshot_config.dev_url;
+  const screenshotDir = `${workDir}/screenshots`;
+
+  for (const ss of screenshots) {
+    try {
+      // Build full URL
+      const fullUrl = new URL(ss.url, devUrl).href;
+
+      console.log(`Capturing: ${ss.id} (${fullUrl})`);
+
+      // Configure capture options
+      const options = {
+        url: fullUrl,
+        viewport: { width: 1280, height: 800 },
+        fullPage: ss.fullPage || false
+      };
+
+      // Wait for specific element if specified
+      if (ss.wait_for) {
+        options.waitFor = ss.wait_for;
+      }
+
+      // Capture specific element if selector provided
+      if (ss.selector) {
+        options.selector = ss.selector;
+      }
+
+      // Add delay for animations
+      await sleep(500);
+
+      // Capture via Chrome MCP
+      const result = await mcp__chrome__screenshot(options);
+
+      // Save as PNG
+      const filename = `${ss.id}.png`;
+      Write(`${screenshotDir}/${filename}`, result.data, { encoding: 'base64' });
+
+      results.captured.push({
+        id: ss.id,
+        file: filename,
+        url: ss.url,
+        description: ss.description,
+        size: result.data.length
+      });
+
+    } catch (error) {
+      console.error(`Failed to capture ${ss.id}:`, error.message);
+      results.failed.push({
+        id: ss.id,
+        url: ss.url,
+        error: error.message
+      });
+    }
+  }
+
+  return results;
+}
+```
+
+### Step 4: Generate Manifest
+
+```javascript
+function generateScreenshotManifest(results, workDir) {
+  const manifest = {
+    generated: new Date().toISOString(),
+    total: results.captured.length + results.failed.length,
+    captured: results.captured.length,
+    failed: results.failed.length,
+    screenshots: results.captured,
+    failures: results.failed
+  };
+
+  Write(`${workDir}/screenshots/screenshots-manifest.json`,
+        JSON.stringify(manifest, null, 2));
+
+  return manifest;
+}
+```
+
+### Step 5: Cleanup
+
+```javascript
+async function cleanupScreenshotEnvironment(env) {
+  if (env.server) {
+    console.log('Stopping dev server...');
+    KillShell({ shell_id: env.server.task_id });
+  }
+}
+```
+
+## Main Runner
+
+```javascript
+async function runScreenshotCapture(workDir, screenshots) {
+  const config = JSON.parse(Read(`${workDir}/manual-config.json`));
+
+  // Prepare environment
+  const env = await prepareScreenshotEnvironment(workDir, config);
+
+  if (env.mode === 'manual') {
+    // Generate manual capture guide
+    generateManualCaptureGuide(screenshots, workDir);
+    return { success: false, mode: 'manual' };
+  }
+
+  try {
+    // Capture screenshots
+    const results = await captureScreenshots(screenshots, config, workDir);
+
+    // Generate manifest
+    const manifest = generateScreenshotManifest(results, workDir);
+
+    // Generate manual guide for failed captures
+    if (results.failed.length > 0) {
+      generateManualCaptureGuide(results.failed, workDir);
+    }
+
+    return {
+      success: true,
+      captured: results.captured.length,
+      failed: results.failed.length,
+      manifest
+    };
+
+  } finally {
+    // Cleanup
+    await cleanupScreenshotEnvironment(env);
+  }
+}
+```
+
+## Manual Capture Fallback
+
+When Chrome MCP is unavailable:
+
+```javascript
+function generateManualCaptureGuide(screenshots, workDir) {
+  const guide = `
+# Manual Screenshot Capture Guide
+
+Chrome MCP is not available. Please capture screenshots manually.
+
+## Prerequisites
+
+1. Start your development server
+2. Open a browser
+3. Use a screenshot tool (Snipping Tool, Screenshot, etc.)
+
+## Screenshots Required
+
+${screenshots.map((ss, i) => `
+### ${i + 1}. ${ss.id}
+
+- **URL**: ${ss.url}
+- **Description**: ${ss.description}
+- **Save as**: \`screenshots/${ss.id}.png\`
+${ss.selector ? `- **Capture area**: \`${ss.selector}\` element only` : '- **Type**: Full page or viewport'}
+${ss.wait_for ? `- **Wait for**: \`${ss.wait_for}\` to be visible` : ''}
+
+**Steps:**
+1. Navigate to ${ss.url}
+${ss.wait_for ? `2. Wait for ${ss.wait_for} to appear` : ''}
+${ss.selector ? `2. Capture only the ${ss.selector} area` : '2. Capture the full viewport'}
+3. Save as \`${ss.id}.png\`
+`).join('\n')}
+
+## After Capturing
+
+1. Place all PNG files in the \`screenshots/\` directory
+2. Ensure filenames match exactly (case-sensitive)
+3. Run Phase 5 (HTML Assembly) to continue
+
+## Screenshot Specifications
+
+- **Format**: PNG
+- **Width**: 1280px recommended
+- **Quality**: High
+- **Annotations**: None (add in post-processing if needed)
+`;
+
+  Write(`${workDir}/screenshots/MANUAL_CAPTURE.md`, guide);
+}
+```
+
+## Advanced Options
+
+### Viewport Sizes
+
+```javascript
+const viewportPresets = {
+  desktop: { width: 1280, height: 800 },
+  tablet: { width: 768, height: 1024 },
+  mobile: { width: 375, height: 667 },
+  wide: { width: 1920, height: 1080 }
+};
+
+async function captureResponsive(ss, config, workDir) {
+  const results = [];
+
+  for (const [name, viewport] of Object.entries(viewportPresets)) {
+    const result = await mcp__chrome__screenshot({
+      url: ss.url,
+      viewport
+    });
+
+    const filename = `${ss.id}-${name}.png`;
+    Write(`${workDir}/screenshots/${filename}`, result.data, { encoding: 'base64' });
+
+    results.push({ viewport: name, file: filename });
+  }
+
+  return results;
+}
+```
+
+### Before/After Comparisons
+
+```javascript
+async function captureInteraction(ss, config, workDir) {
+  const baseUrl = config.screenshot_config.dev_url;
+  const fullUrl = new URL(ss.url, baseUrl).href;
+
+  // Capture before state
+  const before = await mcp__chrome__screenshot({
+    url: fullUrl,
+    viewport: { width: 1280, height: 800 }
+  });
+  Write(`${workDir}/screenshots/${ss.id}-before.png`, before.data, { encoding: 'base64' });
+
+  // Perform interaction (click, type, etc.)
+  if (ss.interaction) {
+    await mcp__chrome__click({ selector: ss.interaction.click });
+    await sleep(500);
+  }
+
+  // Capture after state
+  const after = await mcp__chrome__screenshot({
+    url: fullUrl,
+    viewport: { width: 1280, height: 800 }
+  });
+  Write(`${workDir}/screenshots/${ss.id}-after.png`, after.data, { encoding: 'base64' });
+
+  return {
+    before: `${ss.id}-before.png`,
+    after: `${ss.id}-after.png`
+  };
+}
+```
+
+### Screenshot Annotation
+
+```javascript
+function generateAnnotationGuide(screenshots, workDir) {
+  const guide = `
+# Screenshot Annotation Guide
+
+For screenshots requiring callouts or highlights:
+
+## Tools
+- macOS: Preview, Skitch
+- Windows: Snipping Tool, ShareX
+- Cross-platform: Greenshot, Lightshot
+
+## Annotation Guidelines
+
+1. **Callouts**: Use numbered circles (1, 2, 3)
+2. **Highlights**: Use semi-transparent rectangles
+3. **Arrows**: Point from text to element
+4. **Text**: Use sans-serif font, 12-14pt
+
+## Color Scheme
+
+- Primary: #0d6efd (blue)
+- Secondary: #6c757d (gray)
+- Success: #198754 (green)
+- Warning: #ffc107 (yellow)
+- Danger: #dc3545 (red)
+
+## Screenshots Needing Annotation
+
+${screenshots.filter(s => s.annotate).map(ss => `
+- **${ss.id}**: ${ss.description}
+  - Highlight: ${ss.annotate.highlight || 'N/A'}
+  - Callouts: ${ss.annotate.callouts?.join(', ') || 'N/A'}
+`).join('\n')}
+`;
+
+  Write(`${workDir}/screenshots/ANNOTATION_GUIDE.md`, guide);
+}
+```
+
+## Troubleshooting
+
+### Chrome MCP Not Found
+
+1. Check Claude MCP configuration
+2. Verify Chrome is installed
+3. Check CHROME_PATH environment variable
+
+### Screenshots Are Blank
+
+1. Increase wait time before capture
+2. Check if page requires authentication
+3. Verify URL is correct
+
+### Elements Not Visible
+
+1. Scroll element into view
+2. Expand collapsed sections
+3. Wait for animations to complete
+
+### Server Not Starting
+
+1. Check if port is already in use
+2. Verify dev command is correct
+3. Check for startup errors in logs