oh-my-muse/docs/agent-specs/2026-07-07-S7-生成主链全文通路-execution.md

S7 生成主链全文通路（分支①）执行计划（执行版）

• 版本：v1.0
• 日期：2026-07-07
• 承接：评审版 v0.2（现状已三路测绘校正；三个材料级点所有者 2026-07-07 已裁：①独立加密缓存表 ②采纳恒回传完整正文 ③护栏+合规审上移到完整正文）。设计意图/边界/主权红线以 review v0.2 为准，本文只做任务级拆解；两文冲突以 review v0.2 为准并回改本文。
• 读者：执行 agent（每个 S7x 可独立派工）与项目所有者。

---

0. 执行纪律（每步适用）

1. 主权红线（最高优先）：完整正文只允许存在于「执行线程内存 / 瞬态加密缓存（TTL+决定即清） / SSE 传输 / 客户端」；任何一步都不得把完整正文写入 muse_ai_suggestion、muse_content_block 或任何长期列。每步验收含「候选表 content_snapshot.content 仍是摘要、完整正文不在长期列」的机械断言。
2. 完成=机械验证：每步「验收」命令真跑留证；改动后按依赖链回归（ai 模块单测 → local → real-PG；涉 Dify 再跑 live）。
3. 契约先行：chunk.data.content/sequenceNo 已声明（docs/api-contracts/ai/openapi.yaml SSEChunkEvent），只填充不改 schema；如需新增瞬态取全文端点则先改契约再实现。DDL 只走 sql/muse/V<next>__*.sql（编号取当前最大+1，现状最大 V34）。
4. 最小改动 + 中文注释：只动本步清单文件；完整正文相关字段/表必须有「永不落长期库、TTL、决定即清」的中文注释与脱敏日志。
5. 回写：每步完成回写 docs/mvp/进度总账.md + muse-module-ai/.agent；不新增过程文档。
6. 环境与坑：real-PG/live 按 .agents/knowledge/external-deps-and-gotchas.md §四（清代理、_test 库、-am 防 stale jar、-DreuseForks=false）。
7. 派工分档：各步执行子代理 opus；纯机械（配置值、菜单）可 haiku；S7d 的 Dify fail-closed 语义与 live 验收如遇跨模块硬判可升 fable 或主会话终裁。

---

1. 步骤总图

flowchart LR
  S7a["S7a 捕获+护栏<br/>(provider 无关)"] --> S7b["S7b 瞬态载体+SSE 送达"]
  S7b --> S7c["S7c 前端采纳基准+所见即所写"]
  S7a --> S7d["S7d 生成 provider 切 Dify"]
  S7c --> DONE["S7 验收"]
  S7d --> DONE
  DEP["依赖: Muse 专属 Dify workspace"] -. 仅 S7d .-> S7d

S7a→S7b→S7c 不依赖 Dify workspace，可先行连跑；S7d 依赖 Dify workspace 就绪，可与 S7c 并行准备、workspace 到位后收口。

---

S7a 捕获完整正文 + 护栏上移（provider 无关，不依赖 Dify）

前置	无
触及	muse-module-ai-server：MuseAiRuntimeClient（RuntimeResult）、RealNewApiMuseAiRuntimeClient、RealDifyMuseAiRuntimeClient、MuseAiCandidateReviewService、MuseAiRuntimeProjectionService

动作

1. 运行时结果加不落库全文字段：facade/MuseAiRuntimeClient.java 的 RuntimeResult（L70-78）增加仅内存字段（如 fullOutput），中文注释写明「provider 完整正文，仅进程内传递，永不持久化到任何列/表；落库只用 outputSummary 摘要」。
2. 两个 real client 成功分支捕获完整正文：
   • RealNewApiMuseAiRuntimeClient.success()（L163-192）：在 shortOutputSummary（L172）之前保留完整 content（L171），先跑护栏（见 3），通过后把完整正文塞进 RuntimeResult.fullOutput，仍派生 60 字摘要供落库。
   • RealDifyMuseAiRuntimeClient chat/workflow（L227-285）：answer（L230）/text（L253）同理捕获；注意 Dify 完成原因硬编码为常量（L239），不可用作完整性信号。
