# 6 步法推演问答页面 — 开发说明文档

> 所在目录：`src/components/angentchat/`（主页面 `SixStepChatPage.tsx`）  
> 路由地址：`/qa-center/sixstep-chat`  
> 菜单入口：问答中心 → **6bf**（侧栏文案见 `src/components/Sidebar.tsx`）  
> 同模块相关路由：`/qa-center/sixstep-agents`、`/qa-center/sixstep-agent-edit`  
> **最后更新（摘要）**：2026-05-12 — 流式 **`error_log`** / **`errors[]`** 与 `StreamErrorNotice`（后端 skill 失败摘要可含异常片段）；`buildLayout` 根节点 **`rootTitle` / `rootDetail`**（已选专家）；**`SixStepFlowFullscreen`** 父节点 **收起/展开子树**（过渡动画、缩略图随可见节点）；**`/observability`** 独立全站路由。

---

## 一、功能概述

「6bf 推演问答」由 `SixStepChatPage` 对接后端 **SixStep MCP Backend**。主链路通过 **`POST /api/orchestrate/stream`** 统一流式返回：后端先做 **意图识别**（`intent` 事件），再分支为 **查找专家**（`expert_*`）、**6 步法编排**（信息准备 → 目的 → 行为体 → 预期行为与驱动因素 → 叙事 → 最终结果）、**追问**（`follow_up`，`delta` 流式 Markdown）或 **澄清**（`clarify`）。支持 **结构化卡片** 与 **Markdown** 输出切换；结构化模式下可打开 **流程图沙箱 / 全屏流程图**（`SixStepFlowSandbox` / `SixStepFlowFullscreen`），展示编排返回的实体关系。

单 MCP 调试仍可直接调用 **`POST /api/agents/{key}/invoke`**（例如 `find_expert`、`create_expert`）；6bf 主页面以编排流为主，专家查找也可由流内 `intent` 分支触发。对接细节见同目录 **`INTENT_INTEGRATION.md`**。

页面布局为 **顶栏 + 下方主体**：顶栏含页面标题、`SixStepProgressHorizontal`（横向主/子步骤进度）、以及结构化·Markdown、聊天记录、流程图沙箱等控制；主体为 **可收起的会话列表轨**（`SixStepChatHistory`）、**中间对话区与输入**（`SixStepConversation` + `ChatInputComposer`，含专家匹配与 MCP 选择弹窗）、以及 **可选的右侧沙箱**（宽度可拖拽，可关闭）。全屏流程图仍以 `fixed` 遮罩覆盖视口，独立于上述布局。

```
┌──────────────────────────────────────────────────────────────────┐
│ 顶栏：标题 · SixStepProgressHorizontal · 输出格式 · 聊天记录 · 流程图 │
├───┬────────────────────────────────────────────────────┬─────────┤
│会话│  SixStepConversation（多轮结构化阶段）              │ 流程图  │
│列表│  + ChatInputComposer                             │ 沙箱    │
│轨 │                                                    │(可关闭) │
└───┴────────────────────────────────────────────────────┴─────────┘
```

---

## 二、目录结构与各文件职责

```
src/components/angentchat/
│
├── types.ts                     # 数据模型类型（含 phase / intent / rawSteps 等）
├── mockData.ts                  # 本地模拟流式控制器（与 api 侧事件对齐，便于离线演示）
├── api.ts                       # runIntentOrchestrateStream、runSixStepDeduction、runExpertSearch/Create
├── flowLayout.ts                # SVG 流程图布局
├── styles.css                   # 动画与工具类
│
├── SixStepChatPage.tsx          # 推演主页面（状态中枢）
├── SixStepProgressHorizontal.tsx# 顶栏横向主/子步骤进度（主页面使用）
├── SixStepProgress.tsx          # 纵向进度面板（组件保留；布局以横向为准）
├── SixStepChatHistory.tsx       # 会话列表轨（展开/收起）
├── SixStepConversation.tsx      # 对话区（阶段卡片 + 专家匹配）
├── SixStepCards.tsx             # 阶段卡片原子组件
├── ExpertMatchCards.tsx         # 专家匹配卡片
├── McpSelectModal.tsx           # MCP 多选确认弹窗
├── StreamErrorNotice.tsx        # 助手消息底部：汇总 SSE error_log / 网络类错误的可折叠提示条
├── SixStepFlowSandbox.tsx       # 右侧流程图沙箱
├── SixStepFlowFullscreen.tsx    # 全屏流程图
├── AgentCardList.tsx            # 路由 sixstep-agents：MCP 卡片列表
├── AgentEditPage.tsx            # 路由 sixstep-agent-edit：单 MCP 调试编辑
├── AgentChatMessageList.tsx     # 智能体对话消息列表（编辑页等）
├── INTENT_INTEGRATION.md        # 意图流与前后端字段说明（对接备忘）
└── doc.md                       # 本文档
```

---

## 三、数据模型（`types.ts`）

所有类型均从此文件导出，是各组件之间传递数据的唯一契约。

### 3.1 基础枚举

| 类型 | 取值 | 说明 |
|------|------|------|
| `MainStepKey` | `'info' \| 'sixstep' \| 'final'` | 三个主步骤的键名 |
| `SubStepKey` | `'purpose' \| 'actor' \| 'behavior' \| 'narrative'` | 6步法的四个子阶段键名 |
| `StepStatus` | `'pending' \| 'running' \| 'done'` | 步骤状态，驱动进度面板和动画 |
| `SixStepPhase` | `'idle'` \| `'intent-detecting'` \| `'expert-match'` \| `'expert-confirm'` \| `'generate'` \| `'paused'` \| `'completed'` \| `'clarifying'` \| `'follow-up'` | 助手消息所处交互阶段（与编排流、停止、追问等配合） |
| `SelectableMcpKey` | `'purpose' \| 'actor' \| 'behavior_factor' \| 'narrative'` | MCP 弹窗可选子链，会随请求传给后端 `selected_mcps` |

