@routerhub/agent-rules 1.0.6

package/AGENTS.base.md

@@ -0,0 +1,61 @@
+# Copilot Agent Rules - Base
+
+以下规则适用于所有使用此规则包的项目。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
+
+## 语言与回答
+
+- 始终使用中文回答。
+
+## 文件与目录约束
+
+- 不能随意修改核心业务文件和 API 相关代码。
+- 不要编写或修改 `README.md`（由项目维护）。
+- 先用`typings.d.ts` 中的类型定义，如果没有再自定义 TypeScript类型
+
+## 样式与 UI 约束
+
+- 新增或修改样式时，统一使用 `*.module.scss`，不要在业务页面新增普通 `.css` 样式。
+- `scss` 中的类名统一使用小驼峰命名（如 `topupButton`），不使用下划线或中划线。
+- 不允许使用 `span` 标签选择器。
+- 如果必须存在类名（历史代码场景），类名使用小驼峰命名，不使用下划线或中划线。
+
+## 命名与类型约束
+
+- 参数名、变量名应与 `typings.d.ts` 中字段命名保持一致。
+- 命名使用小驼峰或大驼峰，不使用下划线命名。
+- 变量或值命名时，至少使用两个单词。
+- TS 中不允许使用 `as`，不允许使用 `any`。
+- 组件 `props` 能复用类型时，必须优先复用，不要重复定义。
+
+## 常量与业务规则
+
+- 禁止硬编码数字判断；统一使用常量或枚举，并定义在 `Const.ts` 或 `constants.ts`。
+- `tab` 索引统一使用常量。
+- 时间相关处理统一使用 `dayjs`。
+- 数据回显优先使用对象展开运算符（`...`）。
+
+## 代码风格与结构
+
+- 不允许写 `class`，统一使用函数式编程。
+- 不要写 `try/catch`。
+- 当同一个组件被复用时，传入 `fromType`（值为当前页面名）用于区分来源；组件内部差异逻辑基于 `fromType` 分支。
+
+## 组件复用规则
+
+- **优先复用项目中已存在的组件**，写新功能时尽量不要创建新组件。
+- 检查现有组件库中是否有可复用的基础组件（如表格、卡片、按钮、容器等）。
+- 能通过 `props` 定制的场景，不要创建新组件；优先改进现有组件的 `props` 接口。
+- 任何公共使用频率高的组件应统一维护，避免样式和逻辑分散。
+
+## 自动化测试规则
+
+- 自动化测试默认必须使用真实接口数据，禁止使用 mock/route.fulfill/本地伪造返回；仅在明确同意的情况下才允许使用模拟数据。
+- 编写自动化测试时，关键步骤之间需间隔 2 秒后再执行下一步，以保证操作过程可观察。
+- 自动化测试执行完毕后，自动打开 UI 界面，允许开发者进行手动验证。
+
+## 优先级声明
+
+- 若规则之间有冲突，按以下优先级执行：
+  1. 项目私有规则（AGENTS.private.md）
+  2. 基础规则（此文件）
+  3. 隐含约定

package/AGENTS.private.example.md

