# @fungi\.computer/forage 中文文档

规范地址：https://npmcn.com/package/%40fungi.computer/forage/

版本：0\.3\.9
npm 元数据更新时间：2026-11-14T11:58:07.561Z
中文译文更新时间：2026-11-15T18:08:12.057Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fungi.computer/forage
原文对照：https://npmcn.com/package/%40fungi.computer/forage/?lang=original
项目主页：https://github.com/fungi-computer/forage#readme
源码仓库：https://github.com/fungi-computer/forage

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

- 包体积（解压后）：151 kB，36 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-10-15T08:00:26.324Z
- 最新版本发布：2026-11-14T11:58:07.342Z
- 近 30 天下载量：14350（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

纯可活性Zod型能力发现

## 安装

```sh
npm install @fungi.computer/forage
```

也可以使用：`pnpm add @fungi.computer/forage`、`yarn add @fungi.computer/forage`、`bun add @fungi.computer/forage`

## README

# 饲料(`@fungi.computer/forage`(中文(简体) )

Forage 列表、搜索和描述一个主机拥有的操作目录 已经提供了,所以一个呼叫者或一个模型可以找到正确的一个名字或由 说明。 它帮助呼叫者发现一种能力. 它不执行 有能力或允许使用.

## 安装或设置

```sh
npm install @fungi.computer/forage
```

