htmldrop

HTMLDrop

使用此技能将本地 HTML 或 Markdown 文件转换为临时的 baseurl.ai 预览 URL。完整 URL 包含访问密码，格式为 ?p=...；任何拥有完整 URL 的人都可以查看页面。

上传前

1. 确认要上传的文件。
   • 如果用户提供了路径，请先确认文件存在，然后使用该文件。
   • 如果你刚生成了 HTML 或 Markdown 报告，请使用生成的文件。
   • 如果存在多个候选文件，且用户未指定文件，仅在上下文明确时选择最近生成的、最相关的 .html、.htm、.md 或 .markdown 文件。否则，请简洁地询问一个问题。
2. 上传前检查内容是否敏感。
   • 如果文件似乎包含凭据、私钥、令牌、机密信息，或用户无意向外部分享的数据，请停止并在上传前询问。
   • 将返回的 URL 视为包含机密信息的链接，因为密码位于查询字符串中。
3. HTMLDrop 仅用于可渲染的文件。如果用户要求分享原始源代码、日志、JSON、CSV 或其他不可渲染的文件，请先创建一个简短的 HTML 或 Markdown 包装文件（若这符合用户的需求）；否则，请说明此技能用于 HTML/Markdown 预览。

命令

通过 npx 运行已发布的 CLI：

npx -y htmldrop-cli "<file>"

简写形式会创建一个新的预览。显式的创建形式与之等效：

npx -y htmldrop-cli create "<file>"

CLI 接受相对路径、绝对路径、~/... 和 file:// URI。 请将路径用引号括起来，以正确处理空格。

如果本地文件的名称恰好是 create、update、settings 或 comments，请使用带路径的显式创建形式，例如 npx -y htmldrop-cli create ./update。

查看已安装的 CLI 版本：

npx -y htmldrop-cli --version

预览默认是私密的：只有带密码的链接才能打开。当用户需要无需密码 即可打开的链接（用于公开发布的帖子、招聘广告，或任何可自由转发的内容）时，请传入 --public：

npx -y htmldrop-cli --public "<file>"

默认情况下，打开预览会重置过期时间：如果 14 天内无人访问，预览就会被删除；每次访问都会重新开始计算这 14 天，但预览最迟会在上传后一年删除。--expires <days> 可将期限设为 1 到 30 天；用户要求延长（或缩短）有效期时，请使用此参数：

npx -y htmldrop-cli --expires 30 "<file>"

如果用户需要页面在指定日期删除，无论是否有人打开（例如“3 天后删除”“确保会议结束后消失”或其他任何有时限的要求），或要求访问时不要重置过期时间，请添加 --no-renew。这样一来，无论预览是否被打开，都会在指定日期删除：

npx -y htmldrop-cli --expires 3 --no-renew "<file>"

这些标志也适用于 update；update --private 会将公开预览重新设为私密，而 update --renew（或 settings --renew）会在使用 --no-renew 后重新开启访问时重置过期时间。未指定重置标志时，update 会保留预览当前的设置。只有在用户要求公开链接或无需密码的链接时，才传入 --public；只有在用户要求指定删除日期或访问时不重置过期时间时，才传入 --no-renew。

若要更改谁能打开仍有效的预览，或更改其有效期限，而不重新上传，请使用 settings 并提供完整的带密码 URL：

npx -y htmldrop-cli settings "https://baseurl.ai/<id>?p=<password>" --public
npx -y htmldrop-cli settings "https://baseurl.ai/<id>?p=<password>" --private
npx -y htmldrop-cli settings "https://baseurl.ai/<id>?p=<password>" --expires 30
npx -y htmldrop-cli settings "https://baseurl.ai/<id>?p=<password>" --no-renew

settings 至少需要 --public、--private、--expires、 --renew 或 --no-renew 中的一个。新的 --expires 期限从现在开始计算；仅更改可见性或重置过期时间的设置会保留当前的过期日期。 页面内容及其 URL 均保持不变，也不会覆盖任何内容，因此 settings 无需通过下方的更新确认步骤。用户只想更改访问权限或有效期限时，优先使用它，而不是 update。

只有在用户明确要求保留引用原样，或默认的内联处理导致上传内容过大时，才使用 --no-inline：

npx -y htmldrop-cli --no-inline "<file>"

