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

6.5 KiB
Raw Blame History

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:视觉回归和质量门禁完善。

阶段不是强制顺序模板;具体由审计证据和用户授权决定。每阶段结束应形成可验收交付,不默认自动进入下一阶段。