p2f CLI

p2f 是为 PRD 原型页面采集还原数据、生成实现计划的 CLI。它不直接生成 Dart 页面代码。

核心目标

• 从原型 URL 定位对应的 PRD 页面入口和相关源码范围。
• 使用 Playwright 采集 DOM、可访问性信息、computed styles、可见文本和运行态结构数据。
• 按 Flutter 项目已有图片目录结构同步目标页面运行态可见图片，优先复用 assets/images/<业务目录>/；同步前会用内容、视觉指纹和语义名复用已有图片，未命中的普通 SVG 转为 PNG 2X，SVG 动画保留原文件。
• 抽取页面结构、设计 token 候选、候选交互和运行态数据。
• 扫描目标 Flutter 项目，判断目标页面是否已经存在。
• 生成 main.md、截图探索计划和 implementation-plan.md，把 JSON、源码范围、风险点和实现线索交给 agent。
• CLI 负责采集、图片资源同步和规划，不直接生成 Dart 页面代码。

文档

• 使用流程：初始化、常用命令、标准还原流程、generate 阶段和项目结构 profile。
• 产物与 Agent 规则：任务目录、关键产物、截图规则、审阅顺序和实现规则。
• 维护与发布：CLI 更新、发布、本地开发和 scanner/profile 维护。

环境要求

• Node.js >= 20
• Git 和 PRD 原型源码仓库访问权限
• Flutter SDK
• Flutter 项目根目录，必须存在 pubspec.yaml；默认 profile 按 lib/app 结构扫描
• PRD 原型 Git 仓库地址，首次初始化时通过 p2f init <remote> [branch] 传入
• CLI 会把 PRD 原型源码同步到当前项目的 .p2f-workspace/prd-source

p2f init 会自动安装 PRD 依赖、Playwright Chromium 和内置 p2f skill，不需要手工运行 npx playwright install chromium。升级 CLI 或内置 skill 变更后，可以重新执行 p2f skills-install 安装/更新 agent 规则。

安装

从 npmjs.com 全局安装：

npm install -g prd-to-flutter

升级到 npmjs.com 上的最新版本：

npm install -g prd-to-flutter@latest

包页面见 prd-to-flutter。

本地开发见 维护与发布。

快速开始

在 Flutter 项目根目录执行，也就是包含 pubspec.yaml 的目录：

p2f init "[email protected]:team/prototype.git"
p2f sync
p2f generate "<页面链接>"

remote 必传，branch 可选且默认为 master。非 master 分支示例：

p2f init "[email protected]:team/prototype.git" main

初始化后仓库配置写入 ~/.config/p2f/repository.json，后续 p2f sync 和 p2f generate 直接读取该文件。

旧用户升级时，在已经初始化过的 Flutter 项目根目录执行：

p2f update

升级过程会从 .p2f-workspace/prd-source 的 origin 生成 ~/.config/p2f/repository.json，分支按旧版行为写为 master，并刷新当前项目的内置 p2f skill。p2f generate 触发自动升级时也会执行相同迁移。

升级现有项目时需要注意：

• 迁移只在升级过程中执行；sync、generate 和 doctor 不会从旧工作区 origin 隐式补配置。
• 旧版 *-default profile 名会自动兼容并归一为 flutter-getx，无需手工修改。
• cli/analysis/text-style-map.json 当前为 schemaVersion=2，条目中的文字样式字段统一为 textStyle。

如果需要人工指定页面名：

p2f generate --page "订单详情" "https://example.com/prototype/order-detail"

生成后读取：

.p2f-workspace/pages/<task-name>/main.md

再按 main.md 中的路径审阅 cli/analysis/feature-coverage.md、cli/analysis/screenshot-exploration-plan.md、cli/analysis/implementation-plan.md 等产物，让 agent 打开 live prototype 补齐 agent/screenshots/ 后再实现 Flutter 页面。

完整流程见 使用流程。

常用命令

