Arcrun/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md

Artifact Sharing — Tasks

權威來源：此檔案是進度真相，不是 CLAUDE.md 或對話。 規則：動手前標 [🔄]，完成立刻標 [x]，不批次更新。 依賴：design.md 的關鍵決策 K1-K5；母範本＝cypher-executor/src/routes/recipes.ts（recipe 公庫）。

---

Phase 1：統一公庫模型 + 泛化端點（後端地基）

前置條件

• design.md K1（泛化讀/型別化寫）、K2（KBDB 後端）已 review 無反對。
• 確認 KBDB /entries + /entries/search 現況（workflow-discovery 已用，沿用即可）。

Tasks

• 1.1 定義 public_artifact entry 形狀 + portable_body / dependency_manifest / deps_summary 型別（三型共用）

  • 驗收：TS interface 落在 cypher-executor（或 shared types），涵蓋 recipe/workflow/template 三型 portable_body 的 union；含完整性欄位 created_at/updated_at/tags/compat/license（各標必填/自記/可選，照 design R1「showcase 反推」清單，一個都不少）。
  • 注意：不建新表——entry_type + metadata_json 承載（KBDB 鐵律 D6）。事件 entry（artifact_pull_event/artifact_submission）形狀一併定義（day-one append，設計原則）。

• 1.2 GET /public-artifacts?type=&q=&author=&limit=&offset=（搜/列，帶 market_stat + deps_summary + 作者信譽摘要，落空回創作引導）

  • 驗收：type=workflow 投一筆後搜得到、附 market_stat 與 deps_summary（列表層即見「要配哪些 recipe/template/component/credential」）；author= 過濾回該作者跨型別全部發布；q 無命中回 {found:false,type,query,hint}。
  • 注意：邏輯照抄 recipe /public-recipes，差別＝走 KBDB /entries/search（entry_type=public_artifact + type filter）而非 KV list。

• 1.3 GET /public-artifacts/:type/:canonical_id?author=（取全文，多作者複合分選版 + pull 事件）

  • 驗收：多作者版本並存時回複合分最高版（單品 market_stat＋作者信譽；權重待拍板，先以單品為主、信譽當 tiebreak/冷啟動先驗）；落空回創作引導；成功取全文 append 一筆 artifact_pull_event（誰、何時、哪個 uuid）。
  • 注意：單品數據沿用 recipe fetchMarketStat per-uuid（泛化為 /artifact-stats/:uuid 或復用 recipe-stats）；pull 事件事後不可重建，這條不可延後（設計原則）。

• 1.4 POST /public-artifacts/submit（submit-p，新增作者版本 + 存證）

  • 驗收：投稿領新 uuid、不覆蓋同 canonical；寫一筆 artifact_submission entry；自報 stat 不進真實計數。
  • 注意：沿用 recipe submit 的「新 uuid＝新作者版本」與 fire-and-forget 存證。

• 1.5 recipe 相容轉接（過渡碼，#16 落地前）：泛化端點對 type=recipe 暫時轉呼既有 KV 公庫路徑

  • 驗收：GET /public-artifacts?type=recipe 結果與既有 /public-recipes 一致（不破現況）。
  • 注意：K2——KBDB 是唯一公庫後端，KV 轉接非穩態：#16（RECIPES KV→KBDB）完成後 type=recipe 改走 KBDB、本轉接即拆（見 5.2）。不改 recipe 既有 /public-recipes* 與 KV 儲存（遷移本體＝#16 的事）。可延後（先只上 workflow/template，見 §狀態）。

• 1.6 作者面：GET /public-artifacts/authors/:name（作者頁）＋ author_reputation 查詢時聚合

  • 驗收：回信譽摘要（發布數、彙總 success/failure、最近活躍）＋該作者全部發布清單（每項附 market_stat/deps_summary）；聚合值與逐 uuid 手算一致（衍生視圖，不另立真相源）。
  • 注意：第一階段 compute-on-read 只限單作者面（作者頁/作者名旁，量級 10²）；跨作者榜單（熱門榜/作者榜）不可 on-read 掃全庫——榜單類＝物化候選第一位，走 5.4 物化快照，非即時聚合。曝光位：搜尋結果作者名旁＋作者頁頂部（design 作者信譽段）。

---

Phase 2：可攜格式 export + 依賴清單

前置條件：Phase 1 的 portable_body 型別（1.1）定案。

