From df62933fa5ab384378a9e445fe86053c748bec25 Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 7 Jul 2026 10:15:52 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(spec):=20artifact-sharing=20leo=20?= =?UTF-8?q?=E4=B8=89=E8=A3=9C=E9=BB=9E=20=E2=80=94=20deps=5Fsummary=20?= =?UTF-8?q?=E6=90=9C=E5=B0=8B=E5=B1=A4=E5=8F=AF=E8=A6=8B=20+=20author=20?= =?UTF-8?q?=E4=BF=A1=E8=AD=BD=E7=B6=93=E6=BF=9F=20+=20=E8=B3=87=E6=96=99?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E6=80=A7=E5=84=AA=E5=85=88=E6=96=BC=E7=95=8C?= =?UTF-8?q?=E9=9D=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk --- .../3-specs/arcrun/artifact-sharing/design.md | 74 +++++++++++++++---- .../arcrun/artifact-sharing/requirements.md | 9 ++- .../3-specs/arcrun/artifact-sharing/tasks.md | 28 ++++--- 3 files changed, 81 insertions(+), 30 deletions(-) diff --git a/system-dev/docs/3-specs/arcrun/artifact-sharing/design.md b/system-dev/docs/3-specs/arcrun/artifact-sharing/design.md index 775f379..7ff4b58 100644 --- a/system-dev/docs/3-specs/arcrun/artifact-sharing/design.md +++ b/system-dev/docs/3-specs/arcrun/artifact-sharing/design.md @@ -58,6 +58,11 @@ - **讀寫都走既有 worker**：公庫 record 存 KBDB（`kbdb` worker 的 `/entries`），泛化端點掛在 **cypher-executor**（已是 recipe 公庫 + workflow CRUD 的所在，且已有 KBDB fetch 慣例）。**不新建 worker、不 service binding、不 wrangler**（arcrun-primer A 類）。 +### 設計原則（market 層） + +- **資料完整性優先於界面（leo，2026-07-07）**：「可以沒有界面，但這些資訊會留下；如果哪天已有 1000 個資源、想做個網站告訴大家，卻發現資訊都不足、少東少西，那就糟了。」UI 是未來的皮，**record 完整性是現在的責任**——本 SDD 的公庫 record 與事件記錄，一律用「未來 showcase 網站需要什麼」反推首日 schema（見 R1 欄位清單），而非「現在端點用到什麼」。 +- **事件型資料事後不可重建 → day-one 就 append 記錄**：衍生統計（author_reputation、熱門榜）可以晚算、隨時重算；但**原始事件**——誰何時 pull/download 了哪個 uuid、誰何時 submit 了什麼——**錯過當下就永遠沒有**。故 `artifact_pull_event` / `artifact_submission` 從第一天就寫（KBDB append-only 正好是這個用途），有沒有人看是另一回事。 + ### 關鍵決策 | 決策 | 選擇 | 原因 | 放棄的選項 | @@ -72,25 +77,54 @@ 公庫一筆 = KBDB entry，`entry_type='public_artifact'`，`owner_id=author`（歸屬即隔離），`metadata_json` 承載身份與市場鍵，`content` 放 canonical_id（供 keyword/semantic search）＋ `metadata_json.embed=true` 開語意搜尋： +欄位完整性用「未來 showcase 網站」反推（見設計原則）：哪天有 1000 個資源想做網站，**首日投稿就捕捉的欄位不能少東少西**。每欄標【必填＝投稿時必給｜自記＝系統寫入｜可選】： + ```jsonc // public_artifact entry.metadata_json { - "uuid": "…", // 唯一身份（誕生即領，沿用 §7.5.5） - "type": "workflow", // recipe | workflow | template - "canonical_id": "daily_digest", - "author": "leo", // 該 uuid 投稿者；'system'=種子 - "derived_from": "…uuid?", // 可選：fork 溯源 - "display_name": "每日摘要", - "description": "…", // 供語意搜尋，強制非空（沿用 workflow-discovery R1） - "embed": true, // 開 Vectorize - "portable_body": { … }, // 見「可攜格式」 - "dependency_manifest": [ … ] // 見「依賴解析」 + "uuid": "…", // 【自記】唯一身份（誕生即領，沿用 §7.5.5） + "type": "workflow", // 【必填】recipe | workflow | template + "canonical_id": "daily_digest", // 【必填】 + "author": "leo", // 【必填/自記】該 uuid 投稿者（自 namespace 帶出）；'system'=種子 + "created_at": "…", // 【自記】投稿時間（版本沿革與「最新發布」榜的依據） + "updated_at": "…", // 【自記】metadata 修訂時間（portable_body 不覆蓋——改版＝submit-p 新 uuid） + "derived_from": "…uuid?", // 【可選】fork 溯源；同 canonical_id+author 的歷代版本則靠 created_at 排序追（不需額外欄） + "display_name": "每日摘要", // 【必填】 + "description": "…", // 【必填】人讀的一句話；供語意搜尋，強制非空（沿用 workflow-discovery R1） + "tags": ["social", "fb"], // 【可選，建議】分類/標籤（showcase 分類頁的料） + "compat": { // 【自記，可覆蓋】相容性：投稿當下的 arcrun / portable 格式版本 + "arcrun_version": "1.3.x", + "schema_version": 1 + }, + "license": "MIT", // 【可選】未定→不填（顯示「未聲明」）；是否改必填待拍板 + "embed": true, // 【自記】開 Vectorize + "portable_body": { … }, // 【必填】見「可攜格式」 + "dependency_manifest": [ … ],// 【自記】掃 portable_body 產出，見「依賴解析」 + "deps_summary": { // 【自記】manifest 的輕量聚合（submit 時一併算好存入，搜尋列表直接帶） + "recipes": ["facebook"], // 各類依賴的名稱清單；空類回空陣列 + "templates": ["fb_posts"], + "components": [], + "credentials": ["facebook_token"] + } // market_stat 不存這裡——per-uuid 記在既有 recipe-stats 機制（KBDB），import 時 fetch } ``` +> **deps_summary（leo 補點，2026-07-07）**：`dependency_manifest` 是 pull 用的完整清單；`deps_summary` 是它的**搜尋層摘要**（各類依賴的名稱陣列），submit/export 算 manifest 時順手聚合、存進 metadata_json → 列表回應直接帶、不必解 portable_body。**為什麼要在搜尋層**：對 low-code 用戶，「裝不裝」的判斷資訊必須在搜尋結果就看到，不是 pull 之後才發現缺東西——搜到「把 Facebook post 拉回來儲存」的 workflow，列表項直接顯示「需 1 template（fb_posts）＋1 recipe（facebook）＋1 credential 待填（facebook_token）」，一眼可判斷。 + > **市場數據**：沿用 recipe `fetchMarketStat`（KBDB `/recipe-stats/:id`，per-uuid）。泛化為 `/artifact-stats/:uuid`（或直接復用 recipe-stats 表，key=uuid 本就型別無關）。**不在投稿時寫自報數**（沿用 §7.3：自報數只當存證 `*_submission` entry，不併真實計數，避免污染市場）。 +### 作者信譽（author reputation）—— market 的核心（leo 定義，2026-07-07） + +> leo 原話意涵：「Leo 發表了 100 個 recipe，他的 reputation 非常好，而你找到 Leo 就能看到他 share 的這 100 個 recipes」＋未來獎勵機制掛在信譽上。**Market 的核心＝作者信譽經濟（author-centric）**，per-uuid market_stat（單品數據）只是底層原料，作者層才是信任與激勵的單位。 + +- **author_reputation ＝衍生視圖，不另立真相源**：per-author 統計（發布 artifact 數、彙總 success/failure、最近活躍時間）**全部從 per-uuid market_stat ＋ 該 author 的 public_artifact entry 清單聚合而來**。取捨： + - **第一階段＝查詢時聚合（compute-on-read）**：單一作者的 artifact 數量級小（10²），KBDB 查該 author 的 entries + 逐 uuid 撈 stat 聚合即可，**零新儲存、零一致性問題**（真相永遠在 per-uuid）。 + - **量大再物化**：作者/流量成長後改「定期物化」（cron 聚合寫成 `author_reputation` entry，**明確標記為快取、非真相源**，過期重算）。先簡後繁，避免一開始就養兩份數據。 +- **曝光位**：① 搜尋結果每項的**作者名旁**附信譽摘要（如 `leo（42 發布・96% 成功）`）；② **作者頁頂部**（見端點段 authors 端點）。 +- **選版邏輯升級**：多作者同 canonical_id 時，排序訊號從「單品 success_count」擴為「**單品數據＋作者信譽**」的複合分——單品數據不足（新發布）時作者信譽當先驗。**權重配比待 leo 拍板**（見待拍板清單）。 +- **獎勵機制（future layer，本 SDD 不實作）**：**第一階段的獎勵＝信譽本身**（曝光、排序加權、信任標記）；未來付費分潤/積分**掛在 author identity 上**。因此 **author 身份必須穩定可驗**——現況 author 是字串 namespace（self-hosted 單租戶下夠用），**進 SaaS/多人公開市場前，author 必須綁認證身份**（否則信譽可被冒名、獎勵可被盜領），列為該階段的**前置條件**，非本 SDD 範圍。 + ### 可攜格式（export，R2 / US-3） 每型 `portable_body` = 該型的自足定義，**去識別化 + 去機密**： @@ -105,9 +139,10 @@ export 檔（YAML/JSON，二選一，預設 YAML 對齊 workflow.yaml 慣例） 掛在 cypher-executor，`type` 為必帶 query/param。行為對照 recipe `/public-recipes*` 完全同構： -- `GET /public-artifacts?type=&q=&limit=&offset=` — 搜/列公庫。同 canonical_id 回多筆（多作者），各附 `market_stat`。落空（q 無命中）→ `{ found:false, type, query, hint }` 創作引導（沿用 §7.5.6）。`type` 省略＝跨型別搜（回傳項帶各自 type）。 -- `GET /public-artifacts/:type/:canonical_id?author=` — 取單一全文（pull 用）。多作者→選 `market_stat.success_count` 最高版本（沿用 recipe 選版邏輯）。落空→創作引導。 -- `POST /public-artifacts/submit` — 投稿（submit-p）。body 帶 `{ type, canonical_id, portable_body, dependency_manifest, author, stat? }`。**領新 uuid = 新增作者版本**（不覆蓋，§7.5.5）；`stat` 只寫 `*_submission` 存證 entry，不併真實計數。 +- `GET /public-artifacts?type=&q=&author=&limit=&offset=` — 搜/列公庫。同 canonical_id 回多筆（多作者），各附 `market_stat` **與 `deps_summary`**（配套需求摘要：這個 artifact 要配哪些 recipe/template/component/credential 才跑得起來——「搜一個、看到各要裝什麼」在列表層就成立，見 R1 的 deps_summary 說明），作者名旁附**作者信譽摘要**（見作者信譽段）。**`author=` 過濾**＝跨型別列該作者全部發布（「找到 Leo 就看到他 share 的 100 個 recipes」），可與 `type`/`q` 併用——就是 author 欄的查詢面，成本低。落空（q 無命中）→ `{ found:false, type, query, hint }` 創作引導（沿用 §7.5.6）。`type` 省略＝跨型別搜（回傳項帶各自 type）。 +- `GET /public-artifacts/authors/:name` — **作者頁**：頂部 author_reputation 摘要（發布數、彙總成功率、最近活躍）＋該作者全部發布清單（每項附 market_stat/deps_summary）。reputation＝查詢時從 per-uuid stat 聚合（見作者信譽段的取捨）。 +- `GET /public-artifacts/:type/:canonical_id?author=` — 取單一全文（pull 用）。多作者→**複合分選版**：單品 `market_stat` ＋作者信譽（單品數據不足時作者信譽當先驗；權重待拍板）。落空→創作引導。**成功回應時 append 一筆 `artifact_pull_event`**（誰的 namespace、何時、拉了哪個 uuid）——pull 事件事後不可重建，day-one 就記（見設計原則）。 +- `POST /public-artifacts/submit` — 投稿（submit-p）。body 帶 `{ type, canonical_id, portable_body, dependency_manifest, author, tags?, compat?, license?, stat? }`。**領新 uuid = 新增作者版本**（不覆蓋，§7.5.5）；`stat` 只寫 `*_submission` 存證 entry，不併真實計數。 > **recipe 相容（過渡）**：終態＝三型都走 KBDB `public_artifact` 路徑（K2：KBDB 唯一公庫後端）。#16（RECIPES KV→KBDB）落地前的過渡期，泛化端點對 `type=recipe` 暫時轉呼既有 KV 公庫路徑（`listAllRecipes`/`installRecipeRecord`）——這段轉接碼是**過渡碼**，#16 完成後 `type=recipe` 改走 KBDB、轉接即拆，不留雙後端。可先只上 workflow/template，recipe 沿用既有 `/public-recipes`（見 tasks 分期）。 @@ -134,6 +169,7 @@ export 檔（YAML/JSON，二選一，預設 YAML 對齊 workflow.yaml 慣例） | **credential** | recipe 的 `credentials_required[].key` / workflow `{{credential.xxx}}` | **只列清單引導**：彙總所有需要的 key，回報「請 `acr creds push` 填：notion_token, …」。**值永不隨 artifact 傳輸** | 機密鐵律：值存 CF Worker Secrets，可攜檔只帶 key 名 | - **dependency_manifest** 在 **export/submit 時就算好並存進 record**（掃 portable_body 抽引用），import 端不必反解 workflow 內部結構就能預覽「這東西會拉進哪些 recipe/template、需要哪些零件與 credential」——也是 import 的**信任預覽面**（K5）。 +- **deps_summary 讓配套需求在「搜尋層」就可見**（leo 補點）：算 manifest 時順手聚合出各類依賴名稱清單存進 metadata_json，`GET /public-artifacts` 列表項直接帶。low-code 用戶判斷「裝不裝」的資訊要在搜尋結果就給，不是 pull 之後才發現缺東西——例：搜到「把 Facebook post 拉回來儲存」，列表項即顯示「需 1 template（fb_posts）＋1 recipe（facebook）＋1 credential 待填（facebook_token）」。 - **遞迴有界**：manifest 逐項 pull，維護 visited set 防環 + 深度上限（建議 5），超限回報中止並列未解項。 ### 安全與審核（R7 / K5）—— 對照 Arcrun#23 教訓 @@ -160,7 +196,8 @@ export 檔（YAML/JSON，二選一，預設 YAML 對齊 workflow.yaml 慣例） - 公庫 record：KBDB `public_artifact` entry（見上），**KBDB 是唯一公庫後端**（K2；recipe 過渡期例外見上）。**不建新表**（entry_type + metadata_json 承載，KBDB 鐵律）。 - market_stat：復用既有 KBDB recipe-stats（key=uuid，型別無關）。 -- 存證：`artifact_submission` entry。 +- **事件記錄（day-one append，設計原則第 2 條）**：`artifact_pull_event` entry（誰的 namespace、何時、拉了哪個 uuid——取全文成功即寫）＋ `artifact_submission` entry（誰、何時、投了什麼 uuid、自報 stat）。皆 append-only、不更新不刪除；熱門榜/下載數/作者活躍度等統計全部從這兩類事件＋recipe-stats 事後聚合，**事件是真相，統計是視圖**。 +- **author_reputation：衍生視圖、非真相源**（見作者信譽段）：第一階段查詢時聚合；量大後定期物化成標記為快取的 entry。 - 私庫落地：沿用各型既有儲存（workflow=WEBHOOKS KV+KBDB 雙寫、template=KBDB /templates、recipe=RECIPES——現為 KV，**隨 #16 遷 KBDB**），本 SDD **不改**私庫儲存、materialize adapter 打各型既有寫入 API 故遷移對本 SDD 透明。 --- @@ -177,13 +214,15 @@ export 檔（YAML/JSON，二選一，預設 YAML 對齊 workflow.yaml 慣例） ## 驗收標準 完成的定義（CC 完成任何 task 前必須確認）： -- [ ] `POST /public-artifacts/submit`（type=workflow）投稿後，`GET /public-artifacts?type=workflow&q=` 搜得到、帶 market_stat。 -- [ ] `GET /public-artifacts/workflow/:canonical_id` 回市場最佳作者版本；落空回 `{found:false,hint}`。 +- [ ] `POST /public-artifacts/submit`（type=workflow）投稿後，`GET /public-artifacts?type=workflow&q=` 搜得到、帶 market_stat **與 deps_summary**（搜尋結果每項可見「要配哪些東西才跑得起來」，不必取全文）。 +- [ ] `GET /public-artifacts/workflow/:canonical_id` 回市場最佳作者版本（複合分：單品＋作者信譽）；落空回 `{found:false,hint}`；成功取全文有 append `artifact_pull_event`。 +- [ ] `GET /public-artifacts?author=leo` 列出該作者跨型別全部發布；`GET /public-artifacts/authors/leo` 回信譽摘要＋清單。 - [ ] `acr workflow pull ` 把 workflow push 進自己 namespace，且遞迴 pull 其 recipe/template 依賴、列出缺的 component 與待填 credential。 - [ ] `acr workflow export ` 產出自足 YAML，含 dependency_manifest，grep 不到任何機密值。 - [ ] template 同上一套（submit-p/search/pull/export）跑通。 - [ ] 投稿寫 `artifact_submission` 存證 entry；自報 stat 不進真實計數。 - [ ] 一個引用「未具備零件」的 workflow，pull 時停在引導（不落地、不抓程式）。 +- [ ] **資料完整性（可測定義）**：不看任何 UI，僅用公庫 record + 事件記錄（`public_artifact`/`artifact_pull_event`/`artifact_submission`/recipe-stats），就能重建出一個完整的市場網站首頁——作者榜、熱門榜、最新發布、每項的配套需求。缺哪個欄位榜單做不出來＝schema 不合格。 --- @@ -205,3 +244,6 @@ export 檔（YAML/JSON，二選一，預設 YAML 對齊 workflow.yaml 慣例） 3. **MCP/CLI 命名**：型別化措辭（`acr workflow pull`）vs 泛化措辭（`acr artifact pull --type=`）。本 SDD 建議型別化對外、泛化對內。 4. **依賴遞迴深度上限**：建議 5，是否合適。 5. **K5 信任**：資料 artifact submit 全程無人閘是否可接受於**公開**公庫場景（vs 現況多為 self-hosted 私庫 pull）；若未來上真公開公庫，是否要加 import 端的「首次 pull 陌生作者 → AI 摘要依賴清單給人看一眼」的軟提示（非硬閘）。 +6. **選版複合分權重**：多作者同名時「單品 market_stat vs 作者信譽」怎麼配權（含新發布單品數據不足時作者信譽當先驗的冷啟動處理）。 +7. **license 欄位**：維持可選（未填顯示「未聲明」）或投稿必填。 +8. **author 綁認證身份的時點**：現況字串 namespace 夠用（self-hosted 單租戶）；進 SaaS/多人公開市場前必須綁認證（信譽防冒名、獎勵防盜領）——在哪個里程碑動手。 diff --git a/system-dev/docs/3-specs/arcrun/artifact-sharing/requirements.md b/system-dev/docs/3-specs/arcrun/artifact-sharing/requirements.md index 67b8847..ac4f337 100644 --- a/system-dev/docs/3-specs/arcrun/artifact-sharing/requirements.md +++ b/system-dev/docs/3-specs/arcrun/artifact-sharing/requirements.md @@ -44,7 +44,7 @@ Arcrun 的可攜開發物有三類存在 KBDB / KV 的**宣告式 record**： ### 下載側（我想找別人的來用） -- **US-4（搜公庫）**：我想找「發 Slack 通知」的現成 workflow。對 AI 說一句話 → AI 搜公庫，回幾個候選＋各自市場數據（用過幾次、成功率），我挑一個。 +- **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 要我填。 @@ -52,6 +52,7 @@ Arcrun 的可攜開發物有三類存在 KBDB / KV 的**宣告式 record**： - **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 作者信譽段）。 --- @@ -59,7 +60,7 @@ Arcrun 的可攜開發物有三類存在 KBDB / KV 的**宣告式 record**： - **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，新增作者版本不覆蓋）。三型都要。 +- **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 三層樣板）。 @@ -72,6 +73,7 @@ Arcrun 的可攜開發物有三類存在 KBDB / KV 的**宣告式 record**： - **儲存鐵律（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），衍生統計（作者信譽、熱門榜）晚算沒關係。 - **回應語言**：面向使用者的提示訊息正體中文。 --- @@ -90,7 +92,8 @@ Arcrun 的可攜開發物有三類存在 KBDB / KV 的**宣告式 record**： - [ ] US-1/US-2：`acr workflow submit-p ` / `acr template submit-p ` 能把私庫 artifact 投進公庫，成為具名作者版本（回 uuid）。 - [ ] US-3：`acr workflow export ` 產出自足 YAML，含 dependency_manifest、零機密值。 -- [ ] US-4：`acr workflow search ` 回候選 + 各自 market_stat；落空回創作引導。 +- [ ] US-4：`acr workflow search ` 回候選 + 各自 market_stat **+ deps_summary（搜尋結果可見配套需求）**；落空回創作引導。 - [ ] US-5/US-6：`acr workflow pull ` 把定義寫進自己 namespace，且遞迴 pull recipe/template 依賴、報告缺的 component 與待填 credential。 - [ ] US-7：公庫同 canonical_id 多作者版本並存，pull 預設回 market_stat 最佳版本。 - [ ] US-8：搜尋/取用落空回 `{ found:false, hint }` 創作引導，非空陣列。 +- [ ] US-9：`author=` 過濾／作者頁列出該作者跨型別全部發布＋信譽摘要（從 per-uuid stat 聚合，非另立真相源）。 diff --git a/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md b/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md index 1d5e627..22d6415 100644 --- a/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md +++ b/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md @@ -14,17 +14,17 @@ ### 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.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=&limit=&offset=`（搜/列，帶 market_stat，落空回創作引導） - - 驗收：type=workflow 投一筆後搜得到、附 market_stat；q 無命中回 `{found:false,type,query,hint}`。 +- [ ] 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=`（取全文，多作者選市場最佳） - - 驗收：多作者版本並存時回 success_count 最高版；落空回創作引導。 - - 注意：選版邏輯沿用 recipe `fetchMarketStat` per-uuid（泛化為 `/artifact-stats/:uuid` 或復用 recipe-stats）。 +- [ ] 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 不進真實計數。 @@ -34,6 +34,10 @@ - 驗收：`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（單作者量級小）；物化留 5.4。曝光位：搜尋結果作者名旁＋作者頁頂部（design 作者信譽段）。 + --- ## Phase 2：可攜格式 export + 依賴清單 @@ -44,9 +48,9 @@ - 驗收：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.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 已填）。 @@ -98,6 +102,8 @@ - [ ] 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（量大再做）author_reputation 定期物化（cron 聚合寫成標記為快取的 entry；真相仍在 per-uuid stat＋事件） +- [ ] 5.5（future，SaaS/多人市場前置，不在本 SDD 實作）author 綁認證身份（信譽防冒名、獎勵防盜領）＋獎勵機制層（第一階段獎勵＝信譽本身：曝光/排序/信任） --- -- 2.52.0 From af926aaad8c39bb6d9ea92e075a2247906db3f73 Mon Sep 17 00:00:00 2001 From: Leo Date: Tue, 7 Jul 2026 11:14:51 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs(spec):=20tasks=20=E6=98=8E=E6=A8=99?= =?UTF-8?q?=E6=A6=9C=E5=96=AE=E9=A1=9E=EF=BC=9D=E7=89=A9=E5=8C=96=E5=80=99?= =?UTF-8?q?=E9=81=B8=E7=AC=AC=E4=B8=80=E4=BD=8D=EF=BC=88=E8=B7=A8=E4=BD=9C?= =?UTF-8?q?=E8=80=85=E6=A6=9C=E4=B8=8D=E5=8F=AF=20on-read=20=E6=8E=83?= =?UTF-8?q?=E5=85=A8=E5=BA=AB=EF=BC=8C=E5=AF=A9=E6=9F=A5=20#31=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk --- system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md b/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md index 22d6415..f34ab8f 100644 --- a/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md +++ b/system-dev/docs/3-specs/arcrun/artifact-sharing/tasks.md @@ -36,7 +36,7 @@ - [ ] 1.6 作者面：`GET /public-artifacts/authors/:name`（作者頁）＋ author_reputation 查詢時聚合 - 驗收：回信譽摘要（發布數、彙總 success/failure、最近活躍）＋該作者全部發布清單（每項附 market_stat/deps_summary）；聚合值與逐 uuid 手算一致（衍生視圖，不另立真相源）。 - - 注意：第一階段 compute-on-read（單作者量級小）；物化留 5.4。曝光位：搜尋結果作者名旁＋作者頁頂部（design 作者信譽段）。 + - 注意：第一階段 compute-on-read **只限單作者面**（作者頁/作者名旁，量級 10²）；**跨作者榜單（熱門榜/作者榜）不可 on-read 掃全庫**——榜單類＝物化候選第一位，走 5.4 物化快照，非即時聚合。曝光位：搜尋結果作者名旁＋作者頁頂部（design 作者信譽段）。 --- @@ -102,7 +102,7 @@ - [ ] 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（量大再做）author_reputation 定期物化（cron 聚合寫成標記為快取的 entry；真相仍在 per-uuid stat＋事件） +- [ ] 5.4 物化快照：**榜單類（首頁熱門榜/作者榜）＝物化候選第一位**——跨作者/全庫聚合本質不可 on-read 掃全庫，首頁榜單一律走定期物化快照（cron 聚合寫成標記為快取的 entry），非即時聚合；單作者 reputation 量大後同樣收進物化。真相仍在 per-uuid stat＋事件，快照過期重算。 - [ ] 5.5（future，SaaS/多人市場前置，不在本 SDD 實作）author 綁認證身份（信譽防冒名、獎勵防盜領）＋獎勵機制層（第一階段獎勵＝信譽本身：曝光/排序/信任） --- -- 2.52.0