scene-capability-engine 3.6.64 → 3.6.67

package/lib/semantic/delta-export.js

@@ -0,0 +1,145 @@
+const fs = require('fs-extra');
+const path = require('path');
+const { getSceStateStore } = require('../state/sce-state-store');
+const { buildSemanticArchiveDecision } = require('./archive-routing');
+const {
+  resolveTargetLibrary,
+  buildCapabilityId
+} = require('./capability-contract');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeInteger(value, fallback = 0) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function normalizeStringArray(value, fallback = []) {
+  if (!Array.isArray(value)) {
+    return [...fallback];
+  }
+  return value
+    .map((item) => normalizeString(item))
+    .filter(Boolean);
+}
+
+function buildDeltaEntry(lesson = {}) {
+  const evidence = lesson.evidence && typeof lesson.evidence === 'object' ? lesson.evidence : {};
+  const promotion = evidence.promotion && typeof evidence.promotion === 'object' ? evidence.promotion : {};
+  const metadata = lesson.metadata && typeof lesson.metadata === 'object' ? lesson.metadata : {};
+  const publish = metadata.publish && typeof metadata.publish === 'object' ? metadata.publish : {};
+  const archive = metadata.archive && typeof metadata.archive === 'object'
+    ? metadata.archive
+    : buildSemanticArchiveDecision(lesson);
+  return {
+    capability_id: buildCapabilityId(lesson),
+    lesson_id: lesson.lesson_id,
+    target_library: normalizeString(archive.target_library) || resolveTargetLibrary(lesson),
+    scene_id: normalizeString(lesson.scene_id) || null,
+    spec_id: normalizeString(lesson.spec_id) || null,
+    lesson_type: normalizeString(lesson.lesson_type) || null,
+    title: normalizeString(lesson.title) || null,
+    summary: normalizeString(lesson.summary) || null,
+    heuristic: normalizeString(lesson.heuristic) || null,
+    confidence: typeof lesson.confidence === 'number' ? lesson.confidence : null,
+    status: normalizeString(lesson.status) || null,
+    lineage: {
+      observation_ids: normalizeStringArray([
+        evidence.observation_id
+      ], []),
+      evaluation_run_id: normalizeString(promotion.evaluation_run_id) || null
+    },
+    publication: {
+      consent_model: normalizeString(publish.consent_model) || 'adopt-implied',
+      publish_required: publish.publish_required === true,
+      publish_state: normalizeString(publish.publish_state) || 'pending',
+      queued_at: normalizeString(publish.queued_at) || null
+    },
+    archive,
+    sanitized: true
+  };
+}
+
+function resolveDefaultSemanticDeltaOutFile(specId = '') {
+  const normalizedSpecId = normalizeString(specId);
+  if (!normalizedSpecId) {
+    return '';
+  }
+  return `.sce/specs/${normalizedSpecId}/deltas/latest.json`;
+}
+
+async function exportSemanticLibraryDelta(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule,
+    noCache: dependencies.noCache === true
+  });
+  const projectId = normalizeString(options.project_id || options.projectId);
+  const specId = normalizeString(options.spec_id || options.specId);
+  const lessonId = normalizeString(options.lesson_id || options.lessonId);
+  const capabilityId = normalizeString(options.capability_id || options.capabilityId);
+  const limit = normalizeInteger(options.limit, 100);
+
+  let lessons = await store.listSemanticLessonCandidates({
+    project_id: projectId,
+    limit
+  });
+  lessons = Array.isArray(lessons) ? lessons : [];
+  lessons = lessons.filter((item) => {
+    if (normalizeString(item.status) !== 'publish_pending') {
+      return false;
+    }
+    if (specId && normalizeString(item.spec_id) !== specId) {
+      return false;
+    }
+    if (lessonId && normalizeString(item.lesson_id) !== lessonId) {
+      return false;
+    }
+    if (capabilityId && buildCapabilityId(item) !== capabilityId) {
+      return false;
+    }
+    return true;
+  });
+
+  const payload = {
+    mode: 'semantic-delta-export',
+    success: true,
+    generated_at: new Date().toISOString(),
+    project_id: projectId || null,
+    spec_id: specId || null,
+    total: lessons.length,
+    entries: lessons.map((item) => buildDeltaEntry(item))
+  };
+
+  const outFile = normalizeString(options.out_file || options.outFile)
+    || resolveDefaultSemanticDeltaOutFile(specId);
+  if (outFile) {
+    const absolutePath = path.isAbsolute(outFile)
+      ? outFile
+      : path.join(projectPath, outFile);
+    await fileSystem.ensureDir(path.dirname(absolutePath));
+    await fileSystem.writeJson(absolutePath, payload, { spaces: 2 });
+    payload.out_file = path.relative(projectPath, absolutePath).replace(/\\/g, '/');
+  }
+
+  return payload;
+}
+
+module.exports = {
+  resolveTargetLibrary,
+  buildCapabilityId,
+  buildDeltaEntry,
+  resolveDefaultSemanticDeltaOutFile,
+  exportSemanticLibraryDelta
+};

