@routerhub/agent-rules 1.3.11 → 1.4.1

package/AGENTS.base.md

@@ -55,6 +55,7 @@
 - 不允许写 `class`，统一使用函数式编程。
 - 不要写 `try/catch`。
 - 代码注释统一使用中文编写。
+- 每一行代码都必须有对应的中文注释，明确说明该行代码的作用。
 - 能复用现有函数或配置时，不要复制粘贴出第二份近似实现。
 - 编写 Go 代码时，优先使用值传递与局部变量生命周期控制，避免不必要的内存逃逸（如无必要不要返回局部变量指针、避免在热路径中产生额外堆分配）。
 - 编写代码需遵循 SOLID 原则，并结合场景合理应用设计模式优化可维护性与扩展性，避免过度设计。
@@ -70,6 +71,13 @@
 
 - 每次开发新功能时，尽可能将其封装为组件，方便后续在其它页面或场景中复用。
 
+## 需求文档前置规则
+
+- 每次开始实现新需求前，必须先编写对应的需求说明 MD 文档。
+- 需求文档统一存放在项目根目录的 `docs/` 文件夹下。
+- 需求文档至少包含以下内容：需求目标、需求范围、功能要求、验收标准。
+- 如存在补充信息，需在文档中增加“备注”章节说明。
+
 ## 依赖安装规范
 
 - 无论在 Docker 环境还是本地环境，安装和下载依赖都必须使用 `pnpm`，禁止使用 `npm install`、`yarn install` 等其它包管理器安装命令。

package/README.md

@@ -2,7 +2,7 @@
 
 只做两件事：
 
-1. 生成项目可用的 `AGENTS.md`
+1. 生成项目可用的 `AGENTS.md` 和 `.github/copilot-instructions.md`
 2. 自动监听 `AGENTS.private.md` 并同步
 
 完整中文说明见 `README.zh-CN.md`。
@@ -28,6 +28,6 @@ pnpm add -D concurrently @routerhub/agent-rules
 ```
 
 作用：
-- 监听 `AGENTS.private.md` 变更
-- 变更后自动重新同步 `AGENTS.md`
 
+- 监听 `AGENTS.private.md` 变更
+- 变更后自动重新同步 `AGENTS.md` 和 `.github/copilot-instructions.md`

package/README.zh-CN.md

@@ -1,10 +1,10 @@
 # @routerhub/agent-rules 中文说明
 
-`@routerhub/agent-rules` 用来把通用规则和项目私有规则合并成项目根目录下可直接使用的 `AGENTS.md`。
+`@routerhub/agent-rules` 用来把通用规则和项目私有规则合并成项目中可直接使用的规则文件。
 
 它主要提供两类能力：
 
-1. 生成项目可用的 `AGENTS.md`
+1. 生成项目可用的 `AGENTS.md` 和 `.github/copilot-instructions.md`
 2. 监听 `AGENTS.private.md` 变更并自动同步
 
 ## 安装
@@ -27,7 +27,7 @@ pnpm exec agent-rules init
 
 ## 同步规则
 
-将基础规则与项目私有规则合并为 `AGENTS.md`：
+将基础规则与项目私有规则合并为 `AGENTS.md` 和 `.github/copilot-instructions.md`：
 
 ```bash
 pnpm exec agent-rules sync
@@ -41,7 +41,7 @@ pnpm exec agent-rules sync
 
 ## 监听模式
 
