RCF-031：LINE AI 助理 Brief（inbox 手機自動化）

建立日期：2026-05-01 觸發條件：5（影響 2+ 技術系統的架構決策） 狀態：✅ Brief 定稿（v1.2），Phase 1.5 ✅ + Phase 2 ✅ + Phase 3 ⚠️ 部分通過（Gemini 429 BLOCKED Step 3-5，待 Phase 3.5 修 Bug 1+2 + Quota 重置後重測） 改版上限：v1.0 → v1.3（封存舊版 = git history） 版本：v1.2（2026-05-02 補記 Phase 3 偏離 spec 觀察） 產出依據：Session 81 Tim 七輪追問 / 60+ 缺口處理 / 4 項 WebSearch 驗證 / IMP-092 教訓對應 + Session 83 Phase 2 啟動前六輪追問 32+ 缺口處理（含技術棧質疑） Brief 檔位：本文件 = Brief 主檔，後續實作以本文件為單一參考源

---

v1.2 補記說明（2026-05-02，Phase 3 部分通過後）

依 Phase 3 端到端測試實際運行結果，補記三項 spec 偏離觀察 + 兩個 Bug + Phase 3.5 修補項目：

Phase 2 vs spec 偏離（已確認，補記不修 spec）

Phase 3 發現的 Bug（進 Phase 3.5 修）

Phase 3 確認通過項目（Phase 4 不啟動，先過 Phase 3.5）

• ✅ Step 1：HMAC-SHA256 簽章驗證（無 sig + 偽造 sig 皆 401）
• ✅ Step 2 部分：M1（網頁URL）+ M3（PII 攔截）+ M4（研究主題）三條核心路徑通過
• ✅ Step 6：commit author = Tim-LINE-Bot <247732825+shoppy09@users.noreply.github.com> + format feat(inbox): LINE [類型] YYYY-MM-DD HH:MM
• ✅ Step 7：SYS-10 進 inventory.json，status = deployed_unverified（不可標 live）

Phase 3.5 啟動條件

• Gemini quota 重置（次日台灣時間 ~16:00 PT 重置）
• Bug 1 修法 + deploy
• 完整重跑 Step 2-5（M2/M5 + Step 3 PII / Step 4 !force / Step 4.5 Markdown / Step 5 並發）

v1.2 不影響項目

• Section 1-5 帳號方案/閉環機制/技術架構/userId 防守/資安要求 = 不變
• Section 6.1 #1-#2、Section 7 之後 = 不變
• 5 Phase 結構 = 不變（Phase 3 內含 Phase 3.5 子階段，不單獨計數）

---

v1.1 修訂說明（2026-05-01）

依 Phase 2 啟動前 Session 83 六輪追問共 32+ 盲點處理結果，重大方向變更：

v1.0 封存方式：採 git history（git log knowledge/decisions/RCF-031-line-ai-assistant.md）即視為封存，無需另存 archived 副本（RCF-001 慣例補入）

---

Section 1：問題定義 + 帳號方案決策 + 閉環機制決策

1.1 問題定義

RCF-023「整理知識庫」SKILL 後續行動明列「LINE AI 助理（inbox 手機自動化）」為待開發任務。當前 Tim 需電腦端開 Claude Code 才能寫入 knowledge/inbox.md，手機端無便捷捕捉路徑 → Tim 在外靈感、文章連結、待辦觀察容易遺失。

1.2 帳號方案決策：方案 B（新開內部用 LINE OA 帳號）

選 B 理由：風險隔離原則 + 簡化 Brief 結構 + 對應 IMP-092 教訓

1.3 閉環機制決策：39-B 短期 + 39-A 長期混合

---

Section 2：三層架構圖 + inbox.md schema + 訊息類型路由

2.1 架構圖（v1.1：GAS → Vercel Function）

Tim 手機 LINE
    ↓ 傳訊息
新 LINE OA Bot「Tim 知識管家」（內部用）
    ↓ Webhook event POST + x-line-signature header
