参考调研助手 (ref-researcher) 是做什么的？

概述

ref-researcher 将原始的灵感素材——包括实时网站、设计画廊、应用录制、UI 截图或保存的 HTML——转化为一份带有观点且可直接执行的 .md 设计与产品行动手册，用于在设计或编码之前进行深入分析。

将此技能应用于移动应用功能、网页应用流程或营销网站，每当需要深入审视来自外部参考的视觉工艺、动效线索、文案模式以及反模式时，同时确保不偏离项目真实品牌令牌、平台规则和交付范围。

依赖项

协调使用以下已安装的技能，避免重复职责：

uv —— 通过 uv run 整洁地检查并调用 Python 命令行脚本（仅在严格离线/使用标准库且未安装 uv 时回退到 python3）。
chrome-devtools —— 渲染 JS 重度 SPA，检查实时布局/动画行为，并在静态 HTTP 抓取遇到客户端侧空壳（needs_browser_capture: true）或限网站点时，捕获全页面截图或交互式浏览器会话。
frontend-design —— 在综合网页应用或营销网站时，指导视觉观点、字体搭配、空间克制以及反模板批判。
apple-hig-designer —— 在综合移动应用功能或原生 Apple 设备展示时，验证原生 iOS/iPadOS/watchOS 组件保真度、安全区域、表单、动态字体和可访问性。

快速开始

可以从实时 URL（抓取公共 HTML/资产并捕获浏览器截图）或从现有本地参考文件夹开始：

# 1. 将保存的 HTML 参考抽取为结构化 JSON
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./Docs/References & Inspo" \
  --limit 25 \
  --output "/tmp/ref_html_summary.json"

# 2. 将超高截图切片 + 提取视频关键帧到临时目录（1024px 宽）
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./Docs/References & Inspo" \
  --scratch-dir "/tmp/ref_slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/ref_media_manifest.json"

实用脚本

所有程序化的抽取、切片、有礼貌的 HTTP 抓取和链接审计都位于 scripts/ref_researcher.py 中。每个命令需要显式限制和 --output <file.json>（仅向 stdout 输出简洁状态）。

1. `fetch-page` —— 有礼貌的公共 URL 与资产抓取器

从公共 URL 下载静态 HTML 以及顶层样式表和图片，同时检测登录墙、机器人挑战和客户端侧 JS 空壳（needs_browser_capture: true）。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py fetch-page \
  --url "https://example.com" \
  --asset-dir "./refs/example" \
  --max-assets 20 \
  --output "/tmp/fetch_example.json"

2. `extract-html` —— 代码、文案、字体和令牌抽取器

解析保存的 .html 和 .css 文件（最多 --limit 个），输出标题、导航链接、H1–H3 层级、CTA、正文文案样本、十六进制颜色、font-family 声明以及动画库线索（@keyframes、framer、gsap、lottie）。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./refs" \
  --limit 25 \
  --output "/tmp/html_summary.json"

3. `slice-media` —— 超高截图与视频关键帧切片器

读取真实图片像素尺寸（处理重命名的扩展名，如 .webp 后缀下的 JPEG），将超长的全页截图分割成清晰的 1024px 宽视口切片，并通过 ffmpeg 提取均匀间隔的 MP4/MOV/WebM 关键帧。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./refs" \
  --scratch-dir "<scratch_dir>/slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/slice_manifest.json"

工作区清洁： 始终将 --scratch-dir 指向对话临时目录（或 /tmp/），绝不放入用户的仓库工作区。

4. `verify-links` —— 手册资产链接审计器

验证生成的 .md 文件中的所有相对 Markdown 链接是否指向磁盘上的实际文件，如果有任何路径损坏，则退出并返回代码 1。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py verify-links \
  --markdown "./Docs/References & Inspo/PLAYBOOK.md" \
  --markdown "./Docs/References & Inspo/README.md" \
  --output "/tmp/verify_links.json"

工作流程

1. 首先审计目标产品与约束

