中间件管道与扩展点 SDK

中间件管道是灵渠平台的治理本体。每一个进入平台的查询请求，都不会被直接转发给上游模型，而是先经过一条由若干治理中间件串成的有序管道：路由、缓存检查点、安全护栏三类中间件按既定位次依次执行，在请求路径上完成模型选择、缓存短路、安全处置，再把请求转发到选定的上游模型，并在响应回程上逐层收尾。

本节面向部署、运维与二次开发灵渠平台的内部管理员，讲清两件事：

• 管道的编排模型——三类中间件各自做什么、按什么位次执行、如何按请求复杂度分流、何时短路、流式响应如何逐 chunk 处理（本页）。
• 管道的扩展点 SDK——如何以前置/后置对称 Hook 的形态接入自定义治理逻辑、Hook 的签名与生命周期、注册启停与编排约束（见 扩展点 SDK 参考）。

本节定位。 扩展点与编排是灵渠可编程能力的核心，本节是这部分能力的权威文档。后续若管道实现细节与本文出现偏差，以平台运营控制台「中间件编排」页的实际编排状态为准，本文随之修订。

1. 三类治理中间件

平台内建三类治理中间件。它们职责互不重叠，但在同一条请求路径上协同：路由先定"发给谁"，缓存检查点判"是否还要真发"，安全护栏管"发出去与收回来的内容是否合规"。

能力边界声明（重要）。 三类中间件均只在控制面 / 治理面对请求施加处置——选择上游、判定缓存、拦截或脱敏——并不对结果内容做实质性的生成、加工或合成。内容生成由路由选定的上游模型完成；平台对治理过程负责，对生成内容本身不做改写。这条边界在「中间件编排」页对每个中间件节点单独标注，也写入每个扩展点的能力声明。

2. 编排模型

2.1 执行位次：前置 / 内建 / 后置

管道按三个执行段位组织中间件节点，对应一次请求"去程—主调用—回程"的三个阶段：

• 三个段位的段间顺序固定：前置 → 内建 → 后置，不可调整；段位之内的节点顺序可在「中间件编排」页拖拽排序调整（见 §2.2）。
• 前置与后置在结构上对称：每一个在前置段执行的节点，在后置段都有与之配对的收尾位次（详见 扩展点 SDK 参考 的生命周期一节）。

2.2 组内位次：order

同一段位内的多个中间件节点，按 order（整数）决定执行先后——值小者先执行。order 相同时，按节点注册先后保序。

读取当前编排，可调用管道配置接口：

curl https://your-platform/api/v1/pipeline \
  -H "Cookie: <控制台会话凭证>"

响应给出三段位的节点序列、各节点的执行位次与编排属性：

{
  "nodes": [
    {
      "node_id": "<节点标识>",
      "node_kind": "route",
      "placement": "pre",
      "order": 10,
      "branch_condition": "<条件分支说明>",
      "short_circuit": false,
      "stream_per_chunk": false,
      "capability_boundary": "仅控制面治理处置，不实质性生成、加工或合成内容"
    },
    {
      "node_id": "<节点标识>",
      "node_kind": "cache_checkpoint",
      "placement": "pre",
      "order": 20,
      "short_circuit": true,
      "stream_per_chunk": false
    },
    {
      "node_id": "<节点标识>",
      "node_kind": "guardrail",
      "placement": "post",
      "order": 10,
      "stream_per_chunk": true
    }
  ]
}

调整段位内节点顺序，提交新的节点位次：

curl https://your-platform/api/v1/pipeline/order \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "Cookie: <控制台会话凭证>" \
  -d '{
    "nodes": [
      { "node_id": "<节点标识>", "placement": "pre", "order": 10 },
      { "node_id": "<节点标识>", "placement": "pre", "order": 20 }
    ]
  }'

段间顺序（前置 → 内建 → 后置）由平台固定，/api/v1/pipeline/order 只接受段位内的重排；若提交的位次试图把后置节点排到内建之前，会被拒绝并返回 400。

2.3 条件分支：按复杂度分流

路由中间件研判每个请求的复杂度，并据此让管道分流——不同复杂度的请求走不同的后续节点组合。分流条件以 branch_condition 声明，由路由中间件在前置段求值。

分流是结构内分支，不是另起一条管道：所有请求仍在同一条前置 → 内建 → 后置的骨架上流动，只是被分流节点跳过或附加若干处置。复杂度研判结果会随逐条调用记录落账（在「用量明细」页可见 complexity 字段），便于事后核对分流是否符合预期。

2.4 短路语义：缓存命中跳过上游

缓存检查点中间件在前置段判定本次请求是否命中平台侧缓存（即 语义缓存 的精确 / 语义两级判定）。一旦命中，它短路整条管道的内建段——不再向上游发起推理调用，直接以缓存内容进入后置段返回。

