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

64 KiB

Raw Permalink Blame History

AgentScope 2.0 多智能体报告协作工作台——后端实施计划

文档状态：实施中（RC-BE-000～018 已完成；下一票 RC-BE-019）编写日期：2026-09-05；进度更新日期：2026-09-06 目标项目：F:\react01\deeflow-code\deerflow-server\offline-backend-20260512\backend 协作框架：AgentScope 2.0 前端契约来源：frontend-web/src/report-collaboration/api/types.ts、api/mock.ts、state/event-reducer.ts（前端已完成，契约冻结）尖峰基线：offline-backend-20260512/backend/docs/AGENTSCOPE_BASELINE.md 本文只规划新增的报告协作后端，不修改现有多智能体会商，不使用旧 Workflow Studio DAG 调度器。下文 §8 的 BE-n 与 §10 的 RC-BE-00n 是同一批工单的两种编号；进度以 RC-BE-* 为准。

0. 当前进度

已打通 建会话 → 澄清需求 → 生成 2～3 套候选方案 → 选定 → 创建 queued run（冻结模型 + 模板 + 预算），以及 TaskLedger 波次调度 + 受控成员 / 真实 AgentScope 内核 + 主张级 QualityGate + 正式报告版本/改写 + 产品 durable SSE + 租约 dispatcher/恢复 + 运行期自然语言干预 + owner/预算/审计。主开关默认关闭：config.yaml → report_collaboration.enabled / worker_enabled 均为 false。

运行期 IntentRouter 的歧义兜底已可调用冻结的 coordinator 模型，但明确命令走高精度规则；该智能体无工具且不能调度。POST /runs 仍只入队。worker_enabled 为 false 时 lifespan 不挂载后台循环；测试用 dispatch_once() / WaveExecutor 驱动。GET /runs/{id}/stream 可重放/尾随已持久化事件。生产 worker 在双开时注入 AgentScopeMemberKernel。20 项质量评测已在 RC-BE-018 落地（确定性打分，不跑真实模型）。

工单	状态	代码落点 / 缺口
`RC-BE-000`	条件完成	`agentscope_runtime/event_adapter.py`。`agentscope==2.0.5` 仅为 optional extra，未写入 `uv.lock`（等纵向 POC）。
`RC-BE-001`	完成	`app/report_collaboration/contracts/` + `execution/completion.py`。
`RC-BE-002`	完成	`deerflow.config.report_collaboration_config`；默认双关。
`RC-BE-003`	完成	`deerflow.persistence.report_collaboration/`，迁移 `20260905_01`。
`RC-BE-004`	完成	`/api/report-collaboration`。改写 / apply / restore 见 `015`。SSE 见 `011`。
`RC-BE-005`	完成	`requirement/`：规划前澄清；「直接开始」记默认假设；澄清完成 ≠ 出方案。
`RC-BE-006`	完成	`planning/`：目录投影（无 SOUL/密钥）+ 三策略方案；select 与 start-run 独立。
`RC-BE-007`	完成	`DeerFlowChatModelAdapter` + `freeze_plan_models`；缺模型/能力不匹配在 `POST /runs` 前 422。
`RC-BE-008`	完成	`permission_adapter.py` + `tool_adapter.py`：角色 × 工具矩阵、注入扫描。
`RC-BE-009`	完成	`execution/ledger.py` + `member_runner.py`：TaskLedger 按依赖波次分派；AgentScope/协调者建议不能选下一节点；空输出/非法 JSON 进入新 attempt；超限失败不完成整个 run。内核目前为 `ScriptedMemberKernel`（单测），真实模型/web_search 仍待接。
`RC-BE-010`	完成	`execution/quality_gate.py` + `ArtifactBoard.supersede_previous`：冲突数字/缺口径拒绝；未核验或争议主张不能进分析/章节；审稿必须映射到节点或章节；覆盖矩阵缺口拒绝。Ledger 先 schema 再质检，通过才 `validated`。
`RC-BE-011`	完成	`execution/live_hub.py`：run-scoped Live Hub、`PublishingReportCollaborationStore`（先入库再发布）、`after_seq`/`Last-Event-ID` 重放、心跳、token delta 合帧、SSE 断开不取消 run。`GET /runs/{id}/stream` 已挂载。报告正式版本见 `015`。
`RC-BE-012`	完成	store `list_claimable` / `renew_lease` / `finalize_cancel`；`execution/{dispatcher,executor,recovery}.py`：原子 claim、心跳续租、两阶段取消、过期租约接管。恢复保留已完成节点，遗留 in-flight 标 `interrupted`/`superseded` 并开新 `planned` attempt。晚到成果 `validation_status=superseded`，不改终态。`start()` 仅在 `worker_enabled` 时挂循环；默认双关。
`RC-BE-013`	完成	`execution/quality_roles.py`：Verifier/Analyst/Writer/Reviewer/Reviser 作为受控成员（确定性内核，非 AgentScope Team）。核验标记过期/跨包冲突；缺失角度只重开检索链；审稿 `revise` 只重开目标写作节点 + 审稿自身。`TaskResult.additional_drafts` 允许多条 VerificationResult。脚本内核仍供单测；生产 worker 见 `017`。
`RC-BE-014`	完成	`interventions/`：运行期 IntentRouterAgent（规则优先、模型兜底且无工具）+ 确定性 ImpactAnalyzer + command CAS/safe-point。支持节点/agent 归属校验、角度定向、确认闸门、等待边界、overlay、新 attempt、成果失效及晚到结果隔离。
`RC-BE-015`	完成	`reporting/`：run 开始冻结模板；`ReportFinalizer` 在审稿通过且 lint 后落正式版本并发 `report.version.created`；改写候选 / apply / restore 已挂路由，不再 503。
`RC-BE-016`	完成	owner 隔离、跨会话幂等拒绝、`sanitize_for_user` + 审计落库、每用户 active run 上限、每 run 预算 fail-closed。
`RC-BE-017`	完成	`AgentScopeMemberKernel` 真实 `reply_stream` + 工具 + 结构化成果；生产 worker 注入该内核；冒烟可跳过未安装的 `agentscope`。并发交错/租约恢复仍由 `012` 测试覆盖。
`RC-BE-018`	完成	`app/report_collaboration/eval/`：20 项标注任务（政策/市场/企业/事件/对比各 4）、确定性指标、金标/失败实例、会商盲评对照、20 次固定任务可靠性计数。`cite_required` 与当前默认 knobs 为通过评测的推荐画像。真实模型盲评仍属上线决策，不阻塞本票。
`RC-BE-019`	未开始	灰度与离线发版。

当前可联调路径：打开 report_collaboration.enabled 后，规划前轮询 GET /sessions/{id} 即可看到澄清消息和方案卡；POST /runs 只入队；GET /runs/{id}/stream 重放已入库事件。默认不自动领取 queued run（worker_enabled=false）。测试可调 dispatch_once()。

1. 后端目标

新增一套基于 AgentScope 2.0 Core 的多智能体报告协作运行时，实现：

理解任意报告需求并在必要时澄清。
从当前用户可见的智能体、技能、模型和资料源中筛选能力。
生成 2～3 个真实有差异的候选协作计划。
将选定计划实例化为受 TaskLedger 约束的 AgentScope 任务成员，而非让自由会商自行决定流程。
通过结构化成果物完成检索、核验、分析、综合、写作、审稿和返工。
接受全过程自然语言干预，并只重开受影响的任务和下游成果。
使用数据库租约、durable events、幂等命令和版本化报告保证恢复与一致性。
使用现有 DeerFlow 登录、权限、模型、工具、知识库、报告模板和导出能力。
将所有用户可见的规划、AgentScope 团队消息、智能体流式回复、工具调用及其原始返回、分析、核验、写作、审稿、返工、错误和报告变化一对一镜像到统一对话时间线；前端不建立节点执行结果面板，也不以阶段摘要替代实时消息。

