create-yss-spec 3.0.0 → 3.0.1

package/template/.codex/skills/yss-mvc-scaffold-generator/scripts/generate_project.test.mjs

@@ -0,0 +1,337 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, readdir, rm, stat, writeFile, mkdir } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "generate_project.mjs");
+const verifyScript = path.join(path.dirname(fileURLToPath(import.meta.url)), "verify_project.mjs");
+const harnessRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const gitAuthorEnvironment = {
+  GIT_CONFIG_COUNT: "1",
+  GIT_CONFIG_KEY_0: "user.name",
+  GIT_CONFIG_VALUE_0: "Scaffold Tester"
+};
+function run(args, options = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
+    encoding: "utf8",
+    ...options,
+    env: { ...process.env, ...gitAuthorEnvironment, ...(options.env ?? {}) }
+  });
+}
+async function expectedDistributedLock() {
+  const lock = JSON.parse(await readFile(path.join(harnessRoot, "skills-lock.json"), "utf8"));
+  delete lock.skills?.shared?.["yss-mvc-scaffold-generator"];
+  for (const platform of Object.values(lock.skills?.platform ?? {})) delete platform?.["yss-mvc-scaffold-generator"];
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+test("生成固定六模块和 mock endpoint", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-scaffold-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "item1"); const result = run(["--project-name", "data-analysis-item1", "--base-package", "com.yss.dataanalysis.item1", "--target-dir", target, "--database", "oracle", "--with-mock"]);
+  assert.equal(result.status, 0, result.stderr); const backend = target; const pom = await readFile(path.join(backend, "pom.xml"), "utf8");
+  const skillUtils = path.join(base, "skillUtils");
+  for (const module of ["server", "core", "client", "repository", "adapter", "feign-client"]) assert.match(pom, new RegExp(`<module>${module}</module>`));
+  const controller = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/controller/AnalysisController.java"), "utf8"); assert.match(controller, /\/api\/analysis/); assert.doesNotMatch(controller, /;[ \t]+import /);
+  assert.match(controller, /\* \u6570\u636e\u5206\u6790\u67e5\u8be2\u63a5\u53e3\u3002/);
+  assert.match(controller, /@author Scaffold Tester/);
+  assert.match(controller, /@date \d{4}\/\d{2}\/\d{2} \d{2}:\d{2}/);
+  assert.match(controller, /\* \u5206\u9875\u67e5\u8be2\u6570\u636e\u5206\u6790\u7ed3\u679c\u3002[\s\S]*@param query[\s\S]*@return \u6570\u636e\u5206\u6790\u5206\u9875\u7ed3\u679c/);
+  const mock = await readFile(path.join(backend, "adapter/src/main/java/com/yss/dataanalysis/item1/adapter/mock/MockAnalysisQueryExecutor.java"), "utf8"); assert.match(mock, /source|"mock"/);
+  const configuration = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/configuration/AnalysisConfiguration.java"), "utf8"); assert.match(configuration, /Profile\("mock"\)/); assert.match(configuration, /Profile\("oracle & !mock"\)/);
+  await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/Application.java"), "utf8");
+  const controllerTest = await readFile(path.join(backend, "server/src/test/java/com/yss/dataanalysis/item1/server/controller/AnalysisControllerTest.java"), "utf8");
+  assert.match(controllerTest, /pageNo/);
+  assert.match(await readFile(path.join(target, "yss-project.yaml"), "utf8"), /repository_mode: project-instance/);
+  assert.match(await readFile(path.join(target, "CONTEXT.md"), "utf8"), /AnalysisDataset/);
+  assert.match(await readFile(path.join(target, ".artifact-workspace.yaml"), "utf8"), /kind: service/);
+  assert.match(await readFile(path.join(target, "docs/service/module-map.md"), "utf8"), /feign-client/);
+  assert.match(await readFile(path.join(target, "docs/service/current-capabilities.md"), "utf8"), /普通功能开发不手工修改/);
+  assert.match(await readFile(path.join(target, "docs/process/implementation-repo-registry.yaml"), "utf8"), /repository_scope: external-repository/);
+  const analysisProject = await readFile(path.join(target, "docs/process/analysis-project.yaml"), "utf8"); assert.match(analysisProject, /project_name: data-analysis-item1/); assert.doesNotMatch(analysisProject, /galaxy-data-analysis|fegin-client/);
+  assert.match(await readFile(path.join(target, "docs/process/lifecycle-registry.yaml"), "utf8"), /schema_version:/);
+  assert.match(await readFile(path.join(target, "docs/templates/vertical-slice-ticket-template.md"), "utf8"), /status: ready-for-human/);
+  assert.match(await readFile(path.join(target, "docs/templates/local-parent-ticket-template.md"), "utf8"), /lifecycle_status \| routing \/ running \/ paused-human-gate \/ blocked \/ completed/);
+  const lifecycleContract = await readFile(path.join(skillUtils, ".agents/skills/yss-product-lifecycle/references/orchestration-contract.yaml"), "utf8");
+  assert.match(lifecycleContract, /entry_routing:/);
+  assert.match(lifecycleContract, /workflow_execution_result:/);
+  assert.match(lifecycleContract, /work_unit_routes:/);
+  assert.match(await readFile(path.join(target, "docs/templates/approval-record-template.yaml"), "utf8"), /gate_id:/);
+  assert.match(await readFile(path.join(target, "docs/templates/implementation-routing-template.md"), "utf8"), /implementation/);
+  assert.match(await readFile(path.join(target, "docs/templates/verification-record-template.md"), "utf8"), /verification/i);
+  await readFile(path.join(skillUtils, ".agents/skills/yss-product-lifecycle/SKILL.md"), "utf8");
+  for (const projection of [".agents", ".claude", ".codex", ".cursor", ".pi", ".qoder", ".trae"]) {
+    await assert.rejects(stat(path.join(skillUtils, projection, "skills/yss-mvc-scaffold-generator")), { code: "ENOENT" });
+  }
+  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
+  assert.equal(spawnSync("git", ["-C", target, "branch", "--show-current"], { encoding: "utf8" }).stdout.trim(), "main");
+  assert.equal(spawnSync("git", ["-C", target, "rev-list", "--all", "--count"], { encoding: "utf8" }).stdout.trim(), "0");
+  assert.equal(spawnSync("git", ["-C", target, "remote"], { encoding: "utf8" }).stdout.trim(), "");
+  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
+  assert.equal(verification.status, 0, verification.stderr);
+  await assert.rejects(stat(path.join(skillUtils, ".agents/skills/data-analysis-java-implementation")), { code: "ENOENT" });
+  const implementationRegistry = await readFile(path.join(target, "docs/process/implementation-repo-registry.yaml"), "utf8");
+  assert.doesNotMatch(implementationRegistry, /data-analysis-java-implementation|verify_java_web_style\.mjs/);
+  assert.match(implementationRegistry, /fmt-maven-plugin:2\.9\.1:check/);
+  assert.doesNotMatch(implementationRegistry, /smart-doc-maven-plugin:[^\s]+:openapi/);
+  assert.doesNotMatch(implementationRegistry, /smart-doc-verification\.md/);
+  const projectInstanceDocs = await Promise.all([
+    "AGENTS.md",
+    "docs/agents/skills-maintenance.md",
+    "docs/agents/gitlab-workflow-skills.md",
+    "docs/agents/issue-tracker.md",
+    "docs/process/implementation-repo-integration.md",
+    "docs/process/harness-process-tailoring.md",
+    "docs/templates/build-architecture-checklist-template.md"
+  ].map((relative) => readFile(path.join(target, relative), "utf8")));
+  const staleProjectCommands = /scripts\/(?:verify-template|sync-skills|update-skill-lock|export-yss-skills|verify-upstream-skill-source|verify-maintenance-checkpoint|verify-implementation-path-scenarios|gitworks)/;
+  for (const body of projectInstanceDocs) assert.doesNotMatch(body, staleProjectCommands);
+  const serverPom = await readFile(path.join(backend, "server/pom.xml"), "utf8");
+  assert.match(serverPom, /<profiles>[\s\S]*<id>nacos<\/id>[\s\S]*<activeByDefault>true<\/activeByDefault>/);
+  assert.match(serverPom, /<app\.env>dev<\/app\.env>[\s\S]*<app\.profiles>nacos<\/app\.profiles>/);
+  assert.match(serverPom, /spring-boot-maven-plugin/);
+  assert.match(serverPom, /<includes>[\s\S]*data-analysis-item1-client[\s\S]*data-analysis-item1-core[\s\S]*data-analysis-item1-repository[\s\S]*<\/includes>/);
+  const smartDocPlugin = serverPom.match(/<plugin>(?:(?!<\/plugin>)[\s\S])*?<artifactId>smart-doc-maven-plugin<\/artifactId>(?:(?!<\/plugin>)[\s\S])*?<\/plugin>/)?.[0];
+  assert.ok(smartDocPlugin);
+  assert.doesNotMatch(smartDocPlugin, /<executions>/);
+  const smartDoc = await readFile(path.join(backend, "server/src/main/resources/smart-doc.json"), "utf8");
+  assert.match(smartDoc, /"projectName": "data-analysis-item1"/);
+  assert.match(smartDoc, /"packageFilters": "com\.yss\.dataanalysis\.item1\.server\.controller\.\*"/);
+  assert.match(smartDoc, /"showAuthor": true/);
+  assert.match(smartDoc, /"appToken": ""/);
+  assert.doesNotMatch(smartDoc, /43fd1d4bc1c743c1b83bf4843e8167bf|192\.168\./);
+  const logback = await readFile(path.join(backend, "server/src/main/resources/logback-spring.xml"), "utf8");
+  assert.match(logback, /springProfile name="dev,mock"/);
+  assert.match(logback, /springProfile name="uat,pro,oracle,oceanbase-oracle"/);
+  assert.match(logback, /com\.yss\.dataanalysis\.item1/);
+  const bootstrap = await readFile(path.join(backend, "server/src/main/resources/bootstrap.yml"), "utf8");
+  assert.match(bootstrap, /active: \$\{app\.env:dev\},datasource,nacos,oracle,mock/);
+  assert.doesNotMatch(bootstrap, /mock,\s*$/m);
+  const bootstrapNacos = await readFile(path.join(backend, "server/src/main/resources/bootstrap-nacos.yml"), "utf8");
+  assert.match(bootstrapNacos, /server-addr: \$\{nacosserver:192\.168\.165\.58:8848\}/);
+  assert.match(bootstrapNacos, /group: \$\{nacos_group:yss-dm\}/);
+  assert.match(bootstrapNacos, /discovery:[\s\S]*enabled: true[\s\S]*config:[\s\S]*enabled: true/);
+  const bootstrapMock = await readFile(path.join(backend, "server/src/main/resources/bootstrap-mock.yml"), "utf8");
+  assert.match(bootstrapMock, /discovery:[\s\S]*enabled: false/);
+  assert.match(bootstrapMock, /config:[\s\S]*enabled: false[\s\S]*import-check:[\s\S]*enabled: false/);
+  const applicationMock = await readFile(path.join(backend, "server/src/main/resources/application-mock.yml"), "utf8");
+  assert.match(applicationMock, /leaf:[\s\S]*leafSegmentEnable: false[\s\S]*leafSnowflakeEnable: false/);
+  assert.match(applicationMock, /com\.yss\.cloud\.mybatis\.MybatisPlusConfiguration/);
+  assert.match(applicationMock, /com\.yss\.cloud\.sankuai\.config\.LeafDataSourceConfiguration/);
+  const application = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/Application.java"), "utf8");
+  assert.doesNotMatch(application, /@EnableDistributedId/);
+  const databaseInfrastructure = await readFile(path.join(backend, "server/src/main/java/com/yss/dataanalysis/item1/server/configuration/DatabaseInfrastructureConfiguration.java"), "utf8");
+  assert.match(databaseInfrastructure, /@Profile\("!mock"\)/);
+  assert.match(databaseInfrastructure, /@EnableDistributedId/);
+  assert.match(databaseInfrastructure, /@Import\(MapperConfiguration.class\)/);
+});
+
+test("已有 skillUtils 落后时原子刷新并保留备份", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-refresh-"));
+  t.after(() => rm(base, { recursive: true, force: true }));
+  const skillUtils = path.join(base, "skillUtils");
+  await mkdir(skillUtils, { recursive: true });
+  await writeFile(path.join(skillUtils, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\n", "utf8");
+  await writeFile(path.join(skillUtils, "skills-lock.json"), "{\"version\":0}\n", "utf8");
+  await writeFile(path.join(skillUtils, "local-marker.txt"), "preserve old installation\n", "utf8");
+  const target = path.join(base, "item-refresh");
+  const result = run(["--project-name", "data-analysis-refresh", "--base-package", "com.yss.dataanalysis.refresh", "--target-dir", target]);
+  assert.equal(result.status, 0, result.stderr);
+  const output = JSON.parse(result.stdout);
+  assert.equal(output.skill_utils_created, false);
+  assert.equal(output.skill_utils_refreshed, true);
+  assert.ok(output.skill_utils_backup);
+  assert.equal(await readFile(path.join(output.skill_utils_backup, "local-marker.txt"), "utf8"), "preserve old installation\n");
+  assert.equal(await readFile(path.join(skillUtils, "skills-lock.json"), "utf8"), await expectedDistributedLock());
+});
+
+test("已有 skillUtils 与源锁一致时直接复用", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-reuse-"));
+  t.after(() => rm(base, { recursive: true, force: true }));
+  const first = run(["--project-name", "data-analysis-reuse-a", "--base-package", "com.yss.dataanalysis.reusea", "--target-dir", path.join(base, "item-a")]);
+  assert.equal(first.status, 0, first.stderr);
+  const second = run(["--project-name", "data-analysis-reuse-b", "--base-package", "com.yss.dataanalysis.reuseb", "--target-dir", path.join(base, "item-b")]);
+  assert.equal(second.status, 0, second.stderr);
+  const output = JSON.parse(second.stdout);
+  assert.equal(output.skill_utils_created, false);
+  assert.equal(output.skill_utils_refreshed, false);
+  assert.equal(output.skill_utils_backup, null);
+});
+
+test("dry-run 仅报告 skillUtils 将刷新且不修改旧目录", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-skill-dry-refresh-"));
+  t.after(() => rm(base, { recursive: true, force: true }));
+  const skillUtils = path.join(base, "skillUtils");
+  await mkdir(skillUtils, { recursive: true });
+  await writeFile(path.join(skillUtils, "skill-utils.yaml"), "schema_version: 1\nkind: yss-skill-utils\n", "utf8");
+  await writeFile(path.join(skillUtils, "skills-lock.json"), "{\"version\":0}\n", "utf8");
+  const result = run(["--project-name", "data-analysis-dry-refresh", "--base-package", "com.yss.dataanalysis.dryrefresh", "--target-dir", path.join(base, "item"), "--dry-run"]);
+  assert.equal(result.status, 0, result.stderr);
+  const output = JSON.parse(result.stdout);
+  assert.equal(output.skill_utils_refreshed, true);
+  assert.equal(output.skill_utils_backup, null);
+  assert.equal(await readFile(path.join(skillUtils, "skills-lock.json"), "utf8"), "{\"version\":0}\n");
+  assert.deepEqual((await readdir(base)).sort(), ["skillUtils"]);
+});
+
+test("Git 当前用户写入 Javadoc 且缺失时拒绝生成", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-author-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "author-project");
+  const generated = run(["--project-name", "author-project", "--base-package", "com.yss.author", "--target-dir", target], {
+    env: { GIT_CONFIG_VALUE_0: "张三" }
+  });
+  assert.equal(generated.status, 0, generated.stderr);
+  const controller = await readFile(path.join(target, "server/src/main/java/com/yss/author/server/controller/AnalysisController.java"), "utf8");
+  assert.match(controller, /@author 张三/);
+  assert.doesNotMatch(controller, /@author system/);
+
+  const missingTarget = path.join(base, "missing-author");
+  const missing = run(["--project-name", "missing-author", "--base-package", "com.yss.missing", "--target-dir", missingTarget], {
+    env: { GIT_CONFIG_COUNT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: path.join(base, "not-found.gitconfig") }
+  });
+  assert.notEqual(missing.status, 0);
+  assert.match(missing.stderr, /Git user\.name/);
+  await assert.rejects(stat(missingTarget), { code: "ENOENT" });
+});
+
+test("不启用 Mock 时不生成 bootstrap-mock 且不激活 mock profile", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-no-mock-profile-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-no-mock");
+  const result = run(["--project-name", "data-analysis-no-mock", "--base-package", "com.yss.dataanalysis.nomock", "--target-dir", target]);
+  assert.equal(result.status, 0, result.stderr);
+  const bootstrap = await readFile(path.join(target, "server/src/main/resources/bootstrap.yml"), "utf8");
+  assert.match(bootstrap, /active: \$\{app\.env:dev\},datasource,nacos,oracle/);
+  assert.doesNotMatch(bootstrap, /,mock/);
+  await assert.rejects(stat(path.join(target, "server/src/main/resources/bootstrap-mock.yml")), { code: "ENOENT" });
+});
+
+test("Maven settings \u4f5c\u4e3a外部验证输入且不写入项目", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-settings-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const settings = path.join(base, "settings.xml");
+  await writeFile(settings, "<settings/>\n");
+  const target = path.join(base, "data-analysis-item-settings");
+  const result = run(["--project-name", "data-analysis-item-settings", "--base-package", "com.yss.dataanalysis.settings", "--target-dir", target, "--maven-settings", settings]);
+  assert.equal(result.status, 0, result.stderr);
+  const manifest = await readFile(path.join(target, ".yss/scaffold-generation.json"), "utf8");
+  assert.match(manifest, /"maven_settings_mode": "external"/);
+  assert.match(manifest, /"maven_settings_required": true/);
+  assert.doesNotMatch(manifest, new RegExp(settings.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.equal((await readdir(target)).includes("settings.xml"), false);
+});
+test("Maven settings 支持环境变量且显式参数优先", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-settings-resolution-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const environmentSettings = path.join(base, "environment-settings.xml");
+  const explicitSettings = path.join(base, "explicit-settings.xml");
+  await writeFile(environmentSettings, "<settings/>\n");
+  await writeFile(explicitSettings, "<settings/>\n");
+  const environmentTarget = path.join(base, "environment-project");
+  const fromEnvironment = run(["--project-name", "environment-project", "--base-package", "com.yss.environment", "--target-dir", environmentTarget, "--dry-run"], { env: { YSS_MAVEN_SETTINGS: environmentSettings } });
+  assert.equal(fromEnvironment.status, 0, fromEnvironment.stderr);
+  assert.match(fromEnvironment.stdout, /"maven_settings_source": "environment"/);
+  const explicitTarget = path.join(base, "explicit-project");
+  const fromExplicit = run(["--project-name", "explicit-project", "--base-package", "com.yss.explicit", "--target-dir", explicitTarget, "--maven-settings", explicitSettings, "--dry-run"], { env: { YSS_MAVEN_SETTINGS: environmentSettings } });
+  assert.equal(fromExplicit.status, 0, fromExplicit.stderr);
+  assert.match(fromExplicit.stdout, /"maven_settings_source": "explicit"/);
+});
+test("未指定 settings 时仍完整生成，并将依赖解析延后到验证阶段", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "yss-mvc-no-settings-"));
+  t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "no-settings-project");
+  const result = run(["--project-name", "no-settings-project", "--base-package", "com.yss.nosettings", "--target-dir", target], {
+    env: { YSS_MAVEN_SETTINGS: "", USERPROFILE: path.join(base, "missing-user"), HOME: path.join(base, "missing-home") }
+  });
+  assert.equal(result.status, 0, result.stderr);
+  const output = JSON.parse(result.stdout);
+  assert.equal(output.maven_settings_source, "maven-default");
+  assert.equal(output.maven_settings_available, false);
+  assert.equal(output.dependency_resolution, "deferred");
+  assert.equal(output.network_access_during_generation, "disabled");
+  for (const module of ["server", "core", "client", "repository", "adapter", "feign-client"]) {
+    await stat(path.join(target, module, "pom.xml"));
+  }
+  await stat(path.join(target, "mvnw"));
+  assert.equal((await readdir(target)).includes("settings.xml"), false);
+});
+test("拒绝非空目标目录", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-scaffold-nonempty-")); t.after(() => rm(base, { recursive: true, force: true })); await mkdir(base, { recursive: true }); await writeFile(path.join(base, "keep.txt"), "keep");
+  const result = run(["--project-name", "data-analysis-item1", "--base-package", "com.yss.dataanalysis.item1", "--target-dir", base]); assert.notEqual(result.status, 0); assert.match(result.stderr, /目标目录非空/);
+});
+test("允许已存在的空目标目录", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-empty-target-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item-empty"); await mkdir(target);
+  const result = run(["--project-name", "data-analysis-item-empty", "--base-package", "com.yss.dataanalysis.empty", "--target-dir", target]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
+});
+test("嵌套在父仓目录时仍初始化为独立 Git 根", async (t) => {
+  const parent = await mkdtemp(path.join(os.tmpdir(), "data-analysis-parent-repo-")); t.after(() => rm(parent, { recursive: true, force: true }));
+  assert.equal(spawnSync("git", ["init", "--initial-branch=parent-main", parent], { encoding: "utf8" }).status, 0);
+  const target = path.join(parent, "data-analysis-item2");
+  const result = run(["--project-name", "data-analysis-item2", "--base-package", "com.yss.dataanalysis.item2", "--target-dir", target]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(path.resolve(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).stdout.trim()), path.resolve(target));
+  assert.equal(spawnSync("git", ["-C", target, "branch", "--show-current"], { encoding: "utf8" }).stdout.trim(), "main");
+});
+test("dry-run 不创建目录或 Git 仓库", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-dry-run-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item3");
+  const result = run(["--project-name", "data-analysis-item3", "--base-package", "com.yss.dataanalysis.item3", "--target-dir", target, "--dry-run"]);
+  assert.equal(result.status, 0, result.stderr);
+  assert.match(result.stdout, /"mode": "dry-run"/);
+  assert.equal(spawnSync("git", ["-C", target, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).status, 128);
+});
+test("Git 预检失败时不留下目标目录或 staging", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-no-git-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item4");
+  const result = run(["--project-name", "data-analysis-item4", "--base-package", "com.yss.dataanalysis.item4", "--target-dir", target], { env: { ...process.env, PATH: "" } });
+  assert.notEqual(result.status, 0); assert.match(result.stderr, /未检测到可用的 Git/);
+  await assert.rejects(stat(target), { code: "ENOENT" });
+  assert.deepEqual((await readdir(base)).filter((name) => name.includes(".staging-")), []);
+});
+test("staging 创建后中间步骤失败时只清理本轮 staging", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-git-init-fail-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const occupied = path.join(base, ".data-analysis-item5.staging-occupied"); await mkdir(occupied); await writeFile(path.join(occupied, "keep.txt"), "keep");
+  const target = path.join(base, "data-analysis-item5");
+  const result = run(["--project-name", "data-analysis-item5", "--base-package", "com.yss.dataanalysis.item5", "--target-dir", target], { env: { ...process.env, NODE_ENV: "test", YSS_SCAFFOLD_TEST_FAIL_AFTER_STAGING: "1" } });
+  assert.notEqual(result.status, 0); assert.match(result.stderr, /staging 后失败/);
+  await assert.rejects(stat(target), { code: "ENOENT" });
+  assert.equal(await readFile(path.join(occupied, "keep.txt"), "utf8"), "keep");
+  assert.deepEqual((await readdir(base)).filter((name) => name.startsWith(".data-analysis-item5.staging-") && name !== path.basename(occupied)), []);
+});
+test("生成期间空目标目录被写入时保留新内容并拒绝替换", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-target-race-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item6"); await mkdir(target);
+  const result = run(["--project-name", "data-analysis-item6", "--base-package", "com.yss.dataanalysis.item6", "--target-dir", target], { env: { ...process.env, NODE_ENV: "test", YSS_SCAFFOLD_TEST_WRITE_TARGET_DURING_STAGING: "1" } });
+  assert.notEqual(result.status, 0);
+  assert.equal(await readFile(path.join(target, "keep.txt"), "utf8"), "concurrent content\n");
+  assert.deepEqual((await readdir(base)).filter((name) => name.startsWith(".data-analysis-item6.staging-")), []);
+});
+test("结构验证器拒绝与生成清单不一致的实现仓登记", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-registry-drift-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item7");
+  const result = run(["--project-name", "data-analysis-item7", "--base-package", "com.yss.dataanalysis.item7", "--target-dir", target]);
+  assert.equal(result.status, 0, result.stderr);
+  const registryPath = path.join(target, "docs/process/implementation-repo-registry.yaml");
+  const registry = await readFile(registryPath, "utf8");
+  await writeFile(registryPath, registry.replace("repository_scope: external-repository", "repository_scope: harness-apps"));
+  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
+  assert.notEqual(verification.status, 0);
+  assert.match(verification.stderr, /实现仓登记与生成清单不一致/);
+});
+test("OceanBase Oracle 仅生成指定驱动并保持 Java 8 基线", async (t) => {
+  const base = await mkdtemp(path.join(os.tmpdir(), "data-analysis-oceanbase-")); t.after(() => rm(base, { recursive: true, force: true }));
+  const target = path.join(base, "data-analysis-item8");
+  const result = run(["--project-name", "data-analysis-item8", "--base-package", "com.yss.dataanalysis.item8", "--target-dir", target, "--database", "oceanbase-oracle", "--with-mock"]);
+  assert.equal(result.status, 0, result.stderr);
+  const parentPom = await readFile(path.join(target, "pom.xml"), "utf8");
+  const repositoryPom = await readFile(path.join(target, "repository/pom.xml"), "utf8");
+  assert.match(parentPom, /<java.version>1.8<\/java.version>/);
+  assert.match(parentPom, /<version>2.0.0-SNAPSHOT<\/version>/);
+  assert.match(repositoryPom, /oceanbase-client/);
+  assert.doesNotMatch(repositoryPom, /ojdbc8/);
+  const querySource = await readFile(path.join(target, "client/src/main/java/com/yss/dataanalysis/item8/client/query/AnalysisQuery.java"), "utf8");
+  assert.doesNotMatch(querySource, /\brecord\b|List\.of|Map\.of|jakarta\./);
+  const verification = spawnSync(process.execPath, [verifyScript, "--project-root", target], { encoding: "utf8" });
+  assert.equal(verification.status, 0, verification.stderr);
+});

