# #10 T3: 需求探索自动触发 + 黑板内容前端展示

> 版本: v1.1
> 日期: 2026-06-03
> 作者: 庞统（副军师）
> 状态: 待终审（v1.1）
> 前置: #04 黑板协作（@mention + comment）
> 关联: architecture-v3.0.md T3
> 变更: v1.1 纳入司马懿评审反馈 — checkpoint SSE 触发文件修正为 checkpoint_routes.py，SSE payload 统一含 project_id

## 讨论决策记录

### D1: 砍掉 AI 摘要，改为黑板直投前端
原设计：SSE 推原始事件 → AI 生成自然语言摘要 → 前端展示。
改为：黑板内容直接展示到前端。
理由：黑板 comment/output 本身是自然语言，零成本、零延迟、零幻觉。Single source of truth。

### D2: SSE 只做通知，不做数据通道
SSE 是 push notification，不是 data channel。前端收到通知 → 拉黑板 API → 展示。debounce 500ms 防密集通知打爆 API。

### D3: A3 复用 TaskModal 增强，不新建面板
当前 TaskModal 已有 comments/outputs 展示，增强实时性即可（SSE 触发自动刷新）。

### D4: comment author=user 已支持
`add_comment` API 的 author 字段无枚举约束，直接传 `"user"` 即可。前端已有 `author: 'user'` 的调用。

### D5: 三种前端交互方式覆盖当前场景
verify（确认型）、decision（选择型）、comment（自由输入型）。将来可加多选型。

---

## 一、设计总览

T3 分为 4 个子项：

| 子项 | 内容 | 性质 | 优先级 |
|------|------|------|--------|
| A1 | 前端需求探索交互 | 前端 | P1 |
| A2 | 需求探索过程写黑板 comments（Q&A） | 后端 API + prompt | P1 |
| A3 | TaskModal 实时刷新（SSE 触发自动拉取） | 前端 | P2 |
| A4 | 庞统 chat 路径需求探索触发 | prompt 改动 | P2 |

---

## 二、A1: 前端需求探索交互

### 2.1 场景

用户在 Dashboard 新建任务/项目时，填写一个模糊描述（如"我想做个回测系统"）。系统判断描述模糊度，如果需要澄清 → 启动需求探索流程。

### 2.2 交互流程

```
用户输入描述 → 创建任务（status=pending）
  → 庞统收到任务 → 判断需求是否清晰
    ├─ 清晰 → 正常拆解执行
    └─ 不清晰 → 创建 checkpoint(type=decision)
      → 前端展示 checkpoint 面板（复用 CheckpointPanel）
        → 用户选择/回答 → checkpoint resolved
          → 庞统继续追问或确认需求已清晰
            → 需求清晰 → 更新任务描述 + 开始拆解
```

### 2.3 实现方式

**完全复用现有 checkpoint 机制**，不需要新组件：

1. 庞统被 spawn 后，判断需求模糊 → 调用 `POST /api/projects/{pid}/tasks/{tid}/checkpoints` 创建 decision checkpoint
2. 前端 CheckpointPanel 自动展示未处理的 checkpoint
3. 用户选择/确认 → checkpoint resolved → 庞统继续

三种 checkpoint 类型覆盖三种交互：
- `verify`：确认型（"你说的回测是日频还是分钟频？"）
- `decision`：选择型（"数据源用 tushare 还是 akshare？"）
- `action`：行动确认型（"我先帮你拉一下数据样本，确认后继续"）

### 2.4 需求探索的 Q&A 写入黑板

每次 checkpoint 交互（用户回答 + 庞统追问），都作为 comment 写入黑板：

```
comment_type = "general"
author = "pangtong-fujunshi" / "user"
```

这样需求探索的完整过程在黑板上可追溯。

---

## 三、A2: 需求探索过程写黑板 comments

### 3.1 后端改动

**几乎不需要改**。当前 API 已完全支持：
- `POST /api/projects/{pid}/tasks/{tid}/comments` — author 可为 "user"
- `POST /api/projects/{pid}/tasks/{tid}/checkpoints` — 创建 checkpoint
- `POST /api/projects/{pid}/tasks/{tid}/checkpoints/{cp_id}/approve` — 用户确认

唯一需要的后端改动：**新增 SSE 事件 `comment_added`**。

当前 add_comment API（L298-326）写 comment 后没有推送 SSE 事件。需要加：

```python
# 在 add_comment API 返回前
try:
    from src.api.sse_routes import get_broker
    broker = get_broker()
    broker.publish_sync("comment_added", {
        "project_id": project_id,
        "task_id": task_id,
        "comment_id": cid,
        "author": body["author"],
    })
except Exception:
    pass
```

