HVSL：人類可見狀態層——Agent 不得把終端機當成使用者介面的 AI 協作開發方法論

作者：Neo K. 機構：一言諾科技有限公司（EveMissLab） 版本：v1.0 日期：2026年6月 文件類型：Markdown 技術白皮書 / 方法論論文

摘要

本文提出「人類可見狀態層」（Human-Visible State Layer, HVSL）作為 Vibe Coding、意圖語言、AI Agent 與人機協作開發中的基礎方法論。其核心主張是：Agent 的責任不是只完成操作，而是讓人類理解操作後的世界狀態。若使用者必須額外打開終端機、瀏覽器控制台、DevTools、VS Code、git diff、build log 或原始碼，才能知道 Agent 到底做了什麼、是否成功、是否失敗、下一步該做什麼，那麼該 Agent 就產生了「不可見性債」。

在傳統開發中，終端機、控制台、日誌、堆疊追蹤、測試輸出與原始碼差異，是開發者理解系統狀態的重要工具。然而，在 AI 協作開發與 Vibe Coding 的語境下，人類使用者的角色正在改變：使用者不一定是專業工程師，即使是工程師，也不應被迫在每一次 Agent 操作後切換到低階工具鏈中確認狀態。尤其在意圖式開發模式下，人類的核心工作是表達目標、約束結構、判斷結果與決定下一步，而不是不斷追蹤 Agent 留在終端機與控制台中的狀態碎片。

本文主張，成熟的 Agent 系統必須建立 HVSL，把機器狀態、開發者狀態與使用者狀態分層處理，並將底層技術訊號轉譯為一般人可理解、可驗證、可操作的狀態摘要。終端機不是使用者介面；console 不是產品回饋；VS Code 不是一般人的觀測窗口。Agent 若不能將狀態可視化、摘要化、可驗證化與可回復化，就無法真正與人類協作。

本文將 HVSL 定位為 ICL（Intent Collaboration Layer, 意圖協作層）、SCL（Settings Contract Layer, 設定契約層）、UI-SCL（UI Settings Contract Layer, UI 設定契約層）與 MSSP（Mother-Set and Subset Paradigm, 母集與子集範式）的補充層。ICL 定義人類如何以意圖協作；SCL 定義系統允許被如何改變；UI-SCL 定義使用者能如何控制介面；MSSP 定義架構如何被看見；HVSL 則定義 Agent 操作後的人類可見狀態如何被呈現。

關鍵詞：AI Agent、Vibe Coding、意圖語言、人類可見狀態層、狀態翻譯、終端機、控制台、開發者體驗、使用者體驗、AI 協作開發、不可見性債

第一章：問題陳述——Agent 看得到的狀態，人類看不到

1.1 Agent 的觀測能力與人類的觀測落差

AI Agent 在軟體開發場景中，通常能接觸大量技術狀態。例如：

terminal output
console log
build log
test report
runtime stack trace
git diff
file system state
package manager output
network request
browser error
compiler warning
lint result

這些資訊對 Agent 或工程師有用，卻不代表一般使用者能理解。對一般人而言，真正可見的狀態通常只有：

畫面有沒有變
按鈕能不能按
功能有沒有成功
錯誤訊息能不能看懂
資料有沒有保存
下一步要不要做什麼

這兩種狀態之間存在巨大落差。Agent 若只停留在機器狀態或開發者狀態，就會把理解成本轉嫁給人類。使用者被迫打開終端機、瀏覽器控制台、VS Code、測試報告或原始碼來確認 Agent 的工作結果。這不只是使用不便，而是 AI 協作模式的根本缺陷。

1.2 懂技術的人也不應被迫一直下沉

值得注意的是，HVSL 不是只為非技術使用者設計。即使使用者懂終端機、控制台、VS Code、git diff 與測試輸出，也不表示他應該在每次 Agent 操作後都打開這些工具確認狀態。

懂技術與願意被迫耗費時間是兩件事。 會看低階狀態流，不代表應該一直看低階狀態流。