`BackendStepResult`：与后端 `step_end` 原始结构对齐，用于 **`continue_analysis`** 时把 `last_steps` 回传编排接口；`SixStepMessage.rawSteps` 在流式过程中累积，`resumedFrom` 对应 **`resume`** 事件中的继续起点。

### 3.2 卡片数据结构

每类卡片都有独立接口，并通过外键（`purposeId`、`actorId`、`driverId`）建立父子关联，构成树形层级关系。

```
PurposeCard (目的)
  └─ ActorCard.purposeId → PurposeCard.id
       └─ BehaviorDriverCard.actorId → ActorCard.id
            └─ NarrativeCard.driverId → BehaviorDriverCard.id
```

| 接口 | 字段 | 说明 |
|------|------|------|
| `PurposeCard` | `id, index, title, reason` | 目的卡片，包含标题和推演理由 |
| `ActorCard` | `id, index, purposeId, title, content` | 行为体卡片，`purposeId` 关联所属目的 |
| `BehaviorDriverCard` | `id, index, actorId, expectedBehavior, driver` | 预期行为 + 驱动因素二合一卡片，`actorId` 关联所属行为体 |
| `NarrativeCard` | `id, index, driverId, title, reason` | 叙事卡片，`driverId` 关联所属驱动因素（`BehaviorDriverCard.id`） |

### 3.3 阶段数据结构

每个子阶段有独立的 `*StageData` 接口：

```typescript
interface PurposeStageData {
  thinking: string;       // 模型思考过程文本（流式填充）
  cards: PurposeCard[];   // 已生成的卡片列表（逐张追加）
  complete: boolean;      // 该阶段是否完全结束
}
// ActorStageData / BehaviorStageData / NarrativeStageData 结构类似
```

### 3.4 消息总线：`SixStepMessage`

这是整个页面最核心的数据结构，一条助手消息包含所有推演状态：

```typescript
interface SixStepMessage {
  id: string;
  role: 'user' | 'assistant';
  content?: string;
  timestamp: Date;
  outputFormat?: 'structured' | 'markdown';
  markdownContent?: string;
  stages?: SixStepStages;
  finalAnswer?: string;
  mainStepStatus?: Record<MainStepKey, StepStatus>;
  subStepStatus?: Record<SubStepKey, StepStatus>;
  currentSubStep?: SubStepKey;
  currentMainStep?: MainStepKey;
  phase?: SixStepPhase;
  expertMatch?: ExpertMatchData;
  selectedExpert?: ExpertCard;
  selectedMcps?: SelectableMcpKey[];
  intent?: { name: string; confidence?: number; reason?: string };
  clarifyQuestion?: string;
  rawSteps?: BackendStepResult[];
  resumedFrom?: string;
  effectiveUserInput?: string;
  errors?: StreamErrorItem[];
}
```

**`errors` / `StreamErrorItem`**：`runIntentOrchestrateStream` 收到 SSE **`error_log`** 时追加；致命失败仍会走 **`error`** 事件并映射为同类结构。`SixStepConversation` 中 **`StreamErrorNotice`** 读取 `message.errors` 展示摘要（可折叠列表）。

**关键设计**：`mainStepStatus` / `subStepStatus` 驱动顶栏 `SixStepProgressHorizontal`；`stages` 驱动中间对话渲染；`currentSubStep` 驱动流程图沙箱蚂蚁线。`phase` / `intent` / `rawSteps` 与编排流、暂停继续、追问分支一致。所有信息集中在一个对象内，组件通过 props 按需取用。

---

## 四、模拟数据生成器（`mockData.ts`）

> **线上主路径**：`SixStepChatPage` 使用 **`runIntentOrchestrateStream`** 消费真实 `/api/orchestrate/stream`。`mockData.ts` 中的 **`runSixStepDeduction`** 仍保留，用于本地演示或与 `api.ts` 中纯编排解析逻辑对齐；新功能（意图、专家 SSE、`resume` 等）以 `runIntentOrchestrateStream` 为准。

### 4.1 种子数据

文件顶部定义了四组静态种子数组：

| 变量 | 长度 | 用途 |
|------|------|------|
| `PURPOSE_SEED` | 3 | 目的卡片内容模板 |
| `ACTOR_SEED` | 7 | 行为体卡片内容模板 |
| `BEHAVIOR_SEED` | 8 | 预期行为与驱动因素卡片内容模板 |
| `NARRATIVE_SEED` | 8 | 叙事卡片内容模板 |

使用时循环取模（`(counter - 1) % SEED.length`），确保不越界。

### 4.2 卡片生成规则

| 阶段 | 数量规则 |
|------|---------|
| 目的 | 固定 3 张（取自 `PURPOSE_SEED` 全量） |
| 行为体 | 每个目的对应的数量：第 0 个目的 2 张，其余 1 张，共 4 张 |
| 预期行为/驱动 | 每个行为体：偶数索引 2 张，奇数索引 1 张，共 6 张 |
| 叙事 | 每个预期行为：偶数索引 2 张，奇数索引 1 张，共 9 张 |

最终流程图节点总数：`1（智能体）+ 3 + 4 + 6×2（预期行为+驱动因素）+ 9 = 29 节点`。

### 4.3 流式控制器：`runSixStepDeduction`

