llms-full.txt@site/public git:20260907.7b873dbB

Immutable. This exact content is served forever at /api/v1/blob/a8a2303fe5cbd48b.

# Semantix — Full Site Text for AI Assistants

> This file aggregates the full text of the official Semantix documentation for AI assistants, complementing the link index at /llms.txt. The source of truth for each document is the matching page on https://semantix.ensureok.ai/docs/.

## Documentation

- [Semantix website](https://semantix.ensureok.ai/): Official homepage — positioning, features, components, roadmap, and install instructions.
- [Semantix repository](https://github.com/Gnosil/semantix): Source code, tests, design documents, and issue tracker.
- [Benchmarks and evidence](https://semantix.ensureok.ai/benchmarks): Reproducible commands, repository test boundaries, and the labeled retrieval fixture.
- [Evidence methodology](https://semantix.ensureok.ai/evidence/methodology): E0–E3 labels explaining what each result does and does not establish.

## Full text

---

> Source: https://semantix.ensureok.ai/docs/quickstart

# 安装与首次运行

这条路径用于验证最小闭环：**历史会话 → 语义切片 → 检索 → 注入**。先在测试目录运行，再决定是否接入真实 agent。

## 选择安装方式

### 下载完整产品

GitHub Release 的完整包包含 coding agent 与 Semantix 内核。将 `<version>` 和 `<platform>` 替换为 Release 页面中的实际文件名：

```bash
tar -xzf semantix-agent-<version>-<platform>.tar.gz
cd semantix-agent-<version>-<platform>
./semantix-install.sh
```

Windows 用户可下载对应的 `windows-amd64` 或 `windows-arm64` 包，并把可执行文件所在目录加入 `PATH`。

### 从源码构建内核

仓库声明需要 Go 1.26 或更高版本：

```bash
git clone https://github.com/Gnosil/semantix.git
cd semantix
go build -o semantix ./cmd/semantix
```

Windows PowerShell 使用带扩展名的输出文件：

```powershell
go build -o semantix.exe ./cmd/semantix
```

先确认命令可以启动：

```bash
semantix version
semantix help
```

## 准备一段会话

`extract` 接收 JSONL；每行至少包含一条会话消息。下面是最小示例：

```json
{"role":"user","content":"修复 Go 测试失败"}
{"role":"assistant","content":"先定位失败包，再运行聚焦测试。"}
```

保存为 `session.jsonl`，然后运行：

```bash
semantix extract --input session.jsonl --db .semantix/project.db --project demo
semantix search --query "修复 Go 测试失败" --db .semantix/project.db
semantix inject --query "修复 Go 测试失败" --db .semantix/project.db
```

成功标准不是“命令没有报错”这么简单：`search` 应返回来源切片，`inject` 应只在存在合格候选时输出 `[semantix-reuse]` 块。

## 下一步

- 需要接入现有 coding agent：阅读《接入 Coding Agent》。
- 需要稳定保存项目设置：阅读《配置与作用域》。
- 需要判断真实命中率：阅读《验证、用量与健康检查》。

## 对应仓库来源

- `README.zh-CN.md` 的“快速上手”
- `docs/QUICKSTART.md`
- `cmd/semantix/extract.go`、`search.go`、`lookup.go`

---

> Source: https://semantix.ensureok.ai/docs/agent-integration

# 接入 Coding Agent

Semantix 的内核不要求 agent 更换执行循环。最小接入面只有三件事：任务开始前检索、需要时注入、会话结束后提取。

## 先选择集成层级

| 场景 | 推荐路径 | 改动范围 |
|---|---|---|
| Semantix 完整产品 | 使用内置 Semantix Agent 集成 | 无需重复注册工具 |
| Claude Code | 安装 agent skill | 用户级 skill 目录 |
| 支持 function calling 的 agent | 注册 `semantix_lookup`，按需注册 inject/extract | 工具层 |
| 自定义 harness | 会话导出、事件旁路或直接调用 | 适配层 |

## Claude Code

```bash
semantix install --target claude-code
```

安装目标默认是 `~/.claude/skills/semantix/`。安装完成后重启 Claude Code，并用 `semantix lookup --help` 验证二进制仍可从 `PATH` 找到。

## Semantix Agent

仓库中的 Semantix Agent harness 已内置 Semantix 接口。配置中启用对应段落后，harness 会暴露 lookup 能力并把会话事件旁路给内核。不要在同一轮再手工注入第二份相同内容。

## 自定义 harness 的生命周期

### 任务开始

```bash
semantix lookup --query "<当前任务>" --scope user --json
```

只有命中内容确实与当前任务相符时才使用。`grey` 表示需要进一步验证，不是自动执行许可。

### 构造上下文

```bash
semantix inject --query "<当前任务>" --scope user
```

注入块是低权限历史材料。agent 仍需遵守当前用户请求、仓库规则和权限边界。

### 会话结束

```bash
semantix extract --input <session.jsonl> --scope user --project <业务域>
```

如果 harness 的会话格式不同，先在适配层转成仓库约定的 JSONL，不要让内核直接猜测私有格式。

## 验收

仓库提供自测脚本，覆盖提取、lookup 命中和注入块：

```bash
bash agent-skill/scripts/selftest.sh
```

通过标准为脚本输出 `SELFTEST PASS`。这只证明最小接线成立，不代表你的真实会话命中率已经达标。

## 对应仓库来源

- `agent-skill/SKILL.md`
- `agent-skill/tools/semantix-lookup.md`
- `agent-skill/hooks/session-bypass.md`
- `harness/semantix/`

---

> Source: https://semantix.ensureok.ai/docs/configuration

# 配置与作用域

Semantix 可以零配置运行；当路径、检索方式或成本参数需要在团队内稳定复现时，再创建 `semantix.toml`。

## 从示例开始

```bash
cp semantix.example.toml semantix.toml
```

最常用的配置如下：

```toml
[project]
name = "my-project"

[store]
db = ".semantix/project.db"
scope = "project"
max_slices = 5000

[retrieval]
retriever = "hybrid"
limit = 5

[inject]
budget = 4096
top_k = 5
```

## 优先级

运行时按“内置默认值 → 配置文件 → 环境变量 → CLI flag”逐层覆盖。临时实验用 CLI flag；团队默认值放 TOML；凭据只放环境变量。

配置文件不存在时命令继续使用默认值。配置文件存在但语法或字段类型非法时，CLI 返回用法错误，避免静默采用错误参数。

## 三种作用域

| 作用域 | 适合存放 | 注意事项 |
|---|---|---|
| `session` | 单次会话临时信息 | 不应期待跨会话命中 |
| `project` | 仓库架构、命令、局部工作流 | 默认选择，避免跨项目污染 |
| `user` | 跨项目偏好与稳定流程 | 写入前应先做敏感信息治理 |

提取和检索必须使用相容作用域。最常见的“查不到”原因，是写入时使用 `project`，读取时却使用 `user`。

## 哪些字段会改变数据兼容性

- `store.db` 决定切片库文件。
- `retrieval.vector_dim` 会改变 hash embedding 维度；已有向量与新维度不一致时需要重新提取。
- `store.max_slices` 会在维护流程中触发上限淘汰与归档。
- `cost.*` 只影响估算，不会改变模型供应商的实际账单。

## 凭据边界

Judge、上游模型或网关密钥只使用环境变量。不要把真实 key 放入 TOML、命令行历史、会话 JSONL 或 Git。

## 对应仓库来源

- `semantix.example.toml`
- `kernel/config/config.go`
- `cmd/semantix/cfgload.go`
- `cmd/semantix/config_wiring_test.go`

---

> Source: https://semantix.ensureok.ai/docs/extract-search

# 提取与检索

`extract` 负责把会话转换成可复用切片，`search` 负责按当前查询排序这些切片。两者共享同一切片库，但承担不同责任。

## 输入格式

会话文件是 JSONL：一行一个 JSON 对象。典型字段包括 `role`、`content` 和 `tool_calls`。先用少量脱敏会话验证格式，再批量导入。

```bash
semantix extract \
  --input session.jsonl \
  --db .semantix/project.db \
  --scope project \
  --project demo
```

提取器会按会话内容生成不同类型的语义切片。它不是把整份 transcript 原样塞进数据库；上下文提取和压缩均有独立测试约束。

## 三种检索模式

```bash
semantix search --query "失败测试的修复步骤" --retriever bm25
semantix search --query "失败测试的修复步骤" --retriever vector
semantix search --query "失败测试的修复步骤" --retriever hybrid --fusion rrf
```

- `bm25`：依赖词面匹配，容易解释，适合命令、文件名和错误文本。
- `vector`：使用 embedding 相似度，适合同义改写。
- `hybrid`：组合两路结果；支持 weighted 或 RRF 融合。

默认值以当前配置和 `semantix search --help` 为准，不要只依赖旧文章里的参数截图。

## 读取结果

结果除了分数，还会带来源和 zone。zone 用于表达“当前证据有多强”，不是内容权限：

- `hit`：检索证据较强，仍需检查任务上下文。
- `grey`：存在相关性，但应验证后再用。
- `miss`：不应注入或复用。

自动化集成建议使用 `--json`，避免解析面向人的颜色和排版输出。

## 排查无结果

1. 确认 extract 与 search 指向同一个 `--db`。
2. 确认作用域一致。
3. 用会话中的原始术语先测 BM25。
4. 用 `doctor` 检查数据库和配置。
5. 不要为了制造 hit 盲目降低阈值；先检查输入质量。

## 对应仓库来源

- `kernel/ingest/`、`kernel/slice/`
- `kernel/bm25/`、`kernel/embed/`、`kernel/fuse/`
- `cmd/semantix/extract.go`、`search.go`

---

> Source: https://semantix.ensureok.ai/docs/lookup-inject

# Lookup 与上下文注入

`lookup` 和 `inject` 使用同一检索基础，但输出契约不同。前者供程序判断，后者供 prompt 组装。

## 什么时候使用 lookup

```bash
semantix lookup --query "如何处理这个迁移" --scope project --json
```

`lookup` 返回结构化候选、分数、zone 与来源，适合注册成 agent tool。调用方可以决定是否继续读取证据、是否请用户确认，或是否完全忽略命中。

不要把 lookup 命中直接当作工具执行指令。历史切片属于低权限数据，不能覆盖当前用户请求或仓库规则。

## 什么时候使用 inject

```bash
semantix inject \
  --query "如何处理这个迁移" \
  --scope project \
  --budget 4096 \
  --k 5
```

`inject` 在预算内选择完整切片，并输出有明确边界的 `[semantix-reuse]` 块。选择完整切片而不是任意截断，有助于避免把条件和结论拆开。

## 预算与 top-k

- `--k` 控制最多考察多少个候选。
- `--budget` 控制最终注入块的字节预算。
- 候选多并不代表上下文更好；噪声会挤占当前任务所需的 token。

## 推荐接线

1. 用 lookup 获取候选与 zone。
2. hit 候选仍要进行任务相关性检查。
3. 需要把内容交给模型时再调用 inject。
4. 把注入块放在明确的历史材料区域，不与宿主 system prompt 混为一体。
5. 记录最终是否采用，为后续反馈和验证提供依据。

## 对应仓库来源

- `kernel/lookup/lookup.go`
- `kernel/inject/`
- `agent-skill/tools/semantix-lookup.md`
- `harness/tool/semantix.go`

---

> Source: https://semantix.ensureok.ai/docs/verify-observe

# 验证、用量与健康检查

Semantix 把“能运行”“能命中”“值得复用”分成不同检查。不要用单次成功搜索代替完整验收。

## verify：离线回放

```bash
semantix verify --session ./sessions --project demo --scope project
```

`verify` 把部分会话作为历史库，按时间回放剩余会话，并报告命中和 zone 分布。需要把门禁用于 CI 时，再启用 `--strict`。

```bash
semantix verify --session ./sessions --strict --calibrate
```

`--calibrate` 输出分桶分布；提供人工标签后才能进一步估计 precision。没有标签时，不应把相似度分数解释成正确率。

## usage：估算成本

```bash
semantix usage --db .semantix/usage.jsonl
```

usage 根据日志中的 token/cache 事件和配置价目计算基线、实际成本与估算节省。价目是输入参数；报告不会自动核对供应商账单。

## dashboard：一屏状态

```bash
semantix dashboard
```

dashboard 汇总切片库和用量日志，适合人工快速检查，不应作为机器稳定接口。自动化请使用各命令的 `--json` 输出。

## doctor：运行前诊断

```bash
semantix doctor
semantix doctor --json
```

doctor 检查配置、切片库以及已配置的外部能力。某些网络检查只有在配置端点后才执行；未配置不等于远端已通过。

## 一套可执行验收顺序

1. `doctor` 无关键失败。
2. 最小 extract/search/inject 闭环成立。
3. `verify` 使用真实、脱敏的多会话数据。
4. 人工抽查 hit 与 grey 候选。
5. 对照供应商账单核验 usage 估算。

## 对应仓库来源

- `cmd/semantix/verify.go`、`usage.go`、`dashboard.go`、`doctor.go`
- `docs/reports/verify-rubric.md`
- `docs/reports/m0-gate.md`

---

> Source: https://semantix.ensureok.ai/docs/cli-reference

# CLI 命令索引

运行 `semantix help` 查看当前版本命令树，运行 `semantix <command> --help` 查看完整 flags。下面按任务分类，不复制容易过期的全量参数表。

## 建库与复用

| 命令 | 主要用途 |
|---|---|
| `extract` | 从会话 JSONL 生成切片并写入库 |
| `search` | 使用 BM25、向量或混合策略检索 |
| `lookup` | 为 agent tool 返回结构化候选 |
| `inject` | 在预算内生成 L2 复用块 |

## 评估与观测

| 命令 | 主要用途 |
|---|---|
| `verify` | 按时间回放会话并评估命中 |
| `eval` | 比较检索阈值策略 |
| `eval-judge` | 在人工 oracle 样本上评估 judge |
| `calibrate` | 汇总 judge 与运行时负向信号 |
| `usage` | 汇总 token、cache 和估算成本 |
| `dashboard` | 输出面向人的状态面板 |

## 安装与维护

| 命令 | 主要用途 |
|---|---|
| `install` | 安装或卸载 agent skill |
| `doctor` | 检查本地配置与依赖状态 |
| `gc` | 重算价值并归档超限切片 |
| `version` | 输出构建版本 |

## JSON 输出契约

支持 `--json` 的命令使用统一信封：

```json
{"ok":true,"command":"search","data":{},"error":null,"version":"..."}
```

自动化应检查 `ok` 和进程退出码，不应只判断 stdout 是否非空。

## 退出码

| 退出码 | 含义 |
|---|---|
| `0` | 成功 |
| `1` | 运行错误，例如 IO 或检索失败 |
| `2` | 用法错误，例如未知 flag 或非法配置 |
| `3` | 门禁未达标，例如 strict 验证失败 |

## 对应仓库来源

- `cmd/semantix/main.go`
- `cmd/semantix/contract.go`
- `cmd/semantix/envelope.go`
- `docs/reports/cli-v2-architecture.md`

---

> Source: https://semantix.ensureok.ai/docs/slices-and-cache

# 语义切片与三级缓存

Semantix 的核心不是“把整段聊天永久塞回 prompt”，而是把可复用经验拆成带来源、作用域和生命周期的切片，再在不同层级复用。

## 语义切片

切片是可独立检索的最小经验单元。仓库实现包含切片类型、作用域、元数据、文件存储、追加日志、压缩和维护。类型化切片让淘汰策略能够区分短期结果与长期上下文。

## L1：供应商前缀缓存

L1 发生在模型供应商或兼容网关层：当前缀字节稳定时，供应商可能复用 prompt 计算。Semantix 可以通过稳定化和观测帮助提高命中，但最终计费与有效期由上游决定。

## L2：语义切片注入

L2 根据当前任务检索历史切片，把合格内容注入上下文。它复用的是**经验文本**，模型仍会继续推理和执行工具。

这层适合复用：仓库约定、已验证命令、用户偏好和任务流程。它不适合直接复用可能已经过期的最终结果。

## L3：已验证结果复用

L3 尝试跳过部分重复执行，因此风险最高。仓库将候选交给依赖指纹、规则门和可选 judge；无法证明安全时回退正常执行。

“检索到了相似内容”只够支持 L2 候选，不足以单独批准 L3。

## 三层关系

| 层级 | 复用对象 | 仍然执行模型/工具 | 主要风险 |
|---|---|---|---|
| L1 | 稳定 prompt 前缀 | 是 | 上游缓存规则与字节漂移 |
| L2 | 历史语义切片 | 是 | 注入噪声或过时背景 |
| L3 | 已验证执行结果 | 可能跳过 | 项目状态变化导致错误复用 |

## 对应仓库来源

- `kernel/slice/`
- `kernel/inject/`
- `kernel/cache/`、`kernel/fingerprint/`、`kernel/judge/`、`kernel/promote/`
- `docs/reports/cache-taxonomy.md`

---

> Source: https://semantix.ensureok.ai/docs/retrieval-safety

# 检索、分区与复用安全

相关性回答“像不像”，安全复用回答“在当前状态下能不能直接用”。Semantix 把这两个判断分开。

## 混合检索

BM25 擅长精确术语，向量检索擅长语义改写。混合检索通过 weighted 或 RRF 融合两路排名，以减少单一路径的盲区。

融合后仍只是候选排序。高分不证明文件状态、依赖版本或用户意图没有改变。

## 三分区

`kernel/zone` 把候选分为 hit、grey、miss：

- hit：相对和绝对证据都达到较高门槛。
- grey：存在相关性，但证据不足以自动复用。
- miss：不进入复用路径。

三分区的价值是把不确定性显式保留下来，而不是强迫每个候选得到 yes/no。

## L3 的附加门

1. 依赖指纹检查文件状态是否仍一致。
2. 规则门拒绝明显不安全候选。
3. 配置了 judge 时，只对需要判断的候选请求模型。
4. 批准后的结果才进入 promote 流程。

## Fail-open 的含义

Semantix 的 fail-open 是“优化层失败时恢复正常执行”，不是“安全检查失败时仍使用缓存”。读取失败、候选不确定或 judge 不可用时，coding agent 应继续原任务，只是失去这次加速。

## 调参原则

降低阈值通常会提高表面命中率，也可能提高错误复用。应在带人工相关性标签的数据上校准，再观察 false positive、grey traffic 和最终任务结果。

## 对应仓库来源

- `kernel/fuse/`、`kernel/zone/`
- `kernel/fingerprint/`、`kernel/judge/`、`kernel/promote/`
- `docs/specs/issue-261-l3-freshness.md`
- `docs/specs/issue-262-l3-negative-observability.md`

---

> Source: https://semantix.ensureok.ai/docs/scheduling-evolution

# 调度、预取与参数演化

Semantix 不只保存记忆，还包含调度、预取和参数演化模块。这些模块当前有仓库级测试与演示，但不应被描述成已经证明适用于所有生产 workload。

## 调度器

调度器为每轮生成 round plan，包括可并行分组、预算动作、模型层级提示、注入 ID 和预取提示。它表达计划，不替代宿主 harness 的权限和工具执行逻辑。

## 保守预取

预取器根据历史工具转移模式预测后续可能读取的资源。runner 只执行允许的只读动作；系统负载过高、证据不足或预测进入退化状态时，应停止预取。

预取的收益是降低等待时间，成本是浪费 IO、token 或缓存空间。因此命中和浪费必须成对记录。

## 参数演化

演化模块使用反馈更新检索阈值和注入预算。更新有边界、可检查，并使用 EWMA 降低单次异常的影响。

“自我演化”在这里指**少量受约束参数的反馈更新**，不等于 agent 自动改写全部代码或无限扩张权限。

## 安全不变量

- 变化必须有上下界。
- 负反馈不能被只记录不消费。
- 长期只有单一状态时需要逃逸机制，避免吸收态。
- 恢复后仍要保留可审计的参数与事件。
- 优化失败不能阻塞宿主正常完成任务。

## 如何验证

仓库提供调度 demo、演化曲线和对应数据文件。它们适合验证实现与因果开关，不等于独立用户的生产收益证明。

## 对应仓库来源

- `kernel/sched/`、`kernel/prefetch/`、`kernel/evolve/`
- `docs/specs/evolution-invariants.md`
- `docs/reports/agile2-scheduling-demo.md`
- `docs/reports/agile2-evolution-curve.md`

---

> Source: https://semantix.ensureok.ai/docs/gateway

# 部署 OpenAI 兼容 Gateway

Semantix Gateway 位于支持 OpenAI 兼容请求的客户端与上游模型之间，负责请求净化、检索/注入、L3 判定、SSE 转发和用量记录。

## 适用条件

- 客户端允许设置自定义 base URL。
- 你能够安全管理网关密钥和上游模型密钥。
- 你接受“优化失败时继续请求上游”的 fail-open 行为。

## Docker Compose 起步

```bash
cp deploy/semantix-gateway.toml.example deploy/semantix-gateway.toml
export SEMANTIX_GATEWAY_KEY="<gateway-key>"
export DEEPSEEK_API_KEY="<upstream-key>"
docker compose -f deploy/docker-compose.yml up -d --build
```

不要把示例占位符替换成真实密钥后提交到 Git。配置中的 `${VAR}` 在启动时从环境变量展开，缺失凭据会使启动失败。

## 健康检查

```bash
docker compose -f deploy/docker-compose.yml ps
curl http://127.0.0.1:3000/
```

具体端口和拓扑以 compose 文件为准。New API 管理面板与内部 Gateway 是两个组件，不要把面板端口误当成 Gateway 监听地址。

## 判断缓存命中

- 非流式响应：检查 `x-semantix-cache: hit | miss`。
- 流式响应：中间代理可能剥离自定义响应头，以 Gateway usage 日志为准。

```bash
tail -n 5 .semantix/gateway-usage.jsonl
semantix usage --db .semantix/gateway-usage.jsonl
```

## 当前边界

示例配置明确标注了尚未接线或需要额外配置的能力。例如 Gateway retrieval 段当前以实际实现注释为准，不应因为 CLI 支持 hybrid 就推断 Gateway 中同样全部生效。

## 对应仓库来源

- `gateway/`
- `cmd/semantix-gateway/`
- `deploy/docker-compose.yml`
- `deploy/semantix-gateway.toml.example`
- `docs/specs/newapi-gateway-design.md`

---

> Source: https://semantix.ensureok.ai/docs/storage-maintenance

# 存储、维护与安全

Semantix 的切片库是本地文件资产。运维目标是可备份、可审计、可回滚，而不是让缓存无限增长。

## 备份

默认项目库位于 `.semantix/project.db`。在写入停止后复制主文件；如果存在归档文件，也一起保留。

```bash
cp .semantix/project.db .semantix/project.db.backup
cp .semantix/project.db.archive.jsonl .semantix/project.db.archive.jsonl.backup
```

Windows PowerShell 可使用 `Copy-Item`。恢复前先备份当前版本，不要用未经检查的旧库覆盖唯一副本。

## GC 与归档

```bash
semantix gc --db .semantix/project.db
```

GC 会重算价值并按类型、时效与配置上限选择淘汰项。超限切片归档到 `<db>.archive.jsonl`；归档不是删除证明，也不等于敏感数据已经清除。

## 数据权限

实现会为本地库使用受限权限并防御符号链接替换，但运维仍需保证：

- 数据目录只对需要的系统用户开放。
- 会话导入前完成凭据和个人信息脱敏。
- 备份介质使用同等级访问控制。
- 不把 `.semantix/` 提交到版本库。

## 注入安全

历史切片是数据，不是高优先级指令。宿主 agent 应把注入块与 system prompt 分隔，并继续执行当前权限检查。

## 维护前检查

1. 记录当前库路径和文件大小。
2. 创建可恢复备份。
3. 使用 `dashboard` 或 `--json` 记录 GC 前状态。
4. 运行 GC。
5. 聚焦验证常用查询仍能命中。

## 对应仓库来源

- `kernel/slice/file_store.go`
- `kernel/slice/maintenance.go`
- `kernel/slice/score.go`
- `docs/specs/slice-store-append-journal.md`
- `SECURITY.md`

---

> Source: https://semantix.ensureok.ai/docs/evidence-and-status

# 实现状态与证据边界

仓库同时包含设计、实现、测试、合成回放和产品路线。阅读结论前，先判断它属于哪一级证据。

## 四类常见材料

| 材料 | 能证明什么 | 不能直接证明什么 |
|---|---|---|
| 设计/spec | 预期接口、边界和验收标准 | 功能已经交付 |
| 单元/集成测试 | 指定输入下实现符合断言 | 真实用户长期收益 |
| 仓库 demo / 合成回放 | 流程可复现、对照条件下的结果 | 跨团队、跨模型泛化 |
| 真实生产数据 | 特定环境中的实际效果 | 对所有环境都有效 |

## 当前应如何表述 Semantix

- 切片、检索、注入、L3 判定、调度、预取、演化、CLI 与 Gateway 均有代码和测试入口。
- 仓库报告包含合成回放与本地验收结果。
- 真实会话的跨用户、跨项目命中率仍需要持续采集和独立复核。
- 成本估算依赖价目和 usage 数据，不等于供应商最终账单。

因此，文档会区分“实现存在”“仓库测试通过”“合成数据观察到”和“生产环境已验证”，不会把它们合并成一句营销结论。

## 复核路线

```bash
go test ./kernel/... ./cmd/semantix/...
cd site && npm run check
```

完整仓库包含更多 harness 与 Gateway 测试。运行范围应根据改动面扩展，并记录操作系统、Go/Node 版本和数据来源。

## 去哪里看证据

- 官网 `/benchmarks`：当前公开复现入口和证据等级。
- `docs/reports/`：按里程碑和 issue 保存的验收报告。
- `docs/specs/`：设计与尚未完成的验收契约。
- 对应模块的 `*_test.go`：可执行断言。

## 对应仓库来源

- `docs/reports/m0-gate.md`
- `docs/reports/m0-cost-comparison.md`
- `docs/reports/verify-rubric.md`
- `.github/workflows/ci.yml`

---

> Source: https://semantix.ensureok.ai/docs/profile

# Semantix 项目速览

Semantix 是一个用 Go 实现的 Agent Kernel 与 coding-agent 产品仓库。它把历史会话转成可检索的语义切片，并围绕这些切片提供检索、上下文注入、受约束结果复用、调度、预取和反馈演化。

## 它解决什么问题

Coding agent 会重复读取同一批仓库文件、重新定位相似错误、重新组织已经验证过的步骤。普通 transcript 保存了历史，却没有提供稳定的检索、作用域、失效和验收边界。

Semantix 把问题拆成四步：

1. 从会话事件中提取可复用切片。
2. 用词法、向量或混合检索寻找候选。
3. 根据风险选择只注入背景，或经过附加门后复用结果。
4. 记录命中、浪费和任务反馈，用于受约束调参。

## 仓库里有什么

| 模块 | 责任 | 主要目录 |
|---|---|---|
| CLI | 提取、检索、注入、验证、诊断和维护 | `cmd/semantix` |
| Coding agent | Semantix Agent harness 与可执行入口 | `cmd/semantix-agent`、`harness` |
| 语义切片 | 类型、作用域、存储、压缩与淘汰 | `kernel/slice` |
| 检索 | BM25、embedding、融合与 zone | `kernel/bm25`、`kernel/embed`、`kernel/fuse`、`kernel/zone` |
| 复用 | lookup、注入、L3 判定、指纹与提升 | `kernel/lookup`、`kernel/inject`、`kernel/cache`、`kernel/fingerprint`、`kernel/judge`、`kernel/promote` |
| 资源编排 | round plan、预取和有界演化 | `kernel/sched`、`kernel/prefetch`、`kernel/evolve` |
| Gateway | OpenAI 兼容代理、SSE、上游路由与用量 | `gateway`、`cmd/semantix-gateway` |
| 外部接入 | Agent skill、工具 schema 和会话旁路 | `agent-skill` |

## 核心术语

**Harness** 是承载模型调用、工具、权限和会话循环的宿主。**Kernel** 是相对独立的记忆与优化层。两者通过事件和工具接口连接。

**Semantic slice** 是从会话中提取、能够独立检索的经验单元。它带有类型、来源和作用域，不是完整聊天记录的别名。

**L1 / L2 / L3** 分别表示供应商前缀缓存、语义切片注入和已验证结果复用。风险逐级上升，验证要求也逐级上升。

**Zone** 把检索候选分为 hit、grey 和 miss，用来保留不确定性。hit 仍不是越过当前权限或项目状态检查的许可。

## 当前实现边界

仓库已经包含上述模块的实现和测试入口，也包含合成回放、验收报告与 Gateway 示例。它们能够证明特定代码路径和仓库夹具可运行。

仍需单独验证的是：不同团队、不同模型和真实长期会话中的命中率、错误复用率、延迟与实际账单变化。因此官网文档把“实现存在”“仓库测试”“合成回放”和“生产证据”分开描述。

## 建议阅读顺序

1. 《安装与首次运行》：先跑通最小闭环。
2. 《接入 Coding Agent》：选择宿主接线方式。
3. 《语义切片与三级缓存》：理解每层能做什么。
4. 《验证、用量与健康检查》：建立自己的验收数据。

## 事实来源

- `README.md` 与 `README.zh-CN.md`
- `docs/QUICKSTART.md`
- 各 `kernel/*`、`gateway/*`、`harness/*` 模块及其测试
- `docs/reports/` 与 `docs/specs/`

---

> Source: https://semantix.ensureok.ai/docs/guide

# 从零理解 Semantix

要理解 Semantix，可以从一个约束开始：**模型上下文有限、工具执行有成本，而历史会话里并不是所有内容都值得再次使用。**

## 1. 为什么 transcript 不等于记忆

保存聊天记录只解决“没有丢失”。当新任务到来时，系统仍需回答：哪一段历史相关、属于哪个项目、是否已经过期、能否直接复用结果、使用后有没有帮助。

如果把所有历史原样塞回 prompt，会同时增加 token、噪声和指令注入风险。因此 Semantix 选择先抽取有边界的语义切片，再做检索和分级复用。

## 2. 为什么需要作用域

记忆至少有三种寿命：只属于当前会话、属于某个项目、属于这个用户。把它们混在一个全局池会造成跨项目污染；全部限制在单会话又失去跨会话价值。

`session`、`project`、`user` 作用域是数据隔离和召回范围的第一道边界。它不是访问控制的替代品，敏感内容仍应在导入前脱敏。

## 3. 为什么检索不能直接批准复用

BM25 可以找到相同错误文本，向量检索可以找到同义描述，混合检索可以降低两者各自的盲区。但它们衡量的是相关性，不是世界状态是否相同。

例如，“上次依赖升级成功”与当前任务高度相关，但锁文件已经变化。直接复用上次结果可能错误；把升级步骤作为 L2 背景则通常风险较低。

因此 Semantix 使用 hit、grey、miss 表达检索证据，再为 L3 增加依赖指纹、规则门和可选 judge。无法证明安全时恢复正常执行。

## 4. 为什么有三级缓存

三层缓存对应三种不同的复用对象：

1. L1 复用供应商对稳定 prompt 前缀的计算。
2. L2 复用历史经验文本，但模型和工具仍继续工作。
3. L3 复用经过验证的结果，可能跳过重复执行。

把三者叫作“缓存”不代表它们有相同语义。L3 的风险远高于 L1，因此不能只用一个相似度阈值控制全部路径。

## 5. 调度与预取为什么属于 Kernel

Harness 知道当前对话和工具，Kernel 能积累跨会话统计。调度器把这一统计转成 round plan；预取器利用历史转移模式提前读取可能需要的资源。

预测会失败，所以 runner 应限制在可撤销、低风险的只读动作，并同时记录命中和浪费。预取不是越权执行未来步骤。

## 6. “演化”实际指什么

当前仓库中的演化是有边界的参数更新，例如根据反馈调整检索阈值和注入预算。更新使用平滑、上下界和逃逸机制，结果可检查。

它不表示系统能够自动重写所有策略，也不表示使用次数越多就必然提高任务质量。是否有效必须通过真实会话、人工标签和任务结果验证。

## 7. 系统的失败原则

Semantix 是优化层。读取记忆失败、候选不确定、judge 不可用或预取被拒绝时，宿主应继续正常完成用户任务。这是 fail-open。

Fail-open 不意味着安全检查失败后仍使用缓存；它意味着放弃本次优化，回到原始执行路径。

## 8. 如何评价这个项目

先分四层证据：设计文档说明要做什么，代码和测试说明指定路径如何工作，合成回放说明夹具上的效果，真实生产数据才说明某个部署中的实际收益。

Semantix 已具备可运行的实现和仓库级证据。对于泛化成本和性能优势，仍应在你自己的模型、仓库和会话分布上运行 verify、人工抽查候选，并对照真实账单。

---

> Source: https://semantix.ensureok.ai/docs/profile-en

# Semantix Project Overview

Semantix is a Go-based agent kernel and coding-agent product repository. It turns past sessions into searchable semantic slices, then uses those slices for retrieval, context injection, guarded result reuse, scheduling, prefetch, and bounded feedback-driven adaptation.

## The problem it addresses

Coding agents repeatedly inspect the same repository context, rediscover similar failures, and reconstruct previously verified procedures. A transcript preserves history but does not provide scope, retrieval, invalidation, or acceptance boundaries.

Semantix separates the problem into four steps:

1. Extract reusable slices from session events.
2. Retrieve candidates with lexical, vector, or hybrid search.
3. Inject background context or, behind additional gates, reuse a result.
4. Record hits, waste, and task feedback for constrained tuning.

## Repository map

| Area | Responsibility | Main paths |
|---|---|---|
| CLI | Extraction, retrieval, verification, diagnostics, maintenance | `cmd/semantix` |
| Coding agent | Semantix Agent harness and executable | `cmd/semantix-agent`, `harness` |
| Slices | Types, scopes, storage, compression, eviction | `kernel/slice` |
| Retrieval | BM25, embeddings, fusion, zones | `kernel/bm25`, `kernel/embed`, `kernel/fuse`, `kernel/zone` |
| Reuse | Lookup, injection, L3 gates, fingerprints, promotion | `kernel/lookup`, `kernel/inject`, `kernel/cache`, `kernel/fingerprint`, `kernel/judge`, `kernel/promote` |
| Orchestration | Round plans, prefetch, bounded evolution | `kernel/sched`, `kernel/prefetch`, `kernel/evolve` |
| Gateway | OpenAI-compatible proxy, SSE, upstream routing, usage | `gateway`, `cmd/semantix-gateway` |

## Important boundaries

Semantic similarity is not execution equivalence. A search hit may support L2 context injection, while L3 result reuse additionally needs project-state checks and conservative decision gates.

The repository contains implementations, tests, synthetic replay reports, and deployment examples. These establish inspectable code paths and repository-scoped observations. Cross-team production hit rates, latency changes, and billing outcomes still require validation in each deployment.

## Suggested reading path

Start with **Install and first run**, choose a harness path in **Coding-agent integration**, then read **Slices and cache levels** and **Verification and observability**.

---

> Source: https://semantix.ensureok.ai/docs/guide-en

# Understanding Semantix from Scratch

Semantix starts from a constraint: model context is finite, tool execution has a cost, and not every part of a past session deserves to be used again.

## A transcript is not a memory system

Saving a conversation solves persistence. A new task still needs scope, retrieval, freshness, authority, and feedback. Replaying every transcript increases token use, noise, and prompt-injection exposure.

Semantix therefore extracts bounded semantic slices before retrieval and reuse.

## Scope comes before similarity

Session facts, project conventions, and user preferences have different lifetimes. The `session`, `project`, and `user` scopes reduce cross-project contamination and control recall. They are not a substitute for access control or data redaction.

## Retrieval does not approve execution

BM25 finds exact terms, vector retrieval finds paraphrases, and hybrid fusion reduces their individual blind spots. All three rank relevance. They do not prove that files, dependencies, or user intent are unchanged.

Semantix retains uncertainty through hit, grey, and miss zones. L3 candidates additionally pass dependency fingerprints, rule gates, and an optional judge. Uncertain candidates fall back to normal execution.

## Three cache levels, three different objects

- L1 reuses provider computation for a stable prompt prefix.
- L2 injects relevant historical context while the model and tools still run.
- L3 reuses a verified result and may skip repeated work.

The shared word “cache” does not make these paths equivalent. Risk and proof requirements increase from L1 to L3.

## Scheduling, prefetch, and evolution

The scheduler expresses round plans without replacing the harness permission model. Prefetch uses learned transition patterns for restricted read-only work and records both hits and waste.

Evolution currently means bounded parameter updates, such as retrieval thresholds and injection budgets. It does not mean unrestricted self-modification, and repeated use does not guarantee better outcomes.

## Failure behavior

Semantix is an optimization layer. When memory loading, judging, or prefetch cannot establish a safe path, the host continues the original task. Fail-open means abandoning the optimization, not bypassing a failed safety check.

## How to evaluate the project

Separate specifications, executable tests, synthetic replay, and production evidence. Semantix provides the first three in the repository. Generalized performance and cost claims require real sessions, human relevance checks, task outcomes, and billing comparison in the target environment.