SuperAPI AI 工具集

awwwards-atlas

编程与开发

查看项目

更新于 11-12 17:16

技能介绍

Awwwards Atlas 是 awwwards-mcp 1.19+ 中的实验性区块级证据层,建立在同一 SQLite 缓存之上,存放抓取记录、区域、组件摘要、声明、状态与工件,并支持检索与导出。它是选择性开启的功能:默认关闭,需在服务器启动时设置 AWWWARDS_MCP_ATLAS=1;该标志只在启动时读取一次,不支持热重载。仅适用于 awwwards-mcp 1.19.0 或更新版本,1.18.x 中不存在 Atlas 工具。

使用前准备 确认服务器版本并检查 search_atlas 或 get_atlas 是否存在;工具缺失说明标志未开,需让用户以 AWWWARDS_MCP_ATLAS=1 重启 MCP 服务器。全量档工具数量在标志关闭时为 41、开启时为 45;core 档均为 13;v2 档为 15 与 16。若会话报告 45 但缺少 get_atlas,可能是过期服务器或错误缓存。抓取前可用 get_atlas { "kind": "status" } 检查 enabled、revision、schema/FTS 版本、来源与抓取计数、租约状态和 FTS 可用性;空闲租约的 ttlSeconds 为 null。可用 AWWWARDS_MCP_ATLAS=1 awwwards-index --atlas import 从现有缓存离线填充 Atlas,该命令只投影缓存的条目页面与旧图库行,不会在之后执行抓取。

主要工具 search_atlas 搜索已存储的区块或组件,零网络请求;get_atlas 读取状态、分类法、单个区域或单个高亮;capture_atlas 对已知站点 slug 执行受控的实时抓取与发布;export_evidence_pack 为 1 至 12 个区域写出并校验本地证据包。v2 会话通过现有工具的分支调用:search_references 使用 request.kind 为 sections 或 components;get_reference 使用 atlas_region、atlas_highlight 或 atlas_taxonomy;get_index 使用 atlas_status;capture_page 使用 atlas;export_evidence_pack 为独立工具。标志关闭时 v2 的 Atlas 分支仍校验参数结构但返回 FEATURE_DISABLED,且不应把 1.x 名称混入 v2 会话。

典型工作流 先以文本查询或结构化谓词查找候选区域,而非直接抓取。kind 必须是 sections 或 components;scope 默认为 region,也可为 page 或 site;同一谓词内的多个值为 OR,谓词之间为 AND,同一字段的两个谓词会形成两个 AND 条件,可能返回零结果。evidenceMode 默认 candidate,accepted 只返回已接受标签且不含仅候选类型,observed_only 还要求有观测依据。state 为 hover 或 focus 时只查看该状态的声明,无状态证据则返回 insufficient_coverage。分页使用 nextCursor,它绑定查询与 revision,15 分钟后过期。empty_corpus 与 insufficient_coverage 表示未观测到,而非证明不存在。

随后检查证据:用 kind: "region" 加 64 位小写十六进制 regionId 读取抓取条件与来源身份、声明及其证据依据、工件描述符(available、state、hash、path)、父子摘要和当前或历史 head 状态。kind: "highlight" 可用于解析旧别名,歧义时返回 AMBIGUOUS_ALIAS 及候选 regionIds,且不会抓取旧图库页面。创建谓词前可用 kind: "taxonomy" 查看支持的字段、值、别名、范围、状态及明确不支持的操作。

缓存缺少证据时可调用 capture_atlas,传入缓存中的站点 slug(而非任意 URL),可指定 path、viewport(desktop 1440x900 或 mobile 390x844,每次一个)、components(默认 true)、refresh 与最多三个状态请求。path 必须以单个 / 开头,不能以 // 开头,且不得含 ?、# 或凭据。refresh: false 会复用最长七天内的可用活动 head;refresh: true 总是启动受控采集器。发布语义:cached: true 表示未执行新抓取;published: true 表示新 head 替换旧 head;published: false 且 cached: false 表示已采集但发布被拒,旧 head 保留。blocked 表示策略拒绝(如 ROBOTS_DENIED、PRIVATE_DESTINATION、BLOCKED_DESTINATION、HTTP_BLOCKED),inconclusive 包括 ROBOTS_UNAVAILABLE、NAVIGATION_FAILED、CAPTURE_TIMEOUT、CAPTURE_DEADLINE_EXCEEDED 与 TARGET_CHANGED。并发抓取返回可重试的 CAPTURE_BUSY,无排队机制;抓取预算 90 秒,租约 TTL 150 秒。采集限制包括:全新匿名上下文、不导入 Cookie 或会话;每个新文档与重定向前评估 robots,robots 5xx 视为不可用并推迟采集;启动前拒绝敏感查询参数,来源中脱敏凭据、查询与片段;不执行点击、输入、提交、拖拽、键盘导航或路由跳转;最多 120 个组件候选、12 个包、150 个节点、深度 12。

导出证据包时选择同一站点活动 head 上的 1 至 12 个不同区域,includeMedia 为 references 时只复制派生摘要,原始包、截图与素材仍以 id、path、hash 引用;为 permitted 时只复制由调用方声明的 owned、licensed 或 permission 且 scope 为 export_copy、引用非空的工件,未知、缺失、范围错误或受限工件会被排除并注明原因。不得替用户声明法律许可,声明仅记录不验证。证据包写入 <cache>/atlas/evidence-packs/<packId>/,无任意路径、覆盖开关、下载或分享操作;相同选择返回 cached: true,损坏包保留并返回 PACK_CORRUPT。

维护命令 所有维护动作均需开启标志,且与常规爬取互斥:import、capture(可指定 slug 与 viewport)、reindex、verify、prune。verify 为只读,不创建缓存、不迁移、不产生 WAL/SHM 伴随文件、不撤回 head;缓存缺失或无 Atlas 表时退出码为 1。prune 默认演练模式,仅在用户明确授权时加 --apply;活动 head、被证据包固定的抓取、运行中的抓取、较新的抓取与不安全路径受保护。reindex 重建 FTS 与投影,无变化时 revision 稳定。探测 CLI 行为时应把 AWWWARDS_CACHE_DIR 设为测试目录,否则默认使用 ~/.awwwards-mcp。

结果解读与限制 四个工具均返回 awwwards-atlas-v1 信封:ok 与 partial 携带 data,inconclusive 在可用时携带已解析证据(有时为 null),blocked 与 error 携带 data: null、isError: true 且无 structuredContent,消息不含堆栈或绝对路径。应报告 coverage.status、coverage.limitations、omitted、candidateOnly 与 candidateNote,而非把部分结果当作完整结果。当标志关闭、版本低于 1.19.0、slug 不在缓存、robots.txt 不可用或禁止访问、目标为私有/回环/元数据/保留地址、出现 CAPTURE_BUSY 等错误、import 无区域且无法抓取、导出跨站点或历史 head、权限未知却请求 permitted、或用户要求已接受的组件类型精度(该精度未测量)时,应停止并报告。不得把候选标签当作已验证分类法,不得宣称 95% 组件精度或“F9 通过”,不得称 Atlas 稳定、默认开启或已获离线认证,不得绕过 robots、私有地址检查、抓取租约或固定证据包目录,不得在无用户明确权利依据时复制第三方媒体,不得未经确认执行 prune --apply,并注意标志拼写为 AWWWARDS_MCP_ATLAS(双 W)。