kld-sdd 2.4.12 → 2.4.13

package/README.md

@@ -136,16 +136,19 @@ propose → spec → design → task → check
 
 ---
 
-## 预置技能：`kld-sdd`
+## 预置技能
 
-初始化后，SDD 全套技能会统一打包部署到 `.*/skills/kld-sdd/`（与 `gitnexus/` 目录模式一致），包含 `opsx-propose`、`opsx-spec`、`opsx-design`、`opsx-task`、`opsx-check`、`opsx-apply`、`opsx-test`、`opsx-archive`、`opsx-explore`、`opsx-knowledge` 等子技能。
+初始化后，SDD 全套 skill 部署为 **扁平一层**（Claude Code 识别规则）：
 
-激活后，AI 会化身 **SDD 工作流专家**，检测当前项目的文档状态，引导你从当前进度继续：
+```
+.claude/skills/opsx-propose/SKILL.md   → /opsx-propose
+.claude/skills/opsx-spec/SKILL.md      → /opsx-spec
+...
+```
+
+模板源码组织在 `kld-sdd/templates/skills/kld-sdd/`（仅用于打包维护，不是 Claude 的识别路径）。
 
-> "当前项目变更：
-> - `add-user-auth`：propose✓ spec✓ design○ task○（建议下一步：design）
->
-> 请选择：A. 继续 / B. 创建新变更 / C. 质量检查"
+> Claude Code 只识别 `.claude/skills/<skill-name>/SKILL.md` 这一层。嵌套在 `skills/kld-sdd/opsx-*` 下不会被 `/` 菜单发现。GitNexus 能识别是因为 `npx gitnexus analyze` 同时安装了 `~/.claude/skills/gitnexus-*/` 扁平 skill。
 
 ---
 
@@ -190,19 +193,16 @@ your-project/
 │   └── task.md
 ├── .cursor/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/kld-sdd/              # SDD 技能统一目录
-│       ├── opsx-propose/
-│       ├── opsx-spec/
-│       └── ...                      # 其他 opsx-* 子技能
+│   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .claude/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/kld-sdd/              # SDD 技能统一目录
+│   └── skills/opsx-*/               # SDD skills（扁平一层）
 ├── .codebuddy/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/kld-sdd/              # SDD 技能统一目录
+│   └── skills/opsx-*/               # SDD skills（扁平一层）
 └── .agents/
     ├── commands/opsx/               # Codex opsx 命令（9个）
