# X Article Editor — API for agents

把 Markdown 变成能直接粘进 X(Twitter) Article 的排版内容。

X 的 Article 编辑器基于 Draft.js，粘贴时会按白名单过滤：不在名单里的块一律降级成
普通段落，行内样式和实体也会被裁掉。直接把 Markdown 或富文本粘过去，格式必然走样。
这个服务按那份白名单做转换，所以粘过去不走样。

Base URL: https://xarticleeditor.vercel.app

---

## 你多半想要的：POST /api/draft

写完文章调这个，把返回的 `url` 交给用户。用户点开就是排好版的编辑器，
按「复制全文」再到 X 里 Cmd/Ctrl+V 即可。

请求：
    POST /api/draft
    Content-Type: application/json
    { "markdown": "# 标题\n\n正文…", "title": "可选，文章标题" }

返回：
    {
      "url": "https://xarticleeditor.vercel.app/#d=…",
      "steps": 3,
      "hasImages": false,
      "warnings": [ { "code": "...", "message": "..." } ]
    }

文章内容压缩后放在 URL 的 `#` 之后。fragment 浏览器不会发给服务器，
所以正文不落盘、不进日志、不经过我们这边。

curl 示例：
    curl -X POST https://xarticleeditor.vercel.app/api/draft \
      -H 'Content-Type: application/json' \
      -d '{"markdown":"# Hello\n\nThis is **bold**."}'

---

## 你能自己操作剪贴板时：POST /api/convert

同样的输入，返回可直接写进剪贴板的内容。

返回：
    {
      "html":     "写进剪贴板的 text/html，粘进 X Article 不走样",
      "text":     "纯文本回退，写进剪贴板的 text/plain",
      "segments": [ … 见下 … ],
      "warnings": [ … ],
      "url":      "同一篇的编辑器链接"
    }

注意：剪贴板在用户本机。服务端碰不到，也无法替用户按 Cmd+V。
只有当你自己运行在用户机器上（比如本地跑的 Claude Code / Codex）才写得了剪贴板。

---

## segments：为什么不是一段就完事

X Article 里图片和分割线是 atomic block，**无法随 HTML 一起粘贴**——
真粘过去，图片会变成一个字面的 📷 字符，分割线直接消失。
所以整篇被切成有序的 segments，按顺序处理：

    { "kind": "html",    "html": "<h1>…</h1><p>…</p>", "text": "…" }
    { "kind": "image",   "src": "https://…", "alt": "…" }
    { "kind": "divider" }

- `html`    → 粘贴这段
- `image`   → 用户在 X 里手动插图（X 只接受剪贴板里的图片文件，不吃 img 标签）
- `divider` → 用户在 X 里点「插入 → 分割线」

只有纯文字的文章，segments 只有一条，一次粘贴就完成。

---

## X Article 实际支持什么

能随 HTML 粘过去的：
  一级标题、二级标题、正文段落、引用、有序列表、无序列表
  粗体、斜体、删除线、超链接

粘不过去的（X 里有这些功能，但只能手动插入）：
  图片、GIF、嵌入推文、链接预览、代码块、LaTeX、表格、分割线

会被丢弃或降级的：
  H3 及以下 → 降级为加粗正文
  下划线、行内代码 → 丢样式保文字
  嵌套列表 → 拍平成一层
  空行 → 需要特殊字符才能保住（转换已自动处理）

---

## 约束

- 单篇 markdown 上限 400 KB
- 无需鉴权，CORS 全开
- 纯计算，不存储任何内容
- GET 任一端点会返回它自己的用法说明