框架能提供协作机制，不能单独保证报告质量。质量由证据合同、来源核验、独立审稿、定向返工、模板约束和真实评测集共同保证。

1.1 前端冻结契约：后端必须适配，不要求前端回退

已完成的双栏前端以 SessionSnapshot 和 run-scoped durable SSE 为唯一事实来源；后端实现不得另造一套摘要卡或节点结果接口来补足过程。

前端已实现行为	后端适配要求
run 创建前轮询 `GET /sessions/{id}`	澄清、需求修订、候选方案与选择结果必须同步写入完整快照；不能只存在于内存任务。
run 后以 `seq` 重放/订阅 SSE	每个 run 的事件先持久化、再发布，`seq` 严格单调且可用 `after_seq` 补拉。
并行成员横向阶段卡	同一并行波次使用相同 `phase_id`；`node_run_id` 固定为 `${node_id}-attempt{attempt}`，不可使用前端无法反查节点的随机值。
复用 `MessageList` 展示过程	assistant、TeamSay、工具调用、工具结果与流式增量均写入 `report_collaboration_messages` 并按原消息协议推送。
成员状态来自局部快照合并	前端没有 `agent_run.*` 事件；成员开始、等待输入、完成、失败、取消时必须发 `session.snapshot: {agent_runs:[...], run?:...}`。
报告在对话流中渐显	写作阶段发 `report.delta`；质量门和版本落库完成后才发 `report.version.created`。
节点抽屉只读	`GET /runs/{id}/nodes/{node_id}/contract` 只返回职责合同，永不返回执行结果正文。

每个写操作读取前端发送的 X-Idempotency-Key 与 X-Expected-Revision；用户消息的服务端镜像必须将同一幂等键放入 metadata.idempotency_key，以替换前端乐观消息而不重复显示。

2. 关键架构决策

2.1 AgentScope 用作任务执行内核，不把 Agent Team 自主会商当作调度器

AgentScope 官方提供 Event System、Agent Team、任务规划和 Agent Service 示例，但团队可靠性与多进程/分布式服务仍在持续完善：

因此采用下列职责分界：

AgentScope Core：单个受控任务成员的模型调用、流式事件、工具调用、权限封装与结构化输出修复。
DeerFlow TaskLedger：计划实例化、依赖拓扑、并发波次、输入成果选择、状态迁移、重试、租约、取消、命令安全点与业务终态。
DeerFlow ArtifactBoard / QualityGate：成果物事实源、验收、失效传播、引用约束和报告版本准入。
Coordinator：受限的规划/协调智能体，只能提出 PlanProposal、TaskAssignment、RepairRequest 和 ClarificationRequest；它不能自行创建任意图、改变数据库或宣告节点完成。
AgentScope TeamSay：允许作为可见的协作交接文本，但不是任务分派、完成判定或数据依赖的事实来源。
DeerFlow：身份、权限、配置、数据库、消息、命令、作业、租约、SSE、成果、文件、报告版本和审计。
AgentScope Event 通过无损 adapter 转为 DeerFlow 领域事件和 LangChain 兼容消息；用户可见内容不能在 adapter 中压缩为进度摘要。
不运行 AgentScope examples/web_ui，不使用 AgentScope Session、MessageBus 或内存对象作为恢复/重放依据，也不使用其 session SSE 作为产品 SSE。
节点公开接口只返回职责合同、图关系和状态，不返回节点实际输出；实际阶段消息、工具过程和成果仍从会话消息流以原生消息、工具步骤、引用和报告文件卡的形式呈现。

2.2 新功能独立，不进入旧运行内核

API 前缀：/api/report-collaboration。
独立 session、plan、run、node run、artifact、event、command、report version 表。
不读写 Workflow Studio 的 workflow_* 业务表。
不调用 Workflow Studio 自定义 DAG scheduler。
不复用 roundtable draft/job 作为新会话。
可复用 Deep Research/roundtable 的基础设施模式，但不能共享状态。

2.3 流程图不是执行器

候选图和运行图用于：

描述角色和任务依赖。
展示成果物传递关系。
展示当前状态和返工范围。
供用户理解和选择方案。

真正调度由 TaskLedger + ArtifactBoard + QualityGate 完成。协调者只能提出服务端可验证的建议；TaskLedger 才能执行分派、依赖解锁、重试和终态迁移，不能返回任意 Python、任意图或数据库操作。

2.4 数据库是唯一事实源

HTTP 只提交命令，不承载完整长任务。
SSE 只投影 durable events。
AgentScope Python 对象可随进程消失。
恢复依赖 requirement snapshot、plan、task ledger、node runs、artifacts 和 report versions。
成果物未落库并通过合同校验前，节点不能完成。

3. 总体架构

flowchart LR
    UI[报告协作前端] --> API[Gateway Router]
    UI <-->|SSE| API

    API --> SESS[Session/Message/Plan Store]
    API --> CMD[Command Store]
    API --> EVT[Event Store]
    API --> REP[Report Version Store]
    API --> DISP[Lease Dispatcher]

    DISP --> EXEC[Report Collaboration Executor]
    EXEC --> LEDGER[Task Ledger]
    EXEC --> BOARD[Typed Artifact Board]
    LEDGER --> COORD[Constrained Coordinator]
    LEDGER --> AS[AgentScope Core Task Workers]
    COORD --> LEDGER
    AS --> TEAM[Research / Verify / Analyze / Write / Review]
    EXEC --> MODEL[DeerFlow Model Adapter]
    EXEC --> TOOL[Allowlisted Tool Adapter]

    TOOL --> WEB[Web Search]
    TOOL --> KB[Knowledge/Wiki]
    TOOL --> SKILL[Approved Skills/MCP]

    BOARD --> EVT
    BOARD --> REP
    REP --> EXPORT[Existing Markdown/Word Export]

3.1 运行进程

开发阶段：

可由 Gateway lifespan 启动单个 dispatcher/worker，便于本地联调。
必须保留独立启动入口和 worker_enabled 开关。

生产阶段：

Gateway 仅提供 API、鉴权和 SSE。
独立 worker 进程领取数据库租约并运行 AgentScope。
Gateway 和 worker 使用同一后端代码与数据库。
多 worker 依赖数据库 claim/lease，不依赖进程内锁。

4. 包边界与目录

建议新增：

offline-backend-20260512/backend/app/report_collaboration/
  contracts/
    requirements.py
    plans.py
    nodes.py
    artifacts.py
    events.py
    commands.py
  agentscope_runtime/
    model_adapter.py
    tool_adapter.py
    event_adapter.py
    permission_adapter.py
    team_factory.py
    coordinator.py
  planning/
    requirement_resolver.py
    agent_catalog.py
    agent_selector.py
    plan_controller.py
    plan_assembler.py
    plan_validator.py
  execution/
    dispatcher.py
    executor.py
    cancellation.py
    task_ledger.py
    artifact_board.py
    quality_gates.py
    recovery.py
  interventions/
    intent_router.py
    impact_analyzer.py
    command_handler.py
  reporting/
    outline.py
    writer.py
    reviewer.py
    versions.py
  live_hub.py
  service.py

offline-backend-20260512/backend/app/gateway/routers/
  report_collaboration.py

offline-backend-20260512/backend/packages/harness/deerflow/persistence/
  report_collaboration/
    model.py
    base.py
    sql.py
    memory.py
    __init__.py

依赖方向：

app.report_collaboration 可以导入 deerflow.* 和 agentscope.*。
deerflow.* 不能导入 app.*。
AgentScope 运行代码不放入 publishable harness。
tests/test_harness_boundary.py 必须继续通过。
AgentScope 依赖加入应用 pyproject.toml，不加入 Harness 公共依赖。

5. 核心领域合同

5.1 `ReportRequirementSnapshot`

