開發居家練習遊戲

第三方遊戲可使用 RehabBuilder 製作原生 HTML／ZIP，或沿用 jsPsych 8 與平台橋樑。原生投稿包含 settings.json 與 score.json；內建遊戲仍由倉庫貢獻者維護。

原生遊戲可用 RehabBuilder 視覺化製作並匯出 Hub 相容套件。正式投稿仍須檢查活動內容、原始碼、安全限制與結果解釋。

1. 01

   規劃活動

   定義任務需求、刺激參數、輸入方式、停止條件、彙總指標與用途限制。

2. 02

   使用 RehabBuilder

   在 Builder 製作與試玩活動，匯出含 settings.json 與 score.json 的套件；公開服務仍須部署。

3. 03

   核對活動設計卡

   確認每個結果欄位的公式、單位、分母與可能混淆因素，並標明尚未驗證的用途。

4. 04

   產生並驗證

   Hub 套件須含 index.html、settings.json 與可閱讀的原始碼；檢查正常完成、中止與結果數值。

5. 05

   送審前複核

   確認雙語、鍵盤／觸控、無外連、無個資、未混淆、沒有自行打包平台 runtime，再建立新版本投稿。

倉庫開發環境

以下本機環境與 AI Agent 指引供倉庫內建遊戲貢獻者使用；一般投稿者不必安裝 SDK。

這些工具只需安裝一次。NVM 管理 Node.js 版本；Node.js 會提供 npm；Git 保存本機版本歷史；GitHub 與 GitHub CLI（gh）負責遠端倉庫、登入、fork 與 pull request。

四個工具各自負責什麼

NVM

切換不同專案所需的 Node.js 版本。Windows 使用 NVM for Windows；macOS、Linux 與 WSL 使用 nvm-sh，兩者不是同一套程式。

Node.js + npm

執行建置、測試與本機伺服器。本倉庫要求 Node.js 22 以上，並以 packageManager 鎖定 npm 11.19.0。npm 隨 Node.js 安裝，再升級到專案指定版本。

Git

建立分支、比較變更與保留可回復的 checkpoint。AI Agent 修改前應先確認 git status，且不得把密鑰或個資加入 commit。

GitHub + gh

GitHub 保存遠端倉庫；gh 在終端機完成瀏覽器登入、clone、fork 與 pull request。登入憑證交由系統 credential store 保存，不寫進專案檔案。

# PowerShell
winget install --id Git.Git -e --source winget
winget install --id GitHub.cli --source winget

# Download and run nvm-setup.exe from the official Releases page,
# then reopen PowerShell. Use an Administrator shell for nvm install/use.
nvm install lts
nvm use lts
npm install --global [email protected]

# macOS with Homebrew
brew install git gh

# Ubuntu, Debian, or WSL (install gh from its official guide)
sudo apt update
sudo apt install git curl

# macOS, Linux, or WSL: install nvm-sh
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.7/install.sh | bash
. "$HOME/.nvm/nvm.sh"
command -v nvm
nvm install --lts
nvm use --lts
npm install --global [email protected]

設定 Git 身分並連接 GitHub

先建立 GitHub 帳號。Git 的 user.name 與 user.email 會寫入 commit 作者資訊；如不想公開私人信箱，可使用 GitHub 提供的 noreply 信箱。gh auth login --web 會啟動瀏覽器驗證。沒有上游倉庫寫入權限時，請先 fork 再從自己的 fork 建立分支。

git config --global user.name "YOUR NAME"
git config --global user.email "YOUR_GITHUB_EMAIL"

gh auth login --web
gh auth status
gh repo clone ian030590/RehabTrainerHub
cd RehabTrainerHub

下載倉庫、安裝依賴並啟動

在倉庫根目錄核對版本後使用 npm ci，不要以 npm install 任意改寫 lockfile。第一次先跑平台契約測試，再啟動 Hub；本機開發網址以終端機輸出為準。

node --version  # v22 or later
npm --version   # 11.19.0
git --version
gh --version

npm ci --workspaces --include-workspace-root
npm run test:game-platform
npm run dev:hub

• 每次開新終端機都先確認 node --version 與 npm --version；Node.js 必須至少為 22，npm 應為 11.19.0。
• Windows 的 NVM for Windows 與 macOS／Linux 的 nvm-sh 指令細節不同；不要同時安裝兩者。
• 如果只製作第三方 HTML／ZIP，可以建立獨立 Git 倉庫；要修改內建遊戲或執行完整 gate，才需要 clone 本倉庫。

官方安裝與驗證資料