Vercel Serverless Function /api/line-webhook（Hobby 60s 上限）
    ↓ 1. signature 驗證（HMAC-SHA256，Vercel 提供 headers）
    ↓ 2. userId 過濾（非 Tim → 不處理）
    ↓ 3. Vercel KV 查 idempotency key（防 LINE retry 重複）
    ↓ 4. reply「✅ 收到，整理中」立即返回 LINE
    ↓ ─── async 後續處理 ───
    ↓ 5. Gemini API 兩階段：① 個資偵測 ② 分類摘要
    ↓ 6. GitHub Contents API 寫入 knowledge/inbox.md（SHA 樂觀鎖 + retry 3 次）
    ↓ 7. LINE pushMessage 回 Tim「✅ 已記入 inbox [類型]」或「⚠️ 個資攔截」

2.2 inbox.md schema（v1.1：對齊既有單行格式）

每條條目固定格式（對齊 inbox.md 既有路由表 + 「整理知識庫」SKILL Step 6）：

- [ ] [LINE YYYY-MM-DD HH:MM] [類型] 主要內容 // Gemini 摘要

類型 5 類字串（嚴格對齊 inbox.md 路由表）：

• 網頁URL / YouTube / IG-Threads帳號 / 研究主題 / 本機文件

寫入位置：## 待處理項目\n\n 之後、第一個 --- 之前 第一次寫入：偵測「（空，等待第一筆記錄）」字串並一併移除

桌機/手機統一（M 缺口處理）：

• 手機端 Bot 寫入：- [ ] [LINE 日期 時間] [類型] 內容 // 摘要
• 桌機端 Claude 寫入：- [ ] [Tim-桌機 日期 時間] [類型] 內容 // 摘要
• 兩者皆使用相同 5 類類型字串，差異只在來源標籤（LINE vs Tim-桌機）

WHY 對齊既有格式：

• 「整理知識庫」SKILL Step 6 路由邏輯依「項目類型」字串對應 → 新格式直接相容無需修改 SKILL（RCF-033 不觸發）
• RCF-032 收尾自查 N 計數仍以 - [ ] 開頭計數，新格式相容
• Tim 桌機端既有寫法（無前綴）改為加前綴，整體一致性高 + 來源可追溯

2.3 訊息類型路由

---

Section 3：外部 SaaS 設定清單（v1.1：5 項 + Vercel KV）

---

Section 4：userId 防守邏輯 + 程式碼範例（v1.1：TypeScript / Vercel Function）

// /api/line-webhook.ts (Vercel Serverless Function, Node.js runtime)
import { NextApiRequest, NextApiResponse } from 'next';
import crypto from 'crypto';
import { kv } from '@vercel/kv';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // ① Signature 驗證（v1.1 新增 — Vercel 提供 HTTP headers）
  const signature = req.headers['x-line-signature'] as string;
  const rawBody = JSON.stringify(req.body);
  const hash = crypto.createHmac('sha256', process.env.CHANNEL_SECRET!).update(rawBody).digest('base64');
  if (signature !== hash) return res.status(401).end();

  const event = req.body.events[0];

  // ② userId 過濾
  if (event.source.userId !== process.env.TIM_USER_ID) {
    await replyMessage(event.replyToken, '此帳號為內部使用，無法回應外部訊息');
    return res.status(200).end();
  }

  // ③ Idempotency 防 retry 重複（Vercel KV）
  const eventKey = `evt:${event.webhookEventId}`;
  if (await kv.get(eventKey)) return res.status(200).end();
  await kv.set(eventKey, '1', { ex: 30 * 24 * 60 * 60 }); // 30 天 TTL，自動過期免手動清理

  // ④ 立即 reply「✅ 收到」（避免冷啟動 + Gemini 兩階段超時 LINE 5 秒上限）
  if (event.message.type === 'text') {
    await replyMessage(event.replyToken, '✅ 收到，整理中...');
    res.status(200).end(); // 200 後 Vercel Function 仍可繼續執行（Hobby 60s）

    // ⑤ async 後續：Gemini 兩階段
    try {
      const piiCheck = await detectPII(event.message.text); // D3-A 個資攔截
      if (piiCheck.hasPII && !event.message.text.startsWith('!force')) {
        await pushMessage(event.source.userId, `⚠️ 訊息含疑似個資（${piiCheck.detected}），未寫入。如為公開資訊請加 \`!force\` 重傳`);
        return;
      }

      const cleanText = event.message.text.startsWith('!force') ? event.message.text.slice(6).trim() : event.message.text;
      const { category, summary } = await classifyAndSummarize(cleanText);
      await writeToInbox({ category, summary, original: cleanText, timestamp: new Date() });
      await pushMessage(event.source.userId, `✅ 已記入 inbox [${category}]`);
    } catch (err) {
      await pushMessage(event.source.userId, `❌ 處理失敗：${err.message}`);
    }
  } else {
    await replyMessage(event.replyToken, `⚠️ 此類型 (${event.message.type}) 暫不支援整理`);
    res.status(200).end();
  }
}

