第 10 章 · 01 Explorer 图工作台、MCP 与插件生态

第 10 章 · 01 Explorer 图工作台、MCP 与插件生态

本节摘要：管线装配完毕，本节逛生态、看交付面。explorer 图工作台——semantica/explorer 的 FastAPI 后端（约 8900 行，routes/ontology.py 一个文件 3544 行，WebSocket 会话推送图变更）配上根目录 explorer/ 的 React 19 前端（sigma.js 图渲染 + Monaco 编辑器 + vis-timeline 时间轴）；mcp/——独立 MCP server 以 stdio JSON-RPC 暴露 decisions/export/extraction/graph/reasoning 五类 17 个工具，任何 MCP agent 可直接操作 Semantica；再点到 integrations（Agno/CrewAI/OpenClaw）、plugins（8 种编辑器插件 + 市场清单）、cli.py（4422 行、50+ 命令）、deploy（7 个平台模板）与 cookbook 37 册导读。

内容来源：原项目源码 semantica/explorer/app.py、semantica/explorer/routes/、explorer/package.json、explorer/src/workspaces/、mcp/server.py、mcp/README.md、mcp/tools/__init__.py、integrations/、plugins/、semantica/cli.py、deploy/、cookbook/。

⚠️ 注意：explorer 的 WebSocket 端点 /ws/graph-updates 有自己的鉴权（app.py:194-233）——CORS 中间件管不到 WebSocket 握手，代码单独校验 Origin 白名单（非法来源 close 4403）与 x-api-key/api_key 参数（缺失 close 4401）；浏览器无法自定义握手头，所以前端走 query 参数传 key。

学习目标

阅读完本节，你应当能够：

1. 说出 explorer 前后端的分工与 11 个 workspaces，并解释 WebSocket 会话为什么绕开 CORS 自建鉴权。
2. 列出 MCP server 五类工具的代表作，并把这个 server 接进 Claude Code 配置。
3. 区分 integrations、plugins、CLI、deploy 四个生态面的受众与入口。
4. 用 CLI 的命令组地图快速定位目标命令。
5. 把 cookbook 37 册对到八段管线上，规划自己的实练路线。

一、explorer：FastAPI 后端 + React 前端的图工作台

后端 semantica/explorer/ 是标准 FastAPI 应用工厂：create_app（app.py:83 行）里 lifespan（100 行）管理会话生命周期，_install_mutation_bridge（56 行）把图会话的变更事件桥接成 WebSocket 广播——前端改图、后端落库、其他会话实时收到。11 个路由文件按域拆分：graph、decisions、provenance、temporal、sparql、vocabulary、analytics、annotations、enrich、export_import，以及最大的 routes/ontology.py（3544 行）——本体中心的注册、URL/文件加载、预览、创建、实体搜索、SKOS、健康度与 SHACL 全在这一处（模块头注释），文件里还能看到工程防御细节：URL 加载限 20 MB（_MAX_FETCH_BYTES）、健康分析限 5000 节点防 OOM、SSRF 防护（ipaddress/socket 检查）。

前端在仓库根目录 explorer/：React 19 + TypeScript + Vite，渲染三件套写进 package.json——sigma 3.x（含 @sigma/edge-curve、@sigma/node-border，大图 WebGL 渲染）、@monaco-editor/react（SPARQL/查询编辑）、vis-timeline（第 7 章双时态的时间轴可视化），另有 @xyflow/react（流程图）与 react-arborist（树视图）。src/workspaces/ 下 11 个工作区与后端路由一一对应：Graph、Ontology、Decision、Reasoning、Sparql、Vocabulary、Lineage、DiffMerge、Enrich、ImportExport、Manage——第 3 到第 9 章装配的每一层能力，这里都有一个操作台。效果见 demo：

二、mcp/：把 Semantica 交给任何 Agent

顶层包 mcp/ 是独立的 MCP server——不依赖 semantica 包之外的框架，stdio 上跑 JSON-RPC 2.0（server.py 模块头："Claude Code, Cursor, Windsurf, Cline, Continue, VS Code Copilot, etc."），日志走 stderr 不污染协议流。工具按域分五个模块（tools/init.py:15-19 拼装）共 17 个：

另有 4 个资源（semantica://graph/summary、semantica://decisions/list、semantica://schema/info、semantica://ontology/schema）。接入只需一段配置（mcp/README.md 的 Claude Code 示例）：

{"mcpServers": {"semantica": {
    "command": "python", "args": ["-m", "mcp"], "cwd": "/path/to/semantica"}}}
​

意义在于协议级开放：第 5 章的确定性推理、第 6 章的决策记录、第 7 章的溯源审计，从"Python 库 API"升格为"任何 MCP agent 的原生工具"——Claude 在对话里就能 record_decision 并 get_provenance 反查依据。

三、integrations 与 plugins：两个方向的生态钩子