```typescript
export function runSixStepDeduction(
  message: SixStepMessage,    // 直接在此对象上原地修改字段
  options: {
    onUpdate: (msg: SixStepMessage) => void;  // 每次有新内容时回调
    onComplete?: () => void;                   // 全部完成时回调
  }
): SixStepMockController
```

返回的 `SixStepMockController` 包含：
- `message`: 正在被修改的消息对象引用
- `stop()`: 立即取消所有待执行的 `setTimeout`，中止推演
- `promise`: 推演完成后 resolve 的 Promise（stop 后不再 resolve）

**内部时序**（所有延迟均可通过顶部常量调整）：

```
常量              默认值   说明
TYPE_INTERVAL     28ms     每次打字输出 4 个字符后的等待间隔
STAGE_GAP         380ms    阶段切换之间的等待时长
```

执行顺序（伪代码）：

```
setMain('info', 'running') → emit
wait(800ms)                           ← 模拟信息准备耗时
setMain('info', 'done')
setMain('sixstep', 'running') → emit
wait(STAGE_GAP)

setSub('purpose', 'running') → emit
typeInto(PURPOSE_THINKING)            ← 逐字打出思考过程
append cards 逐张（wait 280ms/张）
setSub('purpose', 'done') → emit
wait(STAGE_GAP)

setSub('actor', 'running') → emit
typeInto(ACTOR_THINKING)
append cards 逐张（wait 220ms/张）
setSub('actor', 'done') → emit
wait(STAGE_GAP)

setSub('behavior', 'running') → emit
typeInto(BEHAVIOR_THINKING)
append cards 逐张（wait 200ms/张）
setSub('behavior', 'done') → emit
wait(STAGE_GAP)

setSub('narrative', 'running') → emit
typeInto(NARRATIVE_THINKING)
append cards 逐张（wait 200ms/张）
setSub('narrative', 'done')
setMain('sixstep', 'done')
setMain('final', 'running') → emit
wait(STAGE_GAP)

typeInto(FINAL_ANSWER)                ← 逐字打出最终结论
setMain('final', 'done') → emit
onComplete()
```

**`emit` 机制**：每次调用 `onUpdate({ ...message, stages: { ...message.stages } })`，将消息对象浅拷贝后传给父组件，触发 React re-render。

---

## 五、流程图布局工具（`flowLayout.ts`）

此文件被沙箱和全屏组件共同引用，避免重复计算。

### 5.1 核心函数：`buildLayout`

```typescript
function buildLayout(
  purposes: PurposeCard[],
  actors: ActorCard[],
  behaviors: BehaviorDriverCard[],
  narratives: NarrativeCard[],
  options?: BuildLayoutOptions   // 可覆盖节点尺寸和间距，以及根节点文案
): FlowLayout
```

**`BuildLayoutOptions` 扩展**：除 `nodeWidth`、`nodeHeight`、`levelGap`、`nodeGap`、`paddingX`、`paddingY` 外，可选 **`rootTitle`**、**`rootDetail`**。用于将层级 0 的 `agent-root` 从默认「智能体 / 协同推演…」改为 **当前已选专家**（`SixStepFlowSandbox` / `SixStepFlowFullscreen` 在存在 `message.selectedExpert` 时传入专家姓名与简介摘要）。

返回 `FlowLayout`：
```typescript
interface FlowLayout {
  nodes: LayoutNode[];   // 已计算好坐标的节点列表
  edges: LayoutEdge[];   // 已确定连接关系和颜色对的边列表
  width: number;         // 整体画布宽度（用于 SVG viewBox）
  height: number;        // 整体画布高度
}
```

**布局算法**：改良的"叶节点优先后序遍历"：

1. 从 agent 根节点开始，递归 DFS 处理子树
2. 叶节点（无子节点的节点）按从左到右顺序分配 x 坐标，每次递增 `nodeWidth + nodeGap`
3. 非叶节点的 x = (最左子节点 x + 最右子节点 x) / 2，确保父节点居中于子节点上方
4. 所有节点的 y = `paddingY + level × (nodeHeight + levelGap)`，level 即树的深度

节点层级（`level`）对应关系：

| level | variant | 说明 |
|-------|---------|------|
| 0 | `agent` | 智能体根节点 |
| 1 | `purpose` | 目的 |
| 2 | `actor` | 行为体 |
| 3 | `behavior` | 预期行为 |
| 4 | `driver` | 驱动因素 |
| 5 | `narrative` | 叙事 |

注意：`BehaviorDriverCard` 一张卡片会生成两个节点（`behavior` + `driver`），id 分别为 `${card.id}-behavior` 和 `${card.id}-driver`。

### 5.2 共享常量

| 常量 | 说明 |
|------|------|
| `EDGE_COLOR` | 按边类型分别定义深色/浅色主题颜色（5 组） |
| `EDGE_LABEL` | 每种边类型的中文图例说明 |
| `CURRENT_PAIR_BY_STAGE` | `SubStepKey → LayoutEdge['pair']` 映射，决定哪组边在哪个阶段展示蚂蚁线 |
| `STATUS_TITLE` | `SubStepKey → string` 映射，沙箱/全屏顶部标题文字 |
| `VARIANT_ABBREV` | 节点类型 → 简化缩写（沙箱专用，如 `purpose → 'md'`） |
| `VARIANT_LABEL` | 节点类型 → 完整中文标签 |

### 5.3 辅助函数：`buildEdgePath`

生成 SVG 三次贝塞尔曲线路径字符串：

```
M x1 y1  C x1 my, x2 my, x2 y2
```

控制点均取中间 y 坐标（`(y1+y2)/2`），形成平滑 S 型连线，不与节点重叠。

---

## 六、CSS 动画（`styles.css`）

