@kiwifruit/dsh-syntax-checker
多语言语法检查服务（JS/TS/YAML/Python）：括号匹配、不可见字符、语法错误，通过 Tree-sitter + Ruff
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:kiwifruit13/DSH-Syntax-Checker#31ae979abe925dabc7e9594539c9c79ea342f345Syntax Checker 以 @kiwifruit/dsh-syntax-checker 发布，当前版本为 1.0.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
多语言语法检查服务（JS / TS / YAML / Python）：括号匹配、不可见字符、语法错误检测与自动修复。
同一套引擎支持两种运行形态：
@kiwifruit/dsh-syntax-checker）—— 由 DSH 宿主经纤程加载，向模型暴露 syntax_check 工具，并向其他插件提供 syntaxChecker 服务；createSyntaxChecker() 直接嵌入上游系统。| 能力 | 说明 |
|---|---|
| 括号匹配 | () / [] / {} / 字符串字面量内的括号不参与匹配 |
| 不可见字符 | 检测零宽空格、BOM、双向控制符等隐形陷阱 |
| 语法错误 | Tree-sitter 解析（JS/TS/YAML）+ Ruff（Python） |
| 行尾空白 | 通用规则 |
| YAML 专项 | 重复键、Tab 缩进 |
| 自动修复 | Ruff auto-fix（ruff check --fix）+ 编辑应用器（行/列 → offset） |
web-tree-sitter（WASM 语法，位于 assets/）+ ruff（外部 CLI，Python 后端）@fastify/swagger（OpenAPI 文档，openapi.yaml 为导出产物）@deepseek-ai/cordis（纤程 / waterfall 事件）+ @deepseek-ai/dsh-tools（defineTool）@deepseek-ai/schemastery（Standard Schema）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 | 批量检查（有上限，见 schemas.ts 的 MAX_BATCH_SIZE） |
| POST | /api/v1/fix | 自动修复，返回修复后源码 |
响应采用统一包装（code / message / timestamp / data），HTTP 状态码表达传输层状态，业务错误码在响应体中。完整契约见 openapi.yaml 或启动服务后访问 Swagger UI；错误码清单见 docs/error-codes.md。
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',
});
// result.diagnostics / errorCount / warningCount / infoCount
独立模式无 Cordis 纤程，配置在此处经 Config schema 同步校验并填充默认值。
安装命令（--profile 是必选参数，指定目标配置文件，如 web / desktop）：
dsh plugin --profile web add @kiwifruit/dsh-syntax-checker
<spec> 支持多种来源：
| 来源类型 | 命令格式 | 示例 |
|---|---|---|
| npm 包（推荐） | dsh plugin --profile web add <包名> | dsh plugin --profile web add @kiwifruit/dsh-syntax-checker |
| 精确版本 | dsh plugin --profile web add <包名>@<版本> | dsh plugin --profile web add @kiwifruit/dsh-syntax-checker@1.0.0 |
| GitHub 仓库 | dsh plugin --profile web add github:<owner>/<repo> | dsh plugin --profile web add github:owner/dsh-syntax-checker |
| 本地目录 | dsh plugin --profile web add file:<路径> | dsh plugin --profile web add file:./dsh-syntax-checker |
裸包名解析到 npm
latest，受 pnpm 24 小时最小发布年龄冷却限制——刚发版要立即安装，请写精确版本号（精确版本自动豁免冷却期）。
安装后生效链路：CLI 下载包 → 读取包根 cordis.patch.yml → 以 - insert: 语义合并进 profile 的补丁层 → 重装配激活。若未生效，重启 DSH 进程后再确认。
安装后验证：
dsh plugin --profile web list # 确认包已进入 profile 依赖
然后启动 dsh --profile web，向模型确认 syntax_check 工具已出现在工具列表中（装配验证的两个信号：工具列表 + 服务就绪）。
升级：与安装命令相同，再次执行 dsh plugin --profile web add @kiwifruit/dsh-syntax-checker 即升级。卸载：dsh plugin --profile web remove @kiwifruit/dsh-syntax-checker。
安全提醒：安装插件等同于运行第三方代码。安装前请查看插件源码，不熟悉的插件建议在隔离环境先测试。
仓库根目录的 cordis.yml 即装配清单（格式遵循 约束/001接口/工具扩展.md §3.1–3.2）；随包分发的 cordis.patch.yml 以 - insert: 语义携带同一条目，供 dsh plugin add 自动激活：
- id: syntax-checker
name: '@kiwifruit/dsh-syntax-checker'
inject: [tools]
config:
timeoutMs: 30000
maxRetries: 2
verbose: false
policies: { timeout: true, retry: true, observation: true }
插件入口以原名导出 Cordis 契约：apply / name / inject / provide / Config。这是硬性前提——若只以别名导出，Cordis 会跳过 schema 校验与默认值填充（Config 缺原名时是静默跳过，故障在运行期才炸出）。
加载后：
syntax_check 工具（经 defineTool，参数 filePath / sourceText / language? / fix?）；ctx.provide('syntaxChecker', engine)，消费方声明 inject: ['syntaxChecker'] 即可调用 lint / fix。| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
timeoutMs | number | 30000 | 单次语法检查的超时预算（毫秒）；单次调用可用 options.timeoutMs 覆盖 |
maxRetries | number | 2 | 后端瞬时故障的最大重试次数 |
verbose | boolean | false | 是否记录成功事件（默认只记录 fail / timeout） |
policies.timeout | boolean | true | 超时伴生策略开关 |
policies.retry | boolean | true | 重试伴生策略开关 |
policies.observation | boolean | true | 观测伴生策略开关 |
cordis.yml的config是整行替换、非深度合并——覆盖时必须写全整个对象。 关闭某项策略后，可外接同名伴生插件替换它（策略可装卸，不重复注册）。
Definition（definition.ts） 抽象接口 + 事件词汇表 + 错误码
▲ │
│ 实现 │ 消费
Provider Consumer
├─ RuffBackend（Python） ├─ ParserEngine（中间层）
└─ TreeSitterBackend └─ syntax_check Tool / syntaxChecker 服务
（JS/TS/YAML）
syntax/check（waterfall）：lint 的执行门。伴生策略通过它挂载横切逻辑：
TimeoutPolicy 以 prepend 注册，恒为最外层——保证「超时包住重试」，与插件加载顺序无关；RetryPolicy 默认追加，位于链尾——waterfall 内部 cbs.shift() 共享游标，多次调 next() 的监听器若不在链尾，重试会跳过其后所有监听器；next() 即短路整条链（含默认行为）。syntax/check-end（emit）：检查结束通知（status: success | fail | timeout、耗时、诊断列表、traceId），观测策略经此记录结构化日志。PlatformContext 屏蔽「是否运行在 Cordis 宿主内」的差异：
fs / bash 在 cordis 4.0.2 上并非必需依赖，inject 只声明 ['tools']，多声明会让纤程卡在 PENDING。src/
├── core/ # 领域核心：Diagnostic / Rule / Linter / Fixer / Errors / Language
├── rules/ # 规则实现：universal（括号、不可见字符…）、js-ts、yaml
├── parsers/ # 解析适配：tree-sitter-parser、ruff-runner（spawn + stdin）、ruff-adapter
├── plugin/ # Cordis 插件层
│ ├── definition.ts # 服务契约 + 事件词汇表（declare module 合并进 Cordis 类型）
│ ├── config.ts # Schemastery Config schema（Standard Schema）
│ ├── platform.ts # 宿主/独立双模式平台抽象
│ ├── engine.ts # ParserEngine 中间层（lint/fix 编排）
│ ├── providers/ # RuffBackend / TreeSitterBackend
│ ├── policies/ # Timeout / Retry / Observation 伴生策略
│ ├── tool.ts # syntax_check 工具（defineTool）
│ └── index.ts # 原名导出 apply / name / inject / provide / Config
├── api/ # Fastify 应用：路由、schema、统一错误处理、Swagger
└── index.ts # 库形态总出口（含别名导出，原名契约单列）
npm run typecheck # tsc --noEmit
npm run lint # eslint src tests scripts
npm test # vitest run --coverage
npm run test:watch # vitest watch
npm run docs:openapi# 导出 OpenAPI 文档（代码为唯一真相源）
测试分两层：
tests/：core / rules / parsers / api 的单元与集成测试；tests/plugin/：插件层测试（事件门、平台回退、工具定义、装配——装配测试须打 dist 后测，避免「源码已修、产物漂移」的假绿）。Python 相关用例需要本机可用 ruff，缺失时自动跳过。
ruff fix 子命令不存在，自动修复走 ruff check --fix；exit ≥ 2 视为调用级失败。file:// URL 取路径必须用 fileURLToPath（URL.pathname 会产生 /D:/... 坏路径）。Language.load 接收 Buffer 而非 ArrayBuffer。docs/error-codes.md —— 业务错误码清单docs/dsh-integration-plan.md / docs/integration-review.md —— DSH 集成方案与审查记录openapi.yaml —— API 契约导出产物约束/ 目录，未随本仓库发布MIT