page-best-practice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

页面生成器 (Page Generator Skill)

Page Generator Skill

任务目标

Task Objectives

本 Skill 用于：在
```
apps/web/src/pages
```
目录下快速生成符合项目架构规范的新页面。
核心理念：架构先行。先生成符合规范的代码骨架（脚手架），再由开发者或 AI 填充业务逻辑。

This Skill is used to: Quickly generate new pages that comply with project architecture specifications in the
```
apps/web/src/pages
```
directory.
Core Philosophy: Architecture First. Generate code skeletons (scaffolds) that comply with specifications first, then let developers or AI fill in business logic.

工作原理

Working Principle

分析页面需求，确定UI复杂度和状态管理需求
严格参照 best-practice-examples/ 中的代码结构和模式
根据UI复杂度生成相应的Content组件
如果需要Store，判断是生成新Store还是使用现有Store；如果生成新Store，使用store-best-practice技能生成Store模块
创建Wrapper组件处理依赖注入
实现Index文件提供干净的导出接口
在应用程序中注册路由并使用生成的页面

触发条件：当用户要求“创建新页面”、“增加路由页面”或“生成页面脚手架”时。

Analyze page requirements, determine UI complexity and state management needs
Strictly follow the code structure and patterns in best-practice-examples/
Generate corresponding Content components based on UI complexity
If a Store is needed, determine whether to generate a new Store or use an existing one; if generating a new Store, use the store-best-practice skill to generate the Store module
Create a Wrapper component to handle dependency injection
Implement an Index file to provide a clean export interface
Register the route in the application and use the generated page

Trigger Conditions: When the user requests "create new page", "add route page" or "generate page scaffold".

生成模式 (Generation Modes)

Generation Modes

本 Skill 支持两种生成模式，用户可在开始时选择：

This Skill supports two generation modes, which users can select at the start:

无监督生成 (Unsupervised)

Unsupervised Generation

适用场景：Anatomy 规范足够完备，AI 可自动推导完整结构。
特点：全自动运行，无需人工干预。
流程：直接使用 judgeHasStore.ts 的逻辑判断所有选项，生成完整结构。

Applicable Scenarios: The Anatomy specification is sufficiently complete, and AI can automatically deduce the complete structure.
Features: Fully automated operation, no manual intervention required.
Process: Directly use the logic of judgeHasStore.ts to judge all options and generate the complete structure.

有监督生成 (Supervised)

Supervised Generation

适用场景：存在选项判断的不确定性，需要人工确认。
特点：在关键节点（如是否需要 Store）提问确认，AI 提供推荐但由用户决策。
流程：使用 judgeHasStore.ts 的逻辑判断提供推荐值，提问用户确认是否采纳。

Applicable Scenarios: There is uncertainty in option judgment, requiring manual confirmation.
Features: Ask for confirmation at key nodes (such as whether a Store is needed), AI provides recommendations but the user makes the decision.
Process: Use the logic of judgeHasStore.ts to provide recommended values, then ask the user to confirm whether to adopt them.

主动模式选择 (Active Mode Selection)

Active Mode Selection

重要行为要求：本技能必须在开始任何生成工作前主动询问用户选择生成模式。

Important Behavioral Requirement: This skill must proactively ask the user to select a generation mode before starting any generation work.

询问时机

Inquiry Timing

触发条件：当用户请求创建新页面时
询问位置：在所有分析和判断之前
强制要求：不能跳过此步骤或默认选择模式

Trigger Condition: When the user requests to create a new page
Inquiry Position: Before all analysis and judgment
Mandatory Requirement: This step cannot be skipped or a mode selected by default

选择界面

Selection Interface

提供清晰的选择界面，包含：

模式名称：无监督生成 / 有监督生成
简要描述：每种模式的特点和适用场景
推荐建议：基于页面复杂度的智能推荐（可选）

Provide a clear selection interface including:

Mode Name: Unsupervised Generation / Supervised Generation
Brief Description: Features and applicable scenarios of each mode
Recommendation Suggestion: Intelligent recommendation based on page complexity (optional)

用户决策

User Decision

等待确认：必须等待用户明确选择后再继续
不可跳过：如果用户未选择，不得继续执行
可取消：允许用户取消操作

Wait for Confirmation: Must wait for the user's clear selection before proceeding
Cannot Skip: If the user does not select, do not continue execution
Cancellable: Allow users to cancel the operation

UI 复杂度控制 (UI Complexity Control)

UI Complexity Control

复杂度等级

Complexity Levels

