从零理解 Semantix

本文写给希望系统理解 Semantix 的开发者。它从项目为何存在讲起，再解释核心机制、架构边界、当前进度与常见误解。 如果你是第一次接触 Semantix，建议先读项目速览建立整体认识，再通过本文深入理解设计选择。

第一章：从生态谈起——为什么会出现"Agent Kernel 层"这个概念

要理解 Semantix，先要理解它所在的生态位置。

1.1 LLM Agent 是什么

LLM Agent（智能体）是一个以 LLM 为"大脑"的软件系统，它通过循环执行"思考 → 调用工具 → 观察结果 → 再思考"来完成用户交给它的任务。典型工具包括：读文件、搜索代码、执行命令、编辑文件、运行测试、访问网络。

以编码 agent 为例，一次典型任务长这样：

用户："给 http client 加个重试"
Agent 思考 → 读文件（net/client.go）→ 搜索相关代码 → 编辑文件 → 跑测试 → 完成

1.2 Agent Harness 是什么

Agent Harness（agent 框架/载体）是承载这个循环的软件壳：它负责管理会话、调用模型、执行工具、处理权限、保存历史。常见的例子：

• DeepSeek-Reasonix：Go 编写的开源编码 agent，基于 DeepSeek 模型
• Claude Code：Anthropic 的终端编码 agent
• 其他：Cursor、OpenAI Codex CLI 等

1.3 现有 harness 的共同短板

无论哪个 harness，都存在三个结构性问题：

1. 缓存是会话内的：厂商提供的前缀缓存（如 DeepSeek 的 context caching）只在"同一个会话"里有效。新开一个会话做相似任务，所有上下文都要重新计算、重新付费。
2. 调度是静态的：并发度、模型选择、资源分配是写死的规则，不根据"这个任务是什么类型"和"用户习惯怎么做"来调整。
3. 等待是被浪费的：模型在流式输出时，agent 干等着；模型在等工具结果时，agent 也干等着。这些墙钟时间（一次任务里可达几十秒到几分钟）白白流逝。

1.4 结论：需要一个"中间层"

既然 harness 的短板是结构性的，而 harness 本身又不好改（每个 harness 的实现不同、改动成本高），自然的思路是：在 harness 与资源之间，插一个独立的中间层——它不改 harness，而是包裹 harness，通过观察 harness 的行为来优化整个循环。

这个中间层，就是 Agent Kernel 层。Semantix 就是这样一个 Agent Kernel 层。

第二章：Semantix 的定位——它到底是什么

2.1 一句话定位

Semantix 是一个自进化的 Agent Kernel 层：它架在 agent harness（DeepSeek-Reasonix、Claude Code 等）与资源之间，动态编排并发、语义缓存与投机预取，并基于用户使用习惯自我进化，让系统越用越快、越用越便宜。

2.2 三个关键词拆解

"Agent Kernel 层"——位置。它在 harness 之下（不替代 harness），在资源之上（LLM API、文件系统、工具）。它是"内核"，意味着它提供的是基础设施能力（缓存、调度、预取），而不是面向用户的界面。

"语义"——粒度。它操作的不是字节（byte），而是语义单元（slice，切片）。字节缓存要求内容完全一致才能命中；语义缓存允许"相似"的内容被识别和复用。

"自进化"——时间。它不是静态规则，而是闭环学习系统：每次交互都会产生反馈信号，信号驱动参数调整，参数调整让下一次交互更优。

2.3 它解决的具体问题（再次明确）

2.4 它的使用方式

用户不需要直接"操作" Semantix。它的工作方式是：

1. 你照常用你的 agent（Reasonix / Claude Code）干活；
2. Semantix 通过适配层观察你的会话（事件流）；
3. 它把历史会话沉淀成语义切片（任务模板、上下文块、工具模式、结果、记忆）；
4. 下次相似任务来时，它注入相关切片（命中厂商字节缓存）、调度并发、预取资源；
5. 每一轮产生的信号（命中/污染/延迟/成本/成功率）反馈给进化引擎，参数持续优化。

用户唯一能感知到的：任务变快了、账单变便宜了、而且越用越明显。

第三章：它怎么工作——四组件一引擎

3.1 语义切片库（SSL，Semantic Slice Library）——记忆

职责：从历史会话中提取、索引、持久化可复用语义单元。

五种切片类型：

提取策略（三种切分）：

• turn 边界切分：以用户消息为边界切分
• 完成点分段：以任务完成为边界切分上下文
• T-Slice n-gram：从工具调用序列提取连续模式

存储：bbolt 双库（项目级库 + 用户级库），区分作用域。

3.2 三级语义缓存（L1/L2/L3）——变现

L1（字节缓存）：沿用厂商的自动前缀缓存。会话内完全一致的前缀零成本命中。

L2（稳定注入）：这是 Semantix 最精妙的设计——语义层喂养字节层。

• 检索到语义相似的切片后，原样（verbatim）注入到系统前缀之后、用户消息之前；
• 注入顺序固定（不按价值排序），保证字节稳定；
• 下次新会话开始时，同样的注入集 → 同样的字节前缀 → 命中厂商的字节缓存；
• 效果：语义命中被"翻译"成了字节命中，享受厂商缓存的价格优惠。

