Leo
cdca296044
leo 07-29 指正：「現在沒有 partner key，改用 namespace，現在沒有發 API key 的機制」。
這些契約寫著 'KBDB partner key（ak_xxx）'／'租戶識別（ak_ 前綴）'＝假資訊源——
總管就是被它騙的（先把範例改成不存在的 {{credential.kbdb_partner_key}}），
不修的話下一個 AI 會再挖同一個坑。
改：kbdb_upsert_block／auth_oauth2／auth_service_account／auth_static_key 的
api_key description，改述為「租戶識別＝Arcrun namespace」＋註明 examples 裡的
ak_test/ak_nonexistent 是測試假值不代表真實格式。
只動 description，不動 schema／欄位名／gherkin_tests
（api_key 欄位名保留——改名會破壞現有 workflow）。
驗：四檔 YAML 可解析、required 不變、欄位清單不變、gherkin_tests 全保留、
ak_test 等測試值原封不動。
人閘：leo 07-29 跑 scripts/component-arm.sh 解保險授權。
96 lines
3.3 KiB
YAML
96 lines
3.3 KiB
YAML
canonical_id: "kbdb_upsert_block"
|
||
display_name: "KBDB Upsert Block"
|
||
category: "data"
|
||
version: "v1"
|
||
wasi_target: "preview1"
|
||
stability: "floating"
|
||
runtime_compat:
|
||
- "cf-workers"
|
||
- "workerd"
|
||
- "wazero"
|
||
constraints:
|
||
max_size_kb: 2048
|
||
max_cold_start_ms: 50
|
||
no_network_syscall: false
|
||
no_filesystem_syscall: true
|
||
io_model: "stdin_stdout_json"
|
||
input_schema:
|
||
type: object
|
||
required: [api_key, page_name, content]
|
||
properties:
|
||
api_key:
|
||
type: string
|
||
description: >-
|
||
租戶識別＝Arcrun namespace（送出時放 X-Arcrun-API-Key header）。
|
||
⚠️ 2026-07-29 更正：舊敘述寫「KBDB partner key（ak_xxx）」，但**現行沒有發
|
||
API key 的機制**（leo 07-29 指正）——namespace 即身分即憑證。
|
||
workflow 裡一律寫 {{credential.arcrun_namespace}}，值由執行期解析（D36）。
|
||
欄位名維持 api_key（改名會破壞現有 workflow），只是它裝的是 namespace。
|
||
page_name:
|
||
type: string
|
||
description: 當 idempotency key。內部用 GET /blocks?page_name= 查找。
|
||
content:
|
||
type: string
|
||
description: block 內容（PATCH 時覆寫，CREATE 時新建）
|
||
type:
|
||
type: string
|
||
description: block type（建立時用，PATCH 時忽略）
|
||
parent_id:
|
||
type: string
|
||
description: 父 block id（建立時用，PATCH 時忽略）
|
||
user_id:
|
||
type: string
|
||
description: 建立時帶入 + lookup 時用來 filter（同 page_name 多 user 共存場景）
|
||
source:
|
||
type: string
|
||
description: 來源標記
|
||
tags_json:
|
||
type: string
|
||
description: tags JSON 字串（PATCH 時轉 array、CREATE 時直傳）
|
||
kbdb_url:
|
||
type: string
|
||
description: KBDB API base（預設 https://kbdb.finally.click）
|
||
output_schema:
|
||
type: object
|
||
properties:
|
||
success:
|
||
type: boolean
|
||
action:
|
||
type: string
|
||
enum: [created, patched]
|
||
description: 實際做了哪個動作
|
||
data:
|
||
type: object
|
||
description: KBDB 回傳（含 block id 等）
|
||
error:
|
||
type: string
|
||
phase:
|
||
type: string
|
||
enum: [lookup, patch, create]
|
||
description: 出錯在哪個階段
|
||
gherkin_tests:
|
||
- scenario: "缺 page_name"
|
||
given: '{"api_key":"ak_x","content":"hi"}'
|
||
then_contains: '"success":false'
|
||
- scenario: "建立新 block"
|
||
given: '{"api_key":"ak_x","page_name":"new-page-uniq","content":"hello"}'
|
||
then_contains: '"action":"created"'
|
||
- scenario: "PATCH 既有 block"
|
||
given: '{"api_key":"ak_x","page_name":"existing-page","content":"updated"}'
|
||
then_contains: '"action":"patched"'
|
||
tags: [data, storage, kbdb, upsert, primitive, idempotent]
|
||
description: |
|
||
Upsert：用 page_name 當 idempotency key。內部 GET 找有沒有同 page_name 的 block，
|
||
找到就 PATCH 不到就 POST 新建。解 arcrun workflow 缺 IF/branch 能力的缺口
|
||
（arcrun.md P1 #1）。mira 7B.3f index-entry per-entity 維護是第一個使用者。
|
||
config_example: |
|
||
upsert_index_entry:
|
||
api_key: "{{api_key}}"
|
||
page_name: "index-{{entity}}"
|
||
parent_id: "{{mira_wiki_index_entities_id}}"
|
||
type: "index-entry"
|
||
user_id: "inkstone_mira_tools"
|
||
source: "ai-canon-wiki"
|
||
content: "{{compose_index_entry.data.text}}"
|
||
tags_json: '["mira-wiki", "ai-generated", "index"]'
|