一、项目定位与核心目标

EdgeQuake 是一个面向检索增强生成（RAG）场景的开源框架，核心特色在于将 知识图谱（Knowledge Graph） 与传统向量检索相结合，提供实体抽取、关系发现、上下文聚合与多租户隔离等能力。从最新发布的 v0.12.11 Docker Quickstart 可知，官方推荐使用 quickstart.sh 一键脚本或 docker-compose.quickstart.yml 完成部署，以降低使用门槛 v0.12.11 Release。

框架定位为 多组件、可扩展的 RAG 平台，围绕以下目标构建：

• 图谱化记忆：在文档之上构建实体（Entity）与关系（Relationship）图谱，让 LLM 拥有可遍历的长期记忆。
• 多租户与工作区：通过 Workspace 隔离不同业务方的知识库、LLM 与 Embedding 配置。
• 跨工具集成：通过 MCP（Model Context Protocol）Server 让 Claude、IDE 等外部 Agent 直接消费图谱。
• 可观测的前端体验：基于 Next.js 提供可视化图谱、文档管理、流式查询接口。

资料来源：README.md、edgequake_webui/README.md

二、系统架构与代码组织

EdgeQuake 仓库采用 Cargo Workspace + 多前端 SDK 的分层结构，主要子项目如下表所示。

仓库内嵌了 zz-reference/001-pgvector 与 zz-reference/002-apache-age 两份资料目录，分别记录向量库与图数据库的安装、类型与操作语义，说明底层存储采用 pgvector + Apache AGE 组合：向量存于 vector/halfvec 等类型，关系图存储于 agtype 图模型中 pgvector 002-fundamentals、apache-age 002-fundamentals。

资料来源：edgequake/crates/edgequake-core/src/types/multitenancy/requests.rs、edgequake_webui/README.md、mcp/package.json、sdks/typescript/package.json

flowchart LR
    User[用户 / Agent] -->|HTTP/SSE| WebUI[Next.js WebUI]
    User -->|MCP 协议| MCPServer[MCP Server]
    MCPServer -->|REST| Backend[Rust edgequake-core]
    WebUI -->|REST| Backend
    Backend -->|SQL + agtype| PG[(PostgreSQL<br/>pgvector + Apache AGE)]
    Backend -->|HTTP| LLM[LLM Provider<br/>OpenAI/Ollama/...]
    PDF[edgequake-pdf CLI] -->|Markdown| Backend

三、关键能力与典型流程

1. 工作区与自定义实体：创建工作区时可通过 CreateWorkspaceRequest 配置 LLM 模型、Embedding 模型以及实体类型。请求结构内置 entity_types: Option<Vec<String>>，并附带 entity_types_strict 控制是否将未知类型回退为 OTHER/CONCEPT，文档中提及的 SPEC-085 正是用于支持 UI 自定义实体 edgequake-core multitenancy/requests.rs。

2. 文档导入与进度跟踪：WebUI 通过统一的 IngestionProgress 模型向用户呈现分块、PDF 解析、嵌入等阶段，progress-formatter.ts 负责把秒数格式化为 1h 1m、30s、ETA: 90s 等可读字符串，保证长时间任务的可观测性 progress-formatter.ts。

3. 图谱可视化与社区检测：edgequake_webui/src/lib/graph/clustering.ts 使用 graphology-communities-louvain 对实体进行 Louvain 社区检测，并按社区着色，最多支持 20 种循环配色；孤立节点使用默认色，与 SPEC-0716/0717 对应 clustering.ts。

4. 会话导出：对话窗口提供 Markdown/JSON 两种导出格式，export-conversation.ts 会把消息内容、引用来源、时间戳一起写入文件，并在文件名中执行安全清洗 export-conversation.ts。

5. MCP 集成：MCP Server 通过 document_upload_file、graph_query 等工具，让 Claude/Cursor 等 Agent 直接调用 EdgeQuake，文件类型支持 .txt/.md/.pdf mcp/README.md。

6. PDF 转写：legacy/edgequake-pdf 提供 Rust 实现的 PDF→Markdown 转换器，覆盖字符定位、多列布局、表格识别、H1–H6 标题和代码块，并能通过 OPENAI_API_KEY 调用 gpt-4o-mini 进行图片 OCR legacy/edgequake-pdf/README.md。

四、社区关注与已知约束

围绕 EdgeQuake 的使用，社区形成了若干重点话题，本页简要列出与项目结构相关的几条：

