htmlrun-把本地 HTML 变成可分享的在线链接

概述

调用本 skill 自带的 htmlrun CLI（scripts/htmlrun.cjs，零依赖 Node 脚本，随本 skill一起分发，不需要单独安装）把 HTML 文件发布到 https://html.run ，返回可分享链接。

接口字段、错误码和限流以在线文档为准，本 skill 不再附带一份会过期的副本。CLI 报的错在下文对不上时，先读这一份，它由服务端现算，和线上接口是同一份：

https://html.run/api/docs/agent.md

给人看的页面是 https://html.run/api/docs/agent.html ，机器可读的 OpenAPI 是https://html.run/api/docs/agent.json 。

调用惯例：下文所有命令示例里的 htmlrun.cjs 都是node "<本 skill 目录>/scripts/htmlrun.cjs" 的简写。实际执行时请替换成真实的绝对路径，并用双引号包裹整个路径——Windows 路径可能带空格，skill 目录名也可能带中文，双引号在 cmd/PowerShell/bash 里规则一致，能一次性避开这些坑。

When to Use

• 用户明确要求把某个 HTML/Markdown 文件或代码片段发布成可访问的链接。
• 用户说"发布""上线""部署""发出去"等触发词，且上下文里有一个刚生成/编辑好的

HTML（或可以归一化成 HTML 的）内容。

• 用户发送 /html。后面若带着文件或代码，就发布那一份；只有 /html、眼前又没有

可发布的内容时，先问要发哪一页，不要自己编一页。

• 用户要更新一个之前已经发布过的页面内容。
• 页面需要保存登录用户自己的数据（刷题进度、记账、待办、抽卡记录），需要指导改造为

服务端存储时（见 §9）。

When NOT to Use

• 用户只是要本地预览效果，没有表达"分享给别人/要个链接"的意图。
• 要发布的东西是多个文件（整站目录、需要构建的源码工程）——本服务只支持**单文件

静态 HTML**，不支持整站/目录发布。源码工程、多页面站点等需求请如实告知用户当前不支持，不要勉强打包凑合或建议拆成多个链接。

• 页面要调用任意的自定义后端接口或数据库——本服务没有通用后端，只提供两种内置能力：

表单接管（数据交给作者）与页面数据存储（登录用户自己的数据，见 §9）。除此之外的服务端需求，请如实告知用户。

• 用户想要的是自定义域名、团队协作等本服务不提供的能力——如实说明不支持，不要

编造一个"办法"敷衍过去。

核心原则：相信 CLI 输出，不要抢先解释

CLI 的输出是设计给你直接转达用户的，不要自己总结、替换措辞或脑补原因，尤其是以下几类字段：

• 链接: 后面的 URL——原样发给用户，不要省略协议头，也不要"美化"成别的形式。
• 敏感词(N):——如果出现，原样报告命中了哪些词，不要自己揣测审核标准。
• ⚠ 已被限制访问——如果出现，说明页面当前对外不可见，如实告知，**不要说

"发布成功"**。

• 说明:——服务端给的补充说明（比如这次发布沿用了什么访问权限），原样转达。
• 指引: 以及后面的 ✓/✗/· 列表和 下次:——这是服务端专门给你的操作提示，

照着做，不要自己另外发挥一套说法。

链接一律从 CLI 输出里原文复制，不要凭记忆重新拼接。

凭据纪律

• token 明文（h_ 开头的字符串）禁止出现在你的回复、日志、命令输出转述、

代码注释或任何你写入磁盘的文件里。

• token 唯一合法的落地方式是让 CLI 自己写配置文件：--check 激活成功后自动

落盘、login --token 手工配置、--token flag 或 HTMLRUN_TOKEN 环境变量做一次性覆盖。

• 不要主动要求用户把 token 贴进对话框。如果用户已经贴出了 token，引导对方改成

直接执行 login --token <值>，然后在后续对话里忘掉这个值，不要复述它。

• 协助码（d_ 开头，见「7. AI 协助编辑」）同样按 token 对待：不复述、不写入文件。

它与 token 是两种权限完全不同的凭据，任何一个失效时都不要拿另一个去顶替。

1. 首次使用前检查

