# @agile-team/wl-skills-bd 中文文档

规范地址：https://npmcn.com/package/%40agile-team/wl-skills-bd/

版本：0\.42\.0
npm 元数据更新时间：2026-10-21T05:20:23.628Z
中文译文更新时间：2026-11-06T22:27:41.728Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agile-team/wl-skills-bd
原文对照：https://npmcn.com/package/%40agile-team/wl-skills-bd/?lang=original
项目主页：https://github.com/ChenyCHENYU/wl-skills-bd#readme
源码仓库：https://github.com/ChenyCHENYU/wl-skills-bd

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，264 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-06-01T14:31:05.341Z
- 最新版本发布：2026-10-21T05:20:23.357Z
- 近 30 天下载量：2254（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：50（近 12 个月 50 个）

## 中文简介

面向 Java 8、Spring Boot 2、jh4j-cloud 3 的后端规范、契约生成、质量门与 MCP（v0.42.0：集成失败契约、真实执行证据与交付核验）

## 安装

```sh
npm install @agile-team/wl-skills-bd
```

也可以使用：`pnpm add @agile-team/wl-skills-bd`、`yarn add @agile-team/wl-skills-bd`、`bun add @agile-team/wl-skills-bd`

## README

![WL · World Leading · skills-bd](https://raw.githubusercontent.com/ChenyCHENYU/wl-skills-bd/main/assets/wl-bd-logo.svg)

**把 Java 后端的工程规范、业务契约、代码生成和质量检查接成一条可验证的交付流程。**

[![npm](https://img.shields.io/npm/v/@agile-team/wl-skills-bd?color=886331)](https://www.npmjs.com/package/@agile-team/wl-skills-bd) [![Node](https://img.shields.io/badge/Node-%E2%89%A522-526A81.svg)](https://nodejs.org/) [![Java](https://img.shields.io/badge/Java-8-886331.svg)](https://github.com/ChenyCHENYU/wl-skills-bd/blob/main/files/.github/java-quality/README.md)

## 解决什么问题

| 场景 | 提供的能力 | 你能看到的结果 |
| --- | --- | --- |
| 开发靠口头约定 | 后端规范、任务路由、项目 Profile | 当前任务要读什么、检查什么、还缺什么 |
| 接口、数据库与实现不一致 | 契约校验、代码生成、字段影响和前后端对账 | 差异定位、生成计划、待确认的业务疑点 |
| 问题等到构建或上线才出现 | B 规则、Git 变更审查、Java 质量门模板 | 文件、行号、严重度、修复建议及真实检查范围 |
| 修复依赖 AI 反复改代码 | 确定性修复、计划确认、备份、回滚与复扫 | 可审阅的前后差异，失败可恢复 |

适用于**已接入的 Java 8 / Spring Boot 2 后端工程**。当前已验证的生成 Profile 是 `jh4j3-openapi3`：jh4j-cloud 3.1、MyBatis-Plus、OpenAPI 3。其他技术栈需先核对兼容矩阵，不根据项目名称套用。

## 后端怎么安装

**这是 Node.js 工具包，不是 Maven 业务依赖。** Node.js 22+ 运行安装器、扫描器和 MCP；Java 8 / Maven 编译和验证业务代码。纯 Java 仓库可以直接用 `npx`，无需为了接入创建前端工程。

以下操作都在**实际后端仓库根目录**执行，聚合工作区不作为业务项目安装。

### 1\. 预览接入计划

```bash
npx @agile-team/wl-skills-bd init --json
```

查看待写入的规范、Skill、编辑器入口、MCP 和质量规则文件，取得 `planHash`。这一步不修改项目。

### 2\. 确认并安装

```bash
npx @agile-team/wl-skills-bd init --plan-hash <planHash> --confirm
npx @agile-team/wl-skills-bd check --json
```

只写本包受管资产，保留项目已有内容；`check` 检查安装完整性与漂移。纯 Java 仓库的 MCP 调用固定到安装版本。安装器不自动修改业务源码或 POM。

### 3\. 看第一份结果

```bash
npx @agile-team/wl-skills-bd doctor --json
npx @agile-team/wl-skills-bd validate . --json
```

`doctor` 暴露 JDK、质量门、配置与契约缺项；`validate` 执行后端规则，返回问题位置、建议和覆盖情况。出现 `partial` 时先补齐缺项，不能把未检查范围算作通过。

## 一个场景：提交前发现 SQL 问题

以订单模块为例，Mapper 中出现 `SELECT *`，字段增加后容易产生多余传输和映射风险。

| 步骤 | 工具做什么 | 验收点 |
| --- | --- | --- |
| 识别任务 | `task` 确认目标、规范和规则，返回 `runId` | 编辑前能看到实际 `notice` 和待检查项 |
| 定位问题 | `validate` 的 B3 定位 SQL 行 | 报告指出文件、行号及修复建议 |
| 预览修复 | `fix plan <Mapper路径> --rules B3 --json` | 有安全、显式且别名匹配的 `BaseColumns` 才提供确定性替换 |
| 确认执行 | 同目标 `fix apply` 携带 `--plan-hash <hash> --confirm` | 脚本写入、备份并复扫；不满足前置条件则留人工处理 |
| 复验交付 | 同 `runId` 再 `validate` 并查询 `status` | 问题前后可对比，范围明确；继续完成 Maven 与业务验收 |

```bash
# 路径替换为项目实际文件；runId 使用 task 返回值
npx @agile-team/wl-skills-bd task --input "修复订单 Mapper SQL 问题并复查" --target-file src/main/resources/mapper/OrderMapper.xml --json
npx @agile-team/wl-skills-bd validate src/main/resources/mapper/OrderMapper.xml --rules B3 --run-id <runId> --json
npx @agile-team/wl-skills-bd status --run-id <runId> --json
```

脚本负责可证明安全的机械修改，AI 解释差异与业务语义；权限、租户、SQL 语义和业务算法仍需审阅。单条规则通过只证明这次检查范围，未执行的规则、Java 构建和运行验证会保留未验证状态。

新建接口、加字段或增加业务命令走另一条同样明确的链：**更新契约 → 校验 → 预览生成 → 确认写入 → 前后端对账 → 编译测试 → 运行验收**。详见 [代码生成流程](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/codegen-workflow.md) 与 [业务交付闭环](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/business-closure-playbook.md)。

## 项目与流水线怎么配合

| 层面 | 接入方式 | 成功标志 |
| --- | --- | --- |
| 开发与 AI | `init` 安装入口；任务开始判定，结束复扫并读 `status` | 有真实工具记录和检查文件，缺项明确显示 |
| Git 变更审查 | `review run --base <基线分支> --json`；按项目配置接入钩子或 Gate | 区分新增问题、历史基线和有效豁免 |
| Java 静态分析 | 审查后将包内 Maven Profile 接入父 POM，使用 `wl-quality-audit` | 各适用模块产出真实 Checkstyle / PMD / SpotBugs 报告 |
| 单元与架构测试 | 独立使用 `wl-quality-unit`；已批准严格规范可使用 `wl-quality` | 编译、必测用例和覆盖率有独立结果 |
| 统一门禁与通知 | 按需由 Gate 调用本包并汇总原生报告 | 钩子、CI、报告与群通知按接线实际触发 |

BD 提供后端规则与执行器；**Gate 负责跨包编排和质量闭环**。两者都可独立使用。Java Profile 需先审查 POM 差异、模块范围和测试集合，再在隔离 Runner 验收；不要把静态报告成功当作构建、测试和业务已通过。接入命令见 [Java 质量门](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/java-quality/README.md)。

外部集成可声明步骤前提、调用顺序、未知结果、载荷容量及失败场景。严格策略核对真实 JUnit 与当前输入指纹；可选交付检查识别缺失 profile、跳过门禁和漏交文件。旧策略保留静态匹配语义，未配置项如实显示。配置与测试模板见 [集成失败场景与交付证据](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/integration-failure-contracts.md)。

安装入口不等于所有宿主已自动执行。首次接入用一条可定位问题验证“触发 → 报告 → 修复 → 复扫”；日常执行交给已配置的 AI 宿主、钩子和流水线。

## 按需深入

| 需要 | 入口 |
| --- | --- |
| 全部任务、规则与日常操作 | [使用指南](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/usage.md) · [任务目录](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/standards/26-task-driven.md) · [规范清单](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/standards/index.md) |
| 契约、数据库与前后端联调 | [生成流程](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/codegen-workflow.md) · [协作契约](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/frontend-backend-contract.md) |
| Java 工具与 Maven 配置 | [Java 质量门](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/java-quality/README.md) · [Maven 模板](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/java-quality/maven-snippets/README.md) |
| AI / MCP、协议与维护 | [MCP 工作流](https://npmcn.com/package/%40agile-team/wl-skills-bd/files/.github/guides/mcp-workflow.md) · [公开 API](https://npmcn.com/package/%40agile-team/wl-skills-bd/docs/public-api.md) · [维护契约](https://npmcn.com/package/%40agile-team/wl-skills-bd/docs/maintenance-contract.md) |
| 接入边界、范围配置与版本更新 | [项目范围](https://npmcn.com/package/%40agile-team/wl-skills-bd/docs/project-scope.md) · `wl-skills-bd update / diff / doctor-host` |

## WL 系列

**WL · World Leading**。各包按职责独立接入，已接且适用的包可共享任务 `runId`。

| 包 | 职责 |
| --- | --- |
| [skills-gate](https://github.com/ChenyCHENYU/wl-skills-gate) | 项目接入、钩子与 CI 门禁、报告闭环 |
| [skills-kit](https://github.com/ChenyCHENYU/wl-skills-kit) | PC 前端工程与代码规范 |
| [skills-ui](https://github.com/ChenyCHENYU/wl-skills-ui) | UI 一致性、扫描与确定性修复 |
| **skills-bd** | Java 后端契约、生成与质量检查 |
| [skills-test](https://github.com/ChenyCHENYU/wl-skills-test) | 测试规划、执行与验收证据 |
| [skills-design](https://github.com/ChenyCHENYU/wl-skills-design) | 需求、设计与交付文档 |

## 常见问题

### @agile-team/wl-skills-bd 是什么？

面向 Java 8、Spring Boot 2、jh4j-cloud 3 的后端规范、契约生成、质量门与 MCP（v0\.42\.0：集成失败契约、真实执行证据与交付核验）

### 如何安装 @agile-team/wl-skills-bd？

在项目目录运行 npm install @agile-team/wl-skills-bd，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 wl-skills-bd，可以用 npx wl-skills-bd 直接运行。

### @agile-team/wl-skills-bd 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agile-team\_\_wl-skills-bd 是否存在。

### @agile-team/wl-skills-bd 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @agile-team/wl-skills-bd 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agile-team/wl-skills-bd 可以商用吗？

@agile-team/wl-skills-bd 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @agile-team/wl-skills-bd 的下载量有多少？

根据 npm 官方下载统计，@agile-team/wl-skills-bd 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,254 次，日均约 75 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agile-team/wl-skills-bd 还在维护吗？

最新版本 0\.42\.0 发布于 2026/10/21（17 天前）；至今共发布 50 个版本，其中过去 12 个月发布了 50 个；首次发布于 2026/06/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。