mcpField
H
html-preview

html-preview

github.com/gitboboboクラウド・DevOps062 回インストール今日更新
リポジトリ

html-preview について

html-preview は、API 経由で HTML や ZIP の静的ページプレビューを管理するスキルです。共有用の公開リンクやプログラムからの管理が必要な場合に適しており、URLを維持した内容差し替えや有効期限、ゴミ箱操作に対応します。

主な機能

  1. 01HTMLまたはZIPをアップロードして公開リンクを作成
  2. 02プレビューの検索、絞り込み、ページ分割
  3. 03タイトル、メモ、有効期限の編集
  4. 04公開URLを維持して内容を差し替え
  5. 05お気に入り、ゴミ箱、復元、完全削除

活用シーン

  1. 01静的ページのプレビュー共有
  2. 02CIやエージェントからページをアップロード
  3. 03共有済みページを同じリンクのまま更新
  4. 04プレビューの整理、復元、完全削除

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/gitbobobo/skills --skill html-preview

インストール後、Claude Code で/html-previewを入力して読み込まれたか確認します。

詳細

プロジェクトの README より

HTML Preview API

何时使用

当用户要求你：

  • 上传 HTML 或 ZIP 静态页并生成可分享的公开预览链接
  • 列出、查询、更新预览项的标题、备注或有效期
  • 替换预览内容（保持同一公开 URL）
  • 将预览移入回收站、恢复或彻底删除
  • 通过程序化方式与 HTML Preview 交互（CI、Agent、curl）

认证配置

HTML Preview 使用 API Key 进行程序化认证。Key 格式为 hp_ 开头的 URL-safe 随机串；创建时仅在 Web 设置页完整显示一次。

首次使用（配置持久化）

如果 ~/.config/html-preview/config.yaml 不存在，必须向用户询问以下信息：

  1. Base URL：服务地址，例如 http://localhost:7849 或 https://preview.example.com（默认端口 7849）
  2. API Key：在 Web「设置 → API Key」中创建（hp_ 开头）

然后将配置写入文件：

# ~/.config/html-preview/config.yaml
base_url: "http://localhost:7849"
api_key: "hp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

注意：~/.config 目录在 macOS/Linux 上通常已存在；如果不存在，请先创建目录。

权限边界：API Key 不能创建、列出或吊销 API Key（/api/keys* 仅 Session Cookie）。Bearer 访问 Key 管理端点返回 40300。Key 的创建与吊销须在 Web 管理界面完成。

后续使用

直接读取 ~/.config/html-preview/config.yaml 中的 base_url 和 api_key，不再询问用户。

请求头

JSON 请求：

Authorization: Bearer <api_key>
Content-Type: application/json; charset=utf-8

multipart 上传（POST /api/items、PUT /api/items/:id/content）：

Authorization: Bearer <api_key>

（由 curl -F 自动设置 Content-Type: multipart/form-data，勿手动覆盖为 JSON。）

网页管理入口

路径说明
/首页：搜索、网格、上传
/trash回收站：恢复、彻底删除
/settings改密、API Key、浏览器一键安装、数据路径
/setup首次设密（未初始化时）
/login登录

默认监听 0.0.0.0:7849；本地管理页示例：http://localhost:7849/。

公开预览 URL

每个预览项有固定公开路径（无需鉴权）：

{base_url}/c/{id}/

示例：http://localhost:7849/c/AbCdEfGhIjKlMnOp/

  • 仅 active 且未过期的项可访问；过期或已在回收站则不可用。
  • 响应带 CSP sandbox 等安全头；管理端网格不嵌 iframe 预览。

Item 详情中的 public_path 字段为站内路径（如 /c/{id}/），完整 URL = base_url + public_path。

上传限制

类型限制
HTML 单文件≤ 2 MB
ZIP 压缩包≤ 20 MB
ZIP 解压后总大小≤ 50 MB
ZIP 内文件数≤ 200
ZIP 根目录必须包含 index.html
安全拒绝 ..、绝对路径、怪异 symlink、嵌套 zip

HTML 上传会归一保存为 index.html；ZIP 按相对路径解压到项目录。

有效期

上传或 PATCH 时可指定：

expires_in含义
1d1 天后过期
7d7 天后
30d30 天后
90d90 天后
never永久
（不传）上传默认 30d；PATCH 不传过期字段则不修改