区分两种"缓存"。 触发上述短路的是平台侧语义缓存命中，不是上游模型供应商自家的输入缓存命中。上游供应商缓存命中仍会真实调用上游，只是落到更低的输入单价档（详见下方计量说明与 语义缓存 · 口径注）；唯有平台侧语义缓存命中才跳过上游调用。

短路时管道仍保证对称收尾：在短路点之前已经执行过的前置节点，其配对的后置节点仍会被依次执行（如计量落账、缓存命中标记写入），不会因短路而被跳过。换言之，短路跳过的是"还没发生的上游调用"，而不是"已经发生的前置处置的收尾"。

请求 → [前置] 路由 → [前置] 缓存检查点
                          │
                 命中？───┤
                          │是 → 短路：跳过内建上游调用
                          │       ↓
                          │   [后置] 护栏复核 → 计量落账 → 返回（semantic_hit=true）
                          │否 → [内建] 调用上游模型
                                  ↓
                              [后置] 护栏 → 缓存写入 → 计量落账 → 返回

此处触发短路、写入 semantic_hit=true 的是平台侧语义缓存命中。另有一个并行概念——上游模型供应商的输入缓存命中（计量记录里的 cache_hit，以上游返回为准、命中档计量单价相对更低）：它不触发短路，请求仍真实调用上游。短路是节流手段，不改变任何治理结论——护栏的出站复核在短路路径上同样执行。

2.5 流式逐 chunk 处理

当请求以流式（stream: true）发起时，上游模型分多个数据块（chunk）陆续返回。标记了 stream_per_chunk 的后置节点（典型为安全护栏中间件）会对每一个 chunk 逐块施加处置，而非等整段响应聚齐后一次性处理。

• 出站护栏（脱敏、应拒答复核）逐 chunk 执行，保证流式输出在生成过程中即被治理，不让违规内容先于护栏抵达客户端。
• 计量类后置节点在流末汇总：逐 chunk 累加词元用量，流结束时落一条完整的逐条调用记录。
• 路由与缓存检查点属前置段，不参与逐 chunk 回程处理（它们在请求转发前已完成判定）。

是否逐 chunk 处理由节点的 stream_per_chunk 属性声明，可在「中间件编排」页查看。非流式请求下，所有后置节点按整段响应一次性处理。

3. 一次请求在管道中的完整流转

把上述编排模型串起来，一次典型请求在管道中的流转如下：

查询请求进入
   │
   ▼  ── 前置段（pre）── 正序执行
① 鉴权与归属        校验 API 密钥 → 归属到对应子账户分账
② 路由中间件        研判复杂度 → 按分组/优先级/权重选定上游 → 健康检查
③ 入站护栏          注入防护 / 访问控制
④ 缓存检查点        命中？─是→ 短路（跳过内建段）
   │                       └否→ 继续
   ▼  ── 内建段（builtin）──
⑤ 上游推理          向选定上游模型发起调用（必要时重试 / 故障转移）
   │
   ▼  ── 后置段（post）── 与前置对称收尾
⑥ 出站护栏          脱敏 / 应拒答复核（流式逐 chunk）
⑦ 缓存写入          未命中时写入本次结果
⑧ 计量落账          6 档计价词元计量 → 逐条记录
   │
   ▼
响应返回（含 usage 计量信息、护栏处置结果、cache_hit / thinking 标识）

这条流转在「中间件编排」页以可视化编排图呈现，三类中间件节点、段位、条件分支、短路路径与能力边界标注一目了然，并可在段位内调整位次。每一次请求的实际路由轨迹（选定模型、重试次数、故障转移序号）可在「请求监控」页的路由轨迹明细中追溯。

4. 相关接口一览

本节涉及的管道编排接口集中在控制平面 /api/v1/pipeline/*，仅运营控制台可见：

完整端点契约见 API 参考。

下一步

• 扩展点 SDK 参考：前置/后置对称 Hook 模型、Hook 签名与生命周期、注册启停、编排约束与失败处置、能力边界声明。
• 安全护栏：安全护栏中间件的六类能力（输入/输出过滤、注入防护、脱敏、访问控制、个人信息检测、正反样本调优）、入站/出站对称处置与策略配置。
• 自定义插件开发：把 Hook 组织成可分发插件的工程闭环——构建产物、动态加载、注册、启停与失败处置。
• 用 Go 编写原生插件：原生可加载单元（Go）的语言落地指南——同进程、性能最优、须与平台运行环境构建参数对齐。
• 用 TypeScript 编写插件：经 AssemblyScript 兼容子集编译为 WASM 沙箱可加载单元的语言落地指南。
• 用 WebAssembly 编写插件：沙箱可加载单元的通用 host-guest ABI 与跨语言（Rust 等）编写路径。
• 多上游模型接入：路由中间件择优转发的目标侧——自有与第三方上游接入、模型池准入门槛、优先级与权重配置。
• API 参考：管道编排与扩展点接口的完整端点契约。