shivin4/logiclens

# LogicLens **版本 1.1.0** — 本地优先的桌面应用，可将代码库作为**依赖关系图**进行探索，运行**语义搜索**，查看 **git** 上下文，并使用 **AI**（Groq + CrewAI）进行解释和“假设”爆炸半径风格的报告。无需单独的数据库服务器：图结构存储在 **SQLite** 中，向量数据存储在 **ChromaDB** 中，所有数据均保存在您机器的应用数据文件夹中。 ## 核心亮点 - **桌面优先：** `desktop_main.py`（或打包后的 `.exe`）会打开一个原生窗口（pywebview + Waitress）。 - **首次运行引导：** `/onboarding` — 配置 API 密钥，可选的遥测标志，选择文件夹，然后进行分析（当 Groq 未配置时会自动打开）。 - **增量分析：** 在同一项目上重新运行 **Analyze** 只会重新处理 **mtime + size** 发生变化的文件（包括新增/删除的文件）。切换到另一个代码库会强制进行**完整**的图重建（单一共享的 `logiclens_graph.db`）。 - **项目专属 Chroma：** 每个被分析的文件夹都有其专属的集合（`ll_proj_`）；其他项目的向量数据保留在磁盘上。 - **更新检查：** 设置 → **Check for updates** 会调用 GitHub Releases（默认为 `shivin4/logiclens`；可通过环境变量覆盖）。 - **可选遥测：** 通过 UI 选择启用；需要在 `.env` 中配置 `SENTRY_DSN` 并安装 `sentry-sdk`。如果没有 DSN，则**不会发送任何数据**。 - **无障碍访问：** 交互控件上可见的**焦点环**；设置对话框具有 **ARIA** 标签，支持 **Escape** 键关闭，并在打开时将焦点移入对话框。 ## 技术栈 | 层级 | 技术选型 | |--------|--------| | UI | Flask-served templates, Tailwind, vis-network | | Server | Waitress (桌面端), 可选 Flask 开发服务器 | | Graph | SQLite (`logiclens_graph.db`) | | Vectors | ChromaDB (持久化目录) | | Parse | Tree-sitter | | AI | Groq (解释 / LLM), CrewAI (what-if) | ## 支持的语言 `.py` · `.js` / `.jsx` · `.ts` / `.tsx` · `.java` · `.go` · `.cpp` / `.cc` / `.h` / `.hpp` ## 快速开始 (开发) **前提条件：** Python 3.10+，Groq API key（用于 AI 功能）。 ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python desktop_main.py ``` 如果未在 `%LOCALAPPDATA%\LogicLens\.env`（打包版）或项目的 `.env`（开发版）中设置 `GROQ_API_KEY`，应用将首先打开**引导页**。 **仅浏览器调试**（非正常工作流）： ``` set LOGICLENS_DEBUG=1 python app.py ``` 然后打开 `http://127.0.0.1:5000`。 ## 首次运行与 API 密钥 1. **引导页** (`/onboarding`)：Groq（必填），Gemini（选填），可选的崩溃报告复选框，然后选择一个文件夹并点击 **Analyze & open app**。 2. 或者随时使用 **Settings → Open setup page** (`/setup`)。 密钥在打包时会写入 **`%LOCALAPPDATA%\LogicLens\.env`**，在开发时则写入您配置的 `LOGICLENS_DATA_DIR` 中。 请参阅 **`.env.example`** 了解所有选项（`LOGICLENS_FULL_ANALYZE`、遥测、Sentry 等）。 ## 分析工作原理 (简述) | 情况 | 发生的操作 | |-----------|----------------| | 文件夹**首次**分析 | 完整重建：清除 SQLite 图，重新创建该项目的 Chroma 集合，遍历所有符合条件的文件，构建图结构 + 向量数据。 | | **再次分析**同一文件夹 | 增量更新：仅更新 **mtime/size** 发生变化（或新增/删除路径）的文件；其余跳过。 | | 在另一个项目后分析**不同**文件夹 | 对新文件夹进行完整重建（SQLite 一次只保存一个项目）。 | 指纹清单：`analysis_manifest_.json`。强制完整重建：`LOGICLENS_FULL_ANALYZE=1`。 ## 磁盘数据 除非您设置了 `LOGICLENS_DATA_DIR`，否则所有路径均位于**应用数据目录**下： | 位置 | 作用 | |----------|------| | **应用数据目录** | 本地状态的单一“主目录”。**打包版：** `%LOCALAPPDATA%\LogicLens\`。**开发版：** 通常是代码库根目录，除非被 `LOGICLENS_DATA_DIR` 覆盖。 | | **`logiclens_graph.db`** (SQLite) | **一个文件**，**一次只包含一个逻辑图**：无论您上次成功分析的是哪个项目。它**不是**一个多代码库数据库；它会被清除或修补以匹配**一个**工作区根目录。 | | **`chroma_data/`** (Chroma) | 磁盘上有**多个集合**。每个项目文件夹都有自己的集合名称（`ll_proj_`）。当您打开其他代码库时，旧项目的向量数据**保留**在磁盘上。 | | **`analysis_manifest_.json`** | 每个项目的**文件指纹**账本（每个规范化路径的 `mtime_ns` + `size`）。用于驱动该根目录的**增量**或**完整**分析工作。 | | **`last_graph_project_root.txt`** | 单行文本：当前 **SQLite** 文件描述的项目的规范化路径。如果您分析了一个**不同**的根目录，代码会强制进行一次**完整**的图重建，以避免在其他项目的节点之上运行增量分析。 | | 应用数据中的 **`.env`** | API 密钥和可选的覆盖配置（来自 `/setup`、引导页或手动编辑）。 | **为什么同时使用 SQLite 和 Chroma？** SQLite 存储**结构**（节点/边、调用、API 桥接）。Chroma 存储**语义搜索**和需要原始代码片段的工具的**向量数据**。它们会针对更改的文件一起更新。 ## 更新 - **UI：** 设置 → **Check for updates** — 将 `logiclens/version.py`（或 `LOGICLENS_APP_VERSION`）与 `https://api.github.com/repos///releases/latest` 进行比较。 - **覆盖代码库：** 在 `.env` 中设置 `LOGICLENS_GITHUB_OWNER`，`LOGICLENS_GITHUB_REPO`。 ## 遥测 (隐私优先) - **默认：** 关闭。除非设置了 `LOGICLENS_TELEMETRY=1` **且** `SENTRY_DSN` 已配置，否则不会运行任何分析 SDK。 - **行为：** `sentry-sdk` + Flask 集成；`send_default_pii=False`，`traces_sample_rate=0`。 - 安装：包含在 `requirements.txt` 中；未使用时完全无害。 ## 无障碍 - **焦点：** 按钮、链接、输入框上的 `:focus-visible` 轮廓。 - **设置模态框：** `role="dialog"`，`aria-labelledby`，`aria-describedby`，带有标签的关闭按钮，**Escape** 键关闭，初始焦点位于对话框面板上。 ## 打包与信任 | 文档 | 目的 | |-----|---------| | **[packaging/BUILD_INSTALLER.md](packaging/BUILD_INSTALLER.md)** | PyInstaller → Inno Setup 流水线 | | **[packaging/SIGNING.md](packaging/SIGNING.md)** | 对 `LogicLens.exe` 和安装程序进行代码签名，以减少 SmartScreen 警告 | **版本更新检查清单：** 同步 `logiclens/version.py` (`_DEFAULT_VERSION`)、`packaging/installer.iss` (`MyAppVersion`)、`docs/index.html` (`INSTALLER_URL` 资产名称) 以及您的 GitHub Release 资产文件名。 ``` pyinstaller packaging\logiclens.spec # 可选：对 dist\LogicLens\LogicLens.exe 进行签名（参见 SIGNING.md） # 编译 packaging\installer.iss → dist_installer\LogicLens-Setup-1.1.0.exe ``` ## 落地页 静态网站：**[docs/index.html](docs/index.html)** — 设置 `INSTALLER_URL` / `SOURCE_URL`，托管在 GitHub Pages / Netlify / Vercel — **[docs/DEPLOY.md](docs/DEPLOY.md)** (Pages: 分支 `main`，文件夹 **`/docs`** )。 ## 项目结构 | 路径 | 作用 | |------|------| | `app.py` | Flask 应用，REST API，模板路由 | | `desktop_main.py` | Waitress + pywebview 入口 | | `extractor.py` | Tree-sitter 提取，增量分析，Chroma 更新插入 | | `whatif_engine.py` | 安全的 What-If 入口 (SSE)；委托给 `whatif_crew.py` | | `whatif_crew.py` | CrewAI 实现 (可选依赖) | | `logiclens/config.py` | 路径，环境变量，`normalize_project_file_path`，Chroma 集合命名 | | `logiclens/sqlite_graph.py` | 图 CRUD，`delete_file_subgraph` | | `logiclens/version.py` | `__version__`，用于更新的默认 GitHub 仓库 | | `logiclens/updates.py` | GitHub Releases 最新版检查 | | `logiclens/telemetry.py` | 可选的 Sentry 初始化 | | `templates/index.html` | 主 UI | | `templates/onboarding.html` | 首次运行向导 | | `templates/setup.html` | API 密钥表单 | | `packaging/logiclens.spec` | PyInstaller | | `packaging/installer.iss` | Inno Setup | ## API 参考 (节选) | 方法 | 路径 | 描述 | |--------|------|-------------| | GET | `/` | 主 UI | | GET | `/onboarding` | 首次运行向导 | | GET | `/setup` | API 密钥设置页 | | POST | `/setup` | 保存密钥 + 遥测标志 (JSON) | | GET | `/api/bootstrap` | 数据路径，`groq_configured`，`app_version` 等 | | GET | `/api/updates/check` | GitHub 最新发布元数据 | | POST | `/api/analyze` | 运行 `analyze_project` | | POST | `/api/pick_folder` | 原生文件夹对话框 (仅限 localhost) | | GET | `/api/graph` | 完整图 | | GET | `/api/search?q=` | 语义搜索 (当前项目) | | POST | `/api/whatif` | SSE what-if 报告 | ## 局限性 - 大型 **vendor** 目录树和被压缩过的 JS 文件会被跳过或设置上限 (`LOGICLENS_MAX_JS_BYTES`)。 - **`CALLS`** 边缘在**同一文件中定义的**被调用者中最强；跨文件解析是部分的。 - **增量**变更检测使用 **mtime + size**，而不是整个文件的哈希（极少数情况下会出现误判为“未更改”）。 - 跨文件重复的**函数名**可能会在某些 AI 工具中混淆基于名称的简单查找。 ## 安全性 - 切勿提交 `.env`。密钥仅保存在本地。 - 基于模式的“漏洞”提示是**启发式**的，并非完整的 SAST。 ## 许可证 本代码库中未捆绑许可证文件；如果您分发分支版本，请自行添加一个。

标签：AST解析, ChromaDB, CrewAI, DLL 劫持, Flask, Git上下文, IDE插件替代, IPv6支持, Python, pywebview, SQLite, Tailwind, Tree-sitter, vis-network, Waitress, Windows应用, 云安全监控, 人工智能, 代码分析, 代码可视化, 代码库管理, 代码搜索, 代码解释, 依赖关系图, 凭证管理, 前端技术, 后端开发, 向量数据库, 大语言模型, 威胁情报, 嵌入向量, 开发者工具, 影响分析, 数据管道, 无后门, 无线安全, 本地优先, 桌面应用, 用户模式Hook绕过, 语义搜索, 软件工程, 逆向分析, 逆向工具, 静态分析