# Agent 组件开发问答（Q&A）

> 目录范围：`src/components/agent`
>
> 涵盖文件：
> - `AgentExpertCenterPage.tsx`
> - `AgentExpertEditPage.tsx`
> - `AgentChatPage.tsx`
> - `SkillCreatorPage.tsx`
> - `SkillsWorkshop.tsx`
> - `SkillCreatorThreadSidebar.tsx`
> - `AgentConversationList.tsx`
> - `SkillCreatorConversationItem.tsx`
> - `ChatInputComposer.tsx`
> - `AgentChatPage.css`

---

## Q1：这个目录整体是干什么的？

**A：这是“专家 Agent + 技能工坊 + 技能创建对话”的前端 UI 组件集合。**

- `AgentExpertCenterPage`：专家列表入口（我的专家/发布专家）。
- `AgentExpertEditPage`：专家配置编辑页（左侧对话预览 + 右侧配置）。
- `AgentChatPage`：某个专家的真实聊天页（含线程、文件上传、流式回答）。
- `SkillsWorkshop`：技能资产中心（搜索/筛选/接入/发布/删除/编辑）。
- `SkillCreatorPage`：技能创建/改写专用对话页（支持文件树预览和保存弹窗）。
- `SkillCreatorThreadSidebar`：复用的会话侧边栏（获取线程、新建、删除、切换）。
- `AgentConversationList` + `SkillCreatorConversationItem`：统一消息列表与消息卡片渲染。
- `ChatInputComposer`：统一输入框（发送/停止/上传）。
- `AgentChatPage.css`：`AgentChatPage` 专用动画和滚动条样式。

---

## Q2：核心共享数据模型有哪些？

**A：对话层主要围绕 `ConversationMessage`。**

- 定义位置：`AgentConversationList.tsx`
- 字段：
  - `id`: 消息唯一标识。
  - `role`: `'user' | 'assistant'`
  - `content`: 文本内容（markdown 渲染）。
  - `steps`: 思考步骤列表（数据来自 `data-thinking-step`）。
  - `thinkings`: 推理内容列表（来自 `reasoning-*` 事件）。
  - `toolCalls`: 工具调用（输入输出）列表。

**A：文件树使用 `FileNode`。**

- 在 `AgentChatPage`、`SkillCreatorPage` 内部定义并使用。
- 字段：`name/path/type/size/extension/children`。

**A：线程侧边栏使用 `SkillCreatorThread`。**

- 定义位置：`SkillCreatorThreadSidebar.tsx`
- 字段：`id/title/archived/expert_agent_id/created_at/updated_at`。

---

## Q3：整个目录的“数据流主干”怎么走？

**A：可以看成 3 条主链路。**

### 1) 专家链路（Center -> Edit -> Chat）

1. `AgentExpertCenterPage` 拉专家列表（我的/发布）。
2. 点击“编辑”跳 `AgentExpertEditPage`，加载专家详情 + 工具 + 技能绑定状态。
3. 点击“进行对话”跳 `AgentChatPage`，加载该专家详情和对应会话消息。

### 2) 技能链路（Workshop -> SkillCreator）

1. `SkillsWorkshop` 拉技能列表（official/mine），本地映射成 UI `Skill`。
2. 新建技能：创建会话后跳 `SkillCreatorPage?id=threadId`。
3. AI 辅助编辑已有技能：先创建线程，再 copy skill 到线程，再跳转 `SkillCreatorPage`。

### 3) 对话链路（输入 -> SSE -> UI -> 持久化）

1. `ChatInputComposer` 触发 `onSend`。
2. 页面组件（`AgentChatPage` 或 `SkillCreatorPage`）执行 `handleSendMessage`。
3. 先写入用户消息 + assistant 占位消息。
4. 调流式接口读取 SSE：
   - `data-thinking-step` -> 更新 `steps`
   - `reasoning-start/delta/end` -> 更新 `thinkings`
   - `tool-input-available/tool-output-available` -> 更新 `toolCalls`
   - `text-delta` -> 追加 `content`
5. 完成后将 assistant 结果再次 POST 到消息接口持久化。

---