OpenAI 官方 Codex CLI 可在終端機讀取、修改與執行目前資料夾中的程式碼。安裝方式可能隨平台更新，請以官方安裝頁的作業系統分頁為準。

npm install -g @openai/codex
codex --version

cd path/to/your-game
codex

• 首次執行 codex 時依畫面使用 ChatGPT 帳號或可用的驗證方式登入。
• 先建立 Git checkpoint；只授權 Agent 存取這個專案資料夾。
• 把本頁「AI 結構化提示詞」產生的內容貼給 Agent，再要求它先回報缺少的規格。
• AI 產生的研究敘述、引用、分數公式與無障礙行為都必須由人員查核。

Hub 只負責設定表單、容器、登入紀錄與離開流程。第三方程式在獨立網域的 sandbox="allow-scripts" iframe 執行，無法讀取主平台 Cookie；平台以 MessageChannel 傳送已驗證設定與接收彙總結果。

責任邊界

遊戲擁有

jsPsych timeline、自訂 plugin、renderer／canvas lifecycle、刺激規則、回饋與彙總公式。

Hub 擁有

設定表單、語言、容器、結果外框、登入狀態、紀錄寫入與離開操作。

執行站擁有

CSP、iframe 隔離、版本化 runtime、PWA scope、撤回版本與私有通訊橋樑。

ZIP 的 index.html 與 settings.json 必須直接位於根目錄。所有圖片、音效、字型、CSS、自訂 plugin 與程式碼都放在套件內，路徑只能使用 ASCII 字母、數字、點、底線、連字號與斜線。

index.html
settings.json
game.js
styles.css
assets/
  stimulus.png
  correct.wav

• 上傳檔最多 12 MiB；解壓縮後最多 24 MiB；單檔最多 8 MiB。
• 最多 192 個檔案；可執行與文字原始碼合計最多 4 MiB。
• 提交可閱讀、未壓縮、未混淆的原始碼；單行不得超過 5,000 字元。
• 不要加入 manifest、service worker、jsPsych 或平台通訊橋樑；執行站會提供。
• 原生套件必須提供 score.json，並透過私有通道回傳數值結果；舊版 jsPsych 套件沿用橋樑，不需要 score.json。

settings.json 是兩條開發路徑都需要的宣告。Hub 在建立 iframe 前驗證它，並將使用者選擇的值傳給遊戲。遊戲內不得再複製一份設定畫面。

• schemaVersion 固定為 1，gameId 必須與遊戲 slug／資料夾名稱完全相同。
• 文字必須同時提供 zh-TW 與 en；最多 16 個 section、64 個欄位、64 KiB JSON。
• 支援 slider、list、checkbox、color。slider 的 default 必須落在 min／max 且符合 step。
• key 以小寫英文字母開頭，可含英數、點、底線與連字號；禁止 auth、email、name、token、user 等敏感名稱。
• 只放本次活動需要的刺激與操作參數，不放自由文字、網址、帳號或健康資料。

{
  "schemaVersion": 1,
  "gameId": "target-selection",
  "sections": [
    {
      "id": "activity",
      "title": {
        "zh-TW": "活動設定",
        "en": "Activity settings"
      },
      "fields": [
        {
          "key": "rounds",
          "type": "slider",
          "label": {
            "zh-TW": "回合數",
            "en": "Rounds"
          },
          "default": 20,
          "min": 5,
          "max": 40,
          "step": 5,
          "unit": {
            "zh-TW": "回合",
            "en": "rounds"
          }
        },
        {
          "key": "soundEnabled",
          "type": "checkbox",
          "label": {
            "zh-TW": "聲音回饋",
            "en": "Sound feedback"
          },
          "default": true
        }
      ]
    }
  ]
}

欄位選擇

slider

有上下界與可解釋步距的數值，例如回合數或刺激呈現時間。

list

有限且互斥的條件；不同條件會改變活動需求時，應在結果解釋中分開比較。

checkbox

可獨立開關的非必要功能，例如聲音回饋。

color

六位十六進位色碼；不可用來編碼診斷或能力等級。

原生投稿與內建遊戲使用 score.json，宣告遊戲結果的數值／布林欄位如何呈現為表格、圖表與摘要；計分公式由遊戲執行。