| 类名 | 动画 | 用途 |
|------|------|------|
| `.sixstep-ant-line` | `stroke-dasharray: 6 6` + `dashoffset` 循环 | SVG 边上的蚂蚁线流动效果（当阶段正在生成时） |
| `.sixstep-pulse` | box-shadow 呼吸光晕 | 进度面板当前步骤图标、沙箱标题图标 |
| `.sixstep-shimmer-text` / `...-light` | 渐变横扫文字 | 进度面板"生成中"文字、沙箱标题生成中状态 |
| `.sixstep-spin-soft` | 360° 匀速旋转 | loading 图标 |
| `.sixstep-fade-up` | 从下方淡入 | 子阶段卡片逐步出现 |
| `.sixstep-node-pop` | scale 弹出 + 高光 | 流程图新增节点的弹出动画（持续 600ms） |
| `.sixstep-ring-burst` | SVG circle `r` 从 0 扩散到 60，同时 opacity→0 | 节点出现时的扩散光环效果（持续 700ms） |
| `.sixstep-canvas-grab` / `.sixstep-canvas-grabbing` | `cursor: grab/grabbing` | 流程图画布拖拽手型 |
| `.sixstep-toolbar-btn` | 基础尺寸 + hover 过渡 | 工具栏图标按钮 |
| `.sixstep-minimap-rect` | 静态样式 | 缩略图视口矩形指示框 |
| `.sixstep-resize-handle` | 竖线拖拽手柄 | 沙箱左边缘的宽度调节拖拽条 |

---

## 七、主页面（`SixStepChatPage.tsx`）

### 7.1 职责

主页面是整个功能的**状态中枢**，负责：

- 多会话列表与 **`/api/conversations`** 持久化（`filter_key` / `filter_value` 标识 6bf 页）。
- 创建并管理 **`runIntentOrchestrateStream`**（编排 + 意图）与 **`runExpertSearch` / `runExpertCreate`**（仍可用于「换一批专家」「创建专家」等直连 invoke）的控制器生命周期。
- 将状态与专家相关回调分发给 `SixStepConversation`、`McpSelectModal`、`SixStepFlowSandbox` 等。
- 管理沙箱宽度拖拽。

### 7.2 状态一览（节选）

| 状态 | 类型 | 说明 |
|------|------|------|
| `conversations` / `activeConvId` | 多会话 | 当前选中会话及其 `messages` |
| `input` | `string` | 输入框文本 |
| `isGenerating` | `boolean` | 是否正在请求流式接口 |
| `outputFormat` | `'structured' \| 'markdown'` | 传给后端的 `output_format` |
| `sandboxOpen` / `sandboxWidth` / `fullscreenOpen` | UI | 流程图沙箱与全屏 |
| `historyOpen` / `loading` | UI / 加载 | 聊天记录侧栏与首屏拉取 |
| `activeAssistantMsgId` | `string \| null` | 当前高亮/流式更新的助手消息 |
| `mcpModal` | `{ open, messageId, expert }` | MCP 多选弹窗状态 |

### 7.3 Ref 一览

| Ref | 类型 | 用途 |
|-----|------|------|
| `controllerRef` | `SixStepMockController \| null` | `runIntentOrchestrateStream` 的 `stop()` |
| `expertControllerRef` | `ExpertRunController \| null` | 专家搜索/创建流的 `stop()` |
| `conversationsRef` | 会话数组 | 持久化前读取最新消息 |
| `containerRef` / `resizeRef` | DOM / 拖拽 | 沙箱宽度拖拽 |

### 7.4 核心逻辑

**`handleSend`**

1. 追加用户消息；创建初始助手消息（`buildInitialAssistantMessage`，`phase` 随流程推进）。
2. 调用 **`runIntentOrchestrateStream`**，请求体为 **`IntentOrchestrateRequest`**：`user_input`、`output_format`、`intent_mode`（默认 `auto`）、`current_phase`（含上一条助手为 **`paused`** 时传 `paused`）、`selected_expert`、`selected_mcps`、`expert_candidates`、**`last_steps`（来自上一条助手 `rawSteps`）**、`conversation_history` 等。
   - 暂停继续时会继承上一条助手的 `rawSteps` 与 `selectedMcps`（`pausedSelectedMcps`），并显式回传 `selected_mcps` / `last_steps`，避免恢复时丢失步骤选择与历史上下文。
3. `onUpdate` 内更新当前会话中对应 `id` 的助手消息；结束后 `persistConversation`。

**专家与 MCP**

- 用户确认专家后 **`handleMcpModalConfirm`**：写入 `selectedExpert` / `selectedMcps`，并可用 **`intent_mode: 'force_orchestrate'`** 立即启动分析（无需用户再次输入）。
- **`handleRefetchExpert`**：可用 `force_find_expert` 并排除已有候选。

**`handleStop`**

- `AbortController` 中止流；将未完成步骤从 `running` 收回；助手 **`phase` 置为 `paused`**，便于下次发送走 **`continue_analysis`** / `rerun_from_step` / `revise_input_continue` / `change_steps_continue` / `edit_stage_continue`。

**流内关键事件补充**

- `resume`：恢复继续分析时，会先把已有 `stages` 中的 `purpose/actor/behavior` 卡片回填到转换缓存，确保后续 `step_end` 的父子映射准确。
- `rerun`：前端会按 `affected_steps` 清空受影响阶段（`stages`、`subStepStatus`、`rawSteps` 与局部卡片缓存），再接收重跑后的 `step_*`。
- `change_steps`：按 `removed_steps` 清理被移除阶段与 `rawSteps`，保留未移除阶段并继续执行 `steps_to_run`。
- `edit_apply`：先更新被编辑卡片内容，再按 `affected_steps` 清理后续阶段并触发重跑。
- `intent`：包含 `slots`（如 `step`、`new_input`），用于更细粒度前端状态更新。

