archive-mail-rebuild-threads

Archive Mail — Rebuild Threads Index

掃描 archive 目錄下所有 md 檔的 YAML frontmatter，從 canonical storage 重建 .threads.json。

什麼時候用

1. .threads.json 損壞或被刪除
2. 手動修改過 md frontmatter 的 thread_key（例如拆分長 thread）
3. 從舊版 archive 升級到 v2.6.0+（舊 md 沒有 frontmatter，需先 backfill frontmatter 再 rebuild）
4. 想確認 .threads.json 和 md 檔一致（當作 sanity check）

使用方式

/archive-mail-rebuild-threads
/archive-mail-rebuild-threads communications/emails

• 第一個參數（可選）：archive 目錄，預設 communication/emails

執行步驟

Step 1: 解析參數

• archive_dir: 預設 communication/emails

若目錄不存在，報錯退出。

Step 2: 解析 namespace 路徑 + 備份既有 threads.json（v2.8.0+）

NAMESPACE_DIR=".claude/.mail"
SLUG=$(echo "${archive_dir}" | tr '/' '-' | sed 's/^[-.]*//;s/[-.]*$//')
INDEX_DIR="${NAMESPACE_DIR}/state/archives/${SLUG}"
THREADS_FILE="${INDEX_DIR}/threads.json"

mkdir -p "${INDEX_DIR}"

# Auto-migrate legacy(silent)
if [ ! -f "${THREADS_FILE}" ] && [ -f "${archive_dir}/.threads.json" ]; then
  mv "${archive_dir}/.threads.json" "${THREADS_FILE}"
  echo "🔄 Migrated ${archive_dir}/.threads.json → ${THREADS_FILE}"
fi

# Backup existing threads.json before rebuild
if [ -f "${THREADS_FILE}" ]; then
  cp "${THREADS_FILE}" "${THREADS_FILE}.bak.$(date +%Y%m%d_%H%M%S)"
  echo "Backed up existing threads.json"
fi

備份不刪舊的,方便回滾。

Step 3: 掃描所有 md 檔

用 Glob "${archive_dir}/*.md" 列出所有歸檔 md。

對每一個 md：

1. Read 檔案（只需要前 30 行，frontmatter 一定在這裡面）
2. 解析 YAML frontmatter（位於檔案最前面的 --- 之間）
3. 提取：
   • message_id（必需）
   • thread_key（必需）
   • in_reply_to（可選）
   • date（必需）
   • sender（必需）
4. 若 frontmatter 缺失或必需欄位不全：
   • 記錄到 missing_frontmatter 清單
   • 不中斷流程，繼續下一檔

Step 4: 聚合成 threads 結構

建立新的 threads 物件：

new_threads = {}

for each valid md:
    key = md.thread_key
    if key not in new_threads:
        new_threads[key] = {
            "messages": [],
            "participants_set": set(),
            "first_message": null,
            "last_message": null
        }

    entry = new_threads[key]
    entry.messages.append({
        "message_id": md.message_id,
        "file": md.filename,
        "date": md.date,
        "sender": md.sender,
        "in_reply_to": md.in_reply_to or null
    })
    entry.participants_set.add(md.sender)
    if md.to/cc available in frontmatter → add to set
    entry.first_message = min(entry.first_message, md.date)
    entry.last_message = max(entry.last_message, md.date)

# 後處理
for key, entry in new_threads:
    entry.messages.sort(key=lambda m: m.date)  # 時序排序
    entry.message_count = len(entry.messages)
    entry.participants = sorted(list(entry.participants_set))
    del entry.participants_set