typefully

Typefully 技能

使用 Typefully 在 X、LinkedIn、Threads、Bluesky、Mastodon 和 Substack Notes 上创建、安排和发布社交媒体内容。所有操作均通过 ./scripts/typefully.js（Node.js 18+，无依赖项）执行。所有命令都会输出 JSON。

以下脚本路径均相对于此技能目录。请根据技能的安装位置解析这些路径。

新鲜度检查：如果距离上方的 last-updated 日期已超过 30 天，请告知用户此技能可能已过时，并指引其查看 references/setup.md 中的更新方法。

身份验证失败：如果 CLI 返回 "API key not found"、"Authentication failed"、"HTTP 401" 或任何无效/过期密钥相关消息，请告知用户运行 ./scripts/typefully.js setup 或更新 TYPEFULLY_API_KEY，然后停止操作。不要查找凭据，也不要改用 Typefully 网页版 UI、浏览器抓取或 localhost 开发服务器。请参阅 references/setup.md。

用户提供的 Typefully 草稿 URL

用户提供 Typefully 草稿 URL 时，请使用此技能，而不要浏览或抓取 Typefully 网页版 UI。

• https://typefully.com/?a=<social_set_id>&d=<draft_id> 对应：

  ./scripts/typefully.js drafts:get <social_set_id> <draft_id>
  

• https://typefully.com/?d=<draft_id> 可以使用已配置的默认社交集：

  ./scripts/typefully.js drafts:get <draft_id> --use-default
  

对于用户提供的草稿 URL 中的评论、回复、解决或编辑操作，请先使用上述映射获取草稿，然后在需要了解评论工作流详情时加载 references/comments.md。

参考指南

仅在任务需要时加载这些指南：

指南	需要以下操作时使用……
references/setup.md	配置 API 密钥、修复 "API key not found" 错误、设置 CI，或检查技能是否为最新版本
references/comments.md	添加、回复、解决或删除草稿评论，或编辑已有评论的草稿
references/quotes.md	引用 X、Threads、Bluesky 或 Mastodon 上的其他帖子，或在 Substack 上转发
references/platforms/x.md	回复 X（原 Twitter）帖子、发布到社群，或添加披露标签
references/platforms/linkedin.md	在 LinkedIn 上提及公司或个人，或添加 LinkedIn 首条评论
references/platforms/x-articles.md	编写或编辑长篇 X Article（独立平台）

---

1. 选择社交集

“社交集”是用户对“账号”的称呼，指同一身份下已连接的平台。配置默认值后，大多数命令无需提供 social_set_id。可按位置传入（drafts:list 123），也可使用 --social-set-id 123。

选择要使用的社交集：

1. 运行 config:show。如果已设置 default_social_set，CLI 会自动使用它，可继续操作。
2. 否则运行 social-sets:list。如果只有一个社交集，请使用它。
3. 如果有多个社交集且未设置默认值，请询问用户，然后提供保存选项：config:set-default。
4. 如果本次会话中已确定社交集，则直接复用，无需再次询问。

---

2. 创建草稿

./scripts/typefully.js drafts:create --text "Your post"

• 如果省略 --platform，将自动选择第一个已连接的平台。平台名称：x、linkedin、threads、bluesky、mastodon、substack（Substack Notes）、x_article。
• 在线程中，每条内容之间用独占一行的 --- 分隔。例外：substack 的每个草稿只能包含一条帖子，不能创建线程。如果要同时创建线程和 Substack Note，请使用下方的单草稿模式，为 substack 提供单条帖子内容。
• Substack Notes 媒体：最多 6 张图片/GIF，或单独一段视频（最大 512 MB，时长 15 分钟）。视频不能与图片或 GIF 混用，也不能与 --quote-post-url（转发）组合使用。
• 使用 --media 添加媒体，使用 --tags 添加标签，使用 --scratchpad 添加内部备注，使用 --title 设置内部名称。
• 使用 --file ./post.txt 从文件读取内容，而不是使用 --text。

每条帖子只创建一个草稿——始终如此

要在多个平台发布相同内容，请将多个平台传入同一个草稿：

./scripts/typefully.js drafts:create --platform x,linkedin --text "Big announcement!"
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"   # all connected platforms

