内容
# 上下文清理工具
适用于 AI 代理的本地优先上下文清理工具。
ContextClean 将嘈杂的 HTML、CI 日志、堆栈跟踪、粘贴的终端输出和项目文件夹转换为紧凑、编辑过、按令牌预算的上下文，然后再传递给大型语言模型（LLM）。命令行工具是 `ctxclean`；失败日志包装器是 `ctxrun`。
```bash
ctxclean gha build.log --max-tokens 3200 --format markdown
ctxclean repo . --fit gpt-4.1 --output context.md
ctxrun --max-tokens 8000 npm test
```
## 证明
使用 `scripts/benchmarks.ps1`、`ctxclean` 二进制文件和精确的 `o200k_base` 令牌计数进行测量。每一行都必须保留并删除检查 `benchmarks/results.json`。
| 固定装置 | 清洁前 | 清洁后 | 节省 | 减少 |
| --- | ---: | ---: | ---: | ---: |
| HTML 爬取 | 70,571 | 5,892 | 64,679 | 91.7% |
| CI 失败日志 | 75,768 | 3,200 | 72,568 | 95.8% |
| 提供商 CI 混合 | 17,469 | 33 | 17,436 | 99.8% |
| 堆栈跟踪转储 | 28,189 | 1,850 | 26,339 | 93.4% |
| 脏 HTML 文章 | 371 | 97 | 274 | 73.9% |
## 为什么使用 ContextClean？
AI 代理在获得正确的上下文时效果最佳，而不是获得最多的上下文。原始页面包含脚本、cookie 横幅、跟踪块和重复导航。CI 日志在安装聊天和重复重试下掩盖了实际故障。仓库扫描可能会意外地包含生成的文件、缓存、本地环境文件和机密值。
ContextClean 为您提供了一个确定性的本地优先方法：
- 使用 `o200k_base` 进行精确的 OpenAI 兼容令牌计数
- 通过 `--max-tokens` 和 `--fit gpt-4.1|claude-sonnet|gemini-pro` 进行模型预算
- 保留标题、链接、段落、表格、列表和代码块的 HTML 清理
- 解析器支持的损坏 HTML 清理，以保持嵌套列表、表格和代码可读
- GitHub Actions、pytest、cargo、Docker Buildx、Playwright、pnpm 和 npm 噪音的特定于提供商的日志压缩
- 仓库感知扫描，尊重 `.gitignore` 和 `.ctxcleanignore`
- 默认启用类似机密值的编辑
- 报告令牌节省、噪音源、删除的章节和下一个要运行的命令
- 用于代理工作流的 stdio MCP 模式
- 流式 `ctxrun`，用于清理失败的命令输出，同时保留子退出代码
## 安装
从 [GitHub Releases](https://github.com/karurikwao/contextclean/releases/tag/v0.1.0) 下载发布二进制文件。
附加了 Linux x64、macOS Intel、macOS Apple Silicon 和 Windows x64 存档。
使用 Rust 1.85 或更新版本从 Git 安装：
```bash
cargo install --git https://github.com/karurikwao/contextclean contextclean-cli
```
从本地checkout安装：
```bash
git clone https://github.com/karurikwao/contextclean.git
cd contextclean
cargo install --path crates/contextclean-cli
```
Docker 可用，但暂无主机 Rust：
```bash
docker run --rm -v "${PWD}:/work" -w /work -e CARGO_TARGET_DIR=/tmp/contextclean-target rust:1.85-bookworm sh -lc 'export PATH=/usr/local/cargo/bin:$PATH; cargo test --workspace --all-features --locked'
```
crates.io 发布已准备好用于 `v0.1.0`；请参阅 `docs/RELEASE_CHECKLIST.md`。
## 快速入门
清理 HTML 导出：
```bash
ctxclean fixtures/dirty_html_article.html --mode standard --output clean.md --force
```
清理 GitHub Actions 失败日志：
```bash
ctxclean gha fixtures/ci_failure_log.txt --max-tokens 8000 --format markdown
```
安全打包仓库：
```bash
ctxclean repo . --max-tokens 12000 --format markdown
```
解释上下文为何嘈杂：
```bash
ctxclean report benchmarks/fixtures/github_actions_failure_large.log --max-tokens 8000 --format text
```
运行测试命令，仅在失败时清理输出：
```bash
ctxrun --max-tokens 8000 pytest
ctxrun --format markdown npm test
```
启动 MCP 服务器模式：
```bash
ctxclean mcp
```
## 文档和 Wiki
GitHub Wiki 是 ContextClean 的长形式操作手册：
- [Wiki 首页](https://github.com/karurikwao/contextclean/wiki)：定位、核心概念和页面索引
- [安装](https://github.com/karurikwao/contextclean/wiki/Installation)：发布二进制文件、Cargo 安装、Docker 检查和验证
- [命令指南](https://github.com/karurikwao/contextclean/wiki/Command-Guide)：`ctxclean`、`ctxclean gha`、`ctxclean repo`、`ctxclean report`、`ctxclean mcp` 和 `ctxrun`
- [安全性和隐私](https://github.com/karurikwao/contextclean/wiki/Safety-And-Privacy)：编辑、敏感路径、忽略文件和本地优先保证
- [集成](https://github.com/karurikwao/contextclean/wiki/Integrations)：GitHub Actions、MCP 客户端、AI 编码代理、Python、LangChain 和 LlamaIndex
- [基准和验证](https://github.com/karurikwao/contextclean/wiki/Benchmarks-And-Validation)：固定装置声明、令牌会计和验收检查
使用 README 获取工具的快捷路径。使用 Wiki 时，您需要部署详细信息、集成指导、安全行为或故障排除。
## 命令
```text
ctxclean [OPTIONS] [INPUT]
ctxclean gha [OPTIONS] <INPUT>
ctxclean repo [OPTIONS] <INPUT>
ctxclean report [OPTIONS] <INPUT>
ctxclean mcp
ctxrun [OPTIONS] <COMMAND> [ARGS]...
```
核心选项：
| 选项 | 描述 |
| --- | --- |
| `-o, --output, --out <PATH>` | 将清理后的输出或报告写入文件 |
| `-t, --max-tokens <TOKENS>` | 清理内容的令牌上限 |
| `--fit <MODEL>` | `gpt-4.1`、`claude-sonnet` 或 `gemini-pro` |
| `-m, --mode <MODE>` | `light`、`standard` 或 `aggressive` |
| `-f, --format <FORMAT>` | `text`、`markdown` 或 `json` |
| `-c, --strip-comments` | 删除明显的代码注释行 |
| `--redact-secrets` | 保持默认编辑启用 |
| `--no-redact-secrets` | 禁用防御性编辑 |
| `--include-sensitive` | 仅在明确请求时包含敏感路径 |
| `--dry-run` | 打印而不写入输出文件 |
| `--force` | 覆盖输出文件 |
| `-q, --quiet` | 禁止非错误诊断 |
| `-v, --verbose` | 将额外诊断信息打印到 stderr |
## 集成
- `ctxclean gha failed-log.txt`：GitHub Actions 日志清理。默认为激进模式。
- `ctxclean repo .`：安全的仓库上下文打包器，使用与默认清理器相同的忽略和编辑管道。
- `ctxclean mcp`：stdio 上的换行 JSON-RPC MCP 服务器，带有 `contextclean_clean` 和 `contextclean_report` 工具。
- `ctxrun npm test`：命令包装器，成功输出不更改，失败输出清理，退出代码与子进程一致。
- 第一方 GitHub Action 包装器：`uses: karurikwao/contextclean@main`。
- MCP 兼容性矩阵：`docs/MCP_COMPATIBILITY.md`。
- Homebrew 直接安装和 tap 注释：`docs/HOMEBREW.md`。
- Python 包装器脚手架：`packages/python`。
- Claude/Cursor/Codex、GitHub Actions、MCP 客户端、LangChain 和 LlamaIndex 示例位于 `examples/`。
## JSON 形状
`--format json` 发出一个规范的 `CleanResult`，具有稳定的顶级字段：
```json
{
"version": "0.1.0",
"mode": "standard",
"format": "json",
"source": "input.html",
"input": { "bytes": 18420, "chars": 18102, "tokens": 4526 },
"output": { "bytes": 6920, "chars": 6811, "tokens": 1703, "content": "..." },
"metrics": {
"input_tokens": 4526,
"output_tokens": 1703,
"tokens_saved": 2823,
"compression_ratio": 0.376,
"reduction_percent": 62.4
},
"budget": {
"fit": null,
"model_id": null,
"tokenizer": "o200k_base",
"token_count_is_exact": true,
"preset_limit_tokens": null,
"effective_limit_tokens": null,
"model_max_output_tokens": null,
"limit_source": "none"
},
"truncation": {
"applied": false,
"limit_tokens": null,
"tokens_removed": 0,
"reason": null
},
"removed_sections": [],
"noise_sources": [],
"warnings": [],
"metadata": { "elapsed_ms": 4, "engine": "contextclean-core" }
}
```
报告 JSON 使用 `tokens`、`biggest_noise_sources`、`removed_section_summary`、`recommended_command` 和 `warnings`，不包括清理后的正文。
## 信任和隐私
ContextClean 设计为本地运行。
- CLI 中没有遥测或网络调用。
- 默认情况下，类似机密的值在输出前被编辑。
- 目录扫描默认跳过常见敏感路径和生成路径。
- 尊重 `.gitignore` 和 `.ctxcleanignore` 进行目录扫描。
- 敏感文件和凭证目录需要 `--include-sensitive`。
- `--include-sensitive` 不会覆盖忽略文件。
- 不安全的编辑退出需要 `--no-redact-secrets`。
ContextClean 不能替代安全审查。请始终在共享专有代码之前检查上下文。
## 基准
刷新基准测试夹具和测量表：
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\benchmarks.ps1
```
输出：
- `benchmarks/fixtures/`
- `benchmarks/results.json`
- `benchmarks/results.md`
## 比较
| 工具模式 | 它为您提供什么 | ContextClean 的不同之处 |
| --- | --- | --- |
| `cat file | llm` | 快速原始上下文 | 在粘贴/发送前清理、编辑、测量和预算 |
| 日志跟踪 | 最近的失败文本 | 崩溃重复的噪音并保留独特的失败 |
| HTML 转 Markdown 转换器 | 可读的页面 | 删除 AI 不友好的样板并报告令牌节省 |
| 手动提示修剪 | 人类判断 | 确定性、可复制、精确的令牌会计 |
| 云预处理器 | 方便 | 本地优先，无 API 密钥，无遥测 |
## 路线图
- V0.1.0：HTML 清理器、日志粉碎器、令牌预算、报告、仓库安全、MCP stdio、`ctxrun`、启动基准。
- V0.1.x：解析器支持的损坏 HTML 处理、提供商 CI 蒸馏器、流式 `ctxrun`、第一方操作、MCP 矩阵、Homebrew 直接安装说明和 Python 包装器脚手架。
- V0.2.0：版本化的 GitHub Action 标签、发布的 Homebrew Tap、shell 补全和更丰富的发布二进制文件。
- V0.3.0：发布的 Python 包和更深入的 LangChain/LlamaIndex 适配器。
- V0.4.0：显式标志后面的 AST 感知代码压缩。
## 好的第一件事
- 从公共失败的工作流中添加一个现实世界的 GitHub Actions 夹具。
- 从浏览器导出和文档站点添加更多损坏的 HTML 夹具。
- 为 Bash、Zsh、Fish 和 PowerShell 添加 shell 补全。
- 将 `docs/HOMEBREW.md` 变成发布的 Tap。
- 验证更多 MCP 客户端并更新 `docs/MCP_COMPATIBILITY.md`。
- 为 Docker Buildx、pytest、cargo 和 Playwright 日志添加基准测试夹具。
## 开发
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features --locked
cargo build --workspace --release --locked
```
在 Windows PowerShell 上：
```powershell
.\scripts\check.ps1
```
## 项目站点
Cloudflare Pages 托管站点位于 `site/`，由 `wrangler.toml` 配置。
## 贡献
在发布存储库之前，问题和拉取请求是欢迎的。从 `CONTRIBUTING.md`、`docs/MVP_SCOPE.md`、`docs/ARCHITECTURE.md` 和 `docs/ROADMAP.md` 开始。
