@routerhub/agent-rules 1.5.85 → 1.5.86

package/AGENTS.base.md

@@ -1,537 +1,96 @@
 # Copilot Agent Rules - Base
 
-## 🚨 元规则（最高优先级）
+以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。具体操作流程（PR 创建、部署、Figma 还原、TDD 等）已封装为 Skill，通过 `/skill名` 调用。
 
-**本文件中的每一条规则都是强制规则，不存在"建议"或"可选"。** 所有带 ⚠️ 标记的规则不可协商，不可因"上下文压缩""注意力分散""对话太长"等任何原因遗漏或跳过。
+## 🚨 元规则
 
-以下为始终生效的核心规则。各项目可通过 `AGENTS.private.md` 添加项目特定规则。
+本文件中的每一条规则都是强制规则。所有带 ⚠️ 标记的规则不可因「上下文压缩」「对话太长」等任何原因遗漏或跳过。
 
-## ⚠️ 规则修改入口（必读）
+## ⚠️ 规则修改入口
 
-- **所有规则的新增、修改、删除，必须改 `AGENTS.base.md`（源文件），禁止直接改 `CLAUDE.md` 或 `AGENTS.md`**。`CLAUDE.md` 和 `AGENTS.md` 是 `node merge.js sync` 自动生成的输出文件，直接改动会在下次 sync 时被覆盖丢失。
-- 修改 `AGENTS.base.md` 后，必须执行 `node merge.js sync` 重新生成所有输出文件，然后提交并发版。
+- **新增、修改、删除规则，必须改 `AGENTS.base.md`（源文件），禁止直接改 `CLAUDE.md` 或 `AGENTS.md`**。改完后必须执行 `node merge.js sync` 重新生成输出文件。
 
 ## 语言与内容
 
-- 始终使用中文回答，代码注释使用中文，每行代码配中文注释。
-- 我是测试用的。
+- 始终使用中文回答，代码注释使用中文。
 - 页面 UI 内容（按钮、字段名、提示等）全部英文；如需中文在 `AGENTS.private.md` 中声明。
-- 仅修改网站协议、条款、页面文案等文本内容时，必须保留原有结构、格式、样式和布局，只替换文字；只有用户明确要求调整样式时，才允许同步修改样式。
 
 ## 需求实现原则
 
-- ⚠️ **严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。** 例如用户说"展示一个轮播图"，就只实现轮播图功能，不得自行添加"最多 6 个元素"、"必须自动播放"等用户没提的限制。
-- 只有代码安全/性能的硬性必要（如防止无限循环、防止内存泄漏、防止 XSS 等）才允许添加隐含约束，且必须在实现时向用户说明添加原因。
-- 不确定某个限制或规则是否必要时，必须先询问用户，禁止直接添加。
+- ⚠️ 严格按用户原话实现需求，禁止擅自添加用户未要求的限制、规则或约束。
+- ⚠️ 不确定某个限制是否必要时，必须先询问用户，禁止直接添加。
 
 ## Git 规范
 
 - 分支用 Git Flow（`feature/`、`bugfix/`、`hotfix/`、`refactor/`、`chore/`、`docs/`、`test/`），英文小写中划线分隔。
