@agile-team/wl-skills-gate 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 变更记录
 
+## [0.13.1] — 2026-10-22
+
+- Jenkins安装自动记录实际Node目录；服务器命令别名使用固定Node绝对路径，公共入口及各角色任务自动设置Node/npm的PATH。各节点可用受控WL_NODE_BIN_DIR覆盖本机差异。
+- 接入交付启动器支持WL_NODE_BIN_DIR与现场Node路径，所有安装子进程共用同一套Node/npm；启动前核验执行器原件，脚本被编辑或函数被删除时给出明确恢复提示。
+- 增加精简PATH、自定义Node路径、原件恢复与跨节点环境回归，保留完整性校验及严格构建准入。
+
 ## [0.13.0] — 2026-10-22
 
 - Jenkins服务器公共入口随Gate安装，按实际Job识别检查、构建、中央、签发和维护角色；一个fleet任务批量配置，预览确认、回读、续跑及回退均留记录。

package/README.md

@@ -49,7 +49,7 @@ Gate 是质量执行与裁决层，复用项目已有检查器和适用的 WL
 wl-quality init
 ```
 
-本轮统一使用`0.13.0`固定版本；交付包与批准安装源的版本和字节摘要须一致，安装脚本自动核验。
+本轮统一使用`0.13.1`固定版本；交付包与批准安装源的版本和字节摘要须一致，安装脚本自动核验。
 
 | 项目 | 依赖装在哪里 | 业务构建 |
 | --- | --- | --- |

package/docs/01-quick-start.md

@@ -27,7 +27,7 @@ wl-quality init
 
 ```bash
 npm exec --yes --ignore-scripts --registry=https://registry.npmjs.org/ \
