@jspg-ai/coding-bb 0.0.1

package/cbb/lib/wiki/mermaid-guard.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+/**
+ * Mermaid 语法守卫 — 在发布到 Confluence Wiki 前自动修复已知兼容性问题。
+ *
+ * Confluence 的 mermaid-macro 插件不支持 flowchart 关键字（仅支持 graph），
+ * 也不支持 stateDiagram-v2 版本号后缀。classDiagram 的继承箭头 <|-- 中的 <
+ * 会被 Confluence 编码为 &lt; 导致渲染失败，需反转箭头方向。
+ * 同样不支持 :::内联样式、<|.. 反向虚线继承、classDef 样式定义等语法。
+ */
+
+/**
+ * 对 mermaid 代码应用语法守卫转换
+ * @param {string} content - mermaid 代码块内容
+ * @returns {{ fixed: string, warnings: string[] }}
+ */
+function applyMermaidGuard(content) {
+  const warnings = [];
+  let fixed = content;
+
+  // 1. flowchart → graph（Confluence 不支持 flowchart 关键字）
+  if (/^\s*flowchart\b/m.test(fixed)) {
+    fixed = fixed.replace(/^\s*flowchart\b/gm, 'graph');
+    warnings.push('flowchart → graph');
+  }
+
+  // 2. stateDiagram-v2 → stateDiagram（去除版本号后缀）
+  if (/^\s*stateDiagram-v2\b/m.test(fixed)) {
+    fixed = fixed.replace(/^\s*stateDiagram-v2\b/gm, 'stateDiagram');
+    warnings.push('stateDiagram-v2 → stateDiagram');
+  }
+
+  // 2b. classDiagram-v2 → classDiagram（去除版本号后缀）
+  if (/^\s*classDiagram-v2\b/m.test(fixed)) {
+    fixed = fixed.replace(/^\s*classDiagram-v2\b/gm, 'classDiagram');
+    warnings.push('classDiagram-v2 → classDiagram');
+  }
+
+  // 3. classDiagram 箭头方向修正: A <|-- B → B --|> A
+  //    Confluence 会将 < 编码为 &lt;，导致渲染失败
+  if (/^\s*classDiagram\b/m.test(fixed)) {
+    const inheritancePattern = /^(\s*)(\w+)\s+<\|--\s+(\w+)/gm;
+    if (inheritancePattern.test(fixed)) {
+      inheritancePattern.lastIndex = 0;
+      fixed = fixed.replace(inheritancePattern, '$1$3 --|> $2');
+      warnings.push('classDiagram inheritance fix: <|-- → --|>');
+    }
+
+    // 3b. 反向虚线继承: A <|.. B → B ..|> A
+    const dottedInheritance = /^(\s*)([\w.]+)\s+<\|\.\.\s+([\w.]+)/gm;
+    if (dottedInheritance.test(fixed)) {
+      dottedInheritance.lastIndex = 0;
+      fixed = fixed.replace(dottedInheritance, '$1$3 ..|> $2');
+      warnings.push('classDiagram dotted inheritance fix: <|.. → ..|>');
+    }
+
+    // 3c. classDef 和 class Xxx styleName 在 Confluence classDiagram 中不支持，移除
+    const classDefPattern = /^\s*classDef\b.*$/gm;
+    if (classDefPattern.test(fixed)) {
+      classDefPattern.lastIndex = 0;
+      fixed = fixed.replace(classDefPattern, '');
+      warnings.push('classDiagram: removed unsupported classDef');
+    }
+
+    // class Xxx styleName（仅匹配引用已定义样式的行，非方法/属性定义）
+    const classStyleRef = /^\s*class\s+(\w+)\s+(\w+)\s*$/gm;
+    if (classStyleRef.test(fixed)) {
+      classStyleRef.lastIndex = 0;
+      fixed = fixed.replace(classStyleRef, '');
+      warnings.push('classDiagram: removed unsupported class style reference');
+    }
+  }
+
+  // 4. :::内联样式 → 提取为 class 语句（Confluence 不支持 :::）
+  const inlineStylePattern = /(\w[\w\[\]"'.]*?):::(\w+)/g;
+  const styleAssignments = [];
+  let styleMatch;
+  while ((styleMatch = inlineStylePattern.exec(fixed)) !== null) {
+    const fullRef = styleMatch[1].trim();
+    const styleClass = styleMatch[2];
+    // 提取节点 ID（去掉 [Label] 部分）
+    const nodeId = fullRef.replace(/\[.*$/, '').trim();
+    if (nodeId && styleClass) {
+      styleAssignments.push(`  class ${nodeId} ${styleClass}`);
+    }
+  }
+  if (styleAssignments.length > 0) {
+    // 移除 ::: 内联样式
+    fixed = fixed.replace(/(\w[\w\[\]"'.]*?):::(\w+)/g, '$1');
+    // 在末尾追加 class 语句
+    fixed = fixed.trimEnd() + '\n' + styleAssignments.join('\n');
+    warnings.push(':::inline style → class statements');
+  }
+
+  // 5. ~GenericType~ 泛型标注 — Confluence 可能不兼容，保留但警告
+  if (/~\w+~/.test(fixed)) {
+    warnings.push('~GenericType~ detected, may not render in Confluence');
+  }
+
+  return { fixed, warnings };
+}
+
+module.exports = { applyMermaidGuard };

package/cbb/lib/wiki/split.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+/**
+ * 内容拆分 — 当 design.md 转换后的 XHTML 超过阈值时，按章节切分为多个子页面，
+ * 主页面保留概述 + 章节导航 TOC。
+ *
+ * 拆分策略（自动降级）：
+ *   1. 先按 # 一级标题切；若切出多于 1 段且每段 XHTML 均 ≤ 阈值 → 用 h1 段
+ *   2. 否则按 ## 二级标题切（design.md 常为单 h1，实际多走此路）
+ *
+ * 概述 = 文档开头到第一个切分标题之前的全部内容（含 # 标题、背景说明等）。
+ * 章节标题 = 该级标题文本；子页面标题 = "<主页面标题> - <章节标题>"。
+ * 导航用 Confluence <ac:link><ri:page ri:content-title="..."/> 按标题引用，
+ * 子页面建好后链接自动生效，无需 pageId 回填。
+ */
+
+const { markdownToXhtml } = require('./convert');
+
+const DEFAULT_THRESHOLD = 200 * 1024; // 200KB
+
+function escapeXml(str) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function escapeCdata(str) {
+  return str.replace(/]]>/g, ']]]]><![CDATA[>');
+}
+
+/**
+ * 按指定层级标题切分 markdown
+ * @param {string} markdown
+ * @param {number} level - 1=#, 2=##
+ * @returns {{overview: string, sections: {title: string, content: string}[]}}
+ *   overview = 开头到第一个该级标题前
+ *   sections = 每个该级标题及其内容（到下一个同级标题前）
+ */
+function splitByHeading(markdown, level) {
+  const prefix = '#'.repeat(level);
+  const re = new RegExp(`^${prefix} (.+)$`, 'gm');
+  const matches = [];
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    matches.push({ title: m[1].trim(), start: m.index, lineEnd: m.index + m[0].length });
+  }
+
+  if (matches.length === 0) {
+    return { overview: markdown, sections: [] };
+  }
+
+  const overview = markdown.slice(0, matches[0].start).trim();
+  const sections = matches.map((mt, i) => {
+    const content = markdown.slice(mt.start, i + 1 < matches.length ? matches[i + 1].start : markdown.length);
+    return { title: mt.title, content: content.trim() };
+  });
+
+  return { overview, sections };
+}
+
+/**
+ * 判断是否需要拆分（基于转换后的 XHTML 长度）
+ * @param {string} xhtml
+ * @param {number} [threshold]
+ */
+function shouldSplit(xhtml, threshold = DEFAULT_THRESHOLD) {
+  return xhtml.length > threshold;
+}
+
+/**
+ * 切分 markdown 为概述 + 章节列表，并预转换各段 XHTML（避免发布时重复转换）
+ * @param {string} markdown
+ * @param {number} [threshold]
+ * @returns {{overview: {markdown: string, xhtml: string}, sections: {title: string, markdown: string, xhtml: string}[], level: number}}
+ */
+function splitMarkdown(markdown, threshold = DEFAULT_THRESHOLD) {
+  // 先尝试 h1
+  let { overview, sections } = splitByHeading(markdown, 1);
+  let level = 1;
+
+  const h1Usable = sections.length > 1 && sections.every(s => markdownToXhtml(s.content).length <= threshold);
+
+  if (!h1Usable) {
+    // 降级 h2
+    const h2 = splitByHeading(markdown, 2);
+    if (h2.sections.length > 1) {
+      overview = h2.overview;
+      sections = h2.sections;
+      level = 2;
+    }
+    // 若 h2 也切不出多段，保持 h1 结果（sections 可能为空或 1 段），调用方按不拆处理
+  }
+
+  return {
+    overview: { markdown: overview, xhtml: markdownToXhtml(overview) },
+    sections: sections.map(s => ({ title: s.title, markdown: s.content, xhtml: markdownToXhtml(s.content) })),
+    level,
+  };
+}
+
+/**
+ * 判断拆分结果是否实际可用（至少切出 1 个章节）
+ */
+function isSplittable(split) {
+  return split.sections.length > 0;
+}
+
+/**
+ * 构建主页面章节导航 TOC（XHTML）
+ * @param {string} mainTitle - 主页面标题，用于拼子页面标题
+ * @param {{title: string}[]} sections
+ * @returns {string}
+ */
+function buildNavXhtml(mainTitle, sections) {
+  const items = sections.map(s => {
+    const subTitle = `${mainTitle} - ${s.title}`;
+    return `<li><ac:link><ri:page ri:content-title="${escapeXml(subTitle)}"/><ac:plain-text-link-body><![CDATA[${escapeCdata(s.title)}]]></ac:plain-text-link-body></ac:link></li>`;
+  }).join('');
+
+  return `<h2>章节导航</h2><ul>${items}</ul>`;
+}
+
+module.exports = {
+  DEFAULT_THRESHOLD,
+  shouldSplit,
+  splitMarkdown,
+  isSplittable,
+  buildNavXhtml,
+};

package/cbb/tools/cbb-decompile-jar/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: cbb-decompile-jar
+description: "JAR 包反编译工具。从本地 Maven 仓库的实际依赖 JAR 中提取类定义（Facade 方法签名、DTO 字段、枚举值），确保看到的是项目真正依赖的版本。触发场景：调用 RPC 接口但不确定入参出参结构、查看依赖库的接口/DTO/枚举定义、确认依赖实际版本的类签名、查看 .class 文件。需要 JDK + Python 3 + 本地 Maven 仓库。仅限 Java 后端场景。"
+---
+
+# JAR 包反编译工具
+
+从 Maven 本地仓库的实际依赖 JAR 中提取类定义，确保看到的是项目真正依赖的版本，而非本地可能过时的源码。
+
+---
+
+## 一、触发场景
+
+以下场景**必须使用此 skill**，而不是猜测或读取本地源码：
+
+| 场景 | 说明 |
+|------|------|
+| 调用 RPC 接口 | 不确定 Facade 方法的入参出参，需要查看接口定义 |
+| 使用第三方 DTO | 需要确认 Request/Response 类的字段列表和类型 |
+| 查看枚举值 | 需要知道枚举类的所有可选值及其 code |
+| 版本确认 | 本地源码可能不是实际依赖版本，需要从 JAR 确认 |
+| 代码迁移 | 需要参考原项目的类结构 |
+
+---
+
+## 二、核心工具
+
+脚本：`<skill-dir>/scripts/decompile.py`（Python，全平台通用）
+
+**前置要求**：需要安装 Python 3（`python3` 或 `python` 命令可用）。如未安装：
+- Windows：从 [python.org](https://www.python.org/downloads/) 下载安装，安装时勾选 "Add Python to PATH"
+- Mac：`brew install python3` 或从 python.org 下载
+- Linux：`sudo apt install python3` / `sudo yum install python3`
+
+### 命令说明
+
+```bash
+SCRIPT="<skill-dir>/scripts/decompile.py"
+
+# 环境与定位
+python $SCRIPT check                            # 环境预检（JDK + Maven + 仓库）
+python $SCRIPT repo                             # 输出本地 Maven 仓库路径
+python $SCRIPT resolve <FQN> [-p projectDir]    # 类全限定名 → JAR 路径 + Maven 坐标
+python $SCRIPT find <G> <A> <V>                 # Maven 坐标 → JAR 路径
+
+# 反编译
+python $SCRIPT list <jarPath> [keyword]                     # 列出 JAR 中的类（可按关键字过滤）
+python $SCRIPT show <jarPath[;jarPath2;...]> <FQN> [-v]     # 查看类的完整信息（-v 输出 verbose 字节码）
+python $SCRIPT api  <jarPath[;jarPath2;...]> <FQN>          # 查看接口方法签名（支持多 JAR）
+python $SCRIPT enum <jarPath[;jarPath2;...]> <FQN>          # 查看枚举类的所有值及 code（支持多 JAR）
+python $SCRIPT batch <jarPath[;jarPath2;...]> <FQN1> <FQN2> ...  # 批量查看多个类（单次调用）
+```
+
+> **多 JAR classpath**：`show`/`api`/`enum` 的第一个参数支持多个 JAR 路径，用系统路径分隔符（Windows 用 `;`，Mac/Linux 用 `:`）或 `,` 分隔。当一个类引用了其他 JAR 中的类型时，需要将相关 JAR 都加入 classpath，否则 javap 会报 class not found。
+>
+> 示例：`python $SCRIPT show "D:\repo\a.jar;D:\repo\b.jar" com.example.MyClass`
+
+---
+
+## 三、标准分析流程
+
+### Step 1：环境预检
+
+**每次使用前必须先执行**：
+
+```bash
+python $SCRIPT check
+```
+
+如果任何组件缺失，**立即停止并提示用户**：
+- JDK 缺失 → "请提供 JDK 安装路径（如 D:\env\jdk\corretto-1.8），或设置 JAVA_HOME 环境变量"
+- Maven 缺失 → "请提供 Maven 安装路径，或设置 MAVEN_HOME 环境变量"
+
+### Step 2：锁定目标类
+
+**若用户提供的是类的全限定名或 Maven 坐标**，直接使用，跳到 Step 3。
+
+**若用户描述的是业务功能（如"查询企业已签署的合同"）而非类名**，需要先在项目代码中搜索定位：
+
+1. 在项目中用关键词搜索相关 Java 文件（如 `grep -rli "contract" --include="*.java" .`）
+2. 找到调用方代码后，从 import 语句中提取外部依赖的全限定类名（FQN）
+3. 确认目标：提取出 Facade 接口名、Request/Response 类名
+
+支持的目标格式：
+- 全限定类名 + 方法名：`com.ymm.uc.uic.common.facade.service.AccountCenterService#getAccountInfoByAccountId`
+- 全限定类名：`com.ymm.uc.uic.common.facade.dto.AccountInfoDTO`
+- Maven 坐标：`com.ymm.uc:uic-common-service-facade:2.0.5`
+
+### Step 3：定位 JAR
+
+如果用户提供的是类名（非 Maven 坐标）：
+
+```bash
+python $SCRIPT resolve com.ymm.uc.uic.common.facade.service.AccountCenterService -p D:\workspace\ka\ymm-ka-capacity-app
+```
+
+输出：
+```
+JAR: D:\env\maven\repository\com\ymm\uc\uic-common-service-facade\2.0.5\uic-common-service-facade-2.0.5.jar
+Coordinates: com.ymm.uc:uic-common-service-facade:2.0.5
+```
+
+脚本内部自动完成：定位 Maven → 读取 settings.xml → 执行 `mvn dependency:tree` → 多级包名前缀缩窄候选 → `jar tf` 确认。
+
+**resolve 增强逻辑**：
+1. **dependency:tree 容错**：如果 `dependency:tree` 构建失败（POM 异常、snapshot 不可用等），自动跳过，进入本地仓库扫描
+2. **多级前缀扫描**：包名和 Maven groupId 不总一致（如 `com.ymm.common.rpc` vs `com.ymm.common-plugins`），脚本会从最长前缀到最短前缀递减扫描本地仓库目录，确保覆盖
+3. **JAR 自动下载**：当 JAR 在本地仓库不存在时，自动执行 `mvn dependency:get` 从远程仓库下载
+
+如果用户提供的是 Maven 坐标，用 `find` 定位：
+
+```bash
+python $SCRIPT find com.ymm.uc uic-common-service-facade 2.0.5
+```
+
+### Step 4：执行反编译
+
+根据用户需求选择子命令：
+
+```bash
+# 探索 JAR 内容
+python $SCRIPT list $jarPath "Facade"
+
+# 查看 RPC 接口方法签名
+python $SCRIPT api $jarPath com.ymm.uc.uic.common.facade.service.AccountCenterService
+
+# 查看类完整信息（字段 + 方法）
+python $SCRIPT show $jarPath com.ymm.uc.uic.common.facade.dto.AccountInfoDTO
+
+# 查看类完整信息（含 verbose 字节码，用于分析常量值等）
+python $SCRIPT show $jarPath com.ymm.uc.uic.common.facade.dto.AccountInfoDTO -v
+
+# 查看枚举值（自动提取 code/desc 字段值）
+python $SCRIPT enum $jarPath com.ymm.uc.uic.common.facade.enums.AccountType
+
+# 批量查看多个类（一次 javap 调用，比逐个 show 快 3 倍）
+python $SCRIPT batch $jarPath com.ymm.xx.SomeRequest com.ymm.xx.SomeResponse com.ymm.xx.SomeDTO
+```
+
+**跨 JAR 类引用处理**：当一个类引用了其他 JAR 中的类型（如 `YmmResult` 不在 Facade 所在的 JAR），`show`/`api` 会报 class not found 并给出提示。此时需要：
+
+1. 用 `resolve` 找到该引用类所在的 JAR
+2. 将多个 JAR 路径拼接后传给 `show`/`api`：
+
+   ```bash
+   # 先 resolve 找到 YmmResult 所在 JAR
+   python $SCRIPT resolve com.ymm.common.rpc.YmmResult -p D:\workspace\ka\ymm-ka-capacity-app
+   # 输出: JAR: D:\repo\ymm-common-rpc-1.0.jar
+
+   # 多 JAR classpath 查看（Windows 用 ; 分隔，Mac/Linux 用 : 分隔）
+   python $SCRIPT show "D:\repo\ymm-ka-capacity-api-1.2.26.jar;D:\repo\ymm-common-rpc-1.0.jar" com.ymm.ka.capacity.core.api.facade.freight.FreightDiffFacade
+   ```
+
+### Step 5：级联查看
+
+看到方法签名后，**必须继续查看** Request/Response 的字段，以及字段引用的枚举类型。
+
+级联查看时，注意：
+- **记录已发现的 JAR 路径**：每次 `resolve` 获取的 JAR 路径应积累起来，后续 `show`/`api`/`enum` 时作为多 JAR classpath 传入，避免重复报 class not found
+- **优先用已有的 JAR 组合**：如果新类可能在已发现的 JAR 中，先尝试多 JAR classpath，不行再 resolve
+- **典型流程**：`api` 看 Facade → 累积 JAR → `show` 看 Request/Response（带已累积的 JAR）→ `show`/`enum` 看引用类型（带已累积的 JAR）→ 如仍报错再 `resolve` 新 JAR → 继续累积
+
+以结构化格式呈现：
+
+```java
+// === Facade 接口 ===
+// 来源：xxx-api-2.3.1.jar
+
+public interface SomeFacade {
+    // 方法签名
+    Result<SomeDTO> doSomething(SomeRequest request);
+}
+
+// === Request 类 ===
+public class SomeRequest {
+    private Long orderId;        // 订单ID
+    private Integer orderType;   // 订单类型（枚举 OrderTypeEnum）
+    private String remark;       // 备注
+}
+
+// === Response/DTO 类 ===
+public class SomeDTO {
+    private Long id;
+    private String name;
+    private Integer status;      // 状态（枚举 StatusEnum）
+}
+
+// === 枚举 ===
+// OrderTypeEnum: ORDER_NORMAL(code="normal", desc="普通订单")
+// StatusEnum: INIT(code="0", desc="初始化"), DONE(code="2", desc="完成")
+```
+
+---
+
+## 四、错误处理
+
+| 错误场景 | 原因 | 处理方式 |
+|----------|------|----------|
+| Python not found | 未安装 Python 3 或未加入 PATH | 安装 Python 3 并确保 `python` 或 `python3` 命令可用 |
+| JDK not found | JAVA_HOME 未设置、PATH 中无 javap、已知路径未找到 | 提示用户设置 JAVA_HOME 或提供 JDK 路径 |
+| Maven not found | MAVEN_HOME 未设置、PATH 中无 mvn、已知路径未找到 | 提示用户设置 MAVEN_HOME 或提供 Maven 路径 |
+| JAR not found at path | 依赖未下载到本地仓库 | 自动执行 `mvn dependency:get` 下载，下载失败才报错 |
+| Class not found in any JAR | 类不在项目依赖中 | 检查 pom.xml 是否声明了对应依赖 |
+| javap 报 class not found | 目标类引用了其他 JAR 中的类型 | 1. 用 `resolve` 定位引用类所在的 JAR；2. 用多 JAR classpath 重新执行 `show`/`api`/`enum` |
+| javap 报 class not found | 类名错误或内部类 | 内部类用 `$` 分隔，先用 `list` 确认类名 |
+| dependency:tree 构建失败 | POM 异常、snapshot 不可用等 | 自动跳过，进入本地仓库多级前缀扫描 |
+| 包名与 groupId 不一致 | Java 包名和 Maven groupId 不同 | 多级前缀递减扫描，从最长到最短覆盖更多目录 |
+| settings.xml 无 localRepository | 未自定义仓库路径 | 自动兜底到 `~/.m2/repository` |
+
+---
+
+## 五、注意事项
+
+1. **必须从 JAR 获取**：不要读取本地源码代替，本地代码可能和实际依赖版本不一致
+2. **级联查看**：看到方法签名后，继续查看 Request/Response 的字段，以及字段引用的枚举类型
+3. **敏感字段**：身份证号、手机号、银行卡号等敏感字段需标注提醒，日志中禁止明文输出
+4. **性能优化**：
+   - `resolve` 结果会缓存到项目目录下的 `.decompile-cache.json`，第二次起直接命中（<0.2s）
+   - 需要查看多个类时，优先使用 `batch` 命令一次性查看，比逐个 `show` 快约 3 倍
+   - `dependency:tree` 有 15 秒超时保护，超时自动 fallback 到本地仓库扫描