feat: 岗位会商命令幂等与圆桌后台作业租约调度

岗位会商写操作引入 command_id 幂等与版本锁,前端支持同键重试;圆桌后台作业改为 DB 租约 dispatcher、去重与草稿 outbox 补偿,并持久化 intent turns。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
董宏凯andCursor committed 2026-08-14 11:08:12 +08:00
1 parent 4f536d9b39
commit 75963c9ad9
51 files changed
+4449 -670

No files matched your search

@@ -54,6 +54,7 @@ class JobProgressWriter:
event_sink: EventSink = None,
on_dialogue: Any | None = None,
recorder: Any | None = None,
lease_owner: str | None = None,
) -> None:
self._store = store
self._job_id = job_id
@@ -65,6 +66,9 @@ class JobProgressWriter:
# 每轮 leader/seat 模型返回后回调(dialogues, consensus)—— 执行器据此把对话
# 写进草稿(和手动跑同一存取路径)。
self._on_dialogue = on_dialogue
# Phase 3 租约持有者:进度落库随 ``update_progress(lease_owner=...)`` 下发,store 的
# 租约门只放行持租者的写(一致性来自 DB 条件 UPDATE)。None = 兼容旧路径(不走租约门)。
self._lease_owner = lease_owner
self._state: dict[str, str] = {a.agent_id: _PENDING for a in agents}
self._spoke_cycle: dict[str, int] = {}
self._consensus = 0
@@ -100,7 +104,11 @@ class JobProgressWriter:
fields.setdefault("dialogues", self._dialogues)
if self._store is not None:
try:
await self._store.update_progress(self._job_id, **fields)
# 带租约持有者时走 store 的租约门(原子条件 UPDATE);返回 None 表示写被拒
# (非持租者 / 已取消)——进度落库 best-effort,不据此中断编排。
await self._store.update_progress(
self._job_id, lease_owner=self._lease_owner, **fields
)
except Exception: # noqa: BLE001 — 进度落库失败不能打断编排
logger.warning("roundtable job progress persist failed", exc_info=True)
if self._event_sink is not None:
@@ -91,6 +91,17 @@ class DatabaseConfig(BaseModel):
"SQLAlchemy default is 30."
),
)
pool_recycle: int = Field(
default=1800,
description=(
"Recycle pooled connections after this many seconds (postgres/mysql only). "
"Prevents stale-connection errors when a firewall, pgbouncer, or MySQL "
"wait_timeout silently drops idle connections. pool_pre_ping catches most "
"cases, but pool_recycle is the belt-and-suspenders safety net. "
"Multi-worker sizing: each worker opens up to (pool_size + max_overflow) "
"connections; total across workers must stay below the DB's max_connections."
),
)
# -- Derived helpers (not user-configured) --
@@ -130,7 +130,7 @@ async def _run_alembic_upgrade(url: str) -> None:
try:
await asyncio.wait_for(asyncio.to_thread(_do_upgrade), timeout=timeout_s)
logger.info("Alembic migrations applied (or already up-to-date)")
except asyncio.TimeoutError:
except TimeoutError:
logger.error(
"Alembic upgrade did not finish within %.0fs; continuing startup on create_all schema. "
"Likely cause: MySQL metadata-lock wait — check SHOW FULL PROCESSLIST for a blocking transaction.",
@@ -213,12 +213,18 @@ def _ensure_orm_columns_sync(sync_conn) -> None:
This sweep compares each existing table against the ORM metadata and issues
``ALTER TABLE … ADD COLUMN`` for every missing column that can be added
safely (nullable, or carrying a server_default). Indexes covering a newly
added column are created as well. Works on sqlite/mysql/postgres — the
column DDL is compiled through the active dialect, so portable types
(``PortableJSON``/``PortableLongText``/``BeijingDateTime``) resolve to the
right backend type. Everything is per-column best-effort: a failure is
logged and startup continues.
added column are created as well. Table-level ``UniqueConstraint`` objects
that are declared on the model but missing from the table are also created
(as a ``CREATE UNIQUE INDEX`` of the same name, which is what the migrations
emit too, and works on SQLite/MySQL/PostgreSQL alike) — without this a newly
declared uniqueness rule (e.g. ``active_dedupe_key``) would silently be absent
on an existing database, weakening dedupe.
Works on sqlite/mysql/postgres — the column DDL is compiled through the
active dialect, so portable types (``PortableJSON``/``PortableLongText``/
``BeijingDateTime``) resolve to the right backend type. Everything is
per-column best-effort: a failure is logged and startup continues.
"""
from sqlalchemy import UniqueConstraint
from sqlalchemy import inspect as sa_inspect
from sqlalchemy.schema import CreateColumn
@@ -273,6 +279,48 @@ def _ensure_orm_columns_sync(sync_conn) -> None:
except Exception:
logger.exception("Failed to auto-create index %s on %s", idx.name, table.name)
# ── 表级 UNIQUE 约束补齐 ──────────────────────────────────────────────────
# create_all 只为全新表建 UniqueConstraint;既有表上新增声明的唯一约束(如
# roundtable_jobs.active_dedupe_key)会静默缺失,去重/幂等的正确性就靠它,故
# 这里显式补建。迁移可能用 CREATE UNIQUE INDEX(同名)实现唯一性,故同时查
# get_unique_constraints 与 get_indexes 的名字集合,避免重复建。
for table in Base.metadata.sorted_tables:
if table.name not in existing_tables:
continue
named_uqs = [
c for c in table.constraints
if isinstance(c, UniqueConstraint) and c.name is not None
]
if not named_uqs:
continue
try:
existing_uq_names = {
uq["name"] for uq in inspector.get_unique_constraints(table.name) if uq.get("name")
}
except Exception:
existing_uq_names = set()
try:
existing_idx_names = {
ix["name"] for ix in inspector.get_indexes(table.name) if ix.get("name")
}
except Exception:
existing_idx_names = set()
for uq in named_uqs:
if uq.name in existing_uq_names or uq.name in existing_idx_names:
continue
# 用 CREATE UNIQUE INDEX(而非 ALTER TABLE ADD CONSTRAINT):迁移本身也用
# CREATE UNIQUE INDEX,且它在 SQLite/MySQL/PostgreSQL 都受支持(SQLite 不
# 支持 ALTER TABLE ADD CONSTRAINT),功能等价地强制唯一性。
cols = ", ".join(preparer.quote(c.name) for c in uq.columns)
try:
sync_conn.exec_driver_sql(
f"CREATE UNIQUE INDEX {preparer.quote(uq.name)} "
f"ON {preparer.quote(table.name)} ({cols})"
)
logger.info("Auto-added unique index %s on %s", uq.name, table.name)
except Exception:
logger.exception("Failed to add unique index %s on %s", uq.name, table.name)
def _is_mysql_unknown_database_error(exc: Exception) -> bool:
message = str(exc).lower()
@@ -287,6 +335,7 @@ async def init_engine(
pool_size: int = 5,
max_overflow: int = 10,
pool_timeout: int = 30,
pool_recycle: int = 1800,
sqlite_dir: str = "",
) -> None:
"""Create the async engine and session factory, then auto-create tables.
@@ -298,6 +347,8 @@ async def init_engine(
pool_size: Base connection pool size (postgres/mysql).
max_overflow: Extra connections allowed beyond pool_size under load (postgres/mysql).
pool_timeout: Seconds to wait for a free pooled connection before erroring (postgres/mysql).
pool_recycle: Recycle connections after N seconds (postgres/mysql). Prevents stale
connections dropped by firewalls / MySQL wait_timeout / pgbouncer.
sqlite_dir: Directory to create for SQLite (ensured to exist).
"""
global _engine, _session_factory, _engine_loop
@@ -366,6 +417,7 @@ async def init_engine(
max_overflow=max_overflow,
pool_timeout=pool_timeout,
pool_pre_ping=True,
pool_recycle=pool_recycle,
json_serializer=_json_serializer,
)
elif backend == "mysql":
@@ -376,7 +428,7 @@ async def init_engine(
max_overflow=max_overflow,
pool_timeout=pool_timeout,
pool_pre_ping=True,
pool_recycle=1800,
pool_recycle=pool_recycle,
json_serializer=_json_serializer,
)
else:
@@ -407,7 +459,7 @@ async def init_engine(
await _auto_create_postgres_db(url)
# Rebuild engine against the now-existing database
await _engine.dispose()
_engine = create_async_engine(url, echo=echo, pool_size=pool_size, max_overflow=max_overflow, pool_timeout=pool_timeout, pool_pre_ping=True, json_serializer=_json_serializer)
_engine = create_async_engine(url, echo=echo, pool_size=pool_size, max_overflow=max_overflow, pool_timeout=pool_timeout, pool_pre_ping=True, pool_recycle=pool_recycle, json_serializer=_json_serializer)
_session_factory = async_sessionmaker(_engine, expire_on_commit=False)
async with _engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
@@ -423,7 +475,7 @@ async def init_engine(
max_overflow=max_overflow,
pool_timeout=pool_timeout,
pool_pre_ping=True,
pool_recycle=1800,
pool_recycle=pool_recycle,
json_serializer=_json_serializer,
)
_session_factory = async_sessionmaker(_engine, expire_on_commit=False)
@@ -460,6 +512,7 @@ async def init_engine_from_config(config) -> None:
pool_size=config.pool_size,
max_overflow=getattr(config, "max_overflow", 10),
pool_timeout=getattr(config, "pool_timeout", 30),
pool_recycle=getattr(config, "pool_recycle", 1800),
sqlite_dir=config.sqlite_dir if config.backend == "sqlite" else "",
)
@@ -0,0 +1,25 @@
"""Intent-turn single-flight persistence (Phase 4).
Exposes a store factory; ``app/gateway/deps.py`` registers it on
``app.state.intent_turn_store`` at startup. The intent router reads it from
``request.app.state`` (no cross-boundary default needed — intent runs only in the
gateway process).
"""
from __future__ import annotations
from deerflow.persistence.intent_turns.model import IntentTurnRow
from deerflow.persistence.intent_turns.sql import IntentTurnRepository
def make_intent_turn_store(session_factory) -> IntentTurnRepository | None:
if session_factory is None:
return None
return IntentTurnRepository(session_factory)
__all__ = [
"IntentTurnRow",
"IntentTurnRepository",
"make_intent_turn_store",
]
@@ -0,0 +1,60 @@
"""ORM model for intent-determination turn single-flight (Phase 4).
一条 ``intent_turns`` 行 = 第一步「确定意图」对话的**一个回合**对 ``(thread_id,
client_turn_id)`` 的占用记录。前端为每个回合生成稳定的 ``client_turn_id``,重试 / 双击 /
网络层重发都复用它;后端用 ``UNIQUE(thread_id, client_turn_id)`` 做跨 worker 单飞:
* 同一 ``(thread_id, client_turn_id)`` 至多一条行 —— INSERT 冲突即幂等命中:
- 已 ``done`` → 原样回放缓存的终态帧,**不再启 run**(杜绝双发意图 / 重复澄清卡);
- 在跑且租约未过期 → 该请求是重复的 in-flight 请求,丢弃(原请求仍在流式吐结果);
- 在跑但租约过期(worker 崩溃)→ 抢占续跑;
- ``message_hash`` 不同(同一 client_turn_id 却是不同内容)→ 409 客户端 bug。
一致性只来自 DB 唯一键 + 条件 UPDATE(租约 CAS),不依赖进程内 ``RunManager``
(后者是每进程内存态,多 worker 下看不到彼此的 run,无法单飞)。
"""
from __future__ import annotations
from datetime import UTC, datetime
from sqlalchemy import String, Text, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
from deerflow.persistence.base import Base
from deerflow.persistence.types import BeijingDateTime, PortableLongText
class IntentTurnRow(Base):
__tablename__ = "intent_turns"
__table_args__ = (
# 跨 worker 单飞的根:同一 (thread_id, client_turn_id) 至多一条。INSERT 冲突即幂等。
UniqueConstraint("thread_id", "client_turn_id", name="uq_intent_turns_thread_client"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
thread_id: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
# 前端每回合生成的稳定幂等键;重试 / 双击复用同一个。
client_turn_id: Mapped[str] = mapped_column(String(64), nullable=False)
# 本回合 message 的 sha256:检测「同 client_turn_id 但内容变了」的客户端 bug(→ 409)。
message_hash: Mapped[str] = mapped_column(String(64), nullable=False)
# running(在跑)/ done(已出终态帧,可回放)/ error。
status: Mapped[str] = mapped_column(
String(16), nullable=False, default="running", server_default="running"
)
# 终态帧的完整 JSON(done/error 时写入):重复请求命中时原样回放,不再启 run。
result_json: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
error: Mapped[str | None] = mapped_column(Text, nullable=True)
# 租约:领走的 worker 标记;过期(worker 崩溃)后可被条件 UPDATE 抢占续跑。
lease_owner: Mapped[str | None] = mapped_column(String(64), nullable=True)
lease_until: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
created_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC)
)
updated_at: Mapped[datetime] = mapped_column(
BeijingDateTime(),
nullable=False,
default=lambda: datetime.now(UTC),
onupdate=lambda: datetime.now(UTC),
)
@@ -0,0 +1,225 @@
"""SQLAlchemy-backed intent-turn single-flight storage (Phase 4).
跨 worker 单飞 + 幂等回放,一致性只来自 DB(唯一键 + 条件 UPDATE),不依赖进程内
``RunManager``(多 worker 下彼此不可见)。两条核心路径:
* ``try_claim`` —— INSERT 占用 ``(thread_id, client_turn_id)``;唯一键冲突即幂等命中,
按「已 done→回放 / 在跑且租约有效→丢弃 / 租约过期或 error→抢占续跑 / 内容不一致→409」分流。
* ``record_result`` —— 持租者把终态帧写回(条件 UPDATE 要求租约匹配),清租约。
"""
from __future__ import annotations
import json
from datetime import UTC, datetime
from typing import Any
from uuid import uuid4
from sqlalchemy import select, update
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import async_sessionmaker
from deerflow.persistence.intent_turns.model import IntentTurnRow
def _loads(value: Any) -> Any:
if isinstance(value, str) and value:
try:
return json.loads(value)
except (json.JSONDecodeError, TypeError):
return value
return value
class IntentTurnRepository:
def __init__(self, session_factory: async_sessionmaker) -> None:
self._sf = session_factory
@staticmethod
def _row_to_dict(row: IntentTurnRow | None) -> dict[str, Any] | None:
if row is None:
return None
return {
"id": row.id,
"thread_id": row.thread_id,
"client_turn_id": row.client_turn_id,
"message_hash": row.message_hash,
"status": row.status,
"result_json": _loads(row.result_json),
"error": row.error,
"lease_owner": row.lease_owner,
"lease_until": row.lease_until.isoformat() if row.lease_until else None,
"created_at": row.created_at,
"updated_at": row.updated_at,
}
async def get(self, thread_id: str, client_turn_id: str) -> dict[str, Any] | None:
stmt = select(IntentTurnRow).where(
IntentTurnRow.thread_id == thread_id,
IntentTurnRow.client_turn_id == client_turn_id,
)
async with self._sf() as session:
row = (await session.execute(stmt)).scalar_one_or_none()
return self._row_to_dict(row)
async def try_claim(
self,
*,
thread_id: str,
client_turn_id: str,
message_hash: str,
lease_owner: str,
lease_until: datetime,
) -> dict[str, Any]:
"""占用一个意图回合 —— 跨 worker 单飞 + 幂等的入口。
返回 ``{"action": ..., "row": {...}}``,``action`` 取值:
* ``"run"`` —— 本调用方赢得占用(新建 / 抢占续跑),应启 run 并在终态写回。
* ``"replay"`` —— 该回合已 ``done``,原样回放 ``row.result_json``,**不再启 run**。
* ``"duplicate"``—— 该回合仍在跑且租约有效(或刚被别处抢占),本请求是重复的
in-flight 请求,应丢弃(原请求仍在流式吐结果)。
* ``"conflict"`` —— 同一 ``client_turn_id`` 但 ``message_hash`` 不同 → 客户端 bug,409。
"""
# 1) 先尝试 INSERT 占用。
new_id = uuid4().hex
try:
async with self._sf() as session:
session.add(
IntentTurnRow(
id=new_id,
thread_id=thread_id,
client_turn_id=client_turn_id,
message_hash=message_hash,
status="running",
lease_owner=lease_owner,
lease_until=lease_until,
)
)
await session.commit()
row = await self.get(thread_id, client_turn_id)
return {"action": "run", "row": row}
except IntegrityError:
# 唯一键 (thread_id, client_turn_id) 冲突 → 幂等命中,读回既有行分流。
pass
existing = await self.get(thread_id, client_turn_id)
if existing is None:
# 极端竞态:冲突与回读之间行被清掉。降级为「可新建」再插一次(best-effort)。
return {"action": "run", "row": None}
# 2) 内容指纹不一致 → 客户端 bug(同 client_turn_id 却换了 message)。
if existing.get("message_hash") != message_hash:
return {"action": "conflict", "row": existing}
status = existing.get("status") or "running"
# 3) 已完成 → 幂等回放终态帧。
if status == "done":
return {"action": "replay", "row": existing}
# 4) 在跑或出错 → 尝试条件 UPDATE 抢占续跑(error 强制;running 要求租约已过期)。
reclaimed = await self._conditional_reclaim(
thread_id=thread_id,
client_turn_id=client_turn_id,
prev_status=status,
lease_owner=lease_owner,
lease_until=lease_until,
)
if reclaimed is not None:
return {"action": "run", "row": reclaimed}
# 5) 抢占失败:仍在跑且租约有效(或刚被别处抢占)→ 本请求是重复 in-flight,丢弃。
return {"action": "duplicate", "row": existing}
async def _conditional_reclaim(
self,
*,
thread_id: str,
client_turn_id: str,
prev_status: str,
lease_owner: str,
lease_until: datetime,
) -> dict[str, Any] | None:
"""原子条件 UPDATE 抢占:``error`` 强制续跑;``running`` 仅当租约已过期。
成功则置 ``status='running'``、写新租约,返回行;否则 None(仍在跑 / 刚被抢占)。
"""
now = datetime.now(UTC)
where = [
IntentTurnRow.thread_id == thread_id,
IntentTurnRow.client_turn_id == client_turn_id,
]
if prev_status == "error":
where.append(IntentTurnRow.status == "error")
else:
where.extend(
[
IntentTurnRow.status == "running",
IntentTurnRow.lease_until.is_not(None),
IntentTurnRow.lease_until < now,
]
)
values = {
"status": "running",
"lease_owner": lease_owner,
"lease_until": lease_until,
"updated_at": now,
}
async with self._sf() as session:
result = await session.execute(
update(IntentTurnRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = (
await session.execute(
select(IntentTurnRow).where(
IntentTurnRow.thread_id == thread_id,
IntentTurnRow.client_turn_id == client_turn_id,
)
)
).scalar_one_or_none()
return self._row_to_dict(row)
async def record_result(
self,
*,
thread_id: str,
client_turn_id: str,
lease_owner: str,
status: str,
result_json: Any = None,
error: str | None = None,
) -> bool:
"""持租者把终态帧写回(条件 UPDATE 要求租约匹配),并清租约。
只有赢得 ``try_claim``(``action='run'``)的调用方才应调用,且 ``lease_owner``
必须与领取时一致 —— 防止「抢占续跑的新 worker」被「旧 worker 的迟到收尾」覆盖。
"""
now = datetime.now(UTC)
values: dict[str, Any] = {
"status": status,
"lease_owner": None,
"lease_until": None,
"updated_at": now,
}
if result_json is not None:
values["result_json"] = json.dumps(result_json, ensure_ascii=False)
if error is not None:
values["error"] = error
where = [
IntentTurnRow.thread_id == thread_id,
IntentTurnRow.client_turn_id == client_turn_id,
IntentTurnRow.lease_owner == lease_owner,
IntentTurnRow.status == "running",
]
async with self._sf() as session:
result = await session.execute(
update(IntentTurnRow).where(*where).values(**values)
)
if result.rowcount == 0:
return False
await session.commit()
return True
@@ -0,0 +1,61 @@
"""Add optimistic-lock version column to position_roundtable_nodes.
Revision ID: 20260813_01
Revises: 20260808_01
Create Date: 2026-08-13
背景:``complete_node_turn`` 把「本节点 done → 下游 invalidate → 解锁下一 stage」
拆成多个独立事务的 ``update_node``,并发下后写覆盖先写,节点状态被打错(卡 locked /
invalidated_by 残留),导致下一阶段 ``_handoff_context`` 拿不到上游产物(断链)。
新增 ``version`` 列供 ``update_node`` 做乐观锁(``WHERE version=?``),并把状态转移
收敛进单一 ``FOR UPDATE`` 事务(``recompute_chain_state``),彻底消除 TOCTOU。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
revision = "20260813_01"
down_revision = "20260808_01"
branch_labels = None
depends_on = None
_TABLE = "position_roundtable_nodes"
_COLUMN = "version"
def _has_table(table_name: str) -> bool:
return table_name in inspect(op.get_bind()).get_table_names()
def _has_column(table_name: str, column_name: str) -> bool:
if not _has_table(table_name):
return False
return any(
column["name"] == column_name
for column in inspect(op.get_bind()).get_columns(table_name)
)
def upgrade() -> None:
if not _has_table(_TABLE):
return
if not _has_column(_TABLE, _COLUMN):
op.add_column(
_TABLE,
sa.Column(
_COLUMN,
sa.Integer(),
nullable=False,
server_default="0",
),
)
def downgrade() -> None:
if not _has_table(_TABLE):
return
if _has_column(_TABLE, _COLUMN):
op.drop_column(_TABLE, _COLUMN)
@@ -0,0 +1,48 @@
"""Add optimistic-lock ``version`` column to both roundtable draft tables.
Revision ID: 20260813_02
Revises: 20260813_01
Create Date: 2026-08-13
为 ``roundtable_drafts``(个人草稿)与 ``roundtable_task_drafts``(任务草稿)各加一列
``version INTEGER NOT NULL DEFAULT 0``,配合 ``update_draft(expected_version=...)`` 乐观锁,
消除后台作业 ``_write_run_to_draft`` 的 step2.runs 读-改-写丢失更新。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
revision = "20260813_02"
down_revision = "20260813_01"
branch_labels = None
depends_on = None
_TABLES = ("roundtable_drafts", "roundtable_task_drafts")
def _has_column(table_name: str, column_name: str) -> bool:
bind = op.get_bind()
if table_name not in inspect(bind).get_table_names():
return False
return any(
column["name"] == column_name
for column in inspect(bind).get_columns(table_name)
)
def upgrade() -> None:
for table in _TABLES:
if not _has_column(table, "version"):
op.add_column(
table,
sa.Column("version", sa.Integer(), nullable=False, server_default="0"),
)
def downgrade() -> None:
for table in _TABLES:
if _has_column(table, "version"):
op.drop_column(table, "version")
@@ -0,0 +1,88 @@
"""Add session version column and command idempotency table.
Revision ID: 20260813_03
Revises: 20260813_02
Create Date: 2026-08-13
岗位会商并发根治(命令式状态机)的两项 DB 支撑:
1. ``position_roundtable_sessions.version`` — session 级乐观锁版本号,保护
「确定意图 / 激活链 / 归档」等 session 级写操作,配合 ``apply_node_command``
的单一 ``FOR UPDATE`` 事务消除两个用户同时激活/归档同一 session 的竞态。
2. ``position_roundtable_commands`` — 命令幂等记录表。网络重试 / 双击 /
beforeunload beacon 可能把同一命令送达多次;靠 ``UNIQUE(session_id,
node_key, command_id)`` 让数据库天然去重,第二次到达时直接返回上次
``result_json``,绝不重复推进状态机。``payload_hash`` 防止客户端误复用
command_id 发送不同参数(同 command_id 但 hash 不同 → 409)。
``create_all`` 会为全新 DB 建表/补列;本迁移只补丁已存在的 DB。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
from sqlalchemy.dialects.mysql import LONGTEXT
revision = "20260813_03"
down_revision = "20260813_02"
branch_labels = None
depends_on = None
_SESSIONS_TABLE = "position_roundtable_sessions"
_COMMANDS_TABLE = "position_roundtable_commands"
def _has_table(table_name: str) -> bool:
return table_name in inspect(op.get_bind()).get_table_names()
def _has_column(table_name: str, column_name: str) -> bool:
if not _has_table(table_name):
return False
return any(
column["name"] == column_name
for column in inspect(op.get_bind()).get_columns(table_name)
)
def upgrade() -> None:
# 1) sessions.version
if _has_table(_SESSIONS_TABLE) and not _has_column(_SESSIONS_TABLE, "version"):
op.add_column(
_SESSIONS_TABLE,
sa.Column("version", sa.Integer(), nullable=False, server_default="0"),
)
# 2) position_roundtable_commands
# result_json 与模型的 PortableLongText 对齐:MySQL 用 LONGTEXT,其余用 TEXT。
long_text = LONGTEXT() if op.get_bind().dialect.name == "mysql" else sa.Text()
if not _has_table(_COMMANDS_TABLE):
op.create_table(
_COMMANDS_TABLE,
sa.Column("id", sa.String(length=64), primary_key=True),
sa.Column("session_id", sa.String(length=64), nullable=False),
sa.Column("node_key", sa.String(length=256), nullable=False, server_default=""),
sa.Column("command_id", sa.String(length=64), nullable=False),
sa.Column("command_type", sa.String(length=32), nullable=False),
sa.Column("payload_hash", sa.String(length=64), nullable=False),
sa.Column("result_json", long_text, nullable=True),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.UniqueConstraint(
"session_id", "node_key", "command_id",
name="uq_position_roundtable_commands_session_node_cmd",
),
)
op.create_index(
"ix_position_roundtable_commands_session_id",
_COMMANDS_TABLE,
["session_id"],
)
def downgrade() -> None:
if _has_table(_COMMANDS_TABLE):
op.drop_table(_COMMANDS_TABLE)
if _has_table(_SESSIONS_TABLE) and _has_column(_SESSIONS_TABLE, "version"):
op.drop_column(_SESSIONS_TABLE, "version")
@@ -0,0 +1,51 @@
"""Add ``draft_persist_pending`` flag to roundtable jobs.
Revision ID: 20260813_04
Revises: 20260813_03
Create Date: 2026-08-13
后台作业 ``_write_run_to_draft`` 的乐观锁重试全部耗尽后,不再退化为
last-write-wins 盲写,而是把 ``draft_persist_pending`` 置 1;由 outbox 补偿器
(Phase 3)负责投影结果到草稿,保证「研讨结果不丢」的一致性来自 DB 标记而非运气。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
revision = "20260813_04"
down_revision = "20260813_03"
branch_labels = None
depends_on = None
_TABLE = "roundtable_jobs"
def _has_column(table_name: str, column_name: str) -> bool:
bind = op.get_bind()
if table_name not in inspect(bind).get_table_names():
return False
return any(
column["name"] == column_name
for column in inspect(bind).get_columns(table_name)
)
def upgrade() -> None:
if not _has_column(_TABLE, "draft_persist_pending"):
op.add_column(
_TABLE,
sa.Column(
"draft_persist_pending",
sa.Boolean(),
nullable=False,
server_default=sa.false(),
),
)
def downgrade() -> None:
if _has_column(_TABLE, "draft_persist_pending"):
op.drop_column(_TABLE, "draft_persist_pending")
@@ -0,0 +1,115 @@
"""Add lease / dedupe / snapshot columns to roundtable jobs (Phase 3).
Revision ID: 20260813_05
Revises: 20260813_04
Create Date: 2026-08-13
把「后台作业不双跑 / 崩溃可接管 / resume·cancel 串行」的一致性收敛到 DB:
- ``active_dedupe_key``:**唯一索引**。作业活跃(非终态)时存
``sha256(scope)``(scope = draft_id + task_id|user_id),进入终态时清 NULL。
MySQL/SQLite 的唯一索引都允许多个 NULL —— 于是「同一 scope 至多一个活跃作业」
由唯一键强制,INSERT 冲突即幂等命中,**不再依赖 GET_LOCK 命名锁**。
- ``request_id`` / ``request_hash``:前端启动请求的幂等键与入参指纹(审计 /
排查用;去重本身由 active_dedupe_key 负责)。
- ``input_snapshot``:启动入参的完整 JSON 快照 —— dispatcher 在**任意 worker**
领取 queued/租约过期作业时据此重建 StartParams(跨进程可接管的前提)。
- ``lease_owner`` / ``lease_until``:租约。条件 UPDATE 抢占(queued 或租约过期),
心跳续租;worker 崩溃后租约自然过期,其它 worker 接管 —— 恢复能力来自 DB 而非
进程内存。
- ``attempt`` / ``version``:接管次数计数 + 行级 CAS 版本(条件 UPDATE 乐观锁)。
``draft_persist_pending`` 已在 20260813_04 加入,此处不重复。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
from sqlalchemy import inspect
from sqlalchemy.dialects import mysql
revision = "20260813_05"
down_revision = "20260813_04"
branch_labels = None
depends_on = None
_TABLE = "roundtable_jobs"
_DEDUPE_INDEX = "uq_roundtable_jobs_active_dedupe_key"
def _has_table(table_name: str) -> bool:
return table_name in inspect(op.get_bind()).get_table_names()
def _has_column(table_name: str, column_name: str) -> bool:
if not _has_table(table_name):
return False
return any(
column["name"] == column_name
for column in inspect(op.get_bind()).get_columns(table_name)
)
def _has_index(table_name: str, index_name: str) -> bool:
if not _has_table(table_name):
return False
try:
return any(ix["name"] == index_name for ix in inspect(op.get_bind()).get_indexes(table_name))
except Exception: # pragma: no cover - 方言差异兜底
return False
def _longtext() -> sa.types.TypeEngine:
"""SQLite/PostgreSQL 用 TEXT(无上限),MySQL 用 LONGTEXT(避免 64KB 截断)。"""
return sa.Text().with_variant(mysql.LONGTEXT(), "mysql")
def upgrade() -> None:
if not _has_table(_TABLE):
return
if not _has_column(_TABLE, "request_id"):
op.add_column(_TABLE, sa.Column("request_id", sa.String(64), nullable=True))
if not _has_column(_TABLE, "request_hash"):
op.add_column(_TABLE, sa.Column("request_hash", sa.String(64), nullable=True))
if not _has_column(_TABLE, "active_dedupe_key"):
op.add_column(_TABLE, sa.Column("active_dedupe_key", sa.String(64), nullable=True))
if not _has_index(_TABLE, _DEDUPE_INDEX):
op.create_index(_DEDUPE_INDEX, _TABLE, ["active_dedupe_key"], unique=True)
if not _has_column(_TABLE, "input_snapshot"):
op.add_column(_TABLE, sa.Column("input_snapshot", _longtext(), nullable=True))
if not _has_column(_TABLE, "lease_owner"):
op.add_column(_TABLE, sa.Column("lease_owner", sa.String(64), nullable=True))
if not _has_column(_TABLE, "lease_until"):
op.add_column(_TABLE, sa.Column("lease_until", sa.DateTime(), nullable=True))
if not _has_column(_TABLE, "attempt"):
op.add_column(
_TABLE,
sa.Column("attempt", sa.Integer(), nullable=False, server_default=sa.text("0")),
)
if not _has_column(_TABLE, "version"):
op.add_column(
_TABLE,
sa.Column("version", sa.Integer(), nullable=False, server_default=sa.text("0")),
)
def downgrade() -> None:
if not _has_table(_TABLE):
return
if _has_index(_TABLE, _DEDUPE_INDEX):
op.drop_index(_DEDUPE_INDEX, table_name=_TABLE)
for col in (
"version",
"attempt",
"lease_until",
"lease_owner",
"input_snapshot",
"active_dedupe_key",
"request_hash",
"request_id",
):
if _has_column(_TABLE, col):
op.drop_column(_TABLE, col)
@@ -0,0 +1,77 @@
"""intent_turns: intent-determination turn single-flight table (Phase 4).
Revision ID: 20260813_06
Revises: 20260813_05
Create Date: 2026-08-13
新建 ``intent_turns`` 表:第一步「确定意图」对话每回合对 ``(thread_id, client_turn_id)``
的占用记录。前端每回合生成稳定 ``client_turn_id``(重试 / 双击复用),后端用
``UNIQUE(thread_id, client_turn_id)`` 跨 worker 单飞 + 幂等回放,杜绝并发下「同一回合
被启两个 run → 双发意图 / 重复澄清卡」(用户报的「确定意图接口报错」)。
为什么需要它:进程内 ``RunManager`` 是每 worker 内存态,多 worker 下看不到彼此的 run,
同 thread 的两个请求若落到不同 worker 会各启一个 run(没有任何 409)—— 单飞只能靠 DB。
防变动既有库:全新部署由 ``create_all`` 建表;既有库由本迁移 + ``_ensure_orm_columns_sync``
兜底(表不存在则建)。所有步骤带 ``_has_table``/``_has_index`` 守卫,可重复执行。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
revision = "20260813_06"
down_revision = "20260813_05"
branch_labels = None
depends_on = None
_TABLE = "intent_turns"
_UQ = "uq_intent_turns_thread_client"
def _has_table(name: str) -> bool:
bind = op.get_bind()
insp = sa.inspect(bind)
return name in insp.get_table_names()
def _has_index(table: str, name: str) -> bool:
bind = op.get_bind()
insp = sa.inspect(bind)
return any(ix["name"] == name for ix in insp.get_indexes(table))
def upgrade() -> None:
if _has_table(_TABLE):
# 既有库(极少见,纯防御):补唯一索引即可。
if not _has_index(_TABLE, _UQ):
op.create_index(_UQ, _TABLE, ["thread_id", "client_turn_id"], unique=True)
return
op.create_table(
_TABLE,
sa.Column("id", sa.String(length=64), nullable=False),
sa.Column("thread_id", sa.String(length=128), nullable=False),
sa.Column("client_turn_id", sa.String(length=64), nullable=False),
sa.Column("message_hash", sa.String(length=64), nullable=False),
sa.Column("status", sa.String(length=16), nullable=False, server_default=sa.text("running")),
sa.Column("result_json", sa.Text().with_variant(sa.dialects.mysql.LONGTEXT(), "mysql"), nullable=True),
sa.Column("error", sa.Text(), nullable=True),
sa.Column("lease_owner", sa.String(length=64), nullable=True),
sa.Column("lease_until", sa.DateTime(), nullable=True),
sa.Column("created_at", sa.DateTime(), nullable=False),
sa.Column("updated_at", sa.DateTime(), nullable=False),
sa.PrimaryKeyConstraint("id"),
)
op.create_index("ix_intent_turns_thread_id", _TABLE, ["thread_id"])
op.create_index(_UQ, _TABLE, ["thread_id", "client_turn_id"], unique=True)
def downgrade() -> None:
if _has_index(_TABLE, _UQ):
op.drop_index(_UQ, table_name=_TABLE)
if _has_index(_TABLE, "ix_intent_turns_thread_id"):
op.drop_index("ix_intent_turns_thread_id", table_name=_TABLE)
if _has_table(_TABLE):
op.drop_table(_TABLE)
@@ -0,0 +1,42 @@
"""Add version column to roundtable_artifact_submissions for CAS.
Revision ID: 20260813_07
Revises: 20260813_06
Create Date: 2026-08-13
Phase 5 CAS: submit/cancel 带 expected_version,并发时旧 cancel 不得撤销新提交。
version 列有 server_default='0',既有行自动得 0,无需数据回填。
"""
from __future__ import annotations
import sqlalchemy as sa
from alembic import op
revision = "20260813_07"
down_revision = "20260813_06"
branch_labels = None
depends_on = None
_TABLE = "roundtable_artifact_submissions"
_COL = "version"
def _has_column(bind, table: str, column: str) -> bool:
inspector = sa.inspect(bind)
return any(col["name"] == column for col in inspector.get_columns(table))
def upgrade() -> None:
bind = op.get_bind()
if not _has_column(bind, _TABLE, _COL):
op.add_column(
_TABLE,
sa.Column(_COL, sa.Integer(), nullable=False, server_default=sa.text("0")),
)
def downgrade() -> None:
bind = op.get_bind()
if _has_column(bind, _TABLE, _COL):
op.drop_column(_TABLE, _COL)
@@ -40,6 +40,7 @@ from deerflow.persistence.concurrency.model import ConcurrencySampleRow
from deerflow.persistence.dashboard_sessions.model import DashboardSessionRow
from deerflow.persistence.embed_sessions.model import EmbedSessionRow
from deerflow.persistence.feedback.model import FeedbackRow
from deerflow.persistence.intent_turns.model import IntentTurnRow
from deerflow.persistence.light_apps.model import LightAppRow
from deerflow.persistence.llm_metrics.model import LlmCallMetricRow
from deerflow.persistence.llmwiki.model import LlmWikiConversationDepositRow, LlmWikiKnowledgeBaseRow
@@ -147,6 +148,7 @@ __all__ = [
"TaskCopTaskRow",
"TaskReportRow",
"EmbedSessionRow",
"IntentTurnRow",
"ThreadMetaRow",
"ThreadShareRow",
"ToolCallMetricRow",
@@ -3,12 +3,14 @@
from __future__ import annotations
from deerflow.persistence.position_roundtable.model import (
PositionRoundtableCommandRow,
PositionRoundtableNodeRow,
PositionRoundtableSessionRow,
)
from deerflow.persistence.position_roundtable.sql import PositionRoundtableRepository
__all__ = [
"PositionRoundtableCommandRow",
"PositionRoundtableNodeRow",
"PositionRoundtableRepository",
"PositionRoundtableSessionRow",
@@ -0,0 +1,117 @@
"""Pure delivery-decision helpers for position-roundtable nodes.
These functions decide whether a turn delivered a real Markdown report, whether
the delivery changed, and whether a node is the special intent position. They
are intentionally **pure** (no DB / no app imports) so the exact same logic can
run both:
- in the API router (for read-only projections and validation), and
- inside ``PositionRoundtableRepository.apply_node_command`` — *under the row
locks* — where every state-machine decision must be computed from the locked
rows, never from a stale pre-transaction snapshot.
Keeping one implementation avoids the classic drift where the router's decision
and the store's transition disagree under concurrency.
"""
from __future__ import annotations
from typing import Any
_OUTPUTS_PREFIX = "mnt/user-data/outputs/"
def _artifact_path(artifact: dict[str, Any]) -> str:
return str(artifact.get("path") or artifact.get("artifact_url") or "").strip().lower()
def _artifact_name(artifact: dict[str, Any]) -> str:
return str(artifact.get("name") or artifact.get("filename") or "").strip().lower()
def _artifact_mime(artifact: dict[str, Any]) -> str:
return str(artifact.get("mime_type") or artifact.get("mimeType") or "").strip().lower()
def _in_outputs(path: str) -> bool:
"""Only files under the thread outputs dir count as deliverables."""
return not path or path.replace("\\", "/").lstrip("/").startswith(_OUTPUTS_PREFIX)
def is_markdown_artifact(artifact: Any) -> bool:
if not isinstance(artifact, dict):
return False
path = _artifact_path(artifact)
name = _artifact_name(artifact)
mime = _artifact_mime(artifact)
if not _in_outputs(path):
return False
return (
"markdown" in mime
or path.endswith(".md")
or path.endswith(".markdown")
or name.endswith(".md")
or name.endswith(".markdown")
)
def is_json_artifact(artifact: Any) -> bool:
if not isinstance(artifact, dict):
return False
path = _artifact_path(artifact)
name = _artifact_name(artifact)
mime = _artifact_mime(artifact)
if not _in_outputs(path):
return False
return "json" in mime or path.endswith(".json") or name.endswith(".json")
def artifact_signature(artifact: dict[str, Any]) -> tuple[str, str, str]:
"""Use server-returned path/mtime/size to detect an actually rewritten file."""
return (
str(artifact.get("path") or artifact.get("artifact_url") or ""),
str(artifact.get("modified_at") or artifact.get("modifiedAt") or ""),
str(artifact.get("size_bytes") or artifact.get("sizeBytes") or ""),
)
def markdown_delivery_changed(
previous_artifacts: Any,
incoming_artifacts: list[dict[str, Any]],
) -> bool:
"""Whether this turn rewrote a Markdown deliverable, not just chatted.
A completed node can receive normal follow-up Q&A. That must not bump its
effective delivery revision or invalidate every downstream stage unless a
Markdown report really changed. The standard artifact listing includes
``modified_at`` and ``size_bytes``, which together make a stable lightweight
version marker without reading a potentially large file again.
"""
old = previous_artifacts if isinstance(previous_artifacts, list) else []
old_signatures = {
artifact_signature(item) for item in old if is_markdown_artifact(item)
}
new_signatures = {
artifact_signature(item) for item in incoming_artifacts if is_markdown_artifact(item)
}
return bool(new_signatures - old_signatures)
def is_intent_position_node(
position_id: str | None,
intent_position_id: str | None = None,
) -> bool:
"""Whether a node is the special intent position (answers need no report)."""
position = str(position_id or "").strip()
if intent_position_id:
return position == intent_position_id
# Existing persisted sessions predate the configurable directory. Retain
# their historical interpretation until they are archived/recreated.
return position.lower() in {"intelligence", "intel", "intent"}
def session_intent_position_id(chain_snapshot: Any) -> str | None:
"""Read the frozen intent-position id from an activated chain snapshot."""
chain = chain_snapshot if isinstance(chain_snapshot, dict) else {}
value = chain.get("_intent_position_id")
return value.strip() if isinstance(value, str) and value.strip() else None
@@ -60,6 +60,10 @@ class PositionRoundtableSessionRow(Base):
# intent_pending -> active -> completed / archived. The router owns legal
# transitions; the DB keeps it as a concise, portable string.
status: Mapped[str] = mapped_column(String(32), nullable=False, default="intent_pending", index=True)
# 乐观并发控制版本号:保护「确定意图 / 激活链 / 归档」等 session 级变更。
# 每次 session 写操作自增;传入 expected_version 时做 ``WHERE version=?`` CAS,
# 命中 0 行即并发冲突(消除两个用户同时激活/归档同一 session 的竞态)。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
created_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC)
)
@@ -101,6 +105,11 @@ class PositionRoundtableNodeRow(Base):
# position Session removes every recovery snapshot through the FK cascade.
conversation_snapshot: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
revision: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
# 乐观并发控制版本号:每次 update_node 自增;传入 expected_version 时做
# ``WHERE version=?`` 校验,命中 0 行即并发冲突。与 revision(业务交付计数)
# 刻意解耦——revision 仅在真正交付新 Markdown 报告时 +1,version 在任意字段
# 变更时 +1,专用于消除「complete_node_turn 多步状态机」并发盲写丢失更新。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
upstream_revision: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
rejection_count: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
last_rejection: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
@@ -114,3 +123,38 @@ class PositionRoundtableNodeRow(Base):
default=lambda: datetime.now(UTC),
onupdate=lambda: datetime.now(UTC),
)
class PositionRoundtableCommandRow(Base):
"""命令幂等记录:同一次客户端操作(由 command_id 标识)只执行一次。
网络重试 / 双击 / beforeunload beacon 可能把同一命令送达多次。靠
``UNIQUE(session_id, node_key, command_id)`` 让数据库天然去重:第二次到达时
命中已有记录,直接返回 ``result_json``(上次结果),绝不重复推进状态机。
``payload_hash`` 防止客户端误复用 command_id 发送不同参数——同 command_id 但
payload 不同 → 409。session 级命令(activate/archive)node_key 存空串。
"""
__tablename__ = "position_roundtable_commands"
__table_args__ = (
UniqueConstraint(
"session_id", "node_key", "command_id",
name="uq_position_roundtable_commands_session_node_cmd",
),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
session_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
# 命令作用的节点;session 级命令(activate/archive/delete)存空串 ""。
node_key: Mapped[str] = mapped_column(String(256), nullable=False, default="")
# 客户端生成的幂等键(一次点击/重试共用)。
command_id: Mapped[str] = mapped_column(String(64), nullable=False)
# complete / bind / reject / conversation / activate / archive / delete
command_type: Mapped[str] = mapped_column(String(32), nullable=False)
# 规范化 payload 的 sha256;同 command_id 但 hash 不同 → 409(防误复用)。
payload_hash: Mapped[str] = mapped_column(String(64), nullable=False)
# 上次执行结果的 JSON 序列化,重放时原样返回。
result_json: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
created_at: Mapped[datetime] = mapped_column(
BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC)
)
@@ -2,6 +2,7 @@
from __future__ import annotations
import hashlib
import json
from datetime import UTC, datetime
from typing import Any
@@ -11,7 +12,14 @@ from sqlalchemy import delete, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.position_roundtable.delivery import (
is_intent_position_node,
is_markdown_artifact,
markdown_delivery_changed,
session_intent_position_id,
)
from deerflow.persistence.position_roundtable.model import (
PositionRoundtableCommandRow,
PositionRoundtableNodeRow,
PositionRoundtableSessionRow,
)
@@ -42,6 +50,85 @@ def _has_material(row: PositionRoundtableNodeRow) -> bool:
return row.revision > 0 or bool(row.latest_answer) or bool(_loads(row.artifact_manifest))
def _has_confirmed_intent_snapshot(intent: Any) -> bool:
"""Return whether a persisted Step-1 snapshot may activate a chain.
This duplicates only the storage-level shape check used by the router so
activation can re-check the prerequisite *after* locking the session row.
A router-only pre-check leaves a TOCTOU window where another user can
overwrite the intent before the chain topology is frozen.
"""
if not isinstance(intent, dict):
return False
required_sections = ("coreGoals", "riskWarnings", "keyPoints", "strategicSignificance")
if any(key in intent for key in required_sections):
if not all(isinstance(intent.get(key), list) for key in required_sections):
return False
return bool(intent["coreGoals"] or intent["strategicSignificance"])
objective = intent.get("objective") or intent.get("goal")
return bool(isinstance(objective, str) and objective.strip() and isinstance(intent.get("constraints"), list))
class NodeConcurrentWriteError(Exception):
"""节点被并发改写,调用方持有的 version 已过期(乐观锁冲突)。
由 ``update_node(expected_version=...)`` / ``recompute_chain_state`` 在检测到
version 不匹配时抛出。调用方可捕获后重新读取最新状态重算(幂等重入)。
"""
def __init__(
self,
node_key: str,
*,
expected: int | None = None,
actual: int | None = None,
) -> None:
self.node_key = node_key
self.expected = expected
self.actual = actual
super().__init__(
f"concurrent write detected on position node {node_key}"
+ (f" (expected version {expected}, got {actual})" if expected is not None else "")
)
class SessionWriteConflictError(Exception):
"""Session-level state changed after a route's optimistic pre-check.
The public routes translate this into HTTP 409. Keeping the exception at
the persistence boundary prevents a stale intent/task save from reviving
an archived session or changing the frozen input of an active chain.
"""
def __init__(self, detail: str) -> None:
self.detail = detail
super().__init__(detail)
class CommandConflictError(Exception):
"""命令在锁内判定为业务冲突(→ HTTP 409),事务已回滚、未改任何状态。
与「幂等重放」严格区分:重放返回上次成功结果;冲突说明状态机拒绝该命令
(节点未解锁 / 已绑定其它线程 / 同 command_id 携带了不同参数等)。
``detail`` 是面向用户的提示,router 直接转成 409。
"""
def __init__(self, detail: str) -> None:
self.detail = detail
super().__init__(detail)
def _payload_hash(command_type: str, payload: dict[str, Any]) -> str:
"""规范化命令参数的 sha256,用于「同 command_id 是否同一参数」判定。"""
normalized = json.dumps(
{"type": command_type, "payload": payload},
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
)
return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
class PositionRoundtableRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
@@ -70,6 +157,7 @@ class PositionRoundtableRepository:
"action_plan_snapshot": _loads(row.action_plan_snapshot),
"action_plan_conversation": _loads(row.action_plan_conversation),
"status": row.status,
"version": row.version,
"created_at": _time(row.created_at),
"updated_at": _time(row.updated_at),
}
@@ -90,6 +178,7 @@ class PositionRoundtableRepository:
"artifact_manifest": _loads(row.artifact_manifest) or [],
"conversation_snapshot": _loads(row.conversation_snapshot),
"revision": row.revision,
"version": row.version,
"upstream_revision": _loads(row.upstream_revision),
"rejection_count": row.rejection_count or 0,
"last_rejection": _loads(row.last_rejection),
@@ -294,11 +383,32 @@ class PositionRoundtableRepository:
action_plan_snapshot: dict[str, Any] | None | object = _UNSET,
action_plan_conversation: dict[str, Any] | None | object = _UNSET,
status: str | object = _UNSET,
allowed_statuses: set[str] | None = None,
) -> dict[str, Any] | None:
"""Update one session snapshot under the same row lock as commands.
Snapshot persistence used to do an unlocked ORM ``get`` followed by a
write. That permitted a stale "confirm intent" save to land after a
concurrent activation/archival, or allowed two different snapshot
surfaces to overwrite each other's unseen values. Acquiring the
parent row lock serializes all session writes with node/session
commands. ``allowed_statuses`` additionally freezes task/intent
inputs once the business chain has become active.
"""
async with self._sf() as session:
row = await session.get(PositionRoundtableSessionRow, session_id)
row = (
await session.execute(
select(PositionRoundtableSessionRow)
.where(PositionRoundtableSessionRow.id == session_id)
.with_for_update()
)
).scalar_one_or_none()
if row is None or not self._can_access(row, user_id):
return None
if row.status == "archived":
raise SessionWriteConflictError("该岗位协同会话已归档,仅可查看历史记录")
if allowed_statuses is not None and row.status not in allowed_statuses:
raise SessionWriteConflictError("会话已启动,不能再修改已冻结的任务或意图")
if task_snapshot is not _UNSET:
row.task_snapshot = _dumps(task_snapshot)
if intent_thread_id is not _UNSET:
@@ -321,6 +431,7 @@ class PositionRoundtableRepository:
row.action_plan_conversation = _dumps(action_plan_conversation)
if status is not _UNSET:
row.status = str(status)
row.version += 1
row.updated_at = datetime.now(UTC)
await session.commit()
await session.refresh(row)
@@ -425,6 +536,7 @@ class PositionRoundtableRepository:
upstream_revision: dict[str, Any] | object = _UNSET,
last_rejection: dict[str, Any] | None | object = _UNSET,
invalidated_by: str | None | object = _UNSET,
expected_version: int | None = None,
increment_revision: bool = False,
increment_rejection: bool = False,
) -> dict[str, Any] | None:
@@ -436,9 +548,17 @@ class PositionRoundtableRepository:
PositionRoundtableNodeRow.session_id == session_id,
PositionRoundtableNodeRow.node_key == node_key,
).limit(1)
# 乐观锁:传入 expected_version 时加行锁并校验,杜绝「检查后到提交之间
# 被并发改写」的 TOCTOU。recompute_chain_state 不走这里(它自管事务)。
if expected_version is not None:
stmt = stmt.with_for_update()
row = (await session.execute(stmt)).scalars().first()
if row is None:
return None
if expected_version is not None and row.version != expected_version:
raise NodeConcurrentWriteError(
node_key, expected=expected_version, actual=row.version
)
if thread_id is not _UNSET:
row.thread_id = thread_id or None
if status is not _UNSET:
@@ -455,6 +575,8 @@ class PositionRoundtableRepository:
row.last_rejection = _dumps(last_rejection)
if invalidated_by is not _UNSET:
row.invalidated_by = invalidated_by or None
# 任意字段变更都 bump version(乐观锁单调递增),与业务交付 revision 解耦。
row.version += 1
if increment_revision:
row.revision += 1
if increment_rejection:
@@ -464,6 +586,734 @@ class PositionRoundtableRepository:
await session.refresh(row)
return self._node_dict(row)
async def recompute_chain_state(
self,
session_id: str,
node_key: str,
user_id: str,
*,
next_status: str,
latest_answer: str | None,
artifact_manifest: list[dict[str, Any]] | None,
upstream_revision: dict[str, Any] | None,
new_effective_delivery: bool,
) -> dict[str, Any] | None:
"""在单一 ``FOR UPDATE`` 事务内原子完成「本节点交付 → 下游失效 → 解锁下一 stage」。
把原来 router 里由若干个独立提交的 ``update_node`` 拼成的状态转移收敛成一个
事务:先锁住本 session 全部节点行(MySQL ``SELECT ... FOR UPDATE``),再在锁
内重算所有节点状态,一次提交。同一 session 的并发 ``complete_node_turn`` 因此被
数据库行锁串行化,彻底消除 TOCTOU / 丢失更新导致的「下一 stage 卡 locked /
invalidated_by 残留 → 下一阶段拿不到上游产物」断链。
幂等可重入:解锁不假设「最后一个 seat 负责」,而是遍历每个「全 done」stage 补
解锁其紧邻下一 stage 的 locked 节点;多次调用结果一致。``next_status`` /
``new_effective_delivery`` 等业务判定由 router 基于调用前快照算好传入,本方法
只负责把它们原子地落到节点状态机上。
"""
async with self._sf() as session:
parent = await session.get(PositionRoundtableSessionRow, session_id)
if parent is None or not self._can_access(parent, user_id):
return None
# 锁住本 session 全部节点行,串行化并发状态转移(行锁持有至 commit)。
rows = (
await session.execute(
select(PositionRoundtableNodeRow)
.where(PositionRoundtableNodeRow.session_id == session_id)
.order_by(
PositionRoundtableNodeRow.stage_index,
PositionRoundtableNodeRow.seat_index,
)
.with_for_update()
)
).scalars().all()
if not rows:
return None
by_key = {r.node_key: r for r in rows}
current = by_key.get(node_key)
if current is None:
return None
now = datetime.now(UTC)
# 本次交付前的 revision(用于判断「此前已交付过 → 新交付需失效下游」)。
old_revision = current.revision
# ① 落本节点交付状态。
current.status = next_status
current.latest_answer = latest_answer
if artifact_manifest is not None:
current.artifact_manifest = _dumps(artifact_manifest)
if upstream_revision is not None:
current.upstream_revision = _dumps(upstream_revision)
current.invalidated_by = None
if new_effective_delivery:
current.revision += 1
current.version += 1
current.updated_at = now
# ② + ③ 与命令式状态机共用同一套下游失效 / 幂等解锁实现,避免逻辑漂移。
self._invalidate_downstream(rows, current, new_effective_delivery, old_revision, now)
self._recompute_unlocks(rows, now)
await session.commit()
await session.refresh(current)
return self._node_dict(current)
# ── command-style state machine ──────────────────────────────────────────
async def apply_node_command(
self,
session_id: str,
node_key: str,
user_id: str,
*,
command_id: str,
command_type: str,
payload: dict[str, Any] | None = None,
expected_session_version: int | None = None,
) -> dict[str, Any]:
"""命令式状态机:所有节点级写命令(complete/bind/conversation/reject)的唯一入口。
单事务内依次完成:
① ``SELECT ... FOR UPDATE`` 锁住 session 行(可选 ``expected_session_version``
CAS,命中失败即 409);
② 命令幂等判定——``UNIQUE(session_id, node_key, command_id)`` 命中已有记录:
参数一致(payload_hash 相同)→ 原样重放上次结果;参数不同 → 409;
③ 锁住本 session 全部节点行,**基于锁内状态**做所有业务判定
(能否完成 / 是否新交付 / 能否驳回),绝不信任调用方传入的过期快照;
④ 应用状态转移(本节点更新 → 下游失效 → 幂等重算解锁);
⑤ 写入命令幂等记录(含结果 JSON),一次提交。
返回 dict:
- ``ok=True`` — ``replayed`` 标记是否幂等重放;``node`` 为目标节点新状态,
``reject`` 命令额外返回 ``nodes``(全部节点)与 ``session``;
- ``ok=False`` — ``http_status``(404/409)+ ``detail``;事务已回滚,状态未变。
一致性只来自数据库:并发命令被 session/节点行锁串行化,重试/双击/beacon 由
命令唯一键去重。进程内任何缓存都不参与正确性。
"""
payload = payload or {}
payload_hash = _payload_hash(command_type, payload)
now = datetime.now(UTC)
async def _run(session: AsyncSession) -> dict[str, Any]:
parent = (
await session.execute(
select(PositionRoundtableSessionRow)
.where(PositionRoundtableSessionRow.id == session_id)
.with_for_update()
)
).scalar_one_or_none()
if parent is None or not self._can_access(parent, user_id):
return {"ok": False, "http_status": 404, "detail": "Position roundtable session not found"}
if expected_session_version is not None and parent.version != expected_session_version:
return {
"ok": False,
"http_status": 409,
"detail": "会话状态已更新,请刷新后重试",
"session": self._session_dict(parent),
}
# 归档后的会话拒绝一切写命令(锁内复检,杜绝路由预检与提交之间的窗口)。
if parent.status == "archived":
return {
"ok": False,
"http_status": 409,
"detail": "该岗位协同会话已归档,仅可查看历史记录",
}
# ② 命令幂等:同 command_id 已执行过 → 重放上次结果(或 409)。
existing = (
await session.execute(
select(PositionRoundtableCommandRow).where(
PositionRoundtableCommandRow.session_id == session_id,
PositionRoundtableCommandRow.node_key == (node_key or ""),
PositionRoundtableCommandRow.command_id == command_id,
)
)
).scalars().first()
if existing is not None:
if existing.payload_hash != payload_hash:
return {
"ok": False,
"http_status": 409,
"detail": "相同操作标识携带了不同参数,已拒绝执行",
}
return {
"ok": True,
"replayed": True,
"command_type": command_type,
**(_loads(existing.result_json) or {}),
}
# ③ 锁住全部节点行(行锁持有至 commit),串行化同 session 并发命令。
rows = (
await session.execute(
select(PositionRoundtableNodeRow)
.where(PositionRoundtableNodeRow.session_id == session_id)
.order_by(
PositionRoundtableNodeRow.stage_index,
PositionRoundtableNodeRow.seat_index,
)
.with_for_update()
)
).scalars().all()
by_key = {r.node_key: r for r in rows}
if command_type == "complete":
result = self._apply_complete(by_key, node_key, parent, payload, now)
elif command_type == "bind":
result = self._apply_bind(by_key, node_key, payload, now)
elif command_type == "conversation":
result = self._apply_conversation(by_key, node_key, payload, now)
elif command_type == "reject":
result = self._apply_reject(by_key, node_key, parent, payload, user_id, now)
else:
return {"ok": False, "http_status": 400, "detail": f"unknown command type: {command_type}"}
if not result.get("ok", True):
return result
# ⑤ 写命令幂等记录(与状态转移同事务提交)。
stored = {k: v for k, v in result.items() if k != "ok"}
session.add(
PositionRoundtableCommandRow(
id=uuid4().hex,
session_id=session_id,
node_key=node_key or "",
command_id=command_id,
command_type=command_type,
payload_hash=payload_hash,
result_json=_dumps(stored),
created_at=now,
)
)
parent.version += 1
parent.updated_at = now
result["replayed"] = False
result["command_type"] = command_type
return result
try:
async with self._sf() as session:
outcome = await _run(session)
if outcome.get("ok", False):
await session.commit()
else:
await session.rollback()
return outcome
except IntegrityError:
# 命令唯一键并发竞态:另一连接已用同一 command_id 提交。读回其结果重放。
async with self._sf() as session:
existing = (
await session.execute(
select(PositionRoundtableCommandRow).where(
PositionRoundtableCommandRow.session_id == session_id,
PositionRoundtableCommandRow.node_key == (node_key or ""),
PositionRoundtableCommandRow.command_id == command_id,
)
)
).scalars().first()
if existing is not None:
if existing.payload_hash != payload_hash:
return {
"ok": False,
"http_status": 409,
"detail": "相同操作标识携带了不同参数,已拒绝执行",
}
return {
"ok": True,
"replayed": True,
"command_type": command_type,
**(_loads(existing.result_json) or {}),
}
raise
# ── command handlers(全部在 FOR UPDATE 锁内调用,入参为锁定的行) ─────────
def _apply_complete(
self,
by_key: dict[str, PositionRoundtableNodeRow],
node_key: str,
parent: PositionRoundtableSessionRow,
payload: dict[str, Any],
now: datetime,
) -> dict[str, Any]:
"""complete-turn:锁内判定能否完成 / 是否新交付,原子落状态机。"""
current = by_key.get(node_key)
if current is None:
return {"ok": False, "http_status": 404, "detail": "Position roundtable node not found"}
if current.status == "locked":
return {"ok": False, "http_status": 409, "detail": "上游节点尚未完成,当前节点未解锁"}
if current.invalidated_by:
return {
"ok": False,
"http_status": 409,
"detail": "上游产物已被驳回或重做,当前节点需等待前序节点重新完成",
}
# 请求未带产物清单 → 沿用锁内的当前清单(绝不用调用方的过期快照兜底)。
incoming = payload.get("artifact_manifest")
current_manifest = _loads(current.artifact_manifest) or []
effective_artifacts = incoming if isinstance(incoming, list) and incoming else current_manifest
latest_answer = payload.get("latest_answer")
upstream_revision = payload.get("upstream_revision")
has_markdown = any(is_markdown_artifact(item) for item in effective_artifacts)
markdown_changed = markdown_delivery_changed(current_manifest, effective_artifacts)
requires_fresh_delivery = current.status in {"rejected", "stale"}
intent_position_id = session_intent_position_id(_loads(parent.chain_snapshot))
is_intent_node = is_intent_position_node(current.position_id, intent_position_id)
next_status = (
"done"
if is_intent_node
else "done"
if has_markdown and (not requires_fresh_delivery or markdown_changed)
else "running"
)
# 有效 revision 是「交付 revision」,不是每一次对话应答。已完成节点上的普通
# 追问,不能仅因其旧 Markdown 仍出现在清单里就失效所有下游 stage。
new_effective_delivery = (
next_status == "done"
and (is_intent_node or current.status != "done" or markdown_changed)
)
old_revision = current.revision
# ④ 落本节点交付状态。
current.status = next_status
current.latest_answer = latest_answer
current.artifact_manifest = _dumps(effective_artifacts)
if upstream_revision is not None:
current.upstream_revision = _dumps(upstream_revision)
current.invalidated_by = None
if new_effective_delivery:
current.revision += 1
current.version += 1
current.updated_at = now
self._invalidate_downstream(by_key.values(), current, new_effective_delivery, old_revision, now)
self._recompute_unlocks(by_key.values(), now)
return {"ok": True, "node": self._node_dict(current)}
def _apply_bind(
self,
by_key: dict[str, PositionRoundtableNodeRow],
node_key: str,
payload: dict[str, Any],
now: datetime,
) -> dict[str, Any]:
"""bind-thread:锁内校验解锁/失效/线程占用后绑定。"""
current = by_key.get(node_key)
if current is None:
return {"ok": False, "http_status": 404, "detail": "Position roundtable node not found"}
thread_id = str(payload.get("thread_id") or "").strip()
if not thread_id:
return {"ok": False, "http_status": 400, "detail": "thread_id is required"}
if current.status == "locked":
return {"ok": False, "http_status": 409, "detail": "上游节点尚未完成,当前节点未解锁"}
if current.invalidated_by:
return {
"ok": False,
"http_status": 409,
"detail": "上游产物已被驳回或重做,当前节点需等待前序节点重新完成",
}
if current.thread_id and current.thread_id != thread_id:
return {"ok": False, "http_status": 409, "detail": "该节点已绑定另一条对话线程"}
current.thread_id = thread_id
if current.status == "ready":
current.status = "running"
current.version += 1
current.updated_at = now
return {"ok": True, "node": self._node_dict(current)}
def _apply_conversation(
self,
by_key: dict[str, PositionRoundtableNodeRow],
node_key: str,
payload: dict[str, Any],
now: datetime,
) -> dict[str, Any]:
"""conversation:对话快照持久化(UI 恢复用),锁内校验线程归属。"""
current = by_key.get(node_key)
if current is None:
return {"ok": False, "http_status": 404, "detail": "Position roundtable node not found"}
thread_id = payload.get("thread_id")
if thread_id and current.thread_id and current.thread_id != thread_id:
return {"ok": False, "http_status": 409, "detail": "Position node is bound to another thread"}
if thread_id and not current.thread_id:
current.thread_id = thread_id
current.conversation_snapshot = _dumps(payload.get("conversation_snapshot"))
current.version += 1
current.updated_at = now
return {"ok": True, "node": self._node_dict(current)}
def _apply_reject(
self,
by_key: dict[str, PositionRoundtableNodeRow],
node_key: str,
parent: PositionRoundtableSessionRow,
payload: dict[str, Any],
user_id: str,
now: datetime,
) -> dict[str, Any]:
"""reject:驳回一个已交付节点并失效全部下游 stage(锁内判定可驳回性)。"""
rows = sorted(
by_key.values(), key=lambda r: (r.stage_index, r.seat_index)
)
target = by_key.get(node_key)
if target is None:
return {"ok": False, "http_status": 404, "detail": "Position roundtable node not found"}
if target.status == "locked":
return {"ok": False, "http_status": 409, "detail": "当前节点尚未解锁,暂无可驳回的交付产物"}
if (
target.revision <= 0
and not target.latest_answer
and not _loads(target.artifact_manifest)
):
return {"ok": False, "http_status": 409, "detail": "当前节点暂无可驳回的交付产物"}
rejection = {
"title": str(payload.get("title") or "").strip() or "产物驳回",
"reason": str(payload.get("reason") or "").strip(),
"rejected_by": user_id,
"rejected_at": now.isoformat(),
}
summary_snapshot = _loads(parent.summary_snapshot)
if isinstance(summary_snapshot, dict) and summary_snapshot.get("status") == "done":
parent.summary_snapshot = _dumps(
{
**summary_snapshot,
"status": "stale",
"invalidated_by": target.node_key,
"invalidated_at": now.isoformat(),
}
)
action_plan_snapshot = _loads(parent.action_plan_snapshot)
if isinstance(action_plan_snapshot, dict) and action_plan_snapshot.get("status") == "done":
parent.action_plan_snapshot = _dumps(
{
**action_plan_snapshot,
"status": "stale",
"invalidated_by": target.node_key,
"invalidated_at": now.isoformat(),
}
)
if parent.status == "completed":
parent.status = "active"
target.status = "rejected"
target.last_rejection = _dumps(rejection)
target.rejection_count += 1
target.invalidated_by = None
target.version += 1
target.updated_at = now
for row in rows:
if row.stage_index <= target.stage_index:
continue
if _has_material(row) or row.status in {"running", "done", "stale", "rejected", "error"}:
row.status = "stale"
else:
row.status = "locked"
row.invalidated_by = target.node_key
row.version += 1
row.updated_at = now
return {
"ok": True,
"session": self._session_dict(parent),
"nodes": [self._node_dict(row) for row in rows],
}
@staticmethod
def _invalidate_downstream(
rows: Any,
current: PositionRoundtableNodeRow,
new_effective_delivery: bool,
old_revision: int,
now: datetime,
) -> None:
"""新交付且本节点此前已交付过 → 后续 stage 全部失效(需重做)。"""
if not (new_effective_delivery and old_revision > 0):
return
for downstream in rows:
if (
downstream.stage_index > current.stage_index
and downstream.status in {"ready", "running", "done", "stale", "rejected", "error"}
):
downstream.status = "stale" if _has_material(downstream) else "locked"
downstream.invalidated_by = current.node_key
downstream.version += 1
downstream.updated_at = now
@staticmethod
def _recompute_unlocks(rows: Any, now: datetime) -> None:
"""幂等重算 stage 解锁:每个「全部 done」stage 解锁其紧邻下一 stage。
locked → ready;stale 保持 stale(产物过期需重做)但清掉 invalidated_by
(上游已就绪)。多次调用结果一致,不依赖调用时序。
"""
row_list = list(rows)
stage_indices = sorted({r.stage_index for r in row_list})
for stage in stage_indices:
stage_rows = [r for r in row_list if r.stage_index == stage]
if not stage_rows or not all(r.status == "done" for r in stage_rows):
continue
later = [t for t in stage_indices if t > stage]
if not later:
continue
next_stage = min(later)
for node in row_list:
if node.stage_index != next_stage:
continue
if node.status == "locked":
node.status = "ready"
node.invalidated_by = None
node.version += 1
node.updated_at = now
elif node.status == "stale":
node.invalidated_by = None
node.version += 1
node.updated_at = now
async def apply_session_command(
self,
session_id: str,
user_id: str,
*,
command_id: str,
command_type: str,
payload: dict[str, Any] | None = None,
expected_session_version: int | None = None,
) -> dict[str, Any]:
"""session 级命令(activate / archive / delete)的命令式入口。
与 ``apply_node_command`` 同一套原则:单事务锁 session 行(``FOR UPDATE``)
+ 命令唯一键幂等 + 锁内判定。返回结构同 ``apply_node_command``
(``ok`` / ``replayed`` / ``http_status`` / ``detail`` / ``session`` / ``nodes``)。
- ``activate`` — payload 需带 ``chain_id`` / ``chain_snapshot`` / ``nodes``。
锁内判定:已激活且链相同 → 幂等返回现有状态;链不同 → 409。
- ``archive`` — 已归档 → 幂等返回;否则置 archived。
- ``delete`` — 删除节点与会话(命令记录无外键,保留供重放)。
"""
payload = payload or {}
payload_hash = _payload_hash(command_type, payload)
now = datetime.now(UTC)
async def _replay_check(session: AsyncSession) -> dict[str, Any] | None:
existing = (
await session.execute(
select(PositionRoundtableCommandRow).where(
PositionRoundtableCommandRow.session_id == session_id,
PositionRoundtableCommandRow.node_key == "",
PositionRoundtableCommandRow.command_id == command_id,
)
)
).scalars().first()
if existing is None:
return None
if existing.payload_hash != payload_hash:
return {
"ok": False,
"http_status": 409,
"detail": "相同操作标识携带了不同参数,已拒绝执行",
}
return {
"ok": True,
"replayed": True,
"command_type": command_type,
**(_loads(existing.result_json) or {}),
}
async def _run(session: AsyncSession) -> dict[str, Any]:
# delete 之后 session 行已不存在,重试必须在锁 session 之前查命令记录。
replayed = await _replay_check(session)
if replayed is not None:
return replayed
parent = (
await session.execute(
select(PositionRoundtableSessionRow)
.where(PositionRoundtableSessionRow.id == session_id)
.with_for_update()
)
).scalar_one_or_none()
if parent is None or not self._can_access(parent, user_id):
return {"ok": False, "http_status": 404, "detail": "Position roundtable session not found"}
if expected_session_version is not None and parent.version != expected_session_version:
return {
"ok": False,
"http_status": 409,
"detail": "会话状态已更新,请刷新后重试",
"session": self._session_dict(parent),
}
if command_type == "activate":
result = await self._apply_activate(session, parent, payload, now)
elif command_type == "archive":
if parent.status == "archived":
result = {
"ok": True,
"session": self._session_dict(parent),
"nodes": [],
"already": True,
}
else:
parent.status = "archived"
parent.version += 1
parent.updated_at = now
result = {
"ok": True,
"session": self._session_dict(parent),
"nodes": [],
}
elif command_type == "delete":
await session.execute(
delete(PositionRoundtableNodeRow).where(
PositionRoundtableNodeRow.session_id == session_id
)
)
await session.execute(
delete(PositionRoundtableSessionRow).where(
PositionRoundtableSessionRow.id == session_id
)
)
result = {"ok": True, "deleted": True}
else:
return {"ok": False, "http_status": 400, "detail": f"unknown command type: {command_type}"}
if not result.get("ok", True):
return result
stored = {k: v for k, v in result.items() if k != "ok"}
session.add(
PositionRoundtableCommandRow(
id=uuid4().hex,
session_id=session_id,
node_key="",
command_id=command_id,
command_type=command_type,
payload_hash=payload_hash,
result_json=_dumps(stored),
created_at=now,
)
)
result["replayed"] = False
result["command_type"] = command_type
return result
try:
async with self._sf() as session:
outcome = await _run(session)
if outcome.get("ok", False):
await session.commit()
else:
await session.rollback()
return outcome
except IntegrityError:
# 命令唯一键并发竞态:读回已提交的那条命令结果重放。
async with self._sf() as session:
replayed = await _replay_check(session)
if replayed is not None:
return replayed
raise
async def _apply_activate(
self,
session: AsyncSession,
parent: PositionRoundtableSessionRow,
payload: dict[str, Any],
now: datetime,
) -> dict[str, Any]:
"""激活业务链:锁内判定「已激活 → 链相同幂等 / 链不同 409」,否则建节点。"""
existing_rows = (
await session.execute(
select(PositionRoundtableNodeRow)
.where(PositionRoundtableNodeRow.session_id == parent.id)
.order_by(
PositionRoundtableNodeRow.stage_index,
PositionRoundtableNodeRow.seat_index,
)
.with_for_update()
)
).scalars().all()
if parent.status == "archived":
return {
"ok": False,
"http_status": 409,
"detail": "该岗位协同会话已归档,仅可查看历史记录",
}
chain_id = str(payload.get("chain_id") or "")
if existing_rows:
# 已激活:同一业务链 → 幂等返回现有状态;不同链 → 冲突。
if parent.chain_id == chain_id:
return {
"ok": True,
"session": self._session_dict(parent),
"nodes": [self._node_dict(row) for row in existing_rows],
"already": True,
}
return {
"ok": False,
"http_status": 409,
"detail": "该会话已激活其他业务链条,不能重复激活",
}
if not _has_confirmed_intent_snapshot(_loads(parent.intent_snapshot)):
return {
"ok": False,
"http_status": 400,
"detail": "请先完成并保存任务意图",
}
chain_snapshot = payload.get("chain_snapshot") or {}
nodes = payload.get("nodes") or []
if not nodes:
return {"ok": False, "http_status": 400, "detail": "activate requires nodes"}
parent.chain_id = chain_id
parent.chain_snapshot = _dumps(chain_snapshot)
parent.status = "active"
parent.version += 1
parent.updated_at = now
node_rows = [
PositionRoundtableNodeRow(
id=uuid4().hex,
session_id=parent.id,
node_key=str(node["node_key"]),
stage_index=int(node["stage_index"]),
seat_index=int(node["seat_index"]),
agent_id=str(node["agent_id"]),
position_id=node.get("position_id") or None,
status=str(node.get("status") or "locked"),
latest_answer=node.get("latest_answer") or None,
artifact_manifest=_dumps(node.get("artifact_manifest") or []),
revision=int(node.get("revision") or 0),
upstream_revision=(
_dumps(node.get("upstream_revision"))
if node.get("upstream_revision") is not None
else None
),
created_at=now,
updated_at=now,
)
for node in nodes
]
session.add_all(node_rows)
# 同事务内 flush 拿到完整行状态,供命令记录与返回值使用。
await session.flush()
return {
"ok": True,
"session": self._session_dict(parent),
"nodes": [self._node_dict(row) for row in node_rows],
}
async def reject_node(
self,
session_id: str,
@@ -27,8 +27,14 @@ class RoundtableArtifactSubmissionStore(ABC):
*,
task_delivery_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any]:
"""Create or update the idempotent submission record for an artifact."""
"""Create or update the idempotent submission record for an artifact.
When *expected_version* is given it must match the current row version;
a mismatch indicates another writer committed first and the caller
should re-read and retry (HTTP 409).
"""
raise NotImplementedError
@abstractmethod
@@ -39,6 +45,7 @@ class RoundtableArtifactSubmissionStore(ABC):
*,
submission_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any] | None:
"""Mark a submission as cancelled without deleting its audit record."""
raise NotImplementedError
@@ -54,7 +54,10 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore)
*,
task_delivery_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any]:
from deerflow.persistence.roundtable_artifact_submissions.sql import SubmissionVersionConflict
key = submission_key(task_id, artifact)
row = self._rows.get((task_id, key))
values = _artifact_values(artifact)
@@ -67,6 +70,7 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore)
**values,
"task_delivery_id": task_delivery_id,
"submitted": True,
"version": 0,
"submitted_at": now,
"cancelled_at": None,
"created_by": actor_id,
@@ -79,6 +83,9 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore)
self._rows[(task_id, key)] = row
return deepcopy(row)
if expected_version is not None and row.get("version", 0) != expected_version:
raise SubmissionVersionConflict(deepcopy(row))
changed = (
not row["submitted"]
or row.get("task_delivery_id") != task_delivery_id
@@ -91,6 +98,7 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore)
{
"task_delivery_id": task_delivery_id,
"submitted": True,
"version": row.get("version", 0) + 1,
"submitted_at": now,
"cancelled_at": None,
"updated_by": actor_id,
@@ -108,16 +116,24 @@ class MemoryRoundtableArtifactSubmissionStore(RoundtableArtifactSubmissionStore)
*,
submission_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any] | None:
from deerflow.persistence.roundtable_artifact_submissions.sql import SubmissionVersionConflict
key = submission_key(task_id, artifact)
row = self._rows.get((task_id, key))
if row is None or (submission_id is not None and row["id"] != submission_id):
return None
if expected_version is not None and row.get("version", 0) != expected_version:
raise SubmissionVersionConflict(deepcopy(row))
if row["submitted"]:
now = _now()
row.update(
{
"submitted": False,
"version": row.get("version", 0) + 1,
"cancelled_at": now,
"updated_by": actor_id,
"cancelled_by": actor_id,
@@ -4,6 +4,7 @@ from __future__ import annotations
from datetime import UTC, datetime
import sqlalchemy as sa
from sqlalchemy import Boolean, Index, Integer, String, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
@@ -41,6 +42,9 @@ class RoundtableArtifactSubmissionRow(Base):
task_delivery_id: Mapped[str | None] = mapped_column(String(255), nullable=True)
submitted: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
# Phase 5 CAS: 每次状态变更 +1。submit/cancel 可带 expected_version 做乐观锁,
# FOR UPDATE + version 检查确保「旧 cancel 不得撤销新提交」。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=sa.text("0"))
submitted_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
cancelled_at: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
@@ -15,6 +15,21 @@ from deerflow.persistence.roundtable_artifact_submissions.memory import submissi
from deerflow.persistence.roundtable_artifact_submissions.model import RoundtableArtifactSubmissionRow
class SubmissionVersionConflict(Exception):
"""Stale ``expected_version`` — another writer committed first.
Carries the freshest row dict so the router can return it in the 409 body,
letting the client merge and retry.
"""
def __init__(self, row: dict[str, Any]) -> None:
self.row = row
super().__init__(
f"submission version conflict: expected_version does not match "
f"current version={row.get('version')}"
)
def _timestamp(value: datetime | None) -> str | None:
return value.isoformat() if isinstance(value, datetime) else value
@@ -34,6 +49,7 @@ def _to_dict(row: RoundtableArtifactSubmissionRow) -> dict[str, Any]:
"revision": row.revision,
"task_delivery_id": row.task_delivery_id,
"submitted": row.submitted,
"version": row.version,
"submitted_at": _timestamp(row.submitted_at),
"cancelled_at": _timestamp(row.cancelled_at),
"created_by": row.created_by,
@@ -92,34 +108,63 @@ class RoundtableArtifactSubmissionRepository(RoundtableArtifactSubmissionStore):
*,
task_delivery_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any]:
key = submission_key(task_id, artifact)
stmt = select(RoundtableArtifactSubmissionRow).where(
RoundtableArtifactSubmissionRow.task_id == task_id,
RoundtableArtifactSubmissionRow.idempotency_key == key,
)
async with self._sf() as session:
result = await session.execute(stmt)
row = result.scalars().first()
now = datetime.now(UTC)
created = row is None
if row is None:
row = RoundtableArtifactSubmissionRow(
id=uuid4().hex,
task_id=task_id,
idempotency_key=key,
task_delivery_id=task_delivery_id,
submitted=True,
submitted_at=now,
created_by=actor_id,
updated_by=actor_id,
submitted_by=actor_id,
created_at=now,
updated_at=now,
# 至多重试一次:第一轮 INSERT 遇唯一键冲突 → 第二轮 FOR UPDATE 读回做 CAS 更新。
for _attempt in range(2):
async with self._sf() as session:
result = await session.execute(
select(RoundtableArtifactSubmissionRow)
.where(
RoundtableArtifactSubmissionRow.task_id == task_id,
RoundtableArtifactSubmissionRow.idempotency_key == key,
)
.with_for_update()
)
_apply_artifact(row, artifact)
session.add(row)
elif _requires_submission_update(row, artifact, task_delivery_id):
row = result.scalars().first()
now = datetime.now(UTC)
if row is None:
# 新提交:INSERT,version=0。
row = RoundtableArtifactSubmissionRow(
id=uuid4().hex,
task_id=task_id,
idempotency_key=key,
task_delivery_id=task_delivery_id,
submitted=True,
submitted_at=now,
created_by=actor_id,
updated_by=actor_id,
submitted_by=actor_id,
created_at=now,
updated_at=now,
version=0,
)
_apply_artifact(row, artifact)
session.add(row)
try:
await session.commit()
except IntegrityError:
# 并发 INSERT 赢家已写入,rollback 后重试 FOR UPDATE 读回。
await session.rollback()
continue
await session.refresh(row)
return _to_dict(row)
# 行已存在 —— CAS 检查:expected_version 不匹配说明在此期间另一个
# 写入已提交(如新 submit 把 version 从 0 bump 到 1),旧 cancel 的
# expected_version=0 必须失败,不得撤销新提交。
# 注意:不调 session.rollback()——rollback 会 expire 所有 ORM 对象,
# 导致 _to_dict 访问属性时触发 lazy-load → MissingGreenlet。
# async with 退出时会自动回滚未提交事务并释放 FOR UPDATE 锁。
if expected_version is not None and row.version != expected_version:
raise SubmissionVersionConflict(_to_dict(row))
if not _requires_submission_update(row, artifact, task_delivery_id):
# 幂等:内容无变化,不 bump version。
return _to_dict(row)
_apply_artifact(row, artifact)
row.task_delivery_id = task_delivery_id
row.submitted = True
@@ -129,34 +174,12 @@ class RoundtableArtifactSubmissionRepository(RoundtableArtifactSubmissionStore):
row.submitted_by = actor_id
row.cancelled_by = None
row.updated_at = now
try:
row.version = row.version + 1
await session.commit()
except IntegrityError:
# Two callers can both observe a missing row. The unique key
# turns that race into a normal idempotent retry instead of a
# 500. If their non-key metadata differs, apply this request
# after loading the winner so PUT still has upsert semantics.
await session.rollback()
if not created:
raise
result = await session.execute(stmt)
row = result.scalars().first()
if row is None:
raise
if _requires_submission_update(row, artifact, task_delivery_id):
now = datetime.now(UTC)
_apply_artifact(row, artifact)
row.task_delivery_id = task_delivery_id
row.submitted = True
row.submitted_at = now
row.cancelled_at = None
row.updated_by = actor_id
row.submitted_by = actor_id
row.cancelled_by = None
row.updated_at = now
await session.commit()
await session.refresh(row)
return _to_dict(row)
await session.refresh(row)
return _to_dict(row)
raise RuntimeError("submit: retry loop exhausted (unexpected)")
async def cancel(
self,
@@ -165,24 +188,36 @@ class RoundtableArtifactSubmissionRepository(RoundtableArtifactSubmissionStore):
*,
submission_id: str | None = None,
actor_id: str | None = None,
expected_version: int | None = None,
) -> dict[str, Any] | None:
key = submission_key(task_id, artifact)
stmt = select(RoundtableArtifactSubmissionRow).where(
RoundtableArtifactSubmissionRow.task_id == task_id,
RoundtableArtifactSubmissionRow.idempotency_key == key,
)
async with self._sf() as session:
result = await session.execute(stmt)
result = await session.execute(
select(RoundtableArtifactSubmissionRow)
.where(
RoundtableArtifactSubmissionRow.task_id == task_id,
RoundtableArtifactSubmissionRow.idempotency_key == key,
)
.with_for_update()
)
row = result.scalars().first()
if row is None or (submission_id is not None and row.id != submission_id):
return None
if row.submitted:
now = datetime.now(UTC)
row.submitted = False
row.cancelled_at = now
row.updated_by = actor_id
row.cancelled_by = actor_id
row.updated_at = now
await session.commit()
await session.refresh(row)
if expected_version is not None and row.version != expected_version:
raise SubmissionVersionConflict(_to_dict(row))
if not row.submitted:
# 幂等:已取消,不 bump version。
return _to_dict(row)
now = datetime.now(UTC)
row.submitted = False
row.cancelled_at = now
row.updated_by = actor_id
row.cancelled_by = actor_id
row.updated_at = now
row.version = row.version + 1
await session.commit()
await session.refresh(row)
return _to_dict(row)
@@ -47,6 +47,9 @@ class RoundtableDraftRow(Base):
default=lambda: datetime.now(UTC),
onupdate=lambda: datetime.now(UTC),
)
# 乐观并发控制版本号:每次 update_draft 自增;传入 expected_version 时校验,命中
# 0 行即并发冲突(防 step2.runs 读-改-写丢失更新——后台作业与前台 PUT 并发)。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
class RoundtableRecommendHistoryRow(Base):
@@ -15,7 +15,7 @@ import re
from datetime import UTC, datetime
from typing import Any
from sqlalchemy import select
from sqlalchemy import case, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.roundtable_drafts.model import (
@@ -66,6 +66,23 @@ def _dumps(value: Any) -> str | None:
return json.dumps(value, ensure_ascii=False)
class DraftConcurrentWriteError(Exception):
"""乐观锁冲突:``update_draft(expected_version=...)`` 时版本号不匹配。
由后台作业 ``_write_run_to_draft`` 的读-改-写重试循环捕获:冲突时重新读取最新草稿、
重新合并 ``step2.runs[]``、再试。防多用户/多 worker 并发写同一草稿时后写覆盖先写。
"""
def __init__(self, draft_id: str, *, expected: int | None = None, actual: int | None = None) -> None:
self.draft_id = draft_id
self.expected = expected
self.actual = actual
super().__init__(
f"concurrent write detected on roundtable draft {draft_id} "
f"(expected version {expected}, got {actual})"
)
class RoundtableDraftRepository:
def __init__(self, session_factory: async_sessionmaker[AsyncSession]) -> None:
self._sf = session_factory
@@ -80,6 +97,8 @@ class RoundtableDraftRepository:
"task_id": row.task_id,
"title": row.title,
"furthest_step": row.furthest_step,
# 乐观锁版本号:列表也携带,供前端本地副本对账(冲突时重拉合并)。
"version": row.version,
# 所用业务链名(历史卡片展示用);无链条 → None → 前端显示「自由模式」。
"chain_title": _extract_chain_title(row.step2),
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
@@ -145,26 +164,60 @@ class RoundtableDraftRepository:
step2=_UNSET,
step3=_UNSET,
task_id=_UNSET,
expected_version: int | None = None,
) -> dict[str, Any] | None:
async with self._sf() as session:
row = await session.get(RoundtableDraftRow, draft_id)
"""原子条件 UPDATE:版本判定与字段写入发生在**同一条 SQL** 里。
一致性只来自数据库:``UPDATE ... WHERE id AND user_id AND version=`` 配合
rowcount 判定,多 worker 并发下不存在「读-改-写」的检查后竞争窗口。
``rowcount == 0`` 时再回读区分「不存在/非本人」(返回 None)与
「版本冲突」(抛 :class:`DraftConcurrentWriteError`)。
"""
values: dict[str, Any] = {
"version": RoundtableDraftRow.version + 1,
"updated_at": datetime.now(UTC),
}
if task_id is not _UNSET and task_id is not None:
values["task_id"] = str(task_id)
if title is not _UNSET and title is not None:
values["title"] = str(title).strip()
if furthest_step is not _UNSET and furthest_step is not None:
# furthest_step 单调不回退:迟到的自动保存不得把已推进的步骤拉回去。
step_value = int(furthest_step)
values["furthest_step"] = case(
(RoundtableDraftRow.furthest_step >= step_value, RoundtableDraftRow.furthest_step),
else_=step_value,
)
if step1 is not _UNSET:
values["step1"] = _dumps(step1)
if step2 is not _UNSET:
values["step2"] = _dumps(step2)
if step3 is not _UNSET:
values["step3"] = _dumps(step3)
where = [
RoundtableDraftRow.id == draft_id,
# 个人草稿严格按 user 隔离(task 聊天记录已迁出到独立存储)。
if row is None or row.user_id != user_id:
RoundtableDraftRow.user_id == user_id,
]
if expected_version is not None:
where.append(RoundtableDraftRow.version == expected_version)
async with self._sf() as session:
result = await session.execute(
update(RoundtableDraftRow).where(*where).values(**values)
)
if result.rowcount == 0:
if expected_version is not None:
# 回读区分冲突与不存在(回读在冲突分支,正常路径零额外开销)。
existing = await session.get(RoundtableDraftRow, draft_id)
if existing is not None and existing.user_id == user_id:
raise DraftConcurrentWriteError(
draft_id, expected=expected_version, actual=existing.version
)
return None
if task_id is not _UNSET and task_id is not None:
row.task_id = str(task_id)
if title is not _UNSET and title is not None:
row.title = str(title).strip()
if furthest_step is not _UNSET and furthest_step is not None:
row.furthest_step = int(furthest_step)
if step1 is not _UNSET:
row.step1 = _dumps(step1)
if step2 is not _UNSET:
row.step2 = _dumps(step2)
if step3 is not _UNSET:
row.step3 = _dumps(step3)
row.updated_at = datetime.now(UTC)
await session.commit()
row = await session.get(RoundtableDraftRow, draft_id)
await session.refresh(row)
return self._draft_to_dict(row)
@@ -19,7 +19,8 @@ from __future__ import annotations
from datetime import UTC, datetime
from sqlalchemy import Integer, String, Text
import sqlalchemy as sa
from sqlalchemy import Boolean, Integer, String, Text, UniqueConstraint
from sqlalchemy.orm import Mapped, mapped_column
from deerflow.persistence.base import Base
@@ -28,6 +29,13 @@ from deerflow.persistence.types import BeijingDateTime, PortableLongText
class RoundtableJobRow(Base):
__tablename__ = "roundtable_jobs"
__table_args__ = (
# 「同一 scope 至多一个活跃作业」由该唯一键强制(Phase 3):活跃时存
# sha256(draft_id + task_id|user_id),进入终态时清 NULL;MySQL/SQLite 唯一索引
# 都允许多个 NULL,故终态历史作业不占键。INSERT 冲突即幂等命中 —— 一致性来自
# DB 唯一键,不再依赖 GET_LOCK 命名锁。
UniqueConstraint("active_dedupe_key", name="uq_roundtable_jobs_active_dedupe_key"),
)
id: Mapped[str] = mapped_column(String(64), primary_key=True)
# The draft/session this job runs for. Indexed for "active job of draft" lookups.
@@ -37,6 +45,24 @@ class RoundtableJobRow(Base):
# **不按 user 分权**(任何人打开同一 task 都能看在跑的研讨);其 draft_id 指向独立的
# ``roundtable_task_drafts`` 表。为空 = 普通个人作业(按 user 分权)。
task_id: Mapped[str | None] = mapped_column(String(128), nullable=True, index=True)
# ── Phase 3:唯一活跃键 + 租约 + dispatcher ──────────────────────────────
# 前端启动请求的幂等键(同键重试返回同一作业)与入参指纹(审计/排查)。
request_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
request_hash: Mapped[str | None] = mapped_column(String(64), nullable=True)
# 活跃去重键:活跃(非终态)时 = sha256(draft_id + task_id|user_id),终态清 NULL。
# 唯一索引(__table_args__)保证「同一 scope 至多一个活跃作业」——INSERT 冲突即幂等。
active_dedupe_key: Mapped[str | None] = mapped_column(String(64), nullable=True)
# 启动入参完整 JSON 快照:dispatcher 在任意 worker 领取 queued/租约过期作业时
# 据此重建 StartParams(跨进程可接管的前提;resume 续跑也重写本列)。
input_snapshot: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
# 租约:条件 UPDATE 抢占(queued 或租约过期)+ 心跳续租;worker 崩溃后租约自然过期,
# 其它 worker 接管。恢复能力来自 DB 而非进程内存。
lease_owner: Mapped[str | None] = mapped_column(String(64), nullable=True)
lease_until: Mapped[datetime | None] = mapped_column(BeijingDateTime(), nullable=True)
# 被 dispatcher 领取执行的次数(接管计数)。
attempt: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=sa.text("0"))
# 行级 CAS 版本:条件 UPDATE 乐观锁,防止并发写互相覆盖。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default=sa.text("0"))
# Job status machine (§2.1): queued / running / awaiting_input / done / error / cancelled.
status: Mapped[str] = mapped_column(String(32), nullable=False, default="queued", index=True)
# Fine-grained phase (§2.2): initializing / leader_thinking / dispatching /
@@ -71,6 +97,11 @@ class RoundtableJobRow(Base):
step3: Mapped[str | None] = mapped_column(PortableLongText, nullable=True)
# Terminal error detail when status=error.
error: Mapped[str | None] = mapped_column(Text, nullable=True)
# 草稿回写 pending 标记:``_write_run_to_draft`` 乐观锁重试耗尽后置 1(绝不退化
# last-write-wins 盲写);由 outbox 补偿器投影结果到草稿后清 0。一致性来自 DB 标记。
draft_persist_pending: Mapped[bool] = mapped_column(
Boolean, nullable=False, default=False, server_default=sa.false()
)
# 时间列必须用 BeijingDateTime(项目规范,与 ai_writing_sessions / roundtable_drafts 对齐)。
created_at: Mapped[datetime] = mapped_column(BeijingDateTime(), nullable=False, default=lambda: datetime.now(UTC))
updated_at: Mapped[datetime] = mapped_column(
@@ -12,11 +12,14 @@ threading a user id through, while gateway routes pass it explicitly.
from __future__ import annotations
import hashlib
import json
import logging
from datetime import UTC, datetime
from typing import Any
from sqlalchemy import delete, select
from sqlalchemy import delete, or_, select, update
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.roundtable_jobs.model import RoundtableJobRow
@@ -24,8 +27,36 @@ from deerflow.runtime.user_context import AUTO, _AutoSentinel, resolve_user_id
_UNSET = object()
logger = logging.getLogger(__name__)
# 终态:列表/清理判定用。
TERMINAL_STATUSES = ("done", "error", "cancelled")
# 非终态(活跃):唯一活跃键去重 / 领取判定用。
ACTIVE_STATUSES = ("queued", "running", "awaiting_input")
# cancel 可命中的状态(queued/running/awaiting_input → cancel_requested)。
CANCELLABLE_STATUSES = ("queued", "running", "awaiting_input")
def compute_active_dedupe_key(
draft_id: str | None, user_id: str | None, task_id: str | None
) -> str | None:
"""活跃去重键:``sha256(scope)``。scope = draft_id + (task_id | user_id)。
- task 作业(task_id 非空):按 (draft_id, task_id) 去重 —— 跨用户共享;
- 普通作业:按 (draft_id, user_id) 去重;
- draft_id 为空 → 无法去重,返回 None(直接创建,保持原行为)。
该键写入 ``active_dedupe_key`` 唯一索引:作业活跃时占用,进入终态时清 NULL
(MySQL/SQLite 唯一索引都允许多个 NULL)——「同一 scope 至多一个活跃作业」
由 DB 唯一键强制,INSERT 冲突即幂等命中。
"""
if not draft_id:
return None
if task_id:
scope = f"task:{draft_id}:{task_id}"
else:
scope = f"user:{draft_id}:{user_id or ''}"
return hashlib.sha256(scope.encode("utf-8")).hexdigest()
def _loads(value: Any) -> Any:
@@ -52,15 +83,72 @@ class RoundtableJobRepository:
@staticmethod
def _row_to_dict(row: RoundtableJobRow) -> dict[str, Any]:
d = row.to_dict()
for k in ("created_at", "updated_at"):
for k in ("created_at", "updated_at", "lease_until"):
if isinstance(d.get(k), datetime):
d[k] = d[k].isoformat()
for k in ("dispatch_chain", "thread_ids", "chain", "orchestration_plan", "dialogues", "step3"):
for k in (
"dispatch_chain",
"thread_ids",
"chain",
"orchestration_plan",
"dialogues",
"step3",
"input_snapshot",
):
d[k] = _loads(d.get(k))
return d
# ── create ────────────────────────────────────────────────────────────
@staticmethod
def _make_row(
*,
id: str,
resolved_user_id: str | None,
draft_id: str | None,
task_id: str | None,
orchestration_mode: str,
coordinator_name: str | None,
thread_ids: dict[str, str] | None,
chain: dict[str, Any] | None,
orchestration_plan: dict[str, Any] | None,
dispatch_chain: list[dict[str, Any]] | None,
status: str,
phase: str,
request_id: str | None = None,
request_hash: str | None = None,
active_dedupe_key: str | None = None,
input_snapshot: dict[str, Any] | None = None,
) -> RoundtableJobRow:
now = datetime.now(UTC)
return RoundtableJobRow(
id=id,
draft_id=draft_id,
user_id=resolved_user_id,
task_id=(task_id or None),
request_id=(request_id or None),
request_hash=(request_hash or None),
active_dedupe_key=(active_dedupe_key or None),
input_snapshot=_dumps(input_snapshot),
status=status,
phase=phase,
cycle=0,
dispatch_chain=_dumps(dispatch_chain),
active_agent_id=None,
consensus_percentage=0,
pending_clarification=None,
thread_ids=_dumps(thread_ids),
coordinator_name=coordinator_name,
orchestration_mode=orchestration_mode,
chain=_dumps(chain),
orchestration_plan=_dumps(orchestration_plan),
error=None,
attempt=0,
version=0,
created_at=now,
updated_at=now,
)
async def create(
self,
*,
@@ -78,27 +166,19 @@ class RoundtableJobRepository:
phase: str = "initializing",
) -> dict[str, Any]:
resolved_user_id = resolve_user_id(user_id, method_name="RoundtableJobRepository.create")
now = datetime.now(UTC)
row = RoundtableJobRow(
row = self._make_row(
id=id,
resolved_user_id=resolved_user_id,
draft_id=draft_id,
user_id=resolved_user_id,
task_id=(task_id or None),
task_id=task_id,
orchestration_mode=orchestration_mode,
coordinator_name=coordinator_name,
thread_ids=thread_ids,
chain=chain,
orchestration_plan=orchestration_plan,
dispatch_chain=dispatch_chain,
status=status,
phase=phase,
cycle=0,
dispatch_chain=_dumps(dispatch_chain),
active_agent_id=None,
consensus_percentage=0,
pending_clarification=None,
thread_ids=_dumps(thread_ids),
coordinator_name=coordinator_name,
orchestration_mode=orchestration_mode,
chain=_dumps(chain),
orchestration_plan=_dumps(orchestration_plan),
error=None,
created_at=now,
updated_at=now,
)
async with self._sf() as session:
session.add(row)
@@ -106,6 +186,102 @@ class RoundtableJobRepository:
await session.refresh(row)
return self._row_to_dict(row)
async def try_create_or_get_active(
self,
*,
draft_id: str | None,
user_id: str | None | _AutoSentinel,
task_id: str | None,
id: str,
orchestration_mode: str = "recommend",
coordinator_name: str | None = None,
thread_ids: dict[str, str] | None = None,
chain: dict[str, Any] | None = None,
orchestration_plan: dict[str, Any] | None = None,
dispatch_chain: list[dict[str, Any]] | None = None,
status: str = "queued",
phase: str = "initializing",
request_id: str | None = None,
request_hash: str | None = None,
input_snapshot: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], bool]:
"""原子地「创建活跃作业 → 冲突则幂等返回已有活跃作业」(Phase 3 唯一活跃键版)。
一致性来自 DB **唯一索引** ``uq_roundtable_jobs_active_dedupe_key``:活跃作业占用
``active_dedupe_key = sha256(draft_id + task_id|user_id)``,进入终态时清 NULL。于是
「同一 scope 至多一个活跃作业」由唯一键强制——直接 INSERT,冲突(IntegrityError)即
说明已有活跃作业,读回它幂等返回(``created=False``)。**不再依赖 GET_LOCK 命名锁**:
唯一键在 MySQL / PostgreSQL / SQLite 上语义一致,跨进程/跨 worker 天然互斥。
极小竞态兜底:INSERT 冲突后读回时若胜者恰好已进终态(键已释放),则重试一次 INSERT。
返回 ``(job_dict, created)``。``draft_id`` 为空时无法去重,直接创建(保持原行为)。
"""
resolved_user_id = resolve_user_id(
user_id, method_name="RoundtableJobRepository.try_create_or_get_active"
)
dedupe_key = compute_active_dedupe_key(draft_id, resolved_user_id, task_id)
def _build_row() -> RoundtableJobRow:
return self._make_row(
id=id,
resolved_user_id=resolved_user_id,
draft_id=draft_id,
task_id=task_id,
orchestration_mode=orchestration_mode,
coordinator_name=coordinator_name,
thread_ids=thread_ids,
chain=chain,
orchestration_plan=orchestration_plan,
dispatch_chain=dispatch_chain,
status=status,
phase=phase,
request_id=request_id,
request_hash=request_hash,
active_dedupe_key=dedupe_key,
input_snapshot=input_snapshot,
)
# 无 draft_id → 无法去重,直接创建(保持原有行为)。
if dedupe_key is None:
row = _build_row()
async with self._sf() as session:
session.add(row)
await session.commit()
await session.refresh(row)
return self._row_to_dict(row), True
for _attempt in range(2):
try:
async with self._sf() as session:
row = _build_row()
session.add(row)
await session.commit()
await session.refresh(row)
return self._row_to_dict(row), True
except IntegrityError:
pass # 唯一键冲突 → 已有活跃作业(或极小竞态,见下)。
existing = await self._get_by_dedupe_key(dedupe_key)
if existing is not None:
return self._row_to_dict(existing), False
# 胜者在冲突与我们读回之间进了终态(键已释放)→ 重试 INSERT 可成功。
# 两次都冲突且读不回 —— 理论上不可达;保守读回/报错,绝不双建。
existing = await self._get_by_dedupe_key(dedupe_key)
if existing is not None:
return self._row_to_dict(existing), False
raise RuntimeError(
f"roundtable job dedupe conflict but no active row found for key {dedupe_key}"
)
async def _get_by_dedupe_key(self, dedupe_key: str) -> RoundtableJobRow | None:
"""按唯一活跃键读回占用该键的(活跃)作业行;无则 None。"""
stmt = select(RoundtableJobRow).where(
RoundtableJobRow.active_dedupe_key == dedupe_key
)
async with self._sf() as session:
return (await session.execute(stmt)).scalars().first()
# ── update progress ─────────────────────────────────────────────────────
async def update_progress(
@@ -125,8 +301,80 @@ class RoundtableJobRepository:
dialogues=_UNSET,
step3=_UNSET,
error=_UNSET,
lease_owner: str | None = None,
) -> dict[str, Any] | None:
"""更新进度字段。
**租约门(Phase 3)**:传入 ``lease_owner`` 时走**原子条件 UPDATE**——要求 DB 里
``lease_owner`` 匹配且状态不在 ``cancel_requested/cancelled``,否则返回 None(写被
拒)。这保证:① 只有持租者能推进度;② 一旦 cancel 落库(cancel_requested),迟到的
进度写不会覆盖取消意图;③ 多 worker 下非持租者的过期写直接失效。一致性来自 DB 条件
UPDATE,而非读后判断。
**终态处理**:写入 status ∈ 终态(done/error/cancelled)时,同时清空
``active_dedupe_key``(释放唯一活跃键,允许该 scope 再建作业)与租约字段。
不传 ``lease_owner`` 时保持原「按 user 分权 + 读改写」行为(向后兼容旧调用/测试)。
"""
resolved_user_id = resolve_user_id(user_id, method_name="RoundtableJobRepository.update_progress")
# ── 租约门:原子条件 UPDATE ──
if lease_owner is not None:
values: dict[str, Any] = {"updated_at": datetime.now(UTC)}
if status is not _UNSET:
values["status"] = status
if phase is not _UNSET:
values["phase"] = phase
if cycle is not _UNSET:
values["cycle"] = int(cycle)
if dispatch_chain is not _UNSET:
values["dispatch_chain"] = _dumps(dispatch_chain)
if active_agent_id is not _UNSET:
values["active_agent_id"] = active_agent_id
if consensus_percentage is not _UNSET:
values["consensus_percentage"] = int(consensus_percentage)
if pending_clarification is not _UNSET:
values["pending_clarification"] = pending_clarification
if thread_ids is not _UNSET:
values["thread_ids"] = _dumps(thread_ids)
if coordinator_name is not _UNSET:
values["coordinator_name"] = coordinator_name
if dialogues is not _UNSET:
values["dialogues"] = _dumps(dialogues)
if step3 is not _UNSET:
values["step3"] = _dumps(step3)
if error is not _UNSET:
values["error"] = error
# 终态:释放唯一活跃键 + 清租约。
if status is not _UNSET and status in TERMINAL_STATUSES:
values["active_dedupe_key"] = None
values["lease_owner"] = None
values["lease_until"] = None
# awaiting_input:任务已暂停、执行协程退出 —— 必须释放租约,否则 resume 前
# 租约未过期没人能重新领取。活跃键保留(作业仍未终态,继续占着 scope)。
elif status is not _UNSET and status == "awaiting_input":
values["lease_owner"] = None
values["lease_until"] = None
values["version"] = RoundtableJobRow.version + 1
where = [
RoundtableJobRow.id == job_id,
RoundtableJobRow.lease_owner == lease_owner,
RoundtableJobRow.status.not_in(["cancel_requested", "cancelled"]),
]
if resolved_user_id is not None:
where.append(RoundtableJobRow.user_id == resolved_user_id)
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = await session.get(RoundtableJobRow, job_id)
return self._row_to_dict(row) if row is not None else None
# ── 兼容路径:按 user 分权 + 读改写(不持租约的旧调用)──
async with self._sf() as session:
row = await session.get(RoundtableJobRow, job_id)
if row is None:
@@ -157,11 +405,319 @@ class RoundtableJobRepository:
row.step3 = _dumps(step3)
if error is not _UNSET:
row.error = error
# 终态同样要释放唯一活跃键(兼容路径没有租约也要清键)。
if status is not _UNSET and status in TERMINAL_STATUSES:
row.active_dedupe_key = None
row.lease_owner = None
row.lease_until = None
# awaiting_input 同样释放租约(与租约门路径一致)。
elif status is not _UNSET and status == "awaiting_input":
row.lease_owner = None
row.lease_until = None
row.updated_at = datetime.now(UTC)
await session.commit()
await session.refresh(row)
return self._row_to_dict(row)
async def mark_draft_persist_pending(self, job_id: str) -> bool:
"""把草稿回写 pending 标记置 1(``_write_run_to_draft`` 重试耗尽时调用)。
一致性来自 DB:绝不退化为 last-write-wins 盲写,而是留下可被 outbox 补偿器
(Phase 3)发现的标记。返回是否命中了作业行。
"""
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow)
.where(RoundtableJobRow.id == job_id)
.values(draft_persist_pending=True, updated_at=datetime.now(UTC))
)
if result.rowcount == 0:
return False
await session.commit()
return True
# ── Phase 3:租约领取 / 续租 / 释放(dispatcher) ────────────────────────
async def list_claimable(self, *, now: datetime, limit: int = 20) -> list[str]:
"""列出可领取的作业 id:``queued``(新作业/续跑入队)或 ``running`` 但租约已过期
(持租 worker 崩溃/卡死)。按 updated_at 升序(先来先领),最多 limit 个。
这只是「候选列表」;真正的领取靠 {@link claim_job} 的条件 UPDATE —— 多 worker 并发
扫到同一候选时,只有一个 UPDATE 能命中(一致性来自 DB)。
"""
stmt = (
select(RoundtableJobRow.id)
.where(
or_(
RoundtableJobRow.status == "queued",
(RoundtableJobRow.status == "running")
& (RoundtableJobRow.lease_until.is_not(None))
& (RoundtableJobRow.lease_until < now),
)
)
.order_by(RoundtableJobRow.updated_at.asc())
.limit(limit)
)
async with self._sf() as session:
result = await session.execute(stmt)
return [r[0] for r in result.all()]
async def list_cancel_reapable(self, *, now: datetime, limit: int = 20) -> list[str]:
"""列出可以由 dispatcher 收口的取消请求。
``cancel_requested`` 是取消的权威意图,但持租 worker 可能在看门狗收口前崩溃。
仅当作业没有租约或租约已过期时才允许 dispatcher 无租约收口;仍持有有效租约的
作业继续由原 worker 的看门狗处理,避免抢占仍在正常退出的执行器。
"""
stmt = (
select(RoundtableJobRow.id)
.where(
RoundtableJobRow.status == "cancel_requested",
or_(
RoundtableJobRow.lease_owner.is_(None),
RoundtableJobRow.lease_until.is_(None),
RoundtableJobRow.lease_until < now,
),
)
.order_by(RoundtableJobRow.updated_at.asc())
.limit(limit)
)
async with self._sf() as session:
result = await session.execute(stmt)
return [r[0] for r in result.all()]
async def claim_job(
self, job_id: str, *, lease_owner: str, lease_until: datetime
) -> dict[str, Any] | None:
"""原子条件 UPDATE 领取一个作业:仅当它仍是可领取状态时才成功。
成功条件(DB 保证,跨 worker 互斥):``status='queued'``,或 ``status='running'``
且租约已过期。成功则置 ``status='running'``、写 ``lease_owner/lease_until``、
``attempt+1``、``version+1``,返回行;否则返回 None(别的 worker 先领了 / 状态已变)。
"""
values = {
"status": "running",
"lease_owner": lease_owner,
"lease_until": lease_until,
"attempt": RoundtableJobRow.attempt + 1,
"version": RoundtableJobRow.version + 1,
"updated_at": datetime.now(UTC),
}
where = [
RoundtableJobRow.id == job_id,
or_(
RoundtableJobRow.status == "queued",
(RoundtableJobRow.status == "running")
& (RoundtableJobRow.lease_until.is_not(None))
& (RoundtableJobRow.lease_until < datetime.now(UTC)),
),
]
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = await session.get(RoundtableJobRow, job_id)
if row is None:
return None
# Phase 7 observability: attempt >= 2 means this job was previously
# claimed by another worker whose lease expired (crash / OOM / GC
# stall) and is now being reclaimed. This is the key signal for
# diagnosing worker instability under load.
if row.attempt >= 2:
logger.warning(
"roundtable_jobs lease takeover: job=%s reclaimed by %s "
"(attempt=%d — previous worker's lease expired)",
job_id, lease_owner, row.attempt,
)
return self._row_to_dict(row)
async def renew_lease(
self, job_id: str, *, lease_owner: str, lease_until: datetime
) -> bool:
"""心跳续租:仅持租者可延长 ``lease_until``。返回是否续租成功。"""
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow)
.where(
RoundtableJobRow.id == job_id,
RoundtableJobRow.lease_owner == lease_owner,
RoundtableJobRow.status == "running",
)
.values(lease_until=lease_until, updated_at=datetime.now(UTC))
)
if result.rowcount == 0:
return False
await session.commit()
return True
async def release_lease(self, job_id: str, *, lease_owner: str | None = None) -> bool:
"""释放租约(进入 awaiting_input 等「暂停但非终态」时调用)。
置 ``lease_owner/lease_until`` 为 NULL,使该作业可被任意 worker 重新领取(续跑)。
传入 ``lease_owner`` 时仅当匹配才释放(防止误放他人的租约)。
"""
where = [RoundtableJobRow.id == job_id]
if lease_owner is not None:
where.append(RoundtableJobRow.lease_owner == lease_owner)
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow)
.where(*where)
.values(lease_owner=None, lease_until=None, updated_at=datetime.now(UTC))
)
if result.rowcount == 0:
return False
await session.commit()
return True
# ── Phase 3:resume / cancel 条件状态机 ──────────────────────────────────
async def queue_for_resume(
self,
job_id: str,
*,
input_snapshot: dict[str, Any] | None = None,
user_id: str | None | _AutoSentinel = AUTO,
task_id: str | None = None,
) -> dict[str, Any] | None:
"""原子条件 UPDATE:``awaiting_input → queued``(续跑入队),仅第一个成功方有效。
多 worker / 重复点击下可能有多个 resume 请求并发;条件 UPDATE(WHERE status=
'awaiting_input')保证只有一个能把它翻成 queued,其余返回 None(路由据此拒绝)。
成功后清租约(交给 dispatcher 重新领取),并把含续跑语义的新 snapshot 写回。
"""
resolved_user_id = resolve_user_id(
user_id, method_name="RoundtableJobRepository.queue_for_resume"
)
values: dict[str, Any] = {
"status": "queued",
"phase": "initializing",
"pending_clarification": None,
"lease_owner": None,
"lease_until": None,
"version": RoundtableJobRow.version + 1,
"updated_at": datetime.now(UTC),
}
if input_snapshot is not None:
values["input_snapshot"] = _dumps(input_snapshot)
where = [RoundtableJobRow.id == job_id, RoundtableJobRow.status == "awaiting_input"]
if task_id is not None:
where.append(RoundtableJobRow.task_id == task_id)
elif resolved_user_id is not None:
where.append(RoundtableJobRow.user_id == resolved_user_id)
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = await session.get(RoundtableJobRow, job_id)
return self._row_to_dict(row) if row is not None else None
async def request_cancel(
self,
job_id: str,
*,
user_id: str | None | _AutoSentinel = AUTO,
task_id: str | None = None,
) -> dict[str, Any] | None:
"""原子条件 UPDATE:可取消态(queued/running/awaiting_input)→ ``cancel_requested``。
cancel 的**第一步**(权威意图落库)。成功后路由再 best-effort 取消本进程任务;
实际终态 ``cancelled`` 由持租者看门狗(检测到 cancel_requested)或 ``finalize_cancel``
写入 —— 保证「已取消」终态由持租者收口,避免竞态。重复 cancel 幂等(已 cancel_requested/
cancelled 时返回 None,路由据此回 409 或返回现状)。
"""
resolved_user_id = resolve_user_id(
user_id, method_name="RoundtableJobRepository.request_cancel"
)
values: dict[str, Any] = {
"status": "cancel_requested",
"version": RoundtableJobRow.version + 1,
"updated_at": datetime.now(UTC),
}
where = [
RoundtableJobRow.id == job_id,
RoundtableJobRow.status.in_(list(CANCELLABLE_STATUSES)),
]
if task_id is not None:
where.append(RoundtableJobRow.task_id == task_id)
elif resolved_user_id is not None:
where.append(RoundtableJobRow.user_id == resolved_user_id)
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = await session.get(RoundtableJobRow, job_id)
return self._row_to_dict(row) if row is not None else None
async def finalize_cancel(
self,
job_id: str,
*,
lease_owner: str | None = None,
) -> dict[str, Any] | None:
"""把 ``cancel_requested``(或孤儿 queued/running)收口为终态 ``cancelled``。
由持租者看门狗(检测 cancel_requested 后)或路由(作业尚在 queued、无持租者时)调用。
条件 UPDATE:仅当 ``status='cancel_requested'`` 时翻转;同时清唯一活跃键 + 租约。
传入 ``lease_owner`` 时要求租约匹配(持租者收口),否则不加租约条件(queued 无租约)。
"""
values: dict[str, Any] = {
"status": "cancelled",
"active_dedupe_key": None,
"lease_owner": None,
"lease_until": None,
"version": RoundtableJobRow.version + 1,
"updated_at": datetime.now(UTC),
}
where = [RoundtableJobRow.id == job_id, RoundtableJobRow.status == "cancel_requested"]
if lease_owner is not None:
where.append(RoundtableJobRow.lease_owner == lease_owner)
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow).where(*where).values(**values)
)
if result.rowcount == 0:
return None
await session.commit()
row = await session.get(RoundtableJobRow, job_id)
return self._row_to_dict(row) if row is not None else None
# ── Phase 3:outbox 补偿器(draft_persist_pending 投影) ─────────────────
async def list_draft_persist_pending(self, *, limit: int = 50) -> list[dict[str, Any]]:
"""列出 ``draft_persist_pending=1`` 的作业行(补偿器待投影清单)。"""
stmt = (
select(RoundtableJobRow)
.where(RoundtableJobRow.draft_persist_pending.is_(True))
.order_by(RoundtableJobRow.updated_at.asc())
.limit(limit)
)
async with self._sf() as session:
result = await session.execute(stmt)
return [self._row_to_dict(r) for r in result.scalars()]
async def clear_draft_persist_pending(self, job_id: str) -> bool:
"""投影成功后清 ``draft_persist_pending`` 标记。返回是否命中。"""
async with self._sf() as session:
result = await session.execute(
update(RoundtableJobRow)
.where(RoundtableJobRow.id == job_id)
.values(draft_persist_pending=False, updated_at=datetime.now(UTC))
)
if result.rowcount == 0:
return False
await session.commit()
return True
# ── read ────────────────────────────────────────────────────────────────
async def get(
@@ -50,3 +50,6 @@ class RoundtableTaskDraftRow(Base):
default=lambda: datetime.now(UTC),
onupdate=lambda: datetime.now(UTC),
)
# 乐观并发控制版本号:每次 update_draft 自增;传入 expected_version 时校验,命中
# 0 行即并发冲突(防 step2.runs 读-改-写丢失更新——多用户/多 worker 并发)。
version: Mapped[int] = mapped_column(Integer, nullable=False, default=0, server_default="0")
@@ -19,9 +19,10 @@ import re
from datetime import UTC, datetime
from typing import Any
from sqlalchemy import select
from sqlalchemy import case, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from deerflow.persistence.roundtable_drafts.sql import DraftConcurrentWriteError
from deerflow.persistence.roundtable_task_drafts.model import RoundtableTaskDraftRow
_UNSET = object()
@@ -77,6 +78,8 @@ class RoundtableTaskDraftRepository:
"task_id": row.task_id,
"title": row.title,
"furthest_step": row.furthest_step,
# 乐观锁版本号:列表也携带,供前端本地副本对账(冲突时重拉合并)。
"version": row.version,
# 所用业务链名(历史卡片展示用);无链条 → None → 前端显示「自由模式」。
"chain_title": _extract_chain_title(row.step2),
"created_at": row.created_at.isoformat() if isinstance(row.created_at, datetime) else row.created_at,
@@ -159,24 +162,52 @@ class RoundtableTaskDraftRepository:
step1=_UNSET,
step2=_UNSET,
step3=_UNSET,
expected_version: int | None = None,
) -> dict[str, Any] | None:
"""Partial update by id. ``user_id`` is ignored (signature-compat only)."""
"""Partial update by id (``user_id`` ignored — signature-compat only).
与个人草稿一致:原子条件 UPDATE,版本判定与写入在同一条 SQL 里,
多 worker 并发下无检查后竞争窗口。``rowcount == 0`` 时回读区分
「不存在」与「版本冲突」。
"""
values: dict[str, Any] = {
"version": RoundtableTaskDraftRow.version + 1,
"updated_at": datetime.now(UTC),
}
if title is not _UNSET and title is not None:
values["title"] = str(title).strip()
if furthest_step is not _UNSET and furthest_step is not None:
# furthest_step 单调不回退:迟到的自动保存不得把已推进的步骤拉回去。
step_value = int(furthest_step)
values["furthest_step"] = case(
(RoundtableTaskDraftRow.furthest_step >= step_value, RoundtableTaskDraftRow.furthest_step),
else_=step_value,
)
if step1 is not _UNSET:
values["step1"] = _dumps(step1)
if step2 is not _UNSET:
values["step2"] = _dumps(step2)
if step3 is not _UNSET:
values["step3"] = _dumps(step3)
where = [RoundtableTaskDraftRow.id == draft_id]
if expected_version is not None:
where.append(RoundtableTaskDraftRow.version == expected_version)
async with self._sf() as session:
row = await session.get(RoundtableTaskDraftRow, draft_id)
if row is None:
result = await session.execute(
update(RoundtableTaskDraftRow).where(*where).values(**values)
)
if result.rowcount == 0:
if expected_version is not None:
existing = await session.get(RoundtableTaskDraftRow, draft_id)
if existing is not None:
raise DraftConcurrentWriteError(
draft_id, expected=expected_version, actual=existing.version
)
return None
if title is not _UNSET and title is not None:
row.title = str(title).strip()
if furthest_step is not _UNSET and furthest_step is not None:
row.furthest_step = int(furthest_step)
if step1 is not _UNSET:
row.step1 = _dumps(step1)
if step2 is not _UNSET:
row.step2 = _dumps(step2)
if step3 is not _UNSET:
row.step3 = _dumps(step3)
row.updated_at = datetime.now(UTC)
await session.commit()
row = await session.get(RoundtableTaskDraftRow, draft_id)
await session.refresh(row)
return self._to_dict(row)