@agile-team/wl-skills-ui 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.16.0] - 2026-10-08
+
+### Added
+
+- 新增公开集成协议 describe/request 统一信封：能力清单与路由语料经真实打包产物验证，供外部宿主与适配器按公开契约接入。
+
+### Fixed
+
+- 输入校验补齐：context 为 null、targets 为空等边界输入返回可解释拒绝，不再产生歧义结果。
+- MCP 目录对齐真实 `tools/list` 的 18 项，修复目录声明与实际暴露不一致。
+
 ## [1.15.0] - 2026-10-07
 
 ### Added

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-ui
 
-**企业级 UI 一致性与 AI 精确治理工具包 v1.15.0** — 面向 Vue 3 + Element Plus 的设计令牌、能力 Profile、样式皮肤、页面骨架、运行时能力、静态扫描、确定性修复、AI Skill、MCP 与脱敏 UI 模板契约。
+**企业级 UI 一致性与 AI 精确治理工具包 v1.16.0** — 面向 Vue 3 + Element Plus 的设计令牌、能力 Profile、样式皮肤、页面骨架、运行时能力、静态扫描、确定性修复、AI Skill、MCP 与脱敏 UI 模板契约。
 
 它把“视觉统一、问题识别、机械修复、项目适配和样例沉淀”拆成可验证、可组合的工程能力。脚本、规则和 MCP 先完成确定性工作，AI 只处理业务语义与人工决策，从而减少重复读源码、上下文 token 和误修改。
 
@@ -94,6 +94,23 @@ CLI、安装器和 MCP 无需安装其他 wl-skills 包或统一客户端即可
 
 `init` 新插入的 HTML tokens link 使用独立边界标记并登记贡献，`clean` 只移除未修改的本包链接，保留项目其他 HTML。历史未标记的链接缺少归属证据，升级时仍作为项目配置保留；SCSS 与 runtime 接入只给出建议，不自动修改或认领项目已有 import。
 
+## 公开集成协议 v1
+
+供 harness、客户端或其他编排层以统一 JSON 入口调用本包判定与状态能力（业务执行仍走本包 CLI/MCP，不因协议新增兄弟包依赖）。
+
+```bash
+wl-ui protocol describe --json                      # 能力目录、五操作映射、请求/响应 Schema、错误码
+wl-ui protocol request --input-file request.json --json
+```
+
+- 操作：`route` / `explain`（只读判定）、`task`（判定并持久化计划，尚未执行）、`status`（回查本包执行回执）、`doctor-host`（宿主入口静态诊断）。
+- 请求字段：`protocolVersion`(1)、`operation`、`requestId`、`runId`、`projectRoot`、`task`、`targets`、`skill`、`host`+ `profile`。
+- 统一信封：`{ ok, result | error, diagnostics }`；机器结果与诊断分离；非法输入在触达执行器前判 `invalid-input`，不写入任何记录。
+- 错误码：`unsupported-protocol` / `unknown-operation` / `missing-input` / `invalid-input` / `internal-error`；请求失败（exit 2）时 stdout 仍为可解析 JSON 信封。
+- **`ok=true` 只表示协议调用成功，不代表业务验证通过**；业务状态以 `result` 内 `validationStatus` / `executionStatus` 为准（仅计划时为 `unverified` / `not-executed`）。
+- 副作用：仅 `task` 写入本包自己的 runs 目录（见 describe 中各操作 `sideEffects`）；其余操作只读。
+- 协议实现为本包内置的同源快照 `integration-protocol.cjs`，五包一致；跨包一致性由 conformance `integration-protocol.check.cjs` 验收。
+
 ## 能力地图
 
 | 层级 | 能力 | 典型内容 | 是否需要业务源码 |
@@ -483,7 +500,7 @@ npx wl-ui doctor --project . --print-overrides
 
 ## 版本与进一步阅读
 
-当前 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.16.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)

package/bin/__tests__/protocol-cli.test.mjs

