Reality Search Taiwan · Search-first MVP · Level 2 MVP 完成版

搜尋此刻真實狀態

輸入自然語言問題，直接取得結論、信心、依據與建議。現階段最穩定的 demo 是中央氣象署即時天氣 / 雨量 / 地震資料。

頁面本身公開，但不嵌入 server-side API key。瀏覽器會用你貼上的 key 呼叫 POST /v1/reality/check。

結論

等待查詢。建議先試：「阿里山現在有下雨嗎？」

信心：—　狀態：waiting_for_query　地點：—　意圖：—

判斷依據

  • 送出查詢後顯示。

建議

目前沒有查詢結果。

原始 API 回應

Level 2 MVP 已完成：首頁提供 15 個固定 demo 問題、首頁一鍵分享、GET /result?query=... 可分享結果頁、非 allowlist 友善提示與 GET /verify 驗證頁；公開頁面不嵌入 server-side API key。

Level 3 Beta：進行中；Sprint 1：Beta Verification Foundation 已建立 GET /beta 狀態頁、source health / freshness / confidence factors contract、Persistence / Audit Contract 與 scripts/verify_level3_beta.py live verification script。

開啟純搜尋頁 /search · Level 2 驗證頁 · Level 3 Beta 狀態頁 · Swagger UI · ReDoc

Reality Intelligence API

台灣現實世界搜尋引擎 Taiwan World Model 的機器介面。這個 staging API 讓 TrueSight / Codex / internal tools 查詢目前可介接的現實資料能力，並測試 Reality Check 合約。

Base URL 
https://taiwanworldmodel.thesense.biz

所有受保護 API 需使用 header：X-API-Key。請不要把 API key 寫死在程式碼或公開 repo。

Reality Search：用自己的 API key 試查「台灣剛剛有地震嗎？」與「阿里山現在有下雨嗎？」。Answer card 會把 current_state=no_rain_detected 等 raw state 轉成人類決策語言，例如「目前未偵測到明顯降雨」、「近10分鐘無雨」與高/中/低信心標籤，避免使用者直接解讀 raw JSON。

目前狀態

Reality Search MVP Location fixes

Earthquake scope parser：地震查詢先使用災害範圍解析，不用一般 POI geocoder 猜地點。「台灣剛剛有地震嗎？」會被視為 national_scope，不會解析成台灣中油；「花蓮剛剛地震多大？」會被視為 county_scope / 花蓮縣，再交給 CWA 地震報告查詢。

Demo 地點擴充：「合歡山現在天氣好嗎？」現在會解析成 weather_suitability + hehuanshan，使用合歡山座標選最近中央氣象署觀測/雨量資料，不再回 intent=unknown。

Level 2 MVP 完成版：首頁免 API key demo mode 已擴充為 15 個固定 demo 問題，首頁提供一鍵分享連結；GET /result?query=... 提供可分享結果頁，公開頁面只呼叫 allowlisted POST /v1/reality/demo-check，不嵌入 server-side API key；非 allowlist query 顯示 demo_query_not_allowed；GET /verify 提供固定驗證頁，列出 Level 2 完成 checklist。

Level 3 Sprint 2：完成 — Sprint 2：Runtime Trust Foundation：Weather / Rain Reality answer 已加入 source_health_status、freshness_seconds、staleness、reliability_score 與 confidence_factors；stale / degraded source 會降低 confidence，且 stability 影響 confidence / stability affects confidence。Persistence contract 目前為 audit log JSONL persistence、usage event JSONL persistence、source health history JSONL persistence 的 Beta contract marker。

Level 3 Beta：完成：TrueSight E2E dry-run integration：完成；Weather / Rain beta-ready、Earthquake / Disaster beta-ready、Forecast Reality beta-ready；audit log JSONL persistence：完成、usage event JSONL persistence：完成、source health history JSONL persistence：完成；final Level 3 live verification：PASSED。外部 TrueSight repo merge 與 production HA 屬下一階段，不阻擋本 Beta gate。

Endpoints

