Files
deerflow-code/frontend-web/docs/microsoft-agent-framework-多智能体会商-实施计划.md
T
董宏凯andCursor e690475e6e feat(maf-roundtable): add Phase-1 multi-agent roundtable infrastructure
Ship an independent, feature-flag-gated MAF roundtable skeleton with six
isolated tables, atomic single-transaction run launch/cancel, owner-scoped
read/write split, shared config enums, and HTTP/concurrency regression tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-01 01:07:05 +08:00

47 KiB
Raw Blame History

Microsoft Agent Framework 多智能体会商对照页实施计划

文档状态:实施中;阶段 1(独立后端骨架与持久化)已验收通过
更新时间:2026-08-01
目标版本:实验性独立功能,不替换现有多智能体会商
建议页面名称:MAF 会商(实验)

0. 当前实施状态与前后端隔离决议

0.1 已完成并验收的阶段 1

新的后端骨架已经独立落在 /api/maf-roundtable 及 maf_roundtable_* 专用表中;会话、运行、事件、审批、用户隔离、启动/取消原子事务与配置校验均不复用旧会商的持久化状态。当前验收证据为:78 项 MAF 后端回归测试通过,且 Harness → App 导入边界检查通过。

阶段 1 完成并不表示功能已对用户开放:maf_roundtable.enabled 继续默认关闭,直到后续 MAF 编排和新前端页面均完成验收。

0.2 新前端页面的强制隔离原则

