@routerhub/agent-rules 1.5.0 → 1.5.2

package/AGENTS.base.md

@@ -7,6 +7,26 @@
 - 始终使用中文回答，代码注释使用中文，每行代码配中文注释。
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
 
+## Git 规范
+
+- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
+- commit 信息必须中文，禁止 `git push --force`。
+
+## 安全
+
+- 未明确授权不操作生产环境（指令需含"生产"/"线上"/"prod"/"production"），操作前二次确认。
+
+## 需求文档
+
+- 新需求先在 `docs/` 写 MD 文档，含：目标、范围、功能要求、验收标准。
+
+## 优先级
+
+1. 项目私有规则（AGENTS.private.md）
+2. 基础规则（此文件）
+
+<!-- @domain: frontend -->
+
 ## 文件约束
 
 - 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。
@@ -43,36 +63,11 @@
 - API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径。
 - 接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
 
-## Go 语言规则
-
-- 优先值传递与局部变量生命周期控制，避免内存逃逸；无必要不返回局部变量指针。
-- 所有删除操作必须使用软删除机制；`DeletedAt` 字段类型必须用 `gorm.DeletedAt`，禁止用 `*time.Time`（后者不实现 `DeleteClausesInterface`，会导致硬删除）。
-
-## GORM Model 规范
-
-- `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
-- 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
-
-## Git 规范
-
-- 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- commit 信息必须中文，禁止 `git push --force`。
-
-## 安全
-
-- 未明确授权不操作生产环境（指令需含"生产"/"线上"/"prod"/"production"），操作前二次确认。
-
 ## 依赖与构建
 
 - 依赖安装统一 `pnpm`，禁止 `npm install`/`yarn install`。
 - 写完代码先 `npm run format`，再 `npm run build`，构建通过才可发版。
 
-## Docker 与部署
-
-- 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
-- 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
-- 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。
-
 ## 测试
 
 - 测试描述、断言使用中文，覆盖中文场景；充值类测试默认用充值 1 的数据。
@@ -85,11 +80,23 @@
 - 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
 - 提交前移除调试日志和临时代码。
 
-## 需求文档
+<!-- @domain: go-backend -->
 
-- 新需求先在 `docs/` 写 MD 文档，含：目标、范围、功能要求、验收标准。
+## Go 语言规则
 
-## 优先级
+- 优先值传递与局部变量生命周期控制，避免内存逃逸；无必要不返回局部变量指针。
+- 所有删除操作必须使用软删除机制；`DeletedAt` 字段类型必须用 `gorm.DeletedAt`，禁止用 `*time.Time`（后者不实现 `DeleteClausesInterface`，会导致硬删除）。
 
-1. 项目私有规则（AGENTS.private.md）
-2. 基础规则（此文件）
+## GORM Model 规范
+
+- `DeletedAt` 字段必须使用 `gorm.DeletedAt` 类型，严禁使用 `*time.Time`。`*time.Time` 不会触发 GORM v2 的软删除机制，会导致 `Delete()` 执行物理删除（DELETE FROM）而非软删除（UPDATE SET deleted_at）。
+- 新建 Model 时，优先嵌入已有的公共基础结构体（如包含 ID、CreatedAt、UpdatedAt、DeletedAt 的 BaseModel），避免各 Model 独立定义这些字段导致类型不一致。
+
+<!-- @domain: devops -->
+
+## Docker 与部署
+
+- 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
+- 部署时打镜像 tag 必须对项目内所有服务/镜像统一打 tag，无论该镜像是否有代码改动；确保所有镜像版本号一致后再发版。
+- 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
+- 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。

package/AGENTS.private.example.md

@@ -1,52 +1,33 @@
-# 项目私有规则模板
+# 项目私有规则
 
-以下是项目特定规则的示例。请根据实际项目情况修改。
+<!-- 说明：未标记域的内容归入全局规则，标记后的内容自动合并到对应域 -->
 
-## 文件与目录约束
+## 全局规则
 
-- 不能修改 `src/apis/api` 下的任何内容
-- 不能修改 `src/core` 下的核心模块
+<!-- 在此添加全局规则，例如：-->
+<!-- - 测试环境 API：https://test-api.example.com -->
+<!-- - PR 必须至少有 1 名审批者同意 -->
 
-## 项目特定的连接配置
+<!-- @domain: frontend -->
 
-- 测试环境 API：https://test-api.example.com
-- 生产环境 API：https://api.example.com
-- 内部工具地址：https://internal-tools.example.com
+## 前端规则
 
-## 组件库路径
+<!-- 在此添加前端规则，例如：-->
+<!-- - 不能修改 `src/apis/api` 下的任何内容 -->
+<!-- - UI 组件：`src/components/ui/` -->
 
-- UI 组件：`src/components/ui/`
-- 业务组件：`src/components/business/`
-- 表格组件使用：`TableBase` 或 `TablePricing`
-- 卡片组件使用：`CardBase`
+<!-- @domain: go-backend -->
 
-## 接口与数据
+## Go 后端规则
 
-- API 响应统一通过 `src/types/api.ts` 定义
-- 数据转换统一通过 `src/utils/transform.ts` 完成
-- 所有业务数据应经过验证，不信任 API 返回
+<!-- 在此添加 Go 后端规则，例如：-->
+<!-- - 配置文件路径：`config/` -->
+<!-- - 接口返回统一使用 `response.Success()` / `response.Error()` -->
 
-## 业务流程规范
+<!-- @domain: devops -->
 
-- 支付流程必须经过风控检查
-- 用户认证使用统一的 `AuthContext`
-- 权限控制通过 `usePermission` hook 实现
+## 部署规则
 
-## 禁止使用
-
-- 不允许直接操作 DOM（使用 React ref）
-- 不允许使用 localStorage 存储敏感信息
-- 不允许直接 fetch，必须通过 `apiClient` 工具
-
-## 测试要求
-
-- 所有业务逻辑必须有单元测试
-- 页面级别测试必须包括主流程和错误流程
-- 不允许使用真实账户进行自动化测试
-
-## 代码审批要求
-
-- PR 必须通过 ESLint 检查
-- PR 必须通过单元测试
-- PR 必须至少有 1 名代码审批者同意
-<!-- 测试 -->
+<!-- 在此添加部署规则，例如：-->
+<!-- - 镜像仓库：ghcr.io/your-org/your-project -->
+<!-- - Portainer 地址配置在 `.env` 文件中 -->

package/merge.js

@@ -152,6 +152,101 @@ function loadRules(rulesDir) {
  * 支持格式: <!-- @domain: go-backend -->
  * 未标记的内容归入全局
  */
+
+// 域元数据配置：域名 → { name, applyTo, outputName, fileName }
+const DOMAIN_META = {
+  frontend: {
+    name: "前端规则",
+    applyTo: [
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.js",
+      "**/*.jsx",
+      "**/*.vue",
+      "**/*.css",
+      "**/*.scss",
+    ],
+    outputName: "frontend",
+    fileName: "frontend.md",
+  },
+  "go-backend": {
+    name: "Go 后端规则",
+    applyTo: ["**/*.go"],
+    outputName: "go-backend",
+    fileName: "go-backend.md",
+  },
+  devops: {
+    name: "DevOps 部署规则",
+    applyTo: [
+      "**/Dockerfile",
+      "**/Dockerfile.*",
+      "**/docker-compose*.yml",
+      "**/docker-compose*.yaml",
+      "**/*.sh",
+      "**/.gitlab-ci.yml",
+      "**/.github/workflows/*.yml",
+      "**/.github/workflows/*.yaml",
+    ],
+    outputName: "devops",
+    fileName: "devops.md",
+  },
+};
+
+/**
+ * 从 AGENTS.base.md 解析域标记，自动拆分生成 rules/*.md
+ * 未标记的内容生成 rules/global.md，各域内容带 frontmatter 生成对应文件
+ */
+function generateRulesFromBase(baseRulesPath, rulesDir) {
+  const baseContent = readFileIfExists(baseRulesPath);
+  if (!baseContent) {
+    console.warn(`⚠️  基础规则文件不存在: ${baseRulesPath}，跳过 rules 生成`);
+    return false;
+  }
+
+  console.log("📝 从 AGENTS.base.md 生成 rules/*.md ...");
+
+  // 复用 parsePrivateDomains 解析域标记
+  const parsed = parsePrivateDomains(baseContent);
+
+  // 去掉标题行（# Copilot Agent Rules - Base 及说明文字）
+  let globalText = parsed.global;
+  const headerRegex =
+    /^#\s+Copilot Agent Rules\s*-?\s*Base\s*\n+(?:以下为.*?\n+)?/;
+  globalText = globalText.replace(headerRegex, "").trim();
+
+  // 生成 rules/global.md
+  fs.mkdirSync(rulesDir, { recursive: true });
+
+  const globalFrontmatter = '---\nname: "通用规则"\n---\n\n';
+  const globalPath = path.join(rulesDir, "global.md");
+  fs.writeFileSync(globalPath, globalFrontmatter + globalText + "\n", "utf-8");
+  console.log(`   ✅ rules/global.md`);
+
+  // 生成各域的 rules/*.md
+  for (const [domainKey, meta] of Object.entries(DOMAIN_META)) {
+    const domainText = parsed.domains[domainKey];
+    if (!domainText) {
+      continue;
+    }
+
+    const frontmatter = [
+      "---",
+      `name: "${meta.name}"`,
+      `applyTo: ${JSON.stringify(meta.applyTo)}`,
+      `outputName: "${meta.outputName}"`,
+      "---",
+      "",
+      "",
+    ].join("\n");
+
+    const filePath = path.join(rulesDir, meta.fileName);
+    fs.writeFileSync(filePath, frontmatter + domainText.trim() + "\n", "utf-8");
+    console.log(`   ✅ rules/${meta.fileName}`);
+  }
+
+  return true;
+}
+
 function parsePrivateDomains(privateContent) {
   if (!privateContent) {
     return { global: "", domains: {} };
@@ -247,9 +342,13 @@ function mergeAgents(config) {
   const copilotOutput = config.copilotOutput || defaultConfig.copilotOutput;
 
   console.log("📦 开始合并规则文件...");
+  console.log(`   基础规则: ${baseRulesPath}`);
   console.log(`   规则目录: ${rulesDir}`);
   console.log(`   私有规则: ${privateRulesPath}`);
 
+  // 0. 从 AGENTS.base.md 自动拆分生成 rules/*.md
+  generateRulesFromBase(baseRulesPath, rulesDir);
+
   // 1. 加载 rules/ 目录的规则文件
   const { globalRules, domainRules } = loadRules(rulesDir);
 
@@ -388,6 +487,7 @@ function scheduleSync(triggerSource) {
 
 function watchAgents() {
   const privateRulesName = "AGENTS.private.md";
+  const baseRulesName = "AGENTS.base.md";
   const privateRulesPath = path.join(currentRoot, privateRulesName);
   const privateTemplatePath = path.join(
     packageRoot,
@@ -404,6 +504,7 @@ function watchAgents() {
 
   runSync("启动监听");
 
+  // 监听项目目录下的 AGENTS.private.md
   fs.watch(currentRoot, (eventType, fileName) => {
     const normalizedFileName = typeof fileName === "string" ? fileName : "";
     if (normalizedFileName !== privateRulesName) {
@@ -413,7 +514,20 @@ function watchAgents() {
     scheduleSync(`${privateRulesName} 已变更`);
   });
 
+  // 监听包目录下的 AGENTS.base.md
+  fs.watch(packageRoot, (eventType, fileName) => {
+    const normalizedFileName = typeof fileName === "string" ? fileName : "";
+    if (normalizedFileName !== baseRulesName) {
+      return;
+    }
+
+    scheduleSync(`${baseRulesName} 已变更`);
+  });
+
   console.log(`[agent-rules:watch] 正在监听 ${privateRulesPath}`);
+  console.log(
+    `[agent-rules:watch] 正在监听 ${path.join(packageRoot, baseRulesName)}`,
+  );
 
   process.on("SIGINT", () => {
     process.exit(0);

package/package.json

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

package/rules/devops.md

@@ -1,21 +1,12 @@
 ---
 name: "DevOps 部署规则"
-applyTo:
-  [
-    "**/Dockerfile",
-    "**/Dockerfile.*",
-    "**/docker-compose*.yml",
-    "**/docker-compose*.yaml",
-    "**/*.sh",
-    "**/.gitlab-ci.yml",
-    "**/.github/workflows/*.yml",
-    "**/.github/workflows/*.yaml",
-  ]
+applyTo: ["**/Dockerfile","**/Dockerfile.*","**/docker-compose*.yml","**/docker-compose*.yaml","**/*.sh","**/.gitlab-ci.yml","**/.github/workflows/*.yml","**/.github/workflows/*.yaml"]
 outputName: "devops"
 ---
 
 ## Docker 与部署
 
 - 默认本地 `docker build`，构建后 `docker push` 到 `ghcr.io`，推送前确保正确 tag。
+- 部署时打镜像 tag 必须对项目内所有服务/镜像统一打 tag，无论该镜像是否有代码改动；确保所有镜像版本号一致后再发版。
 - 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
 - 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。

package/rules/frontend.md

@@ -1,15 +1,6 @@
 ---
 name: "前端规则"
-applyTo:
-  [
-    "**/*.ts",
-    "**/*.tsx",
-    "**/*.js",
-    "**/*.jsx",
-    "**/*.vue",
-    "**/*.css",
-    "**/*.scss",
-  ]
+applyTo: ["**/*.ts","**/*.tsx","**/*.js","**/*.jsx","**/*.vue","**/*.css","**/*.scss"]
 outputName: "frontend"
 ---