@robsun/create-keystone-app 0.2.3 → 0.2.5

package/README.md

@@ -31,6 +31,10 @@ pnpm dlx --package @robsun/create-keystone-app create-keystone-module <module-na
 - `--with-crud`：包含 CRUD 示例代码。
 - `--skip-register`：跳过自动注册步骤。
 
+## AI Skills
+- Codex：`.codex/skills/keystone-dev`
+- Claude：`.claude/skills/keystone-dev`
+
 ## 初始化后操作
 ```bash
 cd <dir>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "scripts": {
     "build": "node scripts/build.js",
     "prepublishOnly": "node scripts/build.js && node scripts/prune-template-deps.js"

package/template/.claude/skills/keystone-dev/CAPABILITIES.md

@@ -0,0 +1,127 @@
+# Keystone 包完整能力清单
+
+## 一、前端组件 (@robsun/keystone-web-core)
+
+### 1. 应用与路由
+```typescript
+import { KeystoneApp, createKeystoneRouter } from '@robsun/keystone-web-core'
+import { registerModule, registerRoutes, registerMenus, registerPermissions } from '@robsun/keystone-web-core'
+```
+
+### 2. 高级 UI 组件
+```typescript
+// 高级表格 - 过滤、分页、行选择、导出
+import { ProTable } from '@robsun/keystone-web-core'
+
+// 智能表单 - 自动验证、加载状态
+import { ProForm } from '@robsun/keystone-web-core'
+
+// 文件上传 - 拖拽、预览、多文件
+import { FileUpload } from '@robsun/keystone-web-core'
+
+// 数据导入向导
+import { DataImporter, ImportWizard, ColumnMapper, ValidationResult } from '@robsun/keystone-web-core'
+
+// 数据导出向导
+import { DataExporter, ExportWizard } from '@robsun/keystone-web-core'
+
+// 权限守卫
+import { PermissionGuard } from '@robsun/keystone-web-core'
+```
+
+### 3. 审批流系统
+```typescript
+import {
+  ApprovalFlowEditor,    // 流程编辑器
+  ApprovalFlowCanvas,    // 可视化画布
+  ApprovalNodeEditor,    // 节点编辑
+  ConditionEditor,       // 条件编辑
+  ApprovalStatus,        // 状态展示
+  ApprovalAction,        // 审批按钮
+  ApprovalHistory        // 审批历史
+} from '@robsun/keystone-web-core'
+```
+
+### 4. 帮助系统
+```typescript
+import {
+  HelpButton, HelpDrawer, HelpSearch, HelpContent,
+  useCurrentHelpKey, useHelpSearch
+} from '@robsun/keystone-web-core'
+```
+
+### 5. 布局与主题
+```typescript
+import { MainLayout, antdTheme, useLayoutStore } from '@robsun/keystone-web-core'
+```
+
+### 6. 认证授权
+```typescript
+import { useAuthStore, useAuth, matchesPermission } from '@robsun/keystone-web-core'
+```
+
+### 7. 运行时服务
+```typescript
+import { api, setApiBaseUrl } from '@robsun/keystone-web-core'
+import { createExportJob, createImportJob } from '@robsun/keystone-web-core'
+import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robsun/keystone-web-core'
+import { getJob, listJobs } from '@robsun/keystone-web-core'
+```
+
+### 8. Hooks
+```typescript
+import { useListState } from '@robsun/keystone-web-core'
+```
+
+### 9. 类型
+```typescript
+import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
+import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
+```
+
+## 二、后端能力 (Go)
+
+### 1. 模块系统
+```go
+type Module interface {
+    Name() string
+    RegisterRoutes(r *gin.RouterGroup)
+    RegisterPermissions() []Permission
+    Migrate(db *gorm.DB) error
+    Seed(db *gorm.DB) error
+}
+```
+
+### 2. 审批引擎
+```go
+approvalService.CreateInstance(...)
+approvalService.Approve(...)
+approvalService.Reject(...)
+approvalService.Cancel(...)
+```
+
+### 3. Job 队列
+```go
+jobService.CreateJob(...)
+jobService.GetJob(...)
+jobService.ListJobs(...)
+```
+
+### 4. 通知服务
+```go
+notificationService.SendNotification(...)
+notificationService.ListNotifications(...)
+notificationService.MarkRead(...)
+```
+
+### 5. 权限中间件
+```go
+middleware.RequirePermission("module:resource:action")
+```
+
+### 6. 存储服务
+```go
+storageService.Upload(...)
+storageService.Download(...)
+storageService.Delete(...)
+```

package/template/.claude/skills/keystone-dev/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: keystone-dev
+description: 基于 Keystone 平台开发业务模块。当用户需要创建新模块、添加业务功能、实现 CRUD、审批流程、数据导入导出、文件上传时使用。Use when creating modules, adding features, implementing CRUD, approval workflows, import/export, or file upload for Keystone platform.
+---
+
+# Keystone 业务模块开发
+
+使用 Keystone 平台快速开发业务模块。
+
+## 工作流程
+
+1. **解析需求** → 识别所需能力
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
+3. **生成后端模块** → handler/, service/, repository/, migrations/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **输出调整建议**
+
+## 能力选择矩阵
+
+根据需求关键词选用对应能力：
+
+| 需求关键词 | 前端能力 | 后端能力 |
+|-----------|---------|---------|
+| 列表、查询 | ProTable + 过滤 + 分页 | ListHandler + Repository |
+| 表单、编辑 | ProForm + 验证 | CreateHandler + UpdateHandler |
+| 导入、批量 | DataImporter | ImportHandler + Job队列 |
+| 导出、下载 | DataExporter | ExportHandler + Job队列 |
+| 上传、附件 | FileUpload | UploadHandler + 存储服务 |
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+详细能力清单见 [CAPABILITIES.md](CAPABILITIES.md)。
+代码模板见 [TEMPLATES.md](TEMPLATES.md)。
+
+## 模块结构约定
+
+### 前端模块
+```
+apps/web/src/modules/{name}/
+├── index.ts              # registerModule()
+├── routes.tsx            # 路由 + 菜单 + 权限
+├── pages/
+│   ├── List.tsx          # ProTable
+│   ├── Detail.tsx
+│   └── Form.tsx          # ProForm
+├── services/api.ts
+├── types.ts
+└── help/index.md
+```
+
+### 后端模块
+```
+apps/server/internal/modules/{name}/
+├── module.go
+├── api/handler/
+├── domain/models/
+├── domain/service/
+├── infra/repository/
+└── bootstrap/migrations/
+```
+
+## 权限命名
+
+格式: `{module}:{resource}:{action}`
+
+动作: view | create | update | delete | manage | export | import | approve
+
+## 注册步骤
+
+生成代码后需完成以下注册（**缺一不可**）：
+
+1. **前端导入** `main.tsx`: `import './modules/{name}'`
+2. **前端启用** `app.config.ts`: 添加到 `modules.enabled` 数组 ⚠️ **必须，否则菜单不显示**
+3. **后端注册** `manifest.go`: `import {name}module "app/internal/modules/{name}"` + `Register({name}module.NewModule())`
+4. **后端启用** `config.yaml`: 添加到 `modules.enabled`

package/template/.claude/skills/keystone-dev/TEMPLATES.md

@@ -0,0 +1,306 @@
+# Keystone 代码模板
+
+## 前端模板
+
+### routes.tsx
+```tsx
+import { RouteObject } from 'react-router-dom'
+import { registerModule } from '@robsun/keystone-web-core'
+
+const routes: RouteObject[] = [
+  {
+    path: '{name}',
+    handle: {
+      menu: { title: '{Title}', icon: 'icon-name' },
+      permission: '{name}:{resource}:view',
+      helpKey: '{name}/index',
+    },
+    children: [
+      { index: true, lazy: () => import('./pages/List') },
+      { path: 'create', lazy: () => import('./pages/Form') },
+      { path: ':id', lazy: () => import('./pages/Detail') },
+      { path: ':id/edit', lazy: () => import('./pages/Form') },
+    ],
+  },
+]
+
+registerModule({ name: '{name}', routes })
+```
+
+### List.tsx (ProTable)
+```tsx
+import { useEffect, useState } from 'react'
+import { ProTable } from '@robsun/keystone-web-core'
+import type { PaginatedData } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+import { list{Entity} } from '../services/api'
+
+const INITIAL_DATA: PaginatedData<{Entity}> = {
+  items: [],
+  total: 0,
+  page: 1,
+  page_size: 10,
+}
+
+export function Component() {
+  const [loading, setLoading] = useState(false)
+  const [data, setData] = useState(INITIAL_DATA)
+
+  const columns = [
+    { title: 'ID', dataIndex: 'id' },
+    { title: '名称', dataIndex: 'name' },
+  ]
+
+  const fetchData = async (page = data.page, pageSize = data.page_size) => {
+    setLoading(true)
+    try {
+      const result = await list{Entity}({ page, page_size: pageSize })
+      setData(result)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    void fetchData()
+  }, [])
+
+  return (
+    <ProTable
+      columns={columns}
+      dataSource={data.items}
+      rowKey="id"
+      loading={loading}
+      pagination={{
+        current: data.page,
+        pageSize: data.page_size,
+        total: data.total,
+        onChange: (page, pageSize) => {
+          void fetchData(page, pageSize)
+        },
+      }}
+    />
+  )
+}
+```
+
+### Form.tsx (ProForm)
+```tsx
+import { ProForm } from '@robsun/keystone-web-core'
+import { api } from '@robsun/keystone-web-core'
+import { useParams, useNavigate } from 'react-router-dom'
+
+export function Component() {
+  const { id } = useParams()
+  const navigate = useNavigate()
+  const isEdit = !!id
+
+  const onSubmit = async (values: any) => {
+    if (isEdit) {
+      await api.patch(`/api/{name}/${id}`, values)
+    } else {
+      await api.post('/api/{name}', values)
+    }
+    navigate('/{name}')
+  }
+
+  return (
+    <ProForm onFinish={onSubmit}>
+      {/* 表单字段 */}
+    </ProForm>
+  )
+}
+```
+
+### services/api.ts
+```typescript
+import { api, type ApiResponse, type PaginatedData, type PaginationParams } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+
+// 注意：使用 api 而非 apiClient，响应格式为 { data: { ... } }
+export const list{Entity} = async (params: PaginationParams = {}) => {
+  const { data } = await api.get<ApiResponse<PaginatedData<{Entity}>>>(
+    '/{module}/{resources}',
+    { params }
+  )
+  return data.data
+}
+
+export const create{Entity} = async (payload: Partial<{Entity}>) => {
+  const { data } = await api.post<ApiResponse<{Entity}>>('/{module}/{resources}', payload)
+  return data.data
+}
+
+export const update{Entity} = async (id: number, payload: Partial<{Entity}>) => {
+  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module}/{resources}/${id}`, payload)
+  return data.data
+}
+
+export const delete{Entity} = async (id: number) => {
+  await api.delete<ApiResponse<{ id: number }>>(`/{module}/{resources}/${id}`)
+}
+```
+
+### types.ts
+```typescript
+export interface {Entity} {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+```
+
+## 后端模板
+
+### module.go
+```go
+package {name}
+
+import (
+    "github.com/gin-gonic/gin"
+    "gorm.io/gorm"
+)
+
+type Module struct{}
+
+func (m *Module) Name() string { return "{name}" }
+
+func (m *Module) RegisterRoutes(r *gin.RouterGroup) {
+    g := r.Group("/{name}")
+    g.GET("", handler.List)
+    g.GET("/:id", handler.Detail)
+    g.POST("", handler.Create)
+    g.PATCH("/:id", handler.Update)
+    g.DELETE("/:id", handler.Delete)
+}
+
+func (m *Module) RegisterPermissions() []Permission {
+    return []Permission{
+        {Name: "{name}:{resource}:view", Title: "查看{Title}"},
+        {Name: "{name}:{resource}:create", Title: "创建{Title}"},
+        {Name: "{name}:{resource}:update", Title: "编辑{Title}"},
+        {Name: "{name}:{resource}:delete", Title: "删除{Title}"},
+    }
+}
+
+func (m *Module) Migrate(db *gorm.DB) error {
+    return db.AutoMigrate(&models.{Entity}{})
+}
+
+func (m *Module) Seed(db *gorm.DB) error { return nil }
+```
+
+### handler/list.go
+```go
+package handler
+
+import (
+    "github.com/gin-gonic/gin"
+)
+
+func (h *Handler) List(c *gin.Context) {
+    page, pageSize := parsePagination(c)
+    items, total, err := h.svc.List(c, page, pageSize)
+    if err != nil {
+        respondError(c, err)
+        return
+    }
+    respondPaginated(c, items, total, page, pageSize)
+}
+```
+
+### domain/models/entity.go
+```go
+package models
+
+import "time"
+
+type {Entity} struct {
+    ID        string    `json:"id" gorm:"primaryKey"`
+    Name      string    `json:"name"`
+    CreatedAt time.Time `json:"createdAt"`
+    UpdatedAt time.Time `json:"updatedAt"`
+}
+```
+
+### domain/service/service.go
+```go
+package service
+
+type Service struct {
+    repo *repository.Repository
+}
+
+func NewService(repo *repository.Repository) *Service {
+    return &Service{repo: repo}
+}
+
+func (s *Service) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    return s.repo.List(ctx, page, pageSize)
+}
+
+func (s *Service) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    return s.repo.Get(ctx, id)
+}
+
+func (s *Service) Create(ctx context.Context, entity *models.{Entity}) error {
+    return s.repo.Create(ctx, entity)
+}
+
+func (s *Service) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return s.repo.Update(ctx, id, entity)
+}
+
+func (s *Service) Delete(ctx context.Context, id string) error {
+    return s.repo.Delete(ctx, id)
+}
+```
+
+### infra/repository/repo.go
+```go
+package repository
+
+import (
+    "context"
+    "gorm.io/gorm"
+)
+
+type Repository struct {
+    db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+    return &Repository{db: db}
+}
+
+func (r *Repository) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    var items []models.{Entity}
+    var total int64
+
+    r.db.Model(&models.{Entity}{}).Count(&total)
+    r.db.Offset((page - 1) * pageSize).Limit(pageSize).Find(&items)
+
+    return items, total, nil
+}
+
+func (r *Repository) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    var item models.{Entity}
+    if err := r.db.First(&item, "id = ?", id).Error; err != nil {
+        return nil, err
+    }
+    return &item, nil
+}
+
+func (r *Repository) Create(ctx context.Context, entity *models.{Entity}) error {
+    return r.db.Create(entity).Error
+}
+
+func (r *Repository) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return r.db.Model(&models.{Entity}{}).Where("id = ?", id).Updates(entity).Error
+}
+
+func (r *Repository) Delete(ctx context.Context, id string) error {
+    return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
+}
+```

