60 lines
6.2 KiB
Markdown
60 lines
6.2 KiB
Markdown
---
|
||
description:
|
||
globs:
|
||
alwaysApply: true
|
||
---
|
||
# GitHub Copilot Instructions
|
||
|
||
本文件定义了项目的代码生成规范,GitHub Copilot 和其他 AI 助手应遵循这些指令。
|
||
|
||
This document outlines the core technical choices, coding conventions, and configuration details for this project. Adhering to these guidelines ensures consistency and leverages the project's setup effectively.
|
||
|
||
## 🚀 Core Technologies & Conventions
|
||
|
||
* **Framework:** Vue 3
|
||
* **Language:** TypeScript
|
||
* **API Style:** **Strictly use the Composition API with `<script setup>` syntax.** The Options API and the standard `<script>` block with the `setup()` function are **not** used in this project.
|
||
* **Single File Component (SFC) Structure:** Follow this order within `.vue` files:
|
||
1. `<script setup lang="ts">` (Imports, logic, composables, etc.)
|
||
2. `<template>` (HTML structure)
|
||
3. `<style>` (Preferably `<style scoped>`)
|
||
* **Code Comments:**
|
||
* All comments within the codebase **must be written in Chinese**. (代码中的所有注释**必须使用中文**。)
|
||
* **注释应解释代码的“为什么”(设计意图、选择某方案的原因)或复杂逻辑/算法的“如何”,而不是解释“是什么”(重复代码功能)或“在哪里”(描述定义位置)。**
|
||
* **严禁添加仅说明代码被移动、重构或提取到其他文件的注释。** 例如,避免 `// XxxState 接口已移至 types.ts` 或 `// 提取为 useXYZ composable` 这样的注释。依赖代码结构、类型系统和 IDE 功能(如 Go To Definition)来理解这些信息,而不是通过注释。Focus comments on the *logic* itself, not its location or history.
|
||
* **同样地,严禁添加描述代码是“新增”、“修改”、“临时”或标记其开发状态的注释。** 例如,避免 `// 新增功能`、`// (新增)`、`// 临时修复`、`// TODO: 优化`(除非 TODO 指向具体的技术债务或未完成的逻辑,而不仅仅是标记状态)等注释。注释的目标是解释代码的内在逻辑或设计决策,而不是其变更历史或当前状态。
|
||
|
||
## 📦 UI Libraries & Components
|
||
|
||
* **UI Libraries:** This project utilizes both **Ant Design Vue** and **PrimeVue**.
|
||
* **Component Auto-Import:** Components from Ant Design Vue, PrimeVue, and those defined in `src/components/**/*.vue` (excluding filenames starting with `__`) are **automatically imported** via `unplugin-vue-components`.
|
||
* **Ant Design Vue:** Use components directly (e.g., `<a-button>`, `<a-table>`). Icons are also resolved (e.g., `<UserOutlined />`). CSS-in-JS is used; no manual style import is needed.
|
||
* **PrimeVue:** Use components directly with their standard names (e.g., `<Button>`, `<InputText>`, `<DataTable>`).
|
||
* **Custom Components:** Local components (e.g., `<MyCustomComponent />` defined in `src/components/MyCustomComponent.vue`) should be used directly in templates without explicit imports in `<script setup>`.
|
||
* **Custom Icons:** Custom SVG icons are available via `unplugin-icons` with the prefix `icon-`. Usage: `<icon-your-svg-file-name />`.
|
||
* **No Auto-Import Comments for Components:** When using auto-imported components (UI libraries, local components), **do not** add comments indicating they are auto-imported. Assume this behavior is known. Trust the tooling.
|
||
|
||
## ✨ API Auto-Import (unplugin-auto-import)
|
||
|
||
* **Automatic API Availability:** This project leverages `unplugin-auto-import` extensively. APIs from the following libraries/modules are globally available and **SHOULD NOT be explicitly imported** in `<script setup>` blocks unless necessary for specific type augmentation or rare cases:
|
||
* `vue` (e.g., `ref`, `computed`, `watch`, `onMounted`, `defineProps`, `defineEmits`, etc.)
|
||
* `pinia` (e.g., `defineStore`, `storeToRefs`)
|
||
* `vue-router/auto` (e.g., `useRouter`, `useRoute`, `useLink`) - Provided by `unplugin-vue-router` integration.
|
||
* `@vueuse/core` (Common utility functions)
|
||
* `vue-i18n` (e.g., `useI18n`)
|
||
* `consola/browser` (Available as the `consola` global for logging)
|
||
* **Auto-Imported Directories:** All exports from files within `src/stores/**` and `src/utils/**` are also auto-imported globally. Functions, variables, or stores defined and exported in these directories can be used directly without explicit import statements.
|
||
* **Template Usage:** Auto-import functionality also applies within the `<template>` block where appropriate (e.g., accessing store state or using certain utility functions directly).
|
||
* **Important:** Rely on the auto-import mechanism for the specified libraries and directories. Explicitly importing these APIs clutters the code unnecessarily.
|
||
* **No Auto-Import Explanation Comments:** When using auto-imported APIs (from libraries like Vue, Pinia, VueUse, or custom directories like `src/utils`, `src/stores`), simply use them directly. **Absolutely avoid adding comments that merely state an item is auto-imported** (e.g., DO NOT add comments like "// xxx is auto-imported from src/utils"). Focus comments on explaining complex logic or intent.
|
||
|
||
## ✅ Summary of Key Rules & Conventions
|
||
|
||
* **Always** use `<script setup lang="ts">`.
|
||
* Composition API is the **only** accepted style.
|
||
* Code comments **must be in Chinese** and explain **why/how (logic, intent)**, **strictly avoiding** comments that explain **what (code repetition), where (definition location), refactoring history, code status (e.g., 'new', 'modified'), or auto-import mechanisms.**
|
||
* Vue 3 Composition API, Pinia, Vue Router (auto), VueUse functions, `consola`, and exports from `src/stores` & `src/utils` are globally available via auto-import; **do not** import them explicitly.
|
||
* Ant Design Vue, PrimeVue, and local `src/components` components are auto-imported; use them directly in templates without explicit imports.
|
||
* **Crucially: Do not add comments solely to explain that an API or component is auto-imported OR where code has been moved/refactored OR the status of the code (e.g., 'new').** Trust the auto-import setup and IDE navigation. Focus on logic.
|
||
* Use custom SVG icons via the `<icon-name />` syntax.
|
||
* Maintain the specified SFC structure: `<script setup>`, `<template>`, `<style>`. |