• 2.1 三型 export：從私庫定義產出自足 portable_body（去 uuid/author/時間戳、去機密）

  • 驗收：workflow/template/recipe 各能 export 成 YAML；grep 不到任何機密值、不含 credential value。
  • 注意：workflow 保留 {{credential.xxx}} 模板（無值）；recipe credentials_required 只留 key 名。

• 2.2 dependency_manifest 產生器：掃 portable_body 抽引用（component/recipe/template/credential）＋順手聚合 deps_summary

  • 驗收：一個引用 http_request+recipe+寫 template+用 credential 的 workflow，manifest 正確列出四類依賴；deps_summary 聚合正確（各類名稱清單，空類空陣列）並存進 record。
  • 注意：manifest 在 export/submit 時算好存進 record（import 端免反解）。這是 import 信任預覽面（K5）＋搜尋層配套可見（deps_summary，leo 補點）的共同來源。

• 2.3 export 落檔（YAML 預設，JSON 可選）＝ portable_body + manifest + type/canonical 標頭

  • 驗收：export 檔在另一相同部署 import 後可跑（前提零件已具備、credential 已填）。

---

Phase 3：導入語意 pull + materialize adapter + 依賴解析

前置條件：Phase 1（端點）+ Phase 2（manifest）完成。

• 3.1 materialize adapter（型別化落地）：workflow→push、template→create_template、recipe→installRecipeRecord

  • 驗收：pull 一個無依賴 workflow → 出現在自己 arcrun_list_workflows；template 同理進 kbdb_list_templates。
  • 注意：owner_id=自己 namespace（租戶隔離，沿用既有身份模型）。

• 3.2 依賴解析引擎（有界遞迴）：讀 manifest 分類處理

  • 驗收：pull 一個引用 recipe R + template T 的 workflow → R/T 自動 co-pull 進私庫；visited set 防環 + 深度上限 5。
  • 注意：K4——recipe/template co-pull；component 只偵測（對照 acr parts）缺則引導 PR、不抓程式；credential 只彙總 key 名引導 acr creds push。

• 3.3 component 缺口偵測 + 引導（界線落點）

  • 驗收：pull 一個引用「本部署沒有的零件」的 workflow → 停在引導（不落地、永不傳輸/安裝零件程式），訊息指向獨立 repo Leo/arcrun-components 開 PR（fork→PR→人審，#23/D29）。
  • 注意：這道牆＝防「workflow 當殼夾帶惡意零件」（#23；arcrun_publish_component 已廢除，勿在引導文案提它）。缺零件必須是硬停，不是警告後照裝。

• 3.4 credential 清單引導

  • 驗收：pull 後回報彙總的待填 key 清單 + acr creds push 指引；artifact 內無任何機密值。

---

Phase 4：MCP + CLI 三層對齊

前置條件：Phase 1-3 端點與語意就緒。

• 4.1 MCP tools：arcrun_artifact_search/pull/submit_p（帶 type）+ arcrun_workflow_export/arcrun_template_export

  • 驗收：MCP tools/list 出現新 tool；search→pull→export 端到端跑通（對照既有 arcrun_recipe_* 樣板）。
  • 注意：tool 名走 brand.ts toolName() 單一來源（沿用現有慣例）。

• 4.2 CLI：acr workflow search/pull/submit-p/export、acr template search/pull/submit-p/export

  • 驗收：對照 cli/src/commands/recipe.ts 樣板；型別化措辭對外、底層打泛化 /public-artifacts 端點。
  • 注意：落空回創作引導文案（沿用 recipe search 落空體驗）。

• 4.3 文件：GUIDE/README/llms.txt 補三型分享的用法（低碼「丟網址/一句話即裝」示例）

  • 驗收：文件零殘留舊工具名；含 US-6「丟網址即裝」示例。

---

Phase 5（可選 / 未來）：安全信任面 + recipe 收斂

• 5.1 import 端 data-exfil-warning 外呼檢查接線（pull 的 recipe 依賴過同層警示）
  • 驗收：pull 一個 endpoint 域名異常的 recipe → import 端出警示（非硬擋）。
• 5.2（已定案，跟 #16 進度走）recipe 公庫收斂到 KBDB public_artifact ＋ 拆 1.5 的 KV 過渡轉接
  • 注意：K2 已定（KBDB 唯一公庫後端，審查 2026-07-07 對齊 #16）；遷移本體由 #16 執行，本項＝#16 落地後把 type=recipe 切到 KBDB 路徑並移除轉接碼。非阻塞（過渡期 1.5 已能運作）。
