feat(maf-roundtable): add Phase-1 multi-agent roundtable infrastructure

Ship an independent, feature-flag-gated MAF roundtable skeleton with six
isolated tables, atomic single-transaction run launch/cancel, owner-scoped
read/write split, shared config enums, and HTTP/concurrency regression tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-01 01:07:05 +08:00
1 parent a0a75a9964
commit e690475e6e
27 files changed
+5369 -101

No files matched your search

@@ -301,6 +301,7 @@ FastAPI application on port 8001 with health check at `GET /health`. Set `GATEWA
| **Dashboard Sessions** (`/api/dashboard-sessions`) | 「大屏绘制智能体」独立页面会话,**按外部 `task_id` 存取,不按 user 分权**(open read + shared writes;`user_id` audit-only)。一个 task 一行(upsert):`transcript`(聊天记录 JSON)+ `report_json`(最新结构化数据,可解析 = 「有效结果」)。`GET /by-task/{task_id}` - 取该 task 会话(无则 404);`PUT /by-task/{task_id}` - upsert(`{transcript?, report_json?}`,只覆盖传入项)。Backed by `deerflow.persistence.dashboard_sessions`(table `dashboard_sessions`, auto-created by `create_all`,无迁移);store wired in `deps.py` as `app.state.dashboard_session_store`。前端独立页 `roundtable-planning/pages/DashboardAgentPage.tsx`(路由 `/page/strategy/dashboard-agent?taskId=`,侧边栏「问答管理 → 大屏绘制」)让智能体分析任务报告 JSON → report-json → 渲染 `DashboardApp`。Tests: `tests/test_dashboard_sessions.py`。 |
| **Task Reports** (`/api/task-reports`) | 任务级研判情报报告详情,**按 `task_id` 共享、不按 user 分权**(写入者只留 `updated_by` 审计)。`GET /by-task/{task_id}` 始终返回原 Consumer 兼容外壳 `{state:"200", msg:"操作成功!", data:[...]}`(未保存为 `data: []`);`POST /by-task/{task_id}` 首次保存,已有报告返回 409;`PUT /by-task/{task_id}` 原子替换完整 `data` 数组。`POST /import/by-task/{task_id}` 面向 TaskCOP 导入页,接收 `sq-report-mock.json` 兼容的 `data`/`records` 数组并完整覆盖目标任务;路径中的选定任务 id 优先于文件内的 `taskId`,避免误写。每一项严格是 `{id, taskId, createTime, updateTime, sessionId, contentJson, categoryType}`;`contentJson` 以 JSON **字符串**原样落在 `records_json`,避免破坏大屏按类目解析的输入格式。保存或导入非空 `data` 后,router 会通过 `app.state.taskcop_task_store.mark_analysis_completed` 将同 id 的 TaskCOP 任务升级至状态 `25`,使旧任务列表显示并筛选为“已完成”;普通保存时不存在匹配任务的报告仍可独立保存,导入则要求目标任务存在。Backed by `deerflow.persistence.task_reports`(table `task_reports`, auto-created by `create_all`);store wired in `deps.py` as `app.state.task_report_store`。前端客户端 `strategy-components/api/task-reports.ts`,`core/auth/dashboard-input.ts` 与 rwfx 3q 完成检查均直接读此接口,不再依赖 Consumer 或本地 sq-report mock。Tests: `tests/test_task_reports.py`。 |
| **Task Buttons** (`/api/task-buttons`) | Task-workspace configurable jump buttons (按钮管理), **global/shared** (no user scoping; `updated_by` audit-only). Each row = one jump button in a task deep-link workspace's bottom 快捷跳转 bar: `{id, business (rwfx/3qfx/xdfx), label, link_type (url/business), target, append_task_id, id_param (editable query-param name, e.g. id/task_id), id_kind (task/action — only xdfx differs, its deep-link id is an 行动id), open_mode (blank/self), login_params, append_auth, auth_token_param, auth_name_param, enabled, sort_order}`. **Two independent, coexisting login-append mechanisms for `url` buttons** — both resolved frontend-side: (1) `login_params` (JSON column `login_params_json`, `PortableJSON`, migration `20260625_01`) = a list of `{key, source, custom_value}` resolved at click time (`source` = a `userInfo` field or `other`→literal `custom_value`) and appended to the target URL — mirrors the light-app login params; empty = nothing appended. (2) `append_auth` + `auth_token_param` + `auth_name_param` (columns, migration `20260625_02`, default off) — appends `?{auth_token_param}={token1}&{auth_name_param}={username}` so the target system can identify the current user; gated on **token login** — the frontend only stashes `token1` (the `?authToken=`) + the raw `getTokenInfo` username (`login.token1`/`login.username`) when login went through `/login/token`, so a non-token-login session appends neither. The **frontend** holds code-seed defaults (rwfx's 4 historical buttons built from the live `task_deeplink` config); only when this table is empty do the workspace + admin page fall back to them, else this table is the sole source of truth. `GET /` - list all (open to any authenticated user — the workspace renders them); `PUT /` - **admin only** (`_require_admin`), atomically **replaces the whole set** (`{buttons: [...]}`, de-duped by `id`, last wins). Backed by `deerflow.persistence.task_buttons` (table `task_buttons`, auto-created by `create_all`); store wired in `deps.py` as `app.state.task_button_store`. Frontend: helpers `core/auth/task-buttons.ts`, client `strategy-components/api/task-buttons.ts`, admin page `pages/TaskButtonsPage.tsx` (route `/page/strategy/admin/task-buttons`, entry「按钮管理」in the bottom-left settings dropdown, admin-only, both sidebar modes; per-business tabs + 「导入默认」). Tests: `tests/test_task_buttons.py`. |
| **MAF Roundtable (实验)** (`/api/maf-roundtable`) | Microsoft Agent Framework 多智能体会商实验 — an **independent, feature-flag-gated** sibling of the legacy multi-agent roundtable (`/api/roundtable-*` / `/api/multi-agent/*`). Uses MAF's Agent / Workflow / Group Chat orchestration while reusing the existing DeerFlow Agent Runtime for each seat's actual execution (tools / skills / MCP / sandbox / external writes). **Phase 1 (shipped)** = persistence skeleton + API contracts: six isolated tables (`maf_roundtable_sessions` / `_participants` / `_runs` / `_events` / `_actions` / `_approvals`) with **no FK to the legacy `roundtable_*` tables** (full isolation — see `tests/test_maf_roundtable_isolation.py::test_maf_tables_isolated_from_legacy_roundtable`); session CRUD + participants + frozen `capability_snapshot`; run lifecycle (create / get / list / cancel); **monotonic per-run event seq** (`(run_id, seq)` unique, `SELECT MAX(seq)+1` with `IntegrityError` retry so concurrent appends from parallel seats produce a dense 1..N seq set — `tests/test_maf_roundtable_api.py::test_concurrent_appends_produce_dense_seq_set`); event 断线补拉 (`GET /runs/{id}/events?after_seq=N`); action idempotency-key uniqueness; approval decision transition + "already decided" guard. **P1/P2 hardening (shipped)**: (1) **atomic single-transaction run launch** — `store.claim_and_create_pending_run` opens one `AsyncSession` + `begin()`: conditional `UPDATE sessions SET status='running' WHERE id=:id AND user_id=:owner AND status NOT IN (active…)` then INSERT a `pending` run (`started_at=None` — pending = queued, not yet handed to the executor); `rowcount!=1` → no run, caller maps to 404/403/409; any flush/commit failure rolls the whole txn back (no residual `starting`, no orphan run). **Atomic cancel** — `store.cancel_run_atomically` SELECTs run JOIN session `with_for_update` in one txn: active run → run+session `cancelled` (+`finished_at`); already-`cancelled` run → repairs a still-active session (fixes historical half-commits); `completed`/`failed` run → run untouched, session repaired only if still active. Concurrent callers are serialised by the DB (not a Python lock). Until a real MAF executor exists the run stays `pending`. (2) **read/write permission split** — `admin_diagnostic_access` widens only the *read* scope (`_read_scope_user`); every *write* is owner-checked via `_write_scope_user` regardless of admin → `403 MafForbiddenError`. (3) **atomic approval decision** — conditional `UPDATE … WHERE status='pending'`; `rowcount==1` wins, already-decided → 409. (4) **config-driven create defaults + shared enums** — `MafMode` / `MafWritePolicy` / `MafParticipantRole` live in `maf_roundtable_config.py` (single source); API schemas reuse them; `default_max_rounds` has `ge=1, le=64`; omitted create fields fall back to config. (5) **no public mock event write** — `POST /runs/{id}/events` removed; events are written only via internal `service.append_event` (future Workflow executor). (6) **PUT rejects explicit null** on non-nullable fields (`title`/`task_text`/`mode`/`max_rounds`/`write_policy`/`participants` → 422); clearable fields (`task_payload`/`model_name`/…) keep null = clear. **User isolation (MAF-01-07)**: every read/write is owner-scoped by `sessions.user_id`; a non-owner gets `404` (not `403`, so existence is not leaked); admins bypass the owner filter when `maf_roundtable.admin_diagnostic_access` is on. **Feature flag (MAF-01-04)**: `config.yaml → maf_roundtable.enabled` (default **false**, deployment-level); when off, write paths return `503 Service Disabled` and the **MAF SDK is never imported** (lazy import inside `app.maf_roundtable` only when a run is actually started — Phase 2+), reads stay open for admin history review. **Run gating**: a session in `running` / `waiting_*` rejects config edits; `capability_snapshot` is frozen at creation and never mutated on update. **Lifespan (MAF-01-03)**: store always wired (`app.state.maf_roundtable_store`), service only constructed when enabled (`app.state.maf_roundtable_service`); init failures are logged but never abort Gateway startup (experimental / opt-in). Boundary: `deerflow.persistence.maf_roundtable` (harness) holds only pure data models + repos (no `app.*` / no MAF SDK); `app.maf_roundtable` (app) is the **only** place the MAF SDK is imported. Config: `deerflow.config.maf_roundtable_config.MafRoundtableConfig` (`enabled` / `default_mode: MafMode` / `default_write_policy: MafWritePolicy` / `default_max_rounds` ge=1 le=64 / `admin_diagnostic_access`). Router `app/gateway/routers/maf_roundtable.py`; service `app/maf_roundtable/service.py`; schemas `app/maf_roundtable/schemas.py`; persistence `packages/harness/deerflow/persistence/maf_roundtable/` (`model.py` = 6 ORM rows, `sessions.py` / `participants.py` / `runs.py` / `events.py` / `actions.py` / `approvals.py` = repos, `store.py` = facade + `claim_and_create_pending_runLine truncated
| **Knowledge** (`/api/knowledge`) | Product knowledge base, **global/shared** (no user isolation; writes record `created_by`/`updated_by` for audit). `POST /ingest/thread/{thread_id}` - sediment one thread into a note (reads messages from the checkpointer, `threads:read` owner-checked); `POST /ingest/threads/batch` - batch-sediment the caller's recent threads (`skip_existing` via `.manifest.json` dedup). **Defaults to `background=true`**: the slow per-thread extraction loop is deferred to a FastAPI background task and the endpoint returns `{queued:true, processed:N}` immediately (each thread's transcript is truncated to `max_input_chars` before the LLM call). Running the loop inline for a large batch outlives the nginx gateway timeout (504), which the frontend's `parseResponse` surfaces as a generic "Request failed"; `background=false` keeps the blocking path (full per-thread `created/skipped/failed` tally) for small batches/scripts. Shared loop: `_run_batch_ingest`. **Optional model selection**: both ingest endpoints accept `model_name` (overrides `knowledge.extract_model_name` for that capture; threaded through `KnowledgeService.capture_thread` ? `extract_thread_llm_multi`). **Model-error surfacing**: when the chosen model produces nothing usable (timeout / API error / non-JSON) capture still **falls back to rule-based extraction and lands a draft** (`llm_fallback:true`); the single-thread (non-background) response and the batch response (`llm_fallback` count) carry this so the UI tells the user "???????". The "??????" chat button stays background/fire-and-forget (passes `model_name`, no per-save error toast); the batch-import dialog is synchronous and shows the fallback count. `POST /ingest/file` - **import an uploaded file** (multipart: `file` + optional `title`/`tags`/`status`/`model_name`) into wiki note(s): the file is converted to Markdown (md/txt read directly, pdf/word/ppt/excel via `convert_file_to_markdown`), distilled by the same wiki-capture LLM pipeline as thread capture (`source_type="file"`), and falls back to a verbatim **draft** note when the model returns nothing usable (`llm_fallback:true`); `POST /ingest/search` - sediment search/tool results as a reference note; `POST /notes` - manual note; `GET /notes` (keyword/tag/source_type/status + pagination); `GET/PUT/DELETE /notes/{id}` (DELETE is soft = archive, `?hard=true` removes the vault file); `POST /search` - `mode=keyword\|vector\|hybrid` (vector?keyword fallback when no embedding endpoint); `GET /notes/{id}/versions` - edit history; `GET /duplicates` + `POST /merge` - dedup; `POST /reindex` - rebuild vector index; `GET /graph` - product graph data (notes + entities, graph-blacklist filtered); `GET/POST /graph/blacklist` + `DELETE /graph/blacklist/{id}` - graph node blacklist (labels = entity names / note titles, case-insensitive match; blacklisted nodes and their edges are dropped from `/graph` and the wiki-export artifacts; table `knowledge_graph_blacklist`, auto-created); `POST /export/graph` + `GET /export/files/{graph.json\|graph.html\|graph.graphml\|cypher.txt}` - obsidian-wiki `wiki-export` artifacts (self-contained `graph.html` for iframe); `POST /resolve` `{targets:[?]}` + `GET /notes/{id}/wikilinks` - resolve `[[wikilink]]` targets to a note id / vault page / missing (powers clickable wikilinks); `GET /vault-page?path=` - read a raw vault meta/hub Markdown page (no DB note). `GET/POST /folders` + `PUT/DELETE /folders/{id}` - user-managed directories (notes carry a `folder` path; `GET /notes?folder=` filters a dir + sub-dirs); `GET/POST /extract-templates` + `GET/PUT/DELETE /extract-templates/{id}` - editable extraction-prompt templates (thread/document ingest accept `template_id`; capture/PUT-note accept `folder`). Backed by the `deerflow.knowledge` module (see below). |
Proxied through nginx: `/api/langgraph/*` ? LangGraph, all other `/api/*` ? Gateway.