Pocket Harmonica · 口袋訪談

正式站：https://harmonica.mashbean.net

一對一 AI 訪談，用來補訪審議裡缺席的聲音。主辦者設定主題、想理解什麼、幾個起始問題；參與者用連結進來，跟一位中立的訪談者對話幾輪（依回答追問、不評價、不說服）。逐字稿匯出成 id,interview,comment 的 tttc.csv，主辦者頁可一鍵交給 Pocket TTTC 建議題樹。整個系統是一個 Cloudflare Worker：一輪訪談一個 SQLite Durable Object，訪談者是 Workers AI（Gemma 4）。沒有帳號、沒有 API 金鑰。

設計概念來自 Harmonica（AGPL）；本專案為獨立重寫，MIT。

免費額度怎麼撐

訪談是神經元密集的：每一輪回覆都是一次模型呼叫。系統用「UTF-8 位元組 + 模板額外量」估輸入、強制 max_tokens: 384 估輸出，最壞情況每輪約 70 神經元，並在兩層帳本預留：

• 每輪訪談（session）最多 9,000；
• 全部署每日最多 9,000（DAILY_NEURON_CEILING，留 1,000 餘裕）。

額度用完時參與者會看到「今天的額度用完了，請明天再回來」，已說的話不會遺失、進度保留。建表單時會算出最壞情況：6 輪 × 20 人 ≈ 8,400，剛好一天；/api/health 回報今天還能回幾輪。開場白是模板，不花神經元；提示詞只帶最近幾則對話（6 KB 上限）。

怎麼用

1. 首頁建立：主題、想理解什麼（會說給參與者聽）、背景與不能漏的聲音（只給訪談者）、1–8 個起始問題、每人輪數、人數上限。建立前要勾「我會告知參與者…」。
2. 參與連結 /s/<id> 給參與者；主辦者連結 /h/<id>#admin=… 只顯示一次。
3. 主辦者頁看進度、匯出 tttc.csv 與 transcripts.json、「送到 Pocket TTTC 分析」、結束或刪除。

參與者每台裝置一段對話（瀏覽器產生 v4 UUID，伺服器只存雜湊），重開同一連結會接續；到達輪數上限時訪談者會收尾。

API

POST   /api/sessions                           {topic, goal, context?, critical?, questions:[…], language?, maxTurns?, maxParticipants?, askAlias?, confirmed:true}
                                               → 201 {sessionId, adminToken, urls:{participate, host, api}, budget}
GET    /api/sessions/:id                       公開設定與進度
POST   /api/sessions/:id/join                  {participantId (v4 uuid), alias?} → {conversation}
POST   /api/sessions/:id/messages              {participantId, text} → {reply, turn, done}；額度用完 503 {budget:true}
GET    /api/sessions/:id/host                  X-Session-Admin
POST   /api/sessions/:id/status                X-Session-Admin {status:"open"|"closed"}
POST   /api/sessions/:id/analyze               X-Session-Admin → 建 Pocket TTTC 報告 {reportUrl, manageUrl}
GET    /api/sessions/:id/export/tttc.csv       X-Session-Admin 或 ?token=
GET    /api/sessions/:id/export/transcripts.json
DELETE /api/sessions/:id                       X-Session-Admin
GET    /api/health                             {ok, aiMode, dailyNeuronsRemaining, repliesRemainingToday}

邊界

• 全站建立限制每小時 10、每日 50 輪；每輪最多 100 人、每人最多 10 輪回覆。
• 不存 IP、不存原始裝置代碼；主辦者權杖只存 SHA-256。
• 訪談者是模型，會誤解或問得不好；逐字稿公開前請人工檢查。
• TTTC_ORIGIN 決定「送分析」交給哪一個 Pocket TTTC。

部署與開發

npm install
npm test            # vitest（AI_MODE=fake，讀 wrangler.test.jsonc）
npm run check
npm run deploy               # workers.dev
npm run deploy:production    # 自訂網域放在 env.production.routes；Worker 名稱不可改

CI（.github/workflows/deploy.yml）需要 repository secrets CLOUDFLARE_API_TOKEN 與 CLOUDFLARE_ACCOUNT_ID。MIT 授權。