---
name: team-communication
description: 团队沟通（通用问题冒泡）——问题按类型沿冒泡路径在团队角色间流转，解决即停、未解决继续冒泡、尽头由人兜底。触发：agent 发现问题、角色提问、PM 退回、故障上报、客户提问等。
---

# 团队沟通（通用问题冒泡）

## 核心概念

- **团队** = 一组不同角色的 agent + 人（`pipeline_team_roles` 表，每个成员 = role_name + agentid）。
  - 多 agent 存在：同一角色可有多个 agent，必须用 `agentid` 区分到具体处理方。
  - `role_type`：`agent`（AI agent）/ `human`（人，如客户）。
- **问题类型**（`pipeline_problem_types`）= 一条冒泡路径 `escalation_path`（处理方序列）。
- **冒泡路径条目**：`"role_name"`（该角色任意 agent/人）或 `{"role":"x","agentid":"y"}`（指定 agent）。

## 冒泡规则（核心）

```
提出问题 raise → 沿路径第一个处理方开始
    ↓
处理方判断：
  解决了  → resolve（status=answered，停止冒泡，任务恢复）
  没解决  → escalate（escalation_pos+1，沿路径继续走到下一个处理方）
    ↓
路径尽头 = 最后一个处理方（通常是"人" customer，兜底）
```

## 工具

| 工具 | 作用 |
|---|---|
| `list_questions` | 列出「当前该我（主agent）处理」的问题（不混入退回给角色 agent 的） |
| `answer_question` | 回答/解决 → 停止冒泡，任务恢复 |
| `escalate_question` | 答不了 → 沿冒泡路径转下一个处理方（通常转客户） |
| `diagnose_project` | 「待回答问题」计数 = 当前该主 agent 处理的问题数 |

后端引擎（`pipeline_service/communication.py`）：`raise_problem` / `resolve_problem` / `escalate_problem` / `list_problems_for`。

## 处理流程（发现「待回答问题」> 0 时必须执行）

1. `list_questions` 列出所有「待我处理」的 pending 问题，不要只报统计数字。
2. 对每个问题：
   - 你能解决 → `answer_question` 直接回答（任务自动恢复，冒泡停止）。
   - 你答不了 → `escalate_question` 沿冒泡路径转下一个处理方（客户），等对方回答后再闭环。

## SDLC 产线默认问题类型（sdlc_general）

| 问题类型 | 冒泡路径 | 说明 |
|---|---|---|
| `need_info` | `[main_agent, customer]` | 角色 agent 缺信息 → 主 agent 答 / 转客户 |
| `review_reject` | `[被退角色, pm]` | PM 退回 → 被退角色响应 / 兜回 pm |
| `fault_report` | `[main_agent, customer]` | 任务失败报障 → 主 agent / 客户人工介入 |

## 多 agent 路由规则

- 处理方 `agentid` 为空 = 该角色任意 agent 可处理。
- 处理方 `agentid` 指定 = 只有该 agent 能处理（同角色其他 agent 看不到）。
- 角色 agent 重新认领任务时，只注入「本角色/本 agent」应响应的 pending 退回意见（`get_task_qa(include_pending_for=role, include_pending_agentid=agentid)`）。

## 相关文件

- `pipeline_service/communication.py` — 通用冒泡引擎（raise/resolve/escalate/list_for）
- `pipeline_service/questions.py` — 向后兼容层（agent_ask/answer_question/forward_question 委托 communication）
- `pipeline_service/agent_loop.py` — 角色提问(need_info)、PM 退回(review_reject)、故障(fault_report)、PM 审核通过答结
- `pipeline_service/sdlc_ability.py` — cockpit 工具 list_questions/answer_question/escalate_question
- `pipeline-core/models/pipeline_team_roles.json` + `pipeline_problem_types.json` — 团队角色 + 问题类型定义