Endpoint用途目前狀態
GET /healthz服務健康檢查Public
GET /verifyLevel 2 MVP verification page：列出 15 個 demo queries、首頁一鍵分享、可分享結果頁、非 allowlist 友善提示與 secret leak check checklist；不嵌入 server-side API keyPublic
GET /camera-testCamera L3 Remote Test page：公開瀏覽器測試頁，讓 operator 貼上自己的 X-API-Key 後呼叫 /v1/reality/cameras/status-table?format=json&limit=500 與 /v1/reality/cameras/{camera_id}/live-query；頁面不嵌入 server-side key、不顯示影像 locator 或原圖Public page；API calls 仍需 API key
GET /betaLevel 3 Beta：進行中 status page；Sprint 1：Beta Verification Foundation，列出 Level 3 Done checklist、source health / freshness / confidence factors contract、Persistence / Audit Contract 與 scripts/verify_level3_beta.py live verification scriptPublic
GET /v1/reality/sources查詢可介接資料源能力目錄，可用 ?intent=... 過濾；回 metadata-only source_catalog_health public source catalog health summary，含 configured_durable、loaded_from_durable、redacted catalog_sha256、paths_hidden=true 與 restart_reload_check=source_catalog_restart_reload_check_v0（列出 restart 後只比較 checksum 的 public/admin health endpoints，requires_path_exposure=false），方便 restart 後驗證 durable catalogAPI key required，回 status=catalog_only
GET /v1/reality/auth/whoami驗證目前 API key 對應的 client identity、tier、endpoint permissions；不回傳 key valueAPI key required
GET /v1/reality/billing/current回傳目前 client 本月 usage metering / shadow billing summary；用於未來評估合理費用，不是正式 invoiceAPI key required，回 shadow_only / internal_usage_only
GET /v1/reality/production-readinessProduction Readiness Matrix V0：以 L0–L8 分級列出 Reality/API 能力目前成熟度、已完成項、缺口與下一個 milestoneAPI key required，回 production_readiness_matrix_v0
GET /v1/reality/source-healthSource Runtime Health V0：read-only 檢查 CWA / camera runtime 是否已設定與可進入下一階段；不執行 upstream fetch、不顯示 credentialAPI key required，回 source_runtime_health_v0
POST /v1/reality/source-health/probeSource Health Recorder / Probe V0：寫入 metadata-only source health observations；不呼叫上游、不顯示 credentialAPI key required，回 source_health_probe_v0，write_scope=source_health_observations_only
POST /v1/reality/source-health/probe/live-cwaCWA Live Fetch Health Probe V0：受控 live upstream probe，呼叫 CWA weather/rainfall datasets 並記錄 latency / staleness / success 或 failureAPI key required，回 cwa_live_fetch_health_probe_v0
GET /v1/reality/source-health/alertsCWA Monitoring / Alerting V0：read-only metadata-only alert evaluator，不呼叫 CWA、不寄送外部通知、不顯示 secretsAPI key required，回 cwa_monitoring_alerts_v0
GET /v1/reality/source-health/notification-channel-statusExternal Notification Channel Staging Config Contract V0：read-only metadata contract，只回 channel configured booleans；不顯示 channel address、provider token 或 credential valueAPI key required，回 cwa_notification_channel_status_v0 / notification_channel_status_ready
GET /v1/reality/source-health/escalation-policyEscalation Ownership Contract V0：read-only metadata contract，定義 owner approval、severity escalation 與 quiet-hours policy 缺口；不顯示個人聯絡值、不啟用 real sendAPI key required，回 cwa_escalation_policy_contract_v0 / escalation_policy_contract_ready
GET /v1/reality/source-health/real-send-approvalStaging Real-send Approval Contract V0：read-only metadata contract，定義 dry-run 進到 one-time staging real-send 的必要 gates；real_send_enabled=false、不寄送通知、不允許 production enablementAPI key required，回 cwa_real_send_approval_contract_v0 / real_send_approval_contract_ready
GET /v1/reality/source-health/notification-deliveryProduction Monitoring Notification Delivery Contract V0：read-only metadata contract，定義 channel readiness、severity mapping、retry/dedupe policy；不寄送通知、不顯示 channel address/provider secretAPI key required，回 cwa_notification_delivery_contract_v0
POST /v1/reality/source-health/notification-drillStaging Notification Drill V0：dry-run only，驗證 alert payload / severity / dedupe key / escalation placeholder；不寄送 Telegram/email/webhookAPI key required，必須 dry_run=true，回 cwa_notification_drill_v0 / dry_run_available
GET /v1/reality/weather/cross-validationForecast / Radar / Satellite Cross-validation V0：read-only metadata contract，定義 forecast/radar/satellite/observation 證據角色；不下載雷達/衛星圖API key required，回 cwa_forecast_radar_satellite_cross_validation_v0
GET /v1/reality/weather/radar-metadataRadar Runtime Metadata V0：read-only metadata contract，定義 CWA radar evidence role、freshness bands、ground-truth limitation；不下載雷達圖、不做 image analysisAPI key required，回 cwa_radar_runtime_metadata_v0
GET /v1/reality/weather/satellite-metadataSatellite Runtime Metadata V0：read-only metadata contract，定義 CWA satellite evidence role、freshness bands、regional-context limitation；不下載衛星圖、不做 image analysisAPI key required，回 cwa_satellite_runtime_metadata_v0
GET /v1/reality/weather/disagreement-scoringDisagreement Scoring Contract V0：read-only metadata contract，定義 observation/forecast/radar/satellite 分歧評分維度、confidence modifiers 與官方觀測優先規則；不計算 live scoreAPI key required，回 cwa_disagreement_scoring_contract_v0
GET /v1/reality/weather/production-thresholdsCWA Weather Production Thresholds V0：freshness/staleness/confidence/SLO metadata contractAPI key required，回 cwa_weather_production_thresholds_v0
GET /v1/reality/cwa-runbookCWA Operator Runbook Contract V0：read-only metadata contract，定義 key rotation、upstream outage、stale data degraded mode、rollback、probe pause 與 emergency wording；不執行危險操作；production gap runtime_status=cwa_runbook_contract_readyAPI key required，回 cwa_operator_runbook_contract_v0
GET /v1/reality/cwa-production-gapCWA Weather Reality Production Gap Checklist V0：明確列出 CWA Weather Reality 從 L6 → L7 production ready 的 pass / partial / blockerAPI key required，回 cwa_production_gap_v0
GET /v1/reality/cameras查詢攝影機白名單/候選 registry，可用 ?location_id=... 過濾；不公開原始 CCTV URLAPI key required，回 status=camera_registry_only
GET /v1/reality/cameras/searchNational Camera Coverage MVP：依 query、county、intent 搜尋全台縣市 coverage camera source candidates；schema=national_camera_coverage_v0，全台縣市 coverage 先回 registry/公開來源頁候選，不表示每筆已可 runtime fetchAPI key required，回 camera_sources_found / no_camera_source_found
GET /v1/reality/cameras/nearbyNational Camera Coverage MVP：依 lat/lng/radius_km 查附近攝影機候選；回 distance_km，仍不公開技術取流網址API key required，回 nearby_camera_sources_found / no_nearby_camera_source_found
GET /v1/reality/cameras/runtime-fetch-expansionCamera Runtime Fetch Expansion：依 query/county/intent 批次回報全台 camera candidates 的 runtime fetch readiness；未帶 filter 時以 upgrade_mode=all_registry_sources_when_no_filter 處理整個 registry；schema=camera_runtime_fetch_expansion_v0，含 L1_public_source_page_only、L2_snapshot_metadata_available、L3_visual_evidence_available、blockers 與 completion_summary；completion 不等於全部升 L3，而是每支都有最高安全等級與下一步；預設 probe=false/visual_probe=false，明確 probe=true 才對白名單/已設定來源做 metadata probe，並以 bounded parallel metadata probes（目前 service default max 16 workers）加速大量 registry 檢查且維持輸出順序；明確 visual_probe=true 才做 AI visual evidence probe；metadata-only snapshot 仍算 L2，不算 L3 AI visual evidence；blocked_or_not_ready 只計仍低於 L2/L3 的 camera，已成功 snapshot probe 的 metadata-only L2 不會因尚未配置 AI vision runtime 被重新計為 blocked；discovery-only public page 仍列為 source_discovery_required_before_internal_use / blocked_pending_source_discovery；latest snapshot configuration_required / fetch_failed / invalid_snapshot 會分別落到 runtime_configuration_required_blocked、runtime_fetch_failed_blocked、runtime_invalid_snapshot_blocked，讓 Phase A completion 明確停在 L2 或可處理 blocker，而非 generic runtime_probe_failedAPI key required，回 runtime_fetch_expansion_reported；不公開 raw URL / raw image bytes
GET /v1/reality/cameras/status-tableCamera Status Table：API-key protected 狀態表，支援 format=json 或 format=markdown，預設以 limit=500 回 397 支 camera 的安全欄位：camera_id、county、location、L0/L1/L2/L3、completion_status、highest_safe_target_level、internal_callability_status、internal_use_allowed、public_access_tier、snapshot_status、locator-free snapshot_failure_reason、blockers、next_action、owner_track、public_source_url；JSON/markdown 都顯示內部可調用性與最後安全 snapshot probe 結果，並在 top-level 回 returned-row internal_callability_summary / public_access_tier_summary / snapshot_probe_status_summary / l2_remediation_summary / l2_remediation_source_groups，以及不受小 limit 分頁影響的 all_registry_summary / all_registry_completion_summary / all_registry_internal_callability_summary / all_registry_snapshot_probe_status_summary / all_registry_camera_rollout_readiness / all_registry_l2_remediation_summary / all_registry_l2_remediation_queue / all_registry_l2_remediation_source_groups / all_registry_l2_remediation_batch_plan，用來盤點全 397 支「內部是否可調用」以及 blocked work 是 configuration_required、fetch_failed 或其他 probe 狀態，而非直接公開影像權限；locator-free snapshot_failure_reason 可包含 missing_configured_locator_value、fetch_failed、unsupported_content_type、official_resource_html_response、official_resource_access_challenge 或 official_resource_record_not_found，其中 access challenge 代表官方端點回 HTML gateway/challenge；record not found 代表官方 JSON resource 可讀但沒有匹配 camera record / 安全 image locator，兩者都需改用授權/一手 image locator 或重新 source discovery 後再 probe；camera_rollout_readiness_v0 明確回全 registry callability conclusion completeness、L2/remediation/L3 counts 與 L3 必要 live gates，且 true_l3_rollout_allowed_from_status_table_only=false；camera_l2_failure_reason_repair_contract_v0 / camera_l2_source_specific_repair_playbook_v0 會在 summary/source groups/batch plan 內針對 locator-free failure reason 回 required artifacts/operator action/no-locator safety flags，避免把 HTML gateway/index 或 fixture/dry-run 誤算 L2/L3；camera_l2_remediation_summary_v0 只回 aggregate counts、public access tier split、safe public_auxiliary first buckets 與 operator order（fetch_failed → invalid_snapshot → configuration_required；先修已配置 server-side locator 的 runtime_probe_failed，再處理 source_discovery_required），camera_l2_source_group_discovery_contract_v0 會嵌在 source groups / batch plan，列出 official source page review、per-camera locator review、server-side secret configuration、re-probe before L2 與 must_not_expose policy；camera_l2_official_source_page_review_v0 只回 data.gov.tw public dataset id/title 與 HTTP 200/title-match review 結論，並嵌入 metadata-only camera_l2_official_resource_metadata_review_v0（public resource format summary、providing agency、update frequency、license、per-camera matching field names、locator field names only），不回 resource endpoint、raw locator/env、credential 或 raw image；camera_l2_remediation_queue_v0 只回最多 10 筆下一批可操作 metadata（camera_id/county/display/location/snapshot_status/access tier/next_action/public source），camera_l2_remediation_source_groups_v0 依 source_lineage/public_source_url 彙總需同批補 server-side locator 或修 probe 的候選數、snapshot/access-tier split 與最多 3 個 sample camera_id；camera_l2_remediation_batch_plan_v0 以預設 90 支為一批，產生 out-of-band server-side locator 設定/修復與 re-probe 的安全 bulk plan，並回 metadata-only missing_locator_configuration_candidates、configured_locator_repair_candidates、expected_live_l2_delta_if_all_candidates_probe_successfully 與 workstreams 以區分補缺 locator 與修已配置但 fetch/invalid 的 locator；四者都不回 locator/env/secret/raw image；unfiltered 小 limit request 只跑單次 all-registry probe，再由同一 probe result 切出 returned rows，避免 transient camera source 造成 returned-row summary 與全表 summary 不一致；若 blockers 或 source policy 為 discovery_only，即使有 public page，也回 source_discovery_required_before_internal_use / blocked_pending_source_discovery，因該頁仍是 discovery/index reference 而非已審查的逐 camera callable locator；batch21/batch28/batch29/batch30/batch31/batch32/batch33/batch34/batch35/batch36/batch37/batch38 延伸 data.gov.tw 36687 水利署水利防災用影像 117 支低隱私水情與防災影像 candidate；batch20 仍保留 data.gov.tw 41567 水利署河川分署遠端監控影像 10 支低隱私臺東卑南溪/高雄二仁溪河川疏濬工區觀測站 L2-candidate，實際 snapshot locator 必須留在 server-side config，未設定前不假稱 L3；data.gov.tw 142980 IoW淹水深度最新資料已列為 official_wra_iow_realtime_flood_depth_review_required 低隱私防災感測 context；data.gov.tw 5982 防災資訊淹水警戒已列為 official_wra_flood_warning_context_review_required 低隱私水利署防災警戒 context；data.gov.tw 22227 河川水位測站站況已列為 official_wra_river_water_level_station_status_metadata_review_required 低隱私水位站 metadata context；data.gov.tw 156083 水位計已列為 official_yunlin_water_level_gauge_metadata_review_required 雲林低隱私水情測站 context；data.gov.tw 145465 水位站已列為 official_yunlin_water_level_station_metadata_review_required 雲林低隱私水情測站 context；data.gov.tw 138749 臺北捷運萬大中和樹林線第一期工程交通即時影像位置資料集已列為 official_taipei_metro_construction_camera_metadata_high_privacy_review_required 交通/施工影像 metadata，高隱私與車牌風險未審查前不升 L2/L3；data.gov.tw 131753 申請介接臺北市閉路電視攝影機(CCTV)作業說明已列為 official_taipei_cctv_authorization_process_reference_only 授權流程參考；data.gov.tw 156053 CCTV設備座標已列為 official_taichung_cctv_device_coordinates_high_privacy_blocked；data.gov.tw 146054 土石流潛勢溪流參考雨量站雨量資料已列為 official_moa_debris_reference_rainfall_context_review_required 低隱私防災雨量 context；data.gov.tw 177644 桃園國際機場即時航班第二版已列為 official_taoyuan_airport_realtime_flight_context_non_camera；data.gov.tw 132888 臺北市室內空氣品質相關資訊已列為 official_taipei_indoor_air_quality_context_review_required；data.gov.tw 174854 觀光政策已列為 official_tourism_policy_reference_only；data.gov.tw 36687 水利署水利防災用影像已列為 official_wra_water_disaster_camera_l2_snapshot_metadata_candidate_review_required；95806 鯉魚潭水庫每日水情資訊、41568 水庫每日營運狀況與 32729 水利署所屬雨量站基本資料只作低隱私水情/雨量 cross-check context；data.gov.tw 37665 CCTV 靜態資訊(v2.0) 與 122133 嘉義縣即時路況攝影機CCTV 僅作交通/CCTV source discovery，高隱私與車牌風險未審查前 blocked；130237 克利金法逐時雷達估計降雨資料只作雨量/淹水 cross-check context；146055 土石流潛勢溪流縣市鄉鎮警戒值清單與 174270 大規模崩塌潛勢區警戒值只作低隱私防災 threshold context；163147 淹水感測器(白金)只作雲林縣政府低隱私防災感測 cross-check context；上述 discovery 需逐筆授權/freshness/probe，不當成 camera visual truth；不回 raw URL / 原圖 / secretAPI key required，回 camera_status_table_ready
scripts/run_camera_upgrade_batch.pyCamera Upgrade Batch Runner：operator-only report runner，schema=camera_upgrade_batch_runner_v0；以 --offset/--batch-size/--max-batches 分批處理全 registry，輸出 L0/L1/L2/L3、blockers 與 Recommended next batch；report-only，不寫 registry，不啟用新 feedCLI / staging operator，支援 --format json / --format markdown；不公開 raw URL / raw image bytes
GET /v1/reality/cameras/{camera_id}/live-queryCamera Live Visual Query：schema=camera_live_visual_query_v0；任一已登錄 camera_id 都可查安全狀態。已達 L3 回即時 visual evidence 摘要；未達 L3 回 9-step onboarding checklist、blockers 與 next steps；不回原圖、不回技術取流網址。Camera L3 Rollout / L2 snapshot metadata：目前 local/fixture-verified L2 snapshot metadata target 為 397 支，含 batch13 data.gov.tw 174655 官方觀測站、batch14 data.gov.tw 100218 臺南市管區域排水即時影像、batch15/batch16/batch17/batch18/batch19/batch20 data.gov.tw 41567 水利署河川分署遠端監控影像、batch21/batch28/batch29/batch30/batch31/batch32/batch33/batch34/batch35/batch36/batch37/batch38 data.gov.tw 36687 水利署水利防災用影像與 batch22/batch23/batch24/batch25/batch26/batch27 data.gov.tw 28196 環境部空氣品質監測即時影像資料 candidate；staging live 仍需 server-side snapshot config/probe 才確認實際 L2，第一手來源優先但不阻塞，proxy evidence 必須標註 lineage/tier/privacy、套 confidence cap 與 limitations，L3 仍需真實可信 vision runtime；已配置 server-side locator 若指向官方 JSON resource/index（含 CKAN-style nested wrappers / CCDList parent-child records），snapshot fetcher 只在 process 內以 split camera terms 匹配單一 camera image 並回 metadata，不公開 resource endpoint、per-camera locator、JSON payload、env var 或 raw imageAPI key required，回 live_visual_evidence_available / onboarding_required / camera_not_found
GET /v1/reality/cameras/selectMulti-source Camera Selection v0：依 location / intent 排序候選鏡頭；不把 discovery_only 視為可抓取影像API key required，目前回 multi_source_camera_selection_v0
GET /v1/reality/cameras/{camera_id}/snapshotserver-side 抓取白名單攝影機 snapshot metadata；不回傳影像內容或 raw URLAPI key required，目前可能回 configuration_required
GET /v1/reality/cameras/{camera_id}/visual-evidence攝影機 visual observation usable V0；有 server-side snapshot 時回 metadata-only visual_evidence_available，不回 raw image bytes、不回 raw URL、不做人臉/車牌/個體追蹤API key required，目前可能回 metadata_only_snapshot_available / snapshot_not_available / analysis_not_enabled
GET /v1/reality/cameras/vision-provider/statusCamera Vision Provider Status V0：只回 provider/model/credential 是否 configured 的 metadata；不呼叫外部 vision API、不回 key/env/raw prompt/raw image；內含 camera_vision_call_budget_guard_v0、max_calls_per_camera_per_hour、cache_ttl_seconds、max_image_bytesAPI key required，回 camera_vision_provider_status_v0，可能是 not_configured / configured_disabled
GET /v1/reality/cameras/{camera_id}/stabilityCamera Stability Monitor v0：回報 fetch 成功率、延遲與內容一致性；不公開 raw URLAPI key required，目前多為 limited_history
GET /v1/reality/cameras/{camera_id}/cross-checkCamera × Official Data Cross-check v0：標準化攝影機 visual evidence 與 CWA / radar / satellite / traffic / water/disaster 官方來源的關係API key required，目前回 insufficient_data / visual_analysis_not_enabled
POST /v1/reality/check送出自然語言 Reality Check 查詢API key required，目前氣象查詢可回 live_data；CWA Forecast Query V0 支援 rain_forecast / cwa_rain_forecast_answer_v0，用 CWA 短時預報回答「阿里山下午會下雨嗎？」並標示 forecast 不是 current observation；CWA Earthquake Reality V0 支援 earthquake_recent，使用 E-A0015-001 / E-A0016-001 回最近地震、震央、規模、深度、最大震度與受影響縣市
POST /v1/reality/demo-checkPublic Demo Check：首頁免 API key demo mode；不需要 X-API-Key，且只允許首頁固定 demo queries（Level 2 為 15 個固定 demo 問題）；非 allowlist 問題回 demo_query_not_allowedPublic but allowlisted；不回傳、不嵌入、不暴露 server-side API key；任意查詢仍需使用 POST /v1/reality/check + 自己的 API key

