@p-dsh-market/conversation-knowledge-map 0.1.0

package/lib/index.js

@@ -0,0 +1,286 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { randomUUID } from 'node:crypto'
+
+import { KnowledgeGenerationOrchestrator } from './generation-orchestrator.js'
+import { errorMessage, jsonResponse, methodOf, parseUrl, readJson, safeId, sseWrite, shortText } from './protocol.js'
+import { listWorkspaceSessions, normalizeWorkspacePath, resolveAnchorSession } from './session-source.js'
+import { WorkspaceRevisionError, WorkspaceStorage } from './workspace-storage.js'
+
+const BASE_PATH = '/conversation-knowledge-map'
+const PLUGIN_ID = '@p-dsh-market/conversation-knowledge-map'
+const SKILL_PATH = fileURLToPath(new URL('../skills/conversation-knowledge-map/SKILL.md', import.meta.url))
+const SKILL_DIR_PATH = fileURLToPath(new URL('../skills/conversation-knowledge-map/', import.meta.url))
+const CONFIRMATION_TTL = 5 * 60 * 1000
+
+function getService(ctx, name) {
+  return ctx?.get?.(name) ?? ctx?.[name]
+}
+
+function registerEffect(ctx, service, value) {
+  if (!service?.register) return
+  const register = () => service.register(value)
+  if (typeof ctx?.effect === 'function') ctx.effect(register)
+  else register()
+}
+
+function writeError(res, error, status = 400) {
+  return jsonResponse(res, status, { ok: false, error: errorMessage(error) })
+}
+
+function parsePath(req) {
+  const pathname = parseUrl(req).pathname
+  if (pathname === BASE_PATH || pathname === `${BASE_PATH}/`) return []
+  if (!pathname.startsWith(`${BASE_PATH}/`)) return null
+  return pathname.slice(`${BASE_PATH}/`.length).split('/').filter(Boolean).map((item) => decodeURIComponent(item))
+}
+
+function normalizeOutputMode(value) {
+  const mode = String(value || 'both').trim()
+  if (!['mind-map', 'knowledge-graph', 'both'].includes(mode)) throw new Error('生成内容必须是 mind-map、knowledge-graph 或 both。')
+  return mode
+}
+
+function normalizeGenerationInput(body = {}) {
+  const selectedSessionIds = [...new Set((Array.isArray(body.selectedSessionIds) ? body.selectedSessionIds : []).map((id) => String(id || '').trim()).filter(Boolean))]
+  if (!selectedSessionIds.length) throw new Error('至少选择一个对话。')
+  const prompt = String(body.prompt || '').trim()
+  if (prompt.length > 4000) throw new Error('额外 Prompt 不能超过 4000 个字符。')
+  const expectedRevision = Number(body.expectedRevision)
+  return {
+    anchorSessionId: safeId(body.anchorSessionId, '锚点 Session ID'),
+    selectedSessionIds,
+    outputMode: normalizeOutputMode(body.outputMode),
+    prompt,
+    strict: body.strict !== false,
+    includeSubagents: body.includeSubagents === true,
+    expectedRevision: Number.isInteger(expectedRevision) && expectedRevision >= 0 ? expectedRevision : 0
+  }
+}
+
+function canonicalPayload(value) {
+  return JSON.stringify({
+    anchorSessionId: value.anchorSessionId,
+    cwd: normalizeWorkspacePath(value.cwd),
+    selectedSessionIds: [...value.selectedSessionIds].map(String).sort(),
+    outputMode: value.outputMode,
+    prompt: value.prompt,
+    strict: value.strict === true,
+    includeSubagents: value.includeSubagents === true,
+    expectedRevision: Number(value.expectedRevision || 0)
+  })
+}
+
+function statusForError(error) {
+  if (error instanceof WorkspaceRevisionError) return 409
+  if (/不存在|无效|不能为空|至少|不属于|没有|必须|不能|超出|缺少|已过期|确认/.test(errorMessage(error))) return 400
+  return 409
+}
+
+export function createHost(options = {}) {
+  const host = {
+    inject: ['agentDefaultModel', 'agents', 'sessionQuery', 'sessions', 'skills', 'webServer'],
+
+    apply(ctx) {
+      const sessionQuery = options.sessionQuery || getService(ctx, 'sessionQuery')
+      const sessions = options.sessions || getService(ctx, 'sessions')
+      const agents = options.agents || getService(ctx, 'agents')
+      const agentDefaultModel = options.agentDefaultModel || getService(ctx, 'agentDefaultModel')
+      const skills = options.skills || getService(ctx, 'skills')
+      const webServer = options.webServer || getService(ctx, 'webServer')
+      const storage = options.storage || new WorkspaceStorage(options.storageOptions)
+      const orchestrator = options.orchestrator || new KnowledgeGenerationOrchestrator({
+        sessionQuery,
+        sessions,
+        agents,
+        agentDefaultModel,
+        storage,
+        modelRunner: options.modelRunner
+      })
+      const confirmations = new Map()
+      const sseClients = new Set()
+
+      async function contextFor(sessionId) {
+        const anchor = await resolveAnchorSession({ sessionQuery, sessions }, sessionId)
+        const header = anchor?.header || anchor?.session || null
+        if (!header?.id) return { ready: false, state: 'no-session', sessionId: '', cwd: '' }
+        const cwd = normalizeWorkspacePath(header.cwd)
+        if (!cwd) return { ready: false, state: 'session-without-cwd', sessionId: String(header.id), cwd: '' }
+        return { ready: true, state: 'ready', sessionId: String(header.id), cwd, origin: String(header.origin || '') }
+      }
+
+      async function sessionsFor(body) {
+        const context = await contextFor(body.anchorSessionId)
+        if (!context.ready) throw new Error('请先打开一个有明确工作路径的已有对话。')
+        return { context, sessions: await listWorkspaceSessions({ sessionQuery, sessions }, context.cwd, context.sessionId, body.includeSubagents === true) }
+      }
+
+      async function confirmGeneration(body) {
+        const input = normalizeGenerationInput(body)
+        const { context, sessions: available } = await sessionsFor(input)
+        const allowed = new Set(available.map((item) => item.id))
+        for (const id of input.selectedSessionIds) if (!allowed.has(id)) throw new Error(`所选对话不属于当前工作路径或已不可用：${id}`)
+        const state = await storage.readState(context.cwd)
+        if (input.expectedRevision !== state.revision) throw new WorkspaceRevisionError(input.expectedRevision, state.revision)
+        const payload = { ...input, anchorSessionId: context.sessionId, cwd: context.cwd, expectedRevision: state.revision }
+        const token = randomUUID()
+        confirmations.set(token, { payload, expiresAt: Date.now() + CONFIRMATION_TTL, used: false })
+        return {
+          token,
+          expiresAt: Date.now() + CONFIRMATION_TTL,
+          revision: state.revision,
+          context,
+          selectedSessions: available.filter((item) => input.selectedSessionIds.includes(item.id)),
+          outputMode: input.outputMode,
+          strict: input.strict,
+          promptSummary: shortText(input.prompt, 300),
+          overwrite: state.exists
+        }
+      }
+
+      function consumeConfirmation(token, body) {
+        const value = confirmations.get(String(token || ''))
+        if (!value || value.used || value.expiresAt < Date.now()) throw new Error('生成确认已过期，请返回配置重新确认。')
+        const supplied = normalizeGenerationInput({ ...body, anchorSessionId: body.anchorSessionId || value.payload.anchorSessionId, selectedSessionIds: body.selectedSessionIds || value.payload.selectedSessionIds, outputMode: body.outputMode || value.payload.outputMode, prompt: body.prompt ?? value.payload.prompt, strict: body.strict ?? value.payload.strict, includeSubagents: body.includeSubagents ?? value.payload.includeSubagents, expectedRevision: body.expectedRevision ?? value.payload.expectedRevision })
+        const expected = canonicalPayload(value.payload)
+        const actual = canonicalPayload({ ...supplied, cwd: value.payload.cwd })
+        if (expected !== actual) throw new Error('确认内容已变化，请返回配置重新确认。')
+        value.used = true
+        return { ...value.payload }
+      }
+
+      async function handleGeneration(req, res) {
+        const path = parsePath(req)
+        const method = methodOf(req)
+        if (!path) return jsonResponse(res, 404, { ok: false, error: 'Not found' })
+        try {
+          if (path.length === 0 && method === 'GET') {
+            return jsonResponse(res, 200, { ok: true, plugin: PLUGIN_ID })
+          }
+          if (path[0] === 'health' && method === 'GET') {
+            return jsonResponse(res, 200, { ok: true, agentsAvailable: Boolean(agents?.create), sessionQueryAvailable: Boolean(sessionQuery), activeGenerations: sseClients.size })
+          }
+          if (path[0] === 'context' && method === 'GET') {
+            const sessionId = parseUrl(req).searchParams.get('sessionId') || ''
+            return jsonResponse(res, 200, { ok: true, context: await contextFor(sessionId) })
+          }
+          if (path[0] === 'sessions' && method === 'GET') {
+            const anchorSessionId = parseUrl(req).searchParams.get('anchorSessionId') || ''
+            const includeSubagents = parseUrl(req).searchParams.get('includeSubagents') === 'true'
+            const { context, sessions: available } = await sessionsFor({ anchorSessionId, includeSubagents })
+            return jsonResponse(res, 200, { ok: true, context, sessions: available })
+          }
+          if (path[0] === 'state' && method === 'GET') {
+            const context = await contextFor(parseUrl(req).searchParams.get('anchorSessionId') || '')
+            if (!context.ready) return jsonResponse(res, 200, { ok: true, context, state: null })
+            const state = await storage.readState(context.cwd)
+            return jsonResponse(res, 200, { ok: true, context, state })
+          }
+          if (path[0] === 'confirm' && method === 'POST') {
+            return jsonResponse(res, 200, { ok: true, confirmation: await confirmGeneration(await readJson(req)) })
+          }
+          if (path[0] === 'generations' && path.length === 1 && method === 'POST') {
+            const body = await readJson(req)
+            const request = consumeConfirmation(body.token, body)
+            const task = orchestrator.start(request)
+            return jsonResponse(res, 202, { ok: true, generation: task })
+          }
+          if (path[0] === 'generations' && path[1] && path[2] === 'events' && method === 'GET') {
+            return handleEvents(req, res, path[1], orchestrator, sseClients)
+          }
+          if (path[0] === 'generations' && path[1] && path[2] === 'cancel' && method === 'POST') {
+            return jsonResponse(res, 200, { ok: true, generation: orchestrator.cancel(path[1]) })
+          }
+          if (path[0] === 'generations' && path[1] && path.length === 2 && method === 'GET') {
+            const generation = orchestrator.get(path[1])
+            return generation ? jsonResponse(res, 200, { ok: true, generation }) : jsonResponse(res, 404, { ok: false, error: '生成任务不存在。' })
+          }
+          if (path[0] === 'mind-map' && path[1] === 'follow-up-question' && method === 'POST') {
+            const body = await readJson(req)
+            const context = await contextFor(body.anchorSessionId)
+            if (!context.ready) throw new Error('当前对话没有可用工作路径。')
+            const state = await storage.readState(context.cwd)
+            const node = state.mindMap?.nodes?.find((item) => item.id === body.nodeId)
+            if (!node) throw new Error('思维导图节点不存在。')
+            const targetSessionId = safeId(body.targetSessionId || node.primarySourceSessionId || node.sourceRefs?.[0]?.sessionId, '目标 Session ID')
+            if (!state.manifest?.sourceSessionIds?.includes(targetSessionId)) throw new Error('目标对话不是本次生成的来源对话。')
+            const result = await orchestrator.formFollowUp({ cwd: context.cwd, node, targetSessionId, strict: state.manifest.strict !== false })
+            return jsonResponse(res, 200, { ok: true, followUp: result, context, revision: state.revision })
+          }
+          if (path[0] === 'navigation' && path[1] === 'confirm' && method === 'POST') {
+            const body = await readJson(req)
+            const context = await contextFor(body.anchorSessionId)
+            if (!context.ready) throw new Error('当前对话没有可用工作路径。')
+            const state = await storage.readState(context.cwd)
+            const targetSessionId = safeId(body.targetSessionId, '目标 Session ID')
+            if (!state.manifest?.sourceSessionIds?.includes(targetSessionId)) throw new Error('目标对话不是本次生成的来源对话。')
+            const question = String(body.question || '').trim()
+            if (!question || question.length > 2000) throw new Error('后续问题不能为空且不能超过 2000 个字符。')
+            const navigation = await storage.appendNavigation({
+              cwd: context.cwd,
+              expectedRevision: state.revision,
+              navigation: { id: randomUUID(), nodeId: body.nodeId, targetSessionId, question }
+            })
+            return jsonResponse(res, 200, { ok: true, navigation: { ...navigation.navigation, question, targetSessionId }, context })
+          }
+          return jsonResponse(res, 404, { ok: false, error: 'Not found' })
+        } catch (error) {
+          return writeError(res, error, statusForError(error))
+        }
+      }
+
+      registerEffect(ctx, webServer, { kind: 'prefix', path: BASE_PATH, handler: handleGeneration })
+      registerEffect(ctx, skills, {
+        name: 'conversation-knowledge-map',
+        description: '从同一工作路径的多个历史对话生成思维导图和静态知识图谱。',
+        whenToUse: '用户明确要求整理多个对话、生成脑图、知识图谱或从脑图节点继续探索时。',
+        source: 'runtime',
+        content: readFileSync(SKILL_PATH, 'utf8').replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/, ''),
+        resourceBase: { kind: 'directory', path: SKILL_DIR_PATH }
+      })
+      if (typeof ctx?.effect === 'function') {
+        ctx.effect(() => () => {
+          for (const client of sseClients.values()) client.close?.()
+          sseClients.clear()
+          for (const task of orchestrator.tasks?.values?.() || []) task.controller?.abort?.(new Error('插件停止。'))
+        })
+      }
+    }
+  }
+  return host
+}
+
+async function handleEvents(req, res, id, orchestrator, sseClients) {
+  const snapshot = orchestrator.get(id)
+  if (!snapshot) return jsonResponse(res, 404, { ok: false, error: '生成任务不存在。' })
+  res.writeHead?.(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache, no-transform',
+    connection: 'keep-alive'
+  })
+  const since = Number(parseUrl(req).searchParams.get('since') || 0)
+  const client = {
+    closed: false,
+    unsubscribe: null,
+    close() {
+      if (client.closed) return
+      client.closed = true
+      client.unsubscribe?.()
+      sseClients.delete(client)
+      try { res.end?.() } catch { /* response already closed */ }
+    }
+  }
+  sseClients.add(client)
+  client.unsubscribe = orchestrator.subscribe(id, (event, current) => {
+    if (event.id <= since || client.closed) return
+    try { sseWrite(res, 'update', { event, generation: current }, event.id) } catch { client.close() }
+  }, since)
+  sseWrite(res, 'snapshot', { generation: orchestrator.get(id) }, snapshot.events?.at(-1)?.id || 0)
+  req.on?.('close', () => client.close())
+  res.on?.('close', () => client.close())
+}
+
+const host = createHost()
+host.pluginId = PLUGIN_ID
+export { BASE_PATH }
+export default host