• schema 固定為 rehab-trainer.game-score/v1；gameId 與 settings.json 相同。
• columns 與 summary 各 1–12 欄，每欄提供 key、zh／en label 與 sources；unit、total 可省略。
• presentation 指定 1–4 個主要摘要、最多 4 個品質／情境欄位、預設每回合指標與 line／bar 圖。
• 只接受有限數值、布林或 null；最多 4,000 回合、450 KiB，數值絕對值不得超過 10¹²。
• 不同構念不得合併成同一來源；反應時間、正確率、完成量與品質指標應分欄並保留單位。

{
  "schema": "rehab-trainer.game-score/v1",
  "gameId": "target-selection",
  "presentation": {
    "primarySummaryKeys": ["accuracy", "medianResponseMs"],
    "qualitySummaryKeys": ["omissions"],
    "defaultRoundMetricKey": "responseMs",
    "chartType": "line"
  },
  "columns": [
    {
      "key": "correct",
      "label": { "zh": "正確", "en": "Correct" },
      "sources": ["correct"]
    },
    {
      "key": "responseMs",
      "label": { "zh": "反應時間", "en": "Response time" },
      "sources": ["responseMs"],
      "unit": "ms"
    }
  ],
  "summary": [
    {
      "key": "accuracy",
      "label": { "zh": "正確率", "en": "Accuracy" },
      "sources": ["accuracy"],
      "unit": "%"
    },
    {
      "key": "medianResponseMs",
      "label": { "zh": "反應時間中位數", "en": "Median response time" },
      "sources": ["medianResponseMs"],
      "unit": "ms"
    },
    {
      "key": "omissions",
      "label": { "zh": "遺漏次數", "en": "Omissions" },
      "sources": ["omissions"]
    }
  ]
}

本節適用舊版 jsPsych 投稿：執行站提供 jsPsych 8.2.3 與版本化橋樑。原生 HTML 投稿可使用自己的程式碼，透過隔離執行站的私有 MessagePort 接收設定與回傳結果。

固定 runtime 路徑

/runtime/jspsych-8.2.3.js
/runtime/jspsych-8.2.3.css
/runtime/trainerhub-game-bridge-1.0.0.js

summarize() 可回傳

• status：completed 或 aborted。
• score：有限數值；durationMs：0 到 24 小時的安全整數。
• trialCount：0 到 100,000 的安全整數。
• metrics：最多 512 個數值、布林或 null；總結果最多 16,000 UTF-8 bytes。
• 禁止姓名、帳號、email、participant、session、token、原始 trial、影像、聲音或動作軌跡。

實作重點

1. 私有通道在 iframe 載入後建立；匯出套件須等待通道與已驗證設定。
2. 自訂 canvas／renderer 應放在單一 jsPsych plugin 內，並在 finish 或 abort 路徑解除 listener 與釋放資源。
3. timeline(settings) 只使用已驗證設定；summarize(jsPsych, settings) 只產生非識別彙總值。

一個看似簡單的遊戲可能同時要求視覺搜尋、持續注意、反應抑制、動作速度與裝置操作。文件與結果只能描述實際任務，不可由遊戲表現推論疾病、日常功能或治療效果。

建議隨程式碼保存的活動規格

• 目標活動需求與非目標需求
• 適用輸入裝置與操作姿勢
• 每回合程序與隨機化方式
• 設定值範圍及選擇理由
• 結果公式、單位與限制
• 練習／中止／錯誤處理
• 雙語可見文字
• 來源與最後查核日期

1. 使用 main、h1–h3、p、button、ol／ul 等語意元素；不要用 div 模擬按鈕。
2. 所有操作可由鍵盤完成，焦點清楚可見；不要只靠顏色、聲音或動態表達狀態。
3. 指標目標至少 44 × 44 CSS px，避免要求精細拖曳；提供等效點按或鍵盤方式。
4. 支援 prefers-reduced-motion；閃爍不得超過安全頻率，時間限制應可在活動規格允許時調整。
5. 指示文字採短句並在操作前呈現；錯誤回饋說明發生什麼與下一步，不責備使用者。
6. 測試 200% 縮放、手機直／橫向、觸控、鍵盤與螢幕閱讀器基本流程。

掃描只是初步分類，不是安全邊界。通過掃描後仍會在無敏感憑證的隔離環境進行原始碼查核與人工試玩。

網路與外部內容

fetch、XHR、WebSocket、EventSource、sendBeacon、WebRTC、http(s) URL、CSS @import。

導頁與瀏覽器狀態

document.cookie、location、window.top、window.open、history navigation、表單與超連結。

動態與背景執行

eval、Function、atob／btoa、Reflective access、ServiceWorker、Worker、SharedWorker、importScripts。

巢狀內容

iframe、frame、object、embed、base、meta refresh 與動態 document.write。