4.6 KiB
4.6 KiB
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 单一来源、交互一致性、可访问性、响应式和质量证据,而不要求所有项目都采用同一套框架。