ShellBot Website

在 Cloudflare Workers 上构建并部署微应用与网站，具备生产级设计能力。

参数说明

• 命令：$0（可选值：create | deploy | domain | provision | secrets | status | teardown）
• 参数 1：$1（模板名称、资源类型、域名等）
• 参数 2 及以上：$2、$3 等
• 全部参数：$ARGUMENTS

身份验证

支持两种身份验证方式，按以下顺序检查：

方式 1：API Token（推荐，代理/CI 环境必需）

设置环境变量 CLOUDFLARE_API_TOKEN。这是首选方式 —— 若同时配置了 OAuth，则以该方式为准。

若任意命令因身份验证失败而报错，请向用户提示如下信息：

从 https://dash.cloudflare.com/profile/api-tokens 获取 API Token  
使用 “Edit Cloudflare Workers” 模板，或自定义创建具备以下权限的 Token：  
  Workers Scripts: Edit  
  D1: Edit  
  Workers KV Storage: Edit  
  Workers R2 Storage: Edit  
  Zone DNS: Edit（用于自定义域名）  
然后执行：export CLOUDFLARE_API_TOKEN="your-token-here"

方式 2：通过 wrangler login 进行 OAuth（本地开发时的备用方案）

若未设置 CLOUDFLARE_API_TOKEN，则尝试 OAuth 登录：

wrangler login

该命令将在浏览器中打开 Cloudflare OAuth 页面。当在代理（agent）环境中运行时：

1. 运行 wrangler login —— 它将向 stdout 输出授权 URL
2. 将该 URL 展示给用户，并请其在浏览器中打开
3. 用户在浏览器中完成授权后，页面将重定向至 localhost:8976
4. Wrangler 接收回调，并将 OAuth Token 存储于 ~/.wrangler/config/default.toml

限制说明：此方式仅适用于代理运行在用户本地机器上的场景（OAuth 回调必须能到达 localhost:8976）。在远程或 CI 环境中不可用 —— 此类环境请务必使用 API Token。

登录完成后，请运行以下命令验证：

wrangler whoami

脚本中的身份验证检查顺序

所有脚本均优先检查 CLOUDFLARE_API_TOKEN。若未设置，则检查 wrangler whoami 是否成功（即 ~/.wrangler/config/default.toml 中是否存在有效的 OAuth Token）。若两者均失败，则报错并提供两种方式的完整指引。

可选：Account ID

CLOUDFLARE_ACCOUNT_ID —— 由 wrangler 自动检测。若存在多个账户，可手动设置该变量以跳过账户选择提示。

获取位置：Dashboard → Overview → 右侧边栏 → Account ID  
然后执行：export CLOUDFLARE_ACCOUNT_ID="your-account-id"

前提条件

• Node.js v20+
• Wrangler：npm install -g wrangler 或直接使用 npx wrangler

验证安装是否就绪：

wrangler whoami

非交互式设计

所有脚本均完全非交互式运行 —— 不出现任何提示，也无需用户输入。这使其可安全地被代理（agent）调用。对于破坏性操作，需显式传入 --force 标志，而非依赖确认提示。

快速开始

# 1. 基于模板生成项目（完全非交互式，不部署，不初始化 Git）
bash scripts/create-project.sh my-app

# 2. 本地开发
cd my-app && npm run dev

# 3. 部署到 Cloudflare
bash scripts/deploy.sh

# 4. 添加自定义域名
bash scripts/setup-domain.sh my-app example.com

# 5. 按需配置资源
bash scripts/provision-d1.sh my-db --binding DB
bash scripts/provision-kv.sh my-cache --binding CACHE
bash scripts/provision-r2.sh my-assets --binding ASSETS

项目脚手架

默认模板

# 主默认模板（React Router + Hono）
bash scripts/create-project.sh my-app

# 改用 Next.js
bash scripts/create-project.sh my-app --template next

# 使用任意 CF 模板（支持简称或完整名称）
bash scripts/create-project.sh my-app --template astro-blog
bash scripts/create-project.sh my-app --template remix
bash scripts/create-project.sh my-app --template vite-react

详见 references/cf-templates.md，其中包含 36+ 个模板的完整目录。

自定义模板 URL

bash scripts/create-project.sh my-app --template-url https://github.com/user/repo

部署

# 部署至 production 环境
bash scripts/deploy.sh

# 部署至指定环境
bash scripts/deploy.sh --env staging
bash scripts/deploy.sh --env production

# 预演模式（仅显示将要部署的内容）
bash scripts/deploy.sh --dry-run

# 查看已部署版本
wrangler deployments list

# 回滚至前一版本
wrangler rollback [version-id]

deploy.sh 脚本会在部署前预先检查 wrangler 配置文件是否存在，以及 CLOUDFLARE_API_TOKEN 是否已设置。

自定义域名

将自定义域名绑定至 CF Worker 的三种方式。完整指南请参阅 references/custom-domains.md。

1. 自动化配置（推荐）

# 域名须已添加至您的 CF 账户
bash scripts/setup-domain.sh my-worker example.com

# 指定 Zone ID（跳过自动查找）
bash scripts/setup-domain.sh my-worker example.com --zone-id abc123

# 子域名
bash scripts/setup-domain.sh my-worker app.example.com

2. 通过 wrangler.toml 的 Routes 配置

[[routes]]
pattern = "example.com/*"
zone_id = "your-zone-id"

