【2026 最新】Huzzah 教學：把 Prompt 變成可追溯偽代碼的 5 步工作流

你一定遇過這種情況：昨天和 AI 把需求聊得很清楚，今天換一個對話，原本的決策理由、例外條件與驗收方式又得重講一次。這篇 Huzzah 教學要處理的，是「意圖容易散落在聊天紀錄與其他文件，未必形成一份精簡、持續維護的 intent/source 對照」這個問題。

Huzzah 嘗試把人寫的偽代碼保留下來，讓 AI 依照每次修改提出新版 JavaScript，再由人檢查差異、假設與逐行對照後決定接受或拒絕。本文專為第一次接觸這類工具的讀者寫：你會從安裝開始，設計三輪可重做的修改與驗收，最後知道它何時有價值、何時應該改用 Git、spec、ADR 或測試。

先說清楚驗證範圍：AlphaLab 以 2026 年 8 月 20 日的固定版本 commit 4c9c826 完成安裝、靜態檢查、Web／Electron build 與本機 UI 啟動；由於執行環境未配置模型憑證，本文不把下列三輪操作包裝成已取得的生成結果，而是提供你可在自己的 provider 上逐項打勾的驗收腳本。

先說結論

Huzzah ＝ 持久 Intent（人寫的意圖）＋ Reconcile（AI 對齊）＋ Review（人類驗收）。

把偽代碼想成可以持續修改的施工圖，AI 產生的 JavaScript 是施工結果，而逐行對照只是「哪段圖可能對應哪段成品」的索引。索引方便巡查，卻不是結構安全證明。固定版本的 REPL 只執行已接受的 committed source：先用 diff、summary 與 assumptions 人工審查提案，明顯不對就 Reject；其餘先 Accept，再用 acceptance tests（驗收測試）驗證。測試沒過，就修改 intent 開下一輪修正。

Huzzah 是什麼？先拆掉三個容易誤會的詞

Huzzah 是一個實驗性介面：左側保存 free-form pseudocode（沒有固定文法的偽代碼），按下 Sync 後，伺服器把舊意圖、新意圖、兩者 diff（改動前後的差異）與目前已接受的完整 source 交給 Pi 所配置的 provider（模型服務商或本機模型）；模型依照固定版本的 reconcile 合約回傳一份完整 ES module（可載入的 JavaScript 模組）、摘要、假設與意圖到程式碼的逐行對照。你按 Accept 之後，新提案才會成為 committed source（目前已接受版本）；按 Reject 則保留舊版，draft intent 仍可繼續修改或重試。

這個 Accept／Reject 邊界很重要：畫面上的 proposed source 只是候選，REPL 仍指向上一份 committed source，直到你接受才一起推進 intent、source、mapping 與 revision。換句話說，Huzzah 的 accepted revision 核心是「人最後同意哪一組意圖與實作」，並同時保存該次 summary、assumptions、mapping、model 與 usage。這比把最新回答直接覆蓋舊檔多了一道決策點，但仍必須用外部測試證明行為。

• 它不是 compiler：偽代碼不是形式語言，同一句話仍可能讓模型做出不同決策。
• 它的 source map 不是瀏覽器除錯器的標準 source map：目前是工具自訂的 intent line → generated line ranges 對照；行號合法不等於語意正確。
• 瀏覽器保存不等於 Git 版控：固定版本的 client state把 workspace 與 revisions 存在 LocalForage（把資料存進瀏覽器的工具）。只要該 origin 的瀏覽器儲存區未被清除，就能在同一 browser profile 回看；它不提供 Git 的 branch、commit author、remote backup 與協作審查。

這個定位和 Specification-first convergence 的方向相近，差別是 Huzzah 把「可編輯意圖 → AI 候選碼 → 人工接受」做成一個具體介面。若你正在建立完整的 Agent 工程系統，還需要 AGENTS.md 的規則與 gates、Git、測試與觀測性共同補位。

Huzzah 教學 Step 1：安裝並先確認環境

痛點：如果工具本身沒跑起來，後面看到的錯誤很容易被誤判成模型問題。解法：先依官方 README 安裝，再切到本文固定 commit，並額外執行 repo 提供的靜態檢查，把環境檢查和 AI reconcile 分開。