Production Readiness Matrix V0

GET /v1/reality/production-readiness 回 production_readiness_matrix_v0 / readiness_matrix_returned，用 L0–L8 明確區分 planned、contract、staging verified、production candidate 與 production ready，避免把 foundation 誤稱為 production。

Source Runtime Health V0

GET /v1/reality/source-health 回 source_runtime_health_v0 / source_health_returned，用 read-only metadata 檢查 CWA official API client 與 camera visual validation foundation 的 runtime readiness。

CWA Weather Reality Production Gap Checklist V0

GET /v1/reality/cwa-production-gap 回 cwa_production_gap_v0 / gap_checklist_returned，明確列出 CWA Weather Reality 從 L6 → L7 production ready 的 pass / partial / blocker。

Admin Console Security Foundation V0

Reality API 也提供給人類營運者看的後台入口：/admin/login。V0 使用 server-side admin username + password hash、session cookie、HttpOnly、Secure、SameSite=Lax，並有登入失敗 rate-limit 與 audit log foundation。

查詢資料源能力

curl -s https://taiwanworldmodel.thesense.biz/v1/reality/sources   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

依 intent 過濾：

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/sources?intent=traffic_congestion"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

送出 Reality Check

curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"阿里山現在有雲海嗎？"}'

Weather Reality API Usage：TrueSight 氣象查詢

