@uzooai/anime-ai-cli 0.0.0-stage → 0.5.0

package/src/graph.js

@@ -0,0 +1,431 @@
+import crypto from 'node:crypto'
+import { isDeepStrictEqual as same } from 'node:util'
+import { syncGroupMemberships } from './group-membership.js'
+import { scopedCanvas } from './materials.js'
+import { segment, generationExtra, validateGeneration } from './workflows.js'
+import {
+  generationModes as modes,
+  normalizeMode,
+  collectGenerationSources,
+  buildGenerationRequest,
+  referenceMapping
+} from './generation-input.js'
+export function nodeKind(node) {
+  const e = node?.data?.extra || {}
+  if (e.repaint?.role === 'split-detail') return 'detail'
+  if (e.video_remake || e.clip_redraw) return 'video'
+  if (node?.type === 'video_repain_begain') return 'entry'
+  if (node?.type?.endsWith('_upload') || e.node_kind === 'asset') return 'asset'
+  return node?.type
+}
+export function sourceType(node) {
+  const kind = nodeKind(node)
+  if (['entry', 'detail'].includes(kind)) return ''
+  return kind === 'asset'
+    ? node.data?.mediaType || node.data?.segment_type || node.type.replace('_upload', '')
+    : kind
+}
+export function connectionReason(source, target, nodes, edges, catalog) {
+  if (!source || !target) return '节点不存在'
+  if (source.id === target.id) return '不能连接自身'
+  if (
+    ['entry', 'detail'].includes(nodeKind(source)) ||
+    ['entry', 'detail'].includes(nodeKind(target))
+  )
+    return '该端口仅供真实流程使用'
+  if (edges.some((e) => e.source === source.id && e.target === target.id)) return '连线已存在'
+  if (edges.some((e) => e.target === source.id && e.source === target.id)) return '反向连线已存在'
+  const targetKind = nodeKind(target),
+    media = sourceType(source)
+  const accepts = {
+    text: ['text', 'image', 'video', 'audio'],
+    image: ['text', 'image'],
+    video: ['text', 'image', 'video', 'audio'],
+    audio: ['text']
+  }
+  if (!accepts[targetKind]?.includes(media)) return '输出与输入类型不兼容'
+  if (media === 'audio' && targetKind !== 'video') return '音频仅能连接视频生成节点'
+  if (targetKind === 'audio') return ''
+  const model = catalog.find(
+    (m) => m.label === target.data?.model_name && m.content_type === targetKind
+  )
+  if (!model || model.member_locked) return '请先选择当前空间可用的目标模型'
+  if (targetKind === 'text') {
+    if (media === 'image' && model.image_understanding !== true) return '目标文本模型不支持图片理解'
+    if (media === 'video' && model.video_understanding !== true) return '目标文本模型不支持视频理解'
+    return ''
+  }
+  const inputs = [
+    ...edges
+      .filter((e) => e.target === target.id)
+      .map((e) => sourceType(nodes.find((n) => n.id === e.source))),
+    media
+  ].filter(Boolean)
+  const compatible = (model.generation_modes || []).some((mode) => {
+    const rule = modes[normalizeMode(mode)]
+    return (
+      rule &&
+      inputs.every((t) => rule[0].includes(t)) &&
+      (!rule[1].length || rule[1].some((t) => inputs.includes(t)))
+    )
+  })
+  if (
+    targetKind === 'video' &&
+    inputs.includes('audio') &&
+    model.audio_reference_requires_visual === true &&
+    !inputs.some((t) => t === 'image' || t === 'video')
+  )
+    return '音频参考需要至少一个图片或视频输入'
+  for (const type of ['image', 'video', 'audio']) {
+    const max =
+      model[`max_${type}_references`] ?? (type === 'image' ? model.max_reference_count : undefined)
+    if (Number.isFinite(max) && inputs.filter((t) => t === type).length > max)
+      return `超出模型 ${type} 参考数量限制`
+  }
+  if (
+    Number.isFinite(model.max_reference_count) &&
+    inputs.filter((t) => t !== 'text').length > model.max_reference_count
+  )
+    return '超出模型参考素材总数量限制'
+  return compatible ? '' : '目标模型不支持当前上游类型组合'
+}
+const groupsOf = (doc) => {
+  const groups = doc.meta?.canvas_groups ?? []
+  if (!Array.isArray(groups)) throw new Error('分组快照无效')
+  return groups
+}
+export async function save(client, doc, changes) {
+  if (
+    !Number.isSafeInteger(doc.version) ||
+    !Array.isArray(doc.nodes) ||
+    !Array.isArray(doc.edges) ||
+    !doc.meta ||
+    !doc.viewport ||
+    typeof doc.name !== 'string'
+  )
+    throw new Error('画布快照不完整')
+  const body = {
+    version: doc.version,
+    name: doc.name,
+    viewport: doc.viewport,
+    nodes: doc.nodes,
+    edges: doc.edges,
+    meta: doc.meta,
+    ...changes
+  }
+  let result
+  try {
+    result = await client.raw(
+      `/canvas/docs/${segment(doc.id)}`,
+      { method: 'PUT', body },
+      { retry: false }
+    )
+  } catch (error) {
+    if (error.status === 409 || error.apiCode === 3002)
+      throw new Error('画布版本冲突；先读回核对，不自动覆盖')
+    throw new Error('画布保存结果未确认；先 canvas get 核对，不自动重放', { cause: error })
+  }
+  if (
+    result.id !== doc.id ||
+    result.version <= doc.version ||
+    !Array.isArray(result.nodes) ||
+    !Array.isArray(result.edges)
+  )
+    throw new Error('保存响应不完整；先读回核对')
+  return result
+}
+export function layoutNodes(nodes, mode, origin) {
+  if (!['horizontal', 'vertical', 'grid'].includes(mode))
+    throw new Error('layout 必须为 horizontal/vertical/grid')
+  const cols =
+    mode === 'horizontal'
+      ? nodes.length
+      : mode === 'vertical'
+        ? 1
+        : Math.ceil(Math.sqrt(nodes.length))
+  const widths = Array(cols).fill(0),
+    heights = Array(Math.ceil(nodes.length / cols)).fill(0)
+  nodes.forEach((n, i) => {
+    widths[i % cols] = Math.max(widths[i % cols], n.width || 300)
+    heights[Math.floor(i / cols)] = Math.max(heights[Math.floor(i / cols)], n.height || 260)
+  })
+  return nodes.map((n, i) => ({
+    ...n,
+    position: {
+      x: origin.x + 40 + widths.slice(0, i % cols).reduce((a, b) => a + b + 120, 0),
+      y: origin.y + 40 + heights.slice(0, Math.floor(i / cols)).reduce((a, b) => a + b + 80, 0)
+    }
+  }))
+}
+export async function renameGraphGroup(client, args, confirmed = false) {
+  if (!args || typeof args !== 'object' || Array.isArray(args) ||
+      Object.keys(args).some(k => !['doc_id', 'space', 'team_uid', 'group_id', 'name', 'expected_version'].includes(k)))
+    throw new Error('组重命名输入仅支持doc_id/space/team_uid/group_id/name/expected_version')
+  if (typeof args.group_id !== 'string' || !args.group_id.trim() ||
+      typeof args.name !== 'string' || !args.name.trim()) throw new Error('分组ID和名称不可为空')
+  if (typeof args.doc_id !== 'string' || !args.doc_id.trim()) throw new Error('doc_id必须为非空字符串')
+  if (args.expected_version !== undefined && (!Number.isSafeInteger(args.expected_version) || args.expected_version < 1))
+    throw new Error('expected_version必须为正整数')
+  const doc = await scopedCanvas(client, args.doc_id, args.space, args.team_uid)
+  if (!Array.isArray(doc.nodes) || !Array.isArray(doc.edges) ||
+      !doc.meta || typeof doc.meta !== 'object' || Array.isArray(doc.meta) ||
+      !doc.viewport || typeof doc.viewport !== 'object' || Array.isArray(doc.viewport) ||
+      typeof doc.name !== 'string') throw new Error('画布快照不完整，停止重命名')
+  if (!Array.isArray(doc.meta.canvas_groups) || doc.meta.canvas_groups.some(g =>
+      !g || typeof g !== 'object' || typeof g.id !== 'string' || !g.id ||
+      typeof g.label !== 'string' || !Array.isArray(g.nodeIds)) ||
+      new Set(doc.meta.canvas_groups.map(g => g.id)).size !== doc.meta.canvas_groups.length)
+    throw new Error('分组快照不完整或ID重复')
+  const groups = groupsOf(doc), matches = groups.filter(g => g.id === args.group_id)
+  if (matches.length !== 1) throw new Error('分组不存在或ID重复')
+  const group = matches[0]
+  if (group.repaint || group.video_remake || group.clip_redraw) throw new Error('派生流程分组请按专用流程操作')
+  if (!Number.isSafeInteger(doc.version) || doc.version < 1) throw new Error('画布版本无效')
+  if (args.expected_version !== undefined && doc.version !== args.expected_version)
+    throw new Error('画布已变化；重新预览，不自动采用最新版本覆盖')
+  const name = args.name.trim()
+  const preview = { doc_id: doc.id, group_id: group.id, before_name: group.label, name,
+    expected_version: doc.version, changed: name !== group.label, canvas_written: false,
+    preserves: ['nodes', 'edges', 'positions', 'references', 'other_groups'], generation_submitted: false }
+  if (!confirmed) return preview
+  if (args.expected_version === undefined) throw new Error('执行组重命名必须提供预览返回的expected_version')
+  if (!preview.changed) return preview
+  const saved = await save(client, doc, { meta: { ...doc.meta, canvas_groups:
+    groups.map(g => g.id === group.id ? { ...g, label: name } : g) } })
+  let current
+  try { current = await scopedCanvas(client, args.doc_id, args.space, args.team_uid) }
+  catch (cause) { throw new Error('重命名已尝试保存但读回未确认；先canvas get核对，不自动重放', { cause }) }
+  const actual = current.meta?.canvas_groups?.filter(g => g?.id === group.id)
+  if (!Number.isSafeInteger(current.version) || current.version < saved.version ||
+      actual?.length !== 1 || actual[0].label !== name)
+    throw new Error('重命名保存后读回不一致；保留当前画布，不自动重放')
+  return { ...preview, version: current.version, canvas_written: true, rename_verified: true }
+}
+export async function ungroupGraph(client, args, confirmed = false) {
+  if (!args || typeof args !== 'object' || Array.isArray(args) ||
+      Object.keys(args).some(k => !['doc_id','space','team_uid','group_id','expected_version'].includes(k)) ||
+      !['doc_id','group_id'].every(k => typeof args[k] === 'string' && args[k].trim()))
+    throw new Error('拆组输入需要doc_id/space/team_uid/group_id，可选expected_version')
+  if (args.expected_version !== undefined && (!Number.isSafeInteger(args.expected_version) || args.expected_version < 1))
+    throw new Error('expected_version必须为正整数')
+  const doc = await scopedCanvas(client, args.doc_id, args.space, args.team_uid)
+  if (!Number.isSafeInteger(doc.version) || doc.version < 1 || !Array.isArray(doc.nodes) ||
+      !Array.isArray(doc.edges) || !doc.meta || Array.isArray(doc.meta) || !doc.viewport || typeof doc.name !== 'string')
+    throw new Error('画布快照不完整')
+  const groups = groupsOf(doc)
+  if (groups.some(g => !g || typeof g.id !== 'string' || !Array.isArray(g.nodeIds)) ||
+      new Set(groups.map(g=>g.id)).size !== groups.length ||
+      new Set(doc.nodes.map(n=>n.id)).size !== doc.nodes.length) throw new Error('分组或节点快照无效')
+  const target = groups.find(g=>g.id === args.group_id)
+  if (!target) throw new Error('分组不存在；先读回核对，不重复执行')
+  const protectedGroup = g => g.repaint || g.video_remake || g.clip_redraw
+  if (protectedGroup(target)) throw new Error('派生流程分组不可普通拆组')
+  if (args.expected_version !== undefined && args.expected_version !== doc.version) throw new Error('画布已变化；重新预览')
+  const state = { nodes: doc.nodes, groups: structuredClone(groups.filter(g=>g.id !== target.id)) }
+  syncGroupMemberships(state)
+  const changed = state.groups.filter(g=>!same(g,groups.find(old=>old.id===g.id)))
+  if (changed.some(protectedGroup)) throw new Error('拆组将影响派生流程组成员，停止')
+  const preview = {doc_id:doc.id,group_id:target.id,removed_group_name:target.label,
+    node_ids:target.nodeIds,expected_version:doc.version,canvas_written:false,generation_submitted:false,
+    membership_changes:changed.map(g=>({group_id:g.id,before:groups.find(old=>old.id===g.id).nodeIds,
+      after:g.nodeIds,exited_before:groups.find(old=>old.id===g.id).exitedNodeIds||[],exited_after:g.exitedNodeIds||[]})),
+    preserves:['nodes','positions','edges','references']}
+  if (!confirmed) return preview
+  if (args.expected_version === undefined) throw new Error('执行拆组须提供预览expected_version')
+  const meta = {...doc.meta}
+  if (state.groups.length) meta.canvas_groups = state.groups
+  else delete meta.canvas_groups
+  const saved = await save(client,doc,{meta})
+  let current
+  try { current = await scopedCanvas(client,args.doc_id,args.space,args.team_uid) }
+  catch(cause) { throw new Error('拆组已尝试保存，读回未确认；不自动重放',{cause}) }
+  if (!Number.isSafeInteger(current.version) || current.version < saved.version ||
+      !same(current.meta,meta) || !same(current.nodes,doc.nodes) || !same(current.edges,doc.edges) ||
+      !same(current.viewport,doc.viewport) || current.name !== doc.name)
+    throw new Error('拆组保存后内容已变化或读回不一致；不自动重放')
+  return {...preview,canvas_written:true,ungroup_verified:true,version:current.version}
+}
+export async function graphWrite(client, args) {
+  if (!args || Array.isArray(args) || typeof args !== 'object')
+    throw new Error('图操作必须为 JSON 对象')
+  const fields = [
+    'action',
+    'doc_id',
+    'space',
+    'team_uid',
+    'node_ids',
+    'position',
+    'layout',
+    'name',
+    'group_id',
+    'target_node_id',
+    'source_node_id'
+  ]
+  if (Object.keys(args).some((k) => !fields.includes(k))) throw new Error('图操作包含不支持的字段')
+  const { doc_id: docId, space, team_uid: teamUid } = args
+  const doc = await scopedCanvas(client, docId, space, teamUid)
+  const groups = groupsOf(doc)
+  if (args.action === 'group-create' || args.action === 'layout') {
+    if (
+      !Array.isArray(args.node_ids) ||
+      args.node_ids.length < 2 ||
+      new Set(args.node_ids).size !== args.node_ids.length ||
+      args.node_ids.some((id) => typeof id !== 'string')
+    )
+      throw new Error('至少提供两个不重复的 node_ids')
+    const selected = args.node_ids.map((id) => doc.nodes.find((n) => n.id === id))
+    if (selected.some((n) => !n)) throw new Error('分组成员不存在')
+    if (
+      selected.some(
+        (n) => n.data?.extra?.repaint || n.data?.extra?.video_remake || n.data?.extra?.clip_redraw
+      )
+    )
+      throw new Error('派生流程节点不能通过普通分组操作重组')
+    // Existing groups and workflow layout are not silently reassigned.
+    if (groups.some((g) => g.nodeIds?.some((id) => args.node_ids.includes(id))))
+      throw new Error('选中节点已有分组；停止以保留原组')
+    const origin = args.position || {
+      x: Math.min(...selected.map((n) => n.position.x)) - 40,
+      y: Math.min(...selected.map((n) => n.position.y)) - 40
+    }
+    if (!Number.isFinite(origin.x) || !Number.isFinite(origin.y)) throw new Error('position 无效')
+    const placed = layoutNodes(selected, args.layout || 'grid', origin)
+    const nodes = doc.nodes.map((n) => placed.find((p) => p.id === n.id) || n)
+    let group
+    if (args.action === 'group-create') {
+      if (typeof args.name !== 'string' || !args.name.trim()) throw new Error('分组名称不可为空')
+      const id = args.group_id || 'group-' + crypto.randomUUID()
+      if (typeof id !== 'string' || groups.some((g) => g.id === id))
+        throw new Error('分组 ID 无效或已存在；先读回核对')
+      group = {
+        id,
+        label: args.name,
+        nodeIds: args.node_ids,
+        position: origin,
+        size: {
+          width: Math.max(...placed.map((n) => n.position.x + (n.width || 300))) - origin.x + 40,
+          height: Math.max(...placed.map((n) => n.position.y + (n.height || 260))) - origin.y + 40
+        },
+        padding: 40,
+        color: '#2c2c2c',
+        borderColor: 'rgba(255, 255, 255, 0.28)'
+      }
+    }
+    const saved = await save(client, doc, {
+      nodes,
+      ...(group ? { meta: { ...doc.meta, canvas_groups: [group, ...groups] } } : {})
+    })
+    return { doc_id: docId, version: saved.version, group, node_ids: args.node_ids }
+  }
+  if (!['connect', 'group-connect'].includes(args.action)) throw new Error('未知图操作')
+  const target = doc.nodes.find((n) => n.id === args.target_node_id)
+  if (!target) throw new Error('目标节点不存在')
+  const group = args.action === 'group-connect' ? groups.find((g) => g.id === args.group_id) : null
+  if (args.action === 'group-connect' && !group) throw new Error('分组不存在')
+  if (group?.repaint) throw new Error('转绘流程分组请按专用流程操作')
+  const ids = group ? group.nodeIds : [args.source_node_id]
+  if (!Array.isArray(ids) || ids.some((id) => !doc.nodes.some((n) => n.id === id)))
+    throw new Error('源节点或组成员不存在')
+  const catalog = await client.raw(
+    '/canvas/models' + (doc.team_uid ? '?team_uid=' + segment(doc.team_uid) : '')
+  )
+  if (!Array.isArray(catalog.items)) throw new Error('模型目录无效')
+  const edges = [...doc.edges],
+    connected = [],
+    skipped = []
+  for (const id of ids) {
+    const source = doc.nodes.find((n) => n.id === id)
+    const reason = connectionReason(source, target, doc.nodes, edges, catalog.items)
+    if (reason) {
+      skipped.push({ node_id: id, reason })
+      continue
+    }
+    edges.push({
+      id: 'edge-' + crypto.randomUUID(),
+      source: id,
+      target: target.id,
+      sourceHandle: '',
+      targetHandle: '',
+      type: 'default',
+      animated: false
+    })
+    connected.push(id)
+  }
+  let nodes = doc.nodes
+  if (connected.length && ['image', 'video'].includes(nodeKind(target))) {
+    const inputs = edges
+      .filter((e) => e.target === target.id)
+      .map((e) => sourceType(doc.nodes.find((n) => n.id === e.source)))
+      .filter(Boolean)
+    const model = catalog.items.find(
+      (m) => m.label === target.data?.model_name && m.content_type === nodeKind(target)
+    )
+    const supported = model.generation_modes.filter(
+      (mode) =>
+        modes[mode] &&
+        inputs.every((t) => modes[mode][0].includes(t)) &&
+        (!modes[mode][1].length || modes[mode][1].some((t) => inputs.includes(t)))
+    )
+    const current = target.data?.extra?.generation_mode
+    const mode = supported.includes(current) ? current : supported[0]
+    nodes = doc.nodes.map((n) =>
+      n.id === target.id
+        ? { ...n, data: { ...n.data, extra: { ...n.data.extra, generation_mode: mode } } }
+        : n
+    )
+  }
+  const result = connected.length ? await save(client, doc, { edges, nodes }) : doc
+  return { doc_id: docId, version: result.version, connected, skipped }
+}
+export async function prepareGeneration(client, { docId, nodeId, space, teamUid }) {
+  const doc = await scopedCanvas(client, docId, space, teamUid)
+  const node = doc.nodes.find((n) => n.id === nodeId)
+  const kind = nodeKind(node)
+  if (
+    !['text', 'image', 'video'].includes(kind) ||
+    node?.data?.extra?.video_remake ||
+    node?.data?.extra?.repaint ||
+    node?.data?.extra?.clip_redraw
+  )
+    throw new Error('仅支持普通文本/图片/视频生成；派生流程须用专用编排')
+  const models = await client.raw(
+    '/canvas/models' + (doc.team_uid ? '?team_uid=' + segment(doc.team_uid) : '')
+  )
+  const model = models.items?.find(
+    (m) => m.label === node.data?.model_name && m.content_type === kind && !m.member_locked
+  )
+  if (!model) throw new Error('节点缺少当前空间可用模型')
+  // Validate actual incoming edges before merging persistent (possibly disconnected) references.
+  for (const edge of doc.edges.filter((e) => e.target === nodeId)) {
+    const source = doc.nodes.find((n) => n.id === edge.source)
+    const reason = connectionReason(
+      source,
+      node,
+      doc.nodes,
+      doc.edges.filter((e) => e !== edge && !(e.source === edge.source && e.target === nodeId)),
+      models.items
+    )
+    if (reason) throw new Error(`上游 ${edge.source} 不合规：${reason}`)
+  }
+  generationExtra(kind, node.data.extra || {}, { fromNode: true })
+  if (Object.hasOwn(node.data, 'generate_audio') || Object.hasOwn(node.data, 'generateAudio'))
+    throw new Error('前端视频节点没有声音开关，CLI 不支持 generate_audio；请先核对节点参数')
+  const inputs = collectGenerationSources(doc, node)
+  const { request, sources } = buildGenerationRequest(doc, node, model, inputs)
+  validateGeneration(request)
+  return {
+    prepared: true,
+    reference_mapping: referenceMapping(request, sources),
+    reference_mapping_scope: 'client_request_before_backend_resolution',
+    wallet: { space, team_uid: doc.team_uid || null },
+    request,
+    source_node_ids: sources.map((source) => source.id),
+    references: sources.map(({ id, title, mediaType, url, text }) => ({
+      id,
+      title,
+      mediaType,
+      url,
+      text
+    }))
+  }
+}

