@bovinphang/frontend-craft 2.7.0 → 2.9.0

package/localized/zh-CN/commands/fec-scaffold.md

@@ -0,0 +1,205 @@
+---
+name: fec-scaffold
+description: 按项目规范创建 page、feature 或 component 的标准目录结构和样板文件。用法：/fec-scaffold <type> <Name>，如 /fec-scaffold page UserDetail
+---
+
+按项目约定的目录结构创建新的 page、feature 或 component。
+
+## 依赖与版本
+
+若本次脚手架涉及新增或建议 `package.json` 依赖，遵循项目 `.claude/rules/fec-react.md` 或 `.claude/rules/fec-vue.md` 中「版本与依赖」约定；项目中尚无对应规则时，优先采用彼此兼容的主流稳定版本（对齐官方文档、脚手架默认值或包管理器推荐）。
+
+## 参数解析
+
+从 `$ARGUMENTS` 中解析两个参数：
+- **type**: `page` | `feature` | `component`（必填）
+- **name**: 模块名称，使用 PascalCase（必填）
+
+如果参数缺失，提示用法示例并要求用户补充：
+```
+用法：/fec-scaffold <type> <Name>
+示例：
+  /fec-scaffold page UserDetail
+  /fec-scaffold feature payment
+  /fec-scaffold component DataTable
+```
+
+## 执行步骤
+
+### 1. 检测项目框架
+
+检查 `package.json` 的 `dependencies`：
+- 包含 `react` → React 项目
+- 包含 `vue` → Vue 项目
+- 都不包含 → 提示用户手动指定
+
+### 2. 探测项目约定并确定目标路径
+
+检查 `src/`、`app/`、`pages/`、`features/`、`components/`、`__tests__/`、`tests/`、`vitest.config.*`、`jest.config.*`、`playwright.config.*` 和现有组件命名方式。优先复用项目已有目录；仅在没有现成约定时使用默认路径：
+- page → `src/pages/<Name>/`
+- feature → `src/features/<name>/`（name 转为 kebab-case）
+- component → `src/components/<Name>/`
+
+如果目标目录已存在，提示用户确认是否继续。
+
+### 3. 创建目录和文件
+
+根据框架和类型，创建以下结构：
+
+#### React page 页面
+
+```
+src/pages/<Name>/
+├── <Name>Page.tsx
+├── components/
+│   └── .gitkeep
+└── hooks/
+    └── .gitkeep
+```
+
+`<Name>Page.tsx` 内容：
+
+```tsx
+export default function <Name>Page() {
+    return (
+        <div>
+            <h1><Name></h1>
+        </div>
+    );
+}
+```
+
+#### React feature 功能模块
+
+```
+src/features/<name>/
+├── components/
+│   └── .gitkeep
+├── hooks/
+│   └── .gitkeep
+├── api.ts
+├── types.ts
+├── constants.ts
+└── index.ts
+```
+
+`index.ts` 内容：
+
+```typescript
+export * from './types';
+export * from './constants';
+```
+
+`api.ts` 内容（仅在项目已有 `src/services/request.*`、`src/lib/request.*`、`src/api/client.*` 或同类 API client 时导入对应 client；否则保持空导出，避免制造不存在的别名依赖）：
+
+```typescript
+export {};
+```
+
+`types.ts` 和 `constants.ts` 创建为空文件或最小空导出。
+
+#### React component 组件
+
+```
+src/components/<Name>/
+├── <Name>.tsx
+├── <Name>.styles.css
+└── __tests__/
+    └── <Name>.spec.tsx
+```
+
+`<Name>.tsx` 内容：
+
+```tsx
+import './<Name>.styles.css';
+
+interface <Name>Props {
+    children?: React.ReactNode;
+}
+
+export function <Name>({ children }: <Name>Props) {
+    return (
+        <div className="<name>">
+            {children}
+        </div>
+    );
+}
+```
+
+#### Vue page 页面
+
+```
+src/pages/<Name>/
+├── <Name>Page.vue
+├── components/
+│   └── .gitkeep
+└── composables/
+    └── .gitkeep
+```
+
+`<Name>Page.vue` 内容：
+
+```vue
+<script setup lang="ts">
+</script>
+
+<template>
+    <div>
+        <h1><Name></h1>
+    </div>
+</template>
+
+<style scoped>
+</style>
+```
+
+#### Vue feature 功能模块
+
+```
+src/features/<name>/
+├── components/
+│   └── .gitkeep
+├── composables/
+│   └── .gitkeep
+├── api.ts
+├── types.ts
+├── constants.ts
+└── index.ts
+```
+
+`index.ts` 内容与 React 相同。
+
+#### Vue component 组件
+
+```
+src/components/<Name>/
+├── <Name>.vue
+└── __tests__/
+    └── <Name>.spec.ts
+```
+
+`<Name>.vue` 内容：
+
+```vue
+<script setup lang="ts">
+interface Props {
+}
+
+const props = defineProps<Props>();
+</script>
+
+<template>
+    <div>
+        <slot />
+    </div>
+</template>
+
+<style scoped>
+</style>
+```
+
+### 4. 输出确认
+
+创建完成后，输出：
+- 创建的文件清单
+- 下一步建议（如"在路由配置中注册新页面"、"在 index.ts 中导出公开 API"）

