26ff1af374
market install 后下游物化方向(用户选)方案设计:深调研 2 agent+spot-check 坐实两物化断点——install 只写 muse_market_installation 与 ai/knowledge 解耦、KB bind kbId=parseLong(sourceId)不建本地 muse_knowledge_base 行致检索 no_dataset 第四门省略、agent slot 放宽但 runtime requireVisibleAgent 拒裸引用。出 C(完整物化)/B(惰性)/B(installed_ref 最小留痕)/暂缓 四方案对比。 推荐 B(installed_ref 最小留痕、KB 优先共享发布者 dataset、物化落点放目标域绑定路径非 install——handoff 非物化桥、安装解耦正确不应改)。地基不对称坐实:KB(V5 kb_type/source_market_asset_id)+agent(V27 source_market_asset_id、注释物化后续主线本列先就位)列已备、但 agent market_installed 类型有文档(后端-04)无实现→两域工程量不同。决策点待拍板:物化深度(倾向 B)、时机(绑定同步非惰性)、dataset 共享 vs 复制(唯一硬风险、共享前必验多租户 RAGFlow 隔离)、agent market_installed 落地量(否则 KB 先行)、召回回滚。两图文+大纲注册。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
193 lines
14 KiB
HTML
193 lines
14 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>临时-02 · Market Install 下游物化方案（人读图）</title>
|
||
<style>
|
||
:root{
|
||
--bg:#0f1419; --panel:#1a2129; --ink:#e6edf3; --sub:#9fb0bf; --line:#2b3641;
|
||
--green:#3fb950; --green-bg:#11331c; --red:#f85149; --red-bg:#3a1718;
|
||
--blue:#58a6ff; --blue-bg:#10243e; --amber:#d29922; --amber-bg:#3a2c0a;
|
||
--purple:#bc8cff; --purple-bg:#241634;
|
||
}
|
||
*{box-sizing:border-box}
|
||
body{margin:0;background:var(--bg);color:var(--ink);
|
||
font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;
|
||
line-height:1.6;padding:32px 20px 80px}
|
||
.wrap{max-width:1140px;margin:0 auto}
|
||
h1{font-size:24px;margin:0 0 6px;letter-spacing:.3px}
|
||
.meta{color:var(--sub);font-size:13px;margin-bottom:22px}
|
||
.tldr{background:linear-gradient(135deg,#10243e,#142e1c);border:1px solid var(--line);
|
||
border-radius:12px;padding:18px 22px;margin-bottom:30px;font-size:15px}
|
||
.tldr b{color:var(--blue)} .tldr .rec{color:var(--green);font-weight:700}
|
||
h2{font-size:17px;margin:38px 0 14px;padding-left:12px;border-left:4px solid var(--blue)}
|
||
.sub{color:var(--sub);font-size:13.5px;margin:-6px 0 14px}
|
||
/* 断点链路 */
|
||
.chain{display:grid;grid-template-columns:1fr 1fr;gap:18px;margin-top:6px}
|
||
@media(max-width:820px){.chain{grid-template-columns:1fr}}
|
||
.lane{border:1px solid var(--line);border-radius:12px;padding:16px;background:var(--panel)}
|
||
.lane h3{margin:0 0 12px;font-size:15px;display:flex;align-items:center;gap:8px}
|
||
.lane.kb h3{color:var(--blue)} .lane.agent h3{color:var(--purple)}
|
||
.node{font-size:13px;padding:9px 12px;border-radius:8px;margin:7px 0;border:1px solid var(--line);background:#141b22}
|
||
.node .lbl{font-size:11px;color:var(--sub);display:block;margin-bottom:2px}
|
||
.node.ok{border-color:#1f6f33;background:var(--green-bg)}
|
||
.node.warn{border-color:#7a5a12;background:var(--amber-bg)}
|
||
.node.bad{border-color:#7d2a2a;background:var(--red-bg)}
|
||
.node.add{border-color:#27ae60;background:var(--green-bg)}
|
||
.arrow{text-align:center;color:var(--sub);font-size:15px;line-height:1;margin:2px 0}
|
||
.break{font-weight:700;color:var(--red);font-size:13px;margin-top:4px;display:flex;gap:6px;align-items:flex-start}
|
||
.fix{font-weight:700;color:var(--green);font-size:13px}
|
||
.code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11.5px;color:var(--amber)}
|
||
/* 对比表 */
|
||
table{width:100%;border-collapse:collapse;margin-top:6px;font-size:12.8px;background:var(--panel);
|
||
border-radius:12px;overflow:hidden}
|
||
th,td{padding:10px 12px;text-align:left;border-bottom:1px solid var(--line);vertical-align:top}
|
||
th{background:#222c36;color:var(--ink);font-weight:600;font-size:12.5px}
|
||
td:first-child,th:first-child{white-space:nowrap}
|
||
.opt{font-weight:700}
|
||
.opt.c{color:var(--amber)} .opt.bp{color:var(--green)} .opt.b{color:var(--blue)} .opt.h{color:var(--sub)}
|
||
.pill{display:inline-block;font-size:11px;padding:1px 8px;border-radius:5px;font-weight:600}
|
||
.p-hi{background:var(--green-bg);color:var(--green)}
|
||
.p-mid{background:var(--amber-bg);color:var(--amber)}
|
||
.p-lo{background:var(--red-bg);color:var(--red)}
|
||
.star{color:var(--green);font-weight:700}
|
||
/* 决策点 */
|
||
.grid2{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:6px}
|
||
@media(max-width:820px){.grid2{grid-template-columns:1fr}}
|
||
.card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:15px}
|
||
.card h4{margin:0 0 6px;font-size:13.5px;color:var(--blue)}
|
||
.card p{margin:5px 0;font-size:12.8px;color:var(--sub)}
|
||
.card .lean{color:var(--green);font-weight:600}
|
||
.legend{font-size:12px;color:var(--sub);margin-top:8px}
|
||
.badge{display:inline-block;font-size:10.5px;padding:1px 7px;border-radius:20px;font-weight:600;border:1px solid}
|
||
.b-add{color:var(--green);border-color:var(--green);background:var(--green-bg)}
|
||
.note{background:var(--blue-bg);border:1px solid #1c3a5e;border-radius:10px;padding:12px 15px;font-size:12.8px;color:var(--ink);margin-top:14px}
|
||
.note b{color:var(--blue)}
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<div class="wrap">
|
||
<h1>临时-02 · Market Install 下游物化方案</h1>
|
||
<div class="meta">评审版 v1 · 2026-06-26 · 给人一眼看懂：两个物化断点 / 四方案权衡 / 关键决策点 · 配套工程稿见同名 .md</div>
|
||
|
||
<div class="tldr">
|
||
用户从市场<b>安装</b>智能体或知识库后<b>点不出效果</b>：知识库检索静默落到“无数据集”而命不中，智能体在生成任务里被运行期直接拒绝。
|
||
根因不是安装坏了——安装按设计<b>只记账、不物化</b>是对的；错在本该承接物化的<b>目标域绑定路径只写了引用、没造出真实体</b>。
|
||
<span class="rec">推荐 B'（installed_ref 最小留痕，知识库优先共享发布者数据集），物化落点放在目标域绑定路径；完整物化 C 留作远期；暂缓是合理过渡（至少先把“静默断点”改成“诚实标注未开放”）。</span>
|
||
</div>
|
||
|
||
<h2>① 两个物化断点（现状：安装→绑定只写引用，下游必然失败）</h2>
|
||
<div class="sub">安装只写 <span class="code">muse_market_installation</span> + 授权投影，<span class="code">targetFactsWritten=false</span>。物化本该在目标域绑定路径发生，但现状那一步也只写了引用。</div>
|
||
<div class="chain">
|
||
<div class="lane kb">
|
||
<h3>🔵 知识库 — 断点①：检索“数据集门”拿不到数据集</h3>
|
||
<div class="node"><span class="lbl">目标域绑定</span>createKnowledgeBinding（消费 handoff token）</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node bad"><span class="lbl">现状只写</span>binding + 来源投影；<span class="code">kbId = parseLong(sourceId)</span><br>❌ 不建 muse_knowledge_base 实体</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node">检索四门：用途 ✓ · 授权 ✓ · 来源状态 ✓</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node warn"><span class="lbl">第四门</span><span class="code">selectActiveDatasetByKbId(kbId)</span> → null<br>（无本地 KB → 无 ragflow_binding 数据集行）</div>
|
||
<div class="break">🔴 <span>记为 <span class="code">no_dataset</span> 静默省略，检索仍 fail-closed 返回。<br>用户：检索悄无声息命不中，<b>不报错</b>，无从排查。</span></div>
|
||
</div>
|
||
<div class="lane agent">
|
||
<h3>🟣 智能体 — 断点②：运行期“二次校验”拒绝</h3>
|
||
<div class="node"><span class="lbl">目标域绑定</span>bindAgentSlot（marketHandoff 仅放宽<b>属主可见性</b>）</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node bad"><span class="lbl">现状只写</span>slot binding <b>裸引用</b>（指向 market 出身 agentId）<br>❌ 不建 muse_agent / muse_agent_version</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node">运行期 resolveAgentForTask → requireVisibleAgent</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node warn"><span class="lbl">关键</span>此路径<b>不带 marketHandoff 放宽</b>，按“系统/本人 user + active 版本”校验</div>
|
||
<div class="break">🔴 <span><span class="code">AI_AGENT_NOT_EXISTS</span> / <span class="code">SCOPE_FORBIDDEN</span>。<br>用户：AI 任务<b>直接失败</b>，尽管市场标“已安装、已绑定”。</span></div>
|
||
</div>
|
||
</div>
|
||
<div class="note"><b>边界澄清：</b>handoff token <b>不负责物化</b>——市场侧 target owner facade 只生成跳转 URL；真正写目标事实（及未来物化）发生在<b>消费域内部</b>，目标域在自己的事务里核销 token + 写事实。正确链路是 <b>install(记账) → 跳转 → 目标域绑定路径(消费 token + 写绑定 + 物化)</b>，不是“install 直接物化”、也不是“handoff 自己物化”。</div>
|
||
|
||
<h2>② B' 物化后：在目标域绑定路径补建实体（同事务、原子）</h2>
|
||
<div class="sub">不复制资产，建轻量“安装引用型”实体让下游能解析；底层数据集/配置优先共享发布者的。地基大半已备：<span class="code">muse_knowledge_base</span> 的 <span class="code">kb_type=installed_ref</span> / <span class="code">source_market_asset_id</span> / <span class="code">license_snapshot_id</span> 在 V5 就有。</div>
|
||
<div class="chain">
|
||
<div class="lane kb">
|
||
<h3>🔵 知识库 B'</h3>
|
||
<div class="node">createKnowledgeBinding：写 binding + 投影（不变）</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node add"><span class="badge b-add">新增</span> 建 muse_knowledge_base<br><span class="code">kb_type=installed_ref</span>，<span class="code">source_market_asset_id</span> 溯源</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node add"><span class="badge b-add">新增</span> 建 ragflow_binding<br>指向<b>发布者数据集（共享，不复制）</b></div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node ok">检索第四门 → 拿到数据集 ✓ → <b>命中，用户可见效果</b> 🟢</div>
|
||
</div>
|
||
<div class="lane agent">
|
||
<h3>🟣 智能体 B'</h3>
|
||
<div class="node">bindAgentSlot：写 slot binding（不变）</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node add"><span class="badge b-add">新增</span> 建 muse_agent（<span class="code">market_installed</span> 型）<br>+ active muse_agent_version（引用发布者 config）</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node warn"><span class="badge b-add">需扩展</span> 运行期 requireVisibleAgent<br>放行“授权有效的 market_installed”</div>
|
||
<div class="arrow">↓</div>
|
||
<div class="node ok">运行期解析通过 → <b>AI 任务可跑</b> 🟢</div>
|
||
</div>
|
||
</div>
|
||
<div class="note"><b>智能体侧多一层成本：</b><span class="code">market_installed</span> 类型<b>有文档无实现</b>——<span class="code">后端-04</span> 写了 <span class="code">muse_agent</span> 区分 system/user/market_installed，但现网 DDL/代码仅 system/user。B' 智能体需先把这类型落成真实 schema + 运行期放行，工程量略大于知识库。可考虑<b>知识库先行、智能体视工程量分阶段</b>。</div>
|
||
|
||
<h2>③ 四方案权衡（本质区别 = 物化深度：造多真的实体 / 复制还是共享数据集）</h2>
|
||
<table>
|
||
<thead><tr>
|
||
<th>方案</th><th>做什么</th><th>用户价值</th><th>工程成本</th><th>数据集</th><th>跨租户</th><th>幂等</th>
|
||
</tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td class="opt c">C 完整物化</td>
|
||
<td>复制成租户独立 agent/kb 实体 + 复制 RAGFlow 数据集</td>
|
||
<td><span class="pill p-hi">最高</span> 自洽副本，发布者改版/下架不影响</td>
|
||
<td><span class="pill p-lo">最高</span> 数据集克隆+重索引异步重活；agent 类型还要落地</td>
|
||
<td>复制 · <b>N 倍放大</b></td>
|
||
<td>隔离天然干净</td>
|
||
<td><span class="pill p-lo">难</span> 避免重复克隆</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="opt bp">B' 最小留痕 <span class="star">★ 推荐</span></td>
|
||
<td>建 installed_ref 实体；数据集/配置<b>优先共享</b>发布者</td>
|
||
<td><span class="pill p-hi">高</span> 终态等价 C（命中/可跑），最小正确步</td>
|
||
<td><span class="pill p-mid">中</span> kb 地基已备；不碰数据集复制；agent 需补类型</td>
|
||
<td>共享 · <b>不放大</b></td>
|
||
<td><span class="pill p-mid">需验证</span> 共享数据集的隔离</td>
|
||
<td><span class="pill p-hi">轻</span> 唯一键+命令回放</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="opt b">B 按需物化</td>
|
||
<td>安装/绑定只留引用，<b>首次使用时</b>惰性物化</td>
|
||
<td><span class="pill p-mid">中</span> 终态同 B'，但首用有延迟</td>
|
||
<td><span class="pill p-lo">反更高</span> 热路径插写+外调，破坏读写分离</td>
|
||
<td>共享（同 B'）</td>
|
||
<td>同 B'</td>
|
||
<td><span class="pill p-lo">最难</span> 热路径并发首用</td>
|
||
</tr>
|
||
<tr>
|
||
<td class="opt h">暂缓</td>
|
||
<td>维持现状 + <b>诚实标注“未开放”</b> + 留接口位</td>
|
||
<td><span class="pill p-lo">低</span> 仍不可用，但消除“静默骗用户”</td>
|
||
<td><span class="pill p-hi">最低</span> 文档/文案为主</td>
|
||
<td>不涉及</td>
|
||
<td>不涉及</td>
|
||
<td>不涉及</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="legend">演进关系：<span class="opt bp">B'</span> ──（当“安装者需独立改造副本/发布者频繁改版冲击安装者”成真实痛点）──▶ <span class="opt c">C</span>。<span class="opt h">暂缓</span> 是合理过渡兜底，不是“什么都不做”——最低限度也要把现状的静默断点降级为诚实提示。</div>
|
||
|
||
<h2>④ 待人类拍板的关键决策点</h2>
|
||
<div class="grid2">
|
||
<div class="card"><h4>1. 物化深度（最关键）</h4><p>完整 C / 最小 B' / 暂缓。</p><p class="lean">倾向 B' 优先，C 远期演进。</p></div>
|
||
<div class="card"><h4>2. 物化时机</h4><p>安装同步 / 绑定同步 / 异步 worker / 惰性首用。</p><p class="lean">倾向绑定同步（与 token 消费原子）；不选惰性。</p></div>
|
||
<div class="card"><h4>3. 数据集：共享 vs 复制 ⚠️</h4><p>B' 与 C 的分水岭，也是 B' 唯一硬风险点。</p><p class="lean">选共享前<b>必须先验证</b>多租户共享同一 RAGFlow 数据集的隔离是否隔得住。</p></div>
|
||
<div class="card"><h4>4. 智能体 market_installed 落地</h4><p>是否接受“补 schema + 运行期放行”工程量。</p><p class="lean">若暂不接受，可知识库先行、智能体暂缓。</p></div>
|
||
<div class="card"><h4>5. 授权快照承载</h4><p>沿用 ADR-020 字符串 envelope（VARCHAR）。</p><p class="lean">market_installation 两列 BIGINT 残留建议<b>不纳入本方案</b>，作独立契约议题。</p></div>
|
||
<div class="card"><h4>6. 来源溯源与回滚</h4><p>经 source_market_asset_id 溯源；来源召回/下架的处置。</p><p class="lean">倾向复用 muse_source_propagation_target：阻断新使用、不自动删。</p></div>
|
||
</div>
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|