mind-map/packages/dsh-plugin/lib/tools.js

/**
 * Register mindmap_* tools that call the local mind-map HTTP API.
 * Plain ToolDefinition objects (same style as dsh-ops-cron).
 */

function text(value) {
  return [{ type: 'text', text: String(value ?? '') }]
}

function jsonText(value) {
  return text(typeof value === 'string' ? value : JSON.stringify(value, null, 0))
}

async function callTool(getBase, name, args) {
  const base = getBase?.()
  if (!base) throw new Error('mind-map server is not running')
  const res = await fetch(`${base}/api/tools/${name}`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(args || {}),
  })
  const body = await res.json().catch(() => ({}))
  if (!res.ok) {
    const err = new Error(body.message || body.error || `HTTP ${res.status}`)
    err.code = body.error || 'TOOL_HTTP'
    throw err
  }
  return body
}

const OBJECT = {
  type: 'object',
  additionalProperties: true,
}

const OP_ITEM = {
  type: 'object',
  additionalProperties: true,
  description:
    'Graph op. REQUIRED discriminator field is `type` (NOT `op`). Examples: {"type":"create_node","text":"贾宝玉","parentId":"..."}, {"type":"link","from":"...","to":"...","kind":"relation","label":"木石前盟"}, {"type":"set_pinned","nodeId":"...","pinned":true,"pos":{"x":120,"y":-80}}',
  properties: {
    type: {
      type: 'string',
      description:
        'Op kind: create_node | update_text | link | unlink | set_pinned | set_focus | set_collapsed | set_style_preset | set_edge_label | set_prefs | move_node | delete_node | …',
    },
  },
  required: ['type'],
}

