@routerhub/agent-rules 1.5.141 → 1.5.143

package/AGENTS.base.md

@@ -310,7 +310,7 @@
 
 ## 功能开发（可视化验证驱动）
 
-- ⚠️ **接收新需求 / 功能开发时，自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
 - ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级

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

package/rules/global.md

@@ -310,7 +310,7 @@ name: "通用规则"
 
 ## 功能开发（可视化验证驱动）
 
-- ⚠️ **接收新需求 / 功能开发时，自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
+- ⚠️ **日常对话中，只要聊到写代码/改代码/排查问题/验证功能/实现需求等任何越过「闲聊」的实质内容，就自动触发 `/visual-report` skill，用它管理「验证证据」的产出**，无需用户额外吩咐。触发不依赖于用户正式说「提需求」「做功能」——用户在平常对话里随口提到的开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」）同样自动触发。该 skill 的职责是：真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
 - ⚠️ **只有用户显式提到「测试 / TDD / 测试用例」时，才调用 `/tdd-workflow` skill**（写测试用例、跑回归）。没有明确指令时，禁止把 TDD 当作默认开发流程；默认开发流程是上面的 `/visual-report`。
 
 ## 优先级

package/skills/visual-report/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: visual-report
 description: >-
-  功能开发/需求实现的可视化验证证据产出流程（默认触发，替代「测试先行」）。
-  触发场景：用户提出任何新需求、新功能、功能开发、修改功能、修复 bug、
-  「帮我开发」「帮我实现」「帮我写」「帮我做」「改一下」「优化一下」「重构一下」等
-  所有需要写代码产出功能的场景——只要用户是在提需求/做功能，就自动触发本 Skill，
-  无需用户额外说「做验证」「加测试」「写报告」。
+  功能开发/需求实现的可视化验证证据产出流程（日常对话自动触发，替代「测试先行」）。
+  触发场景：日常对话中用户提出/聊到任何新需求、新功能、功能开发、修改功能、修复 bug、
+  「帮我开发」「帮我实现」「帮我写」「帮我做」「改一下」「优化一下」「重构一下」，
+  以及「这个页面的按钮没反应」「Redis 里这个 key 好像不对」「帮我把这个查询优化一下」等
+  任何越过「闲聊」、涉及写代码/改代码/排查问题/验证功能/实现需求的实质内容——
+  只要对话进入这类实质内容，就自动触发本 Skill，无需用户额外说「做验证」「加测试」「写报告」。
+  触发不依赖用户正式说「提需求/做功能」；日常对话里随口提到的开发任务同样触发。
   职责：用真实数据 + 真实交互 + 可视化证据（页面截图 / Redis 截图 / 数据库截图），
   把「功能对不对」用用户能一眼看懂的截图和报告证明给用户看。
   ⚠️ 仅当用户显式提到「测试 / TDD / 测试用例」时才改走 /tdd-workflow。
@@ -23,7 +25,7 @@ description: >-
 
 ## 触发时机
 
-- **用户提需求 / 做功能 / 改 bug → 自动触发本 Skill**，不用等用户吩咐。
+- **日常对话里只要出现实质性开发内容就自动触发本 Skill**，不依赖用户说「提需求/做功能」。包括：写代码、改代码、修 bug、排查问题、优化、重构、实现一个小功能，以及用户随口描述的一个开发任务（如「这个页面的按钮没反应」「Redis 里这个 key 好像不对」）。都要默认走可视化验证。
 - 用户说「加测试 / TDD / 测试用例」→ 改走 `/tdd-workflow`。
 
 ## 验证矩阵（什么改动截什么证）