nex_animation/AGENTS.md

7.8 KiB
Raw Blame History

Nex Animation Studio — Agent 工作手册(项目级入口)

本项目引入 NEX Design System 0.1.1 作为跨项目设计标准。NEX 给的是原则, 不是本项目的固定布局模板、技术栈或尺寸表。本项目已经过 20 余轮真实设计与交互 修正,已验证成熟的设计、组件和交互优先保留;不得为了让数字与 NEX 一致而 反向修改本项目。

1. 规范优先级(冲突时从上往下)

层 文件 负责什么
1 docs/UI规范.md 项目级 UI/UX 权威:20 条硬规则 R1–R20、§1–§16 全部尺子与口径、13 道常驻探针、十二步改动流程
2 docs/工程规范.md 目录职责、脚本准入、代码风格、部署、删除策略、最低验收
3 docs/NEX-对照与例外.md NEX 逐条判定(COMPLIANT / ADOPTED / ADAPTED / DEFERRED / NOT APPLICABLE)与项目级例外登记;NEX 与本项目冲突时按此文件执行
4 nex.config.yaml 项目现状声明(真实尺寸、真实技术栈、真实检查命令)。改了布局尺寸必须同步它
5 frontend/src/theme/antd.ts → styles/index.css 数值的唯一实现;文档与它冲突时以实现为准并回头修文档
6 nex_design_system/docs/02–08 跨项目原则层(设计原则 / token 治理 / 布局体系 / 组件系统 / 交互系统 / 页面模式 / 可访问性与响应式)

开始任何前端页面、组件或样式工作前,至少读取:本文件、nex.config.yaml、 docs/NEX-对照与例外.md,以及任务涉及的 docs/UI规范.md 章节。 涉及既有页面时,必须先读该页现有 JSX、CSS 与所依赖的共享组件, 禁止只根据需求描述另造一套样式。

nex.config.yaml 的 requirements 与 rules 都是实施约束:前者是必须达到的 结果,后者是具体实现限制。特别是 maintain_existing_interactions: true —— 视觉改造不得改变既有业务操作路径;确需调整时先说明影响并纳入验收。

⚠️ 历史坑:NEX 0.1.1 的 docs/01-project-audit.md 与 nex.config.yaml 样例描述的是 另一个产品 NexDocus。它的 Header 64 / Sider 260·80 / Content 16·1280 / 控件 34·40 / 无 Tailwind / 204 处硬编码色 均不是本项目现状。 逐条对照见 docs/NEX-对照与例外.md。 同理:.trash/ 与 .local/ 已被 gitignore,是本地杂物,不作为现状依据。

2. 必须保留的资产(改动前先自查)

  • 技术栈:React 18 + TypeScript + Vite + antd 5 + Tailwind CSS v4(只做布局)+ zustand。不升级、不换库、不引入第二套 UI 组件包。
  • 单向 Token 流程:theme/antd.ts → applyRootVars() → :root{--ant-*} → styles/index.css @theme → Tailwind 语义类。禁止反向造第二把尺子,禁止新增 --nex-* 全局变量命名空间(该前缀已被 9 个组件局部变量占用,见对照文档 §4)。
  • 已验证尺寸:Header 56 / Sider 224·折叠 64 / Content 24(窄屏 16·12)/ 最大宽 1680 / 控件 32·24·40 / 圆角 6·8·4 / 断点 576·768·992·1200·1600 / 主色为 antd 出厂蓝(不覆盖 colorPrimary)。
  • 主题机制:跟随系统 + 手动 + localStorage + <html data-theme> + color-scheme + meta theme-color + ⌘⇧L。
  • 共享组件 kit:frontend/src/components/{ui,forms}(25 文件 / 163 导出)。NEX 05 §3 要求的第一批标准组件已全部存在,用它们,不要新造。
  • Empty 三分类:没数据 / 没匹配 / 引导下一步,文案分开,且能清除筛选恢复默认。
  • 反馈四级表面(R19):ErrorText/LineHint → Notice → notify* 吐司 → confirmAction。长任务唯一进度源是顶栏「平台动态」(§13.7),页面内不得再放第二个进度条。
  • 专业工作区交互:分镜卡拖拽、时间线、录音、素材灯箱、版本面板的既有操作路径。
  • 质量闸门:13 道常驻探针 + §16 十二步流程。这是 NEX 10「阶段 5 质量门禁」的现成实现,复用而非重造。
  • 本项目没有文档阅读 / PDF 预览 / AI Chat 工作区,不要为对齐 NEX 引入相应模板、布局或图表依赖。

