OneOS-V2/AGENTS.template.md

{{PROJECT_INFO_SECTION}}

Agents 工作流程说明

🧭 工作流程

步骤	说明	参考文档
① 读取上下文	系统规则、用户资料、相关规范、已有原型与资源目录	—
② 产品需求对齐	新建原型、明显重构或需求模糊时，先收敛目标用户、核心任务、范围、功能清单、内容来源和验收重点	rules/requirements-alignment-guide.md
③ 设计方案对齐	产品需求确认后，先让用户从 3-4 个匹配的 DESIGN.md 候选中确认设计基底，再把布局、交互、视觉和内容呈现收敛为设计决策	rules/requirements-alignment-guide.md
④ 原型开发与验收	根据已确认方案实现原型；遇到问题按错误信息定位修复，并完成预览验收	rules/prototype-development-guide.md

额外产物

产物/场景	位置	参考文档
主题	src/themes/<theme-key>/	rules/theme-guide.md
项目资料和文档	src/resources/	rules/resource-management-guide.md
UI Review 结论	src/prototypes/<prototype-name>/.spec/ui-review.md	rules/ui-review-guide.md
原型 Review 结论	src/prototypes/<prototype-name>/.spec/prototype-review.md	rules/prototype-review-guide.md
ACP 对话缓存	src/prototypes/<prototype-name>/.spec/acp/	本地私有运行数据，不提交、不导出、不发布

⚠️ 重要原则

1. 产品需求和设计方案分阶段对齐

   • 先确认做什么，再确认怎么表达；读取资料、规格/计划确认和开发验收过程中，发现影响方向的问题都要回到相应阶段继续对齐

   阶段	需要对齐的情况
   读取资料	目标、边界、素材、参考或约束不清
   产品需求	出现不同目标用户、功能范围、内容来源或验收标准
   设计方案	出现不同信息架构、交互路径、视觉方向或设计基底
   开发验收	实现结果、体验取舍或验收标准发生变化

2. 优先创建和维护 task/todo

   • 多步骤、高风险、需求对齐、方案确认或跨文件任务，优先用 task/todo 记录当前步骤、状态和下一步
   • 简单局部修改可以保持轻量，但要清楚说明当前正在处理什么、完成后如何验收

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

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

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

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

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

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

6. 早展示，早反馈

   • 产品需求、设计方案或原型应尽早交给用户确认，不要等到全部完成后才暴露方向问题

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

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

项目结构

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