scene-capability-engine 3.6.29 → 3.6.32

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.32] - 2026-03-07
+
+### Fixed
+- Restored auto session/governance retention and stats CLI paths after refactor, including full integration coverage for version/legacy/takeover/auto flows.
+
+## [3.6.31] - 2026-03-07
+
+### Added
+- Continued refactor pass: extracted command-adjacent Magicball, capability, studio, scene, and auto helper/service modules to reduce top-heavy command files.
+- Added Magicball contract index to make schema discovery and frontend adaptation deterministic.
+
+## [3.6.30] - 2026-03-07
+
+### Added
+- Continued internal refactor: extracted shared Magicball modules, capability services, studio task envelope/intents, scene doctor helpers, and auto session metrics helpers.
+- Added Magicball contract index for schema/discovery entrypoint.
+
 ## [3.6.29] - 2026-03-06
 
 ### Added

package/README.md

@@ -218,5 +218,5 @@ MIT. See [LICENSE](LICENSE).
 
 ---
 
-**Version**: 3.6.29  
+**Version**: 3.6.32  
 **Last Updated**: 2026-03-05

package/README.zh.md

@@ -218,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.29  
+**版本**：3.6.32  
 **最后更新**：2026-03-05

package/docs/agent-runtime/magicball-contract-index.md

@@ -0,0 +1,25 @@
+# Magicball Contract Index
+
+Schema references:
+- `docs/agent-runtime/magicball-status.schema.json`
+- `docs/agent-runtime/magicball-task-feedback.schema.json`
+- `docs/agent-runtime/magicball-timeline-view.schema.json`
+- `docs/agent-runtime/capability-iteration-ui.schema.json`
+
+Recommended consumption order:
+1. `magicball-status.schema.json`
+2. `magicball-task-feedback.schema.json`
+3. `magicball-timeline-view.schema.json`
+4. `capability-iteration-ui.schema.json`
+
+Usage mapping:
+- Task cards: `task.feedback_model`
+- Timeline panels: `timeline list/show -> view_model`
+- Capability inventory homepage: `capability inventory`
+
+Implementation modules:
+- `lib/magicball/status-language.js`
+- `lib/magicball/task-feedback-model.js`
+- `lib/magicball/capability-inventory-view-model.js`
+- `lib/magicball/timeline-view-model.js`
+- `lib/capability/inventory-service.js`

package/docs/command-reference.md

@@ -1905,6 +1905,8 @@ Schema references:
 - Magicball shared status: `docs/agent-runtime/magicball-status.schema.json`
 - Magicball task feedback: `docs/agent-runtime/magicball-task-feedback.schema.json`
 - Magicball timeline view: `docs/agent-runtime/magicball-timeline-view.schema.json`
+- Magicball contract index: `docs/agent-runtime/magicball-contract-index.md`
+  Implementation modules are listed in the contract index for internal maintainers.
 - Ontology mapping: `docs/ontology/capability-mapping.schema.json`
 
 ### Capability Library Reuse (query -> match -> use)

package/docs/magicball-capability-iteration-ui.md

@@ -146,6 +146,7 @@ sce capability register --input <template.json> --json
 
 - UI 契约：`docs/agent-runtime/capability-iteration-ui.schema.json`
 - 统一状态语言：`docs/agent-runtime/magicball-status.schema.json`
+- 契约索引：`docs/agent-runtime/magicball-contract-index.md`
 - 本体映射 schema：`docs/ontology/capability-mapping.schema.json`
 
 ---

package/docs/magicball-task-feedback-timeline-guide.md

@@ -8,6 +8,7 @@ Schema references:
 - `docs/agent-runtime/magicball-status.schema.json`
 - `docs/agent-runtime/magicball-task-feedback.schema.json`
 - `docs/agent-runtime/magicball-timeline-view.schema.json`
+- `docs/agent-runtime/magicball-contract-index.md`
 
 
 SCE 现在在 `task` 下增加：
@@ -138,3 +139,10 @@ SCE 现在会在任务反馈模型中提供 `mb_status`：
 - `recommended_action`
 
 Magicball 可直接用这组字段控制颜色、图标、提示文案。
+
+## 7. 维护说明
+
+- 共享实现位于 `lib/magicball/*`
+- `studio` 命令只负责任务流编排与事件产出
+- `timeline` 命令只负责快照读写与 view model 挂载
+- 共享契约入口：`docs/agent-runtime/magicball-contract-index.md`

package/lib/auto/session-metrics.js