**沙箱宽度拖拽**：逻辑同前（`mousemove` / `mouseup`，保证对话区最小宽度）。

**活跃助手消息派生**：

```typescript
const activeAssistantId = /* activeAssistantMsgId 或最后一条 assistant */;
const activeAssistant = messages.find((m) => m.id === activeAssistantId);
const liveMainStatus = activeAssistant?.mainStepStatus ?? DEFAULT_MAIN_STATUS;
const liveSubStatus = activeAssistant?.subStepStatus ?? DEFAULT_SUB_STATUS;
```

`liveMainStatus` / `liveSubStatus` 传给 **`SixStepProgressHorizontal`**；`activeAssistant` 传给沙箱与全屏。

### 7.5 Props 传递图

```
SixStepChatPage
│
├─► SixStepChatHistory          # 会话列表（与顶栏「聊天记录」联动）
├─► SixStepProgressHorizontal   # mainStatus / subStatus / isDark
├─► SixStepConversation
│     messages, isGenerating, activeMessageId,
│     expertHandlers（选专家 / 换一批 / 创建 / 确认）
├─► ChatInputComposer           # onSend → handleSend, onStop → handleStop
├─► SixStepFlowSandbox          # message={activeAssistant}
├─► SixStepFlowFullscreen
└─► McpSelectModal              # 专家确认后选 MCP
```

---

## 八、左侧进度面板（`SixStepProgress.tsx`）

> **主页面顶栏**使用的是 **`SixStepProgressHorizontal.tsx`**（横向主/子步骤）；本节描述纵向 `SixStepProgress` 的 Props 与交互，组件仍保留供其他布局复用。

### 8.1 Props