git clone https://github.com/danielvaughn/hz.git
cd hz
git checkout --detach 4c9c8263910ca3a7c287882d270164b857841794
npm install
npm run check
npm run dev

固定版本的 README 要求 Node.js 22.19 以上。終端顯示開發伺服器後，打開它列出的 Local URL（預設通常是 http://localhost:5173）；首次且尚未關閉 onboarding 時會看到 Welcome modal，否則確認雙欄 editor 正常顯示即可。

Huzzah 透過 Pi 使用你配置的 provider。若你採訂閱登入，官方流程是先執行：

npx --workspace=poc pi

接著在 Pi 輸入 /login、選擇 provider、完成登入後退出，再執行 npm run dev。API key 或本機模型則應依 Pi 的 models 設定文件配置；不要把密鑰寫進偽代碼。

Huzzah 教學 Step 2：只做一個可判定對錯的小函式

痛點：「幫我做購物車」太大，失敗時不知道是需求、模型還是執行環境出了問題。解法：第一輪只定義一個 export、一種輸入與兩個可算出的結果。把下面內容貼到 intent editor：

Create an exported function quote(order).
order has subtotal and quantity.
Shipping is 80.
Total is subtotal plus shipping.
Return an object with subtotal, shipping, and total.

按 Sync 後先別急著 Accept。審查 summary 與 assumptions，確認模型沒有自行加入稅率、幣別、會員規則或外部套件；再看 source diff 是否只圍繞 quote 的責任。有明顯問題就 Reject、修改 intent 再 Sync；人工閱讀提案、未發現明顯問題後才按 Accept。因為 REPL 只載入 committed source，接受後再把下列陣列整段貼進 REPL（輸入 JavaScript 後立即看到結果的互動測試區）：

[
  quote({ subtotal: 900, quantity: 1 }).total === 980,
  quote({ subtotal: 0, quantity: 1 }).shipping === 80
]

畫面回傳 [true, true] 才代表目前已接受的基準版本符合這兩個案例。若失敗，就把原因寫回 intent，重新 Sync、審查與 Accept；Huzzah 不會把剛接受的 proposal 自動退回 pending。這不是在證明所有輸入都正確，而是先建立一個之後不應被改壞的最小檢查點。想把這種「先定義可觀察結果」做成完整系統，可搭配 AI Evals 教學。

建議另外開一份實驗紀錄，每輪只寫五格：intent 改了哪一句、模型新增哪些 assumptions、Accept 前的 Review 決策、Accept 後的新舊測試結果、下一步是保留或再開修正輪。Huzzah 的 revision 適合在介面內回看，這份外部紀錄則讓同事知道你為何放行，也避免瀏覽器資料被清除後只剩生成碼。若要正式併入 repo，再把可執行案例改成測試檔並交給 CI。

Step 3：連改三次偽代碼，每次只接受一個行為變化

修改一：加入會員九折

痛點：一次加入多條價格規則，出錯時很難定位。解法：這輪只加入會員九折；在原意圖後貼上：

order may also have a boolean member.
If member is omitted, treat it as false.
If member is true, apply a 10% discount to subtotal.
Shipping is calculated after the discount.

這裡故意保留一個歧義：「金額何時四捨五入？」先看 assumptions 是否主動說明；沒說就 Reject，補上 Round each money amount to the nearest integer 再 Sync。完成提案人工審查並 Accept 後，把以下陣列整段貼進 REPL，第三式專門檢查 rounding：

[
  quote({ subtotal: 1000, quantity: 1, member: true }).total === 980,
  quote({ subtotal: 1000, quantity: 1, member: false }).total === 1080,
  quote({ subtotal: 999, quantity: 1, member: true }).total === 979
]

修改二：折扣後滿 1,000 才免運

痛點：免運門檻容易在折扣前後算錯。解法：明寫以折扣後小計判斷；把固定運費那行改成：

Shipping is free when the discounted subtotal is at least 1000.
Otherwise shipping is 80.

關鍵不是只測「有沒有免運」，而是用門檻兩側抓出計算順序。完成 Review 並 Accept 新提案後，把以下陣列整段貼進 REPL：

