@routerhub/agent-rules 1.5.190 → 1.5.191

package/AGENTS.base.md

@@ -14,6 +14,17 @@
     - **Skill**：多步骤操作流程，需按需调用，如部署、发 PR、Figma 还原、TDD 流程。新建 `skills/技能名/SKILL.md`。
     - **判断标准**：「这件事每次写代码都要遵守吗？」→ 是 = 规则，否（只有特定场景才触发）= Skill。
 
+## ⚠️ 规则文件分层与个人级启停（机制说明）
+
+agent-rules 生成的规则文件分两层，行为与归属不同，评审/发版/接入时请勿混淆：
+
+- **个人级：`CLAUDE.md` / `AGENTS.md`（不入库，每机本地生成）**。这两个文件是「本地 AI 自动读取」的规则，agent-rules 只是文件生成器、不是运行时拦截器——文件一旦 git 入库，谁 clone 都带上，无法按人关掉。因此改为不入库（`.gitignore` 忽略），是否生成取决于**本机开发者的 git 身份**（`git config user.name` / `user.email` 任一包含包内 `enabled-users.json` 白名单字符串，忽略大小写）。白名单初始为空数组 = **默认停用**；停用 = 不生成 + 清理本机残留的带签名产物（头部 `# Copilot Agent Rules - Base`）+ 加入 `.gitignore`，只删 agent-rules 生成的、开发者自己的同名文件不动。
+- **团队级：`.github/*`、`.claude/skills/*`、`AGENTS.private.md`（入库，始终生成）**。供 GitHub 云端 PR review、团队共享，不参与个人启停。
+
+成员想启用/停用这套个人规则，只取决于「在不在白名单」，与具体项目无关。想启用的人把 `git config user.name` / `git config user.email` 的输出发给 agent-rules 管理员加入白名单即可。
+
+**发版/评审方注意**：升级 PR 中出现「`git rm --cached` 删除已跟踪的 CLAUDE.md / AGENTS.md + .gitignore 追加忽略」是本机制的存量迁移（个人文件从入库改为本地生成），属正常流程，禁止按「误删文件」报错；个人级文件不再入库，规则评审请以团队级产物 `.github/**` 为准。
+
 ## 语言与内容
 
 - 始终使用中文回答，代码注释使用中文。

package/README.zh-CN.md

@@ -2,9 +2,9 @@
 
 `@routerhub/agent-rules` 用来把通用规则和项目私有规则合并成项目中可直接使用的规则文件。
 
-它主要提供两类能力：
+它提供两类能力：
 
-1. 生成项目可用的 `AGENTS.md` 和 `.github/copilot-instructions.md`
+1. 按「个人级 / 团队级」两层生成项目可用的规则文件（详见下方「规则启停」章节）：`CLAUDE.md` / `AGENTS.md` 按本机 git 身份白名单本地生成、默认停用；`.github/*`、skills 等团队级文件始终生成
 2. 监听 `AGENTS.private.md` 变更并自动同步
 
 ## 安装
@@ -85,6 +85,54 @@ pnpm update @routerhub/agent-rules --latest
 
 > 直接 `pnpm i` 会按 `pnpm-lock.yaml` 中的锁定版本安装，必须加 `--latest` 才能拿到最新版本。
 
