← 旅行摺頁 Trip Notes · 純文字版 spec.md · 範例 JSON(多城市) · 範例 JSON(巴士+租車) · 範例 JSON(單一據點) · SKILL.md

旅行摺頁 Trip Notes 資料格式說明(trip-guide/1)

這份文件給 AI 讀。照這裡的格式產出一份 JSON,貼到「旅行摺頁 Trip Notes」網站就會變成一頁手機好讀的旅行網站:每日時間表、地圖、待訂清單、景點、餐廳、住宿、交通、記帳,還有讓使用者自己上傳機票、車票、門票的「票夾」。

分工:版面、地圖繪製、篩選、記帳功能都在網站裡,已經寫好。你(AI)只負責研究和填資料。不要輸出 HTML、CSS 或程式。


1. 輸出規則(最重要)

  1. 只輸出一個 JSON 物件。前後不要加說明文字。如果介面一定會把它包在程式碼區塊裡,可以,但區塊內只能有 JSON。
  2. 必須是合法 JSON:雙引號、沒有註解、沒有結尾逗號、沒有 undefined。
  3. "schema": "trip-guide/1" 必填。
  4. 文字欄位不能放 HTML 標籤。要強調或放連結,只能用第 3 節的四種寫法。
  5. 沒有資料的選填欄位就省略,不要填空字串、"N/A" 或編造內容。
  6. 內文用繁體中文;地名、站名、店名、菜名保留當地語言原文。
  7. 太長一次輸出不完時,先講明會分段,再依頂層欄位分段輸出,最後要能直接拼成一個物件。

2. 內容規則(決定這頁能不能信)

  1. 價格、時刻、營業時間只寫查得到的。 沒查到就寫 {{待確認}},不要猜。
  2. 用推定值就要標出來。 還沒訂的航班、飯店、用去年資料代替的時段,在文字後面加 {{假設}} 或 {{預估}},並在 overview.assumptions 列出全部假設。
  3. 每個事實要有來源。 查過的官方頁面放進 sources.list,並在 meta.checkedOn 寫查核日期。
  4. 檢查休館日。 每個排進行程的點,都要對照「去的那天是星期幾」確認有開,寫進 toolkit.hours。固定公休日、「每月第 2 個週一」這類規則、國定假日都要算。
  5. 待訂清單依後果分級,不是依時間:
  6. hi 高風險:沒訂到,這趟就去不成或要大改
  7. mid 建議先訂:晚訂會變貴或變累,但有替代方案
  8. lo 可晚點:出發前或當天處理就好
  9. chk 待核對:官方還沒公布,或需要使用者確認
  10. 每天要寫「為什麼這樣排」(days[].why),讓使用者知道哪些可以動、哪些不能動。
  11. 尊重使用者的步調。 使用者說不要太累,就每天只排一件主要的事,其餘放「順路選配」。
  12. 照片只能用允許再使用的(例如 Wikimedia Commons),並在 photos 寫作者與授權。找不到就不要放,卡片會顯示「沒有照片」。不要用店家官網或新聞網站的圖。
  13. 經緯度要是那個地點真實的座標(小數 4 位以上)。不確定就不要放進地圖。
  14. 私人資料看用途。 預設這份 JSON 只給使用者自己和旅伴看(網站只把它存在使用者的瀏覽器):使用者提供的航班、訂位代號、飯店、姓名、座位、金額照實放進去(例如票夾欄位的 note、住宿的 note、flights 的 text);使用者沒提供的不要編,也不要上網找。指令寫「會公開分享」時,才改成不放訂位代號、訂單編號、座位號碼、姓名、個人 Email、付款金額或誰付錢,已訂的只寫「已訂」和日期時間。護照號碼、信用卡號、密碼任何情況都不要放。真正的票和確認信由使用者自己上傳到票夾(第 14 節)。

3. 文字欄位可以用的寫法