包装船只实行无害环境管理,并依赖Zod、YAML、JSON Schema Ref Parser和 [应用程序发布](https://npmcn.com/package/%40fungi.computer/puffball/README.md) 在运行时间。 每个操作的输入和 输出是执行标准 JSON Schema 的任何计划, 如 Zod 4 stema; Forage只让JSON Schema被它描述. 它的发现 切入点是 `@fungi.computer/forage`; 只使用主机的 OpenAPI 摄取为 `@fungi.computer/forage/openapi`。纯 JSON-Schema 子集解码器是 `@fungi.computer/forage/json-schema-subset`数字 : `jsonSchemaSubset()` 验证 共享前的远程计划 `jsonSchemaToZod` 编译器读取. 这个 子集拒绝引用、正则表达式限制和保留财产 名称在计划或JSON值中的任何位置。 解码器拒绝深度超过32 和5万多个扩展节点后再进行递归解码;调用器绑定 分别运输字节.

## 快开始

这个示例创建了一个不可改变的目录,搜索它,以及 描述一个操作 :

```ts
import { Forage } from "@fungi.computer/forage";
import { z } from "zod";

const catalog = Forage.createCatalog({
  revision: "run-1",
  operations: [
    {
      path: "files.read",
      description: "Read a file",
      input: z.object({ path: z.string() }),
    },
  ],
});

const matches = catalog.search({ query: "read" });
const description = catalog.describe({ path: "files.read" });
const firstPage = catalog.list({ limit: 25 });
```

编目测试 [`test/catalog.test.ts`](https://npmcn.com/package/%40fungi.computer/forage/test/catalog.test.ts)。 。 。 .

## 核心概念

一个目录有呼叫器提供的修订和一套操作. 每次行动 拥有一个独特的点化路径,一个输入计划,以及可选描述,能力 注释、指示和输出方案。 Forage 验证目录,命令其 确定操作,并在目录为时编写一次说明 创建。 要更改目录,请创建新的修订版,而不是更改目录 现有。 每个行动都必须符合一个完整的描述 目录的汇总元数据仍然有界限. 整个命名空间可以超过 说明反应,不使其个别可贬损的行动 无. 使用页面 `list({ namespace })` 并描述一项操作或 选择 `methods` 当宽名空间描述超过响应约束时. 这同样适用于平地取名空间和巢地取名空间的广泛父母; 答复从不截断,答复约束不变.

`search` 排序匹配操作. `describe` 返回被绑定的类型脚本 描述一个操作或命名空间。 操作说明 包含 `inputSchema`,通过标准JSON从同一验证器投出 Schema, 因此调用者可以看到TypeScript 无法显示的长度、 范围和数组界限 运算。 路径可能具有任何命名空间深度; 描述声明可调用 筑巢 `env` 和操作的输入和输出类型。 生成类型别名 将每个路径段分别为 `$`数字 : `computer.echo` 声明 `computer$echo_Input` 财务报告和审定财务报表 `computer$echo_Output`和窝 `computers.local.files.read` 声明 `computers$local$files$read_Input` 财务报告和审定财务报表 `computers$local$files$read_Output`。这让路径与下划线区分 从巢道而出。 同一规则适用于每一个深度. `stamp()` 返回 a 分类目录元数据的稳定身份,包括计划预测, 能力说明和指示.

## 穷尽列名

`forage.list({limit?, cursor?, namespace?})` (或 `catalog.list` 直接) 精确列出每次注册的操作。 排序是按命名空间 (第一个路径段),然后按UTF-16代码进行比较的全操作路径 单位,不当地。 登记令永远不变 同等业务 与搜索不同,不合并为同级.

每页都有 `results`, (中文(简体) ), `total`, (中文(简体) ), `catalogStamp` 财务报告和审定财务报表 `nextCursor`。结果使用 与搜索相同的概要计划(路径、描述、样本和能力) 注; 分数为零,因为上市不排序匹配。 默认和 最高限为50;最低限为1; 跟随 `nextCursor` 直到它无效. 总数 选定命名空间下的所有操作,包括其嵌入 命名空间,不只是这个页面。 譬如说, `namespace: "apps.bazaar"` (单位:千美元) 选择 `apps.bazaar.windows.open`。缺席的命名空间是指每个命名空间; 未知的命名空间返回一个零的空页.

光标对呼叫者来说不透明,属于一个目录印章和命名空间 过滤器。 在任何更改都明显失败后重用光标 。 开始新鲜的 转而列出。 缩小客户绑定操作范围的主机过滤 现有摘要和使用相同的摘要 `listOperations` 拥有者在呼叫前。 这个 不引入另一个登记册或泄露未加限制的路径。 搜索和描述 保留他们现有的合同.

## OpenAPI 摄取

导入 `normalizeOpenApi` 财务报告和审定财务报表 `parseOpenApiTable` 从 `@fungi.computer/forage/openapi` {\\fn华文楷体\\fs16\\1cHE0E0E0}在主机上 此切入点使用 面向节点的参考解析器;中性工人/客人发现消费者使用 核心切入点,不导入摄入量.

`normalizeOpenApi(specText, {authParameter?})` 接受所有者提供的 OpenAPI 3.0/3.1 JSON或YAML. 它返回服务器和认证提示加支持 操作和明确不支持操作的理由。 它不进行采集, 证书访问或执行。 Swagger 2 必须先转换.

摄取范围为2个米B,深度32个,5万个节点和500个操作. 也门 拒绝使用别名和外部引用。 当地参考资料由 JSON Schema Ref Parser 有文件和 HTTP 解析器被禁用; 递归式方案 没有支持。 扩充预算计算每一次共用参考 在递归图解码或编译之前。 投入和宣布JSON成功 计划使用相同的 `jsonSchemaToZod` 编译器作为 App 方法. 带有 被支持的编译器子集不能保存为不支持, 而不是扩大.

操作以默认的 OpenAPI 显示 scalar 路径/ query/ header 参数 序列化和可选 JSON `body`. 其他序列样式、正文 ,引用路径项目和TRACE不支持。 所需路径参数 必须匹配路径。 保留运输头、申报的API-键参数和 拥有者提供 `authParameter` 无法成为来宾输入 。 获得/接受/选择 ; 其他支持的方法是写作。 特殊化方法名称 和储备金 `describe`, (中文(简体) ), `search`, (中文(简体) ), `then` 和 JavaScript 对象成员名称. 路径不能更改来源、 穿行点段或包含查询/ 分解 语法或编码分隔符. 标题名称遵循 RFC 符号语法并排除 运输、转发、证书和处理方法。 原型名称 在解码前被拒绝。 Regex 关键词( Q)`pattern`, (中文(简体) ), `patternProperties`和 全部 `format` 限制是没有支持的。 打开API 3.0 `nullable` 得到支持; OpenAPI 3.1 必须使用无效类型 。 拒绝未知的策略关键字 .

提供方编写的说明/说明的范围为2 048个 字符,标题为200;标记为16个条目,每个条目64个字符. 操作标记为 `third_party`;主机必须将其设定为数据. 服务器 提示不需要用户信息, 需要 HTTPS; 相对提示相对于 检索到光谱 。 提示不授予网络录用, 不选择证书 目的地:属于私人Veil行刑门.

`parseOpenApiTable(selectedOperations)` 前解码 1 - 64 支持的方法 存储,拒绝512 KiB以上的重复名称和表格,并返回一个平稳 SHA-256摘要. 它储存正常的图案 和调用形状, 从来没有原始的规格或 证书。 编译器结果, 没有声明输出限制, 仍然需要 执行所有者绑定的 JSON 输出解码器。 没有摄入量和表格 验证授予执行权限或验证服务器的网络 承认。 连接器所有者从 HTTP 创建的服务器预览中选择 方法+路径,从不提供客户端操作机构或生成方法名称; 相撞后缀可以在光谱变化时改变.

纯摄入量和选取表定律在 [`test/openapi.test.ts`](https://npmcn.com/package/%40fungi.computer/forage/test/openapi.test.ts)。 。 。 .

## API 参考

### 附加后端方法

`appApiOperations(bindingName, api)` 运行一个解码的 App 释放 API 操作,例如 `PRINTS.generate`,称为 `env.PRINTS.generate()`页:1 点数方法 `desktop.arrange` 实值 `env.TOURTOIS.desktop.arrange()`应用 作者在构建过程中通过 Agar 生成 API; Forage 使用相同的 声明而不是第二个方法列表。 主办方提供 安装绑定名称, 并可在明确的作用下投射相同的 API 别名.

`appMethodSchemas(api)` 提供相同的转换输入和输出计划, 说明、效果和要求. `appToolSchemas(api)` 在排除标记的方法后使用相同的转换器 `hidden: true`。 。 。 . `appApiOperations` 和主机代理/ MCP 发现共享此功能 过滤投影. `appMethodSchemas` 保留所有已宣布的直接方法 RPC验证器. 转换申报没有授权执行.

每种可见方法都可以搜索,在 `describe`。 。 。 . 描述 `PRINTS` 返回可调用巢穴 `env` 声明为 一个同步的方法。 预测包括宣布的效果和能力 要求作为发现说明。 它不提供行刑人员或许可 赠款.

生成声明的往返和巢穴描述由 枢纽企业 `app-api-discovery` 测试.

见生成 [Forage API 参考文献](https://npmcn.com/package/%40fungi.computer/forage/docs/api/README.md)覆盖 `Forage.createCatalog`,则 `createCatalog` 函数、操作定义和 搜索和描述结果类型.

## 实例和检查

现有的目录套件包括验证、确定性搜索和 说明和目录邮票。 运行它与 :

```sh
pnpm --filter @fungi.computer/forage test
```

## 限制和错误

饲料是不可改变的发现数据. 它没有执行人,证书, 授权状态,刷新操作,或主机客户端. 结果是 `search` 或者说 `describe` 不运行操作。 执行人必须这样做 分别决定.

目录必须包含至少一个操作,并且不能重复操作 路径。 Forage 定义元数据并给出描述 。 无效或超大小 输入抛出 `ForageError`. 稳定印章识别不可改变的发现 快照,不是执行行动的权限.

## 贡献和许可证

饲料是麻省理工学院的许可。 见 [`LICENSE`](https://npmcn.com/package/%40fungi.computer/forage/LICENSE)。其保留来源 归属和通知在 [`THIRD_PARTY_NOTICES`](https://npmcn.com/package/%40fungi.computer/forage/THIRD_PARTY_NOTICES)。 。 。 .

## 动态 App 工具计划

`appToolFamilySchemas(api, reply)` 通过它验证动态列表 ,然后用 普通的 App schema 解码器. 传回姓、电话、申报 效果和要求,加上行及其验证器。 一个 `unindexed` 列名 没有工具。 应用程序选择器仍然是行数据;主机构造 透过App的电话主调用 投影没有处理器, 约束默认或权威。 SDK 模块和标签的 MCP 工具可以消耗 相同的行和验证符.

## 常见问题

### @fungi\.computer/forage 是什么？

纯可活性Zod型能力发现

### 如何安装 @fungi\.computer/forage？

在项目目录运行 npm install @fungi\.computer/forage，或使用 pnpm add / yarn add / bun add。

### @fungi\.computer/forage 支持 TypeScript 吗？

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

### @fungi\.computer/forage 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @fungi\.computer/forage 可以商用吗？

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

### @fungi\.computer/forage 的下载量有多少？

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

### @fungi\.computer/forage 还在维护吗？

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