Leo
7777414b70
規劃「資料庫就能完成的開發物」（recipe/workflow/template）的分享/發布/下載/導入/匯出。 泛化一套 /public-artifacts 讀端點 + 型別化 materialize adapter 寫；公庫存 KBDB； 依賴解析劃清界線（recipe/template co-pull、component 走 PR、credential 零傳輸）。 純文件，不改程式。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
97 lines
8.5 KiB
Markdown
97 lines
8.5 KiB
Markdown
# 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）不在此範圍**。零件是**程式**，走 **PR → 併入 main → 由部署/更新流程安裝**（`component-gatekeeping` + `arcrun-components` repo 已定案：投稿唯一入口＝PR，廢 MCP publish 路徑，見 Arcrun#23 教訓）。本 SDD 只在「依賴解析」處與零件交界，不改零件安裝路徑。
|
||
|
||
---
|
||
|
||
## 用戶故事
|
||
|
||
> 貫穿的 low-code 原則：**「丟一個網址 / 一句話給 AI 即可裝」**（對齊 D6 補2「URL 由 AI 自動填、用戶零填寫」、arcrun-primer「AI 用 MCP/CLI/HTTP 就能建立、不碰底層」）。
|
||
|
||
### 發布側（我做好了，想分享）
|
||
|
||
- **US-1（發布 workflow）**：我做好一個 `daily_digest` workflow，想讓別人也能用。我對 AI 說「把這個 workflow 發布到公庫」→ AI 呼叫 submit → 它成為公庫的一個具名作者版本，別人搜得到。
|
||
- **US-2（發布 template）**：我設計了一個好用的 `crm_contact` template（slots: name/email/company/stage），想分享。對 AI 說「發布這個 template」→ 進公庫。
|
||
- **US-3（匯出可攜檔）**：我要把一個 workflow 給不在同一部署的朋友（離線 / 走 email）。對 AI 說「匯出成檔案」→ 得到一份自足的 YAML/JSON（含依賴清單、不含機密）。
|
||
|
||
### 下載側（我想找別人的來用）
|
||
|
||
- **US-4（搜公庫）**：我想找「發 Slack 通知」的現成 workflow。對 AI 說一句話 → AI 搜公庫，回幾個候選＋各自市場數據（用過幾次、成功率），我挑一個。
|
||
- **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）。
|
||
|
||
---
|
||
|
||
## 功能需求
|
||
|
||
- **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 公庫端點**：搜/列（帶市場數據，落空回創作引導）、取全文（pull 用，多作者選最佳）、投稿（submit-p，新增作者版本不覆蓋）。三型都要。
|
||
- **R4 導入語意（pull）**：pull = 把公庫定義寫進自己 namespace——workflow→`push`（/webhooks/named）、template→`create_template`、recipe→既有 `installRecipeRecord`。
|
||
- **R5 依賴解析**：導入一個 workflow 時，遞迴處理它引用的 recipe/template（一起 pull）、驗證引用的 component 是否已具備（缺→引導走 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。
|
||
- **回應語言**：面向使用者的提示訊息正體中文。
|
||
|
||
---
|
||
|
||
## Out of Scope（明確排除，避免 CC 自行延伸）
|
||
|
||
- **零件（component/code）的分享/安裝**——走 PR，另案（`component-gatekeeping` / `arcrun-components`）。本 SDD 只在依賴解析處**偵測**零件缺口並引導，不安裝零件。
|
||
- **credential 的分享**——機密永不可攜。只匯出「需要哪些 key」的清單。
|
||
- **跨環境市場數據聚合層**（self-hosted 各部署的真實成功率匯總回公庫）——沿用 kbdb-base §7.3/§7.5 5.5「另排」，本 SDD 只讀既有 per-uuid market_stat，不做聚合管道。
|
||
- **recipe 既有公庫路徑的重寫 / 從 KV 遷 KBDB**——recipe 現行 KV 路徑已上線且穩定，不在此動它（避免「在既有可用機制上重投資」）。本 SDD 為 workflow/template 建 KBDB-native 公庫，recipe 是否收斂為未來選項（見 design 關鍵決策）。
|
||
- **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；落空回創作引導。
|
||
- [ ] 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 }` 創作引導，非空陣列。
|