@bovinphang/frontend-craft 2.5.0

package/skills/fec-doc-sync/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fec-doc-sync
+description: Use when synchronizing frontend project documentation with source-of-truth files such as package.json, runtime templates, CLI commands, public skills, agents, reports, environment examples, or repository structure. Do not use for general prose polishing only; Chinese triggers include 文档同步, 更新 README, docs sync, 命令清单, 能力表同步.
+---
+
+# 文档同步
+
+## Purpose
+
+从代码、模板和元数据同步公开文档，避免 README、runtime 文档、能力表和报告说明与实际安装内容漂移。
+
+## Procedure
+
+1. 找到事实来源：
+   - `package.json`：版本、脚本、bin、files。
+   - `skills/metadata.json`、`skills/eval_queries.json`：公开 skill 清单。
+   - `agents/`、`commands/`、`templates/shared/rules/`：安装内容。
+   - `docs/project-structure.md` 和 runtime docs：分发说明。
+2. 比对文档中的数量、名称、命令、报告文件名和运行时支持矩阵。
+3. 更新所有受影响语言版本；若仓库有多语言 README，保持信息一致。
+4. 对生成型报告或示例，只更新稳定约定，不把临时报告内容写入公开文档。
+5. 若变更来自依赖升级、架构决策或公共能力调整，同步轻量 ADR、变更说明、示例 prompt 和迁移注意事项。
+6. 运行文档/元数据一致性测试或相关打包检查。
+
+## Constraints
+
+- 不把 README 变成完整实现细节；公开文档保留高信号摘要。
+- 不引入与事实来源不一致的命令、路径或能力名称。
+- 不修改用户项目私有文档，除非用户明确指定。
+- 多语言文档若无法完整翻译，至少保持数量、命令名、skill id、agent id 和报告格式一致。
+- 不把 ADR 当作长篇复盘；只记录背景、决策、取舍、影响范围、验证和回滚线索。
+
+## Expected Output
+
+- README、runtime docs、项目结构和 changelog 中的公开能力清单与代码一致。
+- 相关 metadata、marketplace 描述和测试期望同步。
+- 总结事实来源、更新范围、验证命令和仍需人工校对的翻译风险。

package/skills/fec-e2e-testing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: fec-e2e-testing
+description: Use when creating, maintaining, debugging, or reviewing real-browser end-to-end tests with Playwright or Cypress, including Page Object models, CI artifacts, traces, flaky tests, cross-page visual regression, and critical user journeys such as login, payment, permissions, or CRUD. For layer planning or tests close to UI components, choose the matching testing workflow first; Chinese triggers include E2E, 端到端测试, Playwright, Cypress.
+---
+
+# E2E 测试规范
+
+## Purpose
+
+用真实浏览器验证关键用户旅程，发现单元测试无法覆盖的集成风险。
+
+## Procedure
+
+1. 明确关键旅程：登录、购买、创建、搜索、权限、支付等跨页面流程优先；若只是选择测试层级，先做测试分层规划。
+2. 新项目优先 Playwright；已有 Cypress 项目沿用 Cypress，不为迁移而迁移。
+3. 用 Page Object 或 fixtures 封装登录、页面定位器和共享数据，spec 中避免裸选择器。
+4. 断言用户可见结果，依赖 Locator 自动等待、网络响应或可见状态，不使用固定 sleep。
+5. CI 必须上传 HTML report、截图、trace 或视频；flaky 用例要隔离、复现、标注来源并关联 issue。
+6. 调试失败时先读 trace、console、network 和截图，再改测试；不要把真实产品缺陷误判成 flaky。
+7. 对关键浏览器能力、支付、权限、上传和实时通信流程，记录测试环境、种子数据和清理策略。
+8. 测试数据必须可重复：优先使用 API seed、数据库 fixture、测试账号或 mock 服务；随机数据需带唯一前缀并在 teardown 清理。
+
+## Detailed References
+
+- Load [references/playwright-patterns.md](references/playwright-patterns.md) for directory layout, Page Object, spec structure, config, flaky debugging, and artifact examples.
+- Load [references/e2e-advanced.md](references/e2e-advanced.md) when the task needs CI examples, Markdown report templates, Web3/wallet flows, high-risk financial flows, or visual regression setup.
+
+## Constraints
+
+- 禁止依赖 `sleep` / 固定 `setTimeout` 作为主要同步手段。
+- 不在生产环境跑真实 E2E。
+- 避免在 E2E 中断言组件内部像素级样式；跨页面截图/视觉回归仅覆盖用户旅程中的关键页面状态。
+- 失败必须能靠截图、trace 或视频定位。
+- 组件内部契约测试分流到组件测试 workflow。
+- 不把不稳定等待、随机数据或依赖测试顺序带入 CI。
+- 不把重试次数当作 flaky 治理；重试只能保留证据，根因仍需定位。
+
+## Expected Output
+
+关键用户旅程有稳定 E2E 覆盖，失败产物可定位问题，CI 中报告和 trace 可下载；flaky 用例有复现命令、隔离策略和后续 issue。

