102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# NEX 0.1.6 — 新项目快速开始(带默认技术栈)
|
||
|
||
## 1. 放置规范包
|
||
|
||
建议目录:
|
||
|
||
```text
|
||
project-root/
|
||
├── AGENTS.md
|
||
├── nex.config.yaml
|
||
├── standards/
|
||
│ └── nex-design-system/
|
||
├── docs/
|
||
└── frontend/ / backend/ # 由项目类型和默认技术栈初始化
|
||
```
|
||
|
||
将 ZIP 内 `NEX-Design-System-v0.1.6/` 的内容放入 `standards/nex-design-system/`。
|
||
|
||
## 2. 复制默认配置
|
||
|
||
将 `standards/nex-design-system/config/project-profile.example.yaml` 复制到项目根目录,命名为 `nex.config.yaml`。
|
||
|
||
**默认技术栈已经给定,不需要从零填写:**
|
||
|
||
- 前端:React + TypeScript + Vite + Ant Design + Tailwind CSS v4 + Zustand + React Router + Axios。
|
||
- 后端:Python + FastAPI + Pydantic + SQLAlchemy + Alembic。
|
||
- 数据库:开发 SQLite,生产 PostgreSQL。
|
||
- API:REST + OpenAPI。
|
||
- 本地资源:`./data`。
|
||
- 质量工具:ESLint、Prettier、Vitest、Playwright、Pytest。
|
||
|
||
这些是 NEX 新项目的默认起步方案。需要不同技术时,只修改 YAML 中对应字段,不必填写整份技术清单。
|
||
|
||
### 生命周期如何处理
|
||
|
||
`project.lifecycle` 默认为 `auto`:
|
||
|
||
- 空仓库/无应用代码:按新项目处理,使用上述默认技术栈。
|
||
- 已有代码、锁文件或构建配置:按已有项目处理,自动识别并保留当前技术栈,不会强行改成默认方案。
|
||
|
||
如果需要明确指定,可将其改为 `new` 或 `existing`。
|
||
|
||
### 项目类型
|
||
|
||
默认 `project.type: fullstack`。纯前端项目只需改为 `frontend-only`;纯后端项目改为 `backend-only`。Agent 不应初始化不适用的部分。
|
||
|
||
## 3. 合并根 AGENTS.md
|
||
|
||
不要覆盖项目已有的根 `AGENTS.md`。合并以下规则,并按实际安装路径调整:
|
||
|
||
```markdown
|
||
## NEX Design System
|
||
|
||
本项目采用 NEX Design System 0.1.6 作为跨项目设计治理标准。
|
||
规范位于 `standards/nex-design-system/`。
|
||
UI/UX 任务开始前,读取 NEX AGENTS.md、docs/00-governance-and-adaptation.md、
|
||
docs/09-agent-execution-rules.md、docs/12-responsive-accessibility-quality.md、
|
||
docs/13-project-stack-defaults.md、docs/14-accessibility-platform-matrix.md,以及项目根目录 nex.config.yaml。
|
||
|
||
新项目按 nex.config.yaml 中的 stack 默认值初始化,不得忽略或自行替换技术选型。
|
||
已有项目自动识别实际技术栈并保留,不得因默认值不同而迁移。
|
||
先审计、建立符合性矩阵、提交计划;未经授权不得全量重构或自动进入下一阶段。
|
||
```
|
||
|
||
## 4. 首次交给 Agent
|
||
|
||
将 `templates/new-project-audit-prompt.md` 交给 Agent。
|
||
|
||
- 新项目:先核对默认技术栈与项目类型,给出目录结构、依赖和初始化计划;本轮只审计,不实际创建业务代码,除非你另行授权。
|
||
- 已有项目:从锁文件、源码、构建配置和运行结果识别真实技术栈,形成与 NEX 的差异映射;不得把默认栈当作迁移目标。
|
||
|
||
## 5. 只修改真正需要覆盖的字段
|
||
|
||
例如,若希望数据库从“开发 SQLite、生产 PostgreSQL”改为两阶段均 PostgreSQL,只修改:
|
||
|
||
```yaml
|
||
stack:
|
||
database:
|
||
development: PostgreSQL
|
||
production: PostgreSQL
|
||
```
|
||
|
||
如希望纯前端项目,只修改:
|
||
|
||
```yaml
|
||
project:
|
||
type: frontend-only
|
||
```
|
||
|
||
其余默认项保持不动。审计报告不是代码修改授权;确认实施范围后再让 Agent 开始开发。
|
||
|
||
|
||
## 6. 无障碍测试怎么执行
|
||
|
||
- 默认工程目标为 WCAG 2.2 AA;日常验收使用源码审阅、Playwright/axe 等自动化和浏览器键盘交互(E0–E2)。
|
||
- 真实屏幕阅读器(E3)仅在复杂自定义交互、关键业务流程、Live Region、复合控件或客户/法规要求等风险条件下触发,不是每次提交的必做步骤。
|
||
- 按项目目标平台选择 AT:macOS VoiceOver、Windows NVDA(必要时 JAWS/Narrator)、Linux Orca。项目不承诺的平台不强制加入测试矩阵。
|
||
- Agent 不得自动启动或关闭系统屏幕阅读器;启动/关闭前必须取得本次 E3 测试的明确授权。
|
||
- 目标环境不可用时,若 E3 已判定必要,标记 `MANUAL_QA_REQUIRED`;若风险评估不需要 E3,记录 `E3_NOT_REQUIRED`。
|
||
|
||
详见 `docs/08-accessibility-responsive.md`、`docs/12-responsive-accessibility-quality.md` 和 `docs/14-accessibility-platform-matrix.md`。
|