# llm-squeeze-cli

**Repository Path**: aierwiki/llm-squeeze-cli

## Basic Information

- **Project Name**: llm-squeeze-cli
- **Description**: No description available
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# llm-squeeze-cli

`llm-squeeze-cli` 是一个面向 Agent 工作流的文本压缩命令行工具。

它通过 OpenAI SDK 调用大模型，把长文本压缩成高信息密度摘要，并支持两个可选参数：

- 指定目标输出 token 数
- 指定压缩时重点保留的信息方向

如果输入文本超过允许的 token 上限，工具会直接报错，而不是静默截断。

如果指定了目标 token，工具默认会在输出超限时自动重压缩，最多 3 次；3 次以后如果仍然超限，会明确报错。

工具支持通过 `.env` 管理常用配置。配置一次后，后续可以直接复用，不必每次都重复输入模型、目标 token、保留重点或 API 配置。

## 功能

- 压缩长文本为高信息密度摘要
- 可选指定目标压缩长度
- 可选指定重点保留内容
- 调用前先做输入 token 校验
- 支持单独统计输入 token，方便先判断是否需要切块
- 指定目标 token 时默认自动重压缩最多 3 次
- 支持文件输入、命令行文本输入和标准输入
- 支持纯文本输出和 JSON 输出

## Provider 兼容说明

项目默认按 OpenAI SDK 的通用方式调用模型，但会对部分兼容提供方做内部适配。

以 MiniMax 的 OpenAI 兼容接口为例，当前实现遵循其官方文档：

- 通过 `extra_body.reasoning_split=true` 将思考内容拆到 `reasoning_details`，避免仅靠 `content` 中的 `<think>` 标签解析
- MiniMax 的 `temperature` 合法范围是 `(0, 1]`，因此不会向它发送 `0`
- 如果模型把 JSON 结果包在 Markdown 代码块中，工具会自动剥离代码块并提取真正摘要

这部分兼容逻辑是工具内部行为，不通过 CLI 参数对外暴露。

## 安装

在项目目录下安装：

```bash
pip install -e .
```

## 使用 `.env` 管理配置

可以直接复制示例配置文件：

```bash
cp .env.example .env
```

先初始化配置模板：

```bash
llm-squeeze-cli --init-config
```

查看当前生效配置：

```bash
llm-squeeze-cli --show-config
```

上面两种方式都可以得到 `.env` 文件模板。填写后，工具会自动加载当前目录或上层目录中的 `.env`。

支持的配置项：

- `OPENAI_API_KEY`：必需
- `OPENAI_BASE_URL`：可选
- `LLM_SQUEEZE_MODEL`：可选
- `LLM_SQUEEZE_MAX_INPUT_TOKENS`：可选
- `LLM_SQUEEZE_MAX_RECOMPRESS_ATTEMPTS`：可选
- `LLM_SQUEEZE_TARGET_TOKENS`：可选，默认压缩目标
- `LLM_SQUEEZE_PRESERVE_FOCUS`：可选，默认重点保留信息

命令行参数优先级高于 `.env`。也就是说，你可以平时依赖 `.env`，只有在某次任务需要临时覆盖时再传参数。

如果缺少关键配置，尤其是 `OPENAI_API_KEY`，工具会明确报错并提示先执行 `llm-squeeze-cli --init-config`。

仓库中也提供了 [llm-squeeze-cli/.env.example](llm-squeeze-cli/.env.example) 作为示例配置文件。

## 环境变量

- `OPENAI_API_KEY`：必需
- `OPENAI_BASE_URL`：可选
- `LLM_SQUEEZE_MODEL`：可选，默认 `gpt-4.1-mini`
- `LLM_SQUEEZE_MAX_INPUT_TOKENS`：可选，默认 `32000`（约 32K）
- `LLM_SQUEEZE_MAX_RECOMPRESS_ATTEMPTS`：可选，默认 `3`
- `LLM_SQUEEZE_TARGET_TOKENS`：可选
- `LLM_SQUEEZE_PRESERVE_FOCUS`：可选

## 用法

压缩文件：

```bash
llm-squeeze-cli --input-file notes.txt
```

直接压缩文本：

```bash
llm-squeeze-cli --text "这里是一段要压缩的文本"
```

只统计 token：

```bash
llm-squeeze-cli --input-file notes.txt --count-tokens
```

通过标准输入压缩：

```bash
cat notes.txt | llm-squeeze-cli
```

使用 `.env` 中的默认配置：

```bash
llm-squeeze-cli --input-file notes.txt
```

指定目标 token：

```bash
llm-squeeze-cli --input-file notes.txt --target-tokens 1200
```

指定重点保留信息：

```bash
llm-squeeze-cli --input-file notes.txt --preserve-focus "重点保留结论、限制条件和待办项"
```

输出 JSON：

```bash
llm-squeeze-cli --input-file notes.txt --json
```

## 参数

- `--init-config`：在当前目录生成 `.env` 模板并退出
- `--show-config`：输出当前生效配置并退出
- `--count-tokens`：只统计输入 token 并退出，不调用模型
- `--input-file`：要压缩的文本文件
- `--text`：直接传入待压缩文本
- `--output-file`：把结果写入文件
- `--target-tokens`：希望压缩到的 token 数
- `--max-recompress-attempts`：超限时自动重压缩的最大次数，默认 3
- `--preserve-focus`：压缩时优先保留的信息方向
- `--model`：指定模型
- `--max-input-tokens`：输入 token 上限
- `--api-key`：覆盖 `OPENAI_API_KEY`
- `--base-url`：覆盖 `OPENAI_BASE_URL`
- `--json`：输出 JSON 结果

当 `--count-tokens` 与 `--json` 一起使用时，工具会输出 token 数、模型名、输入上限，以及是否仍在输入上限内。

## 限制

- 输入不能为空
- `--input-file` 和 `--text` 不能同时使用
- 如果没有 `--input-file`、`--text` 且没有标准输入，会报错
- 如果输入 token 超过限制，会直接报错
- 如果指定了 `--target-tokens`，工具会在超限时自动重压缩最多 3 次；仍然超限则报错
- 如果缺少关键配置，会明确提示用户先初始化 `.env` 或传入覆盖参数

工具会在内部根据提供方能力自动做 reasoning 兼容处理；对 MiniMax 这类接口，会优先按官方 `reasoning_split` 方案解析正文，不再通过 CLI 或 `.env` 暴露单独的 thinking 开关。

`--show-config` 会输出当前实际生效的配置，包括模型、输入上限、重压缩次数、默认目标 token、默认重点保留信息，以及 `OPENAI_API_KEY` 是否已配置。

## Skill

本目录还包含一个给 Agent 使用的 Skill 文件：[SKILL.md](SKILL.md)。

该 Skill 用于指导 Agent 在需要压缩长文本、长上下文、长日志或长文档时，正确调用 `llm-squeeze-cli`。