工研院活動溝通 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（米亞那一端）

先讀這幾份

1. CLAUDE.md——朱朱交代過、每一次都適用的長期約定（只用台灣繁體中文、「絕對不能發生」的事擋在程式出口、米亞只有一種聲音、影片一定要有聲音軌、紀錄放哪裡）。
2. SETUP.md——部署、環境變數、Google 試算表怎麼建、Vercel 免費方案的 12 支 Function 上限（現在 api/ 用了 11 支）。
3. LINE-PLAN.md——長期規格：定位、資料模型、七個會害你重做的坑、LINE 的意圖、prompt 規則、不要做的事。
4. docs/batches/README.md——每一批改動的來龍去脈（為什麼這樣改、踩到什麼坑）。程式碼註解寫「批次 N」就到這裡找。
5. 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 條）。