只在要发布时才需要这一步。 如果用户给的是协助码（d_ 开头，走「7. AI 协助编辑」），跳过本节直接去 §7 —— 那条路不需要激活，只要 Node 能跑就行。

要发布、且不确定本机是否已经激活过时，先跑一次：

htmlrun.cjs --check

这一条命令同时做了两件事：检查 Node 环境、检查激活状态。

• 如果这台机器上 node 命令都找不到，或者版本低于 16，脚本会打印类似

"Node 版本过低"的提示并退出。这种情况不要尝试用 pip install htmlrun-cli之类的方式兜底——那是上一代的分发方式，已经停止维护。二选一：

1. 引导用户去 https://nodejs.org 装一个 Node（LTS 版本即可，装完重开终端）；
2. 或者告诉用户可以直接去 https://html.run/web/artifacts 网页在线发布，不需要

任何本地环境。

• 如果 Node 环境正常，脚本会继续检查本机有没有已激活的 token：
  • 没有 → 自动发起激活，打印链接和二维码（进入下面"4. 激活"）；
  • 有 → 校验这个 token 是否仍然可用。可用就静默退出、没有任何输出——这是

正常现象，说明已经激活过，直接进入"3. 发布"；不可用会给出对应提示（进入"常见处置"）。

只做协助编辑时，即使跑了 --check 撞上「尚未激活」也不要停下来喊用户扫码 ——

那个提示对 draft 不适用，直接继续 draft pull 即可。激活只跟发布有关。

2. 三条拿 token 的路径

本 skill 支持三条互不冲突的路径，你只需要认得出它们，不需要自己选——多数情况下走"设备激活"就够了。

三条路径成功后的效果一样：CLI 把可用 token 写进本机配置，可以直接进入「3. 发布」。这份配置和在线文档「怎么拿到凭据」是同一个文件，不要自己去改它。

3. 发布

publish 只收单文件页面（.html/.htm/.md 等单个文件，目录与 .zip会被本地拒绝并给出明确提示）。发布前先归一化：

• 如果用户给的是 Markdown/纯文本内容，先转换成一个完整、独立的 HTML 文件；
• 页面用到的 CSS/JS 必须内嵌在 HTML 文件内部（<style>/<script> 标签）。本地

图片等资源 CLI 会自动内联进最终产物。只内联 HTML 所在目录里的文件；绝对路径和../ 越出该目录的引用会跳过。不需要你手工转 base64。

标准调用：

htmlrun.cjs publish "/绝对路径/output.html" --note "简短说明这次发布的是什么"

• --note/-m：简短描述这次发布/更新的内容，非必填但建议带上；
• --new：强制新建一个工件、拿一个全新链接，即使这个文件路径之前发布过。

慎用——用户想要的通常是"更新原来那个链接"，不是每次都换一个新地址；只有用户明确表示"这是全新的、不要影响之前那个"才加这个 flag；

• --no-inline：不内联本地资源；
• 同一个路径再次 publish（不加 --new）会自动识别成"更新"，链接不变，版本号 +1；
• 体积：5MB 上限。超限 CLI 会在本地上报错并给出指引，不需要你猜限额。

成功后：

• 把输出里 链接: 后面的 URL 原样发给用户；
• 如果输出里有 指引:（对应服务端的 agentHint），按"核心原则"一节的要求原样

转达；

• 命中敏感词或被限制访问时按"常见处置"处理，不要说"发布成功"糊弄过去。

4. 激活（--check 默认路径）

当 --check 判断本机还没有可用 token 时，会打印类似这样的内容：

htmlrun.cjs 3.0.2
请打开这个链接完成激活：

  ➜  https://html.run/login?code=s_xxxxxxxx

或用微信扫这个码，在手机上完成：

██████████████████████████████
██░░░░░░░░░░░░░░░░░░░░░░░░░░██
██░░██████████████████░░░░██
...（实际会是完整的文本二维码字符画）...

确认授权后，回来重试即可。

转达要求：

• 二维码是纯字符画，原样放进代码块（三个反引号包裹）转达给用户，**不要重新

排版、不要改变缩进、不要把 █/░ 替换成别的字符或 emoji**——排版一乱，手机摄像头就识别不出来；

• 如果服务端没给二维码（字段为空），就只转达链接，这是正常的降级路径，不是

报错；

