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>
47 KiB
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_jobsroundtable_draftsroundtable_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 创建会商
- 用户进入
MAF 会商(实验)。 - 输入任务、选择模型、主持人、参会 Agent 和编排模式。
- 前端读取每个 Agent 当前可用的工具组和技能,并展示能力摘要。
- 用户选择外部写入策略:
auto:按现有用户权限直接执行所有已授权写操作。confirm_high_risk:普通写入自动执行,高风险写入等待确认。confirm_all_writes:所有外部写入均等待确认。
- 后端创建 MAF session,并冻结本次
capability_snapshot。 - 后端为主持人和每个席位创建或绑定独立 DeerFlow thread。
4.2 执行会商
- MAF 生成下一步调度决策。
- 被选中的席位收到:用户任务、完整或裁剪后的会商上下文、自己的角色要求和当前阶段目标。
DeerFlowAgentAdapter发起席位 run。- 席位可真实调用工具、技能、MCP、沙箱和外部写入。
- 工具与技能事件实时写入
maf_roundtable_events,并推送给前端。 - 席位完成后,标准化为
AgentResponse返回 MAF。 - MAF 决定下一席位、进入审查、请求用户确认或结束会商。
- 主持人生成结构化最终结论和执行记录。
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
建议字段:
iduser_idtitletask_texttask_payload_jsonmode:structured | group_chatstatus:draft | running | waiting_approval | waiting_input | completed | failed | cancelledmodel_namereasoning_effortmanager_agent_idmax_roundswrite_policycapability_snapshot_jsonfact_ledger_jsonfinal_result_jsoncreated_atupdated_at
8.2 maf_roundtable_participants
idsession_idagent_iddisplay_namerolesort_orderthread_idsandbox_idstatuslast_turn_indexcapability_snapshot_json
8.3 maf_roundtable_runs
idsession_idstatusworkflow_versionmaf_checkpoint_json或 checkpoint 引用last_event_seqstarted_atfinished_aterror_codeerror_message_safetoken_usage_jsonlatency_ms
8.4 maf_roundtable_events
idsession_idrun_idseqevent_typeagent_idturn_indexpayload_jsoncreated_at
唯一约束:(run_id, seq)。
8.5 maf_roundtable_actions
idsession_idrun_idagent_idtool_namelogical_action_ididempotency_keytarget_keyrisk_levelstatusarguments_redacted_jsonresult_redacted_jsonexternal_object_idapproval_idattempt_countstarted_atfinished_at
唯一约束:idempotency_key。
8.6 maf_roundtable_approvals
idsession_idrun_idaction_idrequested_by_agent_idstatus:pending | approved | rejected | expiredsummarypayload_redacted_jsondecided_bydecided_atexpires_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.startedrun.status_changedworkflow.checkpointedmanager.decisionagent.turn_startedagent.message.deltaagent.message.completedskill.selectedskill.startedskill.completedtool.requestedtool.startedtool.progresstool.completedtool.failedaction.waiting_approvalaction.approvedaction.rejectedartifact.createdfact.recordedrun.completedrun.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. 推荐开发顺序与工作量级
建议严格按以下顺序推进:
- 依赖/模型/离线 wheel Spike。
- 独立 session、event 和 SSE 骨架。
- DeerFlow AgentAdapter,先跑通真实工具、技能和一次外部写入。
- 固定流程编排。
- 动态 Group Chat。
- Action Coordinator、审批和恢复。
- 前端完整工作台。
- 对比评测、回归和灰度。
在熟悉当前代码的前提下,这是一个中等偏大的完整功能,建议按 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 的绑定方式。