从URL到代码:ditto.site六阶段编译流水线架构深度解析

原创2026-10-10 18:51:472,270 阅读

从URL到代码:ditto.site六阶段编译流水线架构深度解析

ditto.site 是一款开源的网页克隆编译器:输入一个公开 URL,它会捕获浏览器真实渲染出的页面,并把这份"冻结的捕获"确定性地编译成一个可运行的 Next.js 或 Vite React 项目。整个过程由一条六阶段编译流水线驱动:浏览器捕获 → 渲染 IR 归一化 → 确定性推断 → 应用生成 → 资源物化 → 验证门禁。它不是让 LLM 凭描述"写一个差不多的页面",而是同一份捕获输入,永远产出字节级一致的工程输出。

ditto.site 是什么:确定性的"捕获到代码"编译器

先用一句话理解它的定位:ditto.site = capture-to-code pipeline。官网文档里有一句关键声明(见 README.md):

"Cloning" here means generating a codebase from a live URL — not git clone.

也就是说,你不需要目标站点的源码,甚至不需要它有任何公开的仓库——编译器只看浏览器实际渲染出来的东西:DOM 结构、计算样式、布局盒模型、字体、图片、截图、交互状态和可安全观测的动效。

ditto.site网页克隆工具生成的克隆结果与源站点对比示例

这种"证据优先"的路线带来一个核心承诺:byte-stable。随机性、时间戳、网络状态都被排除在生成文件之外,同一份捕获重复编译,产物字节级相同。这也是它与传统"截图转代码"或"AI 生成页面"工具最大的区别。

六阶段编译流水线一张图看懂

主流程 runClone() 按下面这条链路执行,每个阶段对应 compiler/src/ 下一个独立目录:

URL
  -> 1. 浏览器捕获        (capture/)
  -> 2. 渲染 IR 归一化    (normalize/)
  -> 3. 确定性推断        (infer/)
  -> 4. 应用生成          (generate/)
  -> 5. 资源物化          (infer/assets.ts)
  -> 6. 验证门禁(可选)    (validate/)
阶段 职责 源码位置
1 捕获 多视口渲染、状态稳定化、素材收集 compiler/src/capture/
2 归一化 合并视口快照为统一 render IR compiler/src/normalize/ir.ts
3 推断 版块/令牌/资产图/配方识别 compiler/src/infer/
4 生成 发射 Next.js / Vite 工程 compiler/src/generate/pipeline.ts
5 物化 图片字体落地到 public 目录 compiler/src/infer/assets.ts
6 验证 gates 0–6 + 确定性门禁 compiler/src/validate/

💡 阶段 2–4 由纯函数 generateAll() 串起,它同时被 CLI 和确定性门禁调用——给定同一个 sourceDir,必须产出字节一致的输出。

阶段一|浏览器捕获:拿到页面真实的渲染状态

捕获的入口是 captureSite(),用 Playwright 驱动 Chromium,在 375 / 768 / 1280 / 1920 四个标准视口(REQUIRED_VIEWPORTS)逐一渲染。每个视口记录:

  • DOM 树、每个节点的计算样式与布局包围盒;
  • 图片、SVG、视频、字体、manifest 等资产清单;
  • robots、sitemap、llms.txt 等 SEO 资源;
  • 每个视口的整页截图(仅用于验证,不用于交付)。

真正"抓对状态"靠的是 Stage 2 的一组稳定化手段(capture/stabilize.ts、capture/graft.ts):

  1. 弹层清除——自动识别并关闭 Cookie/订阅/地区选择弹窗,确保截图的是页面本体;
  2. 动画沉降——等待入场/滚动动画静止,几何数据不再抖动;
  3. 动态媒体首帧——无 poster 的 <video> 取一帧定格的画面,<canvas> 动画栅格化成位图兜底;
  4. 跨域 iframe 嫁接——页面内脚本看不进 iframe 的内容,用 graftFrameIntoSnapshot() 把可渲染的 iframe 子树"移植"进快照。

另外两个可选开关分别对应 Stage 4 交互捕获(hover/focus 状态,capture/interactions.ts)和 Stage 5 动效捕获(WAAPI 动画、轮播文本,capture/motion.ts),默认开启。

ditto.site 网页克隆编译器处理视频页面的源站与克隆对比

阶段二|归一化:多视口快照合成一棵渲染 IR

每个视口的快照是独立的,buildIR() 会把它们合并成一棵以 1280 视口为基准的渲染 IR(Intermediary Representation)树:

  • 每个节点带稳定预序编号(n0、n1……),这是后续生成 CSS 和验证对齐的锚点;
  • 每个节点携带每个视口的计算样式、包围盒与可见性,响应式行为天然保留在数据里;
  • 只在特定宽度才出现的子节点按"仅在其来源区间可见"嫁接进来。

这棵树是版块推断、令牌提取、代码生成和验证共同的唯一事实来源——编译器后半程再也不看浏览器,只看这份 IR。

阶段三|确定性推断:版块、设计令牌与资产图

