# @ancplua/qyl-api-schema 中文文档

规范地址：https://npmcn.com/package/%40ancplua/qyl-api-schema/

版本：14\.0\.1
npm 元数据更新时间：2026-10-19T16:27:49.953Z
中文译文更新时间：2026-11-06T07:06:12.701Z
软件包许可：Apache-2\.0

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

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

弃用说明：Moved into ANcpLua/qyl as internal contracts; no longer published\.

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

- 包体积（解压后）：1.8 MB，44 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：zod \>=4\.5\.0 \<5，@typespec/sse ^0\.87\.0，@typespec/http ~1\.17\.0，@typespec/events ^0\.87\.0，@typespec/openapi ~1\.17\.0，@typespec/compiler ~1\.17\.0，@typespec/openapi3 ~1\.17\.0
- 首次发布：2026-06-26T02:55:27.344Z
- 最新版本发布：2026-10-17T02:56:04.534Z
- 近 30 天下载量：4217（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：62（近 12 个月 62 个）

## 中文简介

Typec Qyl API合同的真相来源. (原始内容存档于2018-10-11). Emits OpenAPI, JSON Schema, Qyl.Api. Contract DTOs, and TypeScript Contract type; 不是 OpenTeleometry 软件包, 存储计划, 或服务器执行 .

## 安装

```sh
npm install @ancplua/qyl-api-schema
```

也可以使用：`pnpm add @ancplua/qyl-api-schema`、`yarn add @ancplua/qyl-api-schema`、`bun add @ancplua/qyl-api-schema`

## README

# @ancplua/qyl-api-schema (英语)

TypeSpec为Qyl客户端可见产品API提供的真实来源. 此寄存器 它不执行服务器, 存储引擎,或OTLP接收器.

合同涵盖每个客户可见的qyl采集器和跑道表面:

-   **追踪** —— 说 `GET /api/v1/traces`,一个跟踪, 及其跨度(`api/routes.tsp`, (中文(简体) ), `otel/span.tsp`) (中文(简体) ).
-   **日志** —— 说 `GET /api/v1/logs` 和现场SSE流 `GET /api/v1/stream/logs` 及其心跳(`api/streaming.tsp`, (中文(简体) ), `otel/logs.tsp`) (中文(简体) ).
-   **计量**,只读 `GET /api/v1/metrics` 列出参数描述符 为一个项目录制, `GET /api/v1/metrics/{metric_name}/series` 列出 在一个标准名称下有不同的属性流,以及 `GET /api/v1/metrics/{metric_name}/query` 跨时间范围合计 1 公分 装入桶中`models/metrics.tsp`) (中文(简体) ). 系列保留其资源和仪器 范围。 使用 `series_id` 当仪器描述符冲突时选择一个精确的流; 模糊范围查询返回 409 。 测量点在OTLP上写着 本合同没有说明。 不支持配置文件 .
-   **会议** —— 说 `GET /api/v1/sessions`,一个会,它的痕迹和 `/stats` (单位:千美元)`models/session.tsp`) (中文(简体) ).
-   **卫生** —— 说 `GET /health` 财务报告和审定财务报表 `GET /alive`,其 `HealthReport` 携带 `contract_revision` 握个手`models/health.tsp`) (中文(简体) ).
-   **MCP工具** qyl MCP工具的输入和结构化输出模型 (单位:千美元)`models/mcp-tools.tsp`) (中文(简体) ).
-   **工作区** 本地 MCP 工作台:会话、工作空间、服务器、协议 流、处决、测试案例、套房、评估运行和出口 (单位:千美元)`api/workbench.tsp`, (中文(简体) ), `models/workbench.tsp`) (中文(简体) ).
-   **运行者** ——本地跑者只回放回放 `/runner/resources` 缩写, SSE 流程、日志和重新启动/停止动作 `collector`, (中文(简体) ), `project` 财务报告和审定财务报表 `command` 流程(`api/runner.tsp`, (中文(简体) ), `models/runner.tsp`. MCP 服务器身份和工具 发现被Workbench连接和发现快照曝光.
-   **共享** ——RFC 9457问题细节(`common/errors.tsp`),光标页 (单位:千美元)`common/pagination.tsp`)和常见的平板`common/`),加奥特尔 资源、跨度和日志预测`otel/`) (中文(简体) ).