@@ -0,0 +1,122 @@
+/**
+ * protocol-cli.test.mjs — ui 公开集成协议统一信封与接线测试
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const here = path.dirname(fileURLToPath(import.meta.url));
+const { protocol, runOperation } = await import("../protocol-cli.mjs");
+const pkg = require("../../package.json");
+const BIN = path.join(here, "..", "wl-ui.js");
+
+function tempRoot() {
+  return mkdtempSync(path.join(tmpdir(), "wl-ui-protocol-"));
+}
+
+test("describe 返回协议版本、能力目录与五个统一操作", () => {
+  const described = protocol.describe();
+  assert.equal(described.protocolVersion, 1);
+  assert.equal(described.package, pkg.name);
+  assert.ok(Array.isArray(described.capabilities) && described.capabilities.length > 0);
+  assert.deepEqual(described.operations.map((operation) => operation.id), ["route", "explain", "task", "status", "doctor-host"]);
+  assert.ok(described.errorCodes.includes("unsupported-protocol"));
+});
+
+test("route 只读判定返回六类状态之一", () => {
+  const envelope = protocol.request({ operation: "route", projectRoot: tempRoot(), task: "统一这个页面的表格视觉" }, runOperation);
+  assert.equal(envelope.ok, true);
+  const status = envelope.result.decision ? envelope.result.decision.status : envelope.result.status;
+  assert.ok(["matched", "baseline", "ambiguous", "gap", "not-applicable", "needs-context"].includes(status));
+});
+
+test("task 持久化返回 runId 且 status 可回查", () => {
+  const root = tempRoot();
+  const planned = protocol.request({ operation: "task", projectRoot: root, task: "扫描 src/views 视觉问题" }, runOperation);
+  assert.equal(planned.ok, true);
+  assert.ok(planned.result.runId);
+  const status = protocol.request({ operation: "status", projectRoot: root, runId: planned.result.runId }, runOperation);
+  assert.equal(status.ok, true);
+  assert.equal(status.result.runId, planned.result.runId);
+  assert.equal(status.result.executionStatus, "not-executed");
+});
+
+test("doctor-host 按指定 host 诊断", () => {
+  const envelope = protocol.request({ operation: "doctor-host", projectRoot: tempRoot(), host: "claude" }, runOperation);
+  assert.equal(envelope.ok, true);
+  assert.equal(envelope.result.host, "claude");
+});
+
+test("协议错误码：missing-input / unknown-operation / invalid-input / unsupported-protocol", () => {
+  assert.equal(protocol.request({ operation: "route" }, runOperation).error.code, "missing-input");
+  assert.equal(protocol.request({ operation: "skin" }, runOperation).error.code, "unknown-operation");
+  assert.equal(protocol.request(42, runOperation).error.code, "invalid-input");
+  assert.equal(protocol.request({ protocolVersion: 3, operation: "route", task: "x" }, runOperation).error.code, "unsupported-protocol");
+});
+
+test("边界输入校验：非法类型在触达执行器前判 invalid-input（独立复验缺陷回归）", () => {
+  const invalidPayloads = [
+    { operation: "task", task: true },
+    { operation: "task", task: { text: "bad" } },
+    { operation: "task", task: "检查目标", targets: [null, 42, {}] },
+    { operation: "route", task: "检查目标", projectRoot: 42 },
+    { operation: "task", task: "检查目标", runId: {} },
+  ];
+  for (const payload of invalidPayloads) {
+    const envelope = protocol.request(payload, () => { throw new Error("不应触达执行器"); });
+    assert.equal(envelope.ok, false);
+    assert.equal(envelope.error.code, "invalid-input");
+    assert.ok(envelope.error.field);
+  }
+});
+
+test("CLI 缺 --input-file 时 stdout 输出 missing-input JSON 信封", () => {
+  const run = spawnSync(process.execPath, [BIN, "protocol", "request"], { encoding: "utf8" });
+  assert.equal(run.status, 2);
+  const envelope = JSON.parse(run.stdout);
+  assert.equal(envelope.ok, false);
+  assert.equal(envelope.error.code, "missing-input");
+  assert.equal(envelope.error.field, "input-file");
+});
+
+test("CLI protocol describe / request 全链路", () => {
+  const describe = spawnSync(process.execPath, [BIN, "protocol", "describe"], { encoding: "utf8" });
+  assert.equal(describe.status, 0);
+  assert.equal(JSON.parse(describe.stdout).package, "@agile-team/wl-skills-ui");
+  const root = tempRoot();
+  const file = path.join(root, "req.json");
+  const { writeFileSync } = require("node:fs");
+  writeFileSync(file, JSON.stringify({ operation: "doctor-host", projectRoot: root, host: "copilot" }));
+  const request = spawnSync(process.execPath, [BIN, "protocol", "request", "--input-file", file], { encoding: "utf8" });
+  assert.equal(request.status, 0);
+  assert.equal(JSON.parse(request.stdout).result.host, "copilot");
+});
+
+
+test("context null 判 invalid-input 且零写入（CLI 回归）", () => {
+  const root = tempRoot();
+  const file = path.join(root, "req.json");
+  const { writeFileSync, readdirSync } = require("node:fs");
+  writeFileSync(file, JSON.stringify({ operation: "task", projectRoot: root, task: "扫描 src/views 视觉问题", runId: "ctx-null", context: null }));
+  const run = spawnSync(process.execPath, [BIN, "protocol", "request", "--input-file", file], { encoding: "utf8" });
+  assert.equal(run.status, 2);
+  const envelope = JSON.parse(run.stdout);
+  assert.equal(envelope.ok, false);
+  assert.equal(envelope.error.code, "invalid-input");
+  assert.equal(envelope.error.field, "context");
+  assert.equal(readdirSync(root).filter((name) => name.startsWith(".")).length, 0, "不得写入任何任务记录");
+});
+
+test("targets 空数组与 Schema 一致（运行时接受空范围）", () => {
+  const root = tempRoot();
+  const envelope = protocol.request({ operation: "route", projectRoot: root, task: "扫描 src/views 视觉问题", targets: [] }, runOperation);
+  assert.equal(envelope.ok, true);
+  const described = protocol.describe();
+  assert.equal(described.schemas.request.properties.targets.minItems, undefined, "Schema 不得要求非空 targets");
+});

package/bin/__tests__/protocol-evidence.test.mjs

@@ -0,0 +1,50 @@
+/**
+ * protocol-evidence.test.mjs — ui 证据闭环严格断言（不得兜底通过）
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+const { protocol, runOperation } = await import("../protocol-cli.mjs");
+
+function tempRoot() {
+  return mkdtempSync(path.join(tmpdir(), "wl-ui-evidence-"));
+}
+
+test("status 严格回查同一 runId：字段精确、不兜底", () => {
+  const root = tempRoot();
+  const planned = protocol.request({ operation: "task", projectRoot: root, task: "统一表格视觉", runId: "evidence-run-a" }, runOperation);
+  assert.equal(planned.ok, true);
+  assert.equal(planned.result.runId, "evidence-run-a");
+  assert.equal(planned.result.executionStatus, "not-executed");
+  assert.equal(planned.result.validationStatus, "unverified");
+  const status = protocol.request({ operation: "status", projectRoot: root, runId: "evidence-run-a" }, runOperation);
+  assert.equal(status.result.runId, "evidence-run-a");
+  assert.equal(status.result.executionStatus, "not-executed");
+});
+
+test("混用 runId 不得串记录", () => {
+  const root = tempRoot();
+  protocol.request({ operation: "task", projectRoot: root, task: "任务A统一表格视觉", runId: "evidence-run-a" }, runOperation);
+  protocol.request({ operation: "task", projectRoot: root, task: "任务B统一表格视觉", runId: "evidence-run-b" }, runOperation);
+  const statusB = protocol.request({ operation: "status", projectRoot: root, runId: "evidence-run-b" }, runOperation);
+  assert.equal(statusB.result.runId, "evidence-run-b");
+  assert.equal(JSON.stringify(statusB.result).includes("任务A"), false);
+});
+
+test("不存在的 runId 不得伪造成功记录", () => {
+  const root = tempRoot();
+  const status = protocol.request({ operation: "status", projectRoot: root, runId: "no-such-run" }, runOperation);
+  const serialized = JSON.stringify(status.result);
+  assert.equal(serialized.includes('"validationStatus":"passed"'), false);
+  assert.equal(serialized.includes('"executionStatus":"completed"'), false);
+});
+
+test("空检查集不得判定为通过", () => {
+  const root = tempRoot();
+  const planned = protocol.request({ operation: "task", projectRoot: root, task: "统一表格视觉", runId: "empty-run" }, runOperation);
+  assert.notEqual(planned.result.validationStatus, "passed");
+  assert.equal(planned.result.executionStatus, "not-executed");
+});

package/bin/__tests__/protocol-routing-cases.json

@@ -0,0 +1,105 @@
+[
+  {
+    "task": "统一表格视觉",
+    "skill": "element/el-table"
+  },
+  {
+    "task": "查询表单密集审计",
+    "skill": "element/el-form"
+  },
+  {
+    "task": "弹窗样式对齐",
+    "skill": "element/el-dialog"
+  },
+  {
+    "task": "状态标签颜色统一",
+    "skill": "element/el-tag"
+  },
+  {
+    "task": "列表布局骨架",
+    "skill": "layouts/list-page"
+  },
+  {
+    "task": "AG Grid 适配",
+    "skill": "vendors/ag-grid"
+  },
+  {
+    "task": "UI扫描",
+    "skill": "ops/scan"
+  },
+  {
+    "task": "UI修复统一视觉",
+    "skill": "ops/fix"
+  },
+  {
+    "task": "UI迁移迁移tokens",
+    "skill": "ops/migrate"
+  },
+  {
+    "task": "设计令牌接入消除颜色硬编码",
+    "skill": "runtime/design-tokens"
+  },
+  {
+    "task": "写诗",
+    "skill": null,
+    "status": "not-applicable"
+  },
+  {
+    "task": "生成测试用例",
+    "skill": null,
+    "status": "needs-context"
+  },
+  {
+    "task": "检查",
+    "skill": null,
+    "status": "needs-context"
+  },
+  {
+    "task": "整理页签和卡片组件",
+    "skill": "element/component-family"
+  },
+  {
+    "task": "详情布局整改",
+    "skill": "layouts/detail-page"
+  },
+  {
+    "task": "调整表单弹窗布局",
+    "skill": "layouts/form-dialog"
+  },
+  {
+    "task": "树列表布局",
+    "skill": "layouts/tree-list"
+  },
+  {
+    "task": "做一次UI审计",
+    "skill": "ops/audit"
+  },
+  {
+    "task": "runtime迁移",
+    "skill": "runtime/migration"
+  },
+  {
+    "task": "样式统一风格对齐",
+    "skill": "runtime/style-align"
+  },
+  {
+    "task": "BaseTable 适配",
+    "skill": "vendors/base-table"
+  },
+  {
+    "task": "C组件用法审计",
+    "skill": "vendors/c-components"
+  },
+  {
+    "task": "自定义封装组件治理",
+    "skill": "vendors/custom-wrappers"
+  },
+  {
+    "task": "jh组件接入",
+    "skill": "vendors/jh-components"
+  },
+  {
+    "task": "未知封装组件排查",
+    "skill": "vendors/unknown-wrapper"
+  }
+]

package/bin/__tests__/protocol-routing.test.mjs

@@ -0,0 +1,63 @@
+/**
+ * protocol-routing.test.mjs — ui 路由准确性逐技能语料（预期经人工复核冻结）
+ * ui 是依赖型包：安装态通过真实打包产物 npm 安装到隔离项目验证。
+ */
+import { test, before } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const { protocol, runOperation } = await import("../protocol-cli.mjs");
+const cases = JSON.parse((await import("node:fs")).readFileSync(path.join(here, "protocol-routing-cases.json"), "utf8"));
+const PKG_ROOT = path.join(here, "..", "..");
+
+const state = { installedRoot: null, tarball: null };
+
+function tempRoot() {
+  return mkdtempSync(path.join(tmpdir(), "wl-ui-routing-"));
+}
+
+function routeAt(projectRoot, task) {
+  return protocol.request({ operation: "route", projectRoot, task }, runOperation);
+}
+
+before(() => {
+  const packDir = tempRoot();
+  const pack = spawnSync("npm", ["pack", "--pack-destination", packDir, "--ignore-scripts"], { cwd: PKG_ROOT, encoding: "utf8", timeout: 180000 });
+  assert.equal(pack.status, 0, pack.stderr);
+  state.tarball = path.join(packDir, pack.stdout.trim().split("\n").pop());
+  state.installedRoot = tempRoot();
+  assert.equal(spawnSync("npm", ["init", "-y"], { cwd: state.installedRoot, encoding: "utf8" }).status, 0);
+  const install = spawnSync("npm", ["i", state.tarball], { cwd: state.installedRoot, encoding: "utf8", timeout: 180000 });
+  assert.equal(install.status, 0, install.stderr);
+}, 600000);
+
+for (const item of cases) {
+  const expectedBare = item.skill ? "gap" : item.status;
+  const expectedInstalled = item.installedStatus || (item.skill ? "matched" : item.status);
+
+  test(`未安装：「${item.task}」→ ${expectedBare}${item.skill ? ` + ${item.skill}` : ""}`, () => {
+    const envelope = routeAt(tempRoot(), item.task);
+    assert.equal(envelope.ok, true);
+    const decision = envelope.result.decision || envelope.result;
+    assert.equal(decision.status, expectedBare);
+    if (item.skill) assert.ok(decision.selectedSkills.includes(item.skill), `应选中 ${item.skill}，实际 ${decision.selectedSkills}`);
+    else assert.equal((decision.selectedSkills || []).length, 0);
+  });
+
+  test(`已安装（真实打包产物）：「${item.task}」→ ${expectedInstalled}${item.skill ? ` + ${item.skill}` : ""}`, () => {
+    const envelope = routeAt(state.installedRoot, item.task);
+    assert.equal(envelope.ok, true);
+    const decision = envelope.result.decision || envelope.result;
+    assert.equal(decision.status, expectedInstalled);
+    if (item.skill) assert.ok(decision.selectedSkills.includes(item.skill));
+  });
+}
+
+test.after(() => {
+  if (state.tarball) rmSync(path.dirname(state.tarball), { recursive: true, force: true });
+});

