18 KiB
开发文档 · parallel-agents-vue
面向维护 / 二次开发这个前端的同学。讲清楚:它是什么、架构与数据流、目录与各文件职责、 对接的后端契约、样式系统、以及常见扩展怎么改。使用 / 嵌入请看 07-使用说明.md。
1. 它是什么
一个独立、可嵌入的 Vue3 组件:输入「任务名称 + 简介」→ 并行调用宿主指定的多个智能体 →
深色消息列表(1:1 复刻圆桌 Step2:步骤条 / 协作卡片 / 席位状态条 / 点头像切换单显)→
支持保存 / 回显 / 重新分析。只对外暴露一个组件 ParallelAgentsPanel。
- 后端是同仓库的 DeerFlow 网关(
offline-backend-20260512/backend),本前端只消费它的几个 HTTP 接口。 - 并行编排在后端:前端发一条请求,后端扇出 N 个智能体、合并成一条 SSE回来;前端只解析这一条流。
2. 技术栈
| 方面 | 选型 |
|---|---|
| 框架 | Vue 3(<script setup> + Composition API) |
| 构建 | Vite 6(dev app + build:lib 组件库双产物) |
| 语言 | TypeScript(strict + noUnusedLocals/Parameters) |
| 样式 | 零 CSS 框架:作用域 .pa-* token + 内置「最小工具类子集」(不依赖 Tailwind) |
| Markdown | markdown-it(打进库,宿主无需安装) |
| peer dep | vue ^3.4(宿主提供,库不打包 vue) |
3. 目录结构与各文件职责
实现全部收在一个自包含文件夹 src/parallel-agents/(内部相对路径引用、不依赖构建别名,
整个文件夹可直接拷给宿主用)。src/ 顶层只剩 demo 与库入口。
src/
├─ index.ts 库入口:从 ./parallel-agents 再导出 + install 插件
├─ main.ts / App.vue dev demo(仅本地调试用,不进库)
└─ parallel-agents/ ← 自包含组件文件夹(拷走即用)
├─ index.ts 文件夹入口:import 样式 + 导出组件/类型
├─ config.ts 配置:DEFAULT_BASE_URL / DEFAULT_MODEL / TOKEN_PATH
├─ types.ts 共享类型:Dialogue / SeatView / SeatStatus / DialogueStep /
│ ClarificationPayload / AgentInput / AgentResult / SavedTask / StreamEvent
├─ api.ts 后端访问层:鉴权(取 token+缓存+401 重登) / SSE 流 / 任务 CRUD / 模型列表
├─ useParallelRun.ts 运行编排(前端态核心):消费合并 SSE → 维护 dialogues/seats/busy;
│ start / cancel / hydrate(回显) / reset / rerunAgent(单席位重跑,可并发协助)
├─ avatar-constants.ts 头像配色 + getAvatarTypeFor(轮转)
├─ step-display.ts 步骤条:getStepDisplay(图标+中文文案) / getStepArgs(参数子节点)
├─ parallel-agents.css 作用域深色 token(--pa-*) + .pa-* 语义类 + Markdown 样式 + 工具类子集(无 Tailwind)
├─ ParallelAgentsPanel.vue 主组件:席位条/会话区 + 全部状态编排(表单/按钮在宿主侧)
├─ ParallelSeatStrip.vue 席位状态条(头像 + running/done/clarify/error 角标,点击切换单显)
├─ AutoScrollPane.vue 自动下滑滚动窗格:包住单席位消息,超高出滚动条 + 流式自动钉底 +
│ 用户滚动暂停 + 半透明「自动滚动」浮动按钮(每席位一实例,互不影响)
├─ MessageBubble.vue 单条气泡:头像/发言人/徽标/时间/步骤条/正文/光标/协作卡片
├─ MessageStepsCard.vue 步骤条(ChainOfThought 结构,1:1 对齐 Step2)
├─ StepIcon.vue 步骤图标(lucide 风格 inline SVG,按 IconKey)
├─ ClarificationCard.vue 协作 / 澄清卡片(1:1 对齐圆桌第一步 IntentClarificationCard)
├─ MarkdownContent.vue markdown-it 渲染
├─ Avatar.vue 机器人 / 真人 SVG 头像
└─ README.md 文件夹速用说明
4. 架构与数据流
一次「开始分析」的端到端链路:
用户输入(任务名+简介) ──onStart──> useParallelRun.start(cfg, {taskName, brief, agents, model})
│ 为每个 agent 建一个 Dialogue(流式气泡) + SeatView(席位)
▼
api.streamParallelAgents(cfg, body, handlers, signal)
│ POST {baseUrl}/api/parallel-agents/run/stream (Authorization: Bearer <token>)
▼
后端扇出:每个 agent 各跑一轮 LangGraph,合并成「一条带 agent_id 的 SSE」
▼ 逐条 StreamEvent(见 §5)
useParallelRun.handleEvent(ev) 按 agent_id 路由:
delta→气泡正文(rAF 节流) · step→步骤条 · agent_clarification→协作卡片
agent_done→收口 · agent_error→错误 · all_done→收尾
▼ 响应式 dialogues / seats 变化
组件渲染:ParallelSeatStrip + 当前选中席位的 MessageBubble(单显,点头像切换)
▼ run 结束
panel emit "completed"(AgentResult[]);可点「保存」(按 taskId upsert) / 「重新分析」(重跑)
关键不变量
- 主区单选显示一个席位的消息(
selected=[agentId],点头像切换);后台 N 个智能体仍并行执行。 - delta 用
requestAnimationFrame合并刷新,避免逐 token reflow。 bubbleByAgent: Map<agentId, bubbleId>把事件路由到对应气泡;hydrate/start 时重建。
5. 统一事件协议(前后端唯一契约)
后端 /run/stream 每条 data: 是一个 JSON(StreamEvent,定义在 types.ts):
| type | 字段 | 前端处理 |
|---|---|---|
agent_start |
agent_id |
该席位置 running |
delta |
agent_id, text |
追加正文(节流) |
step |
agent_id, key(=tool_calling:), label, args |
步骤条加一步(含完整 args) |
agent_clarification |
agent_id, content, question, clarification_type, clarification_context, options, allow_* |
设 dialogue.clarification → 卡片;席位置 clarify(待协助,非 done)。澄清卡片任何时候都可点(即便整批仍在跑),用户答完 → panel.onClarify → rerunAgent 重跑该席位 |
agent_done |
agent_id, content |
收口,正文以终态为准 |
agent_error |
agent_id, message |
该席位置 error |
all_done |
— | 全部结束 |
核心数据模型(types.ts):
Dialogue { id, agentId, sender, avatarType, content, time, confidence, streaming?, steps?, clarification? }DialogueStep { id, key, label, ts, args? }(key形如tool_calling:web_search)SeatView { agentId, name, avatarType, status: SeatStatus, bubbleId }SeatStatus = pending | running | done | clarify | error(clarify= 待用户协助,非完成)ClarificationPayload { question, clarificationType, context, options, allowCustom, allowMultiple }AgentResult { agent_id, name, content, status }(宿主读取用;status同SeatStatus)
改协议时:
types.ts的StreamEvent与后端parallel_agents.py的事件 dict 必须同步。
6. 组件树
ParallelAgentsPanel
├─ ParallelSeatStrip ── Avatar (席位条,点头像切换单显)
└─ AutoScrollPane (当前选中席位;限高滚动 + 流式自动下滑 + 浮动「自动滚动」按钮)
└─ MessageBubble
├─ Avatar
├─ MessageStepsCard ── StepIcon (步骤条;getStepDisplay/getStepArgs 翻译 key+args)
├─ MarkdownContent (markdown-it)
└─ ClarificationCard (msg.clarification 存在时;提交→panel.onClarify→rerunAgent)
自动下滑 / 高度自适应(
AutoScrollPane.vue):会话区只负责限高(min-h-0 flex-1 overflow-hidden), 真正的滚动与自动下滑下放到每个席位卡片内部的窗格 —— 父元素不够高时窗格内出现滚动条;模型流式输出时 用ResizeObserver监听内容增高并钉到底部;用户向上滚动(离开底部)即暂停自动下滑、滚回底部自动恢复; 暂停且内容可滚动时底部居中浮出半透明「自动滚动」按钮(.pa-autoscroll-btn),点击恢复并滚到底。 每个席位各一个实例(v-for :key=agentId),autoScroll / 滚动位置都在实例内,多智能体互不影响。 席位卡片靠.pa-rows-fill(grid-auto-rows: minmax(0,1fr))受限于会话区高度,从而内部滚动而非撑破容器。
ParallelAgentsPanel 的对外接口(详见 07-使用说明.md):
- props:
agents(必填) /username/baseUrl/token/getToken/taskId/model/dark - emits:
agent-completed(AgentReply)—— 单个智能体**真正完成(done)**时各触发一次;AgentReply = {agent_id, name, content}(智能体名称 + 模型返回结果,不含 status)。待用户协助(clarify)/ 出错(error)不触发。completed(AgentReply[])—— 所有智能体都完成(done/error、没有任何 clarify 在等用户)后,整批触发一次; 若有席位在等用户协助,本轮不发,待其答完重跑完成后再发。saved(SavedTask)/update:taskId(string)/update:taskName(string)/update:brief(string)
defineExpose:getResults()(返回AgentResult[],含 status) /getResult(id)/start()/reanalyze()/save()/cancel()/loadTask(id)
7. 鉴权
api.ts 的 token 解析优先级:token > getToken() > 缓存 > 用 username 取 token。
- 取 token:
POST {baseUrl}{TOKEN_PATH}(TOKEN_PATH=/api/parallel-agents/auth/token)—— 本面板 专用的「绕过常规登录」公共端点(内网部署限制了标准/login/username)。传{username}直接签发。 - 取到的 token 按
baseUrl::username缓存;业务请求带Authorization: Bearer(顺带绕过 CSRF)。 authedFetch在 401 时清缓存、用 username 重登并重试一次。- 后端该端点在
auth_middleware._PUBLIC_EXACT_PATHS+csrf_middleware._AUTH_EXEMPT_PATHS白名单里。
8. 对接的后端契约
后端实现:offline-backend-20260512/backend/app/gateway/routers/parallel_agents.py
(任务存储:parallel_agent_tasks.py + deerflow/persistence/parallel_agent_tasks/)。
| 用途 | 接口 |
|---|---|
| 取 token | POST /api/parallel-agents/auth/token {username} |
| 并行流式 | POST /api/parallel-agents/run/stream {task_name, brief, agent_ids[], model?} → SSE |
| 任务 CRUD | GET/POST/GET{id}/PUT{id}/DELETE{id} /api/parallel-agent-tasks |
| 模型列表 | GET /api/models → {models:[{name, display_name}]} |
后端运行策略(重要):每个并行席位是「执行席位」,不是总控。
- 禁用工具
_EXCLUDED_TOOLS = [write_file, str_replace, agent_orchestration, bash]:①禁写文件(并行 不互相打架);②禁agent_orchestration/bash(防弱模型模仿总控派活或绕道脚本逃逸)。 - 保留 只读 / 检索工具 +
ask_clarification→ 步骤条、协作卡片正常(用户协助开启)。 - 任务消息带角色边界护栏(「执行席位、不要模仿总控调度 / 派活」)。
- 步骤
args通过累积tool_call_chunks+ 终态全量tool_calls补全(流式期间空 args 不发,防钉死)。 ask_clarification从终态 messages 抽成结构化agent_clarification事件。
前端澄清(用户协助)交互要点(useParallelRun / ClarificationCard / ParallelAgentsPanel):
- 协作卡片不再因
submitting禁用:整批仍在跑时也能立刻回答某个已澄清的席位。 rerunAgent放开了「整批 running 时禁止重跑」的限制(澄清是该席位合并流里的终态,不会再抢气泡), 只拦同一席位的并发重跑;收尾循环(start的 finally)跳过 busy 席位,交给rerunAgent自己结算。- 答澄清后不立刻清空正文/步骤:先移除卡片、置流式并标记
rerunPending,等重跑产出第一条新事件 时(maybeStartRerun)再清空替换,避免单选视图整列空白闪烁。 - 「单席位结算回传」
onAgentSettled:clarify不回传(待用户协助≠模型完成),等重跑出done/error再回传。
9. 样式系统(嵌入安全)
parallel-agents.css(零依赖、不再用 Tailwind):
- 颜色全用作用域内的
--pa-*深蓝 token(取自《深蓝 UI 规范》,与圆桌 Step2 深色一致),全部包在 根类.parallel-agents下,不污染宿主。 - 语义类
.pa-card / .pa-surface / .pa-border / .pa-text(-muted/-primary) / .pa-input / .pa-btn-* / .pa-badge / .pa-dot-*(席位角标,含 .pa-dot-clarify) / .pa-md(Markdown)—— 组件上色用这些类。 - 布局用文件末尾的「最小工具类子集」(
flex/gap-*/rounded-*/text-[11px]/lg:grid-cols-2等,模板用到的逐条手写成纯 CSS)。它包在@layer pa-utilities里,所以无层级的.pa-*语义类在同属性冲突时仍压过工具类(复刻原先 Tailwind-utilities-在-layer 的优先级)。 维护:模板新增布局类时,在该子集补一条对应规则即可(或写组件 scoped<style>)。 - 面板自带深色成色,不随宿主明暗变化;根元素
h-full w-full flex flex-col min-h-0自适应容器。
10. 步骤条 / 协作卡片(与圆桌的对应)
- 步骤条
MessageStepsCard.vue← 圆桌MessageStepsCard.tsx+ChainOfThought:图标列(带竖向连接线)- 中文文案 + 时间 + 参数子节点。文案/图标映射在
step-display.ts(getStepDisplay),参数子节点 在getStepArgs(chip / code / text / kv)。加新工具图标:在step-display.ts的 switch +StepIcon.vue各加一条。
- 中文文案 + 时间 + 参数子节点。文案/图标映射在
- 协作卡片
ClarificationCard.vue← 圆桌第一步IntentClarificationCard.tsx:标题/类型标签/背景/选项 chip(单选点击即发、多选可勾)/自定义输入/发送。提交回传格式化回答 → 面板onClarify→rerunAgent带「【用户补充】…」重跑该单个智能体。
11. 构建与产物
pnpm install
pnpm dev # dev demo(连本地后端,App.vue 里填 baseUrl/username/agents)
pnpm typecheck # vue-tsc --noEmit
pnpm build:lib # 组件库:dist/parallel-agents-vue.{js,umd.cjs,css}
vite.config.ts:--mode lib走build.lib,external:['vue'],output.exports:'named',CSS 不拆分。package.jsonexports:.→ESM/UMD + types;./style.css→样式。宿主import "parallel-agents-vue/style.css"。
12. 常见扩展怎么改
| 需求 | 改哪里 |
|---|---|
| 新增一个 SSE 事件类型 | types.ts 的 StreamEvent + useParallelRun.handleEvent + 后端 parallel_agents.py |
| 步骤条支持新工具的图标/文案 | step-display.ts(getStepDisplay/getStepArgs)+ StepIcon.vue |
| 改深色配色 / 加浅色主题 | parallel-agents.css 的 --pa-*(浅色可在 .parallel-agents--light 下覆盖) |
| 改布局类 / 加新工具类 | parallel-agents.css 末尾的「工具类子集」补规则,或组件 scoped <style>(不要装 Tailwind) |
| 改默认后端地址 / 模型 | config.ts(DEFAULT_BASE_URL / DEFAULT_MODEL) |
| 多席位并排显示(取消单选) | ParallelAgentsPanel.vue 的 selected / visibleSeats / toggleSeat 逻辑 |
| 改自动下滑 / 浮动按钮行为 | AutoScrollPane.vue(BOTTOM_TOLERANCE 容差 / onScroll 暂停恢复逻辑)+ .pa-autoscroll-btn 样式 |
| 宿主自定义存储(不走后端) | 用 @completed + getResults() 取数据,自行存;不调用 createTask/updateTask |
| 改鉴权方式 | api.ts 的 resolveToken / loginByUsername / authedFetch + config.ts 的 TOKEN_PATH |
13. 注意事项 / 已知约束
- agent_id 必须真实(后端注册过的 id),只填名字不行;可用 id 见 06-可用智能体清单.md。
- 并行席位禁派活/脚本/写文件:本面板里每个智能体只做自己那份分析,产出走正文。
- 用户协助(澄清)已启用:
ask_clarification保留;席位信息不足时可弹协作卡片。卡片任何时候都可点 (含整批仍在跑时),用户答完即重跑该席位;待协助(clarify)不算完成、不回传给宿主。 - 协作卡片回答是重跑单个智能体(新线程 + 把回答拼进任务),不是 LangGraph 原地 resume。
- token 取自公共端点(无门槛旁路)—— 适合内网;若网关要暴露公网,建议给取 token 端点加共享密钥校验。
- 跨域:宿主与后端不同源时,后端需放开该来源 CORS +
credentials。