TrueSight 目前可以先用 Reality API 查氣象資訊，暫時不啟用攝影機驗證。支援的 weather runtime intents 包含 rain_now、weather_suitability、flooding_risk。

curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"阿里山現在有下雨嗎？"}'
Status意義TrueSight UI 建議
live_data已取得 CWA 觀測/雨量/短時預報 signals可顯示為氣象現況查證結果，但仍需顯示 limitations
configuration_requiredruntime 已接好，但服務尚未設定 CWA_API_KEY顯示為介接已就緒、等待金鑰設定，不可顯示成即時天氣
insufficient_data該地點或意圖沒有足夠資料顯示無足夠資料，不做明確建議
 
{
  "intent": "rain_now",
  "status": "configuration_required",
  "current_state": "unknown",
  "data_sources": ["cwa_weather_observation", "cwa_rainfall_observation", "cwa_weather_forecast"],
  "signals": [],
  "limitations": ["需要在服務環境設定 CWA_API_KEY"]
}

Short-term Forecast Runtime V0

Weather Reality runtime 現在會嘗試讀取中央氣象署短時/鄉鎮區預報資料集 F-D0047-091，normalize 成 signal_type=short_term_forecast、source_id=cwa_weather_forecast，欄位包含 rain_probability_percent、forecast_uncertainty、weather_description、min_temperature_c、max_temperature_c、forecast_time、valid_time、valid_from、valid_to 與 evidence_role=forecast_not_observation。

POST /v1/reality/check 的 Weather Reality response 會加入 forecast_context / cwa_forecast_context_v0，用 disagreement_status 標示觀測與預報是否一致；例如 forecast_possible_rain_but_observation_no_rain 表示目前地面觀測無明顯降雨，但短時預報顯示後續降雨機率偏高。freshness_status 會標示 valid、expired、missing_valid_time 或 not_yet_valid；只有 decision_usable=true 的有效預報才可提高 confidence。政策是 forecast_is_future_context_not_current_observation，不可把預報包裝成現在已發生的現況。

當 short_term_forecast 成功接入時，evidence_plan 會把 short_term_forecast -> cwa_weather_forecast 標成 live_data，Evidence Fusion 可避免因缺短時預報而降級；若 forecast 尚不可用，仍會誠實標成 planned 或 configuration_required。

注意：短時預報不是現況觀測；它用來回答「接下來一段時間是否會受雨影響」，不可取代測站觀測或現場攝影機驗證。

攝影機驗證下一階段：氣象 live data 穩定後，下一個大項目是公共攝影機白名單與 visual evidence，用來驗證氣象局實時資訊是否符合現場畫面。

Location Resolution：地點解析與最近測站

Location Resolution Engine V1 會先把 query 中的地點解析成可解釋 contract，而不是只回單一座標。location_resolution 會包含 status、confidence、source_provenance、candidates 與 limitations；若短地名有多個接近候選，會回 ambiguous_location，避免過度自信。未解析到單一地點前，不會呼叫天氣、交通或攝影機 runtime，以避免錯用資料源；呼叫端應讓使用者選擇候選或補充縣市/行政區/地標。地名解析的核心不是相似字串，而是依照用戶關鍵字與背後目的/意圖找到正確目標；不確定時必須候選/追問或低信心。若 internal registry 找不到，V1.2 可用 OSM/Nominatim 作 external_geocoding_fallback，回 resolved_low_confidence 並標明 provenance/limitations。天氣 runtime 的最近測站選擇則放在 location_resolution.data_source_resolution，例如 data_source_resolution.method=coordinates_nearest_station。

地點解析不應把未知或非阿里山地點掉回阿里山。已支援將 林口光曜車業 類查詢解析為 新北市林口區附近；也支援 東湖現在的雨量，解析為 臺北市內湖區東湖附近 與 rain_now intent。

curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"林口光曜車業現在有下雨嗎？"}'
curl -s -X POST https://taiwanworldmodel.thesense.biz/v1/reality/check   -H "Content-Type: application/json"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"   -d '{"query":"東湖現在的雨量"}'

若 POI 尚無第一手精準座標，會先降級為行政區或區域附近，例如 新北市林口區附近、臺北市內湖區東湖附近；結果仍需顯示測站距離與 limitations，不可宣稱代表單一店門口或街角微氣候。

Query Understanding V0：理解問題背後目的

POST /v1/reality/check 會回傳 query_understanding，用來說明系統如何從字面問題推斷使用者真正想做的現實決策。欄位包含 surface_query、place_keywords、condition_keywords、time_scope、explicit_intent、inferred_underlying_task、answer_goal、evidence_requirements、clarification_required。

例如 南港展覽館現在雨量 不只是查 mm 數字；V0 會推斷 inferred_underlying_task=go_or_wait_decision，目標是判斷現在前往是否會受雨影響，並要求 evidence_requirements 至少包含最近雨量站、氣象觀測、短時預報與可選攝影機驗證。若使用者只問「台北車站現在怎樣」，會標示 clarification_required=true，先釐清想查天氣/人潮/交通/事件安全狀況。

Evidence Planner V0：證據需求到資料源計畫

query_understanding.evidence_requirements 會進一步轉成 evidence_plan，說明每個 evidence requirement 對應哪個資料源、目前是 live_data、planned、configuration_required、blocked_by_location_ambiguity 或 planned_or_gated，以及是否 blocking。欄位包含 status、summary、required_count、primary_ready_count 與 items。

例如 南港展覽館現在雨量 目前可得到 evidence_plan.status=partially_satisfied：最近雨量站與氣象觀測可由 CWA live data 支援；short_term_forecast 仍是 planned；optional_camera_visual_validation 會標成 planned_or_gated，不可假裝已用於判斷，也不可把第三方/攝影機 optional evidence 當成第一手官方資料。

Evidence Fusion V0：證據完整度與信心降級

evidence_fusion 會根據 evidence_plan 的 readiness 與 blocking 狀態，產生 status、completeness、base_confidence、adjusted_confidence、confidence_delta、applied_rules 與 fusion limitations。當必要 evidence 缺少時會套用 missing_required_evidence，回 partial_evidence 並降低 confidence；當地點仍歧義時會 blocked，不可進行 fusion。

例如 南港展覽館現在雨量 目前 CWA 觀測與雨量 live，但短時預報仍 planned，所以 base confidence 會被降級為 adjusted_confidence，並把缺少 short_term_forecast 的限制加到 response limitations。

Temperature Definitions：溫度定義

Weather Reality 會明確區分 室外實測氣溫 與 體感溫度，避免把測站溫度誤解為人體實際感受。

欄位中文定義資料意義
air_temperature_c室外實測氣溫中央氣象署測站量到的空氣溫度，不等於人在太陽、濕度、風速下的感受。
apparent_temperature_c體感溫度由氣溫、濕度、風速估算；炎熱潮濕時使用 heat index，寒冷有風時使用 wind chill。

Reality Graph 資料源原則

Taiwan World Model 不是 CCTV 聚合器。官方資料是現實證據的一等公民；攝影機是眼睛，不是整個世界模型。

資料類型例子角色
官方公告封路、停班停課、災害警戒、施工公告權威狀態來源
感測器雨量、水位、AQI、VD 車流、溫度量化現實狀態
交通資訊CMS、事故、路況、旅行時間道路可用性與壅塞判斷
攝影機景點 webcam、交通 CCTV、河川影像視覺驗證與補充

Multi-dimensional Fusion：多維融合與單一維度檢視

多維度融合是預設：Taiwan World Model 會把官方觀測、雷達、衛星、攝影機、交通、水文、防災告警、新聞/社群等多個維度互相驗證，形成可解釋、有 confidence、有 limitations 的現實判斷。

單一維度檢視 也可提供，例如只看攝影機、只看衛星、只看雨量站或只看交通；這是 single_dimension_view，適合除錯、透明度、專業查核與使用者只想「看看」某一層。但單一維度只能回答局部狀況，不能包裝成完整 world model 答案。

模式用途限制
multi_dimensional_fusion預設 Reality Engine；回答是否適合出門、是否真的下雨/塞車/危險成本較高，需要治理與來源分級
single_dimension_view只看某一資料層，例如 camera / satellite / rainfall / traffic太大材小用；只能代表局部 layer，不代表完整現實判斷

公共資源 catalog

