From 42268a1e9635848ceb6f0d292ad06601b416bf92 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Thu, 21 May 2026 09:03:56 +0800 Subject: [PATCH] auto-sync: 2026-05-21 09:03:56 --- docs/design/v3.0-ux-simplification.md | 119 ++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/design/v3.0-ux-simplification.md diff --git a/docs/design/v3.0-ux-simplification.md b/docs/design/v3.0-ux-simplification.md new file mode 100644 index 0000000..668fd67 --- /dev/null +++ b/docs/design/v3.0-ux-simplification.md @@ -0,0 +1,119 @@ +# v3.0 UX 精简 — AI Native 交互原则 + +> 日期：2026-05-21 +> 作者：庞统 +> 状态：待评审 + +## 1. 核心原则 + +**AI Native 的交互：Agent 能解决的 Agent 解决，需要人类干预才人类干预。** + +| 原则 | 说明 | +|------|------| +| 看板只看不做 | 卡片 = 状态标签 + 信息，不是操作面板 | +| 操作台按需呈现 | TaskModal 只显示**当前状态人需要做的那个动作** | +| 意图必须明确 | 按钮文字必须是"你要我做什么"，不是"系统状态转换" | +| 非必要不出现 | Agent 自动流转的状态不显示操作按钮 | + +## 2. 状态与人机交互矩阵 + +| 状态 | 含义 | Agent 自行解决？ | 需要人干预？ | 给人的按钮 | 卡片显示 | +|------|------|:---:|:---:|------|------| +| pending | 等待调度 | ✅ 自动认领 | — | 无 | 🟡 待调度 | +| claimed | 已分配 | ✅ 自动开始 | — | 无 | 🟡 已分配 | +| working | 执行中 | ✅ Agent 执行 | — | 无 | 🟢 执行中 | +| review | 审查中 | ✅ Agent 审查 | — | 无 | 🔵 审查中 | +| **waiting_human** | 等人工确认 | — | ✅ Agent 明确请求 | **确认完成 / 拒绝** | 🟠 待确认 | +| **escalated** | 升级求助 | — | ✅ Agent 处理不了 | **继续 / 重新分配** | 🔴 需介入 | +| **failed** | 失败 | ✅ 自动重试 | 超重试上限 | **重试 / 取消** | 🔴 失败 | +| **blocked** | 阻塞 | — | ✅ 需外部帮助 | **解除阻塞** | 🔴 阻塞 | +| paused | 用户暂停 | — | 用户主动 | **继续 / 取消** | ⚪ 已暂停 | +| done | 完成 | ✅ 终态 | 可选归档 | **归档**（可选） | ⚪ 已完成 | +| cancelled | 取消 | — | 终态 | **归档**（可选） | ⚪ 已取消 | + +## 3. 卡片设计变更 + +### 3.1 卡片 = 状态标签 + 信息 + +**移除**：卡片上所有操作按钮（working 的"人工审核"、pending 的"认领"等） + +**保留**： +- 标题、描述摘要 +- 状态指示圆点（替代原来的 risk_level 标签） +- 指派人、时间 +- 点击打开 TaskModal + +### 3.2 状态指示圆点 + +替代卡片左下角的 `risk_level: standard` 标签： + +| 圆点 | 颜色 | 对应状态 | +|------|------|---------| +| 🟢 | `#2ecc8a` 绿色 | working, claimed | +| 🟡 | `#f5c842` 黄色 | pending, review | +| 🟠 | `#f59e0b` 橙色 | waiting_human | +| 🔴 | `#ff5270` 红色 | failed, blocked, escalated | +| ⚪ | `#6b7280` 灰色 | done, cancelled, paused | + +**非标准风险**（high/critical）时，圆点旁额外显示风险标签（如"⚠️ 高风险"）。 + +## 4. TaskModal 状态操作变更 + +### 4.1 移除冗余的"状态操作"区域 + +当前 TaskModal 总览里有一个"🔄 状态操作"区域，列出所有合法状态转换按钮（working 有 7 个）。 + +**改为**：只显示**当前状态需要人做的那个动作**，用意图明确的按钮。 + +### 4.2 各状态的按钮方案 + +| 状态 | 显示的按钮 | 按钮含义 | +|------|----------|---------| +| pending | 无 | 等待调度引擎自动分配 | +| claimed | 无 | 等待 Agent 自动开始 | +| working | **暂停** | 主动暂停任务 | +| review | 无 | 等待审查 Agent 完成 | +| waiting_human | **✅ 确认完成** / **🔄 拒绝，继续做** | 对 Agent 的 Checkpoint 做出决策 | +| escalated | **▶ 继续执行** / **🔄 重新分配** | 对升级任务给出指导 | +| failed | **🔄 重试** | 手动重试 | +| blocked | **🔓 解除阻塞** | 帮助 Agent 继续前进 | +| paused | **▶ 继续** / **🚫 取消** | 用户主动恢复或取消 | +| done | **📦 归档** | 可选归档 | +| cancelled | **📦 归档** | 可选归档 | + +### 4.3 高级操作（收起） + +对于需要手动干预的高级场景（如手动提交审查、强制标记失败），提供"高级操作"收起区域，不默认展示。 + +## 5. Ticker 扫描 _general 修复 + +### 问题 +`_general` 不在 `registry.db` → ticker 不扫描 → 任务创建后不被调度。 + +### 方案 +在 `Ticker._tick_all()` 中，遍历 registry 项目后，额外检查 `_general/blackboard.db` 是否存在。存在则作为虚拟项目扫描一次。 + +```python +# ticker.py _tick_all 方法末尾 +general_db = Path(self.registry.root) / "_general" / "blackboard.db" +if general_db.exists(): + pr = await self._tick_project("_general", {"status": "active", "source": "virtual"}) + results["projects"]["_general"] = pr +``` + +## 6. 变更范围 + +### 前端 +- `EdictBoard.tsx`：移除 CARD_ACTIONS，卡片不再显示操作按钮；risk_level 改为状态圆点 +- `TaskModal.tsx`：精简 StatusButtons，每个状态只显示必要的按钮 + +### 后端 +- `ticker.py`：_tick_all 额外扫描 _general + +### 设计文档 +- 本文档为 v3.0 UX 精简设计，评审通过后归档 + +## 7. 不改的 +- 状态机本身（11 个状态、转换矩阵不变） +- 后端 API（PATCH/POST 端点保留，前端不再调用不代表后端删掉） +- TaskModal 其他选项卡（产出/审查/经验/子任务不变）