Bot 教學 - Laravel Bluesky - Knowledge of Laravel

概觀

本頁面是 AT Protocol 官方 bot 教學的 Laravel 版。說明如何以 laravel-bluesky 套件將 TypeScript 版的內容以 PHP/Laravel 實作。官方教學中會透過 lex 指令逐次下載 Lexicon 檔案，但 laravel-bluesky 已透過 atproto-lexicon-contracts 事先納入所有 Lexicon，因此不需這些步驟。透過 Artisan 指令與 HasShortHand trait 的方法，幾乎所有操作皆可實作。

前置條件

已安裝 laravel-bluesky 套件
已準備好 Bluesky 帳號與 App Password

安裝方式請參考 Laravel Bluesky。

BLUESKY_IDENTIFIER=yourbot.bsky.social
BLUESKY_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx

第 1 部分：基本 bot（貼文）

建立 Artisan 指令

以 php artisan make:command 建立 bot 用的指令。

php artisan make:command BotPostCommand

編輯所產生的 app/Console/Commands/BotPostCommand.php。

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Revolution\Bluesky\Facades\Bluesky;

class BotPostCommand extends Command
{
    protected $signature = 'bot:post';

    protected $description = 'Post to Bluesky';

    public function handle(): void
    {
        Bluesky::login(
            identifier: config('bluesky.identifier'),
            password: config('bluesky.password'),
        )->post('🙂');

        $this->info('Posted successfully.');
    }
}

手動執行

php artisan bot:post

以任務排程自動執行

於 routes/console.php 加入定期執行設定。

use Illuminate\Support\Facades\Schedule;

// 每 3 小時貼文一次
Schedule::command('bot:post')->everyThreeHours();

要啟用排程器，請在 cron 中設定以下內容。

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

以 GitHub Actions 自動執行

若沒有伺服器，也可以透過 GitHub Actions 自動執行。

# .github/workflows/bot.yml
name: Bot Post

on:
  schedule:
    - cron: '0 */3 * * *'  # 每 3 小時
  workflow_dispatch:

jobs:
  post:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
      - run: composer install --no-dev --optimize-autoloader
      - run: php artisan bot:post
        env:
          BLUESKY_IDENTIFIER: ${{ secrets.BLUESKY_IDENTIFIER }}
          BLUESKY_APP_PASSWORD: ${{ secrets.BLUESKY_APP_PASSWORD }}

請於 GitHub Actions 的 secrets 中註冊 BLUESKY_IDENTIFIER 與 BLUESKY_APP_PASSWORD。

第 2 部分：回覆 bot（監控 mention）

建立自動回覆 mention 的 bot。同時介紹使用 AI 生成回覆的範例。

取得通知並回覆 mention

php artisan make:command BotReplyCommand

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\Types\ReplyRef;
use Revolution\Bluesky\Types\StrongRef;

class BotReplyCommand extends Command
{
    protected $signature = 'bot:reply';

    protected $description = 'Reply to mentions on Bluesky';

    public function handle(): void
    {
        Bluesky::login(
            identifier: config('bluesky.identifier'),
            password: config('bluesky.password'),
        );

        $notifications = Bluesky::listNotifications(limit: 20)->json('notifications', []);

        foreach ($notifications as $notification) {
            // 僅處理 mention 通知
            if (data_get($notification, 'reason') !== 'mention') {
                continue;
            }

            // 略過已讀通知（isRead 為 true 者代表已處理）
            if (data_get($notification, 'isRead')) {
                continue;
            }

            $uri = data_get($notification, 'uri');
            $cid = data_get($notification, 'cid');

            if (! $uri || ! $cid) {
                continue;
            }

            $ref = StrongRef::to(uri: $uri, cid: $cid);
            $reply = ReplyRef::to(root: $ref, parent: $ref);

            $post = Post::create('你好！感謝你的 mention。🙂')
                ->reply($reply);

            Bluesky::post($post);

            $this->info("Replied to: {$uri}");
        }

        // 將通知標記為已讀
        Bluesky::updateSeenNotifications(now()->toISOString());
    }
}

若 thread 的 root 不同，請以 app.bsky.feed.getPostThread 取得 thread 資訊並設定為 root。此簡化實作將父貼文視為 root。

排程輪詢

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('bot:reply')->everyFiveMinutes();

使用 AI 生成回覆

將 laravel/ai 套件與 laravel-amazon-bedrock 驅動結合，即可依 mention 內容生成 AI 回覆。

composer require laravel/ai revolution/laravel-amazon-bedrock

建立 AI agent。

<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

class BotReplyAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return '你是一個在 Bluesky 上活動的友善 bot。'
            . '請針對使用者的訊息，以繁體中文生成簡短親切的回覆。'
            . '回覆請控制在 200 字以內。';
    }
}

