fix(examples): graph_neighbors 去寫死官方 KBDB URL(審查 🔴)+敏感輸入註記

審查發現: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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015d5jDbuqT5Htwv3Q88XXKk
This commit is contained in:
2026-07-07 09:01:20 +00:00
parent 06ff0e21ce
commit 39d6fdfaff
2 changed files with 35 additions and 15 deletions
@@ -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}"
# POSTheader 認證)
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_idself-hosted 明碼 namespace
- `kbdb_base`(必填):**你自己的 KBDB base URL**(如 `https://kbdb.example.com`)。
workflow 不寫死任何一家的庫——抄示範時帶錯(或照抄別人的值)=查詢與資料流向直接打進別人的庫
KBDB_BASE_URL fallback 同家族坑,勿重蹈)。
- `directed`(預設 false):`true` 只走 subject→object;否則把 triplet 當雙向邊(無向鄰居)
## 為什麼走 kbdb.finally.clickbase custom domain
cypher-executor 對 kbdb 發 fetch,若打同 zone `*.workers.dev` 會踩 CF 1042same-zone self-fetch)。
打 base 的對外 custom domain `kbdb.finally.click`跨 zone、走公網前門,避開 1042
## kbdb_base 該帶哪種 URL1042
cypher-executor 對 kbdb 發 fetch,若打同 zone URL 會踩 CF 1042same-zone self-fetch)。兩條路皆可:
1. 帶 KBDB 的 **custom domain**跨 zone、走公網前門,天然避開 1042);
2. self-hosted 有 **`global_fetch_strictly_public`** compatibility flagcredential-primitives-wasm
Phase 7cypher wrangler.toml),開了之後 **workers.dev URL 亦可**直接帶。
## ⚠️ 尚未 live 驗(待辦)
- **`code` 零件尚未部署到 leo21c**(另線處理)→ 本工作流無法端到端 live 跑。