HotPlex 术语表

June 4, 2026 · View on GitHub

本文档收录 HotPlex 项目涉及的全部核心术语。按拼音字母顺序排列，每个术语包含英文原名、中文释义和详细说明。

A

AEP (Agent Event Protocol)

HotPlex 自定义的 WebSocket 全双工通信协议。基于 JSON 信封（Envelope）格式，定义了客户端与网关之间的统一消息交互规范，包括事件类型、序列号分配、背压策略和握手流程。当前版本为 aep/v1，定义于 pkg/events/events.go 和 pkg/aep/codec.go。

AEP 事件分为三个方向：C→S（客户端到服务端，如 init、input、control）、S→C（服务端到客户端，如 state、message.delta、done）和双向（如 ping/pong）。所有业务消息通过严格的 seq 序列号在 session 级别有序编排。

Admin API

HotPlex 提供的 HTTP 管理接口，默认监听 localhost:9999。支持 session 管理、配置查询、诊断端点等运维操作。通过 Token 认证和细粒度 Scope 授权（如 session:read、config:write）控制访问权限。

Agent 配置的指令通道（Directives Channel），以 XML <directives> 标签注入 Worker 的系统提示词。内容包括 <hotplex>（META-COGNITION.md，始终存在且排首位）、<persona>（SOUL.md）、<rules>（AGENTS.md）和 <skills>（SKILLS.md）。B 通道为强制性指令，与 C 通道冲突时无条件覆盖。

配置文件存放于 ~/.hotplex/agent-configs/，通过三级 fallback 加载：全局 → 平台（slack/）→ Bot（slack/U12345/），每文件独立解析，命中即终止。

Brain

HotPlex 的 LLM 编排层（internal/brain/），提供单一 Brain 接口（Chat + ChatWithOptions）。通过 enhancedBrainWrapper 实现，内部集成超时控制、模型路由、请求限流、熔断保护和指标记录。

Brain 通过装饰器链（decorator chain）组合功能：retry → cache。Rate limiting 和 circuit breaker 在 wrapper 内部直接处理，避免双重限流并确保 metrics 计时准确。LLM 客户端子包（internal/brain/llm/）提供 OpenAI/Anthropic 适配 + 模型路由 + 成本估算。

输出脱敏功能（security.RedactSensitive）已提取到 internal/security/sanitize.go 作为独立工具，不依赖 Brain 模块。

Bridge

Session 与 Worker 之间的生命周期编排器（internal/gateway/bridge.go）。负责 Worker 的 fork/exec、事件转发（Worker stdout → Hub 广播）、崩溃检测与恢复（resume → fresh start fallback）、LLM 自动重试，以及 Agent 配置注入。

Bridge 还实现了 resetGenerationer 接口的 reset-aware 崩溃处理：通过单调递增的 generation 计数器区分"正常的 reset 重启"和"异常崩溃"，避免误触发 crash recovery。

C

C 通道 (C Channel)

Agent 配置的上下文通道（Context Channel），以 XML <context> 标签注入 Worker 的参考信息。内容包括 <user>（USER.md，用户偏好）和 <memory>（MEMORY.md，长期记忆）。C 通道为参考性内容，与 B 通道冲突时以 B 通道为准。

CardKit

飞书卡片渲染框架 v2（internal/messaging/feishu/streaming.go）。支持流式更新（Streaming Card），在 Worker 输出过程中实时刷新卡片内容。HotPlex 实现了四层防御机制：TTL guard（10 分钟超时）→ 完整性检查 → 带退避重试 → IM Patch 降级兜底，以处理 CardKit 服务降级的场景。

Context Compressor

~~Brain 模块的上下文压缩组件~~。已在 v1.25 中移除。对话 token 管理现由 Worker（Claude Code）原生处理，Brain 模块专注于 LLM 客户端能力。

Cron

HotPlex 的 AI-native 定时任务引擎（internal/cron/），支持三种调度方式：cron（标准 cron 表达式）、every（固定间隔）和 at（一次性执行）。任务 payload 为自然语言提示词，由 Worker 以 Agent Turn 形式执行。