3. 通过 Cloudflare 控制台

Workers & Pages → 您的 Worker → Settings → Domains & Routes → Add Custom Domain。

DNS 要求

• 域名必须已加入您的 Cloudflare 账户（且处于橙色云朵代理状态）
• SSL 证书自动签发，无需手动管理
• 代理域名的 DNS 生效时间通常为 1–5 分钟

资源配置

D1（SQL 数据库）

bash scripts/provision-d1.sh my-db --binding DB
# 创建数据库，并输出 wrangler.toml 所需的 binding 片段  
# 可选参数：--migration-file schema.sql（应用初始迁移）

常用 D1 操作：

wrangler d1 execute my-db --command "SELECT * FROM users"
wrangler d1 execute my-db --file schema.sql
wrangler d1 execute my-db --local --command "..."  # 本地开发
wrangler d1 migrations create my-db add-users
wrangler d1 migrations apply my-db

KV（键值存储）

bash scripts/provision-kv.sh my-cache --binding CACHE
# 创建命名空间，并输出 binding 片段

R2（对象存储）

bash scripts/provision-r2.sh my-assets --binding ASSETS
# 创建 Bucket，并输出 binding 片段

Queues（队列）

bash scripts/provision-queue.sh my-queue --binding QUEUE --type producer
# 创建队列，并输出 Producer / Consumer binding 片段

密钥管理

# 添加密钥（非交互式）
bash scripts/manage-secrets.sh put API_KEY "sk-..."

# 列出所有密钥
bash scripts/manage-secrets.sh list

# 删除密钥
bash scripts/manage-secrets.sh delete API_KEY

# 批量导入 JSON 文件
bash scripts/manage-secrets.sh bulk secrets.json

# 按环境区分
bash scripts/manage-secrets.sh put API_KEY "sk-..." --env production

配置

Wrangler 支持 TOML 和 JSON/JSONC 格式。若两者同时存在，以 JSON/JSONC 为准。请任选其一使用。

快速参考（wrangler.toml）

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"
compatibility_flags = ["nodejs_compat"]

[vars]
API_URL = "https://api.example.com"

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"

[[kv_namespaces]]
binding = "CACHE"
id = "xxx"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

[env.production]
vars = { API_URL = "https://api.example.com" }

[env.staging]
vars = { API_URL = "https://staging-api.example.com" }

详见 references/wrangler-config.md，含 JSONC 格式、静态资源配置及全部 binding 类型的完整说明。

前端设计

构建前端时，请遵循以下原则。每项均链接至深度参考指南。

排版

→ 参见 references/typography.md

选用具有辨识度的字体（避免 Inter / Roboto）。标题采用模块化字号比例并结合 clamp() 实现响应式缩放。合理搭配展示字体（display font）与正文字体（body font）。启用 font-display: swap 并匹配字体度量（metric matching），防止布局偏移（layout shift）。

色彩与主题

→ 参见 references/color-and-contrast.md

使用 OKLCH 构建感知均匀的配色方案。中性色应向品牌主色调微调。遵循 60-30-10 法则（中性色 / 次要色 / 强调色）。避免纯黑/纯白。规避 AI 风格配色（如深色背景配青色文字、紫蓝色渐变）。

布局与留白

→ 参见 references/spatial-design.md

采用 4pt 留白系统。通过差异化间距营造视觉节奏。优先使用 auto-fit 网格。避免将所有内容包裹在卡片中。主动拥抱不对称设计。

动效

→ 参见 references/motion-design.md

仅对 transform 和 opacity 属性进行动画。使用指数缓动（quart/quint/expo）。反馈类动效建议 100–150ms；状态切换类建议 200–300ms；布局类建议 300–500ms。始终适配 prefers-reduced-motion 用户偏好。

交互

→ 参见 references/interaction-design.md

为所有组件设计全部 8 种状态（default / hover / focus / active / disabled / loading / error / success）。键盘焦点仅使用 :focus-visible 显示焦点环。优先采用乐观 UI（optimistic UI）与“撤销”操作，而非确认对话框。

响应式

→ 参见 references/responsive-design.md

采用移动优先策略，配合 min-width 媒体查询。组件级响应式请使用容器查询（container queries）。依据输入方式（pointer: fine/coarse）而非仅屏幕尺寸做适配。妥善处理安全区域（safe area）。

用户体验文案

→ 参见 references/ux-writing.md

按钮文案使用「动词 + 名词」结构。每条错误提示需明确回答「发生了什么」「为什么发生」「如何修复」。空状态应作为引导用户上手的关键时机。术语保持统一，避免混用。

AI Slop 测试

若用户第一眼看到界面便脱口而出“这是 AI 做的”——那便是问题所在。请规避：深色背景配青色文字、紫色渐变、泛滥的玻璃拟态（glassmorphism）、千篇一律的卡片网格、渐变文字、暗色模式下过度发光的强调色。请做出出人意料但意图明确的设计决策。

上下文收集

开展设计工作前，您必须已确认设计上下文：

1. 查阅当前加载的指令中是否存在 Design Context 章节
2. 检查项目根目录下的 .impeccable.md 文件
3. 若二者均不存在，请向用户询问：目标用户、使用场景、品牌个性与语调

故障排查

脚本与参考文档

脚本

参考文档

外部资源

• Workers 文档
• Wrangler CLI 文档
• D1 文档
• R2 文档
• KV 文档
• Workers 模板仓库