-  --package=@agile-team/wl-skills-gate@0.13.0 -- wl-quality init
+  --package=@agile-team/wl-skills-gate@0.13.1 -- wl-quality init
 ```
 
 向导展示差异与实际安装计划，确认后执行；检查异常不能当成零问题。接入后日常由Hook自动检查；正式Review、远端强制检查、群消息与报告权限仍按现场清单验收。

package/docs/07-jenkins.md

@@ -18,7 +18,7 @@ node('wl-quality-router') { load('/opt/wl-quality/gate-validation/jenkins/entry.
 
 ## 节点自检与失败通知
 
-正常接入先运行编号脚本，再由自动创建的`wl-quality-doctor`验环境与机器人。若要在安装Gate前先验证失败通知，使用交付包`验收/环境与飞书验证.Jenkinsfile`：首次默认环境检查；后续在参数化构建中勾选`TEST_NOTIFICATION`可只测消息。自检使用 Python3 标准库；即使 Node 或 Gate 缺失，也能记录失败并尝试签名通知。Node 统一使用节点 PATH 或受控 `WL_NODE_BIN_DIR`，不能在自检与构建中各选一套运行时。
+正常接入先运行编号脚本，再由自动创建的`wl-quality-doctor`验环境与机器人。若要在安装Gate前先验证失败通知，使用交付包`验收/环境与飞书验证.Jenkinsfile`：首次默认环境检查；后续在参数化构建中勾选`TEST_NOTIFICATION`可只测消息。自检使用 Python3 标准库；即使 Node 或 Gate 缺失，也能记录失败并尝试签名通知。安装自动记录实际Node目录，服务器公共入口、命令别名及任务子进程统一使用该目录；其他节点路径不同时，在该节点设置受控`WL_NODE_BIN_DIR`。无需修改受控脚本，不能在自检与构建中各选一套运行时。
 
 生成的业务入口与辅助任务均先自检，再执行业务操作。异常处理使用流水线机器人凭据 `wl-feishu-ci-webhook`、`wl-feishu-ci-signing-secret`；凭据只在通知阶段绑定。缺凭据、缺 Python3、网络失败不会把原失败变成成功，也不假报送达。普通代码质量阻断由中央质量卡片通知，避免再发一张环境异常卡片；报告发布失败仍单独报执行异常。
 
@@ -63,7 +63,7 @@ node('wl-quality-router') { load('/opt/wl-quality/gate-validation/jenkins/entry.
 
 ## 当前交付边界
 
-本轮以0.13.0固定正式版本交付。包发布和隔离测试不代表两业务仓库或远端已接通。正式Review后的自动续建、验证构建结果/制品采集、紧凑检查卡片可靠投递已通过隔离贯通测试；真实项目配置、中央服务、TEST任务和飞书身份仍需现场交接／验收。
+本轮以0.13.1固定正式版本交付。包发布和隔离测试不代表两业务仓库或远端已接通。正式Review后的自动续建、验证构建结果/制品采集、紧凑检查卡片可靠投递已通过隔离贯通测试；真实项目配置、中央服务、TEST任务和飞书身份仍需现场交接／验收。
 
 团队操作以交付包根目录的完整或运维接入操作说明为准，本文供维护者排查底层契约。
 

package/docs/README.md

@@ -1,6 +1,6 @@
 # wl-skills-gate 技术手册索引
 
-当前正式版本0.13.0。团队操作以交付包根目录主说明为准，见[16 项目与运维入口](16-project-ci-integration.md)；本索引提供工具契约与参数参考。
+当前正式版本0.13.1。团队操作以交付包根目录主说明为准，见[16 项目与运维入口](16-project-ci-integration.md)；本索引提供工具契约与参数参考。
 
 授权声明见 [LICENSE](../LICENSE)；公开获取不授予使用、复制、修改或再分发授权，申请入口为 [仓库 Issues](https://github.com/ChenyCHENYU/wl-skills-gate/issues)。
 

package/lib/jenkins-cluster.js

@@ -9,7 +9,8 @@ export const MAINTENANCE_JOBS={node:'wl-quality-doctor',verify:'wl-quality-verif
 export const defaultClusterFile=env=>env.WL_QUALITY_CLUSTER_CONFIG||'/srv/wl-quality/config/jenkins-cluster.json';
 export function loadJenkinsCluster(file){
  file=controlledPath(path.resolve(file));const c=readControlledJson(file),base=path.dirname(file);
- assert(c.schemaVersion===1&&c.kind==='wl-quality-jenkins-cluster'&&Object.keys(c).every(k=>['schemaVersion','kind','jenkinsOrigin','registryFiles','configDir','agents','nativeEntry'].includes(k)),'需要有效的集群接入配置');
+ assert(c.schemaVersion===1&&c.kind==='wl-quality-jenkins-cluster'&&Object.keys(c).every(k=>['schemaVersion','kind','jenkinsOrigin','registryFiles','configDir','nodeBinDir','agents','nativeEntry'].includes(k)),'需要有效的集群接入配置');
+ if(c.nodeBinDir!==undefined){assert(typeof c.nodeBinDir==='string'&&path.isAbsolute(c.nodeBinDir)&&!/[\u0000-\u001f'"`$\\]/.test(c.nodeBinDir),'Node目录须为受控绝对路径');c.nodeBinDir=controlledPath(c.nodeBinDir);}
  const u=new URL(c.jenkinsOrigin);assert(u.protocol==='https:'&&!u.username&&!u.password&&u.pathname==='/'&&!u.search&&!u.hash,'集群入口须为批准HTTPS origin');c.jenkinsOrigin=u.origin+'/';validateNativeEntry(c.nativeEntry);
  assert(Array.isArray(c.registryFiles)&&c.registryFiles.length>0&&c.registryFiles.length<=1000&&new Set(c.registryFiles).size===c.registryFiles.length,'需要无重复的批准登记路径');c.registryFiles=c.registryFiles.map(v=>{assert(typeof v==='string'&&v,'登记路径无效');return controlledPath(path.resolve(base,v));});
  assert(typeof c.configDir==='string'&&c.configDir,'缺少中央配置目录');c.configDir=controlledPath(path.resolve(base,c.configDir));
