toniantunovi/lucidshark
GitHub: toniantunovi/lucidshark
LucidShark 是专为 AI 辅助开发设计的统一代码质量流水线，整合了 Linting、类型检查、安全扫描、测试和覆盖率等多项检查能力，通过 MCP 与 Claude Code 深度集成实现 AI 驱动的代码质量闭环。
Stars: 1 | Forks: 1
# LucidShark
[](https://github.com/toniantunovi/lucidshark/actions/workflows/ci.yml)
[](https://codecov.io/gh/toniantunovi/lucidshark)
[](https://pypi.org/project/lucidshark/)
[](https://pypi.org/project/lucidshark/)
[](https://github.com/toniantunovi/lucidshark/blob/main/LICENSE)
**专为 AI 辅助开发打造的统一代码质量流水线。**
```
AI writes code → LucidShark checks → AI fixes → repeat
```
## 为什么选择 LucidShark
- **本地优先** - 无需服务器，无需 SaaS 账户。在你的机器和 CI 中运行，结果一致。
- **配置即代码** - `lucidshark.yml` 存放在你的仓库中。所有人遵循相同的规则，变更通过代码审查进行。
- **AI 原生** - 与 Claude Code 进行 MCP 集成。提供 AI Agent 可直接据此行动的结构化反馈。
- **统一流水线** - 集成了 Linting、类型检查、安全（SAST/SCA/IaC）、测试、覆盖率和重复检测于一体。无需再配置 5+ 个独立的工具。
- **开源且可扩展** - 采用 Apache 2.0 许可证。通过插件系统添加你自己的工具。
## 快速开始
```
# 1. 安装 LucidShark（选择其一）
# 选项 A：pip（需要 Python 3.10+）
pip install lucidshark
# 选项 B：独立二进制文件（无需 Python）
# Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/toniantunovi/lucidshark/main/install.sh | bash
# Windows (PowerShell):
irm https://raw.githubusercontent.com/toniantunovi/lucidshark/main/install.ps1 | iex
# 2. 设置 Claude Code
lucidshark init
# 3. 重启您的 AI 工具，然后询问它：
# "Autoconfigure LucidShark for this project"
```
就是这样！你的 AI 助手将分析你的代码库，询问你几个问题，并生成 `lucidshark.yml` 配置。
### 安装选项
| 方式 | 命令 | 说明 |
|--------|---------|-------|
| **pip** | `pip install lucidshark` | 需要 Python 3.10+ |
| **Binary (Linux/macOS)** | `curl -fsSL .../install.sh \| bash` | 无需 Python |
| **Binary (Windows)** | `irm .../install.ps1 \| iex` | 无需 Python |
| **Manual** | 从 [Releases](https://github.com/toniantunovi/lucidshark/releases) 下载 | 预编译二进制文件 |
安装脚本会提示你选择：
- **全局安装** (`~/.local/bin` 或 `%LOCALAPPDATA%\Programs\lucidshark`) - 系统范围可用
- **项目本地安装** (当前目录) - 项目专用，将二进制文件保留在你的项目根目录中
### 运行扫描
```
lucidshark scan --all # Run all quality checks
lucidshark scan --linting # Run specific domains
lucidshark scan --linting --fix # Auto-fix linting issues
lucidshark scan --all --dry-run # Preview what would be scanned
```
扫描域：`--linting`, `--type-checking`, `--sast`, `--sca`, `--iac`, `--container`, `--testing`, `--coverage`, `--duplication`
### 输出示例
当发现问题时：
```
$ lucidshark scan --linting --type-checking --sast
Total issues: 4
By severity:
HIGH: 1
MEDIUM: 2
LOW: 1
By scanner domain:
LINTING: 2
TYPE_CHECKING: 1
SAST: 1
Scan duration: 1243ms
```
当一切通过时：
```
$ lucidshark scan --all
No issues found.
```
使用 `--format table` 查看详细的问题明细，或使用 `--format json` 获取机器可读的输出。
### 诊断
使用 doctor 命令检查你的 LucidShark 设置：
```
lucidshark doctor
```
这将检查：
- 配置文件是否存在且有效
- 工具可用性（安全扫描器、Linter、类型检查器）
- Python 环境兼容性
- Git 仓库状态
- MCP 集成 (Claude Code)
### AI 工具设置
```
lucidshark init # Configure Claude Code (.mcp.json + .claude/CLAUDE.md)
```
运行 `init` 后重启你的 AI 工具以激活。
## 支持的语言
LucidShark 支持 15 种编程语言，工具覆盖程度各不相同：
| 级别 | 语言 | 包含内容 |
|------|-----------|-----------------|
| **Full** | Python, TypeScript, JavaScript, Java, Rust | Linting, 类型检查, 测试, 覆盖率, 安全, 重复检测 |
| **Partial** | Kotlin | 测试, 覆盖率, 安全 (通过共享的 Java 工具) |
| **Basic** | Go, Ruby, C, C++, C# | 安全扫描, 重复检测 |
| **Minimal** | PHP, Swift, Scala | 安全扫描 |
有关每种语言的详细工具覆盖范围、配置示例和检测信息，请参阅 [Language Reference](docs/languages/README.md)。
## 检查内容
| 域 | 工具 | 捕获内容 |
|--------|-------|-----------------|
| **Linting** | Ruff, ESLint, Biome, Checkstyle, Clippy | 风格问题, 代码异味 |
| **Type Checking** | mypy, Pyright, TypeScript (tsc), SpotBugs, cargo check | 类型错误, 静态分析 Bug |
| **Security (SAST)** | OpenGrep | 代码漏洞 |
| **Security (SCA)** | Trivy | 依赖漏洞 |
| **Security (IaC)** | Checkov | 基础设施配置错误 |
| **Security (Container)** | Trivy | 容器镜像漏洞 |
| **Testing** | pytest, Jest, Karma (Angular), Playwright (E2E), Maven/Gradle (JUnit), cargo test | 测试失败 |
| **Coverage** | coverage.py, Istanbul, JaCoCo, Tarpaulin | 覆盖率缺口 |
| **Duplication** | Duplo | 代码克隆, 重复代码块 |
所有结果都归一化为通用格式。
## 配置
LucidShark 自动检测你的项目。如需自定义设置，请创建 `lucidshark.yml`：
```
version: 1
pipeline:
linting: { enabled: true, tools: [{ name: ruff }] }
type_checking: { enabled: true, tools: [{ name: mypy, strict: true }] }
security: { enabled: true, tools: [{ name: trivy }, { name: opengrep }] }
testing:
enabled: true
command: "make test" # Optional: custom command overrides plugin-based runner
post_command: "make clean" # Optional: runs after tests complete
tools: [{ name: pytest }]
coverage: { enabled: true, threshold: 80 }
duplication: { enabled: true, threshold: 10.0 }
fail_on:
linting: error
security: high
testing: any
ignore_issues:
- rule_id: CVE-2021-3807
reason: "Not exploitable in our context"
expires: 2026-06-01
exclude: ["**/node_modules/**", "**/.venv/**"]
```
完整配置参考请见 [docs/help.md](docs/help.md)。
## CLI 参考
| 命令 | 描述 |
|---------|-------------|
| `lucidshark scan --all` | 运行所有质量检查 |
| `lucidshark scan --linting --fix` | Lint 并自动修复 |
| `lucidshark init` | 配置 Claude Code 集成 |
| `lucidshark doctor` | 检查设置和环境健康状况 |
| `lucidshark validate` | 验证 `lucidshark.yml` |
完整的 CLI 参考、所有扫描标志、输出格式和退出代码，请见 [docs/help.md](docs/help.md)。
## 开发
```
git clone https://github.com/toniantunovi/lucidshark.git
cd lucidshark
pip install -e ".[dev]"
pytest tests/
```
## 文档
- [支持的语言](docs/languages/README.md) - 每种语言的工具覆盖、检测和配置
- [LLM 参考文档](docs/help.md) - 适用于 AI Agent 和详细参考
- [排除模式与忽略问题](docs/exclude-patterns.md) - 文件排除、按域排除和忽略特定问题
- [完整规范](docs/main.md)
## 许可证
Apache 2.0
标签：AI原生, AI应用开发, Claude, CVE检测, DevSecOps, DLL 劫持, IaC安全, Linting, LLM, MCP, Python, SAST, Unmanaged PE, 上游代理, 人工智能辅助开发, 基础设施即代码扫描, 大语言模型, 安全规则引擎, 文档结构分析, 无后门, 本地优先, 流水线, 盲注攻击, 类型检查, 覆盖率, 逆向工具, 重复代码检测, 错误基检测, 静态代码分析