-- `test` 分支为测试环境专用分支，禁止直接在 `test` 分支上提交代码；所有代码必须在功能分支上开发完成后，通过 PR 合入 `test` 分支。合入后部署 `test` 分支到测试环境，实现单一测试环境共用。
-- commit 信息必须中文，禁止 `git push --force`。
-
-## PR 提交、评审与合入规范
-
-- ⚠️ **强制要求：所有 PR 的 Title、Description、Test Plan 等全部文字内容必须使用中文编写**，方便团队成员阅读理解，禁止使用英文撰写 PR 内容。
-- ⚠️ **强制要求：所有 PR 必须附上相关截图作为可视化证据**，无论是否涉及 UI 改动。截图需包含：功能效果截图、测试结果截图、关键代码变更对比截图等，让 reviewer 无需拉取代码即可直观理解改动内容与验证结果。
-- PR 的目标是让审阅者在不依赖私下沟通的情况下独立理解、验证并放心 Approve；一个好的 PR 必须自解释。
-- 每个 PR 必须能独立通过编译与测试，禁止出现”这个 PR 编译不过，要等下一个 PR 才能跑”的状态。
-- ⚠️ **强制要求：一个 PR 只做一件事**。每个 PR 必须聚焦单一功能改动，按功能维度划分，禁止将多个不相关的功能、修复或重构混在同一个 PR 中。PR 的拆分粒度以”功能”为单位：一个完整的功能点（如新增用户登录、修复支付回调 bug、重构缓存模块）对应一个 PR；不属于同一功能的改动必须拆分为独立 PR。判断标准：如果一个 PR 的 Description 需要用”和”、”以及”、”同时”等连接词来描述多项不相关的改动，说明该 PR 应该拆分。
-- PR Title 必须用祈使句、现在时态描述“做了什么”，建议加模块/组件前缀，保持简洁且一行说清。
-- PR Title 示例：`[auth] Fix token refresh race condition on concurrent requests`、`[payments] Add idempotency key to charge API`、`[infra] Migrate cache layer from Redis 6 to Redis 7`。
-- PR Title 禁止使用 `fix bug`、`update code`、`改了一下` 等无法表达实际改动的标题。
-- PR Description 必须足够充分，至少回答 What（改了什么）、Why（为什么改，解决什么问题或满足什么需求）、How（采用什么方案，为什么选该方案）。
-- PR Description 必须使用中文编写，方便团队成员阅读理解；涉及 UI 改动、交互流程、页面效果等可视化变更时，必须附上截图或录屏作为证据。
-- PR Description 和 Test Plan 的文字应尽可能简洁明了，优先用页面操作路径、按钮点击、表单输入、可见结果描述验证过程；尽量少用代码片段解释，除非代码是理解变更或复现问题的必要证据。
-- 涉及行为变更、接口变更、数据迁移、性能影响时，必须在 Description 中显式写出。
-- 有意不做的事、已知局限、后续 follow-up 必须写清楚，避免 reviewer 重复追问。
-- 关联 issue 必须在 PR 中链接，并优先使用 GitHub 关键字自动关闭，例如 `Closes #123`、`Fixes #123`。
-- Description 推荐模板：
-
-```markdown
-## Description
-
-背景：当前在并发刷新 token 时存在竞态，会导致少量请求拿到过期 token 被拒。
-
-改动：给 token 刷新加分布式锁，保证同一时刻只有一个刷新在飞，其余请求等待复用结果。
-
-方案取舍：考虑过乐观重试，但在高并发下重试风暴更糟，故选锁方案。锁超时 2s 兜底。
-
-不在本 PR 范围：监控告警接入留作后续 follow-up（#457）。
-
-Closes #456
-```
-
-- Test Plan 是硬性必填项，没有 Test Plan 的 PR 不允许进入审阅，建议写进 `.github/PULL_REQUEST_TEMPLATE.md` 固定章节。
-- Test Plan 必须说明如何验证改动正确，并提供可复现步骤或证据，包括自动化测试命令与结果、手动验证步骤、截图、录屏、日志输出、请求响应、修复前后对比等。
-- UI 改动必须贴前后对比截图；接口改动必须贴请求响应；修 bug 必须贴复现前与修复后的对比。
-- Test Plan 必须覆盖必要边界情况，例如并发、异常、空值、回滚路径等。
-- 禁止只写 `tested locally`、`测了没问题`；能用文字日志说明的，也要贴日志原文。
-- Test Plan 推荐模板：
-
-```markdown
-## Test Plan
-
-1. 单元测试：
-   $ npm test -- auth/token/
-   -> 全部通过（截图见下）
-
-2. 手动复现原 bug：
-   - 开 50 并发同时调 /refresh
-   - 修复前：约 3% 请求返回 401（日志附后）
-   - 修复后：0 失败（截图：dashboard 401 曲线归零）
-
-3. 回滚验证：关闭 feature flag 后行为回到旧逻辑，正常。
-
-[截图1：测试通过结果]
-[截图2：修复前后 401 曲线对比]
-```
-
-- 每个 PR 至少需要一名 reviewer Approve 才能合入，建议用 Branch protection 强制 `Require a pull request before merging` 和至少 1 个 Approval。
-- Reviewer 优先指定最熟悉对应模块的 owner，并通过 `CODEOWNERS` 自动请求对应 owner 审阅。
-- 涉及多模块时，每个模块都要指定对应 reviewer。
-- 高风险改动（安全、支付、数据迁移、对外接口）必须通过 `CODEOWNERS` 设置 Required review，由对应 owner 通过后才能合入。
-- 作者不能 Approve 自己的 PR。
-- PR 其他元数据必须完整：Assignees 填负责人，Labels 填类型/优先级/模块，Linked Issues/Projects 关联需求来源与项目看板，Milestone 按需关联发布里程碑。
-- 尚未准备好审阅时必须先开 Draft PR，准备好后再标记 `Ready for review`。
-- 作者提交审阅前必须完成自查：没有夹带格式化、顺手改动等无关改动；Title 清晰；Description 写明 What/Why/How；Test Plan 完整且带证据；已自审 `Files changed`；已移除调试代码、注释代码和无效 TODO；没有泄露密钥、token、内部地址、PII 等敏感信息；已指定合适 reviewer；已关联 issue；本地编译、lint、测试通过；CI status checks 全绿。
-- 满足以下全部条件才允许 Merge：至少一名 reviewer 已 Approve；`CODEOWNERS` required review（如有）已通过；所有 required status checks（构建、单测、lint、静态分析等）全部绿色；所有 review 评论和 `Request changes` 均已解决并 Resolve conversation；分支与目标分支无冲突且已更新到最新。
-- 建议开启 Branch protection 强制合入门禁，并开启 `Require branches to be up to date`。
-- 团队应统一 Merge 方式，多数情况用 `Squash and merge` 保持主干历史干净；需要保留完整提交历史时再用 merge commit。
-- Reviewer 收到 review 请求后应尽量在 1 个工作日内给出首次反馈。
-- Reviewer 必须看懂再 Approve；看不懂就提问，禁止为了快而盲目 Approve。
-- Reviewer 反馈必须区分等级：必须改用 `Request changes`，建议项标注 `nit:` 或 `optional:`，疑问标注 `question:`，避免作者误判优先级。
-- Review 评论必须对事不对人，针对代码与方案并保持尊重。
-- Reviewer Approve 即代表认可该改动可以上线，并对该判断负责。
-- 作者必须回复每一条 review 评论，即使只是 `Done` 或解释为何不改，并 Resolve 对应 conversation。
-- 有分歧时优先在 PR 上公开讨论，结论必须写回 PR，避免私聊后无记录。
-- 较大方案分歧可以升级为线下或会议讨论，但最终结论必须回写到 PR。
-- 改动后必须使用 `Re-request review` 重新请求审阅，并在评论里简述本次更新改了什么。
-- 必须避免以下反模式：Test Plan 只写”测了没问题”；Description 只有”fix bug”；CI 红着或跳过检查直接合；把格式化/重命名和逻辑改动混在一起；评论不回复、不 Resolve 就直接重提 review。
-- PR 规范可按团队约定微调字段，但”充分的 Description + 带证据的 Test Plan + 至少一人 Approve + 状态检查全绿才能 Merge”是不可妥协的核心要求。
-
-## PR 提交辅助规则（AI 自动执行）
-
-- ⚠️ **创建 PR 时，AI 自动在 Description 中补充需求文档链接或需求描述**：自动查找 `docs/` 目录下对应的需求文档并附上链接；如该需求尚无文档，AI 自动根据本次改动内容在 Description 中写出完整的需求描述（含背景、目标、功能点、验收标准），无需用户手动填写。
-- ⚠️ **创建 PR 时，AI 自动附上功能效果截图**：根据改动类型自动截取并贴图 —— UI 改动自动截前后对比截图，接口/后端改动自动截请求响应截图或功能验证截图，修 bug 自动截复现前后对比截图。截图由 AI 自动完成，无需用户手动操作。
-- ⚠️ **PR 截图必须直接放在 Description 正文中**，以 Markdown 图片语法（`![](url)`）内嵌到 Description 里，reviewer 打开 PR 即可直观看到效果，禁止只贴外部链接或附件形式。
-
-### PR 效果截图制作规范
-
-- ⚠️ **截图文件禁止提交到 Git 仓库**。截图通过 GitHub 评论区 file input 上传，获取 CDN URL（`https://github.com/user-attachments/assets/...`），公网可直接访问。
-- ⚠️ **截图必须直接内嵌在 PR Description 中**，以 Markdown 图片语法（`![](url)`）渲染，reviewer 打开 PR 即可直观看到效果，禁止只贴外部链接或附件。
-- ⚠️ **截图必须展示前后对比**（修复前 vs 修复后），左右并排排列。
-- ⚠️ **关键改动区域必须用彩色矩形框圈选标注**（修复前红框，修复后绿框），标注框不遮挡页面内容。
-- ⚠️ **标注说明文字放在截图上方独立色条区域**（修复前红色条，修复后绿色条），文字格式：`❌ 修复前：XXX` / `✅ 修复后：XXX`，色条和标注框色统一。
-- ⚠️ **截图只截取改动相关区域**，顶部无关内容（URL 栏、导航栏等）裁掉不截。
-
-### PR 效果截图制作流程（Claude Code 自动执行）
-
-生成 PR 时按以下步骤自动制作效果截图：
-
-1. **截修复后**：本地开发服打开改动涉及的页面 → 滚动到改动区域 → 全页截图
-2. **截修复前**：临时注释/回退本次改动的代码 → 等 hot reload → 同页面同位置全页截图 → 恢复代码
-3. **生成对比图**：用 `sharp` 拼接两张截图 —— 上方红/绿色标注条（含修复前/后文字说明），下方截图内容（关键改动区域用对应颜色矩形框圈选），左修复前右修复后并排
-4. **上传到 GitHub CDN**：打开 PR 页面 → 通过评论区隐藏的 `#fc-new_comment_field` 上传对比图 → 获取 `user-attachments` CDN URL
-5. **写入 PR Description**：`![](CDN_URL)` 内嵌到 Description 中，清理评论区临时上传的评论
+- `test` 分支禁止直接提交代码，代码必须通过 PR 合入。commit 必须中文，禁止 `git push --force`。
 
