graph-management

GraphOS 技能：graph-management

通过以 HTTP 为先的 API 读取和修改 GraphOS 图的 AI 可操作协议。

适用场景

• 检查图结构、节点关系和所选节点的上下文。
• 在写入操作前验证可用的节点类型。
• 类型架构似乎缺失时，检查插件运行状态。
• 以事务式行为应用一致的批量修改。

运行时基础 URL

默认本地运行时：

• http://localhost:3411

如果你的环境使用不同的主机或端口，请相应替换基础 URL。

Opencode 服务配置

GraphOS 在属性侧边栏中包含一个 AI 助手面板，该面板连接到 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 助手用法

1. 启动 opencode：opencode（TUI 模式）或 opencode serve
2. 启动 GraphOS：npm run dev
3. 在图画布上选择一个节点
4. 在属性面板中，滚动到最底部的 AI 助手 部分
5. 点击 生成，自动创建包含节点 ID、类型和属性的提示词
6. 根据需要编辑提示词，然后点击 在终端中运行（或按 Cmd+Enter）

助手会将任务发送到 opencode 终端执行：

• 终端模式（默认）：使用 tui.appendPrompt + tui.submitPrompt 将任务推送到 opencode TUI 中，并在其中完整显示执行过程。如果没有连接 TUI，则回退到 session.prompt。
• 任务会在 opencode 终端会话中显示并执行，所有工具调用和响应都会在其中可见。

API 参考

get_graph_description

获取完整的图快照，用于规划和验证。

• 方法：GET
• 路径：/api/graph/description
• 查询参数：
  • graphId?: string
• 成功响应包含：
  • graph：id、name、nodeCount、edgeCount、rootNodeIds、leafNodeIds、selectedNodeId
  • nodes：适合 AI 使用的节点描述
  • edges：包含边 ID 的边列表
  • adjacency：每个节点的父节点／子节点 ID
  • aiSummary：自然语言摘要
• 常见错误：
  • 如果找不到图，则返回 404

get_graph_node

获取一个焦点节点及其局部上下文（父节点和子节点）。

• 方法：GET
• 路径：/api/graph/node
• 查询参数：
  • graphId?: string
  • nodeId?: string
• 行为：
  • 如果省略 nodeId，服务端会回退到图中同步的所选节点
• 成功响应包含：
  • graph：id、name、selectedNodeId
  • selectedNode
  • parentNodes
  • childNodes
  • aiSummary：焦点元数据 + naturalLanguage
• 常见错误：
  • 如果缺少 nodeId 且不存在同步的所选节点，则返回 400
  • 如果图或节点不存在，则返回 404

get_available_node_types

列出插件注册的节点类型架构。

• 方法：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?: string
  • ops: Operation[]

操作架构：

• 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 }

注意事项：

• 节点验证依据已注册的节点类型架构执行
• CONNECT 要求源节点和目标节点均存在
• 拒绝重复的节点 ID 和重复的边
• DISCONNECT 使用边 ID，通常为 edge_

成功响应包括：

• success、appliedCount、errorCount
• applied: string[]
• errors: { op, index, reason }[]
• 更新后的图、节点和边
• aiSummary

流程

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

1. 调用 get_available_node_types 了解架构约束。
2. 调用 get_graph_description 获取完整拓扑。
3. 如果仅操作某个节点区域，调用 get_graph_node 获取局部上下文。

完成检查：

• 所需的节点类型均已具备。
• 已确定确切的源/目标 ID 和预期变更。

步骤 2：规划事务

1. 构建一个包含所有相关操作的 apply_graph_transaction 请求。
2. 按依赖关系排列操作（先创建再连接，先断开连接再删除）。
3. 保持 ID 稳定且确定，以便重试时结果一致。

决策要点：

• 如果缺少某种节点类型，重试写入前先检查 get_plugins。
• 如果编辑可能导致数据丢失，仅限于预期范围内的操作。

完成检查：

• 事务包含所有必需的操作，且没有多余的修改。

步骤 3：应用并验证

1. 提交 apply_graph_transaction。
2. 检查响应中的 applied 和 errors。
3. 重新运行 get_graph_description，验证变更后的状态。

决策要点：

• 如果部分成功，仅重试失败的操作意图，不要重放整个批次。
• 如果出现验证错误，先修正请求内容，使其符合节点架构，再重试。

完成检查：

• 图拓扑符合预期的变更后状态。
• 没有未解决的关键错误。

安全规则

• 优先采用一个连贯的事务，而不是多次微小调用。
• 提交前，根据节点类型要求验证节点属性请求内容。
• 对于破坏性更新，先检查当前图，并且只包含预期的操作。
• 将部分成功视为正常情况：检查 errors，并且只重试失败的操作意图。
• 切勿直接编辑 *.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" } } ] }