package/skills/fec-e2e-testing/references/e2e-advanced.md

@@ -0,0 +1,176 @@
+# E2E 高级测试细节
+
+## CI 集成（示例）
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npx playwright test
+        env:
+          CI: true
+          BASE_URL: ${{ vars.STAGING_URL }}
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+Cypress：固定 `CYPRESS_baseUrl` 或配置文件中的 `baseUrl`，失败截图/视频同样建议上传 artifact。
+
+## E2E 报告模板（Markdown）
+
+输出或归档测试报告时可采用下列结构，便于复盘：
+
+```markdown
+# E2E 测试报告
+
+**日期：** YYYY-MM-DD HH:mm  
+**耗时：** X 分 Y 秒  
+**结果：** 通过 / 失败
+
+## 摘要
+
+- 总计 X | 通过 Y | 失败 Z | 不稳定/跳过 说明
+
+## 失败用例
+
+### 用例名
+
+- **文件：** `tests/e2e/xxx.spec.ts:行号`
+- **错误：** 简述断言或超时信息
+- **截图/Trace：** 路径或 artifact 名称
+- **建议修复：** 可执行结论
+
+## 产物
+
+- HTML 报告：`playwright-report/index.html`
+- Trace / 视频 / 截图：CI artifact 或本地 `test-results/`
+```
+
+## 特殊场景（按需）
+
+### Web3 / 钱包注入（Playwright）
+
+在 **`page.goto` 之前**通过 `context.addInitScript` 注入 mock，避免依赖真实插件：
+
+```typescript
+test("连接钱包", async ({ page, context }) => {
+  await context.addInitScript(() => {
+    (window as unknown as { ethereum?: unknown }).ethereum = {
+      isMetaMask: true,
+      request: async ({ method }: { method: string }) => {
+        if (method === "eth_requestAccounts")
+          return ["0x1234567890123456789012345678901234567890"];
+        if (method === "eth_chainId") return "0x1";
+        return null;
+      },
+    };
+  });
+
+  await page.goto("/");
+  await page.getByTestId("connect-wallet").click();
+  await expect(page.getByTestId("wallet-address")).toContainText("0x1234");
+});
+```
+
+链 ID、账户列表与业务契约保持一致即可。
+
+### 金融或高风险操作
+
+- **禁止**在真实生产环境执行真实资金操作；使用 **staging、mock 或 `test.skip`**。
+- 断言**预览金额、成功态**与**关键接口 200** 后再结束用例，超时给足（如链上确认场景）。
+
+```typescript
+test("下单预览与成功态", async ({ page }) => {
+  test.skip(process.env.NODE_ENV === "production", "生产环境跳过真实交易");
+
+  await page.goto("/markets/demo");
+  await page.getByTestId("position-yes").click();
+  await page.getByTestId("trade-amount").fill("1.0");
+
+  const preview = page.getByTestId("trade-preview");
+  await expect(preview).toContainText("1.0");
+
+  await page.getByTestId("confirm-trade").click();
+  await page.waitForResponse(
+    (resp) => resp.url().includes("/api/trade") && resp.status() === 200,
+    { timeout: 30_000 },
+  );
+  await expect(page.getByTestId("trade-success")).toBeVisible();
+});
+```
+
+## 视觉回归测试
+
+通过截图快照对比检测非预期的 UI 变化。适用于 CSS 重构、设计 Token 更新、组件改版等场景。
+
+### 基础用法
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("首页布局与基线一致", async ({ page }) => {
+  await page.goto("/");
+  await page.waitForLoadState("networkidle");
+
+  // 全页截图对比 — 首次运行自动生成基线
+  await expect(page).toHaveScreenshot("homepage-full.png", {
+    fullPage: true,
+    maxDiffPixels: 100, // 允许的轻微像素差异（抗锯齿等）
+  });
+});
+
+test("按钮组件视觉一致", async ({ page }) => {
+  await page.goto("/components/buttons");
+  const submitButton = page.getByTestId("submit-button");
+  await expect(submitButton).toHaveScreenshot("submit-button.png");
+});
+```
+
+### 屏蔽动态内容
+
+时间、随机 ID、第三方广告等动态元素会导致误报，使用 `mask` 屏蔽：
+
+```typescript
+await expect(page).toHaveScreenshot("dashboard.png", {
+  mask: [
+    page.locator(".live-clock"),
+    page.locator(".random-id"),
+    page.locator(".ad-banner"),
+  ],
+});
+```
+
+### 禁用动画
+
+CSS 动画会导致截图不一致，注入样式禁用动画后再截图：
+
+```typescript
+await page.addStyleTag({
+  content:
+    "*, *::before, *::after { animation-duration: 0s !important; transition-duration: 0s !important; }",
+});
+await expect(page).toHaveScreenshot("animated-page.png");
+```
+
+### 基线管理
+
+- **首次运行**: `npx playwright test` 失败但自动生成基线到 `tests/` 目录
+- **更新基线**: UI 有意变更时 `npx playwright test --update-snapshots`
+- **CI 一致性**: 基线必须在与 CI 相同的 OS（Linux/Ubuntu）上生成，字体渲染在 macOS 与 Linux 间存在差异
+- **多浏览器**: 每个 project 独立生成基线（Chromium/Firefox/WebKit 渲染结果不同）
+- **基线文件**: 纳入 `.gitignore` 或 Git LFS 管理，避免仓库膨胀

package/skills/fec-e2e-testing/references/playwright-patterns.md

@@ -0,0 +1,95 @@
+# Playwright / Cypress E2E 模式
+
+## 目录结构
+
+```text
+tests/
+├── e2e/
+│   ├── auth/login.spec.ts
+│   └── features/search.spec.ts
+├── fixtures/
+│   └── auth.ts
+└── pages/
+    ├── LoginPage.ts
+    └── ItemsPage.ts
+playwright.config.ts
+```
+
+## Page Object
+
+```ts
+import { type Locator, type Page } from "@playwright/test";
+
+export class ItemsPage {
+  readonly searchInput: Locator;
+  readonly itemCards: Locator;
+
+  constructor(private readonly page: Page) {
+    this.searchInput = page.getByTestId("search-input");
+    this.itemCards = page.getByTestId("item-card");
+  }
+
+  async goto() {
+    await this.page.goto("/items");
+  }
+
+  async search(keyword: string) {
+    await this.searchInput.fill(keyword);
+    await this.page.waitForResponse((response) => response.url().includes("/api/search"));
+  }
+}
+```
+
+## Spec
+
+```ts
+import { expect, test } from "@playwright/test";
+import { ItemsPage } from "../pages/ItemsPage";
+
+test.describe("商品搜索", () => {
+  test("按关键词搜索有结果", async ({ page }) => {
+    const itemsPage = new ItemsPage(page);
+    await itemsPage.goto();
+    await itemsPage.search("test");
+    await expect(itemsPage.itemCards.first()).toContainText(/test/i);
+  });
+});
+```
+
+## Config
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "./tests/e2e",
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: [["html"], ["junit", { outputFile: "playwright-results.xml" }]],
+  use: {
+    baseURL: process.env.BASE_URL || "http://localhost:3000",
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+    video: "retain-on-failure",
+  },
+  projects: [
+    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
+  ],
+  webServer: {
+    command: "npm run dev",
+    url: "http://localhost:3000",
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## Flaky 调试
+
+```bash
+npx playwright test path/to/spec.ts --repeat-each=10
+npx playwright test path/to/spec.ts --retries=3
+npx playwright show-trace path/to/trace.zip
+```
+
+常见原因：竞态、网络时序、动画、测试数据污染、跨测试状态泄露。

package/skills/fec-form-handling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: fec-form-handling
+description: Use when building or reviewing substantial forms with React Hook Form, Zod schemas, typed validation, dynamic fields, controlled third-party inputs, file upload, multi-step flows, dependent validation, or form performance. Do not use for trivial 1-3 field forms without validation; Chinese triggers include 表单, 表单校验, 动态字段.
+---
+
+# 表单处理
+
+## Purpose
+
+管理表单状态、校验和提交，避免复杂表单输入卡顿。
+
+## Procedure
+
+1. 先判断复杂度：10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时使用 React Hook Form + Zod；极简表单可用原生受控组件。
+2. 用 Zod 定义运行时 schema，并用 `z.infer` 推导 TypeScript 类型；schema 是外部输入边界，不要只写 TS 类型。
+3. `useForm` 必须提供 `defaultValues`，通过 `zodResolver` 统一校验；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
+4. 第三方受控组件用 `Controller`，原生 input 优先 `register`；不要混用两套状态源。
+5. 提交时处理 loading、服务端错误、重复提交和 reset；大型表单用局部订阅和子组件隔离控制重渲染。
+
+## Quick Start
+
+```tsx
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+
+const loginSchema = z.object({
+  email: z.string().email("请输入有效的邮箱地址"),
+  password: z.string().min(8, "密码至少 8 个字符"),
+});
+
+type LoginForm = z.infer<typeof loginSchema>;
+
+export function LoginFormView() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<LoginForm>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: { email: "", password: "" },
+  });
+
+  return (
+    <form onSubmit={handleSubmit((data) => api.login(data))} noValidate>
+      <label htmlFor="email">邮箱</label>
+      <input id="email" {...register("email")} aria-invalid={!!errors.email} />
+      {errors.email && <span role="alert">{errors.email.message}</span>}
+
+      <label htmlFor="password">密码</label>
+      <input id="password" type="password" {...register("password")} />
+      {errors.password && <span role="alert">{errors.password.message}</span>}
+
+      <button disabled={isSubmitting}>
+        {isSubmitting ? "提交中..." : "提交"}
+      </button>
+    </form>
+  );
+}
+```
+
+## Detailed References
+
+涉及 `Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
+
+## Constraints
+
+- React Hook Form 默认非受控；只有第三方受控组件才用 `Controller`。
+- `defaultValues` 必须完整，避免 undefined 触发受控/非受控警告。
+- `reset()` 应传服务器返回或明确的完整默认对象。
+- 异步校验必须 debounce 或放到提交边界，避免每次键入请求。
+- Zod `refine` / `superRefine` 的 `path` 必须指向实际字段。
+
+## Expected Output
+
+产出类型安全、可访问、提交状态明确的表单；复杂字段和文件上传有 schema 约束，输入过程无明显卡顿，服务端错误能回填到用户可理解的位置。

