# Native Multiplatform Frontend

> 创建、改造、审查或构建 Vue Web、微信小程序、iOS、Android 原生前端。锁定唯一目标端并按接口状态实现或预留产品空间；新设计或明显改版按逐阶段审批流程完成设计契约、Pencil 令牌展示、组件、状态和完整界面，再生成可直接导航的响应式 HTML 实验网站并忠实实现到目标平台。

- Skill: `rayekry777/native-multiplatform-frontend` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add rayekry777/native-multiplatform-frontend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rayekry777/native-multiplatform-frontend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Rayekry777 (https://skillmd.com/u/rayekry777)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rayekry777/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` 推进。每个箭头都是硬审批闸门：完成当前阶段后报告产物、验证结果和唯一下一阶段动作，然后暂停请求用户明确批准；“继续”“都可以”或先前对总任务的同意不得替代下一阶段的单独批准。

```yaml
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. 目标端与接口

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

| 目标 | 强证据 | 唯一 UI |
|---|---|---|
| `web` | Vue 3 工程与有效构建脚本 | Vue 3 + Element Plus |
| `wechat-mini` | `project.config.json` 指向有效小程序根 | 微信原生或 TDesign，二选一 |
| `ios` | 可解析的 Xcode 工程/workspace 或应用型 Swift 包 | SwiftUI |
| `android` | Gradle 中存在 Android 应用模块 | Compose Material 3 |

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

| 状态 | 动作 |
|---|---|
| `implemented` | 实现真实调用、流程与完整状态 |
| `developing` | 预留页面、类型和服务边界；仅按用户要求使用明确标注的本地演示数据 |
| `unimplemented` | 预留产品空间，入口禁用、隐藏或标注“即将开放”，不发请求 |
| `unknown` | 停止该能力的网络实现，继续不依赖它的安全工作并报告缺口 |

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

## 3. 设计契约与授权

凡新增页面、改变设计系统、明显改版或创建/修改 `.pen`，先复制 [设计契约模板](assets/design-contract-template.md) 到项目内 `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 设计流程](references/pencil-design.md)。先建立 Variables 和独立令牌展示画布，暂停等待令牌审批；令牌未接受时不得设计业务页面。Pencil 是唯一视觉真源；所有 `.pen` 操作只使用 Pencil MCP。MCP、Schema 或文件不可用时设为 `blocked`，不退回整页生图或另一套视觉稿。

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

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

## 5. 实施与验收

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

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

- `web`：[build-web.md](references/build-web.md)
- `wechat-mini`：[build-wechat-mini.md](references/build-wechat-mini.md)
- `ios`：[build-ios.md](references/build-ios.md)
- `android`：[build-android.md](references/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`，除非用户在当前请求中明确授权。

模板：

```text
type(scope): 简短说明

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

## 7. 前端开发契约

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

## 8. 交付清单

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