topic
objective
audience
language
time_range
geography
required_angles[]
excluded_angles[]
source_constraints
report_structure_id
length_target
tone
deadline_hint
quality_priority
revision

改变研究范围的用户反馈必须创建新 revision。每个 node run 记录使用的 requirement revision，避免新旧要求混用。

5.2 `ReportPlanCandidate`

id
proposal_group_id
title
strategy
summary
rationale
estimated_duration_seconds
estimated_cost_level
requirement_revision
roles[]
nodes[]
edges[]
quality_gates[]
report_structure_id
validation
revision

模型不直接输出可执行图。模型输出 RoleDemand、角度和依赖建议；服务器绑定真实 agent、工具、预算、成果物类型和质量门后生成计划。

5.3 `CollaborationNodeContract`

每个节点包含：

mission
input_artifact_types[]
output_artifact_type
allowed_tools[]
source_policy
acceptance_criteria[]
max_attempts
time_budget_seconds
token_budget
agent_profile_snapshot
dependencies[]

5.4 强类型成果物

成果物	生产者	必要内容	主要消费者
`EvidenceBundle`	Researcher	事实、来源、日期、摘录、可信度、冲突	Verifier、Analyst
`VerificationResult`	Verifier	支持/反对证据、时效、冲突、可用结论	Analyst、Reviewer
`AngleAnalysis`	Analyst	观点、证据引用、假设、局限、缺口	Synthesizer
`SynthesisOutline`	Synthesizer	论证主线、章节、结论、证据分配	Writer
`ReportSectionDraft`	Writer	章节 Markdown、引用、证据 ID	Reviewer、总报告作者
`ReviewDecision`	Reviewer	pass/revise、严重度、问题、返工目标	Coordinator、Reviser
`ReportVersion`	Writer	Markdown、来源索引、模板与质量结果	用户、导出器

TeamSay 用于协作协调，并且其用户可见文本必须原样镜像到会话消息流，便于用户实时查看各成员如何交接；影响下游和报告的内容仍必须写入成果物并通过 Pydantic/JSON Schema，不能因为一条 TeamSay 而视为节点完成。

5.5 节点状态机

planned -> queued -> running -> validating -> completed
                       |             |
                       |             +-> failed
                       +-> awaiting_input -> queued
                       +-> cancel_requested -> cancelled
                       +-> superseded

completed -> reopened -> queued

完成规则：

产生一条 assistant 消息不等于完成。
产生或提交用户协助卡不等于完成。
AgentScope 一次 reply 返回不等于完成。
期望成果物落库、Schema 通过、验收器通过后才能完成。
返工创建新 attempt，保留旧 attempt 和旧成果。

5.6 `TaskLedger`：智能体协作的确定性边界

每个计划节点被实例化为一条可审计的 ledger task；并行只是多个 ready task 位于同一波次，不是让多个智能体在群聊中自行决定谁做什么。

TaskAssignment
  node_id / node_run_id / phase_id / attempt
  requirement_revision
  allowed_input_artifact_ids[]
  expected_artifact_type + acceptance_criteria
  agent_profile_snapshot + allowed_tools + budgets
  command_overlay_revision

TaskResult
  artifact_draft | clarification_request | repair_request | failure
  cited_artifact_ids[]
  source_ids[]

调度规则：

PlanAssembler 将角色建议转为固定节点、边、成果合同和质量门；只允许无环主图。
TaskLedger 仅在依赖的成果物均为 validated、未 supersede 且预算可用时使节点 ready。
每个成员只读 requirement revision、自己的 TaskAssignment 与允许的已验证上游成果；不能把其他成员的原始上下文、工具返回或内部 prompt 当作输入。
并行节点共享 phase_id，但各自有独立 agent_run_id；串行节点用独立 phase_id。成员的 node_run_id 一律为 ${node_id}-attempt{attempt}。
只有 TaskResult 转为成果物并通过 QualityGate 后，ledger 才解锁下游；TeamSay 与普通文本没有解锁能力。
修复/返工创建新 attempt；旧 attempt 及其消息留存但被标为 superseded，不得重新进入下游。

5.7 用户命令的约束化协议

每句话先持久化为用户消息和 CollaborationCommand，再由独立的**意图理解智能体（IntentRouterAgent）**进行两段式判定：规则/上下文高精度路由优先，必要时调用模型并输出受 Pydantic 约束的 IntentDecision。它负责理解，不负责调度或执行。

同一能力有两种受控入口：

时机	`IntentRouterAgent` 的工作	后续处理
尚未开始 run	提取主题、目标、受众、范围、时间、角度、模板和来源约束；判断真正缺失的信息	`RequirementResolver` 写 requirement revision；`PlanController` 生成候选计划。
run 正在执行或已有报告	结合当前选中的 node/agent、等待澄清、成果血缘和报告章节，识别用户是在回答、补角度、重检索、重分析、重跑、改章节、润色、查询还是改规划	`ImpactAnalyzer` 计算实际影响；`TaskLedger` 在确认和安全点后执行。

输入包含用户文本、session/run 状态、最新 requirement、当前 target_node_id / agent_run_id、awaiting clarification、当前报告版本和可见成果摘要；不得输入其他成员的内部 prompt、隐藏推理或无权访问的资料。

IntentDecision
  intent / confidence / normalized_instruction
  scope: conversation | node | artifact_lineage | section | plan
  requested_target_ids[] / requirement_patch?
  requires_confirmation / cost_level / reason

服务端必须验证 target_node_id、agent_run_id 属于当前 session/run，再解析到 node 和成果物血缘；不可相信客户端传入的任意 ID。ImpactAnalyzer 产出实际 impact_nodes、失效成果和新 attempt 计划，用户所见的命令状态由它和 TaskLedger 写入，而非由协调者文本决定。

IntentRouterAgent 的置信度不足、目标不唯一、涉及 requirement/plan revision、预计成本为 high 或影响多个并行分支时，必须返回 requires_confirmation=true；只有用户确认后 TaskLedger 才可执行。对于处于 awaiting_input 的节点，明确回答优先分类为 answer_question，只解锁该节点的依赖链。

6. 数据库设计

表	用途	关键字段
`report_collaboration_sessions`	会话	owner、title、status、requirement_revision、selected_plan_id、active_run_id、current_report_version_id
`report_collaboration_messages`	对话原文镜像	message_id、role、content、tool_calls_json、tool_call_id、agent_run_id、node_run_id、phase_id、visibility、metadata、command_id、created_at、completed_at
`report_collaboration_plans`	候选及修订	proposal_group_id、revision、status、graph_json、validation_json
`report_collaboration_runs`	正式执行	plan_id、status、lease_owner、lease_until、cancel_requested、next_event_seq
`report_collaboration_node_runs`	节点尝试/ledger task	node_id、attempt、`node_run_id=${node_id}-attempt{attempt}`、status、contract_json、input_artifact_ids、command_overlay_revision、agent_snapshot、error、started_at、ended_at
`report_collaboration_agent_runs`	实际团队成员实例	agent_run_id、node_run_id、phase_id、role、display_name、avatar_key、status、agent_snapshot、started_at、ended_at
`report_collaboration_artifacts`	成果物及血缘	artifact_type、producer_node_run_id、requirement_revision、schema_version、content_json、validation_status、superseded_by
`report_collaboration_events`	durable SSE	run_id、seq、event_type、payload、created_at
`report_collaboration_commands`	用户命令	command_id、idempotency_key、intent、scope、status、expected_revision
`report_collaboration_report_versions`	报告版本	version、parent_version_id、markdown、source_index、change_summary

持久化要求：