package/skills/fec-form-handling/references/advanced-form-patterns.md

@@ -0,0 +1,72 @@
+# 高级表单模式
+
+## Controller
+
+```tsx
+<Controller
+  name="role"
+  control={control}
+  rules={{ required: "请选择角色" }}
+  render={({ field, fieldState }) => (
+    <>
+      <Select {...field} options={roleOptions} />
+      {fieldState.error && <span role="alert">{fieldState.error.message}</span>}
+    </>
+  )}
+/>
+```
+
+用于不暴露原生 `ref` 的 Select、DatePicker、RichEditor 等组件。
+
+## 动态字段
+
+```tsx
+const { fields, append, remove } = useFieldArray({
+  control,
+  name: "contacts",
+});
+
+{fields.map((field, index) => (
+  <div key={field.id}>
+    <input {...register(`contacts.${index}.name`)} />
+    <button type="button" onClick={() => remove(index)}>删除</button>
+  </div>
+))}
+```
+
+`key` 必须使用 `field.id`，不要使用数组 index。
+
+## 联动校验
+
+```ts
+const schema = z
+  .object({
+    password: z.string().min(8),
+    confirmPassword: z.string().min(8),
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: "两次密码不一致",
+    path: ["confirmPassword"],
+  });
+```
+
+## 文件上传
+
+```ts
+const schema = z.object({
+  avatar: z
+    .instanceof(FileList)
+    .refine((files) => files.length > 0, "请上传头像")
+    .refine((files) => files[0]?.size <= 5 * 1024 * 1024, "文件大小不超过 5MB")
+    .refine((files) => ["image/jpeg", "image/png"].includes(files[0]?.type), "仅支持 JPG/PNG"),
+});
+```
+
+提交时用 `FormData`，不要把 `File` JSON 序列化。
+
+## 性能
+
+- 用 `useWatch` 或字段级订阅替代全表单 watch。
+- 大表单拆成 memoized 子组件。
+- 高频输入不要每次键入触发网络校验。
+- 多步表单要明确每步 schema 和跨步最终 schema。