Source ID類型狀態備註
cwa_weather_observationweatherclient_ready_requires_cwa_api_key中央氣象署觀測資料；CWA client v0 已完成，需環境變數 API key 才能 live fetch
cwa_rainfall_observationrainfallclient_ready_requires_cwa_api_key中央氣象署雨量資料；CWA client v0 已完成，需記錄測站、觀測時間與 freshness
cwa_weather_forecastforecastplanned週末/假期預報、forecast_uncertainty、forecast_divergence
cwa_radar_echoradarplanned短時降雨 nowcast 與雨帶移動
cwa_satellite_cloudsatelliteplanned雲帶、颱風外圍環流、能見度趨勢
cwa_typhoon_forecastforecast_alertplanned颱風路徑、警報與不確定性
tdx_transport_traffictrafficplannedTDX 交通資料
freeway_vd_traffictraffic_sensorplanned高速公路 VD 車流/車速/占有率
freeway_cms_messagestraffic_bulletinplanned高速公路 CMS 資訊可變標誌
official_road_closure_bulletinsofficial_bulletinplanned封路、施工、災害通報
scenic_camera_public_feedscameracandidate_review_required景點公開攝影機；需白名單審查
freeway_traffic_cctvtraffic_cameracandidate_review_required高速公路 CCTV；不公開原始 URL，不做車牌/車輛追蹤
river_water_level_observationwater_levelplanned河川水位觀測
flood_alertsdisaster_alertplanned淹水警戒與防災告警
reservoir_statusreservoirplanned水庫水情與洩洪資料
aqi_observationair_qualityplanned環境部空氣品質 AQI
public_parking_availabilityparkingplanned公共停車場即時剩餘車位
tourism_scenic_spotstourismplanned觀光景點基本資料與公告
cwa_earthquake_reportsearthquakeplanned中央氣象署地震報告與地震速報；地震資訊需以官方發布時間、震央、規模、深度為準
cwa_tsunami_messagestsunami_alertplanned中央氣象署海嘯資訊與警報；海嘯警報不可由攝影機或社群訊號取代官方告警
nfa_disaster_alertsdisaster_alertplanned消防署 / 災防告警與防災資訊
soil_debris_flow_alertslandslide_alertplanned土石流與大規模崩塌警戒資料

Decision Reality：現在進行式狀態 → 決策

Reality API 的核心不是展示資料，而是回答會影響行動的 現在進行式 狀態：現在是否真的在下雨？現在是否真的在塞車？資料是否夠新，能不能支援即時決策？

使用者決策需要的 current_statedecision_impact / recommendation
騎車要不要穿雨衣rain_now、drizzle_now、road_wetness、rain_trend穿雨衣 / 輕便雨衣即可 / 可暫不穿但 30 分鐘內注意
走路撐傘是否夠rain_intensity、wind_gust、sideways_rain、distance_duration撐傘可行 / 需雨衣 / 建議延後
開車或改搭火車traffic_congestion、road_availability、stuckness、incident_risk開車可接受 / 改搭火車較穩 / 延後出發
 
{
  "current_state": "drizzle_now",
  "decision_impact": "騎車會被淋濕，走路短程撐傘可接受",
  "recommendation": "騎車穿雨衣；步行可撐傘",
  "confidence": 0.78,
  "limitations": ["最近雨量站距離 4.2 公里"]
}

Now Freshness Contract：現在資料必須夠新

若資料不夠新，Reality API 不可假裝是「現在」。每個可用於即時決策的 signal 都應回報 observed_at、fetched_at、freshness_seconds、staleness。資料過舊時應降級為 stale 或 unknown，並提示不要用於即時決策。

狀態意義決策處理
fresh資料足夠新，可支援現在判斷可給 recommendation
stale資料已過時，不代表現在只能給保守建議或要求重查
unknown沒有足夠資料判斷現在不可做明確決策建議

Weather Reality：天氣現狀如何掌握？

天氣不能只看預報。Reality API 會區分 預報 forecast、觀測 observation、現場視覺 visual evidence、nowcasting 臨近推估。當氣象說天晴但現場毛毛雨，常見原因是微氣候、地形雲霧、測站距離、雷達解析度或降雨胞偏移。

問題主要訊號判斷重點
預報晴但現場毛毛雨雨量站、雷達回波、濕度/露點、攝影機地面濕潤、社群回報標記為微尺度降雨或地形性毛毛雨；以資料新鮮度與近距離觀測提高 confidence。
預報雨但現場大太陽雷達雨帶位置、衛星雲圖、日照/能見度、攝影機天空狀態、最近雨量判斷雨帶是否偏移、已通過或只影響同預報區的其他地點。
山區雲海/霧/能見度濕度、露點差、風速、地形高度、攝影機視覺、雷達/衛星把雨、霧、雲海分開；不把看不清楚一律當成下雨。

Forecast Reality：Weekend / Holiday Planning

CWA Rain Forecast Answer V0：POST /v1/reality/check 可將「阿里山下午會下雨嗎？」這類 future rain query 分流成 rain_forecast，並回傳 forecast_answer / cwa_rain_forecast_answer_v0。回應會保留 current_observation_state 與 forecast_context，政策固定為 forecast_is_future_context_not_current_observation，避免把短時預報包裝成現在已下雨。

幾天後或週末假期的天氣預測有價值，但必須顯示 forecast_uncertainty 與 forecast_divergence。颱風生成、外圍環流、下沉氣流、雲雨帶位置與路徑偏移，都可能讓「預測大雨」與「當地實際很熱很晴」同時成立。

情境需要比較的訊號回答方式
颱風預測大雨但當地大太陽颱風路徑、外圍環流、下沉氣流、雲雨帶位置、衛星雲圖顯示預測分歧，標示短期可能熱但後續風險仍高
預報好天氣但烏雲籠罩並下雨雷達回波、衛星雲圖、局部對流、地形雲、即時雨量用 nowcast 修正 forecast，提醒現況已偏離預報
週末露營是否適合多模型比較、預報變動趨勢、雨量機率、風速陣風、地形影響回傳可行/觀望/不建議，並列出不確定性來源

Mountain / Camping Nowcast：山區與露營短時天氣

露營最怕天氣快速變化，因此不能只回答現在有沒有下雨，而要判斷 30–120 分鐘內是短時轉好還是短時轉壞。山區天氣會被地形、地勢、海拔高度、坡向、迎風/背風面、谷地/稜線差異強烈影響。

訊號用途露營判斷
雲的型態與移動判斷雲底是否抬升、雲量是否減少、雨帶是否離開雲層變薄、雲底抬升 → 可能短時轉好
濕度/露點差判斷霧、低雲、毛毛雨與凝結風險露點差很小 + 風弱 → 霧/毛毛雨可能持續
風速風向判斷迎風坡降雨、背風面轉晴、雲霧移動速度風向轉乾、風速增加且雨帶離開 → 可能轉好
雨量趨勢比較近 10/30/60 分鐘雨量變化雨量下降 + 雷達回波遠離 → 可能短時轉好
雷達回波移動追蹤降雨胞是否接近或遠離營地回波增強接近 + 高濕 → 短時轉壞
地形/海拔/坡向修正模型預報與測站資料同一行政區內，稜線、谷地、迎風坡可能完全不同

若當地沒有風速觀測，像 Windy 這類服務通常使用 ECMWF/GFS/ICON 等數值天氣模型推估網格風場，再依位置顯示；Reality API 需標示為 model_estimated_wind，不可假裝是現場實測。

Camera Visual Evidence：攝影機作為現場驗證

攝影機不是唯一資料源，但很適合作為 現場驗證 與 sanity check，用來確認預報、模型、感測器與官方公告是否符合實際畫面。

用途可驗證內容限制
天氣是否真的下雨、地面是否濕、天空是否放晴、雲霧是否降低鏡頭髒污、逆光、夜間畫面會降低可信度
交通車流是否停滯、是否積水、事故/封路是否可視不做車牌或個別車輛追蹤
景點人潮、能見度、海況、現場可用性不做人臉或個體追蹤

治理原則：不公開原始 CCTV URL、不做人臉、不做車牌、不長期保存原始影像；對外只輸出 summary / confidence / limitations。

Identity-Level Analysis Governance：身分層級分析治理

公開版 Reality Search 不追蹤個體。車牌辨識、人臉辨識與個體追蹤不是目前公開 API 的核心能力，也不應混入一般天氣、交通、景點與災害查詢。

模式定位治理要求
Public Reality Search回答地方狀態：下雨、塞車、人潮、淹水、道路可用性不做人臉、不做車牌、不追蹤個體，只回聚合狀態
Law Enforcement Module未來可與警政單位合作的警政授權模組必須獨立權限、合法授權、任務限定、資料最小化、完整審計、用途審查

原則：身分層級的分析只能存在於合法授權、可稽核、政府核准的受管制部署中；不能成為一般公開 Reality Search 的預設能力。

Satellite Evidence：衛星畫面

衛星畫面可以取得，並會作為 Reality Search 的大範圍天氣與災害環境 evidence。策略是：衛星負責大範圍雲系與趨勢，攝影機負責地面現場驗證；衛星影像不可單獨代表某個地點正在下雨或安全。

