用途
本技能用于自动化捕获 MicroSim 可视化的高质量截图，使用 Chrome 无头模式（headless mode）实现。使用时机会包括：为需要社交媒体元数据（og:image）的 MicroSim 创建预览图；为 MicroSim 文档生成截图；捕获可视化用于质量评估或归档；配合 microsim-standardization 技能达成满分 100/100 的质量评分。
典型用户请求示例：
- “为此 MicroSim 创建一张截图”
- “我需要 org-chart MicroSim 的预览图”
- “为此可视化生成社交媒体预览图”
- “捕获 main.html 文件的截图”
主要能力
- 处理动态 JavaScript 内容与外部 CDN 库（如 vis-network.js、p5.js、Chart.js）
- 确保可视化在截图前有足够时间完整渲染
- 自动校验 MicroSim 目录、定位 main.html、提取名称并按约定命名截图
- 使用优化后的 Chrome 无头参数，兼容文件路径与 CDN 资源加载
使用方式
步骤 1：校验 MicroSim 目录
截图前需确认：
- MicroSim 目录存在于提供的路径（通常为 docs/sims/{microsim-name}/）
- 目录中存在 main.html 文件
- MicroSim 名称符合 kebab-case 约定（仅小写字母和短横线）
步骤 2：运行截图捕获脚本
使用 MicroSim 目录路径执行脚本：
bash scripts/capture-screenshot.sh <microsim-directory-path>
示例：
bash scripts/capture-screenshot.sh $HOME/Documents/ws/intro-to-graph/docs/sims/org-chart
脚本会：
- 从目录路径中提取 MicroSim 名称（例如从 .../sims/org-chart/ 提取 org-chart）
- 定位目录中的 main.html 文件
- 使用适用于 JavaScript 可视化渲染的最优参数运行 Chrome 无头模式
- 将截图保存为 MicroSim 目录中的 {microsim-name}.png（如 org-chart.png）
- 成功后显示输出文件路径和大小
使用的关键 Chrome 参数：
--headless=new：使用现代无头模式--disable-web-security+--allow-file-access-from-files：允许加载外部 CDN 资源（对 vis-network、p5.js 等至关重要）--timeout=5000：给 JavaScript 5 秒加载和渲染时间--window-size=1200,800：设置适合社交媒体预览的视口尺寸--hide-scrollbars：确保截图干净无滚动条痕迹
步骤 3：验证截图
脚本完成后：
- 确认图片文件已创建：{microsim-name}.png
- 验证文件大小合理（渲染后的可视化通常为 20-100KB）
- 使用 Read 工具查看截图，确认可视化渲染正常
- 若可视化区域空白/发白，说明 JavaScript 可能需要更多渲染时间，可尝试增大脚本中的 --timeout 值
步骤 4：更新 MicroSim 元数据（可选）
若作为 MicroSim 标准化的一部分进行截图，更新 index.md 的 YAML frontmatter：
---
title: MicroSim Title
description: Brief description
image: microsim-name.png
og:image: microsim-name.png
quality_score: 100
---
这会添加社交媒体预览元数据，并为质量评分贡献 10 分（元数据字段 5 分 + 图片文件存在 5 分）。
故障排查
截图捕获成功但可视化为空白
问题：截图显示页面标题/控件，但主可视化区域为白色/空白。
解决方案：
- 增大脚本中的超时值（将 --timeout=5000 改为 --timeout=10000）
- 检查浏览器控制台的 JavaScript 错误（脚本会过滤这些错误，但它们可能表明问题存在）
- 直接在浏览器中打开 main.html，确认可视化能正常工作
- 对于非常复杂的可视化，可考虑使用
--virtual-time-budget=10000替代--timeout
找不到 Chrome 错误
问题：脚本报告 “Chrome/Chromium not found”。
解决方案：
- 若未安装 Google Chrome，请先安装
- 更新脚本中的 CHROME_PATHS 数组，加入你的 Chrome 安装路径
- 在 macOS 上，Chrome 通常位于 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome
外部资源未加载
问题：使用 CDN 库（vis-network、p5.js、Chart.js）的可视化未渲染。
解决方案：脚本已包含 --disable-web-security 和 --allow-file-access-from-files 参数，应允许 CDN 资源加载。若仍无效：
- 确认网络连接正常（CDN 需可访问）
- 检查 main.html 中的库 CDN URL 是否有效
- 尝试改用 localhost 服务器，而非 file:// URL（见下文高级用法）
高级用法：使用 localhost 代替 file:// URL
对于使用 file:// URL 有问题的 MicroSim，可通过 HTTP 提供内容：
# 在项目根目录启动本地服务器
cd /path/to/project-root
python -m http.server 8000 &
# 修改脚本使用 localhost URL
# 将："file://$ABSOLUTE_PATH"
# 替换为："http://localhost:8000/docs/sims/microsim-name/main.html"
# 捕获截图
bash scripts/capture-screenshot.sh /path/to/microsim
# 停止服务器
pkill -f "http.server"
技术细节
为何使用 Chrome 无头模式
- JavaScript 支持：完整的 Chrome 渲染引擎可处理复杂 JavaScript 可视化
- CDN 加载：在正确参数下可获取 CDN 外部资源
- 时序控制：可在捕获前等待异步内容加载
- 跨平台：适用于 macOS、Linux 和 Windows
- 无需 GUI：可在 CI/CD 环境中运行
截图命名约定
脚本使用 MicroSim 目录名命名截图以保持一致：
- MicroSim：docs/sims/org-chart/ → 截图：org-chart.png
- MicroSim：docs/sims/learning-graph-viewer/ → 截图：learning-graph-viewer.png
与使用通用名称（如 preview.png）不同，这种命名方式：
- 查看目录时可立即明确文件用途
- 批量操作时更易识别截图属于哪个 MicroSim
- 遵循项目其他位置使用的命名约定
默认截图尺寸
默认视口为 1200x800 像素，原因如下：
- 宽度（1200px）：标准桌面视口，适合大多数可视化
- 高度（800px）：捕获标题 + 控件 + 可视化，避免过多留白
- 宽高比（3:2）：适合社交媒体 og:image 标签
- 文件大小：生成大小合理的 PNG 文件（通常 20-100KB）
如需自定义尺寸，修改脚本中的 --window-size 参数。
资源
scripts/capture-screenshot.sh：自动化整个截图捕获过程的 Bash 脚本。该脚本会：
- 校验输入并检查所需文件
- 跨平台定位 Chrome/Chromium
- 使用绝对路径构建正确的 file:// URL
- 以针对 JavaScript 可视化优化的参数运行 Chrome 无头模式
- 报告成功/失败及文件大小信息
该脚本设计为：
- 自包含：除 Chrome 外无外部依赖
- 跨平台：适用于 macOS、Linux 和 Windows（需少量路径调整）
- 容错：过滤不影响功能的常见 Chrome 无头模式警告
- 用户友好：清晰的错误消息和成功提示
限制
资料中未提供收费、价格或平台限制相关的明确信息。运行需本地安装 Chrome/Chromium，且脚本路径与参数可能需要根据实际环境调整。