-    └── skills/kld-sdd/              # Codex 项目级技能
+    └── skills/opsx-*/               # Codex 项目级 skills
 ```
 
 ---

package/lib/init.js

@@ -504,43 +504,40 @@ function overrideOpsxCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
 }
 
 /**
- * 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/ 统一目录）
+ * 清理旧版嵌套 bundle（skills/kld-sdd/opsx-*）
+ * Claude Code 只识别 skills/<skill-name>/SKILL.md 一层，嵌套 bundle 无法被 / 菜单发现
  * @param {string[]} selectedTools - 用户选择的编辑器列表
  */
-function cleanupLegacyFlatOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
-  console.log('🧹 正在清理旧版扁平 opsx-* skills...');
+function cleanupLegacyBundledOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🧹 正在清理旧版嵌套 skills/kld-sdd/ bundle...');
 
   const cwd = process.cwd();
-  const legacySkillDirs = [...OPSX_SKILL_DIRS, 'opsx-sdd'];
 
   for (const toolKey of selectedTools) {
     const config = TOOL_CONFIGS[toolKey];
     if (!config || !config.skillsDir) continue;
 
-    const skillsDir = path.join(cwd, config.skillsDir);
-    if (!fs.existsSync(skillsDir)) continue;
-
-    let removed = 0;
-    for (const legacySkill of legacySkillDirs) {
-      const legacySkillDir = path.join(skillsDir, legacySkill);
-      if (fs.existsSync(legacySkillDir)) {
-        fs.rmSync(legacySkillDir, { recursive: true, force: true });
-        removed++;
-      }
+    const bundledDir = path.join(cwd, config.skillsDir, SKILLS_BUNDLE_NAME);
+    if (fs.existsSync(bundledDir)) {
+      fs.rmSync(bundledDir, { recursive: true, force: true });
+      console.log(`   🗑  ${config.name}: 删除嵌套 bundle ${SKILLS_BUNDLE_NAME}/`);
     }
 
-    if (removed > 0) {
-      console.log(`   🗑  ${config.name}: 删除 ${removed} 个旧版扁平 opsx skills`);
+    const legacySdd = path.join(cwd, config.skillsDir, 'opsx-sdd');
+    if (fs.existsSync(legacySdd)) {
+      fs.rmSync(legacySdd, { recursive: true, force: true });
+      console.log(`   🗑  ${config.name}: 删除旧版 opsx-sdd/`);
     }
   }
 
-  console.log('✅ 旧版扁平 opsx skills 清理完成');
+  console.log('✅ 旧版嵌套 bundle 清理完成');
   return true;
 }
 
 /**
  * 部署 SDD opsx skills
- * 从 templates/skills/kld-sdd/ 复制到各编辑器的 skills/kld-sdd/ 目录
+ * 模板源：templates/skills/kld-sdd/（源码组织）
+ * 部署目标：.claude/skills/opsx-<name>/SKILL.md（扁平一层，Claude Code 可识别）
  * @param {string[]} selectedTools - 用户选择的编辑器列表
  */
 function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
@@ -571,21 +568,17 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
     if (!config || !config.skillsDir) continue;
     
     const targetSkillsDir = path.join(cwd, config.skillsDir);
-    const targetBundleDir = path.join(targetSkillsDir, SKILLS_BUNDLE_NAME);
     
     // 确保 skills 目录存在
     if (!fs.existsSync(targetSkillsDir)) {
       fs.mkdirSync(targetSkillsDir, { recursive: true });
     }
-    if (!fs.existsSync(targetBundleDir)) {
-      fs.mkdirSync(targetBundleDir, { recursive: true });
-    }
     
-    console.log(`   部署 ${config.name} 的 ${SKILLS_BUNDLE_NAME} skills（${skillDirs.length} 个）...`);
+    console.log(`   部署 ${config.name} 的 opsx skills（${skillDirs.length} 个，扁平到 ${config.skillsDir}/）...`);
     
     for (const skillDir of skillDirs) {
       const sourceDir = path.join(skillsTemplatePath, skillDir);
-      const targetDir = path.join(targetBundleDir, skillDir);
+      const targetDir = path.join(targetSkillsDir, skillDir);
       
       if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
@@ -593,18 +586,9 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
       
       if (fs.existsSync(sourceDir)) {
         copyDirRendered(sourceDir, targetDir, config, toolKey);
-        console.log(`     ✓ ${SKILLS_BUNDLE_NAME}/${skillDir}`);
+        console.log(`     ✓ ${skillDir}/`);
       }
     }
-
-    // 复制 bundle 根目录说明文件（如 SKILLS.md）
-    for (const file of fs.readdirSync(skillsTemplatePath)) {
-      const sourceFile = path.join(skillsTemplatePath, file);
-      if (!fs.statSync(sourceFile).isFile()) continue;
-      const rendered = renderTemplate(fs.readFileSync(sourceFile, 'utf8'), config, toolKey);
-      fs.writeFileSync(path.join(targetBundleDir, file), rendered, 'utf8');
-      console.log(`     ✓ ${SKILLS_BUNDLE_NAME}/${file}`);
-    }
   }
   
   console.log('✅ opsx skills 部署完成');
@@ -1066,10 +1050,10 @@ async function main() {
     // 3. 部署 SDD opsx 命令（根据编辑器类型使用不同模板）
     overrideOpsxCommands(selectedTools);
 
-    // 4. 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/）
-    cleanupLegacyFlatOpsxSkills(selectedTools);
+    // 4. 清理旧版嵌套 skills/kld-sdd/ bundle（Claude Code 无法识别二层目录）
+    cleanupLegacyBundledOpsxSkills(selectedTools);
 
-    // 4.1 部署 SDD opsx skills（统一打包到 skills/kld-sdd/）
+    // 4.1 部署 SDD opsx skills（扁平到 .claude/skills/opsx-*/）
     deployOpsxSkills(selectedTools);
     
     // 4.2 清理原生 openspec-* skills（防止残留）

package/lib/skills-bundle.js

@@ -18,11 +18,9 @@ const OPSX_SKILL_DIRS = [
 ];
 
 function renderTemplate(content, config, toolKey) {
-  const skillsBundlePath = `${config.skillsDir}/${SKILLS_BUNDLE_NAME}`;
   return content
     .replace(/^\uFEFF/, '')
-    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey)
-    .replace(/<SkillsBundlePath>/g, skillsBundlePath);
+    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey);
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.4.12",
+  "version": "2.4.13",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
   "main": "index.js",
   "bin": {

package/templates/git-hooks/pre-push-sdd-check.cjs

@@ -10,12 +10,20 @@ function readArg(name) {
   return found ? found.slice(prefix.length) : '';
 }
 
+function resolveLogCli(projectRoot) {
+  const logCjs = path.join(projectRoot, 'skywalk-sdd', 'log.cjs');
+  if (fs.existsSync(logCjs)) {
+    return logCjs;
+  }
+  return null;
+}
+
 function main() {
   const projectRoot = path.resolve(readArg('project') || process.env.SDD_PROJECT || process.cwd());
   const changeName = readArg('change') || process.env.SDD_CHANGE || process.env.OPENSPEC_CHANGE || '';
-  const logCli = path.join(projectRoot, 'skywalk-sdd', 'log.js');
+  const logCli = resolveLogCli(projectRoot);
 
-  if (!fs.existsSync(logCli)) {
+  if (!logCli) {
     console.log('SDD pre-push: skywalk-sdd/log.cjs not found; doctor gate skipped.');
     return;
   }

package/templates/skills/kld-sdd/opsx-apply/SKILL.md

@@ -123,7 +123,7 @@ openspec list --json
 ```
 
 **【可选】业务知识库检索**：
