create-yss-spec 3.2.0 → 3.3.1

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/.trae/skills/yss-stage-decision/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yss-stage-decision
-description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
+description: 编排 Plan 到 Spec 入口的方案决策与业务边界、协作和规则设计；当需求、业务责任区、统一业务词汇或下游影响尚未稳定时使用。
 ---
 
 # YSS Stage Decision
@@ -9,14 +9,16 @@ description: 编排 Discovery 到 Spec 入口的方案决策与业务边界、
 
 ## 适用边界
 
-- 适用于 `project-instance` 的 Discovery → Spec 入口。
+- 适用于 `project-instance` 的 Plan → Spec 入口。
 - `template-source` 只维护本技能、Schema、验证器和合成 Fixture，不生成具体产品领域资产。
 - 业务边界与协作工作单元只回答：有哪些业务板块、每个业务责任区负责什么、不同责任区如何交接、使用哪些统一业务词汇、发生哪些业务事实、有哪些待确认的关键业务对象和不可违反的业务规则。
 - Entity、Aggregate、Repository、Java 类、数据库表和 OpenAPI Freeze 留给下游工作单元。
 
 ## 执行顺序
 
-1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Discovery/Spec、ADR 和父 Ticket/checkpoint。
+Plan 的目标与退出条件由 `docs/process/lifecycle-registry.yaml` 持有；从 `docs/plan/templates/plan-template.md` 汇总输入。旧资产按 `docs/process/plan-migration.md` 重新整理并核查，关键未决项不得延期到 Spec，非关键项记录责任人、解决时点与接收方。
+
+1. 读取 `yss-project.yaml`、`CONTEXT.md`、既有 Plan/Spec、ADR 和父 Ticket/checkpoint。
 2. 分离事实、决策、假设、约束和未决项；技术事实走 `yss-research` 的 `technical-evidence`，领域边界、业务规则、MVP、非目标、成功标准或阶段推进依据等决策证据走 `strategy-evidence`，市场/竞品事实走 `competitive-intelligence`。
 3. 从业务故事、已发生的事实、规则、责任人和失败路径识别业务板块与业务责任区，不从数据库表或调用链直接反推边界。
 4. 为每个业务责任区建立统一业务词汇；对跨责任区协作记录规则提供方、规则使用方、业务决策权、信息传递方向和口径转换负责人。

package/template/.trae/skills/yss-stage-decision/references/stage-decision-package-contract.md

@@ -1,6 +1,6 @@
 # 方案决策包合同
 
-内部对象 `stage_decision_package` 是 Discovery、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
+内部对象 `stage_decision_package` 是 Plan、需求/产品/商务决策与业务边界和规则设计之间的冻结入口。它记录“做什么、为什么做、范围是什么、哪些仍未决”，不复制业务边界与规则事实。
 
 ## 必须包含
 

package/template/AGENTS.md

@@ -38,11 +38,11 @@
 
 ## 5. `project-instance` 产品研发路由
 
-主流程：分诊 → Discovery → Spec / 功能架构 → 产品设计 → 工程契约 → Ticket → 切片 → 验证 / 发布 / 复盘。
+主流程：分诊 → Plan → Spec / 功能架构 → 产品设计 → 工程契约 → Ticket → 切片 → 验证 / 发布 / 复盘。
 
 - 先按 `docs/process/harness-process-tailoring.md` 判定影响面和最近可信阶段，再由 `yss-product-lifecycle` 执行 `docs/process/lifecycle-registry.yaml`；阅读导航见 `docs/process/lifecycle-artifact-map.md`。
 - 命中门禁必须完成；仅未命中时记录带原因的 `not-applicable`，不得生成空文档或混淆门禁、产物、工作单元、证据。安全 / 权限写入普通 Spec、契约、架构、验收和 seam，按实际影响触发门禁。
-- 新功能和较大变更先进入 Discovery；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
+- 新功能和较大变更先进入 Plan；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅为用户显式兼容入口。API 变更先形成 OpenAPI 3.1 Draft，审查后 Freeze，再实现。
 - Spec Delta 只记冻结基线的高风险行为差异。OpenAPI Freeze 或无 API 影响记录后拆窄垂直切片，禁止仅按技术层横拆。
 - `seam-deferred` 必须记录风险、责任人、后续 Ticket、验证计划和目标版本或发布日期。
 

package/template/CONTEXT.md

@@ -15,6 +15,7 @@ context_schema_version: 1
 
 | 术语 | 含义 | 英文标识 | 避免 / 备注 |
 |---|---|---|---|
+| Plan（战略规划） | 确认目标、业务边界、关键规则、MVP / 非目标、优先级和交接责任，为 Spec 提供已确认的战略输入。 | — | 问题探索是其中按需开展的活动；不等同于 AI-DLC 官方阶段名、交付排期或实现合同的 Context Plan。旧阶段 ID 已弃用，不提供兼容解析。 |
 | Agent | 执行特定工作流步骤的 AI 协作者。 | — | 不要与生物人审查者、数字人角色或 Ticket 状态混用。运行时实例（Cursor Agent、Claude Code、Grok Bot 等）是 Agent 的承载，不是角色本身。 |
 | 运行时绑定 | 把数字人角色落到某个 Agent 平台的适配声明，权威清单在数字人角色注册表的 `runtimes`。 | — | 不要为每个平台复制一套职称职责。 |
 | Grok Bot | Grok 平台上的持久数字队友实例；对应 `runtime.grok`。 | — | 不是数字人角色、技能或门禁。 |
