ubs

UBS - Ultimate Bug Scanner

专为 AI 编码工作流打造的静态分析工具。捕获 AI Agent 常引入的 Bug：空值安全、async/await 问题、安全漏洞、内存泄漏。可在 3-5 秒内扫描 JS/TS、Python、Go、Rust、Java、C++、Ruby、Swift。

为什么要有这个工具

AI Agent 行动迅速，Bug 来得更快。你能在几分钟内交付功能，但：

• 空指针崩溃悄悄溜过
• 缺少 await 会导致静默失败
• XSS 漏洞进入生产环境
• 内存泄漏不断累积

UBS 是质量关卡：提交前扫描，合并前修复。

黄金规则

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

退出码 0 = 可以安全提交。退出码 1 = 修复后重新运行。

必备命令

快速扫描（使用这些命令）

ubs file.ts file2.py                    # Specific files (< 1s)
ubs $(git diff --name-only --cached)    # Staged files
ubs --staged                            # Same, cleaner syntax
ubs --diff                              # Working tree vs HEAD

完整项目扫描

ubs .                                   # Current directory
ubs /path/to/project                    # Specific path
ubs --only=js,python src/               # Language filter (faster)

CI/CD 模式

ubs --ci --fail-on-warning .            # Strict mode for CI
ubs --format=json .                     # Machine-readable
ubs --format=sarif .                    # GitHub code scanning

输出格式

⚠️  Category (N errors)
    file.ts:42:5 – Issue description
    💡 Suggested fix
Exit code: 1

解析：file:line:col → 位置 | 💡 → 修复方法 | 退出码 0/1 → 通过/失败

18 种检测类别

严重（始终修复）

类别	检测内容
空值安全	未防护的属性访问、缺少空值检查
安全	XSS、注入、原型污染、硬编码密钥
Async/Await	缺少 await、未处理的拒绝、竞态条件
内存泄漏	未清理的事件监听器、计时器泄漏
类型强制转换	== 与 ===、未指定基数的 parseInt、NaN 比较

重要（生产风险）

类别	检测内容
除法安全	未检查零值的除法
资源生命周期	未关闭的文件、连接、上下文管理器
错误处理	空 catch 块、被吞掉的错误
Promise 链	.then() 后未接 .catch()
数组变更	迭代期间修改数组

代码质量（视上下文而定）

类别	检测内容
调试代码	console.log、debugger、print() 语句
TODO 标记	TODO、FIXME、HACK 注释
类型安全	TypeScript 中使用 any
可读性	复杂的三元表达式、过深的嵌套

特定语言检测

语言	关键模式
JavaScript/TypeScript	innerHTML XSS、eval()、缺少 await、React hooks 依赖
Python	eval()、未使用 with 的 open()、缺少 encoding=、None 检查
Go	Nil 指针、goroutine 泄漏、defer 配对、context 取消
Rust	.unwrap() 引发的 panic、unsafe 块、Option 处理
Java	资源泄漏（try-with-resources）、空值检查、JDBC
C/C++	缓冲区溢出、strcpy()、内存泄漏、释放后使用
Ruby	eval()、send()、instance_variable_set
Swift	强制解包（!）、ObjC 桥接问题

配置档案

ubs --profile=strict .    # Fail on warnings, enforce high standards
ubs --profile=loose .     # Skip TODO/debug nits when prototyping

类别包（定向扫描）

ubs --category=resource-lifecycle .    # Python/Go/Java resource hygiene

将扫描范围缩小到相关语言，并抑制无关类别。

对比模式（回归检测）

# Capture baseline
ubs --ci --report-json .ubs/baseline.json .

# Compare against baseline
ubs --ci --comparison .ubs/baseline.json --report-json .ubs/latest.json .

适用于 CI，可检测相对于 main 分支的回归。

输出格式

格式	标志	使用场景
text	(默认)	易于阅读的终端输出
json	--format=json	机器解析、脚本
jsonl	--format=jsonl	按行分隔、流式处理
sarif	--format=sarif	GitHub 代码扫描
html	--html-report=file.html	PR 附件、仪表板

