@routerhub/agent-rules 1.4.15 → 1.5.0

package/AGENTS.base.md

@@ -48,6 +48,11 @@
 - 优先值传递与局部变量生命周期控制，避免内存逃逸；无必要不返回局部变量指针。
 - 所有删除操作必须使用软删除机制；`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/`），英文小写中划线分隔。

package/CHANGELOG.md

@@ -0,0 +1,173 @@
+# Changelog
+
+所有对 @routerhub/agent-rules 的重大更改都会记录在这个文件中。
+
+## [1.3.12] - 2026-05-02
+
+### Added
+
+- 新增规则：每次开始实现新需求前，必须先在 `docs/` 目录编写需求说明 MD 文档，至少包含需求目标、需求范围、功能要求、验收标准，必要时补充备注。
+
+## [1.0.29] - 2026-04-20
+
+### Added
+
+- 新增规则：相关测试用例执行通过后，才允许运行 npm run test:e2e:ui 打开 UI 自动化测试页面。
+- 新增规则：编写测试用例时，测试描述、断言说明和相关说明文字统一使用中文。
+
+## [1.0.28] - 2026-04-20
+
+### Added
+
+- 新增规则：当用户要求“加测试用例”时，必须主动执行 npm run test:e2e:ui，并说明本次主要测试用例名称或编号。
+
+## [1.0.27] - 2026-04-20
+
+### Changed
+
+- 移除自动化测试规则中“关键步骤之间需间隔 2 秒再执行下一步”的要求。
+
+## [1.0.25] - 2026-04-20
+
+### Added
+
+- 新增规则：错误处理与日志规范，统一使用 console.error 并要求包含上下文信息。
+
+## [1.0.24] - 2026-04-20
+
+### Changed
+
+- 在示例私有规则文件中补充测试注释示例。
+
+## [1.0.23] - 2026-04-20
+
+### Added
+
+- 新增规则：打开 UI 自动化测试后，应明确告知当前业务对应的具体测试用例名称或编号，让开发者清楚当前验证范围。
+
+## [1.0.22] - 2026-04-20
+
+### Added
+
+- 新增规则：写完业务后，必须自动打开 UI 自动化测试页面，执行 `pnpm run test:e2e:ui`，让开发者手动点击验证功能效果。
+
+## [1.0.20] - 2026-04-19
+
+### Added
+
+- UI 自动化测试端口被占用时，需自动切换到未被占用的新端口。
+
+## [1.0.18] - 2026-04-19
+
+### Changed
+
+- 分支管理规范：所有新建分支名称必须使用中文（汉字）或纯中文拼音，禁止英文缩写、数字、拼音与英文混用。
+
+## [1.0.17] - 2026-04-19
+
+### Added
+
+- 新增分支管理规范：所有新建分支名称必须使用中文拼音或汉字，禁止使用无意义英文缩写。
+
+## [1.0.16] - 2026-04-19
+
+### Added
+
+- 新增测试用例规范：所有测试用例必须包含中文断言或校验内容，确保覆盖中文场景。
+
+## [1.0.15] - 2026-04-19
+
+### Changed
+
+- 触发自动更新链路验证发布
+
+## [1.0.14] - 2026-04-19
+
+### Changed
+
+- 自动更新流程改为直接提交到主分支，无需手动合并 PR
+
+## [1.0.13] - 2026-04-19
+
+### Fixed
+
+- 修复自动更新 workflow 权限问题，使用 PAT token 创建 PR
+
+## [1.0.12] - 2026-04-19
+
+### Changed
+
+- 验证自动更新链路
+
+## [1.0.11] - 2026-04-19
+
+### Added
+
+- 新增代码注释规范：注释统一使用中文编写
+
+## [1.0.10] - 2026-04-19
+
+### Added
+
+- 新增中文说明文档 `README.zh-CN.md`，补充安装、初始化、同步和监听的使用说明
+
+### Changed
+
+- README 增加中文说明文档入口
+
+## [1.0.9] - 2026-04-19
+
+### Added
+
+- 新增 UI 自动化测试规则：UI 自动化测试必须请求真实的后端接口，不允许使用本地 mock 数据或截断真实请求
+
+## [1.0.3] - 2026-04-16
+
+### Changed
+
+- 精简 README，只保留安装说明与自动监听 `AGENTS.private.md` 的使用方式
+- 文档默认引导通过 `pnpm dev` 搭配 `agent-rules watch` 使用
+
+## [1.0.2] - 2026-04-16
+
+### Added
+
+- 新增 `agent-rules watch` 命令
+- 支持监听项目根目录下的 `AGENTS.private.md` 变更
+- 监听模式启动时自动执行一次同步，生成最新 `AGENTS.md`
+- 当监听文件尚不存在时，自动监听目录并在文件创建后继续生效
+
+### Changed
+
+- 更新 CLI 帮助文案，补充 `watch` 子命令说明
+
+## [1.0.0] - 2024-01-XX
+
+### Added
+
+- 初始版本发布
+- 基础规则 AGENTS.base.md
+- 合并工具 merge.js
+- GitHub Actions 自动发布流程
+- 项目接入文档和示例
+
+### 说明
+
+此版本包含所有 RouterHub 项目的通用编码规范和最佳实践。
+
+---
+
+## 版本升级指南
+
+### 从 v0.x 升级到 v1.0.0
+
+此版本为首个公开版本，引入了新的规则体系和合并机制。请按照 README.md 中的步骤在各项目中进行集成。
+
+---
+
+## 未来计划
+
+- [ ] 支持更多规则定制选项
+- [ ] 提供 CLI 配置向导
+- [ ] 为不同技术栈（React、Vue、等）提供专用规则
+- [ ] 集成其他 linter 配置（eslint 等）

