kld-sdd 2.4.9 → 2.4.11

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

@@ -34,8 +34,8 @@ allowed-tools:
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.js start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node skywalk-sdd/log.cjs start --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=propose --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 
@@ -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

@@ -34,8 +34,8 @@ allowed-tools:
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.js start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node skywalk-sdd/log.cjs start --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=spec --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 
@@ -98,6 +98,10 @@ openspec list
 | 代码文件 | 了解现有实现约束 | 纳入技术契约和约束条件 |
 | API 文档 | 接口规范参考 | 对齐数据契约和接口格式 |
 
+**【可选】业务知识库检索**：
+术语含义不清且可能影响 spec 准确性时，可调用 **opsx-knowledge** skill（`<SkillsBundlePath>/opsx-knowledge/`）。
+知识库结果仅供参考，spec 契约以用户确认和 proposal 为准；失败时不阻塞。
+
 ### 4. 【关键步骤】读取本地模板文件
 
 **必须先读取** `openspec-templates/spec.md` 作为文档结构模板：

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

@@ -41,8 +41,8 @@ allowed-tools:
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.js start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node skywalk-sdd/log.cjs start --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=task --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---
 

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

@@ -29,8 +29,8 @@ allowed-tools:
 > - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
 > - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
 > **📊 Telemetry（必做，不得跳过）**
-> - 阶段开始：`node skywalk-sdd/log.js start --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
-> - 阶段结束：`node skywalk-sdd/log.js end --event-id=<event_id> --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+> - 阶段开始：`node skywalk-sdd/log.cjs start --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=test --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
 
 ---