package/bin/integration-protocol.cjs

@@ -0,0 +1,283 @@
+"use strict";
+
+/**
+ * integration-protocol.cjs — 五包统一公开集成协议 v1（单源快照）
+ *
+ * 由 kit-internal/conformance/scripts/sync-support.cjs 分发到各包，各包不得修改本文件；
+ * 包特定能力目录、操作映射与执行器在各包的 protocol 接线文件中提供。
+ *
+ * 协议约定：
+ * - describe：返回能力目录、协议版本、操作清单、输入输出约束与错误码；
+ *   request/envelope Schema 按各包操作定义动态生成，与运行时校验一致。
+ * - request：所有字段在执行前完成类型校验；非法输入返回 invalid-input，不触发执行器、
+ *   不写入任何记录。非法的 operation/requestId 不回显到信封（保持 string|null）。
+ * - 信封结构互斥：ok=true 必有 result 且无 error；ok=false 必有 error 且无 result。
+ * - 本协议只统一判定、解释、任务记录、状态查询与宿主诊断；业务执行仍走各包原有 CLI/MCP。
+ */
+
+const PROTOCOL_VERSION = 1;
+const SUPPORTED_VERSIONS = [1];
+const ERROR_CODES = ["unsupported-protocol", "unknown-operation", "missing-input", "invalid-input", "internal-error"];
+const OPTIONAL_STRING_FIELDS = ["requestId", "runId", "projectRoot", "skill", "host", "type", "domain", "profile"];
+
+const STRING_FIELD_SCHEMA = { type: "string", minLength: 1, pattern: "\\S" };
+const ERROR_SCHEMA = {
+  type: "object",
+  required: ["code", "message"],
+  properties: {
+    code: { type: "string", enum: ERROR_CODES },
+    message: { type: "string", minLength: 1 },
+    field: { oneOf: [STRING_FIELD_SCHEMA, { type: "array", items: STRING_FIELD_SCHEMA, minItems: 1 }] },
+    supportedProtocolVersions: { type: "array", items: { type: "integer" }, minItems: 1 },
+    availableOperations: { type: "array", items: STRING_FIELD_SCHEMA, minItems: 1 },
+  },
+  additionalProperties: true,
+};
+const CONTEXT_FIELD_SCHEMA = {
+  type: "object",
+  properties: {
+    signals: { type: "array", items: STRING_FIELD_SCHEMA },
+    domainRelevant: { type: "boolean" },
+  },
+  additionalProperties: true,
+};
+
+function envelopeSchema(packageName) {
+  const stringOrNull = { type: ["string", "null"] };
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: `wl-skills protocol envelope v1 (${packageName})`,
+    type: "object",
+    required: ["protocolVersion", "package", "packageVersion", "operation", "requestId", "ok", "diagnostics"],
+    properties: {
+      protocolVersion: { type: "integer", const: 1 },
+      package: { type: "string" },
+      packageVersion: stringOrNull,
+      operation: stringOrNull,
+      requestId: stringOrNull,
+      ok: { type: "boolean" },
+      result: { type: "object", description: "各包原执行器结果；业务状态以其中 executionStatus/validationStatus 等字段为准" },
+      error: ERROR_SCHEMA,
+      diagnostics: { type: "array", items: { type: "string" } },
+    },
+    oneOf: [
+      { properties: { ok: { const: true }, result: { type: "object" } }, required: ["result"], not: { required: ["error"] } },
+      { properties: { ok: { const: false }, error: ERROR_SCHEMA }, required: ["error"], not: { required: ["result"] } },
+    ],
+  };
+}
+
+function operationCondition(operation) {
+  const clauses = [];
+  if (operation.required.length > 0) clauses.push({ required: [...operation.required] });
+  if (operation.requireAny) clauses.push(...operation.requireAny.map((field) => ({ required: [field] })));
+  if (clauses.length === 0) return null;
+  return {
+    if: { properties: { operation: { const: operation.id } }, required: ["operation"] },
+    then: clauses.length === 1 ? clauses[0] : { anyOf: clauses },
+  };
+}
+
+function requestSchema(config) {
+  const {operations} = config;
+  const conditional = operations.map(operationCondition).filter(Boolean);
+  return {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    title: `wl-skills protocol request v1 (${config.packageName})`,
+    type: "object",
+    required: ["operation"],
+    properties: {
+      protocolVersion: { type: "integer", const: 1 },
+      operation: { type: "string", enum: operations.map((operation) => operation.id) },
+      requestId: STRING_FIELD_SCHEMA,
+      runId: STRING_FIELD_SCHEMA,
+      projectRoot: STRING_FIELD_SCHEMA,
+      task: STRING_FIELD_SCHEMA,
+      targets: { type: "array", items: STRING_FIELD_SCHEMA, description: "空数组表示空范围（与运行时既有语义一致）" },
+      skill: STRING_FIELD_SCHEMA,
+      host: STRING_FIELD_SCHEMA,
+      type: STRING_FIELD_SCHEMA,
+      domain: STRING_FIELD_SCHEMA,
+      profile: STRING_FIELD_SCHEMA,
+      context: CONTEXT_FIELD_SCHEMA,
+    },
+    ...(conditional.length > 0 ? { allOf: conditional } : {}),
+  };
+}
+
+function isEmptyValue(value) {
+  return value === undefined || value === null || (typeof value === "string" && value.trim() === "");
+}
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+function assertValidOperation(operation) {
+  if (!operation.id || typeof operation.summary !== "string") throw new Error(`操作定义不完整：${JSON.stringify(operation)}`);
+  if (typeof operation.readOnly !== "boolean") throw new Error(`操作 ${operation.id} 缺少 readOnly 声明`);
+  if (!Array.isArray(operation.required) || !Array.isArray(operation.optional)) throw new Error(`操作 ${operation.id} 缺少 required/optional 输入声明`);
+  if (operation.requireAny !== undefined && !Array.isArray(operation.requireAny)) throw new Error(`操作 ${operation.id} 的 requireAny 必须是字符串数组`);
+  if (typeof operation.mapping !== "string") throw new Error(`操作 ${operation.id} 缺少原 CLI 映射说明`);
+}
+
+function assertValidConfig(config) {
+  if (!config || typeof config !== "object") throw new Error("integration protocol 需要配置对象");
+  if (!config.packageName) throw new Error("integration protocol 配置缺少 packageName");
+  if (!Array.isArray(config.operations) || config.operations.length === 0) throw new Error("integration protocol 配置缺少 operations");
+  config.operations.forEach(assertValidOperation);
+}
+
+function createProtocol(config) {
+  assertValidConfig(config);
+
+  function base(operation, requestId) {
+    return {
+      protocolVersion: PROTOCOL_VERSION,
+      package: config.packageName,
+      packageVersion: config.packageVersion || null,
+      operation: isNonEmptyString(operation) ? operation : null,
+      requestId: isNonEmptyString(requestId) ? requestId : null,
+    };
+  }
+
+  function fail(operation, requestId, code, message, extra) {
+    return { ...base(operation, requestId), ok: false, error: { code, message, ...(extra || {}) }, diagnostics: [] };
+  }
+
+  function invalidField(input, field, expected) {
+    return fail(input.operation, input.requestId, "invalid-input", `字段 ${field} 非法：应为${expected}`, { field });
+  }
+
+  function validateContextField(input) {
+    const {context} = input;
+    if (context === null || typeof context !== "object" || Array.isArray(context)) return invalidField(input, "context", "非 null 对象（signals: string[] / domainRelevant: boolean）");
+    if (context.signals !== undefined && (!Array.isArray(context.signals) || context.signals.some((item) => !isNonEmptyString(item)))) {
+      return invalidField(input, "context.signals", "非空字符串数组");
+    }
+    if (context.domainRelevant !== undefined && typeof context.domainRelevant !== "boolean") return invalidField(input, "context.domainRelevant", "布尔值");
+    return null;
+  }
+
+function validateStringFields(input) {
+  for (const field of OPTIONAL_STRING_FIELDS) {
+    if (input[field] !== undefined && !isNonEmptyString(input[field])) return invalidField(input, field, "非空字符串");
+  }
+  if (input.task !== undefined && !isNonEmptyString(input.task)) return invalidField(input, "task", "非空字符串");
+  return null;
+}
+
+function validateTargetsField(input) {
+  if (input.targets === undefined) return null;
+  if (!Array.isArray(input.targets)) return invalidField(input, "targets", "字符串数组");
+  if (input.targets.some((item) => !isNonEmptyString(item))) return invalidField(input, "targets", "非空字符串元素数组");
+  return null;
+}
+
+function validateFieldTypes(input) {
+  if (!isNonEmptyString(input.operation)) return invalidField(input, "operation", "非空字符串");
+  const stringError = validateStringFields(input);
+  if (stringError) return stringError;
+  const targetsError = validateTargetsField(input);
+  if (targetsError) return targetsError;
+  if (input.context !== undefined) {
+    const contextError = validateContextField(input);
+    if (contextError) return contextError;
+  }
+  return null;
+}
+
+  function unsupportedVersionError(input) {
+    if (input.protocolVersion === undefined || SUPPORTED_VERSIONS.includes(input.protocolVersion)) return null;
+    return fail(input.operation, input.requestId, "unsupported-protocol", `不支持的协议版本：${input.protocolVersion}`, { supportedProtocolVersions: [...SUPPORTED_VERSIONS] });
+  }
+
+  function findOperation(input) {
+    const operation = config.operations.find((item) => item.id === input.operation);
+    if (operation) return { operation };
+    return { error: fail(input.operation, input.requestId, "unknown-operation", `未知操作：${isNonEmptyString(input.operation) ? input.operation : "(缺失或非法)"}`, { availableOperations: config.operations.map((item) => item.id) }) };
+  }
+
+  function missingInputError(input, operation) {
+    const missingField = operation.required.find((field) => isEmptyValue(input[field]));
+    if (missingField !== undefined) {
+      return fail(operation.id, input.requestId, "missing-input", `操作 ${operation.id} 缺少必要输入：${missingField}`, { field: missingField });
+    }
+    if (operation.requireAny && !operation.requireAny.some((field) => !isEmptyValue(input[field]))) {
+      return fail(operation.id, input.requestId, "missing-input", `操作 ${operation.id} 需要以下输入至少之一：${operation.requireAny.join(" / ")}`, { field: [...operation.requireAny] });
+    }
+    return null;
+  }
+
+  function validateRequest(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return { error: fail(null, null, "invalid-input", "request 必须是 JSON 对象") };
+    }
+    const versionError = unsupportedVersionError(input);
+    if (versionError) return { error: versionError };
+    const typeError = validateFieldTypes(input);
+    if (typeError) return { error: typeError };
+    const found = findOperation(input);
+    if (found.error) return found;
+    const { operation } = found;
+    const inputError = missingInputError(input, operation);
+    if (inputError) return { error: inputError };
+    return { operation };
+  }
+
+  function buildInventory(config) {
+    const inventory = config.inventory || {};
+    return {
+      skills: inventory.skills || [],
+      taskTypes: inventory.taskTypes || [],
+      commands: inventory.commands || [],
+      mcpTools: inventory.mcpTools || [],
+      loadErrors: inventory.loadErrors || [],
+      note: "业务执行仍走各包原 CLI/MCP；inventory 只声明公开调用映射与入口，不改变执行归属；loadErrors 非空表示目录派生存在异常，不得忽略",
+    };
+  }
+
+  function buildConstraints(config) {
+    return {
+      ...(config.constraints || {}),
+      instructionOnly: "未提供 programmatic 执行入口的能力均为指令指导型，由宿主/AI 按各包技能流程执行并提供证据",
+      evidence: "request 返回的判定与状态来自各包自身记录；宿主是否加载、读取、调用以宿主证据为准，本协议不代为宣称",
+      okSemantics: "ok=true 仅表示协议调用成功（判定/记录/查询完成）；业务验证状态以 result 内的 validationStatus/executionStatus 等字段为准",
+    };
+  }
+
+  return {
+    PROTOCOL_VERSION,
+    SUPPORTED_VERSIONS,
+    ERROR_CODES,
+
+    describe() {
+      return {
+        ...base(null, null),
+        capabilities: config.capabilities || [],
+        operations: config.operations.map((operation) => ({ ...operation })),
+        inventory: buildInventory(config),
+        schemas: { request: requestSchema(config), envelope: envelopeSchema(config.packageName) },
+        constraints: buildConstraints(config),
+        errorCodes: [...ERROR_CODES],
+      };
+    },
+
+    request(input, runOperation) {
+      const { operation, error } = validateRequest(input);
+      if (error) return error;
+      const diagnostics = [];
+      try {
+        const result = runOperation(operation.id, input, diagnostics) ?? {};
+        return { ...base(operation.id, input.requestId), ok: true, result, diagnostics };
+      } catch (thrown) {
+        diagnostics.push(String((thrown && thrown.message) || thrown));
+        const envelope = fail(operation.id, input.requestId, "internal-error", "操作执行异常，详见 diagnostics");
+        envelope.diagnostics = diagnostics;
+        return envelope;
+      }
+    },
+  };
+}
+
+module.exports = { createProtocol, PROTOCOL_VERSION, SUPPORTED_VERSIONS, ERROR_CODES };