package/skills/fec-implement-from-design/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: fec-implement-from-design
+description: Use when implementing UI from Figma, Sketch, MasterGo, Pixso, Modao, MockingBot, screenshots, design selections, design tokens, or design-to-code tasks for production frontend components/pages; Chinese triggers include 设计稿, 按设计实现.
+---
+
+# 按设计稿实现
+
+## Purpose
+
+基于设计工具（Figma、Sketch、MasterGo、Pixso、墨刀、摹客）的设计上下文，高保真实现页面或组件，强调组件复用、设计 Token 映射、可访问性和面向生产的前端实现。
+
+## 支持的设计工具
+
+| 工具     | MCP 集成                  | 获取设计数据方式                          |
+| -------- | ------------------------- | ----------------------------------------- |
+| Figma    | `figma` / `figma-desktop` | API 获取设计结构、变量定义                |
+| Sketch   | `sketch`                  | MCP 获取设计选区截图                      |
+| MasterGo | `mastergo`                | API 获取 DSL 结构数据                     |
+| Pixso    | `pixso`                   | 本地 MCP 获取帧数据和代码                 |
+| 墨刀     | `modao`                   | MCP 获取原型数据、生成设计描述            |
+| 摹客     | 无 MCP                    | 通过用户提供的截图、标注或导出的 CSS 获取 |
+
+## 目标
+
+- 尽量高还原地实现设计稿
+- 在创建新组件前优先复用现有项目组件
+- 尽可能把设计变量映射到现有 Token
+- 保持实现结果可维护、类型明确、可测试且具备可访问性
+- 避免引入重复的基础组件或并行设计系统
+
+## 必需工作流
+
+### 1. 识别设计来源
+
+按优先级选择设计数据获取方式：
+
+- `figma` — Figma API 集成
+- `figma-desktop` — Figma 桌面端集成
+- `mastergo` — MasterGo DSL 数据
+- `pixso` — Pixso 本地 MCP
+- `modao` — 墨刀原型数据
+- `sketch` — Sketch 选区截图
+- 如以上 MCP 均不可用，请求用户提供设计截图或标注（适用于摹客等无 MCP 工具）
+
+### 2. 读取设计上下文
+
+通过 MCP 或用户提供的设计数据读取设计上下文：
+
+- 检查布局结构
+- 检查间距、字体、颜色、变量、状态、图标和组件层级
+- 如果 MCP 提供了资源文件或 SVG / 图片源，直接使用
+- 如果 MCP 已提供真实资源，不要自行造占位资源
+- 如果用户提供截图而非 MCP 数据，从截图中推断布局、颜色、字体等视觉信息
+
+### 3. 搜索可复用组件
+
+在创建新组件前先搜索代码库中的可复用组件，重点检查：
+
+- Button
+- Input / Select / Checkbox / Radio / Switch
+- Modal / Drawer / Dialog
+- Table / List / Card
+- Tabs / Breadcrumb / Pagination
+- 页面容器 / 区块容器 / 空状态 / Loading 状态
+
+### 4. 产出实现计划
+
+在改文件前先产出一份简短实现计划，计划必须包含：
+
+- 需要改动的文件列表
+- 组件拆分方案
+- 状态 / 数据流
+- 响应式行为
+- 复用还是新建的决策
+- 设计缺口或歧义点
+
+### 5. 按框架实现
+
+按仓库当前使用的前端框架进行实现：
+
+- 严格遵循仓库现有约定
+- 优先使用明确类型的 props 和 interfaces/types
+- 保持组件小而可组合
+- 将重复逻辑提取为 hooks / composables / utilities
+
+### 6. 设计 Token 映射
+
+- 优先使用现有 design token、CSS 变量、主题变量或工具类
+- 除非确实没有对应 Token，否则不要硬编码颜色、圆角和间距
+- 如果设计使用了新 Token，要明确指出，不要悄悄到处硬编码
+
+### 7. 可访问性保障
+
+- 优先使用语义化 HTML
+- 确保交互控件具有可访问名称
+- 保留可见的焦点样式
+- 检查对话框、菜单、标签页、表单控件的键盘可操作性
+
+### 8. 编码后验证
+
+- 如有 lint，执行 lint
+- 如有测试，执行测试
+- 如果缺少测试，说明建议补充的最小测试范围
+
+## Detailed References
+
+撰写实现计划报告时，加载 [references/design-plan-template.md](references/design-plan-template.md)。
+
+## Constraints
+
+- 如果已有设计上下文（MCP 或截图），不要靠猜来实现 UI
+- 如果项目已有 UI 体系，不要再引入一套新的 UI Kit
+- 除非有合理理由，不要用硬编码替代已 Token 化的样式
+- 不要忽略 hover、active、disabled、loading、empty、error 等状态
+- 摹客等无 MCP 工具场景下，主动向用户索要关键截图和标注信息，不要凭空编造视觉数据
+
+## Expected Output
+
+- 设计实现计划报告保存为 `reports/design-plan-YYYY-MM-DD-HHmmss.md`，包含实现概要、组件拆分方案、状态/数据流、变更文件清单
+- 代码实现高保真还原设计稿，组件复用率最大化
+- 设计变量映射到现有 Token，无硬编码颜色/间距/圆角
+- 交互元素具备可访问名称和键盘支持，焦点样式可见

package/skills/fec-implement-from-design/references/design-plan-template.md

@@ -0,0 +1,36 @@
+# 设计实现计划模板
+
+```markdown
+# 设计实现计划
+
+> 生成时间: YYYY-MM-DD HH:mm
+> 评审工具: frontend-craft
+> 设计工具: Figma / Sketch / MasterGo / Pixso / 墨刀 / 摹客
+
+## 实现概要
+- 设计稿来源: ...
+- 目标页面/组件: ...
+
+## 复用的组件
+- ...
+
+## 新建的组件
+- ...
+
+## 组件拆分方案
+- ...
+
+## 状态/数据流
+- ...
+
+## 与设计稿的偏差
+- ...
+
+## 缺失的资源 / Token / 交互细节
+- ...
+
+## 变更文件清单
+- ...
+```
+
+实现计划确定后，将报告保存到 `reports/design-plan-YYYY-MM-DD-HHmmss.md`，并告知用户报告路径。