sanguo_moziplus_v2/docs/design/10-t3-requirement-exploration-and-blackboard-display.md

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

版本: v1.1 日期: 2026-06-03 作者: 庞统（副军师） 状态: ✅ 已完成（SSE + TaskModal 自动刷新已实现） 前置: #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 事件。需要加：

# 在 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 新增"需求探索"部分：

## 需求探索
- 收到模糊需求时，通过 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 → 重新加载详情。

// 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）
• 不做需求模糊度自动评分（庞统自主判断即可）