SQL 和 memory store 共用抽象接口。
active run 使用数据库唯一键去重。
command 使用 idempotency key 去重。
session/run/node 命令使用行锁和 expected revision。
事件 seq 在 run 行内原子分配。
用户消息、协调者消息、成员 TeamSay、流式回复、工具调用和工具返回使用稳定 message_id 与 timeline/event seq；同一 agentRunId 内严格保持因果顺序，保证 MessageList 能以原生消息重建全过程。
并行成员的消息分别归属 agent_run_id，同一事件流仍全量持久化；前端选择标签只能过滤/聚焦，不能影响事件写入或消息顺序。
成员状态的 event 投影使用 session.snapshot 中的增量 agent_runs[] 合并；不可自定义未被前端处理的 agent_run.* 事件。
删除 session 显式删除子资源，不依赖 SQLite cascade pragma。
写事务在 commit 前完成必要序列化。
不使用跨连接 post-commit refresh。
SQLite、MySQL、PostgreSQL 都有迁移与测试。

7. Gateway API 与事件协议

7.1 REST API

POST   /api/report-collaboration/sessions
GET    /api/report-collaboration/sessions
GET    /api/report-collaboration/sessions/{session_id}
PATCH  /api/report-collaboration/sessions/{session_id}
DELETE /api/report-collaboration/sessions/{session_id}

POST   /api/report-collaboration/sessions/{session_id}/messages
GET    /api/report-collaboration/sessions/{session_id}/messages
POST   /api/report-collaboration/sessions/{session_id}/plan-requests
GET    /api/report-collaboration/sessions/{session_id}/plans
POST   /api/report-collaboration/sessions/{session_id}/plans/{plan_id}/select
POST   /api/report-collaboration/sessions/{session_id}/runs

GET    /api/report-collaboration/runs/{run_id}
GET    /api/report-collaboration/runs/{run_id}/events?after_seq={seq}
GET    /api/report-collaboration/runs/{run_id}/stream?after_seq={seq}
POST   /api/report-collaboration/runs/{run_id}/commands
POST   /api/report-collaboration/runs/{run_id}/commands/{command_id}/confirm
POST   /api/report-collaboration/runs/{run_id}/commands/{command_id}/cancel
POST   /api/report-collaboration/runs/{run_id}/cancel
GET    /api/report-collaboration/runs/{run_id}/nodes/{node_id}/contract

GET    /api/report-collaboration/runs/{run_id}/artifacts
GET    /api/report-collaboration/runs/{run_id}/sources
GET    /api/report-collaboration/sessions/{session_id}/reports
POST   /api/report-collaboration/sessions/{session_id}/report-rewrites
POST   /api/report-collaboration/sessions/{session_id}/report-rewrites/{id}/apply
POST   /api/report-collaboration/sessions/{session_id}/report-versions/{id}/restore

GET /sessions/{session_id} 必须返回完整 SessionSnapshot：

session / messages / plans / run / nodes / agent_runs / commands /
report_versions / last_seq

写请求必须读取并回显：

X-Idempotency-Key（服务端唯一去重键；用户消息镜像写入 metadata.idempotency_key）
X-Expected-Revision（陈旧修改返回 409，不静默覆盖）

计划请求和 run 请求只创建 durable command/job，不在请求生命周期中等待完整模型输出。

节点合同接口只返回：

节点名称、角色和分析角度。
mission。
所需输入类型和资料策略。
预期输出类型、结构和验收条件。
允许工具、禁止事项和预算。
上下游节点 ID。
当前状态标签。

它不得返回节点实际生成内容、工具返回、成果物正文、错误堆栈或 attempt 时间线。重新检索、重新分析和重跑节点统一通过 POST /runs/{run_id}/commands 提交自然语言命令。

7.2 SSE Event Envelope

{
  "eventId": "evt_xxx",
  "sessionId": "session_xxx",
  "runId": "run_xxx",
  "seq": 128,
  "type": "node.status.changed",
  "timestamp": "2026-09-02T10:00:00Z",
  "data": {}
}

事件类型：

session.snapshot
message.created
message.delta
message.completed
tool_call.created
tool_call.delta
tool_call.completed
tool_result.created
tool_result.delta
tool_result.completed
team_message.created
team_message.delta
team_message.completed
requirement.updated
clarification.requested
clarification.resolved
plan.progress
plan.proposed
plan.selected
run.status.changed
node.created
node.status.changed
node.progress
node.attempt.created
artifact.created
artifact.validated
artifact.rejected
source.added
command.classified
command.confirmation.required
command.accepted
command.completed
command.failed
report.delta
report.version.created
review.created
error
heartbeat

规则：

历史与实时使用相同 envelope。
支持 Last-Event-ID 和 after_seq。
高频 token/tool 参数增量按 50～250ms 或大小阈值合帧为已持久化 message.delta / tool_call.delta / tool_result.delta；不能每 token 写数据库，也不能仅 live-only 后丢失重放。
每一批增量与消息最新正文同事务写入，再向 Live Hub 发布；断线时能通过 after_seq 重放，快照也能读到最新 checkpoint。
状态、成果、命令和报告版本必须 durable。
读取事件暂时失败时保持连接并发送可恢复 warning。
session.snapshot 可以携带完整快照，也可以携带 run、nodes、agent_runs 的增量集合；成员状态变化必须用此事件投影。

message.* / team_message.* 的 data 必须携带 LangChain 兼容的消息字段和归属，而非仅有摘要：

{
  "message": {
    "id": "msg_agent_01",
    "type": "ai",
    "content": "正在对销量口径做交叉核对……",
    "tool_calls": [],
    "name": "品牌竞争分析师",
    "additional_kwargs": {
      "report_collaboration": {
        "agentRunId": "agent_run_brand",
        "nodeRunId": "node_run_12",
        "phaseId": "phase_parallel_research",
        "sourceEventId": "as_evt_456"
      }
    }
  }
}

工具调用先在同一条 ai 消息的 tool_calls 上创建/追加参数 delta；返回值随后以 type: "tool"、相同 tool_call_id 的独立消息传输。允许用户查看的正文、参数和返回必须保持原文以及原始增量边界；只有统一脱敏器标记的字段可替换，替换理由写入 metadata。每个成员在开始生成时先发送 message.created，因此即使首 token 尚未到达，前端也能立即显示该成员正在回复，而非静默等待。

reasoning_delta 仅可承载经策略批准的、面向用户的工作说明（如“正在比对统计口径”），不允许桥接模型隐藏推理链、系统 prompt 或内部审稿思路；如模型未提供安全的公开工作说明，省略字段，过程可见性由 TeamSay、工具步骤、来源与普通 assistant 文本承担。

8. 分步实施计划

工单状态见 §0。本节正文仍是验收标准，不因部分完成而删减。

BE-0：AgentScope 兼容性尖峰

状态：条件完成（RC-BE-000）。 事件适配与 dict/真实事件单测已有；真实双模型流式与 uv.lock 仍属后续 POC。20 项标注评测与 20 次固定任务统计已在 RC-BE-018 落地。

先写实验和测试，不接前端，不建正式业务表。

验证：

当前 Python 3.12 与候选 agentscope==2.0.5 兼容；POC 通过后才将精确版本写入 lock，不能使用浮动 main。
验证单任务 worker 所需的 Agent、Tool、Event、Permission API；Agent Team 的自主调度与 Session SSE 不属于本功能的正确性依赖。
uv lock 后检查 Pydantic、SQLAlchemy、FastAPI、OpenAI SDK 冲突。
使用当前至少两个模型完成流式回复。
TaskLedger 分派 2 个并行 worker，完成可见 TeamSay、并发和结构化输出。
主动取消、超时、工具异常和成员异常行为可控。
AgentScope Event 可稳定关联 agent、task、message、tool call，并能一对一写出 LangChain 兼容的 assistant/tool 消息。
内存状态丢失后可由 DeerFlow task ledger/artifact 重建。
连续运行 20 次固定任务，统计早停、空输出、非法 JSON、事件缺失。
从首个 REPLY_START、TeamSay、tool-call start、tool result 到 token delta 的首个可见事件均在指定时限内到达 adapter；并行两个成员交错输出时不串 message ID 或 tool call ID，并能按前端既定 phase_id / node_run_id 聚焦。
人为注入流式中断、未闭合 tool call、等待用户输入与恢复场景；adapter 必须补发终态 tool result，不能留下永久 loading 的工具步骤。

