# Tasks — Recipe System (容器 + Recipe 模式)

> 對應 SDD：[design.md](design.md)
> 上次更新：2026-05-07

**狀態 legend**：`[ ]` 待辦 / `[🔄]` 進行中 / `[x]` 完成

---

## Phase 1：prompt_recipe Schema + KV 規範

- [x] 1.1 寫 `cypher-executor/src/lib/prompt-recipe-schema.ts`（85 行 Zod schema：fragments / inputs / prompt_assembly / output + transform 白名單 7 個）
- [x] 1.2 確認 cypher-executor wrangler.toml 已有 RECIPES KV binding
- [x] 1.3 寫 recipe loader (`recipe-loader.ts` 50 行) + transforms (`recipe-transforms.ts` 58 行) + expander (`recipe-expander.ts` 127 行)
  - transform 7 個：json_array / to_string / join / markdown_list / extract_field / first / pluck_content
  - expander：fragments(KBDB) + inputs(context+transform) → 套 {{var}} 模板 → {prompt, model, output_*}
  - type-check 全通過

## Phase 2：cypher-executor recipe expander（架構選擇 B，不改 claude_api）

- [x] 2.1 寫 `recipe-expander.ts`（127 行：load → fragments → inputs+transform → 套模板 → 回傳 prompt+model+output_*）
- [x] 2.2 寫 `recipe-transforms.ts`（58 行：7 個 transform）
- [x] 2.3 改 `graph-executor.ts` Component case：偵測 `node.data.recipe` → 呼叫 expandPromptRecipe → merge 進 mergedContext
- [x] 2.4 output parser hook：執行完若 `_recipe_output_format === 'json'` 自動 parse + required_fields 驗證
- [x] 2.5 部署 cypher-executor v426b099e
- [x] 2.6 端對端驗證：用 curl 打 `/cypher/execute` 帶 recipe，trace 顯示 recipe 展開正確 + claude_api 拿到組好 prompt（Mira daemon 端 522 timeout 是 daemon 問題，不是 recipe 系統）
- [x] 2.7 [紅利修復] cypher-executor `WASM_HTTP_RUNNER_IDS` 加 5 個 mira 零件（claude_api / kbdb_*）— 短期解，根本修法見 KI-13

## Phase 3：第一個 recipe — wiki_synthesis

- [x] 3.1 寫 `polaris/mira/recipes/wiki_synthesis.json`（4 fragments + 4 inputs + system/user template + json output）
- [x] 3.2 用 `wrangler kv key put --remote` 推進 RECIPES KV (key: `prompt_recipe:wiki_synthesis`)
- [x] 3.3 確認 KV 寫入成功（wrangler kv get 驗證）
- [ ] 3.4 不適用（架構選擇 B 不改 claude_api，recipe 在 cypher-executor 解析）
- [x] 3.5 端對端測試：用 MCP `u6u_execute_workflow` 跑 wiki_synthesis 成功
  - input：1 句草稿（黃仁勳 GTC 2026 物理 AI）
  - output：3 triplets + 3 entities + 1 wiki paragraph + source_summary
  - 過程修了 KI-14 (service binding 指錯)、KI-15 (token 沒轉發)、KI-16 (Claude markdown fence 沒剝)

## Phase 4：mira 7-B 用 recipe 完成 wiki workflow

- [🔄] 4.1 寫 `polaris/mira/workflows/wiki_synthesis.yaml`（cypher binding YAML）
  - 用 `recipe: prompt_recipe:wiki_synthesis` 指 recipe
  - 4-5 個節點：read_stale → foreach → read_drafts → synthesize → write_wiki + log
- [ ] 4.2 用 MCP `u6u_execute_workflow` sandbox 跑（試一個 entity 不真寫 KBDB）
- [ ] 4.3 用 MCP `u6u_deploy_workflow` 部署到 cypher-executor
- [ ] 4.4 手動觸發 cron，驗 wiki page 真的出現
- [ ] 4.5 在 mira/wiki/ 前端看到第一張 AI 合成 wiki page

