awwwards-doctor

Awwwards MCP 诊断工具

你正在修复 awwwards-mcp 工具链，或是在任务进行中设法绕过问题。 按以下顺序操作：诊断 → 机械修复 → 修复解析器（如果发生偏移）→ 恢复用户的任务。绝不要删除用户数据；唯一具有破坏性的步骤（将缓存数据库移至一旁）会保留旧文件——使用 --fix 时将其放在操作系统临时目录中，手动重置时则在完整备份后将其放在缓存旁边。

配置说明： 此技能的工具包括 search_sites、get_site_details、 capture_live_site、analyze_page_structure、capture_component、 export_design_tokens 和 analyze_images。以下示例使用这些 1.x 名称（默认的 full 配置）。在 AWWWARDS_MCP_PROFILE=v2 时，请改用 search_references {request:{kind:"sites", ...}}、 get_reference {request:{kind:"site_details", slug}}、 capture_page {request:{kind:"screenshot", url}}、 inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"component", url}}、 inspect_page {request:{kind:"tokens", url}} 和 audit_page {request:{kind:"images", url}}。完整映射： v2-routing.md。

1. 运行诊断工具（awwwards-mcp 源代码检出目录）

请在 awwwards-mcp 源代码检出目录的根目录下运行以下命令 (github.com/INSANE0777/Awwwards-mcp)， 也就是 package.json 中项目名为 awwwards-mcp 的仓库——不要在 awwwards-skills 检出目录中运行。npm 包不包含这些脚本；如果你已安装该服务，请改用第 3 节。

npm run doctor             # diagnose only
npm run doctor -- --fix    # diagnose AND apply available fixes
npm run doctor -- --json   # machine-readable report

诊断工具会检查五项内容，并能修复其中可机械修复的问题：

检查项	失败含义	--fix 的操作
network	awwwards.com 阻止或质疑了请求	本地无法修复——请等待后再试；切勿循环重试
parser-drift	awwwards.com 的标记语言已发生变化，导致解析器偏移	将原始实时页面保存到 docs/drift-<timestamp>/（已被 Git 忽略），作为修复所用的测试样本
playwright-chromium / ffmpeg-static	缺少可选的捕获依赖项，或依赖项损坏	安装这些依赖项（开发依赖项 + npx playwright install chromium）
cache	SQLite 数据库损坏、被锁定，或索引超过 30 天	将无法读取的数据库移至一旁（保留在临时目录中），并通过 npm run index 重建
boot	dist/cli.js 无法启动	npm run build

修复后重新运行诊断工具；只有结果为 HEALTHY，才能宣称 MCP 已修复。

2. 修复真实的解析器漂移（唯一的代码级故障）

如果 doctor 报告 parser-drift，锚点探测会指出哪个解析器出了问题。 修复流程——按步骤机械执行，并在每一步验证：

1. 收集证据：docs/drift-*/ 中的 --fix 快照就是真实依据。（每日 GitHub Action 也会创建或更新一个 parser-drift 跟踪 issue，并列出发生漂移的锚点名称。）
2. 定位新锚点：打开捕获的 HTML，找到替代旧锚点的标记（按旧锚点的用途搜索，例如卡片 JSON 数据块、Elements 部分标题、og:image 元标记）。
3. 重新锚定解析器：在 src/parsers.ts 中做最小必要修改（一个 split/indexOf/正则字面量），不要改动周边逻辑。
4. 更新探测列表：在 scripts/parser-drift-probe.mjs 中（同一个 awwwards-mcp 检出目录；PROBE_GROUPS）更新探测列表，以便下次能检测到同样的问题。
5. 刷新测试样例：使用客户端相同的 UA 下载实时页面，并替换 test/fixtures/listing.html（或详情页测试样例）。离线测试只针对测试样例运行——刷新后的测试样例可证明重新锚定符合实际情况。
6. npm run typecheck && npm test ——所有测试都必须通过。
7. 提交信息使用 fix: re-anchor <parser> after awwwards.com markup change，并注明跟踪 issue。

注意：年度奖项工具（get_annual_*）来自官方 JSON API（src/annual.ts），而非解析器；扩展的奖项分类列表（sites_of_the_month/year、nominees、winner_category_*）在 test/fixtures/awards/ 下有各自精简的测试样例——这些锚点发生漂移时，也要与每日列表的测试样例一并刷新。

3. 最终用户（通过 npm 安装，而非检出代码库）

doctor 脚本位于代码库中，因此对于通过 npm 安装的服务：

1. 检查版本通知：如果有更新版本的 awwwards-mcp，启动时会在 stderr 输出提示。使用 npm install -g awwwards-mcp@latest 更新（或清除 npx 缓存），然后重启 Agent——许多“故障”报告其实是较旧的解析器，而较新版本已经修复了这些问题。 在 MCP 服务环境中设置 AWWWARDS_AUTO_UPDATE=1，即可选择在启动时后台自动更新。

