X 转 Markdown

将 X 内容转换为 Markdown：

• 推文/线程 → 带有 YAML 前置元数据的 Markdown
• X 文章 → 完整内容提取

脚本目录

脚本位于 scripts/ 子目录中。

路径解析：

1. {baseDir} = 此 SKILL.md 文件所在的目录
2. 脚本路径 = {baseDir}/scripts/main.ts
3. 解析 ${BUN_X} 运行时：如果已安装 bun → 使用 bun；如果 npx 可用 → 使用 npx -y bun；否则建议安装 bun

同意要求

在进行任何转换之前，必须检查并获取同意。

同意流程

步骤 1：检查同意文件

# macOS
cat ~/Library/Application\ Support/baoyu-skills/x-to-markdown/consent.json

# Linux
cat ~/.local/share/baoyu-skills/x-to-markdown/consent.json

步骤 2：如果 accepted： true 且 disclaimerVersion： "1.0" → 打印警告并继续：

警告：使用逆向工程的 X API。接受时间：<acceptedAt>

步骤 3：如果文件缺失或版本不匹配 → 显示免责声明：

免责声明

此工具使用逆向工程的 X API，并非官方 API。

风险：
- 如果 X 更改 API，可能会失效
- 无保证或支持
- 可能导致账户受限
- 使用风险自负

接受条款并继续？

使用 AskUserQuestion 并提供选项：”是，我接受” | “否，我拒绝”

步骤 4：接受后 → 创建同意文件：

{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO 时间戳>",
  "disclaimerVersion": "1.0"
}

步骤 5：拒绝后 → 输出”用户已拒绝。退出。”并停止。

偏好设置 (EXTEND.md)

检查 EXTEND.md 是否存在（优先级顺序）：

# macOS, Linux, WSL, Git Bash
test -f .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "user"

# PowerShell (Windows)
if (Test-Path .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md") { "user" }

┌────────────────────────────────────────────────────────────┬───────────────────┐
│ 路径 │ 位置 │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md │ 项目目录 │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md │ 用户主目录 │
└────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│ 结果 │ 操作 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 找到 │ 读取、解析、应用设置 │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到 │ 必须运行首次设置（见下文）— 不要静默创建默认值 │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持：默认下载媒体 | 默认输出目录

首次设置（阻塞性步骤）

关键：当未找到 EXTEND.md 时，你必须使用 AskUserQuestion 在创建 EXTEND.md 之前询问用户的偏好。切勿在未经询问的情况下使用默认值创建 EXTEND.md。这是一个阻塞性操作 — 在设置完成之前，不要进行任何转换。

使用 AskUserQuestion 在一次调用中提出所有问题：

问题 1 — 标题：”媒体”，问题：”如何处理推文中的图片和视频？”

• “每次都询问（推荐）” — 保存 Markdown 后，询问是否下载媒体
• “始终下载” — 始终将媒体下载到本地的 imgs/ 和 videos/ 目录
• “从不下载” — 在 Markdown 中保留原始的远程 URL

问题 2 — 标题：”输出”，问题：”默认输出目录？”

• “x-to-markdown（推荐）” — 保存到 ./x-to-markdown/{用户名}/{推文-id}.md
• （用户可以选择”其他”来输入自定义路径）

问题 3 — 标题：”保存”，问题：”偏好设置保存到哪里？”

• “用户（推荐）” — ~/.baoyu-skills/（所有项目）
• “项目” — .baoyu-skills/（仅此项目）

用户回答后，在所选位置创建 EXTEND.md，确认”偏好设置已保存到 [路径]”，然后继续。

完整参考：references/config/first-time-setup.md

支持的键

值优先级：

1. 命令行参数 (--download-media, -o)
2. EXTEND.md
3. 技能默认值

使用方法

${BUN_X} {baseDir}/scripts/main.ts <url>
${BUN_X} {baseDir}/scripts/main.ts <url> -o output.md
${BUN_X} {baseDir}/scripts/main.ts <url> --download-media
${BUN_X} {baseDir}/scripts/main.ts <url> --json

选项

支持的 URL

• https://x.com/<用户>/status/<id>
• https://twitter.com/<用户>/status/<id>
• https://x.com/i/article/<id>

输出

---
url: "https://x.com/user/status/123"
author: "名称 (@用户)"
tweetCount: 3
coverImage: "https://pbs.twimg.com/media/example.jpg"
---

内容...

文件结构：x-to-markdown/{用户名}/{推文-id}/{内容标识符}.md

当启用 --download-media 时：

• 图片保存到 Markdown 文件旁边的 imgs/ 目录
• 视频保存到 Markdown 文件旁边的 videos/ 目录
• Markdown 中的媒体链接被重写为本地相对路径

媒体下载工作流程

基于 EXTEND.md 中的 download_media 设置：

“每次都询问”流程

1. 不带 --download-media 标志运行脚本 → 保存 Markdown
2. 检查保存的 Markdown 中是否存在远程媒体 URL（图片/视频链接中的 https：//）
3. 如果未找到远程媒体 → 完成，无需提示
4. 如果找到远程媒体 → 使用 AskUserQuestion：
   • 标题：”媒体”，问题：”下载 N 个图片/视频到本地文件？”
   • “是” — 下载到本地目录
   • “否” — 保留远程 URL
5. 如果用户确认 → 再次使用 --download-media 标志运行脚本（用本地化链接覆盖 Markdown）

身份验证

1. 环境变量（首选）：X_AUTH_TOKEN, X_CT0
2. Chrome 登录（回退）：自动打开 Chrome，在本地缓存 Cookies

扩展支持

通过 EXTEND.md 进行自定义配置。参见偏好设置部分了解路径和支持的选项。