[sclfcz]

概述

新增一套可选的分布式派发层，用于多 Worker 场景。两个开关（DIST_SCHEDULER、DIST_IM_OWNERSHIP）默认关闭，关闭时行为与未引入该层完全一致；MySQL 是运行状态的唯一权威，Redis 只做门控，RabbitMQ 只负责唤醒。

分阶段内容

• MySQL 租约 + fencing 认领：FOR UPDATE SKIP LOCKED 认领、lease_token 递增围栏、心跳续租与 reaper 回收。
• Transactional Outbox + RabbitMQ：状态变更与 outbox 行同事务写入，relay 用 publisher confirms 投递，消费端去重，含重试阶梯与 DLQ。
• Redis 准入：租户并发槽位、模型令牌桶（全部 Lua + 服务端时间），以及按租户配额的 claimFair。
• 步骤 checkpoint 与外部副作用对账：intent → committed/unknown → needs_review，发送前写 send_started_at，结算窗口后判定，不静默重放。
• 定时任务接入派发层：SQLite 仍是结果权威，MySQL 只是派发信封；MySQL 不可用时自动回退到 legacy 认领循环。
• IM 凭证跨实例单持有者：dist:im:owner:{credential} 租约 + fencing token，入站/出站逐条门控，丢租约后重新进入备用。
• 工程化：compose 环境（MySQL 8.4 / RabbitMQ 4 / Redis 7）、一键演示 npm run dist:demo、被回收任务的优先级通道。

对主服务的改动

只涉及 src/db.ts、src/im-manager.ts、src/index.ts、src/task-scheduler.ts，且全部在开关之后（新增导出函数与钩子，不改既有行为）。

新增依赖

mysql2、amqplib、ioredis、@types/amqplib。

如何验证

docker compose -f docker-compose.distributed.yml up -d
export DIST_MYSQL_TEST_URL=mysql://dist:dist@127.0.0.1:3307/dist
export DIST_AMQP_TEST_URL=amqp://dist:dist@127.0.0.1:5672
export DIST_REDIS_TEST_URL=redis://127.0.0.1:6379
npx vitest run tests/distributed
npm run dist:demo

已知边界

• 执行层仍是单机（SQLite + 本地工作区）；本层解决派发、租约与副作用一致性，不是把执行拆成分布式。
• 没有按会话的 serial_key 租约：同一会话内任务的顺序仍由单机 GroupQueue 保证。
• IM 回复未接幂等键：buffered 类平台下是至少一次语义，重复回复需要回复侧去重。
• 三实例 IM 僵尸混沌场景在 mock 平台下不可观测（两实例场景已验证并断言通过）。

测试结果

make test 与合并前基线一致：3190 通过 / 7 失败 / 78 跳过，7 个失败全部是既有的 tests/container-session-permissions.test.ts 环境问题（/proc/self/fd 在当前 Docker 镜像下的行为）。