在 AI 協作開發中，Agent 的價值本應是降低操作成本與狀態追蹤成本。如果使用者在每次任務後仍要自己切換到終端機、console、檔案差異與測試輸出中追查，那麼 Agent 只是把「寫程式」的工作減少，卻把「確認狀態」的成本保留下來，甚至因為修改速度更快而放大了狀態追蹤負擔。

1.3 終端機不是使用者介面

本文提出一條基本命題：

終端機不是使用者介面。Console 不是產品回饋。VS Code 不是一般人的觀測窗口。

終端機與控制台是低階技術工具。它們可以存在，也必須存在，但不應成為使用者理解 Agent 行為的唯一窗口。成熟 Agent 必須把底層狀態轉譯成人類可見狀態，而不是把 log、error、diff 與 command output 原封不動丟給使用者。

這並不表示隱藏細節。正確方式是：預設提供人類可理解摘要，必要時允許展開技術細節。也就是：

一般人看到：功能已完成，設定已保存，仍有一項需要確認。
開發者可展開：查看 build log、git diff、test output、stack trace。

HVSL 的任務正是建立這種分層狀態呈現。

第二章：HVSL 的定義

2.1 基本定義

HVSL（Human-Visible State Layer，人類可見狀態層）是 AI Agent 與人類協作時，用來呈現任務進度、操作結果、錯誤原因、驗證狀態、未完成項目與下一步行動的狀態轉譯層。

它回答以下問題：

Agent 做了什麼？
目前做到哪裡？
是否成功？
是否失敗？
失敗原因是什麼？
哪些東西已驗證？
哪些東西未驗證？
使用者是否需要採取行動？
若要確認，該如何確認？
若要回復，該如何回復？

一句話定義：

HVSL 是把 Agent 的機器狀態與開發者狀態，轉譯成人類可理解、可驗證、可操作狀態的協作層。

2.2 HVSL 的核心命題

本文提出三個核心命題：

1. Agent 的責任不是只完成操作，而是讓人類理解操作後的世界狀態。
2. 沒有可見狀態，就沒有真正協作。
3. 若使用者必須打開終端機、控制台或原始碼才能知道 Agent 是否成功，Agent 就產生了不可見性債。

這三個命題共同指出：AI 協作不只是執行任務，而是共同維持一個可理解的世界狀態。

2.3 HVSL 與 UX 的差異

HVSL 與一般 UX 不完全相同。UX 關心使用者整體體驗，包括介面、流程、情感、效率與滿意度。HVSL 更專注於 Agent 操作後的狀態可見性。

例如，一個網站按鈕好不好按是 UX 問題；Agent 修改完按鈕邏輯後，有沒有告訴人類改了什麼、測了什麼、沒測什麼、如何確認，這是 HVSL 問題。

HVSL 是 AI 協作時代新增的 UX 子領域，也可視為 Agent 狀態觀測的產品化方法論。

第三章：Agent 不可見性債

3.1 定義

「Agent 不可見性債」（Agent Invisibility Debt）指的是：當 Agent 完成、修改、執行、測試或部署任務後，若人類必須額外打開低階工具才能理解目前系統狀態，則代表該 Agent 產生了不可見性債。

更正式地說：

Agent 不可見性債是由狀態未轉譯、結果未摘要、錯誤未說明、驗證未呈現與下一步未指明所造成的人類認知負擔。

3.2 不可見性債的來源

不可見性債通常來自以下情境：

1. Agent 只說 Done，沒有說明做了什麼。
2. Agent 修改多個檔案，但沒有摘要變更。
3. Agent 執行測試，但沒有翻譯測試結果。
4. Agent 遇到錯誤，只貼出原始 log。
5. Agent 未驗證功能，卻讓使用者以為已完成。
6. Agent 需要使用者確認，但沒有清楚指示。
7. Agent 假設使用者會自己開 console。
8. Agent 假設使用者會自己看 VS Code diff。
9. Agent 把開發者狀態當成一般人狀態。
10. Agent 不提供回復路徑。

3.3 不可見性債的後果

不可見性債會造成多重風險：