export function mindmapToolDefinitions(getBase, getCanvasIdForSession, setActiveCanvas, queueUiOpen) {
  /** Tools that must open/switch the right-panel canvas. */
  const HARD_OPEN_UI = new Set(['mindmap_create_canvas', 'mindmap_open_canvas'])
  /** Soft reveal: bind session + open tab only if needed (client dedupes). */
  const SOFT_REVEAL_UI = new Set([
    'mindmap_query',
    'mindmap_find',
    'mindmap_find_and_focus',
    'mindmap_get_node',
    'mindmap_get_edge',
    'mindmap_highlight',
    'mindmap_get_spatial_context',
    'mindmap_get_subgraph',
    'mindmap_focus',
    'mindmap_apply_direct',
    'mindmap_propose',
    'mindmap_accept_proposal',
    'mindmap_export',
  ])

  const run = (name) => async (args, exec) => {
    const sessionId = String(
      exec?.agent?.session?.id ||
        exec?.agent?.session?.header?.id ||
        exec?.sessionId ||
        '',
    ).trim()
    const bound =
      typeof getCanvasIdForSession === 'function' && sessionId
        ? getCanvasIdForSession(sessionId)
        : null
    const payload = {
      ...(args || {}),
      canvasId: args?.canvasId || bound || undefined,
      sessionId: sessionId || undefined,
    }
    const body = await callTool(getBase, name, payload)

    if (name === 'mindmap_delete_canvas' && sessionId && typeof setActiveCanvas === 'function') {
      const deleted = args?.canvasId || bound
      const still = getCanvasIdForSession?.(sessionId)
      if (deleted && still === deleted) setActiveCanvas(sessionId, null)
    }

    const cid =
      body?.canvas?.id ||
      payload.canvasId ||
      (typeof getCanvasIdForSession === 'function' && sessionId
        ? getCanvasIdForSession(sessionId)
        : null)

    if (body && body.ok !== false && sessionId && cid) {
      if (HARD_OPEN_UI.has(name) && typeof queueUiOpen === 'function') {
        queueUiOpen(sessionId, {
          canvasId: cid,
          title: body?.canvas?.title || body?.title || args?.title || 'Mind Map',
        })
      } else if (SOFT_REVEAL_UI.has(name)) {
        // Bind session; open UI at most via queue (client skips if already live).
        if (typeof setActiveCanvas === 'function') setActiveCanvas(sessionId, cid)
        if (typeof queueUiOpen === 'function') {
          queueUiOpen(sessionId, {
            canvasId: cid,
            title: body?.canvas?.title || body?.title || args?.title || 'Mind Map',
          })
        }
      }
    }

    return body
  }

  return [
    {
      name: 'mindmap_get_schema',
      description:
        'Return mind-map op schema: valid `type` values, examples (create_node / link / set_pinned), and tool list. Call when unsure about op shape.',
      parameters: { type: 'object', additionalProperties: false, properties: {} },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_get_schema'),
    },
    {
      name: 'mindmap_list_canvases',
      description: 'List mind-map canvases (id + title).',
      parameters: { type: 'object', additionalProperties: false, properties: {} },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_list_canvases'),
    },
    {
      name: 'mindmap_create_canvas',
      description:
        'Create a brand-new mind-map canvas (new id; does NOT overwrite existing canvases), bind it to this chat session, and open it in the 思维导图 tab. Canvas starts visually empty. Top-level nodes: omit parentId.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          title: { type: 'string', description: 'Canvas title, e.g. 红楼梦人物关系' },
          rootText: {
            type: 'string',
            description:
              'Optional internal label / title sync only — there is no visible root node. Prefer title alone.',
          },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_create_canvas'),
    },
    {
      name: 'mindmap_open_canvas',
      description:
        'Open an existing canvas in the 思维导图 tab and bind it as the edit target for this session.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string', description: 'Canvas id from mindmap_list_canvases' },
        },
        required: ['canvasId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_open_canvas'),
    },
    {
      name: 'mindmap_delete_canvas',
      description:
        'Permanently delete a canvas (hard delete). Omit canvasId to delete the currently open canvas.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_delete_canvas'),
    },
    {
      name: 'mindmap_get_spatial_context',
      description:
        'Get spatial harness context for the active mind-map canvas. Always call before inventing node ids.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string', description: 'Omit to use the open/bound canvas.' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_get_spatial_context'),
    },
    {
      name: 'mindmap_find',
      description:
        'Find nodes or edges. searchScope: text|note|tags|description|edge_label|edge_note|all (default text). Edge scopes return {kind:"edge", edgeId, fromText, toText, label}. If ambiguous, ask the user — do not pick silently.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          query: { type: 'string' },
          searchScope: {
            type: 'string',
            enum: [
              'text',
              'note',
              'tags',
              'description',
              'edge_label',
              'edge_note',
              'all',
            ],
            description:
              'Default text. Use edge_label/edge_note for edges; all includes nodes + edges.',
          },
          canvasId: { type: 'string' },
        },
        required: ['query'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_find'),
    },
    {
      name: 'mindmap_find_and_focus',
      description:
        'Find then focus+highlight the best unique match. Edge hits highlight endpoints + edge. If ambiguous, returns candidates without focusing.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          query: { type: 'string' },
          searchScope: {
            type: 'string',
            enum: [
              'text',
              'note',
              'tags',
              'description',
              'edge_label',
              'edge_note',
              'all',
            ],
          },
          canvasId: { type: 'string' },
        },
        required: ['query'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_find_and_focus'),
    },
    {
      name: 'mindmap_export',
      description:
        'Export canvas as json | md | svg. format=png also returns SVG (vector) for agents; use web UI for raster PNG.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          format: { type: 'string', enum: ['json', 'md', 'svg', 'png'] },
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_export'),
    },
    {
      name: 'mindmap_get_subgraph',
      description:
        'Read a subgraph around a node (depth <= 3). rootId: id|@alias|title. edgeKinds: hierarchy (default, tree children) | relation | all — same as mindmap_query. Use relation/all for relationship networks.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          rootId: {
            type: 'string',
            description: 'Node id, @alias, or unique title',
          },
          depth: { type: 'number' },
          edgeKinds: {
            type: 'string',
            enum: ['hierarchy', 'relation', 'all'],
            description:
              'hierarchy = primary-parent children (default); relation|all = undirected neighborhood',
          },
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_get_subgraph'),
    },
    {
      name: 'mindmap_query',
      description:
        'Deterministic graph Q&A primitives (no LLM inventing). op: neighbors|path|stats|orphans|missing_meta. Node refs: id | @alias | unique title. path returns paths[].edges with meta; stats includes longestPath + mostConnected. If empty, say the graph has no such info.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          op: {
            type: 'string',
            enum: ['neighbors', 'path', 'stats', 'orphans', 'missing_meta'],
          },
          node: { type: 'string', description: 'For neighbors: id|@alias|title' },
          nodeId: { type: 'string' },
          from: { type: 'string', description: 'For path: start node' },
          to: { type: 'string', description: 'For path: end node' },
          depth: { type: 'number' },
          maxDepth: { type: 'number' },
          maxHops: {
            type: 'number',
            description:
              'For path: max edges in a path (default 8). Do NOT pass depth:1 — that was neighbors-only.',
          },
          throughRelationNodes: {
            type: 'boolean',
            description:
              'For path: allow multi-hop via intermediate nodes (default true). false = direct edge only.',
          },
          maxPaths: { type: 'number' },
          direction: {
            type: 'string',
            enum: ['out', 'in', 'both'],
            description:
              'neighbors default both; path default both when throughRelationNodes, else out',
          },
          edgeKinds: {
            type: 'string',
            enum: ['all', 'hierarchy', 'relation'],
          },
          canvasId: { type: 'string' },
        },
        required: ['op'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_query'),
    },
    {
      name: 'mindmap_get_node',
      description:
        'Read one node. Default returns id/text/alias/function + full description. Use after Q&A when user asks for details on a cited node.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          nodeId: { type: 'string', description: 'id | @alias | unique title' },
          node: { type: 'string' },
          fields: {
            type: 'array',
            items: {
              type: 'string',
              enum: ['all', 'description', 'note', 'tags', 'links'],
            },
          },
          canvasId: { type: 'string' },
        },
        required: ['nodeId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_get_node'),
    },
    {
      name: 'mindmap_get_edge',
      description:
        'Read one edge by id. Returns from/to texts + label/direction/weight/lineStyle/note. fields: all|label|meta.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          edgeId: { type: 'string' },
          fields: {
            type: 'array',
            items: { type: 'string', enum: ['all', 'label', 'meta'] },
          },
          canvasId: { type: 'string' },
        },
        required: ['edgeId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_get_edge'),
    },
    {
      name: 'mindmap_highlight',
      description:
        'Flash nodes and/or edges on the open canvas (no graph mutation). Use after path/neighbors Q&A. Optional style + ttlMs (default 5000).',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          nodeIds: {
            type: 'array',
            items: { type: 'string' },
            description: 'id | @alias | title',
          },
          edgeIds: { type: 'array', items: { type: 'string' } },
          style: {
            type: 'object',
            additionalProperties: false,
            properties: {
              nodeColor: { type: 'string' },
              nodeGlow: { type: 'boolean' },
              edgeWidth: { type: 'number' },
              edgeColor: { type: 'string' },
            },
          },
          ttlMs: { type: 'number', description: 'Auto-clear ms (500–60000)' },
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_highlight'),
    },
    {
      name: 'mindmap_apply_direct',
      description:
        'Apply low-risk graph ops immediately. Prefer batch_create for trees; relations[] for inline edges; auto_fit after large builds. EACH op MUST have field `type`. Response includes nodeIdMap. Set preview:true for dry-run. High-risk delete_node/move_node need mindmap_propose.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          ops: { type: 'array', items: OP_ITEM },
          summary: { type: 'string' },
          canvasId: { type: 'string' },
          preview: {
            type: 'boolean',
            description: 'If true, simulate apply + layout without persisting',
          },
        },
        required: ['ops'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_apply_direct'),
    },
    {
      name: 'mindmap_propose',
      description:
        'Submit a validated proposal (ops must use `type`). Then mindmap_accept_proposal({proposalId}) to apply. Failures return invalid_op with details — not a silent stale.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          ops: { type: 'array', items: OP_ITEM },
          rationale: { type: 'string' },
          canvasId: { type: 'string' },
        },
        required: ['ops', 'rationale'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_propose'),
    },
    {
      name: 'mindmap_accept_proposal',
      description: 'Accept a pending proposal by id returned from mindmap_propose.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          proposalId: { type: 'string' },
          canvasId: { type: 'string' },
        },
        required: ['proposalId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_accept_proposal'),
    },
    {
      name: 'mindmap_reject_proposal',
      description: 'Reject a pending proposal by id.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          proposalId: { type: 'string' },
        },
        required: ['proposalId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_reject_proposal'),
    },
    {
      name: 'mindmap_focus',
      description: 'Move visual focus to a node.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          nodeId: { type: 'string' },
          canvasId: { type: 'string' },
        },
        required: ['nodeId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_focus'),
    },
    {
      name: 'mindmap_undo',
      description:
        'Undo latest change set (or specific changeSetId). Creates an undo companion that mindmap_redo can reverse.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          changeSetId: { type: 'string' },
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_undo'),
    },
    {
      name: 'mindmap_redo',
      description:
        'Redo after undo: undoes the latest undo-companion change set on the canvas.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_redo'),
    },
    {
      name: 'mindmap_history',
      description:
        'List recent change sets + named snapshots; shows latest undoable/redoable ids.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string' },
          limit: { type: 'number' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_history'),
    },
    {
      name: 'mindmap_snapshot',
      description:
        'Create a named canvas snapshot, or action:"list" to list snapshots.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          canvasId: { type: 'string' },
          name: { type: 'string' },
          action: { type: 'string', enum: ['create', 'list'] },
          limit: { type: 'number' },
        },
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_snapshot'),
    },
    {
      name: 'mindmap_restore_snapshot',
      description: 'Restore canvas to a prior snapshot id from mindmap_snapshot / mindmap_history.',
      parameters: {
        type: 'object',
        additionalProperties: false,
        properties: {
          snapshotId: { type: 'string' },
          canvasId: { type: 'string' },
        },
        required: ['snapshotId'],
      },
      output: { schema: OBJECT, render: (_a, v) => jsonText(v) },
      execute: run('mindmap_restore_snapshot'),
    },
  ]
}

