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

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

版本：0\.13\.19
npm 元数据更新时间：2026-10-28T16:47:40.961Z
中文译文更新时间：2026-11-06T05:38:49.382Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：3.4 MB，480 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：^22\.13\.0 \|\| \>=24\.0\.0
- 运行依赖：15 个
- 首次发布：2026-10-12T08:02:08.271Z
- 最新版本发布：2026-10-28T16:47:40.786Z
- 近 30 天下载量：4730（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

质量工程执行包 — 统一接入、九维Review证据授权、自动门禁、可信CI采集与分类治理通知

## 安装

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

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

## README

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

**让项目检查、修复复扫、九维 Review 与构建发布接成一条可验证的质量流程。**

[![npm version](https://img.shields.io/npm/v/@agile-team/wl-skills-gate?color=087A7D&label=npm)](https://www.npmjs.com/package/@agile-team/wl-skills-gate) ![Node.js 22.13+ / 24+](https://img.shields.io/badge/Node.js-22.13%2B_or_24%2B-172634)

[快速接入](https://npmcn.com/package/%40agile-team/wl-skills-gate/#readme-%E5%BF%AB%E9%80%9F%E6%8E%A5%E5%85%A5) · [日常流程](https://npmcn.com/package/%40agile-team/wl-skills-gate/#readme-%E6%97%A5%E5%B8%B8%E6%80%8E%E4%B9%88%E7%94%A8) · [流水线接线](https://npmcn.com/package/%40agile-team/wl-skills-gate/#readme-%E6%B5%81%E6%B0%B4%E7%BA%BF%E6%80%8E%E4%B9%88%E6%8E%A5) · [技术手册](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/README.md)

## 解决什么

Gate 是质量执行与裁决层，复用项目已有检查器和适用的 WL 规则包。检查、报告、机械修复、复扫和通知由脚本执行，不调用大模型 API。

| 场景 | Gate 提供什么 | 能看到什么 |
| --- | --- | --- |
| 完整检测 | Java参考六引擎＋BD组织规则；前端类型语义、安全、密钥、重复、架构和依赖 | 原件、覆盖范围、指标与具体位置 |
| 日常提交 | Hook 自动运行分档检查 | 问题位置、规则、修复建议与阻断原因 |
| 问题整改 | 预览方案 → 本人确认 → 白名单脚本 → 复扫 | 修前修后变化、剩余问题与回归项 |
| Code Review | 汇总九维证据，生成待确认草稿 | 非作者逐维确认后的正式 Review |
| 合并与发布 | 核验候选 SHA、必需检查、Review、制品和目标环境 | 绑定本次代码与制品的放行或拒绝结果 |
| 问题跟进 | 分类通知、认领、超时对账、独立复验 | 可追溯的处理与关闭记录 |

**九维范围：** 提交 · 分支 · 编码 · UI 与交互 · Code Review · 测试 · 扫描门禁 · CI/CD · 工程治理。

## 快速接入

技术经理拿到批准的完整接入包后，填写`现场参数.json`，运行根目录`01_接入项目.sh`（macOS可双击`.command`）；运维使用运维包的`01_接入Jenkins.sh`。脚本安装固定包并调用Gate；所需参数与成功反馈见包内唯一主说明。先提供 Node.js 22.13+（22系列）或24+、项目固定的包管理器及原有构建工具。

| 任务 | 人只需做什么 | 脚本完成什么 |
| --- | --- | --- |
| 首次接入项目 | 选择 Git 项目根、批准安装源，确认各阶段差异 | 识别范围、安装固定依赖、同步规则、Hook、POM/锁、首扫及提交说明正反验证 |
| 新成员初始化 | 选择已接项目，在安装与激活计划上确认 | 按仓库已提交清单恢复本机环境，保留项目策略，再验真实 Hook |
| 六分支接线 | 选择批准基础配置，确认完整差异 | 自动生成目标分支独立scope与Review接线；保留验证来源，权限与作业仍由运维配置 |
| 运维接线 | 选择批准配置目录，预检后选择启动 | 核对配置/身份/凭据存在性/旧状态，启动中央采集与操作入口；消息默认预览 |
| 组合发布输入 | 选择批准配置，确认组件与输出 | 从真实采集原件生成输入，核验来源、SHA、制品与兼容证据 |

已安装批准版本的维护者也可启动相同交互流程；进入后无需复制计划摘要或拼接后续命令：

```bash
wl-quality init
```

本轮统一使用`0.13.19`固定版本；正式交付以批准发布的版本及字节摘要为准，安装脚本自动核验。

| 项目 | 依赖装在哪里 | 业务构建 |
| --- | --- | --- |
| PC Vue 管理端，如 `wl-ui-produce` | 根 `package.json`：Gate / Kit / UI | 保留原前端构建 |
| Java/Maven，如 `wl-produce` | `quality-tools/package.json`：Gate / BD | Maven；Node 工具不进入 jar |

`quality-tools/` 是 Java 仓库内的 Node 工具依赖目录。内置后端配套针对 `wl-produce` PL；其他 Maven 项目先由负责人配置模块与必测。移动端、UniApp 不套用 PC 配套。

后续更新使用交付包的增量入口：完整包 `04_增量更新.sh`，运维包 `02_增量更新.sh`。先显示变化，确认后仅更新受管资产；配置和凭据保留，中断可续跑，核验失败回退，无变化跳过安装。Jenkins 继续自动复验公共任务与飞书；规则或工具身份变化须重新核验正式准入，升级不代替 Review 授权。

首次接入反馈在 `quality-reports/setup/<sessionId>/result.html`，质量报告在 `quality-reports/quality-report.html`。只有真实首扫及 Hook 正反验证通过，才返回 `local-validated-awaiting-remote-acceptance`。GitLab/Jenkins 强制检查、独立 Review、真实到群及部署另做现场验收。

工具安装与质量结论分别记录：`installed-quality-blocked` 表示依赖、受管资产、版本锁及 Hook 已验证，真实扫描发现问题，需按报告整改后复扫；业务构建仍被质量门阻断。安装中断或检查执行异常保留真实阶段回执，同一入口继续处理，无需从头配置。

接线配置、非交互任务参数与失败处理见 [接入指南](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/17-onboarding.md)。

## 日常怎么用

开发者正常提交、推送；Hook 自动检查。以 `wl-ui-produce` 修改订单列表为例：

| 步骤 | 开发者 / 负责人做什么 | 系统给出什么 |
| --- | --- | --- |
| 提交前 | 按原流程暂存、提交代码 | 快速检查；有阻断显示具体位置和建议 |
| 推送前 | 正常推送 | 标准检查、HTML 报告；已配置 Review 策略时自动生成九维草稿 |
| 处理问题 | 在已生成的编辑器任务中选择“预览脚本修复”，核对并确认 | 执行批准的机械脚本、自动复扫，展示差异；语义问题保留人工处理 |
| 发起 Review | 非作者查看代码、补齐实际交互与业务证据、逐维确认 | 绑定当前候选与证据的正式 Review |
| 构建发布 | 通过受控流水线推进 | 核验本次候选、检查和制品；部署后独立复验再关闭问题 |

同口径的修前修后报告才展示质量变化。扫描通过、Review 确认、发布授权和问题关闭分别核验；一项通过不会代替其余步骤。

## 流水线怎么接

由 GitLab / Jenkins 维护者接线，项目负责人确认规则与必测，通知负责人配置群与分类。执行模板都在本包中。

Jenkins 节点需启用 Pipeline Utility Steps（`pipeline-utility-steps`）；公共入口使用 `readJSON(returnPojo: true)`，保持 Sandbox 开启。责任目录可由受控交付包导入，项目配置优先；通知身份不授予 Review 权限。报告网络条件由集群配置声明。

| 接线内容 | 入口 | 验证方式 |
| --- | --- | --- |
| GitLab MR、候选与受保护分支 | [CI 模板](https://npmcn.com/package/%40agile-team/wl-skills-gate/templates/ci) · [GitLab 指南](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/06-gitlab.md) | 违规候选不能合并，真实必需作业齐全 |
| Jenkins 检查与构建 | 服务器本地公共入口，单维护任务批量接入／核验／回退；[Jenkins 指南](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/07-jenkins.md) | 两个Job共用包内入口，自动识别范围、核对配置与严格准入 |
| 真实 CI 证据、身份与 Review | [可信 CI 采集](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/18-ci-source.md) · [九维 Review](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/19-nine-dimension-review.md) | 旧报告、缺证据、自审与过期批准被拒绝 |
| 飞书通知、认领、超时与复验 | [中央执行接线](https://npmcn.com/package/%40agile-team/wl-skills-gate/templates/platform/README.md) | 实际送达、失败重试、认领和独立关闭均留记录 |

流水线按批准的工作副本清单和依赖锁准备环境，不运行任意生命周期脚本。构建前自动匹配本次 SHA 的正式 Review 并重查 CI；组合与部署再次核验签名及原件，缺失就阻断。普通警告按周期汇总，首次采集故障、持续异常和恢复也有提醒。

项目检查作业与受控签发、部署、通知作业隔离。Hook 提供早反馈；服务端强制检查负责防绕过。

## 报告怎么看与保存

质量报告展示本次 SHA 的检查结论、风险与九维证据；运维报告展示账号、项目接入、流水线接线、公共配置、执行与报告五类接入诊断。两者均先显示本轮原因与下一步处理，日志按钮定位同一份报告的重点日志，完整控制台保留原始上下文。大量范围按仓库折叠，诊断记录分组展开。

报告 HTML 内嵌完整样式，无需启动本机服务即可离线阅读、转存。在线另附同源 CSS，兼容 Jenkins 的严格内容安全策略，不加载外部脚本、字体或样式。生成的 HTML 与 CSS 按运行归档，不覆盖历史原件。

质量报告对应的构建、已发送或发送结果未知的巡检通知对应构建会标记保留，避免被 Job 的自动清理删除。在线访问仍需内网／VPN与该任务的读取权限；运维应将 Jenkins 持久目录纳入备份，人工删除和存储故障不属于链接留存保证。报告页面不授予构建、配置或凭据权限。

## 按需深入

| 要做什么 | 文档 |
| --- | --- |
| 调整检查器、范围、等级与例外 | [策略配置](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/02-config.md) · [适配器](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/05-adapters.md) |
| 维护修复白名单、漂移检查与回滚 | [修复闭环](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/04-fix-loop.md) |
| 只读定位问题，减少重复扫描与上下文 | [低 token 执行](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/14-low-token-execution.md) · [Java 报告分级](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/15-java-report-triage.md) |
| 排查接入与环境问题 | [项目与运维集成](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/16-project-ci-integration.md) · [完整索引](https://npmcn.com/package/%40agile-team/wl-skills-gate/docs/README.md) |

检查退出码：`0` 通过，`1` 质量阻断，`2` 执行或证据无效。后两者都需要处理，不得以历史绿报告替代本轮结果。

## WL 系列

**WL = World Leading。** 按职责组合，未使用的包无需安装。

| 包 | 职责 |
| --- | --- |
| **Gate** | 统一接入、检查裁决、修复复扫、Review 与发布证据 |
| [Kit](https://github.com/ChenyCHENYU/wl-skills-kit) | PC Vue 管理端需求、契约、代码生成与工程规范 |
| [UI](https://github.com/ChenyCHENYU/wl-skills-ui) | PC 管理端设计令牌、样式与交互质量 |
| [BD](https://github.com/ChenyCHENYU/wl-skills-bd) | Java 后端规范、契约与检查能力 |
| [Test](https://github.com/ChenyCHENYU/wl-skills-test) | 测试设计、执行与结果验证 |
| [Design](https://github.com/ChenyCHENYU/wl-skills-design) | 需求与设计模型、交付契约 |

使用授权见 [LICENSE](https://npmcn.com/package/%40agile-team/wl-skills-gate/LICENSE)。问题反馈请附包版本、执行命令和脱敏报告，提交至 [Issues](https://github.com/ChenyCHENYU/wl-skills-gate/issues)。

消息按钮、布局和品牌从中央 `notification-presentation.json` 逐条热读取；风险、结论、责任人和门禁规则不由该文件控制。Gate执行逻辑仍按固定版本增量升级，不在Hook下载latest。

## 常见问题

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

质量工程执行包 — 统一接入、九维Review证据授权、自动门禁、可信CI采集与分类治理通知

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

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

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

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

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

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

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

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

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

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