从URL到代码:ditto.site六阶段编译流水线架构深度解析
从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 结构、计算样式、布局盒模型、字体、图片、截图、交互状态和可安全观测的动效。
这种"证据优先"的路线带来一个核心承诺: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):
- 弹层清除——自动识别并关闭 Cookie/订阅/地区选择弹窗,确保截图的是页面本体;
- 动画沉降——等待入场/滚动动画静止,几何数据不再抖动;
- 动态媒体首帧——无 poster 的
<video>取一帧定格的画面,<canvas>动画栅格化成位图兜底; - 跨域 iframe 嫁接——页面内脚本看不进 iframe 的内容,用 graftFrameIntoSnapshot() 把可渲染的 iframe 子树"移植"进快照。
另外两个可选开关分别对应 Stage 4 交互捕获(hover/focus 状态,capture/interactions.ts)和 Stage 5 动效捕获(WAAPI 动画、轮播文本,capture/motion.ts),默认开启。
阶段二|归一化:多视口快照合成一棵渲染 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 模式目录),为阶段四注入运行时行为做准备。
阶段四|应用生成:一键产出可运行的工程
这是流水线的"发射口":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),未通过的站点也都有文档化的原因说明。
本地快速跑一次:从命令到可预览的克隆
本地运行只需三条命令(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 中"观察证据优先、确定性输出、不重放私有应用逻辑"三条原则,同一份捕获永远编译出同一个工程——这正是它作为开源编译流水线最值得借鉴的架构思路。



