前言¶

在 DeepSeek Harness（DSH）裏做 MLIR 相關開發時，模型往往需要通過工具去跑 mlir-opt、做 TableGen 生成、或檢查 IR 能否解析。若把這些步驟交給 shell 拼接命令，容易遇到引號轉義、PATH 上找不到二進制、以及 ENOENT 一類環境問題。手工在對話裏寫一長串 shell 也不利於結構化返回結果。

下面介紹的 dsh-mlir-toolchain 是維護者 Rcyc-1025 發佈的 DSH 插件（GitHub：Rcyc-1025/dsh-mlir-toolchain，社區目錄：skillhub 插件頁）。它把由 MLIR 構建腳本生成的 toolchain.json 轉成四個面向模型的工具，經宿主 subprocess 服務執行，不經過 shell、不在 PATH 裏查找二進制，且插件本身 零運行時依賴。分類上屬於「模型推理」相關能力擴展；DSH 社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。

這是什麼¶

一句話：MLIR toolchain tools for DeepSeek Harness: probe, run, TableGen and parse-check.

插件讀取 toolchain.json（或由配置 / 環境變量指定路徑），向會話註冊 mlir_probe、mlir_run、mlir_tblgen、mlir_parse_check 四個工具。適合已經在本地或 CI 裏編好 LLVM/MLIR、並願意用 JSON 固定各二進制路徑的團隊；開發與 CI 校驗曾針對 LLVM 23.1.4，README 說明只要較新版本提供 mlir-opt、mlir-translate、mlir-tblgen 和 llc 一般即可使用。許可證爲 MIT（見倉庫 badge）；當前 package 版本爲 0.2.0。

環境與依賴¶

安裝插件前，主機側需要滿足：

1. Node.js ^22.19.0 || >=24.0.0
2. DeepSeek Harness >=0.2.1-rc.5 <0.3.0-0
3. LLVM/MLIR 二進制；mlir-tblgen 還需要 MLIR TableGen 頭文件（含 mlir/IR/OpBase.td），來自源碼樹或已安裝的 mlir/include

推薦準備 toolchain.json。多餘字段會被忽略，核心形狀如下：

{
  "llvm": {
    "version": "23.1.4",
    "root": "/opt/llvm",
    "mlirRoot": "/opt/llvm-build",
    "tools": {
      "mlirOpt":       { "path": "/opt/llvm-build/bin/mlir-opt",       "version": "23.1.4" },
      "mlirTranslate": { "path": "/opt/llvm-build/bin/mlir-translate", "version": "23.1.4" },
      "mlirTblgen":    { "path": "/opt/llvm-build/bin/mlir-tblgen",    "version": "23.1.4" },
      "llc":           { "path": "/opt/llvm/bin/llc",                  "version": "23.1.4" },
      "mlirRunner":    { "path": "/opt/llvm-build/bin/mlir-runner" },
      "llvmConfig":    { "path": "/opt/llvm/bin/llvm-config" }
    }
  },
  "mlirDev": {
    "include": "/opt/llvm-project/mlir/include",
    "lib": "/opt/llvm-build/lib"
  }
}

llvm.tools 可識別的鍵包括：mlirOpt、mlirTranslate、mlirTblgen、mlirRunner、mlirReduce、llc、opt、clang、llvmConfig、llvmObjdump、cmake、ninja、filecheck 等。

核心功能¶

mlir_probe¶

讀取配置後並行對每個二進制執行 --version 探測，返回 ok、缺失與失敗工具、版本不一致，以及 TableGen 將使用的 include 目錄。missing 表示文件不存在；failed 表示存在但 --version 失敗；可選工具缺失會出現在 optionalMissing（例如 filecheck）。

mlir_run¶

用 argv 數組（無 shell）運行 mlir-opt、mlir-translate、mlir-tblgen、mlir-runner、mlir-reduce、llc、clang、filecheck、llvm-config 或 llvm-objdump 等。可將 IR 文本寫入臨時 .mlir 作爲最後一個參數，或指定 inputPath（相對會話 cwd）。輸出過大時完整日誌落在 .mlir-logs/，返回體帶 hint 指向日誌路徑。

調用示例：

{ "tool": "mlir-opt", "args": ["--pass-pipeline=builtin.module(cse)"],
  "inputText": "module { ... }", "cwd": ".", "timeoutMs": 30000 }

mlir_tblgen¶

面向 -gen-* 代碼生成：支持 35 種命名 kind（如 op-decls、op-defs、pass-decls 等），也支持原始 gen:<name> / -gen-<name>；可自動發現 mlir/IR/OpBase.td 所在 include 根、透傳額外 flag、自動創建輸出目錄父路徑。

