AutoGPT Platform 集成指南：使用 Ayrshare 发布 LinkedIn 帖子（PostToLinkedIn Block 全参数解析与源码原理）

导读

本文围绕 AutoGPT Platform（AutoGPT 构建平台）中基于 Ayrshare 社交管理 API 实现的 Post To LinkedIn 模块展开，讲解如何让 Agent 把内容（纯文本、图片、视频、PPT/PDF 文档）一键发布到 LinkedIn，并支持定时、限流互动开关、内容可见性控制以及面向不同国家、职位、学历、行业、职能、公司规模的受众定向投放。读完本文你将掌握该模块的全部输入输出参数含义、默认值与边界限制，理解其后端源码（post_to_linkedin.py）的校验逻辑与 Ayrshare API 调用链，并能在可视化 Builder 中搭建一个"生产内容 → 自动发 LinkedIn"的完整 Agent 工作流。

关联文档：docs/integrations/block-integrations/ayrshare/post_to_linkedin.md，同类发布模块还覆盖 Bluesky、Facebook、X、Instagram、YouTube 等平台（见 ayrshare 文档目录）。

---

一、模块定位与适用场景

Post To LinkedIn 是 Ayrshare 系列 Block 中的一员，负责调用 Ayrshare 聚合发帖 API 把内容发布到 LinkedIn。AutoGPT 在模块实现中把它标记为社交类（BlockCategory.SOCIAL）且专属 Ayrshare 类型（BlockType.AYRSHARE），Block ID 为 589af4e4-507f-42fd-b9ac-a67ecef25811（见 blocks/ayrshare/init.py 中的登记列表）。

它的典型价值场景包括：

• 企业品牌内容分发：把 LLM 生成的行业观点、产品动态通过 Agent 自动同步到公司主页；
• 内容定时矩阵：结合 schedule_date 将一批帖子编排为可预期的定时发布节奏；
• 图文/视频/文档原生发布：一条 post 支持最多 9 个媒体附件（图片、视频或 PPT/PPTX/DOC/DOCX/PDF 文档），充分发挥 LinkedIn 原生帖子对 PDF/PPT 内嵌支持的传播优势；
• 精准人群触达：借助 8 个 targeting_* 定向维度把帖子只推送给目标国家、行业、职位层级等受众。

同目录下还存在 X、Facebook、YouTube、Instagram 等其他平台模块，因此该 Block 也天然适合与它们组合，实现"一次编排、多平台分发"的矩阵式运营。

---

二、使用前提：API Key 与托管凭证

在动手之前需要理解 Ayrshare 在该平台内的凭证模型，这与常规的"填一个 API Key"不同。

模块依赖后端配置的全局密钥 AYRSHARE_API_KEY（读取自 settings.secrets.ayrshare_api_key）。AyrshareClient 在初始化时会检查该密钥，若未配置则抛出 MissingConfigError，此时 Block 会退化为输出错误 Ayrshare integration is not configured. Please set up the AYRSHARE_API_KEY.。

同时，blocks/ayrshare/_config.py 的文档字符串明确指出其凭证模型经过特别设计：

• Block 暴露给 Agent 的 credentials 是每个用户独立的 Ayrshare profile key，而不是组织级的 AYRSHARE_API_KEY；
• 该 profile key 由 managed_providers/ayrshare.py 中的 AyrshareManagedProvider 自动为每个用户颁发，并以 is_managed=True 存入普通凭证列表，用户无需手工创建；
• _config.py 使用 .with_managed_api_key() 注册凭据类型，刻意避免生成基于环境变量的默认凭据——因为组织级 AYRSHARE_API_KEY 是管理员密钥，绝不能作为"用户 profile key"流入 Block。

落地到操作上就是：管理员（自托管场景）配置好全局 AYRSHARE_API_KEY，普通用户在 Builder 中通过 Ayrshare SSO 弹窗完成 LinkedIn 账号授权关联，此后运行 Block 时会自动携带该用户的 profile key（profile_key=credentials.api_key.get_secret_value()）。相关单测见 managed_providers/ayrshare_test.py。

提示：因为发帖走的是"用户自己的 Ayrshare 档案"，LinkedIn 账号的身份归属、粉丝量（影响定向功能）等均取决于该用户在 Ayrshare 侧绑定的账号。

---

三、输入参数全解析（含默认值与高级项）

该模块的输入 Schema 由两部分组成：所有 Ayrshare 平台共享的基础字段 BaseAyrshareInput（定义于 blocks/ayrshare/_util.py），以及 LinkedIn 专属扩展字段。下文将原文档参数表完整继承，并补充源码中的默认值、是否高级项（advanced）与平台约束，便于在 Builder 表单中快速定位。

3.1 基础输入字段（所有 Ayrshare 平台通用）