| Prop | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mainStatus` | `Record<MainStepKey, StepStatus>` | ✓ | 三主步骤状态 |
| `subStatus` | `Record<SubStepKey, StepStatus>` | ✓ | 四子阶段状态 |
| `collapsed` | `boolean` | 可选 | 是否折叠，默认 `false` |
| `onToggleCollapse` | `() => void` | 可选 | 展开/收起回调 |

### 8.2 展开视图（`collapsed = false`）

从上到下展示三个主步骤卡片，每个卡片包含：
- 彩色图标（每个步骤有独立配色，running 时呼吸脉冲）
- 标题 + 进度徽标（`已完成 / 生成中 / 待开始`）
- 副文本描述（running 时展示 shimmer 动画）
- 步骤之间用竖线连接（完成后变绿色）

当 `sixstep` 阶段进入 running 或 done，在其卡片内部展开四个子阶段列表（`SUB_STEPS`），每个子阶段包含：
- 彩色图标（与流程图对应色）
- 标题 + 状态图标
- 时间线左侧的节点圆点 + 连接竖线

右上角收起按钮（`ChevronLeft`）触发 `onToggleCollapse`。

### 8.3 折叠视图（`collapsed = true`）

渲染轻量的 `CollapsedView` 子组件：
- 宽度由父容器通过 `w-14` 控制（56px），有 `transition-all duration-300` 过渡动画
- 顶部 `ChevronRight` 按钮用于展开
- 竖向排列三个主步骤彩色图标 + 状态圆点
- 若 `sixstep` 已解锁，在其下方额外展示四个小尺寸子阶段图标（`w-7 h-7`）
- 所有元素均有 `title` 属性，鼠标悬停显示步骤名称

### 8.4 配色方案

步骤颜色定义在 `MAIN_STEPS` 和 `SUB_STEPS` 数组的 `color` 字段中：

| 步骤 | 深色 | 浅色 |
|------|------|------|
| 信息准备 | sky-300 / sky-500 | sky-600 / sky-50 |
| 6步法推演 | violet-300 / violet-500 | violet-600 / violet-50 |
| 最终结果 | emerald-300 / emerald-500 | emerald-600 / emerald-50 |
| 目的 | violet-300 | orange |
| 行为体 | cyan-300 | red |
| 预期行为/驱动 | emerald-300 | emerald |
| 叙事 | amber-300 | amber |

---

## 九、对话列表（`SixStepConversation.tsx`）

### 9.1 Props

| Prop | 类型 | 说明 |
|------|------|------|
| `messages` | `SixStepMessage[]` | 全部消息 |
| `isGenerating` | `boolean` | 是否正在生成 |
| `activeMessageId` | `string \| null` | 当前流式聚焦的助手消息 id |
| `expertHandlers` | 可选对象 | `onSelectExpert` / `onRefetchExpert` / `onCreateExpert` / `onConfirmExpert` |

### 9.2 消息渲染策略

每条消息根据 `role` 字段分叉：

- `role === 'user'` → 渲染 `UserMessage`：右对齐气泡 + 用户头像
- `role === 'assistant'` → 渲染 `AssistantMessage`：左对齐 + 机器人头像（生成中时呼吸脉冲 + 星光图标）

消息列表容器 `ref` 监听内容变化，每次 `messages` 或 `isGenerating` 变化后自动滚动到底部。

### 9.3 助手消息 `AssistantMessage`

内部读取 `message.stages` 和 `message.mainStepStatus`、`message.subStepStatus`，根据是否存在各阶段数据来条件渲染对应的阶段块。底部（及部分分支末尾）挂载 **`StreamErrorNotice`**，展示 **`message.errors`**（来自 SSE `error_log` 等）。

助手消息结构示意：

```
AssistantMessage
│
├─ 信息准备中（仅当 info=running 且无任何 stage）→ shimmer 提示
│
├─ PurposeStage     (当 stages.purpose 存在时)
│   ├─ InlineCollapsible (以 StageHeader 为标题)
│   │   ├─ ThinkingBlock (思考过程)
│   │   └─ InlineCollapsible (目的卡片列表)
│   │       └─ PurposeCardItem × N
│
├─ ActorStage       (当 stages.actor 存在时)
│   ├─ InlineCollapsible
│   │   ├─ ThinkingBlock
│   │   └─ InlineCollapsible (行为体卡片列表)
│   │       └─ 按 purpose 分组
│   │           ├─ ParentGroupHeader (所属目的)
│   │           └─ ActorCardItem × N
│
├─ BehaviorStage    (当 stages.behavior 存在时)
│   ├─ InlineCollapsible
│   │   ├─ ThinkingBlock
│   │   └─ InlineCollapsible (预期行为/驱动因素卡片列表)
│   │       └─ 按 actor 分组
│   │           ├─ ParentGroupHeader (所属行为体)
│   │           └─ BehaviorCardItem × N（2列网格）
│
├─ NarrativeStage   (当 stages.narrative 存在时)
│   ├─ InlineCollapsible
│   │   ├─ ThinkingBlock
│   │   └─ InlineCollapsible (叙事卡片列表)
│   │       └─ 按 driver 分组
│   │           ├─ ParentGroupHeader (所属驱动因素)
│   │           └─ NarrativeCardItem × N
│
└─ FinalAnswer      (当 finalAnswer 存在或 final=running 时)
│
└─ StreamErrorNotice (当 message.errors 非空)
```

**分组计算**：`ActorStage`、`BehaviorStage`、`NarrativeStage` 都在内部用 `useMemo` 计算分组，将卡片按父 ID 聚合到 Map，再按父实体列表顺序输出。

---

## 十、卡片原子组件（`SixStepCards.tsx`）

此文件作为"组件库"，为对话列表提供所有可复用的卡片和容器组件。

### 10.1 `InlineCollapsible`

通用折叠面板，思考过程区块、卡片列表区块均复用此组件。

| Prop | 说明 |
|------|------|
| `title` | 标题区 ReactNode |
| `children` | 折叠内容 |
| `defaultOpen` | 默认展开状态（默认 `true`） |
| `variant` | `'default'`（标准边框背景）或 `'subtle'`（更淡）|

展开/收起使用 `grid-template-rows` 动画（`0fr → 1fr`），配合 `opacity` 过渡，无需 JS 计算高度。

### 10.2 各卡片组件

| 组件 | 卡片类型 | 布局特点 |
|------|---------|---------|
| `PurposeCardItem` | 目的 | 紫/橙渐变背景，索引徽标 + Target 图标 + 标题 + 理由 |
| `ActorCardItem` | 行为体 | 青/红渐变背景，UserCheck 图标 + 标题 + 内容 |
| `BehaviorCardItem` | 预期行为/驱动因素 | 翠绿渐变背景，上下两部分：TrendingUp 图标+预期行为 / Zap 图标+驱动因素 |
| `NarrativeCardItem` | 叙事 | 琥珀渐变背景，ScrollText 图标 + 标题 + 理由 |

所有卡片均有 `.sixstep-fade-up` 进入动画，`hover` 时边框加深。

### 10.3 `ParentGroupHeader`

显示某类卡片所属父实体名称的标签行，用于行为体、预期行为/驱动、叙事列表的分组标题。

| Prop | 说明 |
|------|------|
| `label` | 关系说明（如"所属目的"） |
| `parentTitle` | 父实体名称 |
| `count` | 该组卡片数量 |
| `variant` | `'actor' \| 'behavior' \| 'narrative'`，决定图标和配色 |

### 10.4 `ThinkingBlock`

展示思考过程文本的区块，`loading` 为 `true` 时标题行展示 "生成中" shimmer 文字。

### 10.5 `StageHeader`

折叠面板标题，包含阶段图标、阶段标题、卡片数量徽标、状态徽标（已完成/生成中）。`loading = true` 时图标呼吸脉冲，副文本展示 shimmer 动画。

---

## 十一、流程图沙箱（`SixStepFlowSandbox.tsx`）

### 11.1 Props

| Prop | 类型 | 说明 |
|------|------|------|
| `message` | `SixStepMessage \| undefined` | 活跃助手消息，用于提取各阶段卡片数据 |
| `width` | `number` | 当前沙箱宽度（px），由主页面拖拽控制 |
| `onResizeStart` | `(e: React.MouseEvent) => void` | 拖拽手柄 mousedown 回调 |
| `onClose` | `() => void` | 关闭沙箱回调 |
| `onOpenFullscreen` | `() => void` | 打开全屏回调 |

### 11.2 布局参数（`COMPACT_OPTIONS`）

沙箱使用缩小版布局，节点小于全屏版：

```typescript
const COMPACT_OPTIONS = {
  nodeWidth: 120, nodeHeight: 60,
  levelGap: 80,   nodeGap: 24,
  paddingX: 32,   paddingY: 28,
};
```

### 11.3 简化节点（`CompactNode`）

每个节点只显示**彩色图标 + 阶段缩写**（`VARIANT_ABBREV`）：

| 层级 | 缩写 |
|------|------|
| 智能体（或根标题改为已选专家名时仍为 variant `agent`） | AI |
| 目的 | md |
| 行为体 | xwt |
| 预期行为 | yqxw |
| 驱动因素 | qdys |
| 叙事 | xs |

底部固定图例说明对应关系。

### 11.4 新增节点动画

通过 `seenIdsRef`（`Set<string>`）记录已渲染过的节点 ID。每次 `layout.nodes` 变化时，找出新增的 ID，将其加入 `appearingIds` 状态，700ms 后自动移除。

`CompactNode` 接收 `appearing` prop，为 `true` 时：
1. 为 `<g>` 添加 `.sixstep-node-pop` CSS 类（scale 弹出）
2. 在节点中心绘制一个 SVG `<circle>` 并添加 `.sixstep-ring-burst` CSS 类（扩散光环）

### 11.5 交互能力

**平移（Pan）**：
- `mousedown` 记录起始坐标和初始 `tx/ty` 到 `panStart.current`
- 通过 `useEffect` 监听 `isPanning` 状态，动态注册/注销 `window` 的 `mousemove` 和 `mouseup`
- `mousemove` 计算偏移量 `(e.clientX - startX, e.clientY - startY)` 叠加到初始平移值

**缩放（Zoom）**：
- 通过 `useEffect` 向 `containerRef` 注册原生 `wheel` 事件（`{ passive: false }`），确保 `e.preventDefault()` 生效，不触发浏览器页面缩放
- 以鼠标位置为缩放中心：`nextTx = mx - (mx - prev.tx) * (nextScale / prev.scale)`
- 缩放范围：0.3x ~ 2.5x

**工具栏**：
| 按钮 | 功能 |
|------|------|
| `+` | 按 1.2 倍放大 |
| `-` | 按 1.2 倍缩小 |
| ↺ | 恢复 1:1（translate 0,0 scale 1） |
| ⊕ | 定位画布中央（保持当前缩放比，调整平移使图形居中） |
| ⤢ | 触发 `onOpenFullscreen` |

首次有内容时自动执行 `fitToView`（等比缩放 + 居中），由 `fitAppliedRef` 控制只执行一次。

### 11.6 连线说明

SVG 中的 `<defs>` 为每种边类型各定义一个箭头 marker（id 加 `sixstep-sandbox-` 前缀，与全屏版 marker 不冲突）。当 `activePair === edge.pair` 时，该边添加 `.sixstep-ant-line` CSS 类展示蚂蚁线动画。

### 11.7 调整宽度

左侧有一个 `position: absolute` 的 `.sixstep-resize-handle` 竖线拖拽条，`mousedown` 触发 `onResizeStart`（由主页面处理具体逻辑）。

---

## 十二、全屏流程图视图（`SixStepFlowFullscreen.tsx`）

### 12.1 Props

| Prop | 类型 | 说明 |
|------|------|------|
| `message` | `SixStepMessage \| undefined` | 与沙箱相同的活跃助手消息 |
| `onClose` | `() => void` | 关闭全屏回调 |

### 12.2 与沙箱的区别

| 特性 | 沙箱 | 全屏 |
|------|------|------|
| 布局参数 | 紧凑（节点 120×60） | 标准（节点 200×84） |
| 节点内容 | 缩写 + 图标 | 完整标题 + 详情 + 图标 |
| 节点出现动画 | 有（pop + ring-burst） | 无 |
| 子树收起/展开 | 无 | 有（点击**有子节点**的父节点；右下角「-」收起 / 「+」展开；画布左下角有操作提示） |
| 缩略图 | 无 | 有（右下角；仅绘制当前可见节点） |
| 下载 | 无 | 有（导出 SVG） |
| Esc 关闭 | 无 | 有 |
| 层级 | flex 子元素 | `fixed inset-0 z-50`（全视口遮罩） |
| 缩放范围 | 0.3x ~ 2.5x | 0.2x ~ 3x |

### 12.3 详细节点（`DetailNode`）

使用 `foreignObject` 嵌入 HTML，展示：
- 彩色图标包裹 + 大写类型标签（`VARIANT_LABEL`）
- 节点标题（`line-clamp-1`）
- 详情内容（`line-clamp-2`）

深色/浅色主题的渐变背景、图标颜色均通过 `VARIANT_TOKEN` 查表获取。

**收起子树**：当 `flowLayout` 中节点带 **`children`** 时，卡片右上角显示 **`+` / `-`**，点击节点（或该角标）切换 **`collapsedNodeIds`**：自该节点向下的后代节点与相关边不再纳入 **`targetVisibleNodeSet`**，并以约 **240ms** 的透明度过渡（进入/离开集合合并渲染，避免闪烁）。重新生成布局时会剔除已不存在的节点 id，避免残留收起状态。根节点若被选为专家展示，仍可按树结构收起其下子链。

### 12.4 缩略图（`Minimap`）

固定 220×150px，渲染在右下角。

内部逻辑：
1. 计算整体布局与 minimap 尺寸的缩放比 `ratio = Math.min((W-10)/layoutW, (H-10)/layoutH)`
2. 按 `ratio` 缩小绘制每个节点矩形（使用 `MINIMAP_VARIANT_FILL` 颜色，无文字）
3. 根据当前 `transform`（`tx, ty, scale`）和视口尺寸，计算可见区域在世界坐标的矩形，再乘 `ratio` 映射到 minimap 坐标系，绘制蓝色描边矩形（`.sixstep-minimap-rect`）
4. 点击 minimap：将点击的 minimap 坐标逆映射到世界坐标，调用 `onJump` 将视口移动到以该点为中心

### 12.5 SVG 下载

点击下载按钮时：
1. 克隆 `svgRef.current`（当前全屏 SVG 元素）
2. 设置 `width/height` 为实际布局尺寸，移除 transform
3. 用 `XMLSerializer` 序列化为字符串
4. 创建 `Blob` 和临时 `<a>` 标签，触发下载
5. 文件名格式：`6步法推演-YYYY-MM-DD-HH-mm-ss.svg`

> ⚠️ 注意：由于节点内容在 `foreignObject` 中使用 HTML + CSS 类名，下载的 SVG 打开时若外部查看器不支持 CSS，样式会丢失。可在未来改为纯 SVG 文本节点渲染以提升兼容性。

---

## 十三、整体数据流图

```
用户输入（回车）
    │
    ▼
