Leo
1d7f69215a
審查意見兩處（總管 2026-07-07）： 1. K2 原「recipe 維持 KV 公庫、泛化端點 front 兩後端」與 #16（RECIPES KV→KBDB）衝突 → 改為 KBDB 是唯一公庫後端；#16 落地前對 type=recipe 的 KV 轉接明定為過渡碼、 #16 完成即拆（1.5/5.2 對應改）；KV 公庫不得寫成穩態。遷移本體＝#16 負責，不重工。 2. component 界線照 #23/D29 定案改：零件貢獻整層搬到獨立 repo Leo/arcrun-components （fork→PR→人審）；市場只偵測缺件→引導去該 repo 開 PR，永不傳輸/安裝零件程式； arcrun_publish_component 路徑廢除。design/requirements/tasks 凡提零件發布處照此改。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk
125 lines
7.6 KiB
Markdown
125 lines
7.6 KiB
Markdown
# 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` 型別（三型共用）
|
||
- 驗收：TS interface 落在 cypher-executor（或 shared types），涵蓋 recipe/workflow/template 三型 portable_body 的 union。
|
||
- 注意：不建新表——entry_type + metadata_json 承載（KBDB 鐵律 D6）。
|
||
|
||
- [ ] 1.2 `GET /public-artifacts?type=&q=&limit=&offset=`（搜/列，帶 market_stat，落空回創作引導）
|
||
- 驗收：type=workflow 投一筆後搜得到、附 market_stat；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=`（取全文，多作者選市場最佳）
|
||
- 驗收：多作者版本並存時回 success_count 最高版；落空回創作引導。
|
||
- 注意：選版邏輯沿用 recipe `fetchMarketStat` per-uuid（泛化為 `/artifact-stats/:uuid` 或復用 recipe-stats）。
|
||
|
||
- [ ] 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，見 §狀態）。
|
||
|
||
---
|
||
|
||
## 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）
|
||
- 驗收：一個引用 http_request+recipe+寫 template+用 credential 的 workflow，manifest 正確列出四類依賴。
|
||
- 注意：manifest 在 export/submit 時算好存進 record（import 端免反解）。這是 import 信任預覽面（K5）。
|
||
|
||
- [ ] 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 摘要依賴給人看）
|
||
|
||
---
|
||
|
||
## 完成定義
|
||
|
||
整個 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× 返工。
|