Ardot HTML Prototype Converter

中文 | English

一个将 Axure/HTML 原型导出物转换为可编辑、可验证 Ardot 原型的 Codex Skill。它同时支持 PC 后台页面和移动端多状态长页，包含浏览器取证、结构化重建、组件复用与 Manifest 验证流程。

适用场景

将 Axure 或类似工具导出的 HTML 原型转换为 Ardot 可编辑页面。
审查或修复散节点、空壳页面、组件误用、表格结构错误或移动端裁切问题。
为 PC 系统建立一致的 PageFrame/sidepanel/table column 结构，并在同一 page 平铺真实弹窗状态。
为移动端按真实交互状态取证，在同一 Ardot page 中平铺完整 Screen，并保留连续长页。

核心能力

先通过 Playwright 或等价浏览器流程渲染源原型，再从 element JSON 和截图重建。
先判断平台：PC 普通页使用单 PageFrame，弹窗页允许多个完整 PageFrame/<状态> 横向平铺；移动端允许多个 Screen/<状态> 横向平铺。
移动端按状态等价类取证，过滤隐藏祖先节点，支持初始状态、并排状态稿和交互状态，避免默认枚举低价值状态组合。
移动端 Screen 固定项目视口宽度、内容撑高，不滚动、不裁切；超长页面按 Section 截图验证。
源证据和项目约定优先于通用默认值；页面使用 auto layout，并只为本批实际业务角色建立最小本地组件映射。
根节点的本地 AnnotationLayer 批注实例可原样保留，并从业务结构与语义校验中排除。
已知存在跨页节点失效时使用严格单页事务；跨页引用稳定时允许受控小批次，但不批量遗留空 page。
保留逐状态原始截图，并用缩略视觉对照图一次检查多个源图/结果图；只有异常项再展开原图。
Manifest v2 只有在结构、语义和视觉三层验证通过后才允许标记 completed。

详细平台规则位于 references/page-specs/；SKILL.md 只负责平台路由和硬规则。

目录结构

ardot-html-prototype-converter/
├── .github/workflows/public-repo-audit.yml
├── .gitignore
├── SKILL.md
├── agents/openai.yaml
├── assets/
│   ├── audit-policy.template.json
│   ├── mobile-states.template.json
│   └── mobile-manifest-v2.template.json
├── references/
│   ├── workflow.md
│   ├── execution-checklist.md
│   ├── failure-modes.md
│   └── page-specs/
│       ├── common.md
│       ├── pc-list-page.md
│       ├── pc-form-page.md
│       ├── pc-detail-page.md
│       ├── pc-report-page.md
│       ├── pc-dialog.md
│       └── mobile.md
├── scripts/
│   ├── audit_public_repo.js
│   ├── build_visual_review_sheet.js
│   ├── build_visual_review_sheet.test.js
│   ├── probe_mobile_regions.js
│   ├── render_mobile_states.js
│   ├── summarize_mobile_states.js
│   └── validate_mobile_manifest.js
└── LICENSE

使用方式

将本仓库放入 Codex skills 目录，然后调用：

使用 $ardot-html-prototype-converter 将 PC 或移动端 Axure/HTML 原型转换为可编辑、可验证的 Ardot 原型。

Agent 会先读取 SKILL.md，再按平台和页面类型加载必要的 workflow 与规范；检查清单只用于审查/交接，失败模式只在出现异常时加载。移动端可先用 probe_mobile_regions.js 区分业务区域与批注占宽，再从 assets/ 模板建立状态配置与 Manifest；通用脚本通过 CLI 参数接收项目路径，不包含项目专属页面 ID 或业务字段。

视觉对照图

每个状态仍保留原始源截图和 Ardot 截图。需要批量检查时，在项目目录运行：

node <skill>/scripts/build_visual_review_sheet.js \
  --project-root . \
  --manifest out/ardot_manifest_<system>.json \
  --output-root out/visual-review

脚本兼容 Mobile manifest v2、PC 状态记录和普通 PC 页面级截图，也可用 --pairs-file 传入中立的 sourceImages / targetImages 列表。默认使用当前运行环境中的 Playwright 生成 HTML 与 PNG；未安装 Playwright 时会明确失败，可显式使用 --html-only。所有输入图片和输出目录都必须位于 --project-root 内。

{"schemaVersion": 1, "items": [{"id": "page/state", "label": "Default", "sourceImages": ["source.png"], "targetImages": ["result.png"]}]}

本地项目隔离

公开 Skill 仓库只保存通用规则、脚本和占位模板。真实 Axure HTML、业务字段、项目 ID、截图和转换证据默认保存在仓库外：

