# Rokid Article Publisher

> 将 Word、TXT、Markdown 或 HTML 图文稿发布到 Rokid 论坛，保留配图位置与正文格式，修复原帖缺图和标题排版，并在保存后刷新核对。不用于 AIUI 应用打包或平台提审。

- Skill: `easonzhu1997/rokid-article-publisher` (Agent Skill, multi-file: 21 files)
- Install (CLI): `npx get-skill add easonzhu1997/rokid-article-publisher`
- Raw SKILL.md: https://api.skillmd.com/api/skills/easonzhu1997/rokid-article-publisher/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: EasonZhu1997 (https://skillmd.com/u/easonzhu1997)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/easonzhu1997/rokid-article-publisher

---


# Rokid 图文发布

交付的是目标帖子中可阅读、图片位置正确且已保存的文章。编辑器里暂时出现图片、上传返回一个地址、看到成功提示，分别都不足以证明这个结果。

## 先确定此次改动

- 确认用户指定的源稿及目标：修改既有帖子，还是创建新帖子。既有帖从其详情页进入编辑；不要另发一篇来替代修复。
- 用户已明确授权该目标的修改保存或新帖发布时，校验通过后继续执行，不重复索取同一授权。仅要求检查、预览或整理技能，不等于授权线上保存或发布。
- 保存前记录现有标题、正文、图片顺序和必要发布字段。图片修复以线上现有正文为基线，用 Word 确定缺图及位置；保留用户在线上的手工改动。只有用户要求同步整稿时才整体采用源稿正文。
- 缺少登录状态时让用户在浏览器完成登录；不得将账号、密码、Cookie 或签名地址写入可分享技能。必填发布资料无法从用户要求和现有状态确定时，完成其他准备后停在该项，不编造资料。

浏览器工作前阅读 [编辑器操作与校验](references/rokid-editor.md)。所有线上写入经当前工具支持的 CUA 用户界面完成；先读工具返回的实际能力文档。DOM `evaluate` 仅作只读检查，不用它改变正文、触发隐藏接口或调用编辑器内部状态。

## 按源文件选择路线

- `.txt` 默认按纯文本保真：先读 [富文本转入](references/richtext.md)，运行 `render_richtext.py --literal-txt`，不把 `#`、反引号或图片写法当作 Markdown。原空格、制表符与空行有独立基线；无需图片主机授权或 Markdown 依赖。
- `.md` / `.markdown`：先读 [文本预处理](references/text-input.md)，运行 `prepare_text.py`。解决 `blocking_issues`，按 [MD 图片回填](references/md-image-mapping.md) 原生上传和回填，再读 [富文本转入](references/richtext.md)，生成可检查的 HTML。只有用户确认 TXT 实际采用 Markdown 语法时才用 `--txt-as-markdown`。
- `.docx` 或已有 HTML：继续使用下方 Word 清单与原 `fill_image_map.py` 路线，不因新增格式而转换或覆盖旧稿。

两套清单不可混用：Markdown 使用 `{{RK_IMAGE_0001}}`、`prepare_text.py` 清单、`finalize_images.py`；Word/HTML 使用 `{{IMAGE_1}}`、`docx_inventory.py` 清单、`fill_image_map.py`。禁止改几个字段强行互转。

Markdown 的图片主机默认全部拒绝；每个主机须来自本次论坛原生上传并实际显示，分别向 `finalize_images.py` 和 `render_richtext.py` 传入同一精确小写 `--allow-host`，不自动信任 Rokid、其他平台或云存储的整域及子域。没有图片时不需要该参数，也可用空对象映射完成回填。

Rokid 的历史粘贴过滤曾清理包在 `<p>` 内的图。MD 渲染器按解析后的 token 只把顶层、单图、独立图片段转为正文顶层 `<img width="100%">`，保留 alt/title、顺序和邻接图注。混排、链接包图、列表、引用、表格中的图片会明确阻断；先在经核对的副本规范结构，或用原生编辑器逐块插入，不任意拆开改变含义。MD 源码或图片占位稿不能直接当成已经排好版的正文发布。

## Word / HTML 源稿与图片清单

Word 可以用本技能的标准库脚本提取图片和相邻正文：