3. 护栏 + 合规审上移到完整正文（裁决③）：MuseAiCandidateReviewService.review（L42-84）的输入从摘要改为完整正文——完整性校验（长度/结构合理性，判断截断，不信 provider finishReason）+ 凭据痕迹合规扫描均作用于完整正文；疑似截断/不合规 → 返回 RuntimeFailure（可重试），不产出候选。MuseAiRuntimeProjectionService（L250-283）侧：审通过后 content_snapshot.content 仍写摘要（L328 不变）、三审字段照旧（L361-377）。
4. 落库口径不变：候选表恒为摘要 + 三审；fullOutput 不进 outputSummary Map、不进任何列。

验收

• ai 模块单测：两 adapter 返回 fullOutput（日志脱敏，只打长度/hash）；护栏对完整正文——截断样本→failure/可重试、正常→pass；合规扫描命中凭据痕迹→failure。
• 静态/代码审查断言：fullOutput 无任何持久化路径（不被 mapper/DO 引用）。
• run-p1r-verification.sh local 全绿。

回滚：fullOutput 字段与护栏输入改动 revert 即回；无 DDL、无契约变更。

---

S7b 瞬态载体 + SSE 送达（裁决①：独立加密缓存表）

前置	S7a
触及	新增瞬态全文表（DDL）、executor、MuseAiRuntimeProjectionService（事件写入）、MuseAiTaskStreamServiceImpl（读侧 chunk）、采纳/放弃 owner（purge）

动作

1. 瞬态全文存储（仿 MuseAiRuntimePayloadStore）：新增 sql/muse/V36__ai_generated_fulltext_transient.sql 建独立表（key by taskId、加密载荷列、expires_at TTL、租户列）。DDL 版本协调（S6 核验确认）：当前最大 V34；S6 的 runtime_batch_id 迁移占 V35，本瞬态表占 V36；若实际提交顺序不同，按提交时最大版本+1 顺延、勿撞号。，DAO/Store 对齐 MuseAiRuntimePayloadStore（L24-46）的加密 + 短 TTL 语义。表注释写明「瞬态出向完整正文，TTL + 决定即清，非系统记录，永不作为正文来源落 Canonical」。
2. executor 写入 + 终态 purge：MuseAiRuntimeJobExecutor.execute（L75-95）在拿到 RuntimeResult 后、投影前，把 fullOutput 写入瞬态存储；沿用现有终态 finally（L62-64 runtimePayloadStore.remove 同处）追加瞬态全文的兜底清理（异常/超时也不残留）。
3. 事件表发 chunk 引用行：放宽 MuseAiRuntimeProjectionService.appendTaskEvent 的 isValidTerminalEvent（L319-322）以允许写一个非终态 chunk 事件——sequence_no 排在 done 之前，payload_summary 只放指向瞬态存储的引用（如 {contentRef, sequenceNo}），不含正文。保持每任务至多一条终态的部分唯一索引不变（chunk 非终态，不受该约束）。
4. SSE 读侧回取：MuseAiTaskStreamServiceImpl.chunkData（L279-285）遇到带 contentRef 的 chunk 行时回瞬态存储取完整正文填 content；缓存缺失（已 purge/过期）→ content=""（用户已决定，无害）。回放/轮询/重连语义不变（重放 chunk 引用行→再回取，TTL 内可续）。
5. 决定即清：采纳（Content mergeBlockSuggestion owner）与放弃（reject owner）成功路径 purge 该 taskId 的瞬态全文。

验收

• real-PG IT（新增，仿 P1rContentMergeGeneratedSuggestionIT 模式）：真生成后 SSE 重放的 chunk 事件 content = 完整正文（来自瞬态存储，长度 > 摘要阈值）；候选表 content_snapshot.content 仍是摘要、完整正文不在任何长期列（主权不变式断言）；采纳/放弃后瞬态表该行已删；断线重连（seq 0 全量重放）仍能取到完整正文（TTL 内）。
• 契约结构门绿（chunk.data.content 为已声明字段，非破坏）。
• local + real-pg 全绿。

回滚：以开关门控 chunk 引用行发射 + 瞬态写入；关闭即回退「仅 done」旧行为；V35 迁移向前兼容（表未用即空）。

---

S7c 前端接成采纳基准 + 所见即所写（裁决②）

前置	S7b
触及	muse-studio：AIPanel.tsx、useAcceptSuggestion.ts、sse.ts（健壮性）、CandidatePanel.tsx（如需）

动作