integrations/ 面向 Agent 框架，三个一等公民：Agno（context_store、decision_kit、kg_toolkit、knowledge_graph、shared_context 五件——AgnoKGToolkit 提供 extract_entities/extract_relations/add_to_graph/query_graph 等方法给 agent 当工具；cookbook integrations 三册全是 Agno 场景）、CrewAI（knowledge_source/knowledge_graph 把图谱当知识源，kg_tool/decision_tool 当工具）、OpenClaw（个人 AI agent 平台，mcp_tool.py 提供 OpenClawKGTool 与 OpenClawMCPConfig）。plugins/ 面向编辑器：8 份插件清单——.claude-plugin、.cursor-plugin、.codex-plugin、.vscode-plugin、.windsurf-plugin、.cline-plugin、.continue-plugin、.openclaw-plugin，每份含 marketplace.json/plugin.json（.claude-plugin 的 marketplace.json 注册了 "semantica-local" 市场项）。插件内容三块：agents/（decision-advisor、explainability、kg-assistant 三个子代理角色提示词）、skills/（causal/decision/extract/ingest/ontology/provenance/reason/temporal/validate 等 17 个技能）、hooks/。编辑器里的 AI 助手由此获得与 MCP agent 同等的图谱操作力。

四、cli.py 与 deploy：命令行与生产线

semantica/cli.py（4422 行）是 click 构建的单一入口 semantica，全局选项就埋着本章主角：--store（图后端）、--vector-store（向量后端，529 行 main 签名）——第 8 章的一行切换在命令行上是一个 flag。命令按组组织，50+ 个子命令覆盖全管线：顶层 ingest/parse/watch（文件监听增量入库）/init；组命令 kg（build/query/stats）、embed（生成/索引/搜索）、reason（跑推理与解释）、decision（record/list/query/causal）、temporal（时间点查询）、provenance（lineage/审计/PROV-O 导出）、validate（SHACL 与冲突）、ontology（generate/import/validate + SKOS）、visualize、store（管理三类存储后端）、pipeline（init/validate/run）、backup、server（REST API 启停）、explorer（工作台启停）、mcp（server 启停 + 直接调工具）、services、config。deploy/ 备好 7 个平台的部署模板：azure、gcp、helm（含 knowledge-explorer 子表）、kubernetes（deployment/ingress/kustomization/networkpolicy 一应俱全）、railway、render、fly——从本地 demo 到 K8s 集群，交付面已经铺平。

五、cookbook 37 册导读

cookbook/ 共 37 个 notebook：introduction 21 册 + advanced 13 册 + integrations 3 册。introduction 序号即管线段：02 数据摄入、03 文档解析、04 归一化（①②段）；05/06 实体与关系抽取、07/08 图谱构建、09 图库、10 图分析（③⑤段）；11 分块、12 嵌入、13 向量库（③⑥段）；17 冲突、18 去重（④段）；14 本体、15 导出（第 9 章）；16 可视化、19 Context、20 三元组库、21 Amazon Neptune（⑧段与第 8 章）。advanced 按专题进阶：多源集成、高级抽取、Datalog 推理、时序图谱、语义层、非结构化转本体、Snowflake 手动本体映射、高级向量检索等——其中 Advanced_Context_Engineering 与 14_Datalog_Style_Reasoning 直通第 6、5 章两个高点。integrations 3 册全部围绕 Agno：决策智能、GraphRAG 上下文、多智能体共享上下文。读法建议：intro 顺着序号跑一遍（全部无 key 可跑），再按你的管线段跳 advanced。

💡 装配要点：生态四面的分工——explorer 给人（可视化战场，WebSocket 实时协同）；MCP/integrations 给 agent（五类工具 + 三框架钩子，图谱成为 AI 的可审计记忆）；plugins 给编辑器（8 份清单 + 17 技能 + 3 角色提示词）；CLI/deploy 给产线（50+ 命令、--store/--vector-store 全局切换、7 平台模板）。每一面都复用同一套核心 API——生态不是另起炉灶，是同一管线的四种触达方式。

本节要点回顾

1. explorer 分工：FastAPI 后端（11 路由，ontology.py 3544 行，SSRF/内存防护齐备）+ React 19 前端（sigma.js/Monaco/vis-timeline，11 workspaces）；/ws/graph-updates 自建鉴权（Origin 4403、api_key 4401）。
2. MCP server：stdio JSON-RPC，五类 17 工具 + 4 资源；一段 mcpServers 配置接入 Claude Code 等任何 MCP 客户端。
3. integrations：Agno（五件套 + cookbook 3 册）、CrewAI（知识源 + 工具）、OpenClaw（MCP 配置化接入）。
4. plugins：8 编辑器清单（claude/cursor/codex/vscode/windsurf/cline/continue/openclaw）+ 3 agents + 17 skills + hooks。
5. CLI：4422 行 50+ 命令，--store/--vector-store 全局切后端；store/explorer/mcp 子命令把三大入口握在一只手里。
6. deploy + cookbook：7 平台模板（K8s/Helm 最全）；37 册 = 21 intro（按管线序号排）+ 13 advanced + 3 integrations，全程无 key 可跑。

下一节：全书最后一节——沿八段管线把十章装配成果串成一条完整的流水线，复盘 Semantica 的四点核心哲学，交给你一份下一步清单。