内容
<h1 align="center">⚡ GlyphCompress</h1>
<p align="center">
<img src="./assets/logo.png" alt="GlyphCompress Logo" width="300">
</p>
<p align="center">
<a href="https://www.npmjs.com/package/glyph-compress"><img src="https://badgen.net/npm/v/glyph-compress" alt="NPM 版本"></a>
<a href="https://opensource.org/licenses/AGPL-3.0"><img src="https://badgen.net/badge/License/AGPL-3.0-only/blue" alt="许可证：AGPL-3.0-only"></a>
<a href="COMMERCIAL_LICENSE.md"><img src="https://badgen.net/badge/商业许可证/需要用于专有用途/red" alt="商业许可证"></a>
<a href="https://marketplace.visualstudio.com/items?itemName=neolambo.glyph-compress"><img src="https://badgen.net/badge/VS%20Code%20Marketplace/可用/blue" alt="VS Code 市场"></a>
<a href="https://github.com/Neolambo/glyph-compress/releases"><img src="https://badgen.net/github/release/Neolambo/glyph-compress" alt="GitHub 发布"></a>
</p>
<p align="center">
<strong>面向 IDE↔LLM 通信的语义压缩 — CLI、VS Code 扩展和 MCP 服务器，默认可逆压缩，根据真实提供商的标记器进行校准。</strong>
</p>
<p align="center">
在合适的有效载荷上节省高达 90%+（见下面的基准测试）；在项目自身的基准测试套件上，实际聚合节省为 22%，诚实报告。
</p>
GlyphCompress 使用基于成分的激进编码系统（灵感来自中文象形文字）来压缩 IDE 和大型语言模型之间交换的冗余上下文。注入到 LLM 系统中的共享代码簿使它能够将紧凑的字符序列解码回完整的语义概念。
### 🎬 看它在行动
观看最新的 YouTube 视频，看看 GlyphCompress 如何实现 90% 的标记节省：
- ⚙️ **[数据流架构](https://youtu.be/XRwRYEsReJU)**：一个图形动画，展示引擎如何压缩和翻译冗余代码为密集的语义字符。
---
## 📌 目录
- [🎯 问题](#-问题)
- [✨ 解决方案](#-解决方案)
- [🔍 现实会话展示](#-现实会话展示)
- [🧠 高级功能：全息折叠、意图差异和历史衰减](#-高级功能全息折叠意图差异和历史衰减)
- [📊 基准测试](#-基准测试)
- [🚀 使用：命令行（CLI）](#-使用命令行-cli)
- [🚀 快速入门（代码和扩展）](#-快速入门)
- [👻 终极魔法：零命令透明代理](#-终极魔法零命令透明代理-v050)
- [🔌 MCP 服务器（Claude Code、Claude Desktop 等其他 MCP 客户端）](#-mcp-服务器claude-code-claude-desktop-其他-mcp-客户端)
- [🔤 字符协议](#-字符协议)
- [👥 贡献](#-贡献)
- [⚖️ 双重许可模式](#-双重许可模式)
---
## 🎯 问题
每个 IDE→LLM 请求都带有大量冗余上下文。随着编码会话的增长，**聊天历史**呈指数级累积，导致标记成本激增、性能滞后和 LLM 达到上下文窗口限制：
```
系统提示： ~2,000 标记（每次重复）
打开的文件： ~3,000 标记
错误/诊断信息： ~500 标记
聊天历史（多轮）： ~4,000 标记（指数级爆炸）
用户： ~500 标记
─────────────────────────────────────────
总计： ~10,000 标记/请求
```
按 50 请求/天 → **500K 标记/天** → 在 Claude/GPT-4 上花费 $8-15/天。
## ✨ 解决方案
GlyphCompress 拦截输出的 LLM 请求，使用共享代码簿压缩上下文，并利用 **实验性注意力衰减压缩（ADC）** 来逐步将较旧的历史压缩成摘要，从而节省 **80-90% 的标记**，并实现 **近乎无限的多轮聊天**：
```
之前（1,734 字符）：
{ prompt: "修复 UserProfile.tsx 中的错误",
files: [{ path: "src/components/UserProfile.tsx", content: "...44 行..." }],
diagnostics: [{ code: "TS2339", message: "属性 'department' 不存在于类型 'User'" }] }
之后（137 字符）：
[F: ◈₍1₎=src/components/UserProfile.tsx]
⺌✗ ◈₍1₎
◈₍1₎ᵗ [imp:5 exp:1 ◇:4 ⟿:2 ⟳:5 44L]
◈₍1₎:42 ✗∉prop 'department'∉User
→ 12.7 倍压缩，节省 92%
```
## 🔍 现实会话展示
GlyphCompress 包含一个内置的交互式演示基准测试（`npm run demo`），模拟现实世界的开发人员任务（React 调试、SQL 优化、Python 机器学习管道、YAML 配置）来衡量字符和标记减少。
以下是典型的压缩会话遥测数据的示例：
### 1. 修复 React 组件中的 TypeScript 诊断信息
* **原始上下文**：`1,734 字符`（包括 `UserProfile.tsx` 内容、历史记录和 TS2339 错误代码）。
* **压缩输出**：`137 字符`（**12.7 倍压缩，节省 92%**）。
* **发出有效载荷**：
```text
[F: ◈₍1₎=src/components/UserProfile.tsx]
⺌✗ ◈₍2₎
◈₍1₎ᵗ [imp:5 exp:1 ◇:4 ⟿:2 ⟳:5 44L]
◈₍1₎:42 ✗∉prop 'department'∉User
[T1:U:⺍▲] [T2:A:⺍▲]
```
### 2. 优化慢速 Prisma/SQL API 端点
* **原始上下文**：`1,999 字符`（包括两个 TS 控制器/服务文件、Express 导入和历史记录）。
* **压缩输出**：`195 字符`（**10.3 倍压缩，节省 90%**）。
* **发出有效载荷**：
```text
[F: ⊜₍3₎=src/controllers/orders.controller.ts | ⊜₍4₎=src/services/order.service.ts]
⺋ API 端点
⊜₍3₎ᵗ [imp:3 exp:1 20L]
⊜₍4₎ᵗ [imp:1 exp:1 26L]
[T1:U:The /api/orders 端点] [T2:A:⺎▼]
```
### 3. 将应用程序部署到 Kubernetes
* **原始上下文**：`730 字符`（包括原始 Kubernetes Deployment YAML 块和提示）。
* **压缩输出**：`84 字符`（**8.7 倍压缩，节省 88%**）。
* **发出有效载荷**：
```text
[F: ◊₍5₎=k8s/deployment.yaml]
⺏ 应用程序→生产集群
◊₍5₎ [27L]
```
### 4. 调试 Python 机器学习预处理管道
* **原始上下文**：`1,925 字符`（包括 `preprocess.py` 内容、scikit-learn 导入和活动诊断信息）。
* **压缩输出**：`249 字符`（**7.7 倍压缩，节省 87%**）。
* **发出有效载荷**：
```text
[F: ◇₍6₎=src/pipeline/preprocess.py]
⺃ 数据预处理管道
◇₍6₎ᵖ [imp:2 𝒞:1 37L]
◇₍6₎:18 ⚠⚠unused 未使用的导入 train_test_split
◇₍6₎:25 ⚠ FutureWarning: DataFrame.fillna with 'method' 已弃用
[T1:U:管道崩溃] [T2:A:⺎▼]
```
### 📊 会话聚合效率（摊余成本）
* **摊余月节省（Claude Sonnet @ $3/M 标记）**：为单个开发人员在仅 50 请求/天的情况下节省 **$5.85/月**，团队可指数级扩展。
## 🧠 高级功能：全息折叠、意图差异和历史衰减
GlyphCompress 包括针对大型、多轮和多文件的开发人员工作流的先进上下文优化层。
### 1. 全息上下文折叠（v1.15.0）
全息折叠分析提示中的多个文件之间的导入关系。 与其发送每个文件重复的、模板化的导入，不如将它们提取到一个单独的 `Base` 共享头部，并将文件表示为结构化叠加层：
* **工作原理**：检测相互依赖并分组折叠共享导入的文件。
* **格式**：`⟦Base: import A | import B⟧ ↷ [◈Ref struct ↷ ◈Ref struct]`
* **节省**：在多文件上下文中减少高达 40% 的字符/标记。
* **激活**：
* **CLI**：`--folding`（或 `--holographic-folding`）
* **VS Code**：在设置中切换 `"glyphCompress.holographicFolding": true`。
> [!NOTE]
> 例如，在读取两个依赖的 React 组件文件时，中间件会提取公共的 React 导入并将它们的核心声明分组，以避免在重复的样板上进行 LLM 标记开销。
### 2. 生成式意图差异（v1.15.0）
生成式意图差异拦截 git/IDE 统一差异（通常非常冗余且昂贵），并将它们转换为结构化操作行的序列：
* **工作原理**：语法分析添加 (`+`) 和删除 (`-`) 块以总结添加/删除的类 (`▲𝒞` / `▼𝒞`)、函数 (`▲ƒ` / `▼ƒ`) 或包 (`▲📦` / `▼📦`)。
* **格式**：`⚡: ⊝₍1₎ ▼𝒞 OldClass | ⊝₍1₎ ▲𝒞 NewClass`（或 `⚡: ◈ ±LineCount` 表示非符号更改）。
* **节省**：在代码重构上下文中节省超过 80% 的标记。
* **激活**：
* **CLI**：`--intents`（或 `--intent-diffs`）
* **VS Code**：在设置中切换 `"glyphCompress.intentDiffs": true`。
> [!TIP]
> 此功能在使用 git diffs 时非常强大，适用于 Cline、RooCode 或 Cursor 聊天。引擎剥离了大量的 `+` 和 `-` 源代码行，仅发送重构的语义意图。
### 3. 注意力衰减压缩（ADC）（v1.14.0）
注意力衰减模拟多轮聊天记录中的人类记忆。随着对话的进行，较旧的消息会逐渐压缩成密集的 Emoji 标记的摘要，同时保持最新的回合以高保真度的全文：
* **工作原理**：将聊天历史记录分为 4 个衰减区域，基于与当前回合的距离：
* **热区**（回合 1-2）：100% 全文。
* **暖区**（回合 3-4）：轻微压缩。
* **冷区**（回合 5-6）：语义摘要。
* **冷冻区**（回合 7+）：高度压缩的语言标记的要点摘要。
* **节省**：防止聊天历史记录标记爆炸，实现近乎无限的对话长度。
* **激活**：
* **CLI**：`--decay`（或 `--experimental-decay`）
* **VS Code**：在设置中切换 `"glyphCompress.experimentalDecay": true`。
### 4. 团队代码簿注册表（v1.18.0）
每个会话的动态字典（及其跨会话缓存）是每个机器的 - 如果没有这个，两个团队成员独立地在同一个仓库工作，会学习不同的 `§N` 字符分配给相同的标识符，这既浪费了学习效果，又破坏了组织范围内的提供商侧提示缓存（隐含缓存键控以字节相同的字节前缀，这需要相同的单词在每个地方产生相同的字符）：
* **工作原理**：`glyphcompress.team.json` - 一个小的、可提交的 git 文件在工作区根目录（与 gitignored `.glyphcompress/` 缓存目录不同）- 按优先级顺序列出字典条目。每个 `GlyphCompressor` 实例在任何会话学习发生之前都会从中加载 `§N` 索引。
* **工作流**：`glyph-compress team-codebook sync` 将此机器的本地学习字典提升到共享文件中；将其提交到 git，以便整个团队（和每个 CLI/MCP/代理入口点）为相同的单词分配相同的字符。
* **激活**：`glyphcompress.team.json` 存在于工作区根目录时自动 - 无需标志。 使用 `glyph-compress team-codebook show` 检视。
***
### v1.25.0 中的新增功能（OpenAI/Gemini 的缓存稳定代码簿）
在调查 v1.24.0 的 Anthropic 代理错误时发现：为 OpenAI/Gemini 注入的代码簿头部被有效载荷过滤器过滤 - 它只列出特定消息实际使用的 DOM/TECH/SYM/MOD 字符，因此它因请求而异，永远不能成为这些提供商的自动、隐含提示缓存的稳定前缀（需要字节相同的首字母令牌）。 现有的 `test/cache-prefix-stability.js` 套件的名称承诺将其锁定，但其实际检查始终只比较系统消息的第一行（一个永远不会更改的字面量），而是完整的代码簿块 - 这就是为什么此功能未被发现。
1. **混合缓存稳定代码簿**，镜像现有的 Anthropic `cache_control` 首轮-vs-多轮拆分（`useStructuredSystem`）：一旦会话有助手历史记录，`GlyphCompressor` 切换到 OpenAI/Gemini/local 到完整、无条件的代码簿（每次字节相同），动态字典行移动到单独的 `[GLYPH DYNAMIC]` 块，位于系统文本之后，而不是嵌入在可缓存块中。首轮请求没有缓存的先前回合，因此它保留较小的过滤头部。
2. **两层回退，不是一刀切**：较大的稳定头部（~350 个额外标记）仅在聚合跨回合时才有回报 - 对单个调用的标记计数不可见 - 因此，如果它会将特定消息翻转为 GlyphCompress 现有的净负回退消息，则该消息会自动重试使用较小的过滤代码簿（仍然在其自身 v1.25. 优点上净正数），而不是失去其他所有节省（压缩、动态字典、注释剥离）以及它。
3. `test/cache-prefix-stability.js` 获得了真正的多轮断言：整个代码簿块（而不仅仅是第 1 行）在缓存稳定模式下字节相同，动态行在外部隔离，消息太小而无法承担更大的头部，以及确认 `raw`/Anthropic 不受影响。 验证这些新测试实际上失败了 pre-fix 代码，然后修复它。
### v1.24.0 中的新增功能（Anthropic 代理桥 - 关键修复）
**发送到 Anthropic 目标的所有实际请求（`targetApiUrl = https://api.anthropic.com`）都会被破坏并被真实 API 拒绝。** 所有记录的 IDE 集成（Cursor、Cline/RooCode、Continue.dev）都将客户端配置为“OpenAI 兼容”模式，因此代理始终接收 OpenAI 形状的聊天/补全请求，而不管实际的上游 - 这已经正确地处理了 OpenAI 本身和 Gemini（它提供了一个真正的 OpenAI 兼容端点），在 Anthropic 上并非如此。`api.anthropic.com` 不接受 OpenAI 请求形状：系统提示必须是顶级 `system` 字段，而不是 `role: "system"` 消息；身份验证为 `x-api-key` + `anthropic-version`，而不是 `Authorization: Bearer`；端点为 `/v1/messages`，而不是 `/v1/chat/completions`。除此之外，GlyphCompress 的压缩路径插入了一个 *非法的* `role: "system"` 消息到 `messages` 中，当没有消息时。直接重现，而不是信任现有的代理烟雾测试，它只检查了转发的状态代码和 URL，而不是请求形状，因此未发现它。
1. **新的 Anthropic 代理桥** (`src/anthropic-bridge.js`)：将 OpenAI 形状的请求转换为 Anthropic 原生消息 API 形状，并将响应转换回，两者都支持非流式 JSON 和流式 SSE。重用与 `wrapAnthropic()` 已经依赖的相同压缩和 `cache_control` 逻辑，因此代理用户现在获得与直接 SDK 包装器用户相同的缓存稳定结构化系统块 - 以前只能通过直接导入 `wrapAnthropic()` 在 Node 代码中实现，从未通过代理。
2. **已知限制**（有文档记录，但此处未尝试）：多模态图像内容用可见文本占位符标记，而不是翻译为 Anthropic 的图像块；OpenAI 工具结果 (`role: "tool"`) 消息强制转换为标记的 `user` 消息，而不是正确的 `tool_result` 内容块；流式工具调用参数增量未翻译（非流式工具调用已完全翻译，包括响应中的 `tool_calls` 字段）。
3. **测试**：`test/anthropic-bridge.js`（18 个测试）涵盖直接翻译函数以及实际的端到端代理往返（模拟的外部 HTTPS，真实服务器，流和非流）- 包括检查 OpenAI/Gemini 目标完全不受影响的测试。现有的 `test/proxy.js` Anthropic 烟雾测试也被加强；它以前根本没有断言转发请求形状，这是如何让这个错误被发现。验证这些测试实际上捕获了原始错误，通过恢复修复并确认预期的失败，然后再恢复。
### v1.23.0 中的新增功能（自适应工作区内存）
1. **增量代码簿构建**：`buildWorkspaceCodebook()` 不再为每次调用重新解析每个工作区文件。当文件的修改时间自上次构建以来未更改时，其符号/导入/诊断信息将从保存的代码簿中重用，而不是重新提取；只有更改的文件将被重新扫描。返回的代码簿现在报告 `incrementalStats: { reused, rescanned, total }`。传递 `{ incremental: false }` 以强制完全重新扫描。
2. **使用权重的使用相关性**：`recordFileUsage(rootDir, filePaths)` 记录某个文件实际上已被选择并发送到任务；`selectRelevantFiles()`/上下文路由器现在在基于关键字的评分/意图之上添加一个衰减的使用提升（14 天的半衰期，最高可达上限），因此以前证明有用的文件可以优于冷的关键字匹配。`GlyphCompressor.routeAndCompress()` 为每个它选择的每个文件自动调用此操作。
3. **修复了在测试此功能时发现的实际漏洞**：`recordFileUsage()` 最初在没有代码簿持久保存到磁盘时静默无效（只有 CLI 的 `inspect` 命令执行此操作）- 意味着使用情况跟踪在 `routeAndCompress()` 第一次运行时在新工作区中默默地失效。它现在在没有代码簿的情况下动态构建并保存代码簿，以便为下一次调用播种增量缓存。
4. 新的 `test/adaptive-workspace-memory.js`（10 个测试）涵盖增量重用/重新扫描行为、使用情况持久性和衰减，以及 `routeAndCompress()` 实际记录使用情况端到端。
### 新增功能 v1.21.2（VS Code 市场列表修复）
`vscode-ext/` 目录下缺少 `README.md` 文件，因此 Marketplace 的“概述”选项卡显示“尚未由发布者输入概述”——`@vscode/vsce package` 从扩展程序的根目录读取 `README.md` 以填充该页面，但它根本不存在。同时还发现，在 Marketplace 上实际发布的最新版本是 `1.12.0`，落后于当前仓库的许多功能和版本——描述文本在某些时候通过 Marketplace 管理门户手动编辑过，与新软件包版本的发布无关，这使得列表看起来比实际更新。已添加 `vscode-ext/README.md` 和 `vscode-ext/package.json` 中的 `repository` 字段（删除了不再必要的 `--allow-missing-repository` 打包标志）。
### 新增功能 v1.21.1（关键打包修复）
**发布的 VS Code 扩展程序从 v1.17.0 开始就已损坏。** `vscode-ext/glyph-middleware.cjs` 需要 `../src/workspace-intelligence.cjs` 和 `../src/team-codebook.cjs`——这些路径在当前仓库中解析正常，但 `@vscode/vsce package` 只包含 `vscode-ext/` 目录中的文件，因此自 Context Router/Team Codebook Registry 发布以来（v1.17.0-v1.21.0）的每个打包的 VSIX 在尝试压缩任何内容时都会因 `MODULE_NOT_FOUND` 而崩溃。通过提取一个实际安装的 VSIX 并从中启动代理来捕获 - 每个先前的测试都需要通过仓库相对路径查找文件，这从来不会实际测试打包布局。**类似的风险也存在于 npm 包中**（本修复引入的本地 `vscode-ext/` 副本最初未出现在 `package.json` 的 `files` 允许列表中），并在同一提交中修复。
新增了两个回归测试套件来永久锁定此修复：`test/extension.js` 现在扫描每个打包的 `.cjs` 文件中是否有任何 `require("../...")` 转义到 `vscode-ext/` 外部的情况，而 `test/npm-pack-smoke.js` 运行真正的 `npm pack`，提取实际的 tarball，并从中需要发布的入口点——两者都在信任修复程序之前故意重现了原始故障。
### 新增功能 v1.21.0（提供信任 & 用户体验）
1. **代码块压缩现在也考虑实际标记**: 与 v1.17.0 中发现的所有 28 个 `TECH_GLYPHS` 在 OpenAI 上丢失的相同度量标准应用于 `_minifySyntax()` 的关键字到字形替换在代码块内部（`return` → `→`, `function` → `ƒ`, `const` → `◇`, `public` → `+`, ...）。结果：**测试的所有 33 个关键字/字形对也是 OpenAI 上的净标记损失** - 普通代码关键字已经是单个 BPE 标记（代码是预训练数据的很大一部分），因此用 1-4 个标记的 Unicode 字形替换它们永远不会赢。技术名称和代码关键字压缩现在都在 `openai` 提供商上跳过测量的损失替换 - 注释移除、空白行移除和缩进到制表符压缩（不是字形替换）仍然适用，并且仍然节省实际标记。
2. **信任警告** (`buildTrustWarnings()`, `sourceMap.trustWarnings`) : 关于当前信任策略组合实际允许的纯语言、事实导出警告 - 例如“有损信任策略：代码摘要和冗余剥离不可逆转。” 每个警告严格从信任配置文件自己的现有 `可逆`/`redacts`/`lossy`/`allows.*` 标志导出，而不是关于模型行为的新声明。在 CLI `--explain`、VS Code 扩展程序的输出通道（启动时和每次压缩后）和 `sourceMap.trustWarnings` 中均可见，供任何使用者参考。
3. **修复了在添加信任警告 API 时发现的实际导出错误**: `vscode-ext/glyph-middleware.js` 手动维护第二个手动 `module.exports = {...}` 块，供 CJS 使用者使用，与其 `export {...}` 语句（esbuild 自己的自动生成的 CJS 导出是无用代码）一起。一个新导出的添加没有其他列表时，会在 `require()` 使用者中默默地产生 `undefined` - 这正是与此版本中的 `buildTrustWarnings` 一起发布的，立即被一个现在比较两个列表的新回归测试捕获。
### 新增功能 v1.20.0（表达式级源映射 & 真实缩进错误修复）
1. **表达式级 AST 跨度**: `sourceMap.ast` 现在使用箭头函数、函数调用（具有与声明不同的跨度）、解构、异步/等待和异常处理（try/catch/throw/finally）跟踪代码块内部的标记 - 不仅仅是顶级导入/导出/函数/类声明。新增语言覆盖：Ruby、Swift、Kotlin 和 PHP，它们已经有 `TECH_GLYPHS` 条目，但没有标记提取。
2. **修复了在验证跨度保真度时发现的两个实际预先存在的错误**: 在管道中的两个独立位置，空格标准化在整个消息上运行，包括在 ```fenced``` 代码块内，导致 4 空格和 8 空格的嵌套缩进都无声地折叠到同一个空格（或单个制表符），使代码结构在每个压缩级别上都变平 - 不仅仅是激进/超级压缩 - 并且对于像 Python 这样对缩进敏感的语言，改变了代码的实际作用。两个传递现在完全跳过代码围栏内容。
3. **`test/ast-spans.js`**: 每个 AST 标记的跨度必须切片回到与其自己的文本完全相同的原始输入 - 这就是上面捕获错误的测试。
### 新增功能 v1.19.0（结构化诊断 & Git 差异感知路由）
1. **结构化诊断**: 每个代理/CLI 日志条目现在都带有 ISO 时间戳和一致的编辑功能，适用于所有接收器（控制台、VS Code `outputChannel` 和一个新的可选 JSONL 文件接收器，通过 `--log-file`）。以前，编辑功能只在单个调用站点（上游错误正文）运行，因此其他日志行可能会无编辑地泄漏秘密。每个请求现在还记录更丰富的信任/路由诊断信息：隐私防火墙、衰减/折叠/意图差异标志、动态词典和文件索引大小、是否加载了团队代码簿以及净负fallback 是否触发。
2. **`routeAndCompress(query, { gitDiffOnly: true })`**: 限制上下文路由器仅限于 git 分阶段/未分阶段文件，用于“审查我所更改的内容”工作流 - CLI：`glyph-compress route <query> --git-diff-only`。
3. **修复了在此工作期间发现的实际构建漂移错误**: `vscode-ext/proxy.js` 是 `src/proxy.js` 的手动维护的 CommonJS 副本，已与其不同步（缺少多个选项和仪表板/统计端点）。它现在从与 CJS 构建其余部分相同的源生成，因此它不会再次漂移 - 并且在之前或之后都没有测试覆盖， 现在由 CJS 构建烟雾测试覆盖。
### 新增功能 v1.18.0（团队代码簿注册表）
1. **团队代码簿注册表**: `glyphcompress.team.json`（git 可提交，在工作区根目录）允许团队共享优先顺序动态词典，以便每个团队成员的 `GlyphCompressor` - 通过 CLI、MCP 服务器、VS Code 扩展或代理 - 将相同的 `§N` 字形分配给相同的重复标识符，而不是每个机器学习其自己的独立、不兼容的分配。新 CLI：`glyph-compress team-codebook show|sync`。请参阅上面的 [团队代码簿注册表](#4-team-codebook-registry-v1180)。
### 新增功能 v1.17.0（MCP 服务器、上下文路由器 & 真实标记经济）
1. **MCP 服务器**: `npx glyph-compress-mcp` 将 GlyphCompress 公开为 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器 - `compress_text`、`compress_file`、`route_context` 和 `get_codebook` 工具，可从 Claude Code (`claude mcp add glyph-compress -- npx glyph-compress-mcp`)、Claude Desktop 和任何其他 MCP 兼容的客户端在没有 IDE 特定集成工作的情况下使用。有关详细信息，请参阅下面的 [MCP 服务器](#-mcp-server-claude-code-claude-desktop--other-mcp-clients)。
2. **上下文路由器**: `GlyphCompressor.routeAndCompress(query, options)` 和 CLI `glyph-compress route <query> [--budget] [--max-files] [--git-diff-only]` 按相关性对工作区文件进行排名，并压缩尽可能多的文件以适应标记预算，而不是手动选择要发送的文件。`gitDiffOnly` 限制候选文件为 git 分阶段/未分阶段文件，用于“审查我所更改的内容”工作流。报告 `selectedFiles`/`excludedFiles`（带有分数、标记成本和排除原因）以及每个文件的 `sourceMap` 以便审计。构建此功能时发现并修复了一个实际的预先存在的错误：TODO/FIXME/HACK 诊断检测正则表达式没有词边界，匹配“Hacker News”中的“HACK”，提高了不相关的营销文档而不是实际相关源文件的权重。
3. **实际标记 TECH_GLYPHS 经济**: 扩展 `npm run calibrate:tokenizer` 以比较每个字形与实际替换它的单词（而不仅仅是其孤立成本），使用实际的 OpenAI 标记器。结果：**所有 28 个 `TECH_GLYPHS` 都是净标记损失** - 通用技术名称已经是 1-2 个 BPE 标记，而替换它们的 Unicode 字形成本相同或更高（最坏情况：“express”1 标记 vs. 其字形 5）。技术名称替换现在在 `openai` 提供商上永远不会触发，如果它会损失标记（测量的成本表，而不是启发式）；`raw` 模式保持无条件替换以进行演示/字符级报告。
### 新增功能 v1.16.0（代码簿完整性 & 自适应级别）
此版本修复了压缩引擎审核期间发现的实际正确性漏洞，然后在此基础上构建了三个新功能。
**正确性修复：**
1. **动态词典符号冲突修复**: 会话使用的动态词典从希腊/ Cyrillic 字母池中提取，这些字母与保留的 `TECH_GLYPHS` 符号重叠 - `α` 既是第一个动态词典赋值 **又是** “Agent”的固定字形，因此任何具有重复单词和任何提及“Agent”的会话都会产生一个模糊的字形，模型无法可靠地解码。动态条目现在是 `§N` 引用（与文件引用（如 `◈₍1₎`）相同的索引引用约定），无冲突且无固定符号池上限。
2. **未文档化的技术字形修复**: 13 个 `TECH_GLYPHS` 条目（Java、C#、Swift、Ruby、Angular、Svelte、Django、Rails、Express、FastAPI、MySQL、MongoDB、“prompt”）可能出现在压缩输出中，但从未在发送给模型的代码簿中记录。代码簿现在直接从 `TECH_GLYPHS` 生成，因此它不会与压缩器实际发出的内容不同步。遗留 `compressor.js` 引擎（由 `npm run demo` 使用）中也修复了相同类别的错误（14/33 已记录）。
3. **CLI 代码簿完整性修复**: `getCodebookPrompt()` - `npx glyph-compress <file>` 的代码簿源 - 曾经不包括动态词典的 `DYN:` 定义，因此 CLI 输出可能包含 `§N` 字形，而没有任何定义附加在打印输出中。它现在始终包括它生成的每个动态条目的定义。
4. **动态词典经济修复**: 只在有效载荷中出现一次的单词仍被视为“节省”，尽管一次出现无法摊销传输其自身 `word=§N` 定义的成本。词典现在要求一个单词至少重复两次，并在估算节省时扣除定义成本。
5. **`compressText()` 净负fallback 添加**: `compressMessages()` 已经在测量净负时恢复到原始有效载荷；`compressText()`（由 CLI 和独立 SDK 调用）没有等效的安全网，可以默默地返回输出，其成本 **高于输入**。它现在共享相同的 fallback（适用于除 `raw` 之外的所有提供者，后者故意报告无防护的字符级差异）。
**新增功能：**
6. **自动级别选择（`level: 'auto'`）**: 传递 `level: 'auto'`（或 CLI 上的 `--level auto`）并且 GlyphCompress 从内容信号中为每个请求选取 `light`/`standard`/`aggressive`/`ultra` - 文本长度和代码密度 - 而不是固定的默认值。`selectCompressionLevel()` 也直接导出以供编程使用。
7. **标记器校准的字形成本**: `npm run calibrate:tokenizer` 使用 OpenAI 的 `cl100k_base` 和 `o200k_base` 标记器（通过 `js-tiktoken` 开发依赖）测量每个字形的实际标记成本，而不是仅依赖固定启发式，并标记任何实际成本较差的字形。
8. **代码簿完整性测试套件**: `npm run test:codebook` 确定性地运行 `TECH_GLYPHS`/`DOMAIN_GLYPHS` 条目和动态词典的每一个，并断言每个发出的字形都在随它一起发送的代码簿中有文档记录 - 这个测试本来可以自动捕获修复 #1-#3。
9. **缓存前缀稳定性测试套件**: `npm run test:cache-prefix` 锁定注入的代码簿对于相同的内容是字节相同的（OpenAI/Gemini 隐含提示缓存所需），并且 Anthropic 的 `cache_control`-tagged 稳定块永远不会嵌入请求特定的动态词典条目。
> [!NOTE]
> 下面的聚合基准数字由于修复 #4 发生了轻微变化（25% → 22% 真正的节省）- 旧数字包括来自一次出现替换的节省，这些节省从来不是经济现实的。`ultra` 层面的代码密集内容节省不受影响。
### v1.8.0（安全压缩信任策略）
1. **显式信任策略**：添加了 `lossless`、`reversible`、`privacy` 和 `lossy` 信任策略，允许消费者选择允许哪些转换。
2. **转换控制**：`lossless` 保留用户文本，`reversible` 阻止代码压缩/摘要，`privacy` 启用删除，`lossy` 允许激进/极端摘要。
3. **信任元数据**：源映射现在包括 `sourceMap.trustPolicy` 和 `sourceMap.trust`，以便下游工具可以审计压缩保证。
4. **CLI 信任标志**：添加了 `--trust <policy>` / `--policy <policy>` 和所选信任策略的解释输出。
5. **VS Code 信任设置**：在扩展设置中添加了 `glyphCompress.trustPolicy`，并将其连接到压缩器激活。
### 🔥 v1.7.0（提供者感知压缩配置文件）
1. **提供者压缩配置文件**：为 `raw`、`openai`、`anthropic`、`gemini` 和 `local` 模型工作流添加了特定于提供者的压缩配置文件。
2. **估计器引导的动态字典**：动态字典阈值现在适应每个提供者，以便 OpenAI/local 配置文件可以更紧凑，而 Anthropic 保持更稳定的缓存。
3. **源映射配置文件元数据**：源映射现在包括 `provider` 和 `profile` 元数据，动态条目记录了选择它们的提供者策略。
4. **CLI 提供者标志**：添加了 `--provider <provider>`，以便命令行压缩可以估计和配置文件输出，以适应 OpenAI、Anthropic、Gemini 兼容、本地或原始文本目标。
5. **类型化的公共配置文件**：TypeScript 声明现在公开了 `ProviderCompressionProfile` 和 `PROVIDER_COMPRESSION_PROFILES`，以便下游工具使用。
### 🔥 v1.6.0（类似 AST 的代码块源跨度）
1. **代码块令牌映射**：压缩和摘要的代码块现在包括 `tokens` 元数据，用于结构化源令牌。
2. **顶级 AST 映射**：添加了 `sourceMap.ast`，以便下游工具可以在不遍历每个代码块的情况下检查结构化代码跨度。
3. **语言感知令牌**：跟踪 JS/TS、Python、Rust、Go、Java/C# 和 C/C++ 家族的导入、导出、函数、类、声明、返回/产量、包/使用/使用、可见性和类型标记。
4. **类型化的 AST 跨度**：TypeScript 声明现在包括 `GlyphAstTokenSpan`，`getReversibleDictionaries()` 公开了 `ast` 元数据。
5. **发布元数据**：更新了源映射、工作区代码簿、测试、README、路线图、问题模板、npm 元数据和 VS Code 扩展元数据，适用于 v1.6.0。
### 🔥 v1.5.0（隐私防火墙模式）
1. **选择加入隐私防火墙**：添加了 `privacyFirewall: true` / `privacy: true` 以在提示压缩之前删除机密和敏感标识符。
2. **安全删除占位符**：API 密钥、令牌、机密赋值、电子邮件、IP地址、AWS 密钥、GitHub 令牌、JWT 和持有者令牌被替换为稳定的占位符，例如 `⟦SECRET_ASSIGNMENT_1⟧`。
3. **非透露源映射**：添加了 `sourceMap.privacy` 条目，包含删除种类、标签、占位符、行/列跨度和短 SHA-256 哈希元数据，而不存储原始机密。
4. **CLI 隐私标志**：添加了 `--privacy`，以便命令行压缩可以在输出、剪贴板复制或源映射打印之前删除敏感值。
5. **发布元数据**：更新了源映射、工作区代码簿、测试、README、路线图、问题模板、npm 元数据和 VS Code 扩展元数据，适用于 v1.5.0。
### 🔥 v1.4.0（扩展和代理烟雾套件）
1. **VS Code 激活烟雾测试**：添加了一个模拟的 VS Code 主机套件，验证扩展激活达到就绪状态并注册每个贡献的命令。
2. **代理转发烟雾测试**：添加了一个本地代理套件，确认聊天负载压缩、glyph 协议注入、上游路径保留和纠正的 `content-length` 转发。
3. **扩展 CJS 加载强化**：VS Code 扩展现在直接加载 CommonJS 中间件工件，防止激活路径模块格式漂移。
4. **聚焦测试脚本**：添加了 `test:extension` 和 `test:proxy`，并将两者连接到 `npm test` 和发布验证。
5. **发布元数据**：更新了源映射、工作区代码簿、测试、README、路线图、问题模板、npm 元数据和 VS Code 扩展元数据，适用于 v1.4.0。
### 🔥 v1.3.0（语义源映射跨度）
1. **行/列源跨度**：源映射条目现在包括 `span.start` 和 `span.end`，具有行、列和偏移元数据，用于跟踪替换。
2. **符号级映射**：添加了一个 `sourceMap.symbols` 数组，将生成的 glyphs 映射回其原始提示、技术名称、文件路径、诊断、动态字典或代码块源。
3. **可逆跨度访问**：`getReversibleDictionaries()` 现在公开了 `symbols` 以及文件、动态条目、诊断和代码块。
4. **类型化的源映射**：TypeScript 声明现在包括 `GlyphSourcePosition`、`GlyphSourceSpan` 和 `GlyphSymbolSpan`。
5. **发布元数据**：更新了源映射、工作区代码簿、测试、README、路线图和 VS Code 扩展元数据，适用于 v1.3.0。
### 🔥 v1.2.0（提供者准确性和测试套件）
1. **提供者感知令牌估计**：添加了 OpenAI、Anthropic、Gemini 兼容、本地模型和原始文本估计器配置文件，以获得更现实的节省指标。
2. **公共估计器 API**：添加了 `estimateProviderTokens()`、`compareTokenEstimates()`、`normalizeProvider()` 和 `PROVIDER_TOKEN_PROFILES` 到稳定的包导出。
3. **分割测试套件**：添加了聚焦的 `test:unit`、`test:cli`、`test:workspace`、`test:metadata` 和 `test:integration` 脚本，`npm test` 运行完整的套件运行器。
4. **基准测试对齐**：基准测试现在使用提供者特定的估计来计算聊天负载，而不是单一的通用字符启发式。
5. **发布元数据**：更新了源映射、工作区代码簿、测试、README、路线图和 VS Code 扩展元数据，适用于 v1.2.0。
### 🔥 v1.1.1（许可强化）
1. **AGPL-3.0-only 元数据**：根包、VS Code 扩展和包锁定元数据现在使用更精确的 `AGPL-3.0-only` SPDX 标识符。
2. **商业许可门控**：添加了明确的商业使用语言，阐明专有、托管、SaaS、嵌入式、OEM、市场或私有再分发权需要单独的书面协议。
3. **NOTICE 和许可政策**：添加了 `NOTICE` 和 `docs/licensing.md`，以便 npm、GitHub 和企业审查者可以直接看到许可立场。
4. **贡献者保障**：添加了贡献许可条款和 PR 检查清单，以保护未来贡献的双许可模型。
### 🔥 v1.1.0（贡献者和发布卫生）
1. **贡献者指南**：添加了 `CONTRIBUTING.md`，包含设置、测试、文档和 API 稳定性期望。
2. **发布文档**：添加了 `docs/release.md` 和 `docs/architecture.md`，适用于维护者和技术审查者。
3. **GitHub 模板**：添加了用于错误、功能、提供者兼容性、基准测试提交和 PR 检查清单的问题模板。
4. **链接检查**：添加了 `npm run check:links` 并将其连接到 CI。
5. **发布元数据**：更新了测试和包元数据，以验证贡献者卫生资产。
### 🔥 v1.0.0（稳定平台）
1. **稳定公共 API**：`GlyphCompressor`、提供者包装器、源映射、工作区智能导出、CLI 命令和 VS Code 设置被记录为稳定的 `1.x` 平台表面。
2. **TypeScript 声明**：添加了包级声明，适用于中间件、源映射、工作区代码簿、意图检测和存储库医生 API。
3. **CI 和打包验证**：添加了 GitHub Actions 覆盖，用于 Node LTS 测试、基准测试、npm 包干燥运行和 VS Code 扩展打包。
4. **正式治理文档**：添加了安全、隐私和企业部署文档，用于生产采用。
5. **精简 npm 包**：添加了明确的包允许列表，以便 npm 发布包括运行时、文档、类型和扩展文件，而不包含临时工件。
### 🔥 v0.9.0（工作区智能）
1. **持久工作区代码簿**：添加了 `glyph-compress inspect`，以扫描支持的项目文件并写入 `.glyphcompress/codebook.json`，包含符号、导入、诊断、所有者和 git 状态。
2. **意图检测**：检测常见工作流，例如修复错误、审查差异、实现功能、解释架构、编写测试和优化性能。
3. **相关文件选择**：为查询排名工作区文件，以便压缩上下文可以关注最可能相关的文件。
4. **存储库健康命令**：添加了 `glyph-compress doctor` 和 `glyph-compress benchmark`，用于存储库准备和 CLI 的信任指标。
### 🔥 v0.8.0（可逆压缩和源映射）
1. **源映射 API**：`compressText()` 和 `compressMessages()` 现在返回一个 `sourceMap`，包含文件引用、动态字典条目、诊断、代码块和替换。
2. **可逆字典**：添加了 `getReversibleDictionaries()`，用于文件路径、重复标识符、诊断和摘要代码块。
3. **CLI 源映射**：添加了 `glyph-compress --source-map`，以打印源映射 JSON 以及压缩输出。
4. **往返覆盖**：添加了源映射、动态字典、CommonJS 对齐和 CLI 源映射输出的集成测试。
### 🔥 v0.7.0（信任和度量）
1. **基准测试工具**：添加了 `npm run benchmark`，以比较原始和压缩负载，跨原始文本、OpenAI、Anthropic、Gemini 兼容和 ultra 模式固定装置。
2. **信任指标**：基准测试报告负载比率、令牌节省、上下文保真度评分、编辑成功代理和幻觉文件引用。
3. **CLI 解释模式**：添加了 `glyph-compress --explain`，以显示级别行为、索引文件引用、动态字典条目和检测到的压缩更改。
4. **固定装置覆盖**：将 CLI 信任功能覆盖添加到集成套件中。
### 🔥 v0.6.1（打包和 VS Code 强化）
1. **根 API 对齐**：记录的 `GlyphCompressor`、`wrapOpenAI` 和 `wrapAnthropic` 导入现在从包根导出。
2. **CommonJS 入口点**：添加了缺失的 CommonJS 包入口点，以便 `require('glyph-compress')` 可用于 CJS 消费者。
3. **VS Code 代理配置**：扩展代理现在尊重 `glyphCompress.targetApiUrl`，而不是使用硬编码的提供者 URL。
4. **选择加入工作区规则**：自动写入 `.cursorrules` 和 `.github/copilot-instructions.md` 在 `glyphCompress.autoUpdateWorkspaceRules` 后面。
### 📏 基准测试快照（v1.25.0）
`npm run benchmark` 目前报告聚合负载压缩比率为 **1.3x**，**22% 真正令牌节省**，**100% 上下文保真度评分**，**100% 编辑成功代理** 和 **0 幻觉文件引用**，跨代表性固定装置。这些数字使用 Unicode 令牌惩罚和每个 glyph 的盈亏平衡逻辑进行校准 - 每个报告的节省都是真正的净正令牌减少。在 OpenAI 上禁用 `TECH_GLYPHS` 替代，当它明显丢失令牌时（参见上面的“新增 v1.17.0”），并没有改变这些固定装置的数字 - 它消除了一个系统的隐藏浪费源，没有观察到的缺点，而是用衡量的节省来权衡它。
### 🧪 现实基准测试笔记
`npm run benchmark:realistic` 衡量四个行为，而固定装置基准测试本身无法捕捉：
1. **现实存储库语料库压缩**：在 `README.md`、`ROADMAP.md` 和核心运行时源等文件上。
2. **聊天负载开销**：在 OpenAI 和 Anthropic 样式请求中注入 glyph 代码簿后。
3. **多轮聊天摊销**：跨累积 IDE 样式对话。
4. **企业名义 IDE 用法**：跨专业工作流，例如 PR 审查、事件响应、测试规划和发布准备。
5. **本地吞吐量和延迟**：在重复压缩负载下。
当前现实基准测试显示出比以下合成固定装置表格更细致入微的画面：
- 原始存储库文件在 `light`、`standard` 和 `aggressive` 下现在接近收支平衡（大约 **0.9x-1.0x**）在典型的散文和代码文档上。自 v1.16.0 起，动态字典需要一个单词重复至少两次，并考虑传输其自身定义的成本，因此不再用从未真正为自己付费的单一出现替换来膨胀这个数字。
- `ultra` 仍然是具有真正结构节省的代码密集型文件（最高可达 **1.2x**，适用于此存储库的源代码），但并非普遍 - 密集的单文件散文/代码混合文件仍可能略微为负。
- **用户消息本身** 通常可以很好地压缩聊天提示。
- **完整首轮聊天负载** 仍然可能由于注入的代码簿超过用户消息节省而变得更糟糕。
- **累积多轮负载** 现在使用单独测量，因此您可以查看重复回合是否开始摊销代码簿或继续承载净开销。
- 新的 **企业名义使用** 部分报告了加权专业 IDE 摘要。在当前基准测试中，OpenAI 的加权完整负载和隔离用户消息节省都约为 **收支平衡（~0%）**，在该固定装置集上 - 代码簿开销和体内节省在很大程度上相互抵消。
- Anthropic 现在使用 **混合包装策略**：第一轮请求保持 `system` 轻量级，而多轮转录在存在助理历史时切换到结构化可缓存块。
- Anthropic 导向部分包括传输的 **payloadSaved** 指标和 **缓存调整估计**。在当前基准测试中，Anthropic 在加权传输负载上仍然略微为负，约为 **-5%**，而缓存调整加权估计（考虑 `cache_control` 重用系统块和最大用户块）为正，约为 **28%**。这是基准估计，而不是计费保证。
将 `npm run benchmark` 用作稳定的回归基准测试，将 `npm run benchmark:realistic` 用于更诚实的存储库规模和聊天负载行为估计。
### 🔥 v0.6.0（项目“罗塞塔”）
1. **自适应负载字典（APD）**：实时分析术语频率，并将消耗的令牌字符串（类、函数、变量）映射到动态 Unicode“罗塞塔石”上。
2. **语义上下文省略（黑屏算法）**：智能分析用户意图（例如，“修复”、“部署”）。新的 `_elideIrrelevantContext` 函数会删除大量负载中不相关函数的正文，以保留结构签名，同时减少令牌噪声。
3. **Anthropic 的提示缓存**：在上下文中最重的块（字典和文件）中自动注入 `cache_control: { type: 'ephemeral' }`，以最小化 Claude 用户的重复令牌成本和延迟。
4. **缩进最小化**：在最终压缩之前，将空格转换为制表符或自动剥离它们，以降低结构字节和令牌计数。
### ⚡️ 之前的亮点（v0.5.x 及以下）
1. **工作区压缩（VS Code 和 Antigravity）**：一个新的命令 `GlyphCompress: Compress Entire Workspace` 扫描您的整个项目，删除样板并在未保存的选项卡中生成单个语义映射（级别：Ultra）。非常适合将大型架构提供给 Claude 或 Antigravity。
2. **零命令透明代理**：从您的 IDE（Continue、Cursor、Cline）自动拦截 LLM API 调用。无需快捷方式或复制粘贴 - 所有操作都在 `localhost:8080` 上在后台透明地发生。
3. **通用语法最小化**：`aggressive` 压缩级别现在积极删除 **C 家族（JS、TS、C#、Java、C++、Go、Rust）、Python、Ruby、HTML 和 CSS** 的注释和空行，从而大幅减少令牌计数。
4. **谷歌 Gemini 原生支持**：代理无缝地将 OpenAI 格式的请求路由到 Gemini 的官方 `v1beta/openai` 兼容端点。
5. **持久遥测**：VS Code 扩展跟踪您的 *Lifetime Savings*，跨所有会话，准确显示您节省了多少个令牌（和美元）。
## 📊 基准测试
> [!NOTE]
> 下表衡量了 [现实会话展示](#-现实会话展示) 中展示的五个精选场景示例的原始字符 - 这是一个最佳情况的说明，展示了适合的负载可以实现什么，而不是典型或聚合结果。对于诚实报告的、提供者令牌感知的聚合，请参阅下面的 **基准测试快照（**`npm run benchmark`**：**1.3x比率，22％真实节省）** 和 [现实基准测试笔记](#-现实基准测试笔记)（`npm run benchmark:realistic`）用于现实存储库和聊天负载数字，更为谦逊，有时甚至在散文密集的内容上收支平衡或为负。
| 场景 | 原始 | 压缩 | 比率 | 节省 |
| --- | --- | --- | --- | --- |
| 修复 React 中的 TypeScript 错误 | 1734 字符 | 137 字符 | **12.7x** | 92% |
| 优化 API 端点 | 1999 字符 | 195 字符 | **10.3x** | 90% |
| 部署到 Kubernetes | 730 字符 | 84 字符 | **8.7x** | 88% |
| 调试 Python 机器学习管道 | 1925 字符 | 249 字符 | **7.7x** | 87% |
| 创建 React 表单 | 116 字符 | 33 字符 | **3.5x** | 72% |
| **平均值** | | | **9.3x** | **89%** |
## 🚀 使用方法：命令行（CLI）
你可以直接从终端运行 GlyphCompress 来快速压缩文件，以便与 ChatGPT 或 Claude 配合使用。
```bash
# 压缩 Python/Rust/JS 文件并复制到剪贴板
npx glyph-compress src/app.ts --level ultra --copy
# 查看内置帮助
npx glyph-compress --help
# 解释压缩过程中发生的变化
npx glyph-compress src/app.ts --level ultra --explain
# 打印可逆源映射元数据
npx glyph-compress src/app.ts --level ultra --source-map
# 在打印或复制压缩输出之前编辑机密
npx glyph-compress .env --privacy --source-map
# 构建持久的工作区代码簿并排名相关文件
npx glyph-compress inspect "修复 AuthenticationManager 错误"
# 检查存储库是否准备好使用 GlyphCompress 工作流
npx glyph-compress doctor
# 通过 CLI 运行基准测试指标
npx glyph-compress benchmark
```
### 命令行（CLI）：可用命令
```bash
npx glyph-compress [文件|命令] [选项]
```
| 命令 | 目的 | 示例 |
|---|---|---|
| `[文件]` | 压缩单个文件并打印压缩的有效载荷和共享代码簿。 | `npx glyph-compress src/app.ts` |
| `inspect [查询]` | 构建 `.glyphcompress/codebook.json`，检测意图，并排名相关的工作区文件。 | `npx glyph-compress inspect "修复身份验证错误"` |
| `doctor` | 检查存储库的准备情况以及可选的本地检查，检查已安装的扩展版本、Glyph 设置、代理配置和提供商凭据。 | `npx glyph-compress doctor` |
| `benchmark` | 从当前存储库运行基准测试工具。 | `npx glyph-compress benchmark` |
| `route <查询>` *(v1.17.0+)* | 上下文路由器：对查询的相关工作区文件进行排名并压缩，以便在令牌预算内尽可能多地容纳，而不是手动选择要发送的文件。 | `npx glyph-compress route "修复身份验证错误" --budget 2000` |
| `team-codebook show` *(v1.18.0+)* | 打印共享的团队代码簿（如果有）。 | `npx glyph-compress team-codebook show` |
| `team-codebook sync` *(v1.18.0+)* | 将此计算机的本地动态词典提升到 `glyphcompress.team.json`，供整个团队使用。 | `npx glyph-compress team-codebook sync` |
### 命令行（CLI）：选项
| 选项 | 值 | 目的 | 示例 |
|---|---|---|---|
| `-l, --level <level>` | `light`, `standard`, `aggressive`, `ultra`, `auto` | 选择压缩的激进程度，或让 `auto` 按请求选择。默认：`standard`。 | `npx glyph-compress src/app.ts --level ultra` |
| `-c, --copy` | 标志 | 将压缩的输出复制到系统剪贴板。 | `npx glyph-compress src/app.ts --copy` |
| `-x, --explain` | 标志 | 打印压缩、索引、保留或转换的内容。 | `npx glyph-compress src/app.ts --explain` |
| `--source-map` | 标志 | 打印可逆源映射 JSON，包括文件引用、动态条目、诊断、符号、AST/代码块元数据、私人元数据、提供商元数据和信任元数据。 | `npx glyph-compress src/app.ts --source-map` |
| `--privacy` | 标志 | 在压缩/输出之前编辑常见的机密和敏感标识符。 | `npx glyph-compress .env --privacy --source-map` |
| `--provider <provider>` | `raw`, `openai`, `anthropic`, `gemini`, `local` | 选择提供者感知的估计和压缩配置文件。默认：`raw`。 | `npx glyph-compress src/app.ts --provider openai --explain` |
| `--trust <policy>` | `lossless`, `reversible`, `privacy`, `lossy` | 选择允许的转换策略。默认：自动。 | `npx glyph-compress src/app.ts --trust reversible --source-map` |
| `--policy <policy>` | `lossless`, `reversible`, `privacy`, `lossy` | `--trust` 的别名。 | `npx glyph-compress src/app.ts --policy privacy` |
| `--decay` | 标志 | 在聊天历史记录消息上启用注意力衰减压缩。 | `npx glyph-compress --decay` |
| `--folding` | 标志 | 为重叠的相关文件启用全息上下文折叠。 | `npx glyph-compress --folding` |
| `--intents` | 标志 | 启用代码更改的生成意图差异压缩。 | `npx glyph-compress --intents` |
| `--budget <tokens>` | 整数 | `route` 命令的令牌预算。默认：`2000`。 | `npx glyph-compress route "修复错误" --budget 3000` |
| `--max-files <n>` | 整数 | `route` 命令的最大候选文件数。默认：`8`。 | `npx glyph-compress route "修复错误" --max-files 12` |
| `--git-diff-only` | 标志 | 仅限 `route` 命令仅限于 git 分阶段/未分阶段文件，用于“审查我所更改的内容”工作流。 | `npx glyph-compress route "审查我的更改" --git-diff-only` |
| `--json` | 标志 | 为 `inspect`、`doctor` 和 `route` 等支持的命令打印机器可读的 JSON。 | `npx glyph-compress inspect "审查差异" --json` |
| `-p, --proxy [port]` | 可选端口 | 启动零命令透明代理。默认端口：`8080`。 | `npx glyph-compress --proxy 8080` |
| `--log-file <path>` | 文件路径 | 将结构化、编辑的 JSONL 诊断信息从代理（时间戳、信任/路由元数据）追加到此文件。 | `npx glyph-compress --proxy --log-file ~/.glyphcompress/proxy.log` |
| `-h, --help` | 标志 | 显示内置的 CLI 帮助。 | `npx glyph-compress --help` |
### 命令行（CLI）：实用示例
```bash
# 标准文件压缩
npx glyph-compress README.md
# TypeScript 源文件的最大压缩
npx glyph-compress src/app.ts --level ultra
# 为 OpenAI 聊天负载提供商感知压缩
npx glyph-compress src/app.ts --provider openai --level standard --explain
# Anthropic/cache-stable 配置文件，具有可逆源映射元数据
npx glyph-compress src/app.ts --provider anthropic --trust reversible --source-map
# 精确保留模式：当您想要元数据而无需转换时很有用
npx glyph-compress src/app.ts --trust lossless --source-map
# 私人优先模式，用于可能包含机密或客户数据的文件
npx glyph-compress .env --privacy --trust privacy --source-map
# 用于自动化或 CI 脚本的 JSON 工作区检查
npx glyph-compress inspect "实现计费验证" --json
# JSON 格式的存储库就绪检查
npx glyph-compress doctor --json
# 启动本地 OpenAI 兼容压缩代理
npx glyph-compress --proxy 8080
```
**成本节省**：每天 50 个请求可节省约 200 美元/月，使用 Claude Sonnet。
## 🚀 快速入门
在 60 秒内使用 GlyphCompress。 我们强烈建议从 **自动（隐形）** 工作流开始：
### 1. 🤖 自动和透明工作流（推荐）
* **选项 A：零命令隐形代理（100% 自动）**
自动在后台压缩所有发出的 IDE 聊天负载，无需更改任何开发习惯：
1. 从 VS Code 市场安装 **GlyphCompress** 扩展（ID：`neolambo.glyph-compress`）。
2. 打开命令面板（`Ctrl+Shift+P` / `Cmd+Shift+P`）并运行：`GlyphCompress：启动零命令代理`。
3. 将您的 IDE（Cursor、Cline、Continue 等）配置为使用本地代理地址 `http://localhost:8080`（或 `http://localhost:8080/v1`）作为 OpenAI 基础 URL。 *（请参见下面的 [逐步 IDE 集成指南](#%E9%99%8C%E6%AD%A5%E6%AD%8C%E9%99%8F%E9%99%A4%E6%9C%BA%E9%99%8F%E9%A1%B5%E6%89%88%E5%90%88%E6%8C%AF%E6%89%B9%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%B4%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E5%90%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%96%B9%E6%B3%A8%E9%87%85%E6%8A%A5%E5%90%88%E6%8C%AF%E9%99%8F%E6%AD%A6%E5%B0%86%E6%89%88%E6%
### 3. 完成！
您不需要执行其他操作。当您的IDE向LLM发送大块代码时，代理会拦截JSON请求，压缩代码块，注入代码簿，并将高度压缩的请求转发到真正的LLM API。
## 🔌 MCP 服务器（Claude Code、Claude Desktop 等其他 MCP 客户端）
GlyphCompress 附带了一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io/) 服务器，因此任何兼容 MCP 的客户端都可以直接调用压缩功能 — 无需特定的 IDE 集成或代理配置。
### 暴露的工具
| 工具 | 功能 |
|---|---|
| `compress_text` | 压缩任意文本/上下文块。返回压缩文本、解码所需的代码簿和统计信息。 |
| `compress_file` | 从磁盘读取文件并压缩其内容。 |
| `route_context` | 上下文路由器：对查询的相关工作区文件进行排名，并压缩尽可能多的文件以适应 token 预算。 |
| `get_codebook` | 返回手动注入系统提示的 glyph 代码簿。 |
### 添加到 Claude Code
```bash
claude mcp add glyph-compress -- npx glyph-compress-mcp
```
### 添加到 Claude Desktop 或其他 MCP 客户端
将以下内容添加到客户端的 MCP 服务器配置中（对于 Claude Desktop，为 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"glyph-compress": {
"command": "npx",
"args": ["glyph-compress-mcp"]
}
}
}
```
### 直接运行
```bash
npx glyph-compress-mcp
```
服务器通过 stdio 使用官方 `@modelcontextprotocol/sdk` 进行通信。它除了依赖 MCP 客户端自己的传输之外，没有其他网络依赖 — 所有操作都在本地运行，与 CLI 和代理相同。
## 🔤 Glyph 协议
该系统基于 16 个 **基础部首**，它们编码了基本的语义维度：
```
领域： ◈ 前端 ◉ AI/ML ◊ DevOps ◆ 数据库
◇ 语言 ⊕ 自动 ⊗ 架构 ⊙ 移动
⊘ 云 ⊚ 数据 ⊛ 测试 ⊜ 后端
⊝ 安全 ⊞ 文档 ⊟ 性能 ⊠ 网络
操作： ▲ 创建 ▼ 分析 ► 测试 ◄ 监控
■ 文档 □ 连接 ▪ 部署 ▫ 优化
● 转换 ○ 保护
技术： ᵗ TypeScript ᵖ Python ʳ Rust ℜ React
ℕ Next.js 𝒟 Docker 𝒦 K8s ℙ Postgres
结构： ✗ 错误 ⚠ 警告 ∉ 类型不匹配 ∅ 未找到
→ 返回 ƒ 函数 𝒞 类 ◇ 状态 ⟿ 效果
```
### 压缩级别
| 级别 | 压缩内容 | 使用场景 |
|---|---|---|
| **轻度** | 提示模式、技术名称 | 低风险、最小更改 |
| **标准** | 提示模式、技术名称、文件路径、诊断信息、重复标识符 | 默认编码助手 payload |
| **激进** | 标准压缩加上代码块内的多语言语法压缩 | 调试或审查时代码结构仍然重要 |
| **极端** | 激进压缩加上架构代码摘要和冗余去除 | 当内部代码逻辑不那么重要时，最大化上下文节省 |
| **自动** *(v1.16.0+)* | 根据请求的内容长度和代码密度选择轻度/标准/激进/极端 | 您不想为每个 payload 手动选择级别 |
在发送 payload 后需要检查或反向压缩引用时，请使用 `sourceMap` 或 `--source-map`。
## 🏗️ 架构
```
+------------------+ +--------------------+ +-------------+
| IDE / 工具 |---->| GlyphCompress |---->| LLM API |
| | | | | |
| VS Code | | 1. 索引文件 | | OpenAI |
| Antigravity | | 2. 压缩上下文 | | Claude |
| CLI 脚本 | | 3. 注入代码簿 | | Gemini |
| 自定义应用 | | 4. 跟踪统计 | | |
+------------------+ +--------------------+ +-------------+
```
**代码簿**（约 150 个 token）会一次性注入系统。LLM 从中学习解码 glyph，并以自然语言正常响应。
## 📦 项目结构
```
glyph-compress/
├── bin/
│ ├── cli.js # `glyph-compress` CLI（压缩/检查/医生/基准测试/路由/团队代码簿）
│ └── mcp-server.js # `glyph-compress-mcp` MCP 服务器（compress_text/compress_file/route_context/get_codebook）
├── src/
│ ├── index.js # 库入口点（ESM）
│ ├── index.cjs / index.d.ts # CommonJS 入口点 + 稳定 TypeScript 声明
│ ├── glyph-middleware.js # 编译中间件的薄重新导出（参见 vscode-ext/）
│ ├── workspace-intelligence.js # 工作区代码簿、意图检测、文件排名和上下文路由的文件读取器
│ ├── team-codebook.js # 团队代码簿注册表（glyphcompress.team.json 读取/写入/合并）
│ ├── token-estimator.js # 提供者感知 token 估计器
│ ├── radical-alphabet.js / compressor.js / system-prompt-generator.js # 旧独立引擎（由 `npm run demo` 使用）
│ └── workspace-intelligence.cjs, team-codebook.cjs, ... # esbuild 生成的 CJS 构建（参见 scripts/build-middleware.js）
├── vscode-ext/
│ ├── package.json # VS Code 扩展清单
│ ├── extension.js # 扩展激活和命令
│ └── glyph-middleware.js # 核心中间件：GlyphCompressor，wrapOpenAI/wrapAnthropic，routeAndCompress
├── test/
│ ├── run-suites.js # 运行所有 17 个测试套件
│ ├── unit.js, cli.js, workspace.js, metadata.js, snapshots.js, integration.js, holographic-test.js, intent-test.js
│ ├── codebook-completeness.js, auto-level.js, cache-prefix-stability.js, tech-glyph-economics.js
│ ├── context-router.js, mcp-server.js, team-codebook.js # 最新套件 — 路由器、MCP 协议、共享词典
│ ├── tokenizer-calibration.js # 真实 tokenizer glyph 成本报告（npm run calibrate:tokenizer）
│ └── benchmark.js, benchmark-realistic.js
├── examples/
│ ├── openai-example.js, claude-example.js, antigravity-example.js
├── package.json
├── SECURITY.md, PRIVACY.md, ENTERPRISE.md, COMMERCIAL_LICENSE.md, NOTICE, LICENSE
├── ROADMAP.md, RELEASE_NOTES.md
└── README.md
```
## 🧪 测试
```bash
# 运行所有 17 个测试套件
npm test
# 运行聚焦的套件
npm run test:unit
npm run test:cli
npm run test:workspace
npm run test:extension
npm run test:proxy
npm run test:metadata
npm run test:snapshots
npm run test:holographic
npm run test:intent
npm run test:integration
npm run test:codebook # codebook-completeness：每个发出的 glyph 必须被记录
npm run test:auto-level # selectCompressionLevel() / level: 'auto'
npm run test:cache-prefix # 字节稳定的代码簿前缀，用于提供者端的隐式缓存
npm run test:tech-glyph-economics # TECH_GLYPHS 在 OpenAI 上永远不会失去真实 token
npm run test:context-router # routeAndCompress() + CLI `route`
npm run test:mcp-server # 通过官方 SDK 客户端驱动真正的 MCP 服务器
npm run test:team-codebook # glyphcompress.team.json 共享词典
# 运行稳定版本验证捆绑包（构建、完整测试套件、基准测试、链接检查、npm pack dry-run）
npm run check
# 检查本地 Markdown 链接
npm run check:links
# 运行信任和测量基准
npm run benchmark
# 运行现实的语料库、payload 和吞吐量基准
npm run benchmark:realistic
# 在 OpenAI tokenizers（cl100k_base/o200k_base）上测量真实的每个 glyph token 成本
npm run calibrate:tokenizer
# 运行交互式演示
npm run demo
```
## 🔬 理论
GlyphCompress 基于信息论：
- **香农熵** 告诉我们字符级编码的理论压缩极限
- **柯尔莫哥洛夫复杂度** 告诉我们压缩 = 理解
- **语义压缩** 捕获标准算法（GZIP、Brotli）遗漏的结构冗余
关键的洞察：开发通信 **高度结构化** — 相同的模式（`fix error`、`deploy to`、`create component`）以不同的参数重复数千次。通过将这些模式编码为可组合的部首，我们实现了远超字节级算法的压缩比。
> **基本定律**：完美压缩等同于完美理解。信息在消息、代码簿和接收者的上下文中重新分布 — 而不是丢失。
## ⚖️ 双重许可模式
GlyphCompress 在 **双重许可** 模式下分发：
1. **开源：AGPL-3.0-only**。公共仓库和 npm 包可以在 [LICENSE](LICENSE) 中的 AGPL-3.0-only 条款下使用。如果您修改、集成、重新分发或通过网络提供 GlyphCompress，请确保您可以满足 AGPL 义务。
2. **商业许可**。专有、闭源、私有重新分发、SaaS、托管、嵌入、OEM、市场或企业使用，无需 AGPL 义务，需要单独的书面商业协议。下载、安装、导入或捆绑包并不授予商业权利。
参见 [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)、[docs/licensing.md](docs/licensing.md) 和 [NOTICE](NOTICE) 以了解项目的许可立场。如需商业条款，请联系 `campiossasco1@gmail.com`。
## 🤝 贡献
欢迎贡献！感兴趣的领域：
- **新的部首**，适用于新兴技术
- **语言支持**，适用于非英语提示（已支持意大利语、德语、法语；欢迎西班牙语、葡萄牙语、日语等）
- **VS Code Marketplace** 元数据、示例和兼容性报告
- **基准数据**，来自现实世界的 IDE 会话
- **LLM 理解测试**，适用于不同的模型
通过提交贡献，您确认可以根据 [CONTRIBUTING.md](CONTRIBUTING.md) 中描述的双重许可模式使用它。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器