# 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`