交付：

AGENTSCOPE_BASELINE.md。
最小 team/model/tool/event adapter 测试。
Go/No-Go 结论。

Go 条件：

结构化输出达到 POC 阈值。
取消在预算时间内生效。
AgentScope 异常不会把任务误标完成。
业务恢复不依赖 AgentScope Python 对象。

BE-1：配置、依赖和总开关

状态：完成（RC-BE-002）。 enabled / worker_enabled 默认 false。

新增 config.yaml -> report_collaboration：

enabled
worker_enabled
planner_model
coordinator_model
research_model
writer_model
reviewer_model
max_team_members
max_parallel_tasks
max_repair_rounds
max_node_attempts
session_timeout_seconds
node_timeout_seconds
lease_seconds
heartbeat_seconds
event_retention_days
allowed_tools
source_policy
token_budget
cost_budget

要求：

默认关闭。
限制在服务端强制执行。
模型必须来自 AppConfig.models。
工具必须来自 allowlist。
AgentScope 依赖只加入应用 pyproject.toml。
离线 wheelhouse 和镜像在 knowledge-base-bj/deerflow-offline-deployment 更新，不提交到本业务仓库。

BE-2：领域合同和状态机

状态：完成（RC-BE-001）。

完成 Pydantic 合同：

requirement。
agent catalog projection。
role demand。
plan candidate/graph/validation。
node contract/status/attempt。
agent run（并行阶段的稳定成员身份、显示资料和状态）。
artifact schemas。
command intent/status。
event envelope。
report version/rewrite proposal。

测试所有非法状态迁移，尤其：

awaiting input 卡片出现后不能完成节点。
AgentScope reply 返回后无成果物不能完成节点。
cancelled 后晚到输出不能回写 completed。
completed 节点重开时必须产生新 attempt。

BE-3：迁移和持久化 Store

状态：完成（RC-BE-003）。 表前缀 report_collaboration_*，迁移 20260905_01。

任务：

创建数据库迁移。
实现 memory stores。
实现 SQL repositories。
注册 ORM 模型与 create_all。
在 app lifespan 注入 store。
完成 SQLite/MySQL/PostgreSQL 测试。

并发测试：

同一 idempotency key 只创建一条 command。
同一 session 只允许一个 active run。
两个 worker 不能同时领取同一 lease。
event seq 唯一且递增。
stale revision 返回 409。

BE-4：会话、消息和计划 API 骨架

状态：骨架完成（RC-BE-004）+ SSE 已挂载（RC-BE-011）+ 改写/恢复已挂载（RC-BE-015）。 REST 会话/消息/方案/run 已挂载；GET /runs/{id}/stream 为 durable SSE。

任务：

session CRUD 和用户隔离。
GET /sessions/{id} 一次返回前端 SessionSnapshot 的全部字段；run 前的澄清/规划阶段由该快照在 2.5 秒轮询内可见。
message 持久化：完整保存用户可见的 assistant、TeamSay、tool_calls 与 tool 返回，并保留 agent_run_id/node_run_id/phase_id；不只保存阶段摘要。
plan request 入队。
plan list/select。
run create/query。
OpenAPI 响应模型。
路由注册顺序和统一错误模型。
按 frontend-web/src/report-collaboration/api/types.ts 建立契约测试：字段名保持 snake_case，枚举、事件类型、命令确认/取消端点和 revision 头不可漂移。

安全：

不返回 agent 私有 SOUL 全文。
不返回模型密钥、base URL 和工具凭据。
计划卡只返回用户可见职责、能力和选择理由。

BE-5：需求解析和澄清

状态：完成（RC-BE-005）。 规则路径；尚未接规划用 LLM。澄清完成不会自动 plan-requests。

IntentRouterAgent（规划前模式）与 RequirementResolver：

读取会话消息和最新 requirement snapshot。
IntentRouterAgent 输出结构化需求提取、澄清判定或“可直接规划”判定；不得自行建图或启动任务。
RequirementResolver 校验并写入主题、目标、受众、范围、角度、模板和来源限制。
判断是否缺少真正影响方案选择的必要信息。
必要时产生一个或多个独立 clarification。
用户回答后创建新 requirement revision。
达到澄清上限后使用明确假设继续，不能无限追问。

验收：

只有主题的输入会询问真正影响报告的缺口。
用户明确说“直接开始”时记录默认假设。
clarification resolved 不等于 plan ready 或 node completed。

BE-6：智能体目录、筛选和候选计划

状态：完成（RC-BE-006）。 选择器为规则重排，未接规划模型。POST /plan-requests 在 worker_enabled=false 时于请求内同步生成方案（非 LLM）。

五阶段：

AgentCatalogProjection：读取用户可见且启用的 agent、技能和工具元数据。
AgentSelector：规则初筛并用模型重排，输出选择理由。
PlanController：生成 2～3 种策略的 RoleDemand 和角度。
PlanAssembler：绑定真实 agent、工具、预算、成果合同和质量门。
PlanValidator：校验 agent、tool、template、依赖、并发和预算。

默认策略：

balanced_review：完整研究、核验、分析、写作、审稿。
parallel_depth：更多并行角度和双重核验。
focused_fast：角色较少、范围较窄，但保留引用核验和审稿。

要求：

三种方案必须真实影响角色、范围、预算或质量门。
模型不能引用目录外 agent ID。
每个节点必须有成果类型和验收标准。
候选图无任意循环；返工由运行时台账表达。
方案保存 revision，选择和执行是两个独立命令。

BE-7：AgentScope 模型适配

状态：完成（RC-BE-007）。 适配器鸭子类型对齐 ChatModelBase.__call__；运行前冻结快照。真实 Provider 冒烟仍属 RC-BE-009 / 017。

目标：让 AgentScope 使用 DeerFlow 配置的模型，不再建立第二套 Provider 配置。

任务：

从 AppConfig.models 解析模型。
优先实现 AgentScope ChatModelBase adapter。
复用现有 Provider 超时、代理和密钥管理。
转换流式 text、tool call、usage 和错误。
记录每个 node attempt 的 token/费用。
模型不存在或能力不匹配时在 run 前失败。

约束：

prompt、事件和日志不出现密钥。
一次 run 的角色模型快照冻结，运行中不静默换模型。
模型 fallback 必须记录事件和审计。

BE-8：工具与权限适配

状态：完成（RC-BE-008）。

第一版允许：

Web 检索和正文获取。
用户有权限的知识库/Wiki 检索。
明确批准的只读技能/MCP。
成果物板读写工具。
用户可见交接（TeamSay）与受控成果物/澄清工具。

第一版默认禁止：

宿主文件系统直接访问。
任意代码执行。
任意 HTTP。
任意数据库写入。
运行期安装包或技能。

角色权限：

Researcher 不能发布报告。
Writer 不能把未核验证据改成已核验。
Reviewer 只能输出 ReviewDecision，不能覆盖报告。
Coordinator 只能提出受控的计划、澄清与修复建议；实际创建任务、分派、等待、返工和完成由 TaskLedger 服务执行。
所有成员获得本次 run 的最小权限快照。

验收：

每个角色有 allow/deny 测试。
工具结果携带 source ID。
网页 prompt injection 不能提升权限。
AgentScope 工具异常被转换为 node/tool event，不泄露内部堆栈给用户。

BE-9：受控任务成员运行器（不采用自治 Team 调度）