-## 安全
-
-- 用户明确要求上线/部署生产环境时，直接执行，无需二次确认。
-- 执行过程中自行触及生产环境操作（非用户明确要求），必须先向用户二次确认后再执行。
-
-## 需求文档
-
-- 新需求先在 `docs/` 写文档，含：目标、范围、功能要求、验收标准。
-
-## ⚠️ 回归测试体系与 TDD 开发流程（强制）
-
-### 一、回归测试入口
-
-本项目的回归测试通过回归测试中心执行，入口为 `上线回归测试点.js`，本质是打开回归测试中心 UI 页面（`上线前回归测试.html`），在该页面中勾选用例并一键执行。
-
-- **打开回归中心**：`pnpm run regression:open`（自动启动 runner 服务 + 打开浏览器页面）
-- **全量测试按钮**：回归中心页面内有「全量测试」按钮，点击即跑所有已注册的回归用例，生成可视化验收报告
-- **可视化报告**：跑完后自动生成 HTML 报告，包含每条用例的通过/失败状态、E2E 截图、后端代码流程解释卡片、失败定位信息
-
-### 二、回归用例层级
-
-所有回归用例统一注册在 `scripts/superpowers-regression-runner.js` 的 `TEST_CASES` 对象中，按层级分为四类：
-
-| 层级 | 说明 | 示例 |
-|------|------|------|
-| **Go 单元测试** | 后端业务规则单测 | Credit 消耗规则、自动充值、低余额提醒、月度限额合约 |
-| **API 冒烟测试** | 接口可达性与鉴权拦截 | 健康检查、登录入口、受保护接口鉴权拦截、支付回调 |
-| **Admin E2E** | 管理端 Playwright 端到端 | 模型 CRUD 生命周期、Credit 管理、月度限额专项 |
-| **User E2E** | 用户端 Playwright 端到端 | 买赠政策验证、客户端页面流程、AI 助手 |
-
-### 三、Superpowers TDD 开发流程（每次会话强制遵循）
-
-⚠️ **每次接收新需求、修改代码时，必须严格按以下流程执行，不可跳过任何步骤：**
-
-#### 第 1 步：需求记录（留痕）
-
-- 在 `docs/` 目录下新建需求文档（HTML 格式，中文命名），记录：需求背景、功能范围、验收标准、所属版本号/版本名称
-- 如果需求已有版本号 → 标注版本号，后续测试用例归档到该版本
-- 如果需求未说明版本号 → 归档到「全量测试」范围
-- 使用 Superpowers 的 `brainstorming` skill 做需求分析（触发时机：需求不清晰或需要设计方案时）
-
-#### 第 2 步：确认需求归属版本
-
-- 查看该需求属于哪个版本（如 v2.1.0、v2.2.0 等）
-- 如果用户未说明版本号 → 默认为全量测试范围
-- 在需求文档中明确写出：「归属版本：XXX」或「归属范围：全量测试」
-
-#### 第 3 步：测试先行（TDD）
-
-- ⚠️ **先写测试用例，再写业务代码**
-- Go 后端需求 → 先在 `app/supply/`、`app/controller/` 等目录下写 Go 单测（`_test.go`）
-- 前端 UI 需求 → 先在 `admin_web/e2e/` 或 `user_web/e2e/` 下写 Playwright E2E spec
-- API 接口需求 → 先在 `scripts/regression-api-smoke.js` 中加冒烟子命令
-- 然后在 `scripts/superpowers-regression-runner.js` 的 `TEST_CASES` 中注册新用例
-- 测试用例描述、断言必须使用中文
-
-#### 第 4 步：跑基线回归（改动前）
+## PR 核心要求
 
