visionA/local-tool/.autoflow/05-implementation/reviews/M1-1-review.md

M1-1 Review Report — repo 骨架初始化

審查者：Reviewer Agent 審查時間：2026-04-10 審查範圍：M1-1 產出（.gitignore / Makefile / README.md / 目錄骨架 / .gitkeep） 參考文件：

• .autoflow/04-architecture/architecture-overview.md §4.1
• .autoflow/04-architecture/build-pipeline.md §1、§2、§3
• .autoflow/progress.md（第三輪 Q-D 決策：vendor/ 不進 git）

---

結論：✅ 通過（含 3 項 🟢 建議，不阻斷 M1-2）

整體品質良好，目錄結構、.gitignore 的 vendor/ 排除策略、Makefile target 覆蓋度、README 平台版本標註都符合規格。沒有誤建 go.mod / package.json / wails.json，也沒有 git init。以下列出 3 項建議項目，可在 M1-2 前順手補上，或延到後續任務處理。

---

檢查清單

1. 目錄結構對齊 architecture-overview.md §4.1

• server/ 存在（含 .gitkeep） — M1-2 會複製 edge-ai-platform 的 Go 後端
• frontend/ 存在（含 .gitkeep） — M1-4 會複製 Next.js 業務前端
• visiona-local/ 存在（含 .gitkeep） — M1-9 會從 installer/ 複製 Wails shell
• payload/ 存在（含 .gitkeep）
• vendor/ 存在（含 .gitkeep） — 雖 architecture-overview §4.1 原圖沒畫出 top-level vendor/，但 build-pipeline.md §2 明確定義 /Users/jimchen/visionA/local-tool/vendor/ 為依賴快取根目錄，建立是正確的
• dist/ 存在 — 用於最終發行物
• scripts/ 存在（含 .gitkeep） — build-pipeline.md §3.1 有 scripts/vendor-sync.sh、§1 installer-linux 有 scripts/build-appimage.sh，合理
• Makefile 與 README.md 在 repo root

2. .gitignore 正確性（對照 build-pipeline.md §2.4）

