5.1 KiB
5.1 KiB
开发框架约束（供 AI 创建项目使用）
目的：本文件用于约束 AI 在创建/改造项目时的技术选型、目录结构、工程化与交付流程。除非明确得到人工指令，否则 AI 不得偏离本文件的约束。
- 运行环境与基础约束
- Node.js 版本：必须使用 Node.js 22+（建议使用最新 LTS）。
- 主要语言：JavaScript（.js）为主。
- 允许在必要时引入类型检查方案（例如 JSDoc + // @ts-check），但默认不将 TypeScript 作为主要语言。
- 包管理器：强制统一使用
npm。 - 跨平台：默认需兼容 Windows（PowerShell）与类 Unix 环境。
- 技术栈约束
2.1 前端（如需要前端）
- 框架：必须使用 Vue 3.x。
- 生态库：仅引入与 Vue 3.x 兼容的相关库；避免引入与 Vue 2.x 绑定的历史库。
- 构建工具： Vite（如与既有工程冲突，需说明原因并保持一致性）。
- ui-ux-pro-max美化必需遵守： Create a playful educational platform landing page with claymorphism cards, course catalog preview, progress tracking demo, student testimonials, and enrollment CTA. Use vibrant, engaging colors.
2.2 后端（如需要后端）
- 运行时：必须使用 Node.js。
- 语言：后端同样以 JavaScript 为主。
- API 风格：默认使用 HTTP JSON API（如采用 GraphQL/WebSocket 等需明确说明并仍遵循 OpenSpec 约束）。
- OpenSpec（规范驱动）开发流程约束
说明：这里的 OpenSpec 指通过全局安装
@fission-ai/openspec获得的规范驱动工具链；在 API 场景下，接口契约必须使用并遵守 OpenAPI 3.1。两者不冲突：OpenSpec 用于驱动/校验流程，OpenAPI 3.1 是规范文件中必须满足的契约。
3.0 OpenSpec 工具链安装（强制）
-
开发与 CI 环境必须确保可用的 OpenSpec 工具链：
- 安装命令：npm install -g @fission-ai/openspec@latest
-
AI 在生成项目脚本时：
- 必须将规范校验能力接入到 npm scripts（见 3.3）。
- 不得绕过 OpenSpec 校验直接交付“未受规范约束”的 API 实现。 3.1 必须交付的规范产物
-
项目必须包含一个可追溯的规范文件：
- API 项目：
spec/openapi.yaml（或spec/openapi.json），版本 OpenAPI 3.1。
- API 项目：
-
非 API 项目：仍需提供对应的“规格说明”（例如流程/数据结构/输入输出契约），放在 spec/ 目录下。
-
规范文件需满足：
- 可被校验（lint/validate）
- 与实现一致（实现变更必须同步更新规范） 3.2 开发顺序（强制）
- 先写/更新规范（spec-first）：在新增/修改功能前，先更新
spec/下的规范。 - 再实现：实现必须与规范一致。
- 再验证：CI/本地脚本必须包含规范校验步骤。
- 再文档化：README 中必须说明如何查看/使用规范与如何运行校验。
3.3 规范校验与联动（强制）
- 必须提供脚本（示例命名，可按项目调整但不可缺失）：
- npm run spec:lint：调用 OpenSpec 对 spec/ 做 lint（具体 CLI 参数以 openspec --help 为准）
- npm run spec:validate：调用 OpenSpec 对 spec/ 做结构/引用/契约校验（具体 CLI 参数以 openspec --help 为准）
- 若为 API：
- 必须在实现层提供请求/响应校验或至少在测试阶段进行契约校验。
- 鼓励（非强制）从 OpenAPI 生成 client/server stub 或生成类型定义，但不得改变“JS 为主语言”的前提。
- 工程结构约束（建议默认）
AI 创建项目时，默认使用以下结构；如项目类型不适用，可在不违背约束的前提下做最小调整。
- spec/：OpenSpec 规范（OpenAPI 或其他规格说明）
- src/：源代码
- tests/：测试
- scripts/：工程脚本（构建/校验/生成等）
- README.md：必须包含运行、测试、规范使用方式
- 质量与交付约束（强制）
- 必须提供基础脚本：
- npm run dev（如可交互开发）
- npm run build（如需要构建）
- npm run test
- npm run lint
- 变更要求：
- 修改实现时同步更新 spec/ 与测试。
- 不得只改实现不改规范；也不得只改规范不改实现。
- AI 行为约束（强制）
- 若用户需求与本文件冲突：
- 先指出冲突点，并请求用户确认是否允许偏离约束。
- 未明确要求时：
- 不引入与约束无关的“额外页面/功能/组件/花哨配置”。
- 保持最小可用、可验证、可维护的实现。
- 发布版本号约束（强约束）
- 每次发布必须迭代版本号，并同步更新以下位置（缺一不可）：
- 后端版本：
apps/server/package.json - Web 版本：
apps/web/package.json - 插件版本：
apps/extension/package.json - 插件清单版本：
apps/extension/public/manifest.json
- 后端版本：
- 发布后必须验证构建产物里的插件版本已更新：
apps/extension/dist/manifest.json。 - 当前统一版本从 1.0.0 开始。
- 默认规则：仅递增最后一位（patch），例如 1.0.0 → 1.0.1 → 1.0.2。
- 只有在用户明确要求时，才允许变更中间位（minor）；否则不得修改。