uncle6me-web
5d00e71275
頂層 D22 決策（leo 2026-07-03 拍板）：推什麼由開發環境歸屬決定， Gitea private＝除機敏值/build 產物/.github 外全 push。 解 T1.5 卡點：雲端工人 clone 拿得到 credential-store-migration.md，可就地改寫 SDD。 機敏掃描兩輪通過（新增 189 檔約 2.1MB，node_modules/dist/wasm 照舊排除）。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5.7 KiB
5.7 KiB
workflow-discovery — Requirements
來源：InkStoneCo 總管 GitHub issue #8（[地基1]）。 狀態：草案，待 richblack/總管確認方向後才實作。 建立：2026-06-27 白名單：
.claude/hooks/pre-write-guard.shKNOWN_SDDS 已加docs/3-specs/workflow-discovery（2026-06-27 issue #8 授權）。
1. 問題陳述（北極星入口缺口）
北極星：「AI 先查有沒有現成工作流 → 找到就執行它」。這條的入口現在是斷的。
- 零件可被搜（雖然目前只是 KV substring，非真語意，但有
query介面）：u6u_search_components(query)→/components/search?q=。 - 工作流不可被搜：只有
u6u_list_workflows（list / tag 過濾）與u6u_get_workflow（按 ID）。沒有query入口。 - 根因：工作流的 metadata 沒有可語意比對的
description欄位被穩定落庫。- workflow YAML 慣例上已有
description:（registry/examples/*/workflow.yaml就寫了），但：- 不強制（建工作流可不填）。
- 兩條部署路徑落庫不一致（見 §3 現況核實）。
- 即使有 description，存它的
workflow_metadata是 KBDB record（按 template 精確查），不是可被/entries/search文字/語意搜的 entry。
- workflow YAML 慣例上已有
後果：mira 那批工作流（門鈴/催辦/dashboard/閉環）建了也搜不到；對人也一樣——工作流多了會忘在哪。
2. 現況核實（2026-06-27，已讀 code）
| 事實 | 證據（檔案） |
|---|---|
workflow YAML 已有 description: 慣例 |
registry/examples/webhook-to-http/workflow.yaml:2 |
CLI acr push → POST /webhooks/named，description 已接受但 optional（空字串 fallback） |
cypher-executor/src/routes/webhooks-named.ts:67,96 |
MCP u6u_deploy_workflow → POST /workflows/deploy，另存 workflow_metadata record，slots 無 description，只從 YAML 抓 name |
mcp/src/tools/u6u_deploy_workflow.ts:40-58 |
workflow_metadata record 走 /records/search?template=（精確 template 查，無 q 文字搜尋） |
mcp/src/tools/u6u_list_workflows.ts:26、kbdb/src/routes/records.ts:24 |
KBDB entries 已有真語意 search（issue #7）：/entries/search?mode=semantic，未開 Vectorize → 降級 keyword + capability_hint |
kbdb/src/routes/entries.ts:43-76、kbdb/src/embed.ts |
「零件可語意搜」其實是 KV prefix + substring includes(q)，非真語意（code 自注 Phase 0） |
registry/src/actions/queryComponents.ts:88-132 |
3. 需求（issue #8 三任務 → 可驗收條目）
R1：description slot，建工作流時強制填
- R1.1 workflow 部署時
description為必填；空白/缺失 → 部署被擋（回明確錯誤，像零件那樣不給空白過）。 - R1.2 兩條部署路徑（CLI
acr push/ MCPu6u_deploy_workflow）一致強制——不能一條擋一條放。 - R1.3 description 是能力（API 行為），強制邏輯落在 API（cypher-executor 部署端點），不寫進薄殼介面層（守 rule 07）。
R2：search_workflow(query) 工具
- R2.1 補 MCP
search_workflow(query)（命名對齊既有u6u_search_components形態）。 - R2.2 優先語意搜尋；KBDB 未開 Vectorize → 降級關鍵字（LIKE） + 回
capability_hint告知「叫 CC 幫你開語義查詢」（對齊 issue #7 閉環，不假裝有語義、不假綠）。 - R2.3 Vectorize 的開啟由 AI 詢問用戶觸發（
kbdb_embed:true+ redeploy 建 index），對齊 #7 既有開關，不新造機制。 - R2.4 搜尋限本租戶（org_namespace / owner_id 隔離），不跨租戶洩漏。
- R2.5（對稱補強，選做）同一機制可順帶讓 CLI 有對等
acr workflow search（薄殼一致目標，rule 07 §5；可列為次階段）。
R3：既有工作流回填策略
- R3.1 既有無 description 的 workflow_metadata：設計回填/遷移策略——下次部署強制補、或一次性 migrate 端點提示補。
- R3.2 回填不可破壞既有 workflow 執行（description 只影響可發現性，不影響 trigger）。
4. 跨專案約束（頂層鐵律，issue #8 明列）
- C1 框架級慎改：改了影響全部 arcrun 用戶（含 self-hosted）→ 先 SDD 確認方向再實作。
- C2 flag 紅線：search 是 AI 主動 pull，不掛輪詢、不掛 Actions/cron fan-out。
- C3 範圍邊界：「沒想到要找」那一半（釘選/常用清單）是 mira 私人環境的事，另開 mira issue，不在本 repo。
- C4 薄殼鐵律：能力（強制填、搜尋）落 API；CLI/MCP 只暴露（rule 07）。
- C5 誠實不假綠：未開 Vectorize 就老實降級 + hint，不假裝語義（mindset §7、對齊 #7）。
5. 非目標（明確不做）
- ❌ 把零件搜尋升級成真語意（那是 registry 的 Phase 2，另案；本 SDD 只管 workflow）。
- ❌ 釘選/常用工作流清單（C3，mira 私人環境）。
- ❌ 跨租戶/公庫工作流市場搜尋（workflow 目前是私有 namespace 資產；公庫化是更大的另案）。
- ❌ 自動觸發式 search（C2 flag 紅線）。
6. 開放問題（design 要回答 / 待人拍板）
- Q1：workflow metadata 該從 record 改存成 entry（吃 #7 語意）、還是 records 表自己加 q 搜尋、還是雙寫？（design §2 給方案比較與推薦）
- Q2：強制 description 對既有工作流是「下次部署才強制」還是「立即 migrate」？（R3，design 給推薦）
- Q3：description 從 YAML
description:解析強制，還是部署 API 參數強制，還是兩者？（兩條路徑統一點在哪）