inspector-workbench

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Inspector Workbench

Inspector工作台

The Inspector overlay is a visual product. Code that compiles is not proof. The agent must run the standalone workbench and look at screenshots after each visual change.

This skill does not replace

inspector-docs

. If a pane is added, renamed, or removed, load

inspector-docs

as well.

Inspector覆盖层是一款可视化产品。代码编译通过并不代表功能正常。 Agent必须运行独立工作台，并在每次视觉变更后查看截图。

此技能不能替代

inspector-docs

。如果新增、重命名或移除了面板，同时也要加载

inspector-docs

。

When To Use

使用场景

Load this skill at the start of any task that changes

packages/web-inspector

UI, chrome, or overlay behavior.

Do not load it for docs-only Callout work. Do not load it for showcase cells. If the host app is the bug (z-index against host CSS, CopilotChat layout), use that host, then still take screenshots.

在任何修改

packages/web-inspector

UI、浏览器外壳或覆盖层行为的任务开始时，加载此技能。

请勿将其用于仅更新文档说明的Callout工作。请勿用于展示单元。如果问题出在宿主应用（与宿主CSS的z-index冲突、CopilotChat布局问题），请使用该宿主应用，之后仍需截取截图。

Default host

默认宿主

The default host is the standalone Threads state lab:

Command, from the repo root:

nx run @copilotkit/web-inspector:dev:standalone

URL:

http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1

The lab mounts the real
```
cpk-web-inspector
```
and opens the overlay.

Do not start a showcase app, an example app, or Storybook as the default host. Those are slower and hide Inspector-only faults.

The Nx target runs Vite and the CSS watch together. Do not run Vite alone. Do not run

pnpm --filter @copilotkit/web-inspector run dev

. That watch serves consumers, not this lab.

默认宿主是独立的Threads状态实验室：

从仓库根目录执行命令：

nx run @copilotkit/web-inspector:dev:standalone

URL：

http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1

该实验室会挂载真实的
```
cpk-web-inspector
```
并打开覆盖层。

请勿将展示应用、示例应用或Storybook作为默认宿主。这些环境速度更慢，且会隐藏Inspector特有的问题。

Nx目标会同时运行Vite和CSS监听任务。请勿单独运行Vite。请勿执行

pnpm --filter @copilotkit/web-inspector run dev

。该监听服务面向的是消费者，而非本实验室。

Procedures

操作流程

Procedure 1: Start the workbench

流程1：启动工作台

If the change adds, renames, or removes a pane, load
```
inspector-docs
```
too.

From the repo root, start

nx run @copilotkit/web-inspector:dev:standalone

Wait until
```
http://127.0.0.1:5177
```
serves.
Open the browser tool this session has (Playwright MCP, Claude browser, or Codex computer use).

Go to

http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1

If the bug is an empty, locked, error, or unread state, pick that scenario in the lab dropdown, then reload.
Wait until the overlay is open on Home or Threads. The lab clicks the launcher.
Take a baseline screenshot. Look at it before any edit.

如果变更涉及新增、重命名或移除面板，同时加载
```
inspector-docs
```
。

从仓库根目录启动

nx run @copilotkit/web-inspector:dev:standalone

。

等待
```
http://127.0.0.1:5177
```
服务启动完成。
打开本次会话可用的浏览器工具（Playwright MCP、Claude浏览器或Codex计算机工具）。

访问

http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1

。

如果问题是空状态、锁定状态、错误状态或未读状态，请在实验室下拉菜单中选择对应场景，然后重新加载页面。
等待覆盖层在主页或Threads页面打开。实验室会自动点击启动器。
截取基准截图。在进行任何编辑前查看该截图。

Procedure 2: Edit, screenshot, look

流程2：编辑、截图、检查

Edit Inspector source under
```
packages/web-inspector/src
```
.
Wait for Vite to reload the lab.
If the page did not pick up the change, reload the lab URL, then wait for the overlay.
Take a screenshot of the pane that must change.
If the browser tool writes a file, write it under
```
.inspector-workbench/<task>/
```
. Never write a PNG at the repo root.
Look at the screenshot. If the change is not visible, the work is not done.
Repeat steps 1–6 after every visual change.
If layout or the collapsed rail is in scope, take a second screenshot at a narrow viewport.
If theme or contrast is in scope, take light and dark screenshots.

Unit tests still belong in the same change. Screenshots do not replace tests.

在
```
packages/web-inspector/src
```
下编辑Inspector源代码。
等待Vite重新加载实验室。
如果页面未同步变更，请重新加载实验室URL，然后等待覆盖层打开。
截取需要变更的面板的截图。
如果浏览器工具需要写入文件，请将文件写入
```
.inspector-workbench/<task>/
```
目录下。绝对不要在仓库根目录写入PNG文件。
查看截图。如果变更未显示，则工作未完成。
每次视觉变更后重复步骤1-6。
如果涉及布局或折叠侧边栏，请在窄视窗下再截取一张截图。
如果涉及主题或对比度，请分别截取亮色和暗色模式的截图。

单元测试仍需包含在同一变更中。截图不能替代测试。

Procedure 3: Stop the workbench

流程3：停止工作台