package/template/.codex/skills/keystone-dev/CAPABILITIES.md

@@ -0,0 +1,127 @@
+# Keystone 包完整能力清单
+
+## 一、前端组件 (@robsun/keystone-web-core)
+
+### 1. 应用与路由
+```typescript
+import { KeystoneApp, createKeystoneRouter } from '@robsun/keystone-web-core'
+import { registerModule, registerRoutes, registerMenus, registerPermissions } from '@robsun/keystone-web-core'
+```
+
+### 2. 高级 UI 组件
+```typescript
+// 高级表格 - 过滤、分页、行选择、导出
+import { ProTable } from '@robsun/keystone-web-core'
+
+// 智能表单 - 自动验证、加载状态
+import { ProForm } from '@robsun/keystone-web-core'
+
+// 文件上传 - 拖拽、预览、多文件
+import { FileUpload } from '@robsun/keystone-web-core'
+
+// 数据导入向导
+import { DataImporter, ImportWizard, ColumnMapper, ValidationResult } from '@robsun/keystone-web-core'
+
+// 数据导出向导
+import { DataExporter, ExportWizard } from '@robsun/keystone-web-core'
+
+// 权限守卫
+import { PermissionGuard } from '@robsun/keystone-web-core'
+```
+
+### 3. 审批流系统
+```typescript
+import {
+  ApprovalFlowEditor,    // 流程编辑器
+  ApprovalFlowCanvas,    // 可视化画布
+  ApprovalNodeEditor,    // 节点编辑
+  ConditionEditor,       // 条件编辑
+  ApprovalStatus,        // 状态展示
+  ApprovalAction,        // 审批按钮
+  ApprovalHistory        // 审批历史
+} from '@robsun/keystone-web-core'
+```
+
+### 4. 帮助系统
+```typescript
+import {
+  HelpButton, HelpDrawer, HelpSearch, HelpContent,
+  useCurrentHelpKey, useHelpSearch
+} from '@robsun/keystone-web-core'
+```
+
+### 5. 布局与主题
+```typescript
+import { MainLayout, antdTheme, useLayoutStore } from '@robsun/keystone-web-core'
+```
+
+### 6. 认证授权
+```typescript
+import { useAuthStore, useAuth, matchesPermission } from '@robsun/keystone-web-core'
+```
+
+### 7. 运行时服务
+```typescript
+import { api, setApiBaseUrl } from '@robsun/keystone-web-core'
+import { createExportJob, createImportJob } from '@robsun/keystone-web-core'
+import { listNotifications, markNotificationRead, fetchUnreadCount } from '@robsun/keystone-web-core'
+import { getJob, listJobs } from '@robsun/keystone-web-core'
+```
+
+### 8. Hooks
+```typescript
+import { useListState } from '@robsun/keystone-web-core'
+```
+
+### 9. 类型
+```typescript
+import type { ApiResponse, PaginatedData, PaginatedResponse } from '@robsun/keystone-web-core'
+import type { Permission, ModuleName, Action } from '@robsun/keystone-web-core'
+```
+
+## 二、后端能力 (Go)
+
+### 1. 模块系统
+```go
+type Module interface {
+    Name() string
+    RegisterRoutes(r *gin.RouterGroup)
+    RegisterPermissions() []Permission
+    Migrate(db *gorm.DB) error
+    Seed(db *gorm.DB) error
+}
+```
+
+### 2. 审批引擎
+```go
+approvalService.CreateInstance(...)
+approvalService.Approve(...)
+approvalService.Reject(...)
+approvalService.Cancel(...)
+```
+
+### 3. Job 队列
+```go
+jobService.CreateJob(...)
+jobService.GetJob(...)
+jobService.ListJobs(...)
+```
+
+### 4. 通知服务
+```go
+notificationService.SendNotification(...)
+notificationService.ListNotifications(...)
+notificationService.MarkRead(...)
+```
+
+### 5. 权限中间件
+```go
+middleware.RequirePermission("module:resource:action")
+```
+
+### 6. 存储服务
+```go
+storageService.Upload(...)
+storageService.Download(...)
+storageService.Delete(...)
+```

