# @axiom-lattice/cli-a2a 中文文档

规范地址：https://npmcn.com/package/%40axiom-lattice/cli-a2a/

版本：0\.2\.32
npm 元数据更新时间：2026-11-03T01:43:07.180Z
中文译文更新时间：2026-11-07T19:34:54.165Z
软件包许可：ISC

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

原始 npm 页面：https://www.npmjs.com/package/%40axiom-lattice/cli-a2a
原文对照：https://npmcn.com/package/%40axiom-lattice/cli-a2a/?lang=original

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

- 包体积（解压后）：835 kB，72 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.10\.0
- 运行依赖：2 个
- peer 依赖：uuid ^9\.0\.1，express ^5\.1\.0
- 首次发布：2026-06-11T08:31:33.433Z
- 最新版本发布：2026-11-03T01:43:06.978Z
- 近 30 天下载量：2942（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：43（近 12 个月 43 个）

## 中文简介

多提供者 A2A(代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理

## 安装

```sh
npm install @axiom-lattice/cli-a2a
```

也可以使用：`pnpm add @axiom-lattice/cli-a2a`、`yarn add @axiom-lattice/cli-a2a`、`bun add @axiom-lattice/cli-a2a`

## README

# @axiom-lattice/cli-a2a (韩语)

多供应商A2A(代理代理)CLI网关. 环绕本地编码代理 (OpenCode, Codex, Claude Code)作为符合光谱的A2A服务器. 放下一个JSON 配置,获得一个完全符合光谱的A2A剂——可通过 `npx`。 。 。 .

## 快速启动

```bash
# 1. Start your local OpenCode server
opencode serve

# 2. Launch the A2A gateway
npx @axiom-lattice/cli-a2a --provider opencode --port 3000

# 3. Verify
curl http://localhost:3000/health
# → { "status": "healthy", "agent": "CLI A2A Agent", "provider": "opencode" }

curl http://localhost:3000/.well-known/agent-card.json
# → A2A v0.3 AgentCard JSON
```

## 供应商

| 提供者 | 状态 | 连接 |
| --- | --- | --- |
| `opencode` | 准备 | HTTP API (英语)`opencode serve`(中文(简体) ) |
| `codex` | 准备 | CLI 子进程 (`codex`(中文(简体) ) |
| `claude` | 准备 | CLI 子进程 (`claude -p`(中文(简体) ) |

## 使用量

```bash
npx @axiom-lattice/cli-a2a [options]
```

### 选项

```
  --provider <name>            Provider: opencode | codex | claude
  --config, -c <path>          Path to agent JSON config file
  --port, -p <number>          A2A server port (default: 3000)
  --hostname <addr>            Bind address (default: 0.0.0.0)
  --advertise-host <host>      Hostname for agent card URLs
  --agent-name <name>          Agent display name
  --agent-description <desc>   Agent description
  --log-level <level>          debug | info | warn | error (default: info)
```

### 打开代码选项

```
  --opencode-url <url>         OpenCode server URL (default: http://localhost:4096)
  --directory, -d <path>       Project directory
  --model, -m <provider/model> LLM model
  --agent <name>               OpenCode agent preset
```

### 代码选项

```
  --codex-model <model>        Codex model ID (e.g. gpt-4o)
  --codex-api-key <key>        OpenAI API key
```

### Claude 代码选项

```
  --claude-model <model>       Claude Code model ID
  --claude-api-key <key>       Anthropic API key
```

### 网关注册

CLI 可以自动注册一个 `@axiom-lattice/gateway` 服务器 网关作为一等远程代理发现并通向它的路线.

```
  --register-url <url>         Gateway URL to register this agent with
  --register-key <key>         API key for gateway authentication
  --unregister-on-shutdown     Remove agent from gateway on exit
```

```bash
npx @axiom-lattice/cli-a2a \
  --provider opencode \
  --port 3001 \
  --register-url http://gateway:8080 \
  --register-key sk-a2a-gateway-key \
  --unregister-on-shutdown &
```

启动 CLI POST 时 `{registerUrl}/api/assistants` 带有 `graphDefinition` 类型 `a2a_remote` 指着自己的代理卡. 退出时( 如果 `--unregister-on-shutdown`这是DELETES的助手.

注册后,代理人与所有其他代理人一起出现在 网关和可以通过标准引用 `/api/runs` 终点.

## 配置文件

```json
{
  "provider": "opencode",
  "agentCard": {
    "name": "My Coding Agent",
    "description": "A coding assistant powered by OpenCode",
    "skills": [
      {
        "id": "code-gen",
        "name": "Code Generation",
        "description": "Generate and refactor code",
        "tags": ["coding", "typescript"]
      }
    ]
  },
  "server": {
    "port": 3000,
    "advertiseHost": "localhost"
  },
  "opencode": {
    "baseUrl": "http://localhost:4096",
    "projectDirectory": "/path/to/project",
    "model": "anthropic/claude-sonnet-4"
  },
  "features": {
    "autoApprovePermissions": true,
    "streamArtifactChunks": false
  },
  "timeouts": {
    "prompt": 600000
  }
}
```

配置层以优先级顺序合并 : **默认 QQ 配置文件 QQ env vars QCLI 参数**。 。 。 .

### 环境变量

| 变量 | 地图到 |
| --- | --- |
| `OPENCODE_URL` | `opencode.baseUrl` |
| `OPENCODE_DIRECTORY` | `opencode.projectDirectory` |
| `OPENCODE_MODEL` | `opencode.model` |
| `OPENCODE_AGENT` | `opencode.agent` |
| `OPENAI_API_KEY` | `codex.apiKey` |
| `ANTHROPIC_API_KEY` | `claude.apiKey` |

## 终点

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| `GET` | `/health` | 健康检查 |
| `GET` | `/.well-known/agent-card.json` | A2A 代理卡 |
| `POST` | `/a2a/jsonrpc` | A2A JSON-RPC运输 |
| `POST` | `/a2a/rest` | A2A REST运输 |

## 程序化 API

```ts
import {
  createA2AServer,
  resolveConfig,
  registerExecutor,
  createOpenCodeExecutor,
  createCodexExecutor,
  createClaudeExecutor,
  SessionBindingStore,
} from '@axiom-lattice/cli-a2a';

// Register executors
registerExecutor('opencode', createOpenCodeExecutor);
registerExecutor('codex', createCodexExecutor);
registerExecutor('claude', createClaudeExecutor);

// Load config
const config = resolveConfig('agent-config.json');

// Start server
const server = await createA2AServer(config);

// Graceful shutdown
process.on('SIGINT', async () => {
  await server.shutdown();
  process.exit(0);
});
```

## 多回合对话

A2A 协议使用 `contextId` 将信息分组到一个单独的对话中. `cli-a2a` 每个地图 `contextId` 实现多回合制 所有三个提供者的连续性:

| 提供者 | 新建会话 | 复会 | 会话 ID 来源 |
| --- | --- | --- | --- |
| 代码 | `codex exec --json <prompt>` | `codex exec resume <thread_id> <prompt>` | `thread_id` 从杰森勒 `thread.started` 事件 |
| 克劳德代码 | `claude -p --session-id <uuid> <prompt>` | `claude -p --resume <uuid> <prompt>` | 生成的 UUID |
| 打开代码 | `opencode run --format json <prompt>` | `opencode run --session <sessionID> <prompt>` | `sessionID` jSON活动 |

**如何运作:**

1.  A2A 客户端发送信息 `contextId`
2.  `cli-a2a` 抬头看 `contextId` 在会话框中
3.  如果找到: 使用提供者的恢复命令继续 CLI 会话
4.  如果找不到: 创建新的 CLI 会话并保存绑定
5.  随后发出相同信息 `contextId` 重复使用相同的 CLI 会话

历史由基本的CLI工具所维持——不需要迅速召集.

### 会话持久性

捆绑在磁盘上,这样 `cli-a2a` 重新启动保存对话框 :

-   **默认路径**数字 : `~/Library/Application Support/axiom-lattice/cli-a2a/sessions.json`
-   **格式**JSON阵列 `{ provider, contextId, sessionId, ... }`
-   **TTL 电话**: 默认24小时(可通过 `session.ttl`(中文(简体) )
-   **清理**: 装入时卸出并定期卸出过期装入(每1小时)

要禁用持久性 :

```json
{
  "session": {
    "persist": false
  }
}
```

要完全禁用会话再利用( 每个请求都创建新会话) :

```json
{
  "session": {
    "reuseByContext": false
  }
}
```

### 会话配置

```json
{
  "session": {
    "reuseByContext": true,
    "persist": true,
    "storePath": "~/custom/path/sessions.json",
    "ttl": 86400000,
    "cleanupInterval": 3600000
  }
}
```

| 外地 | 默认 | 说明 |
| --- | --- | --- |
| `reuseByContext` | `true` | 地图 `contextId` 改为 CLI 会话进行多回合 |
| `persist` | `true` | 在整个重启中保存磁盘绑定 |
| `storePath` | `~/Library/Application Support/axiom-lattice/cli-a2a/sessions.json` | 自定义绑定存储路径 |
| `ttl` | `86400000` (24小时) | 会话 TTL (毫秒) |
| `cleanupInterval` | `3600000` (1小时) | 以毫秒计的清理间隔 |

## 建筑

```
┌──────────────────────────────────────────────────────┐
│  cli-a2a (Express A2A Server)                        │
│                                                      │
│  ┌─────────────┐  ┌──────────┐  ┌──────────────────┐│
│  │ Agent Card  │  │ JSON-RPC │  │ REST             ││
│  └─────────────┘  └──────────┘  └──────────────────┘│
│                         │                            │
│  ┌──────────────────────▼───────────────────────────┐│
│  │  Executor Registry                                ││
│  │  ┌────────────┐ ┌─────────┐ ┌──────────────────┐ ││
│  │  │ OpenCode   │ │ Codex   │ │ Claude Code      │ ││
│  │  │ Executor   │ │ Executor│ │ Executor         │ ││
│  │  └─────┬──────┘ └────┬────┘ └───────┬──────────┘ ││
│  └────────┼─────────────┼──────────────┼────────────┘│
│           │             │              │              │
│  ┌────────▼─────────────▼──────────────▼────────────┐│
│  │  SessionBindingStore                              ││
│  │  contextId → CLI sessionId + file persistence     ││
│  └──────────────────────────────────────────────────┘│
└───────────┼─────────────┼──────────────┼─────────────┘
            │ HTTP        │ spawn        │ spawn
    ┌───────▼────────┐ ┌──▼───────┐ ┌───▼────────────┐
    │ opencode serve │ │ codex CLI│ │ claude CLI (-p) │
    └────────────────┘ └──────────┘ └────────────────┘
```

## 网络建设——对外网络曝光

该代理运行一个本地的HTTP服务器. 要从外到外,用内置 WebSocket桥(不需要SSH隧道或ngrok).

### 已建成的WebSocket桥(建议)

```bash
# Agent — opens outbound WebSocket to gateway
npx @axiom-lattice/cli-a2a \
  --provider opencode \
  --port 3001 \
  --bridge-url ws://gateway:8080/api/a2a/bridge \
  --bridge-key sk-xxx \
  --register-url http://gateway:8080 \
  --register-key sk-xxx
```

```
Internal Network (agent)           Public (gateway)
┌──────────────────┐              ┌─────────────────────┐
│ cli-a2a :3001    │──WebSocket──→│ /api/a2a/bridge     │
│   ↑              │   outbound   │   ↑                 │
│   │ local call   │              │   │ HTTP proxy      │
│   │              │              │ /api/a2a/bridge/    │
│ Express A2A      │              │   proxy/{agentId}/* │
│ OpenCode/Codex/  │              │                     │
│ Claude           │              │ A2A_REMOTE agent →  │
└──────────────────┘              └─────────────────────┘
```

**如何运作:**

1.  代理打开一个出局的WebSocket进入网关(出局几乎从未被封锁)
2.  网关存储代理 ID 的连接
3.  网关曝光 `GET/POST /api/a2a/bridge/proxy/{agentId}/*`
4.  当管弦乐手调用代理 URL 时, 网关将请求推到 WebSocket 上
5.  Agent 给其Express 服务器发出本地 HTTP 呼叫, 返回响应

经纪人的 `agentCardUrl` 登记点为 `http://gateway:8080/api/a2a/bridge/proxy/{agentId}/.well-known/agent-card.json`。 。 。 .

### SSH 倒转隧道(替代)

```bash
ssh -R 3001:localhost:3001 user@public-bastion.com -N &
npx cli-a2a --provider opencode --port 3001 \
  --advertise-host public-bastion.com \
  --register-url http://gateway:8080 --register-key sk-xxx
```

### 相同的网络

```bash
npx cli-a2a --provider opencode --port 3001 \
  --advertise-host 192.168.1.42 \
  --register-url http://gateway:8080 --register-key sk-xxx
```

## 多项目

为不同的项目运行多个实例 :

```bash
npx @axiom-lattice/cli-a2a --provider opencode -d /proj/frontend --port 3001 &
npx @axiom-lattice/cli-a2a --provider opencode -d /proj/backend  --port 3002 &
```

## 软件包导出

| 导出 | 说明 |
| --- | --- |
| `createA2AServer(config)` | 启动快取 A2A 服务器 |
| `resolveConfig(path?, overrides?)` | 合并配置层 |
| `loadConfigFile(path)` | 读取和剖析 JSON 配置文件 |
| `registerExecutor(provider, factory)` | 注册一个执行工厂 |
| `createOpenCodeExecutor(config, store)` | 创建 OpenCode 执行器 |
| `createCodexExecutor(config, store)` | 创建代码x执行器 |
| `createClaudeExecutor(config, store)` | 创建 Claude 执行器 |
| `SessionBindingStore` | `contextId → sessionId` 持久性 |
| `generateContextId()` | 生成一个新的 UUID 上下文Id |
| `logger`, (中文(简体) ), `LogLevel` | 结构化日志 |

## 许可证

公务员制度委员会

## 常见问题

### @axiom-lattice/cli-a2a 是什么？

多提供者 A2A\(代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理代理

### 如何安装 @axiom-lattice/cli-a2a？

在项目目录运行 npm install @axiom-lattice/cli-a2a，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：uuid（^9\.0\.1）、express（^5\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 cli-a2a，可以用 npx cli-a2a 直接运行。

### @axiom-lattice/cli-a2a 支持 TypeScript 吗？

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

### @axiom-lattice/cli-a2a 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @axiom-lattice/cli-a2a 需要什么版本的 Node\.js？

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

### @axiom-lattice/cli-a2a 可以商用吗？

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

### @axiom-lattice/cli-a2a 的下载量有多少？

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

### @axiom-lattice/cli-a2a 还在维护吗？

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