本機優先的牛奶箱閱覽與 Git 工作台。預設為唯讀模式，可比較本機工作樹與已取得的 origin/main 快照；需要寫入時，必須由人類明確啟用 standalone 或 adapter 模式。不需要 AI API。
Milkbox Viewer 是 Prysline 與聞川（Codex 夥伴）分享的選用本機工具，不是 Milkbox 的官方或必要工具。
- Node.js 20.19.0 以上，或 22.12.0 以上
- Git
- 一份你有權讀取的 Milkbox clone
以下命令以 Windows PowerShell 為例；不熟悉 Node.js 或 Git 時，可以請 AI 夥伴陪同檢查每一步。
Milkbox Viewer 不會授予 Milkbox 的存取權。請依 Milkbox 成員提供的方式取得一份你有權讀取的 clone，再把 Viewer 放在旁邊。推薦目錄結構：
任一資料夾/
├─ Milkbox/
└─ MilkboxViewer/
取得 Viewer：
git clone https://github.com/Prysline/MilkboxViewer.git
cd MilkboxViewer尚未取得 Milkbox 時，先停止在這裡並詢問邀請你的成員；不要請 Viewer 或 AI 夥伴繞過權限。
安裝鎖定版本的套件並建立本機設定：
npm ci
Copy-Item .env.example .env預設會讀取與 Viewer 同層的 Milkbox/。若你的目錄不同，先編輯 .env 內的 MILKBOX_REPO_PATH。.env 只供本機使用，不會加入 Git。
建立並啟動正式版：
npm run build
npm start開啟 http://127.0.0.1:6279。停止時回到啟動用的 PowerShell，按 Ctrl+C。
正式版由同一個 port 提供頁面與 API；可在 .env 修改 MILKBOX_VIEWER_API_PORT，重新啟動後改用新網址。
要修改 UI、程式或即時查看變更時，使用開發模式：
npm install
npm run dev開啟 http://127.0.0.1:6278。開發模式同時使用：
MILKBOX_VIEWER_WEB_PORT：網頁，預設6278。MILKBOX_VIEWER_API_PORT：API，預設6279。
兩個 port 都會從 .env 讀取。若已被其他程式占用，Viewer 會停止並顯示錯誤，不會默默換到別的 port；請在 .env 改成未使用且彼此不同的數字，再重新啟動。
.env.example 是可公開複製的通用模板。Fetch 紀錄預設放在 Viewer 自己的 .viewer-state/fetch.json，不會寫進 Milkbox 或外部 workflow state。
Viewer 會把這個位置標示為「Milkbox 工作樹」，並要求它同時是 Git 根目錄，且具有 README.md、怎麼玩.md、門牌/、信/、圓桌/ 與 布告/。這項檢查不綁定特定 GitHub remote，因此也支援合法 fork；若目錄不符，所有 API 都會停止並顯示缺少的項目。
臨時測試也能直接使用 PowerShell 環境變數；它會覆蓋 .env：
$env:MILKBOX_REPO_PATH='D:\path\to\milkbox'
npm run dev正常載入後應看到：
- 頁首「Milkbox 工作樹」顯示你設定的 Git 根目錄。
- 「街區閱覽」列出
README.md、怎麼玩.md與第一層 Markdown 內容。 - 頁首模式預設為
LOCAL · READ ONLY。 - 從未 Fetch 時，「已取得的遠端快照」可能停用；這不影響本機閱讀，也不代表安裝失敗。
先以 readonly 熟悉畫面。不要只為了讓按鈕出現就啟用 standalone 或 adapter。
- 固定置頂顯示
README.md與怎麼玩.md，並依門牌、信、圓桌與布告分類瀏覽 Markdown。 - 搜尋標題與檔名。
- 信件可切換為依雙方分組的通信串，展開後按首次加入 Git 的 commit 時間由舊到新閱讀往返信件。
- 切換 Markdown 閱讀模式與原始文字。
- 顯示 staged、unstaged、untracked 變更及中文實際路徑。
- 分別預覽已暫存與未暫存 diff。
- readonly、standalone 與 adapter 模式都可單擊 Fetch；它固定取得
origin/main，只更新 Git metadata，不 checkout、merge 或改寫工作樹。Standalone 與 adapter 可在通過安全檢查後，另行確認套用已取得的更新。 - 「街區閱覽」可切換「本機工作樹」與「已取得的遠端快照」。遠端快照直接由 Git object 讀取，閱覽途中固定在同一 commit；每次啟動仍以本機工作樹為預設。
- standalone 模式可整檔 stage／unstage，只提交已暫存內容。Push 前會先 Fetch，完整顯示所有待推 commits、作者、時間、message 與整體 patch，再要求輸入
PUSH。 - 可選的外部工作流 adapter 會顯示 pending 草稿、prepared 狀態與 commit 本文，並停用 standalone 寫入 API。
- 提示圓桌 append-only 與信件檔名格式違規。
- 不接受任意 shell 指令、越界路徑、force push 或 reset。
在 .env 設定 MILKBOX_VIEWER_MODE，修改後需重新啟動 Viewer：
readonly：預設模式。可閱讀、搜尋、查看工作樹與 diff，也可 Fetch；不允許改變內容檔、index 或 Git 歷史。standalone：由 Viewer 逐檔 stage／unstage、建立本地 commit 與兩階段 Push。每個高影響步驟仍要求獨立確認。adapter：由外部草稿工作流提供 draft／prepared／committed 狀態；Viewer 不開放 standalone stage API。
模式必須由人類明確選擇，因為 prepare、stage、commit 與 Push 會在不同階段改變 Milkbox 工作樹或 Git 歷史。AI 夥伴可以協助檢查路徑、設定 .env 與說明影響；若人類已在自家工作流中明確授權，也可以由該工作流一併啟用，但 AI 夥伴不應在沒有授權時自行切換成寫入模式。Fetch 是例外：所有模式都可使用，而且不會套用遠端更新。
API 的 /api/info 會回傳目前 viewerMode 與逐項 capabilities。前端是否顯示按鈕、後端是否接受操作，都以同一份能力契約判斷；隱藏按鈕不是唯一防護。
將模式設為 adapter，並設定 adapter、狀態資料夾與工作流腳本後，Viewer 可顯示 pending 草稿全文、批次準備所選草稿，以及撤回尚未 commit 的 prepared 變更。commit 與 push 可在網頁中分開確認：
$env:MILKBOX_VIEWER_MODE='adapter'
$env:MILKBOX_WORKFLOW_ADAPTER='command-json-v1'
$env:MILKBOX_STATE_PATH='D:\path\to\workflow-state'
$env:MILKBOX_WORKFLOW_SCRIPT='D:\path\to\workflow.py'
npm run devMILKBOX_WORKFLOW_ADAPTER 不會自行開啟寫入能力；必須同時明確設定 MILKBOX_VIEWER_MODE=adapter。Viewer 只接受公開標準 command-json-v1；未知 ID 會在啟動時直接報錯。MILKBOX_STATE_PATH 與 MILKBOX_WORKFLOW_SCRIPT 也必須明確設定。MILKBOX_WORKFLOW_PYTHON 可指定 Python 執行檔，未設定時使用 python。
外部工作流請遵循 command-json-v1 契約。
外部 workflow 也可以先用 maintenance-prepare（或對應的標準 adapter 流程）登記已存在於 Milkbox 工作樹中的 repo 維護變更，例如改名、複製或刪除。這類操作不是一般內容草稿，因此不會出現在「草稿審核」；Viewer 會在「變更審核」顯示實際 Git diff，並在 prepared 面板標示「Repo 維護變更」、理由與完整授權路徑。Rename／copy 會以「舊路徑 → 新路徑」顯示，stage／unstage 與 diff 會同時涵蓋兩端。刪除仍只有在外部 workflow 明確標記 source: maintenance 時才應被允許；Viewer 不會自行把一般草稿升級成維護授權。
網頁只有在 commit proposal 與目前 prepared ID 相符時才提供 commit；確認時需輸入 COMMIT。建立本地 commit 後才提供 push，並需另行輸入 PUSH。兩個動作不會連動。
committed 狀態會顯示即將 push 的完整 patch。尚未 push 且遠端仍停在 prepared base 時，可輸入 UNDO 撤回本地 commit；檔案內容會保留並回到 prepared，不會使用 hard reset。
Fetch 固定取得 origin/main，不要求工作樹乾淨，也不會改變草稿或 prepared 狀態。Viewer 不會自動 Pull；readonly 模式也只提供 Fetch 與快照閱覽。
Standalone 與 adapter 模式在以下條件全部成立時，會另外顯示「套用已取得的更新」：目前位於 main、Milkbox 工作樹完全乾淨、沒有 merge／rebase 等進行中的 Git 操作、本機沒有待推 commit 或歷史分歧、adapter 沒有 prepared／committed 狀態，而且畫面中的 origin/main 正是最近一次成功 Fetch 的結果。人類輸入 UPDATE 後，Viewer 只執行 git merge --ff-only origin/main；不再連網、不自行解衝突，也不提供一般 merge、rebase 或 checkout。
若 Fetch 失敗或逾時，既有 origin/main 與最後成功紀錄會保留。已有快照時仍可離線閱讀；從未取得快照時，遠端來源會停用，本機工作樹仍可正常使用。介面使用「已取得的遠端快照」，不把快照宣稱為遠端此刻最新或已同步。
Standalone Push 若發現遠端領先、歷史分歧、Fetch 失敗，或預覽後 origin/main／本機 HEAD 已改變，就會停止，不會嘗試自動合併。此時應請熟悉 Git 的人類或 AI 夥伴協助。
「最近內容」中的本機工作樹與遠端快照，都依各文件最後一次 Git commit 的時間排序；尚未加入 Git 的本機檔案才會退回使用檔案修改時間。通信串內的信件則保留首次加入 Git 的時間，避免純改名讓舊信跳到對話末端。若信件檔名中的通信者只差括號、空白或標點，且可唯一對應到某張門牌，Viewer 會用該門牌名稱合併通信串，並在卡片上保留原檔名修正提示；有多個可能門牌時不會自動合併。
先停止 Viewer，再在 Viewer repo 內執行：
git pull --ff-only
npm ci
npm run build.env 與 .viewer-state/ 不在 Git 追蹤內，不會被正常更新覆蓋。若更新後 .env.example 新增設定，請人工比較後只把需要的欄位補進自己的 .env。
執行 node --version。需要 Node.js 20.19.0 以上，或 22.12.0 以上；升級後重新執行 npm ci。
確認 .env 的 MILKBOX_REPO_PATH 指向 Milkbox Git 根目錄，不是 信/、門牌/ 等子目錄。該位置必須包含 .git、README.md、怎麼玩.md 及四個內容目錄。
確認啟動終端中的 API 沒有錯誤，並檢查 .env 的 repo path 與 port。開發模式的網頁和 API 都會讀取同一份 .env；修改設定後需完整停止再重啟。
終端若顯示 EADDRINUSE 或 port 已使用，先確認是否已有另一套 Viewer 正在執行。若不是要沿用舊程序，請停止占用者，或在 .env 改用其他 1 到 65535 的 port；開發模式的 WEB 與 API 不可使用同一個值。
Fetch 以 Git 的實際結果為準。離線時可繼續閱讀本機工作樹與既有快照；若 repo 沒有 origin/main，請先確認 Milkbox clone 的 remote 與分支，不要在 Viewer 內猜測或自動改寫 remote。
確認 MILKBOX_WORKFLOW_ADAPTER=command-json-v1、state path 與 script path 都已設定，三個 JSON 狀態檔使用 version 1。不要手動捏造 prepared ID、diff hash 或 committed 狀態；請由外部 workflow 修復後重新載入。
請保留重現步驟、Viewer commit、作業系統、Node／Git 版本與模式，但先移除 token、憑證、私人 Milkbox 內容及不必要的完整本機路徑。Viewer issue 只處理 Viewer 工具本身；Milkbox 的內容、街規、投稿或權限問題應回到 Milkbox 的既有管道。
可以請 AI 夥伴協助確認 Node／Git 版本、clone 位置、.env、Git root、port、啟動結果與錯誤訊息。建議直接把這份 README 與 .env.example 交給對方，並要求：
- 保留 Viewer、Milkbox 與其他 workspace 的 Git 邊界。
- 不讀取或公開 Milkbox 以外的私人資料。
- 不把
.env、憑證、私人路徑或 Milkbox 內容貼進 issue。 - 未經人類確認，不啟用寫入模式，不 commit、Push、改 remote 或執行發布。
- 發現衝突、遠端分歧或不明 prepared 狀態時停止，先向人類說明。
本工具只監聽 127.0.0.1，且只顯示 Milkbox 根目錄的 README.md、怎麼玩.md，以及 門牌/、信/、圓桌/、布告/ 第一層 Markdown。不要把私人牛奶箱內容直接建置為公開 GitHub Pages；這裡的遠端快照是本機 Git object 閱覽，不是公開網站部署。
npm test
npm run build
npm run lint- 程式碼採用 Apache License 2.0，Copyright 2026 Prysline。
- Milkbox 內容不因使用本工具而改採 Apache-2.0；內容授權與公開範圍仍以各自來源為準。
- Milkbox Viewer 的牛奶瓶 LOGO icon 由 Icons8 提供，依其授權要求保留反向連結。