企业官网建设流程全解析

从文档截图到真实仪表盘：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 className="block dark:hidden" src={`${src}-light.png`} alt={alt} style={{ width, maxWidth: "100%", height: "auto" }} /> <img className="hidden 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、以及组件本身）。声明的完整契约如下：

capturedAt：用时间戳做优先级而非唯一判据

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 width="full" contenteditable="false">【免费下载链接】unkeyThe Developer Platform for Modern APIs项目地址: https://gitcode.com/GitHub_Trending/un/unkey