# 纸舟 CLI：让 agent 发布 HTML 演示

网站：https://zzhtml.pages.dev

支持 HTML、ZIP、完整文件夹，包含图片、JSON 数据、manifest、CSS、JS、字体和 `_shared/` 依赖。不需要 Cloudflare 账号、管理密码或 API Key。发布使用现有的免登录接口，与网页共用额度。

## 获取

需要 Node.js 22 或更新版本（推荐 Node.js 24）。Windows、macOS、Linux 均使用相同命令。下载下面的独立文件后，不需要 npm install：

https://zzhtml.pages.dev/paperboat.mjs

也可下载包含使用说明和许可证的压缩包：

https://zzhtml.pages.dev/paperboat-cli.zip

macOS / Linux 下载示例，Windows 可用浏览器下载或将 curl 换为 curl.exe：

```sh
curl -fL https://zzhtml.pages.dev/paperboat.mjs -o paperboat.mjs
node paperboat.mjs --help
```

## 常用命令

发布整个演示目录：

```sh
node paperboat.mjs publish ./demo --json
```

发布 ZIP，并指定 HTML 入口：

```sh
node paperboat.mjs publish ./demo.zip --entry slides/index.html --title "项目演示" --json
```

单个 HTML：

```sh
node paperboat.mjs publish ./demo.html --json
```

单 HTML 只上传该文件，不会自动寻找或上传旁边的图片、数据。需要依赖时，应传入完整目录或 ZIP。文件夹内容按所选目录的相对路径保留；ZIP 中如果所有文件有一层共同外目录，会去掉这一层。`--entry` 使用处理后的路径。优先使用根目录 `index.html` / `index.htm`；只有一个 HTML 时自动选它；其他情况要求明确提供 `--entry`。

## 发布前在本机检查

```sh
node paperboat.mjs publish ./demo --dry-run --json
```

只校验和列出文件，不请求网站、不上传、不占每日次数。会跳过隐藏文件、`node_modules/`、`__MACOSX/`，拒绝符号链接、重复路径、超限和不支持的类型。不会自动应用 `.gitignore`，请只选择要发布的静态演示成品目录，并检查输出中的 `files`。

## 给 agent 的调用约定

1. 确认用户已要求发布，并只选择该演示的文件或目录。当前链接公开可访问，不要把未授权发布的公司资料、密钥或个人信息一同传入。
2. 先调用 `publish <path> --dry-run --json` 检查文件清单。如果有多个入口，用 `--entry` 明确选择。
3. 执行 `publish <path> --json`。命令无需交互；进度写入 stderr，stdout 只输出一份 JSON。
4. 退出码为 0 且 `ok` 为 true 时，将 `url` 作为分享地址给用户，`manifestURL` 是自动生成的资源清单。`--dry-run` 的成功只代表本机检查通过，不代表已发布。
5. 每次正常发布会创建新链接，当前 CLI 不支持更新旧链接、列出全站内容或删除内容。不要把整个命令当作幂等操作无限重跑。

发布结果字段为 `ok`、`server`、`id`、`url`、`manifestURL`、`title`、`entry`、`bytes`、`fileCount`、`visibility`。`visibility` 当前固定为 `public`。不会输出管理凭证或临时上传凭证。

错误结果为 `{"ok":false,"error":{"code":"错误码","message":"具体原因"}}`，有时还包含 `status`。退出码：成功 0；参数/文件错误 2；网络/服务器/发布错误 1；收到中断信号 130。

分段传输及最后提交会对临时网络或服务器错误有限重试。创建上传不会自动重试，避免占用重复配额。如果遇到 `PUBLISH_UNCONFIRMED`，文件已上传但最后确认响应丢失；先检查 `error.publication.url`，不要立即重新创建。传输失败会尽力清理未发布内容；未完成内容不会公开，过期后由服务器清理。

## 限制和访问范围

- CLI 对 HTML、ZIP 和文件夹统一按整包发布：总计最多 20 MiB、200 个文件，单文件最多 5 MiB。网页直接上传和粘贴的单 HTML 也支持 5 MiB。所有入口共用全站 200 份 / 100 MiB 的原始内容上限。
- 同一公网 IP 每天最多创建 10 次，与网页上传共用；中国时间早上 8 点重置。429 表示当天次数用完，请勿自动反复重试。
- 这是公开演示工具：拿到链接的人可以查看和下载原始资源。没有查看密码、人员限制或自动到期。公司敏感数据应使用公司批准的受控分享渠道。
- HTML 的相对路径会保留，站点根路径（例如 `/_shared/base.css`）不会自动改写。manifest 保持原样，但不提供 PWA 离线安装或 Service Worker。
- 云端沙箱不支持浏览器本地存储等部分能力；发布后检查实际页面。大陆能否访问取决于使用者的网络。

## 切换服务和网络

```sh
node paperboat.mjs publish ./demo --server http://localhost:8787 --json
```

`--server` 优先于环境变量 `PAPERBOAT_SERVER`，默认使用 https://zzhtml.pages.dev。只支持 HTTPS 根地址，HTTP 仅允许本机。localhost 生成的链接仅这台电脑能访问。

在提供 `http.setGlobalProxyFromEnv()` 的 Node.js 版本（24.14+，或 25.4+）上，CLI 会读取标准代理环境变量（HTTP_PROXY / HTTPS_PROXY / NO_PROXY）；旧版 Node.js 默认直接连接。参见 [Node.js 官方说明](https://nodejs.org/api/http.html#httpsetglobalproxyfromenvproxyenv)。命令行版仍需能访问上传网站，不能改变云服务的网络条件。

## 本工具开发

源码位于 `cli/`。安装项目依赖后运行 `node scripts/build-cli.mjs`，得到可独立运行的 `public/paperboat.mjs`、ZIP 和 SHA-256 校验文件。发布流程会自动重新打包。解压器 fflate 使用 MIT 许可证，许可证随 ZIP 提供。