使用者不知道 Agent 到底改了什麼。
使用者不知道功能是否真的完成。
使用者不知道錯誤是否被處理。
使用者不知道哪些地方需要自己確認。
使用者被迫進入開發者工具鏈。
一般人直接放棄。
懂的人也被浪費時間。
AI 後續接手時缺乏狀態摘要。
錯誤可能被掩蓋。
信任被削弱。

這些後果會讓 Agent 看似強大，實際難以長期協作。

3.4 不可見性債與技術債的差異

技術債是系統內部結構與實作品質的債；不可見性債是人類理解系統狀態的債。

一段程式碼可以技術上可運行，但狀態上不可理解。 一個 Agent 可以真的完成任務，但使用者不知道它完成了什麼。 這時問題不在功能本身，而在協作界面。

因此，不可見性債應被視為 AI 協作開發中的一等風險。

第四章：三層狀態模型

4.1 機器狀態

機器狀態是系統、工具、編譯器、測試框架與執行環境產生的原始訊號。

範例：

exit code 0
exit code 1
TypeError stack trace
npm run build output
pytest result
HTTP 500
network timeout
git diff
console.warn
lint warning

機器狀態是最精確但最不友善的狀態。它適合工具與工程師，不適合一般使用者。

4.2 開發者狀態

開發者狀態是把機器狀態轉譯成工程語境後的結果。

範例：

build 通過
新增了 settings-provider.js
Header component 已改為從 uiSettings 讀取 theme
RecommendationPanel 尚未接入 UI Region Registry
有一個測試失敗，原因是 mock API 缺少 userPreference 欄位

開發者狀態仍需要技術背景，但已比原始 log 更容易理解。

4.3 使用者狀態

使用者狀態是面向一般人的結果描述。

範例：

功能已啟用。
設定已保存。
這個區塊已隱藏。
目前不需要你做任何事。
操作失敗，原因是網路連線中斷。
請重新整理頁面後再試一次。
請按右上角設定按鈕確認專注模式。

使用者狀態不應要求使用者理解程式碼、build tool、stack trace 或檔案結構。

4.4 狀態轉譯鏈

成熟 Agent 應具備以下轉譯鏈：

機器狀態 → 開發者狀態 → 使用者狀態

例如：

機器狀態：
npm run build exited with code 0

開發者狀態：
前端建置成功，沒有 TypeScript 編譯錯誤。

使用者狀態：
功能已成功更新，可以重新整理頁面查看結果。

再例如：

機器狀態：
TypeError: Cannot read properties of undefined (reading 'theme')

開發者狀態：
SettingsProvider 沒有取得預設 theme 設定，導致 Header render 失敗。

使用者狀態：
頁面主題設定載入失敗，系統已改用預設主題。功能可繼續使用，但建議稍後再保存偏好。

這種翻譯能力是 HVSL 的核心。

第五章：Vibe Coding 中的狀態翻譯責任

5.1 Vibe Coding 不是讓使用者追 log

Vibe Coding 的理想是人類透過自然語言或意圖語言描述目標，由 AI 協助生成、修改與驗證系統。這種模式要成立，前提是人類能快速理解 Agent 的操作狀態。

若每次 AI 修改後，使用者都要自己打開終端機、控制台、VS Code、git diff 與測試報告，Vibe Coding 就會變成一種新的低效率流程。表面上，人類不用逐行寫程式；實際上，人類要逐段檢查 AI 留下的狀態碎片。

成熟的 Vibe Coding 應該是：

人類表達意圖
AI 執行與修改
AI 轉譯狀態
人類快速判斷
人類決定下一步

而不是：

人類表達意圖
AI 修改一堆檔案
人類自己開終端機
人類自己看 console
人類自己看 VS Code diff
人類自己猜哪裡成功哪裡失敗

5.2 意圖語言需要回饋語言

如果未來軟體開發走向意圖語言，那麼不只需要人類能說出意圖，也需要系統能回報狀態。意圖語言不能只有命令，還必須有回饋。

例如：

人類意圖：
把文章頁改成專注閱讀模式，隱藏推薦與社群按鈕。

