DSH 插件：dsh-syntax-checker 多語言語法檢查服務

在 DSH 開發流程中，智能體生成代碼後需要即時校驗。手動檢查效率低且容易遺漏細節，dsh-syntax-checker 提供了一套基於 Tree-sitter 和 Ruff 的語法檢查與自動修復方案，支持 JS/TS/YAML/Python。

安裝與啓用¶

插件已發佈到 npm（scoped 包 @kiwifruit/dsh-syntax-checker）。安裝時必須指定 --profile 參數。

dsh plugin --profile web add @kiwifruit/dsh-syntax-checker@0.1.0

安裝注意事項：
1. pnpm 24 小時冷卻限制：裸包名解析到 latest 受此限制。若剛發版需立即安裝，請寫精確版本號（如 @0.1.0），精確版本自動豁免冷卻期。
2. git 來源：git install 拉取的是源碼而非構建產物。本包提供 prepare 腳本，但 pnpm ≥10 默認拒絕運行 git 依賴的 prepare。若使用 github: 安裝，需在 pnpm-workspace.yaml 中放行：

   allowBuilds:
     dsh-syntax-checker: true

或直接使用 npm 包。

安裝後生效鏈路：dsh plugin 執行 pnpm add 落包，再按已安裝狀態對賬 dsh.profile.bundles。啓動時由 bundle 層讀取 cordis.patch.yml 參與組合。增刪 bundle 後需重啓 DSH 進程。

核心功能¶

該插件基於以下引擎與規則實現：

括號匹配：支持 () [] {} 及字符串字面量內的括號匹配。
不可見字符：檢測零寬空格、BOM、雙向控制符等隱形字符。
語法錯誤：使用 web-tree-sitter 解析 JS/TS/YAML，使用 ruff 解析 Python。
行尾空白：通用規則檢查。
YAML 專項：檢測重複鍵與 Tab 縮進錯誤。
自動修復：利用 Ruff 的 fix.edits 和編輯應用器，多輪迭代收斂修復。

用法示例¶

該插件支持兩種運行形態：DSH 插件模式和獨立模式。

1. 作爲 DSH 插件使用¶

安裝後，模型可通過 syntax_check 工具調用，其他插件可通過 syntaxChecker 服務調用。

向模型確認工具列表：

dsh --profile web --dump-config | tail -20

工具調用參數：
* filePath: 文件路徑
* sourceText: 源碼文本
* language?: 語言標識（可選）
* fix?: 是否自動修復（可選）

2. 獨立 HTTP 服務¶

npm install
npm run build
npm start          # 生產：node dist/api/server.js
npm run dev        # 開發：tsx src/api/server.ts

提供的主要接口：

方法	路徑	用途
GET	`/health`	健康檢查（含 ruff 可用性探測）
POST	`/api/v1/lint`	單文件語法檢查
POST	`/api/v1/lint/batch`	批量檢查
POST	`/api/v1/fix`	自動修復，返回修復後源碼

3. 作爲庫嵌入¶

在 Node.js 項目中直接引入：

import { createSyntaxChecker } from '@kiwifruit/dsh-syntax-checker';

const checker = createSyntaxChecker(undefined, {
  timeoutMs: 30_000,
  maxRetries: 2,
  policies: { timeout: true, retry: true, observation: true },
});

const result = await checker.lint({
  filePath: 'a.py',
  sourceText: 'import os\nimport os\n',
});

配置項¶

在 cordis.yml 中配置插件參數。注意：config 字段是整行替換，非深度合併，覆蓋時需寫全對象。

字段	類型	默認值	說明
`timeoutMs`	number	`30000`	單次檢查超時（毫秒），支持單次調用覆蓋
`maxRetries`	number	`2`	後端瞬時故障重試次數
`verbose`	boolean	`false`	是否記錄成功事件
`policies.timeout`	boolean	`true`	超時伴生策略開關
`policies.retry`	boolean	`true`	重試伴生策略開關
`policies.observation`	boolean	`true`	觀測伴生策略開關

注意事項¶

權限風險：安裝插件等同於運行第三方代碼。安裝前請查看源碼，不熟悉的插件建議在隔離環境測試。
** Cordis 配置**：安裝後 cordis.patch.yml 不必再寫本插件條目，安裝過程已自動登記。
Windows 路徑：從 file:// URL 取路徑時需使用 fileURLToPath，否則會產生路徑錯誤。