开发框架约束（供 AI 创建项目使用）

目的：本文件用于约束 AI 在创建/改造项目时的技术选型、目录结构、工程化与交付流程。除非明确得到人工指令，否则 AI 不得偏离本文件的约束。

1. 运行环境与基础约束

- Node.js 版本：必须使用 Node.js 22+（建议使用最新 LTS）。
- 主要语言：JavaScript（.js）为主。
- 允许在必要时引入类型检查方案（例如 JSDoc + // @ts-check），但默认不将 TypeScript 作为主要语言。
- 包管理器：**强制统一使用 `npm`**。
- 跨平台：默认需兼容 Windows（PowerShell）与类 Unix 环境。

2. 技术栈约束

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 约束）。

3. 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 项目：仍需提供对应的“规格说明”（例如流程/数据结构/输入输出契约），放在 spec/ 目录下。
- 规范文件需满足：
  - 可被校验（lint/validate）
  - 与实现一致（实现变更必须同步更新规范）
3.2 开发顺序（强制）

1. 先写/更新规范（spec-first）：在新增/修改功能前，先更新 `spec/` 下的规范。
2. 再实现：实现必须与规范一致。
3. 再验证：CI/本地脚本必须包含规范校验步骤。
4. 再文档化：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 为主语言”的前提。
4. 工程结构约束（建议默认）

AI 创建项目时，默认使用以下结构；如项目类型不适用，可在不违背约束的前提下做最小调整。

- spec/：OpenSpec 规范（OpenAPI 或其他规格说明）
- src/：源代码
- tests/：测试
- scripts/：工程脚本（构建/校验/生成等）
- README.md：必须包含运行、测试、规范使用方式
5. 质量与交付约束（强制）

- 必须提供基础脚本：
  - npm run dev（如可交互开发）
  - npm run build（如需要构建）
  - npm run test
  - npm run lint
- 变更要求：
  - 修改实现时同步更新 spec/ 与测试。
  - 不得只改实现不改规范；也不得只改规范不改实现。
6. AI 行为约束（强制）

- 若用户需求与本文件冲突：
  - 先指出冲突点，并请求用户确认是否允许偏离约束。
- 未明确要求时：
  - 不引入与约束无关的“额外页面/功能/组件/花哨配置”。
  - 保持最小可用、可验证、可维护的实现。