Files
deerflow-code/frontend-web/docs/microsoft-agent-framework-多智能体会商-实施计划.md
T
董宏凯andCursor f82363d81f feat(maf): Phase 5 - action coordinator, approval flow, frontend MAF roundtable pages
- 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>
2026-08-02 13:07:21 +08:00

69 KiB
Raw Blame History

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 是测试专用写工具,已经证明真实 LangGraph ToolNode 与一次性执行器可用,但不等于已接入业务系统。
  • 当前机器未注入生产 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_jobs
  • roundtable_drafts
  • roundtable_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 创建会商

  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": "..."}
  ]
}

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

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

建议字段:

  • 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/*。当前页面根路由为 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 → LangGraph ToolNode → 测试 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,部分完成)以 TDesign Dialog/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,部分完成)以 TDesign Timeline/Card/Tag 重做 Agent、工具、技能和外部动作时间线;事件展示必须只读取 MAF API,且不得显示原始敏感参数。
  • MAF-06-06(D4,部分完成)以 TDesign Card/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;但基于当前代码盘点,当前恢复开发的顺序调整为:

  1. 阶段 5:先完成 target-key 租约锁和 HTTP 审批恢复全链路;真实 UAT 工具仅在业务方提供协议后接入。
  2. 阶段 4:与阶段 5 的无外部依赖任务并行,补齐真实多轮 Group Chat、selector 和弱模型收敛。
  3. 阶段 6:在阶段 5 的动作/API 契约稳定后,将现有原型改为本地 React TDesign 工作台并完成组件级测试。
  4. 阶段 6.5:以独立 MAF view-model 复用旧会商的视觉与交互思路,隐藏技术 session/thread,不复用旧状态。
  5. 阶段 0 遗留项和阶段 1–3 的真实环境演示验收可穿插进行,但不再阻塞上述代码收口。
  6. 阶段 7:在两种编排和前端均验收后做公平对比。
  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. 参考资料