yankewei/php-acp

Implement ACP with PHP

0.0.1 2026-03-06 16:04 UTC

Requires

• php: ^8.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.0

MIT

• yankewei

README

php-acp 是一个 ACP (Agent Client Protocol) PHP client SDK。

当前版本聚焦于：

• PHP 8.4+
• typed ACP schema DTO
• 双向 JSON-RPC peer
• stdio transport
• client 侧 fs/*、session/request_permission、terminal/* handler 扩展点

状态

当前是第一版可用 SDK，已经打通核心会话流程：

• initialize
• authenticate
• session/new
• session/prompt
• session/cancel
• session/update

目前限制：

• 只实现了 stdio transport
• ACP schema 还不是全量覆盖
• 还没有发布到 Packagist

安装

如果这个仓库就在你的本地工作区，可以先用 path repository：

{
    "repositories": [
        {
            "type": "path",
            "url": "../php-acp"
        }
    ],
    "require": {
        "yankewei/php-acp": "*"
    }
}

然后执行：

composer update yankewei/php-acp

如果你后面把它推到 Git 仓库，也可以改成 vcs repository。

快速开始

最小可运行示例见 examples/basic-client.php。

<?php

declare(strict_types=1);

use Yankewei\PhpAcp\AcpClient;
use Yankewei\PhpAcp\ClientHandler\DefaultClientHandler;
use Yankewei\PhpAcp\Schema\ClientCapabilities;
use Yankewei\PhpAcp\Schema\ContentBlock;
use Yankewei\PhpAcp\Schema\ImplementationInfo;
use Yankewei\PhpAcp\Transport\StdioTransport;

require __DIR__ . '/../vendor/autoload.php';

$transport = new StdioTransport(
    command: PHP_BINARY,
    args: [__DIR__ . '/../fixtures/fake-agent.php'],
    cwd: dirname(__DIR__),
);

$client = AcpClient::connect(
    transport: $transport,
    handler: new DefaultClientHandler(),
    clientInfo: new ImplementationInfo(name: 'my-client', version: '0.1.0'),
    capabilities: ClientCapabilities::filesystemReadWrite(),
);

$client->onSessionUpdate(static function ($notification): void {
    echo 'update: ' . json_encode($notification->toArray(), JSON_UNESCAPED_SLASHES) . PHP_EOL;
});

$client->initialize();
$session = $client->newSession(dirname(__DIR__));
$result = $client->prompt($session->sessionId, [ContentBlock::text('Hello ACP')]);

print_r($result->toArray());

$client->close();

使用流程

典型调用顺序是：

1. 创建 TransportInterface 实例
2. 创建 ClientHandlerInterface 实例
3. AcpClient::connect(...)
4. initialize()
5. 如有需要，authenticate()
6. newSession()
7. prompt()
8. 监听 session/update
9. 结束时 close()

高层入口在 src/AcpClient.php。

核心对象

AcpClient

公开 API：

• initialize(): InitializeResult
• authenticate(string $methodId): AuthenticateResult
• newSession(?string $cwd = null, array $mcpServers = []): NewSessionResult
• prompt(string $sessionId, array $prompt, ?string $mode = null): PromptResult
• cancel(string $sessionId): void
• onSessionUpdate(callable $listener): void
• close(): void

StdioTransport

当前唯一已实现的 transport，定义在 src/Transport/StdioTransport.php。

适合：

• 本地 agent 子进程
• CLI agent
• 桌面端嵌入式 agent

DefaultClientHandler

默认 handler 定义在 src/ClientHandler/DefaultClientHandler.php。

默认行为：

• fs/read_text_file：读取本地文件
• fs/write_text_file：写入本地文件
• session/request_permission：默认选第一个 option
• terminal/*：默认抛 ProtocolException

如果你的 agent 会用到终端能力，应该自定义 handler。

自定义 Handler

示例见 examples/custom-handler.php。

你可以：

• 直接实现 src/ClientHandler/ClientHandlerInterface.php
• 或者基于 DefaultClientHandler 传入回调

例如自定义权限确认：

$handler = new DefaultClientHandler(
    requestPermissionHandler: static function ($params) {
        return new RequestPermissionResult(
            outcome: RequestPermissionOutcome::select($params->options[0]->id),
        );
    },
);

ContentBlock

目前建议优先用工厂方法创建内容块：

ContentBlock::text('hello')
ContentBlock::resourceLink('file:///tmp/a.txt', 'a.txt')

实现见 src/Schema/ContentBlock.php。

本地验证

项目内置了一个 fake agent 和验证脚本：

php bin/verify.php

质量检查：

composer cs
composer phpstan
composer test
composer check

示例

• examples/basic-client.php
• examples/custom-handler.php
• bin/verify.php

Roadmap

• 增加 HTTP / WebSocket transport
• 补全更多 ACP schema 类型
• 抽出更稳定的 serializer / mapper 层
• 提供发布到 Packagist 所需的元数据和版本策略