# @afps-spec/schema 中文文档

规范地址：https://npmcn.com/package/%40afps-spec/schema/

版本：0\.12\.0
npm 元数据更新时间：2026-10-18T22:19:03.937Z
中文译文更新时间：2026-11-06T03:27:53.786Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：156 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2026-03-15T21:57:35.513Z
- 最新版本发布：2026-10-18T22:19:03.615Z
- 近 30 天下载量：5587（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 27 个）

## 中文简介

Zod schemas并生成了JSON Schema 2020-12定义,用于AFPS 0.3显示(代理,技能,mcp-server,集成).

## 安装

```sh
npm install @afps-spec/schema
```

也可以使用：`pnpm add @afps-spec/schema`、`yarn add @afps-spec/schema`、`bun add @afps-spec/schema`

## README

# AFPS JSON 斯克马斯

机能可读表示AFPS规格. 规格文本( E)[光谱md](https://npmcn.com/package/spec.md))是规范来源.

## npm 软件包

此目录作为 `@afps-spec/schema` 时间npm。 执行可以导入Zod计划并扩展其:

```typescript
import { agentManifestSchema } from "@afps-spec/schema";

const myAgentSchema = agentManifestSchema.extend({
  // Extensions go under `_meta`, keyed by a reverse-DNS namespace (spec §10).
  _meta: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
});
```

### JSON Schema 代号

从 AFPS Zod 计划生成 JSON Schema 文件时, 使用导出的文件 `afpsJsonSchemaOverride` 确保 `input.schema` 财务报告和审定财务报表 `output.schema` 字段参考官方 JSON Schema 2020-12 meta-schema:

```typescript
import { toJSONSchema } from "zod/v4/core";
import { agentManifestSchema, afpsJsonSchemaOverride } from "@afps-spec/schema";

const jsonSchema = toJSONSchema(agentManifestSchema, {
  target: "draft-2020-12",
  override: afpsJsonSchemaOverride,
});
```

没有覆盖, 这些字段序列化为不透明 `{}` 对象,因为 AJV meta-schema 验证不能被 Zod 代表 `toJSONSchema()` 一个人.

## 版本计划

Schemas按主要版本排列:

```
schema/
├── v0/                   ← AFPS v0.x schemas
│   ├── agent.schema.json
│   ├── skill.schema.json
│   ├── mcp-server.schema.json
│   └── integration.schema.json
├── src/
│   ├── schemas.ts        ← Zod source (generates v0/)
│   ├── generate.ts       ← Generation script
│   └── index.ts          ← npm entry point
└── package.json          ← @afps-spec/schema
```

URL 遵循模式 `https://schemas.afps.dev/v0/<type>.schema.json`。 。 。 .

这个 `mcp-server.schema.json` 验证 MCP Bundle (MCPB) 显示一个已建 `mcp-server` 包件嵌入; 不同FPS的数据在MCPB下载入 `_meta` 对象.

## Schema 验证

AFPS 计划领域(`input.schema`, (中文(简体) ), `output.schema`)接受任何有效的JSON Schema 2020-12文件,并带有两个AFPS特定的限制:

-   词根 `type` 必须 `"object"`
-   根有一条 `properties` 键

运行时间验证由AJV针对官方JSON Schema 2020-12 meta-schema进行. 生成的 `.schema.json` 文件通过 `allOf` 合并a `$ref` 以亚足联的限制为主.

## 重新生成

修改 Zod 源码后 `src/schemas.ts`数字 :

```sh
cd schema && bun install && bun run generate
```

## 清单中的用法

使用 `$schema` 用于编辑器验证 :

```json
{
  "$schema": "https://schemas.afps.dev/v0/agent.schema.json",
  "schema_version": "0.3",
  "name": "@scope/my-agent",
  "version": "1.0.0",
  "type": "agent"
}
```

实施方案可能会扩大这些计划,在《公约》之下增加一些领域 `_meta` 反 DNS 命名空间公约(参见 spec §10).

## 常见问题

### @afps-spec/schema 是什么？

Zod schemas并生成了JSON Schema 2020-12定义,用于AFPS 0\.3显示\(代理,技能,mcp-server,集成\)\.

### 如何安装 @afps-spec/schema？

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

### @afps-spec/schema 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/afps-spec\_\_schema 是否存在。

### @afps-spec/schema 支持 ESM 还是 CommonJS？

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

### @afps-spec/schema 可以商用吗？

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

### @afps-spec/schema 的下载量有多少？

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

### @afps-spec/schema 还在维护吗？

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