BlueskyManager 與 HasShortHand

概觀

Bluesky Facade 是 BlueskyManager 的薄層封裝。BlueskyManager 管理多個 Agent，HasShortHand trait 則整合了常用方法的捷徑。

架構

BlueskyServiceProvider 將 Factory::class 註冊為 BlueskyManager 的 scoped 單例（每次請求 1 個實體）。

// BlueskyServiceProvider::register()
$this->app->scoped(Factory::class, BlueskyManager::class);

Facade 的 getFacadeAccessor() 會解析此綁定。

// Facades/Bluesky.php
protected static function getFacadeAccessor(): string
{
    return Factory::class;
}

BlueskyManager 的核心方法

以下是 BlueskyManager 自身定義的核心方法。將其與 HasShortHand trait 的方法分開理解，有助於掌握內部結構。

認證

方法	說明
`login(string $identifier, string $password, ?string $service = null)`	使用 App Password 進行認證並設定 `LegacyAgent`
`withToken(?AbstractSession $token)`	傳入 `OAuthSession` 或 `LegacySession` 設定 Agent
`check(): bool`	確認是否已認證（並驗證 token 有效期限）
`refreshSession()`	刷新 token
`logout()`	清除 Agent

Agent 操作

方法	說明
`agent(): ?Agent`	取得目前的 Agent
`withAgent(?Agent $agent)`	直接設定 Agent
`assertDid(): string`	回傳已認證的 DID，未認證時擲出例外

HTTP client

方法	說明
`client(bool $auth = true): AtpClient`	回傳已認證（或匿名）的 XRPC client
`public(): BskyClient`	回傳無需認證的公開端點 client
`send(BackedEnum\|string $api, string $method, bool $auth, ?array $params, ?callable $callback)`	直接呼叫任意的 AT Protocol API

工具

方法	說明
`identity(): Identity`	取得 DID 解析等 identity 服務
`pds(): PDS`	取得 PDS 資訊服務
`entryway(?string $path): string`	回傳服務 URL（如 `bsky.social` 等）
`publicEndpoint(): string`	回傳公開端點 URL

HasShortHand trait

HasShortHand trait 將 AT Protocol 的低階 API 封裝為易讀的 PHP 方法。只要在 BlueskyManager 中寫入 use HasShortHand;，這些方法即可直接透過 Bluesky:: 呼叫。

// BlueskyManager.php
class BlueskyManager implements Factory
{
    use Conditionable;
    use HasShortHand;
    use Macroable;
    // ...
}

之所以將 HasShortHand 獨立為 trait，是為了便於測試與客製化。透過此 trait，可讓 BlueskyManager 的程式碼保持精簡，同時提供豐富的 API 捷徑。

貼文 / feed

方法	說明
`post(Post\|string\|array $text)`	建立新貼文
`getPost(string $uri)`	依 AT-URI 取得貼文
`getPosts(array $uris)`	批次取得多則貼文
`deletePost(string $uri)`	刪除貼文
`getTimeline(?string $algorithm, ?int $limit, ?string $cursor)`	取得首頁時間軸
`getAuthorFeed(?string $actor, ...)`	取得指定帳號的 feed
`searchPosts(string $q, ...)`	搜尋貼文

互動

方法	說明
`like(Like\|StrongRef $subject)`	建立按讚
`deleteLike(string $uri)`	取消按讚
`repost(Repost\|StrongRef $subject)`	建立轉發
`deleteRepost(string $uri)`	取消轉發
`getActorLikes(?string $actor, ...)`	取得帳號的按讚清單

追蹤

方法	說明
`follow(Follow\|string $did)`	追蹤
`deleteFollow(string $uri)`	取消追蹤
`getFollowers(?string $actor, ...)`	取得追蹤者清單
`getFollows(?string $actor, ...)`	取得追蹤中清單

個人資料 / 帳號

方法	說明
`getProfile(?string $actor)`	取得個人資料
`upsertProfile(callable $callback)`	更新個人資料
`resolveHandle(string $handle)`	將 handle 解析為 DID