infer/ 目录里是一组互相独立的纯推断器,全部基于 IR 做确定性计算:

  • 版块检测:detectSections() 用递归下降把页面切成视觉上连贯的横向"版块"(<body>→<main> 这类大容器会被识别为 wrapper 继续下钻),完全不依赖 class 名——因为 class 被刻意从 IR 中丢弃了;
  • 设计令牌提取:extractTokens() 对计算样式建直方图,使用次数 ≥3 的色值/字号/间距/圆角才会被提升为稳定令牌,"explainable rather than clever";
  • 语义色板:infer/semanticTokens.ts 收集每个颜色的用法分布,生成 :root 变量,生成的 CSS 直接引用 var(--token);
  • 资产图与字体图:每个发现的资源 URL 都被映射到本地确定性路径,或记录跳过原因;
  • 配方识别:轮播、手风琴、菜单、marquee 等已知交互模式被识别为"配方"(配合冻结的 pattern-catalog.json 模式目录),为阶段四注入运行时行为做准备。

ditto.site 网站克隆编译器对复杂产品页的高保真重建示例

阶段四|应用生成:一键产出可运行的工程

这是流水线的"发射口":generateAll() 拿着 IR + 捕获结果 + 推断产物,一次性写出:

  • 框架文件:generate/app.ts 从 DOM 重建 JSX——包括规避 React hydration 错误的解析规则(如孤立表格标签降级为 <div>);默认 Next.js App Router,也可 --framework=vite;
  • 样式:generate/css.ts 按节点 cid 发射 CSS 或 Tailwind 工具类,颜色引用语义令牌;
  • 交互与动效:识别出的手风琴/菜单/轮播配方会绑定小型 ditto 运行时助手(src/app/ditto/),动效则以 @keyframes / WAAPI 形式回放;
  • 组件抽取(Stage 4.5):重复出现的子树被提升为独立组件模块;
  • 内容模型(Stage 6):generate/app.ts 把可编辑文案整理进 content.ts,语义化字段命名,方便后续改动;
  • SEO 与交接文档:metadata、JSON-LD、robots/sitemap/llms.txt 路由,外加自动生成的 AGENTS.md 与 ARCHITECTURE.md,告诉你哪些文件可以放心改。

生成目录里同时落盘 sections.json、tokens.json、recipes.json、manifest.json 等中间产物——验证阶段和"确定性回归"都靠它们复核。

阶段五|资源物化:让克隆工程完全自包含

materializeAssets() 把捕获到的图片、SVG、视频、字体、Lottie 等文件复制进生成应用的 public/assets/cloned/ 下,按类型分目录(images / svg / video / fonts / lottie / manifest)。设计目标是 Gate 2 的三条硬约束:每个引用都必须被分类、不允许 404、不允许指向源站的远程地址(除非显式允许)。配合字体图(infer/fonts.ts)里对 @font-face 的本地化解析,克隆出来的工程是零外部依赖的静态资源包。

阶段六|验证门禁:用 gates 0–6 量化保真度

validate/ 把生成出的应用真正 build + 起服务 + 重新渲染,再与源站逐层比对。仓库使用小而可重复的门禁,而不是一个笼统的视觉分数:

门禁 校验内容
Gate 0 build 生成的应用能通过构建
Gate 1 capture 捕获本身有效(非空、未截断)
Gate 2 asset/font 资源引用全部本地化、无 404
Gate 3 DOM DOM 结构一致
Gate 4 style 逐节点计算样式一致(颜色容忍 ±2 通道误差,见 gates.ts)
Gate 5 layout 布局盒与响应式探针宽度下的位置一致
Gate 6 determinism 同一捕获重新生成,关键文件 字节级一致

此外还有 pollution 门禁(拒绝被反爬墙/弹窗污染的退化捕获,gatePollution())与 perceptual 门禁(截图像素 diff)。examples/ 里公开的基准结果可以直观感受这套门禁的严格程度:easy 档 24/24 通过(均分 99.7)、hard 档 23/32 通过(均分 98.8),未通过的站点也都有文档化的原因说明。

ditto.site 网页克隆编译器在 hard 难度站点上的克隆结果示例

本地快速跑一次:从命令到可预览的克隆

本地运行只需三条命令(Chromium 用于捕获与验证):

git clone https://gitcode.com/gh_mirrors/di/ditto.site
cd ditto.site && npm ci && npx playwright install chromium
npm run clone -- https://example.com/ --serve

--serve 会顺手 npm install && npm run dev 并打开浏览器;常用变体:--mode=multi(整站)、--styling=css(语义 CSS 而非 Tailwind)、--framework=vite。产物落在 runs/<site>/latest/(稳定的符号链接路径),详见 compiler/README.md。

仓库导航:一分钟定位六阶段源码

想读什么 去哪里
六阶段总览与 API 用法 README.md
捕获:视口、稳定化、iframe 嫁接 compiler/src/capture/capture.ts、graft.ts
渲染 IR 定义 compiler/src/normalize/ir.ts
版块 / 令牌 / 资产图推断 infer/sections.ts、infer/tokens.ts、infer/assets.ts
生成总管线 compiler/src/generate/pipeline.ts
验证门禁实现 compiler/src/validate/gates.ts
开发方法与评估原则 docs/METHODOLOGY.md
基准结果与视觉证据 examples/README.md

小结

ditto.site 把"网页克隆"从玄学变成了工程问题:先冻结证据(捕获),再确定性编译(IR → 推断 → 生成 → 物化),最后用量化的门禁(gates 0–6)验收。六阶段各司其职、目录边界清晰,配合 docs/METHODOLOGY.md 中"观察证据优先、确定性输出、不重放私有应用逻辑"三条原则,同一份捕获永远编译出同一个工程——这正是它作为开源编译流水线最值得借鉴的架构思路。

登录后查看全文
ditto.site