0 Fork 0

Files

T

2026-09-02 14:57:34 +08:00

39 KiB

Raw Blame History

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

文档状态：待评审、尚未开始编码编写日期：2026-09-02 目标项目：F:\react01\deeflow-code\deerflow-server\offline-backend-20260512\backend 协作框架：AgentScope 2.0 配套前端计划：docs/agentscope-多智能体报告协作工作台-前端实施计划.md 本文只规划新增的报告协作后端，不修改现有多智能体会商，不使用旧 Workflow Studio DAG 调度器。

1. 后端目标

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

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

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

2. 关键架构决策

2.1 使用 AgentScope Core，不采用演示服务作为事实源

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

因此采用：

AgentScope Core：Agent、Team、Tool、Event、Permission。
DeerFlow：身份、权限、配置、数据库、消息、命令、作业、租约、SSE、成果、文件、报告版本和审计。
AgentScope Event 既驱动运行状态，也通过无损 adapter 转为 DeerFlow 领域事件和 LangChain 兼容消息；其用户可见内容不能在 adapter 中被压缩为进度摘要。
不运行 AgentScope examples/web_ui。
不把 AgentScope Session、MessageBus 或内存对象作为恢复依据。
节点公开接口只返回职责合同、图关系和状态，不返回节点实际输出；实际阶段消息、工具过程和成果仍从会话消息流以原生消息、工具步骤、引用和报告文件卡的形式呈现。

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 流程图不是执行器

候选图和运行图用于：

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

真正调度由 Coordinator + TaskLedger + ArtifactBoard + QualityGate 完成。协调者只能从服务端允许的动作中选择，不能返回任意 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 --> AS[AgentScope Core]
    AS --> LEAD[Coordinator]
    AS --> TEAM[Research/Verify/Analyze/Write/Review Team]

    EXEC --> LEDGER[Task Ledger]
    EXEC --> BOARD[Typed Artifact Board]
    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 和旧成果。

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`	节点尝试	node_id、attempt、status、contract_json、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、schema_version、content_json、validation_status
`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，同一事件流仍全量持久化；前端选择标签只能过滤/聚焦，不能影响事件写入或消息顺序。
删除 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}/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

写请求必须支持：

idempotencyKey
expectedRevision

计划请求和 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 delta 可 live-only 合帧，但需周期性保存可恢复 checkpoint。
不能每 token 写数据库。
状态、成果、命令和报告版本必须 durable。
读取事件暂时失败时保持连接并发送可恢复 warning。

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 尚未到达，前端也能立即显示该成员正在回复，而非静默等待。

8. 分步实施计划

BE-0：AgentScope 兼容性尖峰

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

验证：

当前 Python 3.12 与稳定 AgentScope 2.x 兼容。
固定精确版本和 commit，不使用浮动 main。
uv lock 后检查 Pydantic、SQLAlchemy、FastAPI、OpenAI SDK 冲突。
使用当前至少两个模型完成流式回复。
leader + 2 workers 完成任务分配、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。

交付：

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

Go 条件：

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

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

新增 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：领域合同和状态机

完成 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

任务：

创建数据库迁移。
实现 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 骨架

任务：

session CRUD 和用户隔离。
message 持久化：完整保存用户可见的 assistant、TeamSay、tool_calls 与 tool 返回，并保留 agent_run_id/node_run_id/phase_id；不只保存阶段摘要。
plan request 入队。
plan list/select。
run create/query。
OpenAPI 响应模型。
路由注册顺序和统一错误模型。

安全：

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

BE-5：需求解析和澄清

RequirementResolver：

读取会话消息和最新 requirement snapshot。
提取主题、目标、受众、范围、角度、模板和来源限制。
判断是否缺少影响方案选择的必要信息。
必要时产生一个或多个独立 clarification。
用户回答后创建新 requirement revision。
达到澄清上限后使用明确假设继续，不能无限追问。

验收：

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

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

五阶段：

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 模型适配

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

任务：

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

约束：

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

BE-8：工具与权限适配

第一版允许：

Web 检索和正文获取。
用户有权限的知识库/Wiki 检索。
明确批准的只读技能/MCP。
成果物板读写工具。
AgentScope 团队通信与任务工具。

第一版默认禁止：

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

角色权限：

Researcher 不能发布报告。
Writer 不能把未核验证据改成已核验。
Reviewer 只能输出 ReviewDecision，不能覆盖报告。
Coordinator 只能通过受控工具创建任务、分派、等待、返工和建议完成。
所有成员获得本次 run 的最小权限快照。

验收：

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

BE-9：AgentScope Team 运行器

基础角色：

Coordinator
Researcher
Verifier
Analyst
Synthesizer
Writer
Reviewer
Reviser

动态规则：

计划决定 Researcher/Analyst 数量和角度。
服务器限制团队人数、并发、attempt、返工和预算。
每个成员上下文只包含当前任务、需求快照和必要上游成果。
Coordinator 不直接操作数据库，只调用 TaskLedger/ArtifactBoard 工具。
任务完成由 QualityGate 判定，不接受文本声明。