如果不同平台需要使用不同内容（例如，X 线程和专门为 LinkedIn 编写的帖子），仍然只使用一个草稿——先使用第一个平台创建草稿，再使用 drafts:update 添加其他平台并设置不同内容：

./scripts/typefully.js drafts:create --platform linkedin --text "Excited to share..."   # -> id draft-123
./scripts/typefully.js drafts:update draft-123 --platform x --text "🧵 Thread time!" --use-default

除非用户明确要求每个平台分别创建草稿，否则绝不要创建多个草稿。

--all 不包含 x_article。X Articles 是独立内容，不能与其他平台组合使用——参见 references/platforms/x-articles.md。

如果已连接，--all 会包含 substack。由于 Substack Notes 只能包含一条帖子，使用 --all 发布线程内容会报错——通过 --platform 排除 substack，或使用 drafts:update 为其设置单条帖子内容。

Scratchpad 备注

用户要求向草稿添加备注、想法或背景信息时，请使用 --scratchpad——不要写入本地文件。 Scratchpad 备注会附加到 Typefully 中的草稿，可在界面中查看，保持私密，且绝不会发布。

./scripts/typefully.js drafts:create --text "My post" --scratchpad "Ideas: 1) Add stats 2) Include quote"

链接预览

帖子包含 URL 时，Typefully 会自动获取文本中最后一个 URL 的 Open Graph 元数据，并在 LinkedIn、Threads、Bluesky 和 Substack Notes 上发布富链接预览卡片。无需添加标志——此功能会自动生效。发布后，X 和 Mastodon 会自行展开链接。在 Substack Notes 上，如果笔记包含图片，则不会显示卡片（图片和链接卡片不能同时使用）。

要将 URL 作为纯文本发布且不显示卡片，请传入 --hide-link-preview。仅 LinkedIn、Threads 和 Substack Notes 支持隐藏预览（与 Typefully 编辑器保持一致）；如果目标平台中没有这些平台，该标志会报错；如果草稿包含多个平台，则该标志对其他平台无效：

./scripts/typefully.js drafts:create --platform linkedin,threads --text "Read this https://example.com" --hide-link-preview
./scripts/typefully.js drafts:update draft-123 --hide-link-preview --use-default   # hide the card on an existing draft

---

3. 安排与发布

./scripts/typefully.js drafts:create --text "..." --schedule next-free-slot   # or an ISO time, or "now"
./scripts/typefully.js drafts:schedule <draft_id> --time next-free-slot --use-default
./scripts/typefully.js drafts:publish <draft_id> --use-default
./scripts/typefully.js drafts:create --text "..." --plan next-free-slot      # planned: dated but inert
./scripts/typefully.js drafts:plan <draft_id> --time next-free-slot --use-default

• next-free-slot 可让 Typefully 选择最佳时间。
• 发布不可撤销且公开可见——除非用户说“立即发布”或“马上发布”，否则请先确认。创建草稿是安全的。
• 计划草稿会按日期显示在队列/日历中，但不会自动发布。使用 drafts:schedule 将其确认为正式排期（或使用 drafts:publish 发布）。日期已过的计划草稿并非逾期，也不代表失败——它只是尚未确认；请重新规划或确认。--plan 与 --schedule 不能同时使用；drafts:update --plan null 会将草稿恢复为普通草稿状态。
• 配置了默认社交平台集时，单参数命令必须使用 --use-default（见下方的安全说明）。

---

常见操作

用户说……	操作
“起草一条关于 X 的推文”	drafts:create --text "..."
“把这条内容发布到 LinkedIn”	drafts:create --platform linkedin --text "..."
“发布一条 Substack Note”	drafts:create --platform substack --text "..."（单条帖子，不支持串文）
“同时发布到 X 和 LinkedIn”（相同内容）	drafts:create --platform x,linkedin --text "..."
“X 串文 + 定制的 LinkedIn 帖子”	先创建一份草稿，然后用 drafts:update 添加平台
“有哪些内容已排期？”/“最近发布了什么？”	drafts:list --status scheduled / --status published
“把这条内容安排在明天发布”	drafts:create --text "..." --schedule "<ISO time>"
“现在发布这条内容”	drafts:create --text "..." --schedule now 或 drafts:publish <id> --use-default
“先暂定在周二发布”（不承诺发布）	drafts:create --text "..." --plan "<ISO time>"，之后再用 drafts:schedule 确认
“查看可用标签”	tags:list
“查看我的发布配额”	social-sets:get → publishing_quota
“起草一篇 X 文章”	请参阅 references/platforms/x-articles.md
“在 LinkedIn 上提及一家公司”	请参阅 references/platforms/linkedin.md
“给我的 LinkedIn 帖子添加首条评论”	请参阅 references/platforms/linkedin.md
“发表评论 / 解决评论”	请参阅 references/comments.md