{ "kind": "op-decls", "inputPath": "include/MyOps.td",
  "outputPath": "build/MyOps.h.inc" }

Include 解析順序：工具參數 → 插件 includeDirs → 環境變量 MLIR_INCLUDE_DIR → 自動候選（須在目錄中真實存在 mlir/IR/OpBase.td）。找不到時 hint 會列出搜索過的目錄。

mlir_parse_check¶

用 mlir-opt 解析或校驗 MLIR，可選跑 pass 管道，返回結構化的 error / warning / note。

{ "source": "module { func.func @f(%a: i32) -> i32 { return %a : i32 } }",
  "passes": ["cse", "canonicalize"], "maxDiagnostics": 200 }

安裝與啓用¶

在包含本插件 checkout 的目錄下執行（命令來自倉庫 README，勿自行拼接 github:owner/repo）：

dsh plugin --profile desktop add ./dsh-mlir-toolchain

CLI 會把包寫入 profile 的 dsh.profile.bundles；插件通過 bundled cordis.patch.yml 自注冊。服務端插件熱加載後，四個工具會立即可用。卸載：

dsh plugin --profile desktop remove dsh-mlir-toolchain

若在 DSH 沙箱會話（workspace-write）中安裝，profile 目錄可能在 workspace 外，需在普通終端安裝或按提示授予權限。

安全說明： 插件以當前 DSH 進程權限運行子進程；安裝前請自行審閱倉庫源碼與 MIT 許可證，確認 toolchain.json 中的路徑指向你信任的二進制。

配置¶

零配置時，插件會在下列位置自動發現 toolchain.json：插件目錄旁（常見 mlir-lang/dsh-mlir-toolchain + mlir-lang/toolchain.json 佈局）、插件目錄內、會話 cwd、或 <cwd>/mlir-lang/。加載時發現一次；若仍未找到，每次調用會再試，便於切換工作目錄。

優先級：config.toolchainPath / 環境變量 MLIR_TOOLCHAIN_JSON 高於自動發現。

在 profile 中可寫：

- id: mlir-toolchain
  name: 'dsh-mlir-toolchain'
  config:
    toolchainPath: /opt/llvm/toolchain.json   # optional
    includeDirs:                              # optional: extra -I roots
      - /opt/llvm-project/mlir/include
    timeoutMs: 120000
    maxOutputBytes: 1048576
    logKeep: 100
    # Single-binary overrides (absolute or cwd-relative):
    # mlirOptPath, mlirTranslatePath, mlirTblgenPath, mlirRunnerPath,
    # mlirReducePath, llcPath, optPath, clangPath, filecheckPath,
    # llvmObjdumpPath, llvmConfigPath

環境變量：MLIR_TOOLCHAIN_JSON（toolchain.json 路徑）；MLIR_INCLUDE_DIR（TableGen include，; 或 : 分隔）。

典型用法順序¶

1. 用構建腳本生成並維護 toolchain.json，保證路徑與版本字段正確。
2. 安裝插件後調用 mlir_probe，確認無 missing / failed / versionMismatch，並檢查 tblgenInclude.dirs。
3. 日常改 IR 用 mlir_run（mlir-opt 等）或 mlir_parse_check 做診斷。
4. 改 .td 時用 mlir_tblgen 指定 kind 與 inputPath / outputPath。

經過上面的步驟，模型側拿到的是結構化 JSON（含 exitCode、timedOut、hint 等），而不是 fragile 的 shell 一行命令。

適用場景與注意¶

適合： 已在 DSH 裏做 MLIR 方言開發、pass 實驗、TableGen 生成，且希望工具路徑與版本由 toolchain.json 統一管理的工作流。

注意：

• 必須自備 LLVM/MLIR 二進制與 TableGen 頭文件；插件不替你下載 LLVM。
• 子進程超時、輸出截斷與日誌輪轉由 timeoutMs、maxOutputBytes、logKeep 控制，長 CI 日誌需調大或讀 .mlir-logs/。
• DSH 版本須落在 >=0.2.1-rc.5 <0.3.0-0，與 package.json engines.dsh 一致。

結尾¶

dsh-mlir-toolchain 把 MLIR 工具鏈從「shell 字符串 + PATH 猜測」收成四個 DSH 工具：探測、運行、TableGen、解析檢查，並圍繞 toolchain.json 與 include 自動發現給出可操作的 hint。進一步瞭解實現與 issue，見 GitHub 倉庫；在 community 目錄瀏覽元信息見 skillhub 插件頁。