@routerhub/agent-rules 1.5.80 → 1.5.81

package/AGENTS.base.md

@@ -124,14 +124,144 @@ Closes #456
 
 - 新需求先在 `docs/` 写文档，含：目标、范围、功能要求、验收标准。
 
-## ⚠️ Superpowers 需求开发流程（强制）
+## ⚠️ 回归测试体系与 TDD 开发流程（强制）
 
-- ⚠️ **每一个新需求、每一次改动，必须严格按以下 Superpowers 流程执行，不可跳过任何步骤：**
-  1. **确定设计文档**：在写任何代码之前，必须先明确当前改动归属哪个设计文档（`docs/` 目录下的 HTML 文档）。如该文档不存在，必须先创建设计文档，含目标、范围、功能要求、验收标准。
-  2. **准备测试用例**：设计文档确定后，必须先准备测试用例，明确要测什么、怎么测、预期结果是什么。
-  3. **开始写代码**：前两步完成后，才能开始编写代码实现。
-  4. **发新版本**：代码完成并通过测试后，执行 `./release.sh` 发版。
-- ⚠️ **禁止跳过设计文档和测试用例直接写代码。** 没有设计文档和测试用例的改动不得开始编码。
+### 一、回归测试入口
+
+本项目的回归测试通过回归测试中心执行，入口为 `上线回归测试点.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 步：跑基线回归（改动前）
+
+- ⚠️ **改代码之前，必须先跑一次全量回归，建立基线**
+- 确认改动前所有已有用例全部通过，拿到基线报告
+- 如果已有失败用例，先排查是环境问题还是已有 bug，记录在案
+
+#### 第 5 步：实现业务代码
+
+- 按需求文档和测试用例实现功能
+- 实现过程中持续跑新增的测试用例，确保新功能正确
+
+#### 第 6 步：跑全量回归（改动后）
+
+- ⚠️ **改完代码后，必须跑全量回归**
+- 确认：新增用例全部通过 + 所有已有用例仍然通过
+- 如果全量回归有失败：
+  - 改动导致的 → 修代码，重新跑
+  - 环境问题 → 记录在回归报告中
+  - 已有用例本身的问题 → 修复用例或更新断言
+- **全量回归全部通过 = 新功能正确 + 已有功能不被破坏**
+
+#### 第 7 步：上线前回归
+
+- ⚠️ **每次部署生产前，必须跑 `node 上线回归测试点.js`**
+- 这是上线前最后一道防线，确保生产环境不会出问题
+
+### 四、测试用例注册规范
+
+在 `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,
+},
+
+// 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"),
+},
+
+// 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"),
+},
+```
+
+### 五、留痕机制
+
+- 每个需求必须在 `docs/` 下留下需求文档（HTML 格式，中文文件名）
+- 每个需求的测试用例必须在回归中心注册，用例名称包含需求关键词
+- 全量回归报告（HTML）自动生成到 `docs/evidence/visual-acceptance/report.html`，可作为交付证据
+- 如果之前的记录（需求文档、测试用例）与实际情况不符，必须**立即更新**，不留过期文档
+- ⚠️ **每次会话的改动必须有迹可循**：需求文档 → 测试用例 → 回归报告 → 代码改动，四者一一对应
+
+### 六、外部 Coding 的含义
+
+上述流程的本质是**外部化编码（External Coding）**：
+
+- 代码的正确性不是靠"我觉得没问题"来判断的，而是靠**外部可观察的测试结果**来验证的
+- 每一次改动，都有一套完整的、可复现的回归用例作为安全网
+- 新增功能的验收标准在写代码之前就以测试用例的形式固化下来
+- 任何人在任何时候跑全量回归，都能立即知道系统当前的健康状态
+- 代码不再是黑盒，而是被测试用例从外部锁定的、可验证的产物
+
+### 七、AI 助手的职责
+
+作为 AI 开发助手，每次接收需求时必须：
+
+1. **第一反应不是写代码，而是确认归属版本 + 写需求文档 + 设计测试用例**
+2. 在实现代码之前，先在回归中心注册测试用例
+3. 代码写完后，必须跑全量回归并出示报告
+4. 交付时必须说明：新增了哪些测试用例、归属于哪个版本/全量测试、全量回归结果
+5. 如果用户说"直接改就行不用测试"，必须提醒用户测试是安全网，建议至少跑新增用例
 
 ## 文档格式
 
@@ -146,14 +276,6 @@ Closes #456
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
 - ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
-## 新需求与回归测试准入
-
-- 每个新需求必须同步新增或更新可自动化回归用例；仅纯文案、纯文档或无可自动化行为的改动可例外，但交付时必须说明无需新增用例的原因与人工验证方式。
-- 新增或更新的测试用例必须接入项目回归测试中心的可运行范围：用户明确说明当前版本号或版本名称时，归档到对应版本测试范围；用户未说明版本时，归档到全量测试，确保“全量测试”会执行或展示该用例。
-- 使用 Superpowers 或其他代理流程处理需求时，测试设计是交付的一部分；需求文档、实现计划、代码改动与测试接入必须同步考虑，禁止只完成业务代码而遗漏全量或版本回归用例。
-- 交付说明必须列出新增或更新的测试用例名称、所在文件、归属范围（版本或全量）以及已执行的测试命令与结果。
-- 用户未明确豁免时，默认按 Superpowers 等价流程执行新需求交付；每次需求都必须新增或更新至少一个可自动化回归用例，并接入“全量测试”范围。
-
 ## Superpowers 安装与缺失处理
 
 - 团队统一推荐使用 Superpowers 插件或同等技能流程处理新需求、调试、计划、测试驱动开发和完成前验证。
@@ -161,13 +283,6 @@ Closes #456
 - 用户暂不安装或当前环境无法安装时，不得因此中断任务；必须按本规则中的等价流程继续执行，包括需求文档、实现计划、测试准入、代码实现和完成前验证。
 - 不得把某一台电脑已安装 Superpowers 当作团队默认事实；交付说明中应明确本次是使用 Superpowers 流程，还是按 AGENTS 规则执行了等价流程。
 
-## 新需求与回归测试准入
-
-- 每个新需求必须同步新增或更新可自动化回归用例；仅纯文案、纯文档或无可自动化行为的改动可例外，但交付时必须说明无需新增用例的原因与人工验证方式。
-- 新增或更新的测试用例必须接入项目回归测试中心的可运行范围：用户明确说明当前版本号或版本名称时，归档到对应版本测试范围；用户未说明版本时，归档到全量测试，确保“全量测试”会执行或展示该用例。
-- 使用 Superpowers 或其他代理流程处理需求时，测试设计是交付的一部分；需求文档、实现计划、代码改动与测试接入必须同步考虑，禁止只完成业务代码而遗漏全量或版本回归用例。
-- 交付说明必须列出新增或更新的测试用例名称、所在文件、归属范围（版本或全量）以及已执行的测试命令与结果。
-
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）
@@ -187,11 +302,11 @@ Closes #456
 - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
 - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
 
-## 外部文档查看（Notion / 需登录页面）
+## 外部文档查看/浏览器控制（agent-browser）
 
-- 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
-- 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
-- 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。
+- ⚠️ **浏览器控制以个人全局 `CLAUDE.md`（`~/.claude/CLAUDE.md`）为准，本文件不再重复定义端口、Profile、启动流程等配置。**
+- 团队开发者在自己的全局 `CLAUDE.md` 中配置 agent-browser + Chrome CDP 环境（端口、Profile 目录等）。
+- 基本约定：所有需要登录态的页面必须使用 `agent-browser --cdp <端口>` 连接已登录 Chrome，禁止 WebFetch / 无状态模式。
 
 <!-- @domain: frontend -->
 

package/package.json

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

package/rules/global.md

@@ -126,14 +126,144 @@ Closes #456
 
 - 新需求先在 `docs/` 写文档，含：目标、范围、功能要求、验收标准。
 
-## ⚠️ Superpowers 需求开发流程（强制）
+## ⚠️ 回归测试体系与 TDD 开发流程（强制）
 
-- ⚠️ **每一个新需求、每一次改动，必须严格按以下 Superpowers 流程执行，不可跳过任何步骤：**
-  1. **确定设计文档**：在写任何代码之前，必须先明确当前改动归属哪个设计文档（`docs/` 目录下的 HTML 文档）。如该文档不存在，必须先创建设计文档，含目标、范围、功能要求、验收标准。
-  2. **准备测试用例**：设计文档确定后，必须先准备测试用例，明确要测什么、怎么测、预期结果是什么。
-  3. **开始写代码**：前两步完成后，才能开始编写代码实现。
-  4. **发新版本**：代码完成并通过测试后，执行 `./release.sh` 发版。
-- ⚠️ **禁止跳过设计文档和测试用例直接写代码。** 没有设计文档和测试用例的改动不得开始编码。
+### 一、回归测试入口
+
+本项目的回归测试通过回归测试中心执行，入口为 `上线回归测试点.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 步：跑基线回归（改动前）
+
+- ⚠️ **改代码之前，必须先跑一次全量回归，建立基线**
+- 确认改动前所有已有用例全部通过，拿到基线报告
+- 如果已有失败用例，先排查是环境问题还是已有 bug，记录在案
+
+#### 第 5 步：实现业务代码
+
+- 按需求文档和测试用例实现功能
+- 实现过程中持续跑新增的测试用例，确保新功能正确
+
+#### 第 6 步：跑全量回归（改动后）
+
+- ⚠️ **改完代码后，必须跑全量回归**
+- 确认：新增用例全部通过 + 所有已有用例仍然通过
+- 如果全量回归有失败：
+  - 改动导致的 → 修代码，重新跑
+  - 环境问题 → 记录在回归报告中
+  - 已有用例本身的问题 → 修复用例或更新断言
+- **全量回归全部通过 = 新功能正确 + 已有功能不被破坏**
+
+#### 第 7 步：上线前回归
+
+- ⚠️ **每次部署生产前，必须跑 `node 上线回归测试点.js`**
+- 这是上线前最后一道防线，确保生产环境不会出问题
+
+### 四、测试用例注册规范
+
+在 `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,
+},
+
+// 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"),
+},
+
+// 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"),
+},
+```
+
+### 五、留痕机制
+
+- 每个需求必须在 `docs/` 下留下需求文档（HTML 格式，中文文件名）
+- 每个需求的测试用例必须在回归中心注册，用例名称包含需求关键词
+- 全量回归报告（HTML）自动生成到 `docs/evidence/visual-acceptance/report.html`，可作为交付证据
+- 如果之前的记录（需求文档、测试用例）与实际情况不符，必须**立即更新**，不留过期文档
+- ⚠️ **每次会话的改动必须有迹可循**：需求文档 → 测试用例 → 回归报告 → 代码改动，四者一一对应
+
+### 六、外部 Coding 的含义
+
+上述流程的本质是**外部化编码（External Coding）**：
+
+- 代码的正确性不是靠"我觉得没问题"来判断的，而是靠**外部可观察的测试结果**来验证的
+- 每一次改动，都有一套完整的、可复现的回归用例作为安全网
+- 新增功能的验收标准在写代码之前就以测试用例的形式固化下来
+- 任何人在任何时候跑全量回归，都能立即知道系统当前的健康状态
+- 代码不再是黑盒，而是被测试用例从外部锁定的、可验证的产物
+
+### 七、AI 助手的职责
+
+作为 AI 开发助手，每次接收需求时必须：
+
+1. **第一反应不是写代码，而是确认归属版本 + 写需求文档 + 设计测试用例**
+2. 在实现代码之前，先在回归中心注册测试用例
+3. 代码写完后，必须跑全量回归并出示报告
+4. 交付时必须说明：新增了哪些测试用例、归属于哪个版本/全量测试、全量回归结果
+5. 如果用户说"直接改就行不用测试"，必须提醒用户测试是安全网，建议至少跑新增用例
 
 ## 文档格式
 