source_id來源狀態用途
cwa_satellite_cloud中央氣象署衛星雲圖metadata_endpoint_found已確認 CWA dataset O-B0033-003：全解析紅外線衛星雲圖KMZ檔-東亞，10 分鐘更新，metadata 欄位含 Datetime / ProductURL。data.gov.tw 可作 discovery/provenance，runtime 優先接 CWA fileapi / 官方 bucket。
himawari_8_9_open_satelliteJMA / NOAA Open Data on AWScandidate_open_data_raw_pipeline_requiredHimawari-8/9 原始開放衛星資料；需裁切台灣區域、投影與處理後才能作 evidence。

Camera Source Discovery v0：攝影機多來源盤點

攝影機大項目目前進入來源盤點階段，原則是多來源，不單點依賴。第一批 registry seed 已涵蓋山區、海岸、景點、交通與水文防災候選來源；多數仍是 discovery_only 或 license_review_required，不代表已可抓取或可作 production evidence。

location_id類型用途狀態
alishanscenic_camera雲海、下雨、能見度1 個 optional proxy source 可抓 metadata；另有候選來源待審查
hehuanshanmountain_camera雲霧、積雪、能見度discovery_only
wuling_farmmountain_camera天氣、人潮、能見度discovery_only
kentingcoastal_camera玩水條件、浪況視覺輔助、人潮discovery_only
river_disaster_generalwater_disaster_camera淹水、水位、河川現場驗證requires_authorization

Camera Whitelist Workflow：攝影機白名單介接流程

公共公開攝影機不會直接全量接入。每個來源都必須完成候選來源盤點、授權審查、隱私風險審查、技術可用性檢查與白名單啟用。

  1. 候選來源盤點：記錄 provider、頁面來源、地點、用途、更新頻率與初步風險。
  2. 授權審查：確認是否允許抓取、AI 分析、展示截圖或僅可連回原頁。
  3. 隱私風險審查：排除住宅、學校、醫院、私人空間與容易識別個體的角度。
  4. 技術可用性檢查：確認格式、穩定性、更新頻率、延遲與是否需要只存 metadata。
  5. 白名單啟用：只允許通過審查的 camera source 進入 on-demand visual evidence pipeline。

API Key Application / Partner Client Onboarding

早期合作夥伴、政府 PoC 或 TrueSight client 應使用獨立 API key，以便累積 usage metering / shadow billing。建立 client 時使用 scripts/create_api_client.py，stdout 只顯示一次 api_key_once；registry file 只保存 api_key_sha256。不要把 plaintext API key commit 到 repo、docs、tests、logs 或 Codex prompt。

.venv311/bin/python scripts/create_api_client.py   --client-id partner-demo   --tier pilot   --billing-mode shadow_billing   --allow-endpoint v1.reality.auth_whoami   --allow-endpoint v1.reality.billing_current   --allow-endpoint v1.reality.sources   --output /tmp/partner-demo-client.json

完整文件：docs/API_KEY_APPLICATION_AND_CLIENT_ONBOARDING.md。Codex 不應要求使用者把 API key 貼進 prompt；只應使用 runtime env / secret store 中的 key。

Usage Quota Guard：用量上限與成本防護

早期 partner / government PoC client 可設定 monthly_request_limit 與 monthly_ru_limit。受保護 API 在執行昂貴工作前會先做 quota pre-flight check；超過上限時回 429 usage_limit_exceeded，不再產生新的 billable usage event。

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "API client monthly usage limit has been exceeded.",
    "details": {
      "reason": "monthly_request_limit_exceeded",
      "monthly_request_limit": 100000,
      "current_requests": 100000,
      "current_reality_units": 8420.5,
      "estimated_reality_units": 0.1
    }
  }
}

v0 enforcement 已涵蓋 metered endpoints：sources、cameras、camera selection、snapshot、visual evidence、stability、cross-check 與 reality check。monthly_spend_limit_twd 目前仍作為 profile / shadow-billing 欄位，正式金額停權需等 pricing model 校準後再啟用。

Partner Pilot Report：合作夥伴 / 政府 PoC 月報

scripts/generate_partner_report.py 可從 server-side JSONL usage log 產出 partner_pilot_monthly_report_v0，支援 JSON 與 Markdown。用途是對 partner / government PoC 說明本月使用量、Reality Units、endpoint 分布、quota 使用率、高成本功能與下一步建議；它不是正式 invoice。

/opt/taiwan-world-model/.venv/bin/python scripts/generate_partner_report.py   --usage-log /var/lib/taiwan-world-model/usage-events.jsonl   --client-id partner-demo   --period 2026-06   --billing-mode shadow_billing   --monthly-request-limit 100000   --monthly-ru-limit 250000   --monthly-spend-limit-twd 5000   --format markdown

報告只應分享 aggregate summary；不要公開 raw usage log，因為其中可能包含 client_id、endpoint、intent、location_id、status 等 operational metadata。

Admin Console V0：API client 管理平台

Durable Source Catalog Store V0 load-time hardening：load-time catalog fstat failure fail-closed guard、load-time catalog fd fstat before read TypeError fail-closed guard、load-time catalog lstat failure fail-closed guard、load-time catalog open TypeError fail-closed guard、load-time catalog fdopen TypeError fail-closed guard、load parent-dir open TypeError fail-closed guard、initial load-time catalog lstat failure fail-closed guard、initial load-time catalog lstat TypeError fail-closed guard、existing write-time catalog lstat TypeError fail-closed guard、pre-read catalog path lstat TypeError fail-closed guard、write parent-dir lstat TypeError fail-closed guard、write parent-dir helper lstat TypeError fail-closed guard、temp file fsync TypeError fail-closed guard、temp file lstat during fsync TypeError fail-closed guard、parent-dir fsync lstat TypeError fail-closed guard、parent-dir fsync TypeError fail-closed guard、initial load preflight lstat-only metadata validation guard、ancestor symlink lstat-only scanner guard / ancestor symlink lstat TypeError fail-closed guard、load-time catalog fd primary failure precedence guard、load-time catalog fd close-before-read TypeError fail-closed guard、missing restart_consistency.paths_hidden / restart consistency paths_hidden required load guard、redaction removed_categories deterministic order load guard、load parent-dir fstat failure fail-closed guard、load parent-dir fstat TypeError fail-closed guard、load parent-dir lstat TypeError fail-closed guard、load parent-dir lstat failure fail-closed guard、load parent-dir primary failure precedence guard、load parent-dir close TypeError fail-closed guard、load-time catalog parse primary failure precedence guard、post-read catalog fd fileno failure fail-closed guard、post-read catalog fd fileno TypeError fail-closed guard、post-read catalog fd fstat failure fail-closed guard、post-read catalog fd fstat TypeError fail-closed guard、post-read catalog path lstat failure fail-closed guard、post-read catalog lstat TypeError fail-closed guard、post-read parent-dir fstat failure fail-closed guard、post-read parent-dir fstat TypeError fail-closed guard、post-read parent-dir lstat TypeError fail-closed guard、post-read parent-dir lstat failure fail-closed guard、post-read parent-dir close TypeError fail-closed guard 與 post-read parent-dir primary failure precedence guard、post-replace parent-dir fstat TypeError fail-closed guard、post-replace catalog close TypeError fail-closed guard、post-read catalog close TypeError fail-closed guard 會在 load-time catalog fd/path、parent fd/path、catalog parse 與 wrapper validation/post-read fd/path/parent metadata recheck 前，把 catalog fd/path、parent-dir inspection/close failure、parser TypeError 或 reordered redaction.removed_categories wrapper 收斂為 fail-closed fallback，不載入非 canonical durable catalog；inspection/parse/close errors 仍使用 source catalog fd must be inspectable before read / source catalog path must be inspectable before read / source catalog parent directory must be inspectable before read / source catalog parent directory fd must be closable before read / source catalog JSON must be parseable / source catalog fd must be inspectable after read / source catalog path must be inspectable after read / source catalog parent directory must be inspectable after read / source catalog fd must be closable after read / source catalog parent directory fd must be closable after read 這類固定訊息，且不暴露 durable path/source payload/API key/hash/token/password/credential/raw feed locator。

內部管理平台已提供最小 V0：/admin、/admin/clients、/admin/clients/{client_id}、/admin/clients/{client_id}/report。Admin Console 需 server-side REALITY_ADMIN_KEY，呼叫時使用 header X-Admin-Key；不顯示 plaintext API key 或 key hash。

