kld-sdd 2.6.21 → 2.7.8-1

package/skywalk-sdd/context-client.cjs

@@ -12,6 +12,7 @@ const {
   loadKbState,
   resolveKbParams,
   stripBom,
+  httpGetJson,
 } = require('./lib/shared.cjs');
 
 // Re-export requestJson for external callers (API compatibility)
@@ -105,6 +106,7 @@ function buildPayload(args, mode) {
 }
 
 async function retrieveContext(args = parseArgs(process.argv), env = process.env) {
+  if (args.offline) return unavailableContext('engineering_kb_offline', '本次使用本地上下文，未验证远程基线');
   // 优先从共享 state 文件读取配置（与 opsx-ontology-query / opsx-kb-ingest 共用）
   let stateConfig = {};
   const stateFile = args['state-file'] || env.SDD_KB_STATE_FILE;
@@ -131,12 +133,17 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
 
   const { apiBase: kbApiBase, token: kbToken, spaceId: kbSpaceId, kbId: kbKbId, targets: kbTargets } = resolveKbParams(stateConfig, env);
 
+  if (Boolean(args['space-id']) !== Boolean(args['kb-id'])) throw new Error('请同时指定 --space-id 和 --kb-id');
+  const explicitSpace = args['space-id'] || env.ENGINEERING_KB_SPACE_ID;
+  const explicitKb = args['kb-id'] || env.ENGINEERING_KB_KB_ID;
+  if (Boolean(explicitSpace) !== Boolean(explicitKb)) throw new Error('请同时配置目标 spaceId 和 kbId');
+  if (kbTargets.length > 1 && !explicitSpace) throw new Error('配置了多个 KB，请用 --space-id 和 --kb-id 明确本次查询目标');
   const apiBase = args['api-base'] || kbApiBase;
   const token = args.token || kbToken;
-  const spaceId = args['space-id'] || kbSpaceId;
-  const kbId = args['kb-id'] || kbKbId;
+  const spaceId = explicitSpace || kbSpaceId;
+  const kbId = explicitKb || kbKbId;
 
-  // --check-only: 只检查 KB 配置是否就绪，不发起 API 请求
+  // --check-only performs an authenticated check against the selected KB.
   // 用于 SDD 各阶段（propose/spec/design/task/check）统一检测 KB 可用性，消除相对路径歧义
   if (args['check-only']) {
     const missing = [];
@@ -145,31 +152,27 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
     if (!kbId) missing.push('kbId');
     if (missing.length > 0) {
       return {
-        available: false,
-        reason: 'engineering_kb_not_configured',
+        ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'),
+        configured: false,
         missing,
-        hint: 'Run /opsx-kb-config to configure kb-state.json (in spec root)',
       };
     }
-    return {
-      available: true,
-      api: apiBase,
-      targets: kbTargets,
-    };
+    const endpoint = `${String(apiBase).replace(/\/+$/, '')}/v1/spaces/${encodeURIComponent(spaceId)}`
+      + `/knowledge-bases/${encodeURIComponent(kbId)}/context/readiness`;
+    const response = await httpGetJson(endpoint, token, contextTimeout(args, env, 3000));
+    if (response?.code != null && response.code !== 0) throw new Error(response.message || 'KB readiness failed');
+    const readiness = response?.data || response;
+    if (readiness?.available !== true || readiness?.authorized !== true) throw new Error('KB 未返回有效的权限与就绪状态');
+    return { ...readiness, configured: true, api: apiBase, spaceId, kbId };
+
   }
 
-  if (!spaceId || !kbId) {
-    return {
-      available: false,
-      advisory: true,
-      degraded: true,
-      reason: 'engineering_kb_not_configured',
-      hint: 'set ENGINEERING_KB_SPACE_ID and ENGINEERING_KB_KB_ID; do not fall back to local archive/',
-    };
+  if (!spaceId || !kbId || !token) {
+    return { ...unavailableContext('engineering_kb_not_configured', 'KB 尚未配置，本地工作可以继续'), configured: false };
   }
 
   const mode = String(args.mode || 'match').trim().toLowerCase() === 'resolve' ? 'resolve' : 'match';
-  const timeoutMs = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || 30000);
+  const timeoutMs = contextTimeout(args, env, 5000);
   const payload = buildPayload(args, mode);
   const data = await requestJson(
     buildEndpoint(apiBase, spaceId, kbId, mode),
@@ -184,21 +187,38 @@ async function retrieveContext(args = parseArgs(process.argv), env = process.env
   };
 }
 
+function contextTimeout(args, env, fallback) {
+  const timeout = Number(args.timeout || env.ENGINEERING_KB_TIMEOUT_MS || fallback);
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('timeout 必须是大于 0 的毫秒数');
+  return timeout;
+}
+
+function unavailableContext(reason, message) {
+  return {
+    available: false,
+    advisory: true,
+    degraded: true,
+    localWorkAllowed: true,
+    baselineVerified: false,
+    inheritanceAllowed: false,
+    reason,
+    message,
+    hint: '继续本地编写、检查和测试；保留已有身份与真实基线。发布前重新在线校验，不把历史参考当作 KB current。',
+  };
+}
+
 async function main() {
   const args = parseArgs(process.argv);
+  let result;
   try {
-    console.log(JSON.stringify(await retrieveContext(args), null, 2));
+    result = await retrieveContext(args);
   } catch (error) {
-    console.log(JSON.stringify({
-      available: false,
-      advisory: true,
-      degraded: true,
-      reason: 'engineering_kb_unavailable',
-      message: error.message,
-      hint: 'KB unavailable: continue degraded; never scan local archive/ for inheritance UUIDs',
-    }, null, 2));
-    if (args.strict) process.exitCode = 1;
+    const reason = /\b(401|403|Unauthorized|Forbidden)\b/.test(error.message)
+      ? 'engineering_kb_access_denied' : 'engineering_kb_unavailable';
+    result = unavailableContext(reason, error.message);
   }
+  console.log(JSON.stringify(result, null, 2));
+  if (args.strict && result.available !== true) process.exitCode = 1;
 }
 
 if (require.main === module) {

package/skywalk-sdd/index.cjs

@@ -244,7 +244,7 @@ function findActiveStage(projectRoot, criteria) {
       const matchingStarts = [];
       for (const changeDir of changeDirs) {
         const dir = path.join(eventsDir, changeDir);
-        const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).reverse();
         for (const file of files) {
           const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
           for (let i = lines.length - 1; i >= 0; i--) {
@@ -357,7 +357,7 @@ function discoverTaskFiles(projectRoot, changeName) {
   return walkFiles(changeDir, filePath => {
     const fileName = path.basename(filePath).toLowerCase();
     return fileName === 'tasks.md' || fileName === 'task.md';
-  }).sort();
+  }).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function checklistEntriesOutsideCodeFences(lines) {
@@ -587,7 +587,7 @@ function scanTaskCompletionForArchiveDir(projectRoot, changeName, archiveDir) {
   const taskFiles = walkFiles(archiveDir, filePath => {
     const fileName = path.basename(filePath).toLowerCase();
     return fileName === 'tasks.md' || fileName === 'task.md';
-  }).sort();
+  }).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   return scanTaskCompletionFromFiles(normalizedRoot, changeName, taskFiles);
 }
 
@@ -796,7 +796,7 @@ function collectSpecFiles(changeRoot) {
   if (!changeRoot || !fs.existsSync(changeRoot)) return [];
   const specsDir = path.join(changeRoot, 'specs');
   if (fs.existsSync(specsDir) && fs.statSync(specsDir).isDirectory()) {
-    return walkFiles(specsDir, filePath => path.basename(filePath).toLowerCase() === 'spec.md').sort();
+    return walkFiles(specsDir, filePath => path.basename(filePath).toLowerCase() === 'spec.md').sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
   }
   const rootSpec = path.join(changeRoot, 'spec.md');
   if (fs.existsSync(rootSpec)) return [rootSpec];
@@ -1503,7 +1503,7 @@ function readEventsRaw(dataDir, changeName) {
     if (!fs.existsSync(dir)) return [];
 
     const events = [];
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort();
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
     for (const file of files) {
       const lines = fs.readFileSync(path.join(dir, file), 'utf-8').split('\n').filter(Boolean);
       for (const line of lines) {
@@ -4859,7 +4859,7 @@ function buildReport(projectRoot, events, options = {}) {
   const scopedReport = scopeEventsForChangeReport(events, options.change);
   events = scopedReport.events;
   const archiveEvent = latestByTimestamp(events.filter(e => {
-    return e.command === 'archive' && e.type === 'stage_end';
+    return e.command === 'archive' && e.type === 'stage_end' && e.details?.archive_result;
   }));
   const gitCommitTimeline = resolveGitCommitTimeline(
     events,
@@ -5475,7 +5475,8 @@ function cmdEnd(args, options = {}) {
     command: args.command,
     agent_type: args.agent || args['agent-type'],
   };
-  const startEvent = eventId
+  // let：下方占位 change 迁移逻辑需要重新赋值 startEvent（const 会在运行时抛 TypeError）
+  let startEvent = eventId
     ? searchEventInDataDir(dataDir, eventId)
     : findActiveStage(projectRoot, activeCriteria);
   if (!eventId && startEvent) {
@@ -5858,6 +5859,19 @@ function cmdEnd(args, options = {}) {
   if (!options.silent) {
     console.log(JSON.stringify(output, null, 2));
   }
+  // kld-usage-flush: stage_end 落库后冲刷 pending 队列（fire-and-forget，不产生新事件）。
+  // 覆盖"start 时网络故障/无身份，end 时已恢复"的同会话补报场景；失败不影响 output 与退出码。
+  // promise 以不可枚举属性挂返回对象供测试 await，JSON.stringify 输出不变。
+  try {
+    const { flushPendingUsage } = require('./lib/usage-reporter.cjs');
+    const usageFlush = flushPendingUsage({ projectRoot }).catch(() => null);
+    Object.defineProperty(output, 'usageFlush', {
+      value: usageFlush,
+      enumerable: false,
+      writable: false,
+      configurable: true,
+    });
+  } catch { /* flush 不可用不阻塞 */ }
   return output;
 }
 
@@ -5947,7 +5961,7 @@ function normalizeRepositoryRelativeFiles(files, {
     }
     normalized.push(raw);
   }
-  return [...new Set(normalized)].sort();
+  return [...new Set(normalized)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
 function normalizeStrictCheckResult(details, result) {
@@ -6399,13 +6413,13 @@ function normalizeStrictTestResult(args, details) {
 
   const taskId = String(args['task-id'] || args.task_id || input.task_id || '').trim();
   const verifiedTaskIds = Array.isArray(input.verified_task_ids)
-    ? [...new Set(input.verified_task_ids.map(value => String(value || '').trim()).filter(Boolean))].sort()
+    ? [...new Set(input.verified_task_ids.map(value => String(value || '').trim()).filter(Boolean))].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
     : [];
   if (!taskId && verifiedTaskIds.length === 0) {
     fail('E_STRICT_FIELD_REQUIRED: strict test_result 必须提供 task_id 或 verified_task_ids');
   }
   if (taskId && !verifiedTaskIds.includes(taskId)) verifiedTaskIds.push(taskId);
-  verifiedTaskIds.sort();
+  verifiedTaskIds.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 
   const normalized = {
     run_id: requireStrictString(args['run-id'] || args.run_id || input.run_id, 'EVENT_RUN_ID_REQUIRED', 'run_id'),
@@ -7846,7 +7860,7 @@ function searchEventInDataDir(dataDir, eventId) {
 
     for (const changeDir of changeDirs) {
       const dir = path.join(eventsDir, changeDir);
-      const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+      const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).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) {
@@ -7872,7 +7886,7 @@ function readAllEventEndsById(dataDir, eventId, changeName) {
 
   const scanDir = (dir) => {
     if (!fs.existsSync(dir)) return;
-    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort().reverse();
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.jsonl')).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).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) {
@@ -8161,18 +8175,37 @@ function cmdSemanticScan(args) {
 
 function cmdSemanticReconcile(args, options = {}) {
   const context = semanticCommandContext(args);
+  const started = process.hrtime.bigint();
   const result = require('./ontology/runtime.cjs').reconcileChange(
     context.projectRoot,
     context.changeName,
     { profile: context.profile, markPending: Boolean(options.markPending) },
   );
-  console.log(JSON.stringify(semanticResultPayload(result), null, 2));
+  const payload = semanticResultPayload(result);
+  if (options.includeTasks) {
+    const semanticFinished = process.hrtime.bigint();
+    // A review packet avoids another CLI launch and a parent-agent document scan.
+    // It is fresh input metadata, never a cached approval or a substitute for review.
+    payload.task_completion = scanTaskCompletion(context.projectRoot, context.changeName);
+    payload.review_inputs = {
+      change_dir: path.join(context.projectRoot, 'openspec', 'changes', context.changeName),
+      files: result.state.files,
+      identity_history_hash: result.state.identity_history_hash,
+    };
+    const finished = process.hrtime.bigint();
+    payload.timings_ms = {
+      semantic: Number(semanticFinished - started) / 1e6,
+      tasks: Number(finished - semanticFinished) / 1e6,
+      total: Number(finished - started) / 1e6,
+    };
+  }
+  console.log(JSON.stringify(payload, null, 2));
   if (!result.valid) process.exitCode = 1;
   return result;
 }
 
 function cmdSemanticCheck(args) {
-  return cmdSemanticReconcile(args, { markPending: true });
+  return cmdSemanticReconcile(args, { markPending: true, includeTasks: Boolean(args['include-tasks']) });
 }
 
 function cmdSemanticStatus(args) {
@@ -8463,7 +8496,7 @@ SDD Telemetry CLI - 流程度量采集工具
   node skywalk-sdd/log.cjs semantic-identity --delta-state=modified --entity-id=<uuid> --predecessor-version=<uuid>
   node skywalk-sdd/log.cjs semantic-identity --delta-state=unchanged --entity-id=<uuid> --version-id=<uuid>
   node skywalk-sdd/log.cjs semantic-reconcile --project=<path> --change=<name> [--profile=auto|simple|full|strict]
-  node skywalk-sdd/log.cjs semantic-check --project=<path> --change=<name> [--profile=...]
+  node skywalk-sdd/log.cjs semantic-check --project=<path> --change=<name> [--profile=...] [--include-tasks]
   node skywalk-sdd/log.cjs semantic-status --project=<path> --change=<name>
   node skywalk-sdd/log.cjs semantic-observe --project=<path> --change=<name> [--interval=1500]
 
@@ -8481,7 +8514,7 @@ SDD Telemetry CLI - 流程度量采集工具
   semantic-identity 生成或复用实体/版本 ID（8 位十六进制）；无需网络和中央 ID 服务
   semantic-scan 只读解析并校验当前 Change
   semantic-reconcile 全量对账文件与本地工作态本体实例
-  semantic-check 全量对账并在通过时标记 pending
+  semantic-check 全量对账并在通过时标记 pending；--include-tasks 同时返回任务状态、评审输入清单和程序耗时
   semantic-status 读取当前工作态本体实例
   semantic-observe 观察文件变化并同步；不提供 Hook 式控制，Check/Archive 仍会全量对账