@allkit/best-practice 0.0.1

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@allkit/best-practice",
+  "version": "0.0.1",
+  "description": "this is a best practice skills package",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [],
+  "author": "SPig",
+  "license": "MIT" 
+}

package/skills/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: best-practice
+description: 提供项目最佳实践指南，包括项目搭建、模块规范、代码规范、Vue 相关规范等，确保项目开发质量和一致性。
+license: MIT
+metadata:
+  author: allkit
+  version: 1.0
+compatibility:
+  - Vue 3
+  - TypeScript 5.0+
+  - Vite 5.0+
+  - pnpm 
+  - scss 
+---
+
+本技能是 Vue 3 + TypeScript+ tsx+ scss+ pnpm 项目的开发规范和最佳实践指南。它提供了项目搭建、模块规范、代码规范、Vue 相关规范等方面的指导，确保项目开发质量和一致性。
+
+## 何时应用
+
+在 Vue 3 + TypeScript 项目开发过程中始终应用此技能。
+
+- 在创建新项目或新模块时，参考`项目搭建`和`模块规范`
+- 在编写代码时，遵循`代码规范`和`命名规范`
+- 创建新组件时，遵循`组件规范`和 `Hooks 规范`
+- 在使用 JSX jsx/tsx 语法时，遵循`JSX/tsx 规范`
+- 在配置开发环境时，参考 ESLint、TypeScript、Vite 配置
+
+## 技能列表
+
+### 代码规范
+
+| 规范                                      | 描述                                          | 调用时机       |
+| ----------------------------------------- | --------------------------------------------- | -------------- |
+| [变量命名](references/variable-naming.md) | 定义变量的命名规则，包括数组、对象、布尔值等  | 定义变量时遵循 |
+| [函数命名](references/function-naming.md) | 定义函数的命名规则，包括 API、事件、Hook 函数 | 定义函数时遵循 |
+| [枚举命名](references/enum-naming.md)     | 定义枚举的命名规则，包括枚举名和属性命名      | 定义枚举时遵循 |
+| [CSS 规范](references/css-spec.md)        | 定义 CSS 开发规范，包括 BEM、SCSS、Tailwind   | 编写样式时遵循 |
+| [资源规范](references/assets-spec.md)     | 定义静态资源的使用和命名规范                  | 引入资源时遵循 |
+
+### 模块规范
+
+| 规范                                          | 描述                        | 调用时机                                     |
+| --------------------------------------------- | --------------------------- | -------------------------------------------- |
+| [模块目录结构](references/module-spec.md)     | 定义功能模块,目录结构的标准 | 创建新模块,新的vue,,新的组件时新的文件时参考 |
+| [文件夹命名规范](references/folder-naming.md) | 定义文件夹的命名规则        | 创建新文件夹时遵循                           |
+| [文件命名规范](references/file-naming.md)     | 定义各类文件的命名规则      | 创建新文件时遵循                             |
+
+## Vue 相关规范
+
+| 规范                                      | 描述                                            | 调用时机           |
+| ----------------------------------------- | ----------------------------------------------- | ------------------ |
+| [组件规范](references/component-spec.md)  | 定义 Vue 组件的开发规范，包括简单组件和复杂组件 | 开发组件时遵循     |
+| [功能模块规范](references/module-spec.md) | 定义功能模块的开发规范，包括入口页面和职责划分  | 开发功能模块时遵循 |
+| [Hooks 规范](references/hooks-spec.md)    | 定义 Vue Hooks 的开发规范，包括命名和结构       | 开发 Hooks 时遵循  |
+| [JSX/tsx 规范](references/jsx-spec.md)     | 定义 JSX/tsx 语法规范，包括语法对比及注意事项   | 使用 JSX/tsx 时遵循 |
+
+### @allkit 库
+
+| 库                                               | 描述                                       | 调用时机                |
+| ------------------------------------------------ | ------------------------------------------ | ----------------------- |
+| [@allkit/http-client](references/http-client.md) | HTTP 请求客户端，提供统一的请求封装        | 发起 API 请求时自动使用 |
+| [@allkit/shared](references/shared-utils.md)     | 通用工具函数库，提供类型判断、格式化等功能 | 需要工具函数时优先使用  |

package/skills/references/assets-spec.md