• 如果用户的终端是老版 Windows cmd（代码页 936 之类），二维码可能会显示乱码——

提示用户直接点链接就行，链接是保底路径；

• 转达完就停下来等用户确认，不要自己接着循环调用 --check 轮询——用户在

手机上操作通常需要几秒到几十秒，agent 自己重试没有意义，只会刷屏；

• 用户回复"好了"/"扫了"之类的话之后，再重新跑一次 --check 确认；
• 激活成功那一次，--check 的输出里会带一次性的默认访问密码，记得转达给

用户（告诉 ta 这是这条链接默认的访问密码，分享链接时可能需要一起给出去，之后不会再显示第二次）；

• 用户不需要、也不应该自己手工去创建 token——如果用户问"要不要去网站上建一个

token"，告诉 ta 不需要，跑 --check 自动创建就行；如果 ta 确实有自定义名称/权限的需求，那种情况走"5. 反向配对"。

激活相关的失败处置：

5. 反向配对（bind <code>）

如果用户已经在 html.run 管理端（token 列表）自己创建了一个 token 并点了"绑定设备"，会看到一个 8 位字母数字码和一条形如 htmlrun.cjs bind Ab3fK9zq 的命令提示（码里去掉了 0/O、1/I/L 这类易混字符，但大小写仍要区分）。这种情况下不要走 --check 激活流程，直接执行：

htmlrun.cjs bind Ab3fK9zq

成功后效果等同于激活成功——本地配置写好了，直接进入"3. 发布"。

失败处置：

• 配对码错误/已使用/已过期——CLI 会提示配对码可能已过期或已使用，引导用户回

管理端重新生成一个新的（配对码 5 分钟内有效，且用一次就失效）；

• 当前服务端不支持反向绑定——走"附录：手工配置 token"的兜底路径。

6. 命令速查

如果 node 命令本身都不存在——说明这台机器没装 Node，参考"1. 首次使用前检查"里的兜底话术。

7. AI 协助编辑（draft，用户给你协助码时）

用户在 html.run 页面上点「AI 协助编辑」后，会拿到一段提示词和一个 d_ 开头的协助码，然后把它交给你。这条路径与 publish 完全独立：

1. draft pull --code d_xxx -o page.html —— 拉取该页面当前正文。可重复拉，不改状态。
2. 按用户要求改 page.html。
3. draft push page.html --code d_xxx —— 回推。用户在浏览器里就能看到改动。
4. 告诉用户已推送，请 ta 查看效果并决定是否发布。可以继续改、多次回推。

协助码不是 token，四条纪律：

• 协助码不能发布页面。发布权只在用户手里 —— ta 在页面上确认后自己发。你不需要

也无法代替这一步。

• draft 命令只认 --code，不读配置文件、不读 HTMLRUN_TOKEN。这是设计如此。
• 协助码失效（用户取消、超时、或重新发起过）时，**唯一正确的做法是让用户回页面重新

发起拿新码。绝不要改用 publish token 去发布** —— 那绕过了用户的确认环节，等于擅自把未经确认的内容发上线。

• 协助码同样是凭据，适用上面「凭据纪律」的全部要求：不复述、不写进文件。

不需要激活设备。 draft 只认协助码，不读配置文件里的 token，服务端地址也有内置默认值 —— 本机从没跑过 --check 也能直接 draft pull。别为了协助编辑去让用户扫码，那一步在这条路上是多余的（用户能拿到协助码，说明 ta 已经登录过管理端了）。唯一的环境要求是 Node 可用。

8. 展示时间窗（online）

页面发布后默认立即可访问、长期有效，绝大多数场景到此为止，不需要本节。

链接是随机 slug（html.run/s/ 后面那 10 位），分享出去之前别人猜不到，所以"默认可访问"不等于"已经公开"——真正决定谁看得见的是访问模式（见 accessNotice）。

有时效性的页面才需要设展示时间窗，典型的三种：

• 到点才公开：活动页、发布会通知，提前做好但不能提前泄露 → --from
• 到期自动关：限时报名、临时对外的资料 → --until
• 临时撤下：内容有问题要先关掉，改好再打开 → --off / --on

htmlrun.cjs online "/绝对路径/output.html" --from "2026-09-01 09:00" --until "2026-09-30 18:00"

