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

package/CHANGELOG.md

@@ -4,8 +4,24 @@ All notable changes to **@agile-team/wl-skills-ui** will be documented in this f
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.17.0] - 2026-10-09
+
+- 统一可见 notice（包版本/判定/技能或基础约束/规则/目标/runId/待检查项）、开始与收尾提示、规范与执行器版本漂移诊断；保持单包使用与宿主证据未验证口径。
+- 按本包规则与实际 Profile 映射 Skill，不重复前端注释规则；保留旧入口哈希证明迁移与外来内容保护。
+
 ## [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,12 +1,20 @@
 # @agile-team/wl-skills-ui
 
-**企业级 UI 一致性与 AI 精确治理工具包 v1.15.0** — 面向 Vue 3 + Element Plus 的设计令牌、能力 Profile、样式皮肤、页面骨架、运行时能力、静态扫描、确定性修复、AI Skill、MCP 与脱敏 UI 模板契约。
+**企业级 UI 一致性与 AI 精确治理工具包 v1.17.0** — 面向 Vue 3 + Element Plus 的设计令牌、能力 Profile、样式皮肤、页面骨架、运行时能力、静态扫描、确定性修复、AI Skill、MCP 与脱敏 UI 模板契约。
 
 它把“视觉统一、问题识别、机械修复、项目适配和样例沉淀”拆成可验证、可组合的工程能力。脚本、规则和 MCP 先完成确定性工作，AI 只处理业务语义与人工决策，从而减少重复读源码、上下文 token 和误修改。
 
 [![npm version](https://img.shields.io/npm/v/@agile-team/wl-skills-ui.svg)](https://www.npmjs.com/package/@agile-team/wl-skills-ui)
 [![Node](https://img.shields.io/badge/node-%3E%3D22-green.svg)]()
 
+## 如何确认本包正在起作用
+
+每次适用任务先运行项目本地 `wl-ui task "修改目标文件" --target src/Foo.vue --json`。编辑前展示真实 `notice`：包名与版本、判定、选中 Skill 或基础约束、具体规则、目标、runId 和尚未执行的检查。普通修改也需要基础约束提醒；相关但未覆盖的意图显示 gap 与建议；没有目标依据显示 needs-context，职责外显示 not-applicable，不强行匹配。
+
+执行实际检查时复用 `--run-id`，结束读取 `wl-ui status --run-id <id> --json`，分别报告执行和验证、实际检查文件、过期证据与未执行项。`notice.displayEvidence=unverified` 表示工具回执不能证明聊天界面展示；安装、路由或模型自报不能证明宿主加载/模型读取。
+
+`wl-ui doctor-host --json` 对比已分发规范、本地执行器和正在运行的版本，漂移会显式报告。规范更新不会替代依赖升级：同步本包依赖、锁文件和受管入口；未使用的兄弟包无需安装。重开/刷新宿主加载后仍需观察真实任务调用，不能宣称所有 AI 自动触发。
+
 ## 你能获得什么
 
 | 目标 | 包提供的能力 | 带来的效果 |
@@ -94,6 +102,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 +508,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.17.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-gateway.mjs

@@ -9,7 +9,9 @@ description: Vue and Element Plus UI consistency, design tokens, styles, compone
 # wl-skills-ui task gateway
 For one user task reuse the same \`--run-id\` or \`WL_TASK_RUN_ID\` across installed applicable packages. Do not install unused sibling packages or create unrelated IDs.
 
-1. Start each task with \`node node_modules/@agile-team/wl-skills-ui/bin/wl-ui.js task "<task>" --target <path>\`. Retain the run ID and briefly explain the decision, applicable rules and unverified items. A routing decision does not execute checks.
+多项目工作区先沿目标路径向上找到本包安装清单与项目 AGENTS，切到该项目根再调用工具；不要以聚合工作区根代替 projectRoot，也不要在聚合根安装。不同项目分别保存项目身份，同一用户任务复用 runId。
+
+1. Start each relevant task from its project root with \`node node_modules/@agile-team/wl-skills-ui/bin/wl-ui.js task "<task>" --target <path> --json\`. Before editing, visibly show the returned \`notice\`: actual package/version, decision, Skill or baseline, rule IDs/names, target, runId and unverified checks. Include baseline and gaps. Report missing/unsupported local commands and version drift explicitly. A routing decision does not execute checks.
 2. Read \`node_modules/@agile-team/wl-skills-ui/SKILL.md\`, then only the selected canonical Skill under \`node_modules/@agile-team/wl-skills-ui/skills\`. Resolve references relative to that Skill. Honor the actual project Profile; do not infer a table migration from a Skill match.
 3. Run the actual scan/check/fix tools with the same \`--run-id\`. For a code gate use \`wl-ui scan --target <path> --fail-on-error --run-id <id>\`. An ordinary Vue edit still receives UI baseline checks; tasks outside the domain are not applicable.
 4. End with \`wl-ui status --run-id <id>\` and report execution separately from validation. Zero files, skipped checks, dependency-only checks and unresolved review items are not proof of all UI constraints passing.

package/bin/task-integration.mjs

@@ -41,7 +41,7 @@ export function taskCatalog() {
   return catalogFiles(join(root, "skills")).map((file) => {
     const id = relative(join(root, "skills"), file).replace(/\\/g, "/").replace(/\/SKILL\.md$/, "");
     const content = readFileSync(file, "utf8");
-    return { id, path: `node_modules/${pkg.name}/skills/${id}/SKILL.md`, description: content.match(/^# (.+)$/m)?.[1] || id, triggers: TRIGGERS[id] || [], rules: POLICY.baselineRules, checks: ["scan"], status: "enabled" };
+    return { id, path: `node_modules/${pkg.name}/skills/${id}/SKILL.md`, description: content.match(/^# (.+)$/m)?.[1] || id, triggers: TRIGGERS[id] || [], rules: getRules().filter((rule) => rule.skills?.includes(id)).map((rule) => rule.id), checks: ["scan"], status: "enabled" };
   });
 }
 
@@ -75,10 +75,15 @@ export function runTaskAction(action, input = {}) {
   if (action === "doctor-host") return hostDiagnostic({ ...opts, host: input.host || "unknown" });
   const profile = resolveProjectProfile({ projectRoot: opts.projectRoot, profile: input.profile }).profile;
   const routed = decideTask({ task: input.task || "", targets: opts.targets, skill: input.skill });
-  const decision = { ...routed, profile: profile.id, applicableConstraints: routed.applicable === true ? getRules({ profile: profile.id }).map((rule) => rule.id) : [] };
+  const applicable = getRules({ profile: profile.id });
+  const enabled = new Set(applicable.map((rule) => rule.id));
+  const decision = { ...routed, profile: profile.id, applicableConstraints: routed.applicable === true ? [...enabled] : [] };
+  decision.baselineRules = decision.baselineRules.filter((id) => enabled.has(id));
+  decision.requiredRules = decision.requiredRules.filter((id) => enabled.has(id));
+  decision.ruleDetails = applicable.filter((rule) => decision.requiredRules.includes(rule.id)).map((rule) => ({ id: rule.id, name: rule.title, source: `node_modules/${pkg.name}/standards/rules.json` }));
   assetReadiness(decision, opts.projectRoot);
-  if (action !== "task") return decision;
-  return { ...decision, ...core.startTask({ ...opts, task: input.task || "", decision }) };
+  if (action !== "task") return core.attachNotice(decision, opts);
+  return core.attachNotice({ ...decision, ...core.startTask({ ...opts, task: input.task || "", decision }) }, opts);
 }
 
 function hostDiagnostic(opts) {

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" };
 }
 
@@ -262,6 +265,7 @@ function startTask(options) {
   const record = { ...baseRecord(metadata, "task-decision"), task: safeText(options.task), decision: selected, targets: strings(options.targets), inputSnapshot: captureSnapshot(options),
     ruleSnapshot: captureReadEvidence(options, [...strings(options.ruleFiles), ...strings(selected.requiredFiles)]),
     configSnapshot: contextSnapshot(options, "configFiles"), executionStatus: "not-executed", validationStatus: "unverified" };
+  attachNotice(record, options);
   record.recordPath = appendRecord(options, record);
   return record;
 }
@@ -403,12 +407,12 @@ function statusForRecords(records, options) {
   const started = records.filter((record) => record.kind === "tool-started");
   const current = validationContext(plan, tools, options);
   const failed = tools.some((record) => record.executionStatus === "failed");
-  return {
+  return attachNotice({
     recordVersion: RECORD_VERSION, packageName: options.packageName, ...lastRecordContext(records.at(-1), options),
     ...planContext(plan), records, tools,
     executionStatus: executionState(failed, started, history),
     ...current, stages: { selected: plan ? plan.decision.status : "unverified", hostDiscovered: "unverified", contentLoaded: "unverified", toolsExecuted: history.length },
-  };
+  }, options);
 }
 
 function validationContext(plan, tools, options) {
@@ -436,7 +440,7 @@ function uncoveredScope(plan, tools, options) {
 
 function planContext(plan) {
   if (!plan) return { task: null, decision: null, gaps: [] };
-  return { task: plan.task, decision: plan.decision, gaps: plan.decision.gaps || [] };
+  return { task: plan.task, decision: plan.decision, targets: plan.targets, gaps: plan.decision.gaps || [] };
 }
 
 function lastRecordContext(latest, options) {
@@ -502,18 +506,91 @@ function doctorHost(options) {
   const skills = strings(options.skillPaths).map((relative) => inspectHostFile(root, relative, Infinity));
   const gateway = options.gatewayPath ? inspectHostFile(root, options.gatewayPath, Infinity) : null;
   const warnings = entries.filter((entry) => entry.oversized).map((entry) => `${entry.path} 超过 ${maximum} 字节参考预算；请核对宿主实际配置与内容加载范围`);
-  const ready = gateway?.status === "present" && skills.length > 0 && skills.every((skill) => skill.status === "present") && entries.every((entry) => entry.status === "present" && !entry.oversized);
-  return { recordVersion: RECORD_VERSION, packageName: options.packageName, host: options.host || "unspecified", projectRoot: root, entries, skills, gateway, entryReadiness: ready ? "ready" : "incomplete", hostDiscovery: "unverified", mcpConnection: "unverified", contentLoaded: "unverified", warnings, instructionBudgetSource: "reference-default-not-observed-host-config" };
+  const runtime = inspectRuntime(root, options);
+  warnings.push(...runtime.warnings);
+  const ready = hostReady(gateway, skills, entries, runtime);
+  return { recordVersion: RECORD_VERSION, packageName: options.packageName, packageVersion: options.packageVersion, host: options.host || "unspecified", projectRoot: root, entries, skills, gateway, runtime, entryReadiness: ready ? "ready" : "incomplete", hostDiscovery: "unverified", mcpConnection: "unverified", contentLoaded: "unverified", warnings, instructionBudgetSource: "reference-default-not-observed-host-config" };
+}
+
+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; }
+  catch (error) { if (error.code !== "ENOENT") diagnostics.push(`${relative}: ${error.message}`); return null; }
+}
+function declaredDependency(root, packageName) {
+  try { const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")); return pkg.dependencies?.[packageName] || pkg.devDependencies?.[packageName] || null; }
+  catch { return null; }
+}
+function runtimeMismatch(versions, declared, local) {
+  return strings(versions).length > 1 || Boolean(local && /^\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?$/.test(declared || "") && declared !== local);
+}
+function inspectRuntime(root, options) {
+  root = fs.realpathSync(path.resolve(root));
+  const key = (options.packageName || "").replace("@agile-team/wl-skills-", "");
+  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 declaredVersion = declaredDependency(root, options.packageName);
+  const mismatch = runtimeMismatch([distributedVersion, localVersion, options.packageVersion], declaredVersion, localVersion);
+  const state = distributedVersion ? "aligned" : "unverified";
+  return { status: mismatch ? "mismatch" : diagnostics.length ? "invalid" : state, distributedVersion, localVersion, runningVersion: options.packageVersion || null, declaredVersion, diagnostics,
+    warnings: mismatch ? [`${options.packageName} 规范/本地执行器/当前执行器版本不一致：${distributedVersion} / ${localVersion} / ${options.packageVersion}；声明依赖=${declaredVersion}；同步本包依赖、锁文件与受管入口后复验`] : diagnostics, hostInvocation: "unverified" };
+}
+
+/** A notice describes the receipt; it does not claim the host displayed it or read rules. */
+function noticeProjectRoot(record, options) {
+  return options.projectRoot ? fs.realpathSync(path.resolve(options.projectRoot)) : record.notice?.projectRoot || null;
+}
+function noticeRules(item) {
+  const details = new Map((item.ruleDetails || []).map((rule) => [rule.id, rule]));
+  const ids = strings([...strings(item.baselineRules), ...strings(item.requiredRules), ...strings(item.constraints)]);
+  return ids.map((id) => ({ id, name: details.get(id)?.name || id, source: details.get(id)?.source || null }));
+}
+function noticeScope(record, options, item) {
+  return { targets: strings(options.originalTargets || record.targets || options.targets),
+    executionStatus: record.executionStatus || "not-executed", validationStatus: record.validationStatus || "unverified",
+    unverified: strings(item.unverified || ["host-discovery", "model-read-canonical-files", "planned-actions-not-executed"]) };
+}
+function noticeReason(item) { return safeText(item.reason || strings(item.reasons).join("；")); }
+function attachNotice(record, options = {}) {
+  const item = record.decision || record;
+  record.packageName ||= options.packageName;
+  record.packageVersion ||= options.packageVersion;
+  record.notice = {
+    schemaVersion: 1, packageName: record.packageName || null, packageVersion: record.packageVersion || null,
+    projectRoot: noticeProjectRoot(record, options), runId: record.runId || null, decision: item.status || "unverified",
+    skills: strings(item.selectedSkills), requiredChecks: strings(item.requiredChecks), baselineRules: strings(item.baselineRules), rules: noticeRules(item),
+    reason: noticeReason(item), missingInputs: strings(item.missingInputs),
+    gaps: (item.gaps || []).map((gap) => ({ reason: safeText(gap.reason), suggestion: safeText(gap.suggestion) })),
+    ...noticeScope(record, options, item), displayEvidence: "unverified",
+  };
+  return record;
+}
+function noticeRuleText(notice) {
+  const rules = notice.rules.slice(0, 8).map((rule) => rule.name === rule.id ? rule.id : `${rule.id}（${rule.name}）`).join("、");
+  const remaining = notice.rules.length > 8 ? `等 ${notice.rules.length} 条，完整清单见 JSON 回执` : "";
+  return `${rules}${remaining || (rules ? "" : "尚无确认规则")}`;
+}
+function noticePlanText(notice) {
+  return `${notice.requiredChecks.length ? `\n待执行检查：${notice.requiredChecks.join("、")}` : ""}` + `${notice.runId ? `\nrunId=${notice.runId}` : "\n只读判定，尚无任务记录"}；执行=${notice.executionStatus}；验证=${notice.validationStatus}`;
+}
+function noticeGapText(notice) {
+  return `${notice.missingInputs.length ? `\n缺少：${notice.missingInputs.join("、")}` : ""}` + `${notice.gaps.length ? `\n缺口：${notice.gaps.map((gap) => `${gap.reason}；建议：${gap.suggestion}`).join("\n")}` : ""}`;
 }
-
 function formatDecision(record) {
-  const item = record.decision || record;
-  const label = { baseline: "基础约束", ambiguous: "候选需确认", gap: "规则缺口", "not-applicable": "不适用", "needs-context": "缺少上下文" }[item.status] || "待判定";
-  return `[WL ${item.status}] ${strings(item.selectedSkills).join("、") || label}；${safeText(item.reason || strings(item.reasons).join("；"), 300)}${record.runId ? `；runId=${record.runId}` : ""}`;
+  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适用规则：${noticeRuleText(notice)}；范围：${notice.targets.slice(0, 3).join("、") || "未指定目标，检查范围待确认"}` + noticePlanText(notice) + noticeGapText(notice);
 }
 
 function formatStatus(status) {
-  return `[WL 执行=${status.executionStatus} 验证=${status.validationStatus}] runId=${status.runId || "尚无记录"}；工具=${status.tools.length}；待验证=${status.pendingChecks.length}；范围缺口=${(status.scopeGaps || []).length}；规则缺口=${(status.gaps || []).length}；宿主发现=${status.stages.hostDiscovered}`;
+  const identity = `${status.packageName?.replace("@agile-team/wl-skills-", "") || "未知包"}@${status.packageVersion || "未知"}`;
+  const checked = [...new Set(status.tools.flatMap((tool) => (tool.checkedFiles || []).map((file) => file.path)))];
+  return `[WL 执行=${status.executionStatus} 验证=${status.validationStatus}] ${identity}；runId=${status.runId || "尚无记录"}；工具=${status.tools.length}；实际检查文件=${checked.length}；待验证=${status.pendingChecks.length}；范围缺口=${(status.scopeGaps || []).length}；规则缺口=${(status.gaps || []).length}；证据过期=${Boolean(status.stale)}；宿主发现=${status.stages.hostDiscovered}`;
 }
 
 function aggregateStatus(statuses) {
@@ -522,4 +599,4 @@ function aggregateStatus(statuses) {
   return { recordVersion: RECORD_VERSION, runId: runIds.length === 1 ? runIds[0] : null, correlated: runIds.length === 1, packages: valid, mixedRuns: runIds.length > 1, hasFailure: valid.some((status) => status.validationStatus === "failed"), gaps: valid.flatMap((status) => status.gaps || []) };
 }
 
-module.exports = { RECORD_VERSION, STORAGE, evaluateTask, startTask, beginExecution, finishExecution, withExecution, captureSnapshot, readStatus, listGaps, doctorHost, formatDecision, formatStatus, aggregateStatus };
+module.exports = { RECORD_VERSION, STORAGE, evaluateTask, startTask, beginExecution, finishExecution, withExecution, captureSnapshot, readStatus, listGaps, doctorHost, inspectRuntime, attachNotice, formatDecision, formatStatus, aggregateStatus };

package/bin/task-observability.schema.json

@@ -34,7 +34,8 @@
     "artifacts": { "type": "array", "items": { "$ref": "#/definitions/file" } },
     "changedDuringCheck": { "type": "boolean" },
     "errorCode": { "type": "string" },
-    "recordPath": { "type": ["string", "null"] }
+    "recordPath": { "type": ["string", "null"] },
+    "notice": { "$ref": "#/definitions/notice" }
   },
   "allOf": [
     { "if": { "properties": { "kind": { "const": "task-decision" } } }, "then": { "required": ["task", "decision"], "properties": { "executionStatus": { "const": "not-executed" }, "validationStatus": { "const": "unverified" } } } },
@@ -42,6 +43,100 @@
     { "if": { "properties": { "kind": { "const": "tool-finished" } } }, "then": { "required": ["tool", "executionId", "executionStartedAt", "exitCode", "durationMs", "checks", "artifacts", "inputBefore", "changedDuringCheck"], "properties": { "executionStatus": { "enum": ["completed", "failed"] } } } }
   ],
   "definitions": {
+    "notice": {
+      "type": "object",
+      "required": [
+        "schemaVersion",
+        "packageName",
+        "packageVersion",
+        "runId",
+        "decision",
+        "skills",
+        "rules",
+        "requiredChecks",
+        "executionStatus",
+        "validationStatus",
+        "displayEvidence"
+      ],
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "packageName": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "packageVersion": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "runId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "projectRoot": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "decision": {
+          "type": "string"
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "requiredChecks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "rules": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "name",
+              "source"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "source": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            }
+          }
+        },
+        "executionStatus": {
+          "type": "string"
+        },
+        "validationStatus": {
+          "type": "string"
+        },
+        "displayEvidence": {
+          "const": "unverified"
+        }
+      }
+    },
     "file": {
       "type": "object", "required": ["path", "sha256", "bytes"],
       "properties": { "path": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "bytes": { "type": "integer", "minimum": 0 } }

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);
@@ -571,7 +574,7 @@ function transformForEditor(content, editor) {
         ?.slice(2) || "Skill",
     );
 
