[P1/Usability] 非技術使用者的本機開箱即用：安裝包、首次引導、診斷與看得懂的結果

[frankekn]

使用者故事／完成定義

「我不是工程師。我下載並開啟 Needlefish，選專案資料夾、登入 AI 服務，按『開始檢查』就能看到問題與下一步；不必安裝 Node/pnpm、改 PATH、編輯 JSON／環境變數或懂 Git SHA。」

這是產品優先級 P1，不代表已發現 P1 資安漏洞。只新增 npx needlefish setup 或補 README 不算完成此 issue；CLI 精靈可以是共用底層，但必須有真正不需終端機的受支援入門路徑。

現況依據

基準 main@d333e4e：

• README Quick start 的本機路徑要求 Node 20+ 和已登入且在 PATH 上的 runner。
• src/cli.ts 已有 review/dry-run/cached diagnostics，但沒有一條完整的安裝、登入、專案選擇與排錯引導。
• 現有 core/adapter 可以重用，不需要為此重寫 review engine。

最小可交付方案

A. 一個推薦安裝包，不展示七種 runner 選擇

1. 先交付一個完整受支援的桌面 OS/架構路徑，再擴大支援；在下載頁清楚列出支援矩陣，未測平台不宣稱可用。第一個平台應有 clean-machine 安裝測試，不以開發者原機成功代替。
2. 安裝包包含所需 runtime，或由安裝器以受控、固定版本方式安裝到 Needlefish 自有目錄；不要求使用者處理 Node、pnpm、PATH 或 build。Git 與推薦 runner 同樣偵測／受控安裝，支援的授權、再散布與認證方式必須先查證。
3. 只帶一個受測的推薦 runner/model 組合；進階選擇可延後。安裝／下載／更新必須告知並取得同意，驗證來源與發行完整性；不得叫使用者關閉 OS 安全提示或執行不透明提權命令。
4. 升級可恢復上一個可用版本，不偷偷換 provider／計費帳戶；提供完整解除安裝與清除 Needlefish 自有資料的選项，不刪既有 Git／runner 的其他設定。

B. 薄介面＋共用 setup/doctor 邏輯

1. 採一個輕量啟動介面重用現有 TypeScript core：下載／開啟 → 檢查環境 → 選資料夾 → 登入 → 顯示檢查範圍與資料送往哪個服務 → 開始。不要另建 review backend。
2. CLI setup／doctor（命名可調）與畫面共用一份純資料診斷：可用版本、認證狀態、repo 狀態、權限、容量、runner capability。診斷預設不送程式碼、不呼叫計費模型；可能產生費用的測試另行確認。
3. 可使用簡單 native launcher 或隨程式啟動的 loopback HTML 頁面，擇一即可。若用本機 web：僅 loopback、隨機埠、一次性 session、防 CSRF/Origin/Host 檢查、退出即關閉；不提供任意 shell/API，不綁 0.0.0.0，不載入外部追蹤脚本。
4. 認證沿用供應商正式登入／device flow；無正式瀏覽器登入時明確提供一次性的安全 key 輸入說明，不讓使用者找 auth.json。秘密用供應商既有安全儲存或 OS keychain，不進 repo、command history、URL 或診斷包。不得索取供應商帳號密碼。
5. 一般人畫面只看到一個推薦路徑與『進階設定』；有效組態的選擇優先順序集中管理。已正常使用的 CLI／非互動 CI 不跳出對話框、不被自動改設定。

C. 從第一個錯誤到第一份真實結果

• 沒有 Git repo：說明未初始化，不自動 git init／commit／改專案；經明確同意才能做另一步初始化。沒有變更：顯示「沒有可檢查的變更」，不是錯誤，也不是全專案已驗證安全。
• 未登入、帳戶額度不足、網路失敗、runner 版本不相容：每種狀態提供一個清楚的修復動作。不能用假結果代替真實審查。
• 未提交變更明說將检查所選時點的副本，與 [P2] Pin uncommitted review snapshots and expose valid sandbox revisions #101 的固定快照配合；多個工作目錄／子 repo 不要默默選错。
• 無帳戶可使用明標示為離線範例的 demo，零模型呼叫、與真實 review cache 分開。不得顯示成使用者專案已通過。
• 真正開始前揭露程式碼傳送目的地、可能費用、覆蓋範圍與可取消操作。不知道金額時說未知，不能捏造預估。顯示階段進度而非虛假的百分比。
• 結果先顯示「沒有阻擋問題／找到問題／未完成」，再列問題影響、位置、建議下一步；技術細節可展開，繁體中文與英文說明一致。不提供自動修復／自動合併。
• 取消能停止工作、清除本次暫存；產生可預覽、使用者主動匯出的遮蔽診斷包。不得自動上傳程式碼、原始 prompt、token、絕對私有路徑或帳戶資料。

安全邊界要說清楚

現有 sandbox 是 throwaway clone＋事後完整性檢查，不是 OS 隔離（見 runner-sandbox.ts）。本機推薦模式限定使用者信任的自有專案；不得標成可安全執行任意陌生程式。保留 token stripping／唯讀提示／完整性檢查，不在此項開放執行 repo tests/scripts。真正的敵對程式隔離或測試 worker 是另項安全設計，不是安裝必要的 Docker/Kubernetes 前置作業。

驗收

• 受支援平台的乾淨機器，沒有 Node/pnpm/runner 時仍能走完安裝，不要求手動 PATH／環境變數／編譯。
• 5 位沒有程式開發經驗、但有測試專案與可用帳戶的試用者，至少 4 位只靠畫面與入門文件完成安裝、登入、首次真實檢查並說對結果含義；記錄卡關點，不用開發者口頭帶操作。
• 安裝、登入取消、缺額度、缺網路、無變更、非 repo、超時、取消、升級失敗與解除安裝有 end-to-end 測試。
• 未登入的 demo 不被誤認為真實審查；首次付費呼叫有明確同意。
• UI/CLI 使用同一個 core 與診斷 owner；[P1] 未完成審查不得通過合併閘門：統一 needs_human 的 check 與退出狀態 #145/[P2] 依 runner 能力選擇審查流程，禁止無 repo 工具的 HTTP lane 宣稱完成 deep review #146 的失敗／能力限制在畫面正確呈現。
• 自動測試用 stub provider；release 才做受控真實 canary，使用者安裝不用跑完整 eval。

防止過度工程

第一版只做一個 OS 路徑、一個推薦 runner、一個資料夾、一次 review、一個小型設定位置。不要新增 SaaS 帳戶系統、常駐 daemon、遠端資料庫、插件平台、全新前端框架、多專案儀表板或所有 provider 的自製登入系統。不要把其他所有架構 issue 都設成此项開發前置；可平行做介面，但出貨前需驗證相關安全／正確性 gate。