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