e617e303d4
- add .trae/rules/git-commit-message.md with official commit rules - update AGENTS.md to add Chinese commit message requirement - overhaul README.md: update tech stack, directory structure, env vars, routing, i18n and request lib docs
3.5 KiB
3.5 KiB
项目协作指南
本仓库是一个基于 Vite 的 H5 Web 项目。本文档用于约束自动化 Agent 在仓库内的工作方式、目录约定与验证流程。
技术栈与入口
- 构建：Vite 5（ESM，
package.json中"type": "module"） - 框架：Vue 3 + TypeScript
- 路由：vue-router 4（入口为
src/router/index.ts，当前路由配置较少/可能未完成） - 状态管理：Pinia（
src/stores/） - UI：Vant 4
- 样式：Tailwind CSS v4（通过
@tailwindcss/vite），并存在组件级 SCSS - 国际化：vue-i18n（
src/i18n/，含 Vant 语言同步） - 网络/事件：axios、mitt
入口文件：
- 应用入口：
src/main.ts - 根组件：
src/App.vue（<RouterView />） - 全局样式/主题：
src/styles/main.css
目录结构与新增代码放置
- 页面：
src/pages/<module>/... - 公共组件：
src/components/<ComponentName>/... - 国际化：
src/i18n/- 语言包按模块拆分：
src/i18n/modules/{common,home,quick}/
- 语言包按模块拆分：
- 工具/请求：
src/utils/（当前存在requets.ts，文件名可能为历史拼写；不要在未确认引用关系前擅自更名）
组件目录常见形态（尽量遵循）：
src/components/Foo/index.vuesrc/components/Foo/styles/index.scss- 可选：
README.md、demo.vue、prompt.md、images/
代码风格约定
- Vue 组件优先使用
<script setup lang="ts"> - 组件样式优先放在同目录
styles/index.scss，并在组件内通过lang="scss"+scoped方式引入/编写 - 全局主题与 Vant CSS 变量覆盖集中在
src/styles/main.css，避免把全局变量散落到页面/组件中 - TypeScript：开启
strict、noUnusedLocals、noUnusedParameters等约束；新增代码需保持零 TS 报错 - 路径别名：
@/* -> src/*（TS 与 Vite 均配置），新增引用优先使用@/形式
本仓库未集成 ESLint/Prettier 等统一格式化工具：变更时以“周边现有代码”为准保持一致性。
开发、构建与测试（变更后必须执行）
使用 Yarn。
- 安装依赖：
yarn - 本地开发：
yarn dev（Vite dev server，端口 5174） - 类型检查：
yarn typecheck - 构建：
yarn build（包含vue-tsc --noEmit） - 预览：
yarn preview - 测试：
yarn test（Node 原生 test runner，匹配src/**/*.test.ts）
说明：
tsconfig.json排除了src/**/*.test.ts，测试文件如需 TS 类型支持，请在测试内保持自包含，或按项目既有方式处理
修改流程（Agent 工作方式）
- 先定位：优先通过搜索/阅读定位真实调用链与使用方，再进行修改
- 小步提交：单次变更聚焦一个问题点；避免“顺手重构”影响范围
- 保守增依赖：不要新增第三方依赖或升级版本；确有必要时先征询确认并说明替代方案
- 不破坏接口：组件 props/事件/样式类名若被页面依赖，变更需兼容旧用法或同步修改所有调用点
- 变更必验证：完成代码修改后至少运行
yarn typecheck；涉及构建与运行差异时再运行yarn build与相关测试 - 开发计算时，有临时分支，需要提醒用户选择分支合并
限制条件
- 不要废话
- 不要缺失代码
- 不要出现伪需求
- 没有提及的代码不要修改
- 需要编译时就提醒用户手动确定
- 需要测试时就提醒用户手动执行
- 有滚动条的区域，需要添加scrollbar-none [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden 类名
- git 提交时，必须使用中文提交信息