SixStepChatPage.handleSend()
    │
    ├─► 当前会话追加 UserMessage + 初始 AssistantMessage
    │
    └─► runIntentOrchestrateStream(assistant, { onUpdate, onComplete }, IntentOrchestrateRequest)
            │
            │  readSSE('/api/orchestrate/stream', body)
            │
            │  intent / expert_* / clarify / resume / rerun / change_steps / edit_apply
            │  start / step_* / flow / done / delta（追问或 markdown）
            │  每次 onUpdate → 更新会话中该 assistant 的 SixStepMessage
            │
            ▼  React re-render
            │
            ├─► SixStepProgressHorizontal（liveMainStatus / liveSubStatus）
            ├─► SixStepConversation（messages、expertHandlers、intent/clarify 等）
            ├─► SixStepFlowSandbox / Fullscreen（stages → buildLayout）
            └─► persistConversation（SQLite）
```

---

## 十四、路由注册

**`src/App.tsx`**：
```tsx
// 路由定义
<Route path="sixstep-chat" element={<SixStepChatPage />} />
<Route path="/observability" element={<ObservabilityPage />} />

// 导航路径映射（handleNavigate 函数）
else if ([..., 'sixstep-chat'].includes(page)) {
  path = `/qa-center/${page}`;
}
```

**可观测性页面**（调用耗时 / 错误日志筛选）：全站路由 **`/observability`**，侧栏顶级「可观测性」，对接后端 **`GET /api/observability/calls`**、**`/errors`**、**`/options`** 等（详见 `backend/doc.md`）。与 6bf 页面独立，不在 `/qa-center` 前缀下。

**`src/components/Sidebar.tsx`**：
```tsx
// 菜单配置（问答中心 children）
{ id: 'sixstep-chat', label: '6bf', icon: Workflow }

