2026-01-21 23:09:33 +08:00
|
|
|
|
开发框架约束（供 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 行为约束（强制）
|
|
|
|
|
|
|
|
|
|
|
|
- 若用户需求与本文件冲突：
|
|
|
|
|
|
- 先指出冲突点，并请求用户确认是否允许偏离约束。
|
|
|
|
|
|
- 未明确要求时：
|
|
|
|
|
|
- 不引入与约束无关的“额外页面/功能/组件/花哨配置”。
|
2026-01-23 23:55:08 +08:00
|
|
|
|
- 保持最小可用、可验证、可维护的实现。
|
|
|
|
|
|
|
|
|
|
|
|
7. 发布版本号约束（强约束）
|
|
|
|
|
|
|
|
|
|
|
|
- **每次发布必须迭代版本号**，并同步更新以下位置（缺一不可）：
|
|
|
|
|
|
- 后端版本：`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）；否则不得修改。
|