Cron 系统包括：timerLoop tick 引擎（timer.go）、并发槽 CAS 控制、SQLite 持久化（store.go）、YAML 批量导入（loader.go）、执行结果投递（delivery.go，按平台回传飞书卡片/Slack 消息），以及 at 类型指数退避重试（retry.go）。Cron 的技能手册通过 go:embed 嵌入 B 通道（skill.go）。

D

Delta Coalescing

流式消息增量合并机制。pcEntry（internal/gateway/platform_writer.go）在 writeLoop 中将连续的可丢弃事件（message.delta、raw）合并后批量发送到消息平台，减少 HTTP API 调用次数。

配置项包括 DeltaCoalesceInterval（合并时间窗口）和 DeltaCoalesceSize（合并大小阈值），通过 pcEntryConfig 控制。

E

Envelope

AEP v1 消息信封（pkg/events/events.go），所有客户端-网关通信的统一封装格式。结构体字段包括 version（必须为 aep/v1）、id（消息唯一标识）、seq（session 内严格递增序列号）、session_id、timestamp（Unix ms）、priority（data/control，control 跳过背压）、event（包含 type 和 data），以及仅服务端使用的 OwnerID（json:"-"，不序列化到网络）。

Envelope 通过 Clone() 方法实现深拷贝（递归复制嵌套 map/slice），确保热路径上的并发安全。

G

GC (Garbage Collection)

Session 垃圾回收机制（internal/session/manager.go）。定期扫描（默认 60s 间隔）并清理过期或僵尸 session：

IDLE 超时：idle_expires_at ≤ now → TERMINATED
最大生命周期：expires_at ≤ now → TERMINATED
僵尸检测：RUNNING session 的 LastIO() 超过 execution_timeout（默认 30 分钟）→ TERMINATED
保留期清理：TERMINATED session 按 source 差异化保留：cron 类保留 24h、其他保留 7d（cron_term_retention / term_retention），过期后 DELETE FROM sessions

H

Hot-Multiplexing

HotPlex 的核心复用模式：单个 Worker 进程服务多个 Turn（对话轮次），避免冷启动开销。Session 进入 IDLE 状态时 Worker 不终止，收到新 input 时直接复用现有进程恢复执行（IDLE → RUNNING），跳过 fork+exec 的延迟。

对于 OpenCode Server 适配器，这一模式通过全局 SingletonProcessManager 进一步强化：所有 OCS Worker 共享一个 opencode serve 进程（通过 atomic.Pointer 实现并发安全的单例管理），Worker 本身仅为轻量级 SSE 适配器。SingletonProcessManager 使用引用计数跟踪活跃 Worker，当引用归零后启动空闲排空计时器（默认 30 分钟），超时后自动关闭共享进程以释放资源。

Hub

WebSocket 广播中心（internal/gateway/hub.go），管理连接注册和消息路由。维护两张映射表：conns（所有活跃 WS 连接集合）和 sessions（sessionID → SessionWriter 集合的多对多映射）。

Hub 实现背压策略：message.delta 和 raw 类型事件在通道满时静默丢弃（非阻塞 select），state/done/error 等关键事件阻塞发送、永不丢弃。SeqGen（sync.Map + per-session atomic.Int64）为每个 session 分配严格递增的序列号。

I

Intent Router

~~Brain 模块的意图分发组件~~。已在 v1.25 中移除。消息路由现由 Gateway 直接处理，所有用户消息统一转发到 Worker，无需中间意图分类层。

J

Job Object

Windows 平台的进程隔离机制（internal/worker/proc/），等效于 POSIX 的 PGID。通过 Windows Job Object 确保 Worker 进程树在父进程退出时被完全清理。HotPlex 使用 *_unix.go / *_windows.go build tags 实现跨平台进程管理。

M

META-COGNITION

自动注入 B 通道的元认知文件（internal/agentconfig/META-COGNITION.md），通过 go:embed 嵌入，始终存在于 B 通道首位。定义 Worker 的身份边界（不管理 Transport/状态/协议）、B/C 通道冲突隔离法则、配置替换的"命中即终止"机制，以及配置修改 SOP（禁止改全局来影响 Bot）。

Messaging Bridge

消息平台（Slack/飞书）与 Gateway 之间的桥接层（internal/messaging/bridge.go）。实现 3 步 session 生命周期：StartPlatformSession（创建 session + fork Worker）→ JoinPlatformSession（注册到 Hub 接收事件）→ Handle（处理 Worker 输出和交互请求）。

