chore: D22 落地——docs/SDD/wiki/CLAUDE.md 進 repo（Gitea private 預設全 push）
頂層 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>
This commit is contained in:
uncle6me-web
@@ -0,0 +1,82 @@
|
||||
# workflow-discovery — Requirements
|
||||
|
||||
> **來源**：InkStoneCo 總管 GitHub issue #8（[地基1]）。
|
||||
> **狀態**：草案，待 richblack/總管確認方向後才實作。
|
||||
> **建立**：2026-06-27
|
||||
> **白名單**：`.claude/hooks/pre-write-guard.sh` KNOWN_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**。
|
||||
|
||||
**後果**：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` / MCP `u6u_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 參數強制，還是兩者？（兩條路徑統一點在哪）
|
||||
Reference in New Issue
Block a user