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

@@ -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)