AIO Hub Documentation

Appearance

上下文管道 (Context Pipeline) ​

上下文管道是 LLM Chat 的核心数据处理引擎。每当你发送一条消息时，对话历史、智能体预设、世界书条目、知识库片段、会话变量及附件，都会流经这条精心编排的处理器流水线——最终组装成模型可理解的最优上下文。

这里的设置面板允许你可视化地管理整条管道：调整处理器的执行顺序、启用或禁用特定处理器，从而精细控制"模型到底看到了什么"。

界面操作 ​

拖拽排序 ​

每个处理器左侧有一个 Rank 拖拽手柄。按住并上下拖动即可改变处理器的执行顺序。

  • 顺序 = 优先级：列表中越靠上的处理器越先执行。
  • 自动保存：松手后顺序会立即持久化，无需手动确认。

启用 / 禁用 ​

每个处理器右侧有一个开关，用于控制是否参与管道执行。

  • 核心处理器：部分标记为"核心"的处理器（如会话加载器、异步任务处理器）不可禁用——它们保障了最基础的对话功能。
  • 按需关闭：如果你不使用世界书或知识库，可以关闭对应处理器以略微提升响应速度。

重置为默认 ​

点击右上角的 Refresh 重置为默认 按钮，可一键恢复系统推荐的处理器顺序和启用状态。

注意

重置操作不可撤销，执行前会弹窗确认。如果你精心调整过管道顺序，建议先记录当前配置。

处理器详解 ​

以下按默认执行顺序逐一介绍每个内置处理器。

1. 会话加载器 (Session Loader) ​

属性值
默认优先级100（最先执行）
类型核心（不可禁用）
  • 作用：从会话的树状结构中提取当前活动分支的线性历史记录，并转换为管道可处理的"中间格式消息"。
  • 为什么最先执行：它是管道的起点，负责为后续所有处理器提供原始消息数据。
  • 关键能力：
    • 压缩感知：已被上下文压缩的节点会被自动隐藏，不会重复出现在上下文中。
    • HTML → Markdown 转换：对于较旧的消息（超出最近 N 条），如果开启了优化选项，会自动将富文本转换为 Markdown 以节省 Token。
    • Tool 角色转换：可配置将 tool 角色消息转为 user 角色，兼容不支持 tool 角色的模型。

2. 异步任务处理器 ​

属性值
默认优先级110
类型核心
  • 作用：检测上下文中由 工具调用 产生的异步任务节点，从任务状态存储中获取最新进度或结果，动态替换节点内容。
  • 典型场景：当你让 AI 执行一个耗时操作（如文件转换、网络请求），该处理器会在下一轮对话时自动将"任务运行中 / 已完成 / 已失败"的最新状态注入上下文，让模型感知后续任务进展。
  • 为什么紧随其后：它修改的是原始节点内容，必须在消息加载后、后续所有文本处理（正则、Token 计算等）之前完成替换。

3. 正则处理器 (Regex Processor) ​

属性值
默认优先级200
类型可选
  • 作用：对历史消息内容执行正则替换规则。规则来源于三个层级：全局设置 → 智能体配置 → 用户档案，优先级由低到高。
  • 关键能力：
    • 角色过滤：规则可以限定只对特定角色（user / assistant / system）的消息生效。
    • 深度限制：规则可以设定深度范围，例如"只对最近 5 条消息生效"。
    • 应用阶段：规则区分"渲染阶段"和"请求阶段"，此处理器仅执行标记为"请求阶段"的规则。
  • 典型用途：清洗模型幻觉输出、移除不想发送给 API 的特殊标记、格式化特定模板。

顺序建议

默认将正则放在世界书之前，可确保关键词匹配基于清洗后的文本。如果你希望正则也能处理世界书注入的内容，可将其拖到世界书之后。

4. 转写与文本提取器 (Transcription Processor) ​

属性值
默认优先级250
类型可选
  • 作用：将消息中的音频/视频附件转写为文本，将文本类附件（如 .txt、.md）的内容读取并插入消息体，使其参与后续 Token 计算。
  • 关键能力：
    • 占位符替换：支持 【file::assetId】 占位符语法，转写结果会精准替换对应位置。
    • 智能回退：如果附件无法转写（如纯图片），会标注序号标签供多模态模型使用，原始附件保留。
    • 强制转写策略：可配置在较旧的消息中强制将媒体转写为文本（节省多模态 Token）。
  • 为什么在 Token 限制器之前：只有先将附件转为文本，后续限制器才能准确计算实际 Token 占用。

