@jspg-ai/coding-bb 0.0.1

package/cbb/tools/cbb-design-to-wiki/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: cbb-design-to-wiki
+description: 将 OpenSpec design.md（含 mermaid/plantuml 图表）发布到Wiki。触发场景：用户说"发布 design 到 wiki"、"把方案发到 wiki"、"publish to wiki"，或 OpenSpec change archive 后需要发布设计文档，或任何需要把 Markdown 写入 wiki.amh-group.com 的场景。统一 Wiki 发布入口，失败时中断并提示原因。
+---
+
+# 发布 Design.md 到Wiki
+
+## 工作流程
+
+> **严格执行规则**：每一步完成后才能进入下一步，禁止合并或跳过步骤。每步结束时向用户报告结果并等待确认（或自动进入下一步）。
+
+### 第一步：环境检查
+
+**1.1 检查 cbb 安装**
+
+```bash
+cbb --help
+```
+
+不可用则执行 `npx @jspg-ai/coding-bb init`，版本过旧则 `npm install -g @jspg-ai/coding-bb`。
+
+**1.2 检查 Wiki 认证凭据**
+
+检查环境变量 `CBB_WIKI_EMAIL` + `CBB_WIKI_TOKEN` 或配置文件 `~/.cbb/wiki-config.json` 是否存在。
+
+**凭据未配置时，中断并提示：**
+
+> "Wiki 认证凭据未配置，请选择一种方式：
+> 1. 设置环境变量：`$env:CBB_WIKI_EMAIL = '你的邮箱'` 和 `$env:CBB_WIKI_TOKEN = '你的令牌'`
+> 2. 创建 `~/.cbb/wiki-config.json`，写入 `{\"email\":\"你的邮箱\",\"token\":\"令牌\"}`
+>
+> 令牌获取：https://wiki.amh-group.com/plugins/tokens/view.action
+> 配置完成后回复'继续'。"
+
+**凭据检查通过后，报告结果并进入第二步。**
+
+### 第二步：确定要发布的 design.md
+
+**2.1 指令中已传入 change 名**
+
+直接定位文件：`openspec/changes/<change-name>/design.md`，验证文件存在且非空后，报告选中的 change 并进入第三步。
+
+**2.2 指令中未传入 change 名**
+
+仅检测**当前目录**下的 `openspec/changes/` 目录，筛选出包含 `design.md` 且未被归档的 change：
+
+- **只有 1 个** → 自动选中，报告结果并进入第三步
+- **有多个** → 列出所有未归档 change 名称，让用户选择（只能选一个），报告选中结果并进入第三步
+- **没有** → 报错提示："当前目录下未找到任何未归档的 change（含 design.md）"，中断流程
+
+### 第三步：确认 Wiki 目标
+
+根据指令中是否已提供 Wiki 目标信息，按以下优先级处理：
+
+1. **已提供 pageId（数字）或 Wiki 页面链接** → 更新该已有页面，进入第四步
+2. **已提供父页面 ID/链接 + 标题** → 创建新页面，进入第四步
+3. **均未提供** → 向用户明确询问：
+
+> "请确认 Wiki 发布目标：
+> 1. **更新已有页面** — 请提供 pageId（数字，如 `123456`）或页面链接（如 `https://wiki.amh-group.com/pages/viewpage.action?pageId=123456`）
+> 2. **创建新页面** — 请提供父页面的 pageId/链接，以及新页面标题"
+
+等待用户回复后进入第四步。如用户提供的是 Wiki 链接，从中提取 `pageId` 参数后使用。
+
+### 第四步：发布
+
+**先查 CLI 帮助**（不熟悉时必看，命令清单与最新选项以 help 为准）：
+
+```bash
+cbb wp --help       # 发布命令帮助
+cbb wiki --help     # 查询/管理子命令帮助
+```
+
+**参数格式约定**（两种写法等价，混用不报错）：
+
+- GNU 风格（推荐）：`--flag <value>`，例如 `--page-id 123456`
+- 等号风格：`--flag=<value>`，例如 `--page-id=123456`
+- 布尔开关（如 `--dry-run`、`--full`）**不能带值**，写 `--dry-run` 而不是 `--dry-run=true`
+- 文件路径含空格或中文时**必须用引号包住**：`--file "D:\path with space\design.md"`
+- 参数顺序不限，文件名可写在最前（位置参数）也可写 `--file <path>`
+
+**仅使用 `cbb wp` 命令发布，不做自动降级。**
+
+**创建新页面：**
+
+```bash
+# GNU 风格（推荐）
+cbb wp <file> --parent-id <parentPageId> --title "设计方案：<change-name>"
+# 等价写法（等号风格）
+cbb wp --file <file> --parent-id=<parentPageId> --title="设计方案：<change-name>"
+```
+
+**更新已有页面：**
+
+```bash
+cbb wp <file> --page-id <pageId>
+# 等价：cbb wp <file> --page-id=<pageId>
+```
+
+**Dry-run 预览**（不实际发布，仅输出 XHTML）：
+
+```bash
+cbb wp <file> --page-id <pageId> --dry-run
+```
+
+**常见拼错及修正**：
+
+| 用户写法 | 报错 | 修正 |
+|---------|------|------|
+| `cbb wp` 不带参数 | `用法: cbb wp <file> ...` | 加 `<file>` 或 `--file <path>` |
+| `--page-id 123456 --dry-run` 拼成 `--page-id=123456 --dry-run-true` | `未知选项: --dry-run-true` | 改为 `--dry-run`（布尔开关不能带值） |
+| 文件路径含空格未引号包住 | 报"文件不存在"或解析错乱 | 用引号包：`--file "C:\My Docs\design.md"` |
+| 把 `--page-id=123456` 中的 `=` 写成了空格 | 不会报错（两种写法都支持） | — |
+
+**如果发布失败，立即中断并告知用户具体原因：**
+
+| 失败场景 | 提示内容 |
+|----------|---------|
+| 认证失败 (401/403) | "认证失败，请检查邮箱和令牌是否正确。获取令牌：https://wiki.amh-group.com/plugins/tokens/view.action" |
+| 版本冲突 (409) | "页面版本冲突，请重新执行发布命令" |
+| 页面不存在 (404) | "页面不存在，请确认 pageId 是否正确，或使用 --parent-id 创建新页面" |
+| 网络超时 | "网络超时，请检查 VPN/网络连接后重试" |
+| cbb wp 不可用 | "cbb wp 命令不可用，请确认已安装 v1.0.4+ 版本：`cbb --version`" |
+| 参数格式错误 | CLI 已自带提示（含"参数格式为 --flag <value> 或 --flag=<value>"） |
+| 其他错误 | 输出完整错误信息，提示用户排查 |
+
+**发布成功后，报告页面 URL 并进入第五步。**
+
+### 第五步：验证与修复
+
+> **禁止调用 mb-wiki-rest 或其他外部 Wiki 技能。** 使用 `cbb wp --dry-run` 和 `cbb wiki get` 完成验证。
+
+**5.1 Dry-run 检查 XHTML**
+
+```bash
+cbb wp <file> --page-id <pageId> --dry-run | Select-String "mermaid-macro|plantuml|ac:structured-macro"
+```
+
+确认输出中包含正确的 Confluence 宏标签（`<ac:structured-macro>`），而非原始 Markdown 代码块。
+
+**5.2 页面内容验证**
+
+```bash
+cbb wiki get <pageId> --full
+```
+
+确认页面已创建/更新成功，正文内容完整。
+
+**5.3 浏览器验证**
+
+在浏览器中打开 Wiki 页面（URL 格式：`https://wiki.amh-group.com/pages/viewpage.action?pageId=<pageId>`），逐项检查：
+- Mermaid/PlantUML 图表正确渲染（非纯文本）
+- 表格格式正确
+- 代码块格式正确
+- 中文内容无乱码
+
+**5.4 渲染失败修复循环**
+
+如果发现任何渲染问题，执行修复循环：
+
+1. **定位问题**：根据现象判断原因
+   - 图表显示为纯文本 → mermaid/plantuml 宏未正确转换
+   - `@Tool`、`@ConfigurationValue` 等被误解析为用户提及 → Confluence `@` 宏冲突
+   - 表格/代码块格式异常 → XHTML 结构问题
+2. **修复 design.md 源内容**：针对性修改（如 mermaid 语法调整、`@` 转义等）
+3. **重新发布**：回到第四步重新执行 `cbb wp`
+4. **重新验证**：回到 5.3 再次检查
+
+**循环此过程直到所有渲染问题修复、Wiki 页面显示正常为止。**
+
+### 第六步：安全收尾检查
+
+发布完成后，逐项确认并处理：
+
+1. **检查会话中是否产生含凭据的临时文件**
+   - 确认执行过程中未将 token/密码意外写入工作区临时文件
+   - 如有残留 → 立即删除该临时文件
+   - 注意：`~/.cbb/wiki-config.json` 是合法持久化配置，**禁止删除**
+
+**全部检查通过后，告知用户发布流程已完成。**