N

NDJSON (Newline-Delimited JSON)

每行一个 JSON 对象的序列化格式。HotPlex 的 AEP 协议使用 NDJSON 作为 WebSocket 帧的编码格式（pkg/aep/codec.go），Worker 的 stdin/stdout 也使用 NDJSON 通信（Claude Code 通过 --print --session-id 模式的 stdio 接口）。

O

OTEL (OpenTelemetry)

分布式追踪标准。HotPlex 通过 internal/tracing/tracing.go 集成 OpenTelemetry SDK，为每个 AEP 事件创建 Span（命名格式 aep.{event_type}），传播 trace context 到下游组件。支持尾部采样策略：ERROR trace 100% 保留，高延迟 trace 优先保留，正常 trace 1% 采样。

OCS (OpenCode Server)

OpenCode Server Worker 适配器（internal/worker/opencodeserver/），通过单例 opencode serve 进程（HTTP+SSE）提供 Agent 能力。与 Claude Code 的 stdio 模式不同，OCS 使用全局 SingletonProcessManager 管理共享进程，通过引用计数和空闲排空（默认 30 分钟无引用 → 杀进程）优化资源使用。

P

pcEntry

PlatformConn 包装器（internal/gateway/platform_writer.go），将消息平台的 PlatformConn 适配为 Hub 的 SessionWriter 接口。内置异步 writeLoop goroutine 和 Delta Coalescing：写请求进入缓冲 channel，writeLoop 从 channel 读取，合并连续的可丢弃事件后批量发送。

pcEntry 解耦了 Hub.Run() 的主循环与消息平台 HTTP API 调用的阻塞延迟，防止平台 API 响应慢时影响 WebSocket 广播性能。

PGID (Process Group ID)

进程组标识符，用于 POSIX 系统（Linux/macOS）的进程隔离和清理。HotPlex 在 fork Worker 进程时设置 Setpgid: true 创建独立进程组，终止时通过 syscall.Kill(-pid, signal) 向整个进程组发送信号，确保子进程也被清理。

分层终止流程：SIGTERM → 等待 5s → SIGKILL，在 internal/worker/proc/ 中实现。

Platform Bridge

消息平台 ↔ Gateway 的桥接层，参见 Messaging Bridge。

PlatformConn

消息平台连接的写端抽象接口（internal/messaging/platform_conn.go），定义两个方法：

WriteCtx(ctx, env) — 将 AEP Envelope 写入平台（如飞书 API、Slack Web API）
Close() — 永久关闭连接及其关联 goroutine

PlatformConn 是 Hub.JoinPlatformSession 所需的最小接口，使消息平台适配器无需包装为 WebSocket 连接即可注册到 Hub。

PoolManager

Session 配额管理器（internal/session/pool.go），维护两级配额：全局最大活跃 Worker 数（默认 20）和每用户最大空闲 Session 数（默认 5）。通过 Acquire/Release 原子计数器管理配额，超限时返回 ErrPoolExhausted 或 ErrUserQuotaExceeded。

R

ReadPump / WritePump

WebSocket 连接的读写泵（internal/gateway/conn.go）。ReadPump 在独立 goroutine 中循环读取 WS 帧，解析为 AEP Envelope 后分发到 Handler；WritePump 将 Hub 广播的消息写入 WS 连接。两者协同实现全双工通信，通过 ping/pong 心跳机制检测连接存活（默认 60s 超时）。

S

Safety Guard

~~Brain 模块的安全审计组件~~。已在 v1.25 中移除。输出脱敏功能（security.RedactSensitive）已提取到 internal/security/sanitize.go 作为独立工具，提供 7 种敏感数据模式检测（API key、AWS key、PEM 块、JWT、内网 IP、数据库连接串、密码）。

Seq (Sequence Number)

AEP 消息序列号。每个 session 内从 1 开始严格递增，由 Hub 的 SeqGen（sync.Map + per-session atomic.Int64）原子分配。ping/pong 不消耗 seq（字段为 0）。

Seq 保证同一 session 内消息的有序性，用于客户端检测丢包和重排序。被背压丢弃的 message.delta 不消耗 seq。

Session

