scene-capability-engine 3.6.28 → 3.6.32

package/CHANGELOG.md

@@ -7,6 +7,29 @@ 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
+- Added shared Magicball schemas for status, task feedback, and timeline view contracts.
+- Command reference and Magicball integration docs now reference the shared schemas explicitly.
+
 ## [3.6.28] - 2026-03-06
 
 ### Added

package/README.md

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

package/README.zh.md

@@ -218,5 +218,5 @@ MIT，见 [LICENSE](LICENSE)。
 
 ---
 
-**版本**：3.6.28  
+**版本**：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/agent-runtime/magicball-status.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/magicball-status.schema.json",
+  "title": "Magicball Shared Status Contract",
+  "type": "object",
+  "required": [
+    "attention_level",
+    "status_tone",
+    "status_label",
+    "blocking_summary",
+    "recommended_action"
+  ],
+  "properties": {
+    "attention_level": {
+      "type": "string",
+      "enum": ["critical", "high", "medium", "low"]
+    },
+    "status_tone": {
+      "type": "string",
+      "enum": ["danger", "warning", "info", "success"]
+    },
+    "status_label": {
+      "type": ["string", "null"]
+    },
+    "blocking_summary": {
+      "type": ["string", "null"]
+    },
+    "recommended_action": {
+      "type": ["string", "null"]
+    }
+  },
+  "additionalProperties": false
+}

package/docs/agent-runtime/magicball-task-feedback.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/magicball-task-feedback.schema.json",
+  "title": "Magicball Task Feedback View Contract",
+  "type": "object",
+  "required": [
+    "version",
+    "problem",
+    "execution",
+    "diagnosis",
+    "evidence",
+    "next_step",
+    "mb_status"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "problem": {
+      "type": "object",
+      "required": ["component", "action", "expected", "actual"],
+      "properties": {
+        "component": { "type": ["string", "null"] },
+        "action": { "type": ["string", "null"] },
+        "expected": { "type": ["string", "null"] },
+        "actual": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "execution": {
+      "type": "object",
+      "required": ["stage", "status", "summary", "blocking_summary"],
+      "properties": {
+        "stage": { "type": "string" },
+        "status": { "type": "string" },
+        "summary": { "type": "array", "items": { "type": "string" } },
+        "blocking_summary": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "diagnosis": {
+      "type": "object",
+      "required": ["hypothesis", "chain_checkpoint", "root_cause_confidence"],
+      "properties": {
+        "hypothesis": { "type": ["string", "null"] },
+        "chain_checkpoint": { "type": "string" },
+        "root_cause_confidence": { "type": "string", "enum": ["low", "medium", "high"] }
+      },
+      "additionalProperties": false
+    },
+    "evidence": {
+      "type": "object",
+      "required": ["file_count", "file_paths", "command_count", "error_count", "verification_result", "regression_scope"],
+      "properties": {
+        "file_count": { "type": "integer", "minimum": 0 },
+        "file_paths": { "type": "array", "items": { "type": "string" } },
+        "command_count": { "type": "integer", "minimum": 0 },
+        "error_count": { "type": "integer", "minimum": 0 },
+        "verification_result": { "type": "string" },
+        "regression_scope": { "type": "array", "items": { "type": "string" } }
+      },
+      "additionalProperties": false
+    },
+    "next_step": {
+      "type": "object",
+      "required": ["recommended_action", "next_action", "next_command"],
+      "properties": {
+        "recommended_action": { "type": ["string", "null"] },
+        "next_action": { "type": ["string", "null"] },
+        "next_command": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "mb_status": {
+      "$ref": "./magicball-status.schema.json"
+    }
+  },
+  "additionalProperties": false
+}

package/docs/agent-runtime/magicball-timeline-view.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://scene-capability-engine.dev/contracts/magicball-timeline-view.schema.json",
+  "title": "Magicball Timeline View Contract",
+  "type": "object",
+  "required": ["summary", "entries"],
+  "properties": {
+    "summary": {
+      "type": "object",
+      "required": ["total", "latest_snapshot_id", "latest_created_at", "dirty_snapshot_count", "scene_count", "trigger_counts"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "latest_snapshot_id": { "type": ["string", "null"] },
+        "latest_created_at": { "type": ["string", "null"] },
+        "dirty_snapshot_count": { "type": "integer", "minimum": 0 },
+        "scene_count": { "type": "integer", "minimum": 0 },
+        "trigger_counts": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        }
+      },
+      "additionalProperties": false
+    },
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["snapshot_id", "title", "subtitle", "trigger", "event", "created_at", "scene_id", "session_id", "file_count", "branch", "head", "dirty_count", "attention_level", "show_command", "restore_command"],
+        "properties": {
+          "snapshot_id": { "type": ["string", "null"] },
+          "title": { "type": ["string", "null"] },
+          "subtitle": { "type": ["string", "null"] },
+          "trigger": { "type": ["string", "null"] },
+          "event": { "type": ["string", "null"] },
+          "created_at": { "type": ["string", "null"] },
+          "scene_id": { "type": ["string", "null"] },
+          "session_id": { "type": ["string", "null"] },
+          "file_count": { "type": "integer", "minimum": 0 },
+          "branch": { "type": ["string", "null"] },
+          "head": { "type": ["string", "null"] },
+          "dirty_count": { "type": "integer", "minimum": 0 },
+          "attention_level": { "type": "string", "enum": ["high", "medium", "low"] },
+          "show_command": { "type": ["string", "null"] },
+          "restore_command": { "type": ["string", "null"] }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/docs/command-reference.md

@@ -1902,6 +1902,11 @@ sce capability register --input .sce/reports/capability-iteration/scene.customer
 
 Schema references:
 - UI contract: `docs/agent-runtime/capability-iteration-ui.schema.json`
+- 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

@@ -145,6 +145,8 @@ sce capability register --input <template.json> --json
 ## 5. 数据契约（前端对接）
 
 - 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-capability-library.md

@@ -2,6 +2,8 @@
 
 > 目标：在 Magicball UI 中提供“能力库检索/匹配/使用”闭环，加速场景能力落地。
 
+Schema reference: `docs/agent-runtime/magicball-status.schema.json`
+
 ## 1. 能力库复用流程
 
 能力模板进入能力库前，默认要求补齐本体三项核心能力：

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

@@ -4,6 +4,13 @@
 
 ## 1. 任务反馈模型（来源：`sce studio events --json`）
 
+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` 下增加：
 - `feedback_model.version`
 - `feedback_model.problem`
@@ -132,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
+};