package/lib/knowledge-graph-schema.js

@@ -0,0 +1,89 @@
+export const KNOWLEDGE_GRAPH_SCHEMA_VERSION = 1
+export const MAX_ENTITIES = 150
+export const MAX_RELATIONS = 300
+
+export class KnowledgeGraphValidationError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'KnowledgeGraphValidationError'
+  }
+}
+
+function asText(value, label, max = 4000) {
+  const text = String(value ?? '').trim()
+  if (!text) throw new KnowledgeGraphValidationError(`${label} 不能为空。`)
+  if (text.length > max) throw new KnowledgeGraphValidationError(`${label} 超出长度限制。`)
+  return text
+}
+
+function refsOf(raw, selectedSessionIds, label) {
+  const refs = raw?.sourceRefs ?? raw?.evidence ?? []
+  if (!Array.isArray(refs)) return []
+  const selected = new Set(selectedSessionIds || [])
+  return refs.map((ref) => {
+    const sessionId = asText(ref?.sessionId, `${label}来源 Session ID`, 256)
+    if (selected.size && !selected.has(sessionId)) throw new KnowledgeGraphValidationError(`来源 Session 不在本次选择中：${sessionId}`)
+    const eventSeqs = Array.isArray(ref?.eventSeqs)
+      ? [...new Set(ref.eventSeqs.filter((seq) => Number.isInteger(seq) && seq >= 0))]
+      : []
+    if (!eventSeqs.length) throw new KnowledgeGraphValidationError(`${label}来源缺少事件序号。`)
+    return { sessionId, eventSeqs }
+  }).slice(0, 12)
+}
+
+function confidenceOf(value) {
+  const confidence = String(value || 'confirmed').trim()
+  if (!['confirmed', 'inferred', 'conflicted'].includes(confidence)) throw new KnowledgeGraphValidationError(`不支持的置信度：${confidence}`)
+  return confidence
+}
+
+export function validateKnowledgeGraph(input, { selectedSessionIds = [], strict = false } = {}) {
+  if (!input || typeof input !== 'object') throw new KnowledgeGraphValidationError('知识图谱结果必须是对象。')
+  const rawEntities = Array.isArray(input.entities) ? input.entities : []
+  const rawRelations = Array.isArray(input.relations) ? input.relations : []
+  if (!rawEntities.length) throw new KnowledgeGraphValidationError('知识图谱至少需要一个实体。')
+  if (rawEntities.length > MAX_ENTITIES) throw new KnowledgeGraphValidationError(`实体不能超过 ${MAX_ENTITIES} 个。`)
+  if (rawRelations.length > MAX_RELATIONS) throw new KnowledgeGraphValidationError(`关系不能超过 ${MAX_RELATIONS} 条。`)
+  const ids = new Set()
+  const entities = rawEntities.map((raw, index) => {
+    const id = asText(raw?.id || `entity-${index + 1}`, '实体 ID', 256)
+    if (ids.has(id)) throw new KnowledgeGraphValidationError(`实体 ID 重复：${id}`)
+    ids.add(id)
+    const sourceRefs = refsOf(raw, selectedSessionIds, `实体 ${id}`)
+    if (strict && !sourceRefs.length) throw new KnowledgeGraphValidationError(`严格约束要求实体 ${id} 带来源引用。`)
+    return {
+      id,
+      type: asText(raw?.type || 'concept', `实体 ${id} 类型`, 80),
+      name: asText(raw?.name || raw?.label, `实体 ${id} 名称`, 240),
+      summary: asText(raw?.summary || raw?.description, `实体 ${id} 摘要`, 1600),
+      confidence: confidenceOf(raw?.confidence),
+      sourceRefs
+    }
+  })
+  const relations = rawRelations.map((raw, index) => {
+    const from = asText(raw?.from, `关系 ${index + 1} from`, 256)
+    const to = asText(raw?.to, `关系 ${index + 1} to`, 256)
+    if (!ids.has(from) || !ids.has(to)) throw new KnowledgeGraphValidationError(`关系 ${index + 1} 引用了不存在的实体。`)
+    if (from === to) throw new KnowledgeGraphValidationError(`关系 ${index + 1} 不能连接实体自身。`)
+    const evidence = refsOf(raw, selectedSessionIds, `关系 ${index + 1}`)
+    if (strict && !evidence.length) throw new KnowledgeGraphValidationError(`严格约束要求关系 ${index + 1} 带证据。`)
+    return {
+      id: String(raw?.id || `relation-${index + 1}`),
+      from,
+      to,
+      type: asText(raw?.type || 'related_to', `关系 ${index + 1} 类型`, 80),
+      confidence: confidenceOf(raw?.confidence),
+      evidence
+    }
+  })
+  const relationIds = new Set()
+  for (const relation of relations) {
+    if (relationIds.has(relation.id)) throw new KnowledgeGraphValidationError(`关系 ID 重复：${relation.id}`)
+    relationIds.add(relation.id)
+  }
+  return {
+    schemaVersion: KNOWLEDGE_GRAPH_SCHEMA_VERSION,
+    entities,
+    relations
+  }
+}

