nex_design_system/docs/13-project-stack-defaults.md

4.6 KiB
Raw Blame History

13. Project Stack Defaults

1. 目的

NEX 0.1.5 修正 0.1.4 的一个问题:降低配置填写量,不等于移除新项目的技术选型。

新项目需要有明确、可执行的技术栈默认值。Agent 不应在空项目中自行猜测前后端框架、数据库或 UI 组件库;也不应要求用户从零填写整张技术清单。

因此,NEX 采用两种不同策略:

  • 新项目(New):nex.config.yaml 中的默认技术栈就是默认实施目标。只有用户明确覆盖时才使用其他选型。
  • 已有项目(Existing):真实代码、锁文件和构建配置代表当前技术事实。默认技术栈仅供参考,不得据此擅自迁移或替换现有技术。

2. 默认全栈方案

config/project-profile.example.yaml 提供以下默认方案:

层次 默认技术 用途
前端框架 React Web UI
前端语言 TypeScript 类型安全
构建工具 Vite 开发与构建
包管理器 npm 依赖管理
UI 组件库 Ant Design 企业级基础组件
样式方案 Tailwind CSS v4 + CSS Variables 布局工具类与语义化设计变量
状态管理 Zustand 跨组件状态
路由 React Router 前端路由
HTTP 客户端 Axios API 通信
后端语言 Python 服务端开发
后端框架 FastAPI REST API
数据校验 Pydantic 请求/响应模型
ORM SQLAlchemy 数据访问
数据库迁移 Alembic Schema 版本管理
开发数据库 SQLite 本地开发与轻量部署
生产数据库 PostgreSQL 生产持久化
API 风格 REST + OpenAPI 接口契约
本地静态资源 ./data 媒体及文件资源
前端质量工具 ESLint、Prettier、Vitest、Playwright 代码、格式、单测和端到端测试
后端测试 Pytest 后端测试

具体依赖版本采用创建时兼容的稳定版本,并必须提交 lockfile。不得使用无版本约束的通配符依赖;具体版本选择应考虑所选框架、组件库和插件之间的兼容性。

3. 项目类型

默认 project.type: fullstack。

如项目不是全栈,只需修改一个字段:

project:
  type: frontend-only

或:

project:
  type: backend-only

不适用的部分不应初始化。例如 frontend-only 不应创建无用的 FastAPI 服务;backend-only 不应创建 React 前端。

4. 生命周期自动识别

默认 project.lifecycle: auto:

  • 空仓库或尚无实际应用代码:按 new 处理,采用默认技术栈。
  • 已存在可识别的应用代码、锁文件或构建配置:按 existing 处理,以当前代码为准。
  • 仓库状态模糊且会影响是否创建/迁移技术栈时,先进行只读检查;必要时提出一个明确问题,不得擅自覆盖。

也可以手动设置 new 或 existing。

5. 覆盖默认技术栈

用户不需要填写整套配置。只需修改不符合当前项目意图的字段。例如希望使用 PostgreSQL 作为开发数据库:

stack:
  database:
    development: PostgreSQL
    production: PostgreSQL

例如希望采用其他 UI 方案:

stack:
  frontend:
    ui_library: None
    styling: Tailwind CSS v4 + CSS Variables

实际修改时应保留完整 YAML 层级,并仅覆盖有意变更的值。Agent 不得将未修改字段理解为“未指定”。

6. 新项目与已有项目的执行规则

New

  • 将 stack 视为技术选型约束,不要自行替换。
  • 根据 project.type 初始化对应层次。
  • 在创建代码前确认依赖兼容性、目录结构和本地运行方式。
  • 可以提出必要的安全/部署问题,但不要重复询问配置里已经明确给出的技术选型。
  • 如发现某项默认方案与明确需求冲突,先说明冲突并提出最小调整,不得静默改变栈。

Existing

  • 以锁文件、依赖清单、源码、构建配置和运行结果确认当前技术栈。
  • 将自动发现结果写入审计报告,并与默认 profile 对比。
  • 不因默认方案与现状不同而升级、替换或迁移。
  • 只有用户明确授权技术迁移时,才制定单独迁移方案。

7. NEX 不统一项目技术栈的边界

以上是新项目的默认起步方案,不是对所有项目的强制技术栈。

用户可以通过少量字段覆盖默认值;已有项目可以完整保留自己的技术选型。NEX Core 仍然约束设计质量、组件复用、Token 单一来源、交互一致性、可访问性、响应式和质量证据,而不要求所有项目都采用同一套框架。