Riot 服務
服務循環
- 首先使用
riot-contributor來處理倉庫工作流程、骯髒工作目錄處理以及驗證期望。 - 從特定的網站/服務目錄開始工作；每個服務都擁有自己的
package.json、bun.lock、tsconfig.json，通常還有wrangler.toml。 - 當腳本存在時，使用
bun run <script>而不是直接調用工具。 - 保留每個服務的鎖定檔。除非明確要求，否則不要新增倉庫根目錄的 JS 工作區。
- 將部署、遠端遷移、即時端到端測試、令牌變更、DNS 變更以及生產數據變更視為需要使用者明確批准的操作。
- 優先使用本機檢查和假物件；即時測試需要透過服務特定的環境變數選擇加入。
服務對應
sites/api.pkgs.ml：套件註冊表控制平面 Worker。負責發布/驗證/搜尋/檢視/事件、D1 遷移、Drizzle 結構描述、R2 儲存金鑰、佇列、Durable Object 發布協調以及 D1 備份工作流程。sites/cdn.pkgs.ml：套件工件、稀疏索引文件、Riot/OCaml 二進位元資料以及存取分析數據的 CDN Worker。從../api.pkgs.ml/src重用註冊表類型/儲存助手。sites/docs.pkgs.ml：產生的套件文件服務。從 R2 提供文件，消費套件發布/處理佇列，在註冊表 D1 中記錄管線執行/事件，並使用 Cloudflare Sandbox 容器進行文件/建置驗證。sites/pkgs.ml：公開套件註冊表網路應用程式，使用 Astro + Cloudflare 適配器 + React islands。讀取註冊表檢視 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依賴項為最新版本，並透過鎖定檔鎖定，而不是依賴全域安裝。 - 僅將統一的
cfCLI 用於 API/資源檢查或它目前公開的操作，特別是帳戶、區域、DNS、D1 API、R2 API、佇列 API、workers API 元數據以及結構描述發現。 - 在對真實 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類型檔案。
網路工作
- 匹配每個服務現有的 UI 技術棧。
pkgs.ml使用 Astro 伺服器輸出、React islands、Tailwind 和 Cloudflare 適配器；docs*.ml在適用時使用 Starlight；riot.ml是靜態 Astro 網站。 - 將首屏保持為實際的產品/服務表面，而不是行銷佔位符。
- 在新增抽象層之前，優先使用現有元件、佈局、CSS 令牌、字型和路由慣例。
- 對於註冊表網頁變更，優先使用
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/環境閘門，並說明哪些環境變數會使測試具有破壞性或需要驗證。