tuzi-danger-x-to-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

X to Markdown

X 转 Markdown

Converts X content to markdown:

Tweets/threads → Markdown with YAML front matter
X Articles → Full content extraction

将X内容转换为Markdown：

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

Script Directory

脚本目录

Scripts located in

scripts/

subdirectory.

Path Resolution:

```
SKILL_DIR
```
= this SKILL.md's directory
Script path =
```
${SKILL_DIR}/scripts/main.ts
```

脚本位于

scripts/

子目录下。

路径解析规则：

```
SKILL_DIR
```
= 本SKILL.md文件所在目录
脚本路径 =
```
${SKILL_DIR}/scripts/main.ts
```

Consent Requirement

同意条款要求

Before any conversion, check and obtain consent.

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

Consent Flow

同意流程

Step 1: Check consent file

bash

undefined

步骤1：检查同意文件

bash

undefined

macOS

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

Linux

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


**Step 2**: If `accepted: true` and `disclaimerVersion: "1.0"` → print warning and proceed:

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


**Step 3**: If missing or version mismatch → display disclaimer:

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?


Use `AskUserQuestion` with options: "Yes, I accept" | "No, I decline"

**Step 4**: On accept → create consent file:
```json
{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO timestamp>",
  "disclaimerVersion": "1.0"
}

Step 5: On decline → output "User declined. Exiting." and stop.

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


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

警告：正在使用逆向工程的X API，同意时间：<acceptedAt>


**步骤3**：如果文件不存在或版本不匹配 → 展示免责声明：

免责声明

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

风险提示：

若X修改API，工具可能失效
无任何保障或支持服务
可能导致账号受限
风险自负

是否接受条款并继续？


使用`AskUserQuestion`工具，选项为："是，我接受" | "否，我拒绝"

**步骤4**：用户同意后 → 创建同意文件：
```json
{
  "version": 1,
  "accepted": true,
  "acceptedAt": "<ISO timestamp>",
  "disclaimerVersion": "1.0"
}

步骤5：用户拒绝 → 输出"用户拒绝，退出操作。"并停止运行。

Preferences (EXTEND.md)

偏好设置（EXTEND.md）

Use Bash to check EXTEND.md existence (priority order):

bash

undefined

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

bash

undefined

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)

再检查用户级（跨平台：$HOME在macOS/Linux/WSL下均生效）

test -f "$HOME/.tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md" && echo "user"


┌────────────────────────────────────────────────────────────┬───────────────────┐
│                            Path                            │     Location      │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md         │ Project directory │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-danger-x-to-markdown/EXTEND.md   │ User home         │
└────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ **MUST** run first-time setup (see below) — do NOT silently create defaults │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Download media by default | Default output directory

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支持配置项**：默认下载媒体 | 默认输出目录

First-Time Setup (BLOCKING)

首次设置（阻塞式）

CRITICAL: When EXTEND.md is not found, you MUST use
AskUserQuestion
to ask the user for their preferences before creating EXTEND.md. NEVER create EXTEND.md with defaults without asking. This is a BLOCKING operation — do NOT proceed with any conversion until setup is complete.

Use

AskUserQuestion

with ALL questions in ONE call:

Question 1 — header: "Media", question: "How to handle images and videos in tweets?"

"Ask each time (Recommended)" — After saving markdown, ask whether to download media
"Always download" — Always download media to local imgs/ and videos/ directories
"Never download" — Keep original remote URLs in markdown

Question 2 — header: "Output", question: "Default output directory?"

"x-to-markdown (Recommended)" — Save to ./x-to-markdown/{username}/{tweet-id}.md
(User may choose "Other" to type a custom path)

Question 3 — header: "Save", question: "Where to save preferences?"

"User (Recommended)" — ~/.tuzi-skills/ (all projects)
"Project" — .tuzi-skills/ (this project only)

After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.

Full reference: references/config/first-time-setup.md

重要提示：未找到EXTEND.md时，你必须使用
AskUserQuestion
在创建EXTEND.md前询问用户偏好设置。绝对不要未询问就创建带默认配置的EXTEND.md。这是阻塞式操作——设置完成前不得进行任何转换操作。

单次调用

