From 39d6fdfaff277dcb61a63531dde6cf74e310cfa0 Mon Sep 17 00:00:00 2001 From: arcrun-subagent Date: Tue, 7 Jul 2026 09:01:20 +0000 Subject: [PATCH] =?UTF-8?q?fix(examples):=20graph=5Fneighbors=20=E5=8E=BB?= =?UTF-8?q?=E5=AF=AB=E6=AD=BB=E5=AE=98=E6=96=B9=20KBDB=20URL=EF=BC=88?= =?UTF-8?q?=E5=AF=A9=E6=9F=A5=20=F0=9F=94=B4=EF=BC=89=EF=BC=8B=E6=95=8F?= =?UTF-8?q?=E6=84=9F=E8=BC=B8=E5=85=A5=E8=A8=BB=E8=A8=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 審查發現：workflow.yaml 寫死 kbdb.finally.click ＝ KBDB_BASE_URL fallback 同家族坑 （self-hosted 用戶照抄示範，查詢與資料流向直接打進官方庫）。 改法： - fetch_triplets base URL 參數化為 {{input.kbdb_base}}（每次呼叫帶），yaml 檔頂加醒目 警示「先改成你自己的 KBDB URL」；grep 證兩檔零 finally.click 殘留。 - 1042 註解保留並補一句：self-hosted 有 global_fetch_strictly_public flag （credential-primitives-wasm Phase 7），開了 workers.dev URL 亦可帶。 - description.md 參數表加 kbdb_base（必填）＋觸發範例改自有域名佔位＋補 「敏感輸入請用 POST /query（GET /q/ 的 query string 會進各層 log）」。 tsc 乾淨、全套 50 passed（1 失敗為 main 既有 executor.test.ts 斷言漂移，無關）。 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk --- .../examples/graph-neighbors/description.md | 22 ++++++++++----- .../examples/graph-neighbors/workflow.yaml | 28 +++++++++++++------ 2 files changed, 35 insertions(+), 15 deletions(-) diff --git a/registry/examples/graph-neighbors/description.md b/registry/examples/graph-neighbors/description.md index bbf0d6d..89856b2 100644 --- a/registry/examples/graph-neighbors/description.md +++ b/registry/examples/graph-neighbors/description.md @@ -16,14 +16,17 @@ ## 怎麼觸發 ```bash -# GET（最像原本的 /graph/neighbors） -curl "https://cypher.arcrun.dev/q/{namespace}/graph_neighbors?node=Arcrun&depth=2&template=graph_triplet&namespace={namespace}" +# GET（最像原本的 /graph/neighbors）——{你的-cypher-domain}/{你的-kbdb-domain} 換成自己的部署 +curl "https://{你的-cypher-domain}/q/{namespace}/graph_neighbors?node=Arcrun&depth=2&template=graph_triplet&namespace={namespace}&kbdb_base=https://{你的-kbdb-domain}" # POST（header 認證） -curl -X POST https://cypher.arcrun.dev/webhooks/named/graph_neighbors/query \ +curl -X POST https://{你的-cypher-domain}/webhooks/named/graph_neighbors/query \ -H "X-Arcrun-API-Key: {namespace}" \ - -d '{"node":"Arcrun","depth":2,"template":"graph_triplet","namespace":"{namespace}"}' + -d '{"node":"Arcrun","depth":2,"template":"graph_triplet","namespace":"{namespace}","kbdb_base":"https://{你的-kbdb-domain}"}' ``` + +> ⚠️ **敏感輸入請用 `POST /query`**：`GET /q/` 的參數走 query string，會進 CF / proxy / access log +> 各層日誌；node 名、namespace 等若屬敏感，改走 POST body。 回傳（最終節點輸出本身，非信封）： ```json { "success": true, "start": "Arcrun", "depth": 2, "directed": false, @@ -36,11 +39,16 @@ curl -X POST https://cypher.arcrun.dev/webhooks/named/graph_neighbors/query \ - `depth`（預設 1）：最大跳數 - `template`（必填）：triplet 記錄的 base template id（⚠️ 以實際部署的 kbdb-graph-plugin triplet template 為準） - `namespace`（必填）：租戶 owner_id（self-hosted 明碼 namespace） +- `kbdb_base`（必填）：**你自己的 KBDB base URL**（如 `https://kbdb.example.com`）。 + workflow 不寫死任何一家的庫——抄示範時帶錯（或照抄別人的值）＝查詢與資料流向直接打進別人的庫 + （KBDB_BASE_URL fallback 同家族坑，勿重蹈）。 - `directed`（預設 false）：`true` 只走 subject→object；否則把 triplet 當雙向邊（無向鄰居） -## 為什麼走 kbdb.finally.click（base custom domain） -cypher-executor 對 kbdb 發 fetch，若打同 zone `*.workers.dev` 會踩 CF 1042（same-zone self-fetch）。 -打 base 的對外 custom domain `kbdb.finally.click` 屬跨 zone、走公網前門，避開 1042。 +## kbdb_base 該帶哪種 URL（1042） +cypher-executor 對 kbdb 發 fetch，若打同 zone URL 會踩 CF 1042（same-zone self-fetch）。兩條路皆可： +1. 帶 KBDB 的 **custom domain**（跨 zone、走公網前門，天然避開 1042）； +2. self-hosted 有 **`global_fetch_strictly_public`** compatibility flag（credential-primitives-wasm + Phase 7，cypher wrangler.toml），開了之後 **workers.dev URL 亦可**直接帶。 ## ⚠️ 尚未 live 驗（待辦） - **`code` 零件尚未部署到 leo21c**（另線處理）→ 本工作流無法端到端 live 跑。 diff --git a/registry/examples/graph-neighbors/workflow.yaml b/registry/examples/graph-neighbors/workflow.yaml index 0ac4aec..4688bd4 100644 --- a/registry/examples/graph-neighbors/workflow.yaml +++ b/registry/examples/graph-neighbors/workflow.yaml @@ -5,17 +5,28 @@ description: > POST /webhooks/named/:name/query），把 workflow 最終節點輸出直接當 HTTP response 拿回， 取代 graph plugin 內建的 GET /graph/neighbors。對照 kbdb-graph-plugin graph-traverse.ts 的記憶體 BFS。 -# ── 為什麼走 base custom domain（kbdb.finally.click）而非 workers.dev ── -# cypher-executor 執行 http_request 節點時對 kbdb 發 fetch。若打 *.uncle6-me.workers.dev 同 zone -# 會踩 CF 1042（same-zone self-fetch）。打 base 的對外 custom domain kbdb.finally.click 屬跨 zone， -# 前門公網進出，避開 1042（同 credential-primitives-wasm Phase 7 的 global_fetch_strictly_public 精神）。 +# ══════════════════════════════════════════════════════════════════════════════ +# ⚠️ 先改成你自己的 KBDB URL（self-hosted 必看） +# fetch_triplets 的 base URL 走 {{input.kbdb_base}} 參數（每次呼叫帶），**沒有寫死官方庫**。 +# 照抄本示範時，把觸發參數 kbdb_base 換成你自己部署的 KBDB 對外 URL—— +# 抄了別人的值＝你的查詢與資料流向直接打進別人的庫（KBDB_BASE_URL fallback 同家族坑）。 +# ══════════════════════════════════════════════════════════════════════════════ + +# ── 1042 與 kbdb_base 該帶哪種 URL ── +# cypher-executor 執行 http_request 節點時對 kbdb 發 fetch。若打同 zone URL 會踩 CF 1042 +# （same-zone self-fetch）。兩條路皆可： +# a) 帶 KBDB 的 custom domain（跨 zone、走公網前門，天然避開 1042）； +# b) self-hosted 有 `global_fetch_strictly_public` compatibility flag +# （credential-primitives-wasm Phase 7，cypher wrangler.toml），開了之後 +# workers.dev URL 亦可直接帶。 # ── 觸發（同步查詢 trigger，非 202）── -# GET https://cypher.arcrun.dev/q/{namespace}/graph_neighbors?node=Arcrun&depth=2&template=graph_triplet&namespace={namespace} -# POST https://cypher.arcrun.dev/webhooks/named/graph_neighbors/query +# GET https://{你的-cypher-domain}/q/{namespace}/graph_neighbors?node=Arcrun&depth=2&template=graph_triplet&namespace={namespace}&kbdb_base=https://{你的-kbdb-domain} +# POST https://{你的-cypher-domain}/webhooks/named/graph_neighbors/query # -H "X-Arcrun-API-Key: {namespace}" -# -d '{"node":"Arcrun","depth":2,"template":"graph_triplet","namespace":"{namespace}"}' +# -d '{"node":"Arcrun","depth":2,"template":"graph_triplet","namespace":"{namespace}","kbdb_base":"https://{你的-kbdb-domain}"}' # → 直接回 { success, start, depth, directed, neighbors:[...], count }（最終節點輸出本身）。 +# （敏感輸入用 POST /query：GET /q/ 的 query string 會進各層 log，見 description.md。） flow: - "input >> ON_SUCCESS >> fetch_triplets" @@ -27,10 +38,11 @@ config: # 回 { success, records:[{ record_id, values:{subject,predicate,object} }], count }。 # ⚠️ template 名（此處 {{input.template}}，預設由呼叫者帶 graph_triplet）以實際部署的 # kbdb-graph-plugin triplet template id 為準——上線前對一次。 + # ⚠️ base URL 由呼叫者帶（{{input.kbdb_base}}）——不寫死任何一家的庫（見檔頂警示）。 fetch_triplets: component: http_request method: GET - url: "https://kbdb.finally.click/records/by-template/{{input.template}}?owner_id={{input.namespace}}" + url: "{{input.kbdb_base}}/records/by-template/{{input.template}}?owner_id={{input.namespace}}" headers: Accept: "application/json"