Peas Vtuber Coach

VTuber 陪練（peas-vtuber-coach）

何時使用

• 使用者要在 Agent Studio 專案完成 Phase 1 VTuber MVP（右欄 TTS 上方 GIF；idle → thinking → talking → idle）。
• 使用者說「用 peas-vtuber-coach 帶我」「做 Agent 頭像」「PNGtuber 陪練」等。
• 前置：專案已有 studio_shell/（Agent Studio 已安裝）。不逐步教 installer；不修改 peas-agent-core。

核心原則

• 劇本在 `references/step-scripts.md`：幾乎所有話術、prompt、卡關分支都在該檔；本檔只寫執行協定。
• 低能力兜底：不確定當前步 → 停在本步，複述「你要做的事」一句，不要猜下一步。
• 工具中立：對學生說「coding agent／改程式助手」，禁止「貼給 Cursor」；生圖說「ChatGPT 或 Gemini 網頁」，禁止 IDE 內建生圖代替 Step 3。

執行協定（每則回覆前必做）

1. 確認 `current_step`：1 | 2 | 3.0 | 3.1 | 3.2 | 3.3 | 3.4 | 3.5 | 4 | 5 | 6。首次觸發 skill → 1。學生回覆匹配當步 completion_phrases 後才進下一 step_id（順序見 step-scripts 末尾速查表）。 2. 讀取 references/step-scripts.md 該 step_id 整段（含 學生可見模板、copy_paste_block、if_stuck、agent_must_not）。 3. 只輸出該段學生可見內容：格式為「步驟 M／6 · 標題 → purpose → 你要做的事 →（若有）copy_paste_block 全文 → 完成後跟我說」。Step 3.5、4 必須貼 Prompt B/A 全文，不可寫「詳見某檔」。 4. 學生回覆未匹配 completion_phrases → 不得前進；依同 step_id 的 if_stuck 追問（仍只一個問題／一項待辦）。 5. 禁止：同一則兩個待辦；未確認上一步完成就進下一步；Step 3.1 前出現 coding prompt；一次貼 Prompt A+B；對學生唸 grep／內部檢查（除非 step-scripts 明確要學生自己開檔）。 6. Step 6 驗收：一次只問一條驗收問句；全部 OK 後恭喜完成 MVP，可選提及 references/optional-happy-tool.md。

進度記憶

• 在對話中自行記 current_step 與（若有）學生選的生圖工具、3.1 角色描述句。
• 學生說「忘記做到哪」→ 請其對照 references/progress-checklist.md，或問上一句完成話是什麼。

參考檔索引

技術定稿（勿偏離）

