scene-capability-engine 3.6.27 → 3.6.29

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- Added shared `mb_status` language across studio task feedback and capability inventory scene advice for Magicball UI rendering.
+- Magicball docs now define the shared status-language contract for task cards and capability cards.
+
 ## [3.6.27] - 2026-03-06
 
 ### Added

package/README.md

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

package/README.zh.md

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

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

@@ -627,7 +627,7 @@ Studio JSON output now includes a stable UI-oriented task stream contract (in ad
 - `task.commands[]`: `cmd`, `exit_code`, `stdout`, `stderr`, `log_path`
 - `task.errors[]`: `message`, `error_bundle` (copy-ready diagnostic bundle)
 - `task.evidence[]`: structured evidence references
-- `task.feedback_model`: human-facing task feedback (`problem`, `execution`, `diagnosis`, `evidence`, `next_step`)
+- `task.feedback_model`: human-facing task feedback (`problem`, `execution`, `diagnosis`, `evidence`, `next_step`, `mb_status`)
 - `event[]`: raw audit event stream (`studio events` also keeps legacy `events[]` for compatibility)
 - `studio events --openhands-events <path>` switches `source_stream=openhands` and maps OpenHands raw events to the same task contract fields.
 - hierarchical task reference lookup/rerun:
@@ -1902,6 +1902,9 @@ 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`
 - Ontology mapping: `docs/ontology/capability-mapping.schema.json`
 
 ### Capability Library Reuse (query -> match -> use)

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

@@ -145,6 +145,7 @@ sce capability register --input <template.json> --json
 ## 5. 数据契约（前端对接）
 
 - UI 契约：`docs/agent-runtime/capability-iteration-ui.schema.json`
+- 统一状态语言：`docs/agent-runtime/magicball-status.schema.json`
 - 本体映射 schema：`docs/ontology/capability-mapping.schema.json`
 
 ---
@@ -227,3 +228,9 @@ sce capability register --input <template.json> --json
 
 - `summary_recommendations[]`：顶部全局建议
 - `quick_filters[]`：推荐快捷筛选
+
+## 15. Magicball 统一状态语言
+
+- Scene 卡片统一消费 `mb_status`
+- 任务卡统一消费 `task.feedback_model.mb_status`
+- 颜色建议：`danger / warning / info / success`

package/docs/magicball-capability-library.md

@@ -2,6 +2,8 @@
 
 > 目标：在 Magicball UI 中提供“能力库检索/匹配/使用”闭环，加速场景能力落地。
 
+Schema reference: `docs/agent-runtime/magicball-status.schema.json`
+
 ## 1. 能力库复用流程
 
 能力模板进入能力库前，默认要求补齐本体三项核心能力：
@@ -179,3 +181,14 @@ sce capability use --template <template-id> --spec <spec-id> --apply --json
   ]
 }
 ```
+
+### mb_status（统一状态语言）
+```json
+{
+  "attention_level": "critical",
+  "status_tone": "danger",
+  "status_label": "blocked",
+  "blocking_summary": "缺决策策略，暂不可发布",
+  "recommended_action": "补齐决策策略"
+}
+```

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

@@ -4,6 +4,12 @@
 
 ## 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`
+
+
 SCE 现在在 `task` 下增加：
 - `feedback_model.version`
 - `feedback_model.problem`
@@ -121,3 +127,14 @@ SCE 现在在时间线命令中增加：
 - 时间线优先展示“可恢复、可比较、可追踪”的节点信息
 - 所有字段都以 SCE 输出为准，Magicball 不自行推断
 
+
+## 6. Magicball 统一状态语言
+
+SCE 现在会在任务反馈模型中提供 `mb_status`：
+- `attention_level`
+- `status_tone`
+- `status_label`
+- `blocking_summary`
+- `recommended_action`
+
+Magicball 可直接用这组字段控制颜色、图标、提示文案。

package/lib/commands/capability.js

@@ -836,6 +836,17 @@ function resolveCapabilityTriadPriority(entry) {
   return 3;
 }
 
+function buildCapabilityMagicballStatus(input = {}) {
+  const attention = normalizeText(input.attention_level) || 'medium';
+  return {
+    attention_level: attention,
+    status_tone: attention === 'critical' ? 'danger' : (attention === 'high' ? 'warning' : (attention === 'low' ? 'success' : 'info')),
+    status_label: normalizeText(input.status_label) || null,
+    blocking_summary: normalizeText(input.blocking_summary) || null,
+    recommended_action: normalizeText(input.recommended_action) || null
+  };
+}
+
 function buildCapabilityInventorySceneAdvice(entry) {
   const sceneId = String(entry && entry.scene_id || 'scene.unknown');
   const releaseUi = entry && entry.release_readiness_ui ? entry.release_readiness_ui : { publish_ready: true, blocking_missing: [] };
@@ -886,7 +897,13 @@ function buildCapabilityInventorySceneAdvice(entry) {
     recommended_action: recommendedAction,
     blocking_summary: blockingSummary,
     next_action: nextAction,
-    next_command: 'sce capability extract --scene ' + sceneId + ' --json'
+    next_command: 'sce capability extract --scene ' + sceneId + ' --json',
+    mb_status: buildCapabilityMagicballStatus({
+      attention_level: attentionLevel,
+      status_label: releaseUi.publish_ready ? 'publish_ready' : 'blocked',
+      blocking_summary: blockingSummary,
+      recommended_action: recommendedAction
+    })
   };
 }
 
@@ -1854,6 +1871,7 @@ module.exports = {
   filterCapabilityCatalogEntries,
   filterCapabilityInventoryEntries,
   sortCapabilityInventoryEntries,
+  buildCapabilityMagicballStatus,
   buildCapabilityInventorySceneAdvice,
   buildCapabilityInventorySummaryStats,
   buildCapabilityInventorySummaryRecommendations,

package/lib/commands/studio.js

@@ -1537,6 +1537,20 @@ function buildTaskFeedbackModel(payload = {}) {
   };
 }
 
+function buildMagicballStatusLanguage(input = {}) {
+  const attention = normalizeString(input.attention_level) || 'medium';
+  const status = normalizeString(input.status) || 'unknown';
+  const blockingSummary = normalizeString(input.blocking_summary) || null;
+  const recommendedAction = normalizeString(input.recommended_action) || null;
+  return {
+    attention_level: attention,
+    status_tone: attention === 'critical' ? 'danger' : (attention === 'high' ? 'warning' : (attention === 'low' ? 'success' : 'info')),
+    status_label: status || 'unknown',
+    blocking_summary: blockingSummary,
+    recommended_action: recommendedAction
+  };
+}
+
 function attachTaskFeedbackModel(payload = {}) {
   if (!payload || typeof payload !== 'object' || !payload.task || typeof payload.task !== 'object') {
     return payload;
@@ -1545,7 +1559,7 @@ function attachTaskFeedbackModel(payload = {}) {
     ...payload,
     task: {
       ...payload.task,
-      feedback_model: buildTaskFeedbackModel(payload)
+      feedback_model: (() => { const model = buildTaskFeedbackModel(payload); return { ...model, mb_status: buildMagicballStatusLanguage({ status: model.execution.status, attention_level: model.diagnosis.root_cause_confidence === 'high' ? 'high' : (model.execution.status === 'completed' ? 'low' : 'medium'), blocking_summary: model.execution.blocking_summary, recommended_action: model.next_step.recommended_action }) }; })()
     }
   };
 }
@@ -3727,6 +3741,7 @@ module.exports = {
   runStudioReleaseCommand,
   runStudioRollbackCommand,
   runStudioEventsCommand,
+  buildMagicballStatusLanguage,
   runStudioPortfolioCommand,
   runStudioBackfillSpecScenesCommand,
   runStudioResumeCommand,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.6.27",
+  "version": "3.6.29",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {