Arcrun/docs/HANDOFF-mira-repair.md

交辦文件：修復 Mira 的 arcrun workflow（給 Mira 的 CC）

建立：2026-06-03（由 arcrun 端的 CC 撰寫） 對象：接手修復 mira 的 CC 位置：/Users/youlinhsieh/Documents/tech_projects/InkStoneCo/polaris/mira/arcrun/*.yaml

這份文件已把調查做完：每個 workflow 用的 component 都對照過 arcrun prod 現況， 標清楚「哪些不用改、哪些要改、哪些要降級」。你照著改即可，不必重跑調查。

---

0. 為什麼 mira 壞了（一句話）

arcrun 做了大整修：把「打固定 endpoint 卻被做成零件」的假零件降級成 recipe + 刪掉零件目錄 （33 → 22 個零件，DECISIONS §1：零件 = endpoint 薄殼，打固定 API 的是 recipe 不是零件）。 mira 當初自己把一堆東西錯做成假零件，整修後那些零件名的解析方式變了，所以 mira workflow 斷了。

好消息：arcrun prod（cypher.arcrun.dev）活著、降級後的 recipe 都在 KV（已驗證）， mira 大部分 workflow 只需小改，不需重寫。

---

1. 前提（已驗證，你不用重查）

• ✅ cypher-executor prod 活著（cypher.arcrun.dev）
• ✅ 降級 recipe 在 prod KV：kbdb_get / kbdb_create_block / kbdb_patch_block / kbdb_ingest / kbdb_delete / telegram_send / gmail_send / google_sheets_* / line_notify_send
• mira 跑在你（richblack）的 prod 帳號上，不依賴 self-host installer（那是給外部工程師的另一條線）

---

2. 逐 component 分類（mira 6 個 workflow 全部掃過）

component	狀態	動作
kbdb_get	✅ prod recipe 存在	不用改（component: kbdb_get 走解析鏈 step 6 查 recipe:kbdb_get，正確）
kbdb_create_block	✅ prod recipe 存在	不用改
kbdb_patch_block	✅ prod recipe 存在	不用改
cron	✅ 引擎能力	不用改
http_request	✅ primitive	不用改
if_control / set / filter	✅ primitive	不用改
trigger_workflow	✅ 平台 orchestration	不用改
comp_passthrough	✅ 引擎內建純函式（constants.ts:43 (ctx)=>ctx）	不用改
telegram	⚠️ prod 沒有 telegram recipe，只有 telegram_send	要改：component: telegram → component: telegram_send（見 §3）
claude_api	❌ 錯做成零件（非薄殼）	要降級（見 §4）
kbdb_upsert_block	❌ 錯做成零件（非薄殼）	要降級（見 §4）

---

3. 要改：telegram → telegram_send

影響的檔（4 個用到 component: telegram）：

• project_detector.yaml
• agent_feedback_weekly_review.yaml
• wiki_synthesis.yaml
• wiki_giveup_scanner.yaml

改法：把 component: telegram 改成 component: telegram_send。

⚠️ 不只是改名——telegram_send recipe 的介面：endpoint 是 https://api.telegram.org/bot{{auth.bot_token}}/sendMessage，body 帶 chat_id + text， auth 走 auth_service: telegram（static_key path 注入）。確認 mira 的節點 config 傳的是 chat_id / text，且有設好 telegram 的 credential（acr creds push）。

---

4. 要降級：claude_api / kbdb_upsert_block（錯做成零件）

⚠️ 這兩個不是「待刪」，是「做錯了」（richblack 2026-06-03 定性）： 它們不是 endpoint 薄殼，是把工作流硬塞進零件（違反 DECISIONS §1）。 arcrun 已把這兩個 wasm 排除在 self-host 部署來源外（不 commit 進 repo）。 mira 要把它們還原成本來該有的樣子：工作流 / recipe。

4.1 claude_api（影響：agent_feedback_weekly_review / project_detector / wiki_synthesis）

問題：arcrun 是「AI 呼叫的工具」，工作流裡不該有零件回頭呼叫 LLM（mindset §2 / DECISIONS：n8n 需要 AI 節點是因為它沒大腦，arcrun 的大腦就是操盤的 CC）。 claude_api 把「呼叫 Claude」做成零件，方向就錯了。

正解（mira 要自己設計，arcrun 端只給方向）：

• 需要 AI 判斷/轉換的步驟，應該是操盤的 CC（mira 自己）做，再呼叫 workflow 做確定性的下一步。
• 若真的需要在 workflow 內打 Claude API（例如非同步 cron 場景無 CC 在場），那它是打一個固定外部 endpoint（api.anthropic.com）= recipe，不是零件 → 建一個 claude_api 的 API recipe （http_request + endpoint + auth_service），不是零件目錄。
• 哪條對，mira 的 CC 要依 mira 的實際場景判斷（這是 mira 的設計決策，不是 arcrun 能替決的）。

4.2 kbdb_upsert_block（影響：agent_feedback_weekly_review / wiki_synthesis）

問題：upsert 的邏輯（找到則 PATCH、沒找到則 POST）被整段塞進零件。 按 DECISIONS §1，upsert 應該是 KBDB API 那邊提供的 endpoint，零件/recipe 只該「驅動它」。

正解（兩條，mira/KBDB 端決定）：

• 首選：KBDB API 出一個 POST /blocks/upsert endpoint（richblack 已交 KBDB feature request） → 然後在 arcrun 建一個 kbdb_upsert recipe（打那個 endpoint），mira workflow 用 recipe。
• 過渡：若 KBDB 還沒出 upsert endpoint，把「GET 找 → 有則 kbdb_patch_block、無則 kbdb_create_block」 這段用 workflow 表達（mira workflow 層用 if/branch 串現有的 kbdb_get + patch + create recipe）， 而不是塞進一個零件。

---

5. 修復順序建議

1. 先改 telegram（§3）——機械改名 + 確認介面，最快，4 個檔。
2. 驗證 kbdb_ / 其他不用改的 workflow 真的跑通*——acr run <workflow> 或 trigger， 確認 §2 標「不用改」的真的 2xx（誠實驗證，不假設）。
3. 再處理 claude_api / kbdb_upsert_block 降級（§4）——這兩個要 mira 依場景做設計決策，較花時間。

6. 驗收（客觀證據，mindset §7）

• 改完的 workflow acr run / trigger → HTTP 2xx + execution trace 證明跑通，不是口頭宣布。
• claude_api / kbdb_upsert_block 降級後：workflow 不再引用這兩個零件名（grep 確認）。
• 缺 credential 打不通就誠實標「未驗收：缺 X」，不 mock 充綠燈。

---

7. 參考

• arcrun 決策：matrix/arcrun/DECISIONS.md（§1 零件 vs recipe、§3b credential）
• arcrun mindset：matrix/arcrun/.claude/rules/06-mindset.md（§1 工作流是 default、§2 AI→工具）
• arcrun 故障/整修脈絡：matrix/arcrun/docs/HANDOFF-self-host-harness.md