+## 规则启停（按人白名单）
+
+生成的规则文件分两层：
+
+| 层级 | 文件 | 是否入库 | 何时生成 |
+|---|---|---|---|
+| 个人级 | `CLAUDE.md` / `AGENTS.md`（本地 AI 自动读取） | **不入库**（`.gitignore` 忽略，随安装本地生成） | **仅当本机 git 身份命中白名单** |
+| 团队级 | `.github/copilot-instructions.md`、`.github/instructions/*`、`.github/PULL_REQUEST_TEMPLATE.md`、`.claude/skills/*`、`AGENTS.private.md` | 随仓库入库分发 | 始终生成，不受个人启停影响 |
+
+**为什么个人级文件要「不入库 + 每机生成」**：Claude Code / Cursor / Copilot 是「工作区里有这个文件就读」，agent-rules 只是文件生成器、不是运行时拦截器。若个人级文件写死在 git 仓库里，谁 clone 下来都有这套规则，无法按人关掉。所以 `CLAUDE.md` / `AGENTS.md` 改成由每台机器的安装过程按白名单决定「生成 / 不生成」。
+
+### 白名单判定规则
+
+- 白名单载体：npm 包内 `enabled-users.json`（发布到 `node_modules/@routerhub/agent-rules/enabled-users.json`），由 agent-rules 管理员维护。
+- 判定：**本机 git 身份 `user.name` 或 `user.email` 任一「包含」名单中任一字符串（不区分大小写、包含即命中）→ 启用**；未命中 → 默认停用。
+- 与仓库无关：只判断「这台电脑的开发者是谁」，不按项目 / git remote 判断，仓库分发逻辑不变。
+- **默认停用**：名单初始为空数组（先谁也不放）。不想用这套规则的人什么都不用做——只要不在名单里，个人级规则就不会生成（团队级 `.github` 云上 review 规则仍保留，属团队共享，不由个人启停控制）。
+- 逃生门：`AGENT_RULES_ENABLED=1` 强制启用 / `=0` 强制停用（测试与临时场景，环境变量级别，优先级高于白名单）。
+
+### 停用时的行为
+
+- 不生成 `CLAUDE.md` / `AGENTS.md`；
+- 自动把这两个文件加入项目 `.gitignore`，防止后续误提交入库；
+- 清理本机历史安装残留：只删除「存在 + 未被 git 跟踪 + 文件头为 `# Copilot Agent Rules - Base`」的 agent-rules 产物，**开发者自己的同名文件绝不删除**；仍被 git 跟踪的旧产物会提示等待仓库升级移除（升级时自动完成，见下文）。
+
+### 如何获取本机 git 身份（想启用的人自查用）
+
+在目标项目根目录（或任意能取到本机身份的目录）执行：
+
+```bash
+git config user.name
+git config user.email
+```
+
+- 不带 `--global` 时，显示**当前所在项目生效的值**（项目级 `user.name/email` 优先，项目没配则回退到全局 `~/.gitconfig`）。
+- 想确认自己机器全局配置的，再加 `--global`：
+
+```bash
+git config --global user.name
+git config --global user.email
+```
+
+把上面命令输出的字符串发给 agent-rules 管理员，管理员把其中之一（或其子串）加入 `enabled-users.json` 并发版；对方执行一次 `pnpm update @routerhub/agent-rules --latest`（或重新 `pnpm install`）后，个人级规则即在本机生效。
+
+### 存量仓库升级迁移
+
+此前版本 `CLAUDE.md` / `AGENTS.md` 是随仓库 git 跟踪分发的。升级到本版本后，agent-rules 的自动升级 PR（8 个下游仓库）会**一次完成迁移**：把这两个文件移出 git 跟踪（`git rm --cached`，工作区文件保留），并同步 `.gitignore`。合并升级 PR 后，个人规则即按本机身份启停。
+
 ## 注意事项
 
 - 私有规则应只写项目特有的限制、接口地址、组件路径和业务规范

package/enabled-users.json

@@ -0,0 +1 @@
+[]

package/merge.js

@@ -12,13 +12,15 @@
  *   update 自动更新 @routerhub/agent-rules 到最新版本并重新生成规则文件
  *   watch  监听 AGENTS.private.md 变化并自动同步
  *
- * 输出文件：
- *   AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
- *   CLAUDE.md                                    全量合并（Claude Code 自动加载）
- *   .github/copilot-instructions.md              全局规则（VS Code Copilot）
- *   .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
- *   .github/PULL_REQUEST_TEMPLATE.md             统一 PR 模板（GitHub 新建 PR 时预填）
- *   .claude/skills/*                             同步 Skills 到项目本地
+ * 输出文件分两层：
+ *   个人级（不入库、按本机 git 身份白名单本地生成，默认停用）：
+ *     AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
+ *     CLAUDE.md                                    全量合并（Claude Code 自动加载）
+ *   团队级（始终生成、随仓库分发共享）：
+ *     .github/copilot-instructions.md              全局规则（VS Code Copilot）
+ *     .github/instructions/*.instructions.md       按域条件加载（VS Code Copilot applyTo）
+ *     .github/PULL_REQUEST_TEMPLATE.md             统一 PR 模板（GitHub 新建 PR 时预填）
+ *     .claude/skills/*                             同步 Skills 到项目本地
  */
 
 const fs = require("fs");
@@ -105,6 +107,168 @@ function writeFileIfChanged(filePath, content) {
   return true;
 }
 