package/localized/zh-CN/commands/fec-smell.md

@@ -0,0 +1,13 @@
+---
+name: fec-smell
+description: 只诊断前端代码坏味道，基于证据给出候选重构手法，不修改业务代码。
+---
+
+本命令是 **DIAGNOSE ONLY（只诊断）**。不要修改业务代码。
+
+1. 发现分析范围、项目/框架事实和当前 diff。
+2. 收集所有权、重复、变化耦合、数据流、控制流和公共边界证据。
+3. 对照 24 种坏味道并执行误判检查。
+4. 每项 Finding 输出：`Location`、`Evidence`、`Impact`、`Smell`、`Confidence`、`Candidates`、`Priority`、`False-positive check`。
+5. LOW 置信度只能作为开放问题，不能直接驱动自动修改。
+6. 保存到 `reports/refactoring/smell-YYYY-MM-DD-HHmmss.md`。

package/localized/zh-CN/commands/fec-tdd.md

@@ -0,0 +1,25 @@
+---
+name: fec-tdd
+description: 使用前端 TDD 工作流实现功能、修复 Bug 或重构逻辑：先写失败测试，再实现最小代码，再重构。
+---
+
+按 `fec-tdd-workflow` 执行测试驱动开发。
+
+## 执行步骤
+
+1. 明确要验证的前端行为。
+2. 选择最近风险的测试层：单元、组件、轻量集成或 E2E。
+3. 写最小失败测试并运行，确认失败原因正确。
+4. 写最小实现让测试通过。
+5. 保持测试通过后再重构。
+6. 总结测试命令、覆盖行为和剩余风险。
+
+## 分流
+
+- 组件和 hook 测试：`fec-component-testing`
+- 跨页浏览器流程：`fec-e2e-testing`
+- 测试分层策略：`fec-testing-strategy`
+
+## 边界
+
+本命令主要用于新增可观察行为和会改变行为的 Bug 修复。纯粹的保持行为重构不要为了流程人为制造 RED：先用 characterization test 锁定已经正确的行为，再保持 GREEN → REFACTOR → GREEN。

package/localized/zh-CN/skills/TEMPLATE.md