WHY Serverless 而非 Edge：Gemini 兩階段（個資偵測 + 分類）可能 > 10 秒，Edge Function 10s 上限太緊，Serverless 60s 上限充裕

---

Section 5：資安要求（v1.1 升級）

5.1 基礎防護（v1.0 既有）

• ✅ Webhook signature 驗證（HMAC-SHA256，Vercel 提供 headers，v1.1 已可實作）
• ✅ 5 項憑證全部放 Vercel env vars（CHANNEL_SECRET / CHANNEL_ACCESS_TOKEN / TIM_USER_ID / GEMINI_API_KEY / GITHUB_PAT），零硬編碼
• ✅ GitHub Fine-grained PAT scope 最小化：contents:write + repo 限定 shoppy09/tzlth-hq
• ✅ PAT 30 天輪替計畫（Phase 5 加入 weekly-schedule.md 月底任務）
• ✅ Logger 過濾：error log 只記 error.message + stack 首 3 行，不寫 user input / token / userId

5.2 個資攔截規則（v1.1 新增 D3-A）

目的：防止 Tim 諮詢中順手手機筆記時，客戶識別資料誤入 Gemini API（依其條款可能用於模型訓練）+ 永久存於 hq repo

Gemini 兩階段流程：

1. 階段 1：個資偵測（prompt：「偵測此訊息是否含人名、公司名、email、電話、身分證號。回傳 JSON: {hasPII: bool, detected: string[]}」）
2. 階段 2：分類摘要（僅當階段 1 通過或 !force 時執行）

Tim 白名單 seed（Vercel env var WHITELIST_SEEDS，可由 Tim 自訂擴充）：

蒲朝棟,Tim,蒲老師,蒲顧問,職涯停看聽,shoppy09,
Anthropic,Claude,Google,Gemini,Vercel,Render,GitHub,LINE,
Microsoft,Notion,NotebookLM,OpenAI,YouTube,Threads,Instagram,Facebook

Gemini prompt 強制忽略白名單（白名單詞出現不算個資）

!force 例外：訊息開頭加 !force → 跳過個資偵測直接寫入（用於公開資訊或 Tim 確認過的內容）

攔截後行為：reply「⚠️ 訊息含疑似個資（XX），未寫入。如為公開資訊請加 !force 重傳」+ 不寫 inbox

5.3 殘留風險聲明

• Webhook URL 一旦洩漏 → 攻擊者可送假 webhook（signature 驗證可擋；此為第二道防線）
• Gemini API 處理時依其條款可能保留 — 個資攔截為主要防護
• Tim userId 已洩漏（Phase 1 截圖事件）→ Phase 4 觀察期通過後 Revoke + Re-issue Channel Access Token 一次性收斂

---

Section 6：Vercel Function 處理流程（v1.1 重寫）

6.1 響應時間策略

為何 reply + push 雙階段：