@@ -148,14 +278,6 @@ Closes #456
 - ⚠️ **编写 HTML 报告/文档时，每一段说明文字必须与其对应的截图、图片紧挨着放在一起（同一视觉区域内）**，禁止将说明文字集中放在页面顶部、图片全部堆在底部，导致读者需要上下翻页才能对照阅读。正确做法：每写完一段说明文字后，紧接着就放该段说明对应的图片，形成"说明 → 配图"的紧密组合，然后再写下一段说明和下一张图。
 - ⚠️ **HTML 报告必须以截图为主、文字为辅**：报告的核心内容是截图，文字仅作为截图的简要说明和补充。页面布局上截图应占主导地位（占据大部分版面），文字说明应精简扼要，禁止出现大段文字配少量截图的情况。读者应能通过翻阅截图快速了解全貌，无需阅读大量文字。
 
-## 新需求与回归测试准入
-
-- 每个新需求必须同步新增或更新可自动化回归用例；仅纯文案、纯文档或无可自动化行为的改动可例外，但交付时必须说明无需新增用例的原因与人工验证方式。
-- 新增或更新的测试用例必须接入项目回归测试中心的可运行范围：用户明确说明当前版本号或版本名称时，归档到对应版本测试范围；用户未说明版本时，归档到全量测试，确保“全量测试”会执行或展示该用例。
-- 使用 Superpowers 或其他代理流程处理需求时，测试设计是交付的一部分；需求文档、实现计划、代码改动与测试接入必须同步考虑，禁止只完成业务代码而遗漏全量或版本回归用例。
-- 交付说明必须列出新增或更新的测试用例名称、所在文件、归属范围（版本或全量）以及已执行的测试命令与结果。
-- 用户未明确豁免时，默认按 Superpowers 等价流程执行新需求交付；每次需求都必须新增或更新至少一个可自动化回归用例，并接入“全量测试”范围。
-
 ## Superpowers 安装与缺失处理
 
 - 团队统一推荐使用 Superpowers 插件或同等技能流程处理新需求、调试、计划、测试驱动开发和完成前验证。
