HomeBox Edge

HomeBox Edge 是一套非官方、serverless、HomeBox-compatible 的家庭資產管理系統。它沿用 TapCard MCP 的 Cloudflare-only 形狀：同一個 Worker 提供手機／網頁 UI、私人 API、Remote MCP、D1 資料與全文搜尋，以及可撤銷的 MCP key。

它不是 HomeBox fork，也不包含 HomeBox 的 AGPL 程式碼。v0.1 的「HomeBox-compatible」明確指向 HomeBox v0.26.2 的物件 CSV/TSV 雙向交換。

正式服務：https://homebox-edge.alan-chen75.workers.dev

現有功能

• 手機與桌面共用的家庭資產清單

• 新增、搜尋、詳情編輯、封存與還原

• 可選擇同時瀏覽及搜尋已封存資產

• D1 + FTS5：名稱、位置、品牌、型號、序號、標籤與自訂欄位搜尋

• HomeBox CSV/TSV 預覽；預覽不寫入

• 明確確認後才匯入；HB.import_ref 以 owner scope upsert

• HomeBox canonical CSV 匯出，包含封存項目

• HB.parent_import_ref、位置階層、標籤、日期、保固、出售資訊與 HB.field.*

• Remote MCP 與個別可撤銷的 hi_ connector key；D1/KV 只保存 SHA-256 指紋索引

• UI 可列出 MCP key 預覽、到期日並個別撤銷；完整 URL 只在建立時顯示

• MCP tool schema 完整公開 HomeBox-compatible 欄位並拒絕未宣告輸入

• 完整 collection ZIP manifest/table 契約已固定，restore 尚未開放

架構

Mobile / Browser / AI client
              │
       Cloudflare Worker
       ├── Static Assets：responsive UI
       ├── owner API + Remote MCP
       ├── HomeBox CSV compatibility boundary
       ├── D1：assets + FTS5 + MCP key registry
       └── KV：legacy MCP credential compatibility mirror

格式細節與版本來源見 docs/HOMEBOX-COMPATIBILITY.md，產品不變量見 docs/SPEC.md。 分階段交付與 release gate 見 docs/ROADMAP.md，正式發布與回復程序見 docs/RELEASE.md。

部署驗證範例

examples/homebox-v0.26.2-household-assets.csv 提供 24 筆可直接預覽、匯入及重播的合成家庭資產，涵蓋父子關係、中文位置與標籤、保固、投保、封存、出售及自訂欄位。資料全部標示為 Synthetic for testing only，不含真實家庭資產。預期結果與 agent 驗證順序見 examples/README.md。

MCP tools

本機驗證

需求：Node.js 20+。

npm install
npm run cf-typegen
npm run migrate:local
npm test
npm run typecheck
npx wrangler types --check
npm run build
npm audit --omit=dev --audit-level=high
npm run dev

測試門檻：lines／functions／statements 80%，branches 75%。npm test 同時執行 production-build Worker harness，使用真正的 Workerd、D1 migrations 與 KV binding 驗證資產生命週期、HomeBox CSV、MCP key 撤銷、關聯不變量、安全標頭及 request-size 邊界。

部署準備

建立 Cloudflare 資源：

npx wrangler d1 create homebox-edge
npx wrangler kv namespace create MCP_KEYS

把 D1 與 KV ID、PUBLIC_BASE_URL 填入 wrangler.jsonc，再用 secret 設定管理憑證。管理憑證不得寫入原始碼或 Wrangler vars：

npx wrangler secret put ADMIN_TOKEN
npm run cf-typegen
npx wrangler d1 migrations apply homebox-edge --remote
npm test
npm run typecheck
npx wrangler deploy

正式操作必須依 release runbook 先記錄 D1 Time Travel bookmark、檢查待套 migration，部署後再跑 health、owner API、MCP revoke 與瀏覽器 smoke test。部署後開啟 /app，輸入 ADMIN_TOKEN，再於「AI 與 MCP 連線」建立 Connector URL。完整 URL 含私人 key，視同密碼。

需要限時測試登入時，可另外設定 TEMP_ADMIN_TOKEN 與 ISO 8601 格式的 TEMP_ADMIN_TOKEN_EXPIRES_AT。Worker 只會在到期時間前接受這組憑證，既有 ADMIN_TOKEN 不受影響；兩者都應以 wrangler secret put 互動輸入，不得寫入設定檔或版本庫。

資料聲明

repo 內只有依 HomeBox 公開格式製作的合成測試資料，不含真實家庭資產、部署 ID、API key 或其他 secrets。

v0.1 邊界

• 支援 HomeBox item CSV/TSV；尚未宣稱完整 collection ZIP restore 相容。

• CSV 交換不包含照片與附件，這也符合 HomeBox CSV 的既有限制。

• R2 照片／文件將與 collection ZIP attachment mapping 一起進入下一階段。

• 目前為單一 owner 部署；多人 collection 不在 v0.1。

License

Apache-2.0。HomeBox 是獨立的 AGPL 專案；本專案只實作其公開交換格式。