@@ -0,0 +1,460 @@
# 智能体工作过程流式展示与 subagent 子页面设计
> 版本：v1.0（设计稿，未实施）
> 日期：2026-09-28
> 任务：subagent-process-view-design-2026-09-28
> 作者：Cursor（owner），三路并行代码探索 + 主线调研交叉验证
> 交付物性质：系统设计文档，**不含任何代码实施**（用户明示"可以先不实现"）
---
## A. 目标与参照
### A.1 用户需求
1. 让助手的工作过程像豆包、kimi、codex 等工具一样对外输出：**思考（thinking）、工具调用（tool call）、过程内容输出**三类信息；
2. 使用**流式输出**持续更新助手的工作过程，而非终态一次性呈现；
3. 多智能体小队设计 **subagent 子页面**承载上述展示（先设计，不实现）。
### A.2 参照产品的展示形态拆解
| 产品 | 思考展示 | 工具调用展示 | 增量输出 | 交互模式 |
|---|---|---|---|---|
| 豆包 | "深度思考"折叠块：思考中呼吸态滚动，完成后折叠为一行摘要，可点击展开全文 | 工具卡片：图标+工具名+入参摘要+结果摘要+耗时 | 正文逐 token 流式 | 主流内嵌折叠，不打断阅读 |
| kimi | 推理过程折叠区，默认收起，进行中有进度感 | 搜索/工具步骤条 | 逐段流式 | 同上 |
| codex（
共同设计语言：**默认折叠（低认知负荷）→ 状态可感知（进行中动效）→ 按需展开（全文/详情）→ 归档后可回放**。
### A.3 本仓已有基座与约束
本设计不是从零发明，而是延伸既有三层信息架构（2026-09-08 streaming-events 设计，已归档但语义仍有效）：
- **L1 phase/status**（ `task_run_events` ）；
- **L2 summary/delta/briefing**（
- **L3 detail**（ `DetailPayload.category: agent_thought/tool_call/step_output/log` ），但无生产者、双重丢弃**——本设计的主战场。
既有 UX 约束必须继承：
1. **不打扰原则 ** ：detail 默认折叠，不默认展开思考链/工具日志（2026-09-09 chat-wait-error-retry 设计 P1 明确）；
2. **透明可追溯 ** ：详细思考与草稿不丢失，按需可查（工作区文件留存兜底）；
3. **治理红线 ** ：过程展示只是可视化，**不改变验收证据边界**——PI 叙事、模型输出不能冒充 PASS/测试证据（AGENTS.md 安全与证据）。
### A.4 概念区分（重要）
本设计的 "subagent" 指**产品内小队成员**（ `internal/squad` 的 AgentSpec： `scripts/pi_subagents.py` + `.doc/ops/2026-09-24-pi-subagent-executor.md` ）。两者名字相近但完全不同域，实施时不得混用数据源。
---
## B. 过程事件协议扩展
### B.1 现状协议回顾
`internal/stream/types.go` 的 `StreamEvent` 已定义 12 种事件类型；其中 `DetailPayload` ：
``` go
// internal/stream/types.go:68
type DetailPayload struct {
Category string ` json:"category" ` // agent_thought, step_output, tool_call, log
StepID string ` json:"step_id,omitempty" ` // 步骤标识 (如 tasks/01_regulatory)
Role string ` json:"role,omitempty" ` // 对应角色
Title string ` json:"title" `
Content string ` json:"content" ` // 完整推演正文或技术草稿
Collapsible bool ` json:"collapsible" `
}
```
现状问题：
1. 只有 `Content` 全文单帧，无增量模式（思考链逐 token 需要数百帧，全文帧会放大 N 倍流量）；
2. 无 `RunID` 冗余（事件重放时按 run 已隔离，可省；但 live 合并需要前端从通道上下文取）；
3. 并行步骤下 `Role` /`StepID` 已有，但前端折叠键没有用它们（见 B.4）。
### B.2 DetailPayload 扩展（增量模式）
``` go
// 设计草案（不实施）
type DetailPayload struct {
Category string ` json:"category" ` // agent_thought | tool_call | step_output | log（沿用四类）
StepID string ` json:"step_id,omitempty" ` // 步骤标识（如 tasks/03_regulatory）
Role string ` json:"role,omitempty" ` // 成员角色 key（如 regulatory）
RunID string ` json:"run_id,omitempty" ` // 冗余 run 标识（重放通道按 run 已隔离，可选）
Seq int64 ` json:"seq,omitempty" ` // 同一 (category, step_id, role, item_id) 流内的序号
ItemID string ` json:"item_id,omitempty" ` // 聚合项 ID：一个思考块/一次工具调用/一份产出
// 增量模式三选一：
Delta string ` json:"delta,omitempty" ` // 增量帧：追加到 ItemID 项
Content string ` json:"content,omitempty" ` // 终帧/快照帧：ItemID 项的完整内容（或无增量能力的发送方）
Done bool ` json:"done,omitempty" ` // 终帧标记（ItemID 项结束）
Title string ` json:"title,omitempty" `
Collapsible bool ` json:"collapsible" `
// tool_call 特化字段（Category == "tool_call" 时）：
Tool * ToolCallInfo ` json:"tool,omitempty" `
}
type ToolCallInfo struct {
Name string ` json:"name" ` // write_file / read_file / grep ...
Status string ` json:"status" ` // calling | succeeded | failed
Input string ` json:"input,omitempty" ` // 入参摘要（JSON，可能分帧）
Output string ` json:"output,omitempty" ` // 结果摘要（可能分帧）
DurationMs int64 ` json:"duration_ms,omitempty" `
}
```
**增量语义 ** （关键设计决策）：
- 发送方优先逐帧 `Delta` ； `Content` 用于两类场景：(a) 无流能力的发送方（如既有 `step_output` 整段产出），(b) 周期性**快照对账帧**（防止增量丢帧后内容漂移）；
- 客户端按 `(StepID, Role, Category, ItemID)` 聚合：`Delta` 追加、`Content` 覆盖、`Done` 定稿；
- 节流（发送方义务，见 F.1）：逐 token 事件合并为 ~100–300ms 批帧，单帧上限（如 8KB）超限分帧。
### B.3 llm 层事件扩展（reasoning 链）
`internal/agentx/llm` 现有事件只有 `text_delta/tool_call_delta/message_end/error` 。OpenAI 兼容国产模型（MiniMax/DeepSeek 系）在 delta 中返回 `reasoning_content` 字段（思考链）。扩展：
``` go
// internal/agentx/llm/types.go 设计草案
const (
KindTextDelta EventKind = "text_delta"
KindReasoningDelta EventKind = "reasoning_delta" // 新增
KindToolCallDelta EventKind = "tool_call_delta"
...
)
type Event struct {
Kind EventKind
Text string
ReasoningDelta string // 新增：reasoning_content 增量
...
}
```
`ParseSSE` （ `delta.reasoning_content` → `KindReasoningDelta` 。
**容器侧对应 ** ： `deploy/pi-agent/runner.mjs:24` 的 `stripThinkBlocks` 目前把 `<think>…</think>` 块从产物中剥离（丢弃）。设计上不改变"正文不含 think"的既有约定，而是在**剥离前**把 think 块作为 reasoning 事件分流转发（见 C.5）。
### B.4 并行步骤归属路由（修复既有缺陷）
现状 `PhasePayload` 折叠键为 `phase_id#step_index` （ taskrun/phase_snapshot.go:225 ](../../../internal/taskrun/phase_snapshot.go ) 与 [web/src/engine/phaseEventMapper.ts:65 ](../../../web/src/engine/phaseEventMapper.ts )），**并行组成员**（多个 role 同时 `step_executing` ）若无 step_index 会互相覆盖/误折叠。
设计：折叠键升级为 `phase_id#step_index@role` （ `applyPhaseEvent` 与后端 `FoldPhaseEvents` 同步修改，语义保持对齐（两处折叠逻辑本就要求一致，见 phase_snapshot.go 注释）。detail 事件天然带 `role/step_id` ，聚合不受影响。
### B.5 通道选择：沿用 stream/StreamEvent，不新增域事件
理由：
1. `events.StaticContracts` （ （
2. `task_run_events` （ ） `after_seq` 重放已为过程事件准备好持久化与断线恢复；
3. chat SSE 通道（链路 A）无持久化，但 B 轨参谋对话的过程展示可接受"live-only + 终态落库"（
---
## C. 后端链路打通设计（七断点逐条）
### C.0 总览
```
【链路 B：长任务（本设计主通道，先做）】
worker goroutine (taskrun.Manager.runWorker)
└ bizdev.ExecuteTask → squad.WorkflowDriver.runOneStep
└ agent.Backend.Execute(OnEvent 回调) ← 断点 4
├ pi-native: agentx.Run(OnEvent) ← 断点 2/3（直通）
│ └ llm.Stream: reasoning/text/tool delta ← 断点 1
└ pi-agent: POST runner /v1/run/stream ← 断点 5（
└ Streamer.EmitDetail(category, stepID, role, ...) ← 断点 6 之前：detail 已能出 Streamer
└ Manager.appendEvent → task_run_events (seq) ← 持久化（已就绪）
└ SSE: GET /tasks/runs/{id}/events ← 透传（已就绪）
└ 前端 detail 渲染分支 ← 断点 7
【链路 A：聊天 SSE（P4 再做）】
chat.Session → coordinator.generateDialogueReply
└ dialogueBackend.Execute(OnEvent) → token 级 EmitDelta（替换一次性 EmitDelta 伪流式）
```
### C.1 断点 1：
- 文件：[internal/agentx/llm/sse.go ](../../../internal/agentx/llm/sse.go )（ `sseChoice.Delta` 增 `ReasoningContent string \` json:"reasoning_content"\``）、[internal/agentx/llm/types.go](../../../internal/agentx/llm/types.go)（ Event` 增 ` ReasoningDelta` + ` KindReasoningDelta`）
- 语义：reasoning 与 text 分开累计；`message_end` 的 `Message.Content` 仍只含 text（与 runner `stripThinkBlocks` 语义对齐：正文无 think）。
- 兼容性：无 reasoning 的模型零行为变化（字段空即无事件）。
### C.2 断点 2：
- 文件：[internal/agentx/loop.go:178-183 ](../../../internal/agentx/loop.go ) `consume()` ： `case llm.KindToolCallDelta` 增加转发（emit 一个 `tool_call_delta` Event，带 ToolName/ArgumentsDelta）；`KindReasoningDelta` 同理转发 `reasoning_delta` 。
- `agentx.Event` （ `Kind string` （ `Type` 前缀约定（`text_delta` /`reasoning_delta` /`tool_call_delta` /`tool_execution_start` /`tool_execution_end` …已够用，推荐复用 Type）。
### C.3 断点 3：
**设计取舍 ** ：不改 `Backend.Execute` 签名（改签名会波及 stub/fallback/limiter 全部实现与调用方），改为 **Request 增可选回调 ** ：
``` go
// internal/agent/backend.go 设计草案
type Request struct {
...
// OnEvent 过程事件回调（nil = 不需要过程，行为与现状完全一致）
// 实现方必须保证：回调在 Execute 返回前完成（同步或等待收尾），无泄漏 goroutine。
OnEvent func ( ev ProcessEvent )
}
// ProcessEvent 对 agentx.Event 与 runner NDJSON 事件的统一投影
type ProcessEvent struct {
Type string // text_delta | reasoning_delta | tool_call_delta | tool_execution_start | tool_execution_end | message_end | ...
Text string // delta 文本（Type 为 *delta 时）
Tool string // 工具名
Detail string // 工具参数/结果摘要（tool_execution_* 时）
}
```
- pi-native（ internal/agent/pinative.go ](../../../internal/agent/pinative.go )）：`agentx.Run` 的 `OnEvent` 双写——既拼 `execution.log` （现状保留），又投影到 `req.OnEvent` ；
- `WrapWithConcurrencyLimit` 透传 Request 即透传回调，无需改；
- fallback/stub：
### C.4 断点 4：
[internal/squad/workflow.go ](../../../internal/squad/workflow.go ) `runOneStep` （构造 `agent.Request` 处，约 :543）：
``` go
// 设计草案
if req . OnEvent == nil {
req . OnEvent = func ( ev agent . ProcessEvent ) { /* 仅拼日志（现状） */ }
}
// 注入流式桥（streamer 可为 nil，安全）
req . OnEvent = chainEvents ( req . OnEvent , squadDetailBridge ( streamer , step ) )
```
`squadDetailBridge` （新函数，~40 行）把 `ProcessEvent` 翻译为 `EmitDetail` ：
| agentx/runner 事件 | EmitDetail 映射 |
|---|---|
| `reasoning_delta` | category=agent_thought, delta 帧, ItemID=`step.ID#thought<N>` |
| `text_delta` | category=agent_thought 的草稿子项（或 P2 可选：不改，任务正文走终态 step_output，避免与最终 deliverable 重复）→ **推荐 P0 不发 text_delta，仅 reasoning + tool ** |
| `tool_call_delta` | category=tool_call, delta 帧（入参增量）, ItemID=`step.ID#tool<N>` |
| `tool_execution_start` | tool_call 项 status=calling 帧 |
| `tool_execution_end` | tool_call 项 status=succeeded/failed + Output 摘要 + duration 帧 |
| `message_end` | 对应 ItemID 的 done 帧 |
节流在 bridge 内做（100–
**B 轨参谋（链路 A， ） ** ： internal/coordinator/dialogue_llm.go ](../../../internal/coordinator/dialogue_llm.go ) `generateDialogueReply` 同样注入 `OnEvent` ，把 `text_delta` 逐帧转 `streamer.EmitDelta` （替换 [internal/chat/session.go:624 ](../../../internal/chat/session.go ) 一次性 `EmitDelta(NaturalReply)` ），`reasoning_delta` 转 `EmitDetail(agent_thought)` 。注意 chat SSE 无持久化——断线后靠 `chat_turns` 终态查询（现状机制），过程帧不可恢复（可接受，与豆包/kimi 行为一致）。
### C.5 断点 5：远程 runner 流式端点
[deploy/pi-agent/runner.mjs ](../../../deploy/pi-agent/runner.mjs ) 增加端点（不动 `/v1/run` 既有契约——`ResultV1` typed 校验、wire 预算 8MB 等全部保留）：
```
POST /v1/run/stream Content-Type: application/x-ndjson（ ）
请求体 = /v1/run 同构 + stream: true
响应 = 逐行 NDJSON：
{"type":"proc","ev":{...pi RPC stdout 事件行...}} // 过程事件（原样转发已解析的行）
...（执行中持续 flush）
{"type":"result","body":{...与 /v1/run 完全相同的 typed 结果...}} // 终帧
```
- runner 侧改动集中在 `handleRun` ： `on("data")` 里既有的逐行 JSON 解析循环（runner.mjs:365-388）旁路一个转发器；`stripThinkBlocks` 之前先把 think 块作为 `{"type":"reasoning_delta"}` proc 帧发出；
- Go 侧 [internal/agent/piagent.go ](../../../internal/agent/piagent.go ) `executeRemote` ： `req.OnEvent != nil` 时改走流式端点——`http.Client` 无总超时的流式变体（`Timeout` 由 ctx 控制），bufio 逐行读：`proc` 帧 → `req.OnEvent` 投影；`result` 帧 → 走既有 `DecodeRemoteRun` 校验路径（**终态校验逻辑零改动**，保证治理边界不放松）；
- 降级：流式端点 404（旧 runner）→ 回落 `/v1/run` 一次性调用 + 无过程事件（`capabilities` 探测亦可，但 404 回落更简单）。
### C.6 断点 6：
两处硬编码/丢弃：
1. [internal/taskrun/manager.go:364 ](../../../internal/taskrun/manager.go ) `stream.WithListener(ctx, false, listener)` ——worker 侧 Streamer 是否发 detail 由**创建时**决定。设计：`CreateAndStart` /`StartClaimedRun` 透传 `IncludeDetails` （ `RunRecord` 或 `CreateOptions` 增字段；默认 false 保持现状）。**注意**：detail 是否持久化与是否推送解耦——建议 **detail 一律持久化 ** （ `task_run_events` JSONB 足够），`includeDetails` 只控制 live 推送与 chat 通道；重放端点用 query `include_details=0` 过滤，历史 subagent 页面仍可全量回放。取舍理由：持久化膨胀可控（F.1 节流后估算），而"刷新后过程消失"违背透明可追溯原则；
2. [internal/server/sse.go:476 ](../../../internal/server/sse.go ) `_ = includeDetails` ——`StreamChatRequest.IncludeDetails` 已存在（chat 通道）但 task 通道读取后丢弃；接线到 worker 创建。
### C.7 断点 7：前端协议与分支
- [web/src/api/chatStream.ts ](../../../web/src/api/chatStream.ts ) `StreamEvent` 增 `detail?: { category?: string; step_id?: string; role?: string; item_id?: string; seq?: number; delta?: string; content?: string; done?: boolean; title?: string; collapsible?: boolean; tool?: { name?: string; status?: string; input?: string; output?: string; duration_ms?: number } }` ；
- [web/src/hooks/useTaskRunAttempts.ts ](../../../web/src/hooks/useTaskRunAttempts.ts ) `onEvent` switch 增 `case 'detail'` ：聚合进消息的 `processItems` （见 D.4），不进正文。
---
## D. subagent 子页面设计（重点）
### D.1 入口与路由
**决策：扩展 hash 路由，不引入 react-router。 **
理由：
| 方案 | 优点 | 代价 |
|---|---|---|
| A. hash 扩展（推荐） | 复用 [web/src/engine/anchorNavigator.ts ](../../../web/src/engine/anchorNavigator.ts ) 既有解析/监听先例（`#/s/{sessionId}/m/{messageId}` ）；零新依赖；与"工作台为唯一应用视图"的产品形态匹配 | 顶层 view 状态机要加一态；深链参数解析手写 |
| B. react-router | 标准 | 新依赖 + 全仓路由心智迁移；App.tsx 1758 行重构风险；本需求只有一个子页面，收益不成比例 |
路由形态：
```
#/s/{sessionId}/run/{runId}/agents → 子页面（默认选中当前 running/最近完成成员）
#/s/{sessionId}/run/{runId}/agents/{roleId} → 子页面（选中指定成员）
```
实现骨架（设计草案）：
- App.tsx 顶层 view 状态机扩展：`'workbench' | 'admin' | 'subagents'` ； `parseAnchorHash` 扩展识别 `/run/{runId}/agents` 段；
- `handleSubagentsView` 由 TaskRunCard 的"查看小队过程"入口触发（写 hash 触发 hashchange，与消息深链同一机制）；
- 子页面经 `OnDemand` （ web/src/components/lazy/OnDemand.tsx ](../../../web/src/components/lazy/OnDemand.tsx )）懒加载，**props 最小化**：仅 `runId` 、`sessionId` 、`onExit` （返回 workbench）——规避 App.tsx props 钻透：子页面自持 SSE 订阅与状态，不依赖父容器消息流。
### D.2 页面信息架构
```
┌──────────────────────────────────────────────────────────────┐
│ 小队过程 · {任务标题} · run:{runId 截断} [刷新] [返回对话] │
├──────────────┬───────────────────────────────────────────────┤
│ 成员卡列表 │ 选中成员（role: regulatory 法规专员） │
│ │ ┌ 状态条: ⚙️ 正在执行 · 已用 2m13s · 第2/5步 ┐ │
│ 👤 organizer │ └──────────────────────────────────────────┘ │
│ ✅ 完成 1m2s│ ┌ ThinkingBlock（默认折叠）──────────────┐ │
│ 👤 searcher │ │ 💭 思考中…（流式增量，呼吸态） │ │
│ ✅ 完成 3m4s│ └───────────────────────────────────────┘ │
│ 👤 regulatory│ ┌ ToolCallCard ─────────────────────────┐ │
│ ⚙️ 执行中 │ │ 🔧 read_file tasks/01.../output.md │ │
│ 👤 writer │ │ ✅ 213ms · 12KB │ │
│ ⏳ 等待 │ └──────────────────────────────────────┘ │
│ 👤 leader │ ┌ ThinkingBlock（第二段）──────────────┐ │
│ ⏳ 等待 │ ... │ │
│ │ ┌ 步骤产出 output.md（终态 step_output）┐ │
│ [成员详情] │ │ 📄 阶段性产出（可展开全文） │ │
│ │ └──────────────────────────────────────┘ │
├──────────────┴───────────────────────────────────────────────┤
│ 事件时间线（跨成员 phase 事件折叠，复用 applyPhaseEvent 语义） │
└──────────────────────────────────────────────────────────────┘
```
- **左栏数据源**： `squad.json` （成员编制：role/Name/Responsibilities——工作区文件，经新只读端点或既有 workspace API 投影）+ phase/detail 事件聚合出状态与耗时（`step_executing` /`step_completed` /`step_failed` by role）；
- **右栏数据源**：detail 事件流按 `role == selected` 过滤，聚合为 `processItems` （见 D.4）；
- **底部时间线**：全量 phase 事件（复用 `TaskRunCard` 折叠逻辑与 `PhaseEvent` 类型）。
### D.3 三类过程组件
| 组件 | 状态 | 内容来源 | 交互 |
|---|---|---|---|
| `ThinkingBlock` | thinking（呼吸态+增量滚动）/ done（折叠为一行摘要：前 40 字 + 字数）/ error | `agent_thought` 增量帧聚合 | 默认折叠；点击展开全文（Markdown 渲染）；进行中可"实时展开" |
| `ToolCallCard` | calling（转轮）/ succeeded（绿勾+耗时）/ failed（红叹+错误摘要） | `tool_call` 帧聚合（name/input/output/status/duration）
| `ProcessStepOutput` | done | 既有 `step_output` 整段 content | 默认折叠，展开渲染 Markdown |
组件均为纯展示组件（props 驱动），放置 `web/src/components/subagents/` ，配 `node:test` 静态断言测试（与仓内组件测试形态一致）。
### D.4 前端数据流与状态
``` typescript
// 设计草案：web/src/hooks/useRunProcessStream.ts
type ProcessItem = {
key : string ; // `${stepId}/${itemId}`
category : 'agent_thought' | 'tool_call' | 'step_output' | 'log' ;
role : string ;
stepId : string ;
title? : string ;
text : string ; // delta 累计或 content 快照
status : 'streaming' | 'done' | 'error' ;
tool ? : { name : string ; status : string ; input? : string ; output? : string ; durationMs? : number } ;
updatedAt : number ;
} ;
function applyDetailEvent ( items : Record < string , ProcessItem > , ev : DetailEvent ) : Record < string , ProcessItem >
// 纯函数（与 applyPhaseEvent 同风格，node:test 可测）：
// delta → 追加 text、status=streaming
// content → 覆盖 text（快照对账）
// done → status=done
// tool 帧 → 合并 tool 字段
```
订阅策略（复用既有骨架）：
- **live**： `subscribeTaskRunEvents(runId, { onEvent, afterSeq })` （ web/src/api/taskRuns.ts:113 ](../../../web/src/api/taskRuns.ts )），事件分发：`phase` → 左栏状态 + 底部时间线；`detail` → `applyDetailEvent` ；
- **刷新/进入已结束 run**：先 `readTaskRunSSEOnce(runId, 0, …, { replayOnly: true })` 全量重放（事件已持久化，见 C.6），再决定是否续订 live；
- **超量回放保护**： `after_seq` 分页重放（既有能力），detail 大 run 可先只重放 phase + 按需拉成员 detail（ `GET /runs/{id}/events?role=xxx&include_details=1` 过滤参数为可选增强，P2.5）。
### D.5 与主对话气泡的联动
- 气泡内 `TaskRunCard` 保持现状（L1 时间线），新增两处：
1. 运行中：卡片底部一行"查看小队过程 →"（写 hash 深链进子页面）；
2. 完成后：L3 摘要条（如"5 名专员 · 12 次工具调用 · 3 段推演"），点击同样进子页面；
- **不把全量 detail 渲染进气泡**——认知负荷原则：气泡只承载 L1/L2，L3 全文在子页面。`MessageBubble` 现有 `message.phaseEvents` 通道不动。
### D.6 前端基础设施缺口补齐（实施前置）
1. **块级 Markdown + 代码高亮 ** ：现状 `renderInlineMarkdown` 仅行内语法（[web/src/engine/renderMarkdown.ts ](../../../web/src/engine/renderMarkdown.ts )）。工具调用入参/结果需要 fenced code block + JSON 高亮。方案：`renderMarkdown` 增块级分支（heading/fence/list——解析器自研或引入 `marked` /`react-markdown` ；倾向自研轻量扩展，避免新依赖与 XSS 面扩大，沿用现有 escape 纪律）；
2. **高频增量渲染性能 ** ： `React.memo` 行项；
3. **通用折叠组件 ** ：自研 `CollapsibleBlock` （受控 `open` + `Summary` 插槽），三组件复用。
### D.7 后端配套只读端点（成员编制）
子页面左栏需要 `squad.json` 。设计（P2 内最小）：
```
GET /api/v1/tasks/runs/{run_id}/squad
→ { members: [{ role, name, responsibilities, source }], task_key, title }
```
实现：taskrun Manager 读 `record.WorkspaceID` → 工作区 `squad.json` 反序列化（只读投影，权限沿用 run 事件的 `RequireProjectAccess` ）。
---
## E. 分期实施路线
| 期 | 内容 | 验证形态（按验证契约） | 依赖 |
|---|---|---|---|
| **P0 协议+直通 ** | B.2/B.3 协议扩展；C.1– （ （
| **P1 气泡过程块 ** | D.5 气泡内 L3 摘要 + 折叠 ThinkingBlock（最小渲染，块级 markdown 只做 fence+JSON）
| **P2 subagent 子页面 ** | D.1–D.7 全量（hash 路由、成员卡、过程流、squad 端点） | 前端单测 + Playwright spec（新增 e2e/subagents-view.spec.ts）
| **P2.5（可选） ** | 事件过滤参数（role/include_details query）；大 run 分页回放 | 接口测试 | P2 |
| **P3 runner 流式 ** | C.5 `/v1/run/stream` + piagent 流式消费 + 404 回落 | runner 单测（mjs 侧 settle-policy 风格）+ 真实容器验收（dev） | P0（可并行） |
| **P4 B 轨参谋 ** | C.4 尾段：dialogue_llm OnEvent → token 级 EmitDelta + reasoning detail | 真实 PI 对话链路验收（chat SSE）
| **P5（演进） ** | 历史回放端点（transcript.jsonl/execution.log 投影 API）；per-member 持久化表（如 `task_run_step_events` ，仅当 JSONB 容量实测超限） | 视实测 | P2/P3 |
每期独立合入（Conventional Commits： `feat(stream)/feat(web)` 前后端分原子提交），P0 即可演示 pi-native 路径的"思考流+工具卡"。
---
## F. 风险与边界
### F.1 事件量与持久化膨胀
- **节流义务在 bridge**（ – `step_output` 保持现状单帧（终态产物已有 `deliverable` 通道与文档存储，不重复全文持久化时可评估只存摘要——P0 先全文，P2.5 实测再收紧）；
- **容量估算**：单 run 5 成员 × – × `task_run_events` JSONB 单行无硬限，可控；
- **兜底**： `execution.log` /`transcript.jsonl` 仍全量落盘工作区（现状不变），P5 投影 API 作历史回放。
### F.2 认知负荷与安全
- detail 默认折叠贯穿三处（气泡摘要、子页面 ThinkingBlock、ToolCallCard 入参/结果摘要）——继承 2026-09-09 设计 P1 约束；
- **脱敏**： `ProcessEvent` 设计上就不含这些来源）；
- **治理红线**：过程事件不写 `events` 域总线、不参与验收判定；测试/审查结论仍以报告路径与 receipt 为准（pi-subagents 规则），本设计纯可视化。
### F.3 兼容与降级
- 旧 runner（无 `/v1/run/stream` ）→ 404 回落一次性调用，功能退化为 L1 时间线（现状）；
- `OnEvent == nil` → 所有后端行为与现状完全一致（回调是纯增量）；
- 前端不识别 detail（旧前端 + 新后端）→ JSON 字段忽略，无破坏；
- `includeDetails` 默认 false → chat 通道现状不变。
### F.4 并行正确性
- 并行组多成员同时发 detail： `Streamer.Emit` 已有 RWMutex；
- 前端聚合键含 role/stepID（B.4），并行不串扰；
- `step_output` 终态帧在并行完成回调内发出（现状 workflow.go:746 位置不变）。
### F.5 明确不做
- 不引入 WebSocket（
- 不做过程事件的域总线登记（B.5 理由）；
- 不做 B 轨 chat 过程帧的持久化与断线重放（P4 live-only，终态落库现状）；
- 本期不实现任何代码（用户授权边界）。
---
## G. 附录：断点-文件-方案对照表
| # | 断点 | 文件:行 | 方案章节 |
|---|---|---|---|
| 1 | reasoning_content 未解析 | internal/agentx/llm/sse.go、types.go | C.1 / B.3 |
| 2 | agentx 丢弃 tool_call_delta | internal/agentx/loop.go:178-183 | C.2 |
| 3 | Backend 黑盒无回调 | internal/agent/backend.go:38、pinative.go:102 | C.3 |
| 4 | squad 层无成员过程流 | internal/squad/workflow.go:543(runOneStep) | C.4 |
| 5 | runner /v1/run 一次性 | deploy/pi-agent/runner.mjs:600 | C.5 |
| 6 | includeDetails 硬编码 false / 丢弃 | internal/taskrun/manager.go:364、server/sse.go:476 | C.6 |
| 7 | 前端无 detail 协议与分支 | web/src/api/chatStream.ts、hooks/useTaskRunAttempts.ts:474 | C.7 |
## H. 参考文件
- 三层信息架构基座：`.doc/archive/design/superpowers/specs/2026-09-08-streaming-events-and-digestible-ux-design.md`
- 认知负荷约束：`.doc/archive/design/superpowers/specs/2026-09-09-chat-wait-error-retry-ux-design.md`
- 小队编排（含 §18.5 演进方向）：`.doc/system-design/agent-squad/02-智能体小队编排-设计-思路-架构-实现-难点-解决方案-亮点与优势.md`
- 长任务 resume： `.doc/archive/design/superpowers/specs/2026-09-09-longtask-phase-live-resume-ux-design.md`
- 任务记录：`.doc/ops/short-term/2026-09-28-subagent-process-view-design.md`
weichen