2. **先备份，再只重置数据库。**先停止 Agent/MCP 服务，避免数据库正在写入。使用 CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}" 确定缓存根目录（服务读取的也是同一个变量）。先将其复制到其他位置，然后只移动 SQLite 文件；下次索引或运行时会重建这些文件：

   CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}"
   STAMP="$(date +%Y%m%d-%H%M%S)"
   cp -R "$CACHE" "$CACHE.backup-$STAMP"
   mkdir -p "$CACHE.moved-$STAMP"
   for f in "$CACHE"/cache.db*; do [ -e "$f" ] && mv "$f" "$CACHE.moved-$STAMP/"; done
   

   如果直接删除整个缓存根目录，也会销毁 preferences.json（设置选项）、skill-memory/findings.jsonl（已学习的发现）、获奖者监控数据（cache.db 中的行），以及 images/ 和 scene-captures/ 中的捕获文件。定向重置只会丢失搜索索引和监控数据——索引会重建，监控项必须重新添加——而设置选项、已学习的发现和捕获文件都会保留。切勿对缓存根目录执行 rm -rf。

3. 如果问题仍未解决，则属于上游问题（屏蔽或漂移）：请在 awwwards-mcp 代码库中提交 issue，并附上故障 URL 的原始 HTML。

4. 恢复正在进行的任务（也就是你发现问题的原因）

用户的构建或研究不会等你修复。请优雅降级：

• 过期缓存是你的好帮手：实时抓取失败时，search_sites/get_site_details 会提供缓存数据——在回复中说明这一点（“7 天前的缓存数据”）。
• BlockedError 表示停止，而不是重试：客户端绝不会在遭到拦截时继续重试；请告知用户，并继续使用缓存或备用数据。
• 捕获工具不可用（缺少 playwright）：改用 get_site_details 截图（由 CDN 提供，无需浏览器），直到 npm run doctor -- --fix 恢复 chromium。
• 令牌／图像工具不可用：export_design_tokens 会复用 capture_component 包（需要相同的 playwright/chromium）；analyze_images 也需要相同的浏览器。缺少 playwright 时，两者都会返回原始浏览器／模块错误（例如 Cannot find package 'playwright'），而不是友好的安装提示——只有 capture_live_site / analyze_page_structure 这两个工具会返回提示。缓存的 get_site_details 截图是备用方案。analyze_images 绝不会下载资源——没有图像表示页面没有 <img> 元素（内容使用 canvas／CSS 背景），或者扫描未找到图像，并不表示审计出错。
• 只有一条带状截图、有预加载器，或返回 mode:"anchors"：1.14 会检测内部滚动根（scrollRoot），并等待全屏加载器消失；1.15 会为内部滚动页面返回 mode:"anchors"——沿滚动容器生成 6 张有序的视口截图，作为 JSON 路径（anchors[].scrollTop/file），不包含内嵌图像。这是如实的成功结果，不是捕获出错；若要获取一张明确的视口截图，请使用 scrollCapture:"viewport"。scrollRoot 重新查询错误（匹配数为 0 或大于 1）表示扫描与截图之间 DOM 发生了变化——请重新运行，或报告标签和匹配数。如果页面仍只返回一条带状截图，其内容可能位于 shadow DOM 或 canvas 中；请检查并报告限制，不要将其视为完整的长图。
• 任务中途解析器发生偏移：结果可能部分为空（例如有详情，但没有配色）。请指出缺少的部分；不要悄悄把降级数据当作完整数据呈现。
• MCP 恢复正常后，重新运行失败的调用，并与备用方案产生的结果进行核对。

完成反馈闭环

修复经验价值最高，也最难得。成功诊断并修复后，在 awwwards-skills 仓库的工作区中（已安装的技能副本不包含此开发脚本）运行： node scripts/skill-memory.mjs record --skill awwwards-doctor --phase repair --symptom "..." --rule "..." [--evidence <report path>]。Distill 会将反复出现的故障特征整理并合并到已安装副本中，让下一次修复一开始就能利用这些经验。规则经验证有效后，运行 promote --skill awwwards-doctor，它会输出清理后的规则（不含本机证据路径），供已发布副本的 PR 使用。

反模式

• 循环重试遭拦截的请求——礼貌规则和拦截检测的存在，正是为了避免不断请求 awwwards.com。
• 通过比较原始 HTML 检测偏移——页面外观变化会导致每天误报；只有解析器锚点探测才有意义。
• 通过放宽解析器来“修复”它们，让它们悄悄返回空结果——解析器找不到锚点时必须明确报错（这就是偏移信号）。
• 为了“重置”而一概删除缓存根目录——这会毁掉偏好设置、已学习的发现、优选项监控和捕获结果。先备份，再仅移动 cache.db*。
• 因为有一项检查通过，就把医生判定为 UNHEALTHY 当作已完成。