nex_design_system/docs/09-agent-execution-rules.md

108 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 09. Agent Execution Rules
## 0. 默认技术栈与自动发现(NEX 0.1.6,沿用 0.1.5 默认栈)
NEX 配置包含明确的新项目默认技术栈。减少配置填写项,不代表移除技术选型。
- 新项目(`project.lifecycle: new`,或 `auto` 且仓库为空/没有实际应用代码):将 `nex.config.yaml` 的 `stack` 作为明确的初始化目标。不要再次要求用户提供技术栈清单,也不要擅自替换默认方案。
- 已有项目(`project.lifecycle: existing`,或 `auto` 且已经存在应用代码/锁文件/构建配置):以真实项目为准,自动发现并记录技术栈;不得将项目迁移到默认栈。
- `project.type` 默认 `fullstack`;纯前端/纯后端项目只需覆盖该字段。
- 用户只需修改不符合意图的 stack 字段;未修改的默认值仍然有效。
组件目录、Token 权威来源、主题链路、页面模式、断点、质量命令和辅助技术现状仍由 Agent 从项目中发现。无法确认的已有项目事实记录为 `UNKNOWN`。只有当未知信息会改变产品决策或高风险实施时,才提出必要澄清。
## 1. Agent 的角色
Agent 不应在每次任务中重新发明项目设计。它应先理解项目已有规范和资产,再在明确范围内完成实现,并提供可验证的结果。
## 2. Preflight:实施前检查
任何涉及 UI/UX 的任务开始前:
1. 读取 NEX Core 与项目根 Agent 指令。
2. 读取 `nex.config.yaml` 和项目级 UI 规范。
3. 从真实依赖/锁文件/构建配置确认技术栈,不根据过期 README 猜测。
4. 找到 Token 权威来源和派生链路。
5. 盘点现有组件和同类页面。
6. 确认主题、断点、布局尺寸和交互基线。
7. 找到项目现有质量门禁、视觉截图和回归流程。
8. 产出差异映射,使用 `COMPLIANT`、`ADOPTED`、`ADAPTED`、`DEFERRED`、`NOT_APPLICABLE`。
若用户要求只审计,本阶段之后停止,不得修改代码。
## 3. Plan:实施计划
跨组件、跨页面、主题、布局或设计 Token 的改动,先列出:
- 目标与非目标;
- 修改文件/组件/页面范围;
- 复用资产与需要新增的内容;
- 对业务交互和布局的影响;
- 风险和回滚方式;
- 质量检查和视觉验收方法。
用户已明确授权的阶段可在授权范围内执行;不得将授权自动扩展到后续阶段。
## 4. Implement:实现规则
- 先复用项目资产,后新增;先修正权威 Token/主题或共享组件,再改页面。
- 不机械套用参考项目的技术栈、尺寸、断点、品牌色或组件 API。
- 不强制增加第二套 Token、主题或组件系统。
- 不擅自修改业务交互、默认值、数据语义和用户操作路径。
- 对真实缺陷采用最小修复;保留原有交互意图,并补充必要的可访问性行为。
- 将项目不存在的页面/工作区标记为 `NOT_APPLICABLE`,不引入无关功能。
- 不对页面进行无差别批量替换;先确认设计值语义和实际消费位置。
## 5. Verify:验证规则
- 只运行仓库中真实存在的脚本和工具。
- 不把启动成功当作完整 UI 验收。
- 视觉检查范围由实际受影响路由、主题、视口和组件决定;复用项目现有回归矩阵。
- 对无自动化覆盖的项目,明确人工检查范围和无法验证事项。
- 比较基线时区分既有问题、此次引入问题和环境差异。
- 对主题、键盘、拖拽替代路径、状态文本、滚动和溢出进行适用性检查。
## 6. 证据等级与不可夸大原则
按实际执行情况分别记录以下证据,不得跨级推断:
| 等级 | 证据类型 | 可以证明 | 不能单独证明 |
|---|---|---|---|
| E0 | 源码/配置审阅 | 代码中存在预期结构或属性 | 浏览器实际行为、读屏播报 |
| E1 | 静态/自动化闸 | 已覆盖规则的自动化条件通过 | 未覆盖的语义、键盘和真实 AT 表现 |
| E2 | 浏览器人工键盘/指针验证 | 目标浏览器中的操作路径和焦点行为 | 屏幕阅读器实际播报 |
| E3 | 真实辅助技术验证 | 指定 OS、浏览器、屏幕阅读器组合中的实际结果 | 未测试的其他环境组合 |
日常开发默认执行 E0–E2。E3 真实屏幕阅读器验证按风险和产品支持平台选择,不是每次修改的必做步骤。对自定义拖拽/排序、复杂复合控件、复合导航、关键数据表格、重要 Live Region 或明确的合同/用户支持要求,应评估是否触发 E3。经评估无需 E3 时记录 `E3_NOT_REQUIRED`;已判定必要但环境不可用时标记 `MANUAL_QA_REQUIRED`。不能因存在 `aria-label`、`aria-keyshortcuts` 或自动化通过而报告真实读屏已通过。
E3 屏幕阅读器按目标操作系统选择:macOS 使用 VoiceOver;Windows 使用 NVDA(必要时按用户群增加 JAWS 或 Narrator);Linux 使用 Orca。具体浏览器组合见 `docs/14-accessibility-platform-matrix.md`。不得要求所有项目覆盖全部 OS,也不得把一个 OS 的测试结果外推到其他平台。
日常开发、Playwright 自动化和 Computer Use 视觉检查不得自动启动屏幕阅读器。启动/关闭/切换任何系统 AT 前必须获得用户对本次 E3 测试的明确授权;记录测试前状态,不得关闭用户原本已启用的 AT,不得修改系统级偏好。
语义质量闸应尽可能检查角色、可访问名称、状态、键盘行为和实际反馈,而不仅是 DOM 标签或属性字符串。自动化无法可靠判断的部分应转人工验收。
## 7. Report:交付报告
至少汇报:
1. 修改摘要和文件清单;
2. 规范映射状态及偏离理由;
3. 复用/新增/调整的组件;
4. 交互和视觉变化;
5. 实际运行的命令及结果;
6. 受影响的路由、主题、视口和截图;
7. 未解决问题、风险和下一阶段建议;
8. 自动化、键盘和真实 AT 证据等级及未执行项目。
## 8. 分阶段控制
建议按以下阶段推进,但项目可根据实际问题裁剪:
- 阶段 0:规范与基线对齐(原则上只读/只改文档)。
- 阶段 1:高优先级、可复现的视觉/状态缺陷。
- 阶段 2:键盘和可访问性问题。
- 阶段 3:层级、Token、主题等基础治理。
- 阶段 4:共享组件和页面模式改进。
- 阶段 5:分模块页面迁移。
- 阶段 6:视觉回归和质量门禁完善。
阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。