@hunterzheng/kld-sdd 2.4.19

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

@@ -0,0 +1,44 @@
+---
+description: opsx-design 的详细模板：telemetry 命令、上下文类型表、渐进式加载层级图。仅在需要参考详细模板时读取。
+---
+
+# opsx-design — 详细参考（reference）
+
+> 本文件承载 opsx-design 的重细节模板：telemetry 命令、§2 上下文类型表、§3 渐进式上下文加载层级图。
+> SKILL.md 保留入口骨架与指针；本文件为详细模板来源。
+
+---
+
+## 📊 Telemetry 命令模板（必做，不得跳过）
+
+> 阶段开始：`node skywalk-sdd/log.cjs start --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=design --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## §2 上下文类型与用途
+
+| 上下文类型 | 用途 | 如何融入 design |
+|------------|------|----------------|
+| 代码文件 | 分析现有实现、依赖关系 | 确定代码锚点、修改策略 |
+| 架构文档 | 了解系统边界、模块关系 | 对齐总体设计方向 |
+| 数据库 Schema | 了解数据模型约束 | 纳入数据设计章节 |
+
+---
+
+## §3 渐进式上下文加载层级图
+
+**⛔ 必须严格按以下顺序加载：**
+
+```
+第 1 层：全局基线
+  → openspec/specs/overview.md
+
+第 2 层：宏观背景
+  → changes/<name>/proposal.md
+
+第 3 层：精准打击（仅当前 Capability）
+  → changes/<name>/specs/<capability>/spec.md
+
+⛔ 隔离红线：禁止读取其他 Capability 的文档！
+```

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

@@ -0,0 +1,104 @@
+---
+name: opsx-explore
+description: "浏览变更技能 - 查看所有变更状态和 SDD 文档完整性概览"
+argument-hint: "[change-name]"
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: sdd-team
+  version: "3.0"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+---
+
+你是一个 SDD（Specification-Driven Development）变更浏览专家。激活本技能后，你将展示项目中所有变更的状态概览，并引导用户执行下一步操作。
+
+
+> **🖥️ 跨平台执行规则**
+> - 先确认当前终端工作目录是项目根目录；若不是，先 `cd` 到项目根目录。
+> - Telemetry 命令默认使用 `--project=.`，兼容 Windows、macOS、Linux。
+> - 在 Windows Bash / Git Bash / Claude Bash 中，禁止裸写 Windows 反斜杠绝对路径（如 `D:\project\demo`）；如必须使用绝对路径，请写成正斜杠路径或加引号。
+> - 不要省略 `--source=opsx-command` 与 `--session-id=<会话ID>`。
+> **📊 Telemetry（必做，不得跳过）**
+> - 阶段开始：`node skywalk-sdd/log.cjs start --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID>`（保存 event_id）
+> - 阶段结束：`node skywalk-sdd/log.cjs end --event-id=<event_id> --command=explore --project=. --change=<变更名称> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --result=success|failure --summary="摘要"`
+
+---
+
+## 技能定位
+
+| 维度 | 内容 |
+|------|------|
+| 核心问题 | 项目中所有变更的进度如何 |
+| 关键输出 | 变更概览表（文档完整性 + 状态 + 建议操作） |
+| 操作类型 | 只读浏览，不修改任何文件 |
+
+---
+
+## 启动流程
+
+### 1. 获取所有变更列表
+
+```bash
+openspec list
+```
+
+若没有任何变更，提示：
+> "当前项目还没有任何变更。运行 `/opsx-propose <变更描述>` 开始第一个变更。"
+
+### 2. 检查每个变更的 SDD 文档完整性
+
+对每个变更，检查以下文件是否存在：
+- `openspec/changes/<name>/proposal.md`（P）
+- `openspec/changes/<name>/specs/<capability>/spec.md`（S）
+- `openspec/changes/<name>/specs/<capability>/design.md`（D）
+- `openspec/changes/<name>/specs/<capability>/tasks.md`（T）
+
+同时获取每个变更状态：
+```bash
+openspec status --change "<name>" --json
+```
+
+### 3. 展示变更概览表
+
+> "📋 **项目变更概览**（P=提案 S=规格 D=设计 T=任务）：
+>
+> | 变更名称 | P | S | D | T | openspec状态 | 建议下一步 |
+> |---------|---|---|---|---|------------|---------|
+> | add-user-auth | ✅ | ✅ | ✅ | ❌ | PENDING | `/opsx-task add-user-auth` |
+> | payment-refund | ✅ | ❌ | ❌ | ❌ | PENDING | `/opsx-spec payment-refund` |
+> | points-exchange | ✅ | ✅ | ✅ | ✅ | IMPLEMENTING | `/opsx-check points-exchange` |"
+
+### 4. 【交互引导】选择操作
+
+使用 **AskUserQuestion** 让用户选择：
+> "请选择操作：
+> - A. 查看变更详情：输入变更名称
+> - B. 创建新变更：运行 `/opsx-propose`
+> - C. 执行质量检查：运行 `/opsx-check <name>`
+> - D. 申请实施：运行 `/opsx-apply <name>`
+> - E. 退出浏览"
+
+### 5. 若用户选择查看详情
+
+展示选定变更的详细信息：
+```bash
+openspec status --change "<name>" --json
+```
+
+展示：
+- 变更描述和创建时间
+- 各文档状态（存在/缺失/文件大小）
+- openspec 内部状态（`applyRequires` 列表）
+- 建议下一步操作和对应命令
+
+---
+
+## Guardrails
+
+- explore 是**只读操作**，不修改任何文件
+- 发现文档缺失时，推荐对应命令但不自动执行
+- 若某变更 applyRequires 中有未完成项，在概览表中以 ⚠️ 标注

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

@@ -0,0 +1,130 @@
+---
+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. 调用检索脚本
+
+在项目根目录执行（使用 skill 目录变量，与 gitnexus 子 skill 脚本引用方式一致）：
+
+```bash
+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 关键词自动匹配（默认）
+
+### 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();