状态：完成（RC-BE-009 脚本内核 + RC-BE-013 质量角色内核）。 TaskLedger + WaveExecutor + QualityRoleKernel。真实 AgentScope reply_stream / web_search 仍待接。

基础角色：

Coordinator
Researcher
Verifier
Analyst
Synthesizer
Writer
Reviewer
Reviser

动态规则：

计划决定 Researcher/Analyst 数量和角度。
服务器限制团队人数、并发、attempt、返工和预算。
每个成员上下文只包含当前任务、需求快照和必要上游成果。
Coordinator 只接收结构化成果摘要、质量失败与用户命令影响，输出候选计划/修复建议；它不拥有自由消息总线或数据库权限。
TaskLedger 依据已验证成果、预算与并发限额逐波创建 AgentScope worker；AgentScope 不选择下一节点，也不决定任务完成。
每个 worker 只能调用 submit_artifact、request_clarification、request_repair、允许的资料工具和可见 TeamSay；所有改变运行状态的调用都由服务端重新校验。
任务完成由 QualityGate 判定，不接受文本声明。

事件映射：

AgentScope REPLY_* → 以原始文本 chunk 创建/更新协调者或成员的稳定 assistant 消息，保留 agentRunId；不得等待 reply 完成后再合成为进度摘要。
AgentScope TeamSay → 以成员身份创建/更新普通 assistant 消息，保留完整用户可见交接内容与因果顺序；它不会改变 ledger 状态。
MODEL_CALL_* → 内部遥测，默认不下发原始 prompt。
TOOL_CALL_* → 原生 ai.tool_calls 参数事件；对应工具返回 → 原生 tool 消息和相同 tool_call_id。两者在 SSE 和持久化中一一对应，供现有 MessageGroup 直接渲染。
TaskLedger 的分派/校验/重试/取消结果 → node/task ledger 状态；AgentScope 仅上报可验证的 TaskResult。
成果工具 → artifact created/validated/rejected。
每个用户可见阶段开始、进展、完成、等待、返工和失败都必须同步产生稳定的消息或状态事件，供左侧 DeerFlow MessageList 按原始消息顺序展示；不能要求前端读取节点结果后自行拼装过程，也不能用聚合卡替换 AgentScope 的实时可见消息。
agent run 的开始、等待输入、完成、失败和取消，紧邻节点状态事件发 session.snapshot 增量，至少包括相应的 agent_runs[] 和当前 run.current_phase。

验收：

成员失败可定向重试或替换，不直接完成整个 run。
空输出和非法 JSON 进入 repair attempt。
超过上限时给出明确失败/部分完成，不无限循环。

BE-10：成果物板与质量门

状态：完成（RC-BE-010）。 QualityGate 为确定性规则（无二次模型调用）。模板冻结快照与正式 ReportVersion 落库已在 RC-BE-015 落地。

ArtifactBoard：

按 run/node/attempt/type 保存成果。
保存 schema version、需求 revision、来源引用和 validation status。
只向下游提供 validated 成果。
返工保留旧成果并标记 superseded。

QualityGate：

CoverageMatrix：把需求中的每个必选角度/关键问题映射到证据目标、分析节点和模板章节；计划和最终版本均不可漏项。
EvidenceBundle：按主张级保存 claim_id、来源 URL/文档 ID、发布/获取时间、原文摘录、事实或推断标签、适用范围、数值单位/口径、可信度与去重结果。
VerificationResult：对关键主张给出支持与反对证据、冲突、时效、来源独立性和可用结论；数字及重要事实必须经此门。
AngleAnalysis：结论只能引用验证过的 evidence ID，必须分别标示事实、推断、假设、局限和资料缺口。
ReportSectionDraft：关键事实和数字必须有 evidence ID；章节的主张与引用一一可追溯。
CitationTemplateLinter：校验模板章节、必答问题、来源格式、数字/日期/实体一致性、不可用或过期来源和未引用的关键事实。
ReviewDecision：独立于 Writer 上下文运行，问题必须有目标、严重度、证据和修复要求；不能笼统地要求“整体再优化”。
ReportVersion：覆盖矩阵、引用、模板、章节衔接、结论一致性和正式版本持久化全部通过才可创建。

验收：

无成果、空成果和不合 Schema 的成果不能完成节点。
未验证来源不能直接进入最终事实陈述。
Reviewer 的返工目标可映射到具体节点和章节。
同一事实出现冲突或同一数字缺少口径时，QualityGate 必须拒绝或要求定向补证，不能由 Writer 擅自选择一个答案。

BE-11：后台 Dispatcher、租约和恢复

状态：完成（RC-BE-012）。 worker_enabled 默认仍为 false：Gateway lifespan 只有 enabled 且 worker_enabled 同时为真才 dispatcher.start()。测试走 dispatch_once() / executor.execute()，不要依赖后台循环。

复用现有成熟模式：

active-dedupe key。
dispatcher 原子 claim。
executor heartbeat。
cancel watcher。
两阶段取消。
lease 失效接管。
durable event + live hub。

恢复：

读取 requirement、selected plan、task ledger。
保留已验证且未失效成果。
将遗留 running attempt 标为 interrupted。
为未完成任务创建新 attempt。
重建 AgentScope team。
注入必要成果和协调摘要。
从下一批 ready task 继续。

验收：

杀死 worker 后可接管。
已完成节点不重复检索和计费。
worker 丢失 lease 后停止本地模型与工具链。
cancel 后晚到结果只可保存为 superseded，不改变终态。

BE-12：SSE 和 Live Hub

状态：完成（RC-BE-011）。 ConversationReplica 已实现协议镜像；产品 SSE 经 execution/live_hub.py 挂载。报告正式版本写入已在 RC-BE-015 落地。

任务：

实现 event repository。
实现 run-scoped live hub。
实现历史分页和 SSE replay。
支持 heartbeat、after_seq、Last-Event-ID。
短暂存储读取异常时保持连接。
将高频 token delta 合帧。
建立 ConversationReplica：将 AgentScope 用户可见消息、TeamSay、assistant delta、tool_calls、tool 返回、协助请求、报告文件和领域状态写成可重放的统一消息事件。它是协议镜像而不是摘要生成器。
对话镜像完整保留用户有权查看的 TeamSay、原始工具参数和返回；不包含 chain-of-thought、系统/内部 prompt、密钥、权限不可见内容和异常堆栈。脱敏在入库/下发前一次执行，不能由前端自行推断。
对前端已支持的 reasoning_delta，仅推送由本系统生成或模型明确允许公开的短工作说明；它不等同于原始思维链，也不得用作质量门、调度或审计的唯一依据。
agentRunId 是并行消息流的稳定归属。Live Hub 始终发布所有成员事件；前端标签切换只在本地选择消息，不启动第二条运行流，也不取消未聚焦成员的 delta。

验收：

重连不丢 durable event。
重复连接不重复执行业务命令。
终态前报告正式版本已写入并可读。
SSE 断开不取消后台 run。
仅依靠会话快照和事件重放即可重建每个成员的完整原生消息、工具过程和左侧聚焦视图，不需要调用节点结果接口。
在模型/工具中断、取消和接管时，所有已开始的 tool call 都有对应的 completed tool result（成功、失败或 interrupted），不会让复用的 MessageList 永久显示执行中。

BE-13：全过程命令与影响分析

状态：完成（RC-BE-014）。 app/report_collaboration/interventions/ 已实现运行期 IntentRouterAgent、ImpactAnalyzer 和 RuntimeCommandService；SQL/memory store 通过 patch_command(..., expected_statuses=...) 对命令执行权做 CAS。置信度阈值由 report_collaboration.intent_confirmation_threshold 配置（默认 0.8）。

