name: pagepub description: Publish, update, roll back, and delete static websites on a pagepub server using the pagepub CLI. Use when the user asks to publish/deploy/上线/发布 a static site, update a hosted page, view its versions, bind a custom domain, set a permanent link (永久链接), or take a page down.

pagepub — 静态网页发布（Agent Skill）

⚠️ Skill 更新：PagePub 功能持续迭代，本文件是随版本发布的快照，可能滞后。 需要最新说明时，直接读取 https://pagepub.net/skill.md（权威版本，随服务端部署自动同步）；也可 curl -fsSL https://pagepub.net/skill.md -o SKILL.md 覆盖本地副本。若命令行为与本文不一致，一律以线上 skill.md 为准。详见文末「Skill 更新指引」。

这个 Skill 能做什么

把本地任意静态目录（html/js/css/图片/视频等）发布成公开可访问的网站，全程只用一条 CLI：

能力	说明
发布/更新	`pagepub publish <目录>` 首次发布创建站点，重复执行即更新（版本号自动 +1 并生效）
版本管理	每次发布都是不可变版本；可查看历史、一键回滚、删除旧版本
独立地址	每个站点有短链地址 `/s/<短ID>/`，发布即可访问，无需配置域名
自定义域名	`pagepub domain` 绑定自己的域名（DNS 指向服务器即可）
永久链接	`pagepub permlink` 设置 `/p/<短链ID>/<后缀>/` 专属地址（见下）
删除	`pagepub delete` 删除站点及全部版本（不可恢复）

CLI 通过 API 密钥认证；首次发布会在目录里写入 .pagepub 标记文件（记录站点 UUID），之后的发布自动更新同一站点。

Windows 环境特别说明

本机 CLI 路径：C:\Users\cqzsp\.local\bin\pagepub.exe
在 Bash 中调用时使用完整路径："C:/Users/cqzsp/.local/bin/pagepub.exe" <命令>
凭据已保存在 C:\Users\cqzsp\.pagepub\config.json，无需重复 login
严禁修改、重置或覆盖 ~/.pagepub/config.json 中的 server 配置

前置条件（仅首次使用配置一次）

💡 重要：pagepub login 仅需在初始使用时执行一次，凭据会保存在 ~/.pagepub/config.json 中。 升级 CLI 或更新 Skill 绝对不需要重新执行 login，切勿修改、重置或覆盖 ~/.pagepub/config.json 中的 server 配置！

用户在 pagepub 网页控制台「API 密钥」页面创建密钥，并告诉你服务器地址和密钥。
保存凭据并验证（仅需一次）：

pagepub login --server https://pagepub.net --api-key <pp_开头的密钥>

若没有 pagepub 二进制，从服务器下载安装（macOS/Linux）：

curl -fsSL https://pagepub.net/cli/install.sh | sh

也可查看 https://pagepub.net/cli/manifest.json 手动下载对应平台（含 sha256）。凭据也可用环境变量 PAGEPUB_SERVER / PAGEPUB_API_KEY 临时传入，不必 login。

发布 / 更新

pagepub publish <目录>            # 首次发布：创建站点并上传 v1，写入 .pagepub
pagepub publish <目录> --message "说明"
pagepub publish <目录> --no-wait  # 上传后不等待服务器端生效（默认会等待）
pagepub publish <目录> --no-compress  # 跳过本地文本压缩（默认压缩）

输出会给出访问地址（/s/<短ID>/ 等），用 HTTP GET 验证可访问。
本地压缩：CLI 默认对 html/js/css/json/svg/xml 做本地 minify 后再上传（与服务端优化器同一套压缩配置；图片/视频不处理），上传体积更小。 --no-compress 可跳过。
等待生效：服务器开启压缩优化或用户使用自定义 S3（BYOS）时，上传完成后文件要在服务器端压缩并同步到对应存储才真正对外可用。CLI 默认会轮询版本状态直到生效后才打印链接（⏳ 为进行中的进度提示）；--no-wait 跳过等待， --wait-timeout 5m 调整超时，超时会给出警告但仍打印链接。
⚠️ 企业用户与专属域名特别注意：如果当前用户属于某个企业（或配置了企业专属 S3 / 托管存储 / 自定义 CDN 域名），发布成功后返回的 URL 域名会是企业配置的专属 CDN / 独立域名（例如 https://cdn.mycompany.com/s/<短ID>/），与平台默认的 pagepub.link / pagepub.net 不同。向用户汇报发布结果时，必须严格以 CLI 输出中返回的实际 URL 为准，切勿自行拼凑或假设默认域名！
内容仅限静态文件：html/js/css/图片/视频等。隐藏文件（. 开头）、node_modules 会被自动跳过；不支持的扩展名（如 .exe、.php）会被拒绝或跳过并警告。
同一目录重复执行 publish 就是更新（版本号自动 +1 并立即生效）。
检查 .pagepub：如果目录已有此文件说明该目录已绑定站点；不要删除它。换新目录发布会创建新站点。