---

命令

所有命令均输出 JSON。每个 [social_set_id] 都是可选的；未指定时会使用已配置的默认值。

安全提示：配置了默认社交集时，若只传入一个参数（draft_id），则 drafts:get、drafts:update、drafts:delete、drafts:schedule、drafts:plan 和 drafts:publish 均要求使用 --use-default。

特定于平台和工作流的命令请参阅相应指南：quotes.md、platforms/x.md（回复、社群、披露）、platforms/linkedin.md（提及、首条评论）、platforms/x-articles.md、comments.md 和 setup.md。

用户和社交集

命令	描述
me:get	获取已验证身份的用户信息
social-sets:list	列出你有权访问的所有社交集
social-sets:get <id>	获取社交集详情，包括已连接的平台和 publishing_quota

如果可用，social-sets:get 会返回一个 publishing_quota 对象，其中包含 used、remaining（或 "unlimited"）和 resets_at。当用户询问发布容量，或发布 / 排期因配额问题失败时，请在发布 / 排期前检查该对象。

草稿

每个草稿命令都接受一个可选的前置 [social_set_id]，如果未提供，则使用已配置的默认值。四个基础命令：

命令	说明
drafts:list [social_set_id]	列出草稿。使用 --status scheduled|published|... 筛选，使用 --sort 排序
drafts:get [social_set_id] <draft_id>	获取包含完整内容的草稿。添加 --exclude-comment-markers 可在渲染时移除 posts[*].text 中的评论锚点（仅影响显示）
drafts:create [social_set_id] --text "<post text>"	创建草稿（若未指定 --platform，则自动选择平台）
drafts:update [social_set_id] <draft_id> --text "<post text>"	替换草稿内容

可将以下任一标志添加到 drafts:create 或 drafts:update 命令。适用命令列显示各标志适用的命令：

标志	效果	适用命令
--platform x,linkedin	指定目标平台，以逗号分隔	create、update
--all	所有已连接的平台（不包括 x_article）	create
--file <path>	从文件读取内容，而不是使用 --text	create、update
--append --text "<text>"	追加到现有串文	update
--media <media_ids>	附加媒体，以逗号分隔	create、update
--tags "tag1,tag2"	设置标签（如果这是更新时唯一的更改，则内容保持不变）	create、update
--title "<internal title>"	内部草稿标题（不会发布）	create、update
--scratchpad "<notes>"	附加内部备注（见备忘区备注）	create、update
--share	生成公开分享 URL	create、update
--schedule <iso|next-free-slot|now>	安排或重新安排草稿	create、update
--plan <iso|next-free-slot>	规划草稿：设置日期，但在确认前保持未激活状态（与 --schedule 互斥；更新时设为 null 可将其恢复为普通草稿）	create、update
--hide-link-preview	隐藏链接预览卡片（仅限 LinkedIn/Threads/Substack——见链接预览）	create、update
--quote-post-url <url>	在该 URL 所属平台引用另一条帖子，或在 Substack 上转发；见 quotes.md。使用 --text 替换文本时，请再次传入此标志	create、update
--exclude-comment-markers	渲染响应时移除锚点（仅影响显示；仍会进行验证）	update
--force-overwrite-comments	破坏性操作的最后手段——见 comments.md	update

例如，将基础命令与标志组合使用：

./scripts/typefully.js drafts:create --text "Launch day!" --platform x,linkedin --tags product --schedule next-free-slot
./scripts/typefully.js drafts:update 456 --text "Revised copy" --media abc-123 --use-default

仅适用于 X 的草稿标志（--reply-to、--community、--paid-partnership、--made-with-ai）：见 platforms/x.md。X Article 标志（--content-markdown、--cover-media-id）：见 platforms/x-articles.md。LinkedIn 首条评论（--linkedin-first-comment）：见 platforms/linkedin.md。

