inspector-workbench

Inspector 工作台

Inspector 覆盖层是一种视觉产物。代码能编译并不代表正确。 Agent 必须在每次视觉变更后运行独立工作台并查看截图。

本技能不能替代 inspector-docs。如果新增、重命名或删除了面板，还需加载 inspector-docs。

何时使用

在开始任何会改变 packages/web-inspector UI、界面外观或覆盖层行为的任务时加载本技能。

不要为仅涉及文档的 Callout 工作加载它。不要为展示单元格加载它。如果问题出在宿主应用中（z-index 与宿主 CSS 冲突、CopilotChat 布局），请使用该宿主，然后仍然需要截图。

默认宿主

默认宿主是独立的 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。该监听服务于使用者，而不是本实验室。

流程

流程 1：启动工作台

1. 如果变更新增、重命名或删除了面板，还需加载 inspector-docs。
2. 从仓库根目录启动 nx run @copilotkit/web-inspector:dev:standalone。
3. 等待 http://127.0.0.1:5177 开始提供服务。
4. 打开本会话可用的浏览器工具（Playwright MCP、Claude 浏览器或 Codex 计算机使用）。
5. 访问 http://127.0.0.1:5177/?scenario=pro-enabled-existing&reset=1。
6. 如果问题是空状态、锁定状态、错误状态或未读状态，在实验室下拉菜单中选择对应场景，然后重新加载。
7. 等待覆盖层在 Home 或 Threads 上打开。实验室会点击启动器。
8. 截取基线截图。在任何编辑之前先查看它。

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

1. 编辑 packages/web-inspector/src 下的 Inspector 源码。
2. 等待 Vite 重新加载实验室。
3. 如果页面没有拾取到变更，重新加载实验室 URL，然后等待覆盖层。
4. 对必须变更的面板截图。
5. 如果浏览器工具会写入文件，请写入 .inspector-workbench/<task>/ 下。绝不要在仓库根目录写入 PNG。
6. 查看截图。如果变更不可见，则工作尚未完成。
7. 每次视觉变更后重复步骤 1–6。
8. 如果涉及布局或折叠侧栏，在窄视口下再截一张图。
9. 如果涉及主题或对比度，截取浅色和深色截图。

单元测试仍应属于同一次变更。截图不能替代测试。

流程 3：停止工作台

1. Inspector 任务完成后，停止 dev:standalone 进程树。
2. 不要留下 Vite 或 CSS 监听在运行。
3. 不要提交 .inspector-workbench/ 下的文件。
4. 不要提交仓库根目录下的 PNG 文件。

决策树

• Inspector UI、界面外观、覆盖层、启动器或面板视觉：
  • 开始：流程 1
  • 编辑期间：流程 2
  • 任务完成后：流程 3
  • 如果新增、重命名或删除了面板：还需加载 inspector-docs
• 仅涉及文档 Callout：停止。改为加载 inspector-docs。
• 问题仅存在于宿主应用内部：使用该宿主，然后仍然遵循流程 2 的截图要求。
• 运行时或核心变更，不涉及 Inspector UI：本技能不适用。

危险信号

信号	含义	应改为
Showcase、示例或 Storybook 是第一个服务	Agent 跳过了工作台	停止该服务。运行流程 1
视觉编辑后没有截图	Agent 正在根据 CSS 猜测	截图。查看它
仓库根目录下的 PNG 文件（inspector-open.png）	截图路径错误	写入 .inspector-workbench/<task>/ 下
“CSS 看起来正确，所以 UI 已完成”	覆盖层 bug 不会在源码中显现	截图 lab。修复图像显示的问题
Vite 在未使用 Nx target 的情况下启动	缺少 CSS watch	使用 nx run @copilotkit/web-inspector:dev:standalone
端口 5178 或随机端口	lab 固定使用 5177	释放 5177。不要选择其他端口
任务完成后工作台仍在运行	监视器会在这台机器上泄漏内存	运行流程 3
添加了窗格但没有通过 inspector-docs	Docs Callout 将漂移	在同一次变更中加载 inspector-docs

错误处理

• 端口 5177 被占用：停止该端口上遗留的 Inspector 工作台，然后重试流程 1。不要选择其他端口。lab 使用 strictPort。
• 此会话中没有浏览器工具：告诉用户此会话无法查看 Inspector。不要仅根据 CSS 或单元测试猜测视觉结果。
• Lab 为空白或覆盖层已关闭：等待启动。然后截图 lab 控制台的 Runtime 行。如果 Runtime 未连接，在 UI 编辑之前先修复 lab。
• 截图未显示预期变更：不要声称已完成。重新加载，再次截图，然后修复源码。
• HMR 未应用源码编辑：使用相同的 scenario 查询重新加载 http://127.0.0.1:5177。然后截图。
• 需要关闭的启动器或未读光晕：打开 http://127.0.0.1:5177/?scenario=pro-enabled-existing&replay-notification=1。
• 任何意外错误：停止并暴露原始错误。不要切换到 showcase 应用来绕过 lab。