kld-sdd 2.6.21 → 2.7.3

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -1,6 +1,10 @@
-// kld-T04 — 使用事件 reporter（kld-fixback RED#2/#4/#9 重构版）
-// 职责：单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
-//       HTTP 状态分类（confirmed/retry/unauthorized/drop）；401 原子清除 token；
+// kld-T04 — 使用事件 reporter（git 身份缓存化韧性版）
+// 职责：git 身份取自 ~/.kld-sdd/git-identity.json 持久缓存（git 仅由 git-identity.cjs
+//       后台刷新读取，慢 git 环境前台零调用）；无身份当前事件入 pending 队列不跳过，
+//       身份就绪后 flush 时注入身份补报；
+//       server 四级解析（config > kb-state.api > KLD_SDD_SERVER > 内置默认）；
+//       单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
+//       HTTP 状态分类（confirmed/retry/drop，401 归入 drop 不清任何本地状态）；
 //       并发安全（appendFileSync O_APPEND + 事件 id 差集提交）；不改原业务退出码。
 'use strict';
 
@@ -13,11 +17,12 @@ const {
   classifyUsageSubmitResponse,
   postJson,
   mapCommandToUsageSkill,
+  DEFAULT_SERVER_URL,
 } = require('./usage-contract.cjs');
 const {
   readUserConfig,
-  clearUserToken,
 } = require('./user-config.cjs');
+const gitIdentity = require('./git-identity.cjs');
 
 const PENDING_FILE_NAME = 'pending-usage.jsonl';
 const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
@@ -34,6 +39,73 @@ function pendingPathFor(homeDir) {
   return path.join(home, '.kld-sdd', PENDING_FILE_NAME);
 }
 
+// git 身份进程内缓存：仅缓存成功读取；失败不缓存，下次重试
+let gitIdentityCache = null;
+
+/**
+ * 读取本机 git 身份。
+ * - 来源：~/.kld-sdd/git-identity.json 持久缓存（git-identity.cjs 维护，
+ *   git 仅由 detached 后台刷新进程读取——慢 git 环境（7-34s 启动）前台零调用）
+ * - 进程内缓存：首次成功后复用；失败不缓存
+ * - 无缓存 / 缓存缺字段 / tombstone → 返回 null（调用方将当前事件入队待补报，
+ *   并已由 ensureIdentity 触发一次后台刷新）
+ *
+ * @param {string} [homeDir] — 测试注入 home；缺省走 KLD_SDD_HOME/os.homedir
+ * @returns {{userName:string, email:string}|null}
+ */
+function readGitIdentity(homeDir) {
+  if (gitIdentityCache) return gitIdentityCache;
+  const identity = gitIdentity.ensureIdentity({ homeDir });
+  if (!identity) return null;
+  gitIdentityCache = identity;
+  return gitIdentityCache;
+}
+
+/**
+ * 测试专用：重置进程内 git 身份缓存。
+ */
+function _resetGitIdentityCache() {
+  gitIdentityCache = null;
+}
+
+/**
+ * 四级解析上报地址：config.server → 项目 kb-state.json api → env KLD_SDD_SERVER → 内置默认。
+ * 每级均经 normalizeServerUrl；结果永远非空（默认地址兜底）。
+ *
+ * @param {{homeDir?:string, projectRoot?:string, env?:object}} [options]
+ * @returns {string}
+ */
+function resolveReportServer(options = {}) {
+  const env = options.env || process.env;
+  const projectRoot = options.projectRoot || process.cwd();
+  // 1. 用户级 config.server
+  const config = readUserConfig(options.homeDir);
+  if (config && typeof config.server === 'string') {
+    const normalized = normalizeServerUrl(config.server);
+    if (normalized) return normalized;
+  }
+  // 2. 项目级 kb-state.json 的 api
+  try {
+    const kbStatePath = path.join(projectRoot, 'kb-state.json');
+    if (fs.existsSync(kbStatePath)) {
+      const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
+      if (kbState && typeof kbState.api === 'string') {
+        const normalized = normalizeServerUrl(kbState.api);
+        if (normalized) return normalized;
+      }
+    }
+  } catch {
+    // kb-state 读取失败时静默，继续下一级
+  }
+  // 3. env KLD_SDD_SERVER
+  if (env && typeof env.KLD_SDD_SERVER === 'string') {
+    const normalized = normalizeServerUrl(env.KLD_SDD_SERVER);
+    if (normalized) return normalized;
+  }
+  // 4. 内置默认地址兜底
+  return normalizeServerUrl(DEFAULT_SERVER_URL);
+}
+
 /**
  * 生成事件唯一 id（基于时间戳 + pid + 随机字节）。
  * 用于 flush 提交时按 id 差集删除已确认行，避免 read-modify-write 覆盖并发 append。
@@ -174,21 +246,112 @@ function appendPending(event, filePath) {
 }
 
 /**
- * 提交单条事件；返回分类。
- * @returns {Promise<'confirmed'|'unauthorized'|'retry'|'drop'>}
+ * 提交单条事件；发送前注入 git 身份；返回分类。
+ * @returns {Promise<'confirmed'|'retry'|'drop'>}
  */
