#retaintive LLM 平台架构图解

Date: 2026-06-25 Status: Draft（图解配套版，配合 架构终态文档 读）

#0. 这份文档怎么用

这份是图解版——把 架构终态文档 里的三平面模型画成图。两张图：

• 图 1（§2）：现在的系统整理好后长什么样（push context，没有 tool/agent）。
• 图 2（§3）：以后加 RAG / tool / Vapi，新功能该放在哪一层。

配一张 tool loop 时序图（§3.3），因为「模型→授权→执行→拿结果→再问模型」这种循环，用时序图比框图清楚。

为什么用 Mermaid 不用 ASCII / drawio：Mermaid 是文本写、引擎自动对齐渲染、能进 git 做 PR review。这个 Rspress 站点已通过 rspress-plugin-mermaid 支持 fenced Mermaid block；drawio 源文件仍可放在 docs/public/diagrams/，但这类会频繁改动的架构分层图更适合直接写在 Markdown 里。

#1. 三个平面，一句话各是什么

读图前先记住三个平面（详细定义见终态文档 §2）：

⚠️ 命名提醒：官方 六层基座文档 把「Policy Guard / 裁决」那层叫 "Control Plane"。本文为不混淆，把「发版本的治理」叫 Governance / Release Plane，把「运行时拦请求的裁决关」叫 Runtime Gate（图里的 Proposal Commit Gate / Tool Authorization Gate）。前者慢、影响所有请求；后者快、每条请求都过、代码权威。

#2. 图 1：现有系统整理好后（push context，单向）

怎么读：从上往下一条线。Governance 在最上面发出一个 bundle 注入 Data Plane；Data Plane 单向走到写库；写库是一个 Neon 原子事务（业务表 + Decision Ledger 同生共死）；最后投射给客户。Cross-cutting 在右边，贯穿全程。

图 1 相对今天唯一新增的实体：Decision Ledger（和业务表同事务）+ Product Projection 投射层。其余全是把已有的（Traceplane / promptVersion / Policy Guard / 原子 batch）钉进格子。

#3. 图 2：加 RAG / Tool / Vapi 后，新功能放哪

加了 tool/agent 后，Data Plane 从「单向」变「循环」：模型可以中途说「我要调个工具」，拿到结果再继续。但图 1 那条「唯一写库关」不变。新多出来的是一条「工具授权关」和一个「受控执行层」。

#3.1 新功能放置总览（flowchart）

怎么读：Governance 多了 4 个 [+] 新格子（都进 bundle）；Data Plane 里模型输出会分叉——要么「最终 proposal」直接去 Commit Gate（和图 1 一样），要么「tool call」先过 Tool Authorization Gate，执行后回到 Context 再循环。

#3.2 不变的内核（无论加什么）

模型只能 propose，Runtime Gate（代码）才能 authorize，Execution Service 才能 execute，每个动作进 Ledger。 RAG/tool/Vapi 让链路从单向变循环、context 源变多、「执行」变真，但这条 + 原子写 Ledger 永远不变。这是系统世界观的死规矩。

#3.3 tool loop 时序图（循环用时序图最清楚）

怎么读：竖线是参与者，箭头是「谁调谁」，从上往下是时间。loop 框表示「可能来回好几轮」，直到模型给最终 proposal。注意 write tool（Vapi/SMS）比 read tool 多一步人工审批。

#4. 放置决策表：新功能该加在哪

这是这两张图最重要的用途——以后任何新功能一来，查表就知道加哪层、挂什么 ID、要不要留痕。

#4.1 拿到新功能先问三个问题

#4.2 常见新功能 → 加在哪（速查表）

#4.3 三条「放错地方」的红线

❌ 把死红线（DNC/store隔离/写入权限）写进 prompt
   → 必须在 Data Plane / Runtime Gate 的代码里（prompt 只帮模型少犯错，不是权威）

❌ 把「绝不静默丢弃」放进 Traceplane（fail-open 可丢）
   → rejected/skipped 必须进 Neon Decision Ledger，且和业务 mutation 同一个 db.batch 原子事务
     （业务改了但 ledger 没记 = 正好制造了静默丢弃）

❌ 只存 bundleId 的 hash，不存可读 components
   → hash 只能追责，不能解释「当时用了啥」。必须同时存 resolved model/params/versions

❌ 让新功能各自拼一套 prompt / 各自记一套 trace
   → 新输出面复用同一底座（bundle/Ledger/Traceplane/eval）。厚底座薄壳子

#5. 这和 prompt 分层工作怎么对上

如果当前在改 contacts-analyzer prompt 分层，对照图 1，改的是 Data Plane 里「③ LLM Request Builder」那一格的内部结构。这个方向是需要的，但它只是 Governance → Data 这条线上的一个组件。

• prompt 分层 = Data Plane / Builder 内部整理，继续做
• 它没碰 releaseBundle 收敛、Decision Ledger、Traceplane 记结果 —— 这些是下一批独立工作，不该塞进同一个 prompt 分层改动
• schema 从 prompt 手写挪到 request body = 也是 Builder 内部 ✅ 同 branch 可做

#6. 落地顺序（架构演进，不是细粒度 issue）

#7. 调研依据

• 画图方式：本 Rspress 站点通过 rspress-plugin-mermaid 渲染 Mermaid；复杂架构图的 drawio 源文件放在 docs/public/diagrams/。这类需要随文字同步 review 的架构图优先用 Mermaid。
• 架构判断：见 架构终态文档 §10 调研依据（含 live code anchors）。
• 两张图经 Codex adversarial review 修正（箭头方向、两 gate 拆名、releaseBundle vs assembledPromptHash 分层、原子事务框、Approval Queue 独立、read tool 也需 authz 等）。