package/lib/mind-map-schema.js

@@ -0,0 +1,94 @@
+export const MIND_MAP_SCHEMA_VERSION = 1
+export const MAX_MIND_MAP_NODES = 80
+
+export class MindMapValidationError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'MindMapValidationError'
+  }
+}
+
+function asText(value, label, max = 20000) {
+  const text = String(value ?? '').trim()
+  if (!text) throw new MindMapValidationError(`${label} 不能为空。`)
+  if (text.length > max) throw new MindMapValidationError(`${label} 超出长度限制。`)
+  return text
+}
+
+function normalizeRefs(refs, selectedSessionIds) {
+  if (!Array.isArray(refs)) return []
+  const selected = new Set(selectedSessionIds || [])
+  return refs.map((ref) => {
+    const sessionId = asText(ref?.sessionId, '来源 Session ID', 256)
+    if (selected.size && !selected.has(sessionId)) throw new MindMapValidationError(`来源 Session 不在本次选择中：${sessionId}`)
+    const eventSeqs = Array.isArray(ref?.eventSeqs)
+      ? [...new Set(ref.eventSeqs.filter((seq) => Number.isInteger(seq) && seq >= 0))]
+      : []
+    if (!eventSeqs.length) throw new MindMapValidationError(`来源 ${sessionId} 缺少事件序号。`)
+    return { sessionId, eventSeqs }
+  }).slice(0, 12)
+}
+
+function detectCycle(nodes) {
+  const byId = new Map(nodes.map((node) => [node.id, node]))
+  const visiting = new Set()
+  const visited = new Set()
+  function visit(id) {
+    if (visited.has(id)) return
+    if (visiting.has(id)) throw new MindMapValidationError('思维导图层级存在循环。')
+    visiting.add(id)
+    const parentId = byId.get(id)?.parentId
+    if (parentId) visit(parentId)
+    visiting.delete(id)
+    visited.add(id)
+  }
+  for (const node of nodes) visit(node.id)
+}
+
+export function validateMindMap(input, { selectedSessionIds = [], strict = false } = {}) {
+  if (!input || typeof input !== 'object') throw new MindMapValidationError('思维导图结果必须是对象。')
+  const rawNodes = Array.isArray(input.nodes) ? input.nodes : []
+  if (!rawNodes.length) throw new MindMapValidationError('思维导图至少需要一个节点。')
+  if (rawNodes.length > MAX_MIND_MAP_NODES) throw new MindMapValidationError(`思维导图节点不能超过 ${MAX_MIND_MAP_NODES} 个。`)
+  const rootId = asText(input.rootId || rawNodes[0]?.id, '思维导图 rootId', 256)
+  const ids = new Set()
+  const nodes = rawNodes.map((raw, index) => {
+    const id = asText(raw?.id || `mind-node-${index + 1}`, '思维导图节点 ID', 256)
+    if (ids.has(id)) throw new MindMapValidationError(`思维导图节点 ID 重复：${id}`)
+    ids.add(id)
+    const parentId = raw?.parentId === null || raw?.parentId === undefined || raw?.parentId === '' ? null : asText(raw.parentId, 'parentId', 256)
+    const title = asText(raw?.title ?? raw?.label, `节点 ${id} 标题`, 120)
+    const narrative = asText(raw?.narrative ?? raw?.summary, `节点 ${id} 阶段性说明`, 2000)
+    if (narrative.length < 20) throw new MindMapValidationError(`节点 ${id} 的阶段性说明过短，不能只使用关键词。`)
+    const sourceRefs = normalizeRefs(raw?.sourceRefs, selectedSessionIds)
+    if (strict && !sourceRefs.length) throw new MindMapValidationError(`严格约束要求节点 ${id} 带来源引用。`)
+    const primarySourceSessionId = raw?.primarySourceSessionId ? asText(raw.primarySourceSessionId, '主要来源 Session ID', 256) : (sourceRefs[0]?.sessionId || '')
+    if (primarySourceSessionId && selectedSessionIds.length && !selectedSessionIds.includes(primarySourceSessionId)) {
+      throw new MindMapValidationError(`节点 ${id} 的主要来源不在本次选择中。`)
+    }
+    const openQuestions = Array.isArray(raw?.openQuestions)
+      ? raw.openQuestions.map((question) => String(question || '').trim()).filter(Boolean).slice(0, 3)
+      : []
+    return {
+      id,
+      parentId,
+      type: asText(raw?.type || 'stage', `节点 ${id} 类型`, 40),
+      title,
+      narrative,
+      primarySourceSessionId,
+      sourceRefs,
+      openQuestions
+    }
+  })
+  if (!ids.has(rootId)) throw new MindMapValidationError(`rootId 不存在：${rootId}`)
+  const rootNodes = nodes.filter((node) => node.parentId === null)
+  if (rootNodes.length !== 1 || rootNodes[0].id !== rootId) throw new MindMapValidationError('思维导图必须只有一个根节点。')
+  for (const node of nodes) if (node.parentId && !ids.has(node.parentId)) throw new MindMapValidationError(`节点 ${node.id} 的父节点不存在。`)
+  detectCycle(nodes)
+  return {
+    schemaVersion: MIND_MAP_SCHEMA_VERSION,
+    rootId,
+    nodes,
+    edges: nodes.filter((node) => node.parentId).map((node) => ({ from: node.parentId, to: node.id }))
+  }
+}