实现边界：本票负责识别、授权、影响计算、确认、定向失效、overlay 和安全重排队。rewrite_section / polish_report 已能严格保留研究链并只返工写作/审校链；replacement candidate、正式版本 apply/restore 已在 RC-BE-015 落地。add_angle 优先使用用户定向的研究分支，否则按冻结计划顺序确定性选择一个研究分支，只接入其必要下游；无研究支路立即 rejected。rerun_node 没有合法目标时不得扩成整图。需求补丁只在返工成功后写入。卡住的 executing 可在接管或租约超时后收回。command.cancelled 进入 SSE。运行中 POST /sessions/{id}/messages 返回 409。

IntentRouterAgent（运行中干预模式）输入：

用户文本。
session/run 状态。
requirement revision。
当前选中节点或章节上下文。
后端动作白名单。

先由规则层处理明确的回答、取消和节点/章节显式指令；其余由 IntentRouterAgent 输出：

intent
confidence
target_type
target_ids[]
normalized_instruction
requires_confirmation
cost_level
reason

模型输出必须通过 Pydantic 校验，并经服务端 target 授权与置信度/成本闸门后才创建可执行 command；IntentRouterAgent 不可调用分派、取消、成果写入或报告版本工具。

命令类型：

answer_question
update_requirements
add_angle
research_again
reanalyze
rerun_node
rewrite_section
polish_report
ask_report
replan
cancel

ImpactAnalyzer：

answer_question：只解析相应的 clarification；仅解锁依赖该答案的节点，其他并行节点继续。
research_again：为指定节点/角度追加或替换 EvidenceBundle，失效其验证、分析、综合和受影响章节，不误伤无关角度。
reanalyze：保留 validated evidence，只失效指定分析、综合、写作和审校分支。
add_angle：在当前冻结计划中选择一个明确目标或确定性的研究支路承接新角度，再只失效其必要下游；无可用支路时拒绝执行。运行中不暗改前端已选择的 DAG，真正新增画布节点只发生在后续重新规划产生的新 plan revision 中。
rerun_node：以新 attempt 重跑指定节点及必要下游，旧结果保留为 superseded。
rewrite_section：保留研究/分析，只生成 replacement candidate 和该章节审校；用户 apply 后才产生新版本。
polish_report：不重检索；在当前正式版本上创建新版本，并再次执行模板/引用 lint。
update_requirements / replan：均先展示整图影响与高成本确认；前者写入新的 requirement revision 后重开冻结计划，后者重开当前计划全部节点。生成新候选 plan/run branch 的交互留在后续规划版本能力，不能在旧 run 的 SSE 内偷偷切换 run。
ask_report：只读取当前已验证成果或报告版本，不改变任务图。

Safe-point：

可取消的当前工具调用先停止。
不可立即取消的 attempt 继续到边界，command 状态为 accepted_waiting_boundary。
晚到输出可保存但标记 superseded，不能进入下游。
每条 command 有分类、影响范围、状态和结果。
command overlay 仅在模型调用之间、工具返回后或节点提交成果前生效；在不可中断工具期间不能伪称已经完成修改。

验收：

低置信度“改一下”必须追问。
相同幂等键不重复创建返工任务。
运行中命令不能造成 completed/cancelled 状态竞争。
用户针对画布/成员卡的定向修改只影响解析出的节点和成果血缘，不能被协调者扩大为整场重跑。

BE-14：报告模板、写作、审稿和版本

状态：完成（RC-BE-015）。 改写 / apply / restore 已挂载；正式版本在质量门通过后落库。

复用 /api/report-structures，run 开始时冻结模板快照：

章节层级。
每章目标与必答问题。
必需表格/对比维度。
语气、语言、篇幅。
检索方向与允许技能。
引用格式。

写作规则：

Writer 只能使用冻结模板、CoverageMatrix 和 validated artifacts，禁止携带 Web/知识库工具或原始检索上下文进入写作提示词。
关键判断绑定 evidence ID；无法证实的内容明确标为分析、假设或局限。
每章获得确定 evidence set、字数目标和必答问题，输出章节草稿及主张—引用映射。
完整报告先执行 CitationTemplateLinter，再由独立 Reviewer 进行事实、逻辑、受众适配和结论审校。
Reviewer 输出结构化 ReviewDecision；Reviser 只修改指定问题，并由同一质量门复验。
达到返工上限后报告未解决问题，不无限循环。

版本规则：

流式 Markdown 是临时草稿，不覆盖当前正式版本。
正式版本须在所有质量门通过后落库，随后才发 report.version.created 并令 run completed。
章节改写生成 replacement candidate。
用户 apply 后创建新版本。
restore 也创建新头版本，不破坏历史。

BE-15：安全、审计和预算

状态：完成（RC-BE-016）。 快照与 SSE 走统一脱敏；资源 owner、跨会话幂等、预算上限与审计已落地。

所有资源校验 owner 或明确授权。
agent snapshot 移除密钥和不可见 prompt。
工具参数/结果完整镜像到用户消息流；只有密钥、令牌、隐私字段、越权内容和明确的异常堆栈由统一脱敏器替换并记录原因。不能以大小截断或摘要替代用户有权查看的返回；超大返回以可重放 chunk 传输和按需折叠展示，正文仍可完整读取。
外部内容全部视为不可信资料。
每用户 active run 上限。
每 run 团队、并发、检索、来源正文、模型调用、token、费用和总时长上限。
审计 agent 选择、工具调用、来源、用户命令、人工确认和报告版本。
不持久化、不下发原始 chain-of-thought、系统/内部 prompt 或模型隐藏推理 token；前端可显示的 reasoning_delta 必须是经过独立策略筛选的公开工作说明。这不影响用户可见 assistant 文本、TeamSay、工具调用与工具返回的完整镜像。

BE-16：测试与质量评测

状态：完成（RC-BE-018）。 合同 / 适配器 / 规划 / 需求 / SSE / lease / 20 项标注评测集已有。打分器不调用模型；金标必须过门，会商风失败实例必须可复现。

单元测试：

Pydantic 合同。
计划装配和验证。
task ledger 状态机。
artifact validation。
dependency invalidation。
intent router 高成本闸门。
AgentScope event adapter。
同一 message_id 的 token delta、同一 tool_call_id 的参数/结果 delta 以及脱敏字段替换；断线重放后消息正文不得被摘要化或重复。
两个 agentRunId 并行交错输出、其中一员等待用户协助时，消息归属、工具配对、状态和命令目标均正确。
session.snapshot 增量 agent_runs[] 能驱动前端阶段卡从 pending → running → waiting_input → terminal；node_run_id 与画布节点前缀匹配。
流式中断后每个已创建 tool call 都有终态 tool result，MessageList 不留下旋转步骤。

集成测试：

fake model 下完整研究、核验、分析、写作、审稿、返工。
用户协助卡提交后仍需成果校验。
早停、空输出、非法 JSON、无引用。
模型和工具超时。
SSE replay、取消和 worker 崩溃接管。
从 REPLY_START 到首条消息、从 TOOL_CALL_START 到原生工具步骤、从工具返回到 tool 消息的可见时延；不得等待节点完成才出现过程。

真实 AgentScope 冒烟：

至少两个已配置模型。
ledger 驱动的多 worker（不依赖 AgentScope Team 自动分派）。
并发工具和 TeamSay。
取消、超时、异常成员和结果修复。

质量评测集：

不少于 20 个真实任务。
覆盖政策影响、市场趋势、企业研究、事件研判、对比分析。
每个任务记录必选角度、关键事实、禁止编造项、模板和评审规则。
与现有多智能体会商进行盲评，并保留每项失败的可复现实例。
指标：事实准确、来源质量、关键主张引用覆盖、角度覆盖、逻辑一致、模板遵循、定向修改正确率、耗时和成本。
上线前为每个任务标注关键主张/数字、可接受来源、必选角度和模板约束；不能只以主观“文章更像报告”判定成功。

9. 首个纵向 POC