Agent 回饋：
已完成文章頁專注模式。推薦欄與社群按鈕在 focusMode=true 時會自動隱藏。已保留文章內容、返回按鈕與保存狀態。尚未測試手機版布局。

這種回饋讓人類不需要看程式碼，也能理解世界狀態。

5.3 Agent 應主動揭露未驗證項

Agent 最危險的行為之一，是把未驗證的工作包裝成已完成。HVSL 要求 Agent 主動揭露：

已驗證項
未驗證項
推測項
需要人類確認項
可能風險

例如：

已驗證：
- build 通過
- settings schema 格式有效
- focusMode 可隱藏 recommendations

未驗證：
- 尚未測試 Safari
- 尚未測試手機版
- 尚未測試登入後同步

需要你確認：
- 是否希望 focusMode 也隱藏留言區？

這種誠實回報比單純「完成了」更有價值。

第六章：Agent 操作後的最小回報格式

6.1 最小回報格式

每次 Agent 完成一個任務後，至少應提供以下狀態摘要：

1. 任務結果：成功、部分成功、失敗、需要確認
2. 變更摘要：改了哪些東西
3. 變更原因：為什麼這樣改
4. 影響範圍：哪些檔案、模組、功能受影響
5. 驗證狀態：測了什麼，結果如何
6. 未驗證項：哪些地方尚未確認
7. 使用者行動：使用者是否需要做什麼
8. 回復方式：若不滿意如何撤回或修改

6.2 標準輸出模板

## 狀態摘要

**結果**：已完成 / 部分完成 / 失敗 / 需要確認

**我改了什麼**
- ...

**為什麼這樣改**
- ...

**已驗證**
- ...

**未驗證**
- ...

**你可以如何確認**
- ...

**需要你決定**
- ...

**可回復方式**
- ...

6.3 範例

## 狀態摘要

**結果**：已完成

**我改了什麼**
- 新增 `ui-settings.schema.json`
- 新增 `settings-provider.js`
- 將 Header 的 theme 改為從 SettingsProvider 讀取
- 將 RecommendationPanel 註冊為可隱藏區塊

**為什麼這樣改**
- 避免 theme 與 focusMode 被硬編在各個 component 中
- 讓未來 AI 新增 UI 時能讀取同一套設定契約

**已驗證**
- build 通過
- 預設設定可成功載入
- focusMode=true 時推薦欄會隱藏

**未驗證**
- 尚未測試 Safari
- 尚未測試登入後同步

**你可以如何確認**
- 重新整理頁面
- 開啟右上角設定
- 切換「專注模式」
- 確認推薦欄是否隱藏

**可回復方式**
- 關閉專注模式即可恢復推薦欄
- 若要撤回程式變更，可回復本次修改的 settings 與 RecommendationPanel 檔案

這種格式將 Agent 的行為轉譯為人類可理解狀態。

第七章：HVSL 與 UI-SCL 的結合

7.1 UI-SCL 定義可控性，HVSL 定義可見性

UI-SCL 回答：

使用者能控制什麼？
哪些 UI 區塊可隱藏？
哪些偏好可保存？
哪些資訊不可關閉？

HVSL 回答：

使用者如何知道控制是否成功？
Agent 如何回報設定是否保存？
錯誤如何可見？
未完成狀態如何呈現？

兩者結合後，前端 Agent 才能真正服務人類。

7.2 設定變更後的可見狀態

例如，使用者要求：

把網站改成可以隱藏推薦內容，並記住我的選擇。

只有 UI-SCL，系統可能完成設定架構。 只有 HVSL，系統可能回報狀態。 兩者結合，Agent 應做到：

1. 新增 hideRecommendations 設定。
2. 將推薦區塊註冊為 hideable。
3. 使用 localStorage 保存匿名偏好。
4. 在 UI 上顯示「推薦內容已隱藏」。
5. 在任務回報中說明已驗證與未驗證項。

這才是完整的人機協作。

7.3 不可見設定是壞設定

若使用者更改設定後，不知道設定是否生效，這就是不可見設定。

例如：

