前言¶
DeepSeek Harness（DSH）的插件生態致力於通過插件擴展智能體的能力。在智能體開發中，維護架構一致性是一個常見痛點：代碼變更容易導致設計文檔或架構圖失效，人工同步成本高。dsh-normify 針對這一場景，提供了一套從數據建模、校驗到可視化的完整閉環方案。
這是什麼¶
dsh-normify 是一個 DeepSeek Harness 插件，由 yan-mc 維護。它的核心定位是“歸一化框架圖構建器”，旨在將整個項目描述成一棵“人機共讀”的分形模塊樹。
插件將功能拆分爲三個面向對象：
* 面向 AI：提供 normify-gen 技能以及 31 個 normify_* 工具。這套工具鏈支持“先建圖後編程、伴隨編程改圖”的流程，讓模型先建立結構樹，再進行逐個模塊的實現。
* 面向引擎：執行零容忍校驗和確定性編譯。包括寫時的 L1 校驗、全項目的 L2 校驗以及最終產出的 L3 凍結回執。
* 面向人：輸出一個單文件交互式架構圖（normify.html）。它零外部依賴，雙擊即開，支持逐層下鑽、API 直連箭頭以及深鏈接。
核心特性¶
1. 數據模型：分形結構¶
插件使用分形模塊樹結構，實現零冗餘數據模型。整個數據庫由無數個結構相同的“基本模塊”構成，每個模塊對應一個 Markdown 文件。數據模型只存儲 parent 關係，children 通過索引導出，避免數據不一致。API 信息只在葉子節點存儲一次，編譯期生成索引。路徑式 ID 配合不變 UID，確保 AI 能準確定位模塊。
2. 三層校驗機制¶
插件通過三層校驗保證數據一致性：
* L1（寫時校驗）：每次寫入時檢查必填字段、ID 文法、UID、Parent 一致性等。
* L2（全項目校驗）：通過 normify_validate 檢查全局唯一性、文件與 ID 映射、葉子/非葉子規則、API 鍵唯一性、依賴目標以及架構規則。
* L3（凍結回執）：通過 normify_build 執行，任何 error 都不產出產物，產出即進行 SHA-256 凍結並記錄在 receipt.json 中。
3. 伴隨開發流程¶
插件提供了一套完整的伴隨開發流程，確保代碼與架構圖同步：
1. 使用 change_open 開啓變更。
2. 使用 brief 和 check 確認目標。
3. 使用 module_batch(state=planned) 批量建立計劃態模塊。
4. 執行代碼編寫。
5. 使用 module_refresh(activate) 激活模塊。
6. 使用 change_close 收尾，該步驟強制要求 0 error。
4. 單文件交互式架構圖¶
生成的 normify.html 是一個零依賴的單文件。它支持逐層下鑽、搜索、大綱視圖以及中英切換。其核心亮點是“API 直連箭頭”，箭頭可以錨定到具體的 API 行，而不是僅僅落在框邊。此外，支持深鏈接、縮放、懸停高亮以及明暗主題。
5. 架構規則強制執行¶
通過 policy.yml 定義架構規則，包括依賴方向、禁止依賴、無環、深度限制、跨樹依賴策略以及命名規範。normify_validate 和 normify_build 會強制執行這些規則，違規時無法通過。
安裝與啓用¶
官方資料未提供具體的安裝命令。該插件位於 DSH 插件目錄，請通過 SkillHub 目錄頁面進行查找和安裝。
典型用法¶
1. 初始化項目¶
使用 normify_project_init 工具建立項目目錄和默認架構規則。
2. 開發變更流程¶
按照以下步驟進行伴隨開發：
change_open → brief → check → module_batch(state=planned) → 【寫代碼】
→ module_refresh(activate) → change_close(0 error 強制)
3. 檢測漂移與修復¶
當代碼變更導致架構圖數據與實際不符時，使用 normify_sync 檢出漂移，並定位受影響的模塊。
4. 獲取工具參數¶
使用 normify_help topic:tool:<工具名> 獲取指定工具的參數樹，以便 AI 正確調用工具。
適用場景與注意¶
- 適用場景：適合需要嚴格結構化文檔和架構約束的智能體開發項目。插件通過強制執行架構規則，防止代碼與設計偏離。
- 注意：該插件以當前 DSH 進程權限運行。
change_close強制要求 0 error 收尾。架構規則（如依賴方向、命名、環等）必須嚴格遵守。插件採用 MIT 許可證，零外部依賴。
短結尾¶
dsh-normify 通過分形模塊樹、三層校驗和伴隨開發流程，解決了智能體開發中架構圖與代碼脫節的問題。它提供了一個從數據建模到可視化的完整基礎設施，適合對代碼結構有較高要求的工程場景。
- 目錄頁：https://www.skillhub.cn/plugins/yan-mc/dsh-normify
- GitHub：https://github.com/yan-mc/dsh-normify
