Riot 服务
服务循环
- 首先使用
riot-contributor了解库工作流、脏工作树处理和验证预期。 - 从特定的站点/服务目录开始工作；每个服务拥有自己的
package.json、bun.lock、tsconfig.json，通常还有wrangler.toml。 - 如果脚本存在，使用
bun run <script>而不是直接调用工具。 - 保留每个服务的 lockfile。除非明确要求，否则不要在仓库根目录添加 JS 工作空间。
- 将部署、远程迁移、实时 e2e 测试、令牌更改、DNS 更改和生产数据更改视为需要用户明确批准的操作。
- 优先使用本地检查和模拟；实时测试通过服务特定的环境变量选择加入。
服务映射
sites/api.pkgs.ml：包注册表控制平面 Worker。拥有发布/认证/搜索/视图/事件、D1 迁移、Drizzle 模式、R2 存储键、队列、Durable Object 发布协调以及 D1 备份工作流。sites/cdn.pkgs.ml：CDN Worker，处理包制品、稀疏索引文档、Riot/OCaml 二进制元数据和访问分析。从../api.pkgs.ml/src复用注册表类型/存储帮助函数。sites/docs.pkgs.ml：生成的包文档服务。从 R2 提供文档，消费包发布/处理队列，在注册表 D1 中记录管道运行/事件，并使用 Cloudflare Sandbox 容器进行文档/构建验证。sites/pkgs.ml：公共包注册表 Web 应用，Astro + Cloudflare 适配器 + React 岛屿。读取注册表视图 API 和稀疏索引文档。sites/riot.ml：主要的静态 Riot 网站，Astro + Tailwind，Pages 风格部署。sites/get.riot.ml：安装脚本重定向/代理 Worker。
Cloudflare 工具
- 使用 Wrangler 管理 Worker/Astro 服务生命周期：
wrangler dev、wrangler deploy、wrangler d1 migrations apply、wrangler pages deploy、wrangler types以及配置驱动的本地开发。 - 保持服务本地的
wrangler依赖项为最新版本，并通过 lockfile 固定，而不是依赖全局安装。 - 仅将统一的
cfCLI 用于 API/资源检查或它当前暴露的操作，特别是账户、区域、DNS、D1 API、R2 API、队列 API、workers API 元数据和模式发现。 - 在将
cf用于真实的 Cloudflare 修改之前，运行npx cf auth whoami并使用npx cf agent-context <product>或npx cf schema <command...>检查命令形状。 - 不要用
cf替换 Wrangler 的部署/开发/迁移脚本，除非该服务特定的命令已在本地验证过，并且支持相同的配置驱动行为。
配置和绑定
- 保持
wrangler.toml、导出的EnvTypeScript 接口和测试模拟环境同步。 - 优先在 Worker 入口点和共享模块中使用显式
Env接口。 - 将非机密默认值放入
[vars]；将机密信息保存在.env、Wrangler secrets 或 Cloudflare 管理的 secrets 中。 - 对于
api.pkgs.ml中的 D1 模式更改，在sites/api.pkgs.ml/migrations/下添加 SQL 迁移，并一起更新src/schema.ts/DB 帮助函数。 - 运行时 D1 访问通过
api.pkgs.ml/src/db.ts、metadata-db.ts、pipeline-db.ts、access-db.ts或一个命名相似的兄弟文件中的 Drizzle 帮助函数进行。 - R2 对象键契约位于
api.pkgs.ml/src/storage.ts；更改键时，一起更新 CDN/API/Web 消费者和测试。 - 注册表事件有效负载形状是面向用户的服务历史记录。将新事件类型添加到
api.pkgs.ml/src/types.ts、DB 序列化、视图和测试。
测试
- 在完成之前，运行已更改服务的
bun run check。 - 如果服务定义了本地测试，则运行
bun run test。 - 除非明确要求，否则不要运行
bun run deploy、bun run migrate:remote或实时test:e2e。 - 对于
api.pkgs.ml，本地测试使用tests/helpers.ts中的FakeR2Bucket、FakeD1Database、FakeQueue和FakeExecutionContext。 - 对于
cdn.pkgs.ml，复用注册表测试模拟，而不是发明 Cloudflare SDK 模拟。 - 对于
docs.pkgs.ml，优先使用模拟管道执行器和队列清空帮助函数；当测试事件流时，通过数据库序列号断言持久排序。 - 对于 Astro 服务，运行
bun run check；期望 Astro 在检查过程中重新生成.astro类型文件。
Web 工作
- 匹配每个服务现有的 UI 栈。
pkgs.ml使用 Astro 服务器输出、React 岛屿、Tailwind 和 Cloudflare 适配器；docs*.ml在适用时使用 Starlight；riot.ml是一个静态 Astro 站点。 - 将首页作为实际的产品/服务界面，而不是营销占位符。
- 在添加抽象层之前，优先使用现有的组件、布局、CSS token、字体和路由约定。
- 对于注册表 Web 更改，优先使用
sites/pkgs.ml/src/lib/web-views.ts中的注册表视图 API 和package-index.ts中的稀疏索引帮助函数。
操作安全
- 将生产端点视为真实环境：
api.pkgs.ml、registry.pkgs.ml、cdn.pkgs.ml、pkgs.ml、docs.pkgs.ml、docs.riot.ml、play.riot.ml、riot.ml和get.riot.ml。 - 没有用户的明确指示，绝不要运行远程 D1 恢复/导出/导入、DNS 写入、路由/域写入、部署或令牌操作。
- 如果要求进行实时冒烟测试，请先阅读该服务的 README/环境门控，并说明哪些环境变量使测试具有破坏性或需要认证。