diff --git a/docs/research/distill-skills-draft/frontend-design-ai-native.md b/docs/research/distill-skills-draft/frontend-design-ai-native.md new file mode 100644 index 0000000..bfd4052 --- /dev/null +++ b/docs/research/distill-skills-draft/frontend-design-ai-native.md @@ -0,0 +1,76 @@ +--- +name: frontend-design-ai-native +description: >- + AI Native 前端设计原则:按钮矩阵与 AI 自动流转对齐、状态机驱动的 + 动态 UI。涉及前端界面设计、按钮/操作设计、状态流转 UI 时触发。 +--- + +# AI Native 前端设计 + +> 来源:从三国团队(庞统/司马懿/诸葛亮)~2GB 对话历史中蒸馏 +> 卡片数:2(批次1卡片9 + 前端设计相关经验) + +## 适用场景 + +- 设计任务状态流转的前端操作按钮时 +- 设计 Agent 操作界面时 +- 区分"用户操作"和"AI 自动操作"的 UI 边界时 + +## 经验清单 + +### 1. 按钮矩阵需与 AI Native 自动流转对齐(severity: medium) + +**场景**:设计前端按钮时,Agent 倾向于保留传统 CRUD 风格的所有按钮,忽略了 AI 自动流转的核心理念。 + +**正确做法**: +1. **AI 自动流转的操作不需要按钮**:认领、开始、提审——这些由 AI 自动完成 +2. **用户的通用权利需要按钮**:暂停、取消——所有非终态都有 +3. **动态决策项**:特定状态下弹出的选项(如"升级"),不是常驻按钮 +4. 按钮设计从"AI 做什么、人做什么"出发,而非从 CRUD 出发 + +**⚠️ 常见错误**: +- 为每个状态都设计完整操作按钮(认领、开始、提审、通过、打回),忽略 AI 自动认领和流转 +- 把"升级"做成常驻按钮而非动态选项 +- 没有区分"所有人都能做"和"特定角色才能做" + +**关键细节**: +- [frag_0471] 用户说:"认领不用,因为都是 AI 自动认领了...提审不要有,要么是 AI 审核...升级不是按钮吧,是动态出来的选项...其实就是暂停和取消" +- [frag_0472] "随时都可以暂停吧?和取消吧?" +- **AI Native = AI 做绝大部分操作,人类只做决策和干预** +- 暂停和取消是用户的通用权利,不限于特定状态 +- 实际操作结果 = 暂停 + 取消 两个常驻按钮 + 动态决策项 + +> 来源:批次1卡片9(按钮设计,freq=2) + +--- + +### 2. 状态机驱动的动态 UI 设计(severity: medium) + +**场景**:前端操作按钮应根据当前任务状态动态显示/隐藏,而非静态写死所有按钮。 + +**正确做法**: +1. 前端维护本地 ACTION_GUARDS 映射表 + `isAllowed()` 函数 +2. 按钮显示/隐藏由状态机驱动,不是硬编码 +3. 前后端状态枚举必须一致(参见 code-review-quality 中的枚举一致性经验) + +**⚠️ 常见错误**: +- 前端按钮条件和后端状态机不同步 +- 新增状态后前端忘记更新按钮显示逻辑 + +**关键细节**: +- v2.7 状态机守卫设计:TASK_TRANSITIONS(自动流转)和 ACTION_GUARDS(用户动作)独立 +- 前端 EdictBoard/TaskModal 使用本地 ACTION_GUARDS 映射 +- 涉及 UI/API 对接的改动不管多小都走流程——"一个按钮"涉及前端→API→后端三层 [MEMORY.md L5] + +> 来源:批次1卡片9 + MEMORY.md L5 + v2.7 状态机设计经验 + +--- + +## 检查清单(快速参考) + +- [ ] 按钮:AI 自动做的操作(认领/开始/提审)→ 不需要按钮 +- [ ] 按钮:用户的通用权利(暂停/取消)→ 所有非终态都显示 +- [ ] 动态决策项 → 不是常驻按钮,是特定状态下弹出 +- [ ] 前端 ACTION_GUARDS 和后端状态机是否一致? +- [ ] AI Native 原则:AI 做大部分操作,人只做决策和干预 +- [ ] UI 改动不管多小都走三层层流程(前端→API→后端)