create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: "yss-backend-scaffold-parent"
+description: "YSS 服务的后端开发脚手架框架和技术指南。在开发后端功能、创建新模块或检查架构标准时需要用到。"
+---
+
+# 赢时胜数据质量管理服务后端开发规范 (YSS Data Quality Backend Dev Guide)
+
+本 Skill 包含了项目的核心技术栈、架构设计原则以及开发规范，旨在帮助开发者快速上手并遵循项目标准。
+
+在产品生命周期中，本 Skill 是后端 Engineering Baseline / YSS DDD Review 的入口。它用于确认技术栈、模块边界、依赖方向、DTO/Gateway/Repository 约定和实现前检查；具体代码仍按垂直切片加载 `yss-domain`、`yss-repository`、`yss-web-controller` 等专项 Skill。
+
+## 1. 技术栈 (Tech Stack)
+
+### 核心框架
+
+- **JDK**: 8
+- **Spring Boot**: 2.7.18
+- **Spring Framework**: 5.3.x
+- **ORM**: MyBatis Plus (底层封装于 `yss-component-mybatis-starter`)
+- **连接池**: HikariCP
+
+### 数据库支持
+
+- **MySQL**: 8.0+
+- **Oracle**: 12c+
+- **PostgreSQL**: 12+
+- **OpenGauss**
+- **DuckDB**
+
+### 工具库
+
+- **Lombok**: 减少样板代码
+- **Hutool**: Java 通用工具库
+- **MapStruct**: 高性能对象映射
+- **Jackson**: JSON 处理
+- **Guava**: Google 核心库
+
+### 构建工具
+
+- **Maven**: 3.x (必须使用项目根目录下的 `./mvnw` 脚本进行构建、测试、运行和 CI 验证；不要默认使用裸 `mvn ...` 命令)
+
+## 2. 架构设计 (Architecture)
+
+项目采用基于 DDD (领域驱动设计) 的分层架构：
+
+### 分层职责
+
+1.  **Adapter (适配层)**: `adapter`
+    - 处理外部请求 (Web API, Job Runner)
+    - 适配数据库连接器
+2.  **Application (应用层)**: `application`
+    - 业务用例编排
+    - Command/Query/Event Handlers
+3.  **Domain (领域层)**: `domain`
+    - 核心业务逻辑
+    - 包含：聚合根, 实体, 值对象, 领域服务, 仓储接口
+4.  **Infrastructure (基础设施层)**: `infrastructure`
+    - 仓储接口实现 (Repository Impl)
+    - 外部服务适配
+    - 配置管理
+
+### 模块依赖
+
+- `Domain` 是核心层，不依赖 Application、Infrastructure、Adapter 或 Bootstrap。
+- `Application` 依赖 `Domain`，负责用例编排、事务边界和 Command/Query/Event Handler。
+- `Adapter` / Web 层依赖 `Application`，负责协议适配、参数校验、DTO/VO 转换和统一响应。
+- `Infrastructure` 依赖 `Domain`，实现 Domain 中定义的 Gateway / Repository / 外部系统接口。
+- `Bootstrap` 负责组装和启动，不承载业务规则。
+
+依赖方向必须服务于领域核心，不能让 PO、Mapper、HTTP、RPC、Excel、文件、缓存等基础设施细节泄漏到 Domain。
+
+## 3. 开发规范 (Development Guidelines)
+
+### 命名规范
+
+- **PO (Persistent Object)**: 持久化对象，对应数据库表。
+- **VO (Value Object)**: 视图对象，用于 API 返回。
+- **CMD (Command)**: 命令对象，用于增删改操作参数。
+- **Query**: 查询对象，用于查询条件参数。
+
+### 调用链路
+
+标准的调用流向为：
+`Controller / Adapter` -> `Application Use Case / Handler` -> `Domain Aggregate / Domain Service` -> `Gateway / Repository Interface` -> `Infrastructure Implementation` -> `Database / External System`
+
+不要把传统 `Controller -> Service -> Repository` 三层模型作为默认设计。只有当现有工程已经采用 Application Service 命名时，`Service` 才代表应用层用例编排，不应承载领域规则或直接泄漏持久化细节。
+
+数据转换边界：
+`Request DTO / Command / Query` -> `Domain Model` -> `PO / External DTO` -> `Domain Model` -> `Response VO`
+
+### Repository 开发
+
+- 接口继承 `BasePlusRepository<PO>`。
+- 实体类字段使用 `@TableField` 映射。
+- 主键使用 `@TableId(value = "id", type = IdType.ASSIGN_ID)`。
+- 实体类继承 `AuditableEntity` 以自动处理审计字段 (创建人、时间等)。
+
+### 对象转换
+
+- 必须使用 **MapStruct** 进行对象转换。
+- 定义接口并添加 `@Mapper` 注解。
+
+### API 设计
+
+- 遵循 RESTful 风格 (GET/POST/PUT/DELETE)。
+- 使用统一响应包装类：
+  - 单个对象: `SingleResult<T>`
+  - 列表: `MultiResult<T>`
+  - 分页: `PageResult<T>`
+- 涉及新增或变更前后端契约时，先在 `docs/.scratch/<feature>/api/<feature>.yaml` 形成 OpenAPI Draft，经工程基线、架构 / Spec Delta 设计和设计审查后 Freeze，再实现 Controller、DTO、前端调用和契约测试。
+
+## 4. 工程基线检查清单
+
+进入实现前至少确认：
+
+- 模块是否采用 Domain / Application / Infrastructure / Adapter / Bootstrap 分层，或已有工程的等价边界。
+- 新服务是否先由 `yss-ddd-scaffold-generator` 生成骨架；现有服务是否沿用既有模块和包命名。
+- Domain 是否只包含聚合、实体、值对象、领域服务和 Gateway / Repository 接口。
+- Infrastructure 是否只实现 Gateway / Repository，并隔离 PO、Mapper、SQL、外部系统客户端。
+- Web / Adapter 是否只做协议适配、鉴权上下文、参数校验、DTO/VO 转换和响应包装。
+- Application 是否承载用例编排、事务边界和跨聚合协调，不把领域规则下沉到 Controller 或 Mapper。
+- OpenAPI Draft / Freeze、ADR、测试 seam 和已批准的架构约束是否已经明确。
+
+## 5. 常用命令
+
+```bash
+# 清理并编译
+./mvnw clean compile
+
+# 完整验证
+./mvnw clean verify
+```
+
+## 6. 阶段 7 合同
+
+- 工程基线校验必须消费批准合同、实现仓库登记和 scaffold 状态。
+- 脚手架只属于 `controlled-generation`；生成后必须重新路由业务 work units，不能把骨架标为业务完成。
+- 输出统一 `YSS Skill Execution Result`，包含模块边界、Wrapper、编译/测试、OpenAPI/CI 证据和所有偏离。

