@routerhub/agent-rules 1.5.83 → 1.5.85

package/AGENTS.base.md

@@ -336,6 +336,37 @@ Closes #456
 - Figma 中配置或表达的跳转、链接、页面流、弹窗、hover/click 等交互必须同步实现；原型未明确但影响流程闭环的交互，需先核对现有产品或询问用户，禁止自行脑补。
 - 交付前必须对照 Figma 做视觉和交互验收，发现无法完全还原的素材、字体、数据或平台限制时，必须明确说明差异和原因。
 
+### Figma 设计还原规范（MCP 三步验证法）
+
+⚠️ Figma 设计还原时，**禁止直接使用 `get_design_context` 生成的 Tailwind 代码**。`get_design_context` 的代码是大模型推导的近似值，数值（px、间距、尺寸）、布局结构（flex 方向、嵌套关系）和定位方式（absolute/flex）都可能与 Figma 真实设计不符，必须通过以下三步验证：
+
+**第 1 步：`get_design_context` → 获取设计意图**
+- 用 `get_design_context` 了解组件的整体结构、颜色、字体、视觉效果
+- ⚠️ 仅用于理解设计意图，**数值和结构不可信**
+
+**第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）**
+- `get_metadata` 返回的是 Figma 内部每个节点的**真实 x/y/width/height 坐标**，这是所有尺寸、间距、定位的唯一事实源
+- 用 metadata 坐标反推间距：section 内子元素 y 坐标 = section 的 top padding，子元素高度 + 上边距 + 下边距 = 父级高度
+- 用 metadata 验证布局结构：同级兄弟节点的 x/y 关系决定它们是横向还是纵向排列，子节点 x 坐标决定它是 flex 子元素还是 absolute 定位
+
+**第 3 步：`get_metadata` 坐标反推规则**
+
+| 场景 | 反推方法 |
+|------|----------|
+| Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
+| 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
+| 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
+| 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
+| 元素是否有旋转/变换 | `get_design_context` 中有 `rotate`、`-translate-` 等类名 |
+
+**常见踩坑清单：**
+
+1. **`get_design_context` 生成的 padding 不准** → 必须以 metadata 坐标为基准重新计算
+2. **按钮被嵌套在文字 `flex-col` 内部** → metadata 中同级 x 坐标不同、y 坐标相近 = 横向并排，不应嵌套
+3. **固定宽度容器被改成了全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
+4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
+5. **`justify-between` + 全宽把元素推到极端两端** → 必须先确认 metadata 中内容行的宽度
+
 ## 文件约束
 
 - 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。

package/merge.js

@@ -7,9 +7,10 @@
  *   node merge.js [command]
  *
  * command:
- *   init  初始化规则文件，并在缺失时创建 AGENTS.private.md 模板
- *   sync  重新生成所有规则输出文件
- *   watch 监听 AGENTS.private.md 变化并自动同步
+ *   init   初始化规则文件，并在缺失时创建 AGENTS.private.md 模板
+ *   sync   重新生成所有规则输出文件
+ *   update 自动更新 @routerhub/agent-rules 到最新版本并重新生成规则文件
+ *   watch  监听 AGENTS.private.md 变化并自动同步
  *
  * 输出文件：
  *   AGENTS.md                                    全量合并（兼容 Cursor/Claude Code）
@@ -614,6 +615,44 @@ function watchAgents() {
   });
 }
 