package/src/group-edit.js

@@ -0,0 +1,53 @@
+import {isDeepStrictEqual as same} from 'node:util'
+import {scopedCanvas} from './materials.js'
+import {save} from './graph.js'
+import {syncGroupMemberships} from './group-membership.js'
+import {calculateGroupLayout} from './group-layout.js'
+
+export async function editGraphGroup(client,input,action,confirmed=false){
+  const fields=['doc_id','space','team_uid','group_id','expected_version',...(action==='move'?['position']:action==='resize'?['position','size']:action==='layout'?['layout']:[])]
+  const point=p=>p&&typeof p==='object'&&!Array.isArray(p)&&Number.isFinite(p.x)&&Number.isFinite(p.y)
+  if(!['move','resize','layout'].includes(action)||!input||typeof input!=='object'||Array.isArray(input)||Object.keys(input).some(k=>!fields.includes(k))||!['doc_id','group_id'].every(k=>typeof input[k]==='string'&&input[k].trim()))throw Error('分组编辑输入无效')
+  if(action==='move'&&!point(input.position))throw Error('移动必须指定position')
+  if(action==='resize'&&(!input.size||!Number.isFinite(input.size.width)||!Number.isFinite(input.size.height)||input.size.width<120||input.size.height<72||(input.position!==undefined&&!point(input.position))))throw Error('组框size须至少120×72，可选有效position')
+  if(action==='layout'&&!['horizontal','vertical','grid'].includes(input.layout))throw Error('layout须为horizontal/vertical/grid')
+  if(input.expected_version!==undefined&&(!Number.isSafeInteger(input.expected_version)||input.expected_version<1))throw Error('expected_version无效')
+  const doc=await scopedCanvas(client,input.doc_id,input.space,input.team_uid)
+  const groups=doc.meta?.canvas_groups
+  if(!Number.isSafeInteger(doc.version)||doc.version<1||!Array.isArray(doc.nodes)||!Array.isArray(doc.edges)||!Array.isArray(groups)||!doc.viewport||typeof doc.name!=='string'||new Set(doc.nodes.map(n=>n.id)).size!==doc.nodes.length||new Set(groups.map(g=>g?.id)).size!==groups.length)throw Error('画布或分组快照不完整')
+  if(input.expected_version!==undefined&&input.expected_version!==doc.version)throw Error('画布已变化，重新预览')
+  const protectedItem=item=>item?.repaint||item?.videoRemake||item?.clipRedraw||item?.draftFinalizeGeneration||item?.video_remake||item?.clip_redraw||item?.draft_finalize||item?.extra?.repaint||item?.extra?.video_remake||item?.extra?.clip_redraw||item?.extra?.draft_finalize
+  const old=groups.find(g=>g.id===input.group_id)
+  if(!old||protectedItem(old)||!Array.isArray(old.nodeIds)||!point(old.position)||!old.size||!Number.isFinite(old.size.width)||!Number.isFinite(old.size.height))throw Error('普通分组不存在或结构/派生类型不支持')
+  const ids=new Set(old.nodeIds),members=doc.nodes.filter(n=>ids.has(n.id))
+  if(members.length!==ids.size||members.some(n=>protectedItem(n.data)||!point(n.position)))throw Error('组内成员缺失或派生节点不可普通编辑')
+  const state={nodes:structuredClone(doc.nodes),groups:structuredClone(groups)},group=state.groups.find(g=>g.id===old.id)
+  if(action==='move'){
+    const position={x:Math.round(input.position.x),y:Math.round(input.position.y)},dx=position.x-old.position.x,dy=position.y-old.position.y
+    group.position=position
+    for(const n of state.nodes)if(ids.has(n.id))n.position={x:Math.round(n.position.x+dx),y:Math.round(n.position.y+dy)}
+  }else if(action==='resize'){
+    group.size={width:input.size.width,height:input.size.height}
+    if(input.position)group.position={x:input.position.x,y:input.position.y}
+  }else{
+    const layout=calculateGroupLayout(group,members,input.layout)
+    if(!layout)throw Error('空组无法重排')
+    group.size=layout.size
+    for(const n of state.nodes){const p=layout.positions.find(p=>p.id===n.id);if(p)n.position={x:Math.round(p.position.x),y:Math.round(p.position.y)}}
+  }
+  syncGroupMemberships(state)
+  const changedGroups=state.groups.filter(g=>!same(g,groups.find(old=>old.id===g.id)))
+  if(changedGroups.some(protectedItem))throw Error('操作会改变派生组归属，停止')
+  const meta={...doc.meta,canvas_groups:state.groups}
+  const preview={doc_id:doc.id,group_id:old.id,action,expected_version:doc.version,before_group:old,after_group:group,
+    node_moves:state.nodes.filter(n=>!same(n.position,doc.nodes.find(s=>s.id===n.id).position)).map(n=>({node_id:n.id,before:doc.nodes.find(s=>s.id===n.id).position,after:n.position})),
+    membership_changes:changedGroups.map(g=>({group_id:g.id,before:groups.find(o=>o.id===g.id).nodeIds,after:g.nodeIds,exited_before:groups.find(o=>o.id===g.id).exitedNodeIds||[],exited_after:g.exitedNodeIds||[]})),
+    canvas_written:false,generation_submitted:false,changed:!same(state.nodes,doc.nodes)||!same(meta,doc.meta)}
+  if(!confirmed)return preview
+  if(input.expected_version===undefined)throw Error('执行必须提供预览expected_version')
+  if(!preview.changed)return {...preview,group_edit_verified:true}
+  const saved=await save(client,doc,{nodes:state.nodes,meta})
+  let after;try{after=await scopedCanvas(client,input.doc_id,input.space,input.team_uid)}catch(cause){throw Error('分组保存后读回未确认，不自动重放',{cause})}
+  if(!Number.isSafeInteger(after.version)||after.version<saved.version||!same(after.nodes,state.nodes)||!same(after.meta,meta)||!same(after.edges,doc.edges)||!same(after.viewport,doc.viewport)||after.name!==doc.name)throw Error('分组编辑读回不一致，不自动重放')
+  return {...preview,canvas_written:true,version:after.version,group_edit_verified:true}
+}

