@topmindspace/topmind-writing-skills 0.7.1

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

@@ -0,0 +1,85 @@
+# 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-from 公众号稿.md`，
+  从源 md 的 `![]()` 按文档顺序自动取图；**禁止手工拼 `--images` 顺序**
+  （文件名数字排序 ≠ 文档顺序，2026-10-01 九月全景曾因此从第六节起整段错位）。
+  无源可派生的纯 X 原创稿才允许 `--images` 手工传参，且须逐张核对。
+  脚本内置校验：`[图N]` 须连续编号且数量 = 图片数，否则报错退出。
+- `--cover` 只做页顶预览 + 下载，**不占 `[图N]` 编号**
+- 配图建议先压缩到宽 900px 左右的 JPEG（单张 <100KB），11 张图总 HTML 约 800KB，
+  直接双击打开不卡
+- 下载按钮用 JS 取同图 `src` 触发下载，data-URI 在 HTML 里只存一份（体积减半）
+
+## 点击放大（lightbox）
+
+- 正文每张配图、封面预览图均可点击，弹出全屏 lightbox 放大查看原图
+- lightbox 内提供「新标签页打开原图」（Blob URL，绕开浏览器对 data: URL 顶层导航的限制）、
+  「下载原图」按钮；**刻意不拦截右键菜单**，放大后可右键图片另存，或直接截图
+- lightbox 位于 `#article` 之外，「一键复制全文」不会把它带入剪贴板
+
+## 复制行为
+
+- 「一键复制全文」：`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 逐块转换

package/topmind-x-article/scripts/audit_css.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""CSS 审计：本组技能无 CSS 资产；若未来加入 .css 文件，则做括号配平基础检查。"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = ROOT.name
+errors: list[str] = []
+
+
+def main() -> None:
+    print(f"[audit_css] {NAME}")
+    css_files = [p for p in ROOT.rglob("*.css") if ".git" not in p.parts and "dist" not in p.parts]
+    if not css_files:
+        print("  ✓ 无 CSS 资产，跳过")
+        print(f"\n[audit_css] {NAME}: 通过")
+        return
+    for css in css_files:
+        text = css.read_text(encoding="utf-8")
+        balanced = text.count("{") == text.count("}")
+        print(("  ✓ " if balanced else "  ✗ ") + f"{css.name} 括号配平")
+        if not balanced:
+            errors.append(css.name)
+    if errors:
+        print(f"\n[audit_css] {NAME}: {len(errors)} 项失败")
+        sys.exit(1)
+    print(f"\n[audit_css] {NAME}: 全部通过")
+
+
+if __name__ == "__main__":
+    main()

package/topmind-x-article/scripts/audit_docs.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""文档审计：references 完整性与内部链接可达性（任一不过 → 退出码 1）。"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = ROOT.name
+errors: list[str] = []
+
+
+def check(cond: bool, msg: str) -> None:
+    print(("  ✓ " if cond else "  ✗ ") + msg)
+    if not cond:
+        errors.append(msg)
+
+
+def main() -> None:
+    print(f"[audit_docs] {NAME}")
+    md_files = [p for p in ROOT.rglob("*.md") if ".git" not in p.parts and "dist" not in p.parts]
+    check(len(md_files) >= 2, f"md 文档 ≥2（实 {len(md_files)}，含 SKILL.md/README.md）")
+
+    refdir = ROOT / "references"
+    if refdir.is_dir():
+        refs = sorted(refdir.glob("*.md"))
+        check(len(refs) >= 1, f"references/*.md ≥1（实 {len(refs)}）")
+        for md in refs:
+            check(md.stat().st_size > 0, f"references/{md.name} 非空")
+
+    for md in md_files:
+        text = md.read_text(encoding="utf-8")
+        rel = md.relative_to(ROOT).as_posix()
+        for link in set(re.findall(r"\]\(([^)]+)\)", text)):
+            if link.startswith(("http://", "https://", "#", "mailto:")):
+                continue
+            target = (md.parent / link.split("#")[0]).resolve()
+            if link and not target.exists():
+                # 允许指向脚本/资源等非 md 文件的相对链接缺失检查放宽到 md
+                if target.suffix == ".md":
+                    check(False, f"{rel} 悬空链接: {link}")
+    check(True, "内部 md 链接可达")
+
+    # 反引号代码引用中的路径可达（审计 轻微-15 门禁盲区：之前只查 [text](path) 形式，
+    # `references/pan-style.md` 这类反引号引用曾漏网）。抓取反引号内的 references/*.md
+    # 与 scripts/* 路径并校验存在；glob/占位符写法（* ? < > |）跳过。
+    backtick_path_re = re.compile(r"(references|scripts)/([\w.\-/]+)")
+    line_suffix_re = re.compile(r":\d+(?:-\d+)?$")
+    backtick_bad = 0
+    for md in md_files:
+        text = md.read_text(encoding="utf-8")
+        rel = md.relative_to(ROOT).as_posix()
+        for span in set(re.findall(r"`([^`]+)`", text)):
+            for kind, p in backtick_path_re.findall(span):
+                p = line_suffix_re.sub("", p)
+                if not p or any(c in p for c in "*?<>|"):
+                    continue
+                target = md.parent / kind / p
+                if not target.exists():
+                    target = ROOT / kind / p
+                if not target.exists():
+                    backtick_bad += 1
+                    check(False, f"{rel} 反引号引用不可达: `{kind}/{p}`")
+    check(backtick_bad == 0, f"反引号内 references/scripts 引用可达（扫描 {len(md_files)} 个 md 文件）")
+
+    if errors:
+        print(f"\n[audit_docs] {NAME}: {len(errors)} 项失败")
+        sys.exit(1)
+    print(f"\n[audit_docs] {NAME}: 全部通过")
+
+
+if __name__ == "__main__":
+    main()

package/topmind-x-article/scripts/audit_skill.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""技能入口审计：SKILL.md 结构完整性（任一不过 → 退出码 1）。"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = ROOT.name
+errors: list[str] = []
+
+
+def check(cond: bool, msg: str) -> None:
+    print(("  ✓ " if cond else "  ✗ ") + msg)
+    if not cond:
+        errors.append(msg)
+
+
+def main() -> None:
+    print(f"[audit_skill] {NAME}")
+    text = (ROOT / "SKILL.md").read_text(encoding="utf-8")
+
+    m = re.search(r"^triggers:\s*\n((?:  - .+\n?)+)", text, re.M)
+    triggers = re.findall(r"^  - (.+)$", m.group(1), re.M) if m else []
+    check(len(triggers) >= 1, f"triggers ≥1（实 {len(triggers)}）")
+
+    check("When NOT to use" in text or "何时不用" in text, "含 When NOT to use / 何时不用")
+
+    has_workflow = bool(re.search(r"工作流|Workflow|用法|Usage", text))
+    check(has_workflow, "含工作流/用法说明")
+
+    fm = re.match(r"^---\r?\n([\s\S]*?)\r?\n---", text)
+    desc = ""
+    if fm:
+        dm = re.search(r'^description:\s*"([^"]*)"\s*$', fm.group(1), re.M)
+        if dm:
+            desc = dm.group(1).strip()
+        else:
+            dm = re.search(r"^description:\s*>\-\s*\n((?:[ \t]+.*\n?)+)", fm.group(1), re.M)
+            if dm:
+                desc = " ".join(l.strip() for l in dm.group(1).splitlines())
+    check("Use when" in desc or "用" in desc, "description 含使用场景")
+    check("Do NOT use" in desc or "不用" in desc, "description 含不适用场景")
+    check(len(desc) <= 1024, f"description ≤1024（实 {len(desc)}）")
+
+    if errors:
+        print(f"\n[audit_skill] {NAME}: {len(errors)} 项失败")
+        sys.exit(1)
+    print(f"\n[audit_skill] {NAME}: 全部通过")
+
+
+if __name__ == "__main__":
+    main()

package/topmind-x-article/scripts/audit_styles.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""样式资产审计：主题/风格资源有效性（任一不过 → 退出码 1）。
+
+本组技能无 CSS 样式表：若存在 assets/themes/*.json 则校验 JSON 可解析；
+references 风格文档非空（已由 audit_docs 覆盖，此处做存在性断言）。
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = ROOT.name
+errors: list[str] = []
+
+
+def check(cond: bool, msg: str) -> None:
+    print(("  ✓ " if cond else "  ✗ ") + msg)
+    if not cond:
+        errors.append(msg)
+
+
+def main() -> None:
+    print(f"[audit_styles] {NAME}")
+    themes = sorted((ROOT / "assets" / "themes").glob("*.json")) if (ROOT / "assets" / "themes").is_dir() else []
+    if themes:
+        for t in themes:
+            try:
+                json.loads(t.read_text(encoding="utf-8"))
+                check(True, f"assets/themes/{t.name} JSON 可解析")
+            except (OSError, json.JSONDecodeError) as e:
+                check(False, f"assets/themes/{t.name} 解析失败: {e}")
+    else:
+        check(True, "无主题 JSON 资产（本技能不依赖主题文件）")
+
+    refdir = ROOT / "references"
+    has_style_doc = refdir.is_dir() and any(refdir.glob("*.md"))
+    check(has_style_doc, "references 风格/格式文档存在")
+
+    if errors:
+        print(f"\n[audit_styles] {NAME}: {len(errors)} 项失败")
+        sys.exit(1)
+    print(f"\n[audit_styles] {NAME}: 全部通过")
+
+
+if __name__ == "__main__":
+    main()