内容
# 系统查询流程（SysQlow-MCP）
[](https://modelcontextprotocol.io/)
[](https://bun.sh/)
[](https://turso.tech/)
[](https://www.docker.com/)
[](#)
[](https://github.com/barayuda/sysqlow-mcp/actions/workflows/coverage.yml)
**系统查询流程（SysQlow）** 是一个智能、自验证的本地优先工程知识库MCP服务器。它具有微秒级的Turso嵌入式副本同步、自动代码库栈和约定学习，以及一个Gemini驱动的Sentinel验证引擎，用于实时审核代码片段与实时网络文档。
> 🚀 **第一次来这里？从[快速入门指南](docs/getting-started.md)**开始 — 涵盖先决条件、5分钟快速启动、MCP客户端设置（Cursor / Claude Desktop / Antigravity）和第一个代码片段演练。
> 📚 **理论基础：** SysQlow-MCP是一个有原则的 **个人知识图谱（PKG）** 实现，具有内置的 **知识图谱精炼** 环路（Paulheim 2017）和上下文分层子图（Serafini & Homola 2012）。参见 [**LITERATURES.md**](LITERATURES.md) 了解完整的学术基础 — Balog & Kenter的PKG议程、Paulheim的精炼分类法、W3C PROV-O溯源、Vannevar Bush的Memex、Luhmann的Zettelkasten，以及现代时间/上下文知识图谱文献，这些文献为该代码库的每个设计决策提供了参考。
> 🧭 **一致性：** 存储为 `项目上下文` 的代码片段被限制在存储它们的 工作空间 中；通用技术代码片段在所有项目中共享。服务器在每次启动时都会自我审核。→ **[使用指南](docs/coherence-usage.md)** 适用于日常工作流程。
---
## 🛠️ 架构栈与功能
- **项目元数据扫描：** 直接的本地文件系统扫描可以检测到核心技术栈、特定框架版本和项目架构签名配置文件（例如，`package.json`、`composer.json`、`Cargo.toml`等）。
- **本地优先嵌入式副本（Turso）：** 在本地Mac上使用本地SQLite副本（`data/sysqlow.db`）实现微秒级读取延迟，自动将数据库写入和模式创建推送到 **Turso Cloud** 主数据库。对于短暂磁盘主机（Render免费、Fly无卷），通过`SYSQLOW_DB_REMOTE_ONLY=1`选择直接连接到Turso模式 — 参见 [`docs/deploying-to-render.md`](docs/deploying-to-render.md)。
- **强大的通配符搜索索引：** 配备双通道搜索引擎。如果客户端LLM请求广泛扫描（`*`），引擎会优雅地拦截查询以列出所有项目；特定关键词查询使用集成的 **FTS5（全文搜索）** 虚拟索引或回退到SQL `LIKE`模式。
- **“Sentinel”验证引擎：** 连接到 **Google Gemini API** （或OpenAI）以验证技术笔记的准确性，验证内容来自Brave Search或无密钥DuckDuckGo获取的现代文档。
- **后向JSON修复引擎：** 一个自定义构建的、基于正则表达式的解析器（`/(?<!\\)\\(?!["\\/bfnrtu])/g`）自动清理LLM JSON响应中的双反斜杠（例如PHP命名空间`Illuminate\Support`），保证强大的序列化。
```mermaid
graph TD
A[代理客户端 / VS Code / Cursor] <-->|stdio / JSON-RPC| B[FastMCP 服务器]
B <-->|recall / store / learn| C[(本地SQLite副本 - data/sysqlow.db)]
C <-->|双向同步| D[(Turso 云数据库)]
B <-->|learn_codebase| H[本地工作空间配置和README]
B <-->|validate_knowledge| E[Sentinel 引擎]
E -->|1. 网络搜索| F[Brave/DuckDuckGo API]
E -->|2. 推理| G[Gemini/OpenAI API]
G -->|3. 结构化报告| E
B <-->|commit_update| C
```
---
## 🔌 MCP 工具规范与使用指南
SysQlow-MCP 暴露了 11 个高度优化、Zod验证的工具。
---
### 1. `learn_codebase`
扫描当前项目目录，自动检测技术栈和核心依赖版本，总结整体架构指南，并将它们存储在知识库中作为项目上下文。
* **参数：**
* `projectPath`（字符串，可选）：项目根目录的绝对路径。如果省略，则默认为服务器的当前工作目录。
* **如何使用：**
向IDE助手提问：
> *"使用 `learn_codebase` 工具分析我的当前项目栈。"*
* **返回值：**
```markdown
## 🧠 成功学习项目： "my-laravel-app"
从以下文件中发现和分析了关键元数据： package.json, composer.json, README.md
在数据库中存储了 **3** 个项目特定的上下文代码片段。
---
### [1] 主题： my-laravel-app: 技术栈与依赖
类别： 项目上下文
内容： 发现了使用Bun运行时进行前端编译的Laravel 11.x框架...
```
---
### 2. `store_knowledge`
将新的技术代码片段、代码块、配置或命令直接持久化到数据库中。
* **参数：**
* `topic`（字符串，必填）：知识主题（例如，“Laravel 11速率限制”）。
* `content`（字符串，必填）：实际的技术代码片段、配置或终端命令。
* `category`（字符串，可选）：文件夹/类别名称（例如，“后端”，“前端”，“DevOps”）。
* **如何使用：**
向IDE助手提问：
> *"将关于Laravel 11速率限制的技术代码片段存储在'后端'类别下。使用RateLimiter::for() inside bootstrap/app.php..."*
* **返回值：**
```json
{
"status": "success",
"message": "技术代码片段存储成功。",
"id": "7f9b1c90-2da8-4e12-b0c8-472251a3fb80",
"topic": "Laravel 11 速率限制",
"category": "后端"
}
```
---
### 3. `recall_knowledge`
搜索知识库以检索技术代码片段，使用关键词匹配或广泛的列表查询。
* **参数：**
* `query`（字符串，必填）：搜索术语。传递 `"*"` 或留空以检索所有存储的记录。
* `category`（字符串，可选）：按类别筛选结果。
* **如何使用：**
向IDE助手提问：
> *"从数据库中回忆所有Laravel代码片段"* （发送 `"query": "*"`)
> *"在我的知识库中搜索 'rate limit'"* （发送 `"query": "rate limit"`)
* **返回值：**
```markdown
--- 结果 [1] ---
ID: 7f9b1c90-2da8-4e12-b0c8-472251a3fb80
主题： Laravel 11 速率限制
类别： 后端
验证： 是
置信度评分： 10/10
来源网址： https://laravel.com/docs/11.x/rate-limiting
内容：
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;
...
```
---
### 4. `validate_knowledge`
触发 **Sentinel验证引擎** 以审核存储的代码片段的准确性。它搜索实时文档并将其与保存的代码进行比较，返回验证状态、详细原因和建议的代码差异。**它是只读的，永远不会自动写入数据库以确保安全。**
* **参数：**
* `id`（字符串，必填）：要验证的代码片段的UUID。
* **如何使用：**
向IDE助手提问：
> *"审核ID为 '7f9b1c90-2da8-4e12-b0c8-472251a3fb80' 的代码片段的最新网络文档。"*
* **返回值：**
```json
{
"id": "7f9b1c90-2da8-4e12-b0c8-472251a3fb80",
"status": "needs_update",
"confidence_score": 5,
"source_url": "https://laravel.com/docs/11.x/rate-limiting",
"reasoning": "存储的代码片段使用Laravel 9的RouteServiceProvider配置速率限制。在Laravel 11中，RouteServiceProvider已被删除，速率限制必须在bootstrap/app.php中定义。",
"suggested_diff": "--- old_snippet\n+++ new_snippet\n..."
}
```
---
### 5. `commit_update`
保存对存储的代码片段的批准更新。这是 **人机协作** 的完成步骤。一旦您审查并批准来自 `validate_knowledge` 的建议差异，此工具将坚持并将代码片段标记为已验证。
* **参数：**
* `id`（字符串，必填）：要更新的代码片段的UUID。
* `content`（字符串，必填）：新的、精炼的代码片段内容。
* `revalidateBeforeCommit`（布尔值，可选）：默认为 `true`。在写入更新之前再次运行验证。
* **如何使用：**
向IDE助手提问：
> *"验证报告看起来是正确的。提交代码片段 '7f9b1c90-2da8-4e12-b0c8-472251a3fb80' 的建议差异。"*
* **返回值：**
```json
{
"status": "success",
"message": "代码片段 'Laravel 11 速率限制' 已成功更新并标记为已验证。",
"id": "7f9b1c90-2da8-4e12-b0c8-472251a3fb80"
}
```
---
### 6. `knowledge_workflow`
用于意图优先提示的高级编排工具。它帮助客户端自动路由请求，而无需始终提及特定的工具名称。
* **参数：**
* `intent`（枚举，必填）：`learn` | `save` | `search` | `validate` | `apply` | `delete` | `merge` | `semantic` | `import`
* `projectPath`（字符串，可选）：由 `learn` 使用
* `topic`、`content`、`category`（可选字段）：由 `save` 使用
* `query`、`category`（可选字段）：由 `search` 或 `semantic` 使用
* `id`（字符串，可选）：由 `validate`、`apply` 或 `delete` 使用
* `content`（字符串，可选）：由 `apply` 使用
* `revalidateBeforeCommit`（布尔值，可选）：由 `apply` 使用（默认为 `true`）
* `parentId`、`childId`、`mode`（可选字段）：由 `merge` 使用
* `url`（字符串，可选）：由 `import` 使用
* **如何使用：**
向IDE助手提问，意图语言：
> *"分析此工作空间并存储项目上下文。"*
> *"将此代码片段保存到后端。"*
> *"在我的知识库中搜索速率限制。"*
> *"在后端类别中搜索我的缓存选项。"*
> *"从 https://example.com/docs... 抓取和导入文档..."*
> *"链接代码片段 child-id 作为父主题下的子主题..."*
---
### 7. `semantic_search`
对存储的知识代码片段执行概念性、高保真度的向量相似性搜索，使用余弦相似性计算。
* **参数：**
* `query`（字符串，必填）：查询术语或概念（例如，“缓存数据库”）。
* `category`（字符串，可选）：可选类别筛选。
* `limit`（数字，可选）：返回的最大匹配数（默认为5）。
* **优雅降级：** 如果Gemini嵌入式API限制耗尽，该工具会优雅地降级为FTS5关键词索引或标准SQL `LIKE`查找。
---
### 8. `import_documentation`
抓取外部HTML文档，将清理的文本流转换为结构化的Markdown代码片段，并使用Gemini将其保存到数据库中。
* **参数：**
* `url`（字符串，必填）：要抓取和导入的技术文档的URL。
* `category`（字符串，可选）：存储代码片段的类别（默认为“后端”）。
---
## ✍️ 提示别名和现成提示包
使用意图样式提示，以便您的助手可以自动触发SysQlow，即使您没有提及服务器名称。
### 提示别名（推荐动词）
- **分析** = `learn_codebase` / `knowledge_workflow(intent=learn)`
- **保存** = `store_knowledge` / `knowledge_workflow(intent=save)`
- **搜索 / 查找** = `recall_knowledge` / `knowledge_workflow(intent=search)`
- **审核 / 验证** = `validate_knowledge` / `knowledge_workflow(intent=validate)`
- **应用** = `commit_update` / `knowledge_workflow(intent=apply)`
### 复制粘贴提示包
1. 分析当前工作空间并保存项目上下文以供后续回答。
2. 保存此技术笔记。主题：<主题>。类别：<类别>。内容：<内容>。
3. 在类别<类别>中找到我存储的关于<关键词>的笔记。
4. 审核ID<id>的代码片段以检查当前官方文档。
5. 将此批准的更新应用于ID<id>的代码片段，内容为：<内容>。
### 类别规范
为了更好地保持召回一致性，类别被规范化为规范名称：
- 后端
- 前端
- DevOps
- 项目上下文
- 数据库
- 测试
- 工具
### 安全更新规范
`commit_update` 现在默认为 `revalidateBeforeCommit=true`，因此在最终写入之前会再次验证更新。
---
## ⚙️ 设置与配置
### 先决条件
- 在您的机器上安装 [Bun](https://bun.sh/) （v1.2+）。
- 一个 **Turso** 数据库和身份验证令牌。
- 一个 **Google Gemini** API密钥，以启用Sentinel验证。
### 1. 环境配置
在项目根目录下创建一个 `.env` 文件：
```ini
TURSO_DATABASE_URL="libsql://your-db-url.turso.io"
TURSO_AUTH_TOKEN="your-turso-jwt-token"
GEMINI_API_KEY="AIzaSy..." # 启用验证推理
BRAVE_API_KEY="your-brave-key" # 可选（默认为DDG抓取器）
```
---
## ⚡ 原生运行（无需Docker）
在主机上原生运行服务器可以实现毫秒级握手速度和 **无限制的工作空间文件系统访问**，无需配置即可访问机器上的任何文件夹。
### 选项1：实时标准输入/输出开发模式
适用于本地测试。MCP客户端（例如Cursor、Claude Desktop）使用标准输入/输出模式启动服务器：
1. 安装依赖：
```bash
bun install
```
2. 配置MCP客户端（例如Claude Desktop配置 `claude_desktop_config.json`）以直接调用`bun`：
```json
{
"mcpServers": {
"sysqlow-mcp": {
"command": "bun",
"args": ["run", "/Users/barayuda/Projects/personal/sysqlow-mcp/src/index.ts"],
"env": {
"TURSO_DATABASE_URL": "libsql://your-db-url.turso.io",
"TURSO_AUTH_TOKEN": "your-turso-jwt-token",
"GEMINI_API_KEY": "your-gemini-key",
"BRAVE_API_KEY": "your-brave-key"
}
}
}
}
```
### 选项2：编译的独立原生二进制文件（标准输入/输出）
为了实现最大速度和可移植的、无依赖项执行：
1. 将服务器编译为原生二进制文件：
```bash
bun run compile
```
*此操作会在 `dist/sysqlow-mcp` 中输出一个单独的独立可执行文件（约50MB），其中包含模式、编译器、运行时和服务器。您甚至不需要在机器上安装Bun或Node即可运行此二进制文件。*
2. 将您的MCP客户端指向编译后的二进制文件：
```json
{
"mcpServers": {
"sysqlow-mcp": {
"command": "/Users/barayuda/Projects/personal/sysqlow-mcp/dist/sysqlow-mcp",
"env": {
"TURSO_DATABASE_URL": "libsql://your-db-url.turso.io",
"TURSO_AUTH_TOKEN": "your-turso-jwt-token",
"GEMINI_API_KEY": "your-gemini-key"
}
}
}
}
```
### 选项3：SSE模式与Web仪表盘（HTTP/SSE）
在后台原生运行服务器以访问 **交互式Web图谱仪表盘**，端口为 `50741`，无需Docker：
1. 使用`MCP_TRANSPORT`设置为`sse`启动服务器：
```bash
MCP_TRANSPORT=sse PORT=50741 bun start
```
2. 打开浏览器并访问： **`http://localhost:50741/`** 以查看实时仪表盘。
3. 配置IDE客户端直接连接到正在运行的SSE URL端点：
```json
"sysqlow-mcp": {
"type": "sse",
"url": "http://localhost:50741/sse"
}
```
使用Antigravity IDE：
```json
{
"mcpServers": {
"sysqlow-mcp": {
"$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:50741/sse"
],
"env": {
"TURSO_DATABASE_URL": "libsql://your-db-url.turso.io",
"TURSO_AUTH_TOKEN": "your-turso-jwt-token",
"GEMINI_API_KEY": "your-gemini-key",
"BRAVE_API_KEY": "your-brave-key"
}
},
}
}
```
---
## 🐳 使用Docker运行（SSE和仪表盘设置）
我们提供了一个自动化管道，在SSE传输模式下运行服务器，暴露端口 **`50741`** 以服务MCP客户端连接和Web管理仪表盘。
---
### 一键运行：
只需执行附带的bash脚本，即可清理、重建并以分离模式启动容器：
```bash
./run-docker.sh --sse
```
这会将本地机器上的 **`50741`** 端口绑定到容器上，将数据库副本文件安全地定向到挂载的 `data/` 目录。
> **☁️ 部署到远程主机（Render、Fly、Railway）？**
> 请参阅 [`docs/deploying-to-render.md`](docs/deploying-to-render.md) 以获取仅限远程的数据库模式（`SYSQLOW_DB_REMOTE_ONLY=1`），该模式跳过了本地 SQLite 缓存 — 这是具有短暂磁盘的主机所必需的。存储库还附带了一个 `render.yaml` 蓝图，用于一键式 Render 部署。
> [!IMPORTANT]
> **🔒 Docker 挂载范围 — 默认安全：**
> `run-docker.sh` 不再将 `$HOME` 挂载到容器中。默认情况下，它只暴露两个路径：
> 1. **SysQlow-MCP 代码库本身** — 以便二进制文件和资产可用。
> 2. **调用的当前工作目录** (`$PWD`，当您运行 `run-docker.sh` 时) — 以便一致性引擎可以检测您正在工作的 工作空间。
>
> `~/.ssh/`、`~/.aws/credentials`、`~/.npmrc` 或这些路径之外的任意 `.env` 文件等敏感目录在容器内 **不可访问**。脚本每次运行都会打印确切的挂载路径，以便您可以审计已暴露的内容。
>
> **多工作空间选择性加入：** 如果您在单个会话中跳转到多个项目根目录，请将 `SYSQLOW_WORKSPACE_ROOTS` 设置为以逗号分隔的绝对路径列表。脚本会展开 `~`、跳过不存在的条目（并发出警告），并将任何嵌套路径折叠为最短的覆盖祖先（因此 `~/Projects` 和 `~/Projects/foo` 不会产生重叠的 Docker 挂载）。
>
> ```bash
> # 示例：暴露两个无关的工作空间根目录
> SYSQLOW_WORKSPACE_ROOTS="~/Projects,~/work" ./run-docker.sh
> ```
>
> **升级者的重大更改：** 以前的版本在项目位于 `$HOME` 下时，会无声地挂载 `$HOME`。如果您依赖于扫描新挂载范围之外的项目，请设置 `SYSQLOW_WORKSPACE_ROOTS` 以包含它们 — 否则 `detectCurrentProject()` 将在后续运行中看不到这些目录。知识库中的现有行不受影响；只有新项目根的 **检测** 受范围限制。
>
> **其他仍然适用的强化提示：**
> * **最小化机密注入。** 只有 `TURSO_*`、`GEMINI_API_KEY`、`BRAVE_API_KEY`、`MCP_TRANSPORT`、`PORT` 和 `SYSQLOW_WORKSPACE_DIR` 默认被传递到容器中 — 在添加更多之前，请查看 `run-docker.sh`。
> * **仪表板未经过身份验证。** `/` 仪表板和 `/api/*` SSE 模式下的端点没有身份验证层。绑定到 `127.0.0.1`（默认 Render 设置使用 Render 的边缘进行 TLS + 访问控制）或在公开之前使用具有身份验证的反向代理运行。
---
## 🖥️ 交互式 Web 管理控制台和知识图谱仪表板
服务器在 SSE 模式下运行时，打开浏览器并访问：
👉 **`http://localhost:50741/`**
### 仪表板的主要功能：
1. **交互式实体关系知识图谱：** 由 **Vis.js Network** 驱动的可拖动、物理定向 2D 节点。
* **翡翠节点：** 验证的技术片段。
* **琥珀节点：** 过时/待处理片段。
* **蓝色节点：** 自动化的 `项目上下文` 片段。
* **虚线链接：** 类别匹配连接。
* **实线有向箭头：** 内容文本中发现的自动关键词/提及引用。
2. **动态居中和重新居中视图：**
* **自动居中：** 图形在物理模拟稳定后，自动触发高级动画过渡，以将节点居中并适应视口。
* **重新居中按钮：** 底左传奇面板中的玻璃态按钮（“重新居中和适应视图”）执行按需 `.fit()`，使用平滑的 `easeInOutQuad` 缩放和移动曲线，持续时间 `800ms`。
3. **多模式主题选择器（黑暗、浅色、系统模式）：**
* **分段切换栏：** 标题栏中的玻璃态主题选择器，允许您在浅色、黑暗和系统同步模式之间无缝切换（实时跟踪和响应操作系统级别的配色方案更改）。
* **保存的偏好：** 外观设置在刷新和重启之间保存在 `localStorage` 中。
* **动态画布对比度适应：** 切换主题会自动重新校准 Vis.js 画布渲染颜色（在浅色模式下绘制高对比度深板岩边缘和文本标签，在黑暗模式下绘制发光的半透明白色元素），以防止边缘褪色或可读性降低。
4. **交互式多工作空间项目过滤器：** 传奇中的复选框选择允许您在 Vis.js 画布上动态过滤节点和边，瞬间隔离项目视图，无需缓慢的 API 调用。
5. **AI 生成的统一重构差异：** 如果片段已过时，详细信息抽屉会渲染高对比度、彩色编码的 Git 样式统一差异块，突出显示已添加的行（绿色）和已删除的行（红色）。
6. **哨兵手动审计控制：** 点击任意节点，打开密集的高对比度详细信息侧边栏，点击“触发哨兵审计”，使用 Gemini 实时验证您的片段是否符合实时文档。
7. **被动后台“哨兵”审计员：** 在后台 SSE 模式下激活，该工作线程每 12 小时扫描一次数据库，以自动审计和同步过时的片段。
8. **实时 MCP 日志终端：** 等宽、自动滚动的终端馈送，捕获所有服务器操作，自动将标准启动和数据库同步状态跟踪分类为绿色 `[INFO]` 日志，而不是错误。
9. **环境配置查看器：** 在精确的 50/50 垂直分区内显示所有活动环境变量，与日志终端高度匹配，安全地编辑关键凭据（`GEMINI_API_KEY` 等）。
---
## 📦 打包和本地编译
您可以将 SysQlow-MCP 编译为 **单个独立的原生可执行二进制文件**，在主机上无需 Node 或 Bun 运行时：
```bash
# 编译为 dist/sysqlow-mcp
bun run compile
```
---
## 🖥️ IDE 集成配置
要在工作空间中将 **系统查询流** 作为开发人员伴侣集成：
### 1. Antigravity-IDE 集成（SSE / URL 模式）
1. 确保 Docker 容器在 SSE 模式下运行：`./run-docker.sh --sse`。
2. 在 Antigravity-IDE 中打开 **管理 MCP 服务器**，点击 **“查看原始配置”**，并添加：
```json
{
"mcpServers": {
..., // 其他 mcp 服务器，请在此处粘贴
"sysqlow-mcp": {
"$typeName": "exa.cascade_plugins_pb.CascadePluginCommandTemplate",
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:50741/sse"
],
"env": {
"TURSO_DATABASE_URL": "libsql://your-db-url.turso.io",
"TURSO_AUTH_TOKEN": "your-turso-jwt-token",
"GEMINI_API_KEY": "your-gemini-key",
"BRAVE_API_KEY": "your-brave-key"
}
},
}
}
```
> [!NOTE]
> `"mcp-remote"` 特定于 **Antigravity-IDE** 的原始配置格式，用于注册 SSE 网络端点。
### 2. 其他 IDE（Cursor、Windsurf、Claude Desktop 等）
* 对于 Cursor、Claude Desktop、Windsurf 或其他环境，设置过程因平台对 Stdio 或 SSE 的支持而异。
* 请直接参阅 **您的相应 IDE/客户端的官方文档** 以获取正确的设置说明。
#### 示例 Stdio 配置（原生二进制）
对于启动标准输入/输出（stdio）命令的客户端（例如 Claude Desktop 或通用 VS Code 扩展），您可以调用编译后的原生二进制：
```json
{
"mcpServers": {
"sysqlow-mcp": {
"command": "/Users/barayuda/Projects/personal/sysqlow-mcp/dist/sysqlow-mcp",
"env": {
"TURSO_DATABASE_URL": "libsql://your-db-url.turso.io",
"TURSO_AUTH_TOKEN": "your-turso-jwt-token",
"GEMINI_API_KEY": "<your-gemini-key>",
"BRAVE_API_KEY": "<optional-brave-key>"
}
}
}
}
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器