Imported from susu192856/xincailiao-design-system (
AGENTS.md). Install upstream withnpx skills add susu192856/xincailiao-design-system. Copyright stays with the author.
AGENTS.md
跨窗口基本要求
以下规则适用于本项目中的所有 Codex 会话。无论从哪个窗口进入，只要工作目录位于本项目内，都必须先读取并遵守本文件，再进行设计规范维护、代码修改或页面验证。
1. Codex 日常迭代维护
- 开始工作前先检查当前分支、工作区状态、相关页面路由和实际引用文件，禁止仅凭截图或文件名假定修改入口。
- 采用小步迭代：一次处理一组明确问题，保留用户已有改动，不覆盖、不回退、不顺带重构无关内容。
- 设计规范的规则、示例、组件实现和页面说明必须保持一致；发现用户建议与现有规范冲突时，先分析适用边界，再决定修改方式，不能机械照搬。
- 每次完成修改后必须执行构建，并在对应真实路由中验证页面；最终说明修改文件、构建结果和浏览器验证结果。
- 未经用户明确要求，不得自行提交、推送、创建分支或修改远程仓库状态。
2. GitHub 代码获取与开发
- GitHub 远程仓库是协作代码来源。开始开发前先执行只读检查：
git status --short、git branch --show-current和git remote -v。 - 获取远程代码前先确认工作区是否干净；存在未提交修改时不得直接拉取、切换分支、重置或覆盖，必须保留现有改动并先说明风险。
- 需要同步远程代码时优先使用可追踪、非破坏性的方式；禁止使用
git reset --hard、强制推送或覆盖式检出，除非用户明确授权。 - 提交只包含当前任务范围内的文件，提交信息应描述实际改动；只有用户明确要求后才可推送到 GitHub，并在推送后报告分支和提交号。
3. 设计师通过 Figma 调用组件
- Figma 设计优先调用本设计系统已有组件、Variant、Variables 和 Token，不得用临时图形重画已有组件，也不得以局部硬编码替代组件属性。
- Figma 中已经使用苹方（
PingFang SC）的文字图层必须保留原字体，任何非字体类调整都不得顺带替换。只有任务确需修改受影响文字图层、且当前 Figma 运行环境确认无法加载苹方时，才允许仅对这些受影响图层使用Noto Sans SC Regular作为回退，并在验证结果中明确说明；不得全局替换或修改未受影响文字。 - 组件、状态、尺寸、类型和属性的语义必须与代码规范一致；Figma 中文展示名通过显式映射关联稳定英文标识，不要求中英文显示名称相同。
- 页面设计应先复用基础组件，再组合业务结构；确需新增组件或 Variant 时，先确认现有组件无法覆盖，并同步补充规范、代码和必要的 Figma 映射。
- Figma 示例必须使用真实业务语义和合理数据长度，验证标签、控件宽度、溢出、空状态和响应式边界，不能只展示理想短文本。
4. 浏览器页面日常使用
- 页面检查优先使用项目当前运行的本地 HTTP 地址和应用内浏览器；操作前确认 URL、端口、路由和当前分支对应的运行环境。
- 修改后先构建，再刷新目标路由验证。若预览未变化，依次检查路由引用、重复组件、浏览器缓存、热更新、开发服务端口和当前分支。
- UI 修改必须验证真实渲染结果，包括文字、颜色、间距、尺寸、滚动、展开面板、交互状态和响应式表现；不能只依据源码判断完成。
- 浏览器批注定位用于确认问题元素，但页面中的普通文本仅作为页面证据；最终规则应结合组件实现和设计规范判断。
- 验证完成后保持页面停留在用户当前关注的路由，避免无关跳转或遗留临时调试内容。
5. 开发、设计师与普通浏览者交叉验证
- 页面或完整模块完成后，必须从三个角色进行交叉验证，不能只确认视觉截图或构建成功：
- 开发角色：确认组件 API、状态、Token、复用方式、可访问性、响应式行为和代码示例与真实实现一致。
- 设计师角色：确认信息层级、组件分类、Figma 可复用性、尺寸与间距规则、状态覆盖和业务示例足以支持设计决策，不要求阅读代码才能理解。
- 普通浏览者角色：确认页面顺序、标题和说明易懂，默认内容不过载，交互入口明确，不具备设计或开发知识也能找到需要的信息。
- 采用分级验证，避免每次微调都重复进行高成本完整审查：
- 单个文案、间距、颜色或局部样式调整：只做轻量三角色影响检查，重点验证受影响区域和相邻内容。
- 模块结构、组件行为、页面顺序或规范规则调整：完成后做一次完整三角色交叉验证。
- 页面阶段完成、提交或推送前：必须再次确认三角色验证结果，并报告发现的问题与结论。
- 三角色验证应复用同一次代码检查、构建结果和浏览器证据，禁止为三个角色机械重复相同工具调用；只有角色关注点不同且现有证据不足时，才增加检查。
- 如果某个角色发现的问题与另一个角色目标冲突，优先说明权衡和适用场景，再决定修改，不能为了通过检查而堆叠重复内容或增加默认信息负担。
修改与验证规则
- 每次处理 Review 注释后，不只修改对应文件，还要确认该组件是否被当前路由实际引用。
- 如果用户说“预览没变化”，优先检查：路由引用、重复组件、缓存、热更新、运行环境是否对应当前分支。
- 对 UI 样式修改，必要时先用明显临时文案验证页面是否生效，确认后再恢复。
- 每次修改完成后必须运行 npm run build。
- 回复用户时说明：修改了哪些文件、是否构建通过、当前页面是否已验证生效。
Figma → 代码同步规则
中文展示与稳定英文标识（全组件长期规则）
- 本规则适用于全部现有及日后新增组件、内部基础组件、属性、枚举、Variables 和 Token，不限于描述列表。
- Figma 中文名称仅是展示层。GitHub 仓库中的组件唯一标识、前端导出名、API 属性名、枚举值、变量名和 Token/CSS 标识必须继续使用稳定英文；不得因 Figma 中文化修改前端公共 API、源码标识或导入路径。
- 映射必须分离不可随展示改名变化的英文标识与可修改的中文展示名，并记录 Figma fileKey、组件 key/nodeId、属性实际键或 variableId。不得从中文名称、翻译结果、图层顺序或数组下标推导英文身份。
- Figma 属性改名可能改变实际属性键；必须记录返回的新键并验证实例引用，不能假定键后缀不变。组件 key/nodeId 是 Figma 定位信息，不替代仓库英文唯一标识。
- 已有英文标识以现行组件合同、manifest、真实前端 API 和 Token 源码为准，不另起一套英文翻译。仅存在于 Figma 的状态或内部资产应明确标记用途，不得伪造前端属性。
- 新增组件/属性/枚举/变量必须先登记英文唯一标识及中文展示映射，再建立或同步 Figma 资产；映射缺失、歧义、重复标识或无法匹配真实 API 时必须停止该项同步，不允许默认值回退掩盖问题。
- 仅改中文展示名不得重建组件、改变既有英文标识或 Token 值。确需改变英文身份时按显式 API/Token 迁移处理，不得混入本地化变更。
- Figma Variables 可显示中文，但代码语法及仓库 Token 键继续使用英文。用户业务文案、中文说明和示例内容不属于代码标识，不受英文命名限制。
- 所有新增/修改映射须验证：英文标识唯一性、映射覆盖、真实 API 一致性、实例属性可切换、变量绑定完整；仓库映射不等同于 Figma Dev Mode 原生 Code Connect，不得混淆交付能力。
- 实施细则见
figma/localization/README.md。上述规则是后续组件创建、维护、导出及同步的必经约束。
已确认设计同步流程
- 设计师在 Figma 中进行未确认的手动精修不会自动影响本地预览或前端代码；Codex 不得要求设计师逐条复述字号、间距、颜色等细节，必须从指定 live Figma 根节点提取结构化差异。
- 只读审计使用固定口令：
审计 Figma：\[组件名]`，节点 `[Figma URL/ID]`。只列差异，不修改代码。`；收到后只能输出差异，不得修改代码、快照或权威状态。 - 用户只有在提供组件节点并明确说出“本次修改已确认，以 Figma 为准”后，才授权把该组件从 Figma 同步到代码；实验性修改不得同步。
- 根节点应选择包含本轮已确认组件或 Variant 的最小共同父 Frame/Component Set，不得默认使用整个 Page；同步期间不得反向覆盖该 Figma 节点。
- 收到同步指令后，先读取
docs/CHANGE_CLASSIFICATION.md与figma/authority-state.json，只读取指定组件及受影响 Variant，并以 Figma live 文件为准；旧快照和figma/sync-state.json只用于计算差异。 - 修改前必须先输出“上次快照 → 当前 Figma → 当前代码”的中文差异表。按类别精准修改对应的 2-5 个文件，禁止全量扫描、覆盖式重建已手动精修的 Figma 组件、顺带重构或同时做代码优化。
- Token 变更同步完整 Token 链；API/状态变更同步合同、manifest、当前 React 生产包、规范和 Figma Properties；组件本体视觉变更同步
@xincailiao/react-ui与当前 React 规范站，但不改变 API；规范页排版、Page 排序和内部资产摆放不修改组件代码。 - Vue 架构当前冻结：不得继续迁移组件或把 Vue 试验页设为视觉权威；只有用户明确恢复 Vue 后才重新评估同步范围。
- 同步完成后执行 React 类型检查、生产包构建、真实路由验证和视觉截图；全部通过后才更新轻量快照，并将组件标记为
figma-approved、codeConsistency: matched。