内容
# TokenSkein
TokenSkein 是一个为 GPT 客户端和 Codex 提供的本地上下文经济网关。它结合了 pxpipe、Headroom、RTK 和 Caveman-style 输出规范等有用的想法，而不假装每种优化都有助于每个请求。
名字的由来是将 **token** 与 **skein** 结合：模式、恢复的文本、图像页面、shell 输出、样式和推理是单独的线索，作为一个有测量的捆绑进行管理。
当前的可行性验证版本（MVP）可以：
- 代理 OpenAI 响应 API 请求；
- 紧凑的工具模式和旧工具输出；
- 在本地存档每个紧凑的输出，以便确切的文本仍然可检索；
- 通过 MCP 暴露压缩、检索和统计数据；
- 根据任务复杂性路由推理工作量；
- 注入简洁的输出策略，并带有安全例外；
- 可选地将非常密集的文本编码为 PNG 页面，当明确的经济门户通过时；
- 可选地在 RTK 之后为已识别的只读 shell 命令放置一个安全输出过滤器。
状态：**正在实验的 MVP**。文本压缩、存储、MCP、路由、代理和 shell 适配器已经实现并测试过。视觉通道已经实现，但默认情况下禁用，直到模型特定的 A/B 评估确定其实际成本和质量。
## 为什么存在
上下文成本有多种不同的原因，因此仅靠一个技巧是不够的：
- 重复的模式会浪费输入令牌；
- 大日志和 JSON 会消耗上下文，即使只有几行内容；
- 冗长的响应会消耗输出令牌；
- 简单任务不总是需要高推理工作量；
- 密集的视觉文本有时可能比原始文本花费的模型令牌更少，但也可能损害准确性或花费更多；
- 有损压缩在省略的细节在以后需要时变得危险。
TokenSkein 将这些视为独立的通道，拥有独立的门户。其核心规则是：**压缩可替换的内容，保留精确的内容，并保持原始内容可恢复**。
## 架构
```mermaid
flowchart LR
C[Codex 或 GPT 客户端]
U[OpenAI 响应 API]
D[(受保护的本地上下文存储)]
E[(指标 JSONL)]
N[(使用情况 JSONL)]
subgraph L[TokenSkein]
P[响应代理]
Q[请求策略管道]
M[MCP 服务器]
H[Codex 钩子和 shell 过滤器]
A[经济使用记录器]
K[按日期定价目录]
V[仪表盘服务器]
end
C -->|响应请求| P
P --> Q
Q -->|优化请求| U
U -->|流或响应| P
P --> C
Q -->|存档精确原件| D
C <-->|压缩、检索、统计| M
M <--> D
C -->|安全读取命令| H
H -->|可选 RTK 重写| H
H -->|存档大输出| D
Q --> E
M --> E
H --> E
P -->|提供商使用情况| A
K -->|缓存感知成本| A
A --> N
V -->|读取| E
V -->|读取| N
```
在请求策略管道中，操作按以下顺序运行：
1. 删除非操作工具模式元数据；
2. 在启用时注入简洁样式策略；
3. 除非调用者已经选择了一个，否则选择推理工作量；
4. 保留最近的输入尾部完整；
5. 紧凑的合格的旧 `function_call_output` 项；
6. 仅当模型允许列表和盈利能力估计都通过时，可选地追加 PNG 页面；
7. 将转换后的请求转发到配置的上游。
自由编辑的副本位于 [docs/architecture.excalidraw](docs/architecture.excalidraw)；上面的 mermaid 模块是真实的来源，可能领先于它。
### 模块映射
| 模块 | 责任 |
|---|---|
| `src/proxy.ts` | HTTP/SSE 转发、本地端点、请求覆盖 |
| `src/optimize.ts` | 有序响应请求策略管道 |
| `src/compact/` | 工具模式、可恢复文本和 PNG 转换 |
| `src/store.ts` | 内容寻址存档、TTL、搜索、清理 |
| `src/mcp.ts` | `skein_compress`、`skein_retrieve` 和 `skein_stats` |
| `src/shell.ts` | 选择性 Codex 钩子、RTK 委托、shell 输出存档 |
| `src/routing.ts` | 提示复杂性工作量选择 |
| `src/metrics.ts` | 无内容的优化事件聚合 |
| `src/economics.ts` | 提供商使用情况解析（SSE 和 JSON）和使用情况 JSONL 记录 |
| `src/pricing.ts` | 按日期的每个模型定价目录和缓存感知成本计算 |
| `src/dashboard.ts` + `src/dashboard/` | 环形仪表盘服务器和指标/使用情况聚合 |
| `src/config.ts` | 配置加载、验证和环境覆盖 |
| `src/install.ts` | 事务性 Codex 安装、卸载和验证 |
| `src/codex.ts` | 非突变的 Codex 集成代码片段 |
| `src/cli.ts` | 面向用户的命令调度器 |
### 架构原理
- **广泛覆盖的响应代理**。请求级别的节省不应依赖模型记住调用工具。
- **MCP 以实现精确恢复**。短的 `skein:<hash>` 引用在省略的上下文可以按需获取时很有用。
- **本地优先存储**。精确的工具输出保留在机器上，以 `0700` 目录和 `0600` 文件进行 gzip 压缩和权限保护。
- **最近尾部保留**。新的观察结果更有可能影响下一个立即的动作，因此保留不变。
- **文本通道优先于视觉通道**。文本保持可搜索和精确。视觉是模型依赖的优化，因此是可选的，并有一个收支平衡门户。
- **确定性转换优先**。模式清理、行选择、标识符保留和路由是可检查和可测试的。语义总结可以稍后在评估门户后面添加。
- **严格的 shell 允许列表**。钩子重写仅限于识别的读取/验证命令。破坏性、复合、重定向或模糊的命令不会被重写或自动批准。
- **没有夸大其词的衡量**。节省统计数据是基于 tokenizer 的估计。美元数字使用提供商报告的使用情况，通过按日期的每个模型目录定价，并具有缓存感知输入率；目录中不存在的模型报告成本为未知，而不是猜测。
## 仪表盘
仪表盘读取 `token-skein stats` 使用的指标 JSONL 和提供商使用情况 JSONL，并渲染估计的令牌节省、提供商报告的成本和延迟（如果记录）、缓存命中/未命中计数和每小时序列，按优化模式和模型分类。启动它使用 `bun run dashboard`（等同于 `bun run src/dashboard.ts`）；它默认监听 `127.0.0.1:8790`，可使用 `TOKEN_SKEIN_DASHBOARD_PORT` 重写。它仅绑定到环形接口，在网络上不可访问。
## 已移植内容
实现是从选定的概念移植而来，而不是原始项目的串联：
| 来源 | 有用的想法 | TokenSkein 状态 |
|---|---|---|
| pxpipe | 将密集文本渲染成图像页面 | 已实现，可选 |
| pxpipe | 模型允许列表和盈利能力阈值 | 已实现 |
| pxpipe | 保留最近的精确文本尾部 | 已实现响应输入项 |
| Headroom | 压缩-缓存-检索生命周期 | 已实现本地内容寻址存储 |
| Headroom | TTL、清理、定向检索、统计 | 已实现 |
| Headroom | 紧凑的冗余工具模式 | 递归实现 |
| Headroom | MCP 压缩/检索接口 | 实现结构化输出 |
| RTK | 在执行前重写支持的命令 | 实现为可选的 `rtk rewrite` 委托 |
| RTK | 减少嘈杂的 shell 输出 | 实现精确存档恢复 |
| Caveman | 简短答案不丢失技术实质 | 实现为可配置指令 |
| Caveman | 为安全性和不可逆操作绕过简洁样式 | 在样式策略中保留 |
| 全球 Claude 设置 | 分级披露和基于任务的模型工作量 | 实现按需恢复 + 工作量路由 |
| 全球 Claude 设置 | 耐用全局指令层 | 可选 Codex `AGENTS.md` 片段包含 |
可选提示片段位于 [integrations/codex/AGENTS.token-skein.md](integrations/codex/AGENTS.token-skein.md)。它故意很小：移动一个大的全局 `CLAUDE.md` 会花费本项目试图节省的上下文。
## 计划的移植和扩展
优先级待办事项在 [PLAN.md](PLAN.md) 中跟踪。主要计划工作是：
- 构建一个可重复的 A/B 测试框架，用于正确性、精确标识符、延迟和成本；
- 添加流感知响应会计，无需缓冲 SSE；
- 添加会话感知历史压缩而不是仅限于项目年龄规则；
- 调整每种模型的视觉页面并拒绝 OCR 不友好或关键精确度内容；
- 添加原生 shell 减少器，使 RTK 保持可选而不是必需；
- 添加 MCP 资源和大型存档的索引检索；
- 在响应路径稳定后评估其他提供商协议。
## 快速入门
需求：Bun 1.3+ 和用于默认上游的 OpenAI API 密钥。
```bash
cd ~/projects/token-skein
bun install
bun run check
bun run proxy
```
默认代理监听 `http://127.0.0.1:8788` 并转发到 `https://api.openai.com`。它不复制或存储 API 密钥；授权标头在内存中转发。
对于通用响应客户端，将其 OpenAI 基本 URL 指向：
```text
http://127.0.0.1:8788/v1
```
### Codex 集成
打印集成代码片段而不更改全局配置：
```bash
bun run src/cli.ts codex-snippet
```
然后：
1. 将提供商和 MCP 模块合并到 `~/.codex/config.toml`；
2. 在应运行的位置全局或配置文件中选择 `model_provider = "token_skein"`；
3. 如果需要实验 shell 通道，请将钩子模块合并到 `~/.codex/hooks.json`；
4. 在允许列表检查后，将 `shell.enabled` 设置为 `true` 以启用该通道；
5. 启动 `bun run proxy` 之前启动 Codex 配置文件；
6. 确保 `OPENAI_API_KEY` 可用于 Codex。
此路径使用 OpenAI API 密钥计费。它 **不** 声称通过自定义提供商隧道 ChatGPT/Codex 订阅身份验证。WebSocket 响应传输当前禁用；HTTP 和 SSE 被转发。
Codex 钩子适配器针对 `Bash` `PreToolUse` 形状构建。Codex 构建仅通过其他工具名称公开 shell 执行的构建仍将受益于代理和 MCP 通道，但如果添加了适用于该工具形状的适配器，则不会使用 shell 重写。
### 可选的全局指令片段
查看 [integrations/codex/AGENTS.token-skein.md](integrations/codex/AGENTS.token-skein.md)，然后仅合并您想要的规则到 `~/.codex/AGENTS.md` 中。TokenSkein 永远不会自动编辑该全局文件。
## 配置
默认配置路径是 `~/.config/token-skein/config.json`。从 [token-skein.config.example.json](token-skein.config.example.json) 开始。嵌套值会覆盖默认值。
环境变量覆盖：
| 变量 | 用途 |
|---|---|
| `TOKEN_SKEIN_CONFIG` | 替代 JSON 配置路径 |
| `TOKEN_SKEIN_HOST` | 代理绑定主机 |
| `TOKEN_SKEIN_PORT` | 代理端口 |
| `TOKEN_SKEIN_UPSTREAM` | 上游 API 源 |
| `TOKEN_SKEIN_STORE_DIR` | 本地存档目录 |
| `TOKEN_SKEIN_EVENTS_PATH` | 指标 JSONL 路径 |
| `TOKEN_SKEIN_BIN` | 钩子包装器使用的确切命令 |
| `TOKEN_SKEIN_DASHBOARD_PORT` | 仪表盘绑定端口（默认 `8790`），直接由 `bun run dashboard` 读取 |
存档配额是一个配置文件字段，而不是环境变量：`archive.maxBytes`（默认 200 MiB）限制了本地上下文存储，一旦超过，至少最近触摸的条目将被首先驱逐。
请求级控制：
| 头部 | 接受值 | 效果 |
|---|---|---|
| `x-token-skein-bypass` | `true` / `false` | 跳过所有请求转换 |
| `x-token-skein-vision` | `true` / `false` | 覆盖此请求的视觉开关 |
| `x-token-skein-style` | `true` / `false` | 覆盖简洁样式注入 |
| `x-token-skein-effort` | `low`, `medium`, `high`, `xhigh` | 显式推理工作量 |
视觉默认关闭。启用它是仅请求评估通道：内容必须超过 `minimumBytes`，模型必须匹配 `vision.models`，并且估计的文本令牌除以估计的图像令牌必须超过 `minimumSavingsRatio`。
## CLI
```text
token-skein proxy 启动本地响应代理
token-skein mcp 启动_stdio MCP 服务器
token-skein hook codex 从 stdin 处理 PreToolUse 事件
token-skein shell --encoded DATA 执行钩子批准的命令并过滤输出
token-skein stats 显示估计的节省和存档统计
token-skein cleanup 删除过期的存档条目
token-skein codex-snippet 打印 Codex 集成代码片段
token-skein install 安装 Codex 集成（事务性）
token-skein uninstall 删除 Codex 集成
token-skein doctor 检查 Codex 集成的先决条件
token-skein verify 在不修改任何内容的情况下验证现有安装
token-skein config 打印活动配置
```
直到软件包链接全局，请将 `token-skein` 替换为 `bun run src/cli.ts`。
仪表盘（`bun run dashboard`）和许可证扫描器（`bun run license-scan`）是单独的 Bun 脚本，而不是 `token-skein` 子命令。
## MCP 工具
- `skein_compress`：存档精确内容并返回紧凑视图和引用；
- `skein_retrieve`：获取精确原件或具有上下文的匹配行；
- `skein_stats`：聚合优化和存档指标。
MCP 服务器使用_stdio 并仅在 stdout 上发出协议流量；诊断信息发送到 stderr。
## 数据和安全边界
- 存档对象包含原始工具输出，可能包含机密信息。它们是本地的、gzip 压缩的、权限受限的，并且有 TTL 绑定，但 **不加密**。
- 紧凑视图中会编辑常见的 API 密钥、授权、令牌、秘密和密码表单。精确的存档故意保留原件以便恢复。
- 指标记录大小、令牌估计、模式、模型、引用和非内容元数据；它们不故意记录请求或输出正文。
- 代理默认绑定到环形接口。将其绑定到网络接口需要您自己的身份验证和传输控件。
- shell 钩子默认情况下禁用。显式启用时，它永远不会重写包含破坏性模式、命令链接、重定向、 heredocs、命令替换、危险减少器或换行符的命令。非匹配项会回退到正常的 Codex 行为。
## 已知限制
- 节省是使用 `o200k` 分词器估计的，而不是发票级测量。
- 图像令牌成本因模型、图像详细策略、页面密度和定价而异。PNG 可能更便宜、相等或更昂贵。
- 文本图像中的文本对于精确的标点和标识符是有损的。文本侧车和存档降低了这种风险，但不使视觉效果精确。
- 仅自动压缩较旧的 `function_call_output` 字符串；尚未重写任意对话历史。
- 视觉页面上限。省略的材料仍然可以通过存档获得。
- 当前的工作量路由器是启发式的，并且有英语偏见。
- 代理没有分布式存储、静止加密或多用户隔离。
## 验证
```bash
bun run typecheck
bun test
```
测试涵盖存储和到期、可恢复文本压缩、工具模式压缩、工作量路由、视觉门控、shell 安全性和端到端代理转换，通过模拟上游进行测试。
## 许可证和属性
TokenSkein 遵循 Apache-2.0 许可证。它采用了来自 pxpipe（MIT）、Headroom（Apache-2.0）、RTK（Apache-2.0）等概念以及用户的工作流。查看 [NOTICE](NOTICE) 和 [LICENSES/README.md](LICENSES/README.md)。