在指令中使用 AI 回覆。

<?php

namespace App\Console\Commands;

use App\Ai\Agents\BotReplyAgent;
use Illuminate\Console\Command;
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\Types\ReplyRef;
use Revolution\Bluesky\Types\StrongRef;

class BotReplyCommand extends Command
{
    protected $signature = 'bot:reply';

    protected $description = 'Reply to mentions on Bluesky using AI';

    public function handle(): void
    {
        Bluesky::login(
            identifier: config('bluesky.identifier'),
            password: config('bluesky.password'),
        );

        $notifications = Bluesky::listNotifications(limit: 20)->json('notifications', []);

        foreach ($notifications as $notification) {
            if (data_get($notification, 'reason') !== 'mention') {
                continue;
            }

            if (data_get($notification, 'isRead')) {
                continue;
            }

            $uri = data_get($notification, 'uri');
            $cid = data_get($notification, 'cid');
            $mentionText = data_get($notification, 'record.text', '');

            if (! $uri || ! $cid) {
                continue;
            }

            // 以 AI 生成回覆
            $replyText = (new BotReplyAgent)->prompt($mentionText)->text;

            $ref = StrongRef::to(uri: $uri, cid: $cid);
            $reply = ReplyRef::to(root: $ref, parent: $ref);

            $post = Post::create($replyText)->reply($reply);

            Bluesky::post($post);

            $this->info("AI replied to: {$uri}");
        }

        Bluesky::updateSeenNotifications(now()->toISOString());
    }
}

laravel-amazon-bedrock 的設定方式請參考 Amazon Bedrock 驅動。

第 3 部分：Label bot

此為對應官方教學中 labelAsBot 的功能。對 bot 帳號的個人資料附加 self label，明示這是自動化帳號。

Label 只需在初次設定時執行一次即可。與第 1、2 部分的指令獨立實作為另一個指令。

建立 label bot 指令

php artisan make:command BotLabelCommand

<?php

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Profile;
use Revolution\Bluesky\Types\SelfLabels;

class BotLabelCommand extends Command
{
    protected $signature = 'bot:label';

    protected $description = 'Add bot self-label to the Bluesky profile';

    public function handle(): void
    {
        Bluesky::login(
            identifier: config('bluesky.identifier'),
            password: config('bluesky.password'),
        )->upsertProfile(function (Profile $profile) {
            // 設定 !bot label
            $profile->labels(SelfLabels::make(['!bot']));
        });

        $this->info('Bot label applied successfully.');
    }
}

執行

php artisan bot:label

本指令請於 bot 首次設定時執行一次。Label 會永久儲存在個人資料中。

!bot 是 Bluesky 標準的 self label。強烈建議所有 bot 帳號都要設定。

關於其他官方教學

AT Protocol 的官方教學還有其他數個主題。以下彙整 laravel-bluesky 的對應狀況。

自訂 feed

Feed Generator 詳細說明使用 Laravel 實作自訂 feed generator 的方法。

OAuth 認證

Socialite 中說明使用 Laravel Socialite 進行 OAuth 認證的實作方式，比官方教學更容易實作。

社群應用（statusphere）

Laravel 版的 statusphere 於 invokable/statusphere 公開。其基於未使用 lex 或 tap 指令的舊版 statusphere，因此與最新的官方教學略有差異。

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

Bot 教學 - Laravel Bluesky

概觀

前置條件

第 1 部分：基本 bot（貼文）

建立 Artisan 指令

手動執行

以任務排程自動執行

以 GitHub Actions 自動執行

第 2 部分：回覆 bot（監控 mention）

取得通知並回覆 mention

排程輪詢

使用 AI 生成回覆

第 3 部分：Label bot

建立 label bot 指令

執行

關於其他官方教學

自訂 feed

OAuth 認證

社群應用（statusphere）

參考連結

​概觀

​前置條件

​第 1 部分：基本 bot（貼文）

​建立 Artisan 指令

​手動執行

​以任務排程自動執行

​以 GitHub Actions 自動執行

​第 2 部分：回覆 bot（監控 mention）

​取得通知並回覆 mention

​排程輪詢

​使用 AI 生成回覆

​第 3 部分：Label bot

​建立 label bot 指令

​執行

​關於其他官方教學

​自訂 feed

​OAuth 認證

​社群應用（statusphere）

​參考連結

概觀

前置條件

第 1 部分：基本 bot（貼文）

建立 Artisan 指令

手動執行

以任務排程自動執行

以 GitHub Actions 自動執行

第 2 部分：回覆 bot（監控 mention）

取得通知並回覆 mention

排程輪詢

使用 AI 生成回覆

第 3 部分：Label bot

建立 label bot 指令

執行

關於其他官方教學

自訂 feed

OAuth 認證

社群應用（statusphere）

參考連結