# @agentskit/net 中文文档

规范地址：https://npmcn.com/package/%40agentskit/net/

版本：0\.2\.4
npm 元数据更新时间：2026-10-24T15:08:27.414Z
中文译文更新时间：2026-11-05T20:34:15.873Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/net
原文对照：https://npmcn.com/package/%40agentskit/net/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/net
源码仓库：https://github.com/AgentsKit-io/agentskit

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

- 包体积（解压后）：256 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：3 个
- 首次发布：2026-09-28T13:46:16.396Z
- 最新版本发布：2026-10-24T15:08:26.245Z
- 近 30 天下载量：25864（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

AgentsKit 生态系统的可耐性、可约束性和SSRF-安全HTTP:用Retry-after重试、超时、有尺寸限制的身体、SSE解析和私人地址检查。 在Node, Bun, Deno,浏览器和边缘运行.

## 安装

```sh
npm install @agentskit/net
```

也可以使用：`pnpm add @agentskit/net`、`yarn add @agentskit/net`、`bun add @agentskit/net`

## README

# @ agentskit/net (英语)

简介 : `concise-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

用于代理的HTTP管道,在一个小包中:带有后置和 `Retry-After`, 任意超时, 限定对象读取, 服务器发送事件, 以及 SSRF 地址检查。 Web API只运行于节点, Bun, Deno,浏览器和边缘运行时间.

[![npm version](https://img.shields.io/npm/v/@agentskit/net?color=blue)](https://www.npmjs.com/package/@agentskit/net) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/net)](https://www.npmjs.com/package/@agentskit/net) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/net?label=bundle)](https://bundlejs.com/?q=@agentskit/net) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `agentskit` • 妇女 `ai-agents` • 妇女 `fetch` • 妇女 `retry` • 妇女 `sse` • 妇女 `ssrf` • 妇女 `timeout` • 妇女 `edge`

## 已核实的证据

-   软件包元数据和单元测试在下面进行 `packages/net/`。 。 。 .
-   决定记录: [ADR-0037 (英语)](https://npmcn.com/package/docs/architecture/adrs/0037-net-package.md)。 。 。 .
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

适配器、工具和其他代理Kit存储器 各自携带自己的重试回路, `Retry-After` 解析,SSE行分解器和私人-IP检查,每条都有不同的bug. `@agentskit/net` 拥有它们,在 `eventsource-parser` 财务报告和审定财务报表 `ipaddr.js`,因此,呼叫者导入一个已测试的执行.

-   **探员Kit**数字 : `@agentskit/adapters` (流线、回流)和 `@agentskit/tools` (比对用户提供的URL)是预定的消费者.
-   **书记官处**: 随时可以使用的代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/net) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 安装

```bash
npm install @agentskit/net
```

## 快速实例

```ts
import { assertPublicUrl, fetchWithRetry, parseSSEResponse, readJson } from '@agentskit/net'

// Refuse private, loopback and metadata addresses before fetching a user-supplied URL.
const { url } = await assertPublicUrl('https://api.example.com/v1/models')

// Idempotent requests retry on 429/5xx, honouring Retry-After; each attempt times out.
const models = await readJson(await fetchWithRetry(url, undefined, { timeoutMs: 10_000 }), {
  maxBytes: 1_000_000,
})
console.log(models)

