2026-09-07 18:24:55 +08:00

35 KiB

Raw Blame History

对话驱动的多智能体工作流编排：开发设计说明

状态：阶段 A、Evidence Pack、Deep Research 写作接入和阶段 C 的首个“终态节点定点修订”闭环已实现；其余阶段仍为设计与待开发项（以 2026-08-31 的代码为基线）
适用范围：工作流编辑器的“对话运行”页面、工作流运行时、深度研究报告能力
关联文档：WORKFLOW_STUDIO_BACKEND_DEV_ZH.md、ADR 0001

1. 要解决的问题

用户在工作流页面输入一个自然语言任务后，系统应能理解意图、选择合适的工作流模板和智能体角色、并行收集信息、多角度分析、汇总证据，最后生成可追溯的高质量报告。整个过程不是“等所有模型返回后一次性展示”，而是可实时观察、可插话、可调整、可停止和可局部重跑的执行过程。

典型任务例如：

“分析本周销售下滑的原因，结合用户反馈和竞品投放，给出下周广告与产品体验改进建议，并整理成汇报报告。”

该任务应该被拆成可执行的子任务，而不是把原句依次发给多个 Agent：

用户消息
  │
  ▼
意图理解 / 计划生成
  │       ├── 信息不足 ──► 用户协助卡片 ──► 同一运行恢复
  ▼
工作流模板与角色选择
  │
  ├── 销售/业务数据收集 ─┐
  ├── 用户反馈收集      ├──► 证据归一化与校验 ─► 多视角分析
  └── 竞品/投放信息收集 ─┘                          │
                                                       ▼
                                          报告大纲与深度研究写作
                                                       │
                                                       ▼
                                             质检、引用、产物输出

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. 目标架构

┌──────────────────────────── 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 首次发送

用户在左侧对话框提交消息，前端创建 planning session，输入包含 query、附件/资源引用、可选上下文和当前工作流版本。
Planner 产生 2–3 个结构化 WorkflowProposal（每项含目标、角色、候选图、预估成本、缺失信息），而非只生成一段文字或静默启动一个模板。
后端校验每个候选图是否只引用已发布的节点、角色、技能和数据源；不合法的候选图不能展示为“可执行”。
前端在对话区展示候选流程选择卡片。用户点击卡片后，右侧画布加载该候选图；用户可拖拽节点、修改绑定、增删合法连接，再触发实时校验。
用户点击“确认此流程并执行”后，后端冻结编辑后的 graph snapshot，创建正式 workflow run。这一步之后才开始收集、处理、分析、汇总和报告节点；可并行的节点并行执行。
若确认前或运行中仍缺失关键条件，创建 Human Assist 暂停点，发送 run.awaiting_input；前端显示可填写的协助卡片。
每一个状态变化和文本增量都写入事件流；前端即时更新对话消息、节点状态和画布连线。报告节点完成后发布正文、引用、文件/链接等 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：总控输出

