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 工具链

安装

# 使用 pip
pip install vcode-analysis

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

可选依赖

# Java AST 解析
pip install javalang

# C 语言精确解析
pip install pycparser

# 富文本终端输出
pip install rich

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

快速开始

1. 配置 LLM 服务

# 方式一：环境变量
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. 代码审查

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

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

# 指定输出路径（默认生成 Markdown 报告，并自动生成同目录 .html 交互报告）
vcode-analysis review ./src -o report.md

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

# 审查 Git 提交（结果默认保存到 result/ 目录，-o 可指定路径）
vcode-analysis review-commit abc1234

3. 其他分析

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

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

# 重复代码检查（多维分析 + 修改建议）
vcode-analysis dup ./src
vcode-analysis dup ./src --min-lines 10       # 只报告 ≥10 行的重复
vcode-analysis dup ./src --min-similarity 0.9 # 提高近似重复判定门槛
vcode-analysis dup ./src --llm                # LLM 生成统一重构方案
vcode-analysis dup ./src --format json        # JSON 格式输出

# 安全扫描
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. 量化指标与反馈闭环

# 查询量化指标（检出率、误报率、修复率）
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

# 安装 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：

6. Git 操作

# 克隆并分析（结果默认保存到 result/ 目录，-o 可指定路径）
vcode-analysis clone https://github.com/user/repo.git

# 克隆后自动执行代码审查并保存报告
vcode-analysis clone https://github.com/user/repo.git --analyze

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

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

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

Web 操作台（可视化）

提供浏览器操作界面，无需记忆 CLI 命令即可启动分析、查看结果、标记反馈、管理配置与查看指标：

# 安装 Web 依赖（如已用 uv：uv add fastapi "uvicorn[standard]"）
pip install fastapi "uvicorn[standard]"

# 启动（默认 http://127.0.0.1:8970）
python web/app.py

# 局域网共享：python web/app.py --host 0.0.0.0 --port 8970

• 控制台：选路径 + 分析类型 + 高级选项，一键运行，实时进度/日志
• 分析结果：问题明细 + 严重度筛选 + 在线标记「误报/确认/已修复」
• 模型配置：可视化编辑 LLM 参数并自动写入 config.yaml，内置连通性测试
• 指标看板：累计问题 / 误报率 / 修复率 + 规则与严重度分布图

详见 web/README.md。

命令参考

vcode-analysis review <path>              代码审查
vcode-analysis review-commit <commit>     审查指定提交
vcode-analysis doc <path>                 生成文档
vcode-analysis arch <path>                架构分析
vcode-analysis security <path>            安全扫描
vcode-analysis dup <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]     配置管理

全局选项

配置文件

~/.code-analysis/config.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
  # 自定义请求头：调用 LLM 时附加到 HTTP 头（可覆盖默认头）
  custom_headers:
    X-Tenant: "tenant-a"
    X-Trace-Id: "trace-001"
  # 聊天请求路径（base_url 后的 path，默认 /chat/completions）
  chat_path: "/chat/completions"

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

cache:
  ttl: 604800
  memory_cache_size: 1000

duplication:
  min_block_lines: 6        # 代码块最小重复行数
  min_similarity: 0.8       # 近似重复最低相似度
  min_function_lines: 6     # 函数级检测最小函数体行数
  enable_function_level: true

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 模型时，主模型请求失败会自动降级到备用模型：

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 认证失败
• 不可降级错误：客户端请求格式错误等，直接抛出异常
• 冷却恢复：失败模型进入冷却期，冷却结束后自动恢复可用

环境变量

支持的语言

批量分析原理

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            安全扫描（集成指标落库 + 抑制条件）
│   ├── duplication.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/                设计文档

文档

• 用户手册
• 设计文档
• 批量分析优化设计
• Kotlin 解析器设计
• C 解析器设计
• 代码知识图谱设计
• 专家评审意见响应设计
• 三年发展规划

License

MIT