企业官网建设流程全解析

qwen-code ACP Client SDK（Java）实战指南：基于 Agent Client Protocol 构建 AI 智能体客户端

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code

本文面向希望在 Java 应用中接入 AI 编码智能体的开发者，系统讲解 qwen-code 仓库中acp-sdk（Java 版 ACP Client SDK）的安装引入、核心架构、会话管理、事件处理、权限控制与传输层配置。读完本文，你将掌握如何通过几十行 Java 代码启动本地 qwen 智能体进程、创建会话、发送提示词并处理流式回包，以及如何扩展文件系统、终端与 MCP 等能力。

一、项目概览：什么是 ACP Client SDK

acp-sdk是 qwen-code 仓库中针对Agent Client Protocol（ACP）的 Java 客户端 SDK，负责让客户端应用与支持 ACP 协议的 AI 智能体（如终端里的 qwen CLI）进行标准化通信。协议层面它基于 JSON-RPC 2.0 规范，通过 JSON schema 统一定义全部消息类型，保证了不同客户端与不同 ACP 智能体之间的互操作性。

从 client 模块源码结构 看，SDK 的核心能力包括：

• 会话管理：创建（new）、加载（load）与关闭会话，完整管理对话生命周期；
• 文件系统操作：文本文件的读写请求（ReadTextFileRequest/WriteTextFileRequest）；
• 终端命令执行：创建终端、执行命令、读取输出、等待退出、结束进程等请求；
• 工具调用与权限管理：处理工具调用更新，并对敏感操作进行细粒度授权；
• 富内容类型：文本、图片、音频、资源、工具调用等多种 Content Block；
• MCP 集成：在会话请求中携带 MCP Server 配置，扩展外部工具能力。

模块坐标与项目背景可参考 QWEN.md 与 pom.xml。

二、环境要求

使用该 SDK 前需要准备：

SDK 当前版本为0.0.1-alpha（Alpha 阶段），Group ID 为com.alibaba，Artifact ID 为acp-sdk，信息来源于 pom.xml 与 QWEN.md。

三、安装与依赖引入

3.1 Maven

在pom.xml中添加：

<dependency> <groupId>com.alibaba</groupId> <artifactId>acp-sdk</artifactId> <version>0.0.1-alpha</version> </dependency>

3.2 Gradle

在build.gradle中添加：

implementation 'com.alibaba:acp-sdk:0.0.1-alpha'

3.3 关键依赖说明

SDK 自身的编译期依赖在 pom.xml 中定义，包括：

• SLF4J API 2.0.17：日志门面，业务方可自由绑定日志实现；
• Apache Commons Lang3 3.20.0 与 commons-io 2.21.0：参数校验（Validate）、异常上下文（ContextedRuntimeException）等工具；
• FastJSON2 2.0.60：全部 JSON-RPC 消息的序列化与反序列化；
• JUnit 5 / Logback Classic：仅测试作用域，用于单元测试与测试日志。

构建侧还集成了 checkstyle（checkstyle.xml）、JaCoCo 覆盖率统计，以及面向 Maven Central 的发布插件。

四、快速开始：创建客户端并建立会话

下面的示例直接取自仓库测试用例（见 SessionTest.java），演示了最简使用链路：创建AcpClient→ 发送提示词 → 事件消费 → 关闭客户端。

