webEmbedding

webEmbedding

webEmbedding 是一款以源码为先的网站克隆引擎，面向 AI 编码 Agent：它使用 Playwright 捕获在线页面，从 HAR 工件中重放网络证据，仅在无法直接复用时才重建，并自行验证结果。

它以技能 + MCP 服务的形式提供。它不会让模型根据截图“克隆这个网站”，而是检查 URL、选择复用或重建路径、捕获 DOM/运行时 HTML/样式/资源/网络跟踪，生成范围受限的前端重建工件，并通过视觉、DOM、计算样式、交互和响应式断点验证来检查输出。

GitHub 列表页、社交预览和发布文案建议见 docs/github-listing.md。

当前状态

当前流程最适合静态和半静态网页：

• 公司、品牌、营销和文档页面
• 公开落地页
• 需要基于捕获内容重建的 iframe 屏蔽页面
• 涵盖桌面端、平板端和移动端的响应式页面快照

它并非完整的后端或应用逻辑克隆引擎。仅限登录的界面、以应用为先或需要原生应用的服务、验证码密集型网站、地图、游戏、重度依赖 Canvas/WebGL 的页面、实时信息流、支付和预订流程，以及私有服务器行为仍需单独处理。

在运维层面，该仓库现已成为面向 URL 捕获和范围受限重建的候选生产级克隆引擎：任务可以排队，网络证据可以通过 HAR 工件进行重放审计，可使用用户自有的浏览器状态驱动经过身份验证的仪表板运行，本地检查则会验证路由语料库、评分检查、软件包内容和 CI 配置。剩余的主要边界在于服务器端产品行为，而非前端证据的捕获与重建。

测得的检查点

该仓库近期的本地基准测试：

URL	路径	得分
https://developer.mozilla.org/en-US/	iframe 屏蔽页面的范围受限重建	根页面 94，视觉 95，移动端 94，平板端 94，断点平均值 94
https://www.mozilla.org/	范围受限重建	根页面 94，视觉 100
https://www.python.org	难度更高的范围受限重建样本	根页面 90，视觉 100
https://www.example.com	精确复用	就绪 yes

这些结果由本地自验证流程生成，并非人工指定的评分。 可复现的命令和评分阈值记录在 docs/benchmark-evidence.json 中。 生产就绪检查门槛记录在 docs/production-pipeline-gates.json 中。

核心功能

• 源优先路由：
  • 在安全且支持嵌入框架时，直接复用 iframe 或嵌入内容
  • 有原始预览、导出、混编或源代码路由时，优先使用这些路由
  • 仅在无法精确复用时进行有限重建
• 实时浏览器捕获：
  • DOM 快照
  • 运行时 HTML
  • 全页截图
  • 计算样式摘要
  • CSS 分析
  • 资源清单
  • 类似 HAR 的网络元数据
  • 交互状态和回放轨迹
  • 导出存储状态，以支持需要会话的流程
• 被阻止网站的重建：
  • 遇到 X-Frame-Options 和 CSP 阻止的页面时，根据捕获的证据进行重建
  • 根据捕获的页面结构生成可复用的前端重建产物
  • 在捕获到的情况下，保留自定义标签、shadow root 宿主结构和语义化文档结构
• 证据局限报告：
  • 在复现结果和提示词中，将直接捕获的产物与推断出的或缺失的证据区分开
  • 将应用门控、身份验证门控和原生应用主导的界面标记为有限证据，并建议用户提供截图或捕获已验证身份的会话
• 运行故障分类：
  • 报告带类型的管道操作代码，例如 network-replay-limited、auth-session-missing、public-app-gate 和 canvas-visual-fallback
  • 在将捕获的网络证据视为可用于回放之前，公开 HAR/网络的 replay_readiness
• 生产管道辅助工具：
  • 基于文件系统的异步克隆任务队列，支持持久化 JSON 记录、工作进程锁、重试调度、取消和清单注释
  • 确定性 HAR 回放引擎，支持标准 HAR、近似 HAR 以及捕获的 network/manifest.json 产物
  • 已验证身份的仪表板实时语料库运行器，可接受用户提供的 storage_state_path 或仓库外的 user_data_dir
• 自我验证：
  • 截图相似度
  • DOM 快照相似度
  • 计算样式相似度
  • 悬停／聚焦／点击交互状态一致性
  • 交互轨迹一致性
  • 桌面／移动／平板断点报告