package/template/.codex/skills/keystone-dev/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: keystone-dev
+description: 基于 Keystone 平台开发业务模块。当用户需要创建新模块、添加业务功能、实现 CRUD、审批流程、数据导入导出、文件上传时使用。Use when creating modules, adding features, implementing CRUD, approval workflows, import/export, or file upload for Keystone platform.
+---
+
+# Keystone 业务模块开发
+
+使用 Keystone 平台快速开发业务模块。
+
+## 工作流程
+
+1. **解析需求** → 识别所需能力
+2. **生成前端模块** → routes.tsx, pages/, services/, types.ts
+3. **生成后端模块** → handler/, service/, repository/, migrations/
+4. **自动注册** → main.tsx + manifest.go + config.yaml
+5. **输出调整建议**
+
+## 能力选择矩阵
+
+根据需求关键词选用对应能力：
+
+| 需求关键词 | 前端能力 | 后端能力 |
+|-----------|---------|---------|
+| 列表、查询 | ProTable + 过滤 + 分页 | ListHandler + Repository |
+| 表单、编辑 | ProForm + 验证 | CreateHandler + UpdateHandler |
+| 导入、批量 | DataImporter | ImportHandler + Job队列 |
+| 导出、下载 | DataExporter | ExportHandler + Job队列 |
+| 上传、附件 | FileUpload | UploadHandler + 存储服务 |
+| 审批、流程 | ApprovalFlowEditor | 审批引擎 |
+| 权限 | PermissionGuard | 权限中间件 |
+
+详细能力清单见 [CAPABILITIES.md](CAPABILITIES.md)。
+代码模板见 [TEMPLATES.md](TEMPLATES.md)。
+
+## 模块结构约定
+
+### 前端模块
+```
+apps/web/src/modules/{name}/
+├── index.ts              # registerModule()
+├── routes.tsx            # 路由 + 菜单 + 权限
+├── pages/
+│   ├── List.tsx          # ProTable
+│   ├── Detail.tsx
+│   └── Form.tsx          # ProForm
+├── services/api.ts
+├── types.ts
+└── help/index.md
+```
+
+### 后端模块
+```
+apps/server/internal/modules/{name}/
+├── module.go
+├── api/handler/
+├── domain/models/
+├── domain/service/
+├── infra/repository/
+└── bootstrap/migrations/
+```
+
+## 权限命名
+
+格式: `{module}:{resource}:{action}`
+
+动作: view | create | update | delete | manage | export | import | approve
+
+## 注册步骤
+
+生成代码后需完成以下注册（**缺一不可**）：
+
+1. **前端导入** `main.tsx`: `import './modules/{name}'`
+2. **前端启用** `app.config.ts`: 添加到 `modules.enabled` 数组 ⚠️ **必须，否则菜单不显示**
+3. **后端注册** `manifest.go`: `import {name}module "app/internal/modules/{name}"` + `Register({name}module.NewModule())`
+4. **后端启用** `config.yaml`: 添加到 `modules.enabled`

