ray-template/docs/ai-development.md
2026-11-03 14:40:53 +08:00

7.2 KiB
Raw Blame History

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_* 环境变量。

参考:官方 AGENTS.md 规则、Vue TypeScript 指南。