• 响应式基准测试支持：
  • 主要桌面视口：1440x1200
  • 平板配置：768x1024
  • 移动设备配置：390x844
• 修复循环：
  • 如果首个脚手架未达到就绪阈值，可进行有限的自我修复

安装

环境要求

• Node.js 18 或更高版本
• Python 3.9 或更高版本
• 本地需提供 Chrome 或 Chromium，以供 Playwright 运行时捕获使用

此软件包使用 playwright-core；它不会自行下载浏览器。

安装此项目会添加 source-first-clone 插件包、exact-clone-intake 技能，以及用于提供 URL 检查、捕获、重建和验证工具的 MCP 服务。

从 npm 安装

npm install -g web-embedding
web-embedding install
web-embedding doctor

安装后克隆公开 URL：

web-embedding clone \
  --url https://developer.mozilla.org/en-US/ \
  --output-dir ./.tmp/mdn-clone \
  --wait-seconds 2 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

如果你已安装较旧版本的本地插件，可使用以下命令覆盖：

web-embedding install --force
web-embedding doctor

也可以不进行全局安装，直接运行安装程序：

npx web-embedding install

作为 MCP 服务使用

对于能够启动 npm stdio 服务的 MCP 客户端：

{
  "mcpServers": {
    "source-first-clone": {
      "command": "npx",
      "args": ["-y", "web-embedding@latest", "mcp"]
    }
  }
}

用于本地冒烟测试：

npx web-embedding@latest mcp

MCP Registry 标识为 io.github.jongko54/web-embedding；server.json 和 package.json#mcpName 保持同步，以验证 Registry 所有权。

托管应用 SDK 接入端点

Apps SDK Developer Mode 使用的公开远程 MCP 接入端点为：

https://webembedding-jongkos-mcp.vercel.app/mcp

它提供低风险的源优先路由工具，例如 URL 检查、嵌入候选项发现、克隆模式分类和嵌入代码片段生成。完整的浏览器捕获、HAR 回放、队列、有限重建和单次克隆执行仍通过 stdio MCP 软件包在本地优先运行。

Apps SDK 审核页面与端点托管在一起： https://webembedding-jongkos-mcp.vercel.app/privacy.html、 https://webembedding-jongkos-mcp.vercel.app/terms.html 和 https://webembedding-jongkos-mcp.vercel.app/submission.html。

沙盒与审批

webEmbedding 有两个不同的执行边界：

• Hosted Apps SDK 接入：仅进行只读 URL 路由和分类。它接受绝对 http 和 https URL，不运行 Playwright、不读取本地文件、不使用浏览器配置文件或存储状态，也不持久化捕获产物。
• 本地 stdio MCP 和 CLI：完整的捕获、HAR 重放、队列、重建脚手架和自验证都在用户的机器上运行，并遵循用户本地 Agent 和文件系统权限。输出仅写入调用方提供的路径，例如 output_dir 或 queue_root。
• 身份验证后的捕获：需要会话的运行要求调用方有意提供 storage_state_path 或 user_data_dir。webEmbedding 不收集凭据、不绕过登录，也不将公开的登录页面视为私有应用证据。
• 受访问控制的界面：付费墙、验证码流程、私有仪表板、支付／结账／账户／管理流程以及由原生应用主导的页面应被拦截、标记为 needs_session 或转交人工审核，除非用户拥有明确授权并提供所需证据。

本地 URL 入口会拒绝 file:// 等非 HTTP 协议，防止 Agent 将克隆／捕获工具用作本地文件读取器。遥测默认禁用；启用时，不会包含目标 URL、本地路径、捕获的 HTML、屏幕截图、存储状态、环境变量、API 密钥或命令输出。

Agent 市场

此仓库包含两个本地 Agent 界面的市场元数据：

• Codex：.agents/plugins/marketplace.json 指向 ./bundle/source-first-clone。
• Claude Code：.claude-plugin/marketplace.json 指向同一 bundle，且该 bundle 包含 .claude-plugin/plugin.json。

Claude Code 用户可以通过 GitHub 添加市场：

/plugin marketplace add jongko54/webEmbedding
/plugin install source-first-clone@webembedding

AI 自动选择预期和黄金提示词位于 docs/ai-distribution.md 和 evals/ai-selection/webembedding-golden-prompts.json 中。

从发行版安装

curl -fsSL https://github.com/jongko54/webEmbedding/releases/latest/download/install.sh | bash

从此检出版本安装