After the Inspector task is done, stop the
```
dev:standalone
```
process tree.
Do not leave Vite or the CSS watch running.
Do not commit files under
```
.inspector-workbench/
```
.
Do not commit PNG files at the repo root.

Inspector任务完成后，停止
```
dev:standalone
```
进程树。
请勿让Vite或CSS监听任务继续运行。
请勿提交
```
.inspector-workbench/
```
目录下的文件。
请勿提交仓库根目录下的PNG文件。

Decision Tree

决策树

Inspector UI, chrome, overlay, launcher, or pane visuals:
- Start: Procedure 1
- While editing: Procedure 2
- After the task: Procedure 3
- If a pane is added, renamed, or removed: also load
```
inspector-docs
```
Docs Callout only: stop. Load
```
inspector-docs
```
instead.
Bug exists only inside a host app: use that host, then still follow Procedure 2 screenshots.
Runtime or core change with no Inspector UI: this skill does not apply.

涉及Inspector UI、浏览器外壳、覆盖层、启动器或面板视觉效果：
- 启动：执行流程1
- 编辑过程中：执行流程2
- 任务完成后：执行流程3
- 如果新增、重命名或移除面板：同时加载
```
inspector-docs
```
仅涉及文档Callout：停止操作。改为加载
```
inspector-docs
```
问题仅存在于宿主应用内：使用该宿主应用，然后仍需遵循流程2的截图步骤
不涉及Inspector UI的运行时或核心变更：不适用此技能

Red Flags

警示信号

Signal	What it means	Do instead
Showcase, example, or Storybook is the first server	The agent skipped the workbench	Stop that server. Run Procedure 1
No screenshot after a visual edit	The agent is guessing from CSS	Take a screenshot. Look at it
PNG files at the repo root ( `inspector-open.png` )	The screenshot path is wrong	Write under `.inspector-workbench/<task>/`
"The CSS looks correct, so the UI is done"	Overlay bugs do not show in source	Screenshot the lab. Fix what the image shows
Vite started without the Nx target	CSS watch is missing	Use `nx run @copilotkit/web-inspector:dev:standalone`
Port 5178 or a random port	The lab pins 5177	Free 5177. Do not pick another port
Workbench still running after the task	Watchers leak memory on this machine	Run Procedure 3
Pane added with no `inspector-docs` pass	Docs Callout will drift	Load `inspector-docs` in the same change

信号	含义	正确操作
首先启动的是展示应用、示例应用或Storybook	Agent跳过了工作台	停止该服务，执行流程1
视觉编辑后未截取截图	Agent仅通过CSS猜测效果	截取截图并查看
仓库根目录存在PNG文件（如 `inspector-open.png` ）	截图路径错误	将文件写入 `.inspector-workbench/<task>/` 目录下
"CSS看起来没问题，所以UI开发完成"	覆盖层问题不会在源代码中体现	截取实验室截图，修复截图中显示的问题
未通过Nx目标启动Vite	缺少CSS监听任务	使用 `nx run @copilotkit/web-inspector:dev:standalone`
使用端口5178或随机端口	实验室固定使用端口5177	释放端口5177，请勿使用其他端口
任务完成后工作台仍在运行	监听进程会在此机器上泄漏内存	执行流程3
新增面板但未同步更新 `inspector-docs`	文档说明会与实际功能脱节	在同一变更中加载 `inspector-docs`

Error Handling

错误处理

Port 5177 is in use: stop the leftover Inspector workbench on that port, then retry Procedure 1. Do not pick another port. The lab uses
```
strictPort
```
.
No browser tool in this session: tell the user the session cannot see Inspector. Do not guess visual results from CSS or unit tests alone.
Lab is blank or the overlay is closed: wait for boot. Then screenshot the lab console Runtime line. If Runtime is not connected, fix the lab before UI edits.
Screenshot does not show the intended change: do not claim done. Reload, screenshot again, then fix the source.
HMR did not apply a source edit: reload
```
http://127.0.0.1:5177
```
with the same scenario query. Then screenshot.

Need a closed launcher or unread halo: open

http://127.0.0.1:5177/?scenario=pro-enabled-existing&replay-notification=1

Any unexpected error: halt and surface the raw error. Do not switch to a showcase app to work around the lab.

端口5177被占用：停止该端口上残留的Inspector工作台进程，然后重试流程1。请勿使用其他端口。实验室启用了
```
strictPort
```
配置。
本次会话无浏览器工具：告知用户当前会话无法查看Inspector。请勿仅通过CSS或单元测试猜测视觉效果。
实验室页面空白或覆盖层未打开：等待启动完成。然后截取实验室控制台的Runtime行截图。如果Runtime未连接，请先修复实验室问题再进行UI编辑。
截图未显示预期变更：不要声称任务完成。重新加载页面、再次截图，然后修复源代码。
热模块替换（HMR）未应用源代码变更：使用相同的场景参数重新加载
```
http://127.0.0.1:5177
```
，然后截图。

需要关闭启动器或显示未读提示标记：访问

http://127.0.0.1:5177/?scenario=pro-enabled-existing&replay-notification=1

。

任何意外错误：暂停操作并直接上报原始错误。请勿切换到展示应用来规避实验室问题。