@@ -0,0 +1,83 @@
+---
+title: 资源规范
+description: 新增修改(图片,视频等)资源文件的目录结构、命名规范及引用方式
+category: 规范文档
+---
+
+# 资源规范
+
+## 核心原则
+
+1.  **模块化**：资源文件应尽可能存放在使用它的模块内部 `assets` 目录中。
+2.  **引用方式**：必须使用 `import` 或 `new URL()` 引入资源，禁止使用相对路径字符串。
+3.  **命名规范**：使用下划线 `_` 分隔，包含类型前缀。
+
+## 目录结构
+
+每个业务模块都应有独立的 `assets` 目录。
+
+```
+vehicle-picker/
+├── assets/             # 模块私有资源
+│   ├── img_vehicle_box.png
+│   └── ic_close.svg
+├── index.vue
+└── hooks/
+```
+
+全局资源存放在 `src/assets`。
+
+## 命名规范
+
+- **字符限制**：仅限小写字母、数字、下划线 `_`。
+- **格式**：`前缀_功能_描述_状态.扩展名`
+
+### 前缀对照表
+
+| 前缀          | 类型 | 说明        | 示例                     |
+| ------------- | ---- | ----------- | ------------------------ |
+| `ic` / `icon` | 图标 | 小图标、SVG | `ic_search.svg`          |
+| `bg`          | 背景 | 大图背景    | `bg_login.png`           |
+| `img`         | 图片 | 展示类图片  | `img_avatar_default.png` |
+| `btn`         | 按钮 | 按钮背景图  | `btn_submit_hover.png`   |
+
+### 示例
+
+- ❌ `box-truck.png` (使用了中划线)
+- ✅ `img_vehicle_box.png` (符合规范)
+- ✅ `bg_home_banner.jpg`
+- ✅ `ic_nav_home_active.svg`
+
+## 引用规范
+
+### Vue 组件 / TS 文件
+
+必须使用 `import` 导入资源，以确保构建工具能正确处理路径和 hash。
+
+```ts
+// 推荐
+import imgBox from './assets/img_vehicle_box.png'
+
+const list = [{ image: imgBox }]
+```
+
+或者使用 `new URL` (Vite 专用)：
+
+```ts
+const imgUrl = new URL('./assets/img_vehicle_box.png', import.meta.url).href
+```
+
+### CSS / SCSS
+
+使用相对路径引用。
+
+```scss
+.banner {
+  background-image: url('./assets/bg_home_banner.png');
+}
+```
+
+## 注意事项
+
+- **小文件内联**：Vite 默认会将 < 4kb 的资源内联为 base64。
+- **大文件处理**：对于较大的媒体文件，考虑使用 CDN 链接。

package/skills/references/component-spec.md

@@ -0,0 +1,88 @@
+---
+title: 组件规范
+description: Vue3 组件的开发规范、目录结构及 Props/Emits 定义,使用defineComponent定义组件,lang="tsx"语法
+category: 规范文档
+---
+
+# 组件规范
+
+## 使用场景
+定义 Vue 组件的开发规范，确保组件结构一致、可维护。
+
+## 基础使用
+
+### 组件组织
+| 类型 | 目录 | 说明 |
+|------|------|------|
+| 全局组件 | `src/components/` | 可在任意位置使用 |
+| 页面组件 | `src/views/<page>/components/` | 仅在当前页面使用 |
+
+> **注意**: 除非明确需要，否则不要创建全局组件。如果需要创建全局组件，请先询问用户确认。
+
+
+
+### 组件
+需要导出类型、逻辑复杂的组件，使用文件夹形式。
+
+```
+components/
+├── Demo
+│   ├── index.ts           # 导出组件和类型
+│   ├── types.ts           # 类型定义
+│   ├── Demo.vue           # 组件实现
+│   └── hooks/             # 组件 Hooks (可选,询问用户是否需要创建)
+│       └── useXXX.tsx
+```
+
+## 组件结构
+
+### 单文件组件
+```vue
+<script  lang="tsx">
+
+export default defineComponent({
+  name: 'MyComponent',
+  props: Props,
+  setup(props, { emit }) {
+    const onClick = (event: MouseEvent) => {
+      emit('click', event)
+    }
+    return {
+      render() {
+        return (
+          <div class='my-component'>
+            <button onClick={onClick} disabled={props.disabled}>
+              {props.title}
+            </button>
+          </div>
+        )
+      },
+    }
+  },
+})
+</script>
+
+<style scoped lang="scss">
+.my-component {
+  padding: 16px;
+}
+</style>
+```
+
+
+
+
+## Props.ts 定义
+
+```ts
+export let Props = {
+  title: String,
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+}
+```
+
+
+

package/skills/references/css-spec.md