git clone https://github.com/jongko54/webEmbedding.git
cd webEmbedding
npm install
node ./bin/web-embedding.mjs install
node ./bin/web-embedding.mjs doctor

安装到临时主目录

适用于测试，且不会改动你实际使用的 Agent 主目录：

python3 python/web_embedding/installer.py install --target-home ./.tmp/home
python3 python/web_embedding/installer.py doctor --target-home ./.tmp/home
python3 python/web_embedding/installer.py uninstall --target-home ./.tmp/home

自愿启用的遥测

遥测默认禁用。在交互式首次安装时，web-embedding install 会询问一次，默认选项为 No。CI 和 curl | bash 等非交互式安装不会显示提示。如果选择启用，web-embedding 会向你控制的 JSON POST 端点发送少量匿名命令完成事件。它不会发送目标 URL、本地路径、捕获的 HTML、屏幕截图、存储状态、环境变量、API 密钥或命令输出。

安装时启用：

web-embedding install --telemetry --telemetry-endpoint https://your-collector.example/events

或稍后进行管理：

web-embedding telemetry enable --endpoint https://your-collector.example/events
web-embedding telemetry status
web-embedding telemetry disable
web-embedding telemetry reset-id

每个事件包含匿名安装 ID、软件包版本、命令名称、成功／失败状态、操作系统／运行时基本信息，以及 breakpoint_count 或 install_source 等粗略选项标志。

环境控制项：

WEB_EMBEDDING_TELEMETRY=1
WEB_EMBEDDING_NO_TELEMETRY=1
WEB_EMBEDDING_TELEMETRY_PROMPT=0
WEB_EMBEDDING_TELEMETRY_ENDPOINT=https://your-collector.example/events
WEB_EMBEDDING_TELEMETRY_LOG=./telemetry.jsonl

运行本地／可自托管的 JSONL 收集器：

npm run telemetry:collector -- --host 127.0.0.1 --port 8765 --out ./telemetry.jsonl
WEB_EMBEDDING_TELEMETRY=1 \
WEB_EMBEDDING_TELEMETRY_ENDPOINT=http://127.0.0.1:8765/events \
web-embedding doctor

汇总收集到的使用数据：

npm run telemetry:summarize -- ./telemetry.jsonl

摘要包含安装和克隆执行次数、命令总执行次数、匿名安装 ID 数量、命令计数和版本计数。有关收集器和分析器的详情，请参阅 docs/telemetry.md。

快速开始

检查 URL 并获取路由提示：

node ./bin/web-embedding.mjs inspect \
  --url https://developer.mozilla.org/en-US/

在捕获或克隆前运行安全预检审计：

node ./bin/web-embedding.mjs audit \
  --url https://developer.mozilla.org/en-US/

审计会报告此参考是否已准备好进行精确／嵌入复用、是否需要本地捕获、是否需要经过身份验证的会话、是否需要人工审核，或者是否应在运行任何浏览器捕获或文件系统输出之前予以拦截。

运行完整的克隆工作流：

node ./bin/web-embedding.mjs clone \
  --url https://developer.mozilla.org/en-US/ \
  --output-dir ./.tmp/mdn-clone \
  --wait-seconds 2 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

运行轻量级质量基准测试：

python3 scripts/check_clone_quality_bench.py \
  https://developer.mozilla.org/en-US/ \
  --output-root ./.tmp/clone-quality-bench \
  --wait-seconds 1 \
  --timeout-seconds 35 \
  --breakpoints mobile tablet

基准测试会打印根页面、视觉效果和断点分数的精简行。完整产物会写入输出目录。

CLI 命令

node ./bin/web-embedding.mjs capabilities
node ./bin/web-embedding.mjs install
node ./bin/web-embedding.mjs doctor
node ./bin/web-embedding.mjs uninstall
node ./bin/web-embedding.mjs paths
node ./bin/web-embedding.mjs telemetry status

node ./bin/web-embedding.mjs inspect --url https://www.mozilla.org/

node ./bin/web-embedding.mjs audit --url https://www.mozilla.org/

node ./bin/web-embedding.mjs capture \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/capture-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs reproduce \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/reproduce-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs clone \
  --url https://www.mozilla.org/ \
  --output-dir ./.tmp/clone-mozilla \
  --breakpoints mobile tablet

node ./bin/web-embedding.mjs verify \
  --reference-bundle ./.tmp/reference/capture.json \
  --candidate-bundle ./.tmp/candidate/capture.json