若要覆盖现有预览并保留相同的 URL，请将完整的带密码 URL 传回 CLI：

npx -y htmldrop-cli update "https://baseurl.ai/<id>?p=<password>" "<file>"

运行任何 update 命令之前，必须先完成一次阻塞式确认，除非同一用户请求已经提供确切的目标 URL、包含其密码、指定本地文件，并明确要求覆盖、更新或替换该 URL。

• 使用当前运行环境提供的阻塞式提问工具：Claude Code 的 AskUserQuestion、Codex 的 request_user_input，或其他运行环境中的等效阻塞式提问工具。
• 显示目标 URL、用于替换内容的本地文件，并显示以下声明： “此操作将不可逆地覆盖该 URL 对应的现有 HTMLDrop 预览。”
• 如果目标 URL 缺少 ?p=<password>，或无法以其他方式获取密码，请在同一次阻塞式交互中询问密码，不要先询问密码、再另行询问确认。
• 只有在收到明确肯定答复且密码非空后，才能运行 update。如果答复是否定的、不明确、缺少所需密码，或无法进行阻塞式提问，则不要更新；应提议重新上传并创建新的 URL。

update 会执行破坏性覆盖：任何拥有完整 URL 的人都可以查看页面，任何使用相同完整 URL 执行更新的人都可以替换页面内容。

更新时迁移评论

预览可以携带锚定到引用文本的审阅者评论。覆盖文档已编辑过的预览时，引用文本可能已移动或更改，因此应迁移锚点。查看器会在渲染时尝试重新查找每段引用文本，但只有编辑文档的 Agent 知道改写后的段落移到了哪里，因此语义映射由 Agent 负责。CLI 只负责传递；映射不会自动完成，也无法保证成功。

仅在覆盖带有评论的预览时执行此操作，并且仍须完成上述破坏性更新确认步骤。

1. 编辑前获取当前评论：

   npx -y htmldrop-cli comments "https://baseurl.ai/<id>?p=<password>"
   

   这会输出一个 JSON 数组。每条根评论包含 cid、anchor （{ "exact", "prefix", "suffix" } 或 null）、author、text、resolved； 回复则包含 parentId。

2. 对于每条根评论，在新的本地文件中找到对应段落，并创建一个新的锚点：exact 是新的引用文本，prefix/suffix 是其紧邻的前后文本（各几个词）。

3. 将映射写入一个 JSON 数组文件，例如 anchors.json：

   [
     { "cid": "<cid>", "anchor": { "exact": "new quote", "prefix": "...", "suffix": "..." } },
     { "cid": "<cid-gone>", "anchor": null }
   ]
   

   使用 "anchor": null 标记目标已不存在的评论，或者完全省略该 cid。如果新文档中没有可靠的匹配引用文本，请勿编造锚点。

4. 使用映射进行更新：

   npx -y htmldrop-cli update "https://baseurl.ai/<id>?p=<password>" "<file>" --comment-anchors anchors.json
   

文件中未知的或属于回复的 cid 会被服务忽略。省略 --comment-anchors 会保留现有锚点不变（此时查看器会依赖文本引用回退机制，并将无法定位的锚点视为孤立锚点）。

已验证的 CLI 行为