[
  quote({ subtotal: 1200, quantity: 1, member: true }).total === 1080,
  quote({ subtotal: 1100, quantity: 1, member: true }).total === 1070,
  quote({ subtotal: 1000, quantity: 1, member: false }).total === 1000
]

第二式若算成 990，表示程式可能在折扣前判斷免運。這正是「自然語言看似合理，執行結果卻不同」的典型錯誤。

新規格也取代一個舊期望：非會員、subtotal 為 1,000 的 total 應從 1,080 改為 1,000，因為折扣後小計正好達到免運門檻。這不是 regression，而是有意改寫的行為；實驗紀錄要明寫變更原因。

修改三：把非法輸入寫成規則

痛點：正常案例通過，不代表非法輸入會被明確拒絕。解法：明寫拋錯條件；最後加入：

Throw an error when subtotal is negative.
Throw an error when quantity is not a positive integer.

完成 Review 並 Accept 後，再把兩個 failure-path（失敗路徑）組成一個陣列貼進 REPL：

[
  (() => { try { quote({ subtotal: -1, quantity: 1, member: false }); return false } catch { return true } })(),
  (() => { try { quote({ subtotal: 100, quantity: 0, member: false }); return false } catch { return true } })()
]

每一輪先審 proposal，只有 Accept 後才在 REPL 重跑所有仍適用的舊測試；若測試失敗，就修改 intent，重新 Sync 並審查下一份 proposal。若新規格刻意改變舊行為，就同步更新該案例的期望值並記錄原因。你要保存的是「未被新規格改寫的舊行為仍成立＋預期變更已被驗收」的證據；這也是 Agent Harness 裡 rules、tools、state、evals、observability 不能只挑一項的原因。

Step 4：先審 diff，再驗證 committed source

痛點：source map 看起來很精準，容易讓人把「有連線」誤認為「有證明」。解法：Accept 前先問前三題，Accept 後再用 REPL 回答第四題：

1. 規格有沒有漏：每一條非空 intent 是否都能找到合理的 generated range？
2. 程式有沒有多：source 中是否出現 intent 沒要求的外部呼叫、狀態或預設值？
3. 假設能否接受：rounding、錯誤型別、輸入 coercion（自動型別轉換）是否明寫且符合用途？
4. Accept 後行為能否重跑：所有仍適用的舊測試，以及已按新規格更新期望值的案例，是否都得到預期結果？若沒有，就修改 intent 開下一輪。

固定版本的 normalizer主要檢查行號與範圍是否合法，未覆蓋的 intent line 會形成 warning；它不會驗證兩段文字具有相同語意，也不會證明某一行程式「因為」某一行 intent 才出現。因此，逐行高亮最適合當導航，不適合當通過門票。要理解更完整的可追溯性，接著看 Agent Observability。

一個不需改動 Huzzah 內部資料的負向檢查是：選一段附近但無關的程式行，暫時把它當成 mapping 給你的高亮，再問自己「只看這個假高亮，我會不會仍相信它？」如果答案是會，就代表審查流程過度依賴視覺連線。正確做法是回到輸入輸出、錯誤路徑與不變條件；mapping 只負責幫你快速找到要讀的區域。

Step 5：刻意撞四個邊界，才知道 Huzzah 適不適合

1. 歧義測試：刪掉 rounding 規則

操作：建立兩個相同的 fresh file，使用相同 intent 各 Sync 一次，先對比 assumptions、proposed source 與逐行對照；人工閱讀、未發現明顯問題後才分別 Accept，再跑同一組 REPL 案例。判定：若行為或 assumptions 不同，先檢查是否有提案違反明文規格；若都未違反，才表示規格仍留下決策空間。若只有格式或 mapping 不同，則只能說生成／對照不穩定，不能直接歸因於行為規格。把真正影響行為的差異改寫成明確規則，再重做。

2. 手改生成碼：先確認工作流是否允許

操作：先檢查固定 commit 的 generated source viewer；它在此版本是唯讀，可操作方向是 intent → 新 source 提案，而不是手改 source 後自動反推 intent。判定：若你的核心需求是雙向同步，這個版本不符合驗收條件，別用想像補上未出現在此版本的步驟。

3. 多檔案測試：分清「多個記錄」與「跨檔生成」