输入	类型	默认值	Required	说明
credentials	CredentialsMetaInput	—	是	Ayrshare 用户档案凭据，托管自动签发，SSO 弹窗授权账号
post	str	""	否	帖子正文，上限 3000 字符，支持 # 话题标签
media_urls	List[str]	[]	否	媒体 URL 列表；LinkedIn 最多 9 张图片/视频/文档，视频需配合 is_video=True
is_video	bool	False	否	媒体是否为视频；上传视频时应置 True，使计费走视频档
schedule_date	str (date-time)	None	否	UTC 定时发布时间，格式 YYYY-MM-DDThh:mm:ssZ
disable_comments	bool	False	否	是否关闭评论功能
shorten_links	bool	False	否	是否缩短正文中的链接
unsplash	str	None	否	Unsplash 配图配置（Ayrshare 自动配图能力）
requires_approval	bool	False	否	是否开启审批工作流（草稿待人工审核后再发）
random_post	bool	False	否	是否生成随机文案
random_media_url	bool	False	否	是否随机挑选媒体
notes	str	None	否	帖子的附加备注（运营侧信息）

3.2 LinkedIn 专属输入字段（源码中均标记 advanced=True）

输入	类型	默认值	说明
visibility	str	"public"	可见性：public（公开，默认）、connections（仅好友，个人主页）、loggedin（登录用户可见）
alt_text	List[str]	[]	每张图片的替代文本（无障碍特性），不支持视频与文档
titles	List[str]	[]	每个图片/视频的标题或说明文字
document_title	str	""	文档帖的标题（上限 400 字符，不填则用文件名）
thumbnail	str	""	视频封面 URL（PNG/JPG，需与视频同尺寸，小于 10MB）
targeting_countries	List[str]	None	目标国家码，如 ['US', 'IN', 'DE', 'GB']
targeting_seniorities	List[str]	None	目标职级，如 ['Senior', 'VP']
targeting_degrees	List[str]	None	目标学历
targeting_fields_of_study	List[str]	None	目标专业领域
targeting_industries	List[str]	None	目标行业分类
targeting_job_functions	List[str]	None	目标职能分类
targeting_staff_count_ranges	List[str]	None	目标公司规模区间

重要限制：上表中所有 targeting_* 定向字段（以及最终对应的 audience targeting）要求目标受众至少拥有 300 名以上粉丝才可用——这是 LinkedIn 平台侧规则，粉丝不足时会发布失败。

原文档将其整理为"展平"字段而非嵌套对象：源码注释说明这些字段是由 LinkedInTargeting 嵌套模型展开（flattened）而来（对照模型见 _util.py 中 LinkedInTargeting），这样在可视化表单中可以直接逐项填写，无需手工构造 JSON。

---

四、输出说明

输出	类型	说明
error	str	操作失败时的错误信息
post_result	PostResponse	一次发帖请求的完整结果对象
post	PostIds	单平台发帖结果（可能输出多条）

后端数据模型定义于 integrations/ayrshare.py：

• PostResponse 包含 status、id、refId、profileTitle、post、可选的 postIds 列表、scheduleDate（定时场景）以及 errors；
• PostIds 则携带每条平台记录的 status、id、postUrl（发布后的帖子链接）与 platform 字段。

值得注意的运行时行为：源码中会先产出一次 post_result（整包响应），随后若 response.postIds 非空则逐个 postIds 再产出 post。也就是说，后续接一个"记录发布链接"的节点时，可用 post 输出拿到可直接跳转的 postUrl。

---

五、源码级运行逻辑：从输入到 Ayrshare API

理解了参数之后，我们看 run() 方法 的实际执行路径，这能帮你准确预测"什么输入会被拒绝、什么会被如何翻译成 API 字段"。

5.1 请求前的本地校验（返回错误而非发无效请求）

Block 在调用 API 之前会做以下硬性校验，任何一项不满足都会直接 yield "error", ... 并终止：

1. 正文长度：超过 3000 字符报 LinkedIn post text exceeds 3,000 character limit；
2. 媒体数量：media_urls 超过 9 项报 LinkedIn supports a maximum of 9 images/videos/documents；
3. 文档标题长度：document_title 超过 400 字符报错；
4. 可见性枚举：visibility 必须属于 ["public", "connections", "loggedin"]，否则给出合法值列表；
5. 文档类型探测：遍历 media_urls 判断 URL 是否以 .ppt/.pptx/.doc/.docx/.pdf 结尾（大小写不敏感），用于决定 alt_text 是否被允许传入；
6. 定时时间格式：将传入的 schedule_date（datetime）转换为 ISO 字符串 iso_date，无值则为 None。

5.2 LinkedIn 专属参数到 API 字段的映射

源码先把"非默认"的 LinkedIn 专属参数组装为 linkedin_options 字典，映射关系如下：