在打开任何灵感链接之前，阅读目标项目的真实来源文档（PRD、品牌颜色/令牌、设计系统、平台约束）。记录：

目标表面： 移动应用功能、网页应用流程或营销网站。
视觉令牌与对比度陷阱： 精确的十六进制值和 WCAG AA 最低要求（例如，低对比度的暗色模式强调色）。
产品真相矩阵： 区分今天交付与路线图 / 禁止声明。

2. 收集参考（实时抓取、浏览器捕获或现有文件夹）

现有本地参考： 立即对提供的目录运行 extract-html 和 slice-media。
公共 URL / 从头开始调研：
1. 先运行 fetch-page 进行快速、限速的静态 HTML + 资产捕获。
2. 当 needs_browser_capture 为 true（React/Next/Vite CSR 空壳）或需要全页视觉截图时，使用 chrome-devtools 技能（或浏览器工作流）渲染并捕获全页图片/DOM。
3. 认证 / 被阻止站点协议（严格）： 如果站点返回 HTTP 401/403，重定向到 /login，或显示付费墙/机器人墙：
- 请用户先登录，然后重试最多 2 次。
- 如果 2 次重试后访问仍然失败，清晰记录被阻止的源并自动转向可访问的公共站点/页面或同行替代方案，以防进度停滞。

3. 视觉与程序化检查（绝不盲目翻阅未切片的高截图）

全页截图（3840w × 15000px+）如果整体查看会缩小成无法辨认的缩略图。始终通过 slice-media 生成的顺序视口切片，以及 extract-html 提取的文案/CSS 令牌，来检查所有收集的参考。
结合平台指南进行视觉研究：
- 调用 apple-hig-designer 关于 iOS/iPadOS 导航、表单、SF Symbols 和触控/动态字体人机工程学的提示。
- 调用 frontend-design 关于网页排版对比、有意的空白以及摒弃 AI 模板默认值的提示。

4. 综合生成 `.md` 行动手册

在目标项目的参考文件夹内，按照 references/playbook_template.md 编写交付手册。根据目标表面调整蓝图，但始终包含：

产品真相与约束矩阵（包括亮色/暗色对比度陷阱）
执行创意与 UX 方向
架构 / 屏幕流程蓝图
状态与边缘案例清单（空、加载/流式、部分/容量上限、错误/权限）
平台与响应式适配矩阵
排版、表面、动效与文案规则
严格的“该做与不该做”，引用批次中具体的正面和负面示例
索引参考资产查找表（相对 Markdown 链接）
预构建执行与 QA 检查清单

更新目录中的 README.md（如果存在），将新的行动手册置于顶部。

5. 验证所有相对链接

对行动手册（以及更新的 README.md）运行 verify-links。在向用户报告完成之前，修复所有非零退出。

限速

fetch-page 通过文件锁（/tmp/ref_researcher_fetch.lock）和单调时间戳（time.monotonic()）在并发的 agent 进程之间强制执行 1.0 请求/秒（REQUESTS_PER_SECOND = 1.0）。
HTTP 429 会触发指数退避（Retry-After 或 2^尝试次数）并记录到 stderr，然后抛出 RateLimitError。
HTTP 5xx 使用指数退避重试；永久性 HTTP 错误包括 URL 和截断的响应正文，以便快速诊断。

常见错误

直接检查未切片的 15,000px 高截图： 导致模糊的猜测和错过的微交互。始终先用 slice-media 切片。
永远绕过被阻止的登录或无休止地停滞在一个付费墙上： 请用户登录一次，最多重试 2 次，然后干净地转向可访问的源并记录差距。
盲目相信竞争对手的营销声明而不是自己的代码库/PRD： 复制同行“云同步”或“Mac 应用”的主打宣传会制造虚假的营销声明。始终通过产品真相矩阵筛选每个模式。
在项目仓库中留下损坏的相对链接或转储临时图片： 始终将切片写入临时目录，并在收尾前运行 verify-links。

参考调研助手 (ref-researcher)