LAFS 协议

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

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

当前版本 : 1.5.0 页:1 | 光谱 | 移徙指南

LAFS 提供的东西

安装

npm install @cleocode/lafs-protocol

使用量

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为导向的指数和犬类来源

国 际

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

# Run tests
npm test

# Type check
npm run typecheck

信封结构

{
  "$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议定书 通过 @a2a-js/sdk从 @cleocode/lafs-protocol/a2a 子路径 :

import {
  // Extensions
  buildLafsExtension,
  extensionNegotiationMiddleware,
  LAFS_EXTENSION_URI,

  // Task lifecycle
  TaskManager,
  attachLafsEnvelope,
  isTerminalState,

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

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

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

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

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

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

合规检查

项目布局

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

版本历史

许可证

麻省理工学院