@@ -26,5 +27,5 @@ export async function resolveJenkinsContext({role='auto',configFile=defaultClust
   assert(entryPointHash(selected.r.nativeEntry)===entryPointHash(c.nativeEntry),'登记与集群公共入口不一致，先更新批准登记');assert(selected.r.bindings.find(b=>Object.values(b.jobs).includes(env.JOB_NAME)).runtimeHash===gateRuntimeHash(),'跨节点包字节不一致，不能路由到另一套规则');
  }
  if(verifyEntry){assert(c.nativeEntry.runtimeHash===gateRuntimeHash(),'Gate运行时与批准公共入口不一致');assert(digest(readFileSync(controlledPath(c.nativeEntry.loaderFile)))===c.nativeEntry.loaderHash,'服务器公共入口被修改，停止执行');}
- return {schemaVersion:1,kind:'wl-quality-jenkins-context',role,agentLabel,gateRoot,registry:registryFile,configDir:c.configDir,clusterFile:c.file,jenkinsOrigin:c.jenkinsOrigin,nativeEntry:c.nativeEntry,entryVerified:verifyEntry,gateVersion:GATE_VERSION,runtimeHash:gateRuntimeHash(),clusterHash:c.configHash,qualityPassed:false,buildAuthorized:false};
+ return {schemaVersion:1,kind:'wl-quality-jenkins-context',role,agentLabel,gateRoot,nodeBinDir:c.nodeBinDir||path.dirname(process.execPath),registry:registryFile,configDir:c.configDir,clusterFile:c.file,jenkinsOrigin:c.jenkinsOrigin,nativeEntry:c.nativeEntry,entryVerified:verifyEntry,gateVersion:GATE_VERSION,runtimeHash:gateRuntimeHash(),clusterHash:c.configHash,qualityPassed:false,buildAuthorized:false};
 }

package/lib/jenkins-installation.js

