@routerhub/agent-rules 1.5.142 → 1.5.144

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.144",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {

package/skills/deploy-test/SKILL.md

@@ -40,6 +40,17 @@ git commit -m "..."  # 使用有意义的提交信息
 git push origin "$ORIGINAL_BRANCH"
 ```
 
+⚠️ **若本次改动经过循环 review（`loop-review` 修复过代码），必须确认所有 review 修复已同步到当前功能分支（PR 对应分支）并推送远程，再进行 test 合并。** 核对方式：
+
+```bash
+# 确认本地功能分支与远程已同步（本地无未推送提交）
+git status
+git log origin/"$ORIGINAL_BRANCH".."$ORIGINAL_BRANCH" --oneline   # 应无输出 = 无未推送提交
+```
+
+- ⚠️ 若 review 修复还没合进当前功能分支 → 先把修复 commit 到功能分支再推送，禁止带着"修复只在 test 分支"的状态去部署。
+- ⚠️ feature 分支与 test 分支两条线必须保持同步：**所有 review 修复代码必须先落 feature 分支（PR 分支），再合并到 test**，缺一不可。
+
 ### 3. test 分支检查
 
 如果 `test` 分支不存在，从主分支创建：

package/skills/loop-review/SKILL.md

@@ -121,6 +121,7 @@ gh api repos/$REPO/pulls/$PR/reviews?per_page=100 --jq \
 - 判定「值得修」的（无论严重度）→ 每个修复单独 commit，commit 信息用中文，正文引用对应 review 来源
 - 纯建议级且判定值得改的 → 合并为一个 commit
 - 判定「不值得修 / 已处理 / 误报」的 → 按步骤 4 回复，切断 bot 下轮重提
+- ⚠️ **所有修复必须直接 commit 在当前 PR 对应的 feature 分支上**（`git push origin <feature 分支>`），并推送到远程。禁止把 review 修复只放在其他地方（例如直接堆到 test 分支、或修改后不 commit）。**宗旨：feature 分支（PR）与 test 分支两条线保持同步，修复代码同时存在于 feature 分支和 test 分支，缺一不可。**
 
 ### 4. 对「不改」的建议回复（防重复循环，关键）
 
@@ -204,6 +205,7 @@ done
 - ⚠️ **禁止使用 `[skip ci]` / `[skip review]`**——循环依赖「每次 push 触发 review」，跳过就断了。
 - ⚠️ **必须设最大轮数（默认 5；用户明确要求深度循环时最多 8）和等待超时（默认 15 分钟）**，禁止无限循环 / 无限等待。
 - ⚠️ **已修复的功能性问题单独 commit**，禁止与大量建议级改动混在一起，保证每轮 push 的 diff 可读。
+- ⚠️ **每条 review 修复都必须同 commit 回 PR 对应的 feature 分支并推送远程**，不得只推到 test 分支或只放在工作区不 commit。feature 分支与 test 分支两条线必须同步，缺一不可（详见步骤 3）。
 - ⚠️ **等待 bot 审查期间遵守心跳约定**：超过 1 分钟无输出主动说明在等什么。
 - ⚠️ **commit 用中文、禁止 `git push --force`、commit 信息引用对应 review 来源**。
 - ⚠️ **两模型报同一问题合并为一条处理**，不要重复改两遍。