深度解析UI Skills架构Astro Cloudflare Workers的Serverless实现全指南【免费下载链接】ui-skillsSkills for Design Engineers项目地址: https://gitcode.com/GitHub_Trending/ui/ui-skillsUI Skills 是一个专为设计工程师打造的「UI 技能库」项目它基于Astro 框架 Cloudflare Workers构建了一个纯 Serverless 的网站既能被人类浏览又能被 AI Agent 直接调用。本文将带你快速理解它的整体架构、部署方式以及它如何在一个轻量级站点里同时服务「浏览器用户」和「智能体」两种访客。一、技术栈全景为什么选 Astro Cloudflare Workers在深入源码之前先看一眼 package.json 里的核心依赖项目选型非常克制技术版本作用astro5.x内容优先的静态/混合渲染框架astrojs/cloudflare12.x把构建产物编译为 Cloudflare Workerreact 19 base-ui/react19.x少量交互式组件命令面板、复制按钮等tailwindcss 44.x原子化样式shiki3.x代码块语法高亮markdown-for-agents1.x将 HTML 转换为 Agent 友好的 Markdown关键配置在 astro.config.mjs 中只有几行代码却揭示了整个架构的骨架output: server—— 开启 SSR/混合渲染模式允许存在服务端 API 路由adapter: cloudflare({ imageService: compile })—— 使用官方 Cloudflare 适配器图片处理在构建期编译运行零额外成本integrations: [react()]—— 只在需要交互的岛屿island中引入 React其余页面保持纯 Astro 的高性能。这种组合意味着大部分页面在构建期预渲染成静态资源少数 API如 MCP 端点在 Edge 上按需执行无需维护任何服务器。二、部署形态Worker 如何接管请求构建产物如何映射到 Cloudflare答案在 wrangler.jsoncmain: ./dist/_worker.js/index.js // Worker 入口由 Astro 适配器生成 assets: { directory: ./dist, run_worker_first: false } compatibility_flags: [nodejs_compat]这里的部署策略很值得借鉴静态资源优先run_worker_first: false表示静态资产HTML、CSS、图片直接由 Cloudflare 的边缘 CDN 返回不触发 Worker 计算带宽和延迟成本最低Worker 兜底动态路由只有静态资源没命中时如/mcp、/oauth/token、/api/github-stars请求才进入 Worker 执行服务端逻辑Node 兼容层nodejs_compat标志让 Astro 生态中依赖 Node API 的包能在 Edge 环境正常运行。一句话概括能静态就静态必须动态才上 Worker—— 这是该项目 Serverless 成本优化的核心思路。三、双受众设计同时服务人类与 AI AgentUI Skills 最有意思的地方在于它把「AI Agent 也是访客」当成一等公民来设计。3.1 Markdown 协商Accept 头谈判普通页面是 HTML但 AI Agent 更想要 Markdown。项目在 src/middleware.ts 中挂载了一个全局中间件每个响应都会经过 src/lib/markdown-negotiation.ts 检查解析请求的Accept头若 Agent显式偏好text/markdown按 q 值与顺序协商规则与 Cloudflare 一致就把 HTML 响应转换为精简 Markdown 返回并附上x-markdown-tokens等元数据头告知 Token 消耗同时设置Vary: Accept让 CDN 正确缓存两种形态。浏览器照常看到网页Agent 拿到纯文本——同一份路由两种体验3.2 标准化发现协议Agent 不知道你的 API 在哪项目在 src/lib/agent-discovery.ts 中实现了标准化的「自描述」能力通过RFC 8288 Link 头在每个响应上挂载/.well-known/系列入口llms.txt、MCP 服务卡片、OAuth 元数据、站点地图等提供符合RFC 9727的 API Catalog/.well-known/api-catalog像一份「API 目录清单」根路径的 src/pages/llms.txt.ts 输出 LLM 友好的站点索引src/pages/auth.md.ts 和 src/pages/design.md.ts 则以 Markdown 形式提供 Agent 认证与设计系统文档。四、MCP 端点让 Agent 直接查询技能库项目的「杀手级」功能是一个内置的 MCPModel Context Protocol服务实现于 src/lib/mcp-server.ts由 src/pages/mcp/rpc.ts 暴露为/mcp端点MCP 工具功能list_skills列出技能注册表支持关键词过滤get_skill按名称/slug 拉取技能 Markdown 全文这是一个基于JSON-RPC 2.0的无状态接口Agent 通过initialize→tools/list→tools/call三步即可把整个 UI 技能库当作工具来调用与 CLI 命令npx ui-skills list返回完全一致的目录数据。技能数据本身由 src/data/skills.ts、src/data/registry.ts 和 src/data/topics.ts 三个数据模块组织页面路由的生成逻辑集中在 src/lib/skill-catalog.ts供 src/pages/skills/[...slug].astro 这类动态路由在构建期批量产出。五、CLI 与站点的数据一致性仓库同时发布了一个命令行工具bin/ui-skills.js支持start、categories、list、get等子命令。其命令构建逻辑见 src/lib/ui-skills-cli.ts。值得注意的是 scripts/ 目录下的三个构建脚本scripts/precompute-agent-skills-digests.mjs构建前预计算技能内容的摘要指纹写入 src/data/agent-skills-digests.json供 Agent 判断内容是否变化scripts/check-registry-skills.mjs校验注册表与技能源文件一致scripts/write-assetsignore.mjs构建后生成静态资源清单供 Cloudflare 部署使用。这套「数据即内容 构建期校验」的流程保证了网页、CLI、MCP、llms.txt 四个出口输出同一份数据不会出现口径不一致。六、本地运行与快速上手想亲自体验这套架构只需三步克隆仓库git clone https://gitcode.com/GitHub_Trending/ui/ui-skills安装依赖npm install本地开发npm run dev然后打开终端执行npx ui-skills start即可通过 CLI 让 Agent 路由到合适的 UI 技能集完整的类型检查、注册表校验、单元测试与冒烟测试被串成一条命令npm run check见 package.json测试用例分布在 tests/ 目录覆盖路由、Markdown 协商、MCP 发现、OAuth 等关键链路。七、值得借鉴的架构清单⚡混合渲染 静态优先output: server只用于真正的 API 路由页面尽量预渲染Edge 静态资源直出run_worker_first: false让 CDN 挡掉绝大多数请求Agent 友好层Accept 协商返回 Markdown RFC 8288 Link 头自描述 MCP 端点形成完整的「机器可读」链路单一数据源skills/registry/topics 三个数据模块同时驱动页面、CLI、MCP 与 llms.txt✅构建期校验digests 预计算 注册表一致性检查让内容变更可被机器感知。UI Skills 用不到两百行的核心配置演示了一个现代 Serverless 站点的完整姿势人类浏览走 CDNAgent 调用走 MCP数据只维护一份。如果你正在给自己的项目设计「AI 可读」的开放接口这套 Astro Cloudflare Workers 的实现思路非常值得抄作业 【免费下载链接】ui-skillsSkills for Design Engineers项目地址: https://gitcode.com/GitHub_Trending/ui/ui-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考