---
title: 快速入门
description: 在几分钟内将 askRunic 和 storeResult 接入现有智能体。
sidebar:
  order: 1
---
## 安装

```package-install
npm i @runic-labs/sdk
```

`@runic-labs/sdk` 依赖于 `@runic-labs/cache` 和 `@runic-labs/ledger`——除非你想自行构建自定义存储实例，否则无需单独安装它们（参见 [缓存](/cache) 和 [账本](/ledger)）。

## 包装智能体现有的调用

找到智能体中将任务转换为 LLM 或工具调用的位置，并使用 `askRunic` / `storeResult` 将其包装起来：

```ts
import { askRunic, storeResult } from "@runic-labs/sdk";

async function reviewFile(repo: string, file: string) {
  const decision = { intent: "review_code", params: { repo, file } };

  const cached = await askRunic(decision);
  if (cached) {
    console.log(`cache hit — saved ${cached.tokensSpent} tokens`);
    return cached.artifact;
  }

  const response = await callYourLLM(promptFor(repo, file));
  await storeResult(decision, response.text, response.tokensUsed);
  return response.text;
}
```

集成就这么简单。无需任何配置即可开始使用——`askRunic`/`storeResult` 会在当前工作目录下的 `.runic/` 中使用默认的文件支持存储。

## 选择 `intent` 和 `params`

签名采用精确匹配，因此请根据你的使用场景决定什么条件会让两次调用成为“同一决策”：

- **良好**：`{ intent: "summarize_pr", params: { repo: "acme/widgets", pr: 482 } }`——同一仓库、同一 PR 编号、同一意图；每次查询这个确切的 PR 时都保持一致。
- **不佳**：`{ intent: "summarize_pr", params: { prompt: fullPromptString } }`——将原始提示词文本作为参数，意味着任何措辞改动（哪怕只是空白字符）都会导致缓存未命中，从而失去意义。

只将真正用于标识决策的参数放入 `params`。将提示词文本、推理轨迹以及任何非确定性内容完全排除在签名之外——原因请参见[工作原理](/how-it-works)。

## 查看已缓存的内容

```package-install
npm i -g @runic-labs/cli
```

```bash
runic cache status
runic ledger status
```

完整输出示例请参见 [CLI](/cli)。

## 指向不同的存储位置

默认情况下，Runic 会写入 `process.cwd()` 中的 `.runic/`。如果智能体运行所在的工作目录不同于你希望存放状态的位置，可通过环境变量覆盖：

```bash
RUNIC_HOME=/var/lib/my-agent/runic node agent.js
```

## 改用内存存储（测试、临时运行）

```ts
import { createRunicClient } from "@runic-labs/sdk";
import { createCache, MemoryCacheStore } from "@runic-labs/cache";
import { createLedger, MemoryLedgerStore } from "@runic-labs/ledger";

const runic = createRunicClient({
  cache: createCache(new MemoryCacheStore()),
  ledger: createLedger(new MemoryLedgerStore()),
});

const cached = await runic.askRunic({ intent: "summarize_pr", params: { repo, pr } });
```

这正是 `benchmarks/reuse-sweep` 和 `benchmarks/openrouter-savings` 所使用的方式，因此不同脚本运行之间不会保留任何内容。

## 后续

- [工作原理](/how-it-works)——签名算法详解
- [基准测试](/benchmarks)——复现真实的 token 节省数据