@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/localized/zh-CN/skills/fec-e2e-testing/references/e2e-visual-regression.md

@@ -0,0 +1,60 @@
+# E2E 视觉回归测试
+
+通过截图快照对比检测非预期的 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/localized/zh-CN/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);
+  });
+});
+```
+
+## 配置
+
+```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/localized/zh-CN/skills/fec-form-handling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: fec-form-handling
+description: 用于构建或审查较复杂表单，包括 React Hook Form、Zod schema、类型化校验、动态字段、受控第三方输入、文件上传、多步骤流程、依赖校验或表单性能。不要用于没有校验的 1-3 个字段小表单；中文触发词包括 表单、表单校验、动态字段。
+---
+
+# 表单处理
+
+## 用途
+
+管理表单状态、校验和提交，避免复杂表单输入卡顿。
+
+## 流程
+
+1. 先识别框架、项目既有表单库、schema 校验库、组件库和复杂度；10+ 字段、动态字段、联动校验、文件上传、多步流程或输入卡顿时再引入专门表单方案。
+2. 按项目栈选型：React 可考虑 React Hook Form + Zod；Vue 可考虑 vee-validate / FormKit + Zod、Yup 或 Valibot；简单表单可用框架原生状态和基础校验。
+3. 用运行时 schema 或明确校验函数守住外部输入边界；TypeScript 类型可从 schema 推导，但不要只写 TS 类型。
+4. 明确默认值、字段注册、受控/非受控边界和组件库适配；错误提示用 `aria-invalid`、`aria-describedby` 和 `role="alert"`。
+5. 提交时处理 loading、服务端错误、重复提交和 reset；大型表单用局部订阅和子组件隔离控制重渲染。
+
+## React 快速开始
+
+```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>
+  );
+}
+```
+
+## 详细参考
+
+涉及是否需要表单库、框架选型、`Controller`、`useFieldArray`、联动校验、文件上传、多步表单、异步校验和性能模式时，加载 [references/advanced-form-patterns.md](references/advanced-form-patterns.md)。
+
+## 约束
+
+- 沿用仓库既有表单库、schema 库和组件库适配方式，不为单个表单引入第二套体系。
+- 默认值必须完整，避免 undefined 触发受控/非受控警告或初始化抖动。
+- reset 应传服务器返回或明确的完整默认对象。
+- 异步校验必须 debounce 或放到提交边界，避免每次键入请求。
+- schema 级联动校验的错误 path 必须指向实际字段。
+
+## 预期输出
+
+产出类型安全、可访问、提交状态明确的表单；复杂字段和文件上传有 schema 约束，输入过程无明显卡顿，服务端错误能回填到用户可理解的位置。

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

