SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场ubs

ubs

编程与开发

查看项目

更新于 10-16 14:52

技能介绍

用途

UBS（Ultimate Bug Scanner）是为 AI 编码工作流构建的静态分析工具，定位为“AI 智能体的质量门禁”：提交前扫描，合并前修复。其存在的原因是 AI 智能体产出速度快，但缺陷出现得更快，例如空指针崩溃漏过检查、缺失 await 导致静默失败、XSS 漏洞进入生产环境、内存泄漏不断累积。

核心规则：

ubs <changed-files> --fail-on-warning

退出码 0 表示可安全提交，退出码 1 表示需修复后重新运行。

主要能力

支持的检测类别分为三档：

  • 关键（必须修复）：空值安全、安全（XSS、注入、原型污染、硬编码密钥）、async/await（缺失 await、未处理 rejection、竞态）、内存泄漏（未清理的事件监听器、定时器泄漏）、类型强制转换（== 与 ===、缺少基数的 parseInt、NaN 比较）。
  • 重要（生产风险）：除法安全、资源生命周期（未关闭的文件、连接、上下文管理器）、错误处理（空 catch、被吞掉的错误）、Promise 链（无 .catch() 的 .then()）、数组变更（迭代中修改）。
  • 代码质量（视上下文而定）：调试代码（console.log、debugger、print()）、TODO 标记、类型安全（TypeScript any）、可读性（复杂三元、深层嵌套）。

各模块的覆盖范围与数量不同；PHP 仅有五类，因此建议使用 --skip-<lang>=N。

语言与关键模式：JavaScript/TypeScript（innerHTML XSS、eval()、缺失 await、React hooks 依赖）、Python（eval()、无 with 的 open()、缺失 encoding=、None 检查）、Go（nil 指针、goroutine 泄漏、defer 对称性、context cancel）、Rust（.unwrap() panic、unsafe 块、Option 处理）、Java（资源泄漏 try-with-resources、null 检查、JDBC）、C/C++（缓冲区溢出、strcpy()、内存泄漏、use-after-free）、Ruby（eval()、send()、instance_variable_set）、Swift（强制解包 !、ObjC 桥接问题）。

PHP 覆盖请求派生的 SQL、命令/代码执行、include、反序列化与不安全输出；它不提供其他模块那样的异步或生命周期覆盖。

常用命令：

ubs file.ts file2.py                    # 指定文件（< 1s）
ubs $(git diff --name-only --cached)    # 暂存文件
ubs --staged                            # 同上，语法更简洁
ubs --diff                              # 工作区 vs HEAD
ubs .                                   # 当前目录
ubs /path/to/project                    # 指定路径
ubs --only=js,python src/               # 语言过滤（更快）
ubs --ci --fail-on-warning .            # CI 严格模式
ubs --format=json .                     # 机器可读
ubs robot-docs                          # JSON：指南、参数、示例、退出码、格式
ubs --schema=json                       # --format=json 的 JSON Schema
ubs --format=sarif .                    # GitHub 代码扫描

输出格式示例：类别（N 个错误）、file.ts:42:5 位置、💡 建议修复、退出码。解析方式：file:line:col 为位置，💡 为修复方法，退出码 0/1 为通过/失败。

其他能力包括：配置档（--profile=strict / --profile=loose）、类别包（--category=resource-lifecycle）、对比模式（--comparison 与 --report-json 用于回归检测）、输出格式（text、json、jsonl、sarif、html）、行内抑制（在标记行或其正上一行写 ubs:ignore，没有 ubs:ignore-next-line）、退出码（0 无关键问题、1 关键问题或告警、2 环境或用法错误、3 未扫描到任何内容即未通过）、doctor 命令（ubs doctor、ubs doctor --fix）、自定义 AST 规则（~/.config/ubs/rules 下的 YAML，配合 --rules）、路径排除（--exclude）、会话日志（ubs sessions --entries 1）等。

使用方式

安装：

# 一行命令（推荐）
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/install.sh?$(date +%s)" | bash -s -- --easy-mode

# 手动
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/main/ubs \
  -o /usr/local/bin/ubs && chmod +x /usr/local/bin/ubs

修复工作流：读取发现（类别与修复建议）→ 定位 file:line:col 查看上下文 → 确认真实问题（非误报）→ 修复根因而非症状 → 重跑 ubs <file> 至退出码 0 → 提交。

智能体集成：安装时 UBS 会为编码智能体自动配置钩子，包括 Claude Code（.claude/hooks/on-file-write.sh）、Cursor（.cursor/rules）、Codex CLI（.codex/rules/ubs.md）、Gemini（.gemini/rules）、Windsurf（.windsurf/rules）、Cline（.cline/rules）。Claude Code 钩子被注册为 Edit|Write|MultiEdit 的 PostToolUse，并在 .claude/settings.json 中将 git_safety_guard.py 注册为 Bash 的 PreToolUse；钩子从 stdin 读取工具调用，仅扫描被写入的文件，关键发现以退出码 2 反馈给 Claude。工具还提供 Git pre-commit 钩子示例，以及 --jobs=N 控制并行度。

性能参考：5K 行约 0.8 秒、50K 行约 3.2 秒、200K 行约 12 秒、1M 行约 58 秒，即每秒 10,000+ 行。加速建议：限定到变更文件、使用 --staged 或 --diff、语言过滤 --only、跳过类别 --skip。

自动忽略路径：node_modules、.venv、dist、build、target 及编辑器缓存。

适用场景

适合在 AI 智能体高速产出代码的流程中作为提交前质量门禁，用于本地提交前扫描、CI/CD 严格模式、GitHub 代码扫描（SARIF）、PR 附件与仪表盘（HTML 报告），以及在 CI 中对比基线检测回归。也适合作为 Claude Code、Cursor、Codex CLI 等智能体的自动钩子，在文件写入后即时反馈关键问题。另有与 Flywheel 系工具的集成说明：BV 通过 --beads-jsonl=out.jsonl 导出发现、CASS 检索历史会话中的相似缺陷模式、CM 从 UBS 发现中提取规则、Agent Mail 通知智能体扫描结果、DCG 内嵌运行 UBS。

限制

各模块的检测覆盖范围与数量不同，PHP 仅五类且不提供异步或生命周期覆盖，需按语言使用 --skip-<lang>=N。行内抑制只支持在标记行或其正上一行写 ubs:ignore，没有 ubs:ignore-next-line。退出码 3 表示未扫描到任何受支持语言，不算通过。常见问题的处理方式：环境错误（退出码 2）用 ubs doctor --fix；提示 ast-grep 未找到可用 brew install ast-grep 或 cargo install ast-grep；误报过多用 --skip=N 或 // ubs:ignore；扫描过慢则缩小到具体文件而非 ubs .。其他未在资料中明确说明的功能、收费、价格与平台情况暂未提供。