## Q4：`AgentExpertCenterPage` 组件是干什么的？

**A：专家资产“总览入口”，负责展示列表和基础操作入口。**

### 组件职责

- 展示“我的专家”和“发布专家”两种视图。
- 打开专家详情弹窗（支持发布状态切换）。
- 提供“编辑”和“进行对话”跳转入口。

### 数据来源与接口

- 列表查询：
  - `POST /api/v1/expert-agents/list`（按 `is_draft`）
  - 我的专家场景还会额外 `GET /api/v1/expert-agents` 做合并去重。
- 状态切换：
  - `PATCH /api/v1/expert-agents/{id}`（更新 `is_draft`）

### 数据流

- `activeTab` 改变 -> `fetchExpertList` 触发 -> 更新 `agentList`。
- `agentList` -> `cards(useMemo)` -> 渲染卡片。
- 卡片按钮：
  - 编辑 -> `navigate('/qa-center/agent-expert-edit?id=...')`
  - 对话 -> `navigate('/qa-center/agent-chat?id=...')`

### 维护注意

- “创建专家”按钮目前是 UI 壳子，未接创建接口。
- “删除”按钮当前仅 `console.log`，未接真实删除逻辑。

---

## Q5：`AgentExpertEditPage` 组件是干什么的？

**A：专家配置编辑工作台，同时内置一个“测试对话区”。**

### 组件职责

- 左侧：和该专家进行流式对话（非真实聊天线程，使用 no_real 线程）。
- 右侧：编辑专家基础配置（名称、模型、描述、系统提示词）。
- 管理工具绑定、技能绑定（弹窗操作）。

### 关键状态

- 对话相关：`messages/inputValue/threadId/isStreaming`
- 配置相关：`formValues`
- 工具相关：`toolOptions/selectedTools/pendingTools/boundToolIdMap`
- 技能相关：`skillOptions/selectedSkills/boundSkillMap/skillKeyword`

### 主要接口

- 专家详情：`GET /api/v1/expert-agents/{agentId}`
- 保存专家：`PUT /api/v1/expert-agents/{agentId}`
- 绑定工具：
  - 查询：`GET /api/v1/expert-agents/{agentId}/tools`
  - 添加：`POST /api/v1/expert-agents/{agentId}/tools`
  - 删除：`DELETE /api/v1/expert-agents/{agentId}/tools/{toolId}`
- 绑定技能：
  - 查询：`GET /api/v1/expert-agents/{agentId}/skills`
  - 添加：`POST /api/v1/expert-agents/{agentId}/skills`
  - 删除：`DELETE /api/v1/expert-agents/{agentId}/skills/{skillId}`
- 测试对话：
  - 线程：`GET /api/v1/expert-agent-chat/threads/no_real/{agentId}`
  - 用户消息：`POST /api/v1/expert-agent-chat/messages`
  - SSE：`POST /api/v1/expert-agent-chat/run/stream/help_expert`

### 数据流（对话）

- 用户发送 -> append user msg -> 保证 threadId -> 保存用户消息 -> append assistant 占位 -> SSE 增量更新。

### 维护注意

- 右侧 `preview` 区底部 `ChatInputComposer` 是只读展示，不参与真实请求。
- 工具与技能弹窗是“前端状态 + 后端同步”双层状态，调试时优先检查 refresh 查询是否成功。

---

## Q6：`AgentChatPage` 组件是干什么的？

**A：专家“真实聊天页”，并带线程管理、文件上传和文件预览。**

### 组件职责

- 根据 URL `id` 读取专家详情。
- 管理当前线程（localStorage 持久化）。
- 获取历史消息并转换为统一消息结构。
- 流式发送消息并渲染思考过程。
- 管理会话文件（上传、树形结构、预览、侧栏缩放）。

### 关键状态

- 会话：`currentThreadId/messages/inputValue/isStreaming/isLoading`
- UI：`isThreadSidebarOpen/autoScrollEnabled/showScrollButton`
- 文件：`fileList/fileListThreadId/isFileSidebarOpen/expandedPaths/selectedFile/filePreview*`

### 主要接口