-- ⚠️ **改代码之前，必须先跑一次全量回归，建立基线**
-- 确认改动前所有已有用例全部通过，拿到基线报告
-- 如果已有失败用例，先排查是环境问题还是已有 bug，记录在案
+- ⚠️ PR Title / Description / Test Plan 全部中文。一个 PR 只做一件事。
+- ⚠️ 必须附截图作为可视化证据（前后对比、标注改动区域）。
+- ⚠️ 创建 PR 使用 `/create-pr` skill（自动生成中文内容 + 效果截图 + CDN 上传）。
 
-#### 第 5 步：实现业务代码
-
-- 按需求文档和测试用例实现功能
-- 实现过程中持续跑新增的测试用例，确保新功能正确
+## 安全
 
-#### 第 6 步：跑全量回归（改动后）
+- 用户明确要求上线/部署生产环境 → 直接执行。AI 自行触及生产环境操作 → 必须先向用户确认。
 
-- ⚠️ **改完代码后，必须跑全量回归**
-- 确认：新增用例全部通过 + 所有已有用例仍然通过
-- 如果全量回归有失败：
-  - 改动导致的 → 修代码，重新跑
-  - 环境问题 → 记录在回归报告中
-  - 已有用例本身的问题 → 修复用例或更新断言
-- **全量回归全部通过 = 新功能正确 + 已有功能不被破坏**
+## 代码风格
 
-#### 第 7 步：上线前回归
+- 驼峰命名，禁止下划线，变量至少两个单词。禁止 `as` 和 `any`。函数式编程，不写 `class`，不写 `try/catch`。
+- 禁止重复实现，发现重复必须提取封装。同一数据/配置只在一处维护。禁止硬编码数字。
+- 前端：Tailwind CSS 禁止原生 CSS，尺寸单位必须 `rem` 禁止 `px`（1rem=16px）。
+- 测试描述、断言使用中文。测试用例先主流程再边界情况。
 
-- ⚠️ **每次部署生产前，必须跑 `node 上线回归测试点.js`**
-- 这是上线前最后一道防线，确保生产环境不会出问题
+## Go 规则
 
-### 四、测试用例注册规范
+- 值传递优先，软删除用 `gorm.DeletedAt`（禁止 `*time.Time`）。
+- 禁止无条件执行 GORM AutoMigrate，必须由开关控制，默认关闭。
 
-在 `scripts/superpowers-regression-runner.js` 中注册新用例时：
+## 禁止项
 
-```javascript
-// Go 单测用例模板
-"go-xxx": {
-  id: "go-xxx",
-  name: "功能名称（中文）",
-  command: "go test -count=1 -v -run TestXxx ./app/xxx",
-  cwd: ROOT_DIR,
-},
+- ⚠️ AI 禁止自动执行格式化命令（`npm run format`、`prettier` 等）。
+- ⚠️ 禁止修改 GCLB 配置。
+- 禁止修改核心业务文件和 API 相关代码。
+- `.env` 仅允许配端口号，密钥/Token 等敏感信息必须配到 Nacos 配置中心。
 
-// API 冒烟用例模板
-"api-xxx": {
-  id: "api-xxx",
-  name: "接口名称（中文）",
-  command: "node scripts/regression-api-smoke.js xxx",
-  cwd: ROOT_DIR,
-},
+## 部署规则
 
-// Admin E2E 用例模板
-"e2e-admin-xxx": {
-  id: "e2e-admin-xxx",
-  name: "管理端功能名称（中文）",
-  command: "pnpm exec playwright test e2e/Xxx.spec.ts",
-  cwd: path.join(ROOT_DIR, "admin_web"),
-},
+- 发版统一执行 `./release.sh`。部署测试环境使用 `/deploy-test` skill。
 
-// User E2E 用例模板
-"e2e-user-xxx": {
-  id: "e2e-user-xxx",
-  name: "用户端功能名称（中文）",
-  command: "pnpm exec playwright test e2e/Xxx.spec.ts",
-  cwd: path.join(ROOT_DIR, "user_web"),
-},
-```
+## 文档规则
 
