# @buddy-works/docs-schema 中文文档

规范地址：https://npmcn.com/package/%40buddy-works/docs-schema/

版本：0\.1\.4
npm 元数据更新时间：2026-11-05T10:18:32.840Z
中文译文更新时间：2026-11-08T19:45:22.467Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40buddy-works/docs-schema
原文对照：https://npmcn.com/package/%40buddy-works/docs-schema/?lang=original

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

- 包体积（解压后）：365 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：4 个
- 首次发布：2026-09-02T07:29:53.511Z
- 最新版本发布：2026-11-05T10:18:32.716Z
- 近 30 天下载量：2804（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Buddy的YAML和REST API计划,取出,缓存并解为有文件记录的形状

## 安装

```sh
npm install @buddy-works/docs-schema
```

也可以使用：`pnpm add @buddy-works/docs-schema`、`yarn add @buddy-works/docs-schema`、`bun add @buddy-works/docs-schema`

## README

# @buddy-works/docs-schema (英语)

获取 Buddy 的 YAML 和 REST API 计划并把它们解为形状 提供或搜索。 接下来 `$ref` 平面指针 `allOf`并保持阴茎, 限制和实例.

## 安装

```bash
npm install @buddy-works/docs-schema
```

## 使用量

```ts
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"`。每个缓存会分开,所以进程可以 立即按住两个:

```ts
const live = await BuddySchema.load();
const stage = await BuddySchema.load({ environment: "stage" });
```

## 自己提供文件

如果你已经有计划了,交给他们 而不是让包裹 获取。 覆盖了被绑定的版本,磁盘上的文件,或不是 发表。 无所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而无所取而有所取而有所取而有所取而有所取而有所取而有所取而无所取而无所取而有所取而有所取而有所取而有所取而无所取而有所取而有所取而有所取而无所取

```ts
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和获取时间,它们来自哪个部署,是否写入缓存失败,结果缓存的条目被点击并丢失. |

### 选项

```ts
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 的计划 范围为根,上面的方法读取相同的方案。 任何其它的瞄准镜.

```ts
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` | 细节 | 含义 |
    | --- | --- | --- |
    | `syntax` | `line?`, (中文(简体) ), `column?` | YAML不解析,或者里面的一个别名没有锚或扩展而无尾. 块. 异形没有位置. |
    | `document` | `expected`, (中文(简体) ), `got` | 不是范围需要的文件类型,是条目列表或一个条目. 一个空文件都不是 。 块. |
    | `empty` |  | 无条目列表 . |
    | `shape` | `expected`, (中文(简体) ), `got` | 错误类型的值,例如对象所属的单词. |
    | `missingType` | `key` | 未命名其类型的项目 . |
    | `unknownType` | `key`, (中文(简体) ), `value`, (中文(简体) ), `suggestion?` | 工会没有这种类型,离工会关系最近. |
    | `missingKey` | `key` | 缺少的必要密钥 . |
    | `emptyValue` | `key` | 需要的无值密钥 。 警告:巴迪将其保存为空弦. |
    | `emptyItem` |  | 无值的列表项目 。 巴迪拒绝文件. |
    | `unknownKey` | `key`, (中文(简体) ), `suggestion?` | 密钥计划没有声明 。 策略关闭对象时出错, 警告打开对象时出错, 没有规则检查这些键( 打破规则的值是 ) `schema` 寻找). |
    | `schema` | `keyword`, (中文(简体) ), `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` 连接到它开始的版本 带.

## 常见问题

### @buddy-works/docs-schema 是什么？

Buddy的YAML和REST API计划,取出,缓存并解为有文件记录的形状

### 如何安装 @buddy-works/docs-schema？

在项目目录运行 npm install @buddy-works/docs-schema，或使用 pnpm add / yarn add / bun add。

### @buddy-works/docs-schema 支持 TypeScript 吗？

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

### @buddy-works/docs-schema 支持 ESM 还是 CommonJS？

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

### @buddy-works/docs-schema 需要什么版本的 Node\.js？

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

### @buddy-works/docs-schema 可以商用吗？

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

### @buddy-works/docs-schema 的下载量有多少？

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

### @buddy-works/docs-schema 还在维护吗？

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