scene-capability-engine 3.6.26 → 3.6.27

package/CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.27] - 2026-03-06
+
+### Added
+- Studio task payloads now expose `task.feedback_model` for human-facing task cards.
+- Timeline list/show payloads now expose `view_model` for Magicball timeline panels.
+- Added `docs/magicball-task-feedback-timeline-guide.md`.
+
 ## [3.6.26] - 2026-03-06
 
 ### Added

package/README.md

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

package/README.zh.md

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

package/docs/command-reference.md

@@ -627,6 +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`)
 - `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:

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

@@ -0,0 +1,123 @@
+# Magicball Task Feedback + Timeline Integration Guide
+
+> 目标：让 Magicball 在不直接消费底层事件流/快照原始结构的情况下，使用 SCE 的稳定任务反馈模型与时间线视图模型。
+
+## 1. 任务反馈模型（来源：`sce studio events --json`）
+
+SCE 现在在 `task` 下增加：
+- `feedback_model.version`
+- `feedback_model.problem`
+- `feedback_model.execution`
+- `feedback_model.diagnosis`
+- `feedback_model.evidence`
+- `feedback_model.next_step`
+
+### 1.1 字段说明
+
+- `problem.component`：当前问题所属组件/scene
+- `problem.action`：当前动作或阶段
+- `problem.expected`：期望结果
+- `problem.actual`：实际结果
+
+- `execution.stage`：当前阶段（plan/generate/apply/verify/release/rollback/events）
+- `execution.status`：当前状态
+- `execution.summary[]`：3 行以内摘要
+- `execution.blocking_summary`：阻断摘要
+
+- `diagnosis.hypothesis`：当前根因假设/错误摘要
+- `diagnosis.chain_checkpoint`：定位链路检查点
+- `diagnosis.root_cause_confidence`：根因判断置信度（low/medium/high）
+
+- `evidence.file_count` / `evidence.file_paths[]`
+- `evidence.command_count` / `evidence.error_count`
+- `evidence.verification_result`
+- `evidence.regression_scope[]`
+
+- `next_step.recommended_action`：面向人的下一步建议
+- `next_step.next_action`：动作 key
+- `next_step.next_command`：推荐命令
+
+### 1.2 Magicball UI 建议
+
+任务卡默认显示：
+1. `problem.expected / actual`
+2. `execution.summary`
+3. `execution.blocking_summary`
+4. `next_step.recommended_action`
+5. `evidence.file_paths`（最多前 3-5 个）
+
+事件流 `event[]` 保留为“展开查看”，不再作为主视图。
+
+## 2. 时间线视图模型（来源：`sce timeline list/show --json`）
+
+SCE 现在在时间线命令中增加：
+- `view_model.summary`
+- `view_model.entries[]`（list）
+- `view_model.snapshot`（show）
+- `view_model.files_preview[]`（show）
+
+### 2.1 timeline list
+
+关键字段：
+- `view_model.summary.total`
+- `view_model.summary.latest_snapshot_id`
+- `view_model.summary.latest_created_at`
+- `view_model.summary.dirty_snapshot_count`
+- `view_model.summary.scene_count`
+- `view_model.summary.trigger_counts`
+- `view_model.entries[]`
+
+每个 entry：
+- `snapshot_id`
+- `title`
+- `subtitle`
+- `created_at`
+- `scene_id`
+- `file_count`
+- `attention_level`
+- `show_command`
+- `restore_command`
+
+### 2.2 timeline show
+
+关键字段：
+- `view_model.snapshot`
+- `view_model.files_preview[]`
+- `view_model.file_total`
+- `view_model.restore_command`
+
+### 2.3 Magicball UI 建议
+
+时间线面板建议两层：
+- 列表层：使用 `view_model.entries[]` 渲染时间线卡片
+- 详情层：使用 `view_model.snapshot + files_preview` 渲染快照详情
+
+默认展示：
+- 快照标题
+- 创建时间
+- 关联 scene
+- 文件数
+- attention level
+- “查看详情 / 恢复” 按钮
+
+## 3. 推荐对接顺序
+
+1. 任务面板先接 `task.feedback_model`
+2. 再把 `event[]` 放到“高级模式”
+3. 时间线首页接 `timeline list.view_model`
+4. 时间线详情页接 `timeline show.view_model`
+
+## 4. 最小接口清单
+
+- `sce studio events --job <job-id> --json`
+- `sce studio events --job <job-id> --openhands-events <path> --json`
+- `sce timeline list --limit 20 --json`
+- `sce timeline show <snapshot-id> --json`
+
+## 5. 设计原则
+
+- 主视图优先展示“人可判断信息”，不是原始事件流
+- 事件流保留为审计层，不作为第一视图
+- 时间线优先展示“可恢复、可比较、可追踪”的节点信息
+- 所有字段都以 SCE 输出为准，Magicball 不自行推断
+

package/lib/commands/studio.js

@@ -1460,6 +1460,95 @@ function buildTaskAcceptanceCriteria(stageName = '', job = {}, nextAction = '')
   ];
 }
 