用发布时的同一个文件路径，与 publish 认领工件的规则一致，不需要 artifactId。

几条要点：

• 时间窗左闭右开：--until "2026-09-30 18:00" 表示 18:00:00 整点开始就打不开了；
• 只给日期（--from "2026-09-01"）按当天 00:00 算；
• 不接受"下周五""明天"这类相对表述，先自己算成具体时刻再传；
• --off 是手动总开关，优先于时间窗——手动关掉的页面不会因为"到了 --from"

自己打开，要 --on 才恢复；

• 取消已设的限制用 --clear-from / --clear-until（不是 --from ""）；
• 展示期结束后想继续展示，把 --until 改到未来时刻就行，不需要重新发布。

转达纪律： 这个命令的四种结果里，只有"在线"是对外能打开的，另外三种（未到展示时间、展示已结束、已下线）页面对外都打不开，只有用户本人登录后能看。CLI 输出的当前状态: 与 指引: 已经写清楚了，原样转达，不要把"设置成功"说成"页面可以访问了"——用户拿着一个打不开的链接发给别人，是这个功能最常见的事故。

什么时候提这件事： 新建页面成功后，服务端会在 指引: 的 · 提示里带一条关于展示时间窗的说明。看到它就问一下用户这个页面有没有时效性要求，然后按回答处理：

• 用户说要定时/限时 → 跑 online 设上，把结果如实转达；
• 用户说不用、或没明确要求 → 什么都不做，页面保持长期有效。

不要自己替用户决定要不要设时间窗，也不要在用户没提时间要求时主动设上——把一个本该长期可用的页面设成会自动过期，用户往往几周后才发现。

9. 页面数据存储（保存用户自己的数据）

先分清是哪种数据：

• 用户填给作者看的（报名、问卷、留言）→ 走表单接管（发布时的 formTakeover），

数据进作者的控制台。

• 用户自己的数据（刷题进度、记账、待办、抽卡记录）→ 走页面数据存储。

两者不是一回事：作者看不到存储里的内容。

前提：页面必须是"需要登录访问"（authenticated / password / private）。公开页调用存储会返回 403；发布或编辑时如果代码已接入存储、权限还是公开，控制台会自动改成「登录可看」。

怎么改页面：读 https://html.run/api/docs/agent.md 的「页面数据存储」一节，按模板改。要点：

• 在页面第一段脚本开头等一次：await window.HTMLRun.store.ready（与 hydrate() 等价），

返回 { ok, error }；

• 之后页面原有的 localStorage 读写保持不动，运行时会自动同步到服务端；
• 也可以直接用 get / set / remove / clear / setMany；
• ok 为 false 时不要写回默认值，否则会覆盖服务端已有数据；
• 键名 [A-Za-z0-9_-]{1,64}（区分大小写）；单值 ≤8KB；单用户单页 ≤64KB / 100 个键；

写入 60 次/分；

• 不要自建 IndexedDB 或额外前缀的第二套缓存；
• 写入失败会回滚本地值并派发 htmlrun:storage-error，提示用户重试即可。

验证：刷新后数据仍在；换账号看不到；作者详情页只显示近 7 天写入次数。

不需要新命令：CLI 不变，这是页面代码的改造。

10. 保持最新版本

• 每次新对话第一次发布时，建议先跑一次 --check，顺便确认脚本还能正常执行；

只做协助编辑（§7）时不必跑，draft pull 本身就会暴露脚本或服务端的问题；

• 如果报的错误看起来像"这个命令/参数不认识"这类不该出现的问题（而不是本文档

列出的正常业务错误），大概率是 skill 版本太旧、服务端接口已经往前走了——提示用户重新安装/更新这个 skill 即可，scripts/htmlrun.cjs 随 skill 整体分发，没有单独的升级命令；

• 不需要为此写轮询或定时检查逻辑，顺手确认一下就够了。

常见处置

• 敏感词命中（输出里有 敏感词(N): 但没有 ⚠ 已被限制访问）——页面仍可

访问，如实转达命中了哪些词，建议用户修改后重发（同一路径、不加 --new）。

• 页面被限制访问（⚠ 已被限制访问）——如实告知链接当前对外不可见，需要

按提示修改内容后重发才能恢复。

• 发布失败——把 CLI 报的错误原样转达，不要自己编一个理由；如果是文件相关