1. 显示/交接零改动确认：AIPanel.tsx 的 streamContent（L48/56）已接线 chunk.data.content（L130-132）并实时渲染（L189），handleStreamDone（L63-89）优先流正文（L71-75）→ 完整正文经既有值拷贝链落到 CandidatePanel 可编辑 reviewedText（L97-103）。本步只需回归验证该链在真 chunk 下贯通。
2. 采纳恒回传完整正文（裁决②）：useAcceptSuggestion.ts 的 shouldMergeAfterEdit（L39-51）改为恒带 finalContent = 用户审定的完整正文（原样采纳也带）；即采纳恒以「用户回传最终正文」语义写 Canonical。须先核对后端 suggestion-merges 合同：确认 accept_as_is + finalContent 或统一走 modify_then_merge 的后端语义，避免前端恒传但后端忽略。契约文档 docs/api-contracts/content/* 的 MergeBlockSuggestionRequest 同步（如语义调整）。
3. 健壮性：区分「流不完整」与「流为空」：因完整正文不落长期库，中途断连可能只收到截断的流正文，而 handleStreamDone 优先非空 ref（L71-75）会静默采信截断。改为：收到 done 但流正文疑似不完整（如与 done 的完整性标记/长度不符）→ 提示重生成，不静默采纳截断；确实为空→回源（此时只剩摘要，明确提示而非当正文采纳）。
4. quality_check 事件当前被 AIPanel 丢弃（次要），本步不强制接入。

验收

• tsc -b、vitest run、vite build 绿；AIPanel.contract.test.tsx 扩展「真 chunk→完整正文→恒回传 finalContent」断言。
• MSW-off Playwright ai-generation.spec 扩展：渲染正文长度 > 阈值且与 provider 输出一致（非 60/80 字摘要）；采纳后 DB 反查 Canonical 落完整正文（长度一致）、归因 ai_suggestion、revision 递增。
• 隔离/回归：创作主线其余 spec 无回归。

回滚：revert 前端提交；后端不受影响。

---

S7d 生成 provider 切 Dify（依赖 Muse 专属 Dify workspace）

前置	S7a（fullOutput 透出）；S7b/c 不阻塞；依赖 Dify workspace 就绪
触及	在用系统 Agent 版本 config、单人配置、RoutingMuseAiRuntimeClient fail-closed

动作

1. provider 切换：在用系统 Agent 版本 config 设 runtimeProvider=dify + providerRef.dify（app=「muse-写作透传」，credentialRef→S1 凭据，须落 Muse 专属 workspace）；muse.ai.dify.enabled=true 进单人配置；non-stream-read-timeout-seconds 对齐 ≥180s 总预算（现 Dify 90/180）。
2. 完整性信号：Dify 完成原因硬编码常量（RealDifyMuseAiRuntimeClient L239）不可信 → S7a 的完整正文护栏是唯一截断信号，补 Dify 形态断言。
3. fail-closed 反向：RoutingMuseAiRuntimeClient（L18-53，现有 requiresSourceRefs fail-closed L37-40）补「dify 未配/凭据错 → 拒绝、不回退 New-API」路径与断言。
4. New-API 保留：本步不摘 New-API 配置（S8 验收后才摘）。

验收

• live IT（新增/扩展 P1rDify*，opt-in）：Dify 生成 → Shadow 候选（三审齐、审的是完整正文）→ 完整正文经 SSE 可见 → 回传采纳写 Canonical；fail-closed 反向（dify 凭据错→拒绝，无 New-API 回退）。
• local + real-pg 全绿；MSW-off ai-generation.spec 真 Dify 复跑绿。

回滚：在用 Agent runtimeProvider 拨回 new-api 即回（兼容逻辑未动）；配置 revert 独立。

---

2. 全局完成判据

• review v0.2 §9 验收全部逐条留证：主权不变式（候选/正文表无完整正文、瞬态表决定即清）、可见（前端渲染完整正文）、所见即所写（Canonical=回传完整正文）、护栏（作用于完整正文）、Dify 形态 + fail-closed、local+real-PG 回归。
• 里程碑：M1=S7a（捕获+护栏，无 Dify 依赖）/ M2=S7b+S7c（全文经 SSE 可见、所见即所写采纳，仍 New-API）/ M3=S7d（切 Dify）。每 M 点回写总账可暂停评估。

3. 关键风险（承 review §11）

瞬态正文暴露（TTL+决定即清+加密+脱敏日志）、断连丢正文致静默采纳截断（S7c 区分不完整/为空）、单 chunk 体积（必要时分片）、Dify 完成原因不可信（护栏为唯一信号）。