+function buildTaskFeedbackModel(payload = {}) {
+  const task = payload && payload.task && typeof payload.task === 'object' ? payload.task : {};
+  const handoff = task && typeof task.handoff === 'object' ? task.handoff : {};
+  const errors = Array.isArray(task.errors) ? task.errors : [];
+  const commands = Array.isArray(task.commands) ? task.commands : [];
+  const fileChanges = Array.isArray(task.file_changes) ? task.file_changes : [];
+  const evidence = Array.isArray(task.evidence) ? task.evidence : [];
+  const acceptance = Array.isArray(task.acceptance_criteria) ? task.acceptance_criteria : [];
+  const firstError = errors[0] || {};
+  const stage = normalizeString(handoff.stage) || 'task';
+  const status = normalizeString(task.status) || 'unknown';
+  const problemComponent = normalizeString(handoff.component) || normalizeString(payload.sceneId) || null;
+  const expected = normalizeString(acceptance[0]) || ('Complete ' + stage + ' stage successfully');
+  const actual = normalizeString(firstError.message) || ('Current status: ' + status);
+
+  let chainCheckpoint = 'task-envelope';
+  if (errors.length > 0 && commands.length > 0) {
+    chainCheckpoint = 'command-execution';
+  } else if (errors.length > 0) {
+    chainCheckpoint = 'stage-gate';
+  } else if (fileChanges.length > 0) {
+    chainCheckpoint = 'patch-applied';
+  } else if (evidence.length > 0) {
+    chainCheckpoint = 'evidence-collected';
+  }
+
+  let confidence = 'low';
+  if (errors.length > 0) {
+    confidence = 'medium';
+  } else if (status === 'completed') {
+    confidence = 'high';
+  }
+
+  let recommendedAction = '继续当前阶段';
+  if (errors.length > 0) {
+    recommendedAction = '处理阻断后重试';
+  } else if (status === 'completed' && normalizeString(task.next_action) && normalizeString(task.next_action) !== 'complete') {
+    recommendedAction = '执行下一阶段';
+  } else if (status === 'completed') {
+    recommendedAction = '任务完成';
+  }
+
+  return {
+    version: '1.0',
+    problem: {
+      component: problemComponent,
+      action: normalizeString(handoff.action) || stage,
+      expected,
+      actual
+    },
+    execution: {
+      stage,
+      status,
+      summary: Array.isArray(task.summary) ? task.summary.slice(0, 3) : [],
+      blocking_summary: normalizeString(handoff.blocking_summary) || normalizeString(firstError.message) || null
+    },
+    diagnosis: {
+      hypothesis: normalizeString(firstError.error_bundle) || normalizeString(firstError.message) || normalizeString(handoff.reason) || null,
+      chain_checkpoint: chainCheckpoint,
+      root_cause_confidence: confidence
+    },
+    evidence: {
+      file_count: fileChanges.length,
+      file_paths: fileChanges.slice(0, 5).map((item) => normalizeString(item && item.path)).filter(Boolean),
+      command_count: commands.length,
+      error_count: errors.length,
+      verification_result: status === 'completed' ? 'passed-or-advanced' : (errors.length > 0 ? 'blocked' : 'in-progress'),
+      regression_scope: Array.isArray(handoff.regression_scope) ? handoff.regression_scope : []
+    },
+    next_step: {
+      recommended_action: recommendedAction,
+      next_action: normalizeString(task.next_action) || null,
+      next_command: normalizeString(task.next_action) || null
+    }
+  };
+}
+
+function attachTaskFeedbackModel(payload = {}) {
+  if (!payload || typeof payload !== 'object' || !payload.task || typeof payload.task !== 'object') {
+    return payload;
+  }
+  return {
+    ...payload,
+    task: {
+      ...payload.task,
+      feedback_model: buildTaskFeedbackModel(payload)
+    }
+  };
+}
 function buildTaskEnvelope(mode, job, options = {}) {
   const stageName = resolveTaskStage(mode, job, options.stageName);
   const stageState = stageName && job && job.stages && job.stages[stageName]
@@ -2039,13 +2128,13 @@ async function buildCommandPayload(mode, job, options = {}) {
     next_action: resolveNextAction(job),
     artifacts: { ...job.artifacts }
   };
-  return {
+  return attachTaskFeedbackModel({
     ...base,
     ...buildTaskEnvelope(mode, job, {
       ...options,
       taskRef
     })
-  };
+  });
 }
 
 function buildJobDomainChainMetadata(job = {}) {
@@ -3308,7 +3397,9 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
       : null;
   }
   payload.events = events;
-  printStudioEventsPayload(payload, options);
+  const normalizedPayload = attachTaskFeedbackModel(payload);
+  printStudioEventsPayload(normalizedPayload, options);
+  return normalizedPayload;
   return payload;
 }
 

package/lib/commands/timeline.js

@@ -44,6 +44,88 @@ function createStore(dependencies = {}) {
   return dependencies.timelineStore || new ProjectTimelineStore(projectPath, fileSystem);
 }
 
