Add interactive hook examples, shared Pinia runtime state, and configurable layouts. Generate typed namespaced icons during development, HMR, and builds. Refine the UI and establish project comment and design conventions. Validation: typecheck, ESLint, 181 tests, and production build passed.
5.6 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 |
检查应用、测试和 Vite 配置类型,不输出构建文件 |
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/。
给 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_* 环境变量。