create-yss-spec 2.1.5 → 2.1.7

package/template/.codex/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/.codex/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/.codex/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/.codex/skills/yss-design-system/SKILL.md

@@ -80,7 +80,7 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 | Spec 后做页面 / 原型 / 交互说明 | `yss-prototype-stage` → `product-design:index` |
 | 低保真原型进入高保真前评审 | `prototype-review` |
 | 低保真评审通过后的高保真 HTML 原型 | `yss-prototype-stage`；`high-fidelity-html-prototype` 仅兼容入口 |
-| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 / `excalidraw-diagram-generator` |
+| 低保真线框或流程图 | `product-design:index` 或 `wireframe-prototype` 兼容入口 |
 | 前端页面实现 | `yss-ui` / `yss-page-module-development` |
 | 表单 schema | `yss-formily` |
 | YTable / YTree / 高度自适应 | `yss-components` / `yss-use-table-height` / `yss-use-tree-height` |
@@ -96,4 +96,4 @@ description: Use when YSS 产品设计系统与 Ant Design 企业级 UI 风格
 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. 运行 `.agents/skills/yss-design-system/scripts/validate-frontmatter.py` 和 markdown/diff 基础检查；若当前环境安装了 `PyYAML`，再运行 skill-creator 的 `quick_validate.py`。
+6. 运行 `node .agents/skills/yss-design-system/scripts/validate-frontmatter.mjs`、对应 `node --test` 和 markdown/diff 基础检查。

