@topmindspace/tms-skills 0.4.1 → 0.5.0

package/topmind-x-article/README.en.md

@@ -4,7 +4,7 @@
 
 Turn a Markdown draft into a "copy → paste → publish" X long-form (Article) package.
 
-- Version: **v0.1.0** (same tag as `@topmindspace/tms-skills@0.4.1`)
+- Version: **v0.2.0** (same tag as `@topmindspace/tms-skills@0.5.0`)
 
 ## Install
 
@@ -15,17 +15,37 @@ npx @topmindspace/tms-skills install topmind-x-article
 ## Usage
 
 ```bash
-# 1. Draft → paste-ready plain text (the heart of one-click copying)
+# 1. Draft → one-click-copy HTML (preferred)
+python3 scripts/md2x-html.py <draft>.md --out <package>/X长文.html \
+  --images <img1> <img2> ... [--cover cover-1200x675.png]
+# Open X长文.html in a browser → click the top 「一键复制全文」 button → paste into the X Article editor body
+# (the first # heading is excluded from the clipboard — fill it into X's title field by hand;
+#  upload the cover separately via X's dedicated cover entry)
+
+# 2. Plain-text fallback (when HTML copying misbehaves)
 python3 scripts/md2x.py <draft>.md --out <package>/X发布稿.txt
 
-# 2. Cover: generate a 1200×675 cover with topmind-cover
+# 3. Cover: generate a 1200×675 cover with topmind-cover
 
-# 3. Follow references/publish-checklist.md item by item
+# 4. Follow references/publish-checklist.md item by item
 ```
 
 ## Conversion rules
 
-The X Article editor has weak, unstable markdown support, so `md2x.py` converts to plain text per `references/x-format.md`: headings → plain text lines, horizontal rules → blank lines, emphasis markers removed, links → `text（url）`, images → `[图N]` (image list appended at the end), tables → "label：value" lists, blockquotes unquoted, `\` escapes restored.
+The HTML path follows `references/x-html-format.md`: rich-text paste into the X editor
+(headings/bold/links/lists/quote blocks preserved); ` ``` ` prompt blocks render as quote
+blocks with a 「复制提示词」 copy button; GFM tables become lists (X drops `<table>` on paste);
+the first `#` heading is excluded from the clipboard; images are base64-inlined and numbered
+`[图N]`, with per-image 「下载图片」 download buttons as fallback upload.
+
+Prompt copying is dual-channel: the author side uses the 「复制提示词」 button in the HTML
+(to grab the text before publishing); the reader-side one-click copy can only come from X
+native code blocks (convert each block by hand via Insert → Code — native code blocks carry a
+native copy button, while pasted `<pre>` is discarded by X).
+
+The plain-text fallback follows `references/x-format.md`: headings → plain text lines,
+horizontal rules → blank lines, emphasis markers removed, links → `text（url）`, images →
+`[图N]` (image list appended at the end), tables → "label：value" lists, blockquotes unquoted.
 
 Read the result through once by hand after converting.
 

package/topmind-x-article/README.md

@@ -4,7 +4,7 @@
 
 把 Markdown 原稿变成"复制 → 粘贴 → 发"的 X 长文（Article）发布包。
 
-- 版本：**v0.1.0**（与 `@topmindspace/tms-skills@0.4.1` 同 tag）
+- 版本：**v0.2.0**（与 `@topmindspace/tms-skills@0.5.0` 同 tag）
 
 ## 安装
 
@@ -15,21 +15,34 @@ npx @topmindspace/tms-skills install topmind-x-article
 ## 用法
 
 ```bash
-# 1. 原稿转可粘贴纯文本（一键复制的核心）
+# 1. 原稿转一键复制 HTML（首选）
+python3 scripts/md2x-html.py <原稿>.md --out <包>/X长文.html \
+  --images <图1> <图2> ... [--cover cover-1200x675.png]
+# 浏览器打开 X长文.html → 点页顶「一键复制全文」→ 粘贴进 X Article 编辑器正文
+# （首个 # 标题不进剪贴板，手动填入 X 标题栏；封面在 X 独立入口单独上传）
+
+# 2. 纯文本兜底（HTML 复制异常时）
 python3 scripts/md2x.py <原稿>.md --out <包>/X发布稿.txt
 
-# 2. 封面图：用 topmind-cover 生成 1200×675
+# 3. 封面图：用 topmind-cover 生成 1200×675
 
-# 3. 按 references/publish-checklist.md 逐项发布
+# 4. 按 references/publish-checklist.md 逐项发布
 ```
 
 ## 转换规则
 
