From d8028eabe076d0681d1141ad5847c664163e786c Mon Sep 17 00:00:00 2001
From: richblack <leo21c@gmail.com>
Date: Thu, 16 Apr 2026 14:34:16 +0800
Subject: [PATCH] feat(registry): aliases.yaml scope synonym table + contract
 aliases field

- registry/aliases.yaml: scope-level synonym table for 21 built-in components
  covers api (gmail/google_sheets/telegram/line_notify/http_request),
  data (string/array/date/number/json), logic (if/foreach/switch/try_catch/wait),
  ai scopes; includes zh/en/abbrev variants
- types.ts: add optional aliases[] field to ComponentContractSchema
- CONTRIBUTING.md: explain aliases auto-merge from aliases.yaml vs manual contract aliases

Note: manual maintenance for now; aliases.yaml becomes KBDB synonym graph seed data
when KBDB is introduced.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CONTRIBUTING.md       |  21 +++++++
 registry/aliases.yaml | 134 ++++++++++++++++++++++++++++++++++++++++++
 registry/src/types.ts |   4 ++
 3 files changed, 159 insertions(+)
 create mode 100644 registry/aliases.yaml

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 456aab7..3298d27 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -143,6 +143,27 @@ description: "Gmail 發信零件"   # 只是名稱的同義詞，搜不到任何
 
 原則：把這個 description 給一個不知道這個零件存在的人看，他能判斷「這就是我要的東西」嗎？
 
+### aliases（搜尋同義詞）
+
+arcrun 在 `registry/aliases.yaml` 維護一份 scope 級別的同義詞表。當你的零件 `canonical_id` 以已知 scope 為前綴，Registry 建立搜尋索引時會**自動**把對應的同義詞合併進去，不需要在 contract 裡手動填。
+
+例如 `canonical_id: google_sheets_append`，Registry 會自動從 aliases.yaml 取得 `google_sheets` scope 的同義詞（`gsheets`、`試算表`、`spreadsheet`...），搜這些詞都能找到你的零件。
+
+**如果你的零件有額外的情境同義詞**（超出 scope 範圍），可以在 contract 內手動補充：
+
+```yaml
+canonical_id: "google_sheets_append"
+aliases:
+  - "新增資料列"       # 情境同義詞，超出 scope 範圍
+  - "insert row"
+  # google_sheets scope 的同義詞（gsheets / 試算表 / spreadsheet...）
+  # 由 registry/aliases.yaml 自動合併，不需要重複填寫
+```
+
+**想新增新 scope 的同義詞**（例如你要加一個 `notion` 零件）：在 `registry/aliases.yaml` 的對應 category 下加一個新 key，開 PR，merge 後所有以 `notion_` 開頭的零件都自動繼承。
+
+> 這個機制目前是手工維護。未來接入 KBDB 後，`canonical_id` 將獲得系統派發的唯一 hash id，同義詞表將成為 KBDB synonym graph 的初始資料。
+
 ---
 
 ## TinyGo 零件開發
diff --git a/registry/aliases.yaml b/registry/aliases.yaml
new file mode 100644
index 0000000..bfc58d8
--- /dev/null
+++ b/registry/aliases.yaml
@@ -0,0 +1,134 @@
+# registry/aliases.yaml
+#
+# Scope 級別的搜尋同義詞表。
+# 當 canonical_id 以某個 scope 為前綴時，Registry 建立 Vectorize 索引時
+# 會自動把對應的 aliases 合併進去，不需要零件作者手動填寫。
+#
+# 維護原則：
+# - 這裡只放 scope 的同義詞，不放動作詞（append / send / read）
+# - 中英文、縮寫、口語化說法都放進來
+# - 未來接入 KBDB 後，此表將成為 KBDB synonym graph 的初始資料
+#
+# 新增 scope：開 PR，在對應 category 下加一個新 key
+
+scopes:
+
+  # ── 整合類（category: api）──────────────────────────────────────────────────
+
+  gmail:
+    - email
+    - mail
+    - 電子郵件
+    - 信件
+    - google mail
+    - 寄信
+    - 發信
+
+  google_sheets:
+    - gsheets
+    - spreadsheet
+    - google 試算表
+    - 試算表
+    - google sheet
+    - sheets
+    - excel              # 使用者常用 excel 描述試算表需求
+
+  telegram:
+    - tg
+    - telegram bot
+    - bot 通知
+    - 機器人通知
+
+  line_notify:
+    - line
+    - line 通知
+    - line bot
+    - 推播
+
+  http_request:
+    - http
+    - api call
+    - fetch
+    - rest
+    - webhook
+    - curl
+    - 外部 api
+    - 呼叫 api
+
+  # ── 資料處理類（category: data）────────────────────────────────────────────
+
+  string:
+    - 字串
+    - text
+    - 文字
+    - str
+
+  array:
+    - 陣列
+    - list
+    - 清單
+    - 列表
+
+  date:
+    - 日期
+    - time
+    - 時間
+    - datetime
+    - timestamp
+
+  number:
+    - 數字
+    - 數值
+    - numeric
+    - math
+    - 計算
+
+  json:
+    - 物件
+    - object
+    - 資料轉換
+
+  # ── 控制流類（category: logic）─────────────────────────────────────────────
+
+  if:
+    - 條件
+    - condition
+    - 判斷
+    - branch
+    - 分支
+
+  foreach:
+    - 迴圈
+    - loop
+    - iterate
+    - 遍歷
+    - each
+
+  switch:
+    - 多路由
+    - route
+    - 路由
+    - case
+
+  try_catch:
+    - 錯誤處理
+    - error handling
+    - fallback
+    - 例外
+
+  wait:
+    - 延遲
+    - delay
+    - sleep
+    - 等待
+
+  # ── AI 類（category: ai）────────────────────────────────────────────────────
+
+  ai:
+    - llm
+    - gpt
+    - claude
+    - 語言模型
+    - 自然語言
+    - 智慧
+    - 生成
diff --git a/registry/src/types.ts b/registry/src/types.ts
index 3118228..c156429 100644
--- a/registry/src/types.ts
+++ b/registry/src/types.ts
@@ -46,6 +46,10 @@ export const ComponentContractSchema = z.object({
   no_network_syscall: z.boolean().optional(),
   service_binding_key: z.string().optional(),
   description: z.string().optional(),
+  // aliases：搜尋同義詞，不作為識別符使用
+  // 從 registry/aliases.yaml 的 scope 同義詞表自動合併，也可在 contract 內手動補充
+  // 未來接入 KBDB 後，canonical_id 將獲得系統派發的唯一 hash id
+  aliases: z.array(z.string()).optional(),
   tags: z.array(z.string()).optional(),
 });