5. 世界书处理器 (Worldbook Processor) ​

属性值
默认优先级300
类型可选
  • 作用：扫描历史消息中的关键词，触发匹配的世界书条目并注入到上下文中。
  • 关键能力：
    • 多种激活条件：Constant（始终激活）、关键词匹配、Delay（历史不足 N 条时不激活）、Cooldown（激活后冷却）、Sticky（匹配后持续生效）。
    • 递归扫描：已注入的条目内容也会参与关键词匹配，可触发连锁激活。
    • 包含组竞争：同一组内的条目按权重竞争，只有"赢家"被注入，防止上下文膨胀。
    • 位置注入：支持 BeforeChar、AfterChar、Depth（从末尾倒数）等多种注入位置。
    • 角色/标签过滤：条目可限定只对特定智能体或标签生效。
  • SillyTavern 兼容：完整兼容 ST 的世界书格式和大部分高级特性。

6. 注入组装器 (Injection Assembler) ​

属性值
默认优先级400
类型核心
  • 作用：这是管道中最核心的组装步骤。它负责处理智能体预设消息的分类、宏展开，并将预设骨架、深度注入、锚点注入与历史消息进行精密组装。
  • 关键能力：
    • 消息分类：预设消息被分为三类——骨架（按数组顺序）、深度注入（按深度值插入历史）、锚点注入（绑定到特定锚点前后）。
    • 宏处理：在组装前展开所有 {{宏}} 占位符（如 {{user}}、{{char}}、{{time}}），具体逻辑由内置宏引擎处理。
    • 高级深度配置：支持单点 "5"、多点 "3, 10, 15"、循环 "10~5"（从第10条起每5条插入一次）和混合语法。
    • 模型/渠道匹配：预设消息可配置正则规则，仅在特定模型或渠道下生效。
    • 工具宏保底：如果开启了工具调用但预设中没有 {{tools}} 宏，系统会自动追加一条保底注入。

7. 知识库处理器 (Knowledge Processor) ​

属性值
默认优先级450
类型可选
  • 作用：扫描消息中的 【kb】 或 【knowledge】 占位符，执行 RAG 检索，将匹配的知识片段替换到占位符位置。
  • 关键能力：
    • 多种激活模式：always（每轮激活）、gate（关键词门控）、turn（每 N 轮激活）、static（静态加载指定条目）。
    • 参数化占位符：【kb::库名::数量::最低分::模式::参数】，支持精细控制每个检索点的行为。
    • 查询预处理：自动清洗、分词、停用词过滤和标签匹配。
    • 精确文本缓存：采用精确文本匹配策略（完全一致才命中），适用于同轮多占位符和重试场景。
    • 独立检索：每次检索独立执行，不混入历史结果。分数阈值作为主要截断依据。
  • 为什么在注入组装器之后：占位符通常存在于预设消息中，必须等注入组装器完成骨架组装后才能扫描到。

了解更多

知识库处理器的完整配置选项（引擎选择、缓存策略、模板定制等）请参阅 RAG 知识库检索配置。

8. 会话变量处理器 (Variable Processor) ​

属性值
默认优先级500
类型可选
  • 作用：解析消息中的 <svar> 标签，维护变量的状态快照，并执行 $[...] 内置替换符的动态渲染。
  • 关键能力：
    • 标签语法：<svar name="hp" op="+" value="10" /> —— 对变量执行加减乘除或赋值操作。
    • 快照回溯：从最新消息往回查找最近的变量快照作为计算起点，确保分支切换后状态正确。
    • 边界约束：变量定义中可设置 min / max，运算结果会自动钳制到合法范围。
    • 格式化输出：支持 $[svars::table] 将所有可见变量渲染为表格，$[svars::list] 渲染为列表。
  • 为什么在 Token 限制器之前：替换后的变量内容需要参与 Token 计算，否则预算不准确。

9. Token 限制器 (Token Limiter) ​

