chore: D22 落地——docs/SDD/wiki/CLAUDE.md 進 repo（Gitea private 預設全 push）
頂層 D22 決策（leo 2026-07-03 拍板）：推什麼由開發環境歸屬決定， Gitea private＝除機敏值/build 產物/.github 外全 push。 解 T1.5 卡點：雲端工人 clone 拿得到 credential-store-migration.md，可就地改寫 SDD。 機敏掃描兩輪通過（新增 189 檔約 2.1MB，node_modules/dist/wasm 照舊排除）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
uncle6me-web
@@ -0,0 +1,120 @@
|
||||
# 交辦文件：修復 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`
|
||||
Reference in New Issue
Block a user