常用操作

pagepub sites                     # 列出我的所有站点
pagepub info <目录>               # 查看目录的绑定状态
pagepub versions <目录|UUID>      # 查看历史版本（→ 标记当前生效版本）
pagepub rollback <目录|UUID> [--to N]   # 回滚（默认回退到上一个版本）
pagepub domain <目录|UUID> <域名> # 绑定自定义域名（域名 DNS 需指向服务器）
pagepub domain <目录|UUID> --clear     # 解绑域名
pagepub permlink <目录|UUID> <后缀>    # 设置永久链接 /p/短链ID/后缀
pagepub permlink <目录|UUID> --clear   # 清除永久链接
pagepub delete <目录|UUID> --yes  # 删除站点及全部版本（不可恢复）

<目录|UUID> 参数：传本地目录（读取 .pagepub）或站点 UUID 均可；缺省为当前目录。

永久链接

形如 https://<站点域名>/p/<短链ID>/<后缀>/，第一段与短链相同（base58 随机串，不可猜测、恒定不变——修改用户名不影响既有链接），比 /s/<短id>/ 更好记，设置后原短链依然可用。
后缀支持各类语言（中文/日文等 unicode），同一用户内唯一；不能包含 / ? # % & + 或空格，长度 1-64 字符。
不需要用户名即可设置；修改/清除后缀会让旧地址失效，改用户名不影响。
示例：pagepub publish docs && pagepub permlink docs 文档首页 → https://pagepub.link/p/AbCdEfG/文档首页/（AbCdEfG 为短链 base58 ID）

判断成功的标准

publish 输出 ✅ ... (版本 N) 与访问地址；用 HTTP GET 该地址应返回刚上传的 index.html。
更新后浏览器可能因缓存短暂显示旧内容；版本列表里 → 指向最新版即表示服务端已切换。
permlink 输出完整永久链接，GET 该地址返回 200。

排错

现象	处理
`未配置服务器地址 / API 密钥`	先 `pagepub login`，或带 `--server` / `--api-key` 参数
`API key 无效`	密钥被删除或输错；让用户在控制台重新创建
`空间配额不足`	站点超出用户配额；让管理员在后台调大配额或删除旧版本
`不支持的文件类型 .xxx`	上传内容只能是静态文件；移除该文件或让管理员把它加入白名单
目录里没有想发布的文件	确认目录正确；注意隐藏文件和 node_modules 会被跳过

Skill 与 CLI 升级指引

权威版本：https://pagepub.net/skill.md（服务端每次部署自动同步，永远是当前版本的权威说明）。
CLI 版本对比：本地 pagepub version 会输出版本号；线上最新版本见 https://pagepub.net/cli/manifest.json 的 version 字段。
如何升级（无需重新 login）： 1. 升级 CLI 二进制（任选一种）：
- 运行 pagepub upgrade（内置一键检测并安全升级）
- 或运行 curl -fsSL https://pagepub.net/cli/install.sh | sh 2. 升级 Skill 文档：
- 直接读取线上 URL：https://pagepub.net/skill.md；
- 或覆盖本地副本：curl -fsSL https://pagepub.net/skill.md -o SKILL.md。
⚠️ 禁忌事项：
升级 CLI 与 Skill 仅更新程序文件与文档，严禁修改、重置或覆盖 ~/.pagepub/config.json；
严禁随意将 server 改为本地地址（如 127.0.0.1 / localhost）重新 login，原有线上配置会永久有效！

🚀 PagePub