AI 编码代理真正消耗上下文的地方，往往不是源代码本身，而是一长串命令输出。cargo test 会把编译依赖和测试进度全部吐出来，docker build 会把每一层的日志刷满屏，git push 会显示对象计数、压缩、远端解析等细节。人类看这些输出时会自动跳过噪声，但代理会把它们完整塞进上下文窗口。

今天推荐的 mpecan/tokf 就是在这个位置做过滤。它是一个 Rust 写的 CLI，目标是在命令输出到达 AI 工具之前，用可配置的 TOML 规则把冗长日志压缩成更短、更明确的结果。当前 GitHub API 显示项目约有 174 stars、18 forks，主要语言是 Rust，许可为 MIT，仓库创建于 2026 年 2 月 18 日。

项目概览

属性详情
仓库mpecan/tokf
Stars约 174
Forks18
主要语言Rust
许可MIT
创建时间2026 年 2 月 18 日
最近推送2026 年 5 月 21 日

它解决的不是“日志太多”，而是“代理读错重点”

长日志对人类来说只是烦，对 AI agent 来说会变成决策输入。一次测试成功时，真正重要的信息可能只有“47 个测试通过，用时 2.31 秒”。但原始输出里会夹着几十行编译 crate、进度条和重复摘要。失败时更麻烦：如果错误堆在几百行构建输出中间，代理可能先被无关内容占掉注意力，再开始猜测问题在哪里。

tokf 的思路比较直接：不要等日志进入上下文后再让模型总结，而是在命令执行层先把输出过滤掉。README 里的例子显示，cargo test 可以从 61 行压缩成一行测试结果，git push 可以从对象枚举和压缩过程压缩成 ok 加目标分支。项目方称常见命令能减少 60-90% 的 LLM 上下文消耗；这个数字来自项目说明，实际效果仍然取决于命令类型和过滤器质量。

TOML 过滤器是关键设计

tokf 不是把所有命令都套一个固定摘要器。它会为命令查找对应过滤器，执行原命令，再把输出通过过滤器处理。过滤逻辑放在普通 TOML 文件里，不需要重新编译二进制。

这个选择有两个好处。

第一，过滤规则可以贴近具体命令。git status、cargo test、npm test、kubectl get pods 的关键信息完全不同，用同一套启发式摘要很容易漏掉重要状态。tokf 的内置库按命令维护过滤器，更适合处理这些差异。

第二，团队可以覆盖或共享规则。README 提到可以用 tokf eject 把内置过滤器复制到项目或用户配置目录，然后按自己的输出习惯调整。对于有内部工具链的团队，这一点比“只能接受默认摘要”更实用。

支持的命令范围已经不窄

tokf README 里列出的内置过滤器覆盖了不少日常开发命令，包括：

  • Git：add、commit、diff、log、push、show、status；
  • Rust：cargo build、check、clippy、fmt、install、test；
  • JavaScript：npm run、npm test、pnpm add、pnpm install、TypeScript compiler、Next build；
  • 容器和平台工具：docker build、docker compose、docker images、docker ps、kubectl get pods；
  • 其他测试和构建工具：go build、go vet、Gradle、pytest、Prisma、gh 的部分 PR 和 issue 命令。

这说明它的定位不是单纯的 Rust 项目辅助工具，而是面向 AI 编程会话的命令输出层。只要代理经常运行 shell 命令，这一层就会持续影响上下文质量。

用法：显式包一层，或安装 hook

最保守的使用方式是手动包一层：

tokf run git push origin main
tokf run cargo test
tokf run docker build .

这样比较适合先试效果。你可以逐个命令确认过滤后的信息是否足够，再决定是否放进默认工作流。

如果希望 AI 编码工具自动使用 tokf，README 提供了 hook 安装方式：

tokf hook install --global
tokf hook install --tool opencode --global
tokf hook install --tool codex --global

这类全局 hook 要谨慎开启。它的优点是不用每次写 tokf run，代理执行的命令会自动过滤；风险是如果过滤器不适合某个项目，代理可能看不到你希望它看到的完整输出。比较稳的做法是先在一个项目里验证，再决定是否全局安装。

通用错误、测试和摘要模式

当没有专用过滤器时，tokf 还提供了三个通用子命令：

tokf err cargo build
tokf test pytest
tokf summary docker build .

tokf err 关注错误和警告，tokf test 关注测试失败和摘要，tokf summary 做预算内的启发式总结。这些模式的价值在于“先给代理一份更像诊断报告的输出”。它们不替代完整日志，但可以减少代理在无关输出里来回搜索的概率。

对 AI agent 工作流来说，这一点很重要。代理最怕的不是没有信息，而是信息密度太低。一个好的过滤器应该保留退出码、失败位置、错误摘要、必要上下文和下一步线索，同时删除进度条、重复编译行、安装流水账和成功路径里的无关细节。

过滤器也需要测试

tokf 比较值得注意的一点是，它把过滤器本身当成可测试对象。README 里有 tokf verify、tokf verify --json、tokf verify --require-all 和 tokf verify --safety 等命令，用来跑过滤器测试套件、检查覆盖情况，并做 prompt injection、shell injection、隐藏 Unicode 等安全检查。

这比“写几条正则然后相信它”更靠谱。过滤器如果误删失败信息，后果可能比日志冗长更严重。尤其是在代理自动改代码、自动跑测试的场景里，过滤器必须能被验证，否则它会成为新的不透明层。

如果团队准备自定义过滤器，我会把测试作为基本要求：每个过滤器至少放几份成功、失败、边界输出样本，并确认过滤结果不会隐藏退出码和关键错误。

适合什么人

tokf 特别适合几类场景：

  • 经常使用 Claude Code、Codex CLI、OpenCode 等 AI 编码工具的人；
  • Rust、Node、Docker、Kubernetes 输出很多，代理上下文经常被日志占满的项目；
  • 需要让代理反复跑测试、构建和 Git 命令的团队；
  • 想统一“命令输出给代理看什么”的内部工具链维护者；
  • 已经开始为 AI agent 设计 hooks、skills、rules 和工作区约束的人。

如果你只是偶尔让 AI 看一段错误日志，直接手动粘贴可能更简单。但只要代理每天都在本地跑命令，输出过滤就会从“小优化”变成基础设施问题。

需要注意的边界

tokf 仍然是很新的项目，使用前要注意几个现实边界。

首先，过滤器是有观点的。它判断什么是重要信息，什么是噪声；如果你的项目输出格式特殊，默认规则可能不够合适。

其次，hook 会改变代理看到的世界。开启全局 hook 前，最好确认能快速绕过过滤，例如使用 --no-filter 或保留原始日志路径。

第三，不要把压缩比例当作唯一指标。更短不一定更好。真正应该关注的是：失败信息是否完整、成功摘要是否足够、异常路径是否能被保留。

最后，涉及安全和注入的日志要谨慎。tokf 有安全验证命令是好事，但这不等于所有自定义过滤器天然安全。任何会把外部输出交给代理读取的环节，都应该默认不可信。

总结

mpecan/tokf 把一个越来越常见的问题放到了正确的位置：AI 编码代理不需要原始命令输出的全部噪声，它需要稳定、可验证、足够完整的信号。tokf 用 Rust CLI、TOML 过滤器、内置命令库和 hook 集成来做这件事，设计上比单纯让模型“总结日志”更可控。

我最看重的是它把过滤器做成可编辑、可验证的工程资产。AI agent 的上下文管理不应该只靠提示词，也需要这样的工具层。对经常让代理跑构建、测试、Git 和容器命令的开发者来说，tokf 值得放进试验清单。

项目地址：https://github.com/mpecan/tokf