@@ -0,0 +1,83 @@
+---
+title: CSS 规范
+description: BEM + SCSS + Tailwind CSS 组合方案及命名规范
+category: 规范文档
+---
+
+# CSS 规范
+
+## 核心原则
+
+1.  **组合使用**：项目采用 `BEM` + `SCSS` + `Tailwind CSS` 的组合方案,不使用元素选择器。
+2.  **命名空间**：CSS 类名使用中划线（kebab-case）命名。
+3.  **样式隔离**：组件样式**必须**使用 `scoped` 以防止污染。
+
+## 命名规范
+
+- CSS 类名统一使用中划线分隔，如 `.my-component`。
+- 特殊修饰符可使用双中划线 `--`，如 `.btn--primary`。
+
+## BEM 标准
+
+BEM (Block, Element, Modifier) 是项目主要采用的 CSS 模块化命名规范。
+
+### 结构
+
+| 概念                  | 描述             | 示例                                           |
+| --------------------- | ---------------- | ---------------------------------------------- |
+| **Block** (块)        | 独立的组件或模块 | `.warehouse`, `.vehicle-picker`                |
+| **Element** (元素)    | 块的组成部分     | `.warehouse__header`, `.vehicle-picker__title` |
+| **Modifier** (修饰符) | 状态或外观变体   | `.warehouse--active`, `.vehicle-picker--small` |
+
+### 最佳实践
+
+1.  **Block**：通常对应组件名。
+    ```scss
+    .vehicle-picker { ... }
+    ```
+2.  **Element**：使用双下划线 `__` 连接。
+    ```scss
+    .vehicle-picker__header { ... }
+    ```
+3.  **Modifier**：使用双中划线 `--` 连接。
+    ```scss
+    .vehicle-picker__card--selected { ... }
+    ```
+
+
+
+## Tailwind CSS (Atomic CSS)
+
+Tailwind CSS 用于快速实现原子样式，特别适合处理简单的布局、间距和工具类样式,不超过4个属性。
+
+### 使用场景
+
+- **布局与间距**：`flex`, `grid`, `m-4`, `p-2` 等。
+- **简单的工具样式**：`text-center`, `cursor-pointer`, `w-full`。
+- **避免过度使用**：对于复杂的组件业务样式，建议优先使用 BEM + SCSS，保持 HTML 的整洁性。
+
+### 常用语法
+
+- **宽度/高度**：`w-[100px]`, `h-full`, `w-1/2`
+- **边距**：`m-0` (margin: 0), `px-4` (padding-left/right: 1rem)
+- **Flex 布局**：`flex`, `flex-col`, `items-center`, `justify-between`
+- **颜色**：`bg-white`, `text-red-500`, `border-gray-200`
+
+### 示例
+
+```html
+<!-- 混合使用 BEM 和 Tailwind -->
+<div class="vehicle-picker flex flex-col h-full">
+  <!-- 复杂的使用 BEM  -->
+  <div class="vehicle-picker__header flex justify-between items-center p-4">
+    <!-- 简单的使用 Tailwind -->
+    <h2 class="text-xl font-bold">标题</h2>
+  </div>
+</div>
+```
+
+## 优先级
+
+1.  **组件结构样式**：优先使用 BEM + SCSS,不使用元素选择器。
+2.  **简单的样式**：4个css属性以内,直接使用 Tailwind CSS。
+3.  **动态样式**：优先使用css的var变量,然后使用 Vue 的 `:style` 或 `:class` 绑定。

package/skills/references/enum-naming.md

@@ -0,0 +1,99 @@
+---
+title: 枚举命名
+description: 创建枚举,修改枚举名,定义项目中枚举的命名规则。
+category: 命名规范
+---
+
+# 枚举命名
+
+## 使用场景
+定义项目中枚举的命名规则，确保枚举命名清晰、一致。
+
+## 基础使用
+
+### 命名规则
+- 枚举名使用 `Enum` 前缀（推荐）或后缀
+- 枚举名使用 `大驼峰` 命名法
+- 枚举属性使用 `大写 + 下划线`
+
+## 使用示例
+
+### enum 关键字
+```ts
+enum EnumYesOrNo {
+  YES = 1,
+  NO = 0,
+}
+```
+
+### as const 对象
+```ts
+const EnumStatus = {
+  SUCCESS: 1,
+  ERROR: 2,
+} as const
+
+```
+
+
+```ts
+// 状态标签映射
+export const USER_STATUS_LABELS = {
+  [EnumUserStatus.ACTIVE]: '启用',
+  [EnumUserStatus.INACTIVE]: '禁用',
+} as const
+```
+
+### 使用枚举
+```ts
+import { EnumUserStatus, USER_STATUS_LABELS } from './constants'
+
+// 判断状态
+if (user.status === EnumUserStatus.ACTIVE) {
+  // 用户已启用
+}
+
+// 获取标签
+const label = USER_STATUS_LABELS[user.status]
+```
+
+## 命名对照表
+
+| 类型 | 命名规范 | 示例 |
+|------|----------|------|
+| 枚举名 | `Enum` + 大驼峰 | `EnumUserStatus` |
+| 枚举属性 | 大写 + 下划线 | `ACTIVE`, `IN_PROGRESS` |
+| 标签映射 | 枚举名 + `Map` | `StatusMap`, `UserStatusMap` |
+| 枚举策略 | 枚举名 + `Strategy` | `StatusStrategy`, `UserStatusStrategy` |
+
+
+## 最佳实践
+
+```ts
+// 推荐：使用 as const 保持类型安全
+export const EnumStatus = {
+  SUCCESS: 1,
+  ERROR: 0,
+} as const
+
+// 推荐：提供标签映射
+export const StatusLabels = {
+  [EnumStatus.SUCCESS]: '成功',
+  [EnumStatus.ERROR]: '失败',
+}
+
+// 推荐：提供枚举策略
+export const StatusStrategy = {
+  [EnumStatus.SUCCESS]: {
+    label: StatusLabels[EnumStatus.SUCCESS],
+    render: (status: StatusType) => StatusLabels[status],
+  },
+  [EnumStatus.ERROR]: {
+    label: StatusLabels[EnumStatus.ERROR],
+    render: (status: StatusType) => StatusLabels[status],
+  },
+}
+
+// 推荐：提供类型导出
+export type StatusType = typeof EnumStatus[keyof typeof EnumStatus]
+```

