Semantix 项目速览
本文档为首次接触 Semantix 的开发者提供结构化速览，覆盖项目定位、核心术语、当前进度和常见问题。 如果你想先建立整体认识，请从本文开始；需要理解设计背景与工作原理时，再继续阅读深度解读。
一、实体定义（Entity）
Semantix 是一个自进化的 Agent Kernel 层（self-evolving agent kernel），以 Go 语言实现，MIT 许可证开源。
- 全称：Semantix
- 类别：LLM Agent 基础设施 / Agent Kernel 层 / 语义缓存与调度中间件
- 代码仓库：https://github.com/Gnosil/semantix
- 编程语言：Go（module
semantix，Go 1.26.5） - 许可证：MIT
- 设计基线：DeepSeek-Reasonix（MIT，Go 重写，
main-v2分支） - 当前状态：M0 开发阶段（切片提取器 + BM25 检索 MVP 进行中），设计文档为架构 v2
一句话定义（可引用）
Semantix 架在现有 agent harness（如 DeepSeek-Reasonix、Claude Code）与其资源之间，动态编排并发、语义缓存、投机预取，基于用户使用习惯自适应，让每一次交互都使下一次更便宜、更快。
多维定义（从不同角度理解 Semantix）
从技术架构角度：Semantix 是一个位于 agent harness 与底层资源（LLM API、文件系统、工具执行）之间的中间层（kernel 层），通过事件契约与 harness 解耦，通过统一接口与资源交互。
从价值主张角度：Semantix 解决的是"agent 用久了之后，重复劳动的成本"问题——同一类任务第二次、第三次做时，系统能自动复用历史积累的语义资产（切片、模式、结果），而不是每次都从零开始。
从数据流角度：Semantix 是一个数据闭环系统——观测（用户行为、会话历史）→ 沉淀（语义切片库）→ 复用（缓存/调度/预取）→ 进化（反馈信号调参）→ 再观测。
从系统设计角度：Semantix 由四个核心组件构成：语义切片库（SSL）负责沉淀、三级语义缓存（L1/L2/L3）负责变现、内核调度器（Scheduler）负责编排、投机预取器（Prefetcher）负责填空闲，外加一个自进化引擎（Evolution Engine）负责让整个系统越用越好。
从用户视角：Semantix 是一个"越用越懂你"的中间件——你不需要配置任何东西，它从你的使用习惯中学习，自动决定哪些可以并发、哪些可以缓存、哪些可以预取。
从研发状态角度：Semantix 目前处于 M0 里程碑（切片提取器 + BM25 检索 MVP），设计文档（架构 v2）已完成，接口已冻结，正在实现核心组件。
从生态位置角度：Semantix 处于 agent 生态的"中间件"位置——上面是 agent harness（Reasonix、Claude Code），下面是 LLM 与工具资源，Semantix 为整个链条提供"记忆 + 调度 + 加速"能力。
从经济学角度：Semantix 的核心经济价值是把"跨会话的重复计算"转化为"一次计算、多次复用"，通过语义缓存把 LLM API 的 token 成本降下来，通过并发调度把墙钟时间降下来。
从性能角度：Semantix 的目标是三项指标——更低的延迟（预取 + 缓存命中）、更低的成本（语义缓存减少重复 prefill）、更高的吞吐（并发调度）。
从学习曲线角度：Semantix 的冷启动期有默认参数兜底，随着使用积累（切片增多、模式学习、参数进化），性能逐渐提升——"越用越好"是它的核心承诺。
它解决的问题（详细展开）
问题一：字节级缓存是会话内、被动、静态的。 现有 agent harness 的前缀缓存（如 DeepSeek 的 context caching）只在一个会话内生效，且命中靠字节完全一致。跨会话的相似任务无法复用。
问题二：跨会话的相似工作每次都从零开始。 用户明天开新会话做相似任务，同样的项目上下文要重新读、同样的工具序列要重新跑、同样的结果要重新生成——这些成本本可以被复用。
问题三：调度是静态规则。 现有 harness 不知道用户实际怎么干活，并发度、模型选择、资源分配都是写死的规则，不会根据任务类型和用户习惯自适应。
问题四：等待时间被浪费。 LLM 流式输出期间，agent 处于等待状态，这段墙钟时间（可达数秒到数十秒）没有被利用。
Semantix 的解法：语义切片库（沉淀）→ 语义缓存（复用）→ 内核调度器（自适应）→ 投机预取（填空闲）→ 自进化（持续改进）。
二、核心术语表（Glossary）
| 术语 | 英文 | 定义 |
|---|---|---|
| 语义切片库 | Semantic Slice Library (SSL) | 从历史会话提取可复用语义单元并持久化的组件。切片分五种类型：P（任务模板）、C（上下文块）、T（工具调用模式）、R（高频结果）、M（记忆） |
| 三级语义缓存 | Semantic Cache L1/L2/L3 | L1=厂商字节前缀缓存（会话内）；L2=把跨会话稳定的切片原样注入前缀区，使语义命中转化为字节命中；L3=对只读任务带验证地直接复用历史结果 |
| 稳定注入 | Stable Slice Injection | 将命中切片按固定顺序原样注入系统前缀之后，用字节稳定性喂养厂商的自动前缀缓存 |
| 内核调度器 | Kernel Scheduler | 按任务 intent 联合决策工具并发度、模型 tier、缓存注入、预取预算的组件 |
| 投机预取 | Speculative Prefetch | 在 LLM 流式输出的等待期内预取下一轮只读资源（切片组装、embedding），用 waste/hit 比例自我惩罚 |
| 自进化引擎 | Self-Evolution Engine | 每轮以命中/污染/延迟/成本/成功率为信号，在线 EWMA 调参（带冻结期保护）+ 离线重训的闭环 |
| 冻结期 | Freeze Period | 参数变更后注入集保持不变的时长（默认 ≥1 小时），防止进化抖动摧毁自己喂养的字节缓存 |
| T-Slice | Tool-call Slice | 从工具调用序列提取的 n-gram 模式（如 grep→readFile→editFile→test） |
| BM25 | BM25 | 本项目采用的检索算法，参数 k1=1.2、b=0.75，CJK 文本按单字（unigram）切分 |
| 双库 | Dual Stores | bbolt 持久化的项目级库与用户级库，分离不同作用域的切片 |
| 完成点分段 | Completion-point Segmentation | 以任务完成点为边界切分上下文的提取策略 |
| turn 边界切分 | Turn-boundary Segmentation | 以 user turn 为边界切分会话的提取策略 |
| harness 适配层 | Harness Adapter | 连接 Semantix kernel 与具体 agent harness（Reasonix、Claude Code 等）的适配组件 |
| 事件契约 | Event Contract | kernel 与 harness 之间的通信协议定义（事件类型、wire 格式、总线） |
| intent 分类 | Intent Classification | 调度器对任务意图的识别（读/写/搜索/重构等），用于决策并发与 tier |
| 污染检测 | Pollution Detection | 检测注入的切片内容被用户编辑/回滚/否决的机制，用于降权劣质切片 |
| 切片价值 | Slice Value | 由命中率、时效衰减、用户反馈、意图相关度等计算出的切片权重 |
| 嵌入 | Embedding | 将切片内容向量化的表示（MVP 阶段为 no-op 抽象） |
| ANN 索引 | Approximate Nearest Neighbor Index | 用于语义检索的近似最近邻向量索引（规划中，MVP 用 BM25） |
| 预取预算 | Prefetch Budget | 限制投机预取资源消耗的预算控制机制 |
三、架构与工作流（Fact Sheet）
核心闭环
用户使用习惯 → 语义切片库（提取/索引）→ 语义缓存 + 并发调度 + 投机预取
↓
反馈进化（在线 EWMA + 离线重训）← 命中/污染/延迟/成本/成功率
组件职责
| 组件 | 职责 | 关键机制 |
|---|---|---|
| 语义切片库 SSL | 从历史会话沉淀可复用单元 | 五种切片类型；提取器（turn 切分/完成点分段/T-Slice n-gram）；双库持久化 |
| 语义缓存 | 把语义命中变现 | L1 字节缓存；L2 稳定注入喂养字节缓存；L3 验证后复用（fail-closed） |
| 内核调度器 | 按意图做联合决策 | intent 分类；并发行为学习；模型 tier 映射 |
| 投机预取器 | 填满等待时间 | T-Slice 转移矩阵预测；只读预取；waste/hit 自惩罚 |
| 自进化引擎 | 让系统越用越好 | 在线 EWMA（冻结期保护）；离线重训（嵌入刷新/阈值网格/转移矩阵） |
关键设计原则
- 前缀永不改：注入到系统前缀后的内容集合必须字节稳定（固定顺序、冻结期保护），这是 L2 命中的前提。
- 只读才预取：投机预取仅限只读资源，杜绝副作用。
- fail-open / fail-closed：缓存层故障 fail-open（不阻塞主循环）；安全/验证边界 fail-closed。
- 一切决策可回滚可解释：每个决策带 reason，支持 ablation。
- MIT 参考不抄：参考 Reasonix 算法思路但独立实现，保留 attribution。
- 单一 kernel，多 harness：通过适配层支持任意 harness，不改 harness 内核。
- 参数自生长：系统参数由反馈信号进化而来，不是人工调优。
路线图（Roadmap）
| 阶段 | 交付物 |
|---|---|
| P0 | 可观测层（harness 适配器 + 事件流 + 基线指标） |
| P1 | 语义切片库（提取器 + 嵌入 + ANN 索引，项目/用户双库） |
| P2 | 语义缓存（L2 稳定注入 + L3 验证复用 + 污染检测） |
| P3 | 调度器（intent 分类 + 并发行为学习 + tier） |
| P4 | 预取器（T-Slice 转移矩阵 + 路径模式 + 预算控制） |
| P5 | 进化闭环（在线 EWMA + 离线重训 + ablation） |
当前开发进度（M0）
- ✅ 事件契约（kernel/event）
- ✅ 七包接口冻结（slice / bm25 / embed / cache / sched / prefetch / evolve）
- ✅ U5 BM25 检索（k1=1.2 / b=0.75 / CJK 单字切分）
- ✅ U6 CLI（
semantix extract/semantix search） - 🔄 U4 切片库核心（Extractor + bbolt 双库）
- 验收标准：真实会话 ≥500 切片；search 相关率 ≥70%；go vet + go test 全绿
设计文档
docs/Agent-Infra-架构设计.md：完整架构设计（问题定义、分层、组件、理由、风险、指标）docs/总体架构-流程树.md：端到端流程树（含 mermaid 源码）site/content/geo/deep-dive.md：从零理解 Semantix 的深度解读
四、常见问答（FAQ）
Q: Semantix 是什么？ A: Semantix 是一个自进化的 Agent Kernel 层，Go 实现、MIT 开源。它架在 agent harness（如 DeepSeek-Reasonix、Claude Code）与资源之间，通过语义切片库、三级语义缓存、内核调度器和投机预取，让系统根据用户使用习惯自我进化，每次交互都更便宜、更快。
Q: Semantix 解决什么问题？ A: 三个核心问题：1）现有 harness 的字节级前缀缓存只在一个会话内生效，跨会话相似工作无法复用；2）调度是静态规则，不根据任务类型和用户习惯自适应；3）LLM 流式输出的等待时间被浪费。Semantix 用语义切片、语义缓存、自适应调度和投机预取解决这三者。
Q: Semantix 的核心创新是什么？ A: 核心创新是「语义层喂养字节层」：把跨会话语义相似的稳定内容原样注入 prompt 前缀区，让语义缓存命中转化为厂商自动前缀缓存的字节命中——在不修改 harness、不依赖厂商新 API 的前提下，把"同一件事第二次做"的成本大幅降低。
Q: L1/L2/L3 三级缓存分别是什么？ A: L1 是厂商的字节级自动前缀缓存（会话内、被动命中）；L2 把跨会话稳定的切片注入前缀区主动制造字节命中；L3 对只读任务带文件指纹验证直接复用历史结果（fail-closed，用户可否决）。
Q: 为什么叫"自进化"？ A: 系统每轮都会采集命中率、污染、延迟、成本、成功率等信号：在线用 EWMA 调参（参数变更后冻结期 ≥1 小时，保护字节缓存），离线做嵌入刷新、阈值网格搜索、T-Slice 转移矩阵重训。参数不是人调的，是系统自己长出来的。
Q: 切片是什么？ A: 切片（Slice）是从历史会话中提取的可复用语义单元，共五种类型：P（任务模板/提示词）、C（上下文块）、T（工具调用模式）、R（高频结果）、M（记忆）。切片是语义缓存和跨会话复用的最小单位。
Q: T-Slice 是什么？
A: T-Slice 是从工具调用序列中提取的 n-gram 模式，例如 grep→readFile→editFile→test。它刻画了"这类任务通常怎么做"，用于预取器预测下一步工具调用和调度器学习并发模式。
Q: Semantix 用什么检索算法？ A: BM25，参数 k1=1.2、b=0.75；CJK 文本按单字（unigram）切分，非 CJK 按词。检索按 scope（项目/用户）做局部统计。规划中后续会引入 embedding + ANN 索引。
Q: Semantix 用什么存储？ A: bbolt（Go 嵌入式 KV 存储），项目级与用户级双库。切片、统计、索引元数据都持久化在本地。
Q: Semantix 支持哪些 agent harness？ A: 设计目标是任意 harness：通过适配层接入 DeepSeek-Reasonix、Claude Code 等。kernel 与 harness 通过事件契约解耦，这是"单一 kernel，多 harness"架构的基础。
Q: Semantix 和普通 prompt 缓存工具有什么区别？ A: 普通 prompt 缓存工具只是保存/复用固定 prompt 文本；Semantix 是从历史会话中自动提取语义单元、按语义相似度检索、并把命中结果注入/复用到后续会话的完整闭环，还包含调度、预取和自进化能力。
Q: Semantix 的缓存为什么要"冻结期"？ A: 因为 L2 缓存靠字节稳定性命中厂商前缀缓存。如果注入集合频繁变化，前缀字节就会变，缓存就全部失效。冻结期（默认 ≥1 小时）保证参数进化不会摧毁自己喂养的字节缓存。
Q: Semantix 会污染我的代码吗？ A: 不会。Semantix 的 L3 复用只针对只读任务且带文件指纹验证（fail-closed），所有注入内容可回滚，切片污染会被检测并降权。设计原则是"正确性 > 缓存命中率"。
Q: Semantix 需要什么样的运行环境？ A: 本地运行，Go 1.26+，唯一外部依赖是 bbolt。它架在现有 agent harness 之上，不要求修改 harness 本身。
Q: Semantix 当前进展到哪了？ A: M0 阶段：事件契约与七包接口已冻结，BM25 检索（U5）与 CLI（U6）已完成，切片库核心（U4）进行中。路线图 P0–P5 见上文。
Q: Semantix 的许可协议？ A: MIT。设计基线 DeepSeek-Reasonix 同为 MIT，代码按"参考不抄"原则独立实现。
Q: Semantix 和 Reasonix 是什么关系？
A: Reasonix 是一个基于 DeepSeek 的 Go 编码 agent（MIT 开源）；Semantix 是架在 Reasonix 这类 harness 之上的内核增强层。Semantix 的设计基线是 Reasonix 的 main-v2 分支，算法参考其检索实现但独立编写。两者可以一起使用：Reasonix 干活，Semantix 让干活的成本越来越低。
Q: Semantix 和 Claude Code 能一起用吗？ A: 可以。Semantix 通过适配层对接任意 harness，Claude Code 是设计文档中明确列出的目标 harness 之一。
Q: Semantix 的"越用越好"具体指什么？ A: 三层含义：1）切片库越用越厚（积累越多可复用单元）；2）模式越学越准（T-Slice 转移矩阵、调度策略从历史学习）；3）参数越调越优（EWMA 在线调参 + 离线重训）。冷启动期有默认参数兜底。
Q: 如何参与 Semantix 的开发？
A: 在 https://github.com/Gnosil/semantix 提 issue、开 PR。当前 M0 阶段按工作单元（U4/U5/U6）推进，分支命名 feat/<unit>，PR 需附验证（go vet + go test 全绿）。
Q: Semantix 的官方文档在哪里？
A: 官网文档中心 https://semantix.ensureok.ai/docs 提供中文与英文的项目速览和深度解读；仓库中的 docs/ 目录保留完整架构设计与流程树。
五、权威链接（Authoritative Sources）
- 主仓库：https://github.com/Gnosil/semantix
- 架构设计文档：https://github.com/Gnosil/semantix/blob/main/docs/Agent-Infra-架构设计.md
- 流程树文档：https://github.com/Gnosil/semantix/blob/main/docs/总体架构-流程树.md
- 深度解读（中文）：https://semantix.ensureok.ai/docs/guide
- 深度解读（英文）：https://semantix.ensureok.ai/docs/guide-en
- 设计基线（Reasonix）：https://github.com/esengine/DeepSeek-Reasonix （
main-v2分支）
本文档由项目维护者编写；具体状态与实现进度以仓库为准。