前言¶

在 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 插件页。