scene-capability-engine 3.6.10 → 3.6.13

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.13] - 2026-03-06
+
+### Added
+- Capability library reuse commands:
+  - `sce capability catalog list/search/show`
+  - `sce capability match`
+  - `sce capability use`
+- Magicball capability library integration guide:
+  - `docs/magicball-capability-library.md`
+
+## [3.6.12] - 2026-03-06
+
+### Added
+- Magicball task quality governance integration guide:
+  - `docs/magicball-task-quality-governance.md`
+
+## [3.6.11] - 2026-03-05
+
+### Added
+- Task quality governance commands:
+  - `sce task draft`
+  - `sce task consolidate`
+  - `sce task score`
+  - `sce task promote`
+- Task quality policy support:
+  - `.sce/config/task-quality-policy.json`
+  - policy overrides via `--policy <path>`
+- Task promotion now emits acceptance suggestions when acceptance criteria are missing.
+
 ## [3.6.10] - 2026-03-05
 
 ### Added

package/README.md

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

package/README.zh.md

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

package/docs/command-reference.md

@@ -201,6 +201,26 @@ Task references and studio runtime events are persisted in SQLite state store:
 - In-memory fallback is restricted to `NODE_ENV=test` or `SCE_STATE_ALLOW_MEMORY_FALLBACK=1`.
 - If SQLite runtime support is unavailable outside fallback conditions, `task ref/show/rerun` and `studio events` persistence operations fail fast.
 
+#### Task Quality Governance (draft -> score -> promote)
+
+```bash
+# Create draft from dialogue
+sce task draft --scene scene.customer-order --input "Fix checkout timeout and add retry dashboard" --json
+
+# Consolidate drafts for a scene
+sce task consolidate --scene scene.customer-order --json
+
+# Score draft quality
+sce task score --draft <draft-id> --json
+
+# Promote into tasks.md (quality gate enforced unless --force)
+sce task promote --draft <draft-id> --spec 02-00-checkout-optimization --json
+```
+
+Policy file:
+- `.sce/config/task-quality-policy.json`
+- Fields: `min_quality_score`, `require_acceptance_criteria`, `allow_needs_split`, `auto_suggest_acceptance`, `max_sub_goals`
+
 ### Context & Prompts
 
 ```bash
@@ -1868,6 +1888,26 @@ Schema references:
 - UI contract: `docs/agent-runtime/capability-iteration-ui.schema.json`
 - Ontology mapping: `docs/ontology/capability-mapping.schema.json`
 
+### Capability Library Reuse (query -> match -> use)
+
+```bash
+# List capability templates
+sce capability catalog list --json
+
+# Search capability templates
+sce capability catalog search "customer order" --json
+
+# Show capability template metadata + payload
+sce capability catalog show customer-order-core --json
+
+# Match capability templates to a spec (uses problem-domain-chain.json)
+sce capability match --spec 01-02-customer-order --json
+sce capability match --spec 01-02-customer-order --query "订单 库存" --limit 5 --json
+
+# Generate a usage plan for a spec
+sce capability use --template customer-order-core --spec 01-02-customer-order --json
+```
+
 ### Scene Package Batch Publish
 
 ```bash

package/docs/magicball-capability-library.md