package/skills/references/file-naming.md

@@ -0,0 +1,44 @@
+---
+title: 文件命名规范
+description: 创建文件,修改文件名,定义项目中各类文件的命名规则。
+category: 命名规范
+---
+
+# 文件命名规范
+
+## 使用场景
+
+创建文件,修改文件名,定义项目中各类文件的命名规则，确保文件命名一致、可识别。
+
+## 基础使用
+
+### 文件命名规则
+
+| 文件类型  | 命名规范          | 示例               |
+| --------- | ----------------- | ------------------ |
+| 入口页面  | `index.vue`       | -                  |
+| API 文件  | `api.ts`          | api.ts                  |
+| 路由文件  | `router.ts`       | -                  |
+| 类型文件  | `types.ts`        | -                  |
+| 常量文件  | `constants.ts`    | -                  |
+| 字典文件  | `dict.ts`         | -                  |
+| 工具文件  | `util.ts`         | -                  |
+| Hook 文件 | `use*.tsx`        | `useXX.tsx`     |
+| 组件文件  | `PascalCase.vue`  | `DemoTest.vue`   |
+| 样式文件  | `kebab-case.scss` | `bem-xxx.scss` |
+
+### 组件文件命名
+
+| 类型 | 命名规范                            | 示例                           |
+| ---- | ----------------------------------- | ------------------------------ |
+| 组件 | 文件夹 `PascalCase.vue`+ `index.ts` | `Button.vue`+`button/index.ts` |
+
+## 示例
+
+## 组件
+ 参考[组件规范](component-spec.md)
+
+
+### Hook 文件
+
+参考[Hook规范](hook-spec.md)

package/skills/references/folder-naming.md

@@ -0,0 +1,42 @@
+---
+title: 文件夹命名规范
+description: (新增/创建)文件夹时,或者修改文件夹名时,需要遵守的命名规范
+category: 命名规范
+---
+
+# 文件夹命名规范
+
+## 使用场景
+定义项目中文件夹,目录的命名规则，确保目录结构清晰、一致。
+
+## 基础使用
+
+### 命名规则
+- 使用 `小写字母`
+- 多个单词以 `中划线` 分隔,不能用驼峰,文件夹一定不要驼峰
+- 不超过 `三个单词`
+- 不超过 `20个字符`
+- 避免使用 `拼音、数字、特殊字符`
+
+### 示例对比
+
+| 推荐 | 不推荐 | 说明 |
+|------|--------|------|
+| `user-mgr` ,`sys-mgr`| `userMgr`,`sysMgr(不使用驼峰)` | 使用中划线分隔 |
+| `order-list` | `order_list` | 不使用下划线 |
+| `product-detail` | `productDetail2020` | 不使用数字 |
+| `sys-config` | `xitongpeizhi` | 不使用拼音 |
+
+## 特殊目录命名
+
+| 目录名 | 说明 |
+|--------|------|
+| `hooks` | Hook 函数目录 |
+| `components` | 组件目录 |
+| `assets` | 静态资源目录 |
+| `utils` | 工具函数目录 |
+| `types` | 类型定义目录 |
+| `api` | API 接口目录 |
+| `styles` | 样式文件目录 |
+| `constants` | 常量定义目录 |
+

package/skills/references/function-naming.md