package/template/.cursor/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-parent/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Scaffold Parent"
+  short_description: "YSS 后端脚手架父工程、依赖与公共约定实践落地规范"
+  default_prompt: "Use $yss-backend-scaffold-parent to set up the parent project and shared conventions for a YSS backend scaffold."

package/template/.cursor/skills/yss-ddd-scaffold-generator/references/yss-backend-scaffold-web/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: yss-web-layer-reference
+description: Use when the YSS DDD scaffold workflow reaches Web Adapter implementation and needs the shared Web Controller skill.
+---
+
+# Web Adapter Layer Reference
+
+**REQUIRED SUB-SKILL:** Use `yss-web-controller` as the single authoritative Web-layer implementation guide (`references/web-adapter-layer-guide.md`). Do not maintain a second copy under the scaffold generator.

package/template/{.claude/skills → .cursor/skills/yss-ddd-scaffold-generator/references}/yss-backend-scaffold-web/agents/openai.yaml

@@ -2,4 +2,4 @@ version: 1
 interface:
   display_name: "YSS Scaffold Web"
   short_description: "YSS 后端脚手架 Web 层、DTO 与控制器规范"
-  default_prompt: "Use $yss-backend-scaffold-web to implement the web adapter layer for a YSS backend scaffold module."
+  default_prompt: "Use $yss-web-controller to implement the web adapter layer for a YSS backend scaffold module."

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/generate_scaffold.mjs

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/** YSS DDD 后端纯工程骨架生成器；只生成工程结构，不生成任何业务行为。 */
+import { chmod, cp, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile, copyFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SKILL_ROOT = path.resolve(SCRIPT_DIR, "..");
+const REPOSITORY_ROOT = path.resolve(SCRIPT_DIR, "../../../..");
+const COMMANDS = ["./mvnw validate", "./mvnw test", "./mvnw package"];
+
+function fail(message) { throw new Error(message); }
+function isoNow() { return new Date().toISOString(); }
+function localDate() { return new Date().toISOString().slice(0, 10); }
+function backupStamp() { return new Date().toISOString().replace(/[-:TZ.]/g, ""); }
+function usage(error) {
+  const text = `YSS DDD 脚手架生成器\n\n` +
+    `用法: node scripts/generate_scaffold.mjs --project-name <kebab-case> --base-package <package> --output-dir <dir> --contract-file <json> [选项]\n\n` +
+    `必填合同元数据: --contract-id --contract-version --approval-ref --router-draft-ref --persisted-ref\n` +
+    `选项: --database mysql, --force, --overwrite-scope <scope>, --rollback-ref <ref>\n` +
+    `--with-example 已禁用；--without-example 是兼容的无操作参数。`;
+  if (error) process.stderr.write(`错误: ${error}\n\n`);
+  process.stdout.write(`${text}\n`);
+}
+
+function parseArgs(argv) {
+  const options = { database: "mysql", force: false, withExample: false };
+  const mapping = new Map([
+    ["--project-name", "projectName"], ["--base-package", "basePackage"], ["--output-dir", "outputDir"],
+    ["--database", "database"], ["--contract-id", "contractId"], ["--contract-version", "contractVersion"],
+    ["--approval-ref", "approvalRef"], ["--router-draft-ref", "routerDraftRef"], ["--persisted-ref", "persistedRef"],
+    ["--contract-file", "contractFile"], ["--overwrite-scope", "overwriteScope"], ["--rollback-ref", "rollbackRef"],
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    if (token === "--force") { options.force = true; continue; }
+    if (token === "--with-example") { options.withExample = true; continue; }
+    if (token === "--without-example") { options.withExample = false; continue; }
+    const equal = token.indexOf("=");
+    let value;
+    if (equal !== -1) { value = token.slice(equal + 1); token = token.slice(0, equal); }
+    if (!mapping.has(token)) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[mapping.get(token)] = value;
+  }
+  if (options.help) return options;
+  for (const [flag, key] of mapping) {
+    if (["database", "overwriteScope", "rollbackRef", "contractId", "contractVersion", "approvalRef", "routerDraftRef", "persistedRef"].includes(key)) continue;
+    if (!options[key]) fail(`缺少必填参数: ${flag}`);
+  }
+  if (options.database !== "mysql") fail("参数 --database 只支持 mysql");
+  if (!/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("项目名称必须是 kebab-case 格式 (例如: user-service)");
+  if (!/^[a-z](?:[a-z0-9]*)(?:\.[a-z](?:[a-z0-9]*)?)*$/.test(options.basePackage)) fail("包名格式不正确 (例如: com.yss.user)");
+  if (options.contractVersion !== undefined && (!/^\d+$/.test(options.contractVersion) || Number(options.contractVersion) < 1)) fail("--contract-version(必须为正整数)");
+  if (options.contractVersion !== undefined) options.contractVersion = Number(options.contractVersion);
+  if (options.withExample) fail("--with-example 已禁用；业务代码必须由批准的 YSS Slice skill 逐切片生成");
+  return options;
+}
+
+async function exists(target) { try { await lstat(target); return true; } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function isFile(target) { try { return (await stat(target)).isFile(); } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function nonEmpty(target) { const info = await lstat(target); return !info.isDirectory() || (await readdir(target)).length > 0; }
+async function readJson(target, message) { try { return JSON.parse(await readFile(target, "utf8")); } catch (error) { fail(`${message}: ${target}`); } }
+async function writeText(target, content) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content, "utf8"); }
+function isPresent(value) { return value !== undefined && value !== null && value !== "" && (!Array.isArray(value) || value.length > 0); }
+
+class ScaffoldGenerator {
+  constructor(options) {
+    this.options = options;
+    this.projectName = options.projectName;
+    this.basePackage = options.basePackage;
+    this.outputDir = path.resolve(options.outputDir);
+    this.contractFile = path.resolve(options.contractFile);
+    this.finalProjectRoot = path.join(this.outputDir, this.projectName);
+    this.projectRoot = this.finalProjectRoot;
+    this.templateRoot = path.join(SKILL_ROOT, "assets", "templates");
+    this.configTemplateDir = path.join(this.templateRoot, "config");
+    this.pomTemplateDir = path.join(this.templateRoot, "pom");
+    this.packagePath = this.basePackage.replaceAll(".", path.sep);
+    this.author = process.env.USER || "yss-team";
+    this.date = localDate();
+    this.groupId = this.basePackage.split(".").slice(0, 2).join(".");
+    this.dbName = this.projectName.replaceAll("-", "_");
+    this.scaffoldContract = undefined;
+  }
+
+  async generate() {
+    await this.validateHarnessOutputLayout();
+    if (await exists(this.finalProjectRoot) && !this.options.force) fail(`输出目录已存在: ${this.finalProjectRoot}；如确认覆盖，请显式传入 --force`);
+    await this.validateContractMetadata();
+    if (await exists(this.finalProjectRoot) && await nonEmpty(this.finalProjectRoot) && this.options.force) this.validateForceMetadata();
+    await mkdir(this.outputDir, { recursive: true });
+    const stagingRoot = await mkdtemp(path.join(this.outputDir, `.${this.projectName}.staging-`));
+    this.projectRoot = path.join(stagingRoot, this.projectName);
+    try {
+      console.log(`🚀 开始生成项目: ${this.projectName}\n📦 基础包名: ${this.basePackage}\n📁 输出目录: ${this.outputDir}\n`);
+      await this.createProjectStructure(); await this.generatePomFiles(); await this.generateConfigFiles();
+      this.generateDatabaseScripts(); await this.generateDocumentation(); await this.writeGenerationManifest();
+      await this.copyWrapperFiles(); await this.validateGeneratedArtifacts();
+      let backupPath;
+      if (await exists(this.finalProjectRoot)) { backupPath = path.join(this.outputDir, `.${this.projectName}.backup-${backupStamp()}`); await rename(this.finalProjectRoot, backupPath); }
+      await rename(this.projectRoot, this.finalProjectRoot); this.projectRoot = this.finalProjectRoot;
+      console.log(`\n✅ 项目生成完成!\n📂 项目位置: ${this.projectRoot}`);
+      if (backupPath) console.log(`♻️ 原项目备份: ${backupPath}`);
+      console.log(`\n🎯 下一步:\n  cd ${this.projectRoot}\n  ./mvnw validate\n  ./mvnw test\n  ./mvnw package\n  ./mvnw spring-boot:run -pl ${this.projectName}-bootstrap`);
+    } catch (error) { await rm(stagingRoot, { recursive: true, force: true }); throw error; }
+  }
+
+  async validateHarnessOutputLayout() {
+    const relative = path.relative(REPOSITORY_ROOT, this.outputDir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) return; // 外部实现仓库。
+    const parts = relative.split(path.sep).filter(Boolean);
+    if (parts.length >= 2 && parts[0] === "app" && ["backend", "frontend"].includes(parts[1])) fail("禁止使用单数 app/backend 或 app/frontend 作为工程生成路径；Harness 内后端脚手架必须以 apps/backend 为父容器");
+    if (parts.length === 2 && parts[0] === "apps" && parts[1] === "backend") return;
+    if (parts.length >= 2 && parts[0] === "apps" && parts[1] === "frontend") fail("后端脚手架不能输出到 apps/frontend；请使用外部后端仓库或 apps/backend");
+    fail("当前 Harness 内生成后端工程时，输出目录必须是 apps/backend；生成器会以 project_name 创建 apps/backend/<project>/");
+  }
+
+  async validateContractMetadata() {
+    if (!await isFile(this.contractFile)) fail("必须提供已持久化的结构化脚手架合同 JSON 文件: --contract-file");
+    const contract = await readJson(this.contractFile, "脚手架合同文件无法读取或不是合法 JSON");
+    if (!contract || Array.isArray(contract) || typeof contract !== "object") fail("脚手架合同必须是 JSON 对象");
+    const requiredMetadata = [["--contract-id", this.options.contractId], ["--contract-version", this.options.contractVersion], ["--approval-ref", this.options.approvalRef], ["--router-draft-ref", this.options.routerDraftRef], ["--persisted-ref", this.options.persistedRef]];
+    const missing = requiredMetadata.filter(([, value]) => !isPresent(value)).map(([flag]) => flag);
+    if (missing.length) fail(`生成项目必须提供当前已批准脚手架合同的完整元数据: ${missing.join(", ")}`);
+    const required = ["schema_version", "contract_id", "contract_version", "slice_id", "status", "router_draft_ref", "lifecycle_approval_ref", "persisted_ref", "current_version", "implementation_repository", "backend_repository", "scaffold_status", "target_git_url_or_output_dir", "allowed_write_paths", "expected_evidence_files", "verification_commands", "approval", "work_unit", "overwrite_policy"];
+    const missingFields = required.filter((field) => !isPresent(contract[field]));
+    if (missingFields.length) fail(`脚手架合同缺少结构化字段: ${missingFields.join(", ")}`);
+    if (contract.schema_version !== 1 || contract.status !== "approved") fail("脚手架合同必须是 schema_version=1 且已由生命周期批准");
+    if (contract.contract_id !== this.options.contractId) fail("--contract-id 与脚手架合同不一致");
+    if (contract.contract_version !== this.options.contractVersion) fail("--contract-version 与脚手架合同不一致");
+    if (contract.current_version !== contract.contract_version) fail("脚手架合同版本不是当前版本");
+    if (contract.router_draft_ref !== this.options.routerDraftRef) fail("--router-draft-ref 与脚手架合同不一致");
+    if (contract.persisted_ref !== this.options.persistedRef) fail("--persisted-ref 与脚手架合同不一致");
+    if (contract.lifecycle_approval_ref !== this.options.approvalRef) fail("--approval-ref 与脚手架合同不一致");
+    if (contract.scaffold_status !== "required") fail("脚手架生成器只接受 scaffold_status=required");
+    if (!["allowed_write_paths", "expected_evidence_files", "verification_commands"].every((field) => Array.isArray(contract[field]) && contract[field].length)) fail("脚手架合同的 allowed_write_paths、expected_evidence_files、verification_commands 必须非空");
+    if (!contract.expected_evidence_files.map(String).join(" ").includes(".yss/scaffold-generation.json")) fail("脚手架合同 expected_evidence_files 必须包含 .yss/scaffold-generation.json");
+    const targetRef = String(contract.target_git_url_or_output_dir);
+    if (!targetRef.includes("://") && !targetRef.startsWith("git@") && path.resolve(targetRef) !== this.outputDir) fail("脚手架合同目标目录与 --output-dir 不一致");
+    if (JSON.stringify(contract.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架合同验证命令必须固定为三条项目根目录 ./mvnw 命令");
+    const approval = contract.approval;
+    if (!approval || typeof approval !== "object" || ["approval_ref", "approver", "persisted_ref", "current_version"].some((field) => !isPresent(approval[field]))) fail("脚手架合同 approval 记录不完整");
+    if (approval.approval_ref !== this.options.approvalRef || approval.persisted_ref !== this.options.persistedRef) fail("脚手架合同 approval 引用与命令参数不一致");
+    if (approval.current_version !== this.options.contractVersion) fail("脚手架合同 approval 不是当前版本");
+    const workUnit = contract.work_unit;
+    const workFields = ["id", "behavior", "primary_skill", "supporting_skills", "tdd_mode", "allowed_write_paths", "expected_evidence", "verification_commands", "controlled_generation"];
+    if (!workUnit || typeof workUnit !== "object" || workFields.some((field) => !isPresent(workUnit[field]))) fail("脚手架合同 work_unit 结构不完整");
+    if (workUnit.primary_skill !== "yss-ddd-scaffold-generator" || workUnit.tdd_mode !== "controlled-generation" || workUnit.controlled_generation !== true) fail("脚手架合同 work_unit 必须绑定本 skill 和 controlled-generation");
+    if (JSON.stringify(workUnit.verification_commands) !== JSON.stringify(contract.verification_commands) || JSON.stringify(workUnit.allowed_write_paths) !== JSON.stringify(contract.allowed_write_paths)) fail("脚手架合同 work_unit 与根级验证/写路径约束不一致");
+    const overwrite = contract.overwrite_policy;
+    if (!overwrite || typeof overwrite !== "object" || ["force_allowed", "overwrite_scope", "rollback_ref"].some((field) => !(field in overwrite))) fail("脚手架合同 overwrite_policy 结构不完整");
+    this.scaffoldContract = contract;
+  }
+
+  validateForceMetadata() {
+    if (!isPresent(this.options.overwriteScope) || !isPresent(this.options.rollbackRef)) fail("覆盖非空目录必须提供当前批准合同的覆盖范围和回滚引用: --overwrite-scope, --rollback-ref");
+    const policy = this.scaffoldContract.overwrite_policy;
+    if (policy.force_allowed !== true) fail("脚手架合同未批准非空目录覆盖");
+    if (policy.overwrite_scope !== this.options.overwriteScope) fail("--overwrite-scope 与脚手架合同不一致");
+    if (policy.rollback_ref !== this.options.rollbackRef) fail("--rollback-ref 与脚手架合同不一致");
+  }
+
+  templateVars() {
+    const database = this.options.database;
+    const dependency = database === "mysql" ? `<dependency>\n    <groupId>com.mysql</groupId>\n    <artifactId>mysql-connector-j</artifactId>\n    <version>8.4.0</version>\n    <scope>compile</scope>\n</dependency>` : "";
+    return { project_name: this.projectName, base_package: this.basePackage, group_id: this.groupId, project_description: `${this.projectName} service`, author: this.author, date: this.date, database, driver_class: "com.mysql.cj.jdbc.Driver", db_name: this.dbName, jdbc_url: `jdbc:mysql://localhost:3306/${this.dbName}?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai`, db_dependency: dependency };
+  }
+  render(text) { let output = text; for (const [key, value] of Object.entries(this.templateVars())) output = output.replaceAll(`{{${key}}}`, String(value)); return output; }
+  async renderTemplate(template, output) { if (!await isFile(template)) fail(`模板文件不存在: ${template}`); await writeText(output, this.render(await readFile(template, "utf8"))); }
+
+  async createProjectStructure() {
+    console.log("📁 创建项目目录结构...");
+    for (const module of ["domain", "application", "infrastructure", "adapter", "bootstrap"]) {
+      const root = path.join(this.projectRoot, `${this.projectName}-${module}`);
+      await Promise.all([mkdir(path.join(root, "src/main/java", this.packagePath), { recursive: true }), mkdir(path.join(root, "src/main/resources"), { recursive: true }), mkdir(path.join(root, "src/test/java", this.packagePath), { recursive: true })]);
+      console.log(`  ✓ ${this.projectName}-${module}`);
+    }
+    await mkdir(path.join(this.projectRoot, `${this.projectName}-adapter`, `${this.projectName}-web`, "src/main/java", this.packagePath, "rest"), { recursive: true });
+    await mkdir(path.join(this.projectRoot, "db"), { recursive: true });
+    console.log(`  ✓ ${this.projectName}-adapter/${this.projectName}-web\n  ✓ db`);
+  }
+  async generatePomFiles() {
+    console.log("\n📝 生成 Maven POM 文件...");
+    const pom = (name) => path.join(this.pomTemplateDir, name);
+    const target = (module) => path.join(this.projectRoot, module, "pom.xml");
+    await Promise.all([[pom("parent-pom.xml.template"), path.join(this.projectRoot, "pom.xml")], [pom("domain-pom.xml.template"), target(`${this.projectName}-domain`)], [pom("application-pom.xml.template"), target(`${this.projectName}-application`)], [pom("infrastructure-pom.xml.template"), target(`${this.projectName}-infrastructure`)], [pom("adapter-pom.xml.template"), target(`${this.projectName}-adapter`)], [pom("web-pom.xml.template"), target(path.join(`${this.projectName}-adapter`, `${this.projectName}-web`))], [pom("bootstrap-pom.xml.template"), target(`${this.projectName}-bootstrap`)]].map(([from, to]) => this.renderTemplate(from, to)));
+    console.log("  ✓ 父级 pom.xml\n  ✓ domain pom.xml\n  ✓ application pom.xml\n  ✓ infrastructure pom.xml\n  ✓ adapter pom.xml\n  ✓ web pom.xml\n  ✓ bootstrap pom.xml");
+  }
+  async generateConfigFiles() {
+    console.log("\n⚙️  生成配置文件..."); const base = path.join(this.projectRoot, `${this.projectName}-bootstrap`, "src/main/resources");
+    await Promise.all([["application.yml.template", "application.yml"], ["logback-spring.xml.template", "logback-spring.xml"]].map(([from, to]) => this.renderTemplate(path.join(this.configTemplateDir, from), path.join(base, to))));
+    console.log("  ✓ application.yml\n  ✓ logback-spring.xml");
+  }
+  generateDatabaseScripts() { console.log("\n🗃️  保留数据库目录布局...\n  ✓ db/（业务 schema 和初始化数据由批准切片合同生成）"); }
+  async generateDocumentation() {
+    console.log("\n📚 生成项目文档...");
+    await writeText(path.join(this.projectRoot, "README.md"), this.render("# {{project_name}}\n\n## 模块说明\n\n- {{project_name}}-domain\n- {{project_name}}-application\n- {{project_name}}-infrastructure\n- {{project_name}}-adapter\n- {{project_name}}-bootstrap\n\n业务 API、领域模型、数据结构和权限行为必须在冻结的 Slice Implementation Contract 下，由对应 YSS skill 逐切片实现。\n\n## 快速开始\n\n```bash\ncd {{project_name}}\n./mvnw clean compile\n./mvnw spring-boot:run -pl {{project_name}}-bootstrap\n```\n"));
+    console.log("  ✓ README.md");
+  }
+  async writeGenerationManifest() {
+    const contract = this.scaffoldContract;
+    const manifest = { schema_version: 1, contract_id: this.options.contractId, contract_version: this.options.contractVersion, approval_ref: this.options.approvalRef, router_draft_ref: this.options.routerDraftRef, persisted_ref: this.options.persistedRef, contract_file_ref: this.contractFile, slice_id: contract.slice_id, lifecycle_approval_ref: contract.lifecycle_approval_ref, current_version: contract.current_version, approver: contract.approval.approver, allowed_write_paths: contract.allowed_write_paths, expected_evidence_files: contract.expected_evidence_files, project_name: this.projectName, base_package: this.basePackage, database: this.options.database, generation_mode: "controlled-generation", force: this.options.force, overwrite_scope: this.options.overwriteScope, rollback_ref: this.options.rollbackRef, verification_commands: COMMANDS, generated_at: isoNow() };
+    await writeText(path.join(this.projectRoot, ".yss", "scaffold-generation.json"), `${JSON.stringify(manifest, null, 2)}\n`); console.log("  ✓ .yss/scaffold-generation.json");
+  }
+  async copyWrapperFiles() {
+    const wrapper = path.join(SKILL_ROOT, "assets", "wrapper");
+    for (const file of ["mvnw", "mvnw.cmd"]) { const source = path.join(wrapper, file); if (await exists(source)) { const target = path.join(this.projectRoot, file); await mkdir(path.dirname(target), { recursive: true }); await copyFile(source, target); await chmod(target, (await stat(source)).mode); } }
+    if (await exists(path.join(wrapper, ".mvn"))) await cp(path.join(wrapper, ".mvn"), path.join(this.projectRoot, ".mvn"), { recursive: true, force: true });
+  }
+  async validateGeneratedArtifacts() {
+    const required = [path.join(this.projectRoot, "pom.xml"), path.join(this.projectRoot, `${this.projectName}-bootstrap`, "pom.xml"), path.join(this.projectRoot, "mvnw"), path.join(this.projectRoot, ".yss", "scaffold-generation.json")];
+    const missing = []; for (const target of required) if (!await isFile(target)) missing.push(target); if (missing.length) fail(`生成产物缺失: ${missing.join(", ")}`);
+    const manifest = await readJson(required[3], "脚手架生成元数据清单无法读取");
+    if (manifest.contract_id !== this.options.contractId || manifest.contract_version !== this.options.contractVersion || manifest.current_version !== this.options.contractVersion || manifest.generation_mode !== "controlled-generation" || JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) fail("脚手架生成元数据清单与当前批准合同或固定验证命令不一致");
+    const stack = [this.projectRoot], binary = new Set([".class", ".db", ".jar", ".png", ".jpg", ".jpeg", ".gif"]);
+    while (stack.length) { const dir = stack.pop(); for (const entry of await readdir(dir, { withFileTypes: true })) { const target = path.join(dir, entry.name); if (entry.isDirectory()) { stack.push(target); continue; } if (!entry.isFile() || binary.has(path.extname(entry.name))) continue; const content = await readFile(target, "utf8"); if (content.includes("{{") || content.includes("root/root")) fail(`生成文件包含未替换占位符或明文凭据: ${target}`); } }
+  }
+}
+
+async function main() { let options; try { options = parseArgs(process.argv.slice(2)); if (options.help) { usage(); return 0; } await new ScaffoldGenerator(options).generate(); return 0; } catch (error) { process.stderr.write(`\n❌ 生成失败: ${error.message}\n`); return 1; } }
+process.exitCode = await main();

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/run_scaffold_verification.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/** 在生成项目根目录实际执行 YSS 脚手架的固定验证命令并留证。 */
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+
+const PHASES = ["validate", "test", "package"];
+const COMMANDS = PHASES.map((phase) => `./mvnw ${phase}`);
+const isoNow = () => new Date().toISOString();
+async function isFile(target) { try { return (await stat(target)).isFile(); } catch (error) { if (error.code === "ENOENT") return false; throw error; } }
+async function writeText(target, content) { await mkdir(path.dirname(target), { recursive: true }); await writeFile(target, content, "utf8"); }
+function parseArgs(argv) { const result = {}; for (let index = 0; index < argv.length; index += 1) { let token = argv[index]; if (token === "--help" || token === "-h") { result.help = true; continue; } const equals = token.indexOf("="); let value; if (equals !== -1) { value = token.slice(equals + 1); token = token.slice(0, equals); } if (!["--project-root", "--evidence-dir"].includes(token)) throw new Error(`不支持的参数: ${token}`); if (value === undefined) value = argv[++index]; if (!value || value.startsWith("--")) throw new Error(`参数 ${token} 缺少值`); result[token === "--project-root" ? "projectRoot" : "evidenceDir"] = path.resolve(value); } if (result.help) return result; if (!result.projectRoot || !result.evidenceDir) throw new Error("必须提供 --project-root 和 --evidence-dir"); return result; }
+function validateManifest(manifest) {
+  const required = ["schema_version", "contract_id", "contract_version", "slice_id", "approval_ref", "approver", "lifecycle_approval_ref", "router_draft_ref", "persisted_ref", "contract_file_ref", "current_version", "allowed_write_paths", "expected_evidence_files", "verification_commands", "generation_mode"];
+  const missing = required.filter((field) => manifest[field] === undefined || manifest[field] === null || manifest[field] === "");
+  if (manifest.generation_mode !== "controlled-generation" || missing.length) throw new Error(`脚手架生成元数据清单不完整或不是 controlled-generation: ${missing.join(", ")}`);
+  if (manifest.current_version !== manifest.contract_version) throw new Error("脚手架生成元数据清单不是当前合同版本");
+  if (JSON.stringify(manifest.verification_commands) !== JSON.stringify(COMMANDS)) throw new Error("脚手架生成元数据清单验证命令不符合固定合同");
+}
+function execute(wrapper, phase, cwd) { return new Promise((resolve) => { const child = spawn(wrapper, [phase], { cwd, stdio: ["ignore", "pipe", "pipe"] }); let stdout = "", stderr = ""; child.stdout.on("data", (chunk) => { stdout += chunk; }); child.stderr.on("data", (chunk) => { stderr += chunk; }); child.on("error", (error) => resolve({ exitCode: 127, stdout: "", stderr: String(error) })); child.on("close", (code) => resolve({ exitCode: code ?? 1, stdout, stderr })); }); }
+export async function run(projectRoot, evidenceDir) {
+  const wrapper = path.join(projectRoot, "mvnw"), manifestPath = path.join(projectRoot, ".yss", "scaffold-generation.json");
+  if (!await isFile(wrapper)) throw new Error(`项目根目录缺少 Maven wrapper: ${wrapper}`);
+  if (!await isFile(manifestPath)) throw new Error(`项目根目录缺少脚手架生成元数据清单: ${manifestPath}`);
+  let manifest; try { manifest = JSON.parse(await readFile(manifestPath, "utf8")); } catch { throw new Error(`脚手架生成元数据清单无法读取或不是合法 JSON: ${manifestPath}`); }
+  validateManifest(manifest); await mkdir(evidenceDir, { recursive: true }); const commands = [];
+  for (const phase of PHASES) { const stdoutPath = path.join(evidenceDir, `mvnw-${phase}.stdout.log`), stderrPath = path.join(evidenceDir, `mvnw-${phase}.stderr.log`), startedAt = isoNow(), started = process.hrtime.bigint(); const outcome = await execute(wrapper, phase, projectRoot); const durationMs = Number(process.hrtime.bigint() - started) / 1e6; await writeText(stdoutPath, outcome.stdout); await writeText(stderrPath, outcome.stderr); commands.push({ command: `./mvnw ${phase}`, phase, exit_code: outcome.exitCode, duration_ms: Number(durationMs.toFixed(3)), started_at: startedAt, executed_at: isoNow(), stdout_ref: stdoutPath, stderr_ref: stderrPath }); }
+  return { verification_mode: "controlled-generation", project_root: projectRoot, scaffold_manifest_ref: manifestPath, generated_at: isoNow(), status: commands.every((item) => item.exit_code === 0) ? "passed" : "failed", commands };
+}
+async function main() { let args; try { args = parseArgs(process.argv.slice(2)); if (args.help) { console.log("运行 YSS 脚手架真实验证命令\n用法: node scripts/run_scaffold_verification.mjs --project-root <dir> --evidence-dir <dir>"); return 0; } const reportPath = path.join(args.evidenceDir, "scaffold-verification.json"); try { const report = await run(args.projectRoot, args.evidenceDir); await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); console.log(`${report.status}: ${reportPath}`); return report.status === "passed" ? 0 : 1; } catch (error) { const report = { verification_mode: "controlled-generation", project_root: args.projectRoot, generated_at: isoNow(), status: "failed", error: error.message, commands: [] }; await writeText(reportPath, `${JSON.stringify(report, null, 2)}\n`); process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } } catch (error) { process.stderr.write(`❌ 脚手架验证无法执行: ${error.message}\n`); return 1; } }
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) process.exitCode = await main();

package/template/.cursor/skills/yss-ddd-scaffold-generator/scripts/scaffold-generator.test.mjs

@@ -0,0 +1,26 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { chmod, mkdtemp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { run } from "./run_scaffold_verification.mjs";
+
+const scripts = path.dirname(fileURLToPath(import.meta.url));
+const generator = path.join(scripts, "generate_scaffold.mjs");
+const command = (args, options = {}) => new Promise((resolve) => execFile(process.execPath, [generator, ...args], { encoding: "utf8", ...options }, (error, stdout, stderr) => resolve({ code: error?.code ?? 0, stdout, stderr })));
+function contract(outputDir, overrides = {}) {
+  return { schema_version: 1, contract_id: "scaffold-1", contract_version: 1, slice_id: "slice-1", status: "approved", router_draft_ref: "router-1", lifecycle_approval_ref: "approval-1", persisted_ref: "persisted-1", current_version: 1, implementation_repository: "external", backend_repository: "external", scaffold_status: "required", target_git_url_or_output_dir: outputDir, allowed_write_paths: ["."], expected_evidence_files: [".yss/scaffold-generation.json"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], approval: { approval_ref: "approval-1", approver: "reviewer", persisted_ref: "persisted-1", current_version: 1 }, work_unit: { id: "unit-1", behavior: "scaffold", primary_skill: "yss-ddd-scaffold-generator", supporting_skills: ["yss-router"], tdd_mode: "controlled-generation", allowed_write_paths: ["."], expected_evidence: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], controlled_generation: true }, overwrite_policy: { force_allowed: true, overwrite_scope: "replace-service", rollback_ref: "checkpoint-1" }, ...overrides };
+}
+async function fixture() { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-node-")); const output = path.join(root, "implementation"); await mkdir(output); const contractFile = path.join(root, "contract.json"); await writeFile(contractFile, `${JSON.stringify(contract(output), null, 2)}\n`); return { root, output, contractFile, args: ["--project-name", "demo-service", "--base-package", "com.yss.demo", "--output-dir", output, "--database", "mysql", "--contract-id", "scaffold-1", "--contract-version", "1", "--approval-ref", "approval-1", "--router-draft-ref", "router-1", "--persisted-ref", "persisted-1", "--contract-file", contractFile] }; }
+
+test("生成批准合同下的纯工程骨架，并写入清单", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const result = await command(data.args); assert.equal(result.code, 0, result.stderr); const project = path.join(data.output, "demo-service"); const manifest = JSON.parse(await readFile(path.join(project, ".yss/scaffold-generation.json"), "utf8")); assert.equal(manifest.generation_mode, "controlled-generation"); assert.deepEqual(manifest.verification_commands, ["./mvnw validate", "./mvnw test", "./mvnw package"]); assert.match(await readFile(path.join(project, "pom.xml"), "utf8"), /demo-service/); });
+
+test("拒绝不一致合同和未经明确批准的非空目录覆盖", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const rejected = await command([...data.args.slice(0, -1), path.join(data.root, "missing.json")]); assert.equal(rejected.code, 1); assert.match(rejected.stderr, /合同/); await mkdir(path.join(data.output, "demo-service")); await writeFile(path.join(data.output, "demo-service", "keep.txt"), "keep"); const noForce = await command(data.args); assert.equal(noForce.code, 1); assert.match(noForce.stderr, /--force/); const forceMissingRollback = await command([...data.args, "--force"]); assert.equal(forceMissingRollback.code, 1); assert.match(forceMissingRollback.stderr, /覆盖范围和回滚引用/); });
+
+test("已批准的 --force 先备份非空目标，再提交 staging 工程", async (t) => { const data = await fixture(); t.after(() => rm(data.root, { recursive: true, force: true })); const oldProject = path.join(data.output, "demo-service"); await mkdir(oldProject); await writeFile(path.join(oldProject, "old.txt"), "recoverable"); const result = await command([...data.args, "--force", "--overwrite-scope", "replace-service", "--rollback-ref", "checkpoint-1"]); assert.equal(result.code, 0, result.stderr); const entries = await readdir(data.output); const backup = entries.find((entry) => entry.startsWith(".demo-service.backup-")); assert.ok(backup); assert.equal(await readFile(path.join(data.output, backup, "old.txt"), "utf8"), "recoverable"); assert.ok((await readdir(path.join(data.output, "demo-service"))).includes("pom.xml")); });
+
+test("验证器记录三条 wrapper 命令的成功和失败证据", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\n[ \"$1\" = test ] && exit 2\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const evidence = path.join(root, "evidence"); const report = await run(project, evidence); assert.equal(report.status, "failed"); assert.deepEqual(report.commands.map((item) => item.exit_code), [0, 2, 0]); assert.match(await readFile(path.join(evidence, "mvnw-test.stderr.log"), "utf8"), /^$/); });
+
+test("验证器在全部 Maven 命令成功时通过并保留日志引用", async (t) => { const root = await mkdtemp(path.join(os.tmpdir(), "yss-scaffold-verifier-success-")); t.after(() => rm(root, { recursive: true, force: true })); const project = path.join(root, "project"); await mkdir(path.join(project, ".yss"), { recursive: true }); await writeFile(path.join(project, ".yss/scaffold-generation.json"), `${JSON.stringify({ schema_version: 1, contract_id: "id", contract_version: 1, slice_id: "slice", approval_ref: "approval", approver: "reviewer", lifecycle_approval_ref: "approval", router_draft_ref: "router", persisted_ref: "persisted", contract_file_ref: "contract", current_version: 1, allowed_write_paths: ["."], expected_evidence_files: ["manifest"], verification_commands: ["./mvnw validate", "./mvnw test", "./mvnw package"], generation_mode: "controlled-generation" })}\n`); const wrapper = path.join(project, "mvnw"); await writeFile(wrapper, "#!/bin/sh\nprintf 'ran %s\\n' \"$1\"\n"); await chmod(wrapper, 0o755); const report = await run(project, path.join(root, "evidence")); assert.equal(report.status, "passed"); assert.ok(report.commands.every((item) => item.exit_code === 0 && item.stdout_ref.endsWith(".stdout.log"))); });

package/template/.cursor/skills/yss-design-system/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: yss-design-system
+description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格基线。涉及页面设计、原型评审、UI 实现、组件选型、主题 token、颜色排版间距、响应式验收、Ant Design/YSS UI 风格一致性、docs/design/design.md 更新或从外部设计系统引入规范时必须使用。
+---
+
+# YSS Design System
+
+本技能用于把项目 UI 统一到一套可执行的设计系统基线：Ant Design 企业后台风格、YSS 页面工程习惯、设计 token、组件语义、交互状态和响应式验收。
+
+## 权威资料
+
+- 项目设计系统文档：`docs/design/design.md`，作为团队可读的唯一规范来源。
+- 项目 token 快照：`docs/design/tokens/theme.json`、`docs/design/tokens/tokens.default.json`、`docs/design/tokens/tokens.dark.json`、`docs/design/tokens/tokens.compact.json`、`docs/design/tokens/variables.css`、`docs/design/tokens/variables.dark.css`。
+- 本技能执行清单：`references/design-system.md`，用于 Agent 执行和评审，不替代 `docs/design/design.md`。
+- 历史输入包：`/Users/zhudaoming/Downloads/Product-Design-System`，只用于追溯首次引入来源，不作为后续工程依赖。
+- 默认亮色覆盖：项目 Ant Design 5 Less / `:root` 变量已裁定进 `docs/design/design.md` 与 token 快照；原始 Less 不是实现语言。
+- Codex `$design-qa` 项目对照：`references/design-qa-theme.md`，不替代官方 `design-qa` 流程，也不改上游插件正文。
+- 原型阶段合同：`yss-prototype-stage`，用于统一跨 Agent 的原型资产和浏览器验证证据。AntD 事实由 `yss-antd-design` 提供，且只用于原型设计构建。
+
+如果只需要快速判断，先读本文件。若要写 UI 规范、实现页面、评审设计或调整 token，必须读项目内 `docs/design/design.md`；若要执行评审或实现检查，再读 `references/design-system.md`。
+
+## 使用流程
+
+1. 先判断任务阶段：设计系统引入 / 产品设计 / 原型评审 / 前端实现 / UI 改造 / 主题 token 落地。
+2. 读取已有资产：`docs/design/design.md`、相关 Spec、交互说明、状态矩阵、OpenAPI Draft、现有页面代码。
+3. 按设计系统基线约束输出或修改产物：颜色、排版、间距、圆角、动效、组件、状态、响应式。
+4. 若是产品设计阶段，先使用 `yss-prototype-stage`；Codex 以 `product-design:index` 为主入口，其他 Agent 必须交付等价合同资产和证据。
+5. 若是前端实现阶段，配合 `yss-ui`、`yss-components`、`yss-formily`、`yss-page-module-development`，但本技能负责风格与体验一致性门禁。
+6. 若发现现有设计系统文档不足，先更新 `docs/design/design.md`，再让实现或评审引用该文档。
+
+## 核心基线
+
+- UI 定位：中后台、数据密集、表单密集、流程密集、可扫描、低装饰。
+- 主色：`#3371ff`（`--primary-color` / `--brand-color-primary`），用于主操作、链接、焦点、选中态和激活导航。
+- 默认字号：14px；主要字重：400 / 600；字体栈为系统字体，不强制 `Inter`。
+- 默认控件高度：32px；默认圆角 6px。
+- 间距：4px 网格，优先使用 token，不写任意 magic number。
+- 运行时换肤：短名 CSS 变量必须指向 `--brand-*`，不要再维护第二套色值。
+- 表面层级：页面背景、内容容器、浮层三层模型。
+- 组件语言：优先 Ant Design / YSS UI 语义，不自造同类控件。
+- 状态完整性：loading、empty、error、readonly、disabled、no-permission、conflict、success 必须在设计或实现中可解释。
+- Ant Design v6 原型基线：先用语义 token 定义角色，再用组件 token 或 CSS variables 落地；不以局部硬编码替代主题层。
+
+## 强制规则
+
+- 不把该系统改造成营销落地页风格；业务应用首屏应直接进入可用工作界面。
+- 不用大面积渐变、装饰插画、夸张 hero、过度卡片化或单色系视觉堆叠替代信息结构。
+- 不在同一决策区域放两个 primary 按钮。
+- 每个页面或决策区域只保留一个 single primary action；其余动作降级为默认、链接或危险操作。
+- 不硬编码表面色、边框色、状态色；优先使用 token 或主题变量。
+- 交互原型中的每个可点击主动作都必须给出 interaction feedback：状态变化、禁用原因、成功或失败反馈至少覆盖其一。
+- accessibility contrast：默认 token 不能满足目标文本对比度时，优先通过 `ConfigProvider` seed / component token 调整，不新增页面级特例色。
+- React + Ant Design 的暗色或紧凑密度必须使用 theme algorithm，不手工反转颜色或逐控件压缩尺寸。
+- 不用 Tag 表达关键错误、阻断或审批状态；关键状态必须有可读文本和语义反馈。
+- 不让按钮、标签、表头、弹窗、卡片中的文字溢出或遮挡。
+- 不在表格 / 筛选 / 批量操作密集页面使用松散营销式布局。
+
+## 产出要求
+
+设计类任务至少输出：
+
+- 设计系统引用：明确引用 `docs/design/design.md`。
+- 页面和模块：页面清单、布局结构、主路径、异常路径。
+- 组件选择：YSS UI / Ant Design 组件映射。
+- 状态矩阵：加载、空、错、禁用、只读、无权限、冲突、成功。
+- API 反推：字段、筛选、分页、动作、错误码、权限、并发或幂等规则。
+- 响应式要求：关键断点和窄屏替代形态。
+
+实现类任务至少检查：
+
+- 是否通过 `ConfigProvider`、CSS variables 或项目 token 消费主题。
+- 是否将颜色、圆角、阴影和状态样式绑定到 semantic token，而不是复制表面色和交互色。
+- 是否保持 32px 默认控件高度、14px 默认正文、4px 间距网格。
+- 是否使用 YSS UI / Ant Design 的语义组件，而不是自造同类组件。
+- 是否保留 hover、focus、active、disabled、loading、error、empty 状态。
+- 是否为可提交、导出、保存、发布、审批等操作提供明确的 interaction feedback 与不可逆操作确认。
+- 是否在核心视口无横向溢出；表格横向滚动必须被限定在表格容器内。
+
+## 与其他技能的关系
+
+| 场景 | 配合技能 |
+| --- | --- |
+| Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
+| 低保真原型进入高保真前评审 | `prototype-review` |
+| 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
+| 低保真线框或流程图 | `product-design:index` |
+| 前端页面实现 | `yss-ui` / `yss-page-module-development` |
+| 表单 schema | `yss-formily` |
+| YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
+| 原型阶段的 Ant Design v6 组件 / token / demo 查询 | `yss-antd-design`（只用于原型设计构建；前端落地改用 `yss-ui`） |
+| Codex 原型交接前的视觉 QA | `design-qa`；token / 字体对照读 `references/design-qa-theme.md`，以项目覆盖为准 |
+| API 契约 / 接入 | `yss-openapi-governance` / `api-integration` |
+
+## 更新设计系统
+
+当用户要求“引入设计系统”“形成项目规范”“更新设计系统 skill”时：
+
+1. 分析来源设计系统，不原样堆拷贝。
+2. 将稳定规范落到 `docs/design/design.md`。
+3. 将 Agent 执行入口落到 `.agents/skills/yss-design-system/SKILL.md`。
+4. 将 Agent 执行检查清单更新到 `.agents/skills/yss-design-system/references/design-system.md`。
+5. 更新 `docs/design/README.md` 和必要的 `AGENTS.md` 入口规则。
+6. 运行 `node .agents/skills/yss-design-system/scripts/validate-frontmatter.mjs`、对应 `node --test` 和 markdown/diff 基础检查。

package/template/.cursor/skills/yss-design-system/agents/openai.yaml

@@ -0,0 +1,5 @@
+version: 1
+interface:
+  display_name: "YSS Design System"
+  short_description: "YSS 产品设计系统与 Ant Design 风格基线"
+  default_prompt: "Use $yss-design-system to design or review a YSS UI against the project design system."