Bosheda/graphiquest

# GraphiQuest  *寻找关键节点 —— Hunter 呈现信号，Trace 跳入 Hivemind，GraphiQuest 点亮相连的代码路径。（示例 public-repo 关系图：[fastapi/fastapi](https://github.com/fastapi/fastapi) —— 而非 GraphiQuest 自身的源码。）* **GraphiQuest** 是一款针对代码库的**本地优先** 3D 知识图谱仪表盘。开源的 [Graphify](https://github.com/safishamsi/graphify) 扫描器（由 [safishamsi](https://github.com/safishamsi) 开发，MIT 协议） 负责映射代码库；GraphiQuest 将该映射转化为一个**Hivemind**，供你探索、使用 **Hunter** 审计，并从发现的问题 **Trace** 到确切的代码路径 —— 所有操作均在本地图谱上完成。无需云端，无需凭证；你的代码永远不会离开你的电脑。 ## 为什么选择 GraphiQuest - **将你的 repo 视为 3D Hivemind** —— 包括集群、热点、相连文件以及孤立区域 - **点击任意节点**，点亮其相连的路径 - **运行 Hunter** 以挖掘孤立候选者、缺失的链接和热点 - **使用 Trace** 从发现的问题直接跳转到对应节点 - **询问 Claude Code** 并提供聚焦的图谱上下文，而不是倾倒整个 repo —— 只读模式，且需经过你的批准 ## 快速开始（3 条命令） ``` uv tool install graphifyy # 1. the Graphify scanner (one time; or: pipx install graphifyy) graphify update . # 2. graph this repo -> graphify-out/graph.json python scripts/start_graphify_dashboard.py # 3. open the printed URL (http://127.0.0.1:8787/...) ``` ## 查看实际运行效果  *GraphiQuest 仪表盘 —— 一款基于 Graphify 构建的本地优先代码库映射图，集成了 Hivemind、Hunter、Trace、上下文节省以及 Claude Code 连接状态的单视图界面。* ## 大海捞针问题 GraphiQuest 专为 AI 辅助代码库中的**“大海捞针”**问题而构建。与其让模型盲目阅读所有内容，不如**先由 Graphify 映射 repo**。GraphiQuest 将该映射转化为你可以探索、查询和审计的 Hivemind；**Hunter** 会标记出断开连接的区域、孤立候选者、可能缺失的关系以及不完整的流程；当某些内容看起来可疑时，在要求 Claude Code 采取行动之前，**Trace** 会直接将你跳转到对应节点及其相连的路径。 ## 基于 Graphify 构建 GraphiQuest **基于 [Graphify](https://github.com/safishamsi/graphify) 构建**， 这是一款由 **Safi Shamsi ([safishamsi](https://github.com/safishamsi))** 开发的开源 repo 扫描器和知识图谱引擎，基于 **MIT License** 发布。 **Graphify 负责扫描代码库并生成图谱数据；GraphiQuest 负责对其进行可视化、查询、审计和导航** —— 包括 3D Hivemind、2D 浏览器、 Hunter、报告、Trace、token 节省证明、只读 MCP server 以及 UI。 - 引擎： · 包名：`graphifyy` (PyPI) · License：MIT - Graphify 作为**外部 CLI 依赖**使用 —— 其源码不包含在此处， 因此不需要随 GraphiQuest 附带 Graphify 的许可文本。扫描/图谱 引擎的全部荣誉归属于其作者。请参阅 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)。 ## Hunter 模式 Hunter 是“大海捞针”的发现层。 它首先基于**本地 Graphify 图谱**运行，然后呈现： - 孤立候选者 - 断开连接的群组 - 可能缺失的关系 - 热点（高影响范围的文件） - 过时或不完整的区域 - 在你要求 Claude 编辑任何内容之前值得检查的文件 报告是**可点击的**：打开一个发现结果，跳转回 Hivemind，并定位到相应的 节点或断开的路径。 设计上的诚实原则： - **本地图谱优先** —— 基于你的本地图谱构建；无需云端，无需上传。 - **保守措辞** —— 发现结果被表述为 *candidate / possible / inspect*；它们**本身并不能作为存在 bug 的证据**。 - **Claude Code 上下文丰富化是可选的，且需用户批准** —— 每次点击仅进行一次有界的只读调用，绝不自动执行。 ## 这是什么 - **GraphiQuest** —— 一个通过环回接口提供的、依赖轻量级的生成式 HTML 仪表盘（黑玻璃 / 黑曜石 UI）。 - **3D Hivemind** —— 将你的 repo 视为一个熔融的大脑：集群映射到大脑区域， 热点文件呈白热化燃烧，边缘是岩浆通道；包含摄像机滑动、调色板、 运动控制，以及选中时的路径照明。 - **2D Explorer** —— 结构图层视图 + 带有搜索、 节点检查器和工具抽屉的 2D 大脑概览。 - **Concepts** —— 实时过滤两个视图的清单。 - **Ask Console** —— 本地图谱问答（`how many nodes?`、`what is connected to this node?`、`find ` / `jump to ` …）。每次询问都会在本地 作为证据记录下来。 - **Project registry + bridge** —— 连接本地 repo 路径，通过仅限环回的 bridge 安全运行 Graphify，并在生成的项目 图谱之间切换。 - **Hunter + Reports** —— 一个图谱优先的项目审计器：孤立候选者、 断开连接的群组、可能的缺失链接（同一文件夹，无连接）、 热点和过时图谱信号 —— 仅限本地，措辞保守，具有可点击的跳转到节点的功能。 - **Claude Code** —— *唯一的受控连接器，配备真实的本地 MCP server* （`scripts/graphify_mcp_server.py`，仅使用标准库，只读模式）以及一个向导，可以一键注册它。在你批准之前，任何事物都不会连接 —— 它 **永远不会自行发起调用**。 ## 这不是什么 - 不是托管的 runtime —— 它绝不在其他应用程序内部进行托管。 - 不是云服务 —— 默认情况下，任何数据都不会离开你的电脑。 - 不是任意的命令执行器 —— bridge 仅允许一项 操作 pipeline。 - 不是 agent 执行系统 —— MCP server 是只读的，并且 在你配置之前，连接器将保持关闭状态。 - 不是通用的远程导入器 —— 针对*你的数据*的唯一网络流是 显式的“从 GitHub URL 导入”操作（它运行 `graphify clone`）。唯一的 其他网络用途是在首次渲染时从公共 CDN 加载视图库 + Google Fonts（请参阅下面的隐私说明）；完全离线的打包版本已在路线图中。 ## 当前状态（诚实说明） 正在运行：带有真实导航的仪表盘外壳（Knowledge Graph / Skills / How-To / Activity / Settings / Memory）、受追踪的项目注册表、Add Project、 带有 RUN GRAPHIFY 的环回 bridge、完整的 生成 → 读取模型 → 针对每个项目的 2D/3D 视图 pipeline、生成的图谱**切换**、过时检测 （通过生成器契约实现的 `rebuild_required`）、`views_missing`、沙盒化的 清理、相对 repo-path 解析、find/jump 命令（3D + 2D）、 证据/活动日志、带有顶部状态条实时进度的 GitHub-URL 导入、带有报告部分的 Hunter 图谱审计，以及用于 Claude Code 的本地 MCP server。仪表盘内的产品流程：一个 **Settings → Setup & Install** 分步指南（克隆 → 安装 Graphify CLI → 启动 → 第一个 repo，带有 复制按钮 + 实时 CLI 检测）、一个 **Skills** 管理表（16 行真实的 状态行）、**引导式 Claude Code 连接向导**（实时检查、一键 REGISTER FOR ME，绝不自动调用）、将当前 图谱**Unload/Reload**到真实的无图谱状态，以及 **Reports/Activity/Memory** 管理（清除/复制/导出，仅限 localStorage —— 绝不触及 repo 或 生成的视图）。**Graphify Context Savings** 证明了其价值：RUN SAVINGS CHECK 会估算完整结构上下文所需的 token，与聚焦的图谱 查询进行对比，并显示节省的百分比（这是一个诚实的 `chars/4` 估算值，显示在右侧 面板 + Settings + Skills 中；测量的 Claude-token 模式受门控限制）。该连接器是 一个**可用的流程**：一个带有实时安装/扫描器/注册 检测的 CONNECT 向导、一键 **REGISTER FOR ME**，以及一个真实的 **CHECK SELF-TEST**，它 通过 bridge 运行内置 MCP server 的 `--selftest` —— 绝不是虚假的 “已连接”。 局限性：一次只能进行一次图谱生成/导入；过时状态基于文件 （图谱 vs 视图 —— 不监视 repo 源码更改）；在你自行配置之前，连接器绝不向外调用（MCP server 位于 `scripts/graphify_mcp_server.py`）；URL 导入仅限 GitHub-https；视图在 首次渲染时会加载 CDN 库 + Google Fonts（完全离线打包版本已在 包装路线图中）。**Trace**（基于本地 边缘的最短路径 / trace / chain-end）已在询问控制台中构建并连接；`what-changed`（diff 感知 查询）仍在计划中。 ## 环境要求 | 要求 | 备注 | | --- | --- | | Python 3.10+ | 在 3.11/3.13 上开发/测试；仅使用标准库 —— 仪表盘本身无需 pip 安装 | | uv (或 pipx) | 仅用于安装 Graphify CLI | | Graphify CLI | `uv tool install graphifyy`（基于 0.8.36–0.8.37 开发）；必须作为 `graphify` 位于 PATH 中 | | 现代浏览器 | 基于 Chromium 开发；3D 视图需要 WebGL | | 环回端口 | bridge 默认为 `127.0.0.1:8787` | | Tk (tkinter) | *可选* —— 仅用于原生的“选择项目文件夹”选择器。随附于 python.org 的 Windows/macOS 构建版；在 Linux 上请安装 `python3-tk`。如果没有它，请使用 Add Project → 粘贴路径 / 导入 GitHub URL（选择器会如实降级）。 | ## 快速开始 ``` # 1. install the Graphify CLI (one time; uv -- or use: pipx install graphifyy) uv tool install graphifyy # 2. from the repo root: graph this repo once (creates graphify-out/graph.json) graphify update . # 3. start the dashboard -- it builds the read-model + all views itself if # missing, then serves them + the safe local bridge in the foreground python scripts/start_graphify_dashboard.py # add --port 8788 if 8787 is busy # 4. open the printed URL # http://127.0.0.1:8787/views/graphify-dashboard.html ``` 然后，在仪表盘中： 1. 点击 **+ Add a project**（顶部状态条） —— 原生文件浏览器打开（通过 bridge）：选择一个文件夹，它会自动生成图谱并加载。或者 取消进入弹窗以粘贴路径 / **从 GitHub URL 导入** （`graphify clone` → 生成图谱 → 加载；这是唯一使用 网络的流程）。之后所有操作均通过 Settings → Repositories 管理。 2. 点击 **RUN GRAPHIFY** —— bridge 运行白名单 pipeline，并且当 存在真实输出时，项目将变为 **ready**。 3. 点击项目卡片（或 **SELECT**） —— 仪表盘切换到该 项目自己的 3D/2D 图谱、计数和概念。 4. 提问：`how many nodes?` · `what concepts are visible?` · `jump to `。 ## 手动回退（无 bridge） 如果 bridge 没有运行，RUN GRAPHIFY 将变为 **PREPARE COMMAND** 并显示 确切的手动命令： ``` cd "" graphify update . ``` 页面会如实追踪 `waiting for manual run` 状态 —— 如果没有 bridge， 它就无法检查你的文件系统，因此它绝不会谎称图谱已存在。启动 bridge 以进行经过验证的运行和自动视图生成。 ## 项目注册表 - 追踪基准：[`graphify.projects.json`](graphify.projects.json) （包含 id、标签、repo 路径、真实状态；计数**从不存储** —— 它们 来自生成/扫描时的实际输出）。 - 浏览器覆盖层：repo-path 编辑和添加的项目会持久化保存在 `localStorage` 中，并被标记为*“在此浏览器中本地保存”*，直到 CLI 配置编写器上线。 - 状态含义：`ready`（视图存在并已加载）· `repo_path_configured` · `generated — views not built yet` · `rebuild_required`（图谱或生成器 契约比视图更新）· `views_missing` · `generated — incompatible output`（显示确切原因）· `graph_missing` · `no repo path`。 ## 生成的输出（从不提交） ``` graphify-out/ # gitignored views/ # default dashboard views (the graph of whatever repo the dashboard runs from; gitignored — nothing pre-baked ships) projects// # per-project generated views manifest.json # truth: paths, counts, versions, contract read-model.json brain-3d-prototype.html # 3D Hivemind graph-explorer.html # 2D explorer ``` `/graphify-out/graph.json`（+ `GRAPH_REPORT.md`）是 Graphify 自己在 被扫描 repo 内部的输出。所有生成的内容都是一次性的 —— **Settings → Maintenance** 可以安全地清理每个项目的视图。 ## 安全模型 - **仅限环回** —— bridge 绑定 `127.0.0.1`，并在每次请求时额外验证 客户端地址。没有 LAN，没有远程。 - **跨站请求防御** —— 状态更改 还需要同源 `Origin`/`Sec-Fetch-Site`（浏览器发出的跨源请求将被拒绝），因此即使本地 bridge 在运行时，你访问的网页也无法驱动它。非浏览器客户端（如测试、MCP selftest）不发送 `Origin` 且不受影响。 - **仅限白名单 pipeline** —— 浏览器将 `{projectId, repoPath}` 作为 数据发送；bridge 运行固定的 argv（在验证过的 目录中运行 `graphify update .`，然后运行本 repo 自己的视图生成器）。这里**没有命令文本通道**；注入字符串只是无效的路径。 - **路径验证** —— 需要绝对/现有目录；驱动器根目录、 系统目录和裸主目录将被拒绝。 - **一次只能进行一次重建**（HTTP 409），600s 看门狗，**基于证明的成功** （必须存在真实的 `graph.json` 且视图 pipeline 必须完成 —— 仅有 exit 0 绝不代表成功；未更改的图谱会被如实视为最新）。 - **沙盒化清理** —— 仅删除 `graphify-out/projects/` （受 realpath 保护）；源 repo 和设计资产在结构上是无法触及的。 - **默认无凭证，无外部调用** —— 两个诚实的例外： 视图库/字体在首次渲染时从公共 CDN 加载，以及显式的 “从 GitHub URL 导入”操作通过网络克隆（严格限于 `https://github.com//` —— 作为数据验证，固定的 argv）。 - **首次渲染第三方说明（隐私）：**在首次加载时，视图会从 jsDelivr/esm.sh 和 Google Fonts 获取 JS， 这会将你的 IP 和 referer 泄露给这些主机。没有其他任何东西 离开你的电脑。完全离线的本地打包版本（零第三方 请求）已在路线图中 —— 在对敏感代码进行完全私有 使用之前需要此版本。 ## 故障排除 / 视觉 QA - **光泽/普通球体而不是熔融核心** = 纹理图集未加载。视图会在控制台记录一条 **warning**（`atlas missing — default cores kept`）；这里的警告很重要 —— 请检查浏览器控制台和资产路径。 - **空白图谱** —— 无读取模型：在 repo 中运行 `graphify update .`，然后 重新生成视图（或通过 bridge 运行 RUN GRAPHIFY）。 - **`rebuild_required`** —— 图谱或生成器契约比 视图更新；点击 REBUILD。 - **僵尸进程** —— `python scripts/cleanup_graphify_processes.py` （添加 `--kill-stale` 以移除挂起/被取代的 Graphify 重建；它绝不会 触及其他的 python 进程）。Hook 清理： `python scripts/install_graphify_hooks_safe.py`（幂等）。 - **端口已被占用** —— bridge 会打印清晰的消息；使用 `python scripts/start_graphify_dashboard.py --port 8788` 重新运行。 - **停止仪表盘** —— 在运行启动脚本的终端中按 Ctrl+C。 ## 将其与 Claude Code 结合使用（唯一的连接器） **你打开了 Claude Code 并拥有了此 repo 链接 —— 接下来怎么做？**将其粘贴到 Claude Code 中，它会完成整个设置（仪表盘的 How-To §2 中附带了相同的提示，并带有 COPY 按钮）： ``` Set up the Graphify Dashboard from https://github.com/Bosheda/graphiquest : 1. Clone it (or cd into my existing clone). 2. Install the Graphify scanner CLI (open source by safishamsi - github.com/safishamsi/graphify): uv tool install graphifyy 3. Graph the repo: run "graphify update ." in the repo root. 4. Start the dashboard with "python scripts/start_graphify_dashboard.py", leave it running, and tell me the local URL it prints. 5. Register the dashboard's MCP server with yourself using ABSOLUTE paths: claude mcp add -s user graphify -- "" "/scripts/graphify_mcp_server.py" --repo "" 6. Run "claude mcp list", confirm graphify shows a health check, then use the graphify tools to summarize my graph. ``` **各部分如何协同工作（简单版）：**Graphify 扫描器（由 [safishamsi](https://github.com/safishamsi/graphify) 开发，MIT 协议 —— 全部荣誉归于该作者）构建 图谱 · 此仪表盘展示它（3D Hivemind、Hunter、Reports、token 节省） · Claude Code 通过这里附带的微小**只读**本地 MCP server 进行思考 （`scripts/graphify_mcp_server.py`；5 个工具： `graph_summary` · `find_node` · `node_neighbors` · `list_concepts` · `run_hunter`）。 仪表盘从不调用 Claude Code；Claude Code 从不更改仪表盘 —— 你就是连接的桥梁。 **连接向导**（左侧边栏中的 CLAUDE CODE 胶囊按钮，或 Settings/Skills 中的 CONNECT）引导你完成四个经过实时检查的步骤：**(1)** Claude Code 是否已安装？（如果没有，请复制安装命令） · **(2)** Graphify 扫描器 是否已安装？（实时版本检测 + 致谢链接 + 复制安装命令） · **(3)** 连接 —— **REGISTER FOR ME** 通过本地 bridge 运行 Claude Code 自己的注册命令，带有**固定的 argv** 且零客户端输入 （`POST /api/claudecode/register`；bridge 本身从不写入 `~/.claude.json` —— 而是由 claude CLI 完成），或者复制相同的命令并在 PowerShell/CMD 中运行（不要在 Git Bash 中运行，它会破坏路径） · **(4)** 使用 `claude mcp list`（实时健康检查）或 Claude Code 内部的 `/mcp` 检查是否成功。 诚实原则：本地 MCP server **没有浏览器登录**（没有任何事物 可以默默地“授权” Claude）；注册状态通过**读取** `~/.claude.json` 来检测；最强烈的声明是*已注册，已由你验证* —— **绝不会声明“已连接”**。文档示例使用 `C:\Users\%USERNAME%\…` 样式的占位符；向导总是会在**你的**机器上检测真实的 路径。事实已于 2026-06-11 在 Claude Code v2.1.174 + code.claude.com/docs/en/mcp 上进行了实时验证。 **仪表盘本身绝不会发生连接器调用**；页面内的通道 保持关闭状态并如实回答：*“已关闭 —— 未进行任何调用。”*该服务器 不进行任何网络调用，也从不进行任何写入操作。 ## License（本项目） **MIT License** —— 请参阅 repo 根目录下的 [`LICENSE`](LICENSE)（Copyright (c) 2026 DaForgeLayer-AI contributors）。此仪表盘自身的代码及其提交的设计 资产均为 MIT 协议。下面的依赖许可声明是相互独立的并已经过验证。 ## 依赖鸣谢与许可 于 2026-06-11 针对上游源码进行了验证（许可审计；在公开发布前 需要进行最终检查）： | 依赖 | 用途 | 许可 | 交付方式 | | --- | --- | --- | --- | | [3d-force-graph](https://github.com/vasturiano/3d-force-graph) (v1.80.0) 由 Vasco Asturiano 开发 | 3D 图谱渲染 | MIT（已验证） | CDN (jsDelivr)，已锁定版本 | | [three.js](https://github.com/mrdoob/three.js) 包含示例 `UnrealBloomPass` | WebGL + bloom | MIT（已验证） | CDN (jsDelivr / esm.sh)，已锁定版本 | | [Graphify](https://github.com/safishamsi/graphify) (`graphifyy`) | repo 扫描 / 图谱构建 | MIT（已验证） | 外部 CLI 工具 | | 字体：Orbitron, Inter, JetBrains Mono, Saira | UI 排版 | SIL OFL 1.1（已验证） | Google Fonts CSS API | | jsDelivr / esm.sh | 分发 | 免费公共 CDN（特别鸣谢） | — | | 2D explorer | 2D 渲染 | 此 repo —— 自包含 canvas，**零外部库** | 内联 | | Claude Code MCP 文档 | 仅用于连接器文档 | 被引用，未打包 | — | 公开发布前仍需完成：重新实时验证 OFL/Google-Fonts FAQ 解释，并包含 MIT/OFL 许可文本（如果将来有任何库或字体 在本地打包 —— 目前通过 CDN 加载不会产生通知义务）。 ## 路线图 - 独立的 **graphiquest** repo 拆分（目前随附在 DaForgeLayer-AI monorepo 内部） - 打包安装程序 + 完全离线的本地打包版本（包含许可文本） - Repo 导入加固（目前支持 GitHub-https 克隆；其他主机/认证是未来的目标） - 图谱命令：`what-changed` diff 感知查询（Trace —— 最短路径 / trace / chain-end —— 和孤立/断开连接检测已经构建完毕） - 连接器 bridge 执行（已显式关闭并需批准） - 公开发布资产：截图 / GIF / 视频，最终的 README 优化

标签：3D仪表盘, AI辅助编程, 云安全监控, 代码可视化, 代码审查, 数据可视化, 调试辅助, 逆向工具, 静态分析