cf-yoyo 1.0.0

package/deep_todos.md

@@ -0,0 +1,766 @@
+# Cloudflare 專案腳手架 CLI 工具 - 規劃文件
+
+---
+
+## 0. 交付摘要（給人先看重點）
+
+| 欄位 | 內容 |
+|------|------|
+| **任務名稱** | Cloudflare 專案腳手架 CLI 工具規劃 |
+| **目前階段** | 規劃階段（初次建置） |
+| **推薦方案** | 方案 A：Commander.js + Inquirer.js 組合方案 |
+| **本輪主目標** | 建立可審閱的規劃文件，定義技術選型與實施路線 |
+| **本輪不做** | 實際代碼開發、測試、發布 |
+| **最大風險** | 技術選型與 Cloudflare 生態整合的相容性 |
+| **下一個關鍵動作** | 用戶確認推薦方案後，進入方案 A 的實施階段 |
+
+---
+
+## 1. 當前決策快照（給主 agent / 用戶快速判斷）
+
+### 1.1 已確定事項
+
+| 項目 | 決策內容 |
+|------|----------|
+| 技術語言 | Node.js + TypeScript |
+| 目標平台 | Cloudflare 相關專案腳手架 |
+| 核心功能 | 互動式問答、設定檔管理、日誌輸出、子命令結構 |
+| 專案原則 | 繁體中文、保持整潔、可閱讀性、代碼整潔、拒絕 demo |
+| 用戶環境 | 已有 Cloudflare 帳號，CLI 已配置完成 |
+
+### 1.2 待確認事項
+
+| 項目 | 問題 | 保守預設 |
+|------|------|----------|
+| 專案名稱 | CLI 工具的 npm 套件名稱 | `create-cf-project` 或 `cf-cli-scaffold` |
+| 支援的專案類型 | 要支援哪些 Cloudflare 產品類型 | Worker、Pages、D1、KV、R2 |
+| 模板來源 | 本地模板 vs 遠端 Git 倉庫 | 本地模板（優先），遠端模板（擴充） |
+| Node.js 版本 | 最低支援版本 | v18 LTS（保守預設） |
+
+### 1.3 本輪建議決策
+
+- **推薦方案**：方案 A（Commander.js + Inquirer.js）
+- **原因**：生態成熟、學習成本低、可快速實現生產級功能
+- **實施順序**：核心 CLI → 模板系統 → 配置管理 → 測試 → 發布
+
+---
+
+## 2. 任務背景與目標
+
+### 2.1 背景
+
+用戶需要一個類似 `create-cloudflare` 或 `create-next-app` 的 CLI 工具，用於快速產生 Cloudflare 相關專案的初始腳手架。此工具將幫助開發者：
+
+- 快速建立符合 Cloudflare 生態標準的專案結構
+- 自動配置 Cloudflare Workers、Pages、D1、KV、R2 等服務
+- 提供互動式導引，降低新手門檻
+- 統一團隊的專案初始化流程
+
+### 2.2 目標
+
+| 目標類型 | 具體描述 |
+|----------|----------|
+| 功能目標 | 實現互動式專案創建、多種專案類型支援、配置檔生成 |
+| 品質目標 | 生產環境標準、TypeScript 嚴格模式、完整測試覆蓋 |
+| 用戶體驗 | 清晰的終端輸出、友好的錯誤提示、可預期的行為 |
+| 維護目標 | 模組化設計、清晰的文件、易於擴展的架構 |
+
+---
+
+## 3. 範圍界定
+
+### 3.1 包含範圍（In Scope）
+
+#### 核心功能
+- [x] CLI 入口與子命令系統
+- [x] 互動式問答流程（專案名稱、類型、配置選項）
+- [x] 專案模板管理與檔案生成
+- [x] 設定檔初始化（wrangler.toml、tsconfig.json、package.json 等）
+- [x] 日誌輸出與終端美化
+- [x] 錯誤處理與用戶反饋
+
+#### 支援的專案類型
+- [x] Cloudflare Workers（基礎 Worker、Hono、itty-router）
+- [x] Cloudflare Pages（靜態站點、前端框架整合）
+- [x] 資料庫整合（D1 配置）
+- [x] 存儲整合（KV、R2 配置）
+
+#### 開發相關
+- [x] TypeScript 嚴格模式
+- [x] 單元測試與整合測試
+- [x] ESLint + Prettier 配置
+- [x] CI/CD 流程（GitHub Actions）
+- [x] npm 套件發布流程
+
+### 3.2 不包含範圍（Out of Scope）
+
+- [ ] 遠端模板倉庫的管理界面（僅支援 Git URL）
+- [ ] 專案部署功能（專注於腳手架生成）
+- [ ] 圖形化界面（GUI）版本
+- [ ] 雲端存儲的實際資料操作（僅生成配置）
+- [ ] 多語言支援（僅繁體中文與英文錯誤訊息）
+
+### 3.3 未來擴展（Future Scope）
+
+- [ ] 插件系統支援
+- [ ] 自定義模板倉庫
+- [ ] 專案更新機制（migrate）
+- [ ] VS Code 擴充套件
+
+---
+
+## 4. 約束、前提與保守預設
+
+### 4.1 技術約束
+
+| 約束項目 | 說明 |
+|----------|------|
+| Node.js 版本 | 最低 v18 LTS（保守預設），建議 v20+ |
+| 套件管理器 | 預設使用 npm，相容 pnpm/yarn |
+| TypeScript | 嚴格模式啟用，target ES2022 |
+| 依賴原則 | 優先使用成熟穩定的套件，避免實驗性技術 |
+
+### 4.2 環境前提
+
+| 前提項目 | 狀態 |
+|----------|------|
+| Cloudflare 帳號 | ✅ 用戶已有 |
+| Cloudflare CLI | ✅ 已連接帳號 |
+| R2 存儲桶 | ❌ 用戶沒有（不影響規劃） |
+| 手機電話號碼 | ❌ 用戶沒有（不影響 CLI 工具本身） |
+
+### 4.3 保守預設
+
+| 項目 | 預設值 | 說明 |
+|------|--------|------|
+| CLI 名稱 | `create-cf-project` | 可透過 `npm init` 或 `npx` 執行 |
+| 專案輸出目錄 | `./<project-name>` | 相對於當前工作目錄 |
+| 預設模板分支 | `main` | 遠端模板倉庫 |
+| 配置覆蓋行為 | 詢問用戶確認 | 避免意外覆蓋既有檔案 |
+| 日誌級別 | `info` | 支援 debug/info/warn/error |
+
+---
+
+## 5. 驗收視角
+
+### 5.1 功能驗收
+
+| 驗收項目 | 驗收標準 |
+|----------|----------|
+| CLI 基本運行 | `npx create-cf-project` 可正常啟動 |
+| 互動式問答 | 所有問題都有明確提示，輸入驗證正確 |
+| 專案生成 | 根據選項正確生成檔案結構 |
+| 模板渲染 | 變數替換正確，無遺漏 |
+| 錯誤處理 | 無效輸入、權限問題都有友好提示 |
+
+### 5.2 品質驗收
+
+| 驗收項目 | 驗收標準 |
+|----------|----------|
+| 測試覆蓋率 | 核心邏輯 >= 80% |
+| TypeScript | 無 `any` 類型，無編譯錯誤 |
+| 代碼風格 | ESLint + Prettier 無警告 |
+| 文件完整性 | README、API 文檔、使用範例齊全 |
+
+### 5.3 用戶體驗驗收
+
+| 驗收項目 | 驗收標準 |
+|----------|----------|
+| 首次執行 | 新用戶可在 5 分鐘內完成第一個專案創建 |
+| 錯誤訊息 | 中文或英文，明確指出問題與解決方案 |
+| 執行速度 | 基本專案創建 < 10 秒（不含 npm install） |
+
+---
+
+## 6. 完整任務拆解（WBS）
+
+### 6.1 Phase 1：專案基礎建設
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P1-T1 | 專案初始化與配置 | 2h | 無 | 架構師 | package.json、tsconfig.json、目錄結構 |
+| P1-T2 | ESLint + Prettier 配置 | 1h | P1-T1 | 開發者 | 配置文件、格式化腳本 |
+| P1-T3 | Git 倉庫初始化 | 0.5h | 無 | 開發者 | .gitignore、初始提交 |
+| P1-T4 | 開發環境配置 | 1h | P1-T1 | 開發者 | dev 腳本、hot reload |
+
+### 6.2 Phase 2：核心模組開發
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P2-T1 | CLI 入口與命令註冊 | 3h | P1 | 開發者 | 可執行的 CLI、help 輸出 |
+| P2-T2 | 互動式問答模組 | 4h | P2-T1 | 開發者 | Prompt 流程、輸入驗證 |
+| P2-T3 | 專案配置解析 | 3h | P2-T2 | 開發者 | 配置合併、預設值處理 |
+| P2-T4 | 檔案系統操作 | 3h | P2-T3 | 開發者 | 目錄創建、檔案寫入、衝突處理 |
+
+### 6.3 Phase 3：模板系統
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P3-T1 | 模板引擎設計 | 4h | P2 | 架構師 | 模板格式規範、變數語法 |
+| P3-T2 | 本地模板實現 | 6h | P3-T1 | 開發者 | Worker、Pages、D1 模板 |
+| P3-T3 | 遠端模板支援 | 4h | P3-T2 | 開發者 | Git 倉庫下載、快取機制 |
+| P3-T4 | 模板渲染引擎 | 4h | P3-T1 | 開發者 | 變數替換、條件渲染 |
+
+### 6.4 Phase 4：日誌與配置
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P4-T1 | 日誌系統設計 | 3h | P2 | 開發者 | 分級日誌、彩色輸出、靜默模式 |
+| P4-T2 | 進度指示器 | 2h | P4-T1 | 開發者 | spinner、進度條 |
+| P4-T3 | 全局配置管理 | 3h | P4-T1 | 開發者 | 用戶偏好儲存、配置檔讀取 |
+| P4-T4 | 錯誤處理與報告 | 3h | P4-T1 | 開發者 | 錯誤分類、友好提示 |
+
+### 6.5 Phase 5：測試與品質
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P5-T1 | 單元測試框架 | 2h | P2 | 測試工程師 | Vitest 配置、測試結構 |
+| P5-T2 | 核心邏輯測試 | 6h | P5-T1 | 測試工程師 | 問答、配置、檔案操作測試 |
+| P5-T3 | 整合測試 | 4h | P5-T2 | 測試工程師 | E2E CLI 測試 |
+| P5-T4 | 測試覆蓋率報告 | 2h | P5-T3 | 測試工程師 | Coverage >= 80% |
+
+### 6.6 Phase 6：發布與文件
+
+| 任務 ID | 任務名稱 | 工時估計 | 依賴 | 負責角色 | 產出/驗證 |
+|---------|----------|----------|------|----------|-----------|
+| P6-T1 | README 撰寫 | 2h | P3,P4 | 技術寫手 | 安裝、使用、配置說明 |
+| P6-T2 | API 文件 | 3h | P6-T1 | 技術寫手 | TypeDoc 生成、範例代碼 |
+| P6-T3 | CHANGELOG 機制 | 1h | P6-T1 | 開發者 | 版本記錄規範 |
+| P6-T4 | CI/CD 配置 | 3h | P5 | DevOps | GitHub Actions、自動測試、發布 |
+| P6-T5 | npm 發布 | 1h | P6-T4 | 維護者 | 套件發布、tag 管理 |
+
+---
+
+## 7. 依賴、關鍵路徑與里程碑
+
+### 7.1 依賴圖
+
+```
+P1 (基礎建設)
+  │
+  ├─→ P2 (核心模組)
+  │     │
+  │     ├─→ P3 (模板系統)
+  │     │
+  │     └─→ P4 (日誌配置)
+  │           │
+  └───────────┴─→ P5 (測試品質)
+                        │
+                        └─→ P6 (發布文件)
+```
+
+### 7.2 關鍵路徑
+
+**P1 → P2 → P3 → P5 → P6**
+
+總工時估計：約 60 小時
+
+### 7.3 里程碑
+
+| 里程碑 | 預計完成 | 交付物 | 驗收標準 |
+|--------|----------|--------|----------|
+| M1 - 基礎就緒 | Day 1-2 | 專案結構、開發環境 | 可執行 `npm run dev` |
+| M2 - 核心可用 | Day 5-7 | CLI 基本流程、問答功能 | 可交互創建簡單專案 |
+| M3 - 模板完成 | Day 10-12 | 多類型模板支援 | Worker、Pages 模板可用 |
+| M4 - 品質達標 | Day 14-16 | 測試覆蓋率達標 | Coverage >= 80% |
+| M5 - 發布就緒 | Day 17-18 | npm 套件發布 | 可透過 npx 安裝使用 |
+
+---
+
+## 8. 方案 A：Commander.js + Inquirer.js（推薦）
+
+### 8.1 核心思路
+
+使用業界最成熟的 CLI 框架組合：
+- **Commander.js**：處理命令解析、子命令、選項
+- **Inquirer.js**：處理互動式問答、輸入驗證
+- **Chalk + Ora**：美化終端輸出、顯示進度
+
+### 8.2 技術架構
+
+```
+src/
+├── index.ts           # CLI 入口
+├── commands/
+│   ├── create.ts      # create 子命令
+│   ├── list.ts        # list 子命令
+│   └── init.ts        # init 子命令
+├── prompts/
+│   ├── project.ts     # 專案相關問題
+│   ├── template.ts    # 模板選擇問題
+│   └── config.ts      # 配置相關問題
+├── templates/
+│   ├── worker/        # Worker 模板
+│   ├── pages/         # Pages 模板
+│   └── shared/        # 共享模板
+├── utils/
+│   ├── logger.ts      # 日誌工具
+│   ├── fs.ts          # 檔案操作
+│   └── git.ts         # Git 操作
+└── types/
+    └── index.ts       # TypeScript 類型定義
+```
+
+### 8.3 主要套件
+
+| 套件名稱 | 用途 | 版本策略 |
+|----------|------|----------|
+| commander | 命令解析 | ^11.x |
+| inquirer | 互動問答 | ^9.x |
+| chalk | 終端顏色 | ^5.x |
+| ora | 載入指示器 | ^7.x |
+| execa | 進程執行 | ^8.x |
+| fs-extra | 檔案操作 | ^11.x |
+| mustache | 模板渲染 | ^4.x |
+
+### 8.4 優點
+
+1. **生態成熟**：Commander.js 和 Inquirer.js 是 Node.js CLI 的標準方案
+2. **學習成本低**：大量文件、範例、Stack Overflow 資源
+3. **維護穩定**：核心貢獻者活躍，版本更新穩定
+4. **類型支援**：均有完善的 TypeScript 類型定義
+5. **可擴展性**：插件機制成熟，易於自定義
+
+### 8.5 代價
+
+1. **套件體積**：依賴較多，node_modules 較大（約 10-15MB）
+2. **版本鎖定**：需定期更新以獲得安全修復
+3. **自定義限制**：框架約束下的自定義需要額外工作
+
+### 8.6 主要風險
+
+| 風險 | 影響 | 緩解措施 |
+|------|------|----------|
+| 套件棄用 | 中 | 選擇維護活躍的套件 |
+| 版本衝突 | 低 | 鎖定版本範圍 |
+| 效能問題 | 低 | CLI 工具對效能要求不高 |
+
+### 8.7 不適用情境
+
+- 極度輕量需求（< 100 行代碼）
+- 需要完全自定義的命令解析邏輯
+- 對套件體積有嚴格限制（< 1MB）
+
+### 8.8 對應 WBS 任務
+
+- P2-T1（CLI 入口）：使用 Commander.js 實現
+- P2-T2（互動問答）：使用 Inquirer.js 實現
+- P4-T1（日誌系統）：使用 Chalk + Ora 實現
+- P3-T4（模板渲染）：使用 Mustache 實現
+
+---
+
+## 9. 方案 B：基於 create-cloudflare 擴展
+
+### 9.1 核心思路
+
+基於 Cloudflare 官方的 `create-cloudflare`（C3）工具進行擴展或封裝：
+- 複用官方模板和配置邏輯
+- 添加自定義的互動流程和模板
+- 保持與官方生態的相容性
+
+### 9.2 技術架構
+
+```
+src/
+├── index.ts
+├── wrappers/
+│   └── c3.ts          # C3 調用包裝
+├── extensions/
+│   ├── templates/     # 自定義模板
+│   └── prompts/       # 擴展問答
+└── utils/
+    └── patch.ts       # C3 行為補丁
+```
+
+### 9.3 主要套件
+
+| 套件名稱 | 用途 |
+|----------|------|
+| create-cloudflare | 官方 CLI（作為依購或參考） |
+| wrangler | Cloudflare 官方 SDK |
+| 自定義實現 | 擴展模板和流程 |
+
+### 9.4 優點
+
+1. **官方相容**：自動獲得官方更新和安全修復
+2. **生態一致**：與 Cloudflare 官方工具行為一致
+3. **維護輕量**：核心邏輯由官方維護
+4. **功能完整**：繼承 C3 的所有功能
+
+### 9.5 代價
+
+1. **耦合度高**：依賴官方工具的生命週期
+2. **自定義受限**：只能在其框架內擴展
+3. **學習曲線**：需要深入理解 C3 內部實現
+4. **版本跟隨**：官方更新可能破壞自定義功能
+
+### 9.6 主要風險
+
+| 風險 | 影響 | 緩解措施 |
+|------|------|----------|
+| API 變更 | 高 | 鎖定 C3 版本 |
+| 功能受限 | 中 | 評估擴展能力 |
+| 除錯困難 | 中 | 封裝層隔離 |
+
+### 9.7 不適用情境
+
+- 需要完全自定義的用戶體驗
+- 需要支援非 Cloudflare 官方產品
+- 對官方工具行為不滿意
+
+### 9.8 對應 WBS 任務
+
+- P2-T1（CLI 入口）：調用 C3 或包裝 C3
+- P3-T2（本地模板）：在 C3 模板系統上擴展
+- P4-T1（日誌系統）：可能受限於 C3 的輸出
+
+---
+
+## 10. 方案 C：自建輕量級 CLI 框架
+
+### 10.1 核心思路
+
+從零開始建立輕量級 CLI 框架：
+- 自定義命令解析器
+- 簡化的互動式輸入
+- 模板系統自建
+- 完全控制所有環節
+
+### 10.2 技術架構
+
+```
+src/
+├── index.ts
+├── cli/
+│   ├── parser.ts      # 命令解析器
+│   ├── runner.ts      # 命令執行器
+│   └── help.ts        # 幫助生成
+├── ui/
+│   ├── prompt.ts      # 問答實現
+│   ├── spinner.ts     # 載入指示
+│   └── color.ts       # 顏色輸出
+├── templates/
+│   ├── engine.ts      # 模板引擎
+│   └── loader.ts      # 模板載入
+└── utils/
+    └── fs.ts
+```
+
+### 10.3 主要套件
+
+| 套件名稱 | 用途 |
+|----------|------|
+| 最小依賴 | 僅使用 Node.js 內建模組 |
+| picocolors | 輕量級終端顏色（可選） |
+
+### 10.4 優點
+
+1. **零依賴**：node_modules 極小（< 100KB）
+2. **完全控制**：無框架限制，可實現任意功能
+3. **深度優化**：可針對特定需求極致優化
+4. **學習價值**：深入理解 CLI 工具實現
+
+### 10.5 代價
+
+1. **開發成本高**：需自行實現所有基礎功能
+2. **維護負擔**：所有 bug 修復和功能更新需自行處理
+3. **測試負擔**：需自行測試邊界情況和兼容性
+4. **文件缺失**：無現成文件，需自行撰寫
+
+### 10.6 主要風險
+
+| 風險 | 影響 | 緩解措施 |
+|------|------|----------|
+| 開發延遲 | 高 | 預留充足時間 |
+| 邊界 bug | 高 | 完整測試覆蓋 |
+| 功能缺失 | 中 | 對照現有工具 |
+
+### 10.7 不適用情境
+
+- 時間或資源有限
+- 團隊缺乏 CLI 開發經驗
+- 需要快速上線
+- 維護資源有限
+
+### 10.8 對應 WBS 任務
+
+- P2-T1（CLI 入口）：完全自建
+- P2-T2（互動問答）：自建或使用 readline
+- P4-T1（日誌系統）：自建實現
+- P3-T4（模板渲染）：自建簡單模板引擎
+
+---
+
+## 11. 方案對比與推薦決策
+
+### 11.1 對比矩陣
+
+| 維度 | 方案 A<br>Commander+Inquirer | 方案 B<br>基於 C3 | 方案 C<br>自建框架 |
+|------|---------------------------|------------------|-------------------|
+| **開發速度** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ |
+| **維護成本** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
+| **自定義程度** | ⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **學習曲線** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |
+| **生態支援** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ |
+| **套件體積** | ⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
+| **長期穩定性** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
+| **風險等級** | 低 | 中 | 高 |
+
+### 11.2 推薦方案
+
+**推薦：方案 A（Commander.js + Inquirer.js）**
+
+### 11.3 推薦原因
+
+1. **風險最低**：成熟的生態意味著較少的未知問題
+2. **開發效率**：預計可節省 40% 的開發時間
+3. **團隊友好**：易於理解和維護
+4. **生產就緒**：預設就是生產級標準
+5. **擴展靈活**：雖有框架約束，但仍有充足自定義空間
+
+### 11.4 不推薦其他方案的原因
+
+- **方案 B**：過度耦合官方工具，自定義空間有限，且可能受官方更新影響
+- **方案 C**：開發成本高、風險大、維護負擔重，不適合生產環境首選
+
+### 11.5 用戶未指定時的保守預設
+
+若用戶沒有明確偏好，**一律採用方案 A**。
+
+---
+
+## 12. 實施輪廓（至少 2 套可直接採用）
+
+### 12.1 實施輪廓 1：標準路線（推薦）
+
+**適用條件**：通用場景，無特殊限制
+
+**實施順序**：
+
+| 順序 | 階段 | 主要工作 | 預期交付 |
+|------|------|----------|----------|
+| 1 | 基礎建設 | 專案初始化、工具鏈配置 | 可開發的專案結構 |
+| 2 | 核心 CLI | Commander + Inquirer 整合 | 可交互的基礎 CLI |
+| 3 | 模板系統 | 本地模板、渲染引擎 | Worker/Pages 模板可用 |
+| 4 | 完善功能 | 日誌、配置、錯誤處理 | 生產級功能完整 |
+| 5 | 測試品質 | 單元測試、整合測試 | Coverage >= 80% |
+| 6 | 發布就緒 | 文件、CI/CD、發布 | npm 套件上線 |
+
+**前置工作**：
+- 確認專案名稱
+- 確認 npm 組織/發布帳號
+- 準備 Git 倉庫
+
+**預期交付**：
+- 生產級 CLI 工具
+- 完整的測試覆蓋
+- 完善的文件
+- npm 可安裝套件
+
+### 12.2 實施輪廓 2：精簡路線（MVP 優先）
+
+**適用條件**：需要快速驗證概念，後續迭代完善
+
+**實施順序**：
+
+| 順序 | 階段 | 主要工作 | 預期交付 |
+|------|------|----------|----------|
+| 1 | 快速原型 | 最小可行 CLI | 能創建 Worker 專案 |
+| 2 | 核心功能 | 基本問答、檔案生成 | Worker/Pages 支援 |
+| 3 | 品質閘門 | 基礎測試、Lint | 無編譯錯誤 |
+| 4 | 發布 MVP | README、npm 發布 | 可用版本上線 |
+| 5 | 迭代增強 | 高級功能、更多模板 | 功能逐步完善 |
+| 6 | 品質提升 | 完整測試、文件 | 生產級標準 |
+
+**前置工作**：
+- 定義 MVP 範圍（僅 Worker 模板）
+- 準備最小可運作環境
+
+**預期交付**：
+- MVP 版本 CLI（Week 1-2）
+- 完整版本（Week 4-6）
+
+---
+
+## 13. 需要主 agent 回問用戶的事項
+
+### 13.1 高優先級問題
+
+| 問題 | 為什麼要問 | 不問時的保守預設 |
+|------|-----------|------------------|
+| **CLI 工具的確切名稱？** | 影響 package.json name、bin 欄位、npm 發布 | `create-cf-project` |
+| **預設支援哪些專案類型？** | 影響模板設計和問答流程 | Worker、Pages、D1、KV |
+| **是否需要國際化支援？** | 影響 UI 文字和錯誤訊息設計 | 僅繁體中文 + 英文錯誤 |
+| **預期的 Node.js 最低版本？** | 影響語法選擇和依賴版本 | v18 LTS |
+
+### 13.2 中優先級問題
+
+| 問題 | 為什麼要問 | 不問時的保守預設 |
+|------|-----------|------------------|
+| **是否支援遠端模板？** | 影響模板系統架構 | 先本地，遠端作為擴充 |
+| **是否需要插件系統？** | 影響核心架構設計 | 第一版不支援 |
+| **CI/CD 平台偏好？** | 影響 DevOps 配置 | GitHub Actions |
+| **是否開源？** | 影響許可證和倉庫設定 | 開源（MIT） |
+
+### 13.3 建議
+
+**建議主 agent 在進入實作前，至少確認高優先級問題**，以避免後續大規模重構。
+
+---
+
+## 14. 風險、回滾與阻塞訊號
+
+### 14.1 風險清單
+
+| 風險 ID | 風險描述 | 機率 | 影響 | 緩解策略 |
+|---------|----------|------|------|----------|
+| R1 | 套件版本相容性問題 | 中 | 中 | 鎖定版本範圍、定期更新測試 |
+| R2 | Cloudflare API 變更 | 低 | 高 | 追蹤官方更新、抽象 API 層 |
+| R3 | 模板維護負擔 | 中 | 中 | 建立模板更新流程、版本管理 |
+| R4 | 用戶環境差異（Windows/Linux/macOS） | 中 | 中 | CI 多平台測試 |
+| R5 | 命名衝突或商標問題 | 低 | 高 | 確認 npm 名稱可用性 |
+| R6 | 開發時程延遲 | 中 | 中 | 分階段交付、MVP 優先 |
+
+### 14.2 回滾策略
+
+| 情境 | 回滾動作 |
+|------|----------|
+| 套件選型錯誤 | 重構到方案 B 或 C，評估成本後決策 |
+| 架構設計問題 | 保留 interface，重構實現 |
+| 模板系統問題 | 回退到簡單的字串替換 |
+| npm 發布問題 | 撤回版本、修復後重新發布 |
+
+### 14.3 阻塞訊號
+
+出現以下情況應立即停止並回報：
+
+- 🚫 **阻塞**：npm 套件名稱不可用或侵權
+- 🚫 **阻塞**：Cloudflare CLI 連接失效
+- ⚠️ **警告**：核心依賴套件發布棄用聲明
+- ⚠️ **警告**：測試覆蓋率持續無法達標
+
+---
+
+## 15. 對映到 todos.md 的執行批次
+
+### 15.1 建議的 todos.md 結構
+
+```markdown
+# Cloudflare CLI 工具開發任務
+
+## Phase 1: 專案基礎建設
+- [ ] P1-T1: 專案初始化與配置
+- [ ] P1-T2: ESLint + Prettier 配置
+- [ ] P1-T3: Git 倉庫初始化
+- [ ] P1-T4: 開發環境配置
+
+## Phase 2: 核心模組開發
+- [ ] P2-T1: CLI 入口與命令註冊 (Commander.js)
+- [ ] P2-T2: 互動式問答模組 (Inquirer.js)
+- [ ] P2-T3: 專案配置解析
+- [ ] P2-T4: 檔案系統操作
+
+## Phase 3: 模板系統
+- [ ] P3-T1: 模板引擎設計
+- [ ] P3-T2: 本地模板實現 (Worker/Pages)
+- [ ] P3-T3: 遠端模板支援 (Git)
+- [ ] P3-T4: 模板渲染引擎 (Mustache)
+
+## Phase 4: 日誌與配置
+- [ ] P4-T1: 日誌系統設計 (Chalk + Ora)
+- [ ] P4-T2: 進度指示器
+- [ ] P4-T3: 全局配置管理
+- [ ] P4-T4: 錯誤處理與報告
+
+## Phase 5: 測試與品質
+- [ ] P5-T1: 單元測試框架 (Vitest)
+- [ ] P5-T2: 核心邏輯測試
+- [ ] P5-T3: 整合測試 (E2E)
+- [ ] P5-T4: 測試覆蓋率報告
+
+## Phase 6: 發布與文件
+- [ ] P6-T1: README 撰寫
+- [ ] P6-T2: API 文件 (TypeDoc)
+- [ ] P6-T3: CHANGELOG 機制
+- [ ] P6-T4: CI/CD 配置 (GitHub Actions)
+- [ ] P6-T5: npm 發布
+
+## 里程碑
+- [ ] M1: 基礎就緒
+- [ ] M2: 核心可用
+- [ ] M3: 模板完成
+- [ ] M4: 品質達標
+- [ ] M5: 發布就緒
+```
+
+### 15.2 執行批次建議
+
+| 批次 | 任務 | 估計工時 | 負責角色 |
+|------|------|----------|----------|
+| Batch 1 | P1 全部 + P2-T1 | 6h | 架構師/開發者 |
+| Batch 2 | P2-T2 ~ P2-T4 | 10h | 開發者 |
+| Batch 3 | P3 全部 | 14h | 開發者 |
+| Batch 4 | P4 全部 | 11h | 開發者 |
+| Batch 5 | P5 全部 | 14h | 測試工程師 |
+| Batch 6 | P6 全部 | 10h | 技術寫手/DevOps |
+
+---
+
+## 16. 文件同步規則
+
+### 16.1 同步機制
+
+| 來源文件 | 同步目標 | 同步時機 | 規則 |
+|----------|----------|----------|------|
+| deep_todos.md | todos.md | 每次決策變更 | WBS 任務同步 |
+| deep_todos.md | 技術文件 | 方案確定後 | 架構決策同步 |
+| todos.md | deep_todos.md | 進度更新時 | 里程碑狀態同步 |
+
+### 16.2 版本控制
+
+- 本文件版本：`v1.0.0`
+- 建立日期：2025-04-09
+- 更新日誌：記錄於文件底部
+
+### 16.3 更新權限
+
+| 章節 | 可更新角色 | 備註 |
+|------|-----------|------|
+| 0-2（摘要、決策、背景） | 主 agent、規劃師 | 需用戶確認 |
+| 3-7（範圍、約束、驗收、WBS、里程碑） | 規劃師 | 依需求變更更新 |
+| 8-12（方案、對比、實施） | 規劃師、架構師 | 技術決策變更時更新 |
+| 13-16（回問、風險、批次、同步） | 任何 subagent | 發現新資訊時更新 |
+
+---
+
+## 附錄 A：技術參考
+
+### A.1 參考專案
+
+| 專案名稱 | 用途 | 連結 |
+|----------|------|------|
+| create-cloudflare | 官方 CLI | https://github.com/cloudflare/workers-sdk/tree/main/packages/create-cloudflare |
+| create-next-app | 參考架構 | https://github.com/vercel/next.js/tree/canary/packages/create-next-app |
+| commander.js | CLI 框架 | https://github.com/tj/commander.js |
+| inquirer.js | 互動問答 | https://github.com/SBoudrias/Inquirer.js |
+
+### A.2 命名建議
+
+| 名稱類型 | 建議名稱 | 備註 |
+|----------|----------|------|
+| 套件名稱 | `create-cf-project` | 遵循 `create-*` 慣例 |
+| bin 命令 | `create-cf-project` | 與套件名一致 |
+| 縮寫別名 | `cf-create` | 可選快捷命令 |
+
+---
+
+## 更新日誌
+
+| 版本 | 日期 | 變更內容 | 作者 |
+|------|------|----------|------|
+| v1.0.0 | 2025-04-09 | 初次建立，包含完整規劃結構與三個方案分析 | Deep Todos |
+
+---
+
+*本文件由 Deep Todos 規劃 subagent 建立，遵循 AGENTS.md 規範與 deep_todos.template.md 模板結構。*