-async function submitOne(server, token, event, timeoutMs) {
-  // 提交时剔除内部 id（不上传给服务端）
-  const outgoing = Object.assign({}, event);
+async function submitOne(server, identity, event, timeoutMs) {
+  // 提交时剔除内部 id（不上传给服务端），统一注入当前 git 身份
+  // （兼容 pending 队列里无身份字段的遗留事件）
+  const outgoing = Object.assign({}, event, {
+    userName: identity.userName,
+    email: identity.email,
+  });
   delete outgoing.id;
   const result = await postJson(
     `${server}/api/v1/usage-events`,
     outgoing,
-    { token, timeoutMs },
+    { timeoutMs },
   );
   return classifyUsageSubmitResponse(result.statusCode);
 }
 
+/**
+ * 共享冲刷执行体：读 pending → 逐条提交 → 按 id 差集原子提交队列变化。
+ * reportUsageOnce（冲刷后发当前事件）与 flushPendingUsage（只冲刷）共用。
+ *
+ * @returns {Promise<{submitted:number, confirmedIds:Set, droppedIds:Set}>}
+ */
+async function flushPendingQueue(server, identity, pendingFile, deadlineStart) {
+  const deadline = deadlineStart || (Date.now() + SHARED_DEADLINE_MS);
+  const confirmedIds = new Set();   // 已成功的事件 id
+  const droppedIds = new Set();     // 4xx 永久失败的事件 id
+  let submitted = 0;
+
+  const { events: pendingEvents } = readPending(pendingFile);
+  let flushed = 0;
+  for (let i = 0; i < pendingEvents.length; i++) {
+    const ev = pendingEvents[i];
+    const remaining = deadline - Date.now();
+    if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
+
+    const timeoutMs = Math.max(50, remaining);
+    let classification;
+    try {
+      classification = await submitOne(server, identity, ev, timeoutMs);
+    } catch {
+      classification = 'retry';
+    }
+
+    if (classification === 'confirmed') {
+      flushed += 1;
+      submitted += 1;
+      if (ev.id) confirmedIds.add(ev.id);
+      continue;
+    }
+    if (classification === 'drop') {
+      // drop 丢弃该条（含 401），不 retained、不 break，继续下一条
+      if (ev.id) droppedIds.add(ev.id);
+      continue;
+    }
+    // retry：网络/5xx/429/timeout，本次及后续保留
+    break;
+  }
+
+  // 原子提交队列变化（按 id 差集删除已确认 + 已丢弃）
+  // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+  if (confirmedIds.size > 0 || droppedIds.size > 0) {
+    const { events: latestEvents } = readPending(pendingFile);
+    const retained = latestEvents.filter((e) => {
+      if (e.id && confirmedIds.has(e.id)) return false;
+      if (e.id && droppedIds.has(e.id)) return false;
+      return true;
+    });
+    writePendingAtomic(pendingFile, retained);
+  }
+
+  return { submitted, confirmedIds, droppedIds };
+}
+
+/**
+ * 只冲刷 pending 队列，不产生新事件（cmdEnd / git 身份就绪后的补报入口）。
+ * 无身份返回 skipped 零请求；任何失败均不抛。
+ *
+ * @param {object} [options]
+ * @param {string} [options.homeDir] — 测试注入
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
+ */
+async function flushPendingUsage(options = {}) {
+  const result = { submitted: 0, enqueued: false, skipped: false };
+  try {
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      result.skipped = true;
+      return result;
+    }
+    const pendingFile = pendingPathFor(options.homeDir);
+    const { events: pendingEvents } = readPending(pendingFile);
+    if (pendingEvents.length === 0) return result;
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
+    const flushed = await flushPendingQueue(server, identity, pendingFile);
+    result.submitted = flushed.submitted;
+    return result;
+  } catch {
+    // 兜底：永不抛到调用方
+    return result;
+  }
+}
+
 /**
  * 上报一次使用事件（主入口）。任何失败均不抛。
  *
@@ -196,119 +359,68 @@ async function submitOne(server, token, event, timeoutMs) {
  * @param {string} options.skill — 七值之一；非七值立即返回
  * @param {string} [options.startedAt] — ISO8601；缺省取当前
  * @param {string} [options.homeDir] — 测试注入
- * @param {Function} [options.onNotify] — 401 等用户提示
- * @returns {Promise<{submitted:number,enqueued:boolean,tokenCleared:boolean,skipped:boolean}>}
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
  */
 async function reportUsageOnce(options = {}) {
-  const result = { submitted: 0, enqueued: false, tokenCleared: false, skipped: false };
+  const result = { submitted: 0, enqueued: false, skipped: false };
   const skill = mapCommandToUsageSkill(options.skill);
   if (!skill) {
     result.skipped = true;
     return result;
   }
-  const onNotify = typeof options.onNotify === 'function' ? options.onNotify : () => {};
+
+  const startedAt = typeof options.startedAt === 'string' && options.startedAt
+    ? options.startedAt
+    : new Date().toISOString();
+  const currentEvent = { skill, startedAt, id: generateEventId() };
+  const pendingFile = pendingPathFor(options.homeDir);
 
   try {
-    const config = readUserConfig(options.homeDir);
-    if (!config || typeof config.token !== 'string' || !config.token) {
-      result.skipped = true;
-      return result;
-    }
-    const server = normalizeServerUrl(config.server || '');
-    if (!server) {
-      result.skipped = true;
+    // 无 git 身份：当前事件入队（无身份字段，与遗留事件同构），本次冲刷整体跳过、
+    // 队列原有内容保留；身份就绪后由后续 flush 注入身份补报（慢 git 环境不静默丢失）。
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      try {
+        appendPending(currentEvent, pendingFile);
+        result.enqueued = true;
+      } catch { /* append 失败静默，不改退出码 */ }
       return result;
     }
-    const token = config.token;
-
-    const startedAt = typeof options.startedAt === 'string' && options.startedAt
-      ? options.startedAt
-      : new Date().toISOString();
-    const currentEvent = { skill, startedAt, id: generateEventId() };
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
 
-    const pendingFile = pendingPathFor(options.homeDir);
-    const deadline = Date.now() + SHARED_DEADLINE_MS;
     const MAX_TIMEOUT_SKEW_MS = 500; // 调度容差
+    // 共享 3s deadline：冲刷与当前事件共用同一预算
+    const deadline = Date.now() + SHARED_DEADLINE_MS;
 
-    // 1. 先冲刷 pending（最多 100 条）
-    const { events: pendingEvents } = readPending(pendingFile);
-    const confirmedIds = new Set();   // 已成功的事件 id
-    const droppedIds = new Set();     // 4xx 永久失败的事件 id
-    const failedEarly = { hit: false, kind: null }; // 提前终止标记（unauthorized/retry）
-
-    let flushed = 0;
-    for (let i = 0; i < pendingEvents.length; i++) {
-      const ev = pendingEvents[i];
-      const remaining = deadline - Date.now();
-      if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
-
-      const timeoutMs = Math.max(50, remaining);
-      let classification;
-      try {
-        classification = await submitOne(server, token, ev, timeoutMs);
-      } catch {
-        classification = 'retry';
-      }
-
-      if (classification === 'confirmed') {
-        flushed += 1;
-        result.submitted += 1;
-        if (ev.id) confirmedIds.add(ev.id);
-        continue;
-      }
-      if (classification === 'unauthorized') {
-        // 401：原子清除 token；本次及后续不再请求
-        try {
-          if (clearUserToken(options.homeDir)) {
-            result.tokenCleared = true;
-            onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
-          }
-        } catch { /* ignore */ }
-        failedEarly.hit = true;
-        failedEarly.kind = 'unauthorized';
-        break;
-      }
-      if (classification === 'drop') {
-        // kld-fixback YELLOW#4: drop 丢弃该条，不 retained、不 break，继续下一条
-        if (ev.id) droppedIds.add(ev.id);
-        continue;
-      }
-      // retry：网络/5xx/429/timeout，本次及后续保留
-      failedEarly.hit = true;
-      failedEarly.kind = 'retry';
-      break;
-    }
+    // 1. 先冲刷 pending（最多 100 条；retry 提前终止时剩余保留）
+    const flushOutcome = await flushPendingQueue(server, identity, pendingFile, deadline);
+    result.submitted += flushOutcome.submitted;
+    // 冲刷提前失败判定：零提交、零 drop，且队列仍有残留（retry 语义）
+    const failedEarly = flushOutcome.submitted === 0
+      && flushOutcome.confirmedIds.size === 0
+      && flushOutcome.droppedIds.size === 0
+      && readPending(pendingFile).events.length > 0;
 
     // 2. 发当前事件（若仍有预算且未提前失败）
-    // kld-fixback-review#2 RED: flush 提前失败时当前事件必须入队（与 design
-    // 『网络/超时/429/5xx 将事件追加或保留在 pending 队列』一致），不得静默丢弃。
+    // flush 提前失败时当前事件必须入队，不得静默丢弃。
     let currentOutcome = 'pending'; // 'confirmed' | 'enqueued' | 'dropped' | 'pending'
-    if (failedEarly.hit) {
+    if (failedEarly) {
       currentOutcome = 'enqueued';
     } else {
       const remaining = deadline - Date.now();
       if (remaining > MAX_TIMEOUT_SKEW_MS) {
         let classification;
         try {
-          classification = await submitOne(server, token, currentEvent, remaining);
+          classification = await submitOne(server, identity, currentEvent, remaining);
         } catch {
           classification = 'retry';
         }
         if (classification === 'confirmed') {
           result.submitted += 1;
           currentOutcome = 'confirmed';
-        } else if (classification === 'unauthorized') {
-          try {
-            if (clearUserToken(options.homeDir)) {
-              result.tokenCleared = true;
-              onNotify('检测到平台凭证已失效，请运行 `kld-sdd auth login` 重新绑定。');
-            }
-          } catch { /* ignore */ }
-          currentOutcome = 'enqueued';
-          failedEarly.hit = true;
-          failedEarly.kind = 'unauthorized';
         } else if (classification === 'drop') {
-          // kld-fixback YELLOW#4: 当前事件 drop 直接丢弃不入队
+          // 当前事件 drop（含 401）直接丢弃不入队，不清任何本地状态
           currentOutcome = 'dropped';
         } else {
           currentOutcome = 'enqueued';
@@ -318,18 +430,8 @@ async function reportUsageOnce(options = {}) {
       }
     }
 
-    // 3. 原子提交队列变化（按 id 差集删除已确认 + 已丢弃；append 当前事件若需要）
-    // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+    // 3. append 当前事件（若需要）
     try {
-      if (confirmedIds.size > 0 || droppedIds.size > 0) {
-        const { events: latestEvents } = readPending(pendingFile);
-        const retained = latestEvents.filter((e) => {
-          if (e.id && confirmedIds.has(e.id)) return false;
-          if (e.id && droppedIds.has(e.id)) return false;
-          return true;
-        });
-        writePendingAtomic(pendingFile, retained);
-      }
       if (currentOutcome === 'enqueued') {
         appendPending(currentEvent, pendingFile);
         result.enqueued = true;
@@ -345,8 +447,12 @@ async function reportUsageOnce(options = {}) {
 
 module.exports = {
   reportUsageOnce,
+  flushPendingUsage,
   appendPending,
   readPending,
+  readGitIdentity,
+  resolveReportServer,
+  _resetGitIdentityCache,
   PENDING_FILE_NAME,
   PENDING_MAX_BYTES,
   FLUSH_MAX_COUNT,

package/skywalk-sdd/lib/user-config.cjs

@@ -1,13 +1,14 @@
 // kld-T02 — ~/.kld-sdd/config.json 用户级配置管理
-// 职责：读取、规范化、原子写、0600/Windows ACL、401 token 清除、敏感信息脱敏。
-// 与 kb-sdd 跨仓契约对齐：cli_token 仅存于此，不进入 Archive/Knowledge 请求。
+// 职责：读取、规范化、原子写、0600/Windows ACL。
+// schema v2 = {version, server}；使用统计按 git 身份上报，不再保存任何 token。
+// 旧版含 token/userName/boundAt 的 config 读取时 sanitize 为 {version, server}，回写即淘汰。
 'use strict';
 
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const USER_CONFIG_VERSION = 1;
+const USER_CONFIG_VERSION = 2;
 const CONFIG_DIR_NAME = '.kld-sdd';
 const CONFIG_FILE_NAME = 'config.json';
 
@@ -32,9 +33,23 @@ function getConfigPath(homeDir) {
   return path.join(getConfigDir(homeDir), CONFIG_FILE_NAME);
 }
 
+/**
+ * 将任意已解析对象规范化为 v2 config：只保留 {version, server}。
+ * @param {object} parsed
+ * @returns {{version: number, server?: string}}
+ */
+function sanitizeConfig(parsed) {
+  const config = { version: USER_CONFIG_VERSION };
+  if (typeof parsed.server === 'string') {
+    config.server = parsed.server;
+  }
+  return config;
+}
+
 /**
  * 读取用户配置。
  * - 文件不存在 / 损坏 JSON / 非对象 → 返回 null（不抛）
+ * - 旧版多余字段（token/userName/boundAt 等）读取即忽略，不回传
  * - 返回新引用；调用方修改不影响后续读取
  *
  * @param {string} [homeDir]
@@ -55,12 +70,7 @@ function readUserConfig(homeDir) {
     return null;
   }
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
-  // 深拷贝隔离
-  try {
-    return JSON.parse(JSON.stringify(parsed));
-  } catch {
-    return null;
-  }
+  return sanitizeConfig(parsed);
 }
 
 /**
@@ -83,6 +93,7 @@ function hardenPermissions(target, kind) {
 
 /**
  * 原子写入用户配置：先 temp 后 rename，目录与文件均设置权限。
+ * 只持久化 {version, server}，多余字段写入即淘汰。
  * @param {object} config — 必须含 version 字段
  * @param {string} [homeDir]
  * @throws {Error} config 非法 / 缺 version
@@ -100,7 +111,7 @@ function writeUserConfig(config, homeDir) {
   hardenPermissions(dir, 'dir');
 
   const tmp = path.join(dir, `.${CONFIG_FILE_NAME}.${process.pid}.${Date.now()}.tmp`);
-  const payload = JSON.stringify(config, null, 2);
+  const payload = JSON.stringify(sanitizeConfig(config), null, 2);
   fs.writeFileSync(tmp, payload, { encoding: 'utf8', mode: 0o600 });
   hardenPermissions(tmp, 'file');
   try {
@@ -112,46 +123,10 @@ function writeUserConfig(config, homeDir) {
   hardenPermissions(file, 'file');
 }
 
-/**
- * 原子清除 token 字段，保留其他所有字段。
- * - 文件不存在 / 损坏 / 已无 token → 幂等返回 false
- * - 成功清除返回 true
- *
- * @param {string} [homeDir]
- * @returns {boolean}
- */
-function clearUserToken(homeDir) {
-  const file = getConfigPath(homeDir);
-  if (!fs.existsSync(file)) return false;
-  const current = readUserConfig(homeDir);
-  if (!current) return false;
-  if (!Object.prototype.hasOwnProperty.call(current, 'token')) return false;
-  delete current.token;
-  writeUserConfig(current, homeDir);
-  return true;
-}
-
-/**
- * 敏感信息脱敏：任何非空字符串 token 一律返回 '***'。
- * - 空字符串保持空字符串
- * - 非字符串原样返回
- * - 永不抛出
- *
- * @param {*} value
- * @returns {*}
- */
-function redactToken(value) {
-  if (typeof value !== 'string') return value;
-  if (value.length === 0) return '';
-  return '***';
-}
-
 module.exports = {
   USER_CONFIG_VERSION,
   getConfigDir,
   getConfigPath,
   readUserConfig,
   writeUserConfig,
-  clearUserToken,
-  redactToken,
 };

package/skywalk-sdd/ontology/artifact-parser.cjs

@@ -200,7 +200,7 @@ function identityFromValues(values = {}) {
 }
 
 function flushRequirementRef(requirementRefs, currentRef) {
-  if (!currentRef) return null;
+  if (!currentRef) return;
   const { normalize, validate } = require('./external-key.cjs');
   const system = currentRef.system;
   const objectType = currentRef['object-type'] || currentRef.object_type;
@@ -224,7 +224,6 @@ function flushRequirementRef(requirementRefs, currentRef) {
     }
     requirementRefs.push(entry);
   }
-  return null;
 }
 
 function parseStructuredFrontmatter(lines) {

package/templates/git-hooks/commit-msg

@@ -1,6 +1,7 @@
 #!/bin/sh
 # KLD SDD Commit-MSG Hook
-# 自动查找 commit-msg-sdd-trailer.cjs，兼容单仓库/多仓库/单仓mono布局
+# 在下方 SCRIPTS 列表中声明要加载的 .cjs 脚本
+# 删除某行 = 禁用该插件
 # marker: KLD SDD quality gate
 
 # 从 hook 所在目录推算 git 根目录
@@ -8,39 +9,81 @@ hook_dir="$(cd "$(dirname "$0")" && pwd)"
 git_dir="$(dirname "$hook_dir")"
 git_root="$(dirname "$git_dir")"
 
-script=""
+hooks_dir=""
 
 # 方法1: git config sdd.specPath（多仓布局：spec 是独立 clone）
 spec_path=$(git config --local sdd.specPath 2>/dev/null)
-if [ -n "$spec_path" ] && [ -f "$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
-  script="$spec_path/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+if [ -n "$spec_path" ] && [ -d "$spec_path/skywalk-sdd/git-hooks" ]; then
+  hooks_dir="$spec_path/skywalk-sdd/git-hooks"
 fi
 
 # 方法2: .sdd-spec-root（单仓 mono 布局：skywalk-sdd 在 spec 包裹包子目录内）
-if [ -z "$script" ] && [ -f "$git_root/.sdd-spec-root" ]; then
+if [ -z "$hooks_dir" ] && [ -f "$git_root/.sdd-spec-root" ]; then
   spec_rel=$(cat "$git_root/.sdd-spec-root" | head -1 | tr -d '[:space:]')
-  if [ -n "$spec_rel" ] && [ -f "$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
-    script="$git_root/$spec_rel/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+  if [ -n "$spec_rel" ] && [ -d "$git_root/$spec_rel/skywalk-sdd/git-hooks" ]; then
+    hooks_dir="$git_root/$spec_rel/skywalk-sdd/git-hooks"
   fi
 fi
 
 # 方法3: 从 git 根向上搜索 skywalk-sdd/git-hooks（spec 仓本身或父级）
-if [ -z "$script" ]; then
+if [ -z "$hooks_dir" ]; then
   search_dir="$git_root"
   while [ "$search_dir" != "/" ] && [ "$search_dir" != "" ]; do
-    if [ -f "$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs" ]; then
-      script="$search_dir/skywalk-sdd/git-hooks/commit-msg-sdd-trailer.cjs"
+    if [ -d "$search_dir/skywalk-sdd/git-hooks" ]; then
+      hooks_dir="$search_dir/skywalk-sdd/git-hooks"
       break
     fi
     search_dir="$(dirname "$search_dir")"
   done
 fi
 
-if [ -z "$script" ]; then
-  echo "[SDD] 未找到 commit-msg-sdd-trailer.cjs，跳过 commit-msg trailer"
+if [ -z "$hooks_dir" ]; then
+  echo "[SDD] 未找到 spec 仓的 skywalk-sdd/git-hooks 目录，跳过 commit-msg"
   exit 0
 fi
 
-# $1 = Git 传入的 commit message 文件路径
-# --project 告诉 .cjs 脚本代码仓根目录（用于解析 spec 布局）
-node "$script" "$1" --project="$git_root"
+# 从配置文件读取插件列表
+config_file="$hooks_dir/hooks.config"
+if [ ! -f "$config_file" ]; then
+  echo "[SDD] ⚠️  配置文件不存在：hooks.config，使用默认插件"
+  SCRIPTS="commit-msg-sdd-trailer.cjs"
+else
+  # 读取 [commit-msg] 段落的配置
+  in_section=0
+  SCRIPTS=""
+  while IFS= read -r line; do
+    line=$(printf '%s' "$line" | tr -d '\r')
+    case "$line" in
+      "[commit-msg]") in_section=1 ;;
+      "["*) in_section=0 ;;
+      "#"*|"") ;;
+      *)
+        if [ "$in_section" -eq 1 ]; then
+          SCRIPTS="$SCRIPTS $line"
+        fi
+        ;;
+    esac
+  done < "$config_file"
+fi
+
+executed=0
+failed=0
+for script_name in $SCRIPTS; do
+  script="$hooks_dir/$script_name"
+  if [ ! -f "$script" ]; then
+    echo "[SDD] ⚠️  插件不存在：$script_name"
+    continue
+  fi
+  executed=$((executed + 1))
+  echo "[SDD] 执行 commit-msg 插件：$script_name"
+  node "$script" "$1" --project="$git_root" || failed=$((failed + 1))
+done
+
+if [ "$executed" -eq 0 ]; then
+  echo "[SDD] 无 commit-msg 插件，跳过"
+elif [ "$failed" -gt 0 ]; then
+  echo "[SDD] ❌ 共执行 $executed 个 commit-msg 插件，$failed 个失败"
+  exit 1
+else
+  echo "[SDD] ✅ 共执行 $executed 个 commit-msg 插件，全部通过"
+fi

package/templates/git-hooks/hooks.config

@@ -0,0 +1,19 @@
+# KLD SDD Hook 插件配置文件
+# 每行一个脚本名，空行和 # 开头的行会被忽略
+# 注释某行 = 禁用该插件，取消注释 = 启用该插件
+
+[commit-msg]
+# 自动写入 Spec-Change / Spec-Revision Trailer 到 commit message
+commit-msg-sdd-trailer.cjs
+
+[pre-commit]
+# 检查 tasks.md 中是否有未完成的归档任务
+pre-commit-sdd-check.cjs
+# 检查 Spec 一致性校验报告（置信度、过期、人工确认等）
+pre-commit-consistency-check.cjs
+
+[pre-push]
+# 运行 doctor 完整诊断（配置、Trailer 协议、活动变更等）
+pre-push-sdd-check.cjs
+# 轻量检查一致性报告是否存在、是否过期
+pre-push-consistency-check.cjs