简单模式 (Simple): 基础布局 + 基础组件，适合展示型页面
标准模式 (Standard): 搜索/过滤 + 列表展示，适合数据管理页面
复杂模式 (Complex): 多标签页 + 高级交互，适合功能丰富的页面

Simple Mode: Basic layout + basic components, suitable for display-type pages
Standard Mode: Search/filter + list display, suitable for data management pages
Complex Mode: Multiple tabs + advanced interactions, suitable for feature-rich pages

功能适配原则

Function Adaptation Principles

基于需求生成: 根据页面实际需求选择合适的UI复杂度
避免过度设计: 不要添加用户不需要的功能
保持一致性: 遵循现有页面的设计模式和交互方式

Generate Based on Requirements: Select the appropriate UI complexity according to the actual page requirements
Avoid Over-Design: Do not add functions that users do not need
Maintain Consistency: Follow the design patterns and interaction methods of existing pages

复杂度判断逻辑

Complexity Judgment Logic

使用 judgeUIComplexity.ts 智能判断UI复杂度等级
基于页面名称、描述和功能需求自动推导
支持手动指定复杂度覆盖自动判断

Use judgeUIComplexity.ts to intelligently judge the UI complexity level
Automatically deduce based on page name, description and functional requirements
Support manual specification of complexity to override automatic judgment

使用方法

Usage Methods

此技能提供文档和示例。按照参考指南中的步骤操作：

页面最佳实践指南 - 页面设计和实现的详细规则
最佳实践示例 - 必须严格参照的 页面结构和代码示例
- standard-with-store/ - 带Store的标准复杂度页面示例
- simple-no-store/ - 无Store的简单复杂度页面示例

重要： 实现时必须严格遵循 best-practice-examples 中的代码结构、命名约定和模式。任何修改都可能破坏架构一致性和可维护性。

This skill provides documentation and examples. Follow the steps in the reference guide:

Page Best Practice Guide - Detailed rules for page design and implementation
Best Practice Examples - Must strictly follow page structure and code examples
- standard-with-store/ - Example of a standard complexity page with Store
- simple-no-store/ - Example of a simple complexity page without Store

Important: When implementing, you must strictly follow the code structure, naming conventions and patterns in best-practice-examples. Any modification may damage architectural consistency and maintainability.

使用示例 (Usage Examples)

Usage Examples

典型使用场景

Typical Usage Scenarios

用户输入：创建一个用户管理页面，需要显示用户列表、支持搜索和筛选。

Skill 响应：

主动询问生成模式：显示模式选择界面，要求用户选择无监督或有监督生成
根据用户选择，自动分析需求，判断需要 Store 和标准复杂度
生成完整的页面结构和代码
提供路由注册指导

具体配置示例请参考 TEMPLATE_VIEW.md 中的配置示例部分。

User Input: Create a user management page that needs to display a user list and support search and filtering.

Skill Response:

Proactively Ask for Generation Mode: Display the mode selection interface and require the user to select Unsupervised or Supervised Generation
Based on the user's selection, automatically analyze requirements, determine that a Store and standard complexity are needed
Generate the complete page structure and code
Provide route registration guidance

For specific configuration examples, please refer to the configuration example section in TEMPLATE_VIEW.md.

输出

Output

技能将生成：

Index 文件（index.ts，提供干净的导出接口）
Wrapper 组件（[PageName].tsx，处理依赖注入）
Content 组件（[PageName]Content.tsx，实现UI和交互）
可选的 Store 模块（_store/，如果需要状态管理）

The skill will generate:

Index file (index.ts, provides a clean export interface)
Wrapper component ([PageName].tsx, handles dependency injection)
Content component ([PageName]Content.tsx, implements UI and interactions)
Optional Store module (_store/, if state management is needed)

生成结果示例

Example of Generated Results

请参考 ANATOMY.md 的目录结构树部分。

Please refer to the directory structure tree section in ANATOMY.md.

核心规范 (Knowledge Base)

Core Specifications (Knowledge Base)

输入参数规范

Input Parameter Specifications

```
pageName
```
: 页面名称，必须为 PascalCase 格式
```
features.hasStore
```
: 是否需要状态管理（系统自动判断）
```
features.useExistingStore
```
: 如果需要store，是否使用现有store（true/false，系统自动判断）
```
features.existingStorePath
```
: 如果使用现有store，指定store的导入路径（例如 "@/pages/UserPage/_store"）
```
features.uiComplexity
```
: UI 复杂度等级（simple/standard/complex，系统自动判断）
```
description
```
: 页面功能描述，用于智能判断复杂度

本 Skill 的执行完全依赖以下规范文档，请在生成代码时仔细参考：

