canghe-danger-x-to-markdown

用途

该技能用于将 X（Twitter）上的内容转换为 Markdown 文件。具体支持两类内容：推文/推文串转换为带 YAML front matter 的 Markdown；X 文章进行完整内容提取。当用户提及「X to Markdown」等相关需求时使用。

主要能力

将推文和推文串转换为 Markdown，并附加包含 url、author、tweetCount、coverImage 等字段的 YAML front matter。
对 X 文章进行完整内容提取。
支持通过 --json 输出 JSON 格式结果。
支持通过 --download-media 下载图片和视频：图片保存到 Markdown 文件旁的 imgs/ 目录，视频保存到 videos/ 目录，并将 Markdown 中的媒体链接改写为本地相对路径。
支持通过 --login 仅刷新 cookies。
输出文件结构为 x-to-markdown/{username}/{tweet-id}.md。
支持通过 EXTEND.md 进行自定义配置，可配置的键包括 download_media（默认 ask，可选 ask / 1 / 0）和 default_output_dir（默认空，空表示 ./x-to-markdown/）。值优先级为：CLI 参数（--download-media、-o）、EXTEND.md、技能默认值。

使用方式

脚本位于 scripts/ 子目录，脚本路径为 ${SKILL_DIR}/scripts/main.ts，其中 SKILL_DIR 为 SKILL.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: "Name (@user)"
tweetCount: 3
coverImage: "https://pbs.twimg.com/media/example.jpg"
---

Content...

同意要求

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

同意流程：

检查同意文件：
- macOS：cat ~/Library/Application\ Support/canghe-skills/x-to-markdown/consent.json
- Linux：cat ~/.local/share/canghe-skills/x-to-markdown/consent.json
若 accepted: true 且 disclaimerVersion: "1.0"，打印警告并继续：Warning: Using reverse-engineered X API. Accepted on: <acceptedAt>。

若缺失或版本不匹配，显示免责声明：

DISCLAIMER

This tool uses a reverse-engineered X API, NOT official.

Risks:
- May break if X changes API
- No guarantees or support
- Possible account restrictions
- Use at your own risk

Accept terms and continue?

使用 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 是否存在，优先级顺序如下：

项目级：.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md
用户级：$HOME/.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md（跨平台：$HOME 适用于 macOS/Linux/WSL）

路径	位置
.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md	项目目录
$HOME/.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md	用户主目录

结果	操作
找到	读取、解析并应用设置
未找到	必须运行首次设置（见下文）——不要静默创建默认值

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

首次设置（阻塞性）：

当 EXTEND.md 未找到时，必须使用 AskUserQuestion 询问用户偏好，然后才能创建 EXTEND.md。绝不能未经询问就用默认值创建 EXTEND.md。这是阻塞操作——在设置完成前不要进行任何转换。

在单次调用中通过 AskUserQuestion 提出所有问题：

问题 1——header: "Media"，question: "How to handle images and videos in tweets?"

"Ask each time (Recommended)"——保存 Markdown 后询问是否下载媒体
"Always download"——始终将媒体下载到本地 imgs/ 和 videos/ 目录
"Never download"——在 Markdown 中保留原始远程 URL

问题 2——header: "Output"，question: "Default output directory?"

"x-to-markdown (Recommended)"——保存到 ./x-to-markdown/{username}/{tweet-id}.md（用户可选择 "Other" 输入自定义路径）

问题 3——header: "Save"，question: "Where to save preferences?"

"User (Recommended)"——~/.canghe-skills/（所有项目）
"Project"——.canghe-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 进行自定义配置。路径与支持选项见偏好设置部分。