• #85 自定义实体：希望在创建工作区时通过 UI 选择实体类型，而不是依赖后端代码常量。该能力在 CreateWorkspaceRequest::entity_types 中已经预留接口 edgequake-core multitenancy/requests.rs。
• #50 本体（Ontology）：希望在文档处理阶段引入可定义的本体与同义词典，提升实体一致性。
• #160 VectorChord 替代 pgvector：因 pgvector 单向量维度上限 2000，希望切换到 VectorChord 以支持更长向量。
• #55 Docker 构建失败：构建前端镜像时若缺失 next-env.d.ts 会失败，需在 Docker 上下文中补齐文件。
• #250/#251/#253/#255 版本与目录：models.toml 通过 include_str! 编译进二进制，无法在运行时覆盖；UI 版本号曾落后于 API；上传重复文档时确认替换会出现空操作提示；OpenAI 兼容提供方会在模型名前自动拼接 provider/，导致已含 / 的模型名重复加前缀。
• v0.12.4 → v0.12.11 发布节奏：Docker 快速启动脚本自 v0.12.4 起持续打磨，建议用户始终使用最新版镜像以获得稳定性改进 v0.12.11 Release。

资料来源：README.md、edgequake_webui/README.md、mcp/README.md、legacy/edgequake-pdf/README.md、zz-reference/001-pgvector/002-fundamentals/README.md

See Also

• 知识图谱与查询机制（Knowledge Graph & Query）
• MCP Server 集成（Model Context Protocol）
• WebUI 控制台使用指南（edgequake_webui）
• 工作区与多租户（Workspaces & Multitenancy）
• PDF 转写工具（edgequake-pdf）

概述

edgequake_webui/src/lib/ 是 EdgeQuake WebUI 中专门承载业务工具、图算法封装与数据转换逻辑的纯函数层。它位于 React 组件（app/、components/）与后端 API 客户端（api/）之间，负责把后端返回的原始实体、关系、消息流转换为前端可直接消费的结构（如 Markdown 文档、可视化节点、社区配色等）。该目录文件以 TypeScript 实现，遵循"无副作用、可独立测试"的设计原则（参见模块顶部的 JSDoc 中 @module / @implements / @enforces 标注）。 资料来源：edgequake_webui/README.md、edgequake_webui/src/lib/export-conversation.ts:1-15

核心子模块

对话导出工具 (`export-conversation.ts`)

export-conversation.ts 实现 FEAT0727（导出 Markdown）与 FEAT0728（导出 JSON），并通过 BR0724、BR0725 强制约束元数据完整性与文件名安全。其内部 formatMessageMarkdown 会按角色（user / assistant）渲染标题并附带时间戳；若消息携带 context.sources，会折叠成 `

Lib 模块

概述

edgequake_webui/src/lib/ 是 EdgeQuake WebUI 前端工程中的核心工具与领域逻辑库目录，承担了跨多个 React 组件复用的纯函数、类型定义、领域服务封装以及第三方 SDK 适配职责。它与 src/components/（UI 组件层）和 src/app/（Next.js 路由层）共同构成 WebUI 的三层架构：UI 组件层负责渲染，路由层负责页面装配，而 lib/ 层则沉淀了与具体框架无关、可独立测试的业务能力 资料来源：edgequake_webui/README.md

社区关注的两类典型需求——会话数据导出 与知识图谱可视化分析——其底层实现均位于此目录。具体而言：

• 会话导出 由 src/lib/export-conversation.ts 提供，对应需求 FEAT0727/FEAT0728（导出为 Markdown / JSON）资料来源：edgequake_webui/src/lib/export-conversation.ts
• 图谱社区检测 由 src/lib/graph/clustering.ts 提供，对应需求 FEAT0716/FEAT0717（Louvain 社区发现与节点着色）资料来源：edgequake_webui/src/lib/graph/clustering.ts

目录结构与职责划分

lib/ 目录采用领域子目录 + 顶层模块 的扁平化组织方式，便于在大型前端项目中保持良好的可发现性。基于现有源码文件可识别出以下子领域：

src/lib/
├── export-conversation.ts   # 会话导出（Markdown / JSON）
└── graph/
    └── clustering.ts        # 图谱社区检测与着色

表中列出的需求编号来源于各文件头部的 @implements 注解，是 WebUI 工程内部的可追溯性约定。

核心模块详解

会话导出（`export-conversation.ts`）

该模块提供将服务端消息结构序列化为 Markdown 与 JSON 的纯函数工具，目标是让用户能在 WebUI 内一键保存完整对话上下文。模块入口对消息格式做了清晰的角色识别：message.role === "user" 渲染为 You，否则渲染为 Assistant，并在每条消息前附带本地化时间戳 资料来源：edgequake_webui/src/lib/export-conversation.ts:18-30

导出 Markdown 时，若消息携带 context.sources（检索增强引用），会自动在消息体尾部追加一个 `