```bash
python3 scripts/docx_inventory.py --source article.docx --out extracted-article
```

输出 `manifest.json` 与 `media/`。清单记录每次图片出现的位置；相同图片可多次出现，不能把媒体去重数量当作正文应有图片数量。正文表格内的段落也按 XML 阅读顺序记录。浮动图、缺失引用、外链和未知尺寸会产生警告；图注只是候选，须结合源稿与上下文核对。

已有 HTML 稿也应建立同样的 occurrence 清单。不要因为旧稿里有图片地址就认为已上传：检查是否为占位符、临时地址或其他网站的外链。

## 原生上传与归位

1. 从论坛原生图片入口上传本地文件。当前环境若文件选择器不可用，可改用受支持的二进制图片剪贴板和正常粘贴；具体调用方式以当前 CUA 文档为准。
2. 每次或每批上传前后记录新增图片及地址，建立源图片序号到论坛原生托管地址的映射。批量完成顺序可能变化，不能按返回顺序配图。不能使用其他内容平台的热链代替上传。
3. 按源稿的图片位置、图注和前后文归位。候选锚点重复时先消歧；仍无法唯一确定就停下，不猜位置。
4. 若需要准备兼容的富文本片段，当前已验证的形式是正文层级的 `<img width="100%">`。图片套在 `<p>` 等容器中曾被粘贴过滤；先做小范围兼容验证，再处理全文。不要凭旧经验断定所有编辑器版本行为相同。
5. Word/HTML 路线用纯本地助手替换已确认位置的 `{{IMAGE_1}}` 等占位符。它只改图片 `src`，保留其他 HTML 字符；不会上传、保存或发布。Markdown 路线改用 [MD 图片回填](references/md-image-mapping.md)，不调用此助手。

```bash
python3 scripts/fill_image_map.py \
  --template article-template.html \
  --manifest extracted-article/manifest.json \
  --uploads native-uploads.json \
  --allowed-origin https://forum.example.invalid \
  --out prepared-article
```

示例域名必须换成从本次论坛原生上传实际观察到的 origin；不能把其他平台域名列入白名单来绕过上传。映射格式、模板约束和助手的校验范围见 [编辑器操作与校验](references/rokid-editor.md#离线模板与映射)。

## 恢复文章层级

当用户要求排版修复时，从源稿恢复标题层级、正文、图注、列表和原生代码块，不重命名标题。段落字号不同不能代替 `h1/h2/h3` 语义层级。字体样式应适合当前稿件；检查实际渲染字号和粗细，不仅检查写入的 HTML。

代码的换行和引号只能依据明确的源稿与局部差异恢复。源稿与线上手工修改冲突时保留已确认的手工改动；不要通过全局删除空白或统一引号来宣称语义未变。字号修复仍应复核全部图片的 URL、顺序和图注关系。

## 保存和刷新验证

- 对照基线检查：要求保留的正文、链接、标题和代码是否保留，目标图片是否齐全且处于正确位置。
- 依据已有明确授权，点击实际目标的保存修改或发布按钮。平台拒绝、字段缺失、登录失效或安全验证出现时记录具体状态，不连续盲点。
- 返回正确详情页并刷新，检查正文图片加载完成且自然尺寸非零；逐图核对映射与位置，检查标题字号、正文、图注和代码块。可恢复的显示或保存问题继续在原帖内修复。
- 最终说明真实状态：已保存并刷新确认、已提交待审核、或仍缺哪一项。检查不到的内容不能写成已验证。不能取得线上图片二进制时，说明身份核对基于原生上传记录、尺寸和可见内容，不宣称线上 SHA-256 一致。

## 离线自检

```bash
python3 -B -m unittest discover -s scripts -p 'test_*.py' -v
```

脚本最低 Python 3.9；Word、TXT、MD 预处理和图片回填使用标准库。仅 MD 转富文本需要 `requirements-render.txt` 中的 `markdown-it-py`；缺依赖的对应测试会跳过，不能把跳过汇报成通过。可选测试依赖及验证范围见 [验证记录](references/validation.md)。

测试仅使用临时目录里的合成文档和示例域名，不触碰论坛账号或真实帖子。技能包只保留通用脚本和说明，不收入运行时正文、图片、截图、上传映射或浏览器快照。