@@ -15,11 +15,12 @@ export function planJenkinsInstallation(options={}){
  const u=new URL(jenkinsOrigin);assert(u.protocol==='https:'&&u.pathname==='/'&&!u.username&&!u.password&&!u.search&&!u.hash,'安装需要批准Jenkins HTTPS origin');assert([centralAgentLabel,reviewSignerAgentLabel].every(v=>/^[A-Za-z0-9_.-]{1,100}$/.test(v||'')),'需要现场实际中央及独立签发节点标签');
  registryFiles||=[path.join(configDir,'jenkins-bindings.json')];assert(Array.isArray(registryFiles)&&registryFiles.length>0&&registryFiles.every(v=>path.isAbsolute(v)),'批准登记路径须明确');
  const clusterFile=path.join(configDir,'jenkins-cluster.json'),loaderFile=path.join(prefix,'jenkins/entry.groovy'),aliasFile=path.join(prefix,'bin/wl-quality');
- const loader=jenkinsBootstrapHelper()+readFileSync(path.join(GATE_ROOT,'templates/ci/jenkins-loader.groovy'),'utf8').replaceAll('__WL_GATE_ROOT__',GATE_ROOT).replaceAll('__WL_CLUSTER_FILE__',clusterFile).replaceAll('__WL_RUNTIME_HASH__',gateRuntimeHash());
+ const nodeBinDir=controlledPath(path.dirname(process.execPath));assert(!/[\u0000-\u001f'"`$\\]/.test(nodeBinDir),'Node安装路径含不支持的字符');
+ const loader=jenkinsBootstrapHelper()+readFileSync(path.join(GATE_ROOT,'templates/ci/jenkins-loader.groovy'),'utf8').replaceAll('__WL_GATE_ROOT__',GATE_ROOT).replaceAll('__WL_CLUSTER_FILE__',clusterFile).replaceAll('__WL_RUNTIME_HASH__',gateRuntimeHash()).replaceAll('__WL_NODE_BIN_DIR__',nodeBinDir);
  const nativeEntry={loaderFile,loaderHash:digest(loader),runtimeHash:gateRuntimeHash()};
- const c={schemaVersion:1,kind:'wl-quality-jenkins-cluster',jenkinsOrigin:u.origin+'/',registryFiles,configDir,agents:{central:centralAgentLabel,review:reviewSignerAgentLabel},nativeEntry};
- const files=[{file:loaderFile,text:loader,mode:0o644},{file:aliasFile,text:'#!/bin/sh\nset -eu\nexec node '+quote(path.join(GATE_ROOT,'bin/wl-quality.js'))+' "$@"\n',mode:0o755},{file:clusterFile,text:JSON.stringify(c,null,2)+'\n',mode:0o600}].map(f=>{controlledPath(f.file);const before=existsSync(f.file)?readFileSync(f.file,'utf8'):null;return {...f,before,action:before===f.text&&(lstatSync(f.file).mode&0o777)===f.mode?'unchanged':before===null?'create':'update'};});
- const plan={kind:'wl-quality-installation-plan',prefix,configDir,runtimeHash:gateRuntimeHash(),files,nativeEntry,pipelineScript:nativePipelineEntry(nativeEntry),nodeEnvironment:{'PATH+WLQUALITY':path.join(prefix,'bin'),WL_QUALITY_CLUSTER_CONFIG:clusterFile},routerLabel:'wl-quality-router'};return {...plan,planHash:digest(stableStringify(plan)),status:'preview'};
+ const c={schemaVersion:1,kind:'wl-quality-jenkins-cluster',jenkinsOrigin:u.origin+'/',registryFiles,configDir,nodeBinDir,agents:{central:centralAgentLabel,review:reviewSignerAgentLabel},nativeEntry};
+ const files=[{file:loaderFile,text:loader,mode:0o644},{file:aliasFile,text:'#!/bin/sh\nset -eu\nPATH='+quote(nodeBinDir)+':"$PATH"\nexport PATH\nexec '+quote(process.execPath)+' '+quote(path.join(GATE_ROOT,'bin/wl-quality.js'))+' "$@"\n',mode:0o755},{file:clusterFile,text:JSON.stringify(c,null,2)+'\n',mode:0o600}].map(f=>{controlledPath(f.file);const before=existsSync(f.file)?readFileSync(f.file,'utf8'):null;return {...f,before,action:before===f.text&&(lstatSync(f.file).mode&0o777)===f.mode?'unchanged':before===null?'create':'update'};});
+ const plan={kind:'wl-quality-installation-plan',prefix,configDir,runtimeHash:gateRuntimeHash(),files,nativeEntry,pipelineScript:nativePipelineEntry(nativeEntry),nodeEnvironment:{'PATH+WLQUALITY':path.join(prefix,'bin'),WL_NODE_BIN_DIR:nodeBinDir,WL_QUALITY_CLUSTER_CONFIG:clusterFile},routerLabel:'wl-quality-router'};return {...plan,planHash:digest(stableStringify(plan)),status:'preview'};
 }
 export function applyJenkinsInstallation(options={}){
  const plan=planJenkinsInstallation(options);assert(options.confirm===true&&options.planHash===plan.planHash,'准备执行须绑定当前路径、包版本和差异计划');

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@agile-team/wl-skills-gate",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@agile-team/wl-skills-gate",
-      "version": "0.13.0",
+      "version": "0.13.1",
       "license": "UNLICENSED",
       "dependencies": {
         "@secretlint/node": "13.0.7",
@@ -1194,7 +1194,7 @@
         "tapable": "^2.3.3"
       },
       "engines": {
-        "node": ">=10.13.0"
+        "node": ">=10.13.1"
       }
     },
     "node_modules/entities": {
@@ -1613,7 +1613,7 @@
         "is-glob": "^4.0.3"
       },
       "engines": {
-        "node": ">=10.13.0"
+        "node": ">=10.13.1"
       }
     },
     "node_modules/global-directory": {
@@ -1728,7 +1728,7 @@
       "integrity": "sha512-6xwYfHbajpoF0xLW+iwLkhwgvLoZDfjYfoFNu8ftMoXINzwuymNLd9u/KmwtdT2GbR+/Cz66otEGEVVUHX9QLQ==",
       "license": "MIT",
       "engines": {
-        "node": ">=10.13.0"
+        "node": ">=10.13.1"
       }
     },
     "node_modules/is-core-module": {
@@ -2433,7 +2433,7 @@
         "resolve": "^1.20.0"
       },
       "engines": {
-        "node": ">= 10.13.0"
+        "node": ">= 10.13.1"
       }
     },
     "node_modules/regexp-tree": {
@@ -2910,7 +2910,7 @@
         "tsconfig-paths": "^4.1.2"
       },
       "engines": {
-        "node": ">=10.13.0"
+        "node": ">=10.13.1"
       }
     },
     "node_modules/type-check": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-gate",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "质量工程执行包 — 统一接入、九维Review证据授权、自动门禁、可信CI采集与分类治理通知",
   "type": "module",
   "main": "./lib/run.js",

