从文档截图到真实仪表盘Unkey 文档截图自动刷新技能refreshing-docs-screenshots实战解析【免费下载链接】unkeyThe Developer Platform for Modern APIs项目地址: https://gitcode.com/GitHub_Trending/un/unkey本文围绕 Unkey 仓库中.agents/skills/refreshing-docs-screenshots/SKILL.md展开。该技能面向「产品文档截图审计/刷新」场景通过DashboardScreenshot声明与data-docs-target标记在真实本地仪表盘中复现文档所描述的界面状态只替换真正过期的图片。读完本文你将掌握这套声明驱动截图工作流的完整模式all / specific、DashboardScreenshot组件契约、真实仪表盘准备、隔离对话框截图的浏览器级处理以及验证与上报的完整流程并能在任何文档型仓库中复用同一思路。技能定位为什么文档截图需要一套自动化工作流Unkey 的产品文档docs/product中嵌入了大量仪表盘截图用于展示 Root Keys、权限面板、创建密钥对话框等界面。人工维护这些截图有两个痛点容易过期UI 一旦改版控件、布局、文案变化旧截图与真实仪表盘不一致误导读者难以校验截图是否与文档描述相符、是否包含敏感信息、是否双主题light/dark齐全靠肉眼很难系统化检查。refreshing-docs-screenshots技能的核心思路是把「截图应该长什么样」以声明形式写进文档把「真实仪表盘中的目标元素」用data-docs-target标记出来然后用 AI 选择种子数据与浏览器操作在真实本地仪表盘中复现状态并重新捕获。它不要求固定场景脚本也不构建替代 UI——一切以真实产品界面为准。技能支持两种运行模式all扫描docs/product/下所有DashboardScreenshot声明逐张对照当前仪表盘与周边文档检查刷新过期或缺失的图片准确图片保持不变并逐条报告 current / refreshed / blocked 状态specific target-or-src按根相对src路径或唯一target名称匹配单张截图只检查并刷新该截图及其主题变体若多个声明共用同一 target需进一步提供src若页面含多个声明需确认具体指哪一张遇到缺失或重复匹配即停止。典型请求示例「Use refreshing-docs-screenshots in all mode to check the product docs.」或「Use refreshing-docs-screenshots in specific mode for root-key-permissions.」月度巡检可用all模式但除非用户明确要求不要自行创建定时任务一次审计/刷新请求也不构成推送或 PR 授权。读取声明DashboardScreenshot组件与捕获元数据技能要求先阅读 docs/product/snippets/dashboard-screenshot.jsx 再解释其 props。该组件本体非常简洁export const DashboardScreenshot ({ src, alt, width }) ( img classNameblock dark:hidden src{${src}-light.png} alt{alt} style{{ width, maxWidth: 100%, height: auto }} / img classNamehidden dark:block src{${src}-dark.png} alt{alt} style{{ width, maxWidth: 100%, height: auto }} / / );关键点是组件只负责渲染图片不发射捕获元数据也不执行任何工作流。它根据src渲染${src}-light.png与${src}-dark.png两张图dark:hidden/hidden dark:block实现双主题切换width只是 CSS 像素下的最大显示宽度并非捕获视口。因此capturedAt、description、capture等元数据必须从 MDX 源码读取而不是从渲染后的文档 HTML 读取。查找声明用限定作用域的搜索rg -n DashboardScreenshot docs/product --glob *.mdx在仓库中实际命中三处root-keys/overview.mdx、root-keys/permissions.mdx、以及组件本身。声明的完整契约如下字段含义target真实仪表盘元素上data-docs-target属性的值description期望的数据、UI 状态、导航提示与捕获约束供 AI 复现状态capturetarget、viewport或full-page省略时默认targetsrc不含主题后缀与扩展名的根相对图片路径组件据此渲染${src}-light.png/${src}-dark.png同时充当插图标识无需单独idalt面向读者的图片描述width可选CSS 像素下的最大显示宽度不是捕获视口capturedAt保存捕获的 ISO 8601 UTC 时间戳例如2026-09-11T04:48:23Z只存在于 MDX 源码不进入文档 DOMcapturedAt用时间戳做优先级而非唯一判据capturedAt用于优先处理较旧或未知的捕获约一个月前的图片值得关注但「旧」本身不等于「过期」近期捕获在 UI 变更后同样可能失效。all模式下无论时间戳新旧每条声明都必须交代去向。缺失、无效或未来时间戳一律视为「未知」不能当作「新鲜」。时间戳记录的是捕获时刻不是最近一次审计时间不得用渲染时钟设置它也不得因为旧图看起来仍然正确就向前推进只有两张主题图都完成捕获、检查并保存后才能更新它对捕获历史未知的现有图片不要凭空编造时间戳。此外纯img形式的截图没有捕获指令应如实报告其不在本声明式工作流范围内不得静默宣称已检查也不得未经请求全部转换。例如 root-keys/overview.mdx 中的创建密钥对话框就是这种普通img。准备真实仪表盘安全、种子数据与目标定位在动手截图前技能要求先阅读仓库指引与 docs/engineering/contributing/local/development.mdx工具链统一使用mise并在启动任何东西前检查正在运行的服务尽量复用健康的本地栈。开发者机器上mise run dashboard是仪表盘设置任务对应 Makefile 中dashboard目标Makefile先复制.env模板用 docker compose 拉起依赖再pnpm dev。技能特别提醒运行前先阅读它的效果尤其是数据库播种seeding步骤。在 orb 环境使用声明的.amp/services.yaml服务与受监督的服务命令浏览器相关操作前加载using-agent-browser技能并与用户共享 portal URL 而非 localhost URL。数据安全红线确认本地认证与一次性本地数据库连接后再写入数据绝不把凭据或环境文件写进对话记录。只使用合成 fixture只创建描述所需的数据优先复用本地 seed 帮助程序或仪表盘正常创建流程禁止使用生产账号、共享数据库、真实客户数据或真实凭据本地安全环境不可用时停止一切依赖它的工作。目标元素定位在web/apps/dashboard/中必须使用既有路由和 UI不得为方便截图创建预览组件、模拟仪表盘或新路由。若标记缺失报告为 blocked除非用户授权添加标记被授权的标记应放在既有 DOM 容器上或放在会将该属性转发到该容器的组件上包括 portal 渲染的对话框内容。从源码可以印证data-docs-target的落点列表页根容器settings/root-keys/page.tsx/[workspaceSlug]/settings/root-keys/page.tsx#L17) 中PageContainer widthfull contenteditable="false">【免费下载链接】unkeyThe Developer Platform for Modern APIs项目地址: https://gitcode.com/GitHub_Trending/un/unkey创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考