furniture-3d-system-Wu/AGENTS.md

AGENTS.md

适用范围：D:\AI Code\3danzhuang-wuyongjie-mainline 全仓库。 未单独说明时，先遵循全局规则：C:\Users\54972\.codex\AGENTS.md。
这份文件只补充本仓库特有规则，不重复全局通用要求。

重要边界：D:\AI Code\3danzhuang 是历史旧现场；当前正式工作目录以 D:\AI Code\3danzhuang-wuyongjie-mainline 为准，除非用户明确要求，不要混用旧目录。

1. 默认执行口径

• 用户未指定目录时，默认在 furniture-3d-system/ 执行。
• 当任务发生在 furniture-3d-system/ 时，默认按当前会话直接开发。
• 常规任务分支在完成必要验证、确认范围和目标后，可以按团队协作标准流程主动 commit / push。
• main、生产发布、破坏性操作、删除数据、改远端历史等高风险动作仍必须由用户明确授权。
• 禁止破坏性操作，除非用户明确授权。
• 没有“规范审查结论”，任务不算完成。

2. 三条硬规则

• 必须符合企业级架构标准。
• 必须符合统一视觉标准。
• 必须优先做根因修复，不能拿补丁冒充完成。

3. 固定协作入口

当任务发生在 furniture-3d-system/ 时，人和 AI 都必须先读取下面 3 份协作文档，再开始改代码：

• furniture-3d-system/docs/workflow/团队协作模式.md
• furniture-3d-system/docs/workflow/模块边界说明.md
• furniture-3d-system/docs/workflow/主线同步操作手册.md

如果任务和包装协作有关，再额外读取：

• furniture-3d-system/docs/workflow/同事交接模板.md
• furniture-3d-system/docs/workflow/同事本地AGENTS模板.md
• furniture-3d-system/docs/开发指南/包装方案增强/新平台包装底座-同事AI对接说明-20260331.md

4. 协作与分支口径

• main 是最终发布主线，不能随便直接推；生产发布必须另行确认。
• origin/codex/xuxiake-mainline 是当前共享开发主线和默认同步基线。
• 新功能、优化和修复默认从最新 origin/codex/xuxiake-mainline 开任务分支，再按协作流程回流。
• 新分支统一使用 codex/<负责人>-<工作域> 或 codex/<负责人>-<工作域>-<任务简称>。
• 不再使用 feature/packaging、packaging/...、codex/xuxiake-dev 这类泛分支名。
• 长期共享分支同步当前共享开发主线时固定使用 merge。
• 临时个人任务分支只有在确认无人共用时才使用 rebase。

5. 白曜石工坊视觉口径

• furniture-3d-system/docs/设计规范/白曜石工坊统一视觉标准.md 是当前新平台第一视觉标准。
• 新平台主链页面，以及 /admin、/users 等后台管理页面，默认都要向白曜石工坊口径统一。
• 白曜石工坊默认是浅色工作台；不再提供深浅色主题切换入口，也不要把后台页面继续做成默认黑底。
• 页面应保持工作台感、低噪音、克制、层级清楚，不能退回普通 SaaS 卡片墙或营销式大卡片布局。
• Inspector（检视器）、数据列表、表格、长文本和表单密集区必须优先保证可读性，不能用毛玻璃承载正文。
• 毛玻璃只允许用于顶栏、HUD、浮动工具条和轻量状态浮层。
• 板材、五金、组件、包装等资产应按 Meta Component（元组件） 表达，而不是普通图片卡片。
• 如果苹果风格视觉标准与白曜石工坊标准冲突，新平台主链和后台管理页面优先执行白曜石工坊标准；苹果风格标准只作为基础组件、交互细节和可访问性补充参考。

6. 前端责任口径

• 未明确指定其他协作者时，前端、视觉、交互、3D（立体） 表现层和系统联调默认由当前 Codex 全权负责。
• 前端实现必须遵守白曜石工坊视觉标准、模块边界和最小验证要求。
• 处理前端页面时，优先用当前代码、实际页面表现、截图结论和设计规范判断，不再套用旧模型时期的保守分工。
• 复杂任务可以主动拆计划、并行排查和验证，但不能因为模型更强就扩大改动范围或跳过规范审查。

7. 截图和上下文续接

• 工程对话可以正常使用截图，但截图只用于当前判断。
• 压缩上下文、写会话恢复摘要或给新对话续接时，只保留文字结论、关键决策、当前状态和下一步。
• 不继承、不复述 data:image base64（图片编码文本），也不要把图片原始内容写进摘要。
• 如果同一问题需要连续大量截图，优先开短图像对话处理，最后只把文字结论合回主工程对话。

8. 敏感信息和交接材料

• 账号、密码、服务器地址、访问密钥、数据库连接、S3/MinIO 密钥等敏感信息，只能放在本地续接材料里。
• 含敏感信息的摘要、日志或交接文件不能提交 Git，不能发给同事，不能写进共享文档。
• 仓库内协作文档只写非敏感入口、流程和职责；凭据类信息必须用 [REDACTED_SECRET] 或本地路径说明替代。
• 发现摘要文件里混有明文凭据时，默认先提示风险，再决定是否拆成本地敏感版和仓库协作版。

9. 规范审查

规范审查固定只查三件事：

• 架构有没有被破坏
• 视觉有没有跑偏
• 这次是不是根因修复

结论只能是：

• passed
• passed with warnings
• rejected

只要架构违规、视觉违规，或明显是补丁式修复，就必须 rejected。
如果这次不是独立复审，必须明确写出“这是自审，不是独立复审”。

统一清单：furniture-3d-system/docs/workflow/规范审查清单.md

10. 标准来源

• furniture-3d-system/docs/设计规范/白曜石工坊统一视觉标准.md
• furniture-3d-system/docs/workflow/规范审查清单.md

补充参考：

• furniture-3d-system/docs/设计规范/苹果风格视觉标准.md