Src 模块

概述

Src 模块特指 EdgeQuake 项目的核心源码目录——edgequake/crates/edgequake-core/src/，它是整个 RAG（图增强检索）引擎的领域模型与业务逻辑中枢。该模块以 Rust 编写，向下封装了 LLM 提示工程、实体/关系归一化、关键词抽取等核心算法，向上通过 HTTP API 暴露给 WebUI、SDK、MCP Server 等前端组件使用。

模块的设计目标是把"知识图谱构建流水线"沉淀到领域层：把"分块 → 抽取 → 归一 → 入图 → 检索"这一完整链路建模为可被多种客户端复用的纯 Rust 类型与函数。社区反馈中常见的文档上传错误 (Issue #253)、自定义实体类型 (Issue #85)、增量重建 (Issue #252) 等诉求，都是围绕该模块暴露出的类型与流水线行为展开的。

flowchart LR
    UI[WebUI / SDK / MCP] --> API[HTTP API 层]
    API --> Core[edgequake-core/src]
    Core --> KW[keyword_extractor]
    Core --> Ent[types/entity]
    Core --> Rel[types/relationship]
    Core --> MT[types/multitenancy]
    KW --> LLM[(LLM Provider)]
    Ent --> Graph[(Graph Store)]
    Rel --> Graph
    MT --> Tenant[(Workspace/Tenant)]

核心子模块

关键词抽取（keyword_extractor）

keyword_extractor.rs 负责把用户查询拆解为高层关键词与底层关键词，供后续图谱检索的局部-全局混合召回使用。其核心是一个 LLM 提示模板：使用 few-shot 示例引导模型输出形如 {"high_level_keywords":[...], "low_level_keywords":[...]} 的 JSON 结构；模块对模型返回结果进行 JSON 抽取与容错解析，最终归一化为 ExtractedKeywords 类型 资料来源：edgequake/crates/edgequake-core/src/keyword_extractor.rs:1-120。

这种"high/low"双层关键词设计是 EdgeQuake 在查询阶段同时支持"语义向量检索"与"图遍历"的关键——high-level 关键词驱动概念级社区发现，low-level 关键词驱动实体级精确匹配。WebUI 中"图谱 + 来源 + 引用"的检索结果展示即是该模块的下游产物 资料来源：edgequake_webui/src/lib/export-conversation.ts:1-60。

类型系统（types）

类型系统是 Src 模块的"骨架"，由 entity.rs、relationship.rs 等文件共同构成：

• Entity：领域实体的不可变视图。Entity::new 会对 entity_name 调用 normalize_name 实现大小写无关的归一化；entity_type 在构造时被强制 to_uppercase；source_id 采用 "id1|id2" 的管道分隔格式承载多源追溯 资料来源：edgequake/crates/edgequake-core/src/types/entity.rs:1-90。
• Relationship：连接两个实体的边。Relationship::new 同时对 source_entity 与 target_entity 做 trim + to_uppercase 归一化，并通过 Self::generate_id 派生出稳定的边 ID；add_source 同样使用管道分隔追加，避免重复来源 资料来源：edgequake/crates/edgequake-core/src/types/relationship.rs:1-80。

归一化策略保证"Alice"与"alice"以及"ALICE"在图谱中指向同一个节点，从而显著降低 LLM 抽取结果中的实体碎片化问题。这一行为直接回应了社区中"重建图谱以派生新实体"（Issue #252）的诉求：归一化越早做，后续增量派生越简单。

多租户与工作区（multitenancy/requests）

types/multitenancy/requests.rs 定义了创建工作区所需的入参类型 CreateWorkspaceRequest。其中关键字段 entity_types: Option<Vec<String>> 允许调用方在创建工作区时自定义实体类型集合（如 General、Manufacturing、Healthcare、Legal、Research 等预设），这是社区中"允许在 UI 创建工作区时自定义实体配置"（Issue #85）功能的核心落点 资料来源：edgequake/crates/edgequake-core/src/types/multitenancy/requests.rs:1-80。

模块同时提供 entity_types_strict 字段控制是否将未知类型强制重映射为 OTHER/CONCEPT，以及 with_llm_model 这类链式构造器用于设置工作区级 LLM 模型（如 "gemma3:12b" 或 "ollama/gemma3:12b"）。这些设计呼应了 Issue #255 提出的"模型名已含斜杠时跳过自动前缀"需求——模型字符串由调用方显式提供，避免后端做多余改写。

与其他模块的协作

Src 模块不直接处理 HTTP 路由与渲染，而是作为"无状态领域核心"被各前端调用。mcp/README.md 中描述的 document_upload_file 等 MCP 工具，本质上把文件内容送入 Src 的抽取流水线；sdks/typescript/README.md 中列举的 client.documents、client.entities 等子模块则把 Src 的类型映射为 TypeScript 客户端 SDK 资料来源：mcp/README.md:1-80、资料来源：sdks/typescript/README.md:1-80。

edgequake_webui/src/lib/graph/clustering.ts 中的 Louvain 社区发现也消费 Src 导出的图数据：前端在拿到实体/关系后，使用 20 色调色板为社区着色，并将孤立节点 fallback 到默认色 资料来源：edgequake_webui/src/lib/graph/clustering.ts:1-80。

常见失败模式与注意要点

1. 模型名称被双重前缀：当 EDGEQUAKE_LLM_PROVIDER=openai 时若用户传入已含 / 的模型串（如 openai/gpt-4o），旧版本会再次拼接为 openai/openai/gpt-4o；在 Src 模块下游的 LLM provider 适配层应先做"含斜杠则跳过前缀"判断，参见 Issue #255。
2. 上传同名文档：上传已存在文档时 UI 会弹出"替换/取消"对话框；如选择替换但后端未真正写入，会触发 Issue #253 描述的 popup 异常——这是 Src 模块的"upsert"语义与前端 state 未同步导致。
3. 重建整图的开销：新增自定义实体后若触发整图重建（Issue #252），耗时与代价来自 entity.rs 中 add_source 对 source_id 字符串的重复扫描；批量派生场景下应考虑改为 HashSet<String> 存储。

参见

• 快速上手与 Docker 部署（README）
• WebUI 架构与组件
• TypeScript SDK 模块清单
• MCP Server 工具规范
• EdgeQuake PDF 转换器

Pitfall Log / 踩坑日志

项目：raphaelmansuy/edgequake

摘要：发现 14 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 依赖 Docker 环境。

1. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -d --name edgequake -p 8080:8080 -e DATABASE_URL="postgres://user:password@your-db-host:5432/edgequake" -e EDGEQUAKE_LLM_PROVIDER=openai -e OPENAI_API_KEY="sk-..." ghcr.io/raphaelmansuy/edgequake:latest # Verify curl http://localhost:8080/health
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -d --name edgequake -p 8080:8080 -e DATABASE_URL="postgres://user:password@your-db-host:5432/edgequake" -e EDGEQUAKE_LLM_PROVIDER=openai -e OPENAI_API_KEY="sk-..." ghcr.io/raphaelmansuy/edgequake:latest # Verify curl http://localhost:8080/health
• 证据：identity.distribution | https://github.com/raphaelmansuy/edgequake | docker run -d --name edgequake -p 8080:8080 -e DATABASE_URL="postgres://user:password@your-db-host:5432/edgequake" -e EDGEQUAKE_LLM_PROVIDER=openai -e OPENAI_API_KEY="sk-..." ghcr.io/raphaelmansuy/edgequake:latest # Verify curl http://localhost:8080/health

2. 安装坑 · 来源证据：Derive new entities without rebuilding entire graph and embeddings

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Derive new entities without rebuilding entire graph and embeddings
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/252 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：feat: Skip provider prefixing in model names if model already contains a slash '/'

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Skip provider prefixing in model names if model already contains a slash '/'
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/255 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：models.toml is not overridable at runtime

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：models.toml is not overridable at runtime
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/251 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：Database Foreign Key Error When Querying Multiple Workspaces Causes Slow Performance

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Database Foreign Key Error When Querying Multiple Workspaces Causes Slow Performance
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/259 | 来源类型 github_issue 暴露的待验证使用条件。

6. 配置坑 · 来源证据：UI Displays Incorrect Application Version Compared to API Version

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：UI Displays Incorrect Application Version Compared to API Version
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/250 | 来源类型 github_issue 暴露的待验证使用条件。

7. 配置坑 · 来源证据：Upload document error

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Upload document error
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/raphaelmansuy/edgequake/issues/253 | 来源类型 github_issue 暴露的待验证使用条件。

8. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/raphaelmansuy/edgequake | README/documentation is current enough for a first validation pass.

9. 运行坑 · 运行可能依赖外部服务

• 严重度：medium
• 证据强度：source_linked
• 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
• 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
• 证据：packet_text.keyword_scan | https://github.com/raphaelmansuy/edgequake | matched external service / cloud / webhook / database keyword

10. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/raphaelmansuy/edgequake | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/raphaelmansuy/edgequake | no_demo; severity=medium

12. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/raphaelmansuy/edgequake | no_demo; severity=medium

13. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/raphaelmansuy/edgequake | issue_or_pr_quality=unknown

14. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/raphaelmansuy/edgequake | release_recency=unknown