寫法 顯示成 例子
**文字** 粗體 **乘車券 ¥1,000**
[文字](網址) 連結 [官網](https://example.com)
[文字](#錨點) 頁內跳轉 [山本屋本店](#f-yamamotoya)
{{假設}} {{預估}} {{待確認}} 小標籤 CX530 11:30 起飛 {{假設}}
{{pill:hi:文字}} 風險色標籤(hi/mid/lo/chk/done) {{pill:hi:要事先訂}}

標了「可用寫法」以外的欄位(id、key、日期、價格等)請填純文字。

4. 錨點(to 欄位和頁內連結)

很多欄位有 to,表示點了要跳到哪裡。值是下列之一,不加 #:

目標 寫法 例子
某一天 days[].id d2
景點卡 s- + sights[].id s-castle
餐廳卡 f- + food[].id f-maruya
住宿卡 h- + hotels[].id h-base
交通段 transport.guide.legs[].id leg1
工具箱分頁 tab: + 分頁 key tab:trans、tab:f1
區塊 route days sights food stay transport toolkit notes book book

內建分頁 key:money 記帳、wallet 票夾、hol 營業時間、trans 交通指南、info 實用資訊、pack 打包清單、lang 當地語小抄。

規則:days[].id 必須是 d1、d2…依序編號。其他 id 用小寫英數,同一類不重複。指到不存在的錨點,顯示器會提醒。


5. 頂層結構

{
  "schema": "trip-guide/1",
  "meta": {…},              必填
  "flights": [...],
  "overview": {…},
  "daysIntro": "…",
  "days": [...],            必填,至少 1 天
  "sightsIntro": "…", "sightTicketsSummary": [...], "sightTicketsNote": "…", "sightTickets": [...], "sights": [...],
  "foodIntro": "…", "foodPlanSummary": [...], "foodPlan": [...], "foodCats": [...], "food": [...],
  "stayIntro": "…", "hotels": [...], "stayNote": {…},
  "transport": {…},
  "tickets": [...],         票夾欄位,見第 14 節
  "toolkit": {…},
  "bookingsIntro": "…", "bookings": [...],   bookings 必填(沒有就給空陣列)
  "bookingSchedule": [...],
  "notes": [...],
  "sources": {…},
  "photoNote": "…", "photos": {…}
}

下面每節的表格裡,粗體欄位必填,「✎」表示可用第 3 節的寫法。

6. meta

欄位 說明
title 頁面標題,例如 名古屋・鈴鹿 F1 2027
kicker 標題上方的小字,建議用當地語言
subtitle ✎ 一行摘要:日期、人數、幾晚、路線
timezone 目的地 IANA 時區,例如 Asia/Tokyo。用來判斷「今天」
departAt 出發時間,ISO 8601 含時區,例如 2027-04-08T11:30:00+08:00。用來算倒數
checkedOn 資料查核日 YYYY-MM-DD
heroImg / heroAlt 首圖(photos 的 key)與替代文字
cities [{key, name, nameEn, icon}]。key 是 2–4 個小寫字母;icon 選一個:castle flag mountain lake city temple beach pin。只有一個城市也要列
currency {code, symbol, name, decimals, fallbackPerTwd, quoteUnit}。fallbackPerTwd 是 1 單位當地幣等於多少台幣(查當天匯率);quoteUnit 是匯率顯示單位(日圓用 100,歐元用 1)
payers 記帳的兩個付款人名字,預設 ["我", "旅伴"](使用者可在網頁上改)
sectionLabels 各區塊標題旁的當地語小字,key:overview days sights food stay transport toolkit notes
milestone 首頁第二個倒數,例如開賣日:{at, before, after, afterValue}
sample 公開範例設 true:日期是示範的,首圖不顯示倒數
theme {accent, accentDark} 強調色(十六進位色碼),可省略;accentDark 是深色模式用的較亮版本,沒填就用預設金色

7. flights 與 overview

flights:[{label, text, flag}],顯示在首圖上。flag 可填 假設。

overview:

欄位 說明
intro ✎ 一兩句說明這趟的節奏
route [{md, name, note}] 路線條,每站一筆,建議 4–8 筆
cards [{city, to, img, dates, nights, name, nameEn, theme, points[], transport ✎, stay ✎}],每個停留段一張卡,points 放 4 個重點,to 指到那段的第一天
assumptionsTitle / assumptions ✎ 這份行程用了哪些假設,每項一句

8. days(每日行程)

欄位 說明
id d1、d2…
date YYYY-MM-DD
md 顯示用日期 4/8
weekday / weekdayEn 週四/THU
label 日期按鈕上的短標,6 個字內
city meta.cities 的 key。換城市的那天可以寫兩個,用空格分開,例如 "szg vie"
title 當天標題
cityLabel 例如 鈴鹿 Suzuka
banner 橫幅照片(photos 的 key),建議寬圖
sun {rise, set, dark, note} 當地日出、日落、天全黑的時間與一句提醒
stay ✎ / eat ✎ / remind ✎ 住哪裡、吃什麼、當天提醒
extras [{to, label}] 順路選配
timeline 見下
why {title, points: [{lead, text ✎}], details: [{summary, items[]}]}。points 寫為什麼這樣排;details 是可展開的清單(例如「今天要帶」「必看」)
maps 見下,可以 0 到多張

timeline 是陣列,兩種項目交替出現:

停留點 {"type": "stop", "time", "title" ✎, "to", "stay", "note" ✎, "ticketKey"} - time:07:45 或 11:30–12:30 - stay:預留多久,例如 約 1.5 小時 - to:點了跳到哪張卡(見第 4 節),沒有就省略 - ticketKey:這一步要出示的票(tickets[].key),會出現「機票/門票」按鈕。移動項目也可以加

移動 {"type": "move", "modes": [{"mode", "label"}], "time", "summary" ✎, "detail" ✎, "ticketKey"} - mode:walk metro train rail bus tram ferry cable plane car;label 是顯示的字(例如 近鐵特急) - time:約 40 分 - summary:一行,例如 近鐵名古屋 08:10 → 白子 08:49 - detail:展開後的說明。寫清楚搭哪條線、往哪個方向、多少錢、怎麼買、月台或乘車處在哪。省略就不能展開

maps:[{title, stops, segs, water, lines, geoLabels, scaleM, pad, height, totalNote}] - stops:[{name, kind, to, lat, lon, label, query}],照走訪順序。kind:sight food hotel stn。label 是文字放在點的哪一邊:t b l r。query 是 Google 地圖搜尋字串(用當地語言店名最準) - segs:[{mode, text}],數量一定是 stops 少 1。步行段把 text 設成 null,網站會自己算距離和分鐘;搭車的段落自己寫,例如 "約 53 km・40 分" - water:選填,湖或海的多邊形 [[[lat, lon], …]],簡化即可 - lines:選填,河流或環城道路 [{kind: "river" 或 "ring", path: [[lat, lon], …]}] - scaleM:比例尺長度(公尺)。市區步行用 200–500,跨城市用 10000 - pad:[左, 右, 上, 下] 留白,文字被切到時加大那一邊;預設 [50, 60, 34, 40] - 一張圖放 3–6 個點。兩個點距離小於 100 公尺就合併成一個

9. sights(景點)

sights[]:

欄位 說明
id / city / name
date 哪天去,例如 4/12 上午、4/12(選配)
nameLocal 當地語言名稱
label 卡片標記 {text, style}。style: "new" 是金色「新增推薦」(會出現「只看新增推薦」篩選);"old" 是灰色(例如「舊清單、未排入」)
ratings 評分 [{source, score, outOf, count, level}]。有星等填 score(例如 "4.5")與 count(例如 "1.2 萬則");沒有公開數字的來源填 level:熱門 常見 少見。只寫查得到的
img / imgNote 照片 key;不是實景時在 imgNote 寫 示意:…
badge 照片左上角標籤:要買票 ¥500、免費
intro ✎ 兩三句:是什麼、為什麼排進來
pros / cons 各 2 項
ticket {tag, price, note ✎, link: {url, text}, free}。tag:要買票、選配 或 免費;免費的設 free: true
facts 其他短欄位 [[標題, 內容 ✎]]
tip ✎ 一句提醒
ticketKey 已買票時對應的票夾欄位
booking {status, text}。status:todo 待訂、free 免訂、misc 其他
links [{url, text}],通常是地圖和官網
more {history, why, mustSee[], tip ✎}「看更多」的內容

sightTickets[](景點區最上方的門票清單):{date, when, kind, title ✎, price, note ✎, status: {risk, text}, links, ticketKey}。已訂的 status.risk 用 done。 sightTicketsSummary:字串與 {risk, text} 標籤混排的陣列。

10. food(餐廳)

food[]:

欄位 說明
id / city / name
cats 類別 key 陣列,對應 foodCats
date 哪一餐,例如 4/8 晚餐、隨時
img / imgNote 小店通常找不到可用照片,可用招牌菜的代表照並在 imgNote 寫 示意:…
badge 預設 餐廳
intro ✎
dish ✎ 推薦點什麼
price ✎ / priceNote ✎ 每人價位與說明。沒查到寫 {{待確認}}
difficulty ✎ 訂位難度
nameLocal / label / ratings / facts / ticketKey 同景點
pros / cons
tip ✎ 分店、公休日、點餐提醒
email 訂位信箱,選填
booking / links 同景點

foodCats:[{key, name}]。foodPlan[]:每天吃哪裡,欄位同 sightTickets。foodNote ✎:餐廳區的說明小字(例如評分怎麼來的)。

11. hotels(住宿)

hotels[]:{id, name, img, cityLabel, date, status: {risk, text}, address ✎, checkInOut ✎, note ✎, links, ticketKey}。 status.risk:已訂用 done,未訂用 hi,候選用 lo。 還沒訂時:第一筆放「條件」(例如 id: "base",寫清楚要住哪一帶、為什麼),後面列 2–3 間查證過存在的候選。 stayNote:{title, items ✎[]},例如為什麼住這一區。

12. transport(交通)

欄位 說明
intro ✎ / summary
rows 照時間排的機票、車票清單,欄位同 sightTickets(含 ticketKey)
cheatSheet 最難的一段的小抄:{id, title, alert ✎, columns: [{title, steps ✎[], note ✎}], blocks, footer ✎}。blocks 同第 13 節
guide 見下,顯示在工具箱的「交通指南」分頁

guide:

欄位 說明
optionsTitle / options 交通方式比較:[{name, status, sub ✎, time ✎, cost ✎, pros[], cons[], pick}]。主力那一項 pick: true。要列出不推薦的選項和原因
ticketTypesTitle / ticketTypes / ticketTypesNote ✎ {head[], rows[][]} 票種說明表
appsTitle / apps [{name, status, sub, desc ✎, links, placesTitle, places: [{url, text}]}] 要用的 App 與網站;places 是預先存好的地點連結
glossaryTitle / glossary / glossaryNote ✎ [[名稱, 說明]] 當地交通名詞
cityTicketsTitle / cityTickets / cityTicketsNote ✎ [{city, rows: [{title, status, when, body ✎, price, links}]}]
costsTitle / costs {rows: [[段, 方式, 每人]], totalLabel, total, note ✎}
routeMap 全程示意圖,見下
legsTitle / legsNote ✎ / legs [{id, n, cities[], date, title, status, mode, distance, facts: [[標題, 內容 ✎]], links, ticketKey}] 每一段怎麼走
extraBlocks 放在最後的補充積木(例如渡輪時刻表),格式同第 13 節

routeMap:{height, latRange: [南, 北], centerLon, lonFactor, scaleKm, points, lines, badges, water, land, waterLabels, legend, note} - 路線分在兩個相隔很遠的地區(例如中部搭巴士、飛到半島再開車)時,改用 panels:{panels: [{title, height, latRange, centerLon, lonFactor, scaleKm, points, lines, badges, land, water, background}], legend, note}。每個 panel 是一張小地圖,欄位同上;legend、note 放外層共用。跨 panel 的那段(例如國內線)在 note 說明 - background: "sea":有 land 時,背景畫成海(沿海地區用) - points:[{key, name, nameEn, lat, lon, small, label}]。small: true 是小灰點。label:tl tr bl br l r t b - lines:[{style, via: [point key…], badge}] 或 [{style, path: [[lat, lon], …]}](要畫彎曲路線時用 path)。style:main 實線、main-thin 細實線、faint 淡線、dotted 點線、dotted-grey 灰點線、dashed 虛線、drive 灰色實線(開車)。badge 對應 legs[].n - badges:選填,自己放段號 [{text, lat, lon}],例如 "1・5" - water:海或湖的多邊形;land:陸地或國界的多邊形(內陸國用這個,背景就不會整片當陸地)。座標都是 [lat, lon] - lonFactor:選填,東西向的縮放,預設是中間緯度的 cos 值 - latRange 要把所有點包進去,上下各留一點空間

13. toolkit(工具箱)

欄位 說明
intro ✎
customTabs 這趟特有的分頁(賽事、演唱會、滑雪…):[{key, title, lead ✎, blocks}]
hoursLead ✎ / hours [{day, rows: [{key, level, name, to, img, pill, when ✎, hours, note ✎, link, optional}]}]。level:ok 沒影響、warn 要注意、bad 會撲空;選配的點加 optional: true
walletLead ✎ 票夾分頁的說明,省略就用預設文字
info [{title, blocks}]。至少要有:緊急電話、台灣駐當地代表處(查領事事務局)、天氣穿著、付款與小費、插座電壓、時差、入境
packing [{group, items: [{key, text}]}],key 全部不重複
phrasesTitle / phrasesLead / phrases [{zh, local, reading, note}] 常用當地語 12–16 句

blocks 是內容積木的陣列,每個積木一種型別:

type 欄位
heading text;small: true 是小標
steps items ✎[](有編號的步驟)
p text ✎
note text ✎(灰色小字)
list items ✎[]
kv rows: [[標題, 值]](電話號碼這類)
table head[], rows[][] ✎, stack(手機上改成一列一卡,欄位多時設 true)。儲存格寫 **主標**|副標 會分成兩行
cards items: [{title, text ✎, list ✎[], blocks}]

14. tickets(票夾)

工具箱有一個「票夾」分頁。使用者在網頁上把機票、車票、門票、訂房與訂位確認信(PDF 或截圖)上傳到這裡,旅途中點頁面上的按鈕就能打開。檔案只存在使用者自己的瀏覽器,不會上傳到網站。 你只負責建立「欄位」,告訴使用者這趟有哪些票要準備:

tickets[]:{key, kind, title, date, note ✎, to} - key:不重複的小寫英數,例如 eva、t1220、h-hotel。之後更新資料時不要改已有的 key,不然使用者已上傳的檔案會對不上 - kind:flight 機票、train 車票、bus 巴士、ferry 船票、entry 門票、hotel 訂房、food 訂位、pass 票卡(城市卡、周遊券)、other - title:例如 長榮 BR65/BR66 電子機票、Wien → Innsbruck(IC 546+RJX 162) - date:顯示用,例如 12/20 08:57 - note:一句提醒,例如「車票記名,查票時連護照一起出示」 - to:選填,相關的卡或交通段(第 4 節)

在相關的地方加 "ticketKey": "<key>",就會出現打開那張票的按鈕:days[].timeline[]、transport.rows[]、transport.guide.legs[]、sightTickets[]、foodPlan[]、sights[]、food[]、hotels[]。同一張票可以掛在好幾個地方(例如來回機票)。

建議為這些建立欄位:去回程機票、每段要事先買的火車/巴士票、要預約時段的門票、每間飯店的訂房確認、有訂位的餐廳、城市卡或交通周遊券。當天現場買的不用。使用者有提供訂位代號、座位且不公開分享時,可以寫在該欄位的 note;票和確認信的檔案由使用者自己上傳。

15. bookings、bookingSchedule、notes

bookings[]:{key, risk, when, tag, title ✎, why ✎, next ✎, links} - key:不重複的小寫英數。使用者勾選的狀態用它記,之後更新資料時不要改已有的 key - why:沒訂會發生什麼事 - next:下一步具體要做什麼,包含在哪裡訂、什麼時候開賣

bookingSchedule:[[什麼時候 ✎, 訂什麼 ✎, 為什麼是這個時間 ✎]],依時間排。跨時區的開賣時間要寫清楚是哪裡的時間。

notes:[{title, items: [[粗體開頭, 內容 ✎]]}]。建議三個:行程原則、容易漏掉的事、資料可信度(哪些是官方確認、哪些用舊資料代替、哪些是推估、哪些沒查到)。

16. sources 與 photos

sources:{text ✎, list: [{title, url}]}。list 放實際查過的頁面。

photos:以 key 為名的物件,其他地方用 key 引用。

"photos": {
  "castle": {
    "file": "https://upload.wikimedia.org/…/660px-Nagoya_Castle.jpg",
    "title": "Nagoya Castle Tower in Spring.jpg",
    "author": "Miya.m",
    "license": "CC BY-SA 3.0",
    "source": "https://commons.wikimedia.org/wiki/File:Nagoya_Castle_Tower_in_Spring.jpg"
  }
}

file 可以是完整圖片網址,或網站上的相對路徑。建議寬 660 像素以上、橫式。


17. 交出去之前自己檢查

  1. 是合法 JSON,只有一個物件,schema 正確。
  2. 每個 to 和 [文字](#…) 都指到存在的 id。
  3. days[].id 是連號的 d1…dn,date 連續且星期正確。
  4. 每張地圖的 segs 數量等於 stops 減 1,座標是真的。
  5. 所有還沒訂、用舊資料或推估的地方都標了 {{假設}}、{{預估}},沒查到的標了 {{待確認}},而且 overview.assumptions 和「資料可信度」有交代。
  6. 排進行程的每個點,在去的那天有開(星期、公休規則、假日)。
  7. bookings 的 hi 項目真的是「沒訂到就去不成」,並寫了開賣時間和在哪裡訂。
  8. 文字裡沒有 HTML 標籤,沒有編造的價格、電話或網址。
  9. sources.list 有內容,meta.checkedOn 有日期。
  10. 私人資料照第 2 節第 10 條:給自己用時,使用者提供的訂位資料都有放進去;公開分享時沒有訂位代號、訂單編號、座位、姓名、付款紀錄。要出示的票都有 tickets 欄位,而且每個 ticketKey 都對得到。