@p-dsh-market/conversation-knowledge-map 0.1.2 → 0.1.4

package/README.md

@@ -13,6 +13,10 @@ DSH 的“知识视图”插件，把同一工作路径下用户明确选择的
 
 节点“继续对话”只形成一个可编辑的后续问题。确认导航后，插件使用公开的 Session 导航入口；如果当前 Runtime 没有向该槽位暴露草稿镜像，则提供“打开并复制问题”的安全降级，不自动发送消息。
 
+## 生成失败诊断
+
+Host 和生成编排器会输出带 `[conversation-knowledge-map]` 前缀的诊断日志。日志包含路由、Provider / Model、Agent Session、实时事件类型、surface/session 读取次数、提取文本长度、输出形状和错误原因，不记录 Prompt、对话正文或模型返回正文。优先查看 DSH Web Runtime 的终端日志；若 Runtime 提供 logger 服务，则同时写入该 logger。重点关注 `agent event`、`agent idle`、`agent turn failure`、`agent surface read`、`agent session read` 和 `agent output parse failed`。Runtime 在 `turn/end.reason.kind = error` 时会优先显示其 `code/message`；只有未发现 turn 错误且确实没有助手输出时，才会报告“模型没有返回 JSON 对象”。
+
 ## 本地验证
 
 ```powershell

package/lib/generation-orchestrator.js

@@ -2,11 +2,22 @@ import { randomUUID } from 'node:crypto'
 
 import { validateKnowledgeGraph } from './knowledge-graph-schema.js'
 import { validateMindMap } from './mind-map-schema.js'
-import { clone, errorMessage, makeUserMessage, shortText } from './protocol.js'
+import { clone, diagnosticSummary, errorMessage, logMessage, makeUserMessage, shortText } from './protocol.js'
 import { chunkSourceText, readSelectedSurfaces } from './session-source.js'
 
 const MAX_SUMMARY_CHARS = 2400
 
+function modelLabel(selection) {
+  const provider = String(selection?.provider || '').trim()
+  const model = String(selection?.model || '').trim()
+  return provider && model ? `${provider}/${model}` : 'default'
+}
+
+function logId(value) {
+  const text = String(value || '')
+  return text.length > 96 ? `${text.slice(0, 40)}…${text.slice(-40)}` : text
+}
+
 function phaseMessage(status) {
   return {
     confirming: '等待用户确认生成范围…',
@@ -224,17 +235,76 @@ function extractAgentText(surface) {
   return chunks.join('')
 }
 
-async function readAgentText(sessionQuery, sessionId, signal) {
+function agentTurnError(event) {
+  if (String(event?.type || '') !== 'turn/end') return null
+  const data = event?.data && typeof event.data === 'object' ? event.data : {}
+  const reason = data.reason && typeof data.reason === 'object' ? data.reason : null
+  if (reason?.kind !== 'error') return null
+  const nestedError = reason.error && typeof reason.error === 'object' ? reason.error : null
+  const code = String(nestedError?.code || reason.code || '').trim()
+  const message = String(nestedError?.message || reason.message || (typeof reason.error === 'string' ? reason.error : '')).trim()
+  const detail = shortText(message || 'Agent turn 执行失败。', 1200)
+  const error = new Error(`Agent Runtime 生成失败${code ? `（${code}）` : ''}：${detail}`)
+  error.code = code
+  error.agentTurn = true
+  error.cause = nestedError || reason
+  return error
+}
+
+function findAgentTurnError(surface) {
+  const events = Array.isArray(surface?.events) ? surface.events : []
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const error = agentTurnError(events[index])
+    if (error) return error
+  }
+  return null
+}
+
+function wrapAgentRuntimeError(error) {
+  if (error?.agentTurn || /^Agent Runtime 生成失败/.test(errorMessage(error))) return error
+  const wrapped = new Error(`Agent Runtime 生成失败：${errorMessage(error)}`)
+  wrapped.cause = error
+  return wrapped
+}
+
+async function readAgentText(sessionQuery, sessionId, signal, { logger, diagnostics } = {}) {
+  const stats = diagnostics || { surfaceReads: 0, sessionReads: 0 }
   for (let attempt = 0; attempt < 6; attempt += 1) {
     if (signal?.aborted) throw signal.reason || new Error('生成已取消。')
+    stats.surfaceReads += 1
     const surface = await sessionQuery?.readSurface?.(sessionId)
     const text = extractAgentText(surface)
+    const eventCount = Array.isArray(surface?.events) ? surface.events.length : 0
+    stats.lastSurfaceEventCount = eventCount
+    stats.lastSurfaceShape = diagnosticSummary(surface)
+    stats.lastSurfaceTextLength = text.length
+    logMessage(logger, 'info', 'agent surface read session=%s attempt=%d events=%d extractedTextLength=%d shape=%s', logId(sessionId), attempt + 1, eventCount, text.length, stats.lastSurfaceShape)
+    const surfaceError = findAgentTurnError(surface)
+    if (surfaceError) {
+      stats.agentFailureSource = 'surface'
+      stats.agentFailureCode = surfaceError.code || ''
+      logMessage(logger, 'error', 'agent turn failure session=%s source=surface code=%s error=%s', logId(sessionId), surfaceError.code || '', errorMessage(surfaceError))
+      throw surfaceError
+    }
     if (text.trim()) return text
     if (attempt < 5) await new Promise((resolve) => setTimeout(resolve, 40 * (attempt + 1)))
   }
   if (typeof sessionQuery?.readSession === 'function') {
+    stats.sessionReads += 1
     const log = await sessionQuery.readSession(sessionId)
     const text = extractAgentText(log)
+    const eventCount = Array.isArray(log?.events) ? log.events.length : 0
+    stats.lastSessionEventCount = eventCount
+    stats.lastSessionShape = diagnosticSummary(log)
+    stats.lastSessionTextLength = text.length
+    logMessage(logger, 'info', 'agent session read session=%s events=%d extractedTextLength=%d shape=%s', logId(sessionId), eventCount, text.length, stats.lastSessionShape)
+    const sessionError = findAgentTurnError(log)
+    if (sessionError) {
+      stats.agentFailureSource = 'session'
+      stats.agentFailureCode = sessionError.code || ''
+      logMessage(logger, 'error', 'agent turn failure session=%s source=session code=%s error=%s', logId(sessionId), sessionError.code || '', errorMessage(sessionError))
+      throw sessionError
+    }
     if (text.trim()) return text
   }
   return ''
@@ -259,6 +329,7 @@ export class KnowledgeGenerationOrchestrator {
     storage,
     modelRunner,
     sessionEventSource,
+    logger,
     sourceReader = readSelectedSurfaces,
     now = () => Date.now(),
     idFactory = () => randomUUID()
@@ -270,6 +341,7 @@ export class KnowledgeGenerationOrchestrator {
     this.storage = storage
     this.modelRunner = modelRunner
     this.sessionEventSource = sessionEventSource
+    this.logger = logger
     this.sourceReader = sourceReader
     this.now = now
     this.idFactory = idFactory
@@ -338,6 +410,7 @@ export class KnowledgeGenerationOrchestrator {
     }
     this.tasks.set(task.id, task)
     this.busyByWorkspace.set(key, task.id)
+    logMessage(this.logger, 'info', 'generation start id=%s cwd=%s outputMode=%s selectedSessions=%d strict=%s model=%s', logId(task.id), shortText(request.cwd, 180), request.outputMode, Array.isArray(request.selectedSessionIds) ? request.selectedSessionIds.length : 0, request.strict === true, modelLabel(request.model))
     this.update(task, 'created', { request: { ...request, prompt: shortText(request.prompt, 500) } })
     task.promise = this.run(task, request).finally(() => {
       if (this.busyByWorkspace.get(key) === task.id) this.busyByWorkspace.delete(key)
@@ -366,6 +439,7 @@ export class KnowledgeGenerationOrchestrator {
         includeSubagents: request.includeSubagents === true
       })
       this.assertNotCancelled(task)
+      logMessage(this.logger, 'info', 'generation sources loaded id=%s sources=%d events=%d', logId(task.id), sources.length, sources.reduce((total, source) => total + (Array.isArray(source.events) ? source.events.length : 0), 0))
       this.update(task, 'summarizing', { sourceCount: sources.length })
       const summaries = []
       for (const source of sources) {
@@ -430,11 +504,13 @@ export class KnowledgeGenerationOrchestrator {
       })
       task.revision = saved.revision
       task.result = { revision: saved.revision, manifest: saved.manifest, mindMap, knowledgeGraph }
+      logMessage(this.logger, 'info', 'generation completed id=%s revision=%d elapsedMs=%d', logId(task.id), saved.revision, this.now() - task.createdAt)
       this.update(task, 'completed', { revision: saved.revision, result: task.result })
     } catch (error) {
       if (task.controller.signal.aborted || /取消|cancel/i.test(errorMessage(error))) {
         this.update(task, 'cancelled', { error: '' })
       } else {
+        logMessage(this.logger, 'error', 'generation failed id=%s status=%s error=%s', logId(task.id), task.status, errorMessage(error))
         this.update(task, 'failed', { error: errorMessage(error) })
       }
     }
@@ -442,27 +518,80 @@ export class KnowledgeGenerationOrchestrator {
   }
 
   async runModel(input) {
-    if (typeof this.modelRunner === 'function') return parseStructuredOutput(await this.modelRunner(input))
+    const parseModelOutput = (value, source, diagnostics = {}) => {
+      try {
+        const result = parseStructuredOutput(value)
+        logMessage(this.logger, 'info', 'agent output parsed kind=%s source=%s value=%s result=%s', input.kind, source, diagnosticSummary(value), diagnosticSummary(result))
+        return result
+      } catch (error) {
+        logMessage(this.logger, 'error', 'agent output parse failed kind=%s source=%s value=%s diagnostics=%s error=%s', input.kind, source, diagnosticSummary(value), JSON.stringify(diagnostics), errorMessage(error))
+        throw error
+      }
+    }
+    if (typeof this.modelRunner === 'function') {
+      logMessage(this.logger, 'info', 'model runner start kind=%s model=%s promptLength=%d', input.kind, modelLabel(input.model), String(input.prompt || '').length)
+      const value = await this.modelRunner(input)
+      return parseModelOutput(value, 'model-runner')
+    }
     if (!this.agents?.create) throw new Error('当前 DSH Runtime 未提供 agents.create，无法生成知识视图。')
     let selection = normalizeModelSelection(input.model)
     if (!selection) {
-      try { selection = normalizeModelSelection(this.agentDefaultModel?.currentSelection?.()) } catch { selection = null }
+      try {
+        selection = normalizeModelSelection(this.agentDefaultModel?.currentSelection?.())
+      } catch (error) {
+        logMessage(this.logger, 'warn', 'default model selection failed kind=%s error=%s', input.kind, shortText(errorMessage(error), 500))
+        selection = null
+      }
     }
     const provider = String(selection?.provider || '').trim()
     const model = String(selection?.model || '').trim()
-    if (!provider || !model) throw new Error('当前没有可用的默认 Provider/Model。')
+    if (!provider || !model) {
+      logMessage(this.logger, 'error', 'agent call has no usable model kind=%s requestedModel=%s defaultModel=%s', input.kind, modelLabel(input.model), modelLabel(selection))
+      throw new Error('当前没有可用的默认 Provider/Model。')
+    }
     const sessionId = `knowledge-map-${this.idFactory()}`
     const liveEvents = []
+    const diagnostics = {
+      liveEvents: 0,
+      liveAssistantMessages: 0,
+      liveAssistantChunks: 0,
+      liveOtherEvents: 0,
+      surfaceReads: 0,
+      sessionReads: 0,
+      lastSurfaceEventCount: 0,
+      lastSessionEventCount: 0,
+      agentFailureSource: '',
+      agentFailureCode: '',
+      agentFailure: null
+    }
+    logMessage(this.logger, 'info', 'agent call start kind=%s session=%s provider=%s model=%s promptLength=%d', input.kind, logId(sessionId), provider, model, String(input.prompt || '').length)
     let unsubscribe
     if (typeof this.sessionEventSource === 'function') {
       try {
         unsubscribe = this.sessionEventSource((session, event) => {
           const eventSessionId = String(session?.id || session?.header?.id || '')
-          if (eventSessionId === sessionId && event) liveEvents.push(event)
+          if (eventSessionId !== sessionId || !event) return
+          liveEvents.push(event)
+          diagnostics.liveEvents += 1
+          if (event.type === 'assistant/message') diagnostics.liveAssistantMessages += 1
+          else if (event.type === 'assistant/chunk') diagnostics.liveAssistantChunks += 1
+          else diagnostics.liveOtherEvents += 1
+          logMessage(this.logger, 'info', 'agent event session=%s type=%s data=%s', logId(sessionId), String(event.type || 'unknown'), diagnosticSummary(event.data))
+          const failure = agentTurnError(event)
+          if (failure && !diagnostics.agentFailure) {
+            diagnostics.agentFailure = failure
+            diagnostics.agentFailureSource = 'live-event'
+            diagnostics.agentFailureCode = failure.code || ''
+            logMessage(this.logger, 'error', 'agent turn failure session=%s source=live-event code=%s error=%s', logId(sessionId), failure.code || '', errorMessage(failure))
+          }
         })
-      } catch { /* event subscription is an optimization; surface reads remain the fallback */ }
+        logMessage(this.logger, 'info', 'agent event subscription ready session=%s', logId(sessionId))
+      } catch (error) {
+        logMessage(this.logger, 'warn', 'agent event subscription failed session=%s error=%s', logId(sessionId), errorMessage(error))
+      }
     }
     let handle
+    let stage = 'create'
     try {
       handle = await this.agents.create({
         sessionId,
@@ -480,14 +609,26 @@ export class KnowledgeGenerationOrchestrator {
           } catch { /* older runtimes may not expose tool restriction */ }
         }
       })
+      stage = 'followup'
       handle.agent.followup(makeUserMessage(input.prompt, `${sessionId}-${input.kind}`))
+      stage = 'idle'
       await handle.agent.whenIdle()
+      if (diagnostics.agentFailure) throw diagnostics.agentFailure
+      stage = 'read-output'
       const liveText = extractAgentText({ events: liveEvents })
-      if (liveText.trim()) return parseStructuredOutput(liveText)
-      return parseStructuredOutput(await readAgentText(this.sessionQuery, sessionId, input.signal))
+      logMessage(this.logger, 'info', 'agent idle session=%s liveEvents=%d assistantMessages=%d assistantChunks=%d otherEvents=%d liveTextLength=%d', logId(sessionId), diagnostics.liveEvents, diagnostics.liveAssistantMessages, diagnostics.liveAssistantChunks, diagnostics.liveOtherEvents, liveText.length)
+      if (liveText.trim()) return parseModelOutput(liveText, 'live-events', diagnostics)
+      const persistedText = await readAgentText(this.sessionQuery, sessionId, input.signal, { logger: this.logger, diagnostics })
+      logMessage(this.logger, 'info', 'agent persisted output session=%s textLength=%d surfaceReads=%d sessionReads=%d', logId(sessionId), persistedText.length, diagnostics.surfaceReads, diagnostics.sessionReads)
+      return parseModelOutput(persistedText, 'persisted-session', diagnostics)
+    } catch (error) {
+      const surfacedError = diagnostics.agentFailure || (stage === 'read-output' ? error : wrapAgentRuntimeError(error))
+      logMessage(this.logger, 'error', 'agent call failed kind=%s session=%s liveEvents=%d surfaceReads=%d sessionReads=%d error=%s', input.kind, logId(sessionId), diagnostics.liveEvents, diagnostics.surfaceReads, diagnostics.sessionReads, errorMessage(surfacedError))
+      throw surfacedError
     } finally {
-      await unsubscribe?.()
+      if (typeof unsubscribe === 'function') await unsubscribe()
       await handle?.dispose?.()
+      logMessage(this.logger, 'info', 'agent call disposed kind=%s session=%s', input.kind, logId(sessionId))
     }
   }
 

package/lib/index.js

@@ -3,7 +3,7 @@ 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 { errorMessage, jsonResponse, loggerFacade, logMessage, methodOf, parseUrl, readJson, safeId, sseWrite, shortText } from './protocol.js'
 import { listWorkspaceSessions, normalizeWorkspacePath, resolveAnchorSession } from './session-source.js'
 import { WorkspaceRevisionError, WorkspaceStorage } from './workspace-storage.js'
 
@@ -110,6 +110,7 @@ export function createHost(options = {}) {
       const llm = options.llm || getService(ctx, 'llm')
       const skills = options.skills || getService(ctx, 'skills')
       const webServer = options.webServer || getService(ctx, 'webServer')
+      const logger = loggerFacade(options.logger || getService(ctx, 'logger') || ctx?.logger || console)
       const storage = options.storage || new WorkspaceStorage(options.storageOptions)
       const sessionEventSource = options.sessionEventSource || (typeof ctx?.on === 'function' ? (listener) => ctx.on('session/event', listener) : null)
       const orchestrator = options.orchestrator || new KnowledgeGenerationOrchestrator({
@@ -119,10 +120,12 @@ export function createHost(options = {}) {
         agentDefaultModel,
         storage,
         modelRunner: options.modelRunner,
-        sessionEventSource
+        sessionEventSource,
+        logger
       })
       const confirmations = new Map()
       const sseClients = new Set()
+      logMessage(logger, 'info', 'host apply plugin=%s services sessionQuery=%s sessions=%s agents=%s llm=%s webServer=%s sessionEvents=%s', PLUGIN_ID, Boolean(sessionQuery), Boolean(sessions), Boolean(agents?.create), Boolean(llm), Boolean(webServer?.register), Boolean(sessionEventSource))
 
       async function contextFor(sessionId) {
         const anchor = await resolveAnchorSession({ sessionQuery, sessions }, sessionId)
@@ -159,6 +162,7 @@ export function createHost(options = {}) {
           if (!group) groups.unshift({ id: defaultModel.provider, name: defaultModel.provider, models: [{ id: defaultModel.model, name: defaultModel.model }] })
           else if (!group.models.some((item) => item.id === defaultModel.model)) group.models.unshift({ id: defaultModel.model, name: defaultModel.model })
         }
+        logMessage(logger, 'info', 'model catalog default=%s providers=%d groups=%d', defaultModel ? `${defaultModel.provider}/${defaultModel.model}` : 'none', providers.length, groups.length)
         return { default: defaultModel, groups }
       }
 
@@ -180,6 +184,7 @@ export function createHost(options = {}) {
         const payload = { ...input, model, anchorSessionId: context.sessionId, cwd: context.cwd, expectedRevision: state.revision }
         const token = randomUUID()
         confirmations.set(token, { payload, expiresAt: Date.now() + CONFIRMATION_TTL, used: false })
+        logMessage(logger, 'info', 'generation confirmed cwd=%s anchorSession=%s selectedSessions=%d outputMode=%s strict=%s model=%s expectedRevision=%d', shortText(context.cwd, 180), shortText(context.sessionId, 96), input.selectedSessionIds.length, input.outputMode, input.strict, `${model.provider}/${model.model}`, state.revision)
         return {
           token,
           expiresAt: Date.now() + CONFIRMATION_TTL,
@@ -209,6 +214,8 @@ export function createHost(options = {}) {
         const path = parsePath(req)
         const method = methodOf(req)
         if (!path) return jsonResponse(res, 404, { ok: false, error: 'Not found' })
+        const routeLabel = path.join('/') || '(root)'
+        logMessage(logger, 'info', 'route start method=%s path=%s', method, routeLabel)
         try {
           if (path.length === 0 && method === 'GET') {
             return jsonResponse(res, 200, { ok: true, plugin: PLUGIN_ID })
@@ -242,6 +249,7 @@ export function createHost(options = {}) {
             const body = await readJson(req)
             const request = consumeConfirmation(body.token, body)
             const task = orchestrator.start(request)
+            logMessage(logger, 'info', 'generation accepted id=%s outputMode=%s model=%s', shortText(task.id, 96), request.outputMode, `${request.model.provider}/${request.model.model}`)
             return jsonResponse(res, 202, { ok: true, generation: task })
           }
           if (path[0] === 'generations' && path[1] && path[2] === 'events' && method === 'GET') {
@@ -284,7 +292,9 @@ export function createHost(options = {}) {
           }
           return jsonResponse(res, 404, { ok: false, error: 'Not found' })
         } catch (error) {
-          return writeError(res, error, statusForError(error))
+          const status = statusForError(error)
+          logMessage(logger, 'error', 'route failed method=%s path=%s status=%d error=%s', method, routeLabel, status, errorMessage(error))
+          return writeError(res, error, status)
         }
       }
 
@@ -297,6 +307,7 @@ export function createHost(options = {}) {
         content: readFileSync(SKILL_PATH, 'utf8').replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/, ''),
         resourceBase: { kind: 'directory', path: SKILL_DIR_PATH }
       })
+      logMessage(logger, 'info', 'host registrations complete plugin=%s', PLUGIN_ID)
       if (typeof ctx?.effect === 'function') {
         ctx.effect(() => () => {
           for (const client of sseClients.values()) client.close?.()

package/lib/protocol.js

@@ -23,6 +23,36 @@ export function shortText(value, max = 8000) {
   return text.length > max ? `${text.slice(0, Math.max(0, max - 1))}…` : text
 }
 
+export function loggerFacade(service, name = 'conversation-knowledge-map') {
+  if (!service) return null
+  try {
+    const logger = typeof service === 'function' ? service(name) : service
+    return logger && typeof logger === 'object' ? logger : null
+  } catch {
+    return null
+  }
+}
+
+export function logMessage(logger, level, format, ...params) {
+  try { logger?.[level]?.(`[conversation-knowledge-map] ${format}`, ...params) } catch { /* logging must not affect the plugin */ }
+}
+
+function diagnosticShape(value, depth = 0) {
+  if (value === null) return 'null'
+  if (value === undefined) return 'undefined'
+  if (typeof value === 'string') return `string(${value.length})`
+  if (typeof value !== 'object') return typeof value
+  if (depth >= 2) return Array.isArray(value) ? `array(${value.length})` : 'object'
+  if (Array.isArray(value)) return `array(${value.length})[${value.slice(0, 6).map((item) => diagnosticShape(item, depth + 1)).join(',')}]`
+  const keys = Object.keys(value).sort()
+  const suffix = keys.length > 12 ? ',…' : ''
+  return `object{${keys.slice(0, 12).join(',')}${suffix}}`
+}
+
+export function diagnosticSummary(value) {
+  return diagnosticShape(value)
+}
+
 export function clone(value) {
   return value === undefined ? undefined : JSON.parse(JSON.stringify(value))
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p-dsh-market/conversation-knowledge-map",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "DSH 多对话思维导图与静态知识图谱",
   "keywords": [
     "dsh",