想风技术文档🛠一句「帮我把文章发布到推特」，把 Markdown 变成 X 长文（Mac / Windows 小白全教程）
你是不是也这样：想在 X（推特）上发一篇像样的长文，但遇到一些问题 ! 起初我在notion 写好，复制到推特，可图片无法同步，要一张一张把图片插入进去，想找个chrome插件要么收费，要么同步有些问题！尝试直接在 X 编辑器写，偶尔写一半，无法保存，刷新未能保存最新内容，晕死！ 后来用了 obsidian, 开始尝试将markdown 文件直接同步为 X 推特草稿，用过几个skill 还是不完美，不完美兼容图片，代码块，表格！
我以前就是这样。所以我其他开源项目的基础上整合了一个开源的 Skill 来解决它 xaiwind/x-article-publisher
装好之后，你什么都不用记。只要把文章写在一个 Markdown 文件里，然后对你的 AI 助手说一句：
它就会自动把标题、正文、表格、代码块、图片，整整齐齐地填进 X 的「长文」（Articles）草稿箱。
最关键的承诺：它只帮你填草稿，绝不自动发布。最后那一下 Publish，永远由你自己点。
你现在读的这篇教程，本身就是一份 Markdown 文件——下面出现的标题、表格、代码块，都会原样出现在你的 X 长文里。
一、它到底是个啥？跟普通工具有什么不一样
它不是 App，也不是一个要你天天开着的软件，而是一个 Skill（技能包）。你可以把它理解成：一段说明书 + 一段程序，打包好之后装进你的 AI 助手（Claude Code、Codex、DeepSeek 这类会帮你干活的 AI）里。
装完之后，事情就变得特别简单：
- 你：说一句「帮我把文章发布到推特」
- AI：自己读说明书、找到文章、打开浏览器、把内容填进草稿箱
- 你：拿到一个草稿链接，检查一眼，点 Publish
全程你不需要背命令、不需要懂代码，就像多了个帮你排版的助手。
它背后是怎么干的：
二、装之前，准备四样东西
需要什么 | 去哪里弄 | 要不要钱 |
Node.js 18 或更高 | nodejs.org 下载 LTS 版 | 免费 |
Google Chrome | 官网安装的「系统版」Chrome（Edge、Chromium 不行） | 免费 |
X Premium 账号 | X 会员（长文 Articles 是会员功能） | 需要会员 |
一个支持 Skill 的 AI 助手 | Claude Code、Codex、DeepSeek 等 | 看你用的工具 |
另外，装的时候会用到「终端」：
- Mac 上叫「终端」（Terminal）
- Windows 上叫「命令提示符」或「PowerShell」
装好之后，日常使用就完全不用碰终端了，用说的就行。
三、先搞懂：装到哪个 AI 助手？（三个都支持）
现在这个 Skill 支持装进 三类 AI 助手，装的位置不一样。你挑一个（也可以都装）：
AI 助手 | Mac 上的目录 | Windows 上的目录 |
Claude Code | ~/.claude/skills/ | C:\Users<你的用户名>.claude\skills\ |
Codex / DeepSeek Harness | ~/.agents/skills/ | C:\Users<你的用户名>.agents\skills\ |
下面的安装步骤里，每个助手都写了一份命令。区别只有「目录名」：Claude Code 是 .claude；Codex 和 DeepSeek Harness 共用 .agents，其余一模一样。
四、Mac 怎么装（三步）
第一步：装 Node.js
去 nodejs.org 下载 LTS 版本，双击安装包，一路「继续」到底。
第二步：把 Skill 装进 skills 目录
打开「终端」，粘贴对应助手的命令（一行一行回车）：
Claude Code：
Codex / DeepSeek Harness：
没装 Git 也没关系：去 GitHub 页面点绿色 Code → Download ZIP，解压后把整个文件夹改名叫 x-article-publisher，放进上面那个目录即可。
第三步：装依赖
等它跑完，就装好了。装好之后，AI 助手会自动认出这个新 Skill（可能需要重启一下你的 AI 助手）。
五、Windows 怎么装（三步）
- 去 nodejs.org 下载 LTS 安装包，一路 Next 装好 Node.js
- 去 git-scm.com 装好 Git；或者到 GitHub 页面点 Code → Download ZIP 解压
- 打开「命令提示符」或 PowerShell，粘贴对应助手的命令并回车：
Claude Code：
Codex / DeepSeek Harness：
装好的位置在：
C:\Users\<你的用户名>\.claude\skills\x-article-publisher（Claude Code）或 C:\Users\<你的用户名>\.agents\skills\x-article-publisher（Codex / DeepSeek Harness）。六、怎么用（重点：不敲命令，用说的）
第一次用：先登录一次
对你的 AI 助手说：
（或者更简单：直接说「帮我把文章发布到推特」，AI 第一次会弹出一个浏览器窗口，你在里面登录 X 就行。）
登录一次之后，登录状态会存在本地，以后就不用再登了。
日常使用：一句话搞定
把你的 .md 文件路径贴给 AI，说：
小技巧：
- Mac 上，把 .md 文件直接拖进对话框，路径会自动填好
- Windows 上，按住 Shift 右键文件，选「复制文件地址」
AI 会在后台默默跑完，然后给你一个「草稿链接」。复制到浏览器打开，检查内容，没问题就自己点 Publish，发布完成！🎉
几个常用说法，AI 都听得懂：发布到 X、发布文章到推特、把 Markdown 导入 X 长文。
七、它支持哪些 Markdown？（详细映射）
你的 Markdown | 会变成 X 长文里的 |
frontmatter 里的 title，或正文唯一的 H1 | 文章标题 |
frontmatter 里的 cover，或正文第一张图 | 封面 |
、Obsidian 的 ![[图片名.png]] | 图片（大于 150KB 自动压缩） |
代码块 | 原生代码框，带语法高亮和语言标签 |
Markdown 表格 | 原生表格，对齐保留 |
独占一行的推文链接 | 内嵌的引用推文卡片 |
加粗 / 斜体 / 链接 / 列表 / 引用 | 对应原生格式 |
H2 / H3 | 章节标题 |
几个细节说明：
- 标题判定：正文里的 H1，只有当「全文只有这一个 H1」且「它前面只有图片」时，才会被当成文章标题。用 # 一、# 二、 这种当章节标题的文章，会自动回退用文件名当标题，并保留所有 H1。如果markdown文件有title 属性，则为标题。
- Obsidian 附件：![[图片.png]] 在 md 同目录找不到时，会去 vault 根目录按文件名找，|尺寸 后缀自动去掉。如果markdown文件有cover属性则为封面图。
- 降级保护：万一代码块 / 表格 / 推文没插进去，会退回成原始文字（围栏代码 / markdown 表格 / 裸链接），内容不会丢。
八、进阶参数（写给想看细节的人）
参数 | 作用 |
--headless | 无头静默运行，不弹窗口（日常默认用它） |
--profile=<目录> | 自定义登录态目录，默认 ~/.hermes-x-profile |
--timeout=<毫秒> | 登录 / 编辑器等待超时，默认 180000（3 分钟） |
X_CODE_IMAGE=1 | 环境变量；把代码块渲染成深色 PNG 卡片，而不是原生代码框 |
带 --headless 时，跑完就自动退出；不带时浏览器会一直开着，直到你关掉窗口。
九、Windows / macOS / Linux 平台差异
核心功能（打开发布、注入内容、存草稿）三个平台完全一样，只有两个小功能有差异：
能力 | macOS | Windows | Linux |
发布主流程 | ✅ | ✅ | ✅ |
登录态持久化 | ✅ | ✅ | ✅ |
图片自动压缩（sips） | ✅ | ⚠️ 跳过 | ⚠️ 跳过 |
自动关闭占用中的浏览器（pgrep/pkill） | ✅ | ⚠️ 失效 | ✅ |
Windows 用户要注意的两件事：
1. 图片不会自动压缩
macOS 上大于 150KB 的图会用系统自带的 sips 压到长边 1280px / JPEG 82；Windows 直接跳过、上传原图。影响：文章体积大、上传慢，超大图（比如 10MB 的截图）可能上传失败。
对策：发布前自己先压一遍，比如用 ImageMagick（三个平台通用）：
2. 「自动关闭上一个浏览器」不生效
脚本靠 pgrep/pkill 检测有没有别的 Chrome 占着同一个登录态目录，Windows 没这两个命令，这步会静默跳过。影响：如果上次那个自动化 Chrome 窗口还开着，再跑一次可能因为 profile 被锁而启动失败。
对策：跑之前先手动关掉上一次的自动化 Chrome 窗口（注意别关你日常用的 Chrome——自动化用的是独立目录，互不干扰）。
登录态目录位置：
平台 | 默认路径 |
macOS / Linux | ~/.hermes-x-profile |
Windows | C:\Users<你的用户名>.hermes-x-profile |
十、遇到问题怎么办（排错表）
现象 | 平台 | 解决办法 |
Chrome 启动失败 / profile 被占用 | macOS·Linux | 脚本会自动清理锁并重试；还不行就 pkill -f .hermes-x-profile 后重跑 |
Chrome 启动失败 / profile 被占用 | Windows | 先手动关掉上一次的自动化 Chrome 窗口，再重跑。别关你日常用的 Chrome |
找不到 Chrome | 全平台 | 需要「系统安装」的 Google Chrome。只装 Edge 或 Chromium 不行 |
「没找到写文章按钮」 | 全平台 | 没登录（先不带 --headless 跑一次登录），或 X 改了界面 |
结果里 imgOk 与图片数对不上 | 全平台 | 检查图片路径能不能解析；看输出里有没有残留 _XPOSTER 标记 |
图片上传失败 / 很慢 | Windows·Linux | 无自动压缩，大图自己先压到长边 ≤1280 |
编辑器等待超时 | 全平台 | 加大 --timeout，比如 --timeout=300000 |
十一、安全，可以放心
- 网络请求只发往 x.com（草稿的 GraphQL 变更），没有遥测、不往外发任何数据
- 登录 Cookie 存在本地 ~/.hermes-x-profile，权限 700，等同于密码，别拷贝、别提交到 Git
- 永远只做草稿，Publish 那一下在你手里
- MIT 开源，代码全透明，随便看、随便改
十二、开源与致谢
本项目是 MIT 开源，技术源头承袭自 xPoster（MIT），经 punk2898/x-article-publisher v4.1.0（MIT）分叉而来。完整的传承链与逐条改动记录见 NOTICE.md 和 LOCAL_CHANGES.md。
写在最后
最简单的安装就是 把工具地址复制给 Claude 或者 Codex 让智能体帮你装
到此，从今天起，写 X 长文，推送将非常流畅,本文就是使用这个skill 推送发布的
同时给大家推荐几个同步工具,本人在用实测很好用，本文就是使用这个skill 推送发布的！
obsidian 上 markdown 同步到 notion （需配置notion id 和 notion api 令牌）
https://github.com/jxpeng98/obsidian-to-NotionNext
obsidian 上 markdown 同步到 微信公众号 （需要加IP白名单，填id 和 key）
https://community.obsidian.md/plugins/marknice-wechat
微信文章同步到多平台（知乎、掘金、微博等, 推荐使用chrome 扩展 （需同步的平台需要先登录）
https://github.com/wechatsync/Wechatsync
我日常使用 通常是在obisidian 写好文章，同步到推特，同步到notion个人站（我的个人站基于notion构建）,同步到公号，同步到更多中文平台
以上由deepseek辅助创作，本人负责修改审核而成！如果文章对你有帮助，欢迎大家点赞、收藏、关注我，你的一键三连，是我前行的动力！
我是前独立站开发 ，现AI 与出海实践者，热衷分享创造，非常开心与大家一起交流学习！
上一篇
把 NanoBot 跑起来了：本地聊 Discord，代理走远程，Grok 4.5 能聊天能生图。踩了几个坑，记一下。
下一篇
官方入门指引Claude Code 实用技巧工作坊-Boris Cherny
Loading...