Metadata-Version: 2.4
Name: vcode-analysis
Version: 0.10.0
Summary: 基于大模型的智能代码分析工具，支持代码审查、文档生成、架构分析和安全扫描
Author-email: Wellchang <2483808264@qq.com>
License: MIT
Project-URL: Homepage, https://xxxxxx
Project-URL: Repository, https://xxxxxx
Project-URL: Documentation, https://xxxxxx
Project-URL: Bug Tracker, https://xxxxxx
Keywords: vcode-analysis,llm,code-review,documentation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: docopt-ng>=0.9.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: rich
Requires-Dist: rich>=13.0.0; extra == "rich"
Provides-Extra: parsers
Requires-Dist: javalang>=0.13.0; extra == "parsers"
Requires-Dist: pycparser>=2.21; extra == "parsers"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Dynamic: license-file

# VCode Analysis

基于私有化部署大模型的智能代码分析工具。兼容 OpenAI API 格式，支持代码审查、文档生成、架构分析和安全扫描。

## 特性

- **代码审查** — 1-10 评分 + 问题定位 + 改进建议
- **批量分析** — 智能打包多文件为单次 API 调用，减少 85%+ 请求量
- **双层缓存** — 内存 LRU + 磁盘持久化，二次分析减少 98% 调用
- **多模型降级** — 配置多个 LLM 模型，自动故障降级与冷却恢复
- **安全扫描** — 正则规则引擎 + LLM 深度语义分析
- **架构分析** — 模块识别、依赖关系、耦合度评估
- **文档生成** — 模块文档 / API 文档 / README 自动生成
- **知识图谱** — 自动构建代码库领域模型（实体、关系、业务规则）
- **多语言解析** — Python/Java AST、Kotlin/C 双模式、JS/TS/Vue 正则
- **上下文增强** — 自动构建项目依赖关系，提升分析质量
- **Git 集成** — 单仓库 + 批量多仓库操作
- **交互式报告** — Markdown + HTML（排序、筛选、折叠）
- **JSON 容错** — 自动修复 LLM 输出中的 JSON 格式问题（尾随逗号、代码块包裹等）
- **量化指标** — 漏洞检出率、误报率、修复采纳率，SQLite 持久化存储
- **反馈闭环** — 开发者标记误报/确认/修复，驱动规则调优与 LLM 提示词优化
- **MCP Server** — Tool/Resource/Prompt 三能力注册，无缝接入 AI 工具链

## 安装

```bash
# 使用 pip
pip install vcode-analysis

# 或使用 uvx 直接运行
uvx vcode-analysis review ./src
```

### 可选依赖

```bash
# Java AST 解析
pip install javalang

# C 语言精确解析
pip install pycparser

# 富文本终端输出
pip install rich

# MCP Server（接入 AI 工具链）
pip install vcode-analysis[mcp]
```

## 快速开始

### 1. 配置 LLM 服务

```bash
# 方式一：环境变量
export OPENAI_API_BASE=http://localhost:8000/v1
export OPENAI_API_KEY=sk-your-key

# 方式二：配置文件
vcode-analysis config --init
# 编辑 ~/.code-analysis/config.yaml

# 方式三：命令行参数
vcode-analysis review ./src --base-url http://localhost:8000/v1 --model qwen35-35b-a3b
```

### 2. 代码审查

```bash
# 审查目录（默认启用批量+缓存）
vcode-analysis review ./src

# 审查单个文件
vcode-analysis review ./src/main.py

# 指定输出格式
vcode-analysis review ./src -o report.md -f markdown
vcode-analysis review ./src -o report.html -f html

# 启用上下文增强（提升分析质量）
vcode-analysis review ./src --context

# 审查 Git 提交
vcode-analysis review-commit abc1234
```

### 3. 其他分析

```bash
# 生成文档
vcode-analysis doc ./src --type module
vcode-analysis doc ./src --type api
vcode-analysis doc ./src --type readme

# 架构分析
vcode-analysis arch ./src

# 安全扫描
vcode-analysis security ./src
vcode-analysis security ./src --deep    # LLM 深度扫描

# 目录扫描
vcode-analysis scan-dir ./src

# 知识图谱
vcode-analysis kg ./src
vcode-analysis kg ./src --format json    # JSON 格式输出
vcode-analysis kg ./src --llm           # LLM 增强分析
vcode-analysis kg ./src --workers 3     # 并发解析
```

### 4. 量化指标与反馈闭环

```bash
# 查询量化指标（检出率、误报率、修复率）
vcode-analysis metrics . --from 2026-01-01 --to 2026-12-31
vcode-analysis metrics . --group-by rule_id --format json

# 标记问题状态（驱动规则调优）
vcode-analysis feedback <issue-id> --status false_positive --note "误报原因"
vcode-analysis feedback <issue-id> --status confirmed
vcode-analysis feedback <issue-id> --status fixed

# 查看待复核问题
vcode-analysis feedback pending --limit 20

# 批量导入反馈
vcode-analysis feedback import feedback.json

# 启用指标采集（review/security 命令加 --metrics）
vcode-analysis review ./src --metrics
vcode-analysis security ./src --metrics
```

