@agile-team/wl-skills-ui 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,4 +1,13 @@
-# Changelog
+# Changelog
+
+## [1.20.0] - 2026-10-11
+
+- scan 严格校验已注册规则、范围与参数，CLI/MCP 使用同源选择器；非法请求零检查零任务记录。
+- 合法 pnpm/npm-link 本包规则与执行器纳入新鲜度证据，不扩展兄弟包或业务路径权限。
+- 解释、方案/步骤、背景引用与禁止检查的动作判定收敛；任务意图仍不授予业务写入权限。
+- notice 与 result.integration 暴露实际版本对齐，漂移返回 gap/ready=false；只读任务输入变化需重新判定，修改任务允许同 runId 复扫。
+- 本包外部依赖的只读证据核实身份与真实边界，累计快照预算和 Schema 同步，保持零兄弟包/Harness 运行时依赖。
+
 
 ## [1.19.0] - 2026-10-11
 

package/README.md

@@ -510,7 +510,7 @@ npx wl-ui doctor --project . --print-overrides
 
 ## 版本与进一步阅读
 
-当前 v1.19.0：公开集成协议 describe/request 统一信封（能力清单与路由语料经真实打包产物验证）、输入校验收口与 MCP 目录对齐真实 tools/list。v1.15.0：任务判定、真实执行/验证回执、实际检查范围和过期检测；Codex 原生薄入口按需加载 canonical Skill。确定性路由覆盖已发布目录与显式缺口，不保证识别所有自然语言。v1.14.0：明确独立能力边界，安装、更新、清理按本包贡献保护用户及其他包内容；共享文件采用单文件原子替换，支持历史路由与 `.clinerules` 目录迁移。v1.13.2：R044 审查多列表单超宽标签，R040 识别自定义 `stepper`，均供人工复核。v1.13.0：新增 `native-jh-ag` Profile、显式 Profile 兼容承诺与联邦 AG 依赖识别。
+当前 v1.20.0：公开集成协议 describe/request 统一信封（能力清单与路由语料经真实打包产物验证）、输入校验收口与 MCP 目录对齐真实 tools/list。v1.15.0：任务判定、真实执行/验证回执、实际检查范围和过期检测；Codex 原生薄入口按需加载 canonical Skill。确定性路由覆盖已发布目录与显式缺口，不保证识别所有自然语言。v1.14.0：明确独立能力边界，安装、更新、清理按本包贡献保护用户及其他包内容；共享文件采用单文件原子替换，支持历史路由与 `.clinerules` 目录迁移。v1.13.2：R044 审查多列表单超宽标签，R040 识别自定义 `stepper`，均供人工复核。v1.13.0：新增 `native-jh-ag` Profile、显式 Profile 兼容承诺与联邦 AG 依赖识别。
 
 - [版本摘要](docs/version-history.md)
 - [完整 Changelog](CHANGELOG.md)
@@ -544,3 +544,11 @@ npm run pack:dry
 `inventory.executors` 声明本包业务只读检查器、目标与参数 Schema；其适用条件由本包判定。外部适配器须核对同项目、同包、同版本、同 runId 的真实计划、新鲜度与允许动作，指定一个目标，不能扩大范围；支持规则子集的执行器不得选择计划外规则。多目标需拆分调用。五包和 Harness 均为可选组合，不新增兄弟包或 Harness 运行时依赖；卸下适配器后原 CLI/MCP 继续独立使用。
 
 样式规则检查使用 `scan`（支持计划内规则子集）；`check` 只核验接入完整性。技能触发词由本包 `bin/task-triggers.json` 维护并接受目录一致性检查。
+
+`scan/audit/fix` 的未知参数、重复值选项、空值、多余位置参数和不存在的规则选择器在检查或写入前拒绝，机读输出返回 `invalid-input`，不会形成成功检查记录。CLI 与 MCP 共用注册规则选择器，支持单个 ID、逗号列表与三位编号范围（例如 `R031-R037`）；用 `wl-ui rules list` 核对实际规则。Vue 解析错误仍不能被 `--only/--skip` 隐藏。`wl-ui scan --help` 只输出帮助，不启动扫描。
+
+### 任务反馈与执行边界
+
+编辑前展示实际 `notice` 的包版本、判定、动作、技能/规则、目标、runId、待检查项与版本对齐信息；解释/规划和明确禁止检查时不自动执行检查。`runtime=mismatch/invalid` 或 `planStale=true` 必须先同步本包或重新判定。只读 `inspect` 输入变化后重新 `task`；`apply` 完成正常业务修改后可用同 runId 做实际复扫，但规则、配置或版本变化仍需重新判定。
+
+单包只读取自身公开能力；多包复用同 runId 并各存各的证据。`matched/ready/ok=true` 仅说明判定或调用成功，是否完成以实际 `executionStatus/validationStatus/checkedFiles` 为准。未接入或不适用的项目不借父目录规则；宿主发现、模型读取、反馈展示没有真实证据时继续标记未验证。

package/bin/__tests__/external-store-evidence.test.mjs