使用者切換 focusMode，但畫面沒有明確回饋。
使用者關閉通知，但不知道是否保存。
使用者隱藏推薦，但重新整理後又出現，且沒有說明。

UI-SCL 要定義設定；HVSL 要讓設定狀態可見。

第八章：HVSL 與 SCL、ICL、MSSP 的關係

8.1 與 SCL 的關係

SCL 定義系統允許被如何改變。HVSL 定義系統改變後如何讓人類知道。

SCL：可變性契約
HVSL：變更後狀態契約

若沒有 SCL，Agent 不知道哪些地方可以改。 若沒有 HVSL，人類不知道 Agent 改完後發生了什麼。

8.2 與 ICL 的關係

ICL 定義人類如何以意圖與 AI 協作。HVSL 是 ICL 的回饋面。

ICL：人類如何下達意圖
HVSL：Agent 如何回報意圖執行結果

沒有 HVSL 的 ICL 會變成單向命令；有 HVSL 的 ICL 才是雙向協作。

8.3 與 MSSP 的關係

MSSP 主張架構應可視化、可索引、可理解。HVSL 可視為 MSSP 在 Agent 操作狀態上的延伸：

MSSP：讓架構可被看見。
HVSL：讓操作後的狀態可被看見。

兩者都反對黑箱化。

8.4 與三層認知架構的關係

三層認知架構區分宏觀、 中觀、微觀。HVSL 也需要對應三層：

宏觀狀態：任務目標是否達成？
中觀狀態：架構與模組如何改變？
微觀狀態：具體檔案、測試、錯誤如何變動？

Agent 回報不應只停在微觀層，而要把微觀狀態上升為中觀與宏觀摘要。

第九章：Agent 狀態面板的設計

9.1 任務狀態面板

成熟 Agent 應提供任務狀態面板，顯示：

任務名稱
目前階段
進度狀態
最近操作
成功項
失敗項
等待人類確認項
可回復操作

範例：

任務：新增 UI-SCL 設定層
狀態：部分完成
目前階段：等待使用者確認 focusMode 是否隱藏留言區
已完成：schema、provider、region registry
未完成：手機版測試
需要確認：留言區是否納入 focusMode

9.2 變更摘要

變更摘要應面向人類，而不是只顯示 git diff。git diff 可以作為展開細節，但預設摘要應是：

新增了設定層。
移除了硬編碼主題。
新增了專注模式。
推薦區塊現在可以被隱藏。

9.3 測試摘要

測試摘要不應只貼原始輸出，而應說明：

測試是否執行
哪些測試通過
哪些測試失敗
失敗是否影響主要功能
是否需要人類手動驗證

範例：

已執行 npm run build，結果通過。
尚未執行跨瀏覽器測試。
建議手動確認手機版側邊欄。

9.4 錯誤摘要

錯誤摘要應包含：

發生什麼
可能原因
影響範圍
目前是否已修復
使用者是否需要行動
技術細節可展開

範例：

設定保存失敗。原因可能是瀏覽器阻擋 localStorage 或使用者處於隱私模式。頁面仍可使用，但偏好可能無法在重新整理後保留。

第十章：一般使用者、進階使用者與開發者模式

10.1 三種可見性模式

HVSL 不應用同一種方式對所有人呈現狀態。可分成三種模式：

一般模式：只顯示結果、影響與下一步。
進階模式：顯示檔案、模組、測試摘要。
開發者模式：顯示 log、diff、stack trace、command output。

10.2 一般模式

一般模式避免技術細節，強調：

成功或失敗
人類可理解原因
是否需要行動
如何確認

例如：

已完成。你現在可以在設定中開啟專注模式。開啟後，推薦內容會自動隱藏。

10.3 進階模式

進階模式適合懂一點技術或產品的人：

新增了 focusMode 設定。
RecommendationPanel 已接入 UI Region Registry。
localStorage 會保存匿名偏好。

10.4 開發者模式

開發者模式提供細節：

modified:
- src/settings/settings-provider.js
- src/components/RecommendationPanel.jsx
- src/styles/focus-mode.css