// qaPages 集合（控制问答中心父菜单高亮）
const qaPages = new Set([..., 'sixstep-chat']);
```

---

## 十五、流式错误与 `error_log`（`api.ts`）

编排 SSE 除 **`error`** 外，可能下发 **`error_log`**（步骤失败摘要、skill 降级等）。`runIntentOrchestrateStream` 将其归一为 **`StreamErrorItem`** 并 **`push` 到 `message.errors`**；网络异常也会写入类似结构。后端在可执行 **skill 失败已跳过**时，**`message` 文案**可能附带 **异常原因前若干字符**（与 `backend/app/mcp/base.py` 截断策略一致），便于在气泡内区分超时与其它错误。

**`StreamErrorNotice`**：仅在对应助手气泡内展示，支持折叠展开、错误/警告计数摘要；不参与 `showAnalysisContent` 隐藏逻辑（专家阶段亦可显示）。

---


## 十六、扩展指南

### 接入编排与意图流

1. 主入口为 **`runIntentOrchestrateStream`**（`api.ts`），与后端 **`/api/orchestrate/stream`** 事件一一对应；扩展新意图时通常同时改 **`backend/app/intent/detector.py`** 与 **`runIntentOrchestrateStream`** 的分支解析。
   - 当前除 `continue_analysis` 外，还支持 `rerun_from_step`、`revise_input_continue`、`change_steps_continue`、`edit_stage_continue` 分支。
2. 保持 **`onUpdate(SixStepMessage)`** 契约：`SixStepChatPage` 只需合并助手消息字段。
3. 纯编排、无意图分支的调试可继续用 **`runSixStepDeduction`**（同文件内，仅 `start` / `step_*` / `flow` / `done`）。

详见 **`INTENT_INTEGRATION.md`** 与仓库 **`docs/xvqiu.md`**。

### 某子步（如行为体、叙事）体感很慢时

前端 **`step_end`** 事件里会带上该步的 **`duration_ms`**（整步总耗时），便于在 UI 或调试时对比各步。

更细拆分（skill 耗时 vs 拼 prompt 扩展 vs LLM）在**后端**完成：每次 `POST /api/agents/{key}/invoke` 及编排内对 `MCPAgent.invoke` 的调用，服务端会打 **`mcp_timing`** / **`mcp_skill_timing`** 日志（见 **`backend/doc.md`**「MCP 调用接口」与 **`backend/DEVELOPMENT.md`** §5.2）。排查时在运行 `python -m app.main` 的终端查看即可；无需改前端请求体。

### 替换流程图引擎（如 G6 / React Flow）

仅需替换 `SixStepFlowSandbox.tsx` 和 `SixStepFlowFullscreen.tsx` 中的 SVG 渲染部分：
- `buildLayout()` 的 `LayoutNode` 数组可直接转换为 G6 节点
- `LayoutEdge` 数组可直接转换为 G6 边
- `CURRENT_PAIR_BY_STAGE` 和 `EDGE_COLOR` 仍适用

### 新增推演子阶段

1. 在 `types.ts` 的 `SubStepKey` 中新增键名
2. 在 `SixStepStages` 中新增对应 `*StageData` 字段
3. 在 `mockData.ts` 的 `runSixStepDeduction` 中新增生成逻辑（若仍需要离线演示）
4. 在 `SixStepConversation.tsx` 的 `AssistantMessage` 中新增阶段渲染块
5. 在 `SixStepProgress.tsx` / **`SixStepProgressHorizontal.tsx`** 的 `SUB_STEPS` 中新增步骤项
6. 若需要流程图新层级，在 `flowLayout.ts` 的 `buildLayout` 中新增节点构建逻辑