package/scripts/lib-tests/jenkins-native.test.mjs

@@ -16,9 +16,12 @@ const environment=(job='wl-quality-fleet')=>({JENKINS_URL:'https://jenkins.examp
 test('服务器公共入口随Gate安装，零新仓库；重复安装无差异且修改须重新预览',t=>{
  const f=fixture(t),v=installed(f);assert.match(v.result.pipelineScript,/node\('wl-quality-router'\).*load\(.*entry.groovy.*\) \}\.call\(\)/);assert(!v.result.remoteModified);assert(existsSync(v.result.nativeEntry.loaderFile));assert(planJenkinsInstallation(v.input).files.every(e=>e.action==='unchanged'));assert.throws(()=>applyJenkinsInstallation({...v.input,confirm:true,planHash:v.p.planHash}),/差异计划/);assert.throws(()=>planJenkinsInstallation({...v.input,libraryManifestFile:'unused'}),/未知/);
  const alias=spawnSync(v.result.command,['--version'],{encoding:'utf8'});assert.equal(alias.status,0,alias.stderr);assert.equal(alias.stdout.split(' ')[1],GATE_VERSION);
+ const minimal=spawnSync(v.result.command,['--version'],{encoding:'utf8',env:{...process.env,PATH:'/usr/bin:/bin'}});assert.equal(minimal.status,0,minimal.stderr);assert.equal(minimal.stdout.split(' ')[1],GATE_VERSION);
+ assert.equal(v.result.nodeEnvironment.WL_NODE_BIN_DIR,path.dirname(process.execPath));const cluster=JSON.parse(readFileSync(v.result.clusterFile));assert.equal(cluster.nodeBinDir,path.dirname(process.execPath));assert(!readFileSync(v.result.nativeEntry.loaderFile,'utf8').includes('__WL_NODE_BIN_DIR__'));assert(readFileSync(v.result.nativeEntry.loaderFile,'utf8').includes(path.dirname(process.execPath)));
 });
 test('路由按真实Job识别维护角色，拒绝冒充签发者和入口漂移',async t=>{
  const f=fixture(t),v=installed(f),args={configFile:v.result.clusterFile,env:environment(),verifyEntry:true};const c=await resolveJenkinsContext(args);assert.equal(c.role,'fleet');assert.equal(c.agentLabel,'central');assert(c.entryVerified);await assert.rejects(resolveJenkinsContext({...args,role:'review'}),/不能借/);writeFileSync(v.result.nativeEntry.loaderFile,'changed');await assert.rejects(resolveJenkinsContext(args),/入口被修改/);
+ assert.equal(c.nodeBinDir,path.dirname(process.execPath));
 });
 test('业务Job按登记路由，公共入口和当前包字节都须一致',async t=>{
  const f=fixture(t);await bind(f);const v=installed(f),r=JSON.parse(readFileSync(f.registryFile));r.nativeEntry=v.result.nativeEntry;put(f.base,'bindings.json',r);const c=await resolveJenkinsContext({configFile:v.result.clusterFile,env:f.environment('CHECK'),verifyEntry:true});assert.equal(c.role,'job');assert.equal(c.registry,f.registryFile);assert.equal(renderJenkinsEntry(r,f.registryFile),v.result.pipelineScript);await assert.rejects(resolveJenkinsContext({role:'review',configFile:v.result.clusterFile,env:f.environment('CHECK')}),/不能借/);

package/templates/ci/check-project.config.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "kind": "wl-quality-ci-check",
   "project": "REPLACE_WITH_ACTUAL_PROJECT",
-  "gateVersion": "0.13.0",
+  "gateVersion": "0.13.1",
   "workspaceHash": "REPLACE_WITH_APPROVED_WORKSPACE_SHA256",
   "lockHash": "REPLACE_WITH_APPROVED_LOCK_SHA256",
   "policyHash": "REPLACE_WITH_APPROVED_POLICY_SHA256",

package/templates/ci/jenkins-bootstrap.py

@@ -55,7 +55,7 @@ def preflight(env):
     valid_root = root.is_absolute() and root.is_dir()
     check("gate-root", valid_root, "固定 Gate 目录可读取" if valid_root else "固定 Gate 目录不存在或不可读取",
           "在该Jenkins节点运行本包的接入Jenkins脚本；使用安装回执中的 gateHome。包内入口为 bin/wl-skills-gate.js。")
-    expected = env.get("WL_BOOTSTRAP_GATE_VERSION", "0.13.0")
+    expected = env.get("WL_BOOTSTRAP_GATE_VERSION", "0.13.1")
     try:
         package = json.loads((root / "package.json").read_text())
         correct = package.get("name") == "@agile-team/wl-skills-gate" and package.get("version") == expected

package/templates/ci/jenkins-loader.groovy

@@ -2,6 +2,7 @@
 // Installed by Gate outside every project workspace. No shared Git repository.
 def adapter = null
 def target = null
+withEnv(["WL_NODE_BIN_DIR=${env.WL_NODE_BIN_DIR ?: '__WL_NODE_BIN_DIR__'}", "PATH+WLNODE=${env.WL_NODE_BIN_DIR ?: '__WL_NODE_BIN_DIR__'}"]) {
 try {
   wlGatePreflight(mode: 'node', gateRoot: '__WL_GATE_ROOT__', runtimeHash: '__WL_RUNTIME_HASH__')
   def routeDir = "wl-quality-route-${java.util.UUID.randomUUID().toString()}"
@@ -17,6 +18,7 @@ try {
   wlGateFailureNotice()
   throw failure
 }
+}
 def bootstrap = this
 // Return first: the caller releases the router executor before allocating a
 // business/signing Agent. This also works with a single executor on a node.

package/templates/ci/jenkins-native.groovy

@@ -53,6 +53,7 @@ def wlPrepareJobs(Map cfg) {
 }
 def call(Map cfg, def bootstrap) {
   node(cfg.agentLabel) {
+    withEnv(["WL_NODE_BIN_DIR=${env.WL_NODE_BIN_DIR ?: cfg.nodeBinDir ?: '/usr/bin'}", "PATH+WLNODE=${env.WL_NODE_BIN_DIR ?: cfg.nodeBinDir ?: '/usr/bin'}"]) {
     timeout(time: cfg.role == 'fleet' ? 120 : 30, unit: 'MINUTES') {
       try {
         if (cfg.role != 'job') {
@@ -140,6 +141,7 @@ node "$WL_APPROVED_GATE_CLI" automation --config "$WL_CENTRAL_CONFIG/automation-
         archiveArtifacts artifacts: '.wl-gate-bootstrap/**,wl-fleet-public/*,wl-bootstrap-public/*.json,review-delivery/**', allowEmptyArchive: true
       }
     }
+    }
   }
 }
 return this

package/templates/onboarding/backend/quality-tools.package.json

@@ -3,7 +3,7 @@
   "private": true,
   "engines": { "node": "^22.13.0 || >=24.0.0" },
   "devDependencies": {
-    "@agile-team/wl-skills-gate": "0.13.0",
+    "@agile-team/wl-skills-gate": "0.13.1",
     "@agile-team/wl-skills-bd": "0.41.1"
   }
 }

package/templates/quality/rules.lock.json

@@ -1,6 +1,6 @@
 {
   "lockVersion": 1,
-  "wl-skills-gate": "0.13.0",
+  "wl-skills-gate": "0.13.1",
   "tools": {
     "TS-TYPECHECK": "<填写 vue-tsc --version 的完整输出>",
     "FE-ESLINT": "<填写 eslint --version 的完整输出>"