oh-my-muse/docs/agent-specs/2026-06-22-handoff-P3-content-review.md

跨空间 Handoff —— P3(content owner)asset_use 从零建评审版

版本:v0.1(P3 单阶段评审) · 日期:2026-06-22 · 目标读者:架构/产品拍板人 + 实现 agent · 类型:评审版(结论+拍板点+blast radius+验收,不预写代码细节) 上游:handoff 顶层评审 · 执行版 §4.2/§五 P3 · 承 P2 agent 评审(已实施) 依据:本评审现状基于 2 路只读调研(content 后端代码 + design-docs SSOT,file:line 锚点见正文),非 summary 推断。

---

〇、本版定位

handoff 最后一 owner(content)。把 SSOT 已定义表名/职责/索引(后端-04 muse_content_work_asset_use_precheck)、但建表 SQL 未写 + 代码完全缺失 + 产品-02F 标注 feature gate 关闭的 content asset_use,从零建为真实两段式闭环:token 红线兑现(verify+consume)+ 落"作品使用市场资产作参考/AI 上下文"的授权凭证。

P3 与 P1/P2 的关键差异(降风险):

1. asset_use 语义=使用凭证记录,非物化(后端-04 L135"作品资产用于参考、模板或 AI 上下文";产品-02F L456:不写入正文/参考来源/规划项/局域 kb)→ 不涉及 P1/P2 共缺的"market 资产物化"维度,P3 范围天然干净、无"最小验证 vs 完整物化"分裂。
2. 无独立绑定事实表(后端-04 只定义 precheck 表 + precheck_id 唯一索引 L1081;asset_use 的"真实使用"经 muse_ai_candidate_decision_archive.work_asset_use_precheck_id 引用 precheckId 体现 L849)→ asset_use 兑现落点与 knowledge(独立 binding 表)/agent(slot binding)不同,见拍板点 Q1。
3. sourceAssetId 直接是真实 market asset id(已存在)→ e2e 不需 seed 目标实体 fixture(不像 P2 seed market agent),可做完整闭环(来源侧发起 + 落地兑现 + 真实 asset 落库断言)。

---

一、现状(2 路调研实证)

content 侧完全缺失(file:line)

• content 模块零 asset_use/handoffToken/asset-use-precheck 代码(grep 全量零命中,muse-module-content -server/-api)。无 DO/Mapper/Service/Controller/ReqVO。
• content-server/pom.xml 缺 muse-module-market-api(现仅 meta-api/infra-api)。
• content 错误码已用至 1_041_001_003,下一可用段 1_041_002_xxx。

SSOT 已定义(权威,但未建表)

• 后端-04 L135:表 muse_content_work_asset_use_precheck(content target owner service 写,"参考/模板/AI 上下文目标预检;阶段 7 默认 feature disabled")。
• 后端-04 L1081:唯一索引 muse_content_work_asset_use_precheck(precheck_id)。
• 后端-04 L849:muse_ai_candidate_decision_archive 字段含 work_asset_use_precheck_id(AI 接受候选时引用此预检 = asset_use 的真实"被使用"载体)。
• 后端-04a 完整建表 SQL(13 表,含 work/chapter/block/narrative_state)未含 asset_use→ P3 须建表(V28?)。
• 产品-02F L183-185:workAssetUsePrecheckId + feature gate 关闭;L456:asset_use 约束(不写入正文/参考来源/规划项/局域 kb)。
• 专题-03 L181-182:allowedPurpose(上下文检索/生成参考/绑定/导出/确认知识)、forbiddenPurpose(市场作品资产模板化/受限导出/二次分发);L188:授权必须按用途校验。

可照搬参照(完备)

• 两段式蓝本=knowledge(MuseKnowledgeBindingService:precheck 72-127 + binding 130-177 + consumeMarketHandoff 273-284 + requireUsablePrecheck 300-318;MuseKnowledgeBindPrecheckDO 17 字段)——P2 agent 已第二次照搬,P3 第三次复用同形态(收益:三 owner 兑现侧形态统一)。
• content 写命令约定:commandId 幂等(ContentCommandServiceImpl.reserveCommand + insertIgnore)+ expectedRevision 乐观锁(ContentRevisionGuard.requireRevision,ContentAppServiceImpl.updateWork 133-167)。
• market 端口:MarketHandoffTokenApi.verify/consume(P1/P2 已用,进程内 Bean)。

---

二、设计骨架(实现期对齐真实 RespVO,不预写代码)

