WikiNB 後續改進路線圖

文件版本：01
建立日期：2026-07-31
狀態：規劃中

目的

WikiNB 已經具備 Markdown 筆記、公開搜尋、GitHub Pages、自動同步與 Codex 問答。 下一階段的重點不是繼續增加零散功能，而是補齊一個可信任的知識循環：

記錄 → 整理 → 發布或保留私人 → 找回 → 複習 → 形成下一步

最終希望 WikiNB 不只是「可以放筆記的網站」，而是能幫 Kaine：

• 找回以前寫過但已經忘記的內容。
• 定期複習重要知識。
• 看見長期沒有推進的學習目標。
• 從既有筆記整理下一步行動。
• 安全地區分公開作品與私人思考。

現況判斷

目前系統是一個可運作的個人 MVP，但仍有以下缺口：

1. wiki/ 內容會全部進入公開 GitHub Pages，缺少真正的公開／私人界線。
2. Frontmatter 與 _meta.json 同時保存標題、簡述及標籤，存在兩個真相來源。
3. index.md 需要額外維護，刪除整個資料夾時可能留下失效連結。
4. Codex 屬於使用者主動提問後才回答，尚未構成「提醒助理」。
5. Bridge 遠端連線、安全限制與失敗復原仍偏向本機原型。
6. 系統功能已比實際筆記內容成熟，需要避免持續開發卻沒有累積知識。

---

P0：先建立可信任的資料基礎

提醒功能建立在筆記資料之上，因此要先處理隱私與單一真相來源。

1. 區分公開與私人筆記

先選定一種明確規則，建議採用：

visibility: public # public | private

預期行為：

• 只有 visibility: public 的筆記能進入 GitHub Pages 建置結果。
• 未填寫 visibility 時預設為 private，避免誤公開。
• 搜尋索引與相關筆記也必須排除 private 內容。
• 上傳畫面要明確顯示公開狀態，不能只藏在進階欄位。
• 私人內容不應進入公開 repository；若仍使用同一個 repo，至少不能被產生到 dist/。

完成條件：

• 建立一篇 private 測試筆記後，公開站、搜尋資料和建置產物都找不到其內容。
• 建立一篇 public 測試筆記後，可以正常發布與搜尋。
• 文件清楚提醒：登入保護的是管理功能，不等於筆記內容自動保密。

2. 讓 Frontmatter 成為唯一真相來源

目標是移除標題、簡述與標籤在 _meta.json 和 Markdown 之間的優先級混亂。

建議：

• 管理頁更新標題時，直接安全地修改 Markdown frontmatter。
• 上傳沒有 frontmatter 的文件時，自動補齊必要欄位。
• 上傳已有 frontmatter 的文件時，合併使用者在 UI 填寫的欄位。
• 提供一次性 migration，把 _meta.json 的有效內容寫回各 Markdown。
• migration 驗證完成後，移除 _meta.json 的讀寫依賴。

完成條件：

• 在任何 Markdown 工具中打開檔案，看到的 metadata 與網站完全一致。
• 網站不需要 _meta.json 也能正確建置。
• migration 前後的頁面標題、簡述與標籤沒有遺失。

3. 自動產生索引與檢查連結

建議將 wiki/index.md 視為可重建的索引：

• 掃描 wiki/**/*.md 自動產生分類與連結。
• 新增、重新命名、刪除後統一執行 rebuild。
• 建置時檢查 slug 是否存在。
• 發現失效連結時讓測試失敗，並列出來源檔案。

完成條件：

• 刪除整個資料夾後不會留下幽靈索引。
• 重新命名後所有 wiki links 都能開啟。
• 可以只靠現有 Markdown 重建完整 index.md。

4. 強化新增與發布流程

需要清楚區分三種狀態：

已選取檔案 → 已儲存在 Mac → 已發布至 GitHub Pages

建議：

• 同名檔案預設拒絕覆寫，要求使用者明確確認。
• 寫入前先驗證檔名、frontmatter、visibility 與必要欄位。
• 先寫入暫存檔，驗證成功後再替換正式檔案。
• push 失敗時保留「本機已儲存、尚未發布」狀態，提供重新同步。
• 自動 push 前執行內容驗證與 production build。

完成條件：

• 網路中斷不會讓使用者誤以為內容已經上線。
• 同名檔案不會在沒有警告的情況下被覆蓋。
• 無效 frontmatter 或失效連結不會被自動發布。

---

P1：建立真正的提醒與複習 MVP

第一版提醒功能不需要複雜的推薦模型或向量資料庫。先利用明確 metadata 與簡單規則， 驗證它是否真的能讓使用者重新使用舊筆記。

1. 最小複習欄位

可先在需要複習的筆記加入：

review: true
last_reviewed: 2026-07-31
review_interval_days: 14
next_review: 2026-08-14
next_action: 寫一個最小範例驗證理解

欄位原則：

• review：是否加入複習系統。
• last_reviewed：上次真正看過或回答問題的日期。
• review_interval_days：目前複習間隔。
• next_review：下次到期日，可以由系統計算。
• next_action：學習或專案最小的下一步。

2. 新增 /review 頁面

第一版頁面顯示：

• 今天到期的筆記。
• 已逾期的筆記。
• 長期沒有更新的 type: learning 內容。
• 一篇隨機舊筆記，作為知識重現。
• 所有未完成的 next_action。

每篇筆記可以執行：

