OneOS-V2/AGENTS.md

Agent 工作流程

🧭 核心顺序

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

阶段	继续前必须确认	参考文档
产品需求	目标用户、核心任务、范围、功能清单、内容来源和验收重点	rules/requirements-alignment-guide.md
设计方案	设计基底已锁定为 OneOS V2（src/resources/design-system/DESIGN.md）；确认信息架构、交互路径、关键组件取舍和视图选型	rules/requirements-alignment-guide.md · .cursor/rules/oneos-v2-design-system.mdc
原型实现	根据已确认的需求和设计方案实现原型	rules/prototype-development-guide.md

额外产物

产物/场景	位置	参考文档
主题	src/themes/<theme-key>/	rules/theme-guide.md
项目资料和文档	src/resources/	rules/resource-management-guide.md
画布	src/prototypes/<prototype-name>/canvas.excalidraw、canvas-assets/	原型画布和画布素材

⚠️ 重要原则

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

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

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

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

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

• 本项目中的「原型」默认是可运行、接近正式产品的前端页面，不是黑白灰线框图或低保真草稿；只有用户明确要求时才使用低保真、wireframe、placeholder 等表达
• 一个原型 = 侧栏一项：默认同页内模拟列表/详情/视图切换；禁止默认用 useHashPage 拆成侧栏套娃下级页（见 .cursor/rules/one-prototype-one-sidebar.mdc）

4. 不要把截图当唯一真相
   • 截图用于视觉参考；有代码、组件、设计系统、业务资料或用户说明时，要结合上下文判断
5. 早展示，早反馈
   • 产品需求、设计方案或原型应尽早交给用户确认，不要等到全部完成后才暴露方向问题
   • 涉及页面意图、组件取舍或多方案比稿时，优先用低成本、快速的 Markdown ASCII Wireframe/Diagram 或 Mermaid 展示方案，先对齐需求
6. 讲人话，用户不懂技术
   • 用用户能理解的方式说明取舍、风险和结果；用户无法执行 CLI 命令，不得省略验收流程
   • 向用户请求反馈或验收时，提醒用户尽量提供截图、预览链接、页面路径或具体问题位置，便于准确定位和复现

项目结构

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