@@ -0,0 +1,42 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { appendFileSync, cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+const repo = resolve(import.meta.dirname, "../..");
+test("external workspace store keeps own rule and execution evidence fresh or explicitly stale", () => {
+  const temporary = realpathSync(mkdtempSync(join(tmpdir(), "ui-external-store-")));
+  const project = join(temporary, "workspace/apps/admin");
+  const physical = join(temporary, "workspace/node_modules/.pnpm/ui-fixture/node_modules/@agile-team/wl-skills-ui");
+  try {
+    mkdirSync(project, { recursive: true });mkdirSync(physical, { recursive: true });
+    for (const file of ["bin", "scanner", "standards", "skills", "mcp", "SKILL.md", "package.json"]) cpSync(join(repo, file), join(physical, file), { recursive: true });
+    const pkg = JSON.parse(readFileSync(join(repo, "package.json"), "utf8"));
+    writeFileSync(join(project, "package.json"), JSON.stringify({ private: true, devDependencies: { [pkg.name]: pkg.version, vue: "^3.4.0" } }));
+    const logical = join(project, "node_modules", pkg.name);
+    mkdirSync(dirname(logical), { recursive: true });symlinkSync(relative(dirname(logical), physical), logical, "dir");
+    mkdirSync(join(project, "src"));writeFileSync(join(project, "src/Form.vue"), '<template><el-input size="small" /></template>');
+    const run = args => {
+      const result = spawnSync(process.execPath, [join(physical, "bin/wl-ui.js"), ...args], { cwd: project, encoding: "utf8", timeout: 30000 });
+      assert.equal(result.status, 0, result.stderr);return result.stdout;
+    };
+    run(["init", "--editor", "agents-generic", "--profile", "native-element", "--skills-only"]);
+    assert.equal(JSON.parse(run(["doctor-host", "--host", "codex", "--json"])).entryReadiness, "ready");
+    const plan = JSON.parse(run(["task", "检查表单样式", "--target", "src/Form.vue", "--json", "--run-id", "external-store"]));
+    assert.equal(plan.ready, true);assert.deepEqual(plan.selectedSkills, ["element/el-form"]);
+    const status = () => JSON.parse(run(["status", "--run-id", plan.runId, "--json"]));
+    const before = status();assert.equal(before.planStale, false);
+    const snapshot = before.records.find(record => record.kind === "task-decision").ruleSnapshot;
+    assert.ok(snapshot.targets.includes(`node_modules/${pkg.name}/standards/rules.json`));
+    assert.ok(snapshot.targets.includes(`node_modules/${pkg.name}/scanner/rules`));
+    run(["scan", "--target", "src/Form.vue", "--run-id", plan.runId, "--output", "summary"]);
+    assert.equal(status().stale, false);
+    const rules = join(physical, "standards/rules.json");const original = readFileSync(rules);
+    appendFileSync(rules, "\n");assert.equal(status().planStale, true);assert.equal(status().stale, true);
+    writeFileSync(rules, original);assert.equal(status().stale, false);
+    appendFileSync(join(physical, "scanner/rules/form.mjs"), "\n// isolated fixture change\n");
+    assert.equal(status().planStale, true);assert.equal(status().stale, true);
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+});

package/bin/integration-result.cjs

@@ -21,6 +21,7 @@ const SCHEMA = {
       properties: { packageName: nullableString, ruleId: { type: "string" }, legacyId: { type: "string" }, name: { type: "string" }, ruleVersion: nullableString, source: nullableString, kind: { type: "string" }, verification: { const: "unverified" } }, additionalProperties: false } },
     ready: { type: ["boolean", "null"] }, executionStatus: nullableString, validationStatus: nullableString,
     stale: { type: ["boolean", "null"] }, planStale: { type: ["boolean", "null"] },
+    runtime:{oneOf:[{type:'null'},{type:'object',required:['status'],properties:{status:{enum:['aligned','unverified','mismatch','invalid']}},additionalProperties:true}]},
   },
 };
 
