create-yss-spec 2.2.9 → 2.2.10

package/template/docs/process/template-verification-profiles.yaml

@@ -38,7 +38,16 @@ required_files:
   - AGENTS.md
   - CONTEXT.md
   - skills-lock.json
+  - .agents/skills/.yss-skills-manifest.json
+  - .mcp.json
+  - .agents/mcp_config.json
+  - .cursor/mcp.json
+  - .gemini/settings.json
+  - .kiro/settings/mcp.json
+  - .vscode/mcp.json
   - docs/agents/yss-skill-registry.yaml
+  - docs/agents/yss-ui-skills-integration.md
+  - docs/user-guide/yss-ui-mcp.md
   - docs/agents/digital-human-roles.yaml
   - docs/process/lifecycle-registry.yaml
   - docs/process/lifecycle-registry-baseline.json
@@ -138,6 +147,8 @@ routing:
     groups: [governance-release]
   - patterns: [skills-lock.json, ".agents/skills/**", ".claude/skills/**", ".codex/skills/**", ".cursor/skills/**", ".hermes/skills/**", ".pi/skills/**", ".qoder/skills/**", ".trae/skills/**", "docs/agents/yss-skill-registry.yaml", "docs/agents/skills-maintenance.md", "scripts/*skill*"]
     groups: [skills]
+  - patterns: [.mcp.json, .agents/mcp_config.json, .cursor/mcp.json, .gemini/settings.json, .kiro/settings/mcp.json, .vscode/mcp.json, docs/user-guide/yss-ui-mcp.md, docs/agents/yss-ui-skills-integration.md]
+    groups: [skills]
   - patterns: ["docs/process/maintenance-*", "docs/process/harness-process-tailoring.md", "docs/process/schemas/maintenance-*", "scripts/*maintenance*", "scripts/lib/maintenance-*"]
     groups: [maintenance]
   - patterns: ["docs/process/lifecycle-*", "docs/process/templates/lifecycle-*", "scripts/*lifecycle*", "scripts/lib/lifecycle-*"]

package/template/docs/templates/implementation-routing-template.md

@@ -40,7 +40,7 @@ owner: ai
 | Harness 内项目根路径符合 `apps/<backend|frontend>/<project>/` | 是 / 否 / 不适用 | `apps/backend/`、`apps/frontend/` 仅为容器 |
 | 未使用 `app/backend/`、`app/frontend/` 及其子路径 | 是 / 否 / 不适用 | 命中即阻断生成和实现 |
 | 原型确认后先完成后端脚手架，再进入业务代码路由 | 是 / 否 / 不适用 | `backend_scaffold_policy_satisfied` |
-| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | `contract_id`、`contract_version`、Router draft、生命周期批准、持久化引用、允许写路径、预期证据、验证命令 |
+| 后端脚手架合同字段完整且版本当前 | 是 / 否 / 不适用 | schema v2：`scaffold_request_id`、项目/输出目录、Router draft、生命周期批准、base package、Maven 坐标、target DDD/Profile、initialize-only、允许写路径、预期证据、验证命令 |
 | 后端构建 / 测试 / OpenAPI / CI 命令均使用项目根目录 `./mvnw ...`，或已记录受控例外 | 是 / 否 / 不适用 | 裸 `mvn ...` 默认为规范偏离 |
 | 持久化文档正文和章节标题已转换为中文，仅保留必要英文技术标识 / metadata | 是 / 否 | 英文 skill / 模板不得原样落地为交付文档 |
 | YSS skill 路由已完成 | 是 / 否 |  |
@@ -245,10 +245,12 @@ owner: ai
 | 前置 | `prototype_confirmation`、工程基线、实现仓库和脚手架目标已确认；Router 脚手架合同 draft 已经生命周期批准并持久化为结构化 JSON，生成器通过 `--contract-file` 消费 |
 | 生成器 | `yss-ddd-scaffold-generator` |
 | 模式 | `controlled-generation` |