-### 五、留痕机制
+- 新建文档使用 HTML 格式（`.html`）、中文文件名，存到 `docs/` 目录。
+- 使用 `/create-doc` skill 生成符合规范的 HTML 文档。
 
-- 每个需求必须在 `docs/` 下留下需求文档（HTML 格式，中文文件名）
-- 每个需求的测试用例必须在回归中心注册，用例名称包含需求关键词
-- 全量回归报告（HTML）自动生成到 `docs/evidence/visual-acceptance/report.html`，可作为交付证据
-- 如果之前的记录（需求文档、测试用例）与实际情况不符，必须**立即更新**，不留过期文档
-- ⚠️ **每次会话的改动必须有迹可循**：需求文档 → 测试用例 → 回归报告 → 代码改动，四者一一对应
+## Figma 还原
 
-### 六、外部 Coding 的含义
+- Figma 设计还原使用 `/figma-to-code` skill，按 MCP 三步验证法执行。
 
-上述流程的本质是**外部化编码（External Coding）**：
+## TDD 开发
 
-- 代码的正确性不是靠"我觉得没问题"来判断的，而是靠**外部可观察的测试结果**来验证的
-- 每一次改动，都有一套完整的、可复现的回归用例作为安全网
-- 新增功能的验收标准在写代码之前就以测试用例的形式固化下来
-- 任何人在任何时候跑全量回归，都能立即知道系统当前的健康状态
-- 代码不再是黑盒，而是被测试用例从外部锁定的、可验证的产物
-
-### 七、AI 助手的职责
-
-作为 AI 开发助手，每次接收需求时必须：
-
-1. **第一反应不是写代码，而是确认归属版本 + 写需求文档 + 设计测试用例**
-2. 在实现代码之前，先在回归中心注册测试用例
-3. 代码写完后，必须跑全量回归并出示报告
-4. 交付时必须说明：新增了哪些测试用例、归属于哪个版本/全量测试、全量回归结果
-5. 如果用户说"直接改就行不用测试"，必须提醒用户测试是安全网，建议至少跑新增用例
-
-## 文档格式
-
-- 所有新建文档必须使用 HTML 格式（`.html`），禁止使用 Markdown（`.md`）格式。
-- 已有的 `.md` 文件可保留，但新增文档一律使用 HTML。
-- 编写 HTML 文档时，文档标题、正文、章节、说明文字、图注、表格等内容必须使用中文；仅代码、命令、专有名词、接口字段或页面 UI 原文可保留英文。
-- 编写 HTML 文档时，核心内容必须优先用截图、图片、流程图、对比图、标注图等可视化形式表达；图片内需添加箭头、圈选和简短中文标注，尽量减少英文字段和长段文字，能用可视化表达的内容不得只用文字说明。
-- 编写 HTML 文档时，所有图片资源（包括截图、图表、插图等）必须以 base64 data URI 形式内嵌到 HTML 中，禁止引用或额外输出独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件，确保他人只打开 HTML 文件即可看到全部内容并用于发版。
-- ⚠️ **HTML 报告/文档中的所有图片必须支持点击放大、全屏查看**：每张图片必须可点击，点击后弹出全屏遮罩层（lightbox），展示原图或放大版本，支持关闭（点击遮罩背景或关闭按钮）和键盘 ESC 关闭。实现方式：在 HTML 内嵌一段通用 JS 脚本，为所有图片绑定 click 事件，弹出全屏遮罩层展示该图片，遮罩层背景半透明黑色、图片居中自适应屏幕。
-- 所有新建 HTML 文档的文件名必须使用中文命名（如 `用户登录流程说明.html`），禁止使用英文或拼音文件名，方便团队成员一眼识别文档内容。
-- 所有新建 HTML 文档必须统一存放到项目根目录的 `docs/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
-- ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
-- ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
-
-## Superpowers 安装与缺失处理
-
-- 团队统一推荐使用 Superpowers 插件或同等技能流程处理新需求、调试、计划、测试驱动开发和完成前验证。
-- 代理或开发者进入项目后，如果当前环境无法使用 Superpowers，应先提示用户安装或启用 Superpowers；当前代理支持插件安装工具时，应优先发起安装建议，当前代理不支持时，应给出清晰的手动安装说明。
-- 用户暂不安装或当前环境无法安装时，不得因此中断任务；必须按本规则中的等价流程继续执行，包括需求文档、实现计划、测试准入、代码实现和完成前验证。
-- 不得把某一台电脑已安装 Superpowers 当作团队默认事实；交付说明中应明确本次是使用 Superpowers 流程，还是按 AGENTS 规则执行了等价流程。
+- 接收新需求使用 `/tdd-workflow` skill，按七步流程执行。
 
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）
-2. 基础规则（此文件）
-
-## 截图规范
-
-- 当用户要求截图时，必须截取整页（full page），不得只截可视区域。
-- 截图结果必须包含当前页面 URL（地址栏可见或在截图说明中明确写出完整 URL）。
-- 在截图上添加箭头、标注、提示文字等注释时，必须放在页面空白区域，不得覆盖页面原有内容（文字、按钮、表格数据等）。
-- 当用户要求生成 HTML 页面并同时要求截图时，所有截图必须以 base64 data URI 形式内嵌到 HTML 文件中，禁止将截图单独输出为独立的 PNG、JPG、JPEG、SVG、WebP 等图片文件。他人只需打开单个 HTML 文件即可看到完整页面内容和截图，无需额外图片文件。
-- 制作 HTML 报告过程中产生的所有截图、图表、插图等图片文件，必须统一存放到项目根目录的 `screenshots/` 文件夹下，禁止散落在桌面、下载目录、临时目录或其他任意位置。如该文件夹不存在则先创建。
-
-## 可视化汇报
-
-- 完成任务后的汇报优先提供可视化结果，能打开页面时就直接在集成浏览器中打开，并定位到相关区域后再汇报。
-- 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
-- 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
-
-## 外部文档查看/浏览器控制（agent-browser）
-
-- ⚠️ **浏览器控制以个人全局 `CLAUDE.md`（`~/.claude/CLAUDE.md`）为准，本文件不再重复定义端口、Profile、启动流程等配置。**
-- 团队开发者在自己的全局 `CLAUDE.md` 中配置 agent-browser + Chrome CDP 环境（端口、Profile 目录等）。
-- 基本约定：所有需要登录态的页面必须使用 `agent-browser --cdp <端口>` 连接已登录 Chrome，禁止 WebFetch / 无状态模式。
+2. 个人全局规则（~/.claude/CLAUDE.md）
+3. 本基础规则
 
 <!-- @domain: frontend -->
 
-## Figma 还原规范
-
-- 实现 Figma 设计时，必须以 Figma 文件为唯一视觉与交互事实源，逐项还原布局、尺寸、间距、颜色、字体、层级、组件状态、响应式规则和可见文案，禁止按个人审美或主观推测重设计。
-- 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`。
-- TypeScript 类型优先复用 `typings.d.ts`，不存在时再自定义。
-
-## 命名与类型
-
-- 驼峰命名（小驼峰/大驼峰），禁止下划线；变量至少两个单词。
-- 禁止 `as` 和 `any`；`props` 类型优先复用，不重复定义。
-
-## 代码风格
-
-- 函数式编程，不写 `class`，不写 `try/catch`。
-- 禁止重复实现：复用现有函数/组件/配置，发现重复必须提取封装为公共方法。
-- 同一数据/配置只在一处维护，其余通过引用获取，改一处全局生效。
-- 禁止硬编码数字；常量/枚举定义在 `Const.ts` 或 `constants.ts`，`tab` 索引统一使用常量，时间用 `dayjs`。
-- 遵循 SOLID 原则，避免过度设计；数据回显优先用展开运算符（`...`）。
-- 复用组件通过 `fromType`（值为当前页面名）区分来源，内部差异逻辑基于 `fromType` 分支。
-
-## 样式（Tailwind CSS）
-
-- 前端开发禁止编写原生 CSS，所有样式必须使用 Tailwind CSS 的 utility classes 实现，不写 `style` 标签、不写内联样式、不写独立样式文件。
-- 统一 Tailwind CSS，禁止新增 `*.module.scss`、`*.module.css`、`.css` 文件（历史文件可保留）。
-- 项目未集成 Tailwind 时，先完成安装配置再开发。
-- 新增样式通过 utility classes 在 JSX/TSX 中编写；不满足时优先 `tailwind.config` extend → `@apply` 封装 → 行内 `style`。
-- 复杂/重复样式提取为 Tailwind 组件类或 React 组件，避免工具类堆砌。
-- 类名小驼峰，禁止 `span` 标签选择器。
-
-## 前端尺寸单位规范
-
-- ⚠️ **前端项目所有尺寸单位必须使用 `rem`，禁止使用 `px`**。包括但不限于：`width`、`height`、`margin`、`padding`、`font-size`、`border-radius`、`gap`、`line-height`、`top`、`left`、`right`、`bottom` 等所有 CSS 属性的数值。
-- 根元素 `html` 的 `font-size` 默认设置为 `16px`（即 `1rem = 16px`），设计稿中的 `px` 值需转换为 `rem`（公式：`rem = px / 16`）。
-- Tailwind CSS 的 spacing 配置需同步改为 `rem` 单位，禁止在 `tailwind.config` 中使用 `px` 值。
-
-## 组件复用
-
-- 优先复用已有组件，能通过 `props` 定制就不建新组件；新功能尽量封装为可复用组件。
-
-## 前端 API 规范
-
-- API 请求严格使用 OpenAPI 生成的方法，禁止手写请求或直接拼接路径。
-- 接口变更后先更新 OpenAPI 定义并重新生成 API 代码，再进行业务开发。
-
-## 依赖与构建
-
-- 依赖安装统一 `pnpm`，禁止 `npm install`/`yarn install`。
-- 写完代码先 `npm run format`，再 `npm run build`，构建通过才可发版。
-- AI 改完代码后禁止自动执行任何格式化命令（包括但不限于 `npm run format`、`pnpm run format`、`prettier`、`eslint --fix` 等），避免产生仅含格式差异的文件变更，防止 PR 中混入大量与业务逻辑无关的格式化 diff；仅在用户明确要求格式化时才执行格式化操作。
-
-## 测试
-
-- 测试描述、断言使用中文，覆盖中文场景；充值类测试默认用充值 1 的数据。
-- 用户明确要求由代理自行执行自动化测试时，允许使用无头浏览器进行测试与验证。
-- 写完业务后执行 `pnpm run test:e2e:ui`，告知开发者对应测试用例名称；通过后打开 UI 供手动验证。
-- 端口被占用时自动切换新端口。
-- 自动化测试中，若 Mock 数据不影响业务逻辑验证，优先使用 Mock 数据代替真实接口调用，减少外部依赖和测试不稳定性。
-- ⚠️ **测试用例编写顺序：必须先写主流程，再写边界情况**。主流程（happy path）是最重要的，必须优先覆盖并确保通过；边界情况（异常输入、空值、超时、并发竞态等）重要性相对较低，在主流程全部覆盖完毕后再补充。禁止主流程还没写完就去写边界情况测试，也禁止因为花太多时间在边界情况上而遗漏主流程覆盖。
-- ⚠️ **测试用例必须模拟真实用户的操作流程，禁止只写「XX 可见」类表面检查**。测试用例清单中的每一条主流程用例，必须以真实用户的操作路径来编写：打开页面 → 查看初始状态 → 点击按钮/填写表单 → 提交/保存 → 验证结果页面是否正确展示。核心覆盖场景必须包括：
-  - **新建**：从入口进入 → 填写表单 → 提交 → 在列表/详情页验证新建数据是否正确显示，截图每步关键状态。
-  - **编辑**：从列表/详情进入编辑 → 修改字段 → 保存 → 验证修改后的数据在页面上是否正确回显，截图前后对比。
-  - **删除**：触发删除 → 确认弹窗 → 确认后验证列表/页面中该数据已消失，截图删除前列表和删除后列表对比。
-  - **查看/搜索**：进入列表页 → 使用搜索/筛选 → 验证搜索结果是否符合筛选条件，截图搜索结果。
-  - **状态流转**：如果业务有状态变更（如审核、启用/禁用、支付等），必须覆盖每个状态流转的操作和页面反馈，截图每个状态下的页面展示。
-  - **异常操作**：空表单提交、超长文本输入、非法字符、重复提交等用户可能触发的异常场景，截图错误提示和页面状态。
-- ⚠️ **每一条测试用例必须附带对应步骤的截图，缺一不可**。测试用例清单中每条用例必须写出预期要截哪些图（如「截图1：新建表单填写完成」「截图2：提交成功后列表页新数据出现」），实际执行时每张截图都必须产出并嵌入 HTML 报告。禁止只写操作步骤而不产出对应截图，禁止用「已验证通过」等文字描述代替截图。
-
-## 错误日志
-
-- 用 `console.error` 记录错误（含函数名/模块名上下文），禁止 `console.log` 输出错误。
-- 提交前移除调试日志和临时代码。
-- 调试过程中产生的中间产物（临时文件、测试脚本、调试截图、dump 文件、临时注释、`console.log` 等）禁止加入 Git 提交，`.gitignore` 中应配置忽略常见中间产物。
-
-## Modal 内 Tooltip 规范
-
-在 Modal/弹窗内实现 tooltip 时，必须遵守以下规则，避免被 Modal 容器裁剪和消失太快两个问题。
-
-### 1. Tooltip 必须用 Portal 渲染到 document.body
-
-**问题**：Modal 容器通常有 `overflow: hidden` 或 `overflow-y: auto`，用 CSS `position: absolute/fixed` 的 tooltip 会被裁掉。
-
-**解决**：用 React Portal（`createPortal`）把 tooltip 气泡渲染到 `document.body`，完全绕开 Modal 的 overflow 裁剪。
-
-- 用 `getBoundingClientRect()` 获取触发元素（`?` 图标）的屏幕坐标
-- 气泡用 `position: fixed` + `transform: translate(...)` 精确定位在触发元素上方
-- `z-index` 至少 10000，确保在所有弹窗层之上
-
-### 2. 延迟隐藏 + 气泡可 hover
-
-**问题**：鼠标离开触发元素时 tooltip 立即消失，用户来不及把鼠标移到气泡上阅读内容。
-
-**解决**：
-- 隐藏加 200ms 延迟（`setTimeout`），给用户反应时间
-- 气泡本身绑定 `onMouseEnter`（取消隐藏定时器）和 `onMouseLeave`（触发同样的延迟隐藏）
-- CSS 上气泡容器必须 `pointer-events: auto`（不能是 `none`），否则鼠标事件不触发
-
-### 3. 参考实现
-
-实现一个可复用的 `FieldTooltip` 组件，核心结构：
-
-```tsx
-import { createPortal } from 'react-dom';
-
-function FieldTooltip({ text }: { text: string }) {
-  const iconRef = useRef<HTMLSpanElement>(null);
-  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const [visible, setVisible] = useState(false);
-  const [pos, setPos] = useState({ top: 0, left: 0 });
-
-  // show() → 取消定时器 → getBoundingClientRect 更新坐标 → setVisible(true)
-  // hide() → 200ms setTimeout → setVisible(false)
-  // clearHideTimer() → clearTimeout
-
-  // ? 图标: onMouseEnter={show}  onMouseLeave={hide}
-  // Portal 气泡: onMouseEnter={clearHideTimer}  onMouseLeave={hide}
-  //              position: fixed, z-index: 10000, pointer-events: auto
-}
-```
-
-- 禁止在 Modal 内用纯 CSS `position: absolute` 的 hover tooltip
-- 写完 tooltip 后必须实际验证：弹窗内滚动时气泡不被裁剪，鼠标能从图标移到气泡上阅读
+<!-- 前端特有规则在此添加 -->
 
 <!-- @domain: 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 独立定义这些字段导致类型不一致。