@@ -0,0 +1,51 @@
+# 项目私有规则模板
+
+以下是项目特定规则的示例。请根据实际项目情况修改。
+
+## 文件与目录约束
+
+- 不能修改 `src/apis/api` 下的任何内容
+- 不能修改 `src/core` 下的核心模块
+
+## 项目特定的连接配置
+
+- 测试环境 API：https://test-api.example.com
+- 生产环境 API：https://api.example.com
+- 内部工具地址：https://internal-tools.example.com
+
+## 组件库路径
+
+- UI 组件：`src/components/ui/`
+- 业务组件：`src/components/business/`
+- 表格组件使用：`TableBase` 或 `TablePricing`
+- 卡片组件使用：`CardBase`
+
+## 接口与数据
+
+- API 响应统一通过 `src/types/api.ts` 定义
+- 数据转换统一通过 `src/utils/transform.ts` 完成
+- 所有业务数据应经过验证，不信任 API 返回
+
+## 业务流程规范
+
+- 支付流程必须经过风控检查
+- 用户认证使用统一的 `AuthContext`
+- 权限控制通过 `usePermission` hook 实现
+
+## 禁止使用
+
+- 不允许直接操作 DOM（使用 React ref）
+- 不允许使用 localStorage 存储敏感信息
+- 不允许直接 fetch，必须通过 `apiClient` 工具
+
+## 测试要求
+
+- 所有业务逻辑必须有单元测试
+- 页面级别测试必须包括主流程和错误流程
+- 不允许使用真实账户进行自动化测试
+
+## 代码审批要求
+
+- PR 必须通过 ESLint 检查
+- PR 必须通过单元测试
+- PR 必须至少有 1 名代码审批者同意

package/README.md

@@ -0,0 +1,37 @@
+# @routerhub/agent-rules
+
+只做两件事：
+
+1. 生成项目可用的 `AGENTS.md`
+2. 自动监听 `AGENTS.private.md` 并同步
+
+## 安装
+
+在你的项目里安装：
+
+```bash
+pnpm add -D concurrently https://github.com/routerhub/agentRules.git#v1.0.6
+```
+
+## 使用
+
+修改项目package.json中的scripts中的启动命令，改成类似下面这种，
+
+```json
+{
+  "scripts": {
+    "dev": "concurrently \"next dev\" \"agent-rules watch\""
+  }
+}
+```
+
+作用：
+- 监听 `AGENTS.private.md` 变更
+- 变更后自动重新同步 `AGENTS.md`
+
+
+## 如何打tag
+```
+git tag v1.0.5
+git push --tags
+```

