前言¶
DeepSeek Harness (DSH) 採用“一切皆插件”的理念。在開發涉及網絡配置的智能體時，IP 地址和子網的計算是高頻需求，但大模型心算邊界容易出錯。dsh-ipcalc 提供了精確的數學計算能力，確保網絡配置的邏輯正確性。
是什麼¶
dsh-ipcalc 是一個爲 DeepSeek Harness 設計的 IP 與子網數學工具箱。它由 TYEclipse 維護，採用 MIT 許可證。該插件包含五個純本地計算工具，具有零運行時依賴和無網絡 I/O 的特點。它通過本地數學運算替代心算，解決智能體在處理網絡地址時可能出現的精度和邏輯錯誤。
核心功能¶
該工具箱提供以下五個核心功能：
- ipv4_subnet: 對 IPv4 CIDR 進行完整子網布局，輸出網絡號、廣播地址、掩碼、反掩碼、主機範圍、數量及 IANA 分類。
- ipv4_summarize: 將一組 IPv4 地址或範圍歸併爲最小覆蓋的 CIDR 列表（合併與超網計算）。
- ip_parse: 校驗並規範化任意 IPv4/IPv6 地址（遵循 RFC 5952），同時進行 IANA 分類。
- ipv6_subnet: 對 IPv6 CIDR 進行完整子網布局，使用 128 位 BigInt 進行精確算術運算。
- ip_match: 判定裸 IP 是否屬於某個 CIDR 範圍，並返回規範化後的範圍。
安裝與啓用¶
安裝前，請確保你的 DeepSeek Harness 環境已配置好插件管理器。執行以下命令將插件添加到指定配置文件中：
dsh plugin --profile <your-profile> add github:TYEclipse/dsh-ipcalc
安裝完成後，插件即可在 DSH 會話中調用。
典型用法¶
IPv4 子網布局¶
ipv4_subnet("192.168.1.25/24")
輸出將包含網絡地址、廣播地址、子網掩碼、反掩碼、可用主機範圍（含數量）以及 IANA 分類信息。
CIDR 歸併¶
ipv4_summarize(["10.0.0.0/24", "10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"])
這將返回 ["10.0.0.0/22"]。
IPv6 地址解析與規範化¶
ip_parse("::ffff:192.168.1.1")
輸出將顯示該地址爲 IPv6 類型，遵循 RFC 5952 規範化，並識別其內嵌 IPv4 的特徵。
IPv6 子網計算¶
ipv6_subnet("2001:db8:1234:5678::1/64")
使用 128 位 BigInt 計算，輸出網絡地址、首末可用主機範圍及精確的地址總數（以十進制字符串返回，避免精度丟失）。
對於特殊網段：
ipv6_subnet("::/0")
ipv6_subnet("fe80::1/127")
IP 成員測試¶
ip_match("192.168.1.5", "192.168.1.0/24")
返回判斷結果及規範化後的網絡範圍。
技術細節¶
- 精確算術: IPv4 使用 32 位整數計算，IPv6 使用 128 位 BigInt 計算。地址計數在超過安全整數閾值時返回字符串，保證精度。
- RFC 合規性: /31 網段遵循 RFC 3021（點對點鏈路，兩地址均可用）；/127 遵循 RFC 6164；IPv6 規範化遵循 RFC 5952。
- 分類: 依據 IANA 特殊用途註冊表進行分類（如私網、環回、鏈路本地、文檔段、組播等）。
- 版本校驗:
ip_match會拒絕 IPv4 與 IPv6 的版本混用測試，避免靜默錯誤。
注意事項¶
- 該插件在 DSH 進程的本地運行環境中執行，不涉及網絡請求。
- 在啓用插件前，建議查閱源碼以確認其行爲符合你的安全與合規要求。
- IPv6 部分嚴格區分版本，進行匹配測試時必須確保 IP 地址與 CIDR 版本一致。
總結¶
dsh-ipcalc 通過本地化、標準化的數學運算，解決了智能體在網絡配置中常見的計算錯誤。對於需要精確處理 IP 地址和子網的開發者，這是一個可靠的輔助工具。