-  return header + "\nStart each task with local `wl-ui task \"<task>\" --target <path>`. Read only the selected Skill. Finish actual tools with the same `--run-id` and report `wl-ui status`; model declarations do not prove verification.\n\n" + body;
+  return header + "\nStart each task with local `wl-ui task \"<task>\" --target <path>`. Before editing visibly show the returned notice: actual package/version, decision, Skill or baseline, rule IDs/names, targets, runId and unexecuted checks. Report local command failures/version drift. Read only the selected Skill. Finish actual tools with the same `--run-id` and report `wl-ui status`; model declarations do not prove verification.\n\n" + body;
 }
 
 function selectedSkills(mode, profile) {
@@ -661,7 +664,7 @@ function buildSingleFileRouter(skills, profile) {
     `> Active profile: \`${profile?.id || "native-element"}\`.`,
     "",
     "Use the package router first, then open only the relevant Skill:",
-    "Start each task with local `wl-ui task \"<task>\" --target <path>`; read only the selected canonical Skill. Finish actual checks with the same `--run-id`, then report `wl-ui status --run-id <id>`. Routing/model declarations do not prove execution or validation. Native discovery: `.agents/skills/wl-skills-ui/SKILL.md`.",
+    "Start each task with local `wl-ui task \"<task>\" --target <path>`; before editing visibly show notice (actual package/version, decision, Skill or baseline, rule IDs/names, targets, runId, unexecuted checks), including gaps and local command/version failures; read only the selected canonical Skill. Finish actual checks with the same `--run-id`, then report `wl-ui status --run-id <id>`. Routing/model declarations do not prove execution or validation. Native discovery: `.agents/skills/wl-skills-ui/SKILL.md`.",
     "Reuse one `--run-id` / `WL_TASK_RUN_ID` across installed applicable packages for this user task; do not install unused sibling packages.",
     "",
     "- `node_modules/@agile-team/wl-skills-ui/SKILL.md`",
@@ -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.17.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": [