kld-sdd 2.4.10 → 2.4.11

package/README.md

@@ -136,9 +136,9 @@ propose → spec → design → task → check
 
 ---
 
-## 预置技能：`opsx-sdd`
+## 预置技能：`kld-sdd`
 
-初始化后，`opsx-sdd` 技能会自动部署到你的编辑器技能目录（`.*/skills/opsx-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` 等子技能。
 
 激活后，AI 会化身 **SDD 工作流专家**，检测当前项目的文档状态，引导你从当前进度继续：
 
@@ -190,16 +190,19 @@ your-project/
 │   └── task.md
 ├── .cursor/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
+│       ├── opsx-propose/
+│       ├── opsx-spec/
+│       └── ...                      # 其他 opsx-* 子技能
 ├── .claude/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
 ├── .codebuddy/
 │   ├── commands/opsx/               # opsx 命令（9个）
-│   └── skills/opsx-*/               # 预置 SDD 技能
+│   └── skills/kld-sdd/              # SDD 技能统一目录
 └── .agents/
     ├── commands/opsx/               # Codex opsx 命令（9个）
-    └── skills/opsx-*/               # Codex 项目级技能
+    └── skills/kld-sdd/              # Codex 项目级技能
 ```
 
 ---

package/lib/init.js

@@ -327,9 +327,7 @@ function copyDir(source, target) {
 }
 
 function renderTemplate(content, config, toolKey) {
-  return content
-    .replace(/^\uFEFF/, '')
-    .replace(/<Agent(?:\u7c7b\u578b|\u7eeb\u8bf2\u7037)>/g, config.agentType || toolKey);
+  return require('./skills-bundle').renderTemplate(content, config, toolKey);
 }
 
 function copyDirRendered(source, target, config, toolKey) {
@@ -504,9 +502,50 @@ function overrideOpsxCommands(selectedTools = Object.keys(TOOL_CONFIGS)) {
   return true;
 }
 
+const {
+  SKILLS_BUNDLE_NAME,
+  OPSX_SKILL_DIRS,
+  renderTemplate
+} = require('./skills-bundle');
+
+/**
+ * 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/ 统一目录）
+ * @param {string[]} selectedTools - 用户选择的编辑器列表
+ */
+function cleanupLegacyFlatOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
+  console.log('🧹 正在清理旧版扁平 opsx-* skills...');
+
+  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++;
+      }
+    }
+
+    if (removed > 0) {
+      console.log(`   🗑  ${config.name}: 删除 ${removed} 个旧版扁平 opsx skills`);
+    }
+  }
+
+  console.log('✅ 旧版扁平 opsx skills 清理完成');
+  return true;
+}
+
 /**
- * 部署 SDD opsx skills（9 个技能文件）
- * 从 templates/skills/ 目录复制到各编辑器的 skills 目录
+ * 部署 SDD opsx skills
+ * 从 templates/skills/kld-sdd/ 复制到各编辑器的 skills/kld-sdd/ 目录
  * @param {string[]} selectedTools - 用户选择的编辑器列表
  */
 function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
@@ -515,14 +554,14 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
   const pkgPath = getPackagePath();
   const cwd = process.cwd();
   
-  const skillsTemplatePath = path.join(pkgPath, 'templates', 'skills');
+  const skillsTemplatePath = path.join(pkgPath, 'templates', 'skills', SKILLS_BUNDLE_NAME);
   
   if (!fs.existsSync(skillsTemplatePath)) {
     console.log(`⚠️  SDD skills 模板目录不存在: ${skillsTemplatePath}`);
     return false;
   }
   
-  // 获取所有 skill 目录
+  // 获取 bundle 内所有 skill 目录
   const skillDirs = fs.readdirSync(skillsTemplatePath).filter(d => {
     return fs.statSync(path.join(skillsTemplatePath, d)).isDirectory();
   });
@@ -537,17 +576,21 @@ 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} 的 opsx skills（${skillDirs.length} 个）...`);
+    console.log(`   部署 ${config.name} 的 ${SKILLS_BUNDLE_NAME} skills（${skillDirs.length} 个）...`);
     
     for (const skillDir of skillDirs) {
       const sourceDir = path.join(skillsTemplatePath, skillDir);
-      const targetDir = path.join(targetSkillsDir, skillDir);
+      const targetDir = path.join(targetBundleDir, skillDir);
       
       if (!fs.existsSync(targetDir)) {
         fs.mkdirSync(targetDir, { recursive: true });
@@ -555,9 +598,18 @@ function deployOpsxSkills(selectedTools = Object.keys(TOOL_CONFIGS)) {
       
       if (fs.existsSync(sourceDir)) {
         copyDirRendered(sourceDir, targetDir, config, toolKey);
-        console.log(`     ✓ ${skillDir}`);
+        console.log(`     ✓ ${SKILLS_BUNDLE_NAME}/${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 部署完成');
@@ -1019,10 +1071,13 @@ async function main() {
     // 3. 部署 SDD opsx 命令（根据编辑器类型使用不同模板）
     overrideOpsxCommands(selectedTools);
 
-    // 4. 部署 SDD opsx skills
+    // 4. 清理旧版扁平 opsx-* skills（迁移到 skills/kld-sdd/）
+    cleanupLegacyFlatOpsxSkills(selectedTools);
+
+    // 4.1 部署 SDD opsx skills（统一打包到 skills/kld-sdd/）
     deployOpsxSkills(selectedTools);
     
-    // 4.1 清理原生 openspec-* skills（防止残留）
+    // 4.2 清理原生 openspec-* skills（防止残留）
     cleanupNativeOpenspecSkills(selectedTools);
 
     // 4.2 部署 Claude Code Hook Pack（可选增强）

package/lib/skills-bundle.js

@@ -0,0 +1,32 @@
+/**
+ * SDD skills bundle 共享配置与模板渲染
+ */
+
+const SKILLS_BUNDLE_NAME = 'kld-sdd';
+
+const OPSX_SKILL_DIRS = [
+  'opsx-propose',
+  'opsx-spec',
+  'opsx-design',
+  'opsx-task',
+  'opsx-check',
+  'opsx-apply',
+  'opsx-test',
+  'opsx-archive',
+  'opsx-explore',
+  'opsx-knowledge'
+];
+
+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);
+}
+
+module.exports = {
+  SKILLS_BUNDLE_NAME,
+  OPSX_SKILL_DIRS,
+  renderTemplate
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kld-sdd",
-  "version": "2.4.10",
+  "version": "2.4.11",
   "description": "KLD SDD OpenSpec 项目初始化工具 - 内置模版一键初始化",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
     "kld-sdd-init": "bin/kld-sdd-init.js"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node test/validate-skills-bundle.cjs"
   },
   "keywords": [
     "kld",

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

@@ -0,0 +1,28 @@
+# 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-*` 顶层目录**。

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

@@ -122,6 +122,10 @@ openspec list --json
 ⛔ 隔离红线：禁止加载其他 Capability 的文档！
 ```
 
+**【可选】业务知识库检索**：
+编码中遇到不明业务名词时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）辅助理解。
+不得因知识库建议偏离 tasks/spec；查询失败时继续实施。
+
 ### 3. 解析 DAG 任务拓扑
 
 从 tasks.md 中：

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

@@ -94,6 +94,10 @@ openspec list
 | 架构文档 | 了解系统边界、模块关系 | 对齐总体设计方向 |
 | 数据库 Schema | 了解数据模型约束 | 纳入数据设计章节 |
 
+**【可选】业务知识库检索**：
+设计涉及 MM/CO 领域概念且 spec 未充分定义时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）。
+仅作背景参考，不得覆盖 spec；内网不可达时跳过并继续 design。
+
 ### 3. 渐进式上下文加载
 
 **⛔ 必须严格按以下顺序加载：**

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

@@ -0,0 +1,132 @@
+---
+name: opsx-knowledge
+description: "Queries RAGFlow business knowledge base for MM/CO domain terms during SDD workflows. Use when encountering unclear business nouns, internal ERP terminology, MM/CO module concepts, or domain rules in propose/spec/design/apply. Results are advisory only and must not override SDD documents or user input."
+argument-hint: "[question] [--module=mm|co|auto]"
+license: MIT
+metadata:
+  author: sdd-team
+  version: "1.0"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# SDD 业务知识库检索（RAGFlow）
+
+为 SDD 工作流提供 **MM / CO 模块** 的业务知识检索。检索结果 **只做建议参考**，不得作为强制约束写入 spec 红线。
+
+## RAGFlow 知识库配置
+
+```env
+RAGFLOW_BASE_URL=http://10.29.219.26:9380
+RAGFLOW_API_KEY=ragflow-6xxy9RUUtRiE9N6gzpTLfQbY00tnGGKWsEuBR53zp0U
+```
+
+| 模块 | dataset_id |
+|------|------------|
+| MM模块 | `12eda67a4ffb11f19cb713ede57b176f` |
+| CO模块 | `02841d1e4ffb11f19cb713ede57b176f` |
+
+配置已写死在 `scripts/config.json`，脚本会自动读取。
+
+---
+
+## 使用原则（强制）
+
+1. **可选**：仅当业务名词/领域含义不清时才查询
+2. **非强制**：不得因知识库结果覆盖 proposal / spec / design / 用户确认内容
+3. **冲突处理**：与用户输入、现有代码、openspec 文档冲突时，以用户 / 文档 / 代码为准
+4. **引用格式**：输出中标注 `📚 知识库建议：...`，禁止写成“必须 / 规定 / 红线”
+5. **失败降级**：内网不可达、超时、无结果时 **继续 SDD 主流程**，仅提示“未查询到知识库”
+
+---
+
+## 何时查询
+
+**适合查询：**
+- 不明业务名词（如“物料凭证”“评估类”“成本中心”）
+- MM / CO 模块内部术语
+- propose / spec / design 阶段需要补充领域背景
+
+**不必查询：**
+- 通用技术概念
+- 文档已明确定义
+- 用户已给出权威解释
+
+模块判断细则见 [references/modules.md](references/modules.md)。
+
+---
+
+## 执行步骤
+
+### 1. 判断模块
+
+按上下文自行判断查询 **MM**、**CO**，或两者都查：
+
+| 信号 | 倾向模块 |
+|------|----------|
+| 物料、库存、采购、MRP、BOM、仓库 | MM |
+| 成本、费用、预算、核算、CO-PA、成本中心 | CO |
+| proposal/spec 的 capability 名称或路径 | 按模块归属 |
+| 无法判断 | 跳过查询，不阻塞主流程 |
+
+### 2. 调用检索脚本
+
+在项目根目录执行（路径由初始化时注入，统一在 `<SkillsBundlePath>/` 下）：
+
+```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
+```
+
+`--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 条建议，标注来源模块。
+
+**失败（`ok: false`）**：不 retry 阻塞主流程，继续原有 SDD 步骤。
+
+输出模板：
+
+```markdown
+📚 知识库建议（MM模块，仅供参考）：
+- ...
+- ...
+
+说明：以上来自 RAGFlow 知识库，不作为 SDD 契约；如与 spec / 用户输入冲突，以 spec / 用户输入为准。
+```
+
+---
+
+## API 参考
+
+内网 RAGFlow retrieval 接口：
+
+```bash
+curl --request POST \
+  --url http://10.29.219.26:9380/api/v1/retrieval \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer ragflow-6xxy9RUUtRiE9N6gzpTLfQbY00tnGGKWsEuBR53zp0U' \
+  --data '{
+    "question": "What is advantage of ragflow?",
+    "dataset_ids": ["12eda67a4ffb11f19cb713ede57b176f"]
+  }'
+```
+
+日常优先使用 `scripts/retrieve.cjs`，不要手写 curl。
+
+---
+
+## 与其他 SDD Skill 的关系
+
+- **opsx-propose / opsx-spec / opsx-design / opsx-apply**：遇到业务名词时可 **可选** 调用本 skill
+- **opsx-check**：不得把知识库内容当作质量红线依据
+- 本 skill **不修改** 任何 openspec 文档，只提供参考信息

package/templates/skills/kld-sdd/opsx-knowledge/references/modules.md

@@ -0,0 +1,26 @@
+# 模块知识库映射
+
+| 模块 | dataset_id | 典型场景 |
+|------|------------|----------|
+| MM | `12eda67a4ffb11f19cb713ede57b176f` | 物料、库存、采购、MRP、BOM、仓库、批次 |
+| CO | `02841d1e4ffb11f19cb713ede57b176f` | 成本、费用、预算、核算、CO-PA、成本中心 |
+
+## 模块选择规则
+
+1. 优先看 **proposal/spec 中的 Capability 名称与描述**
+2. 再看 **用户输入中的业务名词**
+3. 再看 **代码路径/包名**（如含 `mm`、`co`、`material`、`cost`）
+4. 若 MM 与 CO 都相关，可分别查询两个模块后合并为建议
+5. 若无法判断模块，**跳过查询**，不要阻塞 SDD 主流程
+
+## 查询时机
+
+**适合查询：**
+- 业务名词含义不明（如“物料凭证”“成本中心”“评估类”）
+- 内部术语可能有多种解释
+- 需要补充领域背景以写 propose/spec/design
+
+**不必查询：**
+- 通用技术概念（HTTP、JWT、Redis）
+- proposal/spec/design 已明确定义
+- 用户已给出权威定义

package/templates/skills/kld-sdd/opsx-knowledge/scripts/config.json

@@ -0,0 +1,39 @@
+{
+  "baseUrl": "http://10.29.219.26:9380",
+  "apiKey": "ragflow-6xxy9RUUtRiE9N6gzpTLfQbY00tnGGKWsEuBR53zp0U",
+  "timeoutMs": 8000,
+  "modules": {
+    "mm": {
+      "datasetId": "12eda67a4ffb11f19cb713ede57b176f",
+      "label": "MM模块",
+      "keywords": [
+        "MM",
+        "物料",
+        "库存",
+        "采购",
+        "MRP",
+        "BOM",
+        "仓库",
+        "入库",
+        "出库",
+        "批次",
+        "Material"
+      ]
+    },
+    "co": {
+      "datasetId": "02841d1e4ffb11f19cb713ede57b176f",
+      "label": "CO模块",
+      "keywords": [
+        "CO",
+        "成本",
+        "费用",
+        "预算",
+        "核算",
+        "CO-PA",
+        "利润中心",
+        "成本中心",
+        "Controlling"
+      ]
+    }
+  }
+}

package/templates/skills/kld-sdd/opsx-knowledge/scripts/retrieve.cjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+/**
+ * RAGFlow 知识库检索 CLI（SDD opsx-knowledge 专用）
+ *
+ * 用法:
+ *   node scripts/retrieve.cjs --question="什么是物料凭证" --module=mm
+ *   node scripts/retrieve.cjs --question="成本中心是什么" --module=co
+ *   node scripts/retrieve.cjs --question="..." --module=auto
+ *
+ * 失败时 exit 0 并返回 ok:false，不阻断 SDD 主流程。
+ */
+
+const fs = require('fs');
+const http = require('http');
+const path = require('path');
+const { URL } = require('url');
+
+const CONFIG_PATH = path.join(__dirname, 'config.json');
+
+function readConfig() {
+  return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (const item of argv.slice(2)) {
+    if (!item.startsWith('--')) continue;
+    const eq = item.indexOf('=');
+    if (eq === -1) {
+      args[item.slice(2)] = true;
+    } else {
+      args[item.slice(2, eq)] = item.slice(eq + 1);
+    }
+  }
+  return args;
+}
+
+function scoreModule(question, moduleConfig) {
+  const text = String(question || '').toLowerCase();
+  let score = 0;
+  for (const keyword of moduleConfig.keywords || []) {
+    if (text.includes(String(keyword).toLowerCase())) {
+      score += 1;
+    }
+  }
+  return score;
+}
+
+function resolveModules(question, moduleArg, config) {
+  const modules = config.modules || {};
+  if (moduleArg && moduleArg !== 'auto' && modules[moduleArg]) {
+    return [moduleArg];
+  }
+
+  const ranked = Object.entries(modules)
+    .map(([key, value]) => ({ key, score: scoreModule(question, value) }))
+    .filter(item => item.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  if (ranked.length === 0) {
+    return [];
+  }
+
+  const topScore = ranked[0].score;
+  return ranked.filter(item => item.score === topScore).map(item => item.key);
+}
+
+function postRetrieval(config, question, datasetIds) {
+  return new Promise((resolve, reject) => {
+    const endpoint = new URL('/api/v1/retrieval', config.baseUrl);
+    const payload = JSON.stringify({
+      question,
+      dataset_ids: datasetIds
+    });
+
+    const req = http.request(
+      {
+        hostname: endpoint.hostname,
+        port: endpoint.port || 80,
+        path: endpoint.pathname,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+          Authorization: `Bearer ${config.apiKey}`
+        },
+        timeout: config.timeoutMs || 8000
+      },
+      res => {
+        let body = '';
+        res.on('data', chunk => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            reject(new Error(`HTTP ${res.statusCode}: ${body.slice(0, 500)}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(body));
+          } catch (error) {
+            reject(new Error(`Invalid JSON response: ${error.message}`));
+          }
+        });
+      }
+    );
+
+    req.on('timeout', () => {
+      req.destroy(new Error(`Request timeout after ${config.timeoutMs || 8000}ms`));
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+function normalizeChunks(response) {
+  const chunks = response?.data?.chunks || response?.chunks || [];
+  return chunks.map((chunk, index) => ({
+    index: index + 1,
+    content: chunk.content || chunk.text || '',
+    document_name: chunk.document_name || chunk.doc_name || chunk.document_id || '',
+    similarity: chunk.similarity ?? chunk.score ?? null
+  }));
+}
+
+function failOutput(error, extra = {}) {
+  return {
+    ok: false,
+    advisory: true,
+    error: String(error?.message || error),
+    chunks: [],
+    ...extra
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const question = String(args.question || '').trim();
+  const moduleArg = String(args.module || 'auto').trim().toLowerCase();
+
+  if (!question) {
+    console.log(JSON.stringify(failOutput(new Error('Missing required --question=')), null, 2));
+    process.exit(0);
+    return;
+  }
+
+  let config;
+  try {
+    config = readConfig();
+  } catch (error) {
+    console.log(JSON.stringify(failOutput(error)), null, 2);
+    process.exit(0);
+    return;
+  }
+
+  const selectedModules = resolveModules(question, moduleArg, config);
+  if (selectedModules.length === 0) {
+    console.log(JSON.stringify({
+      ok: false,
+      advisory: true,
+      skipped: true,
+      reason: 'No matching module for question; specify --module=mm or --module=co',
+      question,
+      chunks: []
+    }, null, 2));
+    process.exit(0);
+    return;
+  }
+
+  const datasetIds = selectedModules.map(key => config.modules[key].datasetId);
+  const moduleLabels = selectedModules.map(key => config.modules[key].label);
+
+  try {
+    const response = await postRetrieval(config, question, datasetIds);
+    const chunks = normalizeChunks(response);
+    console.log(JSON.stringify({
+      ok: true,
+      advisory: true,
+      question,
+      modules: selectedModules,
+      module_labels: moduleLabels,
+      dataset_ids: datasetIds,
+      chunk_count: chunks.length,
+      chunks
+    }, null, 2));
+    process.exit(0);
+  } catch (error) {
+    console.log(JSON.stringify(failOutput(error, {
+      question,
+      modules: selectedModules,
+      module_labels: moduleLabels,
+      dataset_ids: datasetIds
+    }), null, 2));
+    process.exit(0);
+  }
+}
+
+main();

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

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

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

@@ -98,6 +98,10 @@ openspec list
 | 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
 | API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
 
+**【可选】业务知识库检索**：
+术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）。
+知识库结果仅供参考，spec 契约以用户确认和 proposal 为准；失败时不阻塞。
+
 ### 4. 【关键步骤】读取本地模板文件
 
 **必须先读取** `openspec-templates/spec.md` 作为文档结构模板：