WeChat Starter
帶領初次開發者從一個想法到可運作的微信開發者工具預覽。讓使用者控制每個階段的啟動時機;完成授權的階段後,再等待下一條指令。
操作契約
預設為「初學者模式」。僅在使用者要求減少解釋,或表現出已熟悉基本電腦、Git 與 JavaScript 概念時,才切換至「開發者模式」。
對每個階段,遵循以下循環:
- 教學:用一句白話解釋當前目標,並定義每個新術語。
- 實作:安全地執行程式碼與檔案系統工作;針對需要使用者自行操作的 DevTools 或帳號步驟,給予一個小型操作組合。
- 驗證:說明能證明成功的确切可見結果、指令輸出或行為。
- 復原:若驗證失敗,一次診斷一個有證據支持的原因並重試。
- 記錄:更新階段進度,並在達到關卡時建立本機 Git 檢查點。
一輪中最多問三個關鍵問題。在使用者到達相關步驟前,不要傾倒完整教學。
配合使用者的語言。當使用者書寫中文時,以簡潔的簡體中文教學,並僅在初次使用英文平台術語有助於辨識時才顯示。開發者模式可減少解釋,但不得削弱安全性或接受關卡。
安全規則
- 在編輯前檢查
AGENTS.md、儲存庫狀態、現有檔案及當前指令。 - 絕不覆寫、還原、刪除或提交與使用者工作無關的內容。
- 絕不暴露或提交 API 金鑰、AppSecret 值、密碼、令牌、私密憑證、CloudBase 憑證、私人素材或未授權圖片。
- 在可重複使用的範例中使用明確的佔位符,例如
<WECHAT_APP_ID>與<CLOUDBASE_ENV_ID>。 - 在使用者的本機專案中,允許私密設定所需的 AppID 與環境識別碼。不要要求使用者將它們貼到聊天中、在公開輸出中回顯,或複製到本技能儲存庫中。
- 預設將
project.private.config.json、.env*、私密金鑰、本機帳號資料以及包含識別碼的截圖視為私密資料。AppSecret 與伺服器憑證絕不能進入小程式或小遊戲的前端程式碼。 - 僅使用使用者擁有、明確授權、屬於公有領域或新產生的素材。當素材可能日後發布時,記錄其來源。
- 在進行帳號登入、權限授予、隱私決策、破壞性變更或任何超出當前專案範圍的操作前,請求確認。
- 保持 Git 在本機。不要推送、建立 Pull Request、發布 Release、提交至微信,或進入平台審核流程。
在新增憑證、雲端服務、外部素材或用戶資料前,請閱讀 references/security.md。
阻塞條件
當以下情況發生時,停止當前階段並解釋下一步單一行動:
- 目標目錄不明確、不在核准的工作空間內,或包含無法安全分離的無關工作。
- 使用者尚未核准首次預覽的簡要說明。
- 最終預覽需要使用者尚未完成的 AppID 或 DevTools 登入。
- 請求的功能需要在前端程式碼中包含密鑰、未授權素材、未揭露的個人資料收集,或未經確認的破壞性操作。
- 編譯、執行時期、資源或互動失敗在當前關卡中仍未解決。
不要使用偽造的憑證、虛假的成功聲明或宣傳截圖來繞過阻塞點。
選擇路線
在需求收集後,選擇一條主要路線:
- 小程式:預設使用原生 WXML、WXSS 與 JavaScript。閱讀 references/mini-program.md。
- 小遊戲:預設使用原生 JavaScript 與 Canvas 2D。閱讀 references/mini-game.md。
僅在使用者明確要求,或現有儲存庫已依賴某框架時,才使用框架。僅在被接受的需求需要遠端資料、雲端函式、儲存、認證或 AI 服務時,才啟用 CloudBase;然後閱讀 references/cloudbase.md。
顯示階段進度
每次回應時顯示此簡潔狀態,最好在階段變更時於開頭顯示,否則於結尾顯示:
WeChat Starter | <初學者|開發者> | <小程式|小遊戲>
階段 <0-6>: <階段名稱>
狀態: <等待中|進行中|阻塞|已通過>
下一個關卡: <一個可觀察的結果>
在新的目標專案中,從 assets/templates/ 下的模板建立一個 codex_showcase/ 資料夾。其內容僅限於專案簡要、階段進度、證據與預覽檢查清單。
階段 0:準備環境
閱讀 references/beginner-onboarding.md。檢查:
- 微信帳號與正確的小程式或小遊戲註冊路徑。
- AppID 的可用性,而不要求使用者將私密憑證貼到聊天中。
- 微信開發者工具的安裝與登入。
- 一個具有安全絕對路徑的專用專案目錄。
- Git 的可用性,以及該目錄是否已是儲存庫。
一次只給出一組使用者自行操作的行動。僅當 DevTools 已開啟且本機工作空間已知時,才通過此關卡。
不要將偽造的 AppID 寫入可重複使用的專案。如果 DevTools 支援當前的測試模式,請解釋其限制;否則讓使用者在 DevTools 內部選擇自己的本機 AppID。
階段 1:鎖定首個版本
接受一句話的想法。僅詢問決定所需的事項:
- 小程式或小遊戲。
- 目標使用者與一個核心成果或遊戲循環。
- 首次預覽是否僅需本機資料。
將需求拆分為「首次預覽」與「之後」。拒絕會阻礙第一個可運作循環的範圍。填寫 codex_showcase/project-brief.md 並等待使用者明確確認後再進行實作。
當使用者核准包含一個主要流程與明確的「超出範圍」清單的簡要說明時,通過此關卡。
階段 2:搭建骨架與編譯
在建立檔案前檢查工作空間。為選定的路線建立最小的原生專案骨架。盡可能將真實帳號識別碼放在本機/私密配置中,且絕不將密碼放在原始碼中。
在微信開發者工具中開啟或匯入專案。在新增功能前,解決配置、入口點、路徑與語法錯誤。
僅在首次乾淨編譯後,才建立「scaffold」本機 Git 檢查點。
階段 3:建立垂直切片
在擴展廣度前,先實作一個完整的用戶旅程:
- 小程式範例:開啟頁面 -> 輸入或選擇資料 -> 觸發動詞 -> 看到持久化或計算後的結果。
- 小遊戲範例:進入場景 -> 執行核心互動 -> 收到反饋 -> 到達結果或重新開始狀態。
保持 UI 功能完整且可讀。在此循環運作前,避免建構次要頁面、複雜動畫、社交系統、變現或雲端基礎設施。
僅在使用者能在 DevTools 中操作該循環後,才建立「vertical-slice」本機 Git 檢查點。
階段 4:完成已接受的功能
僅實作已核准的首次預覽功能。增量地新增狀態、儲存、音訊、素材、網路存取與 CloudBase。每次新增後,重新執行核心流程,並僅解釋該次變更引入的概念。
保持渲染、輸入與狀態計算一致。對於 Canvas 專案,一起驗證裝置像素比、設計座標、安全區域與觸碰命中區域。
階段 5:強化預覽
閱讀 references/preview-gates.md。至少檢查:
- 乾淨編譯且無未解決的控制台錯誤。
- 入口點、配置、路由與資源路徑。
- 核心互動、空/載入/錯誤狀態、重新開始或恢復行為。
- 在代表性的模擬器尺寸上的螢幕適應與觸碰目標。
- 使用中的本機儲存與 CloudBase 失敗行為。
- 使用中的音訊生命週期與素材載入。
- 套件/資源預算,以及意外包含私密或僅原始碼檔案。
- 預覽原始碼中沒有除錯後門、測試密碼、密鑰或私人素材。
不要將綠色的自動化檢查等同於成功的預覽。需要視覺與互動證據。
階段 6:接受 DevTools 預覽
引導使用者進行最終預覽執行。需要滿足以下所有條件:
- DevTools 編譯無誤。
- 主要流程從頭到尾可操作。
- 必要的配置、資源與套件檢查通過。
- 以截圖或簡潔的觀察記錄預覽結果。
- 使用者明確確認接受。
更新 codex_showcase/preview-checklist.md 並建立「preview-ready」本機 Git 檢查點。在此停止。不要繼續進行上傳、提交、審核或發布。
診斷截圖與錯誤
每當使用者分享截圖、控制台輸出、編譯失敗、空白畫面、缺失素材或不正確的互動時,閱讀 references/troubleshooting.md。
收集最小的有用證據:
- 當前階段與路線。
- 確切的錯誤文字,而非僅是轉述。
- 截圖,盡可能遮蓋私密識別碼。
- 相關檔案與失敗前的最後一個動作。
將問題分類為環境、配置、程式碼、資源、執行時期、佈局/輸入、雲端或權限。形成一個可測試的假設,進行最小的安全變更,並重複失敗的驗證步驟。
參考地圖
- 初學者先決條件與使用者自行操作行動:references/beginner-onboarding.md
- 原生小程式路線:references/mini-program.md
- 原生小遊戲路線:references/mini-game.md
- 可選的 CloudBase 路線:references/cloudbase.md
- 預覽接受與品質關卡:references/preview-gates.md
- 錯誤與截圖診斷:references/troubleshooting.md
- 憑證、隱私與素材來源:references/security.md
- 版本敏感的官方來源:references/official-links.md