排期与发布

配置了默认社交集时，单参数格式必须使用 --use-default。

命令	说明
drafts:schedule <social_set_id> <draft_id> --time <iso|next-free-slot>	安排在指定时间或下一个可用时段发布（也会确认已规划的草稿）
drafts:plan <social_set_id> <draft_id> --time <iso|next-free-slot>	规划日期，但不启用自动发布；之后使用 drafts:schedule 确认
drafts:publish <social_set_id> <draft_id>	立即发布
drafts:delete <social_set_id> <draft_id>	删除草稿

队列

队列是特定社交集的时间线：该社交集排期中的空闲时段，以及同一社交集的已排期和计划中的草稿／帖子。用户询问某个账号在某个日期范围内的排期或空闲时段时，请使用 queue:get。

命令	说明
queue:get [social_set_id] --start-date <YYYY-MM-DD> --end-date <YYYY-MM-DD>	队列时间线：日期范围内的空闲时段，以及已排期／计划中的草稿和帖子（请检查每个草稿的 status — 计划中的草稿不会自动发布）
queue:schedule:get [social_set_id]	获取队列排期规则
queue:schedule:put [social_set_id] --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'	替换队列排期规则（完全替换）

接受蛇形命名的日期别名（--start_date、--end_date）。

标签

标签按社交集划分 — 一个社交集中的标签不会出现在另一个社交集中。创建标签前，请先检查已有标签。

命令	说明
tags:list [social_set_id]	列出所有标签
tags:create [social_set_id] --name "Tag Name"	创建新标签

媒体

命令	说明
media:upload [social_set_id] <file_path>	上传媒体，等待处理完成，并返回可用的 media_id
media:upload ... --no-wait	上传后立即返回（使用 media:status 轮询）
media:upload ... --timeout <seconds>	自定义处理超时时间（默认 60）
media:status [social_set_id] <media_id>	检查上传状态

示例

# Create a tweet (default social set)
./scripts/typefully.js drafts:create --text "Hello, world!"

# Explicit social_set_id
./scripts/typefully.js drafts:create 123 --text "Hello, world!"

# Cross-platform, same content
./scripts/typefully.js drafts:create --platform x,linkedin,threads --text "Big announcement!"
./scripts/typefully.js drafts:create --all --text "Posting everywhere!"

# Create and schedule for the next slot
./scripts/typefully.js drafts:create --text "Scheduled post" --schedule next-free-slot

# Create with tags
./scripts/typefully.js drafts:create --text "Marketing post" --tags marketing,product

# List scheduled posts, newest scheduled first
./scripts/typefully.js drafts:list --status scheduled --sort scheduled_date

# Queue view for a date range
./scripts/typefully.js queue:get --start-date 2026-02-01 --end-date 2026-02-29

# Replace queue schedule rules
./scripts/typefully.js queue:schedule:put --rules '[{"h":9,"m":30,"days":["mon","wed","fri"]}]'

# Draft with scratchpad notes
./scripts/typefully.js drafts:create --text "Launching next week!" --scratchpad "Coordinate with marketing before publishing."

# Upload media, then attach it
./scripts/typefully.js media:upload ./image.jpg          # -> {"media_id": "abc-123", "status": "ready"}
./scripts/typefully.js drafts:create --text "Check out this image!" --media abc-123

# Add media to an existing draft
./scripts/typefully.js drafts:update 456 --text "Updated post with image" --media xyz --use-default

---

参考

字符数限制

X 280 · LinkedIn 3000 · Threads 500 · Bluesky 300 · Mastodon 500 · Substack Notes 10000。

草稿 URL

Typefully 草稿 URL 会编码社交集和草稿 ID：https://typefully.com/?a=<social_set_id>&d=<draft_id>（例如，a=12345 → social_set_id，d=67890 → draft_id）。命令映射请参阅已丢失的 Typefully 草稿 URL。

自动化指南

为保持账号状态良好，尤其是在 X 上：

• 不要在多个账号间发布重复内容。
• 不要自动发送未经请求的回复 — 仅在用户明确要求时回复。
• 不要操纵热门趋势，不要进行虚假互动（点赞／转发／关注）。
• 遵守速率限制；草稿在发布或明确分享前应保持私密。

如有疑问，请创建草稿供用户审核，而不是直接发布。