| 命令 | 说明 | | --- | --- | | p2f init <remote> [branch] | 写入本机仓库配置并创建 p2f 工作区；branch 默认 master。 | | p2f sync | 从 PRD 远端配置分支拉取最新代码，并覆盖当前项目的 .p2f-workspace/prd-source。 | | p2f generate "<页面链接>" | 检查 p2f 版本和项目 skill；发现版本更新或规则不一致时自动刷新 skill，然后停止并提示重新加载后重跑。 | | p2f update | 升级 CLI；从当前旧工作区迁移仓库配置到 ~/.config/p2f/repository.json。 | | p2f paths --url "<页面链接>" | 打印当前项目的 p2f 工作区、共享项目快照、pages 和任务目录路径。 | | p2f screenshots-audit --url "<页面链接>" | 审计 agent 截图目录、375x812 基准、平台壳层以及 Flutter 根目录错误 .playwright-cli/ 产物。 | | p2f prune-assets --url "<页面链接>" | 实现后清理本次新导入且未被 Flutter 源码引用的图片。 | | p2f playwright-env --json | 输出 p2f 自带 Playwright 的解析路径，供 agent 截图脚本复用。 | | p2f doctor | 检查环境、skill、.p2f-workspace/prd-source 和 p2f 版本。 |

完整命令表见 使用流程。

项目结构 Profile

p2f generate 默认使用内置 flutter-getx profile。若 Flutter App 或 PRD 原型目录移动，但框架/语法约定没有变，可以在 Flutter 项目根目录新增 p2f.config.json 或 .p2f/config.json 覆盖扫描路径。

示例：

{
  "profile": "flutter-getx",
  "flutter": {
    "moduleRoots": ["lib/features"],
    "routeFiles": {
      "constants": ["lib/router/app_routes.dart"],
      "pages": ["lib/router/app_pages.dart"]
    }
  },
  "prototype": {
    "subprojectCandidates": ["frontend", "prototype", "."],
    "viewsDirs": ["src/pages", "src/views"]
  }
}

完整配置说明见 使用流程。

任务目录

每次 generate 会写入：

.p2f-workspace/pages/<task-name>/
  main.md
  cli/
    source/
    runtime/
    analysis/
    output/
  agent/
    manifest.json
    screenshots/
    runtime/

项目级快照固定写入 .p2f-workspace/project/flutter-project.json。完整产物说明见 产物与 Agent 规则。

原则

• p2f CLI 不直接生成 Dart 页面代码；运行态可见图片会按 Flutter 目录规范自动同步并生成资源清单。
• agent 实现前必须先审阅 main.md、feature coverage、截图探索计划和 implementation plan。
• cli/analysis/flutter-mapping.md 若输出 status=uncertain 或 agentReviewRequired=true，agent 必须先复核页面是否已存在，再决定修改已有页面或新增页面。
• agent 必须打开 live prototype 主动探索并补齐截图，截图写入 agent/screenshots/。
• agent 生成截图、探索日志、说明文件或修改 Flutter 文件后，必须同步更新 agent/manifest.json。
• 遇到 PRD 定位失败、Playwright 采集失败、Flutter 结构扫描失败或关键数据缺失时，必须 fail-fast，不基于不完整信息继续实现。

常见问题

为什么不让 CLI 直接写 Dart？

页面还原涉及已有页面复用、模块归属、路由、主题 token、业务状态和交互细节。纯 CLI 生成 Dart 的效果不稳定，容易偏离目标项目规范。p2f 的职责是准备还原数据和实现计划，真正实现由 agent 根据数据和项目规范完成。

为什么需要 Playwright？

PRD 原型页面的真实结构、样式和交互状态只有运行后才能看到。CLI 使用 Playwright 打开真实页面、等待渲染稳定并读取 DOM/样式/文本；截图和交互分支由 agent 后续在 live page 中主动探索。

.p2f-workspace 是否需要提交？

不建议提交。它是本地运行产物、截图、分析报告和页面目录，已经加入 .gitignore。