+function summarizeTimelineAttention(entry = {}) {
+  const trigger = normalizeText(entry.trigger).toLowerCase();
+  const git = entry && typeof entry.git === 'object' ? entry.git : {};
+  if (trigger === 'restore') {
+    return 'high';
+  }
+  if (trigger === 'push') {
+    return 'medium';
+  }
+  if (Number(git.dirty_count || 0) > 0) {
+    return 'medium';
+  }
+  return 'low';
+}
+
+function buildTimelineEntryViewModel(entry = {}) {
+  const title = normalizeText(entry.summary) || ((normalizeText(entry.trigger) || 'timeline') + ' checkpoint');
+  const subtitleParts = [
+    normalizeText(entry.event),
+    entry.scene_id ? ('scene=' + entry.scene_id) : '',
+    Number.isFinite(Number(entry.file_count)) ? ('files=' + Number(entry.file_count)) : ''
+  ].filter(Boolean);
+  return {
+    snapshot_id: normalizeText(entry.snapshot_id) || null,
+    title,
+    subtitle: subtitleParts.join(' | '),
+    trigger: normalizeText(entry.trigger) || null,
+    event: normalizeText(entry.event) || null,
+    created_at: normalizeText(entry.created_at) || null,
+    scene_id: normalizeText(entry.scene_id) || null,
+    session_id: normalizeText(entry.session_id) || null,
+    file_count: Number.isFinite(Number(entry.file_count)) ? Number(entry.file_count) : 0,
+    branch: entry && entry.git ? normalizeText(entry.git.branch) || null : null,
+    head: entry && entry.git ? normalizeText(entry.git.head) || null : null,
+    dirty_count: entry && entry.git && Number.isFinite(Number(entry.git.dirty_count)) ? Number(entry.git.dirty_count) : 0,
+    attention_level: summarizeTimelineAttention(entry),
+    show_command: normalizeText(entry.snapshot_id) ? ('sce timeline show ' + entry.snapshot_id + ' --json') : null,
+    restore_command: normalizeText(entry.snapshot_id) ? ('sce timeline restore ' + entry.snapshot_id + ' --json') : null
+  };
+}
+
+function buildTimelineListViewModel(payload = {}) {
+  const snapshots = Array.isArray(payload.snapshots) ? payload.snapshots : [];
+  const trigger_counts = {};
+  let dirty_snapshot_count = 0;
+  const sceneIds = new Set();
+  for (const item of snapshots) {
+    const trigger = normalizeText(item.trigger) || 'unknown';
+    trigger_counts[trigger] = Number(trigger_counts[trigger] || 0) + 1;
+    if (item.scene_id) {
+      sceneIds.add(item.scene_id);
+    }
+    if (item.git && item.git.dirty) {
+      dirty_snapshot_count += 1;
+    }
+  }
+  return {
+    summary: {
+      total: Number(payload.total || snapshots.length || 0),
+      latest_snapshot_id: snapshots[0] ? normalizeText(snapshots[0].snapshot_id) || null : null,
+      latest_created_at: snapshots[0] ? normalizeText(snapshots[0].created_at) || null : null,
+      dirty_snapshot_count,
+      scene_count: sceneIds.size,
+      trigger_counts
+    },
+    entries: snapshots.map((item) => buildTimelineEntryViewModel(item))
+  };
+}
+
+function buildTimelineShowViewModel(payload = {}) {
+  const snapshot = payload.snapshot && typeof payload.snapshot === 'object' ? payload.snapshot : {};
+  const filesPayload = payload.files && typeof payload.files === 'object' ? payload.files : {};
+  const files = Array.isArray(filesPayload.files) ? filesPayload.files : [];
+  return {
+    snapshot: buildTimelineEntryViewModel(snapshot),
+    files_preview: files.slice(0, 20),
+    file_preview_count: Math.min(files.length, 20),
+    file_total: Number(filesPayload.file_count || files.length || 0),
+    restore_command: snapshot.snapshot_id ? ('sce timeline restore ' + snapshot.snapshot_id + ' --json') : null
+  };
+}
+
 function printPayload(payload, asJson = false, title = 'Timeline') {
   if (asJson) {
     console.log(JSON.stringify(payload, null, 2));
@@ -112,6 +194,7 @@ async function runTimelineListCommand(options = {}, dependencies = {}) {
     limit: normalizePositiveInteger(options.limit, 20, 2000),
     trigger: normalizeText(options.trigger)
   });
+  payload.view_model = buildTimelineListViewModel(payload);
   printPayload(payload, options.json, 'Timeline List');
   return payload;
 }
@@ -119,6 +202,7 @@ async function runTimelineListCommand(options = {}, dependencies = {}) {
 async function runTimelineShowCommand(snapshotId, options = {}, dependencies = {}) {
   const store = createStore(dependencies);
   const payload = await store.getSnapshot(snapshotId);
+  payload.view_model = buildTimelineShowViewModel(payload);
   printPayload(payload, options.json, 'Timeline Show');
   return payload;
 }

package/package.json

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