@@ -0,0 +1,155 @@
+# Skill 模板规范
+
+> 所有 Skill 必须遵循 agentskills 结构：目录名、frontmatter `name` 和公开 skill id 保持一致；frontmatter 只保留 `name` 与 `description`。
+
+---
+
+## 目录结构
+
+```text
+skills/fec-[主题]/
+  SKILL.md
+  references/   # 可选：按需加载的详细规范、示例或清单
+  scripts/      # 可选：需要确定性执行的脚本
+  assets/       # 可选：输出会用到的模板或资源
+```
+
+## Frontmatter 配置
+
+```yaml
+---
+name: fec-[主题]
+description: 用于 ...
+---
+```
+
+- `name` 必须等于父目录名。
+- `description` 是主要触发依据，必须写清"做什么"和"什么时候用"。
+- 不要在 frontmatter 中加入 `version`、`metadata` 或触发说明以外的字段。
+- 使用中文描述适用场景、边界和触发词，并保留必要的技术关键词。
+
+---
+
+## 模板结构
+
+```markdown
+# Skill: [Skill 名称]
+
+## 用途
+
+一句话说明这个 Skill 解决什么问题，面向什么场景。
+
+## 流程
+
+分步骤实现指南，每步包含代码示例。
+
+### 1. [步骤标题]
+
+说明 + 代码示例
+
+### 2. [步骤标题]
+
+说明 + 代码示例
+
+...
+
+## 约束
+
+- 边界条件 / 注意事项 1
+- 反模式 / 陷阱 1
+- 性能 / 安全约束 1
+
+## 预期输出
+
+明确产出物是什么，如何验证。
+
+```
+
+---
+
+## 编写规范
+
+### 用途
+
+- 一句话，不超过 30 字
+- 说明解决什么问题，而非如何解决
+- 示例: "管理表单状态、校验和提交，避免受控组件的性能问题"
+
+### 触发条件与边界
+
+- 触发条件主要写在 frontmatter `description`，正文不要再重复长篇 `When to Use`。
+- `description` 必须包含 should-trigger 场景和近邻 should-not-trigger 边界。
+- 示例：`用于构建较复杂表单，包括 React Hook Form 与 Zod 校验。不要用于没有校验的 1-3 个字段小表单。`
+
+### 能力关系
+
+- `SKILL.md` 必须自包含，不能依赖另一个 skill 或 agent 才能理解或执行。
+- 不要在 skill 正文添加 `Related Agent`。
+- 不要从 skill 正文链接到 `../agents`、`../../agents`、`../skills` 或 `../../skills`。
+- 相关 skill、边界 workflow 和能力标签统一维护在 `skills/relations.json`。
+- Agent 可以在自己的 frontmatter `skills:` 字段中引用 skills；skill 不反向引用 agent。
+
+### 流程
+
+- 按实施顺序分步骤，每步有编号和标题
+- 每个步骤包含：
+  - 1-2 句说明
+  - 可运行的代码示例（TypeScript 优先）
+  - 关键参数的注释说明
+- 涉及安装的步骤先给出安装命令
+- 代码示例遵循项目已有的编码规范
+- 优先展示完整的最小可运行示例，而非片段
+- `SKILL.md` 只保留每次使用都需要的核心流程；接近 **180-220 行**时优先拆到 `references/`。
+- 长代码、框架变体、进阶配置、评估清单放入一层 `references/` 文件，并从 `SKILL.md` 明确说明何时加载。
+
+### 约束
+
+- 列出 3-6 条关键约束
+- 包括：性能陷阱、安全注意、反模式、兼容性限制
+- 每条简洁，必要时附简短解释
+- 示例:
+  - 虚拟列表中的项目不在 DOM 中直到滚动到，搜索引擎可能无法索引
+
+### 预期输出
+
+- 明确说明产出物是什么
+- 如何验证产出是否正确
+- 1-3 句话
+
+---
+
+## 代码示例约定
+
+- 使用 TypeScript（.tsx / .ts），除非场景明确要求 JavaScript
+- 遵循 React 18+ / Vue 3+ 现代语法
+- 变量和函数名语义化，避免缩写（除非是行业约定如 `ctx`、`ref`）
+- 关键行添加行内注释说明"为什么"而非"是什么"
+- 安装命令使用 `npm install`（不锁包管理器）
+
+---
+
+## 渐进式披露
+
+- `SKILL.md`：触发后每次都需要的操作顺序、约束、边界和最小示例。
+- `references/`：按需加载的详细示例、框架变体、配置模板和长检查清单。
+- 避免把同一说明同时写在 `SKILL.md` 和 reference 中；正文只做导航。
+- reference 只放一层，链接必须使用相对路径。
+
+---
+
+## 触发评估
+
+每个 skill 维护正负样例，用于 description 优化：
+
+- `should_trigger`：8-10 条真实用户问法。
+- `should_not_trigger`：8-10 条近邻误触发问法。
+- 高重叠 skill 优先覆盖 React/Vue/Next/Nuxt、review/security/a11y、component/E2E/Storybook、legacy/migration。
+
+---
+
+## 文件命名
+
+- 目录格式: `skills/fec-{主题}/`
+- 必备文件: `skills/fec-{主题}/SKILL.md`
+- 使用小写和连字符
+- 示例: `skills/fec-storybook-component-doc/`、`skills/fec-list-virtualization/`