# Social-CLI：统一 AI 社交发布的命令行工具

> Letta 推出的开源 CLI 工具，让 AI 代理能够通过统一接口连接 Bluesky、X/Twitter 等社交平台，支持 YAML 配置、自动化通知处理、多平台发布和知识网络集成。

- 板块: [Openclaw Geo](https://www.zingnex.cn/forum/board/openclaw-geo)
- 发布时间: 2026-05-30T17:41:01.000Z
- 最近活动: 2026-05-30T17:50:22.722Z
- 热度: 116.8
- 关键词: AI 代理, 社交网络, Bluesky, Twitter, CLI 工具, 自动化, YAML, 开源, Letta
- 页面链接: https://www.zingnex.cn/forum/thread/social-cli-ai
- Canonical: https://www.zingnex.cn/forum/thread/social-cli-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：letta-ai
- 来源平台：github
- 原始标题：social-cli
- 原始链接：https://github.com/letta-ai/social-cli
- 来源发布时间/更新时间：2026-05-30T17:41:01Z

## 原作者与来源\n\n- **原作者/维护者**: Letta AI\n- **来源平台**: GitHub\n- **原始标题**: social-cli\n- **原始链接**: https://github.com/letta-ai/social-cli\n- **发布时间**: 2026-05-30\n\n---\n\n## 项目概述\n\nSocial-CLI 是一个统一的开源命令行工具，专门设计用于将 AI 代理连接到社交网络。它支持 Bluesky、X（Twitter）、Semble 等多个平台，提供 YAML 配置的输入输出接口，让 AI 能够以结构化的方式在社交网络上发布内容、回复互动、搜索信息和处理通知。该工具是 Letta Code Desktop 的捆绑技能，也可独立使用。\n\n---\n\n## 核心功能与设计哲学\n\nSocial-CLI 的设计理念是 **YAML 进，YAML 出**。所有操作都通过 YAML 文件进行配置和状态管理，这使得 AI 代理可以轻松地读取和写入社交互动状态。工具提供两种主要工作模式：\n\n**代理循环模式**：用于自动化通知处理，AI 可以持续监控社交平台上的提及、回复和互动，决定如何响应，并将决策写入输出队列等待执行。\n\n**快速命令模式**：用于直接操作，如发布帖子、回复、点赞、关注等，不经过通知管道。\n\n这种分离设计让开发者可以根据场景选择合适的工作方式——自动化处理或即时操作。\n\n---\n\n## 支持的平台与功能\n\n### Bluesky / AT Protocol\n\nBluesky 是工具支持最完整的平台，包括：\n- 发布帖子和回复\n- 创建线程（多帖串联）\n- 点赞、关注、屏蔽用户\n- 搜索帖子和用户\n- 读取时间线和自定义信息流\n- 媒体附件支持\n\n### X / Twitter\n\nX 平台支持类似的核心功能：\n- 发布和回复\n- 线程创建\n- 点赞、关注、屏蔽\n- 搜索功能\n- 媒体附件\n\n注意 X 集成使用 OAuth 1.0a 用户认证，而非 OAuth 2.0。\n\n### Semble\n\nSemble 是一个基于 AT Protocol 的社交知识网络，Social-CLI 支持与其集成，允许 AI 代理参与知识网络的构建和互动。\n\n### 其他集成\n\n- **Margin 注释**：支持在网页上添加边注和高亮\n- **GreenGale 博客发布**：通过 Bluesky 凭证发布长文\n- **Leaflet 发布**：需要配置发布 URI\n\n---\n\n## 配置与设置\n\n### 安装\n\n```bash\ngit clone https://github.com/letta-ai/social-cli.git\ncd social-cli\npnpm install\npnpm build\n```\n\n### 配置文件\n\n创建 `config.yaml` 文件定义账户：\n\n```yaml\naccounts:\n  bsky:\n    handle: you.bsky.social\n    credentials: .env\n  x:\n    handle: you\n    credentials: .env\n```\n\n### 凭证文件\n\n创建 `.env` 文件存储平台凭证：\n\n```bash\n# Bluesky / ATProto\nATPROTO_HANDLE=you.bsky.social\nATPROTO_APP_PASSWORD=xxxx-xxxx-xxxx-xxxx\nATPROTO_PDS=https://bsky.social\n\n# X / Twitter (OAuth 1.0a)\nX_API_KEY=...\nX_API_SECRET=...\nX_ACCESS_TOKEN=...\nX_ACCESS_TOKEN_SECRET=...\n```\n\n---\n\n## 状态管理与文件组织\n\nSocial-CLI 将运行时状态写入 gitignored 的状态目录，而非仓库根目录。默认位置：\n\n- Letta 代理：`social-cli/state/agents/<AGENT_ID>/`\n- 其他用户：`social-cli/state/`\n\n可通过环境变量或配置文件覆盖：\n\n```bash\nSOCIAL_CLI_STATE_DIR=/path/to/state\n```\n\n生成的文件包括：\n- `inbox-{platform}.yaml`：从平台拉取的通知\n- `outbox-{platform}.yaml`：待执行的决策\n- `processed-{platform}.yaml`：已处理的通知\n- `sent_ledger-{platform}.yaml`：发送记录\n\n使用 `social-cli doctor` 查看活动状态目录并检测旧文件，使用 `social-cli doctor --migrate` 迁移遗留文件。\n\n---\n\n## 代理工作流\n\n典型的代理自动化流程如下：\n\n```bash\nsocial-cli doctor          # 检查状态目录\nsocial-cli sync -p bsky -p x  # 拉取通知到 inbox\nsocial-cli check || exit 0 # 检查是否有可执行的操作\n# 代理读取 inbox，决策，写入 outbox\nsocial-cli dispatch        # 执行决策并标记为已处理\n```\n\n代理读取 `inbox-{platform}.yaml`，决定如何响应，将决策写入 `outbox-{platform}.yaml`，然后 `dispatch` 执行并处理记账工作（标记已处理、去重、归档）。\n\n---\n\n## 快速命令示例\n\n### 发布内容\n\n```bash\nsocial-cli post "Hello world" -p bsky\nsocial-cli post "Hello world" -p x\n```\n\n### 创建线程\n\n```bash\nsocial-cli thread \"Post 1\" \"Post 2\" \"Post 3\" -p bsky\nsocial-cli thread \"Post 1\" \"Post 2\" -p bsky -m header.png\n```\n\n### 互动操作\n\n```bash\nsocial-cli reply \"Thanks\" --id <post-id> -p bsky\nsocial-cli like <post-id> -p bsky\nsocial-cli follow alice.bsky.social -p bsky\nsocial-cli block spammer.bsky.social -p bsky\nsocial-cli delete <post-id> -p bsky\n```\n\n### 读取信息\n\n```bash\nsocial-cli search \"query\" -p bsky -n 10\nsocial-cli feed -p bsky -n 20\nsocial-cli posts alice.bsky.social -n 10\nsocial-cli profile alice.bsky.social\nsocial-cli whoami\nsocial-cli rate-limits\n```\n\n所有读取命令默认输出 YAML 到 stdout（feed 命令默认写入文件）。\n\n---\n\n## Outbox 决策格式\n\n代理写入 `outbox-{platform}.yaml` 的决策示例：\n\n```yaml\ndispatch:\n  - reply:\n      platform: bsky\n      id: \"at://did:plc:xxx/app.bsky.feed.post/abc\"\n      text: \"Thanks for the mention\"\n\n  - post:\n      text: \"Hello from social-cli\"\n      platforms: [bsky, x]\n\n  - thread:\n      platform: bsky\n      posts:\n        - \"Thread post 1\"\n        - \"Thread post 2\"\n\n  - like:\n      platform: bsky\n      id: \"at://did:plc:xxx/app.bsky.feed.post/abc\"\n\n  - ignore:\n      id: \"notif_003\"\n      reason: \"spam\"\n\n  - annotate:\n      platform: bsky\n      id: \"https://example.com/article\"\n      text: \"Key observation\"\n      motivation: commenting\n      quote: \"exact text to anchor to\"\n```\n\n---\n\n## 钩子机制\n\nSocial-CLI 支持在 dispatch 操作前后运行钩子脚本，在 `config.yaml` 中配置：\n\n```yaml\nhooks:\n  preDispatch:\n    - event: reply\n      command: \"bash hooks/validate-reply.sh\"\n\n  postDispatch:\n    - event: \"*\"\n      command: \"bash hooks/log-dispatch.sh\"\n\n  onError:\n    - event: \"*\"\n      command: \"bash hooks/log-error.sh\"\n```\n\n钩子通过环境变量接收上下文信息，包括事件类型、平台、动作 ID、目标 ID、文本内容等。\n\n---\n\n## 应用场景与价值\n\nSocial-CLI 为 AI 代理的社交集成提供了标准化解决方案：\n\n1. **自动化社交管理**：AI 可以持续监控社交平台，自动回复提及、过滤垃圾信息、维护社交关系\n\n2. **跨平台发布**：一次配置，多平台同步发布，适合内容创作者和营销自动化\n\n3. **知识网络参与**：通过 Semble 集成，AI 可以参与去中心化知识网络的构建\n\n4. **研究与应用**：为学术研究中的社交机器人、自动化内容分析提供工具基础\n\n5. **代理能力扩展**：作为 Letta 代理的技能，扩展 AI 的社交互动能力\n\n---\n\n## 技术特点\n\n- **纯 YAML 接口**：易于解析和生成，适合 AI 代理处理\n- **状态分离**：运行时状态与代码分离，支持多代理共享代码库\n- **平台抽象**：统一接口封装不同平台的 API 差异\n- **钩子扩展**：支持自定义验证和日志记录\n- **字符限制处理**：自动处理 Bluesky（300字符）和 X（280字符）的限制\n- **媒体支持**：支持图片附件和线程创建