package/template/.codex/skills/yss-design-system/scripts/validate-frontmatter.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function validateFrontmatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) throw new Error("Invalid SKILL.md frontmatter block");
+  const fields = new Map();
+  for (const line of match[1].split("\n")) {
+    if (!line.trim()) continue;
+    const index = line.indexOf(":");
+    if (index < 0) throw new Error(`Invalid frontmatter line: ${line}`);
+    fields.set(line.slice(0, index).trim(), line.slice(index + 1).trim());
+  }
+  const keys = [...fields.keys()].sort();
+  if (keys.join(",") !== "description,name") throw new Error(`Expected keys ['description', 'name'], got ${JSON.stringify(keys)}`);
+  const name = fields.get("name");
+  const description = fields.get("description");
+  if (!/^[a-z0-9-]+$/.test(name)) throw new Error("Invalid skill name: " + name);
+  if (!description || description.length > 1024) throw new Error("Description must be present and <= 1024 chars");
+  return name;
+}
+
+async function main() {
+  const skill = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "SKILL.md");
+  try {
+    const name = validateFrontmatter(await readFile(skill, "utf8"));
+    console.log(`${name} frontmatter ok`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.codex/skills/yss-design-system/scripts/validate-frontmatter.test.mjs

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { validateFrontmatter } from "./validate-frontmatter.mjs";
+
+test("accepts the required skill frontmatter", () => {
+  assert.equal(validateFrontmatter("---\nname: yss-design-system\ndescription: Use when validating a skill.\n---\n"), "yss-design-system");
+});
+
+test("rejects missing and unsupported frontmatter fields", () => {
+  assert.throws(() => validateFrontmatter("# no frontmatter"), /Invalid SKILL/);
+  assert.throws(() => validateFrontmatter("---\nname: bad\nextra: x\n---"), /Expected keys/);
+});

package/template/.codex/skills/yss-dictionary/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-dictionary Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 
@@ -20,34 +20,13 @@ Paths below are source path hints captured at refresh time. If they do not exist
 ## Maven Modules
 
 - `yss-microservice-components/yss-component-dictionary-parent`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-feign`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary`
 
 ## Key Java Entry Points
 
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelImportTemplate.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelTemplate.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/MybatisDicConfiguration.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicController.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicQueryController.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2AddMapping.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2EditMapping.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicBasicConvertor.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicClassConvertor.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/AuditableEntity.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicBasicEntity.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicClassEntity.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicSystemEntity.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/DicQueryGateway.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/impl/DicQueryGatewayImpl.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicBasicRepository.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicClassRepository.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicSystemRepository.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/scheduler/DicCacheScheduler.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/DicService.java`
-- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/impl/DicServiceImpl.java`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicAddCmd.java`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicBasicAddCmd.java`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-client/src/main/java/com/yss/cloud/dic/dto/cmd/DicClassAddCmd.java`
@@ -72,6 +51,27 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/EnableDicManage.java`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/EnableDicManageImportSelector.java`
 - `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary-starter/src/main/java/com/yss/cloud/dic/config/DefaultDicConfiguration.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelImportTemplate.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/DicExcelTemplate.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/config/MybatisDicConfiguration.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicController.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/controller/DicQueryController.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2AddMapping.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/Audit2EditMapping.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicBasicConvertor.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/convertor/DicClassConvertor.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/AuditableEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicBasicEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicClassEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/entity/DicSystemEntity.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/DicQueryGateway.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/gateway/impl/DicQueryGatewayImpl.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicBasicRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicClassRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/repository/DicSystemRepository.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/scheduler/DicCacheScheduler.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/DicService.java`
+- `yss-microservice-components/yss-component-dictionary-parent/yss-component-dictionary/src/main/java/com/yss/cloud/dic/service/impl/DicServiceImpl.java`
 
 ## Recommended Next Reads
 

package/template/.codex/skills/yss-distributed-id/references/source-index.md

@@ -1,11 +1,11 @@
 # yss-distributed-id Source Index
 
-Generated: 2026-08-08T15:43:04+00:00
-Source commit: `a34644e2dfc4eb2bfa2b0a1c69dc6b61cc98539a`
+Generated: 2026-08-17T12:03:37.436Z
+Source commit: `38b556a5081e6c66c0c538cbc1ef839b19996ed3`
 Source worktree: `dirty`
 Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.
 
-This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.py`. Do not hand-edit generated sections.
+This file is generated by `yss-source-index/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.
 
 Paths below are source path hints captured at refresh time. If they do not exist in the current workspace, locate sources using `YSS_SOURCE_ROOT`, CodeGraph, package/class names, Maven artifact names, or repository search before assuming the source is unavailable.
 
@@ -25,8 +25,8 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-distributed-id`
 - `yss-microservice-components/yss-component-leaf`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest`
 
 ## Key Java Entry Points
@@ -62,8 +62,6 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/context/RestGenIdContextHelper.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/feign/YssIdGenFeign.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-feign/src/main/java/com/yss/cloud/leaf/mybatis/FeignAutoIdInterceptor.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
-- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/service/UniqueIdService.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequest.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdRequestOrBuilder.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/GenerateUniqueIdResponse.java`
@@ -73,6 +71,8 @@ Paths below are source path hints captured at refresh time. If they do not exist
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/grpc/protobuf/UniqueIdServiceGrpc.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcClientService.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc-lib/src/main/java/com/yss/cloud/leaf/context/GrpcGenIdContextHelper.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/conf/YssCloudLeafAutoConfiguration.java`
+- `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-grpc/src/main/java/com/yss/cloud/leaf/service/UniqueIdService.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/conf/YssLeafRestConfiguration.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/IdGenController.java`
 - `yss-microservice-components/yss-component-leaf/yss-cloud-leaf-rest/src/main/java/com/yss/cloud/leaf/controller/LeafIdRestResponseFactory.java`

package/template/.codex/skills/yss-domain/SKILL.md

@@ -17,7 +17,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 不适用
 
-- 只生成持久层时，优先 `yss-repository` 或 `yss-db2mybatis`。
+- 只生成持久层时，优先 `yss-repository`。
 - 只生成 Controller 时，优先 `yss-web-controller`。
 - 只初始化项目骨架时，优先 `yss-ddd-scaffold-generator`。
 
@@ -51,7 +51,7 @@ description: 用于构建或重构 YSS 领域层代码。当用户要求设计
 
 ## 协同顺序
 
-- 需要持久层时，再接 `yss-repository` 或 `yss-db2mybatis`
+- 需要持久层时，再接 `yss-repository`
 - 需要 Web 层时，再接 `yss-web-controller`
 - 需要完整工程时，先 `yss-ddd-scaffold-generator`
 

package/template/.codex/skills/yss-dto/SKILL.md

@@ -7,6 +7,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 用于处理 `yss-component-dto` 的使用规范和代码接入。
 
+本 skill 同时负责把中台 DTO 映射到公开 HTTP/JSON 边界。`references/openapi-wire-profile.yaml` 是可复用的机器可读映射源；OpenAPI 治理和 Draft Review 必须消费它，不得各自复制一份 wrapper 或分页字段表。
+
 ## 何时使用
 
 - 用户要定义新的分页查询对象。
@@ -18,13 +20,15 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 1. 优先沿用项目现有 DTO 体系，不重复造返回包装类。
 2. 涉及真实类名、返回结构、分页字段或排障时，先读 `references/source-index.md`，再定位源码或文档。
-3. 先确认当前项目用的是哪一套结果封装，再给出改法。
-4. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
+3. 先确认当前项目用的是哪一套结果封装和实际 import；新契约的 canonical 包是 `com.yss.cloud.dto.result`，`com.yss.cloud.dto.response` 只能作为 legacy / compatibility 线索，不能在新契约中引入。
+4. 需要设计或审查 API 时，先校验 `references/openapi-wire-profile.yaml`，再把 endpoint 的具体 DTO/VO schema 组合到 wrapper；Java 泛型不是 OpenAPI schema。
+5. 只围绕当前 DTO 结构回答，不泛化到整个微服务理论。
 
 ## 源码索引
 
 - 源码位置不要假设固定目录；先按 `yss-source-index/references/source-location.md` 定位。
 - 当前技能索引：`references/source-index.md`
+- OpenAPI wire profile：`references/openapi-wire-profile.yaml`
 - 重点源码入口通常包括 `CommandDTO`、`QueryDTO`、`PageQuery`、`PageRequestFactory`、`Result`、`SingleResult`、`MultiResult`、`PageResult`。
 
 当组件源码变化后，用 `yss-source-index` 刷新索引；刷新或读取前先按源码定位策略确认真实位置。
@@ -37,8 +41,13 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - Controller 返回优先使用项目既有的 `Result` 或派生结果对象。
 - 单对象返回优先 `SingleResult`，列表返回优先 `MultiResult`，分页返回优先 `PageResult`，前提是当前项目已采用这套体系。
 - 三种泛型结果要求 `T extends Serializable`；生成的 VO/响应类型必须满足该编译约束。
-- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`，不能只测试 data。
-- `needTotalCount` / `tempTotalCount` 是内部分页协作字段；当前源码中前者标注暂未实现，二者都不是客户端输入。
+- OpenAPI 响应以 `YssResultMeta` 表达公共字段，并用 `allOf` 叠加 endpoint-specific `data` / page 字段；每个响应声明 `x-yss-response-wrapper: SingleResult|MultiResult|PageResult`，不得把 `SingleResult<T>` 文字写成 schema。
+- wire shape 不是 Java 字段清单：`success` 为 boolean，`dataType` 为 `string|null`，`code` 只允许 `string|integer|null`；不得把全局 `code` 放宽为任意 object。
+- `MultiResult.data` 和 `PageResult.data` 对外是数组，空值按 `[]` 建模；`SingleResult.data` 按 endpoint schema 建模并显式处理 nullability。
+- `PageResult` 当前稳定公共字段为 `totalCount/pageSize/pageIndex/data[]`；`totalPages` 是计算 getter，只有目标 HTTP mapper / contract fixture 证明后才能进入具体契约。
+- `PageQuery` 客户端输入只允许 `pageIndex/pageSize/orderBy/orderDirection/groupBy`（后四项按 profile 的 optional / whitelist 规则）；`orderDirection` 只能是 `ASC|DESC`。`offset`、`needTotalCount`、`tempTotalCount` 是计算或内部协作字段，禁止成为客户端输入。
+- `buildSuccess(...)` 各重载设置 code 的行为并不一致；冻结契约必须测试 `success/code/message/tips/dataType`、nullability 和三种 data shape，不能只测试 data。
+- Java getter、Lombok、`@JsonIgnore` 或默认 Jackson 结果都不是目标 HTTP wire fact；冻结前必须记录 mapper identity、代表性序列化 fixture 和 contract-test / 等价 HTTP 证据。
 - DTO 只表达接口契约，不承载 Repository PO 或领域对象的持久化细节。
 
 ## 检查清单
@@ -48,6 +57,9 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - Service / Repository 是否真的接收到了 `PageQuery`。
 - 新增 DTO 是否与现有序列化和校验方式兼容。
 - 返回结构是否和前端或上游调用方契约一致。
+- 是否通过 `scripts/verify-yss-dto-openapi-profile`，并引用 profile 版本。
+- wrapper extension、`YssResultMeta`、`allOf`、具体 data schema 和方向性是否逐 endpoint 对齐。
+- 是否有针对 `offset` / `needTotalCount` / `tempTotalCount` 的负向断言，以及对 `totalPages` 的目标 mapper 证据。
 - Controller、Application Service、Domain、Repository 之间是否存在 DTO/VO/DO/PO 混穿。
 - 前端 Orval 或调用方是否依赖当前返回包装结构。
 
@@ -55,6 +67,8 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 
 - 不要在一个项目里混用多套返回包装类。
 - 不要新建与 `PageQuery` 含义重叠的分页基类。
+- 不要把 `com.yss.cloud.dto.response` 作为新 API 的 canonical 包，也不要从 Java getter 机械生成 wire schema。
+- 不要把 `offset`、`needTotalCount`、`tempTotalCount` 作为客户端分页输入；不要无证据把 `totalPages` 写入所有分页响应。
 - 若项目已有 `SingleResult`、`PageResult`、`MultiResult` 体系，优先保持一致。
 
 ## 按需读取
@@ -63,6 +77,7 @@ description: Use when YSS `Result`, `SingleResult`, `MultiResult`, `PageResult`,
 - DTO 基类示例：`assets/CommandDTO.java`、`assets/QueryDTO.java`
 - 分页基类：`assets/PageQuery.java`
 - 返回结构：`assets/Result.java`
+- HTTP/JSON 映射：`references/openapi-wire-profile.yaml`
 
 ## 阶段 7 合同