3. 强制规则

docs/UI规范.md §0 的 R1–R20 是硬规则,违反任意一条 = 返工(先读那 20 行)。在其之上再加:

  1. 先复用,后新增。 先在 kit 里找;找不到才新增,且不得与已有件功能或视觉重复。
  2. 不擅自改技术栈。 不得借 UI 任务升级 React / antd / Tailwind,或引入新组件库、图表库。
  3. 禁止硬编码设计值。 颜色、字体、间距、圆角、阴影、层级、布局尺寸一律走 token / 语义类(R9)。
  4. 禁止私自建立视觉变体。 新颜色 / 新按钮尺寸 / 新卡片或页头样式 / 新断点前,先确认能否映射到既有 token;不能映射时先登记例外。
  5. 交互状态完整。 loading / success / empty / error / disabled / 权限不足都要考虑;破坏性操作二次确认;可点击元素键盘可达(用正确的语义元素,不自造 div + onClick)。
  6. 不破坏工作区滚动结构。 嵌套 Flex/Grid 必须明确滚动容器,必要时 min-width:0 / min-height:0。
  7. 主题成对实现。 任何表面 / 文字 / 边框 / 选中 / 悬停 / 状态色变更都要检查 Light 与 Dark。
  8. 不滥用局部覆盖。 业务页禁止高优先级选择器、!important、深层 antd DOM 覆盖;styles/app.css 是全站唯一 .ant-* 出口。
  9. 浮层层级不写魔法数。 z-index 走 frontend/src/lib/layers.ts 的层级表与 docs/UI规范.md §10;浮层叠浮层时页面级快捷键先问 floatingLayerOpen()。
  10. 先提交计划再改动。 超过单一组件的任务,先列将复用/新增的组件、涉及页面、状态与验收点。

4. 标准工作流

  1. 查现有页面、共享组件、token(components/{ui,forms}、theme/antd.ts、styles/)。

  2. 明确页面类型、用户任务、关键状态、响应式行为;必要时写 nex_design_system/templates/page-spec.md 规格的页面版。

  3. 先改共享组件 / 主题,再改业务页面。

  4. 跑项目真实存在的检查(本仓库没有 lint 与 test,不得虚构):

    cd frontend && npm run typecheck && npm run build
    node scripts/ui/classaudit.mjs
    NEX_BASE=http://127.0.0.1:5199 .venv/bin/python scripts/ui/<按 §15 改动范围选探针>.py
    
  5. 按 docs/UI规范.md §16 走完十二步;改过尺子(theme/antd.ts、styles/index.css、styles/app.css)必须全量回归,含 430 / 576 窄屏(R12)。

  6. 做 Light/Dark、窄屏(1440 / 768 / 430)、键盘与状态检查。基线是 14 路由 × 3 视口 × 2 主题 = 84 个状态,新截图必须与之可比。

  7. 汇报:改动文件、复用组件、规范偏离、检查命令与实际结果、未完成事项。

5. 完成定义

  • 视觉层级与布局符合 docs/UI规范.md 对应页面模式;
  • 用 token 而非散落硬编码;
  • 交互状态完整且跨页一致;
  • 不引入重复组件或不必要依赖;
  • Light / Dark / 窄屏 / 键盘均已检查并有截图证据;
  • 可运行的质量检查已执行且退出码为 0;跑不了的必须说明原因;
  • 文档(含 nex.config.yaml 与本文件)与实际行为不冲突;偏离 NEX 的已登记在 docs/NEX-对照与例外.md。

6. 例外处理

偏离 NEX 或偏离 docs/UI规范.md 时,在 docs/NEX-对照与例外.md §3 登记: 偏离项 / NEX 条款 / 本项目值 / 证据位置 / 原因 / 影响范围 / 是否可复用 / 状态。 不得把单个业务例外自动推广为全局规范,也不得复制一份与 docs/UI规范.md 大量重复的规范文档。需要修订 NEX 本身的,登记在对照文档 §5 反向清单里。