Native Multiplatform Frontend

多端原生前端

支持 web、wechat-mini、ios、android。服从现有工程，保留用户改动，不改无关代码，不擅自增加依赖，只报告实际验证结果。

0. 语言

默认中文优先。用户使用中文或未指定语言时，设计契约、Pencil 可见文案与图层名称、Token Showcase、HTML 实验室、生产界面示例内容、代码注释、验证记录和交付说明均使用简体中文；技术标识符、变量名、API 路径、框架名称与必须保持原文的品牌名可保留英文。用户明确要求其他语言时服从用户要求，并保证同一交付物内语言一致。

1. 阶段与闸门

按 target → api → contract → pen authorization → tokens → assets → pencil → lab authorization → lab → production authorization → implementation → verified 推进。每个箭头都是硬审批闸门：完成当前阶段后报告产物、验证结果和唯一下一阶段动作，然后暂停请求用户明确批准；“继续”“都可以”或先前对总任务的同意不得替代下一阶段的单独批准。

target: { platform, projectRoot, uiProvider, status }
api: { implemented, developing, unimplemented, unknown, status }
contract: { path, version, reviewStatus }
authorization: { aiAssets, penCreation, visualDecision }
tokens: { variables, showcaseNode, reviewStatus }
assets: { items, provenance, status }
pencil: { filePath, decision, tokens, components, screens, states, responsive, status }
lab: { path, routes, sharedShell, tokenPage, interactions, motion, fidelity, reviewStatus, status }
implementation: { productionWriteAllowed, status }
verification: { build, runtime, integration, fidelity, status }

目标与接口扫描属于契约准备，可连续执行只读工作。除此之外，每次进入 tokens、assets、pencil pages、lab、implementation 和最终验收前都必须单独询问。只允许在用户明确批准紧邻的下一阶段后继续；不得一次请求或一次回答授权多个未来阶段。没有 AI 素材时记录“无”并跳过该审批，不制造空闸门。

仅当目标端已确认、接口已分类，且所有适用设计阶段均通过时，才设 productionWriteAllowed: true。设计任务还必须满足：

• tool/design/design-contract.md 已接受；
• Pencil Variables 已建立，独立令牌展示画布已接受；
• AI 素材逐项获批，完整提示词与实际生成记录可追踪；
• 创建或修改 .pen 已获授权，Pencil 设计已接受；
• 必需的 HTML 实验网站与独立 Token 页面已运行；所有页面共享站点外壳、可直接互相跳转，并含获批微动画且通过忠实度检查；
• 用户已在实验室验收后单独批准写入生产工程。

低风险文案、状态或缺陷修复若不产生视觉决策，可复用现有设计系统并跳过设计阶段；一旦改变布局、风格、组件或响应式规则，恢复完整流程。

2. 目标端与接口

用户已点名唯一目标端时直接记录；否则按强证据推断。只有证据冲突或存在多个可实施端时询问：

只读取当前产品范围需要的 OpenAPI、Swagger 或接口资料，用“HTTP 方法 + 完整路径”定位请求，不猜端点、DTO 或错误码：

记录未来能力对导航、布局容量、窄屏收纳、数据模型和权限边界的影响，优先用功能开关隔离。页面负责编排，组件表达 UI，服务封装业务，网络层集中认证、超时和公共错误；显式处理加载、空、错、离线、未授权、取消、过期结果和重复提交。

3. 设计契约与授权

凡新增页面、改变设计系统、明显改版或创建/修改 .pen，先复制 设计契约模板 到项目内 tool/design/design-contract.md。用工程、接口和用户已提供信息填写；只在缺少会改变结果的信息时询问页面核心任务、参考稿与固定区域、视觉气质或多屏范围。

契约锁定范围、页面和状态、参考来源、真实内容、设计约束、令牌与组件类别、响应式、可访问性、AI 素材完整提示词及验收标准。无参考稿时记录产品世界、受众和禁止风格；局部参考只锁定明确区域；已有 .pen 时优先复用其 Variables 和组件。

完成后设 contract.reviewStatus: pending 并暂停。按顺序、逐阶段请求用户：

1. 接受或修改契约；
2. 批准或拒绝创建或修改 .pen；
3. 令牌展示画布完成后，接受或修改令牌；
4. 批准或拒绝列出的 AI 素材；
5. 接受或修改 Pencil 页面与状态；
6. 批准生成 HTML 实验室；
7. 接受或修改 HTML 实验室；
8. 批准写入生产工程。

不得合并上述审批。范围、令牌或完整提示词实质变化时递增版本并重新审批。

4. AI 素材、Pencil 与实验室

AI 仅生成 Logo、品牌符号、插画、产品图、纹理等确有价值的位图素材；整页结构、导航、文字、表单和组件保持可编辑。每项素材必须先在契约中包含实际使用的完整提示词、禁止项、尺寸、格式和授权。获批后加载 imagegen 或当前官方生图路径，逐项串行生成并记录工具、模型、最终提示词、输出路径和检查结果。Logo 优先“符号标记 + 代码原生品牌名”。

