# 交辦文件：修復 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`