package/cbb/tools/cbb-mvn-guide/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: cbb-mvn-guide
+description: |
+  跨平台 Maven 构建助手，按项目 pom.xml 的 <java.version> 自动切到对应 JDK 后执行构建，
+  避免 JDK 版本不匹配导致编译失败。零外部依赖：pom 版本读取与 JDK 切换均由 skill 自带
+  的 Python 脚本完成（纯标准库），不依赖 jabba / SDKMAN 等外部工具，无需联网下载。
+  提速是默认前提不是附加项：所有命令默认带 -T 1C（按核并行）与 -Dmaven.javadoc.skip=true；
+  首次使用需在 ~/.m2/settings.xml 配置阿里云镜像（一行写入），二次构建（依赖已就位）可加 -o
+  走离线模式进一步省时；若本机装了 mvnd（Maven Daemon，常驻 JVM 省启动开销）则自动用它
+  替代 mvn——跑单测高频场景每次省 2-3s。
+  自动触发场景：
+  - 编译、打包、跑测试（mvn clean compile / package / test）
+  - 本地构建 Java/Spring Boot 多模块项目（如 ymm-ka 系列子项目，各子项目 JDK 要求不同）
+  - 报"未结束的字符串文字/非法字符"等 JDK 版本不匹配错误时排查
+  - 用户要求跑 mvn 但不确定本机该用哪个 JDK
+  工作流：步骤 0 镜像配置（首次，一次性）→ 步骤 1 mvn_pom_jdk_reader.py 读 pom 版本 →
+  步骤 2 mvn_jdk_manager.py 取/切对应 JDK（doctor 清失效 → scan 扫本机 → scan --adopt 登记 → use）→
+  步骤 3 自动检测 mvnd/mvn → 同条命令内 use | $MVN -v 校验 | $MVN -T 1C -Dmaven.javadoc.skip=true -q 执行。
+  跨平台：脚本纯标准库 Python3；shell 语法按当前环境适配（Windows 用 PowerShell，mac/linux 用 sh）。
+license: MIT
+metadata:
+  version: 3.0.0
+  category: development
+---
+
+# cbb-mvn-guide：自动切 JDK + 加速执行 Maven（跨平台、零外部依赖）
+
+## 何时用这个 skill
+
+用户要在本机跑 `mvn`（编译/打包/测试）时用。核心价值：
+1. **自动按项目 pom 的 `<java.version>` 切到正确 JDK**，避免 JDK 不匹配编译失败。
+2. **默认开启并行构建 + 阿里云镜像 + 跳过 javadoc**，所有 mvn 命令自带提速策略，无需临时拼参数。
+
+典型触发：用户说"编译一下""跑测试""mvn xxx"，或遇到文本块报错"未结束的字符串文字/非法字符"（JDK 版本过低）。
+
+## 两个固化脚本（都在 scripts/ 下，纯标准库）
+
+| 脚本 | 作用 |
+|---|---|
+| `mvn_pom_jdk_reader.py` | 读 pom `<java.version>` 并归一化主版本号（含按 `<parent><relativePath>` 找父 pom、`${}` 属性插值） |
+| `mvn_jdk_manager.py` | 迷你 JDK 管理器：`ls`/`current`/`link`/`unlink`/`use`/`scan`/`doctor`，注册表存 `~/.jdk-registry.json` |
+
+**不要临场写正则或 shell 探测**——这两个脚本已把易错逻辑（`1.8` 归一化、向上找父 pom、JDK 路径校验、跨 shell 输出 env 语句）固化，直接调用即可。
+
+调用时 python 命令名按平台：Windows 一般 `python`，部分 mac/linux 为 `python3`。下文统一写 `python`，POSIX 环境自行替换。
+
+## 关键约束（必读）
+
+1. **Shell 状态不持久**：Claude Code 每次执行 shell 调用相互独立，环境变量不跨调用保留。因此"切 JDK"和"跑 mvn"**必须在同一条命令里**串联执行——`mvn_jdk_manager.py use` 输出 env 设置语句，由当前 shell 立即 eval/source，紧接 `mvn -v; mvn ...`。不能分两次调用。
+2. **JDK 版本判断以 `mvn -v` 为准**，不看 `java -version`——`mvn` 用的是 `JAVA_HOME`，不是 PATH 上的 `java`。
+3. **`use` 不直接改环境**：它是子进程，改不了父 shell 的 env。所以 `use` 输出的是**当前 shell 的 set 语句**（PowerShell 输出 `$env:...=`，POSIX 输出 `export ...=`），由调用方 eval/source 生效。
+4. **提速是默认前提，不是可选项**：
+   - 所有构建命令默认带 `-T 1C`（每核 1 线程并行构建）、`-Dmaven.javadoc.skip=true`（跳过 javadoc 生成）。
+   - 首次使用需在 `~/.m2/settings.xml` 配置阿里云镜像（详见下方"步骤 0"）。
+   - 二次构建（依赖已就位）可加 `-o`（离线模式），省去远程仓库校验。
+   - 若本机装了 `mvnd`（Maven Daemon，常驻 JVM），skill 自动检测并用它替代 `mvn`——命令语法完全一致，无需改参数；高频单测场景每次省 2-3s JVM 启动开销。
+5. **输出纪律：成功安静，失败才说话（重要，关乎专业性）**。符合预期的步骤**不要**搞得像报错——红框、`Error: Exit code`、大段 `[ERROR]`/`[WARNING]` 日志都会让用户以为 skill 出了问题。具体：
+   - **mvn 一律加 `--quiet`**（`-q`）：成功时 mvn 完全静默（只看退出码），失败时才输出错误。这样编译/测试成功就干干净净，不会有满屏日志。
+   - **mvn 命令不要加 `2>&1`**：PowerShell 5.1 会把 mvn 走 stderr 的日志包成 `NativeCommandError` 红框并报假的 `Exit code 255`，即便 mvn 实际成功(exit 0)。让 stderr 由 harness 自行处理即可，别主动重定向。
+   - **判成功只看 `$LASTEXITCODE`/`$?`**：mvn 退出码 0 = 成功，非 0 = 失败。不要凭"有没有红字"判断——PS 的红框是 stderr 包装的假象，不代表失败。
+   - **成功时用自然语言一句话报告**（如"web 模块编译成功"），不贴 mvn 原始日志。**失败时**才把 mvn 关键错误行（`[ERROR] ... FAILURE`）提炼出来给用户看，并说明原因。
+   - **`mvn_jdk_manager.py` 一律加 `-q`**：失败时静默退出（exit 非0、无输出），不展示底层报错。由你按退出码判断后用自然语言提示/询问：
+     - `use` 失败（exit 1）→ 名称未登记或路径失效。不展示报错，直接走步骤 2 scan/doctor 流程：先 `doctor --prune` 清失效，`ls`/`scan` 看本机有哪些，没匹配主版本的就 `scan --adopt` 登记或问用户 JDK 装在哪。
+     - `link` 失败（exit 1）→ 路径无效。告诉用户"该路径下找不到 JDK（bin/java）"，问正确路径，不贴原始报错。
+     - `mvn_pom_jdk_reader.py --major` 输出空 → pom 没有 `<java.version>`，问用户该项目用哪个 JDK 版本。
+   - **区分"真错误"与"三方依赖噪音"**：Maven 解析三方 jar 的 pom 缺 `<version>` 时会打 `[ERROR]`（如 `crm-weixin-api` 的 commons-api/hibernate-validator），但这是告警性的、不影响编译、不是你的代码问题。别把这种当失败展示给用户。
+
+## 执行流程（严格按序）
+
+### 步骤 0：首次配置镜像（一次性，仅当用户首次用本 skill 时执行）
+
+Maven 默认从中央仓库（国外）拉依赖，慢且易超时。所有 mvn 命令的提速前提是 `~/.m2/settings.xml` 已配阿里云镜像。
+
+**检测：**
+```bash
+test -f ~/.m2/settings.xml && grep -q "maven.aliyun.com" ~/.m2/settings.xml && echo "MIRROR_OK" || echo "MIRROR_MISSING"
+```
+- `MIRROR_OK` → 跳过此步
+- `MIRROR_MISSING` → 继续
+
+**模板**（已有 settings.xml 时只追加 `<mirrors>` 段，避免覆盖用户其他配置）：
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
+  <mirrors>
+    <mirror>
+      <id>aliyunmaven</id>
+      <mirrorOf>*</mirrorOf>
+      <name>阿里云公共仓库</name>
+      <url>https://maven.aliyun.com/repository/public</url>
+    </mirror>
+  </mirrors>
+</settings>
+```
+
+**PowerShell 一键写入：**
+```powershell
+$dir = "$HOME\.m2"; New-Item -ItemType Directory -Force -Path $dir | Out-Null
+$path = "$dir\settings.xml"
+$xml = @'
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
+  <mirrors>
+    <mirror>
+      <id>aliyunmaven</id>
+      <mirrorOf>*</mirrorOf>
+      <name>阿里云公共仓库</name>
+      <url>https://maven.aliyun.com/repository/public</url>
+    </mirror>
+  </mirrors>
+</settings>
+'@
+Set-Content -Path $path -Value $xml -Encoding UTF8
+```
+
+**POSIX 一键写入：**
+```sh
+mkdir -p ~/.m2 && cat > ~/.m2/settings.xml <<'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
+  <mirrors>
+    <mirror>
+      <id>aliyunmaven</id>
+      <mirrorOf>*</mirrorOf>
+      <name>阿里云公共仓库</name>
+      <url>https://maven.aliyun.com/repository/public</url>
+    </mirror>
+  </mirrors>
+</settings>
+EOF
+```
+
+写完后用开头的检测命令验证一次即可。**只做一次，后续自动生效**。
+
+### 步骤 1：读项目 pom 的 java.version
+
+```
+python scripts/mvn_pom_jdk_reader.py <pom路径> --major
+```
+输出主版本号（`8` / `21` / `17`）；该 pom 及所有父 pom 都没有 `<java.version>` 则输出空行。
+
+完整信息用 JSON 模式：`python scripts/mvn_pom_jdk_reader.py <pom路径>` → `{"raw":"21","major":"21","pom_path":"...","interpolated":true}`。
+
+父 pom 定位优先解析 `<parent><relativePath>`（缺省默认 `../pom.xml`），找不到再回退逐级向上找同名 pom.xml；`${maven.compiler.release}` 这类属性引用会从同 pom `<properties>` 插值，解析不到保留原串并标记 `interpolated:false`（此时问用户用哪个版本）。传子模块 pom 路径即可。
+
+### 步骤 2：用 mvn_jdk_manager 取对应 JDK
+
+先清失效登记，再看已登记的 JDK：
+```
+python scripts/mvn_jdk_manager.py doctor --prune
+python scripts/mvn_jdk_manager.py ls
+```
+`doctor --prune` 清掉路径已失效（JDK 被卸载/迁移）的登记；`ls` 列出 名称 / 主版本 / 路径。判断**主版本匹配**（主版本对即可）。
+
+#### 情况 A：已有匹配主版本的 JDK → 直接 use
+```
+python scripts/mvn_jdk_manager.py -q use <名称>
+```
+
+#### 情况 B：没有匹配的 → scan 扫描本机已装 JDK，确认后 --adopt 登记
+- 先扫描（扫常见目录：Windows `Program Files\Java`、`Eclipse Adoptium`、`Amazon Corretto`、`D:\env\jdk` 等；POSIX `/Library/Java/...`、`/usr/lib/jvm/*`、`~/.jdks/*` 等）：
+  ```
+  python scripts/mvn_jdk_manager.py scan
+  ```
+  输出 序号/主版本/vendor/状态/路径，标记哪些已登记。**扫描结果给用户看**。
+- 确认无误后一键登记未登记的（`--adopt` 是显式触发，命名规则 `jdk<major>` 或 `<vendor><major>`，重名加 `_2`，打印登记明细可追溯）：
+  ```
+  python scripts/mvn_jdk_manager.py scan --adopt
+  ```
+  登记完回到情况 A `use`。
+- 若 scan 结果为空（本机没装该版本 JDK）：**停下告知用户**本机缺少 JDK<major>，请自行安装后 `scan --adopt` 或 `link` 登记。skill 不自动下载（避免联网）。
+
+#### 情况 C：用户已知 JDK 路径，直接 link
+- 用户给路径后登记（脚本校验 `bin/java` 存在，无效路径 `-q` 静默退出 exit 1，你转而提示路径不对）：
+  ```
+  python scripts/mvn_jdk_manager.py -q link <名称> <JDK根路径>
+  python scripts/mvn_jdk_manager.py -q use <名称>
+  ```
+  名称自取，建议含主版本便于辨识，如 `jdk21` / `corretto8`。
+
+### 步骤 3：校验 + 执行 mvn/mvnd（同一条命令，默认带提速参数）
+
+切 JDK 与跑构建 **必须在同一条命令**。先检测用 mvnd 还是 mvn，然后用该命令执行；`mvnd` 与 `mvn` 命令语法完全一致，仅替换可执行文件名即可。
+
+#### 3.1 检测构建命令（每会话或首次时执行一次）
+
+PowerShell：
+```powershell
+$mvndBin = Get-Command mvnd -ErrorAction SilentlyContinue
+if ($mvndBin) { $MVN = $mvndBin.Source }
+else { $mvnBin = Get-Command mvn -ErrorAction SilentlyContinue; if ($mvnBin) { $MVN = $mvnBin.Source } else { "请先安装 Maven 或 mvnd"; exit 1 } }
+"build_cmd=$MVN"
+```
+POSIX：
+```sh
+MVN=$(command -v mvnd 2>/dev/null || command -v mvn 2>/dev/null); if [ -z "$MVN" ]; then echo "请先安装 Maven 或 mvnd"; exit 1; fi; echo "build_cmd=$MVN"
+```
+
+- 输出 `build_cmd=.../mvnd` → 后续用 `mvnd`（daemon 常驻 JVM，高频单测每次省 2-3s 启动）
+- 输出 `build_cmd=.../mvn` → 用 `mvn`
+- 没装任何 → 提示安装（`brew install maven-mvnd` / `sdk install mvnd` / `scoop install mvndaemon` / 或直接下 zip 解压 https://github.com/apache/maven-mvnd/releases）
+
+#### 3.2 切 JDK + 跑构建（同一条命令）
+
+PowerShell：
+```powershell
+python scripts/mvn_jdk_manager.py -q use <名称> | Invoke-Expression; & $MVN -v | Select-String "Java version"; & $MVN -T 1C -Dmaven.javadoc.skip=true -q <命令> -f <pom路径>; "exit=$LASTEXITCODE"
+```
+POSIX：
+```sh
+eval "$(python3 scripts/mvn_jdk_manager.py -q use <名称>)"; $MVN -v | grep "Java version"; $MVN -T 1C -Dmaven.javadoc.skip=true -q <命令> -f <pom路径>; echo "exit=$?"
+```
+
+- `$MVN -v` 看 `Java version:` 是否为期望主版本——不对就停（`use` 没生效多半是没在同条命令里 eval）。
+- `-T 1C`：每核 1 线程并行构建（按 CPU 核数自动伸缩；不写死数字）。
+- `-Dmaven.javadoc.skip=true`：跳过 javadoc 生成（日常开发不需要，慢得显著）。
+- `-f <pom路径>` 显式指定 pom，别靠 cd。
+- 末尾打印退出码用于判断，**退出码 0 即成功**，别被 PS 可能的 stderr 红框误导。
+- **二次构建（依赖已就位）可加 `-o`**（离线模式），省去远程仓库校验。例如：
+  ```sh
+  $MVN -T 1C -Dmaven.javadoc.skip=true -q -o clean compile -f <pom路径>
+  ```
+  仅当本次构建只动源码、不引入新依赖时用 `-o`；改了 pom 加新依赖反而会报缺失。
+
+## Maven 常用命令指南（默认带并行 + 跳过 javadoc + 安静模式）
+
+> 下文命令中的 `mvn` 占位符按步骤 3.1 检测结果替换：装了 `mvnd` 则全部换成 `mvnd`，没装就用 `mvn`。两条命令语法完全一致。
+
+### 子项目 pom 定位
+多个子项目各自独立 pom，**一律 `-f` 指定**。具体版本以各项目 pom 的 `<java.version>` 为准（动态读取，不写死）。
+
+### 常用命令
+```
+# 编译
+mvn -T 1C -Dmaven.javadoc.skip=true -q clean compile -f <子项目>/pom.xml
+# 打包（跳过测试）
+mvn -T 1C -Dmaven.javadoc.skip=true -q clean package -DskipTests -f <子项目>/pom.xml
+# 跑单个测试类（测试命令建议暂不加 -q，便于看测试结果；失败时才把输出给用户）
+mvn -T 1C -Dmaven.javadoc.skip=true test -Dtest=ShippingIntentAgentTest -f <子项目>/pom.xml
+# 跑单个测试方法
+mvn -T 1C -Dmaven.javadoc.skip=true test -Dtest=ShippingIntentAgentTest#testMethodName -f <子项目>/pom.xml
+# 编译安装到本地仓库（跳过测试）
+mvn -T 1C -Dmaven.javadoc.skip=true -q clean install -DskipTests -f <子项目>/pom.xml
+# 二次构建（依赖已就位）—— 加 -o 走离线模式
+mvn -T 1C -Dmaven.javadoc.skip=true -q -o clean compile -f <子项目>/pom.xml
+```
+
+### 常见参数错误规避
+| 错误写法 | 正确写法 | 原因 |
+|---|---|---|
+| `mvn test -Dtest 类名` | `mvn test -Dtest=类名` | `-D` 参数要 `=`,不能空格 |
+| `mvn test -Dtest=类名 方法` | `mvn test -Dtest=类名#方法` | 方法用 `#` 分隔,不是空格 |
+| `mvn clean install` 不加 `-T` | `mvn -T 1C clean install` | 不并行慢；`1C` 按 CPU 核数自动 |
+| 不写 javadoc 还跑 `mvn install` | `-Dmaven.javadoc.skip=true` | javadoc 生成很慢且本地不需要 |
+| 改了 pom 加新依赖还 `-o` | 去掉 `-o` 或先单独 `-T 1C` 拉一次 | `-o` 离线模式无新依赖,加新依赖反而报缺失 |
+| 装了 mvnd 还直接用 `mvn` | 先按步骤 3.1 检测，按 `build_cmd=...` 选命令 | 高频单测每次白付 2-3s 启动开销 |
+| 切 JDK 与构建分两次 shell 调用 | 同一条命令: `use -q \| Invoke-Expression; & $MVN ...` | shell 状态不持久,分开则 use 不生效 |
+| 跨子项目一条命令连跑 | 分开各自 `use` + 构建 | 跨子项目 JDK 可能不同,分开跑 |
+| 给构建命令加 `2>&1`（PS） | 不加 | PS 5.1 把 stderr 包成 NativeCommandError 红框+假退出码255,即便成功也像报错 |
+| 成功时贴满屏构建日志 | 用 `-q` 静默,只看退出码 | 符合预期的步骤不该像报错 |
+
+### 大项目编译卡顿 / OOM
+若按上述跑仍然频繁 GC 或 OOM，给当前 shell 设一下堆内存（不影响其他进程）：
+```sh
+# 临时（仅当前 shell 生效）
+export MAVEN_OPTS="-Xmx2g -Xms2g"
+```
+按机器内存调整：8G 内存机可上 `-Xmx3g`，16G+ 可上 `-Xmx4g`。**不是默认**，仅出现上述症状时设。
+
+### 本地测试噪音（非失败，别误判，别当报错展示给用户）
+- **三方依赖 pom 缺 version 的 `[ERROR]`**：Maven 解析三方 jar（如 `crm-weixin-api`）的 pom 时，若其 `commons-api`/`hibernate-validator` 缺 `<version>`，会打 `[ERROR] ... is missing`。这是告警性的、不影响编译、不是你的代码问题。用 `-q` 可压制；判成败只看最终 `BUILD SUCCESS/FAILURE` 与退出码。
+- **PowerShell 的 `Error: Exit code 255` 红框**：PS 5.1 把 mvn 走 stderr 的日志包成 `NativeCommandError` 并报假退出码 255，**即便 mvn 实际 exit 0**。这是 PS 包装的假象，不是 mvn 失败。别加 `2>&1`，判成败只看 `$LASTEXITCODE`。
+- log4j2 报 `FileNotFoundException: /data/webapps/appenv`（Linux 路径）→ 本地正常，不影响结果。
+- 文本块在低版本 JDK 下报"未结束的字符串文字/非法字符"→ JDK 不匹配，不是代码 bug，切对 JDK 即可。
+
+## 输出要求（专业性）
+
+- **成功时安静**：符合预期的步骤用一句话自然语言报告（如"web 模块编译成功，JDK21，并行 1C"），**不贴 mvn 原始日志、不展示 `[ERROR]`/`[WARNING]` 噪音、不展示 PS 红框**。中间步骤的脚本输出（pom 版本、ls 列表）可在执行时短暂出现，但结论用自然语言总结。
+- **失败时才说话**：mvn 退出码非 0 时，把关键错误行（`[ERROR] ... FAILURE` 段）提炼出来，说明原因，不要整屏堆砌。
+- **判成败只看退出码**（`$LASTEXITCODE`/`$?`），不看"有没有红字"——PS 的 stderr 红框是包装假象。
+- `link` 用户给定路径属写本机注册表，登记前让用户确认路径；skill 本身不联网下载 JDK。