tests:
- npm run build: passed
- npm run test: 1 skipped

這種分層能同時服務一般人與專業使用者。

第十一章：HVSL 的前端實作模式

11.1 Status Store

Agent 應將任務狀態寫入統一的 Status Store，而不是散落在 log 中。

範例：

{
  "taskId": "task-ui-scl-001",
  "title": "新增 UI-SCL 設定層",
  "status": "partial_success",
  "summary": "已新增設定層與專注模式，但尚未測試手機版。",
  "changes": [
    "新增 ui-settings.schema.json",
    "新增 settings-provider.js",
    "RecommendationPanel 已可被 focusMode 隱藏"
  ],
  "verified": [
    "build passed",
    "focusMode hides recommendations"
  ],
  "unverified": [
    "mobile layout",
    "Safari behavior"
  ],
  "requiresUserAction": true,
  "nextAction": "確認 focusMode 是否也要隱藏留言區"
}

11.2 Status Renderer

Status Renderer 負責把 Status Store 轉成不同模式：

一般模式：自然語言摘要
進階模式：模組與測試摘要
開發者模式：詳細 log 與 diff

11.3 Status Timeline

對長任務而言，狀態應有時間線：

10:02 開始分析專案
10:04 找到設定硬編碼
10:07 新增 settings-provider
10:10 修改 Header
10:12 build 通過
10:13 等待你確認 focusMode 範圍

這讓使用者知道 Agent 不是黑箱亂動。

11.4 一鍵驗證與一鍵回復

HVSL 應提供：

一鍵重新執行測試
一鍵打開變更摘要
一鍵回復上一步
一鍵確認人工驗證項

如果只有「完成」而沒有回復路徑，使用者很難信任 Agent。

第十二章：狀態可見性的倫理與信任

12.1 透明不是丟 log

透明不等於把所有 log 丟給使用者。真正的透明是讓使用者理解重要狀態，並在需要時能追溯細節。

丟 log 是卸責。 翻譯狀態才是協作。

12.2 Agent 不應假裝確定

Agent 應明確區分：

我已確認
我推測
我尚未確認
我需要你決定
我無法驗證

這種區分能防止假完成與過度信任。

12.3 使用者時間也是資源

Agent 系統常強調節省開發時間，卻忽略使用者檢查狀態的時間。若 Agent 讓人類反覆打開終端機、控制台、VS Code、瀏覽器、檔案差異與測試報告，其實只是把時間成本轉移，而非真正消除。

HVSL 將使用者時間視為需要保護的資源。

第十三章：HVSL 反模式

13.1 Done 反模式

Agent 只說「完成了」，沒有說明做了什麼、驗證了什麼、未驗證什麼。

13.2 Log Dump 反模式

Agent 貼出大量原始 log，卻不解釋對使用者意味著什麼。

13.3 Silent Failure 反模式

Agent 操作失敗，卻沒有明確告知，或用模糊語句掩蓋。

13.4 Developer-Only Feedback 反模式

Agent 只提供開發者能看懂的回饋，對一般使用者不友善。

13.5 Hidden Assumption 反模式

Agent 假設使用者知道如何驗證，但沒有說明驗證步驟。

13.6 No Rollback 反模式

Agent 修改系統後沒有提供回復路徑。

13.7 False Completion 反模式

Agent 未測試卻聲稱完成。這是最危險的反模式之一。

第十四章：HVSL Prompt 協議

14.1 給 Agent 的狀態回報協議

每次你完成任務後，必須提供 HVSL 狀態摘要：

1. 任務結果：成功、部分成功、失敗、需要確認。
2. 變更摘要：用人類可理解語言說明改了什麼。
3. 影響範圍：列出受影響功能或檔案。
4. 已驗證項：說明執行過哪些檢查。
5. 未驗證項：誠實列出尚未確認部分。
6. 使用者可如何確認：提供不依賴終端機的確認方式，若可能。
7. 技術細節：可折疊或附在後面，不作為唯一回饋。
8. 回復方式：說明如何撤回或修改。
不得只回答 Done。
不得把原始 log 當成完整解釋。
不得假設使用者會打開終端機、控制台或 VS Code。