@@ -0,0 +1,53 @@
+function buildStatusCounts(entries = [], normalizeStatusToken = (value) => value) {
+  const counts = {};
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  for (const entry of safeEntries) {
+    const status = normalizeStatusToken(entry && entry.status) || 'unknown';
+    counts[status] = (counts[status] || 0) + 1;
+  }
+  return counts;
+}
+
+function buildQueueFormatCounts(entries = []) {
+  const counts = {};
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  for (const entry of safeEntries) {
+    const format = String(entry && entry.queue_format ? entry.queue_format : '').trim().toLowerCase() || 'unknown';
+    counts[format] = (counts[format] || 0) + 1;
+  }
+  return counts;
+}
+
+function buildMasterSpecCounts(entries = []) {
+  const counts = {};
+  const safeEntries = Array.isArray(entries) ? entries : [];
+  for (const entry of safeEntries) {
+    const masterSpec = String(entry && entry.master_spec ? entry.master_spec : '').trim();
+    if (!masterSpec) {
+      continue;
+    }
+    counts[masterSpec] = (counts[masterSpec] || 0) + 1;
+  }
+  return counts;
+}
+
+function buildTopCountEntries(counterMap, limit = 10) {
+  const source = counterMap && typeof counterMap === 'object' ? counterMap : {};
+  const maxItems = Number.isInteger(limit) && limit > 0 ? limit : 10;
+  return Object.entries(source)
+    .map(([key, count]) => ({ key, count: Number(count) || 0 }))
+    .sort((left, right) => {
+      if (right.count !== left.count) {
+        return right.count - left.count;
+      }
+      return left.key.localeCompare(right.key);
+    })
+    .slice(0, maxItems);
+}
+
+module.exports = {
+  buildStatusCounts,
+  buildQueueFormatCounts,
+  buildMasterSpecCounts,
+  buildTopCountEntries
+};

package/lib/capability/catalog-service.js