整体结构: references/ANATOMY.md (目录结构、命名规范)
页面最佳实践指南: references/page-best-practice-guide.md (页面设计和实现的详细规则)
最佳实践示例: best-practice-examples/ (必须严格参照的页面结构和代码示例)
输入规范: references/schema.ts (参数校验)
Store判断逻辑: references/judgeHasStore.ts (智能判断是否需要Store)
UI复杂度判断: references/judgeUIComplexity.ts (智能判断UI复杂度等级)
Index模版: references/TEMPLATE_INDEX.md (入口文件写法)
Wrapper模版: references/TEMPLATE_WRAPPER.md (依赖注入层写法)
View模版: references/TEMPLATE_VIEW.md (UI层写法)

💡 Store 相关规范请参考
store-best-practice
技能

```
pageName
```
: Page name, must be in PascalCase format
```
features.hasStore
```
: Whether state management is needed (automatically judged by the system)
```
features.useExistingStore
```
: If a store is needed, whether to use an existing store (true/false, automatically judged by the system)
```
features.existingStorePath
```
: If using an existing store, specify the import path of the store (e.g., "@/pages/UserPage/_store")
```
features.uiComplexity
```
: UI complexity level (simple/standard/complex, automatically judged by the system)
```
description
```
: Page function description, used for intelligent complexity judgment

The execution of this Skill completely depends on the following specification documents, please refer to them carefully when generating code:

Overall Structure: references/ANATOMY.md (directory structure, naming specifications)
Page Best Practice Guide: references/page-best-practice-guide.md (detailed rules for page design and implementation)
Best Practice Examples: best-practice-examples/ (page structure and code examples that must be strictly followed)
Input Specifications: references/schema.ts (parameter validation)
Store Judgment Logic: references/judgeHasStore.ts (intelligently judge whether a Store is needed)
UI Complexity Judgment: references/judgeUIComplexity.ts (intelligently judge UI complexity level)
Index Template: references/TEMPLATE_INDEX.md (entry file writing method)
Wrapper Template: references/TEMPLATE_WRAPPER.md (dependency injection layer writing method)
View Template: references/TEMPLATE_VIEW.md (UI layer writing method)

💡 For Store-related specifications, please refer to the
store-best-practice
skill

质量保证 (Quality Assurance)

Quality Assurance

代码生成原则

Code Generation Principles

类型安全: 所有生成的代码必须通过 TypeScript 编译
性能优化: 强制使用 Zustand selectors，避免不必要的重渲染
架构一致性: 严格遵循项目的技术栈和模式
可维护性: 生成的代码应易于理解和扩展

Type Safety: All generated code must pass TypeScript compilation
Performance Optimization: Mandatory use of Zustand selectors to avoid unnecessary re-renders
Architectural Consistency: Strictly follow the project's tech stack and patterns
Maintainability: Generated code should be easy to understand and extend

错误处理

Error Handling

生成前验证目标路径不存在，避免覆盖
提供清晰的错误信息和修复建议
支持回滚机制（如果生成失败）

注意： 调用完毕技能后，强制查看检查清单，并确保返回的内容完全匹配清单中的所有项目。

Verify that the target path does not exist before generation to avoid overwriting
Provide clear error messages and repair suggestions
Support rollback mechanism (if generation fails)

Note: After calling the skill, forcefully check the Checklist and ensure that the returned content fully matches all items in the checklist.

操作步骤 (Workflow)

Workflow

0. 模式选择 (Mode Selection) - 必须主动询问

0. Mode Selection - Must Proactively Ask

重要：在开始任何生成工作前，必须主动询问用户选择哪种生成模式。不要默认使用无监督模式。

主动询问：显示清晰的选择界面，让用户选择生成模式
选项说明：
- 无监督生成 (Unsupervised): 全自动判断所有参数，适合标准场景
- 有监督生成 (Supervised): 在关键决策点询问用户确认，适合不确定或复杂场景
用户决策：等待用户明确选择后再继续

Important: Before starting any generation work, you must proactively ask the user to select a generation mode. Do not use the Unsupervised mode by default.

Proactive Inquiry: Display a clear selection interface for users to select the generation mode
Option Description:
- Unsupervised Generation: Fully automatic judgment of all parameters, suitable for standard scenarios
- Supervised Generation: Ask users for confirmation at key decision points, suitable for uncertain or complex scenarios
User Decision: Wait for the user's clear selection before proceeding

0.1. 现有代码分析 (Existing Code Analysis)

0.1. Existing Code Analysis