• 5.3（待 leo 拍板 K5）公開公庫場景的 import 軟提示（首次 pull 陌生作者→AI 摘要依賴給人看）
• 5.4 物化快照：榜單類（首頁熱門榜/作者榜）＝物化候選第一位——跨作者/全庫聚合本質不可 on-read 掃全庫，首頁榜單一律走定期物化快照（cron 聚合寫成標記為快取的 entry），非即時聚合；單作者 reputation 量大後同樣收進物化。真相仍在 per-uuid stat＋事件，快照過期重算。
• 5.5（future，SaaS/多人市場前置，不在本 SDD 實作）author 綁認證身份（信譽防冒名、獎勵防盜領）＋獎勵機制層（第一階段獎勵＝信譽本身：曝光/排序/信任）

---

完成定義

整個 SDD 完成 = 以下全部達成：

• 所有 Phase 1-4 tasks 標 [x]（Phase 5 為可選/未來）
• 驗收標準通過（design.md 驗收清單有客觀證據）
• design.md 與實作一致（如有出入需更新）
• 零件界線未被破壞：無任何路徑讓未經 PR 的零件因 artifact 分享進入 host

---

狀態說明

標記	意義
[ ]	未開始
[🔄]	進行中（當前 session）
[x]	完成（有驗收證據）
[~]	暫緩（說明原因）
[!]	阻擋中（說明阻擋原因）

建議施作順序：先 workflow 全鏈（Phase 1-4 只做 workflow）跑通一個型別的閉環，再複製到 template；recipe 相容轉接（1.5）與收斂（5.2）最後或不做。理由＝先證泛化模型對一個型別成立，再擴，避免三型並行時模型未穩就 3× 返工。

---

Phase 1.5：App（bundle）＋實例譜系＋訂閱更新＋多源（P-2026-07-19，confirmed 2026-07-19）

依據：3-specs/pending-changes.md 已裁決 P-2026-07-19（P1-P6 全文）。排序＝緊接 Phase 1； 最小核先行（1.5-1/1.5-2），通知與 self-check 可分批。過渡期 arcrun-rag install.sh 續用， 1.5-2 落籍可先由 installer 代寫（義肢幫器官接生）。

• 1.5-1 bundle 第四型（P1）：type=bundle portable_body＝成員清單（type/canonical_id/uuid 鎖版或 track-latest）＋install_params_schema＋conformance；pull bundle＝成員經 dependency_manifest 全解析。
  • 驗收：arcrun-rag 翻譯成第一個 bundle manifest；pull 後成員全 materialize。
• 1.5-2 installed_from 譜系＋四態（P3）：materialized artifact 落籍 {installed_from_source, installed_from_uuid, installed_at, content_hash}（entry metadata，不建表）；list/console/MCP 標 up_to_date/behind/diverged/sideloaded（＋source_lost）。
  • 驗收：API 直建的 workflow 列表顯 sideloaded；改過的顯 diverged。
• 1.5-3 訂閱與更新查詢（P2）：artifact_subscription entry（policy: notify|auto|pin，預設 notify）＋GET /subscriptions/updates 查詢式；禁發布事件自動 fan-out（D4）。
  • 驗收：submit 新版後，訂閱端查詢見 behind；更新為顯式動作、可拒可 pin。
• 1.5-4 多源與 visibility（P6 第一波＝官方源＋直連一個外源）：artifact 加 visibility: public|org|unlisted；外源拉取走 token 認證；installed_from 記源。org 私區留第二波。
  • 驗收：實例 B 加實例 A 為源、拉 A 的 unlisted bundle 成功；A 斷線後 B 已裝照跑、狀態 source_lost。
  • 鐵律：pull＝複本全落地，runtime 零外部依賴（P6 鐵律段）。
• 1.5-5 conformance self-check（P5）：bundle 附驗收清單（介面×能力機械檢查），install/update 完自動跑產報告。
  • 驗收：arcrun-rag bundle 裝完自動報 GUI/MCP/三模式可用性矩陣。
• 1.5-6 信譽記分邊界（附註）：私下/org 源 pull 事件不進公開信譽；bundle 作者計入 #31 信譽經濟。