# @cleocode/lafs-protocol 中文文档

规范地址：https://npmcn.com/package/%40cleocode/lafs-protocol/

版本：1\.8\.0
npm 元数据更新时间：2026-03-24T21:51:02.790Z
中文译文更新时间：2026-11-10T01:09:53.572Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cleocode/lafs-protocol
原文对照：https://npmcn.com/package/%40cleocode/lafs-protocol/?lang=original
项目主页：https://codluv.gitbook.io/lafs-protocol/
源码仓库：https://github.com/kryptobaseddev/lafs-protocol

弃用说明：This package has been renamed to @cleocode/lafs and moved to the cleocode monorepo\.

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

- 包体积（解压后）：365 kB，81 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2026-02-12T02:05:54.138Z
- 最新版本发布：2026-03-19T06:53:02.780Z
- 近 30 天下载量：6175（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

LLM- Agent- First 规格计划和符合性工具

## 安装

```sh
npm install @cleocode/lafs-protocol
```

也可以使用：`pnpm add @cleocode/lafs-protocol`、`yarn add @cleocode/lafs-protocol`、`bun add @cleocode/lafs-protocol`

## README

# LAFS 协议

**LLM- 代理- 第一规格** ——AI代理系统响应信封合同.

LAFS定义了一个标准信封格式,用于LLM动力代理和工具的结构化响应. 它补充了运输协议 [MCP 磁共振](https://modelcontextprotocol.io/) 财务报告和审定财务报表 [A2A 对](https://github.com/google/A2A) 通过使回来的东西标准化——而不是它如何到达那里.

**当前版本 :** 1.5.0 [页:1](https://codluv.gitbook.io/lafs-protocol/) | [光谱](https://npmcn.com/package/%40cleocode/lafs-protocol/lafs.md) | [移徙指南](https://npmcn.com/package/%40cleocode/lafs-protocol/migrations/)

[![GitBook](https://img.shields.io/badge/docs-gitbook-blue)](https://codluv.gitbook.io/lafs-protocol/) [![npm](https://img.shields.io/npm/v/@cleocode/lafs-protocol)](https://www.npmjs.com/package/@cleocode/lafs-protocol)

## LAFS 提供的东西

| 层 | 文件 | 说明 |
| --- | --- | --- |
| **光谱** | `lafs.md` | 带有RFC 2119语言的议定书规格 |
| **示马斯** | `schemas/v1/envelope.schema.json` | 信封图案(草案-07),附有有条件的页形验证 |
|  | `schemas/v1/context-ledger.schema.json` | 用于在请求/答复周期进行国家跟踪的背景分类账 |
|  | `schemas/v1/error-registry.json` | 12个注册错误代码,带有HTTP/gRPC/CLI运输映射 |
| **工具** | `src/` | TypeScript 校验、 符合性跑道、 CLI 诊断工具 |
| **A2A 对** | `src/a2a/` | 代理对代理集成:扩展、任务生命周期、协议约束(JSON-RPC/HTTP/gRPC) |
| **测试** | `tests/` | 涵盖信封、页码、严格模式、错误处理、A2A扩展、任务生命周期、装订 |
| **固定设备** | `fixtures/` | 14 JSON 装置(有效+无效),用于符合性测试 |
| **文档** | `docs/` | [GitBook 文档](https://codluv.gitbook.io/lafs-protocol/) 带有向导、 SDK 参考和规格 |

## 安装

```bash
npm install @cleocode/lafs-protocol
```

## 使用量

```typescript
import {
  createEnvelope,
  parseLafsResponse,
  LafsError,
  validateEnvelope,
  runEnvelopeConformance,
  isRegisteredErrorCode,
} from "@cleocode/lafs-protocol";

// Build envelope with defaults
const envelope = createEnvelope({
  success: true,
  result: { items: [] },
  meta: { operation: "example.list", requestId: "req_1" },
});

// Validate an envelope against the schema
const validation = validateEnvelope(envelope);
if (!validation.valid) {
  console.error(validation.errors);
}

// Parse envelope responses with one function
try {
  const parsed = parseLafsResponse(envelope);
  console.log(parsed);
} catch (error) {
  if (error instanceof LafsError) {
    console.error(error.code, error.message);
  }
}

// Run full conformance suite (schema + invariants + error codes + strict mode + pagination)
const report = runEnvelopeConformance(envelope);
console.log(report.ok); // true if all checks pass
```

## LLM 代理执行指南

-   `docs/guides/llm-agent-guide.md` - 分析、成功/不当处理、严格的JSON政策
-   `docs/guides/schema-extension.md` - 核心计划之上的操作特定结果验证
-   `docs/guides/compliance-pipeline.md` - 具有验证+符合性门的生成中间软件
-   `docs/llms.txt` - 以LLM为导向的指数和犬类来源

## 国 际

```bash
# Run conformance checks on a fixture
npm run conformance -- --envelope fixtures/valid-success-envelope.json

# Run tests
npm test

# Type check
npm run typecheck
```

## 信封结构

```json
{
  "$schema": "https://lafs.dev/schemas/v1/envelope.schema.json",
  "_meta": {
    "specVersion": "1.0.0",
    "schemaVersion": "1.0.0",
    "timestamp": "2026-02-13T00:00:00Z",
    "operation": "example.list",
    "requestId": "req_01",
    "transport": "http",
    "strict": true,
    "mvi": "standard",
    "contextVersion": 1
  },
  "success": true,
  "result": { "items": [{ "id": "1", "title": "Example" }] },
  "page": {
    "mode": "cursor",
    "nextCursor": "eyJpZCI6IjEwIn0=",
    "hasMore": true
  }
}
```

## 主要特点

-   **条件标记** - 光标、平移和无模式的有特定模式的要求字段
-   **严格/ 借出模式** —— 说 `strict: true` 拒绝未知属性; `strict: false` 允许它们
-   **MVI 披露水平** —— 说 `minimal`, (中文(简体) ), `standard`, (中文(简体) ), `full`, (中文(简体) ), `custom` 控制响应动词
-   **实地选择** (单位:千美元)`_fields`和 **扩大** (单位:千美元)`_expand`) 请求参数
-   **背景分类账** - 单调版本的音轨在请求/响应周期之间状态
-   **错误登记** 12个编码,包括类别、可重试性和运输特定状态绘图
-   **延长机制** —— 说 `_extensions` 供应商元数据字段`x-` 前缀公约)
-   **收养层次** - 核心、标准,符合逐步遵守的要求
-   **A2A 整合** ——代理卡发现,扩展谈判,任务生命周期管理,协议约束

## A2A 一体化

LAFS 与 [A2A议定书](https://github.com/google/A2A) 通过 `@a2a-js/sdk`从 `@cleocode/lafs-protocol/a2a` 子路径 :

```typescript
import {
  // Extensions
  buildLafsExtension,
  extensionNegotiationMiddleware,
  LAFS_EXTENSION_URI,

  // Task lifecycle
  TaskManager,
  attachLafsEnvelope,
  isTerminalState,

  // Protocol bindings
  getErrorCodeMapping,
  createJsonRpcRequest,
  createProblemDetails,
} from "@cleocode/lafs-protocol/a2a";
```

**LAFS 扩展名片代理卡** ——使用 `autoIncludeLafsExtension` 在发现配置中 :

```typescript
import { discoveryMiddleware } from "@cleocode/lafs-protocol/discovery";

app.use(discoveryMiddleware({
  agent: { name: "my-agent", /* ... */ },
  autoIncludeLafsExtension: true,
}));
```

**具有约束力的议定书** 也可作为一个独立的子路径:

```typescript
import { getErrorCodeMapping } from "@cleocode/lafs-protocol/a2a/bindings";
```

## 合规检查

| 检查 | 说明 | 级别 |
| --- | --- | --- |
| `envelope_schema_valid` | JSON Schema 验证书 | 核心 |
| `envelope_invariants` | 成功/结果/不一致 | 核心 |
| `error_code_registered` | 登记册中存在出错代码 | 核心 |
| `meta_mvi_present` | 有效的MVI披露水平 | 标准 |
| `meta_strict_present` | 声明严格模式 | 标准 |
| `strict_mode_behavior` | 严格模式省略( 而非无效) 选项字段 | 标准 |
| `strict_mode_enforced` | 每个模式拒绝/转让其他属性 | 标准 |
| `pagination_mode_consistent` | 页面字段匹配已声明模式 | 标准 |

## 项目布局

```
lafs.md                          # Protocol specification
schemas/v1/
  envelope.schema.json           # Envelope schema (Draft-07)
  context-ledger.schema.json     # Context ledger schema
  error-registry.json            # Error code registry
src/
  types.ts                       # TypeScript types (discriminated unions)
  validateEnvelope.ts            # Ajv-based schema validator
  conformance.ts                 # Conformance runner (8 checks)
  errorRegistry.ts               # Error code helpers
  flagSemantics.ts               # Format flag resolution
  discovery.ts                   # A2A Agent Card discovery middleware
  cli.ts                         # CLI diagnostic tool
  a2a/
    bridge.ts                    # A2A SDK integration & result wrapper
    extensions.ts                # Extension negotiation & LAFS extension builder
    task-lifecycle.ts            # Task state machine & lifecycle management
    bindings/
      jsonrpc.ts                 # JSON-RPC 2.0 method/error constants & builders
      http.ts                    # HTTP endpoints, RFC 9457 Problem Details
      grpc.ts                    # gRPC status codes & service definitions (types only)
      index.ts                   # Barrel export & cross-binding error mapping
tests/                           # Tests (vitest)
fixtures/                        # JSON test fixtures
docs/
  POSITIONING.md                 # MCP/A2A complementary positioning
  VISION.md                      # Project vision and primary persona
  CONFORMANCE.md                 # Conformance checks and adoption tiers
migrations/
  v0.3.0-to-v0.4.0.md           # Envelope rationalization migration
  v0.4.0-to-v0.5.0.md           # Pagination & MVI schema migration
CONTRIBUTING.md                  # Contributor guidelines, RFC process
```

## 版本历史

| 版本 | 阶段 | 说明 |
| --- | --- | --- |
| **页:1** | **页:1** | **A2A v1.0+ 遵守:扩展谈判、任务生命周期、协议约束(JSON-RPC/HTTP/gRPC)** |
| v1.0.0 (韩语) | 3个 | 生产释放:托肯预算、代理发现、MCP集成、完整的SDK |
| 页:1 | 2个B | 有条件的页码、MVI字段选择/扩展、上下文分类账计划 |
| 页:1 | 第2款(A)项 | 可选页面/错误、扩展、严格/开放模式、警告 |
| v0.3.0 (韩语) | 1个 | 战略定位、愿景调整、采纳层次 |
| 页:1 | 0 个 | 议定书清理、固定装置、治理、安全考虑 |
| 页:1 | —— 说 | 初始 npm 发布 |
| 页:1 | —— 说 | 诱饵 |

## 许可证

麻省理工学院

## 常见问题

### @cleocode/lafs-protocol 是什么？

LLM- Agent- First 规格计划和符合性工具注意：该包已被作者标记为弃用——This package has been renamed to @cleocode/lafs and moved to the cleocode monorepo\.

### 如何安装 @cleocode/lafs-protocol？

在项目目录运行 npm install @cleocode/lafs-protocol，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 lafs-conformance，可以用 npx lafs-conformance 直接运行。

### @cleocode/lafs-protocol 支持 TypeScript 吗？

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

### @cleocode/lafs-protocol 支持 ESM 还是 CommonJS？

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

### @cleocode/lafs-protocol 可以商用吗？

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

### @cleocode/lafs-protocol 的下载量有多少？

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

### @cleocode/lafs-protocol 还在维护吗？

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