Pagecast：让 AI 生成的报告与静态网页一键发布到 Cloudflare Pages

背景

在 AI 辅助编程和自动化工作流日益普及的今天，代码代理（Coding Agents，如 Codex、Claude Code 等）能够高效地生成 HTML 报告、Markdown 文档、测试覆盖率输出以及静态 Web 应用。然而，将这些本地生成的“数字资产”分享给团队或公众往往存在摩擦：传统的做法涉及手动构建、配置服务器、处理域名或依赖复杂的 CI/CD 流水线。

对于开发者而言，尤其是那些希望快速验证 AI 生成内容或分享临时快照的用户，缺乏一个轻量级、本地优先且能无缝对接现代静态托管平台的工具。Cloudflare Pages 虽然提供了强大的静态站点托管能力，但其命令行工具（Wrangler）对于非日常运维场景来说略显繁琐，且缺乏针对 AI 代理友好的交互接口。

在此背景下，Pagecast 应运而生。它是一个本地优先的发布工具，旨在简化从本地文件到可分享 Cloudflare Pages URL 的过程，特别针对 AI 代理生成的报告和小型静态项目进行了优化。

核心内容

Pagecast 是一个基于 Node.js 的工具，它提供了一个本地管理界面（Admin UI）和命令行接口，允许用户预览、管理并发布 Markdown、HTML 及静态 Web 项目。其核心设计理念是“本地优先”，即所有数据和控制逻辑首先在本机完成，然后再同步至云端。

1. 核心功能与工作流

• 本地预览与管理： Pagecast 启动后会在本地运行一个管理界面（默认地址 http://127.0.0.1:4173）。用户可以在这里预览 HTML 报告、Markdown 文档或静态迷你应用。它支持管理已发布的版本、重命名链接、重新同步更新以及撤销旧的 URL。
• 双服务器架构： 为了模拟真实的部署环境，Pagecast 运行两个本地服务器：
  • 管理 UI 服务器（端口 4173）：用于日常操作和管理。
  • 本地发布页面服务器（端口 4174）：专门服务于本地发布的页面路由（如 /p/<slug>/）。这使得 Pagecast 能够在本地预览与部署到 Cloudflare Pages 时完全相同的 URL 结构。该服务器的根路径返回 404，仅 /healthz 用于健康检查。
• 发布机制：
  • 单文件发布：支持直接发布 HTML 或 Markdown 文件。发布后会生成一个包含 Token 的共享链接（如 https://<project>.pages.dev/p/<token>/），并自动处理同级资产。
  • 静态项目发布：支持发布整个构建文件夹（如 dist/、build/）。用户可以先运行构建命令，然后发布入口文件，Pagecast 会自动将构建文件夹中的其他静态资源一起部署。
  • 直接站点部署：提供简化的命令直接将静态文件夹部署到指定的 Cloudflare Pages 项目，替代了冗长的 Wrangler 命令。

2. 与 AI 代理的深度集成

Pagecast 特别注重与 AI 编码代理的集成，旨在让代理在完成任务后能自主（但在人类确认后）发布成果。

• Codex 原生技能（Skill）： Pagecast 包含一个针对 OpenAI Codex 的原生技能文件。该技能指示代理在完成 HTML/Markdown/静态工件后，主动询问用户是否发布，并在获得明确确认后执行发布操作。
• Claude Code 集成： 通过安装插件，Pagecast 为 Claude Code 提供了 publish-report 技能和 report-detection 钩子。这使得 Claude 能够识别报告文件并触发发布流程。
• 通用 Agent-Skills 格式： 提供便携式的 Agent-Skills 文件，可适配其他支持该标准的 AI 代理。

3. Chrome 浏览器扩展支持

为了处理本地文件（file:/// 协议），Pagecast 提供了一个 Chrome 扩展。

• 一键发布：当代理打开本地生成的 HTML 报告时，扩展工具栏会出现“Publish to Pagecast”按钮。
• 机制：扩展通过调用本地运行的 Pagecast 服务器的 POST /api/publish-local 端点来上传文件并获取公共链接。
• 配置：需要启用“允许访问文件 URL”权限，并确保本地 Pagecast 服务器处于运行状态。

4. 技术栈与依赖

• 运行时依赖：Node.js 20 或更高版本。
• 包管理：推荐使用 npx 进行一次性使用，无需全局安装。
• 依赖结构：根 CLI/服务器部分没有运行时 npm 依赖。React 管理 UI 从 web/ 目录构建并包含在包中。
• Cloudflare 集成：使用受限的 Wrangler OAuth 范围（account:read, user:read, pages:write）进行认证，也可通过 API Token 进行自动化配置。

关键要点

• 适用场景：
  • HTML 报告、仪表盘、代码覆盖率输出、Playwright 或 Lighthouse 报告。
  • Markdown 格式的规划、提案、发布说明、文档和摘要。
  • 从 dist、build、out 或 public 文件夹生成的静态迷你应用。
  • 需要“发布前确认”机制的编码代理工作流。
• 不适用场景：
  • 私人草稿或临时笔记。
  • 需要运行后端服务的服务器渲染应用（SSR）。
  • Python/Ruby/Node 服务（除非它们先导出静态资产）。
• 安装与运行：
  • 无需全局安装：npx pagecast。
  • 从源码运行：git clone 后执行 npm start。
  • 管理界面地址：http://127.0.0.1:4173。
  • 本地数据配置存储在 .pagecast/ 目录中。
• Cloudflare 配置：
  • 首次使用需通过 UI 或命令行 npx pagecast pages setup --project <name> 连接 Cloudflare 账户。
  • 支持多账户选择，可通过 --account 参数指定 Account ID。
  • 自动化场景建议使用 API Token 并传递 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 环境变量。
• 常用命令示例：
  • 发布 HTML 文件：npx pagecast publish "/path/report.html" --json
  • 发布 Markdown 文件：npx pagecast publish "/path/report.md" --json
  • 发布静态项目：先 npm run build，再 npx pagecast publish "$(pwd)/dist/index.html" --json
  • 直接部署静态文件夹：npx pagecast pages deploy "$(pwd)/dist" --project <name> --branch main --json
• 错误处理：
  • 401 错误：需运行 npx pagecast pages setup 或连接 Cloudflare。
  • 409 错误：需通过 --account 参数指定账户 ID 或在 UI 中选择账户。
• 管理功能：
  • 支持拖拽重排报告。
  • 支持撤销单个版本或所有版本。
  • 支持重命名已发布的 URL（旧链接会自动重定向）。
  • 支持原地重新同步已发布的页面。
  • 支持在应用内编辑 HTML 而不覆盖原始源文件。

意义与影响

Pagecast 的出现填补了 AI 生成内容与公众可见性之间的空白。随着 AI 代理能够生成复杂的报告和应用，如何高效、安全地分享这些成果成为了一个新的痛点。Pagecast 通过以下方式解决了这一问题：

1. 降低分享门槛：通过封装 Cloudflare Pages 的复杂性，提供了一站式的本地预览和一键发布体验