@@ -0,0 +1,101 @@
+---
+title: function函数命名
+description: 新增/创建函数时,或者修改函数名时,需要遵守的命名规范
+category: 命名规范
+---
+
+# 函数命名
+
+## 使用场景
+
+定义项目中函数的命名规则，确保函数命名清晰、可理解。
+
+## 基础使用
+
+### 命名规则
+
+- 使用 `小驼峰` 命名法
+- 采用 `动作 + 特性` 结构
+- 动词在前，名词在后
+
+### 基本示例
+
+```ts
+// 设值、取值
+const setToken = (token: string) => {}
+const getToken = () => {}
+
+```
+
+## 函数类型命名
+
+### API 函数
+
+使用 `api` 前缀
+
+```ts
+const apiGetUserInfo = (id: string) => {
+  return Http.get({ url: `/user/${id}` })
+}
+
+const apiCreateUser = (data: UserFormData) => {
+  return Http.post({ url: '/user', data })
+}
+```
+
+### 事件函数
+
+使用 `on` 或 `handle` 前缀
+
+
+```ts
+// 点击事件
+const onClickEditBtn = (id: string) => {}
+// 键盘事件
+const onKeyUpEnter = () => {}
+// 通用处理
+const handleSearch = () => {}
+```
+
+### Hook 函数
+
+使用 `use` 前缀
+
+```tsx
+// 解构使用
+const { render } = useLoading()
+```
+
+### 渲染函数
+
+使用 `render` 前缀
+
+```tsx
+const renderLoadingIcon = () => {
+  return <Loading size={16} />
+}
+
+const renderEmpty = () => {
+  return <Empty description='暂无数据' />
+}
+```
+
+## 动词对照表
+
+| 动词                | 含义   | 示例                            |
+| ------------------- | ------ | ------------------------------- |
+| `get`               | 获取   | `getToken`, `getUserInfo`       |
+| `set`               | 设置   | `setToken`, `setConfig`         |
+| `add`               | 新增   | `addUser`, `addItem`            |
+| `delete` / `remove` | 删除   | `deleteUser`, `removeItem`      |
+| `update`            | 更新   | `updateUser`, `updateConfig`    |
+| `load`              | 加载   | `loadData`, `loadList`          |
+| `save`              | 保存   | `saveData`, `saveForm`          |
+| `submit`            | 提交   | `submitForm`, `submitOrder`     |
+| `show`              | 显示   | `showDialog`, `showLoading`     |
+| `hide`              | 隐藏   | `hideDialog`, `hideLoading`     |
+| `toggle`            | 切换   | `toggleMenu`, `toggleExpand`    |
+| `validate`          | 校验   | `validateForm`, `validateInput` |
+| `reset`             | 重置   | `resetForm`, `resetState`       |
+| `init`              | 初始化 | `initData`, `initConfig`        |
+| `fetch`             | 请求   | `fetchList`, `fetchDetail`      |

package/skills/references/hooks-spec.md

@@ -0,0 +1,131 @@
+---
+title:Vue3 定义 Hook 
+description: 新增/创建Hook时,或者修改Hook名时,需要遵守的命名规范,
+category: 规范文档
+---
+
+这里的hook,不是Composition API,是vue组件的替代版,免去`emit`,`props`,`attrs`传值问题
+
+## 禁止
+  - 不要创建`ts`结尾的,Composition API文件,只能创建`tsx`结尾的文件,返回对象包含`render`函数
+  - 不要创建`ts`结尾的,Composition API文件,也不要复用其他模块的Hook
+ 
+
+## hook规范要求
+| 类型                | 文件后缀 | 核心用途         | 返回值特征                  | 适用场景                            |
+| :------------------ | :------- | :--------------- | :-------------------------- | :---------------------------------- |
+| **Hook**            | `.tsx`   | **业务组件拆分** | 包含 `render` 函数          | 模块内的业务逻辑 + 视图渲染         |
+
+---
+
+## 一、Hook (.tsx)
+
+### 1. 定义与用途
+
+Hook 是功能模块内的业务单元。它不仅仅是逻辑的抽离，更是**视图组件的拆分**。
+
+- **内聚性**：将相关的业务逻辑和 `JSX` 视图封装在同一个文件中。
+- **模块化**：用于拆分复杂的 `index.vue` 入口文件，保持代码清晰。
+
+### 2. 规范要求
+
+- **文件后缀**：必须为 `.tsx`。
+- **返回值**：必须返回一个对象，且**必须包含 `render` 函数**,函数逻辑在 hook 内部实现，外部只调用 `render` 函数。
+- **状态管理**：使用 `useCtxState` 获取模块级共享状态。
+- **存放位置**：位于模块的 `hooks/` 目录下,vue中统一调用`hooks/index.ts`。
+
+### 3. 代码示例
+
+#### Hook 实现 (`hooks/useList.tsx`)
+
+```tsx
+import { ref } from 'vue'
+import { useCtxState } from '@allkit/use'
+import type { User, UserListState } from '../../types'
+
+export const useList = (openDialog: Function) => {
+  // 1. 获取共享状态
+  const [state,setState] = useCtxState<UserListState>()
+
+  // 定义仅当前hook内部使用的状态
+  let currState =reactive({
+    list:[]
+  })
+
+  // 2. 定义局部逻辑
+  const cols = [
+    { prop: 'id', label: '序号', width: 55 },
+    { prop: 'account', label: '账号' },
+  ]
+
+  const onClickAdd = () => openDialog(true)
+  const onClickEdit = (row: User) => openDialog(false, row)
+
+  // 3. 返回包含 render 的对象
+  return {
+    render: () => (
+      <>
+        <div class='toolbar'>
+          <ElButton type='primary' onClick={onClickAdd}>
+            新增
+          </ElButton>
+        </div>
+        <ElTable data={state.userList}>
+          {cols.value.map((col) => (
+            <ElTableColumn key={col.prop} {...col} />
+          ))}
+        </ElTable>
+      </>
+    ),
+  }
+}
+```
+
+#### 入口调用 (`index.vue`)
+
+```tsx
+import { defineComponent } from 'vue'
+import { defineCtxState } from '@allkit/use'
+/* 引入所有hooks */
+import { useList, useSearchForm } from './hooks'
+
+export default defineComponent({
+  setup() {
+    // 1. 初始化状态
+  let [state]=  defineCtxState<UserListState>({
+      /* ... */
+    })
+
+    // 2. 组合 Hooks
+    const { render: renderSearch } = useSearchForm()
+    const { render: renderList } = useList()
+
+    // 3. 布局渲染
+    return () => (
+      <div class='user-list'>
+        {renderSearch()}
+        {renderList()}
+      </div>
+    )
+  },
+})
+```
+
+---
+
+## 二、Composition API (.ts)
+
+### 1. 定义与用途
+
+Composition API 是纯粹的逻辑复用单元。它不包含任何 JSX 或视图代码。
+
+
+比如:
+- `useWindowSize`
+- `useScroll`
+- `useCssVar`
+
+公共库会定义好,我们只需要在业务模块中引入即可
+**注意**不需要去新创建ts结尾的hook。
+**注意**不需要去新创建ts结尾的hook。
+

