Arcrun/.agents/specs/recipe-system/tasks.md

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

對應 SDD：design.md 上次更新：2026-05-07

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

---

Phase 1：prompt_recipe Schema + KV 規範

• 1.1 寫 cypher-executor/src/lib/prompt-recipe-schema.ts（85 行 Zod schema：fragments / inputs / prompt_assembly / output + transform 白名單 7 個）
• 1.2 確認 cypher-executor wrangler.toml 已有 RECIPES KV binding
• 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）

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

Phase 3：第一個 recipe — wiki_synthesis

• 3.1 寫 polaris/mira/recipes/wiki_synthesis.json（4 fragments + 4 inputs + system/user template + json output）
• 3.2 用 wrangler kv key put --remote 推進 RECIPES KV (key: prompt_recipe:wiki_synthesis)
• 3.3 確認 KV 寫入成功（wrangler kv get 驗證）
• 3.4 不適用（架構選擇 B 不改 claude_api，recipe 在 cypher-executor 解析）
• 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