-编码中遇到不明业务名词时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）辅助理解。
+编码中遇到不明业务名词时，可调用 **opsx-knowledge** skill 辅助理解。
 不得因知识库建议偏离 tasks/spec；查询失败时继续实施。
 
 ### 3. 解析 DAG 任务拓扑

package/templates/skills/kld-sdd/opsx-design/SKILL.md

@@ -95,7 +95,7 @@ openspec list
 | 数据库 Schema | 了解数据模型约束 | 纳入数据设计章节 |
 
 **【可选】业务知识库检索**：
-设计涉及 MM/CO 领域概念且 spec 未充分定义时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）。
+设计涉及 MM/CO 领域概念且 spec 未充分定义时，可调用 **opsx-knowledge** skill。
 仅作背景参考，不得覆盖 spec；内网不可达时跳过并继续 design。
 
 ### 3. 渐进式上下文加载

package/templates/skills/kld-sdd/opsx-knowledge/SKILL.md

@@ -72,22 +72,20 @@ RAGFLOW_API_KEY=ragflow-6xxy9RUUtRiE9N6gzpTLfQbY00tnGGKWsEuBR53zp0U
 
 ### 2. 调用检索脚本
 
-在项目根目录执行（路径由初始化时注入，统一在 `<SkillsBundlePath>/` 下）：
+在项目根目录执行（使用 skill 目录变量，与 gitnexus 子 skill 脚本引用方式一致）：
 
 ```bash
-node <SkillsBundlePath>/opsx-knowledge/scripts/retrieve.cjs --question="物料凭证是什么" --module=mm
-node <SkillsBundlePath>/opsx-knowledge/scripts/retrieve.cjs --question="成本中心与利润中心的区别" --module=co
-node <SkillsBundlePath>/opsx-knowledge/scripts/retrieve.cjs --question="..." --module=auto
+node ${CLAUDE_SKILL_DIR}/scripts/retrieve.cjs --question="物料凭证是什么" --module=mm
+node ${CLAUDE_SKILL_DIR}/scripts/retrieve.cjs --question="成本中心与利润中心的区别" --module=co
+node ${CLAUDE_SKILL_DIR}/scripts/retrieve.cjs --question="..." --module=auto
 ```
 