package/lib/semantic/interaction-observer.js

@@ -0,0 +1,254 @@
+const crypto = require('crypto');
+const { getSceStateStore } = require('../state/sce-state-store');
+const { buildSemanticArchiveDecision } = require('./archive-routing');
+
+function normalizeString(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeTextPreview(value, fallback = '') {
+  const normalized = normalizeString(value || fallback);
+  if (!normalized) {
+    return '';
+  }
+  return normalized.replace(/\s+/g, ' ').slice(0, 240);
+}
+
+function normalizeSignal(value, allowed, fallback) {
+  const normalized = normalizeString(value).toLowerCase();
+  if (allowed.has(normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+function inferIntent(payload = {}) {
+  const explicit = normalizeString(payload.intent);
+  if (explicit) {
+    return explicit;
+  }
+  const text = normalizeString(payload.text || payload.summary || '');
+  if (!text) {
+    return 'unknown';
+  }
+  const lowered = text.toLowerCase();
+  if (/(fix|repair|debug|trace|定位|修复)/.test(lowered)) {
+    return 'debug-or-repair';
+  }
+  if (/(plan|design|spec|requirements|tasks|方案|设计)/.test(lowered)) {
+    return 'planning';
+  }
+  if (/(test|verify|validation|回归|验证)/.test(lowered)) {
+    return 'verification';
+  }
+  if (/(explain|why|how|what|说明|解释|为什么|如何)/.test(lowered)) {
+    return 'analysis';
+  }
+  return 'general';
+}
+
+function inferOutcome(payload = {}) {
+  const explicit = normalizeString(payload.outcome);
+  if (explicit) {
+    return explicit;
+  }
+  const lowered = normalizeString(payload.text || payload.summary || '').toLowerCase();
+  if (/(failed|error|blocked|timeout|exception|失败|报错|阻塞)/.test(lowered)) {
+    return 'failed';
+  }
+  if (/(done|completed|success|resolved|完成|成功|已修复)/.test(lowered)) {
+    return 'succeeded';
+  }
+  return 'observed';
+}
+
+function inferQualitySignal(payload = {}) {
+  const explicit = normalizeString(payload.quality_signal || payload.qualitySignal);
+  if (explicit) {
+    return explicit;
+  }
+  const outcome = inferOutcome(payload);
+  if (outcome === 'failed') {
+    return 'negative';
+  }
+  if (outcome === 'succeeded') {
+    return 'positive';
+  }
+  return 'mixed';
+}
+
+function buildObservationSummary(payload = {}) {
+  const explicit = normalizeTextPreview(payload.summary);
+  if (explicit) {
+    return explicit;
+  }
+  return normalizeTextPreview(payload.text, `${payload.source_runtime || payload.sourceRuntime || 'runtime'} ${payload.event_kind || payload.eventKind || 'event'}`);
+}
+
+function normalizeSemanticObservation(payload = {}) {
+  const sourceRuntime = normalizeString(payload.source_runtime || payload.sourceRuntime).toLowerCase();
+  const eventKind = normalizeString(payload.event_kind || payload.eventKind).toLowerCase();
+  if (!sourceRuntime) {
+    throw new Error('source_runtime is required');
+  }
+  if (!eventKind) {
+    throw new Error('event_kind is required');
+  }
+
+  const rawPayload = payload.raw_payload && typeof payload.raw_payload === 'object'
+    ? payload.raw_payload
+    : (payload.rawPayload && typeof payload.rawPayload === 'object' ? payload.rawPayload : {});
+  const text = normalizeTextPreview(payload.text || payload.message || payload.content);
+  const summary = buildObservationSummary({
+    ...payload,
+    text
+  });
+  const normalized = {
+    observation_id: normalizeString(payload.observation_id || payload.observationId) || null,
+    project_id: normalizeString(payload.project_id || payload.projectId) || null,
+    channel_id: normalizeString(payload.channel_id || payload.channelId) || null,
+    session_id: normalizeString(payload.session_id || payload.sessionId) || null,
+    scene_id: normalizeString(payload.scene_id || payload.sceneId) || null,
+    spec_id: normalizeString(payload.spec_id || payload.specId) || null,
+    task_ref: normalizeString(payload.task_ref || payload.taskRef) || null,
+    source_runtime: sourceRuntime,
+    source_kind: normalizeString(payload.source_kind || payload.sourceKind) || 'embedded-host',
+    host_session_id: normalizeString(payload.host_session_id || payload.hostSessionId) || null,
+    event_kind: eventKind,
+    role: normalizeString(payload.role).toLowerCase() || null,
+    intent: inferIntent({ ...payload, text }),
+    summary,
+    outcome: normalizeSignal(inferOutcome({ ...payload, text }), new Set(['observed', 'succeeded', 'failed', 'blocked']), 'observed'),
+    quality_signal: normalizeSignal(
+      inferQualitySignal({ ...payload, text }),
+      new Set(['positive', 'negative', 'mixed', 'unknown']),
+      'mixed'
+    ),
+    raw_ref: normalizeString(payload.raw_ref || payload.rawRef) || null,
+    raw_payload: {
+      text,
+      ...rawPayload
+    },
+    normalized_payload: {
+      text,
+      summary,
+      role: normalizeString(payload.role).toLowerCase() || null,
+      intent: inferIntent({ ...payload, text }),
+      outcome: normalizeSignal(inferOutcome({ ...payload, text }), new Set(['observed', 'succeeded', 'failed', 'blocked']), 'observed'),
+      quality_signal: normalizeSignal(
+        inferQualitySignal({ ...payload, text }),
+        new Set(['positive', 'negative', 'mixed', 'unknown']),
+        'mixed'
+      ),
+      metadata: payload.metadata && typeof payload.metadata === 'object' ? payload.metadata : {}
+    },
+    created_at: normalizeString(payload.created_at || payload.createdAt) || null,
+    updated_at: normalizeString(payload.updated_at || payload.updatedAt) || null
+  };
+
+  return normalized;
+}
+
+function buildLessonFingerprint(observation = {}) {
+  const basis = JSON.stringify({
+    project_id: normalizeString(observation.project_id),
+    scene_id: normalizeString(observation.scene_id),
+    spec_id: normalizeString(observation.spec_id),
+    source_runtime: normalizeString(observation.source_runtime),
+    intent: normalizeString(observation.intent),
+    outcome: normalizeString(observation.outcome),
+    quality_signal: normalizeString(observation.quality_signal)
+  });
+  return crypto.createHash('sha1').update(basis).digest('hex').slice(0, 16);
+}
+
+function deriveLessonCandidate(observation = {}) {
+  const qualitySignal = normalizeString(observation.quality_signal);
+  const outcome = normalizeString(observation.outcome);
+  const shouldPromote = qualitySignal === 'positive' || qualitySignal === 'negative' || outcome === 'failed';
+  if (!shouldPromote) {
+    return null;
+  }
+
+  const lessonType = qualitySignal === 'negative' || outcome === 'failed'
+    ? 'failure-pattern'
+    : 'success-pattern';
+  const fingerprint = buildLessonFingerprint(observation);
+  const title = lessonType === 'failure-pattern'
+    ? `[${observation.source_runtime}] Avoid ${observation.intent || observation.event_kind}`
+    : `[${observation.source_runtime}] Reuse ${observation.intent || observation.event_kind}`;
+  const summary = lessonType === 'failure-pattern'
+    ? `Observed ${observation.intent || observation.event_kind} leading to ${outcome || 'negative outcome'} in project context.`
+    : `Observed ${observation.intent || observation.event_kind} leading to successful outcome in project context.`;
+  const heuristic = lessonType === 'failure-pattern'
+    ? `When handling ${observation.intent || observation.event_kind}, add stronger verification or narrower scoping before execution.`
+    : `When handling ${observation.intent || observation.event_kind}, preserve the successful structure captured in the observation evidence.`;
+
+  const lesson = {
+    project_id: observation.project_id,
+    scene_id: observation.scene_id,
+    spec_id: observation.spec_id,
+    source_runtime: observation.source_runtime,
+    fingerprint,
+    lesson_type: lessonType,
+    title,
+    summary,
+    heuristic,
+    confidence: lessonType === 'failure-pattern' ? 0.75 : 0.7,
+    status: 'candidate',
+    evidence: {
+      observation_id: observation.observation_id,
+      task_ref: observation.task_ref,
+      quality_signal: observation.quality_signal,
+      outcome: observation.outcome
+    },
+    metadata: {
+      channel_id: observation.channel_id,
+      session_id: observation.session_id,
+      event_kind: observation.event_kind
+    }
+  };
+  return {
+    ...lesson,
+    metadata: {
+      ...lesson.metadata,
+      archive: buildSemanticArchiveDecision(lesson)
+    }
+  };
+}
+
+async function observeSemanticInteraction(payload = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.stateStore || getSceStateStore(projectPath, {
+    fileSystem: dependencies.fileSystem,
+    env: dependencies.env,
+    sqliteModule: dependencies.sqliteModule,
+    noCache: dependencies.noCache === true
+  });
+
+  const normalizedObservation = normalizeSemanticObservation(payload);
+  const observation = await store.appendSemanticObservation(normalizedObservation);
+  if (!observation) {
+    throw new Error('Failed to persist semantic observation');
+  }
+
+  const lessonCandidate = deriveLessonCandidate(observation);
+  const lesson = lessonCandidate
+    ? await store.upsertSemanticLessonCandidate(lessonCandidate)
+    : null;
+
+  return {
+    observation,
+    lesson_candidate: lesson
+  };
+}
+
+module.exports = {
+  normalizeSemanticObservation,
+  buildLessonFingerprint,
+  deriveLessonCandidate,
+  observeSemanticInteraction
+};