snowflake

Snowflake — 静态页面转 EDS

将静态 HTML 页面转换为 EDS 页面，同时保留原始设计，并使内容可在 Document Authoring 中编辑。 支持两种转换级别：

• 页面级（覆盖层）——通过带有 [data-slot] 标记的模板，逐字节保留原始 DOM。一个模板、一个 CSS 文件，以及一个包含以槽位为键的行的 DA 文档。
• 区块级——每个内容区段都转换为独立的 EDS 区块，并拥有自己的 decorate() 函数和 CSS。内容在 DA 区块表格中编辑。页眉和页脚保留为静态片段。

两种级别都会完整保留原始视觉设计。页面级是更安全的默认选项；区块级会生成更标准的 EDS 输出，但要求源页面中的各个区段相互独立。

适用场景

用户有一个由 AI 生成、经过精心设计的静态 HTML 页面，希望在不丢失原始设计的前提下，将其部署到 Edge Delivery Services，并仍能在 DA 中编辑内容。典型表达：

• “将 https://example.com/static-page 转换为 EDS”
• “让此页面可在 DA 中编辑，但保留原始标记”
• “将此页面转换为 EDS 区块”（表示 level=block）
• “开始对 URL … 进行下一轮实验”
• “为 … 创建静态页面转 EDS 覆盖层”（表示 level=page）

此技能不适用于

不适用于规范的 EDS 区块重写迁移——这类任务应使用 page-import。Snowflake 会保留源设计；page-import 会将其重写为标准 EDS 区块模式，不以视觉保真为目标。支持三种资源策略（参见 knowledge/methodology.md §3）： absolute、vendor、da-media。

参数

参数	值	默认值	说明
level	page、auto、check、block	page	转换级别——见下文

level 的值

值	行为
auto	在第 2 阶段运行可行性分析，展示建议，并在进入第 3 阶段前请用户确认
check	仅运行可行性分析——在 decisions.json 中生成报告，并在第 3 阶段前停止。适用于批量扫描
block	区块级转换。分析仍会作为验证运行（结果写入 decisions.json），但不会阻止转换
page	页面级转换（标准覆盖层）。分析仍会作为验证运行，但不会阻止转换

如果用户未提供 level，并且其表达方式表明了意图， 则推断该值：

• “转换为 EDS 区块”、“区块级” → level=block
• “覆盖层”、“保留 DOM”、“snowflake 覆盖层” → level=page
• 中性表达 → level=page

使用示例

/snowflake https://example.com/promo              → page-level; infer repo, daRoot, slug
/snowflake https://example.com/promo level=block  → block-level, infer the rest
/snowflake https://example.com/promo level=auto   → feasibility analysis decides
/snowflake level=check                            → feasibility scan only (asks for URL)
/snowflake                                        → page-level, fully interactive

源 URL 是首个位置参数，也是唯一必填参数。其余内容都会自动解析，并在开始任何工作前汇总为一条确认信息。

技能依赖项

Snowflake 引用了 da-content 技能中的 DA HTML 规则和 DA 管理 API 契约。请与 Snowflake 一起加载 da-content。 第 3 阶段（生成）和第 5 阶段（往返验证）会直接引用该技能。

前提条件

必需项 — 技能无法自行获取的唯一输入：

1. 源 URL — 要转换的静态页面。必须可访问 （公开托管或本地开发服务器）。

自动获取 — 在初始化摘要中显示，以便在开始任何工作前一次性确认：

2. 目标 EDS 仓库 — 通过 gh repo view --json nameWithOwner 检测， 如果失败，则解析 git remote get-url origin。必须已接入 overlay 引擎（参见 knowledge/architecture.md §“解决方案结构”）。如果缺少，Phase 0 会安装它。
3. DA 根路径 — 如果 .snowflake/config.json 中设置了 daRoot 键， 则读取该值；否则默认为当前 git 分支名称（技能用于代码的同一分支）。显示在摘要中；可内联覆盖。
4. 转换级别 — 根据措辞推断（参见 Parameters），否则默认为 page。显示在摘要中；可内联覆盖。
5. Slug / 模板名称 — 根据源 URL 派生（kebab-case， ≤30 个字符）。显示在摘要中；可内联覆盖。

身份验证检查（非阻塞） — DA 令牌依次从 $DA_TOKEN → ~/.aem/da-token.json 获取。其状态会显示在初始化摘要中。Phase 1–4 无需此令牌；如果调用时令牌不存在，请在运行 Phase 5（往返）前调用 da-auth 技能。

初始化

每次调用时，Agent 都会在进入 Phase 0 之前执行以下步骤：