+function selfUpdate() {
+  const { execSync } = require("child_process");
+
+  // 检测包管理器：按锁文件优先级 pnpm > yarn > npm
+  const lockFiles = [
+    { name: "pnpm", file: "pnpm-lock.yaml", cmd: "pnpm update @routerhub/agent-rules --latest" },
+    { name: "yarn", file: "yarn.lock", cmd: "yarn upgrade @routerhub/agent-rules --latest" },
+    { name: "npm", file: "package-lock.json", cmd: "npm update @routerhub/agent-rules@latest" },
+  ];
+
+  let pm = lockFiles[lockFiles.length - 1]; // 默认 npm
+  for (const candidate of lockFiles) {
+    if (fs.existsSync(path.join(currentRoot, candidate.file))) {
+      pm = candidate;
+      break;
+    }
+  }
+
+  console.log(`📦 检测到包管理器: ${pm.name}`);
+  console.log(`🔄 正在更新 @routerhub/agent-rules 到最新版本...`);
+  console.log(`   执行: ${pm.cmd}`);
+
+  try {
+    execSync(pm.cmd, { cwd: currentRoot, stdio: "inherit" });
+    console.log("");
+    console.log("✅ 包更新完成，正在重新生成规则文件...");
+  } catch (err) {
+    console.error(`❌ 包更新失败: ${err.message}`);
+    console.error("   请手动执行: " + pm.cmd);
+    process.exit(1);
+  }
+
+  // 更新完成后执行 sync，重新生成所有规则输出文件
+  mergeAgents(getDefaultConfig());
+  console.log("");
+  console.log("✅ 规则文件已全部更新完成！");
+}
+
 function main() {
   const command = process.argv[2];
 
@@ -628,6 +667,9 @@ function main() {
     console.log(
       "  agent-rules sync   重新生成所有规则输出文件（CLAUDE.md + AGENTS.md + copilot-instructions.md + instructions/*.instructions.md）",
     );
+    console.log(
+      "  agent-rules update 自动更新 @routerhub/agent-rules 到最新版本并重新生成规则文件",
+    );
     console.log(
       "  agent-rules watch  监听 AGENTS.private.md，变更后自动同步所有规则文件",
     );
@@ -659,6 +701,12 @@ function main() {
     return;
   }
 
+  if (command === "update") {
+    selfUpdate();
+    return;
+  }
+
+
   if (command === "watch") {
     watchAgents();
     return;

package/package.json

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

package/rules/frontend.md

@@ -10,6 +10,37 @@ outputName: "frontend"
 - Figma 中配置或表达的跳转、链接、页面流、弹窗、hover/click 等交互必须同步实现；原型未明确但影响流程闭环的交互，需先核对现有产品或询问用户，禁止自行脑补。
 - 交付前必须对照 Figma 做视觉和交互验收，发现无法完全还原的素材、字体、数据或平台限制时，必须明确说明差异和原因。
 
+### Figma 设计还原规范（MCP 三步验证法）
+
+⚠️ Figma 设计还原时，**禁止直接使用 `get_design_context` 生成的 Tailwind 代码**。`get_design_context` 的代码是大模型推导的近似值，数值（px、间距、尺寸）、布局结构（flex 方向、嵌套关系）和定位方式（absolute/flex）都可能与 Figma 真实设计不符，必须通过以下三步验证：
+
+**第 1 步：`get_design_context` → 获取设计意图**
+- 用 `get_design_context` 了解组件的整体结构、颜色、字体、视觉效果
+- ⚠️ 仅用于理解设计意图，**数值和结构不可信**
+
+**第 2 步：`get_metadata` → 获取精确坐标（唯一事实源）**
+- `get_metadata` 返回的是 Figma 内部每个节点的**真实 x/y/width/height 坐标**，这是所有尺寸、间距、定位的唯一事实源
+- 用 metadata 坐标反推间距：section 内子元素 y 坐标 = section 的 top padding，子元素高度 + 上边距 + 下边距 = 父级高度
+- 用 metadata 验证布局结构：同级兄弟节点的 x/y 关系决定它们是横向还是纵向排列，子节点 x 坐标决定它是 flex 子元素还是 absolute 定位
+
+**第 3 步：`get_metadata` 坐标反推规则**
+
+| 场景 | 反推方法 |
+|------|----------|
+| Section 上下 padding | 子元素 y 坐标 = 上 padding；父级高度 - 子元素 y - 子元素高度 = 下 padding |
+| 元素间距（gap） | 兄弟元素之间的 y 差值（纵向）或 x 差值（横向） |
+| 元素是 flex 还是 absolute | 子元素 x 超出父元素左边界 → absolute；子元素在父元素范围内 → flex |
+| 固定宽度还是自适应 | metadata 有明确 width 值 → 固定宽度；否则 → 自适应 |
+| 元素是否有旋转/变换 | `get_design_context` 中有 `rotate`、`-translate-` 等类名 |
+
+**常见踩坑清单：**
+
+1. **`get_design_context` 生成的 padding 不准** → 必须以 metadata 坐标为基准重新计算
+2. **按钮被嵌套在文字 `flex-col` 内部** → metadata 中同级 x 坐标不同、y 坐标相近 = 横向并排，不应嵌套
+3. **固定宽度容器被改成了全宽** → metadata 中有明确 width 的容器不能去掉固定宽度
+4. **装饰图片被当成 flex 子元素** → metadata 中 x 坐标超出父元素范围 = absolute 定位
+5. **`justify-between` + 全宽把元素推到极端两端** → 必须先确认 metadata 中内容行的宽度
+
 ## 文件约束
 
 - 不随意修改核心业务文件和 API 相关代码，不编写或修改 `README.md`。