kld-sdd 2.6.17 → 2.7.3

package/skywalk-sdd/index.cjs

@@ -1375,30 +1375,35 @@ function appendEventUnlocked(dataDir, changeName, event) {
   appendMarkdownLog(dataDir, changeName, event);
 }
 
-/** 追加一行 JSONL 到事件文件；同一 change 的事实写入和日志投影共享跨进程锁。 */
-function appendEvent(dataDir, changeName, event, options = {}) {
-  if (options.lockHeld) {
-    return appendEventUnlocked(dataDir, changeName, event);
-  }
-  return withEventWriteLock(dataDir, changeName, () => {
-    if (event?.type === 'stage_end') {
-      const existing = readAllEventEndsById(dataDir, event.event_id, changeName);
-      if (existing.length > 0) {
-        const latest = existing.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
-        if (latest.result !== event.result) {
-          const error = new Error(
-            `E_STAGE_END_CONFLICT: event_id "${event.event_id}" 已记录 result=${latest.result}，不能改为 ${event.result}`,
-          );
-          error.code = 'E_STAGE_END_CONFLICT';
-          throw error;
-        }
-        return { idempotent: true, event: latest };
-      }
-    }
-    appendEventUnlocked(dataDir, changeName, event);
-    return { idempotent: false, event };
-  });
-}
+	/** 追加一行 JSONL 到事件文件；同一 change 的事实写入和日志投影共享跨进程锁。
+	 *  kld-T06：Progress Runtime 已删除，appendEvent 仅负责本地持久化，不再做事件富化、
+	 *  agent 拉起、metadata refresh 或 artifact snapshot。
+	 */
+	function appendEvent(dataDir, changeName, event, options = {}) {
+	  if (options.lockHeld) {
+	    appendEventUnlocked(dataDir, changeName, event);
+	    return { idempotent: false, event };
+	  }
+	  const result = withEventWriteLock(dataDir, changeName, () => {
+	    if (event?.type === 'stage_end') {
+	      const existing = readAllEventEndsById(dataDir, event.event_id, changeName);
+	      if (existing.length > 0) {
+	        const latest = existing.sort((a, b) => timestampMs(b) - timestampMs(a))[0];
+	        if (latest.result !== event.result) {
+	          const error = new Error(
+	            `E_STAGE_END_CONFLICT: event_id "${event.event_id}" 已记录 result=${latest.result}，不能改为 ${event.result}`,
+	          );
+	          error.code = 'E_STAGE_END_CONFLICT';
+	          throw error;
+	        }
+	        return { idempotent: true, event: latest };
+	      }
+	    }
+	    appendEventUnlocked(dataDir, changeName, event);
+	    return { idempotent: false, event };
+	  });
+	  return result;
+	}
 
 /** 把 ISO 时间戳格式化为本地时区 `YYYY-MM-DD HH:mm:ss (UTC±HH:MM)`。
  *  execution-log 面向人读，统一用本地时区 + 显式偏移标注，避免 UTC 裸值与用户体感差 8 小时（N9）。 */
@@ -5385,6 +5390,20 @@ function cmdStart(args) {
   appendEvent(dataDir, event.change, event);
   writeActiveStage(projectRoot, event);
 
+  // kld-T05: 七值命令成功写入 stage_start 后，异步上报使用事件。
+  // test/explore 与失败路径不上报；上报失败不影响本地事件与退出码。
+  const usagePromise = (() => {
+    try {
+      const { mapCommandToUsageSkill } = require('./lib/usage-contract.cjs');
+      const skill = mapCommandToUsageSkill(command);
+      if (!skill) return null;
+      const { reportUsageOnce } = require('./lib/usage-reporter.cjs');
+      return reportUsageOnce({ skill, startedAt: timestamp }).catch(() => null);
+    } catch {
+      return null;
+    }
+  })();
+
   // 输出 JSON，方便 AI Agent 解析 event_id
   const output = {
     event_id: eventId,
@@ -5392,6 +5411,9 @@ function cmdStart(args) {
     message: `SDD ${command} 阶段开始记录（change: ${event.change}）`,
   };
   console.log(JSON.stringify(output, null, 2));
+  // 返回 usage 上报 promise（可能为 null），便于测试或调用方 await；
+  // 现有 main() 不读返回值，行为兼容。
+  return usagePromise;
 }
 
 const ONTOLOGY_AUTHORING_STAGES = new Set(['propose', 'spec', 'design', 'task', 'check']);
@@ -5738,6 +5760,9 @@ function cmdEnd(args, options = {}) {
       ...event.details.archive_result,
       ...actualPaths,
     };
+    if (event.details.archive_result.archive_id && !event.archive_id) {
+      event.archive_id = event.details.archive_result.archive_id;
+    }
   }
 
   appendEvent(dataDir, event.change, event);
