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，否则会产生路径错误。