103 lines
5.6 KiB
Markdown
103 lines
5.6 KiB
Markdown
# 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`
|