README

一个功能完整、设计优雅的 Coze AI 平台 PHP SDK，提供机器人管理、聊天对话、会话管理等核心功能。

✨ 特性

🚀 高性能: 基于 Symfony HTTP Client，支持连接池和并发请求
🔐 安全认证: 完整的 JWT Bearer 认证机制，自动令牌刷新
💾 智能缓存: 多层缓存策略，提升性能和稳定性
📝 详细日志: 完整的日志记录系统，便于调试和监控
🛡️ 类型安全: 完整的 PHP 8.2+ 类型声明
🧪 测试覆盖: 全面的单元测试和集成测试
🔧 易于扩展: 模块化设计，易于扩展和维护

📦 安装

composer require pfinalclub/coze_sdk

🚀 快速开始

基本配置

<?php

use CozeSdk\OfficialAccount\Application;
use CozeSdk\Kernel\Support\SimpleLogger;

// 创建应用实例
$app = new Application([
    'kid' => 'your_kid_here',
    'iss' => 'your_iss_here',
    'keyPath' => '/path/to/your/private_key.pem',
    'botId' => 'your_bot_id_here'
], new SimpleLogger());

// 验证配置
$app->validate();

聊天功能

<?php

use CozeSdk\Chat\Chat;

// 创建聊天实例
$chat = new Chat($app);

// 发送消息
$response = $chat->setUserId('user_123')
    ->sendMessage('你好，请介绍一下PHP');

// 处理响应
foreach ($response['messages'] as $message) {
    echo $message['content'] . "\n";
}

机器人管理

<?php

use CozeSdk\Bot\Bot;

// 创建机器人管理实例
$bot = new Bot($app->getAccessToken());

// 获取机器人列表
$botList = $bot->setSpaceId('your_space_id')
    ->getBotList();

// 获取机器人详情
$botDetail = $bot->getBotDetail('bot_id_here');

// 搜索机器人
$searchResults = $bot->searchBots('关键词');

流式聊天

SDK 提供了强大的流式传输支持，支持多种处理方式：

基本流式传输

<?php

use CozeSdk\Chat\Chat;

$chat = new Chat($app);

// 创建流式聊天（兼容旧版本）
$streamCallback = $chat->setUserId('user_123')
    ->Query('请写一个PHP函数')
    ->Build(true);

// 执行流式响应
$streamCallback();

高级流式传输（推荐）

<?php

use CozeSdk\Chat\Chat;
use CozeSdk\Kernel\Support\{
    ConsoleStreamHandler,
    JsonStreamHandler,
    MemoryStreamHandler,
    CallbackStreamHandler
};

$chat = new Chat($app);

// 1. 控制台输出流式处理器
$consoleHandler = new ConsoleStreamHandler();
$result = $chat->sendStreamMessage('你好，请介绍一下PHP', $consoleHandler);

// 2. JSON流式处理器
$jsonHandler = new JsonStreamHandler();
$result = $chat->sendStreamMessage('写一个简单的函数', $jsonHandler);

// 3. 内存流式处理器
$memoryHandler = new MemoryStreamHandler();
$result = $chat->sendStreamMessage('解释什么是OOP', $memoryHandler);

// 4. 回调流式处理器（最灵活）
$callbackHandler = new CallbackStreamHandler(
    function($chunk, $metadata) {
        // 处理每个数据块
        echo $chunk;
        flush();
        return true; // 继续处理
    },
    function($metadata) {
        // 流式传输开始
        echo "开始接收数据...\n";
    },
    function($metadata) {
        // 流式传输结束
        echo "\n接收完成\n";
    },
    function($error, $metadata) {
        // 错误处理
        echo "错误: " . $error->getMessage() . "\n";
    }
);

$result = $chat->sendStreamMessage('请写一个详细的教程', $callbackHandler);

高级流式传输功能

SDK 还提供了更高级的流式传输功能：

<?php

use CozeSdk\Chat\Chat;
use CozeSdk\Kernel\Support\{
    EnhancedStreamHandler,
    RealTimeTextHandler,
    ProgressMonitorHandler
};

$chat = new Chat($app);

// 1. 实时文本流式传输
$result = $chat->sendRealTimeMessage('请介绍一下PHP');
echo "文本长度: " . strlen($result) . " 字符";

// 2. 带进度监控的流式传输
$result = $chat->sendProgressMessage('请写一个详细的教程', 20);
echo "统计信息: " . json_encode($result['stats']);

// 3. 增强流式处理器
$result = $chat->sendEnhancedMessage(
    '请解释什么是OOP',
    // 文本回调
    function($text, $metadata) {
        echo $text;
        flush();
        return true;
    },
    // 数据回调
    function($data, $metadata) {
        // 处理结构化数据
        return true;
    },
    // 进度回调
    function($stats, $metadata) {
        echo "\r进度: {$stats['total_text_length']} 字符";
    }
);