1. 解析输入 — 按照上方“前提条件”部分中的快速路径规则处理。

2. 探测基础环境 —

   node <SKILL_DIR>/scripts/install-substrate.mjs --dry-run
   

   记录探测结果（无操作 / 全新安装 / 偏差 / 检测到自定义代码）。

3. 检查 DA 令牌 —

   DA_TOKEN=$(node -e "
     const fs = require('fs');
     const p = process.env.HOME + '/.aem/da-token.json';
     try {
       const t = JSON.parse(fs.readFileSync(p, 'utf8'));
       if (t.expires_at > Date.now() + 60000) process.stdout.write(t.access_token);
     } catch {}
   ")
   

   非阻塞 — 仅记录状态以供摘要显示。

4. 在任何阶段开始前，始终显示运行参数。无条件显示此摘要， 即使所有值都已提前提供或明确推断，也要显示，然后立即继续， 无需等待确认：

   Source URL : https://example.com/promo   ← required (provided)
   Target repo: acme/my-site                ← detected from git
   DA root    : /main                        ← from current branch
   Level      : page                        ← default
   Slug       : promo                       ← derived from URL
   Substrate  : clean install — 9 files     ← (or: already current ✓)
   DA token   : cached ✓                    ← (or: not found — needed at Phase 5)
   

   对于常见情况（全新安装 — 尚无 snowflake 基础环境；被替换的文件会先备份）， 直接继续，无需暂停。仅在出现偏差时暂停（先前的 snowflake 基础环境已发生偏离），因为 覆盖可能会丢失有意保留的自定义内容 — Phase 0 会处理这种情况。

5. 继续 — 按顺序执行 Phase 0 → 1 → … → 6。

快速开始 — 端到端示例

在目标 EDS 仓库根目录中，以下是压缩版的完整七阶段转换流程。位于 phases/ 下的每个阶段文件都包含完整提示词；以下是 Agent 实际发出的命令形式。

# Inputs (resolved during init, confirmed in the summary)
SOURCE_URL="https://example.com/promo"
PAGE_SLUG="promo"
DA_ROOT="/main"                       # defaults to current branch name
NNN=001                           # next run number
PROJECT=".snowflake/projects/${NNN}-${PAGE_SLUG}"
TEMPLATE_NAME="promo"
LEVEL="page"                      # page | auto | check | block

# Phase 0 — install (or verify) the overlay substrate (once per repo)
node "<SKILL_DIR>/scripts/install-substrate.mjs"

# Phase 1 — capture: fetch source + assets into the project folder
mkdir -p "$PROJECT/input"
curl -fsS "$SOURCE_URL" -o "$PROJECT/input/index.html"
# For JS-rendered pages, use a browser to get the fully rendered HTML instead

# Phase 2 — analyze: produce decisions.json (sections, slots, asset
# strategy, head-links, conversionLevel). Includes block-level
# feasibility assessment. If LEVEL=check, stop here.
# Driven by phases/2-analyze.md.

# Phase 3 — generate: produce 5 artifacts + DA-source body
# (templates/<tpl>.html, fragments/<tpl>/{header,footer}.html,
# styles/<tpl>.css, scripts/<tpl>-animations.js, da/<slug>.html).
# Driven by phases/3-generate.md.

# Phase 4 — wire: copy artifacts to EDS-served paths and build the
# drafts file. Driven by phases/4-wire.md.

# Phase 5 — round-trip: local dev server + production preview
npx -y @adobe/aem-cli up --html-folder drafts &
TOKEN="${DA_TOKEN:-$(jq -r .access_token ~/.aem/da-token.json)}"
git checkout -b "snowflake-${NNN}" && git add . && git commit -m "snowflake #${NNN}"
git push -u origin "snowflake-${NNN}"
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -F "data=@${PROJECT}/output/da/${PAGE_SLUG}.html;type=text/html" \
  "https://admin.da.live/source/${OWNER}/${REPO}${DA_ROOT}/${PAGE_SLUG}.html"
curl -X POST -H "Authorization: Bearer $TOKEN" \
  "https://admin.hlx.page/preview/${OWNER}/${REPO}/snowflake-${NNN}${DA_ROOT}/${PAGE_SLUG}"
# Verify at https://snowflake-${NNN}--${REPO}--${OWNER}.aem.page/${DA_ROOT}/${PAGE_SLUG}

# Phase 6 — reflect: append findings to $PROJECT/learnings.md;
# promote cross-project rules to knowledge/learnings.md.

<SKILL_DIR> 是包含此 SKILL.md 的目录的绝对路径。Agent 会在调用前替换它 — 每个主机的路径解析规则请参见 HOST-NOTES.md。

七个阶段（依次执行）

每个阶段都是一个独立的 Markdown 文件，包含可执行的 Bash + Node。 Agent 读取阶段提示词，执行其中的步骤，更新项目根目录中的 state.json （<projectsDir>/<NNN>-<slug>/state.json），然后继续执行。重复运行是安全的——已完成的工作会被跳过。

0. 前置条件——安装/验证覆盖层底层，并为 .snowflake/config.json 写入标记。 每个仓库只运行一次。 请参阅 phases/0-prereq.md。

1. 捕获——获取源 HTML 和引用的外部资源； 创建项目文件夹。 请参阅 phases/1-capture.md。

2. 分析——结构映射：页眉/页脚边界、区块列表、插槽机会、需提取的 head 级链接、资源策略。 同时运行区块级可行性评估——请参阅 knowledge/block-level-feasibility.md。 包含页面复杂度关卡：超过 8 个区块或超过 100 个可插槽元素的页面会自动从页面级切换为区块级，以避免内容提取不完整（请参阅 phases/2-analyze.md）。 生成 notes.md + decisions.json（包括 conversionLevel）。 请参阅 phases/2-analyze.md。

3. 生成——根据第 2 阶段的 conversionLevel 采用不同流程：

   • page：生成 5 个覆盖层构件（模板 HTML、 页眉片段、页脚片段、页面 CSS、动画 JS）， 以及带有插槽键行的 DA 源正文。
   • block：生成各区块的 JS/CSS、页眉/页脚 片段、全局样式/令牌，以及带有标准区块表格的 DA 源正文。
   • hybrid：通过验证的区块采用区块级处理，未通过的区块采用页面级片段。 page 和 block 均受两种底层类型（eds 或 milo）支持。所有 Milo 专属差异——页面框架元数据、页面级/区块级生成、--pa-* 动画 sidecar 文件以及接线——均位于 assets/substrate-milo/FLAVOR.md； 阶段文档中包含指向该文件的条件链接。核心技能不依赖特定底层类型。请参阅 phases/3-generate.md。

4. 接线——将构件复制到 EDS 服务路径，构建本地测试草稿文件，运行 lint。 请参阅 phases/4-wire.md。

5. 往返验证——先在本地（开发服务器）运行，再在生产环境（分支 + 推送 + DA PUT + 预览 API）运行。两者都必须通过浏览器健康关卡：页面必须正常渲染（不能空白）、应用覆盖层、匹配源结构、没有控制台/网络错误，并且通过 1:1 DOM 相等性检查，运行才能继续。 请参阅 phases/5-roundtrip.md。

6. 回顾——追加本次运行的发现；将跨项目经验提升至 knowledge/learnings.md。不会 结束迭代——是否结束由用户决定。 请参阅 phases/6-reflect.md。

**每个阶段的知识解析顺序：**每个阶段先尝试读取 .snowflake/knowledge/<file>.md（项目专属覆盖）， 然后再读取 <SKILL_DIR>/knowledge/<file>.md（内置规范版本）。 发生冲突时，以项目覆盖版本为准。

阅读顺序

按需加载知识——仅在进入需要它的阶段时加载。

调用时（Phase 0 之前）：

1. 本文件。
2. knowledge/methodology.md — 规范的 阶段规则。
3. 确认可以加载 da-content 技能（Phase 3 和 Phase 5 需要）。

在 Phase 2（分析）时： 4. knowledge/block-level-feasibility.md — 块级与页面级转换的判断标准。

在 Phase 3（生成）时： 5. knowledge/architecture.md — 覆盖层 引擎和槽位写入器语义。 6. knowledge/block-level-conversion.md — 块级转换的架构和模式。 7. knowledge/learnings.md — 与生成相关的 跨项目发现。

在 Phase 5（往返验证）时： 8. knowledge/eds-da-mechanics.md — EDS 流水线覆盖层运行时知识。 9. knowledge/learnings.md — 关于媒体 处理、CORS、滚动动画问题的条目（若尚未加载）。

然后从 Phase 0 开始。

延伸阅读（Agent 不会加载）

• README.md — 面向读者的概览、安装命令、 贡献指南。
• HOST-NOTES.md — 各宿主适配器说明（Slicc、 Claude Code、通用 shell）、<SKILL_DIR> 路径解析规则、 .snowflake/ 目录约定，以及禁止跨宿主使用的原语（供维护者参考）。
• examples/README.md — 指向已结束迭代的 完整示例。