source-html-to-app-ui

将源 HTML 转换为应用 UI

目标

将已批准的源 HTML 还原为真实的目标应用。最终体验是衡量成功与否的首要标准：

• 覆盖每个源页面、有意义的状态、可见部分和交互类型；
• 只要有依据，目标应用就应保留源内容、层级、布局、样式、控件和行为；
• 桌面、移动设备、短屏、主题、抽屉和溢出行为均保持可用；
• 成对的 Playwright 证据应展示源页面和目标页面在匹配的路由、状态、主题、视口和页面部分下的情况；
• 最终审查应在运行确切的任务完成命令之前，发现并修复缺失的质量工作。

使用源 HTML 进行探索和比较。将目标编写为常规应用，包含真实路由、组件、样式、资源和本地 UI 状态。任务仅限 UI：不要添加后端、API、数据库、持久化、身份验证、服务端或业务逻辑。

严格执行约定

<execution_contract>

这是端到端实现工作流，而非可选建议。通过一个阶段后才能进入下一阶段，但这不代表任务已成功完成。不要在源探索、阶段 0、目标研究、实现或部分验证运行后停止。如果下一阶段已具备条件，请自动继续。只有阶段 4 通过，且确切的任务完成命令成功运行后，任务才算完成。

每个关卡均由 Agent 负责。浏览器脚本负责收集证据；Agent 审查证据、评估阶段、修复失败项并推进标记。常规数据包失败时应进入修复循环：检查由辅助工具报告的失败，修复同一个数据包，通过生命周期辅助工具重新运行，并刷新已失效的证据。违反流程或未能证明关卡通过都意味着运行失败，不能据此继续或签字确认。

在上下文压缩、恢复、重试、重新连接或开启新会话后，开始任何工作前，重新阅读此技能文档、当前阶段参考资料、当前产物、progress.md、open-gaps.md，以及下一步操作所需的任务专属证据。绝不能依赖对话记忆或旧的 Pass 标签来决定下一步操作。

</execution_contract>

首步锁定

<first_action_lock>

任务的第一个回合仅限处理源内容。在下方的源检查点解锁之前，不要检查目标代码仓库来熟悉项目、确认路由、查找 Logo、检查构建情况或选择资源。任务消息中提供的目标路径只是输入边界，并不代表获准读取该路径。不得对目标根目录运行 ls、find、tree、rg --files、git status 或等效命令；即使只是列出目标目录名称，也属于检查目标内容，解锁前均禁止。熟悉环境之前，唯一允许读取的技能文件是此 SKILL.md 和下文明确指定的阶段 0／生命周期参考路径；绝不能为发现文件而列出、glob 匹配、搜索或检查技能根目录、references/ 或 assets/ 目录。

严格按照以下顺序执行：

1. 阅读此技能，以及当前标记所需的 Phase 0 和生命周期参考资料，并使用参考映射中的准确路径。在完成方向确认之前，不得列出、glob、搜索或读取 .agents/skills/source-html-to-app-ui/ 下的任何其他路径，包括 references/、assets/templates/ 和 assets/scripts/。稍后复制时，只能使用此技能中明确列出的资产路径；不得枚举技能包来查找这些路径。到此为止，模板和辅助工具只能用于复制，辅助工具的命令约定已具有权威性。
2. 新建 task-workflow/，并将 CURRENT_PHASE.txt 设置为 phase-0-source-contract。
3. 将获准的源 HTML 和设计输入逐字节复制到 task-workflow/。你可以为完成设置而读取设计输入，但此时不得打开或读取复制后的源 HTML、内联 CSS 或 JavaScript。
4. 通过生命周期辅助工具，在桌面和移动端进行首次源方向确认，并将准确的已服务 HTML URL 传递给数据包（例如 --env SOURCE_URL=http://127.0.0.1:5192/approved-mock.html）。方向确认数据包应恰好生成一张桌面图片和一张移动图片。辅助工具成功运行后，接下来的两次工具调用必须依次为：读取桌面方向确认图片，然后读取移动端方向确认图片。为每张图片记录一条具体发现。在这两次图片读取之间，以及读取这两张图片之前，不得读取源文件或设计文件、写入数据包、搜索、执行 Shell 命令或进行其他工具调用。如果有任一图片尚未读取，就说明尚未开始检查源文件；此时读取源文件或设计内容将导致 Phase 0 自动失败。必须断言响应成功、最终响应 URL 与 SOURCE_URL 完全一致，且文档内容非空。如果任务元数据提供了预期标题或身份信息，则必须进行断言；否则记录标题，并在完整读取 HTML 后进行核对。辅助工具就绪或标题非空都不足以构成通过。
5. 从头到尾完整读取获准的 HTML、内联 CSS 和 JavaScript，直至 EOF。
6. 通过生命周期辅助工具创建并运行完整的源清单。然后逐张检查清单中的图片：完整读取清单，打开所有引用的完整视图、分区、状态、桌面端和移动端图片，并为每张图片记录一条具体发现。持续检查，直至已打开图片数量与清单中的图片数量完全相等。只检查关键图片、每条路由只检查一张图片、抽样检查、只审查清单或只检查一种视口，都视为 Phase 0 步骤失败。
7. 编写并重新打开 task-workflow/phase-0-source-contract.md，核对 progress.md 和 open-gaps.md，评分至少达到 48/50，并通过所有关键项。
8. 将 CURRENT_PHASE.txt 设置为 phase-1-ui-implementation，重新打开 Phase 0 文档，然后才检查目标架构、现有资产、路由、软件包、配置、构建输出或运行时文件。