-开发时建议通过监听模式自动保持 `AGENTS.md` 最新：
+开发时建议通过监听模式自动保持规则文件最新：
 
 ```json
 {
@@ -53,7 +53,7 @@ pnpm exec agent-rules sync
 
 监听模式会：
 
-- 先执行一次同步，生成最新的 `AGENTS.md`
+- 先执行一次同步，生成最新的 `AGENTS.md` 和 `.github/copilot-instructions.md`
 - 持续监听项目根目录下的 `AGENTS.private.md`
 - 在文件变更后自动重新同步
 
@@ -61,7 +61,8 @@ pnpm exec agent-rules sync
 
 - `AGENTS.base.md`：规则包内置的通用基础规则
 - `AGENTS.private.md`：项目自己的私有规则
-- `AGENTS.md`：最终合并结果，供项目中的 Copilot 或 Agent 使用
+- `AGENTS.md`：最终合并结果，供项目中的 Agent 使用
+- `.github/copilot-instructions.md`：最终合并结果，供 GitHub Copilot 强制规则使用
 
 ## 推荐用法
 
@@ -76,4 +77,4 @@ pnpm exec agent-rules sync
 
 - 私有规则应只写项目特有的限制、接口地址、组件路径和业务规范
 - 通用规范应维护在规则包的 `AGENTS.base.md` 中
-- 若私有规则与基础规则冲突，以项目私有规则为准
+- 若私有规则与基础规则冲突，以项目私有规则为准

package/merge.js

@@ -12,200 +12,245 @@
  *   watch 监听 AGENTS.private.md 变化并自动同步
  */
 
-const fs = require('fs')
-const path = require('path')
+const fs = require("fs");
+const path = require("path");
 
-const packageRoot = __dirname
-const currentRoot = process.cwd()
+const packageRoot = __dirname;
+const currentRoot = process.cwd();
 
-let syncTimer = null
-let isSyncing = false
-let pendingSync = false
+let syncTimer = null;
+let isSyncing = false;
+let pendingSync = false;
 
 function getDefaultConfig() {
   return {
-    output: path.join(currentRoot, 'AGENTS.md'),
-    baseRulesPath: path.join(packageRoot, 'AGENTS.base.md'),
-    privateRulesPath: path.join(currentRoot, 'AGENTS.private.md'),
+    output: path.join(currentRoot, "AGENTS.md"),
+    copilotOutput: path.join(currentRoot, ".github", "copilot-instructions.md"),
+    baseRulesPath: path.join(packageRoot, "AGENTS.base.md"),
+    privateRulesPath: path.join(currentRoot, "AGENTS.private.md"),
+  };
+}
+
+function ensureParentDir(filePath) {
+  const parentDir = path.dirname(filePath);
+  fs.mkdirSync(parentDir, { recursive: true });
+}
+
+function resolveOutputPaths(config) {
+  if (Array.isArray(config.outputs) && config.outputs.length > 0) {
+    return config.outputs;
   }
+
+  const defaultConfig = getDefaultConfig();
+  const output = config.output || defaultConfig.output;
+  const copilotOutput = config.copilotOutput || defaultConfig.copilotOutput;
+  return [output, copilotOutput];
 }
 
 function readFileIfExists(filePath) {
   try {
     if (fs.existsSync(filePath)) {
-      return fs.readFileSync(filePath, 'utf-8')
+      return fs.readFileSync(filePath, "utf-8");
     }
   } catch (e) {
-    console.warn(`无法读取文件 ${filePath}:`, e.message)
+    console.warn(`无法读取文件 ${filePath}:`, e.message);
   }
-  return null
+  return null;
 }
 
 function mergeAgents(config) {
   const {
-    output = getDefaultConfig().output,
     baseRulesPath = getDefaultConfig().baseRulesPath,
     privateRulesPath = getDefaultConfig().privateRulesPath,
-  } = config
+  } = config;
+  const outputs = resolveOutputPaths(config);
 
-  console.log('📦 开始合并规则文件...')
-  console.log(`   基础规则: ${baseRulesPath}`)
-  console.log(`   私有规则: ${privateRulesPath}`)
-  console.log(`   输出文件: ${output}`)
+  console.log("📦 开始合并规则文件...");
+  console.log(`   基础规则: ${baseRulesPath}`);
+  console.log(`   私有规则: ${privateRulesPath}`);
+  console.log(`   输出文件: ${outputs.join(", ")}`);
 
-  const baseRules = readFileIfExists(baseRulesPath)
+  const baseRules = readFileIfExists(baseRulesPath);
   if (!baseRules) {
-    console.error(`❌ 基础规则文件不存在: ${baseRulesPath}`)
-    process.exit(1)
+    console.error(`❌ 基础规则文件不存在: ${baseRulesPath}`);
+    process.exit(1);
   }
 
-  const privateRules = readFileIfExists(privateRulesPath)
+  const privateRules = readFileIfExists(privateRulesPath);
 
-  let merged = baseRules
+  let merged = baseRules;
 
   if (privateRules) {
-    merged += '\n\n---\n\n'
-    merged += '# 项目私有规则\n\n'
-    merged += '以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n'
-    merged += privateRules
+    merged += "\n\n---\n\n";
+    merged += "# 项目私有规则\n\n";
+    merged += "以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n";
+    merged += privateRules;
   }
 
-  try {
-    fs.writeFileSync(output, merged, 'utf-8')
-    console.log(`✅ 规则已合并到 ${output}`)
-  } catch (e) {
-    console.error(`❌ 写入文件失败 ${output}:`, e.message)
-    process.exit(1)
+  for (const outputPath of outputs) {
+    try {
+      ensureParentDir(outputPath);
+      fs.writeFileSync(outputPath, merged, "utf-8");
+      console.log(`✅ 规则已合并到 ${outputPath}`);
+    } catch (e) {
+      console.error(`❌ 写入文件失败 ${outputPath}:`, e.message);
+      process.exit(1);
+    }
   }
 }
 
 function initAgents() {
-  const privateTemplatePath = path.join(packageRoot, 'AGENTS.private.example.md')
-  const privateOutputPath = path.join(currentRoot, 'AGENTS.private.md')
+  const privateTemplatePath = path.join(
+    packageRoot,
+    "AGENTS.private.example.md",
+  );
+  const privateOutputPath = path.join(currentRoot, "AGENTS.private.md");
 
-  mergeAgents(getDefaultConfig())
+  mergeAgents(getDefaultConfig());
 
   if (!fs.existsSync(privateOutputPath) && fs.existsSync(privateTemplatePath)) {
-    fs.copyFileSync(privateTemplatePath, privateOutputPath)
-    console.log(`✅ 已创建私有规则模板 ${privateOutputPath}`)
+    fs.copyFileSync(privateTemplatePath, privateOutputPath);
+    console.log(`✅ 已创建私有规则模板 ${privateOutputPath}`);
   }
 
-  console.log('✅ 初始化完成，后续执行 agent-rules sync 即可刷新 AGENTS.md')
+  console.log(
+    "✅ 初始化完成，后续执行 agent-rules sync 即可刷新 AGENTS.md 和 .github/copilot-instructions.md",
+  );
 }
 
 function runSync(triggerSource) {
   if (isSyncing) {
-    pendingSync = true
-    return
+    pendingSync = true;
+    return;
   }
 
-  isSyncing = true
-  console.log(`[agent-rules:watch] ${triggerSource} -> 执行同步`)
+  isSyncing = true;
+  console.log(`[agent-rules:watch] ${triggerSource} -> 执行同步`);
 
-  mergeAgents(getDefaultConfig())
+  mergeAgents(getDefaultConfig());
 
-  isSyncing = false
+  isSyncing = false;
 
   if (pendingSync) {
-    pendingSync = false
-    runSync('检测到等待中的改动')
+    pendingSync = false;
+    runSync("检测到等待中的改动");
   }
 }
 
 function scheduleSync(triggerSource) {
   if (syncTimer) {
-    clearTimeout(syncTimer)
+    clearTimeout(syncTimer);
   }
 
   syncTimer = setTimeout(() => {
-    syncTimer = null
-    runSync(triggerSource)
-  }, 300)
+    syncTimer = null;
+    runSync(triggerSource);
+  }, 300);
 }
 
 function watchAgents() {
-  const privateRulesName = 'AGENTS.private.md'
-  const privateRulesPath = path.join(currentRoot, privateRulesName)
-  const privateTemplatePath = path.join(packageRoot, 'AGENTS.private.example.md')
+  const privateRulesName = "AGENTS.private.md";
+  const privateRulesPath = path.join(currentRoot, privateRulesName);
+  const privateTemplatePath = path.join(
+    packageRoot,
+    "AGENTS.private.example.md",
+  );
 
   // 不存在则从模板创建
   if (!fs.existsSync(privateRulesPath) && fs.existsSync(privateTemplatePath)) {
-    fs.copyFileSync(privateTemplatePath, privateRulesPath)
-    console.log(`[agent-rules:watch] 已创建 ${privateRulesPath}，请按项目情况修改`)
+    fs.copyFileSync(privateTemplatePath, privateRulesPath);
+    console.log(
+      `[agent-rules:watch] 已创建 ${privateRulesPath}，请按项目情况修改`,
+    );
   }
 
-  runSync('启动监听')
+  runSync("启动监听");
 
   fs.watch(currentRoot, (eventType, fileName) => {
-    const normalizedFileName = typeof fileName === 'string' ? fileName : ''
+    const normalizedFileName = typeof fileName === "string" ? fileName : "";
     if (normalizedFileName !== privateRulesName) {
-      return
+      return;
     }
 
-    scheduleSync(`${privateRulesName} 已变更`)
-  })
+    scheduleSync(`${privateRulesName} 已变更`);
+  });
 
-  console.log(`[agent-rules:watch] 正在监听 ${privateRulesPath}`)
+  console.log(`[agent-rules:watch] 正在监听 ${privateRulesPath}`);
 
-  process.on('SIGINT', () => {
-    process.exit(0)
-  })
+  process.on("SIGINT", () => {
+    process.exit(0);
+  });
 
-  process.on('SIGTERM', () => {
-    process.exit(0)
-  })
+  process.on("SIGTERM", () => {
+    process.exit(0);
+  });
 }
 
 function main() {
-  const command = process.argv[2]
-
-  if (command === '--help' || command === '-h' || command === 'help') {
-    console.log('agent-rules 使用说明:')
-    console.log('  agent-rules        初始化 AGENTS.md，并在缺失时创建 AGENTS.private.md 模板')
-    console.log('  agent-rules init   初始化 AGENTS.md，并在缺失时创建 AGENTS.private.md 模板')
-    console.log('  agent-rules sync   重新生成项目根目录下的 AGENTS.md')
-    console.log('  agent-rules watch  监听 AGENTS.private.md，变更后自动同步 AGENTS.md')
-    console.log('  agent-rules help   查看帮助')
-    return
+  const command = process.argv[2];
+
+  if (command === "--help" || command === "-h" || command === "help") {
+    console.log("agent-rules 使用说明:");
+    console.log(
+      "  agent-rules        初始化 AGENTS.md 与 .github/copilot-instructions.md，并在缺失时创建 AGENTS.private.md 模板",
+    );
+    console.log(
+      "  agent-rules init   初始化 AGENTS.md 与 .github/copilot-instructions.md，并在缺失时创建 AGENTS.private.md 模板",
+    );
+    console.log(
+      "  agent-rules sync   重新生成项目根目录下的 AGENTS.md 与 .github/copilot-instructions.md",
+    );
+    console.log(
+      "  agent-rules watch  监听 AGENTS.private.md，变更后自动同步规则文件",
+    );
+    console.log("  agent-rules help   查看帮助");
+    return;
   }
 
-  if (!command || command === 'init') {
-    initAgents()
-    return
+  if (!command || command === "init") {
+    initAgents();
+    return;
   }
 
-  if (command === 'sync') {
-    mergeAgents(getDefaultConfig())
-    return
+  if (command === "sync") {
+    mergeAgents(getDefaultConfig());
+    return;
   }
 
-  if (command === 'watch') {
-    watchAgents()
-    return
+  if (command === "watch") {
+    watchAgents();
+    return;
   }
 
-  const configPath = command
+  const configPath = command;
 
-  let config = {}
+  let config = {};
 
   if (fs.existsSync(configPath)) {
     try {
-      const configContent = fs.readFileSync(configPath, 'utf-8')
-      config = JSON.parse(configContent)
-      console.log(`📄 已加载配置文件: ${configPath}`)
+      const configContent = fs.readFileSync(configPath, "utf-8");
+      config = JSON.parse(configContent);
+      console.log(`📄 已加载配置文件: ${configPath}`);
     } catch (e) {
-      console.error(`❌ 配置文件解析失败 ${configPath}:`, e.message)
-      process.exit(1)
+      console.error(`❌ 配置文件解析失败 ${configPath}:`, e.message);
+      process.exit(1);
     }
   } else {
-    console.log(`⚠️  配置文件不存在 ${configPath}，使用默认配置`)
+    console.log(`⚠️  配置文件不存在 ${configPath}，使用默认配置`);
   }
 
-  mergeAgents(config)
+  mergeAgents(config);
 }
 
 if (require.main === module) {
-  main()
+  main();
 }
 
-module.exports = { mergeAgents, readFileIfExists, initAgents, getDefaultConfig, watchAgents }
+module.exports = {
+  mergeAgents,
+  readFileIfExists,
+  initAgents,
+  getDefaultConfig,
+  watchAgents,
+  resolveOutputPaths,
+};

package/package.json

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