遥测本身从未通过本合同更改或删除;保留 将取去. 唯一的可写资源是说明(`/api/v1/annotations`, (中文(简体) ), 保存的查询 (单位:千美元)`/api/v1/saved-queries`,用于跟踪、日志或度量的命名结构过滤器, 运行与 `POST …/{saved_query_id}:run`)和失败状态 (单位:千美元)`PATCH /api/v1/failures/{failure_id}`,记录的失败状态、受让人或 被忽略直到时间。 说明和保存的查询扩展共享的写基础 `common/resource.tsp`: 服务器指定 `id`, (中文(简体) ), `created_at`, (中文(简体) ), `updated_at` 财务报告和审定财务报表 `etag`· ; `Idempotency-Key` 创建, 答案 `201` 与 `Location`· ; `If-Match` 打开 `PATCH` 财务报告和审定财务报表 `DELETE`,拒绝 `428` 失踪时 `412` 讽t 这个 失败状态 `PATCH` 一样 `If-Match`。收集器键带有角色 `ingest`, (中文(简体) ), `read`, (中文(简体) ), `write` 财务报告和审定财务报表 `delete` (单位:千美元)`CollectorKeyRole`); 写入需要 `write`, (中文(简体) ), 删除 `delete`。 。 。 .

## 错误和页面

每个错误机构都是RFC 9457问题 `application/problem+json`数字 : `type`, (中文(简体) ), `title`, (中文(简体) ), `status`, (中文(简体) ), `detail` 财务报告和审定财务报表 `instance`,加上扩展成员 `code`每一个 问题类型修正其 `type` URI (美国)`https://qyl.at/problems/<name>`) 及其定义 `code` (单位:千美元)`not_found`, (中文(简体) ), `validation_failed`,所以客户端的分支 要么,从不 `title` 或者说 `detail`问题机构没有标题。 发布响应头 服务器发送的操作 : `X-Trace-Id` 在收藏家的500个回应, `WWW-Authenticate` 工作台的401个回复.

每个列表操作页都带有不透明的光标。 这需要 `limit` (单位:千美元)`PageLimit`:1至1000,略去时为100)和 `cursor`,其页面带有 `has_more` 在每页中,除末页外, `next_cursor`,下一个请求 发回作为 `cursor`。 。 。 .

## 合同管道

```text
authored Qyl TypeSpec
        |
        +----> OpenAPI ----> bundled JSON Schema
        +----> Qyl.Api.Contracts
        +----> generated TypeScript contracts
```

Qyl域模型,路由,响应,流出事件,以及出错在此被编写. 与OTel兼容的模型载有生产者发送的值; `Qyl.Telemetry.SemanticConventions` 拥有 注册词汇和语义验证. 属性密钥横过线作为打开的字符串地图,所以本合同没有 列出 OpenTeleometry 属性注册 .

## 边界

-   每个客户端可见的Qyl 请求,响应,流事件,以及错误被定义于 此仓库 .
-   OTLP 摄取在运行时间使用 OpenTeleometry protobuf 的官方消息,并且是 这里没有重新定义 .
-   模式 `otel/` qyl线路使用的是客户端的JSON预测,而不是 OTLP电讯信息.
-   收集器存储行、摄入批次、查询模型和内部预测 不跨越 HTTP、 gRPC、 MCP、 流线或生成客户端边界 .

如果运行时形状需要变成客户端可见,请先将其添加到TypeSpec中, 重新生成文物,并将运行时间模型映射到生成的合同.

## 已出版文物

两个登记册都从一个发行标签上印出同样的版本。 合同预付款 它自己的主要节奏,没有跟踪qyl产品版本——它已经是 `5.0.0` 当qyl发射时 `1.0.0`从 npm 或 nuget.org 读取当前版本 而不是从这里的作词;此行移动快于修正的README.

| 生态系统 | 艺术 | 目的 |
| --- | --- | --- |
| npm/ 类型Spec | `@ancplua/qyl-api-schema` | 为 Spec 用户编写的计划 |
| 新建 | `Qyl.Api.Contracts` | 只有BCL产生的.NET合同 |
| 已生成 | OpenAPI, JSON Schema, 类型脚本 | 客户和验证投入 |

`main.tsp` 是本地编译的切入点,并包含发射道. `index.tsp` 是已公布的 TypeSpec 切入点,只包含客户端的创建合同.

### 软件包出口

| 子路径 | 内容 |
| --- | --- |
| `@ancplua/qyl-api-schema` | `index.tsp`,整个类型Spec合同 |
| `@ancplua/qyl-api-schema/otel` | `otel/otel-conventions.tsp`: 仅针对不想要qyl API 的 TypeSpec 消费者的OTel 形状资源, 跨度和日志模型 |
| `@ancplua/qyl-api-schema/types` | 生成类型脚本合同类型和 `CONTRACT_REVISION` 常数 |
| `@ancplua/qyl-api-schema/openapi` | `qyl.openapi.json` |
| `@ancplua/qyl-api-schema/json-schema` | 捆绑的JSON斯克马 |
| `@ancplua/qyl-api-schema/zod` | 运行时间验证器, 下方 |
| `@ancplua/qyl-api-schema/runtime` | 生成的演示文稿助手 `AttributeValue` 匹配器( e)`decodeAttributeValue`, (中文(简体) ), `formatAttributeValue`, (中文(简体) ), `attributeString`, (中文(简体) ), `attributeNumber`, (中文(简体) ), `attributeIdentity`, (中文(简体) ), `matchAttributeValue`)和 `UnixNanos` 字符串助手( e)`parseUnixNanos`, (中文(简体) ), `compareUnixNanos`, (中文(简体) ), `unixNanosDelta`, (中文(简体) ), `unixNanosToEpochMs`, (中文(简体) ), `unixNanosToIso`, (中文(简体) ), `epochMsToUnixNanos`) (中文(简体) ). 撰写于 `src/runtime/`编译为 `generated/runtime/` |