属性值
默认优先级600
类型核心
  • 作用：根据智能体配置的"最大上下文 Token"预算，从历史消息中截断超出部分，确保最终发送的上下文不超标。
  • 关键能力：
    • 预设优先：先计算所有预设/注入消息的 Token 占用，剩余预算全部分配给历史消息。
    • 从新到旧保留：保留最新的历史消息，截断最旧的部分。
    • 部分截断保留开头：可配置被截断消息保留前 N 个字符（附加"…(已截断)"标记），而非完全丢弃。
    • 附件 Token 计算：图片等附件也会计入 Token 预算（按模型定义的图片 Token 消耗）。
    • 统计信息输出：处理完成后会在共享黑板中记录截断前后的 Token 和字符数变化，供上下文分析器展示。

关键顺序约束

Token 限制器必须在注入组装器和变量处理器之后执行。只有当所有内容（预设、知识库、变量替换）都已注入完毕，限制器才能准确计算总 Token 占用并精准截断。

10. 消息格式化器 (Message Formatter) ​

属性值
默认优先级800
类型可选

  • 作用：在发送前应用模型特定的消息结构规则，确保请求格式符合不同厂商 API 的要求。

  • 包含四个子规则：

    子规则默认状态说明
    合并 System 到头部✅ 启用将分散的 system 消息合并为一条
    合并连续相同角色✅ 启用将相邻同角色消息合并（如两条连续的 user）
    转换 System 为 User❌ 禁用适用于不支持 system 角色的模型
    确保角色交替❌ 禁用在连续同角色间插入占位符，强制 user/assistant 交替

  • 配置合并策略：默认状态 → 模型定义覆盖 → 智能体配置覆盖。

  • 典型场景：Claude 模型要求 user/assistant 严格交替；某些本地模型不支持 system 角色。

11. Base64 资源解析器 (Asset Resolver) ​

属性值
默认优先级10000（最后执行）
类型核心
  • 作用：管道的最后一步。将剩余的二进制附件引用（图片、文档、音视频）转换为模型 API 可接受的最终格式。
  • 关键能力：
    • 按模型能力适配：根据模型是否支持视觉、原生 PDF 等能力，选择合适的发送格式。
    • PDF 智能转换：如果模型不支持原生 PDF 但支持图片，自动将 PDF 渲染为图片序列。
    • 容错处理：单个附件转换失败不会中断其他附件的处理。
  • 为什么最后执行：Base64 编码后的数据体积极大，如果在前面步骤就转换，会严重拖慢正则匹配、Token 计算等文本处理操作。

为什么顺序很重要？ ​

管道的编排顺序直接影响数据的可见性和计算的准确性。以下是几个关键的顺序依赖关系：

正则 vs 世界书 ​

  • 默认：正则在前 → 确保世界书扫描的是清洗后的文本。
  • 如果反转 → 正则也能修改世界书注入的内容（适合需要统一清洗所有内容的场景）。

注入组装 + 变量 → Token 限制 ​

这是硬性约束。限制器必须看到完整的最终内容才能准确计算。如果把限制器放到组装器前面，预设消息的 Token 占用不会被计入预算，导致实际发送的上下文超标或历史被过度截断。

资源解析必须最后 ​

Base64 数据不参与任何文本逻辑（正则、关键词匹配、Token 计数都基于原始文本完成），所以必须延迟到一切文本处理结束后才转换，这也是为什么它的优先级被设为 10000。

常见操作场景 ​

"我不用世界书和知识库，想提速" ​

关闭世界书处理器和知识库处理器的开关即可。管道会跳过这两步，减少不必要的扫描。

"我想让正则也清洗世界书注入的内容" ​

将正则处理器拖到世界书处理器的下方。这样正则会在世界书注入完成后才执行。

"模型报错说消息格式不对" ​

启用消息格式化器中的对应子规则。例如：

  • 报 "user messages must alternate" → 启用"确保角色交替"
  • 报 "system role not supported" → 启用"转换 System 为 User"

"上下文好像总是超长" ​

检查 Token 限制器是否被禁用或排在了注入组装器之前。确保它在列表中位于所有注入类处理器的下方。

进阶阅读

Released under the Apache-2.0 License.

Copyright © 2024-present miaotouy