# @agenttrace/proxy 中文文档

规范地址：https://npmcn.com/package/%40agenttrace/proxy/

版本：0\.1\.0
npm 元数据更新时间：2026-02-06T07:58:18.377Z
中文译文更新时间：2026-11-06T08:11:56.370Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agenttrace/proxy
原文对照：https://npmcn.com/package/%40agenttrace/proxy/?lang=original
项目主页：https://github.com/agenttrace/agenttrace/tree/main/packages/proxy#readme
源码仓库：https://github.com/agenttrace/agenttrace

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：207 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-02-06T07:58:17.883Z
- 最新版本发布：2026-02-06T07:58:18.177Z
- 近 30 天下载量：3948（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 1 个）

## 中文简介

AgentTrace 代理服务器用于缓冲和转发代理事件

## 安装

```sh
npm install @agenttrace/proxy
```

也可以使用：`pnpm add @agenttrace/proxy`、`yarn add @agenttrace/proxy`、`bun add @agenttrace/proxy`

## README

# @ agenttrace/ 代理服务器

LLM API 呼叫的透明 HTTP 代理 。 将请求转发给上游提供者,从响应(包括SSE流)中取出使用度量衡,并缓冲它们以交付给AgentTrace服务器.

## 支助提供者

-   OpenAI (英语:`api.openai.com`(中文(简体) )
-   发作( A)`api.anthropic.com`(中文(简体) )
-   谷歌 (中文(简体) )`generativelanguage.googleapis.com`(中文(简体) )
-   雾( M)`api.mistral.ai`(中文(简体) )
-   电线( C)`api.cohere.com`(中文(简体) )
-   深层搜索( D)`api.deepseek.com`(中文(简体) )
-   月球拍摄( M)`api.moonshot.cn`(中文(简体) )
-   Zhipu / GLM (英语)`open.bigmodel.cn`(中文(简体) )
-   迷你麦克斯( Minimax) (`api.minimax.chat`(中文(简体) )
-   贝川(`api.baichuan-ai.com`(中文(简体) )
-   Yi/01.AI (中文(简体) )`api.lingyiwanwu.com`(中文(简体) )

## 如何运作

1.  您的 LLM 客户端直接向代理发送请求, 而不是直接发送提供者
2.  代理从主机头检测提供者或请求路径
3.  如果配置, 将向请求头注入提供者 API 密钥
4.  如果配置,则执行每个供应商费率限额(429分超额)
5.  请求转交给真正的上游API
6.  实时回复到客户端
7.  抽取并缓冲盘点、模型、耐久性和成本
8.  缓冲事件被定期冲入代理 Trace 服务器

标准的JSON响应和SSE流化响应都得到了支持.

## 使用量

### 作为CLI的一部分(典型)

```bash
npx agenttrace start
# Proxy starts on port 4000
```

### 独立的CLI

```bash
agenttrace-proxy --api-key <token> --agent-id proxy \
  --provider-keys '{"openai":"sk-..."}' \
  --rate-limits '{"openai":{"maxRequests":100,"windowSeconds":60}}'
```

### 程序化

```typescript
import { startProxy } from "@agenttrace/proxy";

const { server, shutdown } = startProxy({
  port: 4000,
  apiKey: "your-token",
  agentId: "proxy",
  endpoint: "http://localhost:8080/api/events",
  providerKeys: {
    openai: "sk-...",
    anthropic: "sk-ant-...",
  },
  rateLimits: {
    openai: { maxRequests: 100, windowSeconds: 60 },
  },
});

// Later
await shutdown();
```

### 提供者检测

代理自动检测目标提供者 `Host` 头曰. 设置您的 LLM 客户端的基址 `http://localhost:4000` 而代理处理路由.

如果自动检测失败, 请设置 `x-target-url` 明确指定上游基址的头条 .

### API 密钥注入

何时 `providerKeys` 配置后,代理给每个提供者注入正确的认证头:

| 提供者 | 页眉 |
| --- | --- |
| OpenAI,Mistral, Cohere, DeepSeek, Moonshot, Zhipu, MiniMax, Baichuan, Yi (英语) | `Authorization: Bearer <key>` |
| 安东尼 | `x-api-key: <key>` |
| 谷歌 | `x-goog-api-key: <key>` |

如果客户端已经提供了认证头,则代理机不会覆盖它.

### 限制费率

何时 `rateLimits` 配置,代理服务器执行每个提供者的滑动窗口率限制。 超过限额的请求收到 a `429` 答复 `Retry-After` 头曰.

### 健康检查

```
GET http://localhost:4000/health
```

## 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `port` | `number` | `4000` | 代理监听端口 |
| `apiKey` | `string` | **所需经费** | Agent Trace 服务器的认证符 |
| `agentId` | `string` | **所需经费** | 记录事件的代理身份 |
| `endpoint` | `string` | —— 说 | 事件摄取 URL |
| `flushInterval` | `number` | `5000` | 事件缓冲间隔( ms) |
| `maxBufferSize` | `number` | `50` | 自动擦拭前最大缓冲事件 |
| `providerKeys` | `Record<string, string>` | —— 说 | 要注入的 API 密钥提供者 |
| `rateLimits` | `Record<string, RateLimitConfig>` | —— 说 | 每方供应商费率限额 |

## 许可证

阿帕奇 - 2.0

## 常见问题

### @agenttrace/proxy 是什么？

AgentTrace 代理服务器用于缓冲和转发代理事件

### 如何安装 @agenttrace/proxy？

在项目目录运行 npm install @agenttrace/proxy，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 agenttrace-proxy，可以用 npx agenttrace-proxy 直接运行。

### @agenttrace/proxy 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agenttrace/proxy 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @agenttrace/proxy 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agenttrace/proxy 可以商用吗？

@agenttrace/proxy 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @agenttrace/proxy 的下载量有多少？

根据 npm 官方下载统计，@agenttrace/proxy 在 2026/10/05 – 2026/11/03 这 30 天内被下载 3,948 次，日均约 132 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agenttrace/proxy 还在维护吗？

最新版本 0\.1\.0 发布于 2026/02/06（9 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/02/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。