代码修改

2026-05-28 18:29:37 +08:00
1 parent ef1481be63
commit a4b7ab5e9d
@@ -0,0 +1,736 @@
+# 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）行为正确。
+