Merge branch 'feat/step4-node-substitution' into feat/step3-missing-guidance

# Conflicts:
#	system-dev/docs/3-specs/workflow-discovery/tasks.md

cypher-executor/src/routes/cypher.ts

@@ -1,28 +1,63 @@
 import { Hono } from 'hono';
 import type { Bindings } from '../types';
 import { handleCypherSearch, handleCypherExecute } from '../actions/cypher-handlers';
+import { searchByTarget } from '../actions/target-search';
 
 export const cypherRouter = new Hono<{ Bindings: Bindings }>();
 
+const VALID_TARGETS = new Set(['component', 'recipe', 'workflow']);
+
 // POST /cypher/search — 三元組 → 解析節點 → 語意搜尋零件 → 回傳 Cypher JSON (開發友善格式)
+//
+// t159（leo 07-31）：加 `target` 指定搜尋對象（component／recipe／workflow）＋`query` 名字搜尋。
+//   - triplets（不給 target）＝混搜兩庫＋意圖節點替換（步驟 4）
+//   - triplets + target=component|recipe＝只查該庫
+//   - query + target＝名字搜尋，各自走**既有**機制（registry search／私庫 RECIPES／workflows/search）
 cypherRouter.post('/cypher/search', async (c) => {
-  const body = await c.req.json() as { triplets?: unknown; mode?: unknown };
+  const body = await c.req.json() as { triplets?: unknown; mode?: unknown; target?: unknown; query?: unknown };
   const rawTriplets = body?.triplets;
 
+  // ── target 驗證（component / recipe / workflow）─────────────────────────────
+  const target = typeof body?.target === 'string' ? body.target : undefined;
+  if (target !== undefined && !VALID_TARGETS.has(target)) {
+    return c.json({ error: `target 只接受 component／recipe／workflow，收到「${target}」` }, 400);
+  }
+
+  // ── query 名字搜尋分支（需 target）──────────────────────────────────────────
+  const query = typeof body?.query === 'string' ? body.query.trim() : '';
+  if (query) {
+    if (!target) {
+      return c.json({ error: '給 query 必須同時給 target（component／recipe／workflow），指明要搜哪個庫' }, 400);
+    }
+    const apiKey = c.req.header('X-Arcrun-API-Key') ?? undefined;
+    const r = await searchByTarget(target as 'component' | 'recipe' | 'workflow', query, c.env, apiKey);
+    if (!r.ok) return c.json({ error: r.error }, r.status);
+    return c.json(r.body);
+  }
+
   if (!Array.isArray(rawTriplets) || rawTriplets.length === 0) {
-    return c.json({ error: 'triplets 必須為非空字串陣列' }, 400);
+    return c.json({ error: 'triplets 必須為非空字串陣列（或給 query + target 做名字搜尋）' }, 400);
   }
 
   // t158「部署≠發現」：mode=compile＝純編圖（安裝器/acr push 的複製路徑，零存在性查詢）；
   // 預設 discover＝誠實查詢（AI 問「有沒有」的既有契約，not_found＋指路照舊）。
   const mode = body?.mode === 'compile' ? 'compile' : 'discover';
 
+  // target 限庫只屬於 discover（compile＝純複製，不查任何庫，target 無意義）
+  if (target && mode === 'compile') {
+    return c.json({ error: 'mode=compile（複製路徑）不查庫，不接受 target；要指定搜尋對象請用 discover（預設）' }, 400);
+  }
+  // workflow 是名字搜尋，不參與三元組編圖——請帶 query
+  if (target === 'workflow') {
+    return c.json({ error: 'target=workflow 是名字搜尋，請改帶 { target: "workflow", query: "..." }（不吃 triplets）' }, 400);
+  }
+
   try {
     const now = new Date();
     const timestamp = now.toISOString();
     const versionId = `search-v1-${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`;
 
-    const result = await handleCypherSearch(rawTriplets, c.env, mode);
+    const result = await handleCypherSearch(rawTriplets, c.env, mode, target as 'component' | 'recipe' | undefined);
 
     const response = {
       version: versionId,

cypher-executor/src/routes/webhooks-named.ts

@@ -30,6 +30,7 @@ import type { GraphNode } from '../types';
 import { extractCronExpr } from '../lib/cron-match';
 import { updateCronIndexEntry, CRON_INDEX_KEY } from '../lib/cron-index';
 import { recordTelemetry } from '../lib/telemetry';
+import { fetchTenantWorkflowSearch } from '../lib/workflow-search';
 
 export const webhooksNamedRouter = new Hono<{ Bindings: Bindings }>();
 
@@ -177,16 +178,9 @@ webhooksNamedRouter.get('/workflows/search', async (c) => {
   // 預設優先語意；caller 傳 mode=keyword 才強制關鍵字。KBDB 端未開 Vectorize 會自動降級。
   const mode = c.req.query('mode') === 'keyword' ? 'keyword' : 'semantic';
 
-  const base = (c.env.KBDB_BASE_URL ?? 'https://arcrun-kbdb.uncle6-me.workers.dev').replace(/\/$/, '');
-  const headers: Record<string, string> = { 'Content-Type': 'application/json' };
-  if (c.env.KBDB_INTERNAL_TOKEN) headers['Authorization'] = `Bearer ${c.env.KBDB_INTERNAL_TOKEN}`;
-  const params = new URLSearchParams({
-    q,
-    owner_id: apiKey,          // 租戶隔離（只搜本租戶的 workflow）
-    entry_type: 'workflow',    // base 通用 filter（Q4），只回 workflow entry
-    mode,
-  });
-  const res = await fetch(`${base}/entries/search?${params.toString()}`, { headers });
+  // KBDB 轉發抽到 lib/workflow-search.ts（t159 target 參數）：本路由與
+  // POST /cypher/search { target:"workflow" } 共用同一條路，行為必然一致。
+  const res = await fetchTenantWorkflowSearch(c.env, apiKey, q, mode);
   return new Response(res.body, { status: res.status, headers: { 'Content-Type': 'application/json' } });
 });