• /vendor/** 被排除（R4-Q-D 決策 D2：vendor 不進 git）
• !/vendor/.gitkeep 白名單保留
• !/vendor/README.md 白名單保留（但實際 README.md 尚未建立 — 見 🟢-1）
• /dist/ 排除
• /visiona-local/build/ 排除（Wails build 輸出）
• /visiona-local/payload/ 排除（build 暫存），!/visiona-local/payload/.gitkeep 白名單
• /payload/*.tar.gz、/payload/*.zip 排除
• Go 常見忽略齊全（*.exe / *.dylib / *.so / *.test / go.work.sum）
• Node/Next.js 常見忽略齊全（node_modules/ / .next/ / out/ / *.tsbuildinfo / .pnpm-store/）
• Python venv、cache 齊全
• OS 忽略齊全（.DS_Store / Thumbs.db / desktop.ini / ._*）
• Editor（.vscode/ / .idea/ / *.swp）
• Secrets（.env* / *.pem / *.key）
• 保留既有的 .claude/ 與 .autoflow/.backups/ 規則

3. Makefile target 命名對齊 build-pipeline.md §1

build-pipeline.md 規格	M1-1 實作	狀態
help	help	✅
dev / dev-mock	dev / dev-mock	✅
build-server	build-server（+ alias server）	✅
build-frontend	build-frontend（+ alias frontend）	✅
build-embed	build-embed	✅
payload / payload-macos/windows/linux	同名	✅
installer-macos	拆成 wails-macos + dmg	⚠️ 見下
installer-windows	拆成 wails-windows + exe	⚠️ 見下
installer-linux	拆成 wails-linux + appimage	⚠️ 見下
vendor-sync	vendor-sync（新增，build-pipeline.md §3.1 有腳本）	✅
test / lint / fmt / clean	同名	✅

命名差異說明： Backend 把 installer-{os} 拆成兩段（wails-{os} 負責 wails build、dmg/exe/appimage 負責打包成發行檔）。這個拆分可接受，理由：

1. 單一職責更清晰，debug 時可只跑 wails build 不打包
2. CI 可以分開 cache wails build 產物
3. 未來要換打包工具（例如 dmgbuild → create-dmg）只影響後半段
4. 可以加一個 installer-macos: wails-macos dmg 的聚合 target 保持對 spec 的向下相容（見 🟢-2）

4. README.md 平台版本標註

• macOS 14 (Sonoma) / 15 (Sequoia)，x86_64（Apple Silicon 走 Rosetta 2）✅
• Windows 10 / 11，x86_64 ✅
• Ubuntu 22.04 / 24.04，x86_64 ✅
• 明確標註「不支援 ARM native（使用者決策 Q4）」
• 有目錄結構說明、文件索引、狀態（M1 開發中）
• 開發者快速開始有提醒「M1-1 所有 target 都是 placeholder，不會真的 build」，避免誤解

5. 禁區檢查

• 沒有誤建 go.mod（root / server/ 都沒有） — M1-2、M1-3 會處理
• 沒有誤建 package.json（frontend/） — M1-4 會處理
• 沒有誤建 wails.json（visiona-local/） — M1-9 會處理
• 沒有 .git/ 目錄 — 未執行 git init，正確
• 沒有 go.work — architecture-overview §4.1 有列出，但屬 M1-3 範圍，M1-1 跳過是對的

---

問題列表

🔴 阻斷

（無）

🟡 需修

（無）

🟢 建議（不阻斷 M1-2，可順手補）

🟢-1：建立 vendor/README.md 說明依賴取得方式

.gitignore 已經把 !/vendor/README.md 列為白名單，但實際檔案尚未建立。建議補一份最小版本，說明：

• vendor/ 的用途（離線依賴快取）
• 為什麼不進 git（R4-Q-D 決策，避免 binary bloat）
• 如何取得（make vendor-sync）
• 子目錄結構（python/ / wheels/ / ffmpeg/ / yt-dlp/ / drivers/）

這樣新開發者 clone 之後看到空的 vendor/ 不會疑惑。

優先級： 低，可在 M1-2 前順手加，或延到 M3（首次真的用到 vendor/ 時）再補。

🟢-2：加一個 installer-{os} 聚合 target 保持向下相容

為了跟 build-pipeline.md §1 原本的命名一致，建議在 Makefile 加：

installer: installer-$(OS)
installer-macos: wails-macos dmg
installer-windows: wails-windows exe
installer-linux: wails-linux appimage

這樣 build-pipeline.md 原本提到的 make installer-macos 依然能用，又保留 Backend 拆分後的細粒度 target。目前 M1-1 先不做也可以，M1-12（dmg 完成時）再補即可。

優先級： 低，可延到 M1-12。

🟢-3：dist/ 目錄沒有 .gitkeep

目前 dist/ 是空目錄，git 不會追蹤空目錄，下次 clone 後 dist/ 會消失，雖然 Makefile 的 build-server 會 mkdir -p $(DIST)，但建議補一個 .gitkeep 保持一致性（其他五個目錄都有）。注意 .gitignore 的 /dist/ 規則會讓 .gitkeep 也被忽略，需要改成：

/dist/*
!/dist/.gitkeep

或乾脆不保留空 dist/ 目錄，改在第一次 build 時才建立（Makefile clean 已經會 mkdir -p $(DIST)，其實不需要在 repo 中預留目錄）。

建議： 採後者，刪掉目前空的 dist/ 目錄，由 Makefile 負責建立即可，.gitignore 維持 /dist/ 不變。這樣更乾淨。

優先級： 低。

---

通過後可以進入 M1-2 嗎？

可以，立刻進入 M1-2（複製 server core from edge-ai-platform）。

M1-1 的品質已達標，3 項建議都是錦上添花，不影響後續任務：

• 🟢-1（vendor/README.md）可延到 M3
• 🟢-2（installer 聚合 target）可延到 M1-12
• 🟢-3（dist/ 空目錄）可隨時順手處理

Orchestrator 可直接呼叫 Backend Agent 開始 M1-2。