@routerhub/agent-rules 1.5.142 → 1.5.143

package/merge.js

@@ -74,6 +74,37 @@ function readFileIfExists(filePath) {
   return null;
 }
 
+/**
+ * 只在内容变化时写盘（不变量写入 => 磁盘 mtime 不变 => 缓存命中率更高）
+ *
+ * 为什么这样写（对应「缓存命中」优化思路）：
+ * - AI 工具链（Claude Code / Copilot）按文件内容缓存，部分按 mtime 感知变化；
+ *   只要内容没变，反复执行 sync 也会触发一次「写盘 -> mtime 变化 -> 下游以为规则变了」
+ *   的假变更，实际内容一个字都没变，缓存却因此白白失效一次。
+ * - 改成「内容哈希相同则跳过写入」：内容没变，文件字节和 mtime 完全不动，
+ *   下游不会误判「规则变了」，缓存能一直续上；内容真正变了才写一次、失效一次，
+ *   这才是合理的失效。
+ * - 内容统一结尾加一个换行：消除「尾部换行符有无」这种看不见的抖动，
+ *   保证「同一份内容」永远生成出完全一样的字节，不因结尾风格差异触发缓存失效。
+ *
+ * @param {string} filePath 目标文件绝对路径
+ * @param {string} content  生成后的完整内容
+ * @returns {boolean} 是否真正写入了磁盘（false = 内容未变，跳过写入）
+ */
+function writeFileIfChanged(filePath, content) {
+  const normalizedContent = content.endsWith("\n") ? content : content + "\n";
+  const existing = readFileIfExists(filePath);
+
+  // 内容完全相同（含结尾换行也一致）=> 不写盘，保持 mtime 不变
+  if (existing !== null && existing === normalizedContent) {
+    return false;
+  }
+
+  ensureParentDir(filePath);
+  fs.writeFileSync(filePath, normalizedContent, "utf-8");
+  return true;
+}
+
 /**
  * 解析 markdown 文件的 YAML frontmatter
  * 返回 { meta: { name, applyTo, outputName }, content: "去掉 frontmatter 后的正文" }
@@ -234,7 +265,7 @@ function generateRulesFromBase(baseRulesPath, rulesDir) {
 
   const globalFrontmatter = '---\nname: "通用规则"\n---\n\n';
   const globalPath = path.join(rulesDir, "global.md");
-  fs.writeFileSync(globalPath, globalFrontmatter + globalText + "\n", "utf-8");
+  writeFileIfChanged(globalPath, globalFrontmatter + globalText);
   console.log(`   ✅ rules/global.md`);
 
   // 生成各域的 rules/*.md
@@ -255,7 +286,7 @@ function generateRulesFromBase(baseRulesPath, rulesDir) {
     ].join("\n");
 
     const filePath = path.join(rulesDir, meta.fileName);
-    fs.writeFileSync(filePath, frontmatter + domainText.trim() + "\n", "utf-8");
+    writeFileIfChanged(filePath, frontmatter + domainText.trim());
     console.log(`   ✅ rules/${meta.fileName}`);
   }
 
@@ -339,8 +370,7 @@ function generateInstructionFile(
   const frontmatter = `---\napplyTo: ${JSON.stringify(applyTo)}\n---\n`;
   const fileContent = frontmatter + "\n" + content;
 
-  ensureParentDir(outputPath);
-  fs.writeFileSync(outputPath, fileContent, "utf-8");
+  writeFileIfChanged(outputPath, fileContent);
   console.log(`✅ 条件规则已生成: ${outputPath}`);
 }
 
@@ -386,8 +416,7 @@ function generateNoReviewInstructionFile(instructionsDir) {
     "Treat these files as generated artifacts and skip them entirely.",
   ].join("\n");
 
-  ensureParentDir(outputPath);
-  fs.writeFileSync(outputPath, frontmatter + "\n" + body + "\n", "utf-8");
+  writeFileIfChanged(outputPath, frontmatter + "\n" + body);
   console.log(`✅ Code Review 跳过规则已生成: ${outputPath}`);
 }
 
@@ -397,8 +426,7 @@ function syncPrTemplate(config) {
   const output = config.prTemplateOutput || defaultConfig.prTemplateOutput;
   const content = readFileIfExists(src);
   if (!content) return;
-  ensureParentDir(output);
-  fs.writeFileSync(output, content, "utf-8");
+  writeFileIfChanged(output, content);
   console.log(`✅ PR 模板已同步到 ${output}`);
 }
 
@@ -486,8 +514,7 @@ function mergeAgents(config) {
     }
 
     for (const outputPath of [agentsOutput, claudeOutput, copilotOutput]) {
-      ensureParentDir(outputPath);
-      fs.writeFileSync(outputPath, merged, "utf-8");
+      writeFileIfChanged(outputPath, merged);
       console.log(`✅ 规则已合并到 ${outputPath}`);
     }
 
@@ -510,8 +537,7 @@ function mergeAgents(config) {
   if (privateDomains.global) {
     copilotContent += "\n\n---\n\n# 项目私有规则\n\n" + privateDomains.global;
   }
-  ensureParentDir(copilotOutput);
-  fs.writeFileSync(copilotOutput, copilotContent, "utf-8");
+  writeFileIfChanged(copilotOutput, copilotContent);
   console.log(`✅ 全局规则已生成: ${copilotOutput}`);
 
   // 5. 生成 .github/instructions/*.instructions.md（各域规则）
@@ -551,13 +577,11 @@ function mergeAgents(config) {
       "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
       privateContent;
   }
-  ensureParentDir(agentsOutput);
-  fs.writeFileSync(agentsOutput, agentsMerged, "utf-8");
+  writeFileIfChanged(agentsOutput, agentsMerged);
   console.log(`✅ 全量规则已合并到 ${agentsOutput}`);
 
   // CLAUDE.md 与 AGENTS.md 内容一致，供 Claude Code 会话自动加载
-  ensureParentDir(claudeOutput);
-  fs.writeFileSync(claudeOutput, agentsMerged, "utf-8");
+  writeFileIfChanged(claudeOutput, agentsMerged);
   console.log(`✅ 全量规则已合并到 ${claudeOutput}`);
 
   // 6.1 同步 Skills 到项目 .claude/skills/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.5.142",
+  "version": "1.5.143",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {