create-yss-spec 3.2.0 → 3.3.0

package/template/.trae/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs

@@ -1,24 +1,394 @@
 #!/usr/bin/env node
+import { createHash } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-const BACKEND = {"yss-cache":["yss-microservice-components/yss-component-cache-parent"],"yss-mybatis":["yss-microservice-components/yss-component-persistence"],"yss-dto":["yss-microservice-components/yss-component-dto"],"yss-audit-log":["yss-microservice-components/yss-component-audit-log"],"yss-excel-mvc":["yss-microservice-components/yss-component-excel-mvc","yss-microservice-components/yss-component-excel-starter"],"yss-distributed-id":["yss-microservice-components/yss-component-distributed-id","yss-microservice-components/yss-component-leaf"],"yss-resilience4j":["yss-microservice-components/yss-component-resilience4j-starter"],"yss-validation":["yss-microservice-components/yss-component-validation-engine-parent","yss-microservice-components/yss-component-validation-jsr303"],"yss-security-algorithm":["yss-microservice-components/yss-component-security-algorithm"],"yss-userinfo":["yss-microservice-components/yss-component-userinfo-starter"],"yss-exception":["yss-microservice-components/yss-component-exception"]};
-const FRONTEND={"yss-ui":["components","hooks","skills"],"yss-components":["components"],"yss-hook":["hooks"],"yss-ui-business-page-generation":["components","hooks","skills"],"yss-use-table-height":["hooks"],"yss-use-tree-height":["hooks"]};
-const URLS={components:"http://192.168.164.27:3200/components",hooks:"http://192.168.164.27:3200/hooks",skills:"http://192.168.164.27:3200/skills"};
-const KEYS=["Audit","Cache","Clear","Command","Configuration","Controller","DTO","Data","Enable","Excel","Handler","Interceptor","Jdbc","Mapper","Mybatis","Page","Properties","Query","Repository","Request","Response","Result","Update","Aspect","Leaf","Id","Dir","Dic","Dictionary","File","Upload","Log","Message","Mail","Liquibase","Circuit","Breaker","Sql","Tpl","Tag","Task","Flow","Report","Validation","Validator","Security","Crypto","User","Variable","Quality","Search","Similarity","Scheduler","Runner","Duck","Dynamic","Factory","Client","Feign","Gateway","Convertor","Adapter","Advice","Bridge","Route","Uploader","Sftp","Minio","Parser","Express","Rule","Template","Generator","Importer","Engine","Event","Submitter","Executor","Context","Status","Type","State"];
-const DOCS=new Set(["README.md","readme.md","HELP.md","TECHNICAL_DESIGN.md"]);
-const exists=async p=>{try{await access(p);return true}catch{return false}};
-async function walk(root){if(!await exists(root))return[];const out=[];for(const item of await readdir(root,{withFileTypes:true})){const p=path.join(root,item.name);if(item.isDirectory())out.push(...await walk(p));else if(item.isFile())out.push(p)}return out}
-const relative=(root,p)=>{const value=path.relative(root,p);return value&&!value.startsWith("..")?value:p};
-function state(root){try{const run=args=>execFileSync("git",["-C",root,...args],{encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim();return[run(["rev-parse","HEAD"]),run(["status","--porcelain"])?"dirty":"clean"]}catch{return["unavailable","unknown"]}}
-async function sourceRoot(){if(process.env.YSS_SOURCE_ROOT){const root=path.resolve(process.env.YSS_SOURCE_ROOT);if(await exists(path.join(root,"yss-microservice-components")))return root;throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`)}const home=os.homedir(),candidates=[process.cwd(),...ancestors(process.cwd()),path.join(home,"Documents/yss-project/yss-cloud-microservice"),path.join(home,"Documents/yss-project"),path.join(home,"Projects/yss-cloud-microservice"),path.join(home,"Projects")];for(const base of [path.join(home,"Projects"),path.join(home,"Documents"),path.join(home,"Documents/yss-project")])if(await exists(base))for(const entry of await readdir(base,{withFileTypes:true}))if(entry.isDirectory())candidates.push(path.join(base,entry.name));for(const root of candidates)if(await exists(path.join(root,"yss-microservice-components")))return path.resolve(root);throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.")}
-function ancestors(start){const out=[];let current=path.resolve(start);while(path.dirname(current)!==current){current=path.dirname(current);out.push(current)}return out}
-async function files(bases){const out={docs:[],poms:[],java:[]};for(const base of bases)for(const p of await walk(base)){if(DOCS.has(path.basename(p)))out.docs.push(p);else if(path.basename(p)==="pom.xml")out.poms.push(p);else if(p.endsWith(".java")&&p.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`))out.java.push(p)}for(const a of Object.values(out))a.sort();return out}
-export async function refresh({skillsRoot,source,now=new Date().toISOString(),frontend=true}){const [commit,worktree]=state(source);for(const [skill,parts]of Object.entries(BACKEND)){const bases=parts.map(item=>path.join(source,item));const found=await files(bases);const java=found.java.filter(p=>KEYS.some(key=>path.basename(p,".java").includes(key))).slice(0,120);const list=(items,map,empty)=>items.length?items.map(map):[empty];const baseHints=await Promise.all(bases.map(async p=>`- \`${relative(source,p)}\` (${await exists(p)?"existed":"missing"} when indexed)`));const lines=[`# ${skill} Source Index`,``,`Generated: ${now}`,`Source commit: \`${commit}\``,`Source worktree: \`${worktree}\``,`Indexed source root: resolved at refresh time; set \`YSS_SOURCE_ROOT\` to reproduce or refresh.`,``,`This file is generated by \`yss-skill-source-index-refresh/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.`,``,`## Component Path Hints`,``,...baseHints,``,`## Documentation Files`,``,...list(found.docs,p=>`- \`${relative(source,p)}\``,"- No component documentation files found."),``,`## Maven Modules`,``,...list(found.poms,p=>`- \`${relative(source,path.dirname(p))}\``,"- No Maven modules found."),``,`## Key Java Entry Points`,``,...list(java,p=>`- \`${relative(source,p)}\``,"- No key Java entry points matched the configured name patterns."),``,`## Recommended Next Reads`,``,`- Start with the documentation files above when learning component usage.`,`- Search the key Java entry points for annotations, auto configuration, properties, aspects, interceptors, handlers, and result objects before changing application code.`,`- Prefer existing component extension points over rewriting framework logic in business modules.`,``];const target=path.join(skillsRoot,skill,"references","source-index.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,lines.join("\n"),"utf8")}
- if(frontend)for(const[skill,keys]of Object.entries(FRONTEND)){if(!await exists(path.join(skillsRoot,skill)))continue;const target=path.join(skillsRoot,skill,"references","frontend-docs.md");await mkdir(path.dirname(target),{recursive:true});await writeFile(target,[`# ${skill} Frontend Documentation`,``,`Generated: ${now}`,``,`Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.`,``,...keys.map(key=>`- ${key}: ${URLS[key]}`),``,`When documentation and local code differ, inspect the current project code before editing and prefer established local usage.`,``].join("\n"),"utf8")}
- return{backend:Object.keys(BACKEND).length,frontend:frontend?Object.keys(FRONTEND).length:0}}
-async function main(){try{const script=path.dirname(fileURLToPath(import.meta.url));const result=await refresh({skillsRoot:path.resolve(process.env.YSS_SKILLS_ROOT||path.join(script,"../..")),source:await sourceRoot(),frontend:!["0","false","no"].includes((process.env.YSS_REFRESH_FRONTEND||"true").toLowerCase())});console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`)}catch(error){console.error(error.message);process.exitCode=1}}
-if(process.argv[1]===fileURLToPath(import.meta.url))await main();
+const BACKEND = {
+  "yss-cache": ["yss-microservice-components/yss-component-cache-parent"],
+  "yss-mybatis": ["yss-microservice-components/yss-component-persistence"],
+  "yss-dto": ["yss-microservice-components/yss-component-dto"],
+  "yss-audit-log": ["yss-microservice-components/yss-component-audit-log"],
+  "yss-excel-mvc": [
+    "yss-microservice-components/yss-component-excel-mvc",
+    "yss-microservice-components/yss-component-excel-starter",
+  ],
+  "yss-distributed-id": [
+    "yss-microservice-components/yss-component-distributed-id",
+    "yss-microservice-components/yss-component-leaf",
+  ],
+  "yss-resilience4j": ["yss-microservice-components/yss-component-resilience4j-starter"],
+  "yss-validation": [
+    "yss-microservice-components/yss-component-validation-engine-parent",
+    "yss-microservice-components/yss-component-validation-jsr303",
+  ],
+  "yss-security-algorithm": ["yss-microservice-components/yss-component-security-algorithm"],
+  "yss-userinfo": ["yss-microservice-components/yss-component-userinfo-starter"],
+  "yss-exception": ["yss-microservice-components/yss-component-exception"],
+};
+
+const FRONTEND = {
+  "yss-ui": ["components", "hooks", "skills"],
+  "yss-components": ["components"],
+  "yss-hook": ["hooks"],
+  "yss-ui-business-page-generation": ["components", "hooks", "skills"],
+  "yss-use-table-height": ["hooks"],
+  "yss-use-tree-height": ["hooks"],
+};
+
+const URLS = {
+  components: "http://192.168.164.27:3200/components",
+  hooks: "http://192.168.164.27:3200/hooks",
+  skills: "http://192.168.164.27:3200/skills",
+};
+
+const KEYS = [
+  "Audit", "Cache", "Clear", "Command", "Configuration", "Controller", "DTO", "Data", "Enable", "Excel",
+  "Handler", "Interceptor", "Jdbc", "Mapper", "Mybatis", "Page", "Properties", "Query", "Repository", "Request",
+  "Response", "Result", "Update", "Aspect", "Leaf", "Id", "Dir", "Dic", "Dictionary", "File", "Upload", "Log",
+  "Message", "Mail", "Liquibase", "Circuit", "Breaker", "Sql", "Tpl", "Tag", "Task", "Flow", "Report",
+  "Validation", "Validator", "Security", "Crypto", "User", "Variable", "Quality", "Search", "Similarity",
+  "Scheduler", "Runner", "Duck", "Dynamic", "Factory", "Client", "Feign", "Gateway", "Convertor", "Adapter",
+  "Advice", "Bridge", "Route", "Uploader", "Sftp", "Minio", "Parser", "Express", "Rule", "Template", "Generator",
+  "Importer", "Engine", "Event", "Submitter", "Executor", "Context", "Status", "Type", "State",
+];
+
+const DOCS = new Set(["README.md", "readme.md", "HELP.md", "TECHNICAL_DESIGN.md"]);
+const SKIPPED_DIRECTORIES = new Set([".git", "node_modules", "target", "build", "out", "${project.build.directory}"]);
+
+const MYBATIS_CAPABILITIES = [
+  {
+    title: "Repository abstractions",
+    sources: [
+      {
+        suffix: "/support/BaseRepository.java",
+        patterns: [/public interface BaseRepository/, /int (insert|insertSelective|insertList|updateList|updateListSelective)\(/],
+      },
+      {
+        suffix: "/support/BasePlusRepository.java",
+        patterns: [/public interface BasePlusRepository/, /insertBatchSomeColumn/],
+      },
+    ],
+  },
+  {
+    title: "Pagination and activation",
+    sources: [
+      { suffix: "/aop/EntityQueryAspect.java", patterns: [/@Around\(/, /PageHelper\.offsetPage/] },
+      { suffix: "/config/PageQueryEntityConfigration.java", patterns: [/@ConditionalOnProperty/] },
+      {
+        suffix: "/YssMybatisMapperProperties.java",
+        patterns: [
+          /@ConfigurationProperties/,
+          /private (String mapperLocation|String mapperScan|Integer batchSize|String dbType|PageHelper pageHelper|MybatisPlusPagination mybatisPlusPagination)/,
+          /public static class (PageHelper|MybatisPlusPagination)/,
+          /private Boolean enabled/,
+        ],
+      },
+      {
+        suffix: "/config/MapperConfiguration.java",
+        patterns: [/new PageInterceptor\(/, /new PaginationInnerInterceptor\(/, /setBatchSize\(/, /setDbType\(/],
+      },
+    ],
+  },
+  {
+    title: "SQL-level batch insertion",
+    sources: [
+      { suffix: "/config/BatchInsertSettings.java", patterns: [/DEFAULT_BATCH_SIZE/, /configuredBatchSize/] },
+      { suffix: "/config/BatchSqlInjector.java", patterns: [/public class BatchSqlInjector/, /insertBatchSomeColumnInternal/, /FieldFill\.UPDATE/] },
+      { suffix: "/config/DialectInsertBatchSomeColumn.java", patterns: [/public class DialectInsertBatchSomeColumn/, /DbType\.(ORACLE|ORACLE_12C|DM)/] },
+    ],
+  },
+  {
+    title: "Multi-data-source capability boundary",
+    sources: [
+      {
+        suffix: "/MultiDataSourceHolder.java",
+        patterns: [/public class MultiDataSourceHolder/, /Map<String, DataSource>/, /getMultiDataSource\(/],
+      },
+    ],
+  },
+];
+
+const exists = async (target) => {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+async function walk(root) {
+  if (!await exists(root)) return [];
+  const output = [];
+  for (const item of await readdir(root, { withFileTypes: true })) {
+    const target = path.join(root, item.name);
+    if (item.isDirectory() && !SKIPPED_DIRECTORIES.has(item.name)) output.push(...await walk(target));
+    else if (item.isFile()) output.push(target);
+  }
+  return output;
+}
+
+function relative(root, target) {
+  const value = path.relative(root, target).replaceAll(path.sep, "/");
+  return value && !value.startsWith("..") ? value : target;
+}
+
+function runGit(root, args) {
+  return execFileSync("git", ["-C", root, ...args], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"],
+  }).trim();
+}
+
+export function sourceState(root, componentPaths) {
+  try {
+    const commit = runGit(root, ["rev-parse", "HEAD"]);
+    const componentWorktree = runGit(root, ["status", "--porcelain", "--", ...componentPaths]) ? "dirty" : "clean";
+    const componentTrees = componentPaths.map((componentPath) => {
+      let tree = "missing";
+      try {
+        tree = runGit(root, ["rev-parse", `HEAD:${componentPath}`]);
+      } catch {
+        // The path can be newly added or absent in the indexed commit.
+      }
+      return { path: componentPath, tree };
+    });
+    return { commit, componentWorktree, componentTrees };
+  } catch {
+    return {
+      commit: "unavailable",
+      componentWorktree: "unknown",
+      componentTrees: componentPaths.map((componentPath) => ({ path: componentPath, tree: "unavailable" })),
+    };
+  }
+}
+
+async function sourceRoot() {
+  if (process.env.YSS_SOURCE_ROOT) {
+    const root = path.resolve(process.env.YSS_SOURCE_ROOT);
+    if (await exists(path.join(root, "yss-microservice-components"))) return root;
+    throw new Error(`YSS_SOURCE_ROOT must point to the repository root containing \`yss-microservice-components\`: ${root}`);
+  }
+
+  const home = os.homedir();
+  const candidates = [
+    process.cwd(),
+    ...ancestors(process.cwd()),
+    path.join(home, "Documents/yss-project/yss-cloud-microservice"),
+    path.join(home, "Documents/yss-project"),
+    path.join(home, "Projects/yss-cloud-microservice"),
+    path.join(home, "Projects"),
+  ];
+  for (const base of [path.join(home, "Projects"), path.join(home, "Documents"), path.join(home, "Documents/yss-project")]) {
+    if (!await exists(base)) continue;
+    for (const entry of await readdir(base, { withFileTypes: true })) {
+      if (entry.isDirectory()) candidates.push(path.join(base, entry.name));
+    }
+  }
+  for (const root of candidates) {
+    if (await exists(path.join(root, "yss-microservice-components"))) return path.resolve(root);
+  }
+  throw new Error("Could not find a YSS source repository containing `yss-microservice-components`. Export YSS_SOURCE_ROOT=/absolute/path/to/yss-cloud-microservice and rerun.");
+}
+
+function ancestors(start) {
+  const output = [];
+  let current = path.resolve(start);
+  while (path.dirname(current) !== current) {
+    current = path.dirname(current);
+    output.push(current);
+  }
+  return output;
+}
+
+async function files(bases) {
+  const output = { docs: [], poms: [], java: [], metadata: [] };
+  for (const base of bases) {
+    for (const target of await walk(base)) {
+      if (DOCS.has(path.basename(target))) output.docs.push(target);
+      else if (path.basename(target) === "pom.xml") output.poms.push(target);
+      else if (target.endsWith(".java") && target.includes(`${path.sep}src${path.sep}main${path.sep}java${path.sep}`)) output.java.push(target);
+      else if (path.basename(target) === "spring.factories") output.metadata.push(target);
+    }
+  }
+  for (const items of Object.values(output)) items.sort();
+  return output;
+}
+
+async function sha256(target) {
+  return createHash("sha256").update(await readFile(target)).digest("hex");
+}
+
+function list(items, render, empty) {
+  return items.length ? items.map(render) : [empty];
+}
+
+async function genericJavaEntries(source, javaFiles) {
+  const selected = javaFiles
+    .filter((target) => KEYS.some((key) => path.basename(target, ".java").includes(key)))
+    .slice(0, 120);
+  const output = [];
+  for (const target of selected) {
+    output.push(`- \`${relative(source, target)}\` — \`sha256:${await sha256(target)}\``);
+  }
+  return output.length ? output : ["- No key Java entry points matched the configured name patterns."];
+}
+
+function matchingLines(contents, patterns) {
+  return contents
+    .split(/\r?\n/)
+    .map((line, index) => ({ line: index + 1, text: line.trim().replace(/\s+/g, " ") }))
+    .filter(({ text }) => text && patterns.some((pattern) => pattern.test(text)))
+    .slice(0, 14);
+}
+
+async function mybatisCapabilityMatrix(source, javaFiles, metadataFiles) {
+  const output = ["## Capability Matrix", ""];
+  for (const capability of MYBATIS_CAPABILITIES) {
+    output.push(`### ${capability.title}`, "");
+    for (const expected of capability.sources) {
+      const target = javaFiles.find((candidate) => relative(source, candidate).endsWith(expected.suffix));
+      if (!target) {
+        output.push(`- \`${path.basename(expected.suffix)}\` — source not found.`);
+        continue;
+      }
+      const sourcePath = relative(source, target);
+      output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
+      const lines = matchingLines(await readFile(target, "utf8"), expected.patterns);
+      if (!lines.length) output.push("  - No configured public fact matched; refresh rules may need maintenance.");
+      else for (const fact of lines) output.push(`  - \`${sourcePath}:${fact.line}\` — \`${fact.text.replaceAll("`", "'")}\``);
+    }
+    output.push("");
+  }
+
+  output.push("### Auto-configuration registration", "");
+  for (const target of metadataFiles) {
+    const sourcePath = relative(source, target);
+    output.push(`- \`${sourcePath}\` — \`sha256:${await sha256(target)}\``);
+    const registrations = (await readFile(target, "utf8"))
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line && !line.startsWith("#"));
+    for (const registration of registrations.slice(0, 12)) output.push(`  - \`${registration.replaceAll("`", "'")}\``);
+  }
+  if (!metadataFiles.length) output.push("- No `spring.factories` registration found.");
+  output.push("");
+  return output;
+}
+
+async function backendIndex({ skill, parts, source, found, now, stateResolver }) {
+  const currentState = stateResolver(source, parts);
+  const bases = parts.map((item) => path.join(source, item));
+  const baseHints = await Promise.all(bases.map(async (target) =>
+    `- \`${relative(source, target)}\` (${await exists(target) ? "existed" : "missing"} when indexed)`,
+  ));
+  const treeLines = currentState.componentTrees.map(({ path: componentPath, tree }) =>
+    `Component tree \`${componentPath}\`: \`${tree}\``,
+  );
+  const lines = [
+    `# ${skill} Source Index`,
+    "",
+    `Generated: ${now}`,
+    `Source commit: \`${currentState.commit}\``,
+    `Component worktree: \`${currentState.componentWorktree}\``,
+    ...treeLines,
+    "Indexed source root: resolved at refresh time; set `YSS_SOURCE_ROOT` to reproduce or refresh.",
+    "",
+    "This file is generated by `yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.mjs`. Do not hand-edit generated sections.",
+    "",
+    "Paths are relocatable source hints. Exact guidance requires a matching component tree and a clean indexed component subtree; the repository commit is trace metadata and may differ when unrelated components change.",
+    "",
+    "## Component Path Hints",
+    "",
+    ...baseHints,
+    "",
+    "## Documentation Files",
+    "",
+    ...list(found.docs, (target) => `- \`${relative(source, target)}\``, "- No component documentation files found."),
+    "",
+    "Component documentation is a discovery aid. For API signatures, conditions and defaults, prefer the indexed source facts below when documentation differs.",
+    "",
+    "## Maven Modules",
+    "",
+    ...list(found.poms, (target) => `- \`${relative(source, path.dirname(target))}\``, "- No Maven modules found."),
+    "",
+  ];
+
+  if (skill === "yss-mybatis") lines.push(...await mybatisCapabilityMatrix(source, found.java, found.metadata));
+  else lines.push("## Key Java Entry Points", "", ...await genericJavaEntries(source, found.java), "");
+
+  lines.push(
+    "## Freshness and Use",
+    "",
+    "- Locate the current source root using `YSS_SOURCE_ROOT`, CodeGraph, Maven artifact names or repository search.",
+    "- Compare each indexed `Component tree` with `git rev-parse HEAD:<component-path>` and require the current component subtree to be clean before exact guidance.",
+    "- A repository commit difference alone is not stale when the component tree is unchanged; a component tree mismatch or component-local dirty state is stale.",
+    "- Read only the source entries needed for the current decision or troubleshooting path.",
+    "",
+  );
+  return lines.join("\n");
+}
+
+export async function refresh({
+  skillsRoot,
+  source,
+  now = new Date().toISOString(),
+  frontend = true,
+  backendSkills = Object.keys(BACKEND),
+  stateResolver = sourceState,
+}) {
+  const unknownSkills = backendSkills.filter((skill) => !(skill in BACKEND));
+  if (unknownSkills.length) throw new Error(`Unknown backend source-index skill: ${unknownSkills.join(", ")}`);
+  for (const skill of backendSkills) {
+    const parts = BACKEND[skill];
+    const bases = parts.map((item) => path.join(source, item));
+    const found = await files(bases);
+    const target = path.join(skillsRoot, skill, "references", "source-index.md");
+    await mkdir(path.dirname(target), { recursive: true });
+    await writeFile(target, await backendIndex({ skill, parts, source, found, now, stateResolver }), "utf8");
+  }
+
+  if (frontend) {
+    for (const [skill, keys] of Object.entries(FRONTEND)) {
+      if (!await exists(path.join(skillsRoot, skill))) continue;
+      const target = path.join(skillsRoot, skill, "references", "frontend-docs.md");
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, [
+        `# ${skill} Frontend Documentation`,
+        "",
+        `Generated: ${now}`,
+        "",
+        "Use these YSS UI documentation entry points as authoritative references when local repo examples are insufficient.",
+        "",
+        ...keys.map((key) => `- ${key}: ${URLS[key]}`),
+        "",
+        "When documentation and local code differ, inspect the current project code before editing and prefer established local usage.",
+        "",
+      ].join("\n"), "utf8");
+    }
+  }
+  return { backend: backendSkills.length, frontend: frontend ? Object.keys(FRONTEND).length : 0 };
+}
+
+async function main() {
+  try {
+    const script = path.dirname(fileURLToPath(import.meta.url));
+    const result = await refresh({
+      skillsRoot: path.resolve(process.env.YSS_SKILLS_ROOT || path.join(script, "../..")),
+      source: await sourceRoot(),
+      frontend: !["0", "false", "no"].includes((process.env.YSS_REFRESH_FRONTEND || "true").toLowerCase()),
+      backendSkills: process.env.YSS_REFRESH_BACKEND_SKILLS
+        ? process.env.YSS_REFRESH_BACKEND_SKILLS.split(",").map((skill) => skill.trim()).filter(Boolean)
+        : Object.keys(BACKEND),
+    });
+    console.log(`Updated ${result.backend} backend indexes and ${result.frontend} frontend doc references.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main();

package/template/.trae/skills/yss-skill-source-index-refresh/scripts/refresh-yss-skill-index.test.mjs

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
 import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
-import { refresh } from "./refresh-yss-skill-index.mjs";
+import { refresh, sourceState } from "./refresh-yss-skill-index.mjs";
 
 test("writes Node-labelled generated indexes", async () => {
   const root=await mkdtemp(path.join(tmpdir(),"yss-index-")); const source=path.join(root,"source"); const skills=path.join(root,"skills");
@@ -13,3 +14,80 @@ test("writes Node-labelled generated indexes", async () => {
   assert.match(await readFile(path.join(skills,"yss-cache/references/source-index.md"),"utf8"),/refresh-yss-skill-index\.mjs/);
   assert.match(await readFile(path.join(skills,"yss-ui/references/frontend-docs.md"),"utf8"),/components/);
 });
+
+test("writes a source-backed MyBatis capability matrix without absolute paths", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-mybatis-index-"));
+  const source = path.join(root, "source");
+  const skills = path.join(root, "skills");
+  const component = "yss-microservice-components/yss-component-persistence";
+  const plusJava = path.join(source, component, "yss-component-mybatis-plus-starter/src/main/java/com/yss/cloud/mybatis");
+  const baseJava = path.join(source, component, "yss-component-mybatis-starter/src/main/java/com/yss/cloud/mybatis");
+  const commonJava = path.join(source, component, "yss-component-persistence-common/src/main/java/com/yss/cloud/mybatis");
+
+  await mkdir(path.join(plusJava, "support"), { recursive: true });
+  await mkdir(path.join(baseJava, "config"), { recursive: true });
+  await mkdir(commonJava, { recursive: true });
+  await mkdir(path.join(skills, "yss-mybatis"), { recursive: true });
+  await writeFile(path.join(source, component, "pom.xml"), "<project/>");
+  await writeFile(path.join(plusJava, "support/BasePlusRepository.java"), [
+    "public interface BasePlusRepository<T> extends BaseMapper<T> {",
+    "  default Integer insertBatchSomeColumn(List<T> entities) { return 0; }",
+    "  Integer insertBatchSomeColumnInternal(List<T> entities);",
+    "}",
+  ].join("\n"));
+  await writeFile(path.join(baseJava, "config/PageQueryEntityConfigration.java"), [
+    "public class PageQueryEntityConfigration {",
+    "  @ConditionalOnProperty(name = \"yss.mybatis.page-helper.enabled\", havingValue = \"true\", matchIfMissing = true)",
+    "}",
+  ].join("\n"));
+  await writeFile(path.join(commonJava, "MultiDataSourceHolder.java"), [
+    "public class MultiDataSourceHolder {",
+    "  private Map<String, DataSource> multiDataSource;",
+    "}",
+  ].join("\n"));
+
+  await refresh({
+    skillsRoot: skills,
+    source,
+    now: "2026-01-01T00:00:00Z",
+    frontend: false,
+    backendSkills: ["yss-mybatis"],
+    stateResolver: () => ({
+      commit: "a".repeat(40),
+      componentWorktree: "clean",
+      componentTrees: [{ path: component, tree: "b".repeat(40) }],
+    }),
+  });
+
+  const index = await readFile(path.join(skills, "yss-mybatis/references/source-index.md"), "utf8");
+  assert.match(index, /## Capability Matrix/);
+  assert.match(index, /BasePlusRepository<T>/);
+  assert.match(index, /yss\.mybatis\.page-helper\.enabled/);
+  assert.match(index, /Map<String, DataSource>/);
+  assert.match(index, /Component worktree: `clean`/);
+  assert.match(index, /Component tree.*b{40}/);
+  assert.doesNotMatch(index, new RegExp(root.replaceAll("/", "\\/")));
+  assert.doesNotMatch(index, /## Key Java Entry Points/);
+});
+
+test("source freshness is scoped to the indexed component subtree", async () => {
+  const root = await mkdtemp(path.join(tmpdir(), "yss-component-state-"));
+  const component = "yss-microservice-components/yss-component-persistence";
+  const componentFile = path.join(root, component, "pom.xml");
+  const unrelatedFile = path.join(root, "yss-microservice-components/other/README.md");
+  await mkdir(path.dirname(componentFile), { recursive: true });
+  await mkdir(path.dirname(unrelatedFile), { recursive: true });
+  await writeFile(componentFile, "<project/>\n");
+  await writeFile(unrelatedFile, "clean\n");
+  execFileSync("git", ["init", "-q"], { cwd: root });
+  execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: root });
+  execFileSync("git", ["config", "user.name", "Test"], { cwd: root });
+  execFileSync("git", ["add", "."], { cwd: root });
+  execFileSync("git", ["commit", "-qm", "fixture"], { cwd: root });
+
+  await writeFile(unrelatedFile, "dirty elsewhere\n");
+  assert.equal(sourceState(root, [component]).componentWorktree, "clean");
+
+  await writeFile(componentFile, "<project><dirty/></project>\n");
+  assert.equal(sourceState(root, [component]).componentWorktree, "dirty");
+});

package/template/docs/agents/digital-human-roles.yaml

@@ -219,6 +219,7 @@ gate_policy:
     - gate.repository-identity-valid
     - gate.prototype-verified
   orchestrator:
+    - gate.implementation-repositories-ready
     - gate.slice-contract-approved
     - gate.slice-ready-for-agent
   digital_human_review:
@@ -275,6 +276,7 @@ user_decision_policy:
   work_units:
     work-unit.discovery-requirements: discovery-conclusion
     work-unit.service-project-initialization: scaffold-choice
+    work-unit.implementation-repository-preparation: scaffold-choice
     work-unit.slice-implementation: implementation-scope
     work-unit.release-and-retrospective: gate.release-ready
   work_unit_gates:

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

@@ -85,6 +85,7 @@ capabilities:
   - { id: component.gateway-resilience, primary_skill: yss-resilience4j, task_modes: [guidance, integration, slice-implementation, troubleshooting, component-maintenance, review-input] }
   - { id: scaffold.ddd, primary_skill: yss-ddd-scaffold-generator, task_modes: [integration, component-maintenance] }
   - { id: scaffold.layered-mvc, primary_skill: yss-layered-mvc-scaffold-generator, task_modes: [integration, component-maintenance] }
+  - { id: scaffold.frontend-vue3, primary_skill: yss-frontend-scaffold-generator, task_modes: [integration, component-maintenance] }
   - { id: project-init.mvc-data-analysis, primary_skill: yss-mvc-data-analysis-project-initializer, task_modes: [component-maintenance] }
   - { id: migration.springboot3, primary_skill: yss-up-springboot3, task_modes: [guidance, integration, troubleshooting, component-maintenance, review-input] }
 recipes:
@@ -106,8 +107,12 @@ recipes:
   - { id: backend.distributed-id, capabilities: [component.distributed-id] }
   - { id: backend.ddd-scaffold, capabilities: [scaffold.ddd, quality.java-code-style] }
   - { id: backend.mvc-scaffold, capabilities: [scaffold.layered-mvc, quality.java-code-style] }
+  - { id: frontend.vue3-scaffold, capabilities: [scaffold.frontend-vue3] }
   - { id: backend.springboot3-migration, capabilities: [migration.springboot3, quality.java-code-style] }
 skill_dependencies:
+  code-review:
+    - { skill: yss-repository, type: context-conditional, when: backend-persistence-impact }
+    - { skill: yss-mybatis, type: context-conditional, when: backend-persistence-impact }
   yss-prototype-stage:
     - { skill: prototype-review, type: review-only }
     - { skill: yss-design-system, type: coordination-only }

package/template/docs/process/lifecycle-artifact-map.md

@@ -39,6 +39,7 @@
 | `gate.openapi-frozen` | OpenAPI Freeze | `stage.system-data-engineering` | API 进入实现。 | 无 | `evidence.approval-record` |
 | `gate.engineering-baseline-accepted` | 工程基线 | `stage.system-data-engineering` | 后端、前端或高风险工程变化。 | 无 | `evidence.fresh-verification` |
 | `gate.architecture-reviewed` | 架构审查 | `stage.system-data-engineering` | 高风险或跨边界变化。 | 无 | `evidence.design-review-result` |
+| `gate.implementation-repositories-ready` | 实现仓库准备就绪 | `stage.system-data-engineering` | 后端或前端交付面进入 Ticket 正式化；未命中的交付面须记录带原因的 not-applicable。 | `gate.engineering-baseline-accepted` | `evidence.implementation-repository-preparation`、`evidence.fresh-verification` |
 | `gate.slice-contract-approved` | Slice Implementation Contract 批准 | `stage.ticket-formalization` | Agent 进入实现；脚手架完成后每个后续生成代码工作单元。 | 无 | `evidence.contract-approval` |
 | `gate.slice-ready-for-agent` | 垂直切片实现就绪 | `stage.ticket-formalization` | 垂直切片具备直接实现条件。 | 无 | `evidence.contract-approval`、`evidence.approval-record` |
 | `gate.frontend-implementation-verified` | 前端实现还原验证 | `stage.verification-release-retrospective` | UI 影响切片完成实现并准备合并、发布或阶段完成。 | 无 | `evidence.frontend-implementation-verification` |
@@ -67,6 +68,8 @@
 | `artifact.engineering-baseline` | 工程基线记录 | `stage.system-data-engineering` | 后端、前端或高风险工程变化。 |
 | `artifact.architecture-review` | 架构审查记录 | `stage.system-data-engineering` | 高风险或跨边界变化。 |
 | `artifact.technical-design` | 技术设计合同 | `stage.system-data-engineering` | 后端技术设计需要按已确认 DDD 或 MVC 架构明确行为、分层、一致性或数据映射。 |
+| `artifact.project-scaffold-contract` | Project Scaffold Contract | `stage.system-data-engineering` | 命中的前端或后端交付面选择初始化新工程。 |
+| `artifact.implementation-repository-preparation-result` | 实现仓库准备结果 | `stage.system-data-engineering` | 后端或前端交付面进入 Ticket 正式化。 |
 | `artifact.tactical-design` | DDD 战术设计 | `stage.system-data-engineering` | 聚合边界、状态机、一致性或持久化映射复杂到无法在系统概要设计的 Tactical DDD Check 中清楚表达。 |
 | `artifact.spec-delta` | Spec Delta | `stage.spec-architecture` | 已有冻结 Spec 的高风险行为变化。 |
 | `artifact.parent-ticket` | 功能父 Ticket | `stage.ticket-formalization` | 每个进入追踪的功能。 |
@@ -101,6 +104,7 @@
 | `evidence.yss-skill-execution-result` | YSS Skill Execution Result | 专项 skill 的合同版本、写入、验证、延期 seam 与偏离证据。 |
 | `evidence.frontend-implementation-verification` | 前端实现还原验证证据 | UI 实现相对冻结原型和 Spec 的桌面/窄屏视觉、状态、交互、控制台与 pnpm 验证记录。 |
 | `evidence.fresh-verification` | Fresh Verification 记录 | 本轮实际执行的验证命令、结果和时间。 |
+| `evidence.implementation-repository-preparation` | 实现仓库准备证据 | 按项目记录交付面、已有仓库接入或新脚手架合同、生成清单、实际验证结果、仓库位置、Git 边界和当前版本。 |
 | `evidence.checkpoint-and-rollback` | Checkpoint 与回滚点 | 可追溯的变更边界、发布记录和恢复动作。 |
 <!-- lifecycle-registry:structure:end -->
 

package/template/docs/process/lifecycle-registry-baseline.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "registry_id": "yss.lifecycle",
-  "semantic_sha256": "4eadc734957c5112dad60ec9fe4d844ac8790cbe798fbd8177ee60eae6dbe1fa",
+  "semantic_sha256": "68c053060bb837fe4bc2b40d7a6ffcea1a53fc6b5e6b929eb0858824c657a15d",
   "published_ids": [
     "artifact.architecture-review",
     "artifact.data-architecture",
@@ -13,12 +13,14 @@
     "artifact.functional-architecture",
     "artifact.high-fidelity-html-prototype",
     "artifact.impact-assessment",
+    "artifact.implementation-repository-preparation-result",
     "artifact.interaction-spec",
     "artifact.low-fidelity-prototype",
     "artifact.openapi-draft",
     "artifact.openapi-freeze-record",
     "artifact.parent-ticket",
     "artifact.product-overview",
+    "artifact.project-scaffold-contract",
     "artifact.prototype-confirmation",
     "artifact.prototype-deliverable",
     "artifact.prototype-review",
@@ -42,6 +44,7 @@
     "evidence.fresh-verification",
     "evidence.frontend-implementation-verification",
     "evidence.impact-assessment",
+    "evidence.implementation-repository-preparation",
     "evidence.maintenance-intensity-checkpoint",
     "evidence.openapi-draft-review",
     "evidence.prototype-confirmation",
@@ -59,6 +62,7 @@
     "gate.engineering-baseline-accepted",
     "gate.frontend-delivery-inputs-verified",
     "gate.frontend-implementation-verified",
+    "gate.implementation-repositories-ready",
     "gate.openapi-draft-reviewed",
     "gate.openapi-frozen",
     "gate.prototype-reviewed",
@@ -86,6 +90,7 @@
     "work-unit.entry-triage",
     "work-unit.fresh-verification",
     "work-unit.frontend-implementation-verification",
+    "work-unit.implementation-repository-preparation",
     "work-unit.independent-review",
     "work-unit.intensity-aware-review",
     "work-unit.intensity-aware-verification",