auto-sync: 2026-06-03 18:20:38

2026-06-03 18:20:38 +08:00
parent 4eb1ff0a58
commit 0e28515e20
1 changed files with 220 additions and 0 deletions
@@ -0,0 +1,220 @@
+# #10 T3: 需求探索自动触发 + 黑板内容前端展示
+
+> 版本: v1.0
+> 日期: 2026-06-03
+> 作者: 庞统（副军师）
+> 状态: 待评审
+> 前置: #04 黑板协作（@mention + comment）
+> 关联: architecture-v3.0.md T3
+
+## 讨论决策记录
+
+### 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 → 刷新
+    if (s.modalTaskId === data.task_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/blackboard_routes.py` | checkpoint approve 后推送 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/blackboard_routes.py` | checkpoint approve 后推送 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 后推送 SSE checkpoint_resolved 事件
+3. TaskModal 打开时收到相关 SSE 事件自动刷新（debounce 500ms）
+4. 庞统 prompt 包含需求探索指引
+5. 现有测试不 regression
+
+---
+
+## 八、不做的事
+
+- 不做 AI 自然语言摘要（D1）
+- 不做 SSE 事件 payload 丰富化（D2）
+- 不新建前端展示面板（D3）
+- 不做专门的需求探索 API（复用 checkpoint + comment）
+- 不做需求模糊度自动评分（庞统自主判断即可）