媒體

方法	說明
`uploadBlob(StreamInterface\|string $data, string $type)`	上傳圖像等 blob
`uploadVideo(StreamInterface\|string $data, string $type)`	上傳影片
`getJobStatus(string $jobId)`	檢查影片上傳的 job 狀態
`getUploadLimits()`	取得上傳限制

通知

方法	說明
`listNotifications(...)`	取得通知清單
`countUnreadNotifications(...)`	取得未讀通知件數
`updateSeenNotifications(string $seenAt)`	更新已讀狀態

AT Protocol record 操作

方法	說明
`createRecord(string $repo, string $collection, ...)`	建立 record
`getRecord(string $repo, string $collection, string $rkey, ...)`	取得 record
`listRecords(string $repo, string $collection, ...)`	取得 record 清單
`putRecord(string $repo, string $collection, string $rkey, ...)`	更新 / 建立 record
`deleteRecord(string $repo, string $collection, string $rkey, ...)`	刪除 record

Feed generator / labeler

方法	說明
`publishFeedGenerator(BackedEnum\|string $name, Generator $generator)`	發佈 feed generator
`createThreadGate(string $post, ?array $allow)`	建立 thread gate
`upsertLabelDefinitions(callable $callback)`	更新標籤定義
`deleteLabelDefinitions()`	刪除標籤定義
`createLabels(RepoRef\|StrongRef\|array $subject, array $labels)`	附加標籤
`deleteLabels(RepoRef\|StrongRef\|array $subject, array $labels)`	移除標籤

常用捷徑範例

貼文

use Revolution\Bluesky\Facades\Bluesky;

$response = Bluesky::login(
    identifier: config('bluesky.identifier'),
    password: config('bluesky.password'),
)->post('Hello Bluesky');

回覆

回覆時透過 Post::build() 設定父貼文的 StrongRef。HasShortHand 中並沒有專用的 reply() 方法，而是將 Post 物件傳給 post()。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Post;
use Revolution\Bluesky\Types\StrongRef;

$parent = StrongRef::to(uri: 'at://did:plc:.../app.bsky.feed.post/...', cid: 'bafyrei...');

$reply = Post::create('回覆的文字內容')
    ->reply(root: $parent, parent: $parent);

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->post($reply);

按讚 / 轉發

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Types\StrongRef;

$ref = StrongRef::to(uri: 'at://did:plc:.../app.bsky.feed.post/...', cid: 'bafyrei...');

// 按讚
Bluesky::withToken($session)->like($ref);

// 轉發
Bluesky::withToken($session)->repost($ref);

更新個人資料

upsertProfile() 會取得目前的個人資料，並儲存於閉包中修改的內容。可透過 Profile 物件的方法設定 displayName、description 等。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Profile;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->upsertProfile(function (Profile $profile) {
        $profile->displayName('新的顯示名稱')
                ->description('個人資料說明文字');
    });

設定 self label

可以透過 SelfLabels 對整個帳號設定 self label。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Record\Profile;
use Revolution\Bluesky\Types\SelfLabels;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->upsertProfile(function (Profile $profile) {
        $profile->labels(SelfLabels::make(['!no-unauthenticated']));
    });

直接呼叫任意 API

HasShortHand 中沒有的方法，可使用 send() 或 client()。

use Revolution\Bluesky\Facades\Bluesky;

// 以 send() 呼叫任意 XRPC 方法
$response = Bluesky::withToken($session)
    ->send(
        api: 'app.bsky.actor.getProfiles',
        method: 'get',
        params: ['actors' => ['did:plc:...', 'did:plc:...']],
    );

// 以 client() 進行更細部的操作
$response = Bluesky::withToken($session)
    ->client()
    ->bsky()
    ->getProfiles(actors: ['did:plc:...']);

透過 Facade 與直接使用的差異

Bluesky::post() 與 app(Factory::class)->post() 對應的是同一個 BlueskyManager 實體。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Contracts\Factory;

// 透過 Facade（常見用法）
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->post('Hello');