Block 输入字段	linkedin_options 键	触发条件
visibility	visibility	仅当不等于 public 时传入
alt_text	altText	仅当非空且未包含文档附件时传入
titles	titles	非空即传入
document_title	title	仅当非空且检测到文档附件时传入
thumbnail	thumbNail	非空即传入
targeting_* 系列	targeting.{countries / seniorities / degrees / fieldsOfStudy / industries / jobFunctions / staffCountRanges}	各字段非空时分别加入

值得留意的两组"语义不对称"：

• visibility 只有非默认值才会透传，避免把默认 public 重复发给 API；
• document_title 只有在附件是文档时才生效，alt_text 则恰恰相反——检测到文档时会放弃传入 altText（因为 LinkedIn 不支持文档/视频的替代文本）。

随后统一调用 AyrshareClient 的 create_post(...)（签名见 integrations/ayrshare.py），传参要点为：

await client.create_post(
    post=input_data.post,
    platforms=[SocialPlatform.LINKEDIN],          # platform = "linkedin"
    media_urls=input_data.media_urls,
    is_video=input_data.is_video,
    schedule_date=iso_date,                        # ISO 格式的 UTC 时间
    disable_comments=..., shorten_links=...,
    unsplash=..., requires_approval=...,
    random_post=..., random_media_url=..., notes=...,
    linkedin_options=linkedin_options or None,     # 平台专属选项
    profile_key=credentials.api_key.get_secret_value(),  # 用户 profile key
)

5.3 底层 HTTP 链路

AyrshareClient 的底层实现（integrations/ayrshare.py）公开了三条核心端点：

POST_ENDPOINT    = https://api.ayrshare.com/api/post
PROFILES_ENDPOINT = https://api.ayrshare.com/api/profiles
JWT_ENDPOINT     = https://api.ayrshare.com/api/profiles/generateJWT

• 发帖请求打到 /api/post，请求头携带 Authorization: Bearer <AYRSHARE_API_KEY>（管理密钥层）；
• 配置项 raise_for_status=False，所有方法自行检查响应与 status 信封，并以 Ayrshare 返回的可读错误信息抛出 AyrshareAPIException，这样错误流能原样反馈到 Block 的 error 输出中，便于排障；
• SocialPlatform.LINKEDIN = "linkedin"，payload 中的 platforms 会被序列化为该枚举字符串。

另外，blocks/ayrshare/post_to_linkedin.py 顶部使用了 @cost(*AYRSHARE_POST_COSTS) 装饰器（成本表位于同目录 _cost.py），发帖会按 Ayrshare 计费档位记账，其中 is_video=True 决定走视频计费档——这也是上一节提示视频必须正确置位的原因之一。

---

六、在 Builder 中搭建"发布 LinkedIn"Agent 工作流

假设目标是"每天生成一条行业观点并发布到公司主页"。可以按以下方式搭建 Agent 图：

1. 内容节点：用 LLM / 定时触发块生成帖子正文，注意把产出约束在 3000 字符内（否则本模块会返回长度错误）；
2. Post To LinkedIn 节点：把正文连到 post；有配图/PDF 时把外链 URL 填入 media_urls（视频请把高级项 is_video 置 True，并建议同时提供 thumbnail 封面）；
3. 可选增强：
   • 需要定时发布 → 填 schedule_date（UTC，YYYY-MM-DDThh:mm:ssZ）；
   • 需要可控性 → 开启 requires_approval 走审批工作流；
   • 需要精准触达 → 填 targeting_countries 等定向字段（注意 300+ 粉丝门槛）；
   • 需要无障碍合规 → 为每张图片在 alt_text 按顺序提供替代文本；
4. 下游节点：从 post（PostIds.postUrl）或 post_result 取回执，记录到日志/存储；对 error 输出接一个失败通知分支，保证出错可观测。

完成后可先将 visibility 设为 connections 或开启 requires_approval 做一次小范围试发，确认正文、媒体、定向均正常后再放开为 public 全量分发。

---

七、边界与注意事项小结

• 字符与数量上限：正文 ≤ 3000、媒体 ≤ 9、文档标题 ≤ 400，均在后端硬校验；
• 媒体类型差异：alt_text 不支持视频与文档；document_title 仅在含文档时生效；视频记得开 is_video 并给封面；
• 可见性取值受限：只有 public / connections / loggedin 三选一，非法值会在本地报错；
• 定向投放门槛：受众定向需要 LinkedIn 侧目标受众 ≥ 300 粉丝，粉丝不足建议先做内容矩阵再做精准投放；
• 凭证链路：确保后端已配置 AYRSHARE_API_KEY，并让目标账号在 Builder 的 Ayrshare SSO 弹窗中完成授权——这是最容易遗漏的一步。

如需了解同仓库其他平台的异同（例如各自专属 options），可对照 Ayrshare 各平台发布模块源码 与其对应的文档，如 post_to_x.md、post_to_facebook.md。