cfdaily
120 lines
4.8 KiB
Markdown
120 lines
4.8 KiB
Markdown
# 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 其他选项卡（产出/审查/经验/子任务不变）
|