@@ -35,6 +36,7 @@ function allowedExecutors(decision, executors) {
 }
 
 function resultReadiness(result, decision, status) {
+  if (result.planStale || decision.ready === false || status && !["matched", "baseline"].includes(status)) return false;
   if (typeof result.ready === "boolean") return result.ready;
   if (typeof decision.ready === "boolean") return decision.ready;
   return status ? ["matched", "baseline"].includes(status) && !(decision.missingInputs || []).length : null;
@@ -56,6 +58,8 @@ function decisionReadout(decision) {
 function targetReadout(result,input) { return strings(result.targets || input.targets || result.notice?.targets); }
 function projectIdentity(scope,result,input) { return path.resolve(scope?.projectRoot || result.projectRoot || result.root || input.projectRoot || process.cwd()); }
 
+function runtimeReadout(result) { return result.runtime || result.notice?.runtime || null; }
+
 function projectResult(result, input, config) {
   const decision = result.decision || result;
   const scope = result.currentScope || decision.scope || result.scope || null;
@@ -68,6 +72,7 @@ function projectResult(result, input, config) {
       projectRoot: projectIdentity(scope,result,input),
       ...executionState(result), decisionStatus: status, scope,
       ...decisionReadout(decision), targets: targetReadout(result,input), ready,
+      runtime: runtimeReadout(result),
       allowedExecutors: ready && scope?.status === "applicable" ? allowedExecutors(decision, config.executors || []) : [],
     },
   };

package/bin/task-integration.mjs

@@ -44,8 +44,23 @@ export function taskOptions(projectRoot, extra = {}) {
 }
 
 function projectEvidencePaths(projectRoot, candidates) {
-  return candidates.filter((candidate) => existsSync(candidate)).map((candidate) => relative(projectRoot, realpathSync(candidate)).replace(/\\/g, "/"))
-    .filter((rel) => rel && !rel.startsWith("../") && !isAbsolute(rel));
+  return candidates.filter((candidate) => existsSync(candidate)).map((candidate) => projectEvidencePath(projectRoot, candidate)).filter(Boolean);
+}
+
+function evidenceRelative(projectRoot, target) {
+  const value = relative(projectRoot, target);
+  return value && value !== ".." && !value.startsWith("../") && !value.startsWith("..\\") && !isAbsolute(value) ? value.replace(/\\/g, "/") : null;
+}
+
+function projectEvidencePath(projectRoot, candidate) {
+  const physical = realpathSync(candidate);
+  const local = evidenceRelative(projectRoot, physical);
+  if (local) return local;
+  const dependency = join(projectRoot, "node_modules", pkg.name);
+  if (!existsSync(dependency)) return null;
+  const internal = evidenceRelative(realpathSync(dependency), physical);
+  // The shared reader still verifies package identity and its own realpath boundary.
+  return internal ? `node_modules/${pkg.name}/${internal}` : null;
 }
 
 export function decideTask(input) {

package/bin/task-intent.cjs

@@ -5,25 +5,50 @@
  * Preserve the prompt; exclude explicit prohibitions and historical clauses from
  * capability scoring. Intent never substitutes for business write authorization.
  */
-const HISTORY = /(?:旧(?:需求|文档|任务|方案)|历史(?:需求|任务|记录)|上(?:次|一轮|轮)(?:需求|任务|要求|说)|(?:用户|客户|之前|以前).{0,8}(?:曾|原先)(?:说|要求|提)|曾(?:说|要求|提到)|previous(?:\s+(?:request|task))?|previously|used to|historical)/iu;
+const HISTORY = /^(?:旧(?:需求|文档|任务|方案)|历史(?:需求|任务|记录)|上(?:次|一轮|轮)|之前|以前|(?:用户|客户).{0,8}(?:曾|原先)(?:说|要求|提)|曾(?:说|要求|提到)|previous(?:\s+(?:request|task))?|previously|used to|historical)/iu;
 const CURRENT = /(?:本次|这次|此次|现在|当前任务|实际要求|改为|而是|this time|now|instead)/iu;
-const NEGATIVE = /^(?:(?:请|本次|这次|此次|暂时|暂|先|也|并且|且|同时|还)\s*)*(?:不要|不用|无需|禁止|别|不再|不需要|不必|不(?:做|用|画|生成|执行|运行|新增|实现|修改|改写|迁移|创建|编写|修复|自动)|do not\b|don't\b|without\b|skip\b)/iu;
+const NEGATIVE = /^(?:(?:请|本次|这次|此次|本轮|现在|这里|暂时|暂|先|也|并且|且|同时|还)\s*)*(?:不要|不用|无需|禁止|不得|不可|不能|切勿|别|不再|不需要|不必|不(?:做|用|画|生成|执行|运行|跑|检查|校验|扫描|测试|新增|实现|修改|改写|迁移|创建|编写|修复|自动)|跳过|do not\b|don't\b|don’t\b|without\b|skip\b)/iu;
 const APPLY = /生成|绘制|新增|增加|实现|修改|改写|编写|修复|整改|创建|迁移|重构|同步|统一|调整|优化|完善|补充|补[^，。;\n]{0,12}注释|\b(?:generate|draw|create|implement|modify|write|fix|repair|migrate|refactor|adjust|optimize|improve)\b/iu;
-const INSPECT = /检查|校验|验证|审查|审计|扫描|评审|核对|走查|梳理|\b(?:check|validate|verify|inspect|review|audit|scan)\b/iu;
-const DISCUSSION = /(?:(?:只|仅)(?:需要)?(?:分析|讨论|解释|说明|了解|咨询)|(?:先|暂时)(?:分析|讨论|解释|说明)|\b(?:only|just)\s+(?:explain|discuss|describe|analy[sz]e)\b)/iu;
+const INSPECT = /检查|校验|验证|审查|审计|扫描|评审|核对|走查|梳理|(?:运行|执行|跑)(?:自动)?(?:测试|质量门)|\b(?:check|validate|verify|inspect|review|audit|scan|run\s+(?:tests?|checks?|quality\s+gates?))\b/iu;
+const PREFIX = /^(?:(?:本次|这次|此次|现在|先|暂时|请问|请|麻烦你?|帮我|给我|我(?:希望|想要|想)|你(?:能否|可以|能不能)?|能否|可以|能不能|只|仅|需要)|(?:please|can you|could you|would you|only|just|first|this time|now|instead)\b)\s*/iu;
+const EXPLAIN = /^(?:解释|说明|介绍|讨论|分析|了解|咨询|如何|怎么|为什么|explain\b|describe\b|discuss\b|analy[sz]e\b|how\b|why\b)/iu;
+const BACKGROUND = /^(?:为了|为(?:了)?(?=修复|生成|实现|修改)|目的是|背景是|in order to\b|for the purpose of\b)/iu;
+const PLAN = /^(?:(?:列|制定|提供|给出|做)(?:一个|一份|个)?[^，。;\n]{0,40}(?:计划|步骤|方案)|(?:一个|一份)?[^，。;\n]{0,40}(?:计划|步骤)\s*$|[^，。;\n]{1,40}(?:做|拟定|制定)(?:一个|一份|个)?方案\s*$|plan\b)/iu;
+const QUOTES = new Map([['"','"'],["'","'"],["“","”"],["‘","’"],["「","」"],["『","』"]]);
+const CONTRAST = /^(?:但是|但|而是|改为|(?:本次|这次|此次|现在)(?=\s*(?:只|仅|请|要|需要|检查|审查|生成|修改|补充))|(?:but|instead|this time|now)\b)/iu;
 
 function normalized(text) { return String(text || "").normalize("NFKC").toLowerCase().trim(); }
 
+function quoteEnd(text,index,stack) {
+  const character = text[index];
+  if (stack.at(-1) === character) { stack.pop(); return true; }
+  if (!QUOTES.has(character) || character === "'" && /[a-z]/iu.test(text[index - 1] || '') && /[a-z]/iu.test(text[index + 1] || '')) return false;
+  stack.push(QUOTES.get(character)); return true;
+}
+
+function clausesFor(text) {
+  const parts = []; const stack = []; let raw = ''; let visible = '';
+  const finish = () => {if(raw.trim())parts.push({raw:raw.trim(),visible:visible.trim()});raw = '';visible = '';};
+  for(let index = 0;index < text.length;index += 1){
+    const character = text[index]; const outside = stack.length === 0;
+    if(outside && /[，,。；;!?！？\n]/u.test(character)){finish();continue;}
+    if(outside && raw.trim() && CONTRAST.test(text.slice(index)))finish();
+    const delimiter = quoteEnd(text,index,stack);
+    raw += character; visible += outside && !delimiter ? character : ' ';
+  }
+  finish();return parts;
+}
+
 function analyzeTask(task) {
   const original = String(task || "").normalize("NFKC");
-  // Current-request markers and contrast conjunctions start a new evidence clause.
-  const clauses = original.replace(/(但(?:是)?|而是|改为|(?:本次|这次|此次|现在)(?=\s*(?:只|仅|请|要|需要|检查|审查|生成|修改|补充)))/gu, "\n$1")
-    .split(/[，,。；;!?！？\n]+/u).map((part) => part.trim()).filter(Boolean);
+  const clauses = clausesFor(original);
   const excluded = [];
   const active = [];
-  for (const raw of clauses) {
-    const clause = raw.replace(/^(?:但是|但|而是|改为)\s*/u, "").trim();
-    if (HISTORY.test(clause) && !CURRENT.test(clause)) {
+  for (const {raw,visible} of clauses) {
+    const clause = raw.replace(/^(?:但是|不过|但|而是|改为)\s*/u, "").trim();
+    if (BACKGROUND.test(visible)) {
+      excluded.push({ kind: "background", text: clause });
+    } else if (HISTORY.test(visible) && !CURRENT.test(visible)) {
       excluded.push({ kind: "historical", text: clause });
     } else if (NEGATIVE.test(clause)) {
       excluded.push({ kind: "prohibited", text: clause });
@@ -33,12 +58,31 @@ function analyzeTask(task) {
   return {schemaVersion:1,activeText,excluded,action:actionEvidence(activeText,excluded)};
 }
 
+function requestText(text) {
+  let value = text.trim(); let next = value.replace(PREFIX,'');
+  while(next !== value){value = next;next = value.replace(PREFIX,'');}
+  return value;
+}
+
+function clauseMode(text) {
+  const request = requestText(text);
+  if(EXPLAIN.test(request))return 'explain';
+  if(PLAN.test(request))return 'plan';
+  if(APPLY.test(text))return 'apply';
+  if(INSPECT.test(text))return 'inspect';
+  return 'unspecified';
+}
+
+function stopsChecks(text) {
+  const chinese = /^(?:(?:请|本次|这次|此次|本轮|现在|这里|暂时|暂|先|也|并且|且|同时|还)\s*)*(?:不要|不用|无需|禁止|不得|不可|不能|切勿|别|不再|不需要|不必|跳过|不)(?:再|自动|进行|做)?(?:执行|运行|跑)?(?:任何|所有|自动)?(?:工具|命令|检查|校验|测试|扫描|审查)?(?:代码|规范|质量门|任何检查|自动检查)?\s*$/u;
+  const english = /^(?:please\s+)?(?:do not|don't|don’t|skip|without)\s+(?:execute|run|check|validate|verify|inspect|review|audit|scan)(?:\s+(?:any|all|automatic|the))*(?:\s+(?:tools?|commands?|checks?|tests?|code))?\s*$/iu;
+  return chinese.test(text) || english.test(text);
+}
+
 function actionEvidence(activeText, excluded) {
-  const discussion = DISCUSSION.test(activeText);
-  const mode = discussion ? "explain" : /(?:只|仅|先)?(?:列|制定|提供|给出|做)(?:一个|一份)?[^，。;\n]{0,40}计划|\bplan\b/iu.test(activeText) ? "plan"
-    : APPLY.test(activeText) ? "apply" : INSPECT.test(activeText) ? "inspect"
-      : /解释|说明|讨论|咨询|\b(?:explain|discuss|describe)\b/iu.test(activeText) ? "explain" : "unspecified";
-  const genericStop = excluded.some((item) => item.kind === "prohibited" && /(?:暂|先|不要|不)(?:自动)?(?:执行|运行)(?:任何|所有)?(?:工具|命令|检查|校验)?\s*$|\b(?:do not|don't|skip)\s+(?:execute|run)\s+(?:(?:any|all)\s+)?(?:tools?|commands?|checks?)\s*$/iu.test(item.text));
+  const modes = clausesFor(activeText).map(({raw}) => clauseMode(raw));
+  const mode = ['apply','inspect','plan','explain'].find(value => modes.includes(value)) || 'unspecified';
+  const genericStop = excluded.some((item) => item.kind === "prohibited" && stopsChecks(item.text));
   return {
     mode, checksAllowed: !genericStop && ["inspect", "apply"].includes(mode), businessWritesAuthorized: false,
       authorization: "intent-is-not-business-write-authorization",

package/bin/task-observability.cjs

@@ -160,7 +160,31 @@ function projectPath(root, relative) {
   return inspectAncestors(root, path.resolve(root, relative));
 }
 
-function readEvidencePath(root, relative) {
+function insidePath(root,target) {
+  const relative = path.relative(root,target);
+  return !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`);
+}
+
+function ownDependencyRoot(root,packageName) {
+  if(!Object.hasOwn(STORAGE,packageName || ''))throw new Error('WL read evidence escapes project root');
+  const installed = fs.realpathSync(path.join(root,'node_modules',packageName));
+  const manifest = fs.realpathSync(path.join(installed,'package.json'));
+  if(!insidePath(installed,manifest))throw new Error('WL dependency metadata escapes its own package');
+  const metadata = JSON.parse(fs.readFileSync(manifest,'utf8'));
+  if(metadata.name !== packageName || typeof metadata.version !== 'string' || !metadata.version.trim())throw new Error('WL dependency identity is invalid');
+  return installed;
+}
+
+function authorizeRead(root,requested,physical,packageName) {
+  if(insidePath(root,physical))return root;
+  const logical = path.join(root,'node_modules',packageName || '__unowned__');
+  if(!insidePath(logical,requested))throw new Error('WL read evidence escapes project root');
+  const dependency = ownDependencyRoot(root,packageName);
+  if(!insidePath(dependency,physical))throw new Error('WL read evidence escapes its own dependency');
+  return dependency;
+}
+
+function readEvidencePath(root, relative,packageName) {
   if (typeof relative !== "string" || !relative) throw new Error("WL evidence path is required");
   const requested = path.resolve(root, relative);
   const lexical = path.relative(root, requested);
@@ -172,16 +196,44 @@ function readEvidencePath(root, relative) {
     ancestor = path.dirname(ancestor);
   }
   const physical = path.resolve(fs.realpathSync(ancestor), ...suffix);
-  const resolved = path.relative(root, physical);
-  if (resolved.startsWith("..") || path.isAbsolute(resolved)) throw new Error("WL read evidence escapes project root");
+  authorizeRead(root,requested,physical,packageName);
   return physical;
 }
 
 function captureReadEvidence(options, targets) {
   const root = fs.realpathSync(path.resolve(options.projectRoot || process.cwd()));
   const requested = strings(targets);
-  const snapshot = captureSnapshot({ projectRoot: root, targets: requested.map((target) => path.relative(root, readEvidencePath(root, target)) || ".") });
-  return { ...snapshot, targets: requested, resolution: "project-internal-realpath" };
+  const batches = [];let fileCount = 0;let bytes = 0;const seen = new Set();
+  for(const target of requested){
+    const physical = readEvidencePath(root,target,options.packageName);
+    if(seen.has(physical))continue;
+    seen.add(physical);
+    const batch = readSnapshot(root,target,options.packageName,{maxFiles:1000 - fileCount,maxBytes:16 * 1024 * 1024 - bytes});
+    batches.push(batch);fileCount += batch.files.length;bytes += batch.files.reduce((sum,file) => sum + file.bytes,0);
+  }
+  const snapshot = mergeReadSnapshots(batches);
+  return { ...snapshot, targets: requested, resolution: "authorized-read-realpath" };
+}
+
+function readSnapshot(root,target,packageName,limits) {
+  const physical = readEvidencePath(root,target,packageName);
+  const base = authorizeRead(root,path.resolve(root,target),physical,packageName);
+  const snapshot = captureSnapshot({projectRoot:base,targets:[path.relative(base,physical) || '.'],...limits});
+  if(base !== root){
+    const prefix = `node_modules/${packageName}/`;
+    for(const item of [...snapshot.files,...snapshot.omitted])item.path = prefix + item.path;
+  }
+  return snapshot;
+}
+
+function mergeReadSnapshots(batches) {
+  const files = [...new Map(batches.flatMap(batch => batch.files).map(file => [file.path,file])).values()].sort((left,right) => left.path.localeCompare(right.path));
+  const omitted = batches.flatMap(batch => batch.omitted); let bytes = 0;
+  const bounded = files.filter((file,index) => {
+    if(index >= 1000 || bytes + file.bytes > 16 * 1024 * 1024){omitted.push({path:file.path,reason:'snapshot-budget'});return false;}
+    bytes += file.bytes;return true;
+  });
+  return {files:bounded,omitted,complete:omitted.length === 0,sha256:digest(JSON.stringify({files:bounded,omitted}))};
 }
 
 function snapshotFile(root, target, state) {
@@ -190,7 +242,7 @@ function snapshotFile(root, target, state) {
   if (stat.isSymbolicLink()) { state.omitted.push({ path: relative, reason: "symlink" }); return; }
   if (stat.isDirectory()) { snapshotDirectory(root, target, state); return; }
   if (!stat.isFile()) { state.omitted.push({ path: relative, reason: "not-file" }); return; }
-  if (state.files.length >= 1000 || state.bytes + stat.size > 16 * 1024 * 1024) { state.omitted.push({ path: relative, reason: "snapshot-budget" }); return; }
+  if (state.files.length >= state.maxFiles || state.bytes + stat.size > state.maxBytes) { state.omitted.push({ path: relative, reason: "snapshot-budget" }); return; }
   state.files.push({ path: relative, sha256: digest(fs.readFileSync(target)), bytes: stat.size });
   state.bytes += stat.size;
 }
@@ -207,7 +259,7 @@ function snapshotDirectory(root, target, state) {
 
 function captureSnapshot(options = {}) {
   const root = fs.realpathSync(path.resolve(options.projectRoot || process.cwd()));
-  const state = { files: [], omitted: [], bytes: 0 };
+  const state = { files: [], omitted: [], bytes: 0, maxFiles: options.maxFiles ?? 1000, maxBytes: options.maxBytes ?? 16 * 1024 * 1024 };
   for (const relative of strings(options.targets)) {
     const target = projectPath(root, relative);
     if (!fs.existsSync(target)) { state.omitted.push({ path: relative, reason: "missing" }); continue; }
@@ -302,6 +354,10 @@ function checkedFileEvidence(options, files) {
   return captureReadEvidence(options, targets);
 }
 
+function verificationCoverage(input, rules, config) {
+  return { ...input, complete: [input, rules, config].every(snapshot => snapshot.complete) };
+}
+
 function finishExecution(handle, result = {}) {
   const { options, metadata } = handle;
   const checks = (result.checks || []).map(normalizeCheck);
@@ -316,7 +372,7 @@ function finishExecution(handle, result = {}) {
   const record = {
     ...baseRecord(metadata, "tool-finished"), executionId: handle.record.eventId, executionStartedAt: handle.record.recordedAt, tool: handle.record.tool, targets: handle.record.targets,
     executionStatus: exitCode === 0 ? "completed" : "failed", exitCode, durationMs: Date.now() - handle.startedAt,
-    validationStatus: validationState(result.validationStatus, checks, after, changed), checks,
+    validationStatus: validationState(result.validationStatus, checks, verificationCoverage(after, ruleSnapshot, configSnapshot), changed), checks,
     checkedFiles: checkedSnapshot.files, checkedSnapshot, checkedScopeSource: Array.isArray(result.checkedFiles) ? "executor" : "unreported",
     summary: safeMetadata(result.summary || {}), inputSnapshot: after, inputBefore: handle.record.inputSnapshot,
     changedDuringCheck: changed, artifacts: captureSnapshot({ projectRoot: options.projectRoot, targets: result.artifacts || [] }).files,
@@ -376,7 +432,7 @@ function snapshotsFresh(snapshots, options) {
 }
 
 function currentSnapshot(snapshot, options) {
-  return snapshot.resolution === "project-internal-realpath" ? captureReadEvidence(options, snapshot.targets) : captureSnapshot({ projectRoot: options.projectRoot, targets: snapshot.targets });
+  return ["project-internal-realpath","authorized-read-realpath"].includes(snapshot.resolution) ? captureReadEvidence(options, snapshot.targets) : captureSnapshot({ projectRoot: options.projectRoot, targets: snapshot.targets });
 }
 
 function pendingChecks(plan, tools) {
@@ -409,17 +465,19 @@ function statusForRecords(records, options) {
 
 function validationContext(plan, tools, options) {
   const pending = pendingChecks(plan, tools);
-  const outdatedChecker = Boolean(options.packageVersion) && [...tools, ...plan ? [plan] : []].some((record) => record.packageVersion !== options.packageVersion);
+  const runtime = inspectRuntime(options.projectRoot,options);
+  const outdatedChecker = ['mismatch','invalid'].includes(runtime.status) || Boolean(options.packageVersion) && [...tools, ...plan ? [plan] : []].some((record) => record.packageVersion !== options.packageVersion);
   const planStale = Boolean(plan) && !planInputsFresh(plan, options);
   const stale = outdatedChecker || planStale || tools.some((record) => isFresh(record, options) === false);
   const verifiers = tools.filter((record) => record.checks.length || record.validationStatus !== "unverified");
   const scopeGaps = uncoveredScope(plan, verifiers, options);
   const unresolvedDecision = Boolean(plan) && ["gap", "ambiguous", "needs-context"].includes(plan.decision.status);
   const executionOrderUnverified = ambiguousExecutionOrder(tools);
-  return { validationStatus: summarizeValidation(verifiers, pending, stale, unresolvedDecision || scopeGaps.length > 0 || executionOrderUnverified), pendingChecks: pending, stale, outdatedChecker, planStale, scopeGaps, unresolvedDecision, executionOrderUnverified };
+  return { validationStatus: summarizeValidation(verifiers, pending, stale, unresolvedDecision || scopeGaps.length > 0 || executionOrderUnverified), pendingChecks: pending, stale, outdatedChecker, planStale, scopeGaps, unresolvedDecision, executionOrderUnverified,runtime };
 }
 
 function planInputsFresh(plan, options) {
+  if(plan.decision.action?.mode === 'inspect' && !snapshotsFresh([plan.inputSnapshot],options))return false;
   if (!snapshotsFresh([plan.ruleSnapshot, plan.configSnapshot], options)) return false;
   if (!plan.decision.scope?.fingerprint) return true;
   const current = projectScope.resolveScope({ projectRoot: options.projectRoot, packageName: options.packageName });
@@ -429,7 +487,7 @@ function planInputsFresh(plan, options) {
 function uncoveredScope(plan, tools, options) {
   if (!plan) return [];
   const root = fs.realpathSync(path.resolve(options.projectRoot || process.cwd()));
-  const rulePaths = new Set([...(plan.ruleSnapshot?.targets || []), ...strings(plan.decision.requiredFiles)].map((target) => readEvidencePath(root, target)));
+  const rulePaths = new Set([...(plan.ruleSnapshot?.targets || []), ...strings(plan.decision.requiredFiles)].map((target) => readEvidencePath(root, target,options.packageName)));
   const targets = plan.targets.filter((target) => !rulePaths.has(readEvidencePath(root, target)));
   if (!targets.length) return [];
   const current = captureSnapshot({ projectRoot: root, targets });
@@ -491,8 +549,8 @@ function listGaps(options) {
   return [...grouped.values()];
 }
 
-function inspectHostFile(root, relative, maximum) {
-  const file = readEvidencePath(root, relative);
+function inspectHostFile(root, relative, maximum,packageName) {
+  const file = readEvidencePath(root, relative,packageName);
   if (!fs.existsSync(file)) return { path: relative, status: "missing" };
   const stat = fs.statSync(file);
   return { path: relative, status: stat.isFile() ? "present" : "not-file", bytes: stat.size, oversized: stat.size > maximum, sha256: stat.isFile() ? digest(fs.readFileSync(file)) : null };
@@ -502,9 +560,9 @@ function doctorHost(options) {
   const root = fs.realpathSync(path.resolve(options.projectRoot || process.cwd()));
   const { scope } = projectScope.resolveScope({ projectRoot: root, packageName: options.packageName });
   const maximum = options.maxInstructionBytes || 32768;
-  const entries = strings(options.entryFiles).map((relative) => inspectHostFile(root, relative, maximum));
-  const skills = strings(options.skillPaths).map((relative) => inspectHostFile(root, relative, Infinity));
-  const gateway = options.gatewayPath ? inspectHostFile(root, options.gatewayPath, Infinity) : null;
+  const entries = strings(options.entryFiles).map((relative) => inspectHostFile(root, relative, maximum,options.packageName));
+  const skills = strings(options.skillPaths).map((relative) => inspectHostFile(root, relative, Infinity,options.packageName));
+  const gateway = options.gatewayPath ? inspectHostFile(root, options.gatewayPath, Infinity,options.packageName) : null;
   const warnings = entries.filter((entry) => entry.oversized).map((entry) => `${entry.path} 超过 ${maximum} 字节参考预算；请核对宿主实际配置与内容加载范围`);
   const runtime = inspectRuntime(root, options);
   warnings.push(...runtime.warnings);
@@ -515,8 +573,8 @@ function doctorHost(options) {
 function hostReady(gateway, skills, entries, runtime) {
   return gateway?.status === "present" && skills.length > 0 && skills.every((skill) => skill.status === "present") && entries.every((entry) => entry.status === "present" && !entry.oversized) && ["aligned", "unverified"].includes(runtime.status);
 }
-function runtimeVersion(root, relative, diagnostics) {
-  try { const value = JSON.parse(fs.readFileSync(readEvidencePath(root, relative), "utf8")).version; if (typeof value !== "string" || !value.trim()) throw new Error("version 必须是非空字符串"); return value; }
+function runtimeVersion(root, relative, diagnostics,packageName) {
+  try { const value = JSON.parse(fs.readFileSync(readEvidencePath(root, relative,packageName), "utf8")).version; if (typeof value !== "string" || !value.trim()) throw new Error("version 必须是非空字符串"); return value; }
   catch (error) { if (error.code !== "ENOENT") diagnostics.push(`${relative}: ${error.message}`); return null; }
 }
 function declaredDependency(root, packageName) {
@@ -532,7 +590,7 @@ function inspectRuntime(root, options) {
   const manifestPath = { kit: ".wl-skills-manifest.json", design: ".wl-skills-design/state.json", test: ".wl-skills-test/manifest.json" }[key] || `.wl-skills-${key}-manifest.json`;
   const diagnostics = [];
   const distributedVersion = runtimeVersion(root, manifestPath, diagnostics);
-  const localVersion = runtimeVersion(root, `node_modules/${options.packageName}/package.json`, diagnostics);
+  const localVersion = runtimeVersion(root, `node_modules/${options.packageName}/package.json`, diagnostics,options.packageName);
   const declaredVersion = declaredDependency(root, options.packageName);
   const mismatch = runtimeMismatch([distributedVersion, localVersion, options.packageVersion], declaredVersion, localVersion);
   const state = distributedVersion ? "aligned" : "unverified";
@@ -560,6 +618,7 @@ function prepareNoticeDecision(record,options) {
   const item = record.decision || record;
   record.packageName ||= options.packageName;
   record.packageVersion ||= options.packageVersion;
+  prepareRuntimeNotice(record, item, options);
   item.action ||= taskIntent.analyzeTask(record.task || item.task || "").action;
   const details = new Map((item.ruleDetails || []).map((entry) => [entry.id, entry]));
   item.ruleRefs ||= strings([...strings(item.requiredRules), ...details.keys()]).map((id) => {
@@ -570,6 +629,23 @@ function prepareNoticeDecision(record,options) {
   });
   return item;
 }
+
+function prepareRuntimeNotice(record, item, options) {
+  if (!options.projectRoot || !options.packageName) return;
+  record.runtime = inspectRuntime(options.projectRoot, options);
+  runtimeReadiness(item, record.runtime);
+}
+function runtimeReadiness(item,runtime) {
+  if(item.scope?.status !== 'applicable' || !['mismatch','invalid'].includes(runtime.status))return;
+  const code = `runtime-${runtime.status}`;
+  item.routingStatus ||= item.status;
+  item.status = 'gap';item.ready = false;
+  const reason = '本包安装资产、本地依赖与当前执行器版本未对齐，暂不执行';
+  item.reason = reason;item.reasons = strings([...(item.reasons || []),reason]);
+  item.missingInputs = strings([...(item.missingInputs || []),'本包一致的安装资产与执行器版本']);
+  item.gaps ||= [];
+  if(!item.gaps.some(gap => gap.code === code))item.gaps.push({code,reason,suggestion:'在目标项目核对本包依赖和安装清单，正常 update 后重新判定；不需安装兄弟包'});
+}
 function attachNotice(record, options = {}) {
   const item = prepareNoticeDecision(record,options);
   record.notice = {
@@ -580,6 +656,7 @@ function attachNotice(record, options = {}) {
     gaps: (item.gaps || []).map((gap) => ({ reason: safeText(gap.reason), suggestion: safeText(gap.suggestion) })),
     ...noticeScope(record, options, item), displayEvidence: "unverified",
     action: item.action, ruleRefs: item.ruleRefs,
+    runtime:record.runtime || null,warnings:record.runtime?.warnings || [],
   };
   return record;
 }
@@ -598,7 +675,12 @@ function formatDecision(record) {
   const notice = record.notice || attachNotice({ ...record }).notice;
   const label = { baseline: "基础约束", ambiguous: "候选需确认", gap: "规则缺口", "not-applicable": "不适用", "needs-context": "缺少上下文" }[notice.decision] || "待判定";
   const identity = notice.packageName ? `${notice.packageName.replace("@agile-team/wl-skills-", "")}@${notice.packageVersion || "未知"}；` : "";
-  return `[WL ${notice.decision}] ${identity}${notice.skills.join("、") || label}；${notice.reason}` + `\n动作=${notice.action.mode}；允许自动检查=${notice.action.checksAllowed}；业务写入遵循原授权契约` + `\n适用规则：${noticeRuleText(notice)}；范围：${notice.targets.slice(0, 3).join("、") || "未指定目标，检查范围待确认"}` + noticePlanText(notice) + noticeGapText(notice);
+  return `[WL ${notice.decision}] ${identity}${notice.skills.join("、") || label}；${notice.reason}` + `\n动作=${notice.action.mode}；允许自动检查=${notice.action.checksAllowed}；业务写入遵循原授权契约` + `\n适用规则：${noticeRuleText(notice)}；范围：${notice.targets.slice(0, 3).join("、") || "未指定目标，检查范围待确认"}` + noticePlanText(notice) + noticeGapText(notice) + runtimeText(notice.runtime);
+}
+
+function runtimeText(runtime) {
+  if(!runtime)return '';
+  return `\n版本对齐=${runtime.status}；安装资产=${runtime.distributedVersion || '未分发'}；本地依赖=${runtime.localVersion || '未安装'}；当前执行器=${runtime.runningVersion || '未知'}${runtime.warnings.length ? '；' + runtime.warnings.join('；') : ''}`;
 }
 
 function formatStatus(status) {

package/bin/task-observability.schema.json

@@ -397,7 +397,7 @@
           "pattern": "^[a-f0-9]{64}$"
         },
         "resolution": {
-          "const": "project-internal-realpath"
+          "enum": ["project-internal-realpath", "authorized-read-realpath"]
         }
       }
     },

package/docs/task-observability.md

@@ -23,3 +23,5 @@ wl-ui status --run-id <runId> --json
 UI scan 记录规则真实回调次数及 SFC_PARSE 错误；解析错误不受规则过滤隐藏。fast/fallback 仅提取区块，未验证 SFC 语法；compiler SFC 解析也不替代脚本 TypeScript 类型编译、浏览器视觉和业务语义复核。UI Vite 插件只检查依赖组合，明确列出源码 scan 尚未执行。运行时 guard 的存在不证明静态规范已通过。
 
 当前 CLI 检查回执覆盖 scan / audit / check / fix / all 与 Vite 依赖检查，本包 MCP 记录实际调用；其他 CLI snapshot / drift / exempt / contract / 脚手架保留既有产物与日志，不自动等同于 UI 源码检查。未由执行器报告实际文件的操作，其检查范围明确未知；不能用输入目录快照或成功退出补造文件覆盖。
+
+规则选择器来自实际注册表；未知 ID、格式错误和无界范围在扫描前拒绝。CLI 的未知参数、重复值选项、空值与额外位置参数同样不会启动检查或写入回执；JSON/summary/compact-v2 输出返回 `invalid-input` 与 `not-executed`。MCP 的错误调用返回 `isError=true` 与真实失败记录，保留同 runId，`checkedFiles` 与源码检查为空。已注册的规则选择和语法错误检查继续按原有契约执行。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 双模式、任务路由与真实检查回执（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",

package/scanner/cli-input.mjs

@@ -0,0 +1,46 @@
+import { parseArgs } from "node:util";
+import { expandRuleSelector } from "./rule-selector.mjs";
+
+const ACTIONS = { snapshot: ["list", "rollback", "diff", "clean"], exempt: ["init"] };
+const MACHINE_OUTPUTS = new Set(["json", "summary", "compact-v2"]);
+
+function validatePositionals(command, positionals) {
+  const actions = ACTIONS[command];
+  if ((!actions && positionals.length) || positionals.length > 1 || actions && positionals.length && !actions.includes(positionals[0])) {
+    throw new Error(`${command} 不接受位置参数 ${positionals.join(" ")}；请使用该命令声明的选项或操作`);
+  }
+}
+
+function validateValues(values, tokens, options) {
+  const seen = new Set();
+  for (const token of tokens.filter(item => item.kind === "option")) {
+    if (options[token.name]?.type !== "string") continue;
+    if (seen.has(token.name)) throw new Error(`--${token.name} 只接受一个值，不静默覆盖前一个参数`);
+    seen.add(token.name);
+    if (!token.value.trim()) throw new Error(`--${token.name} 缺少有效值`);
+  }
+  for (const name of ["project", "target"]) {
+    if (values[name]?.startsWith("-")) throw new Error(`--${name} 缺少有效路径`);
+  }
+}
+
+function requestedOutput(args) {
+  const equals = args.find(argument => argument.startsWith("--output="));
+  const index = args.indexOf("--output");
+  return equals ? equals.slice("--output=".length) : index >= 0 ? args[index + 1] : undefined;
+}
+
+export function parseScannerInput(command, args, options, registered) {
+  try {
+    const parsed = parseArgs({ args, options, strict: true, allowPositionals: true, tokens: true });
+    validatePositionals(command, parsed.positionals);
+    validateValues(parsed.values, parsed.tokens, options);
+    for (const name of ["only", "skip"]) if (parsed.values[name]) expandRuleSelector(parsed.values[name], registered);
+    return parsed;
+  } catch (error) {
+    const message = error.message || String(error);
+    console.error(`[wl-scan] 无效参数：${message}`);
+    if (MACHINE_OUTPUTS.has(requestedOutput(args))) console.log(JSON.stringify({ ok: false, error: { code: "invalid-input", message }, executionStatus: "not-executed", validationStatus: "unverified", checkedFiles: [] }));
+    process.exit(1);
+  }
+}

package/scanner/engine.mjs

@@ -10,22 +10,10 @@ import { loadExemptConfig } from "./exempt.mjs";
 import { collectChangedVueFiles } from "./changed.mjs";
 import { parseVueSfc, SFC_PARSER_MODES } from "./sfc-parser.mjs";
 import { resolveProjectProfile } from "../standards/profiles-loader.mjs";
+import { expandRuleSelector } from "./rule-selector.mjs";
 
 export function expandRuleRange(input = "") {
-  const set = new Set();
-  for (const part of input.split(",").map((value) => value.trim()).filter(Boolean)) {
-    const match = part.match(/^(R)(\d+)-(R)?(\d+)$/i);
-    if (!match) {
-      set.add(part.toUpperCase());
-      continue;
-    }
-    const start = Number.parseInt(match[2], 10);
-    const end = Number.parseInt(match[4], 10);
-    for (let id = Math.min(start, end); id <= Math.max(start, end); id++) {
-      set.add(`R${String(id).padStart(3, "0")}`);
-    }
-  }
-  return set;
+  return input === "" ? new Set() : expandRuleSelector(input, getRules().map(rule => rule.id));
 }
 
 /**
@@ -191,6 +179,8 @@ export function filterIssues(issues, { layer, vendor, mode, only, skip } = {}) {
 }
 
 export function scanProject(options = {}) {
+  // CLI and MCP share the same selector boundary; never scan first and discard errors later.
+  for (const selector of [options.only, options.skip]) if (selector) expandRuleRange(selector);
   const projectRoot = resolve(options.projectRoot || options.project || ".");
   const targetDir = resolve(projectRoot, options.target || "src");
   const changedFallback = options.changedFallback || "error";

package/scanner/index.mjs

@@ -27,7 +27,8 @@
  */
 import { readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve, relative } from "node:path";
-import { parseArgs } from "node:util";
+import { parseScannerInput } from "./cli-input.mjs";
+import { expandRuleSelector } from "./rule-selector.mjs";
 import { getRules } from "./rules/index.mjs";
 import { generateReport } from "./report.mjs";
 import { checkIntegration } from "./integration.mjs";
@@ -67,9 +68,8 @@ if (args.length > 0 && SUBCOMMANDS.has(args[0])) {
 }
 const isAudit = subcommand === "audit";
 
-const { values } = parseArgs({
-  args,
-  options: {
+const REGISTERED_RULES = getRules().map(rule => rule.id);
+const { values, positionals } = parseScannerInput(subcommand, args, {
     target: { type: "string", default: "./src" },
     project: { type: "string", default: "." },
     output: { type: "string", default: "markdown" },
@@ -98,9 +98,17 @@ const { values } = parseArgs({
     limit: { type: "string", default: "100" },
     cursor: { type: "string", default: "0" },
     "run-id": { type: "string" },
+    help: { type: "boolean", short: "h" },
   },
-  strict: false,
-});
+  REGISTERED_RULES);
+
+if (values.help) {
+  console.log(`wl-ui ${subcommand} [--project <root>] [--target <file|directory>]\n` +
+    "scan/audit: --only R001,R006 | --skip R031-R037 | --output json|summary|compact-v2|markdown | --fail-on-error | --run-id <id>\n" +
+    "fix: --dry-run | --plan-hash <hash>; snapshot: list|rollback|diff|clean; exempt: init\n" +
+    "每个值选项只接受一个值；未知参数、操作和规则会在检查或写入前拒绝。");
+  process.exit(0);
+}
 
 // ── 公共：扫描逻辑 ──────────────────────────────────────────────────────
 if (!SFC_PARSER_MODES.includes(values.parser)) {
@@ -155,20 +163,7 @@ function runScan(
 
 // ── 公共：规则范围展开（R031-R037 → R031,R032,...,R037）────────────────────
 function expandRuleRange(input) {
-  const set = new Set();
-  for (const part of input.split(",").map((s) => s.trim())) {
-    const rangeMatch = part.match(/^(R)(\d+)-(R)?(\d+)$/i);
-    if (rangeMatch) {
-      const start = parseInt(rangeMatch[2]);
-      const end = parseInt(rangeMatch[4]);
-      for (let i = Math.min(start, end); i <= Math.max(start, end); i++) {
-        set.add("R" + String(i).padStart(3, "0"));
-      }
-    } else {
-      set.add(part.toUpperCase());
-    }
-  }
-  return set;
+  return expandRuleSelector(input, REGISTERED_RULES);
 }
 
 // ── 公共：按 layer / vendor / mode 过滤 ─────────────────────────────────────
@@ -320,7 +315,7 @@ if (subcommand === "check") {
 }
 
 if (subcommand === "exempt") {
-  const sub = args[0] || "init";
+  const sub = positionals[0] || "init";
   if (sub === "init") {
     const { existsSync } = await import("node:fs");
     const projectRoot = resolve(values.project);
@@ -412,7 +407,7 @@ if (subcommand === "drift") {
 
 if (subcommand === "snapshot") {
   const projectRoot = resolve(values.project);
-  const sub = args[0] || "list";
+  const sub = positionals[0] || "list";
   if (sub === "list") {
     const snaps = listSnapshots(projectRoot);
     if (snaps.length === 0) {

package/scanner/rule-selector.mjs

@@ -0,0 +1,17 @@
+/** Expand bounded, registered selectors before scans, records or writes begin. */
+export function expandRuleSelector(input, registered) {
+  if (typeof input !== "string") throw new Error("规则选择器必须是字符串");
+  const selected = new Set();
+  const known = new Set([...registered, "SFC_PARSE"]);
+  for (const part of input.split(",").map(value => value.trim().toUpperCase())) {
+    const range = part.match(/^R(\d{3})-(?:R)?(\d{3})$/u);
+    if (range) {
+      const start = Number(range[1]);
+      const end = Number(range[2]);
+      for (let index = Math.min(start, end); index <= Math.max(start, end); index++) selected.add(`R${String(index).padStart(3, "0")}`);
+    } else selected.add(part);
+  }
+  const missing = [...selected].filter(id => !known.has(id));
+  if (missing.length) throw new Error(`不存在或格式无效的规则：${missing.join("、") || "空规则"}；请用 wl-ui rules list 核对规则 ID`);
+  return selected;
+}