Admin Source Registry Persistence V0：staging sources-only apply 在設定 ADMIN_SOURCE_CATALOG_PATH 後，會以 admin_source_catalog_v1 / durable_json_v1 原子寫入 source metadata；redaction allowed key table ADMIN_SOURCE_CATALOG_REDACTION_ALLOWED_KEYS、redaction required value table ADMIN_SOURCE_CATALOG_REDACTION_REQUIRED_VALUES、redaction required list-value table ADMIN_SOURCE_CATALOG_REDACTION_REQUIRED_LIST_VALUES 與 redaction removed-categories table ADMIN_SOURCE_CATALOG_REDACTION_REMOVED_CATEGORIES 維護 deterministic redaction wrapper key allowlist、secrets_removed=true value contract、removed_categories save/load contract、missing/unexpected key fail-closed、tampered secrets_removed fail-closed 與 reordered-category fail-closed；storage allowed key table ADMIN_SOURCE_CATALOG_STORAGE_ALLOWED_KEYS 與 storage required value table ADMIN_SOURCE_CATALOG_STORAGE_REQUIRED_VALUES 共同維護 durable storage wrapper allowlist/value contract（只允許 mode / durable，且必須為 mode=durable_json_v1 / durable=true，tampered mode/durable fail-closed）；contains allowed key table ADMIN_SOURCE_CATALOG_CONTAINS_ALLOWED_KEYS 與 contains required value table ADMIN_SOURCE_CATALOG_CONTAINS_REQUIRED_VALUES 維護 metadata-only contains wrapper allowlist/value contract（只允許 sources count placeholder；save 時以實際 count 覆寫）與 unexpected-key / invalid count / mismatched count fail-closed；source-item allowed key table ADMIN_SOURCE_CATALOG_SOURCE_ITEM_ALLOWED_KEYS 維護每筆 source item wrapper allowlist 與 unexpected-key fail-closed；restart-consistency required value table ADMIN_SOURCE_CATALOG_RESTART_CONSISTENCY_REQUIRED_VALUES 維護 schema_version=source_catalog_restart_consistency_v0 / compare_field=catalog_sha256 / metadata_only=true / paths_hidden=true value contract 與 tampered values fail-closed；並只在 durable save 成功後切換 runtime catalog / Evidence Planner；若 durable save I/O 失敗或 store validation error（例如 duplicate source_id）拒絕 catalog，會 fail closed 回 source_catalog_persist_failed_v0、sources_written=0、不切換 runtime state、audit 只記 metadata-only storage/plan 欄位，避免 save failure 時 imported source 只存在 memory；restore apply 也有 restore durable save failure fail-closed：若 snapshot restore 的 durable source catalog save 失敗，回 source_catalog_restore_persist_failed_v0、restored_sources=0，不切換 runtime catalog / Evidence Planner。service restart 後仍可由 /v1/reality/sources 看到 imported sources。source_catalog_storage 只在 catalog 實際從 durable file 載入或本次成功 durable save 後回 durable_json_v1；若 path 已設定但檔案不存在、schema 不符或無法讀取，會 fallback seed catalog 並回 in_memory_v0，避免誤標示 durable runtime。durable catalog 寫入與啟動載入都會移除 raw feed URL、一般 http(s) URL value、streaming scheme URL-like value（rtsp:// / rtmp:// / ws:// / wss:// / ftp:// / sftp://）、embedded URL-like string value、scheme-relative URL value、bare host/path URL-like value、bare IP host/path URL-like value、API credential、password、token 與 authorization/bearer header hints；initial write-time catalog lstat failure fail-closed guard、initial write-time catalog lstat TypeError fail-closed guard 與 existing write-time catalog lstat TypeError fail-closed guard 會在建立或覆寫既有 catalog 前把 lstat inspection failure 收斂為 source catalog path must be inspectable before write，且既有 durable catalog 覆寫前遇到 TypeError 會保留原 catalog；temporary source catalog symlink guard 會在 payload write 前拒絕 temporary source catalog file must be a regular file；load-time symlink no-follow guard 會在開啟 catalog 讀取前拒絕 source catalog path must not be a symlink before read；load-time parent symlink guard 會在開啟 catalog 讀取前拒絕 source catalog parent directory must not be a symlink before read；ancestor symlink lstat-only scanner guard / ancestor symlink lstat TypeError fail-closed guard 會以 parent lstat 檢查 ancestor symlink，不依賴 Path.is_symlink()；load-time fstat owner/mode recheck 會在 os.open 後再次確認已開啟 fd 仍是 service-user owned、single hard link、owner-only regular file；load-time catalog open fail-closed guard 會在 durable catalog file 無法被 no-follow 開啟時回一致錯誤（source catalog path must be openable before read）；load-time catalog fd close-before-read fail-closed guard 會在 fdopen/read 前 catalog fd 關閉失敗時回一致錯誤（source catalog fd must be closable before read）；load-time catalog read failure fail-closed guard 會在 JSON parse 前 payload read 失敗時回一致錯誤（source catalog file must be readable before parse）；load-time catalog JSON parse fail-closed guard 會將 malformed JSON 統一拒絕為 source catalog JSON must be parseable、load-time catalog UTF-8 decode fail-closed guard（`source catalog file must be valid UTF-8`）；load-time catalog fd/path identity recheck 會在讀取 payload 前比對 path.lstat() 與已開啟 fd，若 catalog path 被換成另一個 inode 會 fail closed（source catalog path changed before read）；post-read catalog fd/path identity recheck 會在 JSON parse 後再次比對已開啟 fd 與 catalog path，若讀取期間 path 被替換會 fail closed（source catalog path changed after read）；post-read catalog fd metadata recheck 會在 JSON parse 後再次確認已開啟 fd 仍是 owner-only regular file，若讀取期間變成 world-readable 會 fail closed（source catalog path must be owner-only readable/writable after read）；post-read parent-dir fd metadata recheck 會在 JSON parse 後再次確認 parent directory fd/path metadata，若讀取期間 parent 變成 group/world-writable 會 fail closed（source catalog parent directory must not be group/world-writable after read）；post-read parent-dir open fail-closed guard / post-read parent-dir open TypeError fail-closed guard / post-read parent-dir close failure fail-closed guard 會在 JSON parse 後若無法重新開啟 parent directory 時 fail closed（source catalog parent directory must be openable after read / source catalog parent directory fd must be closable after read）；post-read catalog fd primary failure precedence guard 會在 JSON parse 後 fd metadata recheck 已有主要錯誤且 close cleanup 也失敗時保留主要錯誤（source catalog fd must be inspectable after read）；post-read catalog close failure fail-closed guard 會在 JSON parse / fd-path recheck / parent recheck 後若 catalog fd close 失敗時 fail closed（source catalog fd must be closable after read）；invalid UTF-8/unreadable catalog text、corrupt JSON、wrong schema、unexpected top-level fields、top-level non-object JSON、non-list sources、non-object source metadata 與 malformed items 會安全忽略並 fallback seed catalog；不擴大到 cameras、clients 或 secrets。Production apply 仍 hard-locked。

能力V0 狀態
Client list / detail可檢視 status、tier、billing profile、allowed endpoints、usage summary
Partner report可從 usage log 產生 client 月報
Suspend / restore / revoke可更新 runtime client status；V0 為 in-memory，重啟後需由 registry/env/DB 持久化
Security需 X-Admin-Key；不可公開 raw usage log、API key、raw CCTV URL

Camera Integration Foundation：攝影機介接基礎

攝影機是大項目，會分階段接入。第一階段先建立安全 registry endpoint：GET /v1/reality/cameras，回傳攝影機候選/白名單狀態，不公開原始 CCTV URL。MVP 的使用者驗證連結 contract 是：提供 public_source_url / public_page_url 作為「查看官方來源頁」入口，並明確回 can_user_verify、verification_label、source_link_policy=public_source_page_only、technical_stream_url_exposed=false；使用者可開公開來源頁自行驗證，但公開來源頁，不是技術取流網址、m3u8、RTSP、thumbnail、signed URL 或任何帶 token 的網址。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras?location_id=alishan"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

第二階段新增第一個 server-side snapshot metadata endpoint：GET /v1/reality/cameras/{camera_id}/snapshot。此 endpoint 只回 snapshot metadata，不回傳影像內容、不公開 raw URL；若尚未在 server 設定來源，會回 configuration_required，但不公開 locator 或 env var 名稱/值。攝影機策略改為歡迎多來源：第一手優先但不阻塞 MVP；YouTube proxy / embed / thumbnail 可作為 source_usage_policy=optional_toggle 的輔助來源，但必須標註 source_lineage、quality profile、evidence tier 與 limitations。camera_l2_official_html_dataset_resolver_v0 會在已白名單官方 data.gov.tw HTML dataset page 中只 follow process-local allowlisted first-party resource link，再交給 JSON resolver 與 CCD identifier / parent-station matching guard；camera_l2_official_camera_html_showone_resolver_v0 只針對已 review 的官方 MOA/ARDSWC camera HTML page，在 process 內解析 same-site displayed frame，再回 L2 snapshot metadata；仍不公開 resource endpoint、raw locator、env/credential、HTML/JSON payload、frame id 或原圖。成功抓到 snapshot 時會回 evidence_scoring，其中 stability_score 會修正來源可信度成 effective_source_trust_score，最後產生 evidence_weight。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/camera_whitelisted_alishan_weather_validation/snapshot"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

