关于 utels-project-bootstrap
用于注册 utels.dev 生产和暂存项目并写入 Cloudflare Worker 密钥的引导工具指南。它通过标准输入传递令牌，避免将令牌放入命令参数、临时文件或日志。
主要功能
- 01注册生产和暂存 utels 项目
- 02将令牌通过标准输入写入 Worker 密钥
- 03支持单环境注册与 DRY_RUN
- 04处理注册冲突并说明恢复方式
- 05通过模拟测试验证流程
适用场景
- 01为 Cloudflare Worker 配置 utels 遥测
- 02安全传递项目摄取令牌
- 03仅重试失败的环境注册
- 04测试注册与密钥写入而不修改远端
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/utels-project-bootstrap确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
README.mdassets/scripts/setup-utels.test.tssetup-utels.ts详细介绍
utels 项目初始化
注册生产环境和暂存环境的 utels.dev 项目，并将各自返回的接入令牌传递给 pnpm exec cf workers secrets update UTELS_INGEST_TOKEN --worker <name> --body @/dev/stdin。JSON 请求体通过 macOS/Linux 上的标准输入传递；令牌不会出现在 argv、临时文件或命令日志中。
辅助脚本
将 setup-utels.ts 复制到 Worker 的 scripts/ 目录。使用 Node.js 24+ 和项目本地的 cf 依赖。此实现针对 cf beta.5；升级时请核对 cf schema workers secrets update 和已安装的实现。
输入：
| 输入 | 用途 |
|---|---|
UTELS_BOOTSTRAP_TOKEN | 必需的注册凭据，通常由 dotenvx 解密 |
APP_WORKER_PROD / APP_WORKER_STAGING | 所选目标环境对应的必需 Worker 名称；cf 资源命令不使用旧的 --env 选择方式 |
APP_SERVER_DIR | Worker 项目目录；默认为复制后的脚本目录的父目录 |
APP_UTELS_PROJECT_PROD / APP_UTELS_PROJECT_STAGING | 项目 slug；请替换示例默认值 |
UTELS_ENDPOINT / --endpoint=<url> | 注册主机，默认为 https://utels.dev |
--only=production / --only=staging | 仅注册一个环境，也可用于部分失败后的重试 |
DRY_RUN=1 | 跳过注册和密钥写入 |
使用前，请在 targets 中自定义显示名称和来源 URL。utels 即使对服务器端项目也会验证来源。请通过 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID 提供 cf 身份验证信息，也可以通过显式指定的 dotenvx 文件提供。
此辅助脚本使用 --body @/dev/stdin，而不是 --text "$TOKEN" 或 @-。它会忽略子进程输出，因为 API 错误可能包含请求正文；失败时会报告 cf 的退出状态。请使用 cf auth whoami 单独检查身份验证。密钥写入失败后，已注册的 slug 可能仍然存在；注册不保证幂等，且此辅助脚本不会自动删除项目。
注册冲突
先前已注册的 slug 可能触发 D1 唯一约束错误，表现为 HTTP 500 / Worker 1101。重试前，请按 ID 查询 utels 数据库：
pnpm exec cf d1 query DATABASE_ID --sql "SELECT project_id FROM project WHERE project_id LIKE '<your-slug>%';"
请另选一个 slug，或通过运营方支持的流程找回现有令牌。引导流程不包含破坏性删除操作。
验证与相关指南
集成测试会模拟 utels 注册和 pnpm 子进程，以验证 Worker 选择、标准输入中的 JSON、写入失败以及不泄露令牌的输出，且不会对远程服务进行更改。
- Cloudflare 遥测：将返回的接入令牌配置为 Worker 绑定。
- cf API 指南：密钥与命令查询。
- 原始辅助脚本：注册协议的来源；此版本调整了向 cf 传递密钥的方式。