OneOS1.2/AGENTS.md

项目信息

• 项目名称：OneOS1.2

🧭 核心顺序

产品需求确认 -> 设计方案确认 -> 原型实现

阶段	继续前必须确认	参考文档
产品需求	目标用户、核心任务、范围、功能清单、内容来源和验收重点	rules/requirements-alignment-guide.md
设计方案	DESIGN.md 设计基底、信息架构、交互路径、关键组件取舍和视觉方向	rules/requirements-alignment-guide.md
原型实现	根据已确认的需求和设计方案实现原型	rules/prototype-development-guide.md

额外产物

产物/场景	位置	参考文档
OneOS V2 全局定版设计规范	src/resources/design-system/DESIGN.md	rules/global-design-spec.md 与 .cursor/rules/oneos-v2-design-system.mdc；OneOS V2 下新建/修改页面强制前置读取
vm-page 列表分页	src/common/TablePagination.tsx + vm-pagination.css	src/prototypes/vm-shared/DESIGN.md
主题	src/themes/<theme-key>/	rules/theme-guide.md
项目资料和文档	src/resources/	rules/resource-management-guide.md
画布	src/prototypes/<prototype-name>/canvas.excalidraw、canvas-assets/	原型画布和画布素材
业务逻辑规格	src/prototypes/<prototype-name>/.spec/<topic>.md	rules/business-logic-documentation-guide.md
AutoPRD + 标注目录	.spec/requirements-prd.md + annotation-source.json；定稿写第 10 章与 prdVersion；云效组合唯一 YunxiaoPMapp	skill oneos-autoprd；清洗用 AutoRDO；规则 .cursor/rules/oneos-autoprd-sync.mdc
对象存储发布 URL	.axhub/make/axhub.config.json → cloudPublishing.s3	rules/cloud-publish-url-guide.md
原型标注布局	src/common/prototype-annotation-host.tsx	rules/prototype-annotation-layout-guide.md

⚠️ 重要原则

1. 需求与设计是继续工作的门禁

   • 产品需求未确认时，禁止继续找视觉参考、拆页面结构、整理 DESIGN.md 候选、写设计方案或开发实现；先用简短摘要让用户确认目标用户、核心任务、范围/功能清单、内容来源和验收重点
   • 设计方案未确认时，禁止继续写规格/计划或开发实现；先确认设计基底、信息架构、交互路径、关键组件取舍和视觉方向
   • 发现目标、范围、内容来源、验收重点、信息架构、交互路径、视觉方向或设计基底存在多种合理选择时，立即停在对应门禁补充对齐

2. 设计要判断何时收敛、何时发散

   • AI 应自行判断当前需要收拢需求还是探索解法：需求不清先收敛；需要改善体验或创新表达时再发散。发散是为了帮助用户选择最终方向

3. 原型按生产级界面处理

   • 本项目中的「原型」默认是可运行、接近正式产品的前端页面，不是黑白灰线框图或低保真草稿；只有用户明确要求时才使用低保真、wireframe、placeholder 等表达

4. 不要把截图当唯一真相

   • 截图用于视觉参考；有代码、组件、设计系统、业务资料或用户说明时，要结合上下文判断

5. 早展示，早反馈

   • 产品需求、设计方案或原型应尽早交给用户确认，不要等到全部完成后才暴露方向问题
   • 涉及页面意图、组件取舍或多方案比稿时，优先用低成本、快速的 Markdown ASCII Wireframe/Diagram 或 Mermaid 展示方案，先对齐需求

6. 讲人话，用户不懂技术

   • 用用户能理解的方式说明取舍、风险和结果；用户无法执行 CLI 命令，不得省略验收流程
   • 向用户请求反馈或验收时，提醒用户尽量提供截图、预览链接、页面路径或具体问题位置，便于准确定位和复现

7. 复杂业务逻辑必须文档化

   • 多步判定、跨模块校验、状态/公式推导、导入规则等，除代码外必须写入 .spec/*.md 与 requirements-prd.md，并同步标注目录（见 rules/business-logic-documentation-guide.md）
   • 不得默认「先实现、后补文档」；逻辑变更与 PRD/标注更新同一轮交付

8. 对象存储发布 URL 与 Make 工具一致

   • 发布或写链接时格式为 {baseUrl}/{prototype-id}/index.html；禁止加 prototypes/ 前缀或去掉 index.html（见 rules/cloud-publish-url-guide.md）

项目结构

├── src/
│   ├── common/      # 公共运行时、类型和工具
│   ├── prototypes/  # 原型页面目录
│   ├── resources/   # 项目资料、文档和素材
│   └── themes/      # 主题与设计规范
├── rules/           # Agent 工作规则
└── .axhub/make/     # 本地运行数据和项目 metadata