@@ -0,0 +1,101 @@
+# 高级表单模式
+
+## 先判断是否需要表单库
+
+- 1-3 个字段、无复杂校验、无动态字段、无组件库适配压力的表单，可用框架原生状态、浏览器约束校验和轻量提交状态。
+- 需要动态字段、跨字段校验、多步流程、文件上传、异步校验、服务端错误回填或明显输入卡顿时，再引入专门表单方案。
+- 表单库只管理字段状态和校验流程，不替代 API 错误映射、权限判断、可访问性标注或服务端最终校验。
+
+## 选型参考
+
+先沿用项目已有表单库、schema 库和组件库适配方式；新增依赖时再按场景选择。
+
+| 场景 | 候选方案 | 注意点 |
+| --- | --- | --- |
+| React 复杂表单 | React Hook Form + Zod | 非受控优先，第三方受控组件用 `Controller`。 |
+| Vue 复杂表单 | vee-validate / FormKit + Zod、Yup 或 Valibot | 不要为 Vue 项目引入 React-only 表单 API；优先沿用项目既有 Vue 表单库。 |
+| 简单表单 | 框架原生状态 + 基础校验 | 避免为了 1-3 个字段引入重型表单体系。 |
+| 多步表单 | 分步 schema + 最终提交 schema | 明确跨步数据保存、返回上一步和最终校验策略。 |
+| 文件上传 | 表单库字段状态 + `FormData` | 校验文件数量、大小、类型；不要把 `File` JSON 序列化。 |
+| 异步校验 | 提交边界校验或 debounce 字段校验 | 避免每次键入请求；处理竞态和旧响应覆盖。 |
+
+## 通用实现原则
+
+- 运行时 schema 或校验函数负责外部输入边界；TypeScript 类型不能替代运行时校验。
+- 默认值、reset 数据和服务端回填数据要形状一致，避免字段在受控/非受控之间切换。
+- 字段错误要能映射到具体字段；全局错误用于提交失败、权限或服务不可用等非字段问题。
+- 组件库适配层要透传 value、onChange、onBlur、name/ref 或等价字段注册能力。
+- 提交时保护 loading、重复提交、取消/过期请求、服务端错误回填和成功后 reset。
+- 文件上传使用 `FormData` 或直传流程，前端校验只做体验保护，服务端仍需最终校验。
+- 性能优化优先使用字段级订阅、局部组件拆分和延迟校验，不要全表单 watch 后驱动整页重渲染。
+
+## React Hook Form 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 等组件。
+
+## React Hook Form 动态字段
+
+```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。
+
+## Zod 联动校验
+
+```ts
+const schema = z
+  .object({
+    password: z.string().min(8),
+    confirmPassword: z.string().min(8),
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: "两次密码不一致",
+    path: ["confirmPassword"],
+  });
+```
+
+## Zod 文件上传校验
+
+```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/localized/zh-CN/skills/fec-image-generation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: fec-image-generation
+description: 用于生成或编辑图表、图形资产、海报、UI 样机、产品图、信息图、学术图、漫画、头像、分镜、品牌板或图像编辑工作流，尤其是导出 PNG 需要视觉质检和有限自动修复时。文字密集图表优先使用确定性的 Mermaid/SVG/HTML/canvas 源；浏览器可打开的技术图优先使用 HTML technical diagrams，覆盖系统蓝图、架构图、部署拓扑、Agent runtime、memory flow、before-after architecture、流程、序列、数据流、生命周期、runbook、PII/数据血缘和状态机；不要用于不涉及生成图像的普通 UI 打磨。中文触发词包括 图片生成、图像编辑、图表生成、架构图、系统蓝图、部署拓扑、Agent runtime、memory flow、before-after architecture、工作流图、数据流、生命周期图、状态机、ER 图、UML、序列图、海报、UI 样机、产品图、信息图、学术图、漫画、头像、分镜、品牌板、PNG 自检、自动修复。
+---
+
+# 图片生成与图表工作流
+
+## 用途
+
+生成或编辑图表、视觉资产和图片工作流，并对导出的 PNG 做可复查的自检与修复迭代。
+
+## 流程
+
+1. 判断产物类型
+   - 文本、结构和连线准确性优先时，用 Mermaid、SVG、HTML/CSS、canvas 或图表库生成可编辑源，再导出 PNG。
+   - 需要单文件浏览器打开、暗/亮主题和结构化 QA 的系统蓝图、架构图、部署拓扑、Agent runtime、memory flow、before-after architecture、流程、序列、数据流、生命周期、runbook、状态机或 PII/数据血缘图时，使用 HTML technical diagrams。
+   - 流程地图、审批流、自动化运行、异常路径和循环运营流需要清晰的起止节点、决策、参与者、步骤编号和摘要，但不需要 diagrams.net 时，使用 HTML `workflow` 路线。
+   - 系统、Agent、memory、数据或 tool-call 图需要语义节点形状、有含义的连线和可浏览器打开、可导出、可 QA 的源文件时，使用主题化 HTML technical diagrams。
+   - 用户需要在本地浏览器里看到节点和连线实时出现，或需要在会话中拖拽、改标签、删除、缩放并快速导出草图时，使用交互式实时图表路线。
+   - 审美、质感、照片、插画、漫画、产品图或品牌氛围优先时，用图片生成或编辑工具，再把最终资产保存到项目或报告目录。
+
+2. 明确输入与约束
+   - 收集受众、用途、尺寸、语言、必须出现的文本、品牌限制、可编辑源格式、导出格式和禁用元素。
+   - 对海报、UI 样机、品牌板和产品图，先写出一行视觉读取：目标用户、场景、可信感来源、主视觉锚点。
+
+3. 选择生成路线
+   - ER 图、UML 类图、序列图、技术架构图、ML/深度学习、流程图等，优先按 [diagram-workflows.md](references/diagram-workflows.md) 建立结构化源。
+   - 浏览器可打开的系统蓝图、架构、流程、序列、数据流和生命周期图，先读 [html-technical-diagrams.md](references/html-technical-diagrams.md)，再用 [tech-diagram-render.mjs](scripts/tech-diagram-render.mjs) 渲染 JSON IR。流程工作流用 `lanes` 表达参与方，用 `nodes` 表达有序动作，用 `edges` 表达异常或回环路径，并可添加 `waypoints`：
+     ```bash
+     node skills/fec-image-generation/scripts/tech-diagram-render.mjs --input diagram.json --output diagram.html --type architecture --manifest diagram.layout.json
+     ```
+   - Agent 和 memory 图优先使用 `architecture` IR，并使用 `agent`、`model`、`memory`、`vectorstore`、`graphdb`、`tool`、`document`、`queue`、`browser`、`user`、`gateway` 等语义节点类型。连线含义重要时添加 `flow`：`control`、`data`、`read`、`write`、`async`、`feedback`；出现两种以上 flow 时自动生成 flow legend。
+   - 需要源文件级主题方向时可添加 `visual.style`：`default`、`terminal`、`blueprint`、`minimal`、`glass`、`warm`、`openai` 或 `editorial-dark`。这些是交付主题，不等同于品牌规范承诺。
+   - 需要从生成好的 HTML/SVG 源导出适合 README 的 SVG、PNG、JPG 或 JPEG 交付物时，使用 [export-diagram.mjs](scripts/export-diagram.mjs)：
+     ```bash
+     node skills/fec-image-generation/scripts/export-diagram.mjs --input diagram.html --format svg
+     node skills/fec-image-generation/scripts/export-diagram.mjs --input diagram.html --format png --output diagram.png --scale 2
+     ```
+   - 实时交互草图使用 [interactive-diagram-server.mjs](scripts/interactive-diagram-server.mjs)，打开服务提供的 [interactive-diagram.html](assets/interactive-diagram.html) 页面并带上唯一 `?s=session-id`，再向 `/cmd?s=session-id` 发送小 JSON 命令：
+     ```bash
+     node skills/fec-image-generation/scripts/interactive-diagram-server.mjs --port 6100
+     curl -s "http://127.0.0.1:6100/cmd?s=checkout-flow" -d '{"cmd":"init","title":"Checkout Flow","direction":"TB"}'
+     curl -s "http://127.0.0.1:6100/cmd?s=checkout-flow" -d '{"cmd":"node","id":"cart","label":"Review cart","type":"process"}'
+     ```
+   - 海报、UI 样机、产品图、信息图、学术图、漫画、头像、分镜、品牌板和图像编辑，按 [artifact-routing.md](references/artifact-routing.md) 选择生成、编辑或混合路线。
+
+4. 导出并自检 PNG
+   - 每次交付前都读取导出的 PNG，检查主体是否真实渲染、文字是否截断、连线是否堆叠、节点是否重叠。
+   - 有布局 manifest 时运行：
+     ```bash
+     node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --manifest layout.json --format markdown
+     ```
+   - 没有 manifest 时仍运行 PNG 基础检查：
+     ```bash
+     node skills/fec-image-generation/scripts/png-qa.mjs --png output.png --format json
+     ```
+
+5. 自动修复循环
+   - 默认最多 2 轮；用户明确要求时可提高到 5 轮软上限。
+   - 修复对象是源文件、prompt、布局参数或导出尺寸，不直接破坏性修改 PNG 像素。
+   - 按 [png-qa-autofix.md](references/png-qa-autofix.md) 把问题转成具体修复：增大画布、换行、移动节点、分层连线、调整 padding 或重导出。
+
+6. 交付记录
+   - 说明最终源文件、PNG 路径、生成路线、QA 轮次、发现并修复的问题、仍需人工确认的文字或品牌风险。
+
+## 约束
+
+- 文本密集图不要只靠位图模型生成；必须保留可编辑结构化源。
+- HTML 技术图必须保留 JSON 源和生成的 HTML；PNG/SVG/JPG 是交付产物，不是事实源。需要官方厂商图标或长期手工编辑时，改用 `.drawio` 路线。
+- 主题化语义图由 Frontend Craft 渲染器实现。不要把 Python、shell、cairosvg、rsvg-convert、Puppeteer、CDN 截图库、复制来的 SVG 模板或外部图标包作为这一路线的必需依赖。
+- 交互式实时图表是会话期预览；当图表成为交付物时要保存 JSON/SVG/PNG 导出，需要长期维护事实源时改用 HTML technical diagrams 或 `.drawio`。
+- 不把截图、假数据或占位图当成最终产品图，除非用户明确要求概念稿。
+- 不直接覆盖原图；编辑工作流默认输出新文件。
+- 不为追求美观牺牲可读标签、连线归属、图例、坐标轴和可访问替代说明。
+- PNG helper 只做检测和建议；修复必须回到源、prompt 或布局参数。
+- 自检结果不能替代人工确认专有名词、公式、论文图注、品牌规范和合规信息。
+
+## 预期输出
+
+产出可编辑源、最终 PNG 或编辑后图片，并附带生成路线与 QA 结果。图表应结构清晰、标签不截断、连线不混乱；视觉资产应匹配用途、尺寸、品牌语气和交付路径。