fajarhide/omni · 上手攻略

  • 仓库：fajarhide/omni
  • 链接：https://github.com/fajarhide/omni
  • 分类：agent · context · Rust CLI
  • 作者：spark
  • 更新：2026-09-02

1. 这是什么

OMNI 是一个 Rust 写的本地 CLI + host hooks 套件，专为 agent 宿主（Claude Code、Codex CLI、Gemini CLI、OpenClaw、Cursor、Aider、Hermes、Pi、Cline、Roo、Copilot 等）做工具输出瘦身。它有两件普通过滤器做不到的事，下面分别展开。它做两件普通过滤器做不到的事：

  1. 按"已读"折叠：第二次（或更多次）出现的内容不再原文回放，而是返回一个 marker + 可取的 handle（16 字符哈希）。本地 SQLite RewindStore 把原文保留 30 天，可用 omni retrieve <handle> 完整取回。
  2. 按结构压缩：Rust distillers 把 build log、Docker layer hashes、ANSI 颜色、cargo test 每个测试的 16.5 KB 噪音折叠成 pass/fail summary 这一类对模型有用的句法。JSON / YAML / CSV / NDJSON 永远按字节透传。

⚠️ 它不是再发明一个 tokenizer，是写在你 agent 宿主周围的一对 hook：pre-hook 在命令运行前，post-hook 在模型读到输出前。所有被剪掉的内容归档到本地 SQLite，数据库不离开机器。

2. 解决什么问题

Agent 在多轮会话里反复读同一份文件 / 同一份 git log / 同一份 build log。无 OMNI 时第二次起的字节照样进 context，按 token 计费；窗口紧时被吐回的内容还会挤掉更新的工作。OMNI 把"已经进过 context 的字节"识别出来折成一个 handle，并按 token 类型分流（Permanent / Working 30d / Verbatim 7d）。

基准里最直观的对照（README 实测表，corpus hash 0b63218ef78a1edb）：

  • 同文件读两次：214 B vs 7.6 KB，97.2% 节省
  • git log -15：每条 commit 压成 hash subject，94% 节省
  • cargo test（490 passed, 10 failed）：从 16.5 KB 折成 runner 自带的 pass/fail 摘要，93.0% 节省
  • docker build（重 cache 噪音）：9.2 KB → 构建结果，98.9% 节省
  • kubectl get pods 35 个 pod：0%，按设计透传（每行是 datum，不能造一个节省）

3. 快速安装

⚠️ 安装命令以仓库 README 为准。最新版本是 v0.7.8（写作时截至 release 页）。

macOS / Linux（Homebrew tap）：

brew install fajarhide/tap/omni
omni init      # 交互式配置 Claude / Cursor / VS Code / Codex / Antigravity
omni doctor    # 验证，或 omni doctor --fix

跨平台万能脚本（macOS / Linux / WSL）：

curl -fsSL omni.weekndlabs.com/install | bash

Windows（PowerShell）：

irm omni.weekndlabs.com/install.ps1 | iex

只装 skill 不装二进制：

npx skills add fajarhide/skills --skill omni

装完跑一遍 omni doctor，它会把每个 host 当前落到 Full / Handoff-first / MCP-only 哪一档打印出来。Codex CLI 装完要先开一次 codex 自己勾一遍 "Hooks need review"，不然 omni doctor 一直 fail（issue #359）。

4. 核心用法

日常使用没有任何前缀、没有代理包装，正常跑命令即可。OMNI 的 hook 在底层接住输出。下面这些是它自带的几个直接能用的子命令：

omni init                  # 交互式安装到各 agent host
omni doctor [--fix]        # 看每个 host 落在哪一档、可修
omni stats [--share|--card] # 看你自己的会话节省；--share 输出可复制，--card 出图
omni dashboard             # 127.0.0.1 只读面板（loopback bind）
omni context --tokens      # v0.7.8 新增：按类别拆当前 context（v0.7.8 changelog）
omni retrieve <handle>     # 16 字符 marker 内的全文取回（即便 MCP 没接也能用）
omni reset                 # 全清；强删前想想
omni_run                   # 给 Handoff-first / MCP-only host 用的入口（issue [#388](https://github.com/fajarhide/omni/issues/388)）

⚠️ 环境变量两个值得记住：

  • OMNI_PASSTHROUGH=1 完全跳过 pipeline（卡 21 ms 时延可以临时关）
  • OMNI_TRACE_RETENTION_DAYS=90 把 execution_traces 短窗口拉长（默认 7 天）

4.1 一条工作流示例

最直觉的用法是：平时就跑命令，不要带任何前缀；遇到一个超长输出了，再用 omni retrieve <handle> 主动取回完整原文。比如 agent 第二次 cat src/main.rs 看到的是这样：

[folded · omni handle 8a3f1b2c4d5e6f70 · 12.4 KB retained · full text via `omni retrieve 8a3f1b2c4d5e6f70`]

需要知道某行具体在哪就直接 omni retrieve 8a3f1b2c4d5e6f70，原文按字节回放，不走 distillers。Handoff-first 档的 Cursor / Windsurf、omni_run 是同一条路径，只是由 agent 自己主动调用，而非 host hook 改写。

4.2 上下文窗口诊断（v0.7.8 新增）

omni context --tokens 是 0.7.8 才加的命令：它不接活，只看当前 context 的类别分布，把 system / tools / files / memories / turns 拆开打出来，方便判断哪一类占太大。这条命令对调 prompt、把 distillers 配置跑偏，或者改 goal memory ttl 都很有用。

想自己复现 README 上的 make bench 表（同 corpus 同哈希）：