14.2 簡短版

請遵守 HVSL：
完成任務後，請用人類可理解方式回報：
做了什麼、是否成功、測了什麼、沒測什麼、我該如何確認、下一步要不要我決定。
不要只貼 log，不要只說 Done，不要假設我會開終端機或 VS Code。

14.3 給 Vibe Coding 的整合提示

你是 AI 協作開發 Agent。
請同時遵守 ICL、SCL、UI-SCL 與 HVSL：

ICL：先理解我的意圖。
SCL：不要破壞設定契約。
UI-SCL：前端偏好必須集中管理。
HVSL：每次修改後都要回報人類可見狀態。

尤其注意：
我不想每次都開終端機、控制台或 VS Code 檢查。
請把必要狀態翻譯成人類可理解摘要。

第十五章：範例情境

15.1 情境一：一般人使用 Agent 修改網站

使用者說：

幫我把網站改成可以隱藏推薦內容。

不良 Agent 回覆：

Done.

或：

Modified RecommendationPanel.jsx and updated localStorage logic.

符合 HVSL 的回覆：

已完成。你現在可以在設定中關閉「推薦內容」。關閉後，首頁與文章頁的推薦欄都會隱藏，重新整理後仍會保留。

我已確認：
- 設定開關可以切換
- 推薦欄會隱藏
- 偏好會保存在本機

尚未確認：
- 不同瀏覽器是否都一致
- 登入後是否跨裝置同步

你可以這樣確認：
打開頁面右上角設定 → 關閉推薦內容 → 回到首頁查看推薦欄是否消失。

15.2 情境二：工程師使用 Agent 重構設定層

工程師說：

把所有 theme 硬編碼改成 SettingsProvider。

符合 HVSL 的回覆：

已完成主要重構。

變更摘要：
- Header、Sidebar、Layout 已改為從 SettingsProvider 讀取 theme.mode。
- 移除三處硬編碼 dark theme。
- 新增 default theme fallback。

已驗證：
- npm run build 通過。
- 切換 theme.mode 可更新 body data-theme。

未驗證：
- 尚未檢查所有第三方 component。
- 尚未測試舊設定遷移。

受影響檔案：
- src/settings/settings-provider.ts
- src/components/Header.tsx
- src/components/Sidebar.tsx
- src/layout/AppLayout.tsx

15.3 情境三：Agent 測試失敗

不良回覆：

Tests failed.

符合 HVSL：

測試未完全通過。

發生什麼：
- 共有 24 個測試，23 個通過，1 個失敗。

失敗原因：
- UserSettingsPanel 測試仍期待舊的 theme prop，但目前已改為從 SettingsProvider 讀取。

影響：
- 主要功能可能正常，但測試需要更新。
- 這不是 build 錯誤，而是測試案例尚未同步新架構。

下一步：
- 我可以幫你更新測試。
- 或者先保留程式碼，稍後再修測試。

這才是可協作狀態。

第十六章：HVSL 與未來 Agent OS

16.1 Agent OS 需要狀態層

未來若 AI Agent 進一步成為本地或雲端的 Agent OS，能操作檔案、應用、瀏覽器、專案、API 與多模型工具，那麼 HVSL 更加必要。

Agent OS 若只能執行，不能清楚回報，就會成為不可控黑箱。使用者不可能每次都去看底層 log。Agent OS 必須有完整狀態層：

任務狀態
檔案狀態
權限狀態
風險狀態
同步狀態
錯誤狀態
回復狀態

16.2 狀態是信任的基礎

使用者信任 Agent，不是因為 Agent 聲稱自己很強，而是因為 Agent 能清楚說明：

我做了什麼
我沒做什麼
我為什麼這樣做
我確認了什麼
我不確定什麼
你可以如何控制
你可以如何回復

沒有這些，Agent 越強，風險越高。

16.3 未來的協作介面

未來成熟的 Agent 介面應該同時具備：

