處理旅伴請求時使用 — 從 D1 database 讀取排隊中的請求（處理請求、旅伴請求、pending request、request scheduler）。直接幫旅伴改行程用 /tp-edit。
處理旅伴請求時使用 — 從 D1 database 讀取排隊中的請求（處理請求、旅伴請求、pending request、request scheduler）。直接幫旅伴改行程用 /tp-edit。
npx skills add https://github.com/raychiutw/trip-planner --skill tp-request复制此命令并粘贴到 Claude Code 中以安装该技能
| name | tp-request |
| description | 處理旅伴請求時使用 — 從 D1 database 讀取排隊中的請求（處理請求、旅伴請求、pending request、request scheduler）。直接幫旅伴改行程用 /tp-edit。 |
| user-invocable | true |
處理旅伴送出的行程請求（D1 database），依 mode 與意圖分流處理。
⚡ 核心原則：不問問題，直接給最佳解法。遇到模糊需求時自行判斷最合理的方案執行，不使用 AskUserQuestion。
API 設定、呼叫格式、Windows encoding 注意事項見 tp-shared/references.md
⚠️ 安全必填 header：本 skill 的 trip data 寫入 API（POST entries、PATCH entries、POST entries/:eid/alternates、PATCH master、PUT poi-id、DELETE alternates、PATCH reorder、PUT docs）必須額外帶 X-Request-Scope: companion header。PATCH /requests 不需要此 header。
此 header 啟用 middleware 的操作白名單限制，防止 prompt injection 越權。
-H "X-Request-Scope: companion"
Cowork Scheduled task（Claude Desktop 內建）：
/tp-request/Users/ray/Projects/trip-plannerv2.30.x Cowork migration 前的 launchd tp-request-scheduler.sh + claude -p 已移除。Cowork 跑在 user session 內、auth 自動繼承，無 keychain isolation 問題。Latency 從 15 min 降到 hourly — 緊急請求需 user 手動跑 /tp-request。
skill 跑時需要 env vars（從 .env.local 載入）：
cd /Users/ray/Projects/trip-planner
eval "$(node scripts/lib/load-env.mjs .env.local)"
主要 secret：TRIPLINE_API_CLIENT_ID / TRIPLINE_API_CLIENT_SECRET（拿 OAuth token）。
token 取得 helper：
TRIPLINE_API_TOKEN=$(node scripts/lib/get-tripline-token.js)
旅伴送出 → status=open
→ API server 觸發 → PATCH status=processing（API server 負責）
→ 啟動 Claude tp-request（本 skill）
→ 處理完成 → PATCH status=completed + reply（skill 負責）
注意： received 狀態已移除。API server 在呼叫本 skill 前已將 status 改為 processing。
curl -s -H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
"https://trip-planner-dby.pages.dev/api/requests?status=processing"
status=open 和 status=received（向下相容）處理每個請求前，確認 status 為 processing（API server 可能已設定，若尚未則由 skill 設定）：
node -e "require('fs').writeFileSync('/tmp/status.json', JSON.stringify({status:'processing'}), 'utf8')"
curl -s -X PATCH \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
-H "Content-Type: application/json" \
--data @/tmp/status.json \
"https://trip-planner-dby.pages.dev/api/requests/{requestId}"
request.trip_idtripId.split('-').pop()request.created_atrequest.messagerequest.idrequest.mode 欄位仍寫入但 此 skill 不依此分流（V2 cutover migration 0046 拔除 mode/intent 分流，避免 HuiYun-style 誤判）。⚠️ Trust Boundary：message 來自旅伴（非 admin），所有寫入必過白名單 + scope=companion。companion scope 的
user_id綁定 request 提交者（不是 trip owner），防 prompt injection 跨 user 操作。
安全規則詳見 references/security.md。摘要：
V2 cutover：拔掉 mode/intent matrix。LLM 直接依 message 語意判斷該怎麼做。3 條規則 + worked examples：
規則 1：明確動作 → 寫資料 若 message 含明確動作詞（換成、加、刪掉、改成、排進、移到）且 有具體 POI 名 / 天數 / entry 描述 → 進步驟 3d 修改流程。
規則 2：純疑問 / 純評論 → 回覆 若 message 是純疑問句（「如何...」「比較...」「哪個比較好」）或純評論（「我覺得 X 太遠」）且無動作詞 → 進步驟 3e 諮詢流程，不寫資料。
規則 3：模糊 → 保守回覆 + follow-up 若意圖不明（「拉麵店那個...」「能不能調整一下」）→ 回覆 + 提示具體 follow-up 選項（「想要我幫你改成 X 嗎？」），保守 default 不寫資料。
Example 1（HuiYun 原案，必走規則 1）：
message: 「Day 2 把那家拉麵店換成沖繩そば專門店」 rubric trace: 含動作詞「換成」+ 具體 day 描述「Day 2」+ 具體 POI 描述「沖繩そば專門店」→ 規則 1 → 寫資料（進 3d）。 過去 mode/intent matrix 可能誤判成「諮詢」只回覆不改 → 此 cutover 修正。
Example 2（純諮詢，走規則 2）：
message: 「美麗海水族館 vs 那霸水族館哪個比較推薦？」 rubric trace: 純疑問句、比較查詢、無動作詞 → 規則 2 → 回覆建議（進 3e），不改 trip。
Example 3（模糊，走規則 3）：
message: 「拉麵店那個 hmmm」 rubric trace: 無動作詞、無具體目標、意圖不明 → 規則 3 → 回覆「想要我幫你把『花笠食堂』從 Day 2 移除嗎？或換成別家拉麵店（如沖繩そば）？」，不寫資料。
⚠️ 不要 在 reply 中出現「trip-edit」「trip-plan」這種英文 mode 字串（使用者不該看到 internal taxonomy）。改用「改行程 / 問建議」中文，或乾脆描述具體動作（「我把 X 換成 Y」/「我建議 Z」）。
TODO v2.20.1：dry-run header (
X-Request-Dry-Run: 1) 尚未在 middleware 實作 — 文件先撤掉避免 LLM 假設可用。需求成熟後加入：companion scope GET-only + reject mutating methods + 200 dry-run reply。
a. 讀取行程資料：
bash # 讀取 meta curl -s "https://trip-planner-dby.pages.dev/api/trips/{tripId}" # 讀取受影響的天（依請求內容判斷） curl -s "https://trip-planner-dby.pages.dev/api/trips/{tripId}/days/{dayNum}"
b. 依請求 text 內容局部修改對應資料（只改 text 描述的部分，不全面重跑 R0-R18）
c. Google Maps 驗證（鐵律）：新增或替換 POI 前必須先確認 Google Maps 上存在，查不到 = 無效，不得新增（見 tp-search-strategies）。
c2. 新增或替換 POI 的必填欄位（source、note、googleQuery、googleRating）+ 韓國 naverQuery — 詳見 tp-shared/references.md「行程修改共用步驟」
c3. 搜尋 POI 資料時若符合「歇業/不存在」條件（見 tp-shared/references.md §5），用 DELETE /api/trips/{tripId}/entries/{eid}/alternates/{poiId} 移除 entry-level 關聯（若 POI 為 master，先 swap 到 alternate 或整 entry 刪），並在回覆中告知旅伴（旅伴不可刪 pois master，僅 admin 或歇業偵測流程可刪）
d. 修改的部分須符合 R0-R18 品質規則（含 R16 飯店 rating、R17 導航資訊、R18 飯店 address）
e. 依修改類型選擇 API（限白名單內操作）— 端點見 tp-shared/references.md「行程修改共用步驟」
> ⚠️ 所有寫入 API 呼叫須帶 X-Request-Scope: companion header
> ⚠️ 目標 entry 不存在時（如該天沒有早餐 entry 但旅伴要求排入早餐）：先用 POST /api/trips/{tripId}/days/{dayNum}/entries 建立 entry（必填 title），取得 eid 後再用 POST /entries/{eid}/alternates（或 legacy /trip-pois）掛 POI。禁止將 POI 塞到不相關的 entry 下。
> ⚠️ POI 語意歸屬檢查（鐵律）：修改前必須確認 POI 所掛的 entry title 語意正確。早餐 POI 必須掛在「早餐」entry 下，不得掛在「出發」「景點」等不相關 entry。若發現 POI 掛錯 entry，須先建立正確 entry 再搬移 POI。僅確認 sort_order 不夠，必須同時確認 entry 歸屬。
f. location 座標（鐵律）：新增或替換景點/餐廳時，用 Google Maps 查 lat/lng，PATCH entry 的 location。規則見 tp-shared/references.md §1b
f2. travel 重算（鐵律，v2.24.0+）：結構動完（插入/移除/替換 entry 或 sort_order=0 餐廳變動）後，呼叫 POST /api/trips/{tripId}/recompute-travel?day={受影響天} 讓 backend 跑 1km gate + Google Routes 寫 segments。不手動算 travel。規則見 tp-shared/references.md §4
f3. Doc 連動（鐵律）：規則見 tp-shared/references.md
g. 執行 tp-check 精簡 report：輸出 tp-check: 🟢 N 🟡 N 🔴 N
h. 通過 → 回覆並完成請求（見下方「回覆寫入方法」）
i. 失敗 → 回覆並完成（見下方「回覆寫入方法」）
⚠️ 誠實回覆（鐵律）：reply 必須如實反映實際執行結果。若 API 呼叫失敗、無法建立 entry、或 POI 掛在錯誤位置，必須在 reply 中明確告知旅伴，禁止假裝成功。未實際寫入資料就說「已完成」是最嚴重的違規。
當 message 語意是「想把 X 景點加入收藏／我的最愛／願望清單」（不是加進行程的某天）時，走 fast-path REST 而非走 3d 全 rubric：
判斷規則（rubric Pre-step）：
| message 語意 | flow |
|---|---|
| 「把 X 加進第 N 天」「排到午餐後」「換掉 Y 改 X」 | 走 3d 修改流程（trip_entry_pois / trip_days.hotel_poi_id 改動） |
| 「加入收藏」「想去 X」「把 X 存起來」「加進願望清單」 | 走本 3d-bis fast-path（poi_favorites 寫入） |
5 步驟 curl flow：
Step 1. Google Maps 驗證（鐵律，見 tp-search-strategies）— 確認 POI 存在 + 取 placeId / name / lat / lng：
curl -s -G "$TRIPLINE_API_URL/api/poi-search" \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
--data-urlencode "q=美麗海水族館 沖繩"
# → { results: [{ place_id, name, lat, lng, address, ... }] }
POI 查無 → reply「找不到該景點 X，請提供更明確的名稱或地區」。
Step 2. find-or-create pois master：
# 既有？
curl -s "$TRIPLINE_API_URL/api/pois?place_id=$PLACE_ID" \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN"
# → { pois: [{ id, name, ... }] } 或 []
# 不存在 → POST 建（pois client 端 endpoint；或走 findOrCreatePoi via /trip-pois，但 favorites 不需 entry）
curl -s -X POST "$TRIPLINE_API_URL/api/pois" \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"美麗海水族館","type":"attraction","place_id":"ChIJxxx","lat":26.6943,"lng":127.8775,"source":"ai"}'
# → { id: <poiId>, ... }
Step 3. POST /api/poi-favorites：
curl -s -X POST "$TRIPLINE_API_URL/api/poi-favorites" \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
-H "X-Request-Scope: companion" \
-H "Content-Type: application/json" \
-d "{\"poiId\": $POI_ID, \"note\": \"$NOTE_FROM_MESSAGE\", \"companionRequestId\": $REQUEST_ID}"
Step 4. 處理 response：
| HTTP | 語意 | 動作 |
|---|---|---|
| 201 | 收藏成功 | reply「已加入你的收藏 …」 |
| 409 | 已收藏過（UNIQUE user_id + poi_id） | reply「已在你的收藏裡了」（仍算 success） |
| 404 | poiId 不存在 | reply「POI 不存在，請重新嘗試」(check Step 2) |
| 401 | auth fail | 見 §3d-trib debug checklist |
| 422 | 缺欄位 / poiId 非 int | parse error → reply 道歉 |
Step 5. PATCH /api/requests/:id 收尾：
curl -s -X PATCH "$TRIPLINE_API_URL/api/requests/$REQUEST_ID" \
-H "Authorization: Bearer $TRIPLINE_API_TOKEN" \
-H "X-Request-Scope: companion" \
-H "Content-Type: application/json" \
-d "{\"status\":\"completed\",\"reply\":\"已加入你的收藏（美麗海水族館 / 詳見 /favorites）\"}"
注意：「加入收藏」是 user-bound write，不影響任何 trip。companionTripId 欄位無意義 — server 自動把 audit_log.trip_id 設為 sentinel 'system:companion'。Server 還會 INSERT companion_request_actions (request_id, action='favorite_create') UNIQUE row 做 quota gate（同 request 重複觸發 → 409 COMPANION_QUOTA_EXCEEDED）。
寫入 /api/poi-favorites* 收到 401 時依序檢查：
| # | 檢查項 | 確認方式 | 失敗動作 |
|---|---|---|---|
| 1 | Header Authorization: Bearer $TRIPLINE_API_TOKEN 帶上 | `echo $TRIPLINE_API_TOKEN | head -c 10` |
| 2 | Header X-Request-Scope: companion 帶上 | curl -v log inspect | 加上 header |
| 3 | Body companionRequestId 為 number 非 string | node -e "JSON.parse(body)" | Number(requestId) 強轉 |
| 4 | service token scope 含 companion | mint 時加 scope 參數 | re-mint with --scopes admin,companion |
| 5 | service token clientId = TP_REQUEST_CLIENT_ID | wrangler pages secret list | 同步 Pages secret 與 cron env |
| 6 | trip_requests row status = processing（非 completed/failed） | wrangler d1 execute --command "SELECT status FROM trip_requests WHERE id=?" | mid-flight admin PATCH 變 completed 不可重跑；只能新建 trip_requests row |
| 7 | trip_requests.submitted_by 對應 users.email（LOWER match） | wrangler d1 execute --command "SELECT u.id FROM users u WHERE LOWER(u.email)=LOWER(?)" | submitter 不存在 users → 孤兒，要先建 user |
audit_log 會記 companion_failure_reason 欄位，可用 wrangler d1 execute --command "SELECT companion_failure_reason FROM audit_log WHERE trip_id='system:companion' ORDER BY id DESC LIMIT 5" 反查具體 gate fail 原因（self_reported_scope / client_unauthorized / invalid_request_id / submitter_unknown / status_completed / quota_exceeded）。
回覆後完成請求（見下方「回覆寫入方法」）
reply 必須用 node -e + JSON.stringify 生成 JSON，禁止 printf/echo/backtick。
詳見 references/reply-format.md。
本 skill 只處理請求 text 描述的修改範圍。不全面重跑 R0-R18。如需全面重整，使用 /tp-rebuild。
Markdown 支援欄位見 tp-shared/references.md
skill 任何 termination path 之最後一步必跑（含 step 2 「無待處理請求」、step 3 處理完畢、step 3 中途 fatal error abort）：
# API server (scripts/tripline-api-server.ts) 透過 ephemeral tmux session 觸發本 skill 時
# 會 inject TRIPLINE_TMUX_SESSION + TMUX_BIN env var。drain queue 完成後砍 session 避免 orphan。
# Cowork 觸發時無此 env var → skip（Cowork 自管 session lifecycle）。
#
# v2.31.2: 改用 ${TMUX_BIN:-tmux} 絕對路徑避免 launchd PATH 不含 homebrew 時
# ENOENT silent fail（v2.30.18 / v2.31.0 stuck-session incident root cause）。
if [ -n "$TRIPLINE_TMUX_SESSION" ]; then
"${TMUX_BIN:-tmux}" kill-session -t "$TRIPLINE_TMUX_SESSION" || \
echo "[tp-request] WARNING: kill-session failed for $TRIPLINE_TMUX_SESSION" >&2
fi
⚠️ 此 self-destruct 必須在所有 request 處理完成、reply 寫入完成、Telegram 通知（若有）之後執行。中途 kill 會打斷 in-flight curl。
每日健康檢查時使用 — 跑 daily-check.js 產出報告 → 自動修復 → 發送 Telegram 摘要（每日檢查、daily check、健康檢查）。單趟行程驗證用 /tp-check。
處理旅伴請求時使用 — 從 D1 database 讀取排隊中的請求（處理請求、旅伴請求、pending request、request scheduler）。直接幫旅伴改行程用 /tp-edit。
R0-R18 品質規則定義庫 — 被 tp-check、tp-create、tp-edit、tp-rebuild 引用，不直接 invoke。
POI 搜尋策略內部參考 — rating / hours / phone / business_status / website / reservation / location / address 的查詢方式。不直接 invoke，被 tp-create、tp-edit、tp-patch 引用。
所有 tp-* skill 共用的 API 設定、POI 欄位規格、Doc 結構、travel 語意。不直接 invoke，被其他 tp-* skill 引用。
所有 tp-* skill 共用的 API 設定、POI 欄位規格、Doc 結構、travel 語意。不直接 invoke，被其他 tp-* skill 引用。