后续前端必须新建一套 MAF 会商页面,仅调用新后台 /api/maf-roundtable/*;不得把新页面接到旧会商 API,也不得为了复用 UI 而修改旧会商的状态机、草稿、运行记录或路由行为。

允许复用通用 UI 基础组件(按钮、Dialog、Tabs、SSE 基础设施、鉴权请求客户端),但以下模块只能作为只读参考,禁止修改其业务代码或直接共用其业务状态:

  • 旧 RoundtablePlanningPage 及 roundtable-planning/**;
  • /api/roundtable-*、/api/multi-agent/* 及其草稿/作业接口;
  • 任务深链会商、岗位会商和现有多智能体会商的页面、store、hooks;
  • roundtable_jobs、roundtable_drafts、roundtable_task_drafts 及旧会商事件流。

新页面的唯一数据源是 MAF 专用 API 与 MAF 专用表;新旧会商之间如需做效果对照,只能通过显式的只读对照记录或导出的指标关联,不能共享运行状态。

1. 结论

本项目可以接入 Microsoft Agent Framework(以下简称 MAF),新增一套独立的多智能体会商页面,并且保留真实的工具调用、技能调用、MCP、沙箱文件写入和外部系统写入能力。

本方案不把 Microsoft Samples 示例应用整体嵌入 DeerFlow,而是使用 MAF 的 Agent/Workflow/Group Chat 能力负责多智能体编排;每个业务席位的实际执行优先复用现有 DeerFlow Agent Runtime。这样能够同时满足以下目标:

  • 原有会商页面、API、任务、草稿、后台作业和数据库表保持原行为。
  • MAF 页面拥有独立路由、独立 API、独立会话和独立事件记录。
  • 现有 Agent 配置中的工具组、技能、MCP、模型、沙箱和用户权限继续生效。
  • 外部写入不是演示占位,而是正式执行能力。
  • 可以在同模型、同提示词、同任务和同能力条件下比较两种编排方式。

2. 范围与边界

2.1 本期必须实现

  • 新页面:/page/strategy/qa/maf-roundtable。
  • 两种 MAF 编排模式:
    • structured:专家并行分析 → 交叉审查 → 主持人综合。
    • group_chat:主持人动态选择下一位发言人,多轮讨论后收敛。
  • 支持从现有 Agent 列表选择主持人和参会席位。
  • 支持现有模型配置,包括 OpenAI 兼容端点。
  • 支持每个席位使用其已有工具组和技能白名单。
  • 支持内置工具、MCP 工具、技能脚本、沙箱产物和外部系统写入。
  • 支持工具过程、技能过程、审批过程、会商发言和最终结果的实时事件流。
  • 支持后台执行、刷新恢复、断线续传、取消和失败重试。
  • 支持查看外部写入结果、调用参数摘要、执行人、执行时间和审计状态。
  • 支持与现有会商的结果指标进行人工或半自动对比。

2.2 本期不做

  • 不替换现有 RoundtablePlanningPage。
  • 不迁移现有 roundtable_jobs、草稿或历史记录。
  • 不把 MAF 依赖放进 deerflow.* 核心 Harness 的 Agent 编排层。
  • 不在第一期制作自由拖线式工作流编辑器。
  • 不在生产业务对象上同时执行两套会商的重复写操作;真实写入对照使用 UAT、测试租户或隔离业务命名空间。

2.3 “不改原有”的工程定义

允许在公共入口增加受特性开关保护的路由注册和菜单入口,但不得改变旧功能的状态机、API 请求体、数据库表、任务恢复逻辑或页面交互。

以下旧链路必须保持兼容:

  • /api/roundtable-*
  • /api/multi-agent/*
  • roundtable_jobs
  • roundtable_drafts
  • roundtable_task_drafts
  • /page/strategy/qa/multi-agent-roundtable
  • 任务深链下的三个原会商入口

2.4 新前端与新后台的对接边界

新前端页面固定使用独立路由 /page/strategy/qa/maf-roundtable,并且只允许请求以下新接口前缀:

GET  /api/maf-roundtable/health
POST /api/maf-roundtable/sessions
GET  /api/maf-roundtable/sessions
GET  /api/maf-roundtable/sessions/{session_id}
PUT  /api/maf-roundtable/sessions/{session_id}
POST /api/maf-roundtable/sessions/{session_id}/runs
GET  /api/maf-roundtable/sessions/{session_id}/runs
GET  /api/maf-roundtable/runs/{run_id}
POST /api/maf-roundtable/runs/{run_id}/cancel
GET  /api/maf-roundtable/runs/{run_id}/events
GET  /api/maf-roundtable/runs/{run_id}/actions
GET  /api/maf-roundtable/runs/{run_id}/approvals
POST /api/maf-roundtable/approvals/{approval_id}/decision

其中事件写入没有公开 HTTP 接口;只有后续后端 Workflow 执行器可以通过内部服务写入事件。前端不得使用 mock 事件、不得伪造工具、技能、审批或外部写入事件。

3. 核心架构决策

3.1 采用“MAF 编排 + DeerFlow 席位执行”

MAF 负责:

  • 工作流拓扑。
  • 发言人选择。
  • 轮次与终止条件。
  • 群聊上下文同步。
  • 并行、审查和综合流程。
  • Workflow checkpoint 与恢复。

DeerFlow Agent Runtime 负责:

  • 读取 Agent 的 SOUL、模型、工具组和技能白名单。
  • 注入技能说明和运行上下文。
  • 调用内置工具、MCP、ACP、沙箱和子智能体工具。
  • 文件产物生成。
  • 用户身份、记忆、视觉、循环检测、工具错误处理等现有中间件。
  • 外部 API、外部业务系统和其他有副作用工具的实际执行。

不建议第一版把 LangChain BaseTool 逐个改造成 MAF 原生工具。现有工具中存在 ToolRuntime、线程、用户、沙箱和中间件依赖,直接包装容易产生“工具能调用,但身份或沙箱上下文丢失”的隐性问题。

第一版应实现一个 DeerFlowAgentAdapter:MAF 把一次席位发言交给适配器,适配器通过进程内 ASGI 调用现有 thread/run stream,完整消费 DeerFlow SSE,再转换成统一的 MAF 会商事件。

3.2 公平对照原则

要比较的是“多智能体编排方式”,而不是模型、提示词或工具实现差异。因此同一组对照实验必须冻结:

  • 模型与推理参数。
  • 任务正文、附件和补充材料。
  • 主持人和席位 Agent。
  • 每个 Agent 的 SOUL、技能和工具权限。
  • 最大轮次、单次超时和总预算。
  • 外部写入模式与目标环境。
  • 最终输出结构和验收规则。

3.3 新功能隔离结构

flowchart LR
    UI["MAF 会商实验页"] --> API["/api/maf-roundtable"]
    API --> SVC["MAF Roundtable Service"]
    SVC --> WF["MAF Workflow / GroupChatBuilder"]
    WF --> MGR["主持人 Agent"]
    WF --> A1["席位 Agent Adapter A"]
    WF --> A2["席位 Agent Adapter B"]
    WF --> A3["席位 Agent Adapter C"]
    A1 --> DF["DeerFlow Thread / Run Stream"]
    A2 --> DF
    A3 --> DF
    DF --> CAP["工具 + 技能 + MCP + 沙箱 + 外部写入"]
    SVC --> DB["独立 MAF 会商表"]
    SVC --> EVT["事件流与审计"]

4. 运行流程

4.1 创建会商

  1. 用户进入 MAF 会商(实验)。
  2. 输入任务、选择模型、主持人、参会 Agent 和编排模式。
  3. 前端读取每个 Agent 当前可用的工具组和技能,并展示能力摘要。
  4. 用户选择外部写入策略:
    • auto:按现有用户权限直接执行所有已授权写操作。
    • confirm_high_risk:普通写入自动执行,高风险写入等待确认。
    • confirm_all_writes:所有外部写入均等待确认。
  5. 后端创建 MAF session,并冻结本次 capability_snapshot。
  6. 后端为主持人和每个席位创建或绑定独立 DeerFlow thread。

4.2 执行会商

  1. MAF 生成下一步调度决策。
  2. 被选中的席位收到:用户任务、完整或裁剪后的会商上下文、自己的角色要求和当前阶段目标。
  3. DeerFlowAgentAdapter 发起席位 run。
  4. 席位可真实调用工具、技能、MCP、沙箱和外部写入。
  5. 工具与技能事件实时写入 maf_roundtable_events,并推送给前端。
  6. 席位完成后,标准化为 AgentResponse 返回 MAF。
  7. MAF 决定下一席位、进入审查、请求用户确认或结束会商。
  8. 主持人生成结构化最终结论和执行记录。

4.3 暂停与恢复

出现以下情况时进入 waiting_approval 或 waiting_input:

  • 工具声明需要审批。
  • 外部写入策略要求审批。
  • Agent 主动请求澄清。
  • MAF 工作流触发人工参与节点。

恢复时必须从持久化 checkpoint 和最后一个事件序号继续,不允许重新执行已经成功的外部写入。

5. 编排模式设计

5.1 固定流程 structured

flowchart LR
    T["任务"] --> P["计划与分工"]
    P --> E1["专家 A"]
    P --> E2["专家 B"]
    P --> E3["专家 C"]
    E1 --> R["交叉审查"]
    E2 --> R
    E3 --> R
    R --> F["主持人综合"]
    F --> O["结论 + 行动 + 产物 + 外部写入记录"]

实现要求:

  • 专家阶段允许并行。
  • 并行席位各用独立 DeerFlow thread 和独立沙箱。
  • 每个席位允许使用工具、技能和外部写入。
  • 并行写同一个外部对象时由 Action Coordinator 串行化,不通过禁用写工具规避冲突。
  • 专家输出必须通过 Pydantic/JSON Schema 校验。
  • 校验失败允许一次定向修复;再次失败则保留原文并标记 schema_invalid,不得无限重试。
  • 审查阶段显式检查证据、冲突、遗漏、工具失败和外部写入结果。

5.2 动态群聊 group_chat

使用 MAF GroupChatBuilder,由主持人或确定性 selector 选择下一位发言人。

实现要求:

  • 默认最大 8 个席位回合,可配置但设置硬上限。
  • 默认最多连续选择同一席位 2 次。
  • 终止条件同时包含:主持人判定完成、结构化结果通过校验、最大回合到达、总超时到达。
  • 每个席位在发言前同步会商上下文,但长工具输出只传摘要与引用,不广播完整二进制或超长日志。
  • 工具执行结果必须进入共享事实账本,避免后续席位把未经执行的提议当作已执行事实。
  • 主持人也可以使用其 Agent 配置中已授权的工具和技能,不做框架级禁用。

5.3 共享事实账本

群聊文本不能作为外部动作成功与否的唯一依据。新增 fact_ledger,记录:

  • 已确认事实。
  • 信息来源与证据引用。
  • 工具调用结果。
  • 已执行外部写入。
  • 等待确认的动作。
  • 失败或状态不确定的动作。
  • Agent 之间尚未解决的冲突。

主持人生成结论时必须以账本状态为准。

6. 工具、技能与外部写入

6.1 工具接入

工具能力不在 MAF 页面统一裁剪。每个席位继承其现有 Agent 配置和当前登录用户权限,包括:

  • config.yaml 配置工具。
  • DeerFlow 内置工具。
  • MCP 工具。
  • ACP Agent 工具。
  • 文件、搜索、浏览器、图像、记忆和计划任务工具。
  • Agent 已获授权的子智能体工具。

能力快照至少包含:

{
  "agent_id": "example-agent",
  "model_name": "configured-model",
  "tool_groups": ["search", "business-api"],
  "tools": [
    {"name": "search", "schema_hash": "...", "source": "builtin"},
    {"name": "update_task", "schema_hash": "...", "source": "mcp"}
  ],
  "skills": [
    {"name": "example-skill", "version": "...", "content_hash": "..."}
  ]
}

快照用于审计和复现,不代表运行期间复制工具实例。

6.2 技能接入

  • 继续使用 Agent 当前技能白名单。
  • 默认 Agent 沿用现有“可见全部已启用技能”的规则。
  • skill_list、skill_view、search_skills 和技能脚本按当前配置生效。
  • 如果启用了技能演进,skill_manage 也允许执行,但其写入必须进入 MAF 审计事件。
  • 会商启动时记录技能内容哈希;会商中途技能被修改时,当前 run 继续使用启动快照,新 run 才读取新版本。
  • 技能脚本产生的文件必须归属当前席位 sandbox,并通过产物清单暴露给其他席位。

6.3 外部写入接入

外部写入是正式能力,不使用全局 excluded_tools 将其移除。为了在多智能体并发下正确执行,需要增加 Action Coordinator。

Action Coordinator 只负责执行一致性,不替代工具:

  • 生成幂等键:session_id + run_id + agent_id + tool_name + logical_action_id。
  • 同一业务对象的写操作按 target_key 加租约锁并串行执行。
  • 工具声明幂等时才允许自动网络重试。
  • 工具未声明幂等且响应状态不明时,标记 unknown 并进入人工核验,不盲目重放。
  • 支持工具返回 external_object_id、before_digest、after_digest 和可选补偿动作。
  • 认证凭据只在服务端解析,不进入模型消息、会商历史或前端事件正文。
  • 日志中的令牌、密码、Cookie、Authorization 和敏感字段必须脱敏。

建议写入风险级别:

等级 示例 auto confirm_high_risk
R0 读取 查询、搜索、读取附件 自动 自动
R1 本地写入 席位沙箱文件、草稿 自动 自动
R2 可逆外部写入 更新测试任务、写入可回退记录 自动 自动
R3 高影响写入 发送消息、生产数据变更、发布 自动,但要求用户显式选择 auto 等待确认
R4 破坏性操作 删除、覆盖且无补偿、批量变更 等待确认 等待确认

这套分级不禁止外部写入,而是保证它在不同运行策略下可控、可恢复、可审计。

6.4 沙箱与产物冲突

  • 一个席位一个 thread,一个 thread 一个沙箱上下文。
  • 席位可正常使用写文件、脚本和产物工具。
  • 不允许多个席位直接共享同一可写目录。
  • 汇总阶段通过只读产物清单读取各席位交付。
  • 最终发布由主持人或指定发布席位写入会商级产物目录。
  • 同名产物使用 agent_id/revision/path 做唯一定位。

7. 后端目录与文件计划

建议新增:

offline-backend-20260512/backend/
├─ app/
│  ├─ gateway/routers/
│  │  └─ maf_roundtable.py
│  └─ maf_roundtable/
│     ├─ __init__.py
│     ├─ schemas.py
│     ├─ service.py
│     ├─ workflow_factory.py
│     ├─ model_client.py
│     ├─ deerflow_agent_adapter.py
│     ├─ event_normalizer.py
│     ├─ context_builder.py
│     ├─ fact_ledger.py
│     ├─ action_coordinator.py
│     ├─ approval_service.py
│     └─ metrics.py
├─ packages/harness/deerflow/persistence/maf_roundtable/
│  ├─ __init__.py
│  ├─ model.py
│  └─ sql.py
└─ tests/
   ├─ test_maf_roundtable_api.py
   ├─ test_maf_roundtable_workflow.py
   ├─ test_maf_agent_adapter.py
   ├─ test_maf_action_coordinator.py
   ├─ test_maf_approval_resume.py
   └─ test_maf_roundtable_isolation.py

边界规则:

  • app.maf_roundtable 可以导入 deerflow.*。
  • deerflow.* 不得导入 app.* 或 MAF SDK。
  • deerflow.persistence.maf_roundtable 只保存纯数据模型,不依赖 MAF SDK。
  • MAF SDK 只在 app.maf_roundtable 内加载。
  • app.py 只增加 router 注册和生命周期初始化,不改变旧 router。

8. 数据模型

8.1 maf_roundtable_sessions

建议字段:

  • id
  • user_id
  • title
  • task_text
  • task_payload_json
  • mode:structured | group_chat
  • status:draft | running | waiting_approval | waiting_input | completed | failed | cancelled
  • model_name
  • reasoning_effort
  • manager_agent_id
  • max_rounds
  • write_policy
  • capability_snapshot_json
  • fact_ledger_json
  • final_result_json
  • created_at
  • updated_at

8.2 maf_roundtable_participants

  • id
  • session_id
  • agent_id
  • display_name
  • role
  • sort_order
  • thread_id
  • sandbox_id
  • status
  • last_turn_index
  • capability_snapshot_json

8.3 maf_roundtable_runs

  • id
  • session_id
  • status
  • workflow_version
  • maf_checkpoint_json 或 checkpoint 引用
  • last_event_seq
  • started_at
  • finished_at
  • error_code
  • error_message_safe
  • token_usage_json
  • latency_ms

8.4 maf_roundtable_events

  • id
  • session_id
  • run_id
  • seq
  • event_type
  • agent_id
  • turn_index
  • payload_json
  • created_at

唯一约束:(run_id, seq)。

8.5 maf_roundtable_actions

  • id
  • session_id
  • run_id
  • agent_id
  • tool_name
  • logical_action_id
  • idempotency_key
  • target_key
  • risk_level
  • status
  • arguments_redacted_json
  • result_redacted_json
  • external_object_id
  • approval_id
  • attempt_count
  • started_at
  • finished_at

唯一约束:idempotency_key。

8.6 maf_roundtable_approvals

  • id
  • session_id
  • run_id
  • action_id
  • requested_by_agent_id
  • status:pending | approved | rejected | expired
  • summary
  • payload_redacted_json
  • decided_by
  • decided_at
  • expires_at

9. API 设计

统一前缀:/api/maf-roundtable。

9.0 契约状态与前端接入顺序

阶段 1 已实现的前端可用基线是会商 CRUD、启动/查询/取消 run、轮询补拉 GET /runs/{run_id}/events、动作查询、审批查询与审批决定,准确路径见 2.4。新前端第一版必须只调用这些已落地接口,并以事件轮询补拉作为恢复机制。

/stream、/resume、/input、对照接口、动作人工核验/补偿接口属于后续编排阶段契约;在对应后端任务验收前,前端不得预先调用、伪造或为其创建兼容旧会商的降级路径。接口新增必须保持在 /api/maf-roundtable/* 前缀内。

9.1 会话

  • POST /sessions:创建会商。
  • GET /sessions:会商列表。
  • GET /sessions/{session_id}:会商详情。
  • PUT /sessions/{session_id}:修改未运行配置。
  • DELETE /sessions/{session_id}:删除草稿或归档记录。

9.2 执行

  • POST /sessions/{session_id}/runs:启动新 run。
  • GET /runs/{run_id}:读取运行状态。
  • GET /runs/{run_id}/events?after_seq=N:断线补拉事件。
  • GET /runs/{run_id}/stream?after_seq=N:SSE 实时订阅。
  • POST /runs/{run_id}/cancel:取消。
  • POST /runs/{run_id}/resume:从 checkpoint 恢复。
  • POST /runs/{run_id}/input:提交澄清内容。

9.3 审批和动作

  • GET /runs/{run_id}/approvals:待处理审批。
  • POST /approvals/{approval_id}/decision:批准或拒绝。
  • GET /runs/{run_id}/actions:外部写入和工具动作清单。
  • GET /actions/{action_id}:单次动作详情。
  • POST /actions/{action_id}/reconcile:状态不明动作的人工核验。
  • POST /actions/{action_id}/compensate:执行工具声明的补偿操作。

9.4 对比

  • POST /comparisons:绑定一个 MAF run 与一个原会商 run。
  • GET /comparisons/{comparison_id}:获取对比指标。

9.5 统一事件格式

{
  "seq": 42,
  "event": "tool.completed",
  "session_id": "...",
  "run_id": "...",
  "agent_id": "risk-reviewer",
  "turn_index": 3,
  "timestamp": "2026-07-31T10:00:00Z",
  "payload": {
    "tool_name": "update_task",
    "action_id": "...",
    "status": "succeeded",
    "summary": "已更新测试任务状态"
  }
}

首期事件类型至少包括:

  • run.started
  • run.status_changed
  • workflow.checkpointed
  • manager.decision
  • agent.turn_started
  • agent.message.delta
  • agent.message.completed
  • skill.selected
  • skill.started
  • skill.completed
  • tool.requested
  • tool.started
  • tool.progress
  • tool.completed
  • tool.failed
  • action.waiting_approval
  • action.approved
  • action.rejected
  • artifact.created
  • fact.recorded
  • run.completed
  • run.failed

10. 前端设计

10.0 独立前端模块、路由和状态

新增目录固定为 frontend-web/src/maf-roundtable/,其 API client 只能封装 /api/maf-roundtable/*。新页面根组件为 MafRoundtablePage.tsx,路由仅新增 /page/strategy/qa/maf-roundtable;不得替换、重命名、迁移或修改旧 multi-agent-roundtable 路由及其页面组件。

入口展示前先读取 GET /api/maf-roundtable/health:enabled=false 时隐藏入口并禁止创建会商;开启后页面必须明确展示“实验版 / 独立后端”标识。TanStack Query 的 key 使用独立命名空间,例如 ['maf-roundtable', 'sessions', ...],不得复用任何旧 roundtable、draft 或 job key。所有页面本地状态、事件 reducer、轮询/补拉游标、取消控制器和历史恢复逻辑也必须归属于 MAF 模块。

前端只能消费新后台写入的事件;不得为联调重新开放公开 mock 写接口,也不得在浏览器端伪造工具、技能、审批或外部写入事件。

建议新增:

frontend-web/src/maf-roundtable/
├─ api/
│  └─ maf-roundtable.ts
├─ components/
│  ├─ MafRoundtableSetup.tsx
│  ├─ ParticipantRail.tsx
│  ├─ DiscussionTimeline.tsx
│  ├─ AgentTurnCard.tsx
│  ├─ CapabilitySnapshot.tsx
│  ├─ ToolExecutionCard.tsx
│  ├─ SkillExecutionCard.tsx
│  ├─ ExternalActionCard.tsx
│  ├─ ApprovalCard.tsx
│  ├─ FactLedgerPanel.tsx
│  ├─ FinalDecisionPanel.tsx
│  └─ ComparisonPanel.tsx
├─ hooks/
│  ├─ useMafRoundtableSession.ts
│  ├─ useMafRoundtableStream.ts
│  └─ useMafRoundtableActions.ts
├─ lib/
│  ├─ event-reducer.ts
│  ├─ schemas.ts
│  └─ metrics.ts
└─ pages/
   └─ MafRoundtablePage.tsx

10.1 页面布局

  • 顶部:实验标识、模型、编排模式、轮次上限、写入策略、启动/暂停/取消。
  • 左侧:主持人与参会席位,展示运行状态、当前发言者、工具数和技能数。
  • 中部:统一时间线,依次展示发言、调度、工具、技能、审批和产物事件。
  • 右侧:事实账本、外部动作、产物和运行指标。
  • 底部或结果页:最终结论、共识、分歧、执行动作、失败动作和证据引用。

10.2 页面必须明确展示的内容

  • 当前使用的是 MAF,而不是原会商。
  • 当前编排模式及终止条件。
  • 每个席位真实启用的工具和技能。
  • 哪个 Agent 请求了外部写入。
  • 写入是否已执行、等待审批、失败或状态不明。
  • 最终报告中的“建议动作”和“已实际执行动作”必须分栏,避免混淆。
  • 刷新后从数据库事件恢复,不依赖 React 内存保存运行状态。

11. 分步实施

11.0 难度定义与分配原则

本文使用 D1–D5 标记开发难度。难度表示任务对工程能力的要求,不代表工作量,也不直接等于最终代码评分。

难度 能力要求 典型任务 适合人员
D1 入门 能按明确样例修改,影响面很小 文案、静态展示、简单配置 初级开发,在指导下完成
D2 基础 能独立完成单模块 CRUD 或普通组件 路由、表单、简单 API、类型定义 初级偏上或一般开发
D3 中等 能处理完整模块、异常和测试 Store、指标、普通流式接口、SDK Spike 中级开发
D4 较难 涉及并发、状态恢复、跨层契约或安全 SSE reducer、权限隔离、工作流、离线交付 中高级开发
D5 核心 涉及框架适配、一致性、不可重复副作用 Agent Adapter、checkpoint、幂等外部写入 高级开发或技术负责人

任务分配时遵守以下规则:

  • 每个任务包只设一名主负责人,其他人通过评审协作,避免责任不清。
  • D4/D5 任务必须提交设计说明、测试证据和失败场景说明,不能只交代码。
  • 不建议让同一位同事同时负责“外部写入实现”和“该模块最终验收”,需要交叉评审。
  • 为了评价个人水平,每个人应使用独立分支和独立提交,避免多人混在一个提交中。
  • 公共入口文件由集成人统一合并;任务开发者不要各自反复修改 app.py、StrategyRoutes.tsx 和菜单文件。
  • 代码评价同时记录任务难度、独立完成度和返工次数,不能只比较总代码量。

阶段 0:依赖与模型连通性 Spike

阶段难度:D3(中等)
建议负责人:熟悉 Python 依赖、异步 SDK 和模型网关的后端开发
前置依赖:无
主要评价点:能否用最小代码验证关键假设,并识别 SDK/模型/离线环境的真实限制

任务:

  • MAF-00-01(D2)确认并固定 MAF Python 包版本,禁止使用浮动版本。
  • MAF-00-02(D2)在独立临时环境安装,不先修改生产锁文件。
  • MAF-00-03(D3)使用当前一个 OpenAI Chat Completions 兼容模型跑通流式单 Agent。
  • MAF-00-04(D3)使用同一模型跑通两个 Agent 的最小 Group Chat。
  • MAF-00-05(D3)验证自定义 base_url、API key、超时和代理配置。
  • MAF-00-06(D4)验证 MAF 的 stream event、checkpoint、cancel 和 resume 接口。
  • MAF-00-07(D4)验证实现 DeerFlowAgentAdapter 所需的 Agent/ChatClient 扩展接口。
  • MAF-00-08(D3)收集 Linux CPython 3.12 所需 wheel,执行离线安装测试。

退出标准:

  • 模型能流式返回。
  • 两个 Agent 能完成至少两轮群聊。
  • 能保存并恢复 checkpoint。
  • 离线环境可以仅使用 wheelhouse 安装。
  • 形成版本锁定记录;如果 SDK API 与 Samples 不一致,以锁定版本实际 API 为准。

阶段 1:独立后端骨架与持久化

阶段难度:D4(较难)
建议负责人:熟悉 FastAPI、SQLAlchemy、鉴权和事件流的中高级后端开发
前置依赖:阶段 0 版本锁定
主要评价点:数据隔离、事件顺序、权限边界、事务处理和可测试性

任务:

  • MAF-01-01(D2)新增 MAF router、service 目录和健康检查。
  • MAF-01-02(D3)新增六张独立数据表及 store。
  • MAF-01-03(D3)在 Gateway lifespan 中初始化 store,并处理初始化失败。
  • MAF-01-04(D2)增加 maf_roundtable.enabled 特性开关。
  • MAF-01-05(D3)实现会话 CRUD、参与者配置和 capability snapshot。
  • MAF-01-06(D4)实现单调递增的事件序号、并发写入和事件补拉 API。
  • MAF-01-07(D4)增加用户隔离、越权测试和管理员诊断权限。

退出标准:

  • 可以创建、读取、更新、归档 MAF 会话。
  • MAF 表和旧 roundtable 表完全无关联外键。
  • 关闭特性开关后不加载 MAF SDK,不显示入口。
  • test_harness_boundary.py 通过。

阶段 2:DeerFlow Agent Adapter

阶段难度:D5(核心)
建议负责人:熟悉 LangGraph/Agent Runtime、SSE、异步取消和本项目中间件链的高级后端开发
前置依赖:阶段 0、阶段 1
主要评价点:是否真正保留工具/技能/身份/沙箱语义,事件转换是否完整,取消和异常是否泄漏资源

任务:

  • MAF-02-01(D3)为每个席位创建、绑定和恢复独立 DeerFlow thread。
  • MAF-02-02(D4)使用 httpx.ASGITransport(app=request.app) 进程内调用现有 API。
  • MAF-02-03(D4)注入当前用户 Authorization 和有效 user context,并证明不存在跨用户泄漏。
  • MAF-02-04(D3)透传 model、thinking、reasoning effort、agent id、subagent 等运行参数。
  • MAF-02-05(D3)保持 Agent 原工具组和技能规则,不传统一 excluded_tools。
  • MAF-02-06(D4)把 MAF 群聊上下文转换成有边界、可裁剪、可追踪的席位输入。
  • MAF-02-07(D5)解析 DeerFlow SSE,正确转换消息、工具、技能、产物、澄清和错误事件。
  • MAF-02-08(D4)将席位最终消息转换为 MAF 标准响应并保留 usage/metadata。
  • MAF-02-09(D5)实现 MAF 取消、超时、客户端断开时的 DeerFlow run 联动取消和资源回收。

退出标准:

  • 一个 MAF 席位能真实调用一个只读工具。
  • 能执行技能并生成沙箱产物。
  • 能调用一个测试环境外部写工具。
  • 前端/接口能看到完整事件顺序。
  • 原 Agent 单聊行为不受影响。

阶段 3:固定流程编排

阶段难度:D4(较难)
建议负责人:熟悉异步工作流、结构化输出和失败恢复的中高级后端开发
前置依赖:阶段 2
主要评价点:并行正确性、结果校验、部分失败处理、checkpoint 可恢复性

任务:

  • MAF-03-01(D4)建立任务规划、并行专家、交叉审查和最终综合节点。
  • MAF-03-02(D3)实现席位输出 Pydantic schema 和可读错误信息。
  • MAF-03-03(D3)实现一次定向格式修复及停止条件。
  • MAF-03-04(D4)建立共享事实账本及证据/动作状态约束。
  • MAF-03-05(D4)实现并行 barrier、部分失败、超时和降级综合。
  • MAF-03-06(D4)将 MAF checkpoint 持久化到 run。
  • MAF-03-07(D5)实现服务重启后的恢复,并证明已完成节点不会重复执行。

退出标准:

  • 三个席位可并行执行真实工具和技能。
  • 某一席位失败时,其余席位结果不丢失。
  • 主持人能区分建议动作与已执行动作。
  • 重启后不会重放已成功的外部动作。

阶段 4:动态 Group Chat

阶段难度:D5(核心)
建议负责人:熟悉多智能体编排、上下文工程和终止状态机的高级开发
前置依赖:阶段 2;建议先完成阶段 3 以复用事实账本和恢复机制
主要评价点:弱模型条件下能否收敛、上下文是否准确、硬终止是否可靠

任务:

  • MAF-04-01(D3)使用 GroupChatBuilder 建立主持人和参与席位。
  • MAF-04-02(D4)实现确定性 selector 与主持人 Agent selector 两种选择方式。
  • MAF-04-03(D4)实现最大轮次、连续发言限制、总超时和单席位超时。
  • MAF-04-04(D5)实现完整上下文同步、长工具输出裁剪、引用保真和 token 预算。
  • MAF-04-05(D4)实现主持人完成判定、schema 校验和结构化终稿。
  • MAF-04-06(D3)把主持人调度原因写入 manager.decision 事件。
  • MAF-04-07(D5)构造弱模型不结束、错误选人、重复发言等测试并保证工作流可收敛。

退出标准:

  • 可以观察每轮由谁发言以及选择原因。
  • 达成结论时提前结束。
  • 弱模型未正确发出结束信号时,硬终止条件仍能停止。
  • 工具结果不会因上下文裁剪而被误判为未执行或执行成功。

阶段 5:外部写入、审批与一致性

阶段难度:D5(核心且高风险)
建议负责人:熟悉分布式一致性、幂等、事务、审计和业务安全的高级后端开发/技术负责人
前置依赖:阶段 1、阶段 2、阶段 3 的 checkpoint 机制
主要评价点:不得重复写、不得越权、状态不明时不得盲目重试、所有动作必须可追踪

任务:

  • MAF-05-01(D3)建立工具风险元数据、默认分类和覆盖规则。
  • MAF-05-02(D3)实现 auto、confirm_high_risk、confirm_all_writes 策略解析。
  • MAF-05-03(D5)实现 Action Coordinator、唯一幂等键、状态机和目标租约锁。
  • MAF-05-04(D5)实现审批暂停、决策、checkpoint 恢复及过期处理。
  • MAF-05-05(D5)实现网络结果未知时的核验流程与可选补偿动作。
  • MAF-05-06(D4)实现凭据、参数、结果和异常日志脱敏,并编写泄漏测试。
  • MAF-05-07(D3)实现审计查询页面所需 API。
  • MAF-05-08(D5)实现并发/重启/重复事件故障注入测试,证明外部写入不会重复。

退出标准:

  • 外部写入可以实际成功执行。
  • 重复事件、断线恢复和服务重启不会造成重复写入。
  • 并行 Agent 写同一目标时不会互相覆盖。
  • 高风险写入在相应策略下能暂停和恢复。
  • 每个外部动作可追溯到用户、会商、run、Agent 和工具调用。

阶段 6:前端工作台

阶段难度:D4(较难)
建议负责人:熟悉 React、TanStack Query、SSE 状态归并和复杂工作台交互的中高级前端开发
前置依赖:阶段 1 已验收的 API 基线与正式事件契约;reducer 可使用本地 fixture 开发,但不得依赖公开 mock 事件接口;可与阶段 2–5 并行开发
主要评价点:事件状态准确、刷新恢复、审批交互、复杂状态下 UI 不误导用户

任务:

  • MAF-06-00(D4)新建 MAF 专属目录、独立 query key、独立路由与 feature-flag 入口;确认旧会商页面、hooks、store、草稿与路由零改动。
  • MAF-06-01(D2)新增路由、菜单、特性开关和实验标识。
  • MAF-06-02(D3)实现创建会商、模型配置和席位选择。
  • MAF-06-03(D2)实现 MAF 两种模式及写入策略切换。
  • MAF-06-04(D5)实现支持断线、补拉、去重和乱序保护的 SSE reducer。
  • MAF-06-05(D3)实现 Agent、工具、技能和外部动作时间线卡片。
  • MAF-06-06(D4)实现审批卡片、澄清输入及并发操作防重。
  • MAF-06-07(D3)实现事实账本、最终结论和产物展示。
  • MAF-06-08(D4)实现取消、恢复、失败重试及对应状态禁用逻辑。
  • MAF-06-09(D4)实现刷新恢复、历史列表和跨页面返回。
  • MAF-06-10(D3)为 reducer 和关键交互编写前端测试。

退出标准:

  • 刷新、切页、重新登录后能恢复当前运行。
  • 工具和技能调用过程可见。
  • 外部写入状态不会仅显示在聊天文本中。
  • 原会商页面视觉和交互没有变化。

阶段 7:对比评测

阶段难度:D3(中等)
建议负责人:具备数据分析意识、理解 Agent 错误分类的全栈/测试开发/算法工程师
前置依赖:阶段 3、阶段 4;指标接口可提前开发
主要评价点:对照是否公平、指标是否可解释、是否能区分模型/工具/编排错误

任务:

  • MAF-07-01(D3)建立同任务、同模型、同能力的配置快照与一致性校验。
  • MAF-07-02(D2)支持绑定原会商 run 与 MAF run。
  • MAF-07-03(D3)采集完成率、格式通过率、轮次、时延、token 和工具成功率。
  • MAF-07-04(D4)建立模型错误、工具错误、编排错误、外部系统错误分类器。
  • MAF-07-05(D3)采集错误工具调用、重复写入、错误写入和人工介入次数。
  • MAF-07-06(D2)增加盲评表:正确性、完整性、可执行性、分歧处理和证据质量。
  • MAF-07-07(D3)准备不少于 10 个包含工具、技能和写入的真实业务测试任务。

对照环境规则:

  • 两套系统使用同一模型和能力快照。
  • 外部写入使用 UAT、测试租户或不同命名空间。
  • 不允许两套实验同时修改同一个生产业务对象。
  • 对比报告必须标注模型错误、工具错误、编排错误和外部系统错误,不能全部归因于框架。

阶段 8:测试、离线打包与灰度

阶段难度:D4(较难)
建议负责人:熟悉自动化测试、Linux 离线部署、故障注入和上线观测的测试开发/DevOps/后端开发
前置依赖:各功能阶段完成;离线依赖验证可在阶段 0 后提前进行
主要评价点:测试有效性、环境可复现、是否真正覆盖恢复和副作用故障

任务:

  • MAF-08-01(D4)补齐后端单元测试、API 集成测试和并发测试。
  • MAF-08-02(D3)完成前端 typecheck、组件测试和关键 E2E。
  • MAF-08-03(D3)跑现有 roundtable、position-roundtable 和 task deep-link 回归。
  • MAF-08-04(D4)构建 Linux CPython 3.12 多平台离线 wheel 集合。
  • MAF-08-05(D4)使用 --no-index --find-links 做全新环境安装与启动验证。
  • MAF-08-06(D3)配置管理员/白名单用户灰度和回退开关。
  • MAF-08-07(D4)建立失败率、恢复率、重复动作数、事件积压和数据库增长观测。

退出标准:

  • 旧会商回归全部通过。
  • 离线部署可重复完成。
  • 外部写入重复执行数为 0。
  • 所有写操作都有审计记录。
  • MAF 功能可通过开关独立关闭。

12. 测试矩阵

12.1 必测成功场景

  • 单席位调用内置读取工具。
  • 多席位并行调用不同工具。
  • 席位发现并执行技能。
  • 技能生成文件并被主持人引用。
  • MCP 读取与 MCP 写入。
  • 外部写操作成功并返回业务对象 ID。
  • 主持人调用自身授权工具。
  • 中途澄清后继续。
  • 高风险操作审批后继续。
  • 服务重启后从 checkpoint 继续。

12.2 必测失败场景

  • 模型超时、限流和返回空消息。
  • 弱模型不遵守输出 schema。
  • Agent 连续选择自己或无限讨论。
  • 工具参数错误。
  • 工具超时但外部系统可能已成功。
  • MCP 服务断开。
  • 技能脚本失败。
  • 用户在等待审批时取消。
  • SSE 断线、事件重复和乱序。
  • 两个 Agent 同时更新同一目标。
  • 用户 A 读取或恢复用户 B 的 session。

12.3 回归场景

  • 原多智能体会商创建、运行、后台恢复和报告。
  • 岗位会商页面。
  • 任务深链三类业务会商。
  • 普通 Agent 单聊的工具、技能和产物。
  • MCP 初始化与工具搜索。
  • Harness → App import firewall。

13. 验收指标

13.1 硬性指标

  • 外部写入重复执行:0。
  • 未授权跨用户读取:0。
  • 未记录的外部写入:0。
  • 旧会商接口契约变化:0。
  • 关闭特性开关后旧功能行为变化:0。
  • 每个 run 均可根据事件记录解释“谁在何时调用了什么”。

13.2 效果指标

  • 结构化结果一次通过率。
  • 会商完成率。
  • 工具调用成功率。
  • 技能任务完成率。
  • 外部写入正确率。
  • 人工澄清次数。
  • 每任务总轮次、总时延和 token。
  • 最终结论中无依据断言数量。
  • 盲评胜率和评审一致性。

不预先设定“MAF 必须胜出”。如果 MAF 只在特定任务或特定模型上更好,应保留两种方案并按业务类型选择。

14. 风险与处理

风险 影响 处理
MAF SDK API 仍快速变化 示例与实际版本不一致 阶段 0 固定版本;集中封装 SDK;业务层不直接依赖 SDK 类型
当前模型只部分兼容 OpenAI 协议 流式、tool call 或 structured output 失败 分别验证 Chat Completions、流式工具调用和 schema;必要时增加模型适配层
群聊广播导致上下文膨胀 成本高、弱模型更易偏航 工具输出摘要、事实账本、轮次硬上限和上下文预算
多 Agent 重复外部写入 业务数据污染 幂等键、目标锁、动作状态机、核验和补偿
直接包装 LangChain 工具丢失运行上下文 身份、沙箱或线程错误 第一版通过 DeerFlow AgentAdapter 执行,不逐个直包工具
后台恢复重放工具 重复副作用 action 表先落意图,幂等执行,恢复时先查动作状态
技能运行时被更新 结果不可复现 会商启动冻结技能哈希和能力快照
两套系统对比污染生产数据 无法公平比较且可能产生副作用 使用 UAT/测试租户/隔离命名空间

15. 发布与回退

  • 配置项 maf_roundtable.enabled 控制后端 API 与前端入口。
  • 首期仅管理员或指定白名单可见。
  • 关闭入口时,已有运行可选择继续完成或管理员取消。
  • 回退只需关闭特性开关和停止新 MAF jobs;旧 roundtable 不需要迁移或回滚。
  • MAF 独立表保留用于审计,不在代码回退时删除。
  • MAF SDK 使用延迟导入,关闭功能时不影响 Gateway 启动。

16. 推荐开发顺序与工作量级

建议严格按以下顺序推进:

  1. 依赖/模型/离线 wheel Spike。
  2. 独立 session、event 和 SSE 骨架。
  3. DeerFlow AgentAdapter,先跑通真实工具、技能和一次外部写入。
  4. 固定流程编排。
  5. 动态 Group Chat。
  6. Action Coordinator、审批和恢复。
  7. 前端完整工作台。
  8. 对比评测、回归和灰度。

在熟悉当前代码的前提下,这是一个中等偏大的完整功能,建议按 3 个可演示里程碑交付:

  • 里程碑 A:后端命令/API 能完成两席位 MAF 会商,真实工具与技能可用。
  • 里程碑 B:页面可运行、可查看工具/技能/产物,外部写入可审批和恢复。
  • 里程碑 C:固定流程和 Group Chat 都可用,完成与原会商的正式对比报告。

16.1 推荐人员任务包

以下任务包适合分给不同同事。一个人可以领取多个连续任务包,但应避免多人同时拥有同一公共模块。

任务包 内容 综合难度 建议角色 可并行条件
WP-A 阶段 0:SDK、模型和离线依赖 Spike D3 Python/模型网关开发 可立即开始
WP-B 阶段 1:数据表、Store、API、事件序号、鉴权 D4 后端开发 WP-A 固定版本后开始
WP-C 阶段 2:DeerFlow Agent Adapter D5 高级后端/Agent Runtime 依赖 WP-A、WP-B 契约
WP-D 阶段 3:固定流程、事实账本、恢复 D4 工作流后端 依赖 WP-C,可先用 fake adapter
WP-E 阶段 4:Group Chat 与上下文控制 D5 多智能体高级开发 依赖 WP-C;与 WP-D 部分并行
WP-F 阶段 5:外部写入与一致性 D5 高级后端/技术负责人 依赖 WP-B;与 WP-D/E 协同
WP-G 阶段 6:前端工作台 D4 中高级前端 WP-B 定稿事件契约后并行
WP-H 阶段 7:评测与错误分类 D3 测试/算法/全栈 指标契约确定后并行
WP-I 阶段 8:故障测试、离线包、灰度 D4 测试开发/DevOps 持续介入,最后收口
WP-J 公共入口与最终集成 D4 集成人/技术负责人 各包通过独立验收后

建议让 WP-J 负责人统一修改公共入口、处理冲突和跑全量回归。其他负责人通过最小接口提交自己的模块,减少“合并冲突掩盖代码能力”的情况。

16.2 交付物要求

每个同事交付任务包时必须提供:

  • 独立分支或明确的 commit 列表。
  • 对应任务编号,例如 MAF-02-07。
  • 设计说明:关键接口、状态机、边界和取舍。
  • 代码改动清单。
  • 自动化测试及执行结果。
  • 至少一个成功案例和一个失败案例。
  • 已知限制与后续风险。
  • 若修改公共文件,说明修改原因和是否可能影响旧功能。

缺少测试或失败场景说明的 D4/D5 任务,不视为完整交付。

16A. 同事代码水平评价标准

后续可以把某位同事的分支、commit 或 diff 交给 Codex,按本节输出统一评价。评价不直接代替团队绩效,只衡量本任务中的工程表现。

16A.1 评价输入

至少提供:

  • 负责人姓名或代号。
  • 任务编号与难度,例如 MAF-05-03 / D5。
  • 分支名、commit SHA 或明确 diff。
  • 是否允许查看测试日志。
  • 哪些代码是他人预先提供的。
  • 是否有时间、环境或接口限制。

如果多人代码混在一个提交中,只能评价该提交的整体质量,无法可靠评价个人水平。

16A.2 统一评分(100 分)

维度 分值 评价内容
功能正确性 25 是否满足任务契约、成功/失败路径是否正确
架构与边界 15 模块职责、依赖方向、是否污染旧会商、是否遵守 Harness/App 防火墙
异常与状态处理 15 超时、取消、重试、恢复、并发、乱序和部分失败
安全与副作用 15 身份隔离、凭据脱敏、幂等、审批、外部写入一致性;不适用部分转入正确性
测试质量 15 测试是否能发现真实 bug,而非只覆盖 happy path
可维护性 10 命名、类型、复杂度、注释、复用和可观测性
交付完整度 5 设计说明、运行证据、已知限制和提交整洁度

16A.3 额外记录项

以下项目不直接混入 100 分,但必须随评价一起报告:

  • 任务难度:D1–D5。
  • 独立完成度:独立完成 | 少量提示 | 多次指导 | 主要由他人修复。
  • 首次验收结果:通过 | 小改后通过 | 大改后通过 | 未通过。
  • 关键缺陷等级:P0/P1/P2/P3 数量。
  • 返工轮次。
  • 是否能清楚解释自己的并发、恢复或安全设计。

16A.4 能力结论参考

必须把代码质量与任务难度结合判断:

表现 参考结论
D1/D2 高分 基础扎实,但不足以单独证明复杂系统能力
D3 85 分以上且独立完成 可独立负责普通完整模块
D4 80 分以上且关键异常覆盖完整 具备中高级复杂功能交付能力
D5 80 分以上、无 P0/P1、能解释取舍 具备核心模块或技术负责人候选能力
任意难度出现越权、重复外部写入或伪造测试 即使功能可演示,也不能判定为合格交付

16A.5 Codex 评审输出模板

# 代码评价:<负责人> / <任务编号>

- 任务难度:D4
- 代码得分:82/100
- 独立完成度:少量提示
- 首次验收:小改后通过
- 建议能力档位:可独立负责普通复杂模块,核心一致性模块仍需评审

## 关键发现

1. [P1] ...
2. [P2] ...

## 分项评分

- 功能正确性:22/25
- 架构与边界:13/15
- 异常与状态处理:10/15
- 安全与副作用:12/15
- 测试质量:13/15
- 可维护性:8/10
- 交付完整度:4/5

## 做得好的地方

...

## 需要本人修正的地方

...

## 复评条件

...

17. 开工前最终确认项

  • 首批灰度用户范围。
  • 默认写入策略采用 confirm_high_risk 还是 auto。
  • 第一批用于验收的外部写工具及其 UAT 地址。
  • 第一批主持人和席位 Agent。
  • 对照实验使用的模型与推理参数。
  • MAF 版本和离线 wheel 构建平台。
  • 原会商 run 与 MAF run 的绑定方式。

18. 参考资料