HotPlex 的核心生命周期单元，代表一次完整的对话。Session 独立于底层连接（WebSocket/Slack/飞书），通过 5 状态机管理生命周期：CREATED → RUNNING → IDLE → TERMINATED → DELETED。

Session ID 通过 UUIDv5 确定性生成（internal/session/key.go），相同的输入参数（ownerID + workerType + clientKey + workDir）始终产生相同的 ID，确保对话恢复的一致性。

Socket Mode

Slack 的 WebSocket 连接模式。HotPlex 的 Slack 适配器（internal/messaging/slack/）使用 Socket Mode 建立到 Slack 的持久 WS 连接，无需公网入口（ingress）即可接收 Slack 事件。支持流式消息、交互管理和 STT 语音转写。

STT (Speech-to-Text)

语音转文本功能（internal/messaging/stt/）。PersistentSTT 组件将飞书语音消息转写为文本后送入 Worker 处理。支持多策略转写（云端 API + 本地工具），跨平台进程隔离（POSIX PGID / Windows Job Object）。

State Machine

Session 的 5 状态机（internal/session/manager.go）：

状态	IsActive	语义
`CREATED`	true	Session 已创建，瞬态（<1s）
`RUNNING`	true	Worker 正在执行
`IDLE`	true	Worker 暂停，等待新输入或重连
`TERMINATED`	false	Worker 已终止，保留历史记录
`DELETED`	false	终态，DB 记录已删除

状态转换规则严格定义，非法转换返回 ErrInvalidTransition。TransitionWithInput 在同一 mutex 内完成状态转换 + input 记录，防止 done/input 竞态。

T

Token Scopes

Admin API 的权限粒度控制。每个 API Token 可配置一组 scope（如 session:read、session:write、config:read、config:write），在 config.yaml 的 admin.token_scopes 字段中以 token → scopes 映射定义。未配置 scope 的 Token 使用 default_scopes 兜底。

TTS (Text-to-Speech)

文本转语音功能（internal/messaging/tts/）。使用 Edge-TTS（微软语音合成引擎）+ FFmpeg Opus 转换。支持 fallback 机制（FallbackSynthesizer）：primary 失败时自动切换到 backup 合成器。配置项包括 provider（edge+moss）、voice（如 zh-CN-XiaoxiaoNeural）和 maxChars（单次合成字符上限）。

Turn

一个请求-响应周期：用户输入（input）→ AI 处理（state: running → message.delta 流式输出 → message.end）→ 完成（done）。Turn 是 HotPlex 计费、配额和超时的基本计量单位。Session 忙碌时（RUNNING 状态）新 input 被硬拒绝（SESSION_BUSY），不排队。

U

UUIDv5

确定性 session ID 生成算法（internal/session/key.go），基于 SHA-1 哈希（RFC 4122 §4.3）。核心函数 DeriveSessionKey(ownerID, workerType, clientKey, workDir) 保证相同的输入参数始终产生相同的 session ID，支持对话恢复。

HotPlex 使用固定命名空间 UUID（6ba7b810-9dad-11d1-80b4-00c04fd430c8）作为 UUIDv5 的 namespace。Cron 系统使用独立的 CronNamespace（从主 namespace 派生）确保定时任务 session 与普通 session 永不冲突。

W

WAL (Write-Ahead Logging)

SQLite 的预写日志模式。HotPlex 强制启用 PRAGMA journal_mode=WAL + PRAGMA busy_timeout=5000，写入通过单写 goroutine 串行化。WAL 模式允许读写并发（读不阻塞写、写不阻塞读），提升 session 持久化（internal/session/store.go）和 cron 存储（internal/cron/store.go）的吞吐量。

Worker

AI Coding Agent 适配器，将不同的 Agent 运行时统一接入 HotPlex。Worker 通过 init() + worker.Register() 模式注册，当前实现：

Claude Code（internal/worker/claudecode/）— stdio 模式，通过 --print --session-id 交互
OpenCode Server（internal/worker/opencodeserver/）— 单例进程，HTTP+SSE 交互

所有 Worker 嵌入 base.BaseWorker，共享 Terminate/Kill/Wait/Health/LastIO/ResetContext 生命周期。Worker 接口定义：Start(ctx, env)、Input(ctx, content)、Terminate()、Kill()、Wait()、Health() 等。