export function registerMindmapTools(
  ctx,
  getBase,
  getCanvasIdForSession,
  setActiveCanvas,
  queueUiOpen,
) {
  const tools = ctx?.tools
  if (!tools || typeof tools.register !== 'function') return () => {}
  const offs = mindmapToolDefinitions(
    getBase,
    getCanvasIdForSession,
    setActiveCanvas,
    queueUiOpen,
  ).map((def) => tools.register(def))
  return () => {
    for (const off of offs) {
      if (typeof off === 'function') off()
    }
  }
}

export function makeMindmapSkill() {
  return {
    name: 'mind-map',
    description:
      'AI 无限画布思维导图：右侧「思维导图」Tab；用 mindmap_* 建图/改图。Ops 必须用 type 字段。',
    whenToUse:
      'User asks for 思维导图 / 关系图 / 梳理人物或家族关系 / Mind Map, OR asks questions about an existing map (路径/依赖/邻居/统计/缺描述).',
    source: 'runtime',
    provider: 'runtime',
    content: `Mind Map workflow (dsh-mind-map):

CRITICAL — op shape:
- Every graph mutation item MUST use discriminator field **type** (NOT op / operation).
- If unsure, call mindmap_get_schema first.
- Prefer **batch_create** for trees (up to 200 nodes) instead of many create_node rounds.
- Valid types include: batch_create, batch_link, create_node, update_text, link, unlink, set_pinned, set_focus, set_collapsed, auto_fit, set_style_preset, set_edge_label, delete_node, move_node, …

Examples:
{"type":"batch_create","nodes":[{"text":"数通","alias":"datacom"},{"text":"交换机","alias":"sw","parentId":"@datacom"},{"text":"AIOps","alias":"aiops","parentId":"@datacom","relations":[{"to":"@restart","label":"触发","kind":"relation"}],"description":{"function":"根因诊断"}},{"text":"自动重启","alias":"restart","parentId":"@datacom"}]}
{"type":"batch_link","edges":[{"from":"@daiyu","to":"@baoyu","kind":"relation","label":"知己"},{"from":"@baoyu","to":"@baochai","kind":"relation","label":"金玉良缘"}]}
{"type":"auto_fit","padding":50}
{"type":"create_node","text":"贾宝玉"}   ← top-level (omit parentId); appears as independent node
{"type":"create_node","text":"贾政","parentId":"<贾宝玉的可见父节点或主题id>"}
{"type":"create_node","text":"AIOps","alias":"aiops","relations":[{"to":"@restart","kind":"relation","label":"触发"}]}
{"type":"link","from":"<黛玉Id>","to":"<宝玉Id>","kind":"relation","label":"木石前盟"}
{"type":"update_text","nodeId":"<id>","text":"新文案"}
{"type":"set_pinned","nodeId":"<id>","pinned":true,"pos":{"x":120,"y":-80}}
{"type":"update_node_meta","nodeId":"@aiops","patch":{"description":{"owner":"SRE","sla":"30s"},"note":"自由文本"}}
{"type":"set_style_preset","nodeId":"@baoyu","stylePreset":"decision"}  ← field is stylePreset (not preset)
{"type":"unlink","from":"@daiyu","to":"@baoyu","kind":"relation"}  ← or edgeId
{"type":"restore_node","nodeId":"<softDeletedId>"}  ← same id after delete_node; also @alias/title of deleted nodes

There is NO visible root node. Canvas title is metadata only. Internally top-level nodes hang under a hidden anchor — agents must never mention or target a root id.

When the user asks to build a map (e.g. 「输出红楼梦人物关系图」):
1. mindmap_create_canvas({ title: "红楼梦人物关系" }) — ALWAYS creates a NEW canvas id (never overwrites an old one). Opens the right tab on that new canvas.
2. mindmap_get_spatial_context — orient on the NEW empty canvas
3. mindmap_apply_direct({ ops: [ {type:"batch_create", nodes:[...]}, {type:"auto_fit"} ] })
4. Keep adding in small batches; never dump a full tree JSON overwrite

If the user asks for another topic later: call mindmap_create_canvas again with the new title. Do NOT reuse the previous canvas unless they explicitly say to continue the same map.
mindmap_list_canvases shows all canvases; mindmap_open_canvas switches the edit target.

Hierarchy vs relation:
- omit parentId = top-level theme/person (siblings look unrelated, which is intended)
- parentId = nest under a visible node
- link kind:"relation" = cross links (人物关系、姻亲等)
- create_node.relations / batch_create[].relations = outgoing graph edges in the same op (not URL bookmarks; those are links[])

Layout:
- Default positions come from auto layout.
- After large batch_create, include {type:"auto_fit"} so the camera frames the map.
- To place manually / avoid overwrite: set_pinned + pos, or create_node with pos (auto-pins).

Propose/accept:
- mindmap_propose validates ops first; then mindmap_accept_proposal({proposalId}).
- Apply failures return error invalid_op (proposal stays pending) — not a fake proposal_stale.
- proposal_stale only means rev drifted > 50 or proposal already finished / missing after restart.

Other tools:
- mindmap_list_canvases / mindmap_open_canvas / mindmap_delete_canvas
- Query/find/highlight also auto-open the 思维导图 tab on the bound canvas (same as create/open)
- mindmap_find — searchScope text|note|tags|description|edge_label|edge_note|all; if ambiguous, ask then mindmap_focus / mindmap_highlight with quickActions[i].args
- mindmap_find_and_focus — unique hit → focus + highlight flash (edges → highlight endpoints)
- mindmap_query — graph Q&A: neighbors|path|stats|orphans|missing_meta (deterministic; cite returned nodes)
- mindmap_get_node / mindmap_get_edge — details for follow-up
- mindmap_highlight — flash path (nodeIds + edgeIds + optional ttlMs/style)
- mindmap_export — format json|md|svg (png→svg for agents; UI has raster PNG)
- mindmap_focus, mindmap_undo, mindmap_redo, mindmap_history
- mindmap_snapshot / mindmap_restore_snapshot — named checkpoints
- mindmap_apply_direct({ preview:true }) — dry-run layout + overlaps, no persist
- mindmap_get_subgraph, mindmap_get_schema
  - get_subgraph: edgeKinds hierarchy (default tree) | relation | all — use relation/all for 关系网络 around a leaf

Graph Q&A workflow:
1. Resolve entities with mindmap_find or @alias (edge labels: searchScope edge_label)
2. Call mindmap_query (never guess paths/relations from memory)
3. If empty/message says no match → answer "图中没有相关信息" — do NOT invent
4. Answer with node names + paths[].edges (label/weight/note); mention citedNodeIds
5. Follow-up details → mindmap_get_node / mindmap_get_edge
6. Visualize → mindmap_highlight({ nodeIds, edgeIds }) after path/neighbors

Examples:
mindmap_find({ query:"高置信", searchScope:"edge_label" })
mindmap_query({ op:"neighbors", node:"@aiops", direction:"out", depth:1 })
mindmap_query({ op:"path", from:"@detect", to:"@knowledge_write", throughRelationNodes:true, maxHops:5, edgeKinds:"relation" })
mindmap_query({ op:"path", from:"@detect", to:"@aiops", throughRelationNodes:false })  // direct edge only
mindmap_query({ op:"stats" })  // connectedComponents + longestPath/mostConnected
mindmap_query({ op:"stats", edgeKinds:"relation" })  // diameter on relation edges only
mindmap_query({ op:"missing_meta" })
mindmap_query({ op:"orphans" })
mindmap_highlight({ nodeIds:["@detect","@aiops"], edgeIds:["e_…"], ttlMs:5000 })

Node refs (P0 — prefer these over raw ids):
{"type":"create_node","text":"AIOps","alias":"aiops"}
{"type":"create_node","text":"重启","parentId":"@aiops"}
{"type":"link","from":"@aiops","to":"重启","kind":"relation","label":"诊断→重启"}
{"type":"link","fromText":"AIOps","toText":"重启","kind":"relation"}
{"type":"batch_link","edges":[{"from":"@daiyu","to":"@baoyu","kind":"relation","label":"知己"},{"from":"@baoyu","to":"@baochai","kind":"relation","label":"金玉良缘"}]}
apply_direct returns nodeIdMap: { "AIOps":"n_…", "@aiops":"n_…" }

Node/edge meta extras:
- update_node_meta patch: description (JSON object; put a short "function" field for Q&A), accentColor, icon, alias, note
- update_edge_meta patch: weight 1-5, lineStyle solid|dashed|dotted, direction forward|both|none
- Prefer batch_create for trees; relations[] for inline edges; batch_link for bulk edges later; auto_fit after big builds

Rules:
1. Always create or open a canvas BEFORE apply/propose.
2. Never invent node ids; use find or create_node results. Never ask for / use a root node id — there is no visible root.
3. Prefer batch_create (or many small ops) over one giant rewrite of unrelated topics.
4. Always use type, never op.
5. Top-level siblings: omit parentId on each create_node.
6. For questions about the map, use mindmap_query first; never fabricate graph facts.`,
  }
}