package/skills/references/jsx-spec.md

@@ -0,0 +1,158 @@
+---
+title: JSX/tsx 规范
+description: Vue3 项目中 JSX/tsx 语法 的使用规范、语法对比及最佳实践
+category: 规范文档
+---
+
+# JSX/tsx 规范
+
+## 使用场景
+在 Vue3 项目中使用 JSX 语法，配合 Composition API 和 Hooks 实现更灵活的组件开发。
+
+## 参考
+- [Vue3 jsx 官方文档](https://cn.vuejs.org/guide/extras/render-function.html#jsx-tsx)
+
+## 基础语法对比
+
+### 1. 普通内容
+```jsx
+// JSX 写法
+setup() {
+  return () => <p type="email">hello</p>
+}
+
+// Template 写法
+<template>
+  <p type="email">hello</p>
+</template>
+```
+
+### 2. 动态变量
+```jsx
+// JSX 写法
+setup() {
+  let age = 1
+  return () => <div age={age}>{age}</div>
+}
+
+```
+
+### 3. 函数事件
+```jsx
+// JSX 写法
+setup() {
+  const age = ref(0)
+  const inc = () => age.value++
+  return () => <div onClick={inc}>{age.value}</div>
+}
+
+```
+
+### 4. Ref 绑定
+```jsx
+// JSX 写法
+setup() {
+  const divRef = ref(null)
+  return () => (
+    <div ref={divRef}>
+      <span>xxx</span>
+    </div>
+  )
+}
+```
+
+### 5. v-model 语法
+```jsx
+// JSX 写法
+setup() {
+  const age = ref(0)
+  const gender = ref('')
+  return () => (
+    <>
+      <tz-input v-model={age} />
+      <tz-input v-model:foo={age} />
+      <tz-input v-model:bar={gender} />
+    </>
+  )
+}
+
+```
+
+### 6. v-slots 语法
+对比`jsx`与 `template` 语法
+```jsx
+// JSX 写法
+const App = {
+  setup() {
+    return () => (
+      <A>
+        {{
+          default: () => <div>A</div>,
+          bar: () => <span>B</span>
+        }}
+      </A>
+    )
+  }
+}
+
+// Template 写法
+<template>
+  <A>
+    <template v-slot:bar>
+      <span>B</span>
+    </template>
+  </A>
+</template>
+```
+
+### 7. v-for 语法
+map循环需要添加`key`属性，否则会报错。
+```jsx
+// JSX 写法
+setup() {
+  const arr = ref([{ label: '1' }, { label: '2' }, { label: '3' }])
+  return () => (
+    <>
+      {arr.value.map(item => <span key={item.label}>{item.label}</span>)}
+    </>
+  )
+}
+
+
+```
+
+### 8. v-if 语法
+```jsx
+// JSX 写法
+setup() {
+  const show = ref(false)
+  return () => (
+    <>
+      {show && <span>test vif</span>}
+      {!show && <span>test velse</span>}
+    </>
+  )
+}
+
+```
+
+### 9. v-show 语法
+```jsx
+// JSX 写法
+setup() {
+  const show = ref(false)
+  return () => (
+    <>
+      <span v-show={show.value}>test vshow</span>
+    </>
+  )
+}
+
+```
+
+## 注意事项
+
+1. **ref 变量处理**：JSX 不会自动处理 `.value`，需要手动添加,所有少用ref定义变量
+2. **事件修饰符**：使用 `withModifiers` 实现 `.self`、`.stop` 等修饰符
+3. **插槽使用**：推荐使用对象形式传递插槽内容
+4. **多 v-model**：使用 `v-model:xx` 语法代替二维数组形式

package/skills/references/module-spec.md

@@ -0,0 +1,173 @@
+---
+title: 功能模块规范
+description: 项目中新增功能模块的目录结构、开发原则及最佳实践
+category: 规范文档
+---
+
+# 功能模块规范
+
+## 【核心开发原则 - 必读】
+
+在开发新模块时，**必须**严格遵守以下原则：
+
+1.  **文件结构**：
+    - 入口文件必须是 `index.vue`，且**必须**使用 `lang="tsx"`，**禁止**使用 `<template>`。
+    - 所有业务逻辑和子组件必须拆分为 `hooks/*.tsx`，**禁止**创建 `.vue` 后缀的子组件。
+    - 样式统一放在 `index.scss`，使用 BEM 规范。**禁止**使用 CSS Modules (`.module.scss`)。
+
+2.  **Hook 模式**：
+    - Hook 文件后缀必须是 `.tsx`。
+    - Hook 必须返回 `{ render: () => JSX }` 对象。
+    - 复杂模块需拆分为多个细粒度 Hook（如 `useFilter`, `useList`, `useFooter`），并在 `index.vue` 中组合。
+
+3.  **状态管理**：
+    - **必须**在 `index.vue` 中使用 `let [state, setState] = defineCtxState({})` 初始化模块级共享状态。
+    - **必须**在子 Hooks 中使用 `useCtxState` 获取`defineCtxState`共享的状态。
+    - 禁止在 Hooks 中使用散乱的 `ref` / `reactive` 管理全局状态。
+
+4.  **资源与命名**：
+    - 图片存放在模块 `assets` 目录，命名格式 `img_func_desc.png`，必须 `import` 引入。
+    - 事件处理函数命名使用 `onClickXxx` (点击) 或 `handleXxx` (通用)。
+
+---
+
+## 目录结构示例
+
+```
+demo/
+├── api.ts              # API 接口
+├── types.ts            # 类型定义(和入口文件在同一级目录)
+├── constants.ts        # 常量定义(可选)
+├── util.ts             # 工具函数(可选)
+├── index.vue           # 入口页面 (TSX)
+├── index.scss          # 样式文件 (BEM 规范)
+└── hooks/              # Hooks 目录 (业务逻辑拆分)
+    ├── index.ts        # 统一导出
+    ├── useList.tsx     # 列表渲染 Hook
+    └── useSearchForm.tsx # 搜索表单 Hook
+```
+
+## 代码示例
+
+### 1. 模块入口 (index.vue)
+
+- 使用 `defineComponent` + `lang="tsx"`。
+- 使用 `let [state, setState] = defineCtxState({})` 初始化状态。
+- 组合 Hooks 的 `render` 函数,并在 `vue` 中的tsx调用。
+
+```vue
+<script lang="tsx">
+import { defineComponent } from 'vue'
+import { apiGetUserList } from '../api'
+import { useList, useSearchForm } from './hooks'
+import type { UserListState } from '../types'
+import { defineCtxState } from '@allkit/use'
+
+export default defineComponent({
+  name: 'Demo',
+  setup() {
+    // 1. 初始化共享状态
+    let [state, setState] = defineCtxState<UserListState>({
+      userList: [],
+      listLoading: false,
+      searchForm: {},
+      pagination: { current: 1, size: 10, total: 0 },
+    })
+
+    const getSearchList = () => {
+      setState(state=>(state.name =1))
+      // ... 业务逻辑
+    }
+
+    // 2. 组合 Hooks
+    const { render: renderSearch } = useSearchForm(getSearchList)
+    const { render: renderList } = useList()
+
+    // 3. 返回渲染函数
+    return () => (
+      <div class='user-list'>
+        {renderSearch()}
+        {renderList()}
+      </div>
+    )
+  },
+})
+</script>
+
+<style lang="scss">
+@import './index.scss';
+</style>
+```
+
+### 2. 业务 Hook (hooks/useSearchForm.tsx)
+
+- `.tsx` 后缀。
+- 使用 `useCtxState` 获取`defineCtxState`共享的状态,内部的状态统一用`let currState =reactive({})`对象包裹 。
+- 返回包含 `render` 的对象。
+
+```tsx
+import { useCtxState } from '@allkit/use'
+import type { UserListState } from '../../types'
+
+export const useSearchForm = () => {
+  const [state, setState] = useCtxState<UserListState>()
+  //内部状态
+  let currState = reactive({
+    name: '',
+  })
+
+  const onClickSearchBtn = () => {
+    setState(state=>state.name=1)
+  }
+
+  const render = () => (
+    <div class='search-form'>
+      {/* 使用 state.searchForm */}
+      <input
+        type='text'
+        placeholder='请输入姓名'
+        value={currState.name}
+        onChange={(e) => (currState.name = e.target.value)}
+      />
+      <button onClick={onClickSearchBtn}>搜索</button>
+    </div>
+  )
+
+  return {
+    render
+  }
+}
+```
+
+### 3. 类型定义 (types.ts)
+
+```ts
+export interface User {
+  id: string
+  name: string
+}
+
+export interface UserListState {
+  listLoading: boolean
+  userList: User[]
+  searchForm: Partial<User>
+  pagination: {
+    current: number
+    size: number
+    total: number
+  }
+}
+```
+
+## 模块职责划分
+
+| 文件/目录        | 职责                                    | 备注 |
+| ---------------- | --------------------------------------- | ---- |
+| `index.vue`      | 页面入口、状态初始化、Hook 组合与布局   | 必选 |
+| `hooks/*.tsx`    | 具体的业务逻辑与 UI 片段 (Logic + View) | 可选 |
+| `hooks/index.ts` | 统一导出所有 Hooks                      | 可选 |
+| `api.ts`         | API 接口定义                            | 可选 |
+| `types.ts`       | 类型定义 (State, Entity)                | 必选 |
+| `index.scss`     | 样式文件 (BEM)                          | 可选 |
+| `dict.ts`        | 枚举定义,map映射 (可选)                  | 可选 |
+| `constants.ts`   | 常量定义 (可选)                         | 可选 |

package/skills/references/variable-naming.md

@@ -0,0 +1,77 @@
+---
+title: 变量命名
+description: 项目中变量的ts,js代码命名规则及最佳实践
+category: 命名规范
+---
+
+# 变量命名
+
+## 使用场景
+定义项目中变量的命名规则，确保代码可读性和一致性。
+
+## 基础使用
+
+### 命名规则
+- 使用 `小驼峰` 命名法
+- 使用 `单词全称`，避免缩写
+- 不超过 `20个字符`
+- 使用规范的前后缀
+
+### 基本示例
+```ts
+const fileName = ''
+const vueRouter = {}
+const orderList = []
+const useHook = () => {}
+```
+
+## 类型命名规范
+
+### 数组命名
+使用 `List`、`Array` 后缀或单词复数
+
+| 推荐 | 不推荐 |
+|------|--------|
+| `orderList` | `orders` |
+| `userArray` | `userArr` |
+| `items` | `itemList` |
+
+### 对象命名
+使用 `Object`、`Obj`、`Data`、`Info` 后缀
+
+| 推荐 | 不推荐 |
+|------|--------|
+| `userInfo` | `user` |
+| `formData` | `form` |
+| `orderObj` | `order` |
+
+### 布尔值命名
+使用 `is`、`has`、`can` 前缀
+
+| 前缀 | 含义 | 示例 |
+|------|------|------|
+| `is` | 是不是 | `isEmpty`, `isLoading` |
+| `has` | 有没有 | `hasPermission`, `hasError` |
+| `can` | 能不能 | `canEdit`, `canDelete` |
+| `show` | 显示状态 | `showDialog`, `showLoading` |
+
+### 数字命名
+使用 `Count`、`Total`、`Num` 后缀
+
+```ts
+const fileCount = 10
+const rowTotal = 100
+const pageNum = 1
+const limit = 20
+```
+
+
+## 命名对照表
+
+| 类型 | 前缀/后缀 | 示例 |
+|------|-----------|------|
+| 数组 | `List`, `Array` | `orderList`, `userArray` |
+| 对象 | `Info`, `Data`, `Obj` | `userInfo`, `formData` |
+| 布尔 | `is`, `has`, `can` | `isEmpty`, `hasError` |
+| 数字 | `Count`, `Total`, `Num` | `totalCount`, `pageTotal` |
+| 响应式 | `State`, `Ref` | `currState`, `inputRef` |