@@ -0,0 +1,248 @@
+const path = require('path');
+const fsExtra = require('fs-extra');
+const TemplateManager = require('../templates/template-manager');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeText(String(value || '')).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function toPositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+async function listCapabilityCatalogService(options = {}, dependencies = {}) {
+  const manager = dependencies.manager || new TemplateManager();
+  const templates = dependencies.filterCapabilityCatalogEntries((await manager.listTemplates({
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  })).map((template) => dependencies.enrichCapabilityTemplateForUi(template)), options);
+  return {
+    mode: 'capability-catalog-list',
+    templates
+  };
+}
+
+async function searchCapabilityCatalogService(keyword, options = {}, dependencies = {}) {
+  const manager = dependencies.manager || new TemplateManager();
+  const templates = dependencies.filterCapabilityCatalogEntries((await manager.searchTemplates(keyword, {
+    category: options.category,
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  })).map((template) => dependencies.enrichCapabilityTemplateForUi(template)), options);
+  return {
+    mode: 'capability-catalog-search',
+    keyword,
+    templates
+  };
+}
+
+async function showCapabilityTemplateService(templatePath, options = {}, dependencies = {}) {
+  const manager = dependencies.manager || new TemplateManager();
+  const template = dependencies.enrichCapabilityTemplateForUi(await manager.showTemplate(templatePath));
+  const parsed = dependencies.parseTemplatePath(templatePath);
+  await manager.ensureCached(parsed.sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(parsed.sourceName);
+  const templateDir = path.join(sourcePath, parsed.templateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fsExtra.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fsExtra.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+  return {
+    mode: 'capability-catalog-show',
+    template,
+    template_file: await fsExtra.pathExists(capabilityFile) ? capabilityFile : null,
+    payload: templatePayload
+  };
+}
+
+async function matchCapabilityTemplatesService(options = {}, dependencies = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fsExtra;
+  const specId = normalizeText(options.spec || options.specId);
+  if (!specId) {
+    throw new Error('spec is required for capability match');
+  }
+  const chain = await dependencies.loadSpecDomainChain(projectPath, specId, fileSystem);
+  if (!chain.exists && normalizeBoolean(options.strict, false)) {
+    throw new Error('problem-domain-chain missing for spec ' + specId);
+  }
+  if (chain.error && normalizeBoolean(options.strict, false)) {
+    throw new Error('problem-domain-chain invalid: ' + chain.error);
+  }
+  const domainChain = chain.payload || {};
+  const specScope = dependencies.buildOntologyScopeFromChain(domainChain);
+  const queryTokens = dependencies.normalizeTokenList(options.query)
+    .concat(dependencies.normalizeTokenList(domainChain.problem && domainChain.problem.statement))
+    .concat(dependencies.normalizeTokenList(domainChain.scene_id));
+  const manager = dependencies.manager || new TemplateManager();
+  const templates = await manager.listTemplates({
+    source: options.source,
+    templateType: 'capability-template',
+    compatibleWith: options.compatibleWith,
+    riskLevel: options.risk
+  });
+  const matches = templates.map((template) => {
+    const overlap = dependencies.buildOntologyOverlap(specScope, template.ontology_scope || {});
+    const scenarioScore = template.applicable_scenarios && domainChain.scene_id
+      ? (template.applicable_scenarios.includes(domainChain.scene_id) ? 1 : 0)
+      : 0;
+    const keywordScore = dependencies.buildKeywordScore(template, queryTokens);
+    const totalScore = (overlap.score * 0.6) + (scenarioScore * 0.2) + (keywordScore * 0.2);
+    const ontologyCore = template.ontology_core || dependencies.buildCoreOntologySummary(template.ontology_scope || {});
+    return {
+      template_id: template.id,
+      source: template.source,
+      name: template.name,
+      description: template.description,
+      category: template.category,
+      risk_level: template.risk_level,
+      ontology_core: ontologyCore,
+      ontology_core_ui: dependencies.buildOntologyCoreUiState(ontologyCore),
+      score: Math.round(totalScore * 100),
+      score_components: {
+        ontology: Number(overlap.score.toFixed(3)),
+        scenario: scenarioScore,
+        keyword: Number(keywordScore.toFixed(3))
+      },
+      overlap
+    };
+  }).sort((a, b) => b.score - a.score);
+
+  const limit = toPositiveInteger(options.limit, 10);
+  return {
+    mode: 'capability-match',
+    spec_id: specId,
+    scene_id: domainChain.scene_id || null,
+    query: normalizeText(options.query) || null,
+    ontology_source: chain.exists ? chain.path : null,
+    match_count: matches.length,
+    matches: matches.slice(0, limit),
+    warnings: chain.exists ? [] : ['problem-domain-chain missing; ontology-based match unavailable']
+  };
+}
+
+async function useCapabilityTemplateService(options = {}, dependencies = {}) {
+  const projectPath = options.projectPath || process.cwd();
+  const fileSystem = options.fileSystem || fsExtra;
+  const templateId = normalizeText(options.template || options.id);
+  if (!templateId) {
+    throw new Error('template is required for capability use');
+  }
+  if (normalizeBoolean(options.apply, false) && normalizeBoolean(options.write, true) === false) {
+    throw new Error('cannot use --apply with --no-write');
+  }
+  const specId = normalizeText(options.spec || options.specId) || null;
+  const manager = dependencies.manager || new TemplateManager();
+  const template = await manager.showTemplate(templateId);
+  const parsed = dependencies.parseTemplatePath(templateId);
+  await manager.ensureCached(parsed.sourceName);
+  const sourcePath = manager.cacheManager.getSourceCachePath(parsed.sourceName);
+  const templateDir = path.join(sourcePath, parsed.templateId);
+  const capabilityFile = path.join(templateDir, 'capability-template.json');
+  let templatePayload = null;
+  if (await fileSystem.pathExists(capabilityFile)) {
+    try {
+      templatePayload = await fileSystem.readJson(capabilityFile);
+    } catch (_error) {
+      templatePayload = null;
+    }
+  }
+
+  const recommendedTasks = [];
+  if (templatePayload && templatePayload.source_candidate && Array.isArray(templatePayload.source_candidate.specs)) {
+    templatePayload.source_candidate.specs.forEach((spec) => {
+      const sample = Array.isArray(spec.task_sample) ? spec.task_sample : [];
+      sample.forEach((task) => {
+        if (task && task.title) {
+          recommendedTasks.push({
+            title: task.title,
+            source_spec_id: spec.spec_id || null,
+            source_task_id: task.id || null
+          });
+        }
+      });
+    });
+  }
+  if (recommendedTasks.length === 0) {
+    recommendedTasks.push({ title: 'Implement capability scope: ' + (template.name || parsed.templateId) });
+  }
+
+  const ontologyCore = template.ontology_core || dependencies.buildCoreOntologySummary(template.ontology_scope || {});
+  const plan = {
+    mode: 'capability-use-plan',
+    generated_at: new Date().toISOString(),
+    template: {
+      id: template.id,
+      name: template.name,
+      source: template.source,
+      description: template.description,
+      ontology_scope: template.ontology_scope || {},
+      ontology_core: ontologyCore,
+      ontology_core_ui: dependencies.buildOntologyCoreUiState(ontologyCore)
+    },
+    spec_id: specId,
+    recommended_tasks: recommendedTasks
+  };
+
+  const outputPath = normalizeText(options.out) || dependencies.buildDefaultUsePlanPath(specId || 'spec', template.id);
+  if (normalizeBoolean(options.write, true)) {
+    await fileSystem.ensureDir(path.dirname(path.join(projectPath, outputPath)));
+    await fileSystem.writeJson(path.join(projectPath, outputPath), plan, { spaces: 2 });
+    plan.output_file = outputPath;
+  }
+
+  if (normalizeBoolean(options.apply, false)) {
+    if (!specId) {
+      throw new Error('spec is required for --apply');
+    }
+    plan.apply = await dependencies.appendCapabilityPlanToSpecTasks({
+      projectPath,
+      spec: specId,
+      sectionTitle: options.sectionTitle
+    }, plan, fileSystem);
+  }
+
+  return plan;
+}
+
+module.exports = {
+  listCapabilityCatalogService,
+  searchCapabilityCatalogService,
+  showCapabilityTemplateService,
+  matchCapabilityTemplatesService,
+  useCapabilityTemplateService
+};

package/lib/capability/inventory-service.js

@@ -0,0 +1,100 @@
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeText(String(value || '')).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function toPositiveInteger(value, fallback) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+async function runCapabilityInventoryService(options = {}, dependencies = {}) {
+  const sceneIds = Array.isArray(dependencies.sceneIds) ? dependencies.sceneIds : [];
+  const limit = toPositiveInteger(options.limit, sceneIds.length || 20);
+  const scenes = [];
+
+  for (const sceneId of sceneIds.slice(0, limit)) {
+    const candidate = await dependencies.buildCandidatePayload(sceneId, {
+      specs: options.specs,
+      sample_limit: options.sample_limit
+    }, dependencies.runtime || {});
+    const score = dependencies.buildScoreFromCandidate(candidate);
+    const releaseReadiness = dependencies.buildCapabilityReleaseReadiness({
+      scene_id: sceneId,
+      ontology_scope: candidate.ontology_scope,
+      ontology_core: candidate.ontology_core
+    });
+    const sceneEntry = {
+      scene_id: sceneId,
+      summary: candidate.summary,
+      source: candidate.source,
+      ontology_scope: candidate.ontology_scope,
+      ontology_core: candidate.ontology_core,
+      ontology_core_ui: dependencies.buildOntologyCoreUiState(candidate.ontology_core),
+      release_readiness: releaseReadiness,
+      release_readiness_ui: dependencies.buildCapabilityReleaseReadinessUi(releaseReadiness),
+      score_preview: score
+    };
+    scenes.push({
+      ...sceneEntry,
+      ...dependencies.buildCapabilityInventorySceneAdvice(sceneEntry)
+    });
+  }
+
+  const filteredScenes = dependencies.sortCapabilityInventoryEntries(
+    dependencies.filterCapabilityInventoryEntries(scenes, options)
+  );
+  const summaryStats = dependencies.buildCapabilityInventorySummaryStats(filteredScenes);
+  const releaseReadyFilterRaw = normalizeText(options.releaseReady || options.release_ready).toLowerCase();
+
+  return {
+    mode: 'capability-inventory',
+    generated_at: new Date().toISOString(),
+    query: {
+      protocol_version: '1.0',
+      scene_id: normalizeText(options.scene || options.sceneId || options.scene_id) || null,
+      limit,
+      sample_limit: toPositiveInteger(options.sample_limit, 5),
+      filters: {
+        release_ready: releaseReadyFilterRaw ? ['1', 'true', 'yes', 'ready'].includes(releaseReadyFilterRaw) : null,
+        missing_triad: normalizeText(options.missingTriad || options.missing_triad) || null
+      }
+    },
+    scene_total: scenes.length,
+    scene_count: filteredScenes.length,
+    summary_stats: summaryStats,
+    summary_recommendations: dependencies.buildCapabilityInventorySummaryRecommendations(filteredScenes),
+    quick_filters: dependencies.buildCapabilityInventoryQuickFilters(summaryStats),
+    sort: {
+      strategy: 'publish_ready -> missing_triad_priority -> value_score_desc -> scene_id',
+      triad_priority: ['decision_strategy', 'business_rules', 'entity_relation']
+    },
+    scenes: filteredScenes
+  };
+}
+
+module.exports = {
+  runCapabilityInventoryService
+};

package/lib/commands/auto.js

@@ -1,4 +1,4 @@
-/**
+/**
  * Autonomous Control CLI Commands
  */