package/lib/protocol.js

@@ -0,0 +1,104 @@
+export const DATA_DIR = '.g-dsh-market-knowledge'
+export const OUTPUT_MODES = new Set(['mind-map', 'knowledge-graph', 'both'])
+export const GENERATION_STATUSES = [
+  'created',
+  'confirming',
+  'reading-sources',
+  'summarizing',
+  'building-mind-map',
+  'building-knowledge-graph',
+  'validating',
+  'saving',
+  'completed',
+  'failed',
+  'cancelled'
+]
+
+export function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error || '未知错误')
+}
+
+export function shortText(value, max = 8000) {
+  const text = String(value ?? '').replace(/\s+/g, ' ').trim()
+  return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text
+}
+
+export function clone(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
+}
+
+export function parseUrl(req) {
+  if (req?.url instanceof URL) return req.url
+  return new URL(String(req?.url || '/'), 'http://dsh.local')
+}
+
+export async function readJson(req, maxBytes = 512 * 1024) {
+  if (req?.body && typeof req.body === 'object') return req.body
+  if (typeof req?.body === 'string') return JSON.parse(req.body || '{}')
+  const chunks = []
+  let size = 0
+  for await (const chunk of req || []) {
+    size += Buffer.byteLength(chunk)
+    if (size > maxBytes) throw new Error('请求体过大。')
+    chunks.push(Buffer.from(chunk))
+  }
+  const text = Buffer.concat(chunks).toString('utf8').trim()
+  return text ? JSON.parse(text) : {}
+}
+
+export function jsonResponse(res, status, body) {
+  const text = JSON.stringify(body)
+  res.writeHead?.(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store'
+  })
+  res.end?.(text)
+  return body
+}
+
+export function sseWrite(res, eventName, body, id) {
+  if (id !== undefined) res.write(`id: ${id}\n`)
+  res.write(`event: ${eventName}\n`)
+  res.write(`data: ${JSON.stringify(body)}\n\n`)
+}
+
+export function methodOf(req) {
+  return String(req?.method || 'GET').toUpperCase()
+}
+
+export function safeId(value, label = 'ID') {
+  const result = String(value || '').trim()
+  if (!result || result.length > 256 || /[\u0000-\u001f]/.test(result)) throw new Error(`${label} 无效。`)
+  return result
+}
+
+export function contentText(value) {
+  if (value === undefined || value === null) return ''
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) {
+    return value.map((item) => {
+      if (item && typeof item === 'object' && item.type === 'reasoning') return ''
+      return contentText(item)
+    }).filter(Boolean).join('')
+  }
+  if (typeof value === 'object') {
+    if (typeof value.text === 'string') return value.text
+    if (typeof value.content !== 'undefined') return contentText(value.content)
+    if (typeof value.value === 'string') return value.value
+  }
+  return ''
+}
+
+export function eventMessageText(event) {
+  const data = event?.data || event || {}
+  const message = data.message || data
+  return contentText(message.content ?? message.text ?? message)
+}
+
+export function makeUserMessage(text, messageId = `knowledge-map-${Date.now()}`) {
+  return {
+    id: messageId,
+    role: 'user',
+    content: [{ type: 'text', text: String(text || '') }]
+  }
+}