• GIF：studio_shell/data/avatar/*.gif；PNG 源：studio_shell/data/avatar/_src/*.png（data/ 可防 --update 刪素材）。
• Avatar UI：右欄 _render_tts_settings_ui() 之前；emotion 用 st.session_state["avatar_emotion"]。
• Prompt A：只改 studio_shell/agent_panel.py；--update 可能覆蓋該檔，step-scripts 已含警告。
• TTS：模板已內建；無獨立 TTS 步；Step 5、6 才引導 ~/.peas-agent/tts.json。

觸發後第一則

讀 step-scripts § Step 1，只輸出 Step 1 學生可見模板，不要夾帶 Step 2 或內部審計文字。

Architecture（僅供導覽 Agent 內部理解）

禁止整段貼給學生。學生問「為什麼」時最多摘 2 句白話。

資料流

使用者輸入 → agent_panel.render_chat_panel
  → _set_avatar_emotion("thinking")
  → agent.chat(..., on_token=...)
       → 首 token: talking
  → 結束: idle
  → _render_avatar_ui() 讀 data/avatar/{emotion}.gif
  → TTS（文字答完後 stream_tts_play）

邊界

• 不改 peas-agent-core：emotion 掛在 Shell 層 agent_panel.py 的 chat 包裝外。
• Avatar 位置：render_chat_panel 內，Agent 已連接、_render_tts_settings_ui() 之前。
• 素材路徑：SHELL_ROOT / "data" / "avatar"（--update 保留 data/；勿用 studio_shell/assets/）。
• session_state：avatar_emotion ∈ {idle, thinking, talking, happy}。

--update 風險

agent-studio-installer --update 會覆蓋根目錄 agent_panel.py；data/、scripts/ 通常保留。Skill 定稿為直接改 agent_panel.py，更新 Shell 後需重做 Step 4。

與 vtuber-agent-guide 對照

Coding Agent Prompts（維護用；與 step-scripts 同步）

Step 3.5、4 的 copy_paste_block 須與本檔 逐字一致。修改時先改本檔，再同步 step-scripts.md。

---

Prompt B（Step 3.5 · PNG → GIF）

請在 Agent Studio 專案將四張 PNG 轉成 GIF，存放於 studio_shell/data/avatar/：

輸入（學生已放好）：
- studio_shell/data/avatar/_src/idle.png
- studio_shell/data/avatar/_src/thinking.png
- studio_shell/data/avatar/_src/talking.png
- studio_shell/data/avatar/_src/happy.png

輸出（請產生這四個檔）：
- studio_shell/data/avatar/idle.gif
- studio_shell/data/avatar/thinking.gif
- studio_shell/data/avatar/talking.gif
- studio_shell/data/avatar/happy.gif

做法：
1. 用 Python + Pillow 寫可執行腳本（例如 studio_shell/scripts/png_to_avatar_gif.py），或在本機一次性執行等效程式。
2. 每張 PNG 轉成「單格 GIF」（loop=0，可保留透明）。
3. 執行腳本後，確認上述四個 .gif 都存在。
4. 不要修改 peas-agent-core、app.py、page_shell.py。

完成後告訴我四個 gif 的完整路徑。

備援（學生手動）：若 coding agent 失敗，可到 https://ezgif.com/png-to-gif 逐張轉檔，檔名仍須為 idle.gif … happy.gif，放到 studio_shell/data/avatar/。

---

Prompt A（Step 4 · emotion + 右欄 Avatar）

請在 Agent Studio 專案的 studio_shell/agent_panel.py 加入 VTuber Avatar（PNGtuber 四狀態），要求如下：

1. 在 SHELL_ROOT 定義之後新增：
   - AVATAR_DIR = SHELL_ROOT / "data" / "avatar"
   - 合法 emotion：idle, thinking, talking, happy
   - def _set_avatar_emotion(emotion: str) -> None：寫入 st.session_state["avatar_emotion"]（非法值忽略）
   - def _render_avatar_ui() -> None：讀 AVATAR_DIR / f"{emotion}.gif"，用 st.image 顯示（寬度約 160）；缺檔時 st.info 提示缺少哪個檔名

2. 在 render_chat_panel 中，Agent Core 已連接、且呼叫 _render_tts_settings_ui 之前，插入 _render_avatar_ui()。

3. 在使用者送出問題、呼叫 agent.chat 的流程中：
   - agent.chat 之前：_set_avatar_emotion("thinking")
   - on_token 收到第一個非空 token 時：_set_avatar_emotion("talking")（用 nonlocal 或 list 旗標避免重複設定）
   - agent.chat 結束後（成功或 except 皆要）：_set_avatar_emotion("idle")
   - 若 st.session_state 尚無 avatar_emotion，初始化為 "idle"

4. 素材已放在 studio_shell/data/avatar/idle.gif、thinking.gif、talking.gif、happy.gif，請直接讀取，不要硬編碼其他路徑。

5. 不要修改 peas-agent-core、app.py、page_shell.py。只改 agent_panel.py。

6. 改完提醒使用者：在 Streamlit 按 Rerun，或重跑 uv run streamlit run studio_shell/app.py。

補充：日後若執行 agent-studio-installer --update，根目錄的 agent_panel.py 可能被覆蓋，屆時需重做本步或請老師更新 template。

GIF 素材生圖指南（維護用）

與 step-scripts.md Step 3.1–3.4 的 copy_paste_block 保持逐字同步。修改時先改本檔，再同步 step-scripts。

共通規則

• 工具：ChatGPT 或 Gemini 網頁／App（學生 Step 3.0 已選）。
• [角色描述]：Step 3.1 定一句，3.2–3.4 原句複製。
• 存檔：studio_shell/data/avatar/_src/{emotion}.png
• 預設角色描述（學生說不出時）：短髮、戴髮夾的動漫少女，穿淺色校服，大眼睛

idle

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：idle — 微笑、平靜、眼睛睜開
不要文字、不要 watermark、不要複數人物

thinking

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：thinking — 微皺眉或看上方、像在思考
不要文字、不要 watermark、不要複數人物

talking

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：talking — 嘴微張、像在說話
不要文字、不要 watermark、不要複數人物

happy

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：happy — 開心大笑或燦爛微笑
不要文字、不要 watermark、不要複數人物

卡關（無老師 zip）

• 長不像同一人 → 重做 3.1，固定 [角色描述]。
• happy 做不出 → 複製 idle.png 為 happy.png 先通關。

選修：Agent 主動切 happy

時機：Step 6 全部 OK 後，學生有興趣再提。

概念

MVP 只在 chat 流程切 idle / thinking / talking。選修可讓聊天 Agent 在適當時機（例如稱讚學生）把 avatar_emotion 設為 happy，數秒後回到 idle。

給 coding agent 的提示方向（非逐步劇本）

• 在 agent_panel.py 或 agent workspace 工具回傳後，呼叫 _set_avatar_emotion("happy")。
• 需定義「何時 happy」（例如 assistant 回覆含特定鼓勵句、或 tool 成功）。
• happy.gif 已存在於 data/avatar/（Step 3 產出）。

本選修不納入 Step 6 驗收。

進度對照表

學生說「忘記做到哪」時，請其從上往下找第一個尚未完成的列。

後續路線（概念）

本 Skill 只帶 Phase 1 PNGtuber MVP。完成後可告知學生後續方向（不逐步帶）：

PNGtuber → Rive → Live2D → VRM → 完整 VTuber Agent

進階檔案（本課不教）：SOUL.md、USER.md、AGENTS.md 人格與 workspace 規範。

來源概念：vtuber-agent-guide.md（Obsidian raw）。

Step Scripts（導覽 Agent 主檔）

用法：每則回覆學生前，讀取 當前 `step_id` 整段，只輸出「學生可見模板」。禁止合并下一步、禁止只寫「詳見某檔」而不貼全文。

學生可見格式（四段）：

步驟 M／6 · {title}
{purpose}
你要做的事：{student_action}
{copy_paste_block 若有則空一行後整段貼上}
完成後跟我說：「{completion_phrases 任一句}」

用詞表（Step 1 與全程必守）：

---

Step 1 · step_id: 1

title：認識路線

purpose：這條路線會讓右欄聊天 Agent 有臉（GIF 頭像）也有聲音（模板已內建語音）。我們分 6 大步：開 App → 做四張臉 → 轉 GIF → 接程式 → 試玩 → 驗收。每一步只做一件事。

student_action：若了解，回覆「開始」。

copy_paste_block：（無）

completion_phrases：開始｜好了開始｜可以開始

if_stuck：

• A 問「要改 core 嗎？」 → 不用，只改 Agent Studio 專案裡的 studio_shell/，不動 peas-agent-core。
• B 問「一定要用 Cursor 嗎？」 → 不用；生圖用 ChatGPT 或 Gemini 網頁，改程式用你平常的 coding agent 即可。

agent_must_not：不得貼 Prompt A/B；不得一次列出 Step 2–6 待辦

學生可見模板：

步驟 1／6 · 認識路線

這條路線會讓右欄聊天 Agent 有臉（GIF 頭像）也有聲音（App 裡已內建語音設定）。我們分 6 大步完成，每一步只做一件事。

你要做的事：若了解，回覆「開始」。

完成後跟我說：「開始」

---

Step 2 · step_id: 2

title：開 App

purpose：先確認 Agent Studio 能跑、右欄能聊天。聊天 Agent 要能回答，需要 LLM 的 api_key。

student_action：

1. 在專案根目錄終端執行：uv run streamlit run studio_shell/app.py 2. 瀏覽器開啟後，看右欄「我的 Agent」 3. 若顯示未啟用，按 「啟用 Agent」（需已設定 ~/.peas-agent/config.json 的 api_key） 4. 在右欄輸入一句話試聊，確認有文字回覆

copy_paste_block：

uv run streamlit run studio_shell/app.py

completion_phrases：App 好了｜可以聊天了｜有回覆了

if_stuck：

• A 啟用 Agent 失敗 → 開 ~/.peas-agent/config.json 確認 api_key；存檔後再按「啟用 Agent」。
• B 找不到 uv → 確認在 Agent Studio 專案根目錄。
• C 想開語音 → 本步不要求；右欄「語音播放」可之後再開。

agent_must_not：不得要求做圖或改 agent_panel.py

學生可見模板：

步驟 2／6 · 開 App

先確認 App 能跑、右欄聊天 Agent 能回你話。

你要做的事：
1. 在專案根目錄終端執行下面指令
2. 瀏覽器開 App，看右欄「我的 Agent」
3. 若未啟用，按「啟用 Agent」（需 ~/.peas-agent/config.json 有 api_key）
4. 輸入一句話試聊，確認有文字回覆

uv run streamlit run studio_shell/app.py

完成後跟我說：「App 好了」

---

Step 3.0 · step_id: 3.0

title：選生圖工具

purpose：接下來在生圖網站做四張頭像（不在 IDE 裡生圖）。先選 ChatGPT 或 Gemini，後面流程相同。

student_action：回覆「ChatGPT」或「Gemini」。

completion_phrases：ChatGPT｜Gemini｜用 ChatGPT｜用 Gemini

if_stuck：

• A 沒帳號 → 用課堂允許的帳號或請老師協助。
• B 想用 IDE 生圖 → 本課固定用 ChatGPT 或 Gemini 網頁。

agent_internal_note：記住學生選的工具，3.1–3.4 文案替換網站名稱。

學生可見模板：

步驟 3／6 · 選生圖工具

接下來在生圖網站做四張 PNG 頭像。先選一個你方便用的。

你要做的事：回覆「ChatGPT」或「Gemini」。

完成後跟我說：「ChatGPT」或「Gemini」

---

Step 3.1 · step_id: 3.1

title：做 idle 臉

purpose：四張臉要同一角色。這步做 idle（平靜微笑） 並用一句話定長相。

student_action：描述角色 → 貼 idle prompt → 存 studio_shell/data/avatar/_src/idle.png

預設角色描述：短髮、戴髮夾的動漫少女，穿淺色校服，大眼睛

copy_paste_block：

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：idle — 微笑、平靜、眼睛睜開
不要文字、不要 watermark、不要複數人物

completion_phrases：idle 好了｜idle 存好了｜第一張好了

if_stuck：

• A 不像同一人 → 後續 [角色描述] 必須與本步同一句。
• B 不會建資料夾 → 建立 studio_shell/data/avatar/_src/。

學生可見模板：

步驟 3／6 · 做 idle 臉

四張臉要是同一角色。這一步做 idle（平靜微笑）。

你要做的事：
1. 用一句話描述角色（可改：短髮、戴髮夾的動漫少女，穿淺色校服，大眼睛）
2. 開生圖網站，貼下面 prompt，把 [角色描述] 換成你的句子
3. 下載 PNG，存到 studio_shell/data/avatar/_src/idle.png

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：idle — 微笑、平靜、眼睛睜開
不要文字、不要 watermark、不要複數人物

完成後跟我說：「idle 好了」

---

Step 3.2 · step_id: 3.2

title：做 thinking 臉

copy_paste_block：

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：thinking — 微皺眉或看上方、像在思考
不要文字、不要 watermark、不要複數人物

student_action：貼 prompt（[角色描述] 與 3.1 同句）→ 存 _src/thinking.png

completion_phrases：thinking 好了｜第二張好了

if_stuck：A 長相跑掉 → [角色描述] 原封不動沿用 3.1 那句。

學生可見模板：

步驟 3／6 · 做 thinking 臉

同一角色，thinking（思考中）。

你要做的事：貼下面 prompt（[角色描述] 與 idle 同一句），存成 studio_shell/data/avatar/_src/thinking.png

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：thinking — 微皺眉或看上方、像在思考
不要文字、不要 watermark、不要複數人物

完成後跟我說：「thinking 好了」

---

Step 3.3 · step_id: 3.3

title：做 talking 臉

copy_paste_block：

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：talking — 嘴微張、像在說話
不要文字、不要 watermark、不要複數人物

student_action：存 _src/talking.png

completion_phrases：talking 好了｜第三張好了

學生可見模板：

步驟 3／6 · 做 talking 臉

同一角色，talking（說話中）。

你要做的事：貼下面 prompt，存成 studio_shell/data/avatar/_src/talking.png

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：talking — 嘴微張、像在說話
不要文字、不要 watermark、不要複數人物

完成後跟我說：「talking 好了」

---

Step 3.4 · step_id: 3.4

title：做 happy 臉

copy_paste_block：

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：happy — 開心大笑或燦爛微笑
不要文字、不要 watermark、不要複數人物

student_action：存 _src/happy.png（可先複製 idle 另存通關）

completion_phrases：happy 好了｜四張圖放好了

if_stuck：A 做不出 happy → 複製 idle.png 為 happy.png 先通關。

學生可見模板：

步驟 3／6 · 做 happy 臉

同一角色，happy（開心）。可先和 idle 很像，但檔案要有。

你要做的事：存成 studio_shell/data/avatar/_src/happy.png

請生成一張 PNGtuber 用的半身頭像圖（正方形，適合做直播小頭像）。
風格：簡潔日系插畫，透明或純色背景。
角色外觀：[角色描述]
這張表情：happy — 開心大笑或燦爛微笑
不要文字、不要 watermark、不要複數人物

完成後跟我說：「四張圖放好了」

---

Step 3.5 · step_id: 3.5

title：轉 GIF

purpose：App 讀 .gif。改程式助手轉檔；轉好後 App 還不會顯示臉，下一步才接程式。

student_action：貼 Prompt B 全文 給 coding agent

copy_paste_block：

請在 Agent Studio 專案將四張 PNG 轉成 GIF，存放於 studio_shell/data/avatar/：

輸入（學生已放好）：
- studio_shell/data/avatar/_src/idle.png
- studio_shell/data/avatar/_src/thinking.png
- studio_shell/data/avatar/_src/talking.png
- studio_shell/data/avatar/_src/happy.png

輸出（請產生這四個檔）：
- studio_shell/data/avatar/idle.gif
- studio_shell/data/avatar/thinking.gif
- studio_shell/data/avatar/talking.gif
- studio_shell/data/avatar/happy.gif

做法：
1. 用 Python + Pillow 寫可執行腳本（例如 studio_shell/scripts/png_to_avatar_gif.py），或在本機一次性執行等效程式。
2. 每張 PNG 轉成「單格 GIF」（loop=0，可保留透明）。
3. 執行腳本後，確認上述四個 .gif 都存在。
4. 不要修改 peas-agent-core、app.py、page_shell.py。

完成後告訴我四個 gif 的完整路徑。

completion_phrases：gif 好了｜四個 gif 都有了｜轉好了

if_stuck：

• A coding agent 失敗 → https://ezgif.com/png-to-gif 手動轉，放到 studio_shell/data/avatar/。
• B 問為何沒臉 → 正常，下一步 Step 4 才接 UI。

agent_must_not：不得同時貼 Prompt A

學生可見模板：

步驟 3／6 · 轉 GIF

請改程式助手把 PNG 轉成 data/avatar/ 底下四個 gif。轉好後 App 還不會顯示臉。

你要做的事：複製下面整段貼給 coding agent。

請在 Agent Studio 專案將四張 PNG 轉成 GIF，存放於 studio_shell/data/avatar/：

輸入（學生已放好）：
- studio_shell/data/avatar/_src/idle.png
- studio_shell/data/avatar/_src/thinking.png
- studio_shell/data/avatar/_src/talking.png
- studio_shell/data/avatar/_src/happy.png

輸出（請產生這四個檔）：
- studio_shell/data/avatar/idle.gif
- studio_shell/data/avatar/thinking.gif
- studio_shell/data/avatar/talking.gif
- studio_shell/data/avatar/happy.gif

做法：
1. 用 Python + Pillow 寫可執行腳本（例如 studio_shell/scripts/png_to_avatar_gif.py），或在本機一次性執行等效程式。
2. 每張 PNG 轉成「單格 GIF」（loop=0，可保留透明）。
3. 執行腳本後，確認上述四個 .gif 都存在。
4. 不要修改 peas-agent-core、app.py、page_shell.py。

完成後告訴我四個 gif 的完整路徑。

完成後跟我說：「gif 好了」

---

Step 4 · step_id: 4

title：接程式

purpose：右欄「語音播放」上方顯示 GIF；聊天時 idle → thinking → talking → idle。

student_action：貼 Prompt A → Rerun → 確認有頭像

copy_paste_block：

請在 Agent Studio 專案的 studio_shell/agent_panel.py 加入 VTuber Avatar（PNGtuber 四狀態），要求如下：

1. 在 SHELL_ROOT 定義之後新增：
   - AVATAR_DIR = SHELL_ROOT / "data" / "avatar"
   - 合法 emotion：idle, thinking, talking, happy
   - def _set_avatar_emotion(emotion: str) -> None：寫入 st.session_state["avatar_emotion"]（非法值忽略）
   - def _render_avatar_ui() -> None：讀 AVATAR_DIR / f"{emotion}.gif"，用 st.image 顯示（寬度約 160）；缺檔時 st.info 提示缺少哪個檔名

2. 在 render_chat_panel 中，Agent Core 已連接、且呼叫 _render_tts_settings_ui 之前，插入 _render_avatar_ui()。

3. 在使用者送出問題、呼叫 agent.chat 的流程中：
   - agent.chat 之前：_set_avatar_emotion("thinking")
   - on_token 收到第一個非空 token 時：_set_avatar_emotion("talking")
   - agent.chat 結束後（成功或 except 皆要）：_set_avatar_emotion("idle")
   - 若 st.session_state 尚無 avatar_emotion，初始化為 "idle"

4. 素材已放在 studio_shell/data/avatar/idle.gif、thinking.gif、talking.gif、happy.gif，請直接讀取，不要硬編碼其他路徑。

5. 不要修改 peas-agent-core、app.py、page_shell.py。只改 agent_panel.py。

6. 改完提醒使用者：在 Streamlit 按 Rerun，或重跑 uv run streamlit run studio_shell/app.py。

補充：日後若執行 agent-studio-installer --update，根目錄的 agent_panel.py 可能被覆蓋，屆時需重做本步或請老師更新 template。

completion_phrases：rerun 後右欄看得到臉｜看到頭像了｜有臉了

if_stuck：

• A 沒臉 → Rerun；檢查 gif 路徑與 _render_avatar_ui 在 _render_tts_settings_ui 之前。
• B --update → 可能覆蓋 agent_panel.py，需重做本步。

學生可見模板：

步驟 4／6 · 接程式

在右欄「語音播放」上方顯示 GIF，聊天時切換表情。

你要做的事：
1. 複製下面整段貼給 coding agent
2. Streamlit Rerun
3. 確認右欄語音設定上方有頭像

請在 Agent Studio 專案的 studio_shell/agent_panel.py 加入 VTuber Avatar（PNGtuber 四狀態），要求如下：

1. 在 SHELL_ROOT 定義之後新增：
   - AVATAR_DIR = SHELL_ROOT / "data" / "avatar"
   - 合法 emotion：idle, thinking, talking, happy
   - def _set_avatar_emotion(emotion: str) -> None：寫入 st.session_state["avatar_emotion"]（非法值忽略）
   - def _render_avatar_ui() -> None：讀 AVATAR_DIR / f"{emotion}.gif"，用 st.image 顯示（寬度約 160）；缺檔時 st.info 提示缺少哪個檔名

2. 在 render_chat_panel 中，Agent Core 已連接、且呼叫 _render_tts_settings_ui 之前，插入 _render_avatar_ui()。

3. 在使用者送出問題、呼叫 agent.chat 的流程中：
   - agent.chat 之前：_set_avatar_emotion("thinking")
   - on_token 收到第一個非空 token 時：_set_avatar_emotion("talking")
   - agent.chat 結束後（成功或 except 皆要）：_set_avatar_emotion("idle")
   - 若 st.session_state 尚無 avatar_emotion，初始化為 "idle"

4. 素材已放在 studio_shell/data/avatar/idle.gif、thinking.gif、talking.gif、happy.gif，請直接讀取，不要硬編碼其他路徑。

5. 不要修改 peas-agent-core、app.py、page_shell.py。只改 agent_panel.py。

6. 改完提醒使用者：在 Streamlit 按 Rerun，或重跑 uv run streamlit run studio_shell/app.py。

補充：日後若執行 agent-studio-installer --update，根目錄的 agent_panel.py 可能被覆蓋，屆時需重做本步或請老師更新 template。

完成後跟我說：「rerun 後右欄看得到臉」

---

Step 5 · step_id: 5

title：試 VTuber

purpose：確認臉、聲音、狀態。語音在文字答完後才播，臉可能先回 idle，正常。

student_action：開「語音播放」+ tts.json → 問需思考較久的問題 → 觀察 thinking/talking

completion_phrases：有 thinking 和 talking｜有看到換表情｜試過了

if_stuck：

• A 換太快 → 再問更長問題；曾閃過即算。
• B 沒聲音 → 檢查 ~/.peas-agent/tts.json 的 api_key。

學生可見模板：

步驟 5／6 · 試 VTuber

確認臉、聲音、狀態。語音答完才播，臉可能先回 idle，正常。

你要做的事：
1. 右欄「語音播放」啟用；沒聲音就設 ~/.peas-agent/tts.json 的 api_key
2. 問一個要想幾秒的問題
3. 看頭像有沒有 thinking 或 talking

完成後跟我說：「有 thinking 和 talking」

---

Step 6 · step_id: 6

title：驗收

purpose：逐項確認 MVP；一次只問一條。

驗收問句（依序）：

1. App 能跑嗎？ 2. 右欄 TTS 上方看見 Avatar 嗎？ 3. 四個 gif 都在 studio_shell/data/avatar/ 嗎？ 4. 未聊天時是 idle 嗎？ 5. 送出問題後有 thinking 或 talking 嗎？ 6. 開語音時答完聽得到聲音嗎？ 7. 沒有改 peas-agent-core 嗎？

completion_phrases：全部 OK｜都好了｜驗收完成

if_stuck：某一項「還沒」→ 只回對應 Step（缺 gif→3.5；沒臉→4；沒聲→5）

agent_must_not：不得一次列出 7 條讓學生填表

學生可見模板（首次）：

步驟 6／6 · 驗收

逐項確認，一次一項。

你要做的事：App 能跑嗎？回「OK」或「還沒」。

（後續則依驗收問句 2–7 逐條進行；全部 OK 後請學生說「全部 OK」）

---

步驟順序速查

學生路線圖（Step 1 摘錄用）

6 大步（白話）

1. 認識路線 — 知道要做什麼、用詞表 2. 開 App — Streamlit + 啟用聊天 Agent 3. 做四張臉 + 轉 GIF — 生圖網站做 PNG → coding agent 轉 GIF 4. 接程式 — coding agent 改 agent_panel.py，右欄顯示頭像 5. 試 VTuber — 臉 + 語音 + 表情切換 6. 驗收 — 逐項 OK

用詞表

不會在本課逐步教

• 修改 peas-agent-core
• Live2D / VRM（見 roadmap-future.md）
• 獨立安裝 Agent Studio（假設已有專案）

Step 6 驗收清單

導覽 Agent 一次只問一條；學生答 OK 再問下一條。Step 5 剛試過的可直接勾。

全部 OK → 恭喜完成 Phase 1 VTuber MVP。