@@ -0,0 +1,117 @@
+# Magicball 能力库复用对接说明（SCE）
+
+> 目标：在 Magicball UI 中提供“能力库检索/匹配/使用”闭环，加速场景能力落地。
+
+## 1. 能力库复用流程
+
+1. **查询**能力库（列表/搜索）
+2. **匹配**当前 spec 的问题域（基于 problem-domain-chain 里的 ontology）
+3. **使用**能力模板（生成可执行的 usage plan）
+
+## 2. SCE CLI 支持（对 Magicball 的最小封装）
+
+### 2.1 查询与搜索
+
+```bash
+sce capability catalog list --json
+sce capability catalog search "customer order" --json
+sce capability catalog show <template-id> --json
+```
+
+### 2.2 匹配（基于 spec ontology）
+
+```bash
+sce capability match --spec <spec-id> --json
+sce capability match --spec <spec-id> --query "订单 库存" --limit 5 --json
+```
+
+匹配会读取：
+- `.sce/specs/<spec>/custom/problem-domain-chain.json`
+
+若该文件缺失，默认仍返回结果，但 `warnings` 中会标记缺失。
+
+### 2.3 使用（生成 usage plan）
+
+```bash
+sce capability use --template <template-id> --spec <spec-id> --json
+```
+
+输出：`capability-use-plan`（用于 UI 展示和后续手工应用）。
+
+## 3. API 封装建议（CLI -> HTTP）
+
+建议 Magicball 后端封装为：
+
+- `POST /api/sce/capability/catalog/list`
+- `POST /api/sce/capability/catalog/search`
+- `POST /api/sce/capability/catalog/show`
+- `POST /api/sce/capability/match`
+- `POST /api/sce/capability/use`
+
+请求体示例：
+
+```json
+{
+  "specId": "01-02-customer-order",
+  "query": "订单 库存",
+  "limit": 5
+}
+```
+
+## 4. UI 行为建议（Magicball）
+
+### 4.1 能力库入口
+- 顶部图标入口
+- Tabs：`能力库` / `匹配结果` / `使用计划`
+
+### 4.2 能力库列表
+- 支持筛选：category / risk / source
+- 展示关键信息：`name` / `description` / `ontology_scope`
+
+### 4.3 匹配结果
+- 展示 `score` + `score_components`
+- 支持一键生成 usage plan
+
+### 4.4 使用计划
+- 展示 `recommended_tasks`
+- 可手工转为当前 spec 的任务
+
+## 5. 输出结构（关键字段）
+
+### capability-match
+```json
+{
+  "mode": "capability-match",
+  "spec_id": "01-02-customer-order",
+  "scene_id": "scene.customer-order",
+  "match_count": 12,
+  "matches": [
+    {
+      "template_id": "customer-order-core",
+      "score": 82,
+      "score_components": {
+        "ontology": 0.72,
+        "scenario": 1,
+        "keyword": 0.35
+      }
+    }
+  ]
+}
+```
+
+### capability-use-plan
+```json
+{
+  "mode": "capability-use-plan",
+  "template": {"id": "customer-order-core", "name": "Customer Order Core"},
+  "spec_id": "01-02-customer-order",
+  "recommended_tasks": [
+    {"title": "Define order entity"},
+    {"title": "Implement order lifecycle"}
+  ]
+}
+```
+
+---
+
+若需要“自动落地写入 spec 任务”的强制执行模式，可以在后续版本加 `--apply` 开关。

package/docs/magicball-task-quality-governance.md

