auto-sync: 2026-05-26 23:45:40

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→后端）