### 5. MCP Server

```bash
# 安装 MCP 依赖
pip install vcode-analysis[mcp]

# stdio 模式（本地 AI 工具链集成）
vcode-mcp

# HTTP 模式（远程部署）
vcode-mcp --transport streamable-http --port 8765
```

MCP Server 提供 8 个 Tool、3 个 Resource、3 个 Prompt：

| 类型 | 名称 | 说明 |
|------|------|------|
| Tool | `review` | 代码审查 |
| Tool | `security` | 安全扫描 |
| Tool | `arch` | 架构分析 |
| Tool | `doc` | 文档生成 |
| Tool | `kg` | 知识图谱 |
| Tool | `scan_dir` | 目录扫描 |
| Tool | `feedback` | 反馈标记 |
| Tool | `metrics` | 指标查询 |
| Resource | `vcode://reports/{run_id}` | 历史报告 |
| Resource | `vcode://rules/{rule_id}` | 规则定义 |
| Resource | `vcode://metrics/summary` | 指标汇总 |
| Prompt | `code-review-checklist` | 代码审查清单 |
| Prompt | `vuln-tuning-advisor` | 规则调优顾问 |
| Prompt | `mr-review-template` | MR 审查模板 |

### 6. Git 操作

```bash
# 克隆并分析
vcode-analysis clone https://github.com/user/repo.git

# 批量克隆（从文件读取 URL 列表）
vcode-analysis batch-clone repos.txt ./workspace

# 批量拉取
vcode-analysis batch-pull ./workspace

# 多仓库状态
vcode-analysis git-status ./workspace
```

## 命令参考

```
vcode-analysis review <path>              代码审查
vcode-analysis review-commit <commit>     审查指定提交
vcode-analysis doc <path>                 生成文档
vcode-analysis arch <path>                架构分析
vcode-analysis security <path>            安全扫描
vcode-analysis kg <path>                  知识图谱生成
vcode-analysis clone <url>                克隆仓库并分析
vcode-analysis batch-clone <file> <dir>   批量克隆
vcode-analysis batch-pull <dir>           批量拉取
vcode-analysis git-status <dir>           多仓库状态
vcode-analysis scan-dir <path>            目录扫描
vcode-analysis metrics <path>             量化指标查询
vcode-analysis feedback <issue-id>        反馈管理
vcode-analysis config [--init|--show]     配置管理
```

### 全局选项

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `-c, --config` | 配置文件路径 | `~/.code-analysis/config.yaml` |
| `--base-url` | LLM API 地址 | `http://localhost:8000/v1` |
| `--api-key` | API 密钥 | `sk-dummy` |
| `-m, --model` | 模型名称 | `qwen35-35b-a3b` |
| `--max-tokens` | 最大输出 Token | 4096 |
| `--timeout` | 请求超时（秒） | 180 |
| `-o, --output` | 输出文件路径 | 自动生成 |
| `-f, --format` | 输出格式（markdown/json/html） | markdown |
| `-w, --workers` | 并发线程数 | 5 |
| `--context` | 启用上下文增强 | 关闭 |
| `--no-cache` | 禁用缓存 | 关闭 |
| `--no-batch` | 禁用批量分析 | 关闭 |
| `--metrics` | 启用指标采集 | 关闭 |
| `--from <date>` | 起始日期（metrics） | 2000-01-01 |
| `--to <date>` | 截止日期（metrics） | 2099-12-31 |
| `--group-by <field>` | 分组字段（metrics） | rule_id |
| `--status <status>` | 问题状态（feedback） | - |
| `--note <text>` | 备注（feedback） | - |

## 配置文件

`~/.code-analysis/config.yaml`：

### 单模型配置

```yaml
llm:
  base_url: "http://localhost:8000/v1"
  api_key: "sk-your-key"
  model: "qwen35-35b-a3b"
  temperature: 0.7
  max_tokens: 8192
  timeout: 180

analysis:
  max_file_size: 102400
  max_workers: 5
  ignore_patterns:
    - "custom_ignore/**"
  supported_extensions:
    - ".py"
    - ".java"
    - ".kt"

cache:
  ttl: 604800
  memory_cache_size: 1000

metrics:
  enabled: true
  db_path: "~/.code-analysis/metrics.db"

feedback:
  http_port: 8766
  auto_start_server: false

mcp:
  transport: "stdio"
  http_port: 8765
  auth_token: ""
```

### 多模型配置（故障自动降级）

配置多个 LLM 模型时，主模型请求失败会自动降级到备用模型：

```yaml
llm:
  cooldown_seconds: 300        # 故障模型冷却期（秒）
  max_retries_per_model: 1     # 单模型最多重试次数
  models:
    - base_url: "http://localhost:8000/v1"
      api_key: "sk-primary"
      model: "qwen35-35b-a3b"
      temperature: 0.7
      max_tokens: 8192
    - base_url: "http://localhost:8001/v1"
      api_key: "sk-backup"
      model: "kimi-latest"
      temperature: 0.7
      max_tokens: 8192
```