package/bin/protocol-cli.mjs

@@ -0,0 +1,134 @@
+/**
+ * protocol-cli.mjs — ui 的公开集成协议接线（薄层）
+ *
+ * 协议实现来自快照 bin/integration-protocol.cjs（单源 conformance/support，勿改）；
+ * 本文件只提供 ui 的能力目录、操作映射，并复用 task-integration 的原执行器。
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { runTaskAction, taskCatalog } from "./task-integration.mjs";
+
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const capabilitiesDocument = require("./capabilities.json");
+const { createProtocol } = require("./integration-protocol.cjs");
+
+const BIN = "wl-ui";
+const OPERATIONS = [
+  { id: "route", summary: "只读任务判定：视觉/样式域技能、约束、歧义与缺口", readOnly: true, required: ["task"], optional: ["targets", "profile", "skill", "projectRoot"], sideEffects: "无写入", mapping: `${BIN} route --text "<task>"` },
+  { id: "explain", summary: "解释本次任务判定（只读，不记录）", readOnly: true, required: ["task"], optional: ["targets", "projectRoot"], sideEffects: "无写入", mapping: `${BIN} explain --text "<task>"` },
+  { id: "task", summary: "判定并持久化任务计划（尚未执行扫描或修复）", readOnly: false, required: ["task"], optional: ["runId", "targets", "profile", "projectRoot"], sideEffects: "写入 .wl-skills-ui/runs/ 下本包任务记录", mapping: `${BIN} task --text "<task>" [--run-id <id>]` },
+  { id: "status", summary: "读取本包执行/校验记录与新鲜度", readOnly: true, required: [], optional: ["runId", "projectRoot"], sideEffects: "无写入", mapping: `${BIN} status [--run-id <id>]` },
+  { id: "doctor-host", summary: "宿主入口静态诊断（不证明宿主已加载）", readOnly: true, required: [], optional: ["host", "projectRoot"], sideEffects: "无写入", mapping: `${BIN} doctor-host [--host <host>]` },
+];
+
+function buildInventory() {
+  const commands = [
+    { name: "init", args: "[--project <path>] [--editor <id>] [--profile <id>] [--skills-only] [--dry-run]", summary: "写入编辑器规则与技能", execution: "programmatic", sideEffects: "写入目标项目编辑器规则目录" },
+    { name: "update", args: "[--project <path>] [--editor <id|all>] [--force] [--dry-run]", summary: "更新已安装 rules/MCP/提示", execution: "programmatic", sideEffects: "按 manifest 更新" },
+    { name: "diff", args: "[--project <path>]", summary: "对比安装与 manifest", execution: "programmatic", sideEffects: "无" },
+    { name: "clean", args: "[--project <path>] [--dry-run]", summary: "清理本包安装文件", execution: "programmatic", sideEffects: "删除本包登记文件" },
+    { name: "scan", args: "[--project <path>] [--profile <id>]", summary: "R 规则扫描", execution: "programmatic", sideEffects: "无（报告输出）" },
+    { name: "audit", args: "[--project <path>]", summary: "审计汇总", execution: "programmatic", sideEffects: "无" },
+    { name: "check", args: "[--project <path>]", summary: "扫描+回执记录", execution: "programmatic", sideEffects: "写 .wl-skills-ui/runs/" },
+    { name: "fix", args: "--run-id <id> --rule <id> [--confirm]", summary: "确定性修复（快照/回滚）", execution: "programmatic", sideEffects: "写源文件（确认制+快照回滚）" },
+    { name: "snapshot", args: "/ drift / exempt", summary: "漂移基线管理", execution: "programmatic", sideEffects: "写基线文件" },
+    { name: "contract", args: "<extract|validate|match>", summary: "ui-contract 提取/校验/匹配", execution: "programmatic", sideEffects: "extract 写契约文件" },
+    { name: "doctor", args: "[--project <path>]", summary: "项目接入诊断", execution: "programmatic", sideEffects: "无" },
+    { name: "task", args: "\"任务\" [--run-id <id>]", summary: "判定并持久化任务计划", execution: "programmatic", sideEffects: "写 .wl-skills-ui/runs/" },
+    { name: "route", args: "\"任务\"", summary: "只读判定", execution: "programmatic", sideEffects: "无" },
+    { name: "explain", args: "\"任务\"", summary: "只读判定解释", execution: "programmatic", sideEffects: "无" },
+    { name: "status", args: "[--run-id <id>]", summary: "读取本包回执", execution: "programmatic", sideEffects: "无" },
+    { name: "doctor-host", args: "[--host <name>]", summary: "宿主入口静态诊断", execution: "programmatic", sideEffects: "无" },
+    { name: "protocol", args: "describe | request --input-file <file>", summary: "本公开集成协议", execution: "programmatic", sideEffects: "见操作声明" },
+  ];
+  const skills = [];
+  const loadErrors = [];
+  try {
+    for (const skill of taskCatalog()) {
+      skills.push({ id: skill.id, description: skill.description, triggers: skill.triggers, status: skill.status, entry: skill.path, execution: "instructional" });
+    }
+  } catch (error) {
+    loadErrors.push(`skills 加载失败：${error.message}`);
+  }
+  // 与 mcp/server.js tools/list 对齐的 18 项（由 readiness 探针持续校验数量与名称一致）
+  const mcpTools = [
+    { name: "wl_ui_task", summary: "判定并持久化 UI 任务计划", write: "persist" },
+    { name: "wl_ui_route", summary: "只读任务判定", write: "readonly" },
+    { name: "wl_ui_explain", summary: "只读判定解释", write: "readonly" },
+    { name: "wl_ui_status", summary: "读取执行回执", write: "readonly" },
+    { name: "wl_ui_doctor_host", summary: "宿主入口静态诊断", write: "readonly" },
+    { name: "wl_ui_check", summary: "执行 UI 检查并记录回执", write: "guarded" },
+    { name: "wl_ui_scan", summary: "R 规则扫描", write: "readonly" },
+    { name: "wl_ui_fix_dry_run", summary: "修复预演（不写盘）", write: "readonly" },
+    { name: "wl_ui_skill_prompt", summary: "技能提示词", write: "readonly" },
+    { name: "wl_ui_route_intent", summary: "意图路由", write: "readonly" },
+    { name: "wl_ui_detect_skin", summary: "皮肤检测", write: "readonly" },
+    { name: "wl_ui_list_rules", summary: "规则清单", write: "readonly" },
+    { name: "wl_ui_describe_rule", summary: "规则详情", write: "readonly" },
+    { name: "wl_ui_drift", summary: "漂移对比", write: "readonly" },
+    { name: "wl_ui_recommend_flow", summary: "推荐流程", write: "readonly" },
+    { name: "wl_ui_contract_extract", summary: "契约提取", write: "guarded" },
+    { name: "wl_ui_contract_validate", summary: "契约校验", write: "readonly" },
+    { name: "wl_ui_contract_match", summary: "契约匹配", write: "readonly" },
+  ];
+  return { skills, commands, mcpTools, loadErrors };
+}
+
+export const protocol = createProtocol({
+  packageName: pkg.name,
+  packageVersion: pkg.version,
+  capabilities: capabilitiesDocument.capabilities || [],
+  constraints: { node: (pkg.engines && pkg.engines.node) || null, boundaryVersion: capabilitiesDocument.boundaryVersion || null },
+  operations: OPERATIONS,
+  inventory: buildInventory(),
+});
+
+export function runOperation(operation, input) {
+  return runTaskAction(operation, {
+    projectRoot: input.projectRoot || ".",
+    task: input.task,
+    targets: Array.isArray(input.targets) ? input.targets : [],
+    runId: input.runId,
+    skill: input.skill,
+    host: input.host,
+    profile: input.profile,
+    context: input.context,
+  });
+}
+
+function envelopeError(code, message, field) {
+  return { protocolVersion: 1, package: pkg.name, packageVersion: pkg.version, operation: null, requestId: null, ok: false, error: { code, message, ...(field ? { field } : {}) }, diagnostics: [] };
+}
+
+export function runCli(argv) {
+  const sub = argv[0];
+  if (sub === "describe") {
+    console.log(JSON.stringify(protocol.describe(), null, 2));
+    return 0;
+  }
+  if (sub === "request") {
+    const fileIndex = argv.indexOf("--input-file");
+    const file = fileIndex >= 0 ? argv[fileIndex + 1] : null;
+    if (!file) {
+      console.log(JSON.stringify(envelopeError("missing-input", "缺少必要输入：--input-file <request.json>", "input-file"), null, 2));
+      return 2;
+    }
+    let input;
+    try {
+      input = JSON.parse(readFileSync(path.resolve(file), "utf8"));
+    } catch (error) {
+      const message = error.code === "ENOENT" ? `请求文件不存在：${file}` : `请求文件无法解析：${error.message}`;
+      console.log(JSON.stringify(envelopeError("invalid-input", message, "input-file"), null, 2));
+      return 2;
+    }
+    const envelope = protocol.request(input, runOperation);
+    console.log(JSON.stringify(envelope, null, 2));
+    return envelope.ok ? 0 : 2;
+  }
+  console.error("用法：");
+  console.error(`  ${BIN} protocol describe --json`);
+  console.error(`  ${BIN} protocol request --input-file <request.json> --json`);
+  return 2;
+}

package/bin/task-observability.cjs

@@ -69,7 +69,10 @@ function scoreSkill(skill, text, contextText) {
   const hits = matches(text, skill.triggers);
   const negative = matches(text, skill.negative);
   const contextHits = matches(contextText, skill.contexts);
-  const score = negative.length ? -100 : hits.length * 5 + contextHits.length * 2;
+  // 最长命中加权：更长的触发短语代表更具体的意图（如「表单弹窗布局」优先于「表单」「弹窗」），
+  // 只在同一命中数级别内打破平局，不改变命中数量的主导地位。
+  const longestHit = hits.reduce((max, phrase) => Math.max(max, String(phrase).length), 0);
+  const score = negative.length ? -100 : hits.length * 5 + contextHits.length * 2 + longestHit;
   return { id: skill.id, path: skill.path || null, score, hits, contextHits, negative, status: skill.status || "released" };
 }
 

package/bin/wl-ui.js

@@ -78,7 +78,7 @@ const SUBCOMMANDS = new Set([
   "contract",
   "rules",
   "profiles",
-  "task", "route", "explain", "status", "doctor-host",
+  "task", "route", "explain", "status", "doctor-host", "protocol",
 ]);
 let subcommand = "help";
 
@@ -95,7 +95,10 @@ if (rawArgs.length > 0 && SUBCOMMANDS.has(rawArgs[0])) {
 }
 
 // 非 init 子命令：直接委托给 scanner/index.mjs
-if (["task", "route", "explain", "status", "doctor-host"].includes(subcommand)) {
+if (subcommand === "protocol") {
+  const { runCli } = await import("./protocol-cli.mjs");
+  process.exitCode = runCli(rawArgs);
+} else if (["task", "route", "explain", "status", "doctor-host"].includes(subcommand)) {
   const { taskCli } = await import("./task-integration.mjs");
   taskCli(subcommand, rawArgs);
   process.exit(0);
@@ -1370,6 +1373,8 @@ wl-ui — @agile-team/wl-skills-ui 统一 CLI v${PKG.version}
                 查看本包实际执行、验证、检查范围和过期状态
   wl-ui doctor-host [--host codex|claude|copilot|cursor] [--json]
                 静态入口诊断；宿主发现与读取仍须宿主证据
+  wl-ui protocol describe --json | wl-ui protocol request --input-file <request.json> --json
+                公开集成协议：能力目录与统一判定/状态 JSON 信封
   wl-ui init   [--project <path>] [--editor <editor>] [--profile <id>]
                 [--dry-run] [--skills-only]
                 把 skills/ 写入目标项目的 AI 编辑器规则目录

package/docs/version-history.md

@@ -2,6 +2,16 @@
 
 本页保留面向使用者的版本能力摘要；逐提交级变更、修复细节和旧版本记录见根目录 [`CHANGELOG.md`](../CHANGELOG.md)。
 
+## v1.16.0 — 公开集成协议与输入校验收口（2026-10-08）
+
+### Added
+
+- 新增公开集成协议 describe/request 统一信封：能力清单与路由语料以真实打包产物验证；外部适配器仅依赖公开入口，移除适配器后本包独立能力不受影响。
+
+### Fixed
+
+- 输入校验收口（context null / 空 targets 返回可解释拒绝）；MCP 目录与真实 `tools/list` 18 项对齐。
+
 ## v1.15.0 — 任务判定、真实执行回执与原生技能入口
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-ui",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "企业级 UI 风格对齐框架 — Vue + Element Plus 双模式、任务路由与真实检查回执（tokens / element / vendors / layouts / runtime / scanner / fixer / skills）",
   "type": "module",
   "main": "./es/index.js",
@@ -59,7 +59,7 @@
   "scripts": {
     "build": "tsup && npm run sync:tokens",
     "sync:tokens": "node -e \"import('fs').then(fs=>fs.copyFileSync('design/tokens/base.css','dist/tokens.css'))\"",
-    "test": "node --test scanner/__tests__/*.test.mjs runtime/__tests__/*.test.mjs",
+    "test": "node --test scanner/__tests__/*.test.mjs runtime/__tests__/*.test.mjs bin/__tests__/*.test.mjs",
     "test:visual": "playwright test --config tests/visual/playwright.config.ts",
     "test:visual:contracts": "playwright test --config tests/visual/playwright.config.ts tests/visual/specs/browser-compat.spec.ts",
     "test:visual:ui": "playwright test --config tests/visual/playwright.config.ts --ui",
@@ -80,7 +80,7 @@
     "pack:dry": "npm pack --dry-run --ignore-scripts",
     "release:check": "npm run verify && npm run test:visual:contracts && npm run pack:dry",
     "prepublishOnly": "npm run release:check",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=bin/vendor/** --test-coverage-lines=70 --test-coverage-branches=65 --test-coverage-functions=70 scanner/__tests__/*.test.mjs runtime/__tests__/*.test.mjs",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=bin/vendor/** --test-coverage-lines=70 --test-coverage-branches=65 --test-coverage-functions=70 scanner/__tests__/*.test.mjs runtime/__tests__/*.test.mjs bin/__tests__/*.test.mjs",
     "benchmark:runtime": "node scripts/benchmark-observer-hub.mjs"
   },
   "files": [