docs(ai): 回写 SSE 长任务超时修复闭环(进度总账 + muse-module-ai/.agent 通则沉淀)

c77b006 SSE 修复后回写:进度总账 AI e2e entry 标已修闭环(A1+③);muse-module-ai/.agent 沉淀通则「SSE 长任务死线须 ≥ 上游 TOTAL_TIMEOUT + AI 流重连必须以 SSE id 幂等去重(后端 seq0 全量回放)」,避免重踩后端比上游先关门。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/mvp/进度总账.md

@@ -189,7 +189,7 @@
 - ✅ **2026-06-25(同日续):admin jobs 子域 e2e 转真连 + governance config 断层标注,admin governance e2e 全收口(commit 2d06ec5)**。剩 3 skip:jobs 2 个转真连(重试→后端校验 retryable 新插 operation_id=adminRetryJob queued 子 job、取消→muse_ai_job.status=cancelled、来源重试→新插 job_type=source_event_retry job;均纯 DB 状态机、活体 code:0),核心治理配置页(:456)保留 skip。关键坑:切片库后台 AI runtime worker ~3s 抢 queued→failed,取消锚点须用 running(queued 活体 cancel 真返 1040100014 不可取消)。global-setup 加 resetJobsFixture(幂等 seed 90001 failed/retryable + 90002 running muse_ai_job + 90003 needs_recheck muse_ai_source_event + 清派生)。真契约:retry 只接受 {commandId}、cancel/source 接受 {commandId,reason},删 museAdminPayloadsByPage。core config(:456)本轮先标 skip、随即续转真连(见下条;此处"缺表"前提经 psql 纠正为缺种子——原 agent 查 muse_function_chain 漏 meta_ 前缀误判无表)。**独立核实:连跑全量 account+market+jobs 6 passed/1 skipped + psql 复核 90002=cancelled/retry 派生=1/source_event_retry=1**。另查明 studio e2e 37 spec 本就 MSW-off 真连(playwright.config webServer VITE_API_MOCK=false 全局关 MSW + global-setup psql 复位)。待补后端:jobs/source 三写命令 P1r 真库 IT(现 Mockito 单测,本次 e2e 真连为首个端到端真验)。
 - ✅ **2026-06-25(同日续):admin governance config 全页巡航转真连——拆 6 子系统+灌系统级种子,admin governance e2e 0 skip 全收口(commit 6bd9030)**。**前提纠正(承上条 jobs 的"缺表"误判)**:psql 实证真表名带 meta_ 前缀=muse_meta_function_chain/muse_meta_protection_node(V3 schema、都在 muse_slice_live、行数 0)——原 agent 查 muse_function_chain 漏 meta_ 前缀误判无表;真断层是切片库缺系统级公共治理对象种子、**非缺表非缺功能**(教训:断层标注前须按真实表名读 schema 验 to_regclass)。每锚点真表+真后端过滤契约(curl 实证):story.draft=muse_meta_schema、故事链路=muse_meta_function_chain(status=active、displayName 取 chain_snapshot)、事实校验=muse_meta_protection_node(status=active+policy_snapshot->>chainKey 绑定)、候选生成 Prompt=muse_prompt(非 muse_ai_prompt)、系统故事智能体=muse_agent(非 muse_ai_agent、agent_type=system)、系统世界观库=muse_knowledge_base(kb_type=global/owner=0)。global-setup 加 resetMetaGovernanceFixture(7 幂等 upsert)。原 1 skip 拆 6 条细粒度真连用例(元结构/功能编排/AI/全局知识/市场/New-API)+修 2 处 strict-mode 多命中。New-API 锚点契约纠正(mock user-e2e/usage-e2e 伪造值→真后端用户数字 id+聚合 recordId {userId}:{period})。**独立核实:连跑全量 e2e x2 各 12 passed/0 skipped + psql 复核 6 锚点种子真灌(function_chain/protection_node active、muse_prompt/muse_agent system/global KB 各 1 行)**。**至此 admin governance e2e 12 真连用例 0 skip 全转真后端**(account+market+jobs+meta governance、反假绿:真 token+代理+PG+契约+写 DB+读种子)。待补后端:jobs/source/market restore P1r 真库 IT;knowledge admin IT=0。
 - ✅ **2026-06-25(同日续):studio e2e 全量健康核查 + 前端双 bug 修 + flaky 根治 + 揪出真后端 bug(commit 443a1f3/de5f4d0/ca0e04c)**。admin governance e2e 全收口后核查 studio e2e(36 spec/56 case、本就 MSW-off 真连)。4 轮全量:整体健康 **54/56 稳定绿、0 假绿候选**(抽查断言强度证非假绿)。**修复三类**:①**前端双 bug**(443a1f3):ChapterPanel 新建章节双提交(onKeyDown Enter+onBlur 双触发 submitCreate、isCreatingPending 异步滞后→重复 POST 第 2 个乐观锁 1041000002)加 useRef 同步守卫;WorkspacePage expectedWorkRevision 用 workRevision()??1 兜底掩盖 work 详情未加载→改传真实 revision(undefined 走 ChapterPanel ==null 早返)。实证单次新建 POST 2→1、chapter spec 修后 8 次全绿。②**环境 fixture 污染**(de5f4d0):asset1 被历史 delist→连带 7 spec 红、work1 多余槽位→agent-slot-bind 多命中;global-setup §17/§18 复位。③**测试间来源污染 flaky**(ca0e04c):source-attribution 期望 block1 user_original 但前序 accept-suggestion 写 ai_suggestion 漂移→改读 pristine block3+§3 复位(断言未放宽、强灌 ai_suggestion 免疫验证)。**最大价值=揪出真后端 bug(mock 永远发现不了)**:`MuseKnowledgeBindingMapper.updateStatusByKbId`(:38-46)无 binding_status 过滤、给该 KB 所有未删 binding 写同一 commandId,违反 uk_muse_knowledge_binding_command(tenant_id,command_id WHERE NOT NULL)唯一索引→DuplicateKeyException(disable POST HTTP 200 但 body code:500)→**任何用户把 KB 绑 ≥2 作品后无法停用该 KB**(生产影响)。mock 单测 mock 该 mapper 返行数掩盖、psql KB1 2 binding curl disable 500/1 binding code:0 坐实、代码 :43-45 铁证。用户批准委托修后端(传播写不覆盖 command_id/逐行派生+补真 PG IT+knowledge-disable-restore e2e 转绿,已修闭环 commit 0b152d9)。