@@ -163,13 +285,6 @@ Closes #456
 - 用户暂不安装或当前环境无法安装时，不得因此中断任务；必须按本规则中的等价流程继续执行，包括需求文档、实现计划、测试准入、代码实现和完成前验证。
 - 不得把某一台电脑已安装 Superpowers 当作团队默认事实；交付说明中应明确本次是使用 Superpowers 流程，还是按 AGENTS 规则执行了等价流程。
 
-## 新需求与回归测试准入
-
-- 每个新需求必须同步新增或更新可自动化回归用例；仅纯文案、纯文档或无可自动化行为的改动可例外，但交付时必须说明无需新增用例的原因与人工验证方式。
-- 新增或更新的测试用例必须接入项目回归测试中心的可运行范围：用户明确说明当前版本号或版本名称时，归档到对应版本测试范围；用户未说明版本时，归档到全量测试，确保“全量测试”会执行或展示该用例。
-- 使用 Superpowers 或其他代理流程处理需求时，测试设计是交付的一部分；需求文档、实现计划、代码改动与测试接入必须同步考虑，禁止只完成业务代码而遗漏全量或版本回归用例。
-- 交付说明必须列出新增或更新的测试用例名称、所在文件、归属范围（版本或全量）以及已执行的测试命令与结果。
-
 ## 优先级
 
 1. 项目私有规则（AGENTS.private.md）
