企业官网建设流程全解析

Transitions.dev架构揭秘:动效扫描引擎、MCP Server与Cloudflare Worker托管修复服务如何实现

【免费下载链接】transitions.devUI montion AI agent, a library of 43+ crafted transitions, a skill that fits your workflow.项目地址: https://gitcode.com/gh_mirrors/tr/transitions.dev

Transitions.dev 是一个开源的 UI 动效 AI Agent 项目：它内置 43+ 个手工打磨的过渡动效配方库，并提供一个能扫描你的代码库、给出 0-100 动效评分、再用 AI 提出修复建议的智能体。本文将拆解它的三层核心架构——确定性的动效扫描引擎、MCP Server和基于 Cloudflare Worker 的托管修复服务，带你弄懂这套"AI 只动 CSS、不碰逻辑"的动效修复方案是如何落地运行的。

一、项目全景：库、Agent、Skill 三位一体

仓库的组织方式非常清晰，三大板块各司其职：

如果你想本地跑起来，可以克隆仓库：

git clone https://gitcode.com/gh_mirrors/tr/transitions.dev

二、动效扫描引擎：纯确定性规则，不花一分钱 AI 费

扫描引擎位于 agent/lib/，是整套系统里最"硬核"的部分。它的设计原则是：扫描完全确定性、免费、离线，AI 只在后续的修复环节出场。

1. 四步流水线

• 文件收集：agent/lib/walk.mjs 遍历仓库，收集 CSS、SCSS、JSX、Vue、Svelte 等样式与组件文件；
• 规则检查：agent/lib/rules.mjs 运行一套纯正则/词法级别的动效规则，例如transition: all、过长的 duration、hover 缺少过渡覆盖、缺少prefers-reduced-motion保护等；
• 组件识别：agent/lib/components.mjs 通过类名、ARIA 角色、组件名、Tailwind 工具类和 Framer Motion 属性，认出每一个 UI 组件（modal、dropdown、tooltip、toast、accordion、tabs……），读懂它的开/关时长、缓动、缩放，再与对应配方的"按用途匹配"的基准值对比；
• 评分汇总：agent/lib/scan.mjs 汇总所有发现，算出动效评分。

2. 评分怎么算出来的

评分算法在 agent/lib/scan.mjs 中一目了然：

• 每条发现按严重度加权：major扣 8 分、warn扣 4 分、info扣 2 分、minor扣 1 分；
• 每条规则设有扣分上限（如recipe-mismatch最多扣 32 分），防止单条"吵闹"规则把分数打到零；
• 最终得分映射为四档等级：90+ 是smooth，75+ 是decent，50+ 是janky，低于 50 是static。

扫描输出的发现分三类，恰好对应修复的三种形态：

三、MCP Server：你的 AI 来修，我方提供配方

第二个架构层是部署在api.transitions.dev/v1/agent/mcp的MCP Server（Model Context Protocol），源码在 agent/worker/mcp.mjs。

它的定位很独特：服务器上从不调用任何模型。你用自己的 Claude Code、Cursor 连过来，用自己的 token干活；Server 只负责提供 AI 无法自己知道的东西——扫描器契约、修复指引和真实的配方源码（Pro 配方按许可证发放）。

Server 暴露四个工具（见 agent/worker/mcp.mjs）：

1. scan_instructions—— 告诉你如何跑确定性扫描、每条发现什么意思；
2. fix_guidance(mode)—— 返回 polish 或 revamp 模式下的完整修复规则；
3. list_recipes—— 列出全部配方清单（slug、名称、tier）；
4. get_recipe(slug, variant)—— 拉取配方的权威源码（CSS / React / TypeScript 三种变体）。

配方的"物料"由 agent/worker/pack-recipes.mjs 打包进 Cloudflare KV 的RECIPES命名空间——配方更新后重跑一次打包即可。免费配方无需密钥；Pro 配方则校验许可证，且每月有 2000 次拉取的宽松额度（KV 存储本身免费，额度只为保护内容）。

四、Cloudflare Worker 托管修复服务：AI Key 只出现在服务端