## 运行时间验证

`@ancplua/qyl-api-schema/zod` 从捆绑的 JSON Schema 创建 Zod 验证器 运行时间。 上面是翻译层 `z.fromJSONSchema` ——写入 `src/zod/` 并编入 `generated/zod-runtime/` - 不是第二个手写的计划,所以 合同更改不能留下描述上一个形状的验证符 .

```ts
import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
import type { Span } from "@ancplua/qyl-api-schema/types";

const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
const span = SpanSchema.parse(await response.json());
```

`zod` 是一个可选的对等依赖( e)`>=4.5.0 <5`:消费者不 安装它从不导入此子路径, 其他子路径也不依赖 就在这 定义名称为已公布 `$defs` 键 — OpenAPI 的同名名称 组件和生成的 C# 和 TypeScript 的 DTO 携带——和 `contractDefinitionNames()` 列出全部。 未检查类型参数 与计划相对应,因此与匹配类型从 `./types`。 。 。 .

## 合同修订

`scripts/emit-contract-revision.mjs` 确定性的修改 `sha256:` 加号 合同中的头16个六十六个字符 语义文摘——两入 期间生成的面孔 `bun run compile`一个收藏家报告它建造的修改 因此客户端可以检测到从不同角度构建的同伴 合同,而不是一次发现一个不匹配的字段。 读取 运行中的收藏器或生成的文物的当前值;它是衍生出来的,永远不会 手持着.

打开API `info.version` 是发行版本 : `prepack` 把它印入包装 文档从释放标记中,跟踪文档保留 TypeSpec 的 `0.0.0`编辑 摘要排除 `info.version`,所以一个只改变其版本的版本 该修订版.

## 调查合同

生成的 `Mcp.Tools` 表面覆盖32个工具的qyl MCP集. 26个读取工具中每个都有不同的,有打字的 `POST /api/v1/analysis/<tool_name>` 操作。 结构化上游支持共享匹配者操作器;读取结果带有绝对值 `window` 财务报告和审定财务报表 `coverage` 与无效的未知数。 现有的跟踪、日志、计量和会话REST路径仍然可用.

失败状态通过 `PATCH /api/v1/failures/{failure_id}` 与 `If-Match`。失败的手柄、验证符和光标由采集器进行范围界定和验证。 注释合同支持失败目标,标签,分类和重试键. 这些合同只载有产品数据;遥测运行时间的依赖性仍然存在于其生产者储存库中.

收集器的行为和种子活工具的答案由收集器和MCP套件对照同样的生成的合同进行测试.

## 捐款

如何建造、提供、再生和出版 [捐款额](https://npmcn.com/package/%40ancplua/qyl-api-schema/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @ancplua/qyl-api-schema 是什么？

Typec Qyl API合同的真相来源\. \(原始内容存档于2018-10-11\)\. Emits OpenAPI, JSON Schema, Qyl\.Api\. Contract DTOs, and TypeScript Contract type; 不是 OpenTeleometry 软件包, 存储计划, 或服务器执行 \.注意：该包已被作者标记为弃用——Moved into ANcpLua/qyl as internal contracts; no longer published\.

### 如何安装 @ancplua/qyl-api-schema？

在项目目录运行 npm install @ancplua/qyl-api-schema，或使用 pnpm add / yarn add / bun add。

### @ancplua/qyl-api-schema 支持 TypeScript 吗？

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

### @ancplua/qyl-api-schema 支持 ESM 还是 CommonJS？

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

### @ancplua/qyl-api-schema 需要什么版本的 Node\.js？

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

### @ancplua/qyl-api-schema 可以商用吗？

@ancplua/qyl-api-schema 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ancplua/qyl-api-schema 的下载量有多少？

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

### @ancplua/qyl-api-schema 还在维护吗？

最新版本 14\.0\.1 发布于 2026/10/17（21 天前）；至今共发布 62 个版本，其中过去 12 个月发布了 62 个；首次发布于 2026/06/26。作者已将其标记为弃用，新项目建议寻找替代方案。