检查目标路径是否已存在页面文件
如果存在，分析现有代码结构、样式和组件使用
询问用户是否要：
- 重构现有代码：保留业务逻辑与样式，只规范化架构
- 重新生成：完全替换为新架构
- 增量改进：在现有基础上添加缺失的架构元素

Check whether page files already exist in the target path
If they exist, analyze the existing code structure, styles and component usage
Ask the user whether to:
- Refactor Existing Code: Retain business logic and styles, only standardize the architecture
- Regenerate: Completely replace with the new architecture
- Incremental Improvement: Add missing architectural elements on the existing basis

1. 意图解析与校验

1. Intent Parsing and Validation

读取用户指令，确定生成模式
使用
```
schema.ts
```
中的规则校验参数
自动生成页面名称：根据用户描述和指令，自动生成 PascalCase 格式的页面名称（例如，用户说"创建用户管理页面"则生成"UserManagementPage"）

Read the user's instruction and determine the generation mode
Use the rules in
```
schema.ts
```
to validate parameters
Automatically Generate Page Name: Automatically generate a PascalCase page name based on the user's description and instruction (e.g., if the user says "create user management page", generate "UserManagementPage")

1.1. Store 判断逻辑

1.1. Store Judgment Logic

无监督模式：直接调用
```
judgeHasStoreFromDescription()
```
自动判断是否需要store，如果需要，进一步调用
```
judgeUseExistingStoreFromDescription()
```
判断是否使用现有store，如果使用现有store，调用
```
inferExistingStorePath()
```
推导路径
有监督模式：调用
```
judgeHasStoreSupervised()
```
获取推荐，询问用户确认是否采纳；如果需要store，进一步调用
```
judgeUseExistingStoreSupervised()
```
询问是否使用现有store，如果使用，询问用户指定路径或使用推导路径
重要：如果判断需要新Store，请使用
```
store-best-practice
```
技能生成相应的 Store 模块；如果使用现有store，则无需生成

Unsupervised Mode: Directly call
```
judgeHasStoreFromDescription()
```
to automatically judge whether a store is needed; if needed, further call
```
judgeUseExistingStoreFromDescription()
```
to judge whether to use an existing store; if using an existing store, call
```
inferExistingStorePath()
```
to deduce the path
Supervised Mode: Call
```
judgeHasStoreSupervised()
```
to get recommendations, ask the user to confirm whether to adopt them; if a store is needed, further call
```
judgeUseExistingStoreSupervised()
```
to ask whether to use an existing store; if yes, ask the user to specify the path or use the deduced path
Important: If a new Store is judged to be needed, use the
```
store-best-practice
```
skill to generate the corresponding Store module; if using an existing store, no need to generate

1.2. UI 复杂度判断

2. File List Planning

无监督模式：直接调用
```
judgeUIComplexity()
```
自动判断
有监督模式：调用
```
judgeUIComplexitySupervised()
```
获取推荐，询问用户确认

According to

ANATOMY.md

and the parameters

hasStore

and

useExistingStore

, plan the file paths to be created.

Basic Files:

index.ts

[PageName].tsx

[PageName]Content.tsx

Optional Files:

_store/index.ts

_store/provider.tsx

_store/[camelCase]Slice.ts

_store/[camelCase]Store.ts

(only when

hasStore=true

and

useExistingStore=false

, generated via the

store-best-practice

skill)

2. 规划文件列表

3. Code Generation (In Order)

根据

ANATOMY.md

和

hasStore

、

useExistingStore

参数，规划需要创建的文件路径。

基础文件：

index.ts

[PageName].tsx

[PageName]Content.tsx

可选文件：

_store/index.ts

_store/provider.tsx

_store/[camelCase]Slice.ts

_store/[camelCase]Store.ts

(仅当

hasStore=true

且

useExistingStore=false

，通过

store-best-practice

技能生成)

Please reuse the templates in References, replacing

{{PageName}}

and

{{camelCasePageName}}

with actual values.

Step 3.1: Store Module Handling

If
```
hasStore=true
```
and
```
useExistingStore=false
```
, use the
```
store-best-practice
```
skill to generate the corresponding Store module
If
```
hasStore=true
```
and
```
useExistingStore=true
```
, use the specified
```
existingStorePath
```
to import the existing Store
Store files will be placed in the
```
_store/
```
directory (only when generating a new Store)

Step 3.2: Generate UI View (Content)

Refer to TEMPLATE_VIEW.md.
Select the appropriate UI complexity based on the
```
uiComplexity
```
parameter:
- simple: Basic layout, no search/sort functions, only basic display
- standard: Add search and sort functions, suitable for data management pages
- complex: Add tabs, advanced filtering, batch operations, etc., suitable for feature-rich pages

