create-yss-spec 2.2.10 → 3.0.1

package/template/docs/agents/yss-skill-registry.yaml

@@ -1,19 +1,127 @@
-schema_version: 1
+schema_version: 2
 registry_id: yss.skill-routing
 status: active
 description: >-
-  技能分层、别名、默认可发现性和 Agent 运行时入口的可执行路由注册表。
-  invocation_contract 提供低成本的调用模式、触发条件、排除条件、主要输出与依赖元数据；不执行三层行为评估，也不替代 skills-lock.json 的来源、hash 与投影完整性职责。
-  Router 与生命周期编排器只消费通过本表校验的 canonical 技能。
+  技能身份、capability、任务模式、类型化依赖、分层、别名和默认可发现性的
+  单一可执行注册表。实现合同编译器与生命周期编排器只消费通过本表校验的
+  canonical 技能；skills-lock.json 继续独立持有来源、hash 与投影完整性。
 canonical_content_root: .agents/skills
 runtime_policy:
-  consumed_by_router: true
+  consumed_by_compiler: true
   consumed_by_lifecycle: true
   discovery_enforced: true
+capability_contract:
+  schema_version: 2
+  id_pattern: "^[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*)+$"
+  dependency_types: [context-required, context-conditional, coordination-only, review-only, component-dependency]
+  task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input, contract-compilation, reroute, result-validation, source-index-refresh]
+  closure:
+    recursive_types: [context-required]
+    conditional_type: context-conditional
+    non_expanding_types: [coordination-only, review-only, component-dependency]
+    deduplicate_skills: true
+    preserve_all_reasons: true
+  deterministic_order: [recipe-declaration, dependency-topology, skill-id]
+capabilities:
+  - { id: governance.implementation-contract, primary_skill: yss-implementation-contract-compiler, task_modes: [contract-compilation, reroute, result-validation] }
+  - { id: maintenance.skill-source-index, primary_skill: yss-skill-source-index-refresh, task_modes: [component-maintenance, source-index-refresh] }
+  - { id: architecture.tactical-domain, primary_skill: yss-tactical-design, task_modes: [guidance, integration, slice-implementation, review-input] }
+  - { id: layer.domain, primary_skill: yss-domain, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: layer.application, primary_skill: yss-application, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: layer.persistence, primary_skill: yss-repository, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: layer.web-adapter, primary_skill: yss-web-controller, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: contract.dto-wire, primary_skill: yss-dto, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: contract.request-validation, primary_skill: yss-validation, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: contract.error-mapping, primary_skill: yss-exception, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: framework.mybatis, primary_skill: yss-mybatis, task_modes: [guidance, integration, slice-implementation, troubleshooting, review-input] }
+  - { id: quality.java-code-style, primary_skill: alibaba-java-code-style, task_modes: [guidance, slice-implementation, review-input] }
+  - { id: codegen.mapstruct, primary_skill: mapstruct, task_modes: [integration, slice-implementation, troubleshooting, review-input] }
+  - { id: codegen.lombok, primary_skill: lombok, task_modes: [integration, slice-implementation, troubleshooting, review-input] }
+  - { id: component.cache, primary_skill: yss-cache, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.current-user-context, primary_skill: yss-userinfo, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.audit-log, primary_skill: yss-audit-log, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.excel-import-export, primary_skill: yss-excel-mvc, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.distributed-id, primary_skill: yss-distributed-id, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.security-algorithm, primary_skill: yss-security-algorithm, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: component.gateway-resilience, primary_skill: yss-resilience4j, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
+  - { id: scaffold.ddd, primary_skill: yss-ddd-scaffold-generator, task_modes: [integration, component-maintenance] }
+  - { id: scaffold.mvc, primary_skill: yss-mvc-scaffold-generator, task_modes: [integration, component-maintenance] }
+  - { id: migration.springboot3, primary_skill: yss-up-springboot3, task_modes: [guidance, integration, troubleshooting, component-maintenance, review-input] }
+recipes:
+  - { id: backend.domain-behavior, capabilities: [layer.domain, layer.application, quality.java-code-style] }
+  - { id: backend.persistence-mybatis, capabilities: [layer.persistence, framework.mybatis, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
+  - { id: backend.http-api, capabilities: [layer.web-adapter, contract.dto-wire, contract.request-validation, contract.error-mapping, codegen.mapstruct, codegen.lombok, quality.java-code-style] }
+  - { id: backend.current-user-context, capabilities: [component.current-user-context, contract.dto-wire] }
+  - { id: backend.cached-current-user, capabilities: [component.current-user-context, component.cache, contract.dto-wire] }
+  - { id: backend.audit-event, capabilities: [component.audit-log, component.current-user-context, contract.dto-wire] }
+  - { id: backend.excel-import-export, capabilities: [component.excel-import-export, contract.dto-wire, contract.request-validation, contract.error-mapping] }
+  - { id: backend.gateway-resilience, capabilities: [component.gateway-resilience, contract.error-mapping] }
+  - { id: backend.security-algorithm, capabilities: [component.security-algorithm, contract.error-mapping] }
+  - { id: backend.distributed-id, capabilities: [component.distributed-id] }
+  - { id: backend.ddd-scaffold, capabilities: [scaffold.ddd, quality.java-code-style] }
+  - { id: backend.mvc-scaffold, capabilities: [scaffold.mvc, quality.java-code-style] }
+  - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
+skill_dependencies:
+  yss-prototype-stage:
+    - { skill: prototype-review, type: review-only }
+    - { skill: yss-design-system, type: coordination-only }
+    - { skill: yss-antd-design, type: context-conditional, when: h2-react-antd }
+  yss-ddd-scaffold-generator:
+    - { skill: yss-backend-scaffold-parent, type: context-required }
+    - { skill: alibaba-java-code-style, type: context-required }
+  yss-domain:
+    - { skill: alibaba-java-code-style, type: context-required }
+    - { skill: domain-modeling, type: coordination-only }
+    - { skill: yss-tactical-design, type: context-conditional, when: tactical-domain }
+    - { skill: lombok, type: context-conditional, when: pojo }
+  yss-tactical-design:
+    - { skill: domain-modeling, type: coordination-only }
+    - { skill: yss-openapi-draft-review, type: review-only, when: api-impact }
+    - { skill: yss-repository, type: component-dependency, when: data-impact }
+  yss-application:
+    - { skill: alibaba-java-code-style, type: context-required }
+    - { skill: mapstruct, type: context-conditional, when: conversion }
+    - { skill: lombok, type: context-conditional, when: pojo }
+  yss-repository:
+    - { skill: yss-mybatis, type: context-conditional, when: mybatis }
+    - { skill: mapstruct, type: context-conditional, when: conversion }
+    - { skill: lombok, type: context-conditional, when: pojo }
+    - { skill: alibaba-java-code-style, type: context-required }
+  yss-web-controller:
+    - { skill: yss-dto, type: context-required }
+    - { skill: yss-validation, type: context-conditional, when: request-validation }
+    - { skill: yss-exception, type: context-conditional, when: error-mapping }
+    - { skill: mapstruct, type: context-conditional, when: conversion }
+    - { skill: lombok, type: context-conditional, when: pojo }
+    - { skill: alibaba-java-code-style, type: context-required }
+  yss-userinfo:
+    - { skill: yss-dto, type: component-dependency }
+    - { skill: yss-cache, type: context-conditional, when: cache-lookup }
+  yss-audit-log:
+    - { skill: yss-userinfo, type: component-dependency }
+    - { skill: yss-dto, type: component-dependency }
+  yss-validation:
+    - { skill: yss-exception, type: component-dependency }
+  yss-security-algorithm:
+    - { skill: yss-exception, type: component-dependency }
+  yss-exception:
+    - { skill: yss-dto, type: context-required }
+  yss-ui-business-page-generation:
+    - { skill: yss-components, type: context-conditional, when: components }
+    - { skill: yss-hook, type: context-conditional, when: hooks }
+    - { skill: yss-formily, type: context-conditional, when: form }
+    - { skill: yss-api-integration, type: context-conditional, when: api }
+  yss-page-module-development:
+    - { skill: yss-components, type: context-conditional, when: components }
+    - { skill: yss-hook, type: context-conditional, when: hooks }
+    - { skill: yss-formily, type: context-conditional, when: form }
+    - { skill: yss-api-integration, type: context-conditional, when: api }
+  yss-api-integration:
+    - { skill: yss-openapi-governance, type: context-conditional, when: regeneration }
 invocation_contract:
-  schema_version: 1
-  scope: routing-and-dependencies-only
-  required_fields: [invocation_mode, trigger_conditions, exclusion_conditions, primary_output, required_dependencies, optional_dependencies]
+  schema_version: 2
+  scope: discovery-only
+  required_fields: [invocation_mode, trigger_conditions, exclusion_conditions, primary_output]
   allowed_invocation_modes: [user, model, both]
   trigger_source: impacts
   trigger_encoding: "impact:<impact>"
@@ -22,8 +130,6 @@ invocation_contract:
     trigger_conditions: [registered-skill-request]
     exclusion_conditions: [no-trigger-match]
     primary_output: skill-guidance
-    required_dependencies: []
-    optional_dependencies: []
   layer_defaults:
     core:
       invocation_mode: both
@@ -37,12 +143,21 @@ invocation_contract:
     maintainer-only:
       invocation_mode: user
       primary_output: maintenance-operation
-  overrides: {}
+  overrides:
+    yss-prototype-stage:
+      invocation_mode: both
+      trigger_conditions: [impact:prototype]
+      exclusion_conditions: [no-product-design-impact]
+      primary_output: artifact.prototype-deliverable
+    yss-antd-design:
+      invocation_mode: model
+      trigger_conditions: [prototype-profile:H2, component-basis:react-antd]
+      exclusion_conditions: [prototype-profile:H1, component-basis:not-antd]
+      primary_output: versioned-antd-facts
 agent_runtime_roots:
   claude: .claude/skills
   codex: .codex/skills
   cursor: .cursor/skills
-  hermes: .hermes/skills
   pi: .pi/skills
   qoder: .qoder/skills
   trae: .trae/skills
@@ -197,11 +312,11 @@ skills:
     instance_default_discoverable: true
     aliases: []
     impacts: [prototype]
-  - id: research
+  - id: yss-research
     layer: core
     maturity: supported
     instance_default_discoverable: true
-    aliases: []
+    aliases: [research]
     impacts: [discovery]
   - id: resolving-merge-conflicts
     layer: core
@@ -425,6 +540,12 @@ skills:
     instance_default_discoverable: false
     aliases: [microapp-commit]
     impacts: [frontend]
+  - id: yss-mvc-scaffold-generator
+    layer: specialist
+    maturity: supported
+    instance_default_discoverable: false
+    aliases: []
+    impacts: [backend]
   - id: yss-mybatis
     layer: specialist
     maturity: supported
@@ -473,7 +594,7 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend]
-  - id: yss-router
+  - id: yss-implementation-contract-compiler
     layer: core
     maturity: supported
     instance_default_discoverable: true
@@ -491,7 +612,7 @@ skills:
     instance_default_discoverable: false
     aliases: []
     impacts: [backend]
-  - id: yss-source-index
+  - id: yss-skill-source-index-refresh
     layer: maintainer-only
     maturity: supported
     instance_default_discoverable: false

package/template/docs/api/templates/openapi-draft-review-checklist.md

@@ -16,8 +16,8 @@
 | 原型 / 线框图 |  |  |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |  |
 | 原型评审结论 | `docs/.scratch/<feature>/design/<feature>-prototype-review.md` |  |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` | 有 UI 时必需；主题/视觉标准必须为 Ant Design v6，并通过 YSS Product Design adapter + `product-design:index` 路由产出或记录例外原因；生产 API 为 YSS UI + Ant Design Vue 4.x |
-| AntD CLI 校验证据 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` 或评审记录 | 有 UI 时必需；记录 design.md / info / demo / token / semantic 查询 |
+| 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL | 有产品设计影响时必需；必须引用 schema v3 档位决策与交付物验证 |
+| 条件 AntD 事实 | `prototype-evidence.yaml` 的档位证据 | H1 不适用；H2 使用 AntD 时引用新鲜 fact pack 或增量 CLI；不得作为生产 YSS/AntDV 组件事实 |
 | 用户确认记录 | `docs/.scratch/<feature>/design/<feature>-prototype-confirmation.md` | 有 UI 时必需；未确认前不得进入 OpenAPI Draft 评审 |
 | YSS 工程基线 | `.codex/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md` |  |
 | YSS DTO wire profile | `.agents/skills/yss-dto/references/openapi-wire-profile.yaml`；`scripts/verify-yss-dto-openapi-profile` |  |
@@ -37,7 +37,7 @@
 | YAML 权威性 | 单一 OAS 3.1 document；未混入生命周期 frontmatter / 根字段；`operationId` 稳定 |  |  |
 | P0 覆盖 | 每个 P0 需求有 endpoint/schema/error/test 或明确非目标 |  |  |
 | 产品总体设计完整 | Draft 已依据 Spec 和产品总体设计 / 功能架构；缺产品总体设计时返回上游补齐 |  |  |
-| 交互输入完整 | 有 UI 时，Draft 已同时依据交互说明、原型/线框、状态矩阵、prototype-review、Ant Design v6 主题/视觉标准高保真 HTML 原型、schema v2 AntD/语义映射/浏览器/无障碍证据和用户确认记录；无 UI 时需说明页面 / 交互资产不适用原因 |  |  |
+| 交互输入完整 | 有产品设计影响时，Draft 已同时依据交互说明、低保真、状态矩阵、prototype-review、H1/H2 原型交付物、schema v3 浏览器/Design QA/条件 AntD 事实和用户确认；无产品设计影响时说明不适用原因 |  |  |
 | DDD 契约边界 | Endpoint/schema 归属的限界上下文清楚；术语与 `CONTEXT.md` 和功能架构一致；契约不直接暴露内部聚合、Repository 或持久化表结构 |  |  |
 | 页面动作覆盖 | 每个按钮 / 抽屉 / 弹窗动作有 endpoint/non-goal、`actionKey` 和错误码；Spec 明确认认证 / 授权变化时同时映射该行为 |  |  |
 | 对象生命周期 | manage/maintain/configure/create/update/archive/retry/cancel/publish/export/create-draft 语义闭环 |  |  |

package/template/docs/architecture/templates/engineering-baseline-review-template.md

@@ -76,10 +76,10 @@ owner: ai
 | 检查项 | 结论 | 证据 / 备注 |
 |---|---|---|
 | 原型确认已完成，或已记录 `not-applicable` 原因 | 是 / 否 / 不适用 | `prototype_confirmation` |
-| `scaffold_status=required` 时先由 Router 编译脚手架合同并经生命周期批准，再使用 `yss-ddd-scaffold-generator` | 是 / 否 / 不适用 | 结构化 `contract_id` / `contract_version`、Router draft、批准引用、持久化引用和生成结果 |
+| `scaffold_status=required` 时先由 实现合同编译器 编译脚手架合同并经生命周期批准，再使用 `yss-ddd-scaffold-generator` | 是 / 否 / 不适用 | 结构化 `contract_id` / `contract_version`、实现合同编译器 draft、批准引用、持久化引用和生成结果 |
 | 脚手架生成结果只包含工程结构、配置和机械模板 | 是 / 否 | 禁止生成业务行为 |
 | 生成器输入、预期文件和实际 `./mvnw validate` / `./mvnw test` / `./mvnw package` 已留证 | 是 / 否 | 每条命令记录 `exit_code`、`duration_ms`、stdout/stderr 引用和执行时间；打印命令不算证据 |
-| `yss-backend-scaffold-parent` 基线校验已完成并重新进入 `yss-router` | 是 / 否 / 不适用 |  |
+| `yss-backend-scaffold-parent` 基线校验已完成并重新进入 `yss-implementation-contract-compiler` | 是 / 否 / 不适用 |  |
 | 脚手架后所有业务代码均绑定批准 Slice Implementation Contract 和 YSS Skill Execution Result | 是 / 否 |  |
 
 ## 5. 完成标准
@@ -92,7 +92,7 @@ owner: ai
 - [ ] `baseline_id` / `baseline_version` 已登记，后续切片和审查只引用该质量基线，未重复定义。
 - [ ] 命中高风险影响时已完成 Doubt-Driven 主张、反证、证据和残余风险记录；未命中时已记录 `not-applicable` 原因。
 - [ ] 风险影响、验证证据和责任人已记录。
-- [ ] 原型确认后已按脚手架顺序完成工程基线、生成器、`yss-backend-scaffold-parent` 和 Router 重编译；脚手架未生成业务行为。
+- [ ] 原型确认后已按脚手架顺序完成工程基线、生成器、`yss-backend-scaffold-parent` 和 实现合同编译器 重编译；脚手架未生成业务行为。
 
 ## 6. 下一步门禁
 

package/template/docs/design/README.md

@@ -18,7 +18,7 @@ node .template-source/tooling/node/scripts/design-md.mjs drift
 
 令牌变更必须先修改 `DESIGN.md`，再更新派生快照；业务状态、API、权限和交互验收继续使用 Spec、交互说明及状态矩阵。
 
-产品原型产出默认以 `product-design:index` 为主入口。该 skill 只负责路由，实际按 Product Design plugin 规则进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill；YSS 生命周期仍负责校验低保真评审、高保真 HTML 原型、AntD CLI 校验证据、用户确认和 Spec / OpenAPI 回填。
+产品原型由 `yss-prototype-stage` 持有阶段合同：先评审低保真/状态矩阵，再选择 H1 视觉或 H2 流程，并按需调用 `product-design:index` focused workflow。YSS 生命周期负责校验档位选择、schema v3 交付物、统一 Design QA、用户确认和 Spec / OpenAPI 回填。原型阶段不得调用生产实现技能 `yss-ui`。
 
 进入 Spec 初稿 / 需求基线流程后，必须先沉淀产品总体设计 / 功能架构，再进入页面 / 原型 / 交互设计、Spec 校准、API 影响分析 / 契约草案或实现。产品总体设计文档必须包含低保真原型 / 页面草图，用于验证页面结构、关键操作和主流程。无 UI 的功能也需要产品总体设计 / 功能架构来说明功能域、业务对象、模块边界、API / 数据影响和不适用的页面状态；只有不进入 Spec 生命周期的小改动可在影响面评估中记录不适用原因。
 
@@ -31,7 +31,7 @@ node .template-source/tooling/node/scripts/design-md.mjs drift
 - 表单、表格、弹窗、抽屉、步骤流等交互说明。
 - loading、empty、error、readonly、disabled、no-permission、conflict 等状态矩阵。
 - 页面字段、筛选条件、操作按钮和权限规则。
-- 低保真原型评审通过后的 Ant Design v6 主题/视觉标准高保真可交互 HTML 原型，默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`；标准 React 原型组件精确锁定与 CLI 一致的 `antd@6.x`，通过 YSS Product Design adapter 消费项目 token、pnpm、同视口 QA 和无障碍证据。生产组件/API 仍是 Vue 3 + YSS UI + 实现仓 lockfile 的 Ant Design Vue 4.x。产出后必须记录 schema v2 原型证据并获得用户确认。
+- 原型交付物默认路径为 `docs/.scratch/<feature>/design/prototypes/index.html`，也可为稳定 URL。H1 无 Node/AntD 依赖；H2 支持 React/Vite + AntD 但按需使用。真实 Vue 3 + YSS UI/AntDV 组件只在批准后的前端实现和实现还原验证中使用。产出后必须记录 schema v3 证据并获得用户确认。
 
 这些资产用于反推 API 影响、契约草案、OpenAPI 请求 / 响应字段、错误结构、分页筛选、权限状态和前端验收标准。
 
@@ -41,18 +41,18 @@ node .template-source/tooling/node/scripts/design-md.mjs drift
 - `docs/design/templates/interaction-spec-template.md`：页面、流程、交互、Spec 回填项和 OpenAPI 反推清单。
 - `docs/design/templates/state-matrix-template.md`：loading、empty、error、readonly、no-permission、conflict 等状态。
 - `docs/design/templates/prototype-review-checklist.md`：进入 Spec 校准 / API 影响分析 / 契约草案前的原型评审门禁。
-- `docs/design/templates/prototype-confirmation-template.md`：高保真 HTML 原型产出后的用户确认记录。
-- `docs/design/templates/prototype-evidence-template.yaml`：原型阶段的 AntD CLI、浏览器验证、评审和确认的机器可读证据清单。
+- `docs/design/templates/prototype-confirmation-template.md`：原型交付物验证后的用户确认记录。
+- `docs/design/templates/prototype-evidence-template.yaml`：schema v3 原型档位、浏览器、统一 Design QA、条件组件事实、评审和确认的机器可读证据清单。
 
 推荐技能：
 
 - `yss-design-system`：项目设计系统与 Ant Design 企业级 UI 风格基线；页面设计、原型评审、UI 实现和主题 token 落地时默认先引用。Codex `$design-qa` 的 token / 字体对照读该技能的 `references/design-qa-theme.md`，以项目覆盖为准，不改上游 `design-qa` 插件。
 - `yss-prototype-stage`：跨 Agent 的原型阶段主合同，固定资产、证据、设计优先级与生命周期回流；其 `references/product-design-adapter.md` 把 Codex `product-design:index` 通用产出接入 YSS 双轨版本、项目主题和证据合同。
 - `product-design:index`：Codex 产品原型产出的主路由；根据输入是否有 URL、截图、Figma、代码目标或视觉方向，进入 `$get-context`、`$ideate`、`$prototype`、`$image-to-code`、`$url-to-code`、`$share` 或 `$design-qa` 等 focused skill。
-- Product Design focused skills：基于 Spec 初稿和产品总体设计 / 功能架构，产出低保真 / 高保真页面、原型、交互设计资产和可分享原型；高保真 HTML 原型默认由该路由链路产出。
-- `yss-antd-design`：仅用于原型设计构建的 Ant Design v6 事实技能；生成或修改高保真 HTML 原型前后必须留下 CLI 校验证据。前端代码落地改用 `yss-ui`。
+- Product Design focused skills：按 H1/H2 的问题边界产出视觉或流程设计资产；ideation 只在新/不确定视觉方向时强制。
+- `yss-antd-design`：仅用于相关 H2 React/AntD 原型的版本事实或 fact pack 增量更新；H1 不适用。
 - `prototype-review`：原型阶段评审门禁；未通过则不要进入 Spec 校准 / API 影响分析 / 契约草案。
-- 兼容入口：`product-design-prototype`、`high-fidelity-html-prototype` 仅作为历史兼容或产物门禁名称保留；新的产品原型产出默认使用 `product-design:index`，已退休技能不再提供兼容路由。
+- 兼容入口：`product-design-prototype`、`high-fidelity-html-prototype` 只读迁移；新资产统一使用 `artifact.prototype-deliverable`、`yss-prototype-stage` 与 schema v3。
 
 推荐目录：
 

package/template/docs/design/design.md

@@ -63,7 +63,7 @@ node .template-source/tooling/node/scripts/design-md.mjs drift
 
 Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以本文件和 `docs/design/tokens/*` 为 source visual truth，而不是官方默认或历史 `#1677ff` / `Inter` / `8px` 品牌圆角。执行清单见 `.agents/skills/yss-design-system/references/design-qa-theme.md`。
 
-版本边界固定为双轨：高保真原型以 React Ant Design v6 的 `design.md`、semantic token 和标准组件事实作为主题样式基线；生产实现使用 Vue 3、YSS UI 与目标实现仓 lockfile 中的 Ant Design Vue 4.x API。两者版本号不同不是冲突。原型到生产只迁移视觉角色、项目 Token、状态和验收行为，禁止迁移 React hook、props、JSX、静态 API 或事件模型。
+版本边界按原型档位处理：H1 直接消费项目 Token；H2 仅在采用 React AntD 时以 Ant Design v6 的 `design.md`、semantic token 和标准组件事实为补充。原型阶段不得调用 `yss-ui`；生产实现进入批准切片后才从目标实现仓 lockfile 中读取 Vue 3、YSS UI 与 Ant Design Vue 的真实 API。原型到生产只迁移视觉角色、项目 Token、状态和验收行为，禁止把 React hook、props、JSX、静态 API 或事件模型当作 Vue 合同。
 
 ## 设计原则
 
@@ -181,7 +181,7 @@ Codex `$design-qa` 的 Colors/tokens 与 Fonts/typography 对照必须以本文
 
 ### 紧凑密度（默认原型规格）
 
-高保真原型和中后台数据密集页面默认使用紧凑密度。紧凑密度不是把所有间距机械缩小，而是使用 `docs/design/tokens/tokens.compact.json` 和下表控制页面节奏；没有明确的展示型或触屏场景时，不切回宽松密度。
+原型交付物和中后台数据密集页面默认使用紧凑密度。紧凑密度不是把所有间距机械缩小，而是使用 `docs/design/tokens/tokens.compact.json` 和下表控制页面节奏；没有明确的展示型或触屏场景时，不切回宽松密度。
 
 | 场景 | Padding | Margin / Gap | 说明 |
 | --- | --- | --- | --- |
@@ -266,24 +266,32 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 避免大面积渐变、装饰插画、夸张 hero、过多卡片化包装和单色系视觉堆叠。
 - 权限不足、只读、空数据、加载中、校验失败、冲突、提交成功等状态必须在设计阶段明确。
 
-## 高保真原型交付规格
+## 原型交付规格
 
-高保真原型的主产物是可在浏览器运行和复验的 HTML，而不是截图、设计说明或生产前端代码。默认入口固定为 `docs/.scratch/<feature>/design/prototypes/index.html`；关联 CSS、JavaScript、字体和本地资源应与入口一起存放在该目录内，保持相对路径可移植。
+原型交付物必须提供可在浏览器运行或复验的稳定入口，而不是只给截图、设计说明或生产前端代码。默认入口为 `docs/.scratch/<feature>/design/prototypes/index.html`；也可交付稳定 URL。关联资源保持相对路径可移植，不强制内联成单文件。
 
-- HTML 必须呈现真实页面密度、Card、表单、筛选、表格、弹层和状态反馈；不得只输出静态画布或图片热区。
-- 默认启用本文件定义的紧凑密度：页面 padding、区域 gap、Card `8px` 圆角、Card padding 和 `28px` 控件高度必须可在浏览器计算样式中复核。
-- 至少覆盖主流程、一个 loading / empty 状态，以及一个 error / no-permission / conflict 状态；主操作必须产生可见反馈。
-- HTML 是评审与确认主载体；截图只作为指定视口和指定状态的验证证据，不能替代 HTML。
-- 原型可以使用构建工具生成，但交付目录必须提供稳定的 `index.html` 入口。依赖开发服务器时，证据中必须记录启动命令、实际端口和版本；不得只交付无法独立定位入口的源码目录。
-- 标准组件存在 Ant Design 实现时，React 原型必须精确锁定与 CLI 查询一致的 `antd@6.x`，使用 pnpm lockfile，并通过 `ConfigProvider` 消费由 `docs/design/tokens/theme.json` 转换出的可执行 ThemeConfig。生产映射仍以 YSS UI / Ant Design Vue 4.x lockfile 为准。
-- Design QA、浏览器验证和视觉目标必须使用同一视口与同一状态；默认 desktop `1440×900`、mobile `390×844`，按实际影响追加其他视口。
-- 原型仍须通过 `prototype-review`、AntD CLI 事实核对和浏览器验证；HTML 存在不代表 `gate.prototype-reviewed`、`gate.prototype-verified` 或 `gate.user-confirmation` 已通过。
+低保真与状态矩阵经独立 `prototype-review` 后，按风险选择满足当前决策的最低档位：
+
+| 档位 | 用途 | 技术边界 | 最低验证 |
+|---|---|---|---|
+| H1 `visual-review` | 布局、密度、层级、文案和少量关键交互 | 语义 HTML/CSS/最小 JS 或设计工具导出；无需 Node、package、lockfile 或 AntD CLI | desktop/narrow 非空渲染、项目 Token、console、关键交互、基础键盘/焦点/对比度；zoom/reduced-motion 按影响 |
+| H2 `flow-review` | 主流程、权限、失败恢复、复杂联动和冲突 | 浏览器可运行流程；React/Vite + AntD v6 是受支持默认而非强制 | H1 共同证据 + 主流程、关键异常、zoom/reduced-motion；视觉回归按风险 |
+
+- H1 不得为了“显得完整”创建空 `package.json`、lockfile 或 AntD 证据。H2 不得声明真实目标组件已验证。
+- 原型中识别出的生产组件假设与待验行为写入 `implementation_handoff`，由 `frontend_implementation_plan` 和 `frontend_implementation_verification` 承接；不得在原型阶段引入 `yss-ui`、目标 lockfile 或 Storybook。
+- 新视觉方向、信息架构不确定或有多个合理方案时执行三方案 ideation；复用已批准视觉模式时记录 source visual 与 `not-applicable` 理由。
+- 默认启用紧凑密度；页面 padding、gap、Card 圆角、Card padding 和控件高度必须在浏览器计算样式中可复核。
+- Design QA、浏览器验证和视觉目标使用同一视口与同一状态；默认 desktop `1440×900`、narrow `390×844`。
+- Design QA 统一覆盖 visual、layout、interaction、content、accessibility、cross-platform 六轴，不再复制第二份检查清单。
+- AntD fact pack 仅在精确版本、组件集合、项目 Token baseline digest 相同且没有新 API 疑问时复用；否则做增量查询。`lint/doctor` 只在存在相关 React 源时执行。
+- 原型源码默认 throwaway；项目 Token、组件语义映射、状态、测试场景和验收标准可以进入下游，源码复用仍需 实现合同编译器、Slice Contract 与 TDD。
+- 用户确认只覆盖原型确认的决定、可操作范围、模拟/gap 与接受结论；HTML、story 或截图存在都不代表三个产品设计门禁已经通过。
 
 ### 无障碍覆盖
 
 品牌 Seed `#3371ff` 保持项目身份，不等于每个组件状态都必须直接使用该填充。普通文本或控件状态不满足 WCAG 2.2 AA 时，优先通过组件 Token 调整实际填充色或文字色，并同时验证 default、hover、active、disabled 与 focus；不得用单页特例色绕过主题层。
 
-原型证据至少覆盖对比度、键盘导航、焦点顺序与可见焦点、语义标签和 Dialog 焦点管理、200% zoom、`prefers-reduced-motion`、目标尺寸及自动化扫描。组件库默认能力不能替代对真实页面 DOM 与交互的验证。
+原型证据按档位覆盖无障碍：所有档位至少检查对比度、键盘导航、焦点顺序与可见焦点；H2 追加语义标签/Dialog、200% zoom、`prefers-reduced-motion`、目标尺寸及适用扫描。组件库默认能力不能替代对真实页面 DOM 与交互的验证。
 
 ## 响应式验收矩阵
 
@@ -318,7 +326,7 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 组件样式优先通过 Ant Design token、component token、CSS variables 或主题算法表达。
 - 消息、通知、Modal 静态方法应使用 `App`、hook API 或 context holder，避免主题上下文丢失。
 - 暗色模式使用 `darkAlgorithm` 或 `docs/design/tokens/variables.dark.css`，不要手工反转颜色。本轮只同步了暗色的字体栈和圆角 seed；完整暗色色板仍是历史算法结果，启用暗色前应再派生一次。
-- 紧凑模式默认使用 `compactAlgorithm` 或 `docs/design/tokens/tokens.compact.json`，不要逐组件压缩高度；高保真 HTML 必须按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
+- 紧凑模式默认使用 `compactAlgorithm` 或 `docs/design/tokens/tokens.compact.json`，不要逐组件压缩高度；原型交付物必须按紧凑 token 验收实际 padding、gap、Card 圆角和控件高度。
 
 如果前端不是 Ant Design：
 
@@ -345,13 +353,13 @@ Margin 使用规则：组件自身默认不声明外部 margin，兄弟元素之
 - 将 `docs/design/tokens/theme.json` 接入前端工程主题配置。
 - 将 `docs/design/tokens/variables.css` 中的 `--brand-*` 与运行时别名纳入项目 token 管理。
 - 如果项目启用暗色模式，用 `darkAlgorithm` 按新 seed 重派生 `docs/design/tokens/tokens.dark.json`，并补充截图验收。
-- 将高保真 HTML 原型模板默认接入 `docs/design/tokens/tokens.compact.json`，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
+- 让三档原型适配器默认接入项目 Token，并在浏览器证据中记录实际计算后的 padding、gap、Card 圆角和控件高度。
 
 ## Ant Design v6 原型补充基线
 
-本节根据官方 `https://ant.design/design.md` 与本轮固定目标版本的 `antd design.md --format json` 提炼，用于高保真原型和后续前端实现，不替代项目 token，也不提供 Ant Design Vue API。
+本节根据官方 `https://ant.design/design.md` 与目标版本的 `antd design.md --format json` 提炼，仅用于采用 React AntD 的 H2 和语义映射，不替代项目 token，也不提供 Ant Design Vue API。
 
 - 先按 `bg-layout`、`bg-container`、`bg-elevated`、文本、边框、状态、圆角和阴影等 semantic token 角色设计，再映射到 `ConfigProvider`、组件 token 或 CSS variables；不得用页面局部色值替代主题层。
-- 默认亮色使用 `theme.defaultAlgorithm`；高保真原型默认叠加紧凑密度 algorithm，暗色和紧凑密度均通过 theme algorithm 切换，禁止手工反色或逐控件压缩。
+- 默认亮色使用 `theme.defaultAlgorithm`；相关 H2 默认叠加紧凑密度 algorithm，暗色和紧凑密度均通过 theme algorithm 切换，禁止手工反色或逐控件压缩。
 - 每个决策区域只保留一个 single primary action。保存、提交、审批、发布、导出和重试等动作必须提供 interaction feedback；不可逆或高风险动作使用确认弹窗。
 - 对实际字号、图标和背景复核 accessibility contrast。默认 token 不足时，通过种子 token 或组件 token 调整，不引入单页特例色。

package/template/docs/design/templates/interaction-spec-template.md

@@ -12,8 +12,8 @@
 | Discovery | `docs/.scratch/<feature>/discovery/<feature>-discovery.md` | 可选 |
 | 原型阶段合同 / Product Design 路由 | `yss-prototype-stage -> product-design:index -> <focused skill>` | 必需；记录 `$get-context`、`$ideate`、`$prototype`、`$image-to-code` 或 `$url-to-code` |
 | 原型 / 线框图 | `<链接或导出图片路径>` | Excalidraw / Figma / Penpot / tldraw / Axure / Markdown |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` | 低保真原型评审通过后补齐；主题/视觉标准必须为 Ant Design v6，标准 React 组件锁定 antd@6，生产映射为 YSS UI + Ant Design Vue 4.x；产出后必须获得用户确认 |
-| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 记录实际 CLI / AntD 版本、CLI JSON 输出、浏览器验证和阻塞项 |
+| 原型交付物 | `docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL | 低保真评审后按 H1/H2 档位补齐；H2 AntD 条件取事实；真实组件待验事项交接到前端实现计划，产出后必须获得用户确认 |
+| 原型验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` | 记录 schema v3 档位、浏览器、统一 Design QA、条件组件证据和阻塞项 |
 | 现有 API 草案 | `docs/.scratch/<feature>/api/<feature>.yaml` | 可选；通常应先完成产品设计和 Spec 校准 |
 
 ## 2. 页面地图
@@ -105,8 +105,8 @@
 - loading、empty、error、no-permission、readonly、conflict、dirty-form 状态已展示，或明确不适用。
 - 每个表格列、筛选条件、表单字段、抽屉、弹窗和按钮都有数据来源或契约反推说明。
 - 设计可以拆成独立可演示的垂直切片。
-- 低保真原型评审通过后，高保真 HTML 原型使用 Ant Design v6 主题/视觉标准覆盖主流程、关键状态和响应式断点，并记录到生产 YSS UI/Ant Design Vue 4.x 的语义映射。
-- 原型产出前已使用 `antd` CLI 查询设计语言、组件 API、demo、token 和 semantic 信息；原型产出后已在 `prototype-evidence.yaml` 记录实际版本、CLI 与浏览器验证证据。
+- 低保真评审通过后，记录档位触发与待确认决定；H1 覆盖视觉和少量交互，H2 覆盖主流程/关键异常。
+- H2 只有实际使用 React AntD 且 fact pack 不新鲜时才执行增量 CLI 查询；H1 不创建 AntD 证据。任何原型档位都不得调用 `yss-ui` 或声明已验证真实生产组件。
 
 ## 9. 决策与未决问题
 

package/template/docs/design/templates/prototype-confirmation-template.md

@@ -1,6 +1,6 @@
-# <功能名称> 高保真原型确认记录
+# <功能名称> 原型交付物确认记录
 
-> 适用时机：Ant Design v6 主题/视觉标准高保真 HTML 原型产出后、Spec 校准 / 需求冻结 / UI 驱动 OpenAPI Draft 前。生产 API 仍为 YSS UI + Ant Design Vue 4.x；未确认前不得进入下游门禁。
+> 适用时机：H1/H2 原型交付物验证后、Spec 校准 / 需求冻结 / UI 驱动 OpenAPI Draft 前。用户只确认设计决定、可操作范围与模拟/gap；未确认前不得进入下游门禁。
 
 ## 1. 原型信息
 
@@ -12,24 +12,22 @@
 | 交互说明 | `docs/.scratch/<feature>/design/<feature>-interaction-spec.md` |
 | 状态矩阵 | `docs/.scratch/<feature>/design/<feature>-state-matrix.md` |
 | 原型评审 | `docs/.scratch/<feature>/design/<feature>-prototype-review.md` |
-| 高保真 HTML 原型 | `docs/.scratch/<feature>/design/prototypes/index.html` |
+| 原型档位与交付物 | `<H1/H2>`；`docs/.scratch/<feature>/design/prototypes/index.html` 或稳定 URL |
 | 机器可读验证清单 | `docs/.scratch/<feature>/verification/prototype-evidence.yaml` |
-| Product Design 路由 | `product-design:index -> <focused skill>` |
+| 原型路由 | `yss-prototype-stage -> H1/H2 -> <adapter>` |
 | 产出方式 | 系统 / Agent 自动产出 / 人工补充 |
-| Ant Design 目标版本 | `<实际项目选择的 v6 版本>` |
 
-## 2. AntD CLI 校验证据
+## 2. 用户需要确认的范围
 
-| 校验项 | 命令 / 记录路径 | 结论 |
+| 项目 | 内容 |
 |---|---|---|
-| 设计语言 | `antd design.md --format json` |  |
-| 组件 API | `antd info <Component> --version <target_antd_version> --format json` |  |
-| 组件 demo | `antd demo <Component> <demo> --version <target_antd_version> --format json` |  |
-| 组件 token | `antd token <Component> --version <target_antd_version> --format json` |  |
-| semantic | `antd semantic <Component> --version <target_antd_version> --format json` |  |
-| lint / 替代校验 | `antd lint <prototype path> --format json` |  |
-
-CLI 实际版本、目标 AntD 版本、完整 JSON 输出与浏览器验证结论以 `prototype-evidence.yaml` 为准；不得用本文中的示例版本替代实际记录。
+| 本原型确认的决定 |  |
+| 可操作范围 |  |
+| 模拟数据 / 模拟行为 |  |
+| 未关闭 gap |  |
+| 接受的差异或非目标 |  |
+
+技术栈、CLI、lockfile、digest 和扫描结果由 `prototype-evidence.yaml` 自动或工程验证记录，不要求用户确认。
 
 ## 3. 用户确认