@@ -26,9 +27,9 @@ context_schema_version: 1
 | 运行时副作用审批 | 对发消息、改生产、付款、删数据等工具动作的账号级确认。 | — | 点 Allow 不等于门禁已批准或可发布。避免只称「Grok 平台审批」。 |
 | Ticket 状态 | Tracker 五态：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。 | — | 不要称为数字人角色或「标准角色」。 |
 | 阶段协作组 | 某阶段需要共同可见会签的逻辑成员集合。 | — | 不是某个产品的群聊；平台人数上限只写在对应 `runtimes`。 |
-| 需求经理 | 主责 Discovery 语言、用户/MVP/非目标、Spec 正文与测试 seam 的数字人角色。 | — | 不拥有原型视觉定稿，不 Freeze API，不写实现。 |
+| 需求经理 | 主责 Plan 语言、用户/MVP/非目标、Spec 正文与测试 seam 的数字人角色。 | — | 不拥有原型视觉定稿，不 Freeze API，不写实现。 |
 | 产品经理 | 主责优先级、产品设计影响、原型确认建议、范围裁剪以及商业约束、交付承诺、发布窗口和商业非目标的数字人角色。 | — | 不写生产代码，不单独 Freeze API；对外商务合同和正式承诺须由生物人批准。 |
-| 商业约束 | Discovery 与发布阶段需要确认的商业边界、交付承诺、发布窗口和商业非目标。 | — | 由产品经理负责数字人侧的整理与协调；不等同于独立的“商务”数字人角色。 |
+| 商业约束 | Plan 与发布阶段需要确认的商业边界、交付承诺、发布窗口和商业非目标。 | — | 由产品经理负责数字人侧的整理与协调；不等同于独立的“商务”数字人角色。 |
 | Agent 入口规则 | Agent 启动任务时必须先遵守的全局路由、硬门禁和禁止事项。 | — | 不作为 YSS 后端、前端或其他专项编码规范的完整手册。 |
 | 标准文档语言 | 面向业务、产品、架构、实施、审查、发布和复盘的持久化文档所使用的默认语言。 | — | 统一使用简体中文；英文专有名词、代码标识、API 路径、schema、文件名和协议 metadata 保持原样。 |
 | Matt Engineering Skills | 来自 `mattpocock/skills` 的轻量工程流程技能集合。 | — | 用于澄清、Spec、Ticket、实现、TDD、诊断、审查和架构治理，不替代 YSS 专项规范。 |

package/template/README.md

@@ -23,7 +23,7 @@
 │   ├── api/                 ← OpenAPI 3.1 契约
 │   ├── adr/                 ← 架构决策记录
 │   ├── requirements/        ← Spec / 用户故事 / 需求草案 / 垂直切片
-│   ├── discovery/           ← 机会探索、市场、竞品和用户材料
+│   ├── plan/                ← 战略规划与 Spec 上游输入
 │   ├── design/              ← 产品设计、原型、交互说明和状态矩阵
 │   ├── architecture/        ← 架构设计与审查模板
 │   ├── releases/            ← 发布说明
@@ -42,7 +42,7 @@
 1. 先读取 `yss-project.yaml`，按 `repository_mode` 选择模板维护或产品研发生命周期。
 2. 必读入口为 `AGENTS.md` 与 `CONTEXT.md`；流程事实分别以生命周期映射和裁剪指南为准。
 3. `template-source` 修改后先按 `maintenance-intensity.yaml` 判定 L1 / L2 / L3，默认用 `scripts/verify-template-fast` 达到 `implementation-ready`；L3 日常采用维护者自检，正式发布前执行完整门禁；只有共享 skill 变更才运行 `scripts/sync-skills` 和 `scripts/update-skill-lock`。
-4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Discovery、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
+4. `project-instance` 默认从 `yss-product-lifecycle` 的 `route` 模式开始，再由原生 `work-unit.*` 推进 Plan、Spec、产品设计、工程契约和 Ticket 正式化；`grill-with-docs`、`to-spec`、`to-tickets`、`implement` 仅作为用户显式调用的兼容入口。
 5. 实现仓库接入、YSS 路由、独立审查、fresh verification 和 Git checkpoint 以 `AGENTS.md` 的硬门禁为准。
 
 YSS skills 的公开发布投影维护在 [iloveZzz/yss-spec-dev-skills](https://github.com/iloveZzz/yss-spec-dev-skills)，发布清单和导出命令见 [skills 维护说明](./docs/agents/skills-maintenance.md)。
@@ -115,7 +115,7 @@ scripts/verify-template-fast
 | [docs/agents/README.md](./docs/agents/README.md) | Agent 协作文档目录说明 |
 | [docs/agents/skills-maintenance.md](./docs/agents/skills-maintenance.md) | Agent skills 安装与维护 |
 | [docs/user-guide/yss-ui-mcp.md](./docs/user-guide/yss-ui-mcp.md) | YSS UI MCP 项目配置、全局安装边界与自检 |
-| [docs/discovery/IDEATION.md](./docs/discovery/IDEATION.md) | 机会构想方法 |
+| [docs/plan/IDEATION.md](./docs/plan/IDEATION.md) | 机会构想方法 |
 | [docs/architecture/README.md](./docs/architecture/README.md) | 架构设计 + 审查清单 |
 | [docs/testing/README.md](./docs/testing/README.md) | 测试策略 |
 

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

@@ -12,7 +12,7 @@
 |---|---|---|
 | 数字人角色 | 职称配置（需求经理、产品经理、前端工程师…） | Ticket 五态、某个平台的 Bot |
 | 主控数字人 | 生命周期编排器的运行时实例 | 第八个业务职称 |
-| 职能工作单元 | Discovery / Spec / Code / Review | 职称 |
+| 职能工作单元 | Plan / Spec / Code / Review | 职称 |
 | 执行态 | Explorer / Drafter / Worker / Reviewer / Verifier | 数字人角色 |
 | 运行时绑定 | 如何在 Cursor / Claude / Grok 等落地 | 角色职责本身 |