canghe-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前置内容的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/canghe-skills/x-to-markdown/consent.json

Linux

cat ~/.local/share/canghe-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/canghe-skills/x-to-markdown/consent.json


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

警告: 使用逆向工程X API。同意时间: <acceptedAt>


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

免责声明

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

风险:

若X修改API，工具可能失效
不提供任何保证或支持
可能导致账号受限
风险自负

是否接受条款并继续?


使用`AskUserQuestion`，选项: "Yes, I accept" | "No, I decline"

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

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

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 .canghe-skills/canghe-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/.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md" && echo "user"


┌────────────────────────────────────────────────────────────┬───────────────────┐
│                            Path                            │     Location      │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ .canghe-skills/canghe-danger-x-to-markdown/EXTEND.md         │ Project directory │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.canghe-skills/canghe-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/.canghe-skills/canghe-danger-x-to-markdown/EXTEND.md" && echo "user"


┌────────────────────────────────────────────────────────────┬───────────────────┐
│                            路径                            │     位置      │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ .canghe-skills/canghe-danger-x-to-markdown/EXTEND.md         │ 项目目录 │
├────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.canghe-skills/canghe-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)" — ~/.canghe-skills/ (all projects)
"Project" — .canghe-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 — 标题: "媒体"，问题: "如何处理推文中的图片和视频?"

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

问题2 — 标题: "输出"，问题: "默认输出目录?"

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

问题3 — 标题: "保存"，问题: "偏好设置保存位置?"

"User (Recommended)" — ~/.canghe-skills/（所有项目通用）
"Project" — .canghe-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}.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"
---

内容...

文件结构:

x-to-markdown/{username}/{tweet-id}.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中的远程媒体URL（图片/视频链接中的
```
https://
```
）
未找到远程媒体 → 完成，无需提示
找到远程媒体 → 使用
```
AskUserQuestion
```
:
- 标题: "媒体"，问题: "是否下载N张图片/视频到本地文件?"
- "Yes" — 下载到本地目录
- "No" — 保留远程URL
用户确认后 → 再次使用
```
--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进行自定义配置。详见偏好设置部分的路径和支持选项。