-
-## 数据库 Auto-Migrate 规范
+## Go 后端规则
 
-- ⚠️ **禁止在代码中无条件执行 GORM AutoMigrate**。AutoMigrate 的执行必须由一个显式的开关（如配置项、环境变量或 feature flag）控制，默认关闭。
-- 应用启动时，如果检测到数据库 schema 与 Model 定义不匹配且 auto-migrate 开关未开启，必须：
-  1. **明确报错并拒绝启动**，在日志中输出具体的 schema 差异信息（哪些表/字段缺失或不匹配）。
-  2. **提示运维手动开启 auto-migrate 开关**，给出开关名称和开启方式（例如「请将配置 `DB_AUTO_MIGRATE` 设为 `true` 后重新部署」），禁止静默挂掉或输出含糊错误。
-- auto-migrate 脚本必须随代码一起提交并部署（满足「部署自包含」要求），只是执行时机由开关控制，确保运维可审计、可控制。
-- 生产环境 auto-migrate 执行完毕后，建议运维立即关闭开关并重新部署，避免后续非预期的 DDL 操作。
+<!-- Go 后端特有规则在此添加 -->
 
 <!-- @domain: devops -->
 
 ## 部署规则
 
-- 部署方式因项目而异，具体部署规则请在项目 `AGENTS.private.md` 中按需定义。
-- `.env` 文件中仅允许配置端口号（如 `PORT`、`API_PORT` 等），其余所有配置项（API 地址、数据库连接、第三方服务地址等）必须直接写死到代码中。
-- 密钥、Token、密码、证书等敏感信息不得写入 `.env` 或代码中，必须统一配置到 Nacos 配置中心，应用启动时从 Nacos 拉取。
-- 用户说「部署测试环境」时，必须按以下步骤执行：
-  1. **记录当前分支**：在切分支之前，先记录当前所在的功能分支名称（`git branch --show-current`），后续步骤需要用它切回来。
-  2. **test 分支检查**：如果当前项目的 `test` 分支不存在，从主分支（`main` 或 `master`）创建 `test` 分支并推送到远程。
-  3. **合并当前分支到 test**：将当前功能分支合并到 `test` 分支。
-  4. ⚠️ **推送 test 分支到远程**：合并完成后，必须立即将 `test` 分支推送到远程仓库（`git push origin test`），确保团队其他成员能看到 test 分支上的最新代码，避免远程 test 分支落后于本地。
-  5. **部署 test 分支**：按当前项目自己的部署方式部署 `test` 分支（如 Cloud Run 部署、容器部署、npm publish 等）。
-  6. **发新版本**：按当前项目自己的发版规则发布新版本（如 `./release.sh`、自动递增版本号等）。
-  7. ⚠️ **切回原功能分支**：部署和发版全部完成后，必须立即切回步骤 1 记录的原功能分支（`git checkout <原分支名>`），确保 VS Code 当前所在的 Git 分支恢复到部署前的功能分支，而不是停留在 `test` 分支。如果忘记切回，用户后续的开发工作会在 `test` 分支上进行，违反「禁止直接在 test 分支上提交代码」的规则。
-	- ⚠️ **部署必须自包含，禁止部署后人工补操作**：后端代码写完并部署时，所有依赖该代码的准备工作必须一并完成并通过自动化方式执行，不允许部署完成后再由人工手动执行命令补救。常见必须自动化的事项包括：
-	  - **数据库 migration**：涉及 schema 变更（新增表、字段、索引、约束等）时，必须同时编写 migration 脚本，并集成到部署流程中自动执行（如应用启动时自动 migrate、CI/CD 中跑 migrate 命令等），禁止部署后人工登数据库手动执行 DDL。
-	  - **数据迁移/回填脚本**：涉及存量数据清洗、转换、回填时，脚本必须随代码一起提交，并在部署流程中自动执行或在 PR 中明确写出执行计划。
-	  - **配置变更**：涉及 Nacos 配置中心新增/修改配置项时，配置变更必须与代码部署同步完成，并在部署流程中自动同步或通过配置管理工具批量推送。
-	  - **依赖更新**：涉及新的系统依赖（如新的中间件、新的外部服务地址、新的环境变量等）时，必须在部署脚本中自动检查依赖可用性，不存在时部署失败并明确报错，禁止静默跳过等人工发现。
-	  - **缓存/队列/索引重建**：涉及 Redis 缓存结构变更、消息队列 topic 新增、ES 索引 mapping 变更等，必须脚本化并自动执行。
-	  - 以上所有自动化脚本必须在 PR 的 Test Plan 中明确写出执行时机（部署前/部署中/部署后）、执行方式和验证方法，不得只写"部署后手动执行"。
-
-## GCLB 规范
-
-- ⚠️ **禁止修改 GCLB（Google Cloud Load Balancer）配置**。任何情况下不得新增、修改或删除 GCLB 相关配置，包括但不限于转发规则、后端服务、健康检查、SSL 证书、URL 映射等。
+<!-- 部署特有规则在此添加 -->