+/* ===== 个人级启停（按人白名单）=====
+ *
+ * AGENTS.md / CLAUDE.md 是「本地 AI 自动读取」的个人级规则文件，不入库、随安装生成。
+ * 是否生成取决于「当前机器开发者的本地 git 身份」（user.name / user.email）是否命中
+ * enabled-users.json 白名单中的任一字符串（不区分大小写、包含即命中）。默认白名单为
+ * 空数组 → 所有人默认停用。停用 = 不再生成 + 清理本机残留的 agent-rules 个人文件。
+ * 团队级文件（.github/*、.claude/skills/*、AGENTS.private.md）始终生成，不参与个人启停。
+ * 逃生门：环境变量 AGENT_RULES_ENABLED=1/0 可强制启用/停用（测试与临时场景）。
+ */
+
+// agent-rules 生成文件的签名头部，用于安全识别「我们的产物」，避免误删开发者自己的文件
+const PERSONAL_OUTPUT_SIGNATURE = "# Copilot Agent Rules - Base";
+
+// 读取当前开发者的本地 git 身份（项目级配置优先，缺失时回退全局；均无则返回空串）
+function getGitIdentity() {
+  const { spawnSync } = require("child_process");
+  const read = (key) => {
+    try {
+      const result = spawnSync("git", ["config", "--get", key], {
+        cwd: currentRoot,
+        encoding: "utf8",
+      });
+      if (result.status === 0) {
+        return (result.stdout || "").trim();
+      }
+    } catch (e) {
+      // 忽略：目录不在 git 仓库或 git 不可用，视为拿不到该身份
+    }
+    return "";
+  };
+  return { name: read("user.name"), email: read("user.email") };
+}
+
+// 读取随包分发的白名单（agent-rules 包根目录 enabled-users.json）
+function loadEnabledUsers() {
+  const usersPath = path.join(packageRoot, "enabled-users.json");
+  try {
+    if (fs.existsSync(usersPath)) {
+      const parsed = JSON.parse(fs.readFileSync(usersPath, "utf8"));
+      if (Array.isArray(parsed)) {
+        return parsed.map((s) => String(s).trim()).filter(Boolean);
+      }
+    }
+  } catch (e) {
+    console.warn(
+      `⚠️  白名单 ${usersPath} 解析失败，默认按「停用」处理: ${e.message}`,
+    );
+  }
+  return [];
+}
+
+// 个人规则（CLAUDE.md / AGENTS.md）是否对当前机器启用，返回 { enabled, reason } 便于打印原因
+function resolvePersonalEnabled() {
+  const force = process.env.AGENT_RULES_ENABLED;
+  if (force === "1" || force === "true") {
+    return { enabled: true, reason: "环境变量 AGENT_RULES_ENABLED=1 强制启用" };
+  }
+  if (force === "0" || force === "false") {
+    return { enabled: false, reason: "环境变量 AGENT_RULES_ENABLED=0 强制停用" };
+  }
+
+  const { name, email } = getGitIdentity();
+  const identities = [name, email].map((s) => s.toLowerCase()).filter(Boolean);
+  // 拿不到任何 git 身份（CI / bot / 非 git 目录且无全局配置）→ 默认停用
+  if (identities.length === 0) {
+    return { enabled: false, reason: "当前目录未取到 git 身份（CI / bot / 非开发者）" };
+  }
+
+  const enabledUsers = loadEnabledUsers();
+  if (enabledUsers.length === 0) {
+    return { enabled: false, reason: "enabled-users.json 白名单为空（默认停用）" };
+  }
+  // git 身份（name/email）「包含」白名单任一字符串（不区分大小写）即启用
+  const hit = enabledUsers.some((candidate) => {
+    const key = candidate.toLowerCase();
+    return identities.some((identity) => identity.includes(key));
+  });
+  return hit
+    ? { enabled: true, reason: "本机 git 身份命中 enabled-users.json 白名单" }
+    : { enabled: false, reason: "本机 git 身份未命中 enabled-users.json 白名单" };
+}
+
+function isPersonalEnabled() {
+  return resolvePersonalEnabled().enabled;
+}
+
+// 文件是否已被 git 跟踪（true 时删除会改变 git 状态，不应由生成器擅自处理）
+function isGitTracked(filePath) {
+  const { spawnSync } = require("child_process");
+  const relPath = path.relative(currentRoot, filePath);
+  try {
+    const result = spawnSync(
+      "git",
+      ["ls-files", "--error-unmatch", "--", relPath],
+      { cwd: currentRoot, encoding: "utf8" },
+    );
+    return result.status === 0;
+  } catch (e) {
+    return false;
+  }
+}
+
+// 停用时清理个人规则文件：只删「存在 + untracked + 头部为 agent-rules 签名」的产物；
+// tracked 产物提示走仓库迁移（生成器不擅动 git 状态）；签名不匹配（可能已被开发者
+// 替换/改写）绝不删除，只删我们生成的、别人的不动。
+function cleanupPersonalOutput(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return;
+  }
+  const content = readFileIfExists(filePath);
+  if (content === null || !content.startsWith(PERSONAL_OUTPUT_SIGNATURE)) {
+    console.log(
+      `   ⏭️  跳过 ${filePath}：内容不是 agent-rules 生成产物（可能是开发者自己的文件），未删除`,
+    );
+    return;
+  }
+  if (isGitTracked(filePath)) {
+    console.log(
+      `   ⏭️  跳过 ${filePath}：该文件仍被 git 跟踪，请等待仓库升级移除（或由管理员手动删除后提交），生成器不擅动 git 状态`,
+    );
+    return;
+  }
+  fs.unlinkSync(filePath);
+  console.log(`   🗑️  已删除停用的个人规则文件 ${filePath}`);
+}
+
+// 幂等：把个人规则文件加入项目 .gitignore，防止后续误提交入库
+function ensureIgnorePersonalOutputs() {
+  const gitignorePath = path.join(currentRoot, ".gitignore");
+  const header =
+    "# agent-rules：个人规则文件（CLAUDE.md / AGENTS.md）不入库，随安装按白名单本地生成";
+  const patterns = ["/AGENTS.md", "/CLAUDE.md"];
+
+  const existed = fs.existsSync(gitignorePath);
+  const existing = readFileIfExists(gitignorePath) || "";
+  const currentLines = existing.split(/\r?\n/);
+  const missing = patterns.filter((pattern) => {
+    const bare = pattern.replace(/^\//, "");
+    return !currentLines.some((line) => {
+      const trimmed = line.trim();
+      return trimmed === pattern || trimmed === bare;
+    });
+  });
+  if (missing.length === 0) {
+    return;
+  }
+
+  const block = header + "\n" + missing.join("\n") + "\n";
+  let nextContent;
+  if (!existed) {
+    nextContent = block;
+  } else if (existing.endsWith("\n")) {
+    nextContent = existing + block;
+  } else {
+    nextContent = existing + "\n" + block;
+  }
+  fs.writeFileSync(gitignorePath, nextContent, "utf-8");
+  console.log(
+    `   ℹ️  已把个人规则文件加入 ${gitignorePath}（/AGENTS.md、/CLAUDE.md）`,
+  );
+}
+
 /**
  * 解析 markdown 文件的 YAML frontmatter
  * 返回 { meta: { name, applyTo, outputName }, content: "去掉 frontmatter 后的正文" }
@@ -487,6 +651,17 @@ function mergeAgents(config) {
   console.log(`   规则目录: ${rulesDir}`);
   console.log(`   私有规则: ${privateRulesPath}`);
 
+  // 个人级启停：决定 CLAUDE.md / AGENTS.md 是否本地生成（按本机 git 身份白名单）
+  const { enabled: personalEnabled, reason: personalReason } =
+    resolvePersonalEnabled();
+  console.log(
+    `   个人规则文件(CLAUDE.md / AGENTS.md): ${
+      personalEnabled ? "✅ 启用" : "⏸️  停用"
+    } —— ${personalReason}`,
+  );
+  // 幂等：无论启停都确保个人文件被 .gitignore 忽略，防止被误提交入库
+  ensureIgnorePersonalOutputs();
+
   // 同步统一 PR 模板到 .github/PULL_REQUEST_TEMPLATE.md（独立于 rules/ 是否为空）
   syncPrTemplate(config);
 
@@ -513,10 +688,18 @@ function mergeAgents(config) {
         privateRules;
     }
 
-    for (const outputPath of [agentsOutput, claudeOutput, copilotOutput]) {
-      writeFileIfChanged(outputPath, merged);
-      console.log(`✅ 规则已合并到 ${outputPath}`);
+    // 个人级输出（CLAUDE.md / AGENTS.md）受白名单启停；团队级 copilot 始终生成
+    if (personalEnabled) {
+      for (const outputPath of [agentsOutput, claudeOutput]) {
+        writeFileIfChanged(outputPath, merged);
+        console.log(`✅ 规则已合并到 ${outputPath}`);
+      }
+    } else {
+      cleanupPersonalOutput(agentsOutput);
+      cleanupPersonalOutput(claudeOutput);
     }
+    writeFileIfChanged(copilotOutput, merged);
+    console.log(`✅ 规则已合并到 ${copilotOutput}`);
 
     // 同步 Skills
     syncSkills(config);
@@ -577,12 +760,19 @@ function mergeAgents(config) {
       "\n\n---\n\n# 项目私有规则\n\n以下规则仅适用于本项目，会覆盖基础规则中的相同部分。\n\n" +
       privateContent;
   }
-  writeFileIfChanged(agentsOutput, agentsMerged);
-  console.log(`✅ 全量规则已合并到 ${agentsOutput}`);
-
-  // CLAUDE.md 与 AGENTS.md 内容一致，供 Claude Code 会话自动加载
-  writeFileIfChanged(claudeOutput, agentsMerged);
-  console.log(`✅ 全量规则已合并到 ${claudeOutput}`);
+  // 6. 个人级输出（CLAUDE.md / AGENTS.md）：仅当本机 git 身份命中白名单才生成；
+  //    停用则清理本机残留（untracked + 签名的产物），团队级文件不受影响
+  if (personalEnabled) {
+    writeFileIfChanged(agentsOutput, agentsMerged);
+    console.log(`✅ 全量规则已合并到 ${agentsOutput}`);
+
+    // CLAUDE.md 与 AGENTS.md 内容一致，供 Claude Code 会话自动加载
+    writeFileIfChanged(claudeOutput, agentsMerged);
+    console.log(`✅ 全量规则已合并到 ${claudeOutput}`);
+  } else {
+    cleanupPersonalOutput(agentsOutput);
+    cleanupPersonalOutput(claudeOutput);
+  }
 
   // 6.1 同步 Skills 到项目 .claude/skills/
   syncSkills(config);
@@ -603,9 +793,10 @@ function initAgents() {
   }
 
   console.log("✅ 初始化完成，后续执行 agent-rules sync 即可刷新规则文件");
-  console.log("   输出文件:");
-  console.log("   - CLAUDE.md（全量，Claude Code 会话自动加载）");
-  console.log("   - AGENTS.md（全量，兼容 Cursor/Claude Code）");
+  console.log("   个人级文件（按本机 git 身份白名单启停，默认停用）:");
+  console.log("   - CLAUDE.md / AGENTS.md（停用时不会生成，并清理本机残留）");
+  console.log("     查看当前 git 身份：git config user.name  /  git config user.email");
+  console.log("   团队级文件（始终生成、随仓库分发）:");
   console.log("   - .github/copilot-instructions.md（全局规则）");
   console.log("   - .github/instructions/*.instructions.md（按域条件加载）");
   console.log("   - .claude/skills/*（Claude Code Skills 技能文件）");
@@ -754,13 +945,14 @@ function main() {
     );
     console.log("  agent-rules help   查看帮助");
     console.log("");
-    console.log("输出文件:");
+    console.log("输出文件（个人级，按本机 git 身份白名单启停，默认停用）:");
     console.log(
       "  CLAUDE.md                                    全量合并（Claude Code 会话自动加载）",
     );
     console.log(
       "  AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）",
     );
+    console.log("输出文件（团队级，始终生成）:");
     console.log(
       "  .github/copilot-instructions.md              全局规则（VS Code Copilot）",
     );
@@ -770,6 +962,17 @@ function main() {
     console.log(
       "  .claude/skills/*                             Claude Code Skills（创建PR / 部署 / Figma / TDD / 写文档等）",
     );
+    console.log("");
+    console.log("个人级启停说明:");
+    console.log(
+      "  本机 git 身份（git config user.name / user.email）包含 enabled-users.json 白名单任一字符串即启用",
+    );
+    console.log(
+      "  查看当前身份: git config user.name  /  git config user.email",
+    );
+    console.log(
+      "  强制开关（测试/临时）: AGENT_RULES_ENABLED=1 强制启用 / =0 强制停用",
+    );
     return;
   }
 

package/package.json

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