// Server-sent events as an async iterable.
const stream = await fetch('https://api.example.com/v1/stream', { method: 'POST' })
for await (const event of parseSSEResponse(stream)) {
  if (event.data === '[DONE]') break
  console.log(event.event ?? 'message', event.data)
}
```

## 特征

| 区域 | API 密码 | 替换 |
| --- | --- | --- |
| 重试 | `retry`, (中文(简体) ), `computeBackoff`, (中文(简体) ), `parseRetryAfter`, (中文(简体) ), `isRetryableStatus`, (中文(简体) ), `RETRYABLE_STATUSES` | 手写 `for` 有固定睡眠的循环, 忽略 `Retry-After` |
| 获取 | `fetchWithRetry` | 重试两次 POST , 漏出已丢弃的响应机构, 超过所有尝试的超时 |
| 超时 | `timeoutSignal`, (中文(简体) ), `anySignal`, (中文(简体) ), `withTimeout` | `setTimeout` + 键 `AbortController` 锅炉板 |
| 机构 | `readBody`, (中文(简体) ), `readText`, (中文(简体) ), `readJson` | `await res.text()` 对无约束反应的答复 |
| 证监会 | `parseSSE`, (中文(简体) ), `parseSSEResponse` | `split('\n')` + 键 `startsWith('data: ')` 解析 CRLF 、 多行数据和块边界 |
| 地址 | `assertPublicUrl`, (中文(简体) ), `isPublicAddress`, (中文(简体) ), `classifyAddress` | regexs 结束 `127.`编号 :`10.`编号 :`192.168.` 错过 IPv6、 IPv4 和元数据地址 |

-   **默认缺额**数字 : `fetchWithRetry` 复试 获得/获得/获得/得到/得到/得到/得到/得到/得到/得到/得到/获得;通过 `retryMethods: 'all'` 选入 POST 。 流体从不复试.
    
-   **输入错误**数字 : `NetError` 与 `AK_NET_TIMEOUT`, (中文(简体) ), `AK_NET_BODY_TOO_LARGE`, (中文(简体) ), `AK_NET_BLOCKED_ADDRESS`, (中文(简体) ), `AK_NET_INVALID_INPUT`, (中文(简体) ), `AK_NET_SSE_PARSE_FAILED`。 。 。 .
    
-   **DNS 已经注射**数字 : `assertPublicUrl` 使用一个 `lookup` 函数,所以软件包没有 `node:` 进口。 连接前的检查不会停止 DNS 重新绑定; 将已解决的地址绑定为重要 .
    
-   **建造在**数字 : `eventsource-parser`, (中文(简体) ), `ipaddr.js`。 。 。 .
    
-   **护卫规则**数字 : `NET_RULES` (单位:千美元)`readonly NetRule[]`从 `@agentskit/net/rules` 检测重复 HTTP 重试、 SSE、 超时、 地址和身体处理。 添加 `@agentskit/cross-platform` 作为运行扫描仪的 dev 依赖; 传出 `NET_RULES` 改为 `scanText(file, source, rules)` 或者说 `scanRepository(options)`。两个返回结论都认为: `compareToBaseline(findings, baseline)` 鼠标。 使用 `<id>-ignore: <reason>` 例如,对经核准的单一规则的禁止 `net-retry-after-ignore: legacy retry handler`。存储器检查是 `node scripts/check-net-rules.mjs`。 。 。 .
    
    ```ts
    import { NET_RULES } from '@agentskit/net/rules'
    import { scanText } from '@agentskit/cross-platform'
    
    const findings = scanText('src/http.ts', 'const body = await response.text()', NET_RULES)
    console.log(findings.length)
    ```
    

## 可撤销的等待和最后期限

`sleep(ms, signal?)` 接受0至2,147,483,647毫秒的延迟。 它默认使用可中止的定时器,在中止时清除该定时器,并用信号的实际理由拒绝. `retry` 默认使用此公共助手; 其可选 `sleep` 回调有形状 `(ms, signal?) => Promise<void>`。单参数调用仍然兼容;需要立即取消的调用应尊重可选信号.

`withTimeout(work, ms, parent?)` 接受2,147,483,647毫秒的正期限,并传递在最后期限或母信号中止时中止的信号。 逾期的最后期限被拒绝 `NetError` 代码 `AK_NET_TIMEOUT`; 无效的超时 `AK_NET_INVALID_INPUT`. 呼叫者流产保留其确切原因,成功或原工作失败不会改变。 包装者拒绝准时,即使工作忽略了信号,但只有合作工作,如 `fetch` ; 任意 JavaScript 无法强制取消.

```ts
import { retry, sleep, withTimeout } from '@agentskit/net'

const parent = new AbortController()
const response = await withTimeout(
  signal => fetch('https://api.example.com/data', { signal }),
  5_000,
  parent.signal,
)

await retry(async () => fetch('https://api.example.com/retry'), {
  sleep: (ms, signal) => sleep(ms, signal),
})
```

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 核心](https://www.npmjs.com/package/@agentskit/core) | `AgentsKitError`基础 `NetError` |
| [@ agentskit/ 适应器](https://www.npmjs.com/package/@agentskit/adapters) | 供应商流动和重复 |
| [@ agentskit/ 工具](https://www.npmjs.com/package/@agentskit/tools) | 安全获取用户提供的 URL |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)没有1.0.
-   **节点.js 20+** (20.19+), Bun, Deno, 现代浏览器和边缘运行时间; **类型脚本** 严格模式
-   发表于 `@agentskit/net`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @agentskit/net 是什么？

AgentsKit 生态系统的可耐性、可约束性和SSRF-安全HTTP:用Retry-after重试、超时、有尺寸限制的身体、SSE解析和私人地址检查。 在Node, Bun, Deno,浏览器和边缘运行\.

### 如何安装 @agentskit/net？

在项目目录运行 npm install @agentskit/net，或使用 pnpm add / yarn add / bun add。

### @agentskit/net 支持 TypeScript 吗？

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

### @agentskit/net 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agentskit/net 需要什么版本的 Node\.js？

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

### @agentskit/net 可以商用吗？

@agentskit/net 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentskit/net 的下载量有多少？

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

### @agentskit/net 还在维护吗？

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