mcpField
P
paperclip-page

paperclip-page

github.com/paperclipai云与 DevOps108.3k94 次安装今天更新
代码仓库

关于 paperclip-page

paperclip-page 是将静态目录发布到已配置 Paperclip pages 主机的技能，面向发布静态网站的工作流。它验证目录并将内容写入指定的存储桶和路径，更新时不会删除远程对象。

主要功能

  1. 01发布静态目录
  2. 02发布前验证目录结构
  3. 03支持指定或推导路径 slug
  4. 04更新时仅覆盖，不删除远程对象
  5. 05拒绝符号链接和隐藏文件

适用场景

  1. 01发布包含根目录 index.html 的静态网站
  2. 02用稳定 URL 路径发布页面
  3. 03从原始目录安全更新已发布页面

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/paperclipai/paperclip --skill paperclip-page

安装后在 Claude Code 中输入/paperclip-page确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
scripts/
publish.sh
publish.test.mjs

详细介绍

Paperclip 页面

使用此技能将静态目录发布到已配置的 Paperclip 页面 主机，例如 https://pages.paperclip.ing/<slug>/。

要求

  • 源目录的根目录中包含 index.html。
  • 实时发布时，PATH 中需有 aws CLI v2、curl 和 jq。
  • 需配置以下环境变量：
    • PAPERCLIP_PAGE_BUCKET
    • PAPERCLIP_PAGE_BASE_URL
    • AWS_REGION
    • PAPERCLIP_PAGE_AWS_ACCESS_KEY_ID 和 PAPERCLIP_PAGE_AWS_SECRET_ACCESS_KEY 这两个变量需使用 Paperclip Secrets 中的页面上传凭据
  • 可选环境变量：
    • PAPERCLIP_PAGE_DEFAULT_PREFIX
    • PAPERCLIP_PAGE_AWS_PROFILE（可替代带命名空间的密钥对）
    • PAPERCLIP_PAGE_AWS_SESSION_TOKEN（仅与带命名空间的密钥对一起使用）

不要将页面上传凭据绑定为全局 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY：在所有 AWS SDK 中，静态环境变量的优先级都高于 AWS_PROFILE，因此全局变量会在每个 Agent 运行进程中悄然替换主机身份。带命名空间的变量可将上传者身份限定为仅供此辅助工具使用。如果未设置任何 PAPERCLIP_PAGE_AWS_* 凭据变量，仍会回退到环境凭据链。

工作流

  1. 检查源目录，并确认其中仅包含公开静态内容。
  2. 运行 scripts/publish.sh <dir> --dry-run，以验证本地结构并查看解析后的 URL/前缀。
  3. 选择一个 slug：
    • 用户提供了稳定的 URL 路径时，使用 --slug <slug>。
    • 省略 --slug，根据源目录名称生成 slug。
  4. 发布：
.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page
  1. 将打印出的公开 URL 和 S3 前缀返回给问题提交者/用户。

更新工作流

更新仅会覆盖现有内容并添加新内容。此辅助工具绝不会删除远程对象。

.agents/skills/paperclip-page/scripts/publish.sh ./site --slug my-page --update

如果目标前缀已存在，--update 要求提供本地所有权证明，该证明位于 ./site/.paperclip-page/state.json，由先前从同一源目录进行的发布生成。若没有此状态文件，请创建新的 slug，而不要覆盖其他页面。

安全规则

  • 仅发布公开内容。不要发布机密、客户数据、公司内部资料、凭据或内部日志。
  • 绝不打印 AWS 密钥值。
  • 绝不通过此技能更改存储桶策略、IAM、DNS、CloudFront 或 ACM 设置。设置工作应由操作人员按照运行手册执行，而非使用发布辅助工具。
  • 绝不上传到配置的存储桶和前缀之外。
  • v1 中绝不使用 aws s3 sync --delete，也不要求 s3:DeleteObject 权限。
  • 辅助工具会强制使用 --no-follow-symlinks，并在存在任何源符号链接时失败。
  • 辅助工具会拒绝隐藏文件和点号路径段，但其自身的 .paperclip-page/state.json 除外。
  • slug 和前缀段只能使用小写 ASCII 字母、数字和连字符。
  • 保留 404.html 等全站根对象，由操作人员管理；发布目标始终为 <slug>/... 或 <default-prefix>/<slug>/...。

故障排查

  • Slug already exists：选择其他 slug，或从包含 .paperclip-page/state.json 的原始源目录使用 --update。
  • Missing index.html：先构建静态网站，或将辅助工具指向包含根 HTML 文件的目录。
  • Found symlink：发布前将符号链接替换为实际文件。
  • AccessDenied：确认上传者 IAM 策略允许对配置的存储桶/前缀执行 ListBucket、 GetObject 和 PutObject，并确认 Agent 已获得 Paperclip Secrets。
  • 公开 URL 验证失败：检查 CloudFront 部署/DNS、对象是否存在，以及分发配置是否使用 HTTPS 和私有 S3 REST 源站。

请参阅此技能旁的 README.md，了解操作人员设置、AWS 策略示例、凭据轮换以及安装/附加命令。

评论

支持 Markdown