- 专家详情：`GET /api/v1/expert-agents/{agentId}`
- 会话消息：
  - 历史：`GET /api/v1/expert-agent-chat/threads/{id}/messages`
  - 保存用户：`POST /api/v1/expert-agent-chat/messages`
  - SSE：`POST /api/v1/expert-agent-chat/run/stream`
  - 保存助手：`POST /api/v1/expert-agent-chat/messages`
- 文件：
  - 列表：`GET /api/v1/expert-agent-chat/threads/{id}/files/all`
  - 上传：`POST /api/v1/expert-agent-chat/threads/{id}/files/upload`
  - 预览：`GET /api/v1/expert-agent-chat/threads/{id}/files/preview?path=...`

### 关键行为细节

- **发送即出现 assistant 占位**：点击发送后立即插入 assistant 空消息，保证用户立刻看到“连接中”态。
- **连接中显示规则**：由 `AgentConversationList` 判断“最后一条 assistant 且还没有任何生成内容”才显示连接状态。
- **失败回滚**：发送或流式失败时移除该 assistant 占位，避免残留空卡片。
- **停止流式**：`AbortController` 中断请求，并清理 loading 态字段。

### 维护注意

- `threadStorageKey` 与 `agentId` 强绑定，切换专家会切换独立 thread 记忆。
- `normalizeHistoryContent` 是历史消息兼容核心，后端 content 结构变更时先改这里。

---

## Q7：`SkillCreatorPage` 组件是干什么的？

**A：技能创建/重构专用对话页，结构上是 `AgentChatPage` 的“技能场景定制版”。**

### 组件职责

- 从 query/localStorage 同步当前线程 ID。
- 加载技能会话历史与会话文件。
- 走技能专属流式接口输出思考步骤/推理/tool call/文本。
- 提供“保存技能”弹窗（当前主要是 UI + 本地状态）。

### 与 `AgentChatPage` 的主要差异

- 线程 ID 同步到 URL（`useSearchParams`）。
- 有独立 `isConnecting` 状态，用于连接中阶段展示。
- 流式接口是：`POST /api/v1/expert-agent-chat/skills-agent`
- 页面内注入了 dot/shimmer 动画样式（供消息连接中态使用）。

### 主要接口

- 会话消息：`GET /threads/{id}/messages`
- 流式：`POST /skills-agent`
- 保存 assistant：`POST /messages`
- 文件：`GET all` / `POST upload` / `GET preview`

### 数据流

- 发消息 -> append 用户 + assistant 占位 -> `isConnecting=true` -> 收到首个流块后 `isConnecting=false` -> 增量刷新 assistant -> 持久化。

### 维护注意

- 保存技能按钮目前仅 `console.log` 输出技能名和描述，未接正式后端保存接口。

---

## Q8：`SkillsWorkshop` 组件是干什么的？

**A：技能资产管理页（发现、筛选、接入、发布、删除、进入编辑）。**

### 组件职责

- 拉取 `official` 与 `mine` 技能，映射成统一 UI 结构。
- 支持搜索、类型筛选、分类筛选。
- 支持官方技能接入到“我的技能”。
- 支持发布、删除、编辑（编辑弹窗支持 AI 编辑和上传覆盖）。
- 支持“新建技能体”：Agent 对话创建 / 上传文件创建。

### 主要接口

- 列表：`GET /api/v1/skills?type=official|mine`
- 发布：`POST /api/v1/expert-agents/skills/publish`
- 删除我的技能：`DELETE /api/v1/skills/mine/{skillId}`
- 上传覆盖：`PUT /api/v1/skills/{skillId}/upload`
- 接入官方技能：`POST /api/v1/skills/mine/add`
- 上传创建：`POST /api/v1/skills/upload`
- Agent 创建线程：`POST /api/v1/expert-agent-chat/threads`
- AI 编辑复制技能：`POST /threads/{threadId}/copy-skill/{skillId}`

### 数据流

- filter/search 改变 -> `useEffect` 重新拉取技能 -> 本地去重并缓存到 `skills`。
- 卡片编辑 -> `editingSkill` 打开弹窗 -> 选择 AI 编辑时创建线程后跳 `SkillCreatorPage`。