事件映射：

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

验收：

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

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

ArtifactBoard：

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

QualityGate：

EvidenceBundle：来源数量、日期、URL/文档 ID、摘录和去重。
VerificationResult：支持与反对证据、冲突、时效。
AngleAnalysis：结论必须引用验证过的 evidence ID。
ReportSectionDraft：关键事实和数字必须有引用。
ReviewDecision：问题必须有目标、严重度和修复要求。
ReportVersion：模板覆盖、引用完整、章节一致、正式版本已持久化。

验收：

无成果、空成果和不合 Schema 的成果不能完成节点。
未验证来源不能直接进入最终事实陈述。
Reviewer 的返工目标可映射到具体节点和章节。

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

复用现有成熟模式：

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

任务：

实现 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、密钥、权限不可见内容和异常堆栈。脱敏在入库/下发前一次执行，不能由前端自行推断。
agentRunId 是并行消息流的稳定归属。Live Hub 始终发布所有成员事件；前端标签切换只在本地选择消息，不启动第二条运行流，也不取消未聚焦成员的 delta。

验收：

重连不丢 durable event。
重复连接不重复执行业务命令。
终态前报告正式版本已写入并可读。
SSE 断开不取消后台 run。
仅依靠会话快照和事件重放即可重建每个成员的完整原生消息、工具过程和左侧聚焦视图，不需要调用节点结果接口。

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

IntentRouter 输入：

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

输出：

intent
confidence
target_type
target_ids[]
normalized_instruction
requires_confirmation
cost_level
reason

命令类型：

answer_question
update_requirements
add_angle
research_again
reanalyze
rerun_node
rewrite_section
polish_report
ask_report
replan
cancel

ImpactAnalyzer：

重新检索：失效指定 EvidenceBundle 和引用它的下游。
重新分析：保留 evidence，失效分析和对应章节。
章节重写：保留研究/分析，只生成 replacement candidate。
语气润色：创建新报告版本，不失效事实成果。
全局改向：新建 plan revision，确认后创建 run branch。

Safe-point：

可取消的当前工具调用先停止。
不可立即取消的 attempt 继续到边界，command 状态为 accepted_waiting_boundary。
晚到输出可保存但标记 superseded，不能进入下游。
每条 command 有分类、影响范围、状态和结果。

验收：

低置信度“改一下”必须追问。
相同幂等键不重复创建返工任务。
运行中命令不能造成 completed/cancelled 状态竞争。

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

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

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

写作规则：

Writer 只能使用 validated artifacts。
关键判断绑定 evidence ID。
无法证实的内容明确标为分析、假设或局限。
每章获得确定 evidence set。
完整报告执行引用、模板、衔接和结论一致性检查。
Reviewer 输出结构化 ReviewDecision。
Reviser 只修改指定问题。
达到返工上限后报告未解决问题，不无限循环。

版本规则：

流式 Markdown 是临时草稿，不覆盖当前正式版本。
正式版本落库并确认后 run 才能 completed。
章节改写生成 replacement candidate。
用户 apply 后创建新版本。
restore 也创建新头版本，不破坏历史。

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

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

BE-16：测试与质量评测

单元测试：

Pydantic 合同。
计划装配和验证。
task ledger 状态机。
artifact validation。
dependency invalidation。
intent router 高成本闸门。
AgentScope event adapter。
同一 message_id 的 token delta、同一 tool_call_id 的参数/结果 delta 以及脱敏字段替换；断线重放后消息正文不得被摘要化或重复。
两个 agentRunId 并行交错输出、其中一员等待用户协助时，消息归属、工具配对、状态和命令目标均正确。

集成测试：

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

真实 AgentScope 冒烟：

至少两个已配置模型。
leader + 多 worker。
并发工具和 TeamSay。
取消、超时、异常成员和结果修复。

质量评测集：

不少于 20 个真实任务。
覆盖政策影响、市场趋势、企业研究、事件研判、对比分析。
每个任务记录必选角度、关键事实、禁止编造项、模板和评审规则。
与现有多智能体会商进行盲评。
指标：事实准确、来源质量、角度覆盖、逻辑一致、格式遵循、可修改性、耗时和成本。

9. 首个纵向 POC

固定任务：

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

POC-1：候选计划

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

POC-2：三角色闭环

角色：Coordinator、Researcher、Writer。

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

POC-3：质量角色

加入 Verifier、Analyst、Reviewer、Reviser。

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

POC-4：全过程干预

必须演示：

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

10. 后端开发顺序

RC-BE-000：AgentScope 版本与兼容性尖峰。
RC-BE-001：领域合同和状态机。
RC-BE-002：配置、依赖和 feature flag。
RC-BE-003：数据库迁移和 stores。
RC-BE-004：session/message/plan API。
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。
RC-BE-010：task ledger、artifact board、quality gate。
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：灰度与离线发布接入。

前后端共同依赖：在 RC-BE-001 后冻结 OpenAPI、event envelope 和共享枚举，前端再开始真实 API 层开发。

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

39 KiB Raw Blame History Unescape Escape