@buddy-works/docs-schema (英语)
获取 Buddy 的 YAML 和 REST API 计划并把它们解为形状
提供或搜索。 接下来 $ref 平面指针 allOf并保持阴茎,
限制和实例.
安装
npm install @buddy-works/docs-schema
使用量
import { BuddySchema } from "@buddy-works/docs-schema";
const parser = await BuddySchema.load();
await parser.actions.list(); // every action a pipeline can run
await parser.actions.get("AMAZON_S3"); // one action, in full
await parser.actions.search("notify"); // the ones that send notifications
await parser.search("deploy to s3"); // across YAML and the REST API
await parser.api.endpoint("GET", "/workspaces/{workspace_domain}/projects");
如何得到计划
BuddySchema.load() 从本地缓存中读取,并重验证 HTTP
一旦缓存是3小时。 A 304 保存缓存副本并启动
窗口。 一个200取代该文件。 在电话需要之前,什么都拿不到
它,所以一个只询问动作的过程从不下载 OpenAPI
文档.
在MCP服务器等长期运行的过程中,检查会在背景中运行 和来自记忆的呼叫回答。 查询从不在网络上等待 。 当一个200 土地、新文件、旧文件的成形成果 被丢弃。 一个已经在飞行中的查询会根据它开始的图表完成.
不解析或缺乏其范围所依赖的关键的反应是:
拒绝。 之前的好副本留在原地,而不是被一个
错误页 。 如果服务器完全无法到达, 缓存的复制件会一直存在
服务 stats() 报告 staleSince 该文件.
它读取生产,除非 environment 说不然。 其他名称是:
"stage", (中文(简体) ), "master" 财务报告和审定财务报表 "dev"。每个缓存会分开,所以进程可以
立即按住两个:
const live = await BuddySchema.load();
const stage = await BuddySchema.load({ environment: "stage" });
自己提供文件
如果你已经有计划了,交给他们 而不是让包裹 获取。 覆盖了被绑定的版本,磁盘上的文件,或不是 发表。 无所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而有所取而有所取而无所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而无所取
import { readFileSync } from "node:fs";
const parser = BuddySchema.from({
pipelines: JSON.parse(readFileSync("yaml-schema.json", "utf8")),
});
密钥是文档,而不是范围,以及 pipelines 背对其中两个:
| 密钥 | 服务范围 |
|---|---|
pipelines | parser.pipelines, (中文(简体) ), parser.actions |
targets | parser.targets |
environments | parser.environments |
sandboxes | parser.sandboxes |
agents | parser.agents |
domains | parser.domains |
customActions | parser.customActions |
distributions | parser.distributions |
api | parser.api |
达到你没有提供文件的范围 和名称是什么 给出.
方法
这九份文件有十个范围 提供什么范围取决于它
计划宣布, 类型执行它. parser.agents.list() 没有
编译,因为schema特工没有工会.
每个YAML 范围
| 方法 | 它会做什么 |
|---|---|
names(options?) | 文档中的定义名称,减去计划退出的名称. { includeDeprecated: true } 也列出这些.await parser.pipelines.names() → ["PipelineYaml", "TransferActionYaml", …] |
def(name) | 一个定义作为文档:字段,它所指的类型,示例.await parser.pipelines.def("VariableYaml") |
properties(name) | 同一定义被平整成地产行,表格的形状。 文档不声明名称为空 .await parser.pipelines.properties("VariableYaml") |
search(query, options?) | 排名击出. 质询被分解成单词和结果排序,按它们匹配的数量排列,因此一个整个问题都有效.await parser.actions.search("notify") → ROLLBAR, SMS, HONEYBADGER…await parser.search("deploy to s3") → AMAZON_S3… |
search(query, { fuzzy: true }) | 同样的,容忍的打字。 默认关闭, 因为松散的匹配 排名高于准确的.await parser.actions.search("varibles", { fuzzy: true }) → SET_VARIABLES… |
search(query, { includeDeprecated: true }) | 退休的成员和定义也一样。 默认关闭,像 list(): 搜索是呼叫者如何找到要使用的.await parser.actions.search("sandbox") 只有活着的人 |
有根的范围
pipelines, (中文(简体) ), targets, (中文(简体) ), environments, (中文(简体) ), sandboxes, (中文(简体) ), agents, (中文(简体) ), domains, (中文(简体) ),
customActions, (中文(简体) ), distributions
root() 给出文档的条目类型: 该路径上的 YAML 文件可能是什么
包含. await parser.pipelines.root() 返回时 PipelineYaml 文档.
工会的范围
actions, (中文(简体) ), targets, (中文(简体) ), environments
| 方法 | 它会做什么 |
|---|---|
list(options?) | 歧视者重视工会的接受,减去计划退休者.await parser.targets.list() → ["SSH", "FTP", "MATCH", …]{ includeDeprecated: true } 也列出这些. get() 财务报告和审定财务报表 search() 给一个退休成员回答 无论是哪种方式. |
get(value) | 一个全名成员:名称、Docs sult、标记、所需字段、实例、属性和形状文档.await parser.actions.get("BUILD")outputs 保持行动留下的痕迹: files 带有 path 财务报告和审定财务报表 description,以及 variables 带有 name, (中文(简体) ), description 财务报告和审定财务报表 example。两份名单对于宣布无名单的成员都是空的.(await parser.actions.get("HTTP")).outputs.variables → BUDDY_HTTP_ACTION_RESPONSE_STATUS… |
commonFields() | 向工会每个成员申报.await parser.actions.commonFields() → ["type", "action", "trigger_time", …] |
pipelines
| 方法 | 它会做什么 |
|---|---|
eventVariables(type?) | 运行的变数暴露在它开始的事件上。 每个都有 name, (中文(简体) ), description 财务报告和审定财务报表 example。没有类型,每个事件类型都会暴露任何类型.await parser.pipelines.eventVariables("PUSH") → BUDDY_RUN_EVENT_TYPE…一个不曝光的事件类型, 例如 SCHEDULE,给出一个空列表. |
api
| 方法 | 它会做什么 |
|---|---|
operations() | 文档宣布的每一项操作,及其 summary, (中文(简体) ), operationId, (中文(简体) ), tags, (中文(简体) ), deprecated 财务报告和审定财务报表 security。没有解决任何问题,所以列出每个终点需要一次行走而不是一次操作.await parser.api.operations() |
endpoint(method, path, variant?) | 作为文件的操作:参数,请求正文,响应. 过 variant 选择工会机构的一个分支.await parser.api.endpoint("POST", "/oauth2/register")机构是一个清单: request.contents 和每个响应的 contents 按照文档的顺序,每个媒体类型都有一个条目,所以下载一个字节流 财务报告和审定财务报表 a JSON信封均报告。 宣布无内容的地位是没有的. |
variants(method, path) | 歧视者的价值你可以通过 variant当身体被命名为类型时空出。 这些形状在文档上,在 request.contents[0].body.variants。 。 。 . |
type(name) | 一个命名为schema的文档, 对于一个字段中的类型名称。 保存其端点的回接.await parser.api.type("ExecutionView") |
typeNames(options?) | 每一个计划名称 文档宣布,减去退休的. |
search(query, options?) | 如上,在操作摘要、路径和标记上. |
在客户端
| 方法 | 它会做什么 |
|---|---|
search(query, options?) | 每个范围都有一个指数,YAML和REST加在一起. 缩小范围 { scopes: ["actions"] }。二十次点击,除非 limit 说不然.每次命中都带着 kind, (中文(简体) ), scope, (中文(简体) ), key, (中文(简体) ), name, (中文(简体) ), tags, (中文(简体) ), score。 。 。 . |
raw(document) | 未解决的文件, $ref 指针完好无损 用来校正他们或者阅读 $defs 直接说. |
prefetch(documents?) | 而不是第一个请求 下 from() 本报告 { refreshed: [], reason: "documents were supplied" } 而不是扔东西. |
release(document) | 丢弃取来的文件及其决议备忘录 。 形状-结果缓存是共享的,因此它是被完全空出而不是每个文档. 回返 false 提供的文件,不能重新获得. |
stats() | 哪些文件被持有,它们的ETag和获取时间,它们来自哪个部署,是否写入缓存失败,结果缓存的条目被点击并丢失. |
选项
await BuddySchema.load({ environment, cacheDir, ttlMs, results });
BuddySchema.from(documents, { results });
environment 是以上名称之一. cacheDir 财务报告和审定财务报表 ttlMs 滚回原地
下面的变量. results 限制有多少形状文件。 过 false
{\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}让每个电话都恢复.
错误
DocumentUnavailableError: 没有获取和缓存副本 。 名称 URL 和点数BuddySchema.from()。 。 。 .MissingDocumentError:达到其文件的范围from()没有 给出。 列出是什么.ScopeUnsupportedError: 提供的文档不是范围范围的设计 需要帮助。 表示所期望的,所发现的,以及最近的现存名称.
验证 YAML 文件
@buddy-works/docs-schema/validate 检查 YAML 文件与 a 的计划
范围为根,上面的方法读取相同的方案。 任何其它的瞄准镜.
import { validateYaml } from "@buddy-works/docs-schema/validate";
const report = await validateYaml(parser, "pipelines", yaml);
报告载有: findings, (中文(简体) ), checked 财务报告和审定财务报表 blocked。 。 。 . blocked 实值 true 仅限
当文件完全无法读取为范围文档时。 其他的发现
是忠告,而拒绝的,是打电话者的电话.
每个发现都有一个 severity页:1 message (单位:千美元) path 例如
pipelines[0].actions[1].type,它们一起读作一行。 为了什么
另外,请使用其余部分:
-
at: 与段相同的位置,[0, "actions", 1, "type"]. 调查结果 关于关键点. -
code:出了什么问题,旁边的细节是:code细节 含义 syntaxline?, (中文(简体) ),column?YAML不解析,或者里面的一个别名没有锚或扩展而无尾. 块. 异形没有位置. documentexpected, (中文(简体) ),got不是范围需要的文件类型,是条目列表或一个条目. 一个空文件都不是 。 块. empty无条目列表 . shapeexpected, (中文(简体) ),got错误类型的值,例如对象所属的单词. missingTypekey未命名其类型的项目 . unknownTypekey, (中文(简体) ),value, (中文(简体) ),suggestion?工会没有这种类型,离工会关系最近. missingKeykey缺少的必要密钥 . emptyValuekey需要的无值密钥 。 警告:巴迪将其保存为空弦. emptyItem无值的列表项目 。 巴迪拒绝文件. unknownKeykey, (中文(简体) ),suggestion?密钥计划没有声明 。 策略关闭对象时出错, 警告打开对象时出错, 没有规则检查这些键( 打破规则的值是 ) schema寻找).schemakeyword, (中文(简体) ),params计划的其他规则. -
declaredIn:在一个未知的密钥上,允许有密钥的密钥被宣布, 行动类型或范围的定义。 点一个读者,比如 与parser.actions.get(type)或者说parser.pipelines.def(name)。 。 。 .
checked 列出可以匹配的每个条目、项目和对象区域
以定义为基础, 缺少类型、类型
工会是不存在的,或者是错误的。 每个都带着这个
定义(一个纯值没有)和联盟选择的变体。 一个节点通过
当找不到时 at 从它自己的开始.
在Buddy保存了文件后,它可能已经丢掉密钥或重新命名了它们.
reconcileWithSaved(findings, sentYaml, savedYaml) 比较当时的文件
随保存的文件一起发送 :
- 它放弃了对保存文件的密钥的查找, 以该名或该名下 另一个.
- 它标志着一个未知的密钥, 保存的文件丢失为
not saved by Buddy。 。 。 .
所需资源
节点20.19或更新,或Bun.
缓存在 ~/.buddy/docs-schema,每个文档一对文件:
身体和它的ETAG。 两种环境变量覆盖默认值:
BUDDY_DOCS_SCHEMA_CACHE: 缓存目录.BUDDY_DOCS_SCHEMA_TTL:毫秒缓存副本保持新鲜.0重新验证每个访问.Infinity连接到它开始的版本 带.