7.2 KiB
AI 辅助开发
本轮建设用于让 AI 助手理解和验证现有工程;没有接入模型服务,也没有在页面增加聊天功能。
首次使用
下面以 nvm 为例;使用 fnm 时,将前两行替换为 fnm install && fnm use。
nvm install
nvm use
npm install --global pnpm@12.16.1
pnpm install --frozen-lockfile
pnpm env:check
pnpm dev
开发地址为 http://127.0.0.1:9527/ray-template/。需要局域网访问时显式运行 pnpm dev --host 0.0.0.0。当前固定环境以 .nvmrc 和 package.json#packageManager 为准,不要通过全局升级所有用户项目来解决本工程的问题。
Codex 自动读取根目录 AGENTS.md;Cursor、Copilot 和 Claude 的项目入口也指向同一份规则。新对话只需提供目标、影响页面或报错、预期行为、约束和验收条件,无需粘贴整个仓库。
编写或修改注释时统一遵循 注释规范,由 AGENTS.md 引入。组件说明放在 README 和示例页;函数契约、模块声明与内部逻辑使用各自规定的形式,不在工具适配文件重复维护规范。
命令契约
| 命令 | 用途与结果 |
|---|---|
pnpm env:check |
检查 Node、pnpm 和依赖安装状态,失败时返回非零退出码并提示修复方式 |
pnpm typecheck |
检查应用、测试、Node 构建配置和 Mock 类型,不生成 JS 或声明文件 |
pnpm lint |
检查代码与 Vue 规则,不改文件;warning 也会失败 |
pnpm format:check |
检查格式,不改文件 |
pnpm lint:fix |
显式自动修复可修复的代码规范问题 |
pnpm format |
显式格式化受管文件;历史 CHANGELOG、生成声明和静态素材由 ignore 排除 |
pnpm test |
本地交互监听;按提示退出 |
pnpm test:run |
单次执行完整回归测试,适合 AI 和 CI |
pnpm test:run -- __test__/hooks/usePagination.spec.ts |
只运行指定回归文件 |
pnpm test:ui |
开启 Vitest 可视化界面 |
pnpm build |
类型检查并生成 dist/production |
pnpm dev-build |
生成含 sourcemap 的 dist/development |
pnpm preview |
本地预览生产产物,不能作为正式服务器 |
pnpm report |
生成体积分析,非交互模式,不自动打开浏览器 |
pnpm check |
依次运行环境、类型、lint、格式、单测和生产构建,任一步失败即停止 |
命令不接收业务参数;Vite/Vitest 参数使用对应 CLI 选项。日志来自各工具,退出码 0 表示本项检查通过。pnpm check 的生产产物写入 dist/production,需要保留源码之外的临时证据时放入 .ai-local/。
TypeScript 项目配置
根目录的 tsconfig.json 用项目引用组织三个检查单元。严格模式、模块解析和 TypeScript 路径别名集中在 tsconfig.base.json。Vite 的运行时别名在 vite.custom.config.ts,更改别名时同步更新两处。
| 配置 | 检查范围 | 环境 |
|---|---|---|
| tsconfig.app.json | src 和自动生成的 Vue 声明 |
浏览器、Vue JSX 和 Vite 客户端 |
| tsconfig.node.json | Vite、Vitest、UnoCSS 配置,vite-helper 和 mock |
Node.js |
| tsconfig.test.json | __test__ 及测试所引用的源码 |
应用类型、Happy DOM、Node.js 和 Vitest 全局类型 |
项目的 types 列表控制自动加载的环境声明。依赖也能通过自身声明引入其他类型,例如 vite-svg-loader 的声明引用 Vite 的 Node 类型。
pnpm typecheck 通过 vue-tsc --build 检查全部项目,增量缓存存放在 .ai-local/。需要从头检查时运行 pnpm exec vue-tsc --build --force。单独检查应用或测试可用 pnpm exec vue-tsc -p tsconfig.app.json 或 pnpm exec vue-tsc -p tsconfig.test.json,Node 配置可用 pnpm exec tsc -p tsconfig.node.json。VS Code 应通过工作区的 TypeScript 版本读取这些配置。
给 AI 的任务示例
请按 AGENTS.md 完成:修复 RTablePro 切换每页条数后未回到第一页的问题。
先追踪 usePagination、useTablePro 和调用方,保留现有公开 API。
新增覆盖页码与回调次数的回归测试,运行 pnpm check。
交付说明实际通过的验证,以及需要浏览器确认的交互。
依赖升级任务应包含:查询 npm 稳定版本、核对 peerDependencies 和官方迁移说明、修改配置与调用方、更新锁文件、运行 pnpm check,再验证对应页面。TypeScript 7 的已知阻塞见 工具链升级记录,不要为了追到最新版本关闭类型检查。
验收与持续维护
- CI 在 Linux、Windows、macOS 使用相同 Node/pnpm 和
pnpm check,PR 只检查;main的 push 在所有检查通过后才更新dist部署分支。 - Dependabot 每周提出 npm 与 Actions 更新 PR;大版本仍需阅读迁移说明并验证,不会自动合并。
- Husky 在提交前只处理暂存文件,并校验 commit message。AI 代码和人工代码使用相同门槛。
- 页面验收覆盖登录、菜单/权限、页面缓存、明暗主题、中英文、图表、表格和修改涉及的演示页。说明具体浏览器与检查范围。
- 不把测试通过等同于真实鉴权、微前端宿主、生产后端或 Docker 部署成功;无法验证的部分在交付中明确说明。
本工程不需要模型 API key。后续若增加产品 AI 功能,需要先明确后端代理、数据边界、费用和评估标准;服务端密钥不得放入 VITE_* 环境变量。