dsh-code-check

DeepSeek Harness (dsh) 代码审查插件：整合 ESLint 静态检查、Prettier 格式校验与启发式问题分析，输出包含问题列表、分级与修复建议的结构化审查报告。

功能特性

• 🔍 多步审查流水线：读取目标 → ESLint 检查 → Prettier 格式校验 → 启发式分析 → 生成报告
• 📁 目录审查：path 指向目录时递归扫描（自动排除 node_modules/.git/dist 等），聚合生成总评分 + 文件清单 + 逐文件问题详情
• 📐 TypeScript / JSX 支持：通过 typescript-eslint 正确解析 .ts/.tsx/.jsx，提供类型级规则（no-explicit-any、no-unused-vars 等）
• 🎚 规则集档位：preset 可选 lenient（宽松）/ standard（标准）/ strict（严格），同时调整内置 ESLint 规则级别、启发式阈值（行宽 160/120/100）与评分权重
• 🧾 机器可读 JSON：output: "json" 输出统一结构的审查数据（score/grade/counts/issues/nextActions），供 CI 与上层 Agent 程序化消费
• 📋 结构化报告：评分（A-D）、问题概览表、错误/警告分区、修复建议、下一步行动
• 🛠 工具整合：调用 ESLint CLI（JSON 输出解析）+ Prettier API，支持项目自有 eslint.config，缺失时使用内置通用配置
• 💡 修复建议知识库：常见 ESLint 规则 → 中文修复指引，并标注可 --fix 自动修复的条目
• 🔒 路径安全：文件审查限制在 dsh 工作目录内，拒绝 .. 逃逸与符号链接越权
• 🔧 fix 模式：可选先执行 eslint --fix 再输出修复后的报告

安装

npm install dsh-code-check

或在 dsh 配置中引用插件路径：

plugins:
  - id: code-check
    name: "绝对路径/dsh-code-check/index.js"

工具说明

code_review

参数

| 参数 | 类型 | 必填 | 说明 | |---|---|---|---| | path | string | 与 snippet 二选一 | 要审查的文件或目录路径（相对 dsh 工作目录），目录会递归审查 | | snippet | string | 与 path 二选一 | 要审查的代码片段文本 | | language | string | 否 | snippet 的语言：javascript/typescript/json/css/html/markdown（默认 javascript） | | fix | boolean | 否 | 为 true 时先执行 eslint --fix 再出报告（默认 false） | | maxFiles | number | 否 | 目录审查时最多扫描的文件数（默认 200） | | preset | string | 否 | 规则集档位：lenient 宽松 / standard 标准（默认）/ strict 严格 | | output | string | 否 | 报告格式：markdown（默认）/ json（机器可读） |

使用示例

对话中直接说：

审查一下 src/index.ts

Agent 会调用：

{ "path": "src/index.ts" }

目录审查：

审查一下 src 目录

Agent 会调用：

{ "path": "src", "maxFiles": 200 }

审查代码片段：

{
  "snippet": "var a = 1\nif (a == 1) { console.log(a) }",
  "language": "javascript"
}

严格档位 + JSON 输出（接入 CI 门禁）：

{
  "path": "src",
  "preset": "strict",
  "output": "json"
}

CI 可依据 score / counts.errors 决定是否拦截合入。

报告结构（Markdown / JSON 同源）

# 📋 代码审查报告
**审查目标**: src/index.js（124 行，3.2 KB）
**整体评分**: ⭐ A（96/100）

## 📊 问题概览        —— 错误/警告/可自动修复/格式/建议 计数表
## ❌ 必须修复（Error） —— [行:列] 规则名 + 说明 + 修复建议
## ⚠️ 建议改进（Warning）
## 💡 风格与潜在问题    —— TODO 标记、console 残留、超长行、eval 风险等
## 🎨 代码格式          —— Prettier 差异行数与修复命令
## 🔧 下一步行动        —— 可执行的修复入口

设计要点