若同时传 expires_at（ISO 8601 / RFC3339）与 expires_in，以 expires_at 为准。永久必须显式传 never。

过期后后台自动移入回收站；回收站保留 30 天后硬删。

核心接口

所有成功响应：{"code":0,"data":...}；失败：{"code":<int>,"message":"..."}。

上传预览
curl -X POST "$BASE_URL/api/items" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]" \
  -F "title=演示页" \
  -F "notes=可选备注" \
  -F "expires_in=7d"

字段：file（必填）、title、notes、expires_in、expires_at。

列表
curl -G "$BASE_URL/api/items" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "q=关键词" \
  --data-urlencode "status=active" \
  --data-urlencode "favorite=true" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=24"
参数说明
q标题/备注关键词
statusactive（默认）或 trash
favorite可选，仅接受字面 true（只返回收藏项，其他值返回 40001）
page页码，默认 1
page_size每页数量，默认 24，最大 100

排序固定为 updated_at 倒序；favorite 可与 q、status、page、page_size 自由组合。

响应 data：{items, page, page_size, total}。

详情
curl "$BASE_URL/api/items/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY"
更新元数据 / 有效期
curl -X PATCH "$BASE_URL/api/items/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"title":"新标题","notes":"新备注","expires_in":"30d"}'
收藏 / 取消收藏
curl -X POST "$BASE_URL/api/items/$ITEM_ID/favorite" \
  -H "Authorization: Bearer $API_KEY"

curl -X DELETE "$BASE_URL/api/items/$ITEM_ID/favorite" \
  -H "Authorization: Bearer $API_KEY"

两者均返回更新后的 item；幂等，重复收藏/取消都成功（重复收藏保持首次的 favorited_at）。仅限 active 条目：回收站项返回 40900，不存在返回 40400。

  • 收藏切换不更新 updated_at，不影响列表排序。
  • favorite 不能通过 PATCH /api/items/{id} 修改（未知字段被忽略），须用上述专用端点。
  • 收藏为全局状态，所有 API Key 共享同一份收藏。

Item 字段：favorite（bool）、favorited_at（RFC3339 UTC 字符串或 null，收藏时间；取消后为 null）。

替换内容（ID 与公开 URL 不变，触发重新截图）
curl -X PUT "$BASE_URL/api/items/$ITEM_ID/content" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"
移入回收站
curl -X DELETE "$BASE_URL/api/items/$ITEM_ID" \
  -H "Authorization: Bearer $API_KEY"
从回收站恢复
curl -X POST "$BASE_URL/api/items/$ITEM_ID/restore" \
  -H "Authorization: Bearer $API_KEY"
彻底删除（不可恢复）
curl -X DELETE "$BASE_URL/api/items/$ITEM_ID/permanent" \
  -H "Authorization: Bearer $API_KEY"
缩略图（需鉴权）
curl "$BASE_URL/api/items/$ITEM_ID/thumb/desktop" \
  -H "Authorization: Bearer $API_KEY" -o thumb.webp

variant：desktop 或 mobile；无缩略图时 404。

API Key 权限范围

资源Session（Cookie）API Key（Bearer）
Items 读/写（上传、PATCH、替换、收藏、回收站、恢复、硬删）✅✅
缩略图✅✅
API Key CRUD（/api/keys*）✅❌（40300）
改密、浏览器安装（/api/settings/*）✅❌（40300）
公开页 /c/{id}/无需登录无需登录

错误处理

HTTP 状态Code含义
40040001参数/校验失败（无效过期、zip 不安全、缺 index.html 等）
40140100未登录或 Key 无效/已吊销
40340300禁止（Key 访问 Key 管理、Session 专用接口等）
40440400资源不存在
40940900状态冲突（如对已删除项的错误操作）
41341300文件过大
50050000内部错误

收到 401 时检查：

  1. Authorization: Bearer hp_... 是否正确
  2. base_url 是否指向正确的实例与端口（默认 7849）
  3. Key 是否已在 Web 设置页吊销

注意事项

  • 更新、删除操作使用 Item 的 id（URL-safe 公开 id），不是文件名。
  • 截图状态见 screenshot_status：pending / ready / failed / no_browser；无浏览器时上传仍成功。
  • 所有时间字段为 ISO 8601（RFC3339）格式。
  • JSON 请求建议 --data-binary @body.json，避免 shell 编码问题。

コメント

Markdown 対応