baoyu-danger-x-to-markdown实战：在授权边界内归档推文与长文

返回总教程

baoyu-danger-x-to-markdown 用于把 X/Twitter 推文、线程和 X Articles 转成带 YAML 元数据的 Markdown。名字中的 danger 不是装饰：实现使用逆向分析的非官方接口，接口随时可能变化，也可能带来账号限制。

本文基于固定提交源码核对；案例仅为操作示例，非付费内容、账号或接口实测。写作过程中未登录、提取 Cookie、调用接口或生成归档。

一、什么时候用，什么时候不用

适合保存自己有权查看的公开推文、技术讨论串和长文，形成可搜索的资料库。相较复制一段截图，Markdown 更便于检索原话、保存来源和继续翻译。

它不提供官方 API 的稳定性保证，不能承诺某条线程一定完整，也不能保证引用的推文仍然存在。内容删除、隐私限制、订阅权限和接口调整，都可能让正文或附件缺失。用户能在浏览器看到某页，也不意味着脚本当前接口一定支持它。

不要用该工具绕过登录、访问控制或付费权限；不要导入别人的会话凭证。归档成功也不等于获得转载授权。个人研究资料和公开发布文章应分开，尤其不能把私密账号内容或 Cookie 缓存随 Hexo 发布。

二、前置依赖与按需安装

需要能执行文件工作流的 Agent、Bun 或可用的 npx，并且能够以自己的账号正常访问目标内容。脚本入口是完整技能目录中的 scripts/main.ts，运行时优先 Bun，否则允许 npx -y bun。

仓库 README 提供安装入口，本系列另核实 skills CLI 1.7.2 的按需选择参数：

1	npx skills add jimliu/baoyu-skills --skill baoyu-danger-x-to-markdown --agent codex

在安装流程中只选这个技能；或者按 README 的项目级方式，把固定版本的完整技能目录放入项目 .agents/skills/。不要只安装一份说明文件：脚本还依赖同目录的 Cookie、线程、媒体本地化代码，以及 baoyu-chrome-cdp。

最新安装不等于固定快照，安装命令本身不会锁定本文版本。若必须复现本文，应使用提交 1567581c26ec29f4216c6e6835415bf30343b0e3 的源码目录，并让 Agent 核查实际运行版本。本文不要求安装任何所谓“X 官方 SDK”，也不把非官方接口包装成官方支持。

三、同意流程必须先于登录与转换

源码在执行登录刷新和转换之前调用 ensureConsent。它会读取本地 consent.json；有效记录需要版本、已接受状态、接受时间，以及 disclaimerVersion: "1.0" 等字段。文件不存在、无效或免责声明版本变化时，必须向用户说明风险并征求选择。

风险说明至少应包含：这是非官方逆向接口；X 调整接口可能导致失效；没有官方支持和保证；可能出现账号限制。用户拒绝，就停止，不能替用户勾选同意。已经接受的情况下，仍会显示此前接受时间及警告。

在 Windows 上，源码按 %APPDATA%/baoyu-skills/x-to-markdown/consent.json 定位；macOS 使用 ~/Library/Application Support/baoyu-skills/x-to-markdown/，Linux 默认使用 ~/.local/share/baoyu-skills/x-to-markdown/。X_DATA_DIR 可改变数据目录，Linux 也尊重 XDG_DATA_HOME。

非交互执行时若缺同意记录，脚本会报错，不会替你完成接受。Agent 只能在用户明确接受后记录同意；不能为了让流水线通过而预填接受状态。这里故意不提供“直接创建已同意文件”的快捷命令。

四、登录态与配置如何管理

SKILL 列出的凭证方式包括环境变量 X_AUTH_TOKEN、X_CT0，以及 Chrome 登录后在本地缓存 Cookie。它们是会话凭证，不是可公开的普通配置。不要把真实值写进 Markdown、聊天示例、Git 提交或截图；不要请求 Agent 把它们打印出来排错。

脚本支持 --login，仅刷新 Cookie 后退出，不会顺便归档文章。但即使只刷新登录态，同意检查仍然执行。登录失败应回到用户本人可见的正常登录流程，不提供绕过验证或复制他人凭证的方案。

内容偏好使用 EXTEND.md，查找顺序为项目、XDG、用户目录，第一个命中生效：

1
2
3

.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md
${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md
$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md

支持的核心内容：

1 2	download_media: ask default_output_dir: ./x-archive/

首次没有配置时必须询问媒体策略、输出位置和配置保存范围。ask 是发现远程媒体后再问，1 是下载，0 是保留链接。偏好确认与接口风险同意是两件不同的事，不能互相替代。

五、输入输出与可复制请求

输入支持 x.com/<user>/status/<id>、twitter.com/<user>/status/<id> 和 x.com/i/article/<id>。默认推文目录形态是 x-to-markdown/{username}/{tweet-id}/{content-slug}.md；文章 URL 没有用户名时，脚本使用文章 ID 参与目录组织。给出明确输出文件路径，可避免依赖自动命名细节。

Markdown 通常包含来源 URL、作者、推文数量等元数据；长文和推文的字段并不完全相同，不要强行要求每个输出都含 tweetCount。启用媒体下载后会建立 imgs/、videos/ 并改写相对链接。JSON 模式主要便于读取实际结果路径，不能把某个固定字段当作所有内容类型都一样的保证。

请使用 baoyu-danger-x-to-markdown 归档这条我有权访问的内容：[完整X URL]。
先说明非官方逆向接口风险并检查同意状态；需要新同意时等我确认。
如果需要登录，由我在自己的浏览器中完成，不读取其他账号凭证。
首次配置先询问我；输出到 [私有资料目录]，媒体先保留远程链接。
正文保存后检查作者、来源、线程顺序与缺失内容，再问是否下载媒体。
不要发布，不要把 Cookie、浏览器配置或任何令牌写入结果和报告。

六、操作案例：归档一组技术讨论

假设你在自己的 X 登录会话中看到一位开发者的五段技术说明，想保存供以后写文章时核对。这里的“五段”是案例设定，不是实测结果。

确认权限与风险。 提供线程的完整地址，确认是自己可访问内容。Agent 完成免责声明与偏好确认，不直接开始网络请求。
获取文本。 先不下载媒体，减少不必要的请求和磁盘占用。读回 Markdown，核对作者和链接，检查输出是否覆盖预计的五段；若少了两段，应报告缺失，不补写猜测内容。
区分正文与引用。 若原推文引用其他作者观点，保留归属关系，不能把引用合并成主作者结论。技术文章里的配图说明也不等于图片内容已被识别。
决定媒体归档。 用户确认需要离线阅读后才下载。源码会尝试复用与目标 URL 匹配的现有 Markdown 来本地化媒体，所以不要假定第二次一定重新抓取正文，也不要随意改掉来源元数据。
验证资源与留存。 检查图片、视频文件是否实际存在，记录仍保留远程 URL 的附件。保持整个目录移动，避免 Obsidian 中的图片相对路径失效。
另写发布稿。 需要引用时新建自己的文章，标注原作者与原链接，只引用必要片段。不要直接给整份归档加 publish: true，更不要把会话文件带进博客。