本頁彙整已知的技術債、風險與償還策略,供維護者排序。分為「程式碼」「架構」「文件/流程」「相依性」四類。
償還原則:優先處理「會影響可重現性或正確性」的項目,其次是「拖慢新使用者採用」的項目。
| 項目 |
位置 |
風險 |
建議 |
| 硬編路徑殘留 |
META_PIPE_ROOT 已可組態,但仍需全面稽核其他腳本是否有 /Users/htlin/meta-pipe 假設 |
中:非本機環境會壞 |
grep 全庫 /Users/htlin,改用相對或環境變數 |
| 未實作的資料解析 |
generate_quickstart_guide.py:40 — # TODO: Parse actual data from files
|
低:目前用佔位資料 |
接上真實專案資料來源 |
| 測試 fixture 與 schema 易漂移 |
tests/ 中依賴檔案結構的測試 |
中:schema 一改就紅 |
抽出共用 fixture builder,schema 集中定義 |
| Merge conflict 殘留風險 |
git status 顯示 tooling/python/ai_screen.py 曾處於 UU(未解衝突)狀態 |
高:未解衝突會導致執行錯誤 |
確認衝突已解、ai_screen.py 可正常 import 與執行 |
| 項目 |
說明 |
建議 |
| Python / R 雙語邊界 |
資料在 Python(CSV/DB)與 R(分析)之間交換,schema 契約隱性 |
明確定義交換格式與欄位契約,加驗證層 |
| Skill 即文件即介面的耦合 |
流程邏輯分散在多個 SKILL.md,修改需人工同步 |
建立 SKILL 之間的交叉引用檢查(延伸 /module-management) |
| Agent teams 仍為實驗性 |
平行寫入靠「目錄所有權」約定,缺乏強制隔離 |
用 hook 強制檔案所有權,或改 worktree 隔離 |
| 品質模式雙軌 |
strict/draft 分支散落在多處判斷 |
集中到 project_meta.py,避免遺漏分支 |
| 項目 |
說明 |
建議 |
| README 缺完整使用範例 |
issue #6 |
補端到端範例 + 截圖/影片(#37) |
| GUI 方向分歧 |
PR #41 與 #8 並存 |
收斂為單一路線,關閉重複 PR |
[Unreleased] 累積過多 |
CHANGELOG 已累積 3 個 Sprint |
切版釋出,建立明確版本節點 |
| 大量 Markdown(約 41,700 行) |
skills/references 內容龐大,易有陳舊段落 |
定期用 vale 或連結檢查掃描失效引用 |
| 項目 |
說明 |
建議 |
| Claude CLI 版本綁定 |
ai_screen.py 需 CLI ≥ 2.1.100 且特定 flag |
已有 _assert_claude_cli() 啟動檢查;持續追 CLI flag 變動 |
| 外部 API 依賴 |
Entrez / CrossRef / OpenAlex / Unpaywall / Scopus |
已有 fallback 鏈;補上速率限制與快取以降風險 |
| R 環境設定脆弱 |
setup.sh 曾在 macOS ARM 因 fs 套件需 cmake 失敗(#24,已修) |
R 套件化(#18)可根本降低此類風險 |
| uv/renv 鎖檔漂移 |
新增依賴若忘記 lock/snapshot 會破壞可重現性 |
CI 檢查 lock 一致性 |
-
高:確認
ai_screen.py 無殘留 merge conflict、可正常執行。
-
高:全庫稽核硬編路徑,確保跨環境可重現。
-
中:測試 fixture/schema 去耦合。
-
中:切版釋出、清空
[Unreleased]。
-
低:補文件範例、收斂 GUI、Markdown 陳舊內容清理。