social-cli

social-cli

针对 Agent 优化的社交 CLI。支持 Bluesky 和 X。输入 YAML，输出 YAML，并为自动化提供退出码。

仓库：https://github.com/letta-ai/social-cli

安装设置

1. 安装

git clone https://github.com/letta-ai/social-cli.git
cd social-cli
pnpm install
pnpm build

在全局范围链接该二进制文件，或在仓库目录中通过 node dist/cli.js / pnpm start 调用。

2. 凭据

在运行 social-cli 的工作目录中创建 .env：

# Bluesky / ATProto
ATPROTO_HANDLE=you.bsky.social
ATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx
ATPROTO_PDS=https://bsky.social          # optional, defaults to bsky.social

# X / Twitter (OAuth 1.0a)
X_API_KEY=...
X_API_SECRET=...
X_ACCESS_TOKEN=...
X_ACCESS_TOKEN_SECRET=...
X_BEARER_TOKEN=...                       # optional, for app-only endpoints

只需提供你实际使用的平台的凭据。

3. 验证

social-cli whoami
social-cli rate-limits

Agent 循环（同步 → 检查 → 分发）

标准自动化工作流。每个阶段都会读取和写入工作目录中的 YAML 文件。

social-cli sync                    # pull notifications → inbox-{platform}.yaml
social-cli check || exit 0         # anything actionable? exit 1 = nothing to do
# read inbox, decide, write outbox-{platform}.yaml
social-cli dispatch                # execute outbox, archive results

• sync：根据 sent_ledger-{platform}.yaml 去重，并限制收件箱大小。
• check：如果收件箱中有可处理的项目，则退出码为 0；否则为 1。在 cron 循环中使用时，请以 || exit 0 包装。
• dispatch：以原子方式执行发件箱操作。写入 dispatch_result-{platform}.yaml，并追加到 sent_ledger-{platform}.yaml，以防止重放。

快速命令

# Post / reply / thread
social-cli post "Hello world" -p bsky
social-cli reply "Thanks" --id "at://did:plc:.../app.bsky.feed.post/abc" -p bsky
social-cli thread "p1" "p2" "p3" -p bsky

# Engagement
social-cli like "at://..." -p bsky
social-cli delete "at://..." -p bsky
social-cli follow "handle.bsky.social" -p bsky

# Reading
social-cli search "query" -p bsky -n 10              # → stdout YAML
social-cli feed -p bsky -n 20                        # → feed.yaml (or -o - for stdout)
social-cli feed --feed "at://did:.../app.bsky.feed.generator/name" -n 10  # custom feed
social-cli profile "handle.bsky.social" -p bsky
social-cli whoami
social-cli rate-limits

注释（仅限 Bluesky）

使用 at.margin.note 词汇表（W3C Web Annotation 模型）。注释适用于任何 URL，而不仅限于 ATProto 帖子。注释会显示在 margin.at 和 Semble 中。

# Annotate a web page
social-cli annotate "Note about this article" --target https://example.com

# Anchor to an exact passage
social-cli annotate "Key insight" --target https://example.com \
  --quote "exact passage from the page" --motivation highlighting

动机：commenting、highlighting、questioning、describing、linking。

收件箱格式（inbox-{platform}.yaml）

notifications:
  - id: "at://did:plc:xxx/app.bsky.feed.post/abc"
    platform: bsky
    type: mention          # mention, reply, like, follow, repost, quote
    author: someone.bsky.social
    authorId: "did:plc:xxx"
    postId: "at://..."
    text: "Hey, what do you think?"
    timestamp: "2026-03-25T12:00:00Z"
    parentPostId: "at://..."     # for replies
    parentPostText: "..."        # context
    rootPostId: "at://..."       # thread root
    rootPostText: "..."

发件箱格式（outbox-{platform}.yaml）

将操作写入 dispatch 列表。每个条目都是一个独立操作。

dispatch:
  - reply:
      platform: bsky
      id: "at://did:plc:xxx/app.bsky.feed.post/abc"
      text: "Thanks for the mention"

  - post:
      text: "Hello from my agent"
      platforms: [bsky, x]          # post to both

  - thread:
      platform: bsky
      posts:
        - "Thread post 1"
        - "Thread post 2"

  - like:
      platform: bsky
      id: "at://..."

  - annotate:
      platform: bsky
      id: "https://example.com/article"
      text: "Key observation"
      motivation: commenting
      quote: "exact text to anchor to"

  - ignore:
      id: "notif_003"
      reason: "spam"

分发结果和退出码

每次分发后都会写入 dispatch_result-{platform}.yaml。退出码：

代码	含义
0	所有操作均成功
1	发件箱无效（架构错误、缺少凭据）
2	部分失败（部分操作成功，部分失败）

线程失败时会包含 resumeFrom 字段，其中记录索引和剩余帖子，以便你重试剩余部分。

字符数限制

平台	限制
Bluesky	300 个字符
X	280 个字符

CLI 会在调用 API 前拒绝超出限制的帖子。

平台差异

功能	Bluesky	X
注释（at.margin.note）	是	否
搜索	是	是
信息流	是（自定义信息流）	是（主页／用户）
线程	是	是
通知	提及、回复、点赞、关注、转帖、引用	仅提及
引用帖子上下文	是	是

弹性

• 遇到 429、5xx 和网络错误时，采用指数退避重试 3 次。遵循 Retry-After。
• Bluesky 会话会在令牌过期时自动刷新。
• 原子文件写入（临时文件 + 重命名）——避免收件箱／发件箱发生部分损坏。
• 通过 resumeFrom 在部分失败后恢复线程。
• sent_ledger-{platform}.yaml 可防止不同运行之间重复分发。

工作目录布局

所有内容都限定在当前工作目录中，因此你可以运行多个状态彼此隔离的 Agent：

./
├── .env
├── inbox-bsky.yaml          # sync output
├── inbox-x.yaml
├── outbox-bsky.yaml         # your decisions
├── outbox-x.yaml
├── dispatch_result-bsky.yaml  # last dispatch outcome
├── dispatch_result-x.yaml
├── sent_ledger-bsky.yaml      # replay protection
├── sent_ledger-x.yaml
└── feed.yaml                  # optional feed snapshots

参考资料

• references/commands.md：包含所有标志的完整命令列表
• references/outbox-schema.md：完整的发件箱 YAML 架构
• references/agent-loop.md：用于 cron/systemd 自动化循环的模式