package/src/group-layout.js

@@ -0,0 +1,113 @@
+// Independent CLI group layout contract, checked against frontend groupLayout.js.
+const DEFAULT_NODE_WIDTH = 200
+const DEFAULT_NODE_HEIGHT = 100
+export const GROUP_LAYOUT_PADDING = 40
+const DEFAULT_HORIZONTAL_GAP = 120
+const DEFAULT_VERTICAL_GAP = 80
+
+function spacing(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) ? Math.max(number, 0) : fallback
+}
+
+function getNodeSize(node) {
+  const width = Number(node?.computedWidth) || Number(node?.width)
+  const height = Number(node?.computedHeight) || Number(node?.height)
+  return {
+    width: Number.isFinite(width) && width > 0 ? width : DEFAULT_NODE_WIDTH,
+    height: Number.isFinite(height) && height > 0 ? height : DEFAULT_NODE_HEIGHT,
+  }
+}
+
+function sortNodes(nodes, mode) {
+  return [...nodes].sort((left, right) => {
+    const leftX = Number(left?.position?.x) || 0
+    const leftY = Number(left?.position?.y) || 0
+    const rightX = Number(right?.position?.x) || 0
+    const rightY = Number(right?.position?.y) || 0
+    if (mode === 'horizontal') return leftX - rightX || leftY - rightY
+    return leftY - rightY || leftX - rightX
+  })
+}
+
+export function calculateGroupLayout(group, nodes, mode, options = {}) {
+  const sourceNodes = Array.isArray(nodes) ? nodes.filter(Boolean) : []
+  if (!group || !sourceNodes.length) return null
+  if (!['horizontal', 'vertical', 'grid'].includes(mode)) return null
+
+  const padding = spacing(
+    options.padding ?? group.padding ?? GROUP_LAYOUT_PADDING,
+    GROUP_LAYOUT_PADDING
+  )
+  // Horizontal ports need more room for curves than rows need for titles and controls.
+  const gapX = spacing(
+    options.gapX ?? options.gap ?? DEFAULT_HORIZONTAL_GAP,
+    DEFAULT_HORIZONTAL_GAP
+  )
+  const gapY = spacing(options.gapY ?? options.gap ?? DEFAULT_VERTICAL_GAP, DEFAULT_VERTICAL_GAP)
+  const originX = Number(group.position?.x) || 0
+  const originY = Number(group.position?.y) || 0
+  const orderedNodes = sortNodes(sourceNodes, mode)
+  const sizes = orderedNodes.map(getNodeSize)
+  const positions = []
+  let contentWidth = 0
+  let contentHeight = 0
+
+  if (mode === 'horizontal') {
+    let x = originX + padding
+    contentHeight = Math.max(...sizes.map((size) => size.height))
+    orderedNodes.forEach((node, index) => {
+      positions.push({ id: String(node.id), position: { x, y: originY + padding } })
+      x += sizes[index].width + gapX
+    })
+    contentWidth = x - originX - padding - gapX
+  } else if (mode === 'vertical') {
+    let y = originY + padding
+    contentWidth = Math.max(...sizes.map((size) => size.width))
+    orderedNodes.forEach((node, index) => {
+      positions.push({ id: String(node.id), position: { x: originX + padding, y } })
+      y += sizes[index].height + gapY
+    })
+    contentHeight = y - originY - padding - gapY
+  } else {
+    const columnCount = Math.ceil(Math.sqrt(orderedNodes.length))
+    const rowCount = Math.ceil(orderedNodes.length / columnCount)
+    const columnWidths = Array.from({ length: columnCount }, () => 0)
+    const rowHeights = Array.from({ length: rowCount }, () => 0)
+    sizes.forEach((size, index) => {
+      const column = index % columnCount
+      const row = Math.floor(index / columnCount)
+      columnWidths[column] = Math.max(columnWidths[column], size.width)
+      rowHeights[row] = Math.max(rowHeights[row], size.height)
+    })
+    const columnOffsets = columnWidths.map(
+      (_, index) =>
+        columnWidths.slice(0, index).reduce((sum, width) => sum + width, 0) + gapX * index
+    )
+    const rowOffsets = rowHeights.map(
+      (_, index) =>
+        rowHeights.slice(0, index).reduce((sum, height) => sum + height, 0) + gapY * index
+    )
+    orderedNodes.forEach((node, index) => {
+      const column = index % columnCount
+      const row = Math.floor(index / columnCount)
+      positions.push({
+        id: String(node.id),
+        position: {
+          x: originX + padding + columnOffsets[column],
+          y: originY + padding + rowOffsets[row],
+        },
+      })
+    })
+    contentWidth = columnWidths.reduce((sum, width) => sum + width, 0) + gapX * (columnCount - 1)
+    contentHeight = rowHeights.reduce((sum, height) => sum + height, 0) + gapY * (rowCount - 1)
+  }
+
+  return {
+    positions,
+    size: {
+      width: Math.round(contentWidth + padding * 2),
+      height: Math.round(contentHeight + padding * 2),
+    },
+  }
+}