projectmind

<p align="center"> <img src="docs/assets/logo.png" alt="ProjectMind" width="96" height="96"/> </p> <h1 align="center">ProjectMind</h1> <p align="center"><strong>您的项目，由 AI 解释。</strong></p> <p align="center">_{by Plaintext · MPL-2.0}</p> ProjectMind 使用 AI-ready 项目地图来解释软件架构、类、模块和关系，以一种人类和编码代理可以导航的方式。它是一个轻量级、**只读**的源代码架构浏览器，与 LLM 驱动的编码代理（如 Claude Code、ChatGPT / OpenAI Codex、Gemini CLI、Cursor 等）双向配对。 <p align="center"> <img src="docs/assets/demo-walkthrough.gif" alt="An AI agent authors a guided tour of a Spring codebase over MCP; ProjectMind renders every step live" width="820"/> </p> <p align="center">_{AI 代理实时创作此游览 <strong>通过 MCP</strong> — 步骤、行高亮和旁白被推送到查看器。没有人类点击任何内容。}</p> > **状态：** v0.8 — MCP 服务器 + 桌面应用，适用于 **macOS、Linux 和 Windows**，带有签名自动更新。Java + Rust 语言插件、Spring + Lombok 框架识别器、八种图表类型（bean graph、C4 container、folder heatmap、package tree、inheritance tree、doc graph、architecture layers、language stats）、Markdown + HTML 浏览器（sandboxed）、AI 引导游览，带有测验支持，以及 LLM、桌面应用和浏览器之间的双向 MCP 同步。 ## 快速开始 使用一行命令安装桌面应用 + MCP 服务器。脚本为您的 OS/arch 选择正确的预构建包，无需构建工具链。 **macOS / Linux：** ```sh curl -fsSL https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.sh | sh ``` **Windows (PowerShell)：** ```powershell iwr -useb https://raw.githubusercontent.com/Plaintext-Gmbh/projectmind/master/scripts/install.ps1 | iex ``` 桌面应用位于 `/Applications`（macOS）、`~/.local/share/projectmind`（Linux）或 `%LOCALAPPDATA%\Programs\ProjectMind`（Windows）。MCP 服务器二进制文件安装在您的 `PATH` 上，因此任何 LLM CLI 都可以启动它。 重新运行脚本将升级到最新版本。使用 `PM_VERSION=v1.2.3 …` 固定特定版本。跳过组件使用 `PM_NO_APP=1` 或 `PM_NO_MCP=1`（Bash）或 `$env:PM_NO_APP="1"`（PowerShell）。 当 bash 安装程序检测到 `PATH` 上支持的 LLM CLI（当前为 `claude` 和 `codex`）时，它会为您提供使用单个 `claude mcp add` / `codex mcp add` 调用注册 `projectmind-mcp` 的选项。使用 `PM_REGISTER=yes`（自动注册每个检测到的 CLI 而无需提示）或 `PM_REGISTER=no`（跳过提示并仅打印手动命令）覆盖。 ## 为什么 现代 AI 辅助开发与 CLI 代理非常出色，直到您想要 *查看* 刚刚更改的内容，*可视化* 架构如何演变，或 *深入* 了解结构而不启动重型 IDE。 `projectmind` 旨在成为缺失的部分： - **独立** 桌面应用（Mac 和 Linux）；不是 VS Code 扩展。 - **只读** — 无编辑，无构建。仅作为“架构镜头”。 - **MCP 双向** — 您的 LLM 可以说 *“显示类 X，突出显示行 42-58”*，查看器渲染它。您可以标记代码区域，选择权返回到对话中。 - **基于插件** — 语言（Java、Kotlin、TypeScript 等）、框架（Spring、Lombok、JSF 等）和可视化（bean graph、package tree、C4 等）都是插件。 ## GUI 标签 Tauri shell 有四个标签（每个标签在打开仓库之前都被禁用）： - **代码** — 模块边栏、类列表、带有立体型过滤器的源代码查看器、包钻取。 - **图表** — Mermaid bean graph 或 package tree；单击节点进行钻取。 - **MD** — 仓库中的每个 Markdown 文件，按顶级目录分组，带有渲染的预览、mermaid 块和嵌入图像。 - **HTML** — 每个 `.html` / `.xhtml` / `.htm` / `.jsp` / `.vm` / `.ftl` 文件，以及从 `.java` / `.kt` / `.groovy` / `.scala` 字符串字面量中提取的 HTML 片段（支持 Java 文本块）。切换渲染 ↔ 源代码；渲染使用严格的 sandbox iframe（无 JS，无网络），因此不受信任的仓库内容保持惰性。 ## 它是什么样子 一个 21 模块的 Spring Boot monorepo（543 个类），在 `open_repo` 后： | 文件夹热图 | C4 容器视图 | AI 引导游览 | |---|---|---| |  |  |  | 黑暗和浅色主题，五种 UI 语言，整个界面可调整大小。 ## 今天有效的内容 第一阶段 MVP 提供了 **Rust MCP 服务器**（`projectmind-mcp`），任何 MCP 感知客户端都可以连接，如 Claude Code、ChatGPT、Gemini CLI、Cursor 或您自己的自定义代理。它实现了： | 工具 | 它做什么 | |---|---| | `open_repo` | 打开一个仓库。检测 Maven 多模块布局（任何 `pom.xml`）和 Cargo 工作区（任何带有 `[package]` 的 `Cargo.toml`）；否则回退到单个模块。 | | `repo_info` | 活动仓库的摘要（模块、类）。 | | `module_summary` | 按模块的类计数和立体型直方图。 | | `list_classes` | 列出解析的类（按立体型过滤）。 | | `find_class` | 不区分大小写的简单或完全限定名称的子字符串搜索。 | | `class_outline` | 类的方法、字段、注解和可见性 — 无源代码。 | | `show_class` | 类的源代码，带有可选的行范围高亮。 | | `list_changes_since` | 自给定 git ref 以来的更改文件。 | | `show_diff` | 两个 refs（或 ref 与工作树）之间的统一 diff。 | | `show_diagram` | Mermaid bean graph（子图按 Maven 模块划分，按立体型颜色编码）或 package tree。 | | `list_html` | 仓库中列出 HTML / XHTML / JSP / Velocity / FreeMarker 模板文件。 | | `list_html_snippets` | 从源代码文件中扫描 HTML 片段（`.java`、`.kt`、`.groovy`、`.scala`，包括 Java 文本块）到字符串字面量中 — 过滤到 ≥2 个标签，以便 XML 命名空间声明和短错误字符串被丢弃。 | | `plugin_info` | 列出活动的语言和框架插件。 | | `start_gui` | 如果 ProjectMind 桌面应用未运行，则启动它（`view_*` 工具按需自动启动）。遵守 `$PROJECTMIND_APP` 以覆盖路径。 | | `open_browser_repo` | 启动在-process 浏览器主机，在令牌化的 URL 处提供 ProjectMind webapp。默认绑定到 `127.0.0.1`；传递 `lan: true` 以绑定到 `0.0.0.0`，以便从同一 WLAN 上的另一个设备（iPad / 手机 / 第二个笔记本电脑）访问 URL。URL 片段中的 bearer 令牌控制每个 API 调用。 | | `browser_status` | 返回正在运行的浏览器主机的绑定地址、令牌化 URL 和打开的仓库，或如果未启动主机，则返回 null。无副作用 — 方便地重新显示 URL/令牌而无需重启主机。 | | `stop_browser` | 忘记缓存的浏览器主机状态，以便下一次 `open_browser_repo` 启动新的。 | 浏览器主机是自然而然的答案：*“在我的 iPad 上打开这个仓库，同时在笔记本电脑上继续工作”*：请 LLM 调用 `open_browser_repo` 并带有 `lan: true`，响应携带一个 `http://<lan-ip>:<port>/#token=…` URL，您在第二个设备上打开。Tauri 桌面窗口和浏览器标签都订阅相同的共享状态文件，因此任何后续的 `view_*` / `walkthrough_*` 推从 LLM 镜像到任意打开的查看器。 第一阶段活跃的语言插件： - **Java** — Tree-sitter 解析器。类、接口、枚举、记录；方法、字段、注解、可见性。 - **Rust** — Tree-sitter 解析器。结构体、枚举、特质、联合体；`impl` 块附加方法和将 `impl Trait for T` 作为 `T` 上的注解。 第一阶段活跃的框架识别器： - **Spring** — `@Service`、`@RestController`、`@Controller`、`@Component`、`@Repository`、`@Configuration`。构造函数和字段注入（`@Autowired`、`@Inject`、`@Resource`）成为 Mermaid 边。 - **Lombok** — `@Data`、`@Value`、`@Builder`、`@SuperBuilder`、`@*ArgsConstructor`、`@ToString`、`@EqualsAndHashCode`、`@Slf4j`/`@Log*`、`@Getter`、`@Setter`、`@With`，… 附加为 `lombok` 立体型，并带有检测到的注解。 在真实代码库中进行烟雾测试：一个 21 模块的 Spring Boot Maven monorepo 解析为 **~500 个类**，带有立体型直方图和按模块分组的 Mermaid bean graph；一个 8-crate Cargo 工作区（此仓库）解析为 ~60 个类，每个 crate 有模块。 ## 从源代码构建 MCP 服务器（Ubuntu / Debian） 这是您想要的路径，以便 **从任何 MCP 感知代理（Claude Code、ChatGPT、Gemini CLI、…）在 Ubuntu 上使用 `projectmind`** — 无需 GUI。 仓库提供了一个安装程序，供 impatient 使用： ```bash git clone git@github.com:Plaintext-Gmbh/projectmind.git cd projectmind ./scripts/install-ubuntu.sh # 仅 MCP 服务器 # 或： ./scripts/install-ubuntu.sh --with-app # 还构建 Tauri shell ``` 脚本安装构建先决条件、Rust 工具链（如果缺少，则通过 rustup），然后构建并打印一个现成的 `.mcp.json` 片段。如果您想手动安装： ```bash sudo apt update sudo apt install -y build-essential pkg-config libssl-dev cmake git curl curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source "$HOME/.cargo/env" git clone git@github.com:Plaintext-Gmbh/projectmind.git cd projectmind cargo build --release --bin projectmind-mcp # 结果：target/release/projectmind-mcp ``` ## 从源代码构建 MCP 服务器（macOS） ```bash # 先决条件 — Homebrew + Rust brew install rustup-init || true rustup-init -y source "$HOME/.cargo/env" git clone git@github.com:Plaintext-Gmbh/projectmind.git cd projectmind cargo build --release --bin projectmind-mcp ``` ## 构建 Tauri shell（可选，GUI） Tauri 应用是只读图形浏览器。它是相同的引擎，只是顶部有 UI。 ### Ubuntu / Debian ```bash # Tauri 先决条件 sudo apt install -y \ libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev \ librsvg2-dev libsoup-3.0-dev libjavascriptcoregtk-4.1-dev patchelf # Node 工具链（用于前端） curl -fsSL https://get.pnpm.io/install.sh | sh - # 构建 cd app pnpm install pnpm tauri build ``` ### macOS ```bash # Node 工具链 brew install pnpm cd app pnpm install pnpm tauri build ``` 在开发模式下运行应用（实时加载）： ```bash cd app && pnpm tauri dev ``` ## 与 MCP 感知代理一起使用 ProjectMind 使用 **Model Context Protocol（MCP）**，因此任何支持 MCP 的前沿 LLM 客户端都可以驱动它：Claude Code、ChatGPT 桌面版、Gemini CLI、Cursor、Continue 或您自己的脚本代理。将服务器添加到客户端使用的配置中（例如 `.mcp.json` 用于 Claude Code，`mcp_settings.json` 用于 Cursor）： ```json { "mcpServers": { "projectmind": { "type": "stdio", "command": "/absolute/path/to/projectmind-mcp", "env": { "PROJECTMIND_LOG": "info" } } } } ``` ### `projectmind-mcp` 在磁盘上的位置？ 选择您已安装的任意一个： - **已安装桌面应用** — MCP 服务器与 GUI 二进制文件一起捆绑，因此您可以直接指向应用路径内的路径。 - **macOS:** `/Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp` - **Linux（`.deb` / `.AppImage`）：** `/usr/bin/projectmind-mcp`（`.deb` 安装到 `/usr/bin/`；`.AppImage` 挂载临时 FUSE 根 — 使用 `--appimage-extract` 提取 AppImage 如果您需要一个稳定的路径） - **Windows（`.msi`）：** `C:\Program Files\ProjectMind\projectmind-mcp.exe` - **仅 MCP 安装**（无桌面应用） — 使用 [Releases 页面](https://github.com/Plaintext-Gmbh/projectmind/releases/latest) 或 [`scripts/`](scripts/) 下的帮助脚本安装独立 tarball。 二进制文件位于您放置它的位置（通常 `~/.local/bin/projectmind-mcp`）。 - **从源代码** — `target/release/projectmind-mcp` 在 `cargo build --release --bin projectmind-mcp` 之后。 Claude Code 用户可以使用一行命令注册捆绑的二进制文件： ```bash # macOS claude mcp add projectmind /Applications/ProjectMind.app/Contents/MacOS/projectmind-mcp ``` 重新运行相同的命令在桌面应用升级后是 no-op，因此 MCP 服务器会自动与 GUI 版本保持同步。 重启客户端。从会话中，您可以询问类似： - *"打开 `/home/me/projects/my-spring-app` 仓库，并告诉我每个模块有多少服务和控制器。"* - *"查找任何包含 `Auszahl` 的类并概述最相关的类。"* - *"显示 `UserService` 类 — 突出显示行 80-95。"* - *"自 HEAD~5 以来哪些文件更改了？按模块分组。"* - *"渲染 bean graph 为 Mermaid 图。"* 代理将从上面的列表中选择合适的工具调用。 ### 预构建二进制文件 [Releases 页面](https://github.com/Plaintext-Gmbh/projectmind/releases/latest)上的最新版本提供 `projectmind-mcp` 和桌面应用包，其中 GitHub 运行程序可以构建它们。新的版本由 **Auto-Release** 工作流从 Actions 选项卡生成；它增加版本、打开 PR、合并、标记并发布一步到位。## 测试 / 开发 用于日常工作的 `./build` 帮助程序： ```bash ./build dev # 带有热重载的 Tauri 应用 ./build check # cargo fmt --check + cargo clippy ./build test # cargo test --workspace --all-targets + doctests ./build ci # check + test ./build mcp # release-build and smoke-test projectmind-mcp ./build app # 桌面应用包适用于此机器 ./build dist # 应用程序包 + tar.gz + sha256 包 ``` 底层 CI 包装器仍然可用，当您需要确切的工作流命令时： ```bash ./scripts/ci.sh check ./scripts/ci.sh test ./scripts/ci.sh all ``` CI 在 **Ubuntu 22.04** 和 **macOS 14** 上的每次推送和拉取请求运行 Linux 构建测试。 ## 架构 带有七个 crate 的 Cargo 工作区 + Svelte 前端： | Crate | 目的 | |---|---| | `crates/plugin-api` | 公共特性和类型（无实现） | | `crates/core` | 仓库加载器、文件遍历器、插件管道加载器、插件管道、Maven + Cargo 发现、git 助手 | | `crates/mcp-server` | `projectmind-mcp` 二进制文件（JSON-RPC via stdio） | | `plugins/lang-java` | 通过 Tree-sitter 的 Java 解析器 | | `plugins/lang-rust` | 通过 Tree-sitter 的 Rust 解析器 | | `plugins/framework-spring` | Spring 立体型 + bean graph | | `plugins/framework-lombok` | Lombok 注解识别器 | | `app/src-tauri` | Tauri shell（Rust 后端暴露 Tauri 命令） | | `app/src/` | Svelte + TypeScript 前端，带有 Mermaid 集成 | 第一阶段插件是 **静态注册** 的。第二阶段将添加从 `./plugins/` 目录动态加载到二进制文件旁边的 `.so` / `.dylib` 文件，因此第三方插件可以以 `.so` / `.dylib` 文件的形式放入其中。 ## 仓库中的参考文档 - [`docs/architecture.md`](docs/architecture.md) — 工作区布局、插件 API、MCP 工具模式。代码的实时参考，保持与代码同步。 - [`docs/SYNC.md`](docs/SYNC.md) — MCP 服务器和 Tauri GUI 如何保持同步（状态文件 + 视图意图）。 - [`docs/branding.md`](docs/branding.md) — 颜色、排版、标志规范。 - [`docs/reviews/`](docs/reviews/) — 历史架构评论。 ## 路线图和规划 路线图和功能积压现在位于 **GitHub**： - **[问题](https://github.com/Plaintext-Gmbh/projectmind/issues)** — 具体的、可安排的工作项（错误、功能、子任务、史诗） - **[项目看板](https://github.com/Plaintext-Gmbh/projectmind/projects)** — 正在进行的任务的 Kanban 视图 - **[讨论](https://github.com/Plaintext-Gmbh/projectmind/discussions)** — 愿景、更长形式的设计对话和可视化草图。 [愿景和路线图线程](https://github.com/Plaintext-Gmbh/projectmind/discussions/8) 是高层次方向的规范。 第一阶段总结： - **第一阶段（已完成）：** MCP 服务器，具有 Java + Spring + Lombok 插件、Rust 插件、包树、bean graph、文件夹映射、diff 视图、Markdown + HTML 浏览器、漫游模式、核心 MCP 工具、具有双向 MCP 同步的 Tauri shell。 - **第二阶段（进行中）：** 注解轮询、 ~~draw.io 嵌入~~ （`.drawio` 文件通过嵌入的 diagrams.net 查看器渲染）、Confluence MCP 桥、从 `./plugins/` 动态加载插件。 - **第三阶段：** 插件市场、更多语言、JSF / PrimeFaces 预览、C4 图形生成器。 ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。该项目处于早期设计阶段 — 欢迎讨论、想法和可视化草图。 ## 许可证 [MPL 2.0](LICENSE) — Mozilla 公共许可证 2.0 版。