只有完成步骤 7 的全部内容，才能解锁目标检查；仅捕获屏幕截图、完成清单、制定计划或声称已了解源文件，都不够。如果检查点有任何一项缺失，就必须停留在仅检查源文件的阶段。如果不确定是否通过，就按未通过处理。首次源方向确认还有顺序锁：在步骤 4 完成且桌面端和移动端图片均已打开之前，不得打开或读取源 HTML、任何内联 CSS 或 JavaScript，即使只是为了规划方向确认数据包也不行。生命周期调用失败不算完成步骤 4。将此类失败视为 Phase 0 中的硬性暂停：唯一合法的下一步是检查由辅助工具负责的失败，修正范围受限的调用（例如选择另一个明确指定的端口），读取修正后的数据包，然后通过生命周期辅助工具重新运行。不得读取源 HTML/CSS/JavaScript 或设计 JSON、编写 Phase 0 交接文档，也不得将辅助工具日志或部分屏幕截图视为方向确认的证据，除非辅助工具负责的重新运行成功且所有成功生成的方向确认图片均已打开。 任务消息可能要求使用真实品牌 Logo。该要求仍然适用，但其中“唯一例外”的措辞是资源选择说明，不是提前检查的例外。请将该要求记录在 Phase 0 合约中，并仅在源检查点解锁目标研究后检查或复制真实 Logo。切勿提前打开 public/、build/ 或其他目标资源路径来查找它。

