wsk/deerflow-code
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

da

Browse Source
This commit is contained in:
董宏凯 committed 2026-06-10 12:51:13 +08:00
1 parent ca9960c8bc
commit bd426ed1d3
24 files changed
+912 -108
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

parallel-agents-vue/docs/05-嵌入与深色样式.md
+5 -5
View File
@@ -84,15 +84,15 @@ pnpm build:lib
## PA-EMBED-06 · 不污染宿主全局样式（P0）
**目的**：核对**未引入 Tailwind preflight**（不重置宿主全局标签样式）。
**目的**：核对面板**不依赖 Tailwind**、不重置宿主全局标签样式（无任何裸标签选择器 / reset）。
**操作步骤**
1. 在一个有自己样式的宿主页里嵌入面板（页面有 `h1/p/button/ul` 等默认样式）。
1. 在一个有自己样式、且**没装 Tailwind** 的宿主页里嵌入面板（页面有 `h1/p/button/ul` 等默认样式）。
**预期结果**
- 嵌入后，宿主页面**自身**的 `h1/p/button/列表/边距` 等样式**不被改变**（没有被 Tailwind 的 reset 抹平）。
- 面板内部样式正常（不依赖宿主提供 Tailwind）。
- 类名都在 `.parallel-agents` 作用域下，不与宿主类名冲突。
- 嵌入后，宿主页面**自身**的 `h1/p/button/列表/边距` 等样式**不被改变**（面板样式无全局 reset、无裸标签规则）。
- 面板内部样式正常（**不需要宿主提供 Tailwind**；布局类是面板自带的作用域工具类子集）。
- 所有规则都在 `.parallel-agents` 作用域下，不与宿主类名冲突。
---
parallel-agents-vue/docs/07-使用说明.md
+32 -12
View File
@@ -20,6 +20,8 @@
2. **样式**：`parallel-agents-vue/style.css`（一次性引入即可，样式作用域全在 `.parallel-agents` 下）
> 依赖说明：`vue ^3.4`（宿主提供，库不打包 vue）；`markdown-it` 已打进库内，无需宿主安装。
> **无需 Tailwind 或任何 CSS 框架**：布局样式已内置为 `parallel-agents.css` 末尾的「最小工具类子集」
> （全部作用域在 `.parallel-agents` 下，不污染宿主）。宿主项目**不用**装 / 配 Tailwind。
---
@@ -41,21 +43,32 @@
import "parallel-agents-vue/style.css";
```
### 方式 B：直接拷贝源码（无需发包）
### 方式 B：直接拷贝源码（无需发包，**推荐给需要改源码的人**）
把本项目 `src/` 下这些拷进宿主项目（保持相对结构），按相对路径引入 `ParallelAgentsPanel.vue` +
`styles/parallel-agents.css` 即可：
所有实现已收进**一个自包含文件夹** `src/parallel-agents/`。把**整个文件夹**拷进宿主项目的 `src/`
下即可，内部全是相对路径引用、不依赖任何构建别名：
```
src/
components/ ParallelAgentsPanel.vue · MessageBubble.vue · MessageStepsCard.vue
ParallelSeatStrip.vue · Avatar.vue · MarkdownContent.vue
composables/ useParallelRun.ts
lib/ avatar-constants.ts
styles/ parallel-agents.css
api.ts · config.ts · types.ts
src/parallel-agents/ ← 整个文件夹拷走即用
index.ts 入口：自动引样式 + 导出组件/类型
ParallelAgentsPanel.vue 主组件
ParallelSeatStrip.vue · MessageBubble.vue · MessageStepsCard.vue · StepIcon.vue
ClarificationCard.vue · MarkdownContent.vue · Avatar.vue （子组件）
useParallelRun.ts 并行运行编排
api.ts · types.ts · config.ts · avatar-constants.ts · step-display.ts
parallel-agents.css 作用域样式（深色 token + 语义类 + 工具类子集，无 Tailwind）
README.md 本文件夹的速用说明
```
引入（样式由 `index.ts` 自动引入，无需手动 import css）：
```ts
import { ParallelAgentsPanel } from "@/parallel-agents";
// 或相对路径： import { ParallelAgentsPanel } from "./parallel-agents";
```
宿主需有 `markdown-it` 依赖（`pnpm add markdown-it`），并保证构建支持 `.vue`（Vite/@vitejs/plugin-vue）。
**不需要 Tailwind**。
---
@@ -446,6 +459,9 @@ function readOne(id: string) {
```
`AgentResult = { agent_id, name, content, status }`，`content` 即该智能体模型返回的正文（Markdown）。
`status` 取值：`pending | running | done | clarify | error`。**`clarify` = 该智能体在等用户协助
（待确认），不是已完成**——宿主判断「是否全部完成」时应排除 `clarify`（例如
`results.every(r => r.status === "done")`），不要把待协助当成 done。
`defineExpose` 还暴露了 `reanalyze()` / `start()` / `save()` / `cancel()` / `loadTask(id)` 等方法及
`running` / `saving` / `hasResults` / `canStart` / `history` 等状态，完整清单见 [§六·二](#六二暴露的方法与状态模板-ref)。
@@ -503,7 +519,10 @@ taskId.value = "task-001"; // 改了之后面板自动回显 task-
防子智能体模仿总控调度）；检索、查看、`ask_clarification` 等照常 —— 所以**步骤条 / 协作卡片正常
显示**，每个智能体只做自己那份分析。
- 主区每次只显示**一个**席位的消息列表；**点席位头像切换**要看哪个（单选）。
- 顶部席位状态条显示每个智能体的进行中 / 完成 / 出错。
- 顶部席位状态条显示每个智能体的进行中 / 完成 / **待协助** / 出错；待协助数量会单独标「N 待协助」。
- **用户协助（澄清）**：智能体要澄清时该席位变「待协助」（不是完成），气泡里弹协作卡片。多个智能体
同时待协助时**可分别点协助、互不阻塞**（协助 A 不会禁用 B/C 的卡片）；提交回答后该席位自动带上
补充重跑。
- **任务名 / 简介 / 模型 / 按钮 / 历史下拉全部在宿主侧**：模型空 = `model` prop / 配置 / 后端回退；
模型作用于**下一次**`reanalyze()`。
- `panel.save()` 存档；`panel.loadTask(id)` 回显；`panel.reanalyze()` 清空重跑；`panel.cancel()` 停止。
@@ -514,7 +533,8 @@ taskId.value = "task-001"; // 改了之后面板自动回显 task-
## 九、注意事项
- **不会污染宿主全局样式**：库未引入 Tailwind preflight，类名都在 `.parallel-agents` 作用域内。
- **不会污染宿主全局样式**：**不依赖 Tailwind**，布局类已内置为作用域工具类子集，所有规则都在
`.parallel-agents` 下，绝不外泄到宿主页面。
- **深色自带成色**：面板始终深蓝深色，不随宿主明暗切换（与圆桌 Step2 观感一致）。
- **跨域**：若宿主与后端不同源，后端需允许该来源的 CORS + 带 `credentials`；登录端点公共且 CSRF 豁免，
业务请求用 Bearer 头已绕过 CSRF。
parallel-agents-vue/docs/08-开发文档.md
+47 -33
View File
@@ -23,7 +23,7 @@
| 框架 | Vue 3（`<script setup>` + Composition API） |
| 构建 | Vite 6（dev app + `build:lib` 组件库双产物） |
| 语言 | TypeScript（`strict` + `noUnusedLocals/Parameters`） |
| 样式 | TailwindCSS v4（**仅 utilities，不引 preflight**）+ 作用域 `.pa-*` token |
| 样式 | **零 CSS 框架**：作用域 `.pa-*` token + 内置「最小工具类子集」（不依赖 Tailwind） |
| Markdown | `markdown-it`（打进库，宿主无需安装） |
| peer dep | `vue ^3.4`（宿主提供，库不打包 vue） |
@@ -31,31 +31,33 @@
## 3. 目录结构与各文件职责
实现全部收在**一个自包含文件夹** `src/parallel-agents/`（内部相对路径引用、不依赖构建别名，
整个文件夹可直接拷给宿主用）。`src/` 顶层只剩 demo 与库入口。
```
src/
├─ index.ts 库入口：导出 ParallelAgentsPanel + install 插件 + 类型；import 样式
├─ index.ts 库入口：从 ./parallel-agents 再导出 + install 插件
├─ main.ts / App.vue dev demo（仅本地调试用，不进库）
├─ config.ts 配置：DEFAULT_BASE_URL / DEFAULT_MODEL / TOKEN_PATH
├─ types.ts 共享类型：Dialogue / SeatView / DialogueStep / ClarificationPayload
│ / AgentInput / AgentResult / SavedTask / StreamEvent（事件协议）
├─ api.ts 后端访问层：鉴权(取 token+缓存+401 重登) / SSE 流 / 任务 CRUD / 模型列表
├─ composables/
│ └─ useParallelRun.ts 运行编排（前端态核心）：消费合并 SSE → 维护 dialogues/seats；
│ start / cancel / hydrate(回显) / reset / rerunAgent(单席位重跑)
├─ lib/
│ ├─ avatar-constants.ts 头像配色 + getAvatarTypeFor（轮转）
│ └─ step-display.ts 步骤条：getStepDisplay(图标+中文文案) / getStepArgs(参数子节点)
├─ styles/
│ └─ parallel-agents.css 作用域深色 token(--pa-*) + .pa-* 语义类 + Markdown 样式（无 preflight）
└─ components/
├─ ParallelAgentsPanel.vue 主组件：输入区/操作区/模型切换/历史/席位条/会话区 + 全部状态编排
├─ ParallelSeatStrip.vue 席位状态条（头像 + running/done/error 角标，点击切换单显）
└─ 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 角标，点击切换单显）
├─ 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 头像
├─ Avatar.vue 机器人 / 真人 SVG 头像
└─ README.md 文件夹速用说明
```
---
@@ -98,7 +100,7 @@ panel emit "completed"(AgentResult[])；可点「保存」(按 taskId upsert) /
| `agent_start` | `agent_id` | 该席位置 running |
| `delta` | `agent_id, text` | 追加正文（节流） |
| `step` | `agent_id, key(=`tool_calling:<tool>`), label, args` | 步骤条加一步（含完整 args） |
| `agent_clarification` | `agent_id, content, question, clarification_type, clarification_context, options, allow_*` | 设 `dialogue.clarification` → 卡片 |
| `agent_clarification`〔已禁用〕 | `agent_id, content, question, clarification_type, clarification_context, options, allow_*` | 设 `dialogue.clarification` → 卡片；席位置 **clarify**（待协助，非 done）。**注**：后端已把 `ask_clarification` 加入 `_EXCLUDED_TOOLS`，本面板**无人值守**不再发该事件；前端协作卡片相关代码保留（兜底，正常不触发） |
| `agent_done` | `agent_id, content` | 收口，正文以终态为准 |
| `agent_error` | `agent_id, message` | 该席位置 error |
| `all_done` | — | 全部结束 |
@@ -106,9 +108,10 @@ panel emit "completed"(AgentResult[])；可点「保存」(按 taskId upsert) /
**核心数据模型**（`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: pending|running|done|error, bubbleId }`
- `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 }`（宿主读取用）
- `AgentResult { agent_id, name, content, status }`（宿主读取用；`status` 同 `SeatStatus`）
> 改协议时：`types.ts` 的 `StreamEvent` 与后端 `parallel_agents.py` 的事件 dict **必须同步**。
@@ -157,23 +160,30 @@ ParallelAgentsPanel
| 模型列表 | `GET /api/models` → `{models:[{name, display_name}]}` |
**后端运行策略（重要）**：每个并行席位是「执行席位」，不是总控。
- **禁用工具** `_EXCLUDED_TOOLS = [write_file, str_replace, agent_orchestration, bash]`：①禁写文件（并行
不互相打架）；②禁 `agent_orchestration`/`bash`（防弱模型模仿总控**派活**或绕道脚本逃逸）。
- **保留** 只读 / 检索工具 + `ask_clarification` → 步骤条、协作卡片正常。
- 任务消息带**角色边界护栏**（「执行席位、不要模仿总控调度 / 派活」）。
- **禁用工具** `_EXCLUDED_TOOLS = [write_file, str_replace, agent_orchestration, bash, ask_clarification]`：
①禁写文件（并行不互相打架）；②禁 `agent_orchestration`/`bash`（防弱模型模仿总控**派活**或绕道脚本逃逸）；
③禁 `ask_clarification`（**禁用用户协助**：本面板是并行**无人值守**扇出，没有让单席位中途打断、向用户
要澄清的交互位 —— 席位信息不足时自行做**合理假设**并写进正文交付，而非挂起等人）。
- **保留** 只读 / 检索工具 → 步骤条正常。
- 任务消息带**角色边界护栏**（「执行席位、不要模仿总控调度 / 派活」）+ **无人值守护栏**（「信息不足时
自行合理假设并注明，不要反问用户 / 不要挂起等待补充」）。
- 步骤 `args` 通过累积 `tool_call_chunks` + 终态全量 `tool_calls` 补全（流式期间空 args 不发，防钉死）。
- `ask_clarification` 从终态 messages 抽成结构化 `agent_clarification` 事件。
- `ask_clarification` 已被禁用，正常不再产生 `agent_clarification` 事件；`_clarification_from_messages`
仅作终态兜底（工具被禁后恒返回 `None`），不影响其他业务路由（圆桌 / 普通问答的澄清照常）。
---
## 9. 样式系统（嵌入安全）
`styles/parallel-agents.css`：
- **不引 Tailwind preflight**（`@import "tailwindcss/theme.css"` + `utilities.css`），避免重置宿主全局样式。
`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-md(Markdown)` —— 组件**上色用这些类**，布局用 Tailwind 工具类。
.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` 自适应容器。
---
@@ -181,7 +191,7 @@ ParallelAgentsPanel
## 10. 步骤条 / 协作卡片（与圆桌的对应）
- **步骤条** `MessageStepsCard.vue` ← 圆桌 `MessageStepsCard.tsx` + `ChainOfThought`：图标列(带竖向连接线)
+ 中文文案 + 时间 + 参数子节点。文案/图标映射在 `lib/step-display.ts`（`getStepDisplay`），参数子节点
+ 中文文案 + 时间 + 参数子节点。文案/图标映射在 `step-display.ts`（`getStepDisplay`），参数子节点
在 `getStepArgs`（chip / code / text / kv）。加新工具图标：在 `step-display.ts` 的 switch + `StepIcon.vue`
各加一条。
- **协作卡片** `ClarificationCard.vue` ← 圆桌第一步 `IntentClarificationCard.tsx`：标题/类型标签/背景/选项
@@ -208,8 +218,9 @@ pnpm build:lib # 组件库：dist/parallel-agents-vue.{js,umd.cjs,css}
| 需求 | 改哪里 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| 新增一个 SSE 事件类型 | `types.ts` 的 `StreamEvent` + `useParallelRun.handleEvent` + 后端 `parallel_agents.py` |
| 步骤条支持新工具的图标/文案 | `lib/step-display.ts`（`getStepDisplay`/`getStepArgs`）+ `StepIcon.vue` |
| 改深色配色 / 加浅色主题 | `styles/parallel-agents.css` 的 `--pa-*`（浅色可在 `.parallel-agents--light` 下覆盖） |
| 步骤条支持新工具的图标/文案 | `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` 逻辑 |
| 宿主自定义存储（不走后端） | 用 `@completed` + `getResults()` 取数据，自行存；不调用 `createTask/updateTask` |
@@ -221,6 +232,9 @@ pnpm build:lib # 组件库：dist/parallel-agents-vue.{js,umd.cjs,css}
- **agent_id 必须真实**（后端注册过的 id），只填名字不行；可用 id 见 [06-可用智能体清单.md](./06-可用智能体清单.md)。
- 并行席位**禁派活/脚本/写文件**：本面板里每个智能体只做自己那份分析，产出走正文。
- 协作卡片回答是**重跑单个智能体**（新线程 + 把回答拼进任务），不是 LangGraph 原地 resume。
- **已禁用「用户协助」**：并行无人值守，后端把 `ask_clarification` 加入 `_EXCLUDED_TOOLS`，席位不再向用户要
澄清（信息不足时自行合理假设并在正文注明）。前端 `ClarificationCard.vue` / `onClarify` / `rerunAgent`
等协作链路代码保留作兜底，正常不触发；**仅影响本面板**，圆桌 / 普通问答的澄清不受影响。
- 协作卡片回答是**重跑单个智能体**（新线程 + 把回答拼进任务），不是 LangGraph 原地 resume（当前已禁用，仅兜底保留）。
- token 取自公共端点（无门槛旁路）—— 适合内网；若网关要暴露公网，建议给取 token 端点加共享密钥校验。
- 跨域：宿主与后端不同源时，后端需放开该来源 CORS + `credentials`。