package/merge.js

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+
+/**
+ * 合并规则脚本
+ *
+ * 使用方式：
+ *   node merge.js [command]
+ *
+ * command:
+ *   init  初始化 AGENTS.md，并在缺失时创建 AGENTS.private.md 模板
+ *   sync  重新生成项目根目录下的 AGENTS.md
+ *   watch 监听 AGENTS.private.md 变化并自动同步
+ */
+
+const fs = require('fs')
+const path = require('path')
+
+const packageRoot = __dirname
+const currentRoot = process.cwd()
+
+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'),
+  }
+}
+
+function readFileIfExists(filePath) {
+  try {
+    if (fs.existsSync(filePath)) {
+      return fs.readFileSync(filePath, 'utf-8')
+    }
+  } catch (e) {
+    console.warn(`无法读取文件 ${filePath}:`, e.message)
+  }
+  return null
+}
+
+function mergeAgents(config) {
+  const {
+    output = getDefaultConfig().output,
+    baseRulesPath = getDefaultConfig().baseRulesPath,
+    privateRulesPath = getDefaultConfig().privateRulesPath,
+  } = config
+
+  console.log('📦 开始合并规则文件...')
+  console.log(`   基础规则: ${baseRulesPath}`)
+  console.log(`   私有规则: ${privateRulesPath}`)
+  console.log(`   输出文件: ${output}`)
+
+  const baseRules = readFileIfExists(baseRulesPath)
+  if (!baseRules) {
+    console.error(`❌ 基础规则文件不存在: ${baseRulesPath}`)
+    process.exit(1)
+  }
+
+  const privateRules = readFileIfExists(privateRulesPath)
+
+  let merged = baseRules
+
+  if (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)
+  }
+}
+
+function initAgents() {
+  const privateTemplatePath = path.join(packageRoot, 'AGENTS.private.example.md')
+  const privateOutputPath = path.join(currentRoot, 'AGENTS.private.md')
+
+  mergeAgents(getDefaultConfig())
+
+  if (!fs.existsSync(privateOutputPath) && fs.existsSync(privateTemplatePath)) {
+    fs.copyFileSync(privateTemplatePath, privateOutputPath)
+    console.log(`✅ 已创建私有规则模板 ${privateOutputPath}`)
+  }
+
+  console.log('✅ 初始化完成，后续执行 agent-rules sync 即可刷新 AGENTS.md')
+}
+
+function runSync(triggerSource) {
+  if (isSyncing) {
+    pendingSync = true
+    return
+  }
+
+  isSyncing = true
+  console.log(`[agent-rules:watch] ${triggerSource} -> 执行同步`)
+
+  mergeAgents(getDefaultConfig())
+
+  isSyncing = false
+
+  if (pendingSync) {
+    pendingSync = false
+    runSync('检测到等待中的改动')
+  }
+}
+
+function scheduleSync(triggerSource) {
+  if (syncTimer) {
+    clearTimeout(syncTimer)
+  }
+
+  syncTimer = setTimeout(() => {
+    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')
+
+  // 不存在则从模板创建
+  if (!fs.existsSync(privateRulesPath) && fs.existsSync(privateTemplatePath)) {
+    fs.copyFileSync(privateTemplatePath, privateRulesPath)
+    console.log(`[agent-rules:watch] 已创建 ${privateRulesPath}，请按项目情况修改`)
+  }
+
+  runSync('启动监听')
+
+  fs.watch(currentRoot, (eventType, fileName) => {
+    const normalizedFileName = typeof fileName === 'string' ? fileName : ''
+    if (normalizedFileName !== privateRulesName) {
+      return
+    }
+
+    scheduleSync(`${privateRulesName} 已变更`)
+  })
+
+  console.log(`[agent-rules:watch] 正在监听 ${privateRulesPath}`)
+
+  process.on('SIGINT', () => {
+    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
+  }
+
+  if (!command || command === 'init') {
+    initAgents()
+    return
+  }
+
+  if (command === 'sync') {
+    mergeAgents(getDefaultConfig())
+    return
+  }
+
+  if (command === 'watch') {
+    watchAgents()
+    return
+  }
+
+  const configPath = command
+
+  let config = {}
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const configContent = fs.readFileSync(configPath, 'utf-8')
+      config = JSON.parse(configContent)
+      console.log(`📄 已加载配置文件: ${configPath}`)
+    } catch (e) {
+      console.error(`❌ 配置文件解析失败 ${configPath}:`, e.message)
+      process.exit(1)
+    }
+  } else {
+    console.log(`⚠️  配置文件不存在 ${configPath}，使用默认配置`)
+  }
+
+  mergeAgents(config)
+}
+
+if (require.main === module) {
+  main()
+}
+
+module.exports = { mergeAgents, readFileIfExists, initAgents, getDefaultConfig, watchAgents }

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@routerhub/agent-rules",
+  "version": "1.0.6",
+  "description": "Shared Copilot agent rules and guidelines for RouterHub projects",
+  "main": "AGENTS.base.md",
+  "bin": {
+    "agent-rules": "merge.js"
+  },
+  "files": [
+    "AGENTS.base.md",
+    "merge.js",
+    "AGENTS.private.example.md",
+    "postinstall.js",
+    "package.json"
+  ],
+  "scripts": {
+    "merge": "node merge.js",
+    "sync": "node merge.js sync",
+    "init": "node merge.js init",
+    "watch": "node merge.js watch",
+    "postinstall": "node postinstall.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/routerhub/agent-rules"
+  },
+  "keywords": [
+    "copilot",
+    "agent",
+    "rules",
+    "guidelines"
+  ],
+  "author": "RouterHub Team",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/postinstall.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+console.log('')
+console.log('[agent-rules] 安装完成')
+console.log('[agent-rules] 下一步执行: npx agent-rules')
+console.log('[agent-rules] 或显式初始化: npx agent-rules init')
+console.log('[agent-rules] 以后同步规则: npx agent-rules sync')
+console.log('[agent-rules] 查看帮助: npx agent-rules help')
+console.log('')