工研院活動溝通 AI 平台（itri-event-ai）
多活動共用的記者會 AI 問答平台。記者在網頁或 LINE（米亞） 問活動的新聞稿內容，承辦人在後台管活動與看數據；
另外還有 AI 能見度追蹤（GEO）、媒體訓練、活動報名（原名「媒體報名」，批次 112 改名），以及給業發處的企業場與合作洽詢（批次 118、119）。純 Node serverless（Vercel）＋靜態 HTML＋Google Sheets 當資料庫，沒有前端框架。
有哪些入口
| 誰用 | 網址 | 主要檔案 |
|---|
| 記者（網頁問答） | /event?id=… | public/event.html、api/chat.js、api/event-page.js（SSR，給搜尋引擎與 AI 爬蟲讀） |
| 記者（LINE 米亞） | LINE 官方帳號 | api/line.js（webhook 入口）、lib/line-*.js（記者、群組、職員、報名各一支，對照表在 api/line.js 開頭）、lib/router.js、lib/menu.js、lib/staff.js |
| 承辦人（後台） | /admin | public/index.html、api/events.js、api/analytics.js、api/export.js |
| 同仁（改自己那一場） | /edit?id=…&code=… | public/edit.html、api/events.js（get_edit／update_edit） |
| 主管（成效報告） | /report | public/report.html（含互動簡報 report-deck.js／.css）、api/exposure.js |
| 部會／計畫主管機關（單場計畫成效，唯讀） | /impact?id=…&k=…（後台活動卡片「更多」產生） | public/impact.html、lib/impact.js、lib/impact-api.js（搭在 api/events.js，批次 151） |
| AI 能見度追蹤 | /geo | public/geo.html、api/geo.js、lib/geo-*.js |
| 承辦人與同仁（記者名單健檢） | /media.html（後台側邊欄；同仁用共用連結 ?code=） | public/media.html、api/media.js |
| 主管（媒體訓練） | /training | public/training.html、api/training.js |
| 記者（活動報名）／後台：所有活動與名單 | /register／/registrations | public/register.html、public/registrations.html、lib/registration*.js |
| 企業（合作洽詢單） | /inquiry | public/inquiry.html、lib/b2b-api.js（搭在 api/events.js 的 b2b_ 系列） |
| 企業洽案管理（原「業發處」，批次 157 改名；收件匣、客戶專屬頁／全部企業場、成員、設定、稽核） | /b2b（每個人自己的連結 /b2b#k=…） | public/b2b.html、lib/b2b.js（資料在另一本試算表）、lib/b2b-api.js、lib/b2b-line.js（米亞那一端） |
先讀這幾份
- CLAUDE.md——朱朱交代過、每一次都適用的長期約定（只用台灣繁體中文、「絕對不能發生」的事擋在程式出口、米亞只有一種聲音、影片一定要有聲音軌、紀錄放哪裡）。
- SETUP.md——部署、環境變數、Google 試算表怎麼建、Vercel 免費方案的 12 支 Function 上限（現在
api/ 用了 11 支）。
- LINE-PLAN.md——長期規格：定位、資料模型、七個會害你重做的坑、LINE 的意圖、prompt 規則、不要做的事。
- docs/batches/README.md——每一批改動的來龍去脈（為什麼這樣改、踩到什麼坑）。程式碼註解寫「批次 N」就到這裡找。
- AI 能見度：GEO_SETUP.md（怎麼設定）、GEO-METHOD.md（測量方法與依據）。FIX-PLAN.md 是已完成的工單紀錄。
開發與驗證
npm test # 全部測試，約 35 秒。用假的 Google Sheets／LINE／模型，不需要金鑰、也不需要 npm install
npm test -- flow batch110 # 只跑檔名含這些字的測試
SHIFT_DAYS=90 npm test # 把「現在」往後撥 90 天再跑，專門抓寫死日期的測試
GitHub Actions（.github/workflows/test.yml）每個 PR 與 main 推送都會跑上面第一種與第三種（SHIFT_DAYS=90），最後再把業發處的設定打開（B2B_SPREADSHEET_ID）把全部測試多跑一輪——業發處開著，既有功能照樣要全過（批次 119）。
新增測試只要把 test-*.mjs／*.test.mjs 放進 test/，不用改清單。
不進 npm test 的檢查（需要 playwright 與 Chromium，前置 npm i playwright --no-save；或要花錢、要網路）：
| 工具 | 做什麼 |
|---|
tools/geo-ui-check、tools/reg-ui-check、tools/training-flow-check.mjs、tools/training-voice-check.mjs | 在真的瀏覽器裡把 /geo、/registrations（活動報名後台）、媒體訓練的流程與語音跑一遍 |
tools/sri-check | 驗證 CDN 資源的 SRI 雜湊（原檔通過、竄改過的被瀏覽器拒絕） |
tools/persona-check（line.mjs、web.mjs） | 四種角色（同事、記者、主管、洽案廠商）把 LINE 與網頁前後台實際走一遍，帶斷言；網頁那支用 Chromium、後端是真的 api/*.js（試算表與 AI 是假的）。改了權限、選單、後台助理、名單、洽詢單之後跑一次（批次 144） |
tools/line-button-audit、tools/line-group-sim、tools/line-persona-sim | 把 LINE 的每一步、群組對話、四種角色丟進真的 api/line.js，看按鈕與回應（AI 是假的，看的是規則層） |
tools/grounding-backtest | 把後台匯出的真實問答丟進去，量「答案出口檢查」（ANSWER_GROUNDING）的誤報率，決定要不要打開（批次 132；真實問答含個資，別 commit） |
tools/model-ab | 同一批問題比兩個模型的答案（會花真的錢） |
tools/time-travel | SHIFT_DAYS 用的時間位移 |
tools/guide-video | 使用說明影片與米亞的聲音（見 CLAUDE.md 第 3、4 條） |
動手前先記住
- 會踩到 Google Sheets 的讀取額度（每分鐘 60 次、全站共用）。公開入口讀活動表一律走
lib/events-table.js 的快取，不要各自 readRange('events!…')。
- 管理員與編輯碼的比對一律走
lib/auth.js（requireAdmin()、codeMatches()），不要自己寫 password !== …——那樣在密碼沒設定時會放行。
- 「絕對不能發生」的事擋在程式出口，不是寫在 prompt：繁體字（
lib/zh-tw.js 的 toTraditionalTW()）、發布閘門（lib/event-status.js）、網頁問答一定要有媒體名稱（api/chat.js）、管理員驗證（lib/auth.js）。
- 新增後台頁面時，要把它加進
vercel.json 的安全標頭規則（test/test-batch110.mjs 會逐頁檢查）。
- 企業場不出現在記者看得到的地方：活動類型是企業說明會／技術媒合會／客戶參訪／技術交流會的場次，以及報名對象選「企業」的報名，米亞的清單、公開列表、搜尋引擎都看不到（LINE-PLAN.md 第 8 節，
lib/audience.js）。新增任何「列出活動」的入口，要先想清楚企業場該不該在裡面。
- 寫入 Sheets 不是每一種都能重送：
appendRows()（加一列）與 batchUpdate()（刪列、加分頁）逾時或 500 時不重試，免得多一列或刪錯列（批次 117，見 lib/sheets.js）。新增會呼叫模型的地方，記得接 logAiUsage()（test-batch117 會檢查）。
- 業發處的東西不能影響記者與既有功能（朱朱 10/8：「務必確保不要影響既有的功能與媒體之使用」）：客戶資料只放
B2B_SPREADSHEET_ID 那本，沒設定就整套停用、絕不退回記者會那本（lib/b2b.js 的 db()）；業發處的 LINE 通知有每月上限（跟米亞共用推播額度）；企業場的 AI 可以用另一把金鑰（ANTHROPIC_API_KEY_BUSINESS）。測試的 test/loader.mjs 沒有接業發處那本，記者那邊的任何一條路碰到業發處的資料就會報錯，CI 的第三輪就是靠這個抓。兩邊共用的每一樣東西（推播額度、Sheets 額度、AI 警報、登入失敗的計數…）都要有一道擋，盤點表在 批次 119 的紀錄 第三節；新增共用的東西時照著補一列。
- 模型的輸出怎麼進到使用者手上，每一個出口都要過四道（批次 132–135）：① 繁體出口
toTraditionalTW()——模型寫的字走完整的字＋用語，名稱與原文（活動名稱、記者姓名、官網標題、聯絡人）用 { terms:false } 只轉字，不然會被用語層改壞；② 拒答：新增呼叫模型的地方要處理 stop_reason:"refusal"（HTTP 200，不是錯誤，lib/ai-refusal.js），不要把它當金鑰／額度問題通知管理員；③ 用量：記 logAiUsage()（test-batch117 會檢查，走 postAnthropic() 的也算）；④ 記者端的答案：數字、網址、英文名詞要過 checkAnswerGrounding()（預設影子模式，ANSWER_GROUNDING）。
- 紀錄要寫：改了什麼、為什麼、踩到什麼坑——寫在
docs/batches/，不是 commit message（見 CLAUDE.md 第 5 條）。