{
  "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 的输出先归一化为证据包，再给分析和报告节点使用。这样能减少“前一节点随手写一段话、下一节点盲目采信”的问题。

{
  "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：用户中途调整

{
  "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 的候选都会被拒绝。

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：


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 协议：

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 指向源运行。一次用户修改的完整目标处理为：

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 是长时任务，应该保持其现有作业模型。工作流节点只做以下适配：

提交 Job：将 ReportSpec、EvidencePack、可公开检索范围和已确认上下文提交给 Deep Research 服务；
订阅 Job：把研究进度、正文增量、引用和文件状态映射成 run/node 事件；
取消 Job：run 被停止或 revision 失效时向下传递取消；
固化产物：报告正文、引用清单和生成文件写入 artifact 存储，供后续 QA、用户修改和下载复用；
质量门：未达到引用/结构/敏感信息规则时，不直接标记为最终成品。

传给写作管线的重点是已筛选的证据与明确的报告要求，不是多个 Agent 的原始长对话拼接。这样才可控制上下文长度、降低幻觉、保留来源归因。

12. 实施顺序

阶段 A：先打通当前消息与运行链路（部分完成）

已完成：明确普通发送（候选规划）、指定 Agent、正式运行确认三种 API 语义；
已完成：修复用户 query 到 Agent 节点 prompt/input binding 的链路，支持 inputBindings 和目标 Agent 投影；
已完成：运行中的节点状态和 node.output.delta 映射到前端，终态清除 loading；
已完成：候选流程卡片、右侧画布加载/编辑、图校验、确认后冻结快照并创建唯一正式 run；
已完成：Human Assist 卡片按 formSchema 渲染、提交结构化值/自然语言补充，并用一次性令牌恢复原 run；
待完成：单 Agent、两并行 Agent、人工暂停工作流的浏览器端端到端验收。

阶段 B：模板化多智能体研究（进行中）

部分完成：已有 Agent/技能/数据源权限目录；仍需补全 Role Catalog 的角色元数据与输入输出 schema；
部分完成：受约束 Planner 已只对固定安全策略排序和组图；尚未有独立 task_planner 节点类型；
部分完成：已引入 EvidencePack 与 evidence_normalizer，并接入并行调研候选图；仍需证据去重、质量评分和更丰富的多视角模板；
已完成：将 Deep Research 包装成 deep_research_write 节点，并接入并行调研候选图（调研 → Evidence Pack → 综合分析 → 深度研究报告）；相同主题、证据快照和写作配置会复用同一持久化 Job，任一输入变化都不会复用旧报告；
部分完成：报告 Markdown 已作为 run artifact，并通过工作流 SSE 流式显示；前端可直接调用统一 Word 导出接口下载正式 .docx，不改写制品；仍需引用质量/去重和浏览器端端到端验收。

阶段 C：可控的人机协同与修订

部分完成：已实现终态、无循环图的完成 Agent/Skill 的定点反馈；通过下游闭包重跑、上游 node-run 复用和稳定幂等键保留审计关系；
部分完成：运行中输入新方向已有安全的“停止旧 run → 原任务 + 调整重新规划”前端闭环；仍需 ChangeRequest / 独立 revision 表、同一运行内的局部调整、循环图、Deep Research/有外部副作用节点的专门确认策略，以及产物版本对比；
部分完成：对话区已在完成的智能体消息旁呈现“调整此分析”，提交后切换到新 revision run；仍需在历史/画布中显式展示复用与版本差异；
部分完成：已有取消、重试、断线重连、重复反馈的回归测试；仍需浏览器端端到端验收和多用户/有副作用技能覆盖。

阶段 D：受约束的动态子图（可选）

仅当固定模板无法覆盖真实任务后再实施：引入 PlanSpec 编译器、配额限制、拓扑/权限校验和动态子图审计。不要把该阶段作为修复当前“消息走不通”的前置条件。

13. 验收标准

13.1 功能验收

用户发送一句任务后，任一正在运行 Agent 在数秒内出现状态变化，首个文本增量能在模型完成前显示；
并行 Agent 同时高亮，连线动画只对应真实的 running 状态；
用户补充预算/周期等字段后，能恢复同一 run，而非创建新 run；
用户对某分析节点提出修改后，只有该节点、其下游合并和报告节点重跑，其他收集结果可复用；
报告包含可回溯证据/引用，且可下载为 artifact；
停止运行会取消进行中的子任务并让所有 loading 进入明确终态；
SSE 断开重连后，消息、节点状态和报告正文不重复、不缺失、顺序正确。

13.2 安全与可运维验收

Planner 无法调用未在当前空间授权的技能、数据源或模板；
每一项外部副作用都有操作者、授权来源、输入摘要、输出和事件审计；
每个 run/revision 都可还原 graph snapshot、计划、节点输入输出、人工提交和 artifact；
并发数、单次运行成本、超时、重试次数、报告任务数量均有配额；
失败事件向用户展示可理解原因，详细堆栈仅在受控诊断日志中可见。

14. 最小闭环建议

先不要尝试让一个总控 Agent 任意编排所有节点。最小可用闭环应为：

对话输入
  → task_planner（选择固定“研究报告”模板）
  → [资料收集 Agent A || 资料收集 Agent B]
  → evidence_normalizer
  → analysis_agent
  → human_assist（仅在关键事实缺失时）
  → deep_research_write
  → report_qa / artifact 输出

这个闭环能直接验证当前最关键的产品承诺：用户输入确实进入节点、过程实时可见、用户可在中途补充或纠偏、最终能得到来源可追溯的报告。稳定后再扩展角色数量、技能生态和动态图能力。

35 KiB Raw Blame History Unescape Escape