两段式(token 红线,照 knowledge/P2 同款)

• precheck:POST /muse/works/{workId}/asset-use-prechecks,ReqVO:commandId/handoffToken/sourceAssetId/sourceVersion/authorizationSummaryId/purposes。逻辑:commandId 幂等→market 来源调 verify(targetOwner=content,action=asset_use)+consume(token 明文仅此阶段持有、核销)→落 muse_content_work_asset_use_precheck(status active)。
• create:POST /muse/works/{workId}/asset-uses,ReqVO:commandId/assetUsePrecheckId/expectedWorkRevision。逻辑:requireUsablePrecheck→expectedWorkRevision 乐观锁→落"使用事实"(形态见 Q1)→标 precheck consumed;token 已在 precheck 核销,本段凭 precheckId(同 P1/P2 自审修正:token 明文不进 create 段)。

前端 + e2e

• ContentHandoffLanding 落地组件 + useContentHandoff hooks(useAssetUsePrecheck/useCreateAssetUse)+ HandoffLandingPage 加 content dispatch。
• 02F MarketAssetDetailPage 加 targetOwner=content/action=asset_use 发起(asset_use 不依赖物化、sourceAssetId=真实 asset id,可做完整发起入口)。
• handoff-content.spec 真后端:正路 bind-precheck(content)→createHandoff→assetUsePrecheck verify+consume→createAssetUse 落库;负路伪造 token 被 verify 拒、0 写。

---

三、blast radius

• 纯新增:content asset_use 两段式(DO/Mapper/Service/Controller/ReqVO/错误码 + 表迁移),不改 content 现有写路径(work/block/planning/merge)。
• content-server 加 market-api 依赖(同 knowledge/ai,BcBoundaryArchTest 通用规则已覆盖、0 新 @Test;后端-04 L908/L1030 明确"目标 owner 自校验落 precheck")。
• 前端:复用 P0 基座(HandoffLandingPage + HandoffStore + 02F createHandoff),加 content 分支。
• DDL:新建 muse_content_work_asset_use_precheck(+ 使用事实表若 Q1 选独立表)迁移 V28,全新表向后兼容。⚠️ 应用共享 muse_slice_live = 人类 gate(同 V27)。

---

四、风险/失败路径

1. 原子性(load-bearing,同 P1/P2):precheck 落库 + consume token 同事务(content-server @Transactional + market-api consume REQUIRED 传播)。
2. token 红线:伪造/过期/跨属主 token 在 content 服务端被 verify 拒(fail-closed),0 写。
3. asset_use 不越界(产品-02F L456 硬约束):只落"使用授权凭证",不写入正文/参考来源/规划项/局域 kb——实现须守边界(不触 content/knowledge 写路径)。
4. purposes 授权校验 + 禁模板化:按 purposes 校验授权;market 作品资产模板化属 forbiddenPurpose(专题-03 L182),purpose 白名单须排除 template。

---

五、拍板点(请你定)

#	拍板点	选项	评审建议
Q1	asset_use "使用事实"落库形态	(A) 单表:precheck 表即事实载体(active→consumed 即"作品可用此资产"凭证,AI archive 引用 precheckId)/ (B) 独立使用事实表 muse_content_work_asset_use(与 knowledge binding 对称,便于按 work 聚合已用资产)	倾向 A(SSOT 只定义 precheck 表 + AI archive 引用的是 work_asset_use_precheck_id=precheckId,非独立 asset_use_id;A 最贴 SSOT、最小)。若产品要"作品已用资产清单"读模型,可在 A 上加投影,不必独立事实表
Q2	asset_use 兑现的用户价值锚点(产品)	asset_use 落库后不拉内容/不写正文,用户怎么感知"用了这个资产"? (A) 仅记录"作品已授权使用市场资产 X 作参考/AI 上下文",后续 AI 生成时作上下文来源(价值在 AI 链)/ (B) 加可见的"作品已关联资产"展示区	待你定(关系 P3 是否有即时可见价值,还是"记录就绪、价值在后续 AI 上下文消费";若选 A,P3 验收=记录+红线,AI 消费另立)
Q3	purposes 白名单	reference(参考)/ai_context(上下文检索)/generate_reference(生成参考);排除 template/模板化(forbiddenPurpose)	确认即可(SSOT 专题-03 L182 + 产品-02F L456 已定模板化禁止)
Q4	P3 范围	(A) 完整闭环(来源侧发起 02F + 落地兑现 + 真实 asset e2e,因不依赖物化)/ (B) 仅兑现侧(同 P2 最小)	倾向 A(asset_use 不物化、sourceAssetId 真实,P3 可比 P1/P2 更完整、无 fixture 替身)
Q5	revision 挂级	work 级(expectedWorkRevision)	确认即可(SSOT 后端-01 L60 + knowledge binding targetVersion 一致)