package/template/.codex/skills/yss-mvc-scaffold-generator/scripts/lib/envelope.mjs

@@ -0,0 +1,66 @@
+import { cp, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { HARNESS_ROOT, MODULES, PROJECT_SCRIPT_FILES, exists, fail } from "./runtime.mjs";
+import { put } from "./storage.mjs";
+
+const TEMPLATE_SOURCE_COMMAND = /scripts\/(?:verify-template(?:-fast|-candidate)?|sync-skills|update-skill-lock|export-yss-skills|verify-upstream-skill-source|verify-maintenance-checkpoint|verify-implementation-path-scenarios|gitworks)/g;
+
+function removeTemplateSourceCommands(content) {
+  return content.replace(TEMPLATE_SOURCE_COMMAND, "上游 Harness 专用命令");
+}
+
+export async function writeProjectEnvelope(o) {
+  await put(o.targetDir, "yss-project.yaml", "schema_version: 1\nrepository_mode: project-instance");
+  await put(o.targetDir, ".artifact-workspace.yaml", `schema_version: 1\nkind: service\nservice_id: ${o.projectName}\nowner: ${JSON.stringify(o.gitAuthor)}`);
+  await cp(path.join(HARNESS_ROOT, "AGENTS.md"), path.join(o.targetDir, "AGENTS.md"));
+  const generatedAgents = await readFile(path.join(o.targetDir, "AGENTS.md"), "utf8");
+  await writeFile(path.join(o.targetDir, "AGENTS.md"), generatedAgents
+    .replaceAll(".agents/skills", "../skillUtils/.agents/skills")
+    .replaceAll(".codex/skills", "../skillUtils/.codex/skills")
+    .replace("- 模板维护默认以 `scripts/verify-template-fast` 完成 `implementation-ready`；显式晋级审查时用 `scripts/verify-template-candidate`，首次冻结前和最终发布前仍必须执行完整 `scripts/verify-template`。后者是不可裁剪的模板发布阻断门禁。模板与外部 `create-yss-spec` 的跨仓库契约未完成集成验证时，不得声称可发布。", "- 模板发布门禁只在上游 Harness 模板源执行；当前项目实例不分发或运行模板验证命令。"), "utf8");
+  await put(o.targetDir, "CONTEXT.md", "# 领域上下文\n\n## 业务术语\n\n| 术语 | 定义 | 英文标识 | 避免 / 备注 |\n|---|---|---|---|\n| 分析数据集 | 支撑一个数据分析功能的表结构、字段语义和查询边界。 | AnalysisDataset | 具体业务术语在需求分析后补充 |\n| 分析结果 | 数据分析接口返回的分页明细或聚合结果。 | AnalysisResult | 不表示未经约束的原始结果集 |");
+  for (const relative of ["docs/agents", "docs/process", "docs/templates", "docs/architecture/templates"]) {
+    const source = path.join(HARNESS_ROOT, relative);
+    if (!await exists(source)) fail(`项目实例治理资产不存在: ${source}`);
+    await cp(source, path.join(o.targetDir, relative), { recursive: true });
+  }
+  const integrationPath = path.join(o.targetDir, "docs/process/implementation-repo-integration.md");
+  const integration = (await readFile(integrationPath, "utf8"))
+    .replace("模板仓库至少执行：", "以下命令仅由上游 Harness 模板源执行，项目实例不分发这些模板维护工具：")
+    .replace(/scripts\/sync-skills --check\r?\nscripts\/update-skill-lock --check\r?\nscripts\/verify-template/, "在 Harness 模板源执行 Skill 投影同步、锁文件检查和模板发布校验。");
+  await writeFile(integrationPath, integration, "utf8");
+  const checklistPath = path.join(o.targetDir, "docs/templates/build-architecture-checklist-template.md");
+  await writeFile(checklistPath, (await readFile(checklistPath, "utf8")).replace("scripts/verify-implementation-path-scenarios", "node scripts/implementation-path-policy"), "utf8");
+  for (const relative of ["AGENTS.md", "docs/process/implementation-repo-integration.md", "docs/process/harness-process-tailoring.md", "docs/templates/build-architecture-checklist-template.md"]) {
+    const target = path.join(o.targetDir, relative);
+    await writeFile(target, removeTemplateSourceCommands(await readFile(target, "utf8")), "utf8");
+  }
+  const agentReadmePath = path.join(o.targetDir, "docs/agents/README.md");
+  const agentReadme = (await readFile(agentReadmePath, "utf8"))
+    .replace("Engineering Skills 的安装、升级和验证说明", "项目实例使用共享 `skillUtils` 的版本检查说明")
+    .replace("GitLab、MR、CI 和自动 gitworks 的技能配置与使用规则", "GitLab、MR 和 CI 的 `glab` 使用规则");
+  await writeFile(agentReadmePath, agentReadme, "utf8");
+  const issueTrackerPath = path.join(o.targetDir, "docs/agents/issue-tracker.md");
+  await writeFile(issueTrackerPath, (await readFile(issueTrackerPath, "utf8")).replace("当平台为 GitLab 时，优先使用 `glab` 或项目快捷入口 `scripts/gitworks`。", "当平台为 GitLab 时，使用已认证的 `glab`。"), "utf8");
+  const tailoringPath = path.join(o.targetDir, "docs/process/harness-process-tailoring.md");
+  await writeFile(tailoringPath, (await readFile(tailoringPath, "utf8")).replace("使用 `scripts/verify-maintenance-checkpoint <file>` 或通过 stdin 传入 YAML / JSON 做只读校验。触发项 ID 与最低等级只由 `docs/process/maintenance-intensity.yaml` 维护；校验器消费该策略。未知触发项必须先更新该权威策略和场景，不能静默接受。", "维护 checkpoint 校验只在上游 Harness 模板源执行。触发项 ID 与最低等级只由 `docs/process/maintenance-intensity.yaml` 维护；未知触发项必须先更新该权威策略和场景，不能静默接受。"), "utf8");
+  await put(o.targetDir, "docs/agents/skills-maintenance.md", "# 项目实例 Skill 环境\n\n本项目不维护或发布共享 Skill。共享 Skill 位于相邻的 `../skillUtils`，版本由项目根 `skills-lock.json` 锁定。\n\n开发前执行：\n\n```bash\nnpm run check-agent-environment\n```\n\n输出 `READY` 表示工具版本、兼容协议、Agent 投影和 canonical Skill hash 一致。输出 `NOT_READY` 时停止功能实现，使用上游 Harness 的项目初始化或刷新流程更新 `skillUtils`；不要在项目内手工同步、导出或覆盖共享 Skill。\n\n项目实例只消费已提交的 `scripts/lib/*.mjs` 和 `scripts/vendor/*.mjs`。模板发布、Skill 投影生成、上游来源验证和公开导出均属于 Harness 模板源维护，不在本项目执行。");
+  await put(o.targetDir, "docs/agents/gitlab-workflow-skills.md", "# GitLab 工作流\n\n本项目不分发 GitLab 包装脚本。需要查看 MR、Pipeline 或 CI 时，使用已认证的 `glab`，并先确认当前仓库的 `origin` 指向目标 GitLab 项目。\n\n常用只读命令：\n\n```bash\ngit status --short --branch\nglab mr list\nglab ci list\nglab ci status\n```\n\n创建分支、commit、push、MR 或触发 Pipeline 都必须遵守 `AGENTS.md` 的显式授权和 checkpoint 规则。Token 只通过 `glab auth login` 或环境变量管理，不写入仓库文件。");
+  for (const relative of PROJECT_SCRIPT_FILES) await cp(path.join(HARNESS_ROOT, "scripts", relative), path.join(o.targetDir, "scripts", relative));
+  for (const relative of ["lib", "vendor"]) await cp(path.join(HARNESS_ROOT, "scripts", relative), path.join(o.targetDir, "scripts", relative), { recursive: true });
+  for (const relative of ["package.json", "skills-lock.json", ".nvmrc"]) {
+    const source = path.join(HARNESS_ROOT, relative);
+    if (await exists(source)) await cp(source, path.join(o.targetDir, relative));
+  }
+  await put(o.targetDir, "skills-lock.json", JSON.stringify({ version: 1, distribution: { mode: "sibling-directory", skillUtilsDir: "../skillUtils", required: true, compatibility: "skill-utils-v1", requiredToolVersion: "1.0.0" }, skills: { source: "../skillUtils/skills-lock.json", validation: "scripts/check-agent-environment.mjs" } }, null, 2));
+  await put(o.targetDir, "package.json", JSON.stringify({ name: o.projectName, private: true, scripts: { "check-agent-environment": "node scripts/check-agent-environment.mjs", "verify-project": "node scripts/verify-lifecycle-registry", "verify-dto": "node scripts/verify-yss-dto-openapi-profile" } }, null, 2));
+  await put(o.targetDir, "docs/process/analysis-project.yaml", `project_name: ${o.projectName}\nproject_type: data-analysis\nrepository_scope: external-repository\nimplementation_root: .\nruntime_java: 8\npersistence_profile: yss-mybatis-plus\nid_strategy: ASSIGN_ID\ndatabase:\n  type: ${o.database}\n  runtime_connection: true\n  metadata_contract: docs/data-model\nquery:\n  sql_mode: readonly\n  allowed_statement_types: [select, with]\n  parameter_binding_required: true\nmodules:\n${MODULES.map((module) => `  - ${module}`).join("\n")}\nworkflow:\n  - requirement-and-data-contract\n  - specification-freeze\n  - vertical-slice-implementation\n  - automated-gates\n  - single-release-confirmation\n  - runtime-monitoring`);
+  await put(o.targetDir, "docs/process/implementation-repo-registry.yaml", `schema_version: 1\nprojects:\n  - project_type: backend\n    project_name: ${o.projectName}\n    project_root: .\n    git_root: .\n    repository_scope: external-repository\n    scaffold_status: initialized\n    default_branch: main\n    allowed_write_paths:\n      - .\n    verification_commands:\n      - mvnw com.coveo:fmt-maven-plugin:2.9.1:check\n      - mvnw validate\n      - mvnw test\n      - mvnw package\n    expected_evidence_files:\n      - docs/.scratch/<feature>/verification/yss-skill-execution-result.yaml\n      - docs/.scratch/<feature>/verification/fresh-verification.md\n    ci: not-configured\n    rollback_point: initial-empty-repository`);
+  await put(o.targetDir, "docs/.scratch/.gitkeep", "# Local lifecycle artifacts are created in feature subdirectories.");
+  await put(o.targetDir, "docs/service/service-overview.md", `# ${o.projectName} 服务说明\n\nOwner: ${o.gitAuthor}\n\n## 职责\n\n提供数据分析服务能力；具体业务职责在产品服务登记和功能 Spec 中维护。\n\n## 非职责\n\n## 依赖服务\n`);
+  await put(o.targetDir, "docs/service/module-map.md", `# ${o.projectName} Module 地图\n\n| Module | 职责 | 主要 Interface |\n|---|---|---|\n| server | Web 入口与运行配置 | HTTP Controller |\n| core | 领域与应用行为 | Domain/Application Interface |\n| client | 对外 DTO 与客户端契约 | Request/Response |\n| repository | 数据持久化 | Gateway/Repository |\n| adapter | 外部系统适配 | Adapter |\n| feign-client | 服务间调用客户端 | Feign Interface |\n`);
+  await put(o.targetDir, "docs/service/current-capabilities.md", "# 当前能力\n\n本文件是发布时生成的派生阅读视图，普通功能开发不手工修改。功能详情位于 `docs/features/`，开发中功能位于 `docs/.scratch/`。\n");
+  await put(o.targetDir, "docs/engineering/data-analysis-java-conventions.md", `# 数据分析 Java 工程规范\n\n变量、参数和字段必须使用业务含义名称。public 类、接口和方法必须有简体中文 Javadoc；Controller 类和公开接口方法使用初始化时读取的 Git user.name（本项目为 @author ${o.gitAuthor}）和生成时的 @date，方法参数、返回值分别使用 @param、@return 完整说明。Javadoc 正文、@author、@date、@param、@return 必须分行；Mapping 注解、方法签名、方法体不得压缩在同一行。\n`);
+  await put(o.targetDir, ".gitignore", "target/\n**/target/\n.idea/\n*.iml\n.env\n.env.*\n!.env.example\n.local/\n");
+}

package/template/.codex/skills/yss-mvc-scaffold-generator/scripts/lib/runtime.mjs

@@ -0,0 +1,115 @@
+import { existsSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const MODULES = ["server", "core", "client", "repository", "adapter", "feign-client"];
+export const SKILL_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+export const HARNESS_ROOT = findHarnessRoot();
+export const SHARED_SKILLS_ROOT = path.join(HARNESS_ROOT, ".agents", "skills");
+export const SKILL_UTILS_NAME = "skillUtils";
+export const SKILL_UTILS_DIRECTORIES = [
+  ".agents/skills", ".claude/skills", ".codex/skills", ".cursor/skills",
+  ".pi/skills", ".qoder/skills", ".trae/skills"
+];
+export const PROJECT_SCRIPT_FILES = [
+  "check-agent-environment.mjs", "implementation-path-policy", "repository-mode", "repository-scope-policy",
+  "generate-lifecycle-artifacts", "node-generate-lifecycle-artifacts.mjs", "node-verify-lifecycle-registry.mjs",
+  "verify-lifecycle-registry", "verify-lifecycle-checkpoint", "verify-frontend-implementation-evidence",
+  "verify-yss-dto-openapi-profile"
+];
+
+export function findHarnessRoot() {
+  let candidate = SKILL_ROOT;
+  while (true) {
+    if (existsSync(path.join(candidate, ".agents", "skills")) && existsSync(path.join(candidate, "AGENTS.md"))) return candidate;
+    const parent = path.dirname(candidate);
+    if (parent === candidate) break;
+    candidate = parent;
+  }
+  throw new Error(`未找到插件 Harness 根目录: ${SKILL_ROOT}`);
+}
+
+export function fail(message) { throw new Error(message); }
+
+export function parseArgs(argv) {
+  const options = { database: "oracle", withMock: false, dryRun: false };
+  const fields = {
+    "--project-name": "projectName", "--base-package": "basePackage", "--target-dir": "targetDir",
+    "--database": "database", "--maven-settings": "mavenSettings"
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    let token = argv[index];
+    if (token === "--with-mock") { options.withMock = true; continue; }
+    if (token === "--dry-run") { options.dryRun = true; continue; }
+    if (token === "--help" || token === "-h") { options.help = true; continue; }
+    const equals = token.indexOf("=");
+    let value = equals >= 0 ? token.slice(equals + 1) : undefined;
+    if (equals >= 0) token = token.slice(0, equals);
+    if (!fields[token]) fail(`不支持的参数: ${token}`);
+    if (value === undefined) value = argv[++index];
+    if (!value || value.startsWith("--")) fail(`参数 ${token} 缺少值`);
+    options[fields[token]] = value;
+  }
+  if (options.help) return options;
+  if (!options.projectName || !/^[a-z][a-z0-9-]*$/.test(options.projectName)) fail("--project-name 必须是小写连字符名称");
+  if (!options.basePackage || !/^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)+$/.test(options.basePackage)) fail("--base-package 不是合法 Java 包名");
+  if (!options.targetDir) fail("必须提供 --target-dir");
+  if (!["oracle", "oceanbase-oracle"].includes(options.database)) fail("--database 只支持 oracle 或 oceanbase-oracle");
+  options.targetDir = path.resolve(options.targetDir);
+  if (options.mavenSettings) options.mavenSettings = path.resolve(options.mavenSettings);
+  return options;
+}
+
+export async function exists(target) {
+  try { await stat(target); return true; } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function xml(value) { return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;"); }
+export function packagePath(name) { return name.replaceAll(".", "/"); }
+export function generatedAtLocal() {
+  const now = new Date();
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${now.getFullYear()}/${pad(now.getMonth() + 1)}/${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}`;
+}
+
+export function runGit(args, cwd) { return spawnSync("git", args, { cwd, encoding: "utf8" }); }
+export function assertGitAvailable() {
+  const result = runGit(["--version"], process.cwd());
+  if (result.status !== 0) fail("未检测到可用的 Git，无法初始化独立项目仓库");
+}
+export function resolveGitAuthor() {
+  const result = runGit(["config", "--get", "user.name"], process.cwd());
+  const author = result.status === 0 ? result.stdout.trim() : "";
+  if (!author) fail("未配置 Git user.name；请先执行 git config --global user.name \"你的姓名\"");
+  if (/[\r\n]|\*\//.test(author)) fail("Git user.name 包含不能安全写入 Javadoc 的字符");
+  return author;
+}
+export function initializeGit(root) {
+  let result = runGit(["init", "--initial-branch=main"], root);
+  if (result.status !== 0) {
+    result = runGit(["init"], root);
+    if (result.status === 0) result = runGit(["branch", "-M", "main"], root);
+  }
+  if (result.status !== 0) fail(`Git 仓库初始化失败: ${(result.stderr || result.stdout).trim()}`);
+}
+
+export async function resolveMavenSettings(options) {
+  if (options.mavenSettings) {
+    if (!await exists(options.mavenSettings)) fail(`Maven settings 不存在: ${options.mavenSettings}`);
+    return { path: options.mavenSettings, source: "explicit", available: true };
+  }
+  if (process.env.YSS_MAVEN_SETTINGS) {
+    const environmentPath = path.resolve(process.env.YSS_MAVEN_SETTINGS);
+    if (!await exists(environmentPath)) fail(`Maven settings 不存在: ${environmentPath}`);
+    return { path: environmentPath, source: "environment", available: true };
+  }
+  const userSettings = path.join(os.homedir(), ".m2", "settings.xml");
+  if (await exists(userSettings)) return { path: userSettings, source: "user-home", available: true };
+  return { path: null, source: "maven-default", available: false };
+}

package/template/.codex/skills/yss-mvc-scaffold-generator/scripts/lib/storage.mjs

@@ -0,0 +1,90 @@
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  HARNESS_ROOT,
+  SKILL_ROOT,
+  SKILL_UTILS_DIRECTORIES,
+  SKILL_UTILS_NAME,
+  fail,
+  exists
+} from "./runtime.mjs";
+
+const BOOTSTRAP_ONLY_SKILLS = ["yss-mvc-scaffold-generator"];
+
+async function distributedSkillLock() {
+  const source = path.join(HARNESS_ROOT, "skills-lock.json");
+  if (!await exists(source)) fail(`技能工具包源锁文件不存在: ${source}`);
+  const lock = JSON.parse(await readFile(source, "utf8"));
+  for (const name of BOOTSTRAP_ONLY_SKILLS) {
+    delete lock.skills?.shared?.[name];
+    for (const platform of Object.values(lock.skills?.platform ?? {})) delete platform?.[name];
+  }
+  return `${JSON.stringify(lock, null, 2)}\n`;
+}
+
+export async function assertEmpty(target) {
+  if (!await exists(target)) return;
+  if ((await readdir(target)).length) fail(`目标目录非空，拒绝生成: ${target}`);
+}
+
+export async function put(root, relative, content, author) {
+  const target = path.join(root, relative);
+  const rendered = author ? content.replaceAll("@author system", `@author ${author}`) : content;
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, `${rendered.trim()}\n`, "utf8");
+}
+
+export async function renderAsset(name, replacements) {
+  let content = await readFile(path.join(SKILL_ROOT, "assets", name), "utf8");
+  for (const [token, value] of Object.entries(replacements)) content = content.replaceAll(`{{${token}}}`, value);
+  return content;
+}
+
+async function populateSkillUtils(destination) {
+  await mkdir(destination, { recursive: true });
+  for (const relative of SKILL_UTILS_DIRECTORIES) {
+    const source = path.join(HARNESS_ROOT, relative);
+    if (!await exists(source)) fail(`技能工具包源目录不存在: ${source}`);
+    await cp(source, path.join(destination, relative), { recursive: true });
+  }
+  for (const root of SKILL_UTILS_DIRECTORIES) {
+    for (const name of BOOTSTRAP_ONLY_SKILLS) {
+      await rm(path.join(destination, root, name), { recursive: true, force: true });
+    }
+  }
+  await writeFile(path.join(destination, "skills-lock.json"), await distributedSkillLock(), "utf8");
+  const publicSkills = path.join(HARNESS_ROOT, "yss-public-skills.json");
+  if (!await exists(publicSkills)) fail(`技能工具包源文件不存在: ${publicSkills}`);
+  await cp(publicSkills, path.join(destination, "yss-public-skills.json"));
+  await writeFile(path.join(destination, "skill-utils.yaml"), `schema_version: 1\nkind: yss-skill-utils\ntool_version: 1.0.0\ncompatibility: skill-utils-v1\nsource: ${path.basename(HARNESS_ROOT)}\ncanonical_root: .agents/skills\nprojection_roots:\n  - .codex/skills\n  - .claude/skills\n  - .cursor/skills\nexcluded_skills:\n  - yss-mvc-scaffold-generator\n`, "utf8");
+}
+
+export async function ensureSkillUtils(targetDir, { apply = true } = {}) {
+  const parent = path.dirname(targetDir);
+  const skillUtils = path.join(parent, SKILL_UTILS_NAME);
+  const marker = path.join(skillUtils, "skill-utils.yaml");
+  const expectedLock = await distributedSkillLock();
+  if (await exists(skillUtils)) {
+    if (!await exists(marker)) fail(`技能工具包目录已存在但不是受支持的 skillUtils: ${skillUtils}`);
+    const installedLock = path.join(skillUtils, "skills-lock.json");
+    const current = await exists(installedLock) ? await readFile(installedLock, "utf8") : "";
+    if (current === expectedLock) return { path: skillUtils, created: false, refreshed: false, backup: null };
+    if (!apply) return { path: skillUtils, created: false, refreshed: true, backup: null };
+    const staging = await mkdtemp(path.join(parent, ".skillUtils.refresh-"));
+    const backup = path.join(parent, `.skillUtils.backup-${Date.now()}`);
+    try {
+      await populateSkillUtils(staging);
+      await rename(skillUtils, backup);
+      try { await rename(staging, skillUtils); }
+      catch (error) { await rename(backup, skillUtils); throw error; }
+    } catch (error) {
+      if (await exists(staging)) await rm(staging, { recursive: true, force: true });
+      throw error;
+    }
+    return { path: skillUtils, created: false, refreshed: true, backup };
+  }
+  if (!apply) return { path: skillUtils, created: true, refreshed: false, backup: null };
+  await populateSkillUtils(skillUtils);
+  return { path: skillUtils, created: true, refreshed: false, backup: null };
+}