POC-1 的规则路径已通（三策略差异方案、select ≠ start）。POC-2 脚本闭环已通（研究员 → 撰写员，协调者建议不调度）。POC-3 质量角色已通（核验 / 分析 / 审稿定向返工，确定性内核）。真实检索与 AgentScope 成员仍待接。POC-4 未开始。

固定任务：

撰写一份新能源汽车主要品牌市场趋势分析报告，覆盖 2024 年至今的市场份额、价格策略、技术路线、海外进展、政策环境和未来 12～24 个月风险与机会，面向企业战略决策人员，要求所有关键数字给出来源。

POC-1：候选计划

状态：规则路径已通（RC-BE-006）。 三策略差异方案、select ≠ start；尚未接规划 LLM。

生成 3 种真实有差异的方案。
每个方案只引用有效 agent/tool/template。
每个节点有职责、输入、输出和验收条件。
选择方案不开始，显式 run 命令才开始。

POC-2：三角色闭环

状态：脚本路径已通（RC-BE-009），SSE 重放已挂载（RC-BE-011）。 真实 Web 检索仍待工具实装接入运行器。

角色：Coordinator、Researcher、Writer。

完成真实 Web 检索。
形成 EvidenceBundle。
生成带来源报告。
durable event 可驱动前端流程图。
每位成员的 TeamSay、流式文本、工具调用和工具返回可由同一 SSE 流重放，并能按 agentRunId 还原。

POC-3：质量角色

状态：完成（RC-BE-010 质检 + RC-BE-013 受控成员 + RC-BE-017 真实内核）。 QualityRoleKernel 跑通 Verifier / Analyst / Writer / Reviewer / Reviser；过期与跨包冲突写入 VerificationResult；缺失角度只重开检索链；审稿失败只重开目标写作节点。生产 worker 使用 AgentScopeMemberKernel。

加入 Verifier、Analyst、Reviewer、Reviser。

过期资料被识别。
冲突资料被标记。
缺失角度触发定向补充。
报告未通过评审时只返工目标节点。

POC-4：全过程干预

状态：命令与 safe-point 路径完成（RC-BE-014）。 增加角度、指定角度重检索、章节重写/润色的定向影响已覆盖；运行中旧 attempt 在边界后 supersede，晚到成果不能进入下游。正式报告 replacement/version 展示已在 RC-BE-015 落地。

必须演示：

“增加供应链与原材料风险角度”。
“海外市场资料太旧，重新检索 2026 年最新信息”。
“重写第二章，结论更谨慎，不要重新检索”。
刷新页面后继续。
取消时晚到输出不改变终态。
worker 崩溃后租约接管。

10. 后端开发顺序

已完成：

RC-BE-000：AgentScope 版本与兼容性尖峰（条件 Go；未写入 uv.lock）。
RC-BE-001：领域合同和状态机。
RC-BE-002：配置、依赖和 feature flag。
RC-BE-003：数据库迁移和 stores。
RC-BE-004：session/message/plan API（改写 / 恢复见 015）。
RC-BE-005：需求解析与澄清。
RC-BE-006：agent catalog、selector、plan assembler/validator。
RC-BE-007：AgentScope model adapter。
RC-BE-008：tool/permission adapter。
RC-BE-009：三角色 team POC（脚本内核 + TaskLedger 波次）。
RC-BE-010：artifact board 主张级质量门（Coverage / 核验 / 审稿）。
RC-BE-011：durable event、原生消息镜像、SSE 和 live hub。
RC-BE-012：dispatcher、executor、lease、cancel、recovery。
RC-BE-013：Verifier/Analyst/Reviewer/Reviser。
RC-BE-014：intent router、impact analyzer、safe-point commands（已完成）。
RC-BE-015：report structures、report versions、rewrite candidates（已完成）。
RC-BE-016：安全、审计、预算、监控（已完成）。
RC-BE-017：并发、故障恢复和真实 AgentScope 测试（已完成）。
RC-BE-018：20 项质量评测和参数调优（已完成）。

下一票起：

RC-BE-019：灰度与离线发布接入。

编号说明：§8 的 BE-n 与上表 RC-BE-00n 在 008 之后不完全一一对应（例如 §8 BE-11 dispatcher ≈ RC-BE-012，BE-12 SSE ≈ RC-BE-011）。排期与代码以 RC-BE-* 为准。

前后端共同依赖：OpenAPI / event envelope / 共享枚举已按 frontend-web/src/report-collaboration/api/types.ts 冻结；前端页面与 mock 已完成。真实 SSE 可联调 GET /runs/{id}/stream（RC-BE-011）；领取/恢复见 RC-BE-012；质量角色见 RC-BE-013；运行中自然语言命令见 RC-BE-014。正式报告改写候选与版本 apply/restore 已在 RC-BE-015 挂载。生产默认仍不挂后台循环（worker_enabled=false）。

11. 上线质量门

11.1 功能门

任一协助卡不会完成节点。
任一 assistant 短消息不会完成 run。
每个完成节点都有 validated artifact。
每条用户反馈都有 durable command。
每个正式报告都有已持久化版本。

11.2 质量门

关键事实引用覆盖率达到评测目标。
引用可打开对应来源。
过期、冲突、低可信来源可识别。
必选角度覆盖。
Reviewer 问题可映射到返工节点。
模板章节完整。
不生成来源中不存在的数字、事件或观点归属。

11.3 可靠性门

command、run create、cancel 幂等。
SSE 重连不丢事件。
worker 崩溃可接管。
cancelled 不被晚到结果改写。
正式报告不被失败的流式草稿覆盖。
PostgreSQL/MySQL 并发测试通过。

11.4 决策门

质量盲评必须证明新方案相对现有会商在报告质量或交互效率上有明确提升。若没有提升，不以“AgentScope 已接入”作为上线理由。

12. 风险与应对

12.1 AgentScope API 快速变化

固定版本和 commit；所有上游对象通过 adapter；升级必须跑兼容性尖峰和真实任务评测。

12.2 Agent Team 可靠性不足

状态、完成条件、重试和恢复由 DeerFlow TaskLedger/ArtifactBoard 管理；AgentScope 负责协作，不决定业务终态。

12.3 多智能体成本高但质量不提升

按复杂度控制团队规模；快速方案也保留核验/审稿；以评测指标而不是 agent 数量验收。

12.4 智能体互相传话失真

TeamSay 不作为事实来源；报告事实只能引用 validated EvidenceBundle。

12.5 全过程对话产生状态竞争

反馈先落 durable command；使用 revision、幂等键、safe-point、依赖失效和 superseded 输出。

12.6 进程恢复后上下文不一致

不恢复 Python 对象；从需求、计划、台账、成果和协调摘要重建 AgentScope team。

12.7 离线依赖缺失

业务仓库只维护依赖锁与代码；wheelhouse、镜像和发布脚本统一进入离线发布仓库。

13. 后端完成定义

后端只有同时满足以下条件才算完成：

使用 AgentScope 2.0 Core 执行真实的受控任务成员，且由 DeerFlow TaskLedger 而非自治 Team 调度协作。
不调用旧 Workflow Studio DAG scheduler。
不改变现有多智能体会商行为。
DeerFlow 数据库是状态唯一事实源。
成果物校验而不是模型文本决定节点完成。
规划、检索、分析、核验、写作、审稿、返工、错误和报告变化均可由同一对话时间线完整重建。
节点公开接口只提供职责合同和状态，不向前端暴露执行结果面板所需数据。
全过程用户反馈能准确分类、定向失效和安全生效。
规划、运行、等待、返工、取消和报告版本均有 durable event。
刷新、断线、worker 崩溃和租约接管后可恢复。
模型、工具、资料、用户和报告权限不被 AgentScope 绕过。
报告完成前已持久化正式版本并通过质量门。
真实质量评测达到上线阈值。
离线依赖和部署验证在独立发布仓库完成。

64 KiB Raw Permalink Blame History Unescape Escape