内容
<div align="center">
# 💾 奥拉
### 面向 AI 智能体的无依赖上下文优化器
* [⚡️ 闪蝶家族](https://shaddai-g81x.onrender.com) 的一部分
您的智能体在每次调用时都会发送**整个工具箱、整个历史记录和整个系统** - 其中大部分都是无效的。奥拉（AURA）在请求**之前**修剪了发送的内容：仅发送此调用所需的工具，压缩过时的历史记录，并提炼膨胀的提示。奥拉是**确定性的**，**零依赖**，并且它**公开失败** - 它永远不会静默丢弃模型需要的某些内容。作为 **CLI**、**MCP 服务器**（Claude / Cursor / Claude Code）和**库**发布。
> **40 工具智能体，真实提示：82% 的工具模式令牌被剪裁**（`npm run bench`）。按照 $3/M 输入计算，相当于 **~$410 每 10 万次调用** - 仅限于工具模式。
<br>
[](https://www.npmjs.com/package/shaddai-aura)
[](LICENSE)
[](package.json)
[](#-mcp-server)
[**𝕏 @shaddaiAI**](https://x.com/shaddaiAI) · [**由 @IzzoSol 构建**](https://x.com/IzzoSol)
</div>
---
## ✦ 为什么
每个 LLM 应用都为相同的问题反复付费。奥拉在 **API 调用之前**拦截它们 - 从缓存、计算、种子事实和无参数技能配方中提供确定性答案。能免费回答的问题就免费回答。
一句话总结：**奥拉是一个零依赖、策略门控的确定性预处理器，用于 AI 智能体。** 它在本地解决重复、结构化或可计算的提示，验证可重用的技能，并且仅在您配置时才让付费模型运行。
> **核心原则：让模型远离热点。** 一次解决某个问题，然后永远确定性地运行。奥拉在小端应用该原则 - 缓存、本地计算和作者定义的技能意味着重复提示的费用为零，无需**编译器**、**图形运行时**和**依赖项**。参见 **[COMPARISON.md](COMPARISON.md)** 以获得与 LLM 缓存的诚实对比（以及何时选择 GPTCache 或 LangChain）。
## ✦ 安装
```bash
# 一次性 MCP 服务器（Claude Desktop / Cursor / Claude Code）
npx -y -p shaddai-aura aura-mcp
# 或 CLI
npm i -g shaddai-aura
aura ask "重复问题"
aura stats
```
## ✦ 一个调用：`aura.optimize(request)`
直接替换。给奥拉您的模型请求，它会返回一个更精简的请求 - 仅包含此调用所需的工具、提炼的系统提示和压缩的历史记录 - 已准备好发送。非变异，每个表面都是可调的或可跳过的。
处理每个真实请求形状：字符串 `system`，Anthropic **块数组** `system`（`[{type:'text', text, cache_control}]` - 结构和 `cache_control` 保留），或 OpenAI `system` 角色消息。OpenAI 或 Anthropic 形式的工具均适用。
```javascript
const aura = require('shaddai-aura');
// 您的正常请求（OpenAI 或 Anthropic 形状均可）
const { request, report } = aura.optimize(
{ system, messages, tools },
{ tools: { k: 6 } } // 可选：调整/禁用任何表面
);
await client.messages.create(request); // 发送优化后的请求
report // → { tools:{total,sent,saved}, instructions:{saved}, history:{saved,elided}, tokensSaved }
```
一行代码，三个节省：**工具 + 指令 + 历史记录**，全部确定性，全部报告。或者分别调用它们：`aura.selectTools`、`aura.distill`、`aura.compress`.
**拟合硬上下文预算：** 传递 `maxTokens`，奥拉压缩足够硬以使整个请求适应，然后告诉您真相 - `report.budget = { limit, finalTokens, fit }`. 如果 `fit:false` 表示它已经挤压到安全极限（系统、任务、最近回合）- 它从不静默丢弃这些以达到数字。
**原生提示缓存：** 传递 `cache: true`，奥拉标记稳定前缀可缓存（`cache_control: {type:'ephemeral'}` 在提炼的系统提示上），提供者在第一次之后的每次调用中按 ~10% 计费。仅当您不按回合修剪工具时才会缓存工具（否则会每次调用错过缓存）。OpenAI 自动缓存长前缀，因此它是 no-op - 在 `report.cache` 中报告。
> **顶点基准**（`npm run bench`）- 真实的 10 回合智能体会话，40 个工具，增长的历史记录每次调用：**节省 60% 的总请求令牌**（工具注入 ~12.7k + 历史记录压缩 ~10.5k + 提炼）。`aura stats` 显示每个表面的相同分割。
## ✦ 命令
| 命令 | 功能 |
|---|---|
| `aura ask "<prompt>"` | 如果可能，免费回答（缓存/计算/技能）。 |
| `aura ask "<prompt>" --llm [--model <id>]` | 如果没有免费答案，请调用您的 AI 模型，然后缓存它。 |
| `aura learn "<prompt>" "<answer>"` | 教奥拉一个答案，以便下次免费。 |
| `aura learn-sessions [--apply]` | 从您的 Claude Code 历史记录中学习稳定的事实和重复的提示（干运行除 `--apply` 外；筛出秘密）。 |
| `aura skill add\|list\|remove\|validate\|lint` | 管理可重用的技能（见下文）。 |
| `aura stats` · `aura clear` · `aura where` | 节省 · 清除缓存 · 缓存位置。 |
## ✦ 已保存的技能（定义一次 → 永久免费）
**技能** 是一个微小的“编译程序”：模式 → 确定性动作，存储在 `~/.shaddai-aura/skills.json` 中。保存后，任何匹配的提示都以 **无需 AI 调用** 的方式免费回答。
```
# 子字符串/关键字匹配 → 固定答案
aura skill add "支持" --match "支持邮箱" --do "cloudzncrownz@gmail.com"
aura ask "嘿，支持邮箱是什么" # → cloudzncrownz@gmail.com （免费 · 通过技能）
# 正则表达式匹配，带有 $1, $2 捕获组替换（--regex，或包装模式在 /.../ 中）
aura skill add "问候" --match "/^hi (\w+)/i" --do "Hello, $1!" --regex
aura skill list # 显示所有已保存的技能
aura skill remove "问候" # 删除一个
```
**适配器（实时数据，仍然免费，无密钥）：** 技能动作可以是 `{ type:'adapter', adapter:'price', args:{ coin:'btc' } }` 以获取确定性数据而不是调用 LLM。适配器执行网络 I/O，因此它们通过异步 `ask()` 运行并**优雅降级** - 离线时直接返回正常未命中。
### 模式和验证
技能遵循类型化合约（记录在 [`schema/skill-schema.json`](schema/skill-schema.json) 中）。验证是**手工编写的零依赖** - 绝不会将无效技能写入 `skills.json`。
```bash
aura skill validate ./my-skills.json # 验证文件中的数组（或一个技能）
aura skill lint # 验证您的 installed skills.json
```
除了形状外，验证器拒绝：一个无法编译的正则表达式（`regex:true` 或 `/.../ ` 字面量）或与已知**灾难性回溯**形状（嵌套量词 (`(\w+)+`) 或重叠交替量词 (`(a|a)*`, `(a|ab)+`）匹配；一个动作缺少其 `type` 所需的有效负载；一个**适配器不在允许列表中**（目前仅 `price` - 无 shell/任意适配器）；一个具有空/嵌套步骤的 `chain`；一个超出范围的 `priority`；以及**重复的技能名称**。
**加载时安全，而不是仅在添加时。** ReDoS 筛选是尽力而为的静态分析（健全的保证需要匹配时限），因此 `skills.json` 也会在加载时进行消毒：任何正则表达式未能通过筛选，或其字段超过大小上限的技能都会被静默跳过。手动编辑或第三方 `skills.json` 不能挂起路由器 - 但只加载您信任的技能。
### 优先级
当多个技能与一个提示匹配时，通过显式 **`priority`** （0-1000，越高越优先）→ **关键词计数** （更具体优先）→ **插入顺序** 选择获胜者。整体路由顺序为 **精确缓存 → 模糊缓存 → 技能 → 计算**。
```
aura skill add "部署-prod" --match "部署 prod" --do "run: npm run deploy:prod" --priority 900
```
## ✦ 从您自己的历史记录中学习
`aura learn-sessions` 扫描您的 Claude Code 转录记录（`~/.claude/projects/**/*.jsonl`），查找您询问的**稳定事实** 和您重复询问的提示，并教导奥拉它们以便下次免费回答 - 基于“编译一次，永久运行”，并个性化为您。
```
aura learn-sessions # 干燥运行 - 显示它将学习的内容，不写入任何内容
aura learn-sessions --apply # 实际教导奥拉（事实 → 缓存，3 次重复 → 技能）
aura learn-sessions --dir <path> # 扫描不同的转录文件夹
aura learn-sessions --min-repeat 5 # 需要 5 次重复才能成为技能
```
- **转录记录中绝不会留下秘密。** 任何包含 API 密钥、令牌、私钥、连接字符串或 env-style 机密的提示/答案都会被完整删除 - 从未缓存。通用高熵筛选器捕获命名模式未捕获的凭证形字符串。
- **没有过时答案。** 时间敏感、定价、版本或“今日/最新”内容会被跳过；代码、创意散文、命令式命令、闲聊和子代理/工具轮也会被跳过。
默认情况下它是**干燥运行** - 在您传递 `--apply` 之前不会写入任何内容。最佳结果来自支持/FAQ/知识风格的历史记录。随时可以使用 `aura clear` 撤销。
## ✦ 工具注入 - 发送此回合所需的工具
被忽视的排水：一个 40 工具智能体发送 **~1,600 个令牌的 JSON 工具模式每次调用** - 即使用户只说了“谢谢”。大多数回合使用两个或三个工具。奥拉根据当前提示（BM25，与模糊缓存相同的零依赖索引）评估每个工具的名称 + 描述 + 参数，并仅发送相关的工具。
```javascript
const aura = require('shaddai-aura');
const { tools, report } = aura.selectTools(userPrompt, allTools, { k: 6 });
// 将 `tools` 传递给模型而不是 `allTools`
// 报告 → { total: 40, sent: 5, savedTokens: 1444, dropped: [...], scores: [...] }
```
**上下文感知：** 传递整个消息数组 (`selectTools(messages, tools)`) 和一个简洁的后续操作，如 *"yes, do it"* 仍然可以从最近的对话中解析正确的工具 - 因此您可以积极地修剪而不会使简短的回复中断。一个纯粹的提示字符串也适用。
与 **OpenAI** (`{type:'function',function:{…}}`) 和 **Anthropic** (`{name,input_schema}`) 工具形状均兼容。通过 `k` （最大工具数）、`alwaysInclude` （不能很好地表达的关键）、`contextWindow` 和 `minPool` 进行调整。
**安全保证 - 它公开失败。** 如果提示与任何工具没有共同词汇，或者工具箱很小，或者没有得分，奥拉会发送**所有内容**而不是冒着工具模型需要的风险。你可以调整攻击性；你永远不会静默丢失工具。每个决定都会被报告。运行 `npm run bench` 以在现实的 40 工具智能体上看到它（**~82% 剪裁**）。
## ✦ 蒸馏 - 修剪膨胀的系统提示
系统提示每次调用**都会被计费，永久生效。** OpenAI 的 GPT-5.6 指南很明确：精简提示在评估中得分 **~10-15% 更高**，同时减少 **41-66% 的令牌**。奥拉确定性地应用该规则 - 并且安全地。
```bash
aura distill "您有帮助。保持简洁。总结它。总结它。绝不泄密。"
# 修剪： [exact-duplicate] 总结它。
# 标记： [model-likely-reliable] 保持简洁。
# 保护：绝不泄密。
aura distill --file system-prompt.md # 打印报告 + 精简提示
aura distill --file system-prompt.md --apply # 写回（保留.bak）
aura distill --file system-prompt.md --llm # 还进行语义重写（需要密钥）
aura distill "<prompt>" --json # 机器可读的报告
```
**它只删除可证明冗余的内容** - 精确重复规则，近似重复规则（以相同规则重述的规则）和前导填充（“请注意...”）。所有**受保护**的内容 - 安全/许可约束，成功/停止标准，所需输出形状，上下文依赖的工具路由和**行为范围**规则（工具预算，不确定性政策，停止/升级）- **保护** - 按章节结构和关键词。
可选的 `--llm` 传递执行实际的语义重写，但前提是**每个受保护的行都存活下来** - 模型不能静默丢弃规则。
## ✦ 连接您的 AI 模型（适用于 `--llm`）
在运行之前设置**其中一个**:
```bash
export OPENROUTER_API_KEY="sk-..." # 或 OPENAI_API_KEY，或 ANTHROPIC_API_KEY
```
然后 `aura ask "summarize this..." --llm` 即可生效。无需密钥时，`--llm` 只会告诉您没有连接模型 - 它绝不会编造。奥拉会自动选择最便宜的可用模型（轻/平衡/重）用于提示并缓存答案。
## ✦ MCP 服务器
将任何 MCP 客户端指向 `aura-mcp`。stdout 保持纯 JSON-RPC（日志记录到 stderr），输入限制未知，工具/资源/提示降级。请参见 `SECURITY.md`。
```json
{ "mcpServers": { "aura": { "command": "npx", "args": ["-y", "-p", "shaddai-aura", "aura-mcp"] } } }
```
它公开了六个零依赖工具：
| 工具 | 功能 |
|---|---|
| `aura_ask` | 尝试免费回答提示（缓存/保存技能/计算）。模型首先调用此操作，在命中时跳过自己的推理。 |
| `aura_remember` | 缓存模型刚刚生成的答案，以便下次免费使用。 |
| `aura_stats` | 显示节省的令牌和美元。 |
| `aura_distill` | 修剪提示/系统提示中的冗余指令（保护安全/输出/路由规则；标记其他）。 |
| `aura_compress` | 在下一回合之前压缩长对话历史记录。 |
| `aura_select_tools` | 选择性工具注入 - 返回此回合需要的工具（公开失败）。 |
| `aura_optimize` | 全一调用优化器 - 修剪工具 + 蒸馏系统 + 压缩历史记录整个请求。 |
| `aura_savings` | 组合答案缓存 + 工具缓存节省报告。 |
还有一个只读资源 **`aura://savings`** - 实时每表面节省的ledger，直接拉取到客户端的上下文中。
**Claude Code:** `claude mcp add aura -- npx -y -p shaddai-aura aura-mcp`
## ✦ 它如何节省
| 路径 | 功能 |
|------|--------------|
| **工具注入** | 只发送此提示需要的工具，而不是全部 40 个 - 最大的每次调用收益（~82% 的工具模式令牌），公开失败以避免所需工具被丢弃 |
| **压缩** | 在每个回合之前压缩对话历史记录（重复读取文件，折叠重复的日志/重试行，截断过时的工具转储） |
| **蒸馏** | 从提示/系统提示本身修剪冗余指令 |
| **缓存/查询** | 具有限 TTL 缓存的先前答案 + 模糊的同义疑问词命中 |
| **技能/配方** | 作者定义的技能无需模型运行 |
| **计算** | 确定性地本地计算的答案 - 数学，%，单位/温度转换，日期，哈希，基数转换，颜色等（一个奖励快速通道，不是主要功能） |
奥拉在 **每次调用的四个表面上节省**：工具（注入），历史记录（压缩），**指令**（蒸馏）和数学。 （一个额外的快速通道，而不是主要的）
---
## ✦ 闪蝶家族
| 仓库 | 功能 |
|------|------|
| **[闪蝶](https://shaddai-g81x.onrender.com)** | 主权 AI 智能体帝国 - 7 个智能体，200+ 真实工具 |
| **[奥拉](https://github.com/IzzoSol/aura)** | *此* 无依赖令牌节省工具 · CLI + MCP + 库 |
| **[闪蝶-剪辑器-功能](https://github.com/IzzoSol/Shaddai-Clipper-Feature-)** | 长视频 → 有字幕的垂直短视频 |
<div align="center">
<br>
**由 [@IzzoSol](https://x.com/IzzoSol) 构建 · 关注 [@shaddaiAI](https://x.com/shaddaiAI)** · MIT
</div>