@Test public void testSession() throws AgentInitializeException, SessionNewException, IOException { // 创建 ACP 客户端，通过进程传输层启动本地 qwen 智能体 AcpClient acpClient = new AcpClient( new ProcessTransport(new ProcessTransportOptions().setCommandArgs(new String[] {"qwen", "--acp", "-y"}))); try { // 向智能体发送提示词 acpClient.sendPrompt(Collections.singletonList(new TextContent("你是谁")), new AgentEventConsumer().setContentEventConsumer(new ContentEventSimpleConsumer() { @Override public void onAgentMessageChunkSessionUpdate(AgentMessageChunkSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } @Override public void onAvailableCommandsUpdateSessionUpdate(AvailableCommandsUpdateSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } @Override public void onCurrentModeUpdateSessionUpdate(CurrentModeUpdateSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } @Override public void onPlanSessionUpdate(PlanSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } @Override public void onToolCallUpdateSessionUpdate(ToolCallUpdateSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } @Override public void onToolCallSessionUpdate(ToolCallSessionUpdate sessionUpdate) { logger.info(sessionUpdate.toString()); } })); } finally { // 使用完毕务必关闭客户端，释放子进程资源 acpClient.close(); } }

其中qwen --acp -y表示以子进程方式启动 qwen CLI 并进入 ACP 协议模式（--acp为启用 ACP 协议的 CLI 参数，-y为自动确认参数，具体语义以 qwen CLI 的说明为准）。sendPrompt内部会自动完成“新建会话 + 发送提示词”两个动作；在finally中调用close()会关闭传输层并销毁子进程（见 AcpClient.close()），避免资源泄漏。

五、架构与核心组件

5.1 四个核心构件

按 README 与源码组织，SDK 由四个核心构件组成：

1. AcpClient：客户端主入口类，管理到 ACP 智能体的连接。构造时即启动传输层并发起initialize握手，负责新建/加载会话、发送提示词、关闭连接；
2. Session：代表与智能体的一段对话会话，封装发送提示词、取消任务以及各类事件/请求的分发处理；
3. Transport：底层通信抽象，承载 JSON-RPC 消息在 stdio 子进程、HTTP 等通道上的收发；
4. Protocol Definitions：由 schema.json 定义的协议模型生成的 Java 类，覆盖所有 ACP 消息类型。

5.2 AcpClient 的生命周期与握手

AcpClient.java 是整个 SDK 的入口，构造流程清晰地体现了 ACP 握手过程：

• 调用transport.start()启动传输层（对进程传输即拉起子进程）；
• 构造InitializeRequest并发送，等待智能体返回InitializeResponse；
• 若初始化响应携带error字段，则抛出AgentInitializeException。

构造完成后，客户端提供三个核心操作：

• newSession()/newSession(NewSessionRequestParams)：发送NewSessionRequest，依据返回的sessionId创建Session实例；失败抛出SessionNewException；
• loadSession(LoadSessionRequestParams)：发送LoadSessionRequest恢复既有会话，失败抛出SessionLoadException；
• sendPrompt(List<ContentBlock>, AgentEventConsumer)：等价于“新建会话后发送提示词”的组合调用。

会话参数（如cwd工作目录、mcpServersMCP 服务器列表）通过NewSessionRequestParams传递，并被透传到后续LoadSessionRequestParams中（见 AcpClient.java）。

5.3 协议结构

ACP 协议在 SDK 中被组织为清晰的 JSON-RPC 消息体系（见 protocol 包）：

• Request / Response 类型：客户端与智能体间的请求-响应模型，如InitializeRequest、NewSessionRequest、PromptRequest、ReadTextFileRequest等；
• Notification 机制：智能体向客户端推送的实时更新（如SessionNotification），以及客户端发出的CancelNotification；
• 错误处理与能力协商：JSON-RPCError对象 +initialize阶段的能力声明；
• Content Block：文本、图片、音频、嵌入资源等多样化的消息内容载体；
• 工具调用定义与执行流：ToolCallUpdate、ToolCallLocation、ToolCallStatus、ToolKind等模型，覆盖工具调用的全生命周期状态。

5.4 消息路由与反序列化

Session.java 中的toMessage方法展示了 SDK 的消息分派逻辑：根据 JSON 中是否包含method、result/error字段，分别解析为方法消息（MethodMessage）、提示词回合结束响应（PromptResponse，以stopReason为判别标志）或普通响应，最终统一路由给对应的消费者处理。

六、传输层深入：ProcessTransport 与超时控制

6.1 Transport 接口契约

Transport.java 定义了所有传输实现的统一契约：

• isReading()：当前是否处于读取状态；
• start()/close()/isAvailable()：生命周期管理；
• inputWaitForOneLine(message)：发送消息并等待单行响应（用于握手类请求）；
• inputWaitForMultiLine(message, callback)：发送消息并逐行回调处理多行响应（用于提示词回合）；
• inputNoWaitResponse(message)：只发送不等待（用于通知类消息）。

6.2 ProcessTransport 配置项

当前仓库内置的传输实现是 ProcessTransport，通过ProcessBuilder启动子进程，以 stdio 管道承载 JSON-RPC 消息。其配置项集中在 ProcessTransportOptions.java：

其中turnTimeout作用于inputWaitForOneLine与inputWaitForMultiLine的整轮等待，messageTimeout作用于多行迭代中读取单行的时间上限（见 ProcessTransport.java）。这些超时值定义在 Timeout.java，SDK 预置了 3 秒、60 秒、180 秒、30 分钟四档常量，也支持自定义new Timeout(value, timeUnit)。

提示：ProcessTransport内部会异步读取子进程的 stderr 并通过errorHandler处理，同时用AtomicBoolean reading标记读取状态，避免并发读写冲突，适合作为自定义传输实现（如 HTTP Transport）的参考范本。

七、事件驱动模型：AgentEventConsumer 与消费者体系

SDK 采用事件消费者模式接收智能体的实时输出。AgentEventConsumer.java 是一个消费者容器，可通过链式 setter 挂载五类消费者：

7.1 会话更新类型

ContentEventConsumer（可继承 ContentEventSimpleConsumer.java 简化实现）需要处理六类会话更新：

• AgentMessageChunkSessionUpdate：智能体消息内容块流式更新；
• ToolCallUpdateSessionUpdate/ToolCallSessionUpdate：工具调用的进行中/最终状态；
• AvailableCommandsUpdateSessionUpdate：可用命令列表变更；
• CurrentModeUpdateSessionUpdate：当前会话模式变更；
• PlanSessionUpdate：计划条目更新（对应Plan/PlanEntry/PlanEntryStatus/PlanEntryPriority模型）。

7.2 事件分发的超时与异常语义

在 Session.java 中，事件处理分为两类：

• 通知类（NoWait）：调用消费回调并在超时内完成，超时默认 60 秒（defaultEventConsumeTimeout）；
• 请求类（Request）：如权限请求、文件读写、终端操作，处理器返回结果后由 SDK 自动构造Response回传给智能体；若消费过程抛出EventConsumeException或超时，则回传 JSON-RPCINTERNAL_ERROR。这一机制让业务方可以同步决策（比如“是否允许写文件”）而无需关心底层请求-响应编解码。

八、能力协商与权限控制

8.1 初始化阶段声明客户端能力

InitializeRequestParams（见 InitializeRequest.java）携带协议版本、clientCapabilities与clientInfo。其中ClientCapabilities用于声明客户端支持的能力，例如在 SessionTest.java 中：

AcpClient acpClient = new AcpClient(transport, new InitializeRequestParams().setClientCapabilities( new ClientCapabilities() .setTerminal(true) .setFs(new FileSystemCapability().setReadTextFile(true).setWriteTextFile(true))));

上述代码声明客户端支持终端能力、可读写文本文件，从而让智能体在会话中放心发起相应的请求。

8.2 权限请求处理示例

当智能体需要执行敏感操作（如创建文件）时，会向客户端发送RequestPermissionRequest，由PermissionEventConsumer决定放行方式。仓库测试给出了一个“自动选择 ALLOW_ALWAYS”的完整实现：

session.sendPrompt(Collections.singletonList(new TextContent("创建一个test.touch文件")), new AgentEventConsumer() .setFileEventConsumer(new FileEventSimpleConsumer()) .setPermissionEventConsumer(new PermissionEventConsumer() { @Override public RequestPermissionResponseResult onRequestPermissionRequest(RequestPermissionRequest request) throws EventConsumeException { return new RequestPermissionResponseResult(new RequestPermissionOutcome() .setOptionId(Optional.of(request) .map(MethodMessage::getParams) .map(RequestPermissionRequestParams::getOptions) .flatMap(options -> options.stream() .filter(option -> ALLOW_ALWAYS.equals(option.getKind())) .findFirst()) .map(PermissionOption::getOptionId).orElse(null)) .setOutcome(PermissionOutcomeKind.SELECTED)); } @Override public Timeout onRequestPermissionRequestTimeout(RequestPermissionRequest request) { return Timeout.TIMEOUT_60_SECONDS; } }));

这里 SDK 在智能体给出的多个权限选项中（PermissionOption，种类见PermissionOptionKind）自动挑选ALLOW_ALWAYS，并通过PermissionOutcomeKind.SELECTED回传选择结果。企业应用可在此处接入自己的审批系统（如工单、人工审核），实现对敏感操作的可控授权。

九、典型使用场景

结合 SDK 能力与仓库定位，acp-sdk适用的场景包括：

• 企业应用内的 AI 智能体集成：在业务系统中嵌入本地编码智能体，通过统一协议交互；
• 自动化脚本与任务执行：程序化向智能体下发任务并处理结果；
• 文件系统操作自动化：借助文件事件消费者实现文本文件的受控读写；
• 终端命令执行与结果处理：通过终端事件消费者驱动命令行任务；
• 外部服务与工具集成：通过NewSessionRequestParams携带 MCP Server 配置，扩展智能体工具集。

十、构建与测试

10.1 构建命令

在packages/sdk-java/client目录下执行：

# 编译项目 mvn compile # 运行测试 mvn test # 打包 JAR mvn package # 安装到本地仓库 mvn install

构建配置的细节值得注意：Maven Surefire 配置了failIfNoTests=true且排除了integration测试组（见 pom.xml），这意味着依赖真实 qwen 子进程的集成测试（如SessionTest的@Tag("integration")）在默认mvn test下不会执行，保证单元测试可在无智能体环境运行；Checkstyle 在构建期强制执行代码规范，JaCoCo 在测试阶段生成覆盖率报告。

10.2 测试覆盖

仓库测试覆盖了协议枚举（PermissionOptionKindTest、PlanEntryStatusTest、StopReasonTest、ToolCallStatusTest、ToolKindTest、PlanEntryPriorityTest）、会话管理（SessionTest）、线程池配置（ThreadPoolConfigTest）等，对应路径见 client 测试目录。测试重点验证：协议消息生成、会话管理功能、权限处理工作流、内容类型处理。

十一、开发约定与许可

• SDK 遵循标准 Java 编码规范，使用 SLF4J 日志门面，基于 JSON-RPC 2.0 规范通信，采用 FastJSON2 完成序列化（详见 QWEN.md）；
• 项目采用 Apache 2.0 许可，参见仓库根目录 LICENSE；
• 欢迎通过 Issues 与 Pull Requests 参与贡献，遇到问题可通过 GitHub Issues 反馈。

十二、延伸阅读

• SDK 上下文总览：QWEN.md
• 构建与发布配置：pom.xml
• 客户端入口与握手逻辑：AcpClient.java
• 会话事件分发与请求处理：Session.java
• 传输层接口与进程实现：Transport.java、ProcessTransport.java
• 传输配置项与超时定义：ProcessTransportOptions.java、Timeout.java
• 集成测试示例：SessionTest.java

【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code