@@ -189,8 +304,8 @@ Closes #456
 - 涉及配置、官网或其他系统联动时，需同时打开所有相关页面，并按实际操作路径展示联动结果，方便直接验证。
 - 若客观上无法可视化展示，需说明原因，并补充截图、录屏、日志或请求响应作为替代证据。
 
-## 外部文档查看（Notion / 需登录页面）
+## 外部文档查看/浏览器控制（agent-browser）
 
-- 查看 Notion 文档或其他需要登录态的外部页面时，必须使用 Chrome DevTools MCP（`navigate_page` + `take_snapshot` / `evaluate_script`），禁止使用 WebFetch。WebFetch 无法处理需要登录的页面，会直接报错看不到内容；浏览器 MCP 可复用用户已有的登录态。
-- 页面 snapshot 太大无法直接读取时，用 `evaluate_script` 执行 `document.body.innerText` 或更精准的选择器提取文本内容，再分段读取。
-- 提取到的外部文档内容涉及项目关键规范/数据时，应保存为长期记忆（`memory/` 目录）方便后续引用。
+- ⚠️ **浏览器控制以个人全局 `CLAUDE.md`（`~/.claude/CLAUDE.md`）为准，本文件不再重复定义端口、Profile、启动流程等配置。**
+- 团队开发者在自己的全局 `CLAUDE.md` 中配置 agent-browser + Chrome CDP 环境（端口、Profile 目录等）。
+- 基本约定：所有需要登录态的页面必须使用 `agent-browser --cdp <端口>` 连接已登录 Chrome，禁止 WebFetch / 无状态模式。