827 lines
39 KiB
Markdown
827 lines
39 KiB
Markdown
# 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` 中新增节点构建逻辑
|