package/template/.codex/skills/keystone-dev/TEMPLATES.md

@@ -0,0 +1,306 @@
+# Keystone 代码模板
+
+## 前端模板
+
+### routes.tsx
+```tsx
+import { RouteObject } from 'react-router-dom'
+import { registerModule } from '@robsun/keystone-web-core'
+
+const routes: RouteObject[] = [
+  {
+    path: '{name}',
+    handle: {
+      menu: { title: '{Title}', icon: 'icon-name' },
+      permission: '{name}:{resource}:view',
+      helpKey: '{name}/index',
+    },
+    children: [
+      { index: true, lazy: () => import('./pages/List') },
+      { path: 'create', lazy: () => import('./pages/Form') },
+      { path: ':id', lazy: () => import('./pages/Detail') },
+      { path: ':id/edit', lazy: () => import('./pages/Form') },
+    ],
+  },
+]
+
+registerModule({ name: '{name}', routes })
+```
+
+### List.tsx (ProTable)
+```tsx
+import { useEffect, useState } from 'react'
+import { ProTable } from '@robsun/keystone-web-core'
+import type { PaginatedData } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+import { list{Entity} } from '../services/api'
+
+const INITIAL_DATA: PaginatedData<{Entity}> = {
+  items: [],
+  total: 0,
+  page: 1,
+  page_size: 10,
+}
+
+export function Component() {
+  const [loading, setLoading] = useState(false)
+  const [data, setData] = useState(INITIAL_DATA)
+
+  const columns = [
+    { title: 'ID', dataIndex: 'id' },
+    { title: '名称', dataIndex: 'name' },
+  ]
+
+  const fetchData = async (page = data.page, pageSize = data.page_size) => {
+    setLoading(true)
+    try {
+      const result = await list{Entity}({ page, page_size: pageSize })
+      setData(result)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    void fetchData()
+  }, [])
+
+  return (
+    <ProTable
+      columns={columns}
+      dataSource={data.items}
+      rowKey="id"
+      loading={loading}
+      pagination={{
+        current: data.page,
+        pageSize: data.page_size,
+        total: data.total,
+        onChange: (page, pageSize) => {
+          void fetchData(page, pageSize)
+        },
+      }}
+    />
+  )
+}
+```
+
+### Form.tsx (ProForm)
+```tsx
+import { ProForm } from '@robsun/keystone-web-core'
+import { api } from '@robsun/keystone-web-core'
+import { useParams, useNavigate } from 'react-router-dom'
+
+export function Component() {
+  const { id } = useParams()
+  const navigate = useNavigate()
+  const isEdit = !!id
+
+  const onSubmit = async (values: any) => {
+    if (isEdit) {
+      await api.patch(`/api/{name}/${id}`, values)
+    } else {
+      await api.post('/api/{name}', values)
+    }
+    navigate('/{name}')
+  }
+
+  return (
+    <ProForm onFinish={onSubmit}>
+      {/* 表单字段 */}
+    </ProForm>
+  )
+}
+```
+
+### services/api.ts
+```typescript
+import { api, type ApiResponse, type PaginatedData, type PaginationParams } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+
+// 注意：使用 api 而非 apiClient，响应格式为 { data: { ... } }
+export const list{Entity} = async (params: PaginationParams = {}) => {
+  const { data } = await api.get<ApiResponse<PaginatedData<{Entity}>>>(
+    '/{module}/{resources}',
+    { params }
+  )
+  return data.data
+}
+
+export const create{Entity} = async (payload: Partial<{Entity}>) => {
+  const { data } = await api.post<ApiResponse<{Entity}>>('/{module}/{resources}', payload)
+  return data.data
+}
+
+export const update{Entity} = async (id: number, payload: Partial<{Entity}>) => {
+  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module}/{resources}/${id}`, payload)
+  return data.data
+}
+
+export const delete{Entity} = async (id: number) => {
+  await api.delete<ApiResponse<{ id: number }>>(`/{module}/{resources}/${id}`)
+}
+```
+
+### types.ts
+```typescript
+export interface {Entity} {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+```
+
+## 后端模板
+
+### module.go
+```go
+package {name}
+
+import (
+    "github.com/gin-gonic/gin"
+    "gorm.io/gorm"
+)
+
+type Module struct{}
+
+func (m *Module) Name() string { return "{name}" }
+
+func (m *Module) RegisterRoutes(r *gin.RouterGroup) {
+    g := r.Group("/{name}")
+    g.GET("", handler.List)
+    g.GET("/:id", handler.Detail)
+    g.POST("", handler.Create)
+    g.PATCH("/:id", handler.Update)
+    g.DELETE("/:id", handler.Delete)
+}
+
+func (m *Module) RegisterPermissions() []Permission {
+    return []Permission{
+        {Name: "{name}:{resource}:view", Title: "查看{Title}"},
+        {Name: "{name}:{resource}:create", Title: "创建{Title}"},
+        {Name: "{name}:{resource}:update", Title: "编辑{Title}"},
+        {Name: "{name}:{resource}:delete", Title: "删除{Title}"},
+    }
+}
+
+func (m *Module) Migrate(db *gorm.DB) error {
+    return db.AutoMigrate(&models.{Entity}{})
+}
+
+func (m *Module) Seed(db *gorm.DB) error { return nil }
+```
+
+### handler/list.go
+```go
+package handler
+
+import (
+    "github.com/gin-gonic/gin"
+)
+
+func (h *Handler) List(c *gin.Context) {
+    page, pageSize := parsePagination(c)
+    items, total, err := h.svc.List(c, page, pageSize)
+    if err != nil {
+        respondError(c, err)
+        return
+    }
+    respondPaginated(c, items, total, page, pageSize)
+}
+```
+
+### domain/models/entity.go
+```go
+package models
+
+import "time"
+
+type {Entity} struct {
+    ID        string    `json:"id" gorm:"primaryKey"`
+    Name      string    `json:"name"`
+    CreatedAt time.Time `json:"createdAt"`
+    UpdatedAt time.Time `json:"updatedAt"`
+}
+```
+
+### domain/service/service.go
+```go
+package service
+
+type Service struct {
+    repo *repository.Repository
+}
+
+func NewService(repo *repository.Repository) *Service {
+    return &Service{repo: repo}
+}
+
+func (s *Service) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    return s.repo.List(ctx, page, pageSize)
+}
+
+func (s *Service) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    return s.repo.Get(ctx, id)
+}
+
+func (s *Service) Create(ctx context.Context, entity *models.{Entity}) error {
+    return s.repo.Create(ctx, entity)
+}
+
+func (s *Service) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return s.repo.Update(ctx, id, entity)
+}
+
+func (s *Service) Delete(ctx context.Context, id string) error {
+    return s.repo.Delete(ctx, id)
+}
+```
+
+### infra/repository/repo.go
+```go
+package repository
+
+import (
+    "context"
+    "gorm.io/gorm"
+)
+
+type Repository struct {
+    db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+    return &Repository{db: db}
+}
+
+func (r *Repository) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    var items []models.{Entity}
+    var total int64
+
+    r.db.Model(&models.{Entity}{}).Count(&total)
+    r.db.Offset((page - 1) * pageSize).Limit(pageSize).Find(&items)
+
+    return items, total, nil
+}
+
+func (r *Repository) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    var item models.{Entity}
+    if err := r.db.First(&item, "id = ?", id).Error; err != nil {
+        return nil, err
+    }
+    return &item, nil
+}
+
+func (r *Repository) Create(ctx context.Context, entity *models.{Entity}) error {
+    return r.db.Create(entity).Error
+}
+
+func (r *Repository) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return r.db.Model(&models.{Entity}{}).Where("id = ?", id).Updates(entity).Error
+}
+
+func (r *Repository) Delete(ctx context.Context, id string) error {
+    return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
+}
+```

package/template/README.md

@@ -43,6 +43,10 @@ pnpm create:module <module-name> [options]
 - `--with-crud`：包含 CRUD 示例代码。
 - `--skip-register`：跳过自动注册步骤。
 
+## AI Skills
+- Codex：`.codex/skills/keystone-dev`
+- Claude：`.claude/skills/keystone-dev`
+
 ## 目录结构
 - `apps/web/`：React + Vite 壳与业务模块（`src/modules/*`）。
 - `apps/server/`：Go API + 模块注册/迁移/种子数据（含 `config.yaml`）。

package/template/apps/web/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@ant-design/icons": "^6.1.0",
-    "@robsun/keystone-web-core": "0.1.8",
+    "@robsun/keystone-web-core": "0.1.9",
     "antd": "^6.0.1",
     "dayjs": "^1.11.19",
     "react": "^19.2.0",

package/template/pnpm-lock.yaml

@@ -27,8 +27,8 @@ importers:
         specifier: ^6.1.0
         version: 6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@robsun/keystone-web-core':
-        specifier: 0.1.8
-        version: 0.1.8(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
+        specifier: 0.1.9
+        version: 0.1.9(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
       antd:
         specifier: ^6.0.1
         version: 6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -924,8 +924,8 @@ packages:
       react: '>=16.9.0'
       react-dom: '>=16.9.0'
 
-  '@robsun/keystone-web-core@0.1.8':
-    resolution: {integrity: sha512-r6Qfs1LxTZBv6GVIf5s6LREuTl/lskq8L3Y9YynUFKvL1tuZ3h3sThxPvvP7VQbBZn5As/XUv16kpqqVXX1HvQ==}
+  '@robsun/keystone-web-core@0.1.9':
+    resolution: {integrity: sha512-zbN6yiq3p/wwVOZvGj5YI6lT+xXCyWx87QIsM3IXnNyMxJl4OLRvv1xXN3u6K4uQpp2q+no4CeYLAfRwFIKNNw==}
     peerDependencies:
       '@ant-design/icons': ^6.1.0
       antd: ^6.0.1
@@ -3744,7 +3744,7 @@ snapshots:
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
 
-  '@robsun/keystone-web-core@0.1.8(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))':
+  '@robsun/keystone-web-core@0.1.9(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))':
     dependencies:
       '@ant-design/icons': 6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@vitejs/plugin-react': 5.1.2(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
@@ -6027,4 +6027,3 @@ snapshots:
       use-sync-external-store: 1.6.0(react@19.2.3)
 
   zwitch@2.0.4: {}
-