Skip to content

README_CN.md

Latest commit

 

History

History
266 lines (200 loc) · 6.31 KB

README_CN.md

File metadata and controls

266 lines (200 loc) · 6.31 KB

Poe Rust SDK

一个用于构建 Poe 服务器机器人的 Rust SDK，完全遵循 Poe 协议规范。

特性

  • 🚀 完整的 Poe 协议支持 - 支持所有请求类型（query、settings、report_feedback 等）
  • 🔒 内置认证 - Bearer token 验证和用户代理检查
  • 📡 流式响应 - 支持实时流式文本响应
  • ⚡ 高性能 - 基于 Axum 和 Tokio 构建的异步服务器
  • 🛡️ 错误处理 - 完整的错误类型定义和处理
  • 📝 类型安全 - 完整的 TypeScript 风格类型定义
  • 🔧 配置管理 - 灵活的配置系统
  • 📚 详细文档 - 完整的 API 文档和使用示例

快速开始

安装

将以下内容添加到您的 Cargo.toml：

[dependencies]
poe-rust-sdk = "0.1.0"
tokio = { version = "1", features = ["full"] }

基本使用

use poe_rust_sdk::{
    BotHandler, PoeRequest, PoeResponse, QueryRequest, 
    PartialResponse, text_response, init
};
use async_trait::async_trait;

#[derive(Clone)]
struct MyBot;

#[async_trait]
impl BotHandler for MyBot {
    async fn handle_query(&self, request: QueryRequest) -> Result<PoeResponse, Box<dyn std::error::Error + Send + Sync>> {
        let response_text = format!("你好！你说了：{}", 
            request.query.last().map(|m| &m.content).unwrap_or("(空消息)"));
        
        Ok(text_response!(response_text))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 初始化 SDK
    let bot = MyBot;
    let server = init(bot, "your-access-key".to_string()).await?;
    
    // 启动服务器
    println!("🤖 Poe 机器人服务器启动在 http://0.0.0.0:8080");
    server.serve().await?;
    
    Ok(())
}

高级使用

流式响应

use futures::stream;
use async_stream::stream;

#[async_trait]
impl BotHandler for MyBot {
    async fn handle_query(&self, request: QueryRequest) -> Result<PoeResponse, Box<dyn std::error::Error + Send + Sync>> {
        let response_stream = stream! {
            yield PartialResponse {
                text: "正在思考".to_string(),
                is_suggested_reply: false,
                is_replace_response: false,
            };
            
            // 模拟处理时间
            tokio::time::sleep(tokio::time::Duration::from_millis(500)).await;
            
            yield PartialResponse {
                text: "...完成！".to_string(),
                is_suggested_reply: false,
                is_replace_response: false,
            };
        };
        
        Ok(PoeResponse {
            text: String::new(),
            data: Some(serde_json::json!({})),
            raw_response: None,
            content_type: "text/plain".to_string(),
            suggested_replies: vec![],
            error_allow_retry: false,
        })
    }
}

自定义配置

use poe_rust_sdk::{BotConfig, PoeServer};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = BotConfig {
        access_key: "your-access-key".to_string(),
        bot_name: "MyAwesomeBot".to_string(),
        server_host: "0.0.0.0".to_string(),
        server_port: 8080,
        allow_without_key: false,
        request_timeout_ms: 600000,
        max_request_size: 1024 * 1024, // 1MB
        enable_cors: true,
        cors_origins: vec!["*".to_string()],
    };
    
    let bot = MyBot;
    let server = PoeServer::new(bot, config).await?;
    
    server.serve().await?;
    Ok(())
}

API 文档

核心特征

BotHandler

实现此特征来定义您的机器人行为：

#[async_trait]
pub trait BotHandler: Clone + Send + Sync + 'static {
    async fn handle_query(&self, request: QueryRequest) -> Result<PoeResponse, Box<dyn std::error::Error + Send + Sync>>;
    async fn handle_settings(&self, request: SettingsRequest) -> Result<SettingsResponse, Box<dyn std::error::Error + Send + Sync>>;
    async fn handle_report_feedback(&self, request: ReportFeedbackRequest) -> Result<(), Box<dyn std::error::Error + Send + Sync>>;
    async fn handle_report_error(&self, request: ReportErrorRequest) -> Result<(), Box<dyn std::error::Error + Send + Sync>>;
}

请求类型

  • QueryRequest - 用户查询请求
  • SettingsRequest - 机器人设置请求
  • ReportFeedbackRequest - 用户反馈报告
  • ReportErrorRequest - 错误报告

响应类型

  • PoeResponse - 标准响应
  • PartialResponse - 流式响应片段
  • SettingsResponse - 设置响应

便利宏

// 创建文本响应
let response = text_response!("Hello, world!");

// 创建带建议回复的响应
let response = suggested_response!("Hello!", vec!["Hi there!", "How are you?"]);

配置

环境变量

# 必需
POE_ACCESS_KEY=your-access-key-here

# 可选
POE_BOT_NAME=MyBot
POE_SERVER_HOST=0.0.0.0
POE_SERVER_PORT=8080
POE_REQUEST_TIMEOUT_MS=600000
POE_MAX_REQUEST_SIZE=1048576
POE_ENABLE_CORS=true
POE_CORS_ORIGINS=*

配置文件

创建 bot.toml：

[bot]
name = "MyBot"
access_key = "your-access-key"

[server]
host = "0.0.0.0"
port = 8080
request_timeout_ms = 600000
max_request_size = 1048576

[cors]
enable = true
origins = ["*"]

部署

Docker

FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/poe-bot-example /usr/local/bin/poe-bot
EXPOSE 8080
CMD ["poe-bot"]

构建和运行

# 开发模式
cargo run

# 发布模式
cargo build --release
./target/release/poe-bot-example

示例

查看 src/main.rs 获取完整的示例实现。

协议支持

此 SDK 完全支持 Poe 协议规范 的所有功能：

  • ✅ 查询处理（Query）
  • ✅ 设置管理（Settings）
  • ✅ 反馈报告（Report Feedback）
  • ✅ 错误报告（Report Error）
  • ✅ 流式响应
  • ✅ 认证验证
  • ✅ 请求验证
  • ✅ 错误处理
  • ✅ CORS 支持

许可证

本项目采用 MIT 或 Apache-2.0 双重许可证。

贡献

欢迎贡献！请查看我们的贡献指南。

支持

如果您遇到问题或有疑问，请在 GitHub 上创建 issue。