第三階段新增 visual observation usable V0 endpoint：GET /v1/reality/cameras/{camera_id}/visual-evidence。目前定義 camera_visual_observation_v0 schema，欄位包含 visible_rain、wet_ground、visibility、cloud_or_fog、crowd_level、traffic_density、water_level_visual_risk、scene_usable、observed_at、fetched_at、confidence、limitations。若 server-side snapshot 可用，runtime 會回 visual_evidence_available / metadata_only_snapshot_available，並附 snapshot_metadata 與 evidence_scoring；若接上安全的 analyzer runtime，會回 camera_ai_visual_analysis_v0 / ai_visual_analysis_available，但只允許 low-risk scene/weather fields only：雨、地面濕、能見度、雲霧等低風險欄位；dry-run analyzer 可由 server-side CAMERA_VISION_DRY_RUN_ENABLED=true 開啟，回 camera_vision_dry_run_v0 / vision_dry_run_available 與 external_call_performed=false、would_call_provider=false、budget_decision、deny_reason，只驗證 pipeline/budget/cache 決策，不呼叫外部 API、不產生成本；Provider fixture analyzer 可由 server-side CAMERA_VISION_PROVIDER_FIXTURE_ENABLED=true 開啟，回 camera_vision_provider_fixture_analyzer_v0、fixture_result_used=true、fixture_analysis_plumbing_verified 與 raw_provider_response_returned=false，只用本地 fixture provider result 測試 adapter parser flow，仍不呼叫外部 API、不產生成本，且不得算 L3 或當成即時畫面判讀；人潮、交通、水位仍可維持 unknown，且不做臉、車牌、個體追蹤。若 snapshot 未設定則誠實回 snapshot_not_available / configuration_required；不回 raw image bytes、不回 raw URL。第三方/proxy 來源只能作 auxiliary_proxy_evidence，不得包裝成第一手或等權重官方 evidence。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/camera_whitelisted_alishan_weather_validation/visual-evidence"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

Camera Vision Provider Status V0：GET /v1/reality/cameras/vision-provider/status 回 camera_vision_provider_status_v0，只報告 provider/model/credential 是否 configured；若 provider/model/key 都有設定但安全 gates 未齊，回 configured_disabled。Camera AI Visual Runtime V0 已支援 OpenAI-compatible external analyzer，但預設 fail-closed；必須同時具備 provider/model/credential、CAMERA_VISION_BUDGET_GUARD_ENABLED=true 與 CAMERA_VISION_EXTERNAL_CALLS_ENABLED=true，且未啟用 fixture/dry-run analyzer，才會進入 runtime_enabled / ai_visual_analysis_available。此 endpoint 本身仍 external_call_performed=false、raw_prompt_hidden=true、raw_image_bytes_returned=false、raw_camera_url_returned=false、credential_value_exposed=false，不輸出 API key、env var name、raw prompt、raw image 或 raw URL。Camera Vision Call Budget Guard V0 以 camera_vision_call_budget_guard_v0 宣告接 vision API 前的成本護欄：enabled=false by default、external_calls_allowed=false by default、max_calls_per_camera_per_hour、cache_ttl_seconds、max_image_bytes、denied_requests_billable=false。Camera Vision Provider Adapter Contract V0 以 camera_vision_provider_adapter_contract_v0 / camera_vision_provider_adapter_request_v0 / camera_weather_scene_prompt_v0 固定 request/prompt/output parser contract，預設 parser_status=contract_ready_no_call、raw_provider_response_returned=false；parser 只接受低風險 weather/scene 欄位，會把人潮、交通、水位、臉、車牌、個體追蹤等欄位丟棄或 forced unknown。Camera Vision Provider Call Preflight Guard V0 以 camera_vision_provider_call_preflight_guard_v0 在任何真外部 call 前 fail-closed；預設 external_call_denied，只有 provider/model/credential configured、fixture_analyzer_verified、budget guard enabled 與 explicit_external_call_enabled 全部為 true 時才會進入 external_call_preflight_passed。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/vision-provider/status"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

第四階段新增 Camera Stability Monitor v0 endpoint：GET /v1/reality/cameras/{camera_id}/stability。欄位包含 fetch_success_rate_24h、fetch_success_rate_7d、median_latency_ms、content_type_consistency、byte_size_consistency、last_success_at、last_failure_at、history_status 與 effective_stability_score。v0 使用 in-memory latest fetch history，所以若尚無長期資料會誠實標示 limited_history；runtime stability 可修正 effective_source_trust_score 與 evidence_weight，但不可作 production SLA。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/camera_whitelisted_alishan_weather_validation/stability"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

第五階段新增 Camera × Official Data Cross-check v0 endpoint：GET /v1/reality/cameras/{camera_id}/cross-check，把原本規劃的氣象交叉驗證擴展為 CWA / radar / satellite / traffic / water/disaster 官方資料 cross-check。目前定義 camera_official_cross_check_v0 contract，狀態 enum 包含 supports_official_observation、contradicts_official_observation、inconclusive、insufficient_data、configuration_required。因尚未啟用真 AI visual observation，runtime 誠實回 insufficient_data / visual_analysis_not_enabled；攝影機只作 visual validation，不取代 CWA、雷達、衛星、交通、水文或防災官方來源。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/camera_whitelisted_alishan_weather_validation/cross-check"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"

第六階段新增 Multi-source Camera Selection v0 endpoint：GET /v1/reality/cameras/select。它依 location_id 與 intent 排序候選鏡頭，schema 為 multi_source_camera_selection_v0；排序因素包含 source trust、visual quality、stability、first-party score、review status、usage policy、evidence tier 與 privacy risk。此 endpoint 只做 candidate ranking，不表示 discovery-only 或 requires-authorization 來源可抓影像。

curl -s "https://taiwanworldmodel.thesense.biz/v1/reality/cameras/select?location_id=alishan&intent=cloud_sea_visual_evidence"   -H "X-API-Key: $TRUESIGHT_REALITY_API_KEY"
階段狀態說明
Quality Profilequality_profile_v0_complete所有已 lineage-reviewed 的來源已補齊 source_trust_score、visual_quality_score、stability_score、first_party_score、latency_risk、stability_risk、resolution_quality、license_certainty、privacy_risk；仍不代表授權完成。
Visual Observation Schemacamera_visual_observation_v0已升級為 visual evidence usable V0；snapshot 可用時回 visual_evidence_available / metadata_only_snapshot_available，但內容判讀仍為 uncertain/unknown，第三方/proxy 僅作 auxiliary_proxy_evidence。
Stability Monitorlimited_history已建立 runtime foundation，可回報成功率、延遲、content-type 與 byte-size 一致性，並以 effective_stability_score 修正 trust/weight；長期 24h/7d 仍需 DB。
Cross-checkcamera_official_cross_check_v0已建立 camera visual evidence × official data contract；尚未啟用 AI 視覺分析時回 insufficient_data / visual_analysis_not_enabled。
Multi-source Selectionmulti_source_camera_selection_v0已建立 location/intent 候選鏡頭排序；不把 discovery_only 或 requires_authorization 來源當成可抓取影像。
Registrycamera_registry_only已可查候選/白名單 metadata，不含 raw URL。
Next milestoneconnect_more_reviewed_snapshot_fetchers下一步將更多已通過授權/隱私/技術審查的來源接到 server-side snapshot fetcher。

Traffic Reality：交通如何測量？

交通不能只用「車速低」判斷。Reality API 會把交通問題拆成 道路可用性、壅塞程度、真卡死/假塞車、資料盲區 四類。

問題主要訊號判斷重點
風災豪雨造成道路不可用封路/事故通報、CMS、VD 車流、CCTV、雨量、水位、地方災情不能把「沒速度資料」直接當成順暢；需判斷封路、資料中斷、或車輛已無法前行。
連假高速公路壅塞VD 車流/車速/占有率、ETag/旅行時間、CMS、交流道回堵、歷史連假 baseline區分短暫降速的假塞車與低速、低流量、排隊長度增加的真卡死。
沒顯示塞車但實際不能動上游/下游偵測點落差、CCTV、事故通報、社群/新聞、資料新鮮度標記為資料盲區或異常阻斷，不把官方未顯示塞車視為道路可用。

互動式文件

安全限制