graph-management

用途

GraphOS Skill: graph-management 是一套面向 AI 操作的协议，用于通过 HTTP 优先的 API 读取和修改 GraphOS 图。它适合在需要检查图结构、节点关系与选中节点上下文，或在写入前校验节点类型、检查插件运行时状态、批量应用图变更时使用。

主要能力

该技能提供以下 API：

• get_graph_description：获取完整图快照，用于规划与验证。方法 GET，路径 /api/graph/description，查询参数 graphId?。成功响应包含 graph（id、name、nodeCount、edgeCount、rootNodeIds、leafNodeIds、selectedNodeId）、nodes（AI 友好的节点描述）、edges（带 edge id 的边列表）、adjacency（每个节点的父/子 id）、aiSummary（自然语言摘要）。图不存在时返回 404。
• get_graph_node：获取单个焦点节点及其局部上下文（父节点与子节点）。方法 GET，路径 /api/graph/node，查询参数 graphId?、nodeId?。若省略 nodeId，服务器回退到图中同步的选中节点。成功响应包含 graph（id、name、selectedNodeId）、selectedNode、parentNodes、childNodes、aiSummary。若 nodeId 缺失且无同步选中节点返回 400；图或节点不存在返回 404。
• get_available_node_types：列出插件注册的节点类型 schema。方法 GET，路径 /api/node-types，无查询参数。成功响应为节点类型定义数组（type、description、properties、inTypes、outTypes）。
• get_plugins：列出插件运行时状态。方法 GET，路径 /api/plugins，无查询参数。成功响应为插件状态对象数组，包含 name、status、error、nodeTypeCount。
• apply_graph_transaction：从调用方视角原子性地应用一批图操作。方法 POST，路径 /api/graph/apply，请求体包含 graphId? 与 ops: Operation[]。

Operation schema 支持以下操作：

• CREATE_NODE：metadata 为 { id, type, position: { x, y }, data? }
• UPDATE_NODE：metadata 为 { id, data }
• DELETE_NODE：metadata 为 { id }
• CONNECT：metadata 为 { id, source, target, sourceHandle?, targetHandle? }
• DISCONNECT：metadata 为 { id }

注意事项：节点校验会针对已注册的节点类型 schema 运行；CONNECT 要求源节点与目标节点存在；重复的节点 id 与重复的边会被拒绝；DISCONNECT 使用 edge id，通常形如 edge_。成功响应包含 success、appliedCount、errorCount、applied: string[]、errors: { op, index, reason }[]、更新后的 graph、nodes、edges 以及 aiSummary。

使用方式

运行时基础 URL：默认本地运行时为 http://localhost:3411。若环境使用不同的主机或端口，请相应替换基础 URL。

Opencode 服务器配置：GraphOS 在 Properties 侧边栏中包含一个 AI Assistant 面板，连接到 opencode 服务器以处理关于选中图节点的提示。

启动 Opencode 服务器：

opencode serve [--port <number>] [--hostname <string>] [--cors <origin>]

默认情况下，opencode serve 监听 http://127.0.0.1:4096。若需从 GraphOS 在浏览器中访问，请启用 CORS：

opencode serve --cors http://localhost:3000

环境变量：在运行 GraphOS 开发服务器或构建时，设置环境变量以配置 opencode 服务器 URL。变量 VITE_OPENCODE_SERVER_URL，默认值 http://localhost:4096，描述为运行中的 opencode 服务器的基础 URL。在 .env 或 .env.local 中使用：

VITE_OPENCODE_SERVER_URL=http://localhost:4096

AI Assistant 使用步骤：

1. 启动 opencode：opencode（TUI 模式）或 opencode serve
2. 启动 GraphOS：npm run dev
3. 在图画布上选择一个节点
4. 在 Properties 面板中，滚动到底部的 AI Assistant 区域
5. 点击 Generate 自动创建包含节点 ID、类型和属性的提示
6. 按需编辑提示，然后点击 Run in Terminal（或 Cmd+Enter）

助手将任务发送到 opencode 终端执行：终端模式（默认）使用 tui.appendPrompt + tui.submitPrompt 将任务推入 opencode TUI，在其中以完全可见的方式运行；若未附加 TUI，则回退到 session.prompt。任务会出现在 opencode 终端会话中并执行，所有工具调用与响应均可在其中查看。

操作流程

步骤 1：读取约束与当前状态

• 调用 get_available_node_types 了解 schema 约束。
• 调用 get_graph_description 捕获完整拓扑。
• 若只操作单个节点区域，调用 get_graph_node 获取局部上下文。

完成检查：所需节点类型存在；已知确切的源/目标 id 与预期变更。

步骤 2：规划事务

• 构建一个连贯的 apply_graph_transaction 请求，包含所有相关操作。
• 对操作排序，使依赖关系有效（先创建后连接，先断开后删除）。
• 保持 id 稳定且确定，以便可重复重试。

决策点：若节点类型缺失，在重试写入前检查 get_plugins；若编辑有数据丢失风险，将操作范围收窄至预期范围。

完成检查：事务包含所有必需操作且无冗余变更。

步骤 3：应用并验证

• 提交 apply_graph_transaction。
• 检查响应中的 applied 与 errors。
• 重新运行 get_graph_description 验证后置状态。

决策点：若出现部分成功，仅重试失败的意图，而非重放整个批次；若出现校验错误，在重试前修补 payload 以匹配节点 schema。

完成检查：图拓扑与预期变更后状态一致；无未解决的关键错误。

安全规则

• 优先使用一个连贯的事务，而非大量微调用。
• 提交前根据节点类型要求校验节点属性 payload。
• 对于破坏性更新，先检查当前图，仅包含预期操作。
• 将部分成功视为正常：检查错误并仅重试失败的意图。
• 切勿直接编辑 *.graph.json 文件；所有图读取与修改必须通过本技能记录的 GraphOS API 进行。

请求示例

读取图：

GET /api/graph/description?graphId=main

应用事务：

POST /api/graph/apply Content-Type: application/json

{ "graphId": "main", "ops": [ { "op": "CREATE_NODE", "metadata": { "id": "n_fetch", "type": "http.request", "position": { "x": 120, "y": 80 }, "data": { "properties": { "url": "https://example.com" } } } }, { "op": "CONNECT", "metadata": { "id": "edge_manual_n_fetch_n2", "source": "n_fetch", "target": "n2" } } ] }

适用场景

适用于需要通过 AI 或程序化方式检查 GraphOS 图拓扑、校验节点类型与插件状态、并以事务方式批量修改图的场景。

限制

资料未提供关于收费、价格、平台支持范围或性能效果的信息。默认运行时地址为 http://localhost:3411，若环境不同需自行替换。所有图读取与修改必须通过 GraphOS API 进行，不得直接编辑 *.graph.json 文件。