降级策略：
- 可降级错误：超时、连接错误、5xx、429 限流、401 认证失败
- 不可降级错误：客户端请求格式错误等，直接抛出异常
- 冷却恢复：失败模型进入冷却期，冷却结束后自动恢复可用

### 环境变量

| 变量 | 说明 |
|------|------|
| `OPENAI_API_BASE` / `OPENAI_BASE_URL` | LLM API 地址 |
| `OPENAI_API_KEY` | API 密钥 |
| `CODE_ANALYSIS_MODEL` | 模型名称 |
| `CODE_ANALYSIS_TEMPERATURE` | 温度参数 |
| `CODE_ANALYSIS_MAX_TOKENS` | 最大输出 Token |

## 支持的语言

| 语言 | 扩展名 | 解析方式 |
|------|--------|----------|
| Python | `.py` | AST |
| Java | `.java` | AST (javalang) |
| Kotlin | `.kt`, `.kts` | 双模式 (fast/precise) |
| C | `.c`, `.h` | 双模式 (fast/precise) |
| C++ | `.cpp`, `.hpp`, `.cc`, `.cxx` | 正则 |
| JavaScript | `.js`, `.jsx` | 正则 |
| TypeScript | `.ts`, `.tsx` | 正则 |
| Vue | `.vue` | 正则 |
| Go | `.go` | 正则 |
| Rust | `.rs` | 正则 |
| 配置文件 | `.json`, `.yaml`, `.yml` | 文本 |
| Markdown | `.md` | 文本 |

## 批量分析原理

```
100 个 Python 文件
    │
    ▼  按语言分组 + Token 估算
    │
    ├── 批次 1: file_01.py + file_03.py + file_07.py  (~7500 tokens)
    ├── 批次 2: file_02.py + file_05.py               (~6000 tokens)
    ├── ...
    └── 批次 15: file_98.py + file_99.py              (~5000 tokens)
    │
    ▼  每批合并为一次 API 调用
    │
    100 次 → ~15 次 API 调用（减少 85%）
```

**二次分析**（10 个文件变更）：缓存命中 90 个文件，仅分析 10 个 → ~2 次调用（减少 98%）。

## 项目结构

```
code-analysis/
├── cli.py                     CLI 入口
├── core/                      核心模块
│   ├── analyzer.py            分析引擎
│   ├── llm_client.py          LLM 客户端（单模型 + 故障降级）
│   ├── config.py              配置管理（多模型 + metrics/feedback/mcp）
│   ├── ignore.py              过滤规则
│   ├── git_handler.py         Git 操作
│   ├── batch_planner.py       批量规划
│   ├── batch_analyzer.py      批量分析
│   ├── cache_manager.py       缓存管理
│   ├── token_estimator.py     Token 估算
│   ├── json_utils.py          JSON 解析容错
│   ├── metrics_store.py       量化指标采集（SQLite）
│   ├── feedback_hub.py        反馈接收 HTTP 服务
│   └── report_generator.py    报告生成（Markdown + 交互式 HTML + 反馈按钮）
├── analyzers/                 分析器
│   ├── code_review.py         代码审查（集成指标落库 + 调优提示词注入）
│   ├── documentation.py       文档生成
│   ├── architecture.py        架构分析
│   ├── security.py            安全扫描（集成指标落库 + 抑制条件）
│   ├── directory.py           目录分析
│   ├── context_builder.py     上下文构建
│   └── knowledge_graph.py     知识图谱
├── vcode_mcp/                 MCP Server
│   ├── server.py              MCPServer 入口（Tool/Resource/Prompt 注册）
│   ├── tool_handler.py        Tool 分发逻辑
│   ├── resource_handler.py    Resource 读取器
│   ├── prompt_handler.py      Prompt 模板
│   └── transports/            传输层（stdio / streamable-http）
├── parsers/                   解析器
│   ├── python_parser.py       Python AST
│   ├── java_parser.py         Java AST
│   ├── kotlin_parser.py       Kotlin 双模式
│   ├── c_parser.py            C 双模式
│   ├── javascript_parser.py   JavaScript
│   └── typescript_parser.py   TypeScript
├── scripts/                   运维脚本
│   ├── tune_rules.py          规则调优报告
│   └── tune_prompts.py        提示词调优上下文生成
└── docs/                      文档
    ├── USER_MANUAL.md         用户手册
    └── design/                设计文档
```

## 文档

- [用户手册](docs/USER_MANUAL.md)
- [设计文档](docs/design/vcode-analysis-tool.md)
- [批量分析优化设计](docs/design/batch-cache-optimization.md)
- [Kotlin 解析器设计](docs/design/kotlin-parser-design.md)
- [C 解析器设计](docs/design/c-parser-design.md)
- [代码知识图谱设计](docs/design/code-knowledge-graph.md)
- [专家评审意见响应设计](docs/design/expert-review-response-2026-07.md)
- [三年发展规划](docs/design/three-year-roadmap.md)

## License

MIT