hasStore=true

, replace

{{StoreImport}}

with the corresponding import statement:

useExistingStore=false

import { useStore } from "zustand"; import { use{{PageName}}Store } from "./_store";

useExistingStore=true

import { useStore } from "zustand"; import { use{{PageName}}Store, {{PageName}}StoreProvider } from "{{existingStorePath}}";

hasStore=true

, replace

{{StoreConnection}}

with

const { loading, searchQuery, selectedSort, viewMode } = use{{PageName}}Store();

, otherwise replace with empty

Use
```
cn
```
and Flex layout to generate the basic skeleton.
Important: Avoid over-design, only generate the functions actually needed

Step 3.3: Generate Wrapper

Refer to TEMPLATE_WRAPPER.md.
Key: If a Store is needed, the Wrapper must correctly introduce and nest
```
<StoreProvider>
```
:
- If
```
useExistingStore=false
```
  : Import
```
{{PageName}}StoreProvider
```
  from "./_store"
- If
```
useExistingStore=true
```
  : Import
```
{{PageName}}StoreProvider
```
  from "{{existingStorePath}}"
If no Store is needed, do not introduce it.
Layout Handling: Prioritize using the unified layout at the routing level, only include layout components in the Wrapper if the page requires a unique layout.

Step 3.4: Generate Entry (Index)

Refer to TEMPLATE_INDEX.md.
Only export the Wrapper component, do not export the Content component

Step 3.5: Quality Verification

Verify whether the generated code complies with project specifications
Check type safety and code quality
Confirm that dependency injection is correct

3. 代码生成 (按顺序)

4. Output Confirmation

请复用 References 中的模版，将

{{PageName}}

和

{{camelCasePageName}}

替换为实际值。

步骤 3.1: Store 模块处理

如果

hasStore=true

且

useExistingStore=false

，使用

store-best-practice

技能生成相应的 Store 模块

如果

hasStore=true

且

useExistingStore=true

，使用指定的

existingStorePath

导入现有 Store

Store 文件将放置在
```
_store/
```
目录下（仅当生成新Store时）

步骤 3.2: 生成 UI 视图 (Content)

参考 TEMPLATE_VIEW.md。
根据
```
uiComplexity
```
参数选择合适的UI复杂度：
- simple: 基础布局，无搜索/排序功能，仅基础展示
- standard: 添加搜索和排序功能，适合数据管理页面
- complex: 添加标签页、高级过滤、批量操作等，适合功能丰富的页面

如果

hasStore=true

，替换

{{StoreImport}}

为相应的import语句：

如果

useExistingStore=false

：

import { useStore } from "zustand"; import { use{{PageName}}Store } from "./_store";

如果

useExistingStore=true

：

import { useStore } from "zustand"; import { use{{PageName}}Store, {{PageName}}StoreProvider } from "{{existingStorePath}}";

如果

hasStore=true

，替换

{{StoreConnection}}

为

const { loading, searchQuery, selectedSort, viewMode } = use{{PageName}}Store();

，否则替换为空

使用
```
cn
```
和 Flex 布局生成基础骨架。
重要: 避免过度设计，只生成实际需要的功能

步骤 3.3: 生成包装器 (Wrapper)

参考 TEMPLATE_WRAPPER.md。
关键: 如果需要 Store，Wrapper 必须正确引入并嵌套
```
<StoreProvider>
```
：
- 如果
```
useExistingStore=false
```
  ：引入
```
{{PageName}}StoreProvider
```
  from "./_store"
- 如果
```
useExistingStore=true
```
  ：引入
```
{{PageName}}StoreProvider
```
  from "{{existingStorePath}}"
如果不需要 Store，则不要引入。
布局处理: 优先使用路由层面的统一布局，仅在页面需要独特布局时在 Wrapper 中包含布局组件。

步骤 3.4: 生成入口 (Index)

参考 TEMPLATE_INDEX.md。
只导出包装器组件，不导出Content组件

步骤 3.5: 质量验证

验证生成的代码是否符合项目规范
检查类型安全和代码质量
确认依赖注入正确

Inform the user that the page has been generated to the specified path.
Remind the user to register the page in the route file (such as
```
routeTree
```
or
```
router.tsx
```
).
Provide usage examples of the generated components.
Suggest running tests to verify the generated code.

4. 输出确认

—

告知用户页面已生成至指定路径。
提醒用户需在路由文件（如
```
routeTree
```
或
```
router.tsx
```
）中注册该页面。
提供生成的组件使用示例。
建议运行测试验证生成代码。

—