@@ -5745,6 +5770,37 @@ function cmdEnd(args, options = {}) {
     clearActiveStage(projectRoot, startEvent);
   }
 
+  // Archive stage_end is remapped to archive_linked on the wire. Also emit an explicit
+  // run_ended so monitors that only listen for terminal kinds still close the run.
+  if (command === 'archive' && (result === 'success' || result === 'partial' || result === 'failed' || result === 'failure')) {
+    try {
+      const terminalResult = result === 'failure' ? 'failed' : result;
+      appendEvent(dataDir, event.change, cleanOptionalFields({
+        schema_version: SCHEMA_VERSION,
+        event_id: generateEventId(),
+        type: 'stage_end',
+        event_kind: 'run_ended',
+        source: event.source,
+        command: 'archive',
+        stage: 'archive',
+        change: event.change,
+        agent_type: event.agent_type,
+        project_root: projectRoot,
+        session_id: event.session_id,
+        git_sha: event.git_sha,
+        timestamp: nowISO(),
+        result: terminalResult,
+        summary: event.summary || '变更归档完成，运行已结束',
+        details: {
+          terminal_of: event.event_id,
+          archive_id: event.details?.archive_result?.archive_id,
+        },
+      }));
+    } catch (err) {
+      try { console.error(`[telemetry] run_ended 补发失败（不阻塞）: ${err.message}`); } catch {}
+    }
+  }
+
   // 终态摘要必须基于已经落库的 archive stage_end。
   if (command === 'archive') {
     try { appendChangeSummary(projectRoot, change, readEvents(dataDir, change)); } catch (err) {
@@ -5802,6 +5858,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;
 }
 
@@ -6246,6 +6315,64 @@ function normalizeStrictFinalOutputSnapshot(details) {
   };
 }
 