### 维护注意

- `inferCategory` 是关键词规则映射，新增技能类型时可优先扩展该规则。
- “进入”按钮目前使用 `skill.id` 跳 `skill-creator`，若后端语义改成 threadId 需调整。

---

## Q9：`SkillCreatorThreadSidebar` 组件是干什么的？

**A：会话线程管理的复用侧边栏。**

### 组件职责

- 打开时加载会话列表。
- 新建会话并自动选中。
- 删除会话并在当前会话被删时自动回退到其它会话。
- 支持线程过滤（如仅展示当前专家线程）。

### 输入输出（Props 视角）

- 输入：`authedFetch/currentThreadId/isOpen/isBusy/threadFilter/createThreadPayload...`
- 输出：
  - `onThreadSelect(threadId)`
  - `onClose()`

### 数据流

- `isOpen` 从 false -> true：触发 `refreshThreads`。
- 新建成功：更新本地列表并触发 `onThreadSelect`。
- 删除成功：本地移除；若删的是当前线程，自动选择 fallback。

### 维护注意

- `createThreadPayload` 是高复用扩展点，场景页可注入 `expert_agent_id/title` 等字段。

---

## Q10：`AgentConversationList` 组件是干什么的？

**A：统一遍历消息并决定“连接中状态”是否显示。**

### 核心逻辑

- 逐条渲染 `SkillCreatorConversationItem`。
- 只在以下条件满足时给最后一条 assistant 传 `isConnecting=true`：
  - 页面处于连接/流式阶段；
  - 当前消息是最后一条 assistant；
  - 且还没有任何实际生成内容（`content/steps/thinkings/toolCalls` 都为空）。

### 价值

- 将“连接中占位显示时机”从页面组件抽离，统一控制，减少重复判断代码。

---

## Q11：`SkillCreatorConversationItem` 组件是干什么的？

**A：单条消息卡片渲染器（用户消息 + 助手多面板消息）。**

### 渲染结构

- 用户消息：右侧气泡 + user avatar。
- 助手消息：左侧 avatar + 多段内容：
  - `StepsSummary`
  - `ThinkingPanel[]`
  - `ToolCallPanel[]`
  - 连接中动画文案（`正在连接技能服务...`）
  - Markdown 正文

### 数据来源

- 完全由父级传入 `message` 和 `isConnecting` 控制，不直接请求后端。

### 维护注意

- 此组件是所有对话页的统一呈现层；若改动 message schema，要同步更新这里的各面板。

---

## Q12：`ChatInputComposer` 组件是干什么的？

**A：通用输入组件，封装输入、发送/停止、上传文件。**

### 输入输出（Props）

- 输入：`value/disabled/readOnly/isSending/isDarkMode/showUpload/placeholder...`
- 回调：
  - `onChange(value)`
  - `onSend()`
  - `onStop()`
  - `onUploadFile(file)`

### 关键交互

- Enter（非 Shift）触发发送（前提：`submitEnabled` 且非 `isSending`）。
- 发送按钮在发送中切换为停止按钮（`onClick={isSending ? onStop : onSend}`）。
- 文件上传通过隐藏 `input[type=file]` + 按钮触发。

### 维护注意

- 当前实现里文本框只受 `disabled` 控制，不再因为 `isSending` 禁止输入。
- 上传按钮仍受 `disabled || !onUploadFile` 控制。

---

## Q13：`AgentChatPage.css` 主要做了什么？

**A：提供 `AgentChatPage` 的辅助样式。**

- `.agent-resizing`：拖拽文件侧栏时全局 cursor/user-select 控制。
- `.agent-file-tree-scroll` / `.agent-file-preview-scroll`：滚动条样式统一。
- `.agent-file-markdown-preview`：markdown 首尾边距和图片样式收敛。
- `.animate-breathing` 等动画类：预留呼吸动效。

---

## Q14：典型业务流程：发送一条消息时，数据如何传输？

**A：以 `AgentChatPage` 为例。**

1. 用户在 `ChatInputComposer` 输入后点击发送。
2. `handleSendMessage` 校验 `text/threadId/isStreaming`。
3. 立即写入：
   - user message
   - assistant 占位 message（空内容）