## Phase 5：MCP recipe 管理 tools

- [ ] 5.1 加 MCP tool `arcrun_list_recipes(prefix?)`：列所有 prompt_recipe
- [ ] 5.2 加 MCP tool `arcrun_get_recipe(name)`：取單一 recipe 內容
- [ ] 5.3 加 MCP tool `arcrun_push_recipe(name, yaml_content)`：upsert recipe
- [ ] 5.4 加 MCP tool `arcrun_delete_recipe(name)`
- [ ] 5.5 既有 auth_recipe / api_recipe 也通用同套 tool（不只 prompt_recipe）

---

## 風險追蹤

- 風險 1：claude_api 改造跟 mira-app 同時動，可能影響河道 AI 副駕
  - 緩解：向後相容，舊 input 仍可用，mira 河道先不切 recipe
- 風險 2：recipe transform 白名單漏了某種需求
  - 緩解：發現缺什麼再加，第一版優先支援 wiki 用到的（json_array, extract_field, join）
- 風險 3：KV 跟 KBDB 都存配置，AI 困惑「該存哪邊」
  - 緩解：清楚分層 — recipe（容器組合方式） KV，data（schema 文字、skill 模板） KBDB

---

## Known Issues（吃狗糧發現，記錄）

### KI-11：MCP `u6u_execute_workflow` 不暴露 config 欄位 ✅ 修復（2026-05-07）
- 已修：tool schema 加 optional `config: Record<string, Record<string, any>>`
- 部署：u6u-mcp v11d7e366
- 用戶要重啟 client session 才能看到新 schema

### KI-12：MCP execute 路由打 `/execute` 而非 `/cypher/execute` ✅ 修復（2026-05-07）
- 已修：service binding fetch URL 改成 `http://cypher-executor/cypher/execute`
- 部署：u6u-mcp v11d7e366

### KI-14：u6u-mcp service binding 指向已廢棄的 inkstone-cypher-executor ✅ 修復
- 現象：MCP 路徑跑 workflow trace 顯示 synth 變 Output、config 被忽略
- 根因：`u6u-mcp/wrangler.toml` services binding 是舊 worker `inkstone-cypher-executor`，不是現役 `arcrun-cypher-executor`
- 解法：改 service name + redeploy

### KI-15：u6u-mcp 沒把 partner token 轉發給 cypher-executor ✅ 修復
- 現象：recipe expander 抓 KBDB block 401（沒 auth）
- 根因：partnerAuthMiddleware 驗完 token 但只 set org_namespace，沒留 token；execute_workflow tool fetch 沒帶 X-Arcrun-API-Key
- 解法：middleware 也 set partner_token、handleMcpRequest + registerAllTools + execute_workflow 多一個 partnerToken 參數、fetch header 加 X-Arcrun-API-Key

### KI-16：Recipe JSON output 被 Claude 包在 ```json``` markdown fence ✅ 修復
- 現象：JSON.parse 失敗 "Unexpected token \`"
- 根因：Claude 預設輸出 ```json\n{...}\n``` 包裝
- 解法：cypher-executor 解析前 regex 剝 fence

### KI-13：cypher-executor `WASM_HTTP_RUNNER_IDS` 寫死白名單
- 現象：每加新零件要回 cypher-executor 改白名單 + 重部署
- 影響：違反 arcrun「容器+ recipe，新零件無需改 platform」承諾
- 短期解：手動加進白名單（claude_api / kbdb_* 已加）
- 根本解：改成從 component-registry KV 動態查 canonical_id
- 優先級：P1（推廣破口），需新 SDD `cypher-executor-dynamic-component-discovery`

---

## 對外推廣（Phase 6+，本 SDD 不執行，記錄）

- README 示範「容器 + recipe = 一個 service」(Gmail / Slack / Claude)
- onboarding kit GitHub template 內含 5 個經典 recipe 當範例
- 「recipe market」想法：用戶分享 recipe 幫他人少寫 prompt
