umbraco-chrome-navigation

Umbraco 后台导航（Claude-in-Chrome）

为什么需要此技能

Umbraco 后台基于 Lit Web Components 构建。这会给浏览器自动化带来三个问题；如果盲目应对，就会浪费大量工具调用：

1. 所有内容都位于（开放的）Shadow DOM 中。 内置的 find 和 read_page 工具无法穿透 Shadow Root，因此在后台页面上几乎什么也读不到。
2. 模态框会传送到自己的堆叠上下文中，而且经常渲染在约 1536px 的捕获视口之外，或者层层堆叠，导致最新的模态框出现在屏幕外。
3. 截图会滞后于模态框转换期间的实时 DOM——你可能截到一帧已不再反映当前状态的画面，进而完全误读。

解决办法是停止依靠像素导航。注入一个小型的 Shadow DOM 穿透辅助工具，并从 DOM 读取状态（DOM 永远不会滞后），通过标签/文本而不是坐标执行操作。只有在图片本身就是实际交付内容时（例如核实外观，或为用户提供证据）才截图，而不要把截图作为判断屏幕内容的主要方式。

设置（每个浏览器会话只需一次）

此工具包位于此技能中的 scripts/umbraco-chrome-helpers.js。读取该文件，并将其完整内容粘贴到后台标签页上的 mcp__claude-in-chrome__javascript_tool 中。它会定义 window.__umb，并将自身源码存入 localStorage.__umbSrc。

页面加载（导航/重新加载/登录重定向）会清除 window.__umb，但不会清除 localStorage，因此每次导航后都要用以下单行代码重新注入：

eval(localStorage.__umbSrc)

首先按常规方式启动浏览器会话：tabs_context_mcp → tabs_create_mcp（或复用后台标签页），然后导航到后台地址 <your-host>/umbraco（此代码库的主机为 localhost:44325）。

API

所有查找器都会返回元素中心的 {x, y}，以便你在需要时改用电脑工具。

调用	用途
__umb.snapshot()	将可见的可操作元素列为 tag[role] "label" @x,y——“我能点击什么”
__umb.find(text, {role, tag})	按标签/文本（字符串或 RegExp）查找元素，并返回坐标
__umb.click(text, {role, tag, nth})	点击工作区/模态框中的大多数按钮和选项
__umb.fill(labelSubstr, value)	设置 <uui-input>/<input>/<textarea>（会触发 input+change）
__umb.modals()	列出打开的模态框/侧边栏/对话框及其操作按钮
__umb.waitFor(text, {role})	轮询直到元素出现（区段树会异步加载）
__umb.waitGone(text)	轮询直到元素消失（例如模态框关闭）
__umb.section(name)	查找区段标签页（Content/Settings/…）——返回可通过电脑工具点击的坐标
__umb.treeActions(itemName)	打开树形项目的“View actions for 'X'”菜单

为你省时的一条规则：模拟点击与可信点击

__umb.click() 使用元素的真实 .click()。这适用于工作区或模态框中的按钮和选项（Save、Submit、Discard、结果行、创建选项等）。

但以下两类操作不起作用，因为它们需要可信的用户手势：

• 区段标签页（Content、Settings…）——SPA 路由器会忽略模拟点击。
• 侧边栏树形结构的组标题（h3“Structure”/“Templating”），用于展开/折叠。

对于这些操作，使用 __umb.find(...)（或 __umb.section(...)）获取坐标，并通过 mcp__claude-in-chrome__computer 在 {x,y} 处执行 left_click——这是真实可信的点击。

因此，分工如下：使用 DOM 辅助工具查看状态并执行页面内操作；使用电脑工具（配合辅助工具提供的坐标）进行路由导航和树形组的切换。

Helpers 为你暴露的易踩问题

• 隐藏的“放弃更改”模态框。 离开包含未保存状态的工作区时，会弹出 umb-discard-changes-modal，并静默阻止导航。如果导航似乎没有反应，运行 __umb.modals() ——你会看到它——然后运行 __umb.click('Discard changes') （或 'Save'）以继续。
• 空白的创建工作区。 深层链接到 …/create/… 工作区 URL 时经常会显示空白。请改用树或集合中的 “Create” 操作进入创建流程。
• 异步加载的树。 导航到某个分区后，侧边栏树会稍后加载。操作前先运行 __umb.waitFor('<a known item>')。
• 会话失效。 重新创建数据库（全新无人值守安装）会使旧令牌失效；标签页会跳转到 /umbraco/login。重新注入 helpers，然后设置用户名和密码输入框的值并点击提交按钮登录。
• 隐私保护机制。 不要通过 javascript_tool 批量返回 href、URL 或 base64——隐私保护机制会拦截整个结果。只返回标签和坐标（helpers 已会这样做）。

可靠性边界——设置时优先使用 API

通过多步操作驱动 UI 完成设置（创建数据类型 → 文档类型 → 内容）本质上很脆弱：树会异步加载，创建工作区可能为空白，还会有放弃更改保护。当你只需要这些实体存在时，Management API 是合适的操作界面；可通过 Umbraco e2e/Playwright testhelpers（@umbraco-cms/acceptance-test-helpers）调用，它们会正确完成身份验证，并通过少量 umbracoApi.* 调用来创建初始数据。对于必须在实时后台 UI 中完成的部分（验证自定义编辑器能否渲染并正常工作、逐步操作某个流程、截取屏幕截图），请使用此技能。注意：后台 OAuth 令牌保存在内存中，而不是 localStorage/sessionStorage，因此无法从页面中借用令牌，在 Claude-in-Chrome 中直接调用 API。

典型操作循环

1. navigate 到后台标签页，注入工具包（或执行 eval(localStorage.__umbSrc)）。
2. 使用 __umb.snapshot() / __umb.find(...) 查看页面内容——不要截屏。
3. 使用 computer 工具配合 helpers 提供的坐标导航到各分区或展开树组；使用 __umb.click / __umb.fill 执行页面内操作。
4. 每一步之后，使用 __umb.find / __umb.modals / location.pathname 进行验证。
5. 如果交付内容是视觉呈现（外观）或需要向用户提供证据，则在最后截取一张屏幕截图。