• 档位三合一：preset 只改规则的级别与启发式阈值/评分权重，不改变规则覆盖面——严格档不新增需要特殊配置的解析器依赖，任何陌生项目都能直接跑
• TypeScript / JSX 解析：内置兜底配置按文件后缀分流——JS/JSX 用通用规则并开启 ecmaFeatures.jsx，TS/TSX 接入 typescript-eslint 推荐规则与解析器；无需项目自带 tsconfig（未开启类型信息类规则）
• 子进程调用：ESLint 通过 child_process.execFile 运行，--format json 输出后解析为结构化消息列表；片段审查时以临时目录为 cwd，避免规则匹配范围外文件被忽略
• 配置回退：优先使用被审查项目自己的 eslint.config.*；缺失时报错信息识别后自动切换插件内置 eslint.fallback.config.mjs
• 启发式检查：对所有语言生效（TODO/FIXME、console、超长行、行尾空白、Tab 缩进、eval）
• 评分模型：基础权重 8×错误 - 3×警告 - 6×格式失败 - 1×建议（A≥90 / B≥75 / C≥60 / D<60），按档位缩放——宽松误差减权、严格全面加码
• JSON 同源：Markdown 与 JSON 共用 collectReport / collectDirectoryReport 结构化数据，保证两种输出的评分与问题口径一致

开发与测试

cd dsh-code-check
pnpm install
pnpm test    # 47 项断言：报告结构、问题检出、格式校验、参数校验、路径安全、渲染独立性、目录审查、TS 审查、规则集档位、JSON 输出、JSX/TSX 解析、工具注册校验
pnpm lint

扩展方向

• 已支持目录级审查，可继续增强：并行分片、按 git diff 只审查变更文件
• 集成 stylelint（CSS）、markdownlint、Ruff（Python）等更多语言工具
• 报告同时输出 JSON 结构，供上层 Agent 程序化消费

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-code-check
• npm：https://www.npmjs.com/package/dsh-code-check

典型场景

1. 提交前自检

用户：这段代码提交前帮我审一下有没有明显问题

对片段跑 code_review，在落盘前发现语法错误、危险模式与风格问题。

2. 模型生成代码的快速把关

用户：AI 给我的这段实现靠谱吗

把生成的片段交给 code_review 做静态检查，避免直接信任未验证代码。

3. 多语言片段混检

用户：这个 JS 和这段 Python 都看一下

对每段分别调用，插件按语言选择对应检查器。

4. 教学/评审场景补充说明

用户：这段代码哪里不规范

输出的问题清单可直接作为评审意见的补充材料。

安全边界

• 只读分析：仅做静态解析与规则检查，不执行被检查代码，不产生副作用。
• 不落盘：检查过程在临时目录进行，结束后清理，不修改工作区文件。
• 路径敏感：会按调用时解析路径（不在模块顶层固化 cwd），保证任意工作目录下行为一致。
• 结论非权威：静态检查存在误报与漏报，不能替代真实测试与人工评审。

RoadMap

v0.2（已随 0.3.0 落地）

• ✅ 支持 TypeScript / JSX 语法解析
• ✅ 增加可配置规则集（宽松/严格档位）
• ✅ 输出机器可读 JSON，便于接入 CI

v0.3（展望）

• 与 dsh-todo-audit（二期 D13）联动：审查同时收集 TODO/FIXME
• 按 git diff 只审查变更文件，与流水线结合

版本说明

• 0.1.0：初始版本——code_review 片段静态检查（语法、危险模式、风格）。
• 0.2.0：目录批量审查——path 指向目录时递归扫描并聚合报告；修复工具 schema 的非法 required: false（此前在插件注册时即抛错）。
• 0.3.0：规则集档位（lenient/standard/strict）+ 机器可读 JSON 输出 + JSX/TSX 解析；测试扩展至 47 项断言。

其他插件集成说明

代码质量体检可与下列插件组合，形成「体检 → 定位 → 修复 → 复核」闭环。

| 协作插件 | 集成方式 | |---|---| | dsh-markdown-lint | 源码与文档分别体检：code-check 管源码，markdown-lint 管文档 | | dsh-regex-lab | 自定义规则可先用 test_regex 验证，再落库 | | dsh-diff-writer | 修复建议确认后用 apply_patch 精确落盘 | | dsh-hash-checksum | 审查前后比对文件摘要，确认只有预期文件被改动 | | dsh-fs-inspector | 审查前用 dir_size / recent_files 掌握改动范围 |

FAQ

Q：为什么 CI 里检查结果和本地不同？ 插件在调用时惰性解析路径，但检查器（如 ESLint flat config）对工作目录敏感。请在调用前确认 cwd，或在测试脚本中显式切换到目标目录。

Q：会执行我的代码吗？ 不会。只做静态解析，任何"运行结果"都不在检查范围内。

Q：支持哪些语言？ 按片段特征自动识别常见语言（JS/TS/Python 等）；未识别的语言会给出可读性提示而非报错。

Q：能自动修复问题吗？ 不能，本插件只报告问题；修复由你或 dsh-diff-writer 落地。