為 hash-id 新增 key 子命令並拆出獨立的名稱正規化模組，收斂雜湊組法為單一入口 #54

2026-09-08T02:34:18Z

jiantw83 commented

2026-09-08 02:34:18 +00:00

摘要

需求描述：多個技能各自手動拼接「計畫名稱」與「owner/repo」字串再算雜湊，重複邏輯容易長出分歧的正規化寫法，也讓 hash-id 混雜了業務規則、職責不單純；本工作包為雜湊組法提供統一收單一入口。
計畫名稱：jsc 技能組待辦總表 2026-09-07
計畫頁：無
分析頁：https://gitea.jsc.idv.tw/knowledges/ANALYZE/wiki/ANALYZE_0F1898406BE708ADBBD6DF66AFB16F3D0D8ACA0C#wp-02-雜湊組法收單一入口

變更內容

檔案	為什麼改
`tools/hash-id`	新增 `key` 子命令（`hash-id key <計畫名稱> <owner/repo>`），將計畫名稱正規化後以 `\|` 接上 owner/repo 再算雜湊，提供統一組法入口，讓多個技能不必各自接字串；改為呼叫獨立的正規化模組，不再內嵌業務規則。
`tools/normalize-name.sh`（新增）	把正規化規則（Unicode NFC、去頭尾空白、內部連續空白壓一、英數全形轉半形，大小寫不變）獨立成檔案，讓 hash-id 只負責算雜湊，職責單純，也方便其他工具日後重用同一套正規化邏輯。

設計重點

正規化邏輯與雜湊計算分離：hash-id 只呼叫 tools/normalize-name.sh，避免發散式變化（同一檔案承擔兩種變動理由）。
正規化規則刻意保留大小寫差異，只處理空白與全半形問題，避免不同計畫名稱被誤判為相同鍵值。
經 jsc-review:code-review 六組壞味道審查兩輪：第一輪抓到一則中嚴重度（正規化邏輯不該與雜湊職責混在同一檔案）與四則低嚴重度（神秘命名、魔術數字、註解夾帶審查過程痕跡、註解契約缺參數說明與範例），全部修正後第二輪覆核通過（PASS）。

測試結果

hash-id key "我的計畫" "plugins/sdlc" 與手接字串 hash-id "我的計畫|plugins/sdlc" 輸出同一個 40 碼雜湊，驗證統一組法入口與手動拼接等價。
三種空白寫法（半形一格、半形兩格、全形空白）正規化後輸出同一雜湊，驗證空白正規化規則生效。
ABC 計畫 與 abc 計畫 正規化後輸出不同雜湊，驗證大小寫不被抹掉。
bash -n 語法檢查通過；comment-scope.sh sweep 掃描通過，無殘留審查痕跡註解。
API 文件稽核：swagger-detect.sh 判定此存放庫不支援 Swagger（結束碼 1），已依規則跳過。

前置 Push Request

無

## 摘要 - 需求描述：多個技能各自手動拼接「計畫名稱」與「owner/repo」字串再算雜湊，重複邏輯容易長出分歧的正規化寫法，也讓 hash-id 混雜了業務規則、職責不單純；本工作包為雜湊組法提供統一收單一入口。 - 計畫名稱：jsc 技能組待辦總表 2026-09-07 - 計畫頁：無 - 分析頁：https://gitea.jsc.idv.tw/knowledges/ANALYZE/wiki/ANALYZE_0F1898406BE708ADBBD6DF66AFB16F3D0D8ACA0C#wp-02-雜湊組法收單一入口 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/hash-id` | 新增 `key` 子命令（`hash-id key <計畫名稱> <owner/repo>`），將計畫名稱正規化後以 `\|` 接上 owner/repo 再算雜湊，提供統一組法入口，讓多個技能不必各自接字串；改為呼叫獨立的正規化模組，不再內嵌業務規則。 | | `tools/normalize-name.sh`（新增） | 把正規化規則（Unicode NFC、去頭尾空白、內部連續空白壓一、英數全形轉半形，大小寫不變）獨立成檔案，讓 hash-id 只負責算雜湊，職責單純，也方便其他工具日後重用同一套正規化邏輯。 | ## 設計重點 - 正規化邏輯與雜湊計算分離：`hash-id` 只呼叫 `tools/normalize-name.sh`，避免發散式變化（同一檔案承擔兩種變動理由）。 - 正規化規則刻意保留大小寫差異，只處理空白與全半形問題，避免不同計畫名稱被誤判為相同鍵值。 - 經 jsc-review:code-review 六組壞味道審查兩輪：第一輪抓到一則中嚴重度（正規化邏輯不該與雜湊職責混在同一檔案）與四則低嚴重度（神秘命名、魔術數字、註解夾帶審查過程痕跡、註解契約缺參數說明與範例），全部修正後第二輪覆核通過（PASS）。 ## 測試結果 - `hash-id key "我的計畫" "plugins/sdlc"` 與手接字串 `hash-id "我的計畫|plugins/sdlc"` 輸出同一個 40 碼雜湊，驗證統一組法入口與手動拼接等價。 - 三種空白寫法（半形一格、半形兩格、全形空白）正規化後輸出同一雜湊，驗證空白正規化規則生效。 - `ABC 計畫` 與 `abc 計畫` 正規化後輸出不同雜湊，驗證大小寫不被抹掉。 - `bash -n` 語法檢查通過；`comment-scope.sh sweep` 掃描通過，無殘留審查痕跡註解。 - API 文件稽核：`swagger-detect.sh` 判定此存放庫不支援 Swagger（結束碼 1），已依規則跳過。 ## 前置 Push Request - 無

jiantw83 added 1 commit 2026-09-08 02:34:19 +00:00

feat(gitea): 為 hash-id 新增 key 子命令並拆出獨立的名稱正規化模組 96a0772d65

為什麼:多個技能各自手動拼接計畫名稱與 owner/repo 字串再算雜湊,重複邏輯容易長出分歧的正規化寫法,也讓 hash-id 混雜了業務規則,職責變得不單純。

做了什麼:
- hash-id 新增 key 子命令(hash-id key <計畫名稱> <owner/repo>),將計畫名稱正規化後以 | 分隔接上 owner/repo 再計算雜湊,提供統一的組法入口,讓其他技能不必各自接字串。
- 將正規化規則(Unicode NFC、去除頭尾空白、內部連續空白壓成一個、全形英數轉半形,大小寫維持不變)獨立成 tools/normalize-name.sh,hash-id 只呼叫它,不再內嵌業務規則,保持雜湊職責單純,也方便日後其他工具重用同一套正規化邏輯。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

admin merged commit 967faa4f13 into develop

2026-09-08 02:45:25 +00:00

admin deleted branch feat/hash-id-key-subcommand

2026-09-08 02:45:25 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/gitea#54