kld-sdd 2.4.7

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "kld-sdd",
+  "version": "2.4.7",
+  "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
+  "main": "index.js",
+  "bin": {
+    "kld-sdd": "bin/kld-sdd-init.js",
+    "kld-sdd-init": "bin/kld-sdd-init.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "kld",
+    "sdd",
+    "openspec",
+    "init",
+    "cursor",
+    "claude",
+    "codebuddy",
+    "codex",
+    "template"
+  ],
+  "author": "KLD Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "skywalk-sdd/index.js",
+    "README.md"
+  ]
+}

package/skywalk-sdd/index.js

@@ -0,0 +1,587 @@
+#!/usr/bin/env node
+/**
+ * SDD Telemetry CLI
+ * 
+ * 本地 CLI 工具，为 SDD 工作流提供精确的流程度量采集。
+ * AI Agent 通过终端命令调用，将事件写入项目本地 skywalk-sdd/ 目录。
+ * 
+ * 用法:
+ *   node skywalk-sdd/log.js start  --command=propose --project=/path --change=xxx [--agent=cursor]
+ *   node skywalk-sdd/log.js end    --event-id=evt_xxx --result=success --summary="..."
+ *   node skywalk-sdd/log.js metrics --project=/path [--change=xxx]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ── 配置 ──────────────────────────────────────────────
+
+/** 获取项目的 skywalk-sdd 数据目录 */
+function getDataDir(projectRoot) {
+  return path.join(projectRoot, 'skywalk-sdd');
+}
+
+// SDD 标准阶段顺序
+const STAGE_ORDER = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
+const CORE_STAGES = ['propose', 'spec', 'design', 'apply', 'test'];
+
+// ── 工具函数 ──────────────────────────────────────────
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function generateEventId() {
+  return 'evt_' + crypto.randomBytes(6).toString('hex');
+}
+
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function nowISO() {
+  return new Date().toISOString();
+}
+
+/** 安全化 change name，防止路径穿越 */
+function safeChangeName(name) {
+  if (!name) return 'general';
+  return name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/^-+|-+$/g, '') || 'general';
+}
+
+/** 追加一行 JSONL 到事件文件（写入失败时抛出异常） */
+function appendEvent(dataDir, changeName, event) {
+  const dir = path.join(dataDir, 'events', safeChangeName(changeName));
+  ensureDir(dir);
+  const file = path.join(dir, `${today()}.jsonl`);
+  const line = JSON.stringify(event) + '\n';
+  fs.appendFileSync(file, line, 'utf8');
+  if (!fs.existsSync(file) || fs.statSync(file).size === 0) {
+    throw new Error(`事件文件写入验证失败: ${file}`);
+  }
+}
+
+/** 读取指定 change 的所有事件 */
+function readEvents(dataDir, changeName) {
+  try {
+    const dir = path.join(dataDir, 'events', safeChangeName(changeName));
+    if (!fs.existsSync(dir)) return [];
+
+    const events = [];
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort();
+    for (const file of files) {
+      const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
+      for (const line of lines) {
+        try { events.push(JSON.parse(line)); } catch {}
+      }
+    }
+    return events;
+  } catch (err) {
+    console.error('[sdd-telemetry] 事件读取失败:', err.message);
+    return [];
+  }
+}
+
+/** 读取所有 change 的事件 */
+function readAllEvents(dataDir) {
+  const eventsDir = path.join(dataDir, 'events');
+  if (!fs.existsSync(eventsDir)) return [];
+
+  const events = [];
+  const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+    return fs.statSync(path.join(eventsDir, d)).isDirectory();
+  });
+
+  for (const changeDir of changeDirs) {
+    const changeEvents = readEvents(dataDir, changeDir);
+    events.push(...changeEvents);
+  }
+  return events;
+}
+
+// ── 四维度量指标计算 ──────────────────────────────────
+
+/**
+ * 计算单个 change 的四维指标
+ */
+function computeChangeMetrics(changeName, events) {
+  const changeEvents = events.filter(e => e.change === changeName);
+  if (changeEvents.length === 0) return null;
+
+  const starts = changeEvents.filter(e => e.type === 'stage_start');
+  const ends = changeEvents.filter(e => e.type === 'stage_end');
+
+  // 已执行的阶段（去重）
+  const executedStages = [...new Set(starts.map(e => e.command))];
+  const completedStages = [...new Set(ends.map(e => e.command))];
+
+  // ── 维度一：流程健康度 ──
+  const coveredCoreStages = CORE_STAGES.filter(s => executedStages.includes(s));
+  const criticalPathCoverage = coveredCoreStages.length / CORE_STAGES.length;
+
+  // 跳阶段检测
+  const stageSequence = starts.map(e => e.command);
+  const skippedStages = detectSkippedStages(stageSequence);
+
+  // 阶段回退检测
+  const regressions = detectRegressions(stageSequence);
+  const regressionRate = stageSequence.length > 1 
+    ? regressions.length / (stageSequence.length - 1) 
+    : 0;
+
+  // Spec 存在率
+  const hasSpec = executedStages.includes('spec');
+
+  // ── 维度二：交付效率 ──
+  const proposeStart = starts.find(e => e.command === 'propose');
+  const archiveEnd = ends.find(e => e.command === 'archive');
+  const changeLeadTime = (proposeStart && archiveEnd)
+    ? new Date(archiveEnd.timestamp).getTime() - new Date(proposeStart.timestamp).getTime()
+    : null;
+
+  const designEnd = ends.find(e => e.command === 'design');
+  const applyStart = starts.find(e => e.command === 'apply');
+  const designToCodeTime = (designEnd && applyStart)
+    ? new Date(applyStart.timestamp).getTime() - new Date(designEnd.timestamp).getTime()
+    : null;
+
+  // 首次 Apply 成功率
+  const testEnds = ends.filter(e => e.command === 'test');
+  const firstTestSuccess = testEnds.length > 0 ? testEnds[0].result === 'success' : null;
+
+  // 阶段平均耗时
+  const stageDurations = {};
+  for (const end of ends) {
+    if (end.duration_ms) {
+      if (!stageDurations[end.command]) stageDurations[end.command] = [];
+      stageDurations[end.command].push(end.duration_ms);
+    }
+  }
+  const avgStageDurations = {};
+  for (const [stage, durations] of Object.entries(stageDurations)) {
+    avgStageDurations[stage] = Math.round(durations.reduce((a, b) => a + b, 0) / durations.length);
+  }
+
+  // ── 维度三：质量信号 ──
+  const firstTestResult = testEnds.length > 0 ? testEnds[0] : null;
+  const firstTestPassRate = firstTestResult?.details?.test_results
+    ? firstTestResult.details.test_results.passed / 
+      (firstTestResult.details.test_results.passed + firstTestResult.details.test_results.failed + (firstTestResult.details.test_results.skipped || 0))
+    : null;
+
+  const checkEnds = ends.filter(e => e.command === 'check');
+  const firstCheckPass = checkEnds.length > 0 
+    ? (checkEnds[0].details?.check_results?.errors || 0) === 0 
+    : null;
+
+  // Apply-Test-Fix 循环次数
+  const applyCount = starts.filter(e => e.command === 'apply').length;
+
+  // 测试覆盖率趋势
+  const coverageTrend = testEnds
+    .filter(e => e.details?.test_results?.coverage != null)
+    .map(e => ({ timestamp: e.timestamp, coverage: e.details.test_results.coverage }));
+
+  // ── 维度四：团队洞察 ──
+  const agentTypes = [...new Set(changeEvents.filter(e => e.agent_type).map(e => e.agent_type))];
+  const isCompleted = !!archiveEnd;
+
+  return {
+    change: changeName,
+    process_health: {
+      critical_path_coverage: criticalPathCoverage,
+      covered_core_stages: coveredCoreStages,
+      regression_rate: regressionRate,
+      regressions,
+      skipped_stages: skippedStages,
+      has_spec: hasSpec,
+    },
+    delivery_efficiency: {
+      change_lead_time_ms: changeLeadTime,
+      design_to_code_time_ms: designToCodeTime,
+      first_apply_success: firstTestSuccess,
+      avg_stage_durations_ms: avgStageDurations,
+    },
+    quality_signals: {
+      first_test_pass_rate: firstTestPassRate,
+      first_check_pass: firstCheckPass,
+      apply_test_fix_cycles: applyCount,
+      coverage_trend: coverageTrend,
+    },
+    team_insights: {
+      agent_types: agentTypes,
+      is_completed: isCompleted,
+      total_stages_executed: stageSequence.length,
+      executed_stages: executedStages,
+    },
+  };
+}
+
+/** 检测跳阶段 */
+function detectSkippedStages(sequence) {
+  const skipped = [];
+  for (let i = 1; i < sequence.length; i++) {
+    const prevIdx = STAGE_ORDER.indexOf(sequence[i - 1]);
+    const currIdx = STAGE_ORDER.indexOf(sequence[i]);
+    if (prevIdx >= 0 && currIdx >= 0 && currIdx > prevIdx + 1) {
+      const missed = STAGE_ORDER.slice(prevIdx + 1, currIdx);
+      skipped.push({ from: sequence[i - 1], to: sequence[i], missed });
+    }
+  }
+  return skipped;
+}
+
+/** 检测阶段回退 */
+function detectRegressions(sequence) {
+  const regressions = [];
+  for (let i = 1; i < sequence.length; i++) {
+    const prevIdx = STAGE_ORDER.indexOf(sequence[i - 1]);
+    const currIdx = STAGE_ORDER.indexOf(sequence[i]);
+    if (prevIdx >= 0 && currIdx >= 0 && currIdx < prevIdx) {
+      regressions.push({ from: sequence[i - 1], back_to: sequence[i] });
+    }
+  }
+  return regressions;
+}
+
+/**
+ * 计算全局概览指标
+ */
+function computeOverviewMetrics(events) {
+  const changeNames = [...new Set(events.map(e => e.change).filter(Boolean))];
+
+  const changeMetrics = changeNames
+    .map(name => computeChangeMetrics(name, events))
+    .filter(Boolean);
+
+  const totalChanges = changeMetrics.length;
+  if (totalChanges === 0) {
+    return { total_changes: 0, message: '暂无事件数据' };
+  }
+
+  // 维度一汇总
+  const avgCriticalPath = changeMetrics.reduce((s, m) => s + m.process_health.critical_path_coverage, 0) / totalChanges;
+  const specRate = changeMetrics.filter(m => m.process_health.has_spec).length / totalChanges;
+  const avgRegressionRate = changeMetrics.reduce((s, m) => s + m.process_health.regression_rate, 0) / totalChanges;
+
+  // 维度二汇总
+  const completedChanges = changeMetrics.filter(m => m.delivery_efficiency.change_lead_time_ms != null);
+  const avgLeadTime = completedChanges.length > 0
+    ? completedChanges.reduce((s, m) => s + m.delivery_efficiency.change_lead_time_ms, 0) / completedChanges.length
+    : null;
+  const firstApplySuccessRate = (() => {
+    const withTest = changeMetrics.filter(m => m.delivery_efficiency.first_apply_success != null);
+    return withTest.length > 0
+      ? withTest.filter(m => m.delivery_efficiency.first_apply_success).length / withTest.length
+      : null;
+  })();
+
+  // 维度三汇总
+  const firstCheckPassRate = (() => {
+    const withCheck = changeMetrics.filter(m => m.quality_signals.first_check_pass != null);
+    return withCheck.length > 0
+      ? withCheck.filter(m => m.quality_signals.first_check_pass).length / withCheck.length
+      : null;
+  })();
+  const avgApplyTestCycles = changeMetrics.reduce((s, m) => s + m.quality_signals.apply_test_fix_cycles, 0) / totalChanges;
+
+  // 维度四汇总
+  const completedCount = changeMetrics.filter(m => m.team_insights.is_completed).length;
+  const changeCompletionRate = completedCount / totalChanges;
+  const activeChanges = totalChanges - completedCount;
+  const allAgents = [...new Set(changeMetrics.flatMap(m => m.team_insights.agent_types))];
+
+  return {
+    total_changes: totalChanges,
+    process_health: {
+      avg_critical_path_coverage: Math.round(avgCriticalPath * 100) / 100,
+      spec_existence_rate: Math.round(specRate * 100) / 100,
+      avg_regression_rate: Math.round(avgRegressionRate * 100) / 100,
+    },
+    delivery_efficiency: {
+      avg_lead_time_ms: avgLeadTime != null ? Math.round(avgLeadTime) : null,
+      first_apply_success_rate: firstApplySuccessRate != null ? Math.round(firstApplySuccessRate * 100) / 100 : null,
+    },
+    quality_signals: {
+      first_check_pass_rate: firstCheckPassRate != null ? Math.round(firstCheckPassRate * 100) / 100 : null,
+      avg_apply_test_fix_cycles: Math.round(avgApplyTestCycles * 10) / 10,
+    },
+    team_insights: {
+      change_completion_rate: Math.round(changeCompletionRate * 100) / 100,
+      active_changes: activeChanges,
+      agent_distribution: allAgents,
+    },
+  };
+}
+
+// ── CLI 参数解析 ──────────────────────────────────────
+
+/** 解析 --key=value 格式的参数 */
+function parseArgs(argv) {
+  const args = {};
+  for (const arg of argv) {
+    const match = arg.match(/^--([a-zA-Z_-]+)=(.*)$/);
+    if (match) {
+      args[match[1]] = match[2];
+    } else if (arg.match(/^--([a-zA-Z_-]+)$/)) {
+      args[arg.slice(2)] = true;
+    }
+  }
+  return args;
+}
+
+// ── CLI 命令实现 ─────────────────────────────────────
+
+/**
+ * log start: 记录阶段开始
+ */
+function cmdStart(args) {
+  const command = args.command;
+  const projectRoot = args.project || args['project-root'] || process.cwd();
+  const changeName = args.change || args['change-name'] || '';
+  const agentType = args.agent || args['agent-type'] || 'unknown';
+
+  if (!command) {
+    console.error('错误: 缺少 --command 参数');
+    console.error('用法: node skywalk-sdd/log.js start --command=propose --project=/path');
+    process.exit(1);
+  }
+
+  const validCommands = ['propose', 'spec', 'design', 'task', 'check', 'apply', 'test', 'archive', 'explore'];
+  if (!validCommands.includes(command)) {
+    console.error(`错误: 无效的 command "${command}"，有效值: ${validCommands.join(', ')}`);
+    process.exit(1);
+  }
+
+  const dataDir = getDataDir(projectRoot);
+  const eventId = generateEventId();
+  const timestamp = nowISO();
+
+  const event = {
+    event_id: eventId,
+    type: 'stage_start',
+    command,
+    change: changeName || 'general',
+    agent_type: agentType,
+    project_root: projectRoot,
+    timestamp,
+    context: {},
+  };
+
+  appendEvent(dataDir, event.change, event);
+
+  // 输出 JSON，方便 AI Agent 解析 event_id
+  const output = {
+    event_id: eventId,
+    started_at: timestamp,
+    message: `SDD ${command} 阶段开始记录（change: ${event.change}）`,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * log end: 记录阶段结束
+ */
+function cmdEnd(args) {
+  const eventId = args['event-id'] || args.event_id;
+  const result = args.result;
+  const summary = args.summary || '';
+  const projectRoot = args.project || args['project-root'] || process.cwd();
+
+  if (!eventId) {
+    console.error('错误: 缺少 --event-id 参数');
+    console.error('用法: node skywalk-sdd/log.js end --event-id=evt_xxx --result=success --summary="..." --project=/path');
+    process.exit(1);
+  }
+  if (!result) {
+    console.error('错误: 缺少 --result 参数（success/failure/partial）');
+    process.exit(1);
+  }
+
+  // 从事件文件中查找对应的 start 事件
+  const dataDir = getDataDir(projectRoot);
+  const startEvent = searchEventInDataDir(dataDir, eventId);
+  const timestamp = nowISO();
+
+  const durationMs = startEvent
+    ? new Date(timestamp).getTime() - new Date(startEvent.timestamp).getTime()
+    : null;
+
+  const event = {
+    event_id: eventId,
+    type: 'stage_end',
+    command: startEvent?.command || 'unknown',
+    change: startEvent?.change || 'general',
+    agent_type: startEvent?.agent_type || 'unknown',
+    project_root: projectRoot,
+    timestamp,
+    duration_ms: durationMs,
+    result,
+    summary,
+    details: {},
+  };
+
+  appendEvent(dataDir, event.change, event);
+
+  const output = {
+    event_id: eventId,
+    duration_ms: durationMs,
+    recorded_at: timestamp,
+    message: `SDD ${event.command} 阶段结束（${result}，耗时 ${durationMs ? (durationMs / 1000).toFixed(1) + 's' : '未知'}）`,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * 从事件文件中查找 start 事件（因为 CLI 无状态，需要从文件回溯）
+ */
+function findStartEvent(eventId) {
+  // 尝试从当前目录的 skywalk-sdd 查找
+  const cwdDataDir = getDataDir(process.cwd());
+  const found = searchEventInDataDir(cwdDataDir, eventId);
+  if (found) return found;
+  return null;
+}
+
+function searchEventInDataDir(dataDir, eventId) {
+  const eventsDir = path.join(dataDir, 'events');
+  if (!fs.existsSync(eventsDir)) return null;
+
+  try {
+    const changeDirs = fs.readdirSync(eventsDir).filter(d => {
+      return fs.statSync(path.join(eventsDir, d)).isDirectory();
+    });
+
+    for (const changeDir of changeDirs) {
+      const dir = path.join(eventsDir, changeDir);
+      const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+      for (const file of files) {
+        const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
+        for (const line of lines) {
+          try {
+            const event = JSON.parse(line);
+            if (event.event_id === eventId && event.type === 'stage_start') {
+              return event;
+            }
+          } catch {}
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+/**
+ * log metrics: 查询度量指标
+ */
+function cmdMetrics(args) {
+  const projectRoot = args.project || args['project-root'] || process.cwd();
+  const changeName = args.change || args['change-name'];
+  const dateFrom = args['date-from'];
+  const dateTo = args['date-to'];
+
+  const dataDir = getDataDir(projectRoot);
+  let events = changeName ? readEvents(dataDir, changeName) : readAllEvents(dataDir);
+
+  // 日期过滤
+  if (dateFrom || dateTo) {
+    events = events.filter(e => {
+      const d = e.timestamp?.slice(0, 10);
+      if (dateFrom && d < dateFrom) return false;
+      if (dateTo && d > dateTo) return false;
+      return true;
+    });
+  }
+
+  let metrics;
+  if (changeName) {
+    metrics = computeChangeMetrics(changeName, events);
+    if (!metrics) {
+      console.log(JSON.stringify({ error: `未找到变更 "${changeName}" 的事件数据` }));
+      return;
+    }
+  } else {
+    metrics = computeOverviewMetrics(events);
+  }
+
+  console.log(JSON.stringify(metrics, null, 2));
+}
+
+// ── CLI 入口 ─────────────────────────────────────────
+
+function main() {
+  // 支持两种调用方式:
+  // 1) npx kld-sdd log start ...     → argv 含 'log'
+  // 2) node skywalk-sdd/log.js start ... → argv 直接以子命令开头
+  const argv = process.argv.slice(2);
+  const logIdx = argv.indexOf('log');
+  const subArgs = logIdx === -1 ? argv : argv.slice(logIdx + 1);
+
+  if (!subArgs.length || subArgs[0] === '-h' || subArgs[0] === '--help') {
+    showHelp();
+    process.exit(subArgs.length ? 0 : 1);
+  }
+  const subCommand = subArgs[0];
+  const flags = parseArgs(subArgs.slice(1));
+
+  switch (subCommand) {
+    case 'start':
+      cmdStart(flags);
+      break;
+    case 'end':
+      cmdEnd(flags);
+      break;
+    case 'metrics':
+      cmdMetrics(flags);
+      break;
+    default:
+      showHelp();
+      process.exit(1);
+  }
+}
+
+function showHelp() {
+  console.log(`
+SDD Telemetry CLI - 流程度量采集工具
+
+用法:
+  node skywalk-sdd/log.js start   --command=<cmd> --project=<path> [--change=<name>] [--agent=<type>]
+  node skywalk-sdd/log.js end     --event-id=<id> --result=<success|failure|partial> --summary="..."
+  node skywalk-sdd/log.js metrics --project=<path> [--change=<name>]
+
+子命令:
+  start    记录 SDD 阶段开始，返回 event_id
+  end      记录 SDD 阶段结束，关联 event_id
+  metrics  查询度量指标（四维分析）
+
+示例:
+  node skywalk-sdd/log.js start --command=propose --project=/my/project --change=user-auth --agent=cursor
+  node skywalk-sdd/log.js end --event-id=evt_abc123 --result=success --summary="创建 proposal.md"
+  node skywalk-sdd/log.js metrics --project=/my/project --change=user-auth
+`);
+}
+
+// 导出供测试使用
+module.exports = {
+  main,
+  parseArgs,
+  cmdStart,
+  cmdEnd,
+  cmdMetrics,
+  computeChangeMetrics,
+  computeOverviewMetrics,
+  readEvents,
+  readAllEvents,
+  appendEvent,
+  getDataDir,
+  safeChangeName,
+  generateEventId,
+  findStartEvent,
+};
+
+// 直接运行时执行
+if (require.main === module) {
+  main();
+}