+/**
+ * Best-effort per-file byte sizes for apply delivery snapshots.
+ * Looks under projectRoot first, then its parent (split specs/code workspace).
+ * Never fails the record path — missing files simply omit size entries.
+ */
+function attachFinalOutputFileSizes(details, projectRoot) {
+  const snapshot = details?.final_output_snapshot;
+  if (!snapshot || !Array.isArray(snapshot.files) || snapshot.files.length === 0) {
+    return details;
+  }
+  const existing = (snapshot.file_sizes && typeof snapshot.file_sizes === 'object'
+    && !Array.isArray(snapshot.file_sizes))
+    ? { ...snapshot.file_sizes }
+    : {};
+  const roots = [];
+  const pushRoot = (candidate) => {
+    if (!candidate || typeof candidate !== 'string') return;
+    const resolved = path.resolve(candidate);
+    if (!roots.some((item) => item.toLowerCase?.() === resolved.toLowerCase() || item === resolved)) {
+      roots.push(resolved);
+    }
+  };
+  pushRoot(projectRoot);
+  if (projectRoot) pushRoot(path.dirname(projectRoot));
+
+  let changed = false;
+  for (const relative of snapshot.files) {
+    const rel = String(relative || '').trim().replace(/\\/g, '/');
+    if (!rel || Number.isInteger(existing[rel])) continue;
+    for (const root of roots) {
+      try {
+        const absolute = path.resolve(root, ...rel.split('/'));
+        const rootKey = process.platform === 'win32' ? root.toLowerCase() : root;
+        const absKey = process.platform === 'win32' ? absolute.toLowerCase() : absolute;
+        const prefix = rootKey.endsWith(path.sep) ? rootKey : `${rootKey}${path.sep}`;
+        if (absKey !== rootKey && !absKey.startsWith(prefix)) continue;
+        if (!fs.existsSync(absolute) || !fs.statSync(absolute).isFile()) continue;
+        const bytes = fs.statSync(absolute).size;
+        if (Number.isInteger(bytes) && bytes >= 0) {
+          existing[rel] = bytes;
+          changed = true;
+          break;
+        }
+      } catch {
+        // try next root
+      }
+    }
+  }
+  if (!changed && Object.keys(existing).length === 0) return details;
+  return {
+    ...details,
+    final_output_snapshot: {
+      ...snapshot,
+      file_sizes: existing,
+    },
+  };
+}
+
 function normalizeStrictTestResult(args, details) {
   const input = details?.test_results;
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -7362,7 +7489,10 @@ function cmdRecord(args) {
     details = normalizeStrictCheckResult(details, args.result);
   } else if (strict && type === 'final_output_snapshot') {
     strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
-    details = normalizeStrictFinalOutputSnapshot(details);
+    details = attachFinalOutputFileSizes(
+      normalizeStrictFinalOutputSnapshot(details),
+      projectRoot,
+    );
   } else if (strict) {
     strictRunId = requireStrictString(strictRunId, 'EVENT_RUN_ID_REQUIRED', 'run_id');
   }

package/skywalk-sdd/lib/git-identity.cjs

@@ -0,0 +1,270 @@
+// kld-T07 — git 身份持久缓存与后台刷新（慢 git 环境韧性）
+// 职责：~/.kld-sdd/git-identity.json 持久缓存读写（tmp+rename 原子）；
+//   TTL 判定（身份 7 天 / tombstone 1 天）；
+//   detached+unref 后台刷新（git config --get-regexp 单次调用，宽限 60s）；
+//   in-progress 锁（mtime TTL 120s）防并发多 spawn；
+//   仅 git 成功但字段缺失才写 tombstone；失败/超时不写，允许下次重试。
+// 设计背景：企业终端 git 进程启动 7~34s，前台 execFileSync 必然超时；
+//   稳态（缓存命中）零 git 调用、零额外延迟。
+// 依赖注入（spawn/execFileSync/now/env/homeDir）便于单测；Node 14 兼容。
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const childProcess = require('node:child_process');
+
+const IDENTITY_FILE_NAME = 'git-identity.json';
+const REFRESH_LOCK_NAME = 'git-identity.refresh.lock';
+const IDENTITY_TTL_MS = 7 * 24 * 3600 * 1000; // 身份缓存 7 天
+const TOMBSTONE_TTL_MS = 24 * 3600 * 1000; // tombstone 1 天
+const REFRESH_LOCK_TTL_MS = 120 * 1000; // in-progress 锁 120s
+const REFRESH_GIT_TIMEOUT_MS = 60 * 1000; // 后台 git 宽限 60s（适配 7-34s 慢机器）
+
+/** 解析 home：显式 homeDir > env KLD_SDD_HOME > os.homedir（与 pendingPathFor 同注入模式） */
+function resolveHome(homeDir, env) {
+  const e = env || process.env;
+  return homeDir || (e && e.KLD_SDD_HOME) || os.homedir();
+}
+
+function identityPathFor(homeDir, env) {
+  return path.join(resolveHome(homeDir, env), '.kld-sdd', IDENTITY_FILE_NAME);
+}
+
+function refreshLockPathFor(homeDir, env) {
+  return path.join(resolveHome(homeDir, env), '.kld-sdd', REFRESH_LOCK_NAME);
+}
+
+function nowMs(options) {
+  return options && typeof options.now === 'function' ? options.now() : Date.now();
+}
+
+/** 原子写 JSON（tmp+rename），与 writePendingAtomic 同款 */
+function writeJsonAtomic(filePath, obj) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  fs.writeFileSync(tmp, `${JSON.stringify(obj)}\n`, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * 写入身份缓存（readAt 可经 options.now 注入，测试 TTL 用）。
+ * @param {{userName:string,email:string}} identity
+ */
+function writeIdentityCache(identity, options = {}) {
+  writeJsonAtomic(identityPathFor(options.homeDir, options.env), {
+    userName: identity.userName,
+    email: identity.email,
+    readAt: new Date(nowMs(options)).toISOString(),
+  });
+}
+
+/** 写入 tombstone（确认无身份；TTL 1 天，防止每命令反复 spawn git） */
+function writeTombstone(options = {}) {
+  writeJsonAtomic(identityPathFor(options.homeDir, options.env), {
+    unavailable: true,
+    readAt: new Date(nowMs(options)).toISOString(),
+  });
+}
+
+/**
+ * 读身份缓存。
+ * @returns {{kind:'identity',userName:string,email:string,stale:boolean}
+ *          |{kind:'tombstone',stale:boolean}
+ *          |{kind:'miss'}}
+ *   损坏 JSON / 缺字段 / 文件不存在一律 miss
+ */
+function readIdentityCache(options = {}) {
+  let raw;
+  try {
+    raw = fs.readFileSync(identityPathFor(options.homeDir, options.env), 'utf8');
+  } catch {
+    return { kind: 'miss' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { kind: 'miss' };
+  }
+  if (!parsed || typeof parsed !== 'object') return { kind: 'miss' };
+  const readAt = Date.parse(typeof parsed.readAt === 'string' ? parsed.readAt : '');
+  const age = Number.isFinite(readAt) ? nowMs(options) - readAt : Infinity;
+  if (parsed.unavailable === true) {
+    return { kind: 'tombstone', stale: !(age >= 0 && age < TOMBSTONE_TTL_MS) };
+  }
+  if (
+    typeof parsed.userName === 'string' && parsed.userName
+    && typeof parsed.email === 'string' && parsed.email
+  ) {
+    return {
+      kind: 'identity',
+      userName: parsed.userName,
+      email: parsed.email,
+      stale: !(age >= 0 && age < IDENTITY_TTL_MS),
+    };
+  }
+  return { kind: 'miss' };
+}
+
+/**
+ * 获取 in-progress 锁：新鲜锁（<120s）存在或并发创建失败返回 false。
+ * 锁内容无语义，mtime 即心跳。
+ */
+function tryAcquireRefreshLock(options = {}) {
+  const lockPath = refreshLockPathFor(options.homeDir, options.env);
+  let stale = false;
+  try {
+    const st = fs.statSync(lockPath);
+    if (nowMs(options) - st.mtimeMs < REFRESH_LOCK_TTL_MS) return false;
+    stale = true; // 过期锁：可接管
+  } catch { /* 无锁 */ }
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    // 新建用 'wx' 排他竞争；过期锁允许覆盖接管（并发接管最多多刷一次，幂等无害）
+    fs.writeFileSync(lockPath, String(nowMs(options)), { encoding: 'utf8', flag: stale ? 'w' : 'wx' });
+    return true;
+  } catch {
+    return false; // 并发创建失败视为他人持锁
+  }
+}
+
+function releaseRefreshLock(options = {}) {
+  try {
+    fs.unlinkSync(refreshLockPathFor(options.homeDir, options.env));
+  } catch { /* ignore */ }
+}
+
+/**
+ * 触发后台刷新：detached+unref 子进程运行本文件 refresh 模式。
+ * spawn 抛错时释放锁。返回是否真正触发（false=锁被持有或 spawn 失败）。
+ */
+function triggerBackgroundRefresh(options = {}) {
+  if (!tryAcquireRefreshLock(options)) return false;
+  const spawnFn = (options && options.spawn) || childProcess.spawn;
+  try {
+    const child = spawnFn(
+      process.execPath,
+      [__filename, 'refresh', '--home', resolveHome(options.homeDir, options.env)],
+      { detached: true, stdio: 'ignore' },
+    );
+    if (child && typeof child.unref === 'function') child.unref();
+    return true;
+  } catch {
+    releaseRefreshLock(options);
+    return false;
+  }
+}
+
+/**
+ * 主入口（同步，零 git）：读持久缓存，必要时触发后台刷新。
+ * - 身份新鲜：直接返回，零 spawn
+ * - 身份过期：沿用旧值 + 触发刷新
+ * - tombstone 新鲜：返回 null，零 spawn
+ * - tombstone 过期 / miss：返回 null + 触发刷新
+ *
+ * @returns {{userName:string,email:string}|null}
+ */
+function ensureIdentity(options = {}) {
+  const cache = readIdentityCache(options);
+  if (cache.kind === 'identity') {
+    if (cache.stale) triggerBackgroundRefresh(options);
+    return { userName: cache.userName, email: cache.email };
+  }
+  if (cache.kind === 'tombstone' && !cache.stale) return null;
+  triggerBackgroundRefresh(options);
+  return null;
+}
+
+/**
+ * 后台刷新执行体（也可注入 execFileSync 在测试内 in-process 运行）。
+ * git 成功但字段缺失才写 tombstone；失败/超时什么都不写（允许下次重试）。
+ * 总是释放 in-progress 锁。
+ * @returns {boolean} git 调用是否成功（不代表一定写入了身份）
+ */
+function runRefresh(options = {}) {
+  const execFileSyncFn = (options && options.execFileSync) || childProcess.execFileSync;
+  try {
+    let out;
+    try {
+      out = String(execFileSyncFn('git', ['config', '--get-regexp', '^user\\.'], {
+        timeout: REFRESH_GIT_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore'],
+      }));
+    } catch {
+      return false; // 失败/超时：不写 tombstone，允许下次重试
+    }
+    let userName = '';
+    let email = '';
+    for (const line of out.split('\n')) {
+      const m = line.match(/^(\S+)\s+(.*)$/);
+      if (!m) continue;
+      if (m[1] === 'user.name') userName = m[2].trim();
+      else if (m[1] === 'user.email') email = m[2].trim();
+    }
+    if (userName && email) {
+      writeIdentityCache({ userName, email }, options);
+    } else {
+      writeTombstone(options);
+    }
+    return true;
+  } finally {
+    releaseRefreshLock(options);
+  }
+}
+
+/**
+ * refresh 子进程 CLI 入口：node git-identity.cjs refresh --home <dir>
+ * runRefresh 成功且回读缓存为 identity 时，lazy require usage-reporter 自触发一次
+ * pending 冲刷（身份就绪后数秒内补报，不再等下一次七值 start）。
+ * lazy require 规避循环依赖（usage-reporter 顶层已 require 本模块）。
+ * 返回 flush promise（无触发时为 resolved promise），便于测试 await。
+ */
+function runRefreshCli(argv, options = {}) {
+  const homeIdx = argv.indexOf('--home');
+  const homeDir = homeIdx >= 0 ? argv[homeIdx + 1] : undefined;
+  try {
+    const ok = runRefresh(Object.assign({}, options, { homeDir }));
+    if (!ok) return Promise.resolve(false);
+    // 回读缓存：仅真实写入 identity 才触发 flush（tombstone 不触发）
+    const cache = readIdentityCache({ homeDir });
+    if (cache.kind !== 'identity') return Promise.resolve(false);
+    try {
+      const { flushPendingUsage } = require('./usage-reporter.cjs');
+      return flushPendingUsage({ homeDir })
+        .catch(() => false)
+        .then(() => true);
+    } catch {
+      return Promise.resolve(true);
+    }
+  } catch { /* 永不抛到进程外 */ }
+  return Promise.resolve(false);
+}
+
+if (require.main === module) {
+  if (process.argv[2] === 'refresh') runRefreshCli(process.argv.slice(2));
+}
+
+module.exports = {
+  ensureIdentity,
+  readIdentityCache,
+  writeIdentityCache,
+  writeTombstone,
+  triggerBackgroundRefresh,
+  runRefresh,
+  runRefreshCli,
+  identityPathFor,
+  refreshLockPathFor,
+  IDENTITY_TTL_MS,
+  TOMBSTONE_TTL_MS,
+  REFRESH_LOCK_TTL_MS,
+  REFRESH_GIT_TIMEOUT_MS,
+};

package/skywalk-sdd/lib/shared.cjs

@@ -347,12 +347,27 @@ function loadKbState(anchorDir = __dirname, env = process.env) {
   return { config: null, path: null, warnings };
 }
 
+/** 监控项目绑定名长度上限：与 batch schema project_name maxLength 对齐。 */
+const PROJECT_NAME_MAX_LENGTH = 128;
+
+/**
+ * 归一化监控项目绑定名：非字符串或 trim 后为空 → null。
+ *
+ * @param {*} value
+ * @returns {string|null}
+ */
+function normalizeProjectName(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed === '' ? null : trimmed;
+}
+
 /**
  * 从 KB 配置 + 环境变量解析 KB 连接参数。
  *
  * @param {object} stateConfig — loadKbState().config
  * @param {object} [env=process.env]
- * @returns {{ apiBase: string, token: string, spaceId: string, kbId: string, targets: array }}
+ * @returns {{ apiBase: string, token: string, spaceId: string, kbId: string, targets: array, projectName: string|null }}
  */
 function resolveKbParams(stateConfig = {}, env = process.env) {
   const apiBase = stateConfig.api || env.ENGINEERING_KB_API || 'http://localhost:8090/api';
@@ -361,7 +376,136 @@ function resolveKbParams(stateConfig = {}, env = process.env) {
     ? stateConfig.targets[0].spaceId : '';
   const kbId = stateConfig.targets && stateConfig.targets.length > 0
     ? stateConfig.targets[0].kbId : '';
-  return { apiBase, token, spaceId, kbId, targets: stateConfig.targets || [] };
+  const projectName = normalizeProjectName(stateConfig.projectName)
+    || normalizeProjectName(env.ENGINEERING_KB_PROJECT_NAME);
+  return { apiBase, token, spaceId, kbId, targets: stateConfig.targets || [], projectName };
+}
+
+/**
+ * Normalize API client scope list from kb-state or env.
+ * @param {object} stateConfig
+ * @param {object} [env=process.env]
+ * @returns {string[]}
+ */
+function resolveKbScopes(stateConfig = {}, env = process.env) {
+  const fromState = stateConfig.scopes
+    || stateConfig.apiKeyScopes
+    || stateConfig.api_client_scopes;
+  if (Array.isArray(fromState)) {
+    return fromState.map((scope) => String(scope).trim()).filter(Boolean);
+  }
+  if (typeof fromState === 'string' && fromState.trim()) {
+    return fromState.split(/[\s,]+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  const fromEnv = env.ENGINEERING_KB_SCOPES || env.ENGINEERING_KB_API_SCOPES;
+  if (typeof fromEnv === 'string' && fromEnv.trim()) {
+    return fromEnv.split(/[\s,]+/).map((scope) => scope.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+// kld-T06: progress:write 校验、progress binding 读取已随 Progress Runtime 一并删除。
+// Archive/Knowledge 的 api_client 能力由 resolveKbParams / httpGetJson / uploadFile 等保留。
+
+/**
+ * 通过服务端 dimensions 端点校验当前 API Key 用户是否为指定项目成员。
+ *
+ * 用于 kb-config 配置期的项目绑定预校验；服务端 A3 仍在上传时做权威裁决
+ * （非成员置空、不阻断），因此本函数对端点缺失/网络失败软返回而不抛错。
+ *
+ * @param {string} specRoot — spec 包根目录（含 kb-state.json）
+ * @param {string} projectName — 待校验的项目名称
+ * @param {object} [options]
+ * @param {object} [options.env=process.env]
+ * @param {number} [options.timeoutMs=15000]
+ * @returns {Promise<{ ok: boolean, reason?: string, member: boolean|null, matchedProject?: object }>}
+ * @throws {Error} E_PROGRESS_BINDING_INCOMPLETE — kb-state 缺失或缺 api/apiKey
+ */
+async function verifyProjectMembershipViaServer(specRoot, projectName, options = {}) {
+  const env = options.env || process.env;
+  const normalized = normalizeProjectName(projectName);
+  if (!normalized || normalized.length > PROJECT_NAME_MAX_LENGTH) {
+    return { ok: false, reason: 'invalid_input', member: null };
+  }
+
+  const root = path.resolve(specRoot);
+  const { config: kbState, path: statePath } = loadKbState(root, env);
+  if (!kbState || !statePath) {
+    const error = new Error('kb-state.json not found');
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = ['kb-state.json'];
+    throw error;
+  }
+
+  const kbParams = resolveKbParams(kbState, env);
+  const missing = [];
+  if (!kbParams.apiBase) missing.push('api');
+  if (!kbParams.token) missing.push('apiKey');
+  if (missing.length > 0) {
+    const error = new Error(`Progress binding incomplete: missing ${missing.join(', ')}`);
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = missing;
+    throw error;
+  }
+
+  const apiBase = String(kbParams.apiBase).replace(/\/+$/, '');
+  const url = `${apiBase}/v1/sdd-runs/dimensions`;
+  let response;
+  try {
+    response = await httpGetJson(url, kbParams.token, options.timeoutMs || 15000);
+  } catch (error) {
+    // 鉴权失败（密钥失效/吊销）与端点缺失/网络异常分开归因，避免配置流程误导。
+    const statusMatch = error && /^HTTP (\d{3})\b/.exec(String(error.message || ''));
+    if (statusMatch && (statusMatch[1] === '401' || statusMatch[1] === '403')) {
+      return { ok: false, reason: 'auth_failed', member: null };
+    }
+    return { ok: false, reason: 'endpoint_unavailable', member: null };
+  }
+
+  const data = response && typeof response === 'object' && response.data != null
+    ? response.data
+    : response;
+  const projects = Array.isArray(data?.projects) ? data.projects : [];
+  const matched = projects.find((p) => {
+    const name = normalizeProjectName(p && (p.name || p.projectName));
+    return name === normalized;
+  });
+  return {
+    ok: true,
+    member: Boolean(matched),
+    matchedProject: matched
+      ? { id: matched.projectId || matched.id || null, name: normalized }
+      : undefined,
+  };
+}
+
+/**
+ * 原子写入/清除 kb-state.json 的 projectName（监控项目绑定），保留其余键。
+ *
+ * @param {string} specRoot — spec 包根目录
+ * @param {string|null} projectName — 项目名；null/空白 = 清除绑定
+ * @returns {{ ok: true, path: string, projectName: string|null }}
+ * @throws {Error} E_PROGRESS_BINDING_INCOMPLETE — kb-state.json 不存在
+ */
+function setKbProjectName(specRoot, projectName, options = {}) {
+  const env = options.env || process.env;
+  const root = path.resolve(specRoot);
+  const { config: kbState, path: statePath } = loadKbState(root, env);
+  if (!kbState || !statePath) {
+    const error = new Error('kb-state.json not found');
+    error.code = 'E_PROGRESS_BINDING_INCOMPLETE';
+    error.missingFields = ['kb-state.json'];
+    throw error;
+  }
+  const normalized = normalizeProjectName(projectName);
+  if (normalized && normalized.length > PROJECT_NAME_MAX_LENGTH) {
+    const error = new Error(`projectName 超长（>${PROJECT_NAME_MAX_LENGTH} 字符）`);
+    error.code = 'E_PROJECT_NAME_INVALID';
+    throw error;
+  }
+  const next = { ...kbState, projectName: normalized };
+  writeJsonAtomic(statePath, next);
+  return { ok: true, path: statePath, projectName: next.projectName };
 }
 
 // ═══════════════════════════════════════════════════════════════
@@ -656,6 +800,10 @@ module.exports = {
   IDE_DIRS,
   loadKbState,
   resolveKbParams,
+  resolveKbScopes,
+  normalizeProjectName,
+  verifyProjectMembershipViaServer,
+  setKbProjectName,
   // HTTP
   requestJson,
   httpGetJson,