@@ -0,0 +1,301 @@
+# Magicball 任务质量治理对接说明（SCE）
+
+> 适用于：Magicball AI 助手任务卡 UI 的质量治理增强与 SCE Task 质量闭环对接。
+
+## 1. 背景与目标
+
+任务由对话生成，容易出现「多事项混杂、目标不清晰、验收缺失」等问题，导致执行偏移或兜底编程。
+SCE 新增「任务质量治理」闭环能力，保证每个任务可执行、可验收、可追踪。
+
+目标：
+- 让 Magicball UI 在**同一任务卡**内完成“草案 -> 评分 -> 修正 -> Promote”的闭环
+- 通过质量门禁（Policy）强制任务可执行、可验收
+- 保留用户原始输入，避免信息丢失
+
+## 2. SCE 新增能力概览
+
+新增 CLI：
+- `sce task draft`
+- `sce task consolidate`
+- `sce task score`
+- `sce task promote`
+
+新增策略文件：
+- `.sce/config/task-quality-policy.json`
+- 支持 `--policy <path>` 覆盖
+
+默认门禁（可配置）：
+- acceptance_criteria 必须存在
+- needs_split 必须为 false
+- min_score >= 70
+
+## 3. 推荐交互流程（最短闭环）
+
+1. 用户输入 -> `sce task draft`
+2. 多轮输入合并 -> `sce task consolidate`
+3. 评分 -> `sce task score`
+4. 通过门禁 -> `sce task promote`
+5. 成功写入 `tasks.md`
+
+## 4. 字段契约（建议 Magicball 消费）
+
+核心字段：
+- `task_ref`（草案阶段可为空）
+- `title_norm`
+- `raw_request`
+- `goal`
+- `sub_goals`
+- `acceptance_criteria`
+- `needs_split`
+- `confidence`
+- `next_action`
+- `handoff`
+- `score`
+
+示例（草案阶段）：
+```json
+{
+  "task_ref": null,
+  "title_norm": "生成客户-订单-库存演示数据流程",
+  "raw_request": "帮我做一个客户订单库存的demo",
+  "goal": "生成可运行的客户-订单-库存演示流程",
+  "sub_goals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+  "acceptance_criteria": [],
+  "needs_split": true,
+  "confidence": 0.68,
+  "next_action": "split",
+  "handoff": "needs_split=true, acceptance_criteria empty"
+}
+```
+
+评分示例：
+```json
+{
+  "score": 62,
+  "missing_items": ["acceptance_criteria", "split_required"]
+}
+```
+
+Promote 成功：
+```json
+{
+  "success": true,
+  "task_ref": "01.02.03",
+  "message": "promoted"
+}
+```
+
+Promote 失败：
+```json
+{
+  "success": false,
+  "message": "quality gate failed",
+  "reasons": ["acceptance_criteria missing", "needs_split=true"]
+}
+```
+
+## 5. UI 行为规范（强制）
+
+- 草案页：默认显示**评分卡 + 缺失项**
+- `needs_split=true`：必须拆分或补充，**禁止 promote**
+- `acceptance_criteria` 为空：**阻断 promote**
+- promote 失败时提示固定文案：**“质量门禁未通过”**
+
+## 6. 基于现有任务 UI 的最小改动建议
+
+当前 UI：单卡片 + 事件流 + 文件变更 + 错误信息。
+在不改整体布局的前提下，建议：
+
+1) 任务头部
+- 显示 `title_norm`
+- `raw_request` 置于标题下方（可折叠）
+- 状态徽标：Draft / Needs Split / Missing Acceptance / Ready / Failed Gate
+
+2) 评分卡（插入到事件流上方）
+- 展示 `score / missing_items / next_action`
+- 点击展开查看策略阈值与建议
+
+3) 强制阻断逻辑
+- needs_split 或 acceptance 缺失 => promote 按钮置灰
+- 展示原因与修复入口
+
+4) Promote 失败提示
+- 固定文案 “质量门禁未通过”
+- 展示失败原因列表
+
+5) 原有事件流保留，增强复制能力
+- 错误日志一键复制，便于诊断
+
+## 7. 参考命令（Magicball 封装为 API 即可）
+
+```bash
+sce task draft --spec <specPath> --input "<user text>"
+sce task consolidate --spec <specPath>
+sce task score --spec <specPath>
+sce task promote --spec <specPath>
+```
+
+## 8. 版本与发布说明
+
+该能力自 **SCE v3.6.11** 开始提供，若 Magicball 需要兼容老版本，请做版本检测与能力降级处理。
+
+---
+
+如需进一步输出 UI 页面原型或字段映射表，可直接在此文档上增补。
+## 9. 字段映射表（SCE -> Magicball UI）
+
+| SCE 字段 | UI 位置 | 展示方式 | 规则 |
+| --- | --- | --- | --- |
+| task_ref | 任务卡标题前 | 小号标签 | 无则隐藏 |
+| title_norm | 任务卡标题 | 主标题 | 必填 |
+| raw_request | 标题下方 | 灰色可折叠 | 保留原文 |
+| goal | 详情区 | 主目标段落 | 若空提示补齐 |
+| sub_goals | 详情区 | 列表 | needs_split=true 时高亮 |
+| acceptance_criteria | 详情区 | 验收列表 | 为空阻断 promote |
+| needs_split | 状态徽标 | Needs Split | true 则阻断 |
+| confidence | 评分卡 | 低/中/高 | <0.6 高亮 |
+| score | 评分卡 | 数值 + 色阶 | <阈值红色 |
+| missing_items | 评分卡 | 缺失列表 | 点击展开 |
+| next_action | 评分卡 | 下一步 | 生成操作建议 |
+| handoff | 详情区 | 灰色提示 | 展示门禁原因 |
+| errors | 事件流 | 错误块 | 一键复制 |
+| file_changes | 文件变更区 | 文件列表 | diff 快捷入口 |
+
+## 10. 前端组件建议
+
+### 10.1 TaskCard（现有卡片增强）
+- Header：`task_ref + title_norm`，`raw_request` 折叠显示。
+- StatusBadge：Draft / Needs Split / Missing Acceptance / Ready / Failed Gate。
+- QuickActions：Score / Promote / Split / Fix Acceptance。
+
+### 10.2 QualityScorePanel
+- 固定显示 `score / missing_items / next_action`。
+- 展开显示 policy 阈值与建议。
+- 禁止 promote 时显示红色提示条。
+
+### 10.3 AcceptanceEditor
+- 为空时自动提示“请补齐验收标准”。
+- 提供“自动补齐建议”按钮（由 SCE 生成）。
+
+### 10.4 PromoteGuard
+- 拦截条件：needs_split=true 或 acceptance_criteria 为空。
+- 拦截弹窗文案固定：“质量门禁未通过”。
+
+### 10.5 ErrorStream
+- 事件流右侧增加复制按钮。
+- 错误日志折叠/展开。
+
+## 11. 建议的调用顺序（前端按钮）
+
+- 点击“生成草案”：`sce task draft`
+- 点击“合并输入”：`sce task consolidate`
+- 点击“评分”：`sce task score`
+- 点击“Promote”：`sce task promote`
+
+---
+## 12. 示例 UI 结构（JSON/DSL）
+
+```json
+{
+  "type": "TaskCard",
+  "props": {
+    "taskRef": "01.02.03",
+    "titleNorm": "生成客户-订单-库存演示数据流程",
+    "rawRequest": "帮我做一个客户订单库存的demo",
+    "status": "NeedsSplit",
+    "score": 62,
+    "missingItems": ["acceptance_criteria", "split_required"],
+    "nextAction": "split"
+  },
+  "children": [
+    {
+      "type": "QualityScorePanel",
+      "props": {
+        "score": 62,
+        "minScore": 70,
+        "missingItems": ["acceptance_criteria", "split_required"],
+        "nextAction": "split"
+      }
+    },
+    {
+      "type": "TaskDetails",
+      "props": {
+        "goal": "生成可运行的客户-订单-库存演示流程",
+        "subGoals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+        "acceptanceCriteria": [],
+        "handoff": "needs_split=true, acceptance_criteria empty"
+      }
+    },
+    {
+      "type": "EventStream",
+      "props": {
+        "events": [
+          {"ts": "23:59:01", "level": "error", "message": "auto-fix blocked", "copyable": true},
+          {"ts": "23:59:02", "level": "info", "message": "Task completed"}
+        ]
+      }
+    },
+    {
+      "type": "FileChanges",
+      "props": {
+        "files": [
+          {"path": "src/app.ts", "diffRef": "diff:123", "reason": "adjust task acceptance"}
+        ]
+      }
+    }
+  ]
+}
+```
+
+## 13. 前端 API 封装建议（CLI -> HTTP）
+
+建议 Magicball 在后端封装 SCE CLI，前端统一调用 HTTP。
+
+### 13.1 路由定义
+
+- `POST /api/sce/task/draft`
+- `POST /api/sce/task/consolidate`
+- `POST /api/sce/task/score`
+- `POST /api/sce/task/promote`
+
+### 13.2 请求体
+
+```json
+{
+  "specPath": "scenes/01/specs/02/spec.md",
+  "input": "帮我做一个客户订单库存的demo",
+  "policyPath": ".sce/config/task-quality-policy.json"
+}
+```
+
+### 13.3 响应体（统一包裹）
+
+```json
+{
+  "success": true,
+  "data": {
+    "task_ref": "01.02.03",
+    "title_norm": "生成客户-订单-库存演示数据流程",
+    "raw_request": "帮我做一个客户订单库存的demo",
+    "goal": "生成可运行的客户-订单-库存演示流程",
+    "sub_goals": ["定义实体关系", "生成测试数据", "配置页面展示"],
+    "acceptance_criteria": ["前端能展示客户列表"],
+    "needs_split": false,
+    "confidence": 0.81,
+    "score": 78,
+    "missing_items": [],
+    "next_action": "promote",
+    "handoff": "ready"
+  },
+  "errors": []
+}
+```
+
+### 13.4 前端调用顺序（建议）
+
+1. `draft` -> 渲染草案 + 评分卡
+2. `consolidate` -> 合并多轮输入（可选）
+3. `score` -> 质量评分
+4. `promote` -> 写入 tasks.md
+
+---