-- ✅ **2026-06-25(同日续):AI 真生成 e2e 真红深诊——非 AI 外部、两层根因定位(环境已修 + SSE code bug 方案评审中)**。studio 全量末轮 54/56,2 红是 AI 真生成 spec(不 stub):ai-generation 真红、accept-suggestion flaky(隔离 2 次绿)。深诊定位**两层、均非 AI 外部**(New-API curl 真验在线 HTTP 200+/v1/chat/completions 15s 真文本、清代理非劫持误诊):①**环境/启动(已修)**:start-muse-server-infra.sh 漏 source p1r-external-acceptance.env(New-API 凭据)→server 无 MUSE_AI_NEW_API_*→RealNewApiMuseAiRuntimeClientCondition 装 UnavailableMuseAiRuntimeClient 兜底→AI job 秒失败 AI_NEW_API_UNAVAILABLE(runtime 10-21ms、HTTP 没发出);重启 source 两 env 真验 job completed+suggestion 落库(脚本待固化防复发);②**真 code bug(SSE 协议/时序)**:后端 MuseAiTaskStreamServiceImpl DEFAULT_TIMEOUT_MILLIS=30s 硬死线<LLM 真时延(MiniMax 11-60s 抖动)+前端 connectAIStream 无重连(重连只在 connectEventStream)→LLM>30s 后端空关+前端不重连→候选永丢 UI。accept flaky/ai-gen 真红是同一 bug 时延两侧(task70 15.3s 绿/task71 35.7s 红、server 日志 done 晚 8s 落库)。**反假绿:e2e 真红深诊分清环境/code/外部三层**(New-API 实在线、真红是 code bug、非急标 flaky/环境)。第二层属 SSE 协议/时序产品行为变更、用户选 A 委托出方案评审文档(后端 timeout↑/可配 vs 前端 AI 流重连对比、design-docs 临时件)review 后执行,本轮未改 code。
+- ✅ **2026-06-25(同日续):AI 真生成 e2e 真红深诊+修复闭环——非 AI 外部、两层根因(环境已修 + SSE code bug 已修 c77b006)**。studio 全量末轮 54/56,2 红是 AI 真生成 spec(不 stub):ai-generation 真红、accept-suggestion flaky(隔离 2 次绿)。深诊定位**两层、均非 AI 外部**(New-API curl 真验在线 HTTP 200+/v1/chat/completions 15s 真文本、清代理非劫持误诊):①**环境/启动(已修)**:start-muse-server-infra.sh 漏 source p1r-external-acceptance.env(New-API 凭据)→server 无 MUSE_AI_NEW_API_*→RealNewApiMuseAiRuntimeClientCondition 装 UnavailableMuseAiRuntimeClient 兜底→AI job 秒失败 AI_NEW_API_UNAVAILABLE(runtime 10-21ms、HTTP 没发出);重启 source 两 env 真验 job completed+suggestion 落库(脚本待固化防复发);②**真 code bug(SSE 协议/时序)**:后端 MuseAiTaskStreamServiceImpl DEFAULT_TIMEOUT_MILLIS=30s 硬死线<LLM 真时延(MiniMax 11-60s 抖动)+前端 connectAIStream 无重连(重连只在 connectEventStream)→LLM>30s 后端空关+前端不重连→候选永丢 UI。accept flaky/ai-gen 真红是同一 bug 时延两侧(task70 15.3s 绿/task71 35.7s 红、server 日志 done 晚 8s 落库)。**反假绿:e2e 真红深诊分清环境/code/外部三层**(New-API 实在线、真红是 code bug、非急标 flaky/环境)。第二层属 SSE 协议/时序产品行为变更、用户选 A 委托出方案评审文档(design-docs/临时-01、commit 09c35f5)→review 批准 A1+候选③→**已修 commit c77b006**:后端 DEFAULT_TIMEOUT_MILLIS 硬编码→@Value muse.ai.sse.task-timeout-millis 默认 240000(≥上游 TOTAL_TIMEOUT 180s+轮询/回放余量、连接死线:70+poll deadline:198 同引用);前端 connectAIStream 退避重连续 poll+按 SSE id 去重(后端不读 lastEventId、每次 seq0 全量回放→lastSeenSequenceNo 丢弃已见避免重复渲染候选)+done/error terminal 停+总超时 300s onError(SSE_TIMEOUT)不静默卡死(返回仍 AbortController、AIPanel 零改动);A1 start-muse-server-infra.sh 固化 source acceptance env。验证:后端单测 14/14+前端 107/107(含重连去重用例)、活体 e2e ai-generation+accept 连跑 3 轮 6/6 全绿、DB 落 6 行真 LLM suggestion、重连幂等方法 A 活体证。残留:本机 LLM 6.8-19s 未自然跨 30s、慢路径靠「240s 数学覆盖上游 180s+单测+方法 A 重连活体证」三重保证。通则沉淀 muse-module-ai/.agent。
 ### D. gateway 接线(B4,**配置层已收口;运行态后置**)
 - ✅ **配置层收口(2026-06-19)**:`muse-gateway` 已新增 `/admin-api/muse/**`、`/app-api/muse/** → grayLb://muse-server`,删除当前聚合入口未启用的 bpm/pay/report/mp 死路由,Knife4j 聚合入口改为 `muse-server`。新增 `GatewayRouteConfigurationTest` 机械门禁,断言 Muse 路由存在、停用模块路由不回潮、Knife4j 不展示停用服务;本轮 `mvn -pl muse-gateway test -Dtest=GatewayRouteConfigurationTest` **3/3 绿**。
 - ⏸ **运行态仍后置**:单体 P1R-7 仍以 `muse-server` 直服 48080 `/app-api` 为验收关键路径;`muse-server` 默认禁用 Nacos 注册,且 gateway 与 server 本地默认端口同为 48080,所以本轮不声称网关真实转发已完成。后续若启用网关部署,需补注册发现/端口方案并做 curl/e2e 首跑。