<local-project-root>/
  Axure HTML 导出物
  scripts/mobile_states.json
  out/pages_manifest.json
  out/elements/<pageId>/<state>.json
  out/screenshots/<pageId>/<state>.png
  out/visual-review/
  out/ardot_manifest_<system>.json

所有转换脚本通过 --project-root <local-project-root> 访问该目录。临时项目也可以放入本仓库的 .local/projects/<project-key>/，但 .local/ 已被 Git 整体忽略。

将 assets/audit-policy.template.json 复制为 .local/audit-policy.json，在 blockedTerms、blockedRegexes 和 blockedPaths 中登记只属于本地项目的敏感内容。发布前运行：

node scripts/audit_public_repo.js --repo-root .

审计器不会在输出中显示匹配到的敏感文本。GitHub Actions 会对公开分支和 Pull Request 执行不含本地词表的通用审计。

许可

本项目使用 MIT License。

English

A Codex Skill for converting Axure/HTML exports into editable, verifiable Ardot prototypes. It supports both PC admin pages and multi-state, content-driven mobile screens, including browser evidence capture, structured reconstruction, component reuse, and Manifest validation.

Use Cases

Convert Axure or similar HTML prototype exports into editable Ardot pages.
Review or repair scattered nodes, empty shells, component misuse, incorrect tables, and clipped mobile screens.
Apply the PC PageFrame + sidepanel + Content structure, table-column composition, and same-page dialog-state layout.
Capture real mobile states, lay complete screens side by side, and preserve continuous long pages.

Core Capabilities

Render source HTML in a browser before rebuilding from element JSON and screenshots.
Route by platform: ordinary PC pages use one PageFrame, while dialog pages may lay out complete PageFrame/<state> frames side by side; multiple Screen/<state> frames may coexist on a mobile Ardot page.
Capture representative mobile state classes, exclude hidden-ancestor nodes, and support initial, source-region, and interaction recipes without defaulting to low-value state combinations.
Keep mobile screens at the project viewport width with content-driven height, no scroll container, and no clipping; use Section screenshots for long-page evidence.
Prefer source evidence and project conventions over generic defaults; use auto layout and create only the local component-role mappings needed by the current batch.
Preserve root-level local AnnotationLayer instances while excluding them from business structure and semantic validation.
Use strict per-page transactions when cross-page node resolution is unstable; otherwise allow controlled small batches without leaving empty pages behind.
Keep original state screenshots while reviewing multiple source/result pairs through compact visual review sheets; open full-resolution images only for anomalies.
Mark Manifest v2 pages completed only after structure, semantics, and visuals all pass.

Detailed rules live in references/page-specs/; SKILL.md contains routing and hard requirements only.

Usage

Place this repository in a Codex skills directory, then invoke:

Use $ardot-html-prototype-converter to convert a PC or mobile Axure/HTML prototype into an editable, verifiable Ardot prototype.

The mobile templates and parameterized scripts contain no project-specific page IDs or business fields.

Visual review sheets

Keep the original source and Ardot screenshots for every state, then generate compact comparison sheets from the project directory:

node <skill>/scripts/build_visual_review_sheet.js \
  --project-root . \
  --manifest out/ardot_manifest_<system>.json \
  --output-root out/visual-review

The script supports Mobile manifest v2, PC state records, ordinary PC page-level screenshots, and an explicit --pairs-file format with sourceImages and targetImages. It uses Playwright from the executing environment to produce HTML and PNG output, fails clearly when Playwright is unavailable, and supports an explicit --html-only mode. Inputs and outputs must remain inside --project-root.

{"schemaVersion": 1, "items": [{"id": "page/state", "label": "Default", "sourceImages": ["source.png"], "targetImages": ["result.png"]}]}

Local Project Isolation

Keep real Axure exports, business data, project IDs, screenshots, and evidence outside this public repository. Pass that directory through --project-root <local-project-root>. For temporary local work, .local/projects/<project-key>/ is available and ignored by Git.

Copy assets/audit-policy.template.json to .local/audit-policy.json to register project-only terms, regular expressions, and paths. Before publication, run:

node scripts/audit_public_repo.js --repo-root .

The audit reports rule IDs and locations without echoing matched sensitive values. GitHub Actions runs the generic tracked-file audit on pushes and pull requests.

License

Released under the MIT License.

Ardot HTML Prototype Converter

README

Ardot HTML Prototype Converter

适用场景

核心能力

目录结构

使用方式

视觉对照图

本地项目隔离

许可

English

Use Cases

Core Capabilities

Usage

Visual review sheets

Local Project Isolation

License

Comments (0)