流式处理器类型

SDK 提供了多种流式处理器：

ConsoleStreamHandler: 控制台输出
JsonStreamHandler: JSON数据解析
MemoryStreamHandler: 内存存储
FileStreamHandler: 文件存储
CallbackStreamHandler: 回调处理
RealTimeTextHandler: 实时文本显示
ProgressMonitorHandler: 进度监控
EnhancedStreamHandler: 增强处理能力

📚 API 文档

Application 类

主要的应用配置和管理类。

$app = new Application($config, $logger, $cache, $httpClient);

// 获取访问令牌
$accessToken = $app->getAccessToken();

// 获取机器人ID
$botId = $app->getBotId();

// 验证配置
$app->validate();

Chat 类

聊天对话功能。

$chat = new Chat($app, $httpClient, $cache, $logger);

// 设置参数
$chat->setBotId('bot_id')
    ->setUserId('user_id')
    ->setConversationId('conversation_id');

// 发送消息
$response = $chat->sendMessage('消息内容');

// 获取聊天详情
$detail = $chat->getChatRetrieve('chat_id');

// 获取消息列表
$messages = $chat->getChatMessageList('chat_id');

Bot 类

机器人管理功能。

$bot = new Bot($accessToken, $httpClient, $cache, $logger);

// 设置空间ID
$bot->setSpaceId('space_id');

// 获取机器人列表
$botList = $bot->getBotList();

// 获取机器人详情
$botDetail = $bot->getBotDetail('bot_id');

// 获取机器人ID列表
$botIds = $bot->getBotIdList();

// 搜索机器人
$results = $bot->searchBots('关键词');

// 获取统计信息
$stats = $bot->getBotStats();

🔧 配置选项

配置项	类型	必需	描述
`kid`	string	是	密钥ID
`iss`	string	是	发行者ID
`keyPath`	string	是	私钥文件路径
`botId`	string	否	机器人ID
`iat`	string	否	令牌签发时间（默认当前时间）
`exp`	string	否	令牌过期时间（默认1小时后）
`token`	string	否	预生成的令牌

🧪 测试

运行测试

# 运行单元测试（推荐，不依赖API）
composer test:unit

# 运行流式传输测试
composer test:stream

# 运行API测试（需要有效配置）
composer test:api

# 运行所有测试
composer test:all

# 生成测试覆盖率报告
composer test:coverage

# 生成测试报告
composer test:report

测试脚本

# 运行单元测试
php tests/run_tests.php --unit

# 运行流式传输测试
php tests/run_tests.php --stream

# 运行所有测试
php tests/run_tests.php --all

# 显示帮助信息
php tests/run_tests.php --help

快速测试

# 运行简单单元测试
php tests/simple_unit_test.php

# 运行快速功能测试
php tests/quick_test.php

# 验证PHPUnit配置
php tests/test_phpunit.php

测试环境

模拟模式（默认）: 不需要真实API配置，适合开发和CI
真实API模式: 需要有效的API配置，用于集成测试

详细测试说明请参考测试指南

📝 日志

SDK 提供了完整的日志记录功能：

use CozeSdk\Kernel\Support\SimpleLogger;

// 创建日志实例
$logger = new SimpleLogger(true); // 启用日志

// 日志文件位置
// Linux/Mac: /tmp/coze_sdk_logs/coze_sdk.log
// Windows: C:\Users\{username}\AppData\Local\Temp\coze_sdk_logs\coze_sdk.log

🔄 缓存

SDK 支持多种缓存策略：

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

// 文件系统缓存
$cache = new Psr16Cache(new FilesystemAdapter('coze', 1500));

// Redis 缓存（需要安装 redis 扩展）
$cache = new Psr16Cache(new RedisAdapter($redis));

// 内存缓存（测试用）
$cache = new Psr16Cache(new ArrayAdapter());

🛠️ 错误处理

SDK 提供了详细的错误处理：

use CozeSdk\Kernel\Exception\HttpException;
use CozeSdk\Kernel\Exception\ParamsException;

try {
    $response = $chat->sendMessage('消息');
} catch (ParamsException $e) {
    // 参数错误
    echo "参数错误: " . $e->getMessage();
} catch (HttpException $e) {
    // HTTP 请求错误
    echo "请求错误: " . $e->getMessage();
} catch (\Exception $e) {
    // 其他错误
    echo "未知错误: " . $e->getMessage();
}

🤝 贡献

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

👨‍💻 作者

PFinal南丞 - GitHub - lampxiezi@163.com

🙏 致谢

感谢 Coze AI 平台提供的优秀 API 服务。

⭐ 如果这个项目对你有帮助，请给它一个星标！

pfinalclub / coze_sdk

Maintainers

Details