-X Article 编辑器对 markdown 支持弱且不稳定，`md2x.py` 按 `references/x-format.md`
-转纯文本：标题→纯文本行、分隔线→空行、加粗/斜体/行内代码去标记、链接→`文字（url）`、
-图片→`[图N]`（文末附配图清单）、表格→"项：值"列表、引用去 `>`、`\\` 转义还原。
+HTML 链路按 `references/x-html-format.md`：富文本粘贴进 X 编辑器（标题/加粗/链接/
+列表/引用块保留）；` ``` ` 提示词块渲染为引用块 + 「复制提示词」按钮；GFM 表格转列表
+（X 粘贴丢弃 `<table>`）；首个 `#` 标题不进剪贴板；配图 base64 内嵌、按 `[图N]` 编号，
+带不入编辑器时用图下「下载图片」按编号上传。
+
+提示词的复制分双通道：作者侧用 HTML 里的「复制提示词」按钮（发布前取用文本）；
+读者侧一键复制只能来自 X 原生代码块（Insert → Code 手动逐块转换；原生代码块带
+native copy button，粘贴 `<pre>` 会被 X 丢弃，走不过去）。
 
-转完必须人工通读一遍。
+纯文本兜底按 `references/x-format.md`：标题→纯文本行、分隔线→空行、加粗/斜体/
+行内代码去标记、链接→`文字（url）`、图片→`[图N]`（文末附配图清单）、表格→"项：值"列表、
+引用去 `>`。转完必须人工通读一遍。
 
 ## 最小示例
 

package/topmind-x-article/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: topmind-x-article
-version: 0.1.0
-description: "X 长文（Article）一键发布：Markdown 原稿 → 可直接粘贴的 X发布稿.txt + 封面图 + 发布清单。沉淀自实战。Use when X 长文、发 X 文章、X article、长文发 X。Do NOT use for 短推文（→ topmind-x）、公众号（→ topmind-wechat-post）。"
+version: 0.2.0
+description: "X 长文（Article）一键发布：Markdown 原稿 → 可直接复制的 X长文.html（富文本一键复制+配图内嵌）/ X发布稿.txt + 封面图 + 发布清单。沉淀自实战。Use when X 长文、发 X 文章、X article、长文发 X。Do NOT use for 短推文（→ topmind-x）、公众号（→ topmind-wechat-post）。"
 action_category: write
 triggers:
   - X 长文
@@ -12,6 +12,7 @@ triggers:
   - 转纯文本
   - X 纯文本
   - 发 article
+  - 一键复制
 triggers_cn:
   - 写 X 长文
   - X 长文发布
@@ -28,30 +29,48 @@ updated: 2026-09-29
 把一篇 Markdown 原稿变成"复制 → 粘贴 → 发"的 X 长文发布包。
 
 ```
-原稿.md → md2x.py → X发布稿.txt → 封面图(topmind-cover) → 发布清单 → 人工粘贴发布
+原稿.md → md2x-html.py → X长文.html（一键复制全文+配图）→ 封面图(topmind-cover) → 发布清单 → 人工粘贴发布
+原稿.md → md2x.py     → X发布稿.txt（纯文本兜底）
 ```
 
 ## 工作流
 
-1. **转文本**（一键复制的核心）：
+1. **转 HTML**（一键复制的核心，首选）：
    ```bash
-   python3 scripts/md2x.py <原稿>.md --out <包>/X发布稿.txt
+   python3 scripts/md2x-html.py <原稿>.md --out <包>/X长文.html \
+     --images <图1> <图2> ... [--cover cover-1200x675.png]
    ```
