前言¶
DeepSeek Harness (DSH) 采用插件化架构，Agent 的能力扩展通常通过引入外部工具实现。当 Agent 需要对项目代码进行安全扫描或质量检查时，直接调用外部命令行工具或编写自定义解析脚本会增加开发与维护成本。
dsh-code-scan 插件旨在解决这个问题。它通过封装 semgrep，为 DSH Agent 提供了一个名为 code_scan 的单一工具。Agent 只需传入目录路径，插件即可在本地运行安全扫描，并输出一份按文件、行号和严重级别分组的中文 Markdown 报告。
核心功能¶
该插件提供了以下核心能力：
- 单一工具接口：Agent 只需调用
code_scan，传入目标目录路径即可启动扫描。 - 结构化报告：扫描结果按文件分组，列出具体的行号、严重级别（ERROR / WARNING / INFO）以及对应的规则描述。
- 上下文保护：结果默认按严重级别优先排序，且限制最多显示 200 条。这一设计是为了避免过多的扫描结果撑爆 Agent 的上下文窗口。
- 容错机制：如果本机未安装 semgrep 或命令未在 PATH 中，插件会返回友好的中文提示，而不会导致 Agent 调用失败。
安装与前提条件¶
使用该插件前，需确保本地环境满足以下条件：
- 安装 semgrep：本机需安装 semgrep 并确保
semgrep命令在系统 PATH 环境变量中。 - 环境隔离（Windows）：在 Windows 系统上，建议使用独立的虚拟环境安装 semgrep，以避免污染其他 Python 项目环境。
在满足上述条件后，执行以下命令安装插件：
dsh plugin --profile web add dsh-code-scan
安装完成后，需要重启 dsh web 进程以使工具生效。
典型用法¶
安装成功后，在 DSH 的对话界面中，Agent 即可使用 code_scan 工具。
指令示例：
用 code_scan 工具扫描 C:\path\to\your\project
输出报告示例：
# semgrep 扫描报告
- 扫描目录：`C:\...\demo`
- 发现问题：共 4 处（ERROR 2 / WARNING 2 / INFO 0）
## C:\...\app.py（2 处）
- [ERROR] 第 8 行 · 规则 `...sqlalchemy-execute-raw-query`：Avoiding SQL string concatenation...
- [WARNING] 第 18 行 · 规则 `...eval-detected`：Detected the use of eval()...
适用场景与注意¶
- 适用人群：需要为 DeepSeek Harness Agent 增加代码安全审计能力的开发者。
- 权限注意：插件以当前 DSH 进程的权限运行，这意味着 Agent 在扫描目录时需要具备相应的文件读写权限。
- 源码审查：由于 DSH 插件通常在本地执行命令，建议在安装前查看 GitHub 仓库源码以确认许可证与实现逻辑。
总结¶
dsh-code-scan 插件通过简单的接口封装，解决了 Agent 集成静态代码分析工具的痛点。它将复杂的 semgrep 扫描过程转化为结构化的中文 Markdown 报告，既保证了 Agent 的上下文安全，又提供了清晰的可读性。项目地址：https://github.com/xiaohuang-zaianlian/dsh-code-scan
