端到端專案工程：設計、增量建置、驗證、系統性除錯。 當使用者要求建置軟體、儀表板、排程任務或網頁應用程式時使用（例如：建立價格監控器、每日摘要任務、發布 API）。
Phase 0: SKILL DISCOVERY & REQUIRED READING
⚠️ 關鍵 — UI 設計品質關卡： 如果專案會產生任何視覺化的 HTML 輸出（儀表板、網頁應用程式、登陸頁面、作品集、任何使用者會看到的頁面），你必須 read_file ui-design 技能的 SKILL.md 並遵循其內容，然後再開始撰寫任何 HTML/CSS。這不是可選的。project-builder 負責工程；ui-design 負責視覺品質（並告訴你何時該使用元件庫如 shadcn/ui、HeroUI 或 coss ui，而不是手刻）。跳過 ui-design 會產出泛泛的 AI 內容。
A. 挑選技能。 收集專案需要的所有資料來源。針對每個來源，優先使用技能：檢查 <available_skills>，如果沒有合適的，嘗試 search_skills(query) 尋找官方與社群技能。技能是最可靠的層級 — 它們提供經過測試的客戶端、認證和速率限制處理。網路搜尋是最後手段。只有在沒有技能能涵蓋該來源時，才撰寫原始的 HTTP / SDK 程式碼。
B. 閱讀專案涉及的平台規則。 這些規則存在於參考文件中（不在你的系統提示中），所以你必須在撰寫程式碼前 read_file 它們。跳過這一步是造成 401 錯誤、路徑錯誤以及「本機正常，預覽失敗」錯誤的首要原因。
| 如果專案包含... | 在 Phase 2 之前 read_file |
|---|---|
| 任何外部 API 呼叫 | config/context/references/sc-proxy.md |
| 預覽 / 儀表板 / 網頁應用程式 | config/context/references/preview-guide.md |
| 排程任務 | config/context/references/scheduled-tasks-guide.md |
| 長時間執行的背景任務 | config/context/references/background-tasks.md |
| 檔案寫入超過 300 行 | config/context/references/tool-writing-guide.md |
| 任何視覺化的 HTML 輸出（儀表板、網頁應用程式、登陸頁面、作品集） | ui-design 技能的 SKILL.md — 載入並遵循其所有視覺決策（追蹤選擇、顏色、字體、佈局、動畫，以及何時使用元件庫）。此技能是 UI 品質關卡；跳過它會產出泛泛的 AI 內容。 |
Phase 1: DESIGN
將模糊的需求轉化為具體規格。 如果意圖不明確，問一個問題。
架構決策樹：
週期性警報/報告？ → 排程任務
即時視覺介面？ → 預覽伺服器（儀表板）
一次性分析？ → 內嵌（無需建置）
可重複使用的工具？ → 腳本放在工作區
對於中型以上專案，在撰寫程式碼前向使用者呈現：
- 資料流程 — 來源 → 處理 → 輸出
- 架構選擇及原因
- 成本估算 — (每次執行成本) × 頻率 × 30 = 每月成本
- 已知限制
UI 設計關卡（必要、阻斷 — 針對視覺專案）：
如果架構選擇是預覽伺服器或任何會輸出使用者可見 HTML 的專案：
- 立即
read_fileui-design技能的 SKILL.md（如果你尚未在此工作階段中讀取），並選擇一個路線（手刻 vs 元件庫）。 - 對於手刻 UI，執行設計轉盤（位於 ui-design 的
references/design-process.md）以決定表面色、強調色、字體和美學家族。 - 在下方階段計畫中包含設計轉盤的輸出行。
如果你跳過此步驟，UI 看起來會像泛泛的 AI 輸出。此關卡是阻斷性的 — 在完成之前不要進入 Phase 2。
設計關卡（必要、阻斷）：
Phase 1 結束後，暫停並呈現簡短的階段計畫（DESIGN/BUILD/DEBUG 的里程碑）。明確詢問：「批准此計畫並進入 Phase 2 BUILD？」 提問時使用使用者的語言 — 切勿注入硬編碼的非英文字串。
- 如果使用者確認：進入 Phase 2。
- 如果使用者要求修改：修改設計並重新確認。
- 如果沒有確認：不要撰寫/修改程式碼。
Phase 1.5: SCAFFOLD（可分享專案必備）
設計確認後，在撰寫任何程式碼之前，將專案建立在標準佈局下。這使得專案從第一天起就可以透過 community-publish 技能分享 — 無需後續遷移。
標準專案位置： output/projects/{slug}/
output/projects/{slug}/
├── project.yaml # name, version (從 0.1.0 開始), type, description, license, entry, env_required
├── PROJECT.md # 4 個必要區段：What / Required env / How to start / Outputs / Troubleshooting
├── .env.example # 程式碼讀取的每個環境變數，附上佔位值
├── .gitignore # 至少包含：.env, *.key, *.pem, __pycache__, node_modules
└── src/ # 所有程式碼都在這裡，不要分散
├── run.py # type=task — 第一行必須是： # -*- task-system: v3 -*-
├── server.py # type=service
├── main.py # type=script
└── index.html / app.py + frontend # type=preview
專案類型 → 進入點對應：
| 架構選擇 | type | 進入點路徑 |
|---|---|---|
| 排程任務 | task |
src/run.py |
| 預覽伺服器 | preview |
src/index.html（靜態）或 src/app.py |
| 背景守護程式 | service |
src/server.py |
| 一次性工具 | script |
src/main.py |
僅在以下情況跳過 scaffold：
- 純內嵌分析，無需持久化程式碼
- 修改現有的
output/projects/...專案（保留其佈局） - 使用者明確說「把腳本丟到 /tmp 就好」或類似情況
在 Phase 2 BUILD 期間，維護 scaffold：
- 程式碼讀取的每個新環境變數 → 在同一編輯中新增至
.env.example - 每個行為變更 → 更新 PROJECT.md
- 永遠不要在
src/之外撰寫程式碼（設定檔、測試資料：專案根目錄或src/data/）
為什麼這很重要： 已經在標準佈局中的專案可以一條指令發布。分散在 tasks/、output/scripts/、dashboards/ 等處的專案需要先透過 tidy_project() 遷移才能分享，而使用者通常不想從記憶中重建 PROJECT.md。
對於現有分散的程式碼： 呼叫 community-publish 技能 → tidy_project(any_dir) 在發布前重新組織。
API 成本與速率限制：
所有外部 API 呼叫都透過 sc-proxy，它按請求計費並強制執行速率限制。
在設計之前，閱讀 config/context/references/sc-proxy.md 了解定價表和限制。
- 估算成本：
credits_per_request × requests_per_run × runs_per_day × 30 - 遵守速率限制：例如 CoinGecko 每分鐘 60 次請求 — 每分鐘輪詢 10 種貨幣的任務沒問題；100 種則不行
- 優先使用批次端點而非 N 次單一呼叫（例如使用多個 id 的
coin_price而非 N 次單獨呼叫） - 純腳本任務（無 API）：每次執行約 0 點數
- LLM 成本警告： 高階模型每次呼叫可能超過 $0.10。不同模型層級的定價差異很大；昂貴模型可能是廉價模型的 100 倍以上。
- 需按模型估算： 將 LLM 成本按模型細分（
model_price_per_call × expected_calls_per_run × runs_per_day × 30），而不是使用單一通用數字。 - 儀表板自動重新整理會消耗點數 — 除非使用者要求，否則預設為手動重新整理
- 支出保護： 如果預估每月 LLM 成本很高，明確詢問是否要在實作前對每個呼叫者設定限制。
- 每個呼叫者追蹤（必要）： 每個代理請求必須包含
SC-CALLER-ID（例如job:{JOB_ID}、preview:{preview_id}、chat:{thread_id}），以便追蹤使用量並設定上限。詳情請見config/context/references/sc-proxy.md§ Caller Credit Limit
資料可靠性： 原生工具 > 代理 API > 直接請求 > 網頁爬取 > LLM 數字（永遠不要）。
鐵律：腳本負責取得資料。LLM 負責分析文字。最終輸出 = 腳本變數 + LLM 敘述。
任務腳本可以直接匯入技能函式：
from core.skill_tools import coingecko, coinglass # 自動發現 skills/*/exports.py
prices = coingecko.coin_price(coin_ids=["bitcoin"], timestamps=["now"])
工具名稱 = SKILL.md frontmatter 中的 tools: 列表。請參閱 build-patterns.md § Using Skill Functions。
Phase 2: BUILD
每個部分遵循以下循環：
建置一個小部分 → 執行它 → 驗證輸出 → ✅ 下一個部分 / ❌ 先修正
| 建置內容 | 驗證方式 | 通過條件 |
|---|---|---|
| 資料擷取器 | 執行，印出原始回應 | 非空、近期、合理 |
| API 端點 | curl localhost:{port}/api/... |
正確的 JSON |
| HTML 頁面 | preview_serve + preview_check |
ok = true |
| 任務腳本 | python3 tasks/{id}/run.py |
數字與來源相符 |
| LLM 分析 | 數字來自腳本變數，而非 LLM 文字 | 使用範本模式 |
驗證分層：
- 關鍵（必須通過才能預覽/啟用）：資料正確性、核心邏輯、無崩潰
- 參考（可在交付後修正）：樣式、邊緣案例訊息、次要 UX 修飾
反模式：
- ❌ 什麼都沒執行就說「完成了！」
- ❌ 寫了 200 多行才第一次測試
- ❌ 「應該可以運作」
→ 詳細模式：閱讀 references/build-patterns.md
程式碼實務
- 先
read_file再edit_file— 了解現有內容 - 修改時
edit_file優於write_file - 在
write_file前檢查ls— 避免重複現有檔案 - 大型檔案（>300 行）：拆分成多個檔案，或先建立骨架再透過 bash 注入
- 環境變數：
os.environ["KEY"]，將安裝指令持久化到setup.sh
儀表板 UX 預設值（type=preview）
自行決定合理的預設值，並在首次載入時呈現真實資料。將篩選器視為使用者稍後可調整的選用細項 — 絕不將其作為阻擋初始檢視的先決條件。在合理的間隔內自動重新整理。在沒有任何內容出現之前，不要顯示「點擊載入」/「輸入地址」/「選擇代碼」。
視覺設計品質（所有 HTML 輸出必備）： 如果已安裝 ui-design 技能，你必須在撰寫任何 HTML/CSS 之前 read_file 其 SKILL.md 並遵循它。project-builder 負責工程流程；ui-design 負責視覺品質。僅使用 project-builder 會產出功能正常但視覺上泛泛的輸出。
平台規則
- 代理工具僅為工具呼叫 — 不可在腳本中匯入
- 預覽路徑必須是相對路徑（
./path而非/path） - 在程式碼中硬編碼預覽埠號，不要從環境變數讀取。 每個預覽在自己的 pod 中執行，環境變數埠號合約在不同 pod 間不可靠。選擇任何空閒埠號（例如
8765），直接寫入應用程式，並將相同數字傳遞給preview(action="serve", port=...)。兩者必須完全一致。 - 並行預覽需要不同的 ID。 如果兩個預覽共用相同的
dir，較新的會自動終止較舊的（相同目錄取代規則）。迭代時，重複使用相同 ID 而非創造變體，或使用不同的目錄。 - 全端 = 一個埠號（後端提供 API + 靜態檔案）
- Cron 時間為 UTC — 從使用者時區轉換
- 預覽服務與發布 → 閱讀平台參考
config/context/references/preview-guide.md - localhost API → 閱讀
config/context/references/localhost-api.md- 任務腳本決定何時呼叫代理、傳遞哪些資料/上下文、使用哪個模型
- 模式：腳本取得資料 → 評估是否值得注意 → 僅在需要時呼叫 LLM → 印出結果
- 腳本中的 LLM — 兩種選項（詳見
references/build-patterns.md）：- OpenRouter（透過 sc-proxy）：輕量級，用於摘要/翻譯/格式化文字。直接 API 呼叫，無代理開銷。
- localhost /chat/stream：完整代理，包含工具。僅在 LLM 需要工具存取時使用。
- 資料範本規則：腳本擁有數字，LLM 擁有文字。最終輸出由腳本變數的資料 + LLM 的分析組合而成。永遠不要讓 LLM 輸出成為使用者所見數字的唯一來源。
- API 成本與速率限制 → 閱讀平台參考
config/context/references/sc-proxy.md - 營利（選用）：你建置的任何 HTTP 服務都可以透過
x402技能轉變為付費服務 — 一個位於未修改應用程式前的反向代理閘道，按呼叫/訂閱（週至年）/終身/預付餘額收取 Base 上的 USDC，並支援多方案。如果使用者提到要對專案收費、銷售 API 存取或代理對代理付款，請在建置階段後閱讀skills/x402/SKILL.md，並使用scripts/monetize.py包裝服務（暴露 GATEWAY 埠號，而非上游）。包裝後的完整付費服務鏈：preview(serve)閘道 →community-publish→publish_preview()（公開 URL）→create_paid_service(..., pricing_options=[...])→submit_for_review()（多方案服務：審查會透過X-Pricing-Model標頭探測每個方案的 402 金額）→publish_service()→ 在服務市場上線。詳情：community-publish SKILL.md § Paid service listing。 - 常駐服務（長時間執行/已發布/付費）：代理機器在閒置時會自動暫停，自動更新重新啟動會終止服務程序。任何必須 24/7 保持可達的服務需要：① 一個 keepalive 看門狗（排程任務重新啟動服務 — 請參閱
skills/x402/SKILL.md「Always-on availability」），② 將機器切換為手動更新模式（網頁儀表板切換；代理只能在機器內讀取模式 — 如果讀到「auto」，提醒使用者切換開關，否則下一次平台更新會使服務下線）。
Phase 3: DEBUG
檢查日誌 → 重現 → 隔離 → 診斷 → 修正 → 驗證 → 回歸測試
- 先檢查日誌 — 任務日誌、預覽診斷、標準錯誤輸出。如果日誌顯示明確原因，直接跳到修正。
- 僅在日誌不足時重現 — 親眼看到失敗
- 隔離哪一層出問題（資料？邏輯？LLM？輸出？前端？後端？）
- 修正根本原因，然後使用相同的重現步驟驗證。不要只修正 — 要修正並確認。
三振規則： 相同方法失敗兩次 → 停止 → 重新思考 → 向使用者解釋 → 採用不同方法。
→ 完整除錯程序：閱讀 references/debug-handbook.md
快速檢查清單
啟動： ☐ 釐清意圖 ☐ 提出架構 ☐ 估算成本 ☐ 使用者確認（Phase 2 前必要）
建置： ☐ 每個元件已測試 ☐ 數字與來源相符 ☐ 錯誤已處理 ☐ 預覽正常（網頁）
除錯： ☐ 已檢查日誌 ☐ 已重現（或跳過 — 日誌足夠）☐ 已隔離層級 ☐ 已找到根本原因 ☐ 已驗證修正 ☐ 已檢查回歸