OMNI_BENCH_DB=~/.omni/omni.db \
  cargo test --release --test bench_replay -- --ignored --nocapture
# OMNI_BENCH_RTK=/path/to/rtk 加竞争对手 arm
# OMNI_BENCH_ALL=1 跑含 terminal 输出的更宽群体

5. 典型适用场景

下面这几类工作流是 OMNI 最容易出量的位置，建议先用 omni stats 看自己究竟落到哪个档，再决定要不要上：

  • 多轮会话里反复 cat / read 同一份大文件：按内容 fingerprint 折，第二次只是 marker + handle，原文在 RewindStore 里随取。
  • 跑 cargo test / pytest -v 这种超长 PASS 日志：distillers 留 runner 自己写的 summary，不替它造一个"全 PASS"假象（issue #143）。
  • CI log / Docker build 抓人噪音：layer 哈希、进度条、ANSI 颜色会被结构识别折叠。
  • agent 之间切换或重启编辑器：30 天 Working tier（sessions, ledger, hot files）让下一个 session 接着读上一段，省一遍 context rebuild。
  • 想看自己究竟省了多少：omni stats → 看会话级节省（不是单条命令），omni dashboard 看实时分布。

6. 坑与注意

⚠️ 三条硬边界：

  1. 30 天之前 retrieve 不解析。README 自己说"a handle cannot promise"超过 30 天的内容，所以默认 Rolling 30d 之前必须 omni retrieve。需要更长就开 OMNI_TRACE_RETENTION_DAYS=90。
  2. 退出码非零永远原文透传（issue #120）。不要因为看到"短输出"就以为成功了。
  3. 结构化数据 byte-for-byte 透传（pipeline::format 模块）。JSON / YAML / NDJSON / CSV 一律不碰——这是设计，不是疏漏。kubectl get pods 表 0% 节省就是这个原因。

⚠️ 性能账：每条命令 +21 ms（空库）→ +61 ms（205 MB 库）。开销随历史增长，不随 payload 涨。要测速就先 OMNI_PASSTHROUGH=1 比 baseline。

⚠️ 过滤器在 0.7.4 之后已退役。 README FAQ 明确：在 6,656 条命令上 pattern-matching 只省 2,018 字节（0.031%），却吃掉 5–7 ms 的 10 ms 预算。"add my own filter" 现在没有这条路；要改就开 issue。

⚠️ head-to-head 表 OMNI 不是 top arm。同样 8,486,830 字节上：headroom dedup 5.8% / rtk + omni's ledger 5.7% / caveman + omni's ledger 5.6%，OMNI with ledger 4.9% 排第 4。README 直接说："On this corpus OMNI is not the top arm, and both of its halves are behind."——这跟 README 自己承认的数字一致，没吹。证据来自 docs/benchmarks/0.7.8.json，corpus hash 就在表上可以复跑。

⚠️ Codex CLI 多一步：装完 plugin 后要进 Codex 自己 review 一次 hooks，否则 omni doctor 报 fail。

7. 与同类对比

OMNI 是 agent-side output distillation + session caching hybrid，不是 textbook prompt compressor。横向对照表里出现的几个口径：

  • headroom（0.34.0）：只做跨 turn dedup，不重写 host pipeline → 占的字节 5.8% 在 OMNI 前。
  • rtk（0.45.0）：Rust 写的 terminal-aware 命令精简器（rtk pipe 2.1%），加 OMNI ledger → 5.7%。
  • caveman（bin-v1.0.0）：通用 compressor，compress 2.1%，加 OMNI ledger → 5.6%。
  • lean-ctx（3.9.18）compress：直接给 compressed_bytes 而非文本，不能复跑同 corpus 同输出 → 4.8%。
  • OMNI filters only：1.4%（过滤层最弱）。

⚠️ 真正发力的不是 filters，是 ledger（跨 session 折叠 + content-aware handle）。同一 ledger 在 OMNI 之外的项目里配上就涨到 ~5.6–5.7%。一句话：OMNI 的护城河是 ledger + Rust distillers + host hook 三件套，不是 token 重写速度。

CI / corner cases 里 README 还公开了 #398 ：早期有 2 条命令输出比原文还大，他们当场发布了。"no call came back larger" 在 0.7.8 上 self-claim 真实有效（9,478 调）。

选哪个的判断方法：如果你主要在乎"少重复看同一份东西"，选 OMNI；如果主要在乎"每一格 token 都不要再压一遍、跨 turn dedup 越界越大"，可以试 headroom；如果两者都想要，先看宿主落不落 Full 档（Claude Code / Codex / OpenClaw 都落），别在 MCP-only 档的 Cline / Roo 上期待同样数字。

8. 一句话推荐

如果你被多轮会话的"读过的字节重复计费"卡过 context 窗口、又不想完全换 agent host——装 fajarhide/omni，跑一遍 omni doctor，看 omni stats 几天内的会话级节省再判断。三条硬约束（30 天 / 失败透传 / 结构数据透传）比"能省多少"更重要，先读完再上手。

字数：约 1,950 字
来源： 1. https://github.com/fajarhide/omni（首页） 2. https://raw.githubusercontent.com/fajarhide/omni/main/README.md（v0.7.8 README） 3. https://github.com/fajarhide/omni/releases（v0.7.8 changelog） 4. README 内嵌 issue 链接 #120 / #143 / #359 / #388 / #398 作为 anchor

不确定 / 待核： - ⚠️ Windows 安装器的稳定性（只有 PowerShell 一行，未现拉测试） - ⚠️ 对其他 agent host（非 README 列的 14 款）的兼容度，未单独验 - ⚠️ 与 lean-ctx 的对比那行 README 明确说"could only be estimated"，因此略低于可比基线