意圖輸入區
任務計畫區
執行狀態區
人類可見摘要區
技術細節展開區
驗證 checklist
回復控制
權限控制
設定契約
狀態時間線

這種介面不是傳統 IDE，也不是簡單聊天框，而是 AI 協作工作台。

第十七章：結論

本文提出 HVSL（人類可見狀態層）作為 AI Agent、Vibe Coding 與意圖語言時代的基礎方法論。其核心主張是：Agent 的責任不是只完成操作，而是讓人類理解操作後的世界狀態。

在現有 AI 協作開發中，Agent 往往能看到大量底層狀態，卻沒有把這些狀態翻譯給人類。終端機、控制台、VS Code、build log、git diff 與 stack trace 都是有用工具，但它們不是一般人的使用者介面。即使使用者懂這些工具，也不應被迫每次下沉到低階狀態流中確認 Agent 的工作。

HVSL 要求 Agent 將機器狀態轉譯為開發者狀態，再轉譯為使用者狀態。每次操作後，Agent 應提供任務結果、變更摘要、影響範圍、驗證狀態、未驗證項、使用者可確認方式與回復路徑。若缺乏這些，Agent 就產生不可見性債。

本文最後主張：

沒有可見狀態，就沒有真正協作。

AI 可以操作系統，可以修改程式碼，可以執行測試，可以生成 UI。 但人類必須能看懂世界變成了什麼樣。 否則所謂協作，只是 Agent 在黑箱中行動，人類在事後追查。

HVSL 的目的，就是讓 AI 協作從「Agent 自己知道」走向「人類也能理解」。

附錄 A：HVSL 檢查清單

[ ] Agent 是否說明任務結果？
[ ] Agent 是否摘要做了什麼？
[ ] Agent 是否說明為什麼這樣做？
[ ] Agent 是否列出影響範圍？
[ ] Agent 是否列出已驗證項？
[ ] Agent 是否列出未驗證項？
[ ] Agent 是否說明使用者如何確認？
[ ] Agent 是否避免只貼 log？
[ ] Agent 是否避免只說 Done？
[ ] Agent 是否避免假設使用者會開終端機？
[ ] Agent 是否提供回復方式？
[ ] Agent 是否區分一般模式、進階模式、開發者模式？
[ ] Agent 是否誠實標示不確定？
[ ] Agent 是否把錯誤翻譯成人類可理解訊息？

附錄 B：HVSL 最小輸出模板

## 狀態摘要

**結果**：

**我改了什麼**：
- 

**已驗證**：
- 

**未驗證**：
- 

**你可以如何確認**：
- 

**需要你決定**：
- 

**可回復方式**：
- 

附錄 C：核心命題

終端機不是使用者介面。
Console 不是產品回饋。
VS Code 不是一般人的觀測窗口。
Agent 的責任不是只完成操作，而是讓人類理解操作後的世界狀態。
沒有可見狀態，就沒有真正協作。
若使用者必須打開低階工具才能知道 Agent 是否成功，Agent 就產生了不可見性債。
Vibe Coding 需要意圖語言，也需要回饋語言。
懂技術的人，也不應被迫一直下沉到低階狀態流。

附錄 D：與既有方法論的關係

ICL：
  人類如何用意圖與 AI 協作。
  HVSL 是 ICL 的回饋面。

SCL：
  系統允許被如何改變。
  HVSL 說明改變後如何被人類看見。

UI-SCL：
  使用者能如何控制介面。
  HVSL 說明控制是否成功、是否保存、是否需要確認。

MSSP：
  架構如何被看見。
  HVSL 則使操作後狀態被看見。

三層認知架構：
  宏觀：任務是否達成。
  中觀：架構如何變動。
  微觀：檔案、測試、錯誤如何改變。

附錄 E：給 Agent 的短指令

請遵守 HVSL。
每次任務完成後，請用人類可理解方式回報：
你做了什麼、是否成功、測了什麼、沒測什麼、我該如何確認、下一步是否需要我決定。
不要只說 Done。
不要只貼 log。
不要假設我會開終端機、控制台或 VS Code。
技術細節可以提供，但請放在摘要之後。