4. 调 `POST /messages` 落用户消息。
5. 调 `POST /run/stream` 开始 SSE。
6. 每个 SSE event 增量更新 assistant message：
   - step -> `steps`
   - reasoning -> `thinkings`
   - tool -> `toolCalls`
   - text -> `content`
7. 流结束后将聚合结果组装成 `persistedContent`，再 `POST /messages` 落库。
8. 刷新文件列表（对可能新增输出文件做同步）。

---

## Q15：典型业务流程：从技能工坊进入技能创建页，数据如何传输？

**A：两种入口。**

### 入口 A：新建技能（Agent 构建）

1. `SkillsWorkshop.handleCreateSkillByAgent` 创建线程。
2. 将 `threadId` 写入 localStorage。
3. 跳转 `navigate('/qa-center/skill-creator?id=threadId')`。
4. `SkillCreatorPage` 用 query/localStorage 同步 `currentThreadId`，然后拉消息和文件。

### 入口 B：AI 辅助编辑已有技能

1. 创建线程。
2. `POST /threads/{threadId}/copy-skill/{skillId}` 把技能内容复制到线程工作区。
3. 跳转 SkillCreator 页面，后续在线程中对话编辑。

---

## Q16：如果要新增一个“对话页”，建议复用哪些组件？

**A：建议最小复用组合如下。**

- 消息列表：`AgentConversationList`
- 单消息卡片：`SkillCreatorConversationItem`（自动包含 steps/thinking/tool 等面板）
- 输入框：`ChatInputComposer`
- 线程侧边栏：`SkillCreatorThreadSidebar`

**页面层只负责：**

- 状态管理（`messages/input/isStreaming/currentThreadId`）
- 接口请求（历史 + SSE + 持久化）
- 事件映射（把后端事件转为 `ConversationMessage` 结构）

---

## Q17：维护时最容易踩坑的点有哪些？

**A：建议优先关注这 8 个点。**

1. **SSE 事件兼容性**：后端 event type 或字段名变化会直接导致 UI 不更新。
2. **历史内容兼容**：`normalizeHistoryContent` 没跟上 content schema 会出现历史消息空白。
3. **线程切换中断**：切换线程时要记得 abort 流并清状态，避免串流到新线程。
4. **占位消息回收**：发送失败/流失败需移除 assistant 占位，避免残留空卡片。
5. **threadId 语义一致性**：某些页面参数传 skillId/agentId，需避免误当 threadId 使用。
6. **工具/技能绑定状态双源**：本地状态和后端状态不同步时，优先以 refresh 查询结果为准。
7. **上传入口 accept 限制**：上传文件类型修改时要同步后端校验和 UI 提示。
8. **深色主题样式**：该目录深色/浅色分支很多，改样式需双主题回归。

---

## Q18：后续文档扩展建议

**A：当前文档适合开发入门，下一步可补充“接口契约版”。**

- 补完整 SSE event JSON 示例（每种事件一例）。
- 增加错误码到 UI 提示映射表。
- 补一份“页面状态机图”（Idle / Connecting / Streaming / Stopped / Error）。
- 给每个页面补“可测点清单”（单测/联调/回归）。

---

## Q19：能否给一份可联调的“接口契约附录”？

**A：可以，以下按模块整理。**

### 1) 专家模块（Expert）

- 查询专家列表  
  - `POST /api/v1/expert-agents/list`
  - 请求体：
    - `is_draft: boolean`
  - 响应（数组项）：
    - `id/name/avatar_url/description/model_name/is_draft/user_id/created_at`

- 查询专家详情  
  - `GET /api/v1/expert-agents/{agentId}`
  - 响应关键字段：
    - `id/name/description/system_prompt/model_name`

- 更新专家配置  
  - `PUT /api/v1/expert-agents/{agentId}`
  - 请求体关键字段：
    - `name`
    - `description`
    - `system_prompt`
    - `model_name`
    - `avatar_url`（当前传 `null`）

