scene-capability-engine 3.6.13 → 3.6.15

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.15] - 2026-03-06
+
+### Added
+- Capability plan apply result now includes preview lines + skipped titles for UI feedback.
+
+## [3.6.14] - 2026-03-06
+
+### Added
+- `sce capability use --apply` to append recommended tasks to spec tasks.md.
+
 ## [3.6.13] - 2026-03-06
 
 ### Added

package/README.md

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

package/README.zh.md

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

package/docs/command-reference.md

@@ -1906,6 +1906,9 @@ sce capability match --spec 01-02-customer-order --query "订单 库存" --limit
 
 # Generate a usage plan for a spec
 sce capability use --template customer-order-core --spec 01-02-customer-order --json
+
+# Generate usage plan + append tasks to tasks.md
+sce capability use --template customer-order-core --spec 01-02-customer-order --apply --json
 ```
 
 ### Scene Package Batch Publish

package/docs/magicball-capability-library.md

@@ -38,6 +38,12 @@ sce capability use --template <template-id> --spec <spec-id> --json
 
 输出：`capability-use-plan`（用于 UI 展示和后续手工应用）。
 
+如需直接写入 spec 任务：
+
+```bash
+sce capability use --template <template-id> --spec <spec-id> --apply --json
+```
+
 ## 3. API 封装建议（CLI -> HTTP）
 
 建议 Magicball 后端封装为：

package/lib/commands/capability.js

@@ -178,6 +178,144 @@ function buildKeywordScore(template, queryTokens) {
   return hits / queryTokens.length;
 }
 
+function collectExistingTaskRegistry(tasksContent) {
+  const taskPattern = /^-\s*\[[ x~-]\]\*?\s+(\d+(?:\.\d+)*)\s+(.+)$/;
+  const lines = String(tasksContent || '').split('\n');
+  const existingTitles = new Set();
+  let maxTaskId = 0;
+
+  for (const line of lines) {
+    const match = line.match(taskPattern);
+    if (!match) {
+      continue;
+    }
+
+    const rawId = match[1];
+    const rawTitle = match[2];
+    const taskId = Number.parseInt(String(rawId).split('.')[0], 10);
+
+    if (Number.isFinite(taskId)) {
+      maxTaskId = Math.max(maxTaskId, taskId);
+    }
+
+    const normalizedTitle = String(rawTitle || '')
+      .replace(/\s+\[[^\]]+\]$/, '')
+      .trim()
+      .toLowerCase();
+
+    if (normalizedTitle) {
+      existingTitles.add(normalizedTitle);
+    }
+  }
+
+  return {
+    maxTaskId,
+    existingTitles
+  };
+}
+
+function createCapabilityTaskLine(taskId, title, metadata = {}) {
+  const suffixParts = [];
+  if (metadata.templateId) {
+    suffixParts.push(`capability_ref=${metadata.templateId}`);
+  }
+  if (metadata.templateSource) {
+    suffixParts.push(`template_source=${metadata.templateSource}`);
+  }
+  const suffix = suffixParts.length > 0 ? ` [${suffixParts.join(' ')}]` : '';
+  return `- [ ] ${taskId} ${title}${suffix}`;
+}
+
+async function appendCapabilityPlanToSpecTasks(options, plan, fileSystem = fs) {
+  const projectPath = options.projectPath || process.cwd();
+  const specId = normalizeText(options.spec || options.specId);
+  if (!specId) {
+    throw new Error('spec is required to apply capability plan');
+  }
+  const tasksPath = path.join(projectPath, '.sce', 'specs', specId, 'tasks.md');
+  const tasksExists = await fileSystem.pathExists(tasksPath);
+  if (!tasksExists) {
+    throw new Error(`target spec tasks.md not found: ${tasksPath}`);
+  }
+  const currentContent = await fileSystem.readFile(tasksPath, 'utf8');
+  const registry = collectExistingTaskRegistry(currentContent);
+  const recommended = Array.isArray(plan.recommended_tasks) ? plan.recommended_tasks : [];
+  const sectionTitle = normalizeText(options.sectionTitle)
+    || `## Capability Template Tasks (${plan.template.id} - ${new Date().toISOString()})`;
+
+  const lines = [];
+  const addedTasks = [];
+  const skippedTitles = [];
+  let nextTaskId = registry.maxTaskId + 1;
+  let duplicateCount = 0;
+
+  for (const entry of recommended) {
+    const title = normalizeText(entry && entry.title);
+    if (!title) {
+      continue;
+    }
+    const titleKey = title.toLowerCase();
+    if (registry.existingTitles.has(titleKey)) {
+      duplicateCount += 1;
+      skippedTitles.push(title);
+      continue;
+    }
+    registry.existingTitles.add(titleKey);
+
+    lines.push(createCapabilityTaskLine(nextTaskId, title, {
+      templateId: plan.template.id,
+      templateSource: plan.template.source
+    }));
+
+    addedTasks.push({
+      task_id: nextTaskId,
+      title
+    });
+
+    nextTaskId += 1;
+  }
+
+  if (addedTasks.length === 0) {
+    return {
+      tasks_path: tasksPath,
+      section_title: sectionTitle,
+      added_count: 0,
+      skipped_duplicates: duplicateCount,
+      skipped_titles: skippedTitles,
+      preview_lines: [],
+      skipped_reason: recommended.length === 0
+        ? 'no recommended tasks'
+        : 'all recommended tasks already exist in tasks.md',
+      added_tasks: []
+    };
+  }
+
+  const prefix = currentContent.trimEnd();
+  const chunks = [
+    prefix,
+    '',
+    sectionTitle,
+    '',
+    ...lines,
+    ''
+  ];
+
+  const nextContent = chunks.join('\n');
+  await fileSystem.writeFile(tasksPath, nextContent, 'utf8');
+
+  return {
+    tasks_path: tasksPath,
+    section_title: sectionTitle,
+    added_count: addedTasks.length,
+    skipped_duplicates: duplicateCount,
+    skipped_titles: skippedTitles,
+    preview_lines: lines,
+    first_task_id: addedTasks[0].task_id,
+    last_task_id: addedTasks[addedTasks.length - 1].task_id,
+    added_tasks: addedTasks
+  };
+}
+
 async function loadSpecDomainChain(projectPath, specId, fileSystem) {
   const specPath = path.join(projectPath, '.sce', 'specs', specId);
   const domainChainPath = path.join(specPath, DOMAIN_CHAIN_RELATIVE_PATH);
@@ -821,6 +959,9 @@ async function useCapabilityTemplate(options = {}) {
   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 = new TemplateManager();
   const template = await manager.showTemplate(templateId);
@@ -878,6 +1019,17 @@ async function useCapabilityTemplate(options = {}) {
     plan.output_file = outputPath;
   }
 
+  if (normalizeBoolean(options.apply, false)) {
+    if (!specId) {
+      throw new Error('spec is required for --apply');
+    }
+    plan.apply = await appendCapabilityPlanToSpecTasks({
+      projectPath,
+      spec: specId,
+      sectionTitle: options.sectionTitle
+    }, plan, fileSystem);
+  }
+
   if (!normalizeBoolean(options.json, false)) {
     console.log(chalk.green('✅ Capability use plan generated'));
     console.log(chalk.gray(`  Template: ${template.id}`));
@@ -1099,6 +1251,8 @@ function registerCapabilityCommands(program) {
     .requiredOption('--template <template-id>', 'Capability template identifier')
     .option('--spec <spec-id>', 'Spec identifier')
     .option('--out <path>', 'Output JSON path')
+    .option('--apply', 'Append recommended tasks to spec tasks.md')
+    .option('--section-title <title>', 'Custom section title for tasks.md')
     .option('--no-write', 'Skip writing output file')
     .option('--json', 'Output JSON to stdout')
     .action(async (options) => {

package/package.json

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