第三个架构层是同 Worker 上的托管修复接口/v1/agent/fix，入口在 agent/worker/worker.mjs。这里藏着整套架构最核心的安全设计：Anthropic API Key 只存在服务端（secret ANTHROPIC_API_KEY），客户端只发自己的 license key + 扫描发现 + 受影响文件内容。

1. 一次修复请求的完整旅程

客户端 CLI → POST /v1/agent/fix（license key + findings + files） ① 校验许可证（LICENSES KV） ② 配额检查（USAGE KV：月度 / 每日 / 全局预算三重阀门） ③ revamp 模式从 RECIPES KV 加载真实配方源码 ④ 流式调用 Claude，要求返回"精确的搜索-替换编辑"而非整文件 ⑤ 服务端应用编辑（edits.mjs），完整文件原样返回 ⑥ 成功后才记账；失败永远不扣配额

几个值得细看的工程细节：

• 编辑式输出（agent/worker/worker.mjs）：模型只返回{"find": "...", "replace": "..."}级别的精确编辑，一个几百 token 的大组件修复只需几个 token，快且不会截断；agent/worker/edits.mjs 在服务端应用编辑，匹配不上或会破坏代码的编辑会被跳过并如实报告；
• 流式保活（agent/worker/worker.mjs）：长修复任务期间每 5 秒向响应流写一个空格，防止任何代理或客户端超时断开；
• 分级限流（agent/worker/wrangler.toml）：免费档用更快的 haiku 模型，10 次/月、5 次/天，外加一个FREE_GLOBAL_MONTHLY = 2000的全局月度预算熔丝，把免费档的 AI 花费硬性封顶在几十美元；付费档用 sonnet，200 次/月，不受免费池影响；
• 诚实的失败（agent/worker/worker.mjs）：模型过载、超时、上下文过大都映射为可读的错误语义（model_busy、model_timeout、too_large），并附带一句"本次未计入你的配额"。

2. 两种修复模式

五、GitHub Action：让 CI 替每个 PR 把关动效

架构的最后一环是 CI 集成。agent/templates/transitions-agent.yml 提供现成的工作流模板，npx transitions-agent init-ci一条命令即可装好：

• 每个 Pull Request 自动获得一条动效评分评论（含识别出的组件与发现），每次推送原地更新；
• 自动修复：有问题时向该 PR 的分支（绝不含 main）开一个修复 PR——合并即采纳，关闭即拒绝，描述里用人话解释用户会感知到什么（"打开从 800ms 变 250ms"、"关闭时会平滑退出而不是瞬间消失"）；
• 可选的min-score合并门禁，评分低于阈值直接挂掉检查。

agent/action/ 下的 autofix.mjs 与 comment.mjs 分别实现修复 PR 和评分评论，配合revamp/polish/no-motion-fix三个 PR 标签即可按单调整修复策略。

六、安全模型：为什么你可以放心把代码交给它

整套架构的信任边界设计得非常克制，四点值得记住：

1. 先 diff 后落盘——所有修复先以 diff 形式展示，没有一声"yes"不写任何文件；
2. PR 优先——--pr开在新分支上，团队评审、测试通过、人工合并才生效；
3. 全量 git 化——任何已合并的修复都离一次git revert那么远;
4. 只动动效——修复只碰 CSS 过渡与动画保护，永远不碰组件逻辑。

写在最后

Transitions.dev 的架构给了"AI 改代码"类项目一个很好的范本：把确定性逻辑（扫描、评分、配额、应用编辑）全部放在自己可控的层里，把创造性工作（理解代码、生成编辑）交给模型，再用 MCP 这种开放协议让用户选择"用你的 AI"还是"用我们的服务"。如果你想亲手验证，从npx transitions-agent跑一次扫描开始，再顺着 agent/README.md 里的完整文档往下走，你会发现这套动效修复流水线远比你想象的克制、可靠。

【免费下载链接】transitions.devUI montion AI agent, a library of 43+ crafted transitions, a skill that fits your workflow.项目地址: https://gitcode.com/gh_mirrors/tr/transitions.dev