• Markdown 文件（.md、.markdown）会在上传前渲染为 GitHub 风格的 HTML。
• 默认会内联相对路径的 <img src>、<link href> 和 <script src> 引用。远程 URL、数据 URL、片段链接和 JavaScript URL 不会改动。
• --no-inline 会保留本地引用，不进行内联。
• 服务接受最大 50 MiB 的页面（渲染和内联后的 UTF-8 字节数）。资源内联和 Markdown 渲染可能会使最终负载大于原始文件。
• 上传响应包含一个形如 https://baseurl.ai/<id>?p=<password> 的 URL。默认情况下，链接在 14 天未被访问后删除（或按 --expires <days> 指定的天数删除，范围为 1 到 30）；每次访问都会重新开始计时，并且链接最多保留至上传后一年。使用 --no-renew 时，无论是否打开，链接都会在指定日期删除。
• 使用 --public 时，CLI 会在标准输出中打印两行：第一行是不带密码的 https://baseurl.ai/<id>，任何人都可以打开；第二行是密码链接，也就是编辑链接（update、settings 和 comments 所需）。
• update <url> <file> 会将该 URL 中的 id 和密码与新内容一起发送，返回相同的 URL，重新开始有效期计时，并保留预览的可见性、有效期和续期设置，除非 --public、--private、--expires、--renew 或 --no-renew 另有指定。
• settings <url> 会就地更改可见性、有效期和／或续期设置（--public、--private、--expires、--renew、--no-renew），并打印与上传相同的行：先显示可分享的 URL；若预览为公开，则随后显示编辑链接。
• --version 会打印已安装的 htmldrop-cli 版本并退出，不会上传。
• 未知选项会在上传前导致失败。如果本地文件名以 - 开头，请在文件路径前使用 --。
• 在非交互式 shell 中，CLI 会在标准输出中打印 URL。在交互式 TTY 中，如果 pbcopy 成功，还会打印 id、有效期以及剪贴板提示。对于续期预览，有效期显示为 expires: <date> if unopened (renews on visit, until <date>)；对于固定有效期，显示为 expires: <date>；对于固定保留的预览，显示为 expires: never。

处理输出

读取命令的标准输出和标准错误。

• 标准输出的第一行是可分享的 URL。将该 URL 提供给用户。
• 如果标准输出有第二行（你传入了 --public），它是带密码的编辑链接。告诉用户第一个链接是公开链接，第二个链接用于更新；不要把第二个链接当作转发链接提供。
• 如果你使用了 update，说明现有预览已在同一 URL 上被覆盖。
• 如果你使用了 settings，说明更改了什么（现在公开、现在私密、新的过期时间，或续期已开启／关闭），并说明内容和链接未变。使用 --private 后，单独的公开 URL 将无法再打开页面。
• 用通俗语言说明过期时间，并使用你指定的天数（除非使用了 --expires，否则为 14 天）：
  • 默认（访问时续期）：“连续 14 天无人访问后删除；每次访问都会重新开始计时。”如果 CLI 输出了 if unopened (renews on visit, until <date>)，可以补充说明页面最迟会保留到该日期。
  • 使用 --no-renew 时：“将于 删除，无论是否打开。”只有 CLI 输出了确切日期，才原样告知；否则说“将在 N 天后删除”。
  • 不要编造 CLI 未输出的确切时间戳。
  • 如果输出了 expires: never，则页面已由操作员固定：说明链接不会过期，并省略过期说明。
• 对于私密预览，说明链接可自行验证身份，因为密码已包含在 URL 中。除非用户要求，否则不要单独提供密码。
• 只有在 CLI 确实输出了剪贴板消息时，才说明 URL 已复制到剪贴板。
• 如果标准错误报告了资源警告，例如 not found，请指出。URL 仍可能已创建，但未解析的本地引用可能导致远程预览不完整。

默认私密上传的回复示例（仅供参考；请根据所用标志和 CLI 输出调整）：

Uploaded: <url>
The link includes the access password and can be forwarded as-is. It is
deleted after 14 days without a visit; each visit restarts that.

故障排除

• file not found：用 ls -l 重新检查路径，或使用绝对路径。
• 未知选项：重新检查标志拼写。
• markdown conversion failed：CLI 无法通过 marked 渲染 Markdown；报告确切错误，并询问用户是否要安装，或改用 HTML 导出。
• File too large 或 HTTP 413：最终 HTML 负载超过了服务限制。尝试使用 --no-inline、减少嵌入资源、拆分报告，或创建更小的摘要页面。
• update 或 settings 遇到格式错误的 URL、缺少 ?p=...，或 HTTP 403：重新确认用户提供的是原始完整 HTMLDrop URL（对于公开预览，应提供编辑链接，而不是单独的公开链接）。不要尝试从干净的预览 URL 中恢复密码。
• settings failed (409)：保存设置时页面被重新上传。再次运行相同的 settings 命令。
• Unknown option '--update'：update 是子命令，不是标志。运行 update <url> <file>。
• 如果 CLI 提示已安装的 htmldrop skill 已过时，运行 npx skills update htmldrop，然后重试。
• upload failed：报告确切状态和标准错误。除非标准输出中包含 URL，否则不要声称 URL 已创建。
• 资源警告：如果预览需要可移植，请解决缺失的本地资源问题，然后重新上传。