Immutable. This exact content is served forever at /api/v1/blob/822a894918081983.
---
name: rab-cdp-debug
description: 用于指导 Agent 通过 Chrome DevTools MCP 的 `evaluate_script` 工具，结合 `window.__RS_ROOT_CONTAINER__` API 对 `@rabjs/react` 应用进行逻辑验证。当用户提到 Service 逻辑验证、Chrome DevTools 调试 Service、CDP 操控 rsjs Service、浏览器页面中调试 Service 实例 时，应优先使用这个 skill。适用场景包括：使用 chrome-devtools-mcp 的 evaluate_script 访问 Service 实例、验证 Service 状态、调用 Service 方法、通过 listServices 枚举当前页面所有 Service。
version: 0.2.10-beta.0
npm: '@rabjs/devtools'
sourcePath: packages/react
repository: git@github.com:ximing/rab.git
---
# window.__RS_ROOT_CONTAINER__ 调试指南（Chrome DevTools MCP）
本 skill 告知 Agent 如何通过 **Chrome DevTools MCP** 的 `evaluate_script` 工具，利用 `@rabjs/devtools` 挂载的 `window.__RS_ROOT_CONTAINER__` 能力，对 Service 层进行功能验证与状态检查。
---
## 前置条件：初始化挂载
`window.__RS_ROOT_CONTAINER__` **不会自动挂载**，必须由应用入口显式初始化。
1. 安装依赖：
```bash
pnpm add @rabjs/devtools
```
2. 在应用入口（如 `main.tsx`）调用一次：
```ts
import { setupWindowRootContainer } from '@rabjs/devtools';
setupWindowRootContainer();
```
如果目标页面尚未接入，先引导用户完成上述初始化步骤，再进行后续调试。SSR 安全：非浏览器环境下调用会自动跳过。
---
## 能力概述
`window.__RS_ROOT_CONTAINER__` 是 `setupWindowRootContainer()` 在浏览器环境下挂载的全局访问句柄，暴露整棵容器树的查询接口。
**挂载时机**：应用入口调用 `setupWindowRootContainer()` 时。
### 容器树结构
```
global (getGlobalContainer()) ← 真正的根，与 React 无关
└─ RSRootInner_1 ← RSRoot 的 bindServices 容器
└─ ProductPage_2 ← 页面级 bindServices 容器
└─ CartDomain_3 ← Domain 级 bindServices 容器
```
### RSRootContainerHandle 接口
```ts
interface RSRootContainerHandle {
container: Container; // global 容器实例
getService(instanceId: string): Service | undefined;
getContainer(containerName: string): Container | undefined;
listServices(): Array<{
instanceId: string; // 格式: ClassName_nanoid
containerName: string; // 来自 bindServices options.name 或自动生成
identifierLabel: string; // Service 类名
instance: Service; // 内存对象引用，可直接操控
}>;
}
```
---
## evaluate_script 工具使用说明
Chrome DevTools MCP 提供 `evaluate_script` 工具，可在当前选中页面内执行 JavaScript 函数，**返回值必须是 JSON 可序列化的**。
```
function (string) (required): JavaScript 函数声明
示例无参数: () => { return document.title }
示例有参数: (el) => { return el.innerText; }
args (array) (optional): 传入函数的参数列表
```
> **关键约束**：Service 实例本身不可序列化跨进程传递，必须在 `evaluate_script` 内部完成操作，只将基础类型（数字、字符串、布尔、普通对象）作为结果返回。
---
## 常用调试操作
### 1. 检查 handle 是否已挂载
```js
() => {
return typeof window.__RS_ROOT_CONTAINER__;
}
// 期望返回: "object"
```
### 2. 列出所有已实例化的 Service
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '__RS_ROOT_CONTAINER__ 未挂载' };
return handle.listServices().map(s => ({
instanceId: s.instanceId,
containerName: s.containerName,
identifierLabel: s.identifierLabel,
}));
}
```
返回示例：
```json
[
{ "instanceId": "CartService_abc12", "containerName": "ProductPage_2", "identifierLabel": "CartService" },
{ "instanceId": "UserService_xyz99", "containerName": "RSRootInner_1", "identifierLabel": "UserService" }
]
```
### 3. 通过 instanceId 获取 Service 状态
先通过 `listServices` 获得 `instanceId`，再读取 Service 内部状态：
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '__RS_ROOT_CONTAINER__ 未挂载' };
const svc = handle.getService('CartService_abc12');
if (!svc) return { error: '未找到指定 Service' };
// 返回可序列化的状态字段
return {
itemCount: svc.items?.length ?? 0,
total: svc.total,
};
}
```
### 4. 通过 identifierLabel 查找 Service
当不知道具体 `instanceId` 时，先通过类名找到：
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return null;
const entry = handle.listServices().find(s => s.identifierLabel === 'CartService');
if (!entry) return { error: 'CartService 未找到' };
return {
instanceId: entry.instanceId,
containerName: entry.containerName,
};
}
```
### 5. 调用 Service 方法并验证结果
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '__RS_ROOT_CONTAINER__ 未挂载' };
const entry = handle.listServices().find(s => s.identifierLabel === 'CartService');
if (!entry) return { error: 'CartService 未找到' };
const svc = entry.instance;
// 调用方法
svc.addItem({ id: 'test-1', name: 'Test Product', price: 9.9 });
// 返回可序列化的验证结果
return {
itemCount: svc.items.length,
lastItem: svc.items[svc.items.length - 1],
};
}
```
### 6. 调用异步 Service 方法
```js
async () => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '__RS_ROOT_CONTAINER__ 未挂载' };
const entry = handle.listServices().find(s => s.identifierLabel === 'ProductService');
if (!entry) return { error: 'ProductService 未找到' };
const svc = entry.instance;
await svc.fetchProducts();
return {
productCount: svc.products.length,
loadingState: svc.loadingState,
};
}
```
### 7. 通过 containerName 查找特定容器内的 Service
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return null;
return handle.listServices()
.filter(s => s.containerName === 'ProductPage_2')
.map(s => ({ instanceId: s.instanceId, identifierLabel: s.identifierLabel }));
}
```
### 8. 重置 Service 状态（验证后清理）
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '__RS_ROOT_CONTAINER__ 未挂载' };
const entry = handle.listServices().find(s => s.identifierLabel === 'CartService');
if (!entry) return { error: '未找到' };
entry.instance.clearCart?.();
return { cleared: true, itemCount: entry.instance.items?.length ?? 0 };
}
```
---
## 典型验证流程
**Step 1**：确认 handle 存在
```js
() => typeof window.__RS_ROOT_CONTAINER__
// 期望: "object"
```
**Step 2**：枚举所有 Service，找到目标
```js
() => window.__RS_ROOT_CONTAINER__?.listServices().map(s => ({
instanceId: s.instanceId,
identifierLabel: s.identifierLabel,
containerName: s.containerName,
}))
```
**Step 3**：取出 Service 当前状态快照
```js
() => {
const svc = window.__RS_ROOT_CONTAINER__?.getService('CartService_abc12');
return svc ? { total: svc.total, count: svc.items.length } : null;
}
```
**Step 4**：触发操作
```js
() => {
const entry = window.__RS_ROOT_CONTAINER__?.listServices().find(s => s.identifierLabel === 'CartService');
entry?.instance.addItem({ id: '1', name: 'Apple', price: 5 });
return { ok: true };
}
```
**Step 5**：验证状态变更
```js
() => {
const svc = window.__RS_ROOT_CONTAINER__?.getService('CartService_abc12');
return { total: svc?.total, count: svc?.items.length };
}
```
---
## 断言用法
`@rabjs/devtools` 提供了 **RSExpectBuilder** 链式断言 API，可以直接通过 `window.__RS_ROOT_CONTAINER__.expect(instanceId)` 创建，也可以通过独立函数 `rsExpect(instance)` 使用。
### 核心概念
- **懒执行**：`toBe()` / `toExist()` 等方法只记录断言，不立即执行
- **链式调用**：所有断言方法返回 `this`，可无限链式调用
- **三种执行模式**：
- `.run()` — 返回结构化结果对象，不抛错
- `.check()` — 控制台输出彩色报告，返回 `boolean`
- `.expect()` — 失败时抛出 `RSAssertionError`（类 Jest 语义）
### 路径语法
所有断言方法的 `path` 参数支持点号路径，用于深层属性访问：
```
'total' → svc.total
'items.length' → svc.items.length
'user.profile.name' → svc.user.profile.name
```
---
### 断言方法速查表
| 方法 | 说明 | op |
|------|------|-----|
| `.toBe(path, expected)` | `actual === expected` | `eq` |
| `.notToBe(path, expected)` | `actual !== expected` | `neq` |
| `.toBeGreaterThan(path, n)` | `actual > n` | `gt` |
| `.toBeGreaterThanOrEqual(path, n)` | `actual >= n` | `gte` |
| `.toBeLessThan(path, n)` | `actual < n` | `lt` |
| `.toBeLessThanOrEqual(path, n)` | `actual <= n` | `lte` |
| `.toBeBetween(path, lo, hi)` | `lo <= actual <= hi` | `between` |
| `.toExist(path)` | `actual != null` | `exists` |
| `.toNotExist(path)` | `actual == null` | `notExists` |
| `.toInclude(path, item)` | 数组/字符串包含 | `includes` |
| `.toNotInclude(path, item)` | 数组/字符串不包含 | `notIncludes` |
| `.toMatch(path, pattern)` | 正则匹配 | `matches` |
| `.toBeType(path, type)` | `typeof actual === type` | `type` |
| `.toHaveLength(path, n)` | `actual.length === n` | `length` |
| `.toHaveLengthGt(path, n)` | `actual.length > n` | `lengthGt` |
| `.toHaveLengthGte(path, n)` | `actual.length >= n` | `lengthGte` |
| `.toHaveLengthLt(path, n)` | `actual.length < n` | `lengthLt` |
| `.toHaveLengthLte(path, n)` | `actual.length <= n` | `lengthLte` |
| `.toHaveKeys(path, keys)` | 对象包含所有指定 key | `hasKeys` |
| `.toMatchObject(path, subset)` | 对象浅层匹配子集 | `matchObject` |
| `.toDeepEqual(path, expected)` | JSON 深比较 | `deepEq` |
| `.toHaveSome(path, assertion)` | 数组中至少一项满足 | `some` |
| `.toHaveEvery(path, assertion)` | 数组所有项满足 | `every` |
---
### 基本示例：控制台调试（`.check()`）
控制台快速验证，带彩色报告输出，返回 `boolean`：
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '未挂载' };
return handle
.expect('CartService_abc123')
.describe('购物车基础验证')
.toBe('items.length', 3)
.toExist('currentUser')
.toBeGreaterThan('total', 0)
.check(); // 控制台输出报告，返回 true/false
}
```
> **注意**：`.check()` 直接向控制台打印，`evaluate_script` 只需返回布尔值即可。
---
### 获取结构化结果（`.run()`）
`.run()` 返回可 JSON 序列化的结构化结果，适合 evaluate_script 跨进程传递：
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '未挂载' };
const result = handle
.expect('CartService_abc123')
.toBe('items.length', 3)
.toBeGreaterThan('total', 0)
.toExist('currentUser')
.run();
// 返回可序列化的结构化断言结果
return {
passed: result.passed,
summary: result.summary, // { passed: 2, total: 3 }
results: result.results.map(r => ({
path: r.path,
op: r.op,
passed: r.passed,
expected: r.expected,
actual: r.actual,
})),
};
}
```
返回示例：
```json
{
"passed": false,
"summary": { "passed": 2, "total": 3 },
"results": [
{ "path": "items.length", "op": "eq", "passed": true, "expected": 3, "actual": 3 },
{ "path": "total", "op": "gt", "passed": true, "expected": 0, "actual": 29.7 },
{ "path": "currentUser", "op": "exists", "passed": false, "expected": null, "actual": null }
]
}
```
---
### 强断言模式（`.expect()`，类 Jest 语义）
失败时抛出 `RSAssertionError`，适合 E2E 测试脚本：
```js
async () => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) throw new Error('未挂载');
try {
handle
.expect('CartService_abc123')
.toBe('items.length', 3)
.toExist('currentUser')
.expect(); // 失败时抛出 RSAssertionError
return { passed: true };
} catch (e) {
return { passed: false, message: e.message };
}
}
```
---
### 各类断言示例
#### 相等与不等
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('UserService_xyz99')
.toBe('loginState', 'logged_in') // 精确相等
.notToBe('errorCode', 403) // 不等于
.check();
}
```
#### 数值比较
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('CartService_abc123')
.toBeGreaterThan('total', 0) // > 0
.toBeGreaterThanOrEqual('items.length', 1) // >= 1
.toBeLessThan('items.length', 100) // < 100
.toBeBetween('total', 10, 500) // 10 <= total <= 500
.check();
}
```
#### 存在性检查
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('UserService_xyz99')
.toExist('currentUser') // 不为 null/undefined
.toExist('currentUser.token') // 深层路径存在性
.toNotExist('errorMessage') // 为 null/undefined
.check();
}
```
#### 数组与字符串包含
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('ProductService_p001')
.toInclude('tags', 'featured') // 数组包含元素
.toNotInclude('disabledFeatures', 'checkout') // 数组不包含
.toInclude('title', 'iPhone') // 字符串包含子串
.check();
}
```
#### 正则匹配
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('UserService_xyz99')
.toMatch('email', '^\\w+@\\w+\\.\\w+$') // 正则匹配 email 格式
.toMatch('phone', '^\\+?[0-9]{7,15}$')
.check();
}
```
#### 类型检查
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('CartService_abc123')
.toBeType('total', 'number') // typeof total === 'number'
.toBeType('items', 'object') // typeof items === 'object'（数组也是 object）
.toBeType('isLoading', 'boolean')
.check();
}
```
#### 长度断言
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('CartService_abc123')
.toHaveLength('items', 3) // 精确长度
.toHaveLengthGt('items', 0) // 非空
.toHaveLengthLte('items', 10) // 不超过 10
.check();
}
```
#### 对象键与子集匹配
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('UserService_xyz99')
.toHaveKeys('currentUser', ['id', 'name', 'email']) // 包含所有指定 key
.toMatchObject('currentUser', { role: 'admin', active: true }) // 浅层子集
.toDeepEqual('config', { theme: 'dark', lang: 'zh' }) // 深比较
.check();
}
```
#### 数组元素断言（some / every）
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('CartService_abc123')
// 至少一个商品价格 > 100
.toHaveSome('items', { path: 'price', op: 'gt', expected: 100 })
// 所有商品数量 >= 1
.toHaveEvery('items', { path: 'quantity', op: 'gte', expected: 1 })
.check();
}
```
#### 带自定义错误信息
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
return handle
.expect('CartService_abc123')
.toBe('items.length', 3, '购物车应有 3 个商品')
.toExist('currentUser', '用户未登录')
.check();
}
```
---
### 独立使用 `rsExpect(instance)`
脱离 `window` 挂载，直接传入 Service 实例，适合 E2E 测试框架或 Node.js 环境：
```js
// E2E 测试脚本中
import { rsExpect } from '@rabjs/devtools';
// 直接传 Service 实例
rsExpect(cartService, '购物车加购验证')
.toBe('items.length', 1)
.toBe('items.0.name', 'iPhone 15')
.toBeGreaterThan('total', 0)
.expect(); // 失败时抛出 RSAssertionError
```
在 evaluate_script 中组合使用（先取实例，再建立断言）：
```js
() => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '未挂载' };
// 通过类名找到 Service 实例
const entry = handle.listServices().find(s => s.identifierLabel === 'CartService');
if (!entry) return { error: 'CartService 未找到' };
// 直接对实例进行断言（等价于 handle.expect(instanceId)）
const result = handle
.expect(entry.instanceId)
.describe('加购后状态验证')
.toHaveLength('items', 1)
.toBeGreaterThan('total', 0)
.run();
return { passed: result.passed, summary: result.summary };
}
```
---
### 断言 + 操作组合流程
先操作 Service，再断言状态变更：
```js
async () => {
const handle = window.__RS_ROOT_CONTAINER__;
if (!handle) return { error: '未挂载' };
const entry = handle.listServices().find(s => s.identifierLabel === 'CartService');
if (!entry) return { error: 'CartService 未找到' };
// 1. 记录操作前状态
const before = handle
.expect(entry.instanceId)
.toBe('items.length', 0)
.run();
// 2. 触发操作
await entry.instance.addItem({ id: 'test-1', name: 'Test Product', price: 9.9 });
// 3. 断言操作后状态
const after = handle
.expect(entry.instanceId)
.toBe('items.length', 1)
.toBeGreaterThan('total', 0)
.run();
return {
before: { passed: before.passed, summary: before.summary },
after: { passed: after.passed, summary: after.summary },
};
}
```
---
## 常见问题
### `window.__RS_ROOT_CONTAINER__` 为 undefined？
- 页面未完成加载，稍等后重试
### `getService` 找不到 Service？
- 只有调用 `resolve` 后被实例化的 Singleton 才会出现
- 先用 `listServices()` 确认实例是否已存在及其 `instanceId`
### evaluate_script 返回值为 undefined / 不完整？
- 返回值必须是 JSON 可序列化的类型（基础类型、普通对象、数组）
- Service 实例不可直接返回，需提取其中的状态字段
- 避免返回含循环引用的对象