+`${CLAUDE_SKILL_DIR}` 由 Claude Code 注入，指向本 skill 目录（如 `.claude/skills/opsx-knowledge/`）。
+
 `--module` 取值：
 - `mm` / `co`：指定模块
 - `auto`：按 question 关键词自动匹配（默认）
 
-部署后示例：
-- Claude Code：`.claude/skills/kld-sdd/opsx-knowledge/scripts/retrieve.cjs`
-- Cursor：`.cursor/skills/kld-sdd/opsx-knowledge/scripts/retrieve.cjs`
-
 ### 3. 处理结果
 
 **成功（`ok: true`）**：读取 `chunks`，提炼 1-3 条建议，标注来源模块。

package/templates/skills/kld-sdd/opsx-propose/SKILL.md

@@ -89,7 +89,7 @@ allowed-tools:
 - API 文档 → 了解接口约束、数据模型
 
 **【可选】业务知识库检索**：
-遇到不明 MM/CO 业务名词时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）查询 RAGFlow 知识库。
+遇到不明 MM/CO 业务名词时，可调用 **opsx-knowledge** skill 查询 RAGFlow 知识库。
 结果仅作 `📚 知识库建议`，不得写入 proposal 强制约束；查询失败时继续主流程。
 
 ### 3. 创建变更目录

package/templates/skills/kld-sdd/opsx-spec/SKILL.md

@@ -99,7 +99,7 @@ openspec list
 | API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
 
 **【可选】业务知识库检索**：
-术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）。
+术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill。
 知识库结果仅供参考，spec 契约以用户确认和 proposal 为准；失败时不阻塞。
 
 ### 4. 【关键步骤】读取本地模板文件

package/templates/skills/kld-sdd/SKILLS.md

@@ -1,28 +0,0 @@
-# KLD SDD Skills Bundle
-
-所有 SDD 技能统一打包在本目录，部署到 `<SkillsBundlePath>/`（如 `.claude/skills/kld-sdd/`）。
-
-## 子技能索引
-
-| 技能 name | 路径 | 用途 |
-|-----------|------|------|
-| `opsx-propose` | `opsx-propose/SKILL.md` | 业务意图文档 |
-| `opsx-spec` | `opsx-spec/SKILL.md` | 技术契约 |
-| `opsx-design` | `opsx-design/SKILL.md` | 技术方案 |
-| `opsx-task` | `opsx-task/SKILL.md` | 任务拆解 |
-| `opsx-check` | `opsx-check/SKILL.md` | 质量门禁 |
-| `opsx-apply` | `opsx-apply/SKILL.md` | 变更实施 |
-| `opsx-test` | `opsx-test/SKILL.md` | 单元测试 |
-| `opsx-archive` | `opsx-archive/SKILL.md` | 变更归档 |
-| `opsx-explore` | `opsx-explore/SKILL.md` | 变更浏览 |
-| `opsx-knowledge` | `opsx-knowledge/SKILL.md` | RAGFlow 业务知识库（可选） |
-
-## 路径约定
-
-- 子 skill 内相对引用：如 `references/modules.md`、`scripts/retrieve.cjs`（相对于该 skill 目录）
-- 跨 skill 引用：使用 frontmatter 中的 `name`（如 `opsx-knowledge`），或 bundle 路径 `<SkillsBundlePath>/opsx-knowledge/`
-- 知识库脚本：`<SkillsBundlePath>/opsx-knowledge/scripts/retrieve.cjs`
-
-## 与 /opsx:* 命令的关系
-
-命令定义在 `.*/commands/opsx/*.md`；本 bundle 提供对应阶段的 skill 详细工作流。两者通过相同的 `name`（如 `opsx-propose`）关联，**不依赖扁平的 `skills/opsx-*` 顶层目录**。