- 切换草稿/发布状态  
  - `PATCH /api/v1/expert-agents/{agentId}`
  - 请求体：
    - `is_draft: boolean`

### 2) 线程与消息模块（Chat Thread + Message）

- 查询线程列表  
  - `GET /api/v1/expert-agent-chat/threads`
  - 响应：
    - `threads: SkillCreatorThread[]`
    - `archived_threads: SkillCreatorThread[]`

- 新建线程  
  - `POST /api/v1/expert-agent-chat/threads`
  - 请求体常见字段：
    - `title`
    - `archived`
    - `is_real_chat`
    - `expert_agent_id`（专家聊天场景）

- 删除线程  
  - `DELETE /api/v1/expert-agent-chat/threads/{threadId}`

- 查询线程消息历史  
  - `GET /api/v1/expert-agent-chat/threads/{threadId}/messages`
  - 响应消息项关键字段：
    - `id/thread_id/role/content/created_at`

- 保存消息（用户或助手）  
  - `POST /api/v1/expert-agent-chat/messages`
  - 请求体（用户消息）：
    - `thread_id`
    - `role: "user"`
    - `content: { type: "text", text: string }`
  - 请求体（助手消息）：
    - `thread_id`
    - `role: "assistant"`
    - `content: persistedContent[]`

### 3) 流式回复模块（SSE）

- 专家聊天流式  
  - `POST /api/v1/expert-agent-chat/run/stream`
  - 请求体关键字段：
    - `chat_id`
    - `expert_agent_id`
    - `user_query`
    - `messages`

- 专家编辑页测试流式  
  - `POST /api/v1/expert-agent-chat/run/stream/help_expert`

- 技能创建流式  
  - `POST /api/v1/expert-agent-chat/skills-agent`
  - 请求体关键字段：
    - `chat_id`
    - `user_query`

### 4) 文件模块（线程文件）

- 查询线程文件树  
  - `GET /api/v1/expert-agent-chat/threads/{threadId}/files/all`

- 上传文件  
  - `POST /api/v1/expert-agent-chat/threads/{threadId}/files/upload`
  - form-data:
    - `file`

- 文件预览  
  - `GET /api/v1/expert-agent-chat/threads/{threadId}/files/preview?path=...`
  - 兼容响应：
    - 文本
    - JSON 字符串
    - JSON 对象中的 `content`

### 5) 技能模块（Skills）

- 查询技能列表  
  - `GET /api/v1/skills?type=official|mine|all&keyword=&page=1&page_size=100`

- 发布技能  
  - `POST /api/v1/expert-agents/skills/publish`
  - 请求体：
    - `skill_id`

- 添加官方技能到我的技能  
  - `POST /api/v1/skills/mine/add`
  - 请求体：
    - `official_skill_id`

- 删除我的技能  
  - `DELETE /api/v1/skills/mine/{skillId}`

- 上传技能文件创建  
  - `POST /api/v1/skills/upload`

- 上传覆盖已有技能  
  - `PUT /api/v1/skills/{skillId}/upload`

### 6) 专家绑定工具/技能

- 工具  
  - 查询：`GET /api/v1/expert-agents/{agentId}/tools`
  - 绑定：`POST /api/v1/expert-agents/{agentId}/tools`（`tool_name`）
  - 解绑：`DELETE /api/v1/expert-agents/{agentId}/tools/{toolId}`

- 技能  
  - 查询：`GET /api/v1/expert-agents/{agentId}/skills`
  - 绑定：`POST /api/v1/expert-agents/{agentId}/skills`（`skill_id`）
  - 解绑：`DELETE /api/v1/expert-agents/{agentId}/skills/{skillId}`

---

## Q20：SSE 事件规范可以补全吗？

**A：可以，以下是前端当前实现依赖的事件集合。**

### 1) 事件封包格式

- 每行以 `data: ` 开头
- 正文为 JSON 字符串
- 结束标记：`data: [DONE]`

### 2) 前端识别的事件类型

- `data-thinking-step`
  - 用途：更新执行步骤面板
  - 关键字段：
    - `data.id`
    - `data.title`
    - `data.status`（`completed` 或其它）
    - `data.items[]`