获得 .pen 授权后，完整读取 Pencil 设计流程。先建立 Variables 和独立令牌展示画布，暂停等待令牌审批；令牌未接受时不得设计业务页面。Pencil 是唯一视觉真源；所有 .pen 操作只使用 Pencil MCP。MCP、Schema 或文件不可用时设为 blocked，不退回整页生图或另一套视觉稿。

高风险任务在 .pen 中创建 2–3 个结构不同的可编辑方向；未获代选授权时暂停等待选择。方向接受后建立令牌、主题和组件，再逐屏完成页面、状态和响应式。所有视觉修订先落在 Pencil。

中高风险任务或现有视觉覆盖不足时，完整读取 HTML 实验室流程。只有用户单独批准后，才从已接受的 Pencil 节点导出到 tool/htmlcssjs/；必须生成一个带共享导航、真实链接和统一响应式规则的可浏览网站，包含独立令牌页，并用 CSS 与 JavaScript 实现少量、可关闭、尊重 reduced-motion 的微动画。禁止把桌面、移动和状态拆成互不相连的孤立 HTML。实验网站不接 API、认证或持久化，也不承担二次设计。实验室验收后暂停，等待生产写入授权。

5. 实施与验收

仅在 productionWriteAllowed: true 后实施。Pencil 令牌和组件是视觉规范，HTML 实验室是交互规范；按目标端原生模式表达，不把导出 HTML 强塞进小程序、SwiftUI 或 Compose。

构建前确认唯一工程或模块、配置、工具链、依赖、UI 提供方和输出位置，再读取目标端说明：

• web：build-web.md
• wechat-mini：build-wechat-mini.md
• ios：build-ios.md
• android：build-android.md

只有命令成功、日志无失败或跳过信号且产物确为本次生成，才报告构建成功。分别报告类型检查、测试、构建、运行、模拟器或真机、签名、接口联调和剩余风险。

中高风险视觉任务完成两层忠实度验收：

1. Pencil ↔ HTML 实验室；
2. Pencil ↔ 最新目标平台界面。

同屏查看设计和最新截图，至少比较文案、构图、字体、色彩、间距、组件、素材和响应式中的五项。记录偏差、证据和处置；有可修复偏差时继续迭代，不得宣称完成。

6. Git 提交简介

• 每次修改目标端生产源码、配置、测试或构建文件后，交付时都提供一份可直接复制的 Conventional Commits 建议，不等待用户再次询问。
• 使用 <type>(<scope>): <中文简述> 标题；优先选择 feat、fix、refactor、docs、test、perf、build、ci、chore。
• scope 使用稳定的产品领域或目标模块，如 web、miniapp、ios、android、ui、auth、tenant、store；一次提交涉及同一目标的页面、组件和服务时使用业务领域，不罗列目录。
• 标题描述单一逻辑目标，避免“更新前端”“修改代码”等空泛文字；正文用短列表总结关键变化、接口状态和实际验证结果。
• 存在不兼容变更时在类型后加 !，并在正文末尾添加 BREAKING CHANGE: ...。
• 改动包含多个彼此独立的逻辑主题时，建议拆成多条提交信息并说明各自文件范围。
• 只生成建议文本，不执行 git add、git commit 或 git push，除非用户在当前请求中明确授权。

模板：

type(scope): 简短说明

- 关键变化一
- 关键变化二
- 接口：已接入、预留或阻塞边界
- 验证：实际执行的类型检查、测试、构建或运行结果

7. 前端开发契约

• 目标工程进入持续开发后，在项目根目录创建并维护 FRONTEND_DEVELOPMENT.md，作为前端架构、页面状态、接口边界、设计实现、验证记录和后续计划的长期入口。
• 开始设计、开发、修复或审查前先读取该文档；如果文件尚不存在，在首次生产实现或接口联调任务中创建，不用一次性文档代替。
• 文档至少记录目标端、技术栈、目录职责、环境配置、页面与路由状态、接口状态、设计真源、验证基线、当前计划和按日期追加的验证记录。
• 页面、路由、权限、接口状态、设计系统、构建方式或实施阶段变化时，在同一任务内同步更新；只修改说明文字时可按影响范围更新。
• 接口状态只使用“未知、未实现、开发中、已实现、已废弃”，并明确示例数据、占位能力和真实网络请求的边界。
• 验证记录只写实际执行结果；未运行的类型检查、测试、构建、运行、模拟器、真机或接口联调明确写“未验证”。
• 已有同等职责且命名不同的项目文档时沿用现有文件，不重复创建，并在交付中说明入口。

8. 交付清单

• 说明目标端、源码、配置、依赖、路由、组件、状态、接口和设计契约变化。
• 说明 FRONTEND_DEVELOPMENT.md 或项目既有前端开发契约的同步内容。
• 列出类型检查、测试、构建、运行、模拟器或真机、签名、接口联调和忠实度检查的实际结果。
• 明确未验证项、剩余风险、未实现或未知接口边界及下一步联调动作。
• 只要本次修改了生产代码，就附上与实际改动一致的建议 Git 提交信息，并明确未代用户提交。