操作：目前 UI 可以 New／Open／Rename 多個獨立 file record，但一次 Sync 的 request 仍是一份 old/new intent、一道 diff 與一份 current source，response 也是一個完整 JavaScript module；可先用兩個記錄做互不相依的小函式。判定：需要跨檔 import、共享型別或 dependency graph 時，應把它判為未通過，而不是宣稱已支援專案級生成。

4. 安全測試：把生成碼當成不可信輸入

操作：先讀官方 README 的資料流：spec 與目前 source 會送到你選定的模型 provider；接受的 JavaScript 會在本機 Web Worker 執行。判定：這只是 experimental containment，不是能防住惡意程式碼的安全沙箱。所以不要貼私密原始碼或 secret，也不要因為程式在 Worker 裡就略過 source review。

Huzzah、一般 Chat 與工程文件怎麼分工？

最實用的分工是：Chat／plan mode 用來快速探索；Huzzah 用來維持一個小而清楚的 intent/source 配對；Git 記錄誰在何時改了什麼；ADR 保存為什麼做這個取捨；spec 定義系統邊界；tests 把不能退步的行為變成可執行條件。若團隊常因上下文散落而重複解釋，可再讀 Context Repo 教學 與 Context Engineering。

什麼情況值得用？一個 30 秒決策法

• 先試 Huzzah：greenfield（從零開始的專案）、小型、單一 JavaScript module、輸入輸出可明確驗收，而且你願意逐次 review。
• 先用一般 Chat／plan：需求還在發散，只想快速比較做法，暫時沒有值得長期保存的意圖。
• 直接用 spec＋Git＋tests：多人協作、既有大型 repo、跨檔依賴、CI、權限或合規是必要條件。
• 暫停：你不能把程式內容送給目前選定的 provider，或無法隔離與審查 AI 產生的 JavaScript。

一句話判斷：若「意圖和實作一起演進」本身就是你的痛點，Huzzah 值得做小型試驗；若痛點其實是團隊版控、跨檔架構或安全執行，先把既有工程層補齊。

常見問題 FAQ

1. Huzzah 是偽代碼 compiler 嗎？

不是。目前 pseudocode 是 free-form spec，轉換工作由語言模型完成，不是固定文法加上 deterministic compiler。

2. 一定要使用 .hz 副檔名嗎？

固定版本的 UI 不要求。作者文章用 fizz_buzz.hz 當概念例子，但目前 file-name validation 沒有把副檔名設為條件。

3. 它會只重生受影響的幾行嗎？

目前不是 patch 合約。request 帶入完整 current source，模型 response 要回傳完整的下一份 ES module；UI 再顯示兩版的 diff。

4. 可以手改 source，再同步回偽代碼嗎？

在本文固定版本的 Web UI 不行。source viewer 是唯讀，主流程是編輯 intent 後產生 source proposal。

5. Huzzah 可以取代 Git 嗎？

不能。瀏覽器內 revisions 適合回看 Huzzah 的接受紀錄；團隊協作、remote backup、branch、merge 與作者追蹤仍應交給 Git。

6. 逐行對照能證明程式符合意圖嗎？

不能。同一個模型同時提出 code 與 mapping，而 normalizer 驗的是結構範圍；語意與邊界條件仍靠人工審查和 tests。

7. Web Worker 能安全執行任何生成碼嗎？

不能這樣理解。官方只把它定位為 experimental containment，不是對抗惡意程式碼的 sandbox。

8. 誰最適合先試 Huzzah？

願意做小型、單 module、可驗收實驗的開發者。它目前最值得觀察的是 intent/source review UX，而不是把它當成熟的專案級 code-generation platform。

給新手的 5 個重點

1. 先記住公式：Huzzah ＝ 持久意圖＋AI 對齊＋人類驗收。
2. 第一個任務要小到能用幾個布林式判定對錯。
3. 先用 diff／assumptions 審提案；Accept 後才用 REPL 測 committed source，失敗就修改 intent 開下一輪。
4. 每次只改一個行為，重跑仍適用的舊測試，並更新被新規格刻意改寫的期望值。
5. 逐行對照是審查線索，不是正確性證明；Huzzah 也不取代 Git、ADR、spec 與 tests。