AskUserQuestion

时需包含所有问题：

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

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

问题2 — 标题："输出设置"，问题："默认输出目录是？"

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

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

"用户级（推荐）" — ~/.tuzi-skills/（所有项目通用）
"项目级" — .tuzi-skills/（仅当前项目生效）

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

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

Supported Keys

支持的配置项

Key	Default	Values	Description
`download_media`	`ask`	`ask` / `1` / `0`	`ask` = prompt each time, `1` = always download, `0` = never
`default_output_dir`	empty	path or empty	Default output directory (empty = `./x-to-markdown/` )

Value priority:

CLI arguments (
```
--download-media
```
,
```
-o
```
)
EXTEND.md
Skill defaults

配置项	默认值	可选值	描述
`download_media`	`ask`	`ask` / `1` / `0`	`ask` = 每次询问, `1` = 始终下载, `0` = 从不下载
`default_output_dir`	空	路径或空	默认输出目录（空 = `./x-to-markdown/` ）

配置优先级：

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

Usage

使用方法

bash

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

bash

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

Options

参数说明

Option	Description
`<url>`	Tweet or article URL
`-o <path>`	Output path
`--json`	JSON output
`--download-media`	Download image/video assets to local `imgs/` and `videos/` , and rewrite markdown links to local relative paths
`--login`	Refresh cookies only

参数	描述
`<url>`	推文或长文URL
`-o <path>`	输出路径
`--json`	输出JSON格式
`--download-media`	将图片/视频资源下载到本地 `imgs/` 和 `videos/` 目录，并将Markdown中的链接重写为本地相对路径
`--login`	仅刷新Cookie

Supported URLs

支持的URL格式

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

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

Output

输出示例

markdown

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

Content...

File structure:

x-to-markdown/{username}/{tweet-id}/{content-slug}.md

When

--download-media

is enabled:

Images are saved to
```
imgs/
```
next to the markdown file
Videos are saved to
```
videos/
```
next to the markdown file
Markdown media links are rewritten to local relative paths

markdown

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

Content...

文件结构：

x-to-markdown/{用户名}/{推文ID}/{内容slug}.md

启用

--download-media

参数时：

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

Media Download Workflow

媒体下载工作流

Based on

download_media

setting in EXTEND.md:

Setting	Behavior
`1` (always)	Run script with `--download-media` flag
`0` (never)	Run script without `--download-media` flag
`ask` (default)	Follow the ask-each-time flow below

基于EXTEND.md中的

download_media

配置：

配置值	行为
`1` （始终下载）	运行脚本时携带 `--download-media` 参数
`0` （从不下载）	运行脚本时不带 `--download-media` 参数
`ask` （默认）	遵循下方的每次询问流程

Ask-Each-Time Flow

每次询问流程

Run script without
```
--download-media
```
→ markdown saved
Check saved markdown for remote media URLs (
```
https://
```
in image/video links)
If no remote media found → done, no prompt needed
If remote media found → use
```
AskUserQuestion
```
:
- header: "Media", question: "Download N images/videos to local files?"
- "Yes" — Download to local directories
- "No" — Keep remote URLs
If user confirms → run script again with
```
--download-media
```
(overwrites markdown with localized links)

运行脚本不带
```
--download-media
```
参数 → 保存Markdown文件
检查保存的Markdown中是否有远程媒体链接（图片/视频链接中包含
```
https://
```
）
未找到远程媒体 → 流程结束，无需提示
找到远程媒体 → 使用
```
AskUserQuestion
```
：
- 标题："媒体下载"，问题："是否下载N个图片/视频到本地？"
- "是" — 下载到本地目录
- "否" — 保留远程链接
如果用户确认 → 再次运行脚本并携带
```
--download-media
```
参数（覆盖原有Markdown，将链接替换为本地路径）

Authentication

认证方式

Environment variables (preferred):
```
X_AUTH_TOKEN
```
,
```
X_CT0
```
Chrome login (fallback): Auto-opens Chrome, caches cookies locally

环境变量（优先）：
```
X_AUTH_TOKEN
```
,
```
X_CT0
```
Chrome登录（降级方案）：自动打开Chrome，本地缓存Cookie

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

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