• 稍後提醒
• 標記已複習
• 調整下次日期
• 請 Codex 出三題
• 請 Codex 用自己的筆記內容摘要
• 將回答結果寫成新的複習紀錄

3. Codex 複習模式

增加幾個明確入口，而不是只提供空白聊天框：

• 「今天該複習什麼？」
• 「根據這篇筆記出三題，不要先給答案。」
• 「比較我現在的回答和原筆記，指出理解缺口。」
• 「整理本週新增內容與下一步。」
• 「找出超過 30 天沒有進展的 learning 筆記。」

Codex 回答必須標示使用了哪些筆記 slug，讓使用者能回到原文確認。

4. 提醒的交付階段

提醒功能分階段進行：

1. 站內提醒：登入後首頁顯示到期數量。
2. 每日摘要：Bridge 啟動時產生今日複習清單。
3. 排程提醒：由 macOS 排程或 Codex automation 定時執行。
4. Email／其他通知：只有確認站內複習真的有用後才加入。

暫時不做：

• 複雜推播服務
• 多使用者提醒
• AI 自動決定所有複習間隔
• 尚未證明需要的向量資料庫

提醒 MVP 完成條件：

• 可以列出今天到期、逾期與沒有下一步的筆記。
• 使用者能完成一次複習並更新 last_reviewed／next_review。
• Codex 能根據指定筆記出題，回答中附上來源 slug。
• 連續四週至少每週完成一次實際複習。

---

P2：決定 Codex 與 Bridge 的產品方向

需要明確選擇其中一條主路線。

路線 A：本機優先

• 公開網站負責閱讀與展示。
• 私人管理與 AI 工作主要在 Codex Desktop。
• Bridge 只監聽 localhost，不開放外部網路。
• 優點是安全、簡單、維護成本低。

路線 B：跨裝置優先

• 保留網站 Codex 與手機管理。
• Bridge 必須使用 HTTPS 或可信任的安全入口。
• 加入完整 origin allowlist、rate limiting、稽核紀錄與安全的 session 管理。
• 明確處理 GitHub Pages HTTPS 呼叫本機／私有網路服務的瀏覽器限制。

在確定真的需要手機或外部裝置使用前，預設選擇路線 A。

Bridge 必要修正

無論選擇哪條路線，都應處理：

• CORS 改成完整 origin 比對，不使用 startsWith。
• 帳密與 OTP 都加入速率限制。
• OTP 鎖定依來源或登入對象管理，不使用單一全域計數。
• 記錄登入、刪除、重新命名、同步與 Codex 執行事件。
• 顯示 Bridge 重啟後 session 失效的明確訊息。
• 遠端模式不得直接使用未加密 HTTP。

---

P3：測試、復原與維護

建立最小但有價值的自動檢查：

• 所有 Markdown frontmatter schema 驗證。
• slug 唯一性與路徑安全檢查。
• wiki links 失效檢查。
• public build 不包含 private 筆記。
• 上傳同名檔案的衝突測試。
• 刪除資料夾後索引與 metadata 清理測試。
• rename 後連結重寫測試。
• Bridge authentication 與 rate-limit 測試。
• GitHub Actions 先測試，再部署 Pages。

復原原則：

• Git 保留所有已發布內容的歷史。
• 大量 migration 前建立明確 commit。
• 提供 dry-run，先列出將修改的檔案。
• 自動操作失敗時，不刪除仍可復原的來源資料。

---

P4：內容與使用習慣

WikiNB 的成功不能只用功能數量衡量。接下來應優先累積真實內容：

• 每週至少新增或整理一篇有長期價值的筆記。
• 每篇 learning 筆記至少要有一個 next_action。
• 每週使用一次 review／Codex 回想舊內容。
• 每月底整理一次「本月學到什麼、停滯在哪裡、下月做什麼」。
• 測試筆記在完成驗證後刪除或歸檔。

建議追蹤：

• 本月新增筆記數
• 本月重新開啟的舊筆記數
• 到期複習完成率
• 有 next_action 的 learning 比例
• Codex 回答實際引用的筆記數
• 因 WikiNB 找回並再次使用的知識案例

如果持續增加網站功能，卻沒有增加筆記、複習或下一步行動，應暫停開發，先回到內容使用。

---

建議執行順序

第一階段：可靠

1. 建立 public／private 規則與測試。
2. 將 _meta.json migration 回 frontmatter。
3. 自動重建 index 並檢查 wiki links。
4. 補上同名覆寫保護與發布狀態。

第二階段：會提醒

1. 定義 review metadata。
2. 建立 /review 到期清單。
3. 加入完成複習與延後功能。
4. 建立 Codex 出題、週摘要與來源引用模式。

第三階段：可長期使用

1. 決定 Bridge 是本機優先或跨裝置優先。
2. 補齊安全、測試與復原流程。
3. 連續四週實際使用複習流程。
4. 根據使用紀錄決定下一份 Roadmap，不先預造用不到的功能。

下一個最小行動

先建立一份 public／private 設計文件：

Architecture/01_public_private_boundary_YYYYMMDD.md

文件只需要回答：

1. 私人筆記存在哪裡？
2. 公開建置如何保證不讀到私人內容？
3. Codex 可以讀哪些內容？
4. 從 private 轉成 public 的操作流程是什麼？
5. 如何用自動測試證明私人內容沒有出現在 dist/？

完成這個決策後，再開始修改程式。