From 475c95aaae63d714105e14a4750d442ca7d1a4c8 Mon Sep 17 00:00:00 2001
From: richblack <leo21c@gmail.com>
Date: Sun, 17 May 2026 11:07:31 +0800
Subject: [PATCH] feat(kbdb_upsert_block): add create_only flag (#2 stub
 support)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

leo 反饋 2026-05-17：「至少建一個 placeholder 給未來累積」
但 upsert 預設 PATCH 既有會把完整 wiki 覆寫成 stub。

新 input field：create_only (bool, default false)
  - false (預設)：既有 → PATCH (傳統 upsert 行為)
  - true：既有 → return action='exists' 不動，避免 stub 覆寫 full wiki

用於 wiki_synthesis V3.1 referenced_entities → ensure_stub_wiki_page 場景。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 registry/components/kbdb_upsert_block/main.go | 27 ++++++++++++-------
 1 file changed, 18 insertions(+), 9 deletions(-)

diff --git a/registry/components/kbdb_upsert_block/main.go b/registry/components/kbdb_upsert_block/main.go
index 29b7453..a4594ee 100644
--- a/registry/components/kbdb_upsert_block/main.go
+++ b/registry/components/kbdb_upsert_block/main.go
@@ -25,15 +25,17 @@ func hostHttpRequest(
 ) uint32
 
 type Input struct {
-	KBDBUrl  string `json:"kbdb_url"`  // optional
-	APIKey   string `json:"api_key"`   // 必填
-	PageName string `json:"page_name"` // 必填，當 idempotency key
-	Content  string `json:"content"`   // 必填
-	Type     string `json:"type"`      // optional（建立時用，PATCH 時忽略）
-	ParentID string `json:"parent_id"` // optional（建立時用，PATCH 時忽略）
-	UserID   string `json:"user_id"`   // optional（建立時用 + lookup filter）
-	Source   string `json:"source"`    // optional
-	TagsJSON string `json:"tags_json"` // optional（完整覆寫）
+	KBDBUrl    string `json:"kbdb_url"`    // optional
+	APIKey     string `json:"api_key"`     // 必填
+	PageName   string `json:"page_name"`   // 必填，當 idempotency key
+	Content    string `json:"content"`     // 必填
+	Type       string `json:"type"`        // optional（建立時用，PATCH 時忽略）
+	ParentID   string `json:"parent_id"`   // optional（建立時用，PATCH 時忽略）
+	UserID     string `json:"user_id"`     // optional（建立時用 + lookup filter）
+	Source     string `json:"source"`      // optional
+	TagsJSON   string `json:"tags_json"`   // optional（完整覆寫）
+	CreateOnly bool   `json:"create_only"` // 2026-05-17 加：若 true + 已存在 → 不 PATCH，回 action="exists"
+	                                       // 用於 stub creation 場景（避免 stub 覆寫已存在的 full wiki）
 }
 
 var dummy [1]byte
@@ -181,6 +183,13 @@ func main() {
 	}
 
 	if existing != nil {
+		// CreateOnly 模式：已存在 → 不動，回 action="exists"（給 stub creation 用，
+		// 避免後續 raw 提到同 entity 時把完整 wiki 覆寫成 stub）
+		if input.CreateOnly {
+			writeResult("exists", existing)
+			return
+		}
+
 		// PATCH 路徑
 		existingID, _ := existing["id"].(string)
 		if existingID == "" {