package/merge.js

@@ -7,9 +7,14 @@
  *   node merge.js [command]
  *
  * command:
- *   init  初始化 AGENTS.md，并在缺失时创建 AGENTS.private.md 模板
- *   sync  重新生成项目根目录下的 AGENTS.md
+ *   init  初始化规则文件，并在缺失时创建 AGENTS.private.md 模板
+ *   sync  重新生成所有规则输出文件
  *   watch 监听 AGENTS.private.md 变化并自动同步
+ *
+ * 输出文件：
+ *   AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
+ *   .github/copilot-instructions.md              全局规则（VS Code Copilot）
+ *   .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
  */
 
 const fs = require("fs");
@@ -26,6 +31,8 @@ function getDefaultConfig() {
   return {
     output: path.join(currentRoot, "AGENTS.md"),
     copilotOutput: path.join(currentRoot, ".github", "copilot-instructions.md"),
+    instructionsDir: path.join(currentRoot, ".github", "instructions"),
+    rulesDir: path.join(packageRoot, "rules"),
     baseRulesPath: path.join(packageRoot, "AGENTS.base.md"),
     privateRulesPath: path.join(currentRoot, "AGENTS.private.md"),
   };
@@ -58,45 +65,274 @@ function readFileIfExists(filePath) {
   return null;
 }
 
+/**
+ * 解析 markdown 文件的 YAML frontmatter
+ * 返回 { meta: { name, applyTo, outputName }, content: "去掉 frontmatter 后的正文" }
+ */
+function parseFrontmatter(rawContent) {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const matched = rawContent.match(frontmatterRegex);
+  if (!matched) {
+    return { meta: {}, content: rawContent };
+  }
+
+  const yamlBlock = matched[1];
+  const content = matched[2];
+  const meta = {};
+
+  // 简易 YAML 解析，支持 name/outputName(字符串) 和 applyTo(数组)
+  for (const line of yamlBlock.split("\n")) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine || trimmedLine.startsWith("#")) {
+      continue;
+    }
+
+    const colonIndex = trimmedLine.indexOf(":");
+    if (colonIndex === -1) {
+      continue;
+    }
+
+    const yamlKey = trimmedLine.slice(0, colonIndex).trim();
+    const yamlValue = trimmedLine.slice(colonIndex + 1).trim();
+
+    if (yamlKey === "applyTo") {
+      // 解析 JSON 数组格式: ["**/*.go"]
+      const arrayMatch = yamlValue.match(/^\[.*\]$/);
+      if (arrayMatch) {
+        meta[yamlKey] = JSON.parse(yamlValue);
+      }
+    } else {
+      // 去掉引号
+      meta[yamlKey] = yamlValue.replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return { meta, content };
+}
+
+/**
+ * 扫描 rules/ 目录，加载并分类所有规则文件
+ * 返回 { globalRules: [], domainRules: [{ meta, content }] }
+ */
+function loadRules(rulesDir) {
+  const globalRules = [];
+  const domainRules = [];
+
+  if (!fs.existsSync(rulesDir)) {
+    console.warn(`⚠️  规则目录不存在: ${rulesDir}`);
+    return { globalRules, domainRules };
+  }
+
+  const ruleFiles = fs
+    .readdirSync(rulesDir)
+    .filter((fileName) => fileName.endsWith(".md"))
+    .sort();
+
+  for (const fileName of ruleFiles) {
+    const filePath = path.join(rulesDir, fileName);
+    const rawContent = fs.readFileSync(filePath, "utf-8");
+    const { meta, content } = parseFrontmatter(rawContent);
+
+    if (meta.applyTo && meta.outputName) {
+      domainRules.push({ meta, content, fileName });
+      console.log(
+        `   📂 域规则: ${fileName} → ${meta.outputName} (${meta.applyTo.join(", ")})`,
+      );
+    } else {
+      globalRules.push({ meta, content, fileName });
+      console.log(`   🌐 全局规则: ${fileName}`);
+    }
+  }
+
+  return { globalRules, domainRules };
+}
+
+/**
+ * 解析 AGENTS.private.md 中的域标记，按域分发私有规则
+ * 支持格式: <!-- @domain: go-backend -->
+ * 未标记的内容归入全局
+ */
+function parsePrivateDomains(privateContent) {
+  if (!privateContent) {
+    return { global: "", domains: {} };
+  }
+
+  const domainMarkerRegex = /<!--\s*@domain:\s*([\w-]+)\s*-->/g;
+  const sections = [];
+  let lastIndex = 0;
+  let currentMatch;
+
+  while ((currentMatch = domainMarkerRegex.exec(privateContent)) !== null) {
+    // 前一段归入上一个域（或全局）
+    if (currentMatch.index > lastIndex) {
+      sections.push({
+        domain:
+          sections.length === 0
+            ? null
+            : sections[sections.length - 1].nextDomain,
+        text: privateContent.slice(lastIndex, currentMatch.index),
+      });
+    }
+    // 记录下一个域名
+    if (sections.length > 0) {
+      sections[sections.length - 1].nextDomain = currentMatch[1];
+    } else {
+      sections.push({ domain: null, text: "", nextDomain: currentMatch[1] });
+    }
+    lastIndex = currentMatch.index + currentMatch[0].length;
+  }
+
+  // 最后一段
+  if (lastIndex < privateContent.length) {
+    const lastDomain =
+      sections.length > 0 ? sections[sections.length - 1].nextDomain : null;
+    sections.push({
+      domain: lastDomain || null,
+      text: privateContent.slice(lastIndex),
+    });
+  }
+
+  const result = { global: "", domains: {} };
+  for (const section of sections) {
+    const trimmedText = section.text.trim();
+    if (!trimmedText) {
+      continue;
+    }
+    if (!section.domain) {
+      result.global += (result.global ? "\n\n" : "") + trimmedText;
+    } else {
+      if (!result.domains[section.domain]) {
+        result.domains[section.domain] = "";
+      }
+      result.domains[section.domain] +=
+        (result.domains[section.domain] ? "\n\n" : "") + trimmedText;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 生成 .github/instructions/*.instructions.md 文件
+ * 带 applyTo frontmatter，供 VS Code Copilot 条件加载
+ */
+function generateInstructionFile(
+  instructionsDir,
+  outputName,
+  applyTo,
+  content,
+) {
+  const outputPath = path.join(
+    instructionsDir,
+    `${outputName}.instructions.md`,
+  );
+  const frontmatter = `---\napplyTo: ${JSON.stringify(applyTo)}\n---\n`;
+  const fileContent = frontmatter + "\n" + content;
+
+  ensureParentDir(outputPath);
+  fs.writeFileSync(outputPath, fileContent, "utf-8");
+  console.log(`✅ 条件规则已生成: ${outputPath}`);
+}
+
 function mergeAgents(config) {
+  const defaultConfig = getDefaultConfig();
   const {
-    baseRulesPath = getDefaultConfig().baseRulesPath,
-    privateRulesPath = getDefaultConfig().privateRulesPath,
+    baseRulesPath = defaultConfig.baseRulesPath,
+    privateRulesPath = defaultConfig.privateRulesPath,
+    rulesDir = defaultConfig.rulesDir,
+    instructionsDir = defaultConfig.instructionsDir,
   } = config;
-  const outputs = resolveOutputPaths(config);
+
+  const agentsOutput = config.output || defaultConfig.output;
+  const copilotOutput = config.copilotOutput || defaultConfig.copilotOutput;
 
   console.log("📦 开始合并规则文件...");
-  console.log(`   基础规则: ${baseRulesPath}`);
+  console.log(`   规则目录: ${rulesDir}`);
   console.log(`   私有规则: ${privateRulesPath}`);
-  console.log(`   输出文件: ${outputs.join(", ")}`);
 
-  const baseRules = readFileIfExists(baseRulesPath);
-  if (!baseRules) {
-    console.error(`❌ 基础规则文件不存在: ${baseRulesPath}`);
-    process.exit(1);
-  }
+  // 1. 加载 rules/ 目录的规则文件
+  const { globalRules, domainRules } = loadRules(rulesDir);
 
-  const privateRules = readFileIfExists(privateRulesPath);
-
-  let merged = baseRules;
+  if (globalRules.length === 0 && domainRules.length === 0) {
+    // 回退：如果 rules/ 目录为空，使用旧版 AGENTS.base.md
+    console.log("   ⚠️  rules/ 目录为空，回退使用 AGENTS.base.md");
+    const baseRules = readFileIfExists(baseRulesPath);
+    if (!baseRules) {
+      console.error(`❌ 基础规则文件不存在: ${baseRulesPath}`);
+      process.exit(1);
+    }
 
-  if (privateRules) {
-    merged += "\n\n---\n\n";
-    merged += "# 项目私有规则\n\n";
-    merged += "以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n";
-    merged += privateRules;
-  }
+    const privateRules = readFileIfExists(privateRulesPath);
+    let merged = baseRules;
+    if (privateRules) {
+      merged +=
+        "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
+        privateRules;
+    }
 
-  for (const outputPath of outputs) {
-    try {
+    for (const outputPath of [agentsOutput, copilotOutput]) {
       ensureParentDir(outputPath);
       fs.writeFileSync(outputPath, merged, "utf-8");
       console.log(`✅ 规则已合并到 ${outputPath}`);
-    } catch (e) {
-      console.error(`❌ 写入文件失败 ${outputPath}:`, e.message);
-      process.exit(1);
     }
+    return;
+  }
+
+  // 2. 读取并解析私有规则的域标记
+  const privateContent = readFileIfExists(privateRulesPath);
+  const privateDomains = parsePrivateDomains(privateContent);
+
+  // 3. 拼接全局规则内容
+  const globalContent = globalRules
+    .map((rule) => rule.content.trim())
+    .join("\n\n");
+
+  // 4. 生成 .github/copilot-instructions.md（全局规则 + 私有全局部分）
+  let copilotContent = "# Copilot Agent Rules\n\n" + globalContent;
+  if (privateDomains.global) {
+    copilotContent += "\n\n---\n\n# 项目私有规则\n\n" + privateDomains.global;
+  }
+  ensureParentDir(copilotOutput);
+  fs.writeFileSync(copilotOutput, copilotContent, "utf-8");
+  console.log(`✅ 全局规则已生成: ${copilotOutput}`);
+
+  // 5. 生成 .github/instructions/*.instructions.md（各域规则）
+  ensureParentDir(path.join(instructionsDir, "_placeholder"));
+  for (const rule of domainRules) {
+    let domainContent = rule.content.trim();
+    // 追加对应域的私有规则
+    const privateDomainContent = privateDomains.domains[rule.meta.outputName];
+    if (privateDomainContent) {
+      domainContent +=
+        "\n\n---\n\n# 项目私有规则（" +
+        rule.meta.name +
+        "）\n\n" +
+        privateDomainContent;
+    }
+    generateInstructionFile(
+      instructionsDir,
+      rule.meta.outputName,
+      rule.meta.applyTo,
+      domainContent,
+    );
   }
+
+  // 6. 生成 AGENTS.md（全量合并，兼容 Cursor/Claude Code）
+  const allRulesContent = [
+    globalContent,
+    ...domainRules.map((rule) => rule.content.trim()),
+  ].join("\n\n");
+  let agentsMerged =
+    "# Copilot Agent Rules - Base\n\n以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。\n\n" +
+    allRulesContent;
+  if (privateContent) {
+    agentsMerged +=
+      "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
+      privateContent;
+  }
+  ensureParentDir(agentsOutput);
+  fs.writeFileSync(agentsOutput, agentsMerged, "utf-8");
+  console.log(`✅ 全量规则已合并到 ${agentsOutput}`);
 }
 
 function initAgents() {
@@ -113,9 +349,11 @@ function initAgents() {
     console.log(`✅ 已创建私有规则模板 ${privateOutputPath}`);
   }
 
-  console.log(
-    "✅ 初始化完成，后续执行 agent-rules sync 即可刷新 AGENTS.md 和 .github/copilot-instructions.md",
-  );
+  console.log("✅ 初始化完成，后续执行 agent-rules sync 即可刷新规则文件");
+  console.log("   输出文件:");
+  console.log("   - AGENTS.md（全量，兼容 Cursor/Claude Code）");
+  console.log("   - .github/copilot-instructions.md（全局规则）");
+  console.log("   - .github/instructions/*.instructions.md（按域条件加载）");
 }
 
 function runSync(triggerSource) {
@@ -192,18 +430,29 @@ function main() {
   if (command === "--help" || command === "-h" || command === "help") {
     console.log("agent-rules 使用说明:");
     console.log(
-      "  agent-rules        初始化 AGENTS.md 与 .github/copilot-instructions.md，并在缺失时创建 AGENTS.private.md 模板",
+      "  agent-rules        初始化规则文件，并在缺失时创建 AGENTS.private.md 模板",
     );
     console.log(
-      "  agent-rules init   初始化 AGENTS.md 与 .github/copilot-instructions.md，并在缺失时创建 AGENTS.private.md 模板",
+      "  agent-rules init   初始化规则文件，并在缺失时创建 AGENTS.private.md 模板",
     );
     console.log(
-      "  agent-rules sync   重新生成项目根目录下的 AGENTS.md 与 .github/copilot-instructions.md",
+      "  agent-rules sync   重新生成所有规则输出文件（AGENTS.md + copilot-instructions.md + instructions/*.instructions.md）",
     );
     console.log(
-      "  agent-rules watch  监听 AGENTS.private.md，变更后自动同步规则文件",
+      "  agent-rules watch  监听 AGENTS.private.md，变更后自动同步所有规则文件",
     );
     console.log("  agent-rules help   查看帮助");
+    console.log("");
+    console.log("输出文件:");
+    console.log(
+      "  AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）",
+    );
+    console.log(
+      "  .github/copilot-instructions.md              全局规则（VS Code Copilot）",
+    );
+    console.log(
+      "  .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）",
+    );
     return;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@routerhub/agent-rules",
-  "version": "1.4.15",
+  "version": "1.5.0",
   "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
   "main": "AGENTS.base.md",
   "bin": {
@@ -13,7 +13,8 @@
     "AGENTS.private.example.md",
     "README.zh-CN.md",
     "postinstall.js",
-    "package.json"
+    "package.json",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "node --check merge.js && node --check postinstall.js",

package/postinstall.js

@@ -36,7 +36,7 @@ initProcess.on("close", (code) => {
 
     console.log("[agent-rules] 后台监听进程已启动");
     console.log(
-      "[agent-rules] AGENTS.private.md 的变更将自动同步到 AGENTS.md 和 .github/copilot-instructions.md",
+      "[agent-rules] AGENTS.private.md 的变更将自动同步到 AGENTS.md、.github/copilot-instructions.md 和 .github/instructions/*.instructions.md",
     );
     console.log("");
     console.log("[agent-rules] 手动命令：");

package/rules/devops.md

@@ -0,0 +1,21 @@
+---
+name: "DevOps 部署规则"
+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。
+- 部署通过 Portainer 管理界面操作，禁止 SSH 手动执行 docker 命令；地址和账号配置在 `AGENTS.private.md` 或环境变量中，禁止硬编码。
+- 始终通过 Portainer API 更新 Stack 环境变量触发重新部署，不要 SSH 手动操作 Portainer 管理的容器。

package/rules/frontend.md

@@ -0,0 +1,67 @@
+---
+name: "前端规则"
+applyTo:
+  [
+    "**/*.ts",
+    "**/*.tsx",
+    "**/*.js",
+    "**/*.jsx",
+    "**/*.vue",
+    "**/*.css",
+    "**/*.scss",
+  ]
+outputName: "frontend"
+---
+
+## 文件约束
+
+- 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。
+- TypeScript 类型优先复用 `typings.d.ts`，不存在时再自定义。
+
+## 命名与类型
+
+- 驼峰命名（小驼峰/大驼峰），禁止下划线；变量至少两个单词。
+- 禁止 `as` 和 `any`；`props` 类型优先复用，不重复定义。
+
+## 代码风格
+
+- 函数式编程，不写 `class`，不写 `try/catch`。
+- 禁止重复实现：复用现有函数/组件/配置，发现重复必须提取封装为公共方法。
+- 同一数据/配置只在一处维护，其余通过引用获取，改一处全局生效。
+- 禁止硬编码数字；常量/枚举定义在 `Const.ts` 或 `constants.ts`，`tab` 索引统一使用常量，时间用 `dayjs`。
+- 遵循 SOLID 原则，避免过度设计；数据回显优先用展开运算符（`...`）。
+- 复用组件通过 `fromType`（值为当前页面名）区分来源，内部差异逻辑基于 `fromType` 分支。
+
+## 样式（Tailwind CSS）
+
+- 统一 Tailwind CSS，禁止新增 `*.module.scss`、`*.module.css`、`.css` 文件（历史文件可保留）。
+- 项目未集成 Tailwind 时，先完成安装配置再开发。
+- 新增样式通过 utility classes 在 JSX/TSX 中编写；不满足时优先 `tailwind.config` extend → `@apply` 封装 → 行内 `style`。
+- 复杂/重复样式提取为 Tailwind 组件类或 React 组件，避免工具类堆砌。
+- 类名小驼峰，禁止 `span` 标签选择器。
+
+## 组件复用
+
+- 优先复用已有组件，能通过 `props` 定制就不建新组件；新功能尽量封装为可复用组件。
+
+## 前端 API 规范
+
+- API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径。
+- 接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
+
+## 依赖与构建
+
+- 依赖安装统一 `pnpm`，禁止 `npm install`/`yarn install`。
+- 写完代码先 `npm run format`，再 `npm run build`，构建通过才可发版。
+
+## 测试
+
+- 测试描述、断言使用中文，覆盖中文场景；充值类测试默认用充值 1 的数据。
+- 默认使用真实接口数据，禁止 mock；仅明确同意时允许模拟数据。
+- 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
+- 端口被占用时自动切换新端口。
+
+## 错误日志
+
+- 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
+- 提交前移除调试日志和临时代码。

package/rules/global.md

@@ -0,0 +1,26 @@
+---
+name: "通用规则"
+---
+
+## 语言与内容
+
+- 始终使用中文回答，代码注释使用中文，每行代码配中文注释。
+- 页面 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. 基础规则（此文件）

package/rules/go-backend.md

@@ -0,0 +1,15 @@
+---
+name: "Go 后端规则"
+applyTo: ["**/*.go"]
+outputName: "go-backend"
+---
+
+## 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 独立定义这些字段导致类型不一致。