baoyu-danger-x-to-markdown

用途

该技能用于将 X（Twitter）内容转换为 Markdown 格式，包括：

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

主要能力

支持转换单条推文、推文串以及 X 文章。
输出 Markdown 文件，包含 YAML front matter（如 url、author、tweetCount、coverImage 等字段）。
支持 JSON 输出格式。
可选下载图片和视频到本地 imgs/ 和 videos/ 目录，并将 Markdown 中的媒体链接重写为本地相对路径。
支持通过环境变量或 Chrome 登录进行身份验证。

使用方式

脚本位于 scripts/ 子目录，路径解析规则为：SKILL_DIR 是 SKILL.md 所在目录，脚本路径为 ${SKILL_DIR}/scripts/main.ts。

基本命令示例：

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>

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

启用 --download-media 时，图片保存到 Markdown 文件旁的 imgs/，视频保存到 videos/，Markdown 媒体链接重写为本地相对路径。

同意要求

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

同意流程：

检查同意文件：
- macOS：cat ~/Library/Application\ Support/baoyu-skills/x-to-markdown/consent.json
- Linux：cat ~/.local/share/baoyu-skills/x-to-markdown/consent.json
如果 accepted: true 且 disclaimerVersion: "1.0"，打印警告并继续：Warning: Using reverse-engineered X API. Accepted on: <acceptedAt>
如果缺失或版本不匹配，显示免责声明：
- 该工具使用逆向工程的 X API，非官方。
- 风险：X 更改 API 时可能失效；无保证或支持；可能导致账号限制；使用风险自负。
- 使用 AskUserQuestion 提供选项：“Yes, I accept” 或 “No, I decline”。

接受后创建同意文件：

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

拒绝则输出 “User declined. Exiting.” 并停止。

偏好配置（EXTEND.md）

使用 Bash 检查 EXTEND.md 是否存在，优先级顺序：

项目级：.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md
用户级：$HOME/.baoyu-skills/baoyu-danger-x-to-markdown/EXTEND.md

若找到则读取、解析并应用设置；若未找到，必须运行首次设置（阻塞操作），不得静默创建默认值。

EXTEND.md 支持的键：

download_media：默认 ask，可选 ask / 1 / 0。ask = 每次询问，1 = 总是下载，0 = 从不下载。
default_output_dir：默认空，路径或空。默认输出目录（空 = ./x-to-markdown/）。

值优先级：CLI 参数（--download-media、-o） > EXTEND.md > 技能默认值。

首次设置（阻塞）

当 EXTEND.md 未找到时，必须使用 AskUserQuestion 询问用户偏好，然后创建 EXTEND.md。不得在未询问的情况下创建默认 EXTEND.md。此操作阻塞，设置完成前不得进行任何转换。

需在一次 AskUserQuestion 调用中询问所有问题：

媒体处理：
- “Ask each time (Recommended)”：保存 Markdown 后询问是否下载媒体
- “Always download”：总是下载媒体到本地 imgs/ 和 videos/
- “Never download”：在 Markdown 中保留原始远程 URL
默认输出目录：
- “x-to-markdown (Recommended)”：保存到 ./x-to-markdown/{username}/{tweet-id}.md
- 用户可选择 “Other” 输入自定义路径
偏好保存位置：
- “User (Recommended)”：~/.baoyu-skills/（所有项目）
- “Project”：.baoyu-skills/（仅当前项目）

用户回答后，在所选位置创建 EXTEND.md，确认 “Preferences saved to [path]”，然后继续。

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

媒体下载工作流

根据 EXTEND.md 中的 download_media 设置：

1（总是）：运行脚本时带 --download-media 标志
0（从不）：运行脚本时不带 --download-media 标志
ask（默认）：按以下每次询问流程

每次询问流程：

运行脚本时不带 --download-media → 保存 Markdown
检查保存的 Markdown 中是否有远程媒体 URL（图片/视频链接中的 https://）
若无远程媒体 → 完成，无需提示
若有远程媒体 → 使用 AskUserQuestion：
- header: “Media”，question: “Download N images/videos to local files?”
- “Yes”：下载到本地目录
- “No”：保留远程 URL
若用户确认 → 再次运行脚本并带 --download-media（覆盖 Markdown 为本地链接）

身份验证

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

扩展支持

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

OpenClaw 迁移说明

迁移模式：OpenClaw 原生优先
保留目录：scripts（是）、references（是）、prompts（否）
外部依赖：bun、chrome、social-platform-access
风险等级：高
检测到的环境变量：API、HOME、X_AUTH_TOKEN
配置兼容性：保留原始 .baoyu-skills/<skill>/EXTEND.md 行为，并在需要时在运行时包装器中添加 OpenClaw 兼容路径。

OpenClaw 预检：

当脚本示例使用 npx -y bun ... 时，确认 bun 可用。
确认 Chrome 已安装且可启动，用于 CDP/浏览器自动化流程。
在发布或抓取操作前，确认账号会话/cookies 有效。

OpenClaw 失败回退：

若运行时依赖缺失，停止执行并返回确切的安装/设置命令。
若浏览器自动化失败，切换到手动/等待模式（如可用）。
若平台阻止自动化，返回手动发布/导出说明，而非重试循环。
对于高风险工作流，在不可逆操作前要求用户明确确认。

适用场景

需要将 X 推文、推文串或文章归档为 Markdown 文件。
需要将 X 内容迁移到本地知识库或文档系统。
需要提取 X 文章完整内容并保存为结构化 Markdown。
需要下载推文中的图片和视频到本地。

限制

使用逆向工程的 X API，非官方，X 更改 API 时可能失效。
无保证或支持，可能导致账号限制，使用风险自负。
需要用户明确同意后方可使用。
依赖 bun 和 Chrome（用于回退登录）。
首次使用需完成阻塞式设置。
高风险工作流需用户明确确认。