AI 維護守則

工作範圍

親戚只提供 LINE、表單、照片、口述或文件;結構資料由 AI 整理、由程式驗證。任何 AI 都必須把 content 與 data 視為母資料,把 JSON、網站與匯出檔視為可重建產物。

必守規則

  1. 原始史料永不修改、永不刪除;修復版另存新檔。
  2. ID 永不更換、永不重用。人物改名或合併也保留舊 ID 轉址。
  3. 父母只寫在子女檔;不得手工維護子女反向清單。
  4. 妻、前妻、後妻、繼室、妾、收養、過房使用關係節點;日期只寫事件節點。
  5. 妻與妾必須分類;傳統譜載的前妻、後妻表示先後次序,不得自動寫成離婚。現代資料明載「前夫」時,另一端對稱記為「前妻」,但只表示曾婚配且關係已結束;離婚、喪偶、再婚或死亡仍須有來源才能標記。
  6. 不確定原文照錄並標示,不得用猜測填滿空欄。
  7. 每筆事實保留來源與頁碼。AI 新增內容預設 unreviewed。
  8. 可能在世者預設 draft: true、visibility: family。
  9. 人工補述只增不改,每則標示提供者與日期;更正舊說時保留更正紀錄。
  10. 譜牒 PDF、JPG 與轉錄附件只從 00-原始資料/族譜掃描/ 讀取;quartz/static/archive/ 與 public/static/archive/ 是衍生物,不得反向覆蓋原件。
  11. 新典藏組的 publish_public 預設為 false,供「公開遮罩模式」判斷;親友密碼完整版依資料持有人 2026-08-12 的明確決定,會發布全部典藏內容。
  12. 全站 JavaScript 共用密碼門只作為親友間的簡易閱覽門檻,不得在文件或介面中宣稱為加密、身分驗證或真正的隱私隔離。資料持有人已明確選擇讓 GitHub Pages 使用完整資料;任何維護者不得誤認靜態檔受技術性保密。

修改流程

  1. 先讀人物、關係、事件及來源節點。
  2. 判斷事實的唯一權威位置,只改一處。
  3. 日常資料或文件修改先執行 npm.cmd run verify:fast;它會驗證收件 Schema、LINE Worker 及人物/關係資料。
  4. 若出現 broken reference、循環、生晚於死、Schema 錯誤或公開遮罩模式的隱私洩漏,必須停止。
  5. warnings 可保留,但需在交付說明列出新增或改變的項目。
  6. 準備發布前執行 npm.cmd run verify:release;它會跑完整測試並以親友密碼完整版建置正式網站。
  7. 只有需要單獨除錯時才直接執行 npm.cmd run family:build、npm.cmd run build:dev、npm.cmd run build:family 或 npm.cmd run build:public,不得用局部成功取代完整發布驗證。build:site/build:family 是完整親友版;build:public 是公開遮罩版。

程式變更與 Git 追蹤

  1. 修改程式、資料模型、編譯流程、版面規則或大量人物資料時,必須同步更新 變更紀錄;不得只在對話中說明。
  2. 重大事項必須更新 content/00-說明 內對應的正式文件:資料結構改動寫入《資料格式》,互動改動寫入《小世界互動圖方案》,階段與已知問題寫入《開發計畫》。
  3. 每筆重大變更紀錄至少包含:日期、類型、變更原因、實際修改內容、影響範圍、驗證方式、Git 狀態。
  4. Git 提交訊息須清楚說明目的與範圍;可使用中文,或沿用目前儲存庫可辨識的英文 Conventional Commit 風格。不同目的的修改應分開提交,禁止把無關變更混成一個難以追查的提交。
  5. 提交前先檢查 git diff 與 git status,不得覆蓋使用者既有修改;提交後回報提交摘要與雜湊值。
  6. 未經使用者明確要求,不得推送 GitHub。只建立本機提交時也要明確說明「已提交、尚未推送」。
  7. 若工作尚未提交,交付時必須明確寫出「尚未提交」,不得讓使用者誤以為已進 Git。
  8. 個別人物的小型史料校訂寫入人物 notes;影響多人、判定規則或網站行為的校訂,另須寫入《變更紀錄》。

禁止事項

  • 人工編輯 quartz/static/family-data.json。
  • 為了畫圖而把妻妾或女性塞成男性人物的附屬欄位。
  • 為了排版固定「第幾代」為永久身分。
  • 把只有年份的資料改成完整日期。
  • 未經資料持有人明確決定,就在對外公開遮罩模式輸出可能在世者的完整生日、地址、照片或未授權故事。現行親友密碼完整版雖依明確決定輸出完整資料,仍須把 JavaScript 密碼視為可繞過的簡易門檻,不得擅自加入更敏感內容。
  • 因為本機開發版可以看到原件,就推定 GitHub Pages 也已取得公開授權。