- Backend: action_coordinator, capability_snapshot, event_normalizer, tool_executor updates - Backend: approved_tool_executor with write guard, action leases, migration script - Frontend: maf-roundtable module (API client, event timeline, approval cards, fact flow panel) - Frontend: MafRoutes, MafSessionsPage, MafRunDetailPage - Tests: action_leases, migration_phase5, phase5_entry_e2e, real_write_e2e/http_e2e - Docs: update implementation plan Co-authored-by: Cursor <cursoragent@cursor.com>
69 KiB
Microsoft Agent Framework 多智能体会商对照页实施计划
文档状态:实施中;已按当前工作区代码重新盘点,阶段 5 安全闭环处于收口验收,阶段 4 动态会商仍未达到退出标准 更新时间:2026-08-02 目标版本:实验性独立功能,不替换现有多智能体会商
建议页面名称:MAF 会商(实验)
0. 当前实施状态与前后端隔离决议
0.1 代码盘点结论(以 2026-08-02 当前工作区为准)
本节的状态以当前 master-dev、尚未提交的 MAF 改动和本次实际运行结果为准,不沿用同事口头的阶段编号或测试数量。已实现不等于退出验收通过;只有满足本阶段退出标准、测试证据完整且没有 P0/P1 缺口时才能进入下一阶段的正式验收。
| 阶段 | 当前状态 | 已有代码/证据 | 尚未满足的退出条件 |
|---|---|---|---|
| 0 依赖 Spike | 部分完成 | agent-framework-core 已锁定到 lock 中的 1.13.0;真实 SDK WorkflowBuilder 路径可由测试运行。 |
尚无当前部署模型的 OpenAI 兼容流式实测、离线 wheelhouse 全新安装实测和正式 Spike 记录。 |
| 1 独立后端骨架 | 代码完成 | /api/maf-roundtable、独立 maf_roundtable_* 表、事务化启动/取消、事件序号、用户隔离、管理员只读诊断均已实现。 |
本工作区缺少文档提及的 tests/test_harness_boundary.py,需在 CI 或恢复该用例后补一份边界验证证据。 |
| 2 DeerFlow Agent Adapter | 代码完成,集成验收待补 | 独立 thread、用户 principal、运行参数、SSE 标准化、事件脱敏、取消级联、seat-run 持久化均已实现;相关单测覆盖。 | 尚未用已部署模型和真实 MCP/技能完成一条从 API 到 DeerFlow Runtime 的人工验收记录。 |
| 3 固定流程编排 | 代码完成,测试通过 | WorkflowBuilder 的 planner → 并行席位 → 交叉审查 → 审批 → finalizer、事实账本、格式修复、checkpoint/恢复与 execution_stage 身份均已实现。 |
需在真实模型/真实能力快照下完成一次演示验收;不阻塞阶段 5 的安全收口。 |
| 4 动态 Group Chat | 部分实现,不能验收 | group_chat 模式能走真实 SDK 工作流路径,且会写 manager.decision 事件。 |
当前实质是 WorkflowBuilder 的单次 round-robin:没有主持人 Agent selector、没有多轮同席位发言策略、没有完整的总超时/弱模型收敛测试;详见阶段 4。 |
| 5 外部写入与审批 | 框架闭环完成,UAT/部署待输入 | 已有可信工具元数据、WriteGuard、加密参数、审批超时、服务端派生的目标租约、原子一次执行、unknown 失败关闭、审计 API、真实 ToolNode outbox 及 HTTP 决策→恢复全链路测试。 |
尚未指定 UAT 写入工具、最小权限凭据和核验/补偿协议;生产部署尚未注入 MAF_ACTION_SECRET_KEY。 |
| 6 前端工作台 | 原型已存在,未按新约束验收 | 独立 /page/maf/* 路由、健康门、会话/运行页、纯轮询、审批卡、事件代次隔离已实现;前端逻辑测试 19 项通过。 |
现有可视组件主要仍使用旧的本地 shadcn/Radix 封装,未改为用户指定的 tdesign-react;仍直接引用旧会商目录中的脱敏 hook;恢复/失败重试和组件级 API 验收未完成。 |
| 7 对比评测 | 未开始 | 无。 | 依赖阶段 4、5、6 的正式验收。 |
| 8 测试、离线打包与灰度 | 未开始 | 无。 | 依赖可验收版本。 |
本次重新运行的证据:
- 后端安全闭环重点用例:
293 passed in 140.10s(包含真实入口 ToolNode/outbox、能力快照、WriteGuard、审批过期与目标租约、旧 DeerFlow 回归)。 - 后端编排重点用例:
40 passed in 5.46s(真实 SDK structured/group_chat 路径、Agent Adapter、阶段 3 主持人流程)。 - 前端 MAF 逻辑用例:
19 passed;pnpm build通过。 - 全量
test_maf_*.py已在无短时命令限制的终端完成,最终结果为293 passed in 140.10s;PowerShell 下使用文档中的文件枚举方式展开测试文件。
阶段 1 完成并不表示旧会商被替换。当前配置已打开新的 MAF 功能开关;前端入口由健康检查和权限控制。旧 DeerFlow、旧 roundtable、AI 写作不携带 maf_run_id,因此不进入 MAF WriteGuard 分支。
0.3 阶段 5:真实工具、技能与外部写入审批闭环(当前收口)
本阶段已补齐以下安全边界:
use-maf-events.ts为每次runId、enabled、polling、resetSignal变化分配请求代次;旧请求返回后不能污染新 run,终态补拉不会被旧请求阻塞。- 能力快照的工具副作用元数据只从服务端读取,优先级为 MAF 专用精确工具名配置、已有
ToolConfig.extra、内置白名单、保守默认write/R3。浏览器、会话请求和模型输出不能提供或覆盖这些字段。 - 生产写工具登记时,必须在同一服务端元数据中配置
target_key_fields(稳定的顶层租户/业务对象字段)和可选target_key_namespace;这些字段只参与服务端稳定哈希,禁止直接提交target_key。未登记或无法识别对象的写操作共用保守串行目标,并在unknown后保持人工核验屏障。 - 当前真实发现的只读 MCP 工具名为
weknora-retrieval_weknora_list_knowledge_bases和weknora-retrieval_weknora_search,已按精确名称登记为read/R0;不按 server 名或名称前缀猜测。 - 测试环境提供真实 LangGraph
ToolNode写工具maf_test_outbox_write,只写临时 outbox;它经过真实 WriteGuard、加密参数、审批、execute_approved_tool和一次性执行器。生产外部写入目标仍需业务方指定,不能用检索 MCP 代替,也不能擅自猜测业务系统。 write_guard.enabled=true后,缺少MAF_ACTION_SECRET_KEY时只读工具和技能仍可工作,外部写入在执行前失败关闭;健康检查只返回enabled、ready、secret_configured和状态码,不返回密钥。
本轮框架代码已完成阶段 5 的可自行实现项;下列项目必须由业务方/运维补齐后才能将阶段 5 标记为完整完成:
maf_test_outbox_write是测试专用写工具,已经证明真实 LangGraphToolNode与一次性执行器可用,但不等于已接入业务系统。- 当前机器未注入生产
MAF_ACTION_SECRET_KEY,健康状态会显示missing_secret;这符合失败关闭设计,但不能用于生产写入验收。
上线前必须由部署环境注入 MAF_ACTION_SECRET_KEY,不得写入仓库、config.yaml、前端、事件、checkpoint 或模型上下文。当前测试验收命令为:
$env:PYTHONPATH="."
$env:MAF_ACTION_SECRET_KEY="仅测试环境临时值"
$mafTests = Get-ChildItem tests -Filter "test_maf_*.py" | ForEach-Object FullName
uv run --extra maf pytest $mafTests -q -W error
uv run ruff check app/maf_roundtable packages/harness/deerflow
0.3.1 同事 A:MAF-05-03A / 03B / 04A / 08A 收口记录
本轮已完成前阶段 5 的代码与自动化验收项,但按约定仍不将阶段 5 标记为最终验收完成:真实 UAT 写入系统、测试租户、最小权限凭据、核验 API/补偿协议以及生产环境密钥注入仍待业务方和运维提供。
MAF-05-03A:Action 服务层使用公开白名单 DTO;target_key与idempotency_key仅留在持久层和内部仲裁路径,不能通过两个 actions GET 接口、事件或前端类型返回。目标键只读取服务端登记的稳定标量字段,并使用MAF_ACTION_SECRET_KEY做域隔离 HMAC-SHA-256;缺少密钥时真实写入失败关闭。MAF-05-03B:scripts/migrate_maf_roundtable_phase5.py按数据库方言生成 DDL:PostgreSQL 使用TIMESTAMP WITH TIME ZONE,MySQL/MariaDB 使用DATETIME(6),SQLite 使用DATETIME。迁移可重复执行,表、缺失索引和可安全补齐的列会自动补齐;已覆盖 SQLite 实际迁移以及三种方言 DDL 测试。MAF-05-04A:Gateway lifespan 启动和关闭 MAF 专用审批过期扫描任务,间隔由maf_roundtable.approval_scan_interval_seconds配置。扫描使用已有条件式过期 CAS,然后只对受影响 run 调用dispatcher.resume();普通审批 GET 保持只读,决定/恢复仍在操作前执行失败关闭过期检查。MAF-05-08A:入口级测试从 HTTP 创建 session/run 开始,确定性假实现只位于模型边界;真实 Agent Runtime、WriteGuard、LangGraph ToolNode、加密参数和 outbox 均参与执行。覆盖 HTTP 审批后恰好一次写入,以及同目标并发时第二个 run 的waiting_target_lease与显式 resume。
本轮证据:全部 test_maf_*.py 共 293 passed;阶段 5 定向回归 15 passed;git diff --check 通过。仓库现有的全目录 Ruff 基线仍有与本轮无关的历史问题,提交前需在 CI 中单独清理;本轮新增/修改文件已做定向检查。
0.4 下一批开工顺序与责任边界
当前应正式进入阶段 5 收口;阶段 4 的动态会商可与其中不依赖业务系统的任务并行。不要把阶段 6 原型继续扩展成正式页面,直到阶段 5 的动作一致性契约固定。
| 工作包 | 对应任务 | 难度 | 是否可立即开始 | 交付边界 |
|---|---|---|---|---|
| WP-F1 目标一致性 P1 收口 | MAF-05-03A、MAF-05-03B |
D4/D5 | 已完成 | 已封闭 target_key/内部幂等键公开边界,并使 Phase-5 迁移兼容 PostgreSQL/MySQL;真实 UAT 目标仍由 WP-F3 负责。 |
| WP-F2 审批恢复验收补强 | MAF-05-04A、MAF-05-08A |
D4/D5 | 已完成 | 已完成主动过期、并发/重启补扫,以及从真实工作流入口生成审批到 HTTP 决策、ToolNode/outbox 的全链路验收。 |
| WP-F3 真实 UAT 工具 | MAF-05-05、MAF-05-09、MAF-05-10 |
D5 | 需业务方输入 | 仅在拿到目标系统、最小权限凭据、幂等与查询核验协议后实施;这是唯一不能自行假设的工作包。 |
| WP-E 动态会商 | MAF-04-01 ~ MAF-04-07 |
D5 | 可以并行 | 真实多轮 selector、上下文/终止状态机和弱模型收敛测试;不得修改阶段 5 的 Action Coordinator。 |
| WP-G 前端重构准备 | MAF-06-00 |
D3 | 可以并行 | 仅拆除对旧会商 hook 的直接依赖、固定 API view-model 和测试基线;TDesign 页面重构等阶段 5 契约稳定后开始。 |
WP-F1、WP-F2 与 WP-E 必须分别使用独立分支/提交;公共 config.yaml、Gateway 注册和前端路由由集成人统一合并。WP-F3 进入开发前需由业务方书面确认第一个写入目标,缺少该信息时应保持阻塞状态而不是接入猜测的 MCP。
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/maf/*(当前已落地为独立顶级菜单,不嵌入旧会商页)。 - 两种 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/maf/*,并且只允许请求以下新接口前缀:
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": "..."}
]
}
快照用于审计和复现,不代表运行期间复制工具实例。
MAF 的副作用分类是服务端可信配置,不由上述请求体或模型生成的能力描述决定。部署配置使用实际运行时工具名作为键,例如:
maf_roundtable:
tool_metadata:
weknora-retrieval_weknora_search:
side_effect: read
risk_level: R0
未登记工具保持保守的 write/R3,避免未知外部工具被误放行。技能可以继续使用,但技能触发的实际外部副作用必须落到已分类工具调用,不能绕过 WriteGuard。
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 破坏性操作 | 删除、覆盖且无补偿、批量变更 | 等待确认 | 等待确认 |
这套分级不禁止外部写入,而是保证它在不同运行策略下可控、可恢复、可审计。
当前已完成的可执行验收工具是测试专用 maf_test_outbox_write(R2/write),副作用限制在 MAF_E2E_OUTBOX_DIR 指定的临时目录。生产验收还需要业务方明确目标系统、测试租户、最小权限凭证和幂等/核验接口;在此之前不得宣称已经完成生产业务写入接入。
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/*。当前页面根路由为 MafRoutes.tsx,路由仅新增 /page/maf/*;不得替换、重命名、迁移或修改旧 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 以复用事实账本和恢复机制
主要评价点:弱模型条件下能否收敛、上下文是否准确、硬终止是否可靠
当前代码状态:workflow_factory.py 已为 group_chat 建了真实 MAF WorkflowBuilder 图,CoordinatorExecutor 会写 manager.decision,并有一条 SDK 路径测试。但它目前按 round-robin 让每个席位最多发言一次;这只是可运行的占位编排,不是本阶段承诺的动态多轮会商。
任务:
MAF-04-01(D4)改为使用锁定 MAF 版本实际提供的 Group Chat 编排 API;若该版本没有名为GroupChatBuilder的公开类,必须在设计说明中给出等价的官方 API、版本和最小可运行证明。禁止把手写WorkflowBuilder分支称为已完成的 Group Chat。MAF-04-02(D5)实现两种 selector:可复现的确定性 selector,以及由主持人 Agent 根据已验证事实账本选择下一发言人的 selector。两者均须验证候选席位、返回结构和失败降级,不能相信模型随意返回的 agent id。MAF-04-03(D4)实现最大轮次、连续发言上限、总超时和单席位超时;状态必须持久化到 checkpoint,恢复后继续计数而不是重置。MAF-04-04(D5)以事实账本和摘要引用作为群聊输入来源,保留已执行/待审批/失败动作语义;超长工具结果只传播摘要和可追溯引用,并执行明确 token/字符预算。MAF-04-05(D4)由主持人显式输出完成判断与结构化终稿;不合法输出仅允许一次定向修复,仍失败时走确定性降级并留下原因事件。MAF-04-06(D3)已写入manager.decision事件;后续须把现有round_robin原因扩展为 selector 类型、候选集、拒绝原因和终止依据。MAF-04-07(D5)新增弱模型不结束、幻觉席位、重复选人、席位超时、空输出和恢复后继续轮次的测试;至少包含一次真实 SDK 的多轮(同一席位可在合规策略下再次发言)验收。
退出标准:
- 可以观察每轮由谁发言以及选择原因。
- 达成结论时提前结束。
- 弱模型未正确发出结束信号时,硬终止条件仍能停止。
- 工具结果不会因上下文裁剪而被误判为未执行或执行成功。
阶段 5:外部写入、审批与一致性
阶段难度:D5(核心且高风险)
建议负责人:熟悉分布式一致性、幂等、事务、审计和业务安全的高级后端开发/技术负责人
前置依赖:阶段 1、阶段 2、阶段 3 的 checkpoint 机制
主要评价点:不得重复写、不得越权、状态不明时不得盲目重试、所有动作必须可追踪
任务:
MAF-05-01(D3)已建立服务端可信的工具风险元数据、精确名称覆盖和未知工具write/R3保守分类;会话请求、浏览器和模型输出均不可覆盖它。MAF-05-02(D3)已实现auto、confirm_high_risk、confirm_all_writes策略解析,并在 WriteGuard 之前执行分类。MAF-05-03(D5)服务端目标租约与一次性执行核心已实现,并已完成 03A/03B 的公开边界和跨数据库迁移收口;阶段 5 仍受真实 UAT 工具与部署输入约束,不能据此标记为最终验收完成。MAF-05-03A(D4,分配同事 A)已封闭目标租约键的公开边界:target_key与内部idempotency_key仅留在持久层和内部仲裁路径,两个 actions GET、事件、日志和前端类型均不返回;目标键只接受服务端登记的稳定标量业务字段,并使用域隔离 HMAC-SHA-256 派生。HTTP 回归同时证明存储层仍能使用目标键完成租约仲裁。MAF-05-03B(D4,分配同事 A)已修复migrate_maf_roundtable_phase5.py的跨数据库 DDL:PostgreSQL 使用TIMESTAMP WITH TIME ZONE、MySQL/MariaDB 使用DATETIME(6)、SQLite 使用DATETIME;表、缺失索引和可安全补齐列可重复自动补齐。已覆盖 SQLite 实际迁移及 PostgreSQL/MySQL DDL 测试。MAF-05-04(D5)审批创建时写入部署级超时,到期后在同一事务内标记 Approval=expired、Action=rejected和审计事件。已覆盖真实 HTTP:POST /approvals/{id}/decision→dispatcher.resume()→WorkflowRunner.resume()→ToolExecutor→ LangGraphToolNode→ 测试 outbox;重复决策/恢复仍只执行一次。MAF-05-04A(D4,分配同事 A)已将审批过期收口为 Gateway lifespan 中可取消的 MAF 周期扫描任务;间隔可配置,扫描使用条件式 CAS 后恢复受影响 run,普通 GET 保持只读。已覆盖并发扫描、重复/重启补扫、决策并发和过期后 Action 拒绝且工具执行次数为零,测试不使用sleep。MAF-05-05(D5)为指定的第一个真实写工具实现结果未知核验:外部请求必须携带业务幂等 operation id;网络超时/断连后先调用目标系统查询接口核验,再决定succeeded、failed或保留unknown。补偿动作必须独立审批,不能由通用框架自动猜测或自动重试。MAF-05-06(D4)参数加密、API/事件/日志脱敏和泄漏测试已覆盖;继续在新增真实工具适配器中复用,禁止把明文凭据或原始参数放进 checkpoint、事件或模型上下文。MAF-05-07(D3)已提供按 run 查询 actions、approvals、事件及健康状态的 API,前端原型可显示审批和外部动作审计信息。MAF-05-08(D5)已覆盖两个 Agent 同目标租约串行、进程重启后的过期租约unknown恢复、外部成功但本地终态落库失败时禁止重放、审批超时、HTTP 决策全链路、并发占用、重复resume()、拒绝、缺失/损坏密钥、真实 ToolNode/outbox 与旧 DeerFlow 不回归。MAF-05-08A(D5,分配同事 A)已补齐入口级验收:测试从 HTTP 创建 MAF session/run 和真实工作流入口开始,仅在模型边界使用确定性假实现;真实 WriteGuard、ToolNode、加密参数、HTTP 审批和测试 outbox 均参与,单次写入恰好一次。同目标双 run 覆盖waiting_target_lease,第一个完成后第二个只能显式/runs/{id}/resume,且无重复执行;公开 API 同时断言没有target_key/内部幂等键。MAF-05-09(D5,需业务方输入)接入首个真实 UAT 写工具/MCP。开始前必须明确工具名与参数 schema、目标 UAT 地址/租户、最小权限凭据的注入方式、目标键提取规则、外部幂等键、查询核验 API、可选补偿边界和回滚联系人;未提供这些信息不得猜测并接入生产系统。MAF-05-10(D3)在部署环境通过环境变量注入MAF_ACTION_SECRET_KEY,重启后确认/api/maf-roundtable/health返回write_guard_ready=true;密钥不得提交到仓库或写入config.yaml。
阶段 5 的当前可交付边界:测试专用 maf_test_outbox_write 已验证 WriteGuard → 审批超时/决策 → dispatcher → checkpoint 恢复 → 目标租约 → 直接受控 ToolNode 执行一次的链路,03A、03B、04A、08A 的框架代码与自动化验收项已完成。该结论仍仅代表框架核心已实现:真实 UAT 写工具、业务系统查询/补偿协议、最小权限凭据和生产 MAF_ACTION_SECRET_KEY 注入尚未提供,因此阶段 5 不得写为“验收完成”,也不得在生产执行真实外部写入。部署时先运行 PYTHONPATH=. uv run python scripts/migrate_maf_roundtable_phase5.py;它只证明框架安全性,不替代 MAF-05-09 的真实业务系统验收。
退出标准:
- 外部写入可以实际成功执行。
- 重复事件、断线恢复和服务重启不会造成重复写入。
- 并行 Agent 写同一目标时不会互相覆盖。
- 高风险写入在相应策略下能暂停和恢复。
- 每个外部动作可追溯到用户、会商、run、Agent 和工具调用。
target_key、内部幂等键和明文目标标识均不从公开 API、事件、日志或前端状态泄露;Phase-5 迁移能在项目支持的 SQLite、PostgreSQL、MySQL 上幂等执行。- 审批即使无人刷新页面也会在到期后被后台任务关闭,且完整工作流入口到 HTTP 决策、真实 ToolNode 的链路经一次性测试验证。
阶段 6:前端工作台
阶段难度:D4(较难)
建议负责人:熟悉 React、TanStack Query、轮询事件归并和复杂工作台交互的中高级前端开发
前置依赖:阶段 1 已验收的 API 基线与正式事件契约;reducer 可使用本地 fixture 开发,但不得依赖公开 mock 事件接口;可与阶段 2–5 并行开发
主要评价点:事件状态准确、刷新恢复、审批交互、复杂状态下 UI 不误导用户
组件与实现约束:
- 新 MAF 工作台保持独立路由和独立目录,不修改原多智能体会商的页面、组件、状态或视觉。
- 所有新增的可视 UI 组件优先使用项目本地已安装的
tdesign-react(React TDesign);可沿用项目既有的 TDesign 用法与主题配置。 - 不得接入远程 UI 组件库、CDN 样式/脚本、在线组件生成服务或运行时远程加载的组件。图标、样式和交互资源必须随前端构建产物离线交付。
- 第一版实时更新采用已确定的纯前端轮询:基于
GET events?after_seq=N补拉、去重和游标推进;本阶段不新增 SSE 端点。若后续改用 SSE,另立任务并保持轮询回退路径。 - 使用 TDesign 时应复用
Dialog、Form、Input、Select、Checkbox、Button、Tag、Card、Timeline、Loading、Message等本地组件;业务状态、权限判断、事件归并仍由 MAF 专属 hooks/API 层负责,不能写入组件内部的临时全局状态。
当前代码状态:已有独立 frontend-web/src/maf-roundtable/、MafRoutes.tsx、/page/maf/*、会话/运行页、轮询事件 hook、审批卡和 19 项逻辑测试。这些只能视作可编译原型,不能直接作为阶段 6 交付:当前页面主要使用既有 shadcn/Radix 封装,且直接引用 roundtable-planning/lib/use-desensitize-subtree,均与本阶段的独立性和 React TDesign 约束不一致。
任务:
MAF-06-00(D4,部分完成)保留已有 MAF 专属目录、query key 和/page/maf/*,把直接引用旧会商目录的脱敏 hook 抽到中性共享位置或通过公共服务使用;证明旧会商页面、hooks、store、草稿与路由零改动。MAF-06-01(D3,部分完成)保留现有独立菜单、健康门和实验标识,但把新增可视 UI 统一迁移到项目已安装的本地tdesign-react;不加载任何远程 UI/CDN/在线资源。MAF-06-02(D3,部分完成)以 TDesignDialog/Form/Input/Select/Checkbox重做创建会商、模型配置和席位选择;保留经理与席位互斥、智能体 loading/error/empty 状态和 1–64 轮次校验。MAF-06-03(D2,部分完成)以 TDesign 表单控件呈现structured/group_chat与写入策略;后端配置默认值必须可见,前端不得自行伪造能力快照或风险等级。MAF-06-04(D5)纯轮询事件归并已实现:断线重试、分页补拉、按 seq 去重、游标推进、终态补拉和 run/generation 隔离均已有逻辑测试。后续 UI 改造不得改弱这些语义。MAF-06-05(D3,部分完成)以 TDesignTimeline/Card/Tag重做 Agent、工具、技能和外部动作时间线;事件展示必须只读取 MAF API,且不得显示原始敏感参数。MAF-06-06(D4,部分完成)以 TDesignCard/Dialog/Button重做审批卡;批准/拒绝必须禁用重复提交、以实际 run id 刷新 actions/approvals,并展示后端的失败关闭/未知状态。澄清输入仅在后端提供正式waiting_input契约后接入,不能先造假接口。MAF-06-07(D3,部分完成)以本地 TDesign 呈现事实账本、最终结论和产物;明确区分“候选事实”“已确认事实”“待审批动作”“已执行动作”和“失败/未知动作”。MAF-06-08(D4)补齐取消、审批后恢复、失败后创建新 run/重试的交互与状态禁用;不存在的后端 retry 接口不得由前端伪造为已恢复。MAF-06-09(D4,部分完成)完成刷新恢复、会话历史、run 深链和跨页面返回;切换 run 时不串台,终态页面必须补齐完整历史。MAF-06-10(D4,部分完成)保留现有 19 项纯逻辑测试,并新增挂载 hook/组件级 API mock 测试:慢请求切换 run、终态补拉、审批重复点击、health 缺密钥提示、取消/恢复和错误状态。完整pnpm typecheck的既有非 MAF 错误需单独基线记录,不能以它们掩盖 MAF 新错误。
退出标准:
- 刷新、切页、重新登录后能恢复当前运行。
- 工具和技能调用过程可见。
- 外部写入状态不会仅显示在聊天文本中。
- 页面不请求或加载任何远程 UI 组件、CDN 样式或脚本;断网环境下仍可完整呈现 MAF 工作台。
- 新增工作台 UI 组件来自本地
tdesign-react或项目已有本地基础组件,未引入第二套远程 UI 依赖。 - 原会商页面视觉和交互没有变化。
阶段 6.5:旧会商体验融合(阶段 6 验收后)
阶段难度:D4(较难) 建议负责人:熟悉现有会商产品交互、React 状态边界和 React TDesign 的中高级前端开发 前置依赖:阶段 5 的审批闭环验收、阶段 6 的独立工作台验收 主要评价点:保留用户认可的体验,不把旧业务状态或旧 API 重新耦合进 MAF
目标是让 MAF 页面借鉴旧会商的视觉层级、意图理解入口和“总控智能体派活”的可理解性,而不是把旧页面或其数据层搬过来。技术 session/thread 是 MAF 内部实现,普通用户不需要看见“创建线程”。
MAF-06.5-01(D3)梳理旧会商的用户已认可布局、文案、信息层级和关键交互,形成只读视觉/交互对照清单;不复制旧的 store、jobs、草稿或 API 调用。MAF-06.5-02(D4)以本地tdesign-react重构 MAF 创建入口:用户输入任务/意图后,由 MAF 后端静默创建 session、冻结能力快照并启动 run,不展示底层 thread 创建步骤。MAF-06.5-03(D4)把旧体验中的“意图理解 → 总控智能体分工 → 席位执行 → 会商结论”映射到 MAF 的 planner/manager、事实账本和事件时间线;映射只在 MAF view-model/API adapter 层完成。MAF-06.5-04(D4)对照旧会商完成视觉和交互回归:新旧两个入口、路由、草稿和运行状态完全独立;关闭maf_roundtable.enabled后旧会商零变化。
阶段 7:对比评测
阶段难度:D3(中等)
建议负责人:具备数据分析意识、理解 Agent 错误分类的全栈/测试开发/算法工程师
前置依赖:阶段 3、阶段 4、阶段 5、阶段 6;指标接口可提前开发
主要评价点:对照是否公平、指标是否可解释、是否能区分模型/工具/编排错误
任务:
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 与前端入口。 write_guard.enabled已设为true,但只有带maf_run_id的新 MAF 会商进入 WriteGuard;旧 DeerFlow、旧 roundtable 和 AI 写作保持透传。- 上线前由启动环境注入
MAF_ACTION_SECRET_KEY;不在仓库或配置文件保存该值。访问/api/maf-roundtable/health,确认write_guard_status=ready、write_guard_ready=true后,才允许验证真实外部写入。 - 上线顺序:先部署只读 MAF 与精确工具元数据 → 注入密钥并检查健康状态 → 在 UAT/测试租户启用已指定的真实写工具 → 验证审批、恢复、拒绝、重启和 unknown 场景 → 再扩大灰度。
- 首期仅管理员或指定白名单可见。
- 关闭入口时,已有运行可选择继续完成或管理员取消。
- 出现异常时先关闭
maf_roundtable.enabled停止新的 MAF 写入;必要时再关闭write_guard.enabled。若密钥或外部系统异常,保持 MAF 开启也会因失败关闭而拒绝写操作。旧 roundtable 不需要迁移或回滚。 - MAF 独立表保留用于审计,不在代码回退时删除。
- MAF SDK 使用延迟导入,关闭功能时不影响 Gateway 启动。
16. 推荐开发顺序与工作量级
完整项目的依赖顺序仍是阶段 0 → 8;但基于当前代码盘点,当前恢复开发的顺序调整为:
- 阶段 5:先完成 target-key 租约锁和 HTTP 审批恢复全链路;真实 UAT 工具仅在业务方提供协议后接入。
- 阶段 4:与阶段 5 的无外部依赖任务并行,补齐真实多轮 Group Chat、selector 和弱模型收敛。
- 阶段 6:在阶段 5 的动作/API 契约稳定后,将现有原型改为本地 React TDesign 工作台并完成组件级测试。
- 阶段 6.5:以独立 MAF view-model 复用旧会商的视觉与交互思路,隐藏技术 session/thread,不复用旧状态。
- 阶段 0 遗留项和阶段 1–3 的真实环境演示验收可穿插进行,但不再阻塞上述代码收口。
- 阶段 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 的绑定方式。