tuzi-danger-x-to-markdown

X 转 Markdown

将 X 内容转换为 Markdown：

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

脚本目录

脚本位于 scripts/ 子目录中。

路径解析：

1. SKILL_DIR = 此 SKILL.md 所在目录
2. 脚本路径 = ${SKILL_DIR}/scripts/main.ts

同意要求

每次转换之前，都要检查并获取用户同意。

同意流程

步骤 1：检查同意文件

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

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

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

Warning: Using reverse-engineered X API. Accepted on: <acceptedAt>

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

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"

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

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

步骤 5：用户拒绝后 → 输出 "User declined. Exiting." 并停止。

偏好设置（EXTEND.md）

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

# Check project-level first
test -f .tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md" && echo "user"

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

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

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

首次设置（阻塞）

重要：找不到 EXTEND.md 时，必须使用 AskUserQuestion 在创建 EXTEND.md 之前询问用户偏好。绝不能在未询问的情况下使用默认值创建 EXTEND.md。这是一项阻塞操作——设置完成前不得继续进行任何转换。

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

问题 1 — 标题："Media"，问题："How to handle images and videos in tweets?"

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

问题 2 — 标题："Output"，问题："Default output directory?"

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

问题 3 — 标题："Save"，问题："Where to save preferences?"

• "User (Recommended)" — ~/.tuzi-skills/（所有项目）
• "Project" — .tuzi-skills/（仅此项目）

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

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

支持的键

键	默认值	值	说明
download_media	ask	ask / 1 / 0	ask = 每次询问，1 = 始终下载，0 = 从不下载
default_output_dir	空	路径或空	默认输出目录（空 = ./x-to-markdown/）

值的优先级：

1. CLI 参数（--download-media、-o）
2. EXTEND.md
3. 技能默认值

用法

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	仅刷新 Cookie

支持的 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...

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

启用 --download-media 时：

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

媒体下载工作流

根据 EXTEND.md 中的 download_media 设置：

设置	行为
1（始终）	使用 --download-media 标志运行脚本
0（从不）	不使用 --download-media 标志运行脚本
ask（默认）	按照下方的逐次询问流程操作

逐次询问流程

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，并在本地缓存 Cookie

扩展支持

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