Leo
df62933fa5
leo review 方向確認後的三個補點（2026-07-07，總管轉達）： 1. deps_summary：搜尋結果每項就顯示配套需求（從 dependency_manifest 聚合的輕量摘要， submit 時算好存 metadata_json）。low-code 關鍵：判斷「裝不裝」的資訊要在搜尋層， 不是 pull 之後才發現缺東西。design（R1 模型/端點/R5/驗收）、requirements（US-4/R3）、 tasks（1.1/1.2/2.2）對應補。 2. author 信譽經濟（market 核心）：author= 過濾＋作者頁端點（找到 Leo 看到他全部 shares）； author_reputation＝從 per-uuid stat 聚合的衍生視圖、不另立真相源（第一階段查詢時算、 量大再物化）；選版升級為單品＋作者信譽複合分（權重待拍板）；獎勵層 future 不實作 （第一階段獎勵＝信譽本身；author 綁認證身份列 SaaS/多人市場前置）。design（作者信譽段/ 端點/待拍板 6-8）、requirements（US-9/R3）、tasks（1.3/1.6/5.4/5.5）。 3. 資料完整性優先於界面：新增設計原則段（UI 是未來的皮、record 完整性是現在的責任； 事件型資料事後不可重建 → pull/submit 事件 day-one append）；record 欄位用「未來 showcase 網站」反推補齊（created_at/updated_at/tags/compat/license，各標必填/自記/可選）； 驗收加可測定義：不看 UI 僅用 record+事件就能重建市場首頁（作者榜/熱門榜/最新發布/配套需求）。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk
10 KiB
10 KiB
Artifact Sharing — Requirements
狀態：草稿（待 review） 建立：2026-07-07 | 最後更新：2026-07-07 負責人：Arcrun subagent（受 InkStoneCo 總管指派） 上游：對齊
arcrun/kbdb-base§7.5（recipe app-store / 公私庫雙向機制）、component-gatekeeping（零件走 PR）、workflow-discovery（workflow 已雙寫 KBDB）、data-exfil-warning（外呼風險層）。
一句話說明
把 recipe 已有的「公庫發布 / 下載導入 / 市場數據」app-store 模型，擴展到 workflow 與 template(+slots)，讓「資料庫就能完成的開發物」都能分享、發布、下載、導入、匯出。
背景與問題
Arcrun 的可攜開發物有三類存在 KBDB / KV 的宣告式 record：
| Artifact | 現狀儲存 | 現有分享機制 |
|---|---|---|
| recipe | RECIPES KV（UUID 身份模型） |
✅ 完整：GET /public-recipes（搜/列）、GET /public-recipes/:canonical_id（pull 全文）、POST /recipes/submit（submit-p 投稿）、MCP arcrun_recipe_search/pull/push/submit_p、CLI acr recipe search/pull/submit-p |
| workflow | WEBHOOKS KV + KBDB entry_type=workflow（雙寫，供語意搜尋；workflow-discovery） |
❌ 只有本租戶 CRUD（arcrun_push_workflow/list_workflows/get_workflow）＋本租戶語意搜尋（/workflows/search）。無公庫 / submit / pull / export |
| template(+slots) | KBDB /templates（name + slots） |
❌ 只有 kbdb_create_template / kbdb_list_templates。無任何分享機制 |
問題：recipe 能被社群分享成長，workflow 與 template 卻鎖死在單一租戶。使用者做好一個 workflow / template，沒有「發布給別人、或找別人的拉來用」的路。這違背 Arcrun「AI-Friendly 的 n8n」定位——n8n 有 workflow 範本市集，Arcrun 目前只有 recipe 有。
範圍界線（leo 拍板，最重要）
- 本 SDD 只處理「資料庫就能完成的開發物」＝ recipe / workflow / template(+slots)。它們是 KBDB / KV 裡的可攜 record，分享＝發布到公庫 ＋ 下載/導入進自己 namespace ＋ 匯出成可攜格式。
- 零件（component / code）不在此範圍。零件是程式，貢獻已整層搬到獨立 repo
Leo/arcrun-components：唯一入口＝fork→PR→人審→併 main→由部署/更新流程安裝（#23/D29 定案；arcrun_publish_component路徑廢除）。本 SDD 的市場只在「依賴解析」處與零件交界：偵測缺件→引導去該 repo 開 PR，永不傳輸/安裝零件程式。
用戶故事
貫穿的 low-code 原則：「丟一個網址 / 一句話給 AI 即可裝」（對齊 D6 補2「URL 由 AI 自動填、用戶零填寫」、arcrun-primer「AI 用 MCP/CLI/HTTP 就能建立、不碰底層」）。
發布側（我做好了，想分享）
- US-1（發布 workflow）：我做好一個
daily_digestworkflow，想讓別人也能用。我對 AI 說「把這個 workflow 發布到公庫」→ AI 呼叫 submit → 它成為公庫的一個具名作者版本，別人搜得到。 - US-2（發布 template）：我設計了一個好用的
crm_contacttemplate（slots: name/email/company/stage），想分享。對 AI 說「發布這個 template」→ 進公庫。 - US-3（匯出可攜檔）：我要把一個 workflow 給不在同一部署的朋友（離線 / 走 email）。對 AI 說「匯出成檔案」→ 得到一份自足的 YAML/JSON（含依賴清單、不含機密）。
下載側（我想找別人的來用）
- US-4（搜公庫）：我想找「發 Slack 通知」的現成 workflow。對 AI 說一句話 → AI 搜公庫，回幾個候選＋各自市場數據（用過幾次、成功率）＋配套需求摘要（deps_summary）——搜尋結果每一項就顯示「要配哪些東西才跑得起來」（例：搜到「把 Facebook post 拉回來儲存」，列表直接顯示＝需 1 template（fb_posts）＋1 recipe（facebook）＋1 credential 待填（facebook_token）），我在搜尋層就能判斷裝不裝，不是 pull 之後才發現缺東西。
- US-5（pull 導入）：我看中一個 workflow，說「拉這個來用」→ AI 把它寫進我自己的 namespace（workflow→push、template→create_template），連同它引用的 recipe / template 依賴一起備妥，立即可用。
- US-6（丟網址即裝）：朋友給我一個公庫連結 / canonical_id，我丟給 AI，AI 一條龍 pull + 解依賴 + 報告還缺哪些 credential 要我填。
作者 / 市場
- US-7（多作者並存）：公庫同一個
daily_digest可以有 Leo 版、John 版，各自 uuid、各自累積市場數據，pull 時預設給市場最佳版本（沿用 recipe §7.5.5）。 - US-8（落空即創作）：我搜的東西公庫沒有，AI 不該只回空結果，而是引導「你可以自己做一個成為第一個作者」（沿用 recipe §7.5.6）。
- US-9（作者頁＋信譽可見，market 核心）：Leo 發表了 100 個 recipe、reputation 非常好——我找到 Leo 就能看到他 share 的這 100 個 recipes（
author=過濾／作者頁），且搜尋結果的作者名旁就看得到他的信譽摘要（發布數、彙總成功率）。信譽是排序/信任訊號，也是未來獎勵機制的掛載點（獎勵層本 SDD 不實作，見 design 作者信譽段）。
功能需求
- R1 公庫 record 模型統一：三型 artifact 在公庫共用一致的身份/歸屬/市場欄位——
uuid（唯一身份）、type（recipe/workflow/template）、canonical_id、author、derived_from、market_stat（per-uuid success/failure）。沿用 recipe UUID 身份模型（kbdb-base §7.5.5）。 - R2 可攜格式（export）：每型能匯出成自足的 YAML/JSON，含
dependency_manifest（引用的 component/recipe/template/credential 清單），絕不含機密值。 - R3 公庫端點：搜/列（帶市場數據＋每項附 deps_summary 配套需求摘要＋作者信譽摘要，支援
author=過濾，落空回創作引導）、作者頁（信譽聚合＋該作者全部發布）、取全文（pull 用，多作者以「單品數據＋作者信譽」複合分選最佳；成功即記 pull 事件）、投稿（submit-p，新增作者版本不覆蓋）。三型都要。 - R4 導入語意（pull）：pull = 把公庫定義寫進自己 namespace——workflow→
push（/webhooks/named）、template→create_template、recipe→既有installRecipeRecord。 - R5 依賴解析：導入一個 workflow 時，遞迴處理它引用的 recipe/template（一起 pull）、驗證引用的 component 是否已具備（缺→引導去
Leo/arcrun-components開 PR（fork→PR→人審），永不傳輸/安裝零件程式）、列出需要的 credential（引導acr creds push，不隨 artifact 傳輸）。 - R6 三介面對齊：HTTP 端點 → MCP tool → CLI 三層都補齊（沿用 recipe 三層樣板）。
- R7 安全：對照 Arcrun#23（publish_component 零人閘教訓）明確界定——資料 artifact 走 app-store 市場信任（無 submit 前置人閘，leo 2026-06-29 已對 recipe 拍板移除 consent 閘）；真正的程式攻擊面（零件）鎖在 PR 路徑。導入時以市場數據 + 依賴清單 +
data-exfil-warning外呼檢查作為信任判斷點。
非功能需求 / 對齊鐵律
- 儲存鐵律（arcrun-primer / 2026-07-06 leo 釘死）：新增的公庫與可攜 record 都是長效資料 → KBDB / D1，禁止為閃避 KBDB 塞 KV；禁止建新表（用 template/slots / entry_type 承載）。機密 → CF Worker Secrets，永不進可攜檔。
- API-as-Wall（D6）：全走 KBDB API（MCP/CLI/HTTP），插件層禁 SQL 直寫 D1。
- 不碰 wrangler / 不自建 Worker：這是 A 類應用邏輯（arcrun-primer 兩類工作表），端點加在既有 cypher-executor / kbdb worker，不新建 standalone worker、不 service binding。
- 資料完整性優先於界面（leo 2026-07-07）：可以沒有 UI，但 record 資訊 day-one 就要留全——公庫 record 欄位用「未來 showcase 網站」反推（created_at/tags/相容性/license/版本沿革，見 design R1）；事件型資料（pull/submit 誰何時做了什麼）事後不可重建，首日就 append 記錄（KBDB append-only），衍生統計（作者信譽、熱門榜）晚算沒關係。
- 回應語言：面向使用者的提示訊息正體中文。
Out of Scope（明確排除，避免 CC 自行延伸）
- 零件（component/code）的分享/安裝——唯一路徑＝獨立 repo
Leo/arcrun-components的 fork→PR→人審（#23/D29 定案），另案。本 SDD 只在依賴解析處偵測零件缺口並引導去該 repo 開 PR，永不傳輸/安裝零件程式。 - credential 的分享——機密永不可攜。只匯出「需要哪些 key」的清單。
- 跨環境市場數據聚合層（self-hosted 各部署的真實成功率匯總回公庫）——沿用 kbdb-base §7.3/§7.5 5.5「另排」，本 SDD 只讀既有 per-uuid market_stat，不做聚合管道。
- recipe RECIPES KV→KBDB 遷移的執行——由 #16 負責（另案進行中），本 SDD 不動手遷、也不重寫 recipe 既有
/public-recipes*。但設計前提＝KBDB 是唯一公庫後端（design K2）：#16 落地前泛化端點對type=recipe的 KV 轉接只是過渡碼，#16 完成即拆，KV 公庫不是穩態。 - SaaS / api-key 發放——沒有 SaaS（D21）。self-hosted 唯一形態，公庫連線走既有部署 URL。
驗收標準（US 對應）
- US-1/US-2：
acr workflow submit-p <name>/acr template submit-p <name>能把私庫 artifact 投進公庫，成為具名作者版本（回 uuid）。 - US-3：
acr workflow export <name>產出自足 YAML，含 dependency_manifest、零機密值。 - US-4：
acr workflow search <q>回候選 + 各自 market_stat + deps_summary（搜尋結果可見配套需求）；落空回創作引導。 - US-5/US-6：
acr workflow pull <canonical_id>把定義寫進自己 namespace，且遞迴 pull recipe/template 依賴、報告缺的 component 與待填 credential。 - US-7：公庫同 canonical_id 多作者版本並存，pull 預設回 market_stat 最佳版本。
- US-8：搜尋/取用落空回
{ found:false, hint }創作引導，非空陣列。 - US-9：
author=過濾／作者頁列出該作者跨型別全部發布＋信譽摘要（從 per-uuid stat 聚合，非另立真相源）。