@eap/contracts

Enterprise Agent Platform 跨仓共享协议包。

包含内容

• types/ — 核心类型（Agent/Tool/Skill/Message/Task/Session/Hosting/Marketplace/Graph）
• constants/ — 错误码（三段式字符串枚举）、事件命名
• events/ — SSE 事件类型定义
• schemas/ — JSON Schema（@eap/contracts/schemas/*）
• examples/ — 协议样例（如 mcp-config.json）
• mcp/ — mcp-config.json → LocalToolInstallRecord 映射工具

安装

pnpm install @eap/contracts

公司私有 npm

私服：https://maven.gtcloud.cn/repository/npm-local/。

@eap:registry=... 是 .npmrc 文件内容，不是终端命令；在 zsh 里直接输入会报 no such file or directory。

cd eap-contracts
cp .npmrc.example .npmrc          # 写入 registry 配置
npm login --registry https://maven.gtcloud.cn/repository/npm-local/

# 发布（版本见 package.json 的 "version"）
npm publish --registry https://maven.gtcloud.cn/repository/npm-local/

开发者安装（工程内已 cp .npmrc.example .npmrc 时）：

npm install @eap/[email protected]

发布须先于 @eap/runtime；runtime 步骤见 runtime/README.md。

使用示例

类型定义

import type { AgentManifest, ToolManifest, TaskRecord, SessionRecord } from '@eap/contracts';

// Agent 定义
const agent: AgentManifest = {
  id: 'agent-001',
  name: 'my-agent',
  version: '1.0.0',
  tools: ['search', 'calculator'],
};

// Task 记录
const task: TaskRecord = {
  id: 'task-001',
  agentId: 'agent-001',
  status: 'running',
  input: { message: 'Hello' },
};

API 响应

import type { ApiResponse } from '@eap/contracts';
import { ErrorCodes } from '@eap/contracts';

// 成功响应
const success: ApiResponse<{ output: string }> = {
  code: ErrorCodes.OK,  // 'ok'
  data: { output: '回复内容' },
  traceId: 'trace-001',
};

// 错误响应
const error: ApiResponse = {
  code: ErrorCodes.GRAPH_AGENT_NOT_FOUND,  // 'runtime.graph.agent_not_found'
  message: 'Agent ai-bi not found',
  traceId: 'trace-002',
};

错误码

import { ErrorCodes, type ErrorCode } from '@eap/contracts';

// 三段式字符串枚举：{domain}.{category}.{detail}
if (response.code !== ErrorCodes.OK) {
  console.error('业务错误:', response.code, response.message);
}

// 常用错误码示例
ErrorCodes.OK                    // → 'ok'
ErrorCodes.AUTH_UNAUTHENTICATED  // → 'runtime.auth.unauthenticated'
ErrorCodes.TASK_TIMEOUT          // → 'runtime.task.timeout'
ErrorCodes.TOOL_RATE_LIMITED     // → 'runtime.tool.rate_limited'
ErrorCodes.BUDGET_TASK_EXHAUSTED // → 'runtime.budget.task_exhausted'
ErrorCodes.HOSTING_QUEUE_TIMEOUT // → 'hosting.queue.timeout'

// 类型安全
const code: ErrorCode = ErrorCodes.GRAPH_BUILD_FAILED;

错误码命名规则：

| 段 | 含义 | 取值 | |---|------|------| | domain | 来源模块 | runtime / hosting / tool / foundation | | category | 错误分类 | auth / session / task / graph / tool / budget / params / registry / governance / deployment / traffic / instance / queue / dependency | | detail | 具体错误 | 小写+下划线 |

SSE 事件

import { SseEventTypes } from '@eap/contracts';

// 监听事件
eventSource.addEventListener(SseEventTypes.RESPONSE_CHUNK, (event) => {
  console.log('Chunk:', event.data);
});

// 事件类型列表
console.log(SseEventTypes.TASK_STARTED);    // 'task.started'
console.log(SseEventTypes.TASK_COMPLETED);  // 'task.completed'

MCP 桌面配置（mcp-config.json）

与 Cursor / Claude Desktop 的 mcpServers 同构；由 gt-agent / desktop 宿主读盘，Runtime 不直接读此文件。

样例文件：examples/mcp-config.json（stdio file-service + Streamable HTTP remote-echo）。

JSON Schema：@eap/contracts/schemas/mcp-config.schema.json。

字段参考（权威定义见 src/types/mcp-config.ts + schemas/mcp-config.schema.json）：

根对象 EapMcpConfigFile：

| 字段 | 类型 | 必填 | 说明 | 示例 | |------|------|:----:|------|------| | version | string | 否 | 契约版本；缺省视为 "1.0" | "1.0" | | mcpServers | Record<string, EapMcpServerConfig> | 是 | serverId → 连接配置（与 Cursor mcpServers 同构） | 见下表 |

mcpServers 每项 EapMcpServerConfig：

| 字段 | 类型 | 必填 | 说明 | 示例 / 备注 | |------|------|:----:|------|-------------| | transport | "stdio" | "sse" | "streamable_http" | "http" | 否 | 传输协议；缺省时：有 url → streamable_http，否则 stdio | "stdio" | | command | string | 条件 | stdio 子进程命令；transport=stdio 时必填 | "node" | | args | string[] | 否 | stdio 命令参数 | ["mcp-service-file.js"] | | cwd | string | 否 | stdio 工作目录；亦作 bundlePath 默认回退 | "/path/to/mcp-data-service" | | env | Record<string, string> | 否 | stdio 子进程环境变量 | {} | | url | string | 条件 | 远程 MCP 端点；streamable_http / sse / 显式 url 时必填 | "https://mcp.example.com/mcp" | | header | Record<string, string> | 否 | 远程请求头 | { "Authorization": "Bearer …" } | | description | string | 否 | 展示用描述 | "文件读写服务" | | disabled | boolean | 否 | true 时宿主跳过，不生成 InstallRecord | false | | autoApprove | string[] | 展开时 | 免确认工具名；expandEapMcpConfigToInstallRecords 每项至少一个 | ["read_file", "write_file"] | | disabledTools | string[] | 否 | 禁用工具名（enablement 层） | [] | | timeoutMs | integer | 否 | 连接超时（毫秒），默认 30000 | 30000 |

字段分层（写入 Runtime 与否）：

| 层 | 字段 | 去向 | |----|------|------| | 连接层 | transport / command / url / cwd … | eapMcpServerToRuntimeExecution() → McpRuntimeExecution | | 治理层 | autoApprove / disabledTools | gt-agent / governance / HITL，不写入 execution | | 启用层 | disabled | 宿主跳过，不生成 LocalToolInstallRecord |

类型与常量：

import type { EapMcpConfigFile, EapMcpServerConfig } from '@eap/contracts';
import {
  expandEapMcpConfigToInstallRecords,
  eapMcpServerToRuntimeExecution,
  EAP_MCP_CONFIG_DEFAULT_PATHS,
  EAP_MCP_CONFIG_ENV,
} from '@eap/contracts';

展开为本地安装记录（每个 autoApprove 工具名 → 一条 LocalToolInstallRecord）：

import { readFileSync } from 'node:fs';
import { expandEapMcpConfigToInstallRecords, type EapMcpConfigFile } from '@eap/contracts';

const config = JSON.parse(
  readFileSync('examples/mcp-config.json', 'utf8'),
) as EapMcpConfigFile;

const records = expandEapMcpConfigToInstallRecords(config);
// records[0].mcpExecution → LocalToolExecutor 消费

默认搜索路径：~/.config/eap/mcp-config.json、~/.eap/mcp-config.json；或通过环境变量 EAP_MCP_CONFIG 指向绝对路径。

与 Registry MCP Tool 区分：mcp-config.json 是 IDE/桌面直配；Portal 注册的 MCP Tool 使用 ToolManifest（type: 'mcp' + McpExecution）。Code 包文件权威见 schemas/toolset.manifest.schema.json。

详见 docs/contracts/tool-execution.md §4.2；代码样例见 runtime/examples/demo-tool/src/file-service-sample.ts。

设计原则

• 这个包只包含类型定义和常量，零运行时依赖
• 所有仓库（runtime/dev-tools/foundation-service/hosting-service/marketplace/gt-agent/portals）通过 npm 依赖此包
• 修改协议 → 先改此包发版 → 其他仓库升级依赖

相关文档

| 文档 | 说明 | |------|------| | docs 文档索引 | 全平台文档入口 | | 各模块实现全景 | eap-contracts §4、§10.1 验收清单 | | 跨服务 API | 错误码与契约在代码中的用法 | | 04-runtime-core | Runtime 规格 | | 06-governance | ExecutionContext 等类型来源（规格叙述；权威枚举以本包 CallerType 为准：user | client | service） | | platform-four-services-overview §2.3 | ExecutionContext / CallerType 契约备注 | | runtime-sdk-integration-final §3.1 | Runtime 侧 ExecutionContext 接入说明 |

CallerType 重命名待同步（specs 债）

本包枚举已定为 user | client | service（历史：api_key→client，system→service）。下列 .kiro/specs 尚未改写，改规格时应与本包对齐（迁移期可读旧别名）：

| Spec 模块 | 文档 | 待改要点（旧 → 新） | |-----------|------|---------------------| | 06-governance | requirements.md | R 含 Token/API Key：callerType=api_key → client；payload user/api_key → user/client；下游 Tool 禁伪 Delegation 处同 | | 06-governance | design.md | 对照表与 ExecutionContext 示例：api_key→client；system→service；§1.13 流程与身份表标题 | | hosting | requirements.md | ExecutionContext：user|api_key|system → user|client|service；白名单校验条件 callerType=api_key → client | | hosting | design.md | ExecutionContext 类型定义同上 | | skill-registry | design.md | 内部编排：callerType=system → service |

已对齐（勿重复当债）：04-runtime-core（design/requirements）、01-quick-dev（design/requirements）、12-multi-agent（requirements/design）。

不必改 / 低优先级：

• 04-runtime-core/storage-design-complete.md：SQL deleted_by = 'system' 是数据字段字面量，不是 CallerType
• 06-governance/design-v0.1.md、requirements-v0.1.md：历史归档稿；表名 api_keys 等非枚举，可不改；若外发再加脚注