Wintersta7e/Vectis

# Vectis 便携式 C++20 CLI，可生成源代码树的结构化摘要 架构 — 符号、依赖关系、架构标签、复杂度 热点 — 供外部 LLM 代理（Claude Code、CI 流水线、脚本）使用 [](https://github.com/Wintersta7e/Vectis/actions/workflows/ci.yml) [](./LICENSE)    ## 功能特性 - **12 种语言** — Python、JavaScript、TypeScript、C、C++、Rust、Java、C#、Go、Ruby、PHP、SQL。 - **10 种架构标签**，置信度 0–100 — Monolith、Layered、MVC、MVVM、Clean Architecture、Monorepo、Frontend SPA、API Backend、.NET Solution、Library。**基于 33 个项目的参考语料库进行校准，每个类别的精确率/召回率均达到 100%。** - **每个符号的 API 表面** — 每个符号都携带一个 `visibility` 字段（`public` / `private` / `protected` / `internal`），源自各语言的原生习惯（Go 的大小写约定、Python 的下划线约定、Rust 的 `pub` 关键字、Java/C#/TypeScript 修饰符）。 - **装饰器/注解捕获** — 支持 Python、Java、C# 和 Rust。精简摘要中包含 `@app.route(...)`、`@RestController`、`[HttpGet]`、`#[tokio::test]` 等结构化字符串 — 代理可以查找路由处理器、测试、DI 标记，无需重新解析源代码。 - **跨文件依赖图**，支持命名空间感知解析（Java/C#/PHP 通过命名空间索引，Go 通过 `go.mod`，Python 相对导入针对源代码包）。 - **循环检测**（Tarjan 迭代 SCC）和基于复杂度的**热点**排名，完整摘要中包含代码片段。 - **`vectis explain`** — 10 行纯文本叙述摘要，可供人类/LLM 代理直接使用。 - **`.gitignore` 感知扫描**，外加激进的默认排除列表，确保虚拟环境和构建输出不会污染摘要。 - **增量重新扫描**，通过 `--cache` — 基于内容哈希差分，仅重新解析变更的文件。 - **单一二进制文件**，静态链接时零运行时依赖。摘要生成过程中无网络调用。 ## 快速开始 系统包（Ubuntu 24.04 / WSL2）： ``` sudo apt install -y build-essential cmake ninja-build git pkg-config \ libsqlite3-dev libspdlog-dev libfmt-dev nlohmann-json3-dev \ libtomlplusplus-dev libgtest-dev cmake -B build -S . -G Ninja -DCMAKE_BUILD_TYPE=Release cmake --build build --parallel ctest --test-dir build ``` 然后： ``` ./build/vectis explain /path/to/project # narrative summary ./build/vectis digest /path/to/project --format slim # structured JSON ``` `vectis explain` 是让代理快速了解陌生代码库的最快方式。示例输出（Flask）： ``` flask — Library (75% confidence) Architecture: Python library (pyproject.toml + `flask/__init__.py`, no app entry). Scale: 85 files, 1622 symbols, 613 dependency edges. Languages: Python (98%, 83 files), SQL (2%, 2 files). API surface: 1575 public / 47 private. Top hotspots (by cyclomatic complexity): src/flask/sansio/blueprints.py:273 register [function, complexity 22] src/flask/app.py:1224 make_response [function, complexity 17] ... Decorators (top 5 over 657 decorated symbols): @app.route("/") (99), @setupmethod (43), @t.overload (18), @pytest.fixture (17), @app.teardown_request (14). Dependency graph: 171 internal edges, 1 cycle. External imports (top 5): flask (78), pytest (23), werkzeug.exceptions (23), werkzeug.routing (19), os (15). ``` 用于流水线的精简 JSON（摘录）： ``` { "architecture": { "confidence": 75, "label": "Library", "reasoning": "Python library (pyproject.toml + `flask/__init__.py`, …)" }, "symbols": [ { "name": "register", "kind": "function", "path": "src/flask/sansio/blueprints.py", "line": 273, "visibility": "public", "decorators": ["setupmethod"] } ], "dependency_graph": { "edges": [/* … */], "stats": { "internal_edges": 171 } }, "hotspots": [ /* top 10, no body excerpts */ ], "project": { "file_count": 85, "symbol_count": 1622 } } ``` vckg 路径适用于 Windows/便携式静态构建；请参阅 `CMakeLists.txt`。 ## 子命令和格式 | 命令 | 输出 | 用例 | |---|---|---| | `vectis explain` | 文本 | 供人类/LLM 代理使用的叙述摘要 | | `vectis digest --format slim` | JSON | 适合代理上下文的令牌高效结构化映射 | | `vectis digest --format json` | JSON | 完整的每文件符号、热点摘录、平坦 `symbols[]` | | `vectis digest --format md` | Markdown | PR 风格审查输出 | 常用标志（`--cache`、`--cache-dir`、`--output`、`-q` / `-v`）在两个子命令上都可用。`vectis --help` 列出所有选项。 ## 流水线 ``` scan tree (.gitignore + built-in excludes) │ ▼ parse files (tree-sitter, 12 grammars) │ symbols + imports + namespaces ▼ resolve dependencies (paths + namespace index + go.mod) │ ▼ ┌──────────────┬──────────────┬──────────────┐ │ cycles │ hotspots │ architecture │ │ (Tarjan) │ (severity) │ (label) │ └──────────────┴──────────────┴──────────────┘ │ ▼ emit digest (slim JSON · full JSON · Markdown) ``` 当使用 `--cache` 时，状态持久化在 `/vectis-data/vectis.db`（SQLite WAL + FTS5）。 ## 它不是什么 无 GUI。无 LSP 服务器。无嵌入式 LLM 或聊天 UI。无代码修改 — 只读，始终如此。摘要生成过程中无网络调用。 ## 许可证 MIT。第三方归属见 `NOTICES.md`。

标签：AI代理, AST解析, Bash脚本, C++20, IPv6支持, LLM, SOC Prime, tree-sitter, Unmanaged PE, 云安全监控, 代码度量, 代码摘要, 代码架构分析, 依赖图分析, 复杂度分析, 多语言支持, 安全测试框架, 开发工具, 循环检测, 数据管道, 架构模式识别, 架构识别, 源代码分析, 符号分析, 软件工程, 静态分析