// 從容器直接取得
$manager = app(Factory::class);
$manager->login(config('bluesky.identifier'), config('bluesky.password'))
        ->post('Hello');

// 以型別提示進行 DI
class MyService
{
    public function __construct(private Factory $bluesky) {}

    public function doPost(): void
    {
        $this->bluesky->login(
            config('bluesky.identifier'),
            config('bluesky.password'),
        )->post('Hello from DI');
    }
}

由於是 scoped 註冊，因此在一次請求內，login() 之後的 session 狀態會被保留。

Conditionable 與 Macroable

BlueskyManager 同時使用了 Conditionable 與 Macroable trait。

Conditionable：when() / unless()

use Revolution\Bluesky\Facades\Bluesky;

Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->when(config('app.env') === 'production', function ($bluesky) {
        $bluesky->post('從正式環境的貼文');
    });

Macroable：新增自訂方法

透過 macro() 可從應用程式端向 BlueskyManager 增加方法。通常在 AppServiceProvider 的 boot() 中定義。

use Revolution\Bluesky\Facades\Bluesky;

Bluesky::macro('postWithHashtag', function (string $text, string $tag) {
    /** @var \Revolution\Bluesky\BlueskyManager $this */
    return $this->post("{$text} #{$tag}");
});

// 使用範例
Bluesky::login(config('bluesky.identifier'), config('bluesky.password'))
    ->postWithHashtag('Hello', 'laravel');

插入自訂 Agent

透過 withAgent() 可直接設定任意的 Agent 實作。

use Revolution\Bluesky\Facades\Bluesky;
use Revolution\Bluesky\Contracts\Agent;

// 實作自訂 Agent 時，需實作 Agent 介面
class MyCustomAgent implements Agent
{
    // ...
}

Bluesky::withAgent(new MyCustomAgent());

一般認證（login() / withToken()）會自動設定 agent，因此直接使用 withAgent() 的機會主要在測試時。

參考連結

認證方式比較 — App Password 與 OAuth 的詳細差異
Basic client — 認證後的 API 操作範例
測試 — 使用 Fake 進行測試的方式
Source：src/BlueskyManager.php
Source：src/HasShortHand.php

GitHub Copilot

SDK

AI SDK

VOICEVOX

入門套件

Feed 與 RSS

中介層

概觀

架構

BlueskyManager 的核心方法

認證

Agent 操作

HTTP client

工具

HasShortHand trait

貼文 / feed

互動

追蹤

個人資料 / 帳號

媒體

通知

AT Protocol record 操作

Feed generator / labeler

常用捷徑範例

貼文

回覆

按讚 / 轉發

更新個人資料

設定 self label

直接呼叫任意 API

透過 Facade 與直接使用的差異

Conditionable 與 Macroable

Conditionable：when() / unless()

Macroable：新增自訂方法

插入自訂 Agent

參考連結

​概觀

​架構

​BlueskyManager 的核心方法

​認證

​Agent 操作

​HTTP client

​工具

​HasShortHand trait

​貼文 / feed

​互動

​追蹤

​個人資料 / 帳號

​媒體

​通知

​AT Protocol record 操作

​Feed generator / labeler

​常用捷徑範例

​貼文

​回覆

​按讚 / 轉發

​更新個人資料

​設定 self label

​直接呼叫任意 API

​透過 Facade 與直接使用的差異

​Conditionable 與 Macroable

​Conditionable：when() / unless()

​Macroable：新增自訂方法

​插入自訂 Agent

​參考連結

概觀

架構

BlueskyManager 的核心方法

認證

Agent 操作

HTTP client

工具

HasShortHand trait

貼文 / feed

互動

追蹤

個人資料 / 帳號

媒體

通知

AT Protocol record 操作

Feed generator / labeler

常用捷徑範例

貼文

回覆

按讚 / 轉發

更新個人資料

設定 self label

直接呼叫任意 API

透過 Facade 與直接使用的差異

Conditionable 與 Macroable

Conditionable：when() / unless()

Macroable：新增自訂方法

插入自訂 Agent

參考連結