临时-02 · Market Install 下游物化方案
评审版 v1 · 2026-06-26 · 给人一眼看懂：两个物化断点 / 四方案权衡 / 关键决策点 · 配套工程稿见同名 .md
用户从市场安装智能体或知识库后点不出效果：知识库检索静默落到“无数据集”而命不中，智能体在生成任务里被运行期直接拒绝。
根因不是安装坏了——安装按设计只记账、不物化是对的；错在本该承接物化的目标域绑定路径只写了引用、没造出真实体。
推荐 B'（installed_ref 最小留痕，知识库优先共享发布者数据集），物化落点放在目标域绑定路径；完整物化 C 留作远期；暂缓是合理过渡（至少先把“静默断点”改成“诚实标注未开放”）。
① 两个物化断点（现状：安装→绑定只写引用，下游必然失败）
安装只写 muse_market_installation + 授权投影，targetFactsWritten=false。物化本该在目标域绑定路径发生，但现状那一步也只写了引用。
🔵 知识库 — 断点①：检索“数据集门”拿不到数据集
目标域绑定createKnowledgeBinding（消费 handoff token）
↓
现状只写binding + 来源投影；kbId = parseLong(sourceId)
❌ 不建 muse_knowledge_base 实体
↓
检索四门：用途 ✓ · 授权 ✓ · 来源状态 ✓
↓
第四门selectActiveDatasetByKbId(kbId) → null
（无本地 KB → 无 ragflow_binding 数据集行）
🔴 记为 no_dataset 静默省略，检索仍 fail-closed 返回。
用户：检索悄无声息命不中，不报错，无从排查。
🟣 智能体 — 断点②：运行期“二次校验”拒绝
目标域绑定bindAgentSlot（marketHandoff 仅放宽属主可见性）
↓
现状只写slot binding 裸引用（指向 market 出身 agentId）
❌ 不建 muse_agent / muse_agent_version
↓
运行期 resolveAgentForTask → requireVisibleAgent
↓
关键此路径不带 marketHandoff 放宽，按“系统/本人 user + active 版本”校验
🔴 AI_AGENT_NOT_EXISTS / SCOPE_FORBIDDEN。
用户：AI 任务直接失败，尽管市场标“已安装、已绑定”。
边界澄清：handoff token 不负责物化——市场侧 target owner facade 只生成跳转 URL；真正写目标事实（及未来物化）发生在消费域内部，目标域在自己的事务里核销 token + 写事实。正确链路是 install(记账) → 跳转 → 目标域绑定路径(消费 token + 写绑定 + 物化)，不是“install 直接物化”、也不是“handoff 自己物化”。
② B' 物化后：在目标域绑定路径补建实体（同事务、原子）
不复制资产，建轻量“安装引用型”实体让下游能解析；底层数据集/配置优先共享发布者的。地基大半已备：muse_knowledge_base 的 kb_type=installed_ref / source_market_asset_id / license_snapshot_id 在 V5 就有。
🔵 知识库 B'
createKnowledgeBinding：写 binding + 投影（不变）
↓
新增 建 muse_knowledge_base
kb_type=installed_ref，source_market_asset_id 溯源
↓
新增 建 ragflow_binding
指向发布者数据集（共享，不复制）
↓
检索第四门 → 拿到数据集 ✓ → 命中，用户可见效果 🟢
🟣 智能体 B'
bindAgentSlot：写 slot binding（不变）
↓
新增 建 muse_agent（market_installed 型）
+ active muse_agent_version（引用发布者 config）
↓
需扩展 运行期 requireVisibleAgent
放行“授权有效的 market_installed”
↓
运行期解析通过 → AI 任务可跑 🟢
智能体侧多一层成本：market_installed 类型有文档无实现——后端-04 写了 muse_agent 区分 system/user/market_installed，但现网 DDL/代码仅 system/user。B' 智能体需先把这类型落成真实 schema + 运行期放行，工程量略大于知识库。可考虑知识库先行、智能体视工程量分阶段。
③ 四方案权衡（本质区别 = 物化深度：造多真的实体 / 复制还是共享数据集）
| 方案 | 做什么 | 用户价值 | 工程成本 | 数据集 | 跨租户 | 幂等 |
| C 完整物化 |
复制成租户独立 agent/kb 实体 + 复制 RAGFlow 数据集 |
最高 自洽副本，发布者改版/下架不影响 |
最高 数据集克隆+重索引异步重活；agent 类型还要落地 |
复制 · N 倍放大 |
隔离天然干净 |
难 避免重复克隆 |
| B' 最小留痕 ★ 推荐 |
建 installed_ref 实体；数据集/配置优先共享发布者 |
高 终态等价 C（命中/可跑），最小正确步 |
中 kb 地基已备；不碰数据集复制；agent 需补类型 |
共享 · 不放大 |
需验证 共享数据集的隔离 |
轻 唯一键+命令回放 |
| B 按需物化 |
安装/绑定只留引用，首次使用时惰性物化 |
中 终态同 B'，但首用有延迟 |
反更高 热路径插写+外调，破坏读写分离 |
共享（同 B'） |
同 B' |
最难 热路径并发首用 |
| 暂缓 |
维持现状 + 诚实标注“未开放” + 留接口位 |
低 仍不可用，但消除“静默骗用户” |
最低 文档/文案为主 |
不涉及 |
不涉及 |
不涉及 |
演进关系：B' ──（当“安装者需独立改造副本/发布者频繁改版冲击安装者”成真实痛点）──▶ C。暂缓 是合理过渡兜底，不是“什么都不做”——最低限度也要把现状的静默断点降级为诚实提示。
④ 待人类拍板的关键决策点
1. 物化深度（最关键）
完整 C / 最小 B' / 暂缓。
倾向 B' 优先，C 远期演进。
2. 物化时机
安装同步 / 绑定同步 / 异步 worker / 惰性首用。
倾向绑定同步（与 token 消费原子）；不选惰性。
3. 数据集：共享 vs 复制 ⚠️
B' 与 C 的分水岭，也是 B' 唯一硬风险点。
选共享前必须先验证多租户共享同一 RAGFlow 数据集的隔离是否隔得住。
4. 智能体 market_installed 落地
是否接受“补 schema + 运行期放行”工程量。
若暂不接受，可知识库先行、智能体暂缓。
5. 授权快照承载
沿用 ADR-020 字符串 envelope（VARCHAR）。
market_installation 两列 BIGINT 残留建议不纳入本方案，作独立契约议题。
6. 来源溯源与回滚
经 source_market_asset_id 溯源；来源召回/下架的处置。
倾向复用 muse_source_propagation_target：阻断新使用、不自动删。