• LINE replyToken 僅 1 分鐘有效 + 一次用 → 不能等所有處理完才 reply
• Gemini latency 不可預測（WebSearch 顯示有 5-30s 案例）→ 同步處理風險過高
• Vercel async/await 模型支援 reply 後繼續執行（vs GAS 同步限制）

6.2 冷啟動緩解

• Vercel Hobby Serverless 冷啟動 0.5-2s → 第一個訊息可能逼近 5 秒上限
• 緩解 1：reply「✅ 收到」設為固定字串（不需 Gemini，最快響應）
• 緩解 2：Vercel Cron Job 每 5 分鐘 ping /api/keepalive 保暖（可選）

6.3 GitHub Contents API SHA 衝突處理

• LockService 不再需要（Vercel Function 並發由 Vercel runtime 管理）
• 422 conflict → re-GET sha + retry 3 次指數退避（1s/2s/4s）
• 與 Tim 桌機端 Claude Edit 並發：Bot 端 retry，Tim 桌機端 Claude Edit 失敗時自動 re-Read 重試

---

Section 6.1：邊界處理（v1.1 新增）

---

Section 7：成本評估（v1.1 更新）

---

Section 8：Tim 現況實測前置（Phase 1 ✅ 已完成）

---

Section 8.5：Phase 1.5 GAS→Vercel 遷移 Tim 操作 checklist（v1.1 新增）

啟動條件：v1.1 Brief 通過後立即執行 預估時間：Tim 操作 30-45 分鐘

Phase 1.5 完成標準：步驟 8 smoke test 通過 → Phase 2 啟動條件達成

---

Section 9：風險與回滾（v1.1 更新）

---

Section 10：實作 P3 衍生條目（v1.1 更新：5 → 6 Phase）

並行衍生：

• RCF-032 ✅ 已完成（CLAUDE.md 收尾自查掃 inbox HARD STOP，39-B 短期閉環）
• SYS-10（inventory.json 新增「LINE 知識管家 Bot」內部工具）— Phase 3 完成後執行
• RCF-033 ❌ 不觸發（Read SKILL Step 6 確認新格式相容）

---

Section 11：SYS-05 零影響聲明（v1.0 既有，維持）

本案完全不動 SYS-05（既有品牌 LINE OA）的任何設定，驗證方法：Phase 4 觀察期內每週查 SYS-05 LINE OA Manager「自動回應訊息」設定截圖比對。

---

Section 12：SYS-10 治理決策 + RCF-032 並行升規

12.1 SYS-10 inventory.json 新增（Phase 3 完成後執行）

{
  "id": "SYS-10",
  "name": "LINE 知識管家 Bot",
  "category": "employee",
  "type": "saas-integration",
  "tech_stack": ["LINE Messaging API", "Vercel Serverless Function", "Upstash Redis (Vercel KV)", "Gemini 2.5 Flash API", "GitHub Contents API"],
  "status": "live",
  "owner": "Tim 個人",
  "purpose": "手機端 inbox.md 自動寫入閉環"
}

12.2 RCF-032 ✅ 已完成（2026-05-01 Session 81 升規）

---

Section 13：RCF 觸發判斷

• 本 RCF-031：條件 5（影響 LINE OA + Vercel Function + Vercel KV + Gemini API + GitHub API + hq repo 6 系統）✅ 觸發
• v1.0 → v1.1 修訂：屬內部版本迭代，不觸發新 RCF（封存方式 = git history，RCF-001 慣例補入）
• 衍生 RCF-032 ✅ 已完成
• 衍生 RCF-033 ❌ 不觸發（SKILL Step 6 新格式相容）

---

Section 14：v1.1 修訂跨系統影響聲明（v1.1 新增）

本次 v1.1 修訂涉及以下系統與文件：

對 Phase 5（39-A）影響：v1.1 schema 變更後續讀取邏輯需對齊，但 Phase 5 尚未實作，啟動前自然會對齊 ✅ 對既有 GitHub Actions cron 影響：✅ 無（cron 用 git pull --rebase --autostash 處理並發；Bot 用 GitHub Contents API 不衝突）

---

執行記錄