PDS (AT Protocol) API Skill

使用 AT Protocol XRPC API 交互个人数据服务器 (PDS)。

PDS Endpoint

https://pds.seekkey.eu.org

认证 (Authentication)

AT Protocol 使用 JWT 进行认证。通过向 com.atproto.server.createSession 发送请求获取 Access Token (JWT)。

1. 创建会话 (登录)

curl -X POST https://pds.seekkey.eu.org/xrpc/com.atproto.server.createSession \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "your_handle.pds.seekkey.eu.org",
    "password": "your_app_password_or_password"
  }'

响应示例：

{
  "accessJwt": "eyJhbGciOi...",
  "refreshJwt": "eyJhbGciOi...",
  "handle": "your_handle.pds.seekkey.eu.org",
  "did": "did:plc:..."
}

后续请求需要在 Header 中携带 Authorization: Bearer <accessJwt>。

核心操作

1. 发布帖子 (Create Record - Post)

在 AT Protocol 中，发布帖子（Post）是向用户的仓库中写入一条 app.bsky.feed.post 类型的记录。

curl -X POST https://pds.seekkey.eu.org/xrpc/com.atproto.repo.createRecord \
  -H "Authorization: Bearer <accessJwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your_did_or_handle",
    "collection": "app.bsky.feed.post",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "Hello, this is a post from my agent!",
      "createdAt": "2026-06-11T09:20:00Z"
    }
  }'

参数说明：
* repo: 用户的 DID 或 Handle
* collection: 记录的类型集合名称（发布帖子为 app.bsky.feed.post）
* record: 具体的记录对象，必须包含 $type 和 createdAt，以及 text 等字段。

2. 上传媒体文件 (Upload Blob)

发布带图片或视频的帖子前，必须先将媒体文件上传，获取到对应的 blob 对象。

curl -X POST https://pds.seekkey.eu.org/xrpc/com.atproto.repo.uploadBlob \
  -H "Authorization: Bearer <accessJwt>" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@/path/to/image.jpg"

响应示例：

{
  "blob": {
    "$link": "bafkreih...",
    "mimeType": "image/jpeg",
    "size": 12345
  }
}

然后，在 createRecord 时将该 blob 插入到 embed 字段中：

{
  "repo": "your_did_or_handle",
  "collection": "app.bsky.feed.post",
  "record": {
    "$type": "app.bsky.feed.post",
    "text": "Check out this image!",
    "createdAt": "2026-06-11T09:20:00Z",
    "embed": {
      "$type": "app.bsky.embed.images",
      "images": [
        {
          "image": {
            "$type": "blob",
            "ref": {
              "$link": "bafkreih..."
            },
            "mimeType": "image/jpeg",
            "size": 12345
          },
          "alt": "Image description"
        }
      ]
    }
  }
}

3. 获取特定记录 (Get Record)

curl "https://pds.seekkey.eu.org/xrpc/com.atproto.repo.getRecord?repo=<did>&collection=app.bsky.feed.post&rkey=<rkey>"

4. 管理员接口：生成邀请码 (Create Invite Code)

只有管理员有权调用。需要使用管理员基本认证 (Basic auth，账户为 admin，密码从 Infisical 获取 PDS_ADMIN_PASSWORD)。

TOKEN=$(cat ~/.infisical/universal-token)
PDS_ADMIN_PASSWORD=$(infisical secrets get PDS_ADMIN_PASSWORD --domain https://infisical.git4ta.fun --projectId 7fb32203-5f5d-47cc-bca7-9cba8a9eba0e --env dev --token "$TOKEN" --plain)

curl -X POST \
  -H "Authorization: Basic $(echo -n "admin:${PDS_ADMIN_PASSWORD}" | base64)" \
  -H "Content-Type: application/json" \
  -d '{"useCount": 1}' \
  https://pds.seekkey.eu.org/xrpc/com.atproto.server.createInviteCode

响应示例：

{
  "code": "pds-seekkey-eu-org-xxxxx-xxxxx"
}

使用场景

1. 自动发布社交内容：Agent 将工作成果或定时任务结果推送到 Bluesky 社交平台。
2. 生成用户邀请码：当有新用户需要接入您的 PDS 服务时，通过管理员账户自动为其分发邀请码。
3. 读取用户仓库记录：读取或分析当前 PDS 上的用户数据和行为。

最佳实践与注意事项

1. 时区与时间戳：createdAt 必须是符合 ISO 8601 标准的 UTC 时间戳（如 YYYY-MM-DDTHH:mm:ss.sssZ）。
2. 应用密码 (App Passwords)：登录时强烈建议不要使用账户主密码，而是前往 Bluesky 设置生成应用密码（App Password），并以此进行认证。
3. 限频控制：PDS 启用了速率限制 (PDS_RATE_LIMITS_ENABLED=true)，调用 API 时请注意调频，避免产生 429 Too Many Requests。