name: baoyu-danger-x-to-markdown description: 将X（Twitter）推文和文章转换为带有YAML front matter的Markdown。使用反向工程API，需要用户同意。当用户提及“X转Markdown”、“推文转Markdown”、“保存推文”或提供x.com/twitter.com URL进行转换时使用。

X转Markdown

将X内容转换为Markdown：

推文/线程 → 带有YAML front matter的Markdown
X文章 → 完整内容提取

脚本目录

脚本位于scripts/子目录中。

路径解析：

SKILL_DIR = 此SKILL.md的目录
脚本路径 = ${SKILL_DIR}/scripts/main.ts

同意要求

在转换之前，检查并获取同意。

同意流程

步骤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，非官方。

风险：
- 如果X更改API可能会中断
- 无保证或支持
- 可能的账户限制
- 使用风险自负

接受条款并继续？

使用AskUserQuestion，选项：“是，我接受” | “不，我拒绝”

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

{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO timestamp>",
  "disclaimerVersion": "1.0"
}

步骤5：拒绝时 → 输出"用户拒绝。退出。"并停止。

偏好设置 (EXTEND.md)

使用Bash检查EXTEND.md存在（优先级顺序）：

# 首先检查项目级别
test -f .baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md && echo "project"

# 然后用户级别（跨平台：$HOME在macOS/Linux/WSL上工作）
test -f "$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md" && echo "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/{username}/{tweet-id}.md
（用户可以选择"其他"输入自定义路径）

问题3 — 标题：“保存”，问题：“保存偏好的位置？”

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

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

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

支持的关键字

关键字	默认值	值	描述
`download_media`	`ask`	`ask` / `1` / `0`	`ask` = 每次提示，`1` = 总是下载，`0` = 从不
`default_output_dir`	空	路径或空	默认输出目录（空 = `./x-to-markdown/`）

值优先级：

CLI参数（--download-media, -o）
EXTEND.md
技能默认值

用法

npx -y bun ${SKILL_DIR}/scripts/main.ts <url>
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> -o output.md
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --download-media
npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --json

选项

选项	描述
`<url>`	推文或文章URL
`-o <path>`	输出路径
`--json`	JSON输出
`--download-media`	下载图像/视频资源到本地`imgs/`和`videos/`，并重写Markdown链接到本地相对路径
`--login`	仅刷新cookies

支持的URL

https://x.com/<user>/status/<id>
https://twitter.com/<user>/status/<id>
https://x.com/i/article/<id>

输出

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

内容...

文件结构：x-to-markdown/{username}/{tweet-id}.md

当启用--download-media时：

图像保存到Markdown文件旁边的imgs/
视频保存到Markdown文件旁边的videos/
Markdown媒体链接重写到本地相对路径

媒体下载工作流

基于EXTEND.md中的download_media设置：

设置	行为
`1`（总是）	使用`--download-media`标志运行脚本
`0`（从不）	不使用`--download-media`标志运行脚本
`ask`（默认）	遵循每次询问流程如下

每次询问流程

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

认证

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

扩展支持

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