+| Java / Maven 身份 | `base_package` 与 Maven `group_id` 分开登记；项目版本、父 POM GAV、`yss-components.version` 进入批准合同并原样传给 CLI |
 | 允许生成 | Domain / Application / Infrastructure / Adapter / Bootstrap 目录骨架、POM、配置、Wrapper 和非业务机械模板 |
 | 禁止生成 | 业务规则、状态机、权限、事务、复杂查询、错误映射、业务字段和用户可见行为 |
-| 生成选项 | 关闭 `--with-example`；非空目录 `--force` 默认阻断，覆盖范围、备份、回滚点和批准引用齐全后才能单独审查 |
-| 验证 | 受控验证器实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`，逐条记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
+| 生成选项 | 关闭 `--with-example`；生成器严格 initialize-only，非空目录、`--force`、旧项目迁移和当前模板升级均为 `unsupported` |
+| Profile | `target-domain-model` / `mybatis-plus` / `mysql` / `spring-boot-2.7-jdk8` / `javax` / `web` / `yss-internal`；其他组合须先通过独立 fixture |
+| 验证 | 使用一键生成验证入口，实际执行项目根目录 `./mvnw validate`、`./mvnw test`、`./mvnw package`；通过后仅为 `empty-scaffold-verified`，golden first slice 通过后才是 `first-slice-verified` |
 | 后置 | `yss-backend-scaffold-parent`、`yss-router` 业务合同重编译、YSS Skill Execution Result |
 
 所有后续生成代码必须绑定当前批准且版本一致的 Slice Implementation Contract、主 YSS skill、依赖闭包、允许写路径、预期证据和 Execution Result。业务行为必须使用 `behavior-tdd`；缺任一条件即阻断，不得以脚手架成功或时间压力豁免。

package/template/docs/templates/review-report-template.md

@@ -87,8 +87,8 @@ rg -n "class (SingleResult|MultiResult|PageResult|Result)<|public static class .
 
 | 检查项 | 结论 | 证据 |
 |---|---|---|
-| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YssFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
-| `yss-page-module-development` 页面骨架已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
+| `yss-ui` 组件路由已落实：YSS `required` 封装（如 `YTable` / `YTree` / `YFormily`）未被 AntDV 裸组件或其他重型方案绕过；受控回退有能力缺口记录 | pass / violation / not-applicable |  |
+| `yss-ui-business-page-generation` 页面生成与 `yss-page-module-development` 生命周期编排已落实：`index.vue` 只编排，请求与分页不堆在页面根组件 | pass / violation / not-applicable |  |
 | 切片合同 `required_skills` 中的 Formily / 表格 / 树 / 高度 / 主题 / API 专项 skill 已按影响面引用规则；未命中项有 `not-applicable` 原因 | pass / violation / not-applicable |  |
 | 前端验证使用项目根 `pnpm ...`；实际退出码已记录。只做 type-check 或声称“已对齐”不算通过 | pass / violation / not-applicable |  |
 | 机器检查（`pnpm lint` / `pnpm type-check` 等已存在脚本）已执行，或缺失工具已写 `not-applicable` 及原因 | pass / violation / not-applicable |  |

package/template/docs/user-guide/yss-ui-mcp.md

@@ -0,0 +1,43 @@
+# YSS UI MCP 接入
+
+模板已为支持项目级 MCP 配置的客户端预置 `yss-ui` server：
+
+- Claude Code：`.mcp.json`
+- Antigravity：`.agents/mcp_config.json`
+- Cursor：`.cursor/mcp.json`
+- Gemini CLI：`.gemini/settings.json`
+- Kiro：`.kiro/settings/mcp.json`
+- VS Code：`.vscode/mcp.json`
+
+这些配置统一通过 `npx -y @yss-ui/mcp` 启动，不写用户主目录，也不覆盖个人全局配置。首次加载模板后，重启或刷新对应客户端即可发现 MCP。
+
+## Codex 等全局配置客户端
+
+需要写入用户级配置的客户端不由模板自动修改。以 Codex 为例，由使用者明确执行：
+
+```bash
+npx -y @yss-ui/mcp install codex
+```
+
+其他客户端的安装参数以 `@yss-ui/mcp` 当前 CLI 帮助为准。模板只提供说明，不替用户修改 `~/.codex/config.toml` 等全局文件。
+
+## 使用门禁
+
+生成或审查 YSS UI 页面时：
+
+1. 先调用 `get_codegen_rules` 获取当前代码生成约束。
+2. 不确定组件导出时调用 `list_components`。
+3. 配置组件、Hook 或 Utils 前调用 `get_component_docs`。
+4. 复杂场景调用 `get_demo`；无法确定归属时调用 `search_docs`。
+
+本次模板验证基线为 `@yss-ui/mcp@0.1.8`、YSS UI components `1.5.18`，MCP 对外提供 7 个工具。运行时返回值与项目 lockfile 仍优先于本文快照；MCP 不可用时，按 `AGENTS.md` 读取 `llms-full.txt`，并明确记录降级原因。
+
+## 快速自检
+
+客户端中至少确认以下结果：
+
+- `list_components` 能返回 YSS UI 组件清单。
+- `get_codegen_rules` 能返回当前生成规则。
+- 查询 `YTable` 时，`get_component_docs` 能返回对应文档。
+
+MCP 无法启动时，先确认 Node.js、`npx` 和网络/私有源访问，再直接运行 `npx -y @yss-ui/mcp` 查看启动错误；不要把 Registry 认证内容写入日志或提交到仓库。

package/template/scripts/lib/scenario-checks.mjs

@@ -46,7 +46,7 @@ function validateInvocationBoundary(data) {
   ensure(JSON.stringify(boundary?.lifecycle_managed_user_entries) === JSON.stringify(["setup-matt-pocock-skills", "grill-with-docs", "to-spec", "to-tickets", "implement"]), "生命周期管理的显式用户入口清单不完整");
   ensure(boundary?.lifecycle_may_invoke_user_invoked === false && boundary?.formal_artifact_owner === "explicit-user-entry", "生命周期仍可能自动调用 user-invoked skill 或产出其正式资产");
   ensure(JSON.stringify(boundary?.model_invoked_skills) === JSON.stringify(expectedModelInvoked) && JSON.stringify(boundary?.lifecycle_allowed_model_invoked_skills) === JSON.stringify(expectedLifecycleModelInvoked) && boundary?.continuous_orchestration === "compatibility-prepare-and-validate-only", "Matt invocation inventory 或生命周期 model-invoked 白名单不完整");
-  ensure(JSON.stringify(data.skill_source_contract?.source_revisions_required) === JSON.stringify(["mattpocock/skills"]) && data.skill_source_contract?.adaptation_ref_required_when_effective_diff === true && data.skill_source_contract?.retired_shared_skills?.includes("batch-grill-me"), "上游来源或退役 skill 供应链契约不完整");
+  ensure(JSON.stringify(data.skill_source_contract?.source_revisions_required) === JSON.stringify(["mattpocock/skills", "iloveZzz/yss-ui"]) && data.skill_source_contract?.adaptation_ref_required_when_effective_diff === true && data.skill_source_contract?.retired_shared_skills?.includes("batch-grill-me"), "上游来源或退役 skill 供应链契约不完整");
   validateInvocationMetadata(boundary, (skill) => read(`.agents/skills/${skill}/SKILL.md`));
   const setup = data.setup_readiness;
   ensure(setup?.missing_action === "needs-human" && setup?.requested_skill === "setup-matt-pocock-skills" && setup?.resume_route === "setup-readiness" && setup?.preserves?.includes("lifecycle.status"), "readiness=missing 未形成显式用户 setup 的结构化暂停");
@@ -60,9 +60,9 @@ function validateInvocationBoundary(data) {
   const routes = data.work_unit_routes;
   ensure(routes?.["work-unit.discovery-requirements"]?.skills?.includes("grilling") && routes?.["work-unit.discovery-requirements"]?.skills?.includes("domain-modeling"), "需求分析工作单元缺少 grilling/domain-modeling");
   ensure(routes?.["work-unit.discovery-opportunity"]?.route_by?.market_or_competitor_fact === "competitive-intelligence" && routes["work-unit.discovery-opportunity"].route_by.technical_or_standard_fact === "research", "机会调研事实路由不准确");
-  ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui"), "原生实现工作单元缺少 TDD 或 UI 路由");
+  ensure(routes?.["work-unit.slice-implementation"]?.skills?.includes("tdd") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui") && routes?.["work-unit.slice-implementation"]?.skills?.includes("yss-ui-business-page-generation"), "原生实现工作单元缺少 TDD、UI 或业务页面生成路由");
   const frontendRoute = routes?.["work-unit.slice-implementation"]?.frontend_route;
-  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口或页面编排技能");
+  ensure(frontendRoute?.primary_skill === "yss-ui" && frontendRoute?.page_generation_skill === "yss-ui-business-page-generation" && frontendRoute?.page_orchestration_skill === "yss-page-module-development", "前端实现路由缺少 yss-ui 主入口、业务页面生成或页面编排技能");
   for (const impact of ["api_impact", "formily_impact", "table_impact", "tree_impact", "height_impact", "export_impact", "theme_impact"]) {
     ensure(Array.isArray(frontendRoute?.conditional_skills?.[impact]) && frontendRoute.conditional_skills[impact].length > 0 && typeof frontendRoute.not_applicable_reasons?.[impact] === "string", `前端条件专项路由缺少 ${impact}`);
   }

package/template/scripts/lib/skill-governance.mjs

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadSkillRegistry } from "./skill-registry.mjs";
+import { validateYssUiSkillManifest } from "./skill-supply-chain.mjs";
 
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -27,10 +28,43 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
     fail("页面模块 canonical 技能缺少条件化 toolbar-config 规则");
   }
 
+  const yssUiManifest = validateYssUiSkillManifest(JSON.parse(read(".agents/skills/.yss-skills-manifest.json")));
+  const lock = JSON.parse(read("skills-lock.json"));
+  for (const skill of yssUiManifest.skills) {
+    const skillPath = `.agents/skills/${skill.canonical}/SKILL.md`;
+    if (!exists(skillPath)) fail(`yss-ui 前端清单缺少 canonical skill: ${skill.canonical}`);
+    const item = lock.skills?.shared?.[skill.canonical];
+    if (!item || item.source !== yssUiManifest.source || item.sourceRevision !== yssUiManifest.source_revision) {
+      fail(`yss-ui skill 缺少一致的来源锁定: ${skill.canonical}`);
+    }
+    if (item.skillPath !== `${yssUiManifest.source_root}/${skill.upstream}/SKILL.md` || item.upstreamHash !== skill.upstream_hash) {
+      fail(`yss-ui skill 上游路径或 hash 不一致: ${skill.canonical}`);
+    }
+    const content = read(skillPath);
+    for (const match of content.matchAll(/\.\.\/([a-z0-9-]+)\/SKILL\.md/g)) {
+      if (!exists(`.agents/skills/${match[1]}/SKILL.md`)) fail(`${skill.canonical} 引用了不存在的本地 skill: ${match[1]}`);
+    }
+  }
+  const yssUiSkill = read(".agents/skills/yss-ui/SKILL.md");
+  if (!yssUiSkill.includes("`YFormily` 是新代码 canonical name")) fail("yss-ui 必须把 YFormily 声明为新代码 canonical name");
+  if (!yssUiSkill.includes("| 新建或改造完整业务页面 | `yss-ui-business-page-generation` |")) fail("yss-ui 缺少完整业务页面生成路由");
+  const expectedServer = { command: "npx", args: ["-y", "@yss-ui/mcp"] };
+  for (const config of yssUiManifest.mcp.project_configs) {
+    if (!exists(config.path)) fail(`缺少 yss-ui MCP 项目配置: ${config.path}`);
+    const document = JSON.parse(read(config.path));
+    if (JSON.stringify(document?.[config.container]?.[yssUiManifest.mcp.server_name]) !== JSON.stringify(expectedServer)) {
+      fail(`yss-ui MCP 配置不一致: ${config.path}`);
+    }
+  }
+  const mcpGuide = read(yssUiManifest.mcp.global_install_guide);
+  for (const marker of ["npx -y @yss-ui/mcp install codex", "不写用户主目录", "get_codegen_rules", "list_components"]) {
+    if (!mcpGuide.includes(marker)) fail(`YSS UI MCP 指南缺少边界或自检标记: ${marker}`);
+  }
+
   const registry = loadSkillRegistry();
   const canonicalIds = new Set(registry.skills.map((skill) => skill.id));
   const aliases = new Map(registry.skills.flatMap((skill) => skill.aliases.map((alias) => [alias, skill.id])));
-  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height", "yss-ui-business-page-generation"]);
+  const legacy = new Set(["api-integration", "page-module-development", "use-table-height", "use-tree-height"]);
   for (const alias of legacy) {
     if (exists(`.agents/skills/${alias}`)) fail(`legacy alias 不得存在独立 canonical 目录: ${alias}`);
     if (!aliases.has(alias)) fail(`legacy alias 未登记: ${alias}`);
@@ -65,5 +99,5 @@ export function validateSkillGovernance({ read = (relative) => readFileSync(path
       }
     }
   }
-  return { checked: true, legacy_aliases: legacy.size };
+  return { checked: true, legacy_aliases: legacy.size, yss_ui_skills: yssUiManifest.skills.length };
 }

package/template/scripts/lib/skill-registry.mjs

@@ -392,6 +392,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
       }
       if (route.frontend_route) {
         requireString(route.frontend_route.primary_skill, `${routeId}.frontend_route.primary_skill`);
+        requireString(route.frontend_route.page_generation_skill, `${routeId}.frontend_route.page_generation_skill`);
         requireString(route.frontend_route.page_orchestration_skill, `${routeId}.frontend_route.page_orchestration_skill`);
         const conditional = route.frontend_route.conditional_skills;
         if (!conditional || typeof conditional !== "object" || Array.isArray(conditional)) fail(`${routeId}.frontend_route.conditional_skills 必须是对象`);
@@ -402,7 +403,7 @@ export function validateSkillRegistry(registry, { lock, routerContract, lifecycl
             fail(`${routeId}.frontend_route.not_applicable_reasons.${impact} 必须是字符串`);
           }
         }
-        if (!resolve(route.frontend_route.primary_skill) || !resolve(route.frontend_route.page_orchestration_skill)) {
+        if (!resolve(route.frontend_route.primary_skill) || !resolve(route.frontend_route.page_generation_skill) || !resolve(route.frontend_route.page_orchestration_skill)) {
           fail(`${routeId}.frontend_route 主入口引用了未登记技能`);
         }
       }

package/template/scripts/lib/skill-supply-chain.mjs

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const SOURCE_ROOT = path.join(ROOT, ".agents/skills");
 const LOCK_PATH = path.join(ROOT, "skills-lock.json");
+const YSS_UI_MANIFEST_PATH = path.join(SOURCE_ROOT, ".yss-skills-manifest.json");
 export const PROJECTION_ROOTS = [".claude/skills", ".codex/skills", ".cursor/skills", ".hermes/skills", ".pi/skills", ".qoder/skills", ".trae/skills"];
 export const OBSOLETE = new Set(["to-" + "prd", "to-" + "issues", "design-an-interface", "qa", "request-refactor-plan", "ubiquitous-language", "edit-article", "obsidian-vault", "writing-great-skills", "code-review-process", "yss-domain-modeling", "yss-dir", "yss-duckdb", "yss-file", "yss-filerunner", "yss-db2mybatis", "yss-mail", "yss-mapper-dynamic", "yss-quality", "yss-sql-condition", "yss-sql-tpl", "yss-valuation", "yss-variable", "yss-openapi", "web-design-engineer", "web-video-presentation", "wireframe-prototype", "wizard", "git-guardrails-claude-code", "claude-handoff", "batch-grill-me", "product-design-prototype", "yss-dictionary", "yss-jdbc", "yss-log", "yss-taskflow", "yss-backend-scaffold-application", "yss-backend-scaffold-domain", "yss-backend-scaffold-infrastructure", "yss-backend-scaffold-web"]);
 export function obsoleteCanonicalResidues(names, obsolete = OBSOLETE) {
@@ -33,6 +34,61 @@ export function treeHash(directory) {
   }
   return digest.digest("hex");
 }
+
+/**
+ * 校验并返回 YSS UI 前端 skills 与 MCP 的上游集成合同。
+ *
+ * @param {unknown} manifest 待校验的清单对象
+ * @returns {Record<string, any>} 已校验的清单
+ */
+export function validateYssUiSkillManifest(manifest) {
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) throw new TypeError("yss-ui 清单必须是对象");
+  const requiredStrings = ["source", "source_type", "source_root", "source_category", "source_revision", "adaptation_ref"];
+  for (const field of requiredStrings) {
+    if (typeof manifest[field] !== "string" || !manifest[field].trim()) throw new TypeError(`yss-ui 清单缺少 ${field}`);
+  }
+  if (manifest.schema_version !== 2) throw new TypeError("yss-ui 清单 schema_version 必须为 2");
+  if (!/^[0-9a-f]{40}$/.test(manifest.source_revision)) throw new TypeError("yss-ui source_revision 必须是完整 Git SHA");
+  if (!manifest.package || typeof manifest.package.name !== "string" || typeof manifest.package.version !== "string") {
+    throw new TypeError("yss-ui 清单缺少 package name/version");
+  }
+  if (!Array.isArray(manifest.excluded_categories) || manifest.excluded_categories.some((item) => typeof item !== "string" || !item)) {
+    throw new TypeError("yss-ui 清单缺少有效 excluded_categories");
+  }
+  if (!Array.isArray(manifest.excluded_skills) || manifest.excluded_skills.some((item) => typeof item !== "string" || !item)) {
+    throw new TypeError("yss-ui 清单缺少有效 excluded_skills");
+  }
+  if (!Array.isArray(manifest.skills) || !manifest.skills.length) throw new TypeError("yss-ui 清单缺少 skills");
+  const upstreamNames = new Set();
+  const canonicalNames = new Set();
+  for (const skill of manifest.skills) {
+    if (!skill || typeof skill.upstream !== "string" || typeof skill.canonical !== "string") throw new TypeError("yss-ui skill 缺少 upstream/canonical");
+    if (skill.upstream === "java-backend-commit") throw new TypeError("yss-ui 前端清单不得包含 java-backend-commit");
+    if (manifest.excluded_skills.includes(skill.upstream)) throw new TypeError(`yss-ui 清单包含已排除 skill: ${skill.upstream}`);
+    if (upstreamNames.has(skill.upstream)) throw new TypeError(`upstream 重复: ${skill.upstream}`);
+    if (canonicalNames.has(skill.canonical)) throw new TypeError(`canonical 重复: ${skill.canonical}`);
+    if (!/^[0-9a-f]{64}$/.test(skill.upstream_hash ?? "")) throw new TypeError(`${skill.canonical} 缺少有效 upstream_hash`);
+    upstreamNames.add(skill.upstream);
+    canonicalNames.add(skill.canonical);
+  }
+  const mcp = manifest.mcp;
+  if (!mcp || typeof mcp.package !== "string" || typeof mcp.version !== "string" || typeof mcp.components_version !== "string" || typeof mcp.server_name !== "string") {
+    throw new TypeError("yss-ui 清单缺少 MCP package/version/server 信息");
+  }
+  if (!Array.isArray(mcp.project_configs) || !mcp.project_configs.length) throw new TypeError("yss-ui 清单缺少 MCP project_configs");
+  const configPaths = new Set();
+  for (const config of mcp.project_configs) {
+    if (!config || typeof config.path !== "string" || !["mcpServers", "servers"].includes(config.container)) throw new TypeError("yss-ui MCP project_config 无效");
+    if (configPaths.has(config.path)) throw new TypeError(`yss-ui MCP config path 重复: ${config.path}`);
+    configPaths.add(config.path);
+  }
+  if (typeof mcp.global_install_guide !== "string" || !mcp.global_install_guide) throw new TypeError("yss-ui MCP 缺少 global_install_guide");
+  return manifest;
+}
+
+function loadYssUiSkillManifest() {
+  return validateYssUiSkillManifest(JSON.parse(readFileSync(YSS_UI_MANIFEST_PATH, "utf8")));
+}
 function git(args) { return spawnSync("git", args, { cwd: ROOT, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }); }
 function tracked(relativePath) { return git(["ls-files", "-z", "--", relativePath]).stdout.length > 0; }
 function parseLock() { return existsSync(LOCK_PATH) ? JSON.parse(readFileSync(LOCK_PATH, "utf8")) : null; }
@@ -140,6 +196,9 @@ function metadata(name, skillPath, directory, previous, canonical = false, sourc
 }
 export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   const oldLock = parseLock(); const previous = priorMetadata(oldLock); const sources = sourceRevisionMap(oldLock, arguments_); const upstreamRoot = option(arguments_, "upstream-root");
+  const yssUiManifest = loadYssUiSkillManifest();
+  sources[yssUiManifest.source] = { ...(sources[yssUiManifest.source] ?? {}), revision: yssUiManifest.source_revision };
+  const yssUiSkills = new Map(yssUiManifest.skills.map((skill) => [skill.canonical, skill]));
   if (upstreamRoot && !existsSync(upstreamRoot)) throw new TypeError(`--upstream-root 不存在: ${upstreamRoot}`);
   const additions = arguments_.filter((arg) => arg.startsWith("--add=")).map((arg) => arg.slice(6));
   const removals = new Set(arguments_.filter((arg) => arg.startsWith("--remove=")).map((arg) => arg.slice(9)));
@@ -152,7 +211,19 @@ export function updateSkillLock(arguments_ = process.argv.slice(2)) {
   if (unlocked.length) throw new TypeError(`发现未登记到 skills-lock.json 的已跟踪共享 skills: ${unlocked.join(", ")}\n确认新增后运行 scripts/update-skill-lock --add=<skill-name>`);
   const targets = [".agents/skills", ...PROJECTION_ROOTS];
   const shared = Object.fromEntries(sharedNames.map((name) => {
-    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot); item.targets = targets; return [name, item];
+    const item = metadata(name, `.agents/skills/${name}/SKILL.md`, path.join(SOURCE_ROOT, name), previous, true, sources, upstreamRoot);
+    const yssUiSkill = yssUiSkills.get(name);
+    if (yssUiSkill) {
+      item.source = yssUiManifest.source;
+      item.sourceType = yssUiManifest.source_type;
+      item.skillPath = `${yssUiManifest.source_root}/${yssUiSkill.upstream}/SKILL.md`;
+      item.sourceRevision = yssUiManifest.source_revision;
+      item.upstreamHash = yssUiSkill.upstream_hash;
+      if (item.effectiveHash !== item.upstreamHash) item.adaptationRef = yssUiManifest.adaptation_ref;
+      else delete item.adaptationRef;
+    }
+    item.targets = targets;
+    return [name, item];
   }));
   const platform = {};
   for (const root of PROJECTION_ROOTS) {