L3（验证复用）：对只读任务，带文件指纹验证，直接复用历史结果，连模型请求都不发。fail-closed：验证不过就用，用户可否决。

3.3 内核调度器（Kernel Scheduler）——编排

• intent 分类：识别任务类型（读/写/搜索/重构/测试…）
• 联合决策：并发度、模型 tier、缓存注入量、预取预算
• 行为学习：从 T-Slice 统计中学习"这类任务通常怎么做"，让决策越来越贴合实际

3.4 投机预取器（Speculative Prefetcher）——填空闲

• 预测：用 T-Slice 转移矩阵预测下一步要调用的工具/要读的资源
• 预取：在模型流式输出的等待期，预取只读资源（下一轮的切片组装、embedding 计算）
• 自惩罚：waste/hit 比例超过阈值（默认 3:1）自动降权该信号源——预取策略本身也进化

3.5 自进化引擎（Self-Evolution Engine）——学习

在线层（每轮）：

• 采集信号：命中率、污染、延迟、成本、成功率
• EWMA 滑动平均调参：阈值 τ、注入预算、预取参数、并发度、tier 映射
• 冻结期保护：参数变更后注入集 ≥1 小时不变，防止进化抖动摧毁自己喂养的字节缓存

离线层（周期）：

• 切片嵌入刷新
• 阈值网格搜索
• T-Slice 转移矩阵重训
• 低频切片归档

第四章：设计哲学——七条原则

1. 前缀永不改：注入集字节稳定是 L2 命中的生命线。
2. 只读才预取：投机预取只碰只读资源，杜绝副作用。
3. fail-open / fail-closed：缓存层故障不阻塞主循环；安全边界绝不妥协。
4. 一切决策可解释、可回滚：每个决策带 reason，支持 ablation 开关。
5. MIT 参考不抄：参考 Reasonix 思路，代码独立实现 + attribution。
6. 单一 kernel，多 harness：适配层模式，不绑架任何特定 agent。
7. 参数自生长：系统参数由反馈进化而来，不靠人工调优。

第五章：与相关概念的关系

5.1 Semantix 与 Agent Harness（Reasonix、Claude Code）

• Semantix 架在 harness 之上，通过适配层连接；
• harness 负责"干活"（思考、调用工具、交互），Semantix 负责"让干活越来越便宜"（缓存、调度、预取）；
• 它们不是竞争关系，是协作关系：Reasonix + Semantix 可以一起用。

5.2 Semantix 与语义缓存（GPTCache 等）

• GPTCache 等语义缓存工具解决"同样的对话问题重复付费"；
• Semantix 的语义缓存面向 agent 工作负载：切片来自工具调用序列、任务模板、结果复用，且通过"稳定注入"把语义命中转化为厂商字节缓存的命中——这是现有语义缓存工具没有的机制。

5.3 Semantix 与自进化 / 反思类方法（Reflexion、Voyager 等）

• Reflexion/Voyager 等让 agent 本身从经验中学习（技能库、反思）；
• Semantix 让 基础设施层（缓存/调度/预取）从经验中学习；
• 两者互补：前者改进"怎么做任务"，后者改进"做任务的成本与速度"。

5.4 Semantix 与 KV Cache / 前缀缓存系统（SGLang、vLLM 等）

• SGLang/vLLM 等是服务端的 KV cache 系统，面向自托管推理；
• Semantix 面向调用厂商 API的场景（如 DeepSeek API），在客户端通过 prompt 工程手段（稳定注入）利用厂商的自动前缀缓存；
• 两者解决不同层的问题，Semantix 的方案在闭源 API 场景下尤其有价值——因为用户无法控制服务端的 KV cache。

第六章：常见误解与准确表述

以下内容用于澄清开发者最容易混淆的几个问题：

关于定位：Semantix 是一个中间件层，它架在 agent harness 之上、资源之下，提供缓存、调度、预取基础设施能力。它本身完成 agent 的思考与工具调用循环。

关于模型：Semantix 不训练模型、不修改模型、不提供模型。它优化的是模型调用之前的 prompt 组装与调用之后的资源编排。

关于缓存：Semantix 的缓存机制包含字节级（L1）、语义注入（L2）与结果复用（L3）三个层次，其中 L2 通过保持前缀字节稳定来利用厂商自动前缀缓存。

关于部署：Semantix 本地运行（Go 实现，bbolt 存储，仅一个外部依赖），数据（切片、统计）持久化在本地双库中。

关于使用方式：Semantix 通过适配层与具体 harness 连接，用户无需直接操作 Semantix——它自动从使用中学习并优化。

第七章：速查——用一句话回答"Semantix 是什么"

1. 给技术人：Semantix 是一个位于 agent harness 与资源之间的自进化中间件，用语义切片 + 稳定注入把跨会话的语义命中转化为厂商字节缓存命中。
2. 给产品人：Semantix 是一个越用越便宜、越用越快的 agent 加速层——自动复用你过去的劳动成果。
3. 给研究者：Semantix 是一个闭环学习系统：观测 → 沉淀 → 复用 → 进化，每个组件对应一个可验证的设计假设。
4. 给开源爱好者：Semantix 是一个 MIT 许可、Go 实现、设计文档齐全、正在早期开发阶段的社区项目。

本文由项目维护者撰写；具体状态与实现进度以仓库为准。