Handkit 是做什麼的？
手部是 JSON：姿勢是關節角度加上擺放位置；片段是姿勢隨時間的關鍵幀序列；核心引擎將它們轉化為自然動作（彈簧、手指連鎖、跟隨動作、閒置晃動），再由繪圖引擎繪製。一切皆具確定性：相同的片段產生相同的幀。
以下 HANDKIT 代表 Handkit 資料夾（儲存庫根目錄）。請在其中執行命令。
首次使用： 如果尚無 Handkit 資料夾，請先設定（需要 git、Rust 與 FFmpeg；首次建置需幾分鐘，建議背景執行）：
HANDKIT=${HANDKIT:-$HOME/.handkit}
[ -d "$HANDKIT" ] || git clone --depth 1 https://github.com/Ayushmaniar/3d-accurate-hands "$HANDKIT"
cd "$HANDKIT" && cargo build --release -p handkit-cli
(cd starters/fframes-clip && cargo build --release) # 僅在使用 fframes 渲染影片時需要
H=$HANDKIT/target/release/handkit # CLI（執行 cargo build --release 一次）
P=$HANDKIT/starters/fframes-clip/target/release/fframes-clip # 影片播放器
A=$HANDKIT/assets # hand_R.glb, hand_L.glb（手部網格寫入）
工作流程（請依序執行）
- 從手勢庫開始。
$H gestures列出約 50 個命名姿勢與描述（拳頭、 指向、OK、豎拇指、和平手勢、張掌、捏合、愛心手勢、相機取景框、握手……）。 在手部使用"from": "ok"即可採用某個手勢的形狀；幾乎免費。只需撰寫不同的關節角度。 - 撰寫片段（最小化，30 fps）：
{ "version": 1, "fps": 30, "camera": { "position": [0, 0.12, 0.6], "target": [0, 0.1, 0], "fov": 30 }, "look": { "style": "realistic", "skin": "medium" }, "keys": [ { "t": 0, "hands": { "right": { "from": "fist", "place": { "wrist": [0, 0, 0], "palm_facing": [0, 0, 1], "fingers_toward": [0, 1, 0] } } } }, { "t": 0.8, "hands": { "right": { "from": "spread_palm" } } }, { "t": 1.6, "ease": "snappy", "hands": { "right": { "from": "point" } } } ] }t是姿勢到達的時間；move是移動持續時間（0.12 = 快速一揮）；"pass": true讓關鍵幀不暫停直接流過。使用以下方式將手部放置在畫面中："place": {"screen": [x, y], "depth": 0.5, "palm_facing": .., "fingers_toward": ..}（x, y 是畫面比例，0,0 為左上角），並用"elbow_screen": [1.1, 0.9]從畫面邊緣引入手臂。 - 渲染前檢查：
$H check clip.json（檢查接觸碰撞、手指穿透、速度、跳動、構圖、手肘是否在視線內）。依提示修正；它會指出問題所在的關鍵幀。 - 快速低成本的預覽：
$P --clip clip.json --assets $A strip -n 12寫入 strip.png （觀看它）。frame 2.5s寫入一幀完整畫面。 - 渲染：
$P --clip clip.json --assets $A render -o out.mp4（1920x1080，單位秒）。 縱向 1080x1920：使用相同的命令，但換成$HANDKIT/starters/fframes-clip/target-portrait/release/fframes-clip。 背景：--background "#1d1f24"，--spotlight 0.5,0.45,0.35,#3a3f48。
其他可用功能
- 接觸：
"goals": [{"touch": ["right.thumb.tip", "right.index.tip"]}]，然後$H solve pose.json會精確滿足接觸條件（若無法達成則退出碼 2）。瞄準：{"aim": "right.index", "at": [x,y,z]}。 - 外觀： 頂層
"look"：樣式realistic | toon | spiderverse | arcane | clay，膚色light | medium | tan | brown | dark | #rrggbb，outline，motion_blur（子幀）。 也可以在播放器上指定：--look spiderverse,skin=brown。 - 前臂末端： 骨架止於手肘。當手肘會露出時，使用
"look": {"arm": "fade"}或{"arm": {"sleeve": "#1e2a4a", "length": 0.08}}（捲起的袖口）。 - 將 UI 與手部同步：
$H track clip.json --site right.index.tip會輸出每一幀該位置在螢幕上的座標（畫面比例），例如用來讓按鈕對觸碰做出反應。 - 多人： 手部
ana.right，ben.left（任意名稱）；"people": {"ana": {"look": {"skin": "dark"}, "scale": 1}}（scale 0.75 為兒童的手）。 手部會互相推開而不穿透（"collide": false允許重疊）。 - 牽手： 一個目標
{"grip": ["ana.right", "ben.right"], "style": "handshake"}； 樣式有 handshake、interlaced、cupped、high_five、fist_bump、pinky。連續關鍵幀使用相同的握持會讓兩人一起移動，跟隨者延遲數幀。 - 同一人的雙手： 可使用
touch目標來合掌、拍手或構成取景框。
重建參考影片
先仔細研究：ffmpeg -i ref.mp4 -vf fps=4,scale=480:-1 f%03d.png 並閱讀這些幀。每個明顯事件設定一個關鍵幀；使用 screen 放置手部，用 elbow_screen 對準前臂；根據幀數調整時間。比對：python $HANDKIT/tools/motion/compare.py ref.mp4 out.mp4 cmp（產生兩者相同時間點的對照圖，以及一個並排的 MP4）。
需要更多資訊時
$H explain（慣例），$H explain clips，$H explain looks，$H explain <param>
（例如 thumb.cmc_rot），或 $HANDKIT/docs/POSE_SPEC.md。只需閱讀需要的部分。
原始關節範圍：手指 mcp_flex -30..95，pip_flex -5..110，dip_flex -10..85，
mcp_abd 約 -15..25；手腕 wrist_flex -80..85，wrist_dev -35..35。
經驗法則：優先使用手勢庫；關鍵幀少、節奏精準（真實手部移動約 0.2-0.6 秒並保持）；渲染前檢查；先看 strip，不要看整部影片；保持檔案小而精簡。