feat(workflow): 增加会话级多智能体任务规划运行能力
提交范围聚焦于工作流编排新增:新增 workflow_planning 路由与前后端运行入口(workflow_planning.py、workflow_proposal_planner.py、workflow_deep_research_adapter.py),支持基于会话的提案-规划-执行流程,满足任务驱动式多智能体协作。 完成网关层运行时适配:扩展 workflow_resource_checks、workflow_executor、workflow_runs、workflow_agent_runner 与依赖注入,新增/更新配置(config.yaml、workflow_config),并补充 lead_agent 路径与节点实现,确保 Planner 与普通工作流运行态衔接一致。 补齐持久化与建模:新增 workflow_planning 持久化模块与 MySQL migration(20260831_01_workflow_planning_sessions),注册 SQL 与模型、内存 store,并扩展错误/表达式/validator/节点语义以承载新会话态输入输出。 增强文档与测试:新增会话式多智能体编排中文说明、更新开发文档与 AGENTS 指南、补充 workflow_engine/workflow_runs 回归测试,提高新路径的行为可验证性;同时留存 seed 资产(workflow-planner)便于一体化部署。
This commit is contained in:
1 parent
ac92f29db1
commit
1706a24182
39 files changed
+4896
-81
No files matched your search
+476
@@ -0,0 +1,476 @@
|
||||
# 对话驱动的多智能体工作流编排:开发设计说明
|
||||
|
||||
> 状态:阶段 A、Evidence Pack、Deep Research 写作接入和阶段 C 的首个“终态节点定点修订”闭环已实现;其余阶段仍为设计与待开发项(以 2026-08-31 的代码为基线)
|
||||
> 适用范围:工作流编辑器的“对话运行”页面、工作流运行时、深度研究报告能力
|
||||
> 关联文档:[WORKFLOW_STUDIO_BACKEND_DEV_ZH.md](./WORKFLOW_STUDIO_BACKEND_DEV_ZH.md)、[ADR 0001](./adr/0001-workflow-studio-runtime.md)
|
||||
|
||||
## 1. 要解决的问题
|
||||
|
||||
用户在工作流页面输入一个自然语言任务后,系统应能理解意图、选择合适的工作流模板和智能体角色、并行收集信息、多角度分析、汇总证据,最后生成可追溯的高质量报告。整个过程不是“等所有模型返回后一次性展示”,而是可实时观察、可插话、可调整、可停止和可局部重跑的执行过程。
|
||||
|
||||
典型任务例如:
|
||||
|
||||
> “分析本周销售下滑的原因,结合用户反馈和竞品投放,给出下周广告与产品体验改进建议,并整理成汇报报告。”
|
||||
|
||||
该任务应该被拆成可执行的子任务,而不是把原句依次发给多个 Agent:
|
||||
|
||||
```text
|
||||
用户消息
|
||||
│
|
||||
▼
|
||||
意图理解 / 计划生成
|
||||
│ ├── 信息不足 ──► 用户协助卡片 ──► 同一运行恢复
|
||||
▼
|
||||
工作流模板与角色选择
|
||||
│
|
||||
├── 销售/业务数据收集 ─┐
|
||||
├── 用户反馈收集 ├──► 证据归一化与校验 ─► 多视角分析
|
||||
└── 竞品/投放信息收集 ─┘ │
|
||||
▼
|
||||
报告大纲与深度研究写作
|
||||
│
|
||||
▼
|
||||
质检、引用、产物输出
|
||||
```
|
||||
|
||||
## 2. 设计结论
|
||||
|
||||
采用“**薄总控智能体 + 候选流程选择/编辑 + 确定性工作流运行时 + 专项智能体/技能 + 专用报告写作管线**”的结构。
|
||||
|
||||
- 总控(Planner/Controller)只做语言理解、任务规划、候选流程/角色选择、缺失信息判断和变更影响评估。
|
||||
- 总控一次给出 2–3 条可执行的候选流程;用户选择其中一条后,在右侧画布检查和修改,再显式确认执行。模板只是候选图的后端积木,不是系统静默替用户作出的最终选择。
|
||||
- 工作流引擎仍是唯一的调度者:负责 DAG 依赖、并发、重试、暂停、恢复、取消、权限、事件持久化和状态归并。
|
||||
- 专项 Agent 按明确角色执行收集、分析、审校等任务;它们不拥有全局调度权。
|
||||
- Deep Research 写作能力作为一个可运行、可流式输出的专用节点接入,不把它的内部流程混进总控 Prompt。
|
||||
|
||||
因此,“总控智能体”不是一个包办所有事情的 God Agent。它产生受约束的计划;能否执行、执行什么副作用、如何重试,必须由可审计的后端运行时决定。
|
||||
|
||||
## 3. 当前代码基线:已有能力与缺口
|
||||
|
||||
下表区分当前已有实现和本文建议新增的能力,避免把设计目标误认为已经实现。
|
||||
|
||||
| 范围 | 当前已有实现 | 仍需补齐 |
|
||||
| --- | --- | --- |
|
||||
| 工作流调度 | 自建持久化 DAG 运行时,支持依赖、并发、条件、循环、暂停/恢复、取消与事件日志。核心位于 `packages/harness/deerflow/workflows/runtime/engine.py`、`app/gateway/workflow_executor.py`。 | 计划版本、局部失效/重算、由计划驱动的模板实例化。 |
|
||||
| Agent 节点 | `workflow_agent_runner.py` 中的 Agent/Agent Skill 使用 `make_lead_agent`,并从 `agent.astream()` 转发文本增量与工具事件。 | 完整 Role Catalog、结构化计划校验、上下文与产物的统一输入输出契约。 |
|
||||
| Evidence Pack | `evidence_normalizer` 已是确定性节点:把并行研究节点的结果归一化为有来源节点、角色标签、缺口和截断标志的 `evidencePack`;不会将 Agent 文本伪装成已验证事实。并行调研候选图自动在汇总 Agent 前插入该节点。 | 证据去重、外部来源质量评分、事实校验、引用格式化。 |
|
||||
| 流式事件 | 运行事件可持久化并通过 SSE 推送;现有事件覆盖 run、node、output、tool、artifact、awaiting input 等;`deep_research_write` 会把安全的报告增量投影为 `node.output.delta`。 | 计划事件、变更/版本事件、跨工作节点的统一报告回放/去重指标。 |
|
||||
| 对话运行 | 普通发送先创建持久化 `WorkflowPlanningSession`,后端从当前草稿和已授权 Agent 节点构建 2–3 个候选图;指定 Agent 时仍会投影为 `start → agent → output` 的独立任务。用户选择候选卡片、在画布编辑并确认后,才创建正式 run。终态、无循环 run 的已完成 Agent/Skill 支持定点反馈:创建不可变 revision,复用不受影响的完成节点,目标和下游重新流式执行。运行中输入新方向时,前端会先停止旧 run,保留审计,并将原任务与调整交给 Planner 生成新候选图。 | 真正的连续会话上下文、运行中节点的交互式局部调整、循环图/其他节点类型的影响分析、版本对比界面。 |
|
||||
| 规划持久化 | `workflow_planning_sessions` / `workflow_planning_proposals`(migration `20260831_01`)分离保存 query、候选图、推荐理由、图 revision、选择和确认结果;重复确认返回同一 run。 | 规划会话的过期清理、候选方案差异视图、复杂任务的多轮补充信息。 |
|
||||
| 人机协作 | `human_input` 节点会持久化等待状态,并以一次性 `resumeToken` 通过同一 run 恢复;前端已按 `formSchema` 渲染协助卡片、结构化字段和自然语言补充。 | 恢复后按输入影响范围使下游局部失效、复杂多轮协助与卡片审计视图。 |
|
||||
| 深度研究 | `deep_research_write` 已经复用独立 Deep Research 的 session/job/event/source 持久化:Evidence Pack 转成选中且可追溯的素材,报告正文投影为工作流增量,完成后创建 Markdown artifact;取消也传给同一作业。前端可将完整 Markdown 调用既有 Word 导出接口下载,不改写原 artifact。 | 证据去重/质量评分、引用格式化、把 Deep Research 的多智能体计划暂停映射为工作流 `human_input`。 |
|
||||
| 前端可观测性 | 对话区、运行事件、节点状态已有基础;当前前端已开始将运行状态映射为节点高亮和连线动效。 | 计划摘要、待确认项、用户协助卡片、版本/重跑记录、产物引用的产品化界面。 |
|
||||
|
||||
说明:目前每个 Agent 节点默认使用独立线程 `wf-{run_id}-{node_id}`;只有显式 `threadMode: shared_run_thread` 才会共享 `wf-{run_id}`。这适合节点级隔离,但不能自动等价为“整个页面是一段持续对话”。
|
||||
|
||||
## 4. 目标架构
|
||||
|
||||
```text
|
||||
┌──────────────────────────── Workflow Studio 前端 ────────────────────────────┐
|
||||
│ 左:持续对话、计划摘要、用户协助卡片、节点定点反馈、产物预览 │
|
||||
│ 右:可关闭的画布;按 SSE 状态高亮节点、激活连线、展示并发与等待状态 │
|
||||
└────────────────────────────────────┬────────────────────────────────────────┘
|
||||
│ HTTP + SSE
|
||||
┌────────────────────────────────────▼────────────────────────────────────────┐
|
||||
│ API / Run Gateway │
|
||||
│ 创建运行、订阅事件、停止、恢复、提交协助信息、提出变更、局部重跑 │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Planning Boundary(受约束的总控) │
|
||||
│ Intent → TaskPlan;选择已发布模板/角色/能力;需要时请求用户补充信息 │
|
||||
├─────────────────────────────────────────────────────────────────────────────┤
|
||||
│ Durable Workflow Runtime(唯一调度权) │
|
||||
│ DAG、并发、输入绑定、权限、重试、暂停/恢复、取消、事件、版本、产物索引 │
|
||||
├───────────────┬──────────────────────┬───────────────────┬──────────────────┤
|
||||
│ 专项 Agent │ 确定性节点 │ 人工协助节点 │ 报告写作适配节点 │
|
||||
│ 收集/分析/QA │ HTTP/SQL/转换/合并 │ 表单/确认/选择 │ Deep Research │
|
||||
├───────────────┴──────────────────────┴───────────────────┴──────────────────┤
|
||||
│ 数据、知识库、技能服务、深度研究任务、对象存储、运行/事件/产物数据库 │
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 4.1 职责边界
|
||||
|
||||
| 组件 | 负责 | 不负责 |
|
||||
| --- | --- | --- |
|
||||
| Planner/Controller Agent | 理解用户意图;输出受校验的计划;选择模板和角色;识别缺失输入;解释变更影响。 | 直接调度节点、绕过权限调用工具、任意构造可执行图。 |
|
||||
| 工作流运行时 | 根据图和快照调度;管理状态、并发、失败、暂停、恢复、取消、事件、审计。 | 猜测业务意图、生成报告正文。 |
|
||||
| 研究/分析 Agent | 在给定任务、输入和允许能力内收集或分析,输出结构化结果和引用。 | 修改全局计划或直接驱动其他节点。 |
|
||||
| 技能/工具节点 | 执行受控的 API、SQL、检索或计算,并返回可验证结果。 | 接收未经授权的模型任意参数。 |
|
||||
| Human Assist | 向用户收集缺失/确认信息,恢复同一 run。 | 新建无关联运行来“续聊”。 |
|
||||
| Report Writer | 根据 Report Spec 与 Evidence Pack 输出报告、引用和文件产物。 | 代替 Planner 选择业务流程。 |
|
||||
|
||||
## 5. 端到端运行流程
|
||||
|
||||
### 5.1 首次发送
|
||||
|
||||
1. 用户在左侧对话框提交消息,前端创建 `planning session`,输入包含 `query`、附件/资源引用、可选上下文和当前工作流版本。
|
||||
2. Planner 产生 2–3 个结构化 `WorkflowProposal`(每项含目标、角色、候选图、预估成本、缺失信息),而非只生成一段文字或静默启动一个模板。
|
||||
3. 后端校验每个候选图是否只引用已发布的节点、角色、技能和数据源;不合法的候选图不能展示为“可执行”。
|
||||
4. 前端在对话区展示候选流程选择卡片。用户点击卡片后,右侧画布加载该候选图;用户可拖拽节点、修改绑定、增删合法连接,再触发实时校验。
|
||||
5. 用户点击“确认此流程并执行”后,后端冻结编辑后的 graph snapshot,创建正式 `workflow run`。这一步之后才开始收集、处理、分析、汇总和报告节点;可并行的节点并行执行。
|
||||
6. 若确认前或运行中仍缺失关键条件,创建 `Human Assist` 暂停点,发送 `run.awaiting_input`;前端显示可填写的协助卡片。
|
||||
7. 每一个状态变化和文本增量都写入事件流;前端即时更新对话消息、节点状态和画布连线。报告节点完成后发布正文、引用、文件/链接等 artifact。
|
||||
|
||||
### 5.2 用户在运行中插话
|
||||
|
||||
用户消息必须区分为三种语义,不能全部当作“重新跑一遍”:
|
||||
|
||||
| 用户动作 | 例子 | 后端处理 |
|
||||
| --- | --- | --- |
|
||||
| 补充输入 | “预算是 30 万,周期改成 4 周。” | 写入对应 Human Assist 或运行输入;使依赖该字段的节点继续/失效。 |
|
||||
| 定点反馈 | “竞品分析不要只看价格,补充渠道策略。” | 绑定到目标节点或输出 artifact,创建 `ChangeRequest`;仅重跑受影响的分析、合并、报告链路。 |
|
||||
| 改变任务 | “不要做广告方案了,改成用户留存诊断。” | Planner 评估影响;通常创建新的计划版本,必要时重新选择模板。 |
|
||||
|
||||
推荐产品动作是:消息气泡附带“发送给谁”的可选入口,默认交给 Planner 判断;在某个节点/输出旁点击“让该智能体调整”时,前端携带明确的 `targetNodeId` 或 `targetArtifactId`。没有指定目标的消息不应默认广播给所有 Agent。
|
||||
|
||||
### 5.3 用户协助卡片
|
||||
|
||||
Human Assist 卡片必须代表持久化的等待状态,而不是普通聊天文本。它至少包含:
|
||||
|
||||
- `runId`、`nodeRunId`、`requestId`;
|
||||
- 展示给用户的问题、字段定义、选项、校验规则、是否敏感;
|
||||
- 该输入会影响哪些下游节点;
|
||||
- 提交、稍后处理、取消运行三个动作。
|
||||
|
||||
点击提交时调用“恢复同一运行”的接口,带 `requestId` 与结构化答案。运行时写入 input binding,事件从 `awaiting_input` 变为 `node.resumed` / `node.running`,之后按已有 DAG 继续。绝不能用“新建一条普通聊天消息”替代恢复;那会丢失图快照、依赖、审计和已完成结果。
|
||||
|
||||
### 5.4 停止、重试和局部重跑
|
||||
|
||||
- **停止**:取消 token 传到当前 Agent、工具和深度研究任务;run 标记为 `cancelled`,已完成 artifact 仍保留。
|
||||
- **失败重试**:只在输入和上下文未变时重试原 node run,保留 `retryOf` 关系。
|
||||
- **定点修改后重跑**:现有首个实现为 `POST /api/workflows/runs/{run_id}/feedback`,仅接受终态、无循环图中已完成的 `agent`/`skill` 节点。它从原 run 的冻结执行图计算下游闭包,创建带 `revisionOfRunId`/`feedback` 的新 run,复制闭包外已完成 node run;`feedback` 同时保留 affected/reused node ids 供历史和对话说明复用范围。反馈只加入目标节点的 `RunContext.env.nodeFeedback`,目标及下游重新流式执行,旧 run 不被覆盖。未传 `idempotencyKey` 时服务端按原 run、节点与文本生成稳定键。运行中流程应使用 `human_input` 或先停止;循环图、Deep Research/普通数据节点和副作用节点的定点改写仍需单独策略。
|
||||
- **重新规划**:只允许 Planner 生成新的、经过校验的计划版本;用户可在 UI 看到“旧计划/新计划”差异。对于已经发出模型请求的运行中节点,前端不得声称把新文本插入了旧 prompt;首期采用“停止旧运行(保留审计)→ 原任务 + 新调整交给 Planner → 用户确认新版候选图”的安全语义。常规缺失字段仍优先走同一运行的 `human_input`。
|
||||
|
||||
## 6. 关键数据契约(建议新增)
|
||||
|
||||
下面的对象是建议新增的业务协议,不表示当前接口已经提供。
|
||||
|
||||
### 6.1 TaskPlan:总控输出
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": "1.0",
|
||||
"intent": "market_growth_diagnosis",
|
||||
"summary": "诊断销售下滑并给出广告与体验改进建议",
|
||||
"templateId": "growth-diagnosis-v1",
|
||||
"requiredInputs": [
|
||||
{ "key": "business_period", "label": "分析周期", "required": true },
|
||||
{ "key": "budget", "label": "投放预算", "required": false }
|
||||
],
|
||||
"roles": ["sales_researcher", "voice_of_customer_researcher", "competitor_analyst", "strategy_analyst"],
|
||||
"allowedCapabilities": ["sales_sql", "feedback_search", "web_research"],
|
||||
"reportSpec": {
|
||||
"audience": "业务负责人",
|
||||
"format": "management_report",
|
||||
"sections": ["结论摘要", "证据", "原因分析", "行动建议", "风险与假设"],
|
||||
"citationRequired": true
|
||||
},
|
||||
"confidence": 0.86,
|
||||
"needsHumanInput": false
|
||||
}
|
||||
```
|
||||
|
||||
Planner 输出必须通过 JSON Schema / Pydantic 校验,并检查 `templateId`、`roles`、`allowedCapabilities` 是否都在租户已发布白名单中。不得以自然语言里的“调用某数据库/删除某文件”为依据直接执行。
|
||||
|
||||
### 6.2 Evidence Pack:跨 Agent 的事实输入
|
||||
|
||||
所有研究 Agent 的输出先归一化为证据包,再给分析和报告节点使用。这样能减少“前一节点随手写一段话、下一节点盲目采信”的问题。
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"id": "ev_01",
|
||||
"claim": "近四周新客转化率下降 12%",
|
||||
"source": { "type": "sql", "uri": "artifact://...", "retrievedAt": "2026-08-31T10:00:00Z" },
|
||||
"excerpt": "...",
|
||||
"confidence": 0.92,
|
||||
"ownerNodeRunId": "nr_..."
|
||||
}
|
||||
],
|
||||
"assumptions": ["竞品投放数据来自公开渠道,无法代表完整预算"],
|
||||
"gaps": ["缺少按城市拆分的销售数据"]
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 ChangeRequest:用户中途调整
|
||||
|
||||
```json
|
||||
{
|
||||
"runId": "run_...",
|
||||
"baseRevision": 3,
|
||||
"kind": "node_feedback",
|
||||
"target": { "nodeId": "competitor_analysis" },
|
||||
"message": "补充竞品渠道策略,不要只比较价格。",
|
||||
"attachments": [],
|
||||
"requestedBy": "user"
|
||||
}
|
||||
```
|
||||
|
||||
服务端返回影响范围(例如 `competitor_analysis → evidence_merge → report_writer`)和建议动作。涉及范围较大或成本较高时,先要求用户确认再执行。
|
||||
|
||||
### 6.4 Report Spec:报告写作输入
|
||||
|
||||
报告写作节点的输入固定为 `ReportSpec + EvidencePack + 已确认的用户约束`。不要把整个聊天历史无筛选地塞进写作模型。
|
||||
|
||||
`ReportSpec` 至少包含受众、语言、篇幅、结构、格式、引用要求、语气、禁止项、产物格式(Markdown / DOCX / PDF)和质量标准。
|
||||
|
||||
## 7. 图模型与模板策略
|
||||
|
||||
### 7.1 第一阶段:候选流程优先,模板作为积木
|
||||
|
||||
Planner 从已发布的模板、节点角色和连接规则中组装 2–3 条候选流程,例如:
|
||||
|
||||
- `quick-answer-v1`:少量检索 + 单 Agent 答复;
|
||||
- `growth-diagnosis-v1`:销售、VOC、竞品并行收集 → 策略分析 → 报告;
|
||||
- `market-research-v1`:多源研究 → 证据去重/校验 → 多视角分析 → 报告;
|
||||
- `deep-research-report-v1`:明确主题的研究与深度报告产出。
|
||||
|
||||
每张卡片至少展示:推荐理由、关键步骤、参与角色、数据源/技能、预计耗时与成本、尚缺输入、风险提示。默认给出“推荐方案”,但不自动启动;简单任务也至少显示一张可确认的轻量方案。
|
||||
|
||||
用户点击卡片后,候选图变成当前画布草稿。用户可以在受限的节点目录内修改节点、输入绑定和连接关系;每次修改调用现有图校验。确认时保存最终快照,再进入正式运行。这样既有智能规划,又不把图的控制权藏在模型内部。
|
||||
|
||||
候选方案在确认前不是 `workflow run`,建议使用独立、短生命周期但可恢复的 `WorkflowPlanningSession` / `WorkflowProposal` 持久化模型;不能在一个已启动的 run 中途直接替换整个 graph。Planner 的职责是产出受约束的候选图,而不是生成任意拓扑。
|
||||
|
||||
### 7.2 后续阶段:受约束的动态子图
|
||||
|
||||
确实需要按任务动态增加并行研究视角时,可让 Planner 产出受限的 `PlanSpec`,由服务端编译为子图。要求:
|
||||
|
||||
- 节点类型、角色、技能、连接规则来自白名单;
|
||||
- 设置最大节点数、最大并行数、最大预算和超时;
|
||||
- 编译后做 DAG/端口/类型/权限校验;
|
||||
- 保存最终 graph snapshot 与 plan revision,保证重放和审计;
|
||||
- 动态生成的是“已验证子图”,不是 Agent 直接操作数据库或调度器。
|
||||
|
||||
## 8. 运行状态与流式协议
|
||||
|
||||
### 8.1 状态模型
|
||||
|
||||
现有运行状态可继续作为基础:`queued`、`running`、`awaiting_input`、`completed`、`failed`、`cancelled`。节点状态要至少支持 `queued`、`running`、`completed`、`failed`、`awaiting_input`、`cancelled`。
|
||||
|
||||
建议为 revision 增加展示级状态:`stale`(旧版本保留但不再作为最新结果)、`invalidated`(输入变化导致必须重跑)、`reused`(在新版本中复用旧结果)。如需持久化,须在 schema migration 与 API 中显式加入,不能只在前端猜测。
|
||||
|
||||
### 8.2 SSE 事件约定
|
||||
|
||||
现有事件链路应继续作为单一事实来源:运行和节点事件先持久化,再由 SSE 推送。前端断线后按最后事件序号恢复,不依赖内存中的临时 token。
|
||||
|
||||
建议在既有 `run.*`、`node.*`、`node.output.delta`、`artifact.*`、`run.awaiting_input` 之上增加:
|
||||
|
||||
| 建议事件 | 含义 | 前端行为 |
|
||||
| --- | --- | --- |
|
||||
| `plan.ready` | Planner 产生并校验了 TaskPlan | 显示计划摘要、角色、待补充信息。 |
|
||||
| `plan.rejected` | 计划违反模板/能力/权限约束 | 展示可理解的原因,提示重新输入或人工选择。 |
|
||||
| `run.revision.created` | 用户变更创建了新版本 | 切换到新版本,保留旧版本可查看。 |
|
||||
| `node.invalidated` | 节点结果因变更失效 | 画布标记待重算,显示影响来源。 |
|
||||
| `node.reused` | 新版本复用了节点产物 | 展示复用,不播放“正在执行”的假动画。 |
|
||||
| `report.delta` | 写作服务持续输出报告正文 | 追加到报告消息,同时保留 node output 增量。 |
|
||||
|
||||
事件最小公共字段建议为:`eventId`、`seq`、`runId`、`revision`、`nodeRunId?`、`type`、`timestamp`、`payload`。`seq` 必须在一个 run/revision 范围内单调递增。
|
||||
|
||||
### 8.3 前端实时表现
|
||||
|
||||
- `node.running`:节点高亮、对应入边/出边显示流动效果,左侧展示该节点的增量消息;
|
||||
- `node.output.delta`:立即写入该节点对应的 assistant 消息,使用节流批量渲染,不能等 `node.completed`;
|
||||
- `run.awaiting_input`:停止错误的“加载中”图标,显示协助卡片;
|
||||
- 并行节点:同时高亮多个节点,右侧执行摘要展示完成数量;
|
||||
- `completed/failed/cancelled`:停止动效并给出明确终态,不让旋转图标停在页面上。
|
||||
|
||||
画布可以被用户关闭以让对话区扩大,但不得卸载运行订阅或丢弃节点状态;重新打开时应从事件状态恢复。
|
||||
|
||||
## 9. 后端改造建议
|
||||
|
||||
### 9.1 新增节点类型与适配器
|
||||
|
||||
| 节点类型 | 输入 | 输出 | 实现建议 |
|
||||
| --- | --- | --- | --- |
|
||||
| `task_planner` | `query`、上下文、可用模板目录 | `TaskPlan` 或 Human Assist 请求 | 在 Agent Runner 之上增加严格结构化输出与服务端白名单校验。 |
|
||||
| `evidence_normalizer` | 多个研究结果 | `EvidencePack` | **已实现**:确定性转换、上游引用校验和长度上限;必要时后续增加独立事实校验节点。 |
|
||||
| `analysis_agent` | `TaskPlan`、Evidence Pack、角色提示 | 结构化分析与引用 | 继续复用 Lead Agent,但限制输入、技能和线程。 |
|
||||
| `human_assist` | 字段/问题/校验规则 | 已确认的结构化答案 | 复用现有 pause/resume,补全 requestId、表单 schema 与输入绑定。 |
|
||||
| `deep_research_write` | Report Spec、Evidence Pack、上下文 | 流式正文、引用、artifact | **已实现**:不经 HTTP 自调用,Evidence Pack 固化成选中素材后复用 `regenerate` Job;实时 `report_delta` 与持久 `report_chunk` 去重投影为 `node.output.delta`,取消转发给同一 Job。暂不嵌套 Deep Research `multi_agent` 的计划暂停。 |
|
||||
| `report_qa` | 草稿、引用、质量规则 | 通过/问题列表/修订建议 | 先用确定性规则,必要时再加审校 Agent。 |
|
||||
|
||||
`callable_skill` 当前仍会返回“未可执行”的显式错误。若要用于这套流程,必须先建立技能注册表、输入 schema、权限校验、超时/取消、结果 schema 和审计;不能仅在 Planner 文本中列出技能名称。
|
||||
|
||||
### 9.2 已落地接口与后续接口
|
||||
|
||||
当前已实现的候选规划接口如下。候选图仅能使用当前草稿中可用的 Agent 节点及固定的安全拓扑;服务端校验图和资源目录,并以 `graphRevision` 防止两个页面互相覆盖编辑。`POST .../runs` 是唯一创建正式执行的动作;未选择、校验失败或已绑定到其他 run 的候选都会被拒绝。
|
||||
|
||||
```text
|
||||
POST /api/workflows/{workflow_id}/runs
|
||||
对已选择的 graph snapshot 创建正式运行;body 传 planningSessionId + proposalId。
|
||||
|
||||
POST /api/workflows/{workflow_id}/planning-sessions
|
||||
根据用户 query 生成候选 WorkflowProposal;返回会话、候选图和推荐原因。
|
||||
|
||||
GET /api/workflows/planning-sessions/{session_id}
|
||||
读取可恢复的候选规划会话与选择/确认状态。
|
||||
|
||||
POST /api/workflows/planning-sessions/{session_id}/proposals/{proposal_id}/select
|
||||
选择一条候选图,供右侧画布预览和编辑。
|
||||
|
||||
PATCH /api/workflows/planning-sessions/{session_id}/proposals/{proposal_id}/graph
|
||||
保存用户在画布中编辑后的候选图;后端执行拓扑、端口、类型和资源校验。
|
||||
|
||||
```
|
||||
|
||||
以下接口仍是后续阶段,尚未把建议对象落地为公开 API:
|
||||
|
||||
```text
|
||||
|
||||
GET /api/workflow-runs/{run_id}/events?after_seq={seq}
|
||||
SSE;支持断线续传与快照同步。
|
||||
|
||||
GET /api/workflow-runs/{run_id}/plan
|
||||
获取当前 TaskPlan、revision 和待补充项。
|
||||
|
||||
POST /api/workflow-runs/{run_id}/human-requests/{request_id}/responses
|
||||
提交用户协助卡片答案并恢复同一 run。
|
||||
|
||||
POST /api/workflow-runs/{run_id}/change-requests
|
||||
创建定点反馈、补充输入或重新规划请求;返回影响范围和确认要求。
|
||||
|
||||
POST /api/workflow-runs/{run_id}/revisions/{revision}/apply
|
||||
在需要确认时应用已计算的变更计划。
|
||||
|
||||
POST /api/workflow-runs/{run_id}/node-runs/{node_run_id}/retry
|
||||
对原输入的失败节点重试;与“变更后的局部重跑”区分。
|
||||
```
|
||||
|
||||
已落地的定点反馈接口使用现有运行命名空间,而不是上面的未来 `ChangeRequest` 协议:
|
||||
|
||||
```text
|
||||
POST /api/workflows/runs/{run_id}/feedback
|
||||
body: { nodeId, message, idempotencyKey? }
|
||||
201: 新 revision run(revisionOfRunId、affectedNodeIds、reusedNodeIds)
|
||||
```
|
||||
|
||||
所有写接口都应携带租户/空间、操作人、幂等键与权限上下文。对于存在副作用的技能(写库、发送消息、外部发布),需要独立确认策略,不能因为用户说“继续”就自动执行。
|
||||
|
||||
### 9.3 计划版本与局部重跑
|
||||
|
||||
长期建议新增逻辑对象:`WorkflowRunRevision`、`ChangeRequest`、`HumanRequest`。当前首个实现尚未新增表:revision 直接是一个普通 `workflow_runs` 行,`context.revisionOfRunId`、`context.feedback` 和 `retry_of_run_id` 指向源运行。一次用户修改的完整目标处理为:
|
||||
|
||||
```text
|
||||
ChangeRequest
|
||||
→ Planner 评估影响(或规则引擎根据输入绑定计算)
|
||||
→ 生成 proposed revision + affected nodes
|
||||
→ 必要时要求确认
|
||||
→ 固化 revision、复制/复用可用产物
|
||||
→ 使受影响节点及其下游失效
|
||||
→ 从最早失效节点继续调度
|
||||
```
|
||||
|
||||
不要就地覆盖旧 node run 的输入或输出。旧 revision 仍需可查看,才能解释“为什么报告改了”、支持回滚并满足审计。
|
||||
|
||||
## 10. 前端交互规格
|
||||
|
||||
### 10.1 页面布局
|
||||
|
||||
- 左侧为默认主工作区:持续对话、候选流程选择卡片、运行消息、协助卡片和报告预览;宽度可拖动,用户关闭画布后自动扩展。
|
||||
- 右侧为可关闭的流程图:展示当前 graph snapshot 和执行状态;默认不抢占对话阅读空间。
|
||||
- 执行详情为辅助信息,不能替代对话中的实时反馈。
|
||||
- 输入框内使用图标发送按钮;发送中/等待人工输入/取消中有清晰且无歧义的状态。
|
||||
|
||||
### 10.2 消息显示模型
|
||||
|
||||
消息不要只以 `user/assistant` 两类存储。建议前端 ViewModel 支持:
|
||||
|
||||
- `user_message`:原始任务、补充、定点反馈;
|
||||
- `planner_message`:已理解的目标、选用模板、计划摘要;
|
||||
- `agent_stream`:某一节点的流式过程和最终摘要;
|
||||
- `human_request`:可提交的协助卡片;
|
||||
- `system_event`:开始、停止、失败、重跑、复用等可读状态;
|
||||
- `artifact`:报告预览、下载文件、引用和版本信息。
|
||||
|
||||
每个消息应带 `runId`、`revision`、`nodeRunId?` 和 `eventSeq`,SSE 重连时以这些键去重、补齐并排序。
|
||||
|
||||
### 10.3 对话动作规则
|
||||
|
||||
- 默认“发送”创建任务或把补充内容交给 Planner。
|
||||
- Planner 返回候选流程卡片而非直接执行;点击卡片加载右侧候选图,只有点击“确认并执行”才创建 run。
|
||||
- 候选图编辑期间可以切换到另一张卡片或重新让 Planner 生成方案;未确认的方案不会消耗执行型技能预算。
|
||||
- “发送给某智能体”是显式定点动作,显示目标名称和影响范围。
|
||||
- 点击 Human Assist 卡片只恢复原 run;禁止额外创建 run。
|
||||
- 点击节点可筛选该节点在左侧产生的消息、工具调用和产物。
|
||||
- 在报告中选择一段文字并要求修改时,生成指向该 artifact/section 的 `ChangeRequest`。
|
||||
- 终态后的新问题默认新建 run;“基于这次结果继续”则显式带 `parentRunId` 与所选 artifact,不能靠隐藏共享线程推断。
|
||||
|
||||
## 11. 深度研究报告接入
|
||||
|
||||
Deep Research 是长时任务,应该保持其现有作业模型。工作流节点只做以下适配:
|
||||
|
||||
1. 提交 Job:将 `ReportSpec`、`EvidencePack`、可公开检索范围和已确认上下文提交给 Deep Research 服务;
|
||||
2. 订阅 Job:把研究进度、正文增量、引用和文件状态映射成 run/node 事件;
|
||||
3. 取消 Job:run 被停止或 revision 失效时向下传递取消;
|
||||
4. 固化产物:报告正文、引用清单和生成文件写入 artifact 存储,供后续 QA、用户修改和下载复用;
|
||||
5. 质量门:未达到引用/结构/敏感信息规则时,不直接标记为最终成品。
|
||||
|
||||
传给写作管线的重点是已筛选的证据与明确的报告要求,不是多个 Agent 的原始长对话拼接。这样才可控制上下文长度、降低幻觉、保留来源归因。
|
||||
|
||||
## 12. 实施顺序
|
||||
|
||||
### 阶段 A:先打通当前消息与运行链路(部分完成)
|
||||
|
||||
1. **已完成**:明确普通发送(候选规划)、指定 Agent、正式运行确认三种 API 语义;
|
||||
2. **已完成**:修复用户 `query` 到 Agent 节点 prompt/input binding 的链路,支持 `inputBindings` 和目标 Agent 投影;
|
||||
3. **已完成**:运行中的节点状态和 `node.output.delta` 映射到前端,终态清除 loading;
|
||||
4. **已完成**:候选流程卡片、右侧画布加载/编辑、图校验、确认后冻结快照并创建唯一正式 run;
|
||||
5. **已完成**:Human Assist 卡片按 `formSchema` 渲染、提交结构化值/自然语言补充,并用一次性令牌恢复原 run;
|
||||
6. **待完成**:单 Agent、两并行 Agent、人工暂停工作流的浏览器端端到端验收。
|
||||
|
||||
### 阶段 B:模板化多智能体研究(进行中)
|
||||
|
||||
1. **部分完成**:已有 Agent/技能/数据源权限目录;仍需补全 Role Catalog 的角色元数据与输入输出 schema;
|
||||
2. **部分完成**:受约束 Planner 已只对固定安全策略排序和组图;尚未有独立 `task_planner` 节点类型;
|
||||
3. **部分完成**:已引入 `EvidencePack` 与 `evidence_normalizer`,并接入并行调研候选图;仍需证据去重、质量评分和更丰富的多视角模板;
|
||||
4. **已完成**:将 Deep Research 包装成 `deep_research_write` 节点,并接入并行调研候选图(`调研 → Evidence Pack → 综合分析 → 深度研究报告`);相同主题、证据快照和写作配置会复用同一持久化 Job,任一输入变化都不会复用旧报告;
|
||||
5. **部分完成**:报告 Markdown 已作为 run artifact,并通过工作流 SSE 流式显示;前端可直接调用统一 Word 导出接口下载正式 `.docx`,不改写制品;仍需引用质量/去重和浏览器端端到端验收。
|
||||
|
||||
### 阶段 C:可控的人机协同与修订
|
||||
|
||||
1. **部分完成**:已实现终态、无循环图的完成 Agent/Skill 的定点反馈;通过下游闭包重跑、上游 node-run 复用和稳定幂等键保留审计关系;
|
||||
2. **部分完成**:运行中输入新方向已有安全的“停止旧 run → 原任务 + 调整重新规划”前端闭环;仍需 `ChangeRequest` / 独立 revision 表、同一运行内的局部调整、循环图、Deep Research/有外部副作用节点的专门确认策略,以及产物版本对比;
|
||||
3. **部分完成**:对话区已在完成的智能体消息旁呈现“调整此分析”,提交后切换到新 revision run;仍需在历史/画布中显式展示复用与版本差异;
|
||||
4. **部分完成**:已有取消、重试、断线重连、重复反馈的回归测试;仍需浏览器端端到端验收和多用户/有副作用技能覆盖。
|
||||
|
||||
### 阶段 D:受约束的动态子图(可选)
|
||||
|
||||
仅当固定模板无法覆盖真实任务后再实施:引入 `PlanSpec` 编译器、配额限制、拓扑/权限校验和动态子图审计。不要把该阶段作为修复当前“消息走不通”的前置条件。
|
||||
|
||||
## 13. 验收标准
|
||||
|
||||
### 13.1 功能验收
|
||||
|
||||
- 用户发送一句任务后,任一正在运行 Agent 在数秒内出现状态变化,首个文本增量能在模型完成前显示;
|
||||
- 并行 Agent 同时高亮,连线动画只对应真实的 `running` 状态;
|
||||
- 用户补充预算/周期等字段后,能恢复同一 run,而非创建新 run;
|
||||
- 用户对某分析节点提出修改后,只有该节点、其下游合并和报告节点重跑,其他收集结果可复用;
|
||||
- 报告包含可回溯证据/引用,且可下载为 artifact;
|
||||
- 停止运行会取消进行中的子任务并让所有 loading 进入明确终态;
|
||||
- SSE 断开重连后,消息、节点状态和报告正文不重复、不缺失、顺序正确。
|
||||
|
||||
### 13.2 安全与可运维验收
|
||||
|
||||
- Planner 无法调用未在当前空间授权的技能、数据源或模板;
|
||||
- 每一项外部副作用都有操作者、授权来源、输入摘要、输出和事件审计;
|
||||
- 每个 run/revision 都可还原 graph snapshot、计划、节点输入输出、人工提交和 artifact;
|
||||
- 并发数、单次运行成本、超时、重试次数、报告任务数量均有配额;
|
||||
- 失败事件向用户展示可理解原因,详细堆栈仅在受控诊断日志中可见。
|
||||
|
||||
## 14. 最小闭环建议
|
||||
|
||||
先不要尝试让一个总控 Agent 任意编排所有节点。最小可用闭环应为:
|
||||
|
||||
```text
|
||||
对话输入
|
||||
→ task_planner(选择固定“研究报告”模板)
|
||||
→ [资料收集 Agent A || 资料收集 Agent B]
|
||||
→ evidence_normalizer
|
||||
→ analysis_agent
|
||||
→ human_assist(仅在关键事实缺失时)
|
||||
→ deep_research_write
|
||||
→ report_qa / artifact 输出
|
||||
```
|
||||
|
||||
这个闭环能直接验证当前最关键的产品承诺:用户输入确实进入节点、过程实时可见、用户可在中途补充或纠偏、最终能得到来源可追溯的报告。稳定后再扩展角色数量、技能生态和动态图能力。
|
||||
@@ -11,6 +11,7 @@
|
||||
> **阶段 4 状态:已完成** — agent / skill 节点走 DeerFlow lead agent,模型增量与工具步骤映射为 `node.output.delta` / `node.tool.*`
|
||||
> **阶段 5 状态:已完成** — `human_input` 暂停 + 一次性 resume token、子工作流(深度上限 3)、显式循环与 `max_loop_iterations` / `max_steps` 上限
|
||||
> **阶段 6 状态:已完成** — iframe 票据(origin 白名单 + 60s 一次性 + `frameAncestors`)、按 owner/admin 的运行与数据源鉴权、每用户并发运行上限、结构化审计日志、事件/运行保留期配置与后台清理作业(`WorkflowRetentionCleaner`,每小时扫一次)、失败运行 `POST /retry`(复制已完成节点从失败点续跑,新 run 标 `retry_of_run_id`)、SSE `Last-Event-ID` 优先于 `after`。制品落盘文件仍跟随现有 sandbox/artifact 生命周期,不做工作流专属文件回收。多实例租约竞争 + SSE 重连有单机并发测试(`test_two_dispatchers_only_one_claims_a_run` / `test_sse_reconnect_storm_is_ordered_and_complete`),不是外部分布式压测。
|
||||
> **会话规划补充(2026-08-31)** — 普通对话先由独立内置智能体 `workflow-planner`(工作流总控)读取用户可见业务智能体目录、理解意图并选择角色,返回 2–3 条候选策略;它与 `roundtable-coordinator` 完全隔离,只做规划,不调用工具、不执行研究或正式运行。运行时强制 `disable_tools=True` 与 `thinking_enabled=False`,因此只产生一次轻量规划模型调用。模型仅能挑选已验证的 `agentId` 与既定策略,服务端才负责构造和校验可编辑 DAG;控制器不可用时显式报错,绝不退回关键词/静态模板。`POST /api/workflows/{workflow_id}/planning-sessions/stream` 复用 DeerFlow 控制器的真实流式回调,按目录读取、总控解析、角色选择、候选图组装、校验和完成依次发 SSE 里程碑,最后才发送候选会话;连接建立即写出一个真实的「已接收」传输里程碑,并以 SSE comment 保活/跨越代理缓冲阈值,comment 不会进入业务进度或持久化事件。前端默认收起该步骤条,只展示最新阶段,不能以本地定时器伪造进度。
|
||||
> **审计整改(2026-08-29)状态:功能健壮性项已完成** — 按 `WORKFLOW_STUDIO_BACKEND_REMEDIATION_ZH.md`「0. 整改决策记录」:①人工恢复原子化(`resume_with_payload` 单条件更新 + `set_awaiting_input` 一次写入 checkpoint);②草稿保存 CAS 条件更新(409 带 `currentRevision`)+ 发布版本号计数器 `workflow_definitions.next_version_number`;③事件 seq 计数器 `workflow_runs.next_event_seq`(同事务取号,冲突自愈重试),事件落库失败**丢弃不发布**(删除负序号幽灵事件);④输入/输出完整 JSON Schema 校验(`workflows/schema_validation.py`,路由 400 + 节点错误均带字段路径);⑤测试纳入 Git(`.gitignore` 白名单)+ 新增 SQL 并发回归 `tests/test_workflow_concurrency.py`。迁移 `20260828_04_workflow_counter_columns.py` 增加两个计数器列(存量库由启动列同步自动补齐)。P0-01/02(内网可信环境,不实施)、P1-04/05(安全隔离,暂缓)见整改文档决策记录。
|
||||
> 运行时测试:`tests/test_workflow_engine.py`(引擎、表达式、节点、安全策略)+ `tests/test_workflow_runs.py`(HTTP 生命周期、SSE、暂停恢复、租约回收、数据源、票据)+ `tests/test_workflow_concurrency.py`(整改并发回归:内存 + 真实 SQLite)
|
||||
|
||||
|
||||
Reference in new issue
Block a user