输出产物

一次克隆运行可以生成：

• capture.json
• pipeline-run-manifest.json
• dom/snapshot.json
• dom/runtime.html
• styles/computed-summary.json
• styles/css-analysis.json
• network/manifest.json
• network/har.json
• network/har-like.json
• network/replay-report.json
• assets/inventory.json
• interactions/states.json
• interactions/trace.json
• screenshots/runtime.png
• session/storage-state.json
• reproduction/plan.json
• reproduction/evidence-limitations.json
• reproduction/rebuild-prompt.txt
• reproduction/rebuild/starter.html
• reproduction/rebuild/starter.css
• reproduction/rebuild/starter.tsx
• reproduction/rebuild/next-app/
• reproduction/self-verify/summary.json
• reproduction/self-verify/renderers/*/verification.json
• reproduction/self-verify/renderers/*/visual-qa.json
• reproduction/self-verify/renderers/*/breakpoints/*-verification.json

质量基准测试

运行默认的小型基准测试：

npm run check:clone-bench:local

运行通用路由回归语料库和预期检查门：

npm run check:benchmark-routes:local

运行轻量级克隆评分检查门：

npm run check:clone-score-gate:local

验证已提交的基准测试证据清单：

npm run check:benchmark-evidence:local

验证生产流水线检查门：

npm run check:production-readiness:local

分别运行各项运维冒烟测试：

npm run check:job-queue:local
npm run check:har-replay:local
npm run check:authenticated-corpus:local

根据路由报告对失败/操作代码进行分类：

npm run classify:pipeline-failures -- --report ./.tmp/universal-route-benchmark/universal-route-report.json

查找持久化的低分基准测试产物：

npm run summarize:benchmark-scores -- --root ./.tmp --min-score 60 --max-score 70

运行指定 URL：

python3 scripts/check_clone_quality_bench.py \
  https://www.example.com \
  https://www.mozilla.org/ \
  --no-breakpoints

运行响应式基准测试：

python3 scripts/check_clone_quality_bench.py \
  https://developer.mozilla.org/en-US/ \
  --breakpoints mobile tablet

开发检查

python3 -m py_compile \
  bundle/source-first-clone/mcp/source_first_clone/*.py \
  scripts/check_integration_smoke.py \
  scripts/check_clone_quality_bench.py

npm run check:integration:local

git diff --check

仓库布局

• bundle/source-first-clone 已安装的插件包、MCP 服务和精确克隆接收技能。
• bundle/source-first-clone/mcp/source_first_clone 捕获、规划、重建、修复和验证引擎。
• bin/web-embedding.mjs Node 命令行包装器。
• python/web_embedding/installer.py 共享安装程序和命令分发器。
• scripts/check_clone_quality_bench.py URL 克隆质量基准测试辅助工具。
• scripts/benchmark_routes.py 通用路由/捕获深度回归基准测试辅助工具。
• scripts/check_benchmark_report.py 用于精确、最低值和包含式检查的基准测试预期验证器。
• scripts/check_benchmark_evidence.py 基准测试证据清单验证器。
• scripts/check_job_queue_smoke.py 文件系统异步克隆作业队列冒烟测试。
• scripts/check_har_replay_smoke.py 确定性 HAR 重放引擎冒烟测试。
• scripts/benchmark_authenticated_corpus.py 用户提供的已认证仪表盘语料库运行器。
• scripts/summarize_benchmark_scores.py 用于查找输出根目录下低分或高分持久化基准测试产物的工具。
• scripts/classify_pipeline_failures.py 用于报告和捕获产物的运维失败/操作分类汇总工具。
• scripts/check_production_readiness.py 用于验证语料库、失败分类、CI 接线和策略文档的生产就绪检查门。
• scripts/check_integration_smoke.py 发布、安装和仅使用 URL 的克隆冒烟测试。
• scripts/release_bundle.py 发布产物构建器。
• docs/ 架构说明和通用基准测试文档。

定位

对本项目最有力的描述是：

一种以源代码为先的网站克隆引擎，结合 Playwright 捕获、HAR 重放、MCP 工具和自验证功能，重建受 iframe 阻挡的公开页面，并提供可复现的视觉、DOM、样式、交互和响应式评分。

请勿将输出视为绕过法律或所有权限制的手段。该引擎可以重建公开页面结构，但权限、许可和可接受的使用方式仍然重要。

许可证

MIT