---

六、验收

• handoff-content.spec 真后端:正路完整闭环(发起→落地→asset_use 落库)+ 负路伪造 token 拒,2 passed + 幂等。
• content asset_use Service 单测(verify 接入 + consume 核销 + 同事务回滚 + 伪造/缺 token/禁用 purpose 拒)。
• BcBoundaryArchTest 0 违例(content→market-api)。
• 前端 tsc/eslint+vitest + 全量 e2e 不回归;V28 应用共享库(人类 gate)。
• 总账回写。

---

七、回滚

• content asset_use 纯新增,可整段移除(DO/Mapper/Service/Controller/错误码 + 前端组件 + V28 表)。
• 02F content 发起入口 feature-gate。
• 不影响 content 现有写路径 + P0/P1/P2。

下一步:确认 Q1-Q5(尤 Q1 落库形态 + Q2 用户价值锚点 = 真正需拍板)后,按 P2 同款流程实现(后端→前端→e2e→回写)。

---

八、拍板结论(2026-06-22)

• Q1 落库形态 = 单表(SSOT 对齐):muse_content_work_asset_use_precheck 表即事实载体(active→consumed = 作品可用此资产凭证),AI archive 引用 precheckId(L849)。不建独立使用事实表;若后续需"作品已用资产清单"读模型可加投影。
• Q2 用户价值锚点 = 记录 + AI 上下文消费:asset_use 落"作品已授权用市场资产作参考/AI 上下文",价值在后续 AI 生成链(作上下文来源)。P3 验收 = 记录 + token 红线,AI 消费链另立(不在 P3)。
• Q3 purposes = reference/ai_context/generate_reference(禁 template/模板化,forbiddenPurpose,专题-03 L182 + 产品-02F L456)。
• Q4 范围 = 完整闭环:来源侧发起(02F MarketAssetDetailPage targetOwner=content)+ 落地兑现 + 真实 asset e2e(不依赖物化、sourceAssetId 真实,比 P1/P2 更完整、无 fixture 替身)。
• Q5 revision = work 级(expectedWorkRevision,SSOT 后端-01 L60 + knowledge binding targetVersion 一致)。

实现顺序(P2 同款):后端(pom + V28 建表 + DO/Mapper/Service/Controller/ReqVO + 1_041_002_xxx 错误码 + verify/consume + 单测)→ 前端(ContentHandoffLanding + useContentHandoff hooks + HandoffLandingPage content dispatch + 02F 发起 + vitest)→ V28 DDL 人类 gate + handoff-content.spec 完整闭环 e2e + 全量回归 → 总账/总览/review 回写。

---

九、实施状态(2026-06-22 ✅ 已交付)

Q1-Q5 拍板全落地。后端:V28 建表 muse_content_work_asset_use_precheck(单表)+ 两段式 MuseContentAssetUseService(verify/consume + purposes 白名单 + work 级乐观锁)+ 1_041_002_xxx 错误码;MuseContentAssetUseServiceTest 8/0 + BcBoundaryArchTest 0 违例(content→market-api 经端口)。前端:ContentHandoffLanding + useContentHandoff hooks + HandoffLandingPage content dispatch + 02F MarketAssetDetailPage 来源侧发起入口;tsc/eslint 绿 + vitest 97→101(ContentHandoffLanding 4)。e2e:V28 已应用共享 muse_slice_live(flyway now at v28、用户拍板、rebuild jar + 重启 48080)+ handoff-content.spec 2 passed(正路真后端全链兑现 + 负路伪造 token 拒)+ 全量 e2e 50→52(1 flaky 单跑绿、非回归)。

诚实范围:asset_use = 「使用授权事实记录」非资产物化(sourceAssetId 直引真实 asset、无物化步骤),故来源侧发起天然完整、无 fixture 替身;Q2 锚点「AI 上下文消费」(经 muse_ai_candidate_decision_archive.work_asset_use_precheck_id)另立、不在 P3。至此 handoff token 红线三 owner(knowledge P1 / agent P2 / content P3)全覆盖;剩 market→knowledge/agent 资产物化独立主线。详见 docs/mvp/进度总账.md 2026-06-22 P3 条。