首次生命周期导向前，不得在目标仓库或 task-workflow/ 中执行任何读取、列表、存在性检查、环境探测或可用性探测。首次导向前唯一允许的操作，是直接向 task-workflow/** 写入脚手架文件或副本，随后写入一份导向数据包，强制回读一次完整的导向数据包，并调用生命周期辅助程序。设置操作必须只写入：每条用于创建目录或复制文件的 shell 命令都必须以最后一次写入结束。cp <anything> task-workflow/... && ls ...、mkdir ... && cp ... && ls ...、设置后单独执行 ls、仅用于宣布设置完成的末尾 echo/printf，或任何追加的 cat、test、stat、git status、find、rg 或其他验证，都是严重的流程违规。最后执行 printf 'phase-0-source-contract' > task-workflow/CURRENT_PHASE.txt 是有效的设置写入，前提是它是最后一次写入，且之后立即写入导向数据包。不得使用第二条 shell 命令验证或宣布设置完成。最后一次设置写入后，下一次工具操作必须写入导向数据包；写入后，下一次工具操作必须读取完整的导向数据包；仅此读取之后，才可进行首次生命周期调用。你可以复制模板和生命周期辅助程序供后续阶段使用，但在导向数据包回读前，不得列出、重新打开或读取任何已复制的辅助程序、模板、源文件、记录文件或其他 task-workflow 文件；禁止读取复制的 playwright-lifecycle.mjs 以了解其标志或参数，因为以下命令约定具有权威性。不得先列出 task-workflow/、重新打开模板、检查记录文件或检查存在性/元数据状态。首次调用辅助程序前，禁止使用 test -d、test -e、test -f、stat、file、wc、du、head、tail、sed、grep 和 rg 这些确切形式，即使它们仅用于检查是否需要清理或了解源文件大小，也不允许。不得运行 ls、find、tree、git status、which、command -v、python --version、node --version、--help 或类似命令。应直接在辅助程序中使用已知且有界的服务器命令；不得事先测试 Python、Node、Playwright 或某个端口是否存在。

</first_action_lock>

首次定向前的读取许可名单 — 硬性截止

在首次成功完成生命周期定向之前，Agent 唯一可以读取的文件是位于其精确映射路径的 SKILL.md、references/phase-0-source-contract.md 和 references/playwright-lifecycle.md，以及任务消息。读取任何其他路径都会导致 Phase 0 失败，使本次运行无效。这明确包括 assets/scripts/playwright-lifecycle.mjs、assets/templates/ 下的所有文件、任何复制的辅助文件或模板、task-workflow/**、源 HTML、内联 CSS、JavaScript、设计 JSON、目标仓库、软件包文件和运行时文件。辅助文件和模板可以作为盲写入内容逐字节复制，但不得打开它们来了解标志、结构或内容。本技能中的命令约定已足够；不要为了核实或理解命令约定而读取辅助文件。如果违反此截止要求，请停止、重置测试环境并重新开始 Phase 0。

在首次定向之前，设置需要时，请仅使用资产映射中的精确路径，逐字节复制辅助文件和模板。不要列出、展开通配符、搜索或读取 .agents/skills/source-html-to-app-ui/references/、.agents/skills/source-html-to-app-ui/assets/scripts/、.agents/skills/source-html-to-app-ui/assets/templates/，也不要读取任何复制的辅助文件或模板来发现标志、结构或参数。生命周期命令约定和映射的参考文件具有权威性；允许复制，但不允许枚举目录或检查资产。

不可协商的测试关卡

<hard_stop_rules>

本次运行旨在测试工作流是否得到遵循。以下操作并非无害的调查；任何一项都会使当前运行无效，并要求在继续之前重置：

绝不执行	正确做法
首次运行辅助程序前，执行 ls、find、cat，或任何等效操作来检查 /ms-playwright、~/Library/Caches/ms-playwright、node_modules/playwright-core、browsers.json、浏览器可执行文件路径、修订版本或进程／端口状态；执行 which、command -v、--version、--help 或类似命令来探测服务器／运行时是否可用	编写任务专用的数据包，并调用真正的生命周期辅助程序；其首个数据包是唯一的可用性测试
node -e、node --eval、heredoc 浏览器程序、node task-workflow/**/<packet>.mjs，或任何直接的 chromium.launch() 进程	仅将数据包作为辅助程序的 --run 负载运行
page.waitForTimeout(、waitForTimeout(、setTimeout(、setInterval(、shell sleep，或用于等待 UI 稳定的计时器／任意轮询	等待可见的 DOM、URL、响应、几何信息或断言状态
手动／后台服务器、curl／wget 就绪探测、pkill、lsof，或大范围清理进程	将服务器启动、就绪检查、日志和 PID 清理交由辅助程序处理
以任务消息中的资源／徽标例外、必需的品牌徽标路径、目标根路径或实现要求为由，提前检查目标	记录该要求，并推迟所有目标读取，直到字面意义上的 Phase 0 检查点通过
首次生命周期定向完成且已打开桌面端／移动端图像之前，打开、计数或读取获准的源 HTML、内联 CSS 或 JavaScript；包括对源文件使用 wc、stat、file、du、head、tail、sed、grep 或 rg	仅复制源文件；立即通过生命周期辅助程序运行定向数据包，打开其图像，然后将源文件读取至 EOF
允许定向数据包跳转到目录列表、错误路由、空白文档或无关页面；或将辅助程序的就绪 URL 当作获准的 HTML 已打开的证明	将准确的 HTML URL 传入数据包，断言准确的最终 URL 和非目录内容，在任务提供身份信息时断言该信息，并记录标题以便之后与源文件核对；通过生命周期辅助程序使错误页面图像失效并重新采集
Phase 0 源检查点之前，列出、搜索、读取或检查目标的 app/、public/、server/、程序包、配置、程序包文件、node_modules、build/dist、测试、运行时日志、目标资源，或技能的 assets/scripts/ 和 assets/templates/；或在首次运行辅助程序前，使用 ls、find、test -d、test -e、test -f、stat、file、wc、du、head、tail、sed、grep 或 rg 验证 task-workflow/ 的设置，包括脚手架命令末尾附带的 ls 或先读取复制的辅助程序	仅处理源文件：通过只写命令创建／复制任务专用脚手架，编写并仅读取定向数据包，调用生命周期定向程序，打开其图像，将 HTML/CSS/JavaScript 读取至 EOF，运行并打开完整的源文件清单，然后更新并通过 Phase 0 产物
完成指令／参考资料设置后、Phase 0 源码检查点之前，工作区中唯一允许的操作是直接创建／复制 task-workflow/**、读取已批准的设计元数据、编写方向说明包、为审计而读取该说明包、通过生命周期辅助工具运行该说明包、打开其源码证据，以及更新 Phase 0 产物。不要列出或读取目标根目录，也不要探查目标环境来决定要做什么；任务提示已提供目标边界，只有到达明确的解锁点后才能开始研究目标。强制顺序为：在桌面端／移动端进行源码方向梳理 → 打开方向说明图片 → 将 HTML/CSS/JavaScript 完整读取至 EOF → 完成源码清单并打开证据 → 完成 Phase 0 产物检查点 → 研究目标。完成脚手架／模板／源码复制后，不要读取已复制的辅助工具或任何其他 task-workflow 产物；只编写和读取方向说明包，然后调用首次生命周期方向梳理。在编写每个后续数据包之前，先读取该数据包并移除上述禁止构造；不要为了观察结果而“先运行一次”明知无效的数据包。生命周期辅助工具不会使无效载荷合法化。如果发生任何禁止操作，立即停止，在当前 task-workflow 产物中记录失败，重置测试环境，并从 Phase 0 重新开始。

</hard_stop_rules>

Phase 0 之后的托管验证锁定

<managed_verification_lock>

通过 Phase 0 不会放宽生命周期所有权要求。从 Phase 1 直到完成，每次目标浏览器检查、截图、布局测量、滚动测试或运行时检查，都必须通过生命周期拥有的数据包执行。不要直接运行 pnpm run dev、npm run dev、vite 或 react-router dev；不要将服务置于后台；不要使用 shell sleep、curl、wget、端口探测或手动进程清理来启动、等待、检查或停止服务。构建或类型检查成功不等于浏览器验证。

唯一合法的目标浏览器流程是使用生命周期辅助工具，并明确提供目标服务、就绪 URL、运行时目录和数据包：

cd <target-repository>
node task-workflow/scripts/playwright-lifecycle.mjs \
  --server "<target-start-command>" \
  --ready-url "<target-readiness-url>" \
  --runtime-dir "task-workflow/runtime/target" \
  --run "node task-workflow/target-playwright/<packet>.mjs"

如果此流程失败，请修复任务拥有的数据包或有界的辅助工具调用，并通过辅助工具重新运行。绝不要以手动冒烟测试替代。直接启动目标服务、通过 shell 等待、探测就绪状态或检查浏览器，均属于严重流程违规：立即停止，记录违规，重置测试环境，并从 Phase 0 重新开始。

</managed_verification_lock>

操作约定

<operating_contract>

将此文件视为规范性的五阶段执行协议。开始工作前阅读，每到阶段边界时重读，并在压缩、恢复、重试、重新连接或开启新的编码会话后重读。开始当前阶段的工作前，加载该阶段对应的参考资料。

Phase 0 写入锁定 — 执行任何命令前阅读

在 task-workflow/phase-0-source-contract.md 写入、重新打开、评分至少达到 48/50、所有关键项均通过，且 task-workflow/CURRENT_PHASE.txt 设置为 phase-1-ui-implementation 之前，本次运行仅限源码操作。只能写入 task-workflow/**，包括源码运行时文件、源码载荷、清单、截图和日志。不得写入 app/**、public/**、server/**、软件包、配置、软件包文件、构建／dist、测试或任何目标资源。不要运行 curl 或任何输出到目标路径的下载命令。将下载的源码资源保存在 task-workflow/ 中；只有通过 Phase 0 门槛后，才能将其移动或复制到目标路径。品牌 Logo 例外仅影响 Phase 1 的资源选择；绝不允许在通过门槛前写入 public/。任何门槛通过前的目标写入都属于严重的 Phase 0 失败：删除或还原该写入，记录修复，并在开始实现前从 Phase 0 重新开始。

对于任何浏览器、服务、就绪状态、运行时或证据命令，生命周期辅助程序都是唯一的进程所有者。在任务开始前和执行期间，绝不可通过 `node -e`、`node --eval`、heredoc、独立脚本、缓存／可执行文件检查或可用性探测来运行浏览器或 Playwright 预检；绝不可使用 `which`、`command -v`、`--version`、`--help` 或类似方式探测服务运行时；绝不可手动启动服务、使用 `&` 将服务置于后台、使用 `nohup`、使用 shell `sleep`、通过 `curl`／`wget` 探测，或使用 `pkill`、`lsof` 或大范围进程搜索进行清理。使用辅助程序的实际数据包来确认现有浏览器和服务是否正常工作。唯一例外是通过 `curl` 下载已批准的品牌资源，且只能在 Phase 0 门禁通过后进行；这绝不能用作就绪状态或 UI 证明。任何直接运行浏览器／预检命令，或手动运行服务／探测／清理命令，都是严重的流程失败：停止该数据包，记录失败，然后通过 `playwright-lifecycle.mjs` 重新运行该数据包，再评分或晋级阶段。

不存在探索性浏览器例外。选择器检查、动画诊断、截图调查、控制台探测、布局测量或一次性复现，都属于浏览器证据工作。不要创建 /tmp 诊断文件、由 shell 生成的浏览器文件、内联浏览器程序，或 task-workflow/ 目录之外的临时 Playwright 脚本；不要仅仅因为任务自有数据包很短就直接运行它。将诊断添加到适当的 task-workflow 数据包中，将输出保存在 task-workflow 下，并通过下方的生命周期命令形式调用该数据包。只有在辅助程序当前正在运行的数据包内，才允许使用 chromium.launch()。任何其他方式运行它都属于严重失败，即使该数据包是只读的，或只打印计算样式，也不例外。

第一个生命周期数据包也是唯一的浏览器可用性检查。绝不可检查 /ms-playwright、~/Library/Caches/ms-playwright、node_modules/playwright-core、browsers.json、可执行文件路径、浏览器修订版、.runtime.logs 或进程／端口状态，以判断 Playwright 是否可用。绝不可为此使用 ls、find、cat、ps、lsof 或软件包／运行时探测。调用实际辅助程序数据包；如果失败，只检查辅助程序所有的运行时输出，并修复数据包或范围受限的调用。检查缓存、可执行文件、修订版和可用性属于严重的流程失败。

调用辅助程序前，从第 1 行读到文件末尾，完整回读自定义数据包。每次写入或编辑数据包后，紧接着的下一次工具调用必须从第 1 行读到文件末尾，完整回读；在编辑和回读之间，不要运行 grep／rg、再次编辑、调用辅助程序或使用任何其他工具。只有完成这项强制完整回读后，才能通过定向片段确认局部编辑；定向片段不能替代审查。写入响应、差异预览、grep／ripgrep 结果或记忆中的内容，都不能证明整个数据包已完成审查。在数据包或阶段产物中记录完整回读和固定等待审查。若数据包包含 page.waitForTimeout(、waitForTimeout(、setTimeout(、setInterval(、shell sleep、用于等待 UI 稳定的任意轮询／计时器代码，或会抑制浏览器等待、导航、截图、控制台、页面错误或断言失败的 catch／回退逻辑，则该数据包无效，且不得运行。浏览器数据包必须在出错时明确失败：绝不可使用 .catch(() => ...)、宽泛的 try/catch、被忽略的 promise，或可选的回退流程，在必需的浏览器工作失败后继续执行。用可见状态、URL、DOM、响应或几何条件替代计时器等待，例如 locator.waitFor、waitForSelector、waitForURL、waitForResponse 或断言。这是模型拥有的数据包检查，不是评分脚本；任何禁止的结构一旦进入辅助程序，即构成严重的数据包失败，在重写并重新运行数据包之前，不得对该阶段评分或晋级。 Agent 负责每个关卡。阶段关卡是基于证据的自我审查：检查工作，诚实地计算分数，找出薄弱项并修复，更新失效的证据，然后重新评分。未通过关卡意味着进入修复循环，而不是向用户提交报告。只要覆盖范围、证据质量和所需结果保持不变，处理细节可根据任务有所不同。

浏览器脚本用于收集证据，不用于评分或推进阶段。不要创建阶段检查、评分、收尾、收据、强制读取或阶段推进脚本。唯一提供的运行时脚本是 playwright-lifecycle.mjs，负责管理浏览器／服务生命周期。预计会编写自定义 Playwright 脚本，用于发现、交互、捕获、测量和比较，并通过该辅助程序运行。

仅依据当前产物、已打开的证据、回读内容和实际目标文件推进。摘要中的声明、绿色构建、截图路径或先前的 Pass 标签本身都不能作为证明。如果后续工作使某个关卡失效，请返回最早受影响的阶段，并依次重新通过后续阶段。

</operating_contract>

阶段映射

<phase_map>

阶段	标记	负责内容	关卡	结果
0	phase-0-source-contract	最新产物、受管理的源发现、完整清单、源／设计交接、复现约定	48/50	已理解并提供证据，涵盖每个源页面／状态／版块／交互
1	phase-1-ui-implementation	目标研究、负责人映射，以及按顺序以目标原生方式实现经审查的数据包	48/50	每个约定的路由／状态／版块／交互都拥有实际的目标端负责人和编写完成的目标 UI
2	phase-2-paired-responsive-proof	代码完整性、检查／构建、源与目标配对的 Playwright 证明	48/50	响应式、主题、滚动、侧边栏、抽屉及配对证据均通过
3	phase-3-fidelity-repair-signoff	版块比较、不匹配修复、对抗性检查、真实输入证明	49/50；桌面端／移动端各 48/50	一对一视觉与行为验收通过
4	phase-4-final-audit-completion	产物完整性、当前证据、最终差异、完成锁定	恰好 50/50	每个关卡仍然有效，且已解除完成锁定

</phase_map>

在负责该项工作的阶段内完成工作。每个阶段的工作各不相同；不要借助后续阶段来绕过较早的关卡。只要本地修复可行，就继续完成阶段 4。只有在外部阻碍已得到证实、记录在当前产物和 task-workflow/open-gaps.md 中，且不存在本地恢复方案时，才能停止。

阶段门禁循环

每个阶段都运行此循环：

1. 在阶段工作开始前，将 task-workflow/CURRENT_PHASE.txt 设置为该阶段的标记。
2. 重新阅读此文件、对应的参考资料、当前阶段产物、progress.md 和 open-gaps.md。
3. 记录一份简短的工作或证据包：范围、预期负责人、证据路径、排除项及其审查操作。
4. 仅执行该证据包中的工作，并使用所需的真实输入和托管的 Playwright 生命周期。
5. 重新打开已更改的文件和生成的产物；检查重点差异，并在评分前完成证据包逐张图片的清单检查。
6. 对照浏览器发现、源声明、目标代码、证据身份和差距负责人进行核对。
7. 更新并回读阶段产物、progress.md 和 open-gaps.md。
8. 根据具体证据为每条评分标准打分，并单独评估每项关键内容。
9. 如果未通过，将标记保留在该阶段，记录最早需要修复的问题，修复问题，刷新失效的证据，并从步骤 2 开始重做。
10. 如果通过，记录晋级锁定，重新打开产物链，核验算术和证据，设置下一个标记，并立即加载下一份参考资料。

产物链必须保持一致：标记、阶段产物、progress.md、open-gaps.md、证据台账和实际文件必须描述相同的当前阶段和下一步操作。CURRENT_PHASE.txt 是恢复指针，不是证明。progress.md 是精简的恢复台账，不能替代详细证据。

将浏览器工作和视觉审查限制在范围明确的证据包内。源端或目标端证据包应负责一组路由／状态系列及一组协调的视口／主题，并包含数量适中、便于审查的输出。不要创建一个庞大的整体语料库证据包，以免因不相关的选择器或状态问题而必须全部重跑。证据包通过后，保留其清单行；仅修复并重跑失败或失效的证据包，并在证据发生变化时使用新的修订路径。

新建任务工作区

首次写入目标仓库时，根据提供的素材创建干净的 task-workflow/。移除过时的 task-workflow/ 状态，然后创建：

• CURRENT_PHASE.txt、progress.md、open-gaps.md 和 spec.json；
• 五个阶段各自对应一个产物；
• source-playwright/、source/、target-playwright/、verification/；
• runtime/source/、runtime/target/；
• 从本技能逐字节复制的 scripts/playwright-lifecycle.mjs。

将提供的设计 JSON 逐字节复制到 task-workflow/spec.json。所有生成的截图、脚本、清单、运行时日志、说明、台账和决策都必须保存在 task-workflow/ 下。保留提供的模板及其评分卡、关键门槛和晋级锁。只有在证据仍然明确且可评分时，才可以缩短确切措辞。

在阶段 0 期间，上述开篇操作契约锁是绝对要求：目标实现、配置、包、资源、生成、构建和测试文件都必须保持只读且不得读取。在仅检查源代码的证据序列完成之前，不得打开、列出、搜索、查找、检查或调研目标文件、目标构建输出、目标运行时日志、目标资源或目标依赖项。必须按以下顺序操作：(1) 创建 task-workflow 脚手架；(2) 通过生命周期辅助脚本，在桌面和移动设备上进行首次源代码概览；(3) 打开这些概览图像；(4) 将获准的 HTML、内联 CSS 和 JavaScript 读取至文件末尾；(5) 通过生命周期辅助脚本运行并打开完整的源代码清单／状态／分区证据；(6) 记录源代码／设计交接，并对阶段 0 的源代码契约进行评分，确保所有关键条目均通过；(7) 重新打开产物，验证晋级锁，并将 CURRENT_PHASE.txt 设置为 phase-1-ui-implementation；只有此后才能开始调研目标。阶段 0 的交接应指出必需的目标角色和适配方式，但不得在目标调研前臆造确切的目标文件。如果过早检查或写入目标文件，阶段 0 即告失败；只移除或还原过早的写入，记录失败情况，然后重新执行源代码门槛。绝不能使用过早的目标调研或实现作为阶段 0 已通过的证据。

证据契约

<evidence_contract>

源项目发现

严格按以下仅针对源项目的顺序执行：搭建 task-workflow；通过生命周期辅助工具启动源项目；恰好截取一张桌面端和一张移动端方向参考图，并打开两张图片；然后从头到尾完整读取已批准的 HTML、内联 CSS 和 JavaScript；接着通过辅助工具运行完整的源项目清单，并逐张遍历清单中的图片；然后更新并通过 Phase 0 源项目契约；此后才能检查目标架构和资源。方向参考图仅用于启动检查。后续的清单图片遍历是指：完整读取清单，按清单顺序处理每条图片路径，以可读比例打开每张图片，并针对该图片的身份记录一条具体观察结果。只有打开图片数量等于清单图片数量时，遍历才算完成。不得根据关键图片、每条路由一张图片、代表性样本、单独的联系表、仅审阅清单或单一视口进行评分或晋级。较早的仅针对源项目的步骤中，不得检查目标文件、构建产物、运行时日志或依赖项。清点所有类似页面的界面、路由、隐藏视图、状态、区段、交互类别、主题、断点、滚动容器、固定／粘性区域，以及源项目声明但初始时不可见的条目。

使用 Playwright 面向用户的输入 API 到达页面和状态：根据需要使用 locator/page 的 click、fill、selectOption、press、wheel、拖动或触摸操作。不得使用 evaluate(() => element.click())、dispatchEvent(...)、合成路由、直接调用处理程序或 DOM 修改来代替真实交互。这也包括先赋值给 el.value、el.checked 或类名，再派发 input、change 或点击事件。如果常规操作失败，请诊断并修复页面或交互目标；不得通过 DOM 派发事件来绕过失败。选择器应限定在当前活动的路由／状态中，并在使用前断言目标控件或区段唯一。所需区段／状态的截图必须在定位器、断言、截图或发现结果失败时导致证据包失败；不得捕获错误、记录日志后继续提交不完整证据。让清单决定证据量：页面、状态、区段或截图数量没有固定上限。对于每个清点出的页面和有意义的状态，均须采集桌面端和移动端完整视图证据，并在适用时采集清晰可读的区段／状态／主题证据。

配对验证

通过生命周期管理的独立运行分别采集源项目和目标项目。按路由、状态、主题、视口、区段和取景范围配对图片。为每张图片分配唯一且稳定的 ID／路径，并记录实际尺寸、采集时间、生命周期运行、打开时间和具体发现。重新采集时使用新的修订版路径。

在为任何阶段评分前，先完成逐张图片的视觉核验闭环。完整读取清单，然后逐张打开清单中的所有图片，或每批打开不超过 4 张彼此相关且清晰可读的图片。这是对每次审阅批次的上下文保护规则，并非对页面、状态、区段、视口或截图总量的限制。每批审阅后，立即将已打开图片的结果和每张图片的一条具体发现追加到所属阶段的产物中，更新 progress.md 和 open-gaps.md，并回读这些更新，然后再打开下一批。持续进行，直至已打开图片数量与清单数量完全一致。仅审阅“关键图片”、每条路由一张图片、代表性样本、未查看组成图片的联系表、仅审阅清单或只打开一个视口，均属于自动判定的证据失败。只有在打开确切图片并记录其发现后，截图路径或清单行才构成证据。比较内容／顺序、几何布局、间距、字体排版、颜色、背景、边框、圆角、阴影、资源、控件、裁切、重叠、响应式变换、交互状态和滚动行为。

响应式与主题安全

检查桌面端、适用时的平板端、移动端、缺失尺寸的推算结果、短视口高度下的溢出、源主题、目标所需主题，以及重要交互状态。根据已认可的源设计系统／设计规范，谨慎推导缺失的目标主题。修复重叠、裁切、内容截断、画布水平溢出、控件无法使用、意外的文档滚动或空白区域等客观缺陷。

当源页面的入场动画影响截图可读性时，通过真实控件到达相应状态，并等待源页面自身的 DOM、几何位置、不透明度或过渡条件达到稳定状态。不得注入样式、设置不透明度／类名、禁用动画，也不得以其他方式修改源 DOM/CSS 来提升截图可读性。如果源页面没有稳定状态，应记录该行为及其证据，而不是在数据包内改写源页面。

</evidence_contract>

侧边栏、内容滚动与抽屉规范

<sidebar_contract>

存在侧边栏时，应将其滚动架构视为目标要求，而非外观细节。使用真实滚动输入，在强制溢出的短桌面视口高度下验证，并提供前后截图。

分别记录以下两项规范：

规范	记录内容
源页面观测结果	源页面文档／内容滚动值、侧边栏边界、粘滞／固定行为及可见结果
目标要求	视口边界内的外壳、具名侧边栏、具名内容滚动容器、文档滚动保持不变、内容滚动增加、侧边栏固定于视口

目标验证必须从目标清单中复制原始值，并计算：

• 文档滚动增量 = 0；
• 内容窗格滚动增量 > 0；
• 侧边栏顶部和底部的位移均不超过 1px；
• 侧边栏高度及底部覆盖视口的误差均不超过 1px；
• 滚动后的图像中，侧边栏下方没有空白区域。

源页面的值用于描述参考对象；不能用于满足或放宽目标条件。依赖文档滚动、仅使用粘滞定位、固定高度条带或未命名溢出容器的目标，必须返回阶段 1 修复外壳。

存在移动端抽屉时，必须通过真实输入验证打开／关闭、遮罩拦截、全视口几何尺寸、正文／文档滚动锁定，以及滚动位置恢复，并提供截图和测量结果。

</sidebar_contract>

Playwright 托管生命周期

仅限生命周期管理的入口规则

每项浏览器或运行时 UI 检查都必须由生命周期管理。自定义 Playwright 文件是供辅助程序使用的载荷，绝不能作为独立命令运行。不要运行 node task-workflow/source-playwright/<script>.mjs、node task-workflow/target-playwright/<script>.mjs、带有 Playwright 的 node -e/node --eval、内联 heredoc 浏览器程序，或任何等效的直接浏览器命令。调试浏览器行为时，应编辑任务专用的 .mjs 数据包，然后通过辅助程序重新运行该数据包；绝不要将诊断文件写入 /tmp 或其他临时位置，也绝不要使用 shell heredoc 或重定向来生成浏览器脚本。不要为冒烟测试、就绪测试或浏览器运行启动后台服务；不要让 Playwright 连接手动启动的服务；不要使用 shell sleep、curl 或其他手动请求来替代辅助程序提供的就绪 URL。构建后，使用有界服务命令、就绪 URL、运行时目录和自定义 Playwright 载荷调用生命周期辅助程序，以验证运行中的目标。不要调用 playwright install、playwright install --dry-run 或任何等效的浏览器安装或可用性检查命令；应通过生命周期辅助程序使用现有的浏览器缓存。

所有源端和目标端数据包均使用以下格式，只更改自有服务、就绪检查和载荷：

node task-workflow/scripts/playwright-lifecycle.mjs \
  --server "<bounded server command>" \
  --ready-url "http://127.0.0.1:<port>/<ready-path>" \
  --run "node task-workflow/<source-or-target-playwright>/<packet>.mjs"

辅助程序必须负责启动、就绪检查、浏览器环境、运行时日志和按 PID 清理。如果浏览器或服务失败，应检查由辅助程序管理的日志，并修复调用方式或数据包。绝不要绕过辅助程序来测试载荷是否有效；直接运行 Playwright 命令（包括一次性的调试命令）属于严重流程违规，即使它产生了有用输出也是如此。生命周期运行失败始终属于门禁失败，直到通过辅助程序重新运行并获得可用证据。

通过辅助程序启动源端、采集证据并停止；再通过辅助程序启动目标端、采集证据并停止；然后比较保存的证据。端口、脚本、屏幕截图和运行时日志必须彼此隔离。

使用确定性的就绪条件和状态条件，不要使用固定等待时间。page.waitForTimeout、shell sleep、任意轮询延迟和仅靠计时器等待稳定都属于严重的数据包问题；应移除这些做法，记录门禁失败，并在评分前通过辅助程序重新运行。将就绪检查和聚焦脚本的超时设为 15,000–20,000 ms。如果某次运行仅因计时器结束且没有有用诊断，应先记录完整的排查结果，再进行一次 60,000 ms 的重试；通过拆分工作，确保单个定向脚本不超过 120,000 ms。遇到有用的失败信息时，应将其作为修复任务：重新运行前，检查日志、DOM/状态、控制台、网络和服务输出。

生命周期管理及按 PID 清理必须始终由辅助程序负责。优先使用明确的任务专用端口、有界脚本和聚焦重试。保持辅助程序逐字节不变；不要在常规工作流之外进行进程搜寻、后台服务循环、任意端口扫描、浏览器下载或手动生命周期管理。

适配规则

• 在有对应源端证据的地方，逐项匹配并接受这些证据。
• 保留源内容、层级、间距、字体排印、颜色、控件、状态、路由、交互、主题和资源。
• 在保留源端可见效果的同时，采用目标端要求的安全视口外壳／内容滚动区架构。
• 根据源端证据、设计 JSON 和目标端令牌，保守推断未提供的断点。
• 如果有真实的仓库 Logo，请使用它。
• 对不受支持的导航予以禁用，不要虚构目标位置。
• 实现仅限 UI，并以源端证据为依据。

简历和参考资料加载

压缩、恢复、重试、重新连接或开启新会话后，按以下顺序阅读：

1. 此 SKILL.md；
2. task-workflow/progress.md；
3. task-workflow/CURRENT_PHASE.txt；
4. task-workflow/open-gaps.md；
5. 当前阶段或最早失败阶段的产物；
6. 与该标记对应的参考资料；
7. 该阶段所需的任务输入、源 HTML、设计 JSON 和当前目标文件。

参考资料映射：

标记	阅读
缺少工作流或 Phase 0	references/phase-0-source-contract.md、references/playwright-lifecycle.md
Phase 1	references/phase-1-ui-implementation.md
Phase 2 或 3	references/phase-2-3-playwright-fidelity.md、references/playwright-lifecycle.md
Phase 4	references/phase-4-final-audit-completion.md

完成锁定

完成前，请确认：

1. CURRENT_PHASE.txt 为 phase-4-final-audit-completion；
2. 每个阶段产物都在要求的阈值上标明 Decision: Pass；
3. 每个关键行、数据包审查、晋级锁定和差距行都有具体的当前证据；
4. 每张引用的图片都存在且已打开，并有对应的源文件与目标文件对比；
5. 最终桌面端／移动端／区块／侧边栏／抽屉证据均对应最终目标代码；
6. 最终差异仅涉及 UI，且所有必需的检查／构建证据仍为最新；
7. 已复制任务说明中的确切完成命令，但尚未运行；它是唯一剩余操作。

使用提供的确切命令，例如：

node /workspace/builder/task_complete.mjs --projectId "<projectId>" --taskId "<taskId>" --status completed --summary "<brief summary>"

读回 Phase 4 产物和 progress.md 后，将该确切命令作为最后一个工具操作运行。之后不要再运行其他工具；直接根据其结果作答。

资源映射

运行时产物	源资源
phase-0-source-contract.md	assets/templates/phase-0-source-contract.md
phase-1-ui-implementation.md	assets/templates/phase-1-ui-implementation.md
phase-2-paired-responsive-proof.md	assets/templates/phase-2-paired-responsive-proof.md
phase-3-fidelity-repair-signoff.md	assets/templates/phase-3-fidelity-repair-signoff.md
phase-4-final-audit-completion.md	assets/templates/phase-4-final-audit-completion.md
progress.md	assets/templates/progress.md
open-gaps.md	assets/templates/open-gaps.md
scripts/playwright-lifecycle.mjs	assets/scripts/playwright-lifecycle.mjs