饲料(@fungi.computer/forage(中文(简体) )
Forage 列表、搜索和描述一个主机拥有的操作目录 已经提供了,所以一个呼叫者或一个模型可以找到正确的一个名字或由 说明。 它帮助呼叫者发现一种能力. 它不执行 有能力或允许使用.
安装或设置
npm install @fungi.computer/forage
包装船只实行无害环境管理,并依赖Zod、YAML、JSON Schema Ref Parser和
应用程序发布 在运行时间。 每个操作的输入和
输出是执行标准 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万多个扩展节点后再进行递归解码;调用器绑定
分别运输字节.
快开始
这个示例创建了一个不可改变的目录,搜索它,以及 描述一个操作 :
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。 。 。 .
核心概念
一个目录有呼叫器提供的修订和一套操作. 每次行动
拥有一个独特的点化路径,一个输入计划,以及可选描述,能力
注释、指示和输出方案。 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。 。 。 .
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 参考文献覆盖
Forage.createCatalog,则 createCatalog 函数、操作定义和
搜索和描述结果类型.
实例和检查
现有的目录套件包括验证、确定性搜索和 说明和目录邮票。 运行它与 :
pnpm --filter @fungi.computer/forage test
限制和错误
饲料是不可改变的发现数据. 它没有执行人,证书,
授权状态,刷新操作,或主机客户端. 结果是 search
或者说 describe 不运行操作。 执行人必须这样做
分别决定.
目录必须包含至少一个操作,并且不能重复操作
路径。 Forage 定义元数据并给出描述 。 无效或超大小
输入抛出 ForageError. 稳定印章识别不可改变的发现
快照,不是执行行动的权限.
贡献和许可证
饲料是麻省理工学院的许可。 见 LICENSE。其保留来源
归属和通知在 THIRD_PARTY_NOTICES。 。 。 .
动态 App 工具计划
appToolFamilySchemas(api, reply) 通过它验证动态列表
,然后用
普通的 App schema 解码器. 传回姓、电话、申报
效果和要求,加上行及其验证器。 一个 unindexed 列名
没有工具。 应用程序选择器仍然是行数据;主机构造
透过App的电话主调用 投影没有处理器,
约束默认或权威。 SDK 模块和标签的 MCP 工具可以消耗
相同的行和验证符.