错误（比如超过大小限制），检查文件是否符合"3. 发布"的归一化要求。

• token 相关错误（提示"无效的 token"或类似）——引导跑 whoami --remote

看清楚具体状态，或直接 loginwx 重新激活；不要自己猜测然后编一个 token 让用户尝试。

• 触发限流（429，提示里会带等待秒数）——原样告知需要等待的时间，**不要

自动重试**：失败次数会被服务端计数，越重试等得越久。

• 文件不存在——检查路径是否正确、是否是绝对路径。
• online 报「这个路径没有发布记录」——路径与发布时用的不是同一个（比如一边

绝对路径一边相对路径），或这个文件还没发布过。先确认路径，必要时先 publish。

• 页面设了展示时间窗后打不开——这不是故障。查 online 输出的 当前状态:：

"未到展示时间"/"展示已结束"/"已下线"都表示对外不可访问，只有用户本人登录后能看。如实说明，并告诉用户怎么改（改时间窗或 --on）。

完整对话示例

场景 1：首次发布

用户："帮我把这个页面发布一下，发给我看看"

1. 检查要发布的东西是否齐备——内容要完整（没有就先按"3. 发布"的归一化要求

生成一个）；

1. 跑 --check——如果需要激活，按"4. 激活"的要求把链接和二维码转达给用户，

然后停下来等确认；

1. 用户确认完成后，重新 --check 一次确认激活成功；
2. 跑 publish，把链接和（如果有的话）默认访问密码发给用户。

场景 2：刚生成完页面，用户想立刻看看效果

用户："这个不错，给我个能打开的链接"

本机大概率已经激活过，--check 会静默通过，直接跳到 publish 即可，不需要重复解释一遍激活流程。

场景 3：更新已有页面

用户："帮我把刚才那个页面改一下颜色，重新发一下"

改完内容后，对同一个文件路径再次 publish，不加 --new；转达时说清楚"链接没变，内容已经更新"，不要说成是一个新链接。

场景 4：页面要到点才公开

用户："这个活动页 9 月 1 号早上 9 点才能让人看到"

1. 正常 publish（页面此刻是可访问的，但链接还没给出去，别人猜不到）；
2. 紧接着 online "<同一路径>" --from "2026-09-01 09:00"；
3. 转达时说清楚两件事：链接是什么、以及现在这个链接对外还打不开，

9 月 1 号 9 点自动开始展示。

如果用户同时说了结束时间（"到 30 号下班为止"），一条命令带上 --until 一起设，不要分两次调用。

场景 5：发布完不确定要不要设时间

用户："帮我发一下这个通知页"

按 §3 正常发布。看到输出 指引: 里那条关于展示时间窗的 · 提示后，顺口问一句"这个页面有没有时间限制，比如到某天就不展示了？"——用户说不用就到此为止，说要就按场景 4 处理。不要自己替 ta 设一个时间。

场景 6：发布命中敏感词

用户："发布一下" → CLI 输出里带了 敏感词(N):

如实转达命中了哪些词、链接是否还能访问：如果只是提示级别（未被限制），把链接正常给用户，同时提醒一下敏感词的情况；如果已被限制访问，说清楚现在这个链接对外看不到，需要改完再发才能恢复。

场景 7：用户想发布一个多文件的站点

用户："我把做好的网站放在 ~/work/portfolio 了，发一个给我"

本服务只支持单文件 HTML，不支持整站/目录发布。如实告知这个边界，不要尝试把目录打包发过去（会被 CLI 本地拒绝），也不要建议把多个页面硬塞进一个 HTML文件凑合——那会破坏站内的多页面导航结构。可以问用户是否只需要发布其中的一个页面（比如首页），单独把那个文件发出去。

附录：手工配置 token

使用场景：

• 当前服务端不支持设备激活或反向配对（走到这两条路径时 CLI 会明确提示）；
• 用户明确表示"我有一个 token，直接帮我配置上"，不想走扫码流程。

htmlrun.cjs login --token h_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

如果用户是通过粘贴板之类的方式把 token 给你，更安全的做法是引导用户自己在终端里执行、通过 stdin 传入，避免明文出现在对话记录里：

echo "h_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | htmlrun.cjs login --token -

失败处置：