同理，checkpoint approve 时也需要推送 `checkpoint_resolved` 事件。

### 3.2 Prompt 改动（庞统）

**review_pangtong.md** 新增"需求探索"部分：

```markdown
## 需求探索
- 收到模糊需求时，通过 checkpoint(decision/verify) 向用户提问
- 每次只问一个核心问题，不要一次问多个
- 问题要具体到可选项，不要问开放式问题
- 用户回答后，把澄清后的需求写入黑板 comment
- 需求清晰后，更新任务描述（title/description），然后正常拆解执行
- 不要在需求不清晰时就开始拆解任务
```

---

## 四、A3: TaskModal 实时刷新

### 4.1 现状

- TaskModal 打开后只在 `modalTaskId` 变化时加载一次（`useEffect` L318）
- SSE `task_updated` 只更新列表中的 status，不刷新 TaskModal 详情
- 用户需要手动关闭再打开 TaskModal 才能看到新 comments

### 4.2 改动

在 `store.ts` 的 SSE 事件处理中，增加：当收到 `comment_added` / `checkpoint_resolved` / `output_written` 事件时，如果当前 TaskModal 正在显示该 task → 重新加载详情。

```typescript
// store.ts SSE 事件处理中新增
_es.addEventListener('comment_added', (e: MessageEvent) => {
  try {
    const data = JSON.parse(e.data);
    const s = useStore.getState();
    // 如果 TaskModal 正在显示该 task → 刷新
    // 双重检查：task_id + project_id 防跨项目误刷新
    if (s.modalTaskId === data.task_id && s.currentProjectId === data.project_id) {
      s.loadV2TaskDetail(data.task_id);
    }
  } catch { /* ignore */ }
});
```

同样处理 `checkpoint_resolved` 和已有的 `task_updated`（增加 TaskModal 刷新逻辑）。

debounce 500ms：如果短时间内多个事件，只刷新一次。

### 4.3 改动文件

| 文件 | 改动 | 行数 |
|------|------|------|
| `src/api/blackboard_routes.py` | add_comment 后推送 SSE comment_added | ~8 行 |
| `src/api/checkpoint_routes.py` | checkpoint approve/reject 后推送 SSE checkpoint_resolved | ~8 行 |
| `src/frontend/src/store.ts` | 新增 comment_added/checkpoint_resolved 事件监听 + TaskModal 自动刷新 | ~20 行 |
| `src/daemon/sse.py` | 无需改（SSEBroker 已支持任意 event_type） | 0 |

---

## 五、A4: 庞统 chat 路径需求探索触发

### 5.1 场景

用户在 Control UI / chat 中直接说了一个模糊需求（如"帮我看看最近的策略表现"）。庞统主 session 收到后，判断是否需要需求澄清。

### 5.2 改动

**SOUL.md 或 prompt 中增加判断指引**（不需要代码改动）：

庞统在收到模糊需求时，不走 moziplus 的任务流程，而是直接在 chat 中用苏格拉底式追问澄清。澄清完成后再创建黑板任务。

这个实际上庞统的 SOUL.md 已经有"方案先确认"的原则，只需要确保 prompt 中明确引用 requirement-clarification skill。

---

## 六、改动总览

| 文件 | 改动 | 行数 |
|------|------|------|
| `src/api/blackboard_routes.py` | add_comment 后推送 SSE comment_added | ~8 行 |
| `src/api/checkpoint_routes.py` | checkpoint approve/reject 后推送 SSE checkpoint_resolved | ~8 行 |
| `src/frontend/src/store.ts` | SSE 事件监听 + TaskModal 自动刷新 + debounce | ~25 行 |
| `prompt_templates/review_pangtong.md` | 需求探索指引 | ~8 行 |
| **净增** | | **~49 行** |

---

## 七、验收标准

1. add_comment API 调用后推送 SSE comment_added 事件
2. checkpoint approve/reject 后推送 SSE checkpoint_resolved 事件（在 checkpoint_routes.py）
3. TaskModal 打开时收到相关 SSE 事件自动刷新（debounce 500ms）
4. SSE payload 统一包含 project_id，前端检查 task_id + project_id 双重匹配
5. 庞统 prompt 包含需求探索指引

---

## 八、不做的事

- 不做 AI 自然语言摘要（D1）
- 不做 SSE 事件 payload 丰富化（D2）
- 不新建前端展示面板（D3）
- 不做专门的需求探索 API（复用 checkpoint + comment）
- 不做需求模糊度自动评分（庞统自主判断即可）
