Files
deerflow-code/parallel-agents-vue/docs/08-开发文档.md
T
2026-06-10 17:44:44 +08:00

18 KiB
Raw Blame History

开发文档 · 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.json exports:.→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。