-   转换规则见 `references/x-format.md`。转完**通读一遍**：X 不渲染 markdown，
-   标记剥离后断句、 emphasis 全靠文字本身，读不顺就回原稿改。
-2. **封面图**：调 `topmind-cover`，平台选 `x`，得 1200×675 主图。
-3. **发布清单**：按 `references/publish-checklist.md` 逐项过。
-4. **发布**：用户在 X Article 编辑器粘贴 `X发布稿.txt` 全文、上传封面与配图，
+   单文件 HTML：内联样式 + 配图 base64 内嵌。浏览器打开后点页顶
+   「一键复制全文」，富文本（含格式）进剪贴板，去 X 文章编辑器粘贴。
+   转换规则见 `references/x-html-format.md`。
+   - `#` 首个标题**不进剪贴板**：手动填入 X 标题栏（工具栏有三步话术提示）。
+   - 每张配图自动编号 `[图N]`；图片 data-URI 内嵌，能随粘贴带入编辑器最好，
+     带不进去时用图下「下载图片」按钮按编号下载再上传——不用找文件、不用对顺序。
+   - 每个 ``` 提示词块渲染为引用块（X 可识别）+ 右上角「复制提示词」按钮，
+     一键复制该块纯文本。**复制分双通道**：作者侧用 HTML 里的按钮（发布前取用文本）；
+     读者侧一键复制只能来自 X 原生代码块，需在编辑器里 Insert → Code 手动逐块转换
+     （X 原生代码块带 native copy button；粘贴 `<pre>` 会被 X 丢弃，走不过去）。
+     详见 `references/x-html-format.md`「提示词的复制链路（双通道）」。
+   - 封面走 `--cover` 只在页顶预览 + 提供下载；**封面始终在 X 编辑器单独上传**
+     （X 有独立封面入口）。
+2. **转纯文本**（兜底）：`python3 scripts/md2x.py <原稿>.md --out <包>/X发布稿.txt`，
+   规则见 `references/x-format.md`。HTML 复制异常时的备用入口。
+   转完**通读一遍**：X 不渲染 markdown，标记剥离后断句、emphasis 全靠文字本身，
+   读不顺就回原稿改。
+3. **封面图**：调 `topmind-cover`，平台选 `x`，得 1200×675 主图。
+4. **发布清单**：按 `references/publish-checklist.md` 逐项过。
+5. **发布**：用户在 X Article 编辑器粘贴全文、上传封面与配图（按 `[图N]` 编号），
    人工点发布。**API 不发长文**（topmind-x 的 xurl 只覆盖短推文）。
-5. **收尾**：记录发布时间与链接；全文抓回核对一遍（标题、数字、图序）。
+6. **收尾**：记录发布时间与链接；全文抓回核对一遍（标题、数字、图序）。
 
 ## 目录约定
 
 ```
 <包>/
 ├── 原稿.md            # 输入（或复用既有原稿）