- `reasoning-start`
  - 用途：开始一段思考
  - 行为：创建新的 thinking 段，记录开始时间

- `reasoning-delta`
  - 用途：思考内容增量
  - 关键字段：
    - `delta`

- `reasoning-end`
  - 用途：结束当前思考段
  - 行为：计算该段耗时并写入 `duration`

- `tool-input-available`
  - 用途：记录工具调用入参
  - 关键字段：
    - `toolCallId`
    - `toolName`
    - `input`

- `tool-output-available`
  - 用途：记录工具调用输出
  - 关键字段：
    - `toolCallId`
    - `output`

- `text-delta`
  - 用途：助手正文 token 增量
  - 关键字段：
    - `delta`

### 3) 推荐后端保证

- 同一次回复里的 `toolCallId` 全局唯一。
- `reasoning-start` 与 `reasoning-end` 成对（允许无 `delta`）。
- `data-thinking-step` 同一个 `id` 可重复更新状态。
- `text-delta` 在结束前允许为空片段，但尽量减少空片段。

### 4) 前端容错策略（已实现）

- JSON parse 失败：跳过该行，不中断整流。
- 未识别 event.type：忽略。
- `output` 非字符串：尝试 `result` 字段，否则 `JSON.stringify`。
- `AbortError`：按“用户主动停止”处理，不弹致命错误。

---

## Q21：可以给一份页面级测试清单吗？

**A：可以，以下清单按页面拆分，适合联调和回归。**

### A. `AgentChatPage` 测试清单

- 打开页面后，能加载专家信息（名称、描述）。
- 未选线程时，空态正确显示；选中线程后历史消息正确渲染。
- 点击发送后立即出现 assistant 占位卡片，显示连接中状态。
- 首个有效流式事件到达后，连接中占位消失，转为正常内容增量渲染。
- 发送失败/流失败时，assistant 占位会被回收，不留空白卡片。
- 点击停止后，流式中断，按钮状态恢复，后续不再追加内容。
- 上传文件后文件树刷新；文件预览支持 text/json 两类返回。
- 切换线程时会中断当前流，且不会把旧线程流内容写到新线程。

### B. `SkillCreatorPage` 测试清单

- URL `id` 与 localStorage 线程 ID 同步正确。
- 新线程空态和快捷提示按钮显示正常。
- 发送后 `isConnecting=true`，收到首包后 `isConnecting=false`。
- steps/thinking/tool/text 四类流式内容都能正确出现。
- 线程切换、停止流、文件上传/预览路径行为与 `AgentChatPage` 一致。
- 保存技能弹窗开关正常（当前为 UI 行为）。

### C. `AgentExpertEditPage` 测试清单

- 进入页面后基础信息（name/model/description/system_prompt）能回填。
- 保存专家配置后接口成功，按钮 loading 状态恢复。
- 工具弹窗：勾选新增 -> 确认添加 -> 列表刷新一致。
- 技能弹窗：绑定/解绑/一键绑定后状态与后端一致。
- 左侧测试对话能正常流式返回，滚动与发送状态正确。

### D. `SkillsWorkshop` 测试清单

- `all`/`mine` 切换结果正确，搜索词可生效。
- 分类筛选（writing/analysis/decision/validation/workflow）正确过滤。
- 官方技能“+”接入后卡片状态转“已接入”。
- 我的技能菜单中的发布/删除操作正确执行。
- 编辑弹窗中 AI 编辑路径可成功创建线程并跳转 SkillCreator。
- 上传创建、上传覆盖两条路径成功后状态正确恢复（含 input 清空）。

### E. `AgentExpertCenterPage` 测试清单

- mine/published 标签切换后列表正确变化。
- mine 模式会按当前用户过滤，且与全量接口合并去重后正确展示。
- 详情弹窗中的发布开关可切换并刷新列表。
- 编辑、对话跳转路径参数正确。

### F. 主题与可用性回归

- 深色/浅色主题下对话气泡、按钮、边框、hover 都可读。
- 长会话场景滚动性能可接受，自动滚动按钮行为符合预期。
- 键盘发送（Enter）与换行（Shift+Enter）行为正确。