# 图分析工具参考 图驱动分析的工具层：72 个 Graph Engine 目录工具与 3 个 MCP 会话管理接口，按数据准备、结构分析、机器学习和结果表达分类，提供参数、返回与调用边界。 ## 调用约定 iGraph 通过这些工具把分析问题转化为图上的计算。智能体先确认当前图中节点、边、属性和权重的业务含义，再选择查询、路径、社区、中心性或图学习等操作；工具返回的结构与数值构成结果解释的依据。一个任务可以根据证据逐步组合多类工具，具体调用取决于问题和数据条件。技能负责组织流程，Graph Engine 执行图计算。 工具使用固定英文名称与 JSON 参数。本页收录 72 项通用业务工具，并单列 3 个 MCP 会话管理接口；专项案例的扩展工具以运行时 MCP 发现结果为准。参数名称和枚举不随界面语言变化，报告工具可由部署配置关闭。 | 接口层 | 请求与返回 | | --- | --- | | MCP 工具调用 | tools/call 的 params 为 {name, arguments}。用户、会话和执行标识由已建立的 MCP 连接及运行上下文提供；返回内容中的文本是 JSON 结果。 | | Graph Engine HTTP | POST /sessions/{session_id}/tools/{tool_name}，请求体为 {"arguments":{...}}。这是服务间接口，携带服务凭据与用户/会话身份；受控 Run 还携带执行代次和 operation ID。 | | 图与数据集版本 | graph_version 标识会话活动图；revision 标识数据集保存的构图成果。load_constructed_graph 把保存成果接入会话，两个编号不要求相等。 | | 后台工作 | async=true 时保留 job_id，用 get_job_status 查状态。普通完成结果位于 job.result，大图结果通过 get_job_result 获取 summary、preview、artifact_id；明确终态后仍需检查业务结果。 | 独立构图智能体的私有工具集覆盖不同构图阶段，共有 inspect_schema、set_workload、evaluate_queries、optimize_graph、connect_columns、generate_entity_table、unfold_multi_category、add_primary_key、remove_primary_key、materialize_join、finish 这 11 个名称。它们运行在隔离的构图任务中，不属于本页 Graph Engine 目录工具。 主智能体使用页面末尾的 6 个公开构图工具检查能力、读取成果、载入活动图，以及预览和提交用户指定修改。私有 optimize_graph 用于构图过程的候选变换；公开 preview_graph_optimization/commit_graph_optimization 用于保存图的显式修改，两者具有不同的执行与验收上下文。 - success=false 表示工具级失败；HTTP 错误和未满足的数据、模型或版本条件也必须处理。不要把空预览、排队成功或缺失模型当作分析成功。 - 数值 limit 通常最多 200，路径默认 10，列表默认 20，社区/分量默认 5；只有数据模式明确声明的参数可发送。all 会扩大输出，仍需阅读 truncated 与范围字段。 - 点号形式的嵌套参数用于阅读，例如 train_config.epochs；实际 JSON 应发送 {"train_config":{"epochs":200}}。 - [图算法与结果解读](/zh/graph-algorithms/): 先了解各算法的含义、适用条件和数值示例。 - [图机器学习](/zh/graph-ml/): 查看数据结构、训练实现、损失函数和推理示例。 默认 72 项由 60 项图/系统工具、6 项公开构图工具、5 项图学习工具与 1 项报告工具组成；关闭报告后少一项。Runtime 的技能、用户记忆、经验检索和工作区工具另行注册，不在此计数内。本文核对工具目录与实现，不声称所有算法和参数组合已逐项实测。 本页直接调用 Graph Engine 或 MCP 的示例属于内部服务接口，仍需服务密钥与工作区 / 会话上下文。内部 X-User-ID 应与 GET /api/workspace 返回的 user_id 一致；它是默认工作区归属，不是可供浏览器选择的登录身份。浏览器调用 Backend 公共 /api/* 接口不需要此头。 ## 数据接入、数据集与图版本 先区分数据来源与保存位置。边列表、三元组和上传文件可以直接进入会话图；Registry 数据集与已构图数据集有各自的加载接口。加载、清空、无向化和版本切换会改变后续分析使用的图，执行后应核对 get_graph_info 与 graph_version。 ### 加载边列表 · load_graph 将带可选权重的边列表载入当前会话。每行使用 src dst [weight]；可创建图或追加普通图。 - `edge_text` (string, 必填): 边列表文本，每行由起点、终点和可选数值权重构成。 - `append` (boolean): false 替换活动图；true 追加普通图。任一侧为构图属性图时不支持追加。 默认：false 返回：返回加载状态、graph_version 和规模信息。后续用 get_graph_info 检查图结构。 - 覆盖与追加会改变活动图。构图属性图不支持 append，返回 UNSUPPORTED_PROPERTY_GRAPH_APPEND 时原图保持不变。 ### 加载上传的图文件 · load_graph_from_upload 读取已注册的图文件并识别格式，支持 NPZ、PT 与 graph_data.v1 JSON；多图 PT 自动路由到图分类数据集加载。 - `filename` (string, 必填): 当前会话已注册的上传文件名。 - `append` (boolean): false 替换活动图；true 追加普通图。任一侧为构图属性图时不支持追加。 默认：false - `directed` (boolean): 文本格式自动识别时使用的方向参数，默认 true；结构化图的实际方向仍应读取加载结果。 默认：true 返回：直接加载返回格式、状态与图版本；后台加载返回 async、job_id、status。任务完成后读取 get_job_status 的 job.result。 - MCP 对 .sql、.csv、.txt 文件返回 CONSTRUCTION_REQUIRED，要求先在数据集面板构图。引擎的其他文件路径可检测边列表、三元组或自然语言，但不能据此绕过数据集构图入口。 - 自然语言、多图数据集与部分 Nebula 导入会转为后台工作；不要将 queued 当作图已加载完成。 ### 从文本抽取图 · load_graph_from_text 从直接文本或已上传文件抽取实体与关系，并提交异步文本抽图任务。extraction_goal 可限定实体和关系范围。 - `text` (string): 直接传入的待抽取文本；与 filename 二选一。 - `filename` (string): 已上传文本文件名；工具直接读取文件，与 text 二选一。 - `directed` (boolean): 是否按有向关系生成图。 默认：true - `append` (boolean): false 替换活动图；true 追加普通图。任一侧为构图属性图时不支持追加。 默认：false - `extraction_goal` (string): 限定抽取目标，例如只保留公司、人物与任职关系。 返回：返回 async=true、job_id 和 queued 状态；最终结果包含抽取与图加载信息。 - 该入口执行文本关系抽取。基于技能的数据集构图由独立构图智能体完成，具有查询验收与表示演化流程。 ### 加载关系三元组 · load_graph_from_triples 将显式 source–relation–target 三元组转换为图，可附置信度、证据文本和来源分块编号。 - `triples` (array, 必填): 三元组对象数组。每项必须含 source、relation、target，可含 confidence、evidence、chunk_id。 - `directed` (boolean): 是否按有向关系生成图。 默认：true - `append` (boolean): false 替换活动图；true 追加普通图。任一侧为构图属性图时不支持追加。 默认：false 返回：返回加载状态、图版本与规模；关系和附带证据信息参与图数据生成。 - relation 写入 edge_type，evidence 写入 edge_text，confidence 写入 edge_feat；三元组数不一定等于最终边条目数。 ### 清空活动图 · clear_graph 清空当前会话的活动图，并更新图版本状态。 返回：返回 success、graph_version 及清空后的图状态。 ### 转换为无向图 · to_undirected 将当前图转换为无向图，发布转换后的活动版本。 返回：返回转换状态、图版本、节点与边数量及方向信息。 - 方向转换会影响路径、入度/出度与边计数语义；转换后重新读取 get_graph_info。 ### 列出数据集 · list_datasets 列出当前用户与会话范围可访问的数据集，供后续加载或构图成果选择。 返回：返回 datasets 列表及数据集标识、版本和存储信息；构图数据集受访问范围限制。 ### 加载已保存的数据集 · load_dataset 将已保存数据集的指定版本载入活动图；version=latest 选择最新保存版本。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 - `version` (string): 已保存的数据集版本标识；latest 表示最新版本。 默认："latest" 返回：返回 dataset_id、dataset_version、图版本与规模。已构图数据集应使用 load_constructed_graph。 - 已构图数据集使用 load_constructed_graph；普通加载可能返回 USE_CONSTRUCTED_GRAPH_LOADER，提示更新正确的会话绑定。 ### 保存为数据集 · save_as_dataset 把当前图保存为可再次加载的数据集，并更新当前会话的数据集绑定。 - `name` (string, 必填): 新数据集的名称。 - `description` (string): 保存到数据集元数据的用途说明。 返回：返回 dataset 元数据，包括数据集标识、名称、版本及用户或全局范围。 ### 撤销图变更 · undo_graph 将活动图恢复到之前可用的图状态，供撤回上一步图变更。 返回：返回恢复是否成功及当前 graph_version；无可用历史状态时返回失败说明。 ### 列出会话图版本 · list_graph_versions 列出当前会话可加载的图版本，用于在完整图、子图和历史状态之间切换。 返回：每项包含 graph_version、描述、创建时间、节点与边数量，以及 current 标记。 ### 切换会话图版本 · load_graph_version 把当前会话切换到 list_graph_versions 中的指定图版本。 - `graph_version` (integer, 必填): 目标图版本号；使用 list_graph_versions 返回的真实编号。 返回：返回切换状态、当前 graph_version 和节点、边数量。 ### 删除会话图版本 · discard_graph_version 删除指定会话图版本；删除活动版本时先切换到可用的 fallback 版本。用于版本清理与撤销临时派生图。 - `graph_version` (integer, 必填): 要删除的真实图版本编号。 - `fallback_graph_version` (integer): 删除活动版本前切换到的已加载历史版本。省略或不可用时尝试之前可用版本；不存在回退版本则失败。 返回：返回 discarded_graph_version、当前 graph_version 和图规模；版本或可用回退状态不存在时返回失败。 - 该工具在目录中标记为 internal，但原生 MCP 工具发现仍可取得它。它删除历史版本；普通切换使用 load_graph_version。 ## 大图分区计算与结果文件 先准备分区版本，等待 published，再核对能力并提交算法。结果摘要与预览保持有界，可下载文件保存完整或有界物化结果；普通活动图和分区表示不能直接互换。 ### 准备大图分区快照 · prepare_large_graph 将注册的边列表或三元组文件流式处理为版本化分区快照，提交持久化后台作业。 - `filename` (string, 必填): 已在当前会话注册的上传文件名；内容必须符合 input_format。 - `graph_id` (string): 逻辑图标识；省略时使用当前 session_id。 - `graph_version` (integer): 可显式指定至少为 1 的新版本号，不能覆盖已占用版本；省略时由服务分配并校验与普通图版本的绑定。 - `input_format` (string): edgelist 为边列表，triples 为关系三元组；默认 edgelist。 可选值：edgelist, triples 默认："edgelist" - `delimiter` (string): auto 自动识别，或 whitespace、comma、tab、单字符分隔符。 默认："auto" - `directed` (boolean): 是否保留有向语义，默认 true。 默认：true - `partitions` (integer): 分区数量，范围 1–128；省略时按服务端配置和资源计算。 - `workers` (integer): 请求的工作进程数，至少 1；实际并行度受分区数、CPU 和资源准入限制。 - `quality_policy` (object): 显式控制节点规范化、边唯一键、权重冲突、自环和无效记录处理。省略对象与传空对象的默认语义可能不同，见注意事项。 - `quality_policy.node_normalization` (string): exact 保留原名；nfkc_casefold 做 Unicode NFKC 规范化与大小写折叠。 可选值：nfkc_casefold, exact - `quality_policy.edge_key` (string): endpoints 按端点识别逻辑边；endpoints_relation 保留多关系平行边，当前经典算法会拒绝该语义。 可选值：endpoints, endpoints_relation 默认："endpoints" - `quality_policy.weight_conflict` (string): 重复逻辑边取 first/last/max/min 权重或 reject。 可选值：first, last, max, min, reject - `quality_policy.self_loops` (string): 自环保留 allow、跳过 skip 或拒绝 reject。 可选值：allow, skip, reject - `quality_policy.invalid_records` (string): 无效记录跳过 skip 或拒绝 reject。 可选值：skip, reject 返回：提交返回 async=true、job_id、graph_id 与 graph_version；完成结果含质量摘要、规模及 representation=partitioned_snapshot，current_graph_replaced=false。 - 无需先构建完整 GraphData 或 NetworkX 图；需要运行中的大图 worker 与足够资源。省略 quality_policy 时，edgelist 默认保留节点原名并采用最后重复边权；triples 默认 nfkc_casefold 与最大权重。传入空对象使用质量策略类的默认值，不能视作完全等同于省略对象。 ### 提交大图算法作业 · run_large_graph_algorithm 在已发布的分区快照版本上提交算法；先核对运行时能力，不把名称相同当作与普通图算法完全等价。 - `graph_id` (string): 逻辑图标识；省略时使用当前 session_id。 - `graph_version` (integer, 必填): 已发布的分区快照版本号，至少为 1。准备阶段可指定新版本，不能覆盖已占用版本。 - `algorithm` (string, 必填): 选择大图计算入口；子方法与指标放在 parameters 中，先用能力目录核对语义和资源约束。 可选值：degree, in_degree, out_degree, degree_centrality, shortest_path, all_shortest_paths, maximum_flow, minimum_cut, global_minimum_cut, minimum_spanning_tree, community_detection, node_centrality, graph_connectivity, find_cycles, maximum_cycle, topological_sort, degree_analysis, subgraph_extraction, link_prediction_score, path_analysis, clique_analysis, reachability, global_metrics, graph_structure_analysis, connectivity_analysis, tree_dag_analysis, matching_coloring_analysis, distance_measures - `parameters` (object): 按算法提供端点、method/metric、预览和资源选项；点号参数在实际 JSON 中嵌套发送。条件必填项见下文，不能跨算法混用选择器。 - `workers` (integer): 请求的工作进程数，至少 1；实际并行度受分区数、CPU 和资源准入限制。 - `parameters.source` (string): 起点；与 target 或流/割的 sink 配合。 - `parameters.target` (string): 终点；shortest_path 可用 all 生成源点距离结果文件。 - `parameters.sink` (string): maximum_flow/minimum_cut 的汇点。 - `parameters.algorithm` (string): 路径子模式 default/yen_k_shortest；社区子模式为其余名称，当前均映射到加权同步标签传播近似。 可选值：default, yen_k_shortest, louvain, greedy_modularity, label_propagation, label_propagation_asyn, leiden, girvan_newman, asyn_fluidc - `parameters.centrality_type` (string): 中心性指标；部分方法为采样或明确标记的近似，先查询能力。 可选值：degree, betweenness, closeness, pagerank, eigenvector, harmonic, katz, load, voterank, percolation 默认："degree" - `parameters.method` (string): 与顶层 algorithm 对应的子方法，不同分组的枚举不能混用。 可选值：ego_graph, k_core, k_truss, k_corona, node_subset, jaccard, adamic_adar, resource_allocation, preferential_attachment, all_simple_paths, has_path, average_shortest_path_length, find_cliques, clique_number, number_of_cliques, transitive_closure, descendants, ancestors, is_tree, is_forest, is_directed_acyclic_graph, bfs_tree, dfs_tree, lexicographical_topological_sort, all_topological_sorts, is_at_free, check_planarity, is_tournament, score_sequence, is_bipartite, weisfeiler_lehman_graph_hash, node_connectivity, edge_connectivity, minimum_node_cut, minimum_edge_cut, articulation_points, bridges, local_bridges, biconnected_component_edges, bridge_components, condensation, maximum_spanning_tree, random_spanning_tree, lowest_common_ancestor, immediate_dominators, dominance_frontiers, dag_longest_path, dag_longest_path_length, antichains, is_aperiodic, colliders, v_structures, max_weight_matching, min_weight_matching, maximal_matching, min_edge_cover, is_matching, greedy_color, equitable_color - `parameters.metric` (string): global_metrics/distance_measures 的指标选择器。 可选值：density, diameter, radius, transitivity, average_clustering, degree_assortativity, center, periphery, eccentricity, wiener_index, global_efficiency, local_efficiency, average_neighbor_degree, average_degree_connectivity, rich_club_coefficient, reciprocity, flow_hierarchy, barycenter, estrada_index, girth - `parameters.node` (string): ego_graph、descendants/ancestors 必需节点；number_of_cliques 可选指定节点。 - `parameters.nodes` (array): node_subset 的节点名称数组，运行时默认最多 10,000 项，部署可收紧。 - `parameters.focus_nodes` (array): 本次社区结果中需确认归属的节点名，最多 200 项。 - `parameters.k` (integer): Yen 路径数 1–200（默认 3），或 ego 半径及 core/truss/corona 阈值（默认 2）。 - `parameters.cutoff` (integer): all_simple_paths 最大边数，1–10,000，默认 5。 默认：5 - `parameters.limit` (integer | string): 预览项数 1–200；all 仍映射到 200 条硬上限，完整结果以结果文件及其范围说明为准。 - `parameters.top_k` (integer | string): degree/链接预测前列项数，1–200；all 仍为 200。省略时分别为 20/10。 - `parameters.max_cycles` (integer): 最大环搜索候选数 1–100,000，默认 10,000。 默认：10000 - `parameters.optimize_by` (string): maximum_cycle 按节点数或权重总和选择已搜索的最好环。 可选值：length, weight 默认："length" - `parameters.treat_as_undirected` (boolean): global_minimum_cut 是否把有向输入投影为无向图。 默认：true - `parameters.max_iterations` (integer): 迭代上限，目录范围 1–2,000；社区实际最多 500 次，默认 5。 默认：5 - `parameters.sample_sources` (integer): Brandes 类中心性的采样源点数，最多 10,000；小于总节点数时标记 approximate，部署硬上限不能由 allow_expensive 绕过。 - `parameters.damping` (number): PageRank 阻尼系数，必须有限且 0 < damping < 1。 默认：0.85 - `parameters.alpha` (number): Katz 有限衰减系数，默认 0.1。 默认：0.1 - `parameters.beta` (number): Katz 有限外源偏置，默认 1。 默认：1 - `parameters.tolerance` (number): 迭代中心性的有限正收敛容差。 默认：0.000001 - `parameters.use_weight` (boolean): shortest_path 是否按边权计算；all_shortest_paths 固定加权，其他算法忽略此参数。 默认：true - `parameters.create_version` (boolean): 子图提取默认发布新分区版本，后续显式使用 new_graph_version；不自动替换普通活动图。false 仅生成结果文件。 默认：true - `parameters.allow_expensive` (boolean): 允许通过部分平方/指数复杂度准入门槛，不会取消内存、采样等硬限制。 默认：false - `parameters.strict_semantics` (boolean): 拒绝大图中的近似语义映射，不自动改为完整 NetworkX 计算。 默认：false 返回：返回异步作业句柄；完成后通过 get_job_result 获取 summary、preview 和 artifact_id。精确、近似、有界或混合语义以能力与实际结果为准；完整可物化输出保存在结果文件中。 - 路径需 source/target，流/割需 source/sink，方法类需 method，指标类需 metric。LCA 另需 node1/node2，支配关系需 source，均衡着色需 num_colors。参数对象允许扩展字段，但仍由运行时按算法校验；不支持模式或资源不足会明确拒绝。 ### 列出大图快照版本 · list_large_graph_versions 列出当前用户与会话中指定逻辑图的分区版本。 - `graph_id` (string): 逻辑图标识；省略时使用当前 session_id。 返回：返回 success、graph_id 和 versions；版本信息包含准备/发布状态与质量摘要。 - 只有已发布版本可用于算法。该列表不是 list_graph_versions 返回的普通活动图历史，不要仅凭编号假定两个表示已绑定同一数据源。 ### 查看大图结果文件 · get_large_graph_artifact 读取大图结果文件的元数据与可选有界预览，不把完整分区结果放入模型上下文。 - `artifact_id` (string, 必填): 作业真实返回的结果文件标识；必须属于当前用户和会话。 - `include_preview` (boolean): 是否附带有界结果预览，默认 true；不加载完整分区文件。 默认：true 返回：返回 success、artifact 和 download_url_template；文件总数、路径/下载序号预览与完整序号范围在 artifact 中。 - download_url_template 的 {partition} 是扁平结果文件列表的下载序号，不一定等于输入分区编号。经 Backend 的 /api/sessions/{session_id}/large-graph/artifacts/{artifact_id}/partitions/{partition} 逐文件下载，仍校验工作区、会话和文件范围，无需浏览器登录。 ### 查询大图运行能力 · get_large_graph_capabilities 读取当前大图引擎支持的操作、子模式、语义与资源约束。 返回：返回 success 与 capabilities，包含引擎版本、精确/近似/有界语义、复杂度、并行策略和结果类型。 - 目录表示实现契约和适用条件，不代表每个方法都已在当前数据上运行成功。社区名称当前映射为加权同步标签传播近似，部分中心性也有采样或近似映射；严格比较前设置 strict_semantics 并核对实际结果。 ## 图概览与实体检索 从 get_graph_info 开始确认规模和方向，再用精确节点名称或 ID 读取结构。自然语言检索用于缩小候选范围，不能把最高分候选自动视为已确认实体。平行关系可能具有相同端点；完整关系核对应结合保存的属性图和关系标识。 ### 查看图概览 · get_graph_info 读取活动图的规模、方向、结构类型、属性和学习准备情况，作为分析前的起点。 返回：返回图概要、节点与边预览、num_edge_entries、num_unique_edges、semantic_type、storage_type，以及标签、特征与图学习就绪状态。 - num_edge_entries 是存储条目数，num_unique_edges 是去重后的逻辑边数；双向存储的无向图应按其语义理解计数。 ### 查看节点信息 · get_node_info 通过精确节点名称或字符串形式的 ID 查看局部结构和节点属性。 - `node_name` (string, 必填): 精确节点名称或字符串形式的节点 ID。 返回：返回节点度、入度、出度、邻居、前驱、关联边与标签、类型；有节点文本时包含 text。列表按预览上限截断。 - 描述性查询先使用 search_node，取得精确名称后再调用本工具。 ### 查看关系信息 · get_edge_info 查看指定端点之间的有向关系及属性。平行关系可以对应多条关系记录。 - `src_name` (string, 必填): 关系起点的精确节点名称。 - `dst_name` (string, 必填): 关系终点的精确节点名称。 返回：返回存在状态及权重、关系名称、标签与类型；多关系结果附预览和截断信息。 - 平行关系应使用返回的真实关系 ID 区分；只给端点不代表图中只有一条关系。 ### 检查边是否存在 · check_edge_exists 检查指定起点到终点的边是否存在，适合在后续分析前验证精确关系。 - `src_name` (string, 必填): 关系起点的精确节点名称。 - `dst_name` (string, 必填): 关系终点的精确节点名称。 返回：返回 exists 和 directed 等状态字段。 ### 查询一跳邻居 · get_neighbors 查询一跳邻居。统一入口在本地图读取 GraphData，在 Nebula 主存储上执行原生遍历。 - `node_name` (string, 必填): 精确节点名称或字符串形式的节点 ID。 - `direction` (string): out 沿出边，in 沿入边，both 忽略方向作双向遍历；具体支持取决于工具与存储后端。 可选值：out, in, both 默认："out" - `limit` (integer): 一跳邻居返回上限，服务端限制为 1–200；不接受 all。 默认：20 返回：返回指定方向的邻居列表及相关遍历信息，最多按 limit 返回。 - Nebula 的方向参数由原生查询处理；返回的是一跳局部结果。 ### 检索节点 · search_node 从名称、节点文本、类型、标签和度约束中检索节点，将自然语言描述解析为后续工具可用的精确名称。 - `query` (string, 必填): 待检索的自然语言描述、名称或文本片段。 - `top_k` (integer): 候选节点数，默认 8，服务端限制为 1–50。 默认：8 - `filters` (object): 节点约束对象：node_type、label，以及 total/in/out degree 的 min/max 限制。 - `sort` (object): 排序对象：field 可为 score、node_id、degree、num_neighbors、in_degree、out_degree 或 total_degree；order 为 asc 或 desc。 - `rerank` (boolean): 检索响应中的重排开关标记；目前未接入独立重排模型。 默认：true 返回：返回 best、candidates、ambiguous、semantic_enabled 和 retrieval_mode；候选包含精确 node_name 及匹配证据。 - ambiguous=true 时先确认候选。没有可用语义嵌入服务时，精确名称或有效节点编号仍可匹配；其他文本查询不会获得词法相似度分数，候选主要由结构过滤和排序决定。使用 semantic_enabled 与 retrieval_mode 判断模式。 - 实体语义检索依赖 Graph Engine 自己的嵌入服务配置：EMBEDDING_PROVIDER 可显式选择 sentence-transformers、openai 或 lexical。默认先尝试本地 Sentence Transformers（需要依赖与模型权重），失败后在存在 OPENAI_API_KEY 时选择 OpenAI，否则使用词法哈希。当前 OpenAI 分支调用固定的 api.openai.com/v1/embeddings；Agent Runtime 的聊天模型或 EMBEDDING_BASE_URL 配置不会自动改写这个地址。词法模式不为实体查询提供语义相似度排序；索引编码失败时也会禁用语义检索，应检查 semantic_enabled 与检索错误信息。 显式选择 openai 时必须提供 OPENAI_API_KEY；显式提供方初始化失败不会执行上述自动选择。首次实体索引会编码全图节点与边文本，远程服务的可达性、延迟和额度也影响可用性。 ### 检索关系 · search_edge 按关系描述、边文本、属性或起终点描述检索关系；可同时限定两端语义。 - `query` (string): 待检索的自然语言描述、名称或文本片段。 - `src_query` (string): 用名称或自然语言描述约束起点节点。 - `dst_query` (string): 用名称或自然语言描述约束终点节点。 - `top_k` (integer): 候选关系数，默认 8，服务端限制为 1–50。 默认：8 - `filters` (object): 关系约束对象：edge_type、label、min_weight 与 max_weight。 - `sort` (object): 排序对象：field 为 score、edge_idx 或 weight；order 为 asc 或 desc。 - `rerank` (boolean): 检索响应中的重排开关标记；目前未接入独立重排模型。 默认：true 返回：返回 best、candidates、ambiguous 及检索模式，候选包含精确端点和关系信息。 - query、src_query、dst_query 至少提供一项；ambiguous=true 时先确认关系或端点候选。 - 精确端点定位只返回最后一条关系，无法据此枚举全部平行关系；逐条核对请使用保存属性图中的真实 edge_id。 - 语义查询使用与 search_node 相同的 Graph Engine 嵌入服务；无可用服务时只保留精确定位、结构过滤与排序能力，rerank 不会调用独立重排模型。 ## 路径与可达性 先说明“最短”指最少跳数还是最小权重和。all_shortest_paths 枚举等长最优解，yen_k_shortest 返回按成本排序的备选简单路径，两者不同。可达性结果也受方向和远端查询范围影响；没有返回路径时先检查范围字段。 ### 计算最短路径 · shortest_path 计算最低成本或最少跳数路径。default 返回一条最短路径；yen_k_shortest 返回按代价排序的前 k 条简单路径；target=all 查询单源可达路径摘要。 - `source` (string, 必填): 精确起点节点名称。 - `target` (string, 必填): 终点节点；特殊值 all 返回起点到所有可达节点的距离统计和最近路径预览。 - `use_weight` (boolean): true 以边权作为距离或代价；false 只计算跳数。 默认：true - `algorithm` (string): default 返回一条最短路；yen_k_shortest 返回前 k 条不重复的简单路径。 可选值：default, yen_k_shortest 默认："default" - `k` (integer): 仅 yen_k_shortest 使用，指定候选简单路径数量；默认 3，至少为 1。 默认：3 - `direction` (string): 仅 Nebula 主存储且 use_weight=false 时生效；本地最短路遵循活动图方向。 可选值：out, in, both 默认："out" - `max_steps` (integer): Nebula 原生查询或有界物化的最大跳数，服务端限制为 1–20。 默认：10 返回：单路径返回 found、path、hop_count、total_length、edges、weighted；k 路径返回 paths；all 返回 reachable_count、距离统计和 nearest_paths。 - 权重在此表示距离或成本。多重图对同一端点对取最小权重构成私有计算视图，原有关系不被删除。 ### 枚举等长最短路径 · all_shortest_paths 枚举指定两节点之间总权重相同的最短路径，适合检查最优路线是否唯一。 - `source` (string, 必填): 精确起点节点名称。 - `target` (string, 必填): 精确终点节点名称。 - `direction` (string): out 沿出边，in 沿入边，both 忽略方向作双向遍历；具体支持取决于工具与存储后端。 可选值：out, in, both 默认："out" - `max_steps` (integer): Nebula 原生查询或有界物化的最大跳数，服务端限制为 1–20。 默认：10 - `max_nodes` (integer): Nebula 子图物化的节点数量上限，防止无界读取。 - `max_edges` (integer): Nebula 子图物化的边数量上限。 返回：返回 length、paths、count_returned、truncated；默认最多展示 10 条。没有路径时 paths 为空。 - 本工具返回等价最优路径；yen_k_shortest 可以包含成本更高的备选路径。公开参数不含 limit，默认结果上限为 10 条。 ### 分析路径 · path_analysis 判断可达性、枚举简单路径或计算平均最短路径长度；通过 method 选择问题类型。 - `method` (string, 必填): all_simple_paths 枚举简单路径；has_path 判断可达性；average_shortest_path_length 计算平均加权最短距离。 可选值：all_simple_paths, has_path, average_shortest_path_length - `source` (string): all_simple_paths 与 has_path 必需；平均最短路径模式无需填写。 - `target` (string): all_simple_paths 与 has_path 必需；平均最短路径模式无需填写。 - `cutoff` (integer): all_simple_paths 的最大路径边数；默认 5，至少按 1 处理。 默认：5 - `direction` (string): out 沿出边，in 沿入边，both 忽略方向作双向遍历；具体支持取决于工具与存储后端。 可选值：out, in, both 默认："out" - `max_steps` (integer): Nebula 原生查询或有界物化的最大跳数，服务端限制为 1–20。 默认：10 - `max_nodes` (integer): Nebula 子图物化的节点数量上限，防止无界读取。 - `max_edges` (integer): Nebula 子图物化的边数量上限。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：10 返回：按模式返回 has_path、paths/count/truncated 或平均距离结果；Nebula 有界分析会附范围元数据。 - 平均最短路径按边权计算。有向图要求整图强连通，否则失败；无向非连通图只计算最大连通分量。该结果不能用来宣称其他分量也可互达。 ### 分析可达性 · reachability 查询节点的所有可达后代、可达祖先，或生成图的传递闭包预览。 - `method` (string, 必填): transitive_closure 生成传递闭包；descendants 查询后代；ancestors 查询祖先。 可选值：transitive_closure, descendants, ancestors - `node` (string): descendants 和 ancestors 必需，transitive_closure 不需要。 - `max_steps` (integer): Nebula 原生查询或有界物化的最大跳数，服务端限制为 1–20。 默认：10 - `max_nodes` (integer): Nebula 子图物化的节点数量上限，防止无界读取。 - `max_edges` (integer): Nebula 子图物化的边数量上限。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回节点或闭包边预览、数量和截断标记；闭包未完全枚举时给出 num_edges_at_least。 - Nebula 查询受 max_steps、max_nodes、max_edges 限制。范围内无路径或未返回某节点，不能直接证明整图不可达。 ## 网络流、割与生成树 网络流把边权解释为容量，割衡量断开网络所需移除的容量，生成树最小化覆盖节点的连接成本。三类工具的目标函数不同。平行边在流量计算中累加容量，在最小生成树计算中按相应计算策略合并，不修改原始关系记录。 ### 计算最大流 · maximum_flow 把边权解释为容量，计算 source 到 sink 能传输的最大总流量。 - `source` (string, 必填): 精确起点节点名称。 - `sink` (string, 必填): 精确汇点节点名称。 返回：返回 max_flow_value、total_nonzero_edges、top_flow_edges 和 truncated。 - weight 作为容量，平行边容量相加；不能直接把成本图的权重当作吞吐能力。 ### 计算源汇最小割 · minimum_cut 求分离指定源点与汇点的最小容量割，用于定位网络瓶颈。 - `source` (string, 必填): 精确起点节点名称。 - `sink` (string, 必填): 精确汇点节点名称。 返回：返回 min_cut_value、分区规模、较小分区节点和割边预览。 - 源汇最小割使用容量语义；平行关系在计算视图中按容量求和。 ### 计算全局最小割 · global_minimum_cut 无需指定端点，求无向加权图的全局最小割。有向图可显式按无向图处理。 - `treat_as_undirected` (boolean): 允许将有向输入解释为无向加权图；false 时有向全局最小割不受支持。 默认：true - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回 min_cut_value、algorithm、分区规模、割边预览及 disconnected；不连通图割值为 0。 - 有向图在 treat_as_undirected=false 时拒绝该操作；需要保留方向的源汇问题使用 minimum_cut。 ### 计算最小生成树 · minimum_spanning_tree 在无向计算视图上寻找总权重最小的连接骨架；不连通图返回最小生成森林摘要。 返回：连通时返回 total_weight、num_edges 和 mst_edges_preview；不连通时返回 num_components 和 forest_summary。 - 采用无向视图；对属性多重图使用每对节点间的最小权关系。森林摘要不等于完整边列表。 ## 连通性、环、拓扑与团 连通分量描述哪些节点能够连在一起，环揭示循环依赖，拓扑排序只适用于有向无环图。团分析区分“不能再扩大的极大团”和“节点数最多的最大团”。环与团的枚举可能很昂贵；输出条数限制不应被当作完整性证明。 ### 分析连通性 · graph_connectivity 分析有向图的强、弱连通性，或无向图的连通分量。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：5 返回：返回连通性判断、分量总数、大小与节点预览；默认展示 5 个分量，每个预览 10 个节点。 ### 枚举简单环 · find_cycles 枚举图中的简单环，帮助检查反馈回路、循环依赖和闭合结构。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回 cycles、truncated 和 total_cycles_at_least；截断时数量是已确认下界。 - 简单环数量可能指数增长。limit=all 会取消展示枚举上限；truncated=true 时不可把已返回环数写成全图总数。 ### 搜索最大环 · maximum_cycle 在受限的简单环枚举中寻找最长环或权重和最大的环，并报告搜索是否穷尽。 - `optimize_by` (string): length 优先选择节点数最多的环；weight 优先选择总边权最大的环。 可选值：length, weight 默认："length" - `max_cycles` (integer): 最多扫描的简单环数量，默认 10000，服务端限制到 1–100000。 默认：10000 返回：返回 cycle、cycle_length、cycle_weight、edges、cycles_examined、search_exhausted 和 truncated。 - 最长简单环是高成本组合问题。search_exhausted=false 时只保证已扫描候选中的最优结果；多重图暂不支持。 ### 计算拓扑顺序 · topological_sort 为有向无环图生成满足依赖先后关系的拓扑顺序。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回拓扑顺序预览、节点总数及 truncated；包含环时无法给出合法拓扑序。 - 拓扑顺序可能不唯一；预览只是合法顺序的前缀，不代表整个执行计划。 ### 分析团结构 · clique_analysis 在无向视图上枚举极大团、求最大团大小，或统计节点参与多少个极大团。 - `method` (string, 必填): find_cliques 枚举极大团；clique_number 求最大团大小；number_of_cliques 统计节点参与的极大团数。 可选值：find_cliques, clique_number, number_of_cliques - `node` (string): 仅 number_of_cliques 使用；省略则返回各节点的参与次数预览。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：find_cliques 返回团预览及数量下界；clique_number 返回最大团大小；number_of_cliques 返回节点参与次数。 - 极大团是无法再扩展的完全子图；最大团是所有团中规模最大的一个。团枚举可能指数增长，多重图暂不支持。 ### 图结构判定与遍历 · graph_structure_analysis 检查树、森林、DAG、二部图、平面性及锦标赛结构，或生成遍历树、拓扑序和 WL 哈希。 - `method` (string, 必填): 选择本工具支持的方法；不同方法的前提和附加必填参数见下文。 可选值：is_tree, is_forest, is_directed_acyclic_graph, bfs_tree, dfs_tree, lexicographical_topological_sort, all_topological_sorts, is_at_free, check_planarity, is_tournament, score_sequence, is_bipartite, weisfeiler_lehman_graph_hash - `source` (string): BFS/DFS 遍历必填的真实起点名称。 - `depth_limit` (integer): BFS/DFS 最大遍历深度，整数且不小于 0。 - `iterations` (integer): Weisfeiler–Lehman 哈希迭代次数，至少 1，默认 3。 默认：3 - `limit` (integer | string): 列表预览默认 20，正整数最多 200。all 对普通列表可扩大输出，但拓扑序、反链、collider/v-structure 枚举仍保留 200 条硬上限。 默认：20 返回：根据方法返回 value、is_planar、hash、score_sequence、order/orders 或遍历树 edges_preview，附总量与截断信息；不会改变活动图。 - 树/森林、AT-free、二部图和平面性使用无向视图。BFS/DFS 需 source；拓扑排序需 DAG。score_sequence 检查出度序列是否满足锦标赛得分序列条件，不能代替 is_tournament。WL 哈希相同也不是同构证明。 - 当前普通图入口不支持多重图，返回 UNSUPPORTED_MULTIGRAPH_OPERATION；大图同名算子有独立能力约束。 ### 连通度、割集与桥 · connectivity_analysis 计算点/边连通度、最小点割/边割、割点、桥、局部桥、双连通分量、桥分量及强连通缩点图。 - `method` (string, 必填): 选择本工具支持的方法；不同方法的前提和附加必填参数见下文。 可选值：node_connectivity, edge_connectivity, minimum_node_cut, minimum_edge_cut, articulation_points, bridges, local_bridges, biconnected_component_edges, bridge_components, condensation - `source` (string): 局部点/边连通度或割集的起点，与 target 同时提供；二者省略时计算全局值。 - `target` (string): 终点节点的真实名称；局部连通度与割集需与 source 同时提供。 - `limit` (integer | string): 列表预览默认 20，正整数最多 200。all 对普通列表可扩大输出，但拓扑序、反链、collider/v-structure 枚举仍保留 200 条硬上限。 默认：20 返回：按方法返回 value、nodes、items、components 或缩点图 nodes/edges；size/count 和 truncated 描述总量与列表范围。 - 局部连通度/割集同时提供 source 和 target。连通度、割集、割点、桥和双连通类方法使用无向视图；condensation 要求有向图。全局最小点/边割要求非空连通输入，并非前述按权重容量计算的 minimum_cut。 - 当前普通图入口不支持多重图，返回 UNSUPPORTED_MULTIGRAPH_OPERATION；大图同名算子有独立能力约束。 ### 树、DAG 与支配关系 · tree_dag_analysis 查询最大/随机生成树、最近公共祖先、支配关系、DAG 最长路、反链、非周期性与汇聚结构。 - `method` (string, 必填): 选择本工具支持的方法；不同方法的前提和附加必填参数见下文。 可选值：maximum_spanning_tree, random_spanning_tree, lowest_common_ancestor, immediate_dominators, dominance_frontiers, dag_longest_path, dag_longest_path_length, antichains, is_aperiodic, colliders, v_structures - `source` (string): immediate_dominators/dominance_frontiers 必填的真实起点名称。 - `node1` (string): 最近公共祖先查询的第一个节点名。 - `node2` (string): 最近公共祖先查询的第二个节点名。 - `seed` (integer): 随机生成树的随机种子，默认 42。 默认：42 - `limit` (integer | string): 列表预览默认 20，正整数最多 200。all 对普通列表可扩大输出，但拓扑序、反链、collider/v-structure 枚举仍保留 200 条硬上限。 默认：20 返回：按方法返回 edges/total_weight、ancestor、items、path、value、antichains 或 structures。汇聚结构结果含 count_is_exact；count=null 表示未得到精确总数。 - 生成树使用连通无向视图；LCA 需 node1/node2，支配关系需 source。DAG 最长路按 weight 计算，拓扑相关方法要求 DAG。is_aperiodic 要求非空强连通有向图；v_structures 排除两个前驱之间已有连接的情形。 - 当前普通图入口不支持多重图，返回 UNSUPPORTED_MULTIGRAPH_OPERATION；大图同名算子有独立能力约束。 ### 匹配、边覆盖与着色 · matching_coloring_analysis 在无向视图上计算权重匹配、极大匹配、最小边覆盖与着色，或校验给定边集是否构成匹配。 - `method` (string, 必填): 选择本工具支持的方法；不同方法的前提和附加必填参数见下文。 可选值：max_weight_matching, min_weight_matching, maximal_matching, min_edge_cover, is_matching, greedy_color, equitable_color - `edges` (array): is_matching 待校验边集，使用二元数组或 {from,to} 对象，端点为真实节点名。 - `maxcardinality` (boolean): 最大权匹配是否先最大化匹配边数，再优化权重；默认 false。 默认：false - `strategy` (string): greedy_color 使用的 NetworkX 策略名称，默认 largest_first。 默认："largest_first" - `num_colors` (integer): equitable_color 必填颜色数；运行时要求大于图的最大度。 - `limit` (integer | string): 列表预览默认 20，正整数最多 200。all 对普通列表可扩大输出，但拓扑序、反链、collider/v-structure 枚举仍保留 200 条硬上限。 默认：20 返回：返回 matching 或 edges 及 size/total_weight，匹配校验返回 value，着色返回 coloring 与 num_colors；列表可截断。 - 极大匹配是不能再加入边的匹配，不保证边数最大。最小边覆盖拒绝孤立节点；equitable_color 需要 num_colors 大于最大度。greedy_color 的结果依赖策略，不承诺最少颜色。 - 当前普通图入口不支持多重图，返回 UNSUPPORTED_MULTIGRAPH_OPERATION；大图同名算子有独立能力约束。 ### 扩展距离与结构指标 · distance_measures 计算中心、边缘、离心率、Wiener 指数、效率、邻居度、富俱乐部系数、互惠性、流层级、重心、Estrada 指数或围长。 - `metric` (string, 必填): 选择度量指标，注意其方向、权重和连通分量范围。 可选值：center, periphery, eccentricity, wiener_index, global_efficiency, local_efficiency, average_neighbor_degree, average_degree_connectivity, rich_club_coefficient, reciprocity, flow_hierarchy, barycenter, estrada_index, girth - `limit` (integer | string): 列表预览默认 20，正整数最多 200。all 对普通列表可扩大输出，但拓扑序、反链、collider/v-structure 枚举仍保留 200 条硬上限。 默认：20 返回：标量返回 value；节点集合返回 nodes/count，映射返回 values/count，并附适用的 truncated。无环图 girth 返回 value=null、acyclic=true。 - 中心、边缘、离心率、Wiener 指数和重心使用最大无向连通分量；其中重心按 weight，其他四项无权。效率使用无权无向视图，富俱乐部系数 normalized=false。flow_hierarchy 要求有向图并使用权重。 - 当前普通图入口不支持多重图，返回 UNSUPPORTED_MULTIGRAPH_OPERATION；大图同名算子有独立能力约束。 ## 中心性与全局统计 中心性回答节点为何重要，整体指标描述图的形态。度中心性、介数中心性、PageRank 和接近中心性使用不同定义，分值不应直接横向比较。有向图、平行关系、零或负权重会影响可用方法，详细条件见图算法指南。 ### 计算节点中心性 · node_centrality 从连接数、最短路桥接、随机游走、特征向量、传播和投票等角度评估节点重要性。 - `centrality_type` (string): 选择度、介数、接近、PageRank、特征向量、调和、Katz、负载、VoteRank 或渗流中心性。 可选值：degree, betweenness, closeness, pagerank, eigenvector, harmonic, katz, load, voterank, percolation 默认："degree" - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回 centrality_type、total_nodes、value_stats、top_nodes、bottom_nodes 和 truncated。 - 多重图中 PageRank/eigenvector/Katz 使用平行权重求和；betweenness/closeness/harmonic/load 使用最小距离。voterank/percolation 尚未支持多重图。 - 属性/多重图的距离权重须非负；betweenness 与 load 还要求严格正权重。迭代中心性可能因数值或收敛条件失败。 ### 分析度分布 · degree_analysis 分析图的入度、出度或总度分布，识别高连接节点、低连接节点与孤立节点。 - `node` (string): Nebula 主存储下指定节点时直接查询该节点度，避免物化全图；本地路径仍进行图级度分析。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回度统计、分布与高低度节点预览；Nebula 指定 node 时直接返回该节点的度。 ### 计算全局指标 · global_metrics 计算密度、直径、半径、全局聚类系数（传递性）、平均聚类系数或度同配系数等整体指标。 - `metric` (string, 必填): 选择密度、直径、半径、全局聚类系数（传递性）、平均聚类系数或度同配系数。 可选值：density, diameter, radius, transitivity, average_clustering, degree_assortativity 返回：返回 metric、value 与 defined。直径/半径使用最大无向连通分量的无权距离；非有限值表示为 value=null、defined=false。度同配系数无定义时还附原因码和说明。 - density 保留原图方向语义；diameter/radius 在最大无向分量计算。多重图仅显式支持 density、diameter、radius。 ## 社区、子图与结构预测 社区发现形成节点分组，子图提取选择结构范围，结构链接预测对尚不存在的边打分。社区编号只是一次计算的分区标记。subgraph_extraction 默认会创建活动版本，若只想查看结果，应明确设置 create_version=false。 ### 发现社区 · community_detection 在无向计算视图上识别连接紧密的节点群，比较社区大小与模块度。 - `algorithm` (string): 选择 Louvain、贪心模块度、同步/异步标签传播、Leiden、Girvan–Newman 或流体社区。 可选值：louvain, greedy_modularity, label_propagation, leiden, girvan_newman, asyn_fluidc, label_propagation_asyn 默认："louvain" - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：5 - `focus_nodes` (array): 最多 200 个真实节点名，查询它们在本次社区划分中的归属；未知名称列入 missing_focus_nodes。 - `max_iterations` (integer): 范围 1–500，默认 5；仅供大图加权同步标签传播使用，普通 NetworkX 社区算法不使用此参数。 默认：5 返回：返回算法名、社区总数、模块度、社区规模与节点预览，附 communities_truncated。 - Leiden 依赖不可用或计算失败时回退 Louvain。Girvan–Newman 取第一次拆分；asyn_fluidc 在非连通图上只处理最大分量。 - 多重图仅支持 louvain 与 greedy_modularity，以无向平行权重求和视图计算；每个社区内部节点仍是预览。 ### 提取子图 · subgraph_extraction 提取 ego 邻域、核、truss、corona 或指定节点诱导子图，可预览或发布为活动图版本。 - `method` (string, 必填): ego_graph 为 k 跳邻域；k_core 为最小核内度 k；k_truss 要求每边参与至少 k−2 个三角形；k_corona 选核内度恰为 k 的节点；node_subset 为指定节点诱导子图。 可选值：ego_graph, k_core, k_truss, k_corona, node_subset - `node` (string): ego_graph 的中心节点；其他模式无需填写。 - `k` (integer): ego_graph 的半径，或 k_core/k_truss/k_corona 的阈值；k_truss 要求 k≥2。 默认：2 - `nodes` (array): 用于 node_subset 的精确节点名称数组。 - `create_version` (boolean): true 创建并切换到子图版本；false 仅返回预览，保持活动图不变。 默认：true - `description` (string): 新子图版本说明，仅 create_version=true 时保存。 - `direction` (string): Nebula ego_graph 的遍历方向；本地邻域提取遵循相应图算法语义。 可选值：out, in, both 默认："out" - `max_nodes` (integer): Nebula 子图物化的节点数量上限，防止无界读取。 - `max_edges` (integer): Nebula 子图物化的边数量上限。 - `limit` (integer | string): 结果预览上限，数值最多 200；all 请求完整结果，可能显著增加返回量或枚举成本。 默认：20 返回：返回子图规模、节点与边预览；create_version=true 时还返回新图版本并切换活动图。 - create_version 默认 true。仅想检查局部结构时传 false；活动图切换后，后续工具使用新的子图。 - 多重图显式支持 ego_graph 与 node_subset；核、truss 与 corona 不在已支持的多重图选项内。 ### 计算结构链接预测分数 · link_prediction_score 用邻域相似度和节点度构造无需训练的候选边评分；可评估单个节点对或对全图非边排序。 - `method` (string, 必填): jaccard 为共同邻居/邻居并集；adamic_adar 按共同邻居度的对数倒数加权；resource_allocation 使用度倒数；preferential_attachment 使用两节点度乘积。 可选值：jaccard, adamic_adar, resource_allocation, preferential_attachment - `source` (string): 与 target 同时提供时，仅计算此节点对；都不提供时对非边候选排序。 - `target` (string): 与 source 成对使用，指定要评估的另一端节点。 - `top_k` (integer): 全图非边评分返回数，默认 10，实际限制为 1–20。 默认：10 返回：返回指定节点对的得分，或按分数排序的前 top_k 个候选关系。 - 使用无向邻域。全图候选评分仍需扫描非边，top_k 只限制保留的结果；多重图不支持。 ## 文档索引与上下文检索 文档索引与图实体索引独立管理。upload_document 将文本分块并保存索引，retrieve_context 返回相关片段用于解释分析结果。片段相关性不等于图关系已经成立，也不会自动补充当前图中的节点或边。 ### 建立文档索引 · upload_document 将直接文档内容或当前会话上传文件加入文档检索索引，用于后续获取背景证据。 - `filename` (string): 会话上传文件名；直接传 content 时可用作来源标识。 - `content` (string): 直接提供的文档文本；未提供时从 filename 对应的会话上传文件读取。 返回：返回文档标识、分块数量与检索模式等索引结果。 - 文档索引属于当前会话。切换嵌入服务的向量维度可能需要重新索引现有文档。 ### 检索上下文片段 · retrieve_context 从当前会话的文档索引检索与查询相关的片段，为图分析解释提供上下文。 - `query` (string, 必填): 待检索的自然语言描述、名称或文本片段。 - `top_k` (integer): 返回的候选或相关结果数量。 默认：5 返回：返回相关片段、文档与分块标识、分数及检索模式。 ## 可视化与分析报告 先得到真实分析结果，再生成视图或报告。可视化负责裁剪和呈现图结构；报告工具组织调用方提供的结果，不会自动重跑所有分析。显示节点数、社区预览和高亮范围应与算法结果的计算范围分别解释。 ### 生成图视图 · visualize_subgraph 把全图或指定节点子图转换为可交互的节点与边视图，可叠加社区分组和节点、路径、子图高亮。 - `node_names` (array): 可视化的节点名称数组；省略或为空时从全图生成视图。 - `include_community` (boolean): 是否为视图附加社区信息。 默认：true - `max_nodes` (integer): 节点展示上限，目录默认 800；超量时使用确定性的概览选择。引擎省略值可通过 VISUALIZE_MAX_NODES 配置。 默认：800 - `highlights` (object): 高亮对象，可含 nodes、paths、subgraphs。节点组使用 ids，路径使用 node_sequence，子图使用 nodes；各组可设 color 与 label。 返回：返回 nodes、edges 及可选社区与高亮信息；受限视图附 truncated 等字段，活动图不变。 - 概览综合高亮、节点类型、社区代表、高度数节点和连接路径；边上限由 VISUALIZE_MAX_EDGES 控制，默认 2,000。检查 truncated、total_nodes/total_edges、overview.required_nodes_truncated；过多高亮也可能截断。图指标应来自分析工具。 ### 生成分析报告 · create_analysis_report 将已有图分析结果组织为报告规格，包括摘要、图表、表格和规则化文字洞察。 - `report_intent` (string, 必填): 报告目的：overview 总览、analysis 分析、diagnosis 诊断、comparison 对比、custom 自定义。 可选值：overview, analysis, diagnosis, comparison, custom 默认："analysis" - `analysis_goal` (string, 必填): 用户的分析目标，或智能体对任务目标的准确归纳。 - `title` (string): 报告标题。 - `source_results` (object, 必填): 以工具名为键组织真实分析结果，例如 get_graph_info、degree_analysis、node_centrality。 - `options` (object): 报告展示配置：top_k 控制图表与表格上限，include_narrative 控制文字洞察，max_sections 限制章节数。 - `options.top_k` (integer): 图表和表格中展示的项目上限。 默认：10 - `options.include_narrative` (boolean): 是否生成基于结果的规则化文字洞察。 默认：true - `options.max_sections` (integer): 报告章节数量上限。 默认：6 返回：返回报告结构与展示数据；所有统计必须来自 source_results、当前图或用户明确提供的数据。 - 报告工具由 MCP_ENABLE_REPORTING_TOOLS 控制，默认启用；设为 0、false、no 或 off 时不向智能体注册。 - 返回 analysis_report.v2 结构以供界面展示，不自动写入 Markdown/PDF 或 Derived。需要可下载文件时，在 Runtime 的 Ephemeral 工作区生成内容，再用 workspace_publish(path=..., name=...) 发布；name 应带正确扩展名。 ## 图机器学习 训练前确认任务、输入特征、标签与数据划分。单图上的节点分类和链接预测与多图分类使用不同数据绑定；模型 ID 来自实际完成的训练作业。下面列出工具契约，图学习指南进一步解释损失函数、训练循环和推理结构。 ### 加载图分类数据集 · load_graph_classification_dataset 加载会话中上传的 HIV 或 PCBA 多图 PT 文件，并绑定为图分类训练和推理数据集。 - `filename` (string, 必填): 当前会话已注册的上传文件名。 - `dataset_profile` (string): auto 从数据识别契约；hiv 与 pcba 显式选择支持的多图分类数据集格式。 可选值：auto, hiv, pcba 默认："auto" 返回：返回数据集标识、profile、图数量、标签与划分信息；MCP 调用以后台任务处理加载。 - 使用数据集固定契约、划分与指标。将其中一张图加载为活动图不会把多图分类问题变为单图训练数据。 ### 加载单张分类样本图 · load_graph_classification_graph 从已绑定的图分类数据集中选取一张图，载入活动单图供结构分析与可视化。 - `graph_index` (integer, 必填): 图分类数据集中的零基图索引，范围为 0 到 num_graphs−1。 - `dataset_id` (string): 可选指定已绑定图分类数据集；省略时使用当前会话的默认绑定。 返回：返回 graph_version、单图规模、split、graph_label、预览与分析就绪状态。 ### 查看模型结构 · visualize_model_architecture 读取已训练模型的元数据，生成层级结构摘要与 Mermaid 模型图。 - `model_id` (string, 必填): 当前会话可访问的已训练模型 ID。 返回：返回模型结构图、层级摘要和关键超参数。 ### 训练图模型 · train 训练节点分类、链接预测、图分类或预训练模型；数据配置、训练超参数与算法结构分别传入。 - `task` (string, 必填): 选择节点分类、链接预测、图分类或预训练任务。 可选值：node_classification, link_prediction, graph_classification, pretrain - `model` (string): 骨干网络名称：APPNP / GCN / GAT / GATV2 / GEN / GIN / SAGE / TRANSFORMER。三个监督任务和 GNN 预训练必填，Node2Vec 不要求。 - `method` (string): pretrain 必填：node2vec 或 contrastive_learning、graph_contrastive_learning、mask_autoencoding、graph_mask_autoencoding；后四项共享 GNN 边重构实现。 - `graph_version` (integer): 校验当前活动单图的版本，不会自动加载历史版本；省略时使用活动图。图分类不接受此字段。 - `upstream_model_id` (string): 上游已训练模型标识；使用嵌入向量特征时必须提供。 - `data` (object): 训练数据对象：特征来源、目标节点或边子集，以及图分类数据集 ID。 - `train_config` (object): 训练轮数、学习率、划分比例、随机种子和早停等训练设置。 - `algo_config` (object): 模型结构和设备配置；Node2Vec 预训练可传随机游走与负采样设置。 - `data.feature_source` (string): graph 使用 node_feat 或回退结构特征；embedding 按名称读取上游 embedding.npy，必须提供 upstream_model_id。图分类只接受 graph。 可选值：graph, embedding 默认："graph" - `data.target_nodes` (array): 限定节点分类的监督候选范围，使用真实节点名；仍需标签及训练/验证掩码或划分，不只表示训练集。 - `data.target_edges` (array): 链接预测正样本子集，每项必须是两个节点名称组成的数组。 - `data.dataset_id` (string): 图分类数据集 ID；省略则使用会话中已加载的默认数据集。 - `train_config.split` (object): 单图任务的训练/验证比例对象。图分类沿用数据集固定划分，不接受自定义 split。 - `train_config.split.train` (number): 训练集比例，默认 0.8。 默认：0.8 - `train_config.split.val` (number): 验证集比例，默认 0.2。 默认：0.2 - `train_config.split.test` (number): 兼容旧请求的比例字段；当前训练流程不使用此自定义 test 划分。 - `train_config.epochs` (integer): 训练轮数。 默认：200 - `train_config.lr` (number): 优化器学习率。 默认：0.05 - `train_config.weight_decay` (number): 优化器权重衰减系数。 默认：0 - `train_config.seed` (integer): 训练随机种子。 默认：42 - `train_config.early_stop_patience` (integer): 监督任务连续多少轮没有足够提升时早停；0 关闭，负数不合法。预训练忽略早停选项。 默认：0 - `train_config.early_stop_min_delta` (number): 计为提升所需的最小指标增量。 默认：0 - `train_config.batch_size` (integer): 图分类 小批次 的图数量；单图任务忽略此参数。 默认：64 - `train_config.num_workers` (integer): 图分类 DataLoader 的数据加载进程数，默认 0。 默认：0 - `algo_config.device` (string): auto 自动选择可用设备；cpu 或 cuda 显式指定计算设备。 可选值：auto, cpu, cuda 默认："auto" - `algo_config.hidden_dim` (integer): GNN 隐藏表示维度。 默认：64 - `algo_config.node_embedding_dim` (integer): 图分类中节点类别嵌入向量的维度。 默认：64 - `algo_config.embedding_dim` (integer): 节点输出向量维度。目录标注默认 64；实际未传该项时，GNN 跟随 hidden_dim，Node2Vec 使用 128。建议显式填写。 默认：64 - `algo_config.num_layers` (integer): GNN 层数，至少 2 层。 默认：2 - `algo_config.dropout` (number): 训练时的 dropout 比例。 默认：0.2 - `algo_config.gat_heads` (integer): GAT、GATV2 和 TRANSFORMER 的注意力头数，默认 2，使用 concat=False。 默认：2 - `algo_config.use_residual_connection` (boolean): 是否启用层内残差连接；维度不同时使用线性投影。 默认：false - `algo_config.use_normalization` (boolean): 是否在每个 GNN 层启用归一化。 默认：false - `algo_config.norm_pos` (string): pre 在卷积前归一化；post 在卷积或残差之后归一化。 可选值：pre, post 默认："post" - `algo_config.norm_type` (string): 选择 RMSNorm、LayerNorm 或 BatchNorm。 可选值：rms_norm, layer_norm, batch_norm 默认："layer_norm" - `algo_config.walk_length` (integer): Node2Vec 随机游走长度。 默认：20 - `algo_config.context_size` (integer): Node2Vec 的上下文窗口长度。 默认：10 - `algo_config.walks_per_node` (integer): Node2Vec 每个节点发起的随机游走数。 默认：10 - `algo_config.num_negative_samples` (integer): Node2Vec 的负样本数量。 默认：1 - `algo_config.batch_size` (integer): Node2Vec 采样加载器的批大小。 默认：128 - `algo_config.p` (number): Node2Vec 返回偏置参数 p。 默认：1 - `algo_config.q` (number): Node2Vec 向外探索偏置参数 q。 默认：1 - `algo_config.appnp_k` (integer): APPNP 传播迭代次数，至少 1，默认 10。 默认：10 - `algo_config.appnp_alpha` (number): APPNP 返回初始预测的比例，0 < alpha ≤ 1，默认 0.1。 默认：0.1 返回：MCP 返回任务句柄；完成后结果包含模型标识、训练状态与指标或错误。模型产物绑定相应会话与训练数据身份。 - 图分类必须先加载数据集，并使用固定 split/metric。feature_source=embedding 必须提供 upstream_model_id；训练前检查数据就绪状态。 - 嵌套参数用点号展示路径，实际请求仍按 data、train_config、algo_config 对象发送。MCP 自动处理训练的后台任务标记。 - MCP 层可以返回后台句柄；原生运行时的 GraphMCPTools 会监控任务并将最终结果交回主智能体。 - 缺少 node_feat 的单图使用归一化入度、出度、总度与常数特征，原始业务字段不会自动编码。GNN 预训练无独立掩码/增广实现，也不执行早停；Node2Vec 固定 CPU，默认嵌入维度 128，忽略 weight_decay 和早停。 ### 执行模型推理 · infer 使用已保存模型执行推理。任务类型由模型元数据确定，query 指定节点、节点对、候选目标或图索引。 - `model_id` (string, 必填): 当前会话可访问的已训练模型 ID。 - `graph_version` (integer): 推理使用的图版本；模型与图版本不一致时默认拒绝，除非显式允许。 - `query` (object): nodes 选节点，edges 为节点名二元数组，source_node/candidate_nodes 做候选排序，graph_indices 选图，split 选划分。省略时：节点分类返回评估和样例，链接预测搜索非边候选，图分类读取 test，预训练返回已保存向量的前若干项。 - `infer_config` (object): 推理设备、阈值、批大小、分页与任务专属输出设置。 - `query.nodes` (array): 节点分类或嵌入向量查询的精确节点名称列表。 - `query.split` (string): 按 train、val 或 test 划分选择节点或图。 可选值：train, val, test - `query.graph_indices` (array): 图分类数据集中的零基图索引数组。 - `query.edges` (array): 链接预测节点对列表，例如 [["A","B"],["A","C"]]；不接受 source/target 对象。 - `query.source_node` (string): 按一个起点执行链接预测。 - `query.candidate_nodes` (array): 该起点的候选终点名称列表。 - `query.topk` (integer): 保留得分最高的候选数量。 默认：10 - `infer_config.return_prob` (boolean): 是否在预测结果中包含概率。 默认：true - `infer_config.batch_size` (integer): 图分类推理的 小批次 大小。 默认：128 - `infer_config.device` (string): 图分类推理的设备选择：auto/cpu/cuda；节点分类与链接预测当前自动选设备，预训练只读保存的向量。 可选值：auto, cpu, cuda 默认："auto" - `infer_config.threshold` (number): 图分类二分类阈值，范围 0–1。 默认：0.5 - `infer_config.top_k_tasks` (integer): 每张 PCBA 图返回概率最高的任务数量。 默认：5 - `infer_config.return_all_task_probs` (boolean): 为 PCBA 返回完整 128 维概率、预测与真实标签数组。 默认：false - `infer_config.allow_version_mismatch` (boolean): 显式允许模型训练图版本与推理图版本不同；默认关闭。 默认：false - `infer_config.sample_size` (integer): 节点分类在空 query 下返回的随机预测样例数。 默认：20 - `infer_config.sample_seed` (integer): 预测样例抽样使用的随机种子。 默认：42 - `infer_config.result_limit` (integer): 预测明细分页上限；不把全体评估指标限制为这一页。 默认：20 - `infer_config.result_offset` (integer): 预测明细的零基分页偏移。 默认：0 - `infer_config.topk` (integer): 保留得分最高的候选数量。 默认：20 - `infer_config.max_candidate_pairs` (integer): 空 query 链接预测最多保留和评分的非边候选数，默认 200,000；生成阶段仍可能遍历全部节点对，大图建议显式提供候选。 默认：200000 - `infer_config.limit` (integer): 预训练向量查询未指定 nodes 时的返回条数上限。 默认：200 返回：监督任务返回预测明细与相应评估，分页不缩小评估集合；预训练返回 embeddings 数组，每项包含 node 与 embedding。PCBA 默认只展示少量高概率任务。 - edges 必须是二元数组列表。预测分页不应被解读为评估只覆盖这一页；PCBA 默认返回少量高概率任务。 - 预训练推理不对新图执行 GNN，只查询训练时保存的 embedding.npy。链接预测的内积解码器对称，候选中可有已存在边，需检查 exists_in_graph。节点分类 query.split 读取原图掩码，不是训练时未保存的随机划分。 ## 后台任务与图存储 job_id 用于查询已提交的作业，进度游标用于增量读取日志，最终结果来自完成状态下的 job.result。Nebula 专用工具用于存储与原生查询诊断；普通图分析仍优先使用统一工具入口，并阅读物化范围与查询限制。 ### 查询后台作业 · get_job_status 读取属于当前用户与会话的后台任务状态，并按游标获取训练或构图进度。 - `job_id` (string, 必填): 提交后台工作后返回的真实任务 ID，必须属于当前用户与会话。 - `after_seq` (integer): 仅获取此序号之后的持久化进度事件；首轮从 0 开始。 - `progress_limit` (integer): 单次读取的进度事件上限，范围 1–1000；服务端未提供时使用 200。 返回：返回 success、job 和 progress_updates。普通作业 job 含状态、进度、detail 与最终 result；大图 job 含 stage、summary、artifact_id 等持久化状态，完整结果摘要使用 get_job_result 读取。 - 普通作业传 after_seq 可按游标读取进度；省略时消费待推送进度。大图作业 progress_updates 为空。普通完成结果可从 job.result 或 get_job_result 读取，大图完成结果使用 get_job_result；两者均需检查终态与业务 success。 ### 取消后台作业 · cancel_job 请求停止指定后台任务及受控执行中的关联子任务。 - `job_id` (string, 必填): 提交后台工作后返回的真实任务 ID，必须属于当前用户与会话。 返回：返回 success 与 job_id，表示取消请求是否被接受；随后用 get_job_status 确认终态。请求成功不能单独证明计算已退出。 - 取消请求与计算停止分开确认。排队任务不会启动实际计算，运行任务要等待 worker 停止和资源回收。 ### 检查 NebulaGraph 状态 · nebula_status 检查 NebulaGraph 配置、连接及当前图的存储或同步状态。 返回：返回 Nebula 可用性、连接与图存储状态信息。 ### 同步图到 NebulaGraph · nebula_sync_graph 将当前会话图同步到 NebulaGraph，供图数据库中的查询和后续使用。 返回：同步可返回后台 job_id；通过任务状态读取最终同步结果及图版本相关信息。 - 需先配置可用的 Nebula 服务。智能体查询节点与路径通常使用 get_node_info、get_neighbors、shortest_path 这些统一入口。 ### 查询 NebulaGraph 节点 · nebula_get_node_info 直接读取 NebulaGraph 中的节点信息；依据会话使用主存储路径或已同步图路径。 - `node_name` (string, 必填): 当前图中的精确节点名称。 返回：返回 Nebula 节点、属性与连接相关信息；未加载或未同步图时返回相应存储错误。 - 这是后端专用入口。希望由引擎按当前存储选择路径时，可使用 get_node_info。 ### 查询 NebulaGraph 邻居 · nebula_get_neighbors 直接在 NebulaGraph 查询指定方向的一跳邻居，用于数据库遍历与存储侧诊断。 - `node_name` (string, 必填): 当前图中的精确节点名称。 - `direction` (string): out 沿出边，in 沿入边，both 双向遍历。 可选值：out, in, both 默认："out" - `limit` (integer): 邻居返回上限，服务端限制为 1–200，默认 20。 默认：20 返回：返回 Nebula 邻居列表与遍历信息，结果数受 limit 限制。 - 统一的 get_neighbors 同样可路由 Nebula 主存储。两者查询目的相同时无需重复调用。 ### 查询 NebulaGraph 最短路径 · nebula_shortest_path 通过 Nebula 原生查询在指定方向与最大跳数内寻找最短路径，按跳数解释最短。 - `source` (string, 必填): 精确起点节点名称。 - `target` (string, 必填): 精确终点节点名称。 - `direction` (string): out 沿出边，in 沿入边，both 双向遍历。 可选值：out, in, both 默认："out" - `max_steps` (integer): 原生路径查询的最大跳数，服务端限制为 1–20，默认 10。 默认：10 返回：返回有界路径查询结果、节点序列与遍历信息；边界内没有路径不证明整个图不可达。 - 没有 use_weight 参数，不用于最小加权代价。需要统一入口时使用 shortest_path；Nebula 原生路径对应 use_weight=false。 ### 读取后台作业结果 · get_job_result 读取普通或大图后台作业的状态与结果；大图结果保持为摘要、预览和文件引用。 - `job_id` (string, 必填): 提交后台任务后返回的真实作业 ID，属于当前用户和会话。 返回：外层返回 success 与 result。普通终态的 result 含 job_id、status、result、error；大图 result 含 status、graph_id、graph_version、summary、preview、artifact_id、error 等。 - queued/running 的 success=true 仅表示作业查找成功。确认 status=done 后再检查内层业务结果；failed/cancelled 返回 success=false。未知或无权访问的作业不会返回结果。 ## 构图成果与图优化 这些公开工具管理已经保存的构图成果，与构图子智能体内部的候选变换工具分开。读取完整图与 revision 后，预览用户提出的修改，获得确认再提交同一批操作；保存后显式加载最新构图版本，才能让后续会话分析使用它。 ### 查看构图能力 · get_graph_construction_capabilities 查询构图入口对 SQL、CSV、TXT 的算法可用性，以及保存图支持的优化规则。 返回：返回 source_type 对应能力与优化规则；未注册算法显示 algorithm_unavailable。 - 初次源文件构图由数据集面板发起。算法不可用时报告能力状态，不将旧文本抽取结果冒充技能构图成果。 ### 查询构图状态 · get_graph_construction_status 读取一个已保存数据集的构图状态、修订号和规模，判断能否直接复用构图结果。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 返回：返回 status、revision、source_type 和规模。只有 ready 表示已保存图可用。 ### 读取保存的属性图 · get_constructed_graph 读取构图数据集保存的完整属性图与 revision，为检查真实 ID 和规划修改提供依据。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 返回：graph 包含 directed、nodes(id,type,properties) 与 edges(id,source,target,type,properties)，并返回修订信息。 - 先读取图再引用元素 ID。这里的 revision 属于保存数据集，与会话 graph_version 是不同的版本空间。 ### 加载构图成果 · load_constructed_graph 将数据集已保存的构图版本加载到当前会话，接入现有分析、可视化与学习工具。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 返回：返回加载状态、会话图版本和数据集绑定；替换活动图，不重新运行构图。 - 加载后用 get_graph_info 检查分析语义与特征；使用 visualize_subgraph 展示结果。 ### 预览图修改 · preview_graph_optimization 基于已读取的 revision 预览一批保存图修改，查看元素、属性与规模变化，不写入数据集。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 - `base_revision` (integer, 必填): 读取保存图或预览时得到的 revision，必须至少为 1。 - `operations` (array, 必填): 按顺序执行的非空操作数组。每项必须含 op；可选 collapse_node、node_property_to_edge、extract_property_node、delete、reverse_edges、rename_type。 - `operations[].op` (string, 必填): 操作类型，决定本项需要的 ID、属性名与类型名。 可选值：collapse_node, node_property_to_edge, extract_property_node, delete, reverse_edges, rename_type - `operations[].node_id` (string): collapse_node 或 node_property_to_edge 使用的真实节点 ID。 - `operations[].node_ids` (array): extract_property_node 使用的真实节点 ID 数组。 - `operations[].edge_ids` (array): 要迁移属性或反转方向的真实关系 ID 数组。 - `operations[].ids` (array): delete 操作要处理的节点或边 ID，由 target 决定类型。 - `operations[].property` (string): 目标属性名称；delete 设置此字段时删除属性而非整个元素。 - `operations[].target_property` (string): 迁移到关系上的属性名称；省略时使用规则默认名称。 - `operations[].remove_from_node` (boolean): 是否同时从原节点删除已迁移属性；应显式表达所需行为。 - `operations[].node_type` (string): 提取属性节点时使用的节点类型名。 - `operations[].edge_type` (string): 新建或转换关系时使用的边类型名。 - `operations[].target` (string): 指定 node 或 edge，适用于 delete 与 rename_type。 可选值：node, edge - `operations[].cascade` (boolean): 删除节点时是否连带删除关联关系；按预览结果明确选择。 - `operations[].old_type` (string): rename_type 要匹配的现有类型名。 - `operations[].new_type` (string): rename_type 保存的新类型名。 返回：返回预览图与 diff，用于确认受影响节点、关系和属性；保存状态与 revision 不变。 - operations[].op 为每项必需字段，其余字段由具体操作决定；先用 get_constructed_graph 取得真实节点、关系与属性名。 ### 提交图修改 · commit_graph_optimization 保存已经预览并获得用户确认的同一批图优化操作，产生新的数据集 revision。 - `dataset_id` (string, 必填): 当前用户可访问的真实数据集 ID，从数据集列表或会话数据状态读取。 - `base_revision` (integer, 必填): 读取保存图或预览时得到的 revision，必须至少为 1。 - `operations` (array, 必填): 按顺序执行的非空操作数组。每项必须含 op；可选 collapse_node、node_property_to_edge、extract_property_node、delete、reverse_edges、rename_type。 - `operations[].op` (string, 必填): 操作类型，决定本项需要的 ID、属性名与类型名。 可选值：collapse_node, node_property_to_edge, extract_property_node, delete, reverse_edges, rename_type - `operations[].node_id` (string): collapse_node 或 node_property_to_edge 使用的真实节点 ID。 - `operations[].node_ids` (array): extract_property_node 使用的真实节点 ID 数组。 - `operations[].edge_ids` (array): 要迁移属性或反转方向的真实关系 ID 数组。 - `operations[].ids` (array): delete 操作要处理的节点或边 ID，由 target 决定类型。 - `operations[].property` (string): 目标属性名称；delete 设置此字段时删除属性而非整个元素。 - `operations[].target_property` (string): 迁移到关系上的属性名称；省略时使用规则默认名称。 - `operations[].remove_from_node` (boolean): 是否同时从原节点删除已迁移属性；应显式表达所需行为。 - `operations[].node_type` (string): 提取属性节点时使用的节点类型名。 - `operations[].edge_type` (string): 新建或转换关系时使用的边类型名。 - `operations[].target` (string): 指定 node 或 edge，适用于 delete 与 rename_type。 可选值：node, edge - `operations[].cascade` (boolean): 删除节点时是否连带删除关联关系；按预览结果明确选择。 - `operations[].old_type` (string): rename_type 要匹配的现有类型名。 - `operations[].new_type` (string): rename_type 保存的新类型名。 返回：返回提交结果与新 revision。版本冲突需重新读取并预览；之后调用 load_constructed_graph 更新活动会话。 - 必须保持与预览相同的 base_revision 和 operations，并完成用户确认。remove_from_node 与 cascade 应明确填写预期行为。 ## MCP 会话管理接口 这 3 项由 MCP Server 单独注册，不在 72 项工具目录中。原生 GraphMCPTools 没有过滤它们，工具发现可以取得其数据模式。它们操作 MCP 连接的显式会话绑定；原生 Run 通常通过身份请求头定位业务会话，由宿主服务管理生命周期。 | 接口 | 参数 | 用途与返回 | | --- | --- | --- | | register_session | agent_session_id: string，必需；user_id: string\|null，可选，默认空字符串。ctx 由 MCP 注入。 | 将当前 MCP 连接绑定到业务会话并请求 Graph Engine 创建会话，返回注册/创建结果。ID 应取自真实宿主会话；原生按请求头定位会话时通常不需要模型另建绑定。 | | delete_graph_session | 无公开参数；ctx 由 MCP 注入。 | 解除当前 MCP 连接的注册绑定并删除其 Graph Engine 会话。没有显式绑定时返回 success=true，不代表请求头指定的会话已删除。此接口用于会话释放。 | | set_session_config | llm_model: string\|null，必须传该字段但值可为 null；ctx 由 MCP 注入。 | 为显式绑定的 MCP 会话设置抽图等功能使用的 LLM 模型；非空值触发更新，null 不更新。未注册连接返回 session_not_registered，不能假定请求头身份等于注册绑定。 | ## 示例：路径分析与图视图 在可访问 Graph Engine HTTP 服务的服务端环境运行下面的 Python 示例。先通过工作台创建一个用于演示的会话并使其图会话注册完成，再设置 GRAPH_ENGINE_URL、IGRAPH_SESSION_ID、IGRAPH_USER_ID 和 IGRAPH_CONTROL_SERVICE_KEY。演示中的 load_graph 会替换该会话的活动图；后续子图调用使用 create_version=false。 示例权重表示距离或成本。图有 4 个节点、5 条有向边；A→B→C→D 的总成本为 4，优于 A→C→D 和 A→B→D 的成本 6。 ```python import json import os import time from urllib.request import Request, urlopen base = os.environ["GRAPH_ENGINE_URL"].rstrip("/") session_id = os.environ["IGRAPH_SESSION_ID"] headers = { "Content-Type": "application/json", "X-User-ID": os.environ["IGRAPH_USER_ID"], "X-Session-ID": session_id, "X-iGraph-Service-Key": os.environ["IGRAPH_CONTROL_SERVICE_KEY"], } def invoke(name, arguments): body = json.dumps({"arguments": arguments}).encode("utf-8") request = Request( f"{base}/sessions/{session_id}/tools/{name}", data=body, headers=headers, method="POST", ) with urlopen(request, timeout=900) as response: result = json.load(response) if result.get("success") is False: raise RuntimeError(result) return result def call(name, arguments): result = invoke(name, arguments) while result.get("async") and result.get("job_id"): job_id = result["job_id"] while True: status = invoke("get_job_status", {"job_id": job_id}) job = status["job"] if job["status"] == "done": result = job["result"] break if job["status"] in {"failed", "cancelled"}: raise RuntimeError(job) time.sleep(1) return result call("load_graph", { "edge_text": "A B 2\nA C 5\nB C 1\nB D 4\nC D 1", "append": False, }) info = call("get_graph_info", {}) path = call("shortest_path", { "source": "A", "target": "D", "use_weight": True, }) assert path["path"] == ["A", "B", "C", "D"] assert path["total_length"] == 4 preview = call("subgraph_extraction", { "method": "node_subset", "nodes": ["A", "B", "C"], "create_version": False, }) view = call("visualize_subgraph", { "max_nodes": 50, "highlights": {"paths": [{ "node_sequence": path["path"], "label": "Minimum-cost path", "color": "#356ae6", }]}, }) print(json.dumps({"path": path, "preview": preview, "view": view}, indent=2)) ``` | 调用 | 可验证结果 | | --- | --- | | shortest_path · use_weight=true | path=[A,B,C,D]，hop_count=3，total_length=4。 | | shortest_path · use_weight=false | 最少 2 跳；并列路径可能返回 A→B→D 或 A→C→D。 | | subgraph_extraction · create_version=false | 只预览 A、B、C 的诱导子图，活动图仍包含 D。 | | visualize_subgraph · highlights.paths | 在完整活动图视图中突出 A→B→C→D，不从截断视图重新计算最短路径。 | 若要比较多条候选路线，把 shortest_path 的 algorithm 设为 yen_k_shortest、k 设为 3；若只关心等代价最优解，使用 all_shortest_paths。需要保存子图时再明确启用 create_version，并记录返回的 graph_version。