-├── X发布稿.txt        # 唯一复制入口：一键全选复制
-├── cover-1200x675.png # 封面（topmind-cover 产出）
+├── X长文.html         # 首选复制入口：浏览器打开，一键复制全文
+├── X发布稿.txt        # 纯文本兜底入口
+├── cover-1200x675.png # 封面（topmind-cover 产出，X 编辑器单独上传）
 └── 发布清单.md        # 本次发布 checklist（含时间、链接）
 ```
 
@@ -60,6 +79,11 @@ updated: 2026-09-29
 - 补充信息（邀请码、链接、勘误）**不挤正文**，发在发布后首条评论并置顶
 - 标题 ≤140 字符，首段 3 行内出钩子；配图逐张按 `[图N]` 顺序上传，传完对照清单点一遍
 - 事实修正只改发布包，不回头改已发原文（除非勘误）
+- 提示词密集型文章（如 N 条直出提示词），发布时建议把提示词引用块逐块转为
+  X 原生代码块（Insert → Code → 粘贴 → 删原块，每块约 10 秒）：这是 X 平台唯一可靠的
+  读者侧一键复制链路（原生代码块带 native copy button，已实测确认）
+- X 编辑器对剪贴板 data-URI 图片的处理不稳定：**文本格式一键复制可靠，
+  图片按"能带入则带入，带不入则按编号下载上传"处理**，不要承诺用户图片 100% 一键带图
 
 ## When NOT to use
 

package/topmind-x-article/package.json

@@ -1,6 +1,6 @@
 {
   "name": "topmind-x-article",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": true,
   "description": "X 长文（Article）一键发布：Markdown 原稿转可直接粘贴的纯文本 + 封面图 + 发布清单。",
   "license": "MIT",

package/topmind-x-article/references/publish-checklist.md

@@ -4,16 +4,23 @@
 
 ## 发布前
 
-- [ ] `X发布稿.txt` 通读一遍：断句顺、无 markdown 残留标记
+- [ ] `X长文.html` 浏览器打开一遍：「一键复制全文」按钮可用、配图 11 张按序显示、
+      每个提示词块右上角「复制提示词」可用、封面预览 + 下载正常
+- [ ] `X发布稿.txt` 通读一遍：断句顺、无 markdown 残留标记（HTML 复制异常时的兜底）
 - [ ] 标题 ≤140 字符；首段 3 行内出钩子
 - [ ] 承重数字与原稿一致（转格式不改数字）
 - [ ] 封面图 1200×675 已备好，标题字无错别字
 - [ ] 配图按 `[图N]` 顺序排好，清单与文件一一对应
 - [ ] 话题标签想好（放文末，不超过 3 个）
+- [ ] 提示词密集型文章：规划好哪些提示词块要在 X 里转原生代码块
+      （Insert → Code，读者侧一键复制的唯一链路；纯展示、无需取用的可跳过）
 
 ## 发布时
 
-- [ ] 全文粘贴 → 封面上传 → 配图逐张按序插入
+- [ ] 一键复制全文 → X 文章编辑器粘贴 → 封面单独上传 → 配图按 `[图N]` 编号插入
+      （图片若随粘贴带入则跳过上传；带不入则用图下「下载图片」按编号下载再上传）
+- [ ] （提示词类文章推荐）提示词引用块逐块转 X 原生代码块，得读者侧一键复制：
+      HTML 里点该块「复制提示词」→ X 编辑器对应位置 Insert → Code → 粘贴 → 删除原引用块
 - [ ] 预览一遍：图序、段落、标题
 
 ## 发布后

package/topmind-x-article/references/x-html-format.md

@@ -0,0 +1,73 @@
+# x-html-format.md · md2x-html.py 转换规则
+
+`scripts/md2x-html.py` 把 Markdown 原稿转成**单文件 HTML**（内联样式 + 图片 base64 内嵌，
+无外部依赖），浏览器打开即用。对标 `md2wechat` 的公众号体验：页顶「一键复制全文」。
+
+## X 文章编辑器语法（调研结论）
+
+以 X 发文工具实测为准（x-md-to-article 等，2026-09-29 调研）：
+
+| 原稿元素 | HTML 输出 | 粘贴进 X 后的表现 |
+|---|---|---|
+| `#`（首个） | `h1.no-paste`（页面展示） | **不进剪贴板**：手动填入 X 标题栏 |
+| `##` / `###` | `h2` / `h3` | X 原生"标题 / 副标题"两级 |
+| 段落（`**粗体**`、`` `代码` ``、裸链接） | `p`（strong/code/a 保留） | 原生富文本；行内 code 变纯文本；链接保留 |
+| `- ` / `1. ` | `ul` / `ol` | 原生列表 |
+| `> ` | `blockquote` | 原生引用块 |
+| ``` 围栏（直出提示词） | `div.prompt > blockquote > code` + 「复制提示词」按钮 | 原生引用块。**粘贴流到此为止**：X 不识别粘贴的 `<pre>` 为代码块；读者侧一键复制只能来自 X 原生代码块（Insert → Code 手动建），见下节「提示词的复制链路（双通道）」 |
+| `---` | `hr` | 可能被丢弃 → 发布时手动 Insert → 分割线 |
+| GFM 表格 | `ul.xtable`（表头加粗首项） | **X 粘贴会丢弃 `<table>`**，转列表保内容；如需原生表格，走 X 的 Insert → 表格手动建 |
+| `[图N]` 独占一行 | `<figure>`：内嵌 data-URI 图片 + `[图N]` 编号 + 「下载图片」按钮 | 图片随粘贴带入不稳定，保底按编号下载上传 |
+| 封面 `--cover` | 页顶预览 + 下载（`.no-paste`） | 始终在 X 编辑器独立封面入口单独上传 |
+
+「复制全文」前 JS 自动剔除所有 `<button>` 与 `.no-paste` 块（标题、封面预览），
+剪贴板里只剩 X 可识别的语义标签：`h2/h3/p/ul/ol/blockquote/a/hr/img`。
+工具栏三步话术：**① 标题填入 X 标题栏 → ② 一键复制全文 → ③ 粘贴到 X 正文**。
+
+## 提示词的复制链路（双通道）
+
+核实结论（2026-09-29，两处独立实测一致）：
+
+- X 原生代码块（Insert → Code 插入）**带 native copy button**，读者侧可一键复制
+  （jpw-x-articles 真机验证原文："Code content and native copy buttons persist"）。
+- 围栏代码**只能**走 Insert → Code 对话框，"never relies on clipboard HTML round-tripping"；
+  粘贴 HTML 会丢弃 `<pre>`（x-md-to-article 实测笔记，2026-09-07）。
+
+因此提示词的"复制"分两段：
+
+- **通道 A（作者侧，发布前）**：`X长文.html` 里每个提示词块右上角「复制提示词」按钮，
+  一键复制该块纯文本。这是你粘贴发布时取用提示词文本的入口。
+- **通道 B（读者侧，发布后）**：X 编辑器里把提示词引用块手动转为原生代码块，
+  读者才能一键复制。操作（每块约 10 秒）：
+  1. 在 HTML 里点该块「复制提示词」（文本已进剪贴板）；
+  2. X 编辑器对应位置 Insert → Code，新建原生代码块，粘贴；
+  3. 删除原来的引用块（避免正文重复）。
+  提示词密集型文章（如 N 条直出提示词）建议逐块转换；纯展示、无需读者取用的代码可跳过。
+
+`X发布稿.txt` 里围栏已去标记、内容保留为纯文本，同样可作为通道 B 的文本来源。
+
+## 图片约定
+
+- `--images` 按顺序对应 `[图1]`、`[图2]`…；`--cover` 只做页顶预览 + 下载，**不占 `[图N]` 编号**
+- 配图建议先压缩到宽 900px 左右的 JPEG（单张 <100KB），11 张图总 HTML 约 800KB，
+  直接双击打开不卡
+- 下载按钮用 JS 取同图 `src` 触发下载，data-URI 在 HTML 里只存一份（体积减半）
+
+## 复制行为
+
+- 「一键复制全文」：`ClipboardItem` 同时写 `text/html` + `text/plain`，
+  富文本失败时自动降级纯文本
+- 「复制提示词」：`innerText`（HTML 实体自动解码，拿到的是干净纯文本）
+- 「下载图片/下载封面」：`a[download]` + data-URI，保底链路
+
+## 已知限制（写进发布话术，不要过度承诺）
+
+- 文本 + 格式一键复制可靠（富文本剪贴板，多家 X 发文技能同款做法）
+- 图片 data-URI 能否随粘贴带入 X 文章编辑器**不稳定**：
+  有成功案例，但更多实战采用"HTML 粘贴文本 + 图片按编号上传"。
+  话术固定为："能带入则带入，带不入则按编号下载上传"
+- 封面始终在 X 编辑器单独上传（X 有独立封面入口），HTML 里只预览
+- 分割线、代码块、表格三类 X 原生块**只能走 Insert 菜单**，粘贴流不承诺还原；
+  本链路已做最大兼容（引用块/列表/hr），剩余手动补。
+  其中代码块值得手动补：它是 X 侧唯一带读者一键复制（native copy button）的载体，
+  提示词类内容建议走「提示词的复制链路」通道 B 逐块转换