行内抑制

当某个发现是有意为之时：

eval(trustedCode);  // ubs:ignore

// ubs:ignore-next-line
dangerousOperation();

退出码

代码	含义
0	没有严重问题（可以安全提交）
1	存在严重问题或警告（使用 --fail-on-warning 时）
2	环境错误（缺少 ast-grep 等）

Doctor 命令

ubs doctor                # Check environment
ubs doctor --fix          # Auto-fix missing dependencies

检查项：curl/wget、ast-grep、ripgrep、jq、typos、Node.js + TypeScript。

Agent 集成

UBS 会在安装期间自动为编码 Agent 配置钩子：

Agent	钩子位置
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 钩子模式

#!/bin/bash
# .claude/hooks/on-file-write.sh
if [[ "$FILE_PATH" =~ \.(js|jsx|ts|tsx|py|go|rs|java|rb)$ ]]; then
  echo "🔬 Quality check running..."
  if ubs "${PROJECT_DIR}" --ci 2>&1 | head -30; then
    echo "✅ No critical issues"
  else
    echo "⚠️  Issues detected - review above"
  fi
fi

Git 提交前钩子

#!/bin/bash
# .git/hooks/pre-commit
echo "🔬 Running bug scanner..."
if ! ubs . --fail-on-warning 2>&1 | tail -30; then
  echo "❌ Critical issues found. Fix or: git commit --no-verify"
  exit 1
fi
echo "✅ Quality check passed"

性能

Small (5K lines):     0.8 seconds
Medium (50K lines):   3.2 seconds
Large (200K lines):   12 seconds
Huge (1M lines):      58 seconds

每秒处理 10,000+ 行。使用 --jobs=N 控制并行度。

速度提示

1. 限定到已更改的文件：ubs src/file.ts（< 1s）与 ubs .（30s）
2. 使用 --staged 或 --diff：仅扫描即将提交的内容
3. 语言筛选：--only=js,python 跳过无关的扫描器
4. 跳过类别：使用 --skip=11,14 跳过调试/TODO 标记

修复工作流

1. Read finding → category + fix suggestion
2. Navigate file:line:col → view context
3. Verify real issue (not false positive)
4. Fix root cause (not symptom)
5. Re-run ubs <file> → exit 0
6. Commit

Bug 严重程度指南

• 严重（始终修复）：空值安全、XSS/注入、async/await、内存泄漏
• 重要（生产环境）：类型收窄、除零错误、资源泄漏
• 视情况而定（酌情判断）：TODO/FIXME、控制台日志

常见反模式

不要	应该
忽略发现的问题	逐一调查
每次编辑都进行完整扫描	限定到已更改的文件
修复症状（if (x) { x.y }）	修复根本原因（x?.y）
未了解原因就抑制	先确认是误报

安装

# One-liner (recommended)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ultimate_bug_scanner/master/install.sh?$(date +%s)" | bash -s -- --easy-mode

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

自定义 AST 规则

mkdir -p ~/.config/ubs/rules

cat > ~/.config/ubs/rules/no-console.yml <<'EOF'
id: custom.no-console
language: javascript
rule:
  pattern: console.log($$$)
severity: warning
message: "Remove console.log before production"
EOF

ubs . --rules=~/.config/ubs/rules

排除路径

ubs . --exclude=legacy,generated,vendor

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

会话日志

ubs sessions --entries 1    # View latest install session

与 Flywheel 集成

工具	集成方式
BV	--beads-jsonl=out.jsonl 将发现的问题导出供 Beads 使用
CASS	搜索过往会话，查找类似的 Bug 模式
CM	从 UBS 发现的问题中提取规则
Agent Mail	通知 Agent 扫描结果
DCG	UBS 在 DCG 保护下运行

故障排除

错误	修复方法
“Environment error”（